@intentius/chant 0.124.41 → 0.124.42

package/src/components/capability-targets.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Resource targeting (#4300): `--target <component>:<address>` narrows a
+ * component's steps, each capability accepts or refuses by name, and the
+ * targets join the plan digest an approval binds.
+ */
+
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, parseComponentTargets, targetRefusal, type CapabilityPlan, type DeployContext } from "./capability";
+import { deployContext, runComponentDeploy, type DriverComponent } from "./driver";
+import { bindTargets, planWaveComponent, targetedPlanDigest } from "./wave-plan";
+import { fanOutGateDigest, runFanOut } from "./fan-out-run";
+import { planFanOut } from "./fan-out";
+import { memoryGateLedgerPort } from "../op/gate";
+
+const component = (name: string, ...kinds: string[]): DriverComponent => ({
+  name,
+  deploy: [{ phase: "Deploy", steps: kinds.map((kind) => ({ kind })) }],
+});
+
+/** A registry with a verb that accepts targets, one that refuses, and one that says nothing. */
+function registry(seen: DeployContext[] = []): CapabilityRegistry {
+  const r = new CapabilityRegistry();
+  r.register({
+    kind: "narrow",
+    targets: "accept",
+    async plan(ctx: DeployContext): Promise<CapabilityPlan> {
+      seen.push(ctx);
+      return { member: ctx.component, planDigest: "sha256:base", ...(ctx.targets ? { targets: ctx.targets } : {}) };
+    },
+    async run(ctx: DeployContext) {
+      seen.push(ctx);
+      return { ok: true };
+    },
+  } as never);
+  r.register({
+    kind: "whole",
+    targets: { refuse: "whole applies everything" },
+    async plan(ctx: DeployContext): Promise<CapabilityPlan> {
+      return { member: ctx.component, planDigest: "sha256:whole" };
+    },
+    async run() {
+      return { ok: true };
+    },
+  } as never);
+  r.register({
+    kind: "silent",
+    async run() {
+      return { ok: true };
+    },
+  } as never);
+  return r;
+}
+
+describe("parseComponentTargets", () => {
+  test("groups by component, sorted and unique, splitting at the first colon", () => {
+    expect(parseComponentTargets(["net:aws_vpc.main", "net:aws_subnet.a", "net:aws_vpc.main", "app:Deployment/prod/web", "net:x[\"a:b\"]"])).toEqual({
+      app: ["Deployment/prod/web"],
+      net: ["aws_subnet.a", "aws_vpc.main", 'x["a:b"]'],
+    });
+  });
+
+  test("refuses a value with no component or no address, and an unknown component", () => {
+    expect(() => parseComponentTargets([":aws_vpc.main"])).toThrow(/--target <component>:<address>/);
+    expect(() => parseComponentTargets(["net:"])).toThrow(/--target <component>:<address>/);
+    expect(() => parseComponentTargets(["nope:a"], new Set(["net"]))).toThrow(/no component is named nope/);
+  });
+});
+
+describe("targetRefusal", () => {
+  test("accept, refuse with its reason, and unset refusing by name", () => {
+    expect(targetRefusal({ kind: "a", targets: "accept" })).toBeUndefined();
+    expect(targetRefusal({ kind: "b", targets: { refuse: "no" } })).toBe("no");
+    expect(targetRefusal({ kind: "c" })).toMatch(/^c does not say/);
+  });
+});
+
+describe("deployContext", () => {
+  test("gives a component its own targets, sorted, and none to another", () => {
+    const options = { env: "dev", targets: { net: ["b", "a", "a"] } };
+    expect(deployContext(options, "net").targets).toEqual(["a", "b"]);
+    expect(deployContext(options, "app").targets).toBeUndefined();
+  });
+});
+
+describe("planning a targeted component", () => {
+  test("binds the targets into the member's digest and its change-set part", async () => {
+    const seen: DeployContext[] = [];
+    const ctx = deployContext({ env: "dev", targets: { net: ["aws_vpc.main"] } }, "net");
+    const planned = await planWaveComponent(component("net", "narrow"), registry(seen), ctx, {});
+    expect("error" in planned).toBe(false);
+    if ("error" in planned) return;
+    expect(seen[0]!.targets).toEqual(["aws_vpc.main"]);
+    const digest = targetedPlanDigest("sha256:base", ["aws_vpc.main"]);
+    expect(planned.members).toEqual([{ member: "net", planDigest: digest }]);
+    expect(planned.parts[0]!.member.planDigest).toBe(digest);
+  });
+
+  test("another set of targets is another digest, and none is the plan's own", async () => {
+    const a = targetedPlanDigest("sha256:base", ["x"]);
+    const b = targetedPlanDigest("sha256:base", ["y"]);
+    expect(a).not.toBe(b);
+    expect(targetedPlanDigest("sha256:base", ["y", "x"])).toBe(targetedPlanDigest("sha256:base", ["x", "y"]));
+    const untargeted = await planWaveComponent(component("net", "narrow"), registry(), deployContext({ env: "dev" }, "net"), {});
+    expect("error" in untargeted ? undefined : untargeted.members[0]!.planDigest).toBe("sha256:base");
+  });
+
+  test("a verb that refuses names itself, and so does one that says nothing", async () => {
+    const ctx = deployContext({ env: "dev", targets: { net: ["a"] } }, "net");
+    const refused = await planWaveComponent(component("net", "narrow", "whole"), registry(), ctx, {});
+    expect(refused).toEqual({ component: "net", error: 'component "net": whole refuses targets: whole applies everything' });
+    const silent = await planWaveComponent(component("net", "silent"), registry(), ctx, {});
+    expect("error" in silent && silent.error).toMatch(/silent refuses targets: silent does not say/);
+  });
+
+  test("a plan that does not give the targets back refuses", () => {
+    const ctx: DeployContext = { env: "dev", component: "net", targets: ["a", "b"] };
+    expect(() => bindTargets("narrow", ctx, { member: "net", planDigest: "d" })).toThrow(/names no targets/);
+    expect(() => bindTargets("narrow", ctx, { member: "net", planDigest: "d", targets: ["a"] })).toThrow(/names a$/);
+  });
+});
+
+describe("running a targeted component", () => {
+  test("refuses before any step runs when one verb can't narrow", async () => {
+    const seen: DeployContext[] = [];
+    const ctx = deployContext({ env: "dev", targets: { net: ["a"] } }, "net");
+    const result = await runComponentDeploy(component("net", "narrow", "whole"), ctx, registry(seen), {}, undefined, { port: memoryGateLedgerPort() });
+    expect(result.status).toBe("fail");
+    expect(result.records[0]).toMatchObject({ phase: "Targets", kind: "whole", status: "fail" });
+    expect(seen).toEqual([]);
+  });
+
+  test("hands the targets to a verb that accepts them", async () => {
+    const seen: DeployContext[] = [];
+    const ctx = deployContext({ env: "dev", targets: { net: ["a"] } }, "net");
+    const result = await runComponentDeploy(component("net", "narrow"), ctx, registry(seen), {}, undefined, { port: memoryGateLedgerPort() });
+    expect(result.status).toBe("ok");
+    expect(seen[0]!.targets).toEqual(["a"]);
+  });
+});
+
+describe("a gate over the whole set", () => {
+  test("binds the targets, so the untargeted approval does not cover a targeted run", async () => {
+    expect(fanOutGateDigest("sha256:set", undefined)).toBe("sha256:set");
+    expect(fanOutGateDigest("sha256:set", { net: [] })).toBe("sha256:set");
+    const narrowed = fanOutGateDigest("sha256:set", { net: ["a"] });
+    expect(narrowed).not.toBe("sha256:set");
+    expect(fanOutGateDigest("sha256:set", { net: ["b"] })).not.toBe(narrowed);
+
+    const estate = [component("net", "narrow")];
+    const plan = planFanOut({ components: estate, changed: ["net"] });
+    const gates = memoryGateLedgerPort();
+    const result = await runFanOut(plan, estate, registry(), {
+      env: "dev",
+      gates,
+      now: "2026-01-01T00:00:00Z",
+      gate: { op: "fan-out", gate: "set" },
+      targets: { net: ["a"] },
+    });
+    expect(result.status).toBe("gated");
+    expect(result.gate?.planDigest).toBe(fanOutGateDigest(plan.digest, { net: ["a"] }));
+  });
+});

