@intentius/chant 0.124.31 → 0.124.32

package/src/codegen/pinned-upgrade.ts

@@ -29,7 +29,7 @@ import { regenLexicon, type RegenResult } from "./lexicon-regen";
 import { fetchWithRetry } from "./fetch";
 import { isLexiconPlugin, type UpstreamPin } from "../lexicon";
 import { importLexiconPackage } from "../lexicon-module";
-import { ensureTypeScriptLoader } from "../ts-loader";
+import { ensureTypeScriptLoaderFor } from "../ts-loader";
 
 // ── Public types ──────────────────────────────────────────────────────
 
@@ -252,7 +252,7 @@ export async function loadUpstreamPins(lexicon: LexiconId, lexiconDir?: string):
   const entry = lexiconDir ? lexiconEntry(lexiconDir) : null;
   if (entry) {
     try {
-      ensureTypeScriptLoader();
+      ensureTypeScriptLoaderFor(entry);
       const pins = pinsOf((await import(pathToFileURL(entry).href)) as Record<string, unknown>);
       if (pins.length > 0) return pins;
     } catch {

package/src/codegen/post-synth-barrel-guards.test.ts

@@ -26,17 +26,12 @@ describe("post-synth barrel is exported", () => {
   test.each(lexiconDirs)("%s exports ./lint/post-synth", (lexicon) => {
     const pkg = JSON.parse(readFileSync(join(lexiconsDir, lexicon, "package.json"), "utf-8"));
     const entry = pkg.exports?.["./lint/post-synth"];
-    // Lexicons shipping .d.ts use a conditional export — `types` resolves to the
-    // emitted declaration for external consumers; `development`/`default` keep
-    // runtime resolution on source (in-repo and published alike). Lexicons not
-    // yet building dist keep the plain source string.
-    if (typeof entry === "string") {
-      expect(entry).toBe("./src/lint/post-synth/index.ts");
-    } else {
-      expect(entry?.development).toBe("./src/lint/post-synth/index.ts");
-      expect(entry?.types).toBe("./dist/lint/post-synth/index.d.ts");
-      expect(entry?.default).toBe("./src/lint/post-synth/index.ts");
-    }
+    // A conditional export: `types` resolves to the emitted declaration,
+    // `development` keeps the repository's own resolution on source, and
+    // `default` is the compiled JS the package publishes (#3981).
+    expect(entry?.development).toBe("./src/lint/post-synth/index.ts");
+    expect(entry?.types).toBe("./dist/lint/post-synth/index.d.ts");
+    expect(entry?.default).toBe("./dist/lint/post-synth/index.js");
   });
 });
 

package/src/components/capability.ts

@@ -43,7 +43,9 @@ export interface DeployContext {
    * (#3049), keyed by {@link CapabilityPlan.member}. Set by a gated-wave
    * fan-out and by a pull request's apply (#3183). A capability whose `run`
    * finds its own member here applies that plan, the one the approver
-   * approved, instead of planning again.
+   * approved, instead of planning again. A `run` that finds the target moved
+   * since that plan refuses with an error {@link isPlanMovedError} accepts
+   * (#3997), and the command that applied it exits 3, as for a moved digest.
    */
   plans?: Record<string, unknown>;
   /**
@@ -90,6 +92,27 @@ export interface CapabilityPlan {
    * still counts toward the digest, with no entries.
    */
   changeSet?: ChangeSetPart;
+  /**
+   * The outputs `run` will expose once it applies this plan (#3999), as far
+   * as the plan can tell. A pull request's plan reads a dependent's
+   * `stackOutput()` references into this member from here when both are in
+   * the change, instead of from the outputs standing now. Absent when the
+   * plan cannot say: every output of the step is then known only after it
+   * applies.
+   */
+  outputs?: PlannedOutputs;
+}
+
+/**
+ * What a plan says about the outputs its apply will leave (#3999). An
+ * output named in neither field is known only after apply, the same as one
+ * in `unknown`.
+ */
+export interface PlannedOutputs {
+  /** Each output whose value the plan knows, by name: what `run` will expose. */
+  known: Record<string, unknown>;
+  /** Outputs the plan names whose value is known only after apply, sorted. */
+  unknown: string[];
 }
 
 /**
@@ -136,8 +159,11 @@ export interface Capability<In = unknown, Out = unknown> {
   /**
    * Optional: the outputs `run` exposed when it last ran, read without
    * changing anything (#3183). A pull request's plan reads them for each
-   * component a planned one depends on, so a `stackOutput()` wiring resolves
-   * to the value standing now. The shape is `run`'s `outputs` field.
+   * component a planned one depends on that the change does not plan
+   * (#4104), so a `stackOutput()` wiring resolves to the value standing now.
+   * A dependency the change plans is read from its plan's
+   * {@link CapabilityPlan.outputs} instead (#3999). The shape is `run`'s
+   * `outputs` field.
    */
   outputs?(ctx: DeployContext, input: In): Promise<Record<string, unknown>>;
   /**
@@ -160,6 +186,28 @@ export type CapabilityInput<C> = C extends Capability<infer In, unknown> ? In :
 /** Extract a capability's `Out` type. */
 export type CapabilityOutput<C> = C extends Capability<unknown, infer Out> ? Out : never;
 
+/**
+ * The exit code of a command whose capability step refused a plan that moved
+ * since it was approved: 3, the code `pr-apply` gives a moved digest and a
+ * run gives a gate (#3997).
+ */
+export const PLAN_MOVED_EXIT_CODE = 3;
+
+/**
+ * Whether `err` is a `run`'s refusal to apply a plan from
+ * `DeployContext.plans` because the target moved since it was planned
+ * (#3997). The mark is a `planMoved: true` property, not a class, so a
+ * lexicon built against an older core can set it. An `exitCode` of
+ * {@link PLAN_MOVED_EXIT_CODE} on the error is the same mark. Any other
+ * `exitCode` is ignored: a failed step exits 1, so a capability can't pick
+ * the process's exit code.
+ */
+export function isPlanMovedError(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as { planMoved?: unknown; exitCode?: unknown };
+  return e.planMoved === true || e.exitCode === PLAN_MOVED_EXIT_CODE;
+}
+
 /**
  * Thrown by a stub `run`/`rollback` — the verb is specified and typed but has
  * no cloud implementation yet. Distinguishes "not implemented" from a runtime

package/src/components/changed-files.test.ts

@@ -9,7 +9,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
-import { changedFilesBetween } from "./changed-files";
+import { changedFilesBetween, EMPTY_TREE_SHA, resolveMergeBase } from "./changed-files";
 
 const repo = mkdtempSync(join(tmpdir(), "chant-changed-files-"));
 afterAll(() => rmSync(repo, { recursive: true, force: true }));
@@ -56,3 +56,18 @@ describe("changedFilesBetween", () => {
     ]);
   });
 });
+
+describe("the empty tree as the base (a root commit, #4004)", () => {
+  test("is its own merge base, and every file the head holds counts as changed", async () => {
+    expect(await resolveMergeBase(repo, EMPTY_TREE_SHA, "HEAD")).toBe(EMPTY_TREE_SHA);
+    expect(await changedFilesBetween(repo, EMPTY_TREE_SHA)).toEqual([
+      "apps/web/main.tf",
+      "infra/network/roots/vpc/main.tf",
+      "shared/modules/base/main.tf",
+    ]);
+  });
+
+  test("is git's own empty tree", () => {
+    expect(git("hash-object", "-t", "tree", "/dev/null")).toBe(EMPTY_TREE_SHA);
+  });
+});

package/src/components/changed-files.ts

@@ -20,13 +20,21 @@ async function git(cwd: string, args: string[]): Promise<string> {
   return stdout;
 }
 
+/**
+ * Git's empty tree. A root commit has no parent, so a push of one is measured
+ * from this (#4004): every file it holds counts as changed.
+ */
+export const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
 /**
  * The commit a change is measured from: the merge base of `base` and `head`.
  * A pull request's head that branched before `base` moved is measured from
  * where it branched, so the other changes on `base` are not counted as its
- * own; a merge commit's first parent is its own merge base.
+ * own; a merge commit's first parent is its own merge base. The empty tree
+ * has no merge base with anything and is returned as it is.
  */
 export async function resolveMergeBase(cwd: string, base: string, head = "HEAD"): Promise<string> {
+  if (base === EMPTY_TREE_SHA) return base;
   try {
     return (await git(cwd, ["merge-base", base, head])).trim();
   } catch (err) {

package/src/components/driver.test.ts

@@ -11,7 +11,7 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { CapabilityRegistry, type DeployContext } from "./capability";
+import { CapabilityRegistry, isPlanMovedError, type DeployContext } from "./capability";
 import { stubCapability } from "./verbs/stub";
 import { describeGateMismatch, memoryGateLedgerPort } from "../op/gate";
 import { componentPlanDigest } from "./gate-plan";
@@ -22,6 +22,7 @@ import {
   UnknownDependencyError,
   accumulateComponentOutputs,
   collectComponentOutputs,
+  failedRunExitCode,
   resolveComponentGraph,
   resolveWiring,
   runComponentDeploy,
@@ -1173,3 +1174,37 @@ describe("unresolvedWiringSources (#4084)", () => {
     ).toEqual([]);
   });
 });
+
+describe("a step that refuses a moved plan (#3997)", () => {
+  it.each([
+    ["planMoved: true", { planMoved: true }, true],
+    ["exitCode 3", { exitCode: 3 }, true],
+    ["exitCode 7", { exitCode: 7 }, false],
+    ['exitCode "3"', { exitCode: "3" }, false],
+    ["planMoved: \"yes\"", { planMoved: "yes" }, false],
+    ["no mark", {}, false],
+  ])("isPlanMovedError reads an error with %s", (_label, mark, moved) => {
+    expect(isPlanMovedError(Object.assign(new Error("refused"), mark))).toBe(moved);
+  });
+
+  it("is not fooled by a non-object", () => {
+    expect(isPlanMovedError(null)).toBe(false);
+    expect(isPlanMovedError("planMoved")).toBe(false);
+  });
+
+  it("marks the failed step's record, and failedRunExitCode answers 3 for it and 1 for any other failure", async () => {
+    const run = async (mark: object) => {
+      const registry = new CapabilityRegistry();
+      registry.register(fakeCapability("apply", { run: () => { throw Object.assign(new Error("refused"), mark); } }).capability);
+      const component: DriverComponent = { name: "c", deploy: [{ phase: "Apply", steps: [{ kind: "apply" }] }] };
+      return runComponentDeploy(component, { env: "dev", component: "c" }, registry, {});
+    };
+    const moved = await run({ exitCode: 3 });
+    expect(moved.records[0]).toMatchObject({ status: "fail", planMoved: true });
+    expect(failedRunExitCode([moved])).toBe(3);
+    const other = await run({ exitCode: 7 });
+    expect(other.records[0]).not.toHaveProperty("planMoved");
+    expect(failedRunExitCode([other])).toBe(1);
+    expect(failedRunExitCode([other, moved])).toBe(3);
+  });
+});

package/src/components/driver.ts

@@ -54,6 +54,7 @@ import { GateNotRecordableError } from "../lifecycle/no-record";
 import { componentPlanDigest } from "./gate-plan";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
+import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability";
 import { isPromotedArtifact } from "./auto-release";
 import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent } from "./run-progress";
@@ -154,6 +155,8 @@ export interface DriverStepRecord {
   durationMs: number;
   output?: unknown;
   error?: string;
+  /** Set on a failed step whose capability refused a plan that moved since it was approved (`isPlanMovedError`, #3997). */
+  planMoved?: true;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
   approval?: {
     gate: string;
@@ -356,12 +359,51 @@ export function unresolvedWiringSources(
   input: Record<string, unknown>,
   componentOutputs: Record<string, Record<string, unknown>>,
 ): string[] {
-  const found = new Set<string>();
+  return [...new Set(unresolvedWiringReferences(input, componentOutputs).map((r) => r.source))].sort();
+}
+
+/** One cross-component reference a step input makes: whose output, and which. */
+export interface WiringReference {
+  /** The component or stack whose output it reads. */
+  source: string;
+  /** `<stack>.<name>` for `stackOutput()`, `<component>.publish.<field>` for an artifact. */
+  ref: string;
+  /**
+   * Whether it reads a published artifact's identity (#3999): an
+   * `@<component>.publish.*` reference, or a `stackOutput()` whose name is
+   * under `publish`. The driver namespaces every publish-family output there
+   * (`collectComponentOutputs`), whatever capability wrote it.
+   */
+  publish: boolean;
+}
+
+/**
+ * Every cross-component reference in `input` that has no value in
+ * `componentOutputs`, sorted by `ref` and each once (#3999). A pull
+ * request's plan names these when the output is known only after its
+ * upstream applies.
+ */
+export function unresolvedWiringReferences(
+  input: Record<string, unknown>,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): WiringReference[] {
+  return wiringReferences(input).filter((r) => r.value(componentOutputs) === undefined).map(({ source, ref, publish }) => ({ source, ref, publish }));
+}
+
+/**
+ * Every cross-component reference in `input`, each once, sorted by `ref`,
+ * with the value it resolves to against a given outputs map.
+ */
+function wiringReferences(input: Record<string, unknown>): Array<WiringReference & { value: (outputs: Record<string, Record<string, unknown>>) => unknown }> {
+  const found = new Map<string, WiringReference & { value: (outputs: Record<string, Record<string, unknown>>) => unknown }>();
   const walk = (value: unknown): void => {
     if (typeof value === "string") {
       if (PRIOR_STEP_REF.test(value)) return;
       const ref = value.match(COMPONENT_ARTIFACT_REF);
-      if (ref && resolvePath(componentOutputs[ref[1]]?.publish, ref[2]) === undefined) found.add(ref[1]);
+      if (ref) {
+        const [, source, field] = ref;
+        found.set(`${source}.publish.${field}`, { source, ref: `${source}.publish.${field}`, publish: true, value: (o) => resolvePath(o[source]?.publish, field) });
+      }
       return;
     }
     if (Array.isArray(value)) {
@@ -371,14 +413,29 @@ export function unresolvedWiringSources(
     if (value && typeof value === "object") {
       if ("stackOutput" in value) {
         const { stack, name } = (value as { stackOutput: { stack: string; name: string } }).stackOutput;
-        if (resolvePath(componentOutputs[stack], name) === undefined) found.add(stack);
+        found.set(`${stack}.${name}`, { source: stack, ref: `${stack}.${name}`, publish: name === "publish" || name.startsWith("publish."), value: (o) => resolvePath(o[stack], name) });
         return;
       }
       Object.values(value as Record<string, unknown>).forEach(walk);
     }
   };
   walk(input);
-  return [...found].sort();
+  return [...found.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+}
+
+/**
+ * The cross-component references in `input` that resolve to another value
+ * against `now` than against `read`, sorted (#3999). A pull request's apply
+ * holds back a member whose plan read `read` when its upstream applied and
+ * left `now`.
+ */
+export function movedWiringReferences(
+  input: Record<string, unknown>,
+  read: Record<string, Record<string, unknown>>,
+  now: Record<string, Record<string, unknown>>,
+): WiringReference[] {
+  const same = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+  return wiringReferences(input).filter((r) => !same(r.value(read), r.value(now))).map(({ source, ref, publish }) => ({ source, ref, publish }));
 }
 
 // ── Step + phase execution ───────────────────────────────────────────────
@@ -501,6 +558,7 @@ async function runCapabilityStep(
         status: "fail",
         durationMs: Date.now() - start,
         error: errMessage(err),
+        ...(isPlanMovedError(err) ? { planMoved: true as const } : {}),
       },
       resolvedInput,
     };
@@ -995,6 +1053,20 @@ function findStackOutputs(
   return found;
 }
 
+/** Whether a step in `results` refused a plan that moved since it was approved (#3997). */
+export function planMovedIn(results: readonly DriverComponentResult[]): boolean {
+  return results.some((r) => r.records.some((s) => s.planMoved === true));
+}
+
+/**
+ * The exit code of a run that failed: {@link PLAN_MOVED_EXIT_CODE} when a
+ * step refused a plan that moved since it was approved, 1 otherwise. Every
+ * command that runs capability steps ends a failed run with it.
+ */
+export function failedRunExitCode(results: readonly DriverComponentResult[]): number {
+  return planMovedIn(results) ? PLAN_MOVED_EXIT_CODE : 1;
+}
+
 function errMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }

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

@@ -38,7 +38,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { readWaveRecords, writeWaveRecordFile, type WaveRecord } from "../wave-engine";
 import type { ChangeSetDocument } from "../change-set";
-import type { PrMember } from "../pr-loop";
+import type { PrMember, PrWave } from "../pr-loop";
 
 /** What a pull request's apply approved, kept so a re-run can finish it (#3464). */
 export interface PrApplyRecord {
@@ -59,6 +59,11 @@ export interface PrApplyRecord {
    * against them again, so an unchanged member plans to the same digest.
    */
   planOutputs: Record<string, Record<string, unknown>>;
+  /**
+   * With `--wave-gate` (#4003): each wave reached so far and the approval it
+   * applied or waits under, so the next wave's job reports every wave.
+   */
+  waves?: PrWave[];
 }
 
 export interface FanOutAttempt {
@@ -100,6 +105,7 @@ function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
   if (isRecord(planOutputs)) {
     for (const [name, v] of Object.entries(planOutputs)) if (isRecord(v)) outputs[name] = v;
   }
+  const waves = Array.isArray(value.waves) ? value.waves.map(readPrWave).filter((w): w is PrWave => w !== undefined) : [];
   return {
     op,
     gate,
@@ -109,6 +115,28 @@ function readPrApplyRecord(value: unknown): PrApplyRecord | undefined {
     members: members as unknown as PrMember[],
     changeSet: changeSet as unknown as ChangeSetDocument,
     planOutputs: outputs,
+    ...(waves.length > 0 ? { waves } : {}),
+  };
+}
+
+const WAVE_STATUSES: ReadonlySet<string> = new Set(["applied", "failed", "plan-failed", "waiting"]);
+
+/** One `prApply.waves` entry, or `undefined` when it is malformed. */
+function readPrWave(value: unknown): PrWave | undefined {
+  if (!isRecord(value)) return undefined;
+  const { wave, components, status, approval, gate, digest } = value;
+  if (typeof wave !== "number" || !isStringArray(components) || typeof status !== "string" || !WAVE_STATUSES.has(status)) return undefined;
+  if ((approval !== "pull-request" && approval !== "wave") || typeof gate !== "string" || typeof digest !== "string") return undefined;
+  return {
+    wave,
+    components,
+    status: status as PrWave["status"],
+    approval,
+    gate,
+    digest,
+    ...(isStringArray(value.approvedBy) ? { approvedBy: value.approvedBy } : {}),
+    ...(typeof value.approved === "string" ? { approved: value.approved } : {}),
+    ...(isStringArray(value.moved) ? { moved: value.moved } : {}),
   };
 }
 

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

@@ -209,3 +209,38 @@ describe("one approval over the whole set", () => {
     expect(ran.sort()).toEqual(["app-one", "app-three", "app-two", "cluster-b"]);
   });
 });
+
+describe("holding a component back (#3999)", () => {
+  test("a held component and what is downstream of it do not run and settle waiting; independent branches run", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const { registry, ran } = registryWith();
+    const events: Array<{ type: string; component?: string; status?: string }> = [];
+    const asked: Array<[string, string[]]> = [];
+    const result = await runFanOut(plan, ESTATE, registry, {
+      ...opts(),
+      onRunEvent: (e) => events.push(e as never),
+      hold: (name, outputs) => {
+        asked.push([name, Object.keys(outputs).sort()]);
+        return name === "cluster-a" ? "its plan read net.id before that output applied as another value" : undefined;
+      },
+    });
+    expect(result.status).toBe("ok");
+    expect(ran).not.toContain("cluster-a");
+    expect(ran).not.toContain("app-one");
+    expect(ran).toContain("app-three");
+    expect(result.held).toEqual([
+      { component: "cluster-a", reason: "its plan read net.id before that output applied as another value" },
+      { component: "app-one", reason: "its plan read net.id before that output applied as another value", heldBy: "cluster-a" },
+      { component: "app-two", reason: "its plan read net.id before that output applied as another value", heldBy: "cluster-a" },
+    ].sort((a, b) => plan.order.indexOf(a.component) - plan.order.indexOf(b.component)));
+    // Asked once per component as its wave starts, never for one already held.
+    expect(asked.map(([name]) => name).sort()).toEqual(["app-three", "cluster-a", "cluster-b", "net"]);
+    expect(events.filter((e) => e.type === "component-settle" && e.status === "waiting").map((e) => e.component).sort()).toEqual(["app-one", "app-two", "cluster-a"]);
+  });
+
+  test("with no hook, or a hook that holds nothing, the result has no held list", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    expect((await runFanOut(plan, ESTATE, registryWith().registry, opts())).held).toBeUndefined();
+    expect((await runFanOut(plan, ESTATE, registryWith().registry, { ...opts(), hold: () => undefined })).held).toBeUndefined();
+  });
+});

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

@@ -205,6 +205,25 @@ export interface FanOutRunOptions {
    * the returned result cannot do.
    */
   onComponentSettled?: (result: DriverComponentResult, outputs: Record<string, unknown> | undefined) => void;
+  /**
+   * Asked as each component's wave starts, with the outputs standing then
+   * (#3999). A reason holds the component back: it does not run, and nothing
+   * downstream of it runs either; each is listed in `held` and settles
+   * `waiting`. A pull request's apply holds a member whose plan read an
+   * upstream output that applied as another value, or that was known only
+   * after apply. Not with `waveGate`, which plans each wave after the one
+   * before it applied.
+   */
+  hold?: (component: string, componentOutputs: Record<string, Record<string, unknown>>) => string | undefined;
+}
+
+/** A component {@link FanOutRunOptions.hold} held back, or one downstream of it. */
+export interface FanOutHeld {
+  component: string;
+  /** Why the hook held it, or, downstream, why it held the component named in `heldBy`. */
+  reason: string;
+  /** Downstream of a held component: that component. */
+  heldBy?: string;
 }
 
 export interface FanOutRunResult {
@@ -223,6 +242,8 @@ export interface FanOutRunResult {
   gate?: PendingGateRecord;
   /** With `waveGate`: each wave this attempt planned, in order, the one it stopped at included. */
   waves?: WaveRecord[];
+  /** What {@link FanOutRunOptions.hold} held back, in plan order. Absent when nothing was. */
+  held?: FanOutHeld[];
 }
 
 /**
@@ -296,9 +317,21 @@ export async function runFanOut(
   const completed: string[] = [];
   const failed: string[] = [];
   const blockedBy = new Map<string, string>();
+  const held = new Map<string, FanOutHeld>();
   let gatedFact: PendingGateRecord | undefined;
 
   const inPlan = new Set(active.order);
+  const waveOf = waveNumbers(active.waves);
+  /** Hold `root` and everything downstream of it that has not settled otherwise. */
+  const markHeld = (root: string, reason: string): void => {
+    held.set(root, { component: root, reason });
+    emit?.({ type: "component-settle", wave: waveOf.get(root)!, component: root, status: "waiting" });
+    for (const [component] of downstreamWithin(components, inPlan, [root])) {
+      if (held.has(component) || blockedBy.has(component) || failed.includes(component)) continue;
+      held.set(component, { component, reason, heldBy: root });
+      emit?.({ type: "component-settle", wave: waveOf.get(component)!, component, status: "waiting" });
+    }
+  };
   /** Skip everything downstream of `root`, blaming `root` rather than the nearest edge. */
   const markBlocked = (root: string): void => {
     for (const [component, by] of downstreamWithin(components, inPlan, [root])) {
@@ -310,7 +343,12 @@ export async function runFanOut(
   for (const [waveIndex, wave] of active.waves.entries()) {
     const waveNum = waveIndex + 1;
     // A component whose upstream failed in an earlier wave is not dispatched.
-    const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
+    const candidates = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name) && !held.has(name));
+    for (const name of candidates) {
+      const reason = options.hold?.(name, componentOutputs);
+      if (reason !== undefined) markHeld(name, reason);
+    }
+    const runnable = candidates.filter((name) => !held.has(name));
     if (runnable.length === 0) continue;
 
     emit?.({ type: "wave-start", wave: waveNum, components: runnable });
@@ -384,6 +422,7 @@ export async function runFanOut(
     blocked,
     componentOutputs,
     ...(gatedFact ? { gate: gatedFact } : {}),
+    ...(held.size > 0 ? { held: active.order.filter((name) => held.has(name)).map((name) => held.get(name)!) } : {}),
   };
 }
 

package/src/components/pr-pipeline.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The apply job's base fallback (#4004), run in sh against a real
+ * repository. GitHub and Forgejo set `github.event.before`, and GitLab
+ * `CI_COMMIT_BEFORE_SHA`, to forty zeros on a branch's first push.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { EMPTY_TREE_SHA } from "./changed-files";
+import { githubBaseFallback, gitlabBaseFallback, prLoopJobs } from "./pr-pipeline";
+
+const ZEROS = "0".repeat(40);
+const dir = mkdtempSync(join(tmpdir(), "chant-pr-base-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+const ENV = { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@example.com", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@example.com" };
+
+const git = (cwd: string, ...args: string[]): string => execFileSync("git", args, { cwd, encoding: "utf8", env: ENV }).trim();
+
+/** A bare origin and a clone of it, `main` holding `commits` commits. */
+function repo(name: string, commits: number): string {
+  const origin = join(dir, `${name}.git`);
+  const work = join(dir, name);
+  execFileSync("git", ["init", "-q", "--bare", "-b", "main", origin]);
+  execFileSync("git", ["init", "-q", "-b", "main", work]);
+  git(work, "remote", "add", "origin", origin);
+  for (let i = 0; i < commits; i++) {
+    writeFileSync(join(work, "f.txt"), `${i}\n`);
+    git(work, "add", "-A");
+    git(work, "commit", "-q", "-m", `c${i}`);
+  }
+  git(work, "push", "-q", "origin", "main");
+  return work;
+}
+
+/** BASE_SHA after `line` runs in `cwd` with `env`. */
+function settle(cwd: string, line: string, env: Record<string, string>): string {
+  return execFileSync("sh", ["-ec", `${line}\nprintf %s "$BASE_SHA"`], { cwd, encoding: "utf8", env: { ...ENV, ...env } });
+}
+
+describe("githubBaseFallback (#4004)", () => {
+  test("a set base is kept", () => {
+    const work = repo("kept", 2);
+    const parent = git(work, "rev-parse", "HEAD^");
+    expect(settle(work, githubBaseFallback(), { BASE_SHA: parent, GITHUB_SHA: git(work, "rev-parse", "HEAD") })).toBe(parent);
+  });
+
+  test("forty zeros or empty on the target branch's first push: the pushed commit's parent", () => {
+    const work = repo("first", 2);
+    const head = git(work, "rev-parse", "HEAD");
+    const parent = git(work, "rev-parse", "HEAD^");
+    expect(settle(work, githubBaseFallback(), { BASE_SHA: ZEROS, GITHUB_SHA: head })).toBe(parent);
+    expect(settle(work, githubBaseFallback(), { BASE_SHA: "", GITHUB_SHA: head })).toBe(parent);
+  });
+
+  test("a branch's first push: the merge base with the target branch", () => {
+    const work = repo("branch", 1);
+    const fork = git(work, "rev-parse", "HEAD");
+    git(work, "checkout", "-q", "-b", "feature");
+    writeFileSync(join(work, "g.txt"), "g\n");
+    git(work, "add", "-A");
+    git(work, "commit", "-q", "-m", "feature");
+    expect(settle(work, githubBaseFallback(), { BASE_SHA: ZEROS, GITHUB_SHA: git(work, "rev-parse", "HEAD") })).toBe(fork);
+  });
+
+  test("a root commit: the empty tree", () => {
+    const work = repo("root", 1);
+    expect(settle(work, githubBaseFallback(), { BASE_SHA: ZEROS, GITHUB_SHA: git(work, "rev-parse", "HEAD") })).toBe(EMPTY_TREE_SHA);
+  });
+
+  test("a named branch is the one fetched", () => {
+    expect(githubBaseFallback()).toContain('git fetch origin "main"');
+    expect(githubBaseFallback("trunk")).toContain('git fetch origin "trunk"');
+  });
+});
+
+describe("gitlabBaseFallback", () => {
+  test("a root commit's first push: the empty tree, as on GitHub (#4004)", () => {
+    const work = repo("gitlab-root", 1);
+    expect(settle(work, gitlabBaseFallback("main"), { BASE_SHA: ZEROS, CI_COMMIT_SHA: git(work, "rev-parse", "HEAD") })).toBe(EMPTY_TREE_SHA);
+  });
+
+  test("the merge request's diff base comes first", () => {
+    const work = repo("gitlab-mr", 2);
+    const parent = git(work, "rev-parse", "HEAD^");
+    expect(settle(work, gitlabBaseFallback("main"), { BASE_SHA: ZEROS, CI_MERGE_REQUEST_DIFF_BASE_SHA: parent, CI_COMMIT_SHA: git(work, "rev-parse", "HEAD") })).toBe(parent);
+  });
+});
+
+describe("prLoopJobs", () => {
+  test("every forge's apply settles its base first; no plan does", () => {
+    for (const forge of ["github", "forgejo", "gitlab"] as const) {
+      const [plan, apply] = prLoopJobs(forge, "prod", { branch: "trunk" });
+      expect(plan!.setup).toBeUndefined();
+      expect(apply!.setup).toEqual([forge === "gitlab" ? gitlabBaseFallback("trunk") : githubBaseFallback("trunk")]);
+    }
+  });
+});