@omgbase/core 0.10.0 → 0.11.0

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

@@ -37,11 +37,44 @@ function tagAll(rows, t) {
         r[TARGET] = t;
     return rows;
 }
-// docs intrinsics whose BARE (non-$) form is almost always a typo (10 §2); a bare
-// read of one is a loud error, matching the CEL guard. (A bare target name —
-// `docs`, `edges`, … — is a loud error of its own, root-row.ts; `repo` is just an
-// ordinary frontmatter key.)
-const RESERVED_DOC_BASENAMES = new Set(["id", "path", "updated_at", "content_hash", "body"]);
+// THE NAME RULE (spec/surface §1.2, 3.0). `$` belongs to OQX: `$it`, `$key`,
+// `$depth`, `$stop`, `$leaf`, `$frontier`, `$ordinal` are values the LANGUAGE
+// injects into a scope; omgbase adds no `$` names. Every engine attribute is a
+// bare snake_case name that WINS on collision — the convention the relations
+// (`children`, `blocks`, `out_links`, `doc`, `frontmatter`, …) always followed:
+// a bare name that is an engine attribute reads the engine's value, never the
+// author's. The attributes: every row's `id`/`path`; docs' and blocks' `raw`/
+// `hash`/`updated_at`; docs' `title` (the computed title) and `tags` (authored
+// tags ∪ body hashtags) and `format`; a foreign key named for what it is
+// (`doc_id`, `block_id`, `via_id`, `dst_id`, `dst_path`, `uri`), a column its
+// column (`type`, `text`, `depth`, `ordinal`, `kind`, `predicate`, `field`).
+// User data is bare too, read by any non-colliding key; where it collides it is
+// reached through a source handle — `data` (the merged authored view:
+// frontmatter + inline by the property rule, exactly the read a bare
+// non-colliding key performs), `frontmatter`, `inline` — so `data.path` is the
+// author's `path:` key, `data.tags` the authored list alone, `data.title` the
+// authored title. There is no loud-error set: a bare `id`/`path`/`updated_at`/
+// `hash`/`raw` is simply the engine's attribute (before this batch of 3.0 the
+// attributes were `$`-prefixed and the bare spelling was an error, §9). A bare
+// target name — `docs`, `links`, … — is a loud error of its own (root-row.ts).
+const DOC_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "title", "tags", "format"]);
+const BLOCK_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "doc_id", "type", "text", "attrs", "depth", "ordinal"]);
+const NODE_ATTRIBUTES = new Set(["id", "path", "doc_id", "block_id", "kind", "name", "value", "attrs"]);
+const EDGE_ATTRIBUTES = new Set(["id", "path", "doc_id", "block_id", "via_id", "dst_id", "dst_path", "uri", "field", "dst_kind", "predicate", "provenance", "anchor"]);
+/** The engine attributes per kind (spec/surface §1.2 table). Exported so the
+ * translator's tests pin the two against each other. */
+export const ATTRIBUTES = {
+    docs: DOC_ATTRIBUTES, blocks: BLOCK_ATTRIBUTES, nodes: NODE_ATTRIBUTES, links: EDGE_ATTRIBUTES,
+};
+/** The source handles of a document (§1.2): `data` is the merged authored view
+ * (frontmatter + inline), the other two one source each. */
+export const SOURCE_HANDLES = new Set(["data", "frontmatter", "inline"]);
+/** The value of a statically SINGLE relation that has no row — `dst` on an
+ * external or dangling link, `block` on a node without one (oqx 0.20, SEMANTICS
+ * §3): an object the engine treats as one row with no rows, so `dst { title }`
+ * is absent rather than `[]`, while as a VALUE it is absent (`materialize`),
+ * so `dst == null`, `has(dst)` and `dst.title` read as before. */
+export const ABSENT_SINGLE = Object.freeze({});
 export function makeStoreContext(store, repoId, opts = {}) {
     const db = store.db;
     const sv = opts.semanticVectors;
@@ -63,7 +96,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
     // iteration, indexing, `length`, rendering all see a plain array of tagged
     // rows) that runs its SELECT on first use. The engine's optimizer asks
     // `indexFor` about a nested block's receiver BEFORE reading it, so a
-    // correlated probe on `^docs` / `^edges` / … is answered from the
+    // correlated probe on `^docs` / `^links` / … is answered from the
     // store's indexes (store-index.ts) and the scan never runs; anything else
     // (a top-level `from docs`, a `count { }`, a non-indexable path) reads it
     // whole exactly as before. One handle per target per context: a context lives
@@ -106,19 +139,19 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return proxy;
     };
     const rootFns = {
-        docs: () => lazyRoot("docs"), blocks: () => lazyRoot("blocks"), nodes: () => lazyRoot("nodes"), edges: () => lazyRoot("edges"),
+        docs: () => lazyRoot("docs"), blocks: () => lazyRoot("blocks"), nodes: () => lazyRoot("nodes"), links: () => lazyRoot("links"),
     };
     // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18 `rootObject`): the
     // repository, reached as `^$it` from a top-level row (`0^$it` from any depth).
     // Its own enumerable keys are the four collections — lazy getters, so
     // `entries(^$it)` names them without running a scan and `^$it.docs` is the
