@cleocode/core 2026.10.1 → 2026.10.2

package/dist/store/sync/capture.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Capture: persistent pure-SQL triggers that record every change to a
+ * sync-set row into `_sync_capture`, in the writing statement (journal spec
+ * §2.3; S2, `sync.capture`; T12343 AC1 / R4).
+ *
+ * Per sync-set table the generator emits up to five AFTER triggers, all
+ * carrying the `capture` suspension clause (§3.5 Rule 4):
+ *
+ * | Trigger | Fires on | Records |
+ * |---|---|---|
+ * | `_sync_cap_<t>_i` | INSERT | full image; identity read from the LIVE row (N4) |
+ * | `_sync_cap_<t>_u` | UPDATE OF captured columns, when one changed | changed columns `[old, new]` |
+ * | `_sync_cap_<t>_d` | DELETE | full before-image |
+ * | `_sync_cap_<t>_k` | UPDATE OF uid / birth_fp of a keyed row | the re-key (H5) |
+ * | `_sync_cap_<t>_f` | UPDATE OF uid / birth_fp from NULL | patches the latest live I capture (N4, N11) |
+ *
+ * - Values are `enc()`-encoded before any JSON function sees them (`quote()`,
+ *   and `'r' || printf('%!.17g')` for REAL: `-0.0` becomes `0.0`, ±Inf is
+ *   `Inf` / `-Inf`, L4).
+ * - A reference column records `[enc(local key), target uid]`, the uid read at
+ *   write time (H5). JSON-array references are translated at seal time.
+ * - A secret column records only the `<changed>` marker, never its value
+ *   (§2.7); before-images never hold secret values. `strip` columns are
+ *   captured whole and stripped at seal. Local-only columns (claim leases)
+ *   and identity columns never fire an update capture.
+ * - Full images are chunked `json_patch(json_object(≤60 pairs), …)` (L3); the
+ *   update image uses a `UNION ALL` of per-column terms (no argument limit).
+ * - Each trigger also writes `_sync_undo` for the same seq, but only while
+ *   `_sync_meta.undo_enabled` exists (push on, §3.5 Rule 2); S2 runs with it
+ *   off (shadow mode). Append-only tables keep only `rk` and `uid` there.
+ *   An update's undo holds only the changed columns, old and new (D5
+ *   amendment); a delete's holds the full row.
+ * - I and D images omit NULL columns: the sender's column set is pinned by
+ *   its trigger set, so an absent column is NULL.
+ *
+ * The open pass installs the triggers only to match the persisted
+ * `sync.capture` flag ({@link syncCaptureOpenPass}); the kill switch
+ * `CLEO_SYNC_CAPTURE=0` never touches them (M3). `accessor.transaction()`
+ * opens a frame ({@link openCaptureFrame}); finishing it labels the frame's
+ * captures with the connection, frame and kind in one UPDATE
+ * ({@link finishCaptureFrame}).
+ *
+ * @task T12343
+ * @module store/sync/capture
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { TableScope } from '@cleocode/contracts';
+/** How one table is captured. Built from the registries, or by tests. */
+export interface CaptureTableDef {
+    readonly table: string;
+    /** Local key columns (the table's single-row identity on this device). */
+    readonly key: readonly string[];
+    /** Captured columns, in table order: every column except local-only ones. */
+    readonly columns: readonly string[];
+    /** Identity columns (recorded, read from the live row on insert; never fire U). */
+    readonly identity: readonly string[];
+    /** Secret columns: recorded as `<changed>` only. */
+    readonly secret: ReadonlySet<string>;
+    /** Reference columns: target table and its local key column. */
+    readonly refs: ReadonlyMap<string, {
+        table: string;
+        key: string;
+    }>;
+    /** Rows never change: undo keeps only `rk` and `uid`. */
+    readonly appendOnly: boolean;
+}
+/** One generated trigger. */
+export interface CaptureTrigger {
+    readonly name: string;
+    readonly table: string;
+    readonly sql: string;
+    /** Every table the trigger's text references (SYNC_TRIGGER_REFS, N3). */
+    readonly refs: readonly string[];
+}
+/** Largest number of key/value pairs per `json_object` call (L3). */
+export declare const JSON_OBJECT_CHUNK = 60;
+/** The marker a secret column records instead of its value (§2.7). */
+export declare const SECRET_MARKER = "<changed>";
+/** `enc(v)`: lossless text for any SQLite value (§2.3). */
+export declare function enc(expr: string): string;
+/** Wall milliseconds from SQLite's clock, valid on every shipped SQLite (§1.2). */
+export declare const AT_MS_SQL = "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)";
+/** The sync set: portable, not frozen-legacy, declared in ROW_IDENTITY (§2.1). */
+export declare function syncSetTables(scope: TableScope): string[];
+/**
+ * The capture definition of a sync-set table in this store, or `undefined`
+ * when the table is absent or not in the sync set.
+ */
+export declare function captureTableDef(db: DatabaseSync, scope: TableScope, table: string): CaptureTableDef | undefined;
+/** `json_patch(json_object(≤60 pairs), …)` over `pairs` (L3). */
+export declare function chunkedObject(pairs: ReadonlyArray<readonly [string, string]>): string;
+/**
+ * Generate every capture trigger for one table. Pure: the same definition
+ * always yields the same text, so the open pass can compare live text.
+ */
+export declare function captureTriggers(def: CaptureTableDef): CaptureTrigger[];
+/**
+ * Re-mint captures (T12806 × S2): a captured write that CLEARED a row's
+ * identity (a snapshot-overwrite import: K old → NULL) is followed by a fill
+ * that mints the new uid outside capture (the open-time fill runs with the
+ * capture triggers dropped). For every such row, write the K that journals
+ * the new identity (NULL → new uid, and birth_fp), so the pair nets to
+ * old → new. Call inside the fill's bracket, after the fill.
+ *
+ * A row qualifies when its latest live K capture set the uid to NULL and the
+ * row now has a uid. Undo is written only while `undo_enabled` (Rule 2).
+ *
+ * @returns K captures written, per table.
+ */
+export declare function captureRemints(db: DatabaseSync, scope: TableScope): Record<string, number>;
+/** Every capture trigger for the store's sync set. */
+export declare function generateCaptureTriggers(db: DatabaseSync, scope: TableScope): CaptureTrigger[];
+/** SYNC_TRIGGER_REFS: trigger → every table its text references (N3). */
+export declare function syncTriggerRefs(db: DatabaseSync, scope: TableScope): Map<string, readonly string[]>;
+/** What {@link installCaptureTriggers} changed. */
+export interface CaptureInstallReport {
+    readonly installed: string[];
+    readonly replaced: string[];
+    readonly dropped: string[];
+}
+/**
+ * Make the live capture triggers exactly the generated set: create the
+ * missing, replace the differing, drop the orphaned. Writes nothing when
+ * they already match. Requires the sync schema.
+ */
+export declare function installCaptureTriggers(db: DatabaseSync, scope: TableScope): CaptureInstallReport;
+/** Drop every capture trigger. Returns their names. */
+export declare function dropCaptureTriggers(db: DatabaseSync): string[];
+/**
+ * Install the provenance stamp on a chokepoint connection (§2.3). A
+ * persistent trigger cannot read a TEMP table, so the capture triggers write
+ * rows unlabelled; the labels (connection, frame, kind) are written ONCE per
+ * frame by {@link finishCaptureFrame}, over the frame's seq range. Writes are
+ * serialized by the write lock, so every capture from the frame's
+ * `first_seq` on belongs to it. This replaces a TEMP trigger that ran one
+ * UPDATE per capture (S2 insert-path ruling (a)). Also turns
+ * `recursive_triggers` on for this connection (M1; the REPLACE audit is
+ * T12787's zero-tolerance ban plus `recursive-triggers-audit.test.ts`).
+ *
+ * @returns This connection's id.
+ */
+export declare function installCaptureStamp(db: DatabaseSync): string;
+/** Remove the stamp (capture turned off, or the sync tables dropped). */
+export declare function removeCaptureStamp(db: DatabaseSync): void;
+/** Whether this connection carries the capture stamp. */
+export declare function hasCaptureStamp(db: DatabaseSync): boolean;
+/** The kinds a frame can have (§2.3). */
+export type FrameKind = 'write' | 'apply' | 'rebase' | 'repair' | 'exodus' | 'import' | 'remint' | 'rekey';
+/**
+ * Open a frame for the caller's transaction, right after its
+ * `BEGIN IMMEDIATE`: insert the `_sync_frame` row with the first seq its
+ * captures can take. A connection without the stamp (capture off) gets
+ * `null` and nothing is written.
+ */
+export declare function openCaptureFrame(db: DatabaseSync, kind?: FrameKind, actor?: string | null): string | null;
+/**
+ * Before COMMIT: label the frame's captures and undo rows (one UPDATE each
+ * over its seq range), drop the undo of an `apply` / `rebase` frame (D1), and
+ * delete the frame's row when no capture carries it, so a read-only
+ * transaction leaves nothing (N10). A transaction that commits without this
+ * call leaves its captures unframed, never mislabelled.
+ */
+export declare function finishCaptureFrame(db: DatabaseSync, frame: string | null): void;
+/**
+ * In `finally`: nothing is left to clear (the labels are written by
+ * {@link finishCaptureFrame}); kept so callers need not change.
+ */
+export declare function clearCaptureFrame(_db: DatabaseSync, _frame: string | null): void;
+/**
+ * `cleo sync capture on|off` (the storage primitive): persist the flag and
+ * install or drop the triggers, in one transaction.
+ */
+export declare function setCaptureEnabled(db: DatabaseSync, scope: TableScope, on: boolean, options?: {
+    schemaRoot?: string;
+}): CaptureInstallReport | {
+    dropped: string[];
+};
+/** What the capture open pass did. */
+export type CaptureOpenResult = {
+    readonly capture: 'off';
+    readonly dropped: string[];
+} | {
+    readonly capture: 'on';
+    readonly report: CaptureInstallReport;
+    readonly conn: string;
+};
+/**
+ * The capture step of the open pass, after migrations: triggers match the
+ * persisted flag. With the flag off and no trigger present it only reads.
+ */
+export declare function syncCaptureOpenPass(db: DatabaseSync, scope: TableScope, options?: {
+    schemaRoot?: string;
+}): CaptureOpenResult;
+/**
+ * Migration-runner hooks (§2.3a rules 1 and 5): drop every capture trigger
+ * inside the bracket before a migration's statements, and regenerate them for
+ * the new schema before its COMMIT. Only when capture is on.
+ */
+export declare function captureBracketHooks(db: DatabaseSync, scope: TableScope): {
+    suspendCapture?(db: DatabaseSync): void;
+    reinstallCapture?(db: DatabaseSync): void;
+};
+//# sourceMappingURL=capture.d.ts.map

package/dist/store/sync/capture.d.ts.map

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