@intentius/chant 0.102.0 → 0.104.1

package/src/components/fan-out-waves.test.ts

@@ -0,0 +1,375 @@
+/**
+ * Gated waves on a fan-out (#3049): one gate per wave, each bound to the
+ * wave's set digest, each wave planned once the waves before it applied.
+ *
+ * The capability here stands in for `terraform-apply`: `plan` returns the
+ * root and a digest over what it would write (its own `version` and every
+ * input), `run` applies, records what it applied and exposes an output.
+ */
+
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, type DeployContext } from "./capability";
+import { memoryGateLedgerPort } from "../op/gate";
+import { planFanOut } from "./fan-out";
+import { EarlierWaveNotAppliedError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import type { DriverComponent } from "./driver";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+
+interface RootInput {
+  root: string;
+  version?: string;
+  vars?: Record<string, unknown>;
+}
+
+/** A component deploying one root. `vars` may wire another root's output. */
+const root = (name: string, dependsOn?: string[], vars?: Record<string, unknown>): DriverComponent => ({
+  name,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-root", root: name, ...(vars ? { vars } : {}) }] }],
+  ...(dependsOn ? { dependsOn } : {}),
+});
+
+/** net → a, b; app reads a's output. */
+const ESTATE: DriverComponent[] = [
+  root("net"),
+  root("a", ["net"]),
+  root("b", ["net"]),
+  root("app", ["a"], { upstream: { stackOutput: { stack: "a", name: "id" } } }),
+];
+
+interface World {
+  registry: CapabilityRegistry;
+  /** Roots applied, in order. */
+  applied: string[];
+  /** Each plan call: the root and the inputs it planned with. */
+  planned: Array<{ root: string; vars?: Record<string, unknown> }>;
+  /** Each apply: whether it applied the wave's own plan. */
+  fromPlan: Record<string, boolean>;
+  /** What each root would write: change one to "change a root". */
+  versions: Record<string, string>;
+  failing: Set<string>;
+}
+
+function world(): World {
+  const w: World = {
+    registry: new CapabilityRegistry(),
+    applied: [],
+    planned: [],
+    fromPlan: {},
+    versions: {},
+    failing: new Set(),
+  };
+  const digestOf = (input: RootInput) =>
+    computePlanDigest("fake-root", { root: input.root, version: w.versions[input.root] ?? "v1", vars: input.vars ?? null });
+  w.registry.register({
+    kind: "fake-root",
+    async plan(_ctx: DeployContext, input: RootInput) {
+      w.planned.push({ root: input.root, ...(input.vars ? { vars: input.vars } : {}) });
+      const planDigest = digestOf(input);
+      return { member: input.root, planDigest, artifact: { planDigest } };
+    },
+    async run(ctx: DeployContext, input: RootInput) {
+      w.fromPlan[input.root] = ctx.plans?.[input.root] !== undefined;
+      if (w.failing.has(input.root)) throw new Error(`${input.root} failed`);
+      w.applied.push(input.root);
+      return { outputs: { id: `${input.root}-id-${w.versions[input.root] ?? "v1"}` } };
+    },
+  } as never);
+  return w;
+}
+
+const NOW = "2026-10-03T00:00:00Z";
+const LATER = "2026-10-03T01:00:00Z";
+
+/** A ledger that has seen `pending` and then the approvals in `resolutions`, as `chant approve` writes them. */
+function ledger(pending: PendingGateRecord[] = [], resolutions: Array<Partial<GateResolutionRecord>> = []) {
+  return memoryGateLedgerPort({
+    pending,
+    resolutions: resolutions.map((r) => ({
+      version: 1 as const,
+      kind: "resolution" as const,
+      op: "fan-out",
+      gate: "release-wave-1",
+      resolvedBy: "ana",
+      timestamp: LATER,
+      ...r,
+    })),
+  });
+}
+
+const waveOptions = (gates: ReturnType<typeof memoryGateLedgerPort>, extra: Partial<FanOutRunOptions> = {}): FanOutRunOptions => ({
+  env: "test",
+  gates,
+  now: NOW,
+  waveGate: { op: "fan-out", gate: "release" },
+  ...extra,
+});
+
+describe("binding: each wave's gate names that wave's set digest", () => {
+  test("an unapproved first wave stops the run with its digest pending, and nothing applies", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const gates = ledger();
+
+    const result = await runFanOut(plan, ESTATE, w.registry, waveOptions(gates));
+
+    expect(result.status).toBe("gated");
+    expect(w.applied).toEqual([]);
+    // Only wave 1 was planned: later waves read outputs it has not written.
+    expect(w.planned.map((p) => p.root)).toEqual(["net"]);
+    expect(result.gate?.gate).toBe("release-wave-1");
+    expect(result.gate?.planDigest).toBe(result.waves?.[0]?.digest);
+    expect(result.waves).toMatchObject([{ wave: 1, status: "gated", members: [{ member: "net" }] }]);
+  });
+
+  test("an approval with no digest, or with another wave's, does not let the wave through", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const first = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger()));
+    const pending = [first.gate!];
+
+    const noDigest = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger(pending, [{}])));
+    expect(noDigest.status).toBe("gated");
+
+    const otherWave = "jcs1-sha256:" + "9".repeat(64);
+    const wrong = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger(pending, [{ planDigest: otherWave }])));
+    expect(wrong.status).toBe("gated");
+    expect(wrong.waves?.[0]?.approved).toBe(otherWave);
+
+    // Wave 1's digest approved under wave 2's gate does not answer wave 1 either.
+    const misfiled = await runFanOut(
+      plan,
+      ESTATE,
+      w.registry,
+      waveOptions(ledger(pending, [{ gate: "release-wave-2", planDigest: first.gate!.planDigest! }])),
+    );
+    expect(misfiled.status).toBe("gated");
+    expect(w.applied).toEqual([]);
+  });
+
+  test("approving wave 1's digest applies wave 1, then stops at wave 2 with its own digest", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const first = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger()));
+
+    const result = await runFanOut(
+      plan,
+      ESTATE,
+      w.registry,
+      waveOptions(ledger([first.gate!], [{ planDigest: first.gate!.planDigest! }])),
+    );
+
+    expect(w.applied).toEqual(["net"]);
+    expect(w.fromPlan.net).toBe(true);
+    expect(result.status).toBe("gated");
+    expect(result.completed).toEqual(["net"]);
+    expect(result.gate?.gate).toBe("release-wave-2");
+    expect(result.waves?.map((r) => [r.wave, r.status])).toEqual([[1, "applied"], [2, "gated"]]);
+    expect(result.waves?.[1]?.digest).not.toBe(result.waves?.[0]?.digest);
+  });
+});
+
+describe("changed set: approve wave 1, change a root, re-run", () => {
+  test("the run stops naming the approved digest and the new one, and applies nothing", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const first = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger()));
+    const approved = first.gate!.planDigest!;
+
+    w.versions.net = "v2";
+    const result = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger([first.gate!], [{ planDigest: approved }])));
+
+    expect(result.status).toBe("gated");
+    expect(w.applied).toEqual([]);
+    const wave = result.waves![0]!;
+    expect(wave.approved).toBe(approved);
+    expect(wave.digest).not.toBe(approved);
+    // The new plan is recorded pending, so the next `chant approve` approves what will run.
+    expect(result.gate?.planDigest).toBe(wave.digest);
+  });
+});
+
+/**
+ * A ledger where every pending wave is approved for exactly the digest it was
+ * recorded with: each wave stops once, the next attempt passes it.
+ */
+function approvingLedger() {
+  const gates = memoryGateLedgerPort();
+  return {
+    ...gates,
+    async read() {
+      const { pending } = await gates.read("fan-out");
+      return {
+        pending,
+        resolutions: pending.map((p) => ({
+          version: 1 as const,
+          kind: "resolution" as const,
+          op: p.op,
+          gate: p.gate,
+          resolvedBy: "ana",
+          timestamp: LATER,
+          planDigest: p.planDigest!,
+        })),
+      };
+    },
+  };
+}
+
+/** Re-run until the fan-out stops gating, carrying progress and outputs the way `--resume` does. */
+async function runToEnd(w: World, plan: ReturnType<typeof planFanOut>, components: DriverComponent[]) {
+  const gates = approvingLedger();
+  let outputs: Record<string, Record<string, unknown>> = {};
+  let result;
+  for (let i = 0; i < 8; i++) {
+    result = await runFanOut(plan, components, w.registry, {
+      ...waveOptions(memoryGateLedgerPort()),
+      gates,
+      progress: { completed: [...w.applied] },
+      componentOutputs: outputs,
+    });
+    outputs = result.componentOutputs;
+    if (result.status !== "gated") break;
+  }
+  return result!;
+}
+
+describe("planned at the wave", () => {
+  test("a root that reads an upstream output plans with the value the upstream wave wrote", async () => {
+    const w = world();
+    w.versions.a = "v7";
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+
+    const result = await runToEnd(w, plan, ESTATE);
+
+    expect(result.status).toBe("ok");
+    const appPlans = w.planned.filter((p) => p.root === "app");
+    expect(appPlans.length).toBeGreaterThan(0);
+    expect(appPlans.every((p) => p.vars?.upstream === "a-id-v7")).toBe(true);
+  });
+
+  test("each wave is planned after the wave before it applied, never up front", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const events: string[] = [];
+    const registry = w.registry;
+    const capability = registry.resolve("fake-root") as unknown as {
+      plan: (ctx: DeployContext, input: RootInput) => Promise<unknown>;
+      run: (ctx: DeployContext, input: RootInput) => Promise<unknown>;
+    };
+    const plan0 = capability.plan.bind(capability);
+    const run0 = capability.run.bind(capability);
+    capability.plan = async (ctx, input) => (events.push(`plan ${input.root}`), plan0(ctx, input));
+    capability.run = async (ctx, input) => (events.push(`apply ${input.root}`), run0(ctx, input));
+
+    const result = await runToEnd(w, plan, ESTATE);
+
+    expect(result.status).toBe("ok");
+    expect(w.applied).toEqual(["net", "a", "b", "app"]);
+    const first = (e: string) => events.indexOf(e);
+    expect(first("plan a")).toBeGreaterThan(first("apply net"));
+    expect(first("plan b")).toBeGreaterThan(first("apply net"));
+    expect(first("plan app")).toBeGreaterThan(first("apply a"));
+  });
+});
+
+describe("canary", () => {
+  test("a canary list is wave 1 and is gated first; the remaining waves follow the graph", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"], canary: ["b"] });
+    expect(plan.waves).toEqual([["b"], ["net"], ["a"], ["app"]]);
+
+    const result = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger()));
+    expect(result.gate?.gate).toBe("release-wave-1");
+    expect(result.waves?.[0]?.members.map((m) => m.member)).toEqual(["b"]);
+  });
+});
+
+describe("resume", () => {
+  test("a run stopped at wave 2's gate resumes there and never re-applies wave 1", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const first = await runFanOut(plan, ESTATE, w.registry, waveOptions(ledger()));
+    const second = await runFanOut(
+      plan,
+      ESTATE,
+      w.registry,
+      waveOptions(ledger([first.gate!], [{ planDigest: first.gate!.planDigest! }])),
+    );
+    expect(second.gate?.gate).toBe("release-wave-2");
+    expect(w.applied).toEqual(["net"]);
+
+    const third = await runFanOut(
+      plan,
+      ESTATE,
+      w.registry,
+      waveOptions(
+        ledger([first.gate!, second.gate!], [
+          { planDigest: first.gate!.planDigest! },
+          { gate: "release-wave-2", planDigest: second.gate!.planDigest! },
+        ]),
+        { progress: { completed: second.completed } },
+      ),
+    );
+    // Wave 2 ran; wave 1 did not run again. Wave 3 is next.
+    expect(w.applied).toEqual(["net", "a", "b"]);
+    expect(third.gate?.gate).toBe("release-wave-3");
+    expect(third.waves?.map((r) => r.wave)).toEqual([2, 3]);
+  });
+
+  test("after a failed root, the retry applies only what is left, and its dependents wait for it", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    w.failing.add("a");
+
+    const failed = await runToEnd(w, plan, ESTATE);
+    expect(failed.status).toBe("fail");
+    expect(w.applied).toEqual(["net", "b"]);
+    expect(failed.blocked).toEqual([{ component: "app", reason: "blocked", blockedBy: "a" }]);
+    expect(failed.waves?.find((r) => r.wave === 2)).toMatchObject({ status: "failed", failed: [{ component: "a" }] });
+
+    w.failing.clear();
+    const retried = await runToEnd(w, plan, ESTATE);
+    expect(retried.status).toBe("ok");
+    // net and b did not apply a second time.
+    expect(w.applied).toEqual(["net", "b", "a", "app"]);
+  });
+});
+
+describe("one wave per CI job", () => {
+  test("--wave 2 refuses while wave 1 has work left, and runs only wave 2 once it has applied", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, ESTATE, w.registry, { ...waveOptions(ledger()), waveGate: { op: "fan-out", gate: "release", only: 2 } }),
+    ).rejects.toThrow(EarlierWaveNotAppliedError);
+
+    const result = await runFanOut(plan, ESTATE, w.registry, {
+      ...waveOptions(ledger()),
+      waveGate: { op: "fan-out", gate: "release", only: 2 },
+      progress: { completed: ["net"] },
+    });
+    expect(result.gate?.gate).toBe("release-wave-2");
+    expect(result.waves?.map((r) => r.wave)).toEqual([2]);
+    expect(w.planned.map((p) => p.root).sort()).toEqual(["a", "b"]);
+  });
+});
+
+describe("both modes", () => {
+  test("a run takes one gate over the set or one per wave, not both", async () => {
+    const w = world();
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, ESTATE, w.registry, { ...waveOptions(ledger()), gate: { op: "fan-out", gate: "release" } }),
+    ).rejects.toThrow(/not both/);
+  });
+
+  test("a component with no plannable step is a member under its composition digest", async () => {
+    const w = world();
+    w.registry.register({ kind: "plain", async run() { return {}; } } as never);
+    const estate: DriverComponent[] = [{ name: "svc", deploy: [{ phase: "Deploy", steps: [{ kind: "plain" }] }] }];
+    const plan = planFanOut({ components: estate, changed: ["svc"] });
+    const result = await runFanOut(plan, estate, w.registry, waveOptions(ledger()));
+    expect(result.waves?.[0]?.members.map((m) => m.member)).toEqual(["svc"]);
+    expect(result.waves?.[0]?.members[0]?.planDigest).toMatch(/^jcs1-sha256:/);
+  });
+});