-    // same handle as `^docs` — and `get` answers `$id` with the repository id (an
-    // intrinsic, not an entry). Tagged so `get` recognizes it.
+    // same handle as `^docs` — and `get` answers `id` with the repository id (an
+    // attribute, not an entry). Tagged so `get` recognizes it.
     const rootRow = Object.defineProperties({ [ROOT_ROW]: true }, {
         docs: { enumerable: true, get: () => lazyRoot("docs") },
         blocks: { enumerable: true, get: () => lazyRoot("blocks") },
         nodes: { enumerable: true, get: () => lazyRoot("nodes") },
-        edges: { enumerable: true, get: () => lazyRoot("edges") },
+        links: { enumerable: true, get: () => lazyRoot("links") },
     });
     // ---- attrs / property decoding --------------------------------------------
     const parseJson = (v) => {
@@ -165,14 +198,18 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return decodeProp(rows[0]);
         return rows.map(decodeProp);
     };
-    // All of a doc's properties from one source (`frontmatter` / `inline`) as OQX
-    // entries, for `entries(frontmatter)`: one entry per TOP-LEVEL key, valued by
+    // All of a doc's authored properties as OQX entries, for `entries(frontmatter)`
+    // / `entries(inline)` / `entries(data)`: one entry per TOP-LEVEL key, valued by
     // the same scalar-vs-list rule as a bare read (`docProp`), with flattened dotted
-    // keys (`logging.level`) folded back into one nested entry. Keys come in the
-    // properties table's deterministic order — by key — because authored key
-    // position is not indexed (`ord` is the position WITHIN a list-valued key).
+    // keys (`logging.level`) folded back into one nested entry. `data` (source
+    // null) is frontmatter ∪ inline — the keys deduped, each valued by the merged
+    // read. Keys come in the properties table's deterministic order — by key —
+    // because authored key position is not indexed (`ord` is the position WITHIN
+    // a list-valued key).
     const docPropEntries = (docId, source) => {
-        const keys = all(`SELECT DISTINCT key FROM properties WHERE doc_id = ? AND source = ? AND deleted_commit IS NULL ORDER BY key`, docId, source).map((r) => String(r.key));
+        const keys = (source
+            ? all(`SELECT DISTINCT key FROM properties WHERE doc_id = ? AND source = ? AND deleted_commit IS NULL ORDER BY key`, docId, source)
+            : all(`SELECT DISTINCT key FROM properties WHERE doc_id = ? AND source IN ('frontmatter', 'inline') AND deleted_commit IS NULL ORDER BY key`, docId)).map((r) => String(r.key));
         const tops = [];
         const seen = new Set();
         for (const k of keys) {
@@ -182,7 +219,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 tops.push(top);
             }
         }
-        return tops.map((t) => semantics.makeEntry(t, docProp(docId, t, source)));
+        return tops.map((t) => semantics.makeEntry(t, docProp(docId, t, source ?? undefined)));
     };
     // Reconstruct a nested object from flattened dotted keys under `prefix.`
     // (undefined when there are none). Leaves are decoded property values.
