@intentius/chant 0.124.17 → 0.124.19

package/dist/op/op-waves-run.js

@@ -50,7 +50,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix } from "node:path";
-import { decideWaveGate, waveDigestMembers, waveSetDigest, writeWaveRecordFile } from "../wave-engine.js";
+import { decideWaveGate, runWaveLoop, waveDigestMembers, waveSetDigest, writeWaveRecordFile, } from "../wave-engine.js";
 import { approveCommand, evaluateGate, gitGateLedgerPort } from "./gate.js";
 import { isApprovalSpent } from "../lifecycle/gate-applied.js";
 import { OP_WAVE_DEFAULT_APPLY, OP_WAVE_GATE_POLICIES, OP_WAVE_HOOK_MOMENTS, GATE_APPROVAL_SOURCES, assertOpWaveHooks, assertOpWavesSpec, opWaveApplyHooksRunBy, opWaveGateName, opWaveHooksAt, opWavePointAt, opWavePointProblems, opWaveRecordPath, opWaveShare, } from "./op-waves.js";
@@ -710,7 +710,13 @@ function noteHooksAtBase(ctx, rules) {
         ctx.log(`wave ${ctx.k} (${ctx.wave.name}): its hooks are read at ${base.slice(0, 12)}, and this change's differ; the ones at base run`);
     }
 }
