@cleocode/core 2026.10.1 → 2026.10.3

package/dist/store/sync/timestamps.js

@@ -0,0 +1,228 @@
+/**
+ * Uniform timestamp format (journal spec §1.8, R3, M4; T12986, S3c).
+ *
+ * - {@link canonicalStoreTimestamp}: the strict, pure canonicalizer. Accepts
+ *   ISO-8601 with `Z` or an explicit `±hh:mm` offset (any fractional
+ *   precision) and SQLite's `YYYY-MM-DD HH:MM:SS[.fff]` UTC form; refuses
+ *   zoneless `T` forms, date-only values and anything else.
+ * - {@link SYNC_TIMESTAMP_COLUMNS}: the captured timestamp columns per table.
+ * - {@link canonicalizeStoreTimestamps}: the one-time rewrite under the
+ *   `timestamp_canon_v1` marker, run before the capture triggers go in. It
+ *   never touches `tasks_tasks.updated_at` (the #1698 CAS token) and is
+ *   refused once `row_identity_synced` exists.
+ *
+ * After genesis the sealer canonicalizes on the wire only; local rows are
+ * never rewritten there.
+ *
+ * @module store/sync/timestamps
+ * @task T12986
+ * @epic T12323
+ */
+import { ROW_IDENTITY_META_TABLE, ROW_IDENTITY_SYNCED_KEY } from '../row-identity.js';
+import { withImmediateTransaction } from './clock-store.js';
+import { hasTable } from './schema.js';
+import { hasTriggerSuspendTable, withTriggersSuspended } from './trigger-classes.js';
+// ---------------------------------------------------------------------------
+// The canonicalizer
+// ---------------------------------------------------------------------------
+const ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})$/;
+const SQLITE = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?$/;
+function daysIn(year, month) {
+    if (month === 2)
+        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28;
+    return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+/**
+ * The canonical wire form of a stored timestamp,
+ * `YYYY-MM-DDTHH:MM:SS.sssZ`, or `null` when the value is refused.
+ *
+ * Fractions beyond milliseconds are truncated, never rounded, so a carry can
+ * never change the second. Pure: two replicas always agree.
+ *
+ * @example
+ * ```ts
+ * canonicalStoreTimestamp('2026-09-14 19:56:01');          // '2026-09-14T19:56:01.000Z'
+ * canonicalStoreTimestamp('2026-09-14T21:56:01.5+02:00');  // '2026-09-14T19:56:01.500Z'
+ * canonicalStoreTimestamp('2026-09-14T19:56:01');          // null (zoneless)
+ * canonicalStoreTimestamp('2026-09-14');                   // null (date only)
+ * ```
+ */
+export function canonicalStoreTimestamp(value) {
+    const m = ISO.exec(value) ?? SQLITE.exec(value);
+    if (!m)
+        return null;
+    const [y, mo, d, h, mi, s] = m.slice(1, 7).map(Number);
+    if (mo < 1 || mo > 12 || d < 1 || d > daysIn(y, mo))
+        return null;
+    if (h > 23 || mi > 59 || s > 59)
+        return null;
+    const ms = Number((m[7] ?? '').slice(0, 3).padEnd(3, '0'));
+    let offsetMin = 0;
+    const zone = m[8];
+    if (zone !== undefined && zone !== 'Z') {
+        const oh = Number(zone.slice(1, 3));
+        const om = Number(zone.slice(4, 6));
+        if (oh > 23 || om > 59)
+            return null;
+        offsetMin = (zone.startsWith('-') ? -1 : 1) * (oh * 60 + om);
+    }
+    // setUTCFullYear keeps years below 100 as written (Date.UTC would add 1900).
+    const t = new Date(0);
+    t.setUTCFullYear(y, mo - 1, d);
+    t.setUTCHours(h, mi, s, ms);
+    const at = t.getTime() - offsetMin * 60_000;
+    const out = new Date(at);
+    const year = out.getUTCFullYear();
+    if (year < 0 || year > 9999)
+        return null;
+    return out.toISOString();
+}
+// ---------------------------------------------------------------------------
+// The columns
+// ---------------------------------------------------------------------------
+/**
+ * Captured timestamp columns per sync-set table. The claim-lease columns
+ * (`claimed_at`, `lease_expires_at`) are local-only and are not captured, so
+ * they are not here. A test pins this map against every captured `*_at`
+ * column of the sync set.
+ */
+export const SYNC_TIMESTAMP_COLUMNS = {
+    project: {
+        tasks_tasks: ['created_at', 'updated_at', 'completed_at', 'cancelled_at', 'archived_at'],
+        tasks_sessions: ['started_at', 'ended_at', 'task_started_at', 'handoff_consumed_at'],
+        tasks_task_acceptance_criteria: ['created_at', 'updated_at'],
+        tasks_task_acceptance_criteria_history: ['recorded_at'],
+        tasks_evidence_ac_bindings: ['created_at'],
+        tasks_display_id_aliases: ['created_at'],
+        tasks_uid_aliases: ['created_at'],
+    },
+    global: {},
+};
+/**
+ * Columns the one-time rewrite never touches: `tasks_tasks.updated_at` is the
+ * #1698 CAS token, and rewriting it would invalidate a caller's `--if-match`.
+ */
+export const CANON_EXCLUDED_COLUMNS = {
+    project: { tasks_tasks: ['updated_at'] },
+    global: {},
+};
+/** The captured timestamp columns of `table` (empty when it has none). */
+export function timestampColumns(scope, table) {
+    const cols = SYNC_TIMESTAMP_COLUMNS[scope];
+    return new Set(Object.hasOwn(cols, table) ? cols[table] : []);
+}
+// ---------------------------------------------------------------------------
+// The one-time rewrite
+// ---------------------------------------------------------------------------
+/** Marker key in `tasks_row_identity_meta` once the rewrite has run. */
+export const TIMESTAMP_CANON_MARKER = 'timestamp_canon_v1';
+const q = (id) => `"${id.replaceAll('"', '""')}"`;
+function metaValue(db, key) {
+    const row = db
+        .prepare(`SELECT value FROM ${q(ROW_IDENTITY_META_TABLE)} WHERE key = ?`)
+        .get(key);
+    return row?.value;
+}
+function columnsOf(db, table) {
+    const info = db.prepare(`PRAGMA main.table_info(${q(table)})`).all();
+    return new Set(info.map((c) => c.name));
+}
+/** Distinct text values of one column, read once. */
+function distinctText(db, table, column) {
+    return db
+        .prepare(`SELECT DISTINCT ${q(column)} AS v FROM ${q(table)} WHERE typeof(${q(column)}) = 'text'`)
+        .all().map((r) => r.v);
+}
+function countValue(db, table, column, value) {
+    return db.prepare(`SELECT count(*) AS n FROM ${q(table)} WHERE ${q(column)} = ?`).get(value).n;
+}
+/**
+ * Rows whose timestamp the canonicalizer refuses, per `table.column`: the
+ * doctor's `timestamp_ambiguous` finding. Read-only.
+ */
+export function ambiguousTimestamps(db, scope) {
+    const out = {};
+    for (const [table, cols] of Object.entries(SYNC_TIMESTAMP_COLUMNS[scope])) {
+        if (!hasTable(db, table))
+            continue;
+        const present = columnsOf(db, table);
+        for (const col of cols) {
+            if (!present.has(col))
+                continue;
+            let n = 0;
+            for (const v of distinctText(db, table, col)) {
+                if (canonicalStoreTimestamp(v) === null)
+                    n += countValue(db, table, col, v);
+            }
+            if (n > 0)
+                out[`${table}.${col}`] = n;
+        }
+    }
+    return out;
+}
+/**
+ * The one-time rewrite (§1.8): every accepted legacy value in
+ * {@link SYNC_TIMESTAMP_COLUMNS}, except {@link CANON_EXCLUDED_COLUMNS},
+ * becomes canonical. Refused values stay as they are and are counted.
+ *
+ * - Runs once per store: the {@link TIMESTAMP_CANON_MARKER} row records it.
+ * - Refused once `row_identity_synced` exists: values have left the device.
+ * - Runs in one `BEGIN IMMEDIATE` (or the caller's transaction) with the
+ *   capture and side-effect triggers suspended, so nothing is captured and
+ *   no trigger reacts. Guards stay on; canonical values satisfy them.
+ * - Deterministic: each distinct value maps through the pure canonicalizer,
+ *   so two copies of a store agree.
+ */
+export function canonicalizeStoreTimestamps(db, scope) {
+    const tables = Object.entries(SYNC_TIMESTAMP_COLUMNS[scope]);
+    if (tables.length === 0)
+        return { status: 'skipped', reason: `no timestamp columns in ${scope}` };
+    if (!hasTable(db, ROW_IDENTITY_META_TABLE)) {
+        return { status: 'skipped', reason: `${ROW_IDENTITY_META_TABLE} is absent` };
+    }
+    // Without the C2 flag table no trigger can be suspended, and a capture
+    // trigger (which reads it) cannot exist either.
+    if (!hasTriggerSuspendTable(db)) {
+        return { status: 'skipped', reason: 'cleo_trigger_suspend is absent' };
+    }
+    const run = () => {
+        if (metaValue(db, TIMESTAMP_CANON_MARKER) !== undefined)
+            return { status: 'already' };
+        if (metaValue(db, ROW_IDENTITY_SYNCED_KEY) !== undefined) {
+            return {
+                status: 'refused',
+                reason: `${ROW_IDENTITY_SYNCED_KEY} exists: timestamps are canonical on the wire only`,
+            };
+        }
+        const rewritten = {};
+        const ambiguous = {};
+        withTriggersSuspended(db, ['capture', 'side-effect'], 'forward', () => {
+            for (const [table, cols] of tables) {
+                if (!hasTable(db, table))
+                    continue;
+                const present = columnsOf(db, table);
+                const excluded = new Set(CANON_EXCLUDED_COLUMNS[scope][table] ?? []);
+                for (const col of cols) {
+                    if (excluded.has(col) || !present.has(col))
+                        continue;
+                    const update = db.prepare(`UPDATE ${q(table)} SET ${q(col)} = ? WHERE ${q(col)} = ?`);
+                    for (const raw of distinctText(db, table, col)) {
+                        const canon = canonicalStoreTimestamp(raw);
+                        const key = `${table}.${col}`;
+                        if (canon === null) {
+                            ambiguous[key] = (ambiguous[key] ?? 0) + countValue(db, table, col, raw);
+                        }
+                        else if (canon !== raw) {
+                            const n = Number(update.run(canon, raw).changes);
+                            rewritten[key] = (rewritten[key] ?? 0) + n;
+                        }
+                    }
+                }
+            }
+        });
+        db.prepare(`INSERT INTO ${q(ROW_IDENTITY_META_TABLE)} (key, value) VALUES (?, ?)`).run(TIMESTAMP_CANON_MARKER, 'done');
+        return { status: 'done', rewritten, ambiguous };
+    };
+    return db.isTransaction ? run() : withImmediateTransaction(db, run);
+}
+//# sourceMappingURL=timestamps.js.map

package/dist/store/sync/timestamps.js.map

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

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

@@ -0,0 +1,75 @@
+/**
+ * Minimal tombstones (journal spec §1.7, NEW-2, R5-5; T12986, S3c).
+ *
+ * The sealer writes a FULL tombstone on D: the row meta with `deleted = 1`,
+ * the delete HLC, the natural key and the before-image hash. GC never forgets
+ * that a uid was deleted; once the stream is safely past a tombstone,
+ * {@link compactTombstones} shrinks it to the minimal form
+ * (`tbl`, `uid`, `hlc`, `deleted = 1`), so a receiver can still tell a
+ * deleted uid from a never-seen one and a late op never resurrects the row.
+ * It is found by its WITHOUT ROWID key and has no entry in the tombstone
+ * index (which holds only full tombstones): about 155 B per row as measured,
+ * within the spec's ~190 B.
+ *
+ * Append-only tables get no per-row tombstone at all (the sealer removes
+ * their meta on D); the horizon fold into `_sync_tomb_fold` needs checkpoint
+ * receive watermarks and is S4.
+ *
+ * What makes a tombstone compactable is stream state this slice does not own
+ * (the latest verified checkpoint's `ReplicaHeads`, T12338; the inbox's
+ * pending and void transactions, T12344), so the caller supplies it as a
+ * {@link TombstoneGcPolicy}.
+ *
+ * @module store/sync/tombstones
+ * @task T12986
+ * @epic T12323
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** Grace after a tombstone's physical time before it may be compacted (§1.7). */
+export declare const TOMBSTONE_GRACE_MS: number;
+/** When a full tombstone may shrink to its minimal form. */
+export interface TombstoneGcPolicy {
+    /**
+     * The highest HLC every live replica has covered: in the latest verified
+     * checkpoint's `ReplicaHeads`, each live replica's `lastReplicaSeq` covers a
+     * segment whose `hlcMax` is at least this. Retired replicas are left out by
+     * the caller (§1.5). Only tombstones at or below it are compacted.
+     */
+    readonly coveredHlc: string;
+    /** Wall clock, ms. */
+    readonly now: number;
+    /** @defaultValue {@link TOMBSTONE_GRACE_MS} */
+    readonly graceMs?: number;
+    /**
+     * Whether a `pending` or `void` inbox transaction references the uid
+     * (T12344). Such a full tombstone is kept: the void may yet be revived.
+     */
+    readonly referenced: (tbl: string, uid: string) => boolean;
+    /** Most tombstones examined per call. @defaultValue 5000 */
+    readonly budget?: number;
+}
+/** What {@link compactTombstones} did. */
+export interface TombstoneCompactReport {
+    /** Full tombstones shrunk to the minimal form. */
+    readonly compacted: number;
+    /** Eligible by HLC and age, kept because an inbox transaction references the uid. */
+    readonly referenced: number;
+    /** Covered, but younger than the grace period. */
+    readonly young: number;
+}
+/**
+ * Shrink full tombstones the stream no longer needs to their minimal form,
+ * in one `BEGIN IMMEDIATE`. Never deletes a tombstone: a minimal one is kept
+ * for good (NEW-2).
+ *
+ * The minimal form keeps `tbl`, `uid`, `hlc` and `deleted = 1`; `origin` and
+ * `version` take their empty values (`''`, `0`) because the columns are
+ * NOT NULL, and `sent`, `held` and `fk_excluded` are left as they are.
+ */
+export declare function compactTombstones(db: DatabaseSync, policy: TombstoneGcPolicy): TombstoneCompactReport;
+/** Tombstone counts for the doctor and the growth measurement (§1.7 R5-5). */
+export declare function tombstoneCounts(db: DatabaseSync): {
+    full: number;
+    minimal: number;
+};
+//# sourceMappingURL=tombstones.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tombstones.d.ts","sourceRoot":"","sources":["../../../src/store/sync/tombstones.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAA2B,CAAC;AAE3D,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3D,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAUD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,iBAAiB,GACxB,sBAAsB,CAmCxB;AAYD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUnF"}

package/dist/store/sync/tombstones.js

@@ -0,0 +1,103 @@
+/**
+ * Minimal tombstones (journal spec §1.7, NEW-2, R5-5; T12986, S3c).
+ *
+ * The sealer writes a FULL tombstone on D: the row meta with `deleted = 1`,
+ * the delete HLC, the natural key and the before-image hash. GC never forgets
+ * that a uid was deleted; once the stream is safely past a tombstone,
+ * {@link compactTombstones} shrinks it to the minimal form
+ * (`tbl`, `uid`, `hlc`, `deleted = 1`), so a receiver can still tell a
+ * deleted uid from a never-seen one and a late op never resurrects the row.
+ * It is found by its WITHOUT ROWID key and has no entry in the tombstone
+ * index (which holds only full tombstones): about 155 B per row as measured,
+ * within the spec's ~190 B.
+ *
+ * Append-only tables get no per-row tombstone at all (the sealer removes
+ * their meta on D); the horizon fold into `_sync_tomb_fold` needs checkpoint
+ * receive watermarks and is S4.
+ *
+ * What makes a tombstone compactable is stream state this slice does not own
+ * (the latest verified checkpoint's `ReplicaHeads`, T12338; the inbox's
+ * pending and void transactions, T12344), so the caller supplies it as a
+ * {@link TombstoneGcPolicy}.
+ *
+ * @module store/sync/tombstones
+ * @task T12986
+ * @epic T12323
+ */
+import { withImmediateTransaction } from './clock-store.js';
+import { HlcError, parseHlc } from './hlc.js';
+import { hasTable } from './schema.js';
+/** Grace after a tombstone's physical time before it may be compacted (§1.7). */
+export const TOMBSTONE_GRACE_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * A full tombstone: the sealer always writes `version >= 1`, compaction sets
+ * it to 0. The predicate matches the partial index `_sync_row_meta_tomb`
+ * (`(hlc) WHERE deleted = 1 AND version > 0`), so GC scans only full ones and
+ * a minimal tombstone carries no index entry.
+ */
+const FULL = 'version > 0';
+/**
+ * Shrink full tombstones the stream no longer needs to their minimal form,
+ * in one `BEGIN IMMEDIATE`. Never deletes a tombstone: a minimal one is kept
+ * for good (NEW-2).
+ *
+ * The minimal form keeps `tbl`, `uid`, `hlc` and `deleted = 1`; `origin` and
+ * `version` take their empty values (`''`, `0`) because the columns are
+ * NOT NULL, and `sent`, `held` and `fk_excluded` are left as they are.
+ */
+export function compactTombstones(db, policy) {
+    if (!hasTable(db, '_sync_row_meta'))
+        return { compacted: 0, referenced: 0, young: 0 };
+    const grace = policy.graceMs ?? TOMBSTONE_GRACE_MS;
+    const budget = Math.max(1, policy.budget ?? 5000);
+    return withImmediateTransaction(db, () => {
+        const rows = db
+            .prepare(`SELECT tbl, uid, hlc FROM _sync_row_meta
+          WHERE deleted = 1 AND ${FULL} AND hlc <= ?
+          ORDER BY hlc LIMIT ?`)
+            .all(policy.coveredHlc, budget);
+        const shrink = db.prepare(`UPDATE _sync_row_meta
+          SET fhlc = NULL, origin = '', actor = NULL, version = 0,
+              key_json = NULL, chash = NULL, shash = NULL, bfp = NULL
+        WHERE tbl = ? AND uid = ? AND deleted = 1`);
+        let compacted = 0;
+        let referenced = 0;
+        let young = 0;
+        for (const r of rows) {
+            if (policy.now - physicalMs(r.hlc) < grace) {
+                young += 1;
+                continue;
+            }
+            if (policy.referenced(r.tbl, r.uid)) {
+                referenced += 1;
+                continue;
+            }
+            shrink.run(r.tbl, r.uid);
+            compacted += 1;
+        }
+        return { compacted, referenced, young };
+    });
+}
+/** The physical ms of an HLC; an unparseable one counts as brand new (kept). */
+function physicalMs(hlc) {
+    try {
+        return parseHlc(hlc).phys;
+    }
+    catch (err) {
+        if (err instanceof HlcError)
+            return Number.POSITIVE_INFINITY;
+        throw err;
+    }
+}
+/** Tombstone counts for the doctor and the growth measurement (§1.7 R5-5). */
+export function tombstoneCounts(db) {
+    if (!hasTable(db, '_sync_row_meta'))
+        return { full: 0, minimal: 0 };
+    const row = db
+        .prepare(`SELECT coalesce(sum(CASE WHEN ${FULL} THEN 1 ELSE 0 END), 0) AS full,
+              coalesce(sum(CASE WHEN ${FULL} THEN 0 ELSE 1 END), 0) AS minimal
+         FROM _sync_row_meta WHERE deleted = 1`)
+        .get();
+    return { full: row.full, minimal: row.minimal };
+}
+//# sourceMappingURL=tombstones.js.map

package/dist/store/sync/tombstones.js.map

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

package/dist/store/sync/trigger-classes.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Trigger classes and the suspension clause (journal spec §3.5 Rule 4, C2,
+ * D4; T12813, T12819, T12827).
+ *
+ * Every trigger in a store has exactly one class. The class decides whether
+ * the trigger carries the suspension clause, which a rebase frame uses to
+ * turn a class off inside its own transaction:
+ *
+ * | Class | Carries the clause | Example |
+ * |---|---|---|
+ * | `capture` | yes, scope `capture` | `_sync_cap_*` (S2 capture triggers) |
+ * | `guard` | yes, scope `guard` | the parent-cycle and status-pipeline guards |
+ * | `side-effect` | yes, scope `side-effect` | claim release, the handoff mirror |
+ * | `derived-maintenance` | no, always active | FTS `_ai`/`_ad`/`_au` |
+ * | `frozen-guard` | no, never modified | triggers on frozen-legacy bare twins |
+ *
+ * `guard` and `side-effect` triggers are OWNED: {@link OWNED_TRIGGERS} names
+ * each one, and its DDL is the last `CREATE TRIGGER` for that name in the
+ * migration lineage from the C2 migration on, or the code-held DDL of
+ * {@link CODE_OWNED_TRIGGER_DDL} ({@link ownedTriggerDdl}). The open pass and
+ * the doctor compare each owned trigger's LIVE text with that DDL and re-run
+ * the DDL when it differs or is missing (C2(b)), but only where every table
+ * the trigger needs exists ({@link OWNED_TRIGGER_REQUIRES}).
+ *
+ * A trigger is `frozen-guard` ONLY because of the table it fires ON: a
+ * `frozen-legacy` bare twin. A rebase never touches a frozen twin, and giving
+ * such a trigger a clause would make 9.24's replace-if-text-differs
+ * (`twin-collapse.ts`) and this build's repair flip its DDL on every open
+ * that alternates builds (D4). Its name never decides: a trigger on a live
+ * table (even one named `t12535_*`) is owned, or unclassified.
+ *
+ * @task T12819
+ * @task T12827
+ * @module store/sync/trigger-classes
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { TableScope } from '@cleocode/contracts';
+/** A trigger class. */
+export type TriggerClass = 'capture' | 'guard' | 'side-effect' | 'derived-maintenance' | 'frozen-guard';
+/** The classes that carry the suspension clause. */
+export type SuspendableClass = 'capture' | 'guard' | 'side-effect';
+/** The schema-owned flag table the suspension clause reads. Never dropped. */
+export declare const TRIGGER_SUSPEND_TABLE = "cleo_trigger_suspend";
+/**
+ * DDL of the flag table, byte-identical to the C2 migration's first
+ * statement. The open pass runs it (step 0) before migrations.
+ */
+export declare const TRIGGER_SUSPEND_TABLE_DDL = "CREATE TABLE IF NOT EXISTS `cleo_trigger_suspend` (\n  `scope` TEXT PRIMARY KEY NOT NULL CHECK (`scope` IN ('capture', 'guard', 'side-effect', 'all'))\n)";
+/** The C2 migration folder (drizzle-cleo-project). Owned DDL is read from it on. */
+export declare const TRIGGER_CLAUSE_MIGRATION = "20260930170000_t12819-trigger-suspend-clause";
+/** The lineage the owned triggers live in. */
+export declare const OWNED_TRIGGER_LINEAGE = "drizzle-cleo-project";
+/**
+ * The suspension clause a trigger of `cls` carries, exactly as written in
+ * migration SQL. Verification compares it whitespace-normalized.
+ *
+ * The table name is unqualified on purpose. A persistent trigger resolves an
+ * unqualified name in its own schema (a TEMP table cannot shadow it), so the
+ * trigger keeps working when the store is ATTACHed under another name; a
+ * `main.` qualifier makes an attached schema unreadable ("cannot reference
+ * objects in database main").
+ */
+export declare function suspendClause(cls: SuspendableClass): string;
+/**
+ * The owned guard and side-effect triggers (project store), by name. Each
+ * one's DDL comes from the migration lineage or from
+ * {@link CODE_OWNED_TRIGGER_DDL} ({@link ownedTriggerDdl}).
+ */
+export declare const OWNED_TRIGGERS: Readonly<Record<string, 'guard' | 'side-effect'>>;
+/**
+ * Owned triggers whose DDL is held in code, not in the C2 migration.
+ *
+ * The AC uid graveyard trigger writes `tasks_ac_uid_graveyard`. A store whose
+ * t12341 migration was probe-stamped after only its ADD COLUMNs ran (the
+ * 9.25 live-cleocode shape) has no graveyard table, and the table is created
+ * only by the flag-gated identity heal. A migration that created the trigger
+ * unconditionally would make every acceptance-criterion delete fail there
+ * ("no such table: main.tasks_ac_uid_graveyard"), so the trigger is installed
+ * by the open pass, and only where its table exists.
+ */
+export declare const CODE_OWNED_TRIGGER_DDL: Readonly<Record<string, string>>;
+/**
+ * Tables an owned trigger needs besides the one it fires ON. Where one is
+ * missing the trigger is not verified or installed, and a live copy is a
+ * finding (`dangling`) that repair drops: it would fail every write that
+ * fires it.
+ */
+export declare const OWNED_TRIGGER_REQUIRES: Readonly<Record<string, readonly string[]>>;
+/** Prefix of every capture trigger (S2, §2.3). */
+export declare const CAPTURE_TRIGGER_PREFIX = "_sync_cap_";
+/** A classified trigger. */
+export interface TriggerClassification {
+    readonly name: string;
+    readonly table: string;
+    readonly class: TriggerClass;
+    /** Why it has this class. */
+    readonly reason: string;
+}
+/**
+ * The tables a trigger body writes: `INSERT INTO t`, `UPDATE t`,
+ * `DELETE FROM t`, `REPLACE INTO t`. Lower-cased; quotes stripped.
+ */
+export declare function triggerWriteTargets(sql: string): string[];
+/**
+ * Classify one trigger. Returns `undefined` for a trigger no rule covers,
+ * which the Gate test reports.
+ *
+ * @param scope - The store the trigger lives in.
+ * @param name - `sqlite_master.name`.
+ * @param table - `sqlite_master.tbl_name`.
+ * @param sql - `sqlite_master.sql`.
+ */
+export declare function classifyTrigger(scope: TableScope, name: string, table: string, sql: string): TriggerClassification | undefined;
+/** Collapse whitespace so text comparisons ignore layout. */
+export declare function normalizeSql(sql: string): string;
+/**
+ * Split migration text into `CREATE TRIGGER` statements, by name. Later
+ * definitions of the same name replace earlier ones. `IF NOT EXISTS` is
+ * removed, as SQLite removes it from `sqlite_master.sql`.
+ */
+export declare function createTriggerStatements(migrationSql: string): Map<string, string>;
+/**
+ * The owned trigger DDL: {@link CODE_OWNED_TRIGGER_DDL}, then the last
+ * `CREATE TRIGGER` for each owned name in the lineage's migration files from
+ * {@link TRIGGER_CLAUSE_MIGRATION} on, in folder order (a later migration
+ * replaces a code-held text).
+ *
+ * @param folder - The lineage folder (tests pass one; default: installed).
+ * @throws {Error} When an owned trigger has no DDL from C2 on.
+ */
+export declare function ownedTriggerDdl(folder?: string): Map<string, string>;
+/** One finding of {@link verifyOwnedTriggers}. */
+export interface OwnedTriggerFinding {
+    readonly name: string;
+    /** `dangling`: live, but a table it needs is missing (repair drops it). */
+    readonly problem: 'missing' | 'text-differs' | 'no-clause' | 'dangling';
+    readonly repaired: boolean;
+}
+/** Whether the flag table exists. Read-only. */
+export declare function hasTriggerSuspendTable(db: DatabaseSync): boolean;
+/**
+ * Compare every owned trigger's live `sqlite_master.sql` with its owned DDL,
+ * and optionally repair (drop, then re-run the owned DDL) each one that is
+ * missing or differs.
+ *
+ * Only meaningful on a store whose journal has the C2 migration: before it,
+ * the owned DDL references a table the store may not have. Callers check
+ * {@link hasTriggerSuspendTable} and that the owned tables exist.
+ *
+ * @param db - A project store handle.
+ * @param options - `repair` rewrites; `ddl` overrides the owned DDL (tests).
+ * @returns One finding per trigger that was not identical.
+ */
+export declare function verifyOwnedTriggers(db: DatabaseSync, options?: {
+    repair?: boolean;
+    ddl?: Map<string, string>;
+}): OwnedTriggerFinding[];
+/**
+ * Run DDL as one unit (T13024 MED-2): `BEGIN IMMEDIATE` … `COMMIT` on an idle
+ * connection, a SAVEPOINT inside a caller's transaction. A failure rolls the
+ * whole unit back, so a DROP never commits without its CREATE.
+ */
+export declare function atomicDdl<T>(db: DatabaseSync, fn: () => T): T;
+/**
+ * Classify every trigger of a store. Read-only.
+ *
+ * @returns The classified triggers, and the names no rule covers.
+ */
+export declare function classifyStoreTriggers(db: DatabaseSync, scope: TableScope): {
+    classified: TriggerClassification[];
+    unclassified: string[];
+};
+/** What the open pass's step 0 did to the flag table. */
+export interface TriggerSuspendStepZero {
+    /** The table was missing and was created. */
+    readonly created: boolean;
+    /** Committed suspension rows found and cleared (should never happen). */
+    readonly cleared: number;
+}
+/**
+ * Open-pass step 0 (C2, round 9): make sure `cleo_trigger_suspend` exists,
+ * BEFORE migrations, and that it is empty.
+ *
+ * Every write to tasks, sessions and acceptance criteria fires an owned
+ * trigger that reads the table, and any `ALTER … RENAME` re-validates every
+ * trigger, so a store missing it cannot be written. A committed row is
+ * impossible through the rebase frame (it deletes and asserts before
+ * COMMIT); if one is found anyway it is cleared, because a committed
+ * suspension would silently disable guards for everyone.
+ *
+ * Writes nothing when the table exists and is empty.
+ */
+export declare function ensureTriggerSuspendTable(db: DatabaseSync): TriggerSuspendStepZero;
+/**
+ * Throw unless `cleo_trigger_suspend` is empty. A frame calls this right
+ * before COMMIT, so a suspension can never be committed (C4).
+ *
+ * @throws {Error} `E_TRIGGER_SUSPEND_NOT_EMPTY` when a row remains.
+ */
+export declare function assertTriggerSuspendEmpty(db: DatabaseSync): void;
+/**
+ * Why a caller suspends triggers. `rewind` and `undo` restore a state the
+ * store already held, so its guards held for it; `forward` is anything else
+ * (apply, replay, import, a derived rewrite).
+ */
+export type SuspendPurpose = 'rewind' | 'undo' | 'forward';
+/**
+ * Run `fn` with the given trigger classes suspended, inside the caller's
+ * transaction: insert the scope rows, run, delete them, and assert the table
+ * is empty before returning. Other connections never see the rows (WAL), so
+ * their triggers stay active; a crash rolls the rows back.
+ *
+ * Suspending `guard` (or `all`) is allowed only to rewind or undo (T12344
+ * AC5): a forward apply or replay with the guards off would commit a merged
+ * state they refuse (a dependency or parent cycle) without a word.
+ *
+ * @throws {Error} When called outside a transaction, or
+ *   `E_GUARD_SUSPEND_FORWARD` when a forward purpose suspends `guard`.
+ */
+export declare function withTriggersSuspended<T>(db: DatabaseSync, scopes: ReadonlyArray<SuspendableClass | 'all'>, purpose: SuspendPurpose, fn: () => T): T;
+//# sourceMappingURL=trigger-classes.d.ts.map

package/dist/store/sync/trigger-classes.d.ts.map

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