@omgbase/core 0.19.0 → 0.23.0

package/dist/src/mcp/reference.js

@@ -19,10 +19,10 @@ correlates to the current row: \`from docs where nodes exists { where kind ==
 "md:task" }\` returns only the docs that themselves contain a matching node.
 
   [select <items>] from <target> [where <pred>] [frontier <pred>] [follow <dest> [{ … }], …]
-                   [order by <expr> [asc|desc], …] [limit N] [offset N]
+                   [group by <key>, …] [having <pred>] [order by <expr> [asc|desc], …] [limit N] [offset N]
   <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)
 
-CLAUSE ORDER IS FIXED: select, from, where, frontier, follow, order by, limit, offset —
+CLAUSE ORDER IS FIXED: select, from, where, frontier, follow, group by, having, order by, limit, offset —
 each at most once; an out-of-order clause is a parse error naming the order.
 Only \`select\` may drop its keyword, and only as the first clause
 (\`path, era from docs where …\`). A top-level predicate needs \`where\`, because
@@ -109,12 +109,19 @@ read a bare non-colliding key performs), \`frontmatter.<k>\`, \`inline.<k>\`. So
 everywhere: a hit's \`id\` is docs_read's \`id\` and the \`id\` argument of blocks_read.
 
   Reserved bare names per kind (engine attributes; handles; self; relations):
-    docs    id path raw hash updated_at title tags format | data frontmatter inline | doc | blocks nodes out in out_links in_links
+    docs    id path raw hash updated_at title tags format | data frontmatter inline | doc | blocks nodes out_links in_links revisions
     blocks  id path doc_id raw hash updated_at type text attrs depth ordinal | block doc | children nodes out_links section
     nodes   id path doc_id block_id kind name value attrs | section doc block | blocks subsections children
     links   id path doc_id block_id via_id dst_id dst_path uri field dst_kind predicate provenance anchor | doc
+    revisions  id path rev seq doc_id commit ts origin actor reason hash is_current archived | doc
   A key of yours with any of these names is \`data.<k>\` (or frontmatter.<k> /
   inline.<k> by source; attrs.<k> on a block or node).
+  UNKNOWN NAMES: a name that is none of the above AND that no object of the
+  kind in this repository carries is reported before any row is read — on
+  links as a filter_invalid error naming the fields; on docs/blocks/nodes the
+  result gains \`hints\` (one line per name, nearest match when there is one)
+  and the rows still come back; in a plan/apply/execute selector it is refused.
+  A property some objects carry is known (partial presence is normal).
 
 docs:
   - bare identifier  = a document PROPERTY (frontmatter + inline \`key:: value\`,
@@ -136,7 +143,8 @@ docs:
                        links as rows; the documents at their other end are
                        out_links collect distinct { from dst } and
                        in_links collect distinct { from doc } — there is no
-                       out / in relation).
+                       out / in relation), revisions (the document's stored
+                       revisions, oldest first — see revisions below).
 
 blocks:
   - bare fields      = doc_id (the owning doc), type, text (normalized), ordinal
@@ -181,20 +189,39 @@ links:  (the authored link graph as rows — one per open link: the relation a l
                        open edges only (history is blocks_history/changes_since).
   - text()/semantic() are N/A on links.
 
+revisions:  (history as rows — one per stored revision of every document of the
+        repository, deleted documents included: what docs_history lists, queryable)
+  - bare fields      = rev (= id), seq (1, 2, … per document), doc_id, commit,
+                       ts (the commit's time, sorts chronologically), origin
+                       ("observed"/"api"/"import"/"projection"), actor, reason,
+                       hash (the rendered file's sha256 — docs_history's hash),
+                       is_current (true for the document's current revision),
+                       archived (true when the bodies moved to an archive segment:
+                       the row stays, docs_read { at } reads through the segment).
+  - attributes       = id (the revision id, r_…), path (the path the revision
+                       was committed under — a move re-paths only the current
+                       revision, so earlier ones keep the old path). doc.<key>
+                       reaches the document's CURRENT row; absent for a deleted
+                       document, so where doc == null is the revisions of deleted documents.
+  - on docs          = revisions is a relation (oldest first): a document with
+                       more than one version is docs { revisions count { } > 1 }.
+  - text()/semantic() are N/A on revisions. The body as of a revision is
+    docs_read { path, at: "<rev>" } (docs_read_at is the same call).
+
 ## Scoping (ADR-015; the root row since surface 2.0): bare names are LOCAL
 
   name          the CURRENT row only — never falls through to an enclosing row
                 or the repository; an absent field is simply absent.
   ^name         one scope OUT (the enclosing row's fields/intrinsics/lifts);
                 ^^name two scopes out. \`^path\` = the enclosing row's path.
-  ^docs ^nodes ^blocks ^links
+  ^docs ^nodes ^blocks ^links ^revisions
                 THE ROOT ROW (surface 2.0, oqx 0.18): the repository is the root
                 scope's row, one scope out from a top-level row, so ^docs there is
                 the whole documents scan (uncorrelated until you add a ^ predicate);
                 one caret per enclosing block (^^docs from depth two), or the
                 absolute 0^docs from ANY depth. ^id / 0^id = the repository id.
                 ^$it = the root object: ^$it.docs ≡ ^docs, entries(^$it) names the
-                four collections. At the root scope itself a bare target is the scan
+                five collections. At the root scope itself a bare target is the scan
                 (docs count { … }, from docs, entries(docs)).
                 ERRORS: a bare \`docs\` INSIDE a block reads a property of the current
                 row, which has none — refused ("did you mean ^docs"); \`^docs\` AT THE
@@ -231,10 +258,29 @@ links:  (the authored link graph as rows — one per open link: the relation a l
   strings      x.contains("s") x.startsWith("p") x.endsWith("s") x.matches("^re$")
                (real regex) x.lower() x.upper() size(x). ALL CASE-SENSITIVE —
                fold with .lower(): title.lower().contains("aurora").
+               Infix regex: x ~ "re" is x.matches("re"); x ~* "re" is the
+               case-insensitive match; x !~ "re" and x !~* "re" negate them.
+               Unanchored unless the pattern anchors; an absent x is false
+               under ~ and TRUE under !~ (not SQL's NULL).
   functions    has(f)  size(x)  list(x)  entries(x)  range(s)
+  dates        a date is an ISO string, a duration a NUMBER OF SECONDS; arithmetic
+               is METHODS, never + or - (+ concatenates strings).
+               date("today"|"now"|"yesterday"|"tomorrow"|"sow"|"eow"|"som"|"eom"|
+               "soy"|"eoy") — the host clock, UTC; date("2026-10-15") canonical ISO
+               (absent if unparseable). dur("1h30m") dur("2 days, 3 hours")
+               dur("P1DT2H") dur(90) → seconds (year = 365 d, month = 30 d).
+               d.plus(dur("30 days"))  d.minus(86400)  d.plus("1 month") (calendar:
+               Jan 31 → Feb 28)  a.until(b) → signed seconds  d.year() d.month()
+               d.day() d.weekday() (1 = Mon) d.hour() d.minute() d.second()
+               d.date()  d.format("EEE dd MMM yyyy")  n.dur_text() → "1h 30m"
+               n.dur_iso() → "PT1H30M". Total: a non-date is absent, so
+               \`where date(due) < date("today").minus(dur("30 days"))\` just
+               filters. A datetime is never < its own date: compare
+               updated_at.date() == date("today"), or < date("tomorrow").
   literals     "str" 'str' 123 1.5 true false null
-  determinism  no now()/clock/random. Lists/structs are not literals; ternary is
-               not supported. Errors surface as filter_invalid.
+  determinism  no random; the only clock is date("today"/"now"/…), read once per
+               query. Lists/structs are not literals; ternary is not supported.
+               Errors surface as filter_invalid.
   scalars vs lists  a list-authored key never == a scalar (tags == "x" is false
                when tags is a list) — use \`"x" in tags\` / \`in list(tags)\`.
 
@@ -422,6 +468,10 @@ text()/where prune the candidate set; only order by reweights.
   from blocks order by semantic("identity preservation across edits") desc limit 10
   select uri from links where dst_kind == "external"
   docs count { where layer == "canon" }
+  select seq, origin, ts, hash from revisions where path == "/processes/calcination.md" order by seq desc
+  from docs where revisions count { where origin == "api" } > 0
+  select p: path, d: doc.path from revisions where doc == null
+  select layer, n: count(), titles: collect(title), open: rows count { where nodes exists { where kind == "md:task" and not checked } } from docs group by layer having count() > 1 order by count() desc
 
 Common mistake: \`$path\`/\`$id\` (the 2.x spelling) — omgbase has no $ names; write
 \`path\`/\`id\`. Another: \`where tags == "x"\` on a list-valued key is false — write

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,23 +1202,20 @@ 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. A revision whose bodies were moved to an archive segment (`archived` in docs_history / the revisions target) reads through the segment when it is attached; otherwise the call fails `revision_archived` with `data: { rev, archive, path? }` — an operator attaches the file with `omg history attach`.",
         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);
         }
     });
     tool("docs_history", {
-        description: "VERSION HISTORY of matching documents, grouped BY DOCUMENT: for each doc (`id`, `path`, `deleted`, `currentRev`), its ordered revision list (oldest→newest) with `rev`/`seq`/`commit`/`updated_at`/`origin`/`actor`/`hash`/`isCurrent`. Give `path_glob` (e.g. \"journal/*\" — `*` matches ACROSS `/`, so journal/* and journal/** are equivalent) OR a single document by `id` or `path`; at least one is required. `hash` (hex of the revision's rendered file hash) lets you spot no-op vs real changes. Feed a returned `rev` into `docs_read_at` (whole doc AT that rev) or `docs_diff` (block-grain changes BETWEEN two revs). By default only live docs; `include_deleted:true` also returns tombstoned docs (their history is intact for audit). `limit` caps DOCUMENTS returned (default 50) with a `truncated` flag. Contrast `changes_since`: a repo-wide COMMIT feed, not this per-document view.",
+        description: "VERSION HISTORY of matching documents, grouped BY DOCUMENT: for each doc (`id`, `path`, `deleted`, `currentRev`), its ordered revision list (oldest→newest) with `rev`/`seq`/`commit`/`updated_at`/`origin`/`actor`/`hash`/`isCurrent`/`archived` (true when the revision's bodies live in an archive segment — the row stays, docs_read_at reads through the segment while it is attached). Give `path_glob` (e.g. \"journal/*\" — `*` matches ACROSS `/`, so journal/* and journal/** are equivalent) OR a single document by `id` or `path`; at least one is required. `hash` (hex of the revision's rendered file hash) lets you spot no-op vs real changes. Feed a returned `rev` into `docs_read_at` (whole doc AT that rev) or `docs_diff` (block-grain changes BETWEEN two revs). By default only live docs; `include_deleted:true` also returns tombstoned docs (their history is intact for audit). `limit` caps DOCUMENTS returned (default 50) with a `truncated` flag. Contrast `changes_since`: a repo-wide COMMIT feed, not this per-document view.",
         inputSchema: {
             path_glob: z.string().optional(),
             ...DOC_ARGS,

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 {