@intentius/chant 0.13.1 → 0.15.0

package/src/components/presets/ecs-fargate.ts

@@ -0,0 +1,103 @@
+/**
+ * Preset: `EcsFargateComponent` (#566, epic #551 §"6. Presets (Level 2 reuse)").
+ *
+ * The named-composition builder for the ALB/ECS shape
+ * (`../pilots/alb-ecs.pilot.ts`): `docker-build` -> `publish-image` ->
+ * `cfn-deploy` (importing a shared ALB's cross-stack outputs) ->
+ * `ecs-update-service` -> `wait-steady-state` + `health-gate`, with the same
+ * component-declared `rollback-previous` compensation phase the pilot uses
+ * (no native rollback for an already-running service swap — see
+ * ../pilots/alb-ecs.pilot.ts's docstring).
+ *
+ * This is Level 2 reuse over Level 1 raw capabilities: a component that looks
+ * like this composes `EcsFargateComponent({ ... })` directly; the odd case
+ * that needs something extra starts from the same shape and drops to raw
+ * `phase()`/capability `Step`s where it is special (see
+ * docs/components/capabilities.mdx#presets--reuse-without-a-closed-set) —
+ * `./ecs-fargate.test.ts` demonstrates exactly that by re-deriving
+ * `alb-ecs.pilot.ts`'s `searchService` component from this preset and
+ * asserting the two project to the identical JSON contract.
+ */
+
+import type { Component, Wiring } from "../component";
+import { phase, stackOutput } from "../component";
+
+export interface EcsFargateComponentConfig {
+  /** Component/service name (kebab-case) — becomes both the component's `name` and the ECS service name unless `service` overrides it. */
+  name: string;
+  /** ECS service name. Default: `name`. */
+  service?: string;
+  /** Docker build context. Default: ".". */
+  context?: string;
+  /** Path to the built CloudFormation template inside the archive. Default: `archive:<name>.template.json`. */
+  template?: string;
+  /** Health check path for the post-deploy `health-gate`. */
+  healthPath: string;
+  /** Other components that must complete first, beyond the shared-ALB stack (if any). */
+  dependsOn?: string[];
+  /**
+   * Shared ALB stack this service imports `ListenerArn`/`ClusterArn`/`Subnets`
+   * from, via cross-stack `stackOutput()` wiring — the same axis
+   * `alb-ecs.pilot.ts` exercises. Omit for a service with its own
+   * self-contained stack (no shared-ALB import; `cfn-deploy` receives no
+   * `inputs`).
+   */
+  sharedAlbStack?: string;
+  /** Additional/override CloudFormation template inputs, merged with (and taking precedence over) the shared-ALB outputs. */
+  extraInputs?: Record<string, Wiring>;
+  /** ECS cluster reference passed to `ecs-update-service`. Default: `"$env.cluster"`. */
+  cluster?: Wiring;
+  /** Destination registry `publish-image` promotes to. Default: `"$env.registry"`. */
+  registry?: Wiring;
+}
+
+/**
+ * Expand an ECS/Fargate service behind an ALB to its standard
+ * Publish/Apply/Verify composition — the 80% shape `alb-ecs.pilot.ts` is the
+ * hand-composed reference for. Returns a full `Component`; a caller that
+ * needs one extra step (an additional Apply capability, a different Verify
+ * shape) spreads the result and edits `deploy`/`rollback` directly — the
+ * preset is a starting composition, not a closed strategy object.
+ */
+export function EcsFargateComponent(config: EcsFargateComponentConfig): Component {
+  const service = config.service ?? config.name;
+  const template = config.template ?? `archive:${config.name}.template.json`;
+  const cluster = config.cluster ?? "$env.cluster";
+  const registry = config.registry ?? "$env.registry";
+
+  const sharedAlbOutputs = config.sharedAlbStack
+    ? {
+        listenerArn: stackOutput(config.sharedAlbStack, "ListenerArn"),
+        clusterArn: stackOutput(config.sharedAlbStack, "ClusterArn"),
+        subnets: stackOutput(config.sharedAlbStack, "Subnets"),
+      }
+    : undefined;
+  const inputs =
+    sharedAlbOutputs || config.extraInputs ? { ...sharedAlbOutputs, ...config.extraInputs } : undefined;
+
+  const dependsOn = [...(config.sharedAlbStack ? [config.sharedAlbStack] : []), ...(config.dependsOn ?? [])];
+
+  return {
+    name: config.name,
+    archetype: "service",
+    dependsOn,
+    build: { kind: "docker-build", context: config.context ?? ".", into: "archive" },
+    deploy: [
+      phase("Publish", [{ kind: "publish-image", from: "archive", to: registry }]),
+      phase("Apply", [
+        {
+          kind: "cfn-deploy",
+          template,
+          imageRef: "@Publish.digest",
+          ...(inputs ? { inputs } : {}),
+        },
+        { kind: "ecs-update-service", cluster, service },
+      ]),
+      phase("Verify", [
+        { kind: "wait-steady-state", service },
+        { kind: "health-gate", path: config.healthPath },
+      ]),
+    ],
+    rollback: [phase("Rollback", [{ kind: "rollback-previous", service, cluster }])],
+  };
+}

