@omgbase/core 0.10.0 → 0.11.0

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

@@ -13,7 +13,7 @@
 //
 //   • oqx-js string ops are CASE-SENSITIVE, but SQLite `LIKE` is case-insensitive
 //     for ASCII. So `startsWith`/`contains`/`endsWith` translate to
-//     `substr`/`instr`, NEVER `LIKE`. `$path.lower().startsWith("lab/")` becomes
+//     `substr`/`instr`, NEVER `LIKE`. `path.lower().startsWith("lab/")` becomes
 //     `substr(lower(d.path), 1, length(?)) = ?` — the lowercasing is explicit and
 //     the match is byte-exact, matching the in-memory path.
 //   • oqx-js `==`/`!=` are absence-NORMALIZED (two absent values are equal;
@@ -27,8 +27,9 @@
 //     `card='scalar'` row (reads NULL). So a comparison is only pushed when the
 //     KINDS of its two operands are provably compared the same way — see
 //     `comparable` (the spec/surface §1 decline (a)) — and a name that is a relation, reach-through
-//     or source handle is never read as a property (decline (b),
-//     `NON_PROPERTY_NAMES`). A bool or num literal against a JSON or property
+//     or WHOLE source handle is never read as a property (decline (b),
+//     `NON_PROPERTY_NAMES`; a key read THROUGH a handle — `data.k`,
+//     `frontmatter.k` — is a property read, `handleRead`). A bool or num literal against a JSON or property
 //     read is a TYPED push (the 1.2 patch): the stored type is tested in SQL
 //     before the value (`json_type(x) = 'true'`, `p.type = 'number' AND
 //     p.val_num >= ?`) and the whole test is wrapped `(…) IS 1` / `IS NOT 1`,
@@ -52,94 +53,137 @@ import { TARGETS } from "../root-row.js";
  * `translate.test.ts` asserts this set against the store context.
  */
 export const NON_PROPERTY_NAMES = {
-    docs: new Set(["doc", "nodes", "blocks", "out", "in", "out_edges", "in_edges", "frontmatter", "inline"]),
-    blocks: new Set(["block", "doc", "children", "nodes", "out_edges", "section", "attrs"]),
+    docs: new Set(["doc", "nodes", "blocks", "out_links", "in_links", "data", "frontmatter", "inline"]),
+    blocks: new Set(["block", "doc", "children", "nodes", "out_links", "section", "attrs"]),
     nodes: new Set(["section", "doc", "block", "blocks", "subsections", "children", "attrs"]),
-    edges: new Set(["doc"]),
+    links: new Set(["doc", "dst"]),
 };
-// ---- intrinsics -------------------------------------------------------------
-// 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. `$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.
+// ---- engine attributes ------------------------------------------------------
+// The engine attributes (spec/surface §1.2, 3.0: bare, snake_case, winning on
+// collision — `id`, `path`, `raw`, `hash`, `updated_at` on docs and blocks,
+// `title`/`tags` on docs, `id`/`path` on nodes and edges) → a param-free SQL
+// scalar, per target, with its kind. The structural columns and foreign keys are
+// translated in `translateOperand`. Anything not mapped (`raw`, reconstructed or
+// a blob; `title`, computed; `tags`, the union of the authored list and the
+// computed hashtags) returns null → residual, and the caller must NOT fall
+// through to a property read of the same name (the attribute wins in memory).
+// `updated_at` is a correlated subquery. `path` (and the edge field `dst_path`)
+// is 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 attribute 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) {
+/** The identity/bytes/time attributes per kind — the names `attributeSql` owns
+ * (the structural columns are handled per target in `translateOperand`). */
+export const ROW_ATTRIBUTES = {
+    docs: new Set(["id", "path", "raw", "hash", "updated_at", "title", "tags"]),
+    blocks: new Set(["id", "path", "raw", "hash", "updated_at"]),
+    nodes: new Set(["id", "path"]),
+    links: new Set(["id", "path"]),
+};
+function attributeSql(name, ctx) {
     const { self, doc, target } = ctx;
     const text = (sql) => ({ sql, params: [], kind: "text" });
-    const int = (sql) => ({ sql, params: [], kind: "int" });
     if (target === "docs")
         switch (name) {
-            case "$id": return text(`${self}.doc_id`);
-            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)`);
+            case "id": return text(`${self}.doc_id`);
+            case "path": return pathColumn(`${doc}.path`);
+            case "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)`);
         }
     else if (target === "blocks")
         switch (name) {
-            case "$id": return text(`${self}.block_id`);
-            case "$doc": return text(`${self}.doc_id`);
-            case "$path": return pathColumn(`${doc}.path`);
-            case "$ordinal": return int(`${self}.ordinal`);
-            case "$depth": return int(`${self}.depth`);
-            case "$body": return text(`${self}.text`);
-            case "$content_hash": return text(`lower(hex(${self}.raw_hash))`);
+            case "id": return text(`${self}.block_id`);
+            case "path": return pathColumn(`${doc}.path`);
+            case "hash": return text(`lower(hex(${self}.raw_hash))`);
         }
     else if (target === "nodes")
         switch (name) {
-            case "$id":
-            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 pathColumn(`${doc}.path`);
+            case "id": return text(`${self}.node_id`);
+            case "path": return pathColumn(`${doc}.path`);
         }
