@omgbase/core 0.7.1 → 0.10.0

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.
@@ -198,7 +152,7 @@ const VALUE_KEY = "__oqx_value";
 // Rows as values (spec/surface §1.4, 1.2). The engine hands back store rows
 // wherever the projection made a row a VALUE — a nested `collect { }` /
 // `first { }` / `single { }` with an empty projection ("the row itself",
-// spec/oqx §12), a `values` projection of `$value`/`$self`, a field bound to a
+// spec/oqx §12), a `values` projection of `$it`/`$self`, a field bound to a
 // row — and a store row is not a wire shape (column names, `attrs` as a JSON
 // string, the `__path` join column, Buffers). Walk the projected value and
 // render every tagged row as `{ id, path }`; everything else passes through
@@ -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/scan.d.ts

@@ -0,0 +1,27 @@
+import type { Target } from "./translate.js";
+export declare const ALIAS: Record<Target, {
+    self: string;
+    doc: string;
+}>;
+export declare const FROM: Record<Target, string>;
+/** Row columns + the owning-doc path as `__path` (matches the context roots so
+ * produced rows are indistinguishable from a full scan's). */
+export declare const COLS: Record<Target, string>;
+/** The joined targets driven FROM the document: the same rows and columns as
+ * `FROM`, with the loop order fixed by `CROSS JOIN` so a predicate on the
+ * document (`d.path = ?`) is the outer search and the target's rows are
+ * reached through their `doc_id` / `src_doc` index. `guardsByDoc` goes with it. */
+export declare const FROM_BY_DOC: Record<Exclude<Target, "docs">, string>;
+export declare const ORDER: Record<Target, string>;
+/** The live-row and repository guards of a target scan. */
+export declare function guards(target: Target, repoId: string): {
+    sql: string;
+    params: unknown[];
+};
+/** `guards` for a `FROM_BY_DOC` statement: the same tests, with the document's
+ * repo first and the target's repo term behind SQLite's unary `+` so it stays a
+ * filter and never selects a `(repo_id, …)` index over the `doc_id` one. */
+export declare function guardsByDoc(target: Exclude<Target, "docs">, repoId: string): {
+    sql: string;
+    params: unknown[];
+};

package/dist/src/oqx-js/sql/scan.js

@@ -0,0 +1,62 @@
+// The SQL shape of a root scan, shared by the tier-3 planner (planner.ts) and
+// the store-backed indexes (store-index.ts): one FROM clause per target, the
+// columns a produced row carries (the target's own columns plus the owning
+// document's path as `__path`, exactly what the context's root scans select),
+// the default `(path, id)` order and the live-row/repo guards. Any statement
+// that produces rows the engine will treat as a target's rows must come from
+// here, so a planned or probed row is indistinguishable from a scanned one.
+export const ALIAS = {
+    docs: { self: "d", doc: "d" },
+    blocks: { self: "b", doc: "d" },
+    nodes: { self: "n", doc: "d" },
+    edges: { self: "e", doc: "d" },
+};
+export 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). */
+export const COLS = {
+    docs: "d.*",
+    blocks: "b.*, d.path AS __path",
+    nodes: "n.*, d.path AS __path",
+    edges: "e.*, d.path AS __path",
+};
+/** The joined targets driven FROM the document: the same rows and columns as
+ * `FROM`, with the loop order fixed by `CROSS JOIN` so a predicate on the
+ * document (`d.path = ?`) is the outer search and the target's rows are
+ * reached through their `doc_id` / `src_doc` index. `guardsByDoc` goes with it. */
+export const FROM_BY_DOC = {
+    blocks: "docs d CROSS JOIN blocks b ON b.doc_id = d.doc_id",
+    nodes: "docs d CROSS JOIN nodes n ON n.doc_id = d.doc_id",
+    edges: "docs d CROSS JOIN edges e ON e.src_doc = d.doc_id",
+};
+export 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",
+};
+/** The live-row and repository guards of a target scan. */
+export 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] };
+    }
+}
+/** `guards` for a `FROM_BY_DOC` statement: the same tests, with the document's
+ * repo first and the target's repo term behind SQLite's unary `+` so it stays a
+ * filter and never selects a `(repo_id, …)` index over the `doc_id` one. */
+export function guardsByDoc(target, repoId) {
+    switch (target) {
+        case "blocks": return { sql: "d.repo_id = ? AND +b.repo_id = ? AND b.deleted_commit IS NULL AND d.deleted_commit IS NULL", params: [repoId, repoId] };
+        case "nodes": return { sql: "d.repo_id = ? AND +n.repo_id = ? AND d.deleted_commit IS NULL", params: [repoId, repoId] };
+        case "edges": return { sql: "d.repo_id = ? AND +e.repo_id = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL", params: [repoId, repoId] };
+    }
+}
+//# sourceMappingURL=scan.js.map

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)). */

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

