@omgbase/core 0.10.0 → 0.11.0

package/README.md

@@ -51,16 +51,16 @@ const repoId = ensureRepo(ws.store, "notes", root);   // repo row + an `fs` sour
 const sweep = freshnessSweep(ws.store, repoId, root); // ingest new/changed *.md as one checkpoint
 sweep.ingested;                                       // ["todo.md"]
 
-// Query with OQX. Nodes are projections of blocks; $block_id is the anchor block.
+// Query with OQX. Nodes are projections of blocks; block_id is the anchor block.
 const open = oqxRun(ws.store, repoId,
-  'select block: $block_id from nodes where kind == "md:task" && !attrs.checked');
-open.hits;  // [{ id: "n_…", path: "todo.md", block: "b_…" }]
+  'select block: block_id from nodes where kind == "md:task" && !attrs.checked');
+open.hits;  // [{ id: "n_…", path: "/todo.md", block: "b_…" }]
 
 // Read a whole document back byte-exact, with block ids + CAS hashes.
 const doc = findDoc(ws.store, { repoId, path: "todo.md" });
 const read = docsRead(ws.store, doc.docId, { includeIds: true });
-read.content;  // "# Todo\n\n- [ ] write the README\n- [x] ship 0.1\n"
-read.ids;      // ["b_…", "b_…", "b_…", "b_…"]   read.hashes[id] → content_hash
+read.raw;     // "# Todo\n\n- [ ] write the README\n- [x] ship 0.1\n"
+read.ids;      // ["b_…", "b_…", "b_…", "b_…"]   read.hashes[id] → the block's hash (the expect.content_hash value)
 
 // Mutate. The macro expands to kernel `update` ops pinned by content_hash;
 // apply() renders, writes the file, and commits a new revision.
@@ -71,7 +71,7 @@ const result = apply(ws.store, {
   ops: tasksComplete(ws.store, open.hits.map((h) => h.block)),
   origin: { actor: "agent:quickstart", reason: "demo" },
 });
-result;  // { results: [{ ids: ["b_…"] }], revisions: [{ doc: "d_…", path: "todo.md" }], committed: true }
+result;  // { results: [{ ids: ["b_…"] }], revisions: [{ id: "d_…", path: "todo.md", hash: "…" }], committed: true }
 // todo.md on disk now reads "- [x] write the README"
 
 historyNode(ws.store, open.hits[0].block);  // [{ origin: "import", kind: "edited", … }, { origin: "observed", kind: "inserted", … }]
