@intentius/chant 0.13.0 → 0.15.0

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

@@ -0,0 +1,55 @@
+/**
+ * Pilot: image-processor Lambda (#558, epic #551).
+ *
+ * The fourth, deliberately different component #558 asks for, added to prove
+ * the sprawl metric holds beyond the original three pilots (#555): a
+ * container-image AWS Lambda function. `service` archetype, same as ALB/ECS,
+ * but a genuinely different shape on two axes at once:
+ *
+ *  - **apply target**: no CloudFormation stack at all — `lambda-deploy`
+ *    updates a function's code directly (`UpdateFunctionCode` +
+ *    `PublishVersion` + `UpdateAlias`), never a `cfn-deploy` changeset. Every
+ *    prior pilot's apply step was `cfn-deploy`; this is the first pilot whose
+ *    Apply phase contains none.
+ *  - **verify shape**: a single `wait-for-stack`-free health check
+ *    (`health-gate` against the function's alias URL) rather than an ECS
+ *    steady-state poll or a Neo4j quorum probe.
+ *
+ * Reuses `docker-build` + `publish-image` unchanged from the ALB/ECS pilot's
+ * axis (build + promote-by-digest is identical for a container-image Lambda:
+ * https://docs.aws.amazon.com/lambda/latest/dg/images-create.html) — the
+ * `imageRef`/`codeRef` wiring (`@Publish.digest` / `@Publish.uri`) is the same
+ * `@Phase.field` prior-step reference form every pilot already uses. The only
+ * capability this component needed that didn't already exist is `lambda-deploy`
+ * (../verbs/apply.ts) — one new capability, exactly the sprawl metric's bound
+ * for "genuinely novel"; see ../SPRAWL-VALIDATION.md for the full accounting.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/lambda-image-processor.json — 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";
+
+export const imageProcessor: Component = {
+  name: "image-processor-lambda",
+  archetype: "service",
+  dependsOn: [],
+  build: { kind: "docker-build", context: ".", into: "archive" },
+  deploy: [
+    phase("Publish", [{ kind: "publish-image", from: "archive", to: "$env.registry" }]),
+    phase("Apply", [
+      { kind: "lambda-deploy", functionName: "image-processor", codeRef: "@Publish.uri", alias: "live" },
+    ]),
+    phase("Verify", [{ kind: "health-gate", path: "@Apply.functionArn" }]),
+  ],
+  // No native rollback on lambda-deploy for an alias already repointed at a bad
+  // version — same "no automatic capability rollback" story as the ALB/ECS
+  // pilot's ecs-update-service, except here the capability itself supplies the
+  // best-effort restore (see createLambdaDeployCapability's rollback in
+  // ../verbs/apply.ts) rather than the component declaring its own phase, so
+  // no component-level `rollback` field is needed here.
+};

package/src/components/pilots/neo4j-fanout.pilot.ts

@@ -0,0 +1,92 @@
+/**
+ * Pilot: Neo4j per-instance fan-out cluster (#555, epic #551).
+ *
+ * Exercises the fan-out axis: one component composing N per-instance
+ * mini-compositions (`cfn-deploy` + `code-deploy` + a health wait), seeded
+ * first, then rolled through the remaining instances one at a time behind a
+ * `wait-cluster-healthy` gate. See composition-and-wiring.mdx#fan-out-is-composition-not-orchestrator-knowledge.
+ *
+ * The JSON projection of this pilot is authoritative at
+ * ../__fixtures__/neo4j-fanout.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, Phase } from "../component";
+import { gate, phase } from "../component";
+
+/** One Neo4j instance's mini-composition: provision, code-deploy the build, then wait for cluster health. */
+interface Neo4jInstanceConfig {
+  /** Cluster-relative instance index (0 = seed). */
+  index: number;
+  /** Phase display name. */
+  label: string;
+  /** Availability-zone-qualified CloudFormation template for this instance. */
+  template: string;
+  /**
+   * Health condition to satisfy before moving to the next instance. The seed
+   * instance only needs itself up (`size: 1`); every subsequent instance
+   * requires quorum across whatever is live so far.
+   */
+  health: { size: number } | { quorum: true };
+  /** Optional human gate placed before this instance's steps (rolling instances only, never the seed). */
+  approval?: { signalName: string; description: string; timeout: string };
+}
+
+const SEED: Neo4jInstanceConfig = {
+  index: 0,
+  label: "Seed",
+  template: "archive:neo4j-az0-0.template.json",
+  health: { size: 1 },
+};
+
+/**
+ * Followers roll one at a time after the seed is healthy. Node 1 carries an
+ * explicit approval gate — composed the same way any other step is, never as
+ * driver knowledge — so a human confirms the seed before the cluster starts
+ * fanning out further; later nodes roll unattended once that first rollout is
+ * trusted.
+ */
+const FOLLOWERS: Neo4jInstanceConfig[] = [
+  {
+    index: 1,
+    label: "Node 1",
+    template: "archive:neo4j-1.template.json",
+    health: { quorum: true },
+    approval: {
+      signalName: "approve-neo4j-node-1",
+      description: "Confirm the seed node is healthy before rolling to node 1",
+      timeout: "24h",
+    },
+  },
+  {
+    index: 2,
+    label: "Node 2",
+    template: "archive:neo4j-2.template.json",
+    health: { quorum: true },
+  },
+];
+
+/** Build one instance's mini-composition phase — the unit that repeats N times for an N-node cluster. */
+function instancePhase(instance: Neo4jInstanceConfig): Phase {
+  const steps = [
+    ...(instance.approval ? [gate(instance.approval.signalName, instance.approval)] : []),
+    { kind: "cfn-deploy", template: instance.template },
+    { kind: "code-deploy", instance: instance.index, revision: "@Seed.templateUri" },
+    { kind: "wait-cluster-healthy", ...instance.health },
+  ];
+  return phase(instance.label, steps);
+}
+
+export const neo4jCluster: Component = {
+  name: "neo4j-cluster",
+  archetype: "infra",
+  dependsOn: [],
+  deploy: [
+    instancePhase(SEED),
+    // Array.map over instance configs — the fan-out is authored here, in the
+    // composition, never known by the orchestrator (composition-and-wiring.mdx).
+    ...FOLLOWERS.map(instancePhase),
+  ],
+};

