@intentius/chant 0.124.89 → 0.124.91

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 (185) hide show
  1. package/dist/actor.d.ts +5 -3
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +7 -5
  4. package/dist/audit/core.d.ts.map +1 -1
  5. package/dist/audit/core.js +11 -1
  6. package/dist/ci-comment-commands.d.ts +18 -2
  7. package/dist/ci-comment-commands.d.ts.map +1 -1
  8. package/dist/ci-comment-commands.js +30 -2
  9. package/dist/ci-job-guard.d.ts +42 -45
  10. package/dist/ci-job-guard.d.ts.map +1 -1
  11. package/dist/ci-job-guard.js +206 -3
  12. package/dist/ci-note-commands.d.ts +41 -1
  13. package/dist/ci-note-commands.d.ts.map +1 -1
  14. package/dist/ci-note-commands.js +64 -5
  15. package/dist/ci-product.d.ts +50 -1
  16. package/dist/ci-product.d.ts.map +1 -1
  17. package/dist/ci-product.js +52 -6
  18. package/dist/cli/handlers/pr-comment.d.ts +13 -1
  19. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  20. package/dist/cli/handlers/pr-comment.js +90 -1
  21. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  22. package/dist/cli/handlers/pr-notes.js +23 -1
  23. package/dist/cli/handlers/pr.d.ts +2 -2
  24. package/dist/cli/handlers/pr.d.ts.map +1 -1
  25. package/dist/cli/handlers/pr.js +41 -20
  26. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  27. package/dist/cli/handlers/run-wave.js +154 -4
  28. package/dist/cli/main.d.ts.map +1 -1
  29. package/dist/cli/main.js +17 -0
  30. package/dist/cli/parse-args.d.ts.map +1 -1
  31. package/dist/cli/parse-args.js +28 -0
  32. package/dist/cli/registry.d.ts +12 -1
  33. package/dist/cli/registry.d.ts.map +1 -1
  34. package/dist/components/pr-checks.d.ts +39 -1
  35. package/dist/components/pr-checks.d.ts.map +1 -1
  36. package/dist/components/pr-checks.js +45 -2
  37. package/dist/components/pr-pipeline.d.ts +11 -3
  38. package/dist/components/pr-pipeline.d.ts.map +1 -1
  39. package/dist/components/pr-pipeline.js +20 -7
  40. package/dist/components/product-pipeline.d.ts +54 -2
  41. package/dist/components/product-pipeline.d.ts.map +1 -1
  42. package/dist/components/product-pipeline.js +63 -6
  43. package/dist/components/product-plan.d.ts +92 -2
  44. package/dist/components/product-plan.d.ts.map +1 -1
  45. package/dist/components/product-plan.js +172 -22
  46. package/dist/floor-table.data.d.ts.map +1 -1
  47. package/dist/floor-table.data.js +37 -23
  48. package/dist/lexicon-module.d.ts +2 -0
  49. package/dist/lexicon-module.d.ts.map +1 -1
  50. package/dist/lexicon-module.js +6 -2
  51. package/dist/lexicon.d.ts +82 -4
  52. package/dist/lexicon.d.ts.map +1 -1
  53. package/dist/lifecycle/gate-applied.d.ts +9 -0
  54. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  55. package/dist/op/apply-status.d.ts +84 -0
  56. package/dist/op/apply-status.d.ts.map +1 -0
  57. package/dist/op/apply-status.js +106 -0
  58. package/dist/op/before-merge-decide.d.ts +102 -0
  59. package/dist/op/before-merge-decide.d.ts.map +1 -0
  60. package/dist/op/before-merge-decide.js +142 -0
  61. package/dist/op/before-merge-done.d.ts +56 -0
  62. package/dist/op/before-merge-done.d.ts.map +1 -0
  63. package/dist/op/before-merge-done.js +69 -0
  64. package/dist/op/before-merge-store.d.ts +20 -0
  65. package/dist/op/before-merge-store.d.ts.map +1 -0
  66. package/dist/op/before-merge-store.js +48 -0
  67. package/dist/op/before-merge.d.ts +150 -0
  68. package/dist/op/before-merge.d.ts.map +1 -0
  69. package/dist/op/before-merge.js +207 -0
  70. package/dist/op/follow-on-run.d.ts +117 -0
  71. package/dist/op/follow-on-run.d.ts.map +1 -0
  72. package/dist/op/follow-on-run.js +154 -0
  73. package/dist/op/follow-on-store.d.ts +17 -0
  74. package/dist/op/follow-on-store.d.ts.map +1 -0
  75. package/dist/op/follow-on-store.js +54 -0
  76. package/dist/op/gate.d.ts +6 -0
  77. package/dist/op/gate.d.ts.map +1 -1
  78. package/dist/op/gate.js +10 -1
  79. package/dist/op/index.d.ts +3 -1
  80. package/dist/op/index.d.ts.map +1 -1
  81. package/dist/op/index.js +1 -0
  82. package/dist/op/op-waves-after-plan.d.ts +13 -0
  83. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  84. package/dist/op/op-waves-evidence-jobs.d.ts +4 -1
  85. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  86. package/dist/op/op-waves-evidence-jobs.js +10 -2
  87. package/dist/op/op-waves-follow-on.d.ts +162 -0
  88. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  89. package/dist/op/op-waves-follow-on.js +355 -0
  90. package/dist/op/op-waves-run.d.ts +146 -6
  91. package/dist/op/op-waves-run.d.ts.map +1 -1
  92. package/dist/op/op-waves-run.js +871 -99
  93. package/dist/op/op-waves-split.d.ts +122 -0
  94. package/dist/op/op-waves-split.d.ts.map +1 -0
  95. package/dist/op/op-waves-split.js +166 -0
  96. package/dist/op/op-waves.d.ts +20 -0
  97. package/dist/op/op-waves.d.ts.map +1 -1
  98. package/dist/op/op-waves.js +15 -1
  99. package/dist/op/schedule-overdue.d.ts +15 -1
  100. package/dist/op/schedule-overdue.d.ts.map +1 -1
  101. package/dist/op/schedule-overdue.js +18 -2
  102. package/dist/op/stage-hooks.d.ts +36 -1
  103. package/dist/op/stage-hooks.d.ts.map +1 -1
  104. package/dist/op/stage-hooks.js +17 -3
  105. package/dist/op/wave-stop.d.ts +4 -1
  106. package/dist/op/wave-stop.d.ts.map +1 -1
  107. package/dist/op/wave-stop.js +4 -2
  108. package/dist/planned-files.d.ts +16 -8
  109. package/dist/planned-files.d.ts.map +1 -1
  110. package/dist/planned-files.js +12 -8
  111. package/dist/pr-post.d.ts +6 -0
  112. package/dist/pr-post.d.ts.map +1 -1
  113. package/dist/pr-post.js +7 -5
  114. package/dist/release-floors.d.ts +9 -1
  115. package/dist/release-floors.d.ts.map +1 -1
  116. package/dist/release-floors.js +27 -19
  117. package/dist/wave-blocked.d.ts +7 -1
  118. package/dist/wave-blocked.d.ts.map +1 -1
  119. package/dist/wave-blocked.js +7 -2
  120. package/dist/wave-runtime.mjs +364 -351
  121. package/package.json +1 -1
  122. package/src/actor.test.ts +14 -1
  123. package/src/actor.ts +8 -6
  124. package/src/audit/core.ts +13 -1
  125. package/src/audit/first-load.test.ts +101 -0
  126. package/src/ci-comment-commands.test.ts +63 -0
  127. package/src/ci-comment-commands.ts +43 -4
  128. package/src/ci-image.test.ts +1 -2
  129. package/src/ci-job-guard.before-merge.test.ts +148 -0
  130. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  131. package/src/ci-job-guard.follow-on.test.ts +144 -0
  132. package/src/ci-job-guard.ts +221 -3
  133. package/src/ci-note-commands.test.ts +76 -1
  134. package/src/ci-note-commands.ts +96 -7
  135. package/src/ci-product.ts +65 -6
  136. package/src/cli/handlers/pr-comment.ts +85 -2
  137. package/src/cli/handlers/pr-notes.ts +30 -6
  138. package/src/cli/handlers/pr.ts +34 -17
  139. package/src/cli/handlers/run-wave.ts +144 -4
  140. package/src/cli/main.ts +17 -0
  141. package/src/cli/parse-args.ts +20 -0
  142. package/src/cli/registry.ts +12 -1
  143. package/src/components/pr-checks.ts +66 -2
  144. package/src/components/pr-pipeline.ts +21 -9
  145. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  146. package/src/components/product-pipeline.ts +117 -9
  147. package/src/components/product-plan-names.test.ts +135 -0
  148. package/src/components/product-plan.test.ts +23 -5
  149. package/src/components/product-plan.ts +248 -25
  150. package/src/floor-table.data.ts +37 -23
  151. package/src/lexicon-module.ts +6 -2
  152. package/src/lexicon.ts +78 -1
  153. package/src/lifecycle/gate-applied.ts +7 -0
  154. package/src/op/apply-status.test.ts +83 -0
  155. package/src/op/apply-status.ts +132 -0
  156. package/src/op/before-merge-decide.ts +190 -0
  157. package/src/op/before-merge-done.ts +99 -0
  158. package/src/op/before-merge-store.ts +44 -0
  159. package/src/op/before-merge.test.ts +201 -0
  160. package/src/op/before-merge.ts +266 -0
  161. package/src/op/follow-on-run.ts +206 -0
  162. package/src/op/follow-on-store.ts +54 -0
  163. package/src/op/gate.ts +16 -1
  164. package/src/op/index.ts +5 -0
  165. package/src/op/op-waves-after-plan.ts +13 -0
  166. package/src/op/op-waves-evidence-jobs.ts +11 -3
  167. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  168. package/src/op/op-waves-follow-on.test.ts +247 -0
  169. package/src/op/op-waves-follow-on.ts +385 -0
  170. package/src/op/op-waves-render-spec.test.ts +1 -2
  171. package/src/op/op-waves-run.ts +971 -93
  172. package/src/op/op-waves-split-product.test.ts +288 -0
  173. package/src/op/op-waves-split-step.test.ts +298 -0
  174. package/src/op/op-waves-split.test.ts +196 -0
  175. package/src/op/op-waves-split.ts +189 -0
  176. package/src/op/op-waves.ts +28 -3
  177. package/src/op/schedule-overdue.test.ts +29 -1
  178. package/src/op/schedule-overdue.ts +27 -3
  179. package/src/op/stage-hooks.ts +52 -4
  180. package/src/op/wave-stop.ts +5 -3
  181. package/src/planned-files.test.ts +33 -0
  182. package/src/planned-files.ts +26 -10
  183. package/src/pr-post.ts +13 -5
  184. package/src/release-floors.ts +31 -19
  185. package/src/wave-blocked.ts +9 -4
