@intentius/chant 0.46.0 → 0.50.0

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

@@ -1,7 +1,11 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
 import { createMockPlugin, staticDescribeResources } from "@intentius/chant-test-utils";
 import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
+import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import type { ParsedArgs } from "../registry";
 
 /**
@@ -28,6 +32,7 @@ const loadChantConfigMock = vi.fn();
 const buildMock = vi.fn();
 const discoverComponentsMock = vi.fn();
 const findBuildManifestByArtifactDigestMock = vi.fn();
+const readBuildManifestMock = vi.fn();
 
 vi.mock("../../lifecycle/git", () => ({
   getHeadCommit: (...args: unknown[]) => getHeadCommitMock(...args),
@@ -38,6 +43,7 @@ vi.mock("../../lifecycle/git", () => ({
 
 vi.mock("../../lifecycle/build-ledger-store", () => ({
   findBuildManifestByArtifactDigest: (...args: unknown[]) => findBuildManifestByArtifactDigestMock(...args),
+  readBuildManifest: (...args: unknown[]) => readBuildManifestMock(...args),
 }));
 
 vi.mock("../../lifecycle/release-ledger", async () => {
@@ -66,7 +72,7 @@ vi.mock("../../components/discover", () => ({
   discoverComponents: (...args: unknown[]) => discoverComponentsMock(...args),
 }));
 
-const { runComponentsReleaseRecord, runComponentsStatus, runComponentsUnknown } = await import("./components");
+const { runComponentsReleaseRecord, runComponentsStatus, runComponentsExport, runComponentsUnknown } = await import("./components");
 
 function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
   return {
@@ -126,6 +132,7 @@ describe("components handlers", () => {
     buildMock.mockReset().mockResolvedValue(makeBuildResult({}));
     discoverComponentsMock.mockReset().mockResolvedValue({ components: new Map(), sourceFiles: [], errors: [] });
     findBuildManifestByArtifactDigestMock.mockReset().mockResolvedValue(undefined);
+    readBuildManifestMock.mockReset().mockResolvedValue(null);
 
     delete process.env.GITHUB_RUN_ID;
     delete process.env.CI_PIPELINE_ID;
@@ -569,6 +576,197 @@ describe("components handlers", () => {
     });
   });
 
+  describe("runComponentsExport", () => {
+    const originalCwd = process.cwd();
+    let srcDir: string;
+    let outDir: string;
+
+    function makeManifest(overrides: Partial<BuildArchiveManifest> = {}): BuildArchiveManifest {
+      return {
+        version: 1,
+        component: "search-service",
+        createdAt: "2026-01-01T00:00:00.000Z",
+        manifestDigest: "sha256:manifest1",
+        contents: [
+          { kind: "template", path: "search.template.json", digest: "sha256:tmpl1", mediaType: "application/json" },
+          { kind: "asset", path: "dist/search.zip", digest: "sha256:asset1", mediaType: "application/octet-stream" },
+        ],
+        ...overrides,
+      };
+    }
+
+    beforeEach(async () => {
+      srcDir = await mkdtemp(join(tmpdir(), "chant-export-src-"));
+      outDir = await mkdtemp(join(tmpdir(), "chant-export-out-"));
+      process.chdir(srcDir);
+    });
+
+    afterEach(async () => {
+      process.chdir(originalCwd);
+      await rm(srcDir, { recursive: true, force: true });
+      await rm(outDir, { recursive: true, force: true });
+    });
+
+    test("-o/--output is required", async () => {
+      const ctx = { args: makeArgs({ path: "export", digest: "sha256:manifest1" }), plugins: [], serializers: [] };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("-o/--output <dir> is required");
+    });
+
+    test("without --digest, requires environment and --component", async () => {
+      const ctx = { args: makeArgs({ path: "export", output: outDir }), plugins: [], serializers: [] };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("Environment and --component are required");
+    });
+
+    test("--digest resolves the manifest directly and materializes every entry plus manifest.json", async () => {
+      await writeFile(join(srcDir, "search.template.json"), '{"Resources":{}}');
+      await mkdir(join(srcDir, "dist"), { recursive: true });
+      await writeFile(join(srcDir, "dist", "search.zip"), "zip-bytes");
+
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+
+      const ctx = {
+        args: makeArgs({ path: "export", component: "search-service", digest: "sha256:manifest1", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+
+      expect(exit).toBe(0);
+      expect(readBuildManifestMock).toHaveBeenCalledWith("sha256:manifest1");
+      expect(await readFile(join(outDir, "search.template.json"), "utf-8")).toBe('{"Resources":{}}');
+      expect(await readFile(join(outDir, "dist", "search.zip"), "utf-8")).toBe("zip-bytes");
+      const manifestOut = JSON.parse(await readFile(join(outDir, "manifest.json"), "utf-8"));
+      expect(manifestOut.manifestDigest).toBe("sha256:manifest1");
+      expect(manifestOut.contents).toHaveLength(2);
+    });
+
+    test("resolves via the release ledger's latest record when --digest is omitted (manifestDigest present)", async () => {
+      readReleaseLedgerMock.mockResolvedValue({
+        records: [
+          {
+            version: 1, component: "search-service", env: "prod", digest: "sha256:artifact1",
+            gitSha: "abc", runId: "1", timestamp: "2026-01-01T00:00:00.000Z", actor: "alice",
+            manifestDigest: "sha256:manifest1",
+          },
+        ],
+        malformed: 0,
+      });
+      readBuildManifestMock.mockResolvedValue(makeManifest({ contents: [] }));
+
+      const ctx = {
+        args: makeArgs({ path: "export", extraPositional: "prod", component: "search-service", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+
+      expect(exit).toBe(0);
+      expect(readBuildManifestMock).toHaveBeenCalledWith("sha256:manifest1");
+      expect(findBuildManifestByArtifactDigestMock).not.toHaveBeenCalled();
+    });
+
+    test("falls back to findBuildManifestByArtifactDigest when the release record carries no manifestDigest", async () => {
+      readReleaseLedgerMock.mockResolvedValue({
+        records: [
+          {
+            version: 1, component: "search-service", env: "prod", digest: "sha256:artifact1",
+            gitSha: "abc", runId: "1", timestamp: "2026-01-01T00:00:00.000Z", actor: "alice",
+          },
+        ],
+        malformed: 0,
+      });
+      findBuildManifestByArtifactDigestMock.mockResolvedValue(makeManifest({ contents: [] }));
+
+      const ctx = {
+        args: makeArgs({ path: "export", extraPositional: "prod", component: "search-service", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+
+      expect(exit).toBe(0);
+      expect(findBuildManifestByArtifactDigestMock).toHaveBeenCalledWith("sha256:artifact1");
+    });
+
+    test("no release record for the component/env -> error", async () => {
+      readReleaseLedgerMock.mockResolvedValue({ records: [], malformed: 0 });
+      const ctx = {
+        args: makeArgs({ path: "export", extraPositional: "prod", component: "search-service", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("No release record for component");
+    });
+
+    test("--digest with no persisted manifest -> error", async () => {
+      readBuildManifestMock.mockResolvedValue(null);
+      const ctx = {
+        args: makeArgs({ path: "export", digest: "sha256:missing", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("No persisted build manifest found");
+    });
+
+    test("a source file missing on disk is reported per entry and fails the command", async () => {
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+      // Neither entry's source file exists in srcDir.
+      const ctx = {
+        args: makeArgs({ path: "export", digest: "sha256:manifest1", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(1);
+      expect(stderrBuf.join("\n")).toContain("not found on disk");
+    });
+
+    test("--json emits a structured per-entry summary", async () => {
+      await writeFile(join(srcDir, "search.template.json"), "{}");
+      await mkdir(join(srcDir, "dist"), { recursive: true });
+      await writeFile(join(srcDir, "dist", "search.zip"), "zip-bytes");
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+
+      const ctx = {
+        args: makeArgs({ path: "export", digest: "sha256:manifest1", output: outDir, json: true }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(0);
+
+      const parsed = JSON.parse(stdoutBuf.join(""));
+      expect(parsed.component).toBe("search-service");
+      expect(parsed.manifestDigest).toBe("sha256:manifest1");
+      expect(parsed.entries).toHaveLength(2);
+      expect(parsed.entries.every((e: { status: string }) => e.status === "materialized")).toBe(true);
+    });
+
+    test("a --component that mismatches the resolved --digest manifest warns but still exports", async () => {
+      await writeFile(join(srcDir, "search.template.json"), "{}");
+      await mkdir(join(srcDir, "dist"), { recursive: true });
+      await writeFile(join(srcDir, "dist", "search.zip"), "zip-bytes");
+      readBuildManifestMock.mockResolvedValue(makeManifest());
+
+      const ctx = {
+        args: makeArgs({ path: "export", component: "other-service", digest: "sha256:manifest1", output: outDir }),
+        plugins: [],
+        serializers: [],
+      };
+      const exit = await runComponentsExport(ctx);
+      expect(exit).toBe(0);
+      expect(stderrBuf.join("\n")).toContain("does not match the resolved manifest's component");
+    });
+  });
+
   describe("runComponentsUnknown", () => {
     test("reports the unknown subcommand", async () => {
       const ctx = { args: makeArgs({ path: "bogus" }), plugins: [], serializers: [] };

package/src/cli/handlers/components.ts

@@ -26,20 +26,23 @@
  * `componentBom` fall back to `null` exactly as before — no regression for
  * ledgers with no persisted manifests at all.
  */
