@omgbase/core 0.10.1 → 0.11.1

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

@@ -10,16 +10,16 @@
 // are planned; everything else declines to a full in-memory run. One more
 // decline keeps the planned path invisible (spec/surface §1 decline (c)): a
 // pushed conjunct that empties the scan would also hide an OQX eval error a
-// residual conjunct raises in memory (`path == "x" && $path == "nope.md"` was
+// residual conjunct raises in memory (`path == "x" && path == "nope.md"` was
 // `[]` planned, `filter_invalid` in memory), so when any residual conjunct could
 // raise — a function or method call, a `single` block, a `^`-escaped name, or a
 // bare reserved docs basename — the WHOLE query runs unplanned.
 import { ROWS_ROOT, partitionPushable, residualQuery } from "@omgbase/oqx";
 import { makeStoreContext, tagRows } from "./context.js";
-import { translatePredicate, RESERVED_DOC_BASENAMES } from "./sql/translate.js";
+import { translatePredicate } 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`
+// The root collection a query scans, if it is a bare `docs|blocks|nodes|links`
 // 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.
@@ -38,12 +38,12 @@ export function rootTarget(source) {
  *   • any `call` node (a function or method: unknown name, bad regex, wrong target…)
  *   • any nested block whose consumer is `single` (raises on 0 or >1 rows)
  *   • any `^`-escaped name: an `outer` reference or a `^name:` lift
- *   • a bare reserved docs basename (`id path updated_at content_hash body`): as
+ *   • a bare reserved docs basename (`id path updated_at hash raw`): as
  *     an `ident` at the ROOT scope when the target is `docs`, or as `doc.<name>`
  *     on any target at any depth (the reach-through row is a doc)
- *   • a bare target name (`docs blocks nodes edges`, root-row.ts) read as a
+ *   • a bare target name (`docs blocks nodes links`, 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),
+ *     the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
  *     as an `ident` at any depth below (the rows there are unknown), or as
  *     `<head>.<name>` unless the head is a reach-through whose row has that
  *     relation (`doc.nodes`, `doc.blocks`, `block.nodes`, `section.blocks`)
@@ -86,6 +86,8 @@ function subMayRaise(s, target) {
     }
     if (s.orderBy?.some((o) => exprMayRaise(o.expr, target, false)))
         return true;
+    if (s.frontier && exprMayRaise(s.frontier, target, false))
+        return true;
     if (s.follow && followMayRaise(s.follow, target))
         return true;
     if (s.limit && exprMayRaise(s.limit, target, false))
@@ -95,23 +97,18 @@ function subMayRaise(s, target) {
     return false;
 }
 // A destination is a relation Expr read in the frontier row's scope, or a
-// destination block (an OpNode) whose receiver and body may each raise.
+// destination block (an OpNode) whose receiver, body, `frontier` and `depth`
+// are its own (oqx 0.20).
 function followMayRaise(f, target) {
-    if (f.destinations.some((d) => (d.kind === "op" ? opMayRaise(d, target, false) : exprMayRaise(d, target, false))))
-        return true;
-    return [f.where, f.frontier, f.by].some((e) => e !== null && exprMayRaise(e, target, false));
+    return f.destinations.some((d) => (d.kind === "op" ? opMayRaise(d, target, false) : exprMayRaise(d, target, false)));
 }
 function exprMayRaise(e, target, root) {
     switch (e.kind) {
         case "call": return true;
         case "outer": return true;
         case "ident":
-            if (TARGETS.has(e.name))
-                return !root || !isTargetRelationOf(target, e.name);
-            return root && target === "docs" && RESERVED_DOC_BASENAMES.has(e.name);
+            return TARGETS.has(e.name) && (!root || !isTargetRelationOf(target, 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);
@@ -126,6 +123,8 @@ function exprMayRaise(e, target, root) {
             return exprMayRaise(e.left, target, root) || exprMayRaise(e.right, target, root);
         case "range":
             return (e.lo !== null && exprMayRaise(e.lo, target, root)) || (e.hi !== null && exprMayRaise(e.hi, target, root));
+        // A tuple (oqx 0.20) is never pushed down; it raises iff an element does.
+        case "tuple": return e.items.some((x) => exprMayRaise(x, target, root));
         case "lit":
         case "binding": return false;
     }

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

@@ -1,10 +1,10 @@
-export type Target = "docs" | "blocks" | "nodes" | "edges";
+export type Target = "docs" | "blocks" | "nodes" | "links";
 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`). */
