@omgbase/core 0.19.0 → 0.21.0

package/dist/src/mcp/server.js

@@ -12,7 +12,7 @@ import { oqxRunAsync, collectSemanticPhrases } from "../oqx/run.js";
 import { graphNeighborhood } from "./graph.js";
 import { textSearch } from "../search/text.js";
 import { EngineError, errorBody } from "./errors.js";
-import { argumentError, validateArguments } from "./arguments.js";
+import { argumentError, stringList, validateArguments } from "./arguments.js";
 import { linksRetarget, linksRepair } from "../mutate/macros.js";
 import { canonicalDocPath } from "../mutate/docs.js";
 import { applyEffects, executeByDigest, executePlan, planEffects } from "../mutate/plan.js";
@@ -84,7 +84,7 @@ const selectionExpectSchema = z.object({ max: z.number().int().nonnegative() });
 function selectorArgs(args) {
     return { ...(args.select !== undefined ? { select: args.select } : {}), ...(args.expect !== undefined ? { expect: args.expect } : {}) };
 }
-const effectSchema = z.looseObject({ op: z.enum(["create", "insert", "set", "unset", "move", "remove", "split", "merge", "retarget"]) }).describe("one effect: { op: \"create\", path, markdown, frontmatter? } | { op: \"insert\", into: Target, at?, markdown, expect? } | { op: \"set\", target, field, value, expect? } | { op: \"unset\", target, field, expect? } | { op: \"move\", target: document, to, retarget_inbound? } | { op: \"move\", targets: [block…], into, at?, expect? } | { op: \"remove\", target: document } | { op: \"remove\", targets: [block…], expect? } | { op: \"split\", target: block, at: [byte…], expect? } | { op: \"merge\", targets: [block…], separator?, expect? } | { op: \"retarget\", repairs: [{ from, to }], path_glob? }; Target = { kind: \"document\", id? | path? } | { kind: \"block\", id } | { kind: \"node\", id } | { kind: \"section\", heading_id }; any id may be $new.<n> for an identity an earlier effect creates");
+const effectSchema = z.looseObject({ op: z.enum(["create", "insert", "set", "unset", "move", "remove", "split", "merge", "retarget"]) }).describe("one effect: { op: \"create\", path, markdown, frontmatter? } | { op: \"insert\", into: Target, at?, markdown, expect? } | { op: \"set\", target, field, value, expect? } | { op: \"unset\", target: document, field: \"frontmatter.<key>\", expect? } | { op: \"move\", target: document, to, retarget_inbound? } | { op: \"move\", targets: [block…], into, at?, expect? } | { op: \"remove\", target: document } | { op: \"remove\", targets: [block…], expect? } | { op: \"split\", target: block, at: [byte…], expect? } | { op: \"merge\", targets: [block…], separator?, expect? } | { op: \"retarget\", repairs: [{ from, to }], path_glob? }. Target: a bare document path, a block/node id, $new.<n> (an identity an earlier effect creates), or { kind: \"document\", id? | path? } | { kind: \"block\", id } | { kind: \"node\", id } | { kind: \"section\", heading_id }. at: \"start\" | \"end\" | { before: <block id> } | { after: <block id> } — a place among the children of `into`, so \"right after block X\" is into: X's parent (its parent block id, or the document path when X is top-level), at: { after: X }. field: a block's is \"markdown\" or \"attrs.checked\"; a document's \"frontmatter.<key>\" or (set only) \"content\"; a node's an editable property (value, name, checked). expect on a single-target op: { content_hash?, parent_children_hash?, revision? }; on remove/merge targets it is keyed by block id: { <block id>: { content_hash?, parent_children_hash? } }. expect: { max } is the request's top-level argument beside select, never inside an effect.");
 // An example ladder (spec/surface §4 "Descriptions", 4.3): the description of
 // each `MINIMAL_TOOLS` tool is a one-line summary, then one example per line —
 // a rung is a line beginning `{` with the call's arguments as JSON, three
@@ -99,6 +99,10 @@ const effectSchema = z.looseObject({ op: z.enum(["create", "insert", "set", "uns
 // thing; the plans they produce equal the 4.3 object-form rungs' (pinned by
 // `mcp/examples.test.ts`).
 const ladder = (...lines) => lines.join("\n");
+// The `docs_read` ladder's time-travel rung (4.7): the revision id is the one
+// the spec minter gives `/processes/calcination.md`'s ingest revision over the
+// alchemy corpus (`examples.json` runs the rung before any write).
+const REVISION_RUNG = "{\"path\":\"/processes/calcination.md\",\"at\":\"r_7\"}   as of a revision (rev ids: from revisions where path == \"/processes/calcination.md\")";
 function ok(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload) }] };
 }
@@ -236,6 +240,15 @@ export function buildServer(ctx) {
         }
         return (byId ?? byPath).docId;
     }