@@ -261,18 +298,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
         docs: {
             nodes: (r) => docNodesInOrder(r.doc_id, r.path),
             blocks: (r) => tagAll(docBlocksPreorder(r.doc_id, r.path).map((x) => x.row), "blocks"),
-            out: (r) => tagAll(all(`SELECT DISTINCT d2.* FROM docs d2 JOIN edges e ON e.dst_node = d2.doc_id
-         WHERE e.src_doc = ? AND e.to_commit IS NULL AND d2.repo_id = ? AND d2.deleted_commit IS NULL ORDER BY d2.path, d2.doc_id`, r.doc_id, repoId), "docs"),
-            in: (r) => tagAll(all(`SELECT DISTINCT d2.* FROM docs d2 JOIN edges e ON e.src_doc = d2.doc_id
-         WHERE e.dst_node = ? AND e.to_commit IS NULL AND d2.repo_id = ? AND d2.deleted_commit IS NULL ORDER BY d2.path, d2.doc_id`, r.doc_id, repoId), "docs"),
-            out_edges: (r) => tagAll(all(`SELECT e.*, ? AS __path FROM edges e WHERE e.src_doc = ? AND e.to_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.path, r.doc_id), "edges"),
-            in_edges: (r) => tagAll(all(`SELECT e.*, d.path AS __path FROM edges e JOIN docs d ON d.doc_id = e.src_doc
-         WHERE e.dst_node = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.doc_id), "edges"),
+            // The linked / linking DOCUMENTS are reached through the link rows (3.0
+            // follow-up, §9: the `out` / `in` relations are gone): `out_links collect
+            // distinct { from dst }` and `in_links collect distinct { from doc }`.
+            out_links: (r) => tagAll(all(`SELECT e.*, ? AS __path FROM edges e WHERE e.src_doc = ? AND e.to_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.path, r.doc_id), "links"),
+            in_links: (r) => tagAll(all(`SELECT e.*, d.path AS __path FROM edges e JOIN docs d ON d.doc_id = e.src_doc
+         WHERE e.dst_node = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.doc_id), "links"),
         },
         blocks: {
             children: (r) => tagAll(all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.parent_block = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, r.__path, r.block_id), "blocks"),
             nodes: (r) => tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.block_id = ? ORDER BY n.span_start, n.node_id`, r.__path, r.block_id), "nodes"),
-            out_edges: (r) => tagAll(all(`SELECT e.*, ? AS __path FROM edges e WHERE e.src_block = ? AND e.to_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.__path, r.block_id), "edges"),
+            out_links: (r) => tagAll(all(`SELECT e.*, ? AS __path FROM edges e WHERE e.src_block = ? AND e.to_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.__path, r.block_id), "links"),
             // enclosing section node(s): md:section whose range contains this block's top ordinal.
             section: (r) => {
                 const top = topOrdinal(r);
@@ -314,89 +350,193 @@ export function makeStoreContext(store, repoId, opts = {}) {
            ORDER BY json_extract(i.attrs,'$.first_ordinal'), i.node_id`, r.__path, r.doc_id, lvl, f, l, lvl), "nodes");
             },
         },
-        edges: {},
+        links: {},
     };
     const jattr = (row, k) => {
         const a = row.attrs;
         const o = typeof a === "string" ? parseJson(a) : a;
         return o && typeof o === "object" ? o[k] : undefined;
     };
