omgbase 0.25.0 → 0.26.1

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "fd89bb5",
-  "built": "2026-10-19T05:50:09.952Z"
+  "commit": "2637bbd",
+  "built": "2026-10-21T19:17:55.419Z"
 }

package/dist/src/cmd/_mutate.d.ts

@@ -52,7 +52,9 @@ export declare function runSugar(cli: Cli, ws: Workspace, repo: RepoRow, sugar:
  * `refs` are the refs the verb received, refused there when one is a locator.
  */
 export declare function runSugarRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>, refs?: string[]): Promise<number>;
-/** A ref as an effect target for a remote `plan`: a `b_` id is the block, a `d_` id the document, anything else a document path. */
+/** A ref as an effect target for a remote `plan` (spec/mutate §11, 4.0: the address is the
+ *  row's engine attribute): a `b_` id is the block (`_id`), a `d_` id the document (`_id`),
+ *  anything else a document path (`_path`). */
 export declare function targetOf(ref: string): EffectTarget;
 /**
  * `apply` given `{ effects }`: plan + execute as one transaction

package/dist/src/cmd/_mutate.js

@@ -162,13 +162,15 @@ export async function runSugarRemote(cli, tool, toolArgs, effects, refs = []) {
         return renderPlan(cli, await remoteCall(cli, "plan", { effects: await effects(), diffs: true }));
     return renderReceipt(cli, await remoteSugar(cli, tool, toolArgs, effects, refs));
 }
-/** A ref as an effect target for a remote `plan`: a `b_` id is the block, a `d_` id the document, anything else a document path. */
+/** A ref as an effect target for a remote `plan` (spec/mutate §11, 4.0: the address is the
+ *  row's engine attribute): a `b_` id is the block (`_id`), a `d_` id the document (`_id`),
+ *  anything else a document path (`_path`). */
 export function targetOf(ref) {
     if (isValidId(ref, "b"))
-        return { kind: "block", id: ref };
+        return { kind: "block", _id: ref };
     if (isValidId(ref, "d"))
-        return { kind: "document", id: ref };
-    return { kind: "document", path: ref };
+        return { kind: "document", _id: ref };
+    return { kind: "document", _path: ref };
 }
 // ---- the Effect layer (ADR-021; spec/cli 3.2 `apply -f { effects }`, `execute`) ----
 /**

package/dist/src/cmd/_remote.d.ts

@@ -25,13 +25,15 @@ export declare function isLocator(ref: string): boolean;
  * usage error there rather than a bogus document path.
  */
 export declare function remoteSugar<T>(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>, refs?: string[]): Promise<T>;
