@cleocode/core 2026.10.4 → 2026.10.5-rc.ci.672

package/dist/store/sync/apply/frame.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The synchronous apply frame (T12344; journal spec §3.2 "withApplyFrame").
+ *
+ * Every remote op is applied inside one apply frame: a single
+ * `BEGIN IMMEDIATE … COMMIT` holding a `_sync_frame` row of kind `apply`, so
+ * the capture triggers label the frame's captures and the sealer subtracts
+ * the frame's apply intents from them (§3.3). The frame body is SYNCHRONOUS:
+ * an `await` inside it would let another writer on the same handle interleave
+ * its writes into the frame, and they would be subtracted as if the apply had
+ * written them.
+ *
+ * - {@link runApplyFrame} awaits the async preparation first (unsealing,
+ *   loading), then queues the frame behind the handle's foreground
+ *   transactions and committed effects (`scheduleTaskBackground`), and only
+ *   then runs the synchronous body.
+ * - {@link withApplyFrame} is the frame itself:
+ *   - it opens the only transaction, BEGIN IMMEDIATE, once: the handle's
+ *     `busy_timeout` does the waiting (30 s on dual-scope handles), so the
+ *     main thread blocks at most that long, and a BUSY after it is thrown,
+ *     never retried mid-frame;
+ *   - it inserts the frame row and calls the body with the API;
+ *   - **type guard:** the body's return type excludes `PromiseLike`;
+ *   - **runtime guard:** a thenable return rolls back and throws
+ *     `E_SYNC_APPLY_ASYNC`;
+ *   - any API call after the frame ended throws (`assertActive`).
+ *
+ * @module store/sync/apply/frame
+ * @task T12344
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { TableScope } from '@cleocode/contracts';
+import { type ApplyWriteApi } from './write-api.js';
+/** A frame misuse: an async body, a nested call, or a call after the frame ended. */
+export declare class ApplyFrameError extends Error {
+    readonly code: 'E_SYNC_APPLY_ASYNC' | 'E_SYNC_APPLY_NESTED' | 'E_SYNC_APPLY_ENDED';
+    constructor(code: 'E_SYNC_APPLY_ASYNC' | 'E_SYNC_APPLY_NESTED' | 'E_SYNC_APPLY_ENDED', message: string);
+}
+/** A synchronous result: never a thenable. */
+export type SyncResult<T> = T extends PromiseLike<unknown> ? never : T;
+/** Everything a frame body may do. */
+export interface ApplyApi extends ApplyWriteApi {
+    /** The frame id, or null when capture is off on this connection. */
+    readonly frame: string | null;
+    /**
+     * Merge a remote HLC into this replica's clock (§1.3). Returns the new
+     * clock, or `held` when the remote clock is beyond the skew limit.
+     */
+    clockReceive(replica: string, remoteHlc: string, nowMs: number): {
+        held: false;
+        clock: string;
+    } | {
+        held: true;
+    };
+}
+/**
+ * Run `fn` as one apply frame on `db`: the only transaction, with a
+ * `_sync_frame` row of kind `apply`, committed when `fn` returns.
+ *
+ * @param db - The store; must not be inside a transaction.
+ * @param scope - The store's scope.
+ * @param actor - The frame's actor (JSON of the remote writer), or null.
+ * @param fn - The synchronous body.
+ * @returns What `fn` returned.
+ * @throws {ApplyFrameError} On a nested call or a thenable result.
+ * @throws SQLITE_BUSY when another writer holds the store past `busy_timeout`.
+ */
+export declare function withApplyFrame<T>(db: DatabaseSync, scope: TableScope, actor: string | null, fn: (api: ApplyApi) => SyncResult<T>): SyncResult<T>;
+/**
+ * Prepare asynchronously, then run one apply frame queued behind the
+ * handle's foreground transactions (§3.2 steps 1–3).
+ *
+ * @param db - The store.
+ * @param scope - The store's scope.
+ * @param actor - The frame's actor, or null.
+ * @param prepare - Async preparation (unsealing secrets, loading); its result is passed in.
+ * @param fn - The synchronous body.
+ * @returns What `fn` returned.
+ */
+export declare function runApplyFrame<P, T>(db: DatabaseSync, scope: TableScope, actor: string | null, prepare: () => Promise<P>, fn: (api: ApplyApi, prepared: P) => SyncResult<T>): Promise<SyncResult<T>>;
+//# sourceMappingURL=frame.d.ts.map

