@cleocode/core 2026.9.26 → 2026.10.2

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

@@ -0,0 +1,145 @@
+/**
+ * The sealer, S3a + S3b (journal spec §2.5 phase B, §2.4, §1.6, §2.6, §4.3;
+ * T12984, T12985).
+ *
+ * `sealPending` turns live `_sync_capture` rows into sealed transactions:
+ *
+ * 1. **Group (§2.4).** A validated frame (its `_sync_frame` row exists) is
+ *    one transaction. Every capture with no validated frame is a singleton
+ *    transaction flagged `unframed`, provenance `foreign` (ruling (c)): the
+ *    sealer never claims atomicity it did not observe. A batch ends on a
+ *    group boundary. Apply and rebase frames wait for S5's intent subtraction.
+ * 2. **Draft ops (§2.6).** Each capture becomes one draft. Values are decoded
+ *    from the capture's `enc()` text to typed wire values; references become
+ *    uids (resolved from the local key when the capture saw none); secret
+ *    columns and the local columns a stored ref uid is derived from (`ac_id`)
+ *    are removed. Natural rows carry `k`, their key with references as uids.
+ *    An unreadable capture is quarantined (`_sync_quarantine`, its table
+ *    suspect) and never stalls the outbox (T13036).
+ * 3. **Net (§2.4, {@link netTransaction}).** Per (table, uid) inside the
+ *    transaction. Across transactions, the dead incarnation of a row that
+ *    never got a uid (its captures up to its delete) is dropped whole
+ *    (T13036). A minted row with no uid or `birth_fp` keeps its group
+ *    pending, and nothing after it seals first (§2.9).
+ * 4. **HLC.** `tick(at_ms)` per op in order, at its last capture's time; the
+ *    transaction's HLC is its maximum.
+ * 5. **Write.** `_sync_txn`, `_sync_op`; `_sync_row_meta` upserted per op
+ *    (version, origin, actor, per-field `fhlc`, tombstone on D, key on
+ *    natural rows) and MOVED on K (hlc, fhlc, version and chash kept);
+ *    `chash` recomputed from the live row once no live capture of that row
+ *    remains; `_sync_ledger` per table; the `sealer.local_seq` counter.
+ * 6. **Consume.** Sealed, dropped and quarantined captures are deleted, and
+ *    frames no live capture references.
+ *
+ * S3c: timestamp columns are canonical on the wire and in `chash`
+ * ({@link canonicalStoreTimestamp}; local rows are never rewritten here), and
+ * a delete in an append-only table leaves no per-row tombstone (§1.7 R5-5).
+ * The step-0 fill and the repair diff of suspect tables are S3d. `sync.seal`
+ * stays unreleased until those land: the sealer refuses a persisted flag too.
+ *
+ * Phase B is synchronous: one `BEGIN IMMEDIATE` … `COMMIT` with no await, so
+ * a caller on the accessor's transaction queue serializes it with every
+ * writer on the handle.
+ *
+ * @module store/sync/sealer
+ * @task T12984
+ * @epic T12323
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { TableScope } from '@cleocode/contracts';
+import { type CaptureTableDef } from './capture.js';
+import { type WireValue } from './sealer-values.js';
+export { sealBacklog } from './seal-backlog.js';
+export { canonicalJson, decodeEnc, type WireValue } from './sealer-values.js';
+/** One sealed op (§2.6 `LedgerOp`, without the transaction-level fields). */
+export interface SealedOp {
+    readonly t: string;
+    /** Row uid; for K the OLD uid. */
+    readonly u: string;
+    readonly o: 'I' | 'U' | 'D' | 'K';
+    readonly h: string;
+    readonly nu?: string;
+    readonly bfp?: string;
+    readonly obfp?: string;
+    readonly k?: Record<string, WireValue>;
+    readonly a?: Record<string, WireValue>;
+    readonly b?: Record<string, WireValue>;
+}
+/** What one `sealPending` call did. */
+export interface SealReport {
+    readonly txns: number;
+    readonly ops: number;
+    readonly captures: number;
+    readonly unframed: number;
+    /** Groups left pending (a minted row without uid or birth_fp), by first seq. */
+    readonly pending: ReadonlyArray<{
+        readonly firstSeq: number;
+        readonly reason: string;
+    }>;
+    /** Captures of dead incarnations dropped whole (I … D of a row with no uid; T13036). */
+    readonly dropped: number;
+    /** Unreadable captures moved to `_sync_quarantine` (T13036). */
+    readonly quarantined: ReadonlyArray<{
+        readonly seq: number;
+        readonly tbl: string;
+        readonly reason: string;
+    }>;
+    /** Why nothing was sealed, when the preconditions refused. */
+    readonly refused: string | null;
+}
+/** Options for {@link sealPending}. */
+export interface SealOptions {
+    readonly scope: TableScope;
+    /**
+     * This store's replica id (the HLC's replica part, `origin`).
+     * @defaultValue the store's active replica (`_sync_replica`)
+     */
+    readonly replica?: string;
+    /** Most captures to consume; the batch still ends on a group boundary. @defaultValue 5000 */
+    readonly budget?: number;
+    /** Wall clock in ms. @defaultValue Date.now */
+    readonly now?: () => number;
+    /** Environment for the kill switch. @defaultValue process.env */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * Stop starting new groups after this long in one transaction, so a batch
+     * never holds the write lock for long (T13032). @defaultValue 200
+     */
+    readonly maxMs?: number;
+    /**
+     * Seal although `sync.seal` is unreleased (tests only; T13037). Never set
+     * from user input.
+     */
+    readonly allowUnreleased?: boolean;
+}
+/**
+ * sha256 of a row's canonical WIRE image (§2.7, M6; T13031): the values an I
+ * op of the row would carry, so every replica hashes identical bytes. Secret
+ * columns, uid and birth_fp, and a minted table's local key (a display id or
+ * an autoincrement id, which differ per replica) are left out; references are
+ * their uids; NULL columns are omitted, as in an I image; and timestamp
+ * columns hash their canonical form (§1.8), so a replica holding legacy text
+ * hashes like one that received the canonical value.
+ */
+export declare function rowChash(db: DatabaseSync, scope: TableScope, def: CaptureTableDef, uid: string): string | null;
+/**
+ * Why the sealer refuses to run, or `null` when it may. A persisted
+ * `sync.seal` is refused while the flag is unreleased (T13037), whatever
+ * wrote it.
+ */
+export declare function sealPreconditions(db: DatabaseSync, env: NodeJS.ProcessEnv, allowUnreleased?: boolean): string | null;
+/** Where the sealer's transaction counter is persisted (T13033). */
+export declare const SEAL_COUNTER_KEY = "sealer.local_seq";
+/**
+ * Seal up to `budget` live captures (ending on a group boundary) into
+ * transactions, in one synchronous `BEGIN IMMEDIATE` transaction.
+ *
+ * Groups seal strictly in capture order (§2.9): the first group that cannot
+ * seal yet (a row without uid or birth_fp, an unreadable capture) stops the
+ * batch, and is reported in `pending` until it can. Nothing after it gets an
+ * HLC first.
+ *
+ * @returns what was sealed, what stays pending, or why nothing ran.
+ */
+export declare function sealPending(db: DatabaseSync, opts: SealOptions): SealReport;
+//# sourceMappingURL=sealer.d.ts.map

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

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