-/** A document ref as the surface's locator (spec/surface §4 "Arguments", 3.0):
- *  a `d_` id is the `id` argument, anything else the `path` — the two names a
- *  `docs_*` tool takes (one of them required). */
+/** A document ref as the surface's locator (spec/surface §4 "Arguments", 5.0):
+ *  a `d_` id is the `_id` argument, anything else the `_path` — the two names a
+ *  `docs_*` tool takes (one of them required; the bare `id`/`path` are refused
+ *  there as `filter_invalid`). The same pair is a document effect target's
+ *  address (`{ kind: "document", _id | _path }`, spec/mutate §11). */
 export declare function docLocator(ref: string): {
-    id: string;
+    _id: string;
 } | {
-    path: string;
+    _path: string;
 };
 /** The live document a ref names, for a LOCAL verb, or the surface's own
  *  `doc_missing` ("no document with id or path "<ref>"", `data` the locator) —

package/dist/src/cmd/_remote.js

@@ -85,11 +85,13 @@ export async function remoteSugar(cli, tool, toolArgs, effects, refs = []) {
     const reason = typeof toolArgs.reason === "string" ? toolArgs.reason : tool;
     return remoteCall(cli, "apply", { effects: await effects(), reason });
 }
-/** A document ref as the surface's locator (spec/surface §4 "Arguments", 3.0):
- *  a `d_` id is the `id` argument, anything else the `path` — the two names a
- *  `docs_*` tool takes (one of them required). */
+/** A document ref as the surface's locator (spec/surface §4 "Arguments", 5.0):
+ *  a `d_` id is the `_id` argument, anything else the `_path` — the two names a
+ *  `docs_*` tool takes (one of them required; the bare `id`/`path` are refused
+ *  there as `filter_invalid`). The same pair is a document effect target's
+ *  address (`{ kind: "document", _id | _path }`, spec/mutate §11). */
 export function docLocator(ref) {
-    return isValidId(ref, "d") ? { id: ref } : { path: ref };
+    return isValidId(ref, "d") ? { _id: ref } : { _path: ref };
 }
 /** The live document a ref names, for a LOCAL verb, or the surface's own
  *  `doc_missing` ("no document with id or path "<ref>"", `data` the locator) —
@@ -105,7 +107,7 @@ export function requireDoc(store, repoId, ref) {
 export function requireNode(store, repoId, nodeId) {
     const row = store.db.prepare("SELECT 1 FROM nodes WHERE node_id = ? AND repo_id = ?").get(nodeId, repoId);
     if (!row)
-        throw new EngineErrorLike("block_missing", `no node with id ${JSON.stringify(nodeId)}`, { data: { id: nodeId } });
+        throw new EngineErrorLike("block_missing", `no node with id ${JSON.stringify(nodeId)}`, { data: { _id: nodeId } });
     return nodeId;
 }
 /** Close the remote connection if one was opened (idempotent). Called after a

package/dist/src/cmd/cat.js

@@ -49,12 +49,12 @@ async function catOne(cli, ref, resolution) {
     if (cli.flags.server) {
         const tool = blockReadTool(ref);
         if (tool) {
-            const r = await remoteCall(cli, tool, { id: ref, resolution });
-            return { text: String(r.raw ?? r.text ?? r.label ?? ""), json: r, capture: r };
+            const r = await remoteCall(cli, tool, { _id: ref, resolution });
+            return { text: String(r._raw ?? r._text ?? r.label ?? ""), json: r, capture: r };
         }
         const r = await remoteCall(cli, "docs_read", docLocator(ref));
         warnDocResolution(cli, ref, resolution);
-        return { text: String(r.raw ?? ""), json: r, capture: r.raw };
+        return { text: String(r._raw ?? ""), json: r, capture: r._raw };
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -72,13 +72,13 @@ async function catOne(cli, ref, resolution) {
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
         warnDocResolution(cli, ref, resolution);
         // shell: the bytes (a string; @_ only). `--json` is the `docs_read` result.
-        return { text: res.raw, json: res, capture: res.raw };
+        return { text: res._raw, json: res, capture: res._raw };
     }
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution });
     if (!node)
         throw new EngineErrorLike("block_missing", `no block ${ref}`);
     // shell: the block (single entity)
-    return { text: node.raw ?? node.text ?? node.label ?? "", json: node, capture: node };
+    return { text: node._raw ?? node._text ?? node.label ?? "", json: node, capture: node };
 }
 async function runCat(cli, args) {
     const { values, positionals } = parseArgs({

package/dist/src/cmd/diff.js

@@ -3,7 +3,7 @@ import { findDoc, docDiffUnified, diffBlocks } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall, docLocator } from "./_remote.js";
 // `omg diff <doc>` (11 §5.5) — `docs_diff_unified`: the unified diff, `--json` the
-// tool's `{ doc, path, from, to, diff }`. With no revisions: current vs previous
+// tool's `{ _id, _path, from, to, diff }` (spec/surface §3, 5.0). With no revisions: current vs previous
 // ("what did the last commit do here"). `--blocks` is the block-grain `diff`
 // tool: added/removed/changed blocks between the same two revisions.
 async function runDiff(cli, args) {
@@ -54,9 +54,9 @@ async function runDiff(cli, args) {
         if (cli.flags.server)
             entries = await remoteCall(cli, "docs_diff", { ...docLocator(ref), from_rev: result.from, to_rev: result.to });
         else
-            entries = diffBlocks(cli.workspace().store, result.id, result.from, result.to);
+            entries = diffBlocks(cli.workspace().store, result._id, result.from, result.to);
         if (cli.flags.mode !== "human")
-            return emitMachine(cli, entries, { items: entries, ids: entries.map((e) => e.id) });
+            return emitMachine(cli, entries, { items: entries, ids: entries.map((e) => e._id) });
         if (entries.length === 0) {
             io.err(style.dim("  no changes"));
             return EXIT_OK;
@@ -64,7 +64,7 @@ async function runDiff(cli, args) {
         for (const e of entries) {
             const mark = e.kind === "added" ? style.ok("+") : e.kind === "removed" ? style.err("-") : style.warn("~");
             const preview = (e.after ?? e.before ?? "").split("\n")[0] ?? "";
-            io.out(`${mark} ${style.id(e.id)}  ${preview}`.trimEnd());
+            io.out(`${mark} ${style.id(e._id)}  ${preview}`.trimEnd());
         }
         return EXIT_OK;
     }

package/dist/src/cmd/edit.js

@@ -38,10 +38,10 @@ function runEdit(cli, args) {
     const repo = cli.repo(ws);
     const resolved = resolveRef(ws.store, repo.repoId, ref);
     if (!resolved || resolved.kind !== "block")
-        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { _id: ref } });
     const blockId = resolved.blockId;
     const node = nodesGet(ws.store, resolved.docId, blockId, { resolution: "raw" });
-    const before = node?.raw ?? "";
+    const before = node?._raw ?? "";
     const preHash = rawHashOf(ws, blockId); // pin BEFORE the editor opens
     const editor = process.env.OMG_EDITOR ?? process.env.VISUAL ?? process.env.EDITOR;
     if (!editor)

package/dist/src/cmd/find.js

@@ -3,8 +3,9 @@ import { resolve as resolveThing, surfaceResolveHits } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
-// `omg find <text>` (11 §5.2) — resolve: ranked {id, locator, preview,
-// evidence}. `-1` prints the top hit's id alone (pipe fuel: omg cat $(omg find … -1)).
+// `omg find <text>` (11 §5.2) — resolve: ranked {_id, locator, preview,
+// evidence} (spec/surface §4 `blocks_resolve`, 5.0). `-1` prints the top hit's
+// id alone (pipe fuel: omg cat $(omg find … -1)).
 async function runFind(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -65,18 +66,18 @@ async function runFind(cli, args) {
     // -1: bare top id.
     if (values.one) {
         if (hits[0])
-            cli.io.out(hits[0].id);
+            cli.io.out(hits[0]._id);
         return EXIT_OK;
     }
     if (cli.flags.mode !== "human")
-        return emitMachine(cli, hits, { items: hits, ids: hits.map((h) => h.id) });
+        return emitMachine(cli, hits, { items: hits, ids: hits.map((h) => h._id) });
     const { style, io } = cli;
     if (hits.length === 0) {
         io.err(style.dim("  no matches"));
         return EXIT_OK;
     }
     for (const h of hits) {
-        io.out(`${style.id(h.id)}  ${style.accent(h.locator)}  ${h.preview}`);
+        io.out(`${style.id(h._id)}  ${style.accent(h.locator)}  ${h.preview}`);
         if (values.verbose)
             io.err(style.dim(`    ${JSON.stringify(h.evidence)}`));
     }

package/dist/src/cmd/hist.js

@@ -24,7 +24,7 @@ async function runHist(cli, args) {
     if (cli.flags.server) {
         // Remote: blocks_history keys on a block id (globally unique). Pass the ref
         // through — a locator would need a local resolve, so remote hist wants an id.
-        changes = await remoteCall(cli, "blocks_history", { id: ref, ...(values.n ? { limit: Number(values.n) } : {}) });
+        changes = await remoteCall(cli, "blocks_history", { _id: ref, ...(values.n ? { limit: Number(values.n) } : {}) });
     }
     else {
         const ws = cli.workspace();

package/dist/src/cmd/links.js

@@ -3,7 +3,10 @@ import { resolveRef, docLinks } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 // `omg links <node>` (11 §5.4) — open links touching the node; default both
 // directions, grouped; doc-grain by default, --blocks for block-grain (one row
-// per edge, naming the source block). Backlinks = --in.
+// per edge, naming the source block). Backlinks = --in. A row is
+// `{ _predicate, _doc_id, kind, count, samples? | _block_id }` (spec/cli 5.0):
+// the keys that carry a links-row attribute are `_`-prefixed; `kind` (what the
+// far node is), `count` (the rollup) and `samples` name roles and stay bare.
 function runLinks(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -47,7 +50,7 @@ function runLinks(cli, args) {
     cli.capture?.(result); // shell: edges (out+in) become the addressable frame
     // `{ out, in }` is not a list: `--jsonl` prints the document; `--ids` the far nodes.
     if (cli.flags.mode !== "human")
-        return emitMachine(cli, result, { ids: [...result.out, ...result.in].map((e) => e.doc_id) });
+        return emitMachine(cli, result, { ids: [...result.out, ...result.in].map((e) => e._doc_id) });
     const { render, style, io } = cli;
     const g = render.g;
     if (result.out.length === 0 && result.in.length === 0) {
@@ -56,23 +59,23 @@ function runLinks(cli, args) {
     }
     // Doc-grain: one row per (predicate, node) with its rollup count. Block-grain:
     // one row per edge, the source block beside the far node.
-    const src = (e) => style.dim(`(${e.block_id ?? "frontmatter"})`);
+    const src = (e) => style.dim(`(${e._block_id ?? "frontmatter"})`);
     if (result.out.length > 0) {
         io.out(style.dim("  out"));
         for (const e of result.out) {
             if (values.blocks)
-                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.doc_id)} ${src(e)}`);
+                io.out(`    ${style.accent(e._predicate)} ${style.dim(g.arrow)} ${style.id(e._doc_id)} ${src(e)}`);
             else
-                io.out(`    ${style.accent(e.predicate)} ${style.dim(g.arrow)} ${style.id(e.doc_id)} ${style.dim(`×${e.count}`)}`);
+                io.out(`    ${style.accent(e._predicate)} ${style.dim(g.arrow)} ${style.id(e._doc_id)} ${style.dim(`×${e.count}`)}`);
         }
     }
     if (result.in.length > 0) {
         io.out(style.dim("  in (backlinks)"));
         for (const e of result.in) {
             if (values.blocks)
-                io.out(`    ${style.id(e.doc_id)} ${src(e)} ${style.dim(g.arrow)} ${style.accent(e.predicate)}`);
+                io.out(`    ${style.id(e._doc_id)} ${src(e)} ${style.dim(g.arrow)} ${style.accent(e._predicate)}`);
             else
-                io.out(`    ${style.id(e.doc_id)} ${style.dim(g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
+                io.out(`    ${style.id(e._doc_id)} ${style.dim(g.arrow)} ${style.accent(e._predicate)} ${style.dim(`×${e.count}`)}`);
         }
     }
     return EXIT_OK;

package/dist/src/cmd/ls.js

@@ -38,20 +38,20 @@ async function runLs(cli, args) {
         rows.push(...page.items);
         cursor = page.truncated ? page.cursor : null;
     } while (cursor);
-    cli.capture?.(rows); // shell: docs become the addressable frame (ref = id, label path)
-    // `--ids` prints the documents' `id`s (spec/cli 3.0; the paths before, a
-    // stand-in for an identity the row did not carry).
+    cli.capture?.(rows); // shell: docs become the addressable frame (ref = _id, label _path)
+    // `--ids` prints the documents' `_id`s (spec/cli 5.0 — the row's engine
+    // attribute; the paths before 3.0, a stand-in for an identity the row did not carry).
     if (cli.flags.mode !== "human")
-        return emitMachine(cli, rows, { items: rows, ids: rows.map((r) => r.id) });
+        return emitMachine(cli, rows, { items: rows, ids: rows.map((r) => r._id) });
     const { style, io } = cli;
     if (rows.length === 0) {
         io.err(style.dim("  no documents"));
         return EXIT_OK;
     }
     const table = rows.map((r) => [
-        style.accent(r.path),
+        style.accent(r._path),
         style.dim(`${r.blocks} blocks`),
-        style.dim(relTime(r.updated_at)),
+        style.dim(relTime(r._updated_at)),
     ]);
     for (const line of columns(table, [{}, { align: "right" }, { align: "right" }]))
         io.out(line);

package/dist/src/cmd/mutate.js

@@ -12,34 +12,38 @@ import { remoteCall, remoteHasTool } from "./_remote.js";
 // conflict rendering). `apply` is the primitive — a changeset of `effects`
 // (ADR-021, the intentional-write vocabulary; the kernel `ops` input is retired
 // at cli 4.0) — and `execute` commits a frozen plan; the rest are sugar.
+// Error data spells a row attribute as the attribute (spec/surface §4, 5.0):
+// `block_missing { _id }`, and the CLI's own `type_mismatch` names the block's
+// `_id` and `_type`.
 function block(cli, ws, repoId, ref) {
     const r = resolveRef(ws.store, repoId, ref);
     if (!r || r.kind !== "block")
-        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { _id: ref } });
     return r.blockId;
 }
 // A parent ref for insert/move: a block ref names that block as the parent; a
 // document ref (id or path) names the document's top level — the same reading
-// the server gives `blocks_insert.to` / `blocks_move.to`.
+// the server gives `blocks_insert.to` / `blocks_move.to`. The target's address
+// is the row's `_id` (spec/mutate §11, 4.0).
 function parent(ws, repoId, ref) {
     const r = resolveRef(ws.store, repoId, ref);
     if (!r)
-        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { _id: ref } });
     if (r.kind === "document")
-        return { kind: "document", id: r.docId };
-    return { kind: "block", id: r.blockId };
+        return { kind: "document", _id: r.docId };
+    return { kind: "block", _id: r.blockId };
 }
 // `done` addresses task blocks only (spec/cli §6): any other live block type is
 // a type_mismatch before an op is built — the macro itself would record a no-op
-// `edited` commit (its `attrs.checked` only rewrites a task's marker).
+// `edited` commit (its `_attrs.checked` only rewrites a task's marker).
 function taskBlock(ws, ref, blockId) {
     const row = ws.store.db
         .prepare("SELECT type FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
         .get(blockId);
     if (!row)
-        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { _id: ref } });
     if (row.type !== "task") {
-        throw new EngineErrorLike("type_mismatch", `not a task: ${ref} is a ${row.type}`, { data: { block: blockId, type: row.type } });
+        throw new EngineErrorLike("type_mismatch", `not a task: ${ref} is a ${row.type}`, { data: { _id: blockId, _type: row.type } });
     }
     return blockId;
 }
@@ -198,7 +202,7 @@ async function runUpdate(cli, args) {
     const expect = values.expect ? { content_hash: values.expect } : undefined;
     // Remote: the server pins CAS from current bytes when --expect is absent.
     if (cli.flags.server) {
-        return runSugarRemote(cli, "blocks_update", { id: ref, markdown, ...(expect ? { expect } : {}) }, () => updateBlockEffects(ref, { markdown, expect }).effects, [ref]);
+        return runSugarRemote(cli, "blocks_update", { _id: ref, markdown, ...(expect ? { expect } : {}) }, () => updateBlockEffects(ref, { markdown, expect }).effects, [ref]);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
@@ -306,7 +310,7 @@ async function runDone(cli, args) {
         throw new CliUsageError("done requires one or more task blocks (or - for stdin)");
     const checked = !values.undo;
     if (cli.flags.server)
-        return runSugarRemote(cli, "blocks_check", { ids: refs, ...(values.undo ? { checked: false } : {}) }, () => checkEffects(refs, checked).effects, refs);
+        return runSugarRemote(cli, "blocks_check", { _ids: refs, ...(values.undo ? { checked: false } : {}) }, () => checkEffects(refs, checked).effects, refs);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => taskBlock(ws, r, block(cli, ws, repo.repoId, r)));
@@ -341,13 +345,13 @@ async function runAppend(cli, args) {
     // Remote: blocks_append resolves the ref and decides by the block's kind
     // server-side (spec/surface §4); a remote dry run reads the kind first.
     if (cli.flags.server) {
-        return runSugarRemote(cli, "blocks_append", { id: target, text: markdown }, async () => {
-            // The block's type decides the effect; `blocks_read` reads it on a full
+        return runSugarRemote(cli, "blocks_append", { _id: target, text: markdown }, async () => {
+            // The block's `_type` decides the effect; `blocks_read` reads it on a full
             // server, a `query` over the blocks target on a minimal one (§2.3).
             const type = (await remoteHasTool(cli, "blocks_read"))
-                ? (await remoteCall(cli, "blocks_read", { id: target, resolution: "skeleton" })).type
-                : (await remoteCall(cli, "query", { query: `select type from blocks where id == ${JSON.stringify(target)}` })).hits[0]?.type;
-            return appendEffects(type === "heading" ? { kind: "section", heading_id: target } : { kind: "block", id: target }, markdown).effects;
+                ? (await remoteCall(cli, "blocks_read", { _id: target, resolution: "skeleton" }))._type
+                : (await remoteCall(cli, "query", { query: `select _type from blocks where _id == ${JSON.stringify(target)}` })).hits[0]?._type;
+            return appendEffects(type === "heading" ? { kind: "section", heading_id: target } : { kind: "block", _id: target }, markdown).effects;
         }, [target]);
     }
     const ws = cli.workspace();
@@ -363,13 +367,13 @@ function appendSugar(store, blockId, markdown) {
         .prepare("SELECT b.type AS type, d.format AS format, (SELECT count(*) FROM blocks c WHERE c.parent_block = b.block_id AND c.deleted_commit IS NULL) AS children FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ? AND b.deleted_commit IS NULL")
         .get(blockId);
     if (!row)
-        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(blockId)}`, { data: { id: blockId } });
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(blockId)}`, { data: { _id: blockId } });
     if (row.type === "heading")
         return appendEffects({ kind: "section", heading_id: blockId }, markdown);
     if (isContainerBlock(row.format ?? "markdown", { type: row.type, children: new Array(row.children) })) {
-        return appendEffects({ kind: "block", id: blockId }, markdown);
+        return appendEffects({ kind: "block", _id: blockId }, markdown);
     }
-    throw new EngineErrorLike("block_not_container", `block ${blockId} is a ${row.type}, not a heading or a container; append means into — insert after it with blocks_insert { to: <its parent>, at: { after: ${JSON.stringify(blockId)} } }`, { data: { id: blockId, type: row.type } });
+    throw new EngineErrorLike("block_not_container", `block ${blockId} is a ${row.type}, not a heading or a container; append means into — insert after it with blocks_insert { to: <its parent>, at: { after: ${JSON.stringify(blockId)} } }`, { data: { _id: blockId, _type: row.type } });
 }
 // ---- split / merge ----------------------------------------------------------
 async function runSplit(cli, args) {
@@ -403,7 +407,7 @@ async function runSplit(cli, args) {
         return n;
     });
     if (cli.flags.server)
-        return runSugarRemote(cli, "blocks_split", { id: ref, at }, () => splitEffects(ref, at).effects, [ref]);
+        return runSugarRemote(cli, "blocks_split", { _id: ref, at }, () => splitEffects(ref, at).effects, [ref]);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, ref);

package/dist/src/cmd/node.js

@@ -39,9 +39,9 @@ async function runNode(cli, args) {
         if (!nodeId || !prop || valueParts.length === 0)
             throw new CliUsageError("node set <nodeId> <prop> <value>");
         const value = valueParts.join(" ");
-        // Remote: nodes_set resolves node → block + rewrites the span server-side.
+        // Remote: nodes_set (`_id` the node, spec/surface §4 "Arguments", 5.0) resolves node → block + rewrites the span server-side.
         if (cli.flags.server)
-            return runSugarRemote(cli, "nodes_set", { id: nodeId, prop, value }, () => nodeSetEffects(nodeId, prop, value).effects, [nodeId]);
+            return runSugarRemote(cli, "nodes_set", { _id: nodeId, prop, value }, () => nodeSetEffects(nodeId, prop, value).effects, [nodeId]);
         const ws = cli.workspace();
         const repo = cli.repo(ws);
         return runSugar(cli, ws, repo, nodeSetEffects(requireNode(ws.store, repo.repoId, nodeId), prop, value), values.actor ? { actor: values.actor } : {});

package/dist/src/cmd/oqx.d.ts

@@ -5,8 +5,8 @@ import type { Cli } from "../context.js";
  * Render an `OqxResult` in the current mode (shared with `run`). `--json` is the
  * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
  * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
- * `--ids` the hit ids — a scalar result has neither, so those modes print the
- * document, and so does a `bare` result (its hits carry no envelope). The
+ * `--ids` the hits' `_id`s — a scalar result has neither, so those modes print
+ * the document, and so does a `bare` result (its hits carry no envelope). The
  * truncation footer prints in every mode but `--json`.
  */
 export declare function renderOqxResult(cli: Cli, result: OqxResult, bare?: boolean): number;

