@omgbase/core 0.15.0 → 0.21.0

package/dist/src/mutate/effects.js

@@ -1,11 +1,14 @@
 import { findDoc } from "../core/read/reader.js";
-import { withIdMinter } from "../core/ids.js";
+import { normalizeVisibleText } from "../core/hash.js";
+import { referencePath } from "../core/paths.js";
+import { isValidId, withIdMinter } from "../core/ids.js";
 import { inboundLinksTo } from "../graph/inbound-links.js";
 import { readDocBase } from "./commit.js";
 import { canonicalDocPath, composeFile, parseNewDoc, planInboundRetarget, splitFrontmatter } from "./docs.js";
 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]*)$/;
@@ -16,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)
@@ -39,9 +118,56 @@ function optionalString(e, key, here) {
         throw effectInvalid(`${here}: \`${key}\` must be a string`);
     return v;
 }
-function validateTarget(v, here, kinds) {
+/** The `-> ` leader (3.2, §11.8 "Sugar"): a string beginning exactly so is an OQX expression, the rest of the string. */
+export const EXPRESSION_LEADER = "-> ";
+/** A path-looking string: contains `/` or ends `.md` (the bare document target of §11.8 "Sugar"). */
+export function looksLikePath(s) {
+    return s.includes("/") || s.endsWith(".md");
+}
+/** A node id: `n_` + 12 hex (content-hash derived, `core/store/nodes.ts`; the `resolveRef` rule). */
+const NODE_ID_RE = /^n_[0-9a-f]{12}$/;
+/** A bare id of the three target kinds (§11.8 "Sugar"). */
+export function isTargetId(s) {
+    return isValidId(s, "b") || isValidId(s, "d") || NODE_ID_RE.test(s);
+}
+/**
+ * A bare string where a target object is expected (3.2, §11.8 "Sugar"): a
+ * path-looking string → `{ kind: "document", path }`; a `b_`/`d_`/`n_` id →
+ * that kind; `$new.n` → `{ kind: "symbol", id }` (its kind is the symbol
+ * table's at resolution); a `#` locator → `filter_invalid` with a `fix`;
+ * anything else is no target. A `-> ` leader never reaches here from the
+ * planner (`select.ts` desugars it first); as a library input it is refused
+ * the same way, naming the planner.
+ */
+export function bareTarget(ref, here) {
+    if (ref.startsWith(EXPRESSION_LEADER)) {
+        const reason = `${here}: a \`-> \` expression target is bound by the planner (\`plan\` / \`apply\` / \`execute\`), not by the shape check`;
+        throw new MutationError("filter_invalid", reason, { reason, hint: "selection" });
+    }
+    if (ref.includes("#")) {
+        const reason = `${here}: ${JSON.stringify(ref)} is a locator, not a target — a bare target is a document path, a \`b_\`/\`d_\`/\`n_\` id or \`$new.n\``;
+        throw new MutationError("filter_invalid", reason, { reason, hint: "arguments", fix: "resolve the locator to an id first: `blocks_resolve { locator }`, or a `query` whose hit is the block" });
+    }
+    if (isNewSymbol(ref))
+        return { kind: "symbol", id: ref };
+    if (isValidId(ref, "b"))
+        return { kind: "block", id: ref };
+    if (isValidId(ref, "d"))
+        return { kind: "document", id: ref };
+    if (NODE_ID_RE.test(ref))
+        return { kind: "node", id: ref };
+    if (looksLikePath(ref))
+        return { kind: "document", path: ref };
+    throw effectInvalid(`${here}: a target is { kind: …, … } or a bare document path, a \`b_\`/\`d_\`/\`n_\` id or \`$new.n\` (got ${JSON.stringify(ref)})`);
+}
+export function validateTarget(v, here, kinds) {
+    if (typeof v === "string")
+        v = bareTarget(v, here);
     if (!isRecord(v) || typeof v.kind !== "string")
         throw effectInvalid(`${here}: a target is { kind: ${kinds.map((k) => `"${k}"`).join(" | ")}, … }`);
+    // A bare `$new.n` defers its kind check to resolution (`resolveEffect`); the `kinds` are the slot's.
+    if (v.kind === "symbol" && typeof v.id === "string" && isNewSymbol(v.id) && Object.keys(v).length === 2)
+        return { kind: "symbol", id: v.id };
     if (!kinds.includes(v.kind))
         throw effectInvalid(`${here}: \`kind\` must be one of ${kinds.join(", ")} (got "${v.kind}")`);
     switch (v.kind) {
@@ -69,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")
@@ -80,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"]) {
@@ -96,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))
@@ -117,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);
@@ -136,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": {
@@ -147,16 +283,18 @@ export function validateEffect(v, i) {
             const field = requireString(v, "field", here);
             if (!("value" in v))
                 throw effectInvalid(`${here}: \`value\` is required`);
-            checkField(target.kind, field, here, "set");
-            const expect = validateExpect(v.expect, here);
+            if (target.kind !== "symbol")
+                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": {
             onlyKeys(v, ["op", "target", "field", "expect"], here);
             const target = validateTarget(v.target, `${here}.target`, ["document"]);
             const field = requireString(v, "field", here);
-            checkField(target.kind, field, here, "unset");
-            const expect = validateExpect(v.expect, here);
+            if (target.kind !== "symbol")
+                checkField(target.kind, field, here, "unset");
+            const expect = validateExpect(v.expect, here, f);
             return { op: "unset", target, field, ...(expect !== undefined ? { expect } : {}) };
         }
         case "move": {
@@ -164,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);
@@ -179,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);
@@ -190,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": {
@@ -216,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;
@@ -234,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("."))
@@ -337,10 +477,14 @@ export function resolveDocumentTarget(ctx, t) {
             throw effectInvalid(`id ${JSON.stringify(t.id)} and path ${JSON.stringify(t.path)} name different documents`);
         return { kind: "document", id: t.id, path: created.path };
     }
