@omgbase/core 0.1.0 → 0.2.0

package/dist/src/sync/driver.d.ts

@@ -1,12 +1,19 @@
 import type { Store } from "../core/store/store.js";
 import type { SyncSource } from "./plugin.js";
-import type { FileChange, CheckpointResult } from "./checkpoint.js";
+import { type FileChange, type CheckpointResult } from "./checkpoint.js";
 export type { FileChange, CheckpointResult };
 /**
  * Reconcile a batch of changed members against a repo as one checkpoint.
  * `source.fetch(path)` supplies current bytes (or null = left the scope). The
  * engine hashes the bytes itself: a hash equal to the stored file_hash is an
- * echo (no commit); otherwise the member is ingested as an observed commit.
+ * echo (no commit); otherwise the member is ingested as an observed commit; a
+ * member that left the scope tombstones its live doc (drop FTS, tombstone
+ * blocks + doc, pool blocks) so it stops being served. Every member is fetched
+ * first, then the whole batch goes through `observeBatch` — the one
+ * implementation of echo gate + identity threading + conflict flagging (D2),
+ * including the cross-document move phase over the batch — so a live watcher
+ * batch that cuts a block from one member and pastes it into another keeps the
+ * id. (v1 sources are identity-inferred; borne identity is deferred, ADR-010/D4.)
  */
 export declare function reconcileChanges(store: Store, repoId: string, source: SyncSource, changes: FileChange[], opts?: {
     ts?: string;
@@ -20,6 +27,10 @@ export interface AttachResult {
 /**
  * Attach a source scope as a repo: create/reuse the repo row, then ingest every
  * member the source enumerates (identity-inferred sources thread the reconciling
- * resolver so edges + identity are established on the initial walk).
+ * resolver so edges + identity are established on the initial walk; a `borne`
+ * source takes the plain re-minting ingest — spec/sync §9). `opts.ts` pins the
+ * commit timestamp (default now).
  */
-export declare function attachSource(store: Store, slug: string, rootPath: string | null, source: SyncSource): Promise<AttachResult>;
+export declare function attachSource(store: Store, slug: string, rootPath: string | null, source: SyncSource, opts?: {
+    ts?: string;
+}): Promise<AttachResult>;

package/dist/src/sync/driver.js

@@ -1,66 +1,41 @@
-import { mintId } from "../core/ids.js";
 import { ingestFile } from "../core/ingest.js";
 import { ensureRepo } from "../core/attach.js";
 import { makeReconcilingResolver } from "./reconciling-ingest.js";
-import { observeOne } from "./observe.js";
-import { sweepResurrectionPool } from "../core/store/gc.js";
-import { tombstoneObservedDeletion } from "./tombstone.js";
+import { observeBatch } from "./observe.js";
+import { finishCheckpoint } from "./checkpoint.js";
 /**
  * Reconcile a batch of changed members against a repo as one checkpoint.
  * `source.fetch(path)` supplies current bytes (or null = left the scope). The
  * engine hashes the bytes itself: a hash equal to the stored file_hash is an
- * echo (no commit); otherwise the member is ingested as an observed commit.
+ * echo (no commit); otherwise the member is ingested as an observed commit; a
+ * member that left the scope tombstones its live doc (drop FTS, tombstone
+ * blocks + doc, pool blocks) so it stops being served. Every member is fetched
+ * first, then the whole batch goes through `observeBatch` — the one
+ * implementation of echo gate + identity threading + conflict flagging (D2),
+ * including the cross-document move phase over the batch — so a live watcher
+ * batch that cuts a block from one member and pastes it into another keeps the
+ * id. (v1 sources are identity-inferred; borne identity is deferred, ADR-010/D4.)
  */
 export async function reconcileChanges(store, repoId, source, changes, opts = {}) {
     const ts = opts.ts ?? new Date().toISOString();
-    const checkpointId = mintId("cp");
-    const ingested = [];
-    const suppressed = [];
-    const deleted = [];
-    const conflicted = [];
-    const fileEntries = [];
+    const items = [];
     for (const change of changes) {
         const item = await source.fetch(change.path);
-        if (item === null) {
-            // Member left the source scope (deleted/moved out): tombstone the live doc
-            // (drop FTS, tombstone blocks + doc, pool blocks) so it stops being served.
-            const existing = store.db
-                .prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
-                .get(repoId, change.path);
-            if (existing) {
-                tombstoneObservedDeletion(store, repoId, existing.doc_id, ts);
-                deleted.push(change.path);
-            }
-            fileEntries.push([change.path, existing?.file_hash?.toString("hex") ?? null, null]);
-            continue;
-        }
-        // Reconcile the fetched bytes through the shared observe primitive — the one
-        // implementation of echo gate + identity threading + conflict flagging (D2).
-        // (v1 sources are identity-inferred; borne identity is deferred, ADR-010/D4.)
-        const r = observeOne(store, repoId, change.path, item.content, ts);
-        if (r.echo)
-            suppressed.push(change.path);
-        else if (r.conflicted)
-            conflicted.push(change.path);
-        else
-            ingested.push(change.path);
-        fileEntries.push([change.path, r.oldHashHex, r.newHashHex]);
+        items.push({ path: change.path, content: item === null ? null : item.content });
     }
-    store.db
-        .prepare("INSERT INTO checkpoints (id, repo_id, ts, files, git_head) VALUES (?, ?, ?, ?, ?)")
-        .run(checkpointId, repoId, ts, JSON.stringify(fileEntries), opts.gitHead ?? null);
-    sweepResurrectionPool(store, ts);
-    return { checkpointId, ingested, suppressed, deleted, conflicted };
+    return finishCheckpoint(store, repoId, observeBatch(store, repoId, items, ts), { ts, gitHead: opts.gitHead ?? null });
 }
 /**
  * Attach a source scope as a repo: create/reuse the repo row, then ingest every
  * member the source enumerates (identity-inferred sources thread the reconciling
- * resolver so edges + identity are established on the initial walk).
+ * resolver so edges + identity are established on the initial walk; a `borne`
+ * source takes the plain re-minting ingest — spec/sync §9). `opts.ts` pins the
+ * commit timestamp (default now).
  */
-export async function attachSource(store, slug, rootPath, source) {
+export async function attachSource(store, slug, rootPath, source, opts = {}) {
     const repoId = ensureRepo(store, slug, rootPath);
     const inferred = source.capabilities().identity === "inferred";
-    const ts = new Date().toISOString();
+    const ts = opts.ts ?? new Date().toISOString();
     let fileCount = 0;
     let allConverged = true;
     for (const entry of await source.enumerate()) {

package/dist/src/sync/external-source.js

@@ -22,11 +22,14 @@ export async function createExternalSource(spec) {
         child.once("error", (err) => reject(new Error(`sync adapter '${spec.command}' failed to spawn: ${err.message}`)));
         child.once("exit", (code) => reject(new Error(`sync adapter '${spec.command}' exited early (code ${code ?? "?"})`)));
     });
-    // Handshake: the first line declares protocol + capabilities.
+    // Handshake: the first line declares protocol + capabilities. A missing or
+    // non-1 `protocol` is as invalid as a line that does not parse (spec/sync §5).
     const handshakeRaw = await Promise.race([router.nextResponse(), died]);
     let caps;
     try {
         const hs = JSON.parse(handshakeRaw);
+        if (hs.protocol !== 1)
+            throw new Error("protocol");
         const c = hs.capabilities ?? {};
         caps = {
             identity: c.identity === "borne" ? "borne" : "inferred",
@@ -35,6 +38,9 @@ export async function createExternalSource(spec) {
         };
     }
     catch {
+        rl.close();
+        child.stdin.end();
+        child.kill("SIGTERM");
         throw new Error(`sync adapter '${spec.command}' sent an invalid handshake: ${handshakeRaw.slice(0, 120)}`);
     }
     let nextId = 1;

package/dist/src/sync/freshness.d.ts

@@ -1,18 +1,66 @@
 import type { Store } from "../core/store/store.js";
 import { type CheckpointResult } from "./checkpoint.js";
+import { type FileStat, type SyncFs } from "./fs-util.js";
+/** One `file_stats` row (spec/sync §4.3 "the repo's cache rows"). */
+export interface StatCacheRow {
+    path: string;
+    mtime_ns: bigint;
+    size: number;
+    hash: Buffer;
+}
+/** One walked file in the current snapshot; `hash()` reads and hashes its bytes on demand (memoized). */
+export interface SnapshotEntry {
+    path: string;
+    mtime_ns: bigint;
+    size: number;
+    hash: () => Buffer;
+}
+/**
+ * The §4.3 decisions over a cache and a snapshot:
+ * - `candidates`: snapshot paths not in the cache or whose `(mtime_ns, size)` differs (snapshot order);
+ * - `deletions`: cached paths not in the snapshot (cache order);
+ * - `changed`: candidates whose bytes' hash differs from the cached hash, or that have no cache row;
+ * - `refreshed`: candidates whose hash equals the cached one (a touch without an edit — the
+ *   cache's stat is refreshed, nothing is ingested);
+ * - `hashes`: the hash computed for every candidate (the sweep records them).
+ */
+export interface SweepPlan {
+    candidates: string[];
+    changed: string[];
+    deletions: string[];
+    refreshed: string[];
+    hashes: Map<string, Buffer>;
+}
+/** Step 1 of §4.3 alone: the stat-mismatched or new paths, without hashing anything. */
+export declare function sweepCandidates(cache: ReadonlyMap<string, StatCacheRow>, snapshot: readonly SnapshotEntry[]): string[];
+/** spec/sync §4.3 steps 1–2 as a pure function (README §8 `sweep_plan`). */
+export declare function sweepPlan(cache: ReadonlyMap<string, StatCacheRow>, snapshot: readonly SnapshotEntry[]): SweepPlan;
+/** The repo's `file_stats` rows keyed by path. Read with safe integers: an `mtime_ns` is a
+ *  64-bit count a JS number cannot hold exactly, and a rounded value would never equal a stat. */
+export declare function loadStatCache(store: Store, repoId: string): Map<string, StatCacheRow>;
+/** The current filesystem snapshot: the §4.2 walk with each file's stat and a lazy hash. */
+export declare function snapshotOf(fs: SyncFs, rootPath: string): SnapshotEntry[];
 export interface SweepResult extends CheckpointResult {
     scanned: number;
     candidates: number;
     changed: boolean;
 }
-/** Record/refresh a file's stat cache row. Call after any ingest of the file. */
+/** Write a file's stat cache row from a stat (`INSERT … ON CONFLICT DO UPDATE`); a null stat (the
+ *  file vanished) deletes the row. The DB half of `record_file_stat` (spec/sync §4.3 step 4). */
+export declare function recordStat(store: Store, repoId: string, path: string, st: FileStat | null, hash: Buffer): void;
+/** Record/refresh a file's stat cache row from its absolute path. Call after any ingest of the file. */
 export declare function recordFileStat(store: Store, repoId: string, path: string, abs: string, hash: Buffer): void;
 /**
- * Run the freshness sweep for a repo. Returns the checkpoint result plus scan
- * counters. Idempotent; safe alongside a live watcher (hash-based echo
- * suppression makes a double ingest a no-op).
+ * Run the freshness sweep for a repo (spec/sync §4.3). Returns the checkpoint
+ * result plus scan counters. Idempotent; safe alongside a live watcher
+ * (hash-based echo suppression makes a double ingest a no-op). `opts.ts` pins
+ * the batch timestamp (default now); `opts.fs` the filesystem seam.
  */
-export declare function freshnessSweep(store: Store, repoId: string, rootPath: string): SweepResult;
+export declare function freshnessSweep(store: Store, repoId: string, rootPath: string, opts?: {
+    ts?: string;
+    gitHead?: string | null;
+    fs?: SyncFs;
+}): SweepResult;
 /**
  * Counts of ways the DB disagrees with the current filesystem. All fields are
  * "not yet reconciled" states a freshnessSweep/ingest would resolve.
@@ -26,17 +74,20 @@ export interface DiskDrift {
     untracked: number;
 }
 /**
- * READ-ONLY disk-drift detector. Mirrors freshnessSweep's staged cheap approach
- * — stat-compare against file_stats first, hash only the stat-mismatched
- * candidates — but never ingests, commits, or touches file_stats. It answers a
- * single question: does the DB still agree with what's on disk right now?
+ * READ-ONLY disk-drift detector (spec/sync §4.3 "Disk drift"). Mirrors
+ * freshnessSweep's staged cheap approach — the same `sweepCandidates` over the
+ * same cache and snapshot, hashing only the stat-mismatched candidates — but
+ * never ingests, commits, or touches file_stats. It answers a single question:
+ * does the DB still agree with what's on disk right now?
  *
  * `changed` is decided by comparing a candidate's content hash to the doc's
  * stored `file_hash` (the same sha256(bytes) checkpoint writes), so a stat
- * change without a content change is NOT counted as drift. At the envelope
- * (≤10⁴ docs) the clean case is a directory walk plus stats (tens of ms);
- * hashing is bounded to files whose (mtime_ns, size) moved.
+ * change without a content change is NOT counted as drift.
  */
-export declare function detectDiskDrift(store: Store, repoId: string, rootPath: string): DiskDrift;
+export declare function detectDiskDrift(store: Store, repoId: string, rootPath: string, opts?: {
+    fs?: SyncFs;
+}): DiskDrift;
 /** Rebuild file_stats from scratch by re-statting + re-hashing every file. */
-export declare function rebuildFileStats(store: Store, repoId: string, rootPath: string): number;
+export declare function rebuildFileStats(store: Store, repoId: string, rootPath: string, opts?: {
+    fs?: SyncFs;
+}): number;

package/dist/src/sync/freshness.js

@@ -1,101 +1,121 @@
-import { statSync, readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
 import { sha256 } from "../core/hash.js";
 import { processCheckpoint } from "./checkpoint.js";
-import { walkMarkdown } from "./fs-util.js";
-/** Record/refresh a file's stat cache row. Call after any ingest of the file. */
-export function recordFileStat(store, repoId, path, abs, hash) {
-    if (!existsSync(abs)) {
+import { nodeFs } from "./fs-util.js";
+/** Step 1 of §4.3 alone: the stat-mismatched or new paths, without hashing anything. */
+export function sweepCandidates(cache, snapshot) {
+    const out = [];
+    for (const e of snapshot) {
+        const cached = cache.get(e.path);
+        if (!cached || cached.mtime_ns !== e.mtime_ns || cached.size !== e.size)
+            out.push(e.path);
+    }
+    return out;
+}
+/** spec/sync §4.3 steps 1–2 as a pure function (README §8 `sweep_plan`). */
+export function sweepPlan(cache, snapshot) {
+    const byPath = new Map(snapshot.map((e) => [e.path, e]));
+    const candidates = sweepCandidates(cache, snapshot);
+    const deletions = [...cache.keys()].filter((p) => !byPath.has(p));
+    const changed = [];
+    const refreshed = [];
+    const hashes = new Map();
+    for (const path of candidates) {
+        const hash = byPath.get(path).hash();
+        hashes.set(path, hash);
+        const cached = cache.get(path);
+        if (!cached || !cached.hash.equals(hash))
+            changed.push(path);
+        else
+            refreshed.push(path);
+    }
+    return { candidates, changed, deletions, refreshed, hashes };
+}
+/** The repo's `file_stats` rows keyed by path. Read with safe integers: an `mtime_ns` is a
+ *  64-bit count a JS number cannot hold exactly, and a rounded value would never equal a stat. */
+export function loadStatCache(store, repoId) {
+    const cache = new Map();
+    const rows = store.db.prepare("SELECT path, mtime_ns, size, hash FROM file_stats WHERE repo_id = ?").safeIntegers(true).all(repoId);
+    for (const row of rows)
+        cache.set(row.path, { path: row.path, mtime_ns: row.mtime_ns, size: Number(row.size), hash: row.hash });
+    return cache;
+}
+/** The current filesystem snapshot: the §4.2 walk with each file's stat and a lazy hash. */
+export function snapshotOf(fs, rootPath) {
+    const out = [];
+    for (const path of fs.walk(rootPath)) {
+        const st = fs.stat(rootPath, path);
+        if (!st)
+            continue; // vanished between the walk and the stat
+        let memo = null;
+        out.push({
+            path,
+            mtime_ns: st.mtimeNs,
+            size: st.size,
+            hash: () => (memo ??= sha256(fs.read(rootPath, path) ?? "")),
+        });
+    }
+    return out;
+}
+/** Write a file's stat cache row from a stat (`INSERT … ON CONFLICT DO UPDATE`); a null stat (the
+ *  file vanished) deletes the row. The DB half of `record_file_stat` (spec/sync §4.3 step 4). */
+export function recordStat(store, repoId, path, st, hash) {
+    if (!st) {
         store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
         return;
     }
-    const st = statSync(abs, { bigint: true });
     store.db
         .prepare(`INSERT INTO file_stats (repo_id, path, mtime_ns, size, hash) VALUES (?, ?, ?, ?, ?)
        ON CONFLICT(repo_id, path) DO UPDATE SET mtime_ns = excluded.mtime_ns, size = excluded.size, hash = excluded.hash`)
-        .run(repoId, path, st.mtimeNs.toString(), Number(st.size), hash);
+        .run(repoId, path, st.mtimeNs, st.size, hash);
+}
+/** Record/refresh a file's stat cache row from its absolute path. Call after any ingest of the file. */
+export function recordFileStat(store, repoId, path, abs, hash) {
+    recordStat(store, repoId, path, nodeFs.stat(abs, ""), hash);
 }
 /**
- * Run the freshness sweep for a repo. Returns the checkpoint result plus scan
- * counters. Idempotent; safe alongside a live watcher (hash-based echo
- * suppression makes a double ingest a no-op).
+ * Run the freshness sweep for a repo (spec/sync §4.3). Returns the checkpoint
+ * result plus scan counters. Idempotent; safe alongside a live watcher
+ * (hash-based echo suppression makes a double ingest a no-op). `opts.ts` pins
+ * the batch timestamp (default now); `opts.fs` the filesystem seam.
  */
-export function freshnessSweep(store, repoId, rootPath) {
-    const cache = new Map();
-    for (const row of store.db
-        .prepare("SELECT path, mtime_ns, size, hash FROM file_stats WHERE repo_id = ?")
-        .all(repoId)) {
-        cache.set(row.path, { mtime_ns: BigInt(row.mtime_ns), size: row.size, hash: row.hash });
+export function freshnessSweep(store, repoId, rootPath, opts = {}) {
+    const fs = opts.fs ?? nodeFs;
+    const cache = loadStatCache(store, repoId);
+    const snapshot = snapshotOf(fs, rootPath);
+    const plan = sweepPlan(cache, snapshot);
+    const statOf = new Map(snapshot.map((e) => [e.path, { mtimeNs: e.mtime_ns, size: e.size }]));
+    // Content unchanged; refresh the stat cache so we don't re-hash next time.
+    for (const path of plan.refreshed) {
+        const st = statOf.get(path);
+        store.db.prepare("UPDATE file_stats SET mtime_ns = ?, size = ? WHERE repo_id = ? AND path = ?").run(st.mtimeNs, st.size, repoId, path);
     }
-    const paths = walkMarkdown(rootPath);
-    const seen = new Set(paths);
-    // Candidates: files whose (mtime_ns, size) differs from cache, or are new.
-    const candidates = [];
-    const freshStats = new Map();
-    for (const path of paths) {
-        const st = statSync(join(rootPath, path), { bigint: true });
-        freshStats.set(path, { mtimeNs: st.mtimeNs, size: Number(st.size) });
-        const cached = cache.get(path);
-        if (!cached || cached.mtime_ns !== st.mtimeNs || cached.size !== Number(st.size)) {
-            candidates.push(path);
-        }
-    }
-    // Deletions: cached paths no longer on disk.
-    const deletedPaths = [...cache.keys()].filter((p) => !seen.has(p));
-    // Hash candidates; only those whose content hash actually differs from the
-    // cached hash need ingesting (mtime can change without content changing).
-    const changedPaths = [];
-    const candHashes = new Map();
-    for (const path of candidates) {
-        const hash = sha256(readFileSync(join(rootPath, path), "utf8"));
-        candHashes.set(path, hash);
-        const cached = cache.get(path);
-        if (!cached || !cached.hash.equals(hash))
-            changedPaths.push(path);
-        else {
-            // Content unchanged; refresh the stat cache so we don't re-hash next time.
-            const fs = freshStats.get(path);
-            store.db
-                .prepare("UPDATE file_stats SET mtime_ns = ?, size = ? WHERE repo_id = ? AND path = ?")
-                .run(fs.mtimeNs.toString(), fs.size, repoId, path);
-        }
-    }
-    const toIngest = [...changedPaths, ...deletedPaths];
-    const result = processCheckpoint(store, repoId, rootPath, toIngest.map((path) => ({ path })));
+    const result = processCheckpoint(store, repoId, rootPath, [...plan.changed, ...plan.deletions].map((path) => ({ path })), { fs, ...(opts.ts !== undefined ? { ts: opts.ts } : {}), ...(opts.gitHead !== undefined ? { gitHead: opts.gitHead } : {}) });
     // Refresh stat cache for everything we touched (ingested or echo-suppressed).
-    for (const path of changedPaths) {
-        recordFileStat(store, repoId, path, join(rootPath, path), candHashes.get(path));
-    }
-    for (const path of deletedPaths) {
+    for (const path of plan.changed)
+        recordStat(store, repoId, path, fs.stat(rootPath, path), plan.hashes.get(path));
+    for (const path of plan.deletions)
         store.db.prepare("DELETE FROM file_stats WHERE repo_id = ? AND path = ?").run(repoId, path);
-    }
     return {
         ...result,
-        scanned: paths.length,
-        candidates: candidates.length,
+        scanned: snapshot.length,
+        candidates: plan.candidates.length,
         changed: result.ingested.length > 0 || result.deleted.length > 0 || result.conflicted.length > 0,
     };
 }
 /**
- * READ-ONLY disk-drift detector. Mirrors freshnessSweep's staged cheap approach
- * — stat-compare against file_stats first, hash only the stat-mismatched
- * candidates — but never ingests, commits, or touches file_stats. It answers a
- * single question: does the DB still agree with what's on disk right now?
+ * READ-ONLY disk-drift detector (spec/sync §4.3 "Disk drift"). Mirrors
+ * freshnessSweep's staged cheap approach — the same `sweepCandidates` over the
+ * same cache and snapshot, hashing only the stat-mismatched candidates — but
+ * never ingests, commits, or touches file_stats. It answers a single question:
+ * does the DB still agree with what's on disk right now?
  *
  * `changed` is decided by comparing a candidate's content hash to the doc's
  * stored `file_hash` (the same sha256(bytes) checkpoint writes), so a stat
- * change without a content change is NOT counted as drift. At the envelope
- * (≤10⁴ docs) the clean case is a directory walk plus stats (tens of ms);
- * hashing is bounded to files whose (mtime_ns, size) moved.
+ * change without a content change is NOT counted as drift.
  */
-export function detectDiskDrift(store, repoId, rootPath) {
-    // Stat cache keyed by path, for cheap change detection.
-    const cache = new Map();
-    for (const row of store.db
-        .prepare("SELECT path, mtime_ns, size, hash FROM file_stats WHERE repo_id = ?")
-        .all(repoId)) {
-        cache.set(row.path, { mtime_ns: BigInt(row.mtime_ns), size: row.size, hash: row.hash });
-    }
+export function detectDiskDrift(store, repoId, rootPath, opts = {}) {
+    const fs = opts.fs ?? nodeFs;
+    const cache = loadStatCache(store, repoId);
     // Live docs keyed by path, with their durable file_hash (the convergence
     // signal). This is the authority for changed/deleted/untracked, independent
     // of the derived file_stats cache.
@@ -105,47 +125,38 @@ export function detectDiskDrift(store, repoId, rootPath) {
         .all(repoId)) {
         docs.set(row.path, row.file_hash);
     }
-    const paths = walkMarkdown(rootPath);
-    const seen = new Set(paths);
-    // Candidates whose (mtime_ns, size) differs from the stat cache (or are new).
-    const candidates = [];
-    for (const path of paths) {
-        const st = statSync(join(rootPath, path), { bigint: true });
-        const cached = cache.get(path);
-        if (!cached || cached.mtime_ns !== st.mtimeNs || cached.size !== Number(st.size)) {
-            candidates.push(path);
-        }
-    }
+    const snapshot = snapshotOf(fs, rootPath);
+    const byPath = new Map(snapshot.map((e) => [e.path, e]));
     let changed = 0;
     let untracked = 0;
-    for (const path of candidates) {
+    for (const path of sweepCandidates(cache, snapshot)) {
         const doc = docs.get(path);
         if (doc === undefined) {
             // No non-deleted doc for an on-disk *.md ⇒ untracked (new file).
             untracked += 1;
             continue;
         }
-        const hash = sha256(readFileSync(join(rootPath, path), "utf8"));
         // Genuinely drifted only if content hash differs from the doc's file_hash.
-        if (!doc || !doc.equals(hash))
+        if (!doc || !doc.equals(byPath.get(path).hash()))
             changed += 1;
     }
     // A doc present in the DB whose path isn't on disk anymore is a pending delete.
     let deleted = 0;
-    for (const path of docs.keys()) {
-        if (!seen.has(path))
+    for (const path of docs.keys())
+        if (!byPath.has(path))
             deleted += 1;
-    }
     return { changed, deleted, untracked };
 }
 /** Rebuild file_stats from scratch by re-statting + re-hashing every file. */
-export function rebuildFileStats(store, repoId, rootPath) {
+export function rebuildFileStats(store, repoId, rootPath, opts = {}) {
+    const fs = opts.fs ?? nodeFs;
     store.db.prepare("DELETE FROM file_stats WHERE repo_id = ?").run(repoId);
-    const paths = walkMarkdown(rootPath);
+    const paths = fs.walk(rootPath);
     for (const path of paths) {
-        const abs = join(rootPath, path);
-        const hash = sha256(readFileSync(abs, "utf8"));
-        recordFileStat(store, repoId, path, abs, hash);
+        const bytes = fs.read(rootPath, path);
+        if (bytes === null)
+            continue;
+        recordStat(store, repoId, path, fs.stat(rootPath, path), sha256(bytes));
     }
     return paths.length;
 }

package/dist/src/sync/fs-util.d.ts

@@ -1,5 +1,24 @@
 /** Walk `root` for *.md files, returning repo-relative canonical paths. */
 export declare function walkMarkdown(root: string): string[];
+/** The two stat fields the freshness cache keys on (spec/sync §4.3). */
+export interface FileStat {
+    mtimeNs: bigint;
+    size: number;
+}
+/**
+ * The filesystem as the sync paths see it — a walk, a stat and a read, all
+ * keyed by (root, repo-relative path). `nodeFs` is the production default.
+ */
+export interface SyncFs {
+    /** spec/sync §4.2: every `*.md` under `root`, repo-relative, `/` separators, readdir order, depth-first. */
+    walk(root: string): string[];
+    /** `(mtime_ns, size)` of `root/path`, or null when the file is absent. */
+    stat(root: string, path: string): FileStat | null;
+    /** The UTF-8 bytes of `root/path`, or null when the file is absent. */
+    read(root: string, path: string): string | null;
+}
+/** The `node:fs` filesystem. */
+export declare const nodeFs: SyncFs;
 /**
  * Async variant of {@link walkMarkdown}: identical result, but yields to the
  * event loop between directories and invokes `onFound(count)` as matches

package/dist/src/sync/fs-util.js

@@ -1,10 +1,15 @@
-import { readdirSync, statSync } from "node:fs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 // Shared filesystem walk for the in-process one-shot/reconcile paths (attach,
 // checkpoint, freshness). This is NOT the live watcher — chokidar lives only in
 // the external @omgbase/fs-adapter (sync-plugins). node:fs (a builtin) reads
 // are retained here for the one-shot ingest/freshness fast-path.
+//
+// `SyncFs` is the seam those paths read the filesystem through (spec/sync §4,
+// §8): the sweep, the checkpoint and recovery take an optional `fs` and default
+// to `nodeFs`, so a conformance runner can supply an in-memory filesystem with
+// explicit `mtime_ns` and the fixtures stay free of real I/O.
 const IGNORED_DIRS = new Set([".omgbase", ".git", "node_modules"]);
 /** Walk `root` for *.md files, returning repo-relative canonical paths. */
 export function walkMarkdown(root) {
@@ -23,6 +28,24 @@ export function walkMarkdown(root) {
     recur(root);
     return out;
 }
+/** The `node:fs` filesystem. */
+export const nodeFs = {
+    walk: walkMarkdown,
+    stat(root, path) {
+        const st = statSync(join(root, path), { bigint: true, throwIfNoEntry: false });
+        return st ? { mtimeNs: st.mtimeNs, size: Number(st.size) } : null;
+    },
+    read(root, path) {
+        try {
+            return readFileSync(join(root, path), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    },
+};
 /**
  * Async variant of {@link walkMarkdown}: identical result, but yields to the
  * event loop between directories and invokes `onFound(count)` as matches

package/dist/src/sync/observe.d.ts

@@ -1,4 +1,5 @@
 import type { Store } from "../core/store/store.js";
+import { type ReconcileConfig } from "../reconcile/types.js";
 export interface ObserveResult {
     docId: string;
     path: string;
@@ -25,11 +26,56 @@ export interface ObserveOneResult extends ObserveResult {
     /** sha256(content) (hex) — the new file hash. */
     newHashHex: string;
 }
+/** One member of a batch: its current bytes, or `null` when it left the source
+ *  scope (deleted on disk / adapter fetch returned null). */
+export interface BatchItem {
+    path: string;
+    content: string | null;
+}
+/** Outcome of one batch member: an observation (echo or commit) or a deletion. */
+export type BatchOutcome = ({
+    kind: "observed";
+} & ObserveOneResult) | {
+    kind: "deleted";
+    path: string;
+    /** the tombstoned doc, or null when no live doc existed at `path` (no-op). */
+    docId: string | null;
+    oldHashHex: string | null;
+};
+/**
+ * The batch reconcile primitive — one checkpoint's worth of members, in order.
+ * Two passes with the cross-document phase between them (reconciliation-spec §8):
+ *
+ *   1. every member is echo-gated and, when it differs from the stored revision,
+ *      parsed + reconciled against its own prior tree WITHOUT committing
+ *      (`prepareReconcile`; members gone from the source contribute their whole
+ *      live tree as deleted). All members see one resurrection-pool snapshot with
+ *      a shared consumed-set, so no pooled id resurrects twice in a batch.
+ *   2. the per-doc leftovers are pooled — deleted old blocks × inserted new
+ *      blocks, across documents only — and matched at theta_xdoc
+ *      (`crossDocMatch`). Each accepted pair is applied to both results: the
+ *      destination's minted id becomes the carried id (`moved`/`edited_moved`,
+ *      `detail.fromDoc`), the source's `deleted` disposition and pool entry for
+ *      it vanish (`applyCrossDocMatches`).
+ *   3. every member commits, in batch order, each in its own transaction:
+ *      `ingestFile` with the finished result (a carried-in id evicts the row the
+ *      source doc may still hold — see `IdResolver.crossDocIds` — so the order
+ *      of A and B in the batch does not matter), or `tombstoneObservedDeletion`.
+ *
+ * A moved block is therefore never `deleted` + `inserted`, never pooled, and
+ * never `resurrected` inside one batch. Across batches the pool still does that
+ * job (spec/reconcile §5 phase 6b). Does NOT sweep the pool — the caller does,
+ * once per batch. Does NOT write a file.
+ */
+export declare function observeBatch(store: Store, repoId: string, items: BatchItem[], ts: string, opts?: {
+    config?: ReconcileConfig;
+}): BatchOutcome[];
 /**
- * The reconcile primitive: echo-gate `content` for `path` and, when it differs
- * from the stored revision, ingest it as an observed commit (reconciling block
- * identity against the prior revision). Does NOT sweep the resurrection pool —
- * the caller does that once per batch. Does NOT write a file.
+ * The single-member reconcile primitive: echo-gate `content` for `path` and,
+ * when it differs from the stored revision, ingest it as an observed commit
+ * (reconciling block identity against the prior revision). A batch of one — so
+ * no cross-document matching; use `observeBatch` for that. Does NOT sweep the
+ * resurrection pool — the caller does that once per batch. Does NOT write a file.
  */
 export declare function observeOne(store: Store, repoId: string, path: string, content: string, ts: string): ObserveOneResult;
 /** Observe one file's authoritative bytes as an observed commit (echo-suppressed). */
@@ -37,7 +83,9 @@ export declare function observeFile(store: Store, repoId: string, path: string,
     ts?: string;
 }): ObserveResult;
 /** Observe a batch of files under one timestamp + one resurrection sweep. The
- *  batch form of `observeFile`; each item is echo-gated independently. */
+ *  batch form of `observeFile`; each item is echo-gated independently, and a
+ *  block cut from one file and pasted into another in the same batch keeps its
+ *  id (`moved`/`edited_moved`) via the cross-document phase of `observeBatch`. */
 export declare function observeMany(store: Store, repoId: string, items: {
     path: string;
     content: string;