@cleocode/core 2026.9.23 → 2026.9.25

package/dist/store/twin-collapse.js

@@ -45,13 +45,17 @@
  * | every other key (`schemaVersion`, `version`, `focus_state`, `focus_state:<session>`, `project_meta`, `project`, `parallel_state`, `activeSession`, `reconcile.<task>.release`, any unknown key) | none: the bare value |
  *
  * - **Initial collapse**, when the bare table holds at least one carried key:
- *   every bare key is carried under the rules, and a key only the twin holds
- *   is a frozen copy and is DROPPED (listed in the receipt, marker and log).
- *   The exceptions are `task_id_sequence` and `sqlite_snapshot_gate` (a
- *   counter must not move back) and the collapse keys. `file_meta` is dropped
- *   only when the bare table lacks it; when both have it the field rule
- *   applies. When the bare table holds no carried key (a fresh lineage, e.g.
- *   after exodus landed legacy rows in the twin), nothing is dropped.
+ *   every bare key is carried under the rules (the bare value wins every key
+ *   both hold). A key only the twin holds is KEPT, never dropped (the union
+ *   rule, T12535 audit 2026-09-29): it is listed as `kept` in the receipt and
+ *   marker. When a key's twin value would be replaced by a different result,
+ *   the twin value is copied to `twin_collapse_archive:<key>` in
+ *   `tasks_schema_meta` (listed as `archived`; doctor shows it), so nothing
+ *   unique is left only in the snapshot. `focus_state` merges instead: the
+ *   bare value's current fields win and `sessionNotes` is the union of both,
+ *   deduplicated by `(timestamp, note)` ({@link mergeFocusState}); its twin
+ *   value is archived as well. The pre-collapse snapshot holds the store
+ *   before any change and is pinned (never rotated).
  * - **Incremental re-merge**, per bare key whose hash changed since the last
  *   merge:
  *   - twin unchanged since the last merge → the bare value (counter fields
@@ -68,9 +72,13 @@
  * `sticky_tags` → `brain_sticky_tags` (rows are `(sticky_id, tag)`, both the
  * key, so a collision is two identical rows and one is kept):
  *
- * - Initial collapse, when the bare table has rows: the twin is made equal to
- *   the bare set; frozen twin-only rows are dropped and listed. A bare tag whose
- *   note no longer exists is not carried (`skipped`; it stays in the bare table).
+ * - Initial collapse: bare tags are added. A twin-only tag the note's
+ *   `tags_json` names is kept (listed as `kept`). One it does not name leaves
+ *   the junction (which follows `tags_json`, the value every reader displays)
+ *   and is recorded under `twin_collapse_archive:sticky_tags` in
+ *   `brain_schema_meta` (listed as `archived`); adding it to `tags_json` would
+ *   change the tags the user sees. A bare tag whose note no longer exists is
+ *   not carried (`skipped`; it stays in the bare table).
  * - Incremental re-merge, per sticky id whose bare tag-set hash changed: if
  *   the twin's set for that id is unchanged since the last merge, the twin
  *   set is made equal to the bare set (additions AND removals propagate);
@@ -82,12 +90,58 @@
  *   tag filter can never disagree with the displayed tags. A conflict is still
  *   recorded for `cleo doctor`.
  *
+ * `attachments` + `attachment_refs` → `docs_attachments` + `docs_attachment_refs`
+ * merge as ONE pair, in one transaction (a doc and its refs never diverge).
+ * The bare rows are authoritative over the columns both tables share, except
+ * `ref_count`, which is derived: after every merge it is recomputed as the
+ * number of refs in `docs_attachment_refs`, whoever wrote them (never carried,
+ * never max'd). Rows are keyed `d:<id>` and `r:<attachment_id, owner_type,
+ * owner_id>` in the marker hashes.
+ *
+ * - Initial collapse: the twins are made equal to the bare tables, even when
+ *   the bare tables are empty (the older build never showed a twin-only row);
+ *   frozen twin-only rows are dropped and listed.
+ * - Incremental re-merge, per bare doc whose hash moved (see {@link planDocs}):
+ *   twin changed too → conflict, the twin wins; bare row gone → the twin row
+ *   goes unless a ref or a supersedes link still names it (`kept`); the
+ *   content (sha256) already belongs to another twin row → merged into that
+ *   row: the bare id is aliased to it (`twin_collapse_alias:attachments`) and
+ *   its refs follow; the slug already belongs to another twin row → carried
+ *   under `<slug>-<n>` (`renamed`). Natural keys are checked against the state
+ *   after the merge, so a merge never fails on them. Per bare ref whose hash
+ *   moved: added → added (aliased), removed → removed unless this build
+ *   changed it since.
+ * - Change detection: AFTER triggers on the bare tables (`t12535_track_*`)
+ *   bump `twin_collapse_seq:attachments` on every write, the older build's
+ *   included. An open compares that counter with the marker's instead of
+ *   re-hashing every doc; a missing trigger falls back to the full compare.
+ * - Union shape: migration `20260929000000_t12535-docs-attachments-union-shape`
+ *   adds the bare-only `display_alias` column and indexes; the UNIQUE slug and
+ *   sha256 indexes are dropped and re-created by the merge itself around the
+ *   row changes. Every merge ends with them in place, or rolls back.
+ * - The `supersedes` / `superseded_by` self-FKs are checked at commit
+ *   (`PRAGMA defer_foreign_keys`), so a chain merges in any row order.
+ * - A bare row that violates a twin CHECK (e.g. a non-ISO `created_at`) fails
+ *   the merge; the docs pair opens degraded (docs writes refused, everything
+ *   else writable) and `cleo doctor twin-collapse` shows the cause.
+ * - Blobs: after each merge every twin doc's blob gets a keep-link (and is
+ *   restored from it if the older build unlinked it), see `blob-keep.ts`.
+ * - Freeze (option (a), D11160): every merge installs BEFORE
+ *   INSERT/UPDATE/DELETE triggers on the bare docs tables that abort an
+ *   older build's write with the upgrade message ({@link docsFrozenMessage}).
+ *   This build never writes them, so there is no bypass. Every open checks the freeze and change
+ *   triggers and re-installs missing ones (a rebuild or restore drops them);
+ *   `cleo doctor` reports them missing. The (b) defences above cover the time
+ *   a freeze is missing.
+ *
  * ## Contract
  *
  * 1. **Snapshot first** (initial collapse only, only when the merge changes
  *    the twin). The free space is checked before the `VACUUM INTO`. One
  *    snapshot covers every pair collapsing in this open, registered as a
- *    `migration` backup (`cleo backup list`, rotation).
+ *    PINNED `migration` backup: `cleo backup list` shows it, rotation never
+ *    deletes it, and a snapshot an earlier build wrote unpinned is pinned at
+ *    the next open (`cleo doctor` lists an unpinned one).
  * 2. **Atomic.** Each pair merges, verifies and writes its marker in one
  *    `BEGIN IMMEDIATE` transaction, the marker re-read under the write lock.
  *    Any failure rolls back: both tables byte-identical.
@@ -125,9 +179,16 @@
  * @task T12535
  */
 import { createHash } from 'node:crypto';
+import { existsSync, statSync } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { ExitCode } from '@cleocode/contracts';
+import { z } from 'zod';
 import { CleoError } from '../errors.js';
 import { getLogger } from '../logger.js';
+import { getCleoVersion } from '../scaffold/ensure-config.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');
 /** Prefix of the marker key holding a pair's collapse state. */
@@ -151,6 +212,8 @@ export const SCHEMA_META_NEVER_DELETED = new Set([
     'task_id_sequence',
     SNAPSHOT_GATE_KEY,
 ]);
+/** Why a twin-collapse snapshot is pinned (never rotated). */
+const SNAPSHOT_PIN_REASON = 'T12535 twin collapse: the store before the merge (only copy of any row it replaced)';
 /** Most conflicts kept in the marker (the doctor warning lists them). */
 const MAX_CONFLICTS = 50;
 const sha = (value) => createHash('sha256').update(value).digest('hex');
@@ -194,11 +257,23 @@ function readState(db, pair) {
         dropped: Array.isArray(parsed.dropped) ? parsed.dropped : [],
         conflicts: Array.isArray(parsed.conflicts) ? parsed.conflicts : [],
         conflictsAt: typeof parsed.conflictsAt === 'string' ? parsed.conflictsAt : null,
+        seq: typeof parsed.seq === 'string' ? parsed.seq : null,
+        merged: Array.isArray(parsed.merged) ? parsed.merged : [],
+        renamed: Array.isArray(parsed.renamed) ? parsed.renamed : [],
+        kept: Array.isArray(parsed.kept) ? parsed.kept : [],
+        archived: Array.isArray(parsed.archived) ? parsed.archived : [],
     };
 }
 /** Whether the bare side moved since the stored hashes (or no usable state exists). */
 function bareChanged(db, pair, state) {
-    return !state?.hashes || !sameHashes(state.hashes.bare, pair.bareHashes(db));
+    if (!state?.hashes)
+        return true;
+    if (state.seq !== null && pair.changeSeq !== undefined) {
+        const seq = pair.changeSeq(db);
+        if (seq !== undefined)
+            return seq !== state.seq;
+    }
+    return !sameHashes(state.hashes.bare, pair.bareHashes(db));
 }
 /** Hashes of the last merge; a pre-release marker treats the current twin as unchanged. */
 function lastHashes(db, pair, state) {
@@ -315,6 +390,52 @@ function kvRows(db, table, schema = 'main') {
     const rows = db.prepare(`SELECT key, value FROM ${schema}.${table}`).all();
     return new Map(rows.map((r) => [r.key, r.value]));
 }
+/** Prefix of the key holding a twin value the initial collapse replaced. */
+export const TWIN_COLLAPSE_ARCHIVE_PREFIX = 'twin_collapse_archive:';
+/**
+ * `focus_state` when both tables hold it: the bare value's current fields
+ * win, and the session-note history is the union of both
+ * (`sessionNotes`, deduplicated by `(timestamp, note)`, sorted by timestamp).
+ * The twin may hold months of notes the bare copy never saw (178 KB on the
+ * cleocode Linux store). A value that is not a JSON object stays the bare one
+ * (the replaced twin value is archived either way).
+ *
+ * @param bare - The bare value.
+ * @param twin - The twin value.
+ * @returns The merged value.
+ * @task T12535
+ */
+export function mergeFocusState(bare, twin) {
+    const b = parseJson(bare);
+    const t = parseJson(twin);
+    if (b === null || typeof b !== 'object' || Array.isArray(b))
+        return bare;
+    const notesOf = (v) => v !== null &&
+        typeof v === 'object' &&
+        Array.isArray(v.sessionNotes)
+        ? v.sessionNotes
+        : [];
+    const bareNotes = notesOf(b);
+    const twinNotes = notesOf(t);
+    if (twinNotes.length === 0)
+        return bare;
+    const keyOf = (n) => {
+        const r = (n ?? {});
+        return `${String(r.timestamp ?? '')}\u0000${String(r.note ?? JSON.stringify(n))}`;
+    };
+    const seen = new Set();
+    const union = [];
+    for (const n of [...twinNotes, ...bareNotes]) {
+        const k = keyOf(n);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        union.push(n);
+    }
+    const ts = (n) => String((n ?? {}).timestamp ?? '');
+    union.sort((x, y) => ts(x).localeCompare(ts(y)));
+    return JSON.stringify({ ...b, sessionNotes: union });
+}
 /** Carried rows of a `schema_meta` table. */
 function carriedRows(db, table) {
     const all = kvRows(db, table);
@@ -324,7 +445,17 @@ function carriedRows(db, table) {
     return all;
 }
 const hashMap = (m) => Object.fromEntries([...m].map(([k, v]) => [k, sha(v)]));
-const emptyPlan = () => ({ set: new Map(), del: [], dropped: [], conflicts: [], skipped: 0 });
+const emptyPlan = () => ({
+    set: new Map(),
+    del: [],
+    dropped: [],
+    conflicts: [],
+    skipped: 0,
+    merged: [],
+    renamed: [],
+    kept: [],
+    archived: [],
+});
 function planSchemaMeta(db, state) {
     const plan = emptyPlan();
     const bare = carriedRows(db, 'schema_meta');
@@ -336,14 +467,24 @@ function planSchemaMeta(db, state) {
     if (state === undefined) {
         if (bare.size === 0)
             return plan;
-        for (const [key, value] of bare)
-            want(key, mergeSchemaMetaValue(key, value, twin.get(key)));
-        for (const key of [...twin.keys()].sort()) {
-            if (!bare.has(key) && !SCHEMA_META_NEVER_DELETED.has(key)) {
-                plan.del.push(key);
-                plan.dropped.push(key);
+        for (const [key, value] of [...bare].sort(([a], [b]) => a.localeCompare(b))) {
+            const current = twin.get(key);
+            const merged = key === 'focus_state' && current !== undefined
+                ? mergeFocusState(value, current)
+                : mergeSchemaMetaValue(key, value, current);
+            want(key, merged);
+            // The twin's own value would be replaced: keep a copy of it, so nothing
+            // unique is left only in the snapshot.
+            if (current !== undefined && merged !== null && merged !== current) {
+                plan.set.set(`${TWIN_COLLAPSE_ARCHIVE_PREFIX}${key}`, current);
+                plan.archived.push(key);
             }
         }
+        // The union rule: a key only the twin holds is carried over, never
+        // dropped (listed as kept). The bare value wins every key both hold.
+        for (const key of [...twin.keys()].sort())
+            if (!bare.has(key))
+                plan.kept.push(key);
         return plan;
     }
     const last = lastHashes(db, SCHEMA_META, state);
@@ -467,10 +608,32 @@ function planSticky(db, state) {
         }
     };
     if (state === undefined) {
-        if (bare.size === 0)
-            return plan;
-        for (const id of [...new Set([...bare.keys(), ...twin.keys()])].sort())
-            mirror(id, true);
+        // The union rule: bare tags are added. A twin-only tag the note's
+        // tags_json names is kept (listed as kept). One tags_json does not name is
+        // listed as archived: the junction follows tags_json (the value both
+        // builds write and every reader displays), so it leaves the junction, and
+        // its row is recorded under `twin_collapse_archive:sticky_tags`.
+        const tagsJson = db.prepare('SELECT tags_json FROM main.brain_sticky_notes WHERE id = ?');
+        for (const id of [...new Set([...bare.keys(), ...twin.keys()])].sort()) {
+            const b = new Set(bare.get(id) ?? []);
+            const t = new Set(twin.get(id) ?? []);
+            const alive = b.size === 0 || noteExists.get(id) !== undefined;
+            for (const tag of b) {
+                if (!alive)
+                    plan.skipped++;
+                else if (!t.has(tag))
+                    plan.set.set(`${id}\t${tag}`, '');
+            }
+            const named = new Set(tagsOf(tagsJson.get(id)?.tags_json ?? null));
+            for (const tag of t) {
+                if (b.has(tag))
+                    continue;
+                if (named.has(tag))
+                    plan.kept.push(`${id}\t${tag}`);
+                else
+                    plan.archived.push(`${id}\t${tag}`);
+            }
+        }
         return plan;
     }
     const last = lastHashes(db, STICKY_TAGS, state);
@@ -572,6 +735,12 @@ const STICKY_TAGS = {
         const lingering = plan.del.filter(has).length;
         if (missing > 0 || lingering > 0)
             throw new Error(`sticky_tags collapse did not verify: ${missing} missing, ${lingering} not removed`);
+        if (plan.archived.length > 0) {
+            const key = `${TWIN_COLLAPSE_ARCHIVE_PREFIX}sticky_tags`;
+            const previous = parseJson(readKv(db, 'brain_schema_meta', key) ?? '[]');
+            const rows = new Set([...(Array.isArray(previous) ? previous : []), ...plan.archived]);
+            writeKv(db, 'brain_schema_meta', key, JSON.stringify([...rows].sort()));
+        }
         const synced = syncStickyJunction(db, 'main');
         return {
             inserted: counts.inserted + synced.inserted,
@@ -587,8 +756,669 @@ const STICKY_TAGS = {
         syncStickyJunction(db, 'temp');
     },
 };
+// ── attachments + attachment_refs (docs) ─────────────────────────────────────
+/** Key of the bare→twin id aliases (bare rows merged into a twin row by sha256). */
+export const DOCS_ALIAS_KEY = 'twin_collapse_alias:attachments';
+/** Key the bare-side change triggers bump on every write to the bare docs tables. */
+export const DOCS_CHANGE_SEQ_KEY = 'twin_collapse_seq:attachments';
+/** The bare docs tables (the change triggers watch both). */
+const DOCS_BARE = ['attachments', 'attachment_refs'];
+/** The docs twins (both shadowed in read-only-for-users mode). */
+const DOCS_TWINS = ['docs_attachments', 'docs_attachment_refs'];
+/** Columns recomputed after every merge, never carried (a count of the refs). */
+const DOCS_DERIVED = new Set(['ref_count']);
+/**
+ * The UNIQUE indexes the docs code relies on (union shape with the bare table).
+ * Dropped and re-created by every merge, inside its transaction.
+ */
+const DOCS_UNIQUE_INDEXES = [
+    { name: 'uniq_docs_attachments_slug', on: '(slug) WHERE slug IS NOT NULL' },
+    { name: 'uniq_docs_attachments_sha256', on: '(sha256)' },
+];
+/** Column names of a table, in declaration order. */
+function columnsOf(db, schema, table) {
+    return db.prepare(`SELECT name FROM pragma_table_info(?, ?)`).all(table, schema).map((c) => c.name);
+}
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+/** Columns both tables hold, in the bare table's order, minus `skip`. */
+function sharedColumns(db, bare, twin, skip = new Set()) {
+    const twinCols = new Set(columnsOf(db, 'main', twin));
+    return columnsOf(db, 'main', bare).filter((c) => twinCols.has(c) && !skip.has(c));
+}
+/** The carried doc columns (`ref_count` is derived). */
+const docColumns = (db) => sharedColumns(db, 'attachments', 'docs_attachments', DOCS_DERIVED);
+/** The carried ref columns. */
+const refColumns = (db) => sharedColumns(db, 'attachment_refs', 'docs_attachment_refs');
+/** Rows of a table keyed by the JSON of `key` columns (or the bare id for docs). */
+function carriedRowsOf(db, schema, table, columns, key) {
+    const rows = db
+        .prepare(`SELECT ${columns.map(quoteIdent).join(', ')} FROM ${schema}.${quoteIdent(table)}`)
+        .all();
+    return new Map(rows.map((r) => [
+        key.length === 1 ? String(r[key[0]]) : JSON.stringify(key.map((k) => r[k])),
+        { json: JSON.stringify(columns.map((c) => r[c] ?? null)), values: r },
+    ]));
+}
+const REF_KEY = ['attachment_id', 'owner_type', 'owner_id'];
+/** Docs (`d:<id>`) and refs (`r:<key>`) of one side. */
+function docsSide(db, side) {
+    const [docTable, refTable] = side === 'bare' ? DOCS_BARE : DOCS_TWINS;
+    return {
+        docs: carriedRowsOf(db, 'main', docTable, docColumns(db), ['id']),
+        refs: carriedRowsOf(db, 'main', refTable, refColumns(db), REF_KEY),
+    };
+}
+function docsHashes(db, side) {
+    const { docs, refs } = docsSide(db, side);
+    return Object.fromEntries([
+        ...[...docs].map(([k, v]) => [`d:${k}`, sha(v.json)]),
+        ...[...refs].map(([k, v]) => [`r:${k}`, sha(v.json)]),
+    ]);
+}
+function readAliases(db) {
+    const raw = readKv(db, 'tasks_schema_meta', DOCS_ALIAS_KEY);
+    if (raw === undefined)
+        return {};
+    const parsed = parseJson(raw);
+    return parsed !== null && typeof parsed === 'object' ? parsed : {};
+}
+/** The change-trigger name for one bare table and operation. */
+const trackTrigger = (table, op) => `t12535_track_${table}_${op.toLowerCase()}`;
+/**
+ * AFTER triggers on the bare docs tables that bump {@link DOCS_CHANGE_SEQ_KEY}.
+ * They fire for every writer, the older build included, so an open detects an
+ * unchanged bare side by reading one row instead of re-hashing every doc.
+ */
+function ensureDocsTracking(db) {
+    for (const table of DOCS_BARE) {
+        for (const op of SHADOW_WRITE_OPS) {
+            db.exec(`CREATE TRIGGER IF NOT EXISTS main.${trackTrigger(table, op)} AFTER ${op} ON ${table} BEGIN ` +
+                `INSERT OR IGNORE INTO tasks_schema_meta (key, value) VALUES ('${DOCS_CHANGE_SEQ_KEY}', '0'); ` +
+                `UPDATE tasks_schema_meta SET value = CAST(value AS INTEGER) + 1 WHERE key = '${DOCS_CHANGE_SEQ_KEY}'; END`);
+        }
+    }
+}
+/** The freeze-trigger name for one bare table and operation. */
+const freezeTrigger = (table, op) => `t12535_freeze_${table}_${op.toLowerCase()}`;
+/** Every freeze and change trigger the docs pair keeps on the bare tables. */
+const docsGuardTriggers = () => DOCS_BARE.flatMap((t) => SHADOW_WRITE_OPS.flatMap((op) => [freezeTrigger(t, op), trackTrigger(t, op)]));
+/**
+ * The message an older build's write to a frozen bare docs table aborts with.
+ * It names the release that moved the docs, what fails (docs, changesets, and
+ * the IVTR playbook provenance an older build attaches when a playbook run
+ * finalises), and the upgrade command.
+ *
+ * It must never read as contention or corruption to an older build: those
+ * retry on `sqlite_busy` / `database is locked` and restore backups on
+ * `database disk image is malformed`, so none of those words appear (pinned by
+ * a test, see {@link DOCS_FROZEN_FORBIDDEN}).
+ */
+export function docsFrozenMessage(version) {
+    const needs = version === null ? 'the latest cleo' : `cleo ${version} or newer`;
+    return (`CLEO: docs moved to docs_attachments (T12535); this project needs ${needs} ` +
+        'to write docs, changesets and IVTR playbook provenance. ' +
+        'Run: npm i -g @cleocode/cleo@latest');
+}
+/** Key recording the version of the build that first froze this store's bare docs tables. */
+export const DOCS_FROZEN_BY_KEY = 'twin_collapse_frozen_by:attachments';
+/**
+ * The version the freeze message names: the first RELEASE build that froze
+ * (or later opened) this store, recorded under {@link DOCS_FROZEN_BY_KEY}.
+ *
+ * Why recorded, not a literal: the release that ships the freeze was not
+ * known when the code was written (2026.9.23 shipped without it). Why not the
+ * running build's version: a trigger outlives the build that wrote it, and a
+ * development build (a worktree, or the main checkout) reports the PREVIOUS
+ * release's version, which cannot read the store. So only a published build
+ * (running from an installed package, i.e. under `node_modules`) records its
+ * version, and never the unreadable `0.0.0` fallback. Until one does, the
+ * message names no version and points at `@latest`; the first release build
+ * to open the store records itself and the triggers are re-written.
+ *
+ * @param db - The project `cleo.db` connection.
+ * @returns The version to name, or `null` (no release build has frozen or
+ *   opened this store yet).
+ * @task T12535
+ */
+export function docsFrozenVersion(db) {
+    const recorded = readKv(db, 'tasks_schema_meta', DOCS_FROZEN_BY_KEY);
+    if (recorded !== undefined)
+        return recorded.replace(/[^0-9A-Za-z.+-]/g, '');
+    return releaseBuildVersion();
+}
+/** Test hook: what this process counts as (a published build, and its version). */
+let freezeBuildOverride;
+/**
+ * Test only: make this process count as a published build with `version`
+ * (or restore the real detection with `undefined`).
+ *
+ * @param override - The build to pretend to be.
+ * @task T12535
+ */
+export function setFreezeBuildForTests(override) {
+    freezeBuildOverride = override;
+}
+/**
+ * This build's version when it is a published release, else `null`: running
+ * from an installed package (under `node_modules`) with a real version.
+ */
+function releaseBuildVersion() {
+    const published = freezeBuildOverride?.published ??
+        fileURLToPath(import.meta.url)
+            .split(/[\\/]/)
+            .includes('node_modules');
+    if (!published)
+        return null;
+    const version = (freezeBuildOverride?.version ?? getCleoVersion()).replace(/[^0-9A-Za-z.+-]/g, '');
+    return /^\d+\.\d+\.\d+/.test(version) && version !== '0.0.0' ? version : null;
+}
+/** Phrases the freeze message must never contain (older builds' retry and recovery matchers). */
+export const DOCS_FROZEN_FORBIDDEN = [
+    'sqlite_busy',
+    'database is locked',
+    'database disk image is malformed',
+    'malformed',
+    'corrupt',
+    'not a database',
+];
+/**
+ * BEFORE INSERT/UPDATE/DELETE triggers on the bare docs tables that abort
+ * every write with {@link docsFrozenMessage} (option (a), owner decision
+ * D11160). SQLite enforces them whatever build writes, so the 2026.9.20 build
+ * can no longer write rows this build treats as frozen: no duplicate content
+ * or slug, no split ref counts, no stale-read deletes, no ADR number reuse.
+ * Its reads keep working (they show the frozen docs).
+ *
+ * There is no bypass: this build never writes the bare tables. A migration
+ * that rebuilds or drops them is not affected (DDL does not fire DML triggers;
+ * the triggers go with a renamed or dropped table and are re-installed at the
+ * next open, see {@link repairGuards}).
+ */
+function ensureDocsFreeze(db) {
+    if (readKv(db, 'tasks_schema_meta', DOCS_FROZEN_BY_KEY) === undefined) {
+        const version = releaseBuildVersion();
+        if (version !== null)
+            writeKv(db, 'tasks_schema_meta', DOCS_FROZEN_BY_KEY, version);
+    }
+    for (const table of DOCS_BARE) {
+        for (const op of SHADOW_WRITE_OPS) {
+            const name = freezeTrigger(table, op);
+            // A trigger with another text (an older message or version) is replaced.
+            if (freezeSql(db, name) !== undefined && !freezeUpToDate(db, table, op))
+                db.exec(`DROP TRIGGER main.${name}`);
+            db.exec(`CREATE TRIGGER IF NOT EXISTS main.${name} BEFORE ${op} ON ${table} ` +
+                `BEGIN ${freezeBody(db)} END`);
+        }
+    }
+}
+/** The freeze trigger's body (it carries the message). */
+const freezeBody = (db) => `SELECT RAISE(ABORT, '${docsFrozenMessage(docsFrozenVersion(db)).replace(/'/g, "''")}');`;
+/** The stored SQL of a trigger, or `undefined` when it does not exist. */
+function freezeSql(db, name) {
+    return db
+        .prepare("SELECT sql FROM main.sqlite_master WHERE type = 'trigger' AND name = ?")
+        .get(name)?.sql;
+}
+/** Whether a freeze trigger exists with the current table, event and message. */
+function freezeUpToDate(db, table, op) {
+    const sql = freezeSql(db, freezeTrigger(table, op));
+    return sql?.includes(`BEFORE ${op} ON ${table} `) === true && sql.includes(freezeBody(db));
+}
+/** Whether every freeze and change trigger is in place. */
+function docsGuardsIntact(db) {
+    const names = docsGuardTriggers();
+    const present = db
+        .prepare(`SELECT COUNT(*) AS n FROM main.sqlite_master WHERE type = 'trigger' AND name IN (${names.map(() => '?').join(', ')})`)
+        .get(...names).n;
+    if (present !== names.length)
+        return false;
+    return DOCS_BARE.every((t) => SHADOW_WRITE_OPS.every((op) => freezeUpToDate(db, t, op)));
+}
+/** Install the freeze and change triggers (idempotent). */
+function ensureDocsGuards(db) {
+    ensureDocsFreeze(db);
+    ensureDocsTracking(db);
+}
+/** The bare side's change counter, or `undefined` when a change trigger is missing. */
+function docsChangeSeq(db) {
+    const names = DOCS_BARE.flatMap((t) => SHADOW_WRITE_OPS.map((op) => trackTrigger(t, op)));
+    const present = db
+        .prepare(`SELECT COUNT(*) AS n FROM main.sqlite_master WHERE type = 'trigger' AND name IN (${names.map(() => '?').join(', ')})`)
+        .get(...names).n;
+    if (present !== names.length)
+        return undefined;
+    return readKv(db, 'tasks_schema_meta', DOCS_CHANGE_SEQ_KEY) ?? '0';
+}
+/** The first `<slug>-<n>` (n ≥ 2) no other twin row holds. */
+function freeSlug(slug, owners, id) {
+    for (let n = 2;; n++) {
+        const candidate = `${slug}-${n}`;
+        const holder = owners.get(candidate);
+        if (holder === undefined || holder === id)
+            return candidate;
+    }
+}
+/**
+ * The initial docs collapse: a union that never drops content.
+ *
+ * - A row whose id the bare table has: the bare row is authoritative. When the
+ *   twin's row under that id holds DIFFERENT bytes, the twin's version is
+ *   kept as its own row `<id>~twin-<sha8>` (no slug, superseded by the bare
+ *   row) and listed as merged, so no content leaves the twins (unless those
+ *   bytes are already another row's). A metadata-only difference (same sha256)
+ *   goes to the bare row.
+ * - A twin-only row whose sha256 a bare row (or an earlier kept twin-only
+ *   row) holds, i.e. the same content under another id: merged into that row
+ *   (listed as merged), its refs and any supersedes link moved onto it.
+ * - Any other twin-only row: kept under its own id. When a bare row holds its
+ *   slug, the bare (live) doc keeps the slug and this one is carried as
+ *   `<slug>-<n>` (listed as renamed).
+ * - Refs: every bare ref and every twin ref (remapped onto merged ids) is kept.
+ */
+function planInitialDocs(db, plan, bare, twin) {
+    const columns = docColumns(db);
+    const refCols = refColumns(db);
+    const idAt = refCols.indexOf('attachment_id');
+    const bareBySha = new Map();
+    const slugOwner = new Map();
+    for (const [id, row] of bare.docs) {
+        bareBySha.set(String(row.values.sha256), id);
+        if (typeof row.values.slug === 'string')
+            slugOwner.set(row.values.slug, id);
+    }
+    for (const [id, row] of bare.docs)
+        if (twin.docs.get(id)?.json !== row.json)
+            plan.set.set(`d:${id}`, row.json);
+    // An id both tables hold with DIFFERENT content: the bare row wins the id,
+    // and the twin's version is kept as its own row (`<id>~twin-<sha8>`,
+    // superseded by the bare row, no slug), so its bytes stay referenced and
+    // visible. Same content (only metadata differs): the bare row wins.
+    for (const [id, row] of bare.docs) {
+        const twinRow = twin.docs.get(id);
+        if (twinRow === undefined)
+            continue;
+        const content = String(twinRow.values.sha256);
+        if (content === String(row.values.sha256))
+            continue;
+        const owner = bareBySha.get(content);
+        if (owner !== undefined) {
+            plan.merged.push(`${id} (twin version) -> ${owner}`);
+            continue;
+        }
+        const archiveId = `${id}~twin-${content.slice(0, 8)}`;
+        const values = {
+            ...twinRow.values,
+            id: archiveId,
+            slug: null,
+            lifecycle_status: 'superseded',
+            superseded_by: id,
+        };
+        plan.set.set(`d:${archiveId}`, JSON.stringify(columns.map((c) => values[c] ?? null)));
+        plan.merged.push(`${id} (twin version) -> ${archiveId}`);
+        bareBySha.set(content, archiveId);
+    }
+    // Twin-only rows: merge same-content duplicates into the bare row, keep the rest.
+    const mergedInto = new Map();
+    const kept = [];
+    for (const id of [...twin.docs.keys()].sort()) {
+        if (bare.docs.has(id))
+            continue;
+        const row = twin.docs.get(id);
+        const content = String(row.values.sha256);
+        // The same content in a bare row, or in a twin-only row kept already
+        // (a frozen twin had no UNIQUE sha256 index).
+        const owner = bareBySha.get(content);
+        if (owner !== undefined) {
+            mergedInto.set(id, owner);
+            plan.del.push(`d:${id}`);
+            plan.merged.push(`${id} -> ${owner}`);
+        }
+        else {
+            bareBySha.set(content, id);
+            kept.push(id);
+        }
+    }
+    for (const id of kept) {
+        const row = twin.docs.get(id);
+        const values = { ...row.values };
+        let changed = false;
+        if (typeof values.slug === 'string') {
+            const holder = slugOwner.get(values.slug);
+            if (holder !== undefined && holder !== id) {
+                const next = freeSlug(values.slug, slugOwner, id);
+                plan.renamed.push(`${id}: ${values.slug} -> ${next}`);
+                values.slug = next;
+                changed = true;
+            }
+            slugOwner.set(values.slug, id);
+        }
+        for (const col of ['supersedes', 'superseded_by']) {
+            const target = values[col];
+            if (typeof target === 'string' && mergedInto.has(target)) {
+                values[col] = mergedInto.get(target);
+                changed = true;
+            }
+        }
+        if (changed)
+            plan.set.set(`d:${id}`, JSON.stringify(columns.map((c) => values[c] ?? null)));
+    }
+    // Refs: the union, twin refs remapped onto merged ids.
+    for (const [key, row] of bare.refs)
+        if (twin.refs.get(key)?.json !== row.json)
+            plan.set.set(`r:${key}`, row.json);
+    for (const [key, row] of twin.refs) {
+        const [attachmentId, ownerType, ownerId] = JSON.parse(key);
+        const target = mergedInto.get(attachmentId);
+        if (target === undefined)
+            continue; // kept as it is
+        plan.del.push(`r:${key}`);
+        const moved = JSON.stringify([target, ownerType, ownerId]);
+        if (bare.refs.has(moved) || plan.set.has(`r:${moved}`))
+            continue;
+        const values = JSON.parse(row.json);
+        values[idAt] = target;
+        plan.set.set(`r:${moved}`, JSON.stringify(values));
+    }
+    return plan;
+}
+/**
+ * Plan the docs merge. Keys: `d:<twin id>` (doc rows) and `r:<JSON key>` (refs).
+ *
+ * Initial collapse, a union that never drops content ({@link planInitialDocs}):
+ * bare rows are authoritative for their ids; twin-only rows are kept (on the
+ * live cleocode store they are the whole docs history before 2026-06-03: ADRs,
+ * specs, research, with live task refs), except a twin-only row whose content
+ * a bare row holds, which is merged into that bare row; refs are united.
+ *
+ * Incremental re-merge, per bare doc whose row hash moved since the last merge
+ * (its id translated through the aliases):
+ * - twin row changed too → conflict, the twin wins;
+ * - bare row gone → the twin row is deleted unless a ref (from either build)
+ *   or a supersedes link still names it;
+ * - the content (sha256) is another twin row's → no new row: the bare id is
+ *   aliased to that row, and its refs follow it;
+ * - the slug is another twin row's → the doc is carried under `<slug>-<n>`
+ *   (listed as renamed);
+ * - otherwise the bare row is upserted.
+ * Per bare ref whose hash moved: an added ref is added (under the aliased id)
+ * unless the twin has it or its doc is gone; a removed ref is removed unless
+ * this build changed it since.
+ */
+function planDocs(db, state) {
+    const plan = emptyPlan();
+    const bare = docsSide(db, 'bare');
+    const twin = docsSide(db, 'twin');
+    if (state === undefined)
+        return planInitialDocs(db, plan, bare, twin);
+    const last = lastHashes(db, DOCS, state);
+    const aliases = { ...readAliases(db) };
+    plan.aliases = aliases;
+    const hashOf = (row) => (row ? sha(row.json) : ABSENT);
+    const columns = docColumns(db);
+    const deletions = [];
+    const candidates = [];
+    const lastBareDocs = Object.keys(last.bare)
+        .filter((k) => k.startsWith('d:'))
+        .map((k) => k.slice(2));
+    for (const b of [...new Set([...bare.docs.keys(), ...lastBareDocs])].sort()) {
+        const bareRow = bare.docs.get(b);
+        if (hashOf(bareRow) === (last.bare[`d:${b}`] ?? ABSENT))
+            continue;
+        const x = aliases[b] ?? b;
+        const twinRow = twin.docs.get(x);
+        if (hashOf(twinRow) !== (last.twin[`d:${x}`] ?? ABSENT)) {
+            plan.conflicts.push(JSON.stringify([b]));
+            continue;
+        }
+        if (bareRow === undefined) {
+            if (twinRow !== undefined)
+                deletions.push(x);
+        }
+        else {
+            candidates.push({ b, x, twinRow });
+        }
+    }
+    // Natural keys are checked against the state AFTER the merge: twin rows the
+    // merge does not touch, plus the carried rows (so two docs swapping a slug
+    // do not collide with each other's old values).
+    const moving = new Set([...deletions, ...candidates.map((c) => c.x)]);
+    const shaOwner = new Map();
+    const slugOwner = new Map();
+    for (const [id, row] of twin.docs) {
+        if (moving.has(id))
+            continue;
+        shaOwner.set(String(row.values.sha256), id);
+        if (typeof row.values.slug === 'string')
+            slugOwner.set(row.values.slug, id);
+    }
+    for (const { b, x, twinRow } of candidates) {
+        const values = { ...(bare.docs.get(b)?.values ?? {}), id: x };
+        const content = String(values.sha256);
+        const holder = shaOwner.get(content);
+        if (holder !== undefined && holder !== x) {
+            if (twinRow === undefined) {
+                aliases[b] = holder;
+                plan.merged.push(`${b} -> ${holder}`);
+            }
+            else {
+                plan.conflicts.push(JSON.stringify([b]));
+                // The twin row stays as it is: keep its keys owned.
+                shaOwner.set(String(twinRow.values.sha256), x);
+                if (typeof twinRow.values.slug === 'string')
+                    slugOwner.set(twinRow.values.slug, x);
+            }
+            continue;
+        }
+        if (typeof values.slug === 'string') {
+            const slugHolder = slugOwner.get(values.slug);
+            if (slugHolder !== undefined && slugHolder !== x) {
+                const next = freeSlug(values.slug, slugOwner, x);
+                plan.renamed.push(`${b}: ${values.slug} -> ${next}`);
+                values.slug = next;
+            }
+        }
+        shaOwner.set(content, x);
+        if (typeof values.slug === 'string')
+            slugOwner.set(values.slug, x);
+        const json = JSON.stringify(columns.map((c) => values[c] ?? null));
+        if (twinRow?.json !== json)
+            plan.set.set(`d:${x}`, json);
+    }
+    const refCols = refColumns(db);
+    const idAt = refCols.indexOf('attachment_id');
+    const lastBareRefs = Object.keys(last.bare)
+        .filter((k) => k.startsWith('r:'))
+        .map((k) => k.slice(2));
+    const docGoing = new Set(deletions);
+    const docExists = (id) => (twin.docs.has(id) && !docGoing.has(id)) || plan.set.has(`d:${id}`);
+    for (const key of [...new Set([...bare.refs.keys(), ...lastBareRefs])].sort()) {
+        const bareRef = bare.refs.get(key);
+        if (hashOf(bareRef) === (last.bare[`r:${key}`] ?? ABSENT))
+            continue;
+        const [attachmentId, ownerType, ownerId] = JSON.parse(key);
+        const target = aliases[attachmentId] ?? attachmentId;
+        const twinKey = JSON.stringify([target, ownerType, ownerId]);
+        const twinRef = twin.refs.get(twinKey);
+        if (bareRef !== undefined) {
+            if (twinRef !== undefined)
+                continue; // the twin already holds this ref
+            if (!docExists(target)) {
+                plan.skipped++;
+                continue;
+            }
+            const values = JSON.parse(bareRef.json);
+            values[idAt] = target;
+            plan.set.set(`r:${twinKey}`, JSON.stringify(values));
+        }
+        else if (twinRef !== undefined && hashOf(twinRef) === (last.twin[`r:${twinKey}`] ?? ABSENT)) {
+            plan.del.push(`r:${twinKey}`);
+        }
+    }
+    // A doc row goes only when nothing names it any more.
+    const refsAfter = new Map();
+    for (const [key] of twin.refs) {
+        if (plan.del.includes(`r:${key}`))
+            continue;
+        const id = JSON.parse(key)[0];
+        refsAfter.set(id, (refsAfter.get(id) ?? 0) + 1);
+    }
+    for (const key of plan.set.keys()) {
+        if (!key.startsWith('r:'))
+            continue;
+        const id = JSON.parse(key.slice(2))[0];
+        refsAfter.set(id, (refsAfter.get(id) ?? 0) + 1);
+    }
+    const linked = new Set();
+    for (const [id, row] of twin.docs) {
+        if (docGoing.has(id))
+            continue;
+        for (const col of ['supersedes', 'superseded_by']) {
+            const v = row.values[col];
+            if (typeof v === 'string')
+                linked.add(v);
+        }
+    }
+    for (const id of deletions) {
+        if ((refsAfter.get(id) ?? 0) > 0 || linked.has(id))
+            plan.kept.push(id);
+        else
+            plan.del.push(`d:${id}`);
+    }
+    return plan;
+}
+/** Apply a docs plan to `schema` (`main`, or `temp` for the shadows). */
+function applyDocs(db, schema, plan) {
+    const docCols = docColumns(db);
+    const refCols = refColumns(db);
+    const [docs, refs] = DOCS_TWINS;
+    const before = new Set(db.prepare(`SELECT id FROM ${schema}.${docs}`).all().map((r) => r.id));
+    const refsBefore = new Set(db
+        .prepare(`SELECT attachment_id, owner_type, owner_id FROM ${schema}.${refs}`)
+        .all().map((r) => JSON.stringify(REF_KEY.map((k) => r[k]))));
+    const upsert = (table, cols, key) => db.prepare(`INSERT INTO ${schema}.${table} (${cols.map(quoteIdent).join(', ')}) ` +
+        `VALUES (${cols.map(() => '?').join(', ')}) ` +
+        `ON CONFLICT(${key.map(quoteIdent).join(', ')}) DO UPDATE SET ` +
+        cols
+            .filter((c) => !key.includes(c))
+            .map((c) => `${quoteIdent(c)} = excluded.${quoteIdent(c)}`)
+            .join(', '));
+    const upsertDoc = upsert(docs, docCols, ['id']);
+    const upsertRef = upsert(refs, refCols, REF_KEY);
+    const delDoc = db.prepare(`DELETE FROM ${schema}.${docs} WHERE id = ?`);
+    const delRef = db.prepare(`DELETE FROM ${schema}.${refs} WHERE attachment_id = ? AND owner_type = ? AND owner_id = ?`);
+    let inserted = 0;
+    let replaced = 0;
+    let deleted = 0;
+    const params = (json) => JSON.parse(json);
+    for (const key of plan.del)
+        if (key.startsWith('r:'))
+            deleted += Number(delRef.run(...params(key.slice(2))).changes);
+    for (const key of plan.del)
+        if (key.startsWith('d:'))
+            deleted += Number(delDoc.run(key.slice(2)).changes);
+    for (const [key, json] of plan.set) {
+        if (!key.startsWith('d:'))
+            continue;
+        upsertDoc.run(...params(json));
+        if (before.has(key.slice(2)))
+            replaced++;
+        else
+            inserted++;
+    }
+    for (const [key, json] of plan.set) {
+        if (!key.startsWith('r:'))
+            continue;
+        upsertRef.run(...params(json));
+        if (refsBefore.has(key.slice(2)))
+            replaced++;
+        else
+            inserted++;
+    }
+    // `ref_count` is derived: the number of refs, whoever wrote them.
+    db.exec(`UPDATE ${schema}.${docs} SET ref_count = ` +
+        `(SELECT COUNT(*) FROM ${schema}.${refs} r WHERE r.attachment_id = ${docs}.id) ` +
+        `WHERE ref_count IS NOT (SELECT COUNT(*) FROM ${schema}.${refs} r WHERE r.attachment_id = ${docs}.id)`);
+    return { inserted, replaced, deleted };
+}
+/**
+ * `attachments` + `attachment_refs` → `docs_attachments` + `docs_attachment_refs`,
+ * merged as ONE pair in one transaction: a doc and its refs never diverge, and
+ * `ref_count` is recomputed from the merged refs (never carried). See
+ * {@link planDocs} for the rules. Every merge ends with the UNIQUE `slug` and
+ * `sha256` indexes in place and the bare-side change triggers installed; after
+ * the commit, every twin doc's blob is pinned (and restored if an older build
+ * deleted it, see `blob-keep.ts`).
+ */
+const DOCS = {
+    table: 'attachments',
+    twin: 'docs_attachments',
+    kvTable: 'tasks_schema_meta',
+    tables: [...DOCS_BARE, ...DOCS_TWINS, 'tasks_schema_meta'],
+    shadows: DOCS_TWINS,
+    bareHashes: (db) => docsHashes(db, 'bare'),
+    twinHashes: (db) => docsHashes(db, 'twin'),
+    changeSeq: docsChangeSeq,
+    guardsIntact: docsGuardsIntact,
+    installGuards: ensureDocsGuards,
+    plan: planDocs,
+    apply(db, plan) {
+        // Rows may reference each other (self foreign keys); check at COMMIT.
+        db.exec('PRAGMA defer_foreign_keys = ON');
+        for (const index of DOCS_UNIQUE_INDEXES)
+            db.exec(`DROP INDEX IF EXISTS main.${quoteIdent(index.name)}`);
+        const counts = applyDocs(db, 'main', plan);
+        for (const index of DOCS_UNIQUE_INDEXES)
+            db.exec(`CREATE UNIQUE INDEX main.${quoteIdent(index.name)} ON docs_attachments ${index.on}`);
+        if (plan.aliases !== undefined)
+            writeKv(db, 'tasks_schema_meta', DOCS_ALIAS_KEY, JSON.stringify(plan.aliases));
+        ensureDocsGuards(db);
+        const after = docsSide(db, 'twin');
+        for (const [key, json] of plan.set) {
+            const got = key.startsWith('d:')
+                ? after.docs.get(key.slice(2))?.json
+                : after.refs.get(key.slice(2))?.json;
+            if (got !== json)
+                throw new Error(`attachments collapse did not verify for ${key}`);
+        }
+        for (const key of plan.del) {
+            const present = key.startsWith('d:')
+                ? after.docs.has(key.slice(2))
+                : after.refs.has(key.slice(2));
+            if (present)
+                throw new Error(`attachments collapse did not verify the removal of ${key}`);
+        }
+        return counts;
+    },
+    shadow(db, plan) {
+        const keys = {
+            docs_attachments: ['id'],
+            docs_attachment_refs: REF_KEY,
+        };
+        for (const twin of DOCS_TWINS) {
+            db.exec(`CREATE TEMP TABLE IF NOT EXISTS ${twin} AS SELECT * FROM main.${twin} WHERE 0`);
+            db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS temp.${quoteIdent(`${twin}_shadow_key`)} ` +
+                `ON ${twin} (${(keys[twin] ?? []).map(quoteIdent).join(', ')})`);
+            db.exec(`DELETE FROM temp.${twin}`);
+            db.exec(`INSERT INTO temp.${twin} SELECT * FROM main.${twin}`);
+        }
+        applyDocs(db, 'temp', plan);
+    },
+    afterCommit(db, _plan, dbPath) {
+        const cleoDir = dirname(dbPath);
+        const rows = db
+            .prepare('SELECT sha256, attachment_json FROM main.docs_attachments')
+            .all();
+        for (const row of rows) {
+            const primary = blobFileForRow(cleoDir, row.sha256, row.attachment_json);
+            if (primary === null)
+                continue;
+            restoreBlob(cleoDir, row.sha256, primary);
+            pinBlob(cleoDir, row.sha256, primary);
+        }
+    },
+};
 /** The pairs this build collapses, in order. */
-const PAIRS = [SCHEMA_META, STICKY_TAGS];
+const PAIRS = [SCHEMA_META, STICKY_TAGS, DOCS];
 /** Connections serving TEMP shadows because their collapse failed. */
 const degraded = new WeakMap();
 /**
@@ -603,22 +1433,29 @@ export function twinCollapseFailureOf(db) {
     return degraded.get(db);
 }
 /**
- * Refuse a write before its first statement when the store is degraded by a
- * failed twin collapse. The write accessors of the collapsed tables
- * (`tasks_schema_meta`, and sticky notes and tags) call it at entry, so a
- * degraded store never takes a partial write (e.g. a sticky's `tags_json`
- * without its tag rows). The shadows' TEMP triggers stay as the backstop.
- *
- * @param handle - The connection the write would use (a `DatabaseSync`, or a
- *   drizzle instance's `$client`); anything else is not checked.
- * @throws {CleoError} `E_TWIN_COLLAPSE_FAILED` when the connection is degraded.
+ * Refuse a write before its first statement when the collapse of the table it
+ * writes failed. The write accessors of the collapsed tables
+ * (`tasks_schema_meta`, sticky notes and tags, the docs tables) call it at
+ * entry, so a degraded store never takes a partial write (e.g. a sticky's
+ * `tags_json` without its tag rows). Only the failed pairs are blocked: a
+ * docs merge failure leaves task and sticky writes alone. The shadows' TEMP
+ * triggers stay as the backstop.
+ *
+ * @param handle - The connection the write would use: the native
+ *   `DatabaseSync`, or a drizzle instance (its `$client` is checked).
+ *   `null`/`undefined` (no bound handle) is not checked.
+ * @param table - The bare table whose pair the write belongs to.
+ * @throws {CleoError} `E_TWIN_COLLAPSE_FAILED` when that pair's collapse failed.
  * @task T12535
  */
-export function assertTwinCollapseWritable(handle) {
-    if (typeof handle !== 'object' || handle === null)
+export function assertTwinCollapseWritable(handle, table) {
+    if (!handle)
         return;
-    const failure = degraded.get(handle);
-    if (failure)
+    const native = '$client' in handle ? handle.$client : handle;
+    if (typeof native !== 'object' || native === null)
+        return;
+    const failure = degraded.get(native);
+    if (failure?.tables.includes(table))
         throw twinCollapseError(failure);
 }
 /**
@@ -639,10 +1476,16 @@ export function twinCollapseError(failure, cause) {
         ? ` The snapshot needs ${failure.requiredBytes} bytes free` +
             (failure.availableBytes === null ? '.' : ` (${failure.availableBytes} free).`)
         : '';
+    const snapshotProblem = failure.cause.startsWith(SNAPSHOT_FAILURE_PREFIX);
     return new CleoError(ExitCode.TWIN_COLLAPSE_FAILED, `Twin collapse of ${failure.tables.join(', ')} failed (both tables unchanged; reads still ` +
-        `work, writes are refused): ${failure.cause}.${where}${space} Run 'cleo doctor twin-collapse'.`, {
-        fix: "Run 'cleo doctor twin-collapse' for details, clear the cause (free the space, make " +
-            ".cleo/backups/sqlite writable), then 'cleo doctor twin-collapse --retry'.",
+        `work, writes to them are refused): ${failure.cause}.${where}${space} ` +
+        "Run 'cleo doctor twin-collapse'.", {
+        fix: snapshotProblem
+            ? 'The snapshot could not be written: free the space or make .cleo/backups/sqlite ' +
+                "writable, then run 'cleo doctor twin-collapse --retry'."
+            : 'The merge rejected a row of the bare table (the cause names the constraint, e.g. a ' +
+                "CHECK or UNIQUE). Fix or remove that row, then run 'cleo doctor twin-collapse --retry'; " +
+                "'cleo doctor twin-collapse' shows the details.",
         details: { field: 'twinCollapse', ...failure },
         cause,
     });
@@ -659,6 +1502,8 @@ function recordFailure(db, pairs, failure) {
         }
     }
 }
+/** Cause prefix of a failure to write the snapshot (before any merge). */
+const SNAPSHOT_FAILURE_PREFIX = 'snapshot not written: ';
 /** Message a write into a sealed shadow aborts with. */
 export const SHADOW_WRITE_REFUSED = 'E_TWIN_COLLAPSE_FAILED: store is read-only until the twin collapse succeeds; run cleo doctor twin-collapse';
 const SHADOW_WRITE_OPS = ['INSERT', 'UPDATE', 'DELETE'];
@@ -684,7 +1529,8 @@ function sealShadow(db, twin) {
 /** Drop the TEMP shadows (and their triggers) of a connection that is no longer degraded. */
 function clearShadows(db) {
     for (const pair of PAIRS)
-        db.exec(`DROP TABLE IF EXISTS temp.${pair.twin}`);
+        for (const shadow of pair.shadows ?? [pair.twin])
+            db.exec(`DROP TABLE IF EXISTS temp.${shadow}`);
     degraded.delete(db);
 }
 function receipt(pair, status, snapshotPath) {
@@ -699,10 +1545,14 @@ function receipt(pair, status, snapshotPath) {
         skipped: 0,
         dropped: [],
         conflicts: [],
+        merged: [],
+        renamed: [],
+        kept: [],
+        archived: [],
     };
 }
 /** Run one pair's merge in its own transaction. */
-function collapsePair(db, pair, snapshotPath) {
+function collapsePair(db, pair, snapshotPath, dbPath) {
     db.exec('BEGIN IMMEDIATE');
     try {
         // Re-read under the write lock: another process may have merged since.
@@ -721,21 +1571,40 @@ function collapsePair(db, pair, snapshotPath) {
             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,
+            archived: state === undefined ? plan.archived : state.archived,
             conflicts: plan.conflicts.slice(0, MAX_CONFLICTS),
             conflictsAt: plan.conflicts.length > 0 ? now : null,
+            seq: pair.changeSeq?.(db) ?? null,
+            merged: plan.merged.slice(0, MAX_CONFLICTS),
+            renamed: plan.renamed.slice(0, MAX_CONFLICTS),
         };
         writeKv(db, pair.kvTable, `${TWIN_COLLAPSE_MARKER_PREFIX}${pair.table}`, JSON.stringify(next));
         db.prepare(`DELETE FROM main.${pair.kvTable} WHERE key = ?`).run(`${TWIN_COLLAPSE_FAILURE_PREFIX}${pair.table}`);
         db.exec('COMMIT');
+        try {
+            pair.afterCommit?.(db, plan, dbPath);
+        }
+        catch (error) {
+            log.warn({ err: error }, `after-merge work for ${pair.table} failed (T12535)`);
+        }
         const done = {
             ...receipt(pair, state === undefined ? 'initial' : 'incremental', next.snapshot),
             ...counts,
             skipped: plan.skipped,
             dropped: plan.dropped,
             conflicts: plan.conflicts,
+            merged: plan.merged,
+            renamed: plan.renamed,
+            kept: plan.kept,
+            archived: plan.archived,
         };
         if (counts.inserted + counts.replaced + counts.deleted > 0 || plan.conflicts.length > 0)
             log.warn(done, `carried bare ${pair.table} into ${pair.twin} (${done.status}, T12535)`);
@@ -747,6 +1616,30 @@ function collapsePair(db, pair, snapshotPath) {
         throw error;
     }
 }
+/**
+ * Re-install a collapsed pair's bare-table triggers when something removed
+ * them (a table rebuild, a restore, a journal probe that skipped a migration:
+ * the T12541 class). One `sqlite_master` read per open; a write only when a
+ * trigger is missing. Best effort: a failure is logged and `cleo doctor`
+ * reports the missing triggers.
+ */
+function repairGuards(db, pair) {
+    if (!pair.guardsIntact || !pair.installGuards || pair.guardsIntact(db))
+        return;
+    if (db.isTransaction || degraded.has(db))
+        return;
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        pair.installGuards(db);
+        db.exec('COMMIT');
+        log.warn({ table: pair.table }, `re-installed the bare ${pair.table} triggers (T12535)`);
+    }
+    catch (error) {
+        if (db.isTransaction)
+            db.exec('ROLLBACK');
+        log.warn({ err: error, table: pair.table }, `could not re-install the bare triggers (T12535)`);
+    }
+}
 /**
  * Collapse every bare/twin pair present in the store: the initial collapse
  * (snapshot first) where no marker exists yet, an incremental re-merge of
@@ -774,10 +1667,17 @@ export function collapseTwinTables(nativeDb, dbPath, options = {}) {
             continue;
         }
         const state = readState(nativeDb, pair);
+        // A snapshot an earlier collapse took (a build before pinning) is pinned
+        // now, so rotation never deletes it. Best effort; one sidecar read.
+        if (state?.snapshot)
+            pinBackup(state.snapshot, 'migration', SNAPSHOT_PIN_REASON);
         if (bareChanged(nativeDb, pair, state))
             pending.push(pair);
-        else
+        else {
+            if (state !== undefined)
+                repairGuards(nativeDb, pair);
             byTable.set(pair.table, receipt(pair, 'unchanged', state?.snapshot ?? null));
+        }
     }
     if (pending.length === 0) {
         if (degraded.has(nativeDb))
@@ -795,9 +1695,11 @@ export function collapseTwinTables(nativeDb, dbPath, options = {}) {
         // even that cannot be built, reads cannot be served correctly either.
         try {
             for (const pair of pairs) {
-                unsealShadow(nativeDb, pair.twin);
+                for (const shadow of pair.shadows ?? [pair.twin])
+                    unsealShadow(nativeDb, shadow);
                 pair.shadow(nativeDb, pair.plan(nativeDb, readState(nativeDb, pair)));
-                sealShadow(nativeDb, pair.twin);
+                for (const shadow of pair.shadows ?? [pair.twin])
+                    sealShadow(nativeDb, shadow);
             }
         }
         catch (shadowError) {
@@ -818,12 +1720,12 @@ export function collapseTwinTables(nativeDb, dbPath, options = {}) {
     if (needSnapshot.length > 0) {
         const plan = planMigrationSnapshot(nativeDb, dbPath);
         try {
-            snapshotPath = writeMigrationSnapshot(nativeDb, plan, `T12535 twin collapse of ${needSnapshot.map((p) => p.table).join(', ')} (store before the merge)`);
+            snapshotPath = writeMigrationSnapshot(nativeDb, plan, `T12535 twin collapse of ${needSnapshot.map((p) => p.table).join(', ')} (store before the merge)`, { pinnedReason: SNAPSHOT_PIN_REASON });
         }
         catch (error) {
             fail(needSnapshot, {
                 tables: needSnapshot.map((p) => p.table),
-                cause: `snapshot not written: ${error instanceof Error ? error.message : String(error)}`,
+                cause: `${SNAPSHOT_FAILURE_PREFIX}${error instanceof Error ? error.message : String(error)}`,
                 snapshotPath: plan.snapshotPath,
                 snapshotWritten: false,
                 requiredBytes: plan.requiredBytes,
@@ -840,7 +1742,7 @@ export function collapseTwinTables(nativeDb, dbPath, options = {}) {
     let firstError;
     for (const pair of pending) {
         try {
-            byTable.set(pair.table, collapsePair(nativeDb, pair, snapshotPath));
+            byTable.set(pair.table, collapsePair(nativeDb, pair, snapshotPath, dbPath));
         }
         catch (error) {
             failed.push(pair);
@@ -864,6 +1766,12 @@ export function collapseTwinTables(nativeDb, dbPath, options = {}) {
     }
     return inOrder();
 }
+/** Whether a collapse snapshot on disk is pinned, or `null` when there is none. */
+function snapshotPinnedOf(snapshot) {
+    if (!snapshot || !existsSync(snapshot))
+        return null;
+    return isPinnedBackup(dirname(snapshot), basename(snapshot), 'migration');
+}
 /**
  * Report every pair's collapse state without writing (for `cleo doctor`).
  *
@@ -883,6 +1791,13 @@ export function inspectTwinCollapse(db) {
             changedSinceMerge: 0,
             conflicts: [],
             conflictsAt: null,
+            merged: [],
+            renamed: [],
+            kept: [],
+            archived: [],
+            guardsIntact: null,
+            snapshotPinned: null,
+            snapshotMissing: false,
             failure: null,
         };
         if (!pair.tables.every((t) => hasMainTable(db, t)))
@@ -924,8 +1839,596 @@ export function inspectTwinCollapse(db) {
             changedSinceMerge: state === undefined ? 0 : changed,
             conflicts: state?.conflicts ?? [],
             conflictsAt: state?.conflictsAt ?? null,
+            merged: state?.merged ?? [],
+            renamed: state?.renamed ?? [],
+            kept: state?.kept ?? [],
+            archived: state?.archived ?? [],
+            guardsIntact: state === undefined || pair.guardsIntact === undefined ? null : pair.guardsIntact(db),
+            snapshotPinned: snapshotPinnedOf(state?.snapshot ?? null),
+            snapshotMissing: typeof state?.snapshot === 'string' && !existsSync(state.snapshot),
             failure,
         };
     });
 }
+// ── recovery of what 2026.9.21 dropped or replaced (T12727) ─────────────────
+/** Prefix of a recovery receipt key: `twin_collapse_recovery:<recoveredAt>`. */
+export const TWIN_COLLAPSE_RECOVERY_PREFIX = 'twin_collapse_recovery:';
+/** Error code of a recovery or rollback that cannot proceed; nothing was written. */
+export const E_TWIN_COLLAPSE_RECOVER = 'E_TWIN_COLLAPSE_RECOVER';
+const STICKY_ARCHIVE_KEY = `${TWIN_COLLAPSE_ARCHIVE_PREFIX}sticky_tags`;
+/** A JSON object whose `sessionNotes` is an array (other fields pass through). */
+const FocusNotesShape = z.object({ sessionNotes: z.array(z.unknown()) }).passthrough();
+/** The sticky archive: `sticky_id\ttag` rows. */
+const StickyArchiveShape = z.array(z.string());
+/** Session notes of a `focus_state` value; `[]` when it has none or is not JSON. */
+function sessionNotesOf(value) {
+    if (value === undefined)
+        return [];
+    const parsed = FocusNotesShape.safeParse(parseJson(value));
+    return parsed.success ? parsed.data.sessionNotes : [];
+}
+/** The `(timestamp, note)` identity {@link mergeFocusState} deduplicates on. */
+function noteKey(n) {
+    const r = (n !== null && typeof n === 'object' ? n : {});
+    return `${String(r.timestamp ?? '')}\u0000${String(r.note ?? JSON.stringify(n))}`;
+}
+const recoveryWrites = new WeakMap();
+const RecoveryReceiptShape = z.object({
+    task: z.literal('T12727'),
+    id: z.string(),
+    recoveredAt: z.string(),
+    snapshot: z.string().nullable(),
+    archived: z.array(z.object({ key: z.string(), archiveKey: z.string(), sha: z.string() })),
+    focusNotesAdded: z.number(),
+    stickyArchived: z.array(z.string()),
+    stickyArchiveKey: z.string(),
+    before: z.object({ focusState: z.string().nullable(), stickyArchive: z.string().nullable() }),
+    after: z.object({ focusState: z.string().nullable(), stickyArchive: z.string().nullable() }),
+    rolledBackAt: z.string().nullable(),
+});
+/** Parsed receipt rows, by key. */
+function recoveryReceipts(live) {
+    const out = new Map();
+    for (const [key, value] of kvRows(live, 'tasks_schema_meta')) {
+        if (!key.startsWith(TWIN_COLLAPSE_RECOVERY_PREFIX))
+            continue;
+        const parsed = RecoveryReceiptShape.safeParse(parseJson(value));
+        if (parsed.success)
+            out.set(key, parsed.data);
+    }
+    return out;
+}
+/** Tag sets of a sticky junction; empty when the table is absent. */
+function stickySetsIfPresent(db, table) {
+    return hasMainTable(db, table) ? stickySets(db, table) : new Map();
+}
+/**
+ * Plan the recovery of the twin values a 2026.9.21 collapse dropped or
+ * replaced, from the pre-collapse snapshot its marker records (T12727).
+ *
+ * The 9.21 initial collapse was bare-authoritative: it deleted keys and
+ * sticky tags only the twin held and overwrote twin values with the bare
+ * ones, keeping them only in that snapshot. This compares the snapshot's
+ * twin and bare tables (read-only; a pair whose table the snapshot lacks is
+ * skipped) and plans, for every twin value that is not live and not archived:
+ * - `schema_meta`: the twin value is written to `twin_collapse_archive:<key>`
+ *   (a suffixed key when that name already holds another value, so nothing is
+ *   overwritten); for `focus_state` the twin's session notes are also merged
+ *   into the live value ({@link mergeFocusState}: live current fields win,
+ *   notes deduplicated by `(timestamp, note)` and sorted);
+ * - `sticky_tags`: twin-only tags are added to
+ *   `twin_collapse_archive:sticky_tags` in `brain_schema_meta` (a suffixed key
+ *   when that row is not a list of tags).
+ * The notes are merged once: not again after an apply that was not rolled
+ * back, nor when the twin value is already archived, so notes pruned after a
+ * recovery stay pruned. A second apply plans nothing.
+ *
+ * @param live - The project `cleo.db` connection (read-only is enough).
+ * @param snapshot - The snapshot, opened read-only, or `null` when missing.
+ * @returns The plan.
+ * @task T12727
+ */
+export function planTwinCollapseRecovery(live, snapshot, options = {}) {
+    const state = readState(live, SCHEMA_META);
+    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)
+        .map(([k]) => k)
+        .sort();
+    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;
+    // A pair whose bare or twin table the snapshot lacks had nothing to collapse.
+    const kvPair = hasMainTable(snapshot, 'schema_meta') && hasMainTable(snapshot, 'tasks_schema_meta');
+    const sBare = kvPair ? carriedRows(snapshot, 'schema_meta') : new Map();
+    const sTwin = kvPair ? carriedRows(snapshot, 'tasks_schema_meta') : new Map();
+    const kv = new Map();
+    const archive = [];
+    const archivedValues = new Set([...liveKv].filter(([k]) => k.startsWith(TWIN_COLLAPSE_ARCHIVE_PREFIX)).map(([, v]) => v));
+    const focusBefore = liveKv.get('focus_state') ?? null;
+    let focusState = null;
+    let focusNotesAdded = 0;
+    for (const [key, twinValue] of [...sTwin].sort(([a], [b]) => a.localeCompare(b))) {
+        if (sBare.get(key) === twinValue)
+            continue; // not replaced
+        const reason = sBare.has(key) ? 'replaced' : 'dropped';
+        const done = liveKv.get(key) === twinValue || archivedValues.has(twinValue);
+        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)
+            continue;
+        let archiveKey = `${TWIN_COLLAPSE_ARCHIVE_PREFIX}${key}`;
+        if (liveKv.has(archiveKey))
+            archiveKey = `${archiveKey}:${sha(twinValue).slice(0, 8)}`;
+        kv.set(archiveKey, twinValue);
+        archive.push({ key, archiveKey, reason, length: twinValue.length });
+    }
+    // Sticky tags only the twin junction held in the snapshot.
+    const stickyPair = hasMainTable(snapshot, 'sticky_tags') && hasMainTable(snapshot, 'brain_sticky_tags');
+    const sb = stickyPair ? stickySets(snapshot, 'sticky_tags') : new Map();
+    const st = stickyPair ? stickySets(snapshot, 'brain_sticky_tags') : new Map();
+    const liveTags = stickySetsIfPresent(live, 'brain_sticky_tags');
+    const stickyRaw = hasMainTable(live, 'brain_schema_meta')
+        ? readKv(live, 'brain_schema_meta', STICKY_ARCHIVE_KEY)
+        : undefined;
+    const stickyParsed = StickyArchiveShape.safeParse(parseJson(stickyRaw ?? '[]'));
+    // A row that is not a list of tags is someone's data: never overwrite it.
+    const stickyArchiveKey = stickyParsed.success
+        ? STICKY_ARCHIVE_KEY
+        : `${STICKY_ARCHIVE_KEY}:${sha(stickyRaw ?? '').slice(0, 8)}`;
+    const previousRaw = stickyParsed.success
+        ? stickyRaw
+        : readKv(live, 'brain_schema_meta', stickyArchiveKey);
+    const previous = StickyArchiveShape.safeParse(parseJson(previousRaw ?? '[]'));
+    const archivedTags = new Set(previous.success ? previous.data : []);
+    const stickyArchived = [];
+    for (const [id, tags] of st) {
+        const bare = new Set(sb.get(id) ?? []);
+        const now = new Set(liveTags.get(id) ?? []);
+        for (const tag of tags) {
+            const row = `${id}\t${tag}`;
+            if (bare.has(tag) || now.has(tag) || archivedTags.has(row))
+                continue;
+            stickyArchived.push(row);
+        }
+    }
+    stickyArchived.sort();
+    const stickyArchive = stickyArchived.length > 0
+        ? JSON.stringify([...new Set([...archivedTags, ...stickyArchived])].sort())
+        : null;
+    const plan = {
+        ...empty,
+        archive,
+        focusNotesAdded,
+        stickyArchived,
+        stickyArchiveKey,
+        changes: kv.size > 0 || focusState !== null || stickyArchive !== null,
+    };
+    recoveryWrites.set(plan, {
+        snapshot,
+        options,
+        kv,
+        focusBefore,
+        focusState,
+        stickyBefore: previousRaw ?? null,
+        stickyArchive,
+    });
+    return plan;
+}
+/**
+ * Apply a recovery in one `BEGIN IMMEDIATE` transaction on the live store.
+ *
+ * The plan is recomputed INSIDE the transaction from the live values read
+ * under the write lock, so a note written after `plan` was built is merged,
+ * never lost; `plan` is the preview the caller showed. Writes the archive
+ * keys, the merged `focus_state`, the sticky archive, and a new receipt.
+ * Nothing is written when there is nothing to recover. Never touches the
+ * snapshot.
+ *
+ * @param live - The project `cleo.db` connection, outside a transaction.
+ * @param plan - From {@link planTwinCollapseRecovery} on the same connection.
+ * @returns The plan applied and its receipt (`null` when nothing was written).
+ * @throws {CleoError} {@link E_TWIN_COLLAPSE_RECOVER} when the recorded
+ *   snapshot is missing (nothing is written).
+ * @task T12727
+ */
+export function applyTwinCollapseRecovery(live, plan, onRepoint) {
+    if (plan.snapshot === 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, 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) {
+            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}`;
+        for (let n = 2; readKv(live, 'tasks_schema_meta', id) !== undefined; n++)
+            id = `${TWIN_COLLAPSE_RECOVERY_PREFIX}${recoveredAt}:${n}`;
+        const receipt = {
+            task: 'T12727',
+            id,
+            recoveredAt,
+            snapshot: fresh.snapshot,
+            archived: fresh.archive.map((a) => ({
+                key: a.key,
+                archiveKey: a.archiveKey,
+                sha: sha(writes.kv.get(a.archiveKey) ?? ''),
+            })),
+            focusNotesAdded: fresh.focusNotesAdded,
+            stickyArchived: [...fresh.stickyArchived],
+            stickyArchiveKey: fresh.stickyArchiveKey,
+            before: {
+                focusState: writes.focusState === null ? null : writes.focusBefore,
+                stickyArchive: writes.stickyArchive === null ? null : writes.stickyBefore,
+            },
+            after: {
+                focusState: writes.focusState === null ? null : sha(writes.focusState),
+                stickyArchive: writes.stickyArchive === null ? null : sha(writes.stickyArchive),
+            },
+            rolledBackAt: null,
+        };
+        for (const [key, value] of writes.kv)
+            writeKv(live, 'tasks_schema_meta', key, value);
+        if (writes.focusState !== null)
+            writeKv(live, 'tasks_schema_meta', 'focus_state', writes.focusState);
+        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, repointed };
+    }
+    catch (error) {
+        if (live.isTransaction)
+            live.exec('ROLLBACK');
+        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`, {
+        fix: 'Restore that file from a backup of .cleo/backups/sqlite/ and re-run; without it there is nothing to recover from.',
+        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:
+ * - archive keys it wrote are deleted when they still hold that value;
+ * - `focus_state` is restored to its pre-merge value when unchanged since,
+ *   else only the notes the recovery added are removed (notes written since
+ *   stay);
+ * - the sticky archive is restored when unchanged since, else only the rows
+ *   the recovery added are removed;
+ * - the receipt is kept, stamped `rolledBackAt`.
+ *
+ * @param live - The project `cleo.db` connection, outside a transaction.
+ * @param id - The receipt key (`twin_collapse_recovery:<recoveredAt>`).
+ * @returns What was undone.
+ * @throws {CleoError} {@link E_TWIN_COLLAPSE_RECOVER} when the receipt is
+ *   unknown or already rolled back (nothing is written).
+ * @task T12727
+ */
+export function rollbackTwinCollapseRecovery(live, id) {
+    live.exec('BEGIN IMMEDIATE');
+    try {
+        const receipt = recoveryReceipts(live).get(id);
+        if (receipt === undefined || receipt.rolledBackAt !== null)
+            throw new CleoError(ExitCode.NOT_FOUND, `${E_TWIN_COLLAPSE_RECOVER}: ${receipt === undefined ? 'no recovery receipt' : 'already rolled back:'} ${id}; nothing was changed`, {
+                fix: 'cleo doctor twin-collapse --recover --dry-run  # lists the receipts not rolled back',
+            });
+        const archiveDeleted = [];
+        const archiveKept = [];
+        let addedNotes = new Set();
+        for (const a of receipt.archived) {
+            const value = readKv(live, 'tasks_schema_meta', a.archiveKey);
+            if (value === undefined || sha(value) !== a.sha) {
+                archiveKept.push(a.archiveKey);
+                continue;
+            }
+            if (a.key === 'focus_state') {
+                const before = new Set(sessionNotesOf(receipt.before.focusState ?? undefined).map(noteKey));
+                addedNotes = new Set(sessionNotesOf(value)
+                    .map(noteKey)
+                    .filter((k) => !before.has(k)));
+            }
+            live.prepare('DELETE FROM main.tasks_schema_meta WHERE key = ?').run(a.archiveKey);
+            archiveDeleted.push(a.archiveKey);
+        }
+        let focusState = 'none';
+        let notesRemoved = 0;
+        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 ?? 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) {
+                const parsed = FocusNotesShape.safeParse(parseJson(current));
+                if (parsed.success) {
+                    const kept = parsed.data.sessionNotes.filter((n) => !addedNotes.has(noteKey(n)));
+                    notesRemoved = parsed.data.sessionNotes.length - kept.length;
+                    if (notesRemoved > 0)
+                        writeKv(live, 'tasks_schema_meta', 'focus_state', JSON.stringify({ ...parsed.data, sessionNotes: kept }));
+                    focusState = 'notes-removed';
+                }
+            }
+        }
+        let stickyRemoved = 0;
+        if (receipt.after.stickyArchive !== null) {
+            const current = readKv(live, 'brain_schema_meta', receipt.stickyArchiveKey);
+            if (current !== undefined && sha(current) === receipt.after.stickyArchive) {
+                stickyRemoved = receipt.stickyArchived.length;
+                if (receipt.before.stickyArchive === null)
+                    live
+                        .prepare('DELETE FROM main.brain_schema_meta WHERE key = ?')
+                        .run(receipt.stickyArchiveKey);
+                else
+                    writeKv(live, 'brain_schema_meta', receipt.stickyArchiveKey, receipt.before.stickyArchive);
+            }
+            else if (current !== undefined) {
+                const parsed = StickyArchiveShape.safeParse(parseJson(current));
+                if (parsed.success) {
+                    const added = new Set(receipt.stickyArchived);
+                    const kept = parsed.data.filter((r) => !added.has(r));
+                    stickyRemoved = parsed.data.length - kept.length;
+                    writeKv(live, 'brain_schema_meta', receipt.stickyArchiveKey, JSON.stringify(kept));
+                }
+            }
+        }
+        writeKv(live, 'tasks_schema_meta', id, JSON.stringify({ ...receipt, rolledBackAt: new Date().toISOString() }));
+        live.exec('COMMIT');
+        return { id, archiveDeleted, archiveKept, focusState, notesRemoved, stickyRemoved };
+    }
+    catch (error) {
+        if (live.isTransaction)
+            live.exec('ROLLBACK');
+        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