package/dist/src/cmd/oqx.js

@@ -6,15 +6,17 @@ import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
 import { readStdin } from "./_mutate.js";
 // `omg query <source>` — OQX composable query. Dot navigation belongs to the host
-// object model (`doc.layer`, `section.blocks`); whitespace query directives
-// belong to OQX (`<receiver> collect|exists|count|first|single { <block> }`).
+// object model (`_doc.layer`, `$it._blocks`; spec/surface §1.2, 5.0: an engine
+// name is `_`-prefixed, a bare name is an authored key, `$it` is the self);
+// whitespace query directives belong to OQX (`<receiver>
+// collect|exists|count|first|single { <block> }`).
 // `from E` selects + flattens a relation relative to the current source scope
 // (top-level `from docs` = the repository's docs; `docs collect { from
 // nodes … }` re-projects each doc through its nodes). Clause order is fixed
 // (ADR-020): `select … from … where … follow … order by … limit … offset …`,
 // each at most once, at the top level and inside every block. Only `select` may
-// drop its keyword, and only as the first clause (`nodes collect { attrs.text }`
-// projects); a predicate always needs `where` (`nodes exists { where kind ==
+// drop its keyword, and only as the first clause (`_nodes collect { _name }`
+// projects); a predicate always needs `where` (`_nodes exists { where _kind ==
 // "md:task" }`), so a bare boolean property projects rather than filters.
 // `where` may use the body's select aliases. Features: a boolean where
 // tree over scalar predicates and consumer directives, count comparisons
