@omgbase/core 0.3.0 → 0.4.1

package/dist/src/mutate/docs.d.ts

@@ -13,11 +13,30 @@ export interface DocOpContext {
     actor?: string;
     /** Commit timestamp (RFC 3339 UTC) for every commit the operation records; defaults to now (see `ApplyRequest.ts`). */
     ts?: string;
+    /**
+     * Validate and plan only: every check the real operation makes (`doc_missing`,
+     * `path_taken`, …) runs, nothing is written or committed, and the result
+     * carries `committed: false` plus the per-file `diffs` the operation would
+     * produce — the same shape `apply`'s `dryRun` returns. A create's `docId` is
+     * the id the real run would mint next (a dry run consumes it, as `apply`'s does).
+     */
+    dryRun?: boolean;
 }
 export interface DocOpResult {
     docId: string;
     path: string;
     committed: boolean;
+    /**
+     * With `dryRun`: the file changes the operation would make, keyed by
+     * repo-relative path — `before` the current bytes (`""` for a file that
+     * would be created), `after` the bytes the operation would leave (`""` for a
+     * file that would be removed). A rename is two entries: the old path
+     * emptied, the new path filled. Absent on a committed result.
+     */
+    diffs?: Record<string, {
+        before: string;
+        after: string;
+    }>;
 }
 export interface DocMoveOptions {
     /**

package/dist/src/mutate/docs.js

@@ -3,6 +3,7 @@ import { ingestFile } from "../core/ingest.js";
 import { findDoc, findDocByRef } from "../core/read/reader.js";
 import { makeReconcilingResolver } from "../sync/reconciling-ingest.js";
 import { newCommit } from "../core/store/writers.js";
+import { mintId } from "../core/ids.js";
 import { ftsDeleteDoc } from "../core/store/fts.js";
 import { adoptPhantoms, rebuildDocEdges } from "../core/store/edges.js";
 import { withWriterLock } from "../sync/writer-lock.js";
@@ -38,6 +39,11 @@ export function docsCreate(store, ctx, path, markdown, frontmatter) {
         throw new MutationError("path_taken", `document already exists at ${rel}`);
     const content = composeFile(markdown, frontmatter);
     const docStore = resolveDocStore(ctx);
+    if (ctx.dryRun) {
+        if (docStore.exists(rel))
+            throw new MutationError("path_taken", `file already exists on disk at ${rel}`);
+        return { docId: mintId("d"), path: rel, committed: false, diffs: { [rel]: { before: "", after: content } } };
+    }
     return underLock(ctx, () => {
         if (docStore.exists(rel))
             throw new MutationError("path_taken", `file already exists on disk at ${rel}`);
@@ -67,6 +73,21 @@ export function docsMove(store, ctx, docRef, toPath, opts = {}) {
     // Who links here BY PATH, as written — before the path changes.
     const inbound = inboundLinksTo(store, ctx.repoId, info.docId, info.path);
     const docStore = resolveDocStore(ctx);
+    if (ctx.dryRun) {
+        if (docStore.exists(toRel))
+            throw new MutationError("path_taken", `file already exists on disk at ${toRel}`);
+        const content = docStore.read(info.path) ?? "";
+        const diffs = { [info.path]: { before: content, after: "" }, [toRel]: { before: "", after: content } };
+        const planned = { docId: info.docId, path: toRel, committed: false, diffs };
+        if (!opts.retargetInbound || inbound.length === 0)
+            return { ...planned, dangling: inbound, retargeted: null };
+        const plan = planInboundRetarget(store, info.docId, info.path, toRel, inbound);
+        if (plan.ops.length > 0) {
+            const preview = apply(store, { ...applyCtx(ctx), ops: plan.ops, dryRun: true, origin: { actor: ctx.actor ?? "api", reason: `retarget inbound links ${info.path} -> ${toRel}` } });
+            Object.assign(diffs, preview.diffs ?? {});
+        }
+        return { ...planned, dangling: plan.dangling, retargeted: { blocks: plan.blocks, docs: plan.docs } };
+    }
     const moved = underLock(ctx, () => {
         if (docStore.exists(toRel))
             throw new MutationError("path_taken", `file already exists on disk at ${toRel}`);
@@ -118,6 +139,34 @@ export function docsMove(store, ctx, docRef, toPath, opts = {}) {
     // Rewrite the dangling links block by block (one coalesced update per block,
     // CAS on the block's current hash) and apply as one changeset; the re-ingest
     // re-extracts each source doc, whose links now resolve to the moved doc.
+    const plan = planInboundRetarget(store, info.docId, info.path, toRel, inbound);
+    if (plan.ops.length > 0) {
+        apply(store, {
+            ...applyCtx(ctx),
+            ops: plan.ops,
+            origin: { actor: ctx.actor ?? "api", reason: `retarget inbound links ${info.path} -> ${toRel}` },
+        });
+    }
+    return { ...moved, dangling: plan.dangling, retargeted: { blocks: plan.blocks, docs: plan.docs } };
+}
+/** The `ApplyRequest` fields a document operation's context supplies to a follow-up changeset. */
+function applyCtx(ctx) {
+    return {
+        repoId: ctx.repoId,
+        ...(ctx.rootPath ? { rootPath: ctx.rootPath } : {}),
+        ...(ctx.docStore ? { docStore: ctx.docStore } : {}),
+        ...(ctx.omgbaseDir ? { omgbaseDir: ctx.omgbaseDir } : {}),
+        ...(ctx.ts ? { ts: ctx.ts } : {}),
+    };
+}
+/**
+ * The `retarget_inbound` plan of a move `fromPath → toRel`: one coalesced,
+ * CAS-pinned `update` per deepest hit block, the blocks and docs it touches,
+ * and the inbound links it leaves dangling. Pure over the store's current
+ * blocks — the move itself changes no block — so the real move and its dry run
+ * plan identically.
+ */
+function planInboundRetarget(store, docId, fromPath, toRel, inbound) {
     const byBlock = new Map();
     for (const l of inbound)
         if (l.block !== null && !byBlock.has(l.block))
@@ -150,29 +199,18 @@ export function docsMove(store, ctx, docRef, toPath, opts = {}) {
         // Match against the directory the link was RESOLVED in (the source's path at
         // extraction time); write relative forms against the source's CURRENT
         // directory — they differ only for links inside the moved doc itself.
-        const writeDir = src.doc === info.docId ? dirOf(toRel) : dirOf(src.path);
-        const newRaw = retargetLinksInRaw(row.bytes.toString("utf8"), dirOf(src.path), writeDir, info.path, toRel);
+        const writeDir = src.doc === docId ? dirOf(toRel) : dirOf(src.path);
+        const newRaw = retargetLinksInRaw(row.bytes.toString("utf8"), dirOf(src.path), writeDir, fromPath, toRel);
         if (newRaw === null)
             continue;
         ops.push({ op: "update", block: blockId, markdown: newRaw, expect: { content_hash: row.raw_hash.toString("hex") } });
         blocks.push(blockId);
         docs.add(src.doc);
     }
-    if (ops.length > 0) {
-        apply(store, {
-            repoId: ctx.repoId,
-            ...(ctx.rootPath ? { rootPath: ctx.rootPath } : {}),
-            ...(ctx.docStore ? { docStore: ctx.docStore } : {}),
-            ...(ctx.omgbaseDir ? { omgbaseDir: ctx.omgbaseDir } : {}),
-            ...(ctx.ts ? { ts: ctx.ts } : {}),
-            ops,
-            origin: { actor: ctx.actor ?? "api", reason: `retarget inbound links ${info.path} -> ${toRel}` },
-        });
-    }
     // Containers whose rewritten child covered them count as rewritten too.
     const rewritten = new Set([...blocks, ...containers]);
     const dangling = inbound.filter((l) => l.block === null || !rewritten.has(l.block));
-    return { ...moved, dangling, retargeted: { blocks, docs: [...docs] } };
+    return { ops, blocks, docs: [...docs], dangling };
 }
 /** docs_delete: mark a document deleted and remove its file (resurrection-poolable). */
 export function docsDelete(store, ctx, docRef) {
@@ -180,6 +218,9 @@ export function docsDelete(store, ctx, docRef) {
     if (!info)
         throw new MutationError("doc_missing", `no document ${docRef}`);
     const docStore = resolveDocStore(ctx);
+    if (ctx.dryRun) {
+        return { docId: info.docId, path: info.path, committed: false, diffs: { [info.path]: { before: docStore.read(info.path) ?? "", after: "" } } };
+    }
     return underLock(ctx, () => {
         const ts = nowOr(ctx);
         store.write((db) => {
@@ -201,13 +242,20 @@ export function docsSetMeta(store, ctx, docRef, patch) {
     if (!info)
         throw new MutationError("doc_missing", `no document ${docRef}`);
     const docStore = resolveDocStore(ctx);
-    return underLock(ctx, () => {
+    const patched = () => {
         const original = docStore.read(info.path) ?? "";
         const { frontmatter, body } = splitFrontmatter(original);
         const merged = { ...frontmatter, ...(patch.set ?? {}) };
         for (const k of patch.unset ?? [])
             delete merged[k];
-        const content = composeFile(body, merged);
+        return { original, content: composeFile(body, merged) };
+    };
+    if (ctx.dryRun) {
+        const { original, content } = patched();
+        return { docId: info.docId, path: info.path, committed: false, diffs: { [info.path]: { before: original, after: content } } };
+    }
+    return underLock(ctx, () => {
+        const { content } = patched();
         docStore.write(info.path, content);
         const ts = nowOr(ctx);
         const res = ingestFile(store, ctx.repoId, info.path, content, { ts, origin: "api", actor: ctx.actor ?? null, reason: `set_meta ${info.path}`, resolveIds: makeReconcilingResolver(store, ctx.repoId, { ts, path: info.path }) });

package/dist/src/mutate/ops.js

@@ -1,6 +1,6 @@
 import { mintId } from "../core/ids.js";
 import { parseTree } from "../core/parse/tree.js";
-import { adapterForFormat } from "../format/index.js";
+import { adapterForFormat, isContainerBlock } from "../format/index.js";
 import { codeUnitIndexOf } from "../core/utf8.js";
 import { MutationError, locate, rawHashHex, parentChildrenHash, markContainerDirty, ownerOf } from "./tree.js";
 function defaultTrivia(format) {
@@ -34,8 +34,10 @@ function parseContentToBlocks(content, format) {
     });
     return tree.children.filter((b) => b.type !== "frontmatter").map(toMut);
 }
-// Resolve a To into a target sibling list + insertion index.
-function resolveTarget(doc, to) {
+// Resolve a To into a target sibling list + insertion index (spec/mutate §1.1).
+// Shared by insert, move and the destination `parent_children_hash` CAS, so the
+// container rule below is seen by all three.
+function resolveTarget(doc, to, opIndex) {
     let siblings;
     if (to.parent === null || (typeof to.parent === "object" && "doc" in to.parent)) {
         siblings = doc.children;
@@ -46,9 +48,18 @@ function resolveTarget(doc, to) {
         return resolveSection(doc, to.parent.heading, to.at);
     }
     else {
-        const found = locate(doc, to.parent);
+        const parentId = to.parent;
+        const found = locate(doc, parentId);
         if (!found)
-            throw new MutationError("parent_missing", `parent ${String(to.parent)} not found`);
+            throw new MutationError("parent_missing", `parent ${parentId} not found`);
+        // §1.1 (since 1.2): `parent: <id>` must name a CONTAINER. A leaf's `children`
+        // is empty by construction, not by content — placing a block there marked
+        // the leaf dirty, renderBlock rebuilt it from its children, and the leaf's
+        // own text (a heading's line) vanished from the file. The error carries the
+        // two ways to say what the caller meant: next to it, or into its section.
+        if (!isContainerBlock(doc.format, found.block)) {
+            throw new MutationError("type_mismatch", `${parentId} is a ${found.block.type}, not a container; place relative to it with at.before/at.after or append to its section`, { op_index: opIndex, block: parentId, type: found.block.type });
+        }
         siblings = found.block.children;
     }
     return { siblings, index: resolveIndex(siblings, to.at) };
@@ -155,7 +166,7 @@ function markSubtreeClean(b) {
 }
 // ---- the six ops ------------------------------------------------------------
 export function opInsert(doc, to, markdown, expect, opIndex = 0) {
-    const { siblings, index } = resolveTarget(doc, to);
+    const { siblings, index } = resolveTarget(doc, to, opIndex);
     // §1.2: the destination parent's order CAS — `siblings` IS the resolved parent
     // list (a section scope or a `{ doc: true }` anchor both name the top level).
     checkParentChildrenHash(siblings, expect, opIndex);
@@ -352,12 +363,13 @@ export function opMove(doc, blockIds, to, opIndex, expect) {
     if (typeof to.parent === "string" && movedIds.has(to.parent)) {
         throw new MutationError("cycle_move", "target is inside the moved subtree", { op_index: opIndex });
     }
-    // §1.2: the DESTINATION parent's order CAS, resolved on the pre-removal tree
-    // (before the op mutates anything) and checked once for the whole run. When
-    // source and destination are one list this is the "same siblings reordered
-    // under me" guard: the hash covers the moved blocks' current positions too.
-    if (expect?.parent_children_hash !== undefined)
-        checkParentChildrenHash(resolveTarget(doc, to).siblings, expect, opIndex);
+    // Resolve the destination on the PRE-removal tree first: §1.1's container rule
+    // and a missing parent/anchor fail before anything moves, and §1.2's
+    // DESTINATION-parent order CAS is checked once for the whole run against the
+    // children as they stand. When source and destination are one list this is the
+    // "same siblings reordered under me" guard: the hash covers the moved blocks'
+    // current positions too. The index is re-resolved after extraction below.
+    checkParentChildrenHash(resolveTarget(doc, to, opIndex).siblings, expect, opIndex);
     // Extract (preserve order) then re-insert at the target.
     const moving = located.map((l) => l.block);
     for (const m of moving) {
@@ -365,7 +377,7 @@ export function opMove(doc, blockIds, to, opIndex, expect) {
         if (idx >= 0)
             siblings.splice(idx, 1);
     }
-    const { siblings: dstSiblings, index } = resolveTarget(doc, to);
+    const { siblings: dstSiblings, index } = resolveTarget(doc, to, opIndex);
     dstSiblings.splice(index, 0, ...moving);
     // A move within/into a nested container invalidates that container's cached
     // raw (and the source's) — mark them so they re-render from children. No-op

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

@@ -20,4 +20,15 @@ export declare function makeStoreContext(store: Store, repoId: string, opts?: St
 /** Tag SQL rows with their target so the store context resolves them (used by the
  * tier-3 planner to hand produced rows back for residual evaluation). */
 export declare function tagRows(rows: Record<string, unknown>[], target: Target): unknown[];
+/**
+ * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
+ * values, 1.2) is rendered as `{ id, path }` — its id column and its document's
+ * path, the same two keys every hit carries — never the store row itself.
+ * Returns undefined for anything that is not a tagged row (run.ts leaves those
+ * alone).
+ */
+export declare function rowRef(value: unknown): {
+    id: string;
+    path: string;
+} | undefined;
 export { TARGET };

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

@@ -610,5 +610,21 @@ function hex(b) {
 export function tagRows(rows, target) {
     return tagAll(rows, target);
 }
+/**
+ * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
+ * values, 1.2) is rendered as `{ id, path }` — its id column and its document's
+ * path, the same two keys every hit carries — never the store row itself.
+ * Returns undefined for anything that is not a tagged row (run.ts leaves those
+ * alone).
+ */
+export function rowRef(value) {
+    const t = value?.[TARGET];
+    if (!t)
+        return undefined;
+    const r = value;
+    const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : r.edge_id;
+    const path = t === "docs" ? r.path : r.__path;
+    return { id: String(id), path: String(path ?? "") };
+}
 export { TARGET };
 //# sourceMappingURL=context.js.map

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,102 @@ 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, plus what the
+ * typed comparison (`typedComparison`) needs to re-shape it: the JSON column +
+ * path behind a `json` read, the document alias + key behind a `prop` read, and
+ * the constant behind a literal/binding (`value`; `bool`/`num`/`null`/text
+ * constants only — a column operand has none). */
+export interface Operand extends Frag {
+    kind: OperandKind;
+    json?: {
+        col: string;
+        path: string;
+    };
+    prop?: {
+        docAlias: string;
+        key: string;
+    };
+    value?: unknown;
+}
+/**
+ * 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 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 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;