@cleocode/core 2026.9.23 → 2026.9.25

package/dist/store/store-write-guard.js

@@ -16,18 +16,31 @@ import { resolveDualScopeDbPath } from './dual-scope-db.js';
 import { getDb, getNativeDb } from './sqlite.js';
 import { twinCollapseError, twinCollapseFailureOf } from './twin-collapse.js';
 /**
- * The `E_TWIN_COLLAPSE_FAILED` error that blocks writes to this project's
- * store, or `null` when writes may proceed.
+ * Which dispatch domains write each collapsed pair (`'*'`: every mutation).
+ * A failed pair blocks only its writers: a docs merge failure never stops
+ * `cleo add` or `cleo complete`. Writers outside these domains (a memory
+ * observation with attachment refs, a changeset) are still refused at the
+ * accessor entry (`assertTwinCollapseWritable`).
+ */
+const WRITE_SCOPE = {
+    schema_meta: '*',
+    sticky_tags: ['sticky'],
+    attachments: ['docs'],
+};
+/**
+ * The `E_TWIN_COLLAPSE_FAILED` error that blocks this write to the project's
+ * store, or `null` when it may proceed.
  *
  * Binds the tasks domain first (which runs the collapse), so the answer is
  * current. A project without a store, or one whose bind fails for another
  * reason, is not blocked here: the operation then fails, or not, on its own.
  *
  * @param projectRoot - Project directory.
+ * @param request - The operation; omitted, any failed pair blocks.
  * @returns The blocking error, or `null`.
  * @task T12535
  */
-export async function storeWriteBlock(projectRoot) {
+export async function storeWriteBlock(projectRoot, request) {
     let dbPath;
     try {
         dbPath = resolveDualScopeDbPath('project', projectRoot);
@@ -45,6 +58,14 @@ export async function storeWriteBlock(projectRoot) {
     }
     const native = getNativeDb(projectRoot);
     const failure = native ? twinCollapseFailureOf(native) : undefined;
-    return failure ? twinCollapseError(failure) : null;
+    if (!failure)
+        return null;
+    if (request === undefined)
+        return twinCollapseError(failure);
+    const blocks = failure.tables.some((table) => {
+        const scope = WRITE_SCOPE[table] ?? '*';
+        return scope === '*' || scope.includes(request.domain);
+    });
+    return blocks ? twinCollapseError(failure) : null;
 }
 //# sourceMappingURL=store-write-guard.js.map

package/dist/store/store-write-guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-write-guard.js","sourceRoot":"","sources":["../../src/store/store-write-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,WAAmB;IACvD,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,OAAO,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC"}
+{"version":3,"file":"store-write-guard.js","sourceRoot":"","sources":["../../src/store/store-write-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,GAAsD;IACrE,WAAW,EAAE,GAAG;IAChB,WAAW,EAAE,CAAC,QAAQ,CAAC;IACvB,WAAW,EAAE,CAAC,MAAM,CAAC;CACtB,CAAC;AAQF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,WAAmB,EACnB,OAA2B;IAE3B,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,sBAAsB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;QACxC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC"}

package/dist/store/sync/clock-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The persisted HLC clock (journal spec §1.4).
+ *
+ * `_sync_clock(replica_id, phys, ctr)` is local-only. It is read and written
+ * only inside the caller's `BEGIN IMMEDIATE` transaction (every seal and every
+ * apply), so two processes serialize on the SQLite write lock and no clock
+ * state lives in process memory across transactions.
+ *
+ * @task T12342
+ * @module store/sync/clock-store
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import { type Hlc } from './hlc.js';
+/**
+ * Journal tables whose `hlc` column can hold this replica's timestamps. The
+ * clock heals to their maximum on open, which covers a store restored from a
+ * copy taken between a seal and its clock write. They arrive with the sealer
+ * (S3); a missing table is skipped.
+ */
+export declare const CLOCK_HEAL_SOURCES: ReadonlyArray<{
+    table: string;
+    column: string;
+}>;
+/**
+ * The stored clock of a replica, or its genesis when none is stored.
+ */
+export declare function loadClock(db: DatabaseSync, replica: string): Hlc;
+/** Store a clock value. Caller holds the transaction. */
+export declare function storeClock(db: DatabaseSync, h: Hlc): void;
+/**
+ * Issue the next local HLC and persist the clock. Caller holds the
+ * transaction.
+ *
+ * @param wallMs - The physical candidate (§1.2).
+ * @returns The issued timestamp, encoded.
+ */
+export declare function tickClock(db: DatabaseSync, replica: string, wallMs: number): string;
+/**
+ * Merge a received HLC into the persisted clock, unless it is beyond the skew
+ * bound: then nothing is written and the caller must hold the transaction
+ * (see `SkewHold`). Caller holds the transaction.
+ *
+ * @returns `{ held: false, clock }` after a merge, `{ held: true }` otherwise.
+ */
+export declare function receiveClock(db: DatabaseSync, replica: string, remote: string, nowMs: number, maxDriftMs?: number): {
+    held: false;
+    clock: string;
+} | {
+    held: true;
+};
+/**
+ * Heal a replica's clock to the largest HLC it is known to have issued: the
+ * stored clock, or the maximum of {@link CLOCK_HEAL_SOURCES}. Caller holds
+ * the transaction.
+ *
+ * @returns The healed clock.
+ */
+export declare function healClock(db: DatabaseSync, replica: string, sources?: ReadonlyArray<{
+    table: string;
+    column: string;
+}>): Hlc;
+/**
+ * Run `fn` inside `BEGIN IMMEDIATE`, committing on return and rolling back
+ * on a throw. The clock primitives above require such a transaction.
+ */
+export declare function withImmediateTransaction<T>(db: DatabaseSync, fn: () => T): T;
+//# sourceMappingURL=clock-store.d.ts.map

package/dist/store/sync/clock-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-store.d.ts","sourceRoot":"","sources":["../../../src/store/sync/clock-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAGL,KAAK,GAAG,EAOT,MAAM,UAAU,CAAC;AAGlB;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAG/E,CAAC;AAWF;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAKhE;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,GAAG,GAAG,IAAI,CAMzD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKnF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,UAAU,GAAE,MAAqB,GAChC;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAOjD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAa,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAsB,GAC7E,GAAG,CAgBL;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAU5E"}

package/dist/store/sync/clock-store.js

@@ -0,0 +1,117 @@
+/**
+ * The persisted HLC clock (journal spec §1.4).
+ *
+ * `_sync_clock(replica_id, phys, ctr)` is local-only. It is read and written
+ * only inside the caller's `BEGIN IMMEDIATE` transaction (every seal and every
+ * apply), so two processes serialize on the SQLite write lock and no clock
+ * state lives in process memory across transactions.
+ *
+ * @task T12342
+ * @module store/sync/clock-store
+ */
+import { encodeHlc, genesisHlc, isWithinSkew, MAX_DRIFT_MS, maxHlc, parseHlc, receive, tick, } from './hlc.js';
+import { hasTable } from './schema.js';
+/**
+ * Journal tables whose `hlc` column can hold this replica's timestamps. The
+ * clock heals to their maximum on open, which covers a store restored from a
+ * copy taken between a seal and its clock write. They arrive with the sealer
+ * (S3); a missing table is skipped.
+ */
+export const CLOCK_HEAL_SOURCES = [
+    { table: '_sync_op', column: 'hlc' },
+    { table: '_sync_row_meta', column: 'hlc' },
+];
+/** Offset of the replica id inside an encoded HLC (13 + 1 + 6 + 1). */
+const REPLICA_OFFSET = 21;
+function assertInTransaction(db, what) {
+    if (!db.isTransaction) {
+        throw new Error(`${what} must run inside the caller's BEGIN IMMEDIATE transaction`);
+    }
+}
+/**
+ * The stored clock of a replica, or its genesis when none is stored.
+ */
+export function loadClock(db, replica) {
+    const row = db.prepare('SELECT phys, ctr FROM _sync_clock WHERE replica_id = ?').get(replica);
+    return row ? { phys: row.phys, ctr: row.ctr, replica } : genesisHlc(replica);
+}
+/** Store a clock value. Caller holds the transaction. */
+export function storeClock(db, h) {
+    assertInTransaction(db, 'storeClock');
+    db.prepare('INSERT INTO _sync_clock (replica_id, phys, ctr) VALUES (?, ?, ?) ' +
+        'ON CONFLICT(replica_id) DO UPDATE SET phys = excluded.phys, ctr = excluded.ctr').run(h.replica, h.phys, h.ctr);
+}
+/**
+ * Issue the next local HLC and persist the clock. Caller holds the
+ * transaction.
+ *
+ * @param wallMs - The physical candidate (§1.2).
+ * @returns The issued timestamp, encoded.
+ */
+export function tickClock(db, replica, wallMs) {
+    assertInTransaction(db, 'tickClock');
+    const next = tick(loadClock(db, replica), wallMs);
+    storeClock(db, next);
+    return encodeHlc(next);
+}
+/**
+ * Merge a received HLC into the persisted clock, unless it is beyond the skew
+ * bound: then nothing is written and the caller must hold the transaction
+ * (see `SkewHold`). Caller holds the transaction.
+ *
+ * @returns `{ held: false, clock }` after a merge, `{ held: true }` otherwise.
+ */
+export function receiveClock(db, replica, remote, nowMs, maxDriftMs = MAX_DRIFT_MS) {
+    assertInTransaction(db, 'receiveClock');
+    const r = parseHlc(remote);
+    if (!isWithinSkew(r, nowMs, maxDriftMs))
+        return { held: true };
+    const next = receive(loadClock(db, replica), r, nowMs);
+    storeClock(db, next);
+    return { held: false, clock: encodeHlc(next) };
+}
+/**
+ * Heal a replica's clock to the largest HLC it is known to have issued: the
+ * stored clock, or the maximum of {@link CLOCK_HEAL_SOURCES}. Caller holds
+ * the transaction.
+ *
+ * @returns The healed clock.
+ */
+export function healClock(db, replica, sources = CLOCK_HEAL_SOURCES) {
+    assertInTransaction(db, 'healClock');
+    let best = loadClock(db, replica);
+    for (const { table, column } of sources) {
+        if (!/^[a-z_][a-z0-9_]*$/.test(table) || !/^[a-z_][a-z0-9_]*$/.test(column)) {
+            throw new Error(`invalid clock heal source ${table}.${column}`);
+        }
+        if (!hasTable(db, table))
+            continue;
+        const row = db
+            .prepare(`SELECT MAX(${column}) AS h FROM ${table} WHERE substr(${column}, ?) = ?`)
+            .get(REPLICA_OFFSET + 1, replica);
+        if (row?.h)
+            best = maxHlc(best, { ...parseHlc(row.h), replica });
+    }
+    const stored = loadClock(db, replica);
+    if (best.phys !== stored.phys || best.ctr !== stored.ctr)
+        storeClock(db, best);
+    return best;
+}
+/**
+ * Run `fn` inside `BEGIN IMMEDIATE`, committing on return and rolling back
+ * on a throw. The clock primitives above require such a transaction.
+ */
+export function withImmediateTransaction(db, fn) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const out = fn();
+        db.exec('COMMIT');
+        return out;
+    }
+    catch (err) {
+        if (db.isTransaction)
+            db.exec('ROLLBACK');
+        throw err;
+    }
+}
+//# sourceMappingURL=clock-store.js.map

