@intentius/chant 0.18.26 → 0.18.28

package/src/cli/handlers/components.ts

@@ -34,7 +34,7 @@ import {
   listReleaseEnvironments,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
-import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments } from "../../lifecycle/status";
+import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
 import { buildChangeSet } from "../../lifecycle/change-set";
 import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
 import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-store";
@@ -44,7 +44,8 @@ import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import type { ResourceMetadata } from "../../lexicon";
+import type { ResourceMetadata, LexiconPlugin } from "../../lexicon";
+import type { Phase, Component } from "../../components/component";
 
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
@@ -189,6 +190,58 @@ interface StatusJsonRow {
  * 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. */
+function cfnDeployStacks(deploy: Phase[]): string[] {
+  const stacks = new Set<string>();
+  const walkSteps = (steps: Phase["steps"]): void => {
+    for (const step of steps) {
+      // A step may itself be a nested Phase (it carries its own `steps`). Step is
+      // open-typed (capability inputs), so discriminate structurally on `steps`.
+      const nested = (step as { steps?: unknown }).steps;
+      if (Array.isArray(nested)) {
+        walkSteps(nested as Phase["steps"]);
+        continue;
+      }
+      const s = step as { kind?: string; stack?: unknown };
+      if (s.kind === "cfn-deploy" && typeof s.stack === "string") stacks.add(s.stack);
+    }
+  };
+  for (const phase of deploy) walkSteps(phase.steps);
+  return [...stacks];
+}
+
+/**
+ * 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: Map<string, { component: Component }>,
+  observer: LexiconPlugin,
+  environment: string,
+): Promise<Map<string, LiveComponentEvidence>> {
+  const evidence = new Map<string, LiveComponentEvidence>();
+  for (const [name, { component }] of components) {
+    const stacks = cfnDeployStacks(component.deploy);
+    if (stacks.length === 0) continue;
+    const observed = await Promise.all(
+      stacks.map((stack) => observer.describeStackStatus!({ environment, stack }).catch(() => null)),
+    );
+    const determinate = observed.filter((o): o is NonNullable<typeof o> => o !== null);
+    if (determinate.length === 0) continue;
+    const present = determinate.every((o) => o.present);
+    evidence.set(name, { live: present, ownership: present ? "owned" : undefined });
+  }
+  return evidence;
+}
+
 export async function runComponentsStatus(ctx: CommandContext): Promise<number> {
   const { args, plugins, serializers } = ctx;
   const requestedEnv = args.extraPositional;
@@ -261,6 +314,16 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
         merged.entries.push(...cs.entries);
       }
       liveEvidence = liveEvidenceFromChangeSet(merged, liveNameMapping);
+
+      // 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 stackObserver = plugins.find((p) => p.describeStackStatus);
+      if (stackObserver) {
+        const stackEvidence = await observeComponentStacks(discovery.components, stackObserver, environment);
+        liveEvidence = mergeLiveEvidence(liveEvidence, stackEvidence);
+      }
     }
 
     // #609: resolve the persisted build manifest behind each recorded digest

package/src/cli/handlers/graph.test.ts

@@ -18,6 +18,11 @@ vi.mock("../commands/lint", () => ({
   lintCommand: () => lintMock(),
 }));
 
+const componentGraphMock = vi.fn();
+vi.mock("../../components/cli-support", () => ({
+  computeComponentGraph: () => componentGraphMock(),
+}));
+
 // Avoid running a real layout engine in tests; the format dispatch + size/engine
 // plumbing is what matters here (engines have their own unit tests).
 const layoutMock = vi.fn();
@@ -87,6 +92,7 @@ describe("runGraph", () => {
     discoverMock.mockReset();
     lintMock.mockReset();
     layoutMock.mockReset();
+    componentGraphMock.mockReset();
   });
 
   describe("Op graph (default)", () => {
@@ -227,6 +233,79 @@ describe("runGraph", () => {
     });
   });
 
+  describe("component DAG view (--components --format ir|layout)", () => {
+    // shared-foundation (wave 1) <- loom-db (wave 2) <- loom-backend (wave 3).
+    const componentGraphClean = (): void => {
+      componentGraphMock.mockResolvedValue({
+        success: true,
+        order: ["shared-foundation", "loom-db", "loom-backend"],
+        waves: [["shared-foundation"], ["loom-db"], ["loom-backend"]],
+        edges: [
+          { from: "loom-db", to: "shared-foundation" },
+          { from: "loom-backend", to: "loom-db" },
+        ],
+        files: {
+          "shared-foundation": "components/shared-foundation.component.ts",
+          "loom-db": "components/loom-db.component.ts",
+          "loom-backend": "components/loom-backend.component.ts",
+        },
+      });
+    };
+
+    test("--components --format ir emits component nodes, byWave groups, and dependsOn edges", async () => {
+      lintMock.mockResolvedValue({ success: true });
+      componentGraphClean();
+      const exit = await runGraph({ args: makeArgs({ format: "ir", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      // One node per component (not per resource); wave carried on the node.
+      expect(ir.nodes.map((n: { id: string }) => n.id)).toEqual(["shared-foundation", "loom-db", "loom-backend"]);
+      expect(ir.nodes.every((n: { kind: string; lexicon: string }) => n.kind === "Component" && n.lexicon === "chant")).toBe(true);
+      expect(ir.nodes.find((n: { id: string }) => n.id === "loom-backend").attrs.wave).toBe(3);
+      // Each component node deep-links to its source file.
+      expect(ir.nodes.find((n: { id: string }) => n.id === "loom-db").sourceLoc).toEqual({
+        file: "components/loom-db.component.ts",
+      });
+      // dependsOn edges, consumer → producer.
+      expect(ir.edges).toContainEqual({ from: "loom-db", to: "shared-foundation", kind: "ref" });
+      // Waves as groups.
+      expect(ir.groups.byWave).toEqual({
+        "wave-1": ["shared-foundation"],
+        "wave-2": ["loom-db"],
+        "wave-3": ["loom-backend"],
+      });
+      // The entity-graph discovery path is not taken for the component projection.
+      expect(discoverMock).not.toHaveBeenCalled();
+    });
+
+    test("--components --format mermaid lanes the components by wave", async () => {
+      lintMock.mockResolvedValue({ success: true });
+      componentGraphClean();
+      const exit = await runGraph({ args: makeArgs({ format: "mermaid", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const out = stdoutBuf.join("\n");
+      expect(out).toContain("flowchart TD");
+      expect(out).toContain("wave-1");
+    });
+
+    test("--components view is lint-gated like the entity view", async () => {
+      lintMock.mockResolvedValue({ success: false });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stdoutBuf.join("\n")).toBe("");
+      expect(stderrBuf.join("\n")).toMatch(/lint errors/i);
+      expect(componentGraphMock).not.toHaveBeenCalled();
+    });
+
+    test("propagates a component-graph failure (unknown dep / cycle) as a non-zero exit", async () => {
+      lintMock.mockResolvedValue({ success: true });
+      componentGraphMock.mockResolvedValue({ success: false, order: [], waves: [], edges: [], error: "cycle: a ↔ b" });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("cycle: a ↔ b");
+    });
+  });
+
   describe("live graph (--live)", () => {
     // Regression: `graph` is not `requiresPlugins`, so `ctx.plugins` is empty. The
     // live path must load the project's plugins itself — otherwise it wrongly

package/src/cli/handlers/graph.ts

@@ -24,7 +24,9 @@ import { computeComponentGraph } from "../../components/cli-support";
  * cross-lexicon references; `--components` (#560) renders the same
  * order/waves shape for discovered `Component` declarations, from their
  * `dependsOn`; `--format ir|mermaid` emits the lint-gated entity-graph IR (or
- * a Mermaid flowchart of it) for diagrams (#493/#496).
+ * a Mermaid flowchart of it) for diagrams (#493/#496). `--components` with a
+ * `--format` projects the component DAG itself into that format (nodes =
+ * components, wave groups, `dependsOn` edges) — the graph behold renders.
  */
 export async function runGraph(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
@@ -35,6 +37,11 @@ export async function runGraph(ctx: CommandContext): Promise<number> {
     return runGraphLive(ctx, isViewFormat ? (ctx.args.format as (typeof viewFormats)[number]) : "ir");
   }
   if (isViewFormat) {
+    // `--components` projects the component DAG (nodes = components, wave groups,
+    // dependsOn edges) into the same view formats; without it, the entity graph.
+    if (ctx.args.components) {
+      return runComponentGraphView(ctx, ctx.args.format as (typeof viewFormats)[number]);
+    }
     return runGraphView(ctx, ctx.args.format as (typeof viewFormats)[number]);
   }
   if (ctx.args.components) return runComponentGraph(ctx);
@@ -204,6 +211,63 @@ async function runComponentGraph(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+/**
+ * `chant graph --components --format ir|mermaid|dot|layout` — the component DAG
+ * projected into the renderable IR (nodes = components, `groups.byWave` = the
+ * parallel-safe deploy waves, edges = `dependsOn` consumer → producer). This is
+ * the graph behold paints: read one way it is the deploy order, read the other
+ * the CI pipeline. Distinct from `runGraphView`, which emits the AWS *entity*
+ * graph — the component projection has one node per component, not per resource.
+ *
+ * Lint-gated like the entity view: the DAG stands for deployable source, so we
+ * refuse to emit it for source that does not pass lint.
+ */
+async function runComponentGraphView(
+  ctx: CommandContext,
+  format: "ir" | "mermaid" | "dot" | "layout",
+): Promise<number> {
+  const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
+
+  const lint = await lintCommand({ path: ctx.args.path, format: "stylish" });
+  if (!lint.success) {
+    console.error(
+      formatError({
+        message: "Refusing to emit graph: source has lint errors. Run `chant lint` and fix them first.",
+      }),
+    );
+    return 1;
+  }
+
+  const graph = await computeComponentGraph(projectPath);
+  if (!graph.success) {
+    console.error(formatError({ message: graph.error ?? "Failed to compute component graph" }));
+    return 1;
+  }
+
+  // One node per component; wave index carried on the node so a renderer that
+  // ignores groups can still lane by it. `dependsOn` is a plain name edge —
+  // `kind: "ref"` matches the entity graph's edge vocabulary the emitters read.
+  const waveOf = new Map<string, number>();
+  graph.waves.forEach((wave, i) => wave.forEach((name) => waveOf.set(name, i + 1)));
+
+  const ir: GraphIR = {
+    nodes: graph.order.map((name) => ({
+      id: name,
+      kind: "Component",
+      lexicon: "chant",
+      attrs: { wave: waveOf.get(name) ?? null },
+      // Deep-link the node to its `*.component.ts` (behold's inspect panel).
+      ...(graph.files?.[name] ? { sourceLoc: { file: graph.files[name] } } : {}),
+    })),
+    edges: graph.edges.map(({ from, to }) => ({ from, to, kind: "ref" as const })),
+    groups: {
+      byWave: Object.fromEntries(graph.waves.map((wave, i) => [`wave-${i + 1}`, [...wave]])),
+    },
+  };
+
+  return emitIr(ir, ctx, format);
+}
+
 /**
  * `chant graph --format ir|mermaid|dot|layout` — build the graph IR (honouring
  * `--detail`) and emit it as JSON, a Mermaid flowchart, Graphviz DOT, or node

package/src/cli/main.test.ts

@@ -1,5 +1,6 @@
 import { describe, test, expect } from "vitest";
-import { parseArgs } from "./main";
+import { EventEmitter } from "node:events";
+import { parseArgs, waitForStreamDrain } from "./main";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 
 describe("parseArgs", () => {
@@ -416,3 +417,50 @@ describe("parseArgs — run flags", () => {
     expect(result.extraPositional2).toBe("gate-dns");
   });
 });
+
+describe("waitForStreamDrain", () => {
+  // Minimal writable stub — just the surface waitForStreamDrain reads.
+  function fakeStream(len: number): NodeJS.WriteStream & { writableLength: number } {
+    const s = new EventEmitter() as unknown as NodeJS.WriteStream & { writableLength: number };
+    s.writableLength = len;
+    (s as { writableEnded: boolean }).writableEnded = false;
+    (s as { destroyed: boolean }).destroyed = false;
+    return s;
+  }
+
+  test("resolves immediately when nothing is buffered (e.g. a TTY)", async () => {
+    await expect(waitForStreamDrain(fakeStream(0))).resolves.toBeUndefined();
+  });
+
+  test("waits through drains until the buffer is actually empty", async () => {
+    const s = fakeStream(1000);
+    let done = false;
+    const p = waitForStreamDrain(s).then(() => (done = true));
+    await Promise.resolve();
+    expect(done).toBe(false);
+    // A drain while still buffered must NOT resolve (large one-shot write, kernel
+    // took a slice, more remains) — it re-arms.
+    s.emit("drain");
+    await Promise.resolve();
+    expect(done).toBe(false);
+    // Fully flushed now.
+    s.writableLength = 0;
+    s.emit("drain");
+    await p;
+    expect(done).toBe(true);
+  });
+
+  test("resolves on error so a reader that closed early (EPIPE) can't hang exit", async () => {
+    const s = fakeStream(500);
+    const p = waitForStreamDrain(s);
+    s.emit("error", new Error("EPIPE"));
+    await expect(p).resolves.toBeUndefined();
+  });
+
+  test("resolves on close as well", async () => {
+    const s = fakeStream(500);
+    const p = waitForStreamDrain(s);
+    s.emit("close");
+    await expect(p).resolves.toBeUndefined();
+  });
+});

package/src/cli/main.ts

@@ -551,7 +551,48 @@ async function main(): Promise<void> {
   const serializers = plugins.map((p) => p.serializer);
   const ctx = { args, plugins, serializers };
 
-  process.exit(await match.def.handler(ctx));
+  await flushAndExit(await match.def.handler(ctx));
+}
+
+/**
+ * Wait until a writable stream has flushed its buffer. `process.exit()` discards
+ * data still buffered for an async sink (a pipe or file), truncating large output
+ * at the ~64 KB pipe buffer — so `chant graph --format ir` piped into a consumer
+ * loses everything past 64 KB and its JSON won't parse. A TTY writes
+ * synchronously (`writableLength` stays 0), so this is a no-op there. Resolves on
+ * `error`/`close` too, so a reader that closes early (EPIPE) can't hang exit.
+ * Exported for testing.
+ */
+export function waitForStreamDrain(stream: NodeJS.WriteStream): Promise<void> {
+  return new Promise((resolve) => {
+    const tick = (): void => {
+      if (stream.writableLength === 0 || stream.writableEnded || stream.destroyed) {
+        cleanup();
+        resolve();
+        return;
+      }
+      stream.once("drain", tick);
+    };
+    const stop = (): void => {
+      cleanup();
+      resolve();
+    };
+    const cleanup = (): void => {
+      stream.off("drain", tick);
+      stream.off("error", stop);
+      stream.off("close", stop);
+    };
+    stream.once("error", stop);
+    stream.once("close", stop);
+    tick();
+  });
+}
+
+/** Flush stdout+stderr, then exit — so a large piped payload isn't truncated. */
+async function flushAndExit(code: number): Promise<never> {
+  await waitForStreamDrain(process.stdout);
+  await waitForStreamDrain(process.stderr);
+  process.exit(code);
 }
 
 // Only run main when executed directly, not when imported. Robust to symlinked
@@ -559,13 +600,13 @@ async function main(): Promise<void> {
 // whole CLI through the npm .bin shim / a symlinked checkout).
 const isMain = isEntryPoint(process.argv[1], import.meta.url);
 if (isMain) {
-  main().catch((err) => {
+  main().catch(async (err) => {
     const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
     if (verbose && err instanceof Error && err.stack) {
       console.error(err.stack);
     } else {
       console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     }
-    process.exit(1);
+    await flushAndExit(1);
   });
 }

package/src/components/cli-support.ts

@@ -37,6 +37,7 @@ import {
   type DriverRunResult,
 } from "./driver";
 import { isLexiconPlugin, type LexiconPlugin, type ComponentPipelineOptions } from "../lexicon";
+import { relative } from "node:path";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import type { CapabilityRegistry } from "./capability";
 import { applyConfigDefaults } from "./config-defaults";
@@ -129,6 +130,10 @@ export interface ComponentGraphResult {
   order: string[];
   waves: string[][];
   edges: Array<{ from: string; to: string }>;
+  /** Component name → its declaring `*.component.ts` file (relative to `path`),
+   * so a renderer can deep-link a component node to source (`chant graph
+   * --components --format ir` sets `sourceLoc` from this). */
+  files?: Record<string, string>;
   error?: string;
 }
 
@@ -145,13 +150,19 @@ export async function computeComponentGraph(path: string): Promise<ComponentGrap
     deploy: component.deploy,
   }));
 
+  // component name → its declaring file, relative to `path`, for node deep-links.
+  const files: Record<string, string> = {};
+  for (const [name, discovered] of result.components) {
+    files[name] = relative(path, discovered.filePath);
+  }
+
   try {
     const { order, waves } = resolveComponentGraph(driverComponents);
     const edges: Array<{ from: string; to: string }> = [];
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges };
+    return { success: true, order, waves, edges, files };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };

package/src/graph-dot.ts

@@ -12,12 +12,13 @@ import type { GraphIR, IRNode, IREdge } from "./graph-ir";
 export function toDot(ir: GraphIR): string {
   const lines: string[] = ["digraph chant {", "  rankdir=TB;", '  node [shape=box];'];
 
-  const byLexicon = ir.groups.byLexicon;
+  // Cluster by wave (component graph) when present, else by lexicon (entity graph).
+  const clusters = ir.groups.byWave ?? ir.groups.byLexicon;
   const grouped = new Set<string>();
-  if (byLexicon) {
-    for (const [lexicon, members] of Object.entries(byLexicon)) {
-      lines.push(`  subgraph ${q(`cluster_${lexicon}`)} {`);
-      lines.push(`    label=${q(lexicon)};`);
+  if (clusters) {
+    for (const [name, members] of Object.entries(clusters)) {
+      lines.push(`  subgraph ${q(`cluster_${name}`)} {`);
+      lines.push(`    label=${q(name)};`);
       for (const id of members) {
         const node = ir.nodes.find((n) => n.id === id);
         if (!node) continue;

package/src/graph-ir.ts

@@ -94,6 +94,11 @@ export interface IRGroups {
    * so a boundary-box renderer recurses it. Populated by `chant graph --live`
    * from the reference resolver's containment output; absent for source IR. */
   byContainer?: Record<string, string[]>;
+  /** Component-graph deploy wave (`chant graph --components --format ir`):
+   * `wave-N → component node ids` that deploy in parallel in that wave. A
+   * wave-laned renderer reads this the way `byStack` drives boundary boxes.
+   * Present only for the component-DAG projection; absent for entity IR. */
+  byWave?: Record<string, string[]>;
 }
 
 /** A cross-stack export this stack publishes (a `stackOutput`/`output`): its

package/src/graph-mermaid.ts

@@ -20,13 +20,15 @@ export function toMermaid(ir: GraphIR): string {
 
   const lines: string[] = ["flowchart TD"];
 
-  // Cluster by lexicon when grouping is available; nodes outside any group fall
-  // through to the top level. byLexicon is sorted, so output is deterministic.
-  const byLexicon = ir.groups.byLexicon;
+  // Cluster by wave (component graph) when present, else by lexicon (entity
+  // graph); nodes outside any group fall through to the top level. Both are
+  // sorted, so output is deterministic.
+  const clusters = ir.groups.byWave ?? ir.groups.byLexicon;
+  const clusterPrefix = ir.groups.byWave ? "wave" : "lex";
   const grouped = new Set<string>();
-  if (byLexicon) {
-    for (const [lexicon, members] of Object.entries(byLexicon)) {
-      lines.push(`  subgraph ${safeId(`lex_${lexicon}`, ids)}[${quote(lexicon)}]`);
+  if (clusters) {
+    for (const [name, members] of Object.entries(clusters)) {
+      lines.push(`  subgraph ${safeId(`${clusterPrefix}_${name}`, ids)}[${quote(name)}]`);
       for (const id of members) {
         const node = ir.nodes.find((n) => n.id === id);
         if (!node) continue;

package/src/lexicon.ts

@@ -231,6 +231,25 @@ export interface ComponentPipelineResult {
   jobs: ComponentPipelineJob[];
 }
 
+/**
+ * Live status of a single deploy unit (a CloudFormation stack, a K8s release, …)
+ * addressed by its deployed name — the per-component presence signal
+ * `chant components status --live` needs (#57). A component's deploy step carries
+ * the exact unit name it targets (e.g. a `cfn-deploy` step's `stack`), which is
+ * the identity in a multi-stack component project where `describeResources`
+ * (entity-keyed, single-stack-per-env) can't see the component's own stack.
+ */
+export interface StackStatusObservation {
+  /** The deploy-unit name queried (the stack name). */
+  stack: string;
+  /** False when the unit does not exist yet — the pre-first-apply state. */
+  present: boolean;
+  /** Provider-native status string, e.g. CloudFormation "CREATE_COMPLETE". */
+  status?: string;
+  /** True when `status` is a terminal *success* state (deployed and healthy). */
+  healthy?: boolean;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -388,6 +407,22 @@ export interface LexiconPlugin {
     owned?: boolean;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Report the live status of one deploy unit by its deployed name. Opt-in.
+   *
+   * Complements {@link describeResources}: that observes a stack's *entities*
+   * keyed by chant entity name (and assumes one stack per environment), which
+   * can't see a multi-stack component project where each component owns its own
+   * stack. `chant components status --live` resolves a component's deploy-step
+   * target (e.g. a `cfn-deploy` step's `stack`) and calls this to learn whether
+   * that unit is present and healthy — a component-level presence signal.
+   *
+   * Returns `null` when the lexicon cannot determine status (e.g. the provider
+   * CLI failed for a reason other than "does not exist"); a genuinely absent
+   * unit returns `{ present: false }`.
+   */
+  describeStackStatus?(options: { environment: string; stack: string }): Promise<StackStatusObservation | null>;
+
   /**
    * Reference catalog for live edge reconstruction (#778). Declares how this
    * lexicon's observed resources reference each other — an identity map (which

package/src/lifecycle/status.test.ts

@@ -4,6 +4,7 @@ import {
   liveEvidenceFromChangeSet,
   resolveLiveNames,
   compareAcrossEnvironments,
+  mergeLiveEvidence,
   type LiveComponentEvidence,
   type LiveNameMapping,
 } from "./status";
@@ -327,4 +328,35 @@ describe("status", () => {
       expect(result.same).toBe(false);
     });
   });
+
+  describe("mergeLiveEvidence (#57 — per-component stack presence overlay)", () => {
+    test("stack presence overrides change-set 'not live' but keeps its drift action", () => {
+      const base = new Map<string, LiveComponentEvidence>([
+        ["shared-foundation", { live: false }], // entity-keyed observe saw nothing
+        ["loom-backend", { live: true, action: "update", ownership: "owned" }],
+      ]);
+      const supplement = new Map<string, LiveComponentEvidence>([
+        ["shared-foundation", { live: true, ownership: "owned" }], // its stack IS present
+        ["loom-backend", { live: true, ownership: "owned" }],
+      ]);
+      const merged = mergeLiveEvidence(base, supplement);
+      expect(merged.get("shared-foundation")).toEqual({ live: true, ownership: "owned", action: undefined });
+      // loom-backend: presence confirmed, change-set drift action preserved.
+      expect(merged.get("loom-backend")).toEqual({ live: true, ownership: "owned", action: "update" });
+    });
+
+    test("a component only in the supplement is added; base-only entries pass through", () => {
+      const base = new Map<string, LiveComponentEvidence>([["only-base", { live: true, ownership: "foreign" }]]);
+      const supplement = new Map<string, LiveComponentEvidence>([["only-sup", { live: false }]]);
+      const merged = mergeLiveEvidence(base, supplement);
+      expect(merged.get("only-base")).toEqual({ live: true, ownership: "foreign" });
+      expect(merged.get("only-sup")).toEqual({ live: false, ownership: undefined, action: undefined });
+    });
+
+    test("undefined base (no --live change-set) still yields the supplement", () => {
+      const supplement = new Map<string, LiveComponentEvidence>([["c", { live: true, ownership: "owned" }]]);
+      const merged = mergeLiveEvidence(undefined, supplement);
+      expect(merged.get("c")).toEqual({ live: true, ownership: "owned", action: undefined });
+    });
+  });
 });

package/src/lifecycle/status.ts

@@ -86,6 +86,33 @@ export interface LiveComponentEvidence {
   ownership?: "owned" | "foreign" | "unknown";
 }
 
+/**
+ * Overlay per-component stack-presence evidence onto change-set evidence.
+ *
+ * The change-set axis (`liveEvidenceFromChangeSet`) is entity-keyed and, for
+ * AWS, single-stack-per-env — it can't see a multi-stack component project where
+ * each component owns its own stack (#57). `supplement` carries the direct
+ * per-component stack observation (from a lexicon's `describeStackStatus`), which
+ * is authoritative for **presence** (`live`) and **ownership**; the change-set's
+ * `action` is kept, since drift is still assessed from the diff. A component in
+ * only one map passes through unchanged.
+ */
+export function mergeLiveEvidence(
+  base: Map<string, LiveComponentEvidence> | undefined,
+  supplement: Map<string, LiveComponentEvidence>,
+): Map<string, LiveComponentEvidence> {
+  const merged = new Map(base ?? []);
+  for (const [component, sup] of supplement) {
+    const b = merged.get(component);
+    merged.set(component, {
+      live: sup.live,
+      ownership: sup.ownership ?? b?.ownership,
+      action: b?.action,
+    });
+  }
+  return merged;
+}
+
 /**
  * Component -> live entity/resource name(s) it owns (#598). Mirrors
  * `Component.liveNames` (../components/component.ts) without importing it —