@omgbase/core 0.2.0 → 0.3.0

package/dist/src/core/clock.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Pin the wall clock to `ts` (RFC 3339): `new Date()` and `Date.now()` return
+ * that instant until the returned restore function runs. Explicit-argument
+ * constructions (`new Date(ms)`, `new Date(iso)`) and the static parsers are
+ * untouched. Throws `RangeError` when `ts` does not parse.
+ */
+export declare function pinClock(ts: string): () => void;
+/** Run `body` under `pinClock(ts)` (a no-op when `ts` is undefined), restoring the clock afterwards. */
+export declare function withClock<T>(ts: string | undefined, body: () => Promise<T>): Promise<T>;

package/dist/src/core/clock.js

@@ -0,0 +1,46 @@
+// The process clock seam (spec/surface §7.1). Every commit the engine stamps
+// reads "now" through `new Date()` / `Date.now()` (`ingest`, `apply`, the doc
+// ops, `observe*`, checkpoints — none caches a `Date`), so pinning the global
+// `Date` pins every timestamp a tool call produces. Two users: the surface
+// fixtures (`corpus/surface/fixture.ts`, per `read` step) and `omg mcp` under
+// `OMGBASE_SPEC_CLOCK` (for the whole process). Never used in production paths.
+/**
+ * Pin the wall clock to `ts` (RFC 3339): `new Date()` and `Date.now()` return
+ * that instant until the returned restore function runs. Explicit-argument
+ * constructions (`new Date(ms)`, `new Date(iso)`) and the static parsers are
+ * untouched. Throws `RangeError` when `ts` does not parse.
+ */
+export function pinClock(ts) {
+    const RealDate = Date;
+    const fixed = RealDate.parse(ts);
+    if (Number.isNaN(fixed))
+        throw new RangeError(`pinClock: not an RFC 3339 instant: ${JSON.stringify(ts)}`);
+    class PinnedDate extends RealDate {
+        constructor(...args) {
+            if (args.length === 0)
+                super(fixed);
+            else
+                super(...args);
+        }
+        static now() {
+            return fixed;
+        }
+    }
+    globalThis.Date = PinnedDate;
+    return () => {
+        globalThis.Date = RealDate;
+    };
+}
+/** Run `body` under `pinClock(ts)` (a no-op when `ts` is undefined), restoring the clock afterwards. */
+export async function withClock(ts, body) {
+    if (ts === undefined)
+        return body();
+    const restore = pinClock(ts);
+    try {
+        return await body();
+    }
+    finally {
+        restore();
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/src/core/store/writers.d.ts

@@ -9,6 +9,12 @@ export interface TreeInputBlock {
     trivia: string;
     attrs: Record<string, unknown>;
     children: TreeInputBlock[];
+    /** The parsed block's source span, when the tree came from a parse — what
+     *  `ownText` (spec/properties §3.2) uses to blank a container's children. */
+    span?: {
+        start: number;
+        end: number;
+    };
 }
 /** Assign fresh minted ids to a parsed block tree (Stage-1 re-mint path). */
 export declare function assignIds(blocks: RawBlock[]): TreeInputBlock[];

package/dist/src/core/store/writers.js

@@ -9,6 +9,7 @@ export function assignIds(blocks) {
         trivia: b.trivia,
         attrs: b.attrs,
         children: assignIds(b.children),
+        span: b.span,
     }));
 }
 /** Content-address raw text into blobs; returns hex hash. Dedups. */

package/dist/src/format/markdown.js

@@ -2,7 +2,7 @@
 import { AdapterCapability } from "./adapter.js";
 import { parseTree, assertFullCoverage } from "../core/parse/tree.js";
 import { render } from "../core/parse/render.js";
