@omgbase/core 0.3.0 → 0.4.1

package/dist/src/graph/history.js

@@ -1,5 +1,6 @@
 import { findDocByRef } from "../core/read/reader.js";
 import { isValidId } from "../core/ids.js";
+import { EngineError } from "../mcp/errors.js";
 /** history_node: a block's biography from block_changes + commits (06 §3). */
 export function historyNode(store, blockId, opts = {}) {
     const limit = opts.limit ?? 100;
@@ -78,6 +79,25 @@ export function diffUnified(store, docId, fromRev, toRev) {
     const rendered = (rev) => [...blocksAtRevision(store, docId, rev).values()].join("\n");
     return unifiedDiff(rendered(fromRev), rendered(toRev));
 }
+/**
+ * `diff_unified` over a resolved document: `to` defaults to the current revision,
+ * `from` to the one before it (or the current one again when there is only one:
+ * an empty diff). Shared by the MCP tool and `omg diff` so the shape cannot
+ * drift. `label` is how the caller named the document, for the error message.
+ * A document with no revision at all is `target_missing`; an unknown `rev` is
+ * `RevisionNotFound` (→ `target_missing` through `errorBody`).
+ */
+export function docDiffUnified(store, docId, opts = {}) {
+    const revs = store.db
+        .prepare("SELECT rev_id FROM revisions WHERE doc_id = ? ORDER BY seq DESC LIMIT 2")
+        .all(docId);
+    const to = opts.toRev ?? revs[0]?.rev_id;
+    const from = opts.fromRev ?? revs[1]?.rev_id ?? revs[0]?.rev_id;
+    if (!to || !from)
+        throw new EngineError("target_missing", `no revisions to diff for ${opts.label ?? docId}`);
+    const path = store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId)?.path ?? "";
+    return { doc: docId, path, from, to, diff: diffUnified(store, docId, from, to) };
+}
 // ---- unified diff (spec/surface §3) ------------------------------------------
 // A line-grain unified diff with a deterministic Myers script, so both engines
 // (this reference and crates/omgbase-surface/src/history.rs) produce the same
