@omgbase/core 0.8.0 → 0.10.1

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

@@ -2,10 +2,22 @@
  *  tool). The MCP layer maps it to `filter_invalid`. */
 export declare class CursorInvalid extends Error {
     readonly surface: string;
-    constructor(surface: string);
+    readonly reason?: string | undefined;
+    /** `reason` names the fault when it is not the generic "not issued by this
+     *  surface" — a 1.x cursor, say (see `decodePathCursor`). */
+    constructor(surface: string, reason?: string | undefined);
 }
 /** Encode a keyset position as an opaque cursor. */
 export declare function encodeCursor(parts: readonly string[]): string;
 /** Decode a cursor issued by `encodeCursor`, requiring exactly `arity` string
  *  parts. `surface` names the caller for the error. */
 export declare function decodeCursor(cursor: string, surface: string, arity: number): string[];
+/**
+ * `decodeCursor` for the keysets whose FIRST part is a document path (`query`'s
+ * `[path, id]`, `docs_list`/`docs_tree`'s `[path]`). Since spec/surface 2.0 the
+ * surface speaks the reference form, so an issued cursor's path is `/`-rooted;
+ * a bare path can only come from a 1.x cursor, whose keyset would sort before
+ * every rooted row and silently replay the first page — it is refused with a
+ * reason that names the cause.
+ */
+export declare function decodePathCursor(cursor: string, surface: string, arity: number): string[];

package/dist/src/core/cursor.js