-    // owning-entity reach-through (single row).
-    const owningDoc = (row) => tag(one(`SELECT * FROM docs WHERE doc_id = ?`, row.doc_id ?? row.src_doc), "docs");
-    const owningBlock = (row) => row.block_id
-        ? tag(one(`SELECT b.*, d.path AS __path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ?`, row.block_id), "blocks")
-        : undefined;
-    // ---- intrinsics ($-fields) ------------------------------------------------
-    // `$path` / `$dst_path` are the REFERENCE form (`/a/b.md`, spec/surface §1
-    // "Paths", 2.0): the rows carry the storage form (`path`, the `__path` join
-    // column) and the intrinsic roots it on read, so nothing below the binding
+    // Owning-entity reach-through (single row) with FOREIGN-KEY ELIMINATION
+    // (spec/surface §1, 3.0): the owner is handed out as a LAZY row whose identity
+    // columns are already known from the child — a block's/node's `doc_id` and
+    // `__path` name its document, an edge's `src_doc` and `__path` its source doc,
+    // a node's `block_id` (+ `doc_id`, `__path`) its block — so `doc.id` and
+    // `doc.path` (and `block.id`/`block.path`/`block.doc_id` on a node) read
+    // those columns and run NO statement, exactly like the bare `doc_id`; the full
+    // owner row is loaded on the first read of anything else (`doc.layer`,
+    // `block.text`). The translator mirrors this in SQL (`doc.id` → the FK
+    // column). A Proxy over the backing object so the engine sees a plain tagged
+    // row either way (indexing, rendering, `rowRef`).
+    const lazyOwner = (known, t, load) => {
+        const backing = tag({ ...known }, t);
+        const knownKeys = new Set(Object.keys(known));
+        let filled = false;
+        const fill = () => {
+            if (filled)
+                return;
+            filled = true;
+            const full = load();
+            if (full)
+                Object.assign(backing, full);
+        };
+        // Only an unknown STRING key is a column read worth the load: symbols (the
+        // target tag, the context's own row markers, `Symbol.iterator` probes) are
+        // never store columns.
+        const loads = (prop) => typeof prop === "string" && !knownKeys.has(prop);
+        const proxy = new Proxy(backing, {
+            get(target, prop, receiver) {
+                if (loads(prop))
+                    fill();
+                return Reflect.get(target, prop, receiver);
+            },
+            has(target, prop) { if (loads(prop))
+                fill(); return Reflect.has(target, prop); },
+            ownKeys(target) { fill(); return Reflect.ownKeys(target); },
+            getOwnPropertyDescriptor(target, prop) { if (loads(prop))
+                fill(); return Reflect.getOwnPropertyDescriptor(target, prop); },
+        });
+        return proxy;
+    };
+    const owningDoc = (row) => {
+        const id = row.doc_id ?? row.src_doc;
+        if (id == null)
+            return undefined;
+        const path = row.__path;
+        if (typeof path !== "string")
+            return tag(one(`SELECT * FROM docs WHERE doc_id = ?`, id), "docs");
+        return lazyOwner({ doc_id: id, path }, "docs", () => one(`SELECT * FROM docs WHERE doc_id = ?`, id));
+    };
+    // `dst` on a link row (spec/surface §1.2, 3.0 follow-up): the destination
+    // DOCUMENT row when the link points at one (`dst_kind == "document"` and the
+    // document exists — a phantom target has the kind and no row), read by
+    // `dst_id` exactly as `dst_path` is; absent for a `block` or `external`
+    // destination (never reached into). `doc` stays the source document.
+    const destinationDoc = (row) => {
+        if (row.dst_kind !== "document")
+            return undefined;
+        return tag(one(`SELECT * FROM docs WHERE doc_id = ?`, row.dst_node), "docs");
+    };
+    const owningBlock = (row) => {
+        if (!row.block_id)
+            return undefined;
+        const load = () => one(`SELECT b.*, d.path AS __path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ?`, row.block_id);
+        if (typeof row.__path !== "string")
+            return tag(load(), "blocks");
+        return lazyOwner({ block_id: row.block_id, doc_id: row.doc_id, __path: row.__path }, "blocks", load);
+    };
+    // ---- engine attributes -----------------------------------------------------
+    // Bare, snake_case, winning on collision (see the name rule above; spec/surface
+    // §1.2, 3.0). `path` (and the edge field `dst_path`) is the REFERENCE form
+    // (`/a/b.md`, §1 "Paths", 2.0): the rows carry the storage form (`path`, the
+    // `__path` join column) and the read roots it, so nothing below the binding
     // changes. run.ts roots the string literals a query compares them with.