package/src/components/capability.ts

@@ -72,6 +72,14 @@ export interface DeployContext {
    * against missing values.
    */
   unresolvedInputs?: string[];
+  /**
+   * The addresses this component's steps narrow to (#4300), from
+   * `--target <component>:<address>`, sorted. A step's `plan` plans only
+   * these, and its `run` applies only these. Every capability step of the
+   * component must accept targets ({@link Capability.targets}), or the
+   * component refuses before anything plans or runs. Absent: the whole step.
+   */
+  targets?: string[];
 }
 
 /**
@@ -101,6 +109,14 @@ export interface CapabilityPlan {
    * applies.
    */
   outputs?: PlannedOutputs;
+  /**
+   * The targets this plan narrowed to (#4300), sorted. A plan made with
+   * `DeployContext.targets` gives them back, which says it planned only
+   * those. Planning binds them into the member's digest
+   * ({@link targetedPlanDigest} in ./wave-plan.ts), so an approval of a
+   * targeted plan covers that plan and no other.
+   */
+  targets?: string[];
 }
 
 /**
@@ -176,11 +192,44 @@ export interface Capability<In = unknown, Out = unknown> {
    * compensation gap. See ../lint/rules/comp/comp003-mutating-no-rollback.ts.
    */
   readonly rollbackPolicy?: RollbackPolicy;
