@intentius/chant 0.124.13 → 0.124.14

package/dist/cli/handlers/lifecycle.js

@@ -0,0 +1,1727 @@
+import { lexiconNames } from "../../lexicon-module.js";
+import { resolve } from "node:path";
+import { commandBuildParams } from "../build-params-cli.js";
+import { build } from "../../build.js";
+import { takeSnapshot } from "../../lifecycle/snapshot.js";
+import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git.js";
+import { deepDiffForLexicon } from "../../lifecycle/deep-observe.js";
+import { countUnclaimed, countPending, countPropertyDrift, countHeld, suspiciousHeld } from "../../lifecycle/deep-diff.js";
+import { describePathOrigin, getPathProvenance, getProvenance } from "../../provenance.js";
+import { resolveDeepDrift, resolveDriftedField } from "../../fold-provenance.js";
+import { acceptDeviations, baselineForLexicon, emptyBaseline, readObservationBaseline, writeObservationBaseline, OBSERVATION_BASELINE_FILE, } from "../../lifecycle/observation-baseline.js";
+import { computeBuildDigest, declaredDefinitions, diffDigests } from "../../lifecycle/digest.js";
+import { diffLive, diffLiveArtifacts, diffSnapshots, missingRow } from "../../lifecycle/live-diff.js";
+import { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice } from "../../lifecycle/change-set.js";
+import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue } from "../../lifecycle/receipt-plan.js";
+import { annotateDisruption, disruptionNotices } from "../../lifecycle/disruption.js";
+import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt.js";
+import { formatUnobserved, mergeObservations, normalizeObservation, unobservedAll, } from "../../observation.js";
+import { describeIdentities, identityStatusText } from "../../identity.js";
+import { discoverComponents } from "../../components/discover.js";
+import { cfnDeployStacks } from "./components.js";
+import { affectedStacks } from "../../lifecycle/affected.js";
+import { rollbackToRevision } from "../../lifecycle/rollback.js";
+import { loadChantConfig, environmentNames, matchesDeclaredEnvironment, resolveOwnershipStack } from "../../config.js";
+import { unknownEnvError, isProdLikeEnvironment } from "../../env.js";
+import { planTeardown, executeTeardown } from "../../lifecycle/teardown.js";
+import { collectBuildRootContributors } from "../plugins.js";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options.js";
+import { applyLiveEndpoint } from "../../live-endpoint.js";
+import { isObservableDeclarable } from "../../declarable.js";
+import { formatError, formatWarning, formatSuccess, formatBold } from "../format.js";
+/**
+ * Resolve the build root for a lifecycle command. The project root (where
+ * chant.config.ts lives) is always ".", but the *build* can be scoped to a
+ * subdirectory so a mixed-layout project — chant `src/` next to app code with
+ * import side effects — only synthesizes its infra. Precedence: `--src` flag,
+ * then `config.sourceDir`, then "." (the root). Snapshot/diff/plan all use this
+ * so their build digests stay consistent.
+ */
+export function resolveBuildRoot(args, config) {
+    return resolve(args.src ?? config.sourceDir ?? ".");
+}
+/**
+ * The stacks a lifecycle command (`snapshot`/`diff`) iterates. A multi-stack
+ * project declares them via `stacks` in chant.config (#932) — each built from
+ * its own `src` and observed against its own live stack `name`. A single-stack
+ * project (no `stacks`) resolves to one target built from `sourceDir`/root and
+ * observed as the stack named after the environment (unchanged behavior). An
+ * explicit `--src` always wins and forces a single scoped target.
+ */
+function resolveStackTargets(args, config) {
+    if (args.src)
+        return [{ root: resolve(args.src) }];
+    if (config.stacks && config.stacks.length > 0) {
+        return config.stacks.map((s) => ({ stack: s.name, root: resolve(s.src), region: s.region }));
+    }
+    return [{ root: resolveBuildRoot(args, config) }];
+}
+/**
+ * chant lifecycle snapshot <environment> [lexicon]
+ */
+export async function runLifecycleSnapshot(ctx) {
+    const { args, plugins } = ctx;
+    const environment = args.extraPositional;
+    const lexiconFilter = args.extraPositional2;
+    if (!environment) {
+        console.error(formatError({ message: "Environment is required: chant lifecycle snapshot <environment> [lexicon]" }));
+        return 1;
+    }
+    // Validate environment against config
+    const projectPath = resolve(".");
+    const { config } = await loadChantConfig(projectPath);
+    // This invocation's parameters, so the declared side of the comparison is the estate
+    // the caller asked for rather than the parameter defaults (#1483).
+    const declaredParams = await commandBuildParams(config.buildParams, args);
+    if (!declaredParams)
+        return 1;
+    const declaredEnvNames = environmentNames(config.environments);
+    if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
+        console.error(formatError({
+            message: `Unknown environment "${environment}"`,
+            hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
+        }));
+        return 1;
+    }
+    // Filter plugins if lexicon specified
+    const targetPlugins = lexiconFilter
+        ? plugins.filter((p) => p.name === lexiconFilter)
+        : plugins;
+    const targetSerializers = targetPlugins.map((p) => p.serializer);
+    const observingPlugins = targetPlugins.filter((p) => p.describeResources || p.listArtifacts);
+    if (observingPlugins.length === 0) {
+        console.error(formatError({
+            message: "No plugins implement describeResources or listArtifacts",
+            hint: lexiconFilter ? `Lexicon "${lexiconFilter}" does not support state snapshots` : undefined,
+        }));
+        return 1;
+    }
+    // One target per stack (single-stack projects: exactly one). Each stack builds
+    // from its own scoped root — so its logical ids match what it deploys — and
+    // snapshots against its own live stack name (#932).
+    const targets = resolveStackTargets(args, config);
+    let anySnapshotSaved = false;
+    let anyHardError = false;
+    // #1166 — same self-sufficiency as `chant graph --live`: a snapshot is
+    // always a live read, so an environment's declared endpoint applies here
+    // too, unless the ambient shell already set it.
+    const endpointResult = applyLiveEndpoint(config.environments, environment, observingPlugins);
+    if (endpointResult.notice)
+        console.error(formatWarning({ message: endpointResult.notice }));
+    // Build every stack first, so the ambient scan (#1278) can be bounded by the
+    // kinds the PROJECT manages rather than the ones this stack happens to
+    // declare. "Which of my security groups are unused" is a question about the
+    // estate; a region whose stack declares no security group still has a default
+    // one, and scoping the bound per stack silently drops it.
+    const built = [];
+    const buildRoots = collectBuildRootContributors(targetPlugins, config, projectPath);
+    for (const target of targets) {
+        const label = target.stack ? `stack "${target.stack}"` : "project";
+        const buildResult = await build(target.root, targetSerializers, undefined, { buildParams: declaredParams, buildRoots });
+        if (buildResult.errors.length > 0) {
+            console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
+            anyHardError = true;
+            continue;
+        }
+        built.push({ target, buildResult });
+    }
+    const projectKinds = [
+        ...new Set(built.flatMap(({ buildResult }) => [...buildResult.entities.values()].map((e) => e.entityType))),
+    ];
+    try {
+        for (const { target, buildResult } of built) {
+            const label = target.stack ? `stack "${target.stack}"` : "project";
+            let result;
+            try {
+                result = await takeSnapshot(environment, observingPlugins, buildResult, {
+                    stack: target.stack,
+                    region: target.region,
+                    deep: args.deep,
+                    ambient: args.ambient,
+                    ambientKinds: projectKinds,
+                });
+            }
+            catch (err) {
+                if (err instanceof StaleLifecycleBranchError) {
+                    console.error(formatError({
+                        message: `Another snapshot completed for chant/lifecycle after this run started (env: ${environment}).`,
+                        hint: `Pull and retry: \`git fetch origin ${"chant/lifecycle"}:${"chant/lifecycle"}\` && \`chant lifecycle snapshot ${environment}\`.`,
+                    }));
+                    return 1;
+                }
+                throw err;
+            }
+            for (const w of result.warnings) {
+                console.error(formatWarning({ message: w }));
+            }
+            for (const e of result.errors) {
+                console.error(formatError({ message: e }));
+            }
+            if (result.snapshots.length > 0) {
+                anySnapshotSaved = true;
+                const prefix = target.stack ? `${target.stack}: ` : "";
+                const counts = result.snapshots
+                    .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
+                    .join(" ");
+                console.error(formatSuccess(`${prefix}Snapshot saved to chant/lifecycle (${counts})`));
+            }
+            if (result.errors.length > 0)
+                anyHardError = true;
+        }
+        return anyHardError && !anySnapshotSaved ? 1 : 0;
+    }
+    finally {
+        endpointResult.restore();
+    }
+}
+/**
+ * chant lifecycle show <environment> [lexicon]
+ */
+export async function runLifecycleShow(ctx) {
+    const environment = ctx.args.extraPositional;
+    const lexiconFilter = ctx.args.extraPositional2;
+    if (!environment) {
+        console.error(formatError({ message: "Environment is required: chant lifecycle show <environment> [lexicon]" }));
+        return 1;
+    }
+    // Fetch from remote first
+    await fetchLifecycle();
+    if (lexiconFilter) {
+        const content = await readSnapshot(environment, lexiconFilter);
+        if (!content) {
+            console.error(formatError({ message: `No snapshot found for ${environment}/${lexiconFilter}` }));
+            return 1;
+        }
+        const snapshot = JSON.parse(content);
+        printSnapshotTable(snapshot);
+    }
+    else {
+        const snapshots = await readEnvironmentSnapshots(environment);
+        if (snapshots.size === 0) {
+            console.error(formatError({ message: `No snapshots found for environment "${environment}"` }));
+            return 1;
+        }
+        for (const [lexicon, content] of snapshots) {
+            const snapshot = JSON.parse(content);
+            // Depth is stated, not inferred (#1267). An identity snapshot cannot
+            // answer a property question, and a reader that assumes otherwise reads
+            // "no properties recorded" as "no such properties".
+            const depth = snapshot.depth ?? "identity";
+            const depthNote = depth === "deep"
+                ? ` — deep (${Object.keys(snapshot.properties ?? {}).length} property trees)`
+                : " — identity only";
+            console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources${depthNote} — ${snapshot.timestamp}`);
+            printSnapshotTable(snapshot);
+        }
+    }
+    return 0;
+}
+/**
+ * chant lifecycle rollback [<environment>] --to <ref>
+ *
+ * Open a PR restoring `sourceDir` to a prior git revision (#873). Source-level,
+ * reviewable, no cloud mutation — a human merges, then a gated apply rolls the
+ * env back. The `<env>` positional is PR context.
+ */
+export async function runLifecycleRollback(ctx) {
+    const { args } = ctx;
+    const environment = args.extraPositional; // optional — PR context/title
+    const ref = args.migrateTo; // the --to value
+    if (!ref) {
+        console.error(formatError({ message: "Target revision required: chant lifecycle rollback [<env>] --to <ref>" }));
+        return 1;
+    }
+    const { config } = await loadChantConfig(resolve("."));
+    const sourceDir = config.sourceDir ?? ".";
+    try {
+        const result = await rollbackToRevision({ ref, env: environment, sourceDir, cwd: resolve("."), dryRun: args.dryRun });
+        if (result.noop) {
+            console.error(formatSuccess(`${sourceDir} already matches ${ref} — nothing to roll back`));
+            return 0;
+        }
+        if (args.dryRun) {
+            // The delta on stdout, so it pipes and diffs like any other patch; the
+            // summary on stderr, matching the PR path's split.
+            process.stdout.write(result.diff ?? "");
+            console.error(formatSuccess(`Rollback delta for ${ref} computed — no PR opened, nothing pushed`));
+            return 0;
+        }
+        console.log(result.prUrl); // the PR URL — the consumer (behold) reads this from stdout
+        console.error(formatSuccess(`Opened rollback PR on ${result.branch}`));
+        return 0;
+    }
+    catch (err) {
+        console.error(formatError({ message: `rollback failed — ${err instanceof Error ? err.message : String(err)}` }));
+        return 1;
+    }
+}
+/**
+ * chant lifecycle diff <environment> [lexicon]
+ */
+export async function runLifecycleDiff(ctx) {
+    const { args, plugins, serializers } = ctx;
+    const environment = args.extraPositional;
+    const lexiconFilter = args.extraPositional2;
+    if (!environment) {
+        console.error(formatError({ message: "Environment is required: chant lifecycle diff <environment> [lexicon]" }));
+        return 1;
+    }
+    // `--between <refA> <refB>` (#822): diff two saved snapshots against each other.
+    // Purely historical — no build, no cloud query; reads the orphan branch.
+    if (args.betweenA && args.betweenB) {
+        return runLifecycleDiffBetween({
+            environment,
+            lexiconFilter,
+            refA: args.betweenA,
+            refB: args.betweenB,
+            json: !!args.json,
+        });
+    }
+    // Filter serializers to target lexicon before building
+    const targetSerializers = lexiconFilter
+        ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
+        : serializers;
+    // Fetch previous snapshots once (all stacks share the orphan branch).
+    const { config } = await loadChantConfig(resolve("."));
+    // This invocation's parameters, so the declared side of the comparison is the estate
+    // the caller asked for rather than the parameter defaults (#1483).
+    const declaredParams = await commandBuildParams(config.buildParams, args);
+    if (!declaredParams)
+        return 1;
+    await fetchLifecycle();
+    // One target per stack (single-stack projects: exactly one), each built from
+    // its own scoped root and diffed against its own live stack name (#932).
+    const targets = resolveStackTargets(args, config);
+    const json = !!args.json;
+    const perStackJson = {};
+    let combinedLexiconsJson;
+    let totalDrift = 0;
+    let totalUnobserved = 0;
+    let totalChecked = 0;
+    let anyBuildError = false;
+    // Accepted-deviation baseline (#1014). Read once for the whole run — it is
+    // env-keyed, not stack-keyed, and every deep pass subtracts from the same
+    // committed set. Absent is the normal state (nothing accepted yet).
+    const baseline = args.live ? await readObservationBaseline(environment) : null;
+    const accepted = {};
+    // Effect receipts across every target's build (#1833) — `--update-baseline`
+    // refuses to accept drift on them (the effect step is their only writer),
+    // and recognition is marker-based so materialized lexicon rows are caught.
+    const receiptEntities = new Set();
+    // #1166 — an environment can declare its own endpoint (a local emulator like
+    // Floci), so `--live` is self-sufficient even when the ambient shell never
+    // exported e.g. AWS_ENDPOINT_URL. Ambient always wins when it's already set.
+    // Scoped to just the live reads below — restored in `finally`.
+    const liveLexicons = args.live ? plugins.filter((p) => p.describeResources || p.listArtifacts) : [];
+    const endpointResult = applyLiveEndpoint(config.environments, environment, liveLexicons);
+    if (endpointResult.notice)
+        console.error(formatWarning({ message: endpointResult.notice }));
+    // The build `chant build` would produce for this project (#2002's one
+    // place), so the diff folds by default as `chant build` does. A run build
+    // cannot say which composite argument produced a field, so without this
+    // every composite field in the live diff read as unknown (#3597).
+    const projectRoot = resolve(".");
+    const diffBuildOptions = resolveProjectBuildOptions({
+        config,
+        configDir: projectRoot,
+        plugins,
+        modes: resolveBuildModes(config, { fold: args.fold, sandbox: args.sandbox }),
+        buildParams: declaredParams,
+    });
+    try {
+        for (const target of targets) {
+            const buildResult = await build(target.root, targetSerializers, undefined, diffBuildOptions);
+            if (buildResult.errors.length > 0) {
+                const label = target.stack ? `stack "${target.stack}"` : "project";
+                console.error(formatError({ message: `Build failed for ${label} — fix errors before diffing` }));
+                anyBuildError = true;
+                continue;
+            }
+            // The lexicons the diff walks. Keyed on the BUILT manifest — which is
+            // right for the resource axis (a lexicon with no declared entities has
+            // nothing to diff) but drops the artifact axis whole: artifacts are
+            // context-keyed with no declared side at all (that is their defining
+            // property), so an estate that uses helm purely as component deploy
+            // steps builds zero helm entities and its releases were never listed —
+            // `observedArtifacts` silently absent for exactly the estates behold#146
+            // exists for (found live on kubemicrovm-ops, four releases invisible).
+            // On the live path, artifact-capable configured lexicons join the walk;
+            // their resource half stays gated on `describeResources` + declared
+            // entities as before.
+            const builtLexicons = Array.from(buildResult.manifest.lexicons);
+            const artifactLexicons = args.live ? plugins.filter((p) => p.listArtifacts).map((p) => p.name) : [];
+            const lexicons = lexiconFilter
+                ? [lexiconFilter]
+                : [...new Set([...builtLexicons, ...artifactLexicons])];
+            if (args.live) {
+                // Multi-stack component projects: observe each component's own cfn stack
+                // and union (same fix runGraphLive / plan use), so a deployed resource
+                // isn't reported "missing". Only when this target has no explicit stack.
+                let componentStacks = [];
+                if (!target.stack) {
+                    try {
+                        const disc = await discoverComponents(target.root, { sandbox: args.sandbox });
+                        const set = new Set();
+                        for (const { component } of disc.components.values())
+                            for (const s of cfnDeployStacks(component.deploy))
+                                set.add(s);
+                        componentStacks = [...set];
+                    }
+                    catch {
+                        // no components / discovery failed → single-stack observe path
+                    }
+                }
+                const r = await runLifecycleDiffLive({
+                    environment,
+                    lexicons,
+                    plugins,
+                    buildResult,
+                    json,
+                    stack: target.stack,
+                    region: target.region,
+                    componentStacks,
+                    baseline,
+                    updateBaseline: args.updateBaseline,
+                    ...(args.namespace ? { namespace: args.namespace } : {}),
+                    projectRoot,
+                });
+                totalDrift += r.totalDrift;
+                totalUnobserved += r.totalUnobserved;
+                totalChecked += r.totalLexiconsChecked;
+                for (const [lexicon, deviations] of Object.entries(r.toAccept)) {
+                    (accepted[lexicon] ?? (accepted[lexicon] = [])).push(...deviations);
+                }
+                if (args.updateBaseline) {
+                    for (const name of collectEffectReceipts(buildResult.entities).keys())
+                        receiptEntities.add(name);
+                }
+                if (json) {
+                    if (target.stack)
+                        perStackJson[target.stack] = r.byLexicon;
+                    else
+                        combinedLexiconsJson = r.byLexicon;
+                }
+            }
+            else {
+                await runLifecycleDiffDigest({ environment, lexicons, buildResult, stack: target.stack });
+            }
+        }
+        // `--update-baseline` (#1014): record what the deep pass just reported as
+        // accepted, so it stops re-alerting. Runs before the summary lines so the
+        // "no drift" verdict below still describes the run that produced it.
+        if (args.live && args.updateBaseline) {
+            await recordAcceptedBaseline(environment, baseline, accepted, json, receiptEntities);
+        }
+        if (args.live) {
+            if (json) {
+                // Single-stack keeps the original `{ environment, lexicons }` shape
+                // (behold's inspect diff, #852); multi-stack nests under `stacks`.
+                console.log(JSON.stringify(combinedLexiconsJson !== undefined
+                    ? { environment, lexicons: combinedLexiconsJson }
+                    : { environment, stacks: perStackJson }));
+            }
+            else if (totalChecked === 0) {
+                console.error(formatWarning({
+                    message: "No lexicons implement describeResources or listArtifacts — nothing to diff in --live mode",
+                }));
+                return 1;
+            }
+            else if (totalDrift === 0) {
+                // Qualify the all-clear when part of the estate was never read (#1089):
+                // "no drift" over an incomplete observation is not the same claim.
+                console.error(totalUnobserved > 0
+                    ? formatWarning({
+                        message: `No drift detected across ${totalChecked} lexicon(s), but ${totalUnobserved} declared entity(ies) could not be observed — that part of the estate is unknown, not clean`,
+                    })
+                    : formatSuccess(`No drift detected across ${totalChecked} lexicon(s)`));
+            }
+        }
+        return anyBuildError ? 1 : 0;
+    }
+    finally {
+        endpointResult.restore();
+    }
+}
+/**
+ * Write the accepted-deviation baseline (#1014) for everything the deep pass
+ * reported this run, and push it on the same orphan branch the snapshots use.
+ *
+ * Acceptance is a deliberate, committed act — that is the whole difference
+ * between this and a suppression flag — so the write is loud: it names the
+ * count and the storage path, and a failed push says so rather than leaving
+ * the operator believing the team's baseline moved.
+ */
+async function recordAcceptedBaseline(environment, existing, accepted, json, receipts) {
+    const total = Object.values(accepted).reduce((n, d) => n + d.length, 0);
+    if (total === 0) {
+        if (!json) {
+            console.error(formatWarning({
+                message: "--update-baseline: nothing to accept — no property-level deviations were reported",
+            }));
+        }
+        return;
+    }
+    try {
+        // `acceptDeviations` throws on an effect-receipt deviation (#1833) —
+        // inside the try so the refusal reaches the operator as a formatted
+        // error, with no baseline written at all.
+        let next = existing ?? emptyBaseline(environment);
+        for (const [lexicon, deviations] of Object.entries(accepted)) {
+            next = acceptDeviations(next, lexicon, deviations, { receipts });
+        }
+        await writeObservationBaseline(next);
+        const pushed = await pushLifecycle();
+        if (!json) {
+            console.error(formatSuccess(`--update-baseline: accepted ${total} deviation(s) into ${environment}/${OBSERVATION_BASELINE_FILE} on chant/lifecycle` +
+                (pushed ? " (pushed)" : " (local only — no remote configured or push refused)")));
+        }
+    }
+    catch (err) {
+        console.error(formatError({
+            message: `--update-baseline: baseline not updated — ${err instanceof Error ? err.message : String(err)}`,
+        }));
+    }
+}
+/**
+ * `chant lifecycle diff <env> --between <refA> <refB>` (#822). Diffs two saved
+ * snapshots against each other — read-only, no build, no cloud query. Reads
+ * `<ref>:<env>/<lexicon>.json` from the orphan branch at each ref and reports the
+ * two-way delta per lexicon.
+ */
+async function runLifecycleDiffBetween(args) {
+    await fetchLifecycle();
+    const { config } = await loadChantConfig(resolve("."));
+    const lexicons = args.lexiconFilter ? [args.lexiconFilter] : lexiconNames(config.lexicons ?? []);
+    if (lexicons.length === 0) {
+        console.error(formatError({ message: "No lexicons to diff — pass a lexicon or declare `lexicons` in chant.config." }));
+        return 1;
+    }
+    const parseResources = (content) => {
+        if (content === null)
+            return null;
+        try {
+            return JSON.parse(content).resources ?? {};
+        }
+        catch {
+            return null;
+        }
+    };
+    const byLexicon = {};
+    for (const lexicon of lexicons) {
+        const prev = parseResources(await readSnapshotAt(args.environment, lexicon, args.refA));
+        const next = parseResources(await readSnapshotAt(args.environment, lexicon, args.refB));
+        if (prev === null && next === null) {
+            if (!args.json)
+                console.error(formatWarning({ message: `${lexicon}: not captured at either ref — skipping` }));
+            continue;
+        }
+        byLexicon[lexicon] = diffSnapshots(prev ?? {}, next ?? {});
+    }
+    if (args.json) {
+        console.log(JSON.stringify({ environment: args.environment, refA: args.refA, refB: args.refB, lexicons: byLexicon }, null, 2));
+        return 0;
+    }
+    if (Object.keys(byLexicon).length === 0) {
+        console.log(`No snapshots for ${args.environment} at ${args.refA} / ${args.refB}.`);
+        return 0;
+    }
+    console.log(formatBold(`Snapshot diff — ${args.environment}: ${args.refA} → ${args.refB}`));
+    for (const [lexicon, d] of Object.entries(byLexicon)) {
+        console.log(`\n${formatBold(lexicon)} — ${d.added.length} added, ${d.removed.length} removed, ${d.changed.length} changed, ${d.unchanged.length} unchanged`);
+        for (const name of d.added)
+            console.log(`  + ${name}`);
+        for (const name of d.removed)
+            console.log(`  - ${name}`);
+        for (const drift of d.changed)
+            console.log(`  ~ ${drift.name} (${drift.changes.map((c) => c.path).join(", ")})`);
+    }
+    return 0;
+}
+async function runLifecycleDiffDigest(args) {
+    const currentDigest = computeBuildDigest(args.buildResult);
+    if (args.stack)
+        console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
+    for (const lexicon of args.lexicons) {
+        const content = await readSnapshot(args.environment, snapshotStorageKey(lexicon, args.stack));
+        let previousDigest = undefined;
+        if (content) {
+            const snapshot = JSON.parse(content);
+            previousDigest = snapshot.digest;
+        }
+        const diff = diffDigests(currentDigest, previousDigest);
+        console.log(`\n${formatBold(lexicon)}`);
+        console.log("RESOURCE".padEnd(20) + "STATUS".padEnd(12) + "TYPE");
+        console.log("-".repeat(60));
+        for (const name of diff.added) {
+            console.log(name.padEnd(20) + "added".padEnd(12) + (currentDigest.resources[name]?.type ?? ""));
+        }
+        for (const name of diff.changed) {
+            console.log(name.padEnd(20) + "changed".padEnd(12) + (currentDigest.resources[name]?.type ?? ""));
+        }
+        for (const name of diff.removed) {
+            console.log(name.padEnd(20) + "removed".padEnd(12) + (previousDigest?.resources[name]?.type ?? ""));
+        }
+        for (const name of diff.unchanged) {
+            console.log(name.padEnd(20) + "unchanged".padEnd(12) + (currentDigest.resources[name]?.type ?? ""));
+        }
+        // chant #1442 — a lexicon bump can change emitted output with no source
+        // change, so every resource above can read "unchanged" while the build is
+        // not the same build. Printed under the table rather than as a row: no
+        // resource's declaration moved, the thing that interpreted them did.
+        for (const change of diff.lexiconVersionChanges) {
+            const from = change.previous ?? "(absent)";
+            const to = change.current ?? "(absent)";
+            console.log(`\nlexicon ${change.lexicon}: ${from} → ${to}`);
+        }
+    }
+    return 0;
+}
+/**
+ * Read one lexicon's live resources, resolving the observation tri-state
+ * (#1089) for every declared entity: present, confirmed-absent, or not
+ * observed with a reason.
+ *
+ * Two behaviours the old inline call sites did not have. A throw no longer
+ * skips the lexicon — every entity it was asked about comes back
+ * NOT-OBSERVED (`read-failed`), so a failed read shows up in the plan instead
+ * of vanishing from it. And a multi-stack read merges with
+ * present > not-observed > absent, so one unreadable stack cannot un-observe a
+ * resource another stack returned.
+ */
+async function observeLexicon(plugin, opts) {
+    const entityNames = Array.from(opts.declared);
+    const base = {
+        environment: opts.environment,
+        buildOutput: opts.buildOutput,
+        entityNames,
+        entities: opts.entities,
+        ...(opts.region ? { region: opts.region } : {}),
+        ...(opts.owned !== undefined ? { owned: opts.owned } : {}),
+        ...(opts.namespace ? { namespace: opts.namespace } : {}),
+    };
+    try {
+        if (opts.componentStacks && opts.componentStacks.length > 0) {
+            const parts = [];
+            for (const stack of opts.componentStacks) {
+                parts.push(normalizeObservation(await plugin.describeResources({ ...base, stack })));
+            }
+            return mergeObservations(parts);
+        }
+        return normalizeObservation(await plugin.describeResources({ ...base, ...(opts.stack ? { stack: opts.stack } : {}) }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(formatError({
+            message: `${plugin.name}: describeResources failed — ${message} (reporting ${entityNames.length} declared entity(ies) as not observed, not as absent)`,
+        }));
+        return {
+            resources: {},
+            unobserved: unobservedAll(entityNames, "read-failed", message, opts.entities),
+            queried: {},
+            sources: {},
+            notes: [],
+        };
+    }
+}
+/** Diff current build vs live cloud for one stack. Renders the human report
+ * inline; returns per-lexicon results so the caller emits the aggregate `--json`
+ * once (single-stack keeps the original shape; multi-stack nests under `stacks`). */
+async function runLifecycleDiffLive(args) {
+    let totalDrift = 0;
+    let totalUnobserved = 0;
+    let totalLexiconsChecked = 0;
+    const byLexicon = {};
+    const toAccept = {};
+    if (!args.json && args.stack)
+        console.log(`\n${formatBold(`■ stack ${args.stack}`)}`);
+    for (const lexiconName of args.lexicons) {
+        const plugin = args.plugins.find((p) => p.name === lexiconName);
+        if (!plugin)
+            continue;
+        if (!plugin.describeResources && !plugin.listArtifacts) {
+            console.error(formatWarning({
+                message: `${lexiconName}: lexicon does not implement describeResources or listArtifacts — skipping (use without --live for digest diff)`,
+            }));
+            continue;
+        }
+        // Build per-lexicon entity index. Resource declarables only — outputs,
+        // parameters, serializer directives and property-kind declarables (read
+        // inside their parent, #3001) have no live counterpart of their own, and a
+        // declared name the reader can never resolve reads as missing (see
+        // lifecycle/observe.ts).
+        const declared = new Set();
+        const entities = new Map();
+        for (const [name, entity] of args.buildResult.entities) {
+            if (entity.lexicon === lexiconName && isObservableDeclarable(entity)) {
+                declared.add(name);
+                // Path origins are carried across explicitly (#1443): this map is plain
+                // objects, and the symbol-keyed provenance channel does not survive it.
+                const pathOrigins = getPathProvenance(entity);
+                entities.set(name, {
+                    entityType: entity.entityType,
+                    props: (entity.props != null ? entity.props : {}),
+                    ...(pathOrigins ? { pathOrigins } : {}),
+                });
+            }
+        }
+        const rawOutput = args.buildResult.outputs.get(lexiconName);
+        const buildOutput = rawOutput === undefined
+            ? ""
+            : typeof rawOutput === "string"
+                ? rawOutput
+                : rawOutput.primary;
+        // Read previous snapshot once; both flows pull what they need.
+        let prevSnapshot;
+        const content = await readSnapshot(args.environment, snapshotStorageKey(lexiconName, args.stack));
+        if (content)
+            prevSnapshot = JSON.parse(content);
+        let lexiconChecked = false;
+        // ── Resources path (entity-keyed) ──────────────────────────────────────
+        if (plugin.describeResources) {
+            const observed = await observeLexicon(plugin, {
+                environment: args.environment,
+                buildOutput,
+                declared,
+                entities,
+                stack: args.stack,
+                region: args.region,
+                componentStacks: args.componentStacks,
+                ...(args.namespace ? { namespace: args.namespace } : {}),
+            });
+            const observedNow = observed.resources;
+            const observedThen = prevSnapshot?.resources;
+            const diff = diffLive({
+                declared,
+                observedNow,
+                observedThen,
+                unobserved: observed.unobserved,
+                queried: observed.queried,
+                // What each create would create (#3652), so the diff, and the plan
+                // digest ApplyOp's gate binds to it, moves when a missing entity's
+                // declaration does.
+                definitions: declaredDefinitions(entities),
+            });
+            // Unobserved entities are deliberately NOT drift: a hole in the read is
+            // not a change in the cloud. They are reported separately (#1089) so a
+            // "no drift detected" line can never be built on top of a failed read.
+            totalDrift += diff.driftedSinceSnapshot.length + diff.missing.length + diff.orphan.length + diff.disappeared.length;
+            totalUnobserved += diff.unobserved.length;
+            if (args.json) {
+                const entry = (byLexicon[lexiconName] ?? (byLexicon[lexiconName] = {}));
+                entry.resources = diff;
+                entry.observed = observedNow; // live state (#862) — status/attributes per resource
+                if (Object.keys(observed.unobserved).length > 0)
+                    entry.unobserved = observed.unobserved;
+            }
+            else
+                renderLiveDiff(lexiconName, args.environment, diff);
+            lexiconChecked = true;
+            // ── Deep path (property-level, #1014) ───────────────────────────────
+            // Gated purely on the capability: a lexicon without a deep reader is
+            // completely unaffected, including its output.
+            if (plugin.observeResourcesDeep) {
+                const deep = await deepDiffForLexicon(plugin, {
+                    environment: args.environment,
+                    buildOutput,
+                    entities,
+                    stack: args.stack,
+                    region: args.region,
+                    componentStacks: args.componentStacks,
+                    baseline: baselineForLexicon(args.baseline, lexiconName),
+                });
+                totalDrift += countPropertyDrift(deep) + countPending(deep);
+                // Only count a deep hole for an entity the thin read *did* resolve —
+                // otherwise one unreadable entity is counted twice.
+                totalUnobserved += deep.unobserved.filter((u) => !observed.unobserved[u.name]).length;
+                if (args.updateBaseline)
+                    toAccept[lexiconName] = deviationsToAccept(deep);
+                // chant #2161 — the return leg, classified by fold provenance. Read off
+                // the build's own entities, which is where the record lives.
+                const provenanceOf = (name) => {
+                    const entity = args.buildResult.entities.get(name);
+                    return entity ? getProvenance(entity) : undefined;
+                };
+                if (args.json) {
+                    const entry = (byLexicon[lexiconName] ?? (byLexicon[lexiconName] = {}));
+                    entry.deep = deep;
+                    entry.reconcile = resolveDeepDrift(deep.drifted, provenanceOf, { root: args.projectRoot });
+                }
+                else
+                    renderDeepDiff(lexiconName, deep, provenanceOf, args.projectRoot);
+                // Printed on stderr regardless of `--json` (#2162), same reason the
+                // unobserved/disruption notices are: a shape with no column for
+                // "suspicious" must not read as clean.
+                for (const s of suspiciousHeld(deep)) {
+                    console.error(formatWarning({
+                        message: `${lexiconName}: ${s.name}.${s.path} is declared heldElsewhere(by: "${s.by}") but no live value ever showed up there — the hand-over may never have happened.`,
+                    }));
+                }
+            }
+        }
+        // ── Artifacts path (context-keyed) ─────────────────────────────────────
+        if (plugin.listArtifacts) {
+            let observedNow;
+            try {
+                observedNow = await plugin.listArtifacts({ environment: args.environment, entities, stack: args.stack });
+            }
+            catch (err) {
+                console.error(formatError({
+                    message: `${lexiconName}: listArtifacts failed — ${err instanceof Error ? err.message : String(err)}`,
+                }));
+                continue;
+            }
+            const observedThen = prevSnapshot?.artifacts;
+            const adiff = diffLiveArtifacts({ observedNow, observedThen });
+            totalDrift += adiff.added.length + adiff.removed.length + adiff.changed.length;
+            if (args.json) {
+                const lex = (byLexicon[lexiconName] ?? (byLexicon[lexiconName] = {}));
+                lex.artifacts = adiff;
+                // What was actually seen, not just how it moved (behold#146): the
+                // metadata was in hand and dropped, leaving JSON consumers unable to
+                // read an artifact's own status (a Helm release's "deployed").
+                lex.observedArtifacts = observedNow;
+            }
+            else
+                renderLiveArtifactDiff(lexiconName, args.environment, adiff);
+            lexiconChecked = true;
+        }
+        if (lexiconChecked)
+            totalLexiconsChecked++;
+    }
+    return { byLexicon, totalDrift, totalUnobserved, totalLexiconsChecked, toAccept };
+}
+/**
+ * Everything a deep diff reported this run, as deviations to record accepted.
+ * `--update-baseline` accepts what was *reported*, never what was already
+ * suppressed — re-accepting an unchanged suppression would rewrite its
+ * `recordedAt` on every run and turn the baseline into a churn file.
+ */
+function deviationsToAccept(deep) {
+    const out = [];
+    for (const entity of deep.drifted) {
+        for (const change of entity.changes) {
+            // Only a value that is actually live can be accepted: `absent` means the
+            // cloud does not carry the declared property, which is a finding to fix
+            // in source or in the cloud, not a value to bless.
+            if (!("live" in change))
+                continue;
+            out.push({ entity: entity.name, type: entity.type, path: change.path, value: change.live });
+        }
+    }
+    return out;
+}
+/** Property-level drift report (#1014). Silent when a lexicon's deep read found nothing to say. */
+function renderDeepDiff(lexiconName, deep, provenanceOf = () => undefined, projectRoot) {
+    const drift = countPropertyDrift(deep);
+    const unclaimedCount = countUnclaimed(deep);
+    const heldCount = countHeld(deep);
+    const pendingCount = countPending(deep);
+    if (drift === 0 &&
+        pendingCount === 0 &&
+        heldCount === 0 &&
+        unclaimedCount === 0 &&
+        deep.accepted.length === 0 &&
+        deep.unobserved.length === 0 &&
+        deep.undeclaredEntities.length === 0) {
+        return;
+    }
+    const acceptedCount = deep.accepted.reduce((n, e) => n + e.changes.length, 0);
+    console.log(`\n${formatBold(`${lexiconName} (properties)`)}`);
+    console.log(`${drift} property drift across ${deep.drifted.length} resource(s), ` +
+        `${acceptedCount} accepted, ${deep.unchanged.length} unchanged` +
+        (pendingCount > 0 ? `, ${pendingCount} pending` : "") +
+        (heldCount > 0 ? `, ${heldCount} held` : "") +
+        (unclaimedCount > 0 ? `, ${unclaimedCount} unclaimed` : "") +
+        (deep.unobserved.length > 0 ? `, ${deep.unobserved.length} unobserved` : ""));
+    console.log("-".repeat(80));
+    if (deep.unobserved.length > 0) {
+        console.log(formatBold("\nPROPERTIES UNOBSERVED (declared; the deep read could not look):"));
+        for (const u of deep.unobserved)
+            console.log(`  ? ${formatUnobserved(u.name, u)}`);
+    }
+    if (deep.drifted.length > 0) {
+        console.log(formatBold("\nPROPERTY DRIFT (declared vs live; baseline shown where one exists):"));
+        for (const entity of deep.drifted) {
+            console.log(`  - ${entity.name} (${entity.type})`);
+            const provenance = provenanceOf(entity.name);
+            for (const change of entity.changes) {
+                const declared = "declared" in change ? formatValue(change.declared) : "<undeclared>";
+                const live = "live" in change ? formatValue(change.live) : "<absent>";
+                const baseline = "baseline" in change ? ` [accepted: ${formatValue(change.baseline)}]` : "";
+                // Both sides of the attribution, where each is known (#1443/#1189).
+                const from = change.origin ? ` [from: ${describePathOrigin(change.origin)}]` : "";
+                const owner = change.owner ? ` [owner: ${change.owner}]` : "";
+                const seen = change.seenOn ? ` [seen on: ${change.seenOn}]` : "";
+                console.log(`      ${change.path}: ${declared} → ${live}${baseline}${from}${owner}${seen}`);
+                // chant #2161 — what may be done about it, when the origin says
+                // something today's behaviour would get wrong. A field the author
+                // declared directly is left unremarked: editing it IS today's
+                // behaviour, and saying so on every row would bury the two that matter.
+                // #3597 — the line before the proposal names the composite call and
+                // the argument behind the field, with the file and line it was written on.
+                const { resolution, summary } = resolveDriftedField({
+                    entity: entity.name,
+                    entityType: entity.type,
+                    path: change.path,
+                    ...("declared" in change ? { declared: change.declared } : {}),
+                    ...("live" in change ? { live: change.live } : {}),
+                    ...(change.origin ? { origin: change.origin } : {}),
+                    ...(provenance ? { provenance } : {}),
+                    ...(projectRoot ? { root: projectRoot } : {}),
+                });
+                if (resolution.kind !== "edit-declaration") {
+                    console.log(`        ${summary}`);
+                    console.log(`        ${resolution.description}`);
+                }
+            }
+        }
+    }
+    if (pendingCount > 0) {
+        // #3706: changes an apply would make that no declared property shows
+        // (privileges granted by hand). Printed, so the plan digest moves with them.
+        console.log(formatBold("\nPENDING (changes an apply would make that no declared property shows):"));
+        for (const p of deep.pending ?? []) {
+            console.log(`  ~ ${p.subject}: ${p.change}${p.entities && p.entities.length > 0 ? ` [from: ${p.entities.join(", ")}]` : ""}`);
+        }
+    }
+    if (deep.unclaimed.length > 0) {
+        // Not drift, and printed after it for that reason (#2160): chant never set
+        // these fields, so nothing here is a change chant proposes to make.
+        console.log(formatBold("\nUNCLAIMED (live values on properties chant never declared; not drift):"));
+        for (const entity of deep.unclaimed) {
+            console.log(`  - ${entity.name} (${entity.type})`);
+            for (const field of entity.fields) {
+                const holder = field.heldBy
+                    ? `held by ${field.heldBy}`
+                    : "not in this declaration's claimed fields";
+                console.log(`      ${field.path}: ${formatValue(field.live)} [${holder}]`);
+            }
+        }
+    }
+    if (heldCount > 0) {
+        console.log(formatBold("\nHELD (declared heldElsewhere(); not drift, never proposed for update):"));
+        for (const line of renderHeldLines(deep.held))
+            console.log(line);
+    }
+    if (deep.undeclaredEntities.length > 0) {
+        console.log(formatBold("\nUNDECLARED (read deeply, never declared in source):"));
+        for (const name of deep.undeclaredEntities)
+            console.log(`  - ${name}`);
+    }
+    if (acceptedCount > 0) {
+        console.log(formatBold("\nACCEPTED (in the baseline; not drift):"));
+        for (const entity of deep.accepted) {
+            console.log(`  - ${entity.name}: ${entity.changes.map((c) => c.path).join(", ")}`);
+        }
+    }
+}
+/**
+ * Render one `heldElsewhere()` property (#2162) — shared between the deep
+ * diff's HELD section and the plan's, so the two never disagree about what a
+ * held field looks like on the terminal.
+ */
+function formatHeldProperty(h) {
+    const live = "live" in h ? formatValue(h.live) : "<absent>";
+    const owner = h.owner ? ` [owner: ${h.owner}]` : "";
+    const suspicious = h.suspicious
+        ? " [SUSPICIOUS: no live value ever showed up here — check the holder is actually running, or that this is the field it writes]"
+        : "";
+    return `      ${h.path}: held by ${h.by} — ${live}${owner} (${h.reason})${suspicious}`;
+}
+/** Lines for every held property across a lexicon's entities, indented and grouped by entity name. */
+function renderHeldLines(held) {
+    const lines = [];
+    for (const entity of held) {
+        lines.push(`  - ${entity.name} (${entity.type})`);
+        for (const h of entity.held)
+            lines.push(formatHeldProperty(h));
+    }
+    return lines;
+}
+function renderLiveDiff(lexiconName, environment, diff) {
+    const counts = `${diff.missing.length} missing, ${diff.orphan.length} orphan, ` +
+        `${diff.disappeared.length} disappeared, ${diff.newlyObserved.length} newly observed, ` +
+        `${diff.driftedSinceSnapshot.length} drifted, ${diff.unchanged.length} unchanged` +
+        (diff.runtimeChildren.length > 0 ? `, ${diff.runtimeChildren.length} runtime` : "") +
+        (diff.unobserved.length > 0 ? `, ${diff.unobserved.length} unobserved` : "");
+    console.log(`\n${formatBold(lexiconName)} — environment: ${environment}`);
+    console.log(counts);
+    console.log("-".repeat(80));
+    if (diff.unobserved.length > 0) {
+        console.log(formatBold("\nUNOBSERVED (declared; chant could not read live state — status unknown):"));
+        for (const u of diff.unobserved) {
+            console.log(`  ? ${formatUnobserved(u.name, u)}`);
+        }
+    }
+    if (diff.missing.length > 0) {
+        console.log(formatBold("\nMISSING (declared, provider reports not in cloud):"));
+        for (const name of diff.missing) {
+            console.log(missingRow(diff, name));
+        }
+    }
+    if (diff.orphan.length > 0) {
+        console.log(formatBold("\nORPHAN (in cloud, not declared):"));
+        for (const name of diff.orphan)
+            console.log(`  - ${name}`);
+    }
+    if (diff.runtimeChildren.length > 0) {
+        console.log(formatBold("\nRUNTIME (owned by a declared resource; not drift, not an orphan — #1077):"));
+        for (const r of diff.runtimeChildren)
+            console.log(`  - ${r.name} (${r.type}) — owned by ${r.owner}`);
+    }
+    if (diff.disappeared.length > 0) {
+        console.log(formatBold("\nDISAPPEARED (in last snapshot, gone now):"));
+        for (const name of diff.disappeared)
+            console.log(`  - ${name}`);
+    }
+    if (diff.newlyObserved.length > 0) {
+        console.log(formatBold("\nNEWLY OBSERVED (declared, observed, no prior snapshot):"));
+        for (const name of diff.newlyObserved)
+            console.log(`  - ${name}`);
+    }
+    if (diff.driftedSinceSnapshot.length > 0) {
+        console.log(formatBold("\nDRIFTED (changed since last snapshot):"));
+        for (const drift of diff.driftedSinceSnapshot) {
+            console.log(`  - ${drift.name} (${drift.type})`);
+            for (const change of drift.changes) {
+                const oldStr = formatValue(change.oldValue);
+                const newStr = formatValue(change.newValue);
+                console.log(`      ${change.path}: ${oldStr} → ${newStr}`);
+            }
+        }
+    }
+}
+function formatValue(v) {
+    if (v === undefined)
+        return "<unset>";
+    if (typeof v === "string")
+        return v.length > 60 ? v.slice(0, 57) + "..." : v;
+    const json = JSON.stringify(v);
+    return json.length > 60 ? json.slice(0, 57) + "..." : json;
+}
+function renderLiveArtifactDiff(lexiconName, environment, diff) {
+    // Skip emission entirely when there's nothing to show — keeps the output
+    // clean for lexicons that only implement describeResources.
+    if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0 && diff.unchanged.length === 0) {
+        return;
+    }
+    const counts = `${diff.added.length} added, ${diff.removed.length} removed, ` +
+        `${diff.changed.length} changed, ${diff.unchanged.length} unchanged`;
+    console.log(`\n${formatBold(lexiconName)} (artifacts) — environment: ${environment}`);
+    console.log(counts);
+    console.log("-".repeat(80));
+    if (diff.added.length > 0) {
+        console.log(formatBold("\nARTIFACTS ADDED (in cloud now, not in last snapshot):"));
+        for (const name of diff.added)
+            console.log(`  - ${name}`);
+    }
+    if (diff.removed.length > 0) {
+        console.log(formatBold("\nARTIFACTS REMOVED (in last snapshot, gone now):"));
+        for (const name of diff.removed)
+            console.log(`  - ${name}`);
+    }
+    if (diff.changed.length > 0) {
+        console.log(formatBold("\nARTIFACTS CHANGED (metadata differs since last snapshot):"));
+        for (const drift of diff.changed) {
+            console.log(`  - ${drift.name} (${drift.type})`);
+            for (const change of drift.changes) {
+                const oldStr = formatValue(change.oldValue);
+                const newStr = formatValue(change.newValue);
+                console.log(`      ${change.path}: ${oldStr} → ${newStr}`);
+            }
+        }
+    }
+}
+/**
+ * chant lifecycle plan <environment> [lexicon]
+ *
+ * Promote the live diff to a typed, read-only change set: per-entity
+ * create / update / delete / adopt / noop / unobserved. Strictly read-only —
+ * never mutates, never deploys. Deletes are never proposed without ownership
+ * data (added in #121); an undeclared live resource is `adopt`; a declared
+ * entity chant could not read is `unobserved` and gets no proposal at all
+ * (#1089) — a create is only ever proposed against a confirmed absence.
+ */
+export async function runLifecyclePlan(ctx) {
+    const { args, plugins, serializers } = ctx;
+    const environment = args.extraPositional;
+    const lexiconFilter = args.extraPositional2;
+    if (!environment) {
+        console.error(formatError({ message: "Environment is required: chant lifecycle plan <environment> [lexicon]" }));
+        return 1;
+    }
+    const targetSerializers = lexiconFilter
+        ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
+        : serializers;
+    const { config } = await loadChantConfig(resolve("."));
+    // This invocation's parameters, so the declared side of the comparison is the estate
+    // the caller asked for rather than the parameter defaults (#1483).
+    const declaredParams = await commandBuildParams(config.buildParams, args);
+    if (!declaredParams)
+        return 1;
+    const buildResult = await build(resolveBuildRoot(args, config), targetSerializers, undefined, {
+        buildParams: declaredParams,
+        buildRoots: collectBuildRootContributors(plugins, config, resolve(".")),
+    });
+    if (buildResult.errors.length > 0) {
+        console.error(formatError({ message: "Build failed — fix errors before planning" }));
+        return 1;
+    }
+    await fetchLifecycle();
+    const lexicons = lexiconFilter ? [lexiconFilter] : Array.from(buildResult.manifest.lexicons);
+    // Multi-stack component projects deploy one CFN stack per component, so the
+    // single-stack-per-env observe below would see nothing live and plan every
+    // resource as "create". Resolve each component's cfn-deploy stack(s) and
+    // observe them all — the same fix runGraphLive uses (graph.ts). Empty for a
+    // single-stack project → the original single-call path is kept.
+    let componentStacks = [];
+    try {
+        const disc = await discoverComponents(resolveBuildRoot(args, config), { sandbox: args.sandbox });
+        const set = new Set();
+        for (const { component } of disc.components.values())
+            for (const s of cfnDeployStacks(component.deploy))
+                set.add(s);
+        componentStacks = [...set];
+    }
+    catch {
+        // no components / discovery failed → single-stack path
+    }
+    const merged = { env: environment, entries: [] };
+    let checked = 0;
+    // Held properties (#2162), across every lexicon this plan checks — not an
+    // action, so it rides beside `entries` rather than inside it.
+    const heldSets = [];
+    // Effect receipts (#1832): declared, diffed, and observed like any resource,
+    // but observe-only to the generic apply path — the plan compares live value
+    // to resolved expectation and proposes the fire, never a create/update.
+    const receipts = collectEffectReceipts(buildResult.entities);
+    const receiptReadings = new Map();
+    // Every lexicon's observed resources merged, for resolving a receipt's
+    // reference inputs against observed values / stack outputs at plan time.
+    const allObservedResources = {};
+    // #1166 — same self-sufficiency as `chant graph --live`: an environment can
+    // declare its own endpoint, applied here unless the ambient shell already
+    // set it. `chant lifecycle plan` is always a live read (no `--live` flag of
+    // its own), so this applies unconditionally.
+    // Names here, plugins there: the endpoint vars come from each lexicon's own
+    // emulator capability (#1345), so this needs the loaded plugin, not the name.
+    const endpointResult = applyLiveEndpoint(config.environments, environment, lexicons.map((name) => plugins.find((p) => p.name === name)).filter((p) => p !== undefined));
+    if (endpointResult.notice)
+        console.error(formatWarning({ message: endpointResult.notice }));
+    try {
+        for (const lexiconName of lexicons) {
+            const plugin = plugins.find((p) => p.name === lexiconName);
+            if (!plugin)
+                continue;
+            if (!plugin.describeResources) {
+                // Plan is entity-keyed; artifact-only lexicons have no declared axis.
+                if (!args.json) {
+                    console.error(formatWarning({
+                        message: `${lexiconName}: lexicon does not implement describeResources — skipping (no declared axis to plan against)`,
+                    }));
+                }
+                continue;
+            }
+            const declared = new Set();
+            const entities = new Map();
+            for (const [name, entity] of buildResult.entities) {
+                // A receipt has no `props` payload of its own but is declared, diffed,
+                // and observed like any resource (#1832) — it joins the declared axis
+                // so its lexicon's observation can confirm presence or absence.
+                if (entity.lexicon === lexiconName && (isObservableDeclarable(entity) || isEffectReceipt(entity))) {
+                    declared.add(name);
+                    entities.set(name, {
+                        entityType: entity.entityType,
+                        props: (isObservableDeclarable(entity) && entity.props != null ? entity.props : {}),
+                    });
+                }
+            }
+            const rawOutput = buildResult.outputs.get(lexiconName);
+            const buildOutput = rawOutput === undefined
+                ? ""
+                : typeof rawOutput === "string"
+                    ? rawOutput
+                    : rawOutput.primary;
+            const observed = await observeLexicon(plugin, {
+                environment,
+                buildOutput,
+                declared,
+                entities,
+                componentStacks,
+                owned: args.owned,
+                // A plan reading the wrong namespace proposes creates for resources
+                // that are running (#1629) — the same override the live diff takes.
+                ...(args.namespace ? { namespace: args.namespace } : {}),
+            });
+            Object.assign(allObservedResources, observed.resources);
+            // Held properties (#2162), behind `--deep` since #2405.
+            //
+            // A held property is never a proposal: it is computed against this same
+            // observation and carried on the plan beside `entries`, never folded
+            // into one. So the entries a plan proposes are identical whether this
+            // ran or not, and the only thing `--deep` buys is the HELD section.
+            //
+            // It used to run whenever the lexicon could, which made the read's cost
+            // a function of how many resources an estate holds rather than how it is
+            // organised. Measured on 528 resources across 8 stacks: 24 stack-shaped
+            // calls, and 496 from this pass. At ten thousand resources that is
+            // roughly twenty thousand calls against eighty, for a section the caller
+            // did not ask for.
+            //
+            // `--deep` is the flag `lifecycle snapshot` already uses for the same
+            // choice, and `lifecycle diff` still runs the pass unconditionally
+            // because property drift is the question it exists to answer.
+            if (args.deep && plugin.observeResourcesDeep) {
+                const deep = await deepDiffForLexicon(plugin, {
+                    environment,
+                    buildOutput,
+                    entities,
+                    componentStacks,
+                });
+                for (const entity of deep.held)
+                    heldSets.push({ ...entity, lexicon: lexiconName });
+                for (const s of suspiciousHeld(deep)) {
+                    console.error(formatWarning({
+                        message: `${lexiconName}: ${s.name}.${s.path} is declared heldElsewhere(by: "${s.by}") but no live value ever showed up there — the hand-over may never have happened.`,
+                    }));
+                }
+            }
+            for (const [receiptName, receipt] of receipts) {
+                if (receipt.lexicon !== lexiconName)
+                    continue;
+                const live = observed.resources[receiptName];
+                const hole = observed.unobserved[receiptName];
+                if (live) {
+                    receiptReadings.set(receiptName, {
+                        observed: true,
+                        present: true,
+                        value: readReceiptValue(live.attributes),
+                        type: live.type,
+                        ...(live.physicalId ? { physicalId: live.physicalId } : {}),
+                        lexicon: lexiconName,
+                    });
+                }
+                else if (hole) {
+                    receiptReadings.set(receiptName, {
+                        observed: false,
+                        present: false,
+                        lexicon: lexiconName,
+                        ...(hole.type ? { type: hole.type } : {}),
+                        unobservedReason: hole.reason,
+                        ...(hole.detail ? { unobservedDetail: hole.detail } : {}),
+                    });
+                }
+                else {
+                    // Neither returned nor named unobserved: the lexicon looked and
+                    // confirmed the receipt absent — the same claim the change set
+                    // reads off a bare observation (#1089).
+                    receiptReadings.set(receiptName, { observed: true, present: false, lexicon: lexiconName });
+                }
+            }
+            const content = await readSnapshot(environment, lexiconName);
+            const observedThen = content ? JSON.parse(content).resources : undefined;
+            const cs = buildChangeSet(environment, {
+                declared,
+                observedNow: observed.resources,
+                observedThen,
+                unobserved: observed.unobserved,
+                // The resolved read address rides every entry, not just unobserved
+                // ones — the diff path already passes it (#1620); plan lost it.
+                queried: observed.queried,
+                // A create carries its declaration's fingerprint (#3652), so the
+                // plan's digest moves when what it would create does.
+                definitions: declaredDefinitions(entities),
+            }, {
+                // Attribution survives the flat merge below (#1674).
+                lexicon: lexiconName,
+            });
+            // Disruption (#1665) is asked of THIS lexicon, before the merge: the
+            // deltas are paths into its own observation shape, and the replacement
+            // rules are in the spec it compiled. A lexicon that answers nothing
+            // leaves every update `unknown` — never `in-place`.
+            const classified = await annotateDisruption(cs, environment, plugin.classifyDisruption ? (o) => plugin.classifyDisruption(o) : undefined);
+            merged.entries.push(...classified.entries);
+            checked++;
+        }
+    }
+    finally {
+        endpointResult.restore();
+    }
+    if (checked === 0) {
+        console.error(formatWarning({
+            message: "No lexicons implement describeResources — nothing to plan",
+        }));
+        return 1;
+    }
+    // Receipt classification (#1832): live value vs resolved expectation.
+    // Absent/stale proposes the fire; unobservable is a loud hole; whatever the
+    // generic classification proposed for a receipt (a create, a delete) is
+    // replaced — the effect step is the sole writer, and a receipt is never a
+    // prune candidate.
+    if (receipts.size > 0) {
+        const receiptEntries = planReceipts(receipts, receiptReadings, observedValueResolver(allObservedResources));
+        mergeReceiptEntries(merged, receipts, receiptEntries);
+    }
+    merged.entries.sort((a, b) => a.name.localeCompare(b.name));
+    if (heldSets.length > 0)
+        merged.held = heldSets.sort((a, b) => a.name.localeCompare(b.name));
+    // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
+    // shapes have no room for it) still learn the plan has a hole (#1089). The
+    // `markdown` report carries the same wording in its own body instead — a
+    // reviewer reading a comment never sees this stderr.
+    for (const notice of unobservedPlanNotice(merged)) {
+        console.error(formatWarning({ message: notice }));
+    }
+    // Same reason as above (#1665): the `--json` and `--report gitlab-mr` shapes
+    // have no column for how much an update hurts.
+    for (const notice of disruptionNotices(merged)) {
+        console.error(formatWarning({ message: notice }));
+    }
+    // `--report gitlab-mr` emits the GitLab MR plan-widget artifact instead of the
+    // human render. Write it to a file (`tfplan.json`) in CI and declare it as
+    // `artifacts:reports:terraform` to light up the merge-request widget.
+    if (args.reportFile === "gitlab-mr") {
+        console.log(JSON.stringify(gitlabMrReport(merged)));
+        return 0;
+    }
+    // `--report markdown` emits the reviewer-facing projection (#1983) — a
+    // counts header, entries grouped and attributed to their lexicon, holes and
+    // disruption both carried in the body rather than left to stderr.
+    if (args.reportFile === "markdown") {
+        console.log(renderChangeSetMarkdown(merged));
+        return 0;
+    }
+    if (args.json) {
+        console.log(JSON.stringify(merged, null, 2));
+    }
+    else {
+        console.log(renderChangeSet(merged));
+    }
+    return 0;
+}
+/**
+ * chant lifecycle teardown <environment> (#1222).
+ *
+ * Enumerates what deleting the environment would remove: every live resource
+ * carrying this project's ownership marker (managed-by + `ownership.stack`)
+ * with the requested env identity. Stateless — live markers only, no build, no
+ * snapshot. Without `--yes` nothing is deleted; with it the planned set is
+ * executed per lexicon with one bounded retry pass over failures, and every
+ * candidate's outcome is reported (deleted / failed / not-prunable / retained / skipped —
+ * never silence). A production-like environment name additionally requires an
+ * interactive confirmation, or `--confirm-prod` non-interactively.
+ */
+export async function runLifecycleTeardown(ctx) {
+    const { args, plugins } = ctx;
+    const environment = args.extraPositional;
+    if (!environment) {
+        console.error(formatError({ message: "Environment is required: chant lifecycle teardown <environment>" }));
+        return 1;
+    }
+    const { config } = await loadChantConfig(resolve("."));
+    // Refuse an env the project does not declare — a typo here is the difference
+    // between tearing down `dev` and tearing down `prod`. Literal `environments`
+    // entries only (#1221's pattern entries would extend this same check).
+    const envErr = unknownEnvError(environment, config.environments);
+    if (envErr) {
+        console.error(formatError({ message: envErr }));
+        return 1;
+    }
+    // Teardown selects on the ownership marker; a project that stamps none has
+    // nothing to key on, and "delete what looks like mine" is not a fallback.
+    const stack = resolveOwnershipStack(config);
+    if (stack === undefined) {
+        console.error(formatError({
+            message: "This project declares no ownership.stack — teardown is marker-scoped and has nothing to select on",
+            hint: 'Set `ownership: { stack: "<name>" }` in chant.config.ts and deploy, so resources carry the marker teardown keys on.',
+        }));
+        return 1;
+    }
+    // The prod guard (#1222): a production-like name never falls to `--yes`
+    // alone. Interactive runs re-type the environment name; non-interactive
+    // runs say `--confirm-prod` explicitly. Checked before any live read so a
+    // refused teardown touches nothing at all.
+    if (args.yes && isProdLikeEnvironment(environment) && !args.confirmProd) {
+        if (!process.stdin.isTTY) {
+            console.error(formatError({
+                message: `"${environment}" looks like a production environment — --yes alone is not enough`,
+                hint: "Re-run with --yes --confirm-prod to tear it down non-interactively.",
+            }));
+            return 1;
+        }
+        const confirmed = await promptProdTeardown(environment);
+        if (!confirmed) {
+            console.error(formatError({ message: "Confirmation did not match — nothing was deleted." }));
+            return 1;
+        }
+    }
+    // #1166 — teardown is always a live read (and with --yes, a live write), so
+    // an environment's declared endpoint applies here too, unless the ambient
+    // shell already set it.
+    const readingPlugins = plugins.filter((p) => p.teardownOwned || p.describeResources || p.executeTeardown);
+    const endpointResult = applyLiveEndpoint(config.environments, environment, readingPlugins);
+    if (endpointResult.notice)
+        console.error(formatWarning({ message: endpointResult.notice }));
+    let plan;
+    let report;
+    try {
+        // A multi-stack project's declared stacks, for stack-shaped teardowns
+        // (aws enumerates and deletes whole CloudFormation stacks). A single-stack
+        // project passes nothing and the env-named default convention applies.
+        const deployedStacks = (config.stacks ?? []).map((s) => ({
+            name: s.name,
+            ...(s.region ? { region: s.region } : {}),
+        }));
+        plan = await planTeardown({
+            environment,
+            stack,
+            plugins,
+            ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+        });
+        if (args.yes) {
+            report = await executeTeardown({
+                environment,
+                stack,
+                plugins,
+                plan,
+                ...(deployedStacks.length > 0 ? { deployedStacks } : {}),
+            });
+        }
+    }
+    finally {
+        endpointResult.restore();
+    }
+    if (args.json) {
+        console.log(JSON.stringify(report ?? plan, null, 2));
+        return report && report.outcomes.some((o) => o.outcome === "failed") ? 1 : 0;
+    }
+    console.log(formatBold(args.yes
+        ? `Teardown — environment: ${environment}, stack: ${stack}`
+        : `Teardown plan — environment: ${environment}, stack: ${stack} (plan only — nothing is deleted)`));
+    if (plan.entries.length === 0) {
+        console.error(formatWarning({
+            message: `No live resources carry the marker stack "${stack}" + env "${environment}" — nothing would be deleted.` +
+                (plan.holes.length > 0
+                    ? " But this plan has holes (below) — parts of the estate could not be read, so \"nothing\" is a claim about what was readable, not about the environment."
+                    : " If this environment is deployed, check that its resources were stamped (ownership marking on, and the env identity resolved at build time)."),
+        }));
+    }
+    else {
+        console.log(`\n${plan.entries.length} resource(s) would be deleted:`);
+        console.log("RESOURCE".padEnd(28) + "TYPE".padEnd(32) + "MARKER".padEnd(24) + "LEXICON");
+        console.log("-".repeat(96));
+        for (const entry of plan.entries) {
+            console.log(entry.name.padEnd(28) +
+                entry.type.padEnd(32) +
+                `${entry.marker.stack}/${entry.marker.env}`.padEnd(24) +
+                entry.lexicon);
+        }
+    }
+    // Holes are loud (#1089): an unreadable kind is unknown, not absent, and the
+    // execution half must not treat this plan as the whole delete set.
+    if (plan.holes.length > 0) {
+        console.error(formatWarning({
+            message: `${plan.holes.length} hole(s) — resources chant may own but could not read. This plan is incomplete, not clean.`,
+        }));
+        console.log(formatBold("\nHOLES (stamped kinds the read could not cover):"));
+        for (const hole of plan.holes) {
+            console.log(`  ? ${hole.lexicon}: ${hole.name}${hole.type ? ` (${hole.type})` : ""} — ${hole.reason}${hole.detail ? `: ${hole.detail}` : ""}`);
+        }
+    }
+    if (plan.skipped.length > 0) {
+        console.error(formatWarning({
+            message: `Skipped (no teardown enumeration and no describeResources): ${plan.skipped.join(", ")} — those lexicons' resources are not in this plan.`,
+        }));
+    }
+    if (!report) {
+        console.error(formatWarning({ message: "Plan only — re-run with --yes to execute." }));
+        return 0;
+    }
+    if (report.outcomes.length > 0) {
+        console.log(formatBold("\nOutcomes:"));
+        console.log("RESOURCE".padEnd(28) + "OUTCOME".padEnd(14) + "LEXICON".padEnd(12) + "DETAIL");
+        console.log("-".repeat(96));
+        for (const o of report.outcomes) {
+            console.log(o.name.padEnd(28) +
+                o.outcome.padEnd(14) +
+                o.lexicon.padEnd(12) +
+                (o.detail ?? "") +
+                (o.retried ? " (after retry)" : ""));
+        }
+    }
+    const counts = { deleted: 0, failed: 0, "not-prunable": 0, retained: 0, skipped: 0 };
+    for (const o of report.outcomes)
+        counts[o.outcome]++;
+    console.log(`\n${counts.deleted} deleted, ${counts.failed} failed, ${counts["not-prunable"]} not prunable, ` +
+        `${counts.retained} retained, ${counts.skipped} skipped`);
+    if (report.unimplemented.length > 0) {
+        console.error(formatWarning({
+            message: `Not executed (no teardown execution in these lexicons yet): ${report.unimplemented.join(", ")} — their candidates are reported as skipped, not deleted.`,
+        }));
+    }
+    if (counts.retained > 0) {
+        console.error(formatWarning({
+            message: `${counts.retained} resource(s) retained — owned by this env but deliberately kept (generated-once secrets are never swept). ` +
+                `The environment is NOT clean while they exist; delete them explicitly (e.g. kubectl delete) if you mean to.`,
+        }));
+    }
+    if (plan.holes.length > 0) {
+        console.error(formatWarning({
+            message: "This teardown ran over an incomplete plan (holes above) — the environment cannot be called clean.",
+        }));
+    }
+    if (counts.failed > 0) {
+        console.error(formatError({
+            message: `${counts.failed} candidate(s) failed to delete after the retry pass — see the outcomes above.`,
+        }));
+        return 1;
+    }
+    return 0;
+}
+/**
+ * The interactive half of the prod guard: the operator re-types the
+ * environment name. Anything else — including EOF — refuses.
+ */
+async function promptProdTeardown(environment) {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolvePrompt) => {
+        rl.question(`"${environment}" looks like a production environment. Type the environment name to confirm teardown: `, (answer) => {
+            resolvePrompt(answer.trim() === environment);
+            rl.close();
+        });
+        // EOF (Ctrl-D) closes the interface without answering — that is a refusal.
+        rl.on("close", () => resolvePrompt(false));
+    });
+}
+/**
+ * chant lifecycle log [environment]
+ */
+export async function runLifecycleLog(ctx) {
+    const environment = ctx.args.extraPositional;
+    await fetchLifecycle();
+    const entries = await listSnapshots({ environment });
+    if (entries.length === 0) {
+        console.error(formatError({ message: "No state snapshots found" }));
+        return 1;
+    }
+    for (const entry of entries) {
+        const date = entry.date.split("T")[0];
+        console.log(`${entry.commit.slice(0, 7)}  ${date}  ${entry.message}`);
+    }
+    return 0;
+}
+/**
+ * The region core hands `describeIdentity` — the one the environment's stacks
+ * declare, when they declare exactly one (#1261's `stacks[].region`).
+ *
+ * Stacks that declare none, or that disagree, resolve to `undefined`, and the
+ * lexicon then resolves the region its own read path would. Guessing one of
+ * several would report a binding half the estate does not use, which is the
+ * failure this command exists to prevent.
+ */
+function singleDeclaredRegion(targets) {
+    const regions = new Set(targets.map((t) => t.region).filter((r) => Boolean(r)));
+    return regions.size === 1 ? [...regions][0] : undefined;
+}
+/**
+ * chant lifecycle whoami <environment> [lexicon] [--json] [--strict]
+ *
+ * Read-only pre-flight (#1982): who chant would act as in each configured
+ * lexicon, and what that principal is scoped to, before it acts. Never
+ * mutates, never gates — `--strict` is the only way this exits non-zero on an
+ * unresolved row, and a lexicon that answers for nothing is reported as such
+ * rather than as an empty identity.
+ */
+export async function runLifecycleWhoami(ctx) {
+    const { args, plugins } = ctx;
+    const environment = args.extraPositional;
+    const lexiconFilter = args.extraPositional2;
+    if (!environment) {
+        console.error(formatError({
+            message: "Environment is required: chant lifecycle whoami <environment> [lexicon] [--json] [--strict]",
+        }));
+        return 1;
+    }
+    const projectPath = resolve(".");
+    const { config } = await loadChantConfig(projectPath);
+    const declaredEnvNames = environmentNames(config.environments);
+    if (declaredEnvNames && !matchesDeclaredEnvironment(config.environments, environment)) {
+        console.error(formatError({
+            message: `Unknown environment "${environment}"`,
+            hint: `Defined environments: ${declaredEnvNames.join(", ")}`,
+        }));
+        return 1;
+    }
+    const targetPlugins = lexiconFilter ? plugins.filter((p) => p.name === lexiconFilter) : plugins;
+    if (targetPlugins.length === 0) {
+        console.error(formatError({
+            message: `Lexicon "${lexiconFilter}" is not configured for this project`,
+            hint: `Configured: ${plugins.map((p) => p.name).join(", ") || "(none)"}`,
+        }));
+        return 1;
+    }
+    // The environment's declared endpoint applies here exactly as it does to a
+    // `--live` read (#1166). Without it whoami would report the identity of real
+    // AWS while `describeResources` reads the emulator — the wrong-target answer
+    // this command exists to make visible.
+    const endpointResult = applyLiveEndpoint(config.environments, environment, targetPlugins);
+    if (endpointResult.notice)
+        console.error(formatWarning({ message: endpointResult.notice }));
+    const region = singleDeclaredRegion(resolveStackTargets(args, config));
+    let rows;
+    try {
+        rows = await describeIdentities(targetPlugins, {
+            environment,
+            ...(region ? { region } : {}),
+            cwd: projectPath,
+        });
+    }
+    finally {
+        endpointResult.restore();
+    }
+    if (args.json) {
+        console.log(JSON.stringify({ environment, identities: rows }, null, 2));
+    }
+    else {
+        printIdentityTable(rows);
+    }
+    // Never a gate by default: an unresolved identity is a report, and a
+    // pre-flight command that fails the build has stopped being pre-flight.
+    const unresolved = rows.filter((r) => r.status === "unresolved");
+    if (args.strict && unresolved.length > 0) {
+        console.error(formatError({
+            message: `--strict: ${unresolved.length} lexicon(s) could not resolve an identity: ${unresolved.map((r) => r.lexicon).join(", ")}`,
+        }));
+        return 1;
+    }
+    return 0;
+}
+function printIdentityTable(rows) {
+    if (rows.length === 0) {
+        console.error(formatWarning({ message: "No lexicons are configured for this project" }));
+        return;
+    }
+    const width = (pick) => Math.max(...rows.map((r) => pick(r).length));
+    const lexWidth = Math.max(width((r) => r.lexicon), "LEXICON".length);
+    const idWidth = Math.max(width((r) => r.identity ?? identityStatusText(r)), "IDENTITY".length);
+    const scopeWidth = Math.max(width((r) => r.scope ?? ""), "SCOPE".length);
+    console.log("LEXICON".padEnd(lexWidth + 2) + "IDENTITY".padEnd(idWidth + 2) + "SCOPE".padEnd(scopeWidth + 2) + "SOURCE");
+    for (const row of rows) {
+        const identity = row.status === "reported" ? (row.identity ?? "") : identityStatusText(row);
+        console.log(row.lexicon.padEnd(lexWidth + 2) +
+            identity.padEnd(idWidth + 2) +
+            (row.scope ?? "").padEnd(scopeWidth + 2) +
+            (row.source ?? ""));
+    }
+    // The resolved address and the reason's detail are both sentences, so they
+    // go under the table rather than widening a column every row pays for.
+    for (const row of rows) {
+        if (row.endpoint)
+            console.error(`  ${row.lexicon}: resolved endpoint ${row.endpoint}`);
+        if (row.detail)
+            console.error(`  ${row.lexicon}: ${row.detail}`);
+    }
+}
+/**
+ * Fallback for unknown state subcommands.
+ */
+export async function runLifecycleUnknown(ctx) {
+    console.error(formatError({
+        message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
+        hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle whoami, chant lifecycle teardown, chant lifecycle log",
+    }));
+    return 1;
+}
+function printSnapshotTable(snapshot) {
+    console.log("RESOURCE".padEnd(20) + "TYPE".padEnd(28) + "PHYSICAL ID".padEnd(44) + "STATUS");
+    console.log("-".repeat(100));
+    for (const [name, meta] of Object.entries(snapshot.resources)) {
+        const physicalId = meta.physicalId ?? "";
+        const truncId = physicalId.length > 40 ? physicalId.slice(0, 37) + "..." : physicalId;
+        console.log(name.padEnd(20) +
+            meta.type.padEnd(28) +
+            truncId.padEnd(44) +
+            meta.status);
+    }
+}
+/**
+ * chant lifecycle affected --base <ref> [--head <ref>] [--include-dependents] [--json]
+ *
+ * Read-only: report which stacks a change affects (directly-changed via artifact
+ * diff, dependents via the cross-stack graph, external-input as indeterminate).
+ * Returns the set; fanning plan/apply over it is an Op the user composes.
+ *
+ * `config.stacks` is passed through, so on a multi-stack project the answer is
+ * keyed by deployed **stack name** — the name a component's `cfn-deploy` step
+ * uses — instead of by lexicon partition. That is what lets `chant components
+ * fan-out` join a change set to the components that deploy it; an aws-only
+ * estate of fifteen stacks used to answer "aws" no matter which one moved. A
+ * project with no `stacks` declared is untouched: one build of the source root,
+ * one lexicon-keyed answer.
+ *
+ * The cost of per-stack mode is that `dependents` comes back empty (the build
+ * carries cross-lexicon edges, not stack ones), so `--include-dependents` prints
+ * a note saying where the downstream relation actually lives rather than showing
+ * an empty list as if it meant "nothing downstream".
+ */
+export async function runLifecycleAffected(ctx) {
+    const { args, plugins } = ctx;
+    if (!args.base) {
+        console.error(formatError({
+            message: "Base ref is required: chant lifecycle affected --base <ref> [--head <ref>] [--include-dependents]",
+        }));
+        return 1;
+    }
+    const { config } = await loadChantConfig(resolve("."));
+    // A multi-stack project's `stacks[].src` entries are written relative to the
+    // project root, and they are themselves the scoping, so `--src`/`sourceDir`
+    // does not narrow the root a second time (see `AffectedStacksOptions.stacks`).
+    const projectPath = config.stacks?.length ? resolve(".") : resolveBuildRoot(args, config);
+    let result;
+    try {
+        result = await affectedStacks({
+            projectPath,
+            serializers: plugins.map((p) => p.serializer),
+            stacks: config.stacks,
+            baseRef: args.base,
+            headRef: args.head,
+            includeDependents: args.includeDependents,
+        });
+    }
+    catch (err) {
+        console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+        return 1;
+    }
+    // Per-stack mode has no stack graph to walk, so an empty `dependents` here
+    // means "not computed", not "nothing downstream". Say so on stderr — silently
+    // handing back an empty list is the failure this command exists to avoid.
+    const multiStack = (config.stacks?.length ?? 0) > 0;
+    if (multiStack && args.includeDependents) {
+        console.error(formatWarning({
+            message: "Dependents are not computed for a multi-stack project: the downstream relation between deployed stacks is stated by the components' dependsOn, not by the build.",
+            hint: "Run chant components fan-out to walk it.",
+        }));
+    }
+    if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    if (result.changed.length === 0 && result.dependents.length === 0) {
+        console.error(formatSuccess("No stacks affected"));
+    }
+    else {
+        console.log(formatBold("Directly changed:"));
+        console.log(result.changed.length ? result.changed.map((s) => `  ${s}`).join("\n") : "  (none)");
+        if (args.includeDependents) {
+            console.log(formatBold("\nDependents (consume a changed stack):"));
+            console.log(result.dependents.length ? result.dependents.map((s) => `  ${s}`).join("\n") : "  (none)");
+        }
+    }
+    if (result.indeterminate.length > 0) {
+        console.error(formatWarning({
+            message: `External-input stacks — cannot confirm from source: ${result.indeterminate.join(", ")}`,
+        }));
+    }
+    return 0;
+}