@omgbase/core 0.3.0 → 0.4.0

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,

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

@@ -28,7 +28,12 @@ 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[];
 /**
  * Build DocEmbedTask[] for every live document in the repo (doc-grain semantic

package/dist/src/search/tasks.js

@@ -1,5 +1,6 @@
 import { reconstructContent } from "../core/read/document.js";
 import { docPropertiesMerged } from "../core/store/properties.js";
+import { LIVE_LEAF_SQL } from "../core/store/fts.js";
 import { contextPrefix, shouldEmbed, estimateTokens } from "./embeddings.js";
 function docTitle(titleByDoc, firstHeadingByDoc, docId, path) {
     const t = titleByDoc.get(docId);
@@ -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 });

package/dist/src/sync/external-source.js

@@ -17,7 +17,7 @@ export async function createExternalSource(spec) {
     }
     const rl = createInterface({ input: child.stdout });
     let watchListener = null;
-    const router = messageRouter(rl, (paths) => watchListener?.(paths));
+    const router = messageRouter(rl, (ev) => watchListener?.(ev));
     const died = new Promise((_, reject) => {
         child.once("error", (err) => reject(new Error(`sync adapter '${spec.command}' failed to spawn: ${err.message}`)));
         child.once("exit", (code) => reject(new Error(`sync adapter '${spec.command}' exited early (code ${code ?? "?"})`)));
@@ -69,10 +69,19 @@ export async function createExternalSource(spec) {
         },
         ...(caps.watch
             ? {
-                async watch(onBatch) {
-                    watchListener = onBatch;
+                async watch(listener) {
+                    // `ready` resolves on the adapter's {"event":"ready"}; the listener sees
+                    // it as an event too, in wire order with the batches (spec/sync §5, §8).
+                    let markReady = () => { };
+                    const ready = new Promise((resolve) => { markReady = resolve; });
+                    watchListener = (ev) => {
+                        if (ev.event === "ready")
+                            markReady();
+                        listener(ev);
+                    };
                     await call("watch");
                     return {
+                        ready,
                         async stop() {
                             watchListener = null;
                             try {
@@ -105,9 +114,9 @@ export async function createExternalSource(spec) {
     };
     return source;
 }
-// Demultiplex adapter stdout: {"event":"batch"} lines feed the watch listener;
-// every other line is an id-addressed response buffered for nextResponse().
-function messageRouter(rl, onBatch) {
+// Demultiplex adapter stdout: {"event":…} lines feed the watch listener (ready,
+// batch); every other line is an id-addressed response buffered for nextResponse().
+function messageRouter(rl, onEvent) {
     const buffered = [];
     const waiters = [];
     rl.on("line", (line) => {
@@ -117,7 +126,11 @@ function messageRouter(rl, onBatch) {
         try {
             const peek = JSON.parse(trimmed);
             if (peek.event === "batch") {
-                onBatch(peek.paths ?? []);
+                onEvent({ event: "batch", paths: peek.paths ?? [] });
+                return;
+            }
+            if (peek.event === "ready") {
+                onEvent({ event: "ready" });
                 return;
             }
         }

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

@@ -25,13 +25,38 @@ export interface SourceItem extends SourceEntry {
     /** The engine hashes this itself for the authoritative echo/convergence gate. */
     content: string;
 }
-/** A batch of changed storage-keys delivered by a live watch (13 §4.3). */
-export type WatchListener = (paths: string[]) => void;
+/**
+ * An unsolicited event of a live watch (spec/sync §5): `ready` once — the feed
+ * is primed and every change from now on will be reported — then `batch` lines
+ * of changed storage keys. An adapter built before sync 1.2 never sends `ready`.
+ */
+export type WatchEvent = {
+    event: "ready";
+} | {
+    event: "batch";
+    paths: string[];
+};
+/** Receives every event of a live watch, in wire order. */
+export type WatchListener = (event: WatchEvent) => void;
 /** A live subscription created by SyncSource.watch. */
 export interface SourceWatch {
-    /** Stop delivering batches and release resources. */
+    /**
+     * Resolves when the source reported `ready` (spec/sync §5). An in-process
+     * source resolves it at once; an adapter that never reports leaves it pending,
+     * so a host bounds the wait (`awaitReady`).
+     */
+    ready: Promise<void>;
+    /** Stop delivering events and release resources. */
     stop(): Promise<void>;
 }
+/** How long a host waits for `ready` before proceeding as if ready (spec/sync §5: unpinned; 30 s). */
+export declare const WATCH_READY_PATIENCE_MS = 30000;
+/**
+ * Wait for a watch's `ready` with bounded patience: `true` when it resolved in
+ * time, `false` on timeout (the host proceeds as if ready, with a warning — an
+ * adapter without `ready` still works, with the old window).
+ */
+export declare function awaitReady(ready: Promise<void>, patienceMs?: number): Promise<boolean>;
 /**
  * The in-engine handle to an external source process. Only capabilities/
  * enumerate/fetch are always meaningful; watch exists when capabilities().watch,
@@ -43,8 +68,8 @@ export interface SyncSource {
     enumerate(): Promise<SourceEntry[]>;
     /** Current state of one member, or null if it left the scope (a delete). */
     fetch(path: string): Promise<SourceItem | null>;
-    /** Subscribe to debounced change batches (push sources). */
-    watch?(onBatch: WatchListener): Promise<SourceWatch>;
+    /** Subscribe to the change feed (push sources): `ready` once, then debounced `batch` events. */
+    watch?(listener: WatchListener): Promise<SourceWatch>;
     /** Persist engine-authored bytes back to the source (writeThrough only). */
     write?(path: string, content: string): Promise<void>;
     /** Remove a member from the source (writeThrough only). */

package/dist/src/sync/plugin.js

@@ -8,5 +8,17 @@
 // reconciliation, commits, convergence, and durable revision/cursor state — so a
 // source only reports membership and transports bytes; it can never write a
 // commit, mint identity, or bypass the convergence check.
-export {};
+/** How long a host waits for `ready` before proceeding as if ready (spec/sync §5: unpinned; 30 s). */
+export const WATCH_READY_PATIENCE_MS = 30_000;
+/**
+ * Wait for a watch's `ready` with bounded patience: `true` when it resolved in
+ * time, `false` on timeout (the host proceeds as if ready, with a warning — an
+ * adapter without `ready` still works, with the old window).
+ */
+export function awaitReady(ready, patienceMs = WATCH_READY_PATIENCE_MS) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), patienceMs);
+        ready.then(() => { clearTimeout(timer); resolve(true); }, () => { clearTimeout(timer); resolve(false); });
+    });
+}
 //# sourceMappingURL=plugin.js.map

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

@@ -14,6 +14,8 @@ export declare class Watcher {
     private sub;
     constructor(store: Store, repoId: string, source: SyncSource, opts?: WatcherOptions);
     start(): Promise<void>;
+    /** The live subscription's `ready` (spec/sync §5); throws before `start()`. */
+    ready(): Promise<void>;
     private ingest;
     stop(): Promise<void>;
 }