package/dist/store/sync/apply/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../../../src/store/sync/apply/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,KAAK,aAAa,EAAuB,MAAM,gBAAgB,CAAC;AAEzE,qFAAqF;AACrF,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,oBAAoB;gBAAzE,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,oBAAoB,EAClF,OAAO,EAAE,MAAM;CAKlB;AAED,8CAA8C;AAC9C,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,WAAW,CAAC,OAAO,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEvE,sCAAsC;AACtC,MAAM,WAAW,QAAS,SAAQ,aAAa;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;OAGG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ;QAAE,IAAI,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;CACpD;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,GACnC,UAAU,CAAC,CAAC,CAAC,CAgDf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE,CAAC,EACtC,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,EAAE,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,KAAK,UAAU,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CASxB"}

package/dist/store/sync/apply/frame.js

@@ -0,0 +1,127 @@
+/**
+ * The synchronous apply frame (T12344; journal spec §3.2 "withApplyFrame").
+ *
+ * Every remote op is applied inside one apply frame: a single
+ * `BEGIN IMMEDIATE … COMMIT` holding a `_sync_frame` row of kind `apply`, so
+ * the capture triggers label the frame's captures and the sealer subtracts
+ * the frame's apply intents from them (§3.3). The frame body is SYNCHRONOUS:
+ * an `await` inside it would let another writer on the same handle interleave
+ * its writes into the frame, and they would be subtracted as if the apply had
+ * written them.
+ *
+ * - {@link runApplyFrame} awaits the async preparation first (unsealing,
+ *   loading), then queues the frame behind the handle's foreground
+ *   transactions and committed effects (`scheduleTaskBackground`), and only
+ *   then runs the synchronous body.
+ * - {@link withApplyFrame} is the frame itself:
+ *   - it opens the only transaction, BEGIN IMMEDIATE, once: the handle's
+ *     `busy_timeout` does the waiting (30 s on dual-scope handles), so the
+ *     main thread blocks at most that long, and a BUSY after it is thrown,
+ *     never retried mid-frame;
+ *   - it inserts the frame row and calls the body with the API;
+ *   - **type guard:** the body's return type excludes `PromiseLike`;
+ *   - **runtime guard:** a thenable return rolls back and throws
+ *     `E_SYNC_APPLY_ASYNC`;
+ *   - any API call after the frame ended throws (`assertActive`).
+ *
+ * @module store/sync/apply/frame
+ * @task T12344
+ */
+import { finishCaptureFrame, openCaptureFrame } from '../capture.js';
+import { receiveClock } from '../clock-store.js';
+import { createApplyWriteApi } from './write-api.js';
+/** A frame misuse: an async body, a nested call, or a call after the frame ended. */
+export class ApplyFrameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ApplyFrameError';
+    }
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+/**
+ * Run `fn` as one apply frame on `db`: the only transaction, with a
+ * `_sync_frame` row of kind `apply`, committed when `fn` returns.
+ *
+ * @param db - The store; must not be inside a transaction.
+ * @param scope - The store's scope.
+ * @param actor - The frame's actor (JSON of the remote writer), or null.
+ * @param fn - The synchronous body.
+ * @returns What `fn` returned.
+ * @throws {ApplyFrameError} On a nested call or a thenable result.
+ * @throws SQLITE_BUSY when another writer holds the store past `busy_timeout`.
+ */
+export function withApplyFrame(db, scope, actor, fn) {
+    if (db.isTransaction) {
+        // @sync-invariant none:local-only programming-error guard on the local apply frame
+        throw new ApplyFrameError('E_SYNC_APPLY_NESTED', 'an apply frame must open the only transaction');
+    }
+    // One attempt: busy_timeout already waits inside SQLite. A retry loop on
+    // top multiplied that wait while blocking the event loop (#1872 LOW-1).
+    db.exec('BEGIN IMMEDIATE');
+    let active = true;
+    const assertActive = () => {
+        if (!active) {
+            // @sync-invariant none:local-only programming-error guard: the frame's API outlived the frame
+            throw new ApplyFrameError('E_SYNC_APPLY_ENDED', 'the apply frame has ended');
+        }
+    };
+    try {
+        const frame = openCaptureFrame(db, 'apply', actor);
+        const api = {
+            frame,
+            ...createApplyWriteApi(db, scope, frame, assertActive),
+            clockReceive(replica, remoteHlc, nowMs) {
+                assertActive();
+                return receiveClock(db, replica, remoteHlc, nowMs);
+            },
+        };
+        const out = fn(api);
+        if (isThenable(out)) {
+            // Never leave the dropped promise unhandled: a rejection would crash
+            // the process (#1872 LOW-2).
+            Promise.resolve(out).then(undefined, () => undefined);
+            // @sync-invariant none:local-only programming-error guard: an async body would let writers interleave into the frame
+            throw new ApplyFrameError('E_SYNC_APPLY_ASYNC', 'an apply frame body must be synchronous (it returned a thenable)');
+        }
+        finishCaptureFrame(db, frame);
+        db.exec('COMMIT');
+        return out;
+    }
+    catch (err) {
+        if (db.isTransaction)
+            db.exec('ROLLBACK');
+        throw err;
+    }
+    finally {
+        active = false;
+    }
+}
+/**
+ * Prepare asynchronously, then run one apply frame queued behind the
+ * handle's foreground transactions (§3.2 steps 1–3).
+ *
+ * @param db - The store.
+ * @param scope - The store's scope.
+ * @param actor - The frame's actor, or null.
+ * @param prepare - Async preparation (unsealing secrets, loading); its result is passed in.
+ * @param fn - The synchronous body.
+ * @returns What `fn` returned.
+ */
+export async function runApplyFrame(db, scope, actor, prepare, fn) {
+    const prepared = await prepare();
+    // Loaded here: the accessor module is large, and the frame itself needs none of it.
+    const { scheduleTaskBackground } = await import('../../sqlite-data-accessor.js');
+    let out;
+    await scheduleTaskBackground(db, async () => {
+        out = withApplyFrame(db, scope, actor, (api) => fn(api, prepared));
+    });
+    return out;
+}
+//# sourceMappingURL=frame.js.map

