@intentius/chant 0.46.0 → 0.50.0

package/src/cli/registry.ts

@@ -194,9 +194,9 @@ export interface ParsedArgs {
   check?: boolean;
   /** `chant dev surface-diff --update-snapshot --bump` — bump the lexicon's package.json version by the drift severity so the accepted surface is publishable (#616). */
   bump?: boolean;
-  /** `chant components release record --component <name>` (#568) — component name for the release record being appended. */
+  /** `chant components release record --component <name>` (#568) — component name for the release record being appended. Also `chant components export <env> --component <name>` (#929) — which component's most recent recorded build to export. */
   component?: string;
-  /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. */
+  /** `chant components release record --digest <sha256:...>` (#568) — artifact digest to record, joining this release to the build archive/ledger. Also `chant components export --digest <manifestDigest>` (#929) — a build archive manifest digest to export directly, bypassing env/component resolution. */
   digest?: string;
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */
   gitSha?: string;
@@ -218,6 +218,10 @@ export interface ParsedArgs {
   fold?: boolean;
   /** `chant build --sandbox` (#1045 Phase 2) — opt-in: run-fallback source files (or every file, without `--fold`) execute together, isolated, in one sandboxed child process instead of in-process. Also settable project-wide via `chant.config.ts`'s `build.sandbox: true`; the flag always wins when set. Default (flag omitted): in-process execution, unchanged. */
   sandbox?: boolean;
+  /** `chant build --fold --fold-rank` (#1083) — after a `--fold` build, print blockers ranked by dominator retained-count over the forward import-failure graph, plus the separate reverse-taint bucket (chant #1044). Bare boolean form; see {@link foldRankCollapsedFile} for the file-writing form. No-op without `--fold`. */
+  foldRank?: boolean;
+  /** `chant build --fold --fold-rank <path>` (#1083) — same ranking as {@link foldRank}, ALSO exported in Brendan Gregg collapsed stack format (weighted by retained count) to `<path>`, so it renders in any flame/icicle viewer. Mutually exclusive with the bare-boolean form at the parse level (same context-sensitive lookahead as `--report`), but the text report still prints either way. */
+  foldRankCollapsedFile?: string;
   /** `chant build --param name=value` (#1064) — repeatable. Bound to `params.<name>` (`@intentius/chant/params`) for source to reference, after validation against `chant.config.ts`'s declared `buildParams`. Highest precedence over `--params-file`/a declared `env` mapping/the declared `default`. */
   param?: string[];
   /** `chant build --params-file <path>` (#1064) — a JSON file of `{ "name": value }` build-time parameter values. Second precedence, after `--param`. */
@@ -228,6 +232,14 @@ export interface ParsedArgs {
    * forgejo today) — the same generator `chant build --components --generate
    * <lexicon>` uses, reused rather than re-derived. */
   projection?: string;
+  /** `chant operator --interval <duration>` (#1485) — poll interval between rounds, e.g. "30s", "5m". Default: 60s. */
+  interval?: string;
+  /** `chant operator --lease-ttl <duration>` (#1485) — how long an acquired lease is valid before it's reclaimable by another operator. Default: 5m. */
+  leaseTtl?: string;
+  /** `chant operator --once` (#1485) — run a single round and exit, instead of looping until Ctrl-C. Also the offline test/cron-invoker story. */
+  once?: boolean;
+  /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text context recorded on the gate-resolution fact (e.g. a PR URL). */
+  note?: string;
 }
 
 /**

package/src/cli/reporters/stylish.test.ts

@@ -1,6 +1,17 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { formatStylish, formatSummary, formatJson, formatSarif } from "./stylish";
 import type { LintDiagnostic, LintRule } from "../../lint/rule";
+import type { OkfBundle, OkfConcept } from "../../okf-read";
+
+function concept(overrides: Partial<OkfConcept> & { path: string }): OkfConcept {
+  return {
+    type: "decision",
+    binds: [],
+    frontmatter: {},
+    body: "",
+    ...overrides,
+  };
+}
 
 describe("formatStylish", () => {
   const originalNoColor = process.env.NO_COLOR;
@@ -123,6 +134,149 @@ describe("formatStylish", () => {
   });
 });
 
+describe("formatStylish suppressed section (#1866, design #1059)", () => {
+  beforeEach(() => {
+    process.env.NO_COLOR = "1";
+  });
+  afterEach(() => {
+    delete process.env.NO_COLOR;
+  });
+
+  const suppressedDiag: LintDiagnostic & { reason?: string } = {
+    file: "src/storage.ts",
+    line: 12,
+    column: 1,
+    ruleId: "AWS021",
+    severity: "warning",
+    message: "Bucket ACL is public-read",
+  };
+
+  test("no section when there are no suppressed diagnostics", () => {
+    const result = formatStylish([], []);
+    expect(result).not.toContain("Suppressed");
+  });
+
+  test("renders a Suppressed section when suppressed diagnostics exist", () => {
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "backwards compat" }]);
+
+    expect(result).toContain("Suppressed");
+    expect(result).toContain("src/storage.ts");
+    expect(result).toContain("AWS021");
+    expect(result).toContain("backwards compat");
+  });
+
+  test("renders the section even when there are no active diagnostics", () => {
+    const result = formatStylish([], [suppressedDiag]);
+    expect(result).toContain("Suppressed");
+    // No active errors/warnings were counted from a suppressed diagnostic
+    expect(result).toContain("No problems found");
+  });
+
+  test("an okf: citation resolves to the concept's title and bundle-relative path", () => {
+    const bundle: OkfBundle = {
+      concepts: [
+        concept({
+          path: "decisions/public-assets.md",
+          title: "Public asset bucket stays world-readable",
+        }),
+      ],
+    };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("Public asset bucket stays world-readable");
+    expect(result).toContain("decisions/public-assets.md");
+    expect(result).not.toContain("okf:/decisions/public-assets.md");
+  });
+
+  test("also resolves a citation without a leading slash", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:decisions/public-assets.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("Public assets");
+  });
+
+  test("an unresolvable citation prints the raw reason with a warning", () => {
+    const bundle: OkfBundle = { concepts: [] };
+
+    const result = formatStylish(
+      [],
+      [{ ...suppressedDiag, reason: "okf:/decisions/does-not-exist.md" }],
+      bundle,
+    );
+
+    expect(result).toContain("okf:/decisions/does-not-exist.md");
+    expect(result).toContain("unresolved okf citation");
+  });
+
+  test("an okf: citation with no bundle loaded prints the raw reason with a warning", () => {
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }]);
+
+    expect(result).toContain("okf:/decisions/public-assets.md");
+    expect(result).toContain("unresolved okf citation");
+  });
+
+  test("a plain (non-okf) reason renders as-is, unaffected by a loaded bundle", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    };
+
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "grandfathered, see #412" }], bundle);
+
+    expect(result).toContain("grandfathered, see #412");
+    expect(result).not.toContain("Public assets");
+  });
+
+  test("a suppressed diagnostic with no reason still renders", () => {
+    const result = formatStylish([], [suppressedDiag]);
+    expect(result).toContain("AWS021");
+    expect(result).toContain("suppressed");
+  });
+
+  test("active diagnostics and the suppressed section coexist", () => {
+    const active: LintDiagnostic = {
+      file: "src/other.ts",
+      line: 1,
+      column: 1,
+      ruleId: "COR001",
+      severity: "error",
+      message: "Active problem",
+    };
+
+    const result = formatStylish([active], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }], {
+      concepts: [concept({ path: "decisions/public-assets.md", title: "Public assets" })],
+    });
+
+    expect(result).toContain("src/other.ts");
+    expect(result).toContain("Active problem");
+    expect(result).toContain("1 error");
+    expect(result).toContain("Suppressed");
+    expect(result).toContain("Public assets");
+  });
+
+  test("a title-less resolved concept falls back to its path as the label", () => {
+    const bundle: OkfBundle = {
+      concepts: [concept({ path: "decisions/public-assets.md" })],
+    };
+
+    const result = formatStylish([], [{ ...suppressedDiag, reason: "okf:/decisions/public-assets.md" }], bundle);
+
+    expect(result).toContain("decisions/public-assets.md");
+    expect(result).not.toContain("unresolved");
+  });
+});
+
 describe("formatSummary", () => {
   beforeEach(() => {
     process.env.NO_COLOR = "1";

package/src/cli/reporters/stylish.ts

@@ -1,4 +1,5 @@
 import type { LintDiagnostic, LintRule, Severity } from "../../lint/rule";
+import type { OkfBundle } from "../../okf-read";
 import { pathToFileURL } from "node:url";
 
 /**
@@ -33,64 +34,184 @@ function color(text: string, colorCode: string): string {
 /**
  * Format diagnostics in stylish format (similar to ESLint)
  * Groups by file, shows severity, message, and rule ID
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param suppressed - Suppressed diagnostics with optional reason (optional). When
+ *   present and non-empty, a "Suppressed" section is appended (#1866, design #1059)
+ *   below the active diagnostics, mirroring SARIF's `suppressed` param on
+ *   {@link formatSarif} rather than changing what "diagnostics" means here.
+ * @param bundle - The project's loaded OKF knowledge bundle (`../../okf-read`'s
+ *   `loadOkfBundle`), used to resolve `okf:` citations in suppression reasons.
+ *   Omitted (or a bundle with no matching concept) falls back to printing the
+ *   raw reason with a warning — this never affects suppression itself, only
+ *   how a cited reason renders.
  */
-export function formatStylish(diagnostics: LintDiagnostic[]): string {
-  if (diagnostics.length === 0) {
+export function formatStylish(
+  diagnostics: LintDiagnostic[],
+  suppressed?: Array<LintDiagnostic & { reason?: string }>,
+  bundle?: OkfBundle,
+): string {
+  const hasSuppressed = suppressed !== undefined && suppressed.length > 0;
+
+  if (diagnostics.length === 0 && !hasSuppressed) {
     return formatSummary(0, 0);
   }
 
-  // Group by file
-  const byFile = new Map<string, LintDiagnostic[]>();
-  for (const diag of diagnostics) {
+  const lines: string[] = [];
+  let errorCount = 0;
+  let warningCount = 0;
+
+  if (diagnostics.length > 0) {
+    // Group by file
+    const byFile = new Map<string, LintDiagnostic[]>();
+    for (const diag of diagnostics) {
+      const existing = byFile.get(diag.file) ?? [];
+      existing.push(diag);
+      byFile.set(diag.file, existing);
+    }
+
+    for (const [file, fileDiags] of byFile) {
+      // File header with underline
+      lines.push("");
+      lines.push(color(file, colors.underline));
+
+      // Sort by line, then column
+      fileDiags.sort((a, b) => {
+        if (a.line !== b.line) return a.line - b.line;
+        return a.column - b.column;
+      });
+
+      for (const diag of fileDiags) {
+        // Count errors and warnings
+        if (diag.severity === "error") {
+          errorCount++;
+        } else if (diag.severity === "warning") {
+          warningCount++;
+        }
+
+        // Format: "  line:col  severity  message  ruleId"
+        const location = color(
+          `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`,
+          colors.gray
+        );
+
+        const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
+        const severity = color(diag.severity.padEnd(7), severityColor);
+
+        const ruleId = color(diag.ruleId, colors.gray);
+
+        lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+      }
+    }
+  }
+
+  if (hasSuppressed) {
+    lines.push(...formatSuppressedSection(suppressed!, bundle));
+  }
+
+  // Summary line
+  lines.push("");
+  const summary = formatSummary(errorCount, warningCount);
+  lines.push(summary);
+
+  return lines.join("\n");
+}
+
+/**
+ * A suppression reason's `okf:` citation, resolved against a loaded bundle.
+ */
+interface ResolvedCitation {
+  /** What to print beside the rule id: the concept title when resolved, the raw reason otherwise. */
+  label: string;
+  /** The concept's bundle-relative path, printed on the line below — only set when resolved. */
+  path?: string;
+  /** True when the reason carried an `okf:` token that named no concept in `bundle`. */
+  unresolved: boolean;
+}
+
+/**
+ * Resolve a suppression reason's `okf:<path>` citation (#1866, design #1059)
+ * against a loaded bundle's concepts, matched on `OkfConcept.path`. Not an
+ * `okf:` citation at all: returns `null`, and the reason renders as plain
+ * text, same as before this section existed. A leading `/` on the cited path
+ * is accepted and stripped — `okf-read.ts`'s bundle-relative paths never
+ * carry one, but the design doc's worked example writes citations with one
+ * (mirroring an absolute-from-bundle-root reading), so both forms resolve.
+ */
+function resolveOkfCitation(reason: string, bundle: OkfBundle | undefined): ResolvedCitation | null {
+  const prefix = "okf:";
+  if (!reason.startsWith(prefix)) return null;
+
+  const token = reason.slice(prefix.length).trim().replace(/^\/+/, "");
+  const concept = bundle?.concepts.find((c) => c.path === token);
+
+  if (concept) {
+    return { label: concept.title ?? concept.path, path: concept.path, unresolved: false };
+  }
+
+  return { label: reason, unresolved: true };
+}
+
+/**
+ * Render the "Suppressed" section: every suppressed diagnostic, grouped by
+ * file like the active section above, with an `okf:` reason resolved to its
+ * concept's title (and bundle-relative path on the line below) when
+ * `bundle` has a match. A citation naming no concept — including when no
+ * `bundle` was loaded at all — prints the raw reason plus a warning; a
+ * plain (non-`okf:`) reason prints as-is. Never affects which diagnostics
+ * are suppressed, only how the reason renders (design #1059: "a cited
+ * suppression suppresses exactly as an uncited one does").
+ */
+function formatSuppressedSection(
+  suppressed: Array<LintDiagnostic & { reason?: string }>,
+  bundle: OkfBundle | undefined,
+): string[] {
+  const lines: string[] = [];
+
+  const byFile = new Map<string, Array<LintDiagnostic & { reason?: string }>>();
+  for (const diag of suppressed) {
     const existing = byFile.get(diag.file) ?? [];
     existing.push(diag);
     byFile.set(diag.file, existing);
   }
 
-  const lines: string[] = [];
-  let errorCount = 0;
-  let warningCount = 0;
+  lines.push("");
+  lines.push(color("Suppressed", colors.underline));
 
   for (const [file, fileDiags] of byFile) {
-    // File header with underline
     lines.push("");
     lines.push(color(file, colors.underline));
 
-    // Sort by line, then column
     fileDiags.sort((a, b) => {
       if (a.line !== b.line) return a.line - b.line;
       return a.column - b.column;
     });
 
     for (const diag of fileDiags) {
-      // Count errors and warnings
-      if (diag.severity === "error") {
-        errorCount++;
-      } else if (diag.severity === "warning") {
-        warningCount++;
-      }
-
-      // Format: "  line:col  severity  message  ruleId"
-      const location = color(
-        `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`,
-        colors.gray
-      );
-
-      const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
-      const severity = color(diag.severity.padEnd(7), severityColor);
-
+      const locationPlain = `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`;
+      const location = color(locationPlain, colors.gray);
+      const severity = color("suppressed", colors.cyan);
       const ruleId = color(diag.ruleId, colors.gray);
 
-      lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+      const citation = diag.reason ? resolveOkfCitation(diag.reason, bundle) : null;
+      const indent = " ".repeat(2 + locationPlain.length + 2 + "suppressed".length + 2 + diag.ruleId.length + 2);
+
+      if (citation) {
+        lines.push(`  ${location}  ${severity}  ${ruleId}  ${citation.label}`);
+        if (!citation.unresolved) {
+          lines.push(`${indent}${color(citation.path!, colors.gray)}`);
+        } else {
+          lines.push(`${indent}${color("⚠ unresolved okf citation", colors.yellow)}`);
+        }
+      } else if (diag.reason) {
+        lines.push(`  ${location}  ${severity}  ${ruleId}  ${diag.reason}`);
+      } else {
+        lines.push(`  ${location}  ${severity}  ${ruleId}`);
+      }
     }
   }
 
-  // Summary line
-  lines.push("");
-  const summary = formatSummary(errorCount, warningCount);
-  lines.push(summary);
-
-  return lines.join("\n");
+  return lines;
 }
 
 /**

package/src/codegen/docs-rule-scanning.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { scanRules } from "./docs-rule-scanning";
+
+// #1938: a post-synth check's `description` string containing a
+// backslash-escaped quote used to truncate at the first embedded `"`,
+// garbling the generated docs table entry.
+describe("scanRules — post-synth description extraction (#1938)", () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "docs-rule-scanning-"));
+    mkdirSync(join(dir, "lint", "post-synth"), { recursive: true });
+    writeFileSync(
+      join(dir, "lint", "post-synth", "wk8505.ts"),
+      [
+        "export const wk8505 = {",
+        '  id: "WK8505",',
+        '  description: "A rule\'s \\"why\\" must be non-empty, and a backslash like C:\\\\path must survive intact",',
+        "  check() { return []; },",
+        "};",
+        "",
+      ].join("\n"),
+    );
+  });
+
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("extracts the full description past an escaped quote and a backslash", () => {
+    const rules = scanRules(dir);
+    const rule = rules.find((r) => r.id === "WK8505");
+
+    expect(rule).toBeDefined();
+    expect(rule?.description).toBe(
+      'A rule\'s "why" must be non-empty, and a backslash like C:\\path must survive intact',
+    );
+  });
+});

package/src/codegen/docs-rule-scanning.ts

@@ -92,7 +92,7 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]):
     } else {
       // Extract from PostSynthCheck objects: id, description
       const idMatch = content.match(/id:\s*"([^"]+)"/);
-      const descMatch = content.match(/description:\s*"([^"]+)"/);
+      const descMatch = content.match(/description:\s*"((?:[^"\\]|\\.)*)"/);
 
       if (idMatch) {
         out.push({
@@ -100,7 +100,7 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]):
             id: idMatch[1],
             severity: "error",
             category: "post-synth",
-            description: descMatch?.[1] ?? idMatch[1],
+            description: descMatch ? unescapeStringLiteral(descMatch[1]) : idMatch[1],
             type: "post-synth",
           },
           source: content,
@@ -110,6 +110,29 @@ function scanDir(dir: string, type: "lint" | "post-synth", out: ScannedRule[]):
   }
 }
 
+/**
+ * Undo the backslash escaping of a double-quoted JS/TS string literal body
+ * captured by a regex like `/description:\s*"((?:[^"\\]|\\.)*)"/` — the
+ * capture group still has the source's escape sequences (`\"`, `\\`, `\n`,
+ * ...) in it verbatim, so a description written as `"say \"hi\""` would
+ * otherwise render in generated docs as `say \"hi\"` instead of `say "hi"`.
+ */
+function unescapeStringLiteral(raw: string): string {
+  return raw.replace(/\\(.)/g, (_, ch: string) => {
+    switch (ch) {
+      case "n":
+        return "\n";
+      case "t":
+        return "\t";
+      case "r":
+        return "\r";
+      default:
+        // \" -> ", \\ -> \, \' -> ', and anything else -> itself unescaped
+        return ch;
+    }
+  });
+}
+
 function extractDescriptionFromComment(
   content: string,
   ruleId: string,

package/src/components/README.md

@@ -33,6 +33,13 @@ adopting chant.
   work for a component whose own name isn't the entity/resource name it
   deploys, falling back to `name` itself when omitted. See
   docs/src/content/docs/components/observability.mdx.
+- **Composite mapping** — `composites` (#1492), optional: the composite kind
+  name(s) this component's deployed resources come from, when a consumer
+  joining a composite graph to the component DAG (e.g. `chant graph
+  --components --format ir`'s node `attrs.composites`, ../cli/handlers/
+  graph.ts) can't infer it by kebab-casing `name` against each composite's
+  kind. Omitted entirely (the default), that naming convention stays in
+  effect with no behavior change.
 - **The three archetypes** — service (build → publish → apply → verify),
   infra (apply → verify, no build), and producer/library (build → publish
   only, no service apply). `deploy` being a plain composition is what makes

package/src/components/auto-release.ts

@@ -117,6 +117,10 @@ export interface AutoReleaseRunInfo {
   digest?: string;
   /** Orchestrator run identifier — a Temporal `runId`, or a locally generated id for the local executor (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
   runId: string;
+  /** The bypassed capability-profile divergences, when the caller deliberately overrode a deploy-time profile assertion (chant #1244) — recorded verbatim as the release record's `profileOverride`. */
+  profileOverride?: string;
+  /** The deploy's input-side digest, when `digest` is a rendered-content identity (a pinned helm deploy, chant #1242) — recorded as the release record's `inputDigest` so ledger queries can still join on inputs across clusters whose bytes legitimately differ. */
+  inputDigest?: string;
 }
 
 /** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
@@ -202,6 +206,8 @@ export async function maybeRecordAutoRelease(
         runId: run.runId,
         timestamp,
         actor,
+        ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
+        ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
       },
       { cwd: options.cwd },
     );

package/src/components/capability.ts

@@ -44,8 +44,23 @@ export interface Capability<In = unknown, Out = unknown> {
   readonly kind: string;
   /** Perform the operation. */
   run(ctx: DeployContext, input: In): Promise<Out>;
-  /** Optional paired compensation, invoked in reverse order on saga rollback. */
-  rollback?(ctx: DeployContext, input: In): Promise<void>;
+  /**
+   * Optional paired compensation, invoked in reverse order on saga rollback.
+   * `output`, when supplied, is the exact value this step's own `run()` call
+   * returned (#1944, epic #1564 phase 4) — a serializable identity channel a
+   * capability can use to recover state `rollback` needs when it cannot rely
+   * on in-process object identity between its `run`/`rollback` calls. The
+   * local interpret driver (../driver.ts) always threads it through; the
+   * durable Temporal path (lexicons/temporal/src/component-op/*.ts) threads
+   * it across the Activity boundary as plain JSON, which is exactly the case
+   * this exists for — see ./verbs/run-agent.ts's "Rollback identity" doc
+   * comment for the motivating gap (a fresh sprite's checkpoint id, recorded
+   * only in an in-process `WeakMap` keyed by `run()`'s `input` object, never
+   * survives to a `rollback()` call that runs as a separate Activity with its
+   * own freshly-resolved `input`). Optional and additive: a capability that
+   * never needs it (most of them) simply ignores the third parameter.
+   */
+  rollback?(ctx: DeployContext, input: In, output?: Out): Promise<void>;
   /**
    * How this verb relates to rollback, for the COMP003 composition check.
    * Usually derivable and left unset: a capability with a `rollback` method is

package/src/components/cli-support.test.ts

@@ -371,6 +371,23 @@ export const backup =
     expect(result.liveNames?.postgres).toEqual(["pgDeployment", "pgService", "pgClaim"]);
     expect(result.liveNames?.plain).toEqual(["plain"]);
   });
+
+  test("carries each component's declared composites, absent (not defaulted) when undeclared (#1492)", async () => {
+    await writeFile(
+      join(testDir, "aws-plane.component.ts"),
+      `export const awsPlane = { name: "aws-plane", composites: ["ArtifactBucket", "OperatorRole"], dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "plain.component.ts"),
+      `export const plain = { name: "plain", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+
+    const result = await computeComponentGraph(testDir);
+
+    expect(result.success).toBe(true);
+    expect(result.composites?.["aws-plane"]).toEqual(["ArtifactBucket", "OperatorRole"]);
+    expect(result.composites?.plain).toBeUndefined();
+  });
 });
 
 // ── runComponents (#585) ─────────────────────────────────────────────────────

package/src/components/cli-support.ts

@@ -141,6 +141,13 @@ export interface ComponentGraphResult {
    * `Component` contract already specifies. This is what lets a consumer join
    * the component DAG to the resource graph without guessing at kinds. */
   liveNames?: Record<string, string[]>;
+  /** Component name → the composite kind name(s) its resources come from (#1492),
+   * present only for components that declared `composites` explicitly. Unlike
+   * `liveNames`, there is no identity fallback — a component's own name is not
+   * a composite kind — so an undeclared component is left out of this map
+   * entirely rather than defaulting to a guess; a consumer with no entry here
+   * keeps applying its own naming-convention default. */
+  composites?: Record<string, string[]>;
   error?: string;
 }
 
@@ -173,10 +180,15 @@ export async function computeComponentGraph(
   // component name → owned live resource names (#1491), declared or the
   // contract's identity fallback.
   const liveNames: Record<string, string[]> = {};
+  // component name → declared composite kind(s) (#1492), only for components
+  // that declared them — no identity fallback (see ComponentGraphResult doc).
+  const composites: Record<string, string[]> = {};
   for (const [name, discovered] of result.components) {
     files[name] = relative(path, discovered.filePath);
     const declared = discovered.component.liveNames;
     liveNames[name] = declared && declared.length > 0 ? [...declared] : [name];
+    const declaredComposites = discovered.component.composites;
+    if (declaredComposites && declaredComposites.length > 0) composites[name] = [...declaredComposites];
   }
 
   try {
@@ -185,7 +197,7 @@ export async function computeComponentGraph(
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files, liveNames };
+    return { success: true, order, waves, edges, files, liveNames, composites };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };