@cleocode/core 2026.9.23 → 2026.9.25

package/dist/store/sync/replica.js

@@ -0,0 +1,305 @@
+/**
+ * Replica identity: binding a store file to its replica, and rebinding a
+ * copy (journal spec §1.5, H3, N5, N6).
+ *
+ * A replica is one physical store file, not a machine: a worktree copy or a
+ * restored file is a separate replica. The binding is
+ * `(st_ino, st_birthtime, nonce)` plus the stable device id and the device
+ * registry's high-water mark. `st_dev` is NOT used: external volumes, OS
+ * updates, overlay and network mounts renumber it.
+ *
+ * Birthtime (N5): a birthtime of 0, or one equal to the ctime at bind (the
+ * libuv fallback where the filesystem has no birthtime), is stored as NULL,
+ * and birthtimes are compared only when both are non-NULL.
+ *
+ * The open pass rebinds when:
+ * - `file-identity`: the inode differs, or both birthtimes are known and
+ *   differ (a copy, `VACUUM INTO` output, a restore to a new file);
+ * - `foreign-device`: the store was bound on another device;
+ * - `nonce-mismatch`: this device registered the replica id with another
+ *   nonce;
+ * - `rollback`: for some stream the store's persisted `replicaSeq` is below
+ *   the registry's hwm (a restore into the same inode, e.g. `.backup()`).
+ * A store missing from the registry is re-registered, never rebound for that
+ * alone (N6). The server's "seq exists, hash differs" answer is the authority
+ * behind that; S4 reports it through {@link rebindReplica}.
+ *
+ * A rebind retires the old row, mints a new replica id and nonce, carries the
+ * clock forward, and runs the registered {@link RebindHook}s in the same
+ * transaction. Marking inherited journal rows, discarding the pull cursor,
+ * pausing push, the reconcile and the signed retire transaction arrive with
+ * those tables (S4); they plug in as hooks.
+ *
+ * Everything here is behind the store-level `sync.*` flags: with every flag
+ * off, {@link syncOpenPass} reads and writes nothing.
+ *
+ * @task T12342
+ * @module store/sync/replica
+ */
+import { randomBytes } from 'node:crypto';
+import { realpathSync, statSync } from 'node:fs';
+import { uuidv7 } from '../../cloud/crypto.js';
+import { getStableDeviceId } from '../../llm/stable-device-id.js';
+import { healClock, loadClock, storeClock, withImmediateTransaction } from './clock-store.js';
+import { anySyncFlagOn } from './flags.js';
+import { encodeHlc } from './hlc.js';
+import { ReplicaRegistry } from './replica-registry.js';
+import { ensureSyncSchema, hasTable } from './schema.js';
+const rebindHooks = [];
+/**
+ * Register a hook that runs on every rebind.
+ *
+ * @returns A function that unregisters it.
+ */
+export function registerRebindHook(hook) {
+    rebindHooks.push(hook);
+    return () => {
+        const i = rebindHooks.indexOf(hook);
+        if (i >= 0)
+            rebindHooks.splice(i, 1);
+    };
+}
+/** `fs.statSync` in bigint mode. */
+export const defaultStat = (path) => {
+    const s = statSync(path, { bigint: true });
+    return { ino: s.ino, birthtimeNs: s.birthtimeNs, ctimeNs: s.ctimeNs };
+};
+/**
+ * The binding identity of a store file. A birthtime of 0 or equal to the
+ * ctime is the filesystem saying "unknown", so it reads as null (N5).
+ */
+export function fileIdentity(path, stat = defaultStat) {
+    const s = stat(path);
+    const birth = s.birthtimeNs === 0n || s.birthtimeNs === s.ctimeNs ? null : s.birthtimeNs;
+    return { ino: s.ino, birth };
+}
+function rowFrom(r) {
+    return {
+        replicaId: String(r.replica_id),
+        scope: r.scope,
+        nonce: String(r.nonce),
+        deviceId: String(r.device_id),
+        fileIno: BigInt(r.file_ino),
+        fileBirth: r.file_birth === null ? null : BigInt(r.file_birth),
+        boundAt: String(r.bound_at),
+        boundWhy: String(r.bound_why),
+        retiredAt: r.retired_at === null ? null : String(r.retired_at),
+        successor: r.successor === null ? null : String(r.successor),
+    };
+}
+/** The active (not retired) replica of a store, if bound. Read-only. */
+export function activeReplica(db, scope) {
+    if (!hasTable(db, '_sync_replica'))
+        return undefined;
+    const stmt = db.prepare('SELECT * FROM _sync_replica WHERE scope = ? AND retired_at IS NULL ORDER BY bound_at DESC LIMIT 1');
+    stmt.setReadBigInts(true);
+    const r = stmt.get(scope);
+    return r ? rowFrom(r) : undefined;
+}
+/** Every replica row of a store, oldest first. Read-only. */
+export function listReplicas(db) {
+    if (!hasTable(db, '_sync_replica'))
+        return [];
+    const stmt = db.prepare('SELECT * FROM _sync_replica ORDER BY bound_at, replica_id');
+    stmt.setReadBigInts(true);
+    return stmt.all().map(rowFrom);
+}
+const SEQ_PREFIX = 'seq:';
+/**
+ * The store-side high-water mark: the last `replicaSeq` this store persisted
+ * per stream for a replica. Read-only.
+ */
+export function storeHwm(db, replicaId) {
+    if (!hasTable(db, '_sync_meta'))
+        return {};
+    const prefix = `${SEQ_PREFIX}${replicaId}:`;
+    const rows = db
+        .prepare('SELECT key, value FROM _sync_meta WHERE key >= ? AND key < ?')
+        .all(prefix, `${prefix}￿`);
+    return Object.fromEntries(rows.map((r) => [r.key.slice(prefix.length), Number(r.value)]));
+}
+/**
+ * Record, in the caller's transaction, that a segment with `seq` was
+ * persisted for `stream`. S4 calls this in the segment-persist transaction,
+ * then {@link ReplicaRegistry.advanceHwm} after it commits. The value only
+ * moves up.
+ */
+export function persistStoreSeq(db, replicaId, stream, seq, now = new Date()) {
+    if (!db.isTransaction)
+        throw new Error('persistStoreSeq must run inside a transaction');
+    if (!Number.isSafeInteger(seq) || seq < 0)
+        throw new Error(`invalid replicaSeq ${seq}`);
+    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 ' +
+        'WHERE CAST(excluded.value AS INTEGER) > CAST(_sync_meta.value AS INTEGER)').run(`${SEQ_PREFIX}${replicaId}:${stream}`, String(seq), now.toISOString());
+}
+/**
+ * Why a bound store must rebind, if at all. Pure.
+ *
+ * @param row - The store's active replica row.
+ * @param identity - The file's identity now.
+ * @param deviceId - This device.
+ * @param entry - This device's registry entry for the replica, if any.
+ * @param hwm - The store-side hwm for the replica ({@link storeHwm}).
+ */
+export function rebindReasons(row, identity, deviceId, entry, hwm) {
+    const out = [];
+    const birthDiffers = row.fileBirth !== null && identity.birth !== null && row.fileBirth !== identity.birth;
+    if (row.fileIno !== identity.ino || birthDiffers)
+        out.push('file-identity');
+    if (row.deviceId !== deviceId)
+        out.push('foreign-device');
+    if (entry && entry.nonce !== row.nonce)
+        out.push('nonce-mismatch');
+    if (entry && Object.entries(entry.hwm).some(([stream, seq]) => (hwm[stream] ?? 0) < seq)) {
+        out.push('rollback');
+    }
+    return out;
+}
+function insertReplica(db, row) {
+    db.prepare('INSERT INTO _sync_replica (replica_id, scope, nonce, device_id, file_ino, file_birth, bound_at, bound_why) ' +
+        'VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(row.replicaId, row.scope, row.nonce, row.deviceId, row.fileIno, row.fileBirth, row.boundAt, row.boundWhy);
+}
+function mintRow(scope, identity, deviceId, why, now) {
+    return {
+        replicaId: uuidv7(now.getTime()),
+        scope,
+        nonce: randomBytes(16).toString('hex'),
+        deviceId,
+        fileIno: identity.ino,
+        fileBirth: identity.birth,
+        boundAt: now.toISOString(),
+        boundWhy: why,
+        retiredAt: null,
+        successor: null,
+    };
+}
+/**
+ * Retire `previous` and bind a new replica in its place, in the caller's
+ * transaction. The new replica's clock starts from the old one, so HLCs
+ * issued by this store keep increasing. Runs the rebind hooks.
+ */
+function rebindInTransaction(db, previous, identity, deviceId, reasons, now) {
+    const current = mintRow(previous.scope, identity, deviceId, `rebind:${reasons.join(',')}`, now);
+    db.prepare('UPDATE _sync_replica SET retired_at = ?, successor = ? WHERE replica_id = ?').run(now.toISOString(), current.replicaId, previous.replicaId);
+    insertReplica(db, current);
+    const old = healClock(db, previous.replicaId);
+    storeClock(db, { phys: old.phys, ctr: old.ctr, replica: current.replicaId });
+    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('rebind:last', JSON.stringify({ from: previous.replicaId, to: current.replicaId, reasons }), now.toISOString());
+    const retired = {
+        ...previous,
+        retiredAt: now.toISOString(),
+        successor: current.replicaId,
+    };
+    for (const hook of rebindHooks)
+        hook(db, { previous: retired, current, reasons });
+    return current;
+}
+function resolveContext(opts) {
+    if (opts.mode === 'test' && !opts.registry) {
+        throw new Error("sync open mode 'test' needs an explicit registry; it never uses the device's");
+    }
+    const deviceId = opts.deviceId ?? opts.registry?.deviceId ?? getStableDeviceId();
+    const registry = opts.registry ?? ReplicaRegistry.forDevice(deviceId);
+    if (registry.deviceId !== deviceId) {
+        throw new Error(`registry belongs to device ${registry.deviceId}, not ${deviceId}`);
+    }
+    return { deviceId, registry };
+}
+function register(registry, db, row, realpath, now) {
+    return registry.upsert(row.replicaId, { nonce: row.nonce, scope: row.scope, dbRealpath: realpath, hwm: storeHwm(db, row.replicaId) }, now);
+}
+/**
+ * The sync open pass for a canonical store open.
+ *
+ * With `mode: 'off'`, or with every `sync.*` flag off on the store, it reads
+ * nothing beyond the flags and writes nothing. Otherwise, under
+ * `BEGIN IMMEDIATE`: it binds an unbound store, rebinds a copy, a rolled-back
+ * or a foreign store, and heals the clock. Then it brings the device registry
+ * up to date (re-registering a store the registry lost, recording a rename).
+ *
+ * Not yet called by `openDualScopeDb`: the capture slice (S2) wires it in.
+ */
+export function syncOpenPass(db, opts) {
+    if (opts.mode === 'off')
+        return { status: 'off' };
+    if (!anySyncFlagOn(db))
+        return { status: 'disabled' };
+    const now = opts.now?.() ?? new Date();
+    const { deviceId, registry } = resolveContext(opts);
+    ensureSyncSchema(db, { root: opts.schemaRoot, now });
+    const identity = fileIdentity(opts.dbPath, opts.stat);
+    const realpath = realpathSync(opts.dbPath);
+    const known = registry.read().replicas;
+    const outcome = withImmediateTransaction(db, () => {
+        const row = activeReplica(db, opts.scope);
+        if (!row) {
+            const minted = mintRow(opts.scope, identity, deviceId, 'genesis', now);
+            insertReplica(db, minted);
+            healClock(db, minted.replicaId);
+            return { row: minted, previous: undefined, reasons: [] };
+        }
+        const entry = Object.hasOwn(known, row.replicaId) ? known[row.replicaId] : undefined;
+        const reasons = rebindReasons(row, identity, deviceId, entry, storeHwm(db, row.replicaId));
+        if (reasons.length === 0) {
+            healClock(db, row.replicaId);
+            return { row, previous: undefined, reasons };
+        }
+        const current = rebindInTransaction(db, row, identity, deviceId, reasons, now);
+        return { row: current, previous: row, reasons };
+    });
+    let registryWritten = false;
+    if (outcome.previous && Object.hasOwn(known, outcome.previous.replicaId)) {
+        const prev = known[outcome.previous.replicaId];
+        // Only the device's own registration of the retired replica is marked; a
+        // copy's original keeps its entry untouched when it lives elsewhere.
+        if (prev.dbRealpath === realpath) {
+            registryWritten =
+                registry.upsert(outcome.previous.replicaId, { ...prev, retiredAt: now.toISOString(), successor: outcome.row.replicaId }, now) || registryWritten;
+        }
+    }
+    registryWritten = register(registry, db, outcome.row, realpath, now) || registryWritten;
+    return {
+        status: outcome.previous ? 'rebound' : 'bound',
+        replicaId: outcome.row.replicaId,
+        ...(outcome.previous ? { previousReplicaId: outcome.previous.replicaId } : {}),
+        reasons: outcome.reasons,
+        registryWritten,
+    };
+}
+/**
+ * Force a rebind of a bound store: the hook S4 uses when the server answers a
+ * push with "seq exists, hash differs" (N6: the server hwm is authoritative).
+ *
+ * @throws {Error} When the store has no active replica.
+ */
+export function rebindReplica(db, opts, reason = 'server-seq-conflict') {
+    const now = opts.now?.() ?? new Date();
+    const { deviceId, registry } = resolveContext(opts);
+    const identity = fileIdentity(opts.dbPath, opts.stat);
+    const realpath = realpathSync(opts.dbPath);
+    const { previous, current } = withImmediateTransaction(db, () => {
+        const row = activeReplica(db, opts.scope);
+        if (!row)
+            throw new Error(`no active ${opts.scope} replica to rebind`);
+        return {
+            previous: row,
+            current: rebindInTransaction(db, row, identity, deviceId, [reason], now),
+        };
+    });
+    const prev = registry.get(previous.replicaId);
+    if (prev) {
+        registry.upsert(previous.replicaId, { ...prev, retiredAt: now.toISOString(), successor: current.replicaId }, now);
+    }
+    register(registry, db, current, realpath, now);
+    return { replicaId: current.replicaId, previousReplicaId: previous.replicaId };
+}
+/** The current clock of the store's active replica, for diagnostics. Read-only. */
+export function currentClock(db, scope) {
+    const row = activeReplica(db, scope);
+    if (!row || !hasTable(db, '_sync_clock'))
+        return undefined;
+    return encodeHlc(loadClock(db, row.replicaId));
+}
+//# sourceMappingURL=replica.js.map

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

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

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

@@ -0,0 +1,68 @@
+/**
+ * The change journal's own schema, applied lazily.
+ *
+ * The DDL lives in `packages/core/migrations/sync-journal/<folder>/migration.sql`,
+ * one folder per migration, like the drizzle lineages. It is NOT a drizzle
+ * lineage: it runs only when a `sync.*` flag is first enabled on a store
+ * ({@link ensureSyncSchema}), so a store with every flag off (the default)
+ * never gains a table or a journal row. Applied folders are recorded in
+ * `_sync_meta` under `schema:<folder>` with the sha256 of the folder's SQL,
+ * never in `__drizzle_migrations`. A folder whose SQL changed after it was
+ * applied is refused with {@link SyncSchemaHashDriftError}, never skipped.
+ *
+ * @task T12342
+ * @module store/sync/schema
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/** The migrations sub-directory that holds the sync schema. */
+export declare const SYNC_SCHEMA_SET = "sync-journal";
+/** One sync schema folder. */
+export interface SyncSchemaFolder {
+    readonly name: string;
+    readonly sql: string;
+    /** sha256 of `sql`, hex. */
+    readonly hash: string;
+}
+/**
+ * An applied sync schema folder whose SQL no longer matches what was applied
+ * (in the spirit of `E_MIGRATION_HASH_DRIFT`). Editing an applied folder is
+ * never correct: add a new folder instead.
+ */
+export declare class SyncSchemaHashDriftError extends Error {
+    readonly folder: string;
+    readonly applied: string;
+    readonly current: string;
+    readonly code = "E_SYNC_SCHEMA_HASH_DRIFT";
+    constructor(folder: string, applied: string, current: string);
+}
+/** Whether a table exists in the `main` schema. Read-only. */
+export declare function hasTable(db: DatabaseSync, table: string): boolean;
+/** The sync schema folders, oldest first. */
+export declare function syncSchemaFolders(root?: string): SyncSchemaFolder[];
+/**
+ * The schema folders already applied to this store, with the sha256 each was
+ * applied with. Read-only: a store with no `_sync_meta` has none.
+ */
+export declare function appliedSyncSchemaHashes(db: DatabaseSync): Map<string, string>;
+/** The names of the schema folders already applied to this store. Read-only. */
+export declare function appliedSyncSchema(db: DatabaseSync): string[];
+/**
+ * Apply every sync schema folder this store has not applied yet, in one
+ * transaction (a savepoint when the caller already holds one).
+ *
+ * The applied set is read again INSIDE the transaction, under the write
+ * lock, so two processes enabling a flag at once apply each folder once.
+ *
+ * @param db - The store handle.
+ * @param options - `root` overrides the schema folder (tests); `now` stamps
+ *   the journal rows; `beforeLock` runs between the unlocked pre-check and
+ *   taking the lock (a test seam for the two-process race).
+ * @returns The folders applied by this call.
+ * @throws {SyncSchemaHashDriftError} When an applied folder's SQL changed.
+ */
+export declare function ensureSyncSchema(db: DatabaseSync, options?: {
+    root?: string;
+    now?: Date;
+    beforeLock?: () => void;
+}): string[];
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/store/sync/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,+DAA+D;AAC/D,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAK9C,8BAA8B;AAC9B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAI/C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM;IAL1B,QAAQ,CAAC,IAAI,8BAA8B;gBAGhC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM;CAQ3B;AAID,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKjE;AAED,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,MAA4D,GACjE,gBAAgB,EAAE,CAYpB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7E;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,YAAY,GAAG,MAAM,EAAE,CAE5D;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,YAAY,EAChB,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;CAAO,GACnE,MAAM,EAAE,CAuBV"}

package/dist/store/sync/schema.js

@@ -0,0 +1,130 @@
+/**
+ * The change journal's own schema, applied lazily.
+ *
+ * The DDL lives in `packages/core/migrations/sync-journal/<folder>/migration.sql`,
+ * one folder per migration, like the drizzle lineages. It is NOT a drizzle
+ * lineage: it runs only when a `sync.*` flag is first enabled on a store
+ * ({@link ensureSyncSchema}), so a store with every flag off (the default)
+ * never gains a table or a journal row. Applied folders are recorded in
+ * `_sync_meta` under `schema:<folder>` with the sha256 of the folder's SQL,
+ * never in `__drizzle_migrations`. A folder whose SQL changed after it was
+ * applied is refused with {@link SyncSchemaHashDriftError}, never skipped.
+ *
+ * @task T12342
+ * @module store/sync/schema
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveCorePackageMigrationsFolder } from '../resolve-migrations-folder.js';
+/** The migrations sub-directory that holds the sync schema. */
+export const SYNC_SCHEMA_SET = 'sync-journal';
+/** Key prefix under which `_sync_meta` records an applied schema folder. */
+const APPLIED_PREFIX = 'schema:';
+/**
+ * An applied sync schema folder whose SQL no longer matches what was applied
+ * (in the spirit of `E_MIGRATION_HASH_DRIFT`). Editing an applied folder is
+ * never correct: add a new folder instead.
+ */
+export class SyncSchemaHashDriftError extends Error {
+    folder;
+    applied;
+    current;
+    code = 'E_SYNC_SCHEMA_HASH_DRIFT';
+    constructor(folder, applied, current) {
+        super(`sync schema folder ${folder} was applied with sha256 ${applied}, but its SQL now hashes ` +
+            `to ${current}. An applied folder must never change; add a new folder instead.`);
+        this.folder = folder;
+        this.applied = applied;
+        this.current = current;
+        this.name = 'SyncSchemaHashDriftError';
+    }
+}
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/** Whether a table exists in the `main` schema. Read-only. */
+export function hasTable(db, table) {
+    return (db.prepare("SELECT 1 FROM main.sqlite_master WHERE type = 'table' AND name = ?").get(table) !==
+        undefined);
+}
+/** The sync schema folders, oldest first. */
+export function syncSchemaFolders(root = resolveCorePackageMigrationsFolder(SYNC_SCHEMA_SET)) {
+    if (!existsSync(root)) {
+        throw new Error(`sync schema folder not found: ${root}`);
+    }
+    return readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && existsSync(join(root, d.name, 'migration.sql')))
+        .map((d) => d.name)
+        .sort()
+        .map((name) => {
+        const sql = readFileSync(join(root, name, 'migration.sql'), 'utf8');
+        return { name, sql, hash: sha256(sql) };
+    });
+}
+/**
+ * The schema folders already applied to this store, with the sha256 each was
+ * applied with. Read-only: a store with no `_sync_meta` has none.
+ */
+export function appliedSyncSchemaHashes(db) {
+    if (!hasTable(db, '_sync_meta'))
+        return new Map();
+    const rows = db
+        .prepare('SELECT key, value FROM _sync_meta WHERE key LIKE ? ORDER BY key')
+        .all(`${APPLIED_PREFIX}%`);
+    return new Map(rows.map((r) => [r.key.slice(APPLIED_PREFIX.length), r.value]));
+}
+/** The names of the schema folders already applied to this store. Read-only. */
+export function appliedSyncSchema(db) {
+    return [...appliedSyncSchemaHashes(db).keys()];
+}
+/**
+ * The folders still to apply, after checking every applied one for drift.
+ *
+ * @throws {SyncSchemaHashDriftError} When an applied folder's SQL changed.
+ */
+function pending(folders, applied) {
+    for (const f of folders) {
+        const was = applied.get(f.name);
+        if (was !== undefined && was !== f.hash)
+            throw new SyncSchemaHashDriftError(f.name, was, f.hash);
+    }
+    return folders.filter((f) => !applied.has(f.name));
+}
+/**
+ * Apply every sync schema folder this store has not applied yet, in one
+ * transaction (a savepoint when the caller already holds one).
+ *
+ * The applied set is read again INSIDE the transaction, under the write
+ * lock, so two processes enabling a flag at once apply each folder once.
+ *
+ * @param db - The store handle.
+ * @param options - `root` overrides the schema folder (tests); `now` stamps
+ *   the journal rows; `beforeLock` runs between the unlocked pre-check and
+ *   taking the lock (a test seam for the two-process race).
+ * @returns The folders applied by this call.
+ * @throws {SyncSchemaHashDriftError} When an applied folder's SQL changed.
+ */
+export function ensureSyncSchema(db, options = {}) {
+    const folders = syncSchemaFolders(options.root);
+    // Unlocked pre-check: the common case (all applied) takes no write lock.
+    if (pending(folders, appliedSyncSchemaHashes(db)).length === 0)
+        return [];
+    options.beforeLock?.();
+    const stamp = (options.now ?? new Date()).toISOString();
+    const nested = db.isTransaction;
+    db.exec(nested ? 'SAVEPOINT sync_schema' : 'BEGIN IMMEDIATE');
+    try {
+        const todo = pending(folders, appliedSyncSchemaHashes(db));
+        for (const f of todo) {
+            db.exec(f.sql);
+            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(`${APPLIED_PREFIX}${f.name}`, f.hash, stamp);
+        }
+        db.exec(nested ? 'RELEASE sync_schema' : 'COMMIT');
+        return todo.map((f) => f.name);
+    }
+    catch (err) {
+        db.exec(nested ? 'ROLLBACK TO sync_schema; RELEASE sync_schema' : 'ROLLBACK');
+        throw err;
+    }
+}
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/store/sync/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,kCAAkC,EAAE,MAAM,iCAAiC,CAAC;AAErF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAE9C,4EAA4E;AAC5E,MAAM,cAAc,GAAG,SAAS,CAAC;AAUjC;;;;GAIG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAItC;IACA;IACA;IALF,IAAI,GAAG,0BAA0B,CAAC;IAE3C,YACW,MAAc,EACd,OAAe,EACf,OAAe;QAExB,KAAK,CACH,sBAAsB,MAAM,4BAA4B,OAAO,2BAA2B;YACxF,MAAM,OAAO,kEAAkE,CAClF,CAAC;QAPO,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAQ;QACf,YAAO,GAAP,OAAO,CAAQ;QAMxB,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAEzF,8DAA8D;AAC9D,MAAM,UAAU,QAAQ,CAAC,EAAgB,EAAE,KAAa;IACtD,OAAO,CACL,EAAE,CAAC,OAAO,CAAC,oEAAoE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;QAC3F,SAAS,CACV,CAAC;AACJ,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,iBAAiB,CAC/B,OAAe,kCAAkC,CAAC,eAAe,CAAC;IAElE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SAC9C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC;SACjF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;QACpE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,EAAgB;IACtD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAClD,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CAAC,iEAAiE,CAAC;SAC1E,GAAG,CAAC,GAAG,cAAc,GAAG,CAA0C,CAAC;IACtE,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB,CAAC,EAAgB;IAChD,OAAO,CAAC,GAAG,uBAAuB,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,SAAS,OAAO,CAAC,OAAoC,EAAE,OAA4B;IACjF,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI;YACrC,MAAM,IAAI,wBAAwB,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,EAAgB,EAChB,UAAkE,EAAE;IAEpE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,yEAAyE;IACzE,IAAI,OAAO,CAAC,OAAO,EAAE,uBAAuB,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1E,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;IACvB,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACxD,MAAM,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC;IAChC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,uBAAuB,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3D,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACf,EAAE,CAAC,OAAO,CACR,mEAAmE;gBACjE,yFAAyF,CAC5F,CAAC,GAAG,CAAC,GAAG,cAAc,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;QACD,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,8CAA8C,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QAC9E,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/store/sync/skew-hold.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The per-replica FIFO skew hold (journal spec §1.3, M2).
+ *
+ * A received transaction whose HLC is more than the skew bound ahead of the
+ * local wall clock is held: not applied, and it does not advance the clock.
+ * Every later transaction from the SAME origin replica is held behind it, in
+ * `(replicaSeq, index)` order, even when its own HLC is in bounds, so that
+ * replica's causal order is preserved. Other replicas keep flowing. The held
+ * head is re-evaluated on every drain, and the queue releases in order once
+ * the head is within bounds. Nothing is ever dropped.
+ *
+ * This is the in-memory ordering core. Staging the held transactions durably
+ * (`held-skew`) and reporting them through `cleo doctor sync` belong to the
+ * pull slice (S5).
+ *
+ * @task T12342
+ * @module store/sync/skew-hold
+ */
+/** One received transaction, as far as ordering is concerned. */
+export interface InboundTxn {
+    /** Origin replica id. */
+    readonly replica: string;
+    /** The origin's gap-free segment sequence number. */
+    readonly replicaSeq: number;
+    /** Position of the transaction inside its segment. */
+    readonly index: number;
+    /** The transaction's HLC (its largest op HLC), encoded. */
+    readonly hlc: string;
+}
+/** A replica whose queue is blocked by an out-of-bound head. */
+export interface HeldReplica {
+    readonly replica: string;
+    /** The transaction that is too far ahead. */
+    readonly head: InboundTxn;
+    /** How many transactions wait, the head included. */
+    readonly waiting: number;
+    /** How far the head is ahead of the local wall clock, in ms. */
+    readonly aheadMs: number;
+}
+/**
+ * Per-replica FIFO queues that release transactions in origin order and hold
+ * a replica's whole queue behind an out-of-bound head.
+ */
+export declare class SkewHold {
+    private readonly maxDriftMs;
+    private readonly queues;
+    /**
+     * @param maxDriftMs - The skew bound; defaults to {@link MAX_DRIFT_MS}.
+     */
+    constructor(maxDriftMs?: number);
+    /**
+     * Queue a received transaction behind earlier ones from the same replica.
+     * A transaction the queue already holds (same replica, seq and index) is
+     * ignored, so a re-pull is idempotent.
+     */
+    offer(txn: InboundTxn): void;
+    /**
+     * Release every transaction that may apply now, in per-replica order, and
+     * report the replicas that stay held.
+     *
+     * @param nowMs - The local wall clock.
+     * @returns `ready` (to apply, grouped by replica in origin order) and `held`.
+     */
+    drain(nowMs: number): {
+        ready: InboundTxn[];
+        held: HeldReplica[];
+    };
+    /** How many transactions are queued, over all replicas. */
+    get size(): number;
+}
+//# sourceMappingURL=skew-hold.d.ts.map

package/dist/store/sync/skew-hold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skew-hold.d.ts","sourceRoot":"","sources":["../../../src/store/sync/skew-hold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAOD;;;GAGG;AACH,qBAAa,QAAQ;IAMP,OAAO,CAAC,QAAQ,CAAC,UAAU;IALvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D;;OAEG;gBAC0B,UAAU,GAAE,MAAqB;IAE9D;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI;IAY5B;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,IAAI,EAAE,WAAW,EAAE,CAAA;KAAE;IAmBlE,2DAA2D;IAC3D,IAAI,IAAI,IAAI,MAAM,CAIjB;CACF"}