@@ -232,14 +252,19 @@ export function changesSince(store, repoId, opts = {}) {
         params.push(opts.origin);
     params.push(limit + 1);
     const commits = store.db
-        .prepare(`SELECT commit_id, seq, ts, origin, actor FROM commits WHERE repo_id = ? AND seq > ? ${originClause} ORDER BY seq LIMIT ?`)
+        .prepare(`SELECT commit_id, seq, ts, origin, actor, reason FROM commits WHERE repo_id = ? AND seq > ? ${originClause} ORDER BY seq LIMIT ?`)
         .all(...params);
     const truncated = commits.length > limit;
     const page = commits.slice(0, limit);
     const digests = page.map((c) => {
         const revs = store.db.prepare("SELECT r.doc_id AS doc, r.path AS path, r.rendered_hash AS rendered_hash FROM revisions r WHERE r.commit_id = ?").all(c.commit_id).map((r) => ({ doc: r.doc, path: r.path, contentHash: r.rendered_hash.toString("hex") }));
         const dispCounts = store.db.prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind").all(c.commit_id);
-        const summary = renderSummary(c.origin, c.actor, revs, dispCounts);
+        // A deletion or a move writes no revision: the tombstone names the commit
+        // (`docs.deleted_commit`), a move only its reason (`move <from> -> <to>`).
+        const deleted = revs.length === 0
+            ? store.db.prepare("SELECT path FROM docs WHERE deleted_commit = ? ORDER BY path").all(c.commit_id).map((r) => r.path)
+            : [];
+        const summary = renderSummary(c.origin, c.actor, revs, dispCounts, { deleted, moved: revs.length === 0 ? parseMove(c.reason) : null });
         return { commit: c.commit_id, seq: c.seq, ts: c.ts, origin: c.origin, actor: c.actor, summary, revisions: revs };
     });
     const nextCursor = page.length > 0 ? page[page.length - 1].seq : cursor;
@@ -333,12 +358,29 @@ function resolveDocRow(store, repoId, ref, includeDeleted) {
         : store.db.prepare("SELECT doc_id, path, current_rev, deleted_commit FROM docs WHERE repo_id = ? AND path = ?");
     return (asId ? stmt.get(ref) : stmt.get(repoId, ref));
 }
-function renderSummary(origin, actor, revs, disp) {
-    const paths = revs.map((r) => r.path).join(", ");
+/** The `reason` a document move records (`mutate/docs.ts`): `move <from> -> <to>`. */
+function parseMove(reason) {
+    const m = reason === null ? null : /^move (.+) -> (.+)$/.exec(reason);
+    return m ? { from: m[1], to: m[2] } : null;
+}
+/**
+ * One line per commit: `<origin>[(<actor>)]: <paths> — <n> <kind>, …`. A
+ * commit that touched no revision — a document deletion (observed or api) or a
+ * move — says so instead: `deleted <path>` / `moved <from> → <to>`
+ * (spec/cli §6 `log`; the summary is unpinned by spec/surface).
+ */
+function renderSummary(origin, actor, revs, disp, extra = { deleted: [], moved: null }) {
+    let subject = revs.map((r) => r.path).join(", ");
+    if (revs.length === 0) {
+        if (extra.deleted.length > 0)
+            subject = `deleted ${extra.deleted.join(", ")}`;
+        else if (extra.moved)
+            subject = `moved ${extra.moved.from} → ${extra.moved.to}`;
+    }
     const parts = disp.filter((d) => d.kind !== "same").map((d) => `${d.n} ${d.kind}`);
     const detail = parts.length > 0 ? ` — ${parts.join(", ")}` : "";
     if (origin === "api" || origin === "import")
-        return `${origin}(${actor ?? "?"}): ${paths}${detail}`;
-    return `observed: ${paths}${detail}`;
+        return `${origin}(${actor ?? "?"}): ${subject}${detail}`;
+    return `observed: ${subject}${detail}`;
 }
 //# sourceMappingURL=history.js.map

package/dist/src/graph/links.d.ts

@@ -8,6 +8,8 @@ export interface LinkEdge {
     count: number;
     /** sample source block ids (out-edges only) */
     samples?: string[];
+    /** block-grain (`blocks: true`): the source block of this edge (null for a frontmatter edge) */
+    block?: string | null;
 }
 export interface LinksResult {
     out: LinkEdge[];

package/dist/src/graph/links.js

@@ -8,12 +8,12 @@ export function docLinks(store, docId, opts = {}) {
     if (dir === "out" || dir === "both") {
         if (opts.blocks) {
             const rows = store.db
-                .prepare(`SELECT predicate, dst_node, dst_kind FROM edges
-           WHERE src_doc = ? AND to_commit IS NULL ORDER BY predicate, dst_node`)
+                .prepare(`SELECT predicate, dst_node, dst_kind, src_block FROM edges
+           WHERE src_doc = ? AND to_commit IS NULL ORDER BY predicate, dst_node, src_block`)
                 .all(docId);
             for (const r of rows)
                 if (inPred(r.predicate))
-                    out.push({ predicate: r.predicate, node: r.dst_node, kind: r.dst_kind, count: 1 });
+                    out.push({ predicate: r.predicate, node: r.dst_node, kind: r.dst_kind, count: 1, block: r.src_block });
         }
         else {
             const rows = store.db
@@ -28,14 +28,25 @@ export function docLinks(store, docId, opts = {}) {
         }
     }
     if (dir === "in" || dir === "both") {
-        const rows = store.db
-            .prepare(`SELECT predicate, src_doc, count(*) AS cnt FROM edges
-         WHERE dst_node = ? AND to_commit IS NULL
-         GROUP BY predicate, src_doc ORDER BY predicate, src_doc`)
-            .all(docId);
-        for (const r of rows)
-            if (inPred(r.predicate))
-                inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: r.cnt });
+        if (opts.blocks) {
+            const rows = store.db
+                .prepare(`SELECT predicate, src_doc, src_block FROM edges
+           WHERE dst_node = ? AND to_commit IS NULL ORDER BY predicate, src_doc, src_block`)
+                .all(docId);
+            for (const r of rows)
+                if (inPred(r.predicate))
+                    inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: 1, block: r.src_block });
+        }
+        else {
+            const rows = store.db
+                .prepare(`SELECT predicate, src_doc, count(*) AS cnt FROM edges
+           WHERE dst_node = ? AND to_commit IS NULL
+           GROUP BY predicate, src_doc ORDER BY predicate, src_doc`)
+                .all(docId);
+            for (const r of rows)
+                if (inPred(r.predicate))
+                    inbound.push({ predicate: r.predicate, node: r.src_doc, kind: "document", count: r.cnt });
+        }
     }
     return { out, in: inbound };
 }

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";
@@ -27,7 +28,7 @@ export { observeFile, observeMany, observeOne, observeDelete, observeBatch, type
 export { buildServer, type ServerContext } from "./mcp/server.js";
 export { serveStdio, type ServeStdioHandle } from "./mcp/stdio.js";
 export { processCheckpoint, type CheckpointResult } from "./sync/checkpoint.js";
-export { reposStatus, syncStatus, type RepoStatus, type SyncStatus, type DiskStatus } from "./sync/admin.js";
+export { reposStatus, syncStatus, reposList, type RepoStatus, type SyncStatus, type DiskStatus, type ReposList } from "./sync/admin.js";
 export { docsOutline, type OutlineResult, type OutlineOptions } from "./core/read/outline.js";
 export { docsRead, reconstructContent, type DocsReadResult, type DocsReadOptions } from "./core/read/document.js";
 export { nodesGet, nodesGetMany, type GetNode, type Resolution } from "./core/read/nodes.js";
@@ -37,18 +38,18 @@ export { resolveRef, type ResolvedRef } from "./core/read/refs.js";
 export { resolve, type ResolveHit, type ResolveInput } from "./search/resolve.js";
 export { oqxRun, oqxRunAsync, collectSemanticPhrases, parseOqx, type OqxResult, type OqxHit, type OqxOptions, type EmbedQuery } from "./oqx/run.js";
 export { EmbeddingWorker, SemanticUnavailable, contextPrefix, shouldEmbed, estimateTokens, type EmbeddingProvider, type EmbedTask, type DocEmbedTask, type DocEmbedBlockRef, type DocEmbedMethod, type DocVectorRow, } from "./search/embeddings.js";
-export { buildEmbedTasks, buildDocEmbedTasks } from "./search/tasks.js";
+export { buildEmbedTasks, buildDocEmbedTasks, staleEmbedCount } from "./search/tasks.js";
 export { EmbedDrainer, type DrainerOptions } from "./search/drain.js";
 export { embeddingSettings, type EmbeddingSettings } from "./search/provider.js";
 export { createExternalProvider, type ExternalProvider } from "./search/external.js";
 export { hybridSearch, type HybridHit, type HybridInput } from "./search/rrf.js";
 export { vectorSearch, docVectorSearch, type VectorHit, type DocVectorHit } from "./search/vector.js";
-export { historyNode, diffUnified, unifiedDiff, changesSince, type NodeChange, type CommitDigest } from "./graph/history.js";
+export { historyNode, diffUnified, docDiffUnified, diffBlocks, unifiedDiff, changesSince, RevisionNotFound, type NodeChange, type CommitDigest, type DocDiffUnified, type DiffEntry } from "./graph/history.js";
 export { docLinks, type LinksResult, type LinkEdge, type LinksOptions } from "./graph/links.js";
 export { FilterInvalid } from "./search/cel/parser.js";
-export { EngineError, type ErrorCode } from "./mcp/errors.js";
+export { EngineError, errorBody, type ErrorCode, type ErrorBody } from "./mcp/errors.js";
 export { MutationError } from "./mutate/tree.js";
-export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, type IdMinter, type IdPrefix } from "./core/ids.js";
+export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, repeatingMinter, registerIdOracle, type IdMinter, type IdOracle, type IdPrefix } from "./core/ids.js";
 export { pinClock, withClock } from "./core/clock.js";
 export { sha256 } from "./core/hash.js";
 export { ingestFile, type IngestResult } from "./core/ingest.js";