package/dist/store/sync/apply/frame.js.map

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

package/dist/store/sync/apply/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The change journal's apply frame and write API (T12344, PR-2): the only way
+ * apply writes synced rows, recording the apply intents the sealer subtracts.
+ *
+ * @module store/sync/apply
+ * @task T12344
+ */
+export { type ApplyReport, type ApplyStagedOptions, applyStagedTxns } from './applier.js';
+export { type ApplyApi, ApplyFrameError, runApplyFrame, type SyncResult, withApplyFrame, } from './frame.js';
+export { type ApplyWriteApi, ApplyWriteError, createApplyWriteApi, type StoredEncs, wireToSql, } from './write-api.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/sync/apply/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/store/sync/apply/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EACL,KAAK,QAAQ,EACb,eAAe,EACf,aAAa,EACb,KAAK,UAAU,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,aAAa,EAClB,eAAe,EACf,mBAAmB,EACnB,KAAK,UAAU,EACf,SAAS,GACV,MAAM,gBAAgB,CAAC"}

package/dist/store/sync/apply/index.js

@@ -0,0 +1,11 @@
+/**
+ * The change journal's apply frame and write API (T12344, PR-2): the only way
+ * apply writes synced rows, recording the apply intents the sealer subtracts.
+ *
+ * @module store/sync/apply
+ * @task T12344
+ */
+export { applyStagedTxns } from './applier.js';
+export { ApplyFrameError, runApplyFrame, withApplyFrame, } from './frame.js';
+export { ApplyWriteError, createApplyWriteApi, wireToSql, } from './write-api.js';
+//# sourceMappingURL=index.js.map

