@omgbase/core 0.28.0 → 0.29.0

package/dist/src/oqx-js/names.d.ts

@@ -1,12 +1,14 @@
 import type { Query, ReferenceStep } from "@omgbase/oqx";
 import { type Kind } from "./context.js";
 import type { Store } from "../core/store/store.js";
-/** What to do with a tier-3 name on an open kind: record it in `hints` (every read) or refuse the query (a write selector). */
+/** What to do with an unknown bare name on an open kind: record it in `hints` (every read) or refuse the query (a write selector). */
 export type UnknownNames = "hint" | "refuse";
 /** The relations of each kind and the kind of the rows they yield (spec/surface §1.2). */
 export declare const RELATIONS: Readonly<Record<Kind, Readonly<Record<string, Kind>>>>;
-/** The self and reach-through handles of each kind and the kind of the row they reach (§1.2). */
+/** The reach-through handles of each kind and the kind of the row they reach (§1.2; the self aliases are gone in 5.0 — `$it` is the self). */
 export declare const HANDLES: Readonly<Record<Kind, Readonly<Record<string, Kind>>>>;
+/** Every engine name of a kind, in the §1.2 table's order: attributes, reach-throughs, source handles (docs), relations. */
+export declare function engineNames(target: Kind): string[];
 /** The vocabulary of a kind in a repository (cached on the head commit; the SQL runs only when a name is not intrinsic). */
 export declare function vocabulary(store: Store, repoId: string, target: Kind): {
     present: boolean;
@@ -17,24 +19,33 @@ export declare function kindOfScope(steps: readonly ReferenceStep[]): Kind | nul
 /** Optimal string alignment distance (Damerau–Levenshtein with adjacent transpositions, each edit 1). */
 export declare function editDistance(a: string, b: string): number;
 /**
- * The nearest match of `name` among `candidates` (§1.5): case-insensitive; a
- * candidate qualifies when its distance is ≤ 2, or when one of the two is a
- * substring of the other and the shorter has at least three characters; the
- * lowest distance wins, ties broken by the shorter candidate, then
- * alphabetically. Null when nothing qualifies.
+ * The nearest match of `name` among `candidates` (§1.5). First, the one hint
+ * the name rule makes certain: a candidate that is exactly `name` with the
+ * engine prefix added or removed (`id` → `_id`, `_layer` → `layer`) wins
+ * outright, whatever its length. Otherwise case-insensitive and **prefix-blind**
+ * — the `_` is a declaration, not spelling, so `commited` is one edit from
+ * `_commit` and `titel` one from `_title` as from `title`: a candidate
+ * qualifies when its distance is ≤ 2, or when one of the two is a substring of
+ * the other and the shorter has at least three characters; the lowest distance
+ * wins, ties broken by the shorter candidate (so the bare authored `title`
+ * beats `_title` when both are one edit away), then alphabetically. Null when
+ * nothing qualifies.
  */
 export declare function nearest(name: string, candidates: readonly string[]): string | null;
-/** The error of a closed kind: `` `target` is not a field of links (fields: id, path, …); did you mean `…`? ``. */
-export declare function fieldErrorMessage(store: Store, repoId: string, target: Kind, name: string): string;
-/** The hint of an open kind: `` `preview` is not a field of blocks and no block in this repository carries a property by that name; did you mean `…`? ``.
- * Under a source handle the name is an authored lookup by construction, so the
- * hint says only that: `` no document in this repository carries a property `path` (`data.path`); did you mean `…`? ``,
- * the nearest match drawn from the authored keys alone. */
+/** The error of an unknown engine name: `` `_target` is not an engine name of links (engine names: _id, _path, …); did you mean `_dst_path`? ``
+ * — the nearest match drawn from the engine names and the authored keys, so a `_layer` written for the authored `layer` is pointed at it. */
+export declare function engineNameErrorMessage(store: Store, repoId: string, target: Kind, name: string): string;
+/** The error of a bare name on a closed kind: `` `target` reads an authored property, and a link carries none (engine names: _id, _path, …); did you mean `_dst_path`? ``. */
+export declare function closedKindErrorMessage(target: Kind, name: string, handle?: string): string;
+/** The hint of an open kind: `` no block in this repository carries a property `preview`; did you mean `_text`? ``.
+ * Under a source handle the name is shown with it — `` no document in this repository carries a property `x` (`_data.x`); did you mean `y`? `` —
+ * and the nearest match is drawn from the authored keys alone. */
 export declare function propertyHintMessage(store: Store, repoId: string, target: Kind, name: string, handle?: string): string;
 /**
- * Judge every name the query reads. Returns the hints (one per offending name
- * of an open kind, first-reference order, deduplicated) under `"hint"`; throws
- * `FilterInvalid` for a tier-3 name on a closed kind in either mode, and for
- * one on an open kind under `"refuse"`.
+ * Judge every name the query reads. Returns the hints (one per unknown bare
+ * name of an open kind, first-reference order, deduplicated) under `"hint"`;
+ * throws `FilterInvalid` for an unknown engine name (`_x`) and for a bare name
+ * on a closed kind in either mode, and for an unknown bare name on an open kind
+ * under `"refuse"`.
  */
 export declare function checkNames(store: Store, repoId: string, raw: Query, mode: UnknownNames): string[];

package/dist/src/oqx-js/names.js

@@ -1,52 +1,63 @@
-// Unknown names (spec/surface §1.5, 4.6). A query that projects, filters or
-// orders by a name no row of the scope's kind can carry — `select path, target
-// from links` (links have `dst_path`), `where preview != ""` on blocks — used
-// to run silently: an absent column in every row, a predicate true or false of
-// every row. This pass judges every name the query reads (`@omgbase/oqx`'s
-// `references`, AST.md §5b) against the VOCABULARY of the row kind it is read
-// from, statically — before any row is read, so the verdict never depends on
-// the query's own filter — and either records a hint or refuses the query.
+// Unknown names (spec/surface §1.5, 4.6; simplified in 5.0). A query that
+// projects, filters or orders by a name no row of the scope's kind can carry —
+// `select _path, target from links` (links have `_dst_path`), `where preview !=
+// ""` on blocks — used to run silently: an absent column in every row, a
+// predicate true or false of every row. This pass judges every name the query
+// reads (`@omgbase/oqx`'s `references`, AST.md §5b) against the row kind it is
+// read from, statically — before any row is read, so the verdict never depends
+// on the query's own filter — and either records a hint or refuses the query.
 //
-// The three tiers of a name at a scope whose kind is known:
-//   1. an engine attribute, handle or relation of the kind — known;
-//   2. an authored property at least one live object of the kind in this
-//      repository carries (docs: a frontmatter or inline key — `stage` on three
-//      processes is enough; blocks and nodes: a key of a live row's `attrs`,
-//      the bare-name read of those kinds) — known, however partial;
-//   3. a name no object of the kind carries — the complaint.
-// Severity: `links` has a closed row shape (no authored data reaches a link
-// row), so a tier-3 name there is `filter_invalid`; docs, blocks and nodes are
-// open — on a read the result carries one hint per offending name and the rows
-// still come back; a write selector (the AST entry, `unknownNames: "refuse"`)
-// is refused, since a name no row carries would select every row. A repository
-// with no live object of the kind has no vocabulary: the check is skipped for
-// that kind. The vocabulary is read once per (repository, kind) and cached on
-// the repository's head commit (`MAX(commits.seq)`), the one thing every
-// property or attrs change moves.
+// The name rule (§1.2, 5.0) makes the judgement two-sided:
+//   • an UNDERSCORE-prefixed name is an engine name — an attribute, a
+//     reach-through, a source handle or a relation of the kind, a CLOSED set —
+//     so a `_x` that is none of them is `filter_invalid` naming the kind's
+//     engine names (the one loud error of this pass; both modes);
+//   • a BARE name is the author's — on a document a frontmatter or inline key,
+//     on a block or node a key of its `attrs` — and is judged against the
+//     VOCABULARY of the kind in this repository: a name at least one live object
+//     carries is known (however partial: `stage` on three processes out of
+//     twenty documents is the data model working); a name no object carries is
+//     the complaint — on a read the result carries one hint per offending name
+//     and the rows still come back; a write selector (the AST entry,
+//     `unknownNames: "refuse"`) is refused, since a name no row carries would
+//     select every row. The hint's nearest match is drawn from the authored keys
+//     AND the engine names, so the one hint worth keeping survives: a bare
+//     `title` / `id` / `path` / `tags` / `format` that spells an engine attribute
+//     without its prefix says "did you mean `_title`?". A `links` or `revisions`
+//     row carries no authored data at all, so a bare name there is
+//     `filter_invalid` either way (closed row shape). A repository with no live
+//     object of an open kind has no vocabulary: the check is skipped for that
+//     kind. The vocabulary is read once per (repository, kind) and cached on the
+//     repository's head commit (`MAX(commits.seq)`), the one thing every
+//     property or attrs change moves.
 import { references } from "@omgbase/oqx";
-import { ATTRIBUTES, SOURCE_HANDLES } from "./context.js";
+import { ATTRIBUTES, REACH_THROUGHS, SOURCE_HANDLES } from "./context.js";
 import { ROOTS } from "./root-row.js";
 import { FROM, guards } from "./sql/scan.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 /** The relations of each kind and the kind of the rows they yield (spec/surface §1.2). */
 export const RELATIONS = {
-    docs: { blocks: "blocks", nodes: "nodes", out_links: "links", in_links: "links", revisions: "revisions" },
-    blocks: { children: "blocks", nodes: "nodes", out_links: "links", section: "nodes" },
-    nodes: { blocks: "blocks", subsections: "nodes", children: "nodes" },
+    docs: { _blocks: "blocks", _nodes: "nodes", _out_links: "links", _in_links: "links", _revisions: "revisions" },
+    blocks: { _children: "blocks", _nodes: "nodes", _out_links: "links", _section: "nodes" },
+    nodes: { _blocks: "blocks", _subsections: "nodes", _children: "nodes" },
     links: {},
     revisions: {},
 };
-/** The self and reach-through handles of each kind and the kind of the row they reach (§1.2). */
+/** The reach-through handles of each kind and the kind of the row they reach (§1.2; the self aliases are gone in 5.0 — `$it` is the self). */
 export const HANDLES = {
-    docs: { doc: "docs" },
-    blocks: { block: "blocks", doc: "docs" },
-    nodes: { section: "nodes", doc: "docs", block: "blocks" },
-    links: { doc: "docs", dst: "docs", block: "blocks" },
-    revisions: { doc: "docs" },
+    docs: {},
+    blocks: { _doc: "docs" },
+    nodes: { _doc: "docs", _block: "blocks" },
+    links: { _doc: "docs", _dst: "docs", _block: "blocks" },
+    revisions: { _doc: "docs" },
 };
 /** The kinds whose row shape is closed: no authored data reaches a row by bare name. */
 const CLOSED = new Set(["links", "revisions"]);
 const NOUN = { docs: "document", blocks: "block", nodes: "node", links: "link", revisions: "revision" };
+/** Every engine name of a kind, in the §1.2 table's order: attributes, reach-throughs, source handles (docs), relations. */
+export function engineNames(target) {
+    return [...ATTRIBUTES[target], ...REACH_THROUGHS[target], ...(target === "docs" ? [...SOURCE_HANDLES] : []), ...Object.keys(RELATIONS[target])];
+}
 const CACHE = new WeakMap();
 function headSeq(store, repoId) {
     const row = store.db.prepare("SELECT COALESCE(MAX(seq), 0) AS seq FROM commits WHERE repo_id = ?").get(repoId);
@@ -65,7 +76,7 @@ function repoCache(store, repoId) {
 /** The authored vocabulary of a kind: docs — every live frontmatter or inline
  * key (the merged read a bare name performs); blocks and nodes — every key a
  * live row's `attrs` holds (the bare-name read of those kinds). Computed keys
- * (`$title`, `$tags`) are the intrinsics `title`/`tags`, not authored keys. */
+ * (`$title`, `$tags`) are the attributes `_title`/`_tags`, not authored keys. */
 function authoredKeys(store, repoId, target) {
     let sql;
     switch (target) {
@@ -150,7 +161,7 @@ function dotted(e) {
     const inner = dotted(e.recv);
     return inner === null ? null : { head: inner.head, rest: [...inner.rest, e.name] };
 }
-/** Follow a dotted path from a row kind through handles and relations (`doc.blocks` on a link → blocks). */
+/** Follow a dotted path from a row kind through reach-throughs and relations (`_doc._blocks` on a link → blocks). */
 function kindOfPath(on, path) {
     let cur = on;
     for (let i = 0; i < path.length; i++) {
@@ -216,15 +227,19 @@ export function kindOfScope(steps) {
 /** Judge a dotted name read on rows of `target`; null = known. */
 function judge(store, repoId, target, path) {
     const [head, ...rest] = path;
-    // An engine attribute wins on collision; what follows it (`attrs.checked`, `tags.size`) is the value's own navigation.
-    if (ATTRIBUTES[target].has(head))
-        return null;
-    // The source handles reach the authored data under them.
-    if (target === "docs" && SOURCE_HANDLES.has(head))
-        return rest.length === 0 ? null : judgeAuthored(store, repoId, "docs", rest, head);
-    const via = HANDLES[target][head] ?? RELATIONS[target][head];
-    if (via !== undefined)
-        return rest.length === 0 ? null : judge(store, repoId, via, rest);
+    if (head.startsWith("_")) {
+        // An engine attribute: what follows it (`_attrs.checked`, `_tags.size`) is the value's own navigation.
+        if (ATTRIBUTES[target].has(head))
+            return null;
+        // The source handles reach the authored data under them.
+        if (target === "docs" && SOURCE_HANDLES.has(head))
+            return rest.length === 0 ? null : judgeAuthored(store, repoId, "docs", rest, head);
+        const via = HANDLES[target][head] ?? RELATIONS[target][head];
+        if (via !== undefined)
+            return rest.length === 0 ? null : judge(store, repoId, via, rest);
+        // Not an engine name of this kind: the closed set is the whole set.
+        return { target, name: head, why: "engine" };
+    }
     // A bare target name on a row is the context's own loud error (root-row.ts); not doubled here.
     if (ROOTS.has(head))
         return null;
@@ -233,22 +248,15 @@ function judge(store, repoId, target, path) {
 function judgeAuthored(store, repoId, target, path, handle) {
     const name = path.join(".");
     if (CLOSED.has(target))
-        return { target, name, closed: true };
+        return { target, name, why: "closed", ...(handle !== undefined ? { handle } : {}) };
     const v = vocabularyOf(store, repoId, target);
     if (!v.present)
         return null; // no object of the kind: no vocabulary to judge by
     if (v.keys.has(name))
         return null;
-    return { target, name, closed: false, ...(handle !== undefined ? { handle } : {}) };
+    return { target, name, why: "authored", ...(handle !== undefined ? { handle } : {}) };
 }
 // ---- messages --------------------------------------------------------------
-/** The names a kind knows, for the nearest match: attributes, handles, relations, the authored keys. */
-function candidates(store, repoId, target) {
-    const out = [...ATTRIBUTES[target], ...Object.keys(HANDLES[target]), ...(target === "docs" ? [...SOURCE_HANDLES] : []), ...Object.keys(RELATIONS[target])];
-    if (!CLOSED.has(target))
-        out.push(...vocabularyOf(store, repoId, target).list);
-    return out;
-}
 /** Optimal string alignment distance (Damerau–Levenshtein with adjacent transpositions, each edit 1). */
 export function editDistance(a, b) {
     const s = Array.from(a), t = Array.from(b);
@@ -270,21 +278,35 @@ export function editDistance(a, b) {
     return d[m][n];
 }
 /**
- * The nearest match of `name` among `candidates` (§1.5): case-insensitive; a
- * candidate qualifies when its distance is ≤ 2, or when one of the two is a
- * substring of the other and the shorter has at least three characters; the
- * lowest distance wins, ties broken by the shorter candidate, then
- * alphabetically. Null when nothing qualifies.
+ * The nearest match of `name` among `candidates` (§1.5). First, the one hint
+ * the name rule makes certain: a candidate that is exactly `name` with the
+ * engine prefix added or removed (`id` → `_id`, `_layer` → `layer`) wins
+ * outright, whatever its length. Otherwise case-insensitive and **prefix-blind**
+ * — the `_` is a declaration, not spelling, so `commited` is one edit from
+ * `_commit` and `titel` one from `_title` as from `title`: a candidate
+ * qualifies when its distance is ≤ 2, or when one of the two is a substring of
+ * the other and the shorter has at least three characters; the lowest distance
+ * wins, ties broken by the shorter candidate (so the bare authored `title`
+ * beats `_title` when both are one edit away), then alphabetically. Null when
+ * nothing qualifies.
  */
 export function nearest(name, candidates) {
-    const needle = name.toLowerCase();
+    const lower = name.toLowerCase();
+    const prefixed = `_${lower}`;
+    const unprefixed = lower.startsWith("_") ? lower.slice(1) : null;
+    for (const c of candidates) {
+        const hay = c.toLowerCase();
+        if (hay === prefixed || (unprefixed !== null && hay === unprefixed))
+            return c;
+    }
+    const needle = lower.replace(/^_/, "");
     // A name under three characters is within distance 2 of nearly anything, so
     // only a substring match (which needs three characters anyway) could qualify.
     if (needle.length < 3)
         return null;
     let best = null;
     for (const c of new Set(candidates)) {
-        const hay = c.toLowerCase();
+        const hay = c.toLowerCase().replace(/^_/, "");
         if (hay === needle)
             continue;
         const d = editDistance(needle, hay);
@@ -294,9 +316,9 @@ export function nearest(name, candidates) {
         if (!(d <= 2 || sub))
             continue;
         // One typo (distance 1) wins first; then a substring match outranks a
-        // distance-2 match (`via` → `via_id`, not `id`; `dst_pth` → `dst_path`, not
-        // `dst`); within a class the lowest distance, then the shorter candidate,
-        // then alphabetical.
+        // distance-2 match (`_via` → `_via_id`, not `_id`; `_dst_pth` → `_dst_path`,
+        // not `_dst`); within a class the lowest distance, then the shorter
+        // candidate, then alphabetical.
         const rank = (x) => (x.d === 1 ? 0 : x.sub ? 1 : 2);
         const better = best === null ||
             rank({ d, sub }) < rank(best) ||
@@ -310,26 +332,39 @@ function suggestion(name, candidates) {
     const c = nearest(name, candidates);
     return c === null ? "" : `; did you mean \`${c}\`?`;
 }
-/** The error of a closed kind: `` `target` is not a field of links (fields: id, path, …); did you mean `…`? ``. */
-export function fieldErrorMessage(store, repoId, target, name) {
-    return `\`${name}\` is not a field of ${target} (fields: ${[...ATTRIBUTES[target]].join(", ")})${suggestion(name, candidates(store, repoId, target))}`;
+/** The candidates of a bare name: the kind's engine names (so `title` finds `_title`) and its authored keys. */
+function candidates(store, repoId, target) {
+    const out = engineNames(target);
+    if (!CLOSED.has(target))
+        out.push(...vocabularyOf(store, repoId, target).list);
+    return out;
+}
+/** The error of an unknown engine name: `` `_target` is not an engine name of links (engine names: _id, _path, …); did you mean `_dst_path`? ``
+ * — the nearest match drawn from the engine names and the authored keys, so a `_layer` written for the authored `layer` is pointed at it. */
+export function engineNameErrorMessage(store, repoId, target, name) {
+    return `\`${name}\` is not an engine name of ${target} (engine names: ${engineNames(target).join(", ")})${suggestion(name, candidates(store, repoId, target))}`;
+}
+/** The error of a bare name on a closed kind: `` `target` reads an authored property, and a link carries none (engine names: _id, _path, …); did you mean `_dst_path`? ``. */
+export function closedKindErrorMessage(target, name, handle) {
+    const shown = handle !== undefined ? ` (\`${handle}.${name}\`)` : "";
+    return `\`${name}\`${shown} reads an authored property, and a ${NOUN[target]} carries none (engine names: ${engineNames(target).join(", ")})${suggestion(name, engineNames(target))}`;
 }
-/** The hint of an open kind: `` `preview` is not a field of blocks and no block in this repository carries a property by that name; did you mean `…`? ``.
- * Under a source handle the name is an authored lookup by construction, so the
- * hint says only that: `` no document in this repository carries a property `path` (`data.path`); did you mean `…`? ``,
- * the nearest match drawn from the authored keys alone. */
+/** The hint of an open kind: `` no block in this repository carries a property `preview`; did you mean `_text`? ``.
+ * Under a source handle the name is shown with it — `` no document in this repository carries a property `x` (`_data.x`); did you mean `y`? `` —
+ * and the nearest match is drawn from the authored keys alone. */
 export function propertyHintMessage(store, repoId, target, name, handle) {
     if (handle !== undefined) {
         return `no ${NOUN[target]} in this repository carries a property \`${name}\` (\`${handle}.${name}\`)${suggestion(name, vocabularyOf(store, repoId, target).list)}`;
     }
-    return `\`${name}\` is not a field of ${target} and no ${NOUN[target]} in this repository carries a property by that name${suggestion(name, candidates(store, repoId, target))}`;
+    return `no ${NOUN[target]} in this repository carries a property \`${name}\`${suggestion(name, candidates(store, repoId, target))}`;
 }
 // ---- the pass --------------------------------------------------------------
 /**
- * Judge every name the query reads. Returns the hints (one per offending name
- * of an open kind, first-reference order, deduplicated) under `"hint"`; throws
- * `FilterInvalid` for a tier-3 name on a closed kind in either mode, and for
- * one on an open kind under `"refuse"`.
+ * Judge every name the query reads. Returns the hints (one per unknown bare
+ * name of an open kind, first-reference order, deduplicated) under `"hint"`;
+ * throws `FilterInvalid` for an unknown engine name (`_x`) and for a bare name
+ * on a closed kind in either mode, and for an unknown bare name on an open kind
+ * under `"refuse"`.
  */
 export function checkNames(store, repoId, raw, mode) {
     const hints = [];
@@ -343,8 +378,10 @@ export function checkNames(store, repoId, raw, mode) {
         const verdict = judge(store, repoId, kind, ref.name.split("."));
         if (verdict === null)
             continue;
-        if (verdict.closed)
-            throw new FilterInvalid(fieldErrorMessage(store, repoId, verdict.target, verdict.name), "OQX");
+        if (verdict.why === "engine")
+            throw new FilterInvalid(engineNameErrorMessage(store, repoId, verdict.target, verdict.name), "OQX");
+        if (verdict.why === "closed")
+            throw new FilterInvalid(closedKindErrorMessage(verdict.target, verdict.name, verdict.handle), "OQX");
         const message = propertyHintMessage(store, repoId, verdict.target, verdict.name, verdict.handle);
         if (mode === "refuse")
             throw new FilterInvalid(message, "OQX");

package/dist/src/oqx-js/planner.d.ts

@@ -12,15 +12,11 @@ export declare function rootTarget(source: Expr): Target | null;
  *   • any `call` node (a function or method: unknown name, bad regex, wrong target…)
  *   • any nested block whose consumer is `single` (raises on 0 or >1 rows)
  *   • any `^`-escaped name: an `outer` reference or a `^name:` lift
- *   • a bare reserved docs basename (`id path updated_at hash raw`): as
- *     an `ident` at the ROOT scope when the target is `docs`, or as `doc.<name>`
- *     on any target at any depth (the reach-through row is a doc)
  *   • a bare root name (`docs blocks nodes links revisions`, root-row.ts) read
- *     as a property: as an `ident` at the ROOT scope when it is not a relation
- *     of the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
- *     as an `ident` at any depth below (the rows there are unknown), or as
- *     `<head>.<name>` unless the head is a reach-through whose row has that
- *     relation (`doc.nodes`, `doc.blocks`, `block.nodes`, `section.blocks`)
+ *     as a property: as an `ident` at any depth (since 5.0 a bare root name is
+ *     never a relation — the relations are `_blocks`, `_nodes`, `_revisions`),
+ *     or as `<head>.<name>` (`_doc.blocks`, `_block.nodes`: the loud error of a
+ *     bare target name on the reached row)
  *
  * A residual made only of comparisons, logical operators, `in`/ranges, `!`,
  * literals, bindings and plain reads (including exists/none/count/collect/first

package/dist/src/oqx-js/planner.js

@@ -39,15 +39,11 @@ export function rootTarget(source) {
  *   • any `call` node (a function or method: unknown name, bad regex, wrong target…)
  *   • any nested block whose consumer is `single` (raises on 0 or >1 rows)
  *   • any `^`-escaped name: an `outer` reference or a `^name:` lift
- *   • a bare reserved docs basename (`id path updated_at hash raw`): as
- *     an `ident` at the ROOT scope when the target is `docs`, or as `doc.<name>`
- *     on any target at any depth (the reach-through row is a doc)
  *   • a bare root name (`docs blocks nodes links revisions`, root-row.ts) read
- *     as a property: as an `ident` at the ROOT scope when it is not a relation
- *     of the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
- *     as an `ident` at any depth below (the rows there are unknown), or as
- *     `<head>.<name>` unless the head is a reach-through whose row has that
- *     relation (`doc.nodes`, `doc.blocks`, `block.nodes`, `section.blocks`)
+ *     as a property: as an `ident` at any depth (since 5.0 a bare root name is
+ *     never a relation — the relations are `_blocks`, `_nodes`, `_revisions`),
+ *     or as `<head>.<name>` (`_doc.blocks`, `_block.nodes`: the loud error of a
+ *     bare target name on the reached row)
  *
  * A residual made only of comparisons, logical operators, `in`/ranges, `!`,
  * literals, bindings and plain reads (including exists/none/count/collect/first
@@ -70,8 +66,8 @@ function opMayRaise(op, target, root) {
         return true;
     return exprMayRaise(op.receiver, target, root) || subMayRaise(op.sub, target);
 }
-// Inside a block the rows are a different scope (a relation's rows), so a bare
-// reserved name is an ordinary read there — only `doc.<reserved>` still raises.
+// Inside a block the rows are a different scope (a relation's rows); `root` is
+// false there, so a bare root name raises whatever the target.
 function subMayRaise(s, target) {
     if (s.from.some((e) => exprMayRaise(e, target, false)))
         return true;

package/dist/src/oqx-js/root-row.d.ts

@@ -10,12 +10,13 @@ export declare const TARGETS: ReadonlySet<string>;
 /** The root collections, in the root object's entry order (§1.1). */
 export declare const ROOT_NAMES: readonly Root[];
 export declare const ROOTS: ReadonlySet<string>;
-/** The root names that are a relation of each kind's rows (§1.2): `revisions`
- * on a document is its revision list (4.7). */
+/** The root names, as relations of each kind's rows (§1.2, `_`-prefixed since
+ * 5.0): `_revisions` on a document is its revision list (4.7). A BARE root name
+ * on a row is never a relation (it is the loud error below). */
 export declare const TARGET_RELATIONS: Readonly<Record<Root, ReadonlySet<string>>>;
-/** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`, and a link's `dst.x`). */
+/** The reach-through heads and the target of the row they reach (`_doc.x`, `_block.x`, and a link's `_dst.x`; spec/surface §1.2, 5.0 — the self aliases are gone). */
 export declare const REACH_THROUGH: Readonly<Record<string, Target>>;
-export declare const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 \u2014 reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^id` / `0^id`";
+export declare const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 \u2014 reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^_id` / `0^_id`";
 /**
  * The bare-target error. `depth` is the scope depth the name was read at when
  * known statically (the carets in the hint count it); `null` when raised at read
@@ -35,5 +36,5 @@ export declare function pastRootMessage(name: string, levels: number): string;
  * target's name before 3.0, gets its new name spelled out.
  */
 export declare function unknownTargetMessage(name: string): string;
-/** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
+/** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target (`_blocks`, `_nodes`, `_revisions`). */
 export declare function isTargetRelationOf(target: Root | undefined, name: string): boolean;

package/dist/src/oqx-js/root-row.js

@@ -1,6 +1,6 @@
 // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18). The repository is OQX's
 // root row: from a top-level row `^docs` reaches the documents (one caret per
-// enclosing block, or the absolute `0^docs`), `^id` the repository id, and the
+// enclosing block, or the absolute `0^docs`), `^_id` the repository id, and the
 // root object (`^$it`) exposes the five collections (`revisions` since 4.7). Two spellings are refused
 // as `filter_invalid`, with the messages below, in both engines:
 //
@@ -10,12 +10,10 @@
 //     `checkRootSpellings`);
 //   • a bare target name at scope depth ≥ 1 (inside a block, or in a top-level
 //     row's clauses), where a bare name reads a property of the current row,
-//     which has none: `docs` and `links` are no row's relation, so they are
-//     refused statically by the same walk; `blocks`, `nodes` and `revisions`
-//     ARE relations of some rows (`docs.blocks`, `docs.nodes`, `blocks.nodes`,
-//     `section.blocks`, `docs.revisions`), so the context raises the same error
-//     at read time on a row that lacks the relation (context.ts). A frontmatter key named after a
-//     target is unreachable by bare name (use `frontmatter.<k>`).
+//     which has none — refused statically for every root name since 5.0 (the
+//     relations are `_blocks`, `_nodes`, `_revisions`: a bare `blocks` is never
+//     one), and by the context at read time should one reach it (context.ts). A frontmatter key named after a
+//     target is unreachable by bare name (use `_frontmatter.<k>`).
 /** The four row kinds whose names the unknown-names pass judges (names.ts keys
  * its vocabulary tables by them); `revisions` joins when that pass learns the
  * kind. Every OTHER root-collection test uses `ROOTS`. */
@@ -23,19 +21,20 @@ export const TARGETS = new Set(["docs", "blocks", "nodes", "links"]);
 /** The root collections, in the root object's entry order (§1.1). */
 export const ROOT_NAMES = ["docs", "blocks", "nodes", "links", "revisions"];
 export const ROOTS = new Set(ROOT_NAMES);
-/** The root names that are a relation of each kind's rows (§1.2): `revisions`
- * on a document is its revision list (4.7). */
+/** The root names, as relations of each kind's rows (§1.2, `_`-prefixed since
+ * 5.0): `_revisions` on a document is its revision list (4.7). A BARE root name
+ * on a row is never a relation (it is the loud error below). */
 export const TARGET_RELATIONS = {
-    docs: new Set(["nodes", "blocks", "revisions"]),
-    blocks: new Set(["nodes"]),
-    nodes: new Set(["blocks"]),
+    docs: new Set(["_nodes", "_blocks", "_revisions"]),
+    blocks: new Set(["_nodes"]),
+    nodes: new Set(["_blocks"]),
     links: new Set(),
     revisions: new Set(),
 };
-/** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`, and a link's `dst.x`). */
-export const REACH_THROUGH = { doc: "docs", block: "blocks", section: "nodes", dst: "docs" };
+/** The reach-through heads and the target of the row they reach (`_doc.x`, `_block.x`, and a link's `_dst.x`; spec/surface §1.2, 5.0 — the self aliases are gone). */
+export const REACH_THROUGH = { _doc: "docs", _block: "blocks", _dst: "docs" };
 const NOUN = { docs: "documents", blocks: "blocks", nodes: "nodes", links: "links", revisions: "revisions" };
-export const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 — reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^id` / `0^id`";
+export const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 — reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^_id` / `0^_id`";
 /**
  * The bare-target error. `depth` is the scope depth the name was read at when
  * known statically (the carets in the hint count it); `null` when raised at read
@@ -66,7 +65,7 @@ export function unknownTargetMessage(name) {
     const was = name === "edges" ? " (`edges` was renamed `links` in surface 3.0)" : "";
     return `\`${name}\` is not a target — the repository's collections are ${ROOT_NAMES.map((r) => `\`${r}\``).join(", ")}${was}`;
 }
-/** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
+/** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target (`_blocks`, `_nodes`, `_revisions`). */
 export function isTargetRelationOf(target, name) {
     return target !== undefined && TARGET_RELATIONS[target].has(name);
 }

package/dist/src/oqx-js/run.d.ts

@@ -8,20 +8,20 @@ export type EmbedQuery = (text: string) => Promise<{
     model: string;
     vec: Float32Array;
 }>;
-/** A query hit (spec/surface §1.4, 3.0): the row's identity under the SAME
- * bare names the expression language reads — `id`, `path` — plus whatever
+/** A query hit (spec/surface §1.4, 5.0): the row's identity under the SAME
+ * engine names the expression language reads — `_id`, `_path` — plus whatever
  * `select` projected. A key copied from a hit is valid in the next `where` with
- * no translation (`where id == "<hit.id>"`); a `select id, path` is simply the
- * envelope, and any other projection whose output key would be `id` or `path`
- * must be aliased (`envelopeCollision`). */
+ * no translation (`where _id == "<hit._id>"`); a `select _id, _path` is simply
+ * the envelope, and any other projection whose output key would be `_id` or
+ * `_path` must be aliased (`envelopeCollision`). */
 export interface OqxHit {
-    id: string;
-    path: string;
+    _id: string;
+    _path: string;
     [k: string]: unknown;
 }
 export interface OqxResult {
-    /** `{ id, path, ...projection }` per hit — or, under `OqxOptions.bare`, the
-     * projection alone (`id`/`path` present only when the query projected them;
+    /** `{ _id, _path, ...projection }` per hit — or, under `OqxOptions.bare`, the
+     * projection alone (`_id`/`_path` present only when the query projected them;
      * typed as `OqxHit` for the one hit shape every consumer handles, a bare
      * caller knows it asked). */
     hits: OqxHit[];
@@ -47,16 +47,17 @@ export interface OqxResult {
 export interface OqxOptions {
     limit?: number;
     cursor?: string | null;
-    /** Return each hit as its PROJECTION only — no automatic `id`/`path`
-     * members (spec/surface §1.4, 4.2): `select title, era from docs` yields
-     * `{ title, era }` rows. Needs a `select` (without a projection a hit is
+    /** Return each hit as its PROJECTION only — no automatic `_id`/`_path`
+     * members (spec/surface §1.4, 4.2): `select _title, era from docs` yields
+     * `{ _title, era }` rows. Needs a `select` (without a projection a hit is
      * only its envelope) and is refused with `values` (already the bare-values
      * form); both are `filter_invalid` before the engine runs. A projected
-     * `id`/`path` is the intrinsic as everywhere (`select id` → `{ id }`), and
-     * with no envelope there is nothing to collide with (`select path: layer`
-     * is fine). Paging, `distinct`, `truncated` and `cursor` are unchanged —
-     * the runner keeps identity internally and strips the envelope last. The
-     * scalar consumers (`count`/`exists`/`none`) have no hits and ignore it. */
+     * `_id`/`_path` is the attribute as everywhere (`select _id` → `{ _id }`),
+     * and with no envelope there is nothing to collide with (`select _path:
+     * layer` is fine). Paging, `distinct`, `truncated` and `cursor` are
+     * unchanged — the runner keeps identity internally and strips the envelope
+     * last. The scalar consumers (`count`/`exists`/`none`) have no hits and
+     * ignore it. */
     bare?: boolean;
     semanticVectors?: Map<string, SemanticVec>;
     /** Force the pure in-memory engine (skip tier-3 pushdown). Internal — used by