@@ -39,6 +39,8 @@
 // translated (that is the only context `partitionPushable` pushes into). `||`,
 // `!`, `in`, `matches` (needs a regexp UDF), and bare content-property routing
 // are deliberately declined here and left residual for now.
+import { storagePath } from "../../core/paths.js";
+import { TARGETS } from "../root-row.js";
 // ---- names that are never property reads ------------------------------------
 /**
  * Per target, the bare identifiers (and `doc.<k>` keys, via the docs set) that
@@ -59,7 +61,15 @@ export const NON_PROPERTY_NAMES = {
 // A `$`-namespaced intrinsic → a param-free SQL scalar, per target, with its kind.
 // Anything not mapped (e.g. docs `$body`, reconstructed; `$title`/`$tags`,
 // computed) returns null → residual. `$updated_at`/`$dst_path`/`$dst_uri` are
-// correlated subqueries.
+// correlated subqueries. `$path` and `$dst_path` are the REFERENCE form on the
+// surface (spec/surface §1 "Paths", 2.0) — `'/' || <storage column>` in SQL —
+// so every comparison, `startsWith`, `contains`, `lower()`… sees exactly the
+// string the in-memory intrinsic yields; `pathColumn` keeps the bare indexed
+// column at hand for the equality fast path.
+/** The rooted path read over a storage path column. */
+export function pathColumn(col) {
+    return { sql: `('/' || ${col})`, params: [], kind: "text", pathCol: col };
+}
 function intrinsicSql(name, ctx) {
     const { self, doc, target } = ctx;
     const text = (sql) => ({ sql, params: [], kind: "text" });
@@ -67,7 +77,7 @@ function intrinsicSql(name, ctx) {
     if (target === "docs")
         switch (name) {
             case "$id": return text(`${self}.doc_id`);
-            case "$path": return text(`${doc}.path`);
+            case "$path": return pathColumn(`${doc}.path`);
             case "$content_hash": return text(`lower(hex(${self}.file_hash))`);
             case "$updated_at": return text(`(SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ${self}.current_rev)`);
         }
@@ -75,7 +85,7 @@ function intrinsicSql(name, ctx) {
         switch (name) {
             case "$id": return text(`${self}.block_id`);
             case "$doc": return text(`${self}.doc_id`);
-            case "$path": return text(`${doc}.path`);
+            case "$path": return pathColumn(`${doc}.path`);
             case "$ordinal": return int(`${self}.ordinal`);
             case "$depth": return int(`${self}.depth`);
             case "$body": return text(`${self}.text`);
@@ -87,7 +97,7 @@ function intrinsicSql(name, ctx) {
             case "$node_id": return text(`${self}.node_id`);
             case "$doc_id": return text(`${self}.doc_id`);
             case "$block_id": return text(`${self}.block_id`);
-            case "$path": return text(`${doc}.path`);
+            case "$path": return pathColumn(`${doc}.path`);
         }
     else if (target === "edges")
         switch (name) {
@@ -97,8 +107,8 @@ function intrinsicSql(name, ctx) {
             case "$src_block": return text(`${self}.src_block`);
             case "$via": return text(`${self}.via_node`);
             case "$from_commit": return text(`${self}.from_commit`);
-            case "$path": return text(`${doc}.path`);
-            case "$dst_path": return text(`(SELECT dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`);
+            case "$path": return pathColumn(`${doc}.path`);
+            case "$dst_path": return text(`(SELECT '/' || dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`);
             case "$dst_uri": return text(`(SELECT xn.uri FROM external_nodes xn WHERE xn.node_id = ${self}.dst_node)`);
         }
     return null;
@@ -177,8 +187,9 @@ export function translateOperand(e, ctx) {
             if (e.name.startsWith("$"))
                 return intrinsicSql(e.name, ctx);
             // A relation, reach-through, source handle or the whole attrs object is not a
-            // scalar read (decline (b)).
-            if (NON_PROPERTY_NAMES[target].has(e.name))
+            // scalar read (decline (b)); a bare target name is a relation or a loud
+            // error (root-row.ts), never a property.
+            if (NON_PROPERTY_NAMES[target].has(e.name) || TARGETS.has(e.name))
                 return null;
             // Bare field per target.
             if (target === "docs") {
@@ -224,15 +235,15 @@ export function translateOperand(e, ctx) {
                     return null;
                 const k = rest[0];
                 if (k === "$path")
-                    return text(`${doc}.path`);
+                    return pathColumn(`${doc}.path`);
                 if (k === "format")
                     return text(`${doc}.format`);
                 if (k.startsWith("$"))
                     return null;
                 if (RESERVED_DOC_BASENAMES.has(k))
                     return null;
-                if (NON_PROPERTY_NAMES.docs.has(k))
-                    return null; // `doc.nodes`, `doc.frontmatter`, … (decline (b))
+                if (NON_PROPERTY_NAMES.docs.has(k) || TARGETS.has(k))
+                    return null; // `doc.nodes`, `doc.frontmatter`, `doc.docs` … (decline (b))
                 return propScalar(doc, k);
             }
             // block.type / block.text reach-through from a node.
@@ -372,6 +383,9 @@ function translateComparison(e, ctx) {
     const r = translateOperand(e.right, ctx);
     if (!l || !r)
         return null;
+    const fast = pathEquality(e.op, l, r);
+    if (fast)
+        return fast;
     if (plainComparable(e.op, l.kind, r.kind)) {
         // `==`/`!=` → null-safe IS / IS NOT (absence-normalized equality, faithful in
         // any context). Relational ops → plain SQL: a NULL operand yields NULL, which
@@ -387,6 +401,23 @@ function translateComparison(e, ctx) {
     return side === "right" ? typedComparison(e.op, l, r) : typedComparison(FLIP[e.op] ?? e.op, r, l);
 }
 const FLIP = { "<": ">", "<=": ">=", ">": "<", ">=": "<=" };
+/**
+ * The path equality fast path: `$path == "/a.md"` (or `!=`, either side) against
+ * a rooted text constant is `d.path IS ?` with the constant's storage form, so
+ * the `(repo_id, path)` index serves it; `'/' || d.path IS ?` — what the general
+ * form would emit — is the same predicate without the index. Only a constant
+ * that IS rooted qualifies (run.ts roots every literal compared with a path
+ * read, so that is every literal); a bare binding stays on the general form,
+ * where `'/' || d.path` can never equal it — exactly the in-memory answer.
+ */
+function pathEquality(op, l, r) {
+    if (op !== "==" && op !== "!=")
+        return null;
+    const [col, konst] = l.pathCol ? [l, r] : r.pathCol ? [r, l] : [null, null];
+    if (!col || !konst || konst.kind !== "text" || typeof konst.value !== "string" || !konst.value.startsWith("/"))
+        return null;
+    return { sql: `(${col.pathCol} ${IS_OP[op]} ?)`, params: [storagePath(konst.value)] };
+}
 /**
  * The typed push (spec/surface §1, 1.2 patch): `read <op> constant` where the
  * read is a JSON or property read and the constant a bool or num literal/binding.

package/dist/src/oqx-js/store-index.d.ts

@@ -0,0 +1,20 @@
+import type { RowIndex } from "@omgbase/oqx";
+import type Database from "better-sqlite3";
+import type { Target } from "./sql/translate.js";
+/** What the context lends an index: the store, the repo, how it tags rows, how
+ * it reads a field off a row, and the materialized rows of the root scan the
+ * index stands in for (read lazily, only by the fallback). */
+export interface StoreIndexDeps {
+    db: Database.Database;
+    repoId: string;
+    tag(rows: Record<string, unknown>[], target: Target): unknown[];
+    get(row: unknown, key: string): unknown;
+    rows(): unknown[];
+    identity(row: unknown): unknown;
+}
+/** A store-backed `RowIndex` for the root scan of `target` on `path`, or
+ * `undefined` when SQLite has no index for the path (per-target table above;
+ * multi-segment paths; `format`, edge `predicate`/`src_field`, `$tags`, …). */
+export declare function storeIndexFor(target: Target, path: readonly string[], deps: StoreIndexDeps): RowIndex | undefined;
+/** The paths `storeIndexFor` answers from SQLite, per target (for tests and docs). */
+export declare function indexablePaths(target: Target): readonly string[];