@intentius/chant 0.49.0 → 0.51.0

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 };

package/src/components/component-schema.test.ts

@@ -143,6 +143,38 @@ describe("Component JSON Schema", () => {
     expect(validate(invalid)).toBe(false);
   });
 
+  it("accepts an optional composites list (#1492)", () => {
+    const withComposites = {
+      name: "aws-plane",
+      archetype: "infra",
+      dependsOn: [],
+      composites: ["ArtifactBucket", "OperatorRole"],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(withComposites)).toBe(true);
+  });
+
+  it("omitting composites still validates (backward-compatible default)", () => {
+    const noComposites = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(noComposites)).toBe(true);
+  });
+
+  it("rejects an empty composites array (minItems: 1)", () => {
+    const invalid = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      composites: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(invalid)).toBe(false);
+  });
+
   it("rejects an invalid archetype value", () => {
     const invalid = {
       name: "x",

package/src/components/component.schema.json

@@ -54,6 +54,12 @@
       "description": "Optional: the live lexicon entity/resource name(s) this component owns, when they differ from `name` (#598). `chant components status --live` reconciles the release ledger against live evidence by joining on this name; omitted entirely (the default), the join falls back to `name` itself with no behavior change. A component that owns several live entities (e.g. a fan-out cluster with one stack per node) may list them all.",
       "items": { "type": "string", "minLength": 1 },
       "minItems": 1
+    },
+    "composites": {
+      "type": "array",
+      "description": "Optional: the composite kind name(s) this component's deployed resources come from, when a consumer cannot infer it from `name` (#1492). Without this, a consumer joining a composite graph to the component DAG guesses by kebab-casing each composite's kind and matching it against this component's `name`, which only holds when a component maps 1:1 to a composite named for it. Omitted entirely (the default), the naming convention stays in effect with no behavior change. A component built from several composites may list them all.",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
     }
   },
   "$defs": {

package/src/components/component.test.ts

@@ -202,6 +202,27 @@ describe("projectToJson()", () => {
     expect("liveNames" in projected).toBe(false);
   });
 
+  it("projects an explicit composites list through unchanged (#1492)", () => {
+    const component: Component = {
+      name: "aws-plane",
+      dependsOn: [],
+      composites: ["ArtifactBucket", "OperatorRole"],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as { composites?: string[] };
+    expect(projected.composites).toEqual(["ArtifactBucket", "OperatorRole"]);
+  });
+
+  it("omits composites from the projection when not authored (#1492)", () => {
+    const component: Component = {
+      name: "table",
+      dependsOn: [],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as Record<string, unknown>;
+    expect("composites" in projected).toBe(false);
+  });
+
   it("projects a stackOutput() wiring reference to its plain-JSON form", () => {
     const component: Component = {
       name: "svc",

package/src/components/component.ts

@@ -148,6 +148,21 @@ export interface Component {
    * name == entity join with no behavior change.
    */
   liveNames?: string[];
+  /**
+   * Optional: the composite kind name(s) this component's deployed resources
+   * come from, when a consumer joining a composite graph to the component DAG
+   * cannot infer it from `name` (#1492). Components and composites are
+   * different namespaces, the same class of mismatch `liveNames` covers for
+   * components and lexicon entities: a consumer without this field guesses by
+   * kebab-casing each composite's kind and matching it against this
+   * component's `name` (`LoomBackend` -> `loom-backend`), which only holds
+   * when a component maps 1:1 to a composite named for it. A component built
+   * from several composites (e.g. one stack containing both an ArtifactBucket
+   * and an OperatorRole composite, plus loose resources) lists them all.
+   * Omitted entirely (the common case), the naming convention stays the
+   * default and nothing changes.
+   */
+  composites?: string[];
 }
 
 /** Author a named phase. `steps` may mix capability `Step`s, `Gate`s, and nested `Phase`s (fan-out). */

package/src/components/driver.ts

@@ -313,11 +313,19 @@ export function resolveStepInput(
 
 // ── Step + phase execution ───────────────────────────────────────────────
 
-/** A step executed and its resolved input, kept so saga rollback can call the same capability's `rollback` with the same input. */
+/**
+ * A step executed and its resolved input, kept so saga rollback can call the
+ * same capability's `rollback` with the same input. `output` is the step's
+ * own `run()` result — threaded through to `rollback` (#1944) as the
+ * serializable identity channel `Capability.rollback`'s doc comment
+ * describes, alongside object identity (which already works here, since this
+ * driver runs entirely in-process — see this module's own doc comment).
+ */
 interface ExecutedStep {
   step: DriverStep;
   resolvedInput: Record<string, unknown>;
   phaseName: string;
+  output: unknown;
 }
 
 class StepFailure extends Error {
@@ -435,7 +443,7 @@ async function runPhase(
     }
     return {
       records: [record],
-      executed: record.status === "ok" ? [{ step: entry, resolvedInput, phaseName: phaseDef.phase }] : [],
+      executed: record.status === "ok" ? [{ step: entry, resolvedInput, phaseName: phaseDef.phase, output }] : [],
       failed: record.status === "fail",
     };
   };
@@ -505,7 +513,7 @@ async function rollbackExecuted(
   registry: CapabilityRegistry,
 ): Promise<DriverStepRecord[]> {
   const records: DriverStepRecord[] = [];
-  for (const { step, resolvedInput, phaseName } of [...executed].reverse()) {
+  for (const { step, resolvedInput, phaseName, output } of [...executed].reverse()) {
     const start = Date.now();
     try {
       const capability = registry.resolve(step.kind);
@@ -521,7 +529,7 @@ async function rollbackExecuted(
         });
         continue;
       }
-      await capability.rollback(ctx, resolvedInput as never);
+      await capability.rollback(ctx, resolvedInput as never, output as never);
       records.push({
         component: ctx.component,
         phase: phaseName,

package/src/components/run-progress.ts

@@ -107,11 +107,15 @@ export type RunProgressSink = (event: RunProgressEvent) => void;
 /**
  * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
  * `process.stdout.write`), one line per event, as they happen — the
- * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts). Kept separate
- * from `driver-output.ts`'s end-of-run renderers: this emits *during* the
- * run, one line at a time; `renderDriverJson`/`renderDriverHuman` render the
- * completed `DriverRunResult` once, after the run finishes.
+ * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts, for both the
+ * `--components` driver's `RunProgressEvent`s and the Temporal Op path's
+ * `StepRecord`s, chant #1676). Kept separate from `driver-output.ts`'s
+ * end-of-run renderers: this emits *during* the run, one line at a time;
+ * `renderDriverJson`/`renderDriverHuman` render the completed
+ * `DriverRunResult` once, after the run finishes.
  */
-export function ndjsonProgressSink(write: (chunk: string) => void = (s) => void process.stdout.write(s)): RunProgressSink {
+export function ndjsonProgressSink<T = RunProgressEvent>(
+  write: (chunk: string) => void = (s) => void process.stdout.write(s),
+): (event: T) => void {
   return (event) => write(JSON.stringify(event) + "\n");
 }

package/src/components/verbs/index.ts

@@ -30,7 +30,11 @@
  * ./wrangler.ts) and `r2-sync` (#1293, ./r2-sync.ts) are the Cloudflare
  * Workers apply leaves — real implementations over the same injectable
  * `ProcessRunner` `sign` uses, shelling to `wrangler`/`rclone` rather than an
- * AWS-shaped SDK client.
+ * AWS-shaped SDK client. `run-agent` (#1941, epic #1564 phase 1, ./run-agent.ts)
+ * is the typed schema + registry entry for a bounded, attested agent-turn
+ * capability over a fly Sprite — a typed stub for now (`run`/`rollback`
+ * reject with `CapabilityNotImplementedError`), `rollbackPolicy: "native"`
+ * declared up front; the real sprite-lifecycle implementation is #1942.
  */
 
 export * from "./build-archive";
@@ -44,6 +48,7 @@ export * from "./component-bom";
 export * from "./reproducibility";
 export * from "./sign";
 export * from "./verify";
+export * from "./run-agent";
 export * from "./wrangler";
 export * from "./r2-sync";
 export * from "./vuln-scan";