@intentius/chant 0.13.1 → 0.15.0

package/src/components/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Component-native release orchestration — capability contract, starter verb
+ * set, and the thin interpret driver (epic #551, #554/#556). The pilot AWS
+ * leaves have real implementations over an injectable `CloudExecutor` (#557);
+ * every other verb remains a typed stub. See https://intentius.io/chant/components/orchestration/
+ */
+
+export {
+  type Archetype,
+  type Wiring,
+  type StackOutputReference,
+  type BuildSpec,
+  type Step,
+  type Gate,
+  type Phase,
+  type Component,
+  phase,
+  gate,
+  stackOutput,
+  inferArchetype,
+  projectToJson,
+  isComponent,
+} from "./component";
+export {
+  type DiscoveredComponent,
+  type ComponentDiscoveryResult,
+  discoverComponents,
+} from "./discover";
+export {
+  type ListedComponent,
+  type ListComponentsResult,
+  type DescribedComponent,
+  type DescribeComponentResult,
+  type ComponentGraphResult,
+  type GenerateLexicon,
+  type GenerateComponentsResult,
+  type RunComponentsOptions,
+  type RunComponentsResult,
+  type ResolvedComponentTargets,
+  listComponents,
+  describeComponent,
+  computeComponentGraph,
+  generateComponentsPipeline,
+  runComponents,
+  findComponentGate,
+  resolveComponentTargets,
+} from "./cli-support";
+export { renderDriverHuman, renderDriverJson } from "./driver-output";
+export {
+  type Capability,
+  type CapabilityInput,
+  type CapabilityOutput,
+  type DeployContext,
+  CapabilityRegistry,
+  CapabilityNotImplementedError,
+} from "./capability";
+export { createCapabilityRegistry, STARTER_VERB_FAMILIES } from "./registry";
+export {
+  type CapabilityPlugin,
+  type CapabilityManifest,
+  isCapabilityPlugin,
+} from "./capability-plugin";
+export {
+  CapabilityManifestSchema,
+  type CapabilityManifestParsed,
+  validateCapabilityManifest,
+} from "./capability-plugin-schema";
+export {
+  loadCapabilityPlugin,
+  loadCapabilityPlugins,
+  registerCapabilityPlugins,
+  buildCapabilityRegistry,
+  type BuildCapabilityRegistryOptions,
+  MalformedCapabilityPluginError,
+  DuplicateCapabilityKindError,
+} from "./capability-plugin-loader";
+export { starterCapabilityPlugin } from "./starter-plugin";
+export * from "./verbs/index";
+export * from "./builders";
+export {
+  type DriverStep,
+  type DriverGate,
+  type DriverPhase,
+  type DriverComponent,
+  type DriverStepRecord,
+  type DriverComponentResult,
+  type DriverRunResult,
+  type ComponentGraph,
+  type InterpretRunOptions,
+  type WiringValue,
+  resolveComponentGraph,
+  resolveWiring,
+  resolveStepInput,
+  runComponentDeploy,
+  runInterpretDriver,
+  DriverGateUnsupportedError,
+  DependencyCycleError,
+  UnknownDependencyError,
+  DriverRunFailure,
+} from "./driver";
+export {
+  EcsFargateComponent,
+  type EcsFargateComponentConfig,
+  LambdaComponent,
+  type LambdaComponentConfig,
+  SingleHostComposeComponent,
+  type SingleHostComposeComponentConfig,
+} from "./presets/index";
+export {
+  type ComponentTemporalCodegen,
+  type ComponentTemporalCodegenOptions,
+  loadComponentTemporalCodegen,
+} from "./temporal-codegen-loader";

package/src/components/manifest-persistence.test.ts

@@ -0,0 +1,152 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { DriverStepRecord } from "./driver";
+import { createBuildArchiveManifest, addArchiveEntry, type BuildArchiveManifest } from "./verbs/build-archive";
+
+const persistBuildManifestMock = vi.fn();
+const pushLifecycleMock = vi.fn();
+
+vi.mock("../lifecycle/build-ledger-store", () => ({
+  persistBuildManifest: (...args: unknown[]) => persistBuildManifestMock(...args),
+}));
+
+vi.mock("../lifecycle/git", () => ({
+  pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+}));
+
+const {
+  maybePersistBuildManifest,
+  extractRunManifest,
+  extractRunManifestFromPhaseOutputs,
+} = await import("./manifest-persistence");
+
+function makeManifest(component: string, digest: string): BuildArchiveManifest {
+  let manifest = createBuildArchiveManifest(component, { now: () => new Date("2026-01-01T00:00:00.000Z") });
+  manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest });
+  return manifest;
+}
+
+function buildRecord(manifest: BuildArchiveManifest): DriverStepRecord {
+  return {
+    component: manifest.component,
+    phase: "Build",
+    kind: "docker-build",
+    status: "ok",
+    durationMs: 5,
+    output: { archivePath: "image.tar", digest: manifest.contents[0]!.digest, manifest },
+  };
+}
+
+function applyRecord(): DriverStepRecord {
+  return { component: "svc", phase: "Apply", kind: "cfn-deploy", status: "ok", durationMs: 5, output: { ok: true } };
+}
+
+describe("extractRunManifest", () => {
+  test("finds the manifest from a build-shaped step output", () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    expect(extractRunManifest([buildRecord(manifest)])).toEqual(manifest);
+  });
+
+  test("returns undefined when no step produced a manifest", () => {
+    expect(extractRunManifest([applyRecord()])).toBeUndefined();
+  });
+
+  test("ignores failed/skipped steps", () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    const failed: DriverStepRecord = { ...buildRecord(manifest), status: "fail", output: undefined };
+    expect(extractRunManifest([failed])).toBeUndefined();
+  });
+
+  test("takes the last (most-accumulated) manifest when multiple build steps ran", () => {
+    const first = makeManifest("svc", "sha256:first");
+    let second = makeManifest("svc", "sha256:first");
+    second = addArchiveEntry(second, { kind: "image", path: "second.tar", digest: "sha256:second" });
+
+    const result = extractRunManifest([buildRecord(first), buildRecord(second)]);
+    expect(result).toEqual(second);
+    expect(result?.contents).toHaveLength(2);
+  });
+});
+
+describe("extractRunManifestFromPhaseOutputs", () => {
+  test("finds the manifest across phase outputs (Temporal workflow result shape)", () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    expect(
+      extractRunManifestFromPhaseOutputs({
+        Build: { archivePath: "image.tar", digest: "sha256:abc", manifest },
+        Apply: { ok: true },
+      }),
+    ).toEqual(manifest);
+  });
+
+  test("returns undefined for undefined/empty phaseOutputs", () => {
+    expect(extractRunManifestFromPhaseOutputs(undefined)).toBeUndefined();
+    expect(extractRunManifestFromPhaseOutputs({})).toBeUndefined();
+  });
+});
+
+describe("maybePersistBuildManifest", () => {
+  beforeEach(() => {
+    persistBuildManifestMock.mockReset();
+    pushLifecycleMock.mockReset().mockResolvedValue(true);
+  });
+
+  test("success with a manifest in records -> persists and pushes", async () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    persistBuildManifestMock.mockResolvedValue({ commit: "a".repeat(40) });
+
+    const outcome = await maybePersistBuildManifest({ success: true, records: [buildRecord(manifest)] });
+
+    expect(outcome).toEqual({ persisted: true, commit: "a".repeat(40), manifestDigest: manifest.manifestDigest });
+    expect(persistBuildManifestMock).toHaveBeenCalledTimes(1);
+    expect(persistBuildManifestMock.mock.calls[0][0]).toEqual(manifest);
+    expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a pre-resolved manifest (Temporal path) takes precedence over records", async () => {
+    const preResolved = makeManifest("svc", "sha256:temporal");
+    persistBuildManifestMock.mockResolvedValue({ commit: "b".repeat(40) });
+
+    const outcome = await maybePersistBuildManifest({
+      success: true,
+      manifest: preResolved,
+      records: [buildRecord(makeManifest("svc", "sha256:ignored"))],
+    });
+
+    expect(outcome).toMatchObject({ persisted: true, manifestDigest: preResolved.manifestDigest });
+    expect(persistBuildManifestMock.mock.calls[0][0]).toEqual(preResolved);
+  });
+
+  test("failure (run.success = false) -> persists nothing (dry-run/failed-deploy safety)", async () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    const outcome = await maybePersistBuildManifest({ success: false, records: [buildRecord(manifest)] });
+    expect(outcome).toEqual({ persisted: false, reason: "run-not-successful" });
+    expect(persistBuildManifestMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+  });
+
+  test("opt-out (options.disabled) -> persists nothing, even on a successful run with a manifest", async () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    const outcome = await maybePersistBuildManifest(
+      { success: true, records: [buildRecord(manifest)] },
+      { disabled: true },
+    );
+    expect(outcome).toEqual({ persisted: false, reason: "opted-out" });
+    expect(persistBuildManifestMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+  });
+
+  test("no manifest in the run's records -> skipped, not an error (infra-only/apply-only component)", async () => {
+    const outcome = await maybePersistBuildManifest({ success: true, records: [applyRecord()] });
+    expect(outcome).toEqual({ persisted: false, reason: "no-manifest" });
+    expect(persistBuildManifestMock).not.toHaveBeenCalled();
+  });
+
+  test("persist failure -> reported as an error result, not thrown, and never masks the successful deploy", async () => {
+    const manifest = makeManifest("svc", "sha256:abc");
+    persistBuildManifestMock.mockRejectedValue(new Error("git write failed"));
+
+    await expect(
+      maybePersistBuildManifest({ success: true, records: [buildRecord(manifest)] }),
+    ).resolves.toMatchObject({ persisted: false, reason: "error", error: "git write failed" });
+  });
+});

