@omgbase/core 0.3.0 → 0.4.1

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,83 +22,133 @@
 //     `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`). A bool or num literal against a JSON or property
+//     read is a TYPED push (the 1.2 patch): the stored type is tested in SQL
+//     before the value (`json_type(x) = 'true'`, `p.type = 'number' AND
+//     p.val_num >= ?`) and the whole test is wrapped `(…) IS 1` / `IS NOT 1`,
+//     so an absent or differently typed value compares as in memory —
+//     unequal, never ordered. See `typedComparison`.
 //
 // 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',
+// The single-scalar-row scope of a document property (the CEL scalar-in-scope
+// rule): the row for `key` on the document only when the key has exactly one
+// row in scope and it is card='scalar' — a list-valued or nested key has none.
+// `select` is the projected expression over the alias `p`.
+function propSubquery(docAlias, key, select) {
+    return `(SELECT ${select} FROM properties p
+           WHERE p.doc_id = ${docAlias}.doc_id AND p.key = '${key}' AND p.card = 'scalar' AND p.deleted_commit IS NULL
+             AND (SELECT COUNT(*) FROM properties p2 WHERE p2.doc_id = ${docAlias}.doc_id AND p2.key = '${key}' AND p2.deleted_commit IS NULL) = 1
+           LIMIT 1)`;
+}
+// A single-valued document property: the scalar value of its one row in scope,
 // else NULL — matching the store context's `docProp` for a scalar read.
 function propScalar(docAlias, key) {
     if (!SEG.test(key))
         return null;
-    return `(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)`;
+    return {
+        sql: propSubquery(docAlias, key, "COALESCE(p.val_text, p.val_num, p.val_bool)"),
+        params: [],
+        kind: "prop",
+        prop: { docAlias, key },
+    };
 }
 // 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(".")}')`;
+    const path = `'$.${segs.join(".")}'`;
+    return { sql: `json_extract(${col}, ${path})`, params: [], kind: "json", json: { col, path } };
 }
