@intentius/chant 0.78.0 → 0.80.0

package/src/components/discover.ts

@@ -49,6 +49,9 @@ import { isComponent, type Component } from "./component";
 import type { BuildParamProvenance } from "../provenance";
 import { buildParamValues } from "../build-params";
 import { setBuildParams } from "../params";
+import { compileDiscoveryFilter, hasDiscoveryMarker } from "../discovery/files";
+import { resolveDiscoveryGlobs } from "../config";
+import { warnDiscoveryChanges } from "../discovery/convergence";
 
 /** One discovered component, paired with the file it was exported from. */
 export interface DiscoveredComponent {
@@ -118,11 +121,15 @@ export interface ImportedComponentModule {
  * Recursively find every `*.component.ts` file under `path`, the same
  * child-project boundary rule `findInfraFiles` (`../discovery/files.ts`)
  * uses: a subdirectory with its own `chant.config.ts` is a separate scope
- * once the outer project's own source root has been established.
+ * once the outer project's own source root has been established. The
+ * project's `exclude`/`include` globs and the skip marker apply here as they
+ * do there (#2519).
  */
 async function findComponentFiles(path: string): Promise<string[]> {
   const files: string[] = [];
   let sourceRoot: string | null = null;
+  const skip = compileDiscoveryFilter(await resolveDiscoveryGlobs(path));
+  const skippedChildren: string[] = [];
 
   async function scanDirectory(dir: string): Promise<void> {
     let entries;
@@ -148,6 +155,7 @@ async function findComponentFiles(path: string): Promise<string[]> {
           if (sourceRoot === null) {
             sourceRoot = fullPath;
           } else {
+            skippedChildren.push(fullPath);
             continue;
           }
         }
@@ -156,7 +164,9 @@ async function findComponentFiles(path: string): Promise<string[]> {
         entry.isFile() &&
         entry.name.endsWith(".component.ts") &&
         !entry.name.endsWith(".test.component.ts") &&
-        !entry.name.endsWith(".spec.component.ts")
+        !entry.name.endsWith(".spec.component.ts") &&
+        !skip?.(fullPath) &&
+        !(await hasDiscoveryMarker(fullPath))
       ) {
         files.push(fullPath);
       }
@@ -164,6 +174,20 @@ async function findComponentFiles(path: string): Promise<string[]> {
   }
 
   await scanDirectory(path);
+  // #2527's warning release: the list returned is today's, unchanged.
+  await warnDiscoveryChanges({
+    walker: "components",
+    root: path,
+    files,
+    sourceRoot,
+    skippedChildren,
+    fileOk: async (name, full) =>
+      name.endsWith(".component.ts") &&
+      !name.endsWith(".test.component.ts") &&
+      !name.endsWith(".spec.component.ts") &&
+      !skip?.(full) &&
+      !(await hasDiscoveryMarker(full)),
+  });
   return files;
 }
 

package/src/components/driver.test.ts

@@ -450,7 +450,7 @@ describe("runComponentDeploy — onFailure saga rollback", () => {
     );
   });
 
-  it("runs a component-level rollback (schema `rollback` field) after step rollback, matching the ALB/ECS pilot's explicit compensation", async () => {
+  it("runs a component-level rollback (schema `rollback` field) after step rollback", async () => {
     const registry = new CapabilityRegistry();
     registry.register(fakeCapability("docker-build", { run: () => ({ digest: "sha256:abc" }) }).capability);
     registry.register(
@@ -458,26 +458,29 @@ describe("runComponentDeploy — onFailure saga rollback", () => {
         .capability,
     );
     registry.register(fakeCapability("cfn-deploy", { run: () => ({ stackStatus: "UPDATE_COMPLETE", outputs: {} }) }).capability);
-    // ecs-update-service fails, and (per the pilot's comment) has no native
-    // rollback — the component's own `rollback` phase is what should fire.
+    // ecs-update-service fails; the component's own `rollback` phase is what
+    // should fire after the executed steps unwind.
     registry.register(fakeCapability("ecs-update-service", { failRun: true }).capability);
-    const { capability: rollbackPreviousCap, calls: rollbackPreviousCalls } = fakeCapability("rollback-previous", {
+    const { capability: restoreCap, calls: restoreCalls } = fakeCapability("restore-service", {
       run: () => ({ restored: true }),
     });
-    registry.register(rollbackPreviousCap);
+    registry.register(restoreCap);
     // Verify/rollback phases never reached since Apply fails first, but register
     // stubs anyway so a hypothetical reordering wouldn't crash the test on an
     // unregistered kind.
     registry.register(fakeCapability("wait-steady-state", { run: () => ({ runningCount: 1 }) }).capability);
     registry.register(fakeCapability("health-gate", { run: () => ({ healthy: true }) }).capability);
 
-    const json = projectToJson(searchService) as unknown as DriverComponent;
+    const json: DriverComponent = {
+      ...(projectToJson(searchService) as unknown as DriverComponent),
+      rollback: [{ phase: "Rollback", steps: [{ kind: "restore-service", service: "search" }] }],
+    };
     const result = await runComponentDeploy(json, { env: "dev", component: "search-service" }, registry, {});
 
     expect(result.ok).toBe(false);
-    expect(rollbackPreviousCalls).toHaveLength(1);
-    expect(rollbackPreviousCalls[0]!.input).toMatchObject({ service: "search" });
-    const rollbackRecord = result.records.find((r) => r.phase === "Rollback" && r.kind === "rollback-previous");
+    expect(restoreCalls).toHaveLength(1);
+    expect(restoreCalls[0]!.input).toMatchObject({ service: "search" });
+    const rollbackRecord = result.records.find((r) => r.phase === "Rollback" && r.kind === "restore-service");
     expect(rollbackRecord?.status).toBe("ok");
   });
 });
@@ -630,7 +633,6 @@ describe("runInterpretDriver — end to end", () => {
       "ecs-update-service",
       "wait-steady-state",
       "health-gate",
-      "rollback-previous",
       "wait-for-stack",
       "run-migration",
     ];
@@ -750,7 +752,6 @@ describe("runInterpretDriver — end to end", () => {
       "ecs-update-service",
       "wait-steady-state",
       "health-gate",
-      "rollback-previous",
       "wait-for-stack",
       "run-migration",
       "lambda-deploy",

package/src/components/driver.ts

@@ -49,6 +49,7 @@
 import { topoSort } from "../codegen/topo-sort";
 import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
+import { warnOnUnboundComponentApproval } from "./unbound-gate-approval";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
 import type { RunProgressEvent, RunProgressStatus } from "./run-progress";
@@ -479,6 +480,7 @@ async function runPhase(
         }
         throw new GateStop(gateRecords, [], check.pending, check.pushed, check.pushWarning);
       }
+      warnOnUnboundComponentApproval(ctx.component, gateName(gate), ctx.env, check.resolution);
       gateRecords.push({
         ...base,
         status: "ok" as const,

package/src/components/fan-out-support.ts

@@ -13,6 +13,7 @@
  * over.
  */
 
+import { lexiconNames } from "../lexicon-module";
 import { resolveComponentTargets } from "./cli-support";
 import { applyConfigDefaults } from "./config-defaults";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
@@ -91,5 +92,5 @@ export async function deriveFanOut(options: DeriveFanOutOptions): Promise<Derive
  */
 export async function fanOutRegistry(path: string, config?: ChantConfig): Promise<CapabilityRegistry> {
   const resolved = config ?? (await loadChantConfig(path)).config;
-  return buildCapabilityRegistry({ plugins: resolved.capabilities, lexicons: resolved.lexicons });
+  return buildCapabilityRegistry({ plugins: resolved.capabilities, lexicons: lexiconNames(resolved.lexicons) });
 }

package/src/components/pilots/README.md

@@ -13,7 +13,7 @@ The epic ([#551](https://github.com/INTENTIUS/chant/issues/551)) picked these th
 |---|---|---|---|---|---|---|
 | **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-services/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-services/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 |
+| **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-services/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-services/src/pipeline.ts) | **no** — the in-run unwind calls `ecs-update-service`'s best-effort re-apply and `cfn-deploy`'s native rollback. The component declares no `rollback` phase (#2576), and an earlier release is restored with `chant components rollback` |
 
 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.
 

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

@@ -1,7 +1,7 @@
 /**
  * Pilot: ALB/ECS target (#555, epic #551).
  *
- * Exercises the build + cross-stack + auto-rollback axes: `docker-build` →
+ * Exercises the build + cross-stack 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
@@ -16,6 +16,12 @@
  * capabilities. `service` archetype: build → publish → apply → verify, the
  * fullest of the three archetypes.
  *
+ * It declares no component-level `rollback` phase (#2576). It used to declare
+ * one holding a `rollback-previous` step with only `service` and `cluster`,
+ * which the aws capability turned into an `aws ecs update-service` with no
+ * changes. Taking an environment back to an earlier recorded release is
+ * `chant components rollback` (#2531).
+ *
  * 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`
@@ -54,10 +60,4 @@ export const searchService: Component = {
       { 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/presets/ecs-fargate.ts

@@ -4,10 +4,16 @@
  * 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).
+ * `ecs-update-service` -> `wait-steady-state` + `health-gate`.
+ *
+ * There is no component-level `rollback` phase (#2576). The preset used to
+ * declare one holding a `rollback-previous` step with only `service` and
+ * `cluster`. The aws capability behind that kind rolls a service back to the
+ * `taskDefinition` it is given, and with none given it ran `aws ecs
+ * update-service` with no changes, so the phase restored nothing. The
+ * in-run unwind still calls each executed step's own rollback, and taking an
+ * environment back to an earlier recorded release is `chant components
+ * rollback <env> --component <name>` (#2531).
  *
  * This is Level 2 reuse over Level 1 raw capabilities: a component that looks
  * like this composes `EcsFargateComponent({ ... })` directly; the odd case
@@ -98,6 +104,5 @@ export function EcsFargateComponent(config: EcsFargateComponentConfig): Componen
         { kind: "health-gate", path: config.healthPath },
       ]),
     ],
-    rollback: [phase("Rollback", [{ kind: "rollback-previous", service, cluster }])],
   };
 }

package/src/components/promote.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Promote a release without rebuilding (#2530).
+ */
+
+import { describe, test, expect } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "./capability";
+import { memoryGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import type { DriverComponent } from "./driver";
+import type { ReleaseRecord } from "../lifecycle/release-ledger";
+import {
+  planPromotion,
+  planRollback,
+  rollbackRecord,
+  selectRelease,
+  withoutBuildSteps,
+  runPromotion,
+  promotionRecord,
+  gateApprover,
+  promoteArchivePaths,
+  type PromotionPlan,
+} from "./promote";
+
+const rec = (component: string, env: string, digest: string, timestamp: string, runId = `run-${timestamp}`): ReleaseRecord => ({
+  version: 1,
+  component,
+  env,
+  digest,
+  gitSha: "abc123",
+  runId,
+  timestamp,
+  actor: "ci",
+});
+
+/** Build, publish, apply: the shape the pilots and the adopt example use. */
+const service = (name: string, extra: Partial<DriverComponent> = {}): DriverComponent => ({
+  name,
+  deploy: [
+    { phase: "Build", steps: [{ kind: "docker-build", context: ".", into: `${name}.tar` }] },
+    { phase: "Publish", steps: [{ kind: "publish-image", from: `archive:${name}.tar`, to: "$env.registry" }] },
+    { phase: "Apply", steps: [{ kind: "apply", imageRef: "@Publish.digest" }] },
+  ],
+  ...extra,
+});
+
+describe("selecting the source release", () => {
+  const records = [
+    rec("api", "staging", "sha256:old", "2026-01-01T00:00:00Z"),
+    rec("api", "staging", "sha256:new", "2026-01-02T00:00:00Z"),
+    rec("web", "staging", "sha256:web", "2026-01-01T00:00:00Z"),
+  ];
+
+  test("the latest release by default", () => {
+    const picked = selectRelease(records, "api", "staging");
+    expect("record" in picked && picked.record.digest).toBe("sha256:new");
+  });
+
+  test("a named digest that the ledger recorded", () => {
+    const picked = selectRelease(records, "api", "staging", "sha256:old");
+    expect("record" in picked && picked.record.timestamp).toBe("2026-01-01T00:00:00Z");
+  });
+
+  test("a digest missing from the source ledger fails and names what is recorded", () => {
+    const picked = selectRelease(records, "api", "staging", "sha256:nope");
+    expect("error" in picked && picked.error).toMatch(/sha256:nope is not recorded for "api" in "staging"/);
+    expect("error" in picked && picked.error).toMatch(/sha256:old, sha256:new/);
+  });
+
+  test("a component with no release in the source fails", () => {
+    const picked = selectRelease(records, "db", "staging");
+    expect("error" in picked && picked.error).toMatch(/no release of "db" is recorded in "staging"/);
+  });
+});
+
+describe("planning", () => {
+  const records = [
+    rec("api", "staging", "sha256:api", "2026-01-02T00:00:00Z"),
+    rec("gone", "staging", "sha256:gone", "2026-01-02T00:00:00Z"),
+  ];
+
+  test("every declared component with a source release, and the rest reported", () => {
+    const plan = planPromotion({ from: "staging", to: "prod", sourceRecords: records, declared: ["api", "infra"] });
+    expect("items" in plan).toBe(true);
+    const { items, notPromoted } = plan as PromotionPlan;
+    expect(items.map((i) => [i.component, i.digest])).toEqual([["api", "sha256:api"]]);
+    expect(notPromoted).toEqual([{ component: "gone", reason: "recorded but not declared in this checkout" }]);
+  });
+
+  test("refuses the same environment on both sides", () => {
+    const plan = planPromotion({ from: "prod", to: "prod", sourceRecords: records, declared: ["api"] });
+    expect("error" in plan && plan.error).toMatch(/same environment/);
+  });
+
+  test("--digest needs --component", () => {
+    const plan = planPromotion({ from: "staging", to: "prod", sourceRecords: records, declared: ["api"], digest: "sha256:api" });
+    expect("error" in plan && plan.error).toMatch(/needs --component/);
+  });
+
+  test("an empty source ledger is an error, not a no-op", () => {
+    const plan = planPromotion({ from: "staging", to: "prod", sourceRecords: [], declared: ["api"] });
+    expect("error" in plan && plan.error).toMatch(/nothing to promote/);
+  });
+});
+
+describe("taking the build out of a composition", () => {
+  test("build steps go, publish and apply stay", () => {
+    const prepared = withoutBuildSteps(service("api"));
+    expect("component" in prepared).toBe(true);
+    if (!("component" in prepared)) return;
+    expect(prepared.removed).toEqual(["docker-build"]);
+    expect(prepared.component.deploy.map((p) => p.phase)).toEqual(["Publish", "Apply"]);
+  });
+
+  test("gates survive, even in a phase that loses its build step", () => {
+    const c = service("api");
+    c.deploy[0].steps.unshift({ kind: "gate", gate: "release" });
+    const prepared = withoutBuildSteps(c);
+    if (!("component" in prepared)) throw new Error(prepared.error);
+    expect(prepared.component.deploy[0]).toEqual({ phase: "Build", steps: [{ kind: "gate", gate: "release" }] });
+  });
+
+  test("no publish step is refused", () => {
+    const c: DriverComponent = { name: "chart", deploy: [{ phase: "Apply", steps: [{ kind: "helm-upgrade" }] }] };
+    const prepared = withoutBuildSteps(c);
+    expect("error" in prepared && prepared.error).toMatch(/no publish step/);
+  });
+
+  test("two publish steps are refused", () => {
+    const c = service("api");
+    c.deploy[1].steps.push({ kind: "publish-artifact", from: "archive:x.jar" });
+    const prepared = withoutBuildSteps(c);
+    expect("error" in prepared && prepared.error).toMatch(/2 publish steps/);
+  });
+
+  test("a step reading a removed build step's output is refused", () => {
+    const c = service("api");
+    c.deploy[1].steps[0] = { kind: "publish-image", from: "@Build.archivePath", to: "$env.registry" };
+    const prepared = withoutBuildSteps(c);
+    expect("error" in prepared && prepared.error).toMatch(/reads "@Build.archivePath"/);
+  });
+});
+
+/** A registry of fakes. `publishes` is the digest publish-image returns per component. */
+function fakeRegistry(publishes: Record<string, string>) {
+  const ran: string[] = [];
+  const registry = new CapabilityRegistry();
+  const step = (kind: string, run: (ctx: DeployContext, input: Record<string, unknown>) => unknown) =>
+    registry.register({ kind, async run(ctx: DeployContext, input: Record<string, unknown>) { ran.push(`${ctx.env}:${ctx.component}:${kind}`); return run(ctx, input); } } as never);
+  step("docker-build", () => ({ digest: "sha256:rebuilt" }));
+  step("publish-image", (ctx) => ({ digest: publishes[ctx.component], uri: `reg/${ctx.component}@${publishes[ctx.component]}` }));
+  step("apply", (_ctx, input) => ({ applied: input.imageRef }));
+  return { registry, ran };
+}
+
+function planFor(component: string, digest: string): PromotionPlan {
+  return {
+    from: "staging",
+    to: "prod",
+    items: [{ component, digest, source: rec(component, "staging", digest, "2026-01-02T00:00:00Z", "run-7") }],
+    notPromoted: [],
+  };
+}
+
+function prepared(c: DriverComponent): DriverComponent {
+  const p = withoutBuildSteps(c);
+  if ("error" in p) throw new Error(p.error);
+  return p.component;
+}
+
+describe("running a promotion", () => {
+  test("deploys the recorded digest to the target without building", async () => {
+    const { registry, ran } = fakeRegistry({ api: "sha256:api" });
+    const run = await runPromotion({
+      plan: planFor("api", "sha256:api"),
+      components: [prepared(service("api"))],
+      registry,
+      gates: memoryGateLedgerPort(),
+    });
+    expect(run.status).toBe("ok");
+    expect(ran).toEqual(["prod:api:publish-image", "prod:api:apply"]);
+    const apply = run.results[0].records.find((r) => r.kind === "apply");
+    expect(apply?.output).toEqual({ applied: "sha256:api" });
+  });
+
+  test("a publish that yields another digest fails before apply runs", async () => {
+    const { registry, ran } = fakeRegistry({ api: "sha256:different" });
+    const run = await runPromotion({
+      plan: planFor("api", "sha256:api"),
+      components: [prepared(service("api"))],
+      registry,
+      gates: memoryGateLedgerPort(),
+    });
+    expect(run.status).toBe("fail");
+    expect(ran).not.toContain("prod:api:apply");
+    const publish = run.results[0].records.find((r) => r.kind === "publish-image" && r.status === "fail");
+    expect(publish?.error).toMatch(/published sha256:different, but the release being promoted recorded sha256:api/);
+  });
+
+  test("the target's gate still applies, and an approval lets the same promote through", async () => {
+    const gated = service("api");
+    gated.deploy[2].steps.unshift({ kind: "gate", gate: "prod-release" });
+    const resolutions: GateResolutionRecord[] = [];
+    const memory = memoryGateLedgerPort();
+    const gates: GateLedgerPort = {
+      async read(op) {
+        const read = await memory.read(op);
+        return { ...read, resolutions: [...resolutions] };
+      },
+      appendPending: (input) => memory.appendPending(input),
+    };
+    const { registry, ran } = fakeRegistry({ api: "sha256:api" });
+    const opts = { plan: planFor("api", "sha256:api"), components: [prepared(gated)], registry, gates };
+
+    const first = await runPromotion({ ...opts, now: "2026-01-03T00:00:00Z" });
+    expect(first.status).toBe("gated");
+    expect(first.gate?.gate).toBe("prod-release");
+    expect(ran).not.toContain("prod:api:apply");
+
+    resolutions.push({ version: 1, kind: "resolution", op: "api", gate: "prod-release", resolvedBy: "alice", timestamp: "2026-01-03T00:01:00Z" });
+    const second = await runPromotion({ ...opts, now: "2026-01-03T00:02:00Z" });
+    expect(second.status).toBe("ok");
+    expect(gateApprover(second.results[0])).toBe("alice");
+  });
+
+  test("dependencies outside the promotion do not block it", async () => {
+    const { registry } = fakeRegistry({ api: "sha256:api" });
+    const run = await runPromotion({
+      plan: planFor("api", "sha256:api"),
+      components: [prepared(service("api", { dependsOn: ["shared-alb"] }))],
+      registry,
+      gates: memoryGateLedgerPort(),
+    });
+    expect(run.status).toBe("ok");
+  });
+});
+
+describe("the target record", () => {
+  test("carries the source release it promoted", () => {
+    const plan = planFor("api", "sha256:api");
+    plan.items[0].source.manifestDigest = "sha256:manifest";
+    const record = promotionRecord(plan.items[0], "prod", {
+      runId: "run-9",
+      actor: "bob",
+      timestamp: "2026-01-04T00:00:00Z",
+      approver: "alice",
+    });
+    expect(record).toEqual({
+      component: "api",
+      env: "prod",
+      digest: "sha256:api",
+      gitSha: "abc123",
+      runId: "run-9",
+      timestamp: "2026-01-04T00:00:00Z",
+      actor: "bob",
+      approver: "alice",
+      manifestDigest: "sha256:manifest",
+      promotedFrom: { env: "staging", runId: "run-7", timestamp: "2026-01-02T00:00:00Z" },
+    });
+  });
+});
+
+describe("choosing the release a rollback restores", () => {
+  const history = [
+    rec("api", "prod", "sha256:a", "2026-01-01T00:00:00Z"),
+    rec("api", "prod", "sha256:b", "2026-01-02T00:00:00Z"),
+    rec("api", "prod", "sha256:c", "2026-01-03T00:00:00Z"),
+  ];
+  const plan = (input: Partial<Parameters<typeof planRollback>[0]>) =>
+    planRollback({ env: "prod", records: history, declared: ["api"], component: "api", ...input });
+
+  test("the release before the current one by default", () => {
+    const p = plan({});
+    expect("items" in p && p.items[0].digest).toBe("sha256:b");
+    expect("items" in p && p.from).toBe("prod");
+  });
+
+  test("a redeploy of the current digest does not count as an earlier release", () => {
+    const p = plan({ records: [...history, rec("api", "prod", "sha256:c", "2026-01-04T00:00:00Z")] });
+    expect("items" in p && p.items[0].digest).toBe("sha256:b");
+  });
+
+  test("a chosen digest", () => {
+    const p = plan({ digest: "sha256:a" });
+    expect("items" in p && p.items[0].source.timestamp).toBe("2026-01-01T00:00:00Z");
+  });
+
+  test("a digest the environment never recorded is refused", () => {
+    const p = plan({ digest: "sha256:z" });
+    expect("error" in p && p.error).toMatch(/sha256:z is not recorded for "api" in "prod"/);
+  });
+
+  test("the current release is refused", () => {
+    const p = plan({ digest: "sha256:c" });
+    expect("error" in p && p.error).toMatch(/already the current release/);
+  });
+
+  test("a single release has nothing earlier", () => {
+    const p = plan({ records: [history[0]] });
+    expect("error" in p && p.error).toMatch(/no earlier release/);
+  });
+});
+
+describe("pinning the publish step for a rollback", () => {
+  test("the publish step is replaced by the recorded digest", () => {
+    const p = withoutBuildSteps(service("api"), { pinDigest: "sha256:b" });
+    if ("error" in p) throw new Error(p.error);
+    expect(p.removed).toEqual(["docker-build", "publish-image"]);
+    expect(p.component.deploy[0].steps[0]).toMatchObject({ kind: "recorded-digest", digest: "sha256:b", replaces: "publish-image" });
+  });
+
+  test("a step reading another publish output is refused", () => {
+    const c = service("api");
+    c.deploy[2].steps[0] = { kind: "apply", image: "@Publish.uri" };
+    const p = withoutBuildSteps(c, { pinDigest: "sha256:b" });
+    expect("error" in p && p.error).toMatch(/reads "@Publish.uri", but a rollback knows only the recorded digest/);
+  });
+
+  test("a rollback redeploys the recorded digest and publishes nothing", async () => {
+    const { registry, ran } = fakeRegistry({ api: "sha256:new" });
+    const p = withoutBuildSteps(service("api"), { pinDigest: "sha256:b" });
+    if ("error" in p) throw new Error(p.error);
+    const plan: PromotionPlan = {
+      from: "prod",
+      to: "prod",
+      items: [{ component: "api", digest: "sha256:b", source: rec("api", "prod", "sha256:b", "2026-01-02T00:00:00Z", "run-2") }],
+      notPromoted: [],
+    };
+    const run = await runPromotion({ plan, components: [p.component], registry, gates: memoryGateLedgerPort() });
+    expect(run.status).toBe("ok");
+    expect(ran).toEqual(["prod:api:apply"]);
+    expect(run.results[0].records.find((r) => r.kind === "apply")?.output).toEqual({ applied: "sha256:b" });
+
+    expect(rollbackRecord(plan.items[0], "prod", { runId: "run-5", actor: "bob", timestamp: "2026-01-05T00:00:00Z" })).toMatchObject({
+      env: "prod",
+      digest: "sha256:b",
+      restores: { env: "prod", runId: "run-2", timestamp: "2026-01-02T00:00:00Z" },
+    });
+  });
+});
+
+describe("the archive paths a generated promote job carries (#2575)", () => {
+  test("every build step's into, nested phases included, once each and in order", () => {
+    const component: DriverComponent = {
+      name: "api",
+      deploy: [
+        { phase: "Build", steps: [
+          { kind: "docker-build", context: ".", into: "dist/api.tar" },
+          { kind: "generate-sbom", artifactType: "image", path: "dist/api.tar", into: "dist/api.sbom.json" },
+          { phase: "Lambdas", parallel: true, steps: [{ kind: "zip-package", source: "fn", into: "dist/fn.zip" }] },
+        ] },
+        { phase: "Again", steps: [{ kind: "docker-build", context: ".", into: "dist/api.tar" }] },
+        { phase: "Publish", steps: [{ kind: "publish-image", from: "archive:dist/api.tar" }] },
+      ],
+    };
+    expect(promoteArchivePaths(component)).toEqual(["dist/api.tar", "dist/fn.zip"]);
+  });
+
+  test("a component that builds nothing carries nothing", () => {
+    expect(promoteArchivePaths({ name: "infra", deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy" }] }] })).toEqual([]);
+  });
+
+  test("an into that is only known at run time is refused by name", () => {
+    for (const into of ["@Params.path", "$env.archive", undefined]) {
+      const component: DriverComponent = {
+        name: "api",
+        deploy: [{ phase: "Build", steps: [{ kind: "jvm-build", into }] }],
+      };
+      expect(() => promoteArchivePaths(component)).toThrow(/component "api": the jvm-build step in phase "Build".*not a literal path/);
+    }
+  });
+});