@superbee/core 0.2.0-pre.32 → 0.2.0-pre.34

package/dist/recipe-lifecycle/retirement-apply.js

@@ -0,0 +1,165 @@
+/** One explicitly selected actual-source retirement stage; storage remains the commit authority. */
+import { InvalidInputError } from "../errors.js";
+import { compareStorageKeys } from "../paths.js";
+import { VersionConflict } from "../versioning.js";
+import { backendFor } from "../bundle-ops.js";
+import { DocumentNotFoundError, mutateDocument } from "../document-mutation.js";
+import { captureInventoryGuardRequest, INVENTORY_GUARD_DOMAIN, InventoryGuardConflict, InventoryGuardUnsupported, inventoryGuardFor } from "../inventory-guard.js";
+import { buildKindRegistry } from "../kinds.js";
+import { recipePreflightDigest } from "../recipe-set-preflight.js";
+import { prepareRecipeRetirementStage } from "./evolution.js";
+import { inspectRecipeInstallTarget, recipeDocumentForApply } from "./install.js";
+import { definitionDigest } from "./stamp.js";
+import { prepareRecipeDeclarationRetirement } from "./retirement.js";
+export class RecipeRetirementApplyError extends Error {
+    reason;
+    plan;
+    completed = [];
+    failed;
+    pending_definitions;
+    constructor(reason, plan, cause) {
+        super(`Recipe retirement ${reason}; inspect a fresh stage plan before continuing.`, cause === undefined ? undefined : { cause });
+        this.name = "RecipeRetirementApplyError";
+        this.reason = reason;
+        this.plan = plan;
+        this.failed = { id: plan.next_definition, reason };
+        this.pending_definitions = [...(plan.next_definition ? [plan.next_definition] : []), ...plan.pending_definitions];
+    }
+}
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+async function prepareStage(bundle, source, options) {
+    source = structuredClone(source);
+    options = { ...options };
+    if (Object.hasOwn(options, "consumerEvidence")) {
+        try {
+            options.consumerEvidence = structuredClone(options.consumerEvidence);
+        }
+        catch { /* The owning preflight returns unsupported input as a refusal. */ }
+    }
+    const bound = { root: bundle.root, backend: backendFor(bundle) };
+    let target, guardIssue;
+    try {
+        target = await inventoryGuardFor(bound.backend).observeTarget();
+    }
+    catch (error) {
+        guardIssue = error instanceof Error ? error.message : String(error);
+    }
+    const prepared = await prepareRecipeDeclarationRetirement(bound, source, options);
+    const report = prepared.report;
+    const ids = [...new Set(report.declarations.map(row => row.definition))].sort(compareStorageKeys);
+    const next = options.definitionId ?? ids[0] ?? null;
+    const selected = report.declarations.filter(row => row.definition === next);
+    const blockers = [...report.blockers];
+    const block = (code, message) => blockers.push({ code, id: next ?? report.id, message });
+    if (options.scope !== INVENTORY_GUARD_DOMAIN)
+        block("RETIREMENT_SCOPE_REQUIRED", "Explicit exact-root cooperating-local-writers-v1, local-only and consumer-unassessed limits are required.");
+    if (!next || !selected.length)
+        block("RETIREMENT_NO_ELIGIBLE_STAGE", "No eligible deprecated omission exists in the selected definition.");
+    if (!report.local.complete || report.local.issues.length)
+        block("RETIREMENT_LOCAL_UNKNOWN", "Complete readable stable local inventory is required.");
+    if (selected.some(row => row.usage.some(usage => usage.unknown || usage.count > 0)))
+        block("RETIREMENT_DECLARATION_USED_OR_UNKNOWN", "The selected definition has used or unknown retired coordinates.");
+    if (guardIssue || !target)
+        block("RETIREMENT_GUARD_UNAVAILABLE", guardIssue ?? "The actual backend has no supported guard.");
+    if (target && (target.edition !== report.local.okf_version || target.root_version !== report.local.root_index_version))
+        block("RETIREMENT_TARGET_CHANGED", "Guard target metadata differs from the inspected local scope.");
+    const inventory = report.local.inventory.filter((row) => row.version !== null).sort((a, b) => compareStorageKeys(a.id, b.id));
+    let candidate;
+    if (next && selected.length && report.local.complete) {
+        try {
+            const stage = await prepareRecipeRetirementStage(bound, prepared.source, next, selected);
+            blockers.push(...stage.plan.blockers);
+            candidate = stage.writes.get(next);
+            if (!candidate)
+                block("RETIREMENT_STAGE_UNCHANGED", "No actual-source retirement write was prepared.");
+            if (stage.plan.definitions.some(row => row.id === next && row.expected_version !== prepared.snapshots.get(next)?.version))
+                block("RETIREMENT_TARGET_CHANGED", "The stage target changed after the scan.");
+        }
+        catch (error) {
+            block("RETIREMENT_STAGE_UNAVAILABLE", error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (Object.hasOwn(options, "consumerEvidence")) {
+        if (report.consumers.status === "partial" || report.consumers.status === "refused" || report.consumers.binding_issues.length || report.consumers.result?.verdict !== "valid")
+            block("RETIREMENT_CONSUMER_EVIDENCE_UNSUPPORTED", "Supplied consumer evidence must be valid and exactly bound; it cannot be downgraded to unassessed.");
+        // B assessed the final source. It certifies this stage only when all other owned concepts
+        // already match, and this actual evolution-owned candidate matches its assessed projection.
+        const owned = prepared.installation ? [...prepared.installation.docs, ...prepared.installation.connectors.map(row => row.doc), ...prepared.installation.references.map(row => row.doc), ...prepared.installation.pages.map(row => row.registry)] : [];
+        if (!candidate || !owned.length || owned.some(wanted => {
+            const actual = wanted.id === next ? candidate : prepared.snapshots.get(wanted.id)?.doc;
+            if (!actual || !prepared.installation)
+                return true;
+            const inspection = inspectRecipeInstallTarget(actual, wanted, prepared.installation);
+            return !inspection.sameContent || inspection.stamp !== "current" || inspection.stampIntegrity !== "current";
+        }))
+            block("RETIREMENT_STAGE_CONSUMER_UNREPRESENTABLE", "Final-source evidence does not represent this concrete intermediate stage; supply an actual staged source/evidence or inspect a later stage.");
+    }
+    if (target) {
+        try {
+            if (recipePreflightDigest(await inventoryGuardFor(bound.backend).observeTarget()) !== recipePreflightDigest(target))
+                block("RETIREMENT_TARGET_CHANGED", "Guard target changed while planning.");
+        }
+        catch (error) {
+            block("RETIREMENT_GUARD_UNAVAILABLE", error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (target && candidate && next) {
+        try {
+            captureInventoryGuardRequest({ target, domain: INVENTORY_GUARD_DOMAIN, inventory, id: next,
+                expectedVersion: prepared.snapshots.get(next).version, doc: candidate });
+        }
+        catch (error) {
+            block("RETIREMENT_GUARD_UNAVAILABLE", error instanceof Error ? error.message : String(error));
+        }
+    }
+    blockers.sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));
+    const plan = {
+        recipe: "declaration retirement apply", id: report.id, version: report.version, source: report.source, source_digest: report.source_digest,
+        scope: INVENTORY_GUARD_DOMAIN, ready_for_next_stage: blockers.length === 0,
+        next_definition: next, pending_definitions: ids.filter(id => id !== next), declarations: selected, blockers,
+        ...(target ? { target } : {}), consumers: report.consumers, external_consumers: report.external_consumers,
+    };
+    if (plan.ready_for_next_stage && candidate) {
+        plan.plan_token = `retirement-apply/v1:${recipePreflightDigest({ plan, inventory, observation_digest: report.local.observation_digest,
+            candidate: definitionDigest(candidate), stamp: candidate.frontmatter.x_recipe })}`;
+    }
+    return { plan, bundle: bound, candidate, inventory, expectedVersion: next ? prepared.snapshots.get(next)?.version : undefined };
+}
+export async function planRecipeDeclarationRetirementApply(bundle, source, options = {}) {
+    return (await prepareStage(bundle, source, options)).plan;
+}
+export async function applyRecipeDeclarationRetirement(bundle, source, expectedApplyToken, options = {}) {
+    options = { ...options };
+    const stage = await prepareStage(bundle, source, options);
+    const { plan } = stage;
+    if (!plan.ready_for_next_stage)
+        throw new RecipeRetirementApplyError("blocked", plan);
+    if (!/^retirement-apply\/v1:sha256:[0-9a-f]{64}$/.test(expectedApplyToken) || expectedApplyToken !== plan.plan_token)
+        throw new RecipeRetirementApplyError("plan_changed", plan);
+    const now = new Date().toISOString();
+    const desired = recipeDocumentForApply(stage.candidate, plan.target.edition, now);
+    try {
+        const result = await mutateDocument({ bundle: stage.bundle, id: plan.next_definition, mode: "replace-document", onAbsent: "fail",
+            expectedVersion: stage.expectedVersion, maxAttempts: 1, registry: buildKindRegistry([], [], { okfVersion: plan.target.edition }), strict: false,
+            seedGenerationClock: false, persistActor: false, actor: options.actor, now: () => now,
+            inventoryGuard: { target: plan.target, domain: plan.scope, inventory: stage.inventory },
+            buildCandidate: (_existing, context) => {
+                if (context.okfVersion !== plan.target.edition)
+                    throw new InventoryGuardConflict("edition");
+                return { frontmatter: desired.frontmatter, body: desired.body };
+            },
+        });
+        return { recipe: "declaration retirement apply", id: plan.id, version: plan.version, scope: plan.scope,
+            completed: [{ id: plan.next_definition, version: result.version, changed: result.changed, stamped: true }],
+            pending_definitions: plan.pending_definitions, complete: plan.pending_definitions.length === 0, refresh_needed: plan.pending_definitions.length > 0,
+            consumers: plan.consumers, external_consumers: plan.external_consumers };
+    }
+    catch (error) {
+        // These owning typed refusals establish that publication did not occur. Keep their
+        // authority; only an unclassified persistence failure has an uncertain outcome.
+        if (error instanceof InventoryGuardUnsupported || error instanceof InvalidInputError || error instanceof VersionConflict || error instanceof DocumentNotFoundError)
+            throw error;
+        throw new RecipeRetirementApplyError(error instanceof InventoryGuardConflict ? "interrupted" : "outcome_unknown", plan, error);
+    }
+}
+//# sourceMappingURL=retirement-apply.js.map

package/dist/recipe-lifecycle/retirement-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retirement-apply.js","sourceRoot":"","sources":["../../src/recipe-lifecycle/retirement-apply.ts"],"names":[],"mappings":"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"}

package/dist/recipe-lifecycle/retirement.d.ts

@@ -0,0 +1,89 @@
+import { type LoadedRecipe } from "../recipes.js";
+import { type PreflightResult } from "../recipe-set-preflight.js";
+import type { Bundle, ReadResult } from "../types.js";
+import { type PreparedRecipeInstall } from "./install.js";
+export interface RetirementIssue {
+    code: string;
+    id: string;
+    message: string;
+    field?: string;
+}
+export interface RetirementDeclaration {
+    definition: string;
+    kind: string;
+    coordinate: "field" | "value" | "link";
+    name: string;
+    value?: string;
+    installed_version: string;
+    proposed_definition_digest: string;
+    usage: Array<{
+        id: string;
+        count: number;
+        unknown?: true;
+    }>;
+}
+export interface RecipeDeclarationRetirementPlan {
+    recipe: "declaration retirement inspection";
+    id: string;
+    version: string;
+    source: string;
+    source_digest: string;
+    scope: "observed-local-concepts-and-supplied-structural-consumers";
+    can_apply: false;
+    apply_blocker: "RETIREMENT_APPLY_NOT_IMPLEMENTED";
+    analysis: "complete" | "partial" | "refused";
+    declarations: RetirementDeclaration[];
+    blockers: RetirementIssue[];
+    local: {
+        verdict: "complete-clean" | "used" | "unknown";
+        complete: boolean;
+        consistency: "observed-stable-reads-not-an-atomic-snapshot";
+        target_root: string;
+        bundle_id?: string;
+        okf_version: string;
+        root_index_version: string | null;
+        initial_ids: string[];
+        final_ids: string[];
+        inventory: Array<{
+            id: string;
+            version: string | null;
+        }>;
+        observation_digest: string;
+        issues: RetirementIssue[];
+    };
+    consumers: {
+        status: "unassessed" | "valid" | "partial" | "refused";
+        scope: "supplied-declared-structural-only";
+        model: "final-selected-source-hypothesis";
+        evidence_digest?: string;
+        binding_issues: Array<{
+            level: "partial" | "refused";
+            code: string;
+            at: string;
+        }>;
+        result?: PreflightResult;
+        unsupported_semantics: readonly ["enum-value-compatibility", "type-compatibility", "write-intent-compatibility"];
+    };
+    external_consumers: "unknown-unenumerated-offline-and-arbitrary-code";
+    proposed_definitions: Array<{
+        id: string;
+        definition_digest: string;
+        hypothetical_content_version: string;
+    }>;
+}
+/** Internal reusable preparation for future guarded lifecycle application. The report alone
+ * remains non-authoritative; this data carries no permission or committing operation. */
+export interface PreparedRecipeDeclarationRetirement {
+    report: RecipeDeclarationRetirementPlan;
+    source: LoadedRecipe;
+    installation?: PreparedRecipeInstall;
+    snapshots: ReadonlyMap<string, ReadResult>;
+    bundle: Bundle;
+}
+export declare function prepareRecipeDeclarationRetirement(bundle: Bundle, recipe: LoadedRecipe, options?: {
+    consumerEvidence?: unknown;
+}): Promise<PreparedRecipeDeclarationRetirement>;
+export declare function planRecipeDeclarationRetirement(bundle: Bundle, source: LoadedRecipe, options?: {
+    consumerEvidence?: unknown;
+}): Promise<RecipeDeclarationRetirementPlan>;
+//# sourceMappingURL=retirement.d.ts.map

package/dist/recipe-lifecycle/retirement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retirement.d.ts","sourceRoot":"","sources":["../../src/recipe-lifecycle/retirement.ts"],"names":[],"mappings":"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"}

package/dist/recipe-lifecycle/retirement.js

@@ -0,0 +1,347 @@
+/** Read-only retirement evidence. No plan returned here is an instruction or token for mutation. */
+import { backendFor, readBundleOkfVersion, readDocVersioned } from "../bundle-ops.js";
+import { declaredBundleId, BUNDLE_NAME_DOC_ID } from "../dependencies.js";
+import { parseMarkdown } from "../frontmatter.js";
+import { buildKindRegistry, isConventionId, kindDeprecationProblems, parseConventionDoc, inspectKindDeprecatedUsage } from "../kinds.js";
+import { isOkfRecord, okfValuesEqual } from "../okf-authored-values.js";
+import { parseRecipeFiles } from "../recipes.js";
+import { preflightRecipeSet, recipePreflightDigest } from "../recipe-set-preflight.js";
+import { contentVersion } from "../versioning.js";
+import { materializeRecipeForEdition, prepareRecipeInstall, sameInstalledDoc } from "./install.js";
+import { planRecipeEvolution } from "./evolution.js";
+import { conventionStampState, definitionDigest, readRecipeStamp, recipeSourceDigest } from "./stamp.js";
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const sorted = (ids) => [...ids].sort(compare);
+const record = (value) => isOkfRecord(value) ? value : {};
+const own = (value, key) => Object.hasOwn(value, key) ? value[key] : undefined;
+function put(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, configurable: true, writable: true });
+}
+/** Restore only each approved omission for the existing additive engine to inspect every OTHER
+ * change. This comparison recipe is never returned as an apply plan or passed to an apply API. */
+function restoreOmission(target, current, coordinate, name, value) {
+    const child = (parent, key) => {
+        const next = { ...record(own(parent, key)) };
+        put(parent, key, next);
+        return next;
+    };
+    const restoreMap = (parent, key, previous, field) => {
+        const old = record(previous);
+        if (!Object.hasOwn(old, field))
+            return;
+        const next = child(parent, key);
+        if (!Object.hasOwn(next, field))
+            put(next, field, structuredClone(old[field]));
+    };
+    const append = (parent, key, entry) => {
+        const list = own(parent, key);
+        put(parent, key, [...(Array.isArray(list) ? list : []), structuredClone(entry)]);
+    };
+    const currentFields = record(current.frontmatter.fields);
+    const fields = child(target.frontmatter, "fields");
+    const deprecated = child(target.frontmatter, "deprecated");
+    if (coordinate === "field") {
+        append(fields, "optional", name);
+        for (const key of ["values", "types", "descriptions", "value_descriptions"])
+            restoreMap(fields, key, own(currentFields, key), name);
+        append(deprecated, "fields", name);
+        restoreMap(deprecated, "values", record(current.frontmatter.deprecated).values, name);
+    }
+    else if (coordinate === "value") {
+        const values = child(fields, "values");
+        const original = own(record(currentFields.values), name);
+        const member = Array.isArray(original) ? original.find(v => String(v) === value) : value;
+        append(values, name, member);
+        const descriptions = record(own(record(currentFields.value_descriptions), name));
+        if (Object.hasOwn(descriptions, value))
+            restoreMap(child(fields, "value_descriptions"), name, descriptions, value);
+        append(child(deprecated, "values"), name, value);
+    }
+    else {
+        restoreMap(target.frontmatter, "links", current.frontmatter.links, name);
+        restoreMap(target.frontmatter, "link_descriptions", current.frontmatter.link_descriptions, name);
+        append(deprecated, "links", name);
+    }
+}
+function candidateOwned(prepared) {
+    return [...prepared.docs, ...prepared.connectors.map(c => c.doc), ...prepared.references.map(r => r.doc)];
+}
+/** Optional supplied evidence is evaluated by the existing preflight, then bound to THIS source
+ * and this observed local store. A plausible but unrelated preflight cannot certify this report. */
+async function consumersFor(supplied, present, source, prepared, snapshots, local) {
+    const out = { status: "unassessed", scope: "supplied-declared-structural-only", model: "final-selected-source-hypothesis", binding_issues: [],
+        unsupported_semantics: ["enum-value-compatibility", "type-compatibility", "write-intent-compatibility"] };
+    if (!present)
+        return out;
+    const issue = (level, code, at) => { out.binding_issues.push({ level, code, at }); };
+    out.result = await preflightRecipeSet(supplied);
+    try {
+        out.evidence_digest = recipePreflightDigest(supplied);
+    }
+    catch {
+        issue("refused", "RETIREMENT_EVIDENCE_SHAPE", "input");
+    }
+    if (out.result.issues.some(i => i.code === "INPUT_SHAPE")) {
+        out.status = "refused";
+        return out;
+    }
+    const input = supplied;
+    if (!prepared || local.okf_version !== "0.2")
+        issue("partial", "RETIREMENT_PREFLIGHT_EDITION_UNSUPPORTED", local.okf_version);
+    if (!local.complete)
+        issue("partial", "RETIREMENT_LOCAL_INVENTORY_UNKNOWN", "local");
+    const providers = input.selected.filter(s => s.recipeId === source.id && s.release === source.version);
+    if (providers.length !== 1)
+        issue("refused", "RETIREMENT_CANDIDATE_PROVIDER", source.id);
+    const provider = providers[0];
+    if (provider && !provider.artifact)
+        issue("partial", "RETIREMENT_CANDIDATE_ARTIFACT_UNAVAILABLE", provider.key);
+    else if (provider?.artifact) {
+        const parsed = parseRecipeFiles(provider.artifact.files, "retirement:supplied-candidate", { okfVersion: "0.2" });
+        if (!parsed.ok || recipeSourceDigest(parsed.recipe) !== recipeSourceDigest(source))
+            issue("refused", "RETIREMENT_CANDIDATE_SOURCE_MISMATCH", provider.key);
+    }
+    if (provider && prepared) {
+        const observations = input.observations.filter(o => o.provider === provider.key && o.scope === "local");
+        if (observations.length !== 1)
+            issue(observations.length ? "refused" : "partial", "RETIREMENT_CANDIDATE_OBSERVATION", provider.key);
+        for (const observed of observations) {
+            if (observed.availability !== "available" || !observed.complete) {
+                issue("partial", "RETIREMENT_CANDIDATE_OBSERVATION_UNKNOWN", observed.id);
+                continue;
+            }
+            const expected = candidateOwned(prepared);
+            if (!okfValuesEqual(sorted(observed.definitions.map(d => d.id)), sorted(expected.map(d => d.id))))
+                issue("refused", "RETIREMENT_CANDIDATE_DEFINITION_SET", observed.id);
+            for (const def of observed.definitions) {
+                const wanted = expected.find(d => d.id === def.id);
+                try {
+                    const actual = { id: def.id, ...parseMarkdown(def.bytes, def.id, { okfVersion: "0.2" }) };
+                    if (!wanted || definitionDigest(actual) !== definitionDigest(wanted))
+                        issue("refused", "RETIREMENT_CANDIDATE_DEFINITION", `${observed.id}:${def.id}`);
+                }
+                catch {
+                    issue("refused", "RETIREMENT_CANDIDATE_DEFINITION", `${observed.id}:${def.id}`);
+                }
+            }
+        }
+        const expected = new Map([...snapshots].map(([id, read]) => [`${id}.md`, read.doc]));
+        for (const doc of [...candidateOwned(prepared), ...prepared.pages.map(p => p.registry)])
+            expected.set(`${doc.id}.md`, doc);
+        const placements = (input.placementInventories ?? []).filter(p => p.scope === "local");
+        if (placements.length !== 1)
+            issue(placements.length ? "refused" : "partial", "RETIREMENT_LOCAL_PLACEMENT", "local");
+        for (const placement of placements) {
+            if (placement.availability !== "available" || !placement.complete)
+                issue("partial", "RETIREMENT_LOCAL_PLACEMENT_UNKNOWN", placement.id);
+            const docs = placement.files.filter(f => f.path.endsWith(".md"));
+            if (!okfValuesEqual(sorted(docs.map(f => f.path)), sorted([...expected.keys()])))
+                issue("refused", "RETIREMENT_LOCAL_PLACEMENT_SET", placement.id);
+            for (const file of docs) {
+                const wanted = expected.get(file.path);
+                try {
+                    const actual = { id: file.path.slice(0, -3), ...parseMarkdown(file.bytes, undefined, { okfVersion: "0.2" }) };
+                    const candidate = candidateOwned(prepared).some(d => `${d.id}.md` === file.path);
+                    if (!wanted || (candidate ? !sameInstalledDoc(actual, wanted, "0.2") : contentVersion(actual) !== contentVersion(wanted)))
+                        issue("refused", "RETIREMENT_LOCAL_PLACEMENT_CONTENT", file.path);
+                }
+                catch {
+                    issue("refused", "RETIREMENT_LOCAL_PLACEMENT_CONTENT", file.path);
+                }
+            }
+            // Concept inventory does not establish ordinary blob bytes. Preserve that missing scope.
+            if (placement.files.some(f => !f.path.endsWith(".md")))
+                issue("partial", "RETIREMENT_BLOB_BINDING_UNSUPPORTED", placement.id);
+        }
+    }
+    for (const row of [...input.observations, ...(input.placementInventories ?? [])].filter(row => row.scope === "local")) {
+        if (!row.observedVersion)
+            issue("partial", "RETIREMENT_OBSERVATION_VERSION_UNKNOWN", row.id);
+        else if (row.observedVersion !== local.observation_digest)
+            issue("refused", "RETIREMENT_OBSERVATION_VERSION_MISMATCH", row.id);
+        if (row.bundleId && row.bundleId !== local.bundle_id)
+            issue("refused", "RETIREMENT_BUNDLE_IDENTITY", row.id);
+    }
+    out.binding_issues.sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));
+    out.status = out.result.verdict === "refused" || out.binding_issues.some(i => i.level === "refused") ? "refused"
+        : out.result.verdict === "partial" || out.binding_issues.length ? "partial" : input.consumers.length ? "valid" : "unassessed";
+    return out;
+}
+export async function prepareRecipeDeclarationRetirement(bundle, recipe, options = {}) {
+    const source = structuredClone(recipe);
+    const backend = backendFor(bundle), selected = { root: bundle.root, backend };
+    const evidencePresent = Object.hasOwn(options, "consumerEvidence");
+    let evidence = options.consumerEvidence;
+    try {
+        if (evidencePresent)
+            evidence = structuredClone(evidence);
+    }
+    catch { /* Existing preflight returns the shape refusal. */ }
+    const issues = [], blockers = [];
+    const snapshots = new Map();
+    const inventory = [];
+    let initial = [], final = [], indexVersion = null, edition = "0.1";
+    const unknown = (code, id, error) => { issues.push({ code, id, message: error instanceof Error ? error.message : String(error) }); };
+    try {
+        indexVersion = (await backend.readReserved("", "index.md"))?.version ?? null;
+        edition = await readBundleOkfVersion(selected) ?? "0.1";
+    }
+    catch (error) {
+        unknown("RETIREMENT_EDITION_UNREADABLE", "index.md", error);
+    }
+    try {
+        initial = sorted(await backend.list());
+    }
+    catch (error) {
+        unknown("RETIREMENT_INVENTORY_UNAVAILABLE", "*", error);
+    }
+    if (new Set(initial).size !== initial.length)
+        unknown("RETIREMENT_INVENTORY_AMBIGUOUS", "*", "duplicate concept IDs");
+    for (const id of [...new Set(initial)]) {
+        try {
+            const read = await readDocVersioned(selected, id);
+            if (read.doc.id !== id || typeof read.version !== "string" || !read.version)
+                throw new Error("backend returned an invalid concept identity/version");
+            snapshots.set(id, read);
+            inventory.push({ id, version: read.version });
+        }
+        catch (error) {
+            inventory.push({ id, version: null });
+            unknown("RETIREMENT_CONCEPT_UNREADABLE", id, error);
+        }
+    }
+    const currentDocs = [...snapshots.values()].map(r => r.doc);
+    const registry = buildKindRegistry(currentDocs.filter(d => isConventionId(d.id) && d.frontmatter.type === "Convention"), [], { okfVersion: edition });
+    for (const warning of registry.warnings)
+        blockers.push({ code: warning.code, id: "conventions/", message: warning.message, ...(warning.field ? { field: warning.field } : {}) });
+    const declarations = [];
+    let prepared;
+    try {
+        if (edition !== "0.1" && edition !== "0.2")
+            throw new Error(`unsupported bundle edition '${edition}'`);
+        prepared = prepareRecipeInstall(source, { okfVersion: edition, now: "1970-01-01T00:00:00.000Z" });
+        const comparison = materializeRecipeForEdition(structuredClone(source), edition);
+        const proposed = buildKindRegistry(prepared.docs, [], { okfVersion: edition });
+        for (const warning of proposed.warnings)
+            blockers.push({ code: warning.code, id: source.id, message: warning.message, ...(warning.field ? { field: warning.field } : {}) });
+        for (const target of comparison.docs) {
+            const installed = snapshots.get(target.id), current = installed?.doc;
+            const next = parseConventionDoc(target, { okfVersion: edition });
+            if (!current || !installed || !next.ok) {
+                blockers.push({ code: "RETIREMENT_DEFINITION_UNAVAILABLE", id: target.id, message: "retirement requires a readable installed and proposed convention" });
+                continue;
+            }
+            const parsed = parseConventionDoc(current, { okfVersion: edition });
+            if (!parsed.ok || current.frontmatter.type !== "Convention" || parsed.kind.governs !== next.kind.governs) {
+                blockers.push({ code: "RETIREMENT_DEFINITION_IDENTITY", id: target.id, message: "installed and proposed convention identities differ" });
+                continue;
+            }
+            const kind = parsed.kind;
+            if (readRecipeStamp(current)?.id !== source.id || conventionStampState(current) !== "current") {
+                blockers.push({ code: "RETIREMENT_OWNERSHIP_UNPROVEN", id: target.id, message: "an unchanged readable same-recipe ownership stamp is required" });
+                continue;
+            }
+            if (kindDeprecationProblems(kind, registry).length)
+                continue;
+            const retiredFields = new Set();
+            const add = (coordinate, name, value) => {
+                const candidate = { definition: target.id, kind: kind.governs, coordinate, name, ...(value === undefined ? {} : { value }), installed_version: installed.version,
+                    proposed_definition_digest: definitionDigest(prepared.docs.find(d => d.id === target.id)), usage: [] };
+                for (const doc of currentDocs.filter(d => d.frontmatter.type === kind.governs)) {
+                    for (const row of inspectKindDeprecatedUsage(doc, kind)) {
+                        if (row.field !== name || row.code !== (coordinate === "field" ? "KIND_DEPRECATED_FIELD" : coordinate === "value" ? "KIND_DEPRECATED_VALUE" : "KIND_DEPRECATED_LINK"))
+                            continue;
+                        if (coordinate === "value" && row.value !== value)
+                            continue;
+                        candidate.usage.push({ id: doc.id, count: row.count, ...(row.unknown ? { unknown: true } : {}) });
+                    }
+                }
+                declarations.push(candidate);
+                restoreOmission(target, current, coordinate, name, value);
+            };
+            const desiredFields = new Set([...next.kind.fields.required, ...next.kind.fields.optional]);
+            for (const name of kind.fields.optional)
+                if (!desiredFields.has(name) && kind.deprecated?.fields.includes(name)) {
+                    if (Object.hasOwn(kind.fields.terminal, name) && kind.fields.terminal[name].length) {
+                        blockers.push({ code: "RETIREMENT_TERMINAL_CHANGE_UNSUPPORTED", id: target.id, field: name, message: "terminal coordinates require a separate migration" });
+                        continue;
+                    }
+                    retiredFields.add(name);
+                    add("field", name);
+                }
+            for (const [name, values] of Object.entries(kind.fields.values))
+                if (!retiredFields.has(name)) {
+                    const remaining = Object.hasOwn(next.kind.fields.values, name) ? next.kind.fields.values[name] : undefined;
+                    if (!remaining)
+                        continue; // Whole vocabulary removal remains the additive owner's unsupported omission.
+                    const deprecatedValues = kind.deprecated && Object.hasOwn(kind.deprecated.values, name) ? kind.deprecated.values[name] : [];
+                    for (const value of values)
+                        if (!remaining.includes(value) && deprecatedValues.includes(value))
+                            add("value", name, value);
+                }
+            for (const name of Object.keys(kind.links ?? {}))
+                if (!Object.hasOwn(next.kind.links ?? {}, name) && kind.deprecated?.links.includes(name))
+                    add("link", name);
+            const restored = parseConventionDoc(target, { okfVersion: edition });
+            if (restored.ok)
+                for (const [field, before, after] of [
+                    ["fields.types", kind.fields.types ?? {}, restored.kind.fields.types ?? {}],
+                    ["fields.required", sorted(kind.fields.required), sorted(restored.kind.fields.required)],
+                    ["fields.terminal", kind.fields.terminal, restored.kind.fields.terminal], ["claim", kind.claim ?? {}, restored.kind.claim ?? {}],
+                    ["sections", kind.sections ?? [], restored.kind.sections ?? []],
+                ])
+                    if (!okfValuesEqual(before, after))
+                        blockers.push({ code: "RETIREMENT_MIGRATION_UNSUPPORTED", id: target.id, field, message: "retirement inspection does not authorize unrelated type, required, terminal or claim migrations" });
+        }
+        for (const doc of currentDocs.filter(d => isConventionId(d.id) && readRecipeStamp(d)?.id === source.id)) {
+            if (!comparison.docs.some(d => d.id === doc.id))
+                blockers.push({ code: "RETIREMENT_DEFINITION_OMISSION_UNSUPPORTED", id: doc.id, message: "whole convention removal is not declaration retirement" });
+        }
+        // Existing evolution owns all non-retirement omissions, replacements, source warnings and instance validation.
+        const compatibility = await planRecipeEvolution(selected, comparison);
+        blockers.push(...compatibility.blockers);
+    }
+    catch (error) {
+        blockers.push({ code: "RETIREMENT_SOURCE_UNVERIFIABLE", id: source.id, message: error instanceof Error ? error.message : String(error) });
+    }
+    try {
+        final = sorted(await backend.list());
+        if (!okfValuesEqual(initial, final))
+            unknown("RETIREMENT_INVENTORY_CHANGED", "*", "concept membership changed while scanning");
+        for (const row of inventory)
+            if (row.version !== null) {
+                try {
+                    if ((await readDocVersioned(selected, row.id)).version !== row.version)
+                        unknown("RETIREMENT_CONCEPT_CHANGED", row.id, "concept version changed while scanning");
+                }
+                catch (error) {
+                    unknown("RETIREMENT_CONCEPT_CHANGED", row.id, error);
+                }
+            }
+        if (((await backend.readReserved("", "index.md"))?.version ?? null) !== indexVersion)
+            unknown("RETIREMENT_EDITION_CHANGED", "index.md", "root index changed while scanning");
+    }
+    catch (error) {
+        unknown("RETIREMENT_INVENTORY_UNVERIFIABLE", "*", error);
+    }
+    issues.sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));
+    blockers.sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b)));
+    const bundleId = declaredBundleId(snapshots.get(BUNDLE_NAME_DOC_ID)?.doc);
+    const complete = issues.length === 0;
+    const localBase = { complete, consistency: "observed-stable-reads-not-an-atomic-snapshot", target_root: selected.root,
+        ...(bundleId ? { bundle_id: bundleId } : {}), okf_version: edition, root_index_version: indexVersion, initial_ids: initial, final_ids: final, inventory, issues };
+    const local = { ...localBase,
+        verdict: declarations.some(d => d.usage.some(u => !u.unknown)) ? "used" : !complete || blockers.length > 0 || declarations.some(d => d.usage.some(u => u.unknown)) ? "unknown" : "complete-clean",
+        observation_digest: recipePreflightDigest(localBase) };
+    const consumers = await consumersFor(evidence, evidencePresent, source, prepared, snapshots, local);
+    const report = { recipe: "declaration retirement inspection", id: source.id, version: source.version, source: source.source, source_digest: recipeSourceDigest(source),
+        scope: "observed-local-concepts-and-supplied-structural-consumers", can_apply: false, apply_blocker: "RETIREMENT_APPLY_NOT_IMPLEMENTED",
+        analysis: blockers.length || consumers.status === "refused" ? "refused" : !complete || local.verdict === "unknown" || consumers.status === "partial" ? "partial" : "complete",
+        declarations, blockers, local, consumers, external_consumers: "unknown-unenumerated-offline-and-arbitrary-code",
+        proposed_definitions: (prepared ? candidateOwned(prepared) : []).map(doc => ({ id: doc.id, definition_digest: definitionDigest(doc), hypothetical_content_version: contentVersion(doc) })) };
+    return { report, source, ...(prepared ? { installation: prepared } : {}), snapshots, bundle: selected };
+}
+export async function planRecipeDeclarationRetirement(bundle, source, options = {}) {
+    return (await prepareRecipeDeclarationRetirement(bundle, source, options)).report;
+}
+//# sourceMappingURL=retirement.js.map