@omgbase/core 0.1.0 → 0.3.0

package/dist/src/format/markdown.js

@@ -2,8 +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 { parse as parseYaml } from "yaml";
+import { extractFromBlock, extractFromFrontmatter, ownText, scanText, INLINE_FIELD_BRACKETED, INLINE_FIELD_LINE } from "../graph/extract.js";
 export const MARKDOWN_FORMAT = "markdown";
 function toAdapterEdge(e) {
     return {
@@ -23,7 +22,6 @@ export const markdownAdapter = {
         AdapterCapability.Parse,
         AdapterCapability.Render,
         AdapterCapability.ExtractEdges,
-        AdapterCapability.ExtractMetadata,
         AdapterCapability.ComputeProperties,
         AdapterCapability.StructuralMutation,
         AdapterCapability.ProjectNodes,
@@ -37,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)
@@ -58,24 +57,17 @@ export const markdownAdapter = {
         }
         return edges;
     },
-    extractMetadata(source) {
-        const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
-        if (!match)
-            return null;
-        try {
-            const parsed = parseYaml(match[1]);
-            return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-                ? parsed
-                : null;
-        }
-        catch {
-            return null;
-        }
-    },
+    // No `extractMetadata`: Markdown frontmatter is the `frontmatter` block of the
+    // parsed tree and nothing else (spec/properties §3.1), so ingest parses that
+    // block's YAML itself. The regex-over-the-source form this adapter used to
+    // carry disagreed with the block model — `---\nfoo: 1\n---bar\n` has no
+    // frontmatter block yet matched, and a fence containing a line that starts
+    // with `---` was cut short (spec/properties §8 "Fixed").
     projectNodes(blocks) {
         const nodes = [];
-        // Byte span of a regex match within the block's raw bytes (node-locates the
-        // feature inside its block; disambiguates multiple same-kind nodes — 13/nodes).
+        // Span of a regex match within the block's raw, as string indices (ingest
+        // converts to bytes at the store boundary — spec/graph §2.3). It locates the
+        // feature inside its block and disambiguates same-kind nodes (13/nodes).
         const span = (m) => ({
             spanStart: m.index ?? 0,
             spanEnd: (m.index ?? 0) + m[0].length,
@@ -85,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) });
@@ -109,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

@@ -12,6 +12,12 @@ export interface NodeChange {
 export declare function historyNode(store: Store, blockId: string, opts?: {
     limit?: number;
 }): NodeChange[];
+/** A `rev` that names no revision of the document (spec/surface §3: both sides of a diff must exist). The MCP layer maps it to `target_missing` with `{ doc, rev }`. */
+export declare class RevisionNotFound extends Error {
+    readonly docId: string;
+    readonly rev: string;
+    constructor(docId: string, rev: string);
+}
 export interface DiffEntry {
     kind: "added" | "removed" | "changed" | "unchanged";
     blockId: string;
@@ -19,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

@@ -14,6 +14,17 @@ export function historyNode(store, blockId, opts = {}) {
        LIMIT ?`)
         .all(blockId, limit);
 }
+/** A `rev` that names no revision of the document (spec/surface §3: both sides of a diff must exist). The MCP layer maps it to `target_missing` with `{ doc, rev }`. */
+export class RevisionNotFound extends Error {
+    docId;
+    rev;
+    constructor(docId, rev) {
+        super(`no revision ${JSON.stringify(rev)} for document ${docId}`);
+        this.docId = docId;
+        this.rev = rev;
+        this.name = "RevisionNotFound";
+    }
+}
 // Block-grain diff between two revisions of a document: compare block id → raw.
 export function diffBlocks(store, docId, fromRev, toRev) {
     const at = (rev) => blocksAtRevision(store, docId, rev);
@@ -41,9 +52,9 @@ export function diffBlocks(store, docId, fromRev, toRev) {
 // in core/read/document.ts readDocumentAtRevision.
 function blocksAtRevision(store, docId, revId) {
     const rev = store.db.prepare("SELECT root_tree FROM revisions WHERE rev_id = ? AND doc_id = ?").get(revId, docId);
-    const out = new Map();
     if (!rev)
-        return out;
+        throw new RevisionNotFound(docId, revId);
+    const out = new Map();
     const blob = store.db.prepare("SELECT bytes FROM blobs WHERE hash = ?");
     const treeNode = store.db.prepare("SELECT entries FROM tree_nodes WHERE hash = ?");
     const walk = (treeHashHex) => {
@@ -61,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

@@ -9,20 +9,21 @@ export { writeDocNodes, deleteDocNodes } from "./core/store/nodes.js";
 export { docPropertiesMerged, docPropertiesGrouped, writeDocProperties, flattenFrontmatter } from "./core/store/properties.js";
 import "./format/index.js";
 export { Store, type StoreOptions } from "./core/store/store.js";
-export { Workspace, RepoSelectionError, type RepoRow } from "./sync/workspace.js";
+export { Workspace, RepoSelectionError, selectRepo, type RepoRow } from "./sync/workspace.js";
 export { resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, deepMerge, type Settings, } from "./sync/settings.js";
-export { freshnessSweep, rebuildFileStats, recordFileStat, detectDiskDrift, type SweepResult, type DiskDrift } from "./sync/freshness.js";
+export { freshnessSweep, rebuildFileStats, recordFileStat, recordStat, detectDiskDrift, sweepPlan, sweepCandidates, loadStatCache, snapshotOf, type SweepResult, type DiskDrift, type SweepPlan, type StatCacheRow, type SnapshotEntry, } from "./sync/freshness.js";
+export { recoverRepo, type RecoveryResult } from "./sync/recovery.js";
 export { withWriterLock, writerLockFree, WriterLockTimeout } from "./sync/writer-lock.js";
 export { WatchLease, watchLeaseLive } from "./sync/watch-lease.js";
 export { ingestDirectory, type IngestDirResult } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
-export { walkMarkdown, walkMarkdownAsync } from "./sync/fs-util.js";
+export { walkMarkdown, walkMarkdownAsync, nodeFs, type SyncFs, type FileStat } from "./sync/fs-util.js";
 export { Watcher, type WatcherOptions } from "./sync/watcher.js";
 export type { SyncSource, SourceCapabilities, SourceIdentity, SourceEntry, SourceItem, SourceWatch, WatchListener, } from "./sync/plugin.js";
 export { createExternalSource, type ExternalSourceSpec } from "./sync/external-source.js";
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, type AdapterRow, type SourceRow, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";
-export { observeFile, observeMany, observeOne, observeDelete, type ObserveResult, type ObserveOneResult, type ObserveDeleteResult } from "./sync/observe.js";
+export { observeFile, observeMany, observeOne, observeDelete, observeBatch, type ObserveResult, type ObserveOneResult, type ObserveDeleteResult, type BatchItem, type BatchOutcome } from "./sync/observe.js";
 export { buildServer, type ServerContext } from "./mcp/server.js";
 export { serveStdio, type ServeStdioHandle } from "./mcp/stdio.js";
 export { processCheckpoint, type CheckpointResult } from "./sync/checkpoint.js";
@@ -42,12 +43,15 @@ 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 } from "./core/ids.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";
 export { type DocStore, FsDocStore, NullDocStore, resolveDocStore } from "./mutate/doc-store.js";
 export { type To, type At, type Expect } from "./mutate/ops.js";

package/dist/src/index.js

@@ -10,19 +10,20 @@ export { docPropertiesMerged, docPropertiesGrouped, writeDocProperties, flattenF
 import "./format/index.js";
 // Workspace + sync surface used by the CLI (second client, 11 §1).
 export { Store } from "./core/store/store.js";
-export { Workspace, RepoSelectionError } from "./sync/workspace.js";
+export { Workspace, RepoSelectionError, selectRepo } from "./sync/workspace.js";
 export { resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, deepMerge, } from "./sync/settings.js";
-export { freshnessSweep, rebuildFileStats, recordFileStat, detectDiskDrift } from "./sync/freshness.js";
+export { freshnessSweep, rebuildFileStats, recordFileStat, recordStat, detectDiskDrift, sweepPlan, sweepCandidates, loadStatCache, snapshotOf, } from "./sync/freshness.js";
+export { recoverRepo } from "./sync/recovery.js";
 export { withWriterLock, writerLockFree, WriterLockTimeout } from "./sync/writer-lock.js";
 export { WatchLease, watchLeaseLive } from "./sync/watch-lease.js";
 export { ingestDirectory } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
-export { walkMarkdown, walkMarkdownAsync } from "./sync/fs-util.js";
+export { walkMarkdown, walkMarkdownAsync, nodeFs } from "./sync/fs-util.js";
 export { Watcher } from "./sync/watcher.js";
 export { createExternalSource } from "./sync/external-source.js";
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";
-export { observeFile, observeMany, observeOne, observeDelete } from "./sync/observe.js";
+export { observeFile, observeMany, observeOne, observeDelete, observeBatch } from "./sync/observe.js";
 export { buildServer } from "./mcp/server.js";
 export { serveStdio } from "./mcp/stdio.js";
 export { processCheckpoint } from "./sync/checkpoint.js";
@@ -47,12 +48,16 @@ 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 } from "./core/ids.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).
 export { apply } from "./mutate/apply.js";
 export { FsDocStore, NullDocStore, resolveDocStore } from "./mutate/doc-store.js";