package/dist/store/sync/apply/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/store/sync/apply/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA6C,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EAEL,eAAe,EACf,aAAa,EAEb,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,eAAe,EACf,mBAAmB,EAEnB,SAAS,GACV,MAAM,gBAAgB,CAAC"}

package/dist/store/sync/apply/parent-delete.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What a remote delete of an FK parent does to its remaining sync-set
+ * children (T12344 PR-4; journal spec §3.2 "FK actions", R5-7, NEW-4).
+ *
+ * The origin journals its cascaded child deletes before the parent's D, so
+ * normally no child remains when the parent's D applies. A child that does
+ * remain was written concurrently, and SQLite would cascade it away with no
+ * op. The parent table's policy decides instead:
+ *
+ * - `conflict` (tasks, sessions): the parent's D is not applied; it becomes a
+ *   revivable void plus a `delete-with-live-children` conflict listing the
+ *   children. Resolutions are ordinary writes.
+ * - `cascade-with-ops` (hard deletes by design: purges, GC paths): every
+ *   replica deletes the remaining children deterministically inside the
+ *   apply frame, with intents, so nothing is re-emitted.
+ *
+ * Only `ON DELETE CASCADE` children count: a `SET NULL` child survives (its
+ * cleared column is recorded as an apply intent), and a `RESTRICT` child
+ * makes the delete fail, which the applier turns into a guard conflict.
+ * Every sync-set FK parent is declared here; a test fails on an undeclared
+ * one.
+ *
+ * @module store/sync/apply/parent-delete
+ * @task T12344
+ */
+/** A parent table's remote-delete policy. */
+export type ParentDeletePolicy = 'conflict' | 'cascade-with-ops';
+/** The policy of every sync-set table that is an FK parent of sync-set children. */
+export declare const ON_REMOTE_PARENT_DELETE: Readonly<Record<string, ParentDeletePolicy>>;
+/**
+ * The policy for a parent table; `conflict` (never lose a row silently) for
+ * a table the registry does not name.
+ *
+ * @param table - The parent table.
+ * @returns Its policy.
+ */
+export declare function parentDeletePolicy(table: string): ParentDeletePolicy;
+//# sourceMappingURL=parent-delete.d.ts.map

package/dist/store/sync/apply/parent-delete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-delete.d.ts","sourceRoot":"","sources":["../../../../src/store/sync/apply/parent-delete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,kBAAkB,CAAC;AAEjE,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAGhF,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAEpE"}

package/dist/store/sync/apply/parent-delete.js

@@ -0,0 +1,41 @@
+/**
+ * What a remote delete of an FK parent does to its remaining sync-set
+ * children (T12344 PR-4; journal spec §3.2 "FK actions", R5-7, NEW-4).
+ *
+ * The origin journals its cascaded child deletes before the parent's D, so
+ * normally no child remains when the parent's D applies. A child that does
+ * remain was written concurrently, and SQLite would cascade it away with no
+ * op. The parent table's policy decides instead:
+ *
+ * - `conflict` (tasks, sessions): the parent's D is not applied; it becomes a
+ *   revivable void plus a `delete-with-live-children` conflict listing the
+ *   children. Resolutions are ordinary writes.
+ * - `cascade-with-ops` (hard deletes by design: purges, GC paths): every
+ *   replica deletes the remaining children deterministically inside the
+ *   apply frame, with intents, so nothing is re-emitted.
+ *
+ * Only `ON DELETE CASCADE` children count: a `SET NULL` child survives (its
+ * cleared column is recorded as an apply intent), and a `RESTRICT` child
+ * makes the delete fail, which the applier turns into a guard conflict.
+ * Every sync-set FK parent is declared here; a test fails on an undeclared
+ * one.
+ *
+ * @module store/sync/apply/parent-delete
+ * @task T12344
+ */
+/** The policy of every sync-set table that is an FK parent of sync-set children. */
+export const ON_REMOTE_PARENT_DELETE = {
+    tasks_tasks: 'conflict',
+    tasks_sessions: 'conflict',
+};
+/**
+ * The policy for a parent table; `conflict` (never lose a row silently) for
+ * a table the registry does not name.
+ *
+ * @param table - The parent table.
+ * @returns Its policy.
+ */
+export function parentDeletePolicy(table) {
+    return ON_REMOTE_PARENT_DELETE[table] ?? 'conflict';
+}
+//# sourceMappingURL=parent-delete.js.map

