@omgbase/core 0.10.0 → 0.11.0

package/dist/src/graph/links.js

@@ -13,7 +13,7 @@ export function docLinks(store, docId, opts = {}) {
                 .all(docId);
             for (const r of rows)
                 if (inPred(r.predicate))
-                    out.push({ predicate: r.predicate, node: r.dst_node, kind: r.dst_kind, count: 1, block: r.src_block });
+                    out.push({ predicate: r.predicate, doc_id: r.dst_node, kind: r.dst_kind, count: 1, block_id: r.src_block });
         }
         else {
             const rows = store.db
@@ -23,7 +23,7 @@ export function docLinks(store, docId, opts = {}) {
             for (const r of rows) {
                 if (!inPred(r.predicate))
                     continue;
-                out.push({ predicate: r.predicate, node: r.dst_node, kind: r.dst_kind, count: r.count, samples: JSON.parse(r.samples) });
+                out.push({ predicate: r.predicate, doc_id: r.dst_node, kind: r.dst_kind, count: r.count, samples: JSON.parse(r.samples) });
             }
         }
     }
@@ -35,7 +35,7 @@ export function docLinks(store, docId, opts = {}) {
                 .all(docId);
             for (const r of rows)
                 if (inPred(r.predicate))
-                    inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: 1, block: r.src_block });
+                    inbound.push({ predicate: r.predicate, doc_id: r.src_doc, kind: "document", count: 1, block_id: r.src_block });
         }
         else {
             const rows = store.db
@@ -45,7 +45,7 @@ export function docLinks(store, docId, opts = {}) {
                 .all(docId);
             for (const r of rows)
                 if (inPred(r.predicate))
-                    inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: r.cnt });
+                    inbound.push({ predicate: r.predicate, doc_id: r.src_doc, kind: "document", count: r.cnt });
         }
     }
     return { out, in: inbound };

package/dist/src/index.d.ts