@@ -0,0 +1,266 @@
1
+ /**
2
+ * Op waves before merge (#4984): the record that lets an open pull
3
+ * request's head run the waves.
4
+ *
5
+ * Maintainer decision (2026-11-10): waves before merge. The Op waves
6
+ * workflow gets a before-merge mode. The comment job (GitHub, Forgejo) or
7
+ * the note poll (GitLab) decides `/<product> apply` on an open pull
8
+ * request (./before-merge-decide.ts), writes the decided head here, and
9
+ * starts the waves workflow on the default branch for that head. Each wave
10
+ * job's guard (../ci-job-guard.ts) admits the run only when the head, the
11
+ * pull request and the digest it was started with are the ones recorded
12
+ * here. Per-wave runners, cloud identities and evidence stay as they are.
13
+ *
14
+ * The record is `_waves/<op>.before-merge.json` on `chant/lifecycle`, at the
15
+ * top of the branch whatever the member, so the guard reads it at one path.
16
+ * It keeps one decision per head, the newest {@link BEFORE_MERGE_KEPT}.
17
+ * Each decision's digest is sha256 over its fields in a fixed order
18
+ * ({@link beforeMergeDigest}); the run carries it, and the guard computes
19
+ * it again, so a decision edited by hand after it was made reads as no
20
+ * decision.
21
+ *
22
+ * A run carries the decision in three variables: GitHub and Forgejo map
23
+ * them from the `workflow_dispatch` inputs `pr`, `head` and `digest`; on
24
+ * GitLab they are the variables of the pipeline the poll starts.
25
+ */
26
+
27
+ import { createHash } from "node:crypto";
28
+ import { CHANT_EXIT } from "../exit-codes";
29
+
30
+ /** The variable a before-merge run carries the pull request in. */
31
+ export const BEFORE_MERGE_PR_ENV = "CHANT_BEFORE_MERGE_PR";
32
+ /** The variable a before-merge run carries the decided head in. */
33
+ export const BEFORE_MERGE_HEAD_ENV = "CHANT_BEFORE_MERGE_HEAD";
34
+ /** The variable a before-merge run carries the decision's digest in. */
35
+ export const BEFORE_MERGE_DIGEST_ENV = "CHANT_BEFORE_MERGE_DIGEST";
36
+
37
+ /**
38
+ * The variable a wave job's command reads its base from (#4984): set by the
39
+ * step that checks out the decided head, to the default branch's commit the
40
+ * run started at, so the gate policy, holds and spec render come from the
41
+ * default branch and never from the pull request.
42
+ */
43
+ export const WAVES_BASE_ENV = "CHANT_WAVES_BASE";
44
+
45
+ /** The `workflow_dispatch` inputs of a waves workflow with a before-merge mode, and the variables they map to. */
46
+ export const BEFORE_MERGE_INPUTS: Readonly<Record<"pr" | "head" | "digest", string>> = { pr: BEFORE_MERGE_PR_ENV, head: BEFORE_MERGE_HEAD_ENV, digest: BEFORE_MERGE_DIGEST_ENV };
47
+
48
+ /** The directory of the decisions on `chant/lifecycle`, beside the wave stops. */
49
+ export const BEFORE_MERGE_DIR = "_waves";
50
+
51
+ /** How many heads' decisions the file keeps. */
52
+ export const BEFORE_MERGE_KEPT = 50;
53
+
54
+ /** The decisions file of op `op`. */
55
+ export function beforeMergeFile(op: string): string {
56
+ return `${op}.before-merge.json`;
57
+ }
58
+
59
+ /** Its path from the top of `chant/lifecycle`, as the guard reads it. */
60
+ export function beforeMergePath(op: string): string {
61
+ return `${BEFORE_MERGE_DIR}/${beforeMergeFile(op)}`;
62
+ }
63
+
64
+ /** One decision: the pull request, the head it decided, the default branch's commit it was measured from, the last wave, who asked and when. */
65
+ export interface BeforeMergeDecision {
66
+ pr: number;
67
+ head: string;
68
+ base: string;
69
+ /** The last wave that runs, when the comment named one (`wave-<n>`). */
70
+ through?: number;
71
+ at: string;
72
+ by: string;
73
+ }
74
+
75
+ /** A decision with its digest, as the file keeps it. */
76
+ export interface BeforeMergeRecord extends BeforeMergeDecision {
77
+ digest: string;
78
+ }
79
+
80
+ /** The decisions file. */
81
+ export interface BeforeMergeFile {
82
+ version: 1;
83
+ heads: Record<string, BeforeMergeRecord>;
84
+ }
85
+
86
+ /** What a run says it was started for. Unset or empty: a push run. */
87
+ export interface BeforeMergeRun {
88
+ pr?: string;
89
+ head?: string;
90
+ digest?: string;
91
+ }
92
+
93
+ const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
94
+ const OP = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
95
+ const DIGEST = /^sha256:[0-9a-f]{64}$/;
96
+ const PR = /^[1-9][0-9]{0,9}$/;
97
+
98
+ /** The words the digest is taken over, in order. The guard's `node -e` program builds the same array. */
99
+ export function beforeMergeDigestInput(op: string, d: BeforeMergeDecision): string {
100
+ return JSON.stringify(["chant-before-merge/1", op, d.pr, d.head, d.base, d.through ?? 0, d.at, d.by]);
101
+ }
102
+
103
+ /** sha256 over {@link beforeMergeDigestInput}, as `sha256:<hex>`. */
104
+ export function beforeMergeDigest(op: string, d: BeforeMergeDecision): string {
105
+ return `sha256:${createHash("sha256").update(beforeMergeDigestInput(op, d)).digest("hex")}`;
106
+ }
107
+
108
+ /** Read a decisions file; anything that is not one reads as no decisions, and a malformed entry is dropped. */
109
+ export function parseBeforeMerge(text: string | null): BeforeMergeFile {
110
+ let doc: unknown;
111
+ try {
112
+ doc = JSON.parse(text ?? "null");
113
+ } catch {
114
+ return { version: 1, heads: {} };
115
+ }
116
+ const heads: Record<string, BeforeMergeRecord> = {};
117
+ const given = doc && typeof doc === "object" && (doc as { version?: unknown }).version === 1 ? (doc as { heads?: unknown }).heads : undefined;
118
+ if (given && typeof given === "object") {
119
+ for (const [head, r] of Object.entries(given as Record<string, unknown>)) {
120
+ const v = r as Partial<BeforeMergeRecord> | null;
121
+ if (!SHA.test(head) || !v || v.head !== head || !Number.isInteger(v.pr) || (v.pr as number) < 1) continue;
122
+ if (typeof v.base !== "string" || !SHA.test(v.base) || typeof v.at !== "string" || typeof v.by !== "string" || typeof v.digest !== "string") continue;
123
+ if (v.through !== undefined && (!Number.isInteger(v.through) || v.through < 1)) continue;
124
+ heads[head] = { pr: v.pr as number, head, base: v.base, ...(v.through !== undefined ? { through: v.through } : {}), at: v.at, by: v.by, digest: v.digest };
125
+ }
126
+ }
127
+ return { version: 1, heads };
128
+ }
129
+
130
+ /** The file's text: the newest {@link BEFORE_MERGE_KEPT} decisions, by head. */
131
+ export function renderBeforeMerge(file: BeforeMergeFile): string {
132
+ const newest = Object.entries(file.heads).sort((a, b) => b[1].at.localeCompare(a[1].at)).slice(0, BEFORE_MERGE_KEPT);
133
+ return `${JSON.stringify({ version: 1, heads: Object.fromEntries(newest.sort((a, b) => a[0].localeCompare(b[0]))) }, null, 2)}\n`;
134
+ }
135
+
136
+ /** The run's decision variables from the environment. */
137
+ export function beforeMergeRunFromEnv(env: Record<string, string | undefined> = process.env): BeforeMergeRun {
138
+ const v = (k: string): string | undefined => {
139
+ const s = env[k]?.trim();
140
+ return s ? s : undefined;
141
+ };
142
+ const pr = v(BEFORE_MERGE_PR_ENV);
143
+ const head = v(BEFORE_MERGE_HEAD_ENV);
144
+ const digest = v(BEFORE_MERGE_DIGEST_ENV);
145
+ return { ...(pr ? { pr } : {}), ...(head ? { head } : {}), ...(digest ? { digest } : {}) };
146
+ }
147
+
148
+ /** Whether a run names a decision at all: any of the three variables set. */
149
+ export function isBeforeMergeRun(run: BeforeMergeRun): boolean {
150
+ return run.pr !== undefined || run.head !== undefined || run.digest !== undefined;
151
+ }
152
+
153
+ const shown = (v: string | undefined): string => (v === undefined || v === "" ? "none" : JSON.stringify(v));
154
+
155
+ /**
156
+ * What stops a run that names a decision, one line each: a variable that is
157
+ * not what it should be, no decision for the head, a decision for another
158
+ * pull request, another digest, or a decision whose fields no longer give
159
+ * its digest. Empty: the run is the one decided. The guard's `node -e`
160
+ * program gives the same lines.
161
+ */
162
+ export function beforeMergeProblems(op: string, run: BeforeMergeRun, record: BeforeMergeRecord | undefined): string[] {
163
+ const p: string[] = [];
164
+ if (!run.pr || !PR.test(run.pr)) p.push(`before merge: the run's pull request ${shown(run.pr)} is not a number`);
165
+ if (!run.head || !SHA.test(run.head)) p.push(`before merge: the run's head ${shown(run.head)} is not a commit sha`);
166
+ if (!run.digest || !DIGEST.test(run.digest)) p.push(`before merge: the run's digest ${shown(run.digest)} is not a sha256 digest`);
167
+ if (p.length > 0) return p;
168
+ const head = run.head!.slice(0, 12);
169
+ if (!record) return [`before merge: no decision on chant/lifecycle names head ${head} of ${op}, so this run applies nothing`];
170
+ if (record.pr !== Number(run.pr)) p.push(`before merge: the decision for head ${head} is pull request ${record.pr}'s, not ${run.pr}'s`);
171
+ if (record.digest !== run.digest) p.push(`before merge: the run carries digest ${run.digest}, and the decision for head ${head} has ${record.digest}`);
172
+ if (beforeMergeDigest(op, record) !== record.digest) p.push(`before merge: the decision for head ${head} was changed after it was made: its fields give another digest`);
173
+ return p;
174
+ }
175
+
176
+ /**
177
+ * The before-merge mode of an Op waves pipeline (#4984),
178
+ * `OpWavesPipelineOptions.beforeMerge`.
179
+ */
180
+ export interface OpWavesBeforeMerge {
181
+ /**
182
+ * What the job after the last wave does once every wave applied the
183
+ * decided head. `auto`: it merges the pull request at that head (only
184
+ * while it is still the head, open and approved) and releases the locks
185
+ * the change holds. `manual` (the default): it replies that the head
186
+ * applied, and the locks hold until the pull request merges or closes.
187
+ */
188
+ merge?: "auto" | "manual";
189
+ /**
190
+ * The secret (GitHub, Forgejo) or CI/CD variable (GitLab) the merge takes
191
+ * its token from, with `merge: "auto"`. GitHub merges with the job's own
192
+ * token when it is absent. Forgejo refuses a merge made with the job's
193
+ * own token, and GitLab's job token cannot merge, so both need it.
194
+ */
195
+ mergeTokenSecret?: string;
196
+ /** The lock file the change's locks are in, `_locks/<gate>.json`, which `merge: "auto"` releases. Default the pull request loop's. */
197
+ gate?: string;
198
+ }
199
+
200
+ /** The job after the last wave of a before-merge run (#4984). */
201
+ export const BEFORE_MERGE_DONE_JOB = "before-merge-done";
202
+
203
+ /** The variable the done job hands the merge token to `--merge-token-env` in. */
204
+ export const BEFORE_MERGE_TOKEN_ENV = "CHANT_MERGE_TOKEN";
205
+
206
+ /** Check the mode's options for `forge`; throws with the reason. */
207
+ export function assertOpWavesBeforeMerge(forge: "github" | "forgejo" | "gitlab", bm: OpWavesBeforeMerge): void {
208
+ if (bm.merge !== undefined && bm.merge !== "auto" && bm.merge !== "manual") throw new Error(`beforeMerge.merge is auto or manual, not ${JSON.stringify(bm.merge)}`);
209
+ if (bm.mergeTokenSecret !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(bm.mergeTokenSecret)) throw new Error(`beforeMerge.mergeTokenSecret ${JSON.stringify(bm.mergeTokenSecret)} is not a variable name`);
210
+ if (bm.gate !== undefined && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(bm.gate)) throw new Error(`beforeMerge.gate ${JSON.stringify(bm.gate)} is not a lock file name`);
211
+ if (bm.merge === "auto" && forge !== "github" && !bm.mergeTokenSecret) {
212
+ throw new Error(`beforeMerge.merge auto on ${forge} needs mergeTokenSecret: ${forge === "forgejo" ? "Forgejo refuses a merge made with the job's own token" : "GitLab's job token cannot merge"}`);
213
+ }
214
+ }
215
+
216
+ /**
217
+ * The done job's command, through the product's bin: `chant run wave --op
218
+ * <op> --wave <last wave> --merge auto|manual --forge <forge>`. It names the
219
+ * op and the wave count rather than the spec file, which a spec rendered at
220
+ * run time (#4982) leaves uncommitted.
221
+ */
222
+ export function beforeMergeDoneCommand(spec: { name: string; waves: readonly unknown[] }, forge: "github" | "forgejo" | "gitlab", bm: OpWavesBeforeMerge, bin?: string): string {
223
+ const words = (bin ?? "").split(/\s+/).filter(Boolean);
224
+ return [
225
+ ...(words.length > 0 ? words : ["chant"]),
226
+ "run", "wave", "--op", spec.name, "--wave", String(spec.waves.length),
227
+ "--merge", bm.merge ?? "manual",
228
+ "--forge", forge,
229
+ ...(bm.gate ? ["--gate", bm.gate] : []),
230
+ ...(bm.merge === "auto" && bm.mergeTokenSecret ? ["--merge-token-env", BEFORE_MERGE_TOKEN_ENV] : []),
231
+ ].join(" ");
232
+ }
233
+
234
+ /**
235
+ * The lines that check out the decided head (#4984), right after the
236
+ * default branch's checkout and before any of the change's code: nothing
237
+ * on a push run; else fetch the pull request's head ref, stop (exit 9,
238
+ * chant's `misplaced`) unless it is still the decided head, keep the
239
+ * default branch's commit as {@link WAVES_BASE_ENV} for the command, and
240
+ * check the head out. One shell block, so on GitLab it sits among the
241
+ * script's lines. With `checkout: false` (#4987) it fetches and checks the
242
+ * head and keeps the base, and leaves the default branch checked out: the
243
+ * gate and record jobs of a split wave read the head's commit and notes
244
+ * and run none of its code.
245
+ */
246
+ export function beforeMergeCheckoutScript(forge: "github" | "forgejo" | "gitlab", product: string, opts: { checkout?: boolean } = {}): string {
247
+ const ref = forge === "gitlab" ? `refs/merge-requests/\${${BEFORE_MERGE_PR_ENV}}/head` : `refs/pull/\${${BEFORE_MERGE_PR_ENV}}/head`;
248
+ const what = forge === "gitlab" ? `!$${BEFORE_MERGE_PR_ENV}` : `pull request $${BEFORE_MERGE_PR_ENV}`;
249
+ const keep = forge === "gitlab" ? `${WAVES_BASE_ENV}="$(git rev-parse HEAD)"; export ${WAVES_BASE_ENV}` : `echo "${WAVES_BASE_ENV}=$(git rev-parse HEAD)" >> "$GITHUB_ENV"`;
250
+ return [
251
+ `if [ -n "\${${BEFORE_MERGE_HEAD_ENV}:-}" ]; then`,
252
+ ` git fetch -q --no-tags origin "+${ref}:refs/remotes/chant/before-merge-head" || { echo "${product}: could not fetch the head of ${what}" >&2; exit 1; }`,
253
+ ' now="$(git rev-parse refs/remotes/chant/before-merge-head)"',
254
+ ` if [ "$now" != "$${BEFORE_MERGE_HEAD_ENV}" ]; then echo "${product}: ${what} moved to $(printf %.12s "$now") after its head $(printf %.12s "$${BEFORE_MERGE_HEAD_ENV}") was decided, so nothing is applied; comment the apply again" >&2; exit ${CHANT_EXIT.misplaced}; fi`,
255
+ ` ${keep}`,
256
+ ...(opts.checkout === false ? [] : [` git checkout -q --detach "$${BEFORE_MERGE_HEAD_ENV}" || exit 1`]),
257
+ "fi",
258
+ ].join("\n");
259
+ }
260
+
261
+ /** Whether `op` names a decisions file and `sha` a commit. */
262
+ export function beforeMergeKeyProblem(op: string, sha: string): string | undefined {
263
+ if (!OP.test(op)) return `the op name ${JSON.stringify(op)} is not a decisions file name`;
264
+ if (!SHA.test(sha)) return `${JSON.stringify(sha)} is not a commit sha`;
265
+ return undefined;
266
+ }
@@ -0,0 +1,206 @@
1
+ /**
2
+ * What a follow-on run of a `rest` wave carries (#4992), kept free of
3
+ * imports so the job guard (../ci-job-guard.ts) reads it without the waves
4
+ * runner.
5
+ *
6
+ * Maintainer decision (2026-11-10): before merge a `rest` wave's waves run
7
+ * one per run. The record job of the last rendered wave, when the plan found
8
+ * another wave, starts the waves workflow again for it (./op-waves-follow-on.ts).
9
+ * The new run carries the wave in {@link OP_WAVES_WAVE_ENV}, beside the
10
+ * before-merge decision's three variables (./before-merge.ts), or, for a
11
+ * push's run, the pushed commit in {@link OP_WAVES_COMMIT_ENV}. The rest
12
+ * wave's jobs default the wave to their own number, so a run that is no
13
+ * follow-on reads the same; the jobs of the waves before it do not run.
14
+ *
15
+ * #4998: before it starts a follow-on, the record job records it on
16
+ * `chant/lifecycle`, at {@link followOnPath}: one entry per chain, keyed by
17
+ * the decided head (before merge) or the pushed commit, naming the wave it
18
+ * started, the run that started it, the decision or the commit, and the
19
+ * outcomes of every run of the chain so far. Each follow-on replaces the
20
+ * entry, so it names the wave the newest record job started. The guard
21
+ * admits a follow-on only for that wave ({@link followOnRecordProblems}),
22
+ * so a wave started by hand past it, or an earlier wave run again after
23
+ * the chain went on, is refused.
24
+ */
25
+
26
+ /** The wave the rest wave's jobs run: their own number, or a later one in a follow-on run. */
27
+ export const OP_WAVES_WAVE_ENV = "CHANT_WAVES_WAVE";
28
+
29
+ /** The commit a push's follow-on run goes on with: the pushed commit the first run applied. */
30
+ export const OP_WAVES_COMMIT_ENV = "CHANT_WAVES_COMMIT";
31
+
32
+ /** The `workflow_dispatch` inputs a follow-on adds (GitHub, Forgejo), and the variables they map to. */
33
+ export const FOLLOW_ON_INPUTS: Readonly<Record<"wave" | "commit", string>> = { wave: OP_WAVES_WAVE_ENV, commit: OP_WAVES_COMMIT_ENV };
34
+
35
+ /** What a run says about a follow-on, from its variables. Unset or empty: none. */
36
+ export interface FollowOnRun {
37
+ wave?: string;
38
+ commit?: string;
39
+ }
40
+
41
+ /** The run's follow-on variables from the environment. */
42
+ export function followOnRunFromEnv(env: Record<string, string | undefined> = process.env): FollowOnRun {
43
+ const wave = env[OP_WAVES_WAVE_ENV]?.trim();
44
+ const commit = env[OP_WAVES_COMMIT_ENV]?.trim();
45
+ return { ...(wave ? { wave } : {}), ...(commit ? { commit } : {}) };
46
+ }
47
+
48
+ const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
49
+ const WAVE = /^[1-9][0-9]{0,5}$/;
50
+
51
+ /**
52
+ * What stops a job that sees follow-on variables, one line each, and what
53
+ * it checked. `rest` is the rest wave's number when the job is one of its
54
+ * jobs. A job of the rest wave reads its own number when the run is no
55
+ * follow-on. A follow-on's wave comes after the rest wave's; a follow-on of
56
+ * a decided head carries no commit (the head is what it checks out), and a
57
+ * push's names the commit. The job guard's `node -e` program gives the same
58
+ * lines.
59
+ */
60
+ export function followOnProblems(rest: number | undefined, run: FollowOnRun, beforeMerge: boolean): { problems: string[]; checked?: string } {
61
+ const { wave, commit } = run;
62
+ if (rest === undefined) {
63
+ if (wave === undefined && commit === undefined) return { problems: [] };
64
+ return { problems: [`follow-on: the run names wave ${wave ?? "none"} and commit ${commit ?? "none"}, and this job is none of the rest wave's, which alone runs in a follow-on`] };
65
+ }
66
+ if (wave === undefined || wave === String(rest)) {
67
+ if (commit === undefined) return { problems: [] };
68
+ return { problems: [`follow-on: the run names the commit ${commit} and no wave after wave ${rest}, so it is no follow-on`] };
69
+ }
70
+ if (!WAVE.test(wave) || Number(wave) <= rest) return { problems: [`follow-on: the run's wave ${JSON.stringify(wave)} is no wave after wave ${rest}`] };
71
+ if (beforeMerge) {
72
+ if (commit !== undefined) return { problems: [`follow-on: a follow-on of a decided head checks out that head, and the run names the commit ${commit} too`] };
73
+ return { problems: [], checked: `follow-on wave ${wave}` };
74
+ }
75
+ if (commit === undefined || !SHA.test(commit)) return { problems: [`follow-on: a push's follow-on names the commit it goes on with, and the run's ${commit === undefined ? "none" : JSON.stringify(commit)} is not a commit sha`] };
76
+ return { problems: [], checked: `follow-on wave ${wave} at ${commit.slice(0, 12)}` };
77
+ }
78
+
79
+ /** The directory of the follow-on records on `chant/lifecycle` (#4998): beside the before-merge decisions, `_waves`. */
80
+ export const FOLLOW_ON_DIR = "_waves";
81
+
82
+ /** How many chains' records the file keeps. */
83
+ export const FOLLOW_ON_KEPT = 50;
84
+
85
+ /** The follow-on records file of op `op`. */
86
+ export function followOnFile(op: string): string {
87
+ return `${op}.follow-on.json`;
88
+ }
89
+
90
+ /** Its path from the top of `chant/lifecycle`, as the guard reads it. */
91
+ export function followOnPath(op: string): string {
92
+ return `${FOLLOW_ON_DIR}/${followOnFile(op)}`;
93
+ }
94
+
95
+ /** One run's outcome as a chain carries it: a wave outcome file's member, with the wave and the time it was written. */
96
+ export interface FollowOnOutcome {
97
+ status: string;
98
+ by?: string;
99
+ wave: number;
100
+ at: string;
101
+ }
102
+
103
+ /** The record of the newest follow-on of one chain (#4998). */
104
+ export interface FollowOnRecord {
105
+ /** The decided head a before-merge chain applies, or the commit a push's chain goes on with. */
106
+ key: string;
107
+ /** The wave of the follow-on the record job started. */
108
+ wave: number;
109
+ /** The wave the run that started it ran. */
110
+ from: number;
111
+ /** The id of the run that started it (GitHub and Forgejo `GITHUB_RUN_ID`, GitLab `CI_PIPELINE_ID`). */
112
+ run: string;
113
+ /** That run's page, when the forge names it. */
114
+ url?: string;
115
+ /** When the record job wrote it, ISO 8601. */
116
+ at: string;
117
+ /** Before merge: the decision's pull request and digest. */
118
+ pr?: number;
119
+ digest?: string;
120
+ /** A push's chain: the pushed commit, the same as `key`. */
121
+ commit?: string;
122
+ /** Every run's outcomes so far, by member: the newest of each. */
123
+ outcomes: Record<string, FollowOnOutcome>;
124
+ }
125
+
126
+ /** Where the rest wave's record job reads and writes a chain's record (./follow-on-store.ts: `chant/lifecycle`, or memory). */
127
+ export interface FollowOnChainPort {
128
+ /** The record of the chain keyed `key`, as the remote has it; undefined when there is none. */
129
+ read(op: string, key: string): Promise<FollowOnRecord | undefined>;
130
+ /** Replace the chain's record and push it, so the follow-on's guard reads it. */
131
+ write(op: string, record: FollowOnRecord): Promise<void>;
132
+ }
133
+
134
+ /** The follow-on records file: one entry per chain, by its key. */
135
+ export interface FollowOnFile {
136
+ version: 1;
137
+ chains: Record<string, FollowOnRecord>;
138
+ }
139
+
140
+ const isWhole = (v: unknown, min: number): v is number => Number.isInteger(v) && (v as number) >= min;
141
+
142
+ /**
143
+ * Read a follow-on records file; anything that is not one reads as no
144
+ * records, a malformed entry is dropped, and so is a malformed outcome. The
145
+ * guard's `node -e` program checks an entry the same way.
146
+ */
147
+ export function parseFollowOn(text: string | null): FollowOnFile {
148
+ let doc: unknown;
149
+ try {
150
+ doc = JSON.parse(text ?? "null");
151
+ } catch {
152
+ return { version: 1, chains: {} };
153
+ }
154
+ const chains: Record<string, FollowOnRecord> = {};
155
+ const given = doc && typeof doc === "object" && (doc as { version?: unknown }).version === 1 ? (doc as { chains?: unknown }).chains : undefined;
156
+ if (given && typeof given === "object") {
157
+ for (const [key, r] of Object.entries(given as Record<string, unknown>)) {
158
+ const v = r as Partial<FollowOnRecord> | null;
159
+ if (!SHA.test(key) || !v || typeof v !== "object" || v.key !== key || !isWhole(v.wave, 2) || !isWhole(v.from, 1) || typeof v.run !== "string" || typeof v.at !== "string") continue;
160
+ if ((v.digest !== undefined && typeof v.digest !== "string") || (v.pr !== undefined && !isWhole(v.pr, 1)) || (v.commit !== undefined && (typeof v.commit !== "string" || !SHA.test(v.commit)))) continue;
161
+ if (!v.outcomes || typeof v.outcomes !== "object") continue;
162
+ const outcomes: Record<string, FollowOnOutcome> = {};
163
+ for (const [member, o] of Object.entries(v.outcomes as Record<string, Partial<FollowOnOutcome> | null>)) {
164
+ if (!o || typeof o.status !== "string" || !isWhole(o.wave, 1) || typeof o.at !== "string" || (o.by !== undefined && typeof o.by !== "string")) continue;
165
+ outcomes[member] = { status: o.status, ...(o.by !== undefined ? { by: o.by } : {}), wave: o.wave, at: o.at };
166
+ }
167
+ chains[key] = {
168
+ key,
169
+ wave: v.wave,
170
+ from: v.from,
171
+ run: v.run,
172
+ ...(typeof v.url === "string" ? { url: v.url } : {}),
173
+ at: v.at,
174
+ ...(v.pr !== undefined ? { pr: v.pr } : {}),
175
+ ...(v.digest !== undefined ? { digest: v.digest } : {}),
176
+ ...(v.commit !== undefined ? { commit: v.commit } : {}),
177
+ outcomes,
178
+ };
179
+ }
180
+ }
181
+ return { version: 1, chains };
182
+ }
183
+
184
+ /** The file's text: the newest {@link FOLLOW_ON_KEPT} chains, by key. */
185
+ export function renderFollowOn(file: FollowOnFile): string {
186
+ const newest = Object.entries(file.chains).sort((a, b) => b[1].at.localeCompare(a[1].at)).slice(0, FOLLOW_ON_KEPT);
187
+ return `${JSON.stringify({ version: 1, chains: Object.fromEntries(newest.sort((a, b) => a[0].localeCompare(b[0]))) }, null, 2)}\n`;
188
+ }
189
+
190
+ /**
191
+ * What stops a follow-on run (#4998) that {@link followOnProblems} let
192
+ * through, one line each: no record for its chain, a record that started
193
+ * another wave, or, before merge, one started for another decision. `key`
194
+ * is the run's decided head, or a push's commit; `digest` the run's
195
+ * decision digest before merge. Empty: the newest record job of the chain
196
+ * started this wave. The guard's `node -e` program gives the same lines.
197
+ */
198
+ export function followOnRecordProblems(op: string, wave: string, key: string, digest: string | undefined, record: FollowOnRecord | null | undefined): string[] {
199
+ const what = digest !== undefined ? "head" : "commit";
200
+ const short = key.slice(0, 12);
201
+ if (!record) return [`follow-on: no record job of ${op} started a follow-on for ${what} ${short}, so this run applies nothing`];
202
+ const p: string[] = [];
203
+ if (String(record.wave) !== wave) p.push(`follow-on: the newest record job of ${op} for ${what} ${short} started wave ${record.wave}, and this run names wave ${wave}`);
204
+ if (digest !== undefined && record.digest !== digest) p.push(`follow-on: wave ${record.wave} of ${what} ${short} was started for the decision with digest ${record.digest ?? "none"}, and the run carries ${digest}`);
205
+ return p;
206
+ }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The follow-on records on `chant/lifecycle` (#4998): read and written
3
+ * through the ledger's git, at `_waves/<op>.follow-on.json` from the top of
4
+ * the branch (./follow-on-run.ts says what a record is). Kept apart so the
5
+ * generators and the guard load no git code.
6
+ */
7
+
8
+ import { fetchLifecycleStatus, pushLifecycleStatus, readBlobBySha, readPathSha, writeBlobToPath } from "../lifecycle/git";
9
+ import { FOLLOW_ON_DIR, followOnFile, parseFollowOn, renderFollowOn, type FollowOnChainPort, type FollowOnFile } from "./follow-on-run";
10
+
11
+ export type { FollowOnChainPort } from "./follow-on-run";
12
+
13
+ /** The port over `chant/lifecycle`: fetched, written and pushed again when another writer pushed first, up to three times. */
14
+ export function gitFollowOnChainPort(opts: { cwd?: string } = {}): FollowOnChainPort {
15
+ const where = { ...opts, ledgerPrefix: "" };
16
+ return {
17
+ async read(op, key) {
18
+ const fetched = await fetchLifecycleStatus(opts);
19
+ if (fetched.status === "unreachable") throw new Error("chant/lifecycle could not be fetched, so the follow-on records cannot be read");
20
+ const blob = await readPathSha(FOLLOW_ON_DIR, followOnFile(op), where);
21
+ if (!blob) return undefined;
22
+ return parseFollowOn(await readBlobBySha(blob, opts)).chains[key];
23
+ },
24
+ async write(op, record) {
25
+ for (let attempt = 1; attempt <= 3; attempt++) {
26
+ const fetched = await fetchLifecycleStatus(opts);
27
+ if (fetched.status === "unreachable") throw new Error("chant/lifecycle could not be fetched, so the follow-on was not recorded");
28
+ const blob = await readPathSha(FOLLOW_ON_DIR, followOnFile(op), where);
29
+ const file = parseFollowOn(blob ? await readBlobBySha(blob, opts) : null);
30
+ const next: FollowOnFile = { version: 1, chains: { ...file.chains, [record.key]: record } };
31
+ await writeBlobToPath(FOLLOW_ON_DIR, followOnFile(op), renderFollowOn(next), `Follow on ${op}: wave ${record.wave} at ${record.key.slice(0, 12)}, started by run ${record.run}`, { ...where, expectPriorPathSha: blob });
32
+ const pushed = await pushLifecycleStatus(opts);
33
+ if (pushed.status === "stale") continue;
34
+ if (pushed.status === "failed") throw new Error(`could not push the follow-on record to chant/lifecycle (${pushed.stderr.trim()})`);
35
+ return;
36
+ }
37
+ throw new Error("chant/lifecycle kept moving, so the follow-on was not recorded");
38
+ },
39
+ };
40
+ }
41
+
42
+ /** A port held in memory, for tests and for a caller that keeps the records itself. */
43
+ export function memoryFollowOnChainPort(initial: Record<string, FollowOnFile> = {}): FollowOnChainPort & { files: Record<string, FollowOnFile> } {
44
+ const files: Record<string, FollowOnFile> = { ...initial };
45
+ return {
46
+ files,
47
+ async read(op, key) {
48
+ return files[op]?.chains[key];
49
+ },
50
+ async write(op, record) {
51
+ files[op] = parseFollowOn(renderFollowOn({ version: 1, chains: { ...(files[op]?.chains ?? {}), [record.key]: record } }));
52
+ },
53
+ };
54
+ }
package/src/op/gate.ts CHANGED
@@ -51,7 +51,7 @@ import {
51
51
  } from "../lifecycle/gate-ledger";
52
52
  import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
53
53
  import { isModelAuthored } from "../lifecycle/gate-origin";
54
- import { appliedGatePath, isApprovalSpent, parseAppliedGateLines, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
54
+ import { appliedGatePath, isApprovalSpent, parseAppliedGateFile, parseAppliedGateLines, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
55
55
  import { gatedRequestAttachmentPath } from "../lifecycle/gated-request-digest";
56
56
  import { sortedJsonReplacer } from "../utils";
57
57
  import { gateContextDigest, type GateApprover, type GateBaseApproval, type ResolvedGateApproval } from "./gate-approval";
@@ -125,6 +125,12 @@ export interface GateLedgerPort {
125
125
  * Absent on a port that keeps none.
126
126
  */
127
127
  appendFinished?(record: FinishedGateRecord): Promise<{ pushed: boolean; pushWarning?: string }>;
128
+ /**
129
+ * The finished lines of `_gates/<op>/applied.jsonl` (#4994), oldest first,
130
+ * which say an apply under an approval ended. Absent on a port that keeps
131
+ * none.
132
+ */
133
+ readFinished?(op: string): Promise<FinishedGateRecord[]>;
128
134
  /**
129
135
  * Store a file a held request carries, such as a migration's proof, at
130
136
  * `_gates/<op>/requests/<digest>.json` (#4623), once, before the pending
@@ -233,6 +239,12 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
233
239
  const text = await readBlobFromPath(dir, file, opts);
234
240
  return text ? parseAppliedGateLines(text) : [];
235
241
  },
242
+ async readFinished(op) {
243
+ await requireLifecycleLedger(opts);
244
+ const { dir, file } = appliedGatePath(op);
245
+ const text = await readBlobFromPath(dir, file, opts);
246
+ return text ? parseAppliedGateFile(text).finished.map((f) => ({ ...f, op: f.op || op })) : [];
247
+ },
236
248
  async appendApplied(record) {
237
249
  return appendAppliedFileLine(record.op, record as unknown as Record<string, unknown>, `Applied under ${record.gate}`);
238
250
  },
@@ -344,6 +356,9 @@ export function memoryGateLedgerPort(
344
356
  finished.push(record);
345
357
  return { pushed: true };
346
358
  },
359
+ async readFinished(op) {
360
+ return finished.filter((f) => f.op === op);
361
+ },
347
362
  async storeRequestAttachment(op, digest, text) {
348
363
  if (!attachments.has(`${op}/${digest}`)) attachments.set(`${op}/${digest}`, text);
349
364
  },
package/src/op/index.ts CHANGED
@@ -105,6 +105,9 @@ export type {
105
105
  OpWaveHoldRequest,
106
106
  OpWaveHookOutcome,
107
107
  OpWaveHookRun,
108
+ OpWaveInProcessHook,
109
+ OpWaveInProcessHookCall,
110
+ OpWaveHandedFinished,
108
111
  OpWaveHooksFile,
109
112
  OpWaveHooksResult,
110
113
  OpWaveMember,
@@ -153,6 +156,8 @@ export { OP_WAVE_RELEASE_RECORD_FLOOR, opWaveReleaseNames, opWaveReleaseProblems
153
156
  export { gitOpWaveReleasePort } from "./op-waves-release-port";
154
157
  export type { OpWaveReleaseNames, OpWaveReleaseOutcome, OpWaveReleasePort, OpWaveReleaseRequest } from "./op-waves-release";
155
158
  export { OP_WAVE_AFTER_PLAN_WAVE_FLOOR, OP_WAVE_ANSWER_APPROVALS_FLOOR, foldPolicyRows, opWaveAfterPlanProblems, opWaveAfterPlanResultProblems, opWaveAfterPlanWaveResultProblems, runOpWaveAfterPlanHooks } from "./op-waves-after-plan";
159
+ export type { ProductWaveHook } from "./op-waves-after-plan";
160
+ export { opWaveProductStateDir } from "./op-waves-split";
156
161
  export type { OpWaveAfterPlanHook, OpWaveAnswerApproval, OpWaveAfterPlanOutcome, OpWaveAfterPlanResult, OpWaveAfterPlanRun, OpWaveAfterPlanRunOutcome, OpWaveAfterPlanWave, OpWaveAfterPlanWaveOutcome, OpWaveAfterPlanWaveResult } from "./op-waves-after-plan";
157
162
  export { OP_WAVE_AFTER_PLAN_FLOOR } from "./runtime";
158
163
  export { OP_WAVE_RUN_HOOKS_FLOOR, opWaveRunHooksProblems } from "./op-waves-run-hooks";
@@ -430,6 +430,13 @@ export function foldPolicyRows(
430
430
  * (#4614): `runChantInProcess(["run", "wave", ...], words, { wave })`. The
431
431
  * job then calls the product's after-plan hooks, and plans and applies a
432
432
  * `step` through the product's own capability registry when it gives one.
433
+ *
434
+ * #4994: the same hook works in each job of a split wave
435
+ * (`run wave --phase plan|gate|apply|record`) and in the one-job shape. The
436
+ * plan job calls `afterPlan` and plans through `capabilities` and
437
+ * `runHooks`; the applying job plans its runs again and applies them
438
+ * through them; the gate and record jobs plan nothing. `hooks` serves the
439
+ * spec's own hooks in the process of whichever job runs them.
433
440
  */
434
441
  export interface ProductWaveHook {
435
442
  afterPlan?: OpWaveAfterPlanHook | readonly OpWaveAfterPlanHook[];
@@ -438,6 +445,12 @@ export interface ProductWaveHook {
438
445
  hookExec?: import("./stage-hooks").OpWaveAsyncExec;
439
446
  /** Hooks around each run of a wave with a `step` (#4842, `RunOpWaveOptions.runHooks`). */
440
447
  runHooks?: import("./op-waves-run-hooks").OpWaveRunHooks | readonly import("./op-waves-run-hooks").OpWaveRunHooks[];
448
+ /**
449
+ * The spec's hooks served in this process, by name (#4994,
450
+ * `RunOpWaveOptions.inProcessHooks`): in place of a hook command that
451
+ * called back into a long-lived product process over a socket.
452
+ */
453
+ hooks?: Readonly<Record<string, import("./stage-hooks").OpWaveInProcessHook>>;
441
454
  }
442
455
 
443
456
  let activeWave: ProductWaveHook | undefined;
@@ -28,6 +28,7 @@
28
28
 
29
29
  import { EVIDENCE_SOURCES_ENV, WAVE_EVIDENCE_ENV, type EvidenceSourceSpec } from "../ci-evidence-claims";
30
30
  import { opWaveBinArgv, opWaveChecksDir, type OpWaveJob, type OpWavesSpec } from "./op-waves";
31
+ import { BEFORE_MERGE_HEAD_ENV } from "./before-merge";
31
32
 
32
33
  export { EVIDENCE_SOURCES_ENV, WAVE_EVIDENCE_ENV };
33
34
 
@@ -102,13 +103,20 @@ export function opWaveEvidenceSources(forge: "github" | "forgejo" | "gitlab", pl
102
103
  * setup and the product's command after it are the base's code and none of
103
104
  * the change's runs, then sign from the wave job. `sha` is the run's commit
104
105
  * as the shell reads it; the first line keeps the base in
105
- * {@link OP_WAVE_EVIDENCE_BASE_VAR}.
106
+ * {@link OP_WAVE_EVIDENCE_BASE_VAR}. With `beforeMerge` (#4984), a run of a
107
+ * pull request's decided head takes the checkout's commit, the default
108
+ * branch's the run started at, as its base; `sha` then names the head.
106
109
  */
107
- export function opWaveEvidenceLines(spec: Pick<OpWavesSpec, "name" | "base">, plan: OpWaveEvidencePlan, job: Pick<OpWaveJob, "jobName">, opts: { sha: string; bin?: string }): { checkout: string[]; sign: string[] } {
110
+ export function opWaveEvidenceLines(spec: Pick<OpWavesSpec, "name" | "base">, plan: OpWaveEvidencePlan, job: Pick<OpWaveJob, "jobName">, opts: { sha: string; bin?: string; beforeMerge?: boolean }): { checkout: string[]; sign: string[] } {
108
111
  const base = spec.base ?? "HEAD^1";
109
112
  const quoted = `'${base.replace(/'/g, "'\\''")}'`;
113
+ const fromSpec = `${OP_WAVE_EVIDENCE_BASE_VAR}="$(git rev-parse --verify ${quoted}^{commit})" || exit 1`;
114
+ // #4984: a run of a pull request's decided head was measured from the default branch's commit it started at, the checkout here.
115
+ const baseLine = opts.beforeMerge
116
+ ? `if [ -n "\${${BEFORE_MERGE_HEAD_ENV}:-}" ]; then ${OP_WAVE_EVIDENCE_BASE_VAR}="$(git rev-parse --verify HEAD^{commit})" || exit 1; else ${fromSpec}; fi`
117
+ : fromSpec;
110
118
  return {
111
- checkout: [`${OP_WAVE_EVIDENCE_BASE_VAR}="$(git rev-parse --verify ${quoted}^{commit})" || exit 1`, `git checkout --quiet --detach "$${OP_WAVE_EVIDENCE_BASE_VAR}" || exit 1`],
119
+ checkout: [baseLine, `git checkout --quiet --detach "$${OP_WAVE_EVIDENCE_BASE_VAR}" || exit 1`],
112
120
  sign: [
113
121
  [
114
122
  ...opWaveBinArgv(opts.bin),