package/dist/store/sync/apply/parent-delete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent-delete.js","sourceRoot":"","sources":["../../../../src/store/sync/apply/parent-delete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,oFAAoF;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAiD;IACnF,WAAW,EAAE,UAAU;IACvB,cAAc,EAAE,UAAU;CAC3B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,uBAAuB,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC;AACtD,CAAC"}

package/dist/store/sync/apply/post-apply.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Gate C post-apply checks (T12344 PR-5; journal spec §3.6 "post-apply-check",
+ * §3.5 Rule 3).
+ *
+ * The apply writes through the write API, never the TypeScript write paths,
+ * so a merge of two ops each valid on its own device can produce a state the
+ * CLI would refuse while no trigger notices. A post-apply check evaluates one
+ * multi-row invariant over the transaction's page (the rows it wrote, plus
+ * the footprint the invariant declares) after the transaction's ops applied,
+ * inside the same frame. A violation rolls the whole transaction back: it
+ * becomes a revivable void plus one `post-apply` conflict per violation.
+ *
+ * Implemented here, on the tables that sync today:
+ * - PAC-01 `task.tree.shape` ({@link checkTaskTreeShape});
+ * - PAC-15 `apply.preconditions` ({@link checkApplyPreconditions}), which is
+ *   checked before a pass, not per transaction.
+ * PAC-03 `task.dependency.graph` is trigger-covered since T12886
+ * (`tasks_task_dependencies_cycle_guard_*`): a cycle-closing edge is a guard
+ * conflict. The other families stay pending in the write-invariant registry
+ * until their tables join the sync set.
+ *
+ * Read-only.
+ *
+ * @module store/sync/apply/post-apply
+ * @task T12344
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** A row the transaction wrote. */
+export interface PageRow {
+    readonly table: string;
+    readonly uid: string;
+    /**
+     * The op could change the row's own type (an insert, or a write of
+     * `type`): only then are its children re-judged, since moving a row never
+     * changes whether its children are allowed under it.
+     */
+    readonly typeChanged?: boolean;
+}
+/** One broken invariant. */
+export interface PostApplyViolation {
+    /** The write-invariant registry id (e.g. `task.tree.shape`). */
+    readonly check: string;
+    readonly table: string;
+    readonly uid: string;
+    readonly message: string;
+}
+/**
+ * PAC-01 `task.tree.shape` over the page: for every task the transaction
+ * wrote, no self-parent, no ancestor cycle, a parent whose type may contain
+ * it (saga → epic → task → subtask), and every child still allowed under its
+ * (possibly changed) type. Root rules are left to the domain write paths.
+ *
+ * @param db - The store, inside the apply frame.
+ * @param page - The rows the transaction wrote.
+ * @returns The violations; empty when the shape holds.
+ */
+export declare function checkTaskTreeShape(db: DatabaseSync, page: readonly PageRow[]): PostApplyViolation[];
+/**
+ * PAC-15 `apply.preconditions`: why no transaction may apply to this store
+ * now, or null. A store whose twin collapse failed refuses every write
+ * (T12535), so applying would half-write the stream.
+ *
+ * @param db - The store.
+ * @returns The reason, or null.
+ */
+export declare function checkApplyPreconditions(db: DatabaseSync): string | null;
+//# sourceMappingURL=post-apply.d.ts.map

package/dist/store/sync/apply/post-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-apply.d.ts","sourceRoot":"","sources":["../../../../src/store/sync/apply/post-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,mCAAmC;AACnC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,kBAAkB,EAAE,CA8CtB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAKvE"}