@@ -126,7 +126,7 @@ server in your own process with `buildServer(ctx)` and any MCP SDK transport.
 3. A doc is an ordered tree of **blocks** (`b_`): paragraphs, headings, list items, fences, YAML entries, JSON properties…
 4. Block ids are minted once and threaded through re-ingests by the reconciler, so they survive edits and moves.
 5. Blocks are the **mutation anchors**: every kernel op addresses `b_` ids; `expect.content_hash` (sha256 of the block's raw bytes) is the CAS token.
-6. **Nodes** (`n_`) are semantic projections of blocks — `md:task`, `md:heading`, `md:section`, `md:link`, `md:wikilink`, `md:anchor`, `md:inline_field` — queryable but derived; `$block_id` points back at the anchor.
+6. **Nodes** (`n_`) are semantic projections of blocks — `md:task`, `md:heading`, `md:section`, `md:link`, `md:wikilink`, `md:anchor`, `md:inline_field` — queryable but derived; `block_id` points back at the anchor.
 7. **Edges** are typed links between blocks/docs (wikilinks, `$ref`, frontmatter relations) with commit intervals.
 8. Every ingest or mutation appends a **commit** (`c_`) and a per-doc **revision** (`r_`) whose rendered hash equals the file's bytes.
 9. Commits carry `origin` (`observed` from disk, `import` from `apply`) and an actor; `historyNode`/`changesSince` read them back.
@@ -144,11 +144,11 @@ and `semantic("…")` (embedding score) are omgbase additions.
 
 ```js
 oqxRun(ws.store, repoId, `
-  select $path, $title, open: nodes collect { select $block_id where kind == "md:task" && !attrs.checked }
+  select path, title, open: nodes collect { select block_id where kind == "md:task" && !attrs.checked }
   from docs where nodes count { where kind == "md:task" && !attrs.checked } >= 2
-  order by $path limit 10
+  order by path limit 10
 `);
-// hits: [{ id: "d_…", path: "more.md", $path: "more.md", $title: "More", open: [{ $block_id: "b_…" }, …] }]
+// hits: [{ id: "d_…", path: "/more.md", title: "More", open: [{ block_id: "b_…" }, …] }]
 ```
 
 See [`docs/query-language.md`](https://github.com/omgbase/omgbase/blob/main/docs/query-language.md)

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

@@ -1,13 +1,15 @@
 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;
     /** The reference form (`/a/b.md`, spec/surface §1 "Paths"). */
     path: string;
-    docId: string;
     rev: string | null;
     /** Properties grouped by source: { frontmatter, inline, computed }. */
     properties: Record<string, Record<string, unknown>>;
-    content: string;
+    /** The reconstructed file bytes (spec/store §6.1) — the document's `raw`. */
+    raw: string;
     /** Block ids in document order, for follow-up edits (include_ids). */
     ids?: string[];
     /**
@@ -15,7 +17,7 @@ export interface DocsReadResult {
      * `ids` (include_ids). This is the exact value the raw `apply` kernel wants in
      * an update/split/merge/remove op's `expect.content_hash`, so a single read
      * yields both the stable ids AND the CAS tokens to mutate them — no follow-up
-     * nodes_get_many(resolution:"full") hydration round trip.
+     * blocks_read_many(resolution:"full") hydration round trip.
      */
     hashes?: Record<string, string>;
     /**
@@ -36,6 +38,15 @@ export interface DocsReadOptions {
  * convergence check reloads through this) as well as from a Store.
  */
 export declare function reconstructContent(db: Database, docId: string): string | null;
+/**
+ * The surface's `properties` (spec/surface §2, 3.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).
+ */
+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. */
 export declare function docsRead(store: Store, docId: string, opts?: DocsReadOptions): DocsReadResult | null;
 /** Max doc refs honored per docsReadMany call (matches nodesGetMany's cap). */
@@ -66,11 +77,13 @@ export declare function docsReadMany(store: Store, repoId: string, refs: string[
     budgetTokens?: number;
 }): DocsReadManyResult;
 export interface DocsReadAtResult {
+    id: string;
+    /** The path as of that revision, in the reference form. */
     path: string;
-    docId: string;
     /** The revision travelled to (the argument, echoed for confirmation). */
     rev: string;
-    content: string;
+    /** The reconstructed file bytes at `rev` — the document's `raw` then. */
+    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

@@ -41,6 +41,20 @@ export function reconstructContent(db, docId) {
     }
     return out.join("");
 }
+/**
+ * The surface's `properties` (spec/surface §2, 3.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).
+ */
+export function surfaceProperties(grouped) {
+    const computed = {};
+    for (const [k, v] of Object.entries(grouped.computed))
+        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. */
 export function docsRead(store, docId, opts = {}) {
     const info = findDoc(store, { docId });
@@ -50,11 +64,11 @@ export function docsRead(store, docId, opts = {}) {
     if (content === null)
         return null;
     const result = {
+        id: info.docId,
         path: referencePath(info.path),
-        docId: info.docId,
         rev: info.currentRev,
-        properties: docPropertiesGrouped(store.db, docId),
-        content,
+        properties: surfaceProperties(docPropertiesGrouped(store.db, docId)),
+        raw: content,
     };
     if (opts.includeIds) {
         const ids = [];
@@ -81,7 +95,7 @@ export function docsRead(store, docId, opts = {}) {
 // analog of docsRead: given several doc refs (each an id OR a path, via the
 // shared findDocByRef dispatch), it returns `items` (the full reads, identical
 // in shape to docsRead) alongside `errors` (per-ref misses). A miss NEVER fails
-// the whole call — mirrors nodes_getMany's tolerance of unknown ids, but made
+// the whole call — mirrors nodesGetMany's tolerance of unknown ids, but made
 // explicit as an errors array so a caller can tell which refs didn't resolve.
 // Duplicate refs collapse first-seen (a repeated ref yields one item). Capped
 // at MANY_DOCS_CAP refs per call (matching nodesGetMany's 100), with the same
@@ -184,13 +198,13 @@ export function readDocumentAtRevision(store, docId, revId) {
     const content = out.join("");
     const renderedHashMatch = sha256(content).equals(rev.rendered_hash);
     return {
+        id: docId,
         // The revision records the path as of that revision (docs may be moved).
         path: referencePath(rev.path),
-        docId,
         rev: revId,
-        content,
+        raw: content,
         renderedHashMatch,
-        properties: docPropertiesGrouped(db, docId),
+        properties: surfaceProperties(docPropertiesGrouped(db, docId)),
         propertiesAreCurrent: true,
     };
 }

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

@@ -5,15 +5,15 @@ export interface GetNode {
     type: string;
     label?: string;
     text?: string;
+    /** The block's raw source bytes (`raw` / `full`). */
     raw?: string;
-    /** The block's raw_hash (hex) — the value update/split expect as content_hash. */
-    content_hash?: string;
+    /** The block's raw_hash (hex) — the value update/split expect as `expect.content_hash`. */
+    hash?: string;
     attrs?: Record<string, unknown>;
-    placement?: {
-        parent: string | null;
-        ordinal: number;
-        depth: number;
-    };
+    ordinal?: number;
+    depth?: number;
+    /** The parent block's id, null at the top level (`full`). */
+    parent_id?: string | null;
     children?: GetNode[];
 }
 export interface NodesGetOptions {

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

@@ -17,14 +17,16 @@ function project(store, node, resolution, includeChildren) {
             break;
         case "raw":
             out.raw = blockRaw(store, node.rawHashHex);
-            out.content_hash = node.rawHashHex;
+            out.hash = node.rawHashHex;
             break;
         case "full":
             out.raw = blockRaw(store, node.rawHashHex);
-            out.content_hash = node.rawHashHex;
+            out.hash = node.rawHashHex;
             out.text = node.text;
             out.attrs = node.attrs;
-            out.placement = { parent: node.parentBlock, ordinal: node.ordinal, depth: node.depth };
+            out.ordinal = node.ordinal;
+            out.depth = node.depth;
+            out.parent_id = node.parentBlock;
             break;
     }
     if (includeChildren && node.children.length > 0) {

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

@@ -1,10 +1,12 @@
 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. */
+ *  count and last-commit timestamp, under the row attributes' own names
+ *  (spec/surface §1.2, 3.0: `id`, `path`, `updated_at`). */
 export interface DocListRow {
+    id: string;
     path: string;
+    updated_at: string | null;
     blocks: number;
-    ts: string | null;
 }
 /** A page of the docs_list surface. Honors the uniform list contract (mcp-api
  *  §1): `truncated` is honest, and when true `cursor` resumes after the last
@@ -32,16 +34,18 @@ 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"`) or a
- *  collapsed directory (`kind: "dir"`, path ends in `/`) at the requested
- *  depth. `docs`/`blocks` are totals under the entry (a doc counts 1 doc);
- *  `ts` is the latest last-commit timestamp under it. */
+/** 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). */
 export interface DocTreeEntry {
+    id?: string;
     path: string;
     kind: "dir" | "doc";
     docs: number;
     blocks: number;
-    ts: string | null;
+    updated_at: string | null;
 }
 export interface DocTreePage {
     /** The normalized directory prefix the tree was taken under, in the

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

@@ -23,18 +23,16 @@ function liveDocRows(store, repoId, like, after, limit) {
         params.push(limit);
     }
     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
+        .prepare(`SELECT d.doc_id AS id, d.path AS path,
+              (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,
+              (SELECT count(*) FROM blocks b WHERE b.doc_id = d.doc_id AND b.deleted_commit IS NULL) AS blocks
        FROM docs d
        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;
+    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)
@@ -115,7 +113,7 @@ export function docsTree(store, repoId, opts = {}) {
         total.blocks += row.blocks;
         const segs = storage.slice(prefix.length).split("/");
         if (segs.length <= depth) {
-            byPath.set(storage, { path: row.path, kind: "doc", docs: 1, blocks: row.blocks, ts: row.ts });
+            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("/") + "/");
@@ -123,11 +121,11 @@ export function docsTree(store, repoId, opts = {}) {
         if (cur) {
             cur.docs += 1;
             cur.blocks += row.blocks;
-            if (row.ts !== null && (cur.ts === null || row.ts > cur.ts))
-                cur.ts = row.ts;
+            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, ts: row.ts });
+            byPath.set(dir, { path: dir, kind: "dir", docs: 1, blocks: row.blocks, updated_at: row.updated_at });
         }
     }
     let entries = [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));

package/dist/src/format/adapter.d.ts

@@ -17,7 +17,7 @@ export interface ProjectedNode {
     /**
      * `[spanStart, spanEnd)` of the feature within the block's raw, as JavaScript
      * string indices (UTF-16 code units). Ingest converts to UTF-8 byte offsets
-     * before the `nodes` row is written (spec/graph §2.3), and `node_set`
+     * before the `nodes` row is written (spec/graph §2.3), and `nodes_set`
      * converts back before an editor slices the raw.
      */
     spanStart?: number | undefined;

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

@@ -8,7 +8,7 @@ export interface NodeChange {
     confidence: number | null;
     reason: string | null;
 }
-/** history_node: a block's biography from block_changes + commits (06 §3). */
+/** blocks_history: a block's biography from block_changes + commits (06 §3). */
 export declare function historyNode(store: Store, blockId: string, opts?: {
     limit?: number;
 }): NodeChange[];
@@ -18,15 +18,17 @@ 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
+ *  its raw `before`/`after` as applicable. */
 export interface DiffEntry {
     kind: "added" | "removed" | "changed" | "unchanged";
-    blockId: string;
+    id: string;
     before?: string;
     after?: string;
 }
 export declare function diffBlocks(store: Store, docId: string, fromRev: string, toRev: string): DiffEntry[];
 /**
- * `diff_unified` (spec/surface §3): a unified diff of the two revisions'
+ * `docs_diff_unified` (spec/surface §3): a unified diff of the two revisions'
  * **reconstructed file text** — exactly the bytes `docs_read_at` returns for
  * each revision ({@link readDocumentAtRevision}: frontmatter, trivia and
  * top-level order included) — via {@link unifiedDiff}, so hunk line numbers
@@ -36,16 +38,16 @@ export declare function diffBlocks(store: Store, docId: string, fromRev: string,
  * first item (§9). An unknown revision is {@link RevisionNotFound}.
  */
 export declare function diffUnified(store: Store, docId: string, fromRev: string, toRev: string): string;
-/** The `diff_unified` tool's result (spec/surface §3): the resolved revision pair and the diff. */
+/** The `docs_diff_unified` tool's result (spec/surface §3): the resolved revision pair and the diff. */
 export interface DocDiffUnified {
-    doc: string;
+    id: string;
     path: string;
     from: string;
     to: string;
     diff: string;
 }
 /**
- * `diff_unified` over a resolved document: `to` defaults to the current revision,
+ * `docs_diff_unified` over a resolved document: `to` defaults to the current revision,
  * `from` to the one before it (or the current one again when there is only one:
  * an empty diff). Shared by the MCP tool and `omg diff` so the shape cannot
  * drift. `label` is how the caller named the document, for the error message.
@@ -95,12 +97,15 @@ export interface CommitDigest {
     origin: string;
     actor: string | null;
     summary: string;
-    /** `contentHash` (hex of the revision's rendered_hash) lets a puller decide
-     *  "changed vs echo" without a follow-up docs_read/docs_history (ADR-014 §4.2). */
+    /** 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
+     *  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: {
-        doc: string;
+        id: string;
         path: string;
-        contentHash: string;
+        hash: string;
     }[];
 }
 /** changes_since: commit digests after a cursor (repo commit seq) — the change
@@ -124,17 +129,18 @@ export interface DocVersion {
     rev: string;
     seq: number;
     commit: string;
-    ts: 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 — spot no-op vs real change, feed into docs_read_at/diff. */
-    contentHash: string;
+    /** 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;
     /** true when this rev == the doc's current_rev. */
     isCurrent: boolean;
 }
 /** A matching document with its ordered version history. */
 export interface DocVersions {
-    docId: string;
+    id: string;
     path: string;
     deleted: boolean;
     currentRev: string | null;

package/dist/src/graph/history.js

@@ -3,7 +3,7 @@ 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). */
+/** blocks_history: a block's biography from block_changes + commits (06 §3). */
 export function historyNode(store, blockId, opts = {}) {
     const limit = opts.limit ?? 100;
     return store.db
@@ -36,13 +36,13 @@ export function diffBlocks(store, docId, fromRev, toRev) {
     const entries = [];
     for (const [id, raw] of before) {
         if (!after.has(id))
-            entries.push({ kind: "removed", blockId: id, before: raw });
+            entries.push({ kind: "removed", id: id, before: raw });
         else if (after.get(id) !== raw)
-            entries.push({ kind: "changed", blockId: 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", blockId: 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
@@ -78,7 +78,7 @@ function blocksAtRevision(store, docId, revId) {
     return out;
 }
 /**
- * `diff_unified` (spec/surface §3): a unified diff of the two revisions'
+ * `docs_diff_unified` (spec/surface §3): a unified diff of the two revisions'
  * **reconstructed file text** — exactly the bytes `docs_read_at` returns for
  * each revision ({@link readDocumentAtRevision}: frontmatter, trivia and
  * top-level order included) — via {@link unifiedDiff}, so hunk line numbers
@@ -92,12 +92,12 @@ export function diffUnified(store, docId, fromRev, toRev) {
         const at = readDocumentAtRevision(store, docId, rev);
         if (!at)
             throw new RevisionNotFound(docId, rev);
-        return at.content;
+        return at.raw;
     };
     return unifiedDiff(rendered(fromRev), rendered(toRev));
 }
 /**
- * `diff_unified` over a resolved document: `to` defaults to the current revision,
+ * `docs_diff_unified` over a resolved document: `to` defaults to the current revision,
  * `from` to the one before it (or the current one again when there is only one:
  * an empty diff). Shared by the MCP tool and `omg diff` so the shape cannot
  * drift. `label` is how the caller named the document, for the error message.
@@ -113,7 +113,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 { doc: 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
@@ -276,7 +276,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) => ({ doc: r.doc, path: referencePath(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) => ({ 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 or a move writes no revision: the tombstone names the commit
         // (`docs.deleted_commit`), a move only its reason (`move <from> -> <to>`).
@@ -352,13 +352,13 @@ export function docHistory(store, repoId, opts = {}) {
             rev: r.rev,
             seq: r.seq,
             commit: r.commitId,
-            ts: r.ts,
+            updated_at: r.ts,
             origin: r.origin,
             actor: r.actor,
-            contentHash: r.rendered_hash.toString("hex"),
+            hash: r.rendered_hash.toString("hex"),
             isCurrent: r.rev === d.current_rev,
         }));
-        return { docId: 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 };
 }

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

@@ -1,11 +1,11 @@
 import type { Store } from "../core/store/store.js";
 export interface InboundLink {
     /** source document id */
-    doc: string;
-    /** source document repo-relative path */
+    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: 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 */
@@ -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: 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: 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: r.srcDoc, path: r.srcPath, block: 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,9 +46,9 @@ export function inboundLinksTo(store, repoId, docId, docPath) {
             if (e.dstKind === "external" || !resolvesTo(e.target, srcDir, docPath))
                 continue;
             out.push({
-                doc: r.srcDoc,
+                doc_id: r.srcDoc,
                 path: r.srcPath,
-                block: r.srcBlock,
+                block_id: r.srcBlock,
                 target: e.target,
                 anchor: e.anchor,
                 ...(e.srcField ? { field: e.srcField } : {}),

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

@@ -2,14 +2,14 @@ import type { Store } from "../core/store/store.js";
 export type StaleReason = "dangling_doc" | "dangling_block" | "broken_anchor";
 export interface StaleLink {
     /** source document id */
-    srcDoc: string;
-    /** source document repo-relative path */
-    srcPath: string;
+    doc_id: string;
+    /** source document path in the reference form */
+    path: string;
     /** source block id (null for frontmatter-level edges) */
-    srcBlock: string | null;
+    block_id: string | null;
     predicate: string;
     provenance: string;
-    dstKind: string;
+    dst_kind: string;
     /** the canonical target path in the reference form (phantom prefix stripped,
      *  rooted), e.g. "/guides/old.md" — spec/surface §1 "Paths" */
     target: string;
@@ -29,16 +29,16 @@ export interface LinkHealthSummary {
         target: string;
         count: number;
     }[];
-    /** source documents carrying dangling links, most first (ties by path) */
+    /** source documents carrying dangling links, most first (ties by path); `path` the reference form */
     bySource: {
-        srcPath: string;
+        path: string;
         count: number;
     }[];
     externalCount: number;
     totalOpenEdges: number;
 }
 export interface LinkHealth {
-    /** dangling internal links, ordered by srcPath then target */
+    /** dangling internal links, ordered by source path then target */
     stale: StaleLink[];
     /** open external (http(s)) edges — unverifiable, not counted as stale */
     externalCount: number;

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

@@ -88,15 +88,15 @@ 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;
+        // The surface speaks the reference form: `path` and `target` rooted;
         // `authored` stays exactly as written in the source.
         return {
-            srcDoc: r.srcDoc,
-            srcPath: referencePath(r.srcPath),
-            srcBlock: r.srcBlock,
+            doc_id: r.srcDoc,
+            path: referencePath(r.srcPath),
+            block_id: r.srcBlock,
             predicate: r.predicate,
             provenance: r.provenance,
-            dstKind: r.dstKind,
+            dst_kind: r.dstKind,
             target: referencePath(target),
             authored: authoredFor(r.srcBlock, r.srcPath, target, r.anchor),
             anchor: r.anchor,
@@ -140,7 +140,7 @@ export function linksStaleSummary(store, repoId, opts = {}) {
     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)
-        .map((r) => ({ srcPath: referencePath(r.srcPath), count: r.count }));
+        .map((r) => ({ path: referencePath(r.srcPath), count: r.count }));
     return {
         staleCount: byTarget.reduce((n, t) => n + t.count, 0),
         byTarget,

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

@@ -1,15 +1,15 @@
 import type { Store } from "../core/store/store.js";
 export interface LinkEdge {
     predicate: string;
-    /** the other endpoint (dst for out-edges, src for in-edges) */
-    node: string;
+    /** the other endpoint (dst for out-edges, src for in-edges): a doc id, an external node id or `phantom:<path>` */
+    doc_id: string;
     kind: string;
     /** how many underlying block-grain edges this doc-grain row rolls up */
     count: number;
     /** sample source block ids (out-edges only) */
     samples?: string[];
     /** block-grain (`blocks: true`): the source block of this edge (null for a frontmatter edge) */
-    block?: string | null;
+    block_id?: string | null;
 }
 export interface LinksResult {
     out: LinkEdge[];