-    const byId = t.id !== undefined ? findDoc(ctx.store, { docId: t.id }) : null;
-    if (t.id !== undefined && (!byId || byId.repoId !== ctx.repoId))
+    return findDocumentTarget(ctx.store, ctx.repoId, t);
+}
+/** An existing document's `{ id, path }` for a literal document target (`doc_missing`; `filter_invalid` when `id` and `path` disagree). */
+export function findDocumentTarget(store, repoId, t) {
+    const byId = t.id !== undefined ? findDoc(store, { docId: t.id }) : null;
+    if (t.id !== undefined && (!byId || byId.repoId !== repoId))
         throw docMissing(t.id);
-    const byPath = t.path !== undefined ? findDoc(ctx.store, { repoId: ctx.repoId, path: t.path }) : null;
+    const byPath = t.path !== undefined ? findDoc(store, { repoId, path: t.path }) : null;
     if (t.path !== undefined && !byPath)
         throw docMissing(t.path);
     if (byId && byPath && byId.docId !== byPath.docId)
@@ -348,6 +492,15 @@ export function resolveDocumentTarget(ctx, t) {
     const info = (byId ?? byPath);
     return { kind: "document", id: info.docId, path: info.path };
 }
+/** A bare `$new.n` target (3.2): the kind the symbol table recorded, checked against the slot's admitted kinds. */
+function resolveSymbolTarget(ctx, symbol, kinds, here) {
+    const kind = ctx.symbols.kindOf(symbol);
+    if (kind === undefined)
+        throw new MutationError("target_missing", `${symbol} is not created by an earlier effect`, { symbol });
+    if (!kinds.includes(kind))
+        throw effectInvalid(`${here}: \`kind\` must be one of ${kinds.join(", ")} (got "${kind}")`);
+    return { kind, id: symbol };
+}
 function symbolMissing(ctx, symbol, wanted) {
     const kind = ctx.symbols.kindOf(symbol);
     if (kind === undefined)
@@ -393,6 +546,80 @@ function blockInfo(ctx, id) {
         throw new MutationError("block_missing", `block ${id} not found`, { block: id });
     return { docId: row.doc_id, hash: row.h, block: null };
 }
+// ---- the summary (§11.9, 3.3) ---------------------------------------------------------
+//
+// Channel 3 of the teaching surfaces: the plan is a worked example of itself.
+// One line in words per resolved effect — `preview.summary`, which the Receipt
+// repeats as its `summary` and the CLI prints under the commit confirmation.
+// Deterministic and byte-identical across engines (the wording table of §11.9):
+// a document by its rooted path, a heading by its text in quotes, any other
+// block by its type and id, counts with their nouns pluralized by an `s`.
+/** `1 block` / `2 blocks` (an `s` on every noun of the table). */
+export function plural(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+/** The rooted path of a document the plan addresses — a created document's from its `create`. */
+function docPathOf(ctx, docId) {
+    if (isNewSymbol(docId)) {
+        const created = ctx.creates.find((c) => c.symbol === docId);
+        if (created)
+            return referencePath(created.path);
+    }
+    const info = findDoc(ctx.store, { docId });
+    return referencePath(info?.path ?? docId);
+}
+/** A block's type and visible text: the live row when it has one, else the planner's tree (a `$new.k`). */
+function blockDescriptor(ctx, id) {
+    if (!isNewSymbol(id)) {
+        const row = ctx.store.db.prepare("SELECT type, text FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(id);
+        if (row)
+            return { type: row.type, text: row.text };
+    }
+    const inTree = locateLoaded(ctx, id);
+    if (!inTree)
+        return null;
+    return { type: inTree.block.type, text: normalizeVisibleText(inTree.block.raw, inTree.block.type) };
+}
+/** The name of a block in a summary line: `heading "Text"` for a heading, else `<type> <id>` (`paragraph b_12`, `task b_9`). */
+function blockName(ctx, id) {
+    const d = blockDescriptor(ctx, id);
+    if (d === null)
+        return `block ${id}`;
+    return d.type === "heading" ? `heading ${ctx.canonical(d.text)}` : `${d.type} ${id}`;
+}
+/** A section by its heading's text: `section "Risks"`. */
+function sectionName(ctx, headingId) {
+    const d = blockDescriptor(ctx, headingId);
+    return `section ${ctx.canonical(d?.text ?? headingId)}`;
+}
+/**
+ * The placement half of an `insert` / `move blocks` line: `<verb> the end|start
+ * of <container> [in <path>]` — the container a document (its path; no `in`), a
+ * section (`section "Risks"`) or a block (its name) — or `before|after <block>
+ * in <path>`. `verb` is `at` for an insert, `to` for a move.
+ */
+function placeWords(ctx, into, at, verb) {
+    const path = docPathOf(ctx, targetDoc(ctx, into));
+    if (at !== "start" && at !== "end") {
+        const anchor = "before" in at ? at.before : at.after;
+        return `${"before" in at ? "before" : "after"} ${blockName(ctx, anchor)} in ${path}`;
+    }
+    const edge = `${verb} the ${at}`;
+    switch (into.kind) {
+        case "document":
+            return `${edge} of ${path}`;
+        case "section":
+            return `${edge} of ${sectionName(ctx, into.heading_id)} in ${path}`;
+        case "block":
+            return `${edge} of ${blockName(ctx, into.id)} in ${path}`;
+        case "node":
+            return `${edge} of node ${into.id} in ${path}`;
+    }
+}
+/** The document of a block list's first block (a kernel `remove`/`merge` names blocks of one document). */
+function docOfBlocks(ctx, ids) {
+    return docPathOf(ctx, blockInfo(ctx, ids[0]).docId);
+}
 /** Every descendant id of a block: the planner's tree when loaded, else the store's live rows. */
 function descendantsOf(ctx, id) {
     const inTree = locateLoaded(ctx, id);
@@ -535,30 +762,46 @@ function describe(e) {
 function targetName(t) {
     return t.kind === "section" ? `section ${t.heading_id}` : `${t.kind} ${t.id}`;
 }
-/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit. */
-export function resolveEffect(ctx, e) {
-    const target = (t) => (t.kind === "document" ? resolveDocumentTarget(ctx, t) : t);
+/** The target kinds each slot admits (§11.1); `validateTarget` checks a literal, `resolveEffect` a bare `$new.n`. */
+const PLACEMENT_KINDS = ["document", "section", "block"];
+const DOCUMENT_KIND = ["document"];
+const BLOCK_KIND = ["block"];
+const SET_KINDS = ["document", "block", "node"];
+/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit; `i` names the effect in messages. */
+export function resolveEffect(ctx, e, i = 0) {
+    const here = `effects[${i}]`;
+    const target = (t, kinds, member) => {
+        const literal = t.kind === "symbol" ? resolveSymbolTarget(ctx, t.id, kinds, `${here}.${member}`) : t;
+        return literal.kind === "document" ? resolveDocumentTarget(ctx, literal) : literal;
+    };
+    const targets = (list) => list.map((t, k) => target(t, BLOCK_KIND, `targets[${k}]`));
     switch (e.op) {
         case "create":
             return { op: "create", path: canonicalDocPath(e.path), markdown: e.markdown, ...(e.frontmatter !== undefined ? { frontmatter: e.frontmatter } : {}) };
         case "insert":
-            return { op: "insert", into: target(e.into), at: e.at ?? "end", markdown: e.markdown, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+            return { op: "insert", into: target(e.into, PLACEMENT_KINDS, "into"), at: e.at ?? "end", markdown: e.markdown, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
         case "set":
-            return { op: "set", target: target(e.target), field: e.field, value: e.value, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
-        case "unset":
-            return { op: "unset", target: target(e.target), field: e.field, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+        case "unset": {
+            const t = target(e.target, e.op === "set" ? SET_KINDS : DOCUMENT_KIND, "target");
+            // A bare `$new.n` deferred its `field` check (§11.2) to here, where its kind is known.
+            if (e.target.kind === "symbol")
+                checkField(t.kind, e.field, here, e.op);
+            if (e.op === "set")
+                return { op: "set", target: t, field: e.field, value: e.value, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+            return { op: "unset", target: t, field: e.field, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+        }
         case "move":
             if ("targets" in e)
-                return { op: "move", targets: e.targets.map(target), into: target(e.into), at: e.at ?? "end", ...(e.expect !== undefined ? { expect: e.expect } : {}) };
-            return { op: "move", target: target(e.target), to: canonicalDocPath(e.to), retarget_inbound: e.retarget_inbound !== false };
+                return { op: "move", targets: targets(e.targets), into: target(e.into, PLACEMENT_KINDS, "into"), at: e.at ?? "end", ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+            return { op: "move", target: target(e.target, DOCUMENT_KIND, "target"), to: canonicalDocPath(e.to), retarget_inbound: e.retarget_inbound !== false };
         case "remove":
             if ("targets" in e)
-                return { op: "remove", targets: e.targets.map(target), ...(e.expect !== undefined ? { expect: e.expect } : {}) };
-            return { op: "remove", target: target(e.target) };
+                return { op: "remove", targets: targets(e.targets), ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+            return { op: "remove", target: target(e.target, DOCUMENT_KIND, "target") };
         case "split":
-            return { op: "split", target: target(e.target), at: [...e.at], ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+            return { op: "split", target: target(e.target, BLOCK_KIND, "target"), at: [...e.at], ...(e.expect !== undefined ? { expect: e.expect } : {}) };
         case "merge":
-            return { op: "merge", targets: e.targets.map(target), separator: e.separator ?? " ", ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+            return { op: "merge", targets: targets(e.targets), separator: e.separator ?? " ", ...(e.expect !== undefined ? { expect: e.expect } : {}) };
         case "retarget":
             return { op: "retarget", repairs: e.repairs.map((r) => ({ from: r.from, to: r.to })), ...(e.path_glob !== undefined ? { path_glob: e.path_glob } : {}) };
     }
@@ -640,7 +883,7 @@ export function shiftPlaceholders(op, offset) {
  * resolved effect, or null when it was dropped.
  */
 export function lowerEffect(ctx, i, effect) {
-    const e = resolveEffect(ctx, effect);
+    const e = resolveEffect(ctx, effect, i);
     const info = focusOf(ctx, e);
     if (!ctx.tracker.check(i, info, describe(e)))
         return null;
@@ -755,9 +998,11 @@ function applyLowering(ctx, i, e) {
             // document, so every later effect addresses it and its blocks like any other.
             const symbol = ctx.symbols.alloc("document");
             const source = composeFile(e.markdown, e.frontmatter);
-            ctx.planner.adoptNew(symbol, parseNewDoc(symbol, e.path, source));
+            const tree = parseNewDoc(symbol, e.path, source);
+            ctx.planner.adoptNew(symbol, tree);
             ctx.creates.push({ symbol, path: e.path, source, before_op: ctx.ops.length });
             ctx.absentPaths.push(e.path);
+            ctx.summary.push(`create ${referencePath(e.path)} (${plural(tree.children.length, "block")})`);
             return;
         }
         case "insert": {
@@ -766,7 +1011,9 @@ function applyLowering(ctx, i, e) {
             recordParentPin(ctx, doc, e.into, e.expect);
             const to = placement(ctx, e.into, e.at);
             const expect = kernelExpect(e.expect);
+            const where = placeWords(ctx, e.into, e.at, "at");
             pushOp(ctx, { op: "insert", ...(e.into.kind === "document" ? { doc } : {}), to, markdown: e.markdown, ...(expect !== undefined ? { expect } : {}) });
+            ctx.summary.push(`insert ${plural(ctx.planner.results[ctx.planner.results.length - 1].ids.length, "block")} ${where}`);
             return;
         }
         case "set":
@@ -780,6 +1027,7 @@ function applyLowering(ctx, i, e) {
                     if (isNewSymbol(docId))
                         throw new MutationError("target_missing", `${docId} is a document this plan creates; its content is the create's markdown`, { symbol: docId });
                     lowerContent(ctx, docId, e.value);
+                    ctx.summary.push(`set content of ${docPathOf(ctx, docId)}`);
                     return;
                 }
                 // `frontmatter.<key>` — on a created document too (3.0): its tree is loaded, the patch is a head like any other.
@@ -791,6 +1039,7 @@ function applyLowering(ctx, i, e) {
                 else
                     delete merged[key];
                 patchFrontmatter(ctx, docId, merged, body);
+                ctx.summary.push(e.op === "set" ? `set ${e.field} = ${ctx.canonical(e.value)} in ${docPathOf(ctx, docId)}` : `unset ${e.field} in ${docPathOf(ctx, docId)}`);
                 return;
             }
             if (e.op !== "set")
@@ -800,15 +1049,18 @@ function applyLowering(ctx, i, e) {
                 const { docId } = blockInfo(ctx, id);
                 checkRevision(ctx, docId, e.expect);
                 const hash = pin(ctx, id, e.expect?.content_hash);
+                const name = blockName(ctx, id);
                 if (e.field === "markdown") {
                     if (typeof e.value !== "string")
                         throw effectInvalid("`markdown` takes a string value");
                     pushOp(ctx, { op: "update", block: kernelBlockId(ctx, id), markdown: e.value, expect: kernelExpect(e.expect, hash) });
+                    ctx.summary.push(`set markdown of ${name} in ${docPathOf(ctx, docId)}`);
                 }
                 else {
                     if (typeof e.value !== "boolean")
                         throw effectInvalid("`attrs.checked` takes a boolean value");
                     pushOp(ctx, { op: "update", block: kernelBlockId(ctx, id), attrs: { checked: e.value }, expect: kernelExpect(e.expect, hash) });
+                    ctx.summary.push(`${e.value ? "check" : "uncheck"} ${name} in ${docPathOf(ctx, docId)}`);
                 }
                 return;
             }
@@ -822,6 +1074,7 @@ function applyLowering(ctx, i, e) {
                 const hash = pin(ctx, blockId, e.expect?.content_hash ?? u.expect?.content_hash);
                 pushOp(ctx, { ...u, expect: { ...(u.expect ?? {}), content_hash: hash } });
             }
+            ctx.summary.push(`set ${e.field} = ${ctx.canonical(e.value)} on node ${node.id} in ${docPathOf(ctx, docId)}`);
             return;
         }
         case "move": {
@@ -832,9 +1085,12 @@ function applyLowering(ctx, i, e) {
                 recordParentPin(ctx, dst, e.into, e.expect);
                 const to = placement(ctx, e.into, e.at);
                 const expect = kernelExpect(e.expect);
+                const what = ids.length === 1 ? blockName(ctx, ids[0]) : plural(ids.length, "block");
+                const where = placeWords(ctx, e.into, e.at, "to");
                 // `doc` names the destination when `into` is a document (§2.3, 3.0): a
                 // top-level start/end would otherwise mean the SOURCE document's.
                 pushOp(ctx, { op: "move", blocks: ids.map((id) => kernelBlockId(ctx, id)), to, ...(e.into.kind === "document" ? { doc: dst } : {}), ...(expect !== undefined ? { expect } : {}) });
+                ctx.summary.push(`move ${what} ${where}`);
                 return;
             }
             const t = docTarget(e.target);
@@ -854,6 +1110,7 @@ function applyLowering(ctx, i, e) {
                 ctx.docBases.set(t.id, base);
             const inbound = inboundLinksTo(ctx.store, ctx.repoId, t.id, t.path);
             let retargeted = null;
+            let links = "";
             if (e.retarget_inbound && inbound.length > 0) {
                 const plan = planInboundRetarget(ctx.store, t.id, t.path, e.to, inbound);
                 for (const op of plan.ops) {
@@ -862,8 +1119,10 @@ function applyLowering(ctx, i, e) {
                     pushOp(ctx, u);
                 }
                 retargeted = { blocks: plan.blocks, docs: plan.docs };
+                links = ` (retarget ${plural(inbound.length - plan.dangling.length, "link")} in ${plural(plan.docs.length, "document")})`;
             }
             ctx.moves.push({ id: t.id, from: t.path, to: e.to, currentRev: base.currentRev, inbound, retargeted });
+            ctx.summary.push(`move ${referencePath(t.path)} → ${referencePath(e.to)}${links}`);
             return;
         }
         case "remove": {
@@ -875,7 +1134,9 @@ function applyLowering(ctx, i, e) {
                     const hash = pin(ctx, id, given?.content_hash);
                     expect[kernelBlockId(ctx, id)] = { ...(given ?? {}), content_hash: hash };
                 }
+                const line = `remove ${ids.length === 1 ? blockName(ctx, ids[0]) : plural(ids.length, "block")} from ${docOfBlocks(ctx, ids)}`;
                 pushOp(ctx, { op: "remove", blocks: ids.map((id) => kernelBlockId(ctx, id)), expect });
+                ctx.summary.push(line);
                 return;
             }
             const t = docTarget(e.target);
@@ -887,6 +1148,7 @@ function applyLowering(ctx, i, e) {
             if (!ctx.docBases.has(t.id))
                 ctx.docBases.set(t.id, base);
             ctx.tombstones.push({ id: t.id, path: t.path, currentRev: base.currentRev });
+            ctx.summary.push(`remove ${referencePath(t.path)}`);
             return;
         }
         case "split": {
@@ -894,7 +1156,9 @@ function applyLowering(ctx, i, e) {
             const { docId } = blockInfo(ctx, id);
             checkRevision(ctx, docId, e.expect);
             const hash = pin(ctx, id, e.expect?.content_hash);
+            const name = blockName(ctx, id);
             pushOp(ctx, { op: "split", block: kernelBlockId(ctx, id), at: [...e.at], expect: kernelExpect(e.expect, hash) });
+            ctx.summary.push(`split ${name} at offset${e.at.length === 1 ? "" : "s"} ${e.at.join(", ")} in ${docPathOf(ctx, docId)}`);
             return;
         }
         case "merge": {
@@ -905,7 +1169,9 @@ function applyLowering(ctx, i, e) {
                 const hash = pin(ctx, id, given?.content_hash);
                 expect[kernelBlockId(ctx, id)] = { ...(given ?? {}), content_hash: hash };
             }
+            const line = `merge ${plural(ids.length, "block")} into ${blockName(ctx, ids[0])} in ${docOfBlocks(ctx, ids)}`;
             pushOp(ctx, { op: "merge", blocks: ids.map((id) => kernelBlockId(ctx, id)), separator: e.separator, expect });
+            ctx.summary.push(line);
             return;
         }
         case "retarget": {
@@ -916,6 +1182,9 @@ function applyLowering(ctx, i, e) {
                 pin(ctx, u.block, u.expect?.content_hash);
                 pushOp(ctx, u);
             }
+            const docs = new Set(plan.hits.map((h) => h.path)).size;
+            const pair = e.repairs.length === 1 ? `${e.repairs[0].from} → ${e.repairs[0].to}` : `over ${plural(e.repairs.length, "pair")}`;
+            ctx.summary.push(`retarget ${plural(plan.hits.length, "link")} ${pair} in ${plural(docs, "document")}`);
             return;
         }
     }