package/dist/store/sync/apply/post-apply.js

@@ -0,0 +1,118 @@
+/**
+ * Gate C post-apply checks (T12344 PR-5; journal spec §3.6 "post-apply-check",
+ * §3.5 Rule 3).
+ *
+ * The apply writes through the write API, never the TypeScript write paths,
+ * so a merge of two ops each valid on its own device can produce a state the
+ * CLI would refuse while no trigger notices. A post-apply check evaluates one
+ * multi-row invariant over the transaction's page (the rows it wrote, plus
+ * the footprint the invariant declares) after the transaction's ops applied,
+ * inside the same frame. A violation rolls the whole transaction back: it
+ * becomes a revivable void plus one `post-apply` conflict per violation.
+ *
+ * Implemented here, on the tables that sync today:
+ * - PAC-01 `task.tree.shape` ({@link checkTaskTreeShape});
+ * - PAC-15 `apply.preconditions` ({@link checkApplyPreconditions}), which is
+ *   checked before a pass, not per transaction.
+ * PAC-03 `task.dependency.graph` is trigger-covered since T12886
+ * (`tasks_task_dependencies_cycle_guard_*`): a cycle-closing edge is a guard
+ * conflict. The other families stay pending in the write-invariant registry
+ * until their tables join the sync set.
+ *
+ * Read-only.
+ *
+ * @module store/sync/apply/post-apply
+ * @task T12344
+ */
+import { isAllowedWorkGraphParentType } from '@cleocode/contracts/workgraph.js';
+import { twinCollapseFailureOf } from '../../twin-collapse.js';
+/**
+ * The deepest ancestor chain walked before a cycle is assumed: far beyond
+ * the four levels the type matrix allows (saga, epic, task, subtask).
+ */
+const MAX_TREE_DEPTH = 64;
+const TASK_TYPES = new Set(['saga', 'epic', 'task', 'subtask']);
+const isTaskType = (t) => t !== null && TASK_TYPES.has(t);
+const asTaskType = (t) => (isTaskType(t) ? t : null);
+function taskByUid(db, uid) {
+    return db
+        .prepare('SELECT id, uid, parent_id, type FROM main.tasks_tasks WHERE uid = ?')
+        .get(uid);
+}
+function taskById(db, id) {
+    return db.prepare('SELECT id, uid, parent_id, type FROM main.tasks_tasks WHERE id = ?').get(id);
+}
+/**
+ * PAC-01 `task.tree.shape` over the page: for every task the transaction
+ * wrote, no self-parent, no ancestor cycle, a parent whose type may contain
+ * it (saga → epic → task → subtask), and every child still allowed under its
+ * (possibly changed) type. Root rules are left to the domain write paths.
+ *
+ * @param db - The store, inside the apply frame.
+ * @param page - The rows the transaction wrote.
+ * @returns The violations; empty when the shape holds.
+ */
+export function checkTaskTreeShape(db, page) {
+    const out = [];
+    const v = (uid, message) => {
+        out.push({ check: 'task.tree.shape', table: 'tasks_tasks', uid, message });
+    };
+    for (const row of page) {
+        if (row.table !== 'tasks_tasks')
+            continue;
+        const t = taskByUid(db, row.uid);
+        if (!t)
+            continue;
+        if (t.parent_id !== null && t.parent_id === t.id) {
+            v(row.uid, `${t.id} is its own parent`);
+            continue;
+        }
+        // Ancestor chain: no cycle.
+        const seen = new Set([t.id]);
+        let cur = t.parent_id;
+        for (let depth = 0; cur !== null; depth++) {
+            if (seen.has(cur) || depth > MAX_TREE_DEPTH) {
+                v(row.uid, `${t.id} is in a parent cycle`);
+                break;
+            }
+            seen.add(cur);
+            cur = taskById(db, cur)?.parent_id ?? null;
+        }
+        // Its parent may contain it.
+        const type = asTaskType(t.type);
+        if (t.parent_id !== null && type !== null) {
+            const parentType = asTaskType(taskById(db, t.parent_id)?.type ?? null);
+            if (parentType !== null && !isAllowedWorkGraphParentType(type, parentType)) {
+                v(row.uid, `a ${parentType} cannot contain the ${type} ${t.id}`);
+            }
+        }
+        // Its children are still allowed under a changed type (the trigger never re-checks them).
+        if (type !== null && row.typeChanged) {
+            const kids = db
+                .prepare('SELECT id, uid, type FROM main.tasks_tasks WHERE parent_id = ?')
+                .all(t.id);
+            for (const k of kids) {
+                const kt = asTaskType(k.type);
+                if (kt !== null && !isAllowedWorkGraphParentType(kt, type)) {
+                    v(row.uid, `the ${type} ${t.id} cannot contain its ${kt} ${k.id}`);
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * PAC-15 `apply.preconditions`: why no transaction may apply to this store
+ * now, or null. A store whose twin collapse failed refuses every write
+ * (T12535), so applying would half-write the stream.
+ *
+ * @param db - The store.
+ * @returns The reason, or null.
+ */
+export function checkApplyPreconditions(db) {
+    const failure = twinCollapseFailureOf(db);
+    return failure
+        ? `twin collapse failed (${failure.tables.join(', ')}): no apply until it is repaired`
+        : null;
+}
+//# sourceMappingURL=post-apply.js.map

package/dist/store/sync/apply/post-apply.js.map

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

package/dist/store/sync/apply/refs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Reference translation for apply (T12344 PR-4; journal spec §3.2 "Missing
+ * references", NEW-2, T12782).
+ *
+ * On the wire a reference column carries the target row's uid; in the store
+ * it holds the target's LOCAL key. The applier translates both ways:
+ *
+ * - **Writing** ({@link resolveRef}): the uid becomes the target's local key.
+ *   A target the receiver knows only through `tasks_uid_aliases` (re-keyed or
+ *   re-minted) is followed to its current uid. A target with a tombstone is
+ *   `tombstoned` (the op becomes a `dangling-ref` conflict plus a revivable
+ *   void); a target never seen is `missing` (the transaction waits, pending).
+ * - **Reading** ({@link uidOfKey}): the merge compares stream values, so the
+ *   row state it reads carries uids, not local keys.
+ *
+ * Read-only.
+ *
+ * @module store/sync/apply/refs
+ * @task T12344
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { LedgerWireValue } from '@cleocode/contracts/ledger';
+/** Where a wire reference points on this replica. */
+export type RefResolution = {
+    readonly kind: 'row';
+    readonly uid: string;
+    readonly key: LedgerWireValue;
+} | {
+    readonly kind: 'tombstoned';
+    readonly uid: string;
+} | {
+    readonly kind: 'missing';
+    readonly uid: string;
+};
+/**
+ * Resolve a wire reference (a target uid) to the target's local key.
+ *
+ * @param db - The store.
+ * @param target - The referenced table and its local key column.
+ * @param uid - The target uid on the wire.
+ * @returns The row's key, or why there is none.
+ */
+export declare function resolveRef(db: DatabaseSync, target: {
+    readonly table: string;
+    readonly key: string;
+}, uid: string): RefResolution;
+/**
+ * The uid of the row a local key references, or null when that row has no
+ * uid (or is absent).
+ *
+ * @param db - The store.
+ * @param target - The referenced table and its local key column.
+ * @param key - The local key the reference column holds.
+ * @returns The target's uid, or null.
+ */
+export declare function uidOfKey(db: DatabaseSync, target: {
+    readonly table: string;
+    readonly key: string;
+}, key: LedgerWireValue): string | null;
+//# sourceMappingURL=refs.d.ts.map

package/dist/store/sync/apply/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../../../src/store/sync/apply/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAQlE,qDAAqD;AACrD,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAqBvD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACxD,GAAG,EAAE,MAAM,GACV,aAAa,CAqBf;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACxD,GAAG,EAAE,eAAe,GACnB,MAAM,GAAG,IAAI,CAOf"}