-import { extractFromBlock, extractFromFrontmatter, maskCode } from "../graph/extract.js";
+import { extractFromBlock, extractFromFrontmatter, ownText, scanText, INLINE_FIELD_BRACKETED, INLINE_FIELD_LINE } from "../graph/extract.js";
 export const MARKDOWN_FORMAT = "markdown";
 function toAdapterEdge(e) {
     return {
@@ -35,14 +35,15 @@ export const markdownAdapter = {
     extractEdges(blocks, metadata) {
         const edges = [];
         // Walk every block (recursing into list/blockquote/table nesting) and scan
-        // its raw for links. srcBlock is the block's OWN assigned id — the caller
-        // passes id-assigned blocks (blockId zipped on), mirroring projectNodes; a
-        // block-grain edge without it is useless, so fall back to "" only for the
-        // pre-identity callers. extractFromBlock returns [] for link-free blocks, so
-        // no per-block gate is needed (matches the non-adapter fallback path).
+        // its OWN text for links (spec/graph §1: the raw with the children blanked,
+        // so a link in an item is the item's edge only). srcBlock is the block's
+        // OWN assigned id — the caller passes id-assigned blocks (blockId zipped
+        // on), mirroring projectNodes; a block-grain edge without it is useless, so
+        // fall back to "" only for the pre-identity callers. extractFromBlock
+        // returns [] for link-free blocks, so no per-block gate is needed.
         const walk = (list) => {
             for (const block of list) {
-                for (const e of extractFromBlock(block.blockId ?? "", block.type, block.raw)) {
+                for (const e of extractFromBlock(block.blockId ?? "", block.type, ownText(block))) {
                     edges.push(toAdapterEdge(e));
                 }
                 if (block.children.length > 0)
@@ -76,12 +77,13 @@ export const markdownAdapter = {
                 // Anchor to the block's OWN assigned id (zipped on by ingest); fall back
                 // to the parent's id, then "root", for pre-identity/parse-time callers.
                 const id = b.blockId || parentId || "root";
-                // Code is not prose (extraction_version x2): a code_fence block projects
-                // no link/anchor/field nodes, and inline code spans are masked before the
-                // regex scans below. Same rule as graph/extract.ts so the md:link /
-                // md:wikilink nodes and the `references` edges agree. maskCode is
-                // length-preserving, so spans still index the ORIGINAL raw.
-                const scan = b.type === "code_fence" ? "" : maskCode(b.raw);
+                // The block's own text (spec/graph §1): children blanked, so a feature
+                // belongs to the innermost block only; then code masked — a code_fence
+                // block projects no link/anchor/field nodes, and inline code spans are
+                // blanked (extraction_version x2). Same rule as graph/extract.ts so the
+                // md:link / md:wikilink nodes and the `references` edges agree. Both
+                // masks are length-preserving, so spans still index the ORIGINAL raw.
+                const scan = scanText(b);
                 // Links: [text](target)
                 for (const m of scan.matchAll(/\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
                     nodes.push({ kind: "md:link", name: m[1], value: m[2], blockId: id, ...span(m) });
@@ -100,20 +102,22 @@ export const markdownAdapter = {
                 for (const m of scan.matchAll(anchorRe)) {
                     nodes.push({ kind: "md:anchor", name: m[1], blockId: id, ...span(m) });
                 }
-                // Inline fields (dataview forms). Two shapes, so a multi-word value is
-                // captured whole instead of truncated at the first space:
-                //   line form  `key:: value`  — key at line start, value to end of line
+                // Inline fields (dataview forms; the patterns are spec/properties §3.2's,
+                // shared with the properties scanner). Two shapes, so a multi-word value
+                // is captured whole instead of truncated at the first space:
+                //   line form  `key:: value`  — key at line start (after blanks and, since
+                //              1.1, an optional list marker + task checkbox), value to
+                //              end of line; span from the key to the trimmed value's end
                 //   bracketed  `[key:: value]` / `(key:: value)` — value ends at closer
-                // Bracketed matches first; the line form is anchored to a line start
-                // (leading whitespace only), so a `[key:: …]`/`(key:: …)` sitting on its
-                // own line is not double-counted (a bracket is not `[a-z]`).
-                for (const m of scan.matchAll(/[[(]([a-z][a-z0-9_]*)::[ \t]*([^\]\n)]*?)[ \t]*[\])]/gi)) {
+                // Bracketed matches first; a `[key:: …]`/`(key:: …)` sitting on its own
+                // line is not double-counted (a bracket is not `[a-z]`).
+                for (const m of scan.matchAll(INLINE_FIELD_BRACKETED)) {
                     nodes.push({ kind: "md:inline_field", name: m[1], value: m[2], blockId: id, ...span(m) });
                 }
-                for (const m of scan.matchAll(/^[ \t]*([a-z][a-z0-9_]*)::[ \t]*([^\n]*?)[ \t]*$/gim)) {
-                    const start = (m.index ?? 0) + (m[0].match(/^[ \t]*/)?.[0].length ?? 0);
+                for (const m of scan.matchAll(INLINE_FIELD_LINE)) {
+                    const start = (m.index ?? 0) + m[1].length;
                     const end = (m.index ?? 0) + m[0].replace(/[ \t]+$/, "").length;
-                    nodes.push({ kind: "md:inline_field", name: m[1], value: m[2], blockId: id, spanStart: start, spanEnd: end });
+                    nodes.push({ kind: "md:inline_field", name: m[2], value: m[3], blockId: id, spanStart: start, spanEnd: end });
                 }
                 if (b.children.length > 0)
                     walk(b.children, id);

package/dist/src/graph/extract.d.ts

@@ -11,6 +11,42 @@ export interface ExtractedEdge {
     anchor: string | null;
     provenance: Provenance;
 }
+/** Bracketed form: `[key:: value]` / `(key:: value)` anywhere in prose; the value
+ *  runs to the first closer (either bracket), trimmed of spaces and tabs. */
+export declare const INLINE_FIELD_BRACKETED: RegExp;
+/** Line form (1.1): a key at the start of a line — after blanks and optionally
+ *  a list marker (`-`/`*`/`+`/`1.`/`1)`) and a task checkbox — with the value
+ *  to the end of the line, trimmed. Group 1 is the prefix (so a span can start
+ *  at the key), 2 the key as written, 3 the trimmed value. A bracketed field on
+ *  its own line is not also a line-form match: `[`/`(` is not `[a-z]`. */
+export declare const INLINE_FIELD_LINE: RegExp;
+interface SpannedBlock {
+    raw: string;
+    span: {
+        start: number;
+        end: number;
+    };
+    children: SpannedBlock[];
+}
+/**
+ * A block's own text: its `raw` with the span of every DIRECT child blanked to
+ * spaces (newlines kept, like `maskCode`, so line structure survives). A child
+ * sits at `child.span.start - block.span.start` in the parent's raw (spans are
+ * source offsets; spec/format §1 inv. 3 puts a child inside its parent). That
+ * offset is trusted only when the parent's raw actually reads `child.raw`
+ * there; otherwise — callers that hand in blocks without real spans (a tree
+ * rebuilt from store rows carries `{0,0}`), which the invariant makes impossible
+ * for a parsed tree — the child is located as the first occurrence of its raw
+ * at or after the previous child's end, and skipped when not found. Length-
+ * preserving: offsets into the result are offsets into `raw`.
+ */
+export declare function ownText(block: SpannedBlock): string;
+/** What the scanners see for a block: nothing for a `code_fence`, else
+ *  `maskCode(ownText(block))` — own text first (a child's fence is blanked
+ *  either way), code second. Same length as `raw`. */
+export declare function scanText(block: SpannedBlock & {
+    type: string;
+}): string;
 /**
  * Resolve a `./foo` / `../bar` destination against the source document's
  * directory (`docDir` = path with the filename stripped, e.g. "a/b/" or "").
@@ -33,6 +69,10 @@ export declare function normalizeUri(uri: string): string;
  */
 export declare function maskCode(raw: string): string;
 /** Extract edges from a single block's raw markdown. Code is skipped: a
- *  `code_fence` block yields nothing, and inline code spans are masked. */
+ *  `code_fence` block yields nothing, and inline code spans are masked. Pass the
+ *  block's own text (`ownText`) for a container so its children's features are
+ *  not counted again here — the adapter does; a caller with only a stored raw
+ *  (no children) passes it as is. */
 export declare function extractFromBlock(blockId: string, blockType: string, rawInput: string): ExtractedEdge[];
 export declare function extractFromFrontmatter(fm: Record<string, unknown>): ExtractedEdge[];
+export {};

package/dist/src/graph/extract.js

@@ -10,6 +10,12 @@
 // (and links_stale no longer reports them as dangling). There is no persisted
 // extraction version — an existing repo re-extracts a document the next time
 // that document is ingested (checkpoint/observe/apply), not via rebuild-index.
+//
+// spec/properties 1.1 + spec/graph 1.1: every scanner runs over the block's
+// OWN text — `maskCode(ownText(block))`, the raw with each direct child's span
+// blanked — so a feature inside a list item belongs to the item (the innermost
+// block that contains it), never also to the list; and the inline-field line
+// form admits a list marker and a task checkbox (`- key:: v`, `- [ ] due:: x`).
 export const EXTRACTION_VERSION = "x2";
 // --- link/inline scanners (operate on a block's raw markdown) ----------------
 const MD_LINK = /(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g; // [t](dest) / ![alt](dest)
@@ -17,6 +23,55 @@ const WIKILINK = /(!?)\[\[([^\]]+)\]\]/g; // [[note]] / [[note#H]] / [[note^ref]
 const BARE_URL = /(?<![("[])\bhttps?:\/\/[^\s)>\]]+/g;
 const AUTOLINK = /<(https?:\/\/[^>]+)>/g;
 const INLINE_FIELD = /(?:^|\s)([a-z][a-z0-9_]*)::\s*(\[\[[^\]]+\]\]|\/[^\s]+|https?:\/\/[^\s]+)/gi;
+// --- inline-field forms (spec/properties §3.2; shared with md:inline_field) ---
+/** Bracketed form: `[key:: value]` / `(key:: value)` anywhere in prose; the value
+ *  runs to the first closer (either bracket), trimmed of spaces and tabs. */
+export const INLINE_FIELD_BRACKETED = /[[(]([a-z][a-z0-9_]*)::[ \t]*([^\]\n)]*?)[ \t]*[\])]/gi;
+/** Line form (1.1): a key at the start of a line — after blanks and optionally
+ *  a list marker (`-`/`*`/`+`/`1.`/`1)`) and a task checkbox — with the value
+ *  to the end of the line, trimmed. Group 1 is the prefix (so a span can start
+ *  at the key), 2 the key as written, 3 the trimmed value. A bracketed field on
+ *  its own line is not also a line-form match: `[`/`(` is not `[a-z]`. */
+export const INLINE_FIELD_LINE = /^([ \t]*(?:(?:[-*+]|\d{1,9}[.)])[ \t]+(?:\[[ xX]\][ \t]+)?)?)([a-z][a-z0-9_]*)::[ \t]*([^\n]*?)[ \t]*$/gim;
+/**
+ * A block's own text: its `raw` with the span of every DIRECT child blanked to
+ * spaces (newlines kept, like `maskCode`, so line structure survives). A child
+ * sits at `child.span.start - block.span.start` in the parent's raw (spans are
+ * source offsets; spec/format §1 inv. 3 puts a child inside its parent). That
+ * offset is trusted only when the parent's raw actually reads `child.raw`
+ * there; otherwise — callers that hand in blocks without real spans (a tree
+ * rebuilt from store rows carries `{0,0}`), which the invariant makes impossible
+ * for a parsed tree — the child is located as the first occurrence of its raw
+ * at or after the previous child's end, and skipped when not found. Length-
+ * preserving: offsets into the result are offsets into `raw`.
+ */
+export function ownText(block) {
+    if (block.children.length === 0)
+        return block.raw;
+    const raw = block.raw;
+    let out = raw;
+    let cursor = 0;
+    for (const child of block.children) {
+        const len = child.raw.length;
+        if (len === 0)
+            continue;
+        let at = child.span.start - block.span.start;
+        if (!(at >= cursor && at + len <= raw.length && raw.startsWith(child.raw, at))) {
+            at = raw.indexOf(child.raw, cursor);
+            if (at < 0)
+                continue;
+        }
+        out = out.slice(0, at) + blank(child.raw) + out.slice(at + len);
+        cursor = at + len;
+    }
+    return out;
+}
+/** What the scanners see for a block: nothing for a `code_fence`, else
+ *  `maskCode(ownText(block))` — own text first (a child's fence is blanked
+ *  either way), code second. Same length as `raw`. */
+export function scanText(block) {
+    return block.type === "code_fence" ? "" : maskCode(ownText(block));
+}
 function splitAnchor(target) {
     const hashIdx = target.indexOf("#");
     const caretIdx = target.indexOf("^");
@@ -161,7 +216,10 @@ export function maskCode(raw) {
     return out;
 }
 /** Extract edges from a single block's raw markdown. Code is skipped: a
- *  `code_fence` block yields nothing, and inline code spans are masked. */
+ *  `code_fence` block yields nothing, and inline code spans are masked. Pass the
+ *  block's own text (`ownText`) for a container so its children's features are
+ *  not counted again here — the adapter does; a caller with only a stored raw
+ *  (no children) passes it as is. */
 export function extractFromBlock(blockId, blockType, rawInput) {
     const edges = [];
     if (blockType === "code_fence")

package/dist/src/graph/history.d.ts

@@ -25,8 +25,40 @@ export interface DiffEntry {
     after?: string;
 }
 export declare function diffBlocks(store: Store, docId: string, fromRev: string, toRev: string): DiffEntry[];
-/** Unified textual diff (line-based) between two revisions' rendered files. */
+/** `diff_unified` (spec/surface §3): a unified diff of two revisions' rendered
+ * texts — each revision's live raws joined by `\n` — via {@link unifiedDiff}. */
 export declare function diffUnified(store: Store, docId: string, fromRev: string, toRev: string): string;
+/** How each text becomes lines: `split("\n")` exactly — no trimming, no
+ * dropping of a trailing empty element (a raw ending in `\n` yields one) — with
+ * a single special case: the empty text has *no* lines (an empty file is zero
+ * lines, not one empty line), so a diff from/to nothing is `@@ -0,0 +1,n @@`. */
+export declare function diffLines(text: string): string[];
+/** One step of the edit script: `keep` consumes a line from both sides,
+ * `delete` one from the old text, `insert` one from the new text. */
+export interface EditOp {
+    kind: "keep" | "delete" | "insert";
+    line: string;
+}
+/**
+ * Myers' O(ND) shortest edit script (forward, with a per-`d` trace for the
+ * backtrack). `V[k]` is the furthest x on diagonal `k = x - y` reachable with
+ * `d` edits. The canonical tie rule, identical in both engines: at each step
+ * take the diagonal from `k+1` (moving down — an insertion of `b[y]`) when
+ * `k == -d || (k != d && V[k-1] < V[k+1])`, else from `k-1` (moving right —
+ * a deletion of `a[x]`). On a tie (`V[k-1] == V[k+1]`) that is the deletion.
+ */
+export declare function myersScript(a: string[], b: string[]): EditOp[];
+/**
+ * The unified diff of two texts (spec/surface §3): hunks of `DIFF_CONTEXT` (3)
+ * lines of context; a change group extends to include the next change when
+ * fewer than `2 * DIFF_CONTEXT + 1` unchanged lines separate them (the two
+ * contexts touch or overlap). Each hunk is `@@ -a,b +c,d @@` (1-based start
+ * and length; a length of 1 is written as the start alone; a length of 0 as
+ * `a,0` with `a` the line before the insertion point, `0` at the very top)
+ * followed by its lines prefixed `-`, `+` or a space with nothing after the
+ * sign; hunks joined by `\n`; no file header; identical texts → `""`.
+ */
+export declare function unifiedDiff(oldText: string, newText: string): string;
 export interface CommitDigest {
     commit: string;
     seq: number;

package/dist/src/graph/history.js

@@ -72,26 +72,149 @@ function blocksAtRevision(store, docId, revId) {
     walk(rev.root_tree.toString("hex"));
     return out;
 }
-/** Unified textual diff (line-based) between two revisions' rendered files. */
+/** `diff_unified` (spec/surface §3): a unified diff of two revisions' rendered
+ * texts — each revision's live raws joined by `\n` — via {@link unifiedDiff}. */
 export function diffUnified(store, docId, fromRev, toRev) {
-    const rendered = (rev) => {
-        const map = blocksAtRevision(store, docId, rev);
-        return [...map.values()].join("\n");
-    };
-    const a = rendered(fromRev).split("\n");
-    const b = rendered(toRev).split("\n");
-    // Minimal line diff (not a full Myers; sufficient for digests/preview).
-    const out = [];
-    const max = Math.max(a.length, b.length);
-    for (let i = 0; i < max; i++) {
-        if (a[i] === b[i])
-            continue;
-        if (a[i] !== undefined)
-            out.push(`- ${a[i]}`);
-        if (b[i] !== undefined)
-            out.push(`+ ${b[i]}`);
+    const rendered = (rev) => [...blocksAtRevision(store, docId, rev).values()].join("\n");
+    return unifiedDiff(rendered(fromRev), rendered(toRev));
+}
+// ---- unified diff (spec/surface §3) ------------------------------------------
+// A line-grain unified diff with a deterministic Myers script, so both engines
+// (this reference and crates/omgbase-surface/src/history.rs) produce the same
+// bytes for the same two texts. Kept pure so it can be pinned by unit tests.
+/** How each text becomes lines: `split("\n")` exactly — no trimming, no
+ * dropping of a trailing empty element (a raw ending in `\n` yields one) — with
+ * a single special case: the empty text has *no* lines (an empty file is zero
+ * lines, not one empty line), so a diff from/to nothing is `@@ -0,0 +1,n @@`. */
+export function diffLines(text) {
+    return text === "" ? [] : text.split("\n");
+}
+const DIFF_CONTEXT = 3;
+/**
+ * Myers' O(ND) shortest edit script (forward, with a per-`d` trace for the
+ * backtrack). `V[k]` is the furthest x on diagonal `k = x - y` reachable with
+ * `d` edits. The canonical tie rule, identical in both engines: at each step
+ * take the diagonal from `k+1` (moving down — an insertion of `b[y]`) when
+ * `k == -d || (k != d && V[k-1] < V[k+1])`, else from `k-1` (moving right —
+ * a deletion of `a[x]`). On a tie (`V[k-1] == V[k+1]`) that is the deletion.
+ */
+export function myersScript(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const max = n + m;
+    // V is indexed by k ∈ [-max-1, max+1]; `off` maps it onto a plain array.
+    const off = max + 1;
+    const v = new Array(2 * max + 3).fill(0);
+    const trace = [];
+    let found = false;
+    for (let d = 0; d <= max && !found; d++) {
+        trace.push(v.slice());
+        for (let k = -d; k <= d; k += 2) {
+            let x;
+            if (k === -d || (k !== d && v[off + k - 1] < v[off + k + 1]))
+                x = v[off + k + 1];
+            else
+                x = v[off + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[off + k] = x;
+            if (x >= n && y >= m) {
+                found = true;
+                break;
+            }
+        }
+    }
+    // Backtrack from (n, m) through the trace, emitting ops newest-first.
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d >= 0; d--) {
+        const vd = trace[d];
+        const k = x - y;
+        const prevK = k === -d || (k !== d && vd[off + k - 1] < vd[off + k + 1]) ? k + 1 : k - 1;
+        const prevX = vd[off + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            x--;
+            y--;
+            ops.push({ kind: "keep", line: a[x] });
+        }
+        if (d > 0) {
+            if (x === prevX)
+                ops.push({ kind: "insert", line: b[prevY] });
+            else
+                ops.push({ kind: "delete", line: a[prevX] });
+        }
+        x = prevX;
+        y = prevY;
+    }
+    ops.reverse();
+    return ops;
+}
+/**
+ * The unified diff of two texts (spec/surface §3): hunks of `DIFF_CONTEXT` (3)
+ * lines of context; a change group extends to include the next change when
+ * fewer than `2 * DIFF_CONTEXT + 1` unchanged lines separate them (the two
+ * contexts touch or overlap). Each hunk is `@@ -a,b +c,d @@` (1-based start
+ * and length; a length of 1 is written as the start alone; a length of 0 as
+ * `a,0` with `a` the line before the insertion point, `0` at the very top)
+ * followed by its lines prefixed `-`, `+` or a space with nothing after the
+ * sign; hunks joined by `\n`; no file header; identical texts → `""`.
+ */
+export function unifiedDiff(oldText, newText) {
+    const ops = myersScript(diffLines(oldText), diffLines(newText));
+    // Old/new line counts consumed before each op (0-based positions).
+    const oldPos = new Array(ops.length + 1);
+    const newPos = new Array(ops.length + 1);
+    let o = 0;
+    let nn = 0;
+    for (let i = 0; i < ops.length; i++) {
+        oldPos[i] = o;
+        newPos[i] = nn;
+        if (ops[i].kind !== "insert")
+            o++;
+        if (ops[i].kind !== "delete")
+            nn++;
+    }
+    oldPos[ops.length] = o;
+    newPos[ops.length] = nn;
+    const changes = [];
+    for (let i = 0; i < ops.length; i++)
+        if (ops[i].kind !== "keep")
+            changes.push(i);
+    if (changes.length === 0)
+        return "";
+    const hunks = [];
+    let g = 0;
+    while (g < changes.length) {
+        const first = changes[g];
+        let last = first;
+        // Merge rule: the next change joins this hunk iff the unchanged lines
+        // between them number at most 2 * DIFF_CONTEXT.
+        while (g + 1 < changes.length && changes[g + 1] - last - 1 <= 2 * DIFF_CONTEXT) {
+            g++;
+            last = changes[g];
+        }
+        g++;
+        const start = Math.max(0, first - DIFF_CONTEXT);
+        const end = Math.min(ops.length - 1, last + DIFF_CONTEXT);
+        const oldLen = oldPos[end + 1] - oldPos[start];
+        const newLen = newPos[end + 1] - newPos[start];
+        const range = (pos, len) => {
+            const startLine = len === 0 ? pos : pos + 1;
+            return len === 1 ? `${startLine}` : `${startLine},${len}`;
+        };
+        const lines = [`@@ -${range(oldPos[start], oldLen)} +${range(newPos[start], newLen)} @@`];
+        for (let i = start; i <= end; i++) {
+            const op = ops[i];
+            lines.push((op.kind === "keep" ? " " : op.kind === "delete" ? "-" : "+") + op.line);
+        }
+        hunks.push(lines.join("\n"));
     }
-    return out.join("\n");
+    return hunks.join("\n");
 }
 /** changes_since: commit digests after a cursor (repo commit seq) — the change
  * feed (06 §3). `seq` is a dense per-REPO total order, so a cursor is only

package/dist/src/index.d.ts

@@ -43,12 +43,13 @@ export { embeddingSettings, type EmbeddingSettings } from "./search/provider.js"
 export { createExternalProvider, type ExternalProvider } from "./search/external.js";
 export { hybridSearch, type HybridHit, type HybridInput } from "./search/rrf.js";
 export { vectorSearch, docVectorSearch, type VectorHit, type DocVectorHit } from "./search/vector.js";
-export { historyNode, diffUnified, changesSince, type NodeChange, type CommitDigest } from "./graph/history.js";
+export { historyNode, diffUnified, unifiedDiff, changesSince, type NodeChange, type CommitDigest } from "./graph/history.js";
 export { docLinks, type LinksResult, type LinkEdge, type LinksOptions } from "./graph/links.js";
 export { FilterInvalid } from "./search/cel/parser.js";
 export { EngineError, type ErrorCode } from "./mcp/errors.js";
 export { MutationError } from "./mutate/tree.js";
 export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, type IdMinter, type IdPrefix } from "./core/ids.js";
+export { pinClock, withClock } from "./core/clock.js";
 export { sha256 } from "./core/hash.js";
 export { ingestFile, type IngestResult } from "./core/ingest.js";
 export { apply, type ApplyRequest, type ApplyResult, type Op } from "./mutate/apply.js";

package/dist/src/index.js

@@ -48,12 +48,14 @@ export { embeddingSettings } from "./search/provider.js";
 export { createExternalProvider } from "./search/external.js";
 export { hybridSearch } from "./search/rrf.js";
 export { vectorSearch, docVectorSearch } from "./search/vector.js";
-export { historyNode, diffUnified, changesSince } from "./graph/history.js";
+export { historyNode, diffUnified, unifiedDiff, changesSince } from "./graph/history.js";
 export { docLinks } from "./graph/links.js";
 export { FilterInvalid } from "./search/cel/parser.js";
 export { EngineError } from "./mcp/errors.js";
 export { MutationError } from "./mutate/tree.js";
 export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter } from "./core/ids.js";
+// The clock seam (spec/surface §7.1): `omg mcp` pins the process clock under OMGBASE_SPEC_CLOCK.
+export { pinClock, withClock } from "./core/clock.js";
 export { sha256 } from "./core/hash.js";
 export { ingestFile } from "./core/ingest.js";
 // Mutation surface consumed by CLI write commands (11 §5.6).

package/dist/src/mcp/server.js

@@ -50,9 +50,9 @@ const expectSchema = z.object({
     parent_children_hash: z.string().optional(),
 });
 const opSchema = z.discriminatedUnion("op", [
-    z.object({ op: z.literal("insert"), doc: z.string().optional(), to: toSchema, markdown: z.string() }),
+    z.object({ op: z.literal("insert"), doc: z.string().optional(), to: toSchema, markdown: z.string(), expect: expectSchema.optional() }),
     z.object({ op: z.literal("update"), block: z.string(), markdown: z.string().optional(), attrs: z.record(z.string(), z.unknown()).optional(), expect: expectSchema.optional() }),
-    z.object({ op: z.literal("move"), blocks: z.array(z.string()), to: toSchema }),
+    z.object({ op: z.literal("move"), blocks: z.array(z.string()), to: toSchema, expect: expectSchema.optional() }),
     z.object({ op: z.literal("remove"), blocks: z.array(z.string()), expect: z.record(z.string(), expectSchema).optional() }),
     z.object({ op: z.literal("split"), block: z.string(), at: z.array(z.number().int()), expect: expectSchema.optional() }),
     z.object({ op: z.literal("merge"), blocks: z.array(z.string()), separator: z.string().optional(), expect: z.record(z.string(), expectSchema).optional() }),
@@ -939,7 +939,7 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("diff_unified", {
-        description: "Line-based unified diff between two revisions of a document (the `omg diff` rendering): returns `{ doc, path, from, to, diff }` where `diff` is the +/- unified text. `from_rev`/`to_rev` default to the previous and current revisions ('what did the last commit change here'). Contrast `diff`, which returns block-grain added/removed/changed entries.",
+        description: "Unified diff between two revisions of a document (the `omg diff` rendering): returns `{ doc, path, from, to, diff }` where `diff` is a unified diff of the two rendered texts (Myers shortest edit script; `@@ -a,b +c,d @@` hunks with 3 lines of context; lines prefixed `-`, `+` or a space; no file header; identical texts → \"\"). `from_rev`/`to_rev` default to the previous and current revisions ('what did the last commit change here'). Contrast `diff`, which returns block-grain added/removed/changed entries.",
         inputSchema: { doc: z.string(), from_rev: z.string().optional(), to_rev: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {

package/dist/src/mutate/apply.d.ts

@@ -6,6 +6,7 @@ export type Op = {
     doc?: string;
     to: To;
     markdown: string;
+    expect?: Expect;
 } | {
     op: "update";
     block: string;
@@ -18,6 +19,7 @@ export type Op = {
     op: "move";
     blocks: string[];
     to: To;
+    expect?: Expect;
 } | {
     op: "remove";
     blocks: string[];

package/dist/src/mutate/apply.js

@@ -6,7 +6,7 @@ import { makeReconcilingResolver } from "../sync/reconciling-ingest.js";
 import { makeKnownIdResolver } from "./known-ids.js";
 import { loadMutDoc } from "./load.js";
 import { renderDoc, markContainerDirty, MutationError } from "./tree.js";
-import { opInsert, opUpdate, opMove, opRemove, opSplit, opMerge, healTopLevelSeams } from "./ops.js";
+import { opInsert, opUpdate, opMove, opRemove, opSplit, opMerge, healTopLevelSeams, checkParentChildrenHash } from "./ops.js";
 import { withWriterLock } from "../sync/writer-lock.js";
 import { resolveDocStore } from "./doc-store.js";
 // Resolve "$n.ids[i]" placeholders in a string against prior op results.
@@ -92,7 +92,7 @@ export function apply(store, req) {
                     ? resolveDocRef(store, req.repoId, rawOp.doc)
                     : parentDoc(store, req.repoId, to, loaded);
                 const d = ensureDoc(docId);
-                results.push(opInsert(d, to, rawOp.markdown));
+                results.push(opInsert(d, to, rawOp.markdown, rawOp.expect, i));
                 break;
             }
             case "update": {
@@ -114,11 +114,11 @@ export function apply(store, req) {
                 const topLevelSameDoc = typeof to.parent === "object" && "doc" in to.parent && typeof to.at === "string";
                 const dstDocId = topLevelSameDoc ? srcDocId : parentDoc(store, req.repoId, to, loaded);
                 if (dstDocId === srcDocId) {
-                    results.push(opMove(ensureDoc(srcDocId), blocks, to, i));
+                    results.push(opMove(ensureDoc(srcDocId), blocks, to, i, rawOp.expect));
                 }
                 else {
                     // Cross-document move (04 §1): extract from source, insert into target.
-                    results.push(crossDocMove(ensureDoc(srcDocId), ensureDoc(dstDocId), blocks, to, i));
+                    results.push(crossDocMove(ensureDoc(srcDocId), ensureDoc(dstDocId), blocks, to, i, rawOp.expect));
                 }
                 break;
             }
@@ -239,7 +239,7 @@ function throwMissing(id) {
     throw new MutationError("parent_missing", `parent ${id} not found`);
 }
 // Cross-document move: extract the contiguous run from src, insert into dst.
-function crossDocMove(src, dst, blockIds, to, opIndex) {
+function crossDocMove(src, dst, blockIds, to, opIndex, expect) {
     // Extract from src (must be a contiguous top-level or same-parent run).
     const moving = [];
     for (const id of blockIds) {
@@ -248,6 +248,9 @@ function crossDocMove(src, dst, blockIds, to, opIndex) {
             throw new MutationError("block_missing", `block ${id} not found in source doc`, { op_index: opIndex });
         moving.push(found.block);
     }
+    // §1.2: the destination parent's order CAS (in `dst`), before either tree moves.
+    if (expect?.parent_children_hash !== undefined)
+        checkParentChildrenHash(resolveDstTarget(dst, to).siblings, expect, opIndex);
     // remove from their source lists (marking each emptied owner dirty)
     for (const id of blockIds) {
         const f = locateMut(src, id);

package/dist/src/mutate/known-ids.js

@@ -32,7 +32,7 @@ function assignFromMut(blocks, byKey) {
     const walk = (list, parentKey) => list.map((b, index) => {
         const key = `${parentKey ?? ""}/${index}`;
         const blockId = byKey.get(key) ?? mintId("b");
-        return { blockId, type: b.type, raw: b.raw, trivia: b.trivia, attrs: b.attrs, children: walk(b.children, key) };
+        return { blockId, type: b.type, raw: b.raw, trivia: b.trivia, attrs: b.attrs, children: walk(b.children, key), span: b.span };
     });
     return walk(blocks, null);
 }
@@ -41,7 +41,7 @@ function assignFromMut(blocks, byKey) {
 function collectRawBlocks(blocks) {
     return blocks.map((b) => ({
         type: b.type,
-        span: { start: 0, end: 0 },
+        span: b.span ?? { start: 0, end: 0 },
         raw: b.raw,
         text: "",
         attrs: b.attrs,

package/dist/src/mutate/ops.d.ts

@@ -17,13 +17,14 @@ export interface Expect {
     content_hash?: string;
     parent_children_hash?: string;
 }
-export declare function opInsert(doc: MutDoc, to: To, markdown: string): {
+export declare function checkParentChildrenHash(siblings: MutBlock[], expect: Expect | undefined, opIndex: number): void;
+export declare function opInsert(doc: MutDoc, to: To, markdown: string, expect?: Expect, opIndex?: number): {
     ids: string[];
 };
 export declare function opUpdate(doc: MutDoc, blockId: string, opIndex: number, markdown?: string, attrs?: Record<string, unknown>, expect?: Expect, trivia?: string, childIds?: Record<string, string>): {
     ids: string[];
 };
-export declare function opMove(doc: MutDoc, blockIds: string[], to: To, opIndex: number): {
+export declare function opMove(doc: MutDoc, blockIds: string[], to: To, opIndex: number, expect?: Expect): {
     ids: string[];
 };
 export declare function healTopLevelSeams(children: MutBlock[], format: string): void;
@@ -38,4 +39,3 @@ export declare function opMerge(doc: MutDoc, blockIds: string[], opIndex: number
     ids: string[];
     mergedInto: string[];
 };
-export declare function checkParentChildrenHash(doc: MutDoc, parentId: string | null, expected: string, opIndex: number): void;

package/dist/src/mutate/ops.js

@@ -113,6 +113,20 @@ function checkContentHash(block, expect, opIndex) {
         });
     }
 }
+// §1.2 `check_parent_children_hash`: when the expectation carries a
+// `parent_children_hash`, the LIVE direct children of the sibling list it names
+// (the document top level for `doc.children`) must hash to it. Which list is the
+// op's business: update/split/remove/merge pass the block's current sibling list,
+// insert/move the destination's (resolved as the op resolves `to`). Always after
+// the content CAS and before the tree is touched, so a stale order never lands.
+export function checkParentChildrenHash(siblings, expect, opIndex) {
+    if (expect?.parent_children_hash === undefined)
+        return;
+    const current = parentChildrenHash(siblings);
+    if (current !== expect.parent_children_hash) {
+        throw new MutationError("stale_expectation", "parent_children_hash mismatch", { op_index: opIndex, current: { parent_children_hash: current }, retriable: true });
+    }
+}
 // Assign known ids onto a freshly-parsed subtree by positional key (parentKey +
 // '/' + index), the same convention flatten()/known-ids use. Keys absent from
 // the map leave the block's minted id in place (a genuinely new child).
@@ -140,8 +154,11 @@ function markSubtreeClean(b) {
         markSubtreeClean(c);
 }
 // ---- the six ops ------------------------------------------------------------
-export function opInsert(doc, to, markdown) {
+export function opInsert(doc, to, markdown, expect, opIndex = 0) {
     const { siblings, index } = resolveTarget(doc, to);
+    // §1.2: the destination parent's order CAS — `siblings` IS the resolved parent
+    // list (a section scope or a `{ doc: true }` anchor both name the top level).
+    checkParentChildrenHash(siblings, expect, opIndex);
     let blocks = parseContentToBlocks(markdown, doc.format);
     // Inserting into a list: the content must land as list ITEMS, not a nested
     // list. Markdown `- x` parses to a `list` wrapping a `list_item`; unwrap it to
@@ -204,6 +221,8 @@ export function opUpdate(doc, blockId, opIndex, markdown, attrs, expect, trivia,
     // juggling post-op content hashes across the changeset.
     if (markdown !== undefined || expect?.content_hash !== undefined)
         checkContentHash(found.block, expect, opIndex);
+    // §1.2: the block's CURRENT parent, after the content CAS.
+    checkParentChildrenHash(found.siblings, expect, opIndex);
     // Blocks minted from MULTI-block content: the target takes the first parsed
     // block (keeping its id); the rest become fresh siblings right after it.
     const extra = [];
@@ -309,7 +328,7 @@ export function opUpdate(doc, blockId, opIndex, markdown, attrs, expect, trivia,
     }
     return { ids: [blockId, ...extra.map((b) => b.id)] };
 }
-export function opMove(doc, blockIds, to, opIndex) {
+export function opMove(doc, blockIds, to, opIndex, expect) {
     if (blockIds.length === 0)
         throw new MutationError("not_contiguous", "move requires ≥1 block");
     // Locate all; assert contiguous siblings.
@@ -333,6 +352,12 @@ export function opMove(doc, blockIds, to, opIndex) {
     if (typeof to.parent === "string" && movedIds.has(to.parent)) {
         throw new MutationError("cycle_move", "target is inside the moved subtree", { op_index: opIndex });
     }
+    // §1.2: the DESTINATION parent's order CAS, resolved on the pre-removal tree
+    // (before the op mutates anything) and checked once for the whole run. When
+    // source and destination are one list this is the "same siblings reordered
+    // under me" guard: the hash covers the moved blocks' current positions too.
+    if (expect?.parent_children_hash !== undefined)
+        checkParentChildrenHash(resolveTarget(doc, to).siblings, expect, opIndex);
     // Extract (preserve order) then re-insert at the target.
     const moving = located.map((l) => l.block);
     for (const m of moving) {
@@ -395,8 +420,11 @@ export function opRemove(doc, blockIds, opIndex, expectPer) {
                 hint: "the id is not a live block of the targeted document — it may have been removed by an earlier op in this changeset (removing a block removes its whole subtree), or never existed",
             });
         }
-        if (expectPer?.[id])
-            checkContentHash(found.block, expectPer[id], opIndex);
+        const e = expectPer?.[id];
+        if (e) {
+            checkContentHash(found.block, e, opIndex);
+            checkParentChildrenHash(found.siblings, e, opIndex); // §1.2: its current parent
+        }
         if (!hasAncestorIn(doc, found.siblings, set))
             tops.push(id);
     }
@@ -454,6 +482,7 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     if (!found)
         throw new MutationError("block_missing", `block ${blockId} not found`, { op_index: opIndex, block: blockId });
     checkContentHash(found.block, expect, opIndex);
+    checkParentChildrenHash(found.siblings, expect, opIndex); // §1.2: its current parent
     const raw = found.block.raw;
     // `at` are UTF-8 byte offsets into the raw (spec/mutate §2.5) — the same
     // language-neutral unit every persisted span uses. A JavaScript string slices
@@ -509,8 +538,11 @@ export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
             throw new MutationError("not_contiguous", "merge blocks must share a parent", { op_index: opIndex });
         if (located[i].block.type !== type)
             throw new MutationError("type_mismatch", "merge blocks must share a type", { op_index: opIndex });
-        if (expectPer?.[blockIds[i]])
-            checkContentHash(located[i].block, expectPer[blockIds[i]], opIndex);
+        const e = expectPer?.[blockIds[i]];
+        if (e) {
+            checkContentHash(located[i].block, e, opIndex);
+            checkParentChildrenHash(located[i].siblings, e, opIndex); // §1.2: its current parent
+        }
     }
     for (let i = 1; i < indices.length; i++)
         if (indices[i] !== indices[i - 1] + 1)
@@ -525,11 +557,4 @@ export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
         siblings.splice(indices[i], 1);
     return { ids: [first.id], mergedInto };
 }
-export function checkParentChildrenHash(doc, parentId, expected, opIndex) {
-    const list = parentId ? locate(doc, parentId)?.block.children ?? doc.children : doc.children;
-    const current = parentChildrenHash(list);
-    if (current !== expected) {
-        throw new MutationError("stale_expectation", "parent_children_hash mismatch", { op_index: opIndex, current: { parent_children_hash: current }, retriable: true });
-    }
-}
 //# sourceMappingURL=ops.js.map

package/dist/src/oqx-js/context.js

@@ -17,6 +17,8 @@ import { docsRead } from "../core/read/document.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { sanitizeFtsQuery } from "../search/fts-query.js";
 import { cosineBytes } from "../core/vec.js";
+import { ctxHashHex } from "../search/embeddings.js";
+import { makeBlockContextResolver } from "../search/tasks.js";
 const TARGET = Symbol("oqx.target");
 const REPO_ROOT = Symbol("oqx.repoRoot");
 const PROP_SOURCE = Symbol("oqx.propSource");
@@ -470,6 +472,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
         // blocks
         return !!one(`SELECT 1 FROM blocks_fts WHERE rowid = (SELECT rowid FROM blocks WHERE block_id = ?) AND blocks_fts MATCH ?`, r.block_id, match);
     };
+    // A block's vector is the cache row for its CURRENT (raw_hash, ctx_hash)
+    // (spec/surface §1.3, spec/search §3 — since search 1.1; before, the first row
+    // for the raw_hash whatever its context). The context resolver is built once
+    // per query (one scan of titles and sections), then a per-block chain walk.
+    let blockContexts;
+    const blockVector = (r, model) => {
+        blockContexts ??= makeBlockContextResolver(store, { repoId });
+        const path = typeof r.__path === "string" ? r.__path : String(scalar(`SELECT path FROM docs WHERE doc_id = ?`, r.doc_id) ?? "");
+        const ctx = blockContexts.ctx({ doc_id: String(r.doc_id), path, ordinal: Number(r.ordinal), type: String(r.type) });
+        return one(`SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?`, r.raw_hash, Buffer.from(ctxHashHex(ctx), "hex"), model);
+    };
     const semanticScore = (t, r, phrase) => {
         if (t === "nodes" || t === "edges")
             throw new FilterInvalid("semantic(...) is available on the docs and blocks targets", "OQX semantic");
@@ -478,7 +491,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
             throw new FilterInvalid(`semantic(${JSON.stringify(phrase)}) needs an embedding provider; none is configured for this query`, "OQX semantic");
         const row = t === "docs"
             ? one(`SELECT vec FROM doc_embeddings WHERE doc_id = ? AND model = ?`, r.doc_id, resolved.model)
-            : one(`SELECT vec FROM embeddings WHERE content_hash = ? AND model = ? LIMIT 1`, r.raw_hash, resolved.model);
+            : blockVector(r, resolved.model);
         if (!row)
             return null;
         return cosineBytes(row.vec, resolved.vec);

package/dist/src/search/rrf.js

@@ -50,7 +50,8 @@ 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).
+        // First occurrence wins, exactly as for FTS (spec/search §4). Since search
+        // 1.1 vectorSearch yields one candidate per block, so this is a no-op guard.
         vectorSearch(store, input.repoId, input.vector.model, input.vector.vec, { limit: 200 }).forEach((h, i) => {
             if (vecRanks.has(h.blockId))
                 return;

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,25 +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);
-    // 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);
-        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 });
+    // 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) });
     }
-    const scored = [...best.values()];
     scored.sort((a, b) => b.cosine - a.cosine || (a.blockId < b.blockId ? -1 : 1));
     return scored.slice(0, limit);
 }

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

@@ -87,7 +87,14 @@ export interface DiskDrift {
 export declare function detectDiskDrift(store: Store, repoId: string, rootPath: string, opts?: {
     fs?: SyncFs;
 }): DiskDrift;
-/** Rebuild file_stats from scratch by re-statting + re-hashing every file. */
+/**
+ * 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 rebuildFileStats(store: Store, repoId: string, rootPath: string, opts?: {
     fs?: SyncFs;
 }): number;

package/dist/src/sync/freshness.js

@@ -147,16 +147,36 @@ export function detectDiskDrift(store, repoId, rootPath, opts = {}) {
             deleted += 1;
     return { changed, deleted, untracked };
 }
-/** Rebuild file_stats from scratch by re-statting + re-hashing every file. */
+/**
+ * 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);
+    // 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 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;
-        recordStat(store, repoId, path, fs.stat(rootPath, path), sha256(bytes));
+            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/reconciling-ingest.js

@@ -105,7 +105,7 @@ function assignFromMap(blocks, assignment) {
     const walk = (list, parentKey) => list.map((b, index) => {
         const key = `${parentKey ?? ""}/${index}`;
         const blockId = assignment.get(key) ?? mintId("b");
-        return { blockId, type: b.type, raw: b.raw, trivia: b.trivia, attrs: b.attrs, children: walk(b.children, key) };
+        return { blockId, type: b.type, raw: b.raw, trivia: b.trivia, attrs: b.attrs, children: walk(b.children, key), span: b.span };
     });
     return walk(blocks, null);
 }
@@ -260,11 +260,13 @@ function resolveAdapterEdge(db, repoId, srcDoc, e, docDir) {
         provenance: e.provenance,
     };
 }
-// Collect RawBlock-shaped objects from the id-assigned tree for adapter edge extraction.
+// Collect RawBlock-shaped objects from the id-assigned tree for adapter edge
+// extraction. The parsed span rides along so the adapter can blank a
+// container's children (spec/graph §1 own text).
 function collectRawBlocks(blocks) {
     return blocks.map((b) => ({
         type: b.type,
-        span: { start: 0, end: 0 },
+        span: b.span ?? { start: 0, end: 0 },
         raw: b.raw,
         text: "",
         attrs: b.attrs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Open Markdown Graph Base — embedded engine",
   "license": "MIT",
   "repository": {
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@omgbase/oqx": "^0.12.0",
+    "@omgbase/oqx": "^0.13.0",
     "better-sqlite3": "^13.0.3",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-frontmatter": "^2.0.1",