@@ -29,13 +31,13 @@ import { readStdin } from "./_mutate.js";
 // `docs count { … }` / `docs exists { … }` reduce to a scalar,
 // `docs first { … }` / `docs single { … }` to zero-or-one row (bare
 // `from …` = collect). Coexists with `omg q` (CEL). Source is a positional
-// string or -f file|-. Human output: one hit per line (id + path), or an aligned
-// id/path/columns table when the query projects (`select`), or the scalar for
-// count/exists/none (see output.ts renderHits); --json/--jsonl/--ids. `--bare`
-// is the tool's `bare` passed through (ADR-012: a thin client; spec/surface
-// §1.4, 4.2): every hit is its projection alone, rendered as a table without
-// the id/path columns (`--json`/`--jsonl` the bare hits; `--ids` has no id to
-// print and falls back to the document, like a scalar result).
+// string or -f file|-. Human output: one hit per line (_id + _path), or an
+// aligned _id/_path/columns table when the query projects (`select`), or the
+// scalar for count/exists/none (see output.ts renderHits); --json/--jsonl/--ids.
+// `--bare` is the tool's `bare` passed through (ADR-012: a thin client;
+// spec/surface §1.4, 4.2): every hit is its projection alone, rendered as a
+// table without the _id/_path columns (`--json`/`--jsonl` the bare hits;
+// `--ids` has no id to print and falls back to the document, like a scalar result).
 async function runOqx(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -58,39 +60,40 @@ async function runOqx(cli, args) {
                 ["-f <file|->", "read the query from a file, or stdin with `-`"],
                 ["-n <N>", "page size"],
                 ["--cursor <c>", "continue a truncated result"],
-                ["--bare", "hits as the projection only — no automatic id/path columns (needs a `select`; `values` is the bare-values form)"],
+                ["--bare", "hits as the projection only — no automatic _id/_path columns (needs a `select`; `values` is the bare-values form)"],
                 ["--ids", `bare ids, one per line — pipe fuel (\`… --ids | ${cli.prog} cat -\`)`],
             ],
             notes: [
                 `semantic ranking: \`order by semantic("phrase") desc\` or \`where semantic("phrase") > 0.6\` (needs embedding.provider; see \`${cli.prog} embed --help\`).`,
                 "full syntax: the examples below, the MCP `query_syntax` tool, and docs/query-language.md.",
+                "names: an engine field is `_`-prefixed (_id _path _title _tags _updated_at _type _text _doc …); a bare name is an authored key (title, tags, layer); `$it` is the row itself.",
                 "examples:",
             ],
         });
