@omgbase/core 0.2.0 → 0.4.0

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

@@ -19,7 +19,8 @@ export { ingestDirectory, type IngestDirResult } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.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 type { SyncSource, SourceCapabilities, SourceIdentity, SourceEntry, SourceItem, SourceWatch, WatchEvent, WatchListener, } from "./sync/plugin.js";
+export { awaitReady, WATCH_READY_PATIENCE_MS } 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";
@@ -43,12 +44,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

@@ -20,6 +20,7 @@ export { ingestDirectory } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
 export { walkMarkdown, walkMarkdownAsync, nodeFs } from "./sync/fs-util.js";
 export { Watcher } from "./sync/watcher.js";
+export { awaitReady, WATCH_READY_PATIENCE_MS } from "./sync/plugin.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";
@@ -48,12 +49,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

@@ -45,14 +45,23 @@ const toSchema = z.object({
     ]),
     at: atSchema,
 });
+// blocks_insert / blocks_move carry the op-level expectation of spec/mutate §1.2:
+// only `parent_children_hash` (the destination parent's live direct child ids
+// joined by "," and sha256-hexed) has a meaning there — there is no target block
+// whose content_hash could be checked — so the schema names that one key alone
+// (an accidental `content_hash` is dropped, not an error; the kernel would
+// ignore it anyway).
+const parentExpectSchema = z.object({
+    parent_children_hash: z.string().optional(),
+});
 const expectSchema = z.object({
     content_hash: z.string().optional(),
     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() }),
