@omgbase/core 0.1.0 → 0.2.0

package/dist/src/reconcile/phase5.js

@@ -1,16 +1,16 @@
 import { shingles, dice, tokenCount } from "./similarity.js";
 // score(o,n) = 0.55 text_sim + 0.15 neighbor_ctx + 0.10 parent_match
 //            + 0.10 position_prior + 0.10 anchor_evidence
-function scorePair(o, n, state, oldCount, newCount) {
+function scorePair(o, n, state, oldSiblings, newSiblings) {
     const textSimVal = dice(shingles(o.text), shingles(n.text));
     // neighbor_ctx: fraction of {prev,next} siblings that are matched pairs.
     const neighborCtx = neighborContext(o, n, state);
     // parent_match: 1 if parents are a matched pair (or both roots).
     const parentMatch = parentsMatched(o, n, state) ? 1 : 0;
-    // position_prior: 1 - |rel_pos(o) - rel_pos(n)|
-    const relO = oldCount > 1 ? o.index / (oldCount - 1) : 0;
-    const relN = newCount > 1 ? n.index / (newCount - 1) : 0;
-    const positionPrior = 1 - Math.abs(relO - relN);
+    // position_prior: 1 - |rel(o) - rel(n)| with rel(b) = b.index / (siblings - 1)
+    // over b's own sibling count (spec §5; m2.1 — m2.0 divided by the size of
+    // the whole flattened list, compressing the prior for nested blocks).
+    const positionPrior = 1 - Math.abs(relPos(o, oldSiblings) - relPos(n, newSiblings));
     // anchor_evidence: shared anchors / code-fence info / heading prefix.
     const anchorEvidence = sharedAnchorEvidence(o, n);
     return (0.55 * textSimVal +
@@ -19,6 +19,18 @@ function scorePair(o, n, state, oldCount, newCount) {
         0.1 * positionPrior +
         0.1 * anchorEvidence);
 }
+function siblingCounts(blocks) {
+    const counts = new Map();
+    for (const b of blocks) {
+        const k = b.parentKey ?? "";
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    return counts;
+}
+function relPos(b, counts) {
+    const siblings = counts.get(b.parentKey ?? "") ?? 1;
+    return siblings > 1 ? b.index / (siblings - 1) : 0;
+}
 function siblingAt(blocks, parentKey, index) {
     return blocks.find((b) => b.parentKey === parentKey && b.index === index);
 }
@@ -98,7 +110,8 @@ function unmatchedNew(state) {
  * Phase 5 — scored assignment. Greedy-by-score with R3 order constraints:
  * accept the highest-scoring candidate, discard conflicting candidates
  * (same old or new, or order-crossing with an already-accepted same-parent
- * pair), repeat. Accept while score ≥ θ (θ_small for tiny blocks).
+ * pair), repeat. Accept a candidate when score ≥ θ (θ_small for tiny blocks);
+ * a candidate below its θ is skipped, not a stopping point.
  */
 export function phase5Scored(state) {
     const olds = unmatchedOld(state);
@@ -108,11 +121,12 @@ export function phase5Scored(state) {
     // Bulk path guard: too many unmatched ⇒ skip (handled by give-up logic 2.5).
     if (olds.length + news.length > state.config.maxScoredBlocks * 2)
         return;
-    const oldCount = state.old.length;
-    const newCount = state.neu.length;
+    // Sibling counts once per tree (position_prior).
+    const oldSiblings = siblingCounts(state.old);
+    const newSiblings = siblingCounts(state.neu);
     const candidates = pruneCandidates(olds, news);
     for (const c of candidates)
-        c.score = scorePair(c.old, c.neu, state, oldCount, newCount);
+        c.score = scorePair(c.old, c.neu, state, oldSiblings, newSiblings);
     // Deterministic order: score desc, then old key, then new key.
     candidates.sort((a, b) => b.score - a.score || cmp(a.old.key, b.old.key) || cmp(a.neu.key, b.neu.key));
     // All scored candidates per new key, for near-miss recording (R5).
@@ -125,8 +139,11 @@ export function phase5Scored(state) {
         if (state.usedOld.has(c.old.blockId) || state.usedNew.has(c.neu.key))
             continue;
         const threshold = tokenCount(c.neu.text) < state.config.smallBlockTokens ? state.config.thetaSmall : state.config.thetaAccept;
+        // Sorted desc, but θ differs per candidate (θ_small for tiny new blocks), so a
+        // sub-threshold tiny-block candidate must not end the walk for the regular
+        // candidates sorted below it (m2.1; spec §5 phase 5 step 2).
         if (c.score < threshold)
-            break; // sorted desc: nothing below will qualify either
+            continue;
         // R3: within the same new parent, accepted pairs must not cross in order.
         if (c.old.parentKey === c.neu.parentKey) {
             const list = acceptedByParent.get(c.neu.parentKey) ?? [];

package/dist/src/reconcile/phase6a.js

@@ -2,6 +2,9 @@ import { shingles, dice, tokenCount, tokenize } from "./similarity.js";
 // Phase 6a — compound classification (03 §4): split, merge, copy over the
 // still-unmatched. Split/merge use dominant-fragment inheritance (tunable via
 // split.dominant_share; set to 1.01 to disable). Copies never steal identity.
+// Each pass proceeds in document order over the blocks that were unmatched when
+// it began and are still unmatched when reached, resolving every split (merge)
+// it finds (m2.1; m2.0 returned after the first).
 function unmatchedOld(state) {
     return state.old.filter((b) => !state.usedOld.has(b.blockId));
 }
@@ -44,11 +47,15 @@ function noteLineage(state, newB, kind, counterpartOldId) {
 function detectSplits(state) {
     const { splitCoverage, splitDominantShare } = state.config;
     for (const o of unmatchedOld(state)) {
+        if (state.usedOld.has(o.blockId))
+            continue; // consumed earlier in this pass
         const news = unmatchedNew(state)
             .filter((n) => n.parentKey === o.parentKey && n.type === o.type)
             .sort((a, b) => a.index - b.index);
-        // find a contiguous run (by index) of length ≥2 covering O
-        for (let start = 0; start < news.length; start++) {
+        // find a contiguous run (by index) of length ≥2 covering O; the first hit
+        // (start ascending, longest window first) is the split.
+        let found = false;
+        for (let start = 0; start < news.length && !found; start++) {
             for (let end = news.length; end > start + 1; end--) {
                 const run = news.slice(start, end);
                 if (!isContiguous(run))
@@ -76,7 +83,8 @@ function detectSplits(state) {
                     for (const n of run)
                         noteLineage(state, n, "split_from", o.blockId);
                 }
-                return; // one split per pass (conservative)
+                found = true;
+                break; // on to the next unmatched old block
             }
         }
     }
@@ -85,10 +93,13 @@ function detectSplits(state) {
 function detectMerges(state) {
     const { splitCoverage, splitDominantShare } = state.config;
     for (const n of unmatchedNew(state)) {
+        if (state.usedNew.has(n.key))
+            continue; // consumed earlier in this pass
         const olds = unmatchedOld(state)
             .filter((o) => o.parentKey === n.parentKey && o.type === n.type)
             .sort((a, b) => a.index - b.index);
-        for (let start = 0; start < olds.length; start++) {
+        let found = false;
+        for (let start = 0; start < olds.length && !found; start++) {
             for (let end = olds.length; end > start + 1; end--) {
                 const run = olds.slice(start, end);
                 if (!isContiguous(run))
@@ -116,7 +127,8 @@ function detectMerges(state) {
                     }
                     noteLineage(state, n, "merged_into", first.blockId);
                 }
-                return;
+                found = true;
+                break; // on to the next unmatched new block
             }
         }
     }

package/dist/src/reconcile/phases.d.ts

@@ -18,11 +18,49 @@ export declare function phase2Normalized(state: PhaseState): void;
 /** Phase 3 — anchor lock: same authored ^ref, unique on both sides. */
 export declare function phase3Anchor(state: PhaseState): void;
 /**
- * Phase 4 — context propagation (03 §4). Matched siblings vouch for the
- * stranger between them: within a gap bounded by matched blocks, if exactly one
- * unmatched OLD child remains, pair it with its best-matching unmatched NEW
- * child in that same gap (text_sim ≥ floor, unique best). Insertions in the gap
- * do not block the carry — they simply lose to the better-matching candidate,
- * which is why an inserted block never steals an edited block's identity.
+ * Phase 4a — context propagation (spec/reconcile §5). Matched siblings vouch
+ * for the stranger between them: within a gap bounded by matched blocks, if
+ * exactly one unmatched OLD child remains, pair it with its best-matching
+ * unmatched NEW child in that same gap (text_sim ≥ floor, unique best).
+ * Insertions in the gap do not block the carry — they simply lose to the
+ * better-matching candidate, which is why an inserted block never steals an
+ * edited block's identity.
+ *
+ * Step 5, the singleton rule (m2.3): when the floor test fails (or there is
+ * no best), a carried container (not the root pair) with exactly one unmatched
+ * old child and exactly one unmatched new child of its type carries them
+ * without a text floor, provided the new child sits in the SAME SLOT — same
+ * index, or the siblings just before both (or just after both) are a carried
+ * pair — and anchors do not veto (if either block has anchors they must share
+ * one). Reason `context_unique`, confidence 0.75 + 0.2 × text_sim, whatever
+ * text_sim is (0 for a two-word item whose one word changed). Root-level
+ * singletons are excluded: an unrelated replacement paragraph is common there
+ * and paragraphs carry the block references R4 protects.
  */
 export declare function phase4Context(state: PhaseState): void;
+/**
+ * Phase 4b — children vouch for their parent (03 §4). Phase 4 lets a matched
+ * parent vouch for the stranger among its children; this is the converse. For
+ * each unmatched OLD container, look at where its already-carried children
+ * landed. If a clear majority of them (≥ childrenVouchFrac of ALL its children)
+ * sit under one unmatched NEW block of the same type, and that block is the
+ * unique destination for them, and the old container is in turn the unique
+ * source of that block's carried children (mutual best by children), and the
+ * two containers' own parents do not contradict the pairing (a matched pair,
+ * both roots, or both still undecided), the containers pair. Reason
+ * `context_children`, confidence 0.75 + 0.2 × fraction.
+ *
+ * Text is deliberately not consulted: a container's visible text is its
+ * children's text, so a one-word-per-item list has no shingle evidence to give
+ * — its children's carried ids are the evidence. Returns true if any pair was
+ * made (phase4Propagate iterates to a fixed point).
+ */
+export declare function phase4bChildren(state: PhaseState): boolean;
+/**
+ * Phase 4 fixed point: context propagation (parents/siblings vouch for a
+ * child) and children vouching (children vouch for their parent) feed each
+ * other — a newly paired list unlocks its lone edited item; a newly paired
+ * inner list unlocks the item that contains it, then the outer list. Iterate
+ * until neither adds a pair. Terminates: every round consumes ≥ 1 old block.
+ */
+export declare function phase4Propagate(state: PhaseState): void;

package/dist/src/reconcile/reconcile.js

@@ -1,6 +1,6 @@
 import { mintId } from "../core/ids.js";
 import { DEFAULT_CONFIG } from "./types.js";
-import { phase1Exact, phase2Normalized, phase3Anchor, phase4Context } from "./phases.js";
+import { phase1Exact, phase2Normalized, phase3Anchor, phase4Propagate } from "./phases.js";
 import { phase5Scored } from "./phase5.js";
 import { phase6aCompound } from "./phase6a.js";
 function newState(old, neu, config) {
@@ -50,7 +50,7 @@ export function reconcileDocument(oldBlocks, newBlocks, opts = {}) {
         return bulkRewrite(state);
     }
     phase3Anchor(state);
-    phase4Context(state);
+    phase4Propagate(state); // phases 4 + 4b to a fixed point
     phase5Scored(state);
     phase6aCompound(state);
     if (opts.pool && opts.pool.length > 0)
@@ -84,15 +84,24 @@ function finalize(state, consumedPool) {
             dispositions.push({ blockId: minted, kind: "inserted", confidence: null, reason: null, matcherV: state.config.matcherV, detail: {} });
         }
     }
-    // Remaining old blocks (not carried) → deleted.
-    const deleted = [];
+    // Remaining old blocks (not carried, not otherwise disposed) → deleted.
     for (const o of state.old) {
         if (!state.usedOld.has(o.blockId)) {
-            deleted.push(o.blockId);
             dispositions.push({ blockId: o.blockId, kind: "deleted", confidence: null, reason: "tombstone", matcherV: state.config.matcherV, detail: {} });
         }
     }
-    return { assignment, dispositions, deleted, consumedPool };
+    return { assignment, dispositions, deleted: deletedIds(state.old, dispositions), consumedPool };
+}
+/** `deleted` = every old id whose disposition kind is `deleted` — the phase 7
+ * tombstones and the phase 6a non-dominant split tombstones — in old document
+ * order (spec §2; m2.1 — m2.0 listed only the phase 7 ones, so a split
+ * tombstone never reached the resurrection pool). */
+function deletedIds(old, dispositions) {
+    const deletedSet = new Set();
+    for (const d of dispositions)
+        if (d.kind === "deleted")
+            deletedSet.add(d.blockId);
+    return old.filter((o) => deletedSet.has(o.blockId)).map((o) => o.blockId);
 }
 function bulkRewrite(state) {
     // Mint everything; emit one doc-scoped bulk_rewrite + deleted for all old.
@@ -105,11 +114,9 @@ function bulkRewrite(state) {
         assignment.set(n.key, minted);
         dispositions.push({ blockId: minted, kind: "inserted", confidence: null, reason: null, matcherV: state.config.matcherV, detail: {} });
     }
-    const deleted = [];
     for (const o of state.old) {
-        deleted.push(o.blockId);
         dispositions.push({ blockId: o.blockId, kind: "deleted", confidence: null, reason: "tombstone", matcherV: state.config.matcherV, detail: {} });
     }
-    return { assignment, dispositions, deleted, consumedPool: [] };
+    return { assignment, dispositions, deleted: deletedIds(state.old, dispositions), consumedPool: [] };
 }
 //# sourceMappingURL=reconcile.js.map

package/dist/src/reconcile/types.d.ts

@@ -1,5 +1,5 @@
 export type DispositionKind = "same" | "edited" | "moved" | "edited_moved" | "inserted" | "deleted" | "split_from" | "merged_into" | "copied_from" | "resurrected" | "bulk_rewrite";
-export type Reason = "exact_hash" | "normalized_hash" | "anchor" | "context_unique" | "scored" | "tombstone" | "api";
+export type Reason = "exact_hash" | "normalized_hash" | "anchor" | "context_unique" | "context_children" | "scored" | "tombstone" | "api";
 export interface MatchBlock {
     /** present on old blocks; undefined on new blocks until assigned */
     blockId?: string;
@@ -34,6 +34,9 @@ export interface ReconcileConfig {
     maxScoredBlocks: number;
     smallBlockTokens: number;
     contextSimFloor: number;
+    /** phase-4b: minimum fraction of an old container's children that must have
+     * carried into one new container for the children to vouch for it (0.5). */
+    childrenVouchFrac: number;
 }
 export declare const DEFAULT_CONFIG: ReconcileConfig;
 /** The result of matching one document's old tree against new blocks. */

package/dist/src/reconcile/types.js

@@ -3,9 +3,17 @@
 // without ids) and produces an assignment: each new block either CARRIES an
 // existing id or is MINTED, plus a disposition per carry/mint.
 export const DEFAULT_CONFIG = {
-    matcherV: "m1.0",
+    // "m" + spec/reconcile/VERSION. m2.0: phase 4b (children vouch for their
+    // parent) and the phase-4 fixed point. m2.1: the four spec §10 fixes — phase 5
+    // skips (not stops at) a sub-threshold candidate, position_prior over the
+    // sibling count, every split and merge per run, split tombstones listed in
+    // `deleted`. m2.2: thetaSmall 0.80 → 0.62 (eval harness, 2026-09-26). m2.3:
+    // phase 4a's singleton rule — the lone unmatched child of a carried container
+    // carries into the lone unmatched child in the same slot without a text floor
+    // (2026-09-26). Rule refinements bump the minor; phase changes bump the major.
+    matcherV: "m2.3",
     thetaAccept: 0.62,
-    thetaSmall: 0.8,
+    thetaSmall: 0.62,
     thetaXdoc: 0.8,
     splitCoverage: 0.8,
     splitDominantShare: 0.7,
@@ -15,5 +23,6 @@ export const DEFAULT_CONFIG = {
     maxScoredBlocks: 2000,
     smallBlockTokens: 8,
     contextSimFloor: 0.35,
+    childrenVouchFrac: 0.5,
 };
 //# sourceMappingURL=types.js.map

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

@@ -11,3 +11,13 @@ export interface ExternalProvider {
  * failure. Callers must call close() when done.
  */
 export declare function createExternalProvider(settings: EmbeddingSettings): Promise<ExternalProvider | null>;
+/**
+ * The environment a stdio embedder is spawned with: our own env, with the
+ * repo's explicit `embedding.model` / `dim` / `maxInputTokens` settings laid over
+ * it as the `OMGBASE_EMBEDDER_*` variables `omgbase-embedder` reads. Explicit
+ * settings win over an inherited variable (config is the deliberate per-repo
+ * choice; the env is ambient); an unset setting leaves the inherited value (or
+ * the embedder's own default) in place. The handshake still has the last word on
+ * what the provider reports back (see connectStdio).
+ */
+export declare function embedderEnv(settings: EmbeddingSettings, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/src/search/external.js

@@ -67,7 +67,7 @@ async function connectStdio(settings) {
     // even after we exit. A private pipe we own severs that coupling.
     let child;
     try {
-        child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+        child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"], env: embedderEnv(settings) });
     }
     catch (err) {
         throw new Error(`embedding command '${settings.provider}' failed to spawn: ${err.message}`);
@@ -153,6 +153,23 @@ async function connectStdio(settings) {
     };
     return { provider, close };
 }
+/**
+ * The environment a stdio embedder is spawned with: our own env, with the
+ * repo's explicit `embedding.model` / `dim` / `maxInputTokens` settings laid over
+ * it as the `OMGBASE_EMBEDDER_*` variables `omgbase-embedder` reads. Explicit
+ * settings win over an inherited variable (config is the deliberate per-repo
+ * choice; the env is ambient); an unset setting leaves the inherited value (or
+ * the embedder's own default) in place. The handshake still has the last word on
+ * what the provider reports back (see connectStdio).
+ */
+export function embedderEnv(settings, base = process.env) {
+    return {
+        ...base,
+        ...(settings.model !== undefined ? { OMGBASE_EMBEDDER_MODEL: settings.model } : {}),
+        ...(settings.dim !== undefined ? { OMGBASE_EMBEDDER_DIM: String(settings.dim) } : {}),
+        ...(settings.maxInputTokens !== undefined ? { OMGBASE_EMBEDDER_MAX_TOKENS: String(settings.maxInputTokens) } : {}),
+    };
+}
 // A pull-based async line reader over a readline Interface: next() resolves with
 // the next line, buffering lines that arrive before they're requested.
 function lineQueue(rl) {

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

@@ -1,9 +1,13 @@
 export interface EmbeddingSettings {
-    /** Package name to import, e.g. "@omgbase/embedder". Absent ⇒ no provider. */
+    /** The embedder: a command to spawn (e.g. "omgbase-embedder") or an http(s)
+     *  URL. Absent ⇒ no provider (`semantic_unavailable`). */
     provider?: string;
-    /** Optional model id passed through to the provider factory. */
+    /** Optional model id. For a spawned command it is exported as
+     *  OMGBASE_EMBEDDER_MODEL (explicit setting wins over an inherited variable);
+     *  the provider's handshake/metadata reply overrides it for reporting. */
     model?: string;
-    /** Optional dimension override passed through to the provider factory. */
+    /** Optional dimension. For a spawned command it is exported as
+     *  OMGBASE_EMBEDDER_DIM; the handshake/metadata reply overrides it. */
     dim?: number;
     /**
      * Optional max input length (tokens) the provider's model accepts before it

package/dist/src/search/provider.js

@@ -1,10 +1,11 @@
-// Provider configuration (05 §6). The embedding provider is a plugin named in
-// repo settings (embedding.provider = a package that exports
-// `createProvider(opts?) => EmbeddingProvider`). The dynamic import itself lives
-// in the application (the CLI), not here, so it resolves against the app's
-// dependency tree and core carries no ML dependency. @omgbase/embedder is the
-// default local implementation; a remote HTTP provider is the same contract
-// behind a different package name — nothing privileges local vs. remote.
+// Provider configuration (05 §6). The embedding provider is an external
+// *process or endpoint* named in repo settings — `embedding.provider` is either
+// a shell command (spawned and spoken to over the stdio JSON protocol) or an
+// http(s) URL (GET metadata, POST embed) — see `search/external.ts`. Nothing is
+// imported in-process, so core carries no ML dependency and the embedder can be
+// any language. `@omgbase/embedder`'s `omgbase-embedder` binary is the default
+// local implementation; an HTTP endpoint is the same contract over the wire —
+// nothing privileges local vs. remote.
 /** Read the embedding.* block out of a repo's parsed settings JSON. */
 export function embeddingSettings(settings) {
     const e = settings.embedding;

package/dist/src/search/rrf.js

@@ -50,7 +50,10 @@ export function hybridSearch(store, input) {
     const vecRanks = new Map();
     const cosineByBlock = new Map();
     if (input.vector) {
+        // First occurrence wins, exactly as for FTS (spec/search §4).
         vectorSearch(store, input.repoId, input.vector.model, input.vector.vec, { limit: 200 }).forEach((h, i) => {
+            if (vecRanks.has(h.blockId))
+                return;
             vecRanks.set(h.blockId, i + 1);
             cosineByBlock.set(h.blockId, h.cosine);
         });

package/dist/src/search/vector.js

@@ -19,10 +19,18 @@ export function vectorSearch(store, repoId, model, queryVec, opts = {}) {
        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) => {
+    // One hit per live block (spec/search §3). Several cache rows can join to the
+    // same block — a stale ctx row survives a heading rename next to the fresh one
+    // — and the block keeps its best cosine, not one hit per row.
+    const best = new Map();
+    for (const r of rows) {
         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) };
-    });
+        const c = cosine(queryVec, v);
+        const prev = best.get(r.blockId);
+        if (!prev || c > prev.cosine)
+            best.set(r.blockId, { blockId: r.blockId, docId: r.docId, path: r.path, cosine: c });
+    }
+    const scored = [...best.values()];
     scored.sort((a, b) => b.cosine - a.cosine || (a.blockId < b.blockId ? -1 : 1));
     return scored.slice(0, limit);
 }
@@ -39,10 +47,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