@@ -8,9 +8,13 @@
  *  tool). The MCP layer maps it to `filter_invalid`. */
 export class CursorInvalid extends Error {
     surface;
-    constructor(surface) {
-        super("invalid cursor");
+    reason;
+    /** `reason` names the fault when it is not the generic "not issued by this
+     *  surface" — a 1.x cursor, say (see `decodePathCursor`). */
+    constructor(surface, reason) {
+        super(reason === undefined ? "invalid cursor" : `invalid cursor: ${reason}`);
         this.surface = surface;
+        this.reason = reason;
         this.name = "CursorInvalid";
     }
 }
@@ -32,4 +36,19 @@ export function decodeCursor(cursor, surface, arity) {
         throw new CursorInvalid(surface);
     return parts;
 }
+/**
+ * `decodeCursor` for the keysets whose FIRST part is a document path (`query`'s
+ * `[path, id]`, `docs_list`/`docs_tree`'s `[path]`). Since spec/surface 2.0 the
+ * surface speaks the reference form, so an issued cursor's path is `/`-rooted;
+ * a bare path can only come from a 1.x cursor, whose keyset would sort before
+ * every rooted row and silently replay the first page — it is refused with a
+ * reason that names the cause.
+ */
+export function decodePathCursor(cursor, surface, arity) {
+    const parts = decodeCursor(cursor, surface, arity);
+    if (!parts[0].startsWith("/")) {
+        throw new CursorInvalid(surface, `cursor was issued before surface 2.0 (its path ${JSON.stringify(parts[0])} is not /-rooted); start the page sequence again without a cursor`);
+    }
+    return parts;
+}
 //# sourceMappingURL=cursor.js.map

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

@@ -0,0 +1,10 @@
+/** The reference (surface) form of a storage path: exactly one leading `/`.
+ *  `""` (the repo root, `docs_tree`'s prefix) becomes `/`. */
+export declare function referencePath(path: string): string;
+/** The storage form of a path a caller handed in: every leading `/` stripped
+ *  (a missing slash is fine, an extra one is forgiven). */
+export declare function storagePath(path: string): string;
+/** `referencePath` over a nullable value; `null`/`undefined` pass through. */
+export declare function referencePathOrNull<T extends string | null | undefined>(path: T): T extends string ? string : T;
+/** A `{ <path>: … }` record (dry-run `diffs`) re-keyed by the reference form. */
+export declare function referenceKeyed<V>(byPath: Record<string, V>): Record<string, V>;

package/dist/src/core/paths.js

@@ -0,0 +1,34 @@
+// The two path forms (spec/surface §1 "Paths", 2.0). omgbase stores a
+// document's path in git's repo-relative form (`projects/oqx.md`: `docs.path`,
+// the filesystem adapters, every store/sync spec) while every reference a user
+// authors — a Markdown link, a wikilink, a frontmatter relation — is
+// root-absolute (`/projects/oqx.md`). The surface speaks the reference form:
+// every path a query, a tool or a CLI verb RETURNS is `/`-rooted, and every
+// path they ACCEPT tolerates both forms. These two functions are the whole
+// conversion; the storage layer never sees a rooted path and the surface never
+// hands out a bare one.
+/** The reference (surface) form of a storage path: exactly one leading `/`.
+ *  `""` (the repo root, `docs_tree`'s prefix) becomes `/`. */
+export function referencePath(path) {
+    return "/" + storagePath(path);
+}
+/** The storage form of a path a caller handed in: every leading `/` stripped
+ *  (a missing slash is fine, an extra one is forgiven). */
+export function storagePath(path) {
+    let i = 0;
+    while (i < path.length && path[i] === "/")
+        i++;
+    return i === 0 ? path : path.slice(i);
+}
+/** `referencePath` over a nullable value; `null`/`undefined` pass through. */
+export function referencePathOrNull(path) {
+    return (typeof path === "string" ? referencePath(path) : path);
+}
+/** A `{ <path>: … }` record (dry-run `diffs`) re-keyed by the reference form. */
+export function referenceKeyed(byPath) {
+    const out = {};
+    for (const [k, v] of Object.entries(byPath))
+        out[referencePath(k)] = v;
+    return out;
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/core/read/document.d.ts

@@ -1,6 +1,7 @@
 import type { Database } from "better-sqlite3";
 import type { Store } from "../store/store.js";
 export interface DocsReadResult {
+    /** The reference form (`/a/b.md`, spec/surface §1 "Paths"). */
     path: string;
     docId: string;
     rev: string | null;

package/dist/src/core/read/document.js

@@ -1,6 +1,7 @@
 import { findDoc, findDocByRef, loadDocBlocks } from "./reader.js";
 import { docPropertiesGrouped } from "../store/properties.js";
 import { sha256 } from "../hash.js";
+import { referencePath } from "../paths.js";
 function blob(db, hash) {
     const row = db.prepare("SELECT bytes FROM blobs WHERE hash = ?").get(hash);
     return row ? row.bytes.toString("utf8") : "";
@@ -49,7 +50,7 @@ export function docsRead(store, docId, opts = {}) {
     if (content === null)
         return null;
     const result = {
-        path: info.path,
+        path: referencePath(info.path),
         docId: info.docId,
         rev: info.currentRev,
         properties: docPropertiesGrouped(store.db, docId),
@@ -184,7 +185,7 @@ export function readDocumentAtRevision(store, docId, revId) {
     const renderedHashMatch = sha256(content).equals(rev.rendered_hash);
     return {
         // The revision records the path as of that revision (docs may be moved).
-        path: rev.path,
+        path: referencePath(rev.path),
         docId,
         rev: revId,
         content,

package/dist/src/core/read/reader.d.ts

@@ -44,8 +44,8 @@ export interface DocTreeEntry {
     ts: string | null;
 }
 export interface DocTreePage {
-    /** The normalized directory prefix the tree was taken under (`""` = root;
-     *  otherwise ends in `/`). */
+    /** The normalized directory prefix the tree was taken under, in the
+     *  reference form: `/` for the repo root, else `/<dir>/`. */
     prefix: string;
     depth: number;
     /** Totals over EVERYTHING under `prefix`, regardless of paging. */
@@ -69,7 +69,8 @@ export interface DocTreeOptions {
     budgetTokens?: number;
 }
 export declare const DOCS_TREE_DEFAULT_LIMIT = 200;
-/** Normalize a tree prefix: no leading `/`, and either empty or ending in `/`. */
+/** Normalize a tree prefix to its storage form: no leading `/`, and either
+ *  empty or ending in `/` (either path form is accepted). */
 export declare function normalizeTreePrefix(path: string | undefined): string;
 /** The path-separator-aware orientation read (`tree -L depth` + `du`): every
  *  live doc under `path` is collapsed at `depth` segments into one entry per
@@ -99,6 +100,8 @@ export declare function blockRaw(store: Store, rawHashHex: string): string;
 export interface DocInfo {
     docId: string;
     repoId: string;
+    /** The STORAGE form (`a/b.md`): `DocInfo` is the library's internal handle on
+     *  a document (file writes, SQL); the surface roots what it returns. */
     path: string;
     format: string;
     currentRev: string | null;

package/dist/src/core/read/reader.js

@@ -1,9 +1,11 @@
 import { isValidId } from "../ids.js";
-import { encodeCursor, decodeCursor } from "../cursor.js";
+import { encodeCursor, decodePathCursor } from "../cursor.js";
+import { referencePath, storagePath } from "../paths.js";
 export const DOCS_LIST_DEFAULT_LIMIT = 200;
-/** Escape a user glob into a LIKE pattern (`*` → `%`; literal `%`/`_` escaped). */
+/** Escape a user glob into a LIKE pattern over the storage path (`*` → `%`;
+ *  literal `%`/`_` escaped); the glob may be spelled in either path form. */
 function globToLike(glob) {
-    return glob.replace(/[%_\\]/g, "\\$&").replace(/\*/g, "%");
+    return storagePath(glob).replace(/[%_\\]/g, "\\$&").replace(/\*/g, "%");
 }
 /** Live docs of a repo (path, live block count, last-commit ts) whose path
  *  matches `like`, ordered by path, optionally resuming strictly after `after`
@@ -20,7 +22,7 @@ function liveDocRows(store, repoId, like, after, limit) {
         tail = " LIMIT ?";
         params.push(limit);
     }
-    return store.db
+    const rows = store.db
         .prepare(`SELECT d.path AS path,
               (SELECT count(*) FROM blocks b WHERE b.doc_id = d.doc_id AND b.deleted_commit IS NULL) AS blocks,
               (SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = d.current_rev) AS ts
@@ -28,14 +30,20 @@ function liveDocRows(store, repoId, like, after, limit) {
        WHERE d.repo_id = ? AND d.deleted_commit IS NULL AND d.path LIKE ? ESCAPE '\\'${where}
        ORDER BY d.path${tail}`)
         .all(...params);
+    // The surface speaks the reference form (spec/surface §1 "Paths"): rooted on
+    // the way out, the storage form never leaves this module.
+    for (const r of rows)
+        r.path = referencePath(r.path);
+    return rows;
 }
 // Path-keyset cursors for the path-ordered list surfaces: the shared kernel
-// encoding (core/cursor.ts) with a one-part tuple.
+// encoding (core/cursor.ts) with a one-part tuple holding the row's (rooted)
+// path; a 1.x cursor (a bare path) is refused (core/cursor.ts).
 function encodePathCursor(path) {
     return encodeCursor([path]);
 }
-function decodePathCursor(cursor) {
-    return decodeCursor(cursor, "docs_list/docs_tree", 1)[0];
+function decodeListCursor(cursor) {
+    return decodePathCursor(cursor, "docs_list/docs_tree", 1)[0];
 }
 /** Page an already path-ordered row set under a limit + token budget, issuing
  *  a keyset cursor when it stops early. Shared by docs_list and docs_tree. */
@@ -68,16 +76,18 @@ function pagePathOrdered(rows, limit, budgetTokens, moreBeyond) {
 export function docsList(store, repoId, opts = {}) {
     const like = opts.pathGlob ? globToLike(opts.pathGlob) : "%";
     const limit = Math.max(1, Math.floor(opts.limit ?? DOCS_LIST_DEFAULT_LIMIT));
-    const after = opts.cursor ? decodePathCursor(opts.cursor) : null;
+    // The cursor carries the reference form; the keyset predicate runs on the column.
+    const after = opts.cursor ? storagePath(decodeListCursor(opts.cursor)) : null;
     // Fetch one past the limit so `truncated` is a fact, not a guess.
     const rows = liveDocRows(store, repoId, like, after, limit + 1);
     const moreBeyond = rows.length > limit;
     return pagePathOrdered(rows.slice(0, limit), limit, opts.budgetTokens, moreBeyond);
 }
 export const DOCS_TREE_DEFAULT_LIMIT = 200;
-/** Normalize a tree prefix: no leading `/`, and either empty or ending in `/`. */
+/** Normalize a tree prefix to its storage form: no leading `/`, and either
+ *  empty or ending in `/` (either path form is accepted). */
 export function normalizeTreePrefix(path) {
-    const trimmed = (path ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+    const trimmed = storagePath(path ?? "").replace(/\/+$/, "");
     return trimmed === "" ? "" : trimmed + "/";
 }
 /** The path-separator-aware orientation read (`tree -L depth` + `du`): every
@@ -94,17 +104,21 @@ export function docsTree(store, repoId, opts = {}) {
     const limit = Math.max(1, Math.floor(opts.limit ?? DOCS_TREE_DEFAULT_LIMIT));
     const like = prefix === "" ? "%" : globToLike(prefix) + "%";
     const rows = liveDocRows(store, repoId, like, null, null);
+    // `liveDocRows` hands out reference paths; the tree is built over the storage
+    // form and rooted again on the way out, so the entries, the prefix and the
+    // cursor all speak the reference form.
     const byPath = new Map();
     const total = { docs: 0, blocks: 0 };
     for (const row of rows) {
+        const storage = storagePath(row.path);
         total.docs += 1;
         total.blocks += row.blocks;
-        const segs = row.path.slice(prefix.length).split("/");
+        const segs = storage.slice(prefix.length).split("/");
         if (segs.length <= depth) {
-            byPath.set(row.path, { path: row.path, kind: "doc", docs: 1, blocks: row.blocks, ts: row.ts });
+            byPath.set(storage, { path: row.path, kind: "doc", docs: 1, blocks: row.blocks, ts: row.ts });
             continue;
         }
-        const dir = prefix + segs.slice(0, depth).join("/") + "/";
+        const dir = referencePath(prefix + segs.slice(0, depth).join("/") + "/");
         const cur = byPath.get(dir);
         if (cur) {
             cur.docs += 1;
@@ -118,11 +132,11 @@ export function docsTree(store, repoId, opts = {}) {
     }
     let entries = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     if (opts.cursor) {
-        const after = decodePathCursor(opts.cursor);
+        const after = decodeListCursor(opts.cursor);
         entries = entries.filter((e) => e.path > after);
     }
     const { items, truncated, cursor } = pagePathOrdered(entries, limit, opts.budgetTokens, false);
-    return { prefix, depth, total, entries: items, truncated, cursor };
+    return { prefix: referencePath(prefix), depth, total, entries: items, truncated, cursor };
 }
 function toNode(r) {
     return {
@@ -172,7 +186,8 @@ export function findDoc(store, ref) {
         row = store.db.prepare("SELECT doc_id, repo_id, path, format, current_rev FROM docs WHERE doc_id = ? AND deleted_commit IS NULL").get(ref.docId);
     }
     else if (ref.repoId && ref.path) {
-        row = store.db.prepare("SELECT doc_id, repo_id, path, format, current_rev FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL").get(ref.repoId, ref.path);
+        // Either path form is accepted (spec/surface §1 "Paths"); the column holds the storage form.
+        row = store.db.prepare("SELECT doc_id, repo_id, path, format, current_rev FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL").get(ref.repoId, storagePath(ref.path));
     }
     if (!row)
         return null;

package/dist/src/graph/history.js

@@ -2,6 +2,7 @@ import { findDocByRef } from "../core/read/reader.js";
 import { readDocumentAtRevision } from "../core/read/document.js";
 import { isValidId } from "../core/ids.js";
 import { EngineError } from "../mcp/errors.js";
+import { referencePath, storagePath } from "../core/paths.js";
 /** history_node: a block's biography from block_changes + commits (06 §3). */
 export function historyNode(store, blockId, opts = {}) {
     const limit = opts.limit ?? 100;
@@ -111,8 +112,8 @@ export function docDiffUnified(store, docId, opts = {}) {
     const from = opts.fromRev ?? revs[1]?.rev_id ?? revs[0]?.rev_id;
     if (!to || !from)
         throw new EngineError("target_missing", `no revisions to diff for ${opts.label ?? docId}`);
-    const path = store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId)?.path ?? "";
-    return { doc: docId, path, from, to, diff: diffUnified(store, docId, from, to) };
+    const path = store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId)?.path;
+    return { doc: docId, path: path === undefined ? "" : referencePath(path), from, to, diff: diffUnified(store, docId, from, to) };
 }
 // ---- unified diff (spec/surface §3) ------------------------------------------
 // A line-grain unified diff with a deterministic Myers script, so both engines
@@ -272,15 +273,18 @@ export function changesSince(store, repoId, opts = {}) {
         .all(...params);
     const truncated = commits.length > limit;
     const page = commits.slice(0, limit);
+    // Every path in a digest — the revisions', a deletion's, a move's two, and
+    // the summary's — is the reference form (spec/surface §1 "Paths").
     const digests = page.map((c) => {
-        const revs = store.db.prepare("SELECT r.doc_id AS doc, r.path AS path, r.rendered_hash AS rendered_hash FROM revisions r WHERE r.commit_id = ?").all(c.commit_id).map((r) => ({ doc: r.doc, path: r.path, contentHash: r.rendered_hash.toString("hex") }));
+        const revs = store.db.prepare("SELECT r.doc_id AS doc, r.path AS path, r.rendered_hash AS rendered_hash FROM revisions r WHERE r.commit_id = ?").all(c.commit_id).map((r) => ({ doc: r.doc, path: referencePath(r.path), contentHash: r.rendered_hash.toString("hex") }));
         const dispCounts = store.db.prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind").all(c.commit_id);
         // A deletion or a move writes no revision: the tombstone names the commit
         // (`docs.deleted_commit`), a move only its reason (`move <from> -> <to>`).
         const deleted = revs.length === 0
-            ? store.db.prepare("SELECT path FROM docs WHERE deleted_commit = ? ORDER BY path").all(c.commit_id).map((r) => r.path)
+            ? store.db.prepare("SELECT path FROM docs WHERE deleted_commit = ? ORDER BY path").all(c.commit_id).map((r) => referencePath(r.path))
             : [];
-        const summary = renderSummary(c.origin, c.actor, revs, dispCounts, { deleted, moved: revs.length === 0 ? parseMove(c.reason) : null });
+        const moved = revs.length === 0 ? parseMove(c.reason) : null;
+        const summary = renderSummary(c.origin, c.actor, revs, dispCounts, { deleted, moved: moved ? { from: referencePath(moved.from), to: referencePath(moved.to) } : null });
         return { commit: c.commit_id, seq: c.seq, ts: c.ts, origin: c.origin, actor: c.actor, summary, revisions: revs };
     });
     const nextCursor = page.length > 0 ? page[page.length - 1].seq : cursor;
@@ -317,14 +321,16 @@ export function docHistory(store, repoId, opts = {}) {
         const deletedClause = includeDeleted ? "" : "AND deleted_commit IS NULL";
         const params = [repoId];
         let pathClause;
-        if (opts.pathGlob.includes("*")) {
-            const like = opts.pathGlob.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
+        // The glob is spelled in either path form; the column holds the storage form.
+        const glob = storagePath(opts.pathGlob);
+        if (glob.includes("*")) {
+            const like = glob.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
             pathClause = "path LIKE ? ESCAPE '\\'";
             params.push(like);
         }
         else {
             pathClause = "path = ?";
-            params.push(opts.pathGlob);
+            params.push(glob);
         }
         params.push(limit + 1);
         docRows = store.db
@@ -352,7 +358,7 @@ export function docHistory(store, repoId, opts = {}) {
             contentHash: r.rendered_hash.toString("hex"),
             isCurrent: r.rev === d.current_rev,
         }));
-        return { docId: d.doc_id, path: d.path, deleted: d.deleted_commit !== null, currentRev: d.current_rev, versions };
+        return { docId: d.doc_id, path: referencePath(d.path), deleted: d.deleted_commit !== null, currentRev: d.current_rev, versions };
     });
     return { docs, truncated };
 }
@@ -372,7 +378,7 @@ function resolveDocRow(store, repoId, ref, includeDeleted) {
     const stmt = asId
         ? store.db.prepare("SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE doc_id = ?")
         : store.db.prepare("SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE repo_id = ? AND path = ?");
-    return (asId ? stmt.get(ref) : stmt.get(repoId, ref));
+    return (asId ? stmt.get(ref) : stmt.get(repoId, storagePath(ref)));
 }
 /** The `reason` a document move records (`mutate/docs.ts`): `move <from> -> <to>`. */
 function parseMove(reason) {

package/dist/src/graph/link-health.d.ts

@@ -10,7 +10,8 @@ export interface StaleLink {
     predicate: string;
     provenance: string;
     dstKind: string;
-    /** canonical target PATH (phantom prefix stripped, no leading `/`), e.g. "guides/old.md" */
+    /** the canonical target path in the reference form (phantom prefix stripped,
+     *  rooted), e.g. "/guides/old.md" — spec/surface §1 "Paths" */
     target: string;
     /** the destination exactly as authored in the source block, e.g. "/guides/old.md#Setup"
      * — paste-ready as `links_repair.from`. null when it can't be recovered (frontmatter

package/dist/src/graph/link-health.js

@@ -1,13 +1,16 @@
 import { canonicalLinkPath, docDirOf, splitDestination } from "./link-destinations.js";
+import { referencePath, storagePath } from "../core/paths.js";
 // Convert a path glob to a SQL LIKE clause + param, mirroring compileWithin
 // (search/cel/compile.ts) and docHistory (graph/history.ts): escape %/_ then
 // map `*`→`%`. A glob without `*` is an exact-path match.
 export function globClause(column, glob) {
-    if (glob.includes("*")) {
-        const like = glob.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
+    // Either path form is accepted; the column holds the storage form.
+    const g = storagePath(glob);
+    if (g.includes("*")) {
+        const like = g.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
         return { clause: `${column} LIKE ? ESCAPE '\\'`, param: like };
     }
-    return { clause: `${column} = ?`, param: glob };
+    return { clause: `${column} = ?`, param: g };
 }
 /**
  * linksStale: scan open edges repo-wide and return the dangling internal ones,
@@ -85,14 +88,16 @@ export function linksStale(store, repoId, opts = {}) {
     const stale = page.map((r) => {
         // Strip the "phantom:" prefix to expose the canonical path.
         const target = r.dstNode.slice("phantom:".length);
+        // The surface speaks the reference form: `srcPath` and `target` rooted;
+        // `authored` stays exactly as written in the source.
         return {
             srcDoc: r.srcDoc,
-            srcPath: r.srcPath,
+            srcPath: referencePath(r.srcPath),
             srcBlock: r.srcBlock,
             predicate: r.predicate,
             provenance: r.provenance,
             dstKind: r.dstKind,
-            target,
+            target: referencePath(target),
             authored: authoredFor(r.srcBlock, r.srcPath, target, r.anchor),
             anchor: r.anchor,
             // All phantom targets are dangling DOCUMENTS in this data model (cross-doc
@@ -131,10 +136,11 @@ export function linksStaleSummary(store, repoId, opts = {}) {
     const byTarget = store.db
         .prepare(`SELECT e.dst_node AS dstNode, count(*) AS count ${phantom} GROUP BY e.dst_node ORDER BY count DESC, e.dst_node`)
         .all(...params)
-        .map((r) => ({ target: r.dstNode.slice("phantom:".length), count: r.count }));
+        .map((r) => ({ target: referencePath(r.dstNode.slice("phantom:".length)), count: r.count }));
     const bySource = store.db
         .prepare(`SELECT d.path AS srcPath, count(*) AS count ${phantom} GROUP BY d.path ORDER BY count DESC, d.path`)
-        .all(...params);
+        .all(...params)
+        .map((r) => ({ srcPath: referencePath(r.srcPath), count: r.count }));
     return {
         staleCount: byTarget.reduce((n, t) => n + t.count, 0),
         byTarget,

package/dist/src/index.d.ts

@@ -35,7 +35,9 @@ export { docsOutline, type OutlineResult, type OutlineOptions } from "./core/rea
 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 { CursorInvalid, encodeCursor, decodeCursor } from "./core/cursor.js";
+export { CursorInvalid, encodeCursor, decodeCursor, decodePathCursor } from "./core/cursor.js";
+export { referencePath, storagePath, referencePathOrNull, referenceKeyed } from "./core/paths.js";
+export * from "./surface-paths.js";
 export { resolveRef, type ResolvedRef } from "./core/read/refs.js";
 export { resolve, type ResolveHit, type ResolveInput } from "./search/resolve.js";
 export { oqxRun, oqxRunAsync, collectSemanticPhrases, parseOqx, type OqxResult, type OqxHit, type OqxOptions, type EmbedQuery } from "./oqx/run.js";

package/dist/src/index.js

@@ -36,7 +36,9 @@ 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 { CursorInvalid, encodeCursor, decodeCursor } from "./core/cursor.js";
+export { CursorInvalid, encodeCursor, decodeCursor, decodePathCursor } from "./core/cursor.js";
+export { referencePath, storagePath, referencePathOrNull, referenceKeyed } from "./core/paths.js";
+export * from "./surface-paths.js";
 export { resolveRef } from "./core/read/refs.js";
 export { resolve } from "./search/resolve.js";
 // OQX — omgbase Query eXpressions (unified composable query language, slice 1:

package/dist/src/mcp/errors.js

@@ -22,7 +22,7 @@ export function errorBody(err) {
     if (err instanceof FilterInvalid)
         return { error: "filter_invalid", message: err.message, data: { reason: err.reason, hint: err.hint }, retriable: false };
     if (err instanceof CursorInvalid)
-        return { error: "filter_invalid", message: err.message, data: { reason: `cursor was not issued by ${err.surface}`, hint: "resume only with a `cursor` returned by a truncated page of the same tool" }, retriable: false };
+        return { error: "filter_invalid", message: err.message, data: { reason: err.reason ?? `cursor was not issued by ${err.surface}`, hint: "resume only with a `cursor` returned by a truncated page of the same tool" }, retriable: false };
     if (err instanceof MutationError)
         return { error: err.code, message: err.message, data: err.data, retriable: Boolean(err.data.retriable) };
     if (err instanceof RevisionNotFound)

package/dist/src/mcp/graph.js

@@ -10,7 +10,7 @@
 // bound is `follow`'s; nothing here re-implements BFS/DFS.
 //
 // Mapping (args → follow query):
-//   roots      → the seed `where $id == … || …` (refs resolved to doc ids first)
+//   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)
 //   predicate  → restricts the neighborhood to docs reachable via that predicate
@@ -23,8 +23,10 @@
 // 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.
+import { build, parse, print, OqxError } from "@omgbase/oqx";
 import { findDocByRef } from "../core/read/reader.js";
 import { oqxRunAsync } from "../oqx/run.js";
+import { FilterInvalid } from "../search/cel/parser.js";
 import { EngineError } from "./errors.js";
 const DEFAULT_DEGREES = 1;
 const DEFAULT_MAX_DOCUMENTS = 200;
@@ -37,10 +39,10 @@ function cmpBytes(a, b) {
 // 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.
 function buildUserSelect(select) {
-    if (!select || select.length === 0)
-        return { clause: "", outNames: [] };
     const items = [];
     const outNames = [];
+    if (!select || select.length === 0)
+        return { items, outNames };
     const used = new Set();
     select.forEach((expr, i) => {
         const trimmed = expr.trim();
@@ -52,20 +54,54 @@ function buildUserSelect(select) {
             name = `${name}_${i}`;
         used.add(name);
         outNames[i] = name;
-        items.push(`_u${i}: ${trimmed}`);
+        items.push(...userItems(trimmed, `_u${i}`));
     });
-    return { clause: items.length ? `, ${items.join(", ")}` : "", outNames };
+    return { items, outNames };
+}
+// A caller's projection expression as AST: parsed as the item of a projection,
+// so it may be anything a `select` item may be (a navigation, an expression, a
+// nested block) and nothing more. A malformed expression is `filter_invalid`,
+// as it would be in the `query` tool.
+function userItems(src, alias) {
+    let q;
+    try {
+        q = parse(`select ${alias}: ${src} from docs`);
+    }
+    catch (e) {
+        if (e instanceof OqxError)
+            throw new FilterInvalid(e.message, "OQX");
+        throw e;
+    }
+    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).
-const EDGE_COLLECT = "{ 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 }";
-function buildQuery(seed, dir, depth, userSelect) {
-    const edgesRel = dir === "out" ? "doc.out_edges" : "doc.in_edges";
-    return (`select _depth: $depth, _stop: $stop, _edges: ${edgesRel} collect ${EDGE_COLLECT}${userSelect} ` +
-        `from docs where ${seed} ` +
-        `follow distinct doc.${dir} { depth ${depth} }`);
+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"],
+];
+// 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> }
+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 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),
+            ...userSelect,
+        ],
+        where: seed.length === 1 ? seed[0] : build.or(seed),
+        follow: build.follow([build.path("doc", dir)], { distinct: true, depth }),
+    });
+    return print(q);
 }
 /**
  * Run the `graph` neighborhood macro: compile the args into OQX `follow`
@@ -93,14 +129,13 @@ export async function graphNeighborhood(store, repoId, args, embedQuery) {
     const direction = args.direction ?? "both";
     const maxDocuments = Math.max(1, Math.floor(args.max_documents ?? DEFAULT_MAX_DOCUMENTS));
     const dirs = direction === "both" ? ["out", "in"] : [direction];
-    const seed = rootIds.map((id) => `$id == ${JSON.stringify(id)}`).join(" || ");
-    const { clause: userSelect, outNames } = buildUserSelect(args.select);
+    const { items: userSelect, outNames } = buildUserSelect(args.select);
     const queries = [];
     const docMap = new Map();
     const edgeMap = new Map();
     let queryTruncated = false;
     for (const dir of dirs) {
-        const q = buildQuery(seed, dir, depth, userSelect);
+        const q = buildQuery(rootIds, dir, depth, userSelect);
         queries.push(q);
         // Fetch one more than the cap to detect truncation of a single scan; `follow
         // distinct` yields one row per reached node so the row count == node count.