@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/handlers/components.js

@@ -0,0 +1,730 @@
+/**
+ * `chant components` handlers — release ledger + status surface (#568, epic
+ * #551 "Build & deploy observability").
+ *
+ * Two subcommands:
+ *  - `chant components release record` — append one immutable release record
+ *    to the `chant/lifecycle` orphan branch (../../lifecycle/release-ledger.ts).
+ *    A deploy composition calls this (typically from a `Verify` phase, or the
+ *    CI job that ran `chant build --components --generate <lexicon>`) once
+ *    the artifact digest, git sha, and run id are known.
+ *  - `chant components status [env]` — the status surface: joins the release
+ *    ledger against live evidence (`lifecycle diff --live` + ownership,
+ *    reused via `buildChangeSet`) by digest, and reports what's built vs
+ *    what's deployed where, flagging unrecorded deploys and drift.
+ *
+ * `componentBom`/`build.reproducibility` (#614) resolve to real data as of
+ * #609: for every recorded digest in an environment's ledger, this handler
+ * looks up the persisted `BuildArchiveManifest` that produced it
+ * (`findBuildManifestByArtifactDigest`, ../../lifecycle/build-ledger-
+ * store.ts) and derives `buildsByDigest`/`componentBomByDigest` from it via
+ * `buildLedgerEntries`/`componentBomSummary` — the same derivation
+ * `build-ledger.test.ts` already exercises directly, now fed by a real
+ * manifest instead of a hand-built one. A digest with no persisted manifest
+ * (predates #609, or was recorded via `chant components release` alone with
+ * no corresponding build) simply has no entry in either map, so `build`/
+ * `componentBom` fall back to `null` exactly as before — no regression for
+ * ledgers with no persisted manifests at all.
+ */
+import { resolve, join, dirname } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { getHeadCommit, fetchLifecycle, pushLifecycle, readSnapshot, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git.js";
+import { appendReleaseRecord, readReleaseLedger, listReleaseEnvironments, latestPerComponent, resolveRunId, InvalidReleaseRecordError, } from "../../lifecycle/release-ledger.js";
+import { persistReleasePlan, InvalidReleasePlanError } from "../../lifecycle/plan-ledger.js";
+import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence } from "../../lifecycle/status.js";
+import { commandBuildParams } from "../build-params-cli.js";
+import { buildChangeSet } from "../../lifecycle/change-set.js";
+import { buildLedgerEntries, componentBomSummary } from "../../lifecycle/build-ledger.js";
+import { findBuildManifestByArtifactDigest, readBuildManifest } from "../../lifecycle/build-ledger-store.js";
+import { loadChantConfig } from "../../config.js";
+import { applyLiveEndpoint } from "../../live-endpoint.js";
+import { isObservableDeclarable } from "../../declarable.js";
+import { build } from "../../build.js";
+import { discoverComponents } from "../../components/discover.js";
+import { formatError, formatWarning, formatSuccess, formatBold } from "../format.js";
+import { normalizeObservation, mergeObservations, unobservedAll } from "../../observation.js";
+import { deployUnits } from "../../components/deploy-units.js";
+import { sortedJsonReplacer } from "../../utils.js";
+import { withoutReadFlags } from "../../lifecycle/legacy-digest.js";
+/**
+ * chant components release <env> --component <name> --digest <sha256:...>
+ *   [--git-sha <sha>] [--run-id <id>] [--actor <name>]
+ *
+ * `--git-sha` defaults to the current HEAD commit (`git rev-parse HEAD`);
+ * `--run-id` defaults to common CI run-id env vars
+ * (`GITHUB_RUN_ID`/`CI_PIPELINE_ID`) or a locally generated id; `--actor`
+ * defaults to common CI actor env vars
+ * (`GITHUB_ACTOR`/`GITLAB_USER_LOGIN`/`USER`) but must resolve to *something*
+ * — an unattributed release record defeats the point of a release ledger, so
+ * this is the one field with no silent fallback to a placeholder.
+ *
+ * The timestamp is always a real `new Date()` taken here, at record time —
+ * never threaded in from elsewhere and never mocked in production code, per
+ * #568: "the session cannot call Date.now() in some contexts; take the
+ * timestamp from the environment/CLI at record time."
+ *
+ * `--release-plan <file>` (ws-055, #2733) takes `--digest`'s place: the file is a
+ * release plan JSON object naming its own `digest` field, persisted
+ * content-addressed to `_plans/<digest>.json` (../../lifecycle/plan-
+ * ledger.ts) before the release record is appended, so the record's digest
+ * always names a plan this checkout can resolve. Passing both requires them
+ * to agree — a plan is content-addressed by its own digest, so a caller
+ * naming a different one is a mistake, not an override.
+ */
+export async function runComponentsReleaseRecord(ctx) {
+    const { args } = ctx;
+    const environment = args.extraPositional;
+    if (!environment) {
+        console.error(formatError({
+            message: "Environment is required: chant components release <env> --component <name> --digest <sha256:...>",
+        }));
+        return 1;
+    }
+    const component = args.component;
+    let digest = args.digest;
+    let plan;
+    if (args.releasePlanFile) {
+        let raw;
+        try {
+            raw = await readFile(args.releasePlanFile, "utf-8");
+        }
+        catch (err) {
+            console.error(formatError({ message: `Could not read --release-plan ${args.releasePlanFile}: ${err instanceof Error ? err.message : String(err)}` }));
+            return 1;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            console.error(formatError({ message: `--release-plan ${args.releasePlanFile} is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }));
+            return 1;
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            console.error(formatError({ message: `--release-plan ${args.releasePlanFile} must be a JSON object` }));
+            return 1;
+        }
+        plan = parsed;
+        if (typeof plan.digest !== "string" || plan.digest.length === 0) {
+            console.error(formatError({ message: `--release-plan ${args.releasePlanFile} is missing its own "digest" field — a release plan is content-addressed by its own digest` }));
+            return 1;
+        }
+        if (digest !== undefined && digest !== plan.digest) {
+            console.error(formatError({ message: `--digest ${digest} does not match --release-plan ${args.releasePlanFile}'s own digest ${plan.digest}` }));
+            return 1;
+        }
+        digest = plan.digest;
+    }
+    if (!component || !digest) {
+        console.error(formatError({
+            message: "--component and --digest are required",
+            hint: "chant components release <env> --component <name> --digest <sha256:...> [--release-plan <file>] [--git-sha <sha>] [--run-id <id>] [--actor <name>] [--approver <name>]",
+        }));
+        return 1;
+    }
+    const gitSha = args.gitSha ?? (await getHeadCommit().catch(() => undefined));
+    // Id + origin resolved together from the same environment (#2045), so the
+    // recorded runId always says which id space it lives in and how to reach it.
+    const { runId, runOrigin } = resolveRunId(args.runId);
+    const actor = args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+    // Who approved a gated change (#1035). Optional — omitted for an ungated
+    // change, and never defaulted to `actor`, since recording the approver as the
+    // triggerer would defeat the separation-of-duties the field exists to attest.
+    const approver = args.approver;
+    if (!gitSha) {
+        console.error(formatError({ message: "Could not resolve --git-sha (not in a git repo?) — pass it explicitly." }));
+        return 1;
+    }
+    if (!actor) {
+        console.error(formatError({
+            message: "Could not resolve --actor from the environment",
+            hint: "Pass --actor explicitly, or set GITHUB_ACTOR / GITLAB_USER_LOGIN / USER.",
+        }));
+        return 1;
+    }
+    const timestamp = new Date().toISOString();
+    try {
+        if (plan)
+            await persistReleasePlan(plan);
+        const { commit, record } = await appendReleaseRecord({
+            component,
+            env: environment,
+            digest,
+            gitSha,
+            runId,
+            ...(runOrigin ? { runOrigin } : {}),
+            timestamp,
+            actor,
+            ...(approver ? { approver } : {}),
+        });
+        await pushLifecycle();
+        if (args.json) {
+            console.log(JSON.stringify(record, null, 2));
+        }
+        else {
+            console.error(formatSuccess(`Recorded release: ${formatBold(component)}@${environment} -> ${digest} (commit ${commit.slice(0, 7)})`));
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof InvalidReleaseRecordError || err instanceof InvalidReleasePlanError) {
+            console.error(formatError({ message: err.message }));
+            return 1;
+        }
+        if (err instanceof StaleLifecycleBranchError) {
+            console.error(formatError({
+                message: err.message,
+                hint: `Pull and retry: \`git fetch origin chant/lifecycle:chant/lifecycle\` && \`chant components release ${environment} --component ${component} --digest ${digest}\`.`,
+            }));
+            return 1;
+        }
+        throw err;
+    }
+}
+/**
+ * chant components export <env> --component <name> [--digest <manifestDigest>]
+ *   -o <dir> [--json]
+ *
+ * Materializes a persisted `BuildArchiveManifest` (#609,
+ * ../../lifecycle/build-ledger-store.ts) to a portable directory: every
+ * `image`/`template`/`asset`/`sbom` entry is copied byte-for-byte from where
+ * the build that produced it left it on disk (its `path`, resolved against
+ * the current working directory — the same directory a component's
+ * `docker-build`/`addArchiveTemplate`/etc. step wrote it into) under that
+ * same archive-relative path in `-o <dir>`, plus a `manifest.json` so the
+ * directory is self-describing without chant. No re-synthesis: this reads
+ * bytes a prior `chant build`/`run --components` already produced, never
+ * regenerates them (#929) — the "byte-identical, promote-by-digest" contract
+ * the build archive is built on (see ../../components/verbs/build-archive.ts).
+ *
+ * Manifest resolution:
+ *  - `--digest <manifestDigest>` reads it directly (`readBuildManifest`),
+ *    independent of any environment/release record.
+ *  - Otherwise resolves "the manifest behind this component's most recent
+ *    successful run" in `<env>`: the latest release record's own
+ *    `manifestDigest` when it was recorded, else a reverse lookup by its
+ *    promoted artifact digest (`findBuildManifestByArtifactDigest`) — the
+ *    same join `chant components status` already performs.
+ *
+ * A source file missing on disk (the build that produced the manifest ran
+ * somewhere else, or its output was since cleaned) is reported per entry
+ * rather than silently dropped; the command exits non-zero so an incomplete
+ * export is never mistaken for a complete one.
+ */
+export async function runComponentsExport(ctx) {
+    const { args } = ctx;
+    const environment = args.extraPositional;
+    const component = args.component;
+    const outDir = args.output;
+    const usage = "chant components export <env> --component <name> [--digest <manifestDigest>] -o <dir>";
+    if (!outDir) {
+        console.error(formatError({ message: "-o/--output <dir> is required", hint: usage }));
+        return 1;
+    }
+    await fetchLifecycle();
+    let manifest;
+    if (args.digest) {
+        const resolved = await readBuildManifest(args.digest);
+        if (!resolved) {
+            console.error(formatError({ message: `No persisted build manifest found for digest ${args.digest}` }));
+            return 1;
+        }
+        if (component && resolved.component !== component) {
+            console.error(formatWarning({
+                message: `--component ${component} does not match the resolved manifest's component (${resolved.component}) — exporting the manifest at --digest ${args.digest} anyway`,
+            }));
+        }
+        manifest = resolved;
+    }
+    else {
+        if (!environment || !component) {
+            console.error(formatError({
+                message: "Environment and --component are required unless --digest <manifestDigest> is given",
+                hint: usage,
+            }));
+            return 1;
+        }
+        const ledger = await readReleaseLedger(environment);
+        const latest = latestPerComponent(ledger.records).get(component);
+        if (!latest) {
+            console.error(formatError({
+                message: `No release record for component "${component}" in environment "${environment}"`,
+            }));
+            return 1;
+        }
+        const resolved = latest.manifestDigest
+            ? await readBuildManifest(latest.manifestDigest)
+            : await findBuildManifestByArtifactDigest(latest.digest);
+        if (!resolved) {
+            console.error(formatError({
+                message: `No persisted build manifest found for ${component}@${environment}'s recorded digest ${latest.digest}`,
+                hint: "The build predates #609, or was recorded via `chant components release` alone with no corresponding `chant build`/`run --components`.",
+            }));
+            return 1;
+        }
+        manifest = resolved;
+    }
+    const targetDir = resolve(outDir);
+    const sourceRoot = resolve(".");
+    await mkdir(targetDir, { recursive: true });
+    const entries = [...manifest.contents].sort((a, b) => a.path.localeCompare(b.path));
+    const results = [];
+    for (const entry of entries) {
+        try {
+            const bytes = await readFile(resolve(sourceRoot, entry.path));
+            const target = join(targetDir, entry.path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, bytes);
+            results.push({ kind: entry.kind, path: entry.path, digest: entry.digest, status: "materialized" });
+        }
+        catch (err) {
+            results.push({
+                kind: entry.kind,
+                path: entry.path,
+                digest: entry.digest,
+                status: "missing",
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // The exported manifest is the recorded one; read-side flags (#2514) stay out of it.
+    await writeFile(join(targetDir, "manifest.json"), JSON.stringify(withoutReadFlags(manifest), sortedJsonReplacer, 2));
+    const missing = results.filter((r) => r.status === "missing");
+    if (args.json) {
+        console.log(JSON.stringify({
+            component: manifest.component,
+            manifestDigest: manifest.manifestDigest,
+            ...(manifest.flags ? { flags: manifest.flags } : {}),
+            outDir: targetDir,
+            entries: results,
+        }, null, 2));
+    }
+    else {
+        console.log(formatBold(`${manifest.component} (${manifest.manifestDigest}) -> ${targetDir}`));
+        for (const r of results) {
+            const status = r.status === "materialized" ? formatSuccess("ok") : formatError({ message: r.reason ?? "missing" });
+            console.log(`  ${r.kind.padEnd(10)}${r.path.padEnd(40)}${status}`);
+        }
+        console.log(`  ${"manifest".padEnd(10)}${"manifest.json".padEnd(40)}${formatSuccess("ok")}`);
+    }
+    if (missing.length > 0) {
+        console.error(formatError({
+            message: `${missing.length} of ${results.length} archive entr${missing.length === 1 ? "y" : "ies"} not found on disk — export incomplete`,
+            hint: `Run this from the checkout where the build that produced ${manifest.manifestDigest} still has its output on disk.`,
+        }));
+        return 1;
+    }
+    console.error(formatSuccess(`Exported ${results.length} entr${results.length === 1 ? "y" : "ies"} + manifest.json to ${targetDir}`));
+    return 0;
+}
+/**
+ * chant components status [env] [--live] [--json] [--compare-to <env>]
+ *
+ * Answers "what's built" and "what's deployed where," joined by digest.
+ * Without `--live`, reports the release ledger alone (recorded vs unrecorded
+ * is meaningless without live evidence, so every recorded row reports
+ * `unknown` reconciliation — still useful as a pure ledger read). With
+ * `--live`, joins against `lifecycle diff --live` + ownership (reusing
+ * `buildChangeSet`, the same classification `lifecycle plan` already
+ * trusts) to flag unrecorded deploys and drift.
+ *
+ * Omitting `<env>` reports every environment that has release records.
+ * `--compare-to <env>` answers the single-query cross-environment question
+ * the epic names explicitly: "which build is in `<env>`, and is it the one
+ * tested in `<compare-to>`."
+ */
+/** Every distinct `cfn-deploy` stack name a component's deploy phases target. A
+ * step may itself be a nested `Phase`, so walk recursively; a resolved component
+ * carries the stack as a concrete string.
+ *
+ * Exported for `chant graph --live` (../handlers/graph.ts's `runGraphLive`,
+ * #57): the same per-component stack resolution this file uses for `chant
+ * components status --live` is also how the live graph learns which stacks to
+ * observe on a multi-stack, per-component project (`describeResources`'s
+ * single-stack-named-after-the-environment convention never matches one). */
+export function cfnDeployStacks(deploy) {
+    // The CloudFormation slice of the generic deploy-unit walk (#1495) — kept
+    // because `chant graph --live`'s stack enrichment is genuinely CFN-shaped.
+    return deployUnits(deploy)
+        .filter((u) => u.lexicon === "aws")
+        .map((u) => u.unit);
+}
+/**
+ * Per-component stack presence for `--live`: resolve each component's own
+ * `cfn-deploy` stack(s) and observe them directly via a lexicon's
+ * `describeStackStatus`. This is the multi-stack component signal that
+ * `describeResources` (entity-keyed, single-stack-per-env) misses (#57): a
+ * component whose stack is present reconciles as live/owned, joined to the DAG
+ * by component name. Components with no `cfn-deploy` stack — or where the
+ * observer can't determine any of theirs — are omitted, so the change-set
+ * evidence still governs them.
+ */
+async function observeComponentStacks(components, plugins, environment) {
+    // Observer per unit's own lexicon (#1495): a component's kubectl-apply unit
+    // is read by the k8s lexicon, its cfn-deploy stack by aws. A unit whose
+    // lexicon ships no describeStackStatus is skipped — the same absent-observer
+    // degradation as before, per unit instead of per project.
+    const observerFor = (lexicon) => plugins.find((p) => p.name === lexicon && p.describeStackStatus);
+    const evidence = new Map();
+    for (const [name, { component }] of components) {
+        const units = deployUnits(component.deploy).filter((u) => observerFor(u.lexicon));
+        const stacks = units.map((u) => u.unit);
+        if (stacks.length === 0)
+            continue;
+        const observed = await Promise.all(units.map((u) => observerFor(u.lexicon).describeStackStatus({ environment, stack: u.unit }).catch(() => null)));
+        const determinate = observed.filter((o) => o !== null);
+        if (determinate.length === 0) {
+            // Every stack read came back indeterminate (the lexicon's own "I cannot
+            // tell" — see describeStackStatus). Record the hole rather than dropping
+            // the component, which would leave a recorded component reading `stale`
+            // (#1089).
+            evidence.set(name, {
+                live: false,
+                unobserved: {
+                    reason: "read-failed",
+                    detail: `no determinate status for stack(s): ${stacks.join(", ")}`,
+                },
+            });
+            continue;
+        }
+        const present = determinate.every((o) => o.present);
+        // Surface the (first present, else first) stack's raw status for a richer
+        // palette than the reconciliation verdict. One cfn-deploy stack per component
+        // is the norm; a multi-stack component reports its representative unit.
+        const repr = determinate.find((o) => o.present) ?? determinate[0];
+        // Some-but-not-all present is its own answer (#1528): `live` stays false —
+        // deployed means all of it — but the split and the missing unit names ride
+        // along, so the row can say "half up" instead of "nothing observed live"
+        // while its own `stack` field shows a healthy unit.
+        const presentCount = determinate.filter((o) => o.present).length;
+        const missing = determinate.filter((o) => !o.present).map((o) => o.stack);
+        evidence.set(name, {
+            live: present,
+            ownership: present ? "owned" : undefined,
+            stack: { name: repr.stack, status: repr.status, healthy: repr.healthy },
+            ...(presentCount > 0 && !present ? { partial: { present: presentCount, total: determinate.length, missing } } : {}),
+        });
+    }
+    return evidence;
+}
+/**
+ * The last lifecycle snapshot(s) for one lexicon, as `components status --live`
+ * reads them for its drift baseline (#2513). Reads the stack-keyed snapshot for
+ * each stack the status read targets and the unstacked one `lifecycle plan`
+ * reads, merging resources (a stack's own snapshot wins) and remembering, per
+ * entity, which snapshot's timestamp it came from. A missing or unreadable
+ * snapshot is no baseline, never an error: with none, nothing can have changed
+ * since, and the status falls back to identity and presence.
+ */
+async function readStatusBaseline(environment, lexicon, stacks) {
+    const keys = [...new Set([...stacks.filter((s) => !!s).map((s) => snapshotStorageKey(lexicon, s)), snapshotStorageKey(lexicon)])];
+    let resources;
+    const timestamps = new Map();
+    for (const key of keys) {
+        let snap;
+        try {
+            const content = await readSnapshot(environment, key);
+            snap = content ? JSON.parse(content) : undefined;
+        }
+        catch {
+            snap = undefined;
+        }
+        if (!snap?.resources)
+            continue;
+        resources ?? (resources = {});
+        for (const [name, meta] of Object.entries(snap.resources)) {
+            if (Object.prototype.hasOwnProperty.call(resources, name))
+                continue;
+            resources[name] = meta;
+            if (snap.timestamp)
+                timestamps.set(name, snap.timestamp);
+        }
+    }
+    return { resources, timestamps };
+}
+export async function runComponentsStatus(ctx) {
+    const { args, plugins, serializers } = ctx;
+    const requestedEnv = args.extraPositional;
+    await fetchLifecycle();
+    const environments = requestedEnv ? [requestedEnv] : await listReleaseEnvironments();
+    if (environments.length === 0) {
+        console.error(formatWarning({
+            message: requestedEnv
+                ? `No release records found for environment "${requestedEnv}"`
+                : "No release records found in any environment",
+        }));
+        return args.json ? (console.log(JSON.stringify([])), 0) : 0;
+    }
+    // Discover components (best-effort) so a live/owned-but-never-recorded
+    // component still gets a row, not just those that appear in the ledger.
+    const { config } = await loadChantConfig(resolve("."));
+    const discovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."), {
+        sandbox: args.sandbox,
+    });
+    const allComponents = [...discovery.components.keys()];
+    // Component -> live entity/resource name(s) it owns (#598), when declared
+    // explicitly via `Component.liveNames`. Components with no `liveNames`
+    // simply have no entry here, so `liveEvidenceFromChangeSet` falls back to
+    // the name == entity join — no regression for the pilot components.
+    const liveNameMapping = new Map();
+    for (const [name, discovered] of discovery.components) {
+        if (discovered.component.liveNames?.length) {
+            liveNameMapping.set(name, discovered.component.liveNames);
+        }
+    }
+    const allRows = [];
+    const ledgerByEnv = new Map();
+    for (const environment of environments) {
+        const ledger = await readReleaseLedger(environment);
+        ledgerByEnv.set(environment, ledger);
+        if (ledger.malformed > 0) {
+            console.error(formatWarning({ message: `${environment}: skipped ${ledger.malformed} malformed ledger line(s)` }));
+        }
+        let liveEvidence;
+        if (args.live) {
+            // #1166 — an environment can declare its own endpoint (a local emulator
+            // like Floci), applied here unless the ambient shell already set it, so
+            // `--live` status doesn't silently read the wrong account per environment.
+            const endpointResult = applyLiveEndpoint(config.environments, environment, plugins.filter((p) => p.describeResources || p.describeStackStatus));
+            if (endpointResult.notice)
+                console.error(formatWarning({ message: endpointResult.notice }));
+            try {
+                const targetSerializers = serializers;
+                // With this invocation's parameters (#1483). Built on defaults, the
+                // declared half of the comparison is a different estate from the one
+                // deployed, and every resource the real parameter declares reads as
+                // absent.
+                const statusParams = await commandBuildParams(config.buildParams, args);
+                if (!statusParams)
+                    return 1;
+                const buildResult = await build(resolve(args.src ?? config.sourceDir ?? "."), targetSerializers, undefined, {
+                    buildParams: statusParams,
+                });
+                // Which deployed stack(s) to read the change set from (behold#100).
+                //
+                // `describeResources` defaults to the single-stack convention — the
+                // stack named after the environment — which is wrong for exactly the
+                // projects this command exists for: a component project deploys the
+                // stack its own `cfn-deploy` names, and that is almost never the env
+                // name. Every declared resource then came back absent, so the rollup
+                // #1300 computes read `present: 0` over a healthy estate. That was
+                // invisible while nothing consumed the rollup; behold#100 paints from
+                // it, so it has to be right.
+                //
+                // The components' own `cfn-deploy` stacks are the authority (the same
+                // ones `observeComponentStacks` reads below), with `config.stacks` as
+                // the declared override for a project whose stacks aren't derivable
+                // from a deploy step. `[undefined]` keeps the old single-read
+                // behaviour for a project with neither.
+                const componentStackNames = new Set();
+                for (const { component } of discovery.components.values()) {
+                    for (const stack of cfnDeployStacks(component.deploy))
+                        componentStackNames.add(stack);
+                }
+                for (const stack of config.stacks ?? [])
+                    componentStackNames.add(stack.name);
+                const readTargets = componentStackNames.size ? [...componentStackNames] : [undefined];
+                const merged = { env: environment, entries: [] };
+                const observations = new Map();
+                for (const plugin of plugins) {
+                    if (!plugin.describeResources)
+                        continue;
+                    const declared = new Set();
+                    const entities = new Map();
+                    for (const [name, entity] of buildResult.entities) {
+                        // Resource declarables only (see lifecycle/observe.ts).
+                        if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
+                            declared.add(name);
+                            entities.set(name, {
+                                entityType: entity.entityType,
+                                props: (entity.props != null ? entity.props : {}),
+                            });
+                        }
+                    }
+                    let observed;
+                    try {
+                        observed = mergeObservations(await Promise.all(readTargets.map(async (stack) => normalizeObservation(await plugin.describeResources({
+                            environment,
+                            buildOutput: "",
+                            entityNames: Array.from(declared),
+                            entities,
+                            ...(stack ? { stack } : {}),
+                        })))));
+                    }
+                    catch (err) {
+                        // A failed read is not an empty environment (#1089): mark every
+                        // declared entity NOT-OBSERVED so the status rows say "unknown"
+                        // rather than "stale" (recorded, and nothing live).
+                        const message = err instanceof Error ? err.message : String(err);
+                        console.error(formatWarning({ message: `${plugin.name}: describeResources failed — ${message} (components in this lexicon report unknown, not stale)` }));
+                        observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {}, sources: {}, notes: [] };
+                    }
+                    // The last lifecycle snapshot is the prior observation drift is
+                    // measured against (#2513) — the same one `lifecycle plan` reads, so
+                    // `drifted` here means what `update` means there. Without it every
+                    // live, declared entity classified `noop` and `drifted` could not be
+                    // reached. Each entity remembers its snapshot's timestamp so the
+                    // status join can ignore a change made before the release.
+                    const baseline = await readStatusBaseline(environment, plugin.name, readTargets);
+                    const cs = buildChangeSet(environment, {
+                        declared,
+                        observedNow: observed.resources,
+                        observedThen: baseline.resources,
+                        unobserved: observed.unobserved,
+                    }, { lexicon: plugin.name });
+                    merged.entries.push(...cs.entries);
+                    for (const entry of cs.entries) {
+                        observations.set(entry.name, {
+                            now: observed.resources[entry.name],
+                            then: baseline.resources?.[entry.name],
+                            thenAt: baseline.timestamps.get(entry.name),
+                        });
+                    }
+                }
+                liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping, { observations });
+                // Multi-stack component projects (each component owns its own stack) are
+                // invisible to the entity-keyed, single-stack `describeResources` above —
+                // observe each component's own cfn-deploy stack directly and overlay it as
+                // the authoritative presence signal (#57).
+                const anyObserver = plugins.some((p) => p.describeStackStatus);
+                if (anyObserver) {
+                    const stackEvidence = await observeComponentStacks(discovery.components, plugins, environment);
+                    liveEvidence = mergeLiveEvidence(liveEvidence, stackEvidence);
+                }
+            }
+            finally {
+                endpointResult.restore();
+            }
+        }
+        // #609: resolve the persisted build manifest behind each recorded digest
+        // (if any) so `build`/`componentBom` are real queries, not always null.
+        const buildsByDigest = new Map();
+        const componentBomByDigest = new Map();
+        const recordedDigests = new Set(ledger.records.map((r) => r.digest));
+        for (const digest of recordedDigests) {
+            const manifest = await findBuildManifestByArtifactDigest(digest);
+            if (!manifest)
+                continue;
+            const bom = componentBomSummary(manifest);
+            if (bom)
+                componentBomByDigest.set(digest, bom);
+            const ledgerEntries = await buildLedgerEntries(manifest);
+            const entry = ledgerEntries.find((e) => e.digest === digest);
+            if (entry)
+                buildsByDigest.set(digest, entry);
+        }
+        const rows = reconcileStatus(environment, ledger.records, {
+            liveEvidence,
+            allComponents,
+            buildsByDigest,
+            componentBomByDigest,
+        });
+        for (const row of rows) {
+            allRows.push({
+                component: row.component,
+                env: row.env,
+                recorded: row.recorded
+                    ? {
+                        digest: row.recorded.digest,
+                        gitSha: row.recorded.gitSha,
+                        runId: row.recorded.runId,
+                        timestamp: row.recorded.timestamp,
+                        actor: row.recorded.actor,
+                        ...(row.recorded.flags ? { flags: row.recorded.flags } : {}),
+                    }
+                    : null,
+                build: row.build
+                    ? {
+                        manifestDigest: row.build.manifestDigest,
+                        referrers: row.build.referrers.map((r) => r.kind),
+                        sbom: row.build.sbom
+                            ? {
+                                mediaType: row.build.sbom.mediaType,
+                                packageCount: row.build.sbom.packageCount,
+                                generator: row.build.sbom.generator,
+                                source: row.build.sbom.source,
+                            }
+                            : null,
+                        reproducibility: row.build.reproducibility
+                            ? { basis: row.build.reproducibility.basis, verifyBy: row.build.reproducibility.verifyBy }
+                            : null,
+                    }
+                    : null,
+                componentBom: row.componentBom
+                    ? {
+                        leaves: row.componentBom.leaves.map((l) => ({
+                            path: l.path,
+                            bomKind: l.bomKind,
+                            subjectDigest: l.subjectDigest,
+                            mediaType: l.mediaType,
+                            packageCount: l.packageCount,
+                            generator: l.generator,
+                        })),
+                        totalPackageCount: row.componentBom.totalPackageCount,
+                        isAssembly: row.componentBom.isAssembly,
+                    }
+                    : null,
+                reconciliation: row.reconciliation,
+                detail: row.detail,
+                ...(row.live !== undefined ? { live: row.live } : {}),
+                ...(row.unobserved ? { unobserved: row.unobserved } : {}),
+                ...(row.stack ? { stack: row.stack } : {}),
+                ...(row.resources ? { resources: row.resources } : {}),
+            });
+        }
+    }
+    // `--compare-to` — single-query cross-env digest comparison, per component.
+    let comparisons;
+    if (args.compareTo && requestedEnv) {
+        const otherLedger = ledgerByEnv.get(args.compareTo) ?? (await readReleaseLedger(args.compareTo));
+        const componentsToCompare = new Set([...allRows.map((r) => r.component)]);
+        comparisons = [...componentsToCompare].sort().map((component) => compareAcrossEnvironments(component, { name: requestedEnv, records: ledgerByEnv.get(requestedEnv)?.records ?? [] }, { name: args.compareTo, records: otherLedger.records }));
+    }
+    if (args.json) {
+        console.log(JSON.stringify(comparisons ? { rows: allRows, comparisons } : allRows, null, 2));
+        return 0;
+    }
+    console.log(formatBold("COMPONENT".padEnd(24)) +
+        formatBold("ENV".padEnd(12)) +
+        formatBold("DIGEST".padEnd(20)) +
+        formatBold("STATUS".padEnd(14)) +
+        formatBold("DETAIL"));
+    console.log("-".repeat(110));
+    for (const row of allRows) {
+        const digestShort = row.recorded ? row.recorded.digest.slice(0, 19) : "-";
+        console.log(row.component.padEnd(24) +
+            row.env.padEnd(12) +
+            digestShort.padEnd(20) +
+            row.reconciliation.padEnd(14) +
+            row.detail +
+            (row.recorded?.flags?.length ? ` [${row.recorded.flags.join(", ")}]` : ""));
+    }
+    if (comparisons) {
+        console.log(`\n${formatBold(`Cross-check: ${requestedEnv} vs ${args.compareTo}`)}`);
+        for (const c of comparisons) {
+            const verdict = c.same
+                ? "same build"
+                : c.mixedDigestForms
+                    ? "different digests, one recorded before real SHA-256 (legacy-digest), so this cannot tell"
+                    : "DIFFERENT builds";
+            console.log(`  ${c.component}: ${c.digestA ?? "(none)"} vs ${c.digestB ?? "(none)"} — ${verdict}`);
+        }
+    }
+    const unrecordedCount = allRows.filter((r) => r.reconciliation === "unrecorded").length;
+    const driftedCount = allRows.filter((r) => r.reconciliation === "drifted").length;
+    if (unrecordedCount === 0 && driftedCount === 0) {
+        console.error(formatSuccess(`No unrecorded deploys or drift across ${allRows.length} row(s)`));
+    }
+    else {
+        console.error(formatWarning({ message: `${unrecordedCount} unrecorded, ${driftedCount} drifted` }));
+    }
+    return 0;
+}
+/** Fallback for `chant components` with no/unknown subcommand. */
+export async function runComponentsUnknown(ctx) {
+    console.error(formatError({
+        message: `Unknown components subcommand: ${ctx.args.path}`,
+        hint: "Available: chant components status [env], chant components release <env>, chant components export <env>",
+    }));
+    return 1;
+}