@cleocode/core 2026.9.23 → 2026.9.25

package/dist/store/sync/hlc.js

@@ -0,0 +1,172 @@
+/**
+ * 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
+ */
+/** The largest counter the 6-digit field can hold. */
+export const MAX_COUNTER = 999_999;
+/** The largest physical time the 13-digit field can hold (year 2286). */
+export const MAX_PHYS = 9_999_999_999_999;
+/**
+ * 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 const MAX_DRIFT_MS = 5 * 60 * 1000;
+const HLC_RE = /^(\d{13})-(\d{6})-([0-9a-f-]{36})$/;
+const REPLICA_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** Thrown for a malformed HLC, replica id or physical time. */
+export class HlcError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HlcError';
+    }
+}
+function assertParts(phys, ctr, replica) {
+    if (!Number.isSafeInteger(phys) || phys < 0 || phys > MAX_PHYS) {
+        throw new HlcError(`HLC physical time out of range: ${phys}`);
+    }
+    if (!Number.isSafeInteger(ctr) || ctr < 0 || ctr > MAX_COUNTER) {
+        throw new HlcError(`HLC counter out of range: ${ctr}`);
+    }
+    if (!REPLICA_RE.test(replica)) {
+        throw new HlcError(`HLC replica id is not a lowercase UUID: ${replica}`);
+    }
+}
+/**
+ * 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 function encodeHlc(h) {
+    assertParts(h.phys, h.ctr, h.replica);
+    return `${String(h.phys).padStart(13, '0')}-${String(h.ctr).padStart(6, '0')}-${h.replica}`;
+}
+/**
+ * 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 function parseHlc(s) {
+    const m = HLC_RE.exec(s);
+    if (!m)
+        throw new HlcError(`not an encoded HLC: ${s}`);
+    const h = { phys: Number(m[1]), ctr: Number(m[2]), replica: m[3] };
+    assertParts(h.phys, h.ctr, h.replica);
+    return h;
+}
+/**
+ * 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 function compareHlc(a, b) {
+    if (a.phys !== b.phys)
+        return a.phys < b.phys ? -1 : 1;
+    if (a.ctr !== b.ctr)
+        return a.ctr < b.ctr ? -1 : 1;
+    if (a.replica === b.replica)
+        return 0;
+    return a.replica < b.replica ? -1 : 1;
+}
+/**
+ * The clock of a replica that has issued nothing yet.
+ *
+ * @param replica - The replica id.
+ */
+export function genesisHlc(replica) {
+    assertParts(0, 0, replica);
+    return { phys: 0, ctr: 0, replica };
+}
+/** Carry a counter overflow into the physical part. */
+function carry(phys, ctr, replica) {
+    if (ctr > MAX_COUNTER)
+        return { phys: phys + 1, ctr: 0, replica };
+    return { phys, ctr, replica };
+}
+/**
+ * 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 function tick(last, wallMs) {
+    const wall = Math.floor(wallMs);
+    assertParts(Math.max(0, wall), 0, last.replica);
+    const phys = Math.max(last.phys, wall);
+    const ctr = phys === last.phys ? last.ctr + 1 : 0;
+    return carry(phys, ctr, last.replica);
+}
+/**
+ * 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 function receive(last, remote, nowMs) {
+    const now = Math.floor(nowMs);
+    const phys = Math.max(last.phys, remote.phys, now);
+    let ctr;
+    if (phys === last.phys && phys === remote.phys)
+        ctr = Math.max(last.ctr, remote.ctr) + 1;
+    else if (phys === last.phys)
+        ctr = last.ctr + 1;
+    else if (phys === remote.phys)
+        ctr = remote.ctr + 1;
+    else
+        ctr = 0;
+    return carry(phys, ctr, last.replica);
+}
+/**
+ * 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 function isWithinSkew(remote, nowMs, maxDriftMs = MAX_DRIFT_MS) {
+    return remote.phys <= Math.floor(nowMs) + maxDriftMs;
+}
+/**
+ * The larger of two HLCs (by {@link compareHlc}).
+ */
+export function maxHlc(a, b) {
+    return compareHlc(a, b) >= 0 ? a : b;
+}
+//# sourceMappingURL=hlc.js.map

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

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

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