-        cli.io.out("  e.g. query 'from docs where nodes count { where kind == \"md:task\" } >= 2'");
-        cli.io.out("       query 'select items: section.blocks collect { where type == \"list_item\" } from nodes where kind == \"md:section\"'");
-        cli.io.out("       query 'select path, open from docs where nodes collect { ^open: value where kind == \"md:task\" and not attrs.checked }'");
-        cli.io.out("       query 'select owner_id, owner: ^nodes single { where kind == \"person\" and attrs.id == ^owner_id } from docs'   # ^docs/^nodes/^blocks/^links: the repository (the root row) from inside a row; 0^docs from any depth; ^id / 0^id = the repository id");
+        cli.io.out("  e.g. query 'from docs where _nodes count { where _kind == \"md:task\" } >= 2'");
+        cli.io.out("       query 'select items: _blocks collect { where _type == \"list_item\" } from nodes where _kind == \"md:section\"'");
+        cli.io.out("       query 'select _title, open from docs where _nodes collect { ^open: _value where _kind == \"md:task\" and not checked }'");
+        cli.io.out("       query 'select owner_id, owner: ^nodes single { where _kind == \"person\" and id == ^owner_id } from docs'   # ^docs/^nodes/^blocks/^links: the repository (the root row) from inside a row; 0^docs from any depth; ^_id / 0^_id = the repository id");
         cli.io.out("       query 'docs count { where layer == \"canon\" }'   # scalar; also <target> exists/none/first/single { … } at the top level");
-        cli.io.out("       query 'from docs where nodes none { where kind == \"md:task\" and not checked }'   # none = zero rows (≡ not … exists; \"every\" = none over the complement)");
+        cli.io.out("       query 'from docs where _nodes none { where _kind == \"md:task\" and not checked }'   # none = zero rows (≡ not … exists; \"every\" = none over the complement)");
         cli.io.out("       query 'from docs where era is not null and (layer == \"canon\" or layer == \"working\")'   # and / or / not are the connectives (&& || ! accepted); x is y / x is not y = identity, x is null = absent");
-        cli.io.out("       query 'docs { type == \"substance\" and not verified }'   # sugar: a block without a consumer is collect; a leading predicate drops `where` (bare names still project — filter a bare field with `is x`); after a follow destination too: follow children { depth 2 } is its block");
-        cli.io.out("       query 'select subject, process: ^docs[slug == ^subject].path from docs where type == \"lab-note\"'   # x[p] = first match or absent; x[p]! = exactly one, required; x[n] = positional; title! = the value or a loud error; a select item may use the items to its left");
-        cli.io.out("       query 'select path, $depth from docs where path == \"/timeline/review.md\" follow refs(before), refs(after)'   # refs(field): the live documents a property's references name (either path form or a d_ id; dangling dropped) — a receiver, a source or a follow destination");
-        cli.io.out("       query 'select path, next: ^docs { ^path in list(before) } from docs where type == \"milestone\"'   # paths are /-rooted on the surface (path == \"/x.md\"; inputs accept both forms), so a property's reference compares with ^path directly");
+        cli.io.out("       query 'docs { type == \"substance\" and not verified }'   # sugar: a block without a consumer is collect; a leading predicate drops `where` (bare names still project — filter a bare field with `is x`); after a follow destination too: follow _children { depth 2 } is its block");
+        cli.io.out("       query 'select subject, process: ^docs[slug == ^subject]._path from docs where type == \"lab-note\"'   # x[p] = first match or absent; x[p]! = exactly one, required; x[n] = positional; _title! = the value or a loud error; a select item may use the items to its left");
+        cli.io.out("       query 'select _title, $depth from docs where _path == \"/timeline/review.md\" follow refs(before), refs(after)'   # refs(field): the live documents a property's references name (either path form or a d_ id; dangling dropped) — a receiver, a source or a follow destination");
+        cli.io.out("       query 'select _title, next: ^docs { ^_path in list(before) } from docs where type == \"milestone\"'   # paths are /-rooted on the surface (_path == \"/x.md\"; inputs accept both forms), so a property's reference compares with ^_path directly");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc limit 2 offset 1'   # limit/offset bound the set (after order/distinct, before the consumer)");
-        cli.io.out("       query 'select fm: entries(frontmatter) collect { k: $key, v: $it } from docs where path == \"/x.md\"'   # a record as a collection ($key/$it); also entries(attrs), entries(inline)");
-        cli.io.out("       query 'select path values from docs where layer == \"canon\"'   # `values`: bare values, no {id,path} hits (one item only)");
-        cli.io.out("       query 'select path, tags: tags collect { $it values where $it != \"draft\" } from docs'   # $it = the current item (here: each tag)");
-        cli.io.out("       query 'docs collect { from nodes where kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
+        cli.io.out("       query 'select fm: entries(_frontmatter) collect { k: $key, v: $it } from docs where _path == \"/x.md\"'   # a record as a collection ($key/$it); also entries(_data), entries(_attrs), entries(_inline)");
+        cli.io.out("       query 'select _path values from docs where layer == \"canon\"'   # `values`: bare values, no {_id,_path} hits (one item only)");
+        cli.io.out("       query 'select _title, tags: _tags collect { $it values where $it != \"draft\" } from docs'   # $it = the current item (here: each tag); _tags = authored tags ∪ #hashtags, bare `tags` the authored key alone");
+        cli.io.out("       query 'docs collect { from _nodes where _kind == \"md:task\" }'   # `from E` re-projects the source (→ nodes)");
         cli.io.out("       query 'from docs where text(\"philosophers stone\") and layer == \"canon\"'   # full-text prune");
         cli.io.out("       query 'select s: semantic(\"the great work\") from blocks where semantic(\"the great work\") > 0.6'  # embedding score (needs a provider)");
         cli.io.out("       query 'from docs where type == \"practitioner\" order by era desc'   # order by <expr> [asc|desc]");
-        cli.io.out("       query 'select t: text, d: $depth, s: $stop from blocks where id == \"b_x\" follow block.children'   # recursive walk ($depth/$stop metadata)");
-        cli.io.out("       query 'from nodes where name == \"Overview\" follow section.subsections { depth 3 }'   # follow [distinct] <dest> [{ where … frontier … depth n }] — a brace after any destination is that destination's block (identity is $key: project $key: <expr> to rekey a walk)");
-        cli.io.out("       query 'select p: path, d: $depth, s: $stop from docs where path == \"/index.md\" follow out_links collect { from dst }'   # citation graph (cyclic-safe: $stop=cycle)");
-        cli.io.out("       query 'from blocks where type == \"list_item\" and $leaf follow block.children'   # $leaf/$depth/$stop filter the walk result post-walk");
-        cli.io.out("       query 'select src: doc_id, to: dst_path from links where predicate == \"depends_on\"'   # the links target: predicate/provenance/dst_kind + doc_id/dst_path/uri");
+        cli.io.out("       query 'select t: _text, d: $depth, s: $stop from blocks where _id == \"b_x\" follow _children'   # recursive walk ($depth/$stop metadata)");
+        cli.io.out("       query 'from nodes where _name == \"Overview\" follow _subsections { depth 3 }'   # follow [distinct] <dest> [{ where … frontier … depth n }] — a brace after any destination is that destination's block (identity is $key: project $key: <expr> to rekey a walk)");
+        cli.io.out("       query 'select p: _doc._path, d: $depth, s: $stop from docs where _path == \"/index.md\" follow _out_links collect { from _dst }'   # citation graph (cyclic-safe: $stop=cycle)");
+        cli.io.out("       query 'from blocks where _type == \"list_item\" and $leaf follow _children'   # $leaf/$depth/$stop filter the walk result post-walk");
+        cli.io.out("       query 'select src: _doc_id, to: _dst_path from links where _predicate == \"depends_on\"'   # the links target: _predicate/_provenance/_dst_kind + _doc_id/_dst_path/_uri");
         return EXIT_OK;
     }
     const source = values.file
