@omgbase/core 0.3.0 → 0.4.0

package/dist/src/core/ingest.js

@@ -6,7 +6,7 @@ import { assignIds, writeBlockTree, putBlob, newCommit, writeRevision } from "./
 import { sha256, childQuoteDepth, visibleText } from "./hash.js";
 import { mintId } from "./ids.js";
 import { keyBetween } from "./order-key.js";
-import { ftsDeleteDoc, ftsIndexDoc } from "./store/fts.js";
+import { ftsBeforeEvictRows, ftsDeleteDoc, ftsIndexDoc } from "./store/fts.js";
 import { rebuildSections } from "./store/sections.js";
 import { writeDocNodes, projectSectionNodes, toByteSpans } from "./store/nodes.js";
 import { flattenFrontmatter, flattenComputed, writeDocProperties } from "./store/properties.js";
@@ -288,25 +288,28 @@ export function ingestFile(store, repoId, path, content, opts = {}) {
     });
 }
 // Remove another document's `blocks` row for each id in `ids` (a cross-doc move
-// or a resurrection re-homes the id into `docId`). A live foreign row still has
-// an FTS entry (external-content index: delete with the original text); a
-// tombstoned one does not. The source document, if it commits later in the same
+// or a resurrection re-homes the id into `docId`). A live foreign LEAF row still
+// has an FTS entry (external-content index: delete with the original text); a
+// tombstoned row or a container does not (spec/search §1.1) — ftsBeforeEvictRows
+// decides leaf-ness over the table before any row goes and re-indexes a parent
+// left childless. The source document, if it commits later in the same
 // checkpoint, rewrites its rows wholesale and never lists a carried id as
 // deleted, so nothing there depends on the evicted row.
 function evictForeignBlockRows(db, docId, ids) {
-    const sel = db.prepare("SELECT rowid, text, deleted_commit FROM blocks WHERE block_id = ? AND doc_id != ?");
-    const ftsDel = db.prepare("INSERT INTO blocks_fts(blocks_fts, rowid, text) VALUES('delete', ?, ?)");
+    const sel = db.prepare("SELECT rowid, block_id, doc_id, parent_block, text, deleted_commit FROM blocks WHERE block_id = ? AND doc_id != ?");
     const del = db.prepare("DELETE FROM blocks WHERE block_id = ? AND doc_id != ?");
     const unpool = db.prepare("DELETE FROM resurrection_pool WHERE block_id = ?");
+    const rows = [];
     for (const id of ids) {
         const row = sel.get(id, docId);
-        if (row) {
-            if (row.deleted_commit === null)
-                ftsDel.run(row.rowid, row.text);
-            del.run(id, docId);
-        }
-        unpool.run(id);
+        if (row)
+            rows.push(row);
     }
+    ftsBeforeEvictRows(db, rows);
+    for (const r of rows)
+        del.run(r.block_id, docId);
+    for (const id of ids)
+        unpool.run(id);
 }
 // Zip assigned block ids onto the parsed RawBlocks for node projection. The
 // parsed `rest` and `assigned` trees are the same blocks in the same order and

package/dist/src/core/read/document.js

@@ -116,8 +116,13 @@ export function docsReadMany(store, repoId, refs, opts = {}) {
             errors.push({ ref, error: "doc_not_found" });
             continue;
         }
+        // The budget is checked before the SECOND item onward (spec/surface §2, 1.2):
+        // the first item is always emitted even when it alone exceeds the budget —
+        // the same "at least one row" contract docs_list/docs_tree keep, so a
+        // budgeted client always makes progress. `truncated` stays honest: it is
+        // set only when the budget stopped an item that would otherwise have shipped.
         const cost = Math.ceil(JSON.stringify(read).length / 4);