-/** Plan, decide and apply one wave, or one part of a wide wave. */
+/**
+ * Plan, decide and apply one wave, or one part of a wide wave: the wave
+ * engine's loop (`runWaveLoop`, #3766) over this module's steps. An apply
+ * that comes back `replan` plans the wave again (#3821), at most
+ * {@link OP_WAVE_MAX_REPLANS} times; a `rest` wave goes on through the waves
+ * its plan command found.
+ */
 export async function runOpWave(options) {
     const { spec } = options;
     assertOpWavesSpec(spec);
@@ -718,37 +724,47 @@ export async function runOpWave(options) {
     const last = spec.waves[spec.waves.length - 1];
     const applied = [];
     const rest = [];
-    for (let k = options.wave;; k++) {
-        let result;
-        let prior;
-        // #3821: an apply that came back "replan" plans the wave again, a bounded number of times.
-        for (let pass = 0;; pass++) {
-            result = await runOneWave(options, k, prior, pass);
-            if (!result.replan)
-                break;
-            if (pass + 1 >= OP_WAVE_MAX_REPLANS) {
-                log(`wave ${k}: its apply asked to plan again ${OP_WAVE_MAX_REPLANS} times, so the wave stops here`);
-                result.exitCode = 1;
-                break;
-            }
-            log(`wave ${k}: the apply applied nothing and asks to plan again${result.replan.reason ? ` (${result.replan.reason})` : ""}; planning again`);
-            prior = result.decision;
-        }
-        applied.push(...result.applied);
-        // #3821: a `rest` wave goes on through the waves its plan command found.
-        const found = result.decision?.discovered?.waves;
-        const onward = k >= spec.waves.length && last.rest === true && options.share === undefined && !options.decide && result.exitCode === 0 && found !== undefined && k < found;
-        if (rest.length > 0 || onward)
-            rest.push({ wave: k, exitCode: result.exitCode, ...(result.decision ? { digest: result.decision.digest } : {}) });
-        if (!onward)
-            return { ...result, applied, ...(rest.length > 0 ? { rest } : {}) };
-        log(`wave ${k} applied; the plan found ${found} waves, so this job goes on to wave ${k + 1}`);
-    }
+    const result = await runWaveLoop({
+        first: options.wave,
+        plan: (at) => planOpWave(options, at),
+        // A share job applies under the digest its deciding job recorded; it does not take the set digest again.
+        digest: (_at, planned) => (planned.kind === "share" ? planned.decision.digest : opWaveSetDigest(spec, planned.members, planned.extras)),
+        decide: (at, planned, digest) => (planned.kind === "share" ? shareUnmoved(planned) : decideOpWave(options, at, planned, digest)),
+        apply: (_at, planned, decided) => applyOpWave(options, planned, decided),
+        replan: (_at, outcome) => outcome.replan !== undefined,
+        maxPasses: OP_WAVE_MAX_REPLANS,
+        passesSpent({ k }, outcome) {
+            log(`wave ${k}: its apply asked to plan again ${OP_WAVE_MAX_REPLANS} times, so the wave stops here`);
+            outcome.exitCode = 1;
+            return outcome;
+        },
+        replanning({ k }, outcome) {
+            log(`wave ${k}: the apply applied nothing and asks to plan again${outcome.replan.reason ? ` (${outcome.replan.reason})` : ""}; planning again`);
+        },
+        onward(k, outcome) {
+            applied.push(...outcome.applied);
+            // #3821: a `rest` wave goes on through the waves its plan command found.
+            const found = outcome.decision?.discovered?.waves;
+            const onward = k >= spec.waves.length && last.rest === true && options.share === undefined && !options.decide && outcome.exitCode === 0 && found !== undefined && k < found;
+            if (rest.length > 0 || onward)
+                rest.push({ wave: k, exitCode: outcome.exitCode, ...(outcome.decision ? { digest: outcome.decision.digest } : {}) });
+            if (onward)
+                log(`wave ${k} applied; the plan found ${found} waves, so this job goes on to wave ${k + 1}`);
+            return onward;
+        },
+    });
+    return { ...result, applied, ...(rest.length > 0 ? { rest } : {}) };
 }
 /** How many times one wave job plans again when its apply asks to (#3821). */
 export const OP_WAVE_MAX_REPLANS = 10;
-/** Plan, decide and apply wave `k`, or one part of a wide wave. `prior`: the decision of the pass whose apply asked to plan again. */
-async function runOneWave(options, k, prior, pass) {
+/**
+ * Plan wave `k`: read its rules at base and run the before-plan hooks
+ * around planning its runs, or for a share job, read the deciding job's
+ * decision and plan the share's slice between its hooks. Ends the wave when
+ * a hook fails or holds it on another gate, or a share's decision waits or
+ * was refused.
+ */
+async function planOpWave(options, { k, pass }) {
     const { spec } = options;
     const cwd = options.cwd ?? process.cwd();
     const exec = options.exec ?? spawnExec;
@@ -779,7 +795,7 @@ async function runOneWave(options, k, prior, pass) {
         ctx.gateRule = { approval: decision.approval, base: decision.base, neverOverMcp: decision.neverOverMcp === true };
         if (decision.status === "waiting" || decision.status === "refused") {
             log(`wave ${k} (${wave.name}) is ${decision.status === "refused" ? "refused by its policy" : `waiting on ${decision.heldOn?.gate ?? decision.gate}`}; nothing applied. ${decision.approve ?? ""}`.trim());
-            return { ...result, exitCode: decision.status === "refused" ? refusedExit(decision) : 3 };
+            return { end: { ...result, exitCode: decision.status === "refused" ? refusedExit(decision) : 3 } };
         }
         // The share runs the hooks its deciding job read at base, around its own slice.
         if (wave.discover) {
@@ -790,32 +806,17 @@ async function runOneWave(options, k, prior, pass) {
         const slice = opWaveShare(wave.runs, options.share, shares);
         const before = await runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
         if (before.failed)
-            return failed(ctx, `a hook before the plan failed, so nothing in share ${options.share} of wave ${k} was planned or applied`);
+            return { end: failed(ctx, `a hook before the plan failed, so nothing in share ${options.share} of wave ${k} was planned or applied`) };
         if (before.waitingOn)
-            return waitOnOther(ctx, decision, before.waitingOn);
+            return { end: await waitOnOther(ctx, decision, before.waitingOn) };
         const { members } = planRuns(ctx, slice);
         const planned = new Map(members.map((m) => [m.member, m]));
         const after = await runHooks(ctx, "after-plan", decision.hooks?.["after-plan"], slice, planned);
         if (after.failed)
-            return failed(ctx, `a hook after the plan failed, so nothing in share ${options.share} of wave ${k} was applied`);
+            return { end: failed(ctx, `a hook after the plan failed, so nothing in share ${options.share} of wave ${k} was applied`) };
         if (after.waitingOn)
-            return waitOnOther(ctx, decision, after.waitingOn);
-        const decided = new Map(decision.members.map((m) => [m.member, m.planDigest]));
-        const unmoved = [];
-        for (const run of slice) {
-            const now = planned.get(run.target);
-            if (decided.get(run.target) !== now.planDigest) {
-                log(`${run.target}: its plan moved since wave ${k} was decided, so it was not applied. ` +
-                    `decided: ${decided.get(run.target) ?? "(not in the decision)"}; planned now: ${now.planDigest}`);
-                result.moved.push(run.target);
-                continue;
-            }
-            unmoved.push(run);
-        }
-        await applyStage(options, ctx, decision, unmoved, planned, [...before.holds, ...after.holds]);
-        if (result.exitCode === 0 && result.moved.length > 0)
-            result.exitCode = 4;
-        return result;
+            return { end: await waitOnOther(ctx, decision, after.waitingOn) };
+        return { go: { kind: "share", ctx, decision, slice, planned, holds: [...before.holds, ...after.holds] } };
     }
     // The policy, the approval mode and the hooks, read at base before anything runs.
     const rules = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
@@ -825,7 +826,7 @@ async function runOneWave(options, k, prior, pass) {
     noteHooksAtBase(ctx, rules);
     // #3836: a point at base that cannot be asked fails the wave; the ledger never stands in for it.
     if (rules.pointRefused)
-        return failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`);
+        return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`) };
     const own = opWavePointAt(spec, wave.name);
     if (JSON.stringify(own) !== JSON.stringify(rules.point)) {
         log(`wave ${k} (${wave.name}): its gate's decision point is read at ${base.slice(0, 12)} (${rules.point?.name ?? "none"}), and this change's differs (${own?.name ?? "none"}); the one at base holds`);
@@ -858,9 +859,9 @@ async function runOneWave(options, k, prior, pass) {
     };
     const before = await runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
     if (before.failed)
-        return failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`);
+        return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
     if (before.waitingOn)
-        return decided(ctx, decision, recordPath, before.waitingOn);
+        return { end: await decided(ctx, decision, recordPath, before.waitingOn) };
     const { members, pending, overriders, overridersSource, extras, waves: found } = planRuns(ctx, wave.runs, wave.discover === true);
     if (wave.discover) {
         wave = { ...wave, runs: members.map((m) => ({ target: m.member, ...(m.op !== spec.op ? { op: m.op } : {}) })) };
@@ -869,47 +870,96 @@ async function runOneWave(options, k, prior, pass) {
         log(`wave ${k} (${wave.name}): the plan found ${members.length} run${members.length === 1 ? "" : "s"}${found !== undefined ? ` of ${found} waves` : ""}${members.length ? `: ${members.map((m) => m.member).join(", ")}` : ""}`);
     }
     const planned = new Map(members.map((m) => [m.member, m]));
-    const digest = opWaveSetDigest(spec, members, extras);
+    return {
+        go: {
+            kind: "decide",
+            ctx,
+            recordPath,
+            rules,
+            decision,
+            holds,
+            before: before.holds,
+            members,
+            planned,
+            ...(pending ? { pending } : {}),
+            ...(overriders ? { overriders } : {}),
+            ...(overridersSource ? { overridersSource } : {}),
+            ...(extras ? { extras } : {}),
+        },
+    };
+}
+/**
+ * A share job's decision is its deciding job's: it applies the runs of its
+ * slice whose plan has not moved since, and names each one that has.
+ */
+async function shareUnmoved(planned) {
+    const { ctx, decision, slice, holds } = planned;
+    const decidedDigests = new Map(decision.members.map((m) => [m.member, m.planDigest]));
+    const unmoved = [];
+    for (const run of slice) {
+        const now = planned.planned.get(run.target);
+        if (decidedDigests.get(run.target) !== now.planDigest) {
+            ctx.log(`${run.target}: its plan moved since wave ${ctx.k} was decided, so it was not applied. ` +
+                `decided: ${decidedDigests.get(run.target) ?? "(not in the decision)"}; planned now: ${now.planDigest}`);
+            ctx.result.moved.push(run.target);
+            continue;
+        }
+        unmoved.push(run);
+    }
+    return { go: { runs: unmoved, earlierHolds: holds } };
+}
+/**
+ * Decide wave `k` against its set digest: run the after-plan hooks, settle
+ * the product's denials and the gate under the rules read at base, write the
+ * decision record and run the after-gate hooks. Ends the wave when it waits,
+ * is refused or failed, and for a deciding job (`--decide`), which spends the
+ * approval and overrides its shares apply under and applies nothing.
+ */
+async function decideOpWave(options, { prior }, planned, digest) {
+    const { ctx, recordPath, decision, holds, members, pending, overriders, overridersSource, extras } = planned;
+    const { k, wave, log, result } = ctx;
+    const { policy, source, base } = planned.rules;
     decision.digest = digest;
     decision.members = members;
     if (extras)
         decision.extras = extras;
     if (pending)
         decision.pending = pending;
-    const after = await runHooks(ctx, "after-plan", rules.hooks["after-plan"], wave.runs, planned, digest);
+    const after = await runHooks(ctx, "after-plan", planned.rules.hooks["after-plan"], wave.runs, planned.planned, digest);
     if (after.failed)
-        return failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`);
-    holds.push(...before.holds, ...after.holds);
+        return { end: failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`) };
+    holds.push(...planned.before, ...after.holds);
     if (holds.length > 0)
         decision.heldBy = holds;
     if (after.waitingOn)
-        return decided(ctx, decision, recordPath, after.waitingOn);
+        return { end: await decided(ctx, decision, recordPath, after.waitingOn) };
     // #3821: a run the product's policy denied applies only under an override; with none the wave is refused, and no approval is waited for.
-    const kept = prior !== undefined && (prior.status === "approved" || prior.status === "not-required") && prior.digest === digest;
+    const was = prior?.decision;
+    const kept = was !== undefined && (was.status === "approved" || was.status === "not-required") && was.digest === digest;
     if (kept) {
         // The overrides this job applied under, and spent, still let the same plans through.
-        const byRun = new Map(prior.members.map((m) => [m.member, m.override]));
+        const byRun = new Map(was.members.map((m) => [m.member, m.override]));
         for (const m of members)
             if (m.denied && byRun.get(m.member))
                 m.override = byRun.get(m.member);
-        if (prior.overridesSpentAt)
-            decision.overridesSpentAt = prior.overridesSpentAt;
+        if (was.overridesSpentAt)
+            decision.overridesSpentAt = was.overridesSpentAt;
     }
     if (members.some((m) => m.denied && !m.override))
         await settleDenials(ctx, decision, overriders, overridersSource);
-    if (kept && prior.status === "approved" && decision.status !== "refused") {
+    if (kept && was.status === "approved" && decision.status !== "refused") {
         // #3821: planned again after the apply asked to, to the same digest: the approval this job found still holds, and is not spent twice.
         for (const key of ["via", "approvedBy", "approvedAt", "review", "spentAt"])
-            if (prior[key] !== undefined)
-                decision[key] = prior[key];
+            if (was[key] !== undefined)
+                decision[key] = was[key];
         decision.status = "approved";
-        log(`wave ${k} (${wave.name}): planned again to the same digest, so the approval by ${prior.approvedBy} still holds`);
+        log(`wave ${k} (${wave.name}): planned again to the same digest, so the approval by ${was.approvedBy} still holds`);
     }
     else if (decision.status !== "refused" && (opWaveNeedsApproval(policy, members) || holds.length > 0))
         await settleGate(options, ctx, decision);
     const code = await decided(ctx, decision, recordPath);
     if (code.exitCode !== 0)
-        return code;
+        return { end: code };
     log(`wave ${k} (${wave.name}): gate ${policy} (read at ${base.slice(0, 12)}${source === "absent-at-base" ? ", where the wave is absent" : ""}), ` +
         `digest ${digest}: ${decision.status}${decision.approvedBy ? ` by ${decision.approvedBy}` : ""}` +
         (decision.via === "pr-review" ? ` (review of #${decision.review?.pr})` : "") +
@@ -917,13 +967,20 @@ async function runOneWave(options, k, prior, pass) {
     // A wide wave's shares apply under the deciding job's approval and overrides, so they are spent here, once.
     if (options.decide) {
         if (!(await spendApproval(options, ctx, decision)) || !(await spendOverrides(ctx, decision)))
-            return ctx.result;
+            return { end: ctx.result };
         if (decision.spentAt || decision.overridesSpentAt)
             writeRecord(recordPath, decision, result);
-        return result;
+        return { end: result };
     }
-    await applyStage(options, ctx, decision, wave.runs, planned, [], recordPath);
-    return result;
+    return { go: { runs: wave.runs, earlierHolds: [], recordPath } };
+}
+/** Apply a decided wave, or a share's unmoved runs (exit 4 when any moved). */
+async function applyOpWave(options, planned, decidedWave) {
+    const { ctx, decision } = planned;
+    await applyStage(options, ctx, decision, decidedWave.runs, planned.planned, decidedWave.earlierHolds, decidedWave.recordPath);
+    if (planned.kind === "share" && ctx.result.exitCode === 0 && ctx.result.moved.length > 0)
+        ctx.result.exitCode = 4;
+    return ctx.result;
 }
 /**
  * The gate has decided (#3821): write the decision record, run the

package/dist/wave-engine.d.ts

@@ -8,6 +8,9 @@
  * - The share split of a wide wave: {@link waveShare}.
  * - The gate decision call: {@link decideWaveGate}.
  * - The record file a wave job hands the next one: {@link writeWaveRecordFile}.
+ * - The loop itself: {@link runWaveLoop} plans a wave, takes its set digest,
+ *   decides its gate and applies it, then goes on to the next wave or plans
+ *   the same one again, as the entry point's steps say.
  *
  * The parts that need neither the gate ledger nor the filesystem live in
  * `./gated-waves.ts`, which terragucci bundles on its own (#3421), and
@@ -15,11 +18,12 @@
  * use it without the change-set code; this module re-exports both so a
  * runner imports the engine from one place.
  *
- * What stays with each entry point: how a wave is planned (Op runs' plan
- * commands, or each component's capabilities), the gate policy, approval
- * mode, decision point, hooks and spend rule (Op waves only), and the shape
- * of the record each writes. Those shapes are read by jobs and approvals
- * already in the wild, so the engine writes what it is handed.
+ * What stays with each entry point, as the steps it hands {@link runWaveLoop}:
+ * how a wave is planned (Op runs' plan commands, or each component's
+ * capabilities), which members its digest covers, the gate policy, approval
+ * mode, decision point, hooks and spend rule (Op waves only), how it applies,
+ * and the shape of the record each writes. Those shapes are read by jobs and
+ * approvals already in the wild, so the engine writes what it is handed.
  */
 import { type GateCheck, type GateLedgerPort } from "./op/gate.js";
 import type { AppliedGateRecord } from "./lifecycle/gate-applied.js";
@@ -59,4 +63,69 @@ export declare function decideWaveGate(port: GateLedgerPort, request: WaveGateRe
  * through it.
  */
 export declare function writeWaveRecordFile(path: string, value: unknown): void;
+/**
+ * What a step hands {@link runWaveLoop}: `go` carries a value into the
+ * wave's next step; `end` ends the wave with its outcome, and nothing after
+ * that step runs for it.
+ */
+export type WaveStep<T, R> = {
+    go: T;
+} | {
+    end: R;
+};
+/** Where the loop is: wave `k` (1-based), its `pass`, and the outcome of the pass before when the wave is planned again. */
+export interface WaveAttempt<R> {
+    k: number;
+    /** 0 on a wave's first plan. */
+    pass: number;
+    /** The outcome of the pass that asked to plan again. */
+    prior?: R;
+}
+/**
+ * The steps an entry point hands {@link runWaveLoop}, typed by what planning
+ * gives (`P`), what deciding gives (`D`) and a wave's outcome (`R`).
+ *
+ * The two entry points differ in each step, on purpose:
+ *
+ * - `chant run wave` (Op waves) plans with argv commands and hooks, takes
+ *   the digest under `digest.over` with the plans file's extras, decides
+ *   with the approval mode, decision point, spend rule, denials and pending
+ *   fields read at base, and runs one wave per job (a `rest` wave walks on,
+ *   an apply may ask to plan again; a share job applies under its deciding
+ *   job's decision).
+ * - `chant components fan-out --wave-gate` plans each component's
+ *   capabilities, takes the digest over every member (a wave where nothing
+ *   planned has the empty digest, and one where nothing is left to run skips
+ *   its gate), asks the plain ledger, and walks every wave in one job.
+ */
+export interface WaveLoopSteps<P, D, R> {
+    /** The first wave's number. */
+    first: number;
+    /** Plan the wave, or end it before it has a set (nothing to run, a hook failed or waits). */
+    plan(at: WaveAttempt<R>): Promise<WaveStep<P, R>>;
+    /** The wave's set digest over what was planned. */
+    digest(at: WaveAttempt<R>, planned: P): string;
+    /** Decide the wave's gate against its digest: what the apply goes ahead under, or the outcome when the wave stops here. */
+    decide(at: WaveAttempt<R>, planned: P, digest: string): Promise<WaveStep<D, R>>;
+    /** Apply the decided wave. */
+    apply(at: WaveAttempt<R>, planned: P, decided: D): Promise<R>;
+    /** Whether the outcome asks for the same wave to be planned again in this job. Absent: never. */
+    replan?(at: WaveAttempt<R>, outcome: R): boolean;
+    /** How many passes one wave gets before a replan is refused. Default 1. */
+    maxPasses?: number;
+    /** The wave asked to plan again after its last pass: the outcome it ends with. */
+    passesSpent?(at: WaveAttempt<R>, outcome: R): R;
+    /** Called before another pass at the same wave. */
+    replanning?(at: WaveAttempt<R>, outcome: R): void;
+    /** The wave ended with `outcome`: whether the job goes on to wave `k + 1`. */
+    onward(k: number, outcome: R): boolean;
+}
+/**
+ * The wave loop both entry points run (#3766): for each wave, plan it, take
+ * its set digest, decide its gate and apply it; plan it again while its
+ * outcome asks to, up to `maxPasses`; then go on to the next wave while
+ * `onward` says so. Returns the outcome of the last wave it ran. A step that
+ * throws ends the loop with that error.
+ */
+export declare function runWaveLoop<P, D, R>(steps: WaveLoopSteps<P, D, R>): Promise<R>;
 //# sourceMappingURL=wave-engine.d.ts.map

package/dist/wave-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wave-engine.d.ts","sourceRoot":"","sources":["../src/wave-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,EACL,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,eAAe,CAAC;AAEvB,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAYjG;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAKtE"}
+{"version":3,"file":"wave-engine.d.ts","sourceRoot":"","sources":["../src/wave-engine.ts"],"names":[],"mappings":"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"}

package/dist/wave-engine.js

@@ -8,6 +8,9 @@
  * - The share split of a wide wave: {@link waveShare}.
  * - The gate decision call: {@link decideWaveGate}.
  * - The record file a wave job hands the next one: {@link writeWaveRecordFile}.
+ * - The loop itself: {@link runWaveLoop} plans a wave, takes its set digest,
+ *   decides its gate and applies it, then goes on to the next wave or plans
+ *   the same one again, as the entry point's steps say.
  *
  * The parts that need neither the gate ledger nor the filesystem live in
  * `./gated-waves.ts`, which terragucci bundles on its own (#3421), and
@@ -15,11 +18,12 @@
  * use it without the change-set code; this module re-exports both so a
  * runner imports the engine from one place.
  *
- * What stays with each entry point: how a wave is planned (Op runs' plan
- * commands, or each component's capabilities), the gate policy, approval
- * mode, decision point, hooks and spend rule (Op waves only), and the shape
- * of the record each writes. Those shapes are read by jobs and approvals
- * already in the wild, so the engine writes what it is handed.
+ * What stays with each entry point, as the steps it hands {@link runWaveLoop}:
+ * how a wave is planned (Op runs' plan commands, or each component's
+ * capabilities), which members its digest covers, the gate policy, approval
+ * mode, decision point, hooks and spend rule (Op waves only), how it applies,
+ * and the shape of the record each writes. Those shapes are read by jobs and
+ * approvals already in the wild, so the engine writes what it is handed.
  */
 import { dirname } from "node:path";
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
@@ -57,3 +61,41 @@ export function writeWaveRecordFile(path, value) {
     writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n");
     renameSync(temporary, path);
 }
+/**
+ * The wave loop both entry points run (#3766): for each wave, plan it, take
+ * its set digest, decide its gate and apply it; plan it again while its
+ * outcome asks to, up to `maxPasses`; then go on to the next wave while
+ * `onward` says so. Returns the outcome of the last wave it ran. A step that
+ * throws ends the loop with that error.
+ */
+export async function runWaveLoop(steps) {
+    for (let k = steps.first;; k++) {
+        let outcome;
+        let prior;
+        for (let pass = 0;; pass++) {
+            const at = { k, pass, ...(prior !== undefined ? { prior } : {}) };
+            outcome = await runWave(steps, at);
+            if (!steps.replan?.(at, outcome))
+                break;
+            if (pass + 1 >= (steps.maxPasses ?? 1)) {
+                outcome = steps.passesSpent ? steps.passesSpent(at, outcome) : outcome;
+                break;
+            }
+            steps.replanning?.(at, outcome);
+            prior = outcome;
+        }
+        if (!steps.onward(k, outcome))
+            return outcome;
+    }
+}
+/** One pass at one wave: plan, digest, decide, apply. */
+async function runWave(steps, at) {
+    const planned = await steps.plan(at);
+    if ("end" in planned)
+        return planned.end;
+    const digest = steps.digest(at, planned.go);
+    const decided = await steps.decide(at, planned.go, digest);
+    if ("end" in decided)
+        return decided.end;
+    return steps.apply(at, planned.go, decided.go);
+}