+    // `docs_read { at }` and its sugar `docs_read_at` (spec/surface §2, 4.7): the
+    // document AS OF a revision, `spec/store` §6.2 reconstruct; a revision that is
+    // not the document's is `target_missing`.
+    function docsReadAt(docId, rev) {
+        const res = readDocumentAtRevision(store, docId, rev);
+        if (!res)
+            throw new EngineError("target_missing", `no revision ${JSON.stringify(rev)} for document ${docId}`, { data: { doc: docId, rev } });
+        return res;
+    }
     // The owning document of a block id (`blocks_read`): the block must be live.
     function docOfBlock(blockId) {
         const row = store.db.prepare("SELECT doc_id FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(blockId);
@@ -415,16 +428,26 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_read", {
-        description: ladder("docs_read — One document, whole: raw bytes plus properties { frontmatter, inline, computed } and id/path/rev.", "{\"path\":\"/processes/calcination.md\"}   by path (either form)", "{\"path\":\"/processes/calcination.md\",\"include_ids\":true}   plus ids (pre-order), hashes (the CAS tokens expect.content_hash takes), parents (null = top level)", "{\"id\":\"d_14\"}   by id (a query hit's id)", "Structure only: query md:section nodes. Many documents: a query with select raw. Grammar: query_syntax."),
+        description: ladder("docs_read — One document, whole: raw bytes plus properties { frontmatter, inline, computed } and id/path/rev.", "{\"path\":\"/processes/calcination.md\"}   by path (either form)", "{\"path\":\"/processes/calcination.md\",\"include_ids\":true}   plus ids (pre-order), hashes (the CAS tokens expect.content_hash takes), parents (null = top level)", "{\"id\":\"d_14\"}   by id (a query hit's id)", REVISION_RUNG, "Structure only: query md:section nodes. Many documents: a query with select raw. Grammar: query_syntax."),
         inputSchema: {
             ...DOC_ARGS,
             include_ids: z.boolean().optional(),
+            at: z.string().optional(),
             ...REPO_ARG,
         },
     }, async (args) => {
         try {
             const { repoId } = repoScope(args.repo);
-            const docId = locateDoc(repoId, "docs_read", registry.get("docs_read").shape, args);
+            const shape = registry.get("docs_read").shape;
+            const docId = locateDoc(repoId, "docs_read", shape, args);
+            if (args.at !== undefined) {
+                // `at` (4.7): the document AS OF that revision — `docs_read_at`'s
+                // code path, so the two return the same bytes. Block ids at a past
+                // revision are a later question: `include_ids` is refused with `at`.
+                if (args.include_ids)
+                    throw argumentError("docs_read", "`include_ids` is not available with `at`", shape);
+                return ok(docsReadAt(docId, args.at));
+            }
             const res = docsRead(store, docId, args.include_ids ? { includeIds: true } : {});
             if (!res)
                 throw new EngineError("doc_missing", `no document with id or path ${JSON.stringify(args.id ?? args.path)}`, { data: { id: docId } });
@@ -437,7 +460,7 @@ export function buildServer(ctx) {
     tool("docs_read_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 document id OR a path, in either form), and get back one full read per ref. Returns `{ items, errors, truncated }`: each found doc is a full docs_read projection (`raw` = complete file bytes verbatim, `properties` grouped by source, plus `id`/`path`/`rev`, and — with include_ids:true — the document's ordered block `ids`, a `hashes` {block `id` → block `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/blocks_search/blocks_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 (docs_get_many before surface 3.0).",
         inputSchema: {
-            docs: z.array(z.string()),
+            docs: stringList(),
             include_ids: z.boolean().optional(),
             budget_tokens: z.number().int().optional(),
             ...REPO_ARG,
@@ -502,7 +525,7 @@ export function buildServer(ctx) {
     tool("blocks_read_many", {
         description: "Fetch up to 100 blocks by id (in request order) with budget truncation — the plural of blocks_read (nodes_get_many before surface 3.0). Block ids are globally unique, so `ids` may span ANY number of documents — each id is resolved to its owning doc server-side. Result carries `nodes` (the hydrated blocks, one per resolved id), `truncated` (cap or `budget_tokens` hit — the first resolved block 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: {
-            ids: z.array(z.string()),
+            ids: stringList(),
             resolution: z.enum(["skeleton", "outline", "text", "raw", "full"]).optional(),
             budget_tokens: z.number().int().optional(),
             ...REPO_ARG,
@@ -573,7 +596,7 @@ export function buildServer(ctx) {
         inputSchema: {},
     }, async () => ok({ syntax: QUERY_SYNTAX }));
     tool("query", {
-        description: ladder("query — Read anything: rows with id and path plus your projection, from docs, blocks, nodes or links.", "{\"query\":\"select title, stage from docs where type == \\\"process\\\"\"}   frontmatter fields by name", "{\"query\":\"select b: block_id from nodes where kind == \\\"md:section\\\" and name == \\\"Tasks\\\" and path == \\\"/processes/calcination.md\\\"\"}   a heading's block id by its text (the heading_id an insert into a section takes)", "{\"query\":\"select value from nodes where kind == \\\"md:task\\\" and not checked and path == \\\"/processes/calcination.md\\\"\"}   open tasks in one document (a task node's text is its value)", "{\"query\":\"docs count { where layer == \\\"canon\\\" }\"}   a scalar", "{\"query\":\"select path from docs where \\\"process\\\" in tags order by path limit 5\"}   list membership, ordering; a truncated page's cursor continues it", "Full grammar, follow, ^docs joins, text()/semantic(): call query_syntax."),
+        description: ladder("query — rows (id, path, projection) from docs, blocks, nodes or links.", "{\"query\":\"select title, stage from docs where \\\"process\\\" in tags order by path limit 5\"}   frontmatter; membership; order, limit", "{\"query\":\"select type, text from blocks where path == \\\"/processes/calcination.md\\\"\"}   a document's blocks in order", "{\"query\":\"select block_id from nodes where kind == \\\"md:section\\\" and name == \\\"Tasks\\\" and path == \\\"/processes/calcination.md\\\"\"}   a heading's block id", "{\"query\":\"select path, value from nodes where kind == \\\"md:task\\\" and not checked\"}   open tasks", "{\"query\":\"select path, block_id from links where dst_path == \\\"/processes/calcination.md\\\"\"}   inbound links (path = source)", "{\"query\":\"select path from docs where title ~* \\\"salt\\\"\"}   regex (~* ci, !~ not); substring: .contains(\\\"s\\\")", "Also docs count { where … }, follow, ^docs joins, text()/semantic(): query_syntax."),
         inputSchema: {
             query: z.string(),
             limit: z.number().int().optional(),
@@ -601,11 +624,11 @@ export function buildServer(ctx) {
     tool("graph", {
         description: "Neighborhood macro: the bounded graph AROUND one or more root documents in ONE call — { documents, links, frontier } — so you can orient without hand-writing an OQX `follow`. This is a CONVENIENCE WRAPPER, not a new engine: it compiles its args into an OQX `follow out_links collect { from dst }` / `follow in_links collect { from doc }` query and runs it through the same `query` path (the returned `queries` field is the exact follow query it generated). It does NOT replace `follow` or `from links` — reach for the `query` tool directly when you need successor/frontier predicates, `$key`-keyed identity, `$ordinal` budgets, cross-document correlation, or the links scan with its own projections. `roots` are one or more doc refs (paths and/or ids); they are depth 0. `degrees` is the max hop distance (root = 0; maps to `follow … collect { … depth degrees+1 }`, capped so degrees+1 ≤ 8; default 1). `direction` is `out` (outgoing links), `in` (backlinks), or `both` (default). `predicate` restricts the neighborhood to documents reachable from a root via edges of that predicate (both the documents and the edges are filtered). `select` adds document projections (OQX select expressions, e.g. \"layer\", \"path\"). `max_documents` caps the distinct document set (default 200) with a `truncated` flag. Returns: `documents` (each with `id`/`path`/`degree` = min hops from a root/`frontier` bool + your projections — a bare-name selection such as \"title\" is its own key, `id`/`path` land on the envelope keys, and any other expression is `sel_<i>`), `links` (the traversed links as rows of the `links` target under its own field names — `id`, `doc_id`/`block_id` (the source), `via_id`, `dst_id`, `dst_path`, `uri`, `dst_kind`, `predicate`, `provenance`, `anchor`, `field`; external `x_…` and dangling phantom endpoints are preserved as edge stubs, exactly as `from links` surfaces them), and `frontier` (the documents on the outer boundary — `{ id, path, degree }`, min degree == degrees; at degrees 0 that is the roots themselves).",
         inputSchema: {
-            roots: z.array(z.string()).min(1),
+            roots: stringList({ min: 1 }),
             degrees: z.number().int().optional(),
             direction: z.enum(["in", "out", "both"]).optional(),
             predicate: z.string().optional(),
-            select: z.array(z.string()).optional(),
+            select: stringList().optional(),
             max_documents: z.number().int().optional(),
             ...REPO_ARG,
         },
@@ -678,14 +701,21 @@ export function buildServer(ctx) {
     // commits exactly a plan (the plan form, or the digest form `plan_id` +
     // `effects`); `apply { effects }` above is plan + execute in one call.
     tool("plan", {
-        description: ladder("plan — Preview a write: the frozen Plan (summary, diffs, $new.n per minted id) burns no id; execute next.", "{\"effects\":[{\"op\":\"set\",\"target\":\"/processes/calcination.md\",\"field\":\"frontmatter.verified\",\"value\":false}]}   path = document", "{\"effects\":[{\"op\":\"insert\",\"into\":{\"kind\":\"section\",\"heading_id\":\"b_153\"},\"markdown\":\"- [ ] Weigh the calx\"}]}   under a heading", "{\"effects\":[{\"op\":\"create\",\"path\":\"lab/march.md\",\"markdown\":\"# March\\n\"},{\"op\":\"insert\",\"into\":\"$new.0\",\"markdown\":\"Hi.\"}]}   fill it: $new.0", "{\"select\":\"from docs where stage == \\\"nigredo\\\"\",\"effects\":[{\"op\":\"set\",\"field\":\"frontmatter.ok\",\"value\":true}]}   no target = the hit", "{\"select\":\"from docs where type == \\\"lab-note\\\"\",\"effects\":[{\"op\":\"insert\",\"into\":\"-> `/processes/${subject}.md`\",\"markdown\":\"-> `[${title}](${path})`\"}]}   -> reads the row", "Ops: create insert set unset move remove split merge retarget. Grammar: query_syntax."),
-        inputSchema: { effects: z.array(effectSchema), select: z.string().optional(), expect: selectionExpectSchema.optional(), ...REPO_ARG },
+        description: ladder("plan — Preview a write: the Plan (summary, $new.n ids) burns no id; execute next. diffs: true for file bodies.", "{\"effects\":[{\"op\":\"set\",\"target\":\"/processes/calcination.md\",\"field\":\"frontmatter.verified\",\"value\":false}]}   path = doc", "{\"effects\":[{\"op\":\"insert\",\"into\":{\"kind\":\"section\",\"heading_id\":\"b_153\"},\"markdown\":\"- [ ] Weigh the calx\"}]}   in a section", "{\"effects\":[{\"op\":\"create\",\"path\":\"lab/march.md\",\"markdown\":\"# March\\n\"},{\"op\":\"insert\",\"into\":\"$new.0\",\"markdown\":\"Hi.\"}]}   fill it: $new.0", "{\"select\":\"from docs where stage == \\\"nigredo\\\"\",\"effects\":[{\"op\":\"set\",\"field\":\"frontmatter.ok\",\"value\":true}]}   no target: the hit", "{\"select\":\"from docs where type == \\\"lab-note\\\"\",\"effects\":[{\"op\":\"insert\",\"into\":\"-> `/processes/${subject}.md`\",\"markdown\":\"-> `[${title}](${path})`\"}]}   -> reads the row", "Ops: create insert set unset move remove split merge retarget; grammar: query_syntax."),
+        inputSchema: { effects: z.array(effectSchema), select: z.string().optional(), expect: selectionExpectSchema.optional(), diffs: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
             if (!rootPath)
                 throw new EngineError("repo_not_found", "repo has no filesystem source; mutation disabled");
-            return ok(surfacePlan(planEffects(store, { repoId, rootPath, effects: args.effects, ...selectorArgs(args), ...LOCK_DIR })));
+            const plan = surfacePlan(planEffects(store, { repoId, rootPath, effects: args.effects, ...selectorArgs(args), ...LOCK_DIR }));
+            // (4.5) `preview.diffs` — whole before/after bodies of every touched
+            // document — only on request: `diffs: true`. The digest is over the
+            // core, never the preview, so `plan_id` is the same either way.
+            if (args.diffs === true || plan.preview === undefined)
+                return ok(plan);
+            const { diffs: _diffs, ...preview } = plan.preview;
+            return ok({ ...plan, preview });
         }
         catch (e) {
             return fail(e);
@@ -762,7 +792,7 @@ export function buildServer(ctx) {
     });
     tool("blocks_move", {
         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. Sugar for `apply { effects: [{ op: \"move\", targets, into, at, expect? }] }` — returns the Receipt; preview with `plan`.",
-        inputSchema: { blocks: z.array(z.string()), to: z.string(), at: atSchema.optional(), expect: parentExpectSchema.optional(), ...REPO_ARG },
+        inputSchema: { blocks: stringList(), to: z.string(), at: atSchema.optional(), expect: parentExpectSchema.optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
@@ -783,7 +813,7 @@ export function buildServer(ctx) {
     });
     tool("blocks_remove", {
         description: "Remove block(s) (the resurrection pool catches regret). `blocks` are refs; removing a block removes its whole subtree, and a set that names both a container and some of its descendants (e.g. every id of a section straight from docs_read include_ids) is fine — it collapses to the top-most blocks. Sugar for `apply { effects: [{ op: \"remove\", targets }] }` — returns the Receipt; preview with `plan` (its `preview.results[0].removed` lists everything that would leave). To delete a whole document use docs_delete.",
-        inputSchema: { blocks: z.array(z.string()), ...REPO_ARG },
+        inputSchema: { blocks: stringList(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
@@ -813,7 +843,7 @@ export function buildServer(ctx) {
     });
     tool("blocks_merge", {
         description: "Merge adjacent blocks into the first, joined by `separator` (default a blank line). `blocks` are refs (≥2). Sugar for `apply { effects: [{ op: \"merge\", targets, separator? }] }` — returns the Receipt; preview with `plan`.",
-        inputSchema: { blocks: z.array(z.string()), separator: z.string().optional(), ...REPO_ARG },
+        inputSchema: { blocks: stringList(), separator: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
@@ -828,7 +858,7 @@ export function buildServer(ctx) {
     });
     tool("blocks_check", {
         description: "Macro: check (or uncheck with checked:false) the given task blocks. `ids` are the blocks' ids (or refs). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"block\", id }, field: \"attrs.checked\", value }, …] }`, one per block, each CAS-pinned — returns the Receipt; preview with `plan` (tasks_complete { blocks } before surface 3.0).",
-        inputSchema: { ids: z.array(z.string()), checked: z.boolean().optional(), ...REPO_ARG },
+        inputSchema: { ids: stringList(), checked: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId, rootPath } = repoScope(args.repo);
@@ -1056,7 +1086,7 @@ export function buildServer(ctx) {
     });
     tool("docs_set_meta", {
         description: "Surgical frontmatter patch: set the given keys and/or unset named keys on the document addressed by `id` or `path`. Other frontmatter and the whole body are preserved (every block keeps its id). Sugar for `apply { effects: [{ op: \"set\", target: { kind: \"document\", id }, field: \"frontmatter.<key>\", value }, { op: \"unset\", …, field: \"frontmatter.<key>\" }, …] }`, one effect per key — returns the Receipt; at least one of `set`/`unset` is required. Preview with `plan` over those effects (`preview.diffs[path]` is the file before → after).",
-        inputSchema: { ...DOC_ARGS, set: z.record(z.string(), z.unknown()).optional(), unset: z.array(z.string()).optional(), ...REPO_ARG },
+        inputSchema: { ...DOC_ARGS, set: z.record(z.string(), z.unknown()).optional(), unset: stringList().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
             const scope = repoScope(args.repo);
@@ -1127,7 +1157,7 @@ export function buildServer(ctx) {
         }
     });
     tool("blocks_history", {
-        description: "A block's biography: the commits that touched the block `id` names, with disposition kind/confidence/reason, newest first (history_node before surface 3.0 — it always took a block id and returned the block's changes). Not repo-scoped: block ids are global.",
+        description: "A block's biography: the commits that CHANGED the block `id` names — inserted, edited, moved, split/merge lineage, resurrected — with disposition kind/confidence/reason, newest first. A commit that rewrote the document but left this block byte-identical in place is not listed (store 14.2: `same` verdicts are not persisted; through 14.1 every commit to the document appeared here), so the newest entry's `ts` is the block's `updated_at`; to learn whether the block was present in some other commit, diff two revisions with docs_diff (history_node before surface 3.0 — it always took a block id and returned the block's changes). Not repo-scoped: block ids are global.",
         inputSchema: { id: z.string(), limit: z.number().int().optional() },
     }, async (args) => {
         try {
@@ -1172,16 +1202,13 @@ export function buildServer(ctx) {
         }
     });
     tool("docs_read_at", {
-        description: "TIME-TRAVEL read: the whole file bytes of a document AS OF a past revision — `raw` is the reconstructed source at that `rev` (fences/tables/list markers preserved), plus `id`/`path` (the path as of that revision)/`rev`. Use this to audit or answer 'what did this doc say at revision N', or to fetch the exact prior text before reverting. Get a `rev` from docs_diff, blocks_history, docs_history or changes_since. Contrast: docs_read = current bytes; docs_diff = block-grain changes BETWEEN two revisions. `renderedHashMatch` is true when the reconstruction is byte-for-byte the file at that revision; it can be false for an old revision ONLY when the document's leading/frontmatter trivia (separator bytes, not block content) changed since — block content always reconstructs faithfully. `properties` are CURRENT values (propertiesAreCurrent:true), since property history is not stored. Address the document by `id` or `path` plus a `rev` id.",
+        description: "TIME-TRAVEL read: the whole file bytes of a document AS OF a past revision — `raw` is the reconstructed source at that `rev` (fences/tables/list markers preserved), plus `id`/`path` (the path as of that revision)/`rev`. Sugar for `docs_read { id | path, at: rev }` (surface 4.7) — the same result, byte for byte. Use this to audit or answer 'what did this doc say at revision N', or to fetch the exact prior text before reverting. Get a `rev` from `query` over the `revisions` target (`from revisions where path == … order by seq`), docs_diff, blocks_history, docs_history or changes_since. Contrast: docs_read = current bytes; docs_diff = block-grain changes BETWEEN two revisions. `renderedHashMatch` is true when the reconstruction is byte-for-byte the file at that revision; it can be false for an old revision ONLY when the document's leading/frontmatter trivia (separator bytes, not block content) changed since — block content always reconstructs faithfully. No `properties`: the property table is current-state only (through 4.6 the current bag rode along flagged propertiesAreCurrent). Address the document by `id` or `path` plus a `rev` id.",
         inputSchema: { ...DOC_ARGS, rev: z.string(), ...REPO_ARG },
     }, async (args) => {
         try {
             const { repoId } = repoScope(args.repo);
             const docId = locateDoc(repoId, "docs_read_at", registry.get("docs_read_at").shape, args);
-            const res = readDocumentAtRevision(store, docId, args.rev);
-            if (!res)
-                throw new EngineError("target_missing", `no revision ${JSON.stringify(args.rev)} for document ${docId}`, { data: { doc: docId, rev: args.rev } });
-            return ok(res);
+            return ok(docsReadAt(docId, args.rev));
         }
         catch (e) {
             return fail(e);

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

@@ -8,6 +8,7 @@ import { type LinkRepairCount, type RetargetHit } from "./macros.js";
 import type { At, Expect } from "./ops.js";
 import type { IdentityPreview } from "./opset.js";
 import { MutationError } from "./tree.js";
+import { type FixRequest } from "./canonical.js";
 /** What an effect addresses. `section` is a derived range (ADR-005), never a stored id.
  *  `symbol` (3.2, §11.8 "Sugar"): a bare `"$new.n"` target whose kind — document or block — the
  *  symbol table decides when the effect is resolved; it never reaches a resolved effect. */
@@ -172,8 +173,25 @@ export type ResolvedEffect = {
     }[];
     path_glob?: string;
 };
-/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }`. */
-export declare function effectInvalid(message: string): MutationError;
+/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }` — with a `fix` (3.4, §8) when the shape check can spell the corrected call. */
+export declare function effectInvalid(message: string, fix?: string): MutationError;
+/**
+ * What the shape check needs to spell a `fix` for the shape errors of §8
+ * (3.4): the request as given (the corrected call is that request with the
+ * offending effect rewritten — the effect at `effects[i]` AS WRITTEN, before
+ * any desugaring) and a live-row lookup for the one fix that needs the store:
+ * `parentOf(block id)` → the block's parent id (`null` at the top level) and
+ * its document's path (storage form), or `null` when no live block has the id
+ * (then there is no fix). The planner's compile (`select.ts`) supplies it; a
+ * library call without it gets the same errors with no `fix`.
+ */
+export interface ShapeFixContext {
+    request: FixRequest;
+    parentOf: (blockId: string) => {
+        parent: string | null;
+        path: string;
+    } | null;
+}
 /** The `-> ` leader (3.2, §11.8 "Sugar"): a string beginning exactly so is an OQX expression, the rest of the string. */
 export declare const EXPRESSION_LEADER = "-> ";
 /** A path-looking string: contains `/` or ends `.md` (the bare document target of §11.8 "Sugar"). */
@@ -191,10 +209,10 @@ export declare function isTargetId(s: string): boolean;
  */
 export declare function bareTarget(ref: string, here: string): EffectTarget;
 export declare function validateTarget(v: unknown, here: string, kinds: readonly EffectTarget["kind"][]): EffectTarget;
-/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`). */
-export declare function validateEffect(v: unknown, i: number): Effect;
+/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`); `fix` (3.4) lets the shape errors of §8 carry their corrected call. */
+export declare function validateEffect(v: unknown, i: number, fix?: ShapeFixContext): Effect;
 /** The whole list; a non-array or an empty list is a shape error too. */
-export declare function validateEffects(v: unknown): Effect[];
+export declare function validateEffects(v: unknown, fix?: ShapeFixContext): Effect[];
 export declare const FRONTMATTER_FIELD: RegExp;
 /** The focus a conflict names: `{ kind, target, field? }`. */
 export interface Focus {

package/dist/src/mutate/effects.js

@@ -8,6 +8,7 @@ import { canonicalDocPath, composeFile, parseNewDoc, planInboundRetarget, splitF
 import { linksRepair, nodeSet } from "./macros.js";
 import { planUpdate } from "./plan-update.js";
 import { MutationError, rawHashHex, renderDoc } from "./tree.js";
+import { fixRequest, withMember } from "./canonical.js";
 export const EFFECT_OPS = ["create", "insert", "set", "unset", "move", "remove", "split", "merge", "retarget"];
 /** `$new.<n>`: an identity an earlier effect of the same request creates (§11.1). */
 export const NEW_SYMBOL_RE = /^\$new\.(0|[1-9][0-9]*)$/;
@@ -18,10 +19,86 @@ export function isNewSymbol(s) {
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }`. */
-export function effectInvalid(message) {
-    return new MutationError("filter_invalid", message, { reason: message, hint: "arguments" });
+/** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }` — with a `fix` (3.4, §8) when the shape check can spell the corrected call. */
+export function effectInvalid(message, fix) {
+    return new MutationError("filter_invalid", message, { reason: message, hint: "arguments", ...(fix !== undefined ? { fix } : {}) });
 }
+function fixerFor(ctx, i, v) {
+    if (ctx === undefined)
+        return undefined;
+    const list = Array.isArray(ctx.request.effects) ? ctx.request.effects : undefined;
+    const written = list !== undefined && isRecord(list[i]) ? list[i] : v;
+    return {
+        written,
+        build: (effect, expect) => fixRequest({
+            ...ctx.request,
+            effects: withMember(ctx.request.effects, [String(i)], effect),
+            ...(expect !== undefined ? { expect: expect.value } : {}),
+        }),
+        parentOf: ctx.parentOf,
+        request: ctx.request,
+    };
+}
+/** A record whose every value is a string. */
+function isStringRecord(v) {
+    return isRecord(v) && Object.values(v).every((x) => typeof x === "string");
+}
+/**
+ * §8 (3.4): an effect-level `expect.max` — the bound belongs to the request's
+ * top-level `expect`, beside `select`. The fix drops it from the effect (the
+ * rest of that `expect` stays; an emptied `expect` goes) and, when the request
+ * has a `select`, moves it to the top level unless a top-level `expect.max` is
+ * already there (then the top-level one is kept as written); without a
+ * `select` a top-level `expect` would itself be refused, so the fix only drops it.
+ */
+function effectLevelMax(v, here, f) {
+    const message = `${here}: \`expect.max\` bounds a selection — it is the request's top-level \`expect\`, beside \`select\`, not an effect's`;
+    if (f === undefined)
+        return effectInvalid(message);
+    const { max, ...rest } = v;
+    const effect = { ...f.written, expect: Object.keys(rest).length > 0 ? rest : undefined };
+    if (f.request.select === undefined)
+        return effectInvalid(message, f.build(effect));
+    const top = isRecord(f.request.expect) ? f.request.expect : {};
+    return effectInvalid(message, f.build(effect, { value: "max" in top ? top : { ...top, max } }));
+}
+/**
+ * §8 (3.4): `at` given as the bare string `"after"` / `"before"` with a block
+ * `into` — "right after block X" is `into: X's parent, at: { after: X }`. The
+ * fix needs the block's live row (its parent, or its document when it is top-
+ * level, spelled as the rooted path); a block the store does not know gets no fix.
+ */
+function bareAnchor(at, into, here, f) {
+    const message = `${here}: \`at\` must be "start", "end", { before: <block id> } or { after: <block id> } — "${at} block X" is into: X's parent (a block, or the document when X is top-level), at: { ${at}: X }`;
+    if (f === undefined || into.kind !== "block")
+        return effectInvalid(message);
+    const row = f.parentOf(into.id);
+    if (row === null)
+        return effectInvalid(message);
+    const parent = row.parent === null ? referencePath(row.path) : { kind: "block", id: row.parent };
+    return effectInvalid(message, f.build({ ...f.written, into: parent, at: { [at]: into.id } }));
+}
+/**
+ * §8 (3.4): a plural-target `expect` written as `{ content_hash: { <id>: <hash>, … } }`
+ * (every key a guard name, every value a map of strings) — the fix inverts the
+ * nesting to `{ <id>: { content_hash: <hash> }, … }`.
+ */
+function invertedExpectMap(v, here, f) {
+    const keys = Object.keys(v);
+    if (keys.length === 0 || !keys.every((k) => k === "content_hash" || k === "parent_children_hash") || !Object.values(v).every(isStringRecord))
+        return null;
+    const message = `${here}: a plural-target \`expect\` is keyed by block id — { <block id>: { content_hash?, parent_children_hash? }, … }`;
+    if (f === undefined)
+        return effectInvalid(message);
+    const inverted = {};
+    for (const [guard, byId] of Object.entries(v)) {
+        for (const [id, hash] of Object.entries(byId))
+            inverted[id] = { ...inverted[id], [guard]: hash };
+    }
+    return effectInvalid(message, f.build({ ...f.written, expect: inverted }));
+}
+/** §8 (3.4): the block-field misspellings the fix corrects to `markdown`. */
+const BLOCK_FIELD_ALIASES = new Set(["text", "content", "body", "raw"]);
 function onlyKeys(e, allowed, here) {
     const extra = Object.keys(e).filter((k) => !allowed.includes(k));
     if (extra.length > 0)
@@ -118,7 +195,7 @@ function validateTargets(v, here) {
         throw effectInvalid(`${here}: \`targets\` must be a non-empty array of block targets`);
     return v.map((t, i) => validateTarget(t, `${here}.targets[${i}]`, ["block"]));
 }
-function validateAt(v, here) {
+function validateAt(v, here, into, f) {
     if (v === undefined)
         return undefined;
     if (v === "start" || v === "end")
@@ -129,13 +206,17 @@ function validateAt(v, here) {
         if (typeof v.after === "string")
             return { after: v.after };
     }
+    if ((v === "before" || v === "after") && into !== undefined)
+        throw bareAnchor(v, into, here, f);
     throw effectInvalid(`${here}: \`at\` must be "start", "end", { before: <block id> } or { after: <block id> }`);
 }
-function validateExpect(v, here) {
+function validateExpect(v, here, f) {
     if (v === undefined)
         return undefined;
     if (!isRecord(v))
         throw effectInvalid(`${here}: \`expect\` must be an object`);
+    if ("max" in v)
+        throw effectLevelMax(v, here, f);
     onlyKeys(v, ["content_hash", "parent_children_hash", "revision"], `${here}.expect`);
     const out = {};
     for (const k of ["content_hash", "parent_children_hash", "revision"]) {
@@ -145,11 +226,16 @@ function validateExpect(v, here) {
     }
     return out;
 }
-function validateExpectMap(v, here) {
+function validateExpectMap(v, here, f) {
     if (v === undefined)
         return undefined;
     if (!isRecord(v))
         throw effectInvalid(`${here}: \`expect\` must be an object keyed by block id`);
+    if ("max" in v)
+        throw effectLevelMax(v, here, f);
+    const inverted = invertedExpectMap(v, here, f);
+    if (inverted !== null)
+        throw inverted;
     const out = {};
     for (const [id, x] of Object.entries(v)) {
         if (!isRecord(x))
@@ -166,13 +252,14 @@ function validateExpectMap(v, here) {
     }
     return out;
 }
-/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`). */
-export function validateEffect(v, i) {
+/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`); `fix` (3.4) lets the shape errors of §8 carry their corrected call. */
+export function validateEffect(v, i, fix) {
     const here = `effects[${i}]`;
     if (!isRecord(v) || typeof v.op !== "string")
         throw effectInvalid(`${here}: an effect is an object whose \`op\` is one of ${EFFECT_OPS.join("/")}`);
     if (!EFFECT_OPS.includes(v.op))
         throw effectInvalid(`${here}: \`op\` must be one of ${EFFECT_OPS.join("/")} (got "${v.op}")`);
+    const f = fixerFor(fix, i, v);
     switch (v.op) {
         case "create": {
             onlyKeys(v, ["op", "path", "markdown", "frontmatter"], here);
@@ -185,9 +272,9 @@ export function validateEffect(v, i) {
         case "insert": {
             onlyKeys(v, ["op", "into", "at", "markdown", "expect"], here);
             const into = validateTarget(v.into, `${here}.into`, ["document", "section", "block"]);
-            const at = validateAt(v.at, here);
+            const at = validateAt(v.at, here, into, f);
             const markdown = requireString(v, "markdown", here);
-            const expect = validateExpect(v.expect, here);
+            const expect = validateExpect(v.expect, here, f);
             return { op: "insert", into, ...(at !== undefined ? { at } : {}), markdown, ...(expect !== undefined ? { expect } : {}) };
         }
         case "set": {
@@ -197,8 +284,8 @@ export function validateEffect(v, i) {
             if (!("value" in v))
                 throw effectInvalid(`${here}: \`value\` is required`);
             if (target.kind !== "symbol")
-                checkField(target.kind, field, here, "set");
-            const expect = validateExpect(v.expect, here);
+                checkField(target.kind, field, here, "set", f);
+            const expect = validateExpect(v.expect, here, f);
             return { op: "set", target, field, value: v.value, ...(expect !== undefined ? { expect } : {}) };
         }
         case "unset": {
@@ -207,7 +294,7 @@ export function validateEffect(v, i) {
             const field = requireString(v, "field", here);
             if (target.kind !== "symbol")
                 checkField(target.kind, field, here, "unset");
-            const expect = validateExpect(v.expect, here);
+            const expect = validateExpect(v.expect, here, f);
             return { op: "unset", target, field, ...(expect !== undefined ? { expect } : {}) };
         }
         case "move": {
@@ -215,8 +302,8 @@ export function validateEffect(v, i) {
                 onlyKeys(v, ["op", "targets", "into", "at", "expect"], here);
                 const targets = validateTargets(v.targets, here);
                 const into = validateTarget(v.into, `${here}.into`, ["document", "section", "block"]);
-                const at = validateAt(v.at, here);
-                const expect = validateExpect(v.expect, here);
+                const at = validateAt(v.at, here, into, f);
+                const expect = validateExpect(v.expect, here, f);
                 return { op: "move", targets, into, ...(at !== undefined ? { at } : {}), ...(expect !== undefined ? { expect } : {}) };
             }
             onlyKeys(v, ["op", "target", "to", "retarget_inbound"], here);
@@ -230,7 +317,7 @@ export function validateEffect(v, i) {
             if ("targets" in v) {
                 onlyKeys(v, ["op", "targets", "expect"], here);
                 const targets = validateTargets(v.targets, here);
-                const expect = validateExpectMap(v.expect, here);
+                const expect = validateExpectMap(v.expect, here, f);
                 return { op: "remove", targets, ...(expect !== undefined ? { expect } : {}) };
             }
             onlyKeys(v, ["op", "target"], here);
@@ -241,14 +328,14 @@ export function validateEffect(v, i) {
             const target = validateTarget(v.target, `${here}.target`, ["block"]);
             if (!Array.isArray(v.at) || v.at.some((n) => typeof n !== "number" || !Number.isInteger(n) || n < 0))
                 throw effectInvalid(`${here}: \`at\` must be an array of byte offsets`);
-            const expect = validateExpect(v.expect, here);
+            const expect = validateExpect(v.expect, here, f);
             return { op: "split", target, at: v.at, ...(expect !== undefined ? { expect } : {}) };
         }
         case "merge": {
             onlyKeys(v, ["op", "targets", "separator", "expect"], here);
             const targets = validateTargets(v.targets, here);
             const separator = optionalString(v, "separator", here);
-            const expect = validateExpectMap(v.expect, here);
+            const expect = validateExpectMap(v.expect, here, f);
             return { op: "merge", targets, ...(separator !== undefined ? { separator } : {}), ...(expect !== undefined ? { expect } : {}) };
         }
         case "retarget": {
@@ -267,16 +354,16 @@ export function validateEffect(v, i) {
     }
 }
 /** The whole list; a non-array or an empty list is a shape error too. */
-export function validateEffects(v) {
+export function validateEffects(v, fix) {
     if (!Array.isArray(v))
         throw effectInvalid("`effects` must be an array of effects");
     if (v.length === 0)
         throw effectInvalid("`effects` must name at least one effect");
-    return v.map((e, i) => validateEffect(e, i));
+    return v.map((e, i) => validateEffect(e, i, fix));
 }
 // §11.2: the `field` spellings per target kind.
 export const FRONTMATTER_FIELD = /^frontmatter\.(.+)$/;
-function checkField(kind, field, here, op) {
+function checkField(kind, field, here, op, f) {
     if (kind === "document") {
         if (FRONTMATTER_FIELD.test(field) || (op === "set" && field === "content"))
             return;
@@ -285,7 +372,9 @@ function checkField(kind, field, here, op) {
     if (kind === "block") {
         if (field === "markdown" || field === "attrs.checked")
             return;
-        throw effectInvalid(`${here}: a block's \`field\` is \`markdown\` or \`attrs.checked\` (got "${field}")`);
+        // (3.4, §8) `text` / `content` / `body` / `raw` on a block: the fix spells `markdown`.
+        const fix = f !== undefined && BLOCK_FIELD_ALIASES.has(field) ? f.build({ ...f.written, field: "markdown" }) : undefined;
+        throw effectInvalid(`${here}: a block's \`field\` is \`markdown\` or \`attrs.checked\` (got "${field}")`, fix);
     }
     // node: the adapter's editable props (`node_not_editable` names them when unknown)
     if (field === "" || field.includes("."))

package/dist/src/mutate/known-ids.d.ts

@@ -1,4 +1,5 @@
 import type { Store } from "../core/store/store.js";
+import type { TreeInputBlock } from "../core/store/writers.js";
 import type { IdResolver } from "../core/ingest.js";
 import type { MutDoc } from "./tree.js";
 /**
@@ -10,3 +11,21 @@ import type { MutDoc } from "./tree.js";
 export declare function makeKnownIdResolver(store: Store, repoId: string, doc: MutDoc, priorIds: Set<string>, opts?: {
     path?: string;
 }): IdResolver;
+/** A carried block's live row, as spec/reconcile §2's carry classification reads it. */
+interface PriorRow {
+    parent: string | null;
+    ordinal: number;
+    rawHashHex: string;
+}
+/**
+ * spec/reconcile §2 "Classifying a carry", applied to the api path's known ids:
+ * `moved` = the parent or the sibling index differs from the live row,
+ * `content_equal` = the raw bytes hash the same; `same` / `moved` / `edited` /
+ * `edited_moved` follow. An id with no prior row (new to this document — a
+ * mint or a cross-document arrival) is `inserted`. Pre-order over the tree.
+ */
+export declare function classifyCarries(blocks: TreeInputBlock[], prior: Map<string, PriorRow>, priorIds: Set<string>): {
+    id: string;
+    kind: string;
+}[];
+export {};