package/src/components/manifest-persistence.ts

@@ -0,0 +1,164 @@
+/**
+ * Persist a component run's `BuildArchiveManifest` after a successful `chant
+ * run --components <name> --env <env>` (#609, epic #551 follow-up to
+ * #564/#568/#606/#613/#614). Mirrors ./auto-release.ts's shape exactly —
+ * same "extract from step records, then call a lifecycle-layer writer, then
+ * push, and never let a write failure fail an already-successful deploy"
+ * structure — because it is solving the same class of problem: the driver
+ * produces something worth recording durably, but the driver itself must
+ * stay capability-agnostic (../components/driver.ts takes no dependency on
+ * ../lifecycle/*), so the CLI performs the write as a post-run step.
+ *
+ * **Why here, not the driver.** Same reasoning as ./auto-release.ts's module
+ * doc: a manifest write is a git commit + push, a non-idempotent side effect
+ * with real-world I/O — exactly what `driver.ts` resists taking on (it is
+ * exercised in tests against a bare `CapabilityRegistry` with no lifecycle
+ * dependency at all) and what Temporal workflow code must never do directly
+ * (replay-safety). The CLI calls this after `runComponents`/`handle.result()`
+ * reports success, the same place `maybeRecordAutoRelease` is already
+ * called from (../cli/handlers/run.ts).
+ *
+ * **Extraction is duck-typed, not capability-specific.** `docker-build`,
+ * `generate-sbom`, `extract-config-bom`, and `addArchiveTemplate` (the
+ * build-family capabilities/helpers, ../components/verbs/build.ts,
+ * ./verbs/sbom.ts, ./verbs/config-bom.ts) all return `{ ..., manifest:
+ * BuildArchiveManifest }` — the accumulation convention documented on each of
+ * their inputs ("manifest to extend... same accumulation convention"). This
+ * module scans a run's step outputs for that shape, exactly the way
+ * ./auto-release.ts's `extractRunDigest` scans for a publish-shaped output,
+ * so a new build-family capability that follows the same `{ manifest }`
+ * output convention is picked up automatically — no branch here names a
+ * specific capability `kind`.
+ */
+import { persistBuildManifest } from "../lifecycle/build-ledger-store";
+import { pushLifecycle } from "../lifecycle/git";
+import type { BuildArchiveManifest } from "./verbs/build-archive";
+import type { DriverStepRecord } from "./driver";
+
+/** A step output shaped like it carries a `BuildArchiveManifest` — duck-typed the same way ./auto-release.ts's `isPublishShaped` detects a publish result. */
+function isManifestShaped(output: unknown): output is { manifest: BuildArchiveManifest } {
+  return (
+    !!output &&
+    typeof output === "object" &&
+    "manifest" in output &&
+    !!(output as { manifest?: unknown }).manifest &&
+    typeof (output as { manifest?: unknown }).manifest === "object"
+  );
+}
+
+/**
+ * Find the most fully-accumulated `BuildArchiveManifest` a component run
+ * produced, by scanning its step records for the last manifest-bearing
+ * output — mirroring `extractRunDigest`'s "last wins" convention, which is
+ * also the correct one here: every build-family capability's `manifest`
+ * input/output accumulates onto whatever manifest came before it in the same
+ * phase (see ../components/verbs/build.ts's `DockerBuildInput.manifest`
+ * doc), so the *last* manifest-bearing step output in run order is always
+ * the fullest one — a template + SBOM + config-BOM composition's final step
+ * carries every earlier entry too, not just its own.
+ */
+export function extractRunManifest(records: DriverStepRecord[]): BuildArchiveManifest | undefined {
+  let found: BuildArchiveManifest | undefined;
+  for (const record of records) {
+    if (record.status !== "ok") continue;
+    if (isManifestShaped(record.output)) {
+      found = record.output.manifest;
+    }
+  }
+  return found;
+}
+
+/**
+ * Same manifest extraction as `extractRunManifest`, but over a component
+ * Temporal workflow's returned `phaseOutputs` (`{ [phase]: output }`) —
+ * mirroring ./auto-release.ts's `extractRunDigestFromPhaseOutputs`, the
+ * `--temporal` CLI path's counterpart, since that path never sees individual
+ * step records either.
+ */
+export function extractRunManifestFromPhaseOutputs(
+  phaseOutputs: Record<string, Record<string, unknown>> | undefined,
+): BuildArchiveManifest | undefined {
+  let found: BuildArchiveManifest | undefined;
+  for (const output of Object.values(phaseOutputs ?? {})) {
+    if (isManifestShaped(output)) {
+      found = output.manifest;
+    }
+  }
+  return found;
+}
+
+/** Explicit reasons `maybePersistBuildManifest` declined to write — never a thrown error, mirroring ./auto-release.ts's `AutoReleaseSkipReason`. */
+export type ManifestPersistSkipReason = "opted-out" | "run-not-successful" | "no-manifest";
+
+export type ManifestPersistResult =
+  | { persisted: true; commit: string; manifestDigest: string }
+  | { persisted: false; reason: ManifestPersistSkipReason }
+  | { persisted: false; reason: "error"; error: string };
+
+/** Input describing one component's completed run — the manifest-persistence counterpart of ./auto-release.ts's `AutoReleaseRunInfo`. */
+export interface ManifestPersistRunInfo {
+  /** Whether the run reported overall success. A caller must not call this for a non-terminal/in-progress run — mirrors `AutoReleaseRunInfo.success`. */
+  success: boolean;
+  /** The component's step records (local executor), used to locate the accumulated manifest via `extractRunManifest`. Mutually exclusive with `manifest`. */
+  records?: DriverStepRecord[];
+  /** A manifest already resolved by the caller (e.g. a future durable/Temporal path that has its own phaseOutputs-shaped extraction). Takes precedence over `records` when both are given. */
+  manifest?: BuildArchiveManifest;
+}
+
+/** Opt-out knobs for manifest persistence, mirroring ./auto-release.ts's `AutoReleaseOptions`. */
+export interface ManifestPersistOptions {
+  /** `--no-release-record` / `chant.config.ts`'s `release.autoRecord: false` also gates manifest persistence — both are "durably record this successful deploy" side effects with the same opt-out story, so one flag/config knob controls both rather than introducing a second, easy-to-forget switch. Default: persistence is ON. */
+  disabled?: boolean;
+  /** Working directory for the git plumbing calls (tests). */
+  cwd?: string;
+}
+
+/**
+ * After a successful `chant run --components <name> --env <env>` (local
+ * executor), persist the run's accumulated `BuildArchiveManifest` (if any)
+ * to the durable build-manifest store (../lifecycle/build-ledger-store.ts)
+ * and push it — or explain, without throwing, why it didn't. Never called
+ * for a failed run, matching `maybeRecordAutoRelease`'s contract exactly.
+ *
+ * Skips (returns `{ persisted: false, reason }`, never throws):
+ *  - `options.disabled` — the opt-out flag/config was set.
+ *  - `run.success` false — defensive; callers should not reach here on
+ *    failure. A dry-run/failed deploy persists nothing, by construction —
+ *    this is also what makes a dry run safe: `chant run --components` never
+ *    calls this function at all unless the run actually completed.
+ *  - no manifest found in the run's records — a component with no
+ *    build-family step (an infra-only/apply-only component, or a
+ *    build-less `Publish`-only producer that reused a prior archive) has
+ *    nothing to persist. This is the expected common case for most deploys,
+ *    not an error.
+ *
+ * Write/push failures (any error `persistBuildManifest`/`pushLifecycle`
+ * throw) are reported as `{ persisted: false, reason: "error", error }`
+ * rather than propagated — same "never turn a successful deploy into a
+ * failing CLI invocation" contract `maybeRecordAutoRelease` already
+ * establishes for release records.
+ */
+export async function maybePersistBuildManifest(
+  run: ManifestPersistRunInfo,
+  options: ManifestPersistOptions = {},
+): Promise<ManifestPersistResult> {
+  if (options.disabled) {
+    return { persisted: false, reason: "opted-out" };
+  }
+  if (!run.success) {
+    return { persisted: false, reason: "run-not-successful" };
+  }
+
+  const manifest = run.manifest ?? extractRunManifest(run.records ?? []);
+  if (!manifest) {
+    return { persisted: false, reason: "no-manifest" };
+  }
+
+  try {
+    const { commit } = await persistBuildManifest(manifest, { cwd: options.cwd });
+    await pushLifecycle({ cwd: options.cwd });
+    return { persisted: true, commit, manifestDigest: manifest.manifestDigest };
+  } catch (err) {
+    return { persisted: false, reason: "error", error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/components/pilots/README.md

@@ -0,0 +1,33 @@
+# Pilot component definitions
+
+Three concrete components authored against the [Component contract](../../../../../docs/src/content/docs/components/component-contract.mdx), picked (epic [#551](https://github.com/INTENTIUS/chant/issues/551)) to be the three most-different real components chant deploys today. Each is provided as:
+
+- a **TypeScript authoring form** (`*.pilot.ts`) — composed using the real capability `kind` verbs and typed inputs from [`../verbs`](../verbs/), against the real typed `Component`/`phase()`/`gate()`/`stackOutput()` authoring frontend (`../component.ts`, Phase 2, [#560](https://github.com/INTENTIUS/chant/issues/560)). Prior to #560 these pilots authored against a local stopgap shape (`authoring-shape.ts`, now deleted) that mirrored `component.schema.json` field-for-field as a placeholder; migrating them to import `../component` instead was a like-for-like swap since the two shapes matched 1:1 by design.
+- its **JSON projection** (`project.ts` + [`pilots.test.ts`](./pilots.test.ts)) — asserted equal to the existing fixture in [`../__fixtures__/`](../__fixtures__/) that already validates against the schema ([#553](https://github.com/INTENTIUS/chant/issues/553)/[#571](https://github.com/INTENTIUS/chant/pull/571)). The fixture stays the one authoritative JSON document per pilot; this directory does not fork a second copy.
+
+## Mapping to the epic's axes
+
+The epic ([#551](https://github.com/INTENTIUS/chant/issues/551)) picked these three specifically to exercise different points on each axis at once, so three components prove more than three would if they were shape-variations of each other.
+
+| Pilot | File / fixture | build vs no-build | single vs fan-out | sticky vs simple apply | cross-stack wiring | auto vs no rollback |
+|---|---|---|---|---|---|---|
+| **Neo4j per-instance fan-out** | [`neo4j-fanout.pilot.ts`](./neo4j-fanout.pilot.ts) / [`neo4j-fanout.json`](../__fixtures__/neo4j-fanout.json) | no-build (`infra`, applies pre-built templates) | **fan-out** — one component composes 3 per-instance mini-compositions (`cfn-deploy` + `code-deploy` + `wait-cluster-healthy`), seed-first then rolling, gated at node 1 | simple apply (no `onReplace`/`stageGsi` — no sticky CFN concerns here) | none (self-contained cluster, no shared-stack imports) | **auto** — `code-deploy` (AWS CodeDeploy) rollback is native/automatic on failure, declared once inside the capability, never scripted per node |
+| **DynamoDB table** | [`dynamodb.pilot.ts`](./dynamodb.pilot.ts) / [`dynamodb-infra.json`](../__fixtures__/dynamodb-infra.json) | no-build (`infra`, applies an existing table template) | single (one `cfn-deploy`, no fan-out) | **sticky** — `onReplace: "block"` refuses a replacing changeset (data loss guard); `stageGsi: true` stages the GSI add→backfill→remove instead of an in-place replace | none | no rollback declared — a blocked replacement is not something to compensate, it is a stop |
+| **ALB/ECS target** | [`alb-ecs.pilot.ts`](./alb-ecs.pilot.ts) / [`alb-ecs-service.json`](../__fixtures__/alb-ecs-service.json) | **build** — `docker-build` → `publish-image` (promote by digest at deploy time) | single (one service, one `cfn-deploy` + `ecs-update-service`) | simple apply (no replacement-sensitive resource here) | **cross-stack** — imports `shared-alb`'s `ListenerArn`/`ClusterArn`/`Subnets` via `stackOutput()`, replacing the `describe-stacks \| jq` glue in [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-api/src/pipeline.ts) | **no** (component-declared) — `ecs-update-service`/`cfn-deploy` have no native automatic rollback for an already-running service swap, so the component supplies an explicit `rollback` phase (`rollback-previous`) rather than relying on capability compensation |
+
+Read together, the three cover every cell at least once: build only shows up for ALB/ECS, fan-out only for Neo4j, sticky-apply only for DynamoDB, cross-stack only for ALB/ECS, and both rollback styles (capability-native vs component-declared) appear once each.
+
+## A fourth component (#558): image-processor Lambda
+
+[`lambda.pilot.ts`](./lambda.pilot.ts) / [`lambda-image-processor.json`](../__fixtures__/lambda-image-processor.json) adds a fourth component, added after the three above to validate the sprawl metric ([#551](https://github.com/INTENTIUS/chant/issues/551)#definition-of-done-the-sprawl-metric), not to re-cover the same axes. It reuses `docker-build`/`publish-image` unchanged (build + promote-by-digest is identical to ALB/ECS's) but its Apply phase dispatches to `lambda-deploy` instead of `cfn-deploy` — the first component in the set with no CloudFormation stack in its apply step at all. `lambda-deploy` was the one new capability this component needed; see [`../SPRAWL-VALIDATION.md`](../SPRAWL-VALIDATION.md) for the full accounting and the ALB/ECS pipeline-glue before/after.
+
+## Why the fixture is authoritative, not this directory
+
+[#555](https://github.com/INTENTIUS/chant/issues/555) explicitly scopes "committed under an `examples/` or `fixtures/` path" — the schema's own `__fixtures__/` already holds real components drawn from this epic, including these three. Duplicating them here as a second JSON copy would immediately be the "composition copy-paste" / definition-sprawl failure mode the epic itself guards against ([#551](https://github.com/INTENTIUS/chant/issues/551)#failure-modes). Instead:
+
+- `../__fixtures__/*.json` remains the one JSON document per pilot, already covered by [`../component-schema.test.ts`](../component-schema.test.ts).
+- This directory adds the TypeScript authoring form the issue also asks for, and [`pilots.test.ts`](./pilots.test.ts) asserts the two never drift apart — if a pilot's composition changes, the fixture is the file to update, and the test fails loudly if only one side moves.
+
+## What's out of scope here
+
+Per the issue: running these compositions (the [Phase 1 driver](https://github.com/INTENTIUS/chant/issues/556)) and real capability implementations ([#557](https://github.com/INTENTIUS/chant/issues/557)) are separate issues. Every capability referenced below is still a typed stub (see [`../verbs/`](../verbs/)) — `run()`/`rollback()` throw `CapabilityNotImplementedError`. Nothing here executes anything.

package/src/components/pilots/alb-ecs.pilot.ts

@@ -0,0 +1,63 @@
+/**
+ * Pilot: ALB/ECS target (#555, epic #551).
+ *
+ * Exercises the build + cross-stack + auto-rollback axes: `docker-build` →
+ * `publish-image` (promote by digest, deploy-time) → `cfn-deploy` (importing
+ * the shared ALB's listener/cluster/subnets as cross-stack outputs, resolved
+ * by `chant graph --stacks` rather than a `describe-stacks | jq` pipeline
+ * step — see composition-and-wiring.mdx#cross-stack-outputs) →
+ * `ecs-update-service` → `wait-steady-state` + `health-gate`.
+ *
+ * This is the direct component-native replacement for the hand-rolled GitLab
+ * pipeline in `examples/gitlab-aws-alb-api/src/pipeline.ts`: the
+ * `describe-stacks`/`jq` glue in that pipeline's `deployService` job is
+ * exactly the cross-stack `stackOutput()` wiring below, and its
+ * `docker build`/`docker push` steps are the `docker-build` + `publish-image`
+ * capabilities. `service` archetype: build → publish → apply → verify, the
+ * fullest of the three archetypes.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/alb-ecs-service.json (already schema-validated by
+ * component-schema.test.ts) — this module is the real typed `Component`
+ * authoring form (#560, ../component.ts) that composes to that same
+ * document; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+
+import type { Component } from "../component";
+import { phase, stackOutput } from "../component";
+
+/** The shared ALB stack's exported outputs this service imports — the cross-stack wiring axis. */
+const sharedAlbOutputs = {
+  listenerArn: stackOutput("shared-alb", "ListenerArn"),
+  clusterArn: stackOutput("shared-alb", "ClusterArn"),
+  subnets: stackOutput("shared-alb", "Subnets"),
+};
+
+export const searchService: Component = {
+  name: "search-service",
+  archetype: "service",
+  dependsOn: ["shared-alb"],
+  build: { kind: "docker-build", context: ".", into: "archive" },
+  deploy: [
+    phase("Publish", [{ kind: "publish-image", from: "archive", to: "$env.registry" }]),
+    phase("Apply", [
+      {
+        kind: "cfn-deploy",
+        template: "archive:search.template.json",
+        imageRef: "@Publish.digest",
+        inputs: sharedAlbOutputs,
+      },
+      { kind: "ecs-update-service", cluster: "$env.cluster", service: "search" },
+    ]),
+    phase("Verify", [
+      { kind: "wait-steady-state", service: "search" },
+      { kind: "health-gate", path: "/healthz" },
+    ]),
+  ],
+  // No native `rollback` on ecs-update-service/cfn-deploy for an already-running
+  // service swap — the component declares an explicit compensation phase
+  // (auto/no-rollback axis: this is the "no automatic capability rollback,
+  // component supplies its own" side, contrasted with code-deploy's native
+  // automatic rollback in the Neo4j pilot).
+  rollback: [phase("Rollback", [{ kind: "rollback-previous", service: "search", cluster: "$env.cluster" }])],
+};

package/src/components/pilots/dynamodb.pilot.ts

@@ -0,0 +1,59 @@
+/**
+ * Pilot: DynamoDB table (#555, epic #551).
+ *
+ * Exercises the sticky-apply axis: `cfn-deploy` carries declarative safety
+ * options — `onReplace: "block"` refuses a changeset that would replace the
+ * table (losing data) rather than update it in place, and `stageGsi: true`
+ * stages a GSI change (add → backfill → remove) instead of an in-place
+ * replace. That stickiness lives inside the `cfn-deploy` capability, exposed
+ * as options, not scripted per component — see
+ * capabilities.mdx#stickiness-lives-in-the-capability. `infra` archetype: no
+ * build, apply → verify only. Verify fans out in parallel: the stack wait and
+ * a GSI backfill migration have no ordering dependency on each other.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/dynamodb-infra.json (already schema-validated by
+ * component-schema.test.ts) — this module is the real typed `Component`
+ * authoring form (#560, ../component.ts) that composes to that same
+ * document; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+
+import type { Component } from "../component";
+import { phase } from "../component";
+
+// `cfn-deploy`'s safety fields, kept as a plain literal here: the pilot is
+// agnostic component *data* naming the `cfn-deploy` kind, so it does not import
+// the AWS capability's types (those live in the aws lexicon now). The `onReplace`
+// value must match `cfn-deploy`'s `CfnReplacePolicy` union.
+const cfnSafetyOptions: { onReplace: "block" | "allow" | "snapshot-first"; stageGsi: boolean } = {
+  onReplace: "block",
+  stageGsi: true,
+};
+
+export const ordersTable: Component = {
+  name: "orders-table",
+  archetype: "infra",
+  dependsOn: [],
+  deploy: [
+    phase("Apply", [
+      { kind: "cfn-deploy", template: "archive:orders-table.template.json", ...cfnSafetyOptions },
+    ]),
+    phase(
+      "Verify",
+      [
+        { kind: "wait-for-stack", stack: "orders-table" },
+        {
+          kind: "run-migration",
+          script: "archive:migrations/backfill-gsi.sql",
+          // A GSI backfill has no clean inverse: once items are re-projected
+          // onto the new index, "rolling back" the migration would mean a
+          // second migration to undo it, not a mechanical compensation the
+          // capability could run automatically — see COMP003
+          // (lint-rules/composition.mdx) for the opt-out convention.
+          noRollback: "GSI backfill is forward-only; undoing it needs a second, hand-written migration, not automatic compensation",
+        },
+      ],
+      { parallel: true },
+    ),
+  ],
+};

package/src/components/pilots/jar-emr.pilot.ts

@@ -0,0 +1,69 @@
+/**
+ * Pilot pair: JAR producer -> EMR consumer, cross-component artifact outputs
+ * (#561, epic #551).
+ *
+ * This is the epic's worked example for cross-component wiring (#551
+ * §"Cross-component outputs", docs/components/composition-and-wiring.mdx
+ * §"Cross-component outputs"): a **producer-library** component
+ * (`jar-lib`) that only builds and publishes an artifact — no apply, no
+ * service — paired with an **infra** consumer (`emr-job`) that submits an
+ * EMR job run against the producer's published S3 URI.
+ *
+ * The wiring itself needs no new machinery: `dependsOn: ["jar-lib"]` orders
+ * the producer first (`resolveComponentGraph`, ../driver.ts), and
+ * `"@jar-lib.publish.uri"` is the same `@<component>.publish.uri|digest|key`
+ * reference form `resolveWiring` (../driver.ts) already resolves generically
+ * from `componentOutputs`, which `runComponentDeploy` already populates from
+ * any step whose output carries `uri`/`digest`/`key` (`findPublishOutput`) —
+ * both landed with #556/#560 and are exercised by ../driver.test.ts's
+ * "wires a cross-component artifact reference" case. What #561 actually adds
+ * is: this pair authored as real typed `Component`s (rather than only the
+ * hand-written JSON fixtures), and a real `emr-start-job-run`/`wait-job`
+ * capability implementation (../verbs/job-submission.ts,
+ * ../verbs/wait-verify.ts) so the pair runs to completion against a mocked
+ * `CloudExecutor` instead of throwing `CapabilityNotImplementedError`.
+ *
+ * The JSON projections of these two components are authoritative at
+ * ../__fixtures__/jar-lib-producer.json and
+ * ../__fixtures__/emr-job-consumer.json (pre-existing, from #560) — this
+ * module is the real typed `Component` authoring form that composes to those
+ * same documents; see ./pilots.test.ts, which asserts the two never diverge.
+ */
+
+import type { Component } from "../component";
+import { phase } from "../component";
+
+/** Producer: a JAR built from a Maven project, published to S3. Publish-only deploy — no apply phase at all, the defining shape of the `producer-library` archetype. */
+export const jarLib: Component = {
+  name: "jar-lib",
+  archetype: "producer-library",
+  dependsOn: [],
+  build: { kind: "jvm-build", context: ".", into: "archive" },
+  deploy: [
+    // → @jar-lib.publish.uri / @jar-lib.publish.digest, resolved by the graph
+    // for any downstream consumer — never known by this component itself.
+    phase("Publish", [{ kind: "publish-artifact", from: "archive", to: "$env.s3" }]),
+  ],
+};
+
+/** Consumer: an EMR job run reading the producer's published JAR by S3 URI. `dependsOn: ["jar-lib"]` orders the producer first; the graph resolves the reference into the Submit step. */
+export const emrJob: Component = {
+  name: "emr-job",
+  archetype: "infra",
+  dependsOn: ["jar-lib"],
+  deploy: [
+    phase("Submit", [
+      {
+        kind: "emr-start-job-run",
+        jar: "@jar-lib.publish.uri",
+        args: ["--input", "$env.inputPath", "--output", "$env.outputPath"],
+        // A submitted EMR job run has no automatic "undo": stopping a
+        // running/completed job is not the same as reverting whatever it
+        // already wrote, so compensation is a human/runbook decision, not a
+        // mechanical capability rollback — see COMP003 (lint-rules/composition.mdx).
+        noRollback: "a submitted job run has no automatic undo; cancelling it does not revert data it already wrote",
+      },
+    ]),
+    phase("Verify", [{ kind: "wait-job", runId: "@Submit.runId" }]),
+  ],
+};