+  /**
+   * Whether this verb narrows to `DeployContext.targets` (#4300). `"accept"`:
+   * its `plan` and `run` act on the targets alone, and its plan gives them
+   * back in {@link CapabilityPlan.targets}. `{ refuse }`: it can't, and says
+   * why. Unset refuses too, with a reason that names the verb.
+   */
+  readonly targets?: TargetSupport;
 }
 
 /** A capability's relationship to rollback — see `Capability.rollbackPolicy`. */
 export type RollbackPolicy = "native" | "none-by-design" | "needs-opt-out";
 
+/** Whether a capability accepts `DeployContext.targets` (#4300). See `Capability.targets`. */
+export type TargetSupport = "accept" | { refuse: string };
+
+/**
+ * A component was asked to narrow to targets (#4300) and one of its steps'
+ * capabilities refuses them. Nothing in the component plans or runs.
+ */
+export class TargetsRefusedError extends Error {
+  constructor(
+    readonly component: string,
+    readonly kind: string,
+    readonly reason: string,
+  ) {
+    super(`component "${component}": ${kind} refuses targets: ${reason}`);
+    this.name = "TargetsRefusedError";
+  }
+}
+
+/** Why `capability` refuses targets, or `undefined` when it accepts them (#4300). */
+export function targetRefusal(capability: Pick<Capability<never, unknown>, "kind" | "targets">): string | undefined {
+  const t = capability.targets;
+  if (t === "accept") return undefined;
+  if (t && typeof t === "object" && typeof t.refuse === "string") return t.refuse;
+  return `${capability.kind} does not say it can narrow to targets`;
+}
+
 /** Extract a capability's `In` type. */
 export type CapabilityInput<C> = C extends Capability<infer In, unknown> ? In : never;
 /** Extract a capability's `Out` type. */
@@ -257,3 +306,25 @@ export class CapabilityRegistry {
     return [...this.capabilities.keys()].sort();
   }
 }