@@ -0,0 +1,20 @@
+/**
+ * The change journal's foundation (T12342, slice S1): the hybrid logical
+ * clock, its persisted row, the store-level `sync.*` flags, the lazily
+ * applied sync schema, replica binding and the device replica registry.
+ *
+ * Nothing here runs on a hot path yet, and every write is behind a flag that
+ * is off by default. Capture (S2), sealing (S3), push (S4) and pull (S5)
+ * build on these modules.
+ *
+ * @task T12342
+ * @module store/sync
+ */
+export * from './clock-store.js';
+export * from './flags.js';
+export * from './hlc.js';
+export * from './replica.js';
+export * from './replica-registry.js';
+export * from './schema.js';
+export * from './skew-hold.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/store/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/store/sync/index.js

@@ -0,0 +1,20 @@
+/**
+ * The change journal's foundation (T12342, slice S1): the hybrid logical
+ * clock, its persisted row, the store-level `sync.*` flags, the lazily
+ * applied sync schema, replica binding and the device replica registry.
+ *
+ * Nothing here runs on a hot path yet, and every write is behind a flag that
+ * is off by default. Capture (S2), sealing (S3), push (S4) and pull (S5)
+ * build on these modules.
+ *
+ * @task T12342
+ * @module store/sync
+ */
+export * from './clock-store.js';
+export * from './flags.js';
+export * from './hlc.js';
+export * from './replica.js';
+export * from './replica-registry.js';
+export * from './schema.js';
+export * from './skew-hold.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/store/sync/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC"}

package/dist/store/sync/replica-registry.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The device's replica registry (journal spec §1.5, N6).
+ *
+ * A JSON file of device state, never inside a store and never synced: its
+ * path comes from `@cleocode/paths` ({@link resolveSyncReplicaRegistryPath}),
+ * in the machine-local state dir, keyed by the stable device id. Per replica
+ * id it records the store's nonce, where the store lives, and the device-side
+ * high-water mark (`hwm`): the last `replicaSeq` this device persisted per
+ * stream. A store whose own persisted sequence is BELOW the hwm was rolled
+ * back (restored into the same file), which the open pass turns into a
+ * rebind.
+ *
+ * Losing the file (a new device, a wiped state dir) or finding it unreadable
+ * is treated as an empty registry: the open pass re-registers the store and
+ * does not rebind for that alone. The server's sequence check (S4) is the
+ * authority that catches what a lost registry cannot.
+ *
+ * Writes use the file-then-rename pattern, so a crash leaves the old or the
+ * new file, never a torn one.
+ *
+ * @task T12342
+ * @module store/sync/replica-registry
+ */
+/** One replica this device has bound. */
+export interface ReplicaRegistryEntry {
+    /** The nonce minted with the replica and stored in its `_sync_replica` row. */
+    readonly nonce: string;
+    /** `project` or `global`. */
+    readonly scope: string;
+    /** Real path of the store file when last opened here. */
+    readonly dbRealpath: string;
+    /** Last persisted `replicaSeq` per stream. */
+    readonly hwm: Readonly<Record<string, number>>;
+    /** When this replica was retired on this device, if it was. */
+    readonly retiredAt?: string;
+    /** The replica that replaced it. */
+    readonly successor?: string;
+    readonly updatedAt: string;
+}
+/** The registry file. */
+export interface ReplicaRegistryFile {
+    readonly version: 1;
+    readonly deviceId: string;
+    readonly replicas: Readonly<Record<string, ReplicaRegistryEntry>>;
+}
+/** Reads and writes one device's registry file. */
+export declare class ReplicaRegistry {
+    readonly path: string;
+    readonly deviceId: string;
+    /**
+     * @param path - The registry file.
+     * @param deviceId - The device the file belongs to.
+     */
+    constructor(path: string, deviceId: string);
+    /** The registry at its canonical path for `deviceId`. */
+    static forDevice(deviceId: string): ReplicaRegistry;
+    private empty;
+    /**
+     * The registry contents. A missing, unreadable or foreign file (another
+     * device id) reads as empty.
+     */
+    read(): ReplicaRegistryFile;
+    /** One replica's entry, if registered. */
+    get(replicaId: string): ReplicaRegistryEntry | undefined;
+    /** Replace the whole file (file-then-rename). */
+    write(file: ReplicaRegistryFile): void;
+    /**
+     * Insert or update one replica's entry. The hwm only moves up.
+     *
+     * @returns Whether the file changed.
+     */
+    upsert(replicaId: string, patch: Omit<ReplicaRegistryEntry, 'updatedAt' | 'hwm'> & {
+        hwm?: Readonly<Record<string, number>>;
+    }, now?: Date): boolean;
+    /**
+     * Advance a replica's hwm for one stream after a segment persist committed
+     * (S4 calls this right after the store transaction, §2.8). If the process
+     * dies in between, the store is ahead of the registry, which is the safe
+     * direction: only a store BEHIND the registry rebinds.
+     *
+     * @returns Whether the file changed.
+     */
+    advanceHwm(replicaId: string, stream: string, seq: number, now?: Date): boolean;
+}
+//# sourceMappingURL=replica-registry.d.ts.map