-// 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 and `val_bool` surface 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", value: v };
+        case "number": return { sql: "?", params: [v], kind: "num", value: v };
+        case "boolean": return { sql: "?", params: [v ? 1 : 0], kind: "bool", value: v };
+        case "undefined": return { sql: "?", params: [null], kind: "null", value: null };
+        default: return v === null ? { sql: "?", params: [null], kind: "null", value: 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 +163,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 +215,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 +224,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 +256,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 +270,81 @@ 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 PLAINLY (`IS` / `IS NOT`) 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 plainly iff both operands are text
+ *     or both are numeric.
+ *   TYPED pushes (the 1.2 patch, `typedComparison`): a bool literal/binding
+ *     against a json or prop read (`==`, `!=` only) and a num literal/binding
+ *     against a json or prop read (every op) push with the stored type tested
+ *     first — `json_type(x) = 'true'`, `json_type(x) IN ('integer','real') AND
+ *     json_extract(x) <op> ?`, `p.type = 'bool' AND p.val_bool = ?`, `p.type =
+ *     'number' AND p.val_num <op> ?` — wrapped `(…) IS 1` (or `IS NOT 1` for
+ *     `!=`), so an absent or differently typed value is unequal and never
+ *     ordered, exactly as in memory.
+ *   Every other pair declines: SQLite sees JSON `true` and `1`, `val_bool` and
+ *     `val_num` alike (`$ordinal == checked`, `true == 1`), orders every
+ *     integer before every text (`$ordinal < "3"`, `level < "x"`, `$path > 5`),
+ *     and two JSON or property reads carry no type at plan time
+ *     (`attrs.a == attrs.b`, `era == stages`).
+ *
+ * The resulting grid (P = pushed plainly, T = typed push, 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     T     T
+ *   bool      P     D     D     D     P     T     T
+ *   null      P     P     P     P     P     P     D
+ *   json      P     D     T     T     P     D     D
+ *   prop      P     D     T     T     D     D     D
+ *
+ * and for `<` `<=` `>` `>=` text×text, int×int, int×num, num×num push plainly
+ * and num×json, num×prop push typed.
+ */
+export function comparable(op, a, b) {
+    return plainComparable(op, a, b) || typedPair(op, a, b) !== null;
+}
+// The plain cells of the grid (P): the two operands compare the same way as-is.
+function plainComparable(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 typed cells of the grid (T): which side is the constant (`"left"` /
+// `"right"`), or null when the pair is not a typed push. A bool constant pushes
+// typed only under `==` / `!=` (booleans never order); a num constant under any op.
+function typedPair(op, a, b) {
+    const read = (k) => k === "json" || k === "prop";
+    const constant = (k) => k === "num" || (k === "bool" && (op === "==" || op === "!="));
+    if (constant(a) && read(b))
+        return "left";
+    if (constant(b) && read(a))
+        return "right";
+    return null;
+}
+/** 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,15 +368,67 @@ 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;
-    // `==`/`!=` → 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,
-    // matching `relate`'s absent-operand ⇒ false rule.
-    return { sql: `(${l.sql} ${op} ${r.sql})`, params: [...l.params, ...r.params] };
+    if (plainComparable(e.op, l.kind, r.kind)) {
+        // `==`/`!=` → 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,
+        // matching `relate`'s absent-operand ⇒ false rule.
+        return { sql: `(${l.sql} ${op} ${r.sql})`, params: [...l.params, ...r.params] };
+    }
+    const side = typedPair(e.op, l.kind, r.kind);
+    if (side === null)
+        return null; // decline (a): the positive comparison rule
+    // Normalize to <read> <op> <constant>, flipping a relational op when the
+    // constant is on the left (`800 < era` ⇔ `era > 800`).
+    return side === "right" ? typedComparison(e.op, l, r) : typedComparison(FLIP[e.op] ?? e.op, r, l);
+}
+const FLIP = { "<": ">", "<=": ">=", ">": "<", ">=": "<=" };
+/**
+ * The typed push (spec/surface §1, 1.2 patch): `read <op> constant` where the
+ * read is a JSON or property read and the constant a bool or num literal/binding.
+ * The stored type is tested before the value, and the whole test is wrapped
+ * `(…) IS 1` for `==` and the relational ops, `(…) IS NOT 1` for `!=` — so a
+ * NULL (absent path, no scalar row) or a `0` (other type, unequal value) reads
+ * as "not equal" / "not ordered", which is the in-memory answer: `checked == 1`
+ * finds nothing, `checked != 1` everything, `level >= 2` only numeric levels.
+ *
+ *   json × bool   (json_type(col, path) = 'true'|'false') IS [NOT] 1        no bind: the type string IS the value
+ *   json × num    (json_type(col, path) IN ('integer','real') AND json_extract(col, path) <op> ?) IS [NOT] 1
+ *   prop × bool   (SELECT p.type = 'bool' AND p.val_bool = ? FROM properties p WHERE <scope> LIMIT 1) IS [NOT] 1   ? = 1|0
+ *   prop × num    (SELECT p.type = 'number' AND p.val_num <op> ? FROM properties p WHERE <scope> LIMIT 1) IS [NOT] 1
+ *
+ * where <op> is `=` for both `==` and `!=` (the `!=` case negates the equality
+ * by its `IS NOT 1` wrap) and the relational operator itself otherwise.
+ *
+ * `<scope>` is `propSubquery`'s single-scalar-row condition, so a list-valued or
+ * nested key yields NULL → unequal/unordered, as in memory.
+ */
+function typedComparison(op, read, constant) {
+    // `!=` is `!equals`: the EQUALITY test, wrapped IS NOT 1 (never `<>` inside —
+    // `(type AND val <> ?) IS NOT 1` would drop every row of the right type with a
+    // different value, the differential caught it).
+    const wrap = op === "!=" ? "IS NOT 1" : "IS 1";
+    const cmp = op === "==" || op === "!=" ? "=" : op;
+    if (read.json) {
+        const { col, path } = read.json;
+        if (constant.kind === "bool") {
+            return { sql: `((json_type(${col}, ${path}) = '${constant.value ? "true" : "false"}') ${wrap})`, params: [] };
+        }
+        return {
+            sql: `((json_type(${col}, ${path}) IN ('integer', 'real') AND json_extract(${col}, ${path}) ${cmp} ?) ${wrap})`,
+            params: [...constant.params],
+        };
+    }
+    if (read.prop) {
+        const { docAlias, key } = read.prop;
+        const test = constant.kind === "bool" ? `p.type = 'bool' AND p.val_bool = ?` : `p.type = 'number' AND p.val_num ${cmp} ?`;
+        return { sql: `(${propSubquery(docAlias, key, test)} ${wrap})`, params: [...constant.params] };
+    }
+    return null;
 }
 // startsWith / contains / endsWith — CASE-SENSITIVE, via substr/instr (never
 // LIKE). `matches` (regex) is declined until a `regexp` UDF is registered.

package/dist/src/search/tasks.d.ts

@@ -28,8 +28,22 @@ export declare function makeBlockContextResolver(store: Store, scope: {
 } | {
     docId: string;
 }): BlockContextResolver;
-/** Build EmbedTask[] for every embeddable live block in the repo. */
+/**
+ * Build EmbedTask[] for every embeddable live block in the repo: the live
+ * LEAF blocks (spec/search §2.1, 1.2 — a container's text is its children's
+ * text, so embedding it would pool the same words twice) whose text clears the
+ * `shouldEmbed` floor.
+ */
 export declare function buildEmbedTasks(store: Store, repoId: string): EmbedTask[];
+/**
+ * The embedding queue depth without a provider process (spec/search §2.3): the
+ * embeddable blocks (`buildEmbedTasks`) whose current `(content_hash, ctx_hash)`
+ * has no cached vector — for `model` when one is named (the `embedding.model`
+ * setting), else for any model. `omg status` reports it as `embedQueue`;
+ * `EmbeddingWorker.staleBlocks` is the same test keyed by the connected
+ * provider's model.
+ */
+export declare function staleEmbedCount(store: Store, repoId: string, model?: string): number;
 /**
  * Build DocEmbedTask[] for every live document in the repo (doc-grain semantic
  * retrieval). Each task carries the whole-document embed input (header +

package/dist/src/search/tasks.js

@@ -1,6 +1,7 @@
 import { reconstructContent } from "../core/read/document.js";
 import { docPropertiesMerged } from "../core/store/properties.js";
-import { contextPrefix, shouldEmbed, estimateTokens } from "./embeddings.js";
+import { LIVE_LEAF_SQL } from "../core/store/fts.js";
+import { contextPrefix, ctxHashHex, shouldEmbed, estimateTokens } from "./embeddings.js";
 function docTitle(titleByDoc, firstHeadingByDoc, docId, path) {
     const t = titleByDoc.get(docId);
     if (t && t.trim())
@@ -61,13 +62,18 @@ export function makeBlockContextResolver(store, scope) {
         }),
     };
 }
-/** Build EmbedTask[] for every embeddable live block in the repo. */
+/**
+ * Build EmbedTask[] for every embeddable live block in the repo: the live
+ * LEAF blocks (spec/search §2.1, 1.2 — a container's text is its children's
+ * text, so embedding it would pool the same words twice) whose text clears the
+ * `shouldEmbed` floor.
+ */
 export function buildEmbedTasks(store, repoId) {
     const blocks = store.db
         .prepare(`SELECT b.block_id, b.doc_id, d.path AS path,
               b.ordinal, b.type, b.text, b.raw_hash
        FROM blocks b JOIN docs d ON d.doc_id = b.doc_id
-       WHERE b.repo_id = ? AND b.deleted_commit IS NULL
+       WHERE b.repo_id = ? AND ${LIVE_LEAF_SQL}
        ORDER BY d.path, b.ordinal`)
         .all(repoId);
     const contexts = makeBlockContextResolver(store, { repoId });
@@ -79,6 +85,28 @@ export function buildEmbedTasks(store, repoId) {
     }
     return tasks;
 }
+/**
+ * The embedding queue depth without a provider process (spec/search §2.3): the
+ * embeddable blocks (`buildEmbedTasks`) whose current `(content_hash, ctx_hash)`
+ * has no cached vector — for `model` when one is named (the `embedding.model`
+ * setting), else for any model. `omg status` reports it as `embedQueue`;
+ * `EmbeddingWorker.staleBlocks` is the same test keyed by the connected
+ * provider's model.
+ */
+export function staleEmbedCount(store, repoId, model) {
+    const tasks = buildEmbedTasks(store, repoId);
+    const cached = model
+        ? store.db.prepare("SELECT 1 FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?")
+        : store.db.prepare("SELECT 1 FROM embeddings WHERE content_hash = ? AND ctx_hash = ?");
+    let stale = 0;
+    for (const t of tasks) {
+        const key = [Buffer.from(t.contentHashHex, "hex"), Buffer.from(ctxHashHex(t.ctx), "hex")];
+        const hit = model ? cached.get(...key, model) : cached.get(...key);
+        if (!hit)
+            stale++;
+    }
+    return stale;
+}
 // The doc-embedding header: a lightweight identifying line prepended to the
 // body so schema-y atomic notes (a two-line canon definition) embed with their
 // title + type/layer context rather than as near-empty bodies. Kept minimal and

package/dist/src/sync/admin.d.ts

@@ -57,3 +57,16 @@ export interface SyncStatus {
  *   re-ingested — the exact stale-under-green-light failure this guards against.
  */
 export declare function syncStatus(store: Store, repoId: string, rootPath?: string): SyncStatus;
+/** The `repos` tool's result: every repo of the workspace and whether an `fs` source feeds it. */
+export interface ReposList {
+    repos: {
+        slug: string;
+        hasSource: boolean;
+    }[];
+}
+/**
+ * `repos` (spec/surface §4): the workspace's repos by slug, `hasSource` when an
+ * `fs` source is attached. Shared by the MCP tool and `omg repos --json` so the
+ * shape cannot drift; per-repo counts are `reposStatus`.
+ */
+export declare function reposList(store: Store): ReposList;

package/dist/src/sync/admin.js

@@ -50,4 +50,15 @@ export function syncStatus(store, repoId, rootPath) {
         disk: status.disk,
     };
 }
+/**
+ * `repos` (spec/surface §4): the workspace's repos by slug, `hasSource` when an
+ * `fs` source is attached. Shared by the MCP tool and `omg repos --json` so the
+ * shape cannot drift; per-repo counts are `reposStatus`.
+ */
+export function reposList(store) {
+    const rows = store.db
+        .prepare("SELECT r.slug AS slug, MAX(CASE WHEN s.adapter = 'fs' THEN 1 ELSE 0 END) AS has_fs FROM repos r LEFT JOIN attachments a ON a.repo_id = r.repo_id LEFT JOIN sources s ON s.source_id = a.source_id GROUP BY r.repo_id, r.slug ORDER BY r.slug")
+        .all();
+    return { repos: rows.map((r) => ({ slug: r.slug, hasSource: r.has_fs === 1 })) };
+}
 //# sourceMappingURL=admin.js.map