@omgbase/core 0.7.1 → 0.10.0

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

@@ -12,15 +12,19 @@
 // the corpus and the differential baseline. The tier-3 SQLite planner (planner.ts)
 // pushes the hot predicates down; both must agree (conformance suite).
 import { semantics } from "@omgbase/oqx";
+import { storeIndexFor } from "./store-index.js";
+import { TARGETS, bareTargetMessage } from "./root-row.js";
+import { COLS, FROM, ORDER, guards } from "./sql/scan.js";
 import { detectRange } from "../core/store/properties.js";
 import { docsRead } from "../core/read/document.js";
+import { referencePath, storagePath } from "../core/paths.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { sanitizeFtsQuery } from "../search/fts-query.js";
 import { cosineBytes } from "../core/vec.js";
 import { ctxHashHex } from "../search/embeddings.js";
 import { makeBlockContextResolver } from "../search/tasks.js";
 const TARGET = Symbol("oqx.target");
-const REPO_ROOT = Symbol("oqx.repoRoot");
+const ROOT_ROW = Symbol("oqx.rootRow");
 const PROP_SOURCE = Symbol("oqx.propSource");
 function tag(row, t) {
     if (!row)
@@ -34,9 +38,9 @@ function tagAll(rows, t) {
     return rows;
 }
 // docs intrinsics whose BARE (non-$) form is almost always a typo (10 §2); a bare
-// read of one is a loud error, matching the CEL guard.
-// (The root-scan receiver is the `$repo` intrinsic — `$repo.docs`/`$repo.nodes`/… —
-// so a bare `repo` is just an ordinary frontmatter key.)
+// read of one is a loud error, matching the CEL guard. (A bare target name —
+// `docs`, `edges`, … — is a loud error of its own, root-row.ts; `repo` is just an
+// ordinary frontmatter key.)
 const RESERVED_DOC_BASENAMES = new Set(["id", "path", "updated_at", "content_hash", "body"]);
 export function makeStoreContext(store, repoId, opts = {}) {
     const db = store.db;
@@ -49,20 +53,73 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return undefined;
         return Object.values(r)[0];
     };
-    // ---- root collections (ordered for a stable (path, id) default) -----------
-    const docsRoot = () => tagAll(all(`SELECT * FROM docs WHERE repo_id = ? AND deleted_commit IS NULL ORDER BY path, doc_id`, repoId), "docs");
-    const blocksRoot = () => tagAll(all(`SELECT b.*, d.path AS __path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id
-       WHERE b.repo_id = ? AND b.deleted_commit IS NULL AND d.deleted_commit IS NULL
-       ORDER BY d.path, b.block_id`, repoId), "blocks");
-    const nodesRoot = () => tagAll(all(`SELECT n.*, d.path AS __path FROM nodes n JOIN docs d ON d.doc_id = n.doc_id
-       WHERE n.repo_id = ? AND d.deleted_commit IS NULL ORDER BY d.path, n.node_id`, repoId), "nodes");
-    const edgesRoot = () => tagAll(all(`SELECT e.*, d.path AS __path FROM edges e JOIN docs d ON d.doc_id = e.src_doc
-       WHERE e.repo_id = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL
-       ORDER BY d.path, e.edge_id`, repoId), "edges");
-    const rootFns = { docs: docsRoot, blocks: blocksRoot, nodes: nodesRoot, edges: edgesRoot };
-    // The repository handle behind the `$repo` intrinsic: `$repo.<target>` is the
-    // explicit root scan (rootFns), `$repo.$id` the repository id.
-    const repoRoot = { [REPO_ROOT]: true };
+    // ---- root collections (the shared scan shape of sql/scan.ts: live rows of
+    // this repo, ordered for a stable (path, id) default) -----------------------
+    const scan = (t) => {
+        const g = guards(t, repoId);
+        return tagAll(all(`SELECT ${COLS[t]} FROM ${FROM[t]} WHERE ${g.sql} ORDER BY ${ORDER[t]}`, ...g.params), t);
+    };
+    // A root scan is handed out LAZILY: an array (a `Proxy` over one — `Array.isArray`,
+    // iteration, indexing, `length`, rendering all see a plain array of tagged
+    // rows) that runs its SELECT on first use. The engine's optimizer asks
+    // `indexFor` about a nested block's receiver BEFORE reading it, so a
+    // correlated probe on `^docs` / `^edges` / … is answered from the
+    // store's indexes (store-index.ts) and the scan never runs; anything else
+    // (a top-level `from docs`, a `count { }`, a non-indexable path) reads it
+    // whole exactly as before. One handle per target per context: a context lives
+    // for one run, during which the store does not change, so `^docs` read
+    // from every outer row is one SELECT, not one per row — and the engine, which
+    // keys collections by identity, sees the same collection each time.
+    // `rootScans` recognizes the handles for `indexFor`. Because the handle IS an
+    // array, this context needs no `DataContext.materialize` (the Rust port's
+    // marker value does); `spec/surface` `lazy-root-*` pins what the language
+    // sees either way.
+    const rootScans = new WeakMap();
+    const handles = new Map();
+    const lazyRoot = (t) => {
+        let h = handles.get(t);
+        if (!h)
+            handles.set(t, (h = makeLazyRoot(t)));
+        return h;
+    };
+    const makeLazyRoot = (t) => {
+        const backing = [];
+        let filled = false;
+        const fill = () => {
+            if (!filled) {
+                filled = true;
+                for (const r of scan(t))
+                    backing.push(r);
+            }
+            return backing;
+        };
+        const proxy = new Proxy(backing, {
+            get(target, prop, receiver) { fill(); return Reflect.get(target, prop, receiver); },
+            has(target, prop) { fill(); return Reflect.has(target, prop); },
+            ownKeys(target) { fill(); return Reflect.ownKeys(target); },
+            getOwnPropertyDescriptor(target, prop) { fill(); return Reflect.getOwnPropertyDescriptor(target, prop); },
+            set(target, prop, value, receiver) { fill(); return Reflect.set(target, prop, value, receiver); },
+            defineProperty(target, prop, desc) { fill(); return Reflect.defineProperty(target, prop, desc); },
+            deleteProperty(target, prop) { fill(); return Reflect.deleteProperty(target, prop); },
+        });
+        rootScans.set(proxy, { target: t, rows: fill });
+        return proxy;
+    };
+    const rootFns = {
+        docs: () => lazyRoot("docs"), blocks: () => lazyRoot("blocks"), nodes: () => lazyRoot("nodes"), edges: () => lazyRoot("edges"),
+    };
+    // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18 `rootObject`): the
+    // repository, reached as `^$it` from a top-level row (`0^$it` from any depth).
+    // Its own enumerable keys are the four collections — lazy getters, so
+    // `entries(^$it)` names them without running a scan and `^$it.docs` is the
+    // same handle as `^docs` — and `get` answers `$id` with the repository id (an
+    // intrinsic, not an entry). Tagged so `get` recognizes it.
+    const rootRow = Object.defineProperties({ [ROOT_ROW]: true }, {
+        docs: { enumerable: true, get: () => lazyRoot("docs") },
+        blocks: { enumerable: true, get: () => lazyRoot("blocks") },
+        nodes: { enumerable: true, get: () => lazyRoot("nodes") },
+        edges: { enumerable: true, get: () => lazyRoot("edges") },
+    });
     // ---- attrs / property decoding --------------------------------------------
     const parseJson = (v) => {
         if (typeof v !== "string")
@@ -270,6 +327,10 @@ export function makeStoreContext(store, repoId, opts = {}) {
         ? tag(one(`SELECT b.*, d.path AS __path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ?`, row.block_id), "blocks")
         : undefined;
     // ---- intrinsics ($-fields) ------------------------------------------------
+    // `$path` / `$dst_path` are the REFERENCE form (`/a/b.md`, spec/surface §1
+    // "Paths", 2.0): the rows carry the storage form (`path`, the `__path` join
+    // column) and the intrinsic roots it on read, so nothing below the binding
+    // changes. run.ts roots the string literals a query compares them with.
     const intrinsic = (row, t, name) => {
         // `$self` = the current row: run.ts rewrites row-scoped domain functions
         // (text/semantic/under_*/…) to `$self.fn(…)` so they arrive via callMethod
@@ -279,7 +340,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
         if (t === "docs")
             switch (name) {
                 case "$id": return row.doc_id;
-                case "$path": return row.path;
+                case "$path": return referencePath(String(row.path));
                 case "$content_hash": return row.file_hash == null ? null : hex(row.file_hash);
                 case "$updated_at": return scalar(`SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ?`, row.current_rev) ?? null;
                 case "$body": return docsRead(store, String(row.doc_id))?.content ?? null;
@@ -290,7 +351,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
             switch (name) {
                 case "$id": return row.block_id;
                 case "$doc": return row.doc_id;
-                case "$path": return row.__path;
+                case "$path": return referencePath(String(row.__path));
                 case "$ordinal": return row.ordinal;
                 case "$depth": return row.depth;
                 case "$body": return row.text;
@@ -303,7 +364,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 case "$node_id": return row.node_id;
                 case "$doc_id": return row.doc_id;
                 case "$block_id": return row.block_id;
-                case "$path": return row.__path;
+                case "$path": return referencePath(String(row.__path));
             }
         if (t === "edges")
             switch (name) {
@@ -313,8 +374,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 case "$src_block": return row.src_block;
                 case "$via": return row.via_node;
                 case "$from_commit": return row.from_commit;
-                case "$path": return row.__path;
-                case "$dst_path": return scalar(`SELECT path FROM docs WHERE doc_id = ?`, row.dst_node) ?? null;
+                case "$path": return referencePath(String(row.__path));
+                case "$dst_path": {
+                    const p = scalar(`SELECT path FROM docs WHERE doc_id = ?`, row.dst_node);
+                    return p == null ? null : referencePath(String(p));
+                }
                 case "$dst_uri": return scalar(`SELECT uri FROM external_nodes WHERE node_id = ?`, row.dst_node) ?? null;
             }
         return undefined;
@@ -323,14 +387,9 @@ export function makeStoreContext(store, repoId, opts = {}) {
     const getFrom = (row, key) => {
         if (row == null)
             return undefined;
-        // `$repo` is an intrinsic of EVERY scope — the root and any row, store-backed
-        // or plain. Bare names resolve against the current row only (oqx ≥ 0.7: no
-        // scope climbing), so a correlated subquery at any depth reaches the
-        // repository root through this local intrinsic, never by falling through
-        // to an enclosing scope.
-        if (key === "$repo")
-            return repoRoot;
-        if (row[REPO_ROOT]) {
+        // The root row: `^$it.$id` is the repository id, `^$it.<target>` the lazy
+        // root scan (the same handle `^<target>` / `root(name)` hands out).
+        if (row[ROOT_ROW]) {
             if (key === "$id")
                 return repoId;
             return rootFns[key] ? rootFns[key]() : undefined;
@@ -363,6 +422,13 @@ export function makeStoreContext(store, repoId, opts = {}) {
         const rels = rel[t];
         if (rels[key])
             return rels[key](r);
+        // A bare target name that is not one of this row's relations reads a
+        // property the row has none of (spec/surface §1.1, 2.0): loud, naming the
+        // root-row spelling. `docs`/`edges` never get here (run.ts refuses them
+        // statically); `blocks` on a block or edge row and `nodes` on a node or
+        // edge row do.
+        if (TARGETS.has(key))
+            throw new FilterInvalid(bareTargetMessage(key, null), "OQX");
         // per-target scalar fields.
         if (t === "docs") {
             if (key === "format")
@@ -505,14 +571,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return !!one(`SELECT 1 FROM sections s JOIN blocks hb ON hb.block_id = s.heading_block
        WHERE s.doc_id = ? AND lower(hb.text) LIKE '%' || lower(?) || '%' AND s.first_ordinal <= ? AND s.last_ordinal >= ? LIMIT 1`, r.doc_id, text, top, top);
     };
+    // `within(t)`: a doc id, else a path in either form (`/texts/*`, `texts/*`,
+    // `texts/x.md`) matched against the storage path.
     const within = (r, target) => {
         if (target.startsWith("d_"))
             return r.doc_id === target;
-        if (target.includes("*")) {
-            const like = target.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
+        const path = storagePath(target);
+        if (path.includes("*")) {
+            const like = path.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
             return !!one(`SELECT 1 WHERE ? LIKE ? ESCAPE '\\'`, r.__path, like);
         }
-        return r.__path === target;
+        return r.__path === path;
     };
     const underKind = (r, kind, name) => {
         const ap = String(r.ancestor_path ?? "").split("/").filter(Boolean);
@@ -531,14 +600,67 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return false;
         return jattr(r, "key") === leaf || jattr(r, "key") === key;
     };
+    // ---- refs(x): document references held in a property (spec/surface §1.3, 1.5)
+    // `x` is a string, a list, or absent; every string element that names a live
+    // document of this repo — a doc id (`d_…`), a repo-root-absolute path
+    // (`/a/b.md`) or a bare repo-relative path (`a/b.md`) — resolves to that
+    // document's row; anything else (a dangling reference, a non-string element)
+    // is dropped. Order preserved, duplicates kept. Each element is one indexed
+    // lookup under the root scan's guards and columns (`sql/scan.ts`), so the rows
+    // are indistinguishable from scanned ones and the docs root is never read.
+    const refDoc = (ref) => {
+        const g = guards("docs", repoId);
+        const path = storagePath(ref);
+        const byPath = one(`SELECT ${COLS.docs} FROM ${FROM.docs} WHERE ${g.sql} AND d.path = ?`, ...g.params, path);
+        if (byPath)
+            return tag(byPath, "docs");
+        if (!ref.startsWith("d_"))
+            return undefined;
+        return tag(one(`SELECT ${COLS.docs} FROM ${FROM.docs} WHERE ${g.sql} AND d.doc_id = ?`, ...g.params, ref), "docs");
+    };
+    const refs = (x) => {
+        const items = x == null ? [] : Array.isArray(x) ? x : [x];
+        const out = [];
+        for (const item of items) {
+            if (typeof item !== "string")
+                continue;
+            const row = refDoc(item);
+            if (row)
+                out.push(row);
+        }
+        return out;
+    };
+    // Store indexes by (target, path) — one object, one set of prepared statements,
+    // for the whole run (`null`: the path is not indexable).
+    const indexes = new Map();
+    const identity = (row) => {
+        const t = row?.[TARGET];
+        if (t === "docs")
+            return row.doc_id;
+        if (t === "blocks")
+            return row.block_id;
+        if (t === "nodes")
+            return row.node_id;
+        if (t === "edges")
+            return row.edge_id;
+        return row;
+    };
     return {
+        // The root scope's names (spec/oqx §2 step 5 at the root): the four lazy
+        // scans and `$id`, the repository id — so `^docs` / `0^docs` from any row is
+        // the scan and `^$id` / `0^$id` the id.
         root(name) {
             if (opts.rowsRoot && name === opts.rowsRoot.name)
                 return opts.rowsRoot.rows;
-            if (name === "$repo")
-                return repoRoot;
+            if (name === "$id")
+                return repoId;
             return rootFns[name] ? rootFns[name]() : undefined;
         },
+        // The root scope's row (oqx 0.18): the repository, so `^$it` from a
+        // top-level row is the root row and `^$it.docs` the docs scan.
+        rootObject() {
+            return rootRow;
+        },
         get: getFrom,
         toRows(value) {
             if (value == null)
@@ -551,17 +673,24 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 return value;
             return [value];
         },
-        identity(row) {
-            const t = row?.[TARGET];
-            if (t === "docs")
-                return row.doc_id;
-            if (t === "blocks")
-                return row.block_id;
-            if (t === "nodes")
-                return row.node_id;
-            if (t === "edges")
-                return row.edge_id;
-            return row;
+        identity,
+        // A store-backed equality index for a ROOT SCAN handle on a column or
+        // property SQLite indexes (store-index.ts); `undefined` for any other
+        // collection (a relation's rows, a lifted array) or path, so the engine
+        // builds its own over the materialized rows.
+        indexFor(collection, path) {
+            if (collection === null || typeof collection !== "object")
+                return undefined;
+            const root = rootScans.get(collection);
+            if (!root)
+                return undefined;
+            const key = `${root.target}\u0000${JSON.stringify(path)}`;
+            let index = indexes.get(key);
+            if (index === undefined) {
+                index = storeIndexFor(root.target, path, { db, repoId, tag: (rows, t) => tagAll(rows, t), get: getFrom, rows: root.rows, identity }) ?? null;
+                indexes.set(key, index);
+            }
+            return index ?? undefined;
         },
         // Free functions: oqx-js builtins (list/size/has) plus `range(s)`, which
         // coerces a string value to a range so `<point> in range(prop)` tests
@@ -577,6 +706,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 const p = args[0];
                 return { handled: true, value: docPropEntries(p.docId, p.source) };
             }
+            if (name === "refs")
+                return { handled: true, value: refs(args[0]) };
             if (name === "range") {
                 const s = args[0];
                 if (semantics.isRange(s))
@@ -613,7 +744,8 @@ export function tagRows(rows, target) {
 /**
  * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
  * values, 1.2) is rendered as `{ id, path }` — its id column and its document's
- * path, the same two keys every hit carries — never the store row itself.
+ * path in the reference form (`/a.md`, §1 "Paths"), the same two keys every hit
+ * carries — never the store row itself.
  * Returns undefined for anything that is not a tagged row (run.ts leaves those
  * alone).
  */
@@ -624,7 +756,7 @@ export function rowRef(value) {
     const r = value;
     const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : r.edge_id;
     const path = t === "docs" ? r.path : r.__path;
-    return { id: String(id), path: String(path ?? "") };
+    return { id: String(id), path: path == null ? "" : referencePath(String(path)) };
 }
 export { TARGET };
 //# sourceMappingURL=context.js.map

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

@@ -1,7 +1,8 @@
-import type { Query, Where, QueryPlanner, Plan } from "@omgbase/oqx";
+import type { Query, Expr, Where, QueryPlanner, Plan } from "@omgbase/oqx";
 import type { Store } from "../core/store/store.js";
 import { type StoreContextOptions } from "./context.js";
 import { type Target } from "./sql/translate.js";
+export declare function rootTarget(source: Expr): Target | null;
 /**
  * True when evaluating `where` in memory could raise an OQX error the pushed
  * conjuncts might hide by emptying the scan. The walk is generic over the whole
@@ -14,6 +15,12 @@ import { type Target } from "./sql/translate.js";
  *   • a bare reserved docs basename (`id path updated_at content_hash body`): 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 target name (`docs blocks nodes edges`, 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 edges),
+ *     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`)
  *
  * 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

@@ -17,49 +17,15 @@
 import { ROWS_ROOT, partitionPushable, residualQuery } from "@omgbase/oqx";
 import { makeStoreContext, tagRows } from "./context.js";
 import { translatePredicate, RESERVED_DOC_BASENAMES } from "./sql/translate.js";
-const ALIAS = {
-    docs: { self: "d", doc: "d" },
-    blocks: { self: "b", doc: "d" },
-    nodes: { self: "n", doc: "d" },
-    edges: { self: "e", doc: "d" },
-};
-const FROM = {
-    docs: "docs d",
-    blocks: "blocks b JOIN docs d ON d.doc_id = b.doc_id",
-    nodes: "nodes n JOIN docs d ON d.doc_id = n.doc_id",
-    edges: "edges e JOIN docs d ON d.doc_id = e.src_doc",
-};
-// Row columns + the owning-doc path as __path (matches the context roots so
-// produced rows are indistinguishable from a full scan's).
-const COLS = {
-    docs: "d.*",
-    blocks: "b.*, d.path AS __path",
-    nodes: "n.*, d.path AS __path",
-    edges: "e.*, d.path AS __path",
-};
-const ORDER = {
-    docs: "d.path, d.doc_id",
-    blocks: "d.path, b.block_id",
-    nodes: "d.path, n.node_id",
-    edges: "d.path, e.edge_id",
-};
-function guards(target, repoId) {
-    switch (target) {
-        case "docs": return { sql: "d.repo_id = ? AND d.deleted_commit IS NULL", params: [repoId] };
-        case "blocks": return { sql: "b.repo_id = ? AND b.deleted_commit IS NULL AND d.deleted_commit IS NULL", params: [repoId] };
-        case "nodes": return { sql: "n.repo_id = ? AND d.deleted_commit IS NULL", params: [repoId] };
-        case "edges": return { sql: "e.repo_id = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL", params: [repoId] };
-    }
-}
+import { ALIAS, COLS, FROM, ORDER, guards } from "./sql/scan.js";
+import { REACH_THROUGH, TARGETS, isTargetRelationOf } from "./root-row.js";
 // The root collection a query scans, if it is a bare `docs|blocks|nodes|edges`
-// or `$repo.<target>` source (else null — not a pushable shape).
-function rootTarget(source) {
-    const TARGETS = new Set(["docs", "blocks", "nodes", "edges"]);
+// source at the root scope (else null — not a pushable shape; a nested `^docs`
+// is a block's receiver, never the query's source). run.ts also asks: a bare
+// root scan's rows are store rows by construction.
+export function rootTarget(source) {
     if (source.kind === "ident" && TARGETS.has(source.name))
         return source.name;
-    if (source.kind === "member" && source.recv.kind === "ident" && source.recv.name === "$repo" && TARGETS.has(source.name)) {
-        return source.name;
-    }
     return null;
 }
 // ---- the residual walk (decline (c)) -----------------------------------------
@@ -75,6 +41,12 @@ function rootTarget(source) {
  *   • a bare reserved docs basename (`id path updated_at content_hash body`): 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 target name (`docs blocks nodes edges`, 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 edges),
+ *     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`)
  *
  * A residual made only of comparisons, logical operators, `in`/ranges, `!`,
  * literals, bindings and plain reads (including exists/none/count/collect/first
@@ -133,13 +105,21 @@ function exprMayRaise(e, target, root) {
     switch (e.kind) {
         case "call": return true;
         case "outer": return true;
-        case "ident": return root && target === "docs" && RESERVED_DOC_BASENAMES.has(e.name);
+        case "ident":
+            if (TARGETS.has(e.name))
+                return !root || !isTargetRelationOf(target, e.name);
+            return root && target === "docs" && RESERVED_DOC_BASENAMES.has(e.name);
         case "member":
             if (e.recv.kind === "ident" && e.recv.name === "doc" && RESERVED_DOC_BASENAMES.has(e.name))
                 return true;
+            if (TARGETS.has(e.name) && !(e.recv.kind === "ident" && isTargetRelationOf(REACH_THROUGH[e.recv.name], e.name)))
+                return true;
             return exprMayRaise(e.recv, target, root);
-        case "index": return exprMayRaise(e.recv, target, root) || exprMayRaise(e.index, target, root);
         case "unary": return exprMayRaise(e.expr, target, root);
+        // `x!` raises when absent; a value-position directive may `single`-fail or
+        // read anything its block reads.
+        case "required": return true;
+        case "op": return opMayRaise(e, target, root);
         case "binary":
         case "logical":
         case "in":

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

@@ -0,0 +1,21 @@
+export type Target = "docs" | "blocks" | "nodes" | "edges";
+export declare const TARGETS: ReadonlySet<string>;
+/** The target names that are a relation of each target's rows (§1.2). */
+export declare const TARGET_RELATIONS: Readonly<Record<Target, ReadonlySet<string>>>;
+/** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`). */
+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`";
+/**
+ * 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
+ * time, where the hint spells out the rule instead.
+ */
+export declare function bareTargetMessage(name: string, depth: number | null): string;
+/**
+ * The past-the-root error: `^docs` at the root scope (more carets than there
+ * are enclosing scopes) would read absent and count 0 — refused, naming the
+ * bare spelling. `levels` is the caret count written.
+ */
+export declare function pastRootMessage(name: string, levels: number): 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. */
+export declare function isTargetRelationOf(target: Target | undefined, name: string): boolean;

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

@@ -0,0 +1,55 @@
+// 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
+// root object (`^$it`) exposes the four collections. Two spellings are refused
+// as `filter_invalid`, with the messages below, in both engines:
+//
+//   • `$repo` (removed in 2.0) anywhere — bare, as a member head (`$repo.docs`),
+//     `^$repo`, `0^$repo` — statically, before any row is read, so the error is
+//     deterministic whether or not a row would have reached it (run.ts
+//     `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 `edges` are no row's relation, so they are
+//     refused statically by the same walk; `blocks` and `nodes` ARE relations
+//     of some rows (`docs.blocks`, `docs.nodes`, `blocks.nodes`,
+//     `section.blocks`), 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>`).
+export const TARGETS = new Set(["docs", "blocks", "nodes", "edges"]);
+/** The target names that are a relation of each target's rows (§1.2). */
+export const TARGET_RELATIONS = {
+    docs: new Set(["nodes", "blocks"]),
+    blocks: new Set(["nodes"]),
+    nodes: new Set(["blocks"]),
+    edges: new Set(),
+};
+/** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`). */
+export const REACH_THROUGH = { doc: "docs", block: "blocks", section: "nodes" };
+const NOUN = { docs: "documents", blocks: "blocks", nodes: "nodes", edges: "edges" };
+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
+ * time, where the hint spells out the rule instead.
+ */
+export function bareTargetMessage(name, depth) {
+    const t = name;
+    const carets = "^".repeat(depth ?? 1);
+    const how = depth === null ? `; one caret per enclosing block, or the absolute \`0^${name}\`` : "";
+    return `\`${name}\` inside a block reads a property of the current row, which has none — did you mean \`${carets}${name}\` (the repository's ${NOUN[t]}${how})?`;
+}
+/**
+ * The past-the-root error: `^docs` at the root scope (more carets than there
+ * are enclosing scopes) would read absent and count 0 — refused, naming the
+ * bare spelling. `levels` is the caret count written.
+ */
+export function pastRootMessage(name, levels) {
+    const t = name;
+    return `\`${"^".repeat(levels)}${name}\` reaches past the root — there is no enclosing row at this depth; at the top level the repository's ${NOUN[t]} are the bare \`${name}\` (\`${name} count { … }\`, \`from ${name}\`, \`entries(${name})\`)`;
+}
+/** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
+export function isTargetRelationOf(target, name) {
+    return target !== undefined && TARGET_RELATIONS[target].has(name);
+}
+//# sourceMappingURL=root-row.js.map

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

@@ -1,4 +1,4 @@
-import type { Query } from "@omgbase/oqx";
+import type { Query, Expr } from "@omgbase/oqx";
 import type { Store } from "../core/store/store.js";
 import type { SemanticVec } from "../search/cel/compile.js";
 export type OqxConsumer = "collect" | "count" | "exists" | "none" | "first" | "single";
@@ -34,6 +34,8 @@ export interface OqxOptions {
      * the differential conformance suite to prove planned == in-memory. */
     plan?: boolean;
 }
+export declare function rootPathLiterals(e: Expr): Expr;
+export declare function checkRootSpellings(q: Query): void;
 export declare function collectSemanticPhrases(source: string): string[];
 export declare function oqxRun(store: Store, repoId: string, source: string, opts?: OqxOptions): OqxResult;
 export declare function oqxRunAsync(store: Store, repoId: string, source: string, opts?: OqxOptions, embedQuery?: EmbedQuery): Promise<OqxResult>;