@omgbase/core 0.1.0 → 0.3.0

package/dist/src/search/tasks.d.ts

@@ -1,5 +1,33 @@
 import type { Store } from "../core/store/store.js";
 import { type EmbedTask, type DocEmbedTask } from "./embeddings.js";
+/** The columns a block's current context (spec/search §2.2) is a function of. */
+export interface BlockContextInput {
+    doc_id: string;
+    path: string;
+    ordinal: number;
+    type: string;
+}
+/**
+ * Resolves a block's *current* embedding context (spec/search §2.2) — the one
+ * rule every reader of the `embeddings` cache keys with: the drain (tasks), the
+ * pooled document vector, `vector_search` (§3) and `semantic()` (spec/surface
+ * §1.3). Built once per repo (or per doc) and reused across blocks: one scan of
+ * the frontmatter titles and one of the sections, then a per-block walk of the
+ * doc's sections for the heading chain.
+ */
+export interface BlockContextResolver {
+    ctx(block: BlockContextInput): string;
+}
+/**
+ * Load the title/section facts the context prefix depends on. `scope` narrows
+ * the load to one repo (every doc — the drain and vector search) or one doc
+ * (a single block's lookup).
+ */
+export declare function makeBlockContextResolver(store: Store, scope: {
+    repoId: string;
+} | {
+    docId: string;
+}): BlockContextResolver;
 /** Build EmbedTask[] for every embeddable live block in the repo. */
 export declare function buildEmbedTasks(store: Store, repoId: string): EmbedTask[];
 /**

package/dist/src/search/tasks.js

@@ -7,31 +7,31 @@ function docTitle(titleByDoc, firstHeadingByDoc, docId, path) {
         return t;
     return firstHeadingByDoc.get(docId) ?? path;
 }
-/** Build EmbedTask[] for every embeddable live block in the repo. */
-export function buildEmbedTasks(store, repoId) {
-    const blocks = store.db
-        .prepare(`SELECT b.block_id, b.doc_id, d.path AS path,
-              b.ordinal, b.type, b.text, b.raw_hash
-       FROM blocks b JOIN docs d ON d.doc_id = b.doc_id
-       WHERE b.repo_id = ? AND b.deleted_commit IS NULL
-       ORDER BY d.path, b.ordinal`)
-        .all(repoId);
-    // Frontmatter title per doc (scalar), for the embed context prefix. One scan
-    // of the properties table instead of a per-block metadata parse.
+/**
+ * Load the title/section facts the context prefix depends on. `scope` narrows
+ * the load to one repo (every doc — the drain and vector search) or one doc
+ * (a single block's lookup).
+ */
+export function makeBlockContextResolver(store, scope) {
+    const byRepo = "repoId" in scope;
+    // Frontmatter title per doc (scalar string), for the embed context prefix.
+    // One scan of the properties table instead of a per-block metadata parse.
     const titleByDoc = new Map();
     for (const r of store.db.prepare(`SELECT p.doc_id AS doc_id, p.val_text AS title FROM properties p
-     WHERE p.repo_id = ? AND p.source = 'frontmatter' AND p.key = 'title'
-       AND p.card = 'scalar' AND p.type = 'string' AND p.deleted_commit IS NULL`).all(repoId)) {
+     WHERE ${byRepo ? "p.repo_id = ?" : "p.doc_id = ?"} AND p.source = 'frontmatter' AND p.key = 'title'
+       AND p.card = 'scalar' AND p.type = 'string' AND p.deleted_commit IS NULL`).all(byRepo ? scope.repoId : scope.docId)) {
         if (r.title)
             titleByDoc.set(r.doc_id, r.title);
     }
-    // All sections in the repo, with their heading text, for chain lookup.
+    // The sections in scope with their heading text, for chain lookup. Ordered by
+    // first_ordinal so the first per doc is the title fallback (§2.2).
     const sections = store.db
         .prepare(`SELECT s.doc_id AS doc_id, hb.text AS heading_text, s.level AS level,
               s.first_ordinal AS first_ordinal, s.last_ordinal AS last_ordinal
        FROM sections s JOIN blocks hb ON hb.block_id = s.heading_block
-       WHERE hb.repo_id = ?`)
-        .all(repoId);
+       WHERE ${byRepo ? "hb.repo_id = ?" : "s.doc_id = ?"}
+       ORDER BY s.doc_id, s.first_ordinal, s.rowid`)
+        .all(byRepo ? scope.repoId : scope.docId);
     const sectionsByDoc = new Map();
     for (const s of sections) {
         (sectionsByDoc.get(s.doc_id) ?? sectionsByDoc.set(s.doc_id, []).get(s.doc_id)).push(s);
@@ -52,17 +52,30 @@ export function buildEmbedTasks(store, repoId) {
             .sort((a, b) => a.level - b.level)
             .map((s) => s.heading_text);
     };
-    const tasks = [];
-    for (const b of blocks) {
-        if (!shouldEmbed(b.text))
-            continue;
-        const ctx = contextPrefix({
+    return {
+        ctx: (b) => contextPrefix({
             docTitle: docTitle(titleByDoc, firstHeadingByDoc, b.doc_id, b.path),
             path: b.path,
             headingChain: headingChain(b.doc_id, b.ordinal),
             blockType: b.type,
-        });
-        tasks.push({ blockId: b.block_id, contentHashHex: b.raw_hash.toString("hex"), ctx, text: b.text });
+        }),
+    };
+}
+/** Build EmbedTask[] for every embeddable live block in the repo. */
+export function buildEmbedTasks(store, repoId) {
+    const blocks = store.db
+        .prepare(`SELECT b.block_id, b.doc_id, d.path AS path,
+              b.ordinal, b.type, b.text, b.raw_hash
+       FROM blocks b JOIN docs d ON d.doc_id = b.doc_id
+       WHERE b.repo_id = ? AND b.deleted_commit IS NULL
+       ORDER BY d.path, b.ordinal`)
+        .all(repoId);
+    const contexts = makeBlockContextResolver(store, { repoId });
+    const tasks = [];
+    for (const b of blocks) {
+        if (!shouldEmbed(b.text))
+            continue;
+        tasks.push({ blockId: b.block_id, contentHashHex: b.raw_hash.toString("hex"), ctx: contexts.ctx(b), text: b.text });
     }
     return tasks;
 }

package/dist/src/search/vector.js

@@ -1,3 +1,5 @@
+import { ctxHashHex } from "./embeddings.js";
+import { buildEmbedTasks } from "./tasks.js";
 function cosine(a, b) {
     let dot = 0, na = 0, nb = 0;
     const n = Math.min(a.length, b.length);
@@ -12,17 +14,24 @@ function cosine(a, b) {
 }
 export function vectorSearch(store, repoId, model, queryVec, opts = {}) {
     const limit = opts.limit ?? 50;
-    const rows = store.db
-        .prepare(`SELECT b.block_id AS blockId, b.doc_id AS docId, d.path AS path, e.vec AS vec
-       FROM embeddings e
-       JOIN blocks b ON b.raw_hash = e.content_hash AND b.deleted_commit IS NULL
-       JOIN docs d ON d.doc_id = b.doc_id
-       WHERE b.repo_id = ? AND e.model = ?`)
-        .all(repoId, model);
-    const scored = rows.map((r) => {
-        const v = new Float32Array(r.vec.buffer, r.vec.byteOffset, r.vec.byteLength / 4);
-        return { blockId: r.blockId, docId: r.docId, path: r.path, cosine: cosine(queryVec, v) };
-    });
+    // The candidates are exactly the drain's tasks: every live embeddable block
+    // with its current (content_hash, ctx). Reusing buildEmbedTasks keeps the
+    // context rule in one place; its cost is one walk of the repo's blocks and
+    // sections per query (fine at v1 scale, see the ceiling above).
+    const tasks = buildEmbedTasks(store, repoId);
+    const docPath = store.db.prepare("SELECT doc_id AS docId, path FROM blocks JOIN docs USING (doc_id) WHERE block_id = ?");
+    const vecFor = store.db.prepare("SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?");
+    const scored = [];
+    for (const t of tasks) {
+        const row = vecFor.get(Buffer.from(t.contentHashHex, "hex"), Buffer.from(ctxHashHex(t.ctx), "hex"), model);
+        if (!row)
+            continue; // stale (§2.3): no vector until the next drain
+        const meta = docPath.get(t.blockId);
+        if (!meta)
+            continue;
+        const v = new Float32Array(row.vec.buffer, row.vec.byteOffset, row.vec.byteLength / 4);
+        scored.push({ blockId: t.blockId, docId: meta.docId, path: meta.path, cosine: cosine(queryVec, v) });
+    }
     scored.sort((a, b) => b.cosine - a.cosine || (a.blockId < b.blockId ? -1 : 1));
     return scored.slice(0, limit);
 }
@@ -39,10 +48,17 @@ export function docVectorSearch(store, repoId, model, queryVec, opts = {}) {
        JOIN docs d ON d.doc_id = e.doc_id AND d.deleted_commit IS NULL
        WHERE d.repo_id = ? AND e.model = ?`)
         .all(repoId, model);
-    const scored = rows.map((r) => {
+    // (doc_id, model) is the primary key, so this is one row per doc already;
+    // keep the best-cosine rule for symmetry with vectorSearch.
+    const best = new Map();
+    for (const r of rows) {
         const v = new Float32Array(r.vec.buffer, r.vec.byteOffset, r.vec.byteLength / 4);
-        return { docId: r.docId, path: r.path, cosine: cosine(queryVec, v) };
-    });
+        const c = cosine(queryVec, v);
+        const prev = best.get(r.docId);
+        if (!prev || c > prev.cosine)
+            best.set(r.docId, { docId: r.docId, path: r.path, cosine: c });
+    }
+    const scored = [...best.values()];
     scored.sort((a, b) => b.cosine - a.cosine || (a.docId < b.docId ? -1 : 1));
     return scored.slice(0, limit);
 }

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

@@ -1,4 +1,5 @@
 import type { Store } from "../core/store/store.js";
+import { type SyncFs } from "./fs-util.js";
 export interface IngestDirResult {
     repoId: string;
     fileCount: number;
@@ -8,6 +9,10 @@ export interface IngestDirResult {
  * Ingest a directory as a repo: create/reuse the repo (registering its fs
  * source) + ingest all Markdown, reconciling identity and extracting edges.
  * `files` (repo-relative paths) may be supplied by a caller that already walked
- * the tree, to avoid walking twice; omit it to walk here.
+ * the tree, to avoid walking twice; omit it to walk here. `opts.ts` pins the
+ * commit timestamp (default now); `opts.fs` the filesystem seam (default node).
  */
-export declare function ingestDirectory(store: Store, slug: string, rootPath: string, files?: string[]): IngestDirResult;
+export declare function ingestDirectory(store: Store, slug: string, rootPath: string, files?: string[], opts?: {
+    ts?: string;
+    fs?: SyncFs;
+}): IngestDirResult;

package/dist/src/sync/attach.js

@@ -1,22 +1,24 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import { ensureRepo } from "../core/attach.js";
 import { ingestFile } from "../core/ingest.js";
 import { makeReconcilingResolver } from "./reconciling-ingest.js";
-import { walkMarkdown } from "./fs-util.js";
+import { nodeFs } from "./fs-util.js";
 /**
  * Ingest a directory as a repo: create/reuse the repo (registering its fs
  * source) + ingest all Markdown, reconciling identity and extracting edges.
  * `files` (repo-relative paths) may be supplied by a caller that already walked
- * the tree, to avoid walking twice; omit it to walk here.
+ * the tree, to avoid walking twice; omit it to walk here. `opts.ts` pins the
+ * commit timestamp (default now); `opts.fs` the filesystem seam (default node).
  */
-export function ingestDirectory(store, slug, rootPath, files) {
+export function ingestDirectory(store, slug, rootPath, files, opts = {}) {
     const repoId = ensureRepo(store, slug, rootPath);
-    const walked = files ?? walkMarkdown(rootPath);
-    const ts = new Date().toISOString();
+    const fs = opts.fs ?? nodeFs;
+    const walked = files ?? fs.walk(rootPath);
+    const ts = opts.ts ?? new Date().toISOString();
     let allConverged = true;
     for (const rel of walked) {
-        const content = readFileSync(join(rootPath, rel), "utf8");
+        const content = fs.read(rootPath, rel);
+        if (content === null)
+            continue;
         const res = ingestFile(store, repoId, rel, content, {
             ts,
             resolveIds: makeReconcilingResolver(store, repoId, { ts, path: rel }),

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

@@ -1,4 +1,6 @@
 import type { Store } from "../core/store/store.js";
+import { type BatchOutcome } from "./observe.js";
+import { type SyncFs } from "./fs-util.js";
 export interface FileChange {
     /** repo-relative canonical path */
     path: string;
@@ -13,9 +15,24 @@ export interface CheckpointResult {
 /**
  * Process a batch of changed paths against a repo as one checkpoint. On-disk
  * bytes are read directly; a hash equal to the stored file_hash is an engine
- * echo (no commit). Otherwise ingest as an observed commit.
+ * echo (no commit). Otherwise ingest as an observed commit. A path gone from
+ * disk tombstones its live doc (drop FTS, tombstone blocks + doc, pool blocks
+ * for resurrection) so it stops being served as a ghost. Every member is
+ * reconciled before any commits, so a block cut from one file and pasted into
+ * another in the same checkpoint keeps its id (`observeBatch`). spec/sync §4.1
+ * `process_checkpoint(repo, root, paths, ts)`.
  */
 export declare function processCheckpoint(store: Store, repoId: string, rootPath: string, changes: FileChange[], opts?: {
     ts?: string;
     gitHead?: string | null;
+    fs?: SyncFs;
+}): CheckpointResult;
+/**
+ * Turn a batch's outcomes into the checkpoint row + result, then sweep the
+ * resurrection pool. Shared with the external-source driver (driver.ts), which
+ * obtains its bytes asynchronously but records its checkpoint the same way.
+ */
+export declare function finishCheckpoint(store: Store, repoId: string, outcomes: BatchOutcome[], opts: {
+    ts: string;
+    gitHead: string | null;
 }): CheckpointResult;

package/dist/src/sync/checkpoint.js

@@ -1,52 +1,54 @@
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
 import { mintId } from "../core/ids.js";
-import { observeOne } from "./observe.js";
+import { observeBatch } from "./observe.js";
 import { sweepResurrectionPool } from "../core/store/gc.js";
-import { tombstoneObservedDeletion } from "./tombstone.js";
+import { nodeFs } from "./fs-util.js";
 /**
  * Process a batch of changed paths against a repo as one checkpoint. On-disk
  * bytes are read directly; a hash equal to the stored file_hash is an engine
- * echo (no commit). Otherwise ingest as an observed commit.
+ * echo (no commit). Otherwise ingest as an observed commit. A path gone from
+ * disk tombstones its live doc (drop FTS, tombstone blocks + doc, pool blocks
+ * for resurrection) so it stops being served as a ghost. Every member is
+ * reconciled before any commits, so a block cut from one file and pasted into
+ * another in the same checkpoint keeps its id (`observeBatch`). spec/sync §4.1
+ * `process_checkpoint(repo, root, paths, ts)`.
  */
 export function processCheckpoint(store, repoId, rootPath, changes, opts = {}) {
     const ts = opts.ts ?? new Date().toISOString();
+    const fs = opts.fs ?? nodeFs;
+    const items = changes.map((change) => ({ path: change.path, content: fs.read(rootPath, change.path) }));
+    return finishCheckpoint(store, repoId, observeBatch(store, repoId, items, ts), { ts, gitHead: opts.gitHead ?? null });
+}
+/**
+ * Turn a batch's outcomes into the checkpoint row + result, then sweep the
+ * resurrection pool. Shared with the external-source driver (driver.ts), which
+ * obtains its bytes asynchronously but records its checkpoint the same way.
+ */
+export function finishCheckpoint(store, repoId, outcomes, opts) {
     const checkpointId = mintId("cp");
     const ingested = [];
     const suppressed = [];
     const deleted = [];
     const conflicted = [];
     const fileEntries = [];
-    for (const change of changes) {
-        const abs = join(rootPath, change.path);
-        if (!existsSync(abs)) {
-            // File gone from disk: tombstone the live doc (drop FTS, tombstone blocks +
-            // doc, pool blocks for resurrection) so it stops being served as a ghost.
-            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]);
+    for (const o of outcomes) {
+        if (o.kind === "deleted") {
+            if (o.docId)
+                deleted.push(o.path);
+            fileEntries.push([o.path, o.oldHashHex, null]);
             continue;
         }
-        // Reconcile the disk bytes through the shared observe primitive (echo gate,
-        // identity threading, conflict-marker flagging — the one implementation).
-        const r = observeOne(store, repoId, change.path, readFileSync(abs, "utf8"), ts);
-        if (r.echo)
-            suppressed.push(change.path);
-        else if (r.conflicted)
-            conflicted.push(change.path);
+        if (o.echo)
+            suppressed.push(o.path);
+        else if (o.conflicted)
+            conflicted.push(o.path);
         else
-            ingested.push(change.path);
-        fileEntries.push([change.path, r.oldHashHex, r.newHashHex]);
+            ingested.push(o.path);
+        fileEntries.push([o.path, o.oldHashHex, o.newHashHex]);
     }
     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);
+        .run(checkpointId, repoId, opts.ts, JSON.stringify(fileEntries), opts.gitHead);
+    sweepResurrectionPool(store, opts.ts);
     return { checkpointId, ingested, suppressed, deleted, conflicted };
 }
 //# sourceMappingURL=checkpoint.js.map

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,27 @@ 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, opts?: {
+    fs?: SyncFs;
+}): DiskDrift;
+/**
+ * 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 declare function detectDiskDrift(store: Store, repoId: string, rootPath: string): 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;