-    else if (target === "edges")
+    else if (target === "links")
         switch (name) {
-            case "$id": return text(`${self}.edge_id`);
-            case "$src": return text(`${self}.src_doc`);
-            case "$dst": return text(`${self}.dst_node`);
-            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 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)`);
+            case "id": return text(`${self}.edge_id`);
+            case "path": return pathColumn(`${doc}.path`);
         }
     return null;
 }
-/** 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 const RESERVED_DOC_BASENAMES = new Set(["id", "path", "updated_at", "content_hash", "body"]);
+/** The links target's plain fields → the store's columns (spec/surface §1.2,
+ * 3.0: a foreign key is named for what it is, never `$`-prefixed). `dst_path`
+ * and `uri` are correlated subqueries; `dst_path` is the reference form. */
+function edgeField(name, self) {
+    const text = (sql) => ({ sql, params: [], kind: "text" });
+    switch (name) {
+        case "doc_id": return text(`${self}.src_doc`);
+        case "block_id": return text(`${self}.src_block`);
+        case "via_id": return text(`${self}.via_node`);
+        case "dst_id": return text(`${self}.dst_node`);
+        case "dst_path": return text(`(SELECT '/' || dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`);
+        case "uri": return text(`(SELECT xn.uri FROM external_nodes xn WHERE xn.node_id = ${self}.dst_node)`);
+        case "field": return text(`${self}.src_field`);
+        case "predicate":
+        case "provenance":
+        case "dst_kind":
+        case "anchor": return text(`${self}.${name}`);
+        default: return null;
+    }
+}
 const SEG = /^[A-Za-z_][A-Za-z0-9_]*$/; // injection-safe inlined identifier
 // The single-scalar-row scope of a document property (the CEL scalar-in-scope
 // rule): the row for `key` on the document only when the key has exactly one
 // row in scope and it is card='scalar' — a list-valued or nested key has none.
-// `select` is the projected expression over the alias `p`.
-function propSubquery(docAlias, key, select) {
+// `select` is the projected expression over the alias `p`. `source` narrows
+// the scope to one authored source — the read `frontmatter.<k>` / `inline.<k>`
+// performs (spec/surface §1.2; the in-memory `docProp(docId, key, source)`):
+// both the row and the count are of that source's rows only. The merged
+// `data.<k>` read is the bare read, so it passes no source. `docId` is the SQL
+// expression naming the document: the scan's `d.doc_id`, or a link's
+// `e.dst_node` for a `dst.<k>` read (the destination's rows by its id — a
+// non-document or phantom destination has none, so the read is NULL exactly
+// where `dst` is absent in memory).
+function propSubquery(docId, key, select, source) {
+    const src = source ? ` AND p.source = '${source}'` : "";
+    const src2 = source ? ` AND p2.source = '${source}'` : "";
     return `(SELECT ${select} FROM properties p
-           WHERE p.doc_id = ${docAlias}.doc_id AND p.key = '${key}' AND p.card = 'scalar' AND p.deleted_commit IS NULL
-             AND (SELECT COUNT(*) FROM properties p2 WHERE p2.doc_id = ${docAlias}.doc_id AND p2.key = '${key}' AND p2.deleted_commit IS NULL) = 1
+           WHERE p.doc_id = ${docId} AND p.key = '${key}' AND p.card = 'scalar' AND p.deleted_commit IS NULL${src}
+             AND (SELECT COUNT(*) FROM properties p2 WHERE p2.doc_id = ${docId} AND p2.key = '${key}' AND p2.deleted_commit IS NULL${src2}) = 1
            LIMIT 1)`;
 }
 // A single-valued document property: the scalar value of its one row in scope,
 // else NULL — matching the store context's `docProp` for a scalar read.
-function propScalar(docAlias, key) {
+// `docAlias` is the document's table alias; `propScalarOf` takes the id
+// expression itself.
+function propScalar(docAlias, key, source) {
+    return propScalarOf(`${docAlias}.doc_id`, key, source);
+}
+function propScalarOf(docId, key, source) {
     if (!SEG.test(key))
         return null;
     return {
-        sql: propSubquery(docAlias, key, "COALESCE(p.val_text, p.val_num, p.val_bool)"),
+        sql: propSubquery(docId, key, "COALESCE(p.val_text, p.val_num, p.val_bool)", source),
         params: [],
         kind: "prop",
-        prop: { docAlias, key },
+        prop: source ? { docId, key, source } : { docId, key },
     };
 }
+// A key read through a source handle (spec/surface §1.2, 3.0): `data.<k>` is
+// the merged authored read — exactly the bare property `<k>`; `frontmatter.<k>`
+// / `inline.<k>` the same read scoped to one source. Pushed since 3.0 (batch 3;
+// before, every handle member was residual). A whole-handle reference
+// (`frontmatter == null`) and `entries(<handle>)` still decline.
+const SOURCE_HANDLES = { data: undefined, frontmatter: "frontmatter", inline: "inline" };
+function handleRead(docAlias, handle, key) {
+    return handleReadOf(`${docAlias}.doc_id`, handle, key);
+}
+function handleReadOf(docId, handle, key) {
+    if (!(handle in SOURCE_HANDLES))
+        return null;
+    return propScalarOf(docId, key, SOURCE_HANDLES[handle]);
+}
 // json_extract path from validated segments, or null if any segment is unsafe.
 function jsonExtract(col, segs) {
     if (segs.some((s) => !SEG.test(s)))
@@ -184,8 +228,14 @@ export function translateOperand(e, ctx) {
         case "binding":
             return constOperand(ctx.params[e.index]);
         case "ident": {
+            // An OQX `$` name (`$it`, `$key`, the follow intrinsics) is the language's,
+            // never a column; omgbase adds no `$` names (spec/surface §1.2, 3.0).
             if (e.name.startsWith("$"))
-                return intrinsicSql(e.name, ctx);
+                return null;
+            // The row's own attributes win on collision (§1.2): translated or declined
+            // (`raw`, `title`, `tags`), never read as a property or an attr.
+            if (ROW_ATTRIBUTES[target].has(e.name))
+                return attributeSql(e.name, ctx);
             // A relation, reach-through, source handle or the whole attrs object is not a
             // scalar read (decline (b)); a bare target name is a relation or a loud
             // error (root-row.ts), never a property.
@@ -195,28 +245,25 @@ export function translateOperand(e, ctx) {
             if (target === "docs") {
                 if (e.name === "format")
                     return text(`${self}.format`); // a column, not a property
-                if (RESERVED_DOC_BASENAMES.has(e.name))
-                    return null; // residual raises the guard
                 return propScalar(doc, e.name);
             }
             if (target === "blocks") {
-                if (e.name === "type" || e.name === "text")
+                if (e.name === "doc_id" || e.name === "type" || e.name === "text")
                     return text(`${self}.${e.name}`);
+                if (e.name === "ordinal" || e.name === "depth")
+                    return { sql: `${self}.${e.name}`, params: [], kind: "int" };
                 // Bare non-structural identifier flattens into attrs — same pushdown as
                 // the `attrs.<k>` member form (json_extract), so `checked` == `attrs.checked`.
                 return jsonExtract(`${self}.attrs`, [e.name]);
             }
             if (target === "nodes") {
-                if (e.name === "kind" || e.name === "name" || e.name === "value")
+                if (["doc_id", "block_id", "kind", "name", "value"].includes(e.name))
                     return text(`${self}.${e.name}`);
                 // Bare non-structural identifier flattens into attrs (see blocks above).
                 return jsonExtract(`${self}.attrs`, [e.name]);
             }
-            if (target === "edges") {
-                if (["predicate", "provenance", "dst_kind", "anchor", "src_field"].includes(e.name))
-                    return text(`${self}.${e.name}`);
-                return null;
-            }
+            if (target === "links")
+                return edgeField(e.name, self);
             return null;
         }
         case "member": {
@@ -228,27 +275,88 @@ export function translateOperand(e, ctx) {
             if (head === "attrs" && (target === "blocks" || target === "nodes")) {
                 return jsonExtract(`${self}.attrs`, rest);
             }
+            // <handle>.<k> on docs — `data.layer`, `frontmatter.layer`, `inline.element`
+            // — and `doc.<handle>.<k>` through the owning document on the other
+            // targets: a property read, scoped to the handle's source.
+            if (target === "docs" && head in SOURCE_HANDLES && rest.length === 1)
+                return handleRead(doc, head, rest[0]);
+            if (head === "doc" && rest.length === 2 && rest[0] in SOURCE_HANDLES)
+                return handleRead(doc, rest[0], rest[1]);
             // doc.<x> reach-through — the owning doc (alias `doc`, which is `d`). On the
             // docs target `doc` is the row itself; either way it resolves against `doc`.
+            // FOREIGN-KEY ELIMINATION (spec/surface §1, 3.0): `doc.id` is the row's
+            // own FK column (`b.doc_id`, `n.doc_id`, `e.src_doc`) and `doc.path` /
+            // `doc.hash` / `doc.updated_at` the scan's already-joined document
+            // columns — no extra join, the same SQL as the bare `doc_id`.
             if (head === "doc") {
                 if (rest.length !== 1)
                     return null;
                 const k = rest[0];
-                if (k === "$path")
+                if (k === "id")
+                    return text(target === "links" ? `${self}.src_doc` : `${self}.doc_id`);
+                if (k === "path")
                     return pathColumn(`${doc}.path`);
+                if (k === "hash")
+                    return text(`lower(hex(${doc}.file_hash))`);
+                if (k === "updated_at")
+                    return text(`(SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ${doc}.current_rev)`);
                 if (k === "format")
                     return text(`${doc}.format`);
                 if (k.startsWith("$"))
                     return null;
-                if (RESERVED_DOC_BASENAMES.has(k))
-                    return null;
+                if (ROW_ATTRIBUTES.docs.has(k))
+                    return null; // `doc.raw`, `doc.title`, `doc.tags`: the attribute, not pushable
                 if (NON_PROPERTY_NAMES.docs.has(k) || TARGETS.has(k))
-                    return null; // `doc.nodes`, `doc.frontmatter`, `doc.docs` … (decline (b))
+                    return null; // `doc.nodes`, `doc.data`, `doc.docs` … (decline (b))
                 return propScalar(doc, k);
             }
-            // block.type / block.text reach-through from a node.
-            if (head === "block" && target === "nodes" && rest.length === 1 && (rest[0] === "type" || rest[0] === "text")) {
-                return text(`(SELECT bb.${rest[0]} FROM blocks bb WHERE bb.block_id = ${self}.block_id)`);
+            // dst.<x> reach-through from a link (spec/surface §1.2, 3.0 follow-up): the
+            // destination DOCUMENT, keyed by the row's own `dst_node` — the lookup
+            // `dst_path` already runs. A property read scopes `properties` by
+            // `e.dst_node` directly; the document's own columns are a primary-key
+            // probe `(SELECT … FROM docs dd WHERE dd.doc_id = e.dst_node)` — NULL
+            // wherever `dst` is absent in memory (a block or external destination, a
+            // phantom). `dst.raw` / `dst.title` / `dst.tags` and the relations stay
+            // residual, as `doc.*`'s do.
+            if (head === "dst" && target === "links") {
+                const dstId = `${self}.dst_node`;
+                if (rest.length === 2 && rest[0] in SOURCE_HANDLES)
+                    return handleReadOf(dstId, rest[0], rest[1]);
+                if (rest.length !== 1)
+                    return null;
+                const k = rest[0];
+                const probe = (col) => text(`(SELECT ${col} FROM docs dd WHERE dd.doc_id = ${dstId})`);
+                if (k === "id")
+                    return probe("dd.doc_id");
+                if (k === "path")
+                    return probe("'/' || dd.path");
+                if (k === "hash")
+                    return probe("lower(hex(dd.file_hash))");
+                if (k === "updated_at")
+                    return probe("(SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = dd.current_rev)");
+                if (k === "format")
+                    return probe("dd.format");
+                if (k.startsWith("$"))
+                    return null;
+                if (ROW_ATTRIBUTES.docs.has(k) || NON_PROPERTY_NAMES.docs.has(k) || TARGETS.has(k))
+                    return null;
+                return propScalarOf(dstId, k);
+            }
+            // block.<x> reach-through from a node: the block's identity is the node's
+            // FK (`block.id` → `n.block_id`, `block.path` → the joined `d.path`,
+            // `block.doc_id` → `n.doc_id` — FK elimination again); `type`/`text` are
+            // a correlated read of the block row.
+            if (head === "block" && target === "nodes" && rest.length === 1) {
+                const k = rest[0];
+                if (k === "id")
+                    return text(`${self}.block_id`);
+                if (k === "path")
+                    return pathColumn(`${doc}.path`);
+                if (k === "doc_id")
+                    return text(`${self}.doc_id`);
+                if (k === "type" || k === "text")
+                    return text(`(SELECT bb.${k} FROM blocks bb WHERE bb.block_id = ${self}.block_id)`);
+                return null;
             }
             return null;
         }
@@ -305,7 +413,7 @@ const IS_OP = {
  *     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`).
  *
