@intentius/chant 0.124.88 → 0.124.90

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 (377) hide show
  1. package/dist/actor.d.ts +36 -1
  2. package/dist/actor.d.ts.map +1 -1
  3. package/dist/actor.js +39 -1
  4. package/dist/chant-install.d.ts.map +1 -1
  5. package/dist/chant-install.js +1 -2
  6. package/dist/ci-base.d.ts +30 -0
  7. package/dist/ci-base.d.ts.map +1 -0
  8. package/dist/ci-base.js +33 -0
  9. package/dist/ci-comment-commands.d.ts +193 -0
  10. package/dist/ci-comment-commands.d.ts.map +1 -0
  11. package/dist/ci-comment-commands.js +353 -0
  12. package/dist/ci-comment-replies.d.ts +40 -0
  13. package/dist/ci-comment-replies.d.ts.map +1 -0
  14. package/dist/ci-comment-replies.js +59 -0
  15. package/dist/ci-evidence-from-job.d.ts +25 -0
  16. package/dist/ci-evidence-from-job.d.ts.map +1 -1
  17. package/dist/ci-evidence-from-job.js +43 -2
  18. package/dist/ci-evidence-jobs.d.ts +30 -1
  19. package/dist/ci-evidence-jobs.d.ts.map +1 -1
  20. package/dist/ci-evidence-jobs.js +46 -3
  21. package/dist/ci-image.d.ts +21 -4
  22. package/dist/ci-image.d.ts.map +1 -1
  23. package/dist/ci-image.js +62 -10
  24. package/dist/ci-job-guard.d.ts +42 -45
  25. package/dist/ci-job-guard.d.ts.map +1 -1
  26. package/dist/ci-job-guard.js +206 -3
  27. package/dist/ci-note-commands.d.ts +104 -4
  28. package/dist/ci-note-commands.d.ts.map +1 -1
  29. package/dist/ci-note-commands.js +131 -38
  30. package/dist/ci-product-words.d.ts +42 -0
  31. package/dist/ci-product-words.d.ts.map +1 -1
  32. package/dist/ci-product-words.js +25 -0
  33. package/dist/ci-product.d.ts +72 -1
  34. package/dist/ci-product.d.ts.map +1 -1
  35. package/dist/ci-product.js +73 -6
  36. package/dist/cli/commands/build.d.ts.map +1 -1
  37. package/dist/cli/commands/build.js +29 -2
  38. package/dist/cli/handlers/approve.d.ts.map +1 -1
  39. package/dist/cli/handlers/approve.js +2 -1
  40. package/dist/cli/handlers/ci-check.d.ts +1 -1
  41. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  42. package/dist/cli/handlers/ci-check.js +17 -7
  43. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -1
  44. package/dist/cli/handlers/ci-evidence.js +33 -7
  45. package/dist/cli/handlers/components.d.ts.map +1 -1
  46. package/dist/cli/handlers/components.js +3 -1
  47. package/dist/cli/handlers/generated-check.d.ts +8 -0
  48. package/dist/cli/handlers/generated-check.d.ts.map +1 -1
  49. package/dist/cli/handlers/generated-check.js +31 -1
  50. package/dist/cli/handlers/lock.d.ts.map +1 -1
  51. package/dist/cli/handlers/lock.js +121 -4
  52. package/dist/cli/handlers/pr-comment.d.ts +33 -0
  53. package/dist/cli/handlers/pr-comment.d.ts.map +1 -0
  54. package/dist/cli/handlers/pr-comment.js +201 -0
  55. package/dist/cli/handlers/pr-env.d.ts.map +1 -1
  56. package/dist/cli/handlers/pr-env.js +6 -3
  57. package/dist/cli/handlers/pr-notes.d.ts.map +1 -1
  58. package/dist/cli/handlers/pr-notes.js +23 -1
  59. package/dist/cli/handlers/pr.d.ts +23 -1
  60. package/dist/cli/handlers/pr.d.ts.map +1 -1
  61. package/dist/cli/handlers/pr.js +71 -23
  62. package/dist/cli/handlers/promote.d.ts.map +1 -1
  63. package/dist/cli/handlers/promote.js +2 -1
  64. package/dist/cli/handlers/release.d.ts.map +1 -1
  65. package/dist/cli/handlers/release.js +11 -2
  66. package/dist/cli/handlers/run-wave.d.ts.map +1 -1
  67. package/dist/cli/handlers/run-wave.js +180 -4
  68. package/dist/cli/handlers/run.d.ts.map +1 -1
  69. package/dist/cli/handlers/run.js +2 -1
  70. package/dist/cli/main.d.ts.map +1 -1
  71. package/dist/cli/main.js +41 -2
  72. package/dist/cli/parse-args.d.ts.map +1 -1
  73. package/dist/cli/parse-args.js +31 -0
  74. package/dist/cli/registry.d.ts +19 -1
  75. package/dist/cli/registry.d.ts.map +1 -1
  76. package/dist/components/auto-release.d.ts.map +1 -1
  77. package/dist/components/auto-release.js +2 -1
  78. package/dist/components/pr-checks.d.ts +97 -6
  79. package/dist/components/pr-checks.d.ts.map +1 -1
  80. package/dist/components/pr-checks.js +107 -13
  81. package/dist/components/pr-pipeline.d.ts +19 -14
  82. package/dist/components/pr-pipeline.d.ts.map +1 -1
  83. package/dist/components/pr-pipeline.js +7 -13
  84. package/dist/components/product-pipeline.d.ts +96 -3
  85. package/dist/components/product-pipeline.d.ts.map +1 -1
  86. package/dist/components/product-pipeline.js +120 -14
  87. package/dist/components/product-plan.d.ts +203 -6
  88. package/dist/components/product-plan.d.ts.map +1 -1
  89. package/dist/components/product-plan.js +250 -43
  90. package/dist/drift-record.d.ts +7 -0
  91. package/dist/drift-record.d.ts.map +1 -1
  92. package/dist/drift-record.js +19 -0
  93. package/dist/floor-table.data.d.ts.map +1 -1
  94. package/dist/floor-table.data.js +63 -31
  95. package/dist/forge-check/contract.d.ts +11 -1
  96. package/dist/forge-check/contract.d.ts.map +1 -1
  97. package/dist/forge-check/contract.js +4 -1
  98. package/dist/forge-check/index.d.ts +2 -0
  99. package/dist/forge-check/index.d.ts.map +1 -1
  100. package/dist/forge-check/index.js +2 -0
  101. package/dist/gate-resume-run.d.ts +9 -1
  102. package/dist/gate-resume-run.d.ts.map +1 -1
  103. package/dist/gate-resume-run.js +26 -3
  104. package/dist/generated-check.d.ts +18 -4
  105. package/dist/generated-check.d.ts.map +1 -1
  106. package/dist/generated-check.js +37 -5
  107. package/dist/image-pins.d.ts +26 -0
  108. package/dist/image-pins.d.ts.map +1 -0
  109. package/dist/image-pins.js +19 -0
  110. package/dist/lexicon.d.ts +93 -4
  111. package/dist/lexicon.d.ts.map +1 -1
  112. package/dist/lifecycle/gate-applied.d.ts +9 -0
  113. package/dist/lifecycle/gate-applied.d.ts.map +1 -1
  114. package/dist/lifecycle/git.d.ts +11 -0
  115. package/dist/lifecycle/git.d.ts.map +1 -1
  116. package/dist/lifecycle/git.js +30 -3
  117. package/dist/lifecycle/publish-npm.d.ts +11 -0
  118. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  119. package/dist/lifecycle/publish-npm.js +27 -1
  120. package/dist/lifecycle/reach-locks.d.ts +131 -0
  121. package/dist/lifecycle/reach-locks.d.ts.map +1 -0
  122. package/dist/lifecycle/reach-locks.js +118 -0
  123. package/dist/lifecycle/release-cut.d.ts +3 -1
  124. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  125. package/dist/lifecycle/release-cut.js +15 -0
  126. package/dist/lifecycle/release-images.d.ts.map +1 -1
  127. package/dist/lifecycle/release-images.js +1 -2
  128. package/dist/notify-product.d.ts +12 -3
  129. package/dist/notify-product.d.ts.map +1 -1
  130. package/dist/notify-product.js +10 -6
  131. package/dist/op/activities/source-release.d.ts.map +1 -1
  132. package/dist/op/activities/source-release.js +2 -1
  133. package/dist/op/activities/source-rollback.d.ts.map +1 -1
  134. package/dist/op/activities/source-rollback.js +2 -1
  135. package/dist/op/apply-status.d.ts +84 -0
  136. package/dist/op/apply-status.d.ts.map +1 -0
  137. package/dist/op/apply-status.js +106 -0
  138. package/dist/op/before-merge-decide.d.ts +102 -0
  139. package/dist/op/before-merge-decide.d.ts.map +1 -0
  140. package/dist/op/before-merge-decide.js +142 -0
  141. package/dist/op/before-merge-done.d.ts +56 -0
  142. package/dist/op/before-merge-done.d.ts.map +1 -0
  143. package/dist/op/before-merge-done.js +69 -0
  144. package/dist/op/before-merge-store.d.ts +20 -0
  145. package/dist/op/before-merge-store.d.ts.map +1 -0
  146. package/dist/op/before-merge-store.js +48 -0
  147. package/dist/op/before-merge.d.ts +150 -0
  148. package/dist/op/before-merge.d.ts.map +1 -0
  149. package/dist/op/before-merge.js +207 -0
  150. package/dist/op/follow-on-run.d.ts +117 -0
  151. package/dist/op/follow-on-run.d.ts.map +1 -0
  152. package/dist/op/follow-on-run.js +154 -0
  153. package/dist/op/follow-on-store.d.ts +17 -0
  154. package/dist/op/follow-on-store.d.ts.map +1 -0
  155. package/dist/op/follow-on-store.js +54 -0
  156. package/dist/op/gate.d.ts +6 -0
  157. package/dist/op/gate.d.ts.map +1 -1
  158. package/dist/op/gate.js +10 -1
  159. package/dist/op/index.d.ts +5 -1
  160. package/dist/op/index.d.ts.map +1 -1
  161. package/dist/op/index.js +2 -0
  162. package/dist/op/op-waves-after-plan.d.ts +13 -0
  163. package/dist/op/op-waves-after-plan.d.ts.map +1 -1
  164. package/dist/op/op-waves-evidence-jobs.d.ts +10 -2
  165. package/dist/op/op-waves-evidence-jobs.d.ts.map +1 -1
  166. package/dist/op/op-waves-evidence-jobs.js +19 -5
  167. package/dist/op/op-waves-follow-on.d.ts +162 -0
  168. package/dist/op/op-waves-follow-on.d.ts.map +1 -0
  169. package/dist/op/op-waves-follow-on.js +355 -0
  170. package/dist/op/op-waves-render-spec.d.ts +100 -0
  171. package/dist/op/op-waves-render-spec.d.ts.map +1 -0
  172. package/dist/op/op-waves-render-spec.js +162 -0
  173. package/dist/op/op-waves-run.d.ts +148 -6
  174. package/dist/op/op-waves-run.d.ts.map +1 -1
  175. package/dist/op/op-waves-run.js +873 -100
  176. package/dist/op/op-waves-split.d.ts +122 -0
  177. package/dist/op/op-waves-split.d.ts.map +1 -0
  178. package/dist/op/op-waves-split.js +166 -0
  179. package/dist/op/op-waves.d.ts +24 -0
  180. package/dist/op/op-waves.d.ts.map +1 -1
  181. package/dist/op/op-waves.js +18 -1
  182. package/dist/op/schedule-overdue.d.ts +15 -1
  183. package/dist/op/schedule-overdue.d.ts.map +1 -1
  184. package/dist/op/schedule-overdue.js +77 -5
  185. package/dist/op/stage-hooks.d.ts +36 -1
  186. package/dist/op/stage-hooks.d.ts.map +1 -1
  187. package/dist/op/stage-hooks.js +17 -3
  188. package/dist/op/wave-stop.d.ts +67 -0
  189. package/dist/op/wave-stop.d.ts.map +1 -0
  190. package/dist/op/wave-stop.js +129 -0
  191. package/dist/planned-files.d.ts +76 -0
  192. package/dist/planned-files.d.ts.map +1 -0
  193. package/dist/planned-files.js +108 -0
  194. package/dist/pr-forge-job.d.ts +22 -0
  195. package/dist/pr-forge-job.d.ts.map +1 -0
  196. package/dist/pr-forge-job.js +46 -0
  197. package/dist/pr-loop.d.ts +3 -6
  198. package/dist/pr-loop.d.ts.map +1 -1
  199. package/dist/pr-loop.js +4 -81
  200. package/dist/pr-plan-note.d.ts +97 -0
  201. package/dist/pr-plan-note.d.ts.map +1 -1
  202. package/dist/pr-plan-note.js +94 -1
  203. package/dist/pr-post.d.ts +28 -3
  204. package/dist/pr-post.d.ts.map +1 -1
  205. package/dist/pr-post.js +146 -13
  206. package/dist/pr-status.d.ts +16 -0
  207. package/dist/pr-status.d.ts.map +1 -0
  208. package/dist/pr-status.js +90 -0
  209. package/dist/ref-gate-init.d.ts +16 -2
  210. package/dist/ref-gate-init.d.ts.map +1 -1
  211. package/dist/ref-gate-init.js +24 -13
  212. package/dist/release-floors.d.ts +39 -1
  213. package/dist/release-floors.d.ts.map +1 -1
  214. package/dist/release-floors.js +63 -25
  215. package/dist/render-module.d.ts +15 -0
  216. package/dist/render-module.d.ts.map +1 -0
  217. package/dist/render-module.js +73 -0
  218. package/dist/state-migration.d.ts.map +1 -1
  219. package/dist/state-migration.js +1 -2
  220. package/dist/wave-blocked.d.ts +7 -1
  221. package/dist/wave-blocked.d.ts.map +1 -1
  222. package/dist/wave-blocked.js +7 -2
  223. package/dist/wave-runtime.mjs +366 -350
  224. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  225. package/dist/workspace/ci-green-cli.js +3 -2
  226. package/dist/workspace/release-train.d.ts.map +1 -1
  227. package/dist/workspace/release-train.js +2 -1
  228. package/dist/workspace/release-workflow.d.ts +4 -3
  229. package/dist/workspace/release-workflow.d.ts.map +1 -1
  230. package/dist/workspace/release-workflow.js +10 -7
  231. package/dist/workspace/trust/check-evidence-report.d.ts +7 -2
  232. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -1
  233. package/dist/workspace/trust/check-evidence-report.js +15 -8
  234. package/dist/workspace/trust/ref-gate-cli.d.ts +10 -1
  235. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -1
  236. package/dist/workspace/trust/ref-gate-cli.js +30 -10
  237. package/dist/workspace/workspace-run.d.ts.map +1 -1
  238. package/dist/workspace/workspace-run.js +2 -1
  239. package/package.json +1 -1
  240. package/src/actor.test.ts +68 -2
  241. package/src/actor.ts +61 -1
  242. package/src/chant-install.test.ts +2 -3
  243. package/src/chant-install.ts +1 -2
  244. package/src/ci-base.test.ts +41 -0
  245. package/src/ci-base.ts +43 -0
  246. package/src/ci-comment-commands.test.ts +439 -0
  247. package/src/ci-comment-commands.ts +428 -0
  248. package/src/ci-comment-replies.ts +78 -0
  249. package/src/ci-commit.test.ts +2 -3
  250. package/src/ci-evidence-from-job.test.ts +18 -0
  251. package/src/ci-evidence-from-job.ts +58 -2
  252. package/src/ci-evidence-jobs.ts +50 -5
  253. package/src/ci-image.test.ts +130 -10
  254. package/src/ci-image.ts +85 -12
  255. package/src/ci-job-guard.before-merge.test.ts +148 -0
  256. package/src/ci-job-guard.follow-on-record.test.ts +137 -0
  257. package/src/ci-job-guard.follow-on.test.ts +144 -0
  258. package/src/ci-job-guard.ts +221 -3
  259. package/src/ci-note-commands.test.ts +76 -1
  260. package/src/ci-note-commands.ts +198 -46
  261. package/src/ci-product-words.ts +59 -0
  262. package/src/ci-product.ts +90 -6
  263. package/src/cli/commands/build.test.ts +41 -0
  264. package/src/cli/commands/build.ts +27 -2
  265. package/src/cli/handlers/approve.ts +2 -1
  266. package/src/cli/handlers/ci-check.ts +19 -7
  267. package/src/cli/handlers/ci-evidence.ts +29 -8
  268. package/src/cli/handlers/components.ts +3 -1
  269. package/src/cli/handlers/generated-check.ts +31 -1
  270. package/src/cli/handlers/lock-reach.test.ts +103 -0
  271. package/src/cli/handlers/lock.ts +100 -4
  272. package/src/cli/handlers/pr-comment.ts +187 -0
  273. package/src/cli/handlers/pr-env.ts +6 -3
  274. package/src/cli/handlers/pr-notes.ts +30 -6
  275. package/src/cli/handlers/pr-record.test.ts +1 -1
  276. package/src/cli/handlers/pr.ts +64 -21
  277. package/src/cli/handlers/promote.ts +2 -1
  278. package/src/cli/handlers/release.e2e.test.ts +35 -0
  279. package/src/cli/handlers/release.ts +14 -2
  280. package/src/cli/handlers/run-wave.ts +170 -4
  281. package/src/cli/handlers/run.ts +2 -1
  282. package/src/cli/main.ts +41 -2
  283. package/src/cli/parse-args.ts +23 -0
  284. package/src/cli/registry.ts +19 -1
  285. package/src/components/auto-release.ts +2 -1
  286. package/src/components/pr-checks.ts +165 -17
  287. package/src/components/pr-pipeline.ts +22 -18
  288. package/src/components/product-pipeline.apply-status.test.ts +50 -0
  289. package/src/components/product-pipeline.ts +204 -17
  290. package/src/components/product-plan.test.ts +60 -4
  291. package/src/components/product-plan.ts +367 -50
  292. package/src/drift-record.test.ts +20 -0
  293. package/src/drift-record.ts +16 -0
  294. package/src/floor-table.data.ts +63 -31
  295. package/src/forge-check/contract.ts +12 -1
  296. package/src/forge-check/forge-check.test.ts +17 -0
  297. package/src/forge-check/index.ts +2 -0
  298. package/src/gate-resume-run.ts +27 -3
  299. package/src/generated-check.e2e.test.ts +21 -1
  300. package/src/generated-check.test.ts +66 -0
  301. package/src/generated-check.ts +51 -10
  302. package/src/image-pins.ts +31 -0
  303. package/src/lexicon.ts +89 -1
  304. package/src/lifecycle/gate-applied.ts +7 -0
  305. package/src/lifecycle/git.test.ts +48 -0
  306. package/src/lifecycle/git.ts +27 -4
  307. package/src/lifecycle/publish-npm.ts +31 -1
  308. package/src/lifecycle/reach-locks.test.ts +87 -0
  309. package/src/lifecycle/reach-locks.ts +169 -0
  310. package/src/lifecycle/release-cut.ts +17 -1
  311. package/src/lifecycle/release-images.test.ts +56 -0
  312. package/src/lifecycle/release-images.ts +1 -2
  313. package/src/notify-product.ts +19 -8
  314. package/src/op/activities/source-release.ts +2 -1
  315. package/src/op/activities/source-rollback.ts +2 -1
  316. package/src/op/apply-status.test.ts +83 -0
  317. package/src/op/apply-status.ts +132 -0
  318. package/src/op/before-merge-decide.ts +190 -0
  319. package/src/op/before-merge-done.ts +99 -0
  320. package/src/op/before-merge-store.ts +44 -0
  321. package/src/op/before-merge.test.ts +201 -0
  322. package/src/op/before-merge.ts +266 -0
  323. package/src/op/follow-on-run.ts +206 -0
  324. package/src/op/follow-on-store.ts +54 -0
  325. package/src/op/gate-resume.test.ts +27 -0
  326. package/src/op/gate.ts +16 -1
  327. package/src/op/index.ts +15 -0
  328. package/src/op/op-waves-after-plan.ts +13 -0
  329. package/src/op/op-waves-evidence-jobs.ts +21 -7
  330. package/src/op/op-waves-follow-on-record.test.ts +152 -0
  331. package/src/op/op-waves-follow-on.test.ts +247 -0
  332. package/src/op/op-waves-follow-on.ts +385 -0
  333. package/src/op/op-waves-notify-words.test.ts +18 -0
  334. package/src/op/op-waves-render-spec.test.ts +159 -0
  335. package/src/op/op-waves-render-spec.ts +171 -0
  336. package/src/op/op-waves-run.ts +973 -94
  337. package/src/op/op-waves-split-product.test.ts +288 -0
  338. package/src/op/op-waves-split-step.test.ts +298 -0
  339. package/src/op/op-waves-split.test.ts +196 -0
  340. package/src/op/op-waves-split.ts +189 -0
  341. package/src/op/op-waves.ts +31 -3
  342. package/src/op/schedule-overdue.test.ts +72 -1
  343. package/src/op/schedule-overdue.ts +84 -6
  344. package/src/op/stage-hooks.ts +52 -4
  345. package/src/op/wave-stop.test.ts +72 -0
  346. package/src/op/wave-stop.ts +139 -0
  347. package/src/planned-files.test.ts +80 -0
  348. package/src/planned-files.ts +134 -0
  349. package/src/pr-forge-job.test.ts +53 -0
  350. package/src/pr-forge-job.ts +46 -0
  351. package/src/pr-loop-narrowed.test.ts +2 -1
  352. package/src/pr-loop-words.test.ts +2 -1
  353. package/src/pr-loop.test.ts +1 -2
  354. package/src/pr-loop.ts +4 -80
  355. package/src/pr-plan-note.ts +155 -3
  356. package/src/pr-post-replan.test.ts +144 -0
  357. package/src/pr-post-subject.test.ts +230 -0
  358. package/src/pr-post.test.ts +2 -1
  359. package/src/pr-post.ts +151 -15
  360. package/src/pr-status.ts +91 -0
  361. package/src/ref-gate-init.ts +30 -11
  362. package/src/release-floors.ts +81 -25
  363. package/src/render-module.ts +73 -0
  364. package/src/state-migration-record.test.ts +2 -3
  365. package/src/state-migration.ts +1 -2
  366. package/src/wave-blocked.ts +9 -4
  367. package/src/workspace/ci-green-cli.ts +3 -2
  368. package/src/workspace/ci-green-workflow.test.ts +32 -1
  369. package/src/workspace/release-train.ts +2 -1
  370. package/src/workspace/release-workflow.test.ts +36 -5
  371. package/src/workspace/release-workflow.ts +10 -7
  372. package/src/workspace/trust/check-evidence-report.ts +15 -8
  373. package/src/workspace/trust/check-evidence.test.ts +5 -0
  374. package/src/workspace/trust/ref-gate-cli.ts +30 -8
  375. package/src/workspace/trust/ref-gate-pieces.test.ts +46 -1
  376. package/src/workspace/trust/ref-gate.test.ts +10 -0
  377. package/src/workspace/workspace-run.ts +2 -1
