@omgbase/core 0.1.0 → 0.3.0

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,58 @@ 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) {
+/**
+ * Rebuild `file_stats` from scratch (spec/sync §4.3, since 1.1): delete the repo's rows, then
+ * walk the tree and record a row only for a file whose bytes' hash equals its live doc's
+ * `file_hash` — the cache is allowed to say "known" only about bytes the store already holds.
+ * A file with no live doc, or whose bytes differ from what was ingested, gets no row, so the
+ * next sweep still treats it as a candidate and drift still reports it (a cache rebuild must
+ * never change what the next sweep does). Returns the number of files walked, recorded or not.
+ */
+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);
+    // The live docs' durable convergence signal, keyed by path (one query).
+    const live = new Map();
+    for (const row of store.db
+        .prepare("SELECT path, file_hash FROM docs WHERE repo_id = ? AND deleted_commit IS NULL AND file_hash IS NOT NULL")
+        .all(repoId)) {
+        live.set(row.path, row.file_hash);
+    }
+    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 want = live.get(path);
+        if (!want)
+            continue; // no live doc: nothing the cache may vouch for
+        const bytes = fs.read(rootPath, path);
+        if (bytes === null)
+            continue; // vanished between the walk and the read
+        const hash = sha256(bytes);
+        if (!hash.equals(want))
+            continue; // a pending edit: leave it visible
+        recordStat(store, repoId, path, fs.stat(rootPath, path), hash);
     }
     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;

package/dist/src/sync/observe.js

@@ -1,31 +1,151 @@
 import { sha256 } from "../core/hash.js";
 import { ingestFile } from "../core/ingest.js";
-import { makeReconcilingResolver } from "./reconciling-ingest.js";
+import { makeReconcilingResolver, prepareReconcile, loadOldMatchBlocks, loadPool } from "./reconciling-ingest.js";
 import { hasConflictMarkers } from "./git-heuristics.js";
 import { tombstoneObservedDeletion } from "./tombstone.js";
 import { sweepResurrectionPool } from "../core/store/gc.js";
