@intentius/chant 0.124.92 → 0.124.94

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/dist/__golden__/notify-defaults-plain.json +52 -0
  2. package/dist/__golden__/notify-defaults-relay.json +92 -0
  3. package/dist/ci-job-guard.d.ts +22 -8
  4. package/dist/ci-job-guard.d.ts.map +1 -1
  5. package/dist/ci-job-guard.js +93 -49
  6. package/dist/ci-jobs.d.ts +22 -0
  7. package/dist/ci-jobs.d.ts.map +1 -1
  8. package/dist/ci-jobs.js +23 -0
  9. package/dist/ci-product.d.ts +41 -1
  10. package/dist/ci-product.d.ts.map +1 -1
  11. package/dist/ci-product.js +45 -5
  12. package/dist/cli/handlers/run-wave.js +17 -3
  13. package/dist/cli/main.d.ts.map +1 -1
  14. package/dist/cli/main.js +4 -1
  15. package/dist/components/product-pipeline.d.ts +30 -0
  16. package/dist/components/product-pipeline.d.ts.map +1 -1
  17. package/dist/components/product-pipeline.js +28 -3
  18. package/dist/floor-table.data.d.ts.map +1 -1
  19. package/dist/floor-table.data.js +17 -4
  20. package/dist/gate-resume-run.d.ts +7 -0
  21. package/dist/gate-resume-run.d.ts.map +1 -1
  22. package/dist/gate-resume-run.js +42 -3
  23. package/dist/lexicon.d.ts +64 -1
  24. package/dist/lexicon.d.ts.map +1 -1
  25. package/dist/lifecycle/gate-applied.d.ts +18 -0
  26. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  27. package/dist/notify.d.ts +8 -0
  28. package/dist/notify.d.ts.map +1 -1
  29. package/dist/notify.js +8 -3
  30. package/dist/op/before-merge.d.ts +8 -0
  31. package/dist/op/before-merge.d.ts.map +1 -1
  32. package/dist/op/before-merge.js +6 -0
  33. package/dist/op/gate-run-locator.d.ts +17 -0
  34. package/dist/op/gate-run-locator.d.ts.map +1 -1
  35. package/dist/op/index.d.ts +4 -2
  36. package/dist/op/index.d.ts.map +1 -1
  37. package/dist/op/index.js +3 -2
  38. package/dist/op/op-waves-names.d.ts +65 -2
  39. package/dist/op/op-waves-names.d.ts.map +1 -1
  40. package/dist/op/op-waves-names.js +129 -0
  41. package/dist/op/op-waves-remainder.d.ts +110 -0
  42. package/dist/op/op-waves-remainder.d.ts.map +1 -0
  43. package/dist/op/op-waves-remainder.js +120 -0
  44. package/dist/op/op-waves-render-spec.d.ts +63 -5
  45. package/dist/op/op-waves-render-spec.d.ts.map +1 -1
  46. package/dist/op/op-waves-render-spec.js +68 -10
  47. package/dist/op/op-waves-run.d.ts +29 -1
  48. package/dist/op/op-waves-run.d.ts.map +1 -1
  49. package/dist/op/op-waves-run.js +194 -6
  50. package/dist/op/op-waves-split-resume.d.ts +57 -0
  51. package/dist/op/op-waves-split-resume.d.ts.map +1 -0
  52. package/dist/op/op-waves-split-resume.js +94 -0
  53. package/dist/op/op-waves-stand-down.d.ts +9 -1
  54. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  55. package/dist/op/op-waves-stand-down.js +14 -2
  56. package/dist/op/op-waves.d.ts +38 -2
  57. package/dist/op/op-waves.d.ts.map +1 -1
  58. package/dist/op/op-waves.js +13 -2
  59. package/dist/release-floors.d.ts +9 -1
  60. package/dist/release-floors.d.ts.map +1 -1
  61. package/dist/release-floors.js +9 -1
  62. package/dist/wave-runtime.mjs +368 -368
  63. package/package.json +1 -1
  64. package/src/__golden__/notify-defaults-plain.json +52 -0
  65. package/src/__golden__/notify-defaults-relay.json +92 -0
  66. package/src/ci-job-guard.default-branch.test.ts +125 -0
  67. package/src/ci-job-guard.ts +64 -10
  68. package/src/ci-jobs.ts +26 -0
  69. package/src/ci-product.ts +54 -5
  70. package/src/cli/handlers/run-wave.ts +16 -3
  71. package/src/cli/main.ts +4 -1
  72. package/src/components/product-pipeline.ts +49 -4
  73. package/src/floor-table.data.ts +17 -4
  74. package/src/gate-resume-run.ts +38 -3
  75. package/src/lexicon.ts +64 -1
  76. package/src/lifecycle/gate-applied.ts +16 -0
  77. package/src/notify-bundle.test.ts +3 -2
  78. package/src/notify-relay-name.test.ts +72 -0
  79. package/src/notify.ts +16 -3
  80. package/src/op/before-merge.ts +12 -0
  81. package/src/op/gate-run-locator.ts +14 -0
  82. package/src/op/index.ts +6 -1
  83. package/src/op/op-waves-names.ts +130 -2
  84. package/src/op/op-waves-remainder.test.ts +342 -0
  85. package/src/op/op-waves-remainder.ts +146 -0
  86. package/src/op/op-waves-render-spec.test.ts +107 -0
  87. package/src/op/op-waves-render-spec.ts +81 -10
  88. package/src/op/op-waves-run.ts +204 -7
  89. package/src/op/op-waves-split-resume.test.ts +149 -0
  90. package/src/op/op-waves-split-resume.ts +109 -0
  91. package/src/op/op-waves-stand-down.ts +15 -2
  92. package/src/op/op-waves.ts +46 -3
  93. package/src/release-floors.ts +13 -1