+
+/**
+ * `--target <component>:<address>` values (#4300), grouped by component with
+ * each component's addresses sorted and unique. The address is everything
+ * after the first `:`, so it may hold colons of its own. Throws for a value
+ * with no component or no address, and, given `known`, for a component not
+ * among them.
+ */
+export function parseComponentTargets(values: readonly string[], known?: ReadonlySet<string>): Record<string, string[]> {
+  const out: Record<string, Set<string>> = {};
+  for (const value of values) {
+    const at = value.indexOf(":");
+    const component = at > 0 ? value.slice(0, at).trim() : "";
+    const address = at > 0 ? value.slice(at + 1).trim() : "";
+    if (component === "" || address === "") throw new Error(`--target needs a component and an address: --target <component>:<address>, got "${value}"`);
+    if (known && !known.has(component)) {
+      throw new Error(`--target ${value}: no component is named ${component} (components: ${[...known].sort().join(", ") || "none"})`);
+    }
+    (out[component] ??= new Set()).add(address);
+  }
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)).map(([c, s]) => [c, [...s].sort()]));
+}

package/src/components/cli-support.ts

@@ -390,6 +390,12 @@ export function findComponentGate(component: DriverComponent): { gate: string }
 export interface RunComponentsOptions {
   /** Target environment name, threaded into every capability's `DeployContext.env` (default: "local"). */
   env?: string;
+  /**
+   * The addresses each component's steps narrow to (#4300), by component
+   * (`--target <component>:<address>`). A name the run does not run refuses
+   * the run before anything starts.
+   */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /**
    * chant #1051 — opt-in: discover `*.component.ts` files in a sandboxed
    * child process (`chant run --components <name|all> --sandbox`) instead of
@@ -664,6 +670,12 @@ export async function runComponents(
     return { success: false, selected: [], error: resolved.error };
   }
   const targets = resolved.targets;
+  const narrowed = options.targets ?? {};
+  const outside = Object.keys(narrowed).filter((name) => !targets.some((c) => c.name === name));
+  if (outside.length > 0) {
+    return { success: false, selected: [], error: `--target names ${outside.join(", ")}, which this run does not run` };
+  }
+  const targeted = Object.keys(narrowed).length > 0 ? { targets: narrowed } : {};
 
   // (#629) Resolve `chant.config.ts`'s `sbom`/`signing`/`vulnPolicy` sections
   // and fill their defaults into every recognized step (`generate-sbom`,
@@ -712,6 +724,7 @@ export async function runComponents(
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
         releaseIdentity,
+        ...targeted,
         componentOutputs: seedOutputs,
         ...(emit ? { onRunEvent: emit } : {}),
         ...(gates ? { gates } : {}),
@@ -755,7 +768,7 @@ export async function runComponents(
     emit?.({ type: "component-start", wave: 1, component: componentName });
     const componentResult = await runComponentDeploy(
       resolvedTargets[0],
-      deployContext({ env, releaseIdentity }, componentName),
+      deployContext({ env, releaseIdentity, ...targeted }, componentName),
       registry,
       componentOutputs,
       undefined,

package/src/components/driver.ts

@@ -55,7 +55,7 @@ import { componentPlanDigest } from "./gate-plan";
 import { componentDeployInputs } from "./deploy-inputs";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
-import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
+import { isPlanMovedError, PLAN_MOVED_EXIT_CODE, TargetsRefusedError, targetRefusal } from "./capability";
 import { isPromotedArtifact } from "./auto-release";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent } from "./run-progress";
@@ -889,6 +889,18 @@ export async function runComponentDeploy(
   onRunEvent?: RunEventSink,
 ): Promise<DriverComponentResult> {
   const emit = joinRunEventSinks(onRunEvent, progressSinkOf(onProgress));
+  // #4300: a component narrowed to targets runs only when every step can narrow.
+  try {
+    assertTargetsAccepted(component, registry, ctx);
+  } catch (err) {
+    if (!(err instanceof TargetsRefusedError)) throw err;
+    return {
+      component: component.name,
+      ok: false,
+      status: "fail",
+      records: [{ component: component.name, phase: "Targets", kind: err.kind, status: "fail", durationMs: 0, error: err.message }],
+    };
+  }
   // Each component tracks its own release: a digest one component promoted never stamps another's deploy.
   if (ctx.release) ctx = { ...ctx, release: { ...ctx.release } };
   const phaseOutputs: Record<string, Record<string, unknown>> = {};
@@ -908,6 +920,7 @@ export async function runComponentDeploy(
         component,
         ...(ctx.vars ? { vars: ctx.vars } : {}),
         ...(release !== undefined ? { release } : {}),
+        ...(ctx.targets ? { targets: ctx.targets } : {}),
         // #4155: the files the steps deploy from, read where the steps read
         // them. Only a gate reads the digest, so a run with none skips the hashing.
         ...(hasGateStep(component) ? { inputs: componentDeployInputs(component.deploy, process.cwd()).inputs } : {}),
@@ -1121,6 +1134,8 @@ export interface InterpretRunOptions {
    * step promotes an artifact. Absent: no deploy step sees a release.
    */
   releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
+  /** The addresses each component narrows to (#4300), by component: its `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
 }
 
 /**
@@ -1144,11 +1159,47 @@ export interface InterpretRunOptions {
  */
 /** A component's `DeployContext` for a run: its env, vars and, when the caller knows it, its release. */
 export function deployContext(
-  options: { env: string; vars?: Record<string, unknown>; releaseIdentity?: (component: string) => ReleaseIdentity | undefined },
+  options: {
+    env: string;
+    vars?: Record<string, unknown>;
+    releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
+    targets?: Readonly<Record<string, readonly string[]>>;
+  },
   component: string,
 ): DeployContext {
   const release = options.releaseIdentity?.(component);
-  return { env: options.env, component, ...(options.vars ? { vars: options.vars } : {}), ...(release ? { release: { ...release } } : {}) };
+  const targets = options.targets?.[component];
+  return {
+    env: options.env,
+    component,
+    ...(options.vars ? { vars: options.vars } : {}),
+    ...(release ? { release: { ...release } } : {}),
+    ...(targets && targets.length > 0 ? { targets: [...new Set(targets)].sort() } : {}),
+  };
+}
+
+/**
+ * Refuse a component asked to narrow to `ctx.targets` (#4300) when one of its
+ * capability steps can't: throws {@link TargetsRefusedError} naming the first
+ * such verb, in composition order. A step whose kind is not registered
+ * refuses too. Does nothing when `ctx.targets` is absent.
+ */
+export function assertTargetsAccepted(component: DriverComponent, registry: CapabilityRegistry, ctx: DeployContext): void {
+  if (!ctx.targets || ctx.targets.length === 0) return;
+  const walk = (steps: DriverPhase["steps"]): void => {
+    for (const step of steps) {
+      if (typeof (step as DriverPhase).phase === "string" && Array.isArray((step as DriverPhase).steps)) {
+        walk((step as DriverPhase).steps);
+        continue;
+      }
+      const kind = (step as { kind?: unknown }).kind;
+      if (kind === "gate" || typeof kind !== "string") continue;
+      if (!registry.has(kind)) throw new TargetsRefusedError(component.name, kind, `no capability is registered for ${kind}`);
+      const reason = targetRefusal(registry.resolve(kind));
+      if (reason !== undefined) throw new TargetsRefusedError(component.name, kind, reason);
+    }
+  };
+  for (const phase of component.deploy) walk(phase.steps);
 }
 
 export async function runInterpretDriver(

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

@@ -54,6 +54,7 @@ import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
+import { computePlanDigest } from "../lifecycle/plan-digest";
 import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
 /** The sink a fan-out emits to: run events, and the older stream through them. */
@@ -187,6 +188,8 @@ export interface FanOutGate {
 export interface FanOutRunOptions {
   env: string;
   vars?: Record<string, unknown>;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /** Outputs of components this run is not running: the ones the plan lists in `seeds`. */
   componentOutputs?: Record<string, Record<string, unknown>>;
   onProgress?: (event: RunProgressEvent) => void;
@@ -319,7 +322,7 @@ export async function runFanOut(
       evaluateGate(gates.port, {
         op: gate.op,
         gate: gate.gate,
-        planDigest: active.digest,
+        planDigest: fanOutGateDigest(active.digest, options.targets),
         ...(gate.description ? { description: gate.description } : {}),
         ...(gate.timeout ? { timeout: gate.timeout } : {}),
         ...(options.now ? { now: options.now } : {}),
@@ -455,6 +458,21 @@ export async function runFanOut(
   };
 }
 
+/**
+ * The digest a gate over the whole set binds: the derivation's digest, and,
+ * when the run narrows components to targets (#4300), the digest over it and
+ * every component's sorted targets. An approval of the whole set then covers
+ * no narrowed run, and one narrowed run's approval covers no other.
+ */
+export function fanOutGateDigest(digest: string, targets: FanOutRunOptions["targets"]): string {
+  const narrowed = Object.entries(targets ?? {})
+    .filter(([, t]) => t.length > 0)
+    .map(([component, t]) => [component, [...new Set(t)].sort()] as const)
+    .sort(([a], [b]) => a.localeCompare(b));
+  if (narrowed.length === 0) return digest;
+  return computePlanDigest("fan-out-targets", { plan: digest, targets: Object.fromEntries(narrowed) });
+}
+
 /** The run's `deployContext`, with the carried state and the carry callback (#3459) when the caller gave them. */
 function fanOutContext(options: FanOutRunOptions, component: string): DeployContext {
   return {

package/src/components/gate-plan.ts

@@ -45,6 +45,8 @@ export interface ComponentGatePlan {
   release?: string;
   /** What the steps deploy from (`componentDeployInputs`), when the caller read it. */
   inputs?: readonly DeployInputDigest[];
+  /** The addresses the component narrows to (#4300), sorted. A gate's approval then covers that narrowing alone. */
+  targets?: readonly string[];
 }
 
 /** The plan digest a component gate records and approves. */
@@ -58,5 +60,6 @@ export function componentPlanDigest(plan: ComponentGatePlan): string {
     vars: plan.vars ?? null,
     release: plan.release ?? null,
     ...(plan.inputs && plan.inputs.length > 0 ? { inputs: plan.inputs } : {}),
+    ...(plan.targets && plan.targets.length > 0 ? { targets: [...plan.targets].sort() } : {}),
   });
 }

package/src/components/pr-pipeline.ts

@@ -148,6 +148,16 @@ export interface PrLoopPipelineOptions {
    * false, so a merge deploys nothing. `waveGate` needs it.
    */
   applyOnMerge?: boolean;
+  /**
+   * Apply an open pull request before it merges (#4301, ws-106): the apply
+   * job runs `pr-apply --before-merge` at the pull request's head, started
+   * by a `/chant apply` comment on GitHub and Forgejo, or on GitLab by a
+   * pipeline of the target branch with `CHANT_APPLY_PR` set. A merge still
+   * records. `pr-apply` refuses unless the declaration at base sets
+   * `ci.workflow: "apply-before-merge"`. It takes neither `applyOnMerge`,
+   * `waveGate` nor `build`.
+   */
+  applyBeforeMerge?: boolean;
   /**
    * Stream each job's run events (#4007): `--events-json` on both commands,
    * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
@@ -259,6 +269,10 @@ export function prLoopBuildLines(env: string, options: PrLoopPipelineOptions = {
  */
 export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}, member?: string): PrLoopJob[] {
   const gate = options.gate ?? PR_APPLY_GATE;
+  const early = options.applyBeforeMerge === true;
+  if (early && options.applyOnMerge) throw new Error("--apply-before-merge applies an open pull request and a merge records, so it takes no --apply-on-merge; pass one of them");
+  if (early && options.waveGate) throw new Error("--apply-before-merge applies the pull request's plan in one job, so it takes no --wave-gate");
+  if (early && (options.build || options.buildCommand)) throw new Error("--apply-before-merge runs no build before its requires checks, so it takes no --pr-build or --pr-build-command yet");
   const common = [
     "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
     ...(member ? ["--member", member] : []),
@@ -275,7 +289,8 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   // #4156: the flags `chant ci run` rebuilds `command` from. It finds the member from the directory it runs in.
   const ciRun = (job: PrLoopJob["jobName"]): string[] => [
     "chant", "ci", "run", job, "--in-place", ...(job === "plan" ? ["--no-push"] : []),
-    ...(job === "apply" ? [] : ["--base", '"$BASE_SHA"']), ...(job === "plan" ? ["--pr", '"$PR_NUMBER"'] : []),
+    ...(job === "apply" && !early ? [] : ["--base", '"$BASE_SHA"']), ...(job === "plan" || (job === "apply" && early) ? ["--pr", '"$PR_NUMBER"'] : []),
+    ...(job === "apply" && early ? ["--apply-before-merge"] : []),
     "--env", env, "--gate", gate, "--forge", forge,
     ...(job !== "record" && options.waveGate ? ["--wave-gate", options.waveGate] : []),
     ...(job !== "plan" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
@@ -292,6 +307,37 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
     : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...withoutForgeTokens(jobEnv) };
   const greenBranch = github ? JSON.stringify(options.branch ?? "main") : options.branch ? JSON.stringify(options.branch) : "$CI_DEFAULT_BRANCH";
   const applyEnv = github ? { BASE_SHA: "${{ github.event.before }}", ...jobEnv } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA", ...jobEnv };
+  // #4301: the apply before merge runs in a job of the target branch, whose commit is the base, at the pull request's head.
+  const earlyEnv = github
+    ? { BASE_SHA: "${{ github.sha }}", PR_NUMBER: "${{ github.event.issue.number }}", ...jobEnv }
+    : { BASE_SHA: "$CI_COMMIT_SHA", PR_NUMBER: `$${GITLAB_APPLY_PR_VAR}`, ...jobEnv };
+  const greenApply: PrLoopJob = {
+    // #4168 step 9: the apply applies the newest green commit, measured from the one applied before it.
+    jobName: "apply",
+    command: [
+      "chant", "components", "pr-apply", "--green", ...common,
+      ...(options.requireReview === true ? ["--require-review"] : []),
+      ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
+      "--resume", PR_APPLY_RECORD,
+    ].join(" "),
+    env: jobEnv,
+    checkout: [greenCheckout(greenBranch)],
+    greenBranch,
+    ...build,
+    run: { command: ciRun("apply").join(" "), env: runEnv(jobEnv) },
+  };
+  const earlyApply: PrLoopJob = {
+    // #4301: the requires checks run inside pr-apply, before any of the head's code loads.
+    jobName: "apply",
+    command: [
+      "chant", "components", "pr-apply", "--before-merge", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common,
+      ...(options.requireReview === true ? ["--require-review"] : []),
+      "--resume", PR_APPLY_RECORD,
+    ].join(" "),
+    env: earlyEnv,
+    checkout: [pullRequestCheckout(forge)],
+    run: { command: ciRun("apply").join(" "), env: runEnv(earlyEnv) },
+  };
   return [
     {
       jobName: "plan",
@@ -301,21 +347,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       ...build,
       run: { command: ciRun("plan").join(" "), env: runEnv(planEnv) },
     },
-    {
-      // #4168 step 9: the apply applies the newest green commit, measured from the one applied before it.
-      jobName: "apply",
-      command: [
-        "chant", "components", "pr-apply", "--green", ...common,
-        ...(options.requireReview === true ? ["--require-review"] : []),
-        ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
-        "--resume", PR_APPLY_RECORD,
-      ].join(" "),
-      env: jobEnv,
-      checkout: [greenCheckout(greenBranch)],
-      greenBranch,
-      ...build,
-      run: { command: ciRun("apply").join(" "), env: runEnv(jobEnv) },
-    },
+    early ? earlyApply : greenApply,
     {
       jobName: "record",
       command: ["chant", "components", "pr-record", "--base", '"$BASE_SHA"', ...common].join(" "),
@@ -460,6 +492,22 @@ function pushBaseFallback(target: string, commit: string, diffBase?: string): st
   );
 }
 
+/** The GitLab variable a person sets on a pipeline of the target branch to apply a merge request before it merges (#4301). */
+export const GITLAB_APPLY_PR_VAR = "CHANT_APPLY_PR";
+
+/** The comment that starts the apply before merge on GitHub and Forgejo (#4301). */
+export const APPLY_COMMENT = "/chant apply";
+
+/**
+ * The line that checks out pull request `$PR_NUMBER`'s head (#4301) in a job
+ * of the target branch: the forge's `refs/pull/<n>/head`, or GitLab's
+ * `refs/merge-requests/<n>/head`. A number that is not one fails the job.
+ */
+export function pullRequestCheckout(forge: ForgeKind): string {
+  const ref = forge === "gitlab" ? 'refs/merge-requests/$PR_NUMBER/head' : 'refs/pull/$PR_NUMBER/head';
+  return `echo "$PR_NUMBER" | grep -Eq '^[0-9]+$' && git fetch --quiet origin "+${ref}:refs/remotes/origin/chant-apply/$PR_NUMBER" && git checkout --quiet --detach "refs/remotes/origin/chant-apply/$PR_NUMBER"`;
+}
+
 /**
  * The line that checks out the newest green commit of `branch` (#4168 step
  * 9), after fetching the branch and its tags, for the apply job. `chant ci

package/src/components/pr-run.ts

@@ -110,6 +110,8 @@ export interface PrPlanSetOptions {
   vars?: Record<string, unknown>;
   /** Outputs supplied by the caller (`--seed-outputs`). They win over outputs read here. */
   seededOutputs?: Record<string, Record<string, unknown>>;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /**
    * Where the planning's events go (#4041): a `plan` phase with no
    * component, and in it one `plan` step per component, started as its wave
@@ -384,6 +386,8 @@ export interface PrApplyOptions {
   vars?: Record<string, unknown>;
   /** The set {@link planPrSet} planned and the gate approved, or {@link resumePrSet}'s set. */
   set: PrPlanSet;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   onProgress?: (event: RunProgressEvent) => void;
   /** Where the apply's events go (#4041): the fan-out's run events. */
   onRunEvent?: RunEventSink;
@@ -467,6 +471,7 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
       env: options.env,
       ...(options.vars ? { vars: options.vars } : {}),
       plans,
+      ...(options.targets ? { targets: options.targets } : {}),
       componentOutputs: outputs,
       hold: (name, now) => heldReason(byName.get(name)!, read, now, inChange),
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
@@ -491,6 +496,7 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
       env: options.env,
       ...(options.vars ? { vars: options.vars } : {}),
       seededOutputs: run.componentOutputs,
+      ...(options.targets ? { targets: options.targets } : {}),
     });
     for (const name of plan.order) roundOf.set(name, { round, set });
     const record = (status: PrRound["status"], approval: PrApproval, message?: string): void => {
@@ -626,6 +632,8 @@ export interface PrResumeOptions {
   env: string;
   vars?: Record<string, unknown>;
   seededOutputs?: Record<string, Record<string, unknown>>;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /** The approved set, from the attempt record. */
   record: PrApplyRecord;
   /** Components an earlier attempt applied. */
@@ -677,6 +685,7 @@ export async function resumePrSet(options: PrResumeOptions): Promise<PrResume> {
     env: options.env,
     ...(options.vars ? { vars: options.vars } : {}),
     seededOutputs: { ...(options.seededOutputs ?? {}), ...options.record.planOutputs },
+    ...(options.targets ? { targets: options.targets } : {}),
   });
   const reasons = fresh.doc.members
     .map((m) => planCoveredBy(options.record.changeSet, fresh.doc, m.member))