package/src/components/presets/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Preset library (#566, epic #551 §"6. Presets (Level 2 reuse)") — named
+ * composition builders for the common component shapes. Each preset expands
+ * to a full, valid `Component` (../component.ts): the same typed authoring
+ * form and JSON contract every hand-composed component projects to, so a
+ * preset-based component and a hand-composed one are indistinguishable to
+ * `projectToJson`, schema validation, lint, and the driver.
+ *
+ * This is Level 2 reuse over Level 1 raw capabilities
+ * (docs/components/capabilities.mdx#presets--reuse-without-a-closed-set): a
+ * component that matches one of these shapes calls the preset directly; the
+ * odd one that needs something extra spreads the returned `Component` and
+ * edits `deploy`/`rollback` where it is special. Presets remove composition
+ * copy-paste (the COMP007 lint hint) without creating a closed strategy set —
+ * see ./ecs-fargate.test.ts, ./lambda.test.ts, and
+ * ./single-host-compose.test.ts, each of which re-derives an existing
+ * hand-composed pilot/fixture from its preset and asserts the two project to
+ * the identical JSON contract.
+ *
+ * Deliberately not exhaustive: three presets covering the three archetypes'
+ * most common shapes (a load-balanced container service, a container-image
+ * Lambda function, and a registry-less single-host compose deploy), per
+ * #566's explicit scope ("start with the common shapes; an exhaustive
+ * catalog is out of scope").
+ */
+
+export { EcsFargateComponent, type EcsFargateComponentConfig } from "./ecs-fargate";
+export { LambdaComponent, type LambdaComponentConfig } from "./lambda";
+export {
+  SingleHostComposeComponent,
+  type SingleHostComposeComponentConfig,
+} from "./single-host-compose";

package/src/components/presets/lambda.test.ts

@@ -0,0 +1,35 @@
+/**
+ * `LambdaComponent` (#566): schema validity, and equivalence with the
+ * hand-composed `lambda.pilot.ts` reference component.
+ */
+
+import { describe, expect, it } from "vitest";
+import Ajv2020 from "ajv/dist/2020";
+import componentSchema from "../component.schema.json";
+import { projectToJson } from "../component";
+import { imageProcessor } from "../pilots/lambda.pilot";
+import { LambdaComponent } from "./lambda";
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(componentSchema);
+
+describe("LambdaComponent preset", () => {
+  it("expands to a component that projects to schema-valid JSON", () => {
+    const component = LambdaComponent({ name: "image-processor-lambda", functionName: "image-processor" });
+    const projected = projectToJson(component);
+    const valid = validate(projected);
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+  });
+
+  it("re-derives lambda.pilot.ts's hand-composed imageProcessor component byte-for-byte (as data)", () => {
+    const fromPreset = LambdaComponent({ name: "image-processor-lambda", functionName: "image-processor" });
+    expect(projectToJson(fromPreset)).toEqual(projectToJson(imageProcessor));
+  });
+
+  it("defaults functionName to the component name when omitted", () => {
+    const component = LambdaComponent({ name: "thumbnailer" });
+    const applyStep = component.deploy.find((p) => p.phase === "Apply")!.steps[0] as unknown as { functionName: string };
+    expect(applyStep.functionName).toBe("thumbnailer");
+  });
+});

package/src/components/presets/lambda.ts

@@ -0,0 +1,53 @@
+/**
+ * Preset: `LambdaComponent` (#566, epic #551 §"6. Presets (Level 2 reuse)").
+ *
+ * The named-composition builder for the container-image Lambda shape
+ * (`../pilots/lambda.pilot.ts`): `docker-build` -> `publish-image` ->
+ * `lambda-deploy` -> `health-gate` against the function's alias. Distinct
+ * from `EcsFargateComponent`'s apply family on purpose — no CloudFormation
+ * stack in Apply at all, matching the pilot's documented "first pilot whose
+ * Apply phase contains no cfn-deploy" shape.
+ */
+
+import type { Component } from "../component";
+import { phase } from "../component";
+
+export interface LambdaComponentConfig {
+  /** Component name (kebab-case) — becomes both the component's `name` and, by default, the Lambda function name. */
+  name: string;
+  /** Lambda function name. Default: `name`. */
+  functionName?: string;
+  /** Docker build context. Default: ".". */
+  context?: string;
+  /** Alias to repoint at the new version after publish. Default: "live". */
+  alias?: string;
+  /** Destination registry `publish-image` promotes to. Default: `"$env.registry"`. */
+  registry?: string;
+  /** Other components that must complete first. */
+  dependsOn?: string[];
+}
+
+/**
+ * Expand a container-image AWS Lambda function to its standard
+ * Publish/Apply/Verify composition — the reference shape
+ * `lambda.pilot.ts` hand-composes. Reuses `docker-build`/`publish-image`
+ * unchanged from `EcsFargateComponent`'s build axis (build + promote-by-digest
+ * is identical for a container-image Lambda); only the apply/verify shape
+ * differs.
+ */
+export function LambdaComponent(config: LambdaComponentConfig): Component {
+  const functionName = config.functionName ?? config.name;
+  const alias = config.alias ?? "live";
+
+  return {
+    name: config.name,
+    archetype: "service",
+    dependsOn: config.dependsOn ?? [],
+    build: { kind: "docker-build", context: config.context ?? ".", into: "archive" },
+    deploy: [
+      phase("Publish", [{ kind: "publish-image", from: "archive", to: config.registry ?? "$env.registry" }]),
+      phase("Apply", [{ kind: "lambda-deploy", functionName, codeRef: "@Publish.uri", alias }]),
+      phase("Verify", [{ kind: "health-gate", path: "@Apply.functionArn" }]),
+    ],
+  };
+}

package/src/components/presets/single-host-compose.test.ts

@@ -0,0 +1,65 @@
+/**
+ * `SingleHostComposeComponent` (#566): schema validity, and equivalence with
+ * the hand-written `__fixtures__/single-host-compose.json` reference
+ * document — the fixture is the authoritative hand-composed form for this
+ * shape (no `*.pilot.ts` TypeScript authoring form exists for it yet, unlike
+ * the ALB/ECS and Lambda shapes), matching how `../pilots/pilots.test.ts`
+ * compares a pilot's projection against its `__fixtures__/*.json` sibling.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import Ajv2020 from "ajv/dist/2020";
+import componentSchema from "../component.schema.json";
+import { projectToJson } from "../component";
+import { SingleHostComposeComponent } from "./single-host-compose";
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(componentSchema);
+
+function loadFixture(name: string): unknown {
+  return JSON.parse(readFileSync(join(import.meta.dirname, "..", "__fixtures__", name), "utf-8"));
+}
+
+describe("SingleHostComposeComponent preset", () => {
+  it("expands to a component that projects to schema-valid JSON", () => {
+    const component = SingleHostComposeComponent({
+      name: "monitoring-host",
+      healthPath: "/-/healthy",
+      healthPort: 9090,
+    });
+    const projected = projectToJson(component);
+    const valid = validate(projected);
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+  });
+
+  it("re-derives the hand-written single-host-compose.json fixture (as data, ignoring document-level $schema/contractVersion provenance fields)", () => {
+    const fromPreset = SingleHostComposeComponent({
+      name: "monitoring-host",
+      // The fixture's on-host path is "/opt/monitoring/..." rather than this
+      // preset's "<name>"-derived default ("/opt/monitoring-host/...") — pass
+      // it explicitly to match the pre-existing hand-written fixture exactly.
+      hostComposePath: "/opt/monitoring/compose.yaml",
+      healthPath: "/-/healthy",
+      healthPort: 9090,
+    });
+
+    const fixture = loadFixture("single-host-compose.json") as Record<string, unknown>;
+    const { $schema: _s, contractVersion: _v, ...fixtureContent } = fixture;
+    expect(projectToJson(fromPreset)).toEqual(fixtureContent);
+  });
+
+  it("defaults host and the on-host compose path when omitted", () => {
+    const component = SingleHostComposeComponent({
+      name: "monitoring-host",
+      healthPath: "/-/healthy",
+      healthPort: 9090,
+    });
+    const applyPhase = component.deploy.find((p) => p.phase === "Apply")!;
+    const copyStep = applyPhase.steps[0] as unknown as { host: string; to: string };
+    expect(copyStep.host).toBe("$env.host");
+    expect(copyStep.to).toBe("/opt/monitoring-host/compose.yaml");
+  });
+});

package/src/components/presets/single-host-compose.ts

@@ -0,0 +1,64 @@
+/**
+ * Preset: `SingleHostComposeComponent` (#566, epic #551 §"6. Presets (Level 2
+ * reuse)").
+ *
+ * The named-composition builder for the registry-less single-host Docker
+ * Compose shape (`../__fixtures__/single-host-compose.json`): `docker-build`
+ * -> `load-image-on-host` (registry-free promotion, see
+ * ../verbs/publish.ts's `load-image-on-host` docstring) -> `copy-to-host` the
+ * compose file -> `remote-exec` a `docker compose up -d` -> `wait-endpoint`
+ * against the service's health path. This is the N=1 case of the fan-out
+ * shape `neo4j-fanout.pilot.ts` composes by hand at N=3 — single-host compose
+ * and a host fleet are the same composition shape at different N (see
+ * docs/components/composition-and-wiring.mdx#fan-out-is-composition-not-orchestrator-knowledge).
+ */
+
+import type { Component } from "../component";
+import { phase } from "../component";
+
+export interface SingleHostComposeComponentConfig {
+  /** Component name (kebab-case). */
+  name: string;
+  /** Docker build context. Default: ".". */
+  context?: string;
+  /** Path to the compose file inside the archive. Default: "archive:compose.yaml". */
+  composeFile?: string;
+  /** Destination path for the compose file on the host. Default: `/opt/<name>/compose.yaml`. */
+  hostComposePath?: string;
+  /** Target host (SSM instance id, hostname, or host group). Default: `"$env.host"`. */
+  host?: string;
+  /** Health check path polled after `docker compose up -d`. */
+  healthPath: string;
+  /** Port the health check listens on. */
+  healthPort: number;
+  /** Other components that must complete first. */
+  dependsOn?: string[];
+}
+
+/**
+ * Expand a single-host Docker Compose deploy to its standard
+ * Publish/Apply/Verify composition. No registry ever in the path: the built
+ * image tarball is copied straight onto the host and `docker load`ed there
+ * (`load-image-on-host`), the compose file follows the same way, and
+ * `docker compose up -d` runs via `remote-exec` — the registry-less backend
+ * axis documented in docs/components/build-archive.mdx.
+ */
+export function SingleHostComposeComponent(config: SingleHostComposeComponentConfig): Component {
+  const host = config.host ?? "$env.host";
+  const hostComposePath = config.hostComposePath ?? `/opt/${config.name}/compose.yaml`;
+
+  return {
+    name: config.name,
+    archetype: "service",
+    dependsOn: config.dependsOn ?? [],
+    build: { kind: "docker-build", context: config.context ?? ".", into: "archive" },
+    deploy: [
+      phase("Publish", [{ kind: "load-image-on-host", from: "archive", host }]),
+      phase("Apply", [
+        { kind: "copy-to-host", from: config.composeFile ?? "archive:compose.yaml", to: hostComposePath, host },
+        { kind: "remote-exec", host, command: `docker compose -f ${hostComposePath} up -d` },
+      ]),
+      phase("Verify", [{ kind: "wait-endpoint", host, path: config.healthPath, port: config.healthPort }]),
+    ],
+  };
+}

package/src/components/registry.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect } from "vitest";
+import { createCapabilityRegistry, STARTER_VERB_FAMILIES } from "./registry";
+import { CapabilityNotImplementedError } from "./capability";
+import { stubCapability } from "./verbs/stub";
+
+const ALL_STARTER_KINDS = Object.values(STARTER_VERB_FAMILIES).flat();
+
+describe("createCapabilityRegistry", () => {
+  test("resolves every starter verb by kind", () => {
+    const registry = createCapabilityRegistry();
+    for (const kind of ALL_STARTER_KINDS) {
+      expect(registry.has(kind)).toBe(true);
+      const capability = registry.resolve(kind);
+      expect(capability.kind).toBe(kind);
+      expect(typeof capability.run).toBe("function");
+    }
+  });
+
+  test("kinds() lists exactly the starter set, sorted", () => {
+    const registry = createCapabilityRegistry();
+    expect(registry.kinds()).toEqual([...ALL_STARTER_KINDS].sort());
+  });
+
+  test("throws a friendly error for an unregistered kind", () => {
+    const registry = createCapabilityRegistry();
+    expect(() => registry.resolve("nonexistent-verb")).toThrow(
+      /no capability registered for kind "nonexistent-verb"/,
+    );
+  });
+
+  // The starter set no longer carries any cloud leaf — `cfn-deploy` and the
+  // rest live in the aws lexicon now — so `cfn-deploy` is genuinely unknown to
+  // a core-only registry, resolving only once the aws capability plugin is
+  // loaded (see ./capability-plugin-loader.ts's lexicon path).
+  test("a cloud-leaf kind (cfn-deploy) is not in the core starter set", () => {
+    const registry = createCapabilityRegistry();
+    expect(registry.has("cfn-deploy")).toBe(false);
+    expect(() => registry.resolve("cfn-deploy")).toThrow(/no capability registered for kind "cfn-deploy"/);
+  });
+
+  test("registering a duplicate kind throws", () => {
+    const registry = createCapabilityRegistry();
+    expect(() =>
+      registry.register({
+        kind: "docker-build",
+        run: async () => ({ archivePath: "", digest: "" }),
+      }),
+    ).toThrow('capability "docker-build" is already registered');
+  });
+
+  // No starter verb is a stub any more (all implemented), but the stub
+  // *mechanism* (./verbs/stub.ts) stays for third-party plugins / future verbs:
+  // a stub's run()/rollback() reject with CapabilityNotImplementedError, and
+  // the driver surfaces that as a failed step rather than crashing.
+  test("stubCapability run()/rollback() reject with CapabilityNotImplementedError, naming the kind", async () => {
+    const stub = stubCapability("some-future-verb", { rollback: true });
+    await expect(stub.run({ env: "dev", component: "test" }, {} as never)).rejects.toBeInstanceOf(
+      CapabilityNotImplementedError,
+    );
+    await expect(stub.run({ env: "dev", component: "test" }, {} as never)).rejects.toThrow(
+      'capability "some-future-verb" is not implemented',
+    );
+    expect(typeof stub.rollback).toBe("function");
+    await expect(stub.rollback?.({ env: "dev", component: "test" }, {} as never)).rejects.toBeInstanceOf(
+      CapabilityNotImplementedError,
+    );
+  });
+
+  test("capabilities without declared rollback have none", () => {
+    const registry = createCapabilityRegistry();
+    expect(registry.resolve("zip-package").rollback).toBeUndefined();
+  });
+
+  // The agnostic starter verbs are all real implementations — `run` is a real
+  // function, not the stub thrower.
+  test("agnostic starter verbs are real implementations, not stubs", () => {
+    const registry = createCapabilityRegistry();
+    for (const kind of [
+      "docker-build",
+      "zip-package",
+      "jvm-build",
+      "generate-sbom",
+      "sign",
+      "verify",
+      "vuln-gate",
+      "wait-cluster-healthy",
+      "wait-endpoint",
+      "health-gate",
+    ]) {
+      const capability = registry.resolve(kind);
+      expect(typeof capability.run).toBe("function");
+    }
+  });
+
+  test("family table lists exactly the agnostic starter families (cloud leaves moved to lexicons)", () => {
+    expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
+      ["build", "escapeHatch", "sbom", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+    );
+  });
+
+  // #606: `generate-sbom` is a real implementation (over the injectable,
+  // artifact-type-keyed SbomGenerator — see ./verbs/sbom-generator.ts),
+  // defaulted to the hermetic lockfile-backed generator for dir/zip/jar
+  // artifacts (#630) — `forImage` still needs a real scanner backend wired
+  // in explicitly (#610).
+  test("#606 generate-sbom is registered and callable (default backend is the hermetic lockfile generator, #630)", () => {
+    const registry = createCapabilityRegistry();
+    const capability = registry.resolve("generate-sbom");
+    expect(typeof capability.run).toBe("function");
+    expect(capability.rollback).toBeUndefined();
+  });
+});

package/src/components/registry.ts

@@ -0,0 +1,37 @@
+/**
+ * The starter capability registry — one `CapabilityRegistry` pre-seeded with
+ * every verb in the starter set (epic #551, issue #554). All stubs; no cloud
+ * calls except for the #557/#558 AWS leaves (real implementations).
+ *
+ * Phase 2 (#559) promotes this convention to a first-class plugin contract
+ * (./capability-plugin.ts): the starter verb set now ships as
+ * `starterCapabilityPlugin` (./starter-plugin.ts), and `createCapabilityRegistry`
+ * below builds its registry from that plugin's `capabilities()` instead of
+ * registering each verb inline. This is a pure refactor — same kinds, same
+ * capability instances, same registration order — so every existing caller
+ * (the driver, the pilots, ./registry.test.ts) is unaffected. New code
+ * should prefer `buildCapabilityRegistry` (./capability-plugin-loader.ts),
+ * which additionally supports loading third-party capability plugins on top
+ * of this same starter set, the way lexicons are discovered today.
+ */
+
+import { CapabilityRegistry } from "./capability";
+import { starterCapabilityPlugin, STARTER_VERB_FAMILIES } from "./starter-plugin";
+
+/** Build a fresh `CapabilityRegistry` containing every starter-set verb stub. */
+export function createCapabilityRegistry(): CapabilityRegistry {
+  const registry = new CapabilityRegistry();
+  for (const capability of starterCapabilityPlugin.capabilities()) {
+    registry.register(capability);
+  }
+  return registry;
+}
+
+/**
+ * Every `kind` in the starter verb set, grouped by family — useful for tests
+ * and docs generation. Re-exported here (source of truth moved to
+ * ./starter-plugin.ts to avoid a module cycle with `starterCapabilityPlugin`)
+ * so every existing import of `STARTER_VERB_FAMILIES` from this module keeps
+ * working unchanged.
+ */
+export { STARTER_VERB_FAMILIES };

package/src/components/starter-plugin.ts

@@ -0,0 +1,105 @@
+/**
+ * The starter verb set (epic #551, #554/#557/#558), wrapped as a
+ * `CapabilityPlugin` (#559) — the built-in, always-loaded plugin that
+ * carries every Phase 1 capability forward under the Phase 2 plugin
+ * contract with **no behavior change**.
+ *
+ * Migration path from Phase 1 to Phase 2: Phase 1 (`createCapabilityRegistry`,
+ * ./registry.ts) constructed a `CapabilityRegistry` by registering each
+ * starter verb directly. Phase 2 introduces `CapabilityPlugin` as the
+ * discoverable, typed package contract (./capability-plugin.ts) that
+ * mirrors how lexicons are packaged (../lexicon.ts). Rather than rewrite the
+ * starter verbs, this module packages the *exact same* verb list as one
+ * `CapabilityPlugin` named "starter" — so:
+ *
+ *  - `createCapabilityRegistry()` (./registry.ts) now builds its registry by
+ *    registering `starterCapabilityPlugin.capabilities()` instead of calling
+ *    `registry.register(...)` once per verb inline. Same kinds, same
+ *    instances, same order, same resulting registry — verified by
+ *    ./registry.test.ts, unchanged.
+ *  - `buildCapabilityRegistry()` (./capability-plugin-loader.ts), the new
+ *    Phase 2 entry point, always loads this plugin first, then layers any
+ *    additional third-party capability plugins on top by `kind`.
+ *  - The driver (./driver.ts) and every pilot (./pilots/*.pilot.ts) consume
+ *    only a `CapabilityRegistry` instance and never construct one directly
+ *    from verb modules, so neither needed to change for this migration —
+ *    the compatibility guarantee #559 asks for.
+ */
+
+import type { Capability } from "./capability";
+import {
+  dockerBuildCapability,
+  zipPackageCapability,
+  jvmBuildCapability,
+  generateSbomCapability,
+  signCapability,
+  attestProvenanceCapability,
+  verifyCapability,
+  scanVulnerabilitiesCapability,
+  vulnGateCapability,
+  waitClusterHealthyCapability,
+  waitEndpointCapability,
+  healthGateCapability,
+  shellCapability,
+} from "./verbs/index";
+import type { CapabilityPlugin } from "./capability-plugin";
+
+/**
+ * Every `kind` in the starter verb set, grouped by family, per epic #551 and
+ * docs/components/capabilities.mdx. Source of truth (moved here from
+ * ./registry.ts in #559 to avoid a module cycle: ./registry.ts's
+ * `createCapabilityRegistry` depends on `starterCapabilityPlugin`, so this
+ * plugin module cannot depend back on ./registry.ts). Re-exported from
+ * ./registry.ts unchanged for existing importers.
+ */
+export const STARTER_VERB_FAMILIES = {
+  build: ["docker-build", "zip-package", "jvm-build"],
+  // `extract-config-bom` parses a synthesized CloudFormation template, so it
+  // moved to the aws lexicon (#684) alongside the other AWS leaves; core's sbom
+  // family keeps only the agnostic, artifact-type-keyed `generate-sbom`.
+  sbom: ["generate-sbom"],
+  supplyChainSecurity: ["sign", "attest-provenance", "verify"],
+  supplyChainPolicy: ["scan-vulnerabilities", "vuln-gate"],
+  // Only the *agnostic* wait/verify verbs are in the starter set; the
+  // cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`) are
+  // contributed by the relevant lexicon (aws) — see docs/components/cloud-boundary.
+  waitVerify: ["wait-cluster-healthy", "wait-endpoint", "health-gate"],
+  escapeHatch: ["shell"],
+} as const;
+
+/**
+ * Every starter-set verb, in the same registration order Phase 1's
+ * `createCapabilityRegistry` used. Listed individually (not as a shared
+ * array literal) for the same reason Phase 1 registered them individually:
+ * each capability's own `In`/`Out` generics must be inferred from its own
+ * type, not widened to a lossy common supertype.
+ */
+function starterCapabilities(): Array<Capability<never, unknown>> {
+  return [
+    dockerBuildCapability,
+    zipPackageCapability,
+    jvmBuildCapability,
+    generateSbomCapability,
+    signCapability,
+    attestProvenanceCapability,
+    verifyCapability,
+    scanVulnerabilitiesCapability,
+    vulnGateCapability,
+    waitClusterHealthyCapability,
+    waitEndpointCapability,
+    healthGateCapability,
+    shellCapability,
+  ] as unknown as Array<Capability<never, unknown>>;
+}
+
+/**
+ * The built-in capability plugin carrying the entire Phase 1 starter verb
+ * set forward under the Phase 2 contract. Always loaded first by
+ * `buildCapabilityRegistry` (./capability-plugin-loader.ts).
+ */
+export const starterCapabilityPlugin: CapabilityPlugin = {
+  name: "starter",
+  version: "1.0.0",
+  capabilities: starterCapabilities,
+  families: () => STARTER_VERB_FAMILIES,
+};

package/src/components/temporal-codegen-loader.ts

@@ -0,0 +1,41 @@
+/**
+ * Dynamic loader for the durable component → Temporal codegen (#589, epic
+ * #551 §5/§8). The actual `serializeComponent` generator lives in
+ * `@intentius/chant-lexicon-temporal` (`src/component-op/serializer.ts`),
+ * mirroring `Temporal::Op` codegen — core never statically depends on the
+ * Temporal lexicon, the same boundary `../op/activity-registry.ts`'s
+ * `loadActivities`/`loadProfiles` already keep for Op activities.
+ */
+
+import type { DriverComponent } from "./driver";
+
+/** Target environment (and env-config) baked into the generated workflow at compile time — see `serializeComponent`'s docstring in the Temporal lexicon for why this can't be resolved at workflow-run time instead. */
+export interface ComponentTemporalCodegenOptions {
+  env?: string;
+  vars?: Record<string, unknown>;
+}
+
+export interface ComponentTemporalCodegen {
+  /** Serialize one component into `{ "components/<name>/workflow.ts": "...", ... }`. */
+  serializeComponent(component: DriverComponent, options?: ComponentTemporalCodegenOptions): Record<string, string>;
+  /** Deterministic workflow function name for a component (mirrors the generated `export async function <fn>()`). */
+  componentWorkflowFnName(componentName: string): string;
+}
+
+/**
+ * Dynamically import the Temporal lexicon's component codegen. Throws a
+ * friendly error if the lexicon is not installed — the durable component
+ * path needs the generator even though discovery/local execution never do.
+ */
+export async function loadComponentTemporalCodegen(): Promise<ComponentTemporalCodegen> {
+  try {
+    // Variable specifier so tsc does not statically resolve the optional dep.
+    const spec = "@intentius/chant-lexicon-temporal/component-op/serializer";
+    return (await import(spec)) as unknown as ComponentTemporalCodegen;
+  } catch (err) {
+    throw new Error(
+      "no durable component codegen available — install `@intentius/chant-lexicon-temporal` " +
+        `to run components with --temporal (${err instanceof Error ? err.message : String(err)})`,
+    );
+  }
+}