/**
 * Back up and restore the docs byte surfaces (T13704): the content a project
 * store backup alone cannot serve `docs fetch` from.
 *
 *   - `.cleo/blobs/manifest.db` (blob-store metadata) and
 *     `.cleo/blobs/blobs/<sha256>` (the bytes);
 *   - `.cleo/attachments/index.db` and the legacy byte tree under
 *     `.cleo/attachments/` (`sha256/<2>/<62><ext>`, `keep/...`).
 *
 * The two databases are snapshotted per backup with `VACUUM INTO`, checked
 * with `PRAGMA integrity_check`, and stored as flat `<label>.<backupId>`
 * payloads beside the store snapshot. The byte files go into ONE shared
 * content-addressed pool, `.cleo/backups/blobs/<sha256>`, written once and
 * shared by every backup (T13710: a real store holds ~10k files, so per-backup
 * copies made rotation delete the backups themselves). Each backup lists what
 * it references in a `docs-bytes.json.<backupId>` sidecar; rotation removes a
 * whole backup, sidecar included, and {@link sweepDocsBytePool} then unlinks
 * only pool files no surviving sidecar references.
 *
 * Restore verifies every byte before placing it: each pool file must hash to
 * its recorded sha256, each database snapshot must match its recorded sha256
 * and pass `integrity_check` on the staged copy that is then renamed into
 * place. Anything that fails is listed; a restore with failures is partial,
 * never clean (T13709).
 *
 * Synchronous on purpose: callers hold no async lock across it, and the pool
 * lock is a {@link withLockSync} lock whose stale age covers a full pass.
 *
 * @module store/docs-bytes-backup
 * @task T13704
 * @task T13708
 * @task T13709
 * @task T13710
 */
import type { StoreRestoreDocsBytes } from '@cleocode/contracts';
/** Label of the per-backup sidecar listing the docs bytes it references (`<label>.<backupId>`). */
export declare const DOCS_BYTES_SIDECAR_LABEL = "docs-bytes.json";
/** What {@link backupDocsBytes} captured. */
export interface DocsBytesBackupSummary {
    /** Database labels snapshotted and verified (`blobs.manifest.db`, `attachments.index.db`). */
    readonly dbs: readonly string[];
    /** Byte files referenced from the pool. */
    readonly files: number;
    /** Byte files newly written to the pool (the rest were already there). */
    readonly pooled: number;
    /** What could not be captured. */
    readonly skipped: readonly string[];
}
/** The shared byte pool of a backup directory (`.cleo/backups/sqlite` -> `.cleo/backups/blobs`). */
export declare function docsBytePoolDir(backupDir: string): string;
/**
 * Snapshot the docs byte surfaces of `cleoDir` into backup `backupId` (T13704):
 * VACUUM INTO + integrity_check for each docs database, every byte file into
 * the shared pool (written once), and the `docs-bytes.json.<backupId>`
 * sidecar listing what the backup references. Best effort per file: what
 * fails is reported in `skipped`, never silently dropped.
 *
 * @param cleoDir - The project's `.cleo/` directory.
 * @param backupDir - `.cleo/backups/sqlite`.
 * @param backupId - The backup the snapshot belongs to.
 * @returns What was captured, or `null` when there are no docs byte surfaces.
 */
export declare function backupDocsBytes(cleoDir: string, backupDir: string, backupId: string): DocsBytesBackupSummary | null;
/**
 * Unlink every pool file that no `docs-bytes.json.<backupId>` sidecar left in
 * `backupDir` references (T13710); run after rotation. When any sidecar
 * cannot be read, what it references is unknown, so nothing is removed.
 *
 * @param backupDir - `.cleo/backups/sqlite`.
 * @returns The pool files removed.
 */
export declare function sweepDocsBytePool(backupDir: string): string[];
/**
 * Whether backup `backupId` carries docs byte surfaces (a `docs-bytes.json` sidecar).
 *
 * @param backupDir - `.cleo/backups/sqlite`.
 * @param backupId - The backup.
 */
export declare function hasDocsBytes(backupDir: string, backupId: string): boolean;
/**
 * The live docs databases another connection holds open (a restore over
 * them would be lost to that connection's writes).
 *
 * @param cleoDir - The project's `.cleo/` directory.
 * @returns Absolute paths of the busy databases.
 */
export declare function docsDbsOpenElsewhere(cleoDir: string): string[];
/**
 * Restore the docs byte surfaces of backup `backupId` into `cleoDir`, placing
 * only verified bytes (T13708, T13709). Each database snapshot must match its
 * recorded sha256 and pass `integrity_check` on the staged copy, and its live
 * file must not be open elsewhere; each pool file must hash to its recorded
 * sha256. Failures are listed in `failed`, and `complete` is `false` when
 * there are any.
 *
 * @param cleoDir - The project's `.cleo/` directory.
 * @param backupDir - `.cleo/backups/sqlite`.
 * @param backupId - The backup to restore from.
 * @returns What was placed and what failed, or `null` when the backup holds no docs bytes.
 */
export declare function restoreDocsBytes(cleoDir: string, backupDir: string, backupId: string): StoreRestoreDocsBytes | null;
/**
 * Labels of the docs databases that exist live under `cleoDir`: a safety
 * copy of them must hold each of these before anything replaces them.
 *
 * @param cleoDir - The project's `.cleo/` directory.
 * @returns The live database labels (`blobs.manifest.db`, `attachments.index.db`).
 */
export declare function liveDocsDbLabels(cleoDir: string): string[];
/** What `createBackup` records of the docs capture in `<backupId>.meta.json`. */
export interface DocsBytesMeta {
    /** Database labels captured. */
    readonly dbs?: readonly string[];
    /** Byte files referenced. */
    readonly files?: number;
    /** What could not be captured. */
    readonly skipped?: readonly string[];
    /** Why the capture failed as a whole. */
    readonly error?: string;
}
/**
 * Where backup `backupId` falls short of the docs capture its
 * `<backupId>.meta.json` records (T13709): a capture that failed or skipped
 * files, or a `docs-bytes.json` sidecar that is missing or lists fewer
 * databases or files than recorded. A backup whose meta records no docs
 * capture (older builds) yields nothing.
 *
 * @param backupDir - `.cleo/backups/sqlite`.
 * @param backupId - The backup.
 * @returns One warning per shortfall.
 */
export declare function docsBytesMetaWarnings(backupDir: string, backupId: string): string[];
//# sourceMappingURL=docs-bytes-backup.d.ts.map