@omgbase/core 0.15.0 → 0.19.0

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

@@ -8,7 +8,9 @@ import { type LinkRepairCount, type RetargetHit } from "./macros.js";
 import type { At, Expect } from "./ops.js";
 import type { IdentityPreview } from "./opset.js";
 import { MutationError } from "./tree.js";
-/** What an effect addresses. `section` is a derived range (ADR-005), never a stored id. */
+/** What an effect addresses. `section` is a derived range (ADR-005), never a stored id.
+ *  `symbol` (3.2, §11.8 "Sugar"): a bare `"$new.n"` target whose kind — document or block — the
+ *  symbol table decides when the effect is resolved; it never reaches a resolved effect. */
 export type EffectTarget = {
     kind: "document";
     id?: string;
@@ -22,6 +24,9 @@ export type EffectTarget = {
 } | {
     kind: "section";
     heading_id: string;
+} | {
+    kind: "symbol";
+    id: string;
 };
 export type EffectAt = At;
 /** Guards: the kernel's two CAS fields plus the document's `current_rev` at plan time. */
@@ -169,6 +174,23 @@ export type ResolvedEffect = {
 };
 /** The argument-shape error of the surface, thrown from the planner: `filter_invalid { reason, hint: "arguments" }`. */
 export declare function effectInvalid(message: string): MutationError;
+/** The `-> ` leader (3.2, §11.8 "Sugar"): a string beginning exactly so is an OQX expression, the rest of the string. */
+export declare const EXPRESSION_LEADER = "-> ";
+/** A path-looking string: contains `/` or ends `.md` (the bare document target of §11.8 "Sugar"). */
+export declare function looksLikePath(s: string): boolean;
+/** A bare id of the three target kinds (§11.8 "Sugar"). */
+export declare function isTargetId(s: string): boolean;
+/**
+ * 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 declare function bareTarget(ref: string, here: string): EffectTarget;
+export declare function validateTarget(v: unknown, here: string, kinds: readonly EffectTarget["kind"][]): EffectTarget;
 /** The shape check of one effect (§11.1). `i` names it in the message (`effects[i]`). */
 export declare function validateEffect(v: unknown, i: number): Effect;
 /** The whole list; a non-array or an empty list is a shape error too. */
@@ -304,6 +326,8 @@ export interface LoweringContext {
     canonical: (v: unknown) => string;
     /** the resolved effects kept (dropped duplicates excluded) */
     resolved: ResolvedEffect[];
+    /** `preview.summary` (3.3, §11.9): one line in words per resolved effect, in order */
+    summary: string[];
 }
 /** Resolve a document target: an existing document's `{ id, path }`, or a `$new.n` document this plan creates. */
 export declare function resolveDocumentTarget(ctx: LoweringContext, t: Extract<EffectTarget, {
@@ -311,8 +335,16 @@ export declare function resolveDocumentTarget(ctx: LoweringContext, t: Extract<E
 }>): Extract<ResolvedTarget, {
     kind: "document";
 }>;
-/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit. */
-export declare function resolveEffect(ctx: LoweringContext, e: Effect): ResolvedEffect;
+/** An existing document's `{ id, path }` for a literal document target (`doc_missing`; `filter_invalid` when `id` and `path` disagree). */
+export declare function findDocumentTarget(store: Store, repoId: string, t: Extract<EffectTarget, {
+    kind: "document";
+}>): Extract<ResolvedTarget, {
+    kind: "document";
+}>;
+/** `1 block` / `2 blocks` (an `s` on every noun of the table). */
+export declare function plural(n: number, noun: string): string;
+/** Resolve one validated effect's targets (§11.4): documents to `{ id, path }`, defaults made explicit; `i` names the effect in messages. */
+export declare function resolveEffect(ctx: LoweringContext, e: Effect, i?: number): ResolvedEffect;
 /** Shift a kernel op's `$n.ids[i]` placeholders by `offset` (an opset planned alone, spliced into a longer op list). */
 export declare function shiftPlaceholders(op: Op, offset: number): Op;
 /**

package/dist/src/mutate/effects.js

@@ -1,5 +1,7 @@
 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";
@@ -39,9 +41,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) {
@@ -147,7 +196,8 @@ 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");
+            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 } : {}) };
         }
@@ -155,7 +205,8 @@ export function validateEffect(v, i) {
             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");
+            if (target.kind !== "symbol")
+                checkField(target.kind, field, here, "unset");
             const expect = validateExpect(v.expect, here);
             return { op: "unset", target, field, ...(expect !== undefined ? { expect } : {}) };
         }
@@ -337,10 +388,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 +403,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 +457,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 +673,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 +794,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 +909,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 +922,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 +938,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 +950,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 +960,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 +985,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 +996,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 +1021,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 +1030,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 +1045,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 +1059,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 +1067,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 +1080,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 +1093,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;
         }
     }

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

@@ -3,9 +3,10 @@ import { type ApplyRevision, type Op, type OpResult } from "./apply.js";
 import { type DocStore } from "./doc-store.js";
 import { type CreateEntry, type ResolvedEffect, type RetargetPreview } from "./effects.js";
 import type { IdentityPreview } from "./opset.js";
+import { type Selection } from "./select.js";
 export declare const PLAN_VERSION: 1;
 /** The lowering + conflict rules version (§11.4; the `matcher_v` precedent). */
-export declare const PLANNER_V: "p2";
+export declare const PLANNER_V: "p3";
 /** A kernel op as the plan spells it on the wire: the fixture spelling (`child_ids`). */
 export type WireOp = Exclude<Op, {
     op: "update";
@@ -77,6 +78,8 @@ export interface PlanPreview {
     identity?: Record<string, IdentityPreview>;
     /** (3.0) per `retarget` effect: its hits and pair counts; present when a plan has one */
     retarget?: RetargetPreview[];
+    /** (3.3, §11.9) one line in words per resolved effect, in order — the plan as a worked example; `[]` for a zero-hit selection */
+    summary: string[];
 }
 /** The executable core the digest covers. */
 export interface PlanCore {
@@ -89,10 +92,15 @@ export interface PlanCore {
         symbol: string;
         kind: "block" | "document";
     }[];
+    /** (3.1, §11.8) the selector, its templates and the hits it bound — present only for a selector plan */
+    selection?: Selection;
 }
 export interface Plan extends PlanCore {
     plan_id: string;
     diagnostics: string[];
+    /** (3.2, §11.8 "Sugar") a plain request's effects AS WRITTEN when one carried a `-> ` / `{ oqx }` expression;
+     *  not digested (the core already holds the concrete effects), recorded in the intent record as `templates` */
+    templates?: unknown[];
     /** excluded from the digest; omittable on echo */
     preview?: PlanPreview;
 }
@@ -104,19 +112,11 @@ export interface Receipt {
     /** `$new.n` → the minted id */
     new_ids: Record<string, string>;
     committed: true;
+    /** (3.3, §11.9) the plan's `preview.summary` — what was committed, in words (`[]` when the plan was handed back without its preview) */
+    summary: string[];
 }
-/**
- * Canonical JSON (§11.5): no whitespace; object keys sorted by their UTF-8
- * bytes; members whose value is `undefined` omitted (an optional key absent is
- * absent, never `null`; a JSON `null` value stays `null`); strings escaped only
- * as JSON requires — `"`, `\`, and U+0000–U+001F (`\b \f \n \r \t`, else
- * `\u00xx` lower-case) — everything else literal UTF-8; a number that is
- * integral with |n| < 2^53 printed as a plain integer (`-0` as `0`), any other
- * finite number by ECMAScript `Number::toString` (shortest round-trip digits);
- * `true`/`false`/`null`.
- */
-export declare function canonicalJson(v: unknown): string;
-/** The executable core of a plan — the six digested keys, nothing else. */
+export { canonicalJson } from "./canonical.js";
+/** The executable core of a plan — the six digested keys (seven with `selection`), nothing else. */
 export declare function planCore(p: PlanCore): PlanCore;
 /** `plan_id = hex(sha256(canonical(core)))` (§11.5). */
 export declare function planDigest(core: PlanCore): string;
@@ -126,8 +126,12 @@ export interface PlanEffectsRequest {
     rootPath?: string;
     docStore?: DocStore;
     omgbaseDir?: string;
-    /** The effects as given (validated here: a shape error is `filter_invalid`). */
+    /** The effects as given (validated here: a shape error is `filter_invalid`); with `select`, the templates (§11.8). */
     effects: unknown;
+    /** (3.1) an OQX selector: its hits × `effects` (templates) are the effects planned */
+    select?: unknown;
+    /** (3.1) `{ max }`: the bound on the selection (`selection_too_large` beyond it); the implicit ceiling without it */
+    expect?: unknown;
 }
 /** The kernel op as the plan carries it (`childIds` → `child_ids`). */
 export declare function wireOp(o: Op): WireOp;
@@ -165,10 +169,12 @@ export declare function admitPlan(input: unknown): Plan;
 export declare function executePlan(store: Store, req: ExecuteRequest & {
     plan: unknown;
 }): Receipt;
-/** `execute { plan_id, effects }` (§11.7): re-plan; the digest must equal `plan_id`, else `plan_mismatch`. */
+/** `execute { plan_id, effects, select?, expect? }` (§11.7): re-plan (with the selector when one is given, §11.8); the digest must equal `plan_id`, else `plan_mismatch`. */
 export declare function executeByDigest(store: Store, req: ExecuteRequest & {
     planId: string;
     effects: unknown;
+    select?: unknown;
+    expect?: unknown;
 }): Receipt;
 /**
  * `apply { effects }` with both halves kept (the sugar's seam — `sugar.ts`,
@@ -179,14 +185,18 @@ export declare function executeByDigest(store: Store, req: ExecuteRequest & {
  */
 export declare function applyEffectsDetailed(store: Store, req: ExecuteRequest & {
     effects: unknown;
+    select?: unknown;
+    expect?: unknown;
     dryRun?: boolean;
 }): {
     plan: Plan;
     receipt?: Receipt;
 };
-/** `apply { effects }` (§11.7): plan + execute under one lock and one transaction; `dryRun` returns the Plan. */
+/** `apply { effects, select?, expect? }` (§11.7): plan + execute under one lock and one transaction; `dryRun` returns the Plan. */
 export declare function applyEffects(store: Store, req: ExecuteRequest & {
     effects: unknown;
+    select?: unknown;
+    expect?: unknown;
     dryRun?: boolean;
 }): Plan | Receipt;
 /** Every string that is a key of `ids` replaced by its value, recursively (arrays and plain objects) — a plan's `$new.n` realized from a receipt's `new_ids`. */