@@ -62,3 +63,4 @@ export { planUpdate, applyOpset, docsUpdate, type PlanUpdateOptions, type ApplyO
 export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, type Opset, type PlanOp, type OpsetSummary, type OpsetPrecondition, type PlanDisposition, } from "./mutate/opset.js";
 export { rebuildIndex, type RebuildTarget } from "./core/store/rebuild.js";
 export { runGc, type GcResult } from "./core/store/gc.js";
+export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.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";
@@ -27,7 +28,7 @@ export { observeFile, observeMany, observeOne, observeDelete, observeBatch } fro
 export { buildServer } from "./mcp/server.js";
 export { serveStdio } from "./mcp/stdio.js";
 export { processCheckpoint } from "./sync/checkpoint.js";
-export { reposStatus, syncStatus } from "./sync/admin.js";
+export { reposStatus, syncStatus, reposList } from "./sync/admin.js";
 // Read surface consumed by CLI read commands (11 §5.2–5.5).
 export { docsOutline } from "./core/read/outline.js";
 export { docsRead, reconstructContent } from "./core/read/document.js";
@@ -42,18 +43,18 @@ export { oqxRun, oqxRunAsync, collectSemanticPhrases, parseOqx } from "./oqx/run
 // Embeddings + semantic retrieval (05 §5–6). The provider is a plugin loaded by
 // package name; core carries no ML dependency.
 export { EmbeddingWorker, SemanticUnavailable, contextPrefix, shouldEmbed, estimateTokens, } from "./search/embeddings.js";
