@omgbase/core 0.1.0

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

@@ -0,0 +1,564 @@
+// A store-backed DataContext (oqx-js tier 2): binds `@omgbase/oqx`'s query
+// semantics to omgbase's SQLite store, so the InMemoryEngine reproduces the whole
+// OQX surface (targets, intrinsics, reach-through, structural relations, the edge
+// graph, follow, correlation, lifts) without a bespoke compiler. Rows are the
+// store's raw column objects, tagged with their target; `get` routes field /
+// intrinsic / relation resolution per target, lazily querying the store for
+// relations. Domain functions (text/semantic/under_*/…) are row-scoped, so they
+// arrive via `callMethod` on a synthetic `$self` receiver (see run.ts's AST
+// rewrite) rather than as free functions (which see no row).
+//
+// This is the correctness tier: N+1 queries, materialized collections — fine for
+// the corpus and the differential baseline. The tier-3 SQLite planner (planner.ts)
+// pushes the hot predicates down; both must agree (conformance suite).
+import { semantics } from "@omgbase/oqx";
+import { detectRange } from "../core/store/properties.js";
+import { docsRead } from "../core/read/document.js";
+import { FilterInvalid } from "../search/cel/parser.js";
+import { sanitizeFtsQuery } from "../search/fts-query.js";
+import { cosineBytes } from "../core/vec.js";
+const TARGET = Symbol("oqx.target");
+const REPO_ROOT = Symbol("oqx.repoRoot");
+const PROP_SOURCE = Symbol("oqx.propSource");
+function tag(row, t) {
+    if (!row)
+        return undefined;
+    row[TARGET] = t;
+    return row;
+}
+function tagAll(rows, t) {
+    for (const r of rows)
+        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.
+// (The root-scan receiver is the `$repo` intrinsic — `$repo.docs`/`$repo.nodes`/… —
+// so a bare `repo` is just an ordinary frontmatter key.)
+const RESERVED_DOC_BASENAMES = new Set(["id", "path", "updated_at", "content_hash", "body"]);
+export function makeStoreContext(store, repoId, opts = {}) {
+    const db = store.db;
+    const sv = opts.semanticVectors;
+    const all = (sql, ...params) => db.prepare(sql).all(...params);
+    const one = (sql, ...params) => db.prepare(sql).get(...params);
+    const scalar = (sql, ...params) => {
+        const r = db.prepare(sql).get(...params);
+        if (!r)
+            return undefined;
+        return Object.values(r)[0];
+    };
+    // ---- root collections (ordered for a stable (path, id) default) -----------
+    const docsRoot = () => tagAll(all(`SELECT * FROM docs WHERE repo_id = ? AND deleted_commit IS NULL ORDER BY path, doc_id`, repoId), "docs");
+    const blocksRoot = () => tagAll(all(`SELECT b.*, d.path AS __path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id
+       WHERE b.repo_id = ? AND b.deleted_commit IS NULL AND d.deleted_commit IS NULL
+       ORDER BY d.path, b.block_id`, repoId), "blocks");
+    const nodesRoot = () => tagAll(all(`SELECT n.*, d.path AS __path FROM nodes n JOIN docs d ON d.doc_id = n.doc_id
+       WHERE n.repo_id = ? AND d.deleted_commit IS NULL ORDER BY d.path, n.node_id`, repoId), "nodes");
+    const edgesRoot = () => tagAll(all(`SELECT e.*, d.path AS __path FROM edges e JOIN docs d ON d.doc_id = e.src_doc
+       WHERE e.repo_id = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL
+       ORDER BY d.path, e.edge_id`, repoId), "edges");
+    const rootFns = { docs: docsRoot, blocks: blocksRoot, nodes: nodesRoot, edges: edgesRoot };
+    // The repository handle behind the `$repo` intrinsic: `$repo.<target>` is the
+    // explicit root scan (rootFns), `$repo.$id` the repository id.
+    const repoRoot = { [REPO_ROOT]: true };
+    // ---- attrs / property decoding --------------------------------------------
+    const parseJson = (v) => {
+        if (typeof v !== "string")
+            return v ?? undefined;
+        try {
+            return JSON.parse(v);
+        }
+        catch {
+            return v;
+        }
+    };
+    // A property decodes to a plain scalar. A range-valued string (a frontmatter
+    // `1..5` / `2026-01-01..2026-01-31`) stays a STRING here — range behavior is
+    // opt-in via the `range(prop)` function (see callFunction), so a value that
+    // merely looks rangey is never silently reinterpreted, and projection/equality
+    // see the authored text. The store still caches the parsed bounds in val_json
+    // (see properties.ts detectRange) as an index substrate; it does not change
+    // this decode.
+    const decodeProp = (r) => {
+        switch (r.type) {
+            case "number": return r.val_num;
+            case "bool": return r.val_bool ? true : false;
+            case "null": return null;
+            case "json": return parseJson(r.val_json);
+            default: return r.val_text;
+        }
+    };
+    // A docs property key resolves to a scalar iff it has exactly one row in scope
+    // AND that row is card='scalar'; otherwise to the array of values (list-authored,
+    // repeated, or frontmatter+inline collision) — reproducing the CEL scalar-vs-list
+    // rule so `==` sees a scalar only when authored scalar, and `list()` sees all.
+    const docProp = (docId, key, source) => {
+        const rows = source
+            ? all(`SELECT * FROM properties WHERE doc_id = ? AND key = ? AND source = ? AND deleted_commit IS NULL ORDER BY ord`, docId, key, source)
+            : all(`SELECT * FROM properties WHERE doc_id = ? AND key = ? AND deleted_commit IS NULL ORDER BY ord`, docId, key);
+        if (rows.length === 0) {
+            // No exact key: omgbase flattens nested YAML/JSON maps to dotted keys
+            // (`logging.level`), so a bare `logging` should reconstruct the nested
+            // object for `.level` member navigation.
+            return docPropObject(docId, key, source);
+        }
+        if (rows.length === 1 && rows[0].card === "scalar")
+            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
+    // 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).
+    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 tops = [];
+        const seen = new Set();
+        for (const k of keys) {
+            const top = k.split(".")[0];
+            if (!seen.has(top)) {
+                seen.add(top);
+                tops.push(top);
+            }
+        }
+        return tops.map((t) => semantics.makeEntry(t, docProp(docId, t, source)));
+    };
+    // Reconstruct a nested object from flattened dotted keys under `prefix.`
+    // (undefined when there are none). Leaves are decoded property values.
+    const docPropObject = (docId, prefix, source) => {
+        const rows = source
+            ? all(`SELECT * FROM properties WHERE doc_id = ? AND key LIKE ? AND source = ? AND deleted_commit IS NULL ORDER BY ord`, docId, `${prefix}.%`, source)
+            : all(`SELECT * FROM properties WHERE doc_id = ? AND key LIKE ? AND deleted_commit IS NULL ORDER BY ord`, docId, `${prefix}.%`);
+        if (rows.length === 0)
+            return undefined;
+        const out = {};
+        for (const r of rows) {
+            const rest = String(r.key).slice(prefix.length + 1).split(".");
+            let cur = out;
+            for (let i = 0; i < rest.length - 1; i++) {
+                const seg = rest[i];
+                if (typeof cur[seg] !== "object" || cur[seg] == null)
+                    cur[seg] = {};
+                cur = cur[seg];
+            }
+            cur[rest[rest.length - 1]] = decodeProp(r);
+        }
+        return out;
+    };
+    // ---- top-ordinal of a block's top-level ancestor (for section ranges) -----
+    const topOrdinal = (block) => {
+        if (block.parent_block == null)
+            return block.ordinal;
+        // ancestor_path is '/b_x/b_y/…'; first segment is the top-level ancestor.
+        const ap = String(block.ancestor_path);
+        const first = ap.split("/").filter(Boolean)[0];
+        if (!first)
+            return block.ordinal;
+        const r = one(`SELECT ordinal FROM blocks WHERE doc_id = ? AND block_id = ?`, block.doc_id, first);
+        return r?.ordinal ?? block.ordinal;
+    };
+    // ---- relations (return row arrays) ----------------------------------------
+    const rel = {
+        docs: {
+            nodes: (r) => tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.doc_id = ?`, r.path, r.doc_id), "nodes"),
+            blocks: (r) => tagAll(all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.doc_id = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, r.path, r.doc_id), "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"),
+        },
+        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 = ?`, 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"),
+            // enclosing section node(s): md:section whose range contains this block's top ordinal.
+            section: (r) => {
+                const top = topOrdinal(r);
+                return tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.doc_id = ? AND n.kind = 'md:section'
+             AND json_extract(n.attrs,'$.first_ordinal') <= ? AND json_extract(n.attrs,'$.last_ordinal') >= ?
+           ORDER BY json_extract(n.attrs,'$.first_ordinal'), n.node_id`, r.__path, r.doc_id, top, top), "nodes");
+            },
+        },
+        nodes: {
+            // section.* — the node interpreted as a section (range attrs).
+            blocks: (r) => {
+                const f = jattr(r, "first_ordinal"), l = jattr(r, "last_ordinal");
+                if (f == null || l == null)
+                    return [];
+                // blocks whose top-level ordinal falls in the section range.
+                const rows = all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.doc_id = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, r.__path, r.doc_id);
+                const kept = rows.filter((b) => { const t = topOrdinal(b); return t >= f && t <= l; });
+                return tagAll(kept, "blocks");
+            },
+            subsections: (r) => {
+                const f = jattr(r, "first_ordinal"), l = jattr(r, "last_ordinal"), lvl = jattr(r, "level");
+                if (f == null)
+                    return [];
+                return tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.doc_id = ? AND n.kind = 'md:section'
+             AND json_extract(n.attrs,'$.first_ordinal') >= ? AND json_extract(n.attrs,'$.last_ordinal') <= ?
+             AND json_extract(n.attrs,'$.level') > ? ORDER BY json_extract(n.attrs,'$.first_ordinal'), n.node_id`, r.__path, r.doc_id, f, l, lvl), "nodes");
+            },
+            children: (r) => {
+                const f = jattr(r, "first_ordinal"), l = jattr(r, "last_ordinal"), lvl = jattr(r, "level");
+                if (f == null)
+                    return [];
+                // immediate child sections: contained, deeper, with no intervening section.
+                return tagAll(all(`SELECT i.*, ? AS __path FROM nodes i WHERE i.doc_id = ? AND i.kind = 'md:section'
+             AND json_extract(i.attrs,'$.level') > ?
+             AND json_extract(i.attrs,'$.first_ordinal') >= ? AND json_extract(i.attrs,'$.last_ordinal') <= ?
+             AND NOT EXISTS (SELECT 1 FROM nodes m WHERE m.doc_id = i.doc_id AND m.kind = 'md:section'
+               AND json_extract(m.attrs,'$.level') > ? AND json_extract(m.attrs,'$.level') < json_extract(i.attrs,'$.level')
+               AND json_extract(m.attrs,'$.first_ordinal') <= json_extract(i.attrs,'$.first_ordinal')
+               AND json_extract(m.attrs,'$.last_ordinal') >= json_extract(i.attrs,'$.last_ordinal'))
+           ORDER BY json_extract(i.attrs,'$.first_ordinal'), i.node_id`, r.__path, r.doc_id, lvl, f, l, lvl), "nodes");
+            },
+        },
+        edges: {},
+    };
+    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) ------------------------------------------------
+    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;
+        if (t === "docs")
+            switch (name) {
+                case "$id": return row.doc_id;
+                case "$path": return 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;
+            }
+        if (t === "blocks")
+            switch (name) {
+                case "$id": return row.block_id;
+                case "$doc": return row.doc_id;
+                case "$path": return 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;
+            }
+        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 row.__path;
+            }
+        if (t === "edges")
+            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 row.__path;
+                case "$dst_path": return scalar(`SELECT path FROM docs WHERE doc_id = ?`, row.dst_node) ?? null;
+                case "$dst_uri": return scalar(`SELECT uri FROM external_nodes WHERE node_id = ?`, row.dst_node) ?? null;
+            }
+        return undefined;
+    };
+    // ---- get ------------------------------------------------------------------
+    const getFrom = (row, key) => {
+        if (row == null)
+            return undefined;
+        // `$repo` is an intrinsic of EVERY scope — the root and any row, store-backed
+        // or plain. Bare names resolve against the current row only (oqx ≥ 0.7: no
+        // scope climbing), so a correlated subquery at any depth reaches the
+        // repository root through this local intrinsic, never by falling through
+        // to an enclosing scope.
+        if (key === "$repo")
+            return repoRoot;
+        if (row[REPO_ROOT]) {
+            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);
+        }
+        const t = row[TARGET];
+        if (!t) {
+            // a plain value (parsed attrs/json object, or a lifted array element): plain access.
+            return row[key];
+        }
+        const r = row;
+        if (key.startsWith("$"))
+            return intrinsic(r, t, key);
+        // self-alias namespaces: `doc.x` (docs), `block.x` (blocks), `section.x` (nodes).
+        if (t === "docs" && key === "doc")
+            return r;
+        if (t === "blocks" && key === "block")
+            return r;
+        if (t === "nodes" && key === "section")
+            return r;
+        // reach-through to owning entities.
+        if (t !== "docs" && key === "doc")
+            return owningDoc(r);
+        if (t === "nodes" && key === "block")
+            return owningBlock(r);
+        // relations.
+        const rels = rel[t];
+        if (rels[key])
+            return rels[key](r);
+        // per-target scalar fields.
+        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");
+            }
+            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.
+            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) ---------------
+    const method = (name, recv, args) => {
+        const r = recv;
+        const t = r?.[TARGET];
+        switch (name) {
+            case "text": return { handled: true, value: textMatch(t, r, String(args[0] ?? "")) };
+            case "semantic": return { handled: true, value: semanticScore(t, r, String(args[0] ?? "")) };
+            case "has_anchor": {
+                requireTarget(t, "blocks", "has_anchor");
+                return { handled: true, value: !!one(`SELECT 1 FROM edges WHERE src_block = ? AND anchor IS NOT NULL LIMIT 1`, r.block_id) };
+            }
+            case "child_count": {
+                requireTarget(t, "blocks", "child_count");
+                return { handled: true, value: scalar(`SELECT COUNT(*) FROM blocks WHERE parent_block = ? AND deleted_commit IS NULL`, r.block_id) };
+            }
+            case "parent_type": {
+                requireTarget(t, "blocks", "parent_type");
+                return { handled: true, value: scalar(`SELECT type FROM blocks WHERE block_id = ?`, r.parent_block) ?? null };
+            }
+            case "has_edge": {
+                const pred = String(args[0]);
+                const srcCol = t === "blocks" ? "src_block = ?" : "src_doc = ?";
+                const srcVal = t === "blocks" ? r.block_id : r.doc_id;
+                if (args.length >= 2)
+                    return { handled: true, value: !!one(`SELECT 1 FROM edges WHERE ${srcCol} AND predicate = ? AND to_commit IS NULL AND dst_node = ? LIMIT 1`, srcVal, pred, args[1]) };
+                return { handled: true, value: !!one(`SELECT 1 FROM edges WHERE ${srcCol} AND predicate = ? AND to_commit IS NULL LIMIT 1`, srcVal, pred) };
+            }
+            case "under": {
+                requireTarget(t, "blocks", "under");
+                return { handled: true, value: underSubtree(r, String(args[0])) };
+            }
+            case "under_heading": {
+                requireTarget(t, "blocks", "under_heading");
+                return { handled: true, value: underHeading(r, String(args[0])) };
+            }
+            case "within": {
+                requireTarget(t, "blocks", "within");
+                return { handled: true, value: within(r, String(args[0])) };
+            }
+            case "under_kind": {
+                requireTarget(t, "blocks", "under_kind");
+                return { handled: true, value: underKind(r, String(args[0]), args[1]) };
+            }
+            case "yaml_path": {
+                requireTarget(t, "blocks", "yaml_path");
+                return { handled: true, value: keyPath(r, String(args[0]), "yaml") };
+            }
+            case "json_pointer": {
+                requireTarget(t, "blocks", "json_pointer");
+                return { handled: true, value: keyPath(r, String(args[0]), "json") };
+            }
+            default: return { handled: false };
+        }
+    };
+    const textMatch = (t, r, terms) => {
+        if (t === "edges")
+            throw new FilterInvalid("text(...) is not available on the edges target", "10 §5");
+        const match = sanitizeFtsQuery(terms);
+        if (match === "")
+            return false;
+        if (t === "docs")
+            return !!one(`SELECT 1 FROM blocks_fts JOIN blocks b ON b.rowid = blocks_fts.rowid WHERE b.doc_id = ? AND blocks_fts MATCH ? LIMIT 1`, r.doc_id, match);
+        if (t === "nodes")
+            return !!one(`SELECT 1 FROM nodes_fts WHERE rowid = (SELECT rowid FROM nodes WHERE node_id = ?) AND nodes_fts MATCH ? `, r.node_id, match);
+        // blocks
+        return !!one(`SELECT 1 FROM blocks_fts WHERE rowid = (SELECT rowid FROM blocks WHERE block_id = ?) AND blocks_fts MATCH ?`, r.block_id, match);
+    };
+    const semanticScore = (t, r, phrase) => {
+        if (t === "nodes" || t === "edges")
+            throw new FilterInvalid("semantic(...) is available on the docs and blocks targets", "OQX semantic");
+        const resolved = sv?.get(phrase);
+        if (!resolved)
+            throw new FilterInvalid(`semantic(${JSON.stringify(phrase)}) needs an embedding provider; none is configured for this query`, "OQX semantic");
+        const row = t === "docs"
+            ? one(`SELECT vec FROM doc_embeddings WHERE doc_id = ? AND model = ?`, r.doc_id, resolved.model)
+            : one(`SELECT vec FROM embeddings WHERE content_hash = ? AND model = ? LIMIT 1`, r.raw_hash, resolved.model);
+        if (!row)
+            return null;
+        return cosineBytes(row.vec, resolved.vec);
+    };
+    const underSubtree = (r, target) => {
+        const ap = String(r.ancestor_path ?? "");
+        return ap.includes(`/${target}/`) || r.block_id === target;
+    };
+    const underHeading = (r, text) => {
+        const top = topOrdinal(r);
+        return !!one(`SELECT 1 FROM sections s JOIN blocks hb ON hb.block_id = s.heading_block
+       WHERE s.doc_id = ? AND lower(hb.text) LIKE '%' || lower(?) || '%' AND s.first_ordinal <= ? AND s.last_ordinal >= ? LIMIT 1`, r.doc_id, text, top, top);
+    };
+    const within = (r, target) => {
+        if (target.startsWith("d_"))
+            return r.doc_id === target;
+        if (target.includes("*")) {
+            const like = target.replace(/[%_]/g, "\\$&").replace(/\*/g, "%");
+            return !!one(`SELECT 1 WHERE ? LIKE ? ESCAPE '\\'`, r.__path, like);
+        }
+        return r.__path === target;
+    };
+    const underKind = (r, kind, name) => {
+        const ap = String(r.ancestor_path ?? "").split("/").filter(Boolean);
+        if (ap.length === 0)
+            return false;
+        const placeholders = ap.map(() => "?").join(",");
+        if (name != null) {
+            return !!one(`SELECT 1 FROM blocks WHERE block_id IN (${placeholders}) AND type = ? AND (lower(text) LIKE '%' || lower(?) || '%' OR json_extract(attrs,'$.key') = ?) LIMIT 1`, ...ap, kind, name, name);
+        }
+        return !!one(`SELECT 1 FROM blocks WHERE block_id IN (${placeholders}) AND type = ? LIMIT 1`, ...ap, kind);
+    };
+    const keyPath = (r, path, kind) => {
+        const key = kind === "json" ? path.replace(/^#?\/?/, "").split("/").join(".") : path;
+        const leaf = key.split(".").pop();
+        if (String(r.type ?? "").startsWith(`${kind}:`) === false)
+            return false;
+        return jattr(r, "key") === leaf || jattr(r, "key") === key;
+    };
+    return {
+        root(name) {
+            if (opts.rowsRoot && name === opts.rowsRoot.name)
+                return opts.rowsRoot.rows;
+            if (name === "$repo")
+                return repoRoot;
+            return rootFns[name] ? rootFns[name]() : undefined;
+        },
+        get: getFrom,
+        toRows(value) {
+            if (value == null)
+                return [];
+            if (Array.isArray(value))
+                return value;
+            if (typeof value === "object" && value[TARGET])
+                return [value];
+            if (typeof value === "object" && Symbol.iterator in value)
+                return value;
+            return [value];
+        },
+        identity(row) {
+            const t = row?.[TARGET];
+            if (t === "docs")
+                return row.doc_id;
+            if (t === "blocks")
+                return row.block_id;
+            if (t === "nodes")
+                return row.node_id;
+            if (t === "edges")
+                return row.edge_id;
+            return row;
+        },
+        // Free functions: oqx-js builtins (list/size/has) plus `range(s)`, which
+        // coerces a string value to a range so `<point> in range(prop)` tests
+        // coverage. range() is the explicit opt-in over the store's plain string;
+        // it delegates here (rather than only to the oqx-js builtin) so a future
+        // 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.
+            if (name === "entries" && args[0]?.[PROP_SOURCE]) {
+                const p = args[0];
+                return { handled: true, value: docPropEntries(p.docId, p.source) };
+            }
+            if (name === "range") {
+                const s = args[0];
+                if (semantics.isRange(s))
+                    return { handled: true, value: s };
+                const rv = typeof s === "string" ? detectRange(s) : null;
+                return { handled: true, value: rv ? semantics.makeRange(rv.lo, rv.hi, rv.exclusiveEnd) : null };
+            }
+            const fn = semantics.BUILTIN_FUNCTIONS[name];
+            return fn ? { handled: true, value: fn(args) } : { handled: false };
+        },
+        // Domain methods first; fall back to oqx-js builtin methods
+        // (contains/startsWith/endsWith/matches/size/lower/upper).
+        callMethod(name, recv, args) {
+            const r = method(name, recv, args);
+            if (r.handled)
+                return r;
+            const fn = semantics.BUILTIN_METHODS[name];
+            return fn ? { handled: true, value: fn(recv, args) } : { handled: false };
+        },
+    };
+}
+function requireTarget(t, want, fn) {
+    if (t !== want)
+        throw new FilterInvalid(`${fn}() is only available on the ${want} target`, "10 §5");
+}
+function hex(b) {
+    return Buffer.isBuffer(b) ? b.toString("hex") : String(b);
+}
+/** Tag SQL rows with their target so the store context resolves them (used by the
+ * tier-3 planner to hand produced rows back for residual evaluation). */
+export function tagRows(rows, target) {
+    return tagAll(rows, target);
+}
+export { TARGET };
+//# sourceMappingURL=context.js.map

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

