@omgbase/core 0.4.0 → 0.5.0

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.d.ts

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Store } from "../core/store/store.js";
+import { type HostInfo } from "../version.js";
 export interface ServerContext {
     store: Store;
     /** The DEFAULT repo for calls that omit `repo` (ADR-014). Tools accept an
@@ -26,5 +27,12 @@ export interface ServerContext {
      * embedding happens off it. Absent ⇒ mutations don't auto-drain.
      */
     onMutation?: () => void;
+    /**
+     * The serving binary's identity for the `version` tool (spec/surface §4): its
+     * own version, build info and the module its component packages resolve from.
+     * Set by `omg mcp`; absent for a library embedding (the tool then reports the
+     * engine's own version and whatever components resolve from core).
+     */
+    host?: HostInfo;
 }
 export declare function buildServer(ctx: ServerContext): McpServer;

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,20 +11,19 @@ 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";
+import { versionInfo } from "../version.js";
 // Kernel-op schemas (04 §1) published as the `apply` tool's op grammar. Giving
 // each op a real schema (rather than z.any()) makes the required fields
 // discoverable in the tool's JSON schema and turns a malformed op — e.g. an
@@ -70,20 +68,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 });
@@ -549,7 +536,7 @@ 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>}. 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.",
+        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 {
@@ -594,7 +581,7 @@ 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>}. 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.",
+        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 {
@@ -802,53 +789,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);
@@ -956,15 +946,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);
@@ -1078,10 +1064,21 @@ 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);
+        }
+    });
+    // Which engine and which versions (spec/surface §4, 1.4). No repo scope: the
+    // answer is about the binary and its database, not a repo.
+    server.registerTool("version", {
+        description: "Which engine and which versions you are talking to: `{ engine: \"typescript\"|\"rust\", version, components: { <package>: <version> }, specs: { oqx, format, reconcile, store, properties, graph, search, mutate, sync, surface, cli }, schema, mcp: { protocol, sdk? }, runtime, commit, built }`. " +
+            "`version` is the serving binary's own; `components` every omgbase package it is built from; `specs` the spec versions it implements (compile-time constants); `schema` the database's `PRAGMA user_version`; `commit`/`built` the build's git revision and RFC 3339 time (null when unknown). No arguments, no repo scope.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok(versionInfo(store, ctx.host));
         }
         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

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