@superbee/core 0.2.0-pre.15 → 0.2.0-pre.17

package/dist/recipe-lifecycle/evolution.js

@@ -0,0 +1,659 @@
+// Explicit, state-bound evolution of recipe-installed conventions.
+//
+// Recipe installation is create-only and intentionally never overwrites bundle-authored content.
+// This module owns the distinct upgrade authority: a read-only compatibility plan followed by an
+// exact-token preflight and exact-version CAS apply over each target whose content or recipe stamp
+// needs a write. The stamp travels in the same write as the convention's content. Since the bundle
+// has no cross-document transaction, a postcondition reports concurrent non-target changes honestly.
+import { query, readBlob, readBundleOkfVersion, readDocVersioned } from "../bundle-ops.js";
+import { resolveContentType } from "../content-type.js";
+import { DocumentNotFoundError, mutateDocument } from "../document-mutation.js";
+import { applyV02MutationMetadata } from "../document-write-policy.js";
+import { InvalidInputError, OkfActorError } from "../errors.js";
+import { CONVENTIONS_PREFIX, buildKindRegistry, parseConventionDoc, projectKindValidationWarnings, validateAgainstKind, } from "../kinds.js";
+import { collectLinkDeclarations } from "../link-types.js";
+import { parseLinksFromDoc } from "../links.js";
+import { okfValuesEqual } from "../okf-authored-values.js";
+import { VersionConflict, blobVersion, contentVersion, sha256Hex } from "../versioning.js";
+import { RecipeEditionChanged, RecipeEvolutionBlocked, RecipeEvolutionInterrupted, RecipeEvolutionPlanChanged, RecipeEvolutionPostcondition, } from "./errors.js";
+import { materializeRecipeForEdition, recipeDocumentForApply, sameInstalledDoc, } from "./install.js";
+import { RECIPE_STAMP_KEY, conventionStampState, definitionDigest, recipeStampIdentity, recipeStampState, withRecipeStamp, } from "./stamp.js";
+const RECIPE_EVOLUTION_WRITE_REGISTRY = { kinds: new Map(), warnings: [] };
+function plainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function comparableRecipeDoc(doc, okfVersion) {
+    const { timestamp: _timestamp, [RECIPE_STAMP_KEY]: _stamp, ...frontmatter } = doc.frontmatter;
+    const generated = plainRecord(frontmatter.generated);
+    if (okfVersion === "0.2" && generated) {
+        const { at: _at, ...rest } = generated;
+        if (Object.keys(rest).length > 0)
+            frontmatter.generated = rest;
+        else
+            delete frontmatter.generated;
+    }
+    return { id: doc.id, frontmatter, body: doc.body };
+}
+/** Root keys kept from the installed document, never read from the source; the stamp is one. */
+const PRESERVED_ROOT_METADATA = new Set(["timestamp", "actor", "generated", "verified", "superbee_updated_by", RECIPE_STAMP_KEY]);
+/**
+ * Bundle-local placement: a reading-order `order` an author put on an installed convention is the
+ * bundle's, not the recipe's. Evolution keeps it when the recipe declares none, so ordering the
+ * seeded Kinds never blocks a recipe upgrade; a recipe that declares its own order merges as any
+ * other key.
+ */
+const BUNDLE_LOCAL_PLACEMENT = new Set(["order"]);
+function pointerSegment(value) {
+    return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function setOwn(record, key, value) {
+    Object.defineProperty(record, key, {
+        value,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+}
+/**
+ * Merge recipe declarations into a user-owned convention without deleting or replacing any
+ * existing semantic value. Arrays are declaration sets: additions append, while omissions are
+ * blockers. Root mutation/provenance metadata is preserved by the shared write policy instead of
+ * being treated as recipe-owned schema.
+ */
+function additiveConventionCandidate(existing, desired, blockers) {
+    const addedPaths = [];
+    const merge = (current, next, pointer) => {
+        if (current === undefined) {
+            addedPaths.push(pointer);
+            return next;
+        }
+        if (next === undefined) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_REMOVAL_UNSUPPORTED", desired.id, `automatic evolution preserves the existing declaration at '${pointer}'; remove it manually after reviewing dependent content`, pointer);
+            return current;
+        }
+        if (okfValuesEqual(current, next))
+            return current;
+        if (Array.isArray(current) && Array.isArray(next)) {
+            const merged = [...current];
+            for (const value of current) {
+                if (!next.some((candidate) => okfValuesEqual(candidate, value))) {
+                    evolutionBlocker(blockers, "RECIPE_EVOLUTION_REMOVAL_UNSUPPORTED", desired.id, `automatic evolution preserves the existing declaration value at '${pointer}'`, pointer);
+                }
+            }
+            for (const value of next) {
+                if (merged.some((candidate) => okfValuesEqual(candidate, value)))
+                    continue;
+                merged.push(value);
+                addedPaths.push(`${pointer}/${pointerSegment(String(value))}`);
+            }
+            return merged;
+        }
+        const currentRecord = plainRecord(current);
+        const nextRecord = plainRecord(next);
+        if (currentRecord && nextRecord) {
+            const merged = { ...currentRecord };
+            for (const key of new Set([...Object.keys(currentRecord), ...Object.keys(nextRecord)])) {
+                setOwn(merged, key, merge(currentRecord[key], nextRecord[key], `${pointer}/${pointerSegment(key)}`));
+            }
+            return merged;
+        }
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_REPLACEMENT_UNSUPPORTED", desired.id, `automatic evolution will not replace the existing declaration at '${pointer}'`, pointer);
+        return current;
+    };
+    const currentFrontmatter = existing.frontmatter;
+    const desiredFrontmatter = desired.frontmatter;
+    const candidateFrontmatter = { ...currentFrontmatter };
+    for (const key of new Set([...Object.keys(currentFrontmatter), ...Object.keys(desiredFrontmatter)])) {
+        // Evolution never imports recipe-authored provenance, verification, or mutation attribution.
+        // These coordinates come exclusively from the installed document and the shared write policy.
+        if (PRESERVED_ROOT_METADATA.has(key))
+            continue;
+        if (BUNDLE_LOCAL_PLACEMENT.has(key) && desiredFrontmatter[key] === undefined)
+            continue;
+        setOwn(candidateFrontmatter, key, merge(currentFrontmatter[key], desiredFrontmatter[key], `/frontmatter/${pointerSegment(key)}`));
+    }
+    let body = existing.body;
+    if (existing.body === "" && desired.body !== "") {
+        body = desired.body;
+        addedPaths.push("/body");
+    }
+    else if (existing.body !== desired.body) {
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_BODY_REPLACEMENT_UNSUPPORTED", desired.id, "automatic evolution will not replace an existing convention body; update it manually after review", "/body");
+    }
+    return {
+        candidate: { id: desired.id, frontmatter: candidateFrontmatter, body },
+        addedPaths: [...new Set(addedPaths)].sort(),
+    };
+}
+async function readRecipeDocIfPresent(bundle, id) {
+    try {
+        return await readDocVersioned(bundle, id);
+    }
+    catch (error) {
+        if (error instanceof DocumentNotFoundError || error?.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function evolutionBlocker(blockers, code, id, message, field) {
+    blockers.push({ code, id, message, ...(field ? { field } : {}) });
+}
+function monotonicEvolutionBlockers(current, desired, blockers) {
+    const currentRequired = new Set(current.fields.required);
+    for (const field of desired.fields.required) {
+        if (!currentRequired.has(field)) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_NON_MONOTONIC", desired.id, `automatic evolution cannot newly require '${field}' for '${desired.governs}'; migrate instances explicitly first`, field);
+        }
+    }
+    // An enum on a declared field is admitted, installed or newly declared alike: the instance scan
+    // against the desired kind blocks the plan when any existing document carries a disallowed value.
+    // Adding a `fields.types` entry needs no rule here for the same reason; changing or removing one
+    // is refused by the additive merge before this classifier runs.
+    const desiredDeclared = new Set([...desired.fields.required, ...desired.fields.optional]);
+    for (const [field, desiredValues] of Object.entries(desired.fields.values)) {
+        const currentValues = current.fields.values[field];
+        if (!currentValues) {
+            if (desiredDeclared.has(field))
+                continue;
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_NON_MONOTONIC", desired.id, `automatic evolution cannot add an enum restriction to '${field}' for '${desired.governs}'; declare '${field}' in fields.required or fields.optional first`, field);
+            continue;
+        }
+        const allowed = new Set(desiredValues);
+        const removed = currentValues.filter((value) => !allowed.has(value));
+        if (removed.length > 0) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_NON_MONOTONIC", desired.id, `automatic evolution cannot remove allowed '${field}' value(s) for '${desired.governs}': ${removed.join(", ")}`, field);
+        }
+    }
+    const currentSections = new Set(current.sections ?? []);
+    for (const section of desired.sections ?? []) {
+        if (!currentSections.has(section)) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_NON_MONOTONIC", desired.id, `automatic evolution cannot newly require the '# ${section}' section for '${desired.governs}'`, section);
+        }
+    }
+    // A new outbound link type is additive (its existing edges are revalidated by
+    // linkTypeAdditionBlockers). Removing or retargeting an installed one is not. Compare the PARSED
+    // maps: the parser trims keys, so a raw key such as "at " can redefine "at" through the merge.
+    const desiredLinks = desired.links ?? {};
+    for (const [linkType, target] of Object.entries(current.links ?? {})) {
+        if (Object.hasOwn(desiredLinks, linkType) && desiredLinks[linkType] === target)
+            continue;
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_RELATIONSHIP_CHANGE", desired.id, `automatic evolution does not remove or retarget the outbound link type '${linkType}' for '${desired.governs}'`, `links.${linkType}`);
+    }
+    if (!okfValuesEqual(current.expectsInbound ?? {}, desired.expectsInbound ?? {})) {
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_RELATIONSHIP_CHANGE", desired.id, `automatic evolution does not change inbound relationship expectations for '${desired.governs}'`, "expects_inbound");
+    }
+    if (!okfValuesEqual(current.fields.terminal, desired.fields.terminal)) {
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_TERMINAL_CHANGE", desired.id, `automatic evolution does not change terminal workflow values for '${desired.governs}' because open-work visibility can change`, "fields.terminal");
+    }
+}
+function addedFieldRestrictions(current, desired) {
+    const types = new Map();
+    for (const [field, type] of Object.entries(desired.fields.types ?? {})) {
+        if (!Object.hasOwn(current.fields.types ?? {}, field))
+            types.set(field, type);
+    }
+    const currentDeclared = new Set([...current.fields.required, ...current.fields.optional]);
+    const values = new Map();
+    for (const [field, allowed] of Object.entries(desired.fields.values)) {
+        if (!Object.hasOwn(current.fields.values, field) && currentDeclared.has(field)) {
+            values.set(field, allowed.map((value) => String(value)));
+        }
+    }
+    return { types, values };
+}
+/** Violating documents named in one restriction blocker; the rest are counted. */
+const RESTRICTION_BLOCKER_DOC_CAP = 10;
+/** Outbound link types a changing kind declares that its installed convention did not. */
+function addedLinkTypes(current, desired) {
+    const currentLinks = current.links ?? {};
+    return Object.keys(desired.links ?? {}).filter((linkType) => !Object.hasOwn(currentLinks, linkType));
+}
+/**
+ * Declaring a link type turns every existing edge with that exact text into a typed edge, across
+ * the whole bundle (the vocabulary is global; see `collectLinkDeclarations`). Apply the same rule
+ * `status` uses for `link_type_violations` to those edges under the prospective registry, so an
+ * evolution never introduces a violation. Returns the docs whose edges were checked.
+ */
+function linkTypeAdditionBlockers(docs, addedTexts, currentRegistry, registry, blockers) {
+    const declarations = collectLinkDeclarations(registry);
+    const currentDeclarations = collectLinkDeclarations(currentRegistry);
+    const docsById = new Map(docs.map((doc) => [doc.id, doc]));
+    const docType = (doc) => typeof doc.frontmatter.type === "string" ? doc.frontmatter.type : "";
+    const checked = [];
+    for (const doc of docs) {
+        let carries = false;
+        for (const link of parseLinksFromDoc(doc)) {
+            if (!addedTexts.has(link.text))
+                continue;
+            carries = true;
+            const target = docsById.get(link.to);
+            if (!target)
+                continue; // unresolved edges are their own `status` finding
+            const sourceType = docType(doc);
+            const violates = (declared) => {
+                if (declared.length === 0)
+                    return null;
+                const matched = declared.find((declaration) => declaration.governs === sourceType);
+                return matched && docType(target) === matched.target ? null : matched ?? declared[0];
+            };
+            const expected = violates(declarations.get(link.text) ?? []);
+            if (!expected)
+                continue;
+            // Already a violation before this evolution (another Kind declared the text): status
+            // reports it today; this plan neither creates nor fixes it.
+            if (violates(currentDeclarations.get(link.text) ?? []))
+                continue;
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_INSTANCE_INVALID", doc.id, `declaring link type '${link.text}' would make the edge to '${link.to}' a violation (expected ${expected.governs} -> ${expected.target}, found ${sourceType || "untyped"} -> ${docType(target) || "untyped"})`, `links.${link.text}`);
+        }
+        if (carries)
+            checked.push(doc);
+    }
+    return checked;
+}
+function evolutionPlanToken(input) {
+    return `sha256:${sha256Hex(JSON.stringify(input))}`;
+}
+async function prepareRecipeEvolution(bundle, sourceRecipe) {
+    const okfVersion = await readBundleOkfVersion(bundle) ?? "0.1";
+    const recipe = materializeRecipeForEdition(sourceRecipe, okfVersion);
+    const identity = recipeStampIdentity(sourceRecipe, recipe);
+    const blockers = recipe.warnings.map((warning) => ({
+        code: warning.code,
+        id: recipe.id,
+        message: warning.message,
+        ...(warning.field ? { field: warning.field } : {}),
+    }));
+    const definitions = [];
+    const writes = new Map();
+    const proofs = [];
+    const desiredKinds = new Map();
+    const addedLinkTexts = new Set();
+    const addedRestrictions = new Map();
+    const skippedConventions = [];
+    const installedConventions = await query(bundle, { prefix: CONVENTIONS_PREFIX, type: "Convention" }, {
+        onSkip: (skipped) => skippedConventions.push(skipped),
+    });
+    for (const skipped of skippedConventions) {
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_CONVENTION_UNREADABLE", skipped.id, `cannot prove the prospective registry while convention '${skipped.id}' is unreadable: ${skipped.reason}`);
+    }
+    const prospectiveById = new Map(installedConventions.map((doc) => [doc.id, doc]));
+    const currentRegistry = buildKindRegistry(installedConventions, [], { okfVersion });
+    for (const authored of recipe.docs) {
+        const target = recipeDocumentForApply(authored, okfVersion, "1970-01-01T00:00:00.000Z");
+        const parsedDesired = parseConventionDoc(target, { okfVersion });
+        if (!parsedDesired.ok) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_DEFINITION_INVALID", target.id, `recipe convention '${target.id}' is malformed: ${parsedDesired.reason}`);
+            continue;
+        }
+        for (const warning of parsedDesired.warnings) {
+            evolutionBlocker(blockers, warning.code, target.id, warning.message, warning.field);
+        }
+        if (parsedDesired.reservedFieldsIgnored.length > 0) {
+            evolutionBlocker(blockers, "KIND_RESERVED_FIELD", target.id, `recipe convention declares reserved field name(s): ${parsedDesired.reservedFieldsIgnored.join(", ")}`, parsedDesired.reservedFieldPaths.join(","));
+        }
+        if (okfVersion === "0.2") {
+            try {
+                applyV02MutationMetadata({
+                    candidate: { frontmatter: target.frontmatter, body: target.body },
+                    meaningfulChangeAt: "1970-01-01T00:00:00.000Z",
+                    allowGeneratedProvenanceSeed: false,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof InvalidInputError))
+                    throw error;
+                evolutionBlocker(blockers, "RECIPE_EVOLUTION_WRITE_POLICY_INVALID", target.id, `recipe convention cannot satisfy the OKF v0.2 write policy: ${error.message}`);
+            }
+        }
+        const existing = await readRecipeDocIfPresent(bundle, target.id);
+        if (!existing) {
+            prospectiveById.set(target.id, target);
+            desiredKinds.set(parsedDesired.kind.governs, parsedDesired.kind);
+            const desiredVersion = contentVersion(comparableRecipeDoc(target, okfVersion));
+            definitions.push({
+                id: target.id,
+                governs: parsedDesired.kind.governs,
+                action: "missing",
+                stamp: "missing",
+                expected_version: null,
+                desired_version: desiredVersion,
+                added_paths: [],
+            });
+            proofs.push({ kind: "definition", id: target.id, current_version: null, desired_version: desiredVersion });
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_DEFINITION_MISSING", target.id, "recipe evolution only updates installed conventions; install the complete recipe with 'recipe add' first");
+            continue;
+        }
+        const parsedCurrent = parseConventionDoc(existing.doc, { okfVersion });
+        if (existing.doc.frontmatter.type !== "Convention"
+            || !parsedCurrent.ok
+            || parsedCurrent.kind.governs !== parsedDesired.kind.governs) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_IDENTITY_CONFLICT", target.id, existing.doc.frontmatter.type !== "Convention"
+                ? `existing '${target.id}' has type '${String(existing.doc.frontmatter.type)}', not 'Convention'`
+                : !parsedCurrent.ok
+                    ? `existing '${target.id}' is not a valid convention: ${parsedCurrent.reason}`
+                    : `existing '${target.id}' governs '${parsedCurrent.kind.governs}', not '${parsedDesired.kind.governs}'`, "governs");
+        }
+        const merged = additiveConventionCandidate(existing.doc, target, blockers);
+        let candidate = merged.candidate;
+        if (okfVersion === "0.2") {
+            try {
+                const withMetadata = applyV02MutationMetadata({
+                    existing: existing.doc,
+                    candidate: { frontmatter: candidate.frontmatter, body: candidate.body },
+                    meaningfulChangeAt: "1970-01-01T00:00:00.000Z",
+                    allowGeneratedProvenanceSeed: false,
+                });
+                candidate = { id: candidate.id, ...withMetadata };
+            }
+            catch (error) {
+                if (!(error instanceof InvalidInputError))
+                    throw error;
+                evolutionBlocker(blockers, "RECIPE_EVOLUTION_WRITE_POLICY_INVALID", target.id, `prospective convention cannot satisfy the OKF v0.2 write policy: ${error.message}`);
+            }
+        }
+        prospectiveById.set(target.id, candidate);
+        const parsedCandidate = parseConventionDoc(candidate, { okfVersion });
+        if (!parsedCandidate.ok) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_DEFINITION_INVALID", target.id, `prospective convention '${target.id}' is malformed: ${parsedCandidate.reason}`);
+        }
+        else {
+            desiredKinds.set(parsedCandidate.kind.governs, parsedCandidate.kind);
+            // Additive evolution preserves local declarations that are absent from the recipe.
+            for (const warning of parsedCandidate.warnings) {
+                if (warning.code !== "OKF_WORKFLOW_STATUS_COLLISION" || blockers.some(blocker => blocker.id === target.id && blocker.code === warning.code))
+                    continue;
+                evolutionBlocker(blockers, warning.code, target.id, warning.message, warning.field);
+            }
+        }
+        const desiredVersion = contentVersion(comparableRecipeDoc(candidate, okfVersion));
+        const unchanged = sameInstalledDoc(existing.doc, candidate, okfVersion);
+        // A current identity whose definition disagrees with the stored content is re-stamped only when
+        // that content's definition digest equals the digest of the recipe's own convention: a fresh
+        // stamp is then the honest record. The merge treats lists as sets, so `unchanged` alone would
+        // also re-baseline a local reorder or duplicate.
+        const identityState = recipeStampState(existing.doc, identity);
+        const stamp = unchanged &&
+            identityState === "current" &&
+            conventionStampState(existing.doc) === "diverged" &&
+            definitionDigest(existing.doc) === definitionDigest(target)
+            ? "stale"
+            : identityState;
+        definitions.push({
+            id: target.id,
+            governs: parsedDesired.kind.governs,
+            action: unchanged ? "unchanged" : "update",
+            stamp,
+            expected_version: existing.version,
+            desired_version: desiredVersion,
+            added_paths: unchanged ? [] : merged.addedPaths,
+        });
+        // The write set: a content update (which takes ownership of a foreign stamp), or a stale or
+        // missing stamp on unchanged content. A foreign stamp alone is another recipe's to keep.
+        if (!unchanged)
+            writes.set(target.id, withRecipeStamp(candidate, identity));
+        else if (stamp === "stale" || stamp === "missing")
+            writes.set(target.id, withRecipeStamp(existing.doc, identity));
+        proofs.push({
+            kind: "definition",
+            id: target.id,
+            current_version: existing.version,
+            desired_version: desiredVersion,
+        });
+        if (!unchanged
+            && existing.doc.frontmatter.type === "Convention"
+            && parsedCurrent.ok
+            && parsedCandidate.ok
+            && parsedCurrent.kind.governs === parsedCandidate.kind.governs) {
+            monotonicEvolutionBlockers(parsedCurrent.kind, parsedCandidate.kind, blockers);
+            addedRestrictions.set(parsedCandidate.kind.governs, addedFieldRestrictions(parsedCurrent.kind, parsedCandidate.kind));
+            for (const linkType of addedLinkTypes(parsedCurrent.kind, parsedCandidate.kind))
+                addedLinkTexts.add(linkType);
+        }
+    }
+    const prospectiveRegistry = buildKindRegistry([...prospectiveById.values()], [], { okfVersion });
+    for (const warning of prospectiveRegistry.warnings) {
+        if (warning.code !== "KIND_DUPLICATE_GOVERNS" || !warning.field || !desiredKinds.has(warning.field))
+            continue;
+        evolutionBlocker(blockers, "RECIPE_EVOLUTION_DUPLICATE_GOVERNS", desiredKinds.get(warning.field).id, warning.message, warning.field);
+    }
+    for (const [governs, kind] of desiredKinds) {
+        if (prospectiveRegistry.kinds.get(governs)?.id !== kind.id) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_DUPLICATE_GOVERNS", kind.id, `prospective registry keeps '${prospectiveRegistry.kinds.get(governs)?.id ?? "none"}' as the authority for '${governs}', not '${kind.id}'`, governs);
+        }
+    }
+    const assetDocProof = async (kind, authored) => {
+        const target = recipeDocumentForApply(authored, okfVersion, "1970-01-01T00:00:00.000Z");
+        const wanted = contentVersion(comparableRecipeDoc(target, okfVersion));
+        const existing = await readRecipeDocIfPresent(bundle, target.id);
+        proofs.push({ kind, id: target.id, current_version: existing?.version ?? null, desired_version: wanted });
+        if (!existing) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_ASSET_MISSING", target.id, `recipe asset '${target.id}' is not installed; install the complete recipe with 'recipe add' first`);
+        }
+        else if (!sameInstalledDoc(existing.doc, target, okfVersion)) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_ASSET_CHANGE_UNSUPPORTED", target.id, `recipe evolution does not replace an existing ${kind === "reference" ? "Reference" : "View registry"} asset`);
+        }
+    };
+    for (const reference of recipe.references)
+        await assetDocProof("reference", reference.doc);
+    for (const page of recipe.pages) {
+        await assetDocProof("view-registry", page.registry);
+        const existing = await readBlob(bundle, page.entry);
+        const wantedBytes = new TextEncoder().encode(page.html);
+        const wanted = blobVersion(wantedBytes);
+        proofs.push({ kind: "view-entry", id: page.entry, current_version: existing?.version ?? null, desired_version: wanted });
+        if (!existing) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_ASSET_MISSING", page.entry, `recipe View entry '${page.entry}' is not installed; install the complete recipe with 'recipe add' first`);
+        }
+        else if (existing.version !== wanted || existing.contentType !== resolveContentType(page.entry)) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_ASSET_CHANGE_UNSUPPORTED", page.entry, "recipe evolution does not replace an existing active View entry without an atomic pair-update authority");
+        }
+    }
+    const changingKinds = definitions
+        .filter((definition) => definition.action === "update")
+        .map((definition) => desiredKinds.get(definition.governs))
+        .filter((kind) => kind !== undefined);
+    let instancesChecked = 0;
+    const instanceProofs = [];
+    if (changingKinds.length > 0) {
+        const skippedInstances = [];
+        const docs = await query(bundle, {}, { onSkip: (skipped) => skippedInstances.push(skipped) });
+        for (const skipped of skippedInstances) {
+            evolutionBlocker(blockers, "RECIPE_EVOLUTION_INSTANCE_UNREADABLE", skipped.id, `cannot prove instance compatibility while '${skipped.id}' is unreadable: ${skipped.reason}`);
+        }
+        for (const kind of changingKinds) {
+            const added = addedRestrictions.get(kind.governs);
+            // One blocker per added restriction, naming its violating documents, keeps a large bundle's
+            // plan bounded; every scanned instance is still bound into the token by its proof.
+            const violations = new Map();
+            for (const doc of docs) {
+                if (String(doc.frontmatter.type) !== kind.governs)
+                    continue;
+                instancesChecked += 1;
+                instanceProofs.push({
+                    kind: "instance",
+                    id: doc.id,
+                    current_version: contentVersion(doc),
+                });
+                const stored = validateAgainstKind(doc, kind);
+                const projected = projectKindValidationWarnings(okfVersion, kind, stored);
+                for (const [index, warning] of projected.entries()) {
+                    // Route on the stored field name, which is how the convention declares the restriction.
+                    const field = stored[index].field ?? "";
+                    const restriction = warning.code === "KIND_FIELD_TYPE" && added?.types.has(field)
+                        ? `fields.types.${field}`
+                        : (warning.code === "KIND_FIELD_VALUE" || warning.code === "KIND_FIELD_ARITY") && added?.values.has(field)
+                            ? `fields.values.${field}`
+                            : undefined;
+                    if (restriction === undefined) {
+                        evolutionBlocker(blockers, "RECIPE_EVOLUTION_INSTANCE_INVALID", doc.id, warning.message, warning.field);
+                        continue;
+                    }
+                    const entry = violations.get(restriction) ?? { field, docs: new Map() };
+                    if (!entry.docs.has(doc.id))
+                        entry.docs.set(doc.id, warning.message);
+                    violations.set(restriction, entry);
+                }
+            }
+            for (const [restriction, { field, docs: violating }] of violations) {
+                const ids = [...violating.keys()].sort();
+                const named = ids.slice(0, RESTRICTION_BLOCKER_DOC_CAP).join(", ");
+                const more = ids.length > RESTRICTION_BLOCKER_DOC_CAP ? `, and ${ids.length - RESTRICTION_BLOCKER_DOC_CAP} more` : "";
+                const declared = restriction.startsWith("fields.types.")
+                    ? `type '${added.types.get(field)}'`
+                    : `allowed values [${added.values.get(field).join(", ")}]`;
+                evolutionBlocker(blockers, "RECIPE_EVOLUTION_RESTRICTION_VIOLATED", kind.id, `adding ${declared} to '${field}' for '${kind.governs}' would make ${ids.length} existing document(s) invalid: ${named}${more}; fix them first (e.g. ${ids[0]}: ${violating.get(ids[0])})`, restriction);
+            }
+        }
+        if (addedLinkTexts.size > 0) {
+            const proven = new Set(instanceProofs.map((proof) => proof.id));
+            for (const doc of linkTypeAdditionBlockers(docs, addedLinkTexts, currentRegistry, prospectiveRegistry, blockers)) {
+                if (proven.has(doc.id))
+                    continue;
+                proven.add(doc.id);
+                instancesChecked += 1;
+                instanceProofs.push({ kind: "instance", id: doc.id, current_version: contentVersion(doc) });
+            }
+        }
+    }
+    proofs.push(...instanceProofs.sort((a, b) => a.id.localeCompare(b.id)));
+    definitions.sort((a, b) => a.id.localeCompare(b.id));
+    proofs.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+    blockers.sort((a, b) => `${a.code}:${a.id}:${a.field ?? ""}`.localeCompare(`${b.code}:${b.id}:${b.field ?? ""}`));
+    // Each definition's stamp state and the stamp the apply writes (the recipe's source digest)
+    // are bound into the token, so a stamp that changes after the plan invalidates it.
+    const token = evolutionPlanToken({
+        recipe: { id: recipe.id, version: recipe.version, source: recipe.source, source_digest: identity.source_digest },
+        okfVersion,
+        definitions,
+        proofs,
+        blockers,
+    });
+    const updates = definitions.filter((definition) => definition.action === "update").length;
+    const unchanged = definitions.filter((definition) => definition.action === "unchanged").length;
+    const missing = definitions.filter((definition) => definition.action === "missing").length;
+    const stampWrites = definitions.filter((definition) => writes.has(definition.id) && definition.action !== "update").length;
+    return {
+        plan: {
+            recipe: "evolution plan",
+            id: recipe.id,
+            version: recipe.version,
+            source: recipe.source,
+            okf_version: okfVersion,
+            ready: blockers.length === 0,
+            changed: updates > 0,
+            writes: writes.size,
+            plan_token: token,
+            definitions,
+            counts: {
+                definitions: definitions.length,
+                updates,
+                stamp_writes: stampWrites,
+                unchanged,
+                missing,
+                instances_checked: instancesChecked,
+                blockers: blockers.length,
+            },
+            blockers,
+        },
+        writes,
+    };
+}
+/** Build a read-only, state-bound preflight for installed recipe convention evolution. */
+export async function planRecipeEvolution(bundle, recipe) {
+    return (await prepareRecipeEvolution(bundle, recipe)).plan;
+}
+/** Apply only the exact ready plan the caller previously observed. */
+export async function applyRecipeEvolution(bundle, recipe, expectedPlanToken, options = {}) {
+    const { actor } = options;
+    const prepared = await prepareRecipeEvolution(bundle, recipe);
+    const { plan } = prepared;
+    if (plan.plan_token !== expectedPlanToken) {
+        throw new RecipeEvolutionPlanChanged(expectedPlanToken, plan.plan_token);
+    }
+    if (!plan.ready) {
+        throw new RecipeEvolutionBlocked(plan.id, plan.blockers);
+    }
+    const completed = [];
+    const pending = plan.definitions.filter((definition) => prepared.writes.has(definition.id)).map((definition) => definition.id);
+    for (const definition of plan.definitions) {
+        const planned = prepared.writes.get(definition.id);
+        if (planned === undefined) {
+            completed.push({ id: definition.id, changed: false, stamped: false, version: definition.expected_version });
+            continue;
+        }
+        const now = new Date().toISOString();
+        const desired = recipeDocumentForApply(planned, plan.okf_version, now);
+        try {
+            const result = await mutateDocument({
+                bundle,
+                id: definition.id,
+                mode: "replace-document",
+                onAbsent: "fail",
+                expectedVersion: definition.expected_version,
+                maxAttempts: 1,
+                registry: RECIPE_EVOLUTION_WRITE_REGISTRY,
+                strict: false,
+                // Recipe definitions remain source-comparable; like initial recipe installation, evolution
+                // explicitly opts out of seeding provenance when the installed definition has none.
+                seedGenerationClock: false,
+                // Evolution preserves source-comparable attribution; the backend still records its writer.
+                persistActor: false,
+                actor,
+                now: () => now,
+                buildCandidate: (_existing, context) => {
+                    if (context.okfVersion !== plan.okf_version) {
+                        throw new RecipeEditionChanged(plan.okf_version, context.okfVersion, "evolution");
+                    }
+                    return { frontmatter: { ...desired.frontmatter }, body: desired.body };
+                },
+            });
+            completed.push({
+                id: definition.id,
+                changed: definition.action === "update" && result.changed,
+                stamped: true,
+                version: result.version,
+            });
+            pending.shift();
+        }
+        catch (error) {
+            if (error instanceof RecipeEditionChanged) {
+                throw new RecipeEvolutionInterrupted("edition_changed", error.message, completed, pending, error);
+            }
+            if (error instanceof VersionConflict || error instanceof DocumentNotFoundError) {
+                throw new RecipeEvolutionInterrupted("race", `recipe evolution lost its exact-version race at '${definition.id}'; inspect a fresh plan and resume`, completed, pending, error);
+            }
+            // An actor rejection keeps its own typed error for the presenting boundary (a corrected
+            // spelling), not a post-preflight policy refusal; every other typed input rejection is one.
+            if (error instanceof InvalidInputError && !(error instanceof OkfActorError)) {
+                throw new RecipeEvolutionInterrupted("write_policy", `recipe evolution write policy rejected '${definition.id}' after preflight: ${error.message}`, completed, pending, error);
+            }
+            throw new RecipeEvolutionInterrupted("other", error instanceof Error ? error.message : String(error), completed, pending, error);
+        }
+    }
+    const updated = completed.filter((definition) => definition.changed).length;
+    const stamped = completed.filter((definition) => definition.stamped && !definition.changed).length;
+    const written = updated + stamped;
+    let postcondition;
+    try {
+        postcondition = await prepareRecipeEvolution(bundle, recipe);
+    }
+    catch (error) {
+        throw new RecipeEvolutionPostcondition("unverifiable", `recipe evolution wrote ${written} definition(s), but its postcondition could not be verified: ${error instanceof Error ? error.message : String(error)}`, completed, { cause: error });
+    }
+    if (!postcondition.plan.ready || postcondition.plan.changed || postcondition.plan.writes > 0) {
+        throw new RecipeEvolutionPostcondition("changed", `recipe evolution wrote ${written} definition(s), but the bundle changed (a definition or its stamp) before the postcondition check; a fresh recipe evolve plan shows the current state`, completed, { blockers: postcondition.plan.blockers, postcondition_plan: postcondition.plan.plan_token });
+    }
+    return {
+        recipe: updated > 0 ? "evolved" : stamped > 0 ? "stamped" : "already current",
+        id: plan.id,
+        version: plan.version,
+        source: plan.source,
+        changed: written > 0,
+        plan_token: plan.plan_token,
+        definitions: completed,
+        counts: { updated, stamped, unchanged: completed.length - written },
+    };
+}
+//# sourceMappingURL=evolution.js.map