@@ -0,0 +1,10 @@
+import type { Query, QueryPlanner, Plan } from "@omgbase/oqx";
+import type { Store } from "../core/store/store.js";
+import { type StoreContextOptions } from "./context.js";
+export declare class SQLiteQueryPlanner implements QueryPlanner {
+    private store;
+    private repoId;
+    private ctxOpts;
+    constructor(store: Store, repoId: string, ctxOpts?: StoreContextOptions);
+    plan(query: Query, params: readonly unknown[]): Plan | null;
+}

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

@@ -0,0 +1,91 @@
+// Tier-3 pushdown planner (ADR-013). Reduces the row set a query scans by
+// translating its pushable top-level `where` conjuncts into ONE SQL statement
+// against the store, then handing the produced rows (+ the untranslatable
+// residual) back to the in-memory engine to finish. Correctness is guaranteed by
+// the residual fallback — anything `translate.ts` declines stays in-memory — and
+// verified by the differential conformance suite (planned == in-memory).
+//
+// This is deliberately conservative: only simple top-level target scans (no
+// `follow`, no source re-projection) with at least one pushable scalar conjunct
+// are planned; everything else declines to a full in-memory run.
+import { ROWS_ROOT, partitionPushable, residualQuery } from "@omgbase/oqx";
+import { makeStoreContext, tagRows } from "./context.js";
+import { translatePredicate } from "./sql/translate.js";
+const ALIAS = {
+    docs: { self: "d", doc: "d" },
+    blocks: { self: "b", doc: "d" },
+    nodes: { self: "n", doc: "d" },
+    edges: { self: "e", doc: "d" },
+};
+const FROM = {
+    docs: "docs d",
+    blocks: "blocks b JOIN docs d ON d.doc_id = b.doc_id",
+    nodes: "nodes n JOIN docs d ON d.doc_id = n.doc_id",
+    edges: "edges e JOIN docs d ON d.doc_id = e.src_doc",
+};
+// Row columns + the owning-doc path as __path (matches the context roots so
+// produced rows are indistinguishable from a full scan's).
+const COLS = {
+    docs: "d.*",
+    blocks: "b.*, d.path AS __path",
+    nodes: "n.*, d.path AS __path",
+    edges: "e.*, d.path AS __path",
+};
+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",
+};
+function guards(target, repoId) {
+    switch (target) {
+        case "docs": return { sql: "d.repo_id = ? AND d.deleted_commit IS NULL", params: [repoId] };
+        case "blocks": return { sql: "b.repo_id = ? AND b.deleted_commit IS NULL AND d.deleted_commit IS NULL", params: [repoId] };
+        case "nodes": return { sql: "n.repo_id = ? AND d.deleted_commit IS NULL", params: [repoId] };
+        case "edges": return { sql: "e.repo_id = ? AND e.to_commit IS NULL AND d.deleted_commit IS NULL", params: [repoId] };
+    }
+}
+// The root collection a query scans, if it is a bare `docs|blocks|nodes|edges`
+// or `$repo.<target>` source (else null — not a pushable shape).
+function rootTarget(source) {
+    const TARGETS = new Set(["docs", "blocks", "nodes", "edges"]);
+    if (source.kind === "ident" && TARGETS.has(source.name))
+        return source.name;
+    if (source.kind === "member" && source.recv.kind === "ident" && source.recv.name === "$repo" && TARGETS.has(source.name)) {
+        return source.name;
+    }
+    return null;
+}
+export class SQLiteQueryPlanner {
+    store;
+    repoId;
+    ctxOpts;
+    constructor(store, repoId, ctxOpts = {}) {
+        this.store = store;
+        this.repoId = repoId;
+        this.ctxOpts = ctxOpts;
+    }
+    plan(query, params) {
+        // Only simple top-level scans: no follow, no `from E` re-projection.
+        if (query.follow || query.from.length > 0)
+            return null;
+        const target = rootTarget(query.source);
+        if (!target)
+            return null;
+        const ctx = { target, self: ALIAS[target].self, doc: ALIAS[target].doc, params };
+        const { pushed, residual } = partitionPushable(query.where, (e) => translatePredicate(e, ctx) !== null);
+        if (pushed.length === 0)
+            return null; // nothing to push — let the engine do it all
+        const frags = pushed.map((e) => translatePredicate(e, ctx));
+        const g = guards(target, this.repoId);
+        const whereSql = [g.sql, ...frags.map((f) => `(${f.sql})`)].join(" AND ");
+        const sqlParams = [...g.params, ...frags.flatMap((f) => f.params)];
+        const sql = `SELECT ${COLS[target]} FROM ${FROM[target]} WHERE ${whereSql} ORDER BY ${ORDER[target]}`;
+        const rows = tagRows(this.store.db.prepare(sql).all(...sqlParams), target);
+        // The residual scans ROWS_ROOT; give it a store context that resolves those
+        // produced rows (relations/intrinsics/domain fns still hit the store).
+        const context = makeStoreContext(this.store, this.repoId, { ...this.ctxOpts, rowsRoot: { name: ROWS_ROOT, rows } });
+        return { rows: () => rows, residual: residualQuery(query, residual), context };
+    }
+}
+//# sourceMappingURL=planner.js.map