@@ -153,8 +156,8 @@ async function runOqx(cli, args) {
  * Render an `OqxResult` in the current mode (shared with `run`). `--json` is the
  * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
  * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
- * `--ids` the hit ids — a scalar result has neither, so those modes print the
- * document, and so does a `bare` result (its hits carry no envelope). The
+ * `--ids` the hits' `_id`s — a scalar result has neither, so those modes print
+ * the document, and so does a `bare` result (its hits carry no envelope). The
  * truncation footer prints in every mode but `--json`.
  */
 export function renderOqxResult(cli, result, bare = false) {
@@ -163,7 +166,7 @@ export function renderOqxResult(cli, result, bare = false) {
         const list = result.values ?? (result.consumer === "collect" || result.consumer === "first" || result.consumer === "single" ? result.hits : undefined);
         return emitMachine(cli, result, {
             ...(list ? { items: list } : {}),
-            ...(list && !result.values && !bare ? { ids: result.hits.map((h) => h.id) } : {}),
+            ...(list && !result.values && !bare ? { ids: result.hits.map((h) => h._id) } : {}),
             cursor,
         });
     }

package/dist/src/cmd/outline.js

@@ -32,8 +32,8 @@ async function runOutline(cli, args) {
     let result;
     let header;
     if (cli.flags.server) {
-        // Remote: the docs_outline tool resolves the locator (`id` for a `d_` id,
-        // else `path`) + returns the same OutlineResult. The header shows the ref you passed (no local path lookup):
+        // Remote: the docs_outline tool resolves the locator (`_id` for a `d_` id,
+        // else `_path` — spec/surface §4 "Arguments", 5.0) + returns the same OutlineResult. The header shows the ref you passed (no local path lookup):
         // a path ref rooted (spec/surface §1 "Paths"), a `d_` id verbatim.
         result = await remoteCall(cli, "docs_outline", {
             ...docLocator(ref),

package/dist/src/cmd/retarget.js

@@ -70,7 +70,7 @@ function renderHits(cli, from, to, hits) {
     }
     io.err(style.dim(`  plan — ${hits.length} block(s) would change; re-run with --apply to commit`));
     for (const h of hits) {
-        io.out(style.id(h.id));
+        io.out(style.id(h._id));
         for (const line of unifiedDiffLines(cli, h.oldRaw, h.newRaw))
             io.out(line);
         io.out("");

package/dist/src/cmd/run.js

@@ -99,8 +99,8 @@ async function runRun(cli, args) {
     else {
         result = oqxRun(ws.store, repo.repoId, source);
     }
-    // Same renderer as `omg query`, in every mode: `<id>  <path>` lines, or a
-    // column table when the fence projects (a selected `text` shows as its first line).
+    // Same renderer as `omg query`, in every mode: `<_id>  <_path>` lines, or a
+    // column table when the fence projects (a selected `_text` shows as its first line).
     return renderOqxResult(cli, result);
 }
 export const cmdRun = { name: "run", summary: "Evaluate an ```omg fence (OQX, inert, read-only)", run: (c, a) => runRun(c, a) };

package/dist/src/cmd/show.js

@@ -15,14 +15,14 @@ function showOne(cli, ref, include) {
         if (!res)
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
         const links = docLinks(ws.store, resolved.docId, { direction: "both" });
-        // The authored keys, merged (frontmatter + inline — the `data` view); the
-        // computed rows are rendered under their surface names (`title`/`tags`,
-        // spec/surface §1.2 — the store's `$title`/`$tags` keys never reach the
+        // The authored keys, merged (frontmatter + inline — the `_data` view); the
+        // computed rows are rendered under their surface names (`_title`/`_tags`,
+        // spec/surface §1.2, 5.0 — the store's `$title`/`$tags` keys never reach the
         // terminal) from the re-keyed `properties.computed` the read carries.
         const properties = Object.fromEntries(Object.entries(docPropertiesMerged(ws.store.db, resolved.docId)).filter(([k]) => !k.startsWith("$")));
         const computed = res.properties.computed ?? {};
         const payload = { kind: "document", ...res };
-        return { payload, render: () => renderDocCard(cli, res.path, properties, computed, links) };
+        return { payload, render: () => renderDocCard(cli, res._path, properties, computed, links) };
     }
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution: "full" });
     if (!node)
@@ -74,8 +74,8 @@ function renderDocCard(cli, path, fm, computed, links) {
         for (const k of keys)
             io.out(`    ${style.accent(k)} ${style.dim("=")} ${fmt(fm[k])}`);
     }
-    // The computed rows under their surface names (`title`, `tags` — spec/surface
-    // §1.2), their own section so a computed title never masquerades as authored.
+    // The computed rows under their surface names (`_title`, `_tags` — spec/surface
+    // §1.2, 5.0), their own section so a computed title never masquerades as authored.
     const computedKeys = Object.keys(computed);
     if (computedKeys.length > 0) {
         io.out(`  ${style.dim("computed")}`);
@@ -85,28 +85,28 @@ function renderDocCard(cli, path, fm, computed, links) {
     if (links.out.length > 0) {
         io.out(`  ${style.dim("out links")}`);
         for (const e of links.out)
-            io.out(`    ${style.accent(e.predicate)} ${style.dim(render.g.arrow)} ${style.id(e.doc_id)} ${style.dim(`×${e.count}`)}`);
+            io.out(`    ${style.accent(e._predicate)} ${style.dim(render.g.arrow)} ${style.id(e._doc_id)} ${style.dim(`×${e.count}`)}`);
     }
     if (links.in.length > 0) {
         io.out(`  ${style.dim("backlinks")}`);
         for (const e of links.in)
-            io.out(`    ${style.id(e.doc_id)} ${style.dim(render.g.arrow)} ${style.accent(e.predicate)} ${style.dim(`×${e.count}`)}`);
+            io.out(`    ${style.id(e._doc_id)} ${style.dim(render.g.arrow)} ${style.accent(e._predicate)} ${style.dim(`×${e.count}`)}`);
     }
 }
 function renderBlockCard(cli, node, history) {
     const { render, style, io } = cli;
-    io.out(`  ${render.typeGlyph(node.type)} ${style.bold(node.type)}  ${style.id(node.id)}`);
+    io.out(`  ${render.typeGlyph(node._type)} ${style.bold(node._type)}  ${style.id(node._id)}`);
     io.out(render.rule(40));
-    // The placement is flattened onto the row (3.0: `parent_id`/`ordinal`/`depth`); the line reads the same.
-    if (node.ordinal !== undefined)
-        io.out(`  ${style.dim("placement")}  parent=${style.id(node.parent_id ?? "—")} ordinal=${node.ordinal} depth=${node.depth}`);
-    if (node.attrs && Object.keys(node.attrs).length > 0) {
+    // The placement is flattened onto the row (5.0: `parent_id`/`_ordinal`/`_depth`); the line reads the same.
+    if (node._ordinal !== undefined)
+        io.out(`  ${style.dim("placement")}  parent=${style.id(node.parent_id ?? "—")} ordinal=${node._ordinal} depth=${node._depth}`);
+    if (node._attrs && Object.keys(node._attrs).length > 0) {
         io.out(`  ${style.dim("attrs")}`);
-        for (const [k, v] of Object.entries(node.attrs))
+        for (const [k, v] of Object.entries(node._attrs))
             io.out(`    ${style.accent(k)} ${style.dim("=")} ${fmt(v)}`);
     }
-    if (node.text)
-        io.out(`  ${style.dim("text")}  ${node.text}`);
+    if (node._text)
+        io.out(`  ${style.dim("text")}  ${node._text}`);
     if (history && history.length > 0) {
         io.out(`  ${style.dim("history")}`);
         for (const h of history)

package/dist/src/cmd/update.js

@@ -71,7 +71,7 @@ async function runDocUpdate(cli, args) {
         const repo = cli.repo(ws);
         if (!repo.rootPath)
             throw new CliUsageError(`repo '${repo.slug}' has no filesystem source; 'update' needs a working tree`);
-        const effects = [{ op: "set", target: { kind: "document", id: requireDoc(ws.store, repo.repoId, doc) }, field: "content", value: bytes }];
+        const effects = [{ op: "set", target: { kind: "document", _id: requireDoc(ws.store, repo.repoId, doc) }, field: "content", value: bytes }];
         const req = {
             repoId: repo.repoId,
             rootPath: repo.rootPath,
@@ -93,11 +93,12 @@ async function runDocUpdate(cli, args) {
         return EXIT_OK;
     }
     if (receipt === undefined) {
-        // The plan: its one effect names the document; `preview.identity[<id>]` is
-        // the opset plan (one line per op, an empty line, the summary).
+        // The plan: its one effect names the document (a resolved target carries
+        // `_id` and `_path`, spec/mutate §11); `preview.identity[<id>]` is the opset
+        // plan (one line per op, an empty line, the summary).
         const target = plan.effects[0] && "target" in plan.effects[0] ? plan.effects[0].target : undefined;
-        const docId = target && target.kind === "document" ? target.id : undefined;
-        const path = target && target.kind === "document" ? referencePath(target.path) : doc;
+        const docId = target && target.kind === "document" ? target._id : undefined;
+        const path = target && target.kind === "document" ? referencePath(target._path) : doc;
         const identity = docId !== undefined ? plan.preview?.identity?.[docId] : undefined;
         cli.io.err(cli.style.dim(`  plan for ${cli.style.accent(path)}`));
         if (identity)

package/dist/src/output.d.ts

@@ -83,8 +83,8 @@ interface MachineIO {
 /** Print `doc` in the current machine mode (`--json`/`--jsonl`/`--ids`); returns EXIT_OK. */
 export declare function emitMachine(cli: MachineIO, doc: unknown, shape?: MachineShape): number;
 export interface HitLike {
-    id: string;
-    path: string;
+    _id: string;
+    _path: string;
     [k: string]: unknown;
 }
 export declare const HIT_CELL_MAX = 60;
@@ -93,19 +93,19 @@ export declare function truncateCell(s: string, max?: number): string;
 /** Render one projected value as a table cell (unstyled). */
 export declare function hitCell(v: unknown): string;
 /** The projected column names across `hits`: every key but the envelope's
- *  `id`/`path` (spec/surface §1.4, 3.0 — a `path` projection collapses onto
+ *  `_id`/`_path` (spec/surface §1.4, 5.0 — a `_path` projection collapses onto
  *  the envelope key, so it is never a column), in first-seen order. Empty when
  *  nothing was projected. */
 export declare function hitColumns(hits: HitLike[]): string[];
-/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected
- *  (header `id`, `path`, then the projected keys — spec/cli §4, 3.0). */
+/** Human-tier hit list: `<_id>  <_path>` lines, or an aligned table when projected
+ *  (header `_id`, `_path`, then the projected keys — spec/cli §4, 5.0). */
 export declare function renderHits(cli: {
     io: IO;
     style: Style;
 }, hits: HitLike[]): void;
 /** The bare hit table (`query --bare`, spec/cli §4, 4.1): a hit is its
  *  projection alone (`spec/surface` §1.4, 4.2), so the columns are every key in
- *  first-seen order across the hits — a projected `id`/`path` is an ordinary
+ *  first-seen order across the hits — a projected `_id`/`_path` is an ordinary
  *  column, rendered as any other cell — with no envelope columns before them.
  *  Header row, then one row per hit; cells as the enveloped table's. */
 export declare function renderBareHits(cli: {

package/dist/src/output.js

@@ -191,12 +191,12 @@ export function hitCell(v) {
     return truncateCell(JSON.stringify(v) ?? String(v));
 }
 /** The projected column names across `hits`: every key but the envelope's
- *  `id`/`path` (spec/surface §1.4, 3.0 — a `path` projection collapses onto
+ *  `_id`/`_path` (spec/surface §1.4, 5.0 — a `_path` projection collapses onto
  *  the envelope key, so it is never a column), in first-seen order. Empty when
  *  nothing was projected. */
 export function hitColumns(hits) {
     const cols = [];
-    const seen = new Set(["id", "path"]);
+    const seen = new Set(["_id", "_path"]);
     for (const h of hits) {
         for (const k of Object.keys(h)) {
             if (seen.has(k))
@@ -207,24 +207,24 @@ export function hitColumns(hits) {
     }
     return cols;
 }
-/** Human-tier hit list: `<id>  <path>` lines, or an aligned table when projected
- *  (header `id`, `path`, then the projected keys — spec/cli §4, 3.0). */
+/** Human-tier hit list: `<_id>  <_path>` lines, or an aligned table when projected
+ *  (header `_id`, `_path`, then the projected keys — spec/cli §4, 5.0). */
 export function renderHits(cli, hits) {
     const { io, style } = cli;
     const projected = hitColumns(hits);
     if (projected.length === 0) {
         for (const h of hits)
-            io.out(`${style.id(h.id)}  ${style.accent(h.path)}`.trimEnd());
+            io.out(`${style.id(h._id)}  ${style.accent(h._path)}`.trimEnd());
         return;
     }
-    const cols = ["id", "path", ...projected];
+    const cols = ["_id", "_path", ...projected];
     const rows = [cols.map((c) => style.dim(c))];
     for (const h of hits) {
         rows.push(cols.map((c) => {
-            if (c === "id")
-                return style.id(h.id);
-            if (c === "path")
-                return style.accent(h.path);
+            if (c === "_id")
+                return style.id(h._id);
+            if (c === "_path")
+                return style.accent(h._path);
             return hitCell(h[c]);
         }));
     }
@@ -233,7 +233,7 @@ export function renderHits(cli, hits) {
 }
 /** The bare hit table (`query --bare`, spec/cli §4, 4.1): a hit is its
  *  projection alone (`spec/surface` §1.4, 4.2), so the columns are every key in
- *  first-seen order across the hits — a projected `id`/`path` is an ordinary
+ *  first-seen order across the hits — a projected `_id`/`_path` is an ordinary
  *  column, rendered as any other cell — with no envelope columns before them.
  *  Header row, then one row per hit; cells as the enveloped table's. */
 export function renderBareHits(cli, hits) {

package/dist/src/shell/refs.js

@@ -10,9 +10,9 @@
 // signal to use OQX instead.
 export class RefError extends Error {
 }
-// `.field` reads any projected key (`@1.id`, `@t[1].path`, `@1.layer` —
-// spec/surface §1.4, 3.0 spells the envelope as the bare attributes); a leading
-// `$` is admitted for an OQX-named projection (`$depth`).
+// `.field` reads any projected key (`@1._id`, `@t[1]._path`, `@1.layer` —
+// spec/surface §1.2, 5.0: an engine field is `_`-prefixed, a bare name is an
+// authored key); a leading `$` is admitted for an OQX-named projection (`$depth`).
 const REF_RE = /^@(\d+|_|[A-Za-z][\w-]*)(?:\[(\d+)\])?(?:\.(\$?[A-Za-z_]\w*))?$/;
 /** Parse a whole-token reference; null if the token isn't a reference. */
 export function parseRef(token) {
@@ -48,7 +48,7 @@ export function deriveRows(value) {
             return o.ids.filter((id) => typeof id === "string").map((id) => ({ ref: id, label: id, value: id }));
         }
         if (Array.isArray(o.in) || Array.isArray(o.out)) {
-            // links: both directions, each edge's far node is the selectable ref.
+            // links: both directions, each edge's far node (`_doc_id`) is the selectable ref.
             const edges = [...(o.out ?? []), ...(o.in ?? [])];
             return edges.map(rowOf);
         }
@@ -61,19 +61,24 @@ function rowOf(el) {
     if (el && typeof el === "object") {
         const o = el;
         const ref = firstString(o, REF_KEYS);
-        const label = firstString(o, ["path", "locator", "name", "id", "node", "doc_id"]) ?? ref ?? preview(o);
+        const label = firstString(o, LABEL_KEYS) ?? ref ?? preview(o);
         return { ref: ref ?? label ?? "", label: label ?? "", value: el };
     }
     const s = String(el);
     return { ref: s, label: s, value: el };
 }
 // The keys that make an object an entity ref, in precedence order: a row's
-// `id` (spec/surface §1.2, 3.0 — every tool result spells a row's identity as
-// the attribute; a 2.x server's `id` is the same key), a `links` row's far node
-// (`doc_id`) and an edge's `block_id`, then the pre-3.0 envelopes (`node`,
-// `block`) — kept so a remote 2.x server's results still address — then
-// `locator` and a path.
-const REF_KEYS = ["id", "doc_id", "block_id", "node", "block", "locator", "path"];
+// `_id` (spec/surface §1.2, 5.0 — every tool result spells a row's identity as
+// the engine attribute, `_`-prefixed), a `links` row's far node (`_doc_id`) and
+// an edge's `_block_id`, then the role names `node` and `block` (a `node props`
+// card's `node`; a role key that names a block), then `locator` and the
+// document's `_path`. The
+// bare `id`/`path` (4.x) and `$id`/`$path` tolerance is gone (spec/cli 5.0): a
+// bare key is an authored property, never the row's identity.
+const REF_KEYS = ["_id", "_doc_id", "_block_id", "node", "block", "locator", "_path"];
+// The human label of a row, in precedence order: its `_path`, a `locator`, a
+// `name` (a repo, a source), then the id-like keys.
+const LABEL_KEYS = ["_path", "locator", "name", "_id", "node", "_doc_id"];
 function firstString(o, keys) {
     for (const k of keys)
         if (typeof o[k] === "string")
@@ -107,7 +112,7 @@ export function coerce(value) {
         // A collection-shaped result object (e.g. {hits:[…]}) can't be one arg.
         if (deriveRows(value))
             throw new RefError("reference is a collection; select one with [i]");
-        throw new RefError("reference has no id/locator to use as an argument");
+        throw new RefError("reference has no _id/locator to use as an argument");
     }
     throw new RefError("reference is not usable as an argument");
 }

package/dist/src/shell/session.js

@@ -141,7 +141,7 @@ export class ShellSession {
         line(style.dim("run any omg command; results become addressable:"));
         line(`${style.accent("@1 @2 …")}   ${style.dim("rows of the last displayed collection")}`);
         line(`${style.accent("@_")}         ${style.dim("the previous command's result")}`);
-        line(`${style.accent("@name")}      ${style.dim("a named binding (also @name[i], @name.field)")}`);
+        line(`${style.accent("@name")}      ${style.dim("a named binding (also @name[i], @name.field — e.g. @1._id, @t[1]._path)")}`);
         io.out("");
         line(`${style.accent("@x = <cmd|@ref>")}      ${style.dim("bind a snapshot of a result")}`);
         line(`${style.accent("unset x")}              ${style.dim("drop a binding")}`);
@@ -295,7 +295,7 @@ export class ShellSession {
             return String(v);
         if (v && typeof v === "object") {
             const o = v;
-            const id = o.id ?? o.id ?? o.node ?? o.path ?? o.path ?? o.locator; // a query hit leads with id/path (surface 3.0)
+            const id = o._id ?? o.node ?? o._path ?? o.locator; // a query hit leads with _id/_path (surface 5.0: engine names are `_`-prefixed)
             return id ? String(id) : "record";
         }
         return "empty";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.28.0",
+    "@omgbase/core": "^0.29.1",
     "@omgbase/fs-adapter": "^0.2.0",
-    "@omgbase/sync": "^0.6.0",
+    "@omgbase/sync": "^0.6.2",
     "yaml": "^2.9.0"
   },
   "devDependencies": {