@@ -15,14 +15,20 @@ import { gitShowAtBase, parseOpWavesSpec, readOpWavePolicy, runOpWave, type OpWa
15
15
  import { memoryGateLedgerPort } from "./gate";
16
16
  import {
17
17
  commandSpecRender,
18
+ OP_WAVES_SPEC_BASE_ENV,
18
19
  OP_WAVES_SPEC_COMMAND_ENV,
20
+ OP_WAVES_SPEC_RUNS_ENV,
19
21
  opWavesRenderSpecEnv,
20
22
  opWavesSpecCommandFromEnv,
23
+ opWavesSpecRunsAtHead,
21
24
  renderedJobMissing,
22
25
  renderedSpecShow,
26
+ renderOpWavesJobSpec,
23
27
  renderOpWavesSpecFile,
24
28
  RUNTIME_WAVES_SPEC_FLOOR,
29
+ RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR,
25
30
  } from "./op-waves-render-spec";
31
+ import { NEXT_RELEASE } from "../release-floors";
26
32
  import type { OpWavesSpec } from "./op-waves";
27
33
  import { parseArgs } from "../cli/parse-args";
28
34
  import { runOpWaveCommand } from "../cli/handlers/run-wave";
@@ -44,6 +50,21 @@ process.stdout.write(JSON.stringify({
44
50
  }));
45
51
  `;
46
52
 
53
+ /** #5046: a product whose runs are in its config too; it logs each commit it is handed and the base beside it. */
54
+ const RUNS_JS = `
55
+ const { execFileSync } = require("node:child_process");
56
+ const { appendFileSync } = require("node:fs");
57
+ const at = process.env.CHANT_WAVES_SPEC_AT;
58
+ if (process.env.RENDER_LOG) appendFileSync(process.env.RENDER_LOG, at + " base=" + (process.env.CHANT_WAVES_SPEC_BASE ?? "") + "\\n");
59
+ let config;
60
+ try { config = JSON.parse(execFileSync("git", ["show", at + ":config.json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] })); } catch { process.exit(0); }
61
+ process.stdout.write(JSON.stringify({
62
+ name: "tf-apply", op: "tf-apply",
63
+ plan: ["tool", "plan", "{target}", "--out", "{plan}"], apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
64
+ waves: [{ name: "dev", gate: config.gate, shares: 2, runs: config.runs.map((target) => ({ target })) }],
65
+ }));
66
+ `;
67
+
47
68
  let repo: string;
48
69
  let tools: string;
49
70
  let command: string[];
@@ -128,6 +149,7 @@ describe("a waves spec the job renders at run time (#4982)", () => {
128
149
  expect(renderedJobMissing(spec, 2, { group: "us" })).toBe('wave 2 (g) has no job group "us" in the spec rendered at base');
129
150
  expect(renderedJobMissing(spec, 2, { group: "eu", share: 3 })).toBe('job group "eu" of wave 2 (g) has 2 shares in the spec rendered at base');
130
151
  expect(renderedJobMissing(spec, 2, { group: "eu", share: 1 })).toBeUndefined();
152
+ expect(renderedJobMissing(spec, 1, { share: 3 }, "head")).toBe("wave 1 (w) has 2 shares in the spec rendered at head");
131
153
  });
132
154
 
133
155
  test("the command comes from CHANT_WAVES_SPEC_COMMAND as a JSON list of words", () => {
@@ -140,6 +162,91 @@ describe("a waves spec the job renders at run time (#4982)", () => {
140
162
  expect(RUNTIME_WAVES_SPEC_FLOOR).toBe("0.124.89");
141
163
  });
142
164
 
165
+ test("runsAtHead (#5046): the job's runs come from the render at the applied commit, the gate from the render at base", async () => {
166
+ // The product's runs are in its config too: the change adds root c and loosens the gate.
167
+ writeFileSync(join(tools, "runs.cjs"), RUNS_JS);
168
+ const runs = [process.execPath, join(tools, "runs.cjs")];
169
+ const log = join(tools, "renders.log");
170
+ git("checkout", "-q", "HEAD^1");
171
+ writeFileSync(join(repo, "config.json"), JSON.stringify({ gate: "always", runs: ["a", "b"] }));
172
+ git("commit", "-q", "-am", "runs at base");
173
+ const baseSha = git("rev-parse", "HEAD");
174
+ writeFileSync(join(repo, "config.json"), JSON.stringify({ gate: "never", runs: ["a", "b", "c"] }));
175
+ git("commit", "-q", "-am", "add c and loosen");
176
+ const headSha = git("rev-parse", "HEAD");
177
+ process.env.RENDER_LOG = log;
178
+ try {
179
+ const rendered = renderOpWavesJobSpec({
180
+ specFile: SPEC_FILE,
181
+ base: "HEAD^1",
182
+ cwd: repo,
183
+ render: commandSpecRender(runs, SPEC_FILE, repo),
184
+ fallback: gitShowAtBase,
185
+ parse: parseOpWavesSpec,
186
+ runsAtHead: true,
187
+ headRender: (sha) => commandSpecRender(runs, SPEC_FILE, repo, { [OP_WAVES_SPEC_BASE_ENV]: sha }),
188
+ });
189
+ expect(rendered).toMatchObject({ at: "head", sha: headSha });
190
+ expect(rendered.spec.waves[0]!.runs.map((r) => r.target)).toEqual(["a", "b", "c"]);
191
+ expect(parseOpWavesSpec(readFileSync(join(repo, SPEC_FILE), "utf-8"), "file").waves[0]!.runs).toHaveLength(3);
192
+ const rules = readOpWavePolicy(SPEC_FILE, "dev", "HEAD^1", repo, rendered.show);
193
+ expect(rules).toMatchObject({ policy: "always", source: "base", base: baseSha });
194
+ // The head render alone is handed the base; the rules render is the base's own.
195
+ expect(readFileSync(log, "utf-8").trim().split("\n")).toEqual([`${headSha} base=${baseSha}`, `${baseSha} base=`]);
196
+ const applied: string[] = [];
197
+ const exec: OpWaveExec = (argv, dir) => {
198
+ if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ planDigest: `sha256:${"1".repeat(64)}`, changes: { create: 1 } }));
199
+ if (argv[1] === "apply") applied.push(argv[2]!);
200
+ return 0;
201
+ };
202
+ const result = await runOpWave({ spec: rendered.spec, specFile: SPEC_FILE, wave: 1, cwd: repo, exec, show: rendered.show, gates: memoryGateLedgerPort(), head: headSha });
203
+ expect(result.exitCode).toBe(3);
204
+ expect(result.decision).toMatchObject({ status: "waiting", policy: "always" });
205
+ expect(result.decision!.members.map((m) => m.member).sort()).toEqual(["a", "b", "c"]);
206
+ expect(applied).toEqual([]);
207
+ // Off by default: the runs are the base's.
208
+ const off = renderOpWavesJobSpec({ specFile: SPEC_FILE, base: "HEAD^1", cwd: repo, render: commandSpecRender(runs, SPEC_FILE, repo), fallback: gitShowAtBase, parse: parseOpWavesSpec });
209
+ expect(off).toMatchObject({ at: "base", sha: baseSha });
210
+ expect(off.spec.waves[0]!.runs.map((r) => r.target)).toEqual(["a", "b"]);
211
+ } finally {
212
+ delete process.env.RENDER_LOG;
213
+ }
214
+ });
215
+
216
+ test("CHANT_WAVES_SPEC_RUNS is head or unset", () => {
217
+ expect(opWavesSpecRunsAtHead({})).toBe(false);
218
+ expect(opWavesSpecRunsAtHead({ [OP_WAVES_SPEC_RUNS_ENV]: "head" })).toBe(true);
219
+ expect(() => opWavesSpecRunsAtHead({ [OP_WAVES_SPEC_RUNS_ENV]: "base" })).toThrow(/CHANT_WAVES_SPEC_RUNS is head or unset/);
220
+ expect(opWavesRenderSpecEnv({ command: ["terragucci", "waves-spec"], runsAtHead: true })).toEqual({ CHANT_WAVES_SPEC_COMMAND: '["terragucci","waves-spec"]', CHANT_WAVES_SPEC_RUNS: "head" });
221
+ expect(opWavesRenderSpecEnv({ command: ["terragucci", "waves-spec"], runsAtHead: false })).toEqual({ CHANT_WAVES_SPEC_COMMAND: '["terragucci","waves-spec"]' });
222
+ expect(RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR).toBe(NEXT_RELEASE);
223
+ });
224
+
225
+ test("chant run wave --render-spec with CHANT_WAVES_SPEC_RUNS=head writes the spec rendered at HEAD (#5046)", async () => {
226
+ writeFileSync(join(tools, "runs.cjs"), RUNS_JS);
227
+ git("checkout", "-q", "HEAD^1");
228
+ writeFileSync(join(repo, "config.json"), JSON.stringify({ gate: "always", runs: ["a"] }));
229
+ git("commit", "-q", "-am", "runs at base");
230
+ writeFileSync(join(repo, "config.json"), JSON.stringify({ gate: "always", runs: ["a", "b"] }));
231
+ git("commit", "-q", "-am", "add b");
232
+ const was = process.cwd();
233
+ const saved = { command: process.env[OP_WAVES_SPEC_COMMAND_ENV], runs: process.env[OP_WAVES_SPEC_RUNS_ENV] };
234
+ process.env[OP_WAVES_SPEC_COMMAND_ENV] = JSON.stringify([process.execPath, join(tools, "runs.cjs")]);
235
+ process.env[OP_WAVES_SPEC_RUNS_ENV] = "head";
236
+ process.chdir(repo);
237
+ try {
238
+ const ctx = { args: parseArgs(["run", "wave", "--spec", SPEC_FILE, "--wave", "1", "--share", "3", "--render-spec"]), plugins: [], serializers: [] } as unknown as CommandContext;
239
+ expect(await runOpWaveCommand(ctx)).toBe(0);
240
+ expect(parseOpWavesSpec(readFileSync(join(repo, SPEC_FILE), "utf-8"), "file").waves[0]!.runs.map((r) => r.target)).toEqual(["a", "b"]);
241
+ } finally {
242
+ process.chdir(was);
243
+ for (const [k, v] of [[OP_WAVES_SPEC_COMMAND_ENV, saved.command], [OP_WAVES_SPEC_RUNS_ENV, saved.runs]] as const) {
244
+ if (v === undefined) delete process.env[k];
245
+ else process.env[k] = v;
246
+ }
247
+ }
248
+ });
249
+
143
250
  test("chant run wave --render-spec writes the rendered spec, and a share it does not have exits 0", async () => {
144
251
  const was = process.cwd();
145
252
  const env = process.env[OP_WAVES_SPEC_COMMAND_ENV];
@@ -37,6 +37,22 @@
37
37
  * not applies nothing and exits 0, since the job exists before the runs
38
38
  * are known.
39
39
  *
40
+ * With `runsAtHead` (#5046) the job takes its runs from the applied commit,
41
+ * as a job reading a committed spec does. The job carries
42
+ * `CHANT_WAVES_SPEC_RUNS=head`, and chant renders the job's own spec at the
43
+ * commit the job checked out (the pushed commit, a follow-on's
44
+ * `CHANT_WAVES_COMMIT`, or before merge the decided head), with
45
+ * `CHANT_WAVES_SPEC_BASE` set to the base commit beside `CHANT_WAVES_SPEC_AT`,
46
+ * so the command can work out what the change reaches. That spec is the
47
+ * one written over `specFile`: its waves' runs, shares and groups are the
48
+ * ones the job plans and applies. The gate policy, the holds, the hooks and
49
+ * the evidence rules are still read from the render at base, which carries
50
+ * no `CHANT_WAVES_SPEC_BASE`, so the change cannot loosen its own gate. A
51
+ * wave the base render does not have waits as `always`. The gate and record
52
+ * jobs of a split wave run the default branch's code and take the runs from
53
+ * the saved plan, so they render at base as before. The stand-down's render
54
+ * of a newer commit carries no `CHANT_WAVES_SPEC_BASE` either.
55
+ *
40
56
  * Nothing here imports the wave runner, so the generators' bundles take
41
57
  * the variables without it; `chant run wave` hands in its git reader.
42
58
  */
@@ -47,7 +63,7 @@ import { dirname, isAbsolute, join, posix } from "node:path";
47
63
  import type { OpWaveShowAtBase } from "./op-waves-run";
48
64
  import type { OpWavesSpec } from "./op-waves";
49
65
 
50
- export { RUNTIME_WAVES_SPEC_FLOOR } from "../release-floors";
66
+ export { RUNTIME_WAVES_SPEC_FLOOR, RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR } from "../release-floors";
51
67
 
52
68
  /** The job variable that holds the product command printing the spec, as a JSON argv. */
53
69
  export const OP_WAVES_SPEC_COMMAND_ENV = "CHANT_WAVES_SPEC_COMMAND";
@@ -57,11 +73,22 @@ export const OP_WAVES_SPEC_AT_ENV = "CHANT_WAVES_SPEC_AT";
57
73
  export const OP_WAVES_SPEC_FILE_ENV = "CHANT_WAVES_SPEC_FILE";
58
74
  /** The `chant run wave` flag that renders the spec before the job runs. */
59
75
  export const OP_WAVES_RENDER_SPEC_FLAG = "--render-spec";
76
+ /** The job variable that has the job take its runs from the applied commit (#5046): `head`. */
77
+ export const OP_WAVES_SPEC_RUNS_ENV = "CHANT_WAVES_SPEC_RUNS";
78
+ /** The variable chant hands the command in the job's own render under `runsAtHead` (#5046): the full base commit. */
79
+ export const OP_WAVES_SPEC_BASE_ENV = "CHANT_WAVES_SPEC_BASE";
60
80
 
61
81
  /** `OpWavesPipelineOptions.renderSpec` (#4982). */
62
82
  export interface OpWavesRenderSpec {
63
83
  /** The product command that prints the spec at `CHANT_WAVES_SPEC_AT`, such as `["terragucci", "waves-spec"]`. */
64
84
  command: string[];
85
+ /**
86
+ * The job takes its runs from the spec the command prints at the applied
87
+ * commit, and the rules from the one it prints at base (#5046). The jobs
88
+ * carry `CHANT_WAVES_SPEC_RUNS=head`. Default false: the job runs the
89
+ * spec printed at base.
90
+ */
91
+ runsAtHead?: boolean;
65
92
  }
66
93
 
67
94
  /** What is wrong with a `renderSpec`, or nothing. */
@@ -70,6 +97,8 @@ export function opWavesRenderSpecProblems(value: unknown): string[] {
70
97
  if (!Array.isArray(command) || command.length === 0 || command.some((w) => typeof w !== "string" || w.length === 0)) {
71
98
  return ['renderSpec.command must be the product command that prints the spec, as a list of words: ["terragucci", "waves-spec"]'];
72
99
  }
100
+ const runsAtHead = (value as { runsAtHead?: unknown }).runsAtHead;
101
+ if (runsAtHead !== undefined && typeof runsAtHead !== "boolean") return ["renderSpec.runsAtHead must be true or false"];
73
102
  return [];
74
103
  }
75
104
 
@@ -78,7 +107,15 @@ export function opWavesRenderSpecEnv(renderSpec: OpWavesRenderSpec | undefined):
78
107
  if (renderSpec === undefined) return {};
79
108
  const problems = opWavesRenderSpecProblems(renderSpec);
80
109
  if (problems.length > 0) throw new Error(problems.join("; "));
81
- return { [OP_WAVES_SPEC_COMMAND_ENV]: JSON.stringify(renderSpec.command) };
110
+ return { [OP_WAVES_SPEC_COMMAND_ENV]: JSON.stringify(renderSpec.command), ...(renderSpec.runsAtHead === true ? { [OP_WAVES_SPEC_RUNS_ENV]: "head" } : {}) };
111
+ }
112
+
113
+ /** Whether the job takes its runs from the applied commit (#5046): `CHANT_WAVES_SPEC_RUNS` is `head`. Throws on any other value. */
114
+ export function opWavesSpecRunsAtHead(env: NodeJS.ProcessEnv = process.env): boolean {
115
+ const raw = env[OP_WAVES_SPEC_RUNS_ENV];
116
+ if (raw === undefined || raw === "") return false;
117
+ if (raw === "head") return true;
118
+ throw new Error(`${OP_WAVES_SPEC_RUNS_ENV} is head or unset: got ${JSON.stringify(raw)}`);
82
119
  }
83
120
 
84
121
  /** The product command `CHANT_WAVES_SPEC_COMMAND` names. Throws when it is unset or not a JSON list of words. */
@@ -98,8 +135,12 @@ export function opWavesSpecCommandFromEnv(env: NodeJS.ProcessEnv = process.env):
98
135
  /** Prints the spec at a full commit, or null when that commit has none. Injected for tests. */
99
136
  export type OpWavesSpecRender = (sha: string) => string | null;
100
137
 
101
- /** {@link OpWavesSpecRender} through the product's command, run in `cwd`. Its standard error goes to the job's log. */
102
- export function commandSpecRender(command: readonly string[], specFile: string, cwd: string): OpWavesSpecRender {
138
+ /**
139
+ * {@link OpWavesSpecRender} through the product's command, run in `cwd`. Its
140
+ * standard error goes to the job's log. `extra` adds variables, such as
141
+ * `CHANT_WAVES_SPEC_BASE` for the job's own render at head (#5046).
142
+ */
143
+ export function commandSpecRender(command: readonly string[], specFile: string, cwd: string, extra: Record<string, string> = {}): OpWavesSpecRender {
103
144
  return (sha) => {
104
145
  let out: string;
105
146
  try {
@@ -107,7 +148,7 @@ export function commandSpecRender(command: readonly string[], specFile: string,
107
148
  cwd,
108
149
  encoding: "utf-8",
109
150
  stdio: ["ignore", "pipe", "inherit"],
110
- env: { ...process.env, [OP_WAVES_SPEC_AT_ENV]: sha, [OP_WAVES_SPEC_FILE_ENV]: specFile },
151
+ env: { ...process.env, [OP_WAVES_SPEC_AT_ENV]: sha, [OP_WAVES_SPEC_FILE_ENV]: specFile, ...extra },
111
152
  maxBuffer: 64 * 1024 * 1024,
112
153
  });
113
154
  } catch (err) {
@@ -152,20 +193,50 @@ export function renderOpWavesSpecFile(options: { specFile: string; base: string;
152
193
  return { spec, sha };
153
194
  }
154
195
 
196
+ /**
197
+ * The job's spec and the reader of the rules (#4982, #5046). `show` reads
198
+ * the spec at any commit through `render` (the rules at base, the
199
+ * stand-down's newer commit). The job's own spec is rendered at `base`, or
200
+ * with `runsAtHead` at `HEAD`, the commit the job checked out, through
201
+ * `headRender`, which the caller builds with `CHANT_WAVES_SPEC_BASE` set to
202
+ * the base commit's sha (it gets that sha). Either is written over
203
+ * `specFile`. `at` says where the job's spec came from, for the job's log.
204
+ */
205
+ export function renderOpWavesJobSpec(options: {
206
+ specFile: string;
207
+ base: string;
208
+ cwd: string;
209
+ render: OpWavesSpecRender;
210
+ fallback: OpWaveShowAtBase;
211
+ parse: (text: string, where: string) => OpWavesSpec;
212
+ runsAtHead?: boolean;
213
+ headRender?: (baseSha: string) => OpWavesSpecRender;
214
+ }): { spec: OpWavesSpec; show: OpWaveShowAtBase; sha: string; at: "base" | "head" } {
215
+ const show = renderedSpecShow(options.specFile, options.render, options.fallback);
216
+ if (!options.runsAtHead) return { ...renderOpWavesSpecFile({ specFile: options.specFile, base: options.base, cwd: options.cwd, show, parse: options.parse }), show, at: "base" };
217
+ if (!options.headRender) throw new Error("renderOpWavesJobSpec: runsAtHead needs headRender");
218
+ const { sha: baseSha } = options.fallback(options.base, options.specFile, options.cwd);
219
+ // Its own reader, so the render at head is never taken for the rules, even when the head is the base.
220
+ const headShow = renderedSpecShow(options.specFile, options.headRender(baseSha), options.fallback);
221
+ return { ...renderOpWavesSpecFile({ specFile: options.specFile, base: "HEAD", cwd: options.cwd, show: headShow, parse: options.parse }), show, at: "head" };
222
+ }
223
+
155
224
  /**
156
225
  * Whether job `job` of wave `k` has anything in the rendered spec: a share
157
226
  * past the wave's (or the group's) shares, or a group the wave does not
158
- * have, has nothing. Undefined when it has; otherwise why not.
227
+ * have, has nothing. Undefined when it has; otherwise why not. `at` names
228
+ * the commit the spec was rendered at, `base` or `head` (#5046).
159
229
  */
160
- export function renderedJobMissing(spec: OpWavesSpec, k: number, job: { share?: number; group?: string }): string | undefined {
230
+ export function renderedJobMissing(spec: OpWavesSpec, k: number, job: { share?: number; group?: string }, at: "base" | "head" = "base"): string | undefined {
161
231
  const wave = spec.waves[k - 1];
162
232
  if (!wave) return undefined;
233
+ const where = `in the spec rendered at ${at}`;
163
234
  if (job.group !== undefined) {
164
235
  const group = wave.jobs?.find((g) => g.name === job.group);
165
- if (!group) return `wave ${k} (${wave.name}) has no job group "${job.group}" in the spec rendered at base`;
166
- if (job.share !== undefined && job.share > (group.shares ?? 1)) return `job group "${job.group}" of wave ${k} (${wave.name}) has ${group.shares ?? 1} share${(group.shares ?? 1) === 1 ? "" : "s"} in the spec rendered at base`;
236
+ if (!group) return `wave ${k} (${wave.name}) has no job group "${job.group}" ${where}`;
237
+ if (job.share !== undefined && job.share > (group.shares ?? 1)) return `job group "${job.group}" of wave ${k} (${wave.name}) has ${group.shares ?? 1} share${(group.shares ?? 1) === 1 ? "" : "s"} ${where}`;
167
238
  return undefined;
168
239
  }
169
- if (job.share !== undefined && wave.jobs === undefined && job.share > (wave.shares ?? 1)) return `wave ${k} (${wave.name}) has ${wave.shares ?? 1} share${(wave.shares ?? 1) === 1 ? "" : "s"} in the spec rendered at base`;
240
+ if (job.share !== undefined && wave.jobs === undefined && job.share > (wave.shares ?? 1)) return `wave ${k} (${wave.name}) has ${wave.shares ?? 1} share${(wave.shares ?? 1) === 1 ? "" : "s"} ${where}`;
170
241
  return undefined;
171
242
  }
@@ -81,14 +81,16 @@ import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type G
81
81
  import type { GateAnswerRef, PendingGateInput, PendingGateRecord } from "../lifecycle/gate-ledger";
82
82
  import type { GatePointAsker } from "../point-decision";
83
83
  import type { WaitingPoint } from "./steward-points";
84
- import { finishedApply, isApprovalSpent, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
84
+ import { finishedApply, isApprovalSpent, type AppliedGateChange, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
85
+ import { opWaveApprovedChanges, opWaveCoverRemainder, opWaveRunCovered, opWaveStoppedApply, opWaveUnfinishedApply } from "./op-waves-remainder";
85
86
  import { samePlanDigest } from "../lifecycle/plan-digest";
86
87
  import { movedSincePreview } from "./op-waves-preview";
87
88
  import { isLifecycleLocalNote } from "../lifecycle/local-note";
88
89
  import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
89
90
  import type { TrustPolicy } from "../workspace/trust/policy";
90
91
  import type { GateSigners } from "../lifecycle/gate-seal";
91
- import { ciRunIdFromEnv } from "./gate-run-locator";
92
+ import { ciRunIdFromEnv, resolveGateRunLocator } from "./gate-run-locator";
93
+ import { opWaveSplitResumeLocator } from "./op-waves-split-resume";
92
94
  import { appendRunRecord, DEFAULT_RUN_ENV } from "../lifecycle/run-ledger";
93
95
  import { LifecyclePushLostError, pushLifecycleRebasing } from "../lifecycle/git";
94
96
  import { opWaveEvidenceRefusal, signOpWaveChecks } from "./op-waves-evidence";
@@ -109,7 +111,7 @@ import { gitOpWaveReleasePort } from "./op-waves-release-port";
109
111
  import type { LockGrain } from "../lifecycle/lock-rows";
110
112
  import type { LockLiveness, LockRowsLease } from "../lifecycle/resource-lock";
111
113
  import type { GatePolicyExec } from "../gate-policy";
112
- import { gitOpWaveNewerCommit, opWaveStandDownReason, tipAppliesTargets, type OpWaveNewerCommitPort } from "./op-waves-stand-down";
114
+ import { gitOpWaveNewerCommit, opWaveDefaultBranch, opWaveStandDownReason, tipAppliesTargets, type OpWaveNewerCommitPort } from "./op-waves-stand-down";
113
115
  import { keyedSerial, mapLimited, type SerialSection } from "../parallelism";
114
116
  import {
115
117
  applyOpWaveStep,
@@ -366,6 +368,23 @@ export interface OpWaveDecision {
366
368
  approvedAt?: string;
367
369
  /** When the wave recorded that it applies under the approval, which spent it. */
368
370
  spentAt?: string;
371
+ /** `approvals.remainder` at base, beside `approvals.spend` (#5047): the applied line names the changes, and the apply's end is recorded. */
372
+ remainder?: true;
373
+ /** `approvals.spendStanding` at base (#5047): a wave its gate lets through spends an approval of its digest that stands. */
374
+ spendStanding?: true;
375
+ /**
376
+ * Under `remainder` (#5047): each change the plans make, a run's resource
377
+ * and its digest, which the applied line names. Absent when a run that
378
+ * changes something plans on no resource grain: the apply cannot resume
379
+ * as a remainder.
380
+ */
381
+ changes?: AppliedGateChange[];
382
+ /**
383
+ * Under `remainder` (#5047): the stopped apply this wave applies the rest
384
+ * of, under its approval. The wave writes no applied line of its own; the
385
+ * finished line names this one.
386
+ */
387
+ resumes?: { planDigest: string; appliedAt: string; approvedAt: string; approvedBy: string };
369
388
  /** `apply`: the apply command runs the apply-stage hooks under its own lock (#3804), as read at base. Absent: chant runs them. */
370
389
  applyHooksRunBy?: "apply";
371
390
  /** Every hook's outcome so far in the job that wrote the record (#3804). */
@@ -657,6 +676,10 @@ export interface OpWaveBaseRules {
657
676
  hooksRefused?: string;
658
677
  /** The spec at base sets `approvals.spend` (#3784). */
659
678
  spend: boolean;
679
+ /** The spec at base sets `approvals.remainder` beside `approvals.spend` (#5047). */
680
+ remainder?: boolean;
681
+ /** The spec at base sets `approvals.spendStanding` beside `approvals.spend` (#5047). */
682
+ spendStanding?: boolean;
660
683
  /** Who runs the apply-stage hooks, as read at base (#3804). `chant` when the file, the wave or the hooks are missing there. */
661
684
  applyHooksRunBy: OpWaveApplyHooksRunner;
662
685
  /** The spec at base sets `neverOverMcp` (#3821). */
@@ -725,15 +748,18 @@ export function readOpWavePolicy(
725
748
  }
726
749
  // The spend rule is the spec's, so it holds for a wave the base does not have yet.
727
750
  const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
751
+ // #5047: the rest of a stopped apply, and an approval left standing, both work on the spend rule's lines.
752
+ const settings = (spec as { approvals?: { remainder?: unknown; spendStanding?: unknown } }).approvals;
753
+ const spendRules = { ...(spend && settings?.remainder === true ? { remainder: true } : {}), ...(spend && settings?.spendStanding === true ? { spendStanding: true } : {}) };
728
754
  const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
729
755
  // #3836: the gate's decision point, the spec's for a wave the base does not have yet.
730
756
  const asks = { ...pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`), ...quorumAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...holdsAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...evidenceAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...pullRequestGateAtBase(spec), ...(spec.approvals?.preview === true ? { preview: true } : {}) };
731
757
  const wave = spec.waves.find((w) => w.name === name);
732
- if (!wave) return { ...absent, spend, neverOverMcp, ...asks };
758
+ if (!wave) return { ...absent, spend, ...spendRules, neverOverMcp, ...asks };
733
759
  const policy = wave.gate ?? "always";
734
760
  // An approval mode this chant does not know reads as sealed: the strictest, so an unknown rule never loosens a gate.
735
761
  const approval = wave.approval === undefined ? "ledger" : GATE_APPROVAL_SOURCES.includes(wave.approval) ? wave.approval : "sealed";
736
- const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant", neverOverMcp, ...asks };
762
+ const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, ...spendRules, applyHooksRunBy: "chant", neverOverMcp, ...asks };
737
763
  try {
738
764
  assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}`, spec.hooks);
739
765
  assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}, wave "${name}"`, wave.hooks);
@@ -936,6 +962,8 @@ export interface RunOpWaveOptions {
936
962
  standDown?: boolean;
937
963
  /** How the job finds a newer commit on its branch (#4581). Default: fetch the branch from `origin` ({@link gitOpWaveNewerCommit}). */
938
964
  newerCommit?: OpWaveNewerCommitPort;
965
+ /** The repository's default branch, for a spec with `defaultBranch` (#5032). Default {@link opWaveDefaultBranch} of the job's environment. */
966
+ defaultBranch?: string;
939
967
  /**
940
968
  * Where the job's run events go (#4555), on the run-event contract: a
941
969
  * phase `wave-<k>` per wave and a step per run target, settled as the
@@ -3160,6 +3188,12 @@ async function writeOpWaveRecords(
3160
3188
  }
3161
3189
  result.exitCode = codes.every((c) => c === CHANT_EXIT.done) ? CHANT_EXIT.done : (codes.find((c) => c !== CHANT_EXIT.done && c !== CHANT_EXIT.failed) ?? CHANT_EXIT.failed);
3162
3190
  if (lost && result.exitCode === CHANT_EXIT.done) result.exitCode = CHANT_EXIT.failed;
3191
+ // #5047: how the apply under the gate job's applied line ended; an applying job that left no run record stopped, and says nothing.
3192
+ const line = decision ? remainderLine(decision) : undefined;
3193
+ if (line && !codes.includes(CHANT_EXIT.waiting)) {
3194
+ const applied = codes.every((c) => c === CHANT_EXIT.done) && result.failed.length === 0;
3195
+ await writeApplyFinished(options, { spec: options.spec, k, wave: { name: decision!.name }, cwd, log }, line, applied ? "applied" : "failed");
3196
+ }
3163
3197
  log(`wave ${k}: wrote the run record${records.length === 1 ? "" : "s"} of ${records.length} applying job${records.length === 1 ? "" : "s"}; the wave ends with exit ${result.exitCode}`);
3164
3198
  return result;
3165
3199
  }
@@ -3426,6 +3460,8 @@ async function openWaveDecision(
3426
3460
  status: "not-required",
3427
3461
  ...(Object.keys(hooks).length > 0 ? { hooks } : {}),
3428
3462
  ...(rules.spend ? { spend: "base" as const } : spec.approvals?.spend === true ? { spend: "change" as const } : {}),
3463
+ ...(rules.remainder ? { remainder: true as const } : {}),
3464
+ ...(rules.spendStanding ? { spendStanding: true as const } : {}),
3429
3465
  ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
3430
3466
  ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
3431
3467
  ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
@@ -3628,6 +3664,20 @@ async function shareUnmoved(planned: Extract<OpWavePlanned, { kind: "share" }>):
3628
3664
  const unmoved: OpWaveRun[] = [];
3629
3665
  for (const run of slice) {
3630
3666
  const now = planned.planned.get(run.target)!;
3667
+ if (decidedDigests.get(run.target) !== now.planDigest && ctx.options.phase === "apply" && decision.remainder && decision.changes) {
3668
+ // #5047: a split wave's applying job run again after it stopped: a plan that makes only changes the decision recorded is their rest.
3669
+ const cover = opWaveRunCovered(decision.changes, run.target, now, ctx.steps);
3670
+ if (cover.covered && now.empty === true) {
3671
+ ctx.log(`${run.target}: its plan moved since wave ${ctx.k} was decided and changes nothing now, so every change the decision recorded for it is done`);
3672
+ continue;
3673
+ }
3674
+ if (cover.covered) {
3675
+ ctx.log(`${run.target}: its plan moved since wave ${ctx.k} was decided; ${cover.done.length} of the changes the decision recorded for it are done and it makes the other ${cover.remaining.length}, so it applies under the decision's approval`);
3676
+ unmoved.push(run);
3677
+ continue;
3678
+ }
3679
+ ctx.log(`${run.target}: its plan moved since wave ${ctx.k} was decided, and ${cover.why}`);
3680
+ }
3631
3681
  if (decidedDigests.get(run.target) !== now.planDigest) {
3632
3682
  ctx.log(
3633
3683
  `${run.target}: its plan moved since wave ${ctx.k} was decided, so it was not applied. ` +
@@ -3700,11 +3750,20 @@ async function decideOpWave(
3700
3750
  if (!unseen) log(`wave ${k} (${wave.name}): the plans are the ones pull request #${seen.preview.pr} previewed at ${seen.preview.head?.slice(0, 12)} (${seen.preview.compared === "resources" ? `${seen.preview.recorded}, compared resource by resource; the wave now plans ${digest}` : digest})`);
3701
3751
  else log(`wave ${k} (${wave.name}): ${seen.preview.reason}`);
3702
3752
  }
3753
+ // #5047: under approvals.remainder at base, the changes the applied line names, and the stopped apply these plans are the rest of.
3754
+ if (decision.remainder && !kept && decision.status !== "refused" && !unseen) await remainderOf(options, ctx, decision, members, extras);
3703
3755
  if (kept && was.status === "approved" && decision.status !== "refused") {
3704
3756
  // #3821: planned again after the apply asked to, to the same digest: the approval this job found still holds, and is not spent twice.
3705
- for (const key of ["via", "approvedBy", "approvedAt", "review", "spentAt"] as const) if (was[key] !== undefined) (decision as unknown as Record<string, unknown>)[key] = was[key];
3757
+ for (const key of ["via", "approvedBy", "approvedAt", "review", "spentAt", "changes", "resumes"] as const) if (was[key] !== undefined) (decision as unknown as Record<string, unknown>)[key] = was[key];
3706
3758
  decision.status = "approved";
3707
3759
  log(`wave ${k} (${wave.name}): planned again to the same digest, so the approval by ${was.approvedBy} still holds`);
3760
+ } else if (decision.resumes && decision.status !== "refused" && (opWaveNeedsApproval(policy, members) || holds.length > 0)) {
3761
+ // #5047: the rest of a stopped apply goes out under the approval it applied under, which its applied line already spent.
3762
+ decision.status = "approved";
3763
+ decision.via = "ledger";
3764
+ decision.approvedBy = decision.resumes.approvedBy;
3765
+ decision.approvedAt = decision.resumes.approvedAt;
3766
+ decision.spentAt = decision.resumes.appliedAt;
3708
3767
  } else if (decision.status !== "refused" && (unseen || opWaveNeedsApproval(policy, members) || holds.length > 0)) {
3709
3768
  // terragucci issue 1303: what the product settled before the gate, recorded at it for these plans first.
3710
3769
  if (ctx.answerApprovals?.length) await recordAnswerApprovals(options, ctx, decision);
@@ -3866,6 +3925,9 @@ async function applyOpWave(options: RunOpWaveOptions, planned: OpWavePlanned, de
3866
3925
  const { ctx, decision } = planned;
3867
3926
  await applyStage(options, ctx, decision, decidedWave.runs, planned.planned, decidedWave.earlierHolds, decidedWave.recordPath);
3868
3927
  if (planned.kind === "share" && ctx.result.exitCode === 0 && ctx.result.moved.length > 0) ctx.result.exitCode = CHANT_EXIT.moved;
3928
+ // #5047: the job that applied the whole wave under an approval its applied line names says how the apply ended.
3929
+ const line = planned.kind === "share" ? undefined : remainderLine(decision);
3930
+ if (line && ctx.result.exitCode !== CHANT_EXIT.waiting) await writeApplyFinished(options, ctx, line, ctx.result.exitCode === 0 && ctx.result.failed.length === 0 ? "applied" : "failed");
3869
3931
  return ctx.result;
3870
3932
  }
3871
3933
 
@@ -4726,7 +4788,7 @@ async function standDownForNewer(options: RunOpWaveOptions, ctx: WaveContext, de
4726
4788
  log(`wave ${k} (${wave.name}): ${newer.branch} has a newer commit ${newer.tip.slice(0, 12)}, and its spec cannot be read (${err instanceof Error ? err.message : String(err)}), so this job applies`);
4727
4789
  return false;
4728
4790
  }
4729
- if (!tipAppliesTargets(atTip, newer.branch, wave.name, targets)) {
4791
+ if (!tipAppliesTargets(atTip, newer.branch, wave.name, targets, options.defaultBranch ?? opWaveDefaultBranch())) {
4730
4792
  log(`wave ${k} (${wave.name}): ${newer.branch} has a newer commit ${newer.tip.slice(0, 12)}, and its wave does not apply every target of this job, so this job applies`);
4731
4793
  return false;
4732
4794
  }
@@ -5084,11 +5146,17 @@ async function submitStepReleases(port: OpWaveReleasePort, requests: readonly Op
5084
5146
  * ledger, so a line recorded there is spent.
5085
5147
  */
5086
5148
  async function spendApproval(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<boolean> {
5149
+ // #5047: an approval of these very plans left standing while the gate let them through is spent as they apply.
5150
+ if (decision.spendStanding && decision.spend === "base" && decision.status === "not-required" && !decision.spentAt && options.phase !== "apply") {
5151
+ await spendStanding(options, ctx, decision);
5152
+ return true;
5153
+ }
5087
5154
  if (!decision.spend || decision.status !== "approved" || decision.spentAt || !decision.approvedAt) return true;
5088
5155
  const { spec, k, wave, cwd, log } = ctx;
5089
5156
  const port = options.gates ?? gitGateLedgerPort({ cwd });
5090
5157
  const now = options.now ?? new Date().toISOString();
5091
5158
  const record: AppliedGateRecord = {
5159
+ ...(decision.remainder && decision.changes ? remainderFields(options, ctx, decision, decision.changes) : {}),
5092
5160
  version: 1,
5093
5161
  kind: "applied",
5094
5162
  op: spec.name,
@@ -5111,9 +5179,138 @@ async function spendApproval(options: RunOpWaveOptions, ctx: WaveContext, decisi
5111
5179
  }
5112
5180
  decision.spentAt = now;
5113
5181
  log(`wave ${k} (${wave.name}) applies under the approval by ${record.approvedBy} at ${record.approvedAt}, which is now spent`);
5182
+ if (record.changes) log(`wave ${k} (${wave.name}): ${record.changes.length} change${record.changes.length === 1 ? "" : "s"} recorded on the applied line, so an apply that stops applies the rest under this approval`);
5114
5183
  return true;
5115
5184
  }
5116
5185
 
5186
+ /**
5187
+ * What an applied line carries under `approvals.remainder` (#5047): the
5188
+ * changes, the digest members that are no run, the commit, the run, and
5189
+ * where the run is, so `chant run resume` starts it again once it is gone.
5190
+ * A split wave's gate job writes the line and its applying job is the one
5191
+ * that may stop: GitHub re-runs a run's failed jobs, so the gate job's run
5192
+ * resumes the applying job. GitLab retries one job by its id and Forgejo
5193
+ * starts a new run of the branch, so there the gate job's locator carries
5194
+ * what the generator told it (#5052): the applying and record jobs' names,
5195
+ * or the run's dispatch inputs. A gate job told neither names no run.
5196
+ */
5197
+ function remainderFields(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, changes: AppliedGateChange[]): Partial<AppliedGateRecord> {
5198
+ const commit = waveHeadOf(options, ctx.cwd);
5199
+ const runId = ciRunIdFromEnv();
5200
+ const locator = resolveGateRunLocator();
5201
+ const resume = options.phase === "gate" ? opWaveSplitResumeLocator(locator) : locator;
5202
+ return {
5203
+ changes,
5204
+ ...(decision.extras?.length ? { extras: decision.extras.map((e) => ({ member: e.member, planDigest: e.planDigest })) } : {}),
5205
+ ...(commit ? { commit } : {}),
5206
+ ...(runId ? { runId } : {}),
5207
+ ...(resume ? { resume } : {}),
5208
+ };
5209
+ }
5210
+
5211
+ /**
5212
+ * Under `approvals.remainder` (#5047), in a job with the token that decides
5213
+ * a whole wave (its own job, or a split wave's gate job): the changes the
5214
+ * plans make, kept on the decision for the applied line and the applying
5215
+ * job; with plans that change nothing, the close of a stopped apply; else
5216
+ * the stopped apply at this commit whose rest these plans are, which the
5217
+ * decision then `resumes`. A ledger that cannot be read resumes nothing.
5218
+ */
5219
+ async function remainderOf(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, members: readonly OpWaveMember[], extras: readonly WaveMember[] | undefined): Promise<void> {
5220
+ const { spec, k, wave, cwd, log } = ctx;
5221
+ const label = `wave ${k} (${wave.name})`;
5222
+ // Only a wave one job applies says how its apply ended.
5223
+ if ((wave.shares ?? 1) > 1 || wave.jobs !== undefined) return;
5224
+ const changes = opWaveApprovedChanges(members, ctx.steps);
5225
+ if (changes) decision.changes = changes;
5226
+ const changing = members.some((m) => m.empty !== true) || (extras?.length ?? 0) > 0;
5227
+ if (changing && !changes) log(`${label}: a run that changes something plans on no resource grain, or gave no resource digests, so an apply of it that stops cannot apply the rest under its approval`);
5228
+ const port = options.gates ?? gitGateLedgerPort({ cwd });
5229
+ if (!port.readApplied || !port.readFinished) return;
5230
+ let applied: AppliedGateRecord[];
5231
+ let finished: FinishedGateRecord[];
5232
+ try {
5233
+ applied = await port.readApplied(spec.name);
5234
+ finished = await port.readFinished(spec.name);
5235
+ } catch (err) {
5236
+ log(`${label}: the applied lines could not be read (${err instanceof Error ? err.message : String(err)}), so no stopped apply is taken up`);
5237
+ return;
5238
+ }
5239
+ if (!changing) {
5240
+ // Nothing is left to change: something applied the rest of a stopped apply, which is closed as applied.
5241
+ const open = opWaveUnfinishedApply(applied, finished, decision.gate);
5242
+ if (open) await writeApplyFinished(options, ctx, { gate: open.gate, planDigest: open.planDigest, applied: open.timestamp }, "applied", `the apply of ${open.planDigest} stopped before it finished, and nothing of it is left to apply`);
5243
+ return;
5244
+ }
5245
+ const stopped = opWaveStoppedApply(applied, finished, decision.gate, waveHeadOf(options, cwd));
5246
+ if (!stopped?.changes) return;
5247
+ const cover = opWaveCoverRemainder(stopped.changes, changes, { now: extras, approved: stopped.extras });
5248
+ if (!cover.covered) {
5249
+ log(`${label}: the apply of ${stopped.planDigest}, approved by ${stopped.approvedBy}, stopped before it finished, but ${cover.why}, so these plans need an approval of their own`);
5250
+ return;
5251
+ }
5252
+ decision.resumes = { planDigest: stopped.planDigest, appliedAt: stopped.timestamp, approvedAt: stopped.approvedAt, approvedBy: stopped.approvedBy };
5253
+ log(
5254
+ `${label}: the apply of ${stopped.planDigest}, approved by ${stopped.approvedBy}, stopped before it finished; ${cover.done.length} of its ${stopped.changes.length} change${stopped.changes.length === 1 ? "" : "s"} ` +
5255
+ `are done, and these plans make the other ${cover.remaining.length}, so that approval covers them`,
5256
+ );
5257
+ }
5258
+
5259
+ /**
5260
+ * Write how an apply under an approval ended (#5047): the finished line
5261
+ * that names the applied line. Never fails the wave; a line that cannot be
5262
+ * written is logged, and a resume may apply what is left again, each change
5263
+ * of which the approval covered.
5264
+ */
5265
+ async function writeApplyFinished(options: RunOpWaveOptions, ctx: { spec: Pick<OpWavesSpec, "name">; k: number; wave: { name: string }; cwd: string; log: (line: string) => void }, line: { gate: string; planDigest: string; applied: string }, result: FinishedGateRecord["result"], why?: string): Promise<void> {
5266
+ const { spec, k, cwd, log } = ctx;
5267
+ const label = `wave ${k} (${ctx.wave.name})`;
5268
+ const port = options.gates ?? gitGateLedgerPort({ cwd });
5269
+ try {
5270
+ if (!port.appendFinished) throw new Error("this gate ledger keeps no finished lines");
5271
+ const pushed = await port.appendFinished({ version: 1, kind: "finished", op: spec.name, gate: line.gate, planDigest: line.planDigest, applied: line.applied, result, timestamp: options.now ?? new Date().toISOString() });
5272
+ if (!pushed.pushed && pushed.pushWarning && !isLifecycleLocalNote(pushed.pushWarning)) log(`${label}: the finished line of its apply was written and not pushed: ${pushed.pushWarning}`);
5273
+ log(`${label}: ${why ?? `its apply under the approval ${result === "applied" ? "applied" : "failed"}`}; recorded on the finished line`);
5274
+ } catch (err) {
5275
+ log(`${label}: how its apply ended was not recorded (${err instanceof Error ? err.message : String(err)}); a resume may apply what is left again, and each change it makes is one the approval covered`);
5276
+ }
5277
+ }
5278
+
5279
+ /** The applied line a decision's apply wrote or took up (#5047), when it names changes; what its finished line names. */
5280
+ function remainderLine(decision: Pick<OpWaveDecision, "remainder" | "changes" | "resumes" | "spentAt" | "gate" | "digest">): { gate: string; planDigest: string; applied: string } | undefined {
5281
+ if (!decision.remainder || !decision.spentAt) return undefined;
5282
+ if (decision.resumes) return { gate: decision.gate, planDigest: decision.resumes.planDigest, applied: decision.resumes.appliedAt };
5283
+ return decision.changes ? { gate: decision.gate, planDigest: decision.digest, applied: decision.spentAt } : undefined;
5284
+ }
5285
+
5286
+ /**
5287
+ * Under `approvals.spendStanding` (#5047): the wave's gate let its plans
5288
+ * through, and an approval of their digest that no wave applied under
5289
+ * stands. It is spent now, as they apply, so it does not stand for the next
5290
+ * plans. Never fails the wave.
5291
+ */
5292
+ async function spendStanding(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<void> {
5293
+ const { spec, k, wave, cwd, log } = ctx;
5294
+ if (!decision.digest) return;
5295
+ const port = options.gates ?? gitGateLedgerPort({ cwd });
5296
+ if (!port.appendApplied || !port.readApplied) return;
5297
+ const label = `wave ${k} (${wave.name})`;
5298
+ try {
5299
+ const applied = (await port.readApplied(spec.name)).filter((a) => a.gate === decision.gate);
5300
+ const { resolutions } = await port.read(spec.name);
5301
+ const standing = resolutions
5302
+ .filter((r) => r.gate === decision.gate && samePlanDigest(r.planDigest, decision.digest) && !isApprovalSpent(applied, { gate: decision.gate, planDigest: decision.digest, timestamp: r.timestamp }))
5303
+ .reduce<(typeof resolutions)[number] | undefined>((n, r) => (!n || new Date(r.timestamp).getTime() >= new Date(n.timestamp).getTime() ? r : n), undefined);
5304
+ if (!standing) return;
5305
+ const now = options.now ?? new Date().toISOString();
5306
+ const pushed = await port.appendApplied({ version: 1, kind: "applied", op: spec.name, gate: decision.gate, planDigest: decision.digest, approvedAt: standing.timestamp, approvedBy: standing.resolvedBy, timestamp: now, wave: { number: k, name: wave.name } });
5307
+ if (!pushed.pushed && pushed.pushWarning && !isLifecycleLocalNote(pushed.pushWarning)) log(`${label}: ${pushed.pushWarning}`);
5308
+ log(`${label}: its gate let these plans through, and the approval of ${decision.digest} by ${standing.resolvedBy} at ${standing.timestamp} stood; it is now spent, so it does not stand for the next plans`);
5309
+ } catch (err) {
5310
+ log(`${label}: the approval of these plans that stands was not spent: ${err instanceof Error ? err.message : String(err)}`);
5311
+ }
5312
+ }
5313
+
5117
5314
  /** What {@link approveByReview} found. */
5118
5315
  type ReviewOutcome = ReviewApproval;
5119
5316