@omgbase/core 0.15.0 → 0.21.0

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

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

package/dist/src/mutate/known-ids.js

@@ -1,4 +1,5 @@
 import { mintId } from "../core/ids.js";
+import { sha256 } from "../core/hash.js";
 import { extractFromBlock, extractFromFrontmatter, resolveRelativePath } from "../graph/extract.js";
 import { resolveExternal, resolveDocPath } from "../core/store/edges.js";
 import { adapterForPath } from "../format/index.js";
@@ -79,12 +80,19 @@ export function makeKnownIdResolver(store, repoId, doc, priorIds, opts = {}) {
         const assigned = assignFromMut(rest, byKey);
         const nowIds = collectIds(assigned);
         const nowSet = new Set(nowIds);
-        // Dispositions are INTENT, not inference: a carried id that existed before is
-        // `same`/`edited` (confidence 1.0); an id new this commit is `inserted`; a
-        // prior id no longer present is `deleted`.
-        const dispositions = nowIds.map((id) => ({
-            blockId: id,
-            kind: priorIds.has(id) ? "edited" : "inserted",
+        // Dispositions are INTENT, not inference (confidence 1.0, reason `api`): an
+        // id new this commit is `inserted`; a prior id no longer present is
+        // `deleted` (pooled, no row); a carried id is classified exactly as
+        // spec/reconcile §2 classifies a carry — `same` when its raw bytes, parent
+        // and sibling index are those of its live row, else `edited` / `moved` /
+        // `edited_moved` — so a block the changeset did not touch is `same` and
+        // (spec/store §5.4 step 10, 14.2) never persisted: a one-paragraph edit
+        // moves that paragraph's `updated_at`, not its siblings'. Through store
+        // 14.1 every carried block was stamped `edited`.
+        const prior = docId === null ? new Map() : priorRows(db, docId);
+        const dispositions = classifyCarries(assigned, prior, priorIds).map((c) => ({
+            blockId: c.id,
+            kind: c.kind,
             confidence: 1,
             reason: "api",
             matcherV: null,
@@ -121,10 +129,42 @@ export function makeKnownIdResolver(store, repoId, doc, priorIds, opts = {}) {
             }
             return out;
         };
-        void docId;
         return { assigned, dispositions, deleted, crossDocIds, extractEdges };
     };
 }
+function priorRows(db, docId) {
+    const rows = db
+        .prepare("SELECT block_id, parent_block, ordinal, raw_hash FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL")
+        .all(docId);
+    return new Map(rows.map((r) => [r.block_id, { parent: r.parent_block, ordinal: r.ordinal, rawHashHex: r.raw_hash.toString("hex") }]));
+}
+/**
+ * spec/reconcile §2 "Classifying a carry", applied to the api path's known ids:
+ * `moved` = the parent or the sibling index differs from the live row,
+ * `content_equal` = the raw bytes hash the same; `same` / `moved` / `edited` /
+ * `edited_moved` follow. An id with no prior row (new to this document — a
+ * mint or a cross-document arrival) is `inserted`. Pre-order over the tree.
+ */
+export function classifyCarries(blocks, prior, priorIds) {
+    const out = [];
+    const walk = (list, parent) => {
+        list.forEach((b, index) => {
+            const row = priorIds.has(b.blockId) ? prior.get(b.blockId) : undefined;
+            if (!row) {
+                out.push({ id: b.blockId, kind: "inserted" });
+            }
+            else {
+                const moved = row.parent !== parent || row.ordinal !== index;
+                const contentEqual = row.rawHashHex === sha256(b.raw).toString("hex");
+                out.push({ id: b.blockId, kind: contentEqual ? (moved ? "moved" : "same") : moved ? "edited_moved" : "edited" });
+            }
+            if (b.children.length > 0)
+                walk(b.children, b.blockId);
+        });
+    };
+    walk(blocks, null);
+    return out;
+}
 // Edge resolution — mirrors reconciling-ingest's resolvers (block-anchor targets
 // resolve to the document node in v1; the anchor is preserved on the edge).
 function resolveEdge(db, repoId, srcDoc, e, docDir) {

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

@@ -35,6 +35,7 @@ export declare function opRemove(doc: MutDoc, blockIds: string[], opIndex: numbe
 export declare function opSplit(doc: MutDoc, blockId: string, at: number[], opIndex: number, expect?: Expect): {
     ids: string[];
 };
+export declare function trimCutEdges(pieces: readonly string[]): string[];
 export declare function opMerge(doc: MutDoc, blockIds: string[], opIndex: number, separator?: string, expectPer?: Record<string, Expect>): {
     ids: string[];
     mergedInto: string[];

package/dist/src/mutate/ops.js

@@ -505,7 +505,7 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     const pieces = [];
     for (let i = 1; i < cuts.length; i++)
         pieces.push(raw.slice(cuts[i - 1], cuts[i]));
-    const nonEmpty = pieces.filter((p) => p.trim().length > 0);
+    const nonEmpty = trimCutEdges(pieces).filter((p) => p.trim().length > 0);
     if (nonEmpty.length < 2)
         throw new MutationError("type_mismatch", "split must yield ≥2 non-empty fragments");
     // First fragment carries the id (authored intent, 04 §1); rest minted.
@@ -533,6 +533,25 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     markContainerDirty(doc, found.siblings);
     return { ids: [blockId, ...newBlocks.map((b) => b.id)] };
 }
+// spec/mutate §2.5 (3.5): the pieces of a split are trimmed at the CUT edges
+// only — every piece but the last loses its trailing whitespace, every piece
+// but the first its leading whitespace — so an offset on either side of a
+// space (or inside the run, a `\n`, a hard break's `  \n`) yields the same
+// pieces and no piece ends in a stray space. The raw's own start and end are
+// not cut edges and stay as authored (a last piece keeps the raw's trailing
+// spaces). The whitespace set is the format's trim set (`spec/format` §4.1
+// step 4) — exactly what JavaScript's `trimStart`/`trimEnd` remove.
+export function trimCutEdges(pieces) {
+    const last = pieces.length - 1;
+    return pieces.map((p, i) => {
+        let out = p;
+        if (i < last)
+            out = out.trimEnd();
+        if (i > 0)
+            out = out.trimStart();
+        return out;
+    });
+}
 export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
     if (blockIds.length < 2)
         throw new MutationError("not_contiguous", "merge requires ≥2 blocks");

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`. */

package/dist/src/mutate/plan.js

@@ -7,112 +7,30 @@ import { ChangesetPlanner } from "./apply.js";
 import { commitChangeset, readDocBase } from "./commit.js";
 import { resolveDocStore } from "./doc-store.js";
 import { parseNewDoc } from "./docs.js";
-import { ConflictTracker, SymbolTable, isNewSymbol, lowerEffect, symbolicMinter, validateEffects, effectInvalid, } from "./effects.js";
+import { ConflictTracker, SymbolTable, isNewSymbol, lowerEffect, symbolicMinter, effectInvalid, } from "./effects.js";
+import { compilePlain, compileSelection, selectionInvalid } from "./select.js";
 import { MutationError } from "./tree.js";
+import { canonicalJson, fixRequest, rootOfId, narrowedTo } from "./canonical.js";
 // The Plan (spec/mutate §11.4–§11.7, 2.3): the frozen, executable, digest-named
 // result of lowering an ordered effect list. `plan` writes nothing; `execute`
 // commits exactly a plan — its preconditions re-validated inside the
 // transaction by `commit.ts` — and `apply({ effects })` is plan + execute under
 // one writer lock and one transaction. New identities are symbolic (`$new.n`,
 // minted at execute, mapped in the receipt); a plan's identity is the sha256 of
-// the canonical JSON of its executable core.
+// the canonical JSON of its executable core. Since 3.1 (§11.8) a request may
+// carry an OQX `select` whose hits, bound to the `effects` as templates, ARE
+// the effects (`select.ts`); the frozen `selection` is the core's seventh member.
 export const PLAN_VERSION = 1;
 /** The lowering + conflict rules version (§11.4; the `matcher_v` precedent). */
-export const PLANNER_V = "p2";
+export const PLANNER_V = "p3";
 // ---- canonical JSON and the digest (§11.5) ----------------------------------------------
-function cmpUtf8(a, b) {
-    return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
-}
-// A lone surrogate has no UTF-8 encoding: it cannot be digested (nor sent as JSON text).
-function isWellFormed(s) {
-    for (let i = 0; i < s.length; i++) {
-        const c = s.charCodeAt(i);
-        if (c >= 0xd800 && c <= 0xdbff) {
-            const n = s.charCodeAt(i + 1);
-            if (!(n >= 0xdc00 && n <= 0xdfff))
-                return false;
-            i++;
-        }
-        else if (c >= 0xdc00 && c <= 0xdfff)
-            return false;
-    }
-    return true;
-}
-function canonicalString(s) {
-    if (!isWellFormed(s))
-        throw effectInvalid("strings must be well-formed Unicode (a lone surrogate cannot be digested)");
-    let out = '"';
-    for (let i = 0; i < s.length; i++) {
-        const c = s.charCodeAt(i);
-        switch (c) {
-            case 0x22:
-                out += '\\"';
-                break;
-            case 0x5c:
-                out += "\\\\";
-                break;
-            case 0x08:
-                out += "\\b";
-                break;
-            case 0x0c:
-                out += "\\f";
-                break;
-            case 0x0a:
-                out += "\\n";
-                break;
-            case 0x0d:
-                out += "\\r";
-                break;
-            case 0x09:
-                out += "\\t";
-                break;
-            default:
-                out += c < 0x20 ? `\\u${c.toString(16).padStart(4, "0")}` : s[i];
-        }
-    }
-    return out + '"';
-}
-function canonicalNumber(n) {
-    if (!Number.isFinite(n))
-        throw effectInvalid("a number in a plan must be finite");
-    if (Number.isInteger(n) && Math.abs(n) < 2 ** 53)
-        return String(n === 0 ? 0 : n);
-    return String(n);
-}
-/**
- * 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 function canonicalJson(v) {
-    if (v === null)
-        return "null";
-    switch (typeof v) {
-        case "boolean":
-            return v ? "true" : "false";
-        case "number":
-            return canonicalNumber(v);
-        case "string":
-            return canonicalString(v);
-        case "object": {
-            if (Array.isArray(v))
-                return `[${v.map((x) => canonicalJson(x === undefined ? null : x)).join(",")}]`;
-            const o = v;
-            const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort(cmpUtf8);
-            return `{${keys.map((k) => `${canonicalString(k)}:${canonicalJson(o[k])}`).join(",")}}`;
-        }
-        default:
-            throw effectInvalid(`a ${typeof v} cannot be digested`);
-    }
-}
-/** 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 function planCore(p) {
-    return { version: p.version, planner_v: p.planner_v, effects: p.effects, opset: p.opset, preconditions: p.preconditions, new_ids: p.new_ids };
+    return {
+        version: p.version, planner_v: p.planner_v, effects: p.effects, opset: p.opset, preconditions: p.preconditions, new_ids: p.new_ids,
+        ...(p.selection !== undefined ? { selection: p.selection } : {}),
+    };
 }
 /** `plan_id = hex(sha256(canonical(core)))` (§11.5). */
 export function planDigest(core) {
@@ -141,7 +59,28 @@ export function kernelOp(o) {
  * freeze the preconditions, digest the core. Reads only; mints no real id.
  */
 export function planEffects(store, req) {
-    const effects = validateEffects(req.effects);
+    // A selector request (§11.8): the templates compile into the concrete effects
+    // — hits × templates — and the frozen `selection` joins the core; an empty
+    // selection is an empty plan (the non-empty rule of §11.1 is the templates').
+    let effects;
+    let selection;
+    let templates;
+    let origins = [];
+    if (req.select !== undefined || req.expect !== undefined) {
+        if (req.select === undefined)
+            throw selectionInvalid("`expect` bounds a selection — pass `select` with it");
+        const compiled = compileSelection(store, req.repoId, req.select, req.expect, req.effects);
+        effects = compiled.effects;
+        selection = compiled.selection;
+        origins = compiled.origins;
+    }
+    else {
+        // (3.2) the `-> ` sugar and expressions over each effect's own target row; without any, the shape check alone.
+        const compiled = compilePlain(store, req.repoId, req.effects);
+        effects = compiled.effects;
+        templates = compiled.templates;
+        origins = compiled.origins;
+    }
     const docStore = resolveDocStore(req);
     const symbols = new SymbolTable();
     return withIdMinter(symbolicMinter(symbols), () => {
@@ -150,16 +89,27 @@ export function planEffects(store, req) {
             store, repoId: req.repoId, docStore, planner, symbols,
             blockSymbols: new Map(), creates: [], identity: new Map(), retargets: [], moves: [], tombstones: [], heads: new Map(), ops: [],
             pins: new Map(), parents: [], absentPaths: [], docBases: new Map(),
-            tracker: new ConflictTracker(canonicalJson), canonical: canonicalJson, resolved: [],
+            tracker: new ConflictTracker(canonicalJson), canonical: canonicalJson, resolved: [], summary: [],
         };
         effects.forEach((e, i) => {
             try {
                 lowerEffect(ctx, i, e);
             }
             catch (err) {
-                // Every failure names the effect it arose from (the kernel's own data — `op_index`, `block` — stays).
-                if (err instanceof MutationError && err.data.effect_index === undefined)
-                    err.data = { ...err.data, effect_index: i };
+                // Every failure names the effect it arose from (the kernel's own data — `op_index`, `block` — stays);
+                // an expanded effect's names its template and the hit it was bound to as well (§11.8).
+                if (err instanceof MutationError) {
+                    if (err.data.effect_index === undefined)
+                        err.data = { ...err.data, effect_index: i };
+                    const origin = origins[i];
+                    if (origin !== undefined && err.data.row === undefined) {
+                        err.data = { ...err.data, ...(origin.template_index !== undefined ? { template_index: origin.template_index } : {}), row: origin.row };
+                    }
+                    // (3.3) the corrected example, built from the request as given (§8 "fix").
+                    const fix = planningFix(err, i, req, origins, symbols);
+                    if (fix !== undefined && err.data.fix === undefined)
+                        err.data = { ...err.data, fix };
+                }
                 throw err;
             }
         });
@@ -182,7 +132,7 @@ export function planEffects(store, req) {
             parents: ctx.parents,
             absent_paths: ctx.absentPaths,
         };
-        const core = { version: PLAN_VERSION, planner_v: PLANNER_V, effects: ctx.resolved, opset, preconditions, new_ids: symbols.entries };
+        const core = { version: PLAN_VERSION, planner_v: PLANNER_V, effects: ctx.resolved, opset, preconditions, new_ids: symbols.entries, ...(selection !== undefined ? { selection } : {}) };
         const plan_id = planDigest(core);
         // The preview (not digested): the kernel results, every revision the commit
         // would record — a created document's under its symbol, from its adopted
@@ -205,14 +155,73 @@ export function planEffects(store, req) {
             if (moved)
                 r.path = moved.to;
         }
-        const preview = { results: changeset.results, revisions, diffs };
+        const preview = { results: changeset.results, revisions, diffs, summary: ctx.summary };
         if (ctx.identity.size > 0)
             preview.identity = Object.fromEntries(ctx.identity);
         if (ctx.retargets.length > 0)
             preview.retarget = ctx.retargets;
-        return { ...core, plan_id, diagnostics: ctx.tracker.diagnostics, preview };
+        return { ...core, plan_id, diagnostics: ctx.tracker.diagnostics, ...(templates !== undefined ? { templates } : {}), preview };
     });
 }
+// ---- the corrected examples of planning errors (§8 "fix", 3.3) ------------------------------
+/** The request as the caller gave it, for a `fix`: `select`/`expect` only when present. */
+function requestOf(req) {
+    return { effects: req.effects, ...(req.select !== undefined ? { select: req.select } : {}), ...(req.expect !== undefined ? { expect: req.expect } : {}) };
+}
+/**
+ * `conflicting_effects`: keep the later effect — the request minus the earlier
+ * one; under a selector, a cross-hit collision narrows the selector to the
+ * later hit (`from <root> where id == …`, `expect.max: 1`) and a same-hit
+ * collision drops the earlier template. `stale_plan` at plan time (an
+ * `expect.revision` that no longer holds): the same request with the current
+ * revision in that guard. `target_missing { symbol }` for a `$new.n` no earlier
+ * effect created: the next `create` of a plain request moved before the effect
+ * that uses it, the symbol renamed to the one that create will allocate.
+ */
+function planningFix(err, i, req, origins, symbols) {
+    const effects = Array.isArray(req.effects) ? req.effects : null;
+    if (effects === null)
+        return undefined;
+    const selector = req.select !== undefined;
+    if (err.code === "conflicting_effects" && Array.isArray(err.data.effects)) {
+        const [a, b] = err.data.effects;
+        if (!selector)
+            return fixRequest({ effects: effects.filter((_, k) => k !== a) });
+        const oa = origins[a];
+        const ob = origins[b];
+        if (oa === undefined || ob === undefined || oa.template_index === undefined)
+            return undefined;
+        if (oa.row.id !== ob.row.id)
+            return fixRequest({ select: narrowedTo(rootOfId(ob.row.id), ob.row.id), effects, expect: { max: 1 } });
+        return fixRequest({ ...requestOf(req), effects: effects.filter((_, k) => k !== oa.template_index) });
+    }
+    if (err.code === "stale_plan" && isRecord(err.data.current) && typeof err.data.current.revision === "string") {
+        const t = selector ? origins[i]?.template_index : i;
+        if (t === undefined || !isRecord(effects[t]))
+            return undefined;
+        const e = effects[t];
+        const expect = { ...(isRecord(e.expect) ? e.expect : {}), revision: err.data.current.revision };
+        return fixRequest({ ...requestOf(req), effects: effects.map((x, k) => (k === t ? { ...e, expect } : x)) });
+    }
+    if (err.code === "target_missing" && typeof err.data.symbol === "string" && !selector && symbols.kindOf(err.data.symbol) === undefined) {
+        const c = effects.findIndex((e, k) => k > i && isRecord(e) && e.op === "create");
+        if (c < 0)
+            return undefined;
+        const symbol = `$new.${symbols.entries.length}`;
+        const reordered = effects.filter((_, k) => k !== c);
+        reordered.splice(i, 0, effects[c]);
+        return fixRequest({ effects: reordered.map((e, k) => (k === i + 1 ? substituteSymbols(e, { [err.data.symbol]: symbol }) : e)) });
+    }
+    return undefined;
+}
+/** The `fix` of a plan that cannot be executed as it stands (`stale_plan`, `plan_mismatch`): re-plan and commit in one call — `apply` over the plan's selector form when it has one, else over its concrete effects (none when the plan has no effects: `apply` takes at least one). */
+function replanFix(plan) {
+    if (plan.selection !== undefined) {
+        const sel = plan.selection;
+        return fixRequest({ select: sel.query, effects: sel.templates, expect: sel.expect ?? { max: sel.cardinality } });
+    }
+    return Array.isArray(plan.effects) && plan.effects.length > 0 ? fixRequest({ effects: plan.effects }) : undefined;
+}
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -256,12 +265,24 @@ export function admitPlan(input) {
     }
     if (!Array.isArray(input.new_ids))
         throw effectInvalid("`plan.new_ids` must be an array");
+    if (input.selection !== undefined) {
+        // (3.1) the optional seventh member: its shape, so the digest below covers what it says.
+        const sel = input.selection;
+        if (!isRecord(sel) || typeof sel.query !== "string" || !Array.isArray(sel.templates) || typeof sel.cardinality !== "number" || !Array.isArray(sel.identities)) {
+            throw effectInvalid("`plan.selection` is { query, expect?, templates, cardinality, identities }");
+        }
+        if (sel.expect !== undefined && (!isRecord(sel.expect) || typeof sel.expect.max !== "number"))
+            throw effectInvalid("`plan.selection.expect` is { max }");
+    }
     if (typeof input.plan_id !== "string")
         throw effectInvalid("`plan.plan_id` must be a string");
+    // (3.2) the written effects ride outside the digest, like `diagnostics`; their shape is all that is checked.
+    if (input.templates !== undefined && !Array.isArray(input.templates))
+        throw effectInvalid("`plan.templates` must be an array");
     const plan = input;
     const actual = planDigest(plan);
     if (actual !== plan.plan_id) {
-        throw new MutationError("plan_mismatch", "the plan's digest does not match its plan_id; it was edited or produced by a different planner — re-plan", { expected: plan.plan_id, actual });
+        throw new MutationError("plan_mismatch", "the plan's digest does not match its plan_id; it was edited or produced by a different planner — re-plan", { expected: plan.plan_id, actual, fix: replanFix(plan) });
     }
     return plan;
 }
@@ -271,13 +292,17 @@ export function executePlan(store, req) {
     const docStore = resolveDocStore(req);
     return underLock(req, () => executeAdmitted(store, req, plan, docStore));
 }
-/** `execute { plan_id, effects }` (§11.7): re-plan; the digest must equal `plan_id`, else `plan_mismatch`. */
+/** The selector half of a request, threaded to the planner as given (absent keys stay absent). */
+function selectorOf(req) {
+    return { ...(req.select !== undefined ? { select: req.select } : {}), ...(req.expect !== undefined ? { expect: req.expect } : {}) };
+}
+/** `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 function executeByDigest(store, req) {
     const docStore = resolveDocStore(req);
     return underLock(req, () => {
-        const plan = planEffects(store, { repoId: req.repoId, docStore, ...(req.omgbaseDir !== undefined ? { omgbaseDir: req.omgbaseDir } : {}), effects: req.effects });
+        const plan = planEffects(store, { repoId: req.repoId, docStore, ...(req.omgbaseDir !== undefined ? { omgbaseDir: req.omgbaseDir } : {}), effects: req.effects, ...selectorOf(req) });
         if (plan.plan_id !== req.planId) {
-            throw new MutationError("plan_mismatch", "the effects or the documents they target changed since the plan was made; re-plan", { expected: req.planId, actual: plan.plan_id });
+            throw new MutationError("plan_mismatch", "the effects or the documents they target changed since the plan was made; re-plan", { expected: req.planId, actual: plan.plan_id, fix: fixRequest(requestOf(req)) });
         }
         return executeAdmitted(store, req, plan, docStore);
     });
@@ -291,15 +316,23 @@ export function executeByDigest(store, req) {
  */
 export function applyEffectsDetailed(store, req) {
     const docStore = resolveDocStore(req);
-    const planIt = () => planEffects(store, { repoId: req.repoId, docStore, ...(req.omgbaseDir !== undefined ? { omgbaseDir: req.omgbaseDir } : {}), effects: req.effects });
+    const planIt = () => planEffects(store, { repoId: req.repoId, docStore, ...(req.omgbaseDir !== undefined ? { omgbaseDir: req.omgbaseDir } : {}), effects: req.effects, ...selectorOf(req) });
     if (req.dryRun)
         return { plan: planIt() };
+    // One-shot `apply` with a selector must bound it (§11.8): the caller never saw
+    // the hits. The fix (3.3) is the same call bounded at the selection's actual
+    // size — the selector compiles (reads only) to count it; a selection the
+    // compile itself refuses reports its own error and fix.
+    if (req.select !== undefined && req.expect === undefined) {
+        const { selection } = compileSelection(store, req.repoId, req.select, undefined, req.effects);
+        throw selectionInvalid("`expect.max` is required on `apply` with `select` — bound the selection, or preview it with `plan`", { fix: fixRequest({ select: req.select, effects: req.effects, expect: { max: selection.cardinality } }) });
+    }
     return underLock(req, () => {
         const plan = planIt();
         return { plan, receipt: executeAdmitted(store, req, plan, docStore) };
     });
 }
-/** `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 function applyEffects(store, req) {
     const { plan, receipt } = applyEffectsDetailed(store, req);
     return receipt ?? plan;
@@ -347,7 +380,9 @@ function underLock(req, fn) {
  * `ingest_known { base: null }`; a moved document's revision lands at its new
  * path), tombstones — and `commitChangeset` re-validates every triple inside
  * `BEGIN IMMEDIATE`. The commit row's `ops` is the intent record
- * `canonical({ v: 1, plan_id, effects })`.
+ * `canonical({ v: 1, plan_id, effects, selection?, templates? })` (§11.8: the
+ * selector, its templates and the hits it bound ride along when the plan had
+ * one; a plain request's written effects when one carried an expression, 3.2).
  */
 function executeAdmitted(store, req, plan, docStore) {
     for (const d of plan.preconditions.docs) {
@@ -360,6 +395,7 @@ function executeAdmitted(store, req, plan, docStore) {
                 expected_revision: d.base_revision,
                 current: { revision: row.currentRev, hash: row.fileHash },
                 retriable: true,
+                fix: replanFix(plan),
             });
         }
     }
@@ -375,7 +411,11 @@ function executeAdmitted(store, req, plan, docStore) {
         origin: "api",
         actor: req.origin.actor,
         reason: req.origin.reason ?? null,
-        ops: canonicalJson({ v: 1, plan_id: plan.plan_id, effects: plan.effects }),
+        ops: canonicalJson({
+            v: 1, plan_id: plan.plan_id, effects: plan.effects,
+            ...(plan.selection !== undefined ? { selection: plan.selection } : {}),
+            ...(plan.templates !== undefined ? { templates: plan.templates } : {}),
+        }),
     };
     const stat = req.omgbaseDir !== undefined;
     const moved = new Map(plan.opset.moves.map((m) => [m.id, m]));
@@ -467,6 +507,6 @@ function executeAdmitted(store, req, plan, docStore) {
         if (id !== undefined)
             newIds[s.symbol] = id;
     }
-    return { plan_id: plan.plan_id, commit: outcome.commitId, revisions, new_ids: newIds, committed: true };
+    return { plan_id: plan.plan_id, commit: outcome.commitId, revisions, new_ids: newIds, committed: true, summary: plan.preview?.summary ?? [] };
 }
 //# sourceMappingURL=plan.js.map