-export { buildEmbedTasks, buildDocEmbedTasks } from "./search/tasks.js";
+export { buildEmbedTasks, buildDocEmbedTasks, staleEmbedCount } from "./search/tasks.js";
 export { EmbedDrainer } from "./search/drain.js";
 export { embeddingSettings } from "./search/provider.js";
 export { createExternalProvider } from "./search/external.js";
 export { hybridSearch } from "./search/rrf.js";
 export { vectorSearch, docVectorSearch } from "./search/vector.js";
-export { historyNode, diffUnified, unifiedDiff, changesSince } from "./graph/history.js";
+export { historyNode, diffUnified, docDiffUnified, diffBlocks, unifiedDiff, changesSince, RevisionNotFound } from "./graph/history.js";
 export { docLinks } from "./graph/links.js";
 export { FilterInvalid } from "./search/cel/parser.js";
-export { EngineError } from "./mcp/errors.js";
+export { EngineError, errorBody } from "./mcp/errors.js";
 export { MutationError } from "./mutate/tree.js";
-export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter } from "./core/ids.js";
+export { isValidId, prefixOf, mintId, setIdMinter, withIdMinter, sequentialMinter, repeatingMinter, registerIdOracle } from "./core/ids.js";
 // The clock seam (spec/surface §7.1): `omg mcp` pins the process clock under OMGBASE_SPEC_CLOCK.
 export { pinClock, withClock } from "./core/clock.js";
 export { sha256 } from "./core/hash.js";
@@ -72,4 +73,5 @@ export { planUpdate, applyOpset, docsUpdate, } from "./mutate/plan-update.js";
 export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, } from "./mutate/opset.js";
 export { rebuildIndex } from "./core/store/rebuild.js";
 export { runGc } from "./core/store/gc.js";
+export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";
 //# sourceMappingURL=index.js.map

package/dist/src/mcp/errors.d.ts

@@ -15,3 +15,11 @@ export declare class EngineError extends Error {
     });
     body(): EngineErrorBody;
 }
+/** The rendered body of any thrown error (`error` is the code). */
+export interface ErrorBody {
+    error: string;
+    message: string;
+    data?: unknown;
+    retriable: boolean;
+}
+export declare function errorBody(err: unknown): ErrorBody;

package/dist/src/mcp/errors.js

@@ -1,6 +1,7 @@
-// Error codes (06 §5). Shape: { error, message, data?, retriable }. Codes are
-// stable; prose is free to improve. FilterInvalid from the query compiler maps
-// to filter_invalid with its reason/hint in data.
+import { FilterInvalid } from "../search/cel/parser.js";
+import { CursorInvalid } from "../core/cursor.js";
+import { MutationError } from "../mutate/tree.js";
+import { RevisionNotFound } from "../graph/history.js";
 export class EngineError extends Error {
     code;
     data;
@@ -15,4 +16,17 @@ export class EngineError extends Error {
         return { error: this.code, message: this.message, data: this.data, retriable: this.retriable };
     }
 }
