@intentius/chant 0.124.31 → 0.124.32

package/dist/components/capability.js

@@ -11,6 +11,27 @@
  * live under `./verbs/*` as typed stubs — no cloud calls, no side effects.
  * Cloud implementations are a later phase (see epic #551, issue #554).
  */
+/**
+ * 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) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const e = err;
+    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/dist/components/changed-files.d.ts

@@ -8,11 +8,17 @@
  * changed paths instead (`LexiconPlugin.changedUnits`).
  */
 import type { LexiconPlugin } from "../lexicon.js";
+/**
+ * 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 declare 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 declare function resolveMergeBase(cwd: string, base: string, head?: string): Promise<string>;
 /** The full commit `ref` names. */

package/dist/components/changed-files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changed-files.d.ts","sourceRoot":"","sources":["../../src/components/changed-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAShD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAUhG;AAED,mCAAmC;AACnC,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWrG;AAED,iEAAiE;AACjE,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,EAAE,EACvD,GAAG,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACpF,OAAO,CAAC,MAAM,EAAE,CAAC,CAQnB"}
+{"version":3,"file":"changed-files.d.ts","sourceRoot":"","sources":["../../src/components/changed-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAShD;;;GAGG;AACH,eAAO,MAAM,cAAc,6CAA6C,CAAC;AAEzE;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAWhG;AAED,mCAAmC;AACnC,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWrG;AAED,iEAAiE;AACjE,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,SAAS,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,EAAE,EACvD,GAAG,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACpF,OAAO,CAAC,MAAM,EAAE,CAAC,CAQnB"}

package/dist/components/changed-files.js

@@ -15,13 +15,21 @@ async function git(cwd, args) {
     const { stdout } = await execFileAsync("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
     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, base, head = "HEAD") {
+    if (base === EMPTY_TREE_SHA)
+        return base;
     try {
         return (await git(cwd, ["merge-base", base, head])).trim();
     }

package/dist/components/driver.d.ts

@@ -116,6 +116,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;
@@ -228,6 +230,34 @@ export declare function resolveStepInput(input: Record<string, unknown>, phaseOu
  * `undefined`; a plan uses this to say whose outputs it is waiting on.
  */
 export declare function unresolvedWiringSources(input: Record<string, unknown>, componentOutputs: Record<string, Record<string, unknown>>): string[];
+/** 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 declare function unresolvedWiringReferences(input: Record<string, unknown>, componentOutputs: Record<string, Record<string, unknown>>): WiringReference[];
+/**
+ * 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 declare function movedWiringReferences(input: Record<string, unknown>, read: Record<string, Record<string, unknown>>, now: Record<string, Record<string, unknown>>): WiringReference[];
 /** How a component's run reaches the gate ledger — see `../op/gate.ts`. */
 export interface GateContext {
     port: GateLedgerPort;
@@ -317,6 +347,14 @@ export declare function collectComponentOutputs(phaseOutputs: Record<string, Rec
  * when the component exposed nothing.
  */
 export declare function accumulateComponentOutputs(componentOutputs: Record<string, Record<string, unknown>>, componentName: string, phaseOutputs: Record<string, Record<string, unknown>>): Record<string, Record<string, unknown>>;
+/** Whether a step in `results` refused a plan that moved since it was approved (#3997). */
+export declare function planMovedIn(results: readonly DriverComponentResult[]): boolean;
+/**
+ * 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 declare function failedRunExitCode(results: readonly DriverComponentResult[]): number;
 export interface InterpretRunOptions {
     /** Target environment name, threaded into every capability's `DeployContext`. */
     env: string;

package/dist/components/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/components/driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/components/driver.ts"],"names":[],"mappings":"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"}

package/dist/components/driver.js

@@ -51,6 +51,7 @@ import { evaluateGate, gitGateLedgerPort } from "../op/gate.js";
 import { gateName } from "../op/gate-name.js";
 import { GateNotRecordableError } from "../lifecycle/no-record.js";
 import { componentPlanDigest } from "./gate-plan.js";
+import { isPlanMovedError, PLAN_MOVED_EXIT_CODE } from "./capability.js";
 import { isPromotedArtifact } from "./auto-release.js";
 import { gateEventsOf, joinRunEventSinks, progressSinkOf } from "../run-event-stream.js";
 function isGateStep(step) {
@@ -194,14 +195,32 @@ export function resolveStepInput(input, phaseOutputs, componentOutputs) {
  * `undefined`; a plan uses this to say whose outputs it is waiting on.
  */
 export function unresolvedWiringSources(input, componentOutputs) {
-    const found = new Set();
+    return [...new Set(unresolvedWiringReferences(input, componentOutputs).map((r) => r.source))].sort();
+}
+/**
+ * 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, componentOutputs) {
+    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) {
+    const found = new Map();
     const walk = (value) => {
         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)) {
@@ -211,15 +230,24 @@ export function unresolvedWiringSources(input, componentOutputs) {
         if (value && typeof value === "object") {
             if ("stackOutput" in value) {
                 const { stack, name } = value.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).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, read, now) {
+    const same = (a, b) => 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 }));
 }
 class StepFailure extends Error {
     constructor(records, executed) {
@@ -280,6 +308,7 @@ async function runCapabilityStep(step, phaseName, ctx, registry, phaseOutputs, c
                 status: "fail",
                 durationMs: Date.now() - start,
                 error: errMessage(err),
+                ...(isPlanMovedError(err) ? { planMoved: true } : {}),
             },
             resolvedInput,
         };
@@ -718,6 +747,18 @@ function findStackOutputs(phaseOutputs) {
     }
     return found;
 }
+/** Whether a step in `results` refused a plan that moved since it was approved (#3997). */
+export function planMovedIn(results) {
+    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) {
+    return planMovedIn(results) ? PLAN_MOVED_EXIT_CODE : 1;
+}
 function errMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/components/fan-out-record.d.ts

@@ -36,7 +36,7 @@
  */
 import { type WaveRecord } from "../wave-engine.js";
 import type { ChangeSetDocument } from "../change-set.js";
-import type { PrMember } from "../pr-loop.js";
+import type { PrMember, PrWave } from "../pr-loop.js";
 /** What a pull request's apply approved, kept so a re-run can finish it (#3464). */
 export interface PrApplyRecord {
     /** The gate's op and name: `pr-<n>` and `pr-apply` unless the pipeline names another. */
@@ -56,6 +56,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 {
     digest: string;

package/dist/components/fan-out-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fan-out-record.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,qGAAqG;IACrG,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,wCAAwC;IACxC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AA+BD,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAwBzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAE7E"}
+{"version":3,"file":"fan-out-record.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,EAAwC,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEnD,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,oDAAoD;IACpD,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,qGAAqG;IACrG,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,wCAAwC;IACxC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2CAA2C;IAC3C,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAsDD,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAwBzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAE7E"}

package/dist/components/fan-out-record.js

@@ -55,6 +55,7 @@ function readPrApplyRecord(value) {
             if (isRecord(v))
                 outputs[name] = v;
     }
+    const waves = Array.isArray(value.waves) ? value.waves.map(readPrWave).filter((w) => w !== undefined) : [];
     return {
         op,
         gate,
@@ -64,6 +65,29 @@ function readPrApplyRecord(value) {
         members: members,
         changeSet: changeSet,
         planOutputs: outputs,
+        ...(waves.length > 0 ? { waves } : {}),
+    };
+}
+const WAVE_STATUSES = new Set(["applied", "failed", "plan-failed", "waiting"]);
+/** One `prApply.waves` entry, or `undefined` when it is malformed. */
+function readPrWave(value) {
+    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,
+        approval,
+        gate,
+        digest,
+        ...(isStringArray(value.approvedBy) ? { approvedBy: value.approvedBy } : {}),
+        ...(typeof value.approved === "string" ? { approved: value.approved } : {}),
+        ...(isStringArray(value.moved) ? { moved: value.moved } : {}),
     };
 }
 /** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */

package/dist/components/fan-out-run.d.ts

@@ -138,6 +138,24 @@ 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 {
     /** The plan actually dispatched — `plan` narrowed by `options.progress`. */
@@ -155,6 +173,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[];
 }
 /**
  * Dispatch a fan-out plan.

package/dist/components/fan-out-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fan-out-run.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fan-out-run.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-run.ts"],"names":[],"mappings":"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"}

package/dist/components/fan-out-run.js

@@ -159,8 +159,21 @@ export async function runFanOut(plan, components, registry, options) {
     const completed = [];
     const failed = [];
     const blockedBy = new Map();
+    const held = new Map();
     let gatedFact;
     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, reason) => {
+        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) => {
         for (const [component, by] of downstreamWithin(components, inPlan, [root])) {
@@ -172,7 +185,13 @@ export async function runFanOut(plan, components, registry, options) {
     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 });
@@ -231,6 +250,7 @@ export async function runFanOut(plan, components, registry, options) {
         blocked,
         componentOutputs,
         ...(gatedFact ? { gate: gatedFact } : {}),
+        ...(held.size > 0 ? { held: active.order.filter((name) => held.has(name)).map((name) => held.get(name)) } : {}),
     };
 }
 /** The run's `deployContext`, with the carried state and the carry callback (#3459) when the caller gave them. */

package/dist/components/pr-pipeline.d.ts

@@ -42,6 +42,25 @@
  * build is `chant build --env <env>`, or `buildCommand` when the templates
  * come from several builds (`npm run build`).
  *
+ * With `waveGate` (#4003) the apply runs a wave at a time: `pr-apply
+ * --wave-gate <gate>`, each wave planned after the one before it applied. A
+ * generator writes one apply job per wave of the component graph
+ * (`prLoopWaveJobs`), job `apply-wave-<k>` passing `--wave <k>` and needing
+ * the job before it, and the attempt record carries the approved set from
+ * one job to the next. A wave whose plan the approved change set covers
+ * applies under the pull request's approval; one whose plan moved stops at
+ * `<gate>-wave-<k>` (exit 3), and re-running its job after the approval
+ * carries on. `chant ci serve` runs the one apply job, which runs the waves
+ * in order until one stops.
+ *
+ * Each generated job runs its command through `chant ci run plan|apply
+ * --in-place` (#4156, `PrLoopJob.run`), so a forge job writes the same run
+ * record the chant runner does: Op `pr-plan` or `pr-apply`, signed with
+ * the runner key a forge secret puts in `CHANT_RUNNER_KEY`, and naming the
+ * forge's run as its `runOrigin`. `ci run` runs `command` in the job's own
+ * checkout with the job's environment, less the key. The plan passes
+ * `--no-push`, so it still writes nothing to the remote `chant/lifecycle`.
+ *
  * In a workspace member (#3465) both commands run in the member's directory
  * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
  * note and statuses stay apart from every other member's on the same pull
@@ -49,6 +68,8 @@
  * that one of its units reaches selects that unit.
  */
 import type { ForgeKind } from "../pr-forge.js";
+import type { DriverComponent } from "./driver.js";
+import type { GatedWavePipelineOptions } from "./gated-wave-pipeline.js";
 /** Where both jobs write their reports, kept as a CI artifact. */
 export declare const PR_LOOP_REPORT_DIR = ".chant/pr";
 /**
@@ -111,6 +132,12 @@ export interface PrLoopPipelineOptions {
      * `npm run build`. Setting it turns `build` on.
      */
     buildCommand?: string;
+    /**
+     * A gate per wave on merge (#4003): the apply runs `pr-apply --wave-gate
+     * <waveGate>`, a wave at a time, and a generator writes one apply job per
+     * wave. Set from `--wave-gate` beside `--pr-loop` ({@link prLoopWithWaves}).
+     */
+    waveGate?: string;
     /**
      * Which GitHub-shaped forge the workflow is for. Set by the forgejo
      * generator, which reuses the github one; a caller never needs to.
@@ -133,6 +160,20 @@ export interface PrLoopJob {
     setup?: string[];
     /** With `build` (#4088): the build line and the lint line, run in this order before the command. */
     build?: string[];
+    /** With `waveGate` (#4003): the wave a generated apply job runs, 1-based. */
+    wave?: number;
+    /**
+     * What the generated job runs in place of `command` (#4156): `chant ci run
+     * <job> --in-place` with the same environment, gate, forge, events and
+     * report URL, which runs `command` and records the run. `env` is the
+     * job's `env` and, on GitHub and Forgejo, `CHANT_RUNNER_KEY` from the
+     * repository secret of that name. GitLab hands its CI/CD variables to a
+     * job itself.
+     */
+    run: {
+        command: string;
+        env: Record<string, string>;
+    };
 }
 /** The lines `build` (#4088) runs before a job's command: the build, then the lint. Empty without the option. */
 export declare function prLoopBuildLines(env: string, options?: PrLoopPipelineOptions): string[];
@@ -142,6 +183,22 @@ export declare function prLoopBuildLines(env: string, options?: PrLoopPipelineOp
  * relative to it.
  */
 export declare function prLoopJobs(forge: ForgeKind, env: string, options?: PrLoopPipelineOptions, member?: string): PrLoopJob[];
+/**
+ * The pull-request options with `--wave-gate` beside `--pr-loop` (#4003):
+ * the apply gets a gate per wave. A canary or a fixed base is refused, since
+ * the pull request's waves are its derivation's and each push is measured
+ * from the commit before it.
+ */
+export declare function prLoopWithWaves(prLoop: PrLoopPipelineOptions, gatedWaves?: GatedWavePipelineOptions): PrLoopPipelineOptions;
+/** The name of the apply job for wave `wave` (#4003). */
+export declare function prApplyWaveJobName(wave: number): string;
+/**
+ * One apply job per wave of the component graph (#4003), each `apply`'s
+ * command with `--wave <k>`. A change selects a subset, which never layers
+ * deeper than the graph, so a job past the change's last wave finds nothing
+ * left and exits 0.
+ */
+export declare function prLoopWaveJobs(components: DriverComponent[], apply: PrLoopJob): PrLoopJob[];
 /**
  * The concurrency group (GitHub, Forgejo) or resource group (GitLab) that
  * keeps one apply at a time per environment, and per member in a workspace.
@@ -166,8 +223,14 @@ export declare function prApplyRecordKey(env: string, commit: string, member?: s
 /**
  * GitLab sets `CI_COMMIT_BEFORE_SHA` to forty zeros on a branch's first push.
  * The line replaces it with the merge request's diff base when the pipeline
- * has one, and otherwise with the merge base of the target branch and the
- * pushed commit, or the pushed commit's parent when that is the commit itself.
+ * has one, and otherwise as {@link pushBaseFallback} does.
  */
 export declare function gitlabBaseFallback(branch?: string): string;
+/**
+ * GitHub and Forgejo set `github.event.before` to forty zeros on a branch's
+ * first push (#4004). The line replaces it as {@link pushBaseFallback} does,
+ * with the target branch `main` unless the pipeline names another, the
+ * generators' default.
+ */
+export declare function githubBaseFallback(branch?: string): string;
 //# sourceMappingURL=pr-pipeline.d.ts.map

package/dist/components/pr-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/pr-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAAmC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAAW,CAAC;AAEtC,8CAA8C;AAC9C,eAAO,MAAM,aAAa,UAEzB,CAAC;AAEF,mHAAmH;AACnH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnD;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yBAAqC,CAAC;AAErE,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC9B;AAED,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,iHAAiH;AACjH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,EAAE,CAG3F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAoC3H;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAU1D"}
+{"version":3,"file":"pr-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/pr-pipeline.ts"],"names":[],"mappings":"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"}