-    const intrinsic = (row, t, name) => {
-        // `$self` = the current row: run.ts rewrites row-scoped domain functions
-        // (text/semantic/under_*/…) to `$self.fn(…)` so they arrive via callMethod
-        // with the row as receiver (a free function sees no row).
-        if (name === "$self")
-            return row;
+    // `undefined` means "not an attribute" — the caller falls through to the
+    // handles, relations and the author's data.
+    const attribute = (row, t, name) => {
         if (t === "docs")
             switch (name) {
-                case "$id": return row.doc_id;
-                case "$path": return referencePath(String(row.path));
-                case "$content_hash": return row.file_hash == null ? null : hex(row.file_hash);
-                case "$updated_at": return scalar(`SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ?`, row.current_rev) ?? null;
-                case "$body": return docsRead(store, String(row.doc_id))?.content ?? null;
-                case "$title": return docProp(String(row.doc_id), "$title", "computed") ?? null;
-                case "$tags": return docProp(String(row.doc_id), "$tags", "computed") ?? null;
+                case "id": return row.doc_id;
+                case "path": return referencePath(String(row.path));
+                case "hash": return row.file_hash == null ? null : hex(row.file_hash);
+                case "updated_at": return scalar(`SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ?`, row.current_rev) ?? null;
+                // `raw`: the exact file bytes (spec/store §6.1, frontmatter included).
+                case "raw": return docsRead(store, String(row.doc_id))?.raw ?? null;
+                // `title`: the computed title (spec/properties §3.3 — the authored
+                // title, else the first H1, else absent → null). `data.title` is the
+                // authored one alone.
+                case "title": return docProp(String(row.doc_id), "$title", "computed") ?? null;
+                // `tags`: the union of the authored tags (frontmatter + inline, by the
+                // property rule) and the body `#hashtags` (the computed `$tags` row,
+                // spec/properties §3.3), deduped, authored first in authored order, then
+                // the hashtags in document order; null when both are absent.
+                // `data.tags` is the authored list alone.
+                case "tags": return docTags(String(row.doc_id));
+                case "format": return row.format;
             }
         if (t === "blocks")
             switch (name) {
-                case "$id": return row.block_id;
-                case "$doc": return row.doc_id;
-                case "$path": return referencePath(String(row.__path));
-                case "$ordinal": return row.ordinal;
-                case "$depth": return row.depth;
-                case "$body": return row.text;
-                case "$content_hash": return row.raw_hash == null ? null : hex(row.raw_hash);
-                case "$updated_at": return scalar(`SELECT MAX(c.ts) FROM block_changes bc JOIN commits c ON c.commit_id = bc.commit_id WHERE bc.block_id = ?`, row.block_id) ?? null;
+                case "id": return row.block_id;
+                case "path": return referencePath(String(row.__path));
+                // `raw`: the block's raw source bytes — the blob its `raw_hash` names (a
+                // container's raw holds its children verbatim); `text` is the normalized text.
+                case "raw": return row.raw_hash == null ? null : scalar(`SELECT bytes FROM blobs WHERE hash = ?`, row.raw_hash)?.toString("utf8") ?? null;
+                case "hash": return row.raw_hash == null ? null : hex(row.raw_hash);
+                case "updated_at": return scalar(`SELECT MAX(c.ts) FROM block_changes bc JOIN commits c ON c.commit_id = bc.commit_id WHERE bc.block_id = ?`, row.block_id) ?? null;
+                case "doc_id": return row.doc_id;
+                case "type": return row.type;
+                case "text": return row.text;
+                case "attrs": return parseJson(row.attrs);
+                case "ordinal": return row.ordinal;
+                case "depth": return row.depth;
             }
         if (t === "nodes")
             switch (name) {
-                case "$id":
-                case "$node_id": return row.node_id;
-                case "$doc_id": return row.doc_id;
-                case "$block_id": return row.block_id;
-                case "$path": return referencePath(String(row.__path));
+                case "id": return row.node_id;
+                case "path": return referencePath(String(row.__path));
+                case "doc_id": return row.doc_id;
+                case "block_id": return row.block_id ?? null;
+                case "kind": return row.kind;
+                case "name": return row.name;
+                case "value": return row.value;
+                case "attrs": return parseJson(row.attrs);
             }
-        if (t === "edges")
+        if (t === "links")
             switch (name) {
-                case "$id": return row.edge_id;
-                case "$src": return row.src_doc;
-                case "$dst": return row.dst_node;
-                case "$src_block": return row.src_block;
-                case "$via": return row.via_node;
-                case "$from_commit": return row.from_commit;
-                case "$path": return referencePath(String(row.__path));
-                case "$dst_path": {
+                // the store's columns under the surface's names (spec/surface §1.2).
+                case "id": return row.edge_id;
+                case "path": return referencePath(String(row.__path));
+                case "doc_id": return row.src_doc;
+                case "block_id": return row.src_block ?? null;
+                case "via_id": return row.via_node ?? null;
+                case "dst_id": return row.dst_node;
+                case "dst_path": {
                     const p = scalar(`SELECT path FROM docs WHERE doc_id = ?`, row.dst_node);
                     return p == null ? null : referencePath(String(p));
                 }
-                case "$dst_uri": return scalar(`SELECT uri FROM external_nodes WHERE node_id = ?`, row.dst_node) ?? null;
+                case "uri": return scalar(`SELECT uri FROM external_nodes WHERE node_id = ?`, row.dst_node) ?? null;
+                case "field": return row.src_field ?? null;
+                case "predicate":
+                case "provenance":
+                case "dst_kind":
+                case "anchor": return row[name];
             }
         return undefined;
     };
+    // `tags` on a document: authored ∪ hashtags, each list as the property rule
+    // reads it (a scalar-authored `tags: x` is one element), deduped by value
+    // (canonical JSON, so both engines agree on non-string elements).
+    const docTags = (docId) => {
+        const asList = (v) => (v === undefined || v === null ? [] : Array.isArray(v) ? v : [v]);
+        const authored = asList(docProp(docId, "tags"));
+        const hashtags = asList(docProp(docId, "$tags", "computed"));
+        if (authored.length === 0 && hashtags.length === 0)
+            return null;
+        const seen = new Set();
+        const out = [];
+        for (const v of [...authored, ...hashtags]) {
+            const k = JSON.stringify(v) ?? "undefined";
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(v);
+        }
+        return out;
+    };
     // ---- get ------------------------------------------------------------------
     const getFrom = (row, key) => {
         if (row == null)
             return undefined;
-        // The root row: `^$it.$id` is the repository id, `^$it.<target>` the lazy
+        // The root row: `^$it.id` is the repository id, `^$it.<target>` the lazy
         // root scan (the same handle `^<target>` / `root(name)` hands out).
         if (row[ROOT_ROW]) {
-            if (key === "$id")
+            if (key === "id")
                 return repoId;
             return rootFns[key] ? rootFns[key]() : undefined;
         }
         if (row[PROP_SOURCE]) {
             const p = row;
-            return docProp(p.docId, key, p.source);
+            return docProp(p.docId, key, p.source ?? undefined);
         }
         const t = row[TARGET];
         if (!t) {
@@ -404,8 +544,16 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return row[key];
         }
         const r = row;
-        if (key.startsWith("$"))
-            return intrinsic(r, t, key);
+        // `$self` = the current row: run.ts rewrites row-scoped domain functions
+        // (text/semantic/under_*/…) to `$self.fn(…)` so they arrive via callMethod
+        // with the row as receiver (a free function sees no row). Any other `$`
+        // name is OQX's (resolved by the engine before the row) or unknown — never
+        // an omgbase attribute.
+        if (key === "$self")
+            return r;
+        // engine attributes win on collision (the name rule above).
+        if (ATTRIBUTES[t].has(key))
+            return attribute(r, t, key);
         // self-alias namespaces: `doc.x` (docs), `block.x` (blocks), `section.x` (nodes).
         if (t === "docs" && key === "doc")
             return r;
@@ -413,62 +561,40 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return r;
         if (t === "nodes" && key === "section")
             return r;
-        // reach-through to owning entities.
+        // reach-through to owning entities, and from a link row to its destination —
+        // statically single relations: absent is the single-with-no-row marker.
         if (t !== "docs" && key === "doc")
-            return owningDoc(r);
+            return owningDoc(r) ?? ABSENT_SINGLE;
         if (t === "nodes" && key === "block")
-            return owningBlock(r);
+            return owningBlock(r) ?? ABSENT_SINGLE;
+        if (t === "links" && key === "dst")
+            return destinationDoc(r) ?? ABSENT_SINGLE;
         // relations.
         const rels = rel[t];
         if (rels[key])
             return rels[key](r);
         // A bare target name that is not one of this row's relations reads a
         // property the row has none of (spec/surface §1.1, 2.0): loud, naming the
-        // root-row spelling. `docs`/`edges` never get here (run.ts refuses them
+        // root-row spelling. `docs`/`links` never get here (run.ts refuses them
         // statically); `blocks` on a block or edge row and `nodes` on a node or
         // edge row do.
         if (TARGETS.has(key))
             throw new FilterInvalid(bareTargetMessage(key, null), "OQX");
-        // per-target scalar fields.
+        // the author's data.
         if (t === "docs") {
-            if (key === "format")
-                return r.format;
-            if (key === "frontmatter" || key === "inline")
-                return { [PROP_SOURCE]: true, docId: String(r.doc_id), source: key };
-            if (RESERVED_DOC_BASENAMES.has(key)) {
-                throw new FilterInvalid(`bare '${key}' reads a frontmatter key; did you mean the intrinsic $${key}? (use frontmatter.${key} to force the property)`, "10 §2");
-            }
+            // The source handles: `data` is the merged authored view (frontmatter +
+            // inline), the other two one source each; `data.<k>` reaches an authored
+            // key whose bare name is an engine attribute (`data.path`, `data.tags`).
+            if (SOURCE_HANDLES.has(key))
+                return { [PROP_SOURCE]: true, docId: String(r.doc_id), source: key === "data" ? null : key };
             return docProp(String(r.doc_id), key);
         }
-        if (t === "blocks") {
-            if (key === "type")
-                return r.type;
-            if (key === "text")
-                return r.text;
-            if (key === "attrs")
-                return parseJson(r.attrs);
-            // A bare non-structural identifier flattens into attrs: `checked` reads
-            // `attrs.checked`. Structural fields above win on collision; an absent key
-            // is undefined (silently false in a predicate), matching a doc's missing
-            // frontmatter key. The `attrs.<k>` form still works unchanged.
+        // blocks / nodes: a bare non-structural identifier flattens into attrs:
+        // `checked` reads `attrs.checked`. The attributes above win on collision; an
+        // absent key is undefined (silently false in a predicate), matching a doc's
+        // missing frontmatter key. The `attrs.<k>` form still works unchanged.
+        if (t === "blocks" || t === "nodes")
             return jattr(r, key);
-        }
-        if (t === "nodes") {
-            if (key === "kind")
-                return r.kind;
-            if (key === "name")
-                return r.name;
-            if (key === "value")
-                return r.value;
-            if (key === "attrs")
-                return parseJson(r.attrs);
-            // Bare non-structural identifier flattens into attrs (see blocks above):
-            // `checked` reads `attrs.checked` on an `md:task`, `level` on an `md:section`.
-            return jattr(r, key);
-        }
-        // edges
-        if (key === "predicate" || key === "provenance" || key === "dst_kind" || key === "anchor" || key === "src_field")
-            return r[key];
         return undefined;
     };
     // ---- domain functions (row-scoped, via callMethod on $self) ---------------
@@ -526,8 +652,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
         }
     };
     const textMatch = (t, r, terms) => {
-        if (t === "edges")
-            throw new FilterInvalid("text(...) is not available on the edges target", "10 §5");
+        if (t === "links")
+            throw new FilterInvalid("text(...) is not available on the links target", "10 §5");
         const match = sanitizeFtsQuery(terms);
         if (match === "")
             return false;
@@ -550,7 +676,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return one(`SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?`, r.raw_hash, Buffer.from(ctxHashHex(ctx), "hex"), model);
     };
     const semanticScore = (t, r, phrase) => {
-        if (t === "nodes" || t === "edges")
+        if (t === "nodes" || t === "links")
             throw new FilterInvalid("semantic(...) is available on the docs and blocks targets", "OQX semantic");
         const resolved = sv?.get(phrase);
         if (!resolved)
@@ -633,6 +759,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
     // Store indexes by (target, path) — one object, one set of prepared statements,
     // for the whole run (`null`: the path is not indexable).
     const indexes = new Map();
+    // A row's identity — `$key` (spec/oqx §16, 0.20): its id column for every
+    // kind; anything else (a property bag, a lifted value) is known structurally.
     const identity = (row) => {
         const t = row?.[TARGET];
         if (t === "docs")
@@ -641,18 +769,18 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return row.block_id;
         if (t === "nodes")
             return row.node_id;
-        if (t === "edges")
+        if (t === "links")
             return row.edge_id;
         return row;
     };
     return {
         // The root scope's names (spec/oqx §2 step 5 at the root): the four lazy
-        // scans and `$id`, the repository id — so `^docs` / `0^docs` from any row is
-        // the scan and `^$id` / `0^$id` the id.
+        // scans and `id`, the repository id — so `^docs` / `0^docs` from any row is
+        // the scan and `^id` / `0^id` the id.
         root(name) {
             if (opts.rowsRoot && name === opts.rowsRoot.name)
                 return opts.rowsRoot.rows;
-            if (name === "$id")
+            if (name === "id")
                 return repoId;
             return rootFns[name] ? rootFns[name]() : undefined;
         },
@@ -662,8 +790,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return rootRow;
         },
         get: getFrom,
+        // Row position (spec/oqx §3): a tagged row is ONE row (single — the engine's
+        // default for a non-iterable object), a lazy scan (an iterable Proxy) a
+        // collection, the absent-single marker one row with none.
         toRows(value) {
-            if (value == null)
+            if (value == null || value === ABSENT_SINGLE)
                 return [];
             if (Array.isArray(value))
                 return value;
@@ -673,7 +804,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 return value;
             return [value];
         },
-        identity,
+        // Value position: the absent-single marker is absent.
+        materialize(value) {
+            return value === ABSENT_SINGLE ? undefined : value;
+        },
+        identityOf: identity,
         // A store-backed equality index for a ROOT SCAN handle on a column or
         // property SQLite indexes (store-index.ts); `undefined` for any other
         // collection (a relation's rows, a lifted array) or path, so the engine
@@ -699,9 +834,10 @@ export function makeStoreContext(store, repoId, opts = {}) {
         // pushdown can serve the property's autopromoted/cached bounds — see
         // detectRange + val_json in store/properties.ts.
         callFunction(name, args) {
-            // `entries(frontmatter)` / `entries(inline)`: the source handle is lazy (a
-            // PropSourceRef, not a plain object), so materialize its property bag as
-            // entries here; any other argument falls through to the oqx builtin.
+            // `entries(data)` / `entries(frontmatter)` / `entries(inline)`: the source
+            // handle is lazy (a PropSourceRef, not a plain object), so materialize its
+            // property bag as entries here; any other argument falls through to the
+            // oqx builtin.
             if (name === "entries" && args[0]?.[PROP_SOURCE]) {
                 const p = args[0];
                 return { handled: true, value: docPropEntries(p.docId, p.source) };
@@ -743,9 +879,10 @@ export function tagRows(rows, target) {
 }
 /**
  * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
- * values, 1.2) is rendered as `{ id, path }` — its id column and its document's
- * path in the reference form (`/a.md`, §1 "Paths"), the same two keys every hit
- * carries — never the store row itself.
+ * values, 1.2) is rendered as `{ id, path }` (3.0) — its id column and its
+ * document's path in the reference form (`/a.md`, §1 "Paths"), the same two keys
+ * every hit carries, spelled as the attributes that read them — never the store
+ * row itself.
  * Returns undefined for anything that is not a tagged row (run.ts leaves those
  * alone).
  */

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

@@ -12,12 +12,12 @@ export declare function rootTarget(source: Expr): Target | null;
  *   • 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`)