@intentius/chant 0.49.0 → 0.50.0

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/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";