@cleocode/core 2026.9.19 → 2026.9.21

package/dist/store/twin-collapse.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Twin collapses (T12535): keep a prefixed twin in step with its BARE legacy
+ * table, which stays authoritative while an older CLEO build still writes it.
+ *
+ * ## Why
+ *
+ * The project `cleo.db` carries legacy bare tables beside their prefixed (E6)
+ * twins. For `schema_meta` and `sticky_tags` the runtime wrote the bare table
+ * while the twin held a frozen exodus copy. This build reads and writes only
+ * the twin. The release before it (2026.9.20) is still installed on machines
+ * that share project stores and keeps writing the bare tables, so the collapse
+ * runs at every open:
+ *
+ * - **Initial collapse** (no marker yet): check the free space, snapshot the
+ *   store, then fold the bare table into the twin, bare-authoritative.
+ * - **Incremental re-merge** (marker present): carry over only the bare keys
+ *   (sticky ids) whose hash changed since the last merge. No snapshot. An
+ *   unchanged bare table costs one read of it and no write.
+ *
+ * A later release removes the incremental re-merge once no supported build
+ * writes the bare tables; slice 3 then drops them after a backup.
+ *
+ * ## State and provenance
+ *
+ * The marker row `twin_collapse:<bare table>` in the twin's key/value table
+ * holds, per key (`schema_meta`) or per sticky id (`sticky_tags`), a sha256
+ * of the BARE value and of the TWIN value as of the last merge. A bare hash
+ * that moved means the older build wrote it; a twin hash that moved means this
+ * build wrote it.
+ *
+ * ## Rules
+ *
+ * The bare row is authoritative for every key. A monotonic counter FIELD is
+ * merged on its own: the result is the bare value with that field set to
+ * max(bare, twin). A whole twin value never replaces a bare one
+ * ({@link mergeSchemaMetaValue}).
+ *
+ * | `schema_meta` key | Counter field |
+ * |---|---|
+ * | `task_id_sequence` (`{counter,lastId,checksum}` from `sequence/index.ts`, or a plain number) | `counter` (a plain number takes the max of the two numbers) |
+ * | `sqlite_snapshot_gate` (`{generation,prefixes}`, `snapshot-gate.ts`) | `generation` |
+ * | `file_meta` (`FileMeta`; `session/engine-ops.ts` bumps `generation` on session start/end/resume) | `generation` |
+ * | `backfill:*` (the two `t877` guard keys) | not carried: the lineage re-inserts them into every bare table and nothing reads them |
+ * | `twin_collapse*` | not carried: collapse state and failures live only in the twin |
+ * | 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.
+ * - **Incremental re-merge**, per bare key whose hash changed since the last
+ *   merge:
+ *   - twin unchanged since the last merge → the bare value (counter fields
+ *     maxed);
+ *   - twin ALSO changed (this build wrote it too) → CONFLICT: the TWIN value
+ *     wins, recorded in the marker and reported by `cleo doctor` as a warning.
+ *     A counter key is never a conflict: the twin value is kept with its
+ *     counter field maxed against the bare one.
+ *   A key the older build deleted is deleted from the twin unless the twin
+ *   changed it too (conflict) or it is `task_id_sequence` /
+ *   `sqlite_snapshot_gate`. A key the bare table never changed is never
+ *   touched.
+ *
+ * `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).
+ * - 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);
+ *   if the twin set changed too, the twin wins and a conflict is recorded.
+ *
+ * ## 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).
+ * 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.
+ * 3. **Verified.** Every row the merge decided is re-read and compared before
+ *    the marker is written; a mismatch rolls back.
+ * 4. **The bare table is never written.**
+ * 5. **Never locked out** (inside a domain bind, `onFailure: 'degrade'`). A
+ *    failed or impossible collapse does not fail the bind. The failure is
+ *    recorded (`twin_collapse_failed:<table>`), and the connection is put in a
+ *    READ-ONLY-FOR-USERS mode: the merged view the collapse would have
+ *    committed is computed in memory and served from TEMP shadow tables of the
+ *    same names (unqualified SQL resolves `temp` before `main`), so reads see
+ *    bare-authoritative data while `main` stays untouched. Mutating operations
+ *    are refused with `E_TWIN_COLLAPSE_FAILED` by the dispatch write guard
+ *    ({@link twinCollapseFailureOf}), and the shadows carry TEMP triggers that
+ *    abort any write into them ({@link SHADOW_WRITE_REFUSED}), so a direct SDK
+ *    write fails instead of being lost. `cleo doctor twin-collapse --retry`
+ *    runs the collapse with `onFailure: 'throw'`; on success the shadows and
+ *    their triggers are dropped.
+ *
+ * ## Gate 28
+ *
+ * This module is a sanctioned writer (`scripts/lint-no-raw-table-writes.mjs`
+ * SANCTIONED): it runs on the chokepoint handle inside the domain bind, and the
+ * accessors import the modules that call it.
+ *
+ * @module
+ * @task T12535
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import { CleoError } from '../errors.js';
+/** Prefix of the marker key holding a pair's collapse state. */
+export declare const TWIN_COLLAPSE_MARKER_PREFIX = "twin_collapse:";
+/** Prefix of the key recording a pair's last failed collapse. */
+export declare const TWIN_COLLAPSE_FAILURE_PREFIX = "twin_collapse_failed:";
+/** `schema_meta` keys whose named field is a monotonic counter (merged as max). */
+export declare const SCHEMA_META_COUNTER_FIELDS: Readonly<Record<string, string>>;
+/** `schema_meta` keys never deleted from the twin (a counter never moves back). */
+export declare const SCHEMA_META_NEVER_DELETED: ReadonlySet<string>;
+/** What one call did to one pair. */
+export interface TwinCollapseReceipt {
+    /** The bare legacy table. */
+    readonly table: string;
+    /** The prefixed twin. */
+    readonly twin: string;
+    /**
+     * `initial`: the first collapse ran. `incremental`: bare changes since the
+     * last merge were carried. `unchanged`: the bare table matched the stored
+     * hashes. `degraded`: the collapse failed inside a bind; reads are served
+     * from TEMP shadows and writes are refused. `no-bare-table`: a table of the
+     * pair is missing.
+     */
+    readonly status: 'initial' | 'incremental' | 'unchanged' | 'degraded' | 'no-bare-table';
+    /** The initial collapse's snapshot, or `null`. */
+    readonly snapshotPath: string | null;
+    /** Rows added to the twin. */
+    readonly inserted: number;
+    /** Twin rows whose value was replaced. */
+    readonly replaced: number;
+    /** Twin rows deleted (bare deletions, frozen rows dropped initially). */
+    readonly deleted: number;
+    /** Bare rows not carried by rule (dead keys, tags of deleted notes). */
+    readonly skipped: number;
+    /** Frozen twin rows the initial collapse dropped (keys, or `sticky_id\ttag`). */
+    readonly dropped: readonly string[];
+    /** Keys (or sticky ids) both builds changed since the last merge; the twin was kept. */
+    readonly conflicts: readonly string[];
+}
+/**
+ * The value a `schema_meta` key gets when the bare side is authoritative (the
+ * rule table is in the module comment).
+ *
+ * @param key - The key.
+ * @param bare - Its value in the bare table.
+ * @param twin - Its value in the twin, or `undefined` when absent.
+ * @returns The value to keep, or `null` when the key is not carried.
+ * @task T12535
+ */
+export declare function mergeSchemaMetaValue(key: string, bare: string, twin: string | undefined): string | null;
+/** Why a collapse failed, as carried by `E_TWIN_COLLAPSE_FAILED`. */
+export interface TwinCollapseFailure {
+    /** The bare tables whose collapse did not complete. */
+    readonly tables: readonly string[];
+    /** The underlying error message. */
+    readonly cause: string;
+    /** The snapshot this collapse needs (the planned path) or wrote, or `null`. */
+    readonly snapshotPath: string | null;
+    /** Whether {@link snapshotPath} was written (`false`: only planned). */
+    readonly snapshotWritten: boolean;
+    /** Free space the snapshot needs, in bytes (0 when none was needed). */
+    readonly requiredBytes: number;
+    /** Free space measured on the backup filesystem, or `null`. */
+    readonly availableBytes: number | null;
+    /** When it failed (ISO-8601). */
+    readonly failedAt: string;
+}
+/**
+ * The failure a connection is degraded by, if any: reads on it are served from
+ * TEMP shadows and writes must be refused (the dispatch write guard does).
+ *
+ * @param db - A project `cleo.db` connection.
+ * @returns The failure, or `undefined` when the store is fully collapsed.
+ * @task T12535
+ */
+export declare function twinCollapseFailureOf(db: DatabaseSync): TwinCollapseFailure | undefined;
+/**
+ * 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.
+ * @task T12535
+ */
+export declare function assertTwinCollapseWritable(handle: unknown): void;
+/**
+ * Build the `E_TWIN_COLLAPSE_FAILED` error for a failure.
+ *
+ * @param failure - The failure.
+ * @param cause - The underlying error, when there is one.
+ * @returns The error.
+ * @task T12535
+ */
+export declare function twinCollapseError(failure: TwinCollapseFailure, cause?: unknown): CleoError;
+/** Message a write into a sealed shadow aborts with. */
+export declare const SHADOW_WRITE_REFUSED = "E_TWIN_COLLAPSE_FAILED: store is read-only until the twin collapse succeeds; run cleo doctor twin-collapse";
+/** Options for {@link collapseTwinTables}. */
+export interface CollapseTwinTablesOptions {
+    /**
+     * `throw` (default): raise `E_TWIN_COLLAPSE_FAILED`. `degrade` (the domain
+     * binds): record the failure, serve reads from TEMP shadows, and let the
+     * dispatch write guard refuse writes.
+     */
+    readonly onFailure?: 'throw' | 'degrade';
+}
+/**
+ * Collapse every bare/twin pair present in the store: the initial collapse
+ * (snapshot first) where no marker exists yet, an incremental re-merge of
+ * changed bare keys where one does.
+ *
+ * @param nativeDb - The project `cleo.db` connection, outside any transaction.
+ * @param dbPath - Its file path (locates `.cleo/backups/sqlite/`).
+ * @param options - Failure handling.
+ * @returns One receipt per pair.
+ * @throws {CleoError} `E_TWIN_COLLAPSE_FAILED` with `onFailure: 'throw'`.
+ * @task T12535
+ */
+export declare function collapseTwinTables(nativeDb: DatabaseSync, dbPath: string, options?: CollapseTwinTablesOptions): TwinCollapseReceipt[];
+/** Read-only status of one pair, for `cleo doctor`. */
+export interface TwinCollapseStatus {
+    /** The bare legacy table. */
+    readonly table: string;
+    /** The prefixed twin. */
+    readonly twin: string;
+    /**
+     * `collapsed`: marker present, bare side unchanged since the last merge.
+     * `bare-changed`: the older build changed the bare side since; the next
+     * open carries it. `pending`: no marker; the initial collapse runs at the
+     * next open. `failed`: the last attempt failed (see `failure`); reads are
+     * served, writes refused. `no-bare-table`: nothing to collapse.
+     */
+    readonly state: 'collapsed' | 'bare-changed' | 'pending' | 'failed' | 'no-bare-table';
+    /** Whether a pending initial collapse would change the twin (and so needs a snapshot). */
+    readonly wouldChangeTwin: boolean;
+    /** The initial collapse's snapshot (or the planned one of a failed attempt). */
+    readonly snapshotPath: string | null;
+    /** When the initial collapse ran. */
+    readonly collapsedAt: string | null;
+    /** When the last merge ran. */
+    readonly lastMergedAt: string | null;
+    /** Keys (schema_meta) or sticky ids (sticky_tags) the bare side changed since the last merge. */
+    readonly changedSinceMerge: number;
+    /** Keys / sticky ids both builds changed in the last merge (the twin was kept). */
+    readonly conflicts: readonly string[];
+    /** When those conflicts were recorded. */
+    readonly conflictsAt: string | null;
+    /** The recorded failure, when the last attempt failed. */
+    readonly failure: TwinCollapseFailure | null;
+}
+/**
+ * Report every pair's collapse state without writing (for `cleo doctor`).
+ *
+ * @param db - A connection on the project `cleo.db`; read-only is enough.
+ * @returns One status per pair.
+ * @task T12535
+ */
+export declare function inspectTwinCollapse(db: DatabaseSync): TwinCollapseStatus[];
+//# sourceMappingURL=twin-collapse.d.ts.map

package/dist/store/twin-collapse.d.ts.map

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