@omgbase/core 0.28.0 → 0.29.0

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

@@ -2,14 +2,14 @@ import type { Database } from "better-sqlite3";
 import type { Store } from "../store/store.js";
 import { type PropertySource } from "../store/properties.js";
 export interface DocsReadResult {
-    id: string;
+    _id: string;
     /** The reference form (`/a/b.md`, spec/surface §1 "Paths"). */
-    path: string;
+    _path: string;
     rev: string | null;
     /** Properties grouped by source: { frontmatter, inline, computed }. */
     properties: Record<string, Record<string, unknown>>;
     /** The reconstructed file bytes (spec/store §6.1) — the document's `raw`. */
-    raw: string;
+    _raw: string;
     /** Block ids in document order, for follow-up edits (include_ids). */
     ids?: string[];
     /**
@@ -46,12 +46,13 @@ export declare function currentFrontmatterRaw(db: Database, revId: string): stri
  */
 export declare function reconstructContent(db: Database, docId: string): string | null;
 /**
- * The surface's `properties` (spec/surface §2, 3.0): the `spec/properties` §5
+ * The surface's `properties` (spec/surface §2, 5.0): the `spec/properties` §5
  * grouped shape with the computed group's keys spelled as the attributes that
  * read them — the store writes the computed rows under `$title`/`$tags`
- * (spec/properties §3.3, unchanged), the surface has no `$` names, so
- * `properties.computed` is `{ title, tags }`. Authored groups are untouched (an
- * authored `$x:` key keeps its sigil, as `frontmatter.$x` reads it).
+ * (spec/properties §3.3, unchanged), the surface has no `$` names and its
+ * engine names are `_`-prefixed, so `properties.computed` is `{ _title, _tags }`.
+ * Authored groups are untouched (bare keys; an authored `$x:` key keeps its
+ * sigil, as `_frontmatter.$x` reads it).
  */
 export declare function surfaceProperties(grouped: Record<PropertySource, Record<string, unknown>>): Record<string, Record<string, unknown>>;
 /** Read a whole document by id: full file bytes + properties. Null if missing. */
@@ -93,13 +94,13 @@ export declare function docsReadMany(store: Store, repoId: string, refs: string[
  * the CURRENT bag flagged `propertiesAreCurrent: true`).
  */
 export interface DocsReadAtResult {
-    id: string;
+    _id: string;
     /** The path as of that revision, in the reference form. */
-    path: string;
+    _path: string;
     /** The revision travelled to (the argument, echoed for confirmation). */
     rev: string;
     /** The reconstructed file bytes at `rev` — the document's `raw` then. */
-    raw: string;
+    _raw: string;
     /** True when the reconstructed bytes' sha256 matched the revision's stored
      *  rendered_hash — a byte-faithful round-trip. False flags the fidelity gap
      *  described below (doc-level trivia may differ for an old revision). */

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

@@ -63,17 +63,18 @@ export function reconstructContent(db, docId) {
     return out.join("");
 }
 /**
- * The surface's `properties` (spec/surface §2, 3.0): the `spec/properties` §5
+ * The surface's `properties` (spec/surface §2, 5.0): the `spec/properties` §5
  * grouped shape with the computed group's keys spelled as the attributes that
  * read them — the store writes the computed rows under `$title`/`$tags`
- * (spec/properties §3.3, unchanged), the surface has no `$` names, so
- * `properties.computed` is `{ title, tags }`. Authored groups are untouched (an
- * authored `$x:` key keeps its sigil, as `frontmatter.$x` reads it).
+ * (spec/properties §3.3, unchanged), the surface has no `$` names and its
+ * engine names are `_`-prefixed, so `properties.computed` is `{ _title, _tags }`.
+ * Authored groups are untouched (bare keys; an authored `$x:` key keeps its
+ * sigil, as `_frontmatter.$x` reads it).
  */
 export function surfaceProperties(grouped) {
     const computed = {};
     for (const [k, v] of Object.entries(grouped.computed))
-        computed[k.startsWith("$") ? k.slice(1) : k] = v;
+        computed[k.startsWith("$") ? `_${k.slice(1)}` : k] = v;
     return { frontmatter: grouped.frontmatter, inline: grouped.inline, computed };
 }
 /** Read a whole document by id: full file bytes + properties. Null if missing. */
@@ -85,11 +86,11 @@ export function docsRead(store, docId, opts = {}) {
     if (content === null)
         return null;
     const result = {
-        id: info.docId,
-        path: referencePath(info.path),
+        _id: info.docId,
+        _path: referencePath(info.path),
         rev: info.currentRev,
         properties: surfaceProperties(docPropertiesGrouped(store.db, docId)),
-        raw: content,
+        _raw: content,
     };
     if (opts.includeIds) {
         const ids = [];
@@ -231,11 +232,11 @@ export function readDocumentAtRevision(store, docId, revId) {
     const content = out.join("");
     const renderedHashMatch = sha256(content).equals(rev.rendered_hash);
     return {
-        id: docId,
+        _id: docId,
         // The revision records the path as of that revision (docs may be moved).
-        path: referencePath(rev.path),
+        _path: referencePath(rev.path),
         rev: revId,
-        raw: content,
+        _raw: content,
         renderedHashMatch,
     };
 }

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

@@ -1,20 +1,20 @@
 import type { Store } from "../store/store.js";
 export type Resolution = "skeleton" | "outline" | "text" | "raw" | "full";
 export interface GetNode {
-    id: string;
-    type: string;
+    _id: string;
+    _type: string;
     label?: string;
-    text?: string;
-    /** The block's raw source bytes (`raw` / `full`). */
-    raw?: string;
+    _text?: string;
+    /** The block's raw source bytes (`raw` / `full` resolutions). */
+    _raw?: string;
     /** The block's raw_hash (hex) — the value update/split expect as `expect.content_hash`. */
-    hash?: string;
-    attrs?: Record<string, unknown>;
-    ordinal?: number;
-    depth?: number;
+    _hash?: string;
+    _attrs?: Record<string, unknown>;
+    _ordinal?: number;
+    _depth?: number;
     /** The parent block's id, null at the top level (`full`). */
     parent_id?: string | null;
-    children?: GetNode[];
+    _children?: GetNode[];
 }
 export interface NodesGetOptions {
     resolution?: Resolution;

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

@@ -4,7 +4,7 @@ function firstWords(text, n) {
     return w.length <= n ? w.join(" ") : w.slice(0, n).join(" ") + "…";
 }
 function project(store, node, resolution, includeChildren) {
-    const out = { id: node.blockId, type: node.type };
+    const out = { _id: node.blockId, _type: node.type };
     switch (resolution) {
         case "skeleton":
             out.label = node.type === "heading" ? node.text : node.type;
@@ -13,24 +13,24 @@ function project(store, node, resolution, includeChildren) {
             out.label = firstWords(node.text, 10);
             break;
         case "text":
-            out.text = node.text;
+            out._text = node.text;
             break;
         case "raw":
-            out.raw = blockRaw(store, node.rawHashHex);
-            out.hash = node.rawHashHex;
+            out._raw = blockRaw(store, node.rawHashHex);
+            out._hash = node.rawHashHex;
             break;
         case "full":
-            out.raw = blockRaw(store, node.rawHashHex);
-            out.hash = node.rawHashHex;
-            out.text = node.text;
-            out.attrs = node.attrs;
-            out.ordinal = node.ordinal;
-            out.depth = node.depth;
+            out._raw = blockRaw(store, node.rawHashHex);
+            out._hash = node.rawHashHex;
+            out._text = node.text;
+            out._attrs = node.attrs;
+            out._ordinal = node.ordinal;
+            out._depth = node.depth;
             out.parent_id = node.parentBlock;
             break;
     }
     if (includeChildren && node.children.length > 0) {
-        out.children = node.children.map((c) => project(store, c, resolution, true));
+        out._children = node.children.map((c) => project(store, c, resolution, true));
     }
     return out;
 }

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

@@ -1,11 +1,11 @@
 import type { Store } from "../store/store.js";
 /** One row of the `ls` / docs_list surface: a live document with its block
  *  count and last-commit timestamp, under the row attributes' own names
- *  (spec/surface §1.2, 3.0: `id`, `path`, `updated_at`). */
+ *  (spec/surface §1.2, 5.0: `_id`, `_path`, `_updated_at`). */
 export interface DocListRow {
-    id: string;
-    path: string;
-    updated_at: string | null;
+    _id: string;
+    _path: string;
+    _updated_at: string | null;
     blocks: number;
 }
 /** A page of the docs_list surface. Honors the uniform list contract (mcp-api
@@ -34,18 +34,21 @@ export declare const DOCS_LIST_DEFAULT_LIMIT = 200;
  *  implementation for both surfaces). For a directory-aware summary use
  *  `docsTree`. */
 export declare function docsList(store: Store, repoId: string, opts?: DocListOptions): DocListPage;
-/** One entry of the docs_tree surface: a live document (`kind: "doc"`, with
- *  its `id`) or a collapsed directory (`kind: "dir"`, `path` ends in `/`, no
- *  id) at the requested depth. `docs`/`blocks` are totals under the entry (a
- *  doc counts 1 doc); `updated_at` is the latest last-commit timestamp under
- *  it (spec/surface §1.2, 3.0 names). */
+/** One entry of the docs_tree surface (spec/surface §2, 5.1): a directory
+ *  within `depth` segments under the prefix (`_path` ends in `/`, no `_id`;
+ *  `docs`/`blocks` are the totals beneath it) or — only with `files: true` — a
+ *  live document shallow enough to be listed (`_id`, `_path`, `blocks`; no
+ *  `docs`: a document is one). `_updated_at` (the latest last-commit timestamp
+ *  under the entry) rides only with `updated: true`. Through 5.0 every entry
+ *  carried `kind: "dir" | "doc"`, `docs` and `_updated_at` and the documents
+ *  were always listed — the 29 kB page the 2026-10-21 agent-bench replayed on
+ *  every turn; the directory rollup is the orientation call now. */
 export interface DocTreeEntry {
-    id?: string;
-    path: string;
-    kind: "dir" | "doc";
-    docs: number;
+    _id?: string;
+    _path: string;
+    docs?: number;
     blocks: number;
-    updated_at: string | null;
+    _updated_at?: string | null;
 }
 export interface DocTreePage {
     /** The normalized directory prefix the tree was taken under, in the
@@ -57,6 +60,9 @@ export interface DocTreePage {
         docs: number;
         blocks: number;
     };
+    /** The documents directly in `prefix` (one segment below it) — counted
+     *  whether or not `files` lists them. */
+    files_here: number;
     entries: DocTreeEntry[];
     truncated: boolean;
     cursor: string | null;
@@ -65,9 +71,13 @@ export interface DocTreeOptions {
     /** Directory to take the tree under (`projects` or `projects/`; leading `/`
      *  tolerated). Omit for the repo root. */
     path?: string;
-    /** How many path segments below `prefix` to expand before collapsing
-     *  (default 1 = immediate children, like `tree -L 1`). */
+    /** How many path segments below `prefix` to descend (default 1 = the
+     *  immediate subdirectories, like `tree -L 1 -d`). */
     depth?: number;
+    /** List the documents within `depth` segments too, as lean rows. */
+    files?: boolean;
+    /** Add `_updated_at` to every entry. */
+    updated?: boolean;
     limit?: number;
     cursor?: string | null;
     budgetTokens?: number;
@@ -76,14 +86,17 @@ export declare const DOCS_TREE_DEFAULT_LIMIT = 200;
 /** 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
- *  directory (with doc/block totals + latest ts) or listed as a doc when it is
- *  shallow enough. Entries are ordered by path; dirs carry a trailing `/`. The
- *  result is paged under the same limit/cursor/budget contract as docsList,
- *  and always carries `total` for the whole prefix so an agent sees the size of
- *  what it is looking at even when the page is cut. Backs the `docs_tree` MCP
- *  tool. */
+/** The path-separator-aware orientation read (`tree -L depth -d` + `du`):
+ *  every directory within `depth` segments under `path` is one entry —
+ *  `{ _path (rooted, ending "/"), docs, blocks }`, the totals over everything
+ *  beneath it, a nested directory listed after its parent in path order — and
+ *  the documents directly in `path` are counted as `files_here`. With `files:
+ *  true` the documents within `depth` segments are listed too, as `{ _id,
+ *  _path, blocks }`; with `updated: true` every entry gains `_updated_at` (a
+ *  directory's is the latest beneath it). The result is paged under the same
+ *  limit/cursor/budget contract as docsList, and always carries `total` and
+ *  `files_here` for the whole prefix, so an agent sees the size of what it is
+ *  looking at even when the page is cut. Backs the `docs_tree` MCP tool. */
 export declare function docsTree(store: Store, repoId: string, opts?: DocTreeOptions): DocTreePage;
 export interface BlockNode {
     blockId: string;

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

@@ -32,7 +32,7 @@ function liveDocRows(store, repoId, like, after, limit) {
         .all(...params);
     // The surface speaks the reference form (spec/surface §1 "Paths"): rooted on
     // the way out, the storage form never leaves this module.
-    return rows.map((r) => ({ id: r.id, path: referencePath(r.path), updated_at: r.ts, blocks: r.blocks }));
+    return rows.map((r) => ({ _id: r.id, _path: referencePath(r.path), _updated_at: r.ts, blocks: r.blocks }));
 }
 // Path-keyset cursors for the path-ordered list surfaces: the shared kernel
 // encoding (core/cursor.ts) with a one-part tuple holding the row's (rooted)
@@ -64,7 +64,7 @@ function pagePathOrdered(rows, limit, budgetTokens, moreBeyond) {
         items.push(row);
     }
     const last = items[items.length - 1];
-    return { items, truncated, cursor: truncated && last ? encodePathCursor(last.path) : null };
+    return { items, truncated, cursor: truncated && last ? encodePathCursor(last._path) : null };
 }
 /** List a repo's live documents (path, block count, last-commit ts), ordered by
  *  path, as a page: `{ items, truncated, cursor }`. `pathGlob` is a simple LIKE
@@ -88,53 +88,66 @@ export function normalizeTreePrefix(path) {
     const trimmed = storagePath(path ?? "").replace(/\/+$/, "");
     return trimmed === "" ? "" : trimmed + "/";
 }
-/** The path-separator-aware orientation read (`tree -L depth` + `du`): every
- *  live doc under `path` is collapsed at `depth` segments into one entry per
- *  directory (with doc/block totals + latest ts) or listed as a doc when it is
- *  shallow enough. Entries are ordered by path; dirs carry a trailing `/`. The
- *  result is paged under the same limit/cursor/budget contract as docsList,
- *  and always carries `total` for the whole prefix so an agent sees the size of
- *  what it is looking at even when the page is cut. Backs the `docs_tree` MCP
- *  tool. */
+/** The path-separator-aware orientation read (`tree -L depth -d` + `du`):
+ *  every directory within `depth` segments under `path` is one entry —
+ *  `{ _path (rooted, ending "/"), docs, blocks }`, the totals over everything
+ *  beneath it, a nested directory listed after its parent in path order — and
+ *  the documents directly in `path` are counted as `files_here`. With `files:
+ *  true` the documents within `depth` segments are listed too, as `{ _id,
+ *  _path, blocks }`; with `updated: true` every entry gains `_updated_at` (a
+ *  directory's is the latest beneath it). The result is paged under the same
+ *  limit/cursor/budget contract as docsList, and always carries `total` and
+ *  `files_here` for the whole prefix, so an agent sees the size of what it is
+ *  looking at even when the page is cut. Backs the `docs_tree` MCP tool. */
 export function docsTree(store, repoId, opts = {}) {
     const prefix = normalizeTreePrefix(opts.path);
     const depth = Math.max(1, Math.floor(opts.depth ?? 1));
     const limit = Math.max(1, Math.floor(opts.limit ?? DOCS_TREE_DEFAULT_LIMIT));
+    const files = opts.files === true;
+    const updated = opts.updated === true;
     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 };
+    let filesHere = 0;
     for (const row of rows) {
-        const storage = storagePath(row.path);
+        const storage = storagePath(row._path);
         total.docs += 1;
         total.blocks += row.blocks;
         const segs = storage.slice(prefix.length).split("/");
-        if (segs.length <= depth) {
-            byPath.set(storage, { id: row.id, path: row.path, kind: "doc", docs: 1, blocks: row.blocks, updated_at: row.updated_at });
-            continue;
-        }
-        const dir = referencePath(prefix + segs.slice(0, depth).join("/") + "/");
-        const cur = byPath.get(dir);
-        if (cur) {
-            cur.docs += 1;
-            cur.blocks += row.blocks;
-            if (row.updated_at !== null && (cur.updated_at === null || row.updated_at > cur.updated_at))
-                cur.updated_at = row.updated_at;
-        }
-        else {
-            byPath.set(dir, { path: dir, kind: "dir", docs: 1, blocks: row.blocks, updated_at: row.updated_at });
+        if (segs.length === 1)
+            filesHere += 1;
+        // Every directory above the document within `depth` segments rolls it up.
+        for (let d = 1; d < segs.length && d <= depth; d++) {
+            const dir = referencePath(prefix + segs.slice(0, d).join("/") + "/");
+            const cur = byPath.get(dir);
+            if (cur) {
+                cur.docs += 1;
+                cur.blocks += row.blocks;
+                if (row._updated_at !== null && (cur.ts === null || row._updated_at > cur.ts))
+                    cur.ts = row._updated_at;
+            }
+            else {
+                byPath.set(dir, { _path: dir, dir: true, docs: 1, blocks: row.blocks, ts: row._updated_at });
+            }
         }
+        if (files && segs.length <= depth)
+            byPath.set(row._path, { _id: row._id, _path: row._path, dir: false, docs: 1, blocks: row.blocks, ts: row._updated_at });
     }
-    let entries = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    let accs = [...byPath.values()].sort((a, b) => (a._path < b._path ? -1 : a._path > b._path ? 1 : 0));
     if (opts.cursor) {
         const after = decodeListCursor(opts.cursor);
-        entries = entries.filter((e) => e.path > after);
+        accs = accs.filter((e) => e._path > after);
     }
+    const entries = accs.map((a) => ({
+        ...(a.dir ? {} : { _id: a._id }),
+        _path: a._path,
+        ...(a.dir ? { docs: a.docs } : {}),
+        blocks: a.blocks,
+        ...(updated ? { _updated_at: a.ts } : {}),
+    }));
     const { items, truncated, cursor } = pagePathOrdered(entries, limit, opts.budgetTokens, false);
-    return { prefix: referencePath(prefix), depth, total, entries: items, truncated, cursor };
+    return { prefix: referencePath(prefix), depth, total, files_here: filesHere, entries: items, truncated, cursor };
 }
 function toNode(r) {
     return {

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

@@ -18,11 +18,11 @@ export declare class RevisionNotFound extends Error {
     readonly rev: string;
     constructor(docId: string, rev: string);
 }
-/** One block-grain diff entry: the block's `id` (spec/surface §1.2, 3.0) and
+/** One block-grain diff entry: the block's `_id` (spec/surface §1.2, 5.0) and
  *  its raw `before`/`after` as applicable. */
 export interface DiffEntry {
     kind: "added" | "removed" | "changed" | "unchanged";
-    id: string;
+    _id: string;
     before?: string;
     after?: string;
 }
@@ -40,8 +40,8 @@ export declare function diffBlocks(store: Store, docId: string, fromRev: string,
 export declare function diffUnified(store: Store, docId: string, fromRev: string, toRev: string): string;
 /** The `docs_diff_unified` tool's result (spec/surface §3): the resolved revision pair and the diff. */
 export interface DocDiffUnified {
-    id: string;
-    path: string;
+    _id: string;
+    _path: string;
     from: string;
     to: string;
     diff: string;
@@ -84,14 +84,14 @@ export interface CommitDigest {
     actor: string | null;
     summary: string;
     /** The revisions the commit wrote, each the document's row attributes
-     *  (spec/surface §1.2, 3.0): `id`, `path` as of the commit, `hash` (hex of
+     *  (spec/surface §1.2, 5.0): `_id`, `_path` as of the commit, `_hash` (hex of
      *  the revision's rendered_hash) — the hash lets a puller decide "changed vs
      *  echo" without a follow-up docs_read/docs_history (ADR-014 §4.2). The same
      *  three keys an `apply` revision carries. */
     revisions: {
-        id: string;
-        path: string;
-        hash: string;
+        _id: string;
+        _path: string;
+        _hash: string;
     }[];
 }
 /** changes_since: commit digests after a cursor (repo commit seq) — the change
@@ -110,26 +110,29 @@ export declare function changesSince(store: Store, repoId: string, opts?: {
     truncated: boolean;
     head: number;
 };
-/** One stored version (revision) of a document. */
+/** One stored version (revision) of a document — a `revisions` row under the
+ *  row's own names (spec/surface §1.2, 5.0): `_rev _seq _commit _ts _origin
+ *  _actor _hash _is_current _archived` (through 4.11 `rev seq commit
+ *  updated_at origin actor hash isCurrent archived`). */
 export interface DocVersion {
-    rev: string;
-    seq: number;
-    commit: string;
-    /** the commit's ts — the document's `updated_at` as of this version (spec/surface §1.2, 3.0). */
-    updated_at: string;
-    origin: string;
-    actor: string | null;
-    /** hex of the revision's rendered_hash — the document's `hash` as of this version; spot no-op vs real change, feed into docs_read_at/diff. */
-    hash: string;
+    _rev: string;
+    _seq: number;
+    _commit: string;
+    /** the commit's `ts` — the `revisions` row's `_ts` (spec/surface §1.2, 5.0; `updated_at` through 4.11). */
+    _ts: string;
+    _origin: string;
+    _actor: string | null;
+    /** hex of the revision's rendered_hash — the row's `_hash` — the document's `_hash` as of this version; spot no-op vs real change, feed into docs_read_at/diff. */
+    _hash: string;
     /** true when this rev == the doc's current_rev. */
-    isCurrent: boolean;
+    _is_current: boolean;
     /** true when the revision's bodies live in an archive segment (spec/store §7 "Retention", 15.0; `docs_read { at }` reads through it when attached). */
-    archived: boolean;
+    _archived: boolean;
 }
 /** A matching document with its ordered version history. */
 export interface DocVersions {
-    id: string;
-    path: string;
+    _id: string;
+    _path: string;
     deleted: boolean;
     currentRev: string | null;
     versions: DocVersion[];

package/dist/src/graph/history.js

@@ -39,13 +39,13 @@ export function diffBlocks(store, docId, fromRev, toRev) {
     const entries = [];
     for (const [id, raw] of before) {
         if (!after.has(id))
-            entries.push({ kind: "removed", id: id, before: raw });
+            entries.push({ kind: "removed", _id: id, before: raw });
         else if (after.get(id) !== raw)
-            entries.push({ kind: "changed", id: id, before: raw, after: after.get(id) });
+            entries.push({ kind: "changed", _id: id, before: raw, after: after.get(id) });
     }
     for (const [id, raw] of after)
         if (!before.has(id))
-            entries.push({ kind: "added", id: id, after: raw });
+            entries.push({ kind: "added", _id: id, after: raw });
     return entries;
 }
 // Reconstruct the (block id → raw) map for a document at a revision by walking
@@ -96,7 +96,7 @@ export function diffUnified(store, docId, fromRev, toRev) {
         const at = readDocumentAtRevision(store, docId, rev);
         if (!at)
             throw new RevisionNotFound(docId, rev);
-        return at.raw;
+        return at._raw;
     };
     return unifiedDiff(rendered(fromRev), rendered(toRev));
 }
@@ -117,7 +117,7 @@ export function docDiffUnified(store, docId, opts = {}) {
     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 { id: docId, path: path === undefined ? "" : referencePath(path), from, to, diff: diffUnified(store, docId, from, to) };
+    return { _id: 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
@@ -219,7 +219,7 @@ export function changesSince(store, repoId, opts = {}) {
     // 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) => ({ id: r.doc, path: referencePath(r.path), hash: 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) => ({ _id: r.doc, _path: referencePath(r.path), _hash: 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 writes no revision: the tombstone names the commit
         // (`docs.deleted_commit`). A move names itself by its reason (`move <from>
@@ -295,17 +295,17 @@ export function docHistory(store, repoId, opts = {}) {
     const docs = page.map((d) => {
         const rows = revStmt.all(d.doc_id);
         const versions = rows.map((r) => ({
-            rev: r.rev,
-            seq: r.seq,
-            commit: r.commitId,
-            updated_at: r.ts,
-            origin: r.origin,
-            actor: r.actor,
-            hash: r.rendered_hash.toString("hex"),
-            isCurrent: r.rev === d.current_rev,
-            archived: r.archive !== null,
+            _rev: r.rev,
+            _seq: r.seq,
+            _commit: r.commitId,
+            _ts: r.ts,
+            _origin: r.origin,
+            _actor: r.actor,
+            _hash: r.rendered_hash.toString("hex"),
+            _is_current: r.rev === d.current_rev,
+            _archived: r.archive !== null,
         }));
-        return { id: d.doc_id, path: referencePath(d.path), deleted: d.deleted_commit !== null, currentRev: d.current_rev, versions };
+        return { _id: d.doc_id, _path: referencePath(d.path), deleted: d.deleted_commit !== null, currentRev: d.current_rev, versions };
     });
     return { docs, truncated };
 }
@@ -341,7 +341,7 @@ function parseMove(reason) {
  * is unpinned by spec/surface).
  */
 function renderSummary(origin, actor, revs, disp, extra = { deleted: [], moved: null }) {
-    let subject = revs.map((r) => r.path).join(", ");
+    let subject = revs.map((r) => r._path).join(", ");
     if (extra.moved)
         subject = `moved ${extra.moved.from} → ${extra.moved.to}${revs.length > 0 ? `; ${subject}` : ""}`;
     else if (revs.length === 0 && extra.deleted.length > 0)

package/dist/src/graph/inbound-links.d.ts

@@ -1,17 +1,17 @@
 import type { Store } from "../core/store/store.js";
 export interface InboundLink {
     /** source document id */
-    doc_id: string;
-    /** source document repo-relative path (the surface roots it as `path`) */
-    path: string;
+    _doc_id: string;
+    /** source document repo-relative path (the surface roots it as `_path`) */
+    _path: string;
     /** source block id; null for a frontmatter-level edge */
-    block_id: string | null;
+    _block_id: string | null;
     /** the link's destination path as written (e.g. "/old.md", "../old.md", "old.md") */
     target: string;
     /** #heading / ^ref fragment, if any */
-    anchor: string | null;
+    _anchor: string | null;
     /** frontmatter key or inline-field key for typed edges */
-    field?: string;
+    _field?: string;
 }
 /**
  * Every link occurrence in the repo whose destination resolves to `docPath`,
@@ -19,7 +19,7 @@ export interface InboundLink {
  * re-scanned from the block raw so `target`/`anchor` are as written (and so a
  * self-doc pure-fragment link `#H`, which also has dst_node == docId, is NOT
  * reported — it does not depend on the path). Frontmatter edges are reported
- * with `block_id: null`, `target: docPath`, and their `field`.
+ * with `_block_id: null`, `target: docPath`, and their `_field`.
  */
 export declare function inboundLinksTo(store: Store, repoId: string, docId: string, docPath: string): InboundLink[];
 /**

package/dist/src/graph/inbound-links.js

@@ -17,7 +17,7 @@ function resolvesTo(dest, srcDir, docPath) {
  * re-scanned from the block raw so `target`/`anchor` are as written (and so a
  * self-doc pure-fragment link `#H`, which also has dst_node == docId, is NOT
  * reported — it does not depend on the path). Frontmatter edges are reported
- * with `block_id: null`, `target: docPath`, and their `field`.
+ * with `_block_id: null`, `target: docPath`, and their `_field`.
  */
 export function inboundLinksTo(store, repoId, docId, docPath) {
     const rows = store.db
@@ -30,7 +30,7 @@ export function inboundLinksTo(store, repoId, docId, docPath) {
     const seenBlocks = new Set();
     for (const r of rows) {
         if (r.srcBlock === null) {
-            out.push({ doc_id: r.srcDoc, path: r.srcPath, block_id: null, target: docPath, anchor: null, ...(r.srcField ? { field: r.srcField } : {}) });
+            out.push({ _doc_id: r.srcDoc, _path: r.srcPath, _block_id: null, target: docPath, _anchor: null, ...(r.srcField ? { _field: r.srcField } : {}) });
             continue;
         }
         if (seenBlocks.has(r.srcBlock))
@@ -46,12 +46,12 @@ export function inboundLinksTo(store, repoId, docId, docPath) {
             if (e.dstKind === "external" || !resolvesTo(e.target, srcDir, docPath))
                 continue;
             out.push({
-                doc_id: r.srcDoc,
-                path: r.srcPath,
-                block_id: r.srcBlock,
+                _doc_id: r.srcDoc,
+                _path: r.srcPath,
+                _block_id: r.srcBlock,
                 target: e.target,
-                anchor: e.anchor,
-                ...(e.srcField ? { field: e.srcField } : {}),
+                _anchor: e.anchor,
+                ...(e.srcField ? { _field: e.srcField } : {}),
             });
         }
     }