@omgbase/core 0.11.1 → 0.19.0

package/dist/src/mutate/effects.js

@@ -0,0 +1,1161 @@
+import { findDoc } from "../core/read/reader.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";
+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]*)$/;
+export function isNewSymbol(s) {
+    return NEW_SYMBOL_RE.test(s);
+}
+// ---- validation (§11.1; a malformed effect is `filter_invalid` with `hint: "arguments"`) ----
+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" });
+}
+function onlyKeys(e, allowed, here) {
+    const extra = Object.keys(e).filter((k) => !allowed.includes(k));
+    if (extra.length > 0)
+        throw effectInvalid(`${here}: unknown key${extra.length > 1 ? "s" : ""} ${extra.map((k) => `\`${k}\``).join(", ")}`);
+}
+function requireString(e, key, here) {
+    const v = e[key];
+    if (typeof v !== "string")
+        throw effectInvalid(`${here}: \`${key}\` must be a string`);
+    return v;
+}
+function optionalString(e, key, here) {
+    const v = e[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string")
+        throw effectInvalid(`${here}: \`${key}\` must be a string`);
+    return v;
+}
+/** 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) {
+        case "document": {
+            onlyKeys(v, ["kind", "id", "path"], here);
+            const id = optionalString(v, "id", here);
+            const path = optionalString(v, "path", here);
+            if (id === undefined && path === undefined)
+                throw effectInvalid(`${here}: a document target needs \`id\` or \`path\``);
+            return { kind: "document", ...(id !== undefined ? { id } : {}), ...(path !== undefined ? { path } : {}) };
+        }
+        case "block":
+            onlyKeys(v, ["kind", "id"], here);
+            return { kind: "block", id: requireString(v, "id", here) };
+        case "node":
+            onlyKeys(v, ["kind", "id"], here);
+            return { kind: "node", id: requireString(v, "id", here) };
+        case "section":
+            onlyKeys(v, ["kind", "heading_id"], here);
+            return { kind: "section", heading_id: requireString(v, "heading_id", here) };
+    }
+}
+function validateTargets(v, here) {
+    if (!Array.isArray(v) || v.length === 0)
+        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) {
+    if (v === undefined)
+        return undefined;
+    if (v === "start" || v === "end")
+        return v;
+    if (isRecord(v) && Object.keys(v).length === 1) {
+        if (typeof v.before === "string")
+            return { before: v.before };
+        if (typeof v.after === "string")
+            return { after: v.after };
+    }
+    throw effectInvalid(`${here}: \`at\` must be "start", "end", { before: <block id> } or { after: <block id> }`);
+}
+function validateExpect(v, here) {
+    if (v === undefined)
+        return undefined;
+    if (!isRecord(v))
+        throw effectInvalid(`${here}: \`expect\` must be an object`);
+    onlyKeys(v, ["content_hash", "parent_children_hash", "revision"], `${here}.expect`);
+    const out = {};
+    for (const k of ["content_hash", "parent_children_hash", "revision"]) {
+        const s = optionalString(v, k, `${here}.expect`);
+        if (s !== undefined)
+            out[k] = s;
+    }
+    return out;
+}
+function validateExpectMap(v, here) {
+    if (v === undefined)
+        return undefined;
+    if (!isRecord(v))
+        throw effectInvalid(`${here}: \`expect\` must be an object keyed by block id`);
+    const out = {};
+    for (const [id, x] of Object.entries(v)) {
+        if (!isRecord(x))
+            throw effectInvalid(`${here}.expect[${JSON.stringify(id)}]: must be an object`);
+        onlyKeys(x, ["content_hash", "parent_children_hash"], `${here}.expect[${JSON.stringify(id)}]`);
+        const e = {};
+        const ch = optionalString(x, "content_hash", `${here}.expect[${JSON.stringify(id)}]`);
+        const pch = optionalString(x, "parent_children_hash", `${here}.expect[${JSON.stringify(id)}]`);
+        if (ch !== undefined)
+            e.content_hash = ch;
+        if (pch !== undefined)
+            e.parent_children_hash = pch;
+        out[id] = e;
+    }
+    return out;
+}
+/** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`). */
+export function validateEffect(v, i) {
+    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}")`);
+    switch (v.op) {
+        case "create": {
+            onlyKeys(v, ["op", "path", "markdown", "frontmatter"], here);
+            const path = requireString(v, "path", here);
+            const markdown = requireString(v, "markdown", here);
+            if (v.frontmatter !== undefined && !isRecord(v.frontmatter))
+                throw effectInvalid(`${here}: \`frontmatter\` must be an object`);
+            return { op: "create", path, markdown, ...(v.frontmatter !== undefined ? { frontmatter: v.frontmatter } : {}) };
+        }
+        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 markdown = requireString(v, "markdown", here);
+            const expect = validateExpect(v.expect, here);
+            return { op: "insert", into, ...(at !== undefined ? { at } : {}), markdown, ...(expect !== undefined ? { expect } : {}) };
+        }
+        case "set": {
+            onlyKeys(v, ["op", "target", "field", "value", "expect"], here);
+            const target = validateTarget(v.target, `${here}.target`, ["document", "block", "node"]);
+            const field = requireString(v, "field", here);
+            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);
+            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);
+            if (target.kind !== "symbol")
+                checkField(target.kind, field, here, "unset");
+            const expect = validateExpect(v.expect, here);
+            return { op: "unset", target, field, ...(expect !== undefined ? { expect } : {}) };
+        }
+        case "move": {
+            if ("targets" in v) {
+                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);
+                return { op: "move", targets, into, ...(at !== undefined ? { at } : {}), ...(expect !== undefined ? { expect } : {}) };
+            }
+            onlyKeys(v, ["op", "target", "to", "retarget_inbound"], here);
+            const target = validateTarget(v.target, `${here}.target`, ["document"]);
+            const to = requireString(v, "to", here);
+            if (v.retarget_inbound !== undefined && typeof v.retarget_inbound !== "boolean")
+                throw effectInvalid(`${here}: \`retarget_inbound\` must be a boolean`);
+            return { op: "move", target, to, ...(v.retarget_inbound !== undefined ? { retarget_inbound: v.retarget_inbound } : {}) };
+        }
+        case "remove": {
+            if ("targets" in v) {
+                onlyKeys(v, ["op", "targets", "expect"], here);
+                const targets = validateTargets(v.targets, here);
+                const expect = validateExpectMap(v.expect, here);
+                return { op: "remove", targets, ...(expect !== undefined ? { expect } : {}) };
+            }
+            onlyKeys(v, ["op", "target"], here);
+            return { op: "remove", target: validateTarget(v.target, `${here}.target`, ["document"]) };
+        }
+        case "split": {
+            onlyKeys(v, ["op", "target", "at", "expect"], here);
+            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);
+            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);
+            return { op: "merge", targets, ...(separator !== undefined ? { separator } : {}), ...(expect !== undefined ? { expect } : {}) };
+        }
+        case "retarget": {
+            onlyKeys(v, ["op", "repairs", "path_glob"], here);
+            if (!Array.isArray(v.repairs))
+                throw effectInvalid(`${here}: \`repairs\` must be an array of { from, to }`);
+            const repairs = v.repairs.map((r, j) => {
+                if (!isRecord(r))
+                    throw effectInvalid(`${here}.repairs[${j}]: must be { from, to }`);
+                onlyKeys(r, ["from", "to"], `${here}.repairs[${j}]`);
+                return { from: requireString(r, "from", `${here}.repairs[${j}]`), to: requireString(r, "to", `${here}.repairs[${j}]`) };
+            });
+            const path_glob = optionalString(v, "path_glob", here);
+            return { op: "retarget", repairs, ...(path_glob !== undefined ? { path_glob } : {}) };
+        }
+    }
+}
+/** The whole list; a non-array or an empty list is a shape error too. */
+export function validateEffects(v) {
+    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));
+}
+// §11.2: the `field` spellings per target kind.
+export const FRONTMATTER_FIELD = /^frontmatter\.(.+)$/;
+function checkField(kind, field, here, op) {
+    if (kind === "document") {
+        if (FRONTMATTER_FIELD.test(field) || (op === "set" && field === "content"))
+            return;
+        throw effectInvalid(`${here}: a document's \`field\` is \`frontmatter.<key>\`${op === "set" ? " or `content`" : ""} (got "${field}")`);
+    }
+    if (kind === "block") {
+        if (field === "markdown" || field === "attrs.checked")
+            return;
+        throw effectInvalid(`${here}: a block's \`field\` is \`markdown\` or \`attrs.checked\` (got "${field}")`);
+    }
+    // node: the adapter's editable props (`node_not_editable` names them when unknown)
+    if (field === "" || field.includes("."))
+        throw effectInvalid(`${here}: a node's \`field\` is one of its editable properties (got "${field}")`);
+}
+export function conflictingEffects(effects, focus) {
+    const what = focus.field !== undefined ? `${focus.target.kind} ${focus.target.id ?? focus.target.path} ${focus.field}` : `${focus.target.kind} ${focus.target.id ?? focus.target.path}`;
+    return new MutationError("conflicting_effects", `effects ${effects[0]} and ${effects[1]} contradict each other on ${what}`, { effects, focus, retriable: false });
+}
+/** The focus bookkeeping over an ordered effect list (§11.3). */
+export class ConflictTracker {
+    canonical;
+    scalar = new Map();
+    retiredDocs = new Map();
+    retiredBlocks = new Map();
+    retiredPaths = new Map();
+    touchedDocs = new Map();
+    diagnostics = [];
+    constructor(canonical) {
+        this.canonical = canonical;
+    }
+    /** Check effect `i`; returns `false` when it is an identical duplicate to drop. Throws `conflicting_effects`. */
+    check(i, info, describe) {
+        for (const d of info.docs) {
+            const by = this.retiredDocs.get(d);
+            if (by !== undefined)
+                throw conflictingEffects([by, i], { kind: "identity", target: { kind: "document", id: d } });
+        }
+        for (const b of info.blocks) {
+            const by = this.retiredBlocks.get(b);
+            if (by !== undefined)
+                throw conflictingEffects([by, i], { kind: "identity", target: { kind: "block", id: b } });
+        }
+        for (const p of info.paths) {
+            const by = this.retiredPaths.get(p);
+            if (by !== undefined)
+                throw conflictingEffects([by, i], { kind: "identity", target: { kind: "path", path: p } });
+        }
+        if (info.wholeDoc !== undefined) {
+            const by = this.touchedDocs.get(info.wholeDoc);
+            if (by !== undefined)
+                throw conflictingEffects([by, i], { kind: "identity", target: { kind: "document", id: info.wholeDoc } });
+        }
+        if (info.scalar) {
+            const prev = this.scalar.get(info.scalar.key);
+            if (prev) {
+                const identical = prev.op === info.scalar.op && (info.scalar.op === "unset" || this.canonical(prev.value) === this.canonical(info.scalar.value));
+                if (!identical)
+                    throw conflictingEffects([prev.index, i], { kind: "scalar", target: info.scalar.target, field: info.scalar.field });
+                this.diagnostics.push(`effect ${i} (${describe}) duplicates effect ${prev.index}; dropped`);
+                return false;
+            }
+        }
+        for (const s of info.scalars ?? []) {
+            const prev = this.scalar.get(s.key);
+            if (prev)
+                throw conflictingEffects([prev.index, i], { kind: "scalar", target: s.target, field: s.field });
+        }
+        // Record.
+        if (info.scalar)
+            this.scalar.set(info.scalar.key, { index: i, op: info.scalar.op, value: info.scalar.value, target: info.scalar.target, field: info.scalar.field });
+        for (const s of info.scalars ?? [])
+            this.scalar.set(s.key, { index: i, op: "set", value: undefined, target: s.target, field: s.field });
+        for (const d of info.docs)
+            if (!this.touchedDocs.has(d))
+                this.touchedDocs.set(d, i);
+        for (const d of info.retiresDocs ?? [])
+            this.retiredDocs.set(d, i);
+        for (const b of info.retiresBlocks ?? [])
+            this.retiredBlocks.set(b, i);
+        for (const p of info.retiresPaths ?? [])
+            this.retiredPaths.set(p, i);
+        return true;
+    }
+}
+// ---- the lowering context ---------------------------------------------------------
+/** `$new.n` symbols in allocation order (§11.4 `new_ids`). */
+export class SymbolTable {
+    entries = [];
+    alloc(kind) {
+        const symbol = `$new.${this.entries.length}`;
+        this.entries.push({ symbol, kind });
+        return symbol;
+    }
+    kindOf(symbol) {
+        return this.entries.find((e) => e.symbol === symbol)?.kind;
+    }
+}
+// ---- resolution --------------------------------------------------------------------
+function docMissing(ref) {
+    return new MutationError("doc_missing", `doc ${ref} not found`, { doc: ref });
+}
+/** Resolve a document target: an existing document's `{ id, path }`, or a `$new.n` document this plan creates. */
+export function resolveDocumentTarget(ctx, t) {
+    if (t.id !== undefined && isNewSymbol(t.id)) {
+        const created = ctx.creates.find((c) => c.symbol === t.id);
+        if (!created)
+            throw symbolMissing(ctx, t.id, "document");
+        if (t.path !== undefined && canonicalDocPath(t.path) !== created.path)
+            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 };
+    }
+    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(store, { repoId, path: t.path }) : null;
+    if (t.path !== undefined && !byPath)
+        throw docMissing(t.path);
+    if (byId && byPath && byId.docId !== byPath.docId)
+        throw effectInvalid(`id ${JSON.stringify(t.id)} and path ${JSON.stringify(t.path)} name different documents`);
+    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)
+        return new MutationError("target_missing", `${symbol} is not created by an earlier effect`, { symbol });
+    return new MutationError("target_missing", `${symbol} names a ${kind}, not a ${wanted}`, { symbol });
+}
+/** A block id as the kernel must see it: a `$new.n` an op minted becomes the placeholder of that op;
+ *  a `$new.n` of a created document's tree (3.0) stays the symbol — it IS the tree's id at plan
+ *  time, and `execute` aliases it to the id its replay mints (§11.7). */
+function kernelBlockId(ctx, id) {
+    if (!isNewSymbol(id))
+        return id;
+    const placeholder = ctx.blockSymbols.get(id);
+    if (placeholder !== undefined)
+        return placeholder;
+    if (locateLoaded(ctx, id))
+        return id;
+    throw symbolMissing(ctx, id, "block");
+}
+function kernelAt(ctx, at) {
+    if (at === "start" || at === "end")
+        return at;
+    if ("before" in at)
+        return { before: kernelBlockId(ctx, at.before) };
+    return { after: kernelBlockId(ctx, at.after) };
+}
+/** A block in the planner's trees (a `$new.n` is only there) — never loads a document. */
+function locateLoaded(ctx, id) {
+    const f = ctx.planner.locateLoaded(id);
+    return f ? { docId: f.docId, block: f.block } : null;
+}
+/** The live row of a block: its document and raw hash; `$new.n` from the tree. */
+function blockInfo(ctx, id) {
+    const inTree = locateLoaded(ctx, id);
+    if (inTree)
+        return { docId: inTree.docId, hash: rawHashHex(inTree.block.raw), block: inTree.block };
+    if (isNewSymbol(id))
+        throw symbolMissing(ctx, id, "block");
+    const row = ctx.store.db
+        .prepare("SELECT doc_id, lower(hex(raw_hash)) h FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
+        .get(id);
+    if (!row)
+        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);
+    if (inTree) {
+        const out = [];
+        const walk = (b) => {
+            for (const c of b.children) {
+                out.push(c.id);
+                walk(c);
+            }
+        };
+        walk(inTree.block);
+        return out;
+    }
+    if (isNewSymbol(id))
+        return [];
+    const rows = ctx.store.db
+        .prepare(`WITH RECURSIVE sub(block_id) AS (
+         SELECT block_id FROM blocks WHERE parent_block = ? AND deleted_commit IS NULL
+         UNION ALL
+         SELECT b.block_id FROM blocks b JOIN sub ON b.parent_block = sub.block_id WHERE b.deleted_commit IS NULL
+       ) SELECT block_id FROM sub`)
+        .all(id);
+    return rows.map((r) => r.block_id);
+}
+/** The document a placement target lives in (loading nothing; `parent_missing` for an unknown heading/block). */
+function targetDoc(ctx, t) {
+    switch (t.kind) {
+        case "document":
+            return t.id;
+        case "section": {
+            const inTree = locateLoaded(ctx, t.heading_id);
+            if (inTree)
+                return inTree.docId;
+            const row = ctx.store.db.prepare("SELECT doc_id FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(t.heading_id);
+            if (!row)
+                throw new MutationError("parent_missing", `parent ${t.heading_id} not found`);
+            return row.doc_id;
+        }
+        case "block": {
+            const inTree = locateLoaded(ctx, t.id);
+            if (inTree)
+                return inTree.docId;
+            if (isNewSymbol(t.id))
+                throw symbolMissing(ctx, t.id, "block");
+            const row = ctx.store.db.prepare("SELECT doc_id FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(t.id);
+            if (!row)
+                throw new MutationError("parent_missing", `parent ${t.id} not found`);
+            return row.doc_id;
+        }
+        case "node":
+            return nodeBlock(ctx, t.id).docId;
+    }
+}
+function nodeBlock(ctx, nodeId) {
+    const row = ctx.store.db.prepare("SELECT doc_id, block_id FROM nodes WHERE node_id = ?").get(nodeId);
+    if (!row)
+        throw new MutationError("block_missing", `node ${nodeId} not found`, {});
+    if (!row.block_id)
+        throw new MutationError("node_not_editable", `node ${nodeId} is not anchored to a block`, {});
+    return { docId: row.doc_id, blockId: row.block_id };
+}
+function placement(ctx, into, at) {
+    const kernel = kernelAt(ctx, at);
+    switch (into.kind) {
+        case "document":
+            return { parent: { doc: true }, at: kernel };
+        case "section":
+            return { parent: { heading: kernelBlockId(ctx, into.heading_id), scope: "section" }, at: kernel };
+        case "block":
+            return { parent: kernelBlockId(ctx, into.id), at: kernel };
+        case "node":
+            throw effectInvalid("a node is not a placement target");
+    }
+}
+/** `expect.revision` against the document's current revision (§11.2): a mismatch is `stale_plan`. */
+function checkRevision(ctx, docId, expect) {
+    if (expect?.revision === undefined)
+        return;
+    if (isNewSymbol(docId))
+        throw effectInvalid(`expect.revision cannot name a document this plan creates (${docId})`);
+    const base = readDocBase(ctx.store.db, docId);
+    if (!base)
+        throw docMissing(docId);
+    if (base.currentRev !== expect.revision) {
+        throw new MutationError("stale_plan", `document ${docId} is at revision ${base.currentRev ?? "null"}, not ${expect.revision}; re-plan`, {
+            doc: docId,
+            expected_revision: expect.revision,
+            current: { revision: base.currentRev, hash: base.fileHash },
+            retriable: true,
+        });
+    }
+}
+/** Pin a block's content hash: the caller's `expect.content_hash` when given, else the live row's (the sugar tools' rule). */
+function pin(ctx, id, given) {
+    const hash = given ?? blockInfo(ctx, id).hash;
+    if (!isNewSymbol(id) && !ctx.pins.has(id))
+        ctx.pins.set(id, hash);
+    return hash;
+}
+function pushOp(ctx, op) {
+    ctx.ops.push(op);
+    const before = ctx.planner.results.length;
+    ctx.planner.push(op);
+    // Any `$new.n` this op minted is referenceable through the op's placeholder.
+    const result = ctx.planner.results[before];
+    result.ids.forEach((id, j) => {
+        if (isNewSymbol(id) && !ctx.blockSymbols.has(id))
+            ctx.blockSymbols.set(id, `$${before}.ids[${j}]`);
+    });
+}
+function kernelExpect(e, contentHash) {
+    const out = {};
+    if (contentHash !== undefined)
+        out.content_hash = contentHash;
+    if (e?.parent_children_hash !== undefined)
+        out.parent_children_hash = e.parent_children_hash;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function recordParentPin(ctx, doc, into, expect) {
+    if (expect?.parent_children_hash === undefined)
+        return;
+    const parent = into.kind === "block" ? into.id : null;
+    ctx.parents.push({ doc, parent, parent_children_hash: expect.parent_children_hash });
+}
+// ---- lowering (§11.3, the table) -----------------------------------------------------
+function describe(e) {
+    switch (e.op) {
+        case "create": return `create ${e.path}`;
+        case "insert": return `insert into ${targetName(e.into)}`;
+        case "set": return `set ${e.field} on ${targetName(e.target)}`;
+        case "unset": return `unset ${e.field} on ${targetName(e.target)}`;
+        case "move": return "targets" in e ? `move ${e.targets.map(targetName).join(",")}` : `move ${targetName(e.target)} -> ${e.to}`;
+        case "remove": return "targets" in e ? `remove ${e.targets.map(targetName).join(",")}` : `remove ${targetName(e.target)}`;
+        case "split": return `split ${targetName(e.target)}`;
+        case "merge": return `merge ${e.targets.map(targetName).join(",")}`;
+        case "retarget": return `retarget ${e.repairs.map((r) => `${r.from}->${r.to}`).join(",")}`;
+    }
+}
+function targetName(t) {
+    return t.kind === "section" ? `section ${t.heading_id}` : `${t.kind} ${t.id}`;
+}
+/** 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, PLACEMENT_KINDS, "into"), at: e.at ?? "end", markdown: e.markdown, ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+        case "set":
+        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: 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: 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, BLOCK_KIND, "target"), at: [...e.at], ...(e.expect !== undefined ? { expect: e.expect } : {}) };
+        case "merge":
+            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 } : {}) };
+    }
+}
+function docTarget(t) {
+    if (t.kind !== "document")
+        throw effectInvalid(`expected a document target, got ${t.kind}`);
+    return t;
+}
+function blockTarget(t) {
+    if (t.kind !== "block")
+        throw effectInvalid(`expected a block target, got ${t.kind}`);
+    return t;
+}
+function nodeTarget(t) {
+    if (t.kind !== "node")
+        throw effectInvalid(`expected a node target, got ${t.kind}`);
+    return t;
+}
+/** The current frontmatter patch base of a loaded document: `(frontmatter, body)` of its render. */
+function frontmatterOf(ctx, docId) {
+    const d = ctx.planner.ensureDoc(docId);
+    const { frontmatter, body } = splitFrontmatter(renderDoc(d));
+    return { d, frontmatter, body };
+}
+/**
+ * Patch a loaded document's frontmatter: compose the whole file as
+ * `docs_set_meta` does (`composeFile(body, merged)`, §6), then set the file
+ * head so the known-id ingest renders exactly those bytes — the body blocks
+ * keep their ids and bytes (a file without a trailing newline gains one on its
+ * last block's trivia, as `composeFile` would add it).
+ */
+function patchFrontmatter(ctx, docId, merged, body) {
+    const d = ctx.planner.ensureDoc(docId);
+    const after = composeFile(body, merged);
+    let blocks = d.children.map((b) => renderBlockExact(d, b)).join("");
+    if (!after.endsWith(blocks)) {
+        const last = d.children[d.children.length - 1];
+        if (last && after.endsWith(blocks + "\n")) {
+            last.trivia += "\n";
+            blocks += "\n";
+        }
+        else {
+            throw new MutationError("plan_not_convergent", `the frontmatter patch of ${docId} does not preserve the body bytes`, { doc: docId });
+        }
+    }
+    const head = after.slice(0, after.length - blocks.length);
+    ctx.planner.setHead(docId, head);
+    ctx.heads.set(docId, head);
+}
+// A top-level block as `renderDoc` emits it (its subtree may be dirty from an earlier op).
+function renderBlockExact(d, b) {
+    const solo = { ...d, leadingTrivia: "", frontmatterRaw: null, children: [b] };
+    return renderDoc(solo);
+}
+/** Shift a kernel op's `$n.ids[i]` placeholders by `offset` (an opset planned alone, spliced into a longer op list). */
+export function shiftPlaceholders(op, offset) {
+    const s = (v) => {
+        const m = /^\$(\d+)\.ids\[(\d+)\]$/.exec(v);
+        return m ? `$${Number(m[1]) + offset}.ids[${m[2]}]` : v;
+    };
+    const to = (t) => ({
+        parent: typeof t.parent === "string" ? s(t.parent) : t.parent,
+        at: typeof t.at === "string" ? t.at : "before" in t.at ? { before: s(t.at.before) } : { after: s(t.at.after) },
+    });
+    switch (op.op) {
+        case "insert": return { ...op, to: to(op.to) };
+        case "update": return { ...op, block: s(op.block) };
+        case "move": return { ...op, blocks: op.blocks.map(s), to: to(op.to) };
+        case "remove": return { ...op, blocks: op.blocks.map(s) };
+        case "split": return { ...op, block: s(op.block) };
+        case "merge": return { ...op, blocks: op.blocks.map(s) };
+    }
+}
+/**
+ * Lower effect `i` (already validated): resolve its targets, classify its
+ * focus (throwing `conflicting_effects`, or dropping an identical duplicate
+ * with a diagnostic), then push its kernel ops / document drafts. Returns the
+ * resolved effect, or null when it was dropped.
+ */
+export function lowerEffect(ctx, i, effect) {
+    const e = resolveEffect(ctx, effect, i);
+    const info = focusOf(ctx, e);
+    if (!ctx.tracker.check(i, info, describe(e)))
+        return null;
+    ctx.resolved.push(e);
+    applyLowering(ctx, i, e);
+    return e;
+}
+// The addressed/retired sets and the scalar key of an effect (§11.3 table).
+function focusOf(ctx, e) {
+    const blocksOf = (ids) => {
+        const docs = new Set();
+        for (const id of ids)
+            docs.add(blockInfo(ctx, id).docId);
+        return { docs: [...docs], blocks: ids };
+    };
+    switch (e.op) {
+        case "create":
+            return { docs: [], blocks: [], paths: [e.path] };
+        case "insert": {
+            const doc = targetDoc(ctx, e.into);
+            const blocks = [...(e.into.kind === "block" ? [e.into.id] : e.into.kind === "section" ? [e.into.heading_id] : []), ...anchorIds(e.at)];
+            return { docs: [doc], blocks, paths: [] };
+        }
+        case "set":
+        case "unset": {
+            if (e.target.kind === "document") {
+                const field = e.field === "content" ? "content" : e.field;
+                return {
+                    scalar: { key: `document:${e.target.id}:${field}`, target: { kind: "document", id: e.target.id }, field, op: e.op, value: e.op === "set" ? e.value : undefined },
+                    docs: [e.target.id], blocks: [], paths: [],
+                    ...(field === "content" ? { wholeDoc: e.target.id, retiresDocs: [e.target.id], retiresBlocks: allBlocksOf(ctx, e.target.id) } : {}),
+                };
+            }
+            if (e.target.kind === "block") {
+                const { docId } = blockInfo(ctx, e.target.id);
+                return {
+                    scalar: { key: `block:${e.target.id}:${e.field}`, target: { kind: "block", id: e.target.id }, field: e.field, op: e.op, value: e.op === "set" ? e.value : undefined },
+                    docs: [docId], blocks: [e.target.id], paths: [],
+                    ...(e.field === "markdown" ? { retiresBlocks: descendantsOf(ctx, e.target.id) } : {}),
+                };
+            }
+            const node = nodeTarget(e.target);
+            const { docId, blockId } = nodeBlock(ctx, node.id);
+            return {
+                scalar: { key: `node:${node.id}:${e.field}`, target: { kind: "node", id: node.id }, field: e.field, op: e.op, value: e.op === "set" ? e.value : undefined },
+                docs: [docId], blocks: [blockId], paths: [],
+            };
+        }
+        case "move": {
+            if ("targets" in e) {
+                const ids = e.targets.map((t) => blockTarget(t).id);
+                const { docs } = blocksOf(ids);
+                const dst = targetDoc(ctx, e.into);
+                const blocks = [...ids, ...(e.into.kind === "block" ? [e.into.id] : e.into.kind === "section" ? [e.into.heading_id] : []), ...anchorIds(e.at)];
+                return { docs: [...new Set([...docs, dst])], blocks, paths: [] };
+            }
+            const t = docTarget(e.target);
+            return {
+                scalar: { key: `document:${t.id}:path`, target: { kind: "document", id: t.id }, field: "path", op: "set", value: e.to },
+                docs: [t.id], blocks: [], paths: [e.to], retiresPaths: [t.path],
+            };
+        }
+        case "remove": {
+            if ("targets" in e) {
+                const ids = e.targets.map((t) => blockTarget(t).id);
+                const { docs } = blocksOf(ids);
+                return { docs, blocks: ids, paths: [], retiresBlocks: ids.flatMap((id) => [id, ...descendantsOf(ctx, id)]) };
+            }
+            const t = docTarget(e.target);
+            return { docs: [t.id], blocks: [], paths: [], retiresDocs: [t.id], retiresBlocks: allBlocksOf(ctx, t.id) };
+        }
+        case "split": {
+            const id = blockTarget(e.target).id;
+            return { ...blocksOf([id]), paths: [] };
+        }
+        case "merge": {
+            const ids = e.targets.map((t) => blockTarget(t).id);
+            return { ...blocksOf(ids), paths: [], retiresBlocks: ids.slice(1).flatMap((id) => [id, ...descendantsOf(ctx, id)]) };
+        }
+        case "retarget": {
+            const plan = linksRepair(ctx.store, ctx.repoId, e.repairs, e.path_glob !== undefined ? { pathGlob: e.path_glob } : {});
+            const ids = plan.ops.map((o) => o.block);
+            return {
+                scalars: ids.map((id) => ({ key: `block:${id}:markdown`, target: { kind: "block", id }, field: "markdown" })),
+                ...blocksOf(ids), paths: [],
+            };
+        }
+    }
+}
+function anchorIds(at) {
+    if (at === "start" || at === "end")
+        return [];
+    return ["before" in at ? at.before : at.after];
+}
+function allBlocksOf(ctx, docId) {
+    if (isNewSymbol(docId))
+        return [];
+    return ctx.store.db.prepare("SELECT block_id FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL").all(docId).map((r) => r.block_id);
+}
+// The lowering table (§11.3), one resolved effect → kernel ops / document entries. `i` is the effect's index.
+function applyLowering(ctx, i, e) {
+    switch (e.op) {
+        case "create": {
+            if (findDoc(ctx.store, { repoId: ctx.repoId, path: e.path }))
+                throw new MutationError("path_taken", `document already exists at ${e.path}`, { path: e.path });
+            if (ctx.absentPaths.includes(e.path))
+                throw new MutationError("path_taken", `an earlier effect already creates or moves a document to ${e.path}`, { path: e.path });
+            if (ctx.docStore.exists(e.path))
+                throw new MutationError("path_taken", `file already exists on disk at ${e.path}`, { path: e.path });
+            // 3.0: the document symbol, then its tree parsed under the symbolic minter
+            // — its blocks are the next `$new.k` in pre-order — and adopted as a loaded
+            // 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);
+            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": {
+            const doc = targetDoc(ctx, e.into);
+            checkRevision(ctx, doc, e.expect);
+            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":
+        case "unset": {
+            if (e.target.kind === "document") {
+                const docId = e.target.id;
+                checkRevision(ctx, docId, e.expect);
+                if (e.field === "content") {
+                    if (e.op !== "set" || typeof e.value !== "string")
+                        throw effectInvalid("`content` takes a string value: the complete proposed document");
+                    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.
+                const key = FRONTMATTER_FIELD.exec(e.field)[1];
+                const { frontmatter, body } = frontmatterOf(ctx, docId);
+                const merged = { ...frontmatter };
+                if (e.op === "set")
+                    merged[key] = e.value;
+                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")
+                throw effectInvalid("`unset` takes a document target");
+            if (e.target.kind === "block") {
+                const id = e.target.id;
+                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;
+            }
+            // node: the adapter's editor → one update (macros.ts nodeSet)
+            const node = nodeTarget(e.target);
+            const { docId, blockId } = nodeBlock(ctx, node.id);
+            checkRevision(ctx, docId, e.expect);
+            const ops = nodeSet(ctx.store, node.id, e.field, typeof e.value === "string" ? e.value : ctx.canonical(e.value));
+            for (const op of ops) {
+                const u = op;
+                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": {
+            if ("targets" in e) {
+                const ids = e.targets.map((t) => blockTarget(t).id);
+                const dst = targetDoc(ctx, e.into);
+                checkRevision(ctx, dst, e.expect);
+                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);
+            if (isNewSymbol(t.id))
+                throw new MutationError("target_missing", `${t.id} is a document this plan creates; it cannot be moved in the same plan`, { symbol: t.id });
+            const base = readDocBase(ctx.store.db, t.id);
+            if (!base)
+                throw docMissing(t.id);
+            if (findDoc(ctx.store, { repoId: ctx.repoId, path: e.to }))
+                throw new MutationError("path_taken", `a document already exists at ${e.to}`, { path: e.to });
+            if (ctx.absentPaths.includes(e.to))
+                throw new MutationError("path_taken", `an earlier effect already creates or moves a document to ${e.to}`, { path: e.to });
+            if (ctx.docStore.exists(e.to))
+                throw new MutationError("path_taken", `file already exists on disk at ${e.to}`, { path: e.to });
+            ctx.absentPaths.push(e.to);
+            if (!ctx.docBases.has(t.id))
+                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) {
+                    const u = op;
+                    pin(ctx, u.block, u.expect?.content_hash);
+                    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": {
+            if ("targets" in e) {
+                const ids = e.targets.map((t) => blockTarget(t).id);
+                const expect = {};
+                for (const id of ids) {
+                    const given = e.expect?.[id];
+                    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);
+            if (isNewSymbol(t.id))
+                throw new MutationError("target_missing", `${t.id} is a document this plan creates; it cannot be removed in the same plan`, { symbol: t.id });
+            const base = readDocBase(ctx.store.db, t.id);
+            if (!base)
+                throw docMissing(t.id);
+            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": {
+            const id = blockTarget(e.target).id;
+            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": {
+            const ids = e.targets.map((t) => blockTarget(t).id);
+            const expect = {};
+            for (const id of ids) {
+                const given = e.expect?.[id];
+                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": {
+            const plan = linksRepair(ctx.store, ctx.repoId, e.repairs, e.path_glob !== undefined ? { pathGlob: e.path_glob } : {});
+            ctx.retargets.push({ effect_index: i, hits: plan.hits, pairs: plan.pairs });
+            for (const op of plan.ops) {
+                const u = op;
+                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;
+        }
+    }
+}
+/**
+ * The symbolic minter (§11.4): `b` and `d` mints yield `$new.0, $new.1, …`
+ * from `symbols`, so a plan consumes no real id and the kernel (id-agnostic
+ * for rendering, ADR-002) renders exact bytes. Planning mints nothing else —
+ * `c`/`r`/`x`/`e` are minted inside the commit transaction.
+ */
+export function symbolicMinter(symbols) {
+    return (prefix) => {
+        if (prefix === "b")
+            return symbols.alloc("block");
+        if (prefix === "d")
+            return symbols.alloc("document");
+        throw new Error(`the effect planner mints only b/d ids, not ${prefix}`);
+    };
+}
+/** `set document.content`: the whole-document planner's opset, spliced in (placeholders shifted), its frontmatter as a file head. */
+function lowerContent(ctx, docId, content) {
+    // The whole-document planner verifies its candidates by dry-run applies,
+    // which mint: give them a throwaway symbol table so the plan's own `$new.n`
+    // sequence stays the one `execute`'s replay reproduces (the opset's ops carry
+    // no minted ids — an insert carries markdown — so nothing leaks).
+    const opset = withIdMinter(symbolicMinter(new SymbolTable()), () => planUpdate(ctx.store, ctx.repoId, "", docId, content));
+    if (!opset.converges) {
+        const why = opset.diagnostics.length > 0 ? ` — ${opset.diagnostics[opset.diagnostics.length - 1]}` : "";
+        throw new MutationError("plan_not_convergent", `the proposed content of ${docId} cannot be reproduced by the planner; re-plan${why}`, { doc: docId, diagnostics: opset.diagnostics });
+    }
+    // The identity consequences, surfaced as `preview.identity[doc]` (3.0; the
+    // 3.x `docs_update` result): each planned op by its index in the plan's ops.
+    const offset = ctx.ops.length;
+    ctx.identity.set(docId, {
+        matcher_v: opset.matcherV,
+        summary: opset.summary,
+        ops: opset.ops.map((p, k) => ({ op_index: offset + k, disposition: p.disposition, blocks: p.blocks, confidence: p.confidence, reason: p.reason, ...(p.detail !== undefined ? { detail: p.detail } : {}) })),
+        diagnostics: opset.diagnostics,
+    });
+    if (opset.ops.length === 0 && !opset.frontmatter) {
+        // The content IS the document (the zero-effects rule, §11.7): nothing is
+        // loaded, so nothing is ingested and `execute` records no commit — the
+        // document's triple is still a precondition (the opset's), so the plan is
+        // `stale_plan` once the document moves on.
+        const base = readDocBase(ctx.store.db, docId);
+        if (!base)
+            throw docMissing(docId);
+        if (!ctx.docBases.has(docId))
+            ctx.docBases.set(docId, base);
+        return;
+    }
+    const d = ctx.planner.ensureDoc(docId);
+    if (opset.frontmatter) {
+        // The whole-document planner's frontmatter keeps the leading trivia in
+        // front (its legacy `set_frontmatter`); as a file head that is `leading + raw`.
+        const head = d.leadingTrivia + (opset.frontmatter.raw ?? "");
+        ctx.planner.setHead(docId, head);
+        ctx.heads.set(docId, head);
+    }
+    for (const p of opset.ops)
+        pushOp(ctx, shiftPlaceholders(p.op, offset));
+}
+//# sourceMappingURL=effects.js.map