+export function errorBody(err) {
+    if (err instanceof EngineError)
+        return { error: err.code, message: err.message, ...(err.data !== undefined ? { data: err.data } : {}), retriable: err.retriable };
+    if (err instanceof FilterInvalid)
+        return { error: "filter_invalid", message: err.message, data: { reason: err.reason, hint: err.hint }, retriable: false };
+    if (err instanceof CursorInvalid)
+        return { error: "filter_invalid", message: err.message, data: { reason: `cursor was not issued by ${err.surface}`, hint: "resume only with a `cursor` returned by a truncated page of the same tool" }, retriable: false };
+    if (err instanceof MutationError)
+        return { error: err.code, message: err.message, data: err.data, retriable: Boolean(err.data.retriable) };
+    if (err instanceof RevisionNotFound)
+        return { error: "target_missing", message: err.message, data: { doc: err.docId, rev: err.rev }, retriable: false };
+    return { error: "repo_not_found", message: String(err), retriable: false };
+}
 //# sourceMappingURL=errors.js.map

package/dist/src/mcp/server.js

@@ -4,7 +4,6 @@ import { docsOutline } from "../core/read/outline.js";
 import { docsRead, docsReadMany, MANY_DOCS_CAP, readDocumentAtRevision } from "../core/read/document.js";
 import { nodesGet, nodesGetMany } from "../core/read/nodes.js";
 import { findDoc, findDocByRef, docsList, docsTree, DOCS_LIST_DEFAULT_LIMIT, DOCS_TREE_DEFAULT_LIMIT } from "../core/read/reader.js";
-import { CursorInvalid } from "../core/cursor.js";
 import { resolveRef } from "../core/read/refs.js";
 import { isValidId } from "../core/ids.js";
 import { VERSION } from "../core/index.js";
@@ -12,18 +11,16 @@ import { normalizeText, normalizeVisibleText } from "../core/hash.js";
 import { oqxRunAsync, collectSemanticPhrases } from "../oqx/run.js";
 import { graphNeighborhood } from "./graph.js";
 import { textSearch } from "../search/text.js";
-import { FilterInvalid } from "../search/cel/parser.js";
-import { EngineError } from "./errors.js";
+import { EngineError, errorBody } from "./errors.js";
 import { apply } from "../mutate/apply.js";
-import { MutationError } from "../mutate/tree.js";
 import { tasksComplete, sectionsAppend, docsAppend, linksRetarget, linksRepair, nodeSet } from "../mutate/macros.js";
 import { docsCreate, docsMove, docsDelete, docsSetMeta } from "../mutate/docs.js";
 import { planUpdate, docsUpdate } from "../mutate/plan-update.js";
 import { renderOpsetPlan } from "../mutate/opset.js";
-import { historyNode, diffBlocks, diffUnified, changesSince, docHistory, RevisionNotFound } from "../graph/history.js";
+import { historyNode, diffBlocks, docDiffUnified, changesSince, docHistory } from "../graph/history.js";
 import { linksStale, linksStaleSummary } from "../graph/link-health.js";
 import { resolve as resolveThing } from "../search/resolve.js";
-import { reposStatus, syncStatus } from "../sync/admin.js";
+import { reposStatus, syncStatus, reposList } from "../sync/admin.js";
 import { observeFile, observeMany, observeDelete } from "../sync/observe.js";
 import { QUERY_SYNTAX } from "./reference.js";
 // Kernel-op schemas (04 §1) published as the `apply` tool's op grammar. Giving