+import { crossDocMatch, applyCrossDocMatches } from "../reconcile/crossdoc.js";
+import { DEFAULT_CONFIG } from "../reconcile/types.js";
 /**
- * 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 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 function observeOne(store, repoId, path, content, ts) {
-    const existing = store.db
-        .prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
-        .get(repoId, path);
-    const oldHashHex = existing?.file_hash?.toString("hex") ?? null;
-    const diskHash = sha256(content);
-    const newHashHex = diskHash.toString("hex");
-    // Echo: the stored revision already equals these bytes → no commit. The
-    // loop-breaker the coordinator relies on (§6): re-observing what the engine
-    // already holds is a no-op.
-    if (existing && existing.file_hash && existing.file_hash.equals(diskHash)) {
-        return { docId: existing.doc_id, path, rev: null, commitId: null, converged: true, echo: true, conflicted: false, dispositions: [], oldHashHex, newHashHex };
+export function observeBatch(store, repoId, items, ts, opts = {}) {
+    const db = store.db;
+    const config = opts.config ?? DEFAULT_CONFIG;
+    const liveDoc = db.prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL");
+    // ---- pass 1: echo gate + reconcile, no commits -------------------------------
+    const pool = loadPool(db, repoId, ts);
+    const consumed = new Set();
+    const pending = [];
+    for (const it of items) {
+        const existing = liveDoc.get(repoId, it.path);
+        const oldHashHex = existing?.file_hash?.toString("hex") ?? null;
+        if (it.content === null) {
+            const oldBlocks = existing ? loadOldMatchBlocks(db, existing.doc_id) : [];
+            const result = existing
+                ? { assignment: new Map(), dispositions: [], deleted: oldBlocks.map((b) => b.blockId), consumedPool: [] }
+                : null;
+            pending.push({ kind: "gone", path: it.path, docId: existing?.doc_id ?? null, oldHashHex, oldBlocks, result });
+            continue;
+        }
+        const diskHash = sha256(it.content);
+        const newHashHex = diskHash.toString("hex");
+        // Echo: the stored revision already equals these bytes → no commit. The
+        // loop-breaker the coordinator relies on (§6): re-observing what the engine
+        // already holds is a no-op.
+        if (existing && existing.file_hash && existing.file_hash.equals(diskHash)) {
+            pending.push({
+                kind: "echo",
+                outcome: { kind: "observed", docId: existing.doc_id, path: it.path, rev: null, commitId: null, converged: true, echo: true, conflicted: false, dispositions: [], oldHashHex, newHashHex },
+            });
+            continue;
+        }
+        const prepared = prepareReconcile(store, repoId, it.path, it.content, { ts, config, pool, consumed });
+        pending.push({ kind: "ingest", prepared, oldHashHex, newHashHex });
+    }
+    // ---- cross-document phase (spec/reconcile §7) --------------------------------
+    if (pending.length > 1)
+        crossDocPhase(pending, config);
+    // ---- pass 2: commit, in batch order ------------------------------------------
+    const out = [];
+    for (const p of pending) {
+        if (p.kind === "echo") {
+            out.push(p.outcome);
+        }
+        else if (p.kind === "gone") {
+            if (p.docId)
+                tombstoneObservedDeletion(store, repoId, p.docId, ts);
+            out.push({ kind: "deleted", path: p.path, docId: p.docId, oldHashHex: p.oldHashHex });
+        }
+        else {
+            out.push({ kind: "observed", ...commitPrepared(store, repoId, p.prepared, ts, p.oldHashHex, p.newHashHex) });
+        }
+    }
+    return out;
+}
+// Pool each reconciled member's leftovers (README §7: deleted = old blocks whose
+// ids are in `deleted`, in that order; inserted = new blocks whose disposition
+// is `inserted`, with the minted id, in disposition order), match across
+// documents, and apply. Members are keyed by doc id; a brand-new path has none
+// yet, so it is keyed by path — it can only ever be a destination, and
+// `detail.fromDoc` is always a real doc id.
+function crossDocPhase(pending, config) {
+    const docs = [];
+    const results = new Map();
+    const prepared = new Map();
+    for (const p of pending) {
+        if (p.kind === "echo")
+            continue;
+        if (p.kind === "gone") {
+            if (!p.docId || !p.result)
+                continue;
+            docs.push({ docId: p.docId, deleted: p.oldBlocks.map((block) => ({ block })), inserted: [] });
+            results.set(p.docId, p.result);
+            continue;
+        }
+        const key = p.prepared.docId ?? `new:${p.prepared.path}`;
+        const oldById = new Map(p.prepared.oldBlocks.map((b) => [b.blockId, b]));
+        const newByKey = new Map(p.prepared.newBlocks.map((b) => [b.key, b]));
+        const keyOfId = new Map();
+        for (const [k, id] of p.prepared.result.assignment)
+            keyOfId.set(id, k);
+        const deleted = [];
+        for (const id of p.prepared.result.deleted) {
+            const block = oldById.get(id);
+            if (block)
+                deleted.push({ block });
+        }
+        const inserted = [];
+        for (const d of p.prepared.result.dispositions) {
+            if (d.kind !== "inserted")
+                continue;
+            const k = keyOfId.get(d.blockId);
+            const block = k ? newByKey.get(k) : undefined;
+            if (block)
+                inserted.push({ block, mintedId: d.blockId });
+        }
+        docs.push({ docId: key, deleted, inserted });
+        results.set(key, p.prepared.result);
+        prepared.set(key, p.prepared);
     }
+    if (docs.length < 2)
+        return;
+    const matches = crossDocMatch(docs, config);
+    if (matches.length === 0)
+        return;
+    applyCrossDocMatches(results, matches, config.matcherV);
+    for (const m of matches)
+        prepared.get(m.toDoc)?.crossDocIds.push(m.carriedId);
+}
+// Pass 2 for one reconciled member: commit the finished result as an observed
+// revision (one transaction), flag conflict markers, summarize dispositions.
+function commitPrepared(store, repoId, prepared, ts, oldHashHex, newHashHex) {
+    const { path, content } = prepared;
     const conflicted = hasConflictMarkers(content);
-    const resolveIds = makeReconcilingResolver(store, repoId, { ts, path });
-    const res = ingestFile(store, repoId, path, content, { ts, origin: "observed", resolveIds });
+    const resolveIds = makeReconcilingResolver(store, repoId, { ts, path, prepared });
+    const res = ingestFile(store, repoId, path, content, { ts, origin: "observed", resolveIds, parsed: prepared.tree });
     store.db.prepare("UPDATE docs SET conflicted = ? WHERE repo_id = ? AND path = ?").run(conflicted ? 1 : 0, repoId, path);
     const rows = store.db
         .prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind ORDER BY kind")
@@ -43,6 +163,20 @@ export function observeOne(store, repoId, path, content, ts) {
         newHashHex,
     };
 }
+/**
+ * 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 function observeOne(store, repoId, path, content, ts) {
+    const [outcome] = observeBatch(store, repoId, [{ path, content }], ts);
+    if (!outcome || outcome.kind !== "observed")
+        throw new Error(`observeOne: unexpected outcome for ${path}`);
+    const { kind: _k, ...rest } = outcome;
+    return rest;
+}
 function toPublic(r) {
     const { oldHashHex: _o, newHashHex: _n, ...pub } = r;
     return pub;
@@ -55,10 +189,17 @@ export function observeFile(store, repoId, path, content, opts = {}) {
     return toPublic(r);
 }
 /** 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 function observeMany(store, repoId, items, opts = {}) {
     const ts = opts.ts ?? new Date().toISOString();
-    const out = items.map((it) => toPublic(observeOne(store, repoId, it.path, it.content, ts)));
+    const out = observeBatch(store, repoId, items, ts).map((o) => {
+        if (o.kind !== "observed")
+            throw new Error(`observeMany: unexpected outcome for ${o.path}`);
+        const { kind: _k, ...rest } = o;
+        return toPublic(rest);
+    });
     sweepResurrectionPool(store, ts);
     return out;
 }