@@ -402,7 +510,7 @@ function translateComparison(e, ctx) {
 }
 const FLIP = { "<": ">", "<=": ">=", ">": "<", ">=": "<=" };
 /**
- * The path equality fast path: `$path == "/a.md"` (or `!=`, either side) against
+ * 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
@@ -455,9 +563,9 @@ function typedComparison(op, read, constant) {
         };
     }
     if (read.prop) {
-        const { docAlias, key } = read.prop;
+        const { docId, key, source } = read.prop;
         const test = constant.kind === "bool" ? `p.type = 'bool' AND p.val_bool = ?` : `p.type = 'number' AND p.val_num ${cmp} ?`;
-        return { sql: `(${propSubquery(docAlias, key, test)} ${wrap})`, params: [...constant.params] };
+        return { sql: `(${propSubquery(docId, key, test, source)} ${wrap})`, params: [...constant.params] };
     }
     return null;
 }

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

@@ -14,7 +14,7 @@ export interface StoreIndexDeps {
 }
 /** 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`, …). */
+ * multi-segment paths; `format`, edge `predicate`/`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[];

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

@@ -1,8 +1,8 @@
 // Store-backed equality indexes for the OQX engine (`DataContext.indexFor`):
-// when a nested block's receiver is a ROOT SCAN (`^docs`, `^edges`,
+// when a nested block's receiver is a ROOT SCAN (`^docs`, `^links`,
 // a bare `docs` at the root scope) and its correlated or constant equality is on
-// a column or property SQLite can look up — `where $path == ^^$path`,
-// `where customer == ^$path`, `where $dst == ^$id`, `where type == "order"` —
+// a column or property SQLite can look up — `where path == ^^path`,
+// `where customer == ^path`, `where dst_id == ^id`, `where type == "order"` —
 // the probe runs ONE prepared statement against the store's indexes instead of
 // materializing every row of the target and hashing it. The rows come back
 // exactly as the root scan constructs them (same columns, same `__path`, same
@@ -12,12 +12,12 @@
 //
 // Typed equality (OQX SEMANTICS §5) is preserved by probing per VALUE KIND:
 //
-//   • a text column (`doc_id`, `path`, `type`, `kind`, `name`, `src_doc`, …)
+//   • a text column (`id`, `path`, `type`, `kind`, `name`, `doc_id`, `dst_id`, …)
 //     matches a string probe by `= ?` (TEXT = TEXT, exact); a number, boolean,
 //     object or any other non-string probe matches NO row (the column holds
 //     strings or NULL and `5 == "5"` is false); an absent probe (`null`,
 //     `undefined`: `name == null`) is answered by the in-memory fallback below;
-//   • a document property (`customer`, `$title`) matches a string probe only on
+//   • a document property (`customer`, `title`) matches a string probe only on
 //     a `type = 'string'` row (`val_text = ?`), a number probe only on a
 //     `type = 'number'` row (`val_num = ?`), a boolean only on a `type = 'bool'`
 //     row (`val_bool = ?`), each under the scalar-in-scope rule the in-memory
@@ -38,7 +38,7 @@
 // contract but the engine never calls it for these indexes: it probes
 // `lookupRows` first and so never reads the root whole.
 import { semantics } from "@omgbase/oqx";
-import { NON_PROPERTY_NAMES, RESERVED_DOC_BASENAMES } from "./sql/translate.js";
+import { NON_PROPERTY_NAMES, ROW_ATTRIBUTES } from "./sql/translate.js";
 import { COLS, FROM, FROM_BY_DOC, ORDER, guards, guardsByDoc } from "./sql/scan.js";
 import { storagePath } from "../core/paths.js";
 // ---- which paths SQLite answers ------------------------------------------------
@@ -49,19 +49,19 @@ import { storagePath } from "../core/paths.js";
  * `block_id` (PK), `idx_blocks_doc (doc_id, …)`, `idx_blocks_type (repo_id,
  * type)`; nodes `node_id` (PK), `idx_nodes_doc`, `idx_nodes_kind`,
  * `idx_nodes_name`; edges `edge_id` (PK), `idx_edges_src (src_doc, …)`,
- * `idx_edges_dst (dst_node, …)`; `$path` on a joined target reaches the docs
+ * `idx_edges_dst (dst_node, …)`; `path` on a joined target reaches the docs
  * `(repo_id, path)` key and then the target's `doc_id`/`src_doc` index. */
 const COLUMN_PROBES = {
-    docs: { $id: "d.doc_id = ?", $path: "d.path = ?" },
-    blocks: { $id: "b.block_id = ?", $doc: "b.doc_id = ?", type: "b.type = ?", $path: "d.path = ?" },
-    nodes: { $id: "n.node_id = ?", $node_id: "n.node_id = ?", $doc_id: "n.doc_id = ?", kind: "n.kind = ?", name: "n.name = ?", $path: "d.path = ?" },
-    edges: {
-        $id: "e.edge_id = ?", $src: "e.src_doc = ?", $dst: "e.dst_node = ?", $path: "d.path = ?",
-        // `$dst_path` is the destination document's path (deleted or not — the
-        // intrinsic reads `docs` by id without a liveness guard). A destination is
+    docs: { id: "d.doc_id = ?", path: "d.path = ?" },
+    blocks: { id: "b.block_id = ?", doc_id: "b.doc_id = ?", type: "b.type = ?", path: "d.path = ?" },
+    nodes: { id: "n.node_id = ?", doc_id: "n.doc_id = ?", kind: "n.kind = ?", name: "n.name = ?", path: "d.path = ?" },
+    links: {
+        id: "e.edge_id = ?", doc_id: "e.src_doc = ?", dst_id: "e.dst_node = ?", path: "d.path = ?",
+        // `dst_path` is the destination document's path (deleted or not — the
+        // field reads `docs` by id without a liveness guard). A destination is
         // resolved within the edge's repo (spec/graph §3), where `(repo_id, path)`
         // is UNIQUE, so the probe is that one document; `?r` is the repo id.
-        $dst_path: "e.dst_node IN (SELECT doc_id FROM docs WHERE repo_id = ?r AND path = ?)",
+        dst_path: "e.dst_node IN (SELECT doc_id FROM docs WHERE repo_id = ?r AND path = ?)",
     },
 };
 /** How a one-segment path on `target` is probed, or null when SQLite has no
@@ -76,14 +76,16 @@ function probeFor(target, path) {
     if (target !== "docs")
         return null;
     // A docs property: any bare name the context reads through `docProp` — not a
-    // relation / handle (`out`, `frontmatter`, …), not a reserved basename (a loud
-    // error in memory, left to the scan to raise), not the `format` column (not
-    // indexed), and of the intrinsics only `$title` (a computed scalar property).
-    if (key === "$title")
+    // relation / handle (`out_links`, `data`, `frontmatter`, …), not the `format` column
+    // (not indexed), not an OQX `$` name, and of the engine attributes only
+    // `title` (the computed `$title` row, a scalar property the author's `title:`
+    // never reaches — `data.title` does): `raw`, `hash`, `updated_at` and `tags`
+    // (authored ∪ hashtags) have no index and are never property probes.
+    if (key === "title")
         return { kind: "property", key: "$title", source: "computed" };
     if (key.startsWith("$") || key === "format")
         return null;
-    if (NON_PROPERTY_NAMES.docs.has(key) || RESERVED_DOC_BASENAMES.has(key))
+    if (NON_PROPERTY_NAMES.docs.has(key) || ROW_ATTRIBUTES.docs.has(key))
         return null;
     return { kind: "property", key, source: null };
 }
@@ -108,10 +110,10 @@ class StoreIndex {
         if (this.probe.kind === "column") {
             if (typeof v !== "string")
                 return [];
-            // `$path` / `$dst_path` are the reference form in memory (`/a.md`,
+            // `path` / `dst_path` are the reference form in memory (`/a.md`,
             // spec/surface §1 "Paths"); the column holds the storage form. A rooted
             // probe is de-rooted; a bare one can equal no rooted path — no row.
-            if (this.path === "$path" || this.path === "$dst_path")
+            if (this.path === "path" || this.path === "dst_path")
                 return v.startsWith("/") ? this.column(storagePath(v)) : [];
             return this.column(v);
         }
@@ -135,13 +137,13 @@ class StoreIndex {
         }
         return out.sort((a, b) => a - b);
     }
-    // A `$path` probe on a joined target drives from the document (`FROM_BY_DOC`),
+    // A `path` probe on a joined target drives from the document (`FROM_BY_DOC`),
     // every other column probe from the target's own index. `?r` in a probe is
     // the repo id, bound ahead of the value.
     column(value) {
         const t = this.target;
         const probe = this.probe.sql;
-        const byDoc = t !== "docs" && this.path === "$path";
+        const byDoc = t !== "docs" && this.path === "path";
         const g = byDoc ? guardsByDoc(t, this.deps.repoId) : guards(t, this.deps.repoId);
         const from = byDoc ? FROM_BY_DOC[t] : FROM[t];
         const params = probe.includes("?r") ? [this.deps.repoId, value] : [value];
@@ -180,7 +182,7 @@ class StoreIndex {
 }
 /** 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`, …). */