package/dist/store/sync/clock-store.js.map

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

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

@@ -0,0 +1,51 @@
+/**
+ * Store-level `sync.*` flags (journal spec §5.1, Q8).
+ *
+ * Each flag is persisted per store in `_sync_meta` and is OFF by default. A
+ * store that never enabled one has no `_sync_meta` at all, and reading the
+ * flags never writes, so an all-off store is left byte-for-byte untouched.
+ *
+ * `CLEO_SYNC_<FLAG>=0` (for example `CLEO_SYNC_PUSH=0`) stops that flag's
+ * behaviour in the current process. It never turns a flag on, and it never
+ * installs or drops anything (M3).
+ *
+ * @task T12342
+ * @module store/sync/flags
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** The journal's flags, in slice order. */
+export declare const SYNC_FLAGS: readonly ["sync.capture", "sync.seal", "sync.push", "sync.pull", "sync.strict"];
+/** One journal flag. */
+export type SyncFlag = (typeof SYNC_FLAGS)[number];
+/** Every flag's persisted state. */
+export type SyncFlagState = Readonly<Record<SyncFlag, boolean>>;
+/** The environment kill switch for a flag: `sync.push` → `CLEO_SYNC_PUSH`. */
+export declare function killSwitchVar(flag: SyncFlag): string;
+/**
+ * The persisted flags of a store. Read-only; all off when the store has no
+ * `_sync_meta`.
+ */
+export declare function readSyncFlags(db: DatabaseSync): SyncFlagState;
+/** Whether any flag is persisted on (the kill switches do not count). */
+export declare function anySyncFlagOn(db: DatabaseSync): boolean;
+/**
+ * Whether a flag's behaviour runs in this process: persisted on, and not
+ * stopped by its kill switch.
+ *
+ * @param env - The environment to read the kill switch from.
+ */
+export declare function isSyncFlagOn(db: DatabaseSync, flag: SyncFlag, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Persist a flag. Turning one on first applies the sync schema; turning one
+ * off on a store without the schema writes nothing.
+ *
+ * Prerequisite checks (`cleo sync enable <flag>`) live with the slice that
+ * gives the flag its behaviour; this is the storage primitive.
+ *
+ * @returns Whether the stored value changed.
+ */
+export declare function setSyncFlag(db: DatabaseSync, flag: SyncFlag, on: boolean, options?: {
+    now?: Date;
+    schemaRoot?: string;
+}): boolean;
+//# sourceMappingURL=flags.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../../src/store/sync/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,2CAA2C;AAC3C,eAAO,MAAM,UAAU,iFAMb,CAAC;AAEX,wBAAwB;AACxB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAMhE,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,aAAa,CAU7D;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,QAAQ,EACd,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,YAAY,EAChB,IAAI,EAAE,QAAQ,EACd,EAAE,EAAE,OAAO,EACX,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAWT"}

package/dist/store/sync/flags.js

@@ -0,0 +1,81 @@
+/**
+ * Store-level `sync.*` flags (journal spec §5.1, Q8).
+ *
+ * Each flag is persisted per store in `_sync_meta` and is OFF by default. A
+ * store that never enabled one has no `_sync_meta` at all, and reading the
+ * flags never writes, so an all-off store is left byte-for-byte untouched.
+ *
+ * `CLEO_SYNC_<FLAG>=0` (for example `CLEO_SYNC_PUSH=0`) stops that flag's
+ * behaviour in the current process. It never turns a flag on, and it never
+ * installs or drops anything (M3).
+ *
+ * @task T12342
+ * @module store/sync/flags
+ */
+import { ensureSyncSchema, hasTable } from './schema.js';
+/** The journal's flags, in slice order. */
+export const SYNC_FLAGS = [
+    'sync.capture',
+    'sync.seal',
+    'sync.push',
+    'sync.pull',
+    'sync.strict',
+];
+const ALL_OFF = Object.freeze(Object.fromEntries(SYNC_FLAGS.map((f) => [f, false])));
+/** The environment kill switch for a flag: `sync.push` → `CLEO_SYNC_PUSH`. */
+export function killSwitchVar(flag) {
+    return `CLEO_SYNC_${flag.slice('sync.'.length).toUpperCase()}`;
+}
+/**
+ * The persisted flags of a store. Read-only; all off when the store has no
+ * `_sync_meta`.
+ */
+export function readSyncFlags(db) {
+    if (!hasTable(db, '_sync_meta'))
+        return ALL_OFF;
+    const rows = db
+        .prepare(`SELECT key, value FROM _sync_meta WHERE key IN (${SYNC_FLAGS.map(() => '?').join(', ')})`)
+        .all(...SYNC_FLAGS);
+    const out = { ...ALL_OFF };
+    for (const r of rows)
+        out[r.key] = r.value === '1';
+    return out;
+}
+/** Whether any flag is persisted on (the kill switches do not count). */
+export function anySyncFlagOn(db) {
+    return Object.values(readSyncFlags(db)).some(Boolean);
+}
+/**
+ * Whether a flag's behaviour runs in this process: persisted on, and not
+ * stopped by its kill switch.
+ *
+ * @param env - The environment to read the kill switch from.
+ */
+export function isSyncFlagOn(db, flag, env = process.env) {
+    if (env[killSwitchVar(flag)] === '0')
+        return false;
+    return readSyncFlags(db)[flag];
+}
+/**
+ * Persist a flag. Turning one on first applies the sync schema; turning one
+ * off on a store without the schema writes nothing.
+ *
+ * Prerequisite checks (`cleo sync enable <flag>`) live with the slice that
+ * gives the flag its behaviour; this is the storage primitive.
+ *
+ * @returns Whether the stored value changed.
+ */
+export function setSyncFlag(db, flag, on, options = {}) {
+    if (!SYNC_FLAGS.includes(flag))
+        throw new Error(`unknown sync flag: ${flag}`);
+    if (!on && !hasTable(db, '_sync_meta'))
+        return false;
+    if (readSyncFlags(db)[flag] === on)
+        return false;
+    ensureSyncSchema(db, { root: options.schemaRoot, now: options.now });
+    const stamp = (options.now ?? new Date()).toISOString();
+    db.prepare('INSERT INTO _sync_meta (key, value, updated_at) VALUES (?, ?, ?) ' +
+        'ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at').run(flag, on ? '1' : '0', stamp);
+    return true;
+}
+//# sourceMappingURL=flags.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flags.js","sourceRoot":"","sources":["../../../src/store/sync/flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEzD,2CAA2C;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,cAAc;IACd,WAAW;IACX,WAAW;IACX,WAAW;IACX,aAAa;CACL,CAAC;AAQX,MAAM,OAAO,GAAkB,MAAM,CAAC,MAAM,CAC1C,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAA8B,CACnF,CAAC;AAEF,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,OAAO,aAAa,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAAgB;IAC5C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;QAAE,OAAO,OAAO,CAAC;IAChD,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN,mDAAmD,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3F;SACA,GAAG,CAAC,GAAG,UAAU,CAA4C,CAAC;IACjE,MAAM,GAAG,GAA8B,EAAE,GAAG,OAAO,EAAE,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC;IACnD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,EAAgB;IAC5C,OAAO,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,EAAgB,EAChB,IAAc,EACd,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,aAAa,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CACzB,EAAgB,EAChB,IAAc,EACd,EAAW,EACX,UAA+C,EAAE;IAEjD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;IAC9E,IAAI,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,aAAa,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACjD,gBAAgB,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,EAAE,CAAC,OAAO,CACR,mEAAmE;QACjE,yFAAyF,CAC5F,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}

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

@@ -0,0 +1,115 @@
+/**
+ * Hybrid logical clock (HLC) for the change journal.
+ *
+ * Wire format (fixed by the cloud contract, `Hlc` in `@cleocode/contracts`):
+ * `PPPPPPPPPPPPP-CCCCCC-<replica uuid>`, where `P` is physical milliseconds
+ * since the Unix epoch zero-padded to 13 digits, `C` is the logical counter
+ * zero-padded to 6 digits, and the replica id is the lowercase UUIDv7 of the
+ * store that issued the timestamp. Tuple order `(phys, ctr, replica)` is
+ * exactly the lexical order of the encoded string, so SQL `ORDER BY hlc` and
+ * `MAX(hlc)` are correct.
+ *
+ * This module is pure. The persisted clock row lives in `clock-store.ts`.
+ *
+ * It never reads time from a uid (journal spec R7, T12341 §5.2): a backfilled
+ * uid's timestamp is the row's birth, or 0, not the time of a change. The
+ * module therefore imports nothing, and a test pins that.
+ *
+ * @task T12342
+ * @module store/sync/hlc
+ */
+/** A decoded HLC. */
+export interface Hlc {
+    /** Physical milliseconds since the Unix epoch. */
+    readonly phys: number;
+    /** Logical counter, 0 to {@link MAX_COUNTER}. */
+    readonly ctr: number;
+    /** Lowercase UUID of the issuing replica. */
+    readonly replica: string;
+}
+/** The largest counter the 6-digit field can hold. */
+export declare const MAX_COUNTER = 999999;
+/** The largest physical time the 13-digit field can hold (year 2286). */
+export declare const MAX_PHYS = 9999999999999;
+/**
+ * Default skew bound: a received HLC more than this far ahead of the local
+ * wall clock is held, never applied or dropped (journal spec §1.3, Q6).
+ */
+export declare const MAX_DRIFT_MS: number;
+/** Thrown for a malformed HLC, replica id or physical time. */
+export declare class HlcError extends Error {
+    constructor(message: string);
+}
+/**
+ * Encode an HLC to its wire form.
+ *
+ * @param h - The clock value.
+ * @returns `PPPPPPPPPPPPP-CCCCCC-<replica>`.
+ * @throws {HlcError} When a part is out of range or the replica id is malformed.
+ */
+export declare function encodeHlc(h: Hlc): string;
+/**
+ * Decode an HLC from its wire form.
+ *
+ * @param s - An encoded HLC.
+ * @returns The decoded parts.
+ * @throws {HlcError} When `s` is not an encoded HLC.
+ */
+export declare function parseHlc(s: string): Hlc;
+/**
+ * Total order on HLCs: `(phys, ctr, replica)`. The replica tiebreak is
+ * arbitrary but deterministic, so every replica orders identically.
+ *
+ * @returns Negative, zero or positive, like a sort comparator.
+ */
+export declare function compareHlc(a: Hlc, b: Hlc): number;
+/**
+ * The clock of a replica that has issued nothing yet.
+ *
+ * @param replica - The replica id.
+ */
+export declare function genesisHlc(replica: string): Hlc;
+/**
+ * Issue the next local HLC.
+ *
+ * `phys' = max(last.phys, wall)`; the counter increments when the physical
+ * part did not move and resets to 0 when it did; a counter past
+ * {@link MAX_COUNTER} carries into `phys`. HLCs therefore increase strictly
+ * per replica, even when the wall clock steps backwards or a batch issues
+ * 10^6 timestamps in one millisecond.
+ *
+ * @param last - The replica's current clock.
+ * @param wallMs - The physical candidate (a capture's `at_ms`, or `Date.now()`).
+ * @returns The new clock value, which is also the issued timestamp.
+ */
+export declare function tick(last: Hlc, wallMs: number): Hlc;
+/**
+ * Merge a received HLC into the local clock (standard HLC receive rule).
+ *
+ * `phys' = max(last.phys, remote.phys, now)`. The counter is
+ * `max(last.ctr, remote.ctr) + 1` when all three agree, `last.ctr + 1` or
+ * `remote.ctr + 1` when `phys'` equals only that one, and 0 otherwise. The
+ * result keeps the LOCAL replica id.
+ *
+ * Callers apply the skew bound first ({@link isWithinSkew}): a remote HLC too
+ * far ahead must be held, never merged.
+ *
+ * @param last - The local clock.
+ * @param remote - The received timestamp.
+ * @param nowMs - The local wall clock.
+ * @returns The new local clock value.
+ */
+export declare function receive(last: Hlc, remote: Hlc, nowMs: number): Hlc;
+/**
+ * Whether a received HLC is inside the skew bound: `phys <= now + maxDrift`.
+ *
+ * @param remote - The received timestamp.
+ * @param nowMs - The local wall clock.
+ * @param maxDriftMs - The bound; defaults to {@link MAX_DRIFT_MS}.
+ */
+export declare function isWithinSkew(remote: Hlc, nowMs: number, maxDriftMs?: number): boolean;
+/**
+ * The larger of two HLCs (by {@link compareHlc}).
+ */
+export declare function maxHlc(a: Hlc, b: Hlc): Hlc;
+//# sourceMappingURL=hlc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","sourceRoot":"","sources":["../../../src/store/sync/hlc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,qBAAqB;AACrB,MAAM,WAAW,GAAG;IAClB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sDAAsD;AACtD,eAAO,MAAM,WAAW,SAAU,CAAC;AAEnC,yEAAyE;AACzE,eAAO,MAAM,QAAQ,gBAAoB,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAgB,CAAC;AAK1C,+DAA+D;AAC/D,qBAAa,QAAS,SAAQ,KAAK;gBACrB,OAAO,EAAE,MAAM;CAI5B;AAcD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAGxC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAMvC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAKjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAG/C;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAMnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,CASlE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,SAAe,GAAG,OAAO,CAE3F;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,GAAG,CAE1C"}