@omgbase/core 0.2.0 → 0.4.0

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

@@ -1,6 +1,25 @@
-import type { Query, QueryPlanner, Plan } from "@omgbase/oqx";
+import type { Query, Where, QueryPlanner, Plan } from "@omgbase/oqx";
 import type { Store } from "../core/store/store.js";
 import { type StoreContextOptions } from "./context.js";
+import { type Target } from "./sql/translate.js";
+/**
+ * True when evaluating `where` in memory could raise an OQX error the pushed
+ * conjuncts might hide by emptying the scan. The walk is generic over the whole
+ * residual tree — every `Where` node, every nested block (its `from`, `where`,
+ * `select`, `order by`, `follow`, `limit`/`offset`) and every `Expr` — and flags:
+ *
+ *   • 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
+ *     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 residual made only of comparisons, logical operators, `in`/ranges, `!`,
+ * literals, bindings and plain reads (including exists/none/count/collect/first
+ * blocks of the same) cannot raise, so the pushed conjuncts are kept.
+ */
+export declare function residualMayRaise(where: Where | null, target: Target): boolean;
 export declare class SQLiteQueryPlanner implements QueryPlanner {
     private store;
     private repoId;

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

@@ -7,10 +7,16 @@
 //
 // 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.
+// are planned; everything else declines to a full in-memory run. One more
+// decline keeps the planned path invisible (spec/surface §1 decline (c)): a
+// pushed conjunct that empties the scan would also hide an OQX eval error a
+// residual conjunct raises in memory (`path == "x" && $path == "nope.md"` was
+// `[]` planned, `filter_invalid` in memory), so when any residual conjunct could
+// raise — a function or method call, a `single` block, a `^`-escaped name, or a
+// bare reserved docs basename — the WHOLE query runs unplanned.
 import { ROWS_ROOT, partitionPushable, residualQuery } from "@omgbase/oqx";
 import { makeStoreContext, tagRows } from "./context.js";
-import { translatePredicate } from "./sql/translate.js";
+import { translatePredicate, RESERVED_DOC_BASENAMES } from "./sql/translate.js";
 const ALIAS = {
     docs: { self: "d", doc: "d" },
     blocks: { self: "b", doc: "d" },
@@ -56,6 +62,91 @@ function rootTarget(source) {
     }
     return null;
 }
+// ---- the residual walk (decline (c)) -----------------------------------------
+/**
+ * True when evaluating `where` in memory could raise an OQX error the pushed
+ * conjuncts might hide by emptying the scan. The walk is generic over the whole
+ * residual tree — every `Where` node, every nested block (its `from`, `where`,
+ * `select`, `order by`, `follow`, `limit`/`offset`) and every `Expr` — and flags:
+ *
+ *   • 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
+ *     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 residual made only of comparisons, logical operators, `in`/ranges, `!`,
+ * literals, bindings and plain reads (including exists/none/count/collect/first
+ * blocks of the same) cannot raise, so the pushed conjuncts are kept.
+ */
+export function residualMayRaise(where, target) {
+    return where !== null && whereMayRaise(where, target, true);
+}
+function whereMayRaise(w, target, root) {
+    switch (w.kind) {
+        case "and":
+        case "or": return w.parts.some((p) => whereMayRaise(p, target, root));
+        case "not": return whereMayRaise(w.expr, target, root);
+        case "scalar": return exprMayRaise(w.expr, target, root);
+        case "op": return opMayRaise(w, target, root);
+    }
+}
+function opMayRaise(op, target, root) {
+    if (op.op === "single")
+        return true;
+    return exprMayRaise(op.receiver, target, root) || subMayRaise(op.sub, target);
+}
+// Inside a block the rows are a different scope (a relation's rows), so a bare
+// reserved name is an ordinary read there — only `doc.<reserved>` still raises.
+function subMayRaise(s, target) {
+    if (s.from.some((e) => exprMayRaise(e, target, false)))
+        return true;
+    if (s.where && whereMayRaise(s.where, target, false))
+        return true;
+    for (const item of s.select) {
+        if (item.kind === "field") {
+            if (item.lift > 0 || exprMayRaise(item.expr, target, false))
+                return true;
+        }
+        else if (opMayRaise(item.op, target, false))
+            return true;
+    }
+    if (s.orderBy?.some((o) => exprMayRaise(o.expr, target, false)))
+        return true;
+    if (s.follow && followMayRaise(s.follow, target))
+        return true;
+    if (s.limit && exprMayRaise(s.limit, target, false))
+        return true;
+    if (s.offset && exprMayRaise(s.offset, target, false))
+        return true;
+    return false;
+}
+function followMayRaise(f, target) {
+    return [f.receiver, f.where, f.frontier, f.by].some((e) => e !== null && exprMayRaise(e, target, false));
+}
+function exprMayRaise(e, target, root) {
+    switch (e.kind) {
+        case "call": return true;
+        case "outer": return true;
+        case "ident": return root && target === "docs" && RESERVED_DOC_BASENAMES.has(e.name);
+        case "member":
+            if (e.recv.kind === "ident" && e.recv.name === "doc" && RESERVED_DOC_BASENAMES.has(e.name))
+                return true;
+            return exprMayRaise(e.recv, target, root);
+        case "index": return exprMayRaise(e.recv, target, root) || exprMayRaise(e.index, target, root);
+        case "unary": return exprMayRaise(e.expr, target, root);
+        case "binary":
+        case "logical":
+        case "in":
+            return exprMayRaise(e.left, target, root) || exprMayRaise(e.right, target, root);
+        case "range":
+            return (e.lo !== null && exprMayRaise(e.lo, target, root)) || (e.hi !== null && exprMayRaise(e.hi, target, root));
+        case "lit":
+        case "binding": return false;
+    }
+}
+// ---- the planner -------------------------------------------------------------
 export class SQLiteQueryPlanner {
     store;
     repoId;
@@ -76,6 +167,8 @@ export class SQLiteQueryPlanner {
         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
+        if (residualMayRaise(residual, target))
+            return null; // decline (c): run unplanned
         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 ");

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

@@ -4,7 +4,7 @@
 // keyset pagination, count/exists scalars). Same signature + shape as the former
 // in-tree compiler, so every caller and the corpus are unchanged.
 import { parse, PlannedEngine, InMemoryEngine, OqxError } from "@omgbase/oqx";
-import { makeStoreContext } from "./context.js";
+import { makeStoreContext, rowRef } from "./context.js";
 import { SQLiteQueryPlanner } from "./planner.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { float32ToBlob } from "../core/vec.js";
@@ -194,10 +194,35 @@ const PATH_ITEM = { kind: "field", name: "__oqx_path", expr: { kind: "ident", na
 // so it rides through id/path injection, keyset paging, and distinct as an
 // ordinary record field and is peeled off at the end.
 const VALUE_KEY = "__oqx_value";
+// Rows as values (spec/surface §1.4, 1.2). The engine hands back store rows
+// wherever the projection made a row a VALUE — a nested `collect { }` /
+// `first { }` / `single { }` with an empty projection ("the row itself",
+// spec/oqx §12), a `values` projection of `$value`/`$self`, a field bound to a
+// row — and a store row is not a wire shape (column names, `attrs` as a JSON
+// string, the `__path` join column, Buffers). Walk the projected value and
+// render every tagged row as `{ id, path }`; everything else passes through
+// untouched (plain records and arrays are descended, scalars kept). Hits are
+// records the engine built from the injected id/path items, never rows.
+function renderValue(v) {
+    if (v === null || typeof v !== "object")
+        return v;
+    const ref = rowRef(v);
+    if (ref)
+        return ref;
+    if (Array.isArray(v))
+        return v.map(renderValue);
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null)
+        return v; // Buffer, Map, … — not a record
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+        out[k] = renderValue(x);
+    return out;
+}
 function toHit(row) {
     const o = row;
     const { __oqx_id, __oqx_path, ...rest } = o;
-    return { id: String(__oqx_id), path: String(__oqx_path ?? ""), ...rest };
+    return { id: String(__oqx_id), path: String(__oqx_path ?? ""), ...renderValue(rest) };
 }
 // Top-level `select distinct`: dedup hits by their USER projection (every field
 // except the injected id/path), keeping the first (so the retained hit carries a

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

@@ -19,9 +19,79 @@ export interface Frag {
     sql: string;
     params: unknown[];
 }
+/**
+ * What a translated operand denotes, for the comparison matrix (spec/surface §1
+ * decline (a)):
+ *
+ *   text  a string literal/binding, a text column or intrinsic, `.lower()`/`.upper()`
+ *   int   an integer-typed intrinsic column (blocks `$ordinal`, `$depth`)
+ *   num   a number literal/binding
+ *   bool  a boolean literal/binding
+ *   null  a null (or undefined) literal/binding
+ *   json  a JSON read: an `attrs` path or a bare attribute name on blocks/nodes (json_extract)
+ *   prop  a document property read: a bare key on docs or `doc.<k>` (the scalar-in-scope subquery)
+ */
+export type OperandKind = "text" | "int" | "num" | "bool" | "null" | "json" | "prop";
+/** A value-position fragment with the kind of value it denotes. */
+export interface Operand extends Frag {
+    kind: OperandKind;
+}
+/**
+ * Per target, the bare identifiers (and `doc.<k>` keys, via the docs set) that
+ * `context.ts` resolves to something other than a scalar field or property: the
+ * self alias, the reach-through handles, the relations, the property source
+ * handles and (blocks/nodes) the whole `attrs` object. A comparison naming one of
+ * these is declined (spec/surface §1 decline (b)) — read as a property it would
+ * be `NULL`, where in memory the value is a row, an array or an object.
+ * `translate.test.ts` asserts this set against the store context.
+ */
+export declare const NON_PROPERTY_NAMES: Readonly<Record<Target, ReadonlySet<string>>>;
+/** docs intrinsics whose BARE (non-$) form is a loud error in-memory (10 §2) — not
+ * pushable, so the residual raises it (and the planner keeps the whole query
+ * unplanned when one is residual: spec/surface §1 decline (c)). */
+export declare const RESERVED_DOC_BASENAMES: ReadonlySet<string>;
 /** Translate an expression used as a VALUE (comparison operand, method receiver,
- * function argument) to a SQL scalar. Returns null if not faithfully translatable. */
+ * function argument) to a SQL scalar with its operand kind. Returns null if not
+ * faithfully translatable. */
+export declare function translateOperand(e: Expr, ctx: TranslateCtx): Operand | null;
+/** `translateOperand` without the kind — the plain fragment. */
 export declare function translateValue(e: Expr, ctx: TranslateCtx): Frag | null;
+/**
+ * The comparison rule (spec/surface §1, decline (a)), stated positively: a
+ * comparison is pushed only when its two operand kinds are provably compared
+ * the same way by SQLite and by the in-memory `equals`/`compare`.
+ *
+ *   Equality (`==`, `!=`) pushes iff
+ *     • one operand is text — SQLite's typed `IS` and strict `===` agree that a
+ *       string equals nothing but an equal string (`5 IS '5'` is false);
+ *     • or one operand is null and the other is NOT a property read — the same
+ *       absence both ways, except that a list-valued or nested property has no
+ *       scalar row (SQL NULL) where in memory the value is an array or object;
+ *     • or both operands are numeric (int or num) — an exact integer comparison.
+ *   Relational (`<`, `<=`, `>`, `>=`) pushes iff both operands are text or both
+ *     are numeric.
+ *   Every other pair declines: SQLite sees JSON `true` and `1`, `val_bool` and
+ *     `val_num` alike (`checked == 1`, `$ordinal == checked`, `verified == 1`),
+ *     orders every 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`).
+ *
+ * The resulting grid (P = pushed, D = declined; symmetric) for `==` / `!=`:
+ *
+ *            text  int   num   bool  null  json  prop
+ *   text      P     P     P     P     P     P     P
+ *   int       P     P     P     D     P     D     D
+ *   num       P     P     P     D     P     D     D
+ *   bool      P     D     D     D     P     D     D
+ *   null      P     P     P     P     P     P     D
+ *   json      P     D     D     D     P     D     D
+ *   prop      P     D     D     D     D     D     D
+ *
+ * and for `<` `<=` `>` `>=` only text×text, int×int, int×num, num×num push.
+ */
+export declare function comparable(op: string, a: OperandKind, b: OperandKind): boolean;
+/** The complement of `comparable` — kept for readers of the earlier decline-list form. */
+export declare function declinedPair(a: OperandKind, b: OperandKind, op?: string): boolean;
 /** Translate an expression used as a boolean PREDICATE to a SQL boolean, or null
  * if it cannot be pushed faithfully. Only positive, AND-safe forms are handled. */
 export declare function translatePredicate(e: Expr, ctx: TranslateCtx): Frag | null;

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

@@ -9,7 +9,7 @@
 // The cardinal rule is FIDELITY, not cleverness: the SQL a fragment emits MUST
 // evaluate to the same result as `@omgbase/oqx`'s in-memory `semantics.ts` for
 // every input, because the differential conformance suite runs each query BOTH
-// ways and asserts equality. Two consequences drive the design:
+// ways and asserts equality. Three consequences drive the design:
 //
 //   • oqx-js string ops are CASE-SENSITIVE, but SQLite `LIKE` is case-insensitive
 //     for ASCII. So `startsWith`/`contains`/`endsWith` translate to
@@ -22,59 +22,86 @@
 //     `equals(a,b)` including the both-absent and negation cases, while still
 //     honoring SQLite's typed comparison (`5 IS '5'` is false, matching strict
 //     `5 === "5"`).
+//   • SQLite has no boolean and no array/object scalars: JSON `true` reads as
+//     `1`, `val_bool` is 1/0, and a list-valued or nested property has no
+//     `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`).
 //
 // Only forms that are faithful in a POSITIVE, AND-composed context are
 // translated (that is the only context `partitionPushable` pushes into). `||`,
 // `!`, `in`, `matches` (needs a regexp UDF), and bare content-property routing
 // are deliberately declined here and left residual for now.
+// ---- names that are never property reads ------------------------------------
+/**
+ * Per target, the bare identifiers (and `doc.<k>` keys, via the docs set) that
+ * `context.ts` resolves to something other than a scalar field or property: the
+ * self alias, the reach-through handles, the relations, the property source
+ * handles and (blocks/nodes) the whole `attrs` object. A comparison naming one of
+ * these is declined (spec/surface §1 decline (b)) — read as a property it would
+ * be `NULL`, where in memory the value is a row, an array or an object.
+ * `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"]),
+    nodes: new Set(["section", "doc", "block", "blocks", "subsections", "children", "attrs"]),
+    edges: new Set(["doc"]),
+};
 // ---- intrinsics -------------------------------------------------------------
-// A `$`-namespaced intrinsic → a param-free SQL scalar, per target. Anything not
-// mapped (e.g. docs `$body`, reconstructed; `$title`/`$tags`, computed) returns
-// null → residual. `$updated_at`/`$dst_path`/`$dst_uri` are correlated subqueries.
+// 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.
 function intrinsicSql(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 `${self}.doc_id`;
-            case "$path": return `${doc}.path`;
-            case "$content_hash": return `lower(hex(${self}.file_hash))`;
-            case "$updated_at": return `(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 text(`${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)`);
         }
     else if (target === "blocks")
         switch (name) {
-            case "$id": return `${self}.block_id`;
-            case "$doc": return `${self}.doc_id`;
-            case "$path": return `${doc}.path`;
-            case "$ordinal": return `${self}.ordinal`;
-            case "$depth": return `${self}.depth`;
-            case "$body": return `${self}.text`;
-            case "$content_hash": return `lower(hex(${self}.raw_hash))`;
+            case "$id": return text(`${self}.block_id`);
+            case "$doc": return text(`${self}.doc_id`);
+            case "$path": return text(`${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))`);
         }
     else if (target === "nodes")
         switch (name) {
             case "$id":
-            case "$node_id": return `${self}.node_id`;
-            case "$doc_id": return `${self}.doc_id`;
-            case "$block_id": return `${self}.block_id`;
-            case "$path": return `${doc}.path`;
+            case "$node_id": return text(`${self}.node_id`);
+            case "$doc_id": return text(`${self}.doc_id`);
+            case "$block_id": return text(`${self}.block_id`);
+            case "$path": return text(`${doc}.path`);
         }
     else if (target === "edges")
         switch (name) {
-            case "$id": return `${self}.edge_id`;
-            case "$src": return `${self}.src_doc`;
-            case "$dst": return `${self}.dst_node`;
-            case "$src_block": return `${self}.src_block`;
-            case "$via": return `${self}.via_node`;
-            case "$from_commit": return `${self}.from_commit`;
-            case "$path": return `${doc}.path`;
-            case "$dst_path": return `(SELECT dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`;
-            case "$dst_uri": return `(SELECT xn.uri FROM external_nodes xn WHERE xn.node_id = ${self}.dst_node)`;
+            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 text(`${doc}.path`);
+            case "$dst_path": return text(`(SELECT dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`);
+            case "$dst_uri": return text(`(SELECT xn.uri FROM external_nodes xn WHERE xn.node_id = ${self}.dst_node)`);
         }
     return null;
 }
-// docs intrinsics whose BARE (non-$) form is a loud error in-memory (10 §2) — not
-// pushable, so the residual raises it.
-const RESERVED_DOC_BASENAMES = new Set(["id", "path", "updated_at", "content_hash", "body"]);
+/** 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"]);
 const SEG = /^[A-Za-z_][A-Za-z0-9_]*$/; // injection-safe inlined identifier
 // A single-valued document property (the CEL scalar-in-scope rule): the scalar
 // value only when the key has exactly one row in scope and it is card='scalar',
@@ -82,23 +109,33 @@ const SEG = /^[A-Za-z_][A-Za-z0-9_]*$/; // injection-safe inlined identifier
 function propScalar(docAlias, key) {
     if (!SEG.test(key))
         return null;
-    return `(SELECT COALESCE(p.val_text, p.val_num, p.val_bool) FROM properties p
+    return {
+        sql: `(SELECT COALESCE(p.val_text, p.val_num, p.val_bool) 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
-           LIMIT 1)`;
+           LIMIT 1)`,
+        params: [],
+        kind: "prop",
+    };
 }
 // json_extract path from validated segments, or null if any segment is unsafe.
 function jsonExtract(col, segs) {
     if (segs.some((s) => !SEG.test(s)))
         return null;
-    return `json_extract(${col}, '$.${segs.join(".")}')`;
+    return { sql: `json_extract(${col}, '$.${segs.join(".")}')`, params: [], kind: "json" };
 }
-// better-sqlite3 binds only number/string/bigint/buffer/null — coerce booleans
-// to 1/0 (matching how json_extract surfaces JSON booleans, so `attrs.b == true`
-// compares against `1`). Non-bindable values are left as-is (they only reach a
-// bound `?` for lit/binding operands, which are scalars in practice).
-function bindable(v) {
-    return typeof v === "boolean" ? (v ? 1 : 0) : v;
+// A literal or binding value as a bound `?` with its kind. better-sqlite3 binds
+// only number/string/bigint/buffer/null — booleans are coerced to 1/0 (how
+// json_extract surfaces JSON booleans); anything else (an array binding, say) is
+// not a scalar and declines.
+function constOperand(v) {
+    switch (typeof v) {
+        case "string": return { sql: "?", params: [v], kind: "text" };
+        case "number": return { sql: "?", params: [v], kind: "num" };
+        case "boolean": return { sql: "?", params: [v ? 1 : 0], kind: "bool" };
+        case "undefined": return { sql: "?", params: [null], kind: "null" };
+        default: return v === null ? { sql: "?", params: [null], kind: "null" } : null;
+    }
 }
 // The dotted `attrs.a.b` / `doc.x` receiver chain as segments, or null if it is
 // not a plain identifier navigation.
@@ -113,46 +150,47 @@ function memberSegments(e) {
 }
 // ---- value position ---------------------------------------------------------
 /** Translate an expression used as a VALUE (comparison operand, method receiver,
- * function argument) to a SQL scalar. Returns null if not faithfully translatable. */
-export function translateValue(e, ctx) {
+ * function argument) to a SQL scalar with its operand kind. Returns null if not
+ * faithfully translatable. */
+export function translateOperand(e, ctx) {
     const { self, doc, target } = ctx;
+    const text = (sql) => ({ sql, params: [], kind: "text" });
     switch (e.kind) {
         case "lit":
-            return { sql: "?", params: [bindable(e.value)] };
+            return constOperand(e.value);
         case "binding":
-            return { sql: "?", params: [bindable(ctx.params[e.index])] };
+            return constOperand(ctx.params[e.index]);
         case "ident": {
-            if (e.name.startsWith("$")) {
-                const sql = intrinsicSql(e.name, ctx);
-                return sql ? { sql, params: [] } : null;
-            }
+            if (e.name.startsWith("$"))
+                return intrinsicSql(e.name, ctx);
+            // A relation, reach-through, source handle or the whole attrs object is not a
+            // scalar read (decline (b)).
+            if (NON_PROPERTY_NAMES[target].has(e.name))
+                return null;
             // Bare field per target.
             if (target === "docs") {
                 if (e.name === "format")
-                    return { sql: `${self}.format`, params: [] }; // a column, not a property
+                    return text(`${self}.format`); // a column, not a property
                 if (RESERVED_DOC_BASENAMES.has(e.name))
                     return null; // residual raises the guard
-                const sql = propScalar(doc, e.name);
-                return sql ? { sql, params: [] } : null;
+                return propScalar(doc, e.name);
             }
             if (target === "blocks") {
                 if (e.name === "type" || e.name === "text")
-                    return { sql: `${self}.${e.name}`, params: [] };
+                    return text(`${self}.${e.name}`);
                 // Bare non-structural identifier flattens into attrs — same pushdown as
                 // the `attrs.<k>` member form (json_extract), so `checked` == `attrs.checked`.
-                const sql = jsonExtract(`${self}.attrs`, [e.name]);
-                return sql ? { sql, params: [] } : null;
+                return jsonExtract(`${self}.attrs`, [e.name]);
             }
             if (target === "nodes") {
                 if (e.name === "kind" || e.name === "name" || e.name === "value")
-                    return { sql: `${self}.${e.name}`, params: [] };
+                    return text(`${self}.${e.name}`);
                 // Bare non-structural identifier flattens into attrs (see blocks above).
-                const sql = jsonExtract(`${self}.attrs`, [e.name]);
-                return sql ? { sql, params: [] } : null;
+                return jsonExtract(`${self}.attrs`, [e.name]);
             }
             if (target === "edges") {
                 if (["predicate", "provenance", "dst_kind", "anchor", "src_field"].includes(e.name))
-                    return { sql: `${self}.${e.name}`, params: [] };
+                    return text(`${self}.${e.name}`);
                 return null;
             }
             return null;
@@ -164,8 +202,7 @@ export function translateValue(e, ctx) {
             const [head, ...rest] = segs;
             // attrs.<path> → json_extract on the row's attrs (blocks/nodes).
             if (head === "attrs" && (target === "blocks" || target === "nodes")) {
-                const sql = jsonExtract(`${self}.attrs`, rest);
-                return sql ? { sql, params: [] } : null;
+                return jsonExtract(`${self}.attrs`, rest);
             }
             // 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`.
@@ -174,29 +211,31 @@ export function translateValue(e, ctx) {
                     return null;
                 const k = rest[0];
                 if (k === "$path")
-                    return { sql: `${doc}.path`, params: [] };
+                    return text(`${doc}.path`);
                 if (k === "format")
-                    return { sql: `${doc}.format`, params: [] };
+                    return text(`${doc}.format`);
                 if (k.startsWith("$"))
                     return null;
                 if (RESERVED_DOC_BASENAMES.has(k))
                     return null;
-                const sql = propScalar(doc, k);
-                return sql ? { sql, params: [] } : null;
+                if (NON_PROPERTY_NAMES.docs.has(k))
+                    return null; // `doc.nodes`, `doc.frontmatter`, … (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 { sql: `(SELECT bb.${rest[0]} FROM blocks bb WHERE bb.block_id = ${self}.block_id)`, params: [] };
+                return text(`(SELECT bb.${rest[0]} FROM blocks bb WHERE bb.block_id = ${self}.block_id)`);
             }
             return null;
         }
         case "call": {
-            // `.lower()` / `.upper()` are the value-position string methods.
+            // `.lower()` / `.upper()` are the value-position string methods; their
+            // output is text whatever the receiver.
             if (e.recv !== null && e.args.length === 0 && (e.name === "lower" || e.name === "upper")) {
-                const recv = translateValue(e.recv, ctx);
+                const recv = translateOperand(e.recv, ctx);
                 if (!recv)
                     return null;
-                return { sql: `${e.name}(${recv.sql})`, params: recv.params };
+                return { sql: `${e.name}(${recv.sql})`, params: recv.params, kind: "text" };
             }
             return null;
         }
@@ -204,6 +243,11 @@ export function translateValue(e, ctx) {
             return null;
     }
 }
+/** `translateOperand` without the kind — the plain fragment. */
+export function translateValue(e, ctx) {
+    const o = translateOperand(e, ctx);
+    return o ? { sql: o.sql, params: o.params } : null;
+}
 // ---- predicate position -----------------------------------------------------
 const IS_OP = {
     "==": "IS",
@@ -213,6 +257,55 @@ const IS_OP = {
     ">": ">",
     ">=": ">=",
 };
+/**
+ * The comparison rule (spec/surface §1, decline (a)), stated positively: a
+ * comparison is pushed only when its two operand kinds are provably compared
+ * the same way by SQLite and by the in-memory `equals`/`compare`.
+ *
+ *   Equality (`==`, `!=`) pushes iff
+ *     • one operand is text — SQLite's typed `IS` and strict `===` agree that a
+ *       string equals nothing but an equal string (`5 IS '5'` is false);
+ *     • or one operand is null and the other is NOT a property read — the same
+ *       absence both ways, except that a list-valued or nested property has no
+ *       scalar row (SQL NULL) where in memory the value is an array or object;
+ *     • or both operands are numeric (int or num) — an exact integer comparison.
+ *   Relational (`<`, `<=`, `>`, `>=`) pushes iff both operands are text or both
+ *     are numeric.
+ *   Every other pair declines: SQLite sees JSON `true` and `1`, `val_bool` and
+ *     `val_num` alike (`checked == 1`, `$ordinal == checked`, `verified == 1`),
+ *     orders every 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`).
+ *
+ * The resulting grid (P = pushed, D = declined; symmetric) for `==` / `!=`:
+ *
+ *            text  int   num   bool  null  json  prop
+ *   text      P     P     P     P     P     P     P
+ *   int       P     P     P     D     P     D     D
+ *   num       P     P     P     D     P     D     D
+ *   bool      P     D     D     D     P     D     D
+ *   null      P     P     P     P     P     P     D
+ *   json      P     D     D     D     P     D     D
+ *   prop      P     D     D     D     D     D     D
+ *
+ * and for `<` `<=` `>` `>=` only text×text, int×int, int×num, num×num push.
+ */
+export function comparable(op, a, b) {
+    const numeric = (k) => k === "int" || k === "num";
+    const bothNumeric = numeric(a) && numeric(b);
+    if (op === "==" || op === "!=") {
+        if (a === "text" || b === "text")
+            return true;
+        if ((a === "null" && b !== "prop") || (b === "null" && a !== "prop"))
+            return true;
+        return bothNumeric;
+    }
+    return (a === "text" && b === "text") || bothNumeric;
+}
+/** The complement of `comparable` — kept for readers of the earlier decline-list form. */
+export function declinedPair(a, b, op = "==") {
+    return !comparable(op, a, b);
+}
 /** Translate an expression used as a boolean PREDICATE to a SQL boolean, or null
  * if it cannot be pushed faithfully. Only positive, AND-safe forms are handled. */
 export function translatePredicate(e, ctx) {
@@ -236,10 +329,12 @@ function translateComparison(e, ctx) {
     const op = IS_OP[e.op];
     if (!op)
         return null; // arithmetic operator in predicate position → residual
-    const l = translateValue(e.left, ctx);
-    const r = translateValue(e.right, ctx);
+    const l = translateOperand(e.left, ctx);
+    const r = translateOperand(e.right, ctx);
     if (!l || !r)
         return null;
+    if (!comparable(e.op, l.kind, r.kind))
+        return null; // decline (a): the positive comparison rule
     // `==`/`!=` → null-safe IS / IS NOT (absence-normalized equality, faithful in
     // any context). Relational ops → plain SQL: a NULL operand yields NULL, which
     // is excluded in the positive AND context these fragments are pushed into,