@intentius/chant 0.79.0 → 0.80.0

package/src/components/promote.ts

@@ -0,0 +1,537 @@
+/**
+ * Promote a release to another environment without rebuilding (#2530).
+ *
+ * `chant run --components <name> --env prod` runs the component's whole
+ * `deploy` composition, and a composition that builds (a `Build` phase with
+ * `docker-build`) builds again in prod. The release ledger already knows which
+ * digest staging is running, so a promote reads that record and deploys the
+ * same artifact to the target environment instead.
+ *
+ * The mechanism is a transform on the composition, not a change to the driver:
+ *
+ *  - build-time steps (`BUILD_STEP_KINDS`) are removed, so nothing is built;
+ *  - the publish step stays. It moves the archived bytes to the target
+ *    environment, which is what "promote by digest" means in the build-archive
+ *    model, and its output is checked against the recorded digest. A publish
+ *    that produces any other digest fails the step, and so the component,
+ *    before anything after it runs;
+ *  - gates, apply, verify and every other step run exactly as a normal deploy
+ *    to the target environment would run them, so the target's gates apply.
+ *
+ * A composition the transform cannot pin to one recorded digest is refused
+ * before anything runs: one with no publish step (nothing would carry the
+ * digest), one with more than one (the ledger records one digest per
+ * component), and one whose remaining steps read an output of a removed build
+ * step (it would resolve to nothing).
+ *
+ * A rollback (#2531) is the same run against one environment's own earlier
+ * release. There the publish step is replaced by the recorded digest rather
+ * than run, since the environment already received that artifact when the
+ * release was first deployed (see `withoutBuildSteps`'s `pinDigest`).
+ *
+ * The driver stays capability-agnostic. The two kind lists below are data, in
+ * the same spirit as `DEPLOY_UNIT_RULES` (./deploy-units.ts).
+ */
+
+import { parseWiringRef, type WiringRef } from "../lint/rules/comp/support";
+import { latestPerComponent, type ReleaseRecord, type ReleaseRecordInput, type RunOrigin } from "../lifecycle/release-ledger";
+import { CapabilityRegistry, type Capability } from "./capability";
+import {
+  runInterpretDriver,
+  DriverRunFailure,
+  type DriverComponent,
+  type DriverComponentResult,
+  type DriverGate,
+  type DriverPhase,
+  type DriverRunResult,
+  type DriverStep,
+} from "./driver";
+import type { GateLedgerPort } from "../op/gate";
+import type { RunProgressEvent } from "./run-progress";
+
+/**
+ * Step kinds that produce an artifact at build time: the build family, and the
+ * SBOM steps that read the freshly built archive. A promote removes them.
+ */
+export const BUILD_STEP_KINDS: readonly string[] = [
+  "docker-build",
+  "zip-package",
+  "jvm-build",
+  "generate-sbom",
+  "extract-config-bom",
+];
+
+/**
+ * The publish family (the same set COMP001 recognises, plus the
+ * `publish-asset` alias). Its output digest is the one a release record binds.
+ */
+export const PUBLISH_STEP_KINDS: readonly string[] = [
+  "publish-image",
+  "publish-artifact",
+  "publish-asset",
+  "load-image-on-host",
+];
+
+/** One component a promote will deploy, and the source release it deploys. */
+export interface PromotionItem {
+  component: string;
+  /** The recorded digest being promoted. */
+  digest: string;
+  /** The source environment's release record the digest came from. */
+  source: ReleaseRecord;
+}
+
+/** What a promote will do, decided before anything runs. */
+export interface PromotionPlan {
+  from: string;
+  to: string;
+  items: PromotionItem[];
+  /** Components left alone, and why. Reported, never an error. */
+  notPromoted: Array<{ component: string; reason: string }>;
+}
+
+/**
+ * Pick one release of `component` out of an environment's records: the latest
+ * one, or, when `digest` is given, the latest one that recorded that digest.
+ * A digest the ledger never recorded for the component is an error.
+ */
+export function selectRelease(
+  records: ReleaseRecord[],
+  component: string,
+  env: string,
+  digest?: string,
+): { record: ReleaseRecord } | { error: string } {
+  const own = records.filter((r) => r.component === component);
+  if (own.length === 0) return { error: `no release of "${component}" is recorded in "${env}"` };
+  if (digest === undefined) return { record: latestPerComponent(own).get(component)! };
+  const matching = own.filter((r) => r.digest === digest);
+  if (matching.length === 0) {
+    return {
+      error: `digest ${digest} is not recorded for "${component}" in "${env}"; ` +
+        `its recorded digests are ${[...new Set(own.map((r) => r.digest))].join(", ")}`,
+    };
+  }
+  return { record: latestPerComponent(matching).get(component)! };
+}
+
+/**
+ * Decide which releases a promote deploys. With `component`, exactly that
+ * component's latest source release (or the one recording `digest`). Without
+ * it, the latest source release of every component this checkout declares;
+ * a recorded component the checkout no longer declares is reported and left
+ * alone, since there is no composition to deploy it with.
+ */
+export function planPromotion(input: {
+  from: string;
+  to: string;
+  sourceRecords: ReleaseRecord[];
+  /** Names of the components this checkout declares. */
+  declared: string[];
+  component?: string;
+  digest?: string;
+}): PromotionPlan | { error: string } {
+  const { from, to, sourceRecords, declared, component, digest } = input;
+  if (from === to) return { error: `--from and --to name the same environment ("${from}")` };
+  if (digest !== undefined && component === undefined) {
+    return { error: "--digest picks one release of one component, so it needs --component <name>" };
+  }
+
+  if (component !== undefined) {
+    if (!declared.includes(component)) {
+      return { error: `component "${component}" is not declared in this checkout` };
+    }
+    const picked = selectRelease(sourceRecords, component, from, digest);
+    if ("error" in picked) return picked;
+    return { from, to, items: [{ component, digest: picked.record.digest, source: picked.record }], notPromoted: [] };
+  }
+
+  const latest = latestPerComponent(sourceRecords);
+  const items: PromotionItem[] = [];
+  const notPromoted: PromotionPlan["notPromoted"] = [];
+  for (const [name, record] of [...latest].sort(([a], [b]) => a.localeCompare(b))) {
+    if (declared.includes(name)) items.push({ component: name, digest: record.digest, source: record });
+    else notPromoted.push({ component: name, reason: "recorded but not declared in this checkout" });
+  }
+  if (items.length === 0) {
+    return { error: `nothing to promote: no component declared here has a release recorded in "${from}"` };
+  }
+  return { from, to, items, notPromoted };
+}
+
+/**
+ * Decide which release a rollback restores: the release of `component` in
+ * `env` given by `digest`, or by default the most recent release whose digest
+ * differs from the current one. Restoring the release already current is
+ * refused, since there is nothing to roll back.
+ */
+export function planRollback(input: {
+  env: string;
+  records: ReleaseRecord[];
+  declared: string[];
+  component: string;
+  digest?: string;
+}): PromotionPlan | { error: string } {
+  const { env, records, declared, component, digest } = input;
+  if (!declared.includes(component)) {
+    return { error: `component "${component}" is not declared in this checkout` };
+  }
+  const own = records.filter((r) => r.component === component);
+  const current = latestPerComponent(own).get(component);
+  if (!current) return { error: `no release of "${component}" is recorded in "${env}"` };
+
+  let target: ReleaseRecord;
+  if (digest !== undefined) {
+    const picked = selectRelease(own, component, env, digest);
+    if ("error" in picked) return picked;
+    target = picked.record;
+  } else {
+    const earlier = own.filter((r) => r.digest !== current.digest);
+    if (earlier.length === 0) {
+      return { error: `"${component}" has no earlier release in "${env}" with a digest other than the current ${current.digest}` };
+    }
+    target = latestPerComponent(earlier).get(component)!;
+  }
+  if (target.digest === current.digest) {
+    return { error: `${target.digest} is already the current release of "${component}" in "${env}"; nothing to roll back` };
+  }
+  return { from: env, to: env, items: [{ component, digest: target.digest, source: target }], notPromoted: [] };
+}
+
+function isGate(step: DriverStep | DriverGate | DriverPhase): step is DriverGate {
+  return (step as { kind?: unknown }).kind === "gate";
+}
+
+function isPhase(step: DriverStep | DriverGate | DriverPhase): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+/**
+ * The build steps that write the archive a promote's publish step reads, each
+ * to its `into` path. The SBOM steps are left out: a promote refuses a step
+ * that reads their output, so it never needs it.
+ */
+export const ARCHIVE_STEP_KINDS: readonly string[] = ["docker-build", "zip-package", "jvm-build"];
+
+/**
+ * The paths `component`'s build steps write its archive to, in composition
+ * order without repeats (#2575). A generated pipeline carries these files from
+ * the job that deployed to the source environment to the job that promotes,
+ * since a promote publishes from the archive on disk. Throws when an `into` is
+ * not a literal path, such as a wiring reference or an `$env.` value, because
+ * a generator cannot name a file that is only known at run time.
+ */
+export function promoteArchivePaths(component: DriverComponent): string[] {
+  const paths: string[] = [];
+  const walk = (phases: DriverPhase[]): void => {
+    for (const phase of phases) {
+      for (const step of phase.steps) {
+        if (isPhase(step)) walk([step]);
+        else if (!isGate(step) && ARCHIVE_STEP_KINDS.includes(step.kind)) {
+          const into = step.into;
+          if (typeof into !== "string" || into === "" || into.startsWith("@") || into.startsWith("$")) {
+            throw new Error(
+              `component "${component.name}": the ${step.kind} step in phase "${phase.phase}" writes to ` +
+                `${JSON.stringify(into)}, which is not a literal path, so a generated promote job cannot carry its archive`,
+            );
+          }
+          if (!paths.includes(into)) paths.push(into);
+        }
+      }
+    }
+  };
+  walk(component.deploy);
+  return paths;
+}
+
+/** A component's composition with its build-time steps taken out. */
+export interface PromotableComponent {
+  component: DriverComponent;
+  /** The kinds removed, in composition order. */
+  removed: string[];
+}
+
+/**
+ * The step a rollback puts where the publish step was: it publishes nothing
+ * and returns the recorded digest, so `@Publish.digest` resolves to it.
+ */
+export const RECORDED_DIGEST_KIND = "recorded-digest";
+
+/** The capability behind {@link RECORDED_DIGEST_KIND}. */
+export const recordedDigestCapability: Capability<{ digest: string }, { digest: string }> = {
+  kind: RECORDED_DIGEST_KIND,
+  rollbackPolicy: "none-by-design",
+  async run(_ctx, input) {
+    return { digest: input.digest };
+  },
+};
+
+/**
+ * Remove every build-time step from `component`'s `deploy` composition and
+ * check that what is left can be pinned to one recorded digest. A phase left
+ * with nothing to run is dropped. `rollback` phases are untouched.
+ *
+ * With `pinDigest` (a rollback, #2531), the publish step is replaced too, by a
+ * {@link RECORDED_DIGEST_KIND} step carrying that digest: the environment
+ * already received the artifact when the release being restored was
+ * deployed, and the archive it came from is usually long gone. Only the
+ * digest is known then, so a step reading any other publish output (such as
+ * `@Publish.uri`) is refused.
+ */
+export function withoutBuildSteps(
+  component: DriverComponent,
+  opts: { pinDigest?: string } = {},
+): PromotableComponent | { error: string } {
+  const verb = opts.pinDigest === undefined ? "a promote" : "a rollback";
+  const removed: string[] = [];
+  /** Phases a build step was removed from, and whether anything else is left in them. */
+  const emptied = new Map<string, boolean>();
+  /** Phases a publish step was pinned in, and whether anything else is left in them. */
+  const pinned = new Map<string, boolean>();
+  let publishSteps = 0;
+  const kept: DriverStep[] = [];
+
+  const strip = (phase: DriverPhase): DriverPhase | undefined => {
+    const steps: DriverPhase["steps"] = [];
+    let lostBuildStep = false;
+    let pinnedHere = false;
+    for (const step of phase.steps) {
+      if (isGate(step)) {
+        steps.push(step);
+      } else if (isPhase(step)) {
+        const nested = strip(step);
+        if (nested) steps.push(nested);
+      } else if (BUILD_STEP_KINDS.includes(step.kind)) {
+        removed.push(step.kind);
+        lostBuildStep = true;
+      } else if (PUBLISH_STEP_KINDS.includes(step.kind)) {
+        publishSteps++;
+        if (opts.pinDigest === undefined) {
+          kept.push(step);
+          steps.push(step);
+        } else {
+          removed.push(step.kind);
+          pinnedHere = true;
+          steps.push({
+            kind: RECORDED_DIGEST_KIND,
+            digest: opts.pinDigest,
+            replaces: step.kind,
+            noRollback: "publishes nothing; it hands on a digest the environment already received",
+          });
+        }
+      } else {
+        kept.push(step);
+        steps.push(step);
+      }
+    }
+    const otherWork = steps.some((s) => !isGate(s) && (s as DriverStep).kind !== RECORDED_DIGEST_KIND);
+    if (lostBuildStep) emptied.set(phase.phase, !otherWork && !pinnedHere);
+    if (pinnedHere) pinned.set(phase.phase, !otherWork);
+    // A phase holding only gates after the strip still decides them.
+    if (steps.length === 0) return undefined;
+    return { ...phase, steps };
+  };
+
+  const deploy = component.deploy.map(strip).filter((p): p is DriverPhase => p !== undefined);
+
+  if (publishSteps === 0) {
+    return {
+      error: `component "${component.name}" has no publish step, so nothing in its deploy carries a recorded digest; ` +
+        `${verb} would deploy whatever its current source produces`,
+    };
+  }
+  if (publishSteps > 1) {
+    return {
+      error: `component "${component.name}" has ${publishSteps} publish steps, but its release record carries one digest`,
+    };
+  }
+  for (const step of kept) {
+    const { kind: _kind, ...fields } = step;
+    for (const ref of refsIn(fields)) {
+      if (ref.kind === "prior-step" && emptied.get(ref.phaseName) === true) {
+        return {
+          error: `component "${component.name}" reads "@${ref.phaseName}.${ref.field}", an output of a build step ` +
+            `${verb} does not run`,
+        };
+      }
+      const readsPinned =
+        (ref.kind === "prior-step" && pinned.get(ref.phaseName) === true && ref.field !== "digest") ||
+        (ref.kind === "component-artifact" && ref.componentName === component.name && ref.field !== "digest" && pinned.size > 0);
+      if (readsPinned) {
+        const spelled = ref.kind === "prior-step" ? `@${ref.phaseName}.${ref.field}` : `@${ref.componentName}.publish.${ref.field}`;
+        return {
+          error: `component "${component.name}" reads "${spelled}", but ${verb} knows only the recorded digest; ` +
+            `wire the digest instead`,
+        };
+      }
+    }
+  }
+  return { component: { ...component, deploy }, removed };
+}
+
+/** Every same-project wiring reference anywhere in a step's fields (cross-stack `stackOutput` objects excluded). */
+function refsIn(value: unknown): WiringRef[] {
+  const refs: WiringRef[] = [];
+  const walk = (v: unknown): void => {
+    if (typeof v === "string") {
+      const ref = parseWiringRef(v);
+      if (ref) refs.push(ref);
+    } else if (Array.isArray(v)) {
+      v.forEach(walk);
+    } else if (v && typeof v === "object" && !("stackOutput" in v)) {
+      Object.values(v as Record<string, unknown>).forEach(walk);
+    }
+  };
+  walk(value);
+  return refs;
+}
+
+/**
+ * A registry whose publish-family capabilities check what they published
+ * against the digest being promoted for that component. A mismatch fails the
+ * step, which fails the component through the driver's ordinary path. Every
+ * other capability is passed through untouched, and the recorded-digest step a
+ * rollback's composition carries is added.
+ */
+export function checkPublishedDigest(
+  registry: CapabilityRegistry,
+  expected: ReadonlyMap<string, string>,
+): CapabilityRegistry {
+  const checked = new CapabilityRegistry();
+  if (!registry.has(RECORDED_DIGEST_KIND)) checked.register(recordedDigestCapability);
+  for (const kind of registry.kinds()) {
+    const inner = registry.resolve(kind) as Capability<unknown, unknown>;
+    if (!PUBLISH_STEP_KINDS.includes(kind)) {
+      checked.register(inner);
+      continue;
+    }
+    const wrapped: Capability<unknown, unknown> = {
+      kind,
+      ...(inner.rollbackPolicy ? { rollbackPolicy: inner.rollbackPolicy } : {}),
+      async run(ctx, input) {
+        let output: unknown;
+        try {
+          output = await inner.run(ctx, input);
+        } catch (err) {
+          throw new Error(
+            `${kind} could not publish from the build archive: ${err instanceof Error ? err.message : String(err)}. ` +
+              `A promote publishes the archive the source release was built from, so it has to run where that archive is on disk`,
+          );
+        }
+        const want = expected.get(ctx.component);
+        const got = (output as { digest?: unknown } | undefined)?.digest;
+        if (want !== undefined && got !== want) {
+          throw new Error(
+            `${kind} published ${typeof got === "string" ? got : "no digest"}, but the release being promoted recorded ${want}; ` +
+              `the build archive on disk is not the one that release was built from`,
+          );
+        }
+        return output;
+      },
+      ...(inner.rollback
+        ? { rollback: (ctx, input, output) => inner.rollback!(ctx, input, output) }
+        : {}),
+    };
+    checked.register(wrapped);
+  }
+  return checked;
+}
+
+/** Options for {@link runPromotion}. */
+export interface RunPromotionOptions {
+  plan: PromotionPlan;
+  /** The promotable compositions (see {@link withoutBuildSteps}), one per plan item. */
+  components: DriverComponent[];
+  registry: CapabilityRegistry;
+  componentOutputs?: Record<string, Record<string, unknown>>;
+  gates?: GateLedgerPort;
+  now?: string;
+  onProgress?: (event: RunProgressEvent) => void;
+}
+
+/**
+ * Deploy the plan's components to `plan.to`, in dependency order. A
+ * `dependsOn` edge to a component outside the promotion is dropped, the same
+ * way a single-component `chant run --components` runs without its
+ * dependencies; their outputs come from `componentOutputs`. Returns the
+ * driver's result for every outcome, including a failure.
+ */
+export async function runPromotion(options: RunPromotionOptions): Promise<DriverRunResult> {
+  const { plan } = options;
+  const names = new Set(plan.items.map((i) => i.component));
+  const targets = options.components
+    .filter((c) => names.has(c.name))
+    .map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => names.has(d)) }));
+  const expected = new Map(plan.items.map((i) => [i.component, i.digest]));
+  try {
+    return await runInterpretDriver(targets, checkPublishedDigest(options.registry, expected), {
+      env: plan.to,
+      componentOutputs: options.componentOutputs ?? {},
+      ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+      ...(options.gates ? { gates: options.gates } : {}),
+      ...(options.now ? { now: options.now } : {}),
+    });
+  } catch (err) {
+    if (err instanceof DriverRunFailure) return err.result;
+    throw err;
+  }
+}
+
+/** Who approved the last gate a component passed in this run, if any. */
+export function gateApprover(result: DriverComponentResult | undefined): string | undefined {
+  let approver: string | undefined;
+  for (const record of result?.records ?? []) {
+    if (record.approval) approver = record.approval.resolvedBy;
+  }
+  return approver;
+}
+
+/** What a promote or rollback knows about its own run, for the records it writes. */
+export interface DeployRunInfo {
+  runId: string;
+  runOrigin?: RunOrigin;
+  actor: string;
+  timestamp: string;
+  approver?: string;
+}
+
+/** The fields a promote and a rollback record share: the artifact is the earlier release's own. */
+function redeployRecord(item: PromotionItem, env: string, run: DeployRunInfo): ReleaseRecordInput {
+  const { source } = item;
+  return {
+    component: item.component,
+    env,
+    digest: item.digest,
+    gitSha: source.gitSha,
+    runId: run.runId,
+    ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}),
+    timestamp: run.timestamp,
+    actor: run.actor,
+    ...(run.approver ? { approver: run.approver } : {}),
+    ...(source.manifestDigest ? { manifestDigest: source.manifestDigest } : {}),
+    ...(source.inputDigest ? { inputDigest: source.inputDigest } : {}),
+  };
+}
+
+/** Name an earlier record the way `promotedFrom` and `restores` do. */
+function refTo(record: ReleaseRecord) {
+  return { env: record.env, runId: record.runId, timestamp: record.timestamp };
+}
+
+/**
+ * The release record a successful promotion appends to the target ledger.
+ * The digest, git sha and archive identities are the source release's own,
+ * since the artifact is the one built there; `promotedFrom` names that
+ * release.
+ */
+export function promotionRecord(item: PromotionItem, to: string, run: DeployRunInfo): ReleaseRecordInput {
+  return { ...redeployRecord(item, to, run), promotedFrom: refTo(item.source) };
+}
+
+/**
+ * The release record a successful rollback appends. Like a promotion's, it
+ * carries the restored release's artifact identities; `restores` names that
+ * release.
+ */
+export function rollbackRecord(item: PromotionItem, env: string, run: DeployRunInfo): ReleaseRecordInput {
+  return { ...redeployRecord(item, env, run), restores: refTo(item.source) };
+}