package/src/components/pilots/pilots-lint-clean.test.ts

@@ -0,0 +1,78 @@
+/**
+ * The real pilots must lint clean under the COMP* composition rules (#562,
+ * epic #551's acceptance criteria: "Ensure the four real pilots lint CLEAN
+ * (they are valid compositions)"). #561 added a fifth/sixth component (the
+ * jar-lib producer / emr-job consumer pair) after this issue was filed;
+ * included here too since it now lives alongside the original four as real,
+ * non-stub composition.
+ *
+ * Pilots are authored as `*.pilot.ts` (see ../discover.ts's docstring: only
+ * `*.component.ts` is the discovery convention `chant lint`/`chant build`
+ * actually scan), so this test builds a `ComponentCheckContext` directly from
+ * the imported `Component` values — the same objects `./pilots.test.ts`
+ * schema-validates — rather than depending on file-suffix discovery, and runs
+ * every COMP* check against it exactly as `../../lint/component-checks.ts`'s
+ * `runComponentChecks` would over a real discovered project.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { ComponentCheckContext, ComponentCheckEntry } from "../../lint/component-checks";
+import { loadComponentChecks } from "../../lint/rules/comp/index";
+import { searchService } from "./alb-ecs.pilot";
+import { ordersTable } from "./dynamodb.pilot";
+import { neo4jCluster } from "./neo4j-fanout.pilot";
+import { imageProcessor } from "./lambda.pilot";
+import { jarLib, emrJob } from "./jar-emr.pilot";
+import type { Component } from "../component";
+
+const checks = loadComponentChecks();
+
+function contextFor(components: Component[]): ComponentCheckContext {
+  const map = new Map<string, ComponentCheckEntry>();
+  for (const component of components) {
+    map.set(component.name, { component, filePath: `${component.name}.pilot.ts` });
+  }
+  return { components: map };
+}
+
+/** Every check's diagnostics against one context, tagged with the producing check id. */
+function runAll(ctx: ComponentCheckContext) {
+  return checks.flatMap((check) => check.check(ctx));
+}
+
+describe("Real pilots lint clean under COMP* (#562 acceptance criteria)", () => {
+  it("ALB/ECS, DynamoDB, and the jar-lib/emr-job pair produce zero COMP* diagnostics", () => {
+    const ctx = contextFor([searchService, ordersTable, jarLib, emrJob]);
+    const diagnostics = runAll(ctx);
+    expect(diagnostics).toEqual([]);
+  });
+
+  it("the image-processor Lambda pilot (#558's fourth component) produces zero COMP* diagnostics", () => {
+    const ctx = contextFor([imageProcessor]);
+    expect(runAll(ctx)).toEqual([]);
+  });
+
+  it("the Neo4j fan-out pilot produces zero COMP* diagnostics other than the expected COMP004 (gate requires Temporal)", () => {
+    // The Neo4j pilot's Node-1 approval gate is a deliberate design choice
+    // (see neo4j-fanout.pilot.ts's own docstring and
+    // ../driver.ts's DriverGateUnsupportedError / docs/components/
+    // orchestration.mdx's "Temporal is optional" aside) — it is the one real
+    // pilot that genuinely needs the durable backend, so COMP004 firing here
+    // is the *correct*, expected signal, not a defect. A real project would
+    // acknowledge it with `// chant-disable-next-line COMP004 -- <reason>`
+    // once authored as an actual `*.component.ts` file (see
+    // ../../lint/rules/comp/comp004-gate-needs-temporal.ts and the
+    // comp004/pass fixture demonstrating that opt-out end to end).
+    const ctx = contextFor([neo4jCluster]);
+    const diagnostics = runAll(ctx);
+    expect(diagnostics.every((d) => d.checkId === "COMP004")).toBe(true);
+    expect(diagnostics.filter((d) => d.checkId === "COMP004")).toHaveLength(1);
+  });
+
+  it("all six real components together (the full pilot set) produce zero COMP* diagnostics except the one documented Neo4j gate", () => {
+    const ctx = contextFor([searchService, ordersTable, neo4jCluster, imageProcessor, jarLib, emrJob]);
+    const diagnostics = runAll(ctx);
+    const unexpected = diagnostics.filter((d) => !(d.checkId === "COMP004" && d.component === "neo4j-cluster"));
+    expect(unexpected).toEqual([]);
+  });
+});

package/src/components/pilots/pilots.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Validates the pilot components (#555, #558, epic #551) two ways:
+ *
+ * 1. Each pilot's TypeScript authoring form projects to JSON that validates
+ *    against component.schema.json (draft 2020-12, via the same ajv 2020
+ *    setup as ../component-schema.test.ts).
+ * 2. That projection is byte-identical (as data) to the corresponding
+ *    existing fixture under ../__fixtures__/ — so the fixture stays the one
+ *    authoritative JSON projection per pilot rather than a second, divergent
+ *    copy. If a pilot's composition changes, the fixture is the file to
+ *    update; this test catches the two drifting apart.
+ *
+ * Includes the original three pilots (#555 — Neo4j fan-out, DynamoDB sticky
+ * apply, ALB/ECS cross-stack) plus the fourth validation component #558 added
+ * (image-processor-lambda) to prove the sprawl metric holds beyond the
+ * original three; see ../SPRAWL-VALIDATION.md. Also includes the #561
+ * JAR-producer / EMR-consumer pair (../pilots/jar-emr.pilot.ts) — the epic's
+ * worked cross-component artifact output example.
+ */
+
+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 { neo4jCluster } from "./neo4j-fanout.pilot";
+import { ordersTable } from "./dynamodb.pilot";
+import { searchService } from "./alb-ecs.pilot";
+import { imageProcessor } from "./lambda.pilot";
+import { jarLib, emrJob } from "./jar-emr.pilot";
+import { projectToJson } from "./project";
+import type { Component } from "../component";
+
+const FIXTURES_DIR = join(import.meta.dirname, "..", "__fixtures__");
+
+function loadFixture(name: string): unknown {
+  return JSON.parse(readFileSync(join(FIXTURES_DIR, name), "utf-8"));
+}
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(componentSchema);
+
+const pilots: Array<{ name: string; component: Component; fixture: string }> = [
+  { name: "neo4j per-instance fan-out", component: neo4jCluster, fixture: "neo4j-fanout.json" },
+  { name: "DynamoDB sticky apply", component: ordersTable, fixture: "dynamodb-infra.json" },
+  { name: "ALB/ECS target", component: searchService, fixture: "alb-ecs-service.json" },
+  { name: "image-processor Lambda (#558 fourth component)", component: imageProcessor, fixture: "lambda-image-processor.json" },
+  { name: "jar-lib producer (#561 cross-component pair)", component: jarLib, fixture: "jar-lib-producer.json" },
+  { name: "emr-job consumer (#561 cross-component pair)", component: emrJob, fixture: "emr-job-consumer.json" },
+];
+
+describe("Pilot component definitions", () => {
+  it.each(pilots.map((p) => [p.name, p] as const))(
+    "%s: TypeScript authoring form projects to valid JSON",
+    (_name, pilot) => {
+      const projected = projectToJson(pilot.component);
+      const valid = validate(projected);
+      if (!valid) {
+        throw new Error(`${pilot.name} failed schema validation: ${ajv.errorsText(validate.errors)}`);
+      }
+      expect(valid).toBe(true);
+    },
+  );
+
+  it.each(pilots.map((p) => [p.name, p] as const))(
+    "%s: projection matches the authoritative __fixtures__ JSON (no divergent copy)",
+    (_name, pilot) => {
+      const projected = projectToJson(pilot.component);
+      const fixture = loadFixture(pilot.fixture);
+      // The fixture carries $schema/contractVersion metadata the illustrative
+      // authoring form doesn't reproduce (those are document-level
+      // provenance fields, not composition content); strip them from the
+      // fixture side before comparing so this asserts the two never diverge
+      // on the parts that matter — name/archetype/dependsOn/build/deploy/rollback.
+      const { $schema: _s, contractVersion: _v, ...fixtureContent } = fixture as Record<string, unknown>;
+      expect(projected).toEqual(fixtureContent);
+    },
+  );
+
+  it("each pilot exercises its intended epic axis (build presence / archetype / fan-out shape)", () => {
+    // Neo4j: fan-out — more than one instance phase, nested no build (infra).
+    expect(neo4jCluster.archetype).toBe("infra");
+    expect(neo4jCluster.build).toBeUndefined();
+    expect(neo4jCluster.deploy.length).toBeGreaterThan(1);
+
+    // DynamoDB: sticky apply — no build, cfn-deploy carries onReplace/stageGsi.
+    expect(ordersTable.archetype).toBe("infra");
+    expect(ordersTable.build).toBeUndefined();
+    const applyStep = ordersTable.deploy[0]!.steps[0] as { onReplace?: string; stageGsi?: boolean };
+    expect(applyStep.onReplace).toBe("block");
+    expect(applyStep.stageGsi).toBe(true);
+
+    // ALB/ECS: build present, cross-stack wiring present, service archetype.
+    expect(searchService.archetype).toBe("service");
+    expect(searchService.build).toBeDefined();
+    expect(searchService.dependsOn).toContain("shared-alb");
+    const applyPhase = searchService.deploy.find((p) => p.phase === "Apply")!;
+    const cfnStep = applyPhase.steps[0] as { inputs?: Record<string, unknown> };
+    expect(cfnStep.inputs?.listenerArn).toEqual({ stackOutput: { stack: "shared-alb", name: "ListenerArn" } });
+  });
+
+  it("image-processor Lambda (#558): build present, service archetype, apply has no cfn-deploy at all — the fourth component's distinguishing shape", () => {
+    expect(imageProcessor.archetype).toBe("service");
+    expect(imageProcessor.build).toBeDefined();
+    const applyPhase = imageProcessor.deploy.find((p) => p.phase === "Apply")!;
+    expect(applyPhase.steps.map((s) => (s as { kind: string }).kind)).toEqual(["lambda-deploy"]);
+    expect(applyPhase.steps.some((s) => (s as { kind: string }).kind === "cfn-deploy")).toBe(false);
+  });
+
+  it("jar-lib (#561): producer-library archetype, publish-only deploy — build -> publish, no apply phase at all", () => {
+    expect(jarLib.archetype).toBe("producer-library");
+    expect(jarLib.build).toBeDefined();
+    expect(jarLib.deploy).toHaveLength(1);
+    expect(jarLib.deploy[0]!.phase).toBe("Publish");
+    expect(jarLib.deploy[0]!.steps.map((s) => (s as { kind: string }).kind)).toEqual(["publish-artifact"]);
+  });
+
+  it("emr-job (#561): infra archetype, depends on jar-lib, and references the producer's published artifact by @<component>.publish.uri — the cross-component wiring this issue adds", () => {
+    expect(emrJob.archetype).toBe("infra");
+    expect(emrJob.dependsOn).toEqual(["jar-lib"]);
+    const submitPhase = emrJob.deploy.find((p) => p.phase === "Submit")!;
+    const submitStep = submitPhase.steps[0] as { kind: string; jar: string };
+    expect(submitStep.kind).toBe("emr-start-job-run");
+    expect(submitStep.jar).toBe("@jar-lib.publish.uri");
+  });
+});

package/src/components/pilots/project.ts

@@ -0,0 +1,13 @@
+/**
+ * Re-exports the real `projectToJson` (#560, ../component.ts) under the
+ * pilots' original import path. Prior to #560, this module held its own
+ * "intentionally dumb" projection over the stopgap `authoring-shape.ts`
+ * (#555); now that the real typed `Component` authoring form exists, its
+ * `projectToJson` (which also fills in `archetype` via `inferArchetype` when
+ * a pilot doesn't set one explicitly) is the single implementation. Kept as a
+ * re-export, rather than inlining `../component`'s import into every pilot
+ * test, so `./pilots.test.ts`/`./pilots-e2e.test.ts`/`../driver.test.ts`
+ * don't need their import paths touched by this migration.
+ */
+
+export { projectToJson } from "../component";

package/src/components/presets/comp007-reduction.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Presets reduce identical-composition duplication (#566's third acceptance
+ * criterion, tied to the COMP007 copy-paste hint per epic #551's failure-mode
+ * guardrail #3: "Composition copy-paste (declaration sprawl) ... Guard:
+ * presets (Level 2) + a lint hint when an identical composition repeats
+ * across components").
+ *
+ * This demonstrates the concrete before/after COMP007 exists for:
+ *  - "before" — two components hand-authored with an identical phase/step-kind
+ *    shape (the same scenario ../../lint/rules/comp/__fixtures__/comp007/fail/
+ *    covers) trigger COMP007's declaration-sprawl warning, and require
+ *    hand-copying the full phase/step composition a second time.
+ *  - "after" — expressing both as two `EcsFargateComponent({...})` calls
+ *    collapses each declaration to its own params (name/service/healthPath/
+ *    stack), with the shared composition shape lifted into the preset once.
+ *    COMP007 still fires on the *expanded* shape (its fingerprint is
+ *    structural, over the projected composition, by design — see
+ *    ../../lint/rules/comp/comp007-composition-sprawl.ts's docstring: "own
+ *    destiny is in the params, not the shape" is exactly the case a preset
+ *    should absorb) — the reduction is in what the *author* had to write and
+ *    maintain, not in whether the lint hint still recognizes the shared shape.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { Component } from "../component";
+import { phase } from "../component";
+import { loadComponentChecks } from "../../lint/rules/comp/index";
+import type { ComponentCheckContext, ComponentCheckEntry } from "../../lint/component-checks";
+import { EcsFargateComponent } from "./ecs-fargate";
+
+const checks = loadComponentChecks();
+
+function contextFor(components: Component[]): ComponentCheckContext {
+  const map = new Map<string, ComponentCheckEntry>();
+  for (const component of components) {
+    map.set(component.name, { component, filePath: `${component.name}.component.ts` });
+  }
+  return { components: map };
+}
+
+function comp007Diagnostics(components: Component[]) {
+  const ctx = contextFor(components);
+  return checks.flatMap((check) => check.check(ctx)).filter((d) => d.checkId === "COMP007");
+}
+
+describe("Presets reduce composition copy-paste (#566, tied to COMP007)", () => {
+  it("before: two hand-authored components with an identical build->publish->apply->verify shape trigger COMP007", () => {
+    // Two unrelated services, each requiring the full phase/step composition
+    // to be hand-typed and kept in sync by hand — exactly the declaration
+    // sprawl epic #551's failure mode #3 describes.
+    const catalogService: Component = {
+      name: "catalog-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:catalog.template.json", imageRef: "@Publish.digest" },
+          { kind: "ecs-update-service", cluster: "$env.cluster", service: "catalog" },
+        ]),
+        phase("Verify", [
+          { kind: "wait-steady-state", service: "catalog" },
+          { kind: "health-gate", path: "/healthz" },
+        ]),
+      ],
+    };
+    const billingService: Component = {
+      name: "billing-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:billing.template.json", imageRef: "@Publish.digest" },
+          { kind: "ecs-update-service", cluster: "$env.cluster", service: "billing" },
+        ]),
+        phase("Verify", [
+          { kind: "wait-steady-state", service: "billing" },
+          { kind: "health-gate", path: "/healthz" },
+        ]),
+      ],
+    };
+
+    const diagnostics = comp007Diagnostics([catalogService, billingService]);
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics.map((d) => d.component).sort()).toEqual(["billing-service", "catalog-service"]);
+    expect(diagnostics[0]!.message).toContain("consider extracting a shared preset");
+  });
+
+  it("after: the same two services expressed via EcsFargateComponent collapse to one line of params each, instead of a hand-copied phase/step composition", () => {
+    const catalogService = EcsFargateComponent({
+      name: "catalog-service",
+      healthPath: "/healthz",
+      sharedAlbStack: "shared-alb",
+    });
+    const billingService = EcsFargateComponent({
+      name: "billing-service",
+      healthPath: "/healthz",
+      sharedAlbStack: "shared-alb",
+    });
+
+    // The two declarations are now just their own distinguishing params; the
+    // shared composition shape is defined exactly once, in ./ecs-fargate.ts,
+    // not copy-pasted per component. COMP007's fingerprint is structural
+    // (over the *expanded* composition), so it still — correctly — reports
+    // that these two share a shape; the point of the preset was never to
+    // silence the lint hint, it was to make the shared shape a single
+    // maintained definition instead of N hand-copied ones.
+    const diagnostics = comp007Diagnostics([catalogService, billingService]);
+    expect(diagnostics).toHaveLength(2);
+
+    // The expanded contract is identical to the hand-authored "before" case
+    // above (same phases, same step kinds/order) — the preset changed nothing
+    // about the resulting composition, only how many times its shape had to
+    // be typed out by hand (once, in the preset, instead of once per component).
+    expect(catalogService.deploy.map((p) => ({ phase: p.phase, kinds: p.steps.map((s) => (s as { kind: string }).kind) }))).toEqual(
+      billingService.deploy.map((p) => ({ phase: p.phase, kinds: p.steps.map((s) => (s as { kind: string }).kind) })),
+    );
+  });
+});

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

@@ -0,0 +1,84 @@
+/**
+ * `EcsFargateComponent` (#566): schema validity, and equivalence with the
+ * hand-composed `alb-ecs.pilot.ts` reference component — the "preset-based
+ * and hand-composed component produce equivalent contracts" acceptance
+ * criterion from #566.
+ */
+
+import { describe, expect, it } from "vitest";
+import Ajv2020 from "ajv/dist/2020";
+import componentSchema from "../component.schema.json";
+import { projectToJson } from "../component";
+import { searchService } from "../pilots/alb-ecs.pilot";
+import { EcsFargateComponent } from "./ecs-fargate";
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(componentSchema);
+
+describe("EcsFargateComponent preset", () => {
+  it("expands to a component that projects to schema-valid JSON", () => {
+    const component = EcsFargateComponent({
+      name: "search-service",
+      healthPath: "/healthz",
+      sharedAlbStack: "shared-alb",
+    });
+    const projected = projectToJson(component);
+    const valid = validate(projected);
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+  });
+
+  it("re-derives alb-ecs.pilot.ts's hand-composed searchService component byte-for-byte (as data)", () => {
+    const fromPreset = EcsFargateComponent({
+      name: "search-service",
+      service: "search",
+      // The pilot's template is derived from the service name ("search"), not
+      // the component name ("search-service") this preset defaults from —
+      // pass it explicitly to match the pre-existing hand-composed pilot exactly.
+      template: "archive:search.template.json",
+      healthPath: "/healthz",
+      sharedAlbStack: "shared-alb",
+    });
+
+    // Same contract, whether authored via the preset or hand-composed from
+    // raw capabilities — the preset is Level 2 convenience over the same
+    // Level 1 primitives, never a different orchestrator behavior.
+    expect(projectToJson(fromPreset)).toEqual(projectToJson(searchService));
+  });
+
+  it("supports dropping to a customized shape by spreading the preset's output — the 'starts from it and drops to raw capabilities where special' path #566 requires", () => {
+    const base = EcsFargateComponent({
+      name: "search-service-canary",
+      healthPath: "/healthz",
+      sharedAlbStack: "shared-alb",
+    });
+
+    // A component that is 90% the standard shape but needs one extra Verify
+    // step (e.g. a canary-specific smoke test) starts from the preset and
+    // edits the composition directly, rather than the preset needing a new
+    // config knob for every possible variation.
+    const customized = {
+      ...base,
+      deploy: base.deploy.map((p) =>
+        p.phase === "Verify" ? { ...p, steps: [...p.steps, { kind: "shell", command: "./smoke-test.sh" }] } : p,
+      ),
+    };
+
+    const projected = projectToJson(customized);
+    const valid = validate(projected);
+    if (!valid) throw new Error(ajv.errorsText(validate.errors));
+    expect(valid).toBe(true);
+    const verifyPhase = (projected as { deploy: Array<{ phase: string; steps: Array<{ kind: string }> }> }).deploy.find(
+      (p) => p.phase === "Verify",
+    )!;
+    expect(verifyPhase.steps.map((s) => s.kind)).toEqual(["wait-steady-state", "health-gate", "shell"]);
+  });
+
+  it("omits shared-ALB cross-stack wiring and dependsOn when sharedAlbStack is not given", () => {
+    const standalone = EcsFargateComponent({ name: "standalone-service", healthPath: "/healthz" });
+    expect(standalone.dependsOn).toEqual([]);
+    const applyPhase = standalone.deploy.find((p) => p.phase === "Apply")!;
+    const cfnStep = applyPhase.steps[0] as { inputs?: unknown };
+    expect(cfnStep.inputs).toBeUndefined();
+  });
+});