-import { resolve } from "node:path";
+import { resolve, join, dirname } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { getHeadCommit, fetchLifecycle, pushLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
 import {
   appendReleaseRecord,
   readReleaseLedger,
   listReleaseEnvironments,
+  latestPerComponent,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
 import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
 import { commandBuildParams } from "../build-params-cli";
 import { buildChangeSet } from "../../lifecycle/change-set";
 import { buildLedgerEntries, componentBomSummary, type BuildLedgerEntry } from "../../lifecycle/build-ledger";
-import { findBuildManifestByArtifactDigest } from "../../lifecycle/build-ledger-store";
+import { findBuildManifestByArtifactDigest, readBuildManifest } from "../../lifecycle/build-ledger-store";
 import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
+import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
 import { isResourceDeclarable } from "../../declarable";
@@ -51,6 +54,7 @@ import type { LexiconPlugin } from "../../lexicon";
 import { normalizeObservation, mergeObservations, unobservedAll, type NormalizedObservation } from "../../observation";
 import type { Phase, Component } from "../../components/component";
 import { deployUnits } from "../../components/deploy-units";
+import { sortedJsonReplacer } from "../../utils";
 
 /**
  * chant components release <env> --component <name> --digest <sha256:...>
@@ -147,6 +151,159 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   }
 }
 
+/** One entry of `chant components export`'s per-entry result (text and `--json` output). */
+interface ExportEntryResult {
+  kind: string;
+  path: string;
+  digest: string;
+  status: "materialized" | "missing";
+  /** Set only when `status` is "missing" — why the source file couldn't be read. */
+  reason?: string;
+}
+
+/**
+ * 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: CommandContext): Promise<number> {
+  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: BuildArchiveManifest;
+
+  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: ExportEntryResult[] = [];
+  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),
+      });
+    }
+  }
+
+  await writeFile(join(targetDir, "manifest.json"), JSON.stringify(manifest, sortedJsonReplacer, 2));
+
+  const missing = results.filter((r) => r.status === "missing");
+
+  if (args.json) {
+    console.log(JSON.stringify({
+      component: manifest.component,
+      manifestDigest: manifest.manifestDigest,
+      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;
+}
+
 /** One row of `chant components status` JSON output. */
 interface StatusJsonRow {
   component: string;
@@ -595,7 +752,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
 export async function runComponentsUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown components subcommand: ${ctx.args.path}`,
-    hint: "Available: chant components status [env], chant components release <env>",
+    hint: "Available: chant components status [env], chant components release <env>, chant components export <env>",
   }));
   return 1;
 }

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

@@ -1,5 +1,5 @@
 import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
@@ -90,4 +90,73 @@ describe("runExplain", () => {
     const code = await runExplain(ctx({ format: "okf" }));
     expect(code).toBe(1);
   });
+
+  describe("knowledge sections (#1867)", () => {
+    let projectDir: string;
+
+    beforeEach(async () => {
+      projectDir = await mkdtemp(join(tmpdir(), "chant-explain-knowledge-"));
+    });
+
+    afterEach(async () => {
+      await rm(projectDir, { recursive: true, force: true });
+    });
+
+    test("omits the Knowledge section cleanly when no bundle exists", async () => {
+      const code = await runExplain(ctx({ path: projectDir }));
+      expect(code).toBe(0);
+      expect(logSpy.mock.calls[0][0]).not.toContain("## Knowledge");
+    });
+
+    test("json omits the knowledge field cleanly when no bundle exists", async () => {
+      const code = await runExplain(ctx({ path: projectDir, format: "json" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(parsed.knowledge).toBeUndefined();
+    });
+
+    test("markdown includes a per-entity Knowledge section for bound concepts", async () => {
+      await mkdir(join(projectDir, "knowledge", "decisions"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "decisions", "public-vpc.md"),
+        "---\ntype: decision\ntitle: Public VPC\nbinds: vpc\n---\nWhy the VPC is public.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir }));
+      expect(code).toBe(0);
+      const out = logSpy.mock.calls[0][0] as string;
+      expect(out).toContain("## Knowledge");
+      expect(out).toContain("### `vpc`");
+      expect(out).toContain("decision: Public VPC (`decisions/public-vpc.md`)");
+      expect(out).not.toContain("### `subnet`");
+    });
+
+    test("json carries type/title/path per bound entity", async () => {
+      await mkdir(join(projectDir, "knowledge", "decisions"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "decisions", "public-vpc.md"),
+        "---\ntype: decision\ntitle: Public VPC\nbinds: vpc\n---\nWhy the VPC is public.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir, format: "json" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(parsed.knowledge).toEqual({
+        vpc: [{ type: "decision", title: "Public VPC", path: "decisions/public-vpc.md" }],
+      });
+    });
+
+    test("--format okf output is untouched by a present bundle", async () => {
+      await mkdir(join(projectDir, "knowledge"), { recursive: true });
+      await writeFile(
+        join(projectDir, "knowledge", "note.md"),
+        "---\ntype: decision\ntitle: Note\nbinds: vpc\n---\nBody.\n",
+      );
+
+      const code = await runExplain(ctx({ path: projectDir, format: "okf" }));
+      expect(code).toBe(0);
+      const parsed = JSON.parse(logSpy.mock.calls[0][0] as string);
+      expect(Object.keys(parsed.files).sort()).toEqual(["gcp/subnet.md", "gcp/vpc.md", "index.md"]);
+    });
+  });
 });

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

@@ -431,6 +431,26 @@ describe("runGraph", () => {
       expect(discoverMock).not.toHaveBeenCalled();
     });
 
+    test("--components --format ir carries declared composites (#1492); undeclared components have no composites attr", async () => {
+      lintMock.mockResolvedValue({ success: true });
+      componentGraphMock.mockResolvedValue({
+        success: true,
+        order: ["shared-foundation", "loom-backend"],
+        waves: [["shared-foundation"], ["loom-backend"]],
+        edges: [{ from: "loom-backend", to: "shared-foundation" }],
+        files: {},
+        composites: { "shared-foundation": ["ArtifactBucket", "OperatorRole"] },
+      });
+      const exit = await runGraph({ args: makeArgs({ format: "ir", components: true }), plugins: [], serializers: [] });
+      expect(exit).toBe(0);
+      const ir = JSON.parse(stdoutBuf.join("\n"));
+      expect(ir.nodes.find((n: { id: string }) => n.id === "shared-foundation").attrs.composites).toEqual([
+        "ArtifactBucket",
+        "OperatorRole",
+      ]);
+      expect("composites" in ir.nodes.find((n: { id: string }) => n.id === "loom-backend").attrs).toBe(false);
+    });
+
     test("--components --format mermaid lanes the components by wave", async () => {
       lintMock.mockResolvedValue({ success: true });
       componentGraphClean();

package/src/cli/handlers/graph.ts

@@ -77,7 +77,7 @@ async function graphBuildParams(
 async function graphBuildRootContributors(
   ctx: CommandContext,
   projectPath: string,
-): Promise<Array<() => Promise<import("../../lexicon").BuildRootContribution>>> {
+): Promise<Array<import("../../lexicon").BuildRootContributor>> {
   const { config, configPath } = await loadChantConfigUpward(projectPath).catch(
     () => ({ config: {} as ChantConfig, configPath: undefined }),
   );
@@ -109,7 +109,7 @@ async function graphBuildRootContributors(
  */
 async function mergeGraphBuildRoots(
   entities: Map<string, import("../../declarable").Declarable>,
-  contributors: Array<() => Promise<import("../../lexicon").BuildRootContribution>>,
+  contributors: Array<import("../../lexicon").BuildRootContributor>,
 ): Promise<boolean> {
   if (contributors.length === 0) return true;
   const merged = await mergeBuildRootEntities(entities, contributors);
@@ -580,7 +580,16 @@ async function runComponentGraphView(
       // `liveNames` (#1491): the resources this component owns — declared, or
       // the contract's `[name]` identity fallback — so a consumer can join
       // the component DAG to the resource graph instead of guessing at kinds.
-      attrs: { wave: waveOf.get(name) ?? null, liveNames: graph.liveNames?.[name] ?? [name] },
+      // `composites` (#1492): the composite kind(s) this component's
+      // resources come from, when the component declared them explicitly —
+      // omitted from attrs (not defaulted) when it didn't, so a consumer
+      // knows to fall back to its own naming-convention guess rather than
+      // reading "no composites" from an empty array.
+      attrs: {
+        wave: waveOf.get(name) ?? null,
+        liveNames: graph.liveNames?.[name] ?? [name],
+        ...(graph.composites?.[name] ? { composites: graph.composites[name] } : {}),
+      },
       // Deep-link the node to its `*.component.ts` (behold's inspect panel).
       ...(graph.files?.[name] ? { sourceLoc: { file: graph.files[name] } } : {}),
     })),