@@ -0,0 +1,196 @@
1
+ /**
2
+ * #4987: a split wave's four jobs. The plan job plans and saves the plan
3
+ * and writes nothing to the ledger; the gate job decides the gate on the
4
+ * saved plan, refusing one whose plan files give another digest; the apply
5
+ * job applies the saved plans the decision holds and leaves its run record
6
+ * in a file; the record job writes it to the run ledger.
7
+ */
8
+ import { describe, expect, test } from "vitest";
9
+ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { tmpdir } from "node:os";
12
+ import { opWaveJobs, opWaveOutcomeDir, opWaveRecordPath, type OpWavesSpec } from "./op-waves";
13
+ import { opWavePlanPath, runOpWave, type OpWaveExec, type OpWaveRunPort, type OpWaveSavedPlan, type OpWaveShowAtBase } from "./op-waves-run";
14
+ import { assertOpWavesSplit, opWaveRunRecordFileName, opWaveSavedPlanPath, opWaveSplitJobs, opWaveSplitLastJobs } from "./op-waves-split";
15
+ import { memoryGateLedgerPort } from "./gate";
16
+ import { waveSetDigest } from "../gated-waves";
17
+ import { CHANT_EXIT } from "../exit-codes";
18
+ import type { OpRunRecordInput } from "./runtime";
19
+
20
+ const spec: OpWavesSpec = {
21
+ name: "migrations",
22
+ op: "migrate",
23
+ plan: ["tool", "plan", "{target}", "--out", "{plan}"],
24
+ apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
25
+ waves: [
26
+ { name: "staging", runs: [{ target: "staging" }], gate: "on-destructive" },
27
+ { name: "prod", runs: [{ target: "t1" }, { target: "t2" }, { target: "t3" }], shares: 2, gate: "never" },
28
+ ],
29
+ };
30
+ const digest = (n: string) => `sha256:${n.repeat(64)}`;
31
+
32
+ function harness(plans: Record<string, { planDigest: string; destructive?: boolean }>) {
33
+ const cwd = mkdtempSync(join(tmpdir(), "op-waves-split-"));
34
+ const calls: string[] = [];
35
+ const planExit: { code: number } = { code: 0 };
36
+ const exec: OpWaveExec = (argv, dir) => {
37
+ calls.push(argv.join(" "));
38
+ if (argv[1] === "plan") {
39
+ if (planExit.code !== 0) return planExit.code;
40
+ writeFileSync(join(dir, argv[4]!), JSON.stringify(plans[argv[2]!]));
41
+ }
42
+ return 0;
43
+ };
44
+ const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
45
+ const records: OpRunRecordInput[] = [];
46
+ const runs: OpWaveRunPort = { append: async (r) => void records.push(r) };
47
+ const noRuns: OpWaveRunPort = {
48
+ append: async () => {
49
+ throw new Error("this job writes no run record to the ledger");
50
+ },
51
+ };
52
+ const base = { spec, specFile: "waves.json", cwd, exec, show, log: () => {} };
53
+ return { cwd, calls, exec, show, records, runs, noRuns, planExit, base, done: () => rmSync(cwd, { recursive: true, force: true }) };
54
+ }
55
+
56
+ describe("the split jobs of a before-merge pipeline (#4987)", () => {
57
+ test("each wave is a plan, a gate, its applying jobs and a record job", () => {
58
+ const split = opWaveSplitJobs(spec, opWaveJobs(spec, "waves.json", { beforeMerge: true }));
59
+ expect(split.map((j) => [j.jobName, j.phase, j.runsChange, j.needs])).toEqual([
60
+ ["wave-1-staging-plan", "plan", true, []],
61
+ ["wave-1-staging-gate", "gate", false, ["wave-1-staging-plan"]],
62
+ ["wave-1-staging", "apply", true, ["wave-1-staging-gate"]],
63
+ ["wave-1-staging-record", "record", false, ["wave-1-staging", "wave-1-staging-gate"]],
64
+ ["wave-2-prod-plan", "plan", true, ["wave-1-staging-record"]],
65
+ ["wave-2-prod-gate", "gate", false, ["wave-2-prod-plan"]],
66
+ ["wave-2-prod-share-1", "apply", true, ["wave-2-prod-gate"]],
67
+ ["wave-2-prod-share-2", "apply", true, ["wave-2-prod-gate"]],
68
+ ["wave-2-prod-record", "record", false, ["wave-2-prod-share-1", "wave-2-prod-share-2", "wave-2-prod-gate"]],
69
+ ]);
70
+ // The deciding job's --decide gives way to the phase; a share keeps its slice.
71
+ expect(split[4]!.command.join(" ")).toBe('chant run wave --spec waves.json --wave 2 --base "${CHANT_WAVES_BASE:-HEAD^1}" --phase plan');
72
+ expect(split[7]!.command.join(" ")).toBe('chant run wave --spec waves.json --wave 2 --base "${CHANT_WAVES_BASE:-HEAD^1}" --share 2 --phase apply');
73
+ // The wave's own applying job writes an outcome file of its own, never the gate job's.
74
+ expect(split[2]!.outcome).toBe(".chant/op-waves/migrations/outcomes/outcome-wave-1-apply.json");
75
+ expect(split[1]!.outcome).toBe(".chant/op-waves/migrations/outcomes/outcome-wave-1.json");
76
+ expect(opWaveSplitLastJobs(spec)).toEqual(["wave-2-prod-record"]);
77
+ });
78
+
79
+ test("a step spec and a rest wave split (#4992)", () => {
80
+ expect(() => assertOpWavesSplit({ ...spec, step: { kind: "terraform-apply", root: "{target}" } } as OpWavesSpec)).not.toThrow();
81
+ expect(() => assertOpWavesSplit({ ...spec, waves: [{ ...spec.waves[1]!, rest: true }] })).not.toThrow();
82
+ });
83
+ });
84
+
85
+ describe("a split wave's phases (#4987)", () => {
86
+ const set = waveSetDigest([{ member: "staging", planDigest: digest("a") }]);
87
+ const approval = { version: 1 as const, op: "migrations", gate: "migrations-wave-1", resolvedBy: "alice", timestamp: "2026-11-10T00:00:00Z", planDigest: set };
88
+
89
+ test("plan, gate, apply and record: only the gate and record jobs write the ledger", async () => {
90
+ const h = harness({ staging: { planDigest: digest("a"), destructive: true } });
91
+ const gates = memoryGateLedgerPort({ resolutions: [approval] });
92
+
93
+ const planned = await runOpWave({ ...h.base, wave: 1, phase: "plan", gates, runs: h.noRuns });
94
+ expect(planned.exitCode).toBe(CHANT_EXIT.done);
95
+ expect(gates.appended).toEqual([]);
96
+ const saved = JSON.parse(readFileSync(join(h.cwd, opWaveSavedPlanPath(spec, 1)), "utf-8")) as OpWaveSavedPlan;
97
+ expect(saved).toMatchObject({ version: 1, op: "migrations", wave: 1, name: "staging", digest: set, members: [{ member: "staging", planDigest: digest("a"), destructive: true }] });
98
+ // The plan job decides nothing, so it writes no decision and no outcome.
99
+ expect(existsSync(join(h.cwd, opWaveRecordPath(spec, 1)))).toBe(false);
100
+ expect(existsSync(join(h.cwd, opWaveOutcomeDir(spec)))).toBe(false);
101
+ expect(h.calls).toEqual(["tool plan staging --out .chant/op-waves/migrations/wave-1/staging.plan.json"]);
102
+
103
+ const gated = await runOpWave({ ...h.base, wave: 1, phase: "gate", gates });
104
+ expect(gated).toMatchObject({ exitCode: 0, applied: [], decision: { status: "approved", approvedBy: "alice", digest: set } });
105
+ // The gate plans nothing again.
106
+ expect(h.calls).toHaveLength(1);
107
+ expect(JSON.parse(readFileSync(join(h.cwd, opWaveOutcomeDir(spec), "outcome-wave-1.json"), "utf-8")).members).toEqual({ staging: { status: "decided" } });
108
+
109
+ const before = gates.appended.length;
110
+ const applied = await runOpWave({ ...h.base, wave: 1, phase: "apply", gates, runs: h.noRuns });
111
+ expect(applied).toMatchObject({ exitCode: 0, applied: ["staging"] });
112
+ expect(gates.appended.length).toBe(before);
113
+ expect(h.calls.at(-1)).toBe("tool apply staging --plan .chant/op-waves/migrations/wave-1/staging.plan.json");
114
+ const recordFile = join(h.cwd, opWaveOutcomeDir(spec), opWaveRunRecordFileName(1));
115
+ expect(JSON.parse(readFileSync(recordFile, "utf-8"))).toMatchObject({ op: "migrations", wave: { number: 1, applied: ["staging"], exitCode: 0 } });
116
+ expect(JSON.parse(readFileSync(join(h.cwd, opWaveOutcomeDir(spec), "outcome-wave-1-apply.json"), "utf-8")).members).toEqual({ staging: { status: "applied" } });
117
+
118
+ const recorded = await runOpWave({ ...h.base, wave: 1, phase: "record", runs: h.runs });
119
+ expect(recorded).toMatchObject({ exitCode: 0, applied: ["staging"] });
120
+ expect(h.records).toHaveLength(1);
121
+ expect(h.records[0]!.wave).toMatchObject({ number: 1, applied: ["staging"] });
122
+ h.done();
123
+ });
124
+
125
+ test("without an approval the gate job records the pending fact and waits; the apply job applies nothing", async () => {
126
+ const h = harness({ staging: { planDigest: digest("a"), destructive: true } });
127
+ const gates = memoryGateLedgerPort();
128
+ await runOpWave({ ...h.base, wave: 1, phase: "plan", gates, runs: h.noRuns });
129
+ const gated = await runOpWave({ ...h.base, wave: 1, phase: "gate", gates });
130
+ expect(gated.exitCode).toBe(CHANT_EXIT.waiting);
131
+ expect(gates.appended.map((p) => p.planDigest)).toEqual([set]);
132
+ const applied = await runOpWave({ ...h.base, wave: 1, phase: "apply", gates, runs: h.noRuns });
133
+ expect(applied.exitCode).toBe(CHANT_EXIT.waiting);
134
+ expect(h.calls.filter((c) => c.startsWith("tool apply"))).toEqual([]);
135
+ h.done();
136
+ });
137
+
138
+ test("the gate job refuses a saved plan its plan files do not give, and the apply job a plan file that moved after the gate", async () => {
139
+ const h = harness({ staging: { planDigest: digest("a") } });
140
+ const gates = memoryGateLedgerPort();
141
+ await runOpWave({ ...h.base, wave: 1, phase: "plan", gates, runs: h.noRuns });
142
+ const planFile = join(h.cwd, opWavePlanPath(spec, 1, "staging"));
143
+ writeFileSync(planFile, JSON.stringify({ planDigest: digest("e") }));
144
+ const refused = await runOpWave({ ...h.base, wave: 1, phase: "gate", gates });
145
+ expect(refused).toMatchObject({ exitCode: CHANT_EXIT.moved, moved: ["staging"] });
146
+ expect(gates.appended).toEqual([]);
147
+ expect(existsSync(join(h.cwd, opWaveRecordPath(spec, 1)))).toBe(false);
148
+
149
+ writeFileSync(planFile, JSON.stringify({ planDigest: digest("a") }));
150
+ expect((await runOpWave({ ...h.base, wave: 1, phase: "gate", gates })).exitCode).toBe(0);
151
+ writeFileSync(planFile, JSON.stringify({ planDigest: digest("f") }));
152
+ const moved = await runOpWave({ ...h.base, wave: 1, phase: "apply", gates, runs: h.noRuns });
153
+ expect(moved).toMatchObject({ exitCode: CHANT_EXIT.moved, applied: [], moved: ["staging"] });
154
+ expect(h.calls.filter((c) => c.startsWith("tool apply"))).toEqual([]);
155
+ h.done();
156
+ });
157
+
158
+ test("a plan that fails ends the wave in the plan job; the gate job records that end and decides nothing", async () => {
159
+ const h = harness({ staging: { planDigest: digest("a") } });
160
+ h.planExit.code = 1;
161
+ const gates = memoryGateLedgerPort();
162
+ await expect(runOpWave({ ...h.base, wave: 1, phase: "plan", gates, runs: h.noRuns })).rejects.toThrow("planning staging exited 1");
163
+ const saved = JSON.parse(readFileSync(join(h.cwd, opWaveSavedPlanPath(spec, 1)), "utf-8")) as OpWaveSavedPlan;
164
+ expect(saved.end).toMatchObject({ exitCode: 1 });
165
+ const gated = await runOpWave({ ...h.base, wave: 1, phase: "gate", gates, runs: h.runs });
166
+ expect(gated.exitCode).toBe(1);
167
+ expect(gates.appended).toEqual([]);
168
+ // Its run record says how the wave ended, from the gate job, which holds the token.
169
+ expect(h.records.map((r) => r.status)).toEqual(["fail"]);
170
+ h.done();
171
+ });
172
+
173
+ test("a wide wave's shares apply their slices of the saved plan, and the record job ends as they did", async () => {
174
+ const h = harness({ t1: { planDigest: digest("1") }, t2: { planDigest: digest("2") }, t3: { planDigest: digest("3") } });
175
+ const gates = memoryGateLedgerPort();
176
+ await runOpWave({ ...h.base, wave: 2, phase: "plan", gates, runs: h.noRuns });
177
+ expect((await runOpWave({ ...h.base, wave: 2, phase: "gate", gates })).decision).toMatchObject({ status: "not-required" });
178
+ writeFileSync(join(h.cwd, opWavePlanPath(spec, 2, "t3")), JSON.stringify({ planDigest: digest("9") }));
179
+ expect(await runOpWave({ ...h.base, wave: 2, phase: "apply", share: 1, gates, runs: h.noRuns })).toMatchObject({ exitCode: 0, applied: ["t1", "t2"] });
180
+ expect(await runOpWave({ ...h.base, wave: 2, phase: "apply", share: 2, gates, runs: h.noRuns })).toMatchObject({ exitCode: CHANT_EXIT.moved, moved: ["t3"] });
181
+ const recorded = await runOpWave({ ...h.base, wave: 2, phase: "record", runs: h.runs });
182
+ expect(recorded).toMatchObject({ exitCode: CHANT_EXIT.moved, applied: ["t1", "t2"], moved: ["t3"] });
183
+ expect(h.records.map((r) => r.wave?.share)).toEqual([1, 2]);
184
+ // No applying job left a record for wave 1: the record job says so and fails.
185
+ expect((await runOpWave({ ...h.base, wave: 1, phase: "record", runs: h.runs })).exitCode).toBe(CHANT_EXIT.failed);
186
+ h.done();
187
+ });
188
+
189
+ test("a phase that cannot run is refused", async () => {
190
+ const h = harness({});
191
+ await expect(runOpWave({ ...h.base, wave: 2, phase: "plan", share: 1 })).rejects.toThrow("--share names an applying job; the plan job covers the whole wave");
192
+ await expect(runOpWave({ ...h.base, wave: 1, phase: "gate" })).rejects.toThrow("found no saved plan");
193
+ await expect(runOpWave({ ...h.base, wave: 1, phase: "sideways" as never })).rejects.toThrow("the phase is one of plan, gate, apply, record");
194
+ h.done();
195
+ });
196
+ });
@@ -0,0 +1,189 @@
1
+ /**
2
+ * Op waves before merge, split so the change's code never runs beside a
3
+ * write token (#4987).
4
+ *
5
+ * Maintainer decision (2026-11-10): in a pipeline with `beforeMerge` each
6
+ * wave is four jobs.
7
+ *
8
+ * 1. `<wave>-plan` runs the change's code and holds no write token: the
9
+ * checkout keeps no credentials, the job's token can only read (GitHub),
10
+ * and on GitLab its script drops `CHANT_FORGE_TOKEN` and the job token.
11
+ * `chant run wave --phase plan` plans the wave and saves the plan
12
+ * ({@link opWaveSavedPlanPath}, beside the plan files) as an artifact.
13
+ * 2. `<wave>-gate` runs the default branch's code alone, with the token:
14
+ * `--phase gate` reads the rules at base, takes the saved plan, refuses
15
+ * it when its digest is not the one its plan files give, writes the
16
+ * gate's pending fact or spends the approval on `chant/lifecycle`, and
17
+ * keeps the decision record, as a wide wave's deciding job does.
18
+ * 3. `<wave>` (or each share and job group's job) applies the saved plan,
19
+ * with no write token: `--phase apply` checks each plan file's digest
20
+ * against the decision and applies the ones that match. Its run record
21
+ * goes to a file ({@link opWaveRunRecordFileName}) in place of the ledger.
22
+ * 4. `<wave>-record` runs the default branch's code with the token:
23
+ * `--phase record` writes those run records to the run ledger and exits
24
+ * as the wave's applying jobs did.
25
+ *
26
+ * A push run of the same pipeline takes the same four jobs. A pipeline
27
+ * without `beforeMerge` keeps one job per wave (or a deciding job and its
28
+ * shares), since a push runs merged code.
29
+ *
30
+ * A `step` spec (#4992) plans in the plan job's process; the saved plan
31
+ * keeps each run's step plan (its digest, effects and lock rows) without the
32
+ * engine's artifact. The gate job leases the rows the runs wait for and
33
+ * change, with no heartbeat, before it spends the approval, and the
34
+ * decision names the lease. The applying job plans its runs again through
35
+ * the step, as a share job does, and applies each whose plan digest the
36
+ * decision holds; it hands the release records to the record job, which
37
+ * writes them and lets go of the lease. A run whose plan moved is exit 4.
38
+ *
39
+ * A hook that holds the wave on another gate (#4992) in the plan or apply
40
+ * job reads that gate with no write token: approved, the wave goes on; still
41
+ * waiting, the job leaves the gate's pending fact to the gate job (a plan
42
+ * job's hold) or the record job (an apply job's), which records it, and the
43
+ * wave waits. A hold that asks chant to `record` the gate is spent before
44
+ * its hook runs again, so it fails in an applying job once approved.
45
+ *
46
+ * #4994: in the plan job, such a hold once approved waits, and the gate job
47
+ * spends the approval under its own rules at base, for a re-run of the hook
48
+ * at the wave's commit (an applied line with `rerun.head`). The plan job of
49
+ * the next run of that commit finds the line, with no finished line yet, and
50
+ * runs the hook again under it with `CHANT_HOLD_APPROVED`; the wave then
51
+ * plans on what the hook did. Its gate job writes the finished line from the
52
+ * hook's `CHANT_HOLD_FINISHED`, which the saved plan hands on
53
+ * (`holdsFinished`). Any other commit's job, and any job once the line is
54
+ * finished, reads the approval as spent.
55
+ *
56
+ * A product's hooks run in whichever job runs them (#4994): a hook its
57
+ * process serves by name (`inProcessHooks`) is called there in place of its
58
+ * command, and what the plan job's code keeps for the later jobs goes under
59
+ * {@link opWaveProductStateDir}.
60
+ *
61
+ * A `rest` wave (#4992) runs one wave per run: its four jobs run wave N,
62
+ * the last rendered one, or in a follow-on run the wave the run names
63
+ * (`--wave "${CHANT_WAVES_WAVE:-N}"`), and its record job starts the
64
+ * follow-on for the next wave the plan found (./op-waves-follow-on.ts).
65
+ * Its jobs carry `rest: true`.
66
+ */
67
+
68
+ import { OP_WAVES_WAVE_ENV } from "./follow-on-run";
69
+ import { opWaveOutcomePath, opWaveRecordPath, type OpWaveJob, type OpWavesSpec } from "./op-waves";
70
+
71
+ /** The four jobs of a split wave (#4987). */
72
+ export type OpWavePhase = "plan" | "gate" | "apply" | "record";
73
+
74
+ export const OP_WAVE_PHASES: readonly OpWavePhase[] = ["plan", "gate", "apply", "record"];
75
+
76
+ /** One job of a split wave. `kind` is `decide` for the plan and gate jobs, `share` for an applying job and `wave` for the record job. */
77
+ export interface OpWaveSplitJob extends OpWaveJob {
78
+ phase: OpWavePhase;
79
+ /** The job checks out and runs the change's code: the plan and apply jobs. It holds no write token. */
80
+ runsChange: boolean;
81
+ /** A job of the `rest` wave (#4992): it runs the wave `CHANT_WAVES_WAVE` names, its own number by default. */
82
+ rest?: true;
83
+ }
84
+
85
+ /** Where a wave's plan job saves its plan, beside the run plan files the apply reads (#4987). */
86
+ export function opWaveSavedPlanDir(spec: Pick<OpWavesSpec, "name">, wave: number): string {
87
+ return `.chant/op-waves/${spec.name}/wave-${wave}`;
88
+ }
89
+
90
+ /**
91
+ * Where a product keeps what its own code in a split wave's later jobs reads
92
+ * (#4994): its report rows, the plans it read, a hook's state. It is inside
93
+ * the saved plan's directory, so every forge hands it from the plan job to
94
+ * the gate job and the applying jobs with the saved plan. The plan job runs
95
+ * the change's code, so a gate job reads it as a report, never as a rule.
96
+ */
97
+ export function opWaveProductStateDir(spec: Pick<OpWavesSpec, "name">, wave: number): string {
98
+ return `${opWaveSavedPlanDir(spec, wave)}/product`;
99
+ }
100
+
101
+ /** The saved plan file itself. */
102
+ export function opWaveSavedPlanPath(spec: Pick<OpWavesSpec, "name">, wave: number): string {
103
+ return `${opWaveSavedPlanDir(spec, wave)}/saved-plan.json`;
104
+ }
105
+
106
+ /** The file an applying job leaves its run record in, in the outcome directory, for the record job (#4987). */
107
+ export function opWaveRunRecordFileName(wave: number, part: { group?: string; share?: number } = {}): string {
108
+ const group = part.group !== undefined ? `-group-${part.group.replace(/[^A-Za-z0-9._-]/g, "_")}` : "";
109
+ const share = part.share !== undefined ? `-share-${part.share}` : "";
110
+ return `run-record-wave-${wave}${group}${share}.json`;
111
+ }
112
+
113
+ /** A run record file's name, as {@link opWaveRunRecordFileName} gives it; group 1 is the wave. */
114
+ export const OP_WAVE_RUN_RECORD_FILE = /^run-record-wave-(\d+)(?:-group-[A-Za-z0-9._-]+)?(?:-share-\d+)?\.json$/;
115
+
116
+ /**
117
+ * Refuse a spec whose waves cannot run as four jobs each, naming why. A
118
+ * `step` spec splits (#4992), and a `rest` wave runs one wave per run
119
+ * (./op-waves-follow-on.ts), so nothing is refused today.
120
+ */
121
+ export function assertOpWavesSplit(_spec: Pick<OpWavesSpec, "name" | "waves">): void {}
122
+
123
+ /** A wave job's command without `--decide`, which the plan and gate jobs take the place of; a rest wave's names the wave `CHANT_WAVES_WAVE` gives (#4992). */
124
+ function baseCommand(job: OpWaveJob, rest = false): string[] {
125
+ const words = job.command.filter((w) => w !== "--decide");
126
+ if (!rest) return words;
127
+ const at = words.indexOf("--wave");
128
+ return at < 0 ? words : [...words.slice(0, at + 1), `"\${${OP_WAVES_WAVE_ENV}:-${job.wave}}"`, ...words.slice(at + 2)];
129
+ }
130
+
131
+ /** The job after which the waves after wave `k` start: its record job. */
132
+ export function opWaveRecordJobName(spec: Pick<OpWavesSpec, "waves">, k: number): string {
133
+ return `wave-${k}-${spec.waves[k - 1]!.name}-record`;
134
+ }
135
+
136
+ /**
137
+ * The split jobs of a before-merge pipeline (#4987), from `opWaveJobs`, in
138
+ * order: for each wave its plan job, its gate job, its applying jobs (the
139
+ * wave's own job, or each share and job group's job) and its record job.
140
+ * The plan job of each wave after the first needs the record job of the
141
+ * wave before; the gate needs the plan, each applying job the gate, and the
142
+ * record job every applying job and the gate, whose decision names the rows
143
+ * it leased (#4992).
144
+ */
145
+ export function opWaveSplitJobs(spec: OpWavesSpec, jobs: readonly OpWaveJob[]): OpWaveSplitJob[] {
146
+ assertOpWavesSplit(spec);
147
+ const out: OpWaveSplitJob[] = [];
148
+ for (let k = 1; k <= spec.waves.length; k++) {
149
+ const own = jobs.filter((j) => j.wave === k);
150
+ const first = own[0]!;
151
+ const prefix = `wave-${k}-${first.waveName}`;
152
+ const needs = k === 1 ? [] : [opWaveRecordJobName(spec, k - 1)];
153
+ // #4992: the rest wave's jobs run the wave a follow-on run names.
154
+ const rest = spec.waves[k - 1]!.rest === true;
155
+ const marks = rest ? { rest: true as const } : {};
156
+ const base = baseCommand(first, rest);
157
+ const plan = `${prefix}-plan`;
158
+ const gate = `${prefix}-gate`;
159
+ out.push({ jobName: plan, wave: k, waveName: first.waveName, kind: "decide", needs, command: [...base, "--phase", "plan"], outcome: opWaveOutcomePath(spec, k), phase: "plan", runsChange: true, ...marks });
160
+ out.push({ jobName: gate, wave: k, waveName: first.waveName, kind: "decide", needs: [plan], command: [...base, "--phase", "gate"], record: opWaveRecordPath(spec, k), outcome: opWaveOutcomePath(spec, k), phase: "gate", runsChange: false, ...marks });
161
+ const applying = first.kind === "wave" ? [first] : own.filter((j) => j.kind === "share");
162
+ for (const job of applying) {
163
+ // The wave's own applying job writes `-apply`, so it never reads its own outcome as the gate job's.
164
+ const outcome = job.kind === "wave" ? opWaveOutcomePath(spec, k, { apply: true }) : job.outcome;
165
+ out.push({ ...job, kind: "share", needs: [gate], command: [...baseCommand(job, rest), "--phase", "apply"], record: opWaveRecordPath(spec, k), outcome, phase: "apply", runsChange: true, ...marks });
166
+ }
167
+ out.push({ jobName: opWaveRecordJobName(spec, k), wave: k, waveName: first.waveName, kind: "wave", needs: [...applying.map((j) => j.jobName), gate], record: opWaveRecordPath(spec, k), command: [...base, "--phase", "record"], outcome: opWaveOutcomePath(spec, k), phase: "record", runsChange: false, ...marks });
168
+ }
169
+ return out;
170
+ }
171
+
172
+ /** The jobs a job after the waves needs in a split pipeline: the last wave's record job. */
173
+ export function opWaveSplitLastJobs(spec: Pick<OpWavesSpec, "waves">): string[] {
174
+ return [opWaveRecordJobName(spec, spec.waves.length)];
175
+ }
176
+
177
+ /** What a split job calls itself in its guard's lines: `the plan job of wave 2 (prod) of tf-apply`, `share 1 of wave 2 (prod) of tf-apply`. */
178
+ export function opWaveSplitJobLabel(spec: string, job: Pick<OpWaveSplitJob, "phase" | "wave" | "waveName" | "share" | "group">): string {
179
+ const wave = `wave ${job.wave} (${job.waveName}) of ${spec}`;
180
+ if (job.phase !== "apply") return `the ${job.phase} job of ${wave}`;
181
+ const share = job.share !== undefined ? `share ${job.share} of ` : "";
182
+ if (job.group !== undefined) return `${share}job group ${job.group} of ${wave}`;
183
+ return share ? `${share}${wave}` : `the apply job of ${wave}`;
184
+ }
185
+
186
+ /** The split jobs of wave `k`, by name, for a job after it (an apply status). */
187
+ export function opWaveSplitWaveJobs(jobs: readonly OpWaveSplitJob[], k: number): string[] {
188
+ return jobs.filter((j) => j.wave === k).map((j) => j.jobName);
189
+ }
@@ -405,6 +405,15 @@ export interface OpWave {
405
405
  shares?: number;
406
406
  /** The forge deployment environment the wave's jobs run in (GitHub and GitLab; Forgejo has none). */
407
407
  environment?: OpEnvironment;
408
+ /**
409
+ * Before merge (#4992), the environment of the wave's plan job alone. A
410
+ * split wave's applying job is its deployment and names `environment`, so
411
+ * its reviewers approve the wave once; the plan job names none on GitHub
412
+ * (on GitLab it names `environment` with `action: prepare`, which deploys
413
+ * nothing). Name one here, with no required reviewers, when the plan needs
414
+ * an environment's secrets or its OIDC claim. Forgejo has none.
415
+ */
416
+ planEnvironment?: OpEnvironment;
408
417
  /** Variables for this wave's jobs alone. */
409
418
  variables?: Record<string, string>;
410
419
  /** Steps this wave's jobs run after the checkout, as `ScheduledOpSpec.setup`. */
@@ -841,6 +850,11 @@ export function opWaveJobInputsByWave(spec: Pick<OpWavesSpec, "name" | "waves">,
841
850
  return names.map((name) => waveJobs?.[name]);
842
851
  }
843
852
 
853
+ /** The paths a product's wave job artifact keeps (#4994): `path`, one or a list. */
854
+ export function opWaveJobArtifactPaths(artifact: { path: string | readonly string[] }): string[] {
855
+ return typeof artifact.path === "string" ? [artifact.path] : [...artifact.path];
856
+ }
857
+
844
858
  /** A wave job's artifact name (#4791): `{job}` in `name` is the job's name. */
845
859
  export function opWaveJobArtifactName(name: string, jobName: string): string {
846
860
  return name.split("{job}").join(jobName);
@@ -933,7 +947,7 @@ export function opWaveChecksDir(spec: Pick<OpWavesSpec, "name">): string {
933
947
  }
934
948
 
935
949
  /** The outcome file of wave `wave`'s job, or of one group or share of it (#4322). */
936
- export function opWaveOutcomePath(spec: Pick<OpWavesSpec, "name">, wave: number, part: { group?: string; share?: number } = {}): string {
950
+ export function opWaveOutcomePath(spec: Pick<OpWavesSpec, "name">, wave: number, part: { group?: string; share?: number; apply?: boolean } = {}): string {
937
951
  return `${opWaveOutcomeDir(spec)}/${waveOutcomeFileName(wave, part)}`;
938
952
  }
939
953
 
@@ -1462,14 +1476,22 @@ export function opWaveShare<T extends { target: string }>(runs: readonly T[], sh
1462
1476
  * The jobs of an Op waves pipeline, in order. `specFile` is the spec's path
1463
1477
  * from the job's working directory, which every command names. `bin` is the
1464
1478
  * product's command in place of `chant` (#4607, {@link opWaveBinArgv}).
1479
+ * With `renderSpec` (#4982) every command passes `--render-spec`: the job
1480
+ * renders the spec at base through the product's command
1481
+ * (`./op-waves-render-spec.ts`), and `spec` is the pipeline's shape.
1482
+ * With `beforeMerge` (#4984) every command reads its base from
1483
+ * `CHANT_WAVES_BASE` when the run checked out a pull request's decided
1484
+ * head, else from the spec's `base` (or `HEAD^1`), as a push run does.
1465
1485
  */
1466
- export function opWaveJobs(spec: OpWavesSpec, specFile: string, options: { bin?: string } = {}): OpWaveJob[] {
1486
+ export function opWaveJobs(spec: OpWavesSpec, specFile: string, options: { bin?: string; renderSpec?: boolean; beforeMerge?: boolean } = {}): OpWaveJob[] {
1467
1487
  assertOpWavesSpec(spec);
1468
1488
  const jobs: OpWaveJob[] = [];
1469
1489
  let previous: string[] = [];
1490
+ // #4984: before merge the base is the default branch's commit the run started at, which the head's checkout step exports.
1491
+ const base = options.beforeMerge ? ["--base", `"\${CHANT_WAVES_BASE:-${(spec.base ?? "HEAD^1").replace(/["\\$`]/g, "\\$&")}}"`] : spec.base ? ["--base", spec.base] : [];
1470
1492
  spec.waves.forEach((wave, index) => {
1471
1493
  const k = index + 1;
1472
- const command = [...opWaveBinArgv(options.bin), "run", "wave", "--spec", specFile, "--wave", String(k), ...(spec.base ? ["--base", spec.base] : [])];
1494
+ const command = [...opWaveBinArgv(options.bin), "run", "wave", "--spec", specFile, "--wave", String(k), ...base, ...(options.renderSpec ? ["--render-spec"] : [])];
1473
1495
  const prefix = `wave-${k}-${wave.name}`;
1474
1496
  const shares = wave.shares ?? 1;
1475
1497
  if (shares === 1 && wave.jobs === undefined) {
@@ -1516,6 +1538,12 @@ export function opWaveGroupOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave" | "
1516
1538
  return job.group === undefined ? undefined : spec.waves[job.wave - 1]?.jobs?.find((g) => g.name === job.group);
1517
1539
  }
1518
1540
 
1541
+ /** Wave `k` of the spec, or past its waves the `rest` wave, which stands for each wave its plan found (#3821, #4992); undefined when there is none. */
1542
+ export function opWaveAt(spec: Pick<OpWavesSpec, "waves">, k: number): OpWave | undefined {
1543
+ const last = spec.waves[spec.waves.length - 1];
1544
+ return spec.waves[k - 1] ?? (k > spec.waves.length && last?.rest === true ? last : undefined);
1545
+ }
1546
+
1519
1547
  /** The wave a job belongs to. */
1520
1548
  export function opWaveOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave">): OpWave {
1521
1549
  return spec.waves[job.wave - 1]!;
@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
9
9
  import { join } from "node:path";
10
10
  import { afterEach, describe, expect, test } from "vitest";
11
11
  import { cronFiresUtc } from "./cron";
12
- import { checkOverdueOps, opPipelineFile, overdueOpsAt, overdueVerdict, PLAN_WATCHES_ENV, plannedWatchesFromEnv, scheduledWatches, scheduledWatchProblem } from "./schedule-overdue";
12
+ import { checkOverdueOps, opPipelineFile, overdueOpsAt, overdueVerdict, PLAN_WATCHES_ENV, plannedWatchesFromEnv, scheduledWatches, scheduledWatchProblem, watchesForTarget } from "./schedule-overdue";
13
13
  import { forgejoForge, githubForge, gitlabForge, type ForgeFetch, type PrForge } from "../pr-forge";
14
14
  import { renderPrNote, type PrReport } from "../pr-loop";
15
15
  import type { OpConfig } from "./types";
@@ -309,6 +309,49 @@ describe("checkOverdueOps", () => {
309
309
  expect(asked).toEqual([schedule]);
310
310
  expect(found[0]?.message).toContain("No active pipeline schedule is picked by the Op's rule, one whose TERRAGUCCI_SCHEDULE is none of comments, resume.");
311
311
  });
312
+
313
+ /**
314
+ * #4952: a shallow checkout's oldest commit lists every file as added, so
315
+ * the job that never ran counts from that commit and the check
316
+ * under-reports. The check deepens the history and reads the real commit.
317
+ */
318
+ describe("a shallow checkout", () => {
319
+ function shallowClone(): string {
320
+ const origin = repo({ ".github/workflows/drift.yml": "on: schedule" }, "2026-09-01T00:00:00Z");
321
+ const later = "2026-10-20T00:00:00Z";
322
+ writeFileSync(join(origin, "README.md"), "later\n");
323
+ execFileSync("git", ["-C", origin, "add", "."], { stdio: "pipe" });
324
+ execFileSync("git", ["-C", origin, "-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "later"], { env: { ...process.env, GIT_COMMITTER_DATE: later, GIT_AUTHOR_DATE: later }, stdio: "pipe" });
325
+ const clone = join(origin, ".clone");
326
+ execFileSync("git", ["clone", "-q", "--depth", "1", `file://${origin}`, clone], { stdio: "pipe" });
327
+ return clone;
328
+ }
329
+ const run = (root: string, lines: string[]) =>
330
+ checkOverdueOps({
331
+ watches: [{ op: "drift", cron: "0 6 * * *" }],
332
+ forge: forgeWith("github", async () => ({})),
333
+ repoRoot: root,
334
+ now: new Date("2026-10-22T00:00:00Z"),
335
+ log: (l) => lines.push(l),
336
+ });
337
+
338
+ test("deepens the history and counts from the commit that added the file", async () => {
339
+ const clone = shallowClone();
340
+ const lines: string[] = [];
341
+ const found = await run(clone, lines);
342
+ expect(found.map((o) => o.since.slice(0, 10))).toEqual(["2026-09-01"]);
343
+ expect(execFileSync("git", ["-C", clone, "rev-parse", "--is-shallow-repository"], { encoding: "utf-8" }).trim()).toBe("false");
344
+ });
345
+
346
+ test("a fetch that fails counts from the oldest commit there is, and says so", async () => {
347
+ const clone = shallowClone();
348
+ execFileSync("git", ["-C", clone, "remote", "remove", "origin"], { stdio: "pipe" });
349
+ const lines: string[] = [];
350
+ const found = await run(clone, lines);
351
+ expect(found.map((o) => o.since.slice(0, 10))).toEqual(["2026-10-20"]);
352
+ expect(lines.some((l) => l.includes("the checkout is shallow and its history could not be fetched"))).toBe(true);
353
+ });
354
+ });
312
355
  });
313
356
 
314
357
  describe("the plan note", () => {
@@ -410,4 +453,32 @@ describe("a product's words and watches", () => {
410
453
  expect(plannedWatchesFromEnv({ [PLAN_WATCHES_ENV]: "{" }, (l) => lines.push(l))).toEqual([]);
411
454
  expect(scheduledWatchProblem({ op: "a", cron: "0 6 * * *", schedule: { variable: "V", value: 'x" || true' } })).toContain("schedule value");
412
455
  });
456
+
457
+ // #4988: a product plan's watch scoped to the targets whose note checks it.
458
+ test("a target's note checks the watches scoped to it and the unscoped ones, not another target's", async () => {
459
+ const root = repo({ ".gitlab/yodel-watch.gitlab-ci.yml": "drift" });
460
+ const files = [".gitlab/yodel-watch.gitlab-ci.yml"];
461
+ const watches = [
462
+ { op: "yodel-watch-staging", cron: "0 6 * * *", files, targets: ["staging"] },
463
+ { op: "yodel-watch-prod", cron: "0 6 * * *", files, targets: ["prod"] },
464
+ { op: "shared", cron: "0 6 * * *", files },
465
+ ];
466
+ const asked = async (member: string | undefined): Promise<string[]> => {
467
+ const ops: string[] = [];
468
+ await overdueOpsAt({ forge: forge(async (q) => (ops.push(q.op), {})), cwd: root, now, log: () => {}, watches, ...(member ? { member } : {}) });
469
+ return ops;
470
+ };
471
+ expect(await asked("staging")).toEqual(["yodel-watch-staging", "shared"]);
472
+ expect(await asked("prod")).toEqual(["yodel-watch-prod", "shared"]);
473
+ expect(await asked(undefined)).toEqual(["yodel-watch-staging", "yodel-watch-prod", "shared"]);
474
+ expect(watchesForTarget(watches, "dev").map((w) => w.op)).toEqual(["shared"]);
475
+ });
476
+
477
+ test("a watch's targets reach the note job as names; anything else is not a watch", () => {
478
+ const scoped = { op: "yodel-watch-prod", cron: "0 6 * * *", targets: ["prod"] };
479
+ expect(plannedWatchesFromEnv({ [PLAN_WATCHES_ENV]: JSON.stringify([scoped]) })).toEqual([scoped]);
480
+ expect(scheduledWatchProblem({ ...scoped, targets: [] })).toBe("watch yodel-watch-prod's targets are not a list of target names");
481
+ expect(scheduledWatchProblem({ ...scoped, targets: ["prod; rm"] })).toBe("watch yodel-watch-prod's targets are not a list of target names");
482
+ expect(scheduledWatchProblem({ ...scoped, targets: "prod" })).toBe("watch yodel-watch-prod's targets are not a list of target names");
483
+ });
413
484
  });