@@ -5,6 +5,7 @@ export type { FormatAdapter, AdapterEdge, ProjectedNode, EmbeddingChunk, Reconci
 export { AdapterCapability } from "./format/adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";
 export { markdownAdapter, MARKDOWN_FORMAT } from "./format/markdown.js";
+export { isContainerBlock } from "./format/index.js";
 export { yamlAdapter, YAML_FORMAT } from "./format/yaml.js";
 export { jsonAdapter, JSON_FORMAT } from "./format/json.js";
 export { writeDocNodes, deleteDocNodes } from "./core/store/nodes.js";
@@ -34,7 +35,7 @@ export { reposStatus, syncStatus, reposList, type RepoStatus, type SyncStatus, t
 export { docsOutline, type OutlineResult, type OutlineOptions } from "./core/read/outline.js";
 export { docsRead, reconstructContent, type DocsReadResult, type DocsReadOptions } from "./core/read/document.js";
 export { nodesGet, nodesGetMany, type GetNode, type Resolution } from "./core/read/nodes.js";
-export { findDoc, loadDocBlocks, blockRaw, docsList, docsTree, normalizeTreePrefix, DOCS_LIST_DEFAULT_LIMIT, DOCS_TREE_DEFAULT_LIMIT, type DocInfo, type BlockNode, type DocListRow, type DocListPage, type DocListOptions, type DocTreeEntry, type DocTreePage, type DocTreeOptions, } from "./core/read/reader.js";
+export { findDoc, findDocByRef, loadDocBlocks, blockRaw, docsList, docsTree, normalizeTreePrefix, DOCS_LIST_DEFAULT_LIMIT, DOCS_TREE_DEFAULT_LIMIT, type DocInfo, type BlockNode, type DocListRow, type DocListPage, type DocListOptions, type DocTreeEntry, type DocTreePage, type DocTreeOptions, } from "./core/read/reader.js";
 export { CursorInvalid, encodeCursor, decodeCursor, decodePathCursor } from "./core/cursor.js";
 export { referencePath, storagePath, referencePathOrNull, referenceKeyed } from "./core/paths.js";
 export * from "./surface-paths.js";

package/dist/src/index.js

@@ -4,6 +4,7 @@ export { SPEC_VERSIONS } from "./spec-versions.js";
 export { AdapterCapability } from "./format/adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";
 export { markdownAdapter, MARKDOWN_FORMAT } from "./format/markdown.js";
+export { isContainerBlock } from "./format/index.js";
 export { yamlAdapter, YAML_FORMAT } from "./format/yaml.js";
 export { jsonAdapter, JSON_FORMAT } from "./format/json.js";
 export { writeDocNodes, deleteDocNodes } from "./core/store/nodes.js";
@@ -35,7 +36,7 @@ export { reposStatus, syncStatus, reposList } from "./sync/admin.js";
 export { docsOutline } from "./core/read/outline.js";
 export { docsRead, reconstructContent } from "./core/read/document.js";
 export { nodesGet, nodesGetMany } from "./core/read/nodes.js";
-export { findDoc, loadDocBlocks, blockRaw, docsList, docsTree, normalizeTreePrefix, DOCS_LIST_DEFAULT_LIMIT, DOCS_TREE_DEFAULT_LIMIT, } from "./core/read/reader.js";
+export { findDoc, findDocByRef, loadDocBlocks, blockRaw, docsList, docsTree, normalizeTreePrefix, DOCS_LIST_DEFAULT_LIMIT, DOCS_TREE_DEFAULT_LIMIT, } from "./core/read/reader.js";
 export { CursorInvalid, encodeCursor, decodeCursor, decodePathCursor } from "./core/cursor.js";
 export { referencePath, storagePath, referencePathOrNull, referenceKeyed } from "./core/paths.js";
 export * from "./surface-paths.js";

package/dist/src/mcp/arguments.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { EngineError } from "./errors.js";
+/** One tool's argument shape: the zod raw shape it was registered with. */
+export type ArgShape = Record<string, z.ZodTypeAny>;
+/** The `(tool takes …)` tail: names in bytewise order, `?` on the optional ones. */
+export declare function argumentsHint(tool: string, shape: ArgShape): string;
+/** A `filter_invalid` for an argument-shape failure: the message plus the tool's shape. */
+export declare function argumentError(tool: string, message: string, shape: ArgShape): EngineError;
+/**
+ * Validate `raw` against `shape`: unknown names first (in bytewise order), then
+ * each declared argument (bytewise order) for presence and type. Returns the
+ * arguments with any `undefined` members dropped; throws the first failure.
+ */
+export declare function validateArguments(tool: string, shape: ArgShape, raw: unknown): Record<string, unknown>;
+/**
+ * What to say about an argument name the tool does not take. The names 3.0
+ * retired are called out with their replacement (`doc` → `id`/`path`,
+ * `block`/`node` → `id`, `heading` → `section`,
+ * `markdown` → `text`) when the tool has the replacement; otherwise the
+ * nearest valid name (Levenshtein ≤ 2, or one a prefix of the other).
+ */
+export declare function unknownArgumentMessage(key: string, shape: ArgShape): string;
+/** The nearest candidate: Levenshtein distance ≤ 2, or a prefix relation either way; ties → the bytewise-first. */
+export declare function nearest(name: string, candidates: readonly string[]): string | null;
+export declare function levenshtein(a: string, b: string): number;
+/** The expected-type phrase of an argument, as the Rust catalog spells it from its JSON schema. */
+export declare function phraseFor(schema: z.ZodTypeAny): string;

package/dist/src/mcp/arguments.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { EngineError } from "./errors.js";
+/** The `(tool takes …)` tail: names in bytewise order, `?` on the optional ones. */
+export function argumentsHint(tool, shape) {
+    const names = Object.keys(shape).sort(cmpBytes);
+    if (names.length === 0)
+        return `${tool} takes no arguments`;
+    return `${tool} takes ${names.map((n) => (isOptional(shape[n]) ? `${n}?` : n)).join(", ")}`;
+}
+/** A `filter_invalid` for an argument-shape failure: the message plus the tool's shape. */
+export function argumentError(tool, message, shape) {
+    const full = `${message} (${argumentsHint(tool, shape)})`;
+    return new EngineError("filter_invalid", full, { data: { reason: full, hint: "arguments" } });
+}
+/**
+ * Validate `raw` against `shape`: unknown names first (in bytewise order), then
+ * each declared argument (bytewise order) for presence and type. Returns the
+ * arguments with any `undefined` members dropped; throws the first failure.
+ */
+export function validateArguments(tool, shape, raw) {
+    if (raw === undefined || raw === null)
+        raw = {};
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw argumentError(tool, "arguments must be an object", shape);
+    const args = raw;
+    for (const key of Object.keys(args).sort(cmpBytes)) {
+        if (!(key in shape))
+            throw argumentError(tool, unknownArgumentMessage(key, shape), shape);
+    }
+    const out = {};
+    for (const key of Object.keys(shape).sort(cmpBytes)) {
+        const schema = shape[key];
+        const value = args[key];
+        if (value === undefined) {
+            if (!isOptional(schema))
+                throw argumentError(tool, `\`${key}\` is required`, shape);
+            continue;
+        }
+        const parsed = schema.safeParse(value);
+        if (!parsed.success)
+            throw argumentError(tool, issueMessage(key, schema, parsed.error.issues), shape);
+        // The value as sent, not zod's copy: the schemas here coerce nothing, and
+        // the kernel-op grammar (`apply.ops`) keeps keys the schema does not name.
+        out[key] = value;
+    }
+    return out;
+}
+/** The first failure, spelled for the argument: a top-level type mismatch is
+ *  "`key` must be <phrase>"; a failure inside a nested shape (`ops[0].block`)
+ *  names the path — "is required" when the member is absent, else "must be
+ *  <zod's expected type>". Nested wording is the reference's own (the Rust
+ *  catalog checks nested shapes in its handlers); the top-level form is pinned. */
+function issueMessage(key, schema, issues) {
+    const issue = issues[0];
+    if (!issue || issue.path.length === 0)
+        return `\`${key}\` must be ${phraseFor(schema)}`;
+    const at = key + issue.path.map((p) => (typeof p === "number" ? `[${p}]` : `.${String(p)}`)).join("");
+    if (issue.code === "invalid_type" && issue.input === undefined)
+        return `\`${at}\` is required`;
+    const expected = { string: "a string", number: "an integer", boolean: "a boolean", object: "an object", array: "an array" };
+    return `\`${at}\` must be ${issue.expected !== undefined ? (expected[issue.expected] ?? issue.expected) : "valid"}`;
+}
+/**
+ * What to say about an argument name the tool does not take. The names 3.0
+ * retired are called out with their replacement (`doc` → `id`/`path`,
+ * `block`/`node` → `id`, `heading` → `section`,
+ * `markdown` → `text`) when the tool has the replacement; otherwise the
+ * nearest valid name (Levenshtein ≤ 2, or one a prefix of the other).
+ */
+export function unknownArgumentMessage(key, shape) {
+    const has = (n) => n in shape;
+    const retired = (replacement) => `\`${key}\` is no longer an argument — pass ${replacement}`;
+    if (key === "doc" && has("id") && has("path"))
+        return retired("`id` or `path`");
+    if ((key === "block" || key === "node") && has("id"))
+        return retired("`id`");
+    if (key === "heading" && has("section"))
+        return retired("`section` (the heading's text), or blocks_append with the heading's `id`");
+    if (key === "markdown" && has("text"))
+        return retired("`text`");
+    const near = nearest(key, Object.keys(shape));
+    return near === null ? `unknown argument \`${key}\`` : `unknown argument \`${key}\`; did you mean \`${near}\`?`;
+}
+/** The nearest candidate: Levenshtein distance ≤ 2, or a prefix relation either way; ties → the bytewise-first. */
+export function nearest(name, candidates) {
+    let best = null;
+    for (const c of [...candidates].sort(cmpBytes)) {
+        const d = levenshtein(name, c);
+        const prefix = name.length > 0 && c.length > 0 && (c.startsWith(name) || name.startsWith(c));
+        if (d > 2 && !prefix)
+            continue;
+        const score = prefix && d > 2 ? 3 : d;
+        if (best === null || score < best.score)
+            best = { name: c, score };
+    }
+    return best?.name ?? null;
+}
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[n];
+}
+function cmpBytes(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function defOf(schema) {
+    return schema._zod.def;
+}
+function isOptional(schema) {
+    const d = defOf(schema);
+    return d.type === "optional" || (d.type === "nullable" && isOptional(d.innerType));
+}
+function unwrap(schema) {
+    const d = defOf(schema);
+    return d.type === "optional" || d.type === "nullable" ? unwrap(d.innerType) : schema;
+}
+/** The expected-type phrase of an argument, as the Rust catalog spells it from its JSON schema. */
+export function phraseFor(schema) {
+    const d = defOf(unwrap(schema));
+    switch (d.type) {
+        case "string": return "a string";
+        case "number": return "an integer";
+        case "boolean": return "a boolean";
+        case "object":
+        case "record": return "an object";
+        case "enum": return `one of ${Object.values(d.entries ?? {}).map(String).join(", ")}`;
+        case "array": {
+            const inner = defOf(unwrap(d.element)).type;
+            return `an array of ${inner === "string" ? "strings" : inner === "number" ? "integers" : "objects"}`;
+        }
+        case "union": return "\"start\", \"end\", {before} or {after}";
+        default: return "valid";
+    }
+}
+//# sourceMappingURL=arguments.js.map

package/dist/src/mcp/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = "stale_expectation" | "parent_missing" | "target_missing" | "block_missing" | "doc_missing" | "cycle_move" | "opaque_block" | "not_contiguous" | "type_mismatch" | "conflicted_document" | "path_taken" | "create_conflict" | "ambiguous_locator" | "ambiguous_heading" | "filter_invalid" | "budget_exceeded" | "semantic_unavailable" | "embedder_failed" | "sync_conflict" | "repo_not_found" | "node_not_editable" | "seed_unresolved";
+export type ErrorCode = "stale_expectation" | "parent_missing" | "target_missing" | "block_missing" | "doc_missing" | "cycle_move" | "opaque_block" | "not_contiguous" | "type_mismatch" | "conflicted_document" | "path_taken" | "create_conflict" | "ambiguous_locator" | "ambiguous_heading" | "filter_invalid" | "budget_exceeded" | "provider_unavailable" | "embedder_failed" | "sync_conflict" | "repo_not_found" | "node_not_editable" | "seed_unresolved" | "block_not_container";
 export interface EngineErrorBody {
     error: ErrorCode;
     message: string;

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

@@ -11,25 +11,32 @@ export interface GraphArgs {
     /** restrict the neighborhood to documents reachable from a root via edges of
      * this predicate, within `degrees` (both the docs and the edges are filtered). */
     predicate?: string | undefined;
-    /** extra document projections (OQX select expressions, e.g. "layer", "$path"). */
+    /** extra document projections (OQX select expressions, e.g. "layer", "path"). */
     select?: string[] | undefined;
     /** cap on the distinct documents returned (default 200). */
     max_documents?: number | undefined;
 }
-/** A traversed edge with full provenance (mirrors the `edges` target's rows). */
+/** A traversed edge: a row of the `links` target under its own field names
+ *  (spec/surface §1.2, 3.0 — `id` the edge, `doc_id`/`block_id` the source,
+ *  `via_id`, `dst_id` the destination node, `dst_path`/`uri` its path or URI,
+ *  `field` the authoring key). No rename table: what the walk projects is what
+ *  the result carries. */
 export interface GraphEdge {
     id: string;
-    src: string;
-    dst: string;
+    doc_id: string;
+    block_id: string | null;
+    via_id: string | null;
+    dst_id: string;
     dst_path: string | null;
-    dst_uri: string | null;
+    uri: string | null;
     dst_kind: string;
     predicate: string;
     provenance: string;
     anchor: string | null;
-    src_field: string | null;
+    field: string | null;
 }
-/** A reached document: id/path + walk metadata + any requested projections. */
+/** A reached document: `id`/`path` (the row's own names, as a `query` hit)
+ *  + walk metadata + any requested projections. */
 export interface GraphDoc {
     id: string;
     path: string;
@@ -44,7 +51,7 @@ export interface GraphResult {
     degrees: number;
     direction: GraphDirection;
     documents: GraphDoc[];
-    edges: GraphEdge[];
+    links: GraphEdge[];
     frontier: {
         id: string;
         path: string;
@@ -57,7 +64,7 @@ export interface GraphResult {
 /**
  * Run the `graph` neighborhood macro: compile the args into OQX `follow`
  * query(ies), execute via the shared runner, and shape the walk output into
- * { documents, edges, frontier }. Throws EngineError (doc_missing/target_missing)
+ * { documents, links, frontier }. Throws EngineError (doc_missing/target_missing)
  * for an empty or unresolvable roots list — never a silent empty result.
  */
 export declare function graphNeighborhood(store: Store, repoId: string, args: GraphArgs, embedQuery?: EmbedQuery): Promise<GraphResult>;

package/dist/src/mcp/graph.js

@@ -2,27 +2,30 @@
 //
 // ADR-006: OQX `follow` is the ONE traversal engine; the removed
 // graph_traverse/path/subgraph tools are not resurrected. This macro owns NO
-// graph-walking logic — it compiles its arguments into an OQX `follow doc.out`
-// / `doc.in` query (the exact recursive-CTE walk the `query` tool exposes),
+// graph-walking logic — it compiles its arguments into an OQX `follow out_links
+// collect { from dst }` / `follow in_links collect { from doc }` query (the
+// exact walk the `query` tool exposes over the link rows),
 // runs it through the shared runner (oqxRunAsync), and then only SHAPES the
 // walk's own output (its `$depth`/`$stop` intrinsics and projected edges) into
-// the { documents, edges, frontier } envelope. Every hop, cycle-guard and depth
+// the { documents, links, frontier } envelope. Every hop, cycle-guard and depth
 // bound is `follow`'s; nothing here re-implements BFS/DFS.
 //
 // Mapping (args → follow query):
-//   roots      → the seed `where $id == … or …` (refs resolved to doc ids first; literals in the AST, never spliced text)
-//   degrees    → `follow … { depth degrees+1 }` (seed is $depth 1, so N hops = depth N+1)
-//   direction  → `follow doc.out` | `doc.in` | both (two walks, unioned)
+//   roots      → the seed `where id == … or …` (refs resolved to doc ids first; literals in the AST, never spliced text)
+//   degrees    → `follow … collect { … depth degrees+1 }` (seed is $depth 1, so N hops = depth N+1)
+//   direction  → `follow out_links collect { from dst }` (the linked documents)
+//                | `follow in_links collect { from doc }` (the linking documents)
+//                | both (two walks, unioned)
 //   predicate  → restricts the neighborhood to docs reachable via that predicate
 //                (recomputed over the walk's collected edges; no `via` clause)
 //   select     → extra doc projections spliced into the walk's `select`
 //   max_documents → a post-walk cap on the distinct document set
 //
-// Edges are surfaced by projecting the reached doc's `doc.out_edges`/`doc.in_edges`
+// Edges are surfaced by projecting the reached doc's `doc.out_links`/`doc.in_links`
 // in the SAME walk (a select-position collect), then keeping the induced-subgraph
 // edges (both endpoints in the neighborhood) plus dangling stubs to external/
 // phantom targets — so external (`x_…`) and phantom endpoints are never dropped,
-// exactly as `from edges` surfaces them.
+// exactly as `from links` surfaces them.
 import { build, parse, print, OqxError } from "@omgbase/oqx";
 import { findDocByRef } from "../core/read/reader.js";
 import { oqxRunAsync } from "../oqx/run.js";
@@ -38,21 +41,30 @@ function cmpBytes(a, b) {
 // Build the extra `select` items for caller projections. Each expression gets a
 // stable internal alias (_u0, _u1, …) so it can never collide with a reserved
 // word or the macro's own aliases; the clean output name is derived separately.
+// A bare-name selection (`layer`, `title`) is its own output key, exactly as a
+// `query` hit projects it (spec/surface §1.4, 3.0) — so `id`/`path` collapse
+// onto the envelope keys (the engine reads the same value) and any other name
+// is an ordinary column, deduped by suffix. Anything else (an expression) is
+// `sel_<i>`, so a projection can never overwrite the envelope here.
 function buildUserSelect(select) {
     const items = [];
     const outNames = [];
     if (!select || select.length === 0)
         return { items, outNames };
-    const used = new Set();
+    const used = new Set(["id", "path"]);
     select.forEach((expr, i) => {
         const trimmed = expr.trim();
         if (!trimmed)
             return;
-        const m = /^\$?([A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
+        const m = /^(\$?[A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
         let name = m ? m[1] : `sel_${i}`;
-        while (used.has(name))
-            name = `${name}_${i}`;
-        used.add(name);
+        // The envelope keys are the row's own identity: an `id`/`path` selection
+        // lands on them rather than beside them (the engine reads the same value).
+        if (name !== "id" && name !== "path") {
+            while (used.has(name))
+                name = `${name}_${i}`;
+            used.add(name);
+        }
         outNames[i] = name;
         items.push(...userItems(trimmed, `_u${i}`));
     });
@@ -74,39 +86,47 @@ function userItems(src, alias) {
     }
     return q.select;
 }
-// The edge fields projected from doc.out_edges/doc.in_edges — identical for both
-// directions so a single filter handles either scan (an edge is a directional
-// src→dst fact regardless of which endpoint the walk reached it from).
+// The edge fields projected from doc.out_links/doc.in_links — the `links`
+// target's own names, projected under themselves (spec/surface §1.2, 3.0: no
+// rename between the language and the result) — identical for both directions
+// so a single filter handles either scan (an edge is a directional fact
+// regardless of which endpoint the walk reached it from).
 const EDGE_FIELDS = [
-    ["id", "$id"], ["src", "$src"], ["dst", "$dst"], ["dst_path", "$dst_path"], ["dst_uri", "$dst_uri"],
-    ["dst_kind", "dst_kind"], ["predicate", "predicate"], ["provenance", "provenance"], ["anchor", "anchor"], ["src_field", "src_field"],
+    "id", "doc_id", "block_id", "via_id", "dst_id", "dst_path", "uri",
+    "dst_kind", "predicate", "provenance", "anchor", "field",
 ];
 // The walk, as an AST (spec/oqx/AST.md §7) printed canonically — never spliced
 // strings: the seed ids are literals, the caller's projections parsed items.
 //
-//   select _depth: $depth, _stop: $stop, _edges: doc.<dir>_edges collect { <edge fields> } <user items>
-//   from docs where $id == <root> or … follow distinct doc.<dir> { depth <depth> }
+//   select _depth: $depth, _stop: $stop, _links: doc.<dir>_links collect { <edge fields> } <user items>
+//   from docs where id == <root> or … follow distinct <dir>_links collect { from <dst | doc> depth <depth> }
+//
+// The destination block walks the link rows to the documents at their other
+// end (spec/surface §1.2, 3.0 follow-up: there are no `out`/`in` relations —
+// `dst` is a link's destination document, `doc` its source; a `from` over an
+// absent `dst` — an external or phantom target — contributes no successor).
 function buildQuery(rootIds, dir, depth, userSelect) {
-    const edges = build.op(build.path("doc", `${dir}_edges`), "collect", build.subquery({
-        select: EDGE_FIELDS.map(([name, expr]) => build.field(name, build.ident(expr))),
+    const edges = build.op(build.path("doc", `${dir}_links`), "collect", build.subquery({
+        select: EDGE_FIELDS.map((name) => build.field(name, build.ident(name))),
     }));
-    const seed = rootIds.map((id) => build.scalar(build.binary("==", build.ident("$id"), build.lit(id))));
+    const seed = rootIds.map((id) => build.scalar(build.binary("==", build.ident("id"), build.lit(id))));
     const q = build.query(build.ident("docs"), {
         select: [
             build.field("_depth", build.ident("$depth")),
             build.field("_stop", build.ident("$stop")),
-            build.collect("_edges", edges),
+            build.collect("_links", edges),
             ...userSelect,
         ],
         where: seed.length === 1 ? seed[0] : build.or(seed),
-        follow: build.follow([build.path("doc", dir)], { distinct: true, depth }),
+        // `depth` is the destination block's own clause (oqx 0.20).
+        follow: build.follow([build.op(build.ident(`${dir}_links`), "collect", build.subquery({ from: [build.ident(dir === "out" ? "dst" : "doc")], depth }))], { distinct: true }),
     });
     return print(q);
 }
 /**
  * Run the `graph` neighborhood macro: compile the args into OQX `follow`
  * query(ies), execute via the shared runner, and shape the walk output into
- * { documents, edges, frontier }. Throws EngineError (doc_missing/target_missing)
+ * { documents, links, frontier }. Throws EngineError (doc_missing/target_missing)
  * for an empty or unresolvable roots list — never a silent empty result.
  */
 export async function graphNeighborhood(store, repoId, args, embedQuery) {
@@ -145,18 +165,21 @@ export async function graphNeighborhood(store, repoId, args, embedQuery) {
         for (const hit of res.hits) {
             const hopDepth = Number(hit._depth); // $depth: seed = 1
             const degree = hopDepth - 1; // root = 0
+            // The walk's hits carry `id`/`path` (spec/surface §1.4, 3.0) and so
+            // does `graph`'s document: one notation for a document everywhere.
             const prev = docMap.get(hit.id);
             if (!prev || degree < prev.degree) {
                 const doc = { id: hit.id, path: hit.path, degree, frontier: false };
                 outNames.forEach((name, i) => {
-                    if (name !== undefined)
+                    // An `id`/`path` selection is the envelope key itself (same value).
+                    if (name !== undefined && name !== "id" && name !== "path")
                         doc[name] = hit[`_u${i}`] ?? null;
                 });
                 docMap.set(hit.id, doc);
             }
             // Gather this node's edges; dedup by edge id (an a→b edge is reachable as
             // a's out-edge AND b's in-edge in "both" mode).
-            const raw = hit._edges ?? [];
+            const raw = hit._links ?? [];
             for (const e of raw)
                 if (!edgeMap.has(e.id))
                     edgeMap.set(e.id, e);
@@ -176,9 +199,9 @@ export async function graphNeighborhood(store, repoId, args, embedQuery) {
             if (e.predicate !== P)
                 continue;
             if (dirs.includes("out"))
-                link(e.src, e.dst); // forward
+                link(e.doc_id, e.dst_id); // forward
             if (dirs.includes("in"))
-                link(e.dst, e.src); // backward
+                link(e.dst_id, e.doc_id); // backward
         }
         const depthOf = new Map(rootIds.map((id) => [id, 0]));
         let wave = [...rootIds];
@@ -223,26 +246,26 @@ export async function graphNeighborhood(store, repoId, args, embedQuery) {
     }
     // Keep the induced-subgraph edges (both endpoints in the neighborhood) plus
     // dangling stubs to external/phantom targets, so external (x_…) and phantom
-    // endpoints survive the way `from edges` surfaces them. A `predicate` filter
+    // endpoints survive the way `from links` surfaces them. A `predicate` filter
     // keeps only that predicate's edges (the neighborhood was already restricted to
     // predicate-reachable docs above).
     const edges = [];
     for (const e of edgeMap.values()) {
         if (args.predicate && e.predicate !== args.predicate)
             continue;
-        const srcIn = reached.has(e.src);
+        const srcIn = reached.has(e.doc_id);
         const dstDangling = e.dst_kind === "external" || (e.dst_kind === "document" && e.dst_path === null);
-        const dstIn = reached.has(e.dst) || dstDangling;
+        const dstIn = reached.has(e.dst_id) || dstDangling;
         if (srcIn && dstIn)
             edges.push(e);
     }
-    edges.sort((a, b) => cmpBytes(a.src, b.src) || cmpBytes(a.id, b.id));
+    edges.sort((a, b) => cmpBytes(a.doc_id, b.doc_id) || cmpBytes(a.id, b.id));
     return {
         roots: rootIds,
         degrees: effectiveDegrees,
         direction,
         documents,
-        edges,
+        links: edges,
         frontier,
         truncated,
         queries,