@omgbase/core 0.8.0 → 0.10.1

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

@@ -18,15 +18,14 @@ import { ROWS_ROOT, partitionPushable, residualQuery } from "@omgbase/oqx";
 import { makeStoreContext, tagRows } from "./context.js";
 import { translatePredicate, RESERVED_DOC_BASENAMES } from "./sql/translate.js";
 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)) -----------------------------------------
@@ -42,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
@@ -100,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>;

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

@@ -3,92 +3,79 @@
 // shape the engine's result into omgbase's OqxResult (lean {id, path, …} hits,
 // keyset pagination, count/exists scalars). Same signature + shape as the former
 // in-tree compiler, so every caller and the corpus are unchanged.
-import { parse, PlannedEngine, InMemoryEngine, OqxError } from "@omgbase/oqx";
+import { parse, PlannedEngine, InMemoryEngine, OqxError, resolveAliases, transform, visit, build, semantics } from "@omgbase/oqx";
 import { makeStoreContext, rowRef } from "./context.js";
-import { SQLiteQueryPlanner } from "./planner.js";
+import { SQLiteQueryPlanner, rootTarget } from "./planner.js";
+import { REPO_REMOVED_MESSAGE, TARGETS, bareTargetMessage, pastRootMessage } from "./root-row.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { float32ToBlob } from "../core/vec.js";
-import { encodeCursor as encodeKeyset, decodeCursor as decodeKeyset } from "../core/cursor.js";
+import { encodeCursor as encodeKeyset, decodePathCursor } from "../core/cursor.js";
+import { referencePath } from "../core/paths.js";
 // Row-scoped domain functions: authored as free calls (`text("x")`) that
 // implicitly reference the current row. `@omgbase/oqx` free functions receive no
-// row, so we rewrite them to `$self.fn(…)` (a method whose receiver is the row).
+// row, so we rewrite them to `$self.fn(…)` (a method whose receiver is the row)
+// — one `transform` over the AST (spec/oqx/AST.md §5), every block included.
+// `refs(x)` is NOT here: it reads no row (its argument is the value), so it stays
+// a free function served by the context's `callFunction`. The planner treats
+// every call alike (translate declines it; `exprMayRaise` flags it), `has_edge`
+// and `refs` included.
 const ROW_FNS = new Set([
     "text", "semantic", "under", "under_heading", "within", "under_kind",
     "yaml_path", "json_pointer", "has_edge", "has_anchor", "child_count", "parent_type",
 ]);