+/** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`, and a link's `dst.x`). */
 export declare const REACH_THROUGH: Readonly<Record<string, Target>>;
-export declare const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 \u2014 reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^$id` / `0^$id`";
+export declare const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 \u2014 reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^id` / `0^id`";
 /**
  * The bare-target error. `depth` is the scope depth the name was read at when
  * known statically (the carets in the hint count it); `null` when raised at read
@@ -17,5 +17,12 @@ export declare function bareTargetMessage(name: string, depth: number | null): s
  * bare spelling. `levels` is the caret count written.
  */
 export declare function pastRootMessage(name: string, levels: number): string;
+/**
+ * The unknown-target error (3.0 name pass): a top-level `from <name>` whose name
+ * is not one of the four collections would read an absent root and return an
+ * empty result — refused instead, naming the collections; `edges`, the links
+ * target's name before 3.0, gets its new name spelled out.
+ */
+export declare function unknownTargetMessage(name: string): string;
 /** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
 export declare function isTargetRelationOf(target: Target | undefined, name: string): boolean;

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

@@ -1,6 +1,6 @@
 // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18). The repository is OQX's
 // root row: from a top-level row `^docs` reaches the documents (one caret per
-// enclosing block, or the absolute `0^docs`), `^$id` the repository id, and the
+// enclosing block, or the absolute `0^docs`), `^id` the repository id, and the
 // root object (`^$it`) exposes the four collections. Two spellings are refused
 // as `filter_invalid`, with the messages below, in both engines:
 //
@@ -10,24 +10,24 @@
 //     `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
+//     which has none: `docs` and `links` 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"]);
+export const TARGETS = new Set(["docs", "blocks", "nodes", "links"]);
 /** 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(),
+    links: 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 reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`, and a link's `dst.x`). */
+export const REACH_THROUGH = { doc: "docs", block: "blocks", section: "nodes", dst: "docs" };
+const NOUN = { docs: "documents", blocks: "blocks", nodes: "nodes", links: "links" };
+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
@@ -48,6 +48,16 @@ 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})\`)`;
 }
