@cleocode/core 2026.9.23 → 2026.9.24

package/dist/store/backup-recover.d.ts

@@ -78,6 +78,15 @@ export interface BackupRecoverOptions {
      * perform delta-merge.
      */
     noDelta?: boolean;
+    /**
+     * Directory the recovery was invoked from (T12708). Supplied by the CLI
+     * layer; core never falls back to the process directory. A recovery that
+     * would overwrite the owning project's store from one of its worktrees
+     * needs {@link BackupRecoverOptions.confirmOwnerStore}.
+     */
+    cwd: string;
+    /** Confirm overwriting the owning project's LIVE store from a worktree (T12708). */
+    confirmOwnerStore?: boolean;
 }
 /**
  * Error thrown when the recovery pre-conditions cannot be satisfied.

package/dist/store/backup-recover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup-recover.d.ts","sourceRoot":"","sources":["../../src/store/backup-recover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAIL,KAAK,cAAc,EAIpB,MAAM,2BAA2B,CAAC;AAqBnC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mGAAmG;IACnG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAO1E;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,mBAAmB,CAyGhF"}
+{"version":3,"file":"backup-recover.d.ts","sourceRoot":"","sources":["../../src/store/backup-recover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAIL,KAAK,cAAc,EAIpB,MAAM,2BAA2B,CAAC;AA0BnC;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mGAAmG;IACnG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAO1E;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,mBAAmB,CA0GhF"}

package/dist/store/backup-recover.js

@@ -27,7 +27,9 @@
  */
 import { copyFileSync, existsSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
+import { CleoError } from '../errors.js';
 import { collectSnapshotCandidatesForRole, probeSnapshot, quarantineCorruptDb, recoverMalformedDb, resolveRoleBackupDirs, resolveRoleDbPath, } from './recover-malformed-db.js';
+import { assertOwnerStoreRewriteConfirmed, E_WT_STORE_REWRITE_CONFIRM_REQUIRED, E_WT_STORE_REWRITE_REFUSED, } from './worktree-isolation-guard.js';
 /**
  * Error thrown when the recovery pre-conditions cannot be satisfied.
  *
@@ -218,7 +220,8 @@ export function runBackupRecover(opts) {
             dryRun: true,
         };
     }
-    // Execute mode.
+    // Execute mode. T12708: both paths below replace the whole store file.
+    guardOwnerStoreRewrite(opts, layout.corruptPath);
     if (opts.fromSnapshot) {
         // Pinning path — quarantine the corrupt DB ourselves, then copy the
         // pinned snapshot in place. We deliberately avoid re-implementing
@@ -256,6 +259,30 @@ export function runBackupRecover(opts) {
         dryRun: false,
     };
 }
+/**
+ * Apply the shared whole-store rewrite guard to a recovery, reporting a
+ * refusal as a {@link BackupRecoverError} so every recovery surface renders it.
+ *
+ * @internal
+ */
+function guardOwnerStoreRewrite(opts, target) {
+    try {
+        assertOwnerStoreRewriteConfirmed(`backup recover ${opts.role}`, target, {
+            cwd: opts.cwd,
+            confirmOwnerStore: opts.confirmOwnerStore,
+        });
+    }
+    catch (err) {
+        if (!(err instanceof CleoError)) {
+            // The audit row could not be written, so the rewrite does not run.
+            throw new BackupRecoverError(`Could not write the owner-store audit row for role "${opts.role}": ${err instanceof Error ? err.message : String(err)}`, 1, 'E_AUDIT_WRITE_FAILED', 'Check that the project .cleo/audit/ directory is writable; nothing was restored.');
+        }
+        const codeName = err.message.startsWith(E_WT_STORE_REWRITE_REFUSED)
+            ? E_WT_STORE_REWRITE_REFUSED
+            : E_WT_STORE_REWRITE_CONFIRM_REQUIRED;
+        throw new BackupRecoverError(err.message, err.code, codeName, err.fix);
+    }
+}
 // ---------------------------------------------------------------------------
 // Pinned-restore implementation — mirrors recoverMalformedDb's I/O steps
 // ---------------------------------------------------------------------------

package/dist/store/backup-recover.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup-recover.js","sourceRoot":"","sources":["../../src/store/backup-recover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backup-recover.js","sourceRoot":"","sources":["../../src/store/backup-recover.ts"],"names":[],"mappings":"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"}

package/dist/store/backup-sidecar.d.ts

@@ -48,6 +48,14 @@ export interface BackupSidecar {
     readonly note?: string;
     /** Files captured, each stored as `<file>.<backupId>` next to the sidecar. */
     readonly files: readonly string[];
+    /**
+     * Never rotated (T12535): the snapshot a twin collapse took before it
+     * changed the store. It is the only copy of any row the collapse replaced,
+     * so it outlives the rotation cap until an owner removes it.
+     */
+    readonly pinned?: boolean;
+    /** Why it is pinned (shown by `cleo backup list`). */
+    readonly pinnedReason?: string;
 }
 /**
  * Write a `.meta.json` sidecar atomically (tmp file, then rename).
@@ -57,4 +65,26 @@ export interface BackupSidecar {
  * @task T12535
  */
 export declare function writeBackupSidecar(backupDir: string, sidecar: BackupSidecar): void;
+/**
+ * Whether a backup file is pinned (its sidecar says `pinned: true`).
+ *
+ * @param backupDir - The backup directory.
+ * @param fileName - The backup file (`<file>.<type>-<timestamp>`).
+ * @param backupType - Its backup type.
+ * @returns `true` when pinned.
+ * @task T12535
+ */
+export declare function isPinnedBackup(backupDir: string, fileName: string, backupType: string): boolean;
+/**
+ * Pin the backup a file belongs to, so rotation never deletes it. Writes the
+ * sidecar (`pinned: true`, `pinnedReason`), creating it for a snapshot that has
+ * none. Idempotent and best effort: returns whether the backup is pinned now.
+ *
+ * @param snapshotPath - The backup file (`<dir>/<file>.<type>-<timestamp>`).
+ * @param backupType - Its backup type (`migration` for twin-collapse snapshots).
+ * @param reason - Why it is pinned.
+ * @returns `true` when the backup is pinned after the call.
+ * @task T12535
+ */
+export declare function pinBackup(snapshotPath: string, backupType: string, reason: string): boolean;
 //# sourceMappingURL=backup-sidecar.d.ts.map

package/dist/store/backup-sidecar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup-sidecar.d.ts","sourceRoot":"","sources":["../../src/store/backup-sidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAMrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAmCjG;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAKlF"}
+{"version":3,"file":"backup-sidecar.d.ts","sourceRoot":"","sources":["../../src/store/backup-sidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAcH;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAMrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAqCjG;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAKlF;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAsB3F"}

package/dist/store/backup-sidecar.js

@@ -13,8 +13,9 @@
  * @task T10315
  * @task T12535 — extracted from `system/backup.ts`
  */
-import { existsSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { z } from 'zod';
 /**
  * Format a Date as `YYYYMMDD-HHmmss` (local time) — mirrors the helper of
  * the same name in `sqlite-backup.ts` so both auto-snapshot and manual
@@ -54,6 +55,8 @@ export function rotateBackupDir(backupDir, maxSnapshots, backupType) {
         const ownedPattern = new RegExp(`\\.${escapedType}-`);
         const files = readdirSync(backupDir)
             .filter((f) => !f.endsWith('.meta.json') && !f.endsWith('.tmp') && ownedPattern.test(f))
+            // A pinned backup (T12535) is never rotated and does not count toward the cap.
+            .filter((f) => !isPinnedBackup(backupDir, f, backupType))
             .map((f) => ({
             name: f,
             path: join(backupDir, f),
@@ -93,4 +96,89 @@ export function writeBackupSidecar(backupDir, sidecar) {
     writeFileSync(tmp, JSON.stringify(sidecar, null, 2));
     renameSync(tmp, dest);
 }
+/**
+ * The backup id (`<type>-<timestamp>`) of a backup file named
+ * `<file>.<type>-<timestamp>`, or `null` when the name has no such suffix.
+ */
+function backupIdOf(fileName, backupType) {
+    const at = fileName.indexOf(`.${backupType}-`);
+    return at < 0 ? null : fileName.slice(at + 1);
+}
+/**
+ * Shape of a `.meta.json` sidecar as read back from disk. Unknown fields are
+ * kept (older and newer builds add their own); a sidecar that does not match
+ * reads as absent, so a malformed file can never pin (or unpin) a backup.
+ */
+const backupSidecarSchema = z
+    .object({
+    backupId: z.string().min(1),
+    type: z.string().min(1),
+    timestamp: z.string().min(1),
+    note: z.string().optional(),
+    files: z.array(z.string()),
+    pinned: z.boolean().optional(),
+    pinnedReason: z.string().optional(),
+})
+    .passthrough();
+/** Read a backup's sidecar, or `null` when it is missing, unreadable or malformed. */
+function readSidecar(backupDir, backupId) {
+    try {
+        const parsed = backupSidecarSchema.safeParse(JSON.parse(readFileSync(join(backupDir, `${backupId}.meta.json`), 'utf-8')));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a backup file is pinned (its sidecar says `pinned: true`).
+ *
+ * @param backupDir - The backup directory.
+ * @param fileName - The backup file (`<file>.<type>-<timestamp>`).
+ * @param backupType - Its backup type.
+ * @returns `true` when pinned.
+ * @task T12535
+ */
+export function isPinnedBackup(backupDir, fileName, backupType) {
+    const id = backupIdOf(fileName, backupType);
+    return id !== null && readSidecar(backupDir, id)?.pinned === true;
+}
+/**
+ * Pin the backup a file belongs to, so rotation never deletes it. Writes the
+ * sidecar (`pinned: true`, `pinnedReason`), creating it for a snapshot that has
+ * none. Idempotent and best effort: returns whether the backup is pinned now.
+ *
+ * @param snapshotPath - The backup file (`<dir>/<file>.<type>-<timestamp>`).
+ * @param backupType - Its backup type (`migration` for twin-collapse snapshots).
+ * @param reason - Why it is pinned.
+ * @returns `true` when the backup is pinned after the call.
+ * @task T12535
+ */
+export function pinBackup(snapshotPath, backupType, reason) {
+    try {
+        if (!existsSync(snapshotPath))
+            return false;
+        const backupDir = dirname(snapshotPath);
+        const file = basename(snapshotPath);
+        const id = backupIdOf(file, backupType);
+        if (id === null)
+            return false;
+        const current = readSidecar(backupDir, id);
+        if (current?.pinned === true)
+            return true;
+        writeBackupSidecar(backupDir, {
+            backupId: id,
+            type: current?.type ?? backupType,
+            timestamp: current?.timestamp ?? statSync(snapshotPath).mtime.toISOString(),
+            ...(current?.note !== undefined ? { note: current.note } : {}),
+            files: current?.files ?? [file.slice(0, file.length - id.length - 1)],
+            pinned: true,
+            pinnedReason: reason,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=backup-sidecar.js.map

package/dist/store/backup-sidecar.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup-sidecar.js","sourceRoot":"","sources":["../../src/store/backup-sidecar.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backup-sidecar.js","sourceRoot":"","sources":["../../src/store/backup-sidecar.ts"],"names":[],"mappings":"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"}

package/dist/store/blob-keep.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Blob keep-links: attachment blobs outlive a stale-reading older build
+ * (T12535, mixed-version defence).
+ *
+ * ## Why
+ *
+ * After the twin collapse this build reads and writes `docs_attachments`,
+ * while the 2026.9.20 build still reads and writes the bare `attachments`
+ * table. Both keep blob bytes at the same content-addressed path
+ * (`.cleo/attachments/sha256/<aa>/<rest><ext>`). The older build deletes a blob
+ * when ITS last bare ref goes (and its janitor deletes blobs no BARE row
+ * names), unaware that this build's twin may still reference the content.
+ *
+ * ## How
+ *
+ * Every blob this build stores, references or carries in the collapse gets a
+ * hard link under `.cleo/attachments/keep/<aa>/<rest>` (a copy where hard
+ * links are not possible). The older build only ever unlinks the primary path,
+ * so the bytes survive in the keep-link, and this build restores the primary
+ * path from it on read, on every merge and in the repair.
+ *
+ * This build never deletes a blob straight away: its last deref leaves a
+ * tombstone (`<keep-link>.tomb`, holding the time). The repair (`cleo doctor`,
+ * the janitor) removes the primary file and the keep-link only after the grace
+ * period, and only when neither table names the content.
+ *
+ * @module
+ * @task T12535
+ */
+/**
+ * Resolve a file extension from a MIME type.
+ *
+ * @param mime - IANA MIME type string
+ * @returns Extension string including the leading dot (e.g., `".md"`)
+ */
+export declare function extFromMime(mime: string): string;
+/**
+ * The primary on-disk path of a blob.
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The content hash.
+ * @param mime - The blob's MIME type (gives the extension).
+ * @returns `.cleo/attachments/sha256/<aa>/<rest><ext>`.
+ */
+export declare function blobFilePath(cleoDir: string, sha256: string, mime: string): string;
+/**
+ * The primary path of the blob an attachment row stores bytes for, or `null`
+ * for kinds kept by reference (url, llms-txt, llmtxt-doc) or malformed JSON.
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The row's content hash.
+ * @param attachmentJson - The row's `attachment_json`.
+ * @returns The primary blob path, or `null`.
+ */
+export declare function blobFileForRow(cleoDir: string, sha256: string, attachmentJson: string): string | null;
+/**
+ * Hard-link (or copy) a blob's primary file to its keep-link. Idempotent and
+ * best effort: a missing primary file or an unwritable keep directory is not
+ * an error (the blob is then simply not protected).
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The content hash.
+ * @param primary - The blob's primary path.
+ */
+export declare function pinBlob(cleoDir: string, sha256: string, primary: string): void;
+/**
+ * Put a blob's primary file back from its keep-link when the primary is
+ * missing (an older build unlinked it). Clears a pending tombstone: a restore
+ * means something still needs the bytes.
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The content hash.
+ * @param primary - The blob's primary path.
+ * @returns Whether the primary file exists afterwards.
+ */
+export declare function restoreBlob(cleoDir: string, sha256: string, primary: string): boolean;
+/**
+ * Mark a blob this build no longer references: the repair deletes it after the
+ * grace period if neither table names the content then. The primary file and
+ * the keep-link stay until then.
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The content hash.
+ * @param primary - The blob's primary path (pinned first, so the tombstone has
+ *   a keep-link to guard).
+ * @param now - The tombstone time (ms since the epoch).
+ */
+export declare function tombstoneBlob(cleoDir: string, sha256: string, primary: string, now: number): void;
+/** What {@link collectBlobGarbage} did. */
+export interface BlobGarbageResult {
+    /** Content hashes whose keep-link (and primary file) were deleted. */
+    readonly deleted: string[];
+    /** Tombstones or unreferenced keep-links still inside the grace period. */
+    readonly waiting: number;
+    /** Tombstones dropped because a table names the content again. */
+    readonly revived: number;
+}
+/**
+ * Collect keep-links nobody needs. For each keep-link:
+ *
+ * - referenced by a row in either table: kept; a tombstone on it is dropped
+ *   and its primary file restored if it is gone;
+ * - not referenced, tombstoned (this build's last deref): the primary file
+ *   and the keep-link are deleted once the tombstone is older than the grace
+ *   period;
+ * - not referenced, no tombstone (an older build deleted the row): the
+ *   keep-link (and any primary file) is deleted once the file is older than
+ *   the grace period.
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param isReferenced - Whether a row in either table names the content.
+ * @param graceMs - How long a tombstone (or an unreferenced keep-link) must age.
+ * @param now - The current time (ms since the epoch).
+ * @param dryRun - Report only.
+ * @returns What was deleted, kept waiting, or revived.
+ */
+export declare function collectBlobGarbage(cleoDir: string, isReferenced: (sha256: string) => boolean, graceMs: number, now: number, dryRun: boolean): BlobGarbageResult;
+/**
+ * Whether a blob has a pending tombstone (its deletion waits for the grace
+ * period, so other sweeps leave it alone).
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The content hash.
+ * @returns `true` when tombstoned.
+ */
+export declare function isTombstoned(cleoDir: string, sha256: string): boolean;
+/**
+ * Delete a blob's keep-link (the primary file was deleted by a sweep that
+ * checked both tables).
+ *
+ * @param cleoDir - The project's `.cleo` directory.
+ * @param sha256 - The content hash.
+ */
+export declare function unpinBlob(cleoDir: string, sha256: string): void;
+//# sourceMappingURL=blob-keep.d.ts.map

package/dist/store/blob-keep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-keep.d.ts","sourceRoot":"","sources":["../../src/store/blob-keep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAuCH;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,GACrB,MAAM,GAAG,IAAI,CAUf;AAOD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAa9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAgBrF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CASjG;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,EACzC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,OAAO,GACd,iBAAiB,CAuDnB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/D"}