@@ -279,7 +288,7 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("docs_get_many", {
-        description: "Batch whole-document read — the hydrate half of query→hydrate. The plural of docs_read: pass `docs`, a list of refs (each a doc id OR a path, same id-or-path symmetry docs_read accepts in its `doc` field), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`content` = complete file bytes verbatim, `properties` grouped by source, plus `path`/`docId`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block id → content hash} map for raw-`apply` CAS pinning, and a `parents` {block id → parent block id | null} map so top-level vs nested blocks are distinguishable without an outline read); a ref that resolves to no live document lands in `errors` as {ref, error:\"doc_not_found\"} WITHOUT failing the call, so one bad ref never sinks the batch. Duplicate refs collapse first-seen (a repeated ref yields a single item). Capped at " + MANY_DOCS_CAP + " refs per call; excess refs are dropped and `truncated` is set. Pass budget_tokens to cap total hydrated size — the batch stops early and flags `truncated` when the next doc would exceed it. Use this after query/text_search/resolve to pull N whole docs in ONE round-trip instead of N serial docs_read calls; for a single doc use docs_read, and for lean structure-only orientation use docs_outline.",
+        description: "Batch whole-document read — the hydrate half of query→hydrate. The plural of docs_read: pass `docs`, a list of refs (each a doc id OR a path, same id-or-path symmetry docs_read accepts in its `doc` field), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`content` = complete file bytes verbatim, `properties` grouped by source, plus `path`/`docId`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block id → content hash} map for raw-`apply` CAS pinning, and a `parents` {block id → parent block id | null} map so top-level vs nested blocks are distinguishable without an outline read); a ref that resolves to no live document lands in `errors` as {ref, error:\"doc_not_found\"} WITHOUT failing the call, so one bad ref never sinks the batch. Duplicate refs collapse first-seen (a repeated ref yields a single item). Capped at " + MANY_DOCS_CAP + " refs per call; excess refs are dropped and `truncated` is set. Pass budget_tokens to cap total hydrated size — the batch stops early and flags `truncated` when the next doc would exceed it; the FIRST doc always ships even when it alone exceeds the budget (the same at-least-one-row contract as docs_list/docs_tree, so a budgeted caller always makes progress). Use this after query/text_search/resolve to pull N whole docs in ONE round-trip instead of N serial docs_read calls; for a single doc use docs_read, and for lean structure-only orientation use docs_outline.",
         inputSchema: {
             docs: z.array(z.string()),
             include_ids: z.boolean().optional(),
@@ -322,7 +331,7 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("nodes_get_many", {
-        description: "Fetch up to 100 blocks by id (in request order) with budget truncation. Block ids are globally unique, so `ids` may span ANY number of documents — each id is resolved to its owning doc server-side; `doc`/`path` is an optional SCOPE (ids from other docs then count as unresolved), not a requirement. Result carries `nodes`, `truncated` (cap or `budget_tokens` hit), and `unresolved` — the requested ids that name no live block (never silently dropped).",
+        description: "Fetch up to 100 blocks by id (in request order) with budget truncation. Block ids are globally unique, so `ids` may span ANY number of documents — each id is resolved to its owning doc server-side; `doc`/`path` is an optional SCOPE (ids from other docs then count as unresolved), not a requirement. Result carries `nodes`, `truncated` (cap or `budget_tokens` hit — the first resolved node always ships even when it alone exceeds the budget, so a budgeted caller always makes progress), and `unresolved` — the requested ids that name no live block (never silently dropped).",
         inputSchema: {
             doc: z.string().optional(),
             path: z.string().optional(),
@@ -540,16 +549,18 @@ export function buildServer(ctx) {
     // local: the resolution that used to live in the CLI now lives next to the
     // store, so a remote client needs no local database.
     server.registerTool("blocks_insert", {
-        description: "Insert new block(s) parsed from `markdown` under a parent, at a position. `to` names the parent: a BLOCK ref (id or locator) nests the new blocks under that block, or a DOCUMENT ref (doc id or path) places them at the document's top level — so appending a new section to a document is `{ to: \"<path>\", markdown: \"## New\\n\\n…\" }` (the positional generalization of docs_append). `at` places among the parent's children: \"end\" (default) / \"start\" / {before|after: <block ref>}. Expands to one insert op through the kernel writer.",
-        inputSchema: { to: z.string(), markdown: z.string(), at: atSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
+        description: "Insert new block(s) parsed from `markdown` under a parent, at a position. `to` names the parent: a BLOCK ref (id or locator) nests the new blocks under that block, or a DOCUMENT ref (doc id or path) places them at the document's top level — so appending a new section to a document is `{ to: \"<path>\", markdown: \"## New\\n\\n…\" }` (the positional generalization of docs_append). `at` places among the parent's children: \"end\" (default) / \"start\" / {before|after: <block ref>}. Optional `expect.parent_children_hash` is the destination-parent CAS: the parent's CURRENT direct child ids (the document's top-level ids for a document `to`) joined by \",\" and sha256-hexed — compute it from docs_read include_ids (`ids` filtered by `parents`) — and the insert fails `stale_expectation` (with `data.current.parent_children_hash`) if the siblings changed under you; `content_hash` has no meaning here (there is no target block) and is not accepted. Expands to one insert op through the kernel writer.",
+        inputSchema: { to: z.string(), markdown: z.string(), at: atSchema.optional(), expect: parentExpectSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
             const { parent, docId } = resolveParentRef(repoId, args.to);
             const to = { parent, at: resolveAt(repoId, args.at) };
-            // A document parent carries no block to infer the doc from; pin it.
-            const ops = [{ op: "insert", ...(typeof parent === "object" ? { doc: docId } : {}), to, markdown: args.markdown }];
+            // A document parent carries no block to infer the doc from; pin it. The
+            // caller's expect rides through as the op-level expectation (spec/mutate
+            // §1.2: checked against the destination parent before the op mutates).
+            const ops = [{ op: "insert", ...(typeof parent === "object" ? { doc: docId } : {}), to, markdown: args.markdown, ...(args.expect ? { expect: args.expect } : {}) }];
             return applyOps(repoId, root, ops, "blocks_insert", args.dry_run);
         }
         catch (e) {
@@ -583,8 +594,8 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("blocks_move", {
-        description: "Move block(s) under a new parent at a position. `blocks` are block refs; `to` (the parent) is a block ref, or the blocks' OWN document (id or path) to move them to its top level — moving to ANOTHER document's root is not expressible (target_missing): anchor on a block in that document with `at` {before|after} instead. `at` is \"end\"/\"start\"/{before|after: <ref>}. One move op through the kernel writer.",
-        inputSchema: { blocks: z.array(z.string()), to: z.string(), at: atSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
+        description: "Move block(s) under a new parent at a position. `blocks` are block refs; `to` (the parent) is a block ref, or the blocks' OWN document (id or path) to move them to its top level — moving to ANOTHER document's root is not expressible (target_missing): anchor on a block in that document with `at` {before|after} instead. `at` is \"end\"/\"start\"/{before|after: <ref>}. Optional `expect.parent_children_hash` is the destination-parent CAS (as blocks_insert: the destination parent's CURRENT direct child ids joined by \",\", sha256 hex), checked once for the whole run before anything moves — `stale_expectation` with `data.current.parent_children_hash` if the destination's children changed; `content_hash` is meaningless here and not accepted. One move op through the kernel writer.",
+        inputSchema: { blocks: z.array(z.string()), to: z.string(), at: atSchema.optional(), expect: parentExpectSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
@@ -597,7 +608,7 @@ export function buildServer(ctx) {
                 throw new EngineError("target_missing", `blocks_move cannot target another document's root (${args.to}); anchor on a block in that document with at.before/at.after`, { data: { to: args.to } });
             }
             const to = { parent, at: resolveAt(repoId, args.at) };
-            const ops = [{ op: "move", blocks, to }];
+            const ops = [{ op: "move", blocks, to, ...(args.expect ? { expect: args.expect } : {}) }];
             return applyOps(repoId, root, ops, "blocks_move", args.dry_run);
         }
         catch (e) {
@@ -939,7 +950,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.d.ts

@@ -20,4 +20,15 @@ export declare function makeStoreContext(store: Store, repoId: string, opts?: St
 /** Tag SQL rows with their target so the store context resolves them (used by the
  * tier-3 planner to hand produced rows back for residual evaluation). */
 export declare function tagRows(rows: Record<string, unknown>[], target: Target): unknown[];
+/**
+ * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
+ * values, 1.2) is rendered as `{ id, path }` — its id column and its document's
+ * path, the same two keys every hit carries — never the store row itself.
+ * Returns undefined for anything that is not a tagged row (run.ts leaves those
+ * alone).
+ */
+export declare function rowRef(value: unknown): {
+    id: string;
+    path: string;
+} | undefined;
 export { TARGET };

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);
@@ -597,5 +610,21 @@ function hex(b) {
 export function tagRows(rows, target) {
     return tagAll(rows, target);
 }
+/**
+ * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
+ * values, 1.2) is rendered as `{ id, path }` — its id column and its document's
+ * path, the same two keys every hit carries — never the store row itself.
+ * Returns undefined for anything that is not a tagged row (run.ts leaves those
+ * alone).
+ */
+export function rowRef(value) {
+    const t = value?.[TARGET];
+    if (!t)
+        return undefined;
+    const r = value;
+    const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : r.edge_id;
+    const path = t === "docs" ? r.path : r.__path;
+    return { id: String(id), path: String(path ?? "") };
+}
 export { TARGET };
 //# sourceMappingURL=context.js.map