+/**
+ * The unknown-target error (3.0 name pass): a top-level `from <name>` whose name
+ * is not one of the four collections would read an absent root and return an
+ * empty result — refused instead, naming the collections; `edges`, the links
+ * target's name before 3.0, gets its new name spelled out.
+ */
+export function unknownTargetMessage(name) {
+    const was = name === "edges" ? " (`edges` was renamed `links` in surface 3.0)" : "";
+    return `\`${name}\` is not a target — the repository's collections are \`docs\`, \`blocks\`, \`nodes\`, \`links\`${was}`;
+}
 /** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
 export function isTargetRelationOf(target, name) {
     return target !== undefined && TARGET_RELATIONS[target].has(name);

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

@@ -6,6 +6,12 @@ export type EmbedQuery = (text: string) => Promise<{
     model: string;
     vec: Float32Array;
 }>;
+/** A query hit (spec/surface §1.4, 3.0): the row's identity under the SAME
+ * bare names the expression language reads — `id`, `path` — plus whatever
+ * `select` projected. A key copied from a hit is valid in the next `where` with
+ * no translation (`where id == "<hit.id>"`); a `select id, path` is simply the
+ * envelope, and any other projection whose output key would be `id` or `path`
+ * must be aliased (`envelopeCollision`). */
 export interface OqxHit {
     id: string;
     path: string;

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

@@ -1,12 +1,13 @@
 // omgbase's OQX entry point, served by `@omgbase/oqx`: parse the source, run it
 // through the in-memory engine over a store-backed DataContext (context.ts), and
-// shape the engine's result into omgbase's OqxResult (lean {id, path, …} hits,
-// keyset pagination, count/exists scalars). Same signature + shape as the former
+// shape the engine's result into omgbase's OqxResult (lean {id, path, …} hits
+// — the envelope keys ARE the attributes, spec/surface §1.4 3.0 — 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, resolveAliases, transform, visit, build, semantics } from "@omgbase/oqx";
 import { makeStoreContext, rowRef } from "./context.js";
 import { SQLiteQueryPlanner, rootTarget } from "./planner.js";
-import { REPO_REMOVED_MESSAGE, TARGETS, bareTargetMessage, pastRootMessage } from "./root-row.js";
+import { REPO_REMOVED_MESSAGE, TARGETS, bareTargetMessage, pastRootMessage, unknownTargetMessage } from "./root-row.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { float32ToBlob } from "../core/vec.js";
 import { encodeCursor as encodeKeyset, decodePathCursor } from "../core/cursor.js";
@@ -24,15 +25,25 @@ const ROW_FNS = new Set([
     "yaml_path", "json_pointer", "has_edge", "has_anchor", "child_count", "parent_type",
 ]);
 // 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"]);
+// `path` and the edge field `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/")`, `doc.path == "a.md"` — is rooted first, so both
+// spellings match; a property or binding compared with a path is never touched
+// (it is the author's value), and neither is an authored `path:` key read
+// through a source handle (`data.path`, `frontmatter.path`, `inline.path`): a
+// member read is a path read only through a ROW handle (`doc`, `block`, `dst`,
+// `$it`).
+// The planner sees the rewritten tree too, so the pushed SQL and the in-memory
+// engine agree by construction.
+const PATH_ATTRIBUTES = new Set(["path", "dst_path"]);
+const ROW_HANDLES = new Set(["doc", "block", "dst", "$it"]);
 function isPathRead(e) {
-    return (e.kind === "ident" || e.kind === "outer" || e.kind === "member") && PATH_INTRINSICS.has(e.name);
+    if (e.kind === "ident" || e.kind === "outer")
+        return PATH_ATTRIBUTES.has(e.name);
+    if (e.kind === "member" && PATH_ATTRIBUTES.has(e.name)) {
+        return (e.recv.kind === "ident" || e.recv.kind === "outer") && ROW_HANDLES.has(e.recv.name);
+    }
+    return false;
 }
 function rootLiteral(e) {
     return e.kind === "lit" && typeof e.value === "string" ? { ...e, value: referencePath(e.value) } : e;
@@ -50,7 +61,7 @@ export function rootPathLiterals(e) {
     return e;
 }
 // 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
+// bare `docs`/`links` 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
@@ -59,13 +70,18 @@ export function rootPathLiterals(e) {
 // top level) would read absent and count 0: refused too, naming the bare
 // spelling.
 export function checkRootSpellings(q) {
+    // A top-level `from <name>` that is no collection (`from edges`, the links
+    // target's name before 3.0) would scan an absent root and come back empty:
+    // refused, naming the four collections (root-row.ts).
+    if (q.source.kind === "ident" && !TARGETS.has(q.source.name))
+        throw new FilterInvalid(unknownTargetMessage(q.source.name), "OQX");
     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")) {
+            if (node.kind === "ident" && ctx.depth >= 1 && (node.name === "docs" || node.name === "links")) {
                 throw new FilterInvalid(bareTargetMessage(node.name, ctx.depth), "OQX");
             }
             if (node.kind === "outer" && TARGETS.has(node.name) && node.levels > ctx.depth) {
@@ -110,13 +126,34 @@ export function collectSemanticPhrases(source) {
     });
     return [...phrases];
 }
-const ID_ITEM = build.field("__oqx_id", build.ident("$id"));
-const PATH_ITEM = build.field("__oqx_path", build.ident("$path"));
+const ID_ITEM = build.field("__oqx_id", build.ident("id"));
+const PATH_ITEM = build.field("__oqx_path", build.ident("path"));
+// Result projections may not overwrite the envelope (spec/surface §1.4, 3.0):
+// a projection whose output key is `id` or `path` is allowed only when it IS
+// the envelope's own selection — the bare attribute of the same name, which
+// collapses onto the envelope key (`select id, path` is simply the envelope) —
+// and is otherwise a loud error asking for an alias: `select data.path` must be
+// `select p: data.path`, `select path: doc.layer` likewise. Checked over the
+// resolved items (an alias is just a name here), before the engine runs, so the
+// error never depends on the rows. A `values` projection returns no hits, so
+// the envelope — and the rule — do not apply.
+const ENVELOPE_KEYS = new Set(["id", "path"]);
+function envelopeCollision(items) {
+    for (const item of items) {
+        if (!ENVELOPE_KEYS.has(item.name))
+            continue;
+        if (item.kind === "field" && item.expr.kind === "ident" && item.expr.name === item.name)
+            continue;
+        const hint = item.name === "path" ? "p: data.path" : "i: data.id";
+        return new FilterInvalid(`projection \`${item.name}\` collides with the hit envelope — alias it (\`${hint}\`)`, "OQX");
+    }
+    return null;
+}
 // 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
+// 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
@@ -143,7 +180,7 @@ function describeValue(v) {
     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");
+    return new FilterInvalid(`a hit must be a document, block, node or link 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
@@ -155,9 +192,11 @@ const VALUE_KEY = "__oqx_value";
 // 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
-// untouched (plain records and arrays are descended, scalars kept). Hits are
-// records the engine built from the injected id/path items, never rows.
+// render every tagged row as `{ id, path }` — the hit envelope's own keys
+// (3.0), one notation for "a document reference" everywhere a row shape
+// appears in a result; everything else passes through untouched (plain records
+// and arrays are descended, scalars kept). Hits are records the engine built
+// from the injected id/path items, never rows.
 function renderValue(v) {
     if (v === null || typeof v !== "object")
         return v;
@@ -179,11 +218,13 @@ function toHit(row) {
     const { __oqx_id, __oqx_path, __oqx_self, ...rest } = o;
     if (SELF_KEY in o && !rowRef(__oqx_self))
         throw notAStoreRow(__oqx_self);
+    // The envelope keys lead; a user projection of `id`/`path` collapses onto
+    // them in place (the same value, read by the same attribute).
     return { id: String(__oqx_id), path: String(__oqx_path ?? ""), ...renderValue(rest) };
 }
 // Top-level `select distinct`: dedup hits by their USER projection (every field
-// except the injected id/path), keeping the first (so the retained hit carries a
-// real id/path). Order-preserving.
+// except the envelope's `id`/`path`), keeping the first (so the retained hit
+// carries a real identity). Order-preserving.
 function dedupHitsByProjection(hits) {
     const seen = new Set();
     const out = [];
@@ -248,6 +289,11 @@ function oqxRunInner(store, repoId, source, opts) {
     // the final page below and returned as `values` with `hits` empty.
     const topValues = parsed.values;
     const userSelect = topValues ? [{ ...parsed.select[0], name: VALUE_KEY }] : parsed.select;
+    if (!topValues) {
+        const collision = envelopeCollision(userSelect);
+        if (collision)
+            throw collision;
+    }
     // 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
@@ -302,9 +348,10 @@ 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 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
+// The collect page's keyset is (path, id) — the hit's `path`, so the reference
+// form (`/a.md`), and its `id`: the kernel's shared cursor encoding
+// (core/cursor.ts) with a two-part tuple of VALUES (no key names ride in it, so
+// a 2.x cursor stays valid on 3.0). 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).

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

@@ -9,13 +9,13 @@ export const ALIAS = {
     docs: { self: "d", doc: "d" },
     blocks: { self: "b", doc: "d" },
     nodes: { self: "n", doc: "d" },
-    edges: { self: "e", doc: "d" },
+    links: { 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",
+    links: "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). */
@@ -23,7 +23,7 @@ export const COLS = {
     docs: "d.*",
     blocks: "b.*, d.path AS __path",
     nodes: "n.*, d.path AS __path",
-    edges: "e.*, d.path AS __path",
+    links: "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
@@ -32,13 +32,13 @@ export const COLS = {
 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",
+    links: "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",
+    links: "d.path, e.edge_id",
 };
 /** The live-row and repository guards of a target scan. */
 export function guards(target, repoId) {
@@ -46,7 +46,7 @@ export function guards(target, repoId) {
         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] };
+        case "links": 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
@@ -56,7 +56,7 @@ 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] };
+        case "links": 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

@@ -1,6 +1,6 @@
 import type { Expr } from "@omgbase/oqx";
 /** SQL row domain, matching the store's tables. */
-export type Target = "docs" | "blocks" | "nodes" | "edges";
+export type Target = "docs" | "blocks" | "nodes" | "links";
 /** The SQL aliases the compiler assigned to the current scope's row (`self`) and
  * its owning document (`doc`). On the `docs` target the row IS the document, so
  * both are the same alias. */
@@ -24,7 +24,7 @@ export interface Frag {
  * decline (a)):
  *
  *   text  a string literal/binding, a text column or intrinsic, `.lower()`/`.upper()`
- *   int   an integer-typed intrinsic column (blocks `$ordinal`, `$depth`)
+ *   int   an integer-typed column (blocks `ordinal`, `depth`)
  *   num   a number literal/binding
  *   bool  a boolean literal/binding
  *   null  a null (or undefined) literal/binding
@@ -43,12 +43,16 @@ export interface Operand extends Frag {
         col: string;
         path: string;
     };
+    /** A property read: `docId` is the SQL expression naming the document whose
+     * rows are read (`d.doc_id` for the row's own document, `e.dst_node` for a
+     * link's destination). */
     prop?: {
-        docAlias: string;
+        docId: string;
         key: string;
+        source?: string;
     };
     value?: unknown;
-    /** The storage-form path column behind a `$path` / `doc.$path` read
+    /** 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`). */
@@ -66,10 +70,9 @@ export interface Operand extends Frag {
 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)). */
-export declare const RESERVED_DOC_BASENAMES: ReadonlySet<string>;
+/** The identity/bytes/time attributes per kind — the names `attributeSql` owns
+ * (the structural columns are handled per target in `translateOperand`). */
+export declare const ROW_ATTRIBUTES: Readonly<Record<Target, ReadonlySet<string>>>;
 /** Translate an expression used as a VALUE (comparison operand, method receiver,
  * function argument) to a SQL scalar with its operand kind. Returns null if not
  * faithfully translatable. */
@@ -100,7 +103,7 @@ export declare function translateValue(e: Expr, ctx: TranslateCtx): Frag | null;
  *     ordered, exactly as in memory.
  *   Every other pair declines: SQLite sees JSON `true` and `1`, `val_bool` and
  *     `val_num` alike (`$ordinal == checked`, `true == 1`), orders every
- *     integer before every text (`$ordinal < "3"`, `level < "x"`, `$path > 5`),
+ *     integer before every text (`$ordinal < "3"`, `level < "x"`, `path > 5`),
  *     and two JSON or property reads carry no type at plan time
  *     (`attrs.a == attrs.b`, `era == stages`).
  *