package/src/components/fan-out.ts

@@ -36,6 +36,7 @@
 import { resolveComponentGraph, type DriverComponent } from "./driver";
 import { deployUnits } from "./deploy-units";
 import { computePlanDigest } from "../lifecycle/plan-digest";
+import { layerWaves } from "../gated-waves";
 
 /** Thrown when `changed` or `indeterminate` names a component the project does not have. */
 export class UnknownComponentError extends Error {
@@ -90,6 +91,12 @@ export interface FanOutRequest {
    * the derivation — the selection, the order and the edges it came from.
    */
   inputDigests?: Record<string, string>;
+  /**
+   * Components that form wave 1 whatever the graph order (#3049), so a change
+   * lands on them first. Only selected ones are placed: a canary the change
+   * does not reach has nothing to apply. The remaining waves follow the graph.
+   */
+  canary?: string[];
 }
 
 export interface FanOutPlan {
@@ -137,7 +144,7 @@ function consumersOf(components: DriverComponent[]): Map<string, string[]> {
  * through a fan-out is worse than finding out before it starts.
  */
 export function planFanOut(request: FanOutRequest): FanOutPlan {
-  const { components, changed, indeterminate = [], inputDigests } = request;
+  const { components, changed, indeterminate = [], inputDigests, canary = [] } = request;
 
   // Refuses DependencyCycleError / UnknownDependencyError over the whole graph.
   // Its `order` is deliberately not used: `topoSort` walks in declaration
@@ -169,24 +176,18 @@ export function planFanOut(request: FanOutRequest): FanOutPlan {
   }
 
   // Waves over the selected subgraph only. An unselected dependency is already
-  // applied, so it is not a reason for its dependents to wait.
-  const remaining = new Set(selected);
-  const selectedDeps = new Map(
-    [...selected].map((name) => [name, new Set((byName.get(name)!.dependsOn ?? []).filter((d) => selected.has(d)))]),
+  // applied, so it is not a reason for its dependents to wait. The layering is
+  // the one terragucci calls without components (../gated-waves.ts).
+  // resolveComponentGraph already refused every cycle in the full graph, and a
+  // subgraph of an acyclic graph is acyclic, so it cannot stall.
+  const waves = layerWaves(
+    [...selected].map((name) => ({ name, dependsOn: byName.get(name)!.dependsOn ?? [] })),
+    { canary, known: [...byName.keys()] },
   );
-  const waves: string[][] = [];
-  while (remaining.size > 0) {
-    const wave = [...remaining]
-      .filter((n) => [...selectedDeps.get(n)!].every((d) => !remaining.has(d)))
-      .sort();
-    // resolveComponentGraph already refused every cycle in the full graph, and
-    // a subgraph of an acyclic graph is acyclic, so this cannot stall.
-    for (const n of wave) remaining.delete(n);
-    waves.push(wave);
-  }
 
-  // Every dependency lands in an earlier wave than its dependents, so the
-  // flattening is a topological order, and a sorted one.
+  // Every dependency lands in an earlier wave than its dependents, except
+  // where a canary list put a dependent first on purpose, so the flattening is
+  // a topological order, and a sorted one.
   const order = waves.flat();
 
   const seeds = [

package/src/components/gated-wave-pipeline.ts

@@ -0,0 +1,82 @@
+/**
+ * The jobs of a generated gated-wave pipeline (#3049): one CI job per wave.
+ *
+ * The ruling in #3347 puts gated waves on forge CI by default, a job per
+ * wave, with approvals on `chant/lifecycle`. Each forge's generator (the
+ * gitlab and github lexicons) takes these jobs and adds its own transport;
+ * the commands and the order live here so the two cannot disagree.
+ *
+ * Job `wave-k` runs `chant components fan-out --wave-gate <gate> --wave k`.
+ * It derives the fan-out from the change, plans wave k against the outputs
+ * the record holds, decides that wave's gate and applies it. The attempt
+ * record (`--resume`) is the artifact handed from job to job: it says which
+ * components applied and what they exposed. A gate nobody approved exits 3,
+ * which fails the job; after `chant approve fan-out <gate>-wave-<k> --plan
+ * <digest>`, re-running that job carries on.
+ *
+ * How many jobs: the waves of the whole component graph, with the canary list
+ * in front. A change selects a subset, and a subset never layers deeper than
+ * the graph it came from, so a job past the change's last wave finds nothing
+ * to run and exits 0.
+ */
+
+import type { DriverComponent } from "./driver";
+import { layerWaves } from "../gated-waves";
+
+/** Where each wave job keeps the attempt record it hands the next one. */
+export const GATED_WAVE_RECORD = ".chant/fan-out.json";
+
+/** The `gatedWaves` generator option (`ComponentPipelineOptions.gatedWaves`). */
+export interface GatedWavePipelineOptions {
+  /** The base gate name. Wave k waits on `<gate>-wave-<k>`. */
+  gate: string;
+  /** Components that form wave 1. */
+  canary?: string[];
+  /**
+   * The ref the change is measured from (`--base`). Default `HEAD~1`: the
+   * pipeline runs on the merge commit and fans out what it changed. Every
+   * job must derive the same fan-out, so this must not move between jobs.
+   */
+  base?: string;
+}
+
+export interface GatedWaveJob {
+  /** 1-based. */
+  wave: number;
+  /** `wave-<k>`. */
+  jobName: string;
+  /** The previous wave's job, if any. */
+  needs: string[];
+  /** The job's command, as argv. */
+  command: string[];
+}
+
+/** One job per possible wave, in order, each needing the one before. */
+export function gatedWaveJobs(
+  components: DriverComponent[],
+  env: string,
+  options: GatedWavePipelineOptions,
+): GatedWaveJob[] {
+  const count = layerWaves(
+    components.map((c) => ({ name: c.name, dependsOn: c.dependsOn ?? [] })),
+    { ...(options.canary?.length ? { canary: options.canary } : {}) },
+  ).length;
+  const jobs: GatedWaveJob[] = [];
+  for (let wave = 1; wave <= count; wave++) {
+    jobs.push({
+      wave,
+      jobName: `wave-${wave}`,
+      needs: wave > 1 ? [`wave-${wave - 1}`] : [],
+      command: [
+        "chant", "components", "fan-out",
+        "--base", options.base ?? "HEAD~1",
+        "--env", env,
+        "--wave-gate", options.gate,
+        ...(options.canary?.length ? ["--canary", options.canary.join(",")] : []),
+        "--wave", String(wave),
+        "--resume", GATED_WAVE_RECORD,
+      ],
+    });
+  }
+  return jobs;
+}

package/src/components/index.ts

@@ -14,6 +14,7 @@ export {
   type Gate,
   type Phase,
   type Component,
+  type ComponentEnvironmentDeclaration,
   phase,
   gate,
   stackOutput,

package/src/components/layers.ts

@@ -0,0 +1,30 @@
+/**
+ * Kahn layering over a plain name graph: the wave computation
+ * `resolveComponentGraph` (./driver.ts) runs for `chant components fan-out`.
+ *
+ * It lives on its own, with no imports, so code that needs the same order
+ * without the driver can take it. The terraform lexicon's pin-bump rollout
+ * (#3189) orders roots with it, and that code has to bundle without the
+ * driver's gate and ledger modules (#3421).
+ */
+
+/** The layers, or the names left when no name is ready (a cycle). */
+export type KahnLayers = { waves: string[][]; cycle?: undefined } | { waves?: undefined; cycle: string[] };
+
+/**
+ * Split `deps` (name -> the names it depends on) into waves. A name is ready
+ * once every dependency it names has been placed in an earlier wave. Names in
+ * one wave are sorted. A dependency that is not a key of `deps` is the caller's
+ * to refuse or drop first: here it never becomes ready, so it reads as a cycle.
+ */
+export function kahnLayers(deps: ReadonlyMap<string, ReadonlySet<string>>): KahnLayers {
+  const remaining = new Set(deps.keys());
+  const waves: string[][] = [];
+  while (remaining.size > 0) {
+    const wave = [...remaining].filter((n) => [...deps.get(n)!].every((d) => !remaining.has(d))).sort();
+    if (wave.length === 0) return { cycle: [...remaining].sort() };
+    for (const n of wave) remaining.delete(n);
+    waves.push(wave);
+  }
+  return { waves };
+}

package/src/components/pr-pipeline.ts

@@ -0,0 +1,91 @@
+/**
+ * The jobs of a generated pull-request pipeline (#3183): a plan job on every
+ * pull request and an apply job on every push to the target branch.
+ *
+ * Each forge's generator (the github, gitlab and forgejo lexicons) adds its
+ * own triggers, permissions and artifact handling; the commands and the
+ * values they read from the forge live here so the three cannot disagree.
+ *
+ * - The plan job runs `chant components pr-plan` against the pull request's
+ *   target commit. It posts the note and the `chant/plan` status and writes
+ *   nothing to `chant/lifecycle`, since it runs the pull request's code.
+ * - The apply job runs `chant components pr-apply` against the commit the
+ *   push replaced, finds the pull request that merged the pushed commit
+ *   through the forge, and applies only when an approval stands for the
+ *   digest it plans. With `requireReview` (the default) the approver must
+ *   also have approved the pull request on the forge. It needs write access
+ *   to `chant/lifecycle`, to record the pending fact when the gate stops it.
+ *   One apply runs at a time per environment.
+ *
+ * Measuring the push from the commit it replaced works for merge commits,
+ * squash merges and rebase merges alike, and every job measures from the
+ * merge base of that commit and its own head (`resolveMergeBase`).
+ */
+
+import type { ForgeKind } from "../pr-forge";
+import { PR_APPLY_GATE } from "../pr-loop";
+
+/** Where both jobs write their reports, kept as a CI artifact. */
+export const PR_LOOP_REPORT_DIR = ".chant/pr";
+
+/** The `prLoop` generator option (`ComponentPipelineOptions.prLoop`). */
+export interface PrLoopPipelineOptions {
+  /** The gate the apply waits on. Default `pr-apply`. */
+  gate?: string;
+  /**
+   * The branch pull requests target and merges land on. Default `main` on
+   * GitHub and Forgejo; on GitLab, the project's default branch.
+   */
+  branch?: string;
+  /** Count an approval only from someone who approved the pull request on the forge. Default true. */
+  requireReview?: boolean;
+  /**
+   * Which GitHub-shaped forge the workflow is for. Set by the forgejo
+   * generator, which reuses the github one; a caller never needs to.
+   */
+  forge?: "github" | "forgejo";
+}
+
+/** One job's command and the forge values it reads, as environment variables for its step. */
+export interface PrLoopJob {
+  /** `plan` or `apply`. */
+  jobName: "plan" | "apply";
+  /** The command line. Reads `$BASE_SHA` and, for the plan, `$PR_NUMBER`. */
+  command: string;
+  /**
+   * Values the command reads, by variable name, as the forge spells them:
+   * `${{ ... }}` expressions on GitHub and Forgejo, GitLab's predefined
+   * variables on GitLab.
+   */
+  env: Record<string, string>;
+}
+
+/** The two jobs for `forge`. */
+export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}): PrLoopJob[] {
+  const gate = options.gate ?? PR_APPLY_GATE;
+  const common = ["--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge];
+  const github = forge !== "gitlab";
+  const token: Record<string, string> = github ? { GITHUB_TOKEN: "${{ github.token }}" } : {};
+  return [
+    {
+      jobName: "plan",
+      command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common].join(" "),
+      env: github
+        ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...token }
+        : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" },
+    },
+    {
+      jobName: "apply",
+      command: [
+        "chant", "components", "pr-apply", "--base", '"$BASE_SHA"', ...common,
+        ...(options.requireReview === false ? [] : ["--require-review"]),
+      ].join(" "),
+      env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+    },
+  ];
+}
+
+/** The concurrency group (GitHub, Forgejo) or resource group (GitLab) that keeps one apply at a time per environment. */
+export function prApplyGroup(env: string): string {
+  return `chant-apply-${env}`;
+}