package/dist/store/sync/replica-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica-registry.d.ts","sourceRoot":"","sources":["../../../src/store/sync/replica-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,yBAAyB;AACzB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CACnE;AAED,mDAAmD;AACnD,qBAAa,eAAe;IAMxB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAN3B;;;OAGG;gBAEQ,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM;IAG3B,yDAAyD;IACzD,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe;IAInD,OAAO,CAAC,KAAK;IAIb;;;OAGG;IACH,IAAI,IAAI,mBAAmB;IAuB3B,0CAA0C;IAC1C,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAKxD,iDAAiD;IACjD,KAAK,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI;IAYtC;;;;OAIG;IACH,MAAM,CACJ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,CAAC,oBAAoB,EAAE,WAAW,GAAG,KAAK,CAAC,GAAG;QACvD,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KACxC,EACD,GAAG,GAAE,IAAiB,GACrB,OAAO;IAwBV;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO;CAO5F"}

package/dist/store/sync/replica-registry.js

@@ -0,0 +1,147 @@
+/**
+ * The device's replica registry (journal spec §1.5, N6).
+ *
+ * A JSON file of device state, never inside a store and never synced: its
+ * path comes from `@cleocode/paths` ({@link resolveSyncReplicaRegistryPath}),
+ * in the machine-local state dir, keyed by the stable device id. Per replica
+ * id it records the store's nonce, where the store lives, and the device-side
+ * high-water mark (`hwm`): the last `replicaSeq` this device persisted per
+ * stream. A store whose own persisted sequence is BELOW the hwm was rolled
+ * back (restored into the same file), which the open pass turns into a
+ * rebind.
+ *
+ * Losing the file (a new device, a wiped state dir) or finding it unreadable
+ * is treated as an empty registry: the open pass re-registers the store and
+ * does not rebind for that alone. The server's sequence check (S4) is the
+ * authority that catches what a lost registry cannot.
+ *
+ * Writes use the file-then-rename pattern, so a crash leaves the old or the
+ * new file, never a torn one.
+ *
+ * @task T12342
+ * @module store/sync/replica-registry
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { resolveSyncReplicaRegistryPath } from '@cleocode/paths';
+/** Reads and writes one device's registry file. */
+export class ReplicaRegistry {
+    path;
+    deviceId;
+    /**
+     * @param path - The registry file.
+     * @param deviceId - The device the file belongs to.
+     */
+    constructor(path, deviceId) {
+        this.path = path;
+        this.deviceId = deviceId;
+    }
+    /** The registry at its canonical path for `deviceId`. */
+    static forDevice(deviceId) {
+        return new ReplicaRegistry(resolveSyncReplicaRegistryPath(deviceId), deviceId);
+    }
+    empty() {
+        return { version: 1, deviceId: this.deviceId, replicas: {} };
+    }
+    /**
+     * The registry contents. A missing, unreadable or foreign file (another
+     * device id) reads as empty.
+     */
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(this.path, 'utf8');
+        }
+        catch {
+            return this.empty();
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.version !== 1 ||
+                parsed.deviceId !== this.deviceId ||
+                typeof parsed.replicas !== 'object' ||
+                parsed.replicas === null) {
+                return this.empty();
+            }
+            return { version: 1, deviceId: this.deviceId, replicas: parsed.replicas };
+        }
+        catch {
+            return this.empty();
+        }
+    }
+    /** One replica's entry, if registered. */
+    get(replicaId) {
+        const replicas = this.read().replicas;
+        return Object.hasOwn(replicas, replicaId) ? replicas[replicaId] : undefined;
+    }
+    /** Replace the whole file (file-then-rename). */
+    write(file) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+        try {
+            writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+            renameSync(tmp, this.path);
+        }
+        catch (err) {
+            rmSync(tmp, { force: true });
+            throw err;
+        }
+    }
+    /**
+     * Insert or update one replica's entry. The hwm only moves up.
+     *
+     * @returns Whether the file changed.
+     */
+    upsert(replicaId, patch, now = new Date()) {
+        const file = this.read();
+        const prev = Object.hasOwn(file.replicas, replicaId) ? file.replicas[replicaId] : undefined;
+        const hwm = { ...(prev?.hwm ?? {}) };
+        for (const [stream, seq] of Object.entries(patch.hwm ?? {})) {
+            hwm[stream] = Math.max(hwm[stream] ?? 0, seq);
+        }
+        const next = {
+            nonce: patch.nonce,
+            scope: patch.scope,
+            dbRealpath: patch.dbRealpath,
+            hwm,
+            ...(patch.retiredAt !== undefined ? { retiredAt: patch.retiredAt } : {}),
+            ...(patch.successor !== undefined ? { successor: patch.successor } : {}),
+            updatedAt: prev?.updatedAt ?? now.toISOString(),
+        };
+        if (prev && sameEntry(prev, next))
+            return false;
+        this.write({
+            ...file,
+            replicas: { ...file.replicas, [replicaId]: { ...next, updatedAt: now.toISOString() } },
+        });
+        return true;
+    }
+    /**
+     * Advance a replica's hwm for one stream after a segment persist committed
+     * (S4 calls this right after the store transaction, §2.8). If the process
+     * dies in between, the store is ahead of the registry, which is the safe
+     * direction: only a store BEHIND the registry rebinds.
+     *
+     * @returns Whether the file changed.
+     */
+    advanceHwm(replicaId, stream, seq, now = new Date()) {
+        const prev = this.get(replicaId);
+        if (!prev) {
+            throw new Error(`replica ${replicaId} is not registered on device ${this.deviceId}`);
+        }
+        return this.upsert(replicaId, { ...prev, hwm: { [stream]: seq } }, now);
+    }
+}
+function sameEntry(a, b) {
+    const keys = new Set([...Object.keys(a.hwm), ...Object.keys(b.hwm)]);
+    for (const k of keys)
+        if (a.hwm[k] !== b.hwm[k])
+            return false;
+    return (a.nonce === b.nonce &&
+        a.scope === b.scope &&
+        a.dbRealpath === b.dbRealpath &&
+        a.retiredAt === b.retiredAt &&
+        a.successor === b.successor);
+}
+//# sourceMappingURL=replica-registry.js.map

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

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

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