-        if (tokens + cost > budget) {
+        if (items.length > 0 && tokens + cost > budget) {
             truncated = true;
             break;
         }

package/dist/src/core/read/nodes.js

@@ -89,8 +89,12 @@ export function nodesGetMany(store, docId, blockIds, opts = {}) {
             continue;
         }
         const projected = project(store, node, resolution, false);
+        // At least one resolved node is always returned (spec/surface §2, 1.2): the
+        // budget is checked before the second node onward, as docsReadMany does, so
+        // a first node that alone exceeds it still ships and `truncated` only says
+        // that more remained.
         const cost = Math.ceil(JSON.stringify(projected).length / 4);
-        if (tokens + cost > budget) {
+        if (nodes.length > 0 && tokens + cost > budget) {
             truncated = true;
             break;
         }

package/dist/src/core/store/fts.d.ts

@@ -1,10 +1,41 @@
 import type { Database } from "better-sqlite3";
-/** Remove a document's live block rows from the FTS index (call before deleting
- * or tombstoning blocks). Only live blocks are indexed (see ftsIndexDoc), so the
- * delete must target the SAME set: an already-tombstoned block has no FTS row, and
- * re-issuing a 'delete' for it corrupts the external-content index. Keeping this
- * symmetric with ftsIndexDoc (deleted_commit IS NULL) makes a tombstone followed by
- * a later re-ingest of the same doc id (observed delete → recreate) idempotent. */
+/**
+ * SQL predicate: the `blocks` row aliased `b` is a live leaf. `c.doc_id =
+ * b.doc_id` lets the NOT EXISTS use `idx_blocks_doc` (block ids are unique, so
+ * it never changes the answer).
+ */
+export declare const LIVE_LEAF_SQL = "b.deleted_commit IS NULL AND NOT EXISTS (SELECT 1 FROM blocks c WHERE c.doc_id = b.doc_id AND c.parent_block = b.block_id AND c.deleted_commit IS NULL)";
+/** Remove a document's live leaf rows from the FTS index (call before deleting
+ * or tombstoning blocks). Only live leaves are indexed (see ftsIndexDoc), so the
+ * delete must target the SAME set: an already-tombstoned block or a container has
+ * no FTS row, and re-issuing a 'delete' for it corrupts the external-content
+ * index's statistics. Keeping this symmetric with ftsIndexDoc makes a tombstone
+ * followed by a later re-ingest of the same doc id (observed delete → recreate)
+ * idempotent. */
 export declare function ftsDeleteDoc(db: Database, docId: string): void;
-/** Index a document's current block rows (call after inserting blocks). */
+/** Index a document's current live leaf rows (call after inserting blocks). */
 export declare function ftsIndexDoc(db: Database, docId: string): void;
+/**
+ * Rebuild the whole index: `'delete-all'`, then every live leaf of every live
+ * document. (FTS5's own `'rebuild'` command reads the content table wholesale,
+ * containers included, so it is not used.)
+ */
+export declare function ftsRebuild(db: Database): void;
+/**
+ * Remove single `blocks` rows (by id) that are about to be deleted out of
+ * another document's row set — the cross-document eviction of spec/store §5.4
+ * step 8 — keeping the index equal to the table's live leaves. Every row's
+ * leaf-ness is decided over the table BEFORE any of them goes (so a list moving
+ * with its items is order-independent: the items are leaves and lose their
+ * entries, the list never had one), and a live parent that keeps its row but
+ * loses its last live child becomes a leaf and gains an entry. The caller owns
+ * the DELETE of the rows, which must follow this call.
+ */
+export declare function ftsBeforeEvictRows(db: Database, rows: {
+    rowid: number;
+    block_id: string;
+    doc_id: string;
+    parent_block: string | null;
+    text: string;
+    deleted_commit: string | null;
+}[]): void;

package/dist/src/core/store/fts.js

@@ -1,22 +1,73 @@
-/** Remove a document's live block rows from the FTS index (call before deleting
- * or tombstoning blocks). Only live blocks are indexed (see ftsIndexDoc), so the
- * delete must target the SAME set: an already-tombstoned block has no FTS row, and
- * re-issuing a 'delete' for it corrupts the external-content index. Keeping this
- * symmetric with ftsIndexDoc (deleted_commit IS NULL) makes a tombstone followed by
- * a later re-ingest of the same doc id (observed delete → recreate) idempotent. */
+/**
+ * SQL predicate: the `blocks` row aliased `b` is a live leaf. `c.doc_id =
+ * b.doc_id` lets the NOT EXISTS use `idx_blocks_doc` (block ids are unique, so
+ * it never changes the answer).
+ */
+export const LIVE_LEAF_SQL = "b.deleted_commit IS NULL AND NOT EXISTS (SELECT 1 FROM blocks c WHERE c.doc_id = b.doc_id AND c.parent_block = b.block_id AND c.deleted_commit IS NULL)";
+/** Remove a document's live leaf rows from the FTS index (call before deleting
+ * or tombstoning blocks). Only live leaves are indexed (see ftsIndexDoc), so the
+ * delete must target the SAME set: an already-tombstoned block or a container has
+ * no FTS row, and re-issuing a 'delete' for it corrupts the external-content
+ * index's statistics. Keeping this symmetric with ftsIndexDoc makes a tombstone
+ * followed by a later re-ingest of the same doc id (observed delete → recreate)
+ * idempotent. */
 export function ftsDeleteDoc(db, docId) {
-    const rows = db.prepare("SELECT rowid, text FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL").all(docId);
+    const rows = db.prepare(`SELECT b.rowid AS rowid, b.text AS text FROM blocks b WHERE b.doc_id = ? AND ${LIVE_LEAF_SQL}`).all(docId);
     const del = db.prepare("INSERT INTO blocks_fts(blocks_fts, rowid, text) VALUES('delete', ?, ?)");
     for (const r of rows)
         del.run(r.rowid, r.text);
 }
-/** Index a document's current block rows (call after inserting blocks). */
+/** Index a document's current live leaf rows (call after inserting blocks). */
 export function ftsIndexDoc(db, docId) {
     const rows = db
-        .prepare("SELECT rowid, text FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL")
+        .prepare(`SELECT b.rowid AS rowid, b.text AS text FROM blocks b WHERE b.doc_id = ? AND ${LIVE_LEAF_SQL}`)
         .all(docId);
     const ins = db.prepare("INSERT INTO blocks_fts(rowid, text) VALUES(?, ?)");
     for (const r of rows)
         ins.run(r.rowid, r.text);
 }
+/**
+ * Rebuild the whole index: `'delete-all'`, then every live leaf of every live
+ * document. (FTS5's own `'rebuild'` command reads the content table wholesale,
+ * containers included, so it is not used.)
+ */
+export function ftsRebuild(db) {
+    db.exec("INSERT INTO blocks_fts(blocks_fts) VALUES('delete-all')");
+    const docIds = db.prepare("SELECT doc_id FROM docs WHERE deleted_commit IS NULL").all().map((r) => r.doc_id);
+    for (const docId of docIds)
+        ftsIndexDoc(db, docId);
+}
+/**
+ * Remove single `blocks` rows (by id) that are about to be deleted out of
+ * another document's row set — the cross-document eviction of spec/store §5.4
+ * step 8 — keeping the index equal to the table's live leaves. Every row's
+ * leaf-ness is decided over the table BEFORE any of them goes (so a list moving
+ * with its items is order-independent: the items are leaves and lose their
+ * entries, the list never had one), and a live parent that keeps its row but
+ * loses its last live child becomes a leaf and gains an entry. The caller owns
+ * the DELETE of the rows, which must follow this call.
+ */
+export function ftsBeforeEvictRows(db, rows) {
+    if (rows.length === 0)
+        return;
+    const evicted = new Set(rows.map((r) => r.block_id));
+    const hasLiveChild = db.prepare("SELECT 1 FROM blocks c WHERE c.doc_id = ? AND c.parent_block = ? AND c.deleted_commit IS NULL LIMIT 1");
+    const del = db.prepare("INSERT INTO blocks_fts(blocks_fts, rowid, text) VALUES('delete', ?, ?)");
+    const leaves = rows.filter((r) => r.deleted_commit === null && !hasLiveChild.get(r.doc_id, r.block_id));
+    for (const r of leaves)
+        del.run(r.rowid, r.text);
+    // Parents that stay live but are left childless are leaves from now on.
+    const parentRow = db.prepare(`SELECT b.rowid AS rowid, b.text AS text FROM blocks b WHERE b.block_id = ? AND b.doc_id = ? AND b.deleted_commit IS NULL
+       AND NOT EXISTS (SELECT 1 FROM blocks c WHERE c.doc_id = b.doc_id AND c.parent_block = b.block_id AND c.deleted_commit IS NULL AND c.block_id NOT IN (${rows.map(() => "?").join(",")}))`);
+    const ins = db.prepare("INSERT INTO blocks_fts(rowid, text) VALUES(?, ?)");
+    const seen = new Set();
+    for (const r of rows) {
+        if (r.deleted_commit !== null || !r.parent_block || evicted.has(r.parent_block) || seen.has(r.parent_block))
+            continue;
+        seen.add(r.parent_block);
+        const p = parentRow.get(r.parent_block, r.doc_id, ...rows.map((x) => x.block_id));
+        if (p)
+            ins.run(p.rowid, p.text);
+    }
+}
 //# sourceMappingURL=fts.js.map

package/dist/src/core/store/rebuild.js

@@ -1,6 +1,6 @@
 import { rebuildSections } from "./sections.js";
 import { rebuildDocEdges } from "./edges.js";
-import { ftsIndexDoc } from "./fts.js";
+import { ftsRebuild } from "./fts.js";
 export function rebuildIndex(store, target = "all") {
     store.write((db) => {
         const docIds = db.prepare("SELECT doc_id FROM docs WHERE deleted_commit IS NULL").all().map((r) => r.doc_id);
@@ -14,8 +14,10 @@ export function rebuildIndex(store, target = "all") {
                 rebuildDocEdges(db, docId);
         }
         if (target === "fts" || target === "all") {
-            // Rebuild the external-content FTS index from current block text.
-            db.exec("INSERT INTO blocks_fts(blocks_fts) VALUES('rebuild')");
+            // spec/search §1.1: 'delete-all', then every live leaf of every live doc
+            // (FTS5's 'rebuild' would index the content table wholesale, containers
+            // included).
+            ftsRebuild(db);
         }
         if (target === "block_changes" || target === "all") {
             // block_changes is a projection of dispositions across commits: rebuild
@@ -24,6 +26,5 @@ export function rebuildIndex(store, target = "all") {
             db.exec("INSERT OR IGNORE INTO block_changes (block_id, commit_id, kind) SELECT block_id, commit_id, kind FROM dispositions");
         }
     });
-    void ftsIndexDoc; // fts rebuild uses the FTS5 'rebuild' command directly
 }
 //# sourceMappingURL=rebuild.js.map

package/dist/src/index.d.ts

@@ -19,7 +19,8 @@ export { ingestDirectory, type IngestDirResult } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
 export { walkMarkdown, walkMarkdownAsync, nodeFs, type SyncFs, type FileStat } from "./sync/fs-util.js";
 export { Watcher, type WatcherOptions } from "./sync/watcher.js";
-export type { SyncSource, SourceCapabilities, SourceIdentity, SourceEntry, SourceItem, SourceWatch, WatchListener, } from "./sync/plugin.js";
+export type { SyncSource, SourceCapabilities, SourceIdentity, SourceEntry, SourceItem, SourceWatch, WatchEvent, WatchListener, } from "./sync/plugin.js";
+export { awaitReady, WATCH_READY_PATIENCE_MS } from "./sync/plugin.js";
 export { createExternalSource, type ExternalSourceSpec } from "./sync/external-source.js";
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, type AdapterRow, type SourceRow, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";

package/dist/src/index.js

@@ -20,6 +20,7 @@ export { ingestDirectory } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
 export { walkMarkdown, walkMarkdownAsync, nodeFs } from "./sync/fs-util.js";
 export { Watcher } from "./sync/watcher.js";
+export { awaitReady, WATCH_READY_PATIENCE_MS } from "./sync/plugin.js";
 export { createExternalSource } from "./sync/external-source.js";
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";

package/dist/src/mcp/server.js

@@ -45,6 +45,15 @@ const toSchema = z.object({
     ]),
     at: atSchema,
 });
+// blocks_insert / blocks_move carry the op-level expectation of spec/mutate §1.2:
+// only `parent_children_hash` (the destination parent's live direct child ids
+// joined by "," and sha256-hexed) has a meaning there — there is no target block
+// whose content_hash could be checked — so the schema names that one key alone
+// (an accidental `content_hash` is dropped, not an error; the kernel would
+// ignore it anyway).
+const parentExpectSchema = z.object({
+    parent_children_hash: z.string().optional(),
+});
 const expectSchema = z.object({
     content_hash: z.string().optional(),
     parent_children_hash: z.string().optional(),
@@ -279,7 +288,7 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("docs_get_many", {
-        description: "Batch whole-document read — the hydrate half of query→hydrate. The plural of docs_read: pass `docs`, a list of refs (each a doc id OR a path, same id-or-path symmetry docs_read accepts in its `doc` field), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`content` = complete file bytes verbatim, `properties` grouped by source, plus `path`/`docId`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block id → content hash} map for raw-`apply` CAS pinning, and a `parents` {block id → parent block id | null} map so top-level vs nested blocks are distinguishable without an outline read); a ref that resolves to no live document lands in `errors` as {ref, error:\"doc_not_found\"} WITHOUT failing the call, so one bad ref never sinks the batch. Duplicate refs collapse first-seen (a repeated ref yields a single item). Capped at " + MANY_DOCS_CAP + " refs per call; excess refs are dropped and `truncated` is set. Pass budget_tokens to cap total hydrated size — the batch stops early and flags `truncated` when the next doc would exceed it. Use this after query/text_search/resolve to pull N whole docs in ONE round-trip instead of N serial docs_read calls; for a single doc use docs_read, and for lean structure-only orientation use docs_outline.",
+        description: "Batch whole-document read — the hydrate half of query→hydrate. The plural of docs_read: pass `docs`, a list of refs (each a doc id OR a path, same id-or-path symmetry docs_read accepts in its `doc` field), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`content` = complete file bytes verbatim, `properties` grouped by source, plus `path`/`docId`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block id → content hash} map for raw-`apply` CAS pinning, and a `parents` {block id → parent block id | null} map so top-level vs nested blocks are distinguishable without an outline read); a ref that resolves to no live document lands in `errors` as {ref, error:\"doc_not_found\"} WITHOUT failing the call, so one bad ref never sinks the batch. Duplicate refs collapse first-seen (a repeated ref yields a single item). Capped at " + MANY_DOCS_CAP + " refs per call; excess refs are dropped and `truncated` is set. Pass budget_tokens to cap total hydrated size — the batch stops early and flags `truncated` when the next doc would exceed it; the FIRST doc always ships even when it alone exceeds the budget (the same at-least-one-row contract as docs_list/docs_tree, so a budgeted caller always makes progress). Use this after query/text_search/resolve to pull N whole docs in ONE round-trip instead of N serial docs_read calls; for a single doc use docs_read, and for lean structure-only orientation use docs_outline.",
         inputSchema: {
             docs: z.array(z.string()),
             include_ids: z.boolean().optional(),
@@ -322,7 +331,7 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("nodes_get_many", {
-        description: "Fetch up to 100 blocks by id (in request order) with budget truncation. Block ids are globally unique, so `ids` may span ANY number of documents — each id is resolved to its owning doc server-side; `doc`/`path` is an optional SCOPE (ids from other docs then count as unresolved), not a requirement. Result carries `nodes`, `truncated` (cap or `budget_tokens` hit), and `unresolved` — the requested ids that name no live block (never silently dropped).",
+        description: "Fetch up to 100 blocks by id (in request order) with budget truncation. Block ids are globally unique, so `ids` may span ANY number of documents — each id is resolved to its owning doc server-side; `doc`/`path` is an optional SCOPE (ids from other docs then count as unresolved), not a requirement. Result carries `nodes`, `truncated` (cap or `budget_tokens` hit — the first resolved node always ships even when it alone exceeds the budget, so a budgeted caller always makes progress), and `unresolved` — the requested ids that name no live block (never silently dropped).",
         inputSchema: {
             doc: z.string().optional(),
             path: z.string().optional(),
@@ -540,16 +549,18 @@ export function buildServer(ctx) {
     // local: the resolution that used to live in the CLI now lives next to the
     // store, so a remote client needs no local database.
     server.registerTool("blocks_insert", {
-        description: "Insert new block(s) parsed from `markdown` under a parent, at a position. `to` names the parent: a BLOCK ref (id or locator) nests the new blocks under that block, or a DOCUMENT ref (doc id or path) places them at the document's top level — so appending a new section to a document is `{ to: \"<path>\", markdown: \"## New\\n\\n…\" }` (the positional generalization of docs_append). `at` places among the parent's children: \"end\" (default) / \"start\" / {before|after: <block ref>}. Expands to one insert op through the kernel writer.",
-        inputSchema: { to: z.string(), markdown: z.string(), at: atSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
+        description: "Insert new block(s) parsed from `markdown` under a parent, at a position. `to` names the parent: a BLOCK ref (id or locator) nests the new blocks under that block, or a DOCUMENT ref (doc id or path) places them at the document's top level — so appending a new section to a document is `{ to: \"<path>\", markdown: \"## New\\n\\n…\" }` (the positional generalization of docs_append). `at` places among the parent's children: \"end\" (default) / \"start\" / {before|after: <block ref>}. Optional `expect.parent_children_hash` is the destination-parent CAS: the parent's CURRENT direct child ids (the document's top-level ids for a document `to`) joined by \",\" and sha256-hexed — compute it from docs_read include_ids (`ids` filtered by `parents`) — and the insert fails `stale_expectation` (with `data.current.parent_children_hash`) if the siblings changed under you; `content_hash` has no meaning here (there is no target block) and is not accepted. Expands to one insert op through the kernel writer.",
+        inputSchema: { to: z.string(), markdown: z.string(), at: atSchema.optional(), expect: parentExpectSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             const root = requireRoot(rootPath);
             const { parent, docId } = resolveParentRef(repoId, args.to);
             const to = { parent, at: resolveAt(repoId, args.at) };
-            // A document parent carries no block to infer the doc from; pin it.
-            const ops = [{ op: "insert", ...(typeof parent === "object" ? { doc: docId } : {}), to, markdown: args.markdown }];
+            // A document parent carries no block to infer the doc from; pin it. The
+            // caller's expect rides through as the op-level expectation (spec/mutate
+            // §1.2: checked against the destination parent before the op mutates).
+            const ops = [{ op: "insert", ...(typeof parent === "object" ? { doc: docId } : {}), to, markdown: args.markdown, ...(args.expect ? { expect: args.expect } : {}) }];
             return applyOps(repoId, root, ops, "blocks_insert", args.dry_run);
         }
         catch (e) {
@@ -583,8 +594,8 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("blocks_move", {
-        description: "Move block(s) under a new parent at a position. `blocks` are block refs; `to` (the parent) is a block ref, or the blocks' OWN document (id or path) to move them to its top level — moving to ANOTHER document's root is not expressible (target_missing): anchor on a block in that document with `at` {before|after} instead. `at` is \"end\"/\"start\"/{before|after: <ref>}. One move op through the kernel writer.",
-        inputSchema: { blocks: z.array(z.string()), to: z.string(), at: atSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
+        description: "Move block(s) under a new parent at a position. `blocks` are block refs; `to` (the parent) is a block ref, or the blocks' OWN document (id or path) to move them to its top level — moving to ANOTHER document's root is not expressible (target_missing): anchor on a block in that document with `at` {before|after} instead. `at` is \"end\"/\"start\"/{before|after: <ref>}. Optional `expect.parent_children_hash` is the destination-parent CAS (as blocks_insert: the destination parent's CURRENT direct child ids joined by \",\", sha256 hex), checked once for the whole run before anything moves — `stale_expectation` with `data.current.parent_children_hash` if the destination's children changed; `content_hash` is meaningless here and not accepted. One move op through the kernel writer.",
+        inputSchema: { blocks: z.array(z.string()), to: z.string(), at: atSchema.optional(), expect: parentExpectSchema.optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
@@ -597,7 +608,7 @@ export function buildServer(ctx) {
                 throw new EngineError("target_missing", `blocks_move cannot target another document's root (${args.to}); anchor on a block in that document with at.before/at.after`, { data: { to: args.to } });
             }
             const to = { parent, at: resolveAt(repoId, args.at) };
-            const ops = [{ op: "move", blocks, to }];
+            const ops = [{ op: "move", blocks, to, ...(args.expect ? { expect: args.expect } : {}) }];
             return applyOps(repoId, root, ops, "blocks_move", args.dry_run);
         }
         catch (e) {

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