-const selfRef = { kind: "ident", name: "$self" };
-function rewriteExpr(e) {
-    switch (e.kind) {
-        case "member": return { ...e, recv: rewriteExpr(e.recv) };
-        case "index": return { ...e, recv: rewriteExpr(e.recv), index: rewriteExpr(e.index) };
-        case "unary": return { ...e, expr: rewriteExpr(e.expr) };
-        case "binary":
-        case "logical":
-        case "in":
-            return { ...e, left: rewriteExpr(e.left), right: rewriteExpr(e.right) };
-        case "range":
-            return { ...e, lo: e.lo ? rewriteExpr(e.lo) : null, hi: e.hi ? rewriteExpr(e.hi) : null };
-        case "call": {
-            const recv = e.recv ? rewriteExpr(e.recv) : null;
-            const args = e.args.map(rewriteExpr);
-            if (recv === null && ROW_FNS.has(e.name))
-                return { kind: "call", recv: selfRef, name: e.name, args };
-            return { kind: "call", recv, name: e.name, args };
-        }
-        default: return e; // lit, ident, outer, binding
-    }
-}
-function rewriteWhere(w) {
-    switch (w.kind) {
-        case "and": return { kind: "and", parts: w.parts.map(rewriteWhere) };
-        case "or": return { kind: "or", parts: w.parts.map(rewriteWhere) };
-        case "not": return { kind: "not", expr: rewriteWhere(w.expr) };
-        case "scalar": return { kind: "scalar", expr: rewriteExpr(w.expr) };
-        case "op": return rewriteOp(w);
-    }
+// Paths on the surface are the reference form (spec/surface §1 "Paths", 2.0):
+// `$path` and `$dst_path` read `/a/b.md`. A string literal a query compares
+// with one of them — `$path == "a.md"`, `"a.md" != $dst_path`,
+// `$path.startsWith("lab/")` — is rooted first, so both spellings match; a
+// property or binding compared with a path is never touched (it is the
+// author's value). The planner sees the rewritten tree too, so the pushed SQL
+// and the in-memory engine agree by construction.
+const PATH_INTRINSICS = new Set(["$path", "$dst_path"]);
+function isPathRead(e) {
+    return (e.kind === "ident" || e.kind === "outer" || e.kind === "member") && PATH_INTRINSICS.has(e.name);
 }
-function rewriteOp(op) {
-    return { ...op, receiver: rewriteExpr(op.receiver), sub: rewriteSub(op.sub) };
+function rootLiteral(e) {
+    return e.kind === "lit" && typeof e.value === "string" ? { ...e, value: referencePath(e.value) } : e;
 }
-function rewriteFollow(f) {
-    return {
-        ...f,
-        // each destination is a relation Expr or a destination block (an OpNode)
-        destinations: f.destinations.map((d) => (d.kind === "op" ? rewriteOp(d) : rewriteExpr(d))),
-        where: f.where ? rewriteExpr(f.where) : null,
-        frontier: f.frontier ? rewriteExpr(f.frontier) : null,
-        by: f.by ? rewriteExpr(f.by) : null,
-    };
-}
-function rewriteSelect(items) {
-    return items.map((it) => it.kind === "field" ? { ...it, expr: rewriteExpr(it.expr) } : { ...it, op: rewriteOp(it.op) });
+export function rootPathLiterals(e) {
+    if (e.kind === "binary" && (e.op === "==" || e.op === "!=")) {
+        if (isPathRead(e.left))
+            return { ...e, right: rootLiteral(e.right) };
+        if (isPathRead(e.right))
+            return { ...e, left: rootLiteral(e.left) };
+    }
+    if (e.kind === "call" && e.recv !== null && e.name === "startsWith" && e.args.length === 1 && isPathRead(e.recv)) {
+        return { ...e, args: [rootLiteral(e.args[0])] };
+    }
+    return e;
 }
-function rewriteSub(s) {
-    return {
-        from: s.from.map(rewriteExpr),
-        where: s.where ? rewriteWhere(s.where) : null,
-        select: rewriteSelect(s.select),
-        orderBy: s.orderBy ? s.orderBy.map((o) => ({ ...o, expr: rewriteExpr(o.expr) })) : null,
-        follow: s.follow ? rewriteFollow(s.follow) : null,
-        ...(s.values ? { values: true } : {}),
-        ...(s.limit ? { limit: rewriteExpr(s.limit) } : {}),
-        ...(s.offset ? { offset: rewriteExpr(s.offset) } : {}),
-    };
+// The root row (root-row.ts, spec/surface §1.1, 2.0): `$repo` anywhere, and a
+// bare `docs`/`edges` at scope depth ≥ 1 (a property read of a row that has
+// none), are refused before evaluation — one `visit` over the parsed tree, so
+// the error does not depend on which rows the data happens to hold and the
+// planned and in-memory paths agree trivially. `blocks`/`nodes` are relations of
+// some rows and are judged by the context at read time (same message). A
+// `^<target>` with more carets than enclosing scopes (`^docs count { }` at the
+// top level) would read absent and count 0: refused too, naming the bare
+// spelling.
+export function checkRootSpellings(q) {
+    visit(q, {
+        enter(node, ctx) {
+            if (node.kind !== "ident" && node.kind !== "outer")
+                return;
+            if (node.name === "$repo")
+                throw new FilterInvalid(REPO_REMOVED_MESSAGE, "OQX");
+            if (node.kind === "ident" && ctx.depth >= 1 && (node.name === "docs" || node.name === "edges")) {
+                throw new FilterInvalid(bareTargetMessage(node.name, ctx.depth), "OQX");
+            }
+            if (node.kind === "outer" && TARGETS.has(node.name) && node.levels > ctx.depth) {
+                throw new FilterInvalid(pastRootMessage(node.name, node.levels), "OQX");
+            }
+        },
+    });
 }
 function rewriteQuery(q) {
-    return {
-        source: rewriteExpr(q.source),
-        from: q.from.map(rewriteExpr),
-        where: q.where ? rewriteWhere(q.where) : null,
-        select: rewriteSelect(q.select),
-        orderBy: q.orderBy ? q.orderBy.map((o) => ({ ...o, expr: rewriteExpr(o.expr) })) : null,
-        consumer: q.consumer,
-        follow: q.follow ? rewriteFollow(q.follow) : null,
-        ...(q.distinct ? { distinct: true } : {}),
-        ...(q.values ? { values: true } : {}),
-        ...(q.limit ? { limit: rewriteExpr(q.limit) } : {}),
-        ...(q.offset ? { offset: rewriteExpr(q.offset) } : {}),
-    };
+    return transform(q, (e) => (e.kind === "call" && e.recv === null && ROW_FNS.has(e.name) ? { ...e, recv: build.ident("$self") } : rootPathLiterals(e)));
 }
 // A top-level `limit`/`offset` on the collect path is applied by the runner (see
 // oqxRunInner), so it must be a plain number literal here — there is no row to
@@ -101,76 +88,9 @@ function constBound(e, word) {
         return e.value;
     throw new FilterInvalid(`top-level ${word} must be a non-negative integer literal`, "OQX");
 }
-// Distinct phrases referenced by `semantic("…")` (free calls in the raw parse).
+// Distinct phrases referenced by `semantic("…")` (free calls in the raw parse),
+// found by one `visit` over the whole tree.
 export function collectSemanticPhrases(source) {
-    const phrases = new Set();
-    const visitExpr = (e) => {
-        switch (e.kind) {
-            case "call":
-                if (e.recv === null && e.name === "semantic" && e.args[0]?.kind === "lit" && typeof e.args[0].value === "string") {
-                    phrases.add(e.args[0].value);
-                }
-                if (e.recv)
-                    visitExpr(e.recv);
-                e.args.forEach(visitExpr);
-                return;
-            case "member":
-                visitExpr(e.recv);
-                return;
-            case "index":
-                visitExpr(e.recv);
-                visitExpr(e.index);
-                return;
-            case "unary":
-                visitExpr(e.expr);
-                return;
-            case "binary":
-            case "logical":
-            case "in":
-                visitExpr(e.left);
-                visitExpr(e.right);
-                return;
-            case "range":
-                if (e.lo)
-                    visitExpr(e.lo);
-                if (e.hi)
-                    visitExpr(e.hi);
-                return;
-            default: return;
-        }
-    };
-    const visitWhere = (w) => {
-        switch (w.kind) {
-            case "and":
-            case "or":
-                w.parts.forEach(visitWhere);
-                return;
-            case "not":
-                visitWhere(w.expr);
-                return;
-            case "scalar":
-                visitExpr(w.expr);
-                return;
-            case "op":
-                visitOp(w);
-                return;
-        }
-    };
-    const visitOp = (op) => { visitExpr(op.receiver); visitSub(op.sub); };
-    const visitFollow = (f) => {
-        f.destinations.forEach((d) => (d.kind === "op" ? visitOp(d) : visitExpr(d)));
-        [f.where, f.frontier, f.by].forEach((x) => x && visitExpr(x));
-    };
-    const visitSub = (s) => {
-        s.from.forEach(visitExpr);
-        if (s.where)
-            visitWhere(s.where);
-        s.select.forEach((it) => it.kind === "field" ? visitExpr(it.expr) : visitOp(it.op));
-        if (s.orderBy)
-            s.orderBy.forEach((o) => visitExpr(o.expr));
-        if (s.follow)
-            visitFollow(s.follow);
-    };
     let q;
     try {
         q = parse(source);
@@ -178,19 +98,53 @@ export function collectSemanticPhrases(source) {
     catch {
         return [];
     }
-    visitExpr(q.source);
-    q.from.forEach(visitExpr);
-    if (q.where)
-        visitWhere(q.where);
-    q.select.forEach((it) => it.kind === "field" ? visitExpr(it.expr) : visitOp(it.op));
-    if (q.orderBy)
-        q.orderBy.forEach((o) => visitExpr(o.expr));
-    if (q.follow)
-        visitFollow(q.follow);
+    const phrases = new Set();
+    visit(q, {
+        enter(node) {
+            if (node.kind === "call" && node.recv === null && node.name === "semantic") {
+                const arg = node.args[0];
+                if (arg?.kind === "lit" && typeof arg.value === "string")
+                    phrases.add(arg.value);
+            }
+        },
+    });
     return [...phrases];
 }
-const ID_ITEM = { kind: "field", name: "__oqx_id", expr: { kind: "ident", name: "$id" }, lift: 0 };
-const PATH_ITEM = { kind: "field", name: "__oqx_path", expr: { kind: "ident", name: "$path" }, lift: 0 };
+const ID_ITEM = build.field("__oqx_id", build.ident("$id"));
+const PATH_ITEM = build.field("__oqx_path", build.ident("$path"));
+// A hit is a store row (spec/surface §1.4, 1.5). The engine's top-level rows
+// are store rows by construction when the source is a bare root scan and
+// nothing re-projects them; a `follow` destination (`follow before` over a
+// frontmatter list of paths), a `from E` re-projection or any other source can
+// reach a scalar, which the injected `$id`/`$path` reads would render as the
+// junk hit `{ id: "undefined", path: "" }`. For those queries the row itself is
+// projected too (`$it`), and `toHit` fails the query when it is not a row. Only
+// then: a row clone per hit is free here but not in the Rust port, and a root
+// scan cannot need it. A `values` projection returns no hits, so it is exempt
+// (`from docs from tags select $it values` is a flat list of tags).
+const SELF_KEY = "__oqx_self";
+const SELF_ITEM = build.field(SELF_KEY, build.ident("$it"));
+function mayReachNonRows(q) {
+    return q.follow !== null || q.from.length > 0 || rootTarget(q.source) === null;
+}
+function describeValue(v) {
+    if (v === null || v === undefined)
+        return "an absent value";
+    if (typeof v === "string")
+        return `a string (${JSON.stringify(v)})`;
+    if (typeof v === "number")
+        return `a number (${String(v)})`;
+    if (typeof v === "boolean")
+        return `a boolean (${String(v)})`;
+    if (Array.isArray(v))
+        return "an array";
+    if (semantics.isRange(v))
+        return "a range";
+    return "an object";
+}
+function notAStoreRow(v) {
+    return new FilterInvalid(`a hit must be a document, block, node or edge row — the query reached ${describeValue(v)}; to follow document references held in a property use refs(<field>)`, "OQX");
+}
 // The reserved key a top-level `values` projection's single item is renamed to,
 // so it rides through id/path injection, keyset paging, and distinct as an
 // ordinary record field and is peeled off at the end.
@@ -222,7 +176,9 @@ function renderValue(v) {
 }
 function toHit(row) {
     const o = row;
-    const { __oqx_id, __oqx_path, ...rest } = o;
+    const { __oqx_id, __oqx_path, __oqx_self, ...rest } = o;
+    if (SELF_KEY in o && !rowRef(__oqx_self))
+        throw notAStoreRow(__oqx_self);
     return { id: String(__oqx_id), path: String(__oqx_path ?? ""), ...renderValue(rest) };
 }
 // Top-level `select distinct`: dedup hits by their USER projection (every field
@@ -255,7 +211,11 @@ export function oqxRun(store, repoId, source, opts = {}) {
     }
 }
 function oqxRunInner(store, repoId, source, opts) {
-    const parsed = rewriteQuery(parse(source));
+    // The query's `select` aliases are resolved HERE, once, before the runner
+    // renames/injects items (an engine evaluates the query it is given).
+    const raw = parse(source);
+    checkRootSpellings(raw);
+    const parsed = rewriteQuery(resolveAliases(raw));
     const consumer = parsed.consumer;
     const ctxOpts = opts.semanticVectors ? { semanticVectors: opts.semanticVectors } : {};
     const ctx = makeStoreContext(store, repoId, ctxOpts);
@@ -281,21 +241,22 @@ function oqxRunInner(store, repoId, source, opts) {
     // id/path are unique per row and would defeat the engine's projection dedup, so
     // we run without engine-distinct and dedup hits by their USER projection below,
     // keeping the first row's id/path.
-    const topDistinct = !!parsed.distinct;
+    const topDistinct = parsed.distinct;
     // A top-level `values` projection runs as a RECORD projection whose single
     // item is renamed to VALUE_KEY (the engine's own values mode is switched off),
     // so pagination and distinct work unchanged; the bare values are peeled off
     // the final page below and returned as `values` with `hits` empty.
-    const topValues = !!parsed.values;
+    const topValues = parsed.values;
     const userSelect = topValues ? [{ ...parsed.select[0], name: VALUE_KEY }] : parsed.select;
     // On the collect path a top-level `limit`/`offset` is ALSO taken out of the
     // engine query and applied here, after the runner's own distinct — the engine
     // would otherwise bound the raw rows before dedup (`select distinct type
     // limit 3` must be three distinct types). first/single keep theirs: the
     // engine's offset-aware cap is exactly right for them.
-    const { limit: topLimit, offset: topOffset, ...unbounded } = parsed;
-    const base = consumer === "collect" ? unbounded : parsed;
-    const q = { ...base, distinct: false, values: false, select: [ID_ITEM, PATH_ITEM, ...userSelect] };
+    const { limit: topLimit, offset: topOffset } = parsed;
+    const base = consumer === "collect" ? { ...parsed, limit: null, offset: null } : parsed;
+    const guard = !topValues && mayReachNonRows(parsed) ? [SELF_ITEM] : [];
+    const q = { ...base, distinct: false, values: false, select: [ID_ITEM, PATH_ITEM, ...guard, ...userSelect] };
     const res = engine.run(q, []);
     if (consumer === "first" || consumer === "single") {
         const row = res.consumer === "first" || res.consumer === "single" ? res.row : null;
@@ -341,14 +302,17 @@ export async function oqxRunAsync(store, repoId, source, opts = {}, embedQuery)
     }
     return oqxRun(store, repoId, source, { ...opts, semanticVectors });
 }
-// The collect page's keyset is (path, id): the kernel's shared cursor encoding
-// (core/cursor.ts) with a two-part tuple. A malformed cursor is CursorInvalid,
-// which the MCP layer maps to filter_invalid.
+// The collect page's keyset is (path, id) — the hit's path, so the reference
+// form (`/a.md`): the kernel's shared cursor encoding (core/cursor.ts) with a
+// two-part tuple. A malformed cursor is CursorInvalid, which the MCP layer maps
+// to filter_invalid; so is a cursor whose path is not rooted — one issued by a
+// 1.x surface, whose keyset would otherwise sort before every rooted hit and
+// silently replay the first page (spec/surface §1.4, 2.0).
 function encodeCursor(path, id) {
     return encodeKeyset([path, id]);
 }
 function decodeCursor(cursor) {
-    const [path, id] = decodeKeyset(cursor, "query", 2);
+    const [path, id] = decodePathCursor(cursor, "query", 2);
     return { path: path, id: id };
 }
 /** Parse an OQX source into the `@omgbase/oqx` AST (re-exported for callers). */

package/dist/src/oqx-js/sql/translate.d.ts

@@ -48,6 +48,11 @@ export interface Operand extends Frag {
         key: string;
     };
     value?: unknown;
+    /** The storage-form path column behind a `$path` / `doc.$path` read
+     * (`d.path`): the operand's SQL is the rooted `'/' || <col>`, and an
+     * equality against a rooted text constant is re-shaped onto the bare,
+     * indexed column (`pathEquality`). */
+    pathCol?: string;
 }
 /**
  * Per target, the bare identifiers (and `doc.<k>` keys, via the docs set) that
@@ -59,6 +64,8 @@ export interface Operand extends Frag {
  * `translate.test.ts` asserts this set against the store context.
  */
 export declare const NON_PROPERTY_NAMES: Readonly<Record<Target, ReadonlySet<string>>>;
+/** The rooted path read over a storage path column. */
+export declare function pathColumn(col: string): Operand;
 /** docs intrinsics whose BARE (non-$) form is a loud error in-memory (10 §2) — not
  * pushable, so the residual raises it (and the planner keeps the whole query
  * unplanned when one is residual: spec/surface §1 decline (c)). */