@cleocode/core 2026.9.24 → 2026.9.26

package/dist/store/twin-collapse.js

@@ -179,7 +179,7 @@
  * @task T12535
  */
 import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ExitCode } from '@cleocode/contracts';
@@ -187,7 +187,7 @@ import { z } from 'zod';
 import { CleoError } from '../errors.js';
 import { getLogger } from '../logger.js';
 import { getCleoVersion } from '../scaffold/ensure-config.js';
-import { isPinnedBackup, pinBackup } from './backup-sidecar.js';
+import { isPinnedBackup, pinBackup, readBackupSidecar, restoreBackupSidecar, unpinBackup, } from './backup-sidecar.js';
 import { blobFileForRow, pinBlob, restoreBlob } from './blob-keep.js';
 import { planMigrationSnapshot, writeMigrationSnapshot } from './pre-repair-snapshot.js';
 const log = getLogger('twin-collapse');
@@ -1571,7 +1571,11 @@ function collapsePair(db, pair, snapshotPath, dbPath) {
             task: 'T12535',
             collapsedAt: state?.collapsedAt || now,
             lastMergedAt: now,
-            snapshot: state?.snapshot ?? snapshotPath,
+            // Only an initial collapse records the snapshot it took. A later one
+            // keeps what the marker holds, including `null` after an owner
+            // released it (T12767): the snapshot another pair's initial collapse
+            // took is not this pair's pre-collapse store.
+            snapshot: state === undefined ? snapshotPath : state.snapshot,
             hashes: { bare: pair.bareHashes(db), twin: pair.twinHashes(db) },
             dropped: state === undefined ? plan.dropped : state.dropped,
             kept: state === undefined ? plan.kept.slice(0, MAX_CONFLICTS) : state.kept,
@@ -1924,9 +1928,10 @@ function stickySetsIfPresent(db, table) {
  * @returns The plan.
  * @task T12727
  */
-export function planTwinCollapseRecovery(live, snapshot) {
+export function planTwinCollapseRecovery(live, snapshot, options = {}) {
     const state = readState(live, SCHEMA_META);
-    const snapshotPath = state?.snapshot ?? null;
+    const recorded = state?.snapshot ?? null;
+    const snapshotPath = recorded === null ? null : (options.snapshotPath ?? recorded);
     const liveKv = kvRows(live, 'tasks_schema_meta');
     const receipts = [...recoveryReceipts(live)]
         .filter(([, r]) => r.rolledBackAt === null)
@@ -1935,12 +1940,14 @@ export function planTwinCollapseRecovery(live, snapshot) {
     const empty = {
         snapshot: snapshotPath,
         snapshotExists: snapshot !== null,
+        snapshotPinned: recoverySnapshotPinned(snapshotPath),
         archive: [],
         focusNotesAdded: 0,
         stickyArchived: [],
         stickyArchiveKey: STICKY_ARCHIVE_KEY,
         receipts,
         changes: false,
+        movedFrom: recorded !== null && snapshotPath !== recorded ? recorded : null,
     };
     if (snapshot === null)
         return empty;
@@ -1959,11 +1966,25 @@ export function planTwinCollapseRecovery(live, snapshot) {
             continue; // not replaced
         const reason = sBare.has(key) ? 'replaced' : 'dropped';
         const done = liveKv.get(key) === twinValue || archivedValues.has(twinValue);
-        if (key === 'focus_state' && focusBefore !== null && !done && receipts.length === 0) {
-            const merged = mergeFocusState(focusBefore, twinValue);
-            if (merged !== focusBefore) {
-                focusNotesAdded = sessionNotesOf(merged).length - sessionNotesOf(focusBefore).length;
-                focusState = merged;
+        if (key === 'focus_state' && !done && receipts.length === 0) {
+            if (focusBefore !== null) {
+                const merged = mergeFocusState(focusBefore, twinValue);
+                if (merged !== focusBefore) {
+                    focusNotesAdded = sessionNotesOf(merged).length - sessionNotesOf(focusBefore).length;
+                    focusState = merged;
+                }
+            }
+            else if (reason === 'dropped') {
+                // Only the twin held it (the kodomeet shape) and nothing replaced the
+                // legacy key since: its notes are live again. Its pointer is not:
+                // bound sessions keep their focus under `focus_state:<sessionId>`
+                // (T11345, T12501), and the next keyless one would adopt a live legacy
+                // pointer months stale. The full value stays in the archive (T12771).
+                const parsed = FocusNotesShape.safeParse(parseJson(twinValue));
+                if (parsed.success) {
+                    focusState = JSON.stringify({ ...parsed.data, currentTask: null });
+                    focusNotesAdded = parsed.data.sessionNotes.length;
+                }
             }
         }
         if (done)
@@ -2017,6 +2038,7 @@ export function planTwinCollapseRecovery(live, snapshot) {
     };
     recoveryWrites.set(plan, {
         snapshot,
+        options,
         kv,
         focusBefore,
         focusState,
@@ -2042,19 +2064,36 @@ export function planTwinCollapseRecovery(live, snapshot) {
  *   snapshot is missing (nothing is written).
  * @task T12727
  */
-export function applyTwinCollapseRecovery(live, plan) {
+export function applyTwinCollapseRecovery(live, plan, onRepoint) {
     if (plan.snapshot === null)
-        return { plan, receipt: null };
+        return { plan, receipt: null, repointed: null };
     const preview = recoveryWrites.get(plan);
     if (!plan.snapshotExists || preview === undefined)
         throw missingSnapshot(plan.snapshot);
     live.exec('BEGIN IMMEDIATE');
     try {
-        const fresh = planTwinCollapseRecovery(live, preview.snapshot);
+        const fresh = planTwinCollapseRecovery(live, preview.snapshot, preview.options);
         const writes = recoveryWrites.get(fresh);
+        // Only when there is something to write (T12772): a re-run on a
+        // recovered store is a no-op whatever the pin. Checked before anything
+        // (the re-point, its audit row) is written.
+        if (fresh.changes && writes !== undefined && !fresh.snapshotPinned)
+            throw unpinnedSnapshot(fresh.snapshot);
+        // A moved store (T12788): the markers name the file where it lives now,
+        // whether or not anything is left to recover. `onRepoint` audits it just
+        // before COMMIT, so a failure that rolls the re-point back leaves no
+        // audit row claiming it.
+        let repointed = null;
+        if (fresh.movedFrom !== null && fresh.snapshot !== null)
+            repointed = repointSnapshotMarkers(live, fresh.movedFrom, fresh.snapshot);
         if (!fresh.changes || writes === undefined) {
-            live.exec('ROLLBACK');
-            return { plan: fresh, receipt: null };
+            if (repointed === null)
+                live.exec('ROLLBACK');
+            else {
+                onRepoint?.(repointed);
+                live.exec('COMMIT');
+            }
+            return { plan: fresh, receipt: null, repointed };
         }
         const recoveredAt = new Date().toISOString();
         let id = `${TWIN_COLLAPSE_RECOVERY_PREFIX}${recoveredAt}`;
@@ -2090,8 +2129,10 @@ export function applyTwinCollapseRecovery(live, plan) {
         if (writes.stickyArchive !== null)
             writeKv(live, 'brain_schema_meta', fresh.stickyArchiveKey, writes.stickyArchive);
         writeKv(live, 'tasks_schema_meta', id, JSON.stringify(receipt));
+        if (repointed !== null)
+            onRepoint?.(repointed);
         live.exec('COMMIT');
-        return { plan: fresh, receipt };
+        return { plan: fresh, receipt, repointed };
     }
     catch (error) {
         if (live.isTransaction)
@@ -2099,6 +2140,24 @@ export function applyTwinCollapseRecovery(live, plan) {
         throw error;
     }
 }
+/** Point every marker that records `from` at `to` (inside the caller's transaction). */
+function repointSnapshotMarkers(live, from, to) {
+    const markers = [];
+    for (const pair of PAIRS) {
+        if (!hasMainTable(live, pair.kvTable))
+            continue;
+        const key = `${TWIN_COLLAPSE_MARKER_PREFIX}${pair.table}`;
+        const raw = readKv(live, pair.kvTable, key);
+        const parsed = raw === undefined ? undefined : parseJson(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            continue;
+        if (parsed.snapshot !== from)
+            continue;
+        writeKv(live, pair.kvTable, key, JSON.stringify({ ...parsed, snapshot: to }));
+        markers.push(`${pair.kvTable}:${key}`);
+    }
+    return { from, to, markers };
+}
 /** The error for a recorded snapshot that is not on disk. */
 export function missingSnapshot(path) {
     return new CleoError(ExitCode.NOT_FOUND, `${E_TWIN_COLLAPSE_RECOVER}: the pre-collapse snapshot ${path ?? '(none recorded)'} is missing; nothing was recovered`, {
@@ -2106,6 +2165,28 @@ export function missingSnapshot(path) {
         details: { field: 'snapshot', actual: path },
     });
 }
+/** The error for a recorded snapshot rotation could still delete. */
+export function unpinnedSnapshot(path) {
+    return new CleoError(ExitCode.VALIDATION_ERROR, `${E_TWIN_COLLAPSE_RECOVER}: the pre-collapse snapshot ${path ?? '(none recorded)'} is not pinned, so backup rotation may delete it; nothing was recovered`, {
+        fix: 'cleo doctor twin-collapse --recover --pin-snapshot  # pins it (writes only its .meta.json sidecar), then recovers',
+        details: { field: 'snapshotPinned', expected: true, actual: false },
+    });
+}
+/** Whether the recorded snapshot is on disk and pinned. */
+function recoverySnapshotPinned(path) {
+    return (path !== null && existsSync(path) && isPinnedBackup(dirname(path), basename(path), 'migration'));
+}
+/**
+ * Pin the recorded pre-collapse snapshot before a recovery
+ * (`--pin-snapshot`): writes its `.meta.json` sidecar only, never the snapshot.
+ *
+ * @param path - The snapshot the marker records.
+ * @returns Whether it is pinned now.
+ * @task T12727
+ */
+export function pinRecoverySnapshot(path) {
+    return pinBackup(path, 'migration', SNAPSHOT_PIN_REASON);
+}
 /**
  * Undo one recovery apply (`cleo doctor twin-collapse --rollback <id>`), in
  * one `BEGIN IMMEDIATE` transaction:
@@ -2152,12 +2233,16 @@ export function rollbackTwinCollapseRecovery(live, id) {
         }
         let focusState = 'none';
         let notesRemoved = 0;
-        if (receipt.after.focusState !== null && receipt.before.focusState !== null) {
+        if (receipt.after.focusState !== null) {
             const current = readKv(live, 'tasks_schema_meta', 'focus_state');
             if (current !== undefined && sha(current) === receipt.after.focusState) {
                 notesRemoved =
-                    sessionNotesOf(current).length - sessionNotesOf(receipt.before.focusState).length;
-                writeKv(live, 'tasks_schema_meta', 'focus_state', receipt.before.focusState);
+                    sessionNotesOf(current).length -
+                        sessionNotesOf(receipt.before.focusState ?? undefined).length;
+                if (receipt.before.focusState === null)
+                    live.prepare("DELETE FROM main.tasks_schema_meta WHERE key = 'focus_state'").run();
+                else
+                    writeKv(live, 'tasks_schema_meta', 'focus_state', receipt.before.focusState);
                 focusState = 'restored';
             }
             else if (current !== undefined) {
@@ -2203,4 +2288,147 @@ export function rollbackTwinCollapseRecovery(live, id) {
         throw error;
     }
 }
+// ── releasing a pre-collapse snapshot (T12767) ──────────────────────────────
+/** Error code of a snapshot release that cannot proceed; nothing was written. */
+export const E_TWIN_COLLAPSE_RELEASE = 'E_TWIN_COLLAPSE_RELEASE';
+/** Pairs whose loss the recovery (T12727) verifies; a release covers only these. */
+const RECOVERABLE_PAIRS = [SCHEMA_META, STICKY_TAGS];
+/** Whether a recorded snapshot path is the one `id` names (backup id, file name or path). */
+function namesSnapshot(path, id) {
+    const want = basename(id);
+    const have = basename(path);
+    return have === want || have.endsWith(`.${want}`);
+}
+/**
+ * Plan releasing a pre-collapse snapshot (T12767): which markers reference
+ * it, how many bytes it holds, and whether it may be released. It may only
+ * after a verified recovery or a no-recovery-needed check: the recovery plan
+ * against it ({@link planTwinCollapseRecovery}) must find nothing left to
+ * recover, and only the `schema_meta` / `sticky_tags` markers (the pairs the
+ * recovery covers) may reference it.
+ *
+ * @param live - The project `cleo.db` connection (read-only is enough).
+ * @param id - The snapshot: its backup id (`migration-<timestamp>`), file name or path.
+ * @param snapshot - The snapshot opened read-only, or `null` when it is not on disk.
+ * @returns The plan.
+ * @task T12767
+ */
+export function planSnapshotRelease(live, id, snapshot, options = {}) {
+    let path = null;
+    const markers = [];
+    const blockers = [];
+    for (const pair of PAIRS) {
+        if (!hasMainTable(live, pair.kvTable))
+            continue;
+        const recorded = readState(live, pair)?.snapshot;
+        if (typeof recorded !== 'string' || !namesSnapshot(recorded, id))
+            continue;
+        path ??= recorded;
+        markers.push(`${pair.kvTable}:${TWIN_COLLAPSE_MARKER_PREFIX}${pair.table}`);
+        if (!RECOVERABLE_PAIRS.includes(pair))
+            blockers.push(`the ${pair.table} marker references it, and the recovery does not cover ${pair.table}`);
+    }
+    if (path === null)
+        return {
+            snapshot: null,
+            markers,
+            exists: false,
+            bytes: 0,
+            basis: null,
+            receipts: [],
+            blockers: [`no twin-collapse marker references ${id}`],
+            movedFrom: null,
+        };
+    // A moved store (T12788): the markers name the old path; the file is local.
+    const recorded = path;
+    path = options.snapshotPath ?? recorded;
+    const exists = existsSync(path);
+    const bytes = [path, `${path}-wal`, `${path}-shm`].reduce((sum, f) => sum + (existsSync(f) ? statSync(f).size : 0), 0);
+    const receipts = [...recoveryReceipts(live)]
+        .filter(([, r]) => r.rolledBackAt === null && (r.snapshot === path || r.snapshot === recorded))
+        .map(([k]) => k)
+        .sort();
+    if (!exists || snapshot === null)
+        blockers.push('the snapshot is not on disk, so no recovery check can run against it');
+    else {
+        const recovery = planTwinCollapseRecovery(live, snapshot, { snapshotPath: path });
+        if (recovery.changes)
+            blockers.push(`it still holds ${recovery.archive.length} value(s), ${recovery.focusNotesAdded} session note(s) and ` +
+                `${recovery.stickyArchived.length} sticky tag(s) the live store lacks: run --recover first`);
+    }
+    return {
+        snapshot: path,
+        markers,
+        exists,
+        bytes,
+        basis: blockers.length > 0 ? null : receipts.length > 0 ? 'recovered' : 'no-recovery-needed',
+        receipts,
+        blockers,
+        movedFrom: recorded !== path ? recorded : null,
+    };
+}
+/** The release refusal for a plan with blockers. */
+export function releaseRefused(id, plan) {
+    return new CleoError(ExitCode.VALIDATION_ERROR, `${E_TWIN_COLLAPSE_RELEASE}: ${id} cannot be released: ${plan.blockers.join('; ')}; nothing was changed`, {
+        fix: `cleo doctor twin-collapse --recover --dry-run  # then --recover, and --release-snapshot ${id} --dry-run`,
+        details: { field: 'snapshot', actual: plan.snapshot, blockers: plan.blockers },
+    });
+}
+/**
+ * Release a pre-collapse snapshot, in one `BEGIN IMMEDIATE` transaction: the
+ * plan is re-checked under the write lock, each referencing marker's
+ * `snapshot` is cleared (so an open no longer pins it and rotation no longer
+ * keeps it), its sidecar pin is released, and `audit` records the release
+ * before the commit (a failed audit write refuses it). The snapshot file is
+ * never touched; it rotates normally from then on.
+ *
+ * @param live - The project `cleo.db` connection, outside a transaction.
+ * @param id - The snapshot: backup id, file name or path.
+ * @param snapshot - The snapshot opened read-only, or `null`.
+ * @param audit - Appends the audit row; throws to refuse.
+ * @returns What was released.
+ * @throws {CleoError} {@link E_TWIN_COLLAPSE_RELEASE} when it may not be released.
+ * @task T12767
+ */
+export function releaseTwinCollapseSnapshot(live, id, snapshot, audit, options = {}) {
+    live.exec('BEGIN IMMEDIATE');
+    let sidecarBefore;
+    let path = null;
+    try {
+        const plan = planSnapshotRelease(live, id, snapshot, options);
+        if (plan.basis === null || plan.snapshot === null)
+            throw releaseRefused(id, plan);
+        path = plan.snapshot;
+        for (const pair of PAIRS) {
+            const key = `${TWIN_COLLAPSE_MARKER_PREFIX}${pair.table}`;
+            if (!plan.markers.includes(`${pair.kvTable}:${key}`))
+                continue;
+            const raw = readKv(live, pair.kvTable, key);
+            const parsed = raw === undefined ? undefined : parseJson(raw);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw releaseRefused(id, { ...plan, blockers: [`the ${pair.table} marker is unreadable`] });
+            writeKv(live, pair.kvTable, key, JSON.stringify({ ...parsed, snapshot: null }));
+        }
+        sidecarBefore = readBackupSidecar(path, 'migration');
+        const sidecar = unpinBackup(path, 'migration', `T12767: released by an owner after a ${plan.basis} check`);
+        const release = {
+            snapshot: path,
+            markers: plan.markers,
+            basis: plan.basis,
+            bytes: plan.bytes,
+            releasedAt: sidecar.releasedAt ?? new Date().toISOString(),
+            movedFrom: plan.movedFrom,
+        };
+        audit({ ...release, receipts: plan.receipts });
+        live.exec('COMMIT');
+        return release;
+    }
+    catch (error) {
+        if (live.isTransaction)
+            live.exec('ROLLBACK');
+        if (sidecarBefore !== undefined && path !== null)
+            restoreBackupSidecar(path, 'migration', sidecarBefore);
+        throw error;
+    }
+}
 //# sourceMappingURL=twin-collapse.js.map