+ * multi-segment paths; `format`, edge `predicate`/`field`, `tags`, …). */
 export function storeIndexFor(target, path, deps) {
     const probe = probeFor(target, path);
     return probe ? new StoreIndex(target, path[0], probe, deps) : undefined;
@@ -188,6 +190,6 @@ export function storeIndexFor(target, path, deps) {
 /** The paths `storeIndexFor` answers from SQLite, per target (for tests and docs). */
 export function indexablePaths(target) {
     const cols = Object.keys(COLUMN_PROBES[target]);
-    return target === "docs" ? [...cols, "$title", "<property key>"] : cols;
+    return target === "docs" ? [...cols, "title", "<property key>"] : cols;
 }
 //# sourceMappingURL=store-index.js.map

package/dist/src/search/cel/ast.d.ts

@@ -61,7 +61,7 @@ export interface Quantifier {
     varName: string;
     predicate: Node;
 }
-/** dotted field path; `$` set when intrinsic ($id, $path, doc.$path handled by segments) */
+/** dotted field path; `$` set when intrinsic (id, path, doc.path handled by segments) */
 export interface FieldRef {
     kind: "field";
     segments: string[];

package/dist/src/search/cel/compile.d.ts

@@ -1,5 +1,5 @@
 import type { Node } from "./ast.js";
-export type Target = "docs" | "blocks" | "nodes" | "edges";
+export type Target = "docs" | "blocks" | "nodes" | "links";
 export interface AliasCtx {
     self: string;
     doc: string;