@@ -45,6 +42,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(),
@@ -61,20 +67,9 @@ function ok(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload) }] };
 }
 function fail(err) {
-    let body;
-    if (err instanceof EngineError)
-        body = err.body();
-    else if (err instanceof FilterInvalid)
-        body = { error: "filter_invalid", message: err.message, data: { reason: err.reason, hint: err.hint }, retriable: false };
-    else if (err instanceof CursorInvalid)
-        body = { error: "filter_invalid", message: err.message, data: { reason: `cursor was not issued by ${err.surface}`, hint: "resume only with a `cursor` returned by a truncated page of the same tool" }, retriable: false };
-    else if (err instanceof MutationError)
-        body = { error: err.code, message: err.message, data: err.data, retriable: Boolean(err.data.retriable) };
-    else if (err instanceof RevisionNotFound)
-        body = { error: "target_missing", message: err.message, data: { doc: err.docId, rev: err.rev }, retriable: false };
-    else
-        body = { error: "repo_not_found", message: String(err), retriable: false };
-    return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+    // One mapping for every client (errors.ts `errorBody`): the CLI renders the
+    // same body, so a code can never differ between `omg` and `omg mcp`.
+    return { content: [{ type: "text", text: JSON.stringify(errorBody(err)) }], isError: true };
 }
 export function buildServer(ctx) {
     const server = new McpServer({ name: "omgbase", version: VERSION });
@@ -279,7 +274,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 +317,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 +535,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 — it must be a CONTAINER (a list, list item, task, blockquote or table); a leaf such as a heading or paragraph fails `type_mismatch` (spec/mutate §1.1) — use sections_append for \"under this heading\" or `at: {after: <ref>}` for \"right after this 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 +580,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 (a container — a leaf parent is `type_mismatch`, as for blocks_insert), 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 +594,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) {
@@ -791,53 +788,56 @@ export function buildServer(ctx) {
     // Doc-level operations (06 §API). The MCP server serializes writes in-process,
     // so these pass no omgbaseDir (the flock is for cross-process CLI writers);
     // MCP-originated writes are actor agent:mcp.
-    const docCtx = (scope) => {
+    // `dry_run` validates and returns the per-file `diffs` without writing
+    // (`DocOpContext.dryRun`), the docs-verb peer of `apply`'s preview.
+    const docCtx = (scope, dryRun) => {
         if (!scope.rootPath)
             throw new EngineError("repo_not_found", "repo has no filesystem source; mutation disabled");
-        return { repoId: scope.repoId, rootPath: scope.rootPath, actor: "agent:mcp" };
+        return { repoId: scope.repoId, rootPath: scope.rootPath, actor: "agent:mcp", ...(dryRun ? { dryRun: true } : {}) };
     };
+    const docResult = (res, dryRun) => (dryRun ? ok(res) : okMutated(res));
     server.registerTool("docs_create", {
-        description: "Create a new document at `path` from complete file bytes (`markdown`), with optional structured `frontmatter`. Fails path_taken if it already exists.",
-        inputSchema: { path: z.string(), markdown: z.string(), frontmatter: z.record(z.string(), z.unknown()).optional(), ...REPO_ARG },
+        description: "Create a new document at `path` from complete file bytes (`markdown`), with optional structured `frontmatter`. Fails path_taken if it already exists. dry_run:true validates and returns the would-be file under `diffs` (committed:false) without writing.",
+        inputSchema: { path: z.string(), markdown: z.string(), frontmatter: z.record(z.string(), z.unknown()).optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
-            return okMutated(docsCreate(store, docCtx(repoScope(args.repo)), args.path, args.markdown, args.frontmatter));
+            return docResult(docsCreate(store, docCtx(repoScope(args.repo), args.dry_run), args.path, args.markdown, args.frontmatter), args.dry_run);
         }
         catch (e) {
             return fail(e);
         }
     });
     server.registerTool("docs_move", {
-        description: "Rename a document to a new repo-relative path; block identity and history are preserved. Fails path_taken if the destination exists. Links follow the PATH, not the identity: inbound links written against the old path now dangle (their edges become `phantom:<old path>`, so links_stale reports them), and links already written against the new path start resolving to this doc. The result lists those `dangling` inbound links ({doc, path, block, target, anchor, field?} per occurrence; block null = a frontmatter relation). Pass `retarget_inbound:true` to rewrite them in the same call — a destination-aware rewrite (anchors/link text/code spans preserved, absolute vs relative style kept) applied as one CAS-checked changeset, after which `dangling` holds only what could not be rewritten (frontmatter relations) and `retargeted` lists the touched blocks/docs.",
-        inputSchema: { doc: z.string(), to_path: z.string(), retarget_inbound: z.boolean().optional(), ...REPO_ARG },
+        description: "Rename a document to a new repo-relative path; block identity and history are preserved. Fails path_taken if the destination exists. Links follow the PATH, not the identity: inbound links written against the old path now dangle (their edges become `phantom:<old path>`, so links_stale reports them), and links already written against the new path start resolving to this doc. The result lists those `dangling` inbound links ({doc, path, block, target, anchor, field?} per occurrence; block null = a frontmatter relation). Pass `retarget_inbound:true` to rewrite them in the same call — a destination-aware rewrite (anchors/link text/code spans preserved, absolute vs relative style kept) applied as one CAS-checked changeset, after which `dangling` holds only what could not be rewritten (frontmatter relations) and `retargeted` lists the touched blocks/docs. dry_run:true validates and returns the plan — `dangling`, `retargeted`, and the per-file `diffs` (the old path emptied, the new path filled, plus any rewritten sources) — without renaming or committing.",
+        inputSchema: { doc: z.string(), to_path: z.string(), retarget_inbound: z.boolean().optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
-            return okMutated(docsMove(store, docCtx(repoScope(args.repo)), args.doc, args.to_path, { retargetInbound: args.retarget_inbound === true }));
+            return docResult(docsMove(store, docCtx(repoScope(args.repo), args.dry_run), args.doc, args.to_path, { retargetInbound: args.retarget_inbound === true }), args.dry_run);
         }
         catch (e) {
             return fail(e);
         }
     });
     server.registerTool("docs_delete", {
-        description: "Delete a document: tombstone it and its live blocks (resurrection-poolable) and remove the file. Requires the explicit doc id/path.",
-        inputSchema: { doc: z.string(), ...REPO_ARG },
+        description: "Delete a document: tombstone it and its live blocks (resurrection-poolable) and remove the file. Requires the explicit doc id/path. dry_run:true validates and returns the file's removal under `diffs` without deleting.",
+        inputSchema: { doc: z.string(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
-            return okMutated(docsDelete(store, docCtx(repoScope(args.repo)), args.doc));
+            return docResult(docsDelete(store, docCtx(repoScope(args.repo), args.dry_run), args.doc), args.dry_run);
         }
         catch (e) {
             return fail(e);
         }
     });
     server.registerTool("docs_set_meta", {
-        description: "Surgical frontmatter patch: set the given keys and/or unset named keys, re-ingesting the document. Other frontmatter is preserved.",
-        inputSchema: { doc: z.string(), set: z.record(z.string(), z.unknown()).optional(), unset: z.array(z.string()).optional(), ...REPO_ARG },
+        description: "Surgical frontmatter patch: set the given keys and/or unset named keys, re-ingesting the document. Other frontmatter is preserved. dry_run:true validates and returns the rewritten file under `diffs` without writing.",
+        inputSchema: { doc: z.string(), set: z.record(z.string(), z.unknown()).optional(), unset: z.array(z.string()).optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
-            return okMutated(docsSetMeta(store, docCtx(repoScope(args.repo)), args.doc, {
+            return docResult(docsSetMeta(store, docCtx(repoScope(args.repo), args.dry_run), args.doc, {
                 ...(args.set ? { set: args.set } : {}),
                 ...(args.unset ? { unset: args.unset } : {}),
-            }));
+            }), args.dry_run);
         }
         catch (e) {
             return fail(e);
@@ -945,15 +945,11 @@ export function buildServer(ctx) {
         try {
             const { repoId } = repoScope(args.repo);
             const docId = resolveDocId(repoId, { doc: args.doc });
-            const revs = store.db
-                .prepare("SELECT rev_id FROM revisions WHERE doc_id = ? ORDER BY seq DESC LIMIT 2")
-                .all(docId);
-            const toRev = args.to_rev ?? revs[0]?.rev_id;
-            const fromRev = args.from_rev ?? revs[1]?.rev_id ?? revs[0]?.rev_id;
-            if (!toRev || !fromRev)
-                throw new EngineError("target_missing", `no revisions to diff for ${JSON.stringify(args.doc)}`);
-            const path = store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId)?.path ?? "";
-            return ok({ doc: docId, path, from: fromRev, to: toRev, diff: diffUnified(store, docId, fromRev, toRev) });
+            return ok(docDiffUnified(store, docId, {
+                ...(args.from_rev !== undefined ? { fromRev: args.from_rev } : {}),
+                ...(args.to_rev !== undefined ? { toRev: args.to_rev } : {}),
+                label: JSON.stringify(args.doc),
+            }));
         }
         catch (e) {
             return fail(e);
@@ -1067,10 +1063,7 @@ export function buildServer(ctx) {
         inputSchema: {},
     }, async () => {
         try {
-            const rows = store.db
-                .prepare("SELECT r.slug AS slug, MAX(CASE WHEN s.adapter = 'fs' THEN 1 ELSE 0 END) AS has_fs FROM repos r LEFT JOIN attachments a ON a.repo_id = r.repo_id LEFT JOIN sources s ON s.source_id = a.source_id GROUP BY r.repo_id, r.slug ORDER BY r.slug")
-                .all();
-            return ok({ repos: rows.map((r) => ({ slug: r.slug, hasSource: r.has_fs === 1 })) });
+            return ok(reposList(store));
         }
         catch (e) {
             return fail(e);

package/dist/src/mutate/apply.js

@@ -9,6 +9,7 @@ import { renderDoc, markContainerDirty, MutationError } from "./tree.js";
 import { opInsert, opUpdate, opMove, opRemove, opSplit, opMerge, healTopLevelSeams, checkParentChildrenHash } from "./ops.js";
 import { withWriterLock } from "../sync/writer-lock.js";
 import { resolveDocStore } from "./doc-store.js";
+import { isContainerBlock } from "../format/index.js";
 // Resolve "$n.ids[i]" placeholders in a string against prior op results.
 function resolvePlaceholder(value, results) {
     const m = /^\$(\d+)\.ids\[(\d+)\]$/.exec(value);
@@ -248,9 +249,11 @@ function crossDocMove(src, dst, blockIds, to, opIndex, expect) {
             throw new MutationError("block_missing", `block ${id} not found in source doc`, { op_index: opIndex });
         moving.push(found.block);
     }
-    // §1.2: the destination parent's order CAS (in `dst`), before either tree moves.
+    // §1.1 container rule + §1.2 destination CAS (in `dst`), resolved once before
+    // either tree moves so a leaf destination errors with both trees untouched.
+    const pre = resolveDstTarget(dst, to, opIndex);
     if (expect?.parent_children_hash !== undefined)
-        checkParentChildrenHash(resolveDstTarget(dst, to).siblings, expect, opIndex);
+        checkParentChildrenHash(pre.siblings, expect, opIndex);
     // remove from their source lists (marking each emptied owner dirty)
     for (const id of blockIds) {
         const f = locateMut(src, id);
@@ -260,7 +263,7 @@ function crossDocMove(src, dst, blockIds, to, opIndex, expect) {
         }
     }
     // Insert into dst at the resolved target; the destination owner re-renders.
-    const target = resolveDstTarget(dst, to);
+    const target = resolveDstTarget(dst, to, opIndex);
     target.siblings.splice(target.index, 0, ...moving);
     markContainerDirty(dst, target.siblings);
     // Heal both documents' top-level seams (spec/mutate §2.3): a block that was
@@ -283,7 +286,7 @@ function locateMut(doc, blockId) {
     };
     return search(doc.children);
 }
-function resolveDstTarget(dst, to) {
+function resolveDstTarget(dst, to, opIndex = 0) {
     if (typeof to.parent === "object" && "doc" in to.parent) {
         return { siblings: dst.children, index: resolveAt(dst.children, to.at) };
     }
@@ -291,6 +294,11 @@ function resolveDstTarget(dst, to) {
         const f = locateMut(dst, to.parent);
         if (!f)
             throw new MutationError("parent_missing", `parent ${to.parent} not found in dest`);
+        // spec/mutate §1.1 (1.2): a leaf destination would be re-rendered from its
+        // children and lose its own text — the same rule as the in-document ops.
+        if (!isContainerBlock(dst.format, f.block)) {
+            throw new MutationError("type_mismatch", `${to.parent} is a ${f.block.type}, not a container; place relative to it with at.before/at.after or append to its section`, { op_index: opIndex, block: to.parent, type: f.block.type });
+        }
         return { siblings: f.block.children, index: resolveAt(f.block.children, to.at) };
     }
     // heading/section: insert into top-level list at the anchor.

package/dist/src/mutate/doc-store.js

@@ -2,6 +2,7 @@ import { writeFileSync, readFileSync, existsSync, renameSync, unlinkSync, mkdirS
 import { join, dirname } from "node:path";
 import { sha256 } from "../core/hash.js";
 import { recordFileStat } from "../sync/freshness.js";
+import { EngineError } from "../mcp/errors.js";
 /** Filesystem-backed DocStore rooted at a working-tree directory (v1 default). */
 export class FsDocStore {
     root;
@@ -66,6 +67,8 @@ export function resolveDocStore(req) {
         return req.docStore;
     if (req.rootPath != null)
         return new FsDocStore(req.rootPath);
-    throw new Error("mutation requires a rootPath or an explicit docStore");
+    // Typed, so every client renders the same `repo_not_found` the MCP server's
+    // pre-checks emit (spec/surface §4; spec/cli §9 "sourceless writes").
+    throw new EngineError("repo_not_found", "repo has no filesystem source; mutation disabled");
 }
 //# sourceMappingURL=doc-store.js.map