@@ -0,0 +1,181 @@
+/**
+ * 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 type { DatabaseSync } from 'node:sqlite';
+import { ReplicaRegistry, type ReplicaRegistryEntry } from './replica-registry.js';
+/** Which store a replica is. */
+export type ReplicaScope = 'project' | 'global';
+/**
+ * How an open treats sync (§1.5). `off` for every non-canonical open
+ * (backups, snapshots, scratch copies, bundle staging): nothing is read or
+ * written. `live` for the canonical project and global stores. `test` for a
+ * scratch-bound replica that must never touch the device registry: the
+ * caller passes its own registry.
+ */
+export type SyncOpenMode = 'off' | 'live' | 'test';
+/** Why a store was rebound. */
+export type RebindReason = 'file-identity' | 'foreign-device' | 'nonce-mismatch' | 'rollback' | 'server-seq-conflict';
+/** What `stat` reports about a store file, in nanoseconds. */
+export interface FileStat {
+    readonly ino: bigint;
+    readonly birthtimeNs: bigint;
+    readonly ctimeNs: bigint;
+}
+/** Reads a file's stat. Injectable so tests can simulate filesystems. */
+export type StatFn = (path: string) => FileStat;
+/** The part of a file's identity the binding compares. */
+export interface FileIdentity {
+    readonly ino: bigint;
+    /** Birthtime in ns, or null when unknown (N5). */
+    readonly birth: bigint | null;
+}
+/** A `_sync_replica` row. */
+export interface ReplicaRow {
+    readonly replicaId: string;
+    readonly scope: ReplicaScope;
+    readonly nonce: string;
+    readonly deviceId: string;
+    readonly fileIno: bigint;
+    readonly fileBirth: bigint | null;
+    readonly boundAt: string;
+    readonly boundWhy: string;
+    readonly retiredAt: string | null;
+    readonly successor: string | null;
+}
+/** Context handed to a {@link RebindHook}. */
+export interface RebindContext {
+    readonly previous: ReplicaRow;
+    readonly current: ReplicaRow;
+    readonly reasons: readonly RebindReason[];
+}
+/**
+ * Runs inside the rebind transaction, after the new replica is bound. S4
+ * registers the hooks that mark inherited rows, discard the cursor and pause
+ * push. A throw rolls the whole rebind back.
+ */
+export type RebindHook = (db: DatabaseSync, ctx: RebindContext) => void;
+/**
+ * Register a hook that runs on every rebind.
+ *
+ * @returns A function that unregisters it.
+ */
+export declare function registerRebindHook(hook: RebindHook): () => void;
+/** `fs.statSync` in bigint mode. */
+export declare const defaultStat: StatFn;
+/**
+ * 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 declare function fileIdentity(path: string, stat?: StatFn): FileIdentity;
+/** The active (not retired) replica of a store, if bound. Read-only. */
+export declare function activeReplica(db: DatabaseSync, scope: ReplicaScope): ReplicaRow | undefined;
+/** Every replica row of a store, oldest first. Read-only. */
+export declare function listReplicas(db: DatabaseSync): ReplicaRow[];
+/**
+ * The store-side high-water mark: the last `replicaSeq` this store persisted
+ * per stream for a replica. Read-only.
+ */
+export declare function storeHwm(db: DatabaseSync, replicaId: string): Record<string, number>;
+/**
+ * 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 declare function persistStoreSeq(db: DatabaseSync, replicaId: string, stream: string, seq: number, now?: Date): void;
+/**
+ * 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 declare function rebindReasons(row: ReplicaRow, identity: FileIdentity, deviceId: string, entry: ReplicaRegistryEntry | undefined, hwm: Readonly<Record<string, number>>): RebindReason[];
+/** Options for {@link syncOpenPass} and {@link rebindReplica}. */
+export interface SyncOpenOptions {
+    /** Path of the store file the handle has open. */
+    readonly dbPath: string;
+    readonly scope: ReplicaScope;
+    readonly mode: SyncOpenMode;
+    /** This device. Defaults to `getStableDeviceId()` (live mode only). */
+    readonly deviceId?: string;
+    /** The device registry. Required in `test` mode; defaults to the device's in `live` mode. */
+    readonly registry?: ReplicaRegistry;
+    readonly stat?: StatFn;
+    readonly now?: () => Date;
+    /** Sync schema folder override (tests). */
+    readonly schemaRoot?: string;
+}
+/** What an open pass did. */
+export type SyncOpenResult = {
+    readonly status: 'off' | 'disabled';
+} | {
+    readonly status: 'bound' | 'rebound';
+    readonly replicaId: string;
+    readonly previousReplicaId?: string;
+    readonly reasons: readonly RebindReason[];
+    /** Whether the device registry file was written. */
+    readonly registryWritten: boolean;
+};
+/**
+ * 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 declare function syncOpenPass(db: DatabaseSync, opts: SyncOpenOptions): SyncOpenResult;
+/**
+ * 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 declare function rebindReplica(db: DatabaseSync, opts: SyncOpenOptions, reason?: RebindReason): {
+    replicaId: string;
+    previousReplicaId: string;
+};
+/** The current clock of the store's active replica, for diagnostics. Read-only. */
+export declare function currentClock(db: DatabaseSync, scope: ReplicaScope): string | undefined;
+//# sourceMappingURL=replica.d.ts.map

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

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