package/src/components/unbound-gate-approval.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The warning a release ahead of environment- and plan-bound component gate
+ * approvals (chant #2574). The gate decision itself must not change.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CapabilityRegistry } from "./capability";
+import { runComponentDeploy, type DriverComponent } from "./driver";
+import { memoryGateLedgerPort } from "../op/gate";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { resetUnboundGateApprovalWarnings, warnOnUnboundComponentApproval } from "./unbound-gate-approval";
+
+const NOW = "2026-09-05T12:00:00.000Z";
+
+const component: DriverComponent = {
+  name: "search-service",
+  deploy: [{ phase: "Apply", steps: [{ kind: "gate", gate: "approve-prod" }, { kind: "ecs-deploy" }] }],
+};
+
+const pending: PendingGateRecord = {
+  version: 1, kind: "pending", op: "search-service", gate: "approve-prod",
+  timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z",
+};
+
+const unbound: GateResolutionRecord = {
+  version: 1, op: "search-service", gate: "approve-prod",
+  resolvedBy: "alex", timestamp: "2026-09-05T11:00:00.000Z",
+};
+
+function registry(calls: string[]): CapabilityRegistry {
+  const r = new CapabilityRegistry();
+  r.register({ kind: "ecs-deploy", async run() { calls.push("ecs-deploy"); return { ok: true }; } });
+  return r;
+}
+
+describe("warnOnUnboundComponentApproval (#2574)", () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    resetUnboundGateApprovalWarnings();
+    warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+  afterEach(() => warn.mockRestore());
+
+  it("warns once per component and gate when the approval records no plan", () => {
+    expect(warnOnUnboundComponentApproval("search-service", "approve-prod", "prod", unbound)).toBe(true);
+    expect(warnOnUnboundComponentApproval("search-service", "approve-prod", "staging", unbound)).toBe(false);
+    expect(warnOnUnboundComponentApproval("orders-table", "approve-prod", "prod", { ...unbound, op: "orders-table" })).toBe(true);
+    expect(warn).toHaveBeenCalledTimes(2);
+    const line = String(warn.mock.calls[0]![0]);
+    expect(line).toContain('gate "approve-prod" on component "search-service" passed in "prod"');
+    expect(line).toContain("From the next chant release");
+    expect(line).toContain("chant approve search-service approve-prod");
+    expect(line).toContain("issues/2574");
+  });
+
+  it("says nothing for an approval that records a plan", () => {
+    const bound = { ...unbound, planDigest: `sha256:${"a".repeat(64)}` };
+    expect(warnOnUnboundComponentApproval("search-service", "approve-prod", "prod", bound)).toBe(false);
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("a deploy passes the gate exactly as before, and warns", async () => {
+    const calls: string[] = [];
+    const result = await runComponentDeploy(
+      component, { env: "prod", component: "search-service" }, registry(calls), {}, undefined,
+      { port: memoryGateLedgerPort({ pending: [pending], resolutions: [unbound] }), now: NOW },
+    );
+    expect(result.status).toBe("ok");
+    expect(calls).toEqual(["ecs-deploy"]);
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("a gated deploy does not warn", async () => {
+    const calls: string[] = [];
+    const result = await runComponentDeploy(
+      component, { env: "prod", component: "search-service" }, registry(calls), {}, undefined,
+      { port: memoryGateLedgerPort(), now: NOW },
+    );
+    expect(result.status).toBe("gated");
+    expect(warn).not.toHaveBeenCalled();
+  });
+});

package/src/components/unbound-gate-approval.ts

@@ -0,0 +1,51 @@
+/**
+ * The warning a release ahead of environment- and plan-bound component gate
+ * approvals (chant #2574).
+ *
+ * A component gate approval is keyed by the component and the gate name only,
+ * so an approval given for one environment, or for one deploy, can pass the
+ * same gate later on another environment or on a promote or rollback. The
+ * next release binds each approval to the environment and the plan digest it
+ * was given for, the way Op gates bind a plan since #2300, and refuses an
+ * approval that records neither.
+ *
+ * This release only says so. When a component gate passes on an approval that
+ * records no plan, the driver prints one warning per component and gate, per
+ * process. The decision itself is unchanged.
+ */
+
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import { approveCommand } from "../op/gate";
+
+/** `component\0gate` pairs already warned about in this process. */
+const warned = new Set<string>();
+
+/** Forget which gates were warned about. For tests. */
+export function resetUnboundGateApprovalWarnings(): void {
+  warned.clear();
+}
+
+/**
+ * Warn once for `component`'s `gate` when the approval that just passed it in
+ * `env` records no plan. Returns whether a warning was printed.
+ */
+export function warnOnUnboundComponentApproval(
+  component: string,
+  gate: string,
+  env: string,
+  resolution: GateResolutionRecord,
+): boolean {
+  if (resolution.planDigest !== undefined) return false;
+  const key = `${component}\0${gate}`;
+  if (warned.has(key)) return false;
+  warned.add(key);
+  console.warn(
+    `[chant] warning: gate "${gate}" on component "${component}" passed in "${env}" on an approval by ` +
+      `${resolution.resolvedBy} at ${resolution.timestamp} that records no environment and no plan. ` +
+      "From the next chant release, a component gate approval counts only for the environment and plan " +
+      "digest it was given for, and approvals recorded before then are refused. After upgrading, run the " +
+      `deploy again and approve the gate it stops at with \`${approveCommand(component, gate)}\`. ` +
+      "See https://github.com/INTENTIUS/chant/issues/2574",
+  );
+  return true;
+}