@intentius/chant 0.124.55 → 0.124.57

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 (419) hide show
  1. package/dist/ci-agent.d.ts.map +1 -1
  2. package/dist/ci-agent.js +1 -2
  3. package/dist/ci-audit/attribution.d.ts +111 -0
  4. package/dist/ci-audit/attribution.d.ts.map +1 -0
  5. package/dist/ci-audit/attribution.js +194 -0
  6. package/dist/ci-audit/audit-log.d.ts +144 -0
  7. package/dist/ci-audit/audit-log.d.ts.map +1 -0
  8. package/dist/ci-audit/audit-log.js +149 -0
  9. package/dist/ci-audit/index.d.ts +12 -0
  10. package/dist/ci-audit/index.d.ts.map +1 -0
  11. package/dist/ci-audit/index.js +11 -0
  12. package/dist/ci-audit/unrecorded.d.ts +74 -0
  13. package/dist/ci-audit/unrecorded.d.ts.map +1 -0
  14. package/dist/ci-audit/unrecorded.js +95 -0
  15. package/dist/ci-audit.d.ts +3 -0
  16. package/dist/ci-audit.d.ts.map +1 -0
  17. package/dist/ci-audit.js +2 -0
  18. package/dist/ci-control.d.ts.map +1 -1
  19. package/dist/ci-control.js +3 -4
  20. package/dist/ci-estate.d.ts +24 -0
  21. package/dist/ci-estate.d.ts.map +1 -1
  22. package/dist/ci-estate.js +1 -2
  23. package/dist/ci-identity.d.ts.map +1 -1
  24. package/dist/ci-identity.js +2 -3
  25. package/dist/ci-job-guard.d.ts +139 -0
  26. package/dist/ci-job-guard.d.ts.map +1 -0
  27. package/dist/ci-job-guard.js +287 -0
  28. package/dist/ci-jobs.d.ts +7 -0
  29. package/dist/ci-jobs.d.ts.map +1 -1
  30. package/dist/ci-jobs.js +7 -0
  31. package/dist/ci-product-words.d.ts +7 -1
  32. package/dist/ci-product-words.d.ts.map +1 -1
  33. package/dist/ci-product-words.js +38 -4
  34. package/dist/ci-product.d.ts +35 -0
  35. package/dist/ci-product.d.ts.map +1 -1
  36. package/dist/ci-product.js +38 -4
  37. package/dist/ci-respond-run.d.ts +73 -0
  38. package/dist/ci-respond-run.d.ts.map +1 -0
  39. package/dist/ci-respond-run.js +247 -0
  40. package/dist/ci-respond.d.ts +189 -0
  41. package/dist/ci-respond.d.ts.map +1 -0
  42. package/dist/ci-respond.js +285 -0
  43. package/dist/cli/handlers/audit-log.d.ts +12 -0
  44. package/dist/cli/handlers/audit-log.d.ts.map +1 -0
  45. package/dist/cli/handlers/audit-log.js +81 -0
  46. package/dist/cli/handlers/build.d.ts +7 -0
  47. package/dist/cli/handlers/build.d.ts.map +1 -1
  48. package/dist/cli/handlers/build.js +81 -0
  49. package/dist/cli/handlers/ci-check-job.d.ts +11 -0
  50. package/dist/cli/handlers/ci-check-job.d.ts.map +1 -0
  51. package/dist/cli/handlers/ci-check-job.js +27 -0
  52. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  53. package/dist/cli/handlers/ci-check.js +38 -9
  54. package/dist/cli/handlers/e2e-safe-run.d.ts +12 -0
  55. package/dist/cli/handlers/e2e-safe-run.d.ts.map +1 -0
  56. package/dist/cli/handlers/e2e-safe-run.js +23 -0
  57. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  58. package/dist/cli/handlers/lifecycle.js +14 -0
  59. package/dist/cli/handlers/pr.d.ts +5 -0
  60. package/dist/cli/handlers/pr.d.ts.map +1 -1
  61. package/dist/cli/handlers/pr.js +346 -36
  62. package/dist/cli/handlers/run-wave.js +89 -1
  63. package/dist/cli/main.d.ts.map +1 -1
  64. package/dist/cli/main.js +56 -2
  65. package/dist/cli/parse-args.d.ts.map +1 -1
  66. package/dist/cli/parse-args.js +107 -0
  67. package/dist/cli/registry.d.ts +38 -0
  68. package/dist/cli/registry.d.ts.map +1 -1
  69. package/dist/components/adoption.d.ts.map +1 -1
  70. package/dist/components/adoption.js +1 -2
  71. package/dist/components/auto-release.d.ts +5 -2
  72. package/dist/components/auto-release.d.ts.map +1 -1
  73. package/dist/components/auto-release.js +9 -4
  74. package/dist/components/capability.d.ts +47 -0
  75. package/dist/components/capability.d.ts.map +1 -1
  76. package/dist/components/capability.js +25 -0
  77. package/dist/components/check-hooks.d.ts +4 -1
  78. package/dist/components/check-hooks.d.ts.map +1 -1
  79. package/dist/components/check-steps.d.ts +74 -0
  80. package/dist/components/check-steps.d.ts.map +1 -0
  81. package/dist/components/check-steps.js +102 -0
  82. package/dist/components/ci-services.d.ts.map +1 -1
  83. package/dist/components/ci-services.js +1 -2
  84. package/dist/components/deploy-units.d.ts +12 -0
  85. package/dist/components/deploy-units.d.ts.map +1 -1
  86. package/dist/components/deploy-units.js +20 -1
  87. package/dist/components/driver.d.ts +12 -0
  88. package/dist/components/driver.d.ts.map +1 -1
  89. package/dist/components/driver.js +35 -1
  90. package/dist/components/groups.d.ts.map +1 -1
  91. package/dist/components/groups.js +4 -3
  92. package/dist/components/pr-env-ledger.d.ts.map +1 -1
  93. package/dist/components/pr-env-ledger.js +1 -2
  94. package/dist/components/pr-environment.d.ts +1 -1
  95. package/dist/components/pr-environment.d.ts.map +1 -1
  96. package/dist/components/pr-environment.js +1 -1
  97. package/dist/components/pr-pipeline.d.ts +137 -5
  98. package/dist/components/pr-pipeline.d.ts.map +1 -1
  99. package/dist/components/pr-pipeline.js +164 -20
  100. package/dist/components/pr-run.d.ts +8 -0
  101. package/dist/components/pr-run.d.ts.map +1 -1
  102. package/dist/components/pr-run.js +9 -4
  103. package/dist/components/product-pipeline.d.ts +35 -2
  104. package/dist/components/product-pipeline.d.ts.map +1 -1
  105. package/dist/components/product-pipeline.js +24 -5
  106. package/dist/components/row-lease.d.ts +22 -1
  107. package/dist/components/row-lease.d.ts.map +1 -1
  108. package/dist/components/row-lease.js +32 -6
  109. package/dist/components/wave-plan.d.ts +8 -0
  110. package/dist/components/wave-plan.d.ts.map +1 -1
  111. package/dist/components/wave-plan.js +18 -2
  112. package/dist/e2e-harness/bucket.d.ts +21 -0
  113. package/dist/e2e-harness/bucket.d.ts.map +1 -0
  114. package/dist/e2e-harness/bucket.js +61 -0
  115. package/dist/e2e-harness/claim.d.ts +70 -0
  116. package/dist/e2e-harness/claim.d.ts.map +1 -0
  117. package/dist/e2e-harness/claim.js +98 -0
  118. package/dist/e2e-harness/driver.d.ts +64 -0
  119. package/dist/e2e-harness/driver.d.ts.map +1 -0
  120. package/dist/e2e-harness/driver.js +243 -0
  121. package/dist/e2e-harness/forgejo.d.ts +77 -0
  122. package/dist/e2e-harness/forgejo.d.ts.map +1 -0
  123. package/dist/e2e-harness/forgejo.js +205 -0
  124. package/dist/e2e-harness/git.d.ts +32 -0
  125. package/dist/e2e-harness/git.d.ts.map +1 -0
  126. package/dist/e2e-harness/git.js +67 -0
  127. package/dist/e2e-harness/index.d.ts +22 -0
  128. package/dist/e2e-harness/index.d.ts.map +1 -0
  129. package/dist/e2e-harness/index.js +47 -0
  130. package/dist/e2e-harness/jobs.d.ts +8 -0
  131. package/dist/e2e-harness/jobs.d.ts.map +1 -0
  132. package/dist/e2e-harness/jobs.js +34 -0
  133. package/dist/e2e-harness/pins.d.ts +45 -0
  134. package/dist/e2e-harness/pins.d.ts.map +1 -0
  135. package/dist/e2e-harness/pins.js +44 -0
  136. package/dist/e2e-harness/ports.d.ts +113 -0
  137. package/dist/e2e-harness/ports.d.ts.map +1 -0
  138. package/dist/e2e-harness/ports.js +4 -0
  139. package/dist/e2e-harness/reports.d.ts +45 -0
  140. package/dist/e2e-harness/reports.d.ts.map +1 -0
  141. package/dist/e2e-harness/reports.js +57 -0
  142. package/dist/e2e-harness/safe-run-cli.d.ts +17 -0
  143. package/dist/e2e-harness/safe-run-cli.d.ts.map +1 -0
  144. package/dist/e2e-harness/safe-run-cli.js +43 -0
  145. package/dist/e2e-harness/safe-run.d.ts +61 -0
  146. package/dist/e2e-harness/safe-run.d.ts.map +1 -0
  147. package/dist/e2e-harness/safe-run.js +172 -0
  148. package/dist/e2e-harness/scenario.d.ts +11 -0
  149. package/dist/e2e-harness/scenario.d.ts.map +1 -0
  150. package/dist/e2e-harness/scenario.js +89 -0
  151. package/dist/e2e-harness/schemas/demo-cycle.schema.json +282 -0
  152. package/dist/e2e-harness/schemas/demo-step.schema.json +245 -0
  153. package/dist/e2e-harness/schemas/e2e-claim-row.schema.json +33 -0
  154. package/dist/e2e-harness/schemas/e2e-claims.schema.json +18 -0
  155. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +150 -0
  156. package/dist/e2e-harness/schemas/index.d.ts +191 -0
  157. package/dist/e2e-harness/schemas/index.d.ts.map +1 -0
  158. package/dist/e2e-harness/schemas/index.js +62 -0
  159. package/dist/e2e-harness/stack.d.ts +124 -0
  160. package/dist/e2e-harness/stack.d.ts.map +1 -0
  161. package/dist/e2e-harness/stack.js +207 -0
  162. package/dist/e2e-harness/steps.d.ts +11 -0
  163. package/dist/e2e-harness/steps.d.ts.map +1 -0
  164. package/dist/e2e-harness/steps.js +22 -0
  165. package/dist/e2e-harness.d.ts +3 -0
  166. package/dist/e2e-harness.d.ts.map +1 -0
  167. package/dist/e2e-harness.js +2 -0
  168. package/dist/exit-codes.d.ts +7 -1
  169. package/dist/exit-codes.d.ts.map +1 -1
  170. package/dist/exit-codes.js +7 -1
  171. package/dist/lexicon.d.ts +55 -0
  172. package/dist/lexicon.d.ts.map +1 -1
  173. package/dist/lifecycle/gate-ledger.d.ts.map +1 -1
  174. package/dist/lifecycle/gate-ledger.js +2 -3
  175. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  176. package/dist/lifecycle/gated-request.js +1 -2
  177. package/dist/lifecycle/git.d.ts +39 -3
  178. package/dist/lifecycle/git.d.ts.map +1 -1
  179. package/dist/lifecycle/git.js +223 -15
  180. package/dist/lifecycle/lock-rows.d.ts +23 -0
  181. package/dist/lifecycle/lock-rows.d.ts.map +1 -1
  182. package/dist/lifecycle/lock-rows.js +47 -8
  183. package/dist/lifecycle/query.d.ts.map +1 -1
  184. package/dist/lifecycle/query.js +4 -5
  185. package/dist/lifecycle/release-catalog.d.ts.map +1 -1
  186. package/dist/lifecycle/release-catalog.js +1 -1
  187. package/dist/lifecycle/release-ledger.d.ts.map +1 -1
  188. package/dist/lifecycle/release-ledger.js +1 -2
  189. package/dist/lifecycle/release-status.d.ts +20 -0
  190. package/dist/lifecycle/release-status.d.ts.map +1 -1
  191. package/dist/lifecycle/release-status.js +1 -22
  192. package/dist/lifecycle/resource-lock.d.ts +70 -0
  193. package/dist/lifecycle/resource-lock.d.ts.map +1 -1
  194. package/dist/lifecycle/resource-lock.js +241 -5
  195. package/dist/lifecycle/wave-plans.d.ts +23 -7
  196. package/dist/lifecycle/wave-plans.d.ts.map +1 -1
  197. package/dist/lifecycle/wave-plans.js +9 -2
  198. package/dist/op/approval-status.d.ts +103 -0
  199. package/dist/op/approval-status.d.ts.map +1 -0
  200. package/dist/op/approval-status.js +197 -0
  201. package/dist/op/gate.js +21 -4
  202. package/dist/op/index.d.ts +1 -1
  203. package/dist/op/index.d.ts.map +1 -1
  204. package/dist/op/index.js +1 -1
  205. package/dist/op/op-waves-capability-spec.d.ts +8 -0
  206. package/dist/op/op-waves-capability-spec.d.ts.map +1 -1
  207. package/dist/op/op-waves-capability-spec.js +21 -0
  208. package/dist/op/op-waves-release-port.js +1 -1
  209. package/dist/op/op-waves-release.d.ts +2 -1
  210. package/dist/op/op-waves-release.d.ts.map +1 -1
  211. package/dist/op/op-waves-release.js +1 -2
  212. package/dist/op/op-waves-run.d.ts +15 -2
  213. package/dist/op/op-waves-run.d.ts.map +1 -1
  214. package/dist/op/op-waves-run.js +195 -31
  215. package/dist/op/op-waves-stand-down.d.ts.map +1 -1
  216. package/dist/op/op-waves-stand-down.js +1 -2
  217. package/dist/op/op-waves.d.ts +53 -0
  218. package/dist/op/op-waves.d.ts.map +1 -1
  219. package/dist/op/op-waves.js +62 -6
  220. package/dist/op/runtime.d.ts +4 -0
  221. package/dist/op/runtime.d.ts.map +1 -1
  222. package/dist/op/runtime.js +2 -3
  223. package/dist/otlp.d.ts.map +1 -1
  224. package/dist/otlp.js +1 -2
  225. package/dist/parallelism.d.ts +17 -0
  226. package/dist/parallelism.d.ts.map +1 -0
  227. package/dist/parallelism.js +33 -0
  228. package/dist/policy-source.d.ts.map +1 -1
  229. package/dist/policy-source.js +1 -2
  230. package/dist/pr-forge.d.ts.map +1 -1
  231. package/dist/pr-forge.js +56 -39
  232. package/dist/pr-loop.d.ts +9 -0
  233. package/dist/pr-loop.d.ts.map +1 -1
  234. package/dist/pr-loop.js +22 -4
  235. package/dist/pr-merge.d.ts +64 -0
  236. package/dist/pr-merge.d.ts.map +1 -0
  237. package/dist/pr-merge.js +78 -0
  238. package/dist/pr-post.d.ts +70 -1
  239. package/dist/pr-post.d.ts.map +1 -1
  240. package/dist/pr-post.js +116 -5
  241. package/dist/pr-report-url.d.ts.map +1 -1
  242. package/dist/pr-report-url.js +1 -2
  243. package/dist/release-floors.d.ts +1 -1
  244. package/dist/release-floors.js +1 -1
  245. package/dist/run-event.d.ts.map +1 -1
  246. package/dist/run-event.js +1 -2
  247. package/dist/scheduled-op-cloud.d.ts +32 -0
  248. package/dist/scheduled-op-cloud.d.ts.map +1 -0
  249. package/dist/scheduled-op-cloud.js +69 -0
  250. package/dist/wave-runtime.mjs +351 -328
  251. package/dist/workspace/ci-lock-grain.d.ts +5 -0
  252. package/dist/workspace/ci-lock-grain.d.ts.map +1 -1
  253. package/dist/workspace/ci-lock-grain.js +1 -7
  254. package/dist/workspace/ci-run.d.ts.map +1 -1
  255. package/dist/workspace/ci-run.js +5 -1
  256. package/dist/workspace/pr-report.schema.json +5 -0
  257. package/package.json +1 -1
  258. package/src/ci-agent.ts +1 -2
  259. package/src/ci-audit/__fixtures__/cloudtrail-lookup-bucket.json +37 -0
  260. package/src/ci-audit/__fixtures__/cloudtrail-writes-window.json +59 -0
  261. package/src/ci-audit/attribution.ts +260 -0
  262. package/src/ci-audit/audit-log.ts +220 -0
  263. package/src/ci-audit/ci-audit.test.ts +175 -0
  264. package/src/ci-audit/index.ts +14 -0
  265. package/src/ci-audit/unrecorded.ts +140 -0
  266. package/src/ci-audit.ts +2 -0
  267. package/src/ci-control.ts +3 -4
  268. package/src/ci-estate.ts +1 -2
  269. package/src/ci-identity-database.test.ts +2 -3
  270. package/src/ci-identity-targets.test.ts +1 -3
  271. package/src/ci-identity.ts +2 -3
  272. package/src/ci-job-guard.test.ts +154 -0
  273. package/src/ci-job-guard.ts +319 -0
  274. package/src/ci-jobs.ts +8 -0
  275. package/src/ci-product-comment-targets.test.ts +45 -0
  276. package/src/ci-product-words.ts +35 -6
  277. package/src/ci-product.ts +55 -4
  278. package/src/ci-respond-run.ts +291 -0
  279. package/src/ci-respond.test.ts +264 -0
  280. package/src/ci-respond.ts +412 -0
  281. package/src/cli/handlers/audit-log.ts +74 -0
  282. package/src/cli/handlers/build-pr-loop-flags.test.ts +98 -0
  283. package/src/cli/handlers/build.ts +69 -0
  284. package/src/cli/handlers/ci-check-job.test.ts +114 -0
  285. package/src/cli/handlers/ci-check-job.ts +33 -0
  286. package/src/cli/handlers/ci-check.ts +38 -8
  287. package/src/cli/handlers/e2e-safe-run.ts +27 -0
  288. package/src/cli/handlers/lifecycle.ts +13 -0
  289. package/src/cli/handlers/pr-before-merge.test.ts +1 -1
  290. package/src/cli/handlers/pr-deploy-inputs.test.ts +1 -1
  291. package/src/cli/handlers/pr-endpoint.test.ts +1 -1
  292. package/src/cli/handlers/pr-green.test.ts +1 -1
  293. package/src/cli/handlers/pr-plan-comment-targets.test.ts +166 -0
  294. package/src/cli/handlers/pr-plan-flags.test.ts +161 -0
  295. package/src/cli/handlers/pr-plan-targets.test.ts +1 -1
  296. package/src/cli/handlers/pr-record.test.ts +34 -2
  297. package/src/cli/handlers/pr-waves-blocked.test.ts +1 -1
  298. package/src/cli/handlers/pr-waves.test.ts +1 -1
  299. package/src/cli/handlers/pr.test.ts +1 -1
  300. package/src/cli/handlers/pr.ts +311 -32
  301. package/src/cli/handlers/run-wave.ts +79 -1
  302. package/src/cli/main.test.ts +1 -1
  303. package/src/cli/main.ts +56 -2
  304. package/src/cli/parse-args.ts +77 -0
  305. package/src/cli/registry.ts +38 -0
  306. package/src/components/adoption.ts +1 -2
  307. package/src/components/auto-release.test.ts +4 -2
  308. package/src/components/auto-release.ts +9 -5
  309. package/src/components/capability.ts +60 -0
  310. package/src/components/check-hooks.ts +4 -1
  311. package/src/components/check-steps.test.ts +70 -0
  312. package/src/components/check-steps.ts +158 -0
  313. package/src/components/ci-services.ts +1 -2
  314. package/src/components/deploy-units.test.ts +18 -1
  315. package/src/components/deploy-units.ts +26 -1
  316. package/src/components/driver.ts +35 -1
  317. package/src/components/groups.ts +4 -2
  318. package/src/components/plan-flags.test.ts +46 -0
  319. package/src/components/pr-comment-preview-targets.test.ts +34 -0
  320. package/src/components/pr-env-ledger.ts +1 -2
  321. package/src/components/pr-env-run-bundle.test.ts +0 -20
  322. package/src/components/pr-environment.ts +1 -1
  323. package/src/components/pr-pipeline-runners.test.ts +80 -0
  324. package/src/components/pr-pipeline.ts +244 -20
  325. package/src/components/pr-run.ts +17 -6
  326. package/src/components/pr-stale-job.test.ts +34 -0
  327. package/src/components/product-pipeline.ts +50 -8
  328. package/src/components/row-lease.test.ts +61 -1
  329. package/src/components/row-lease.ts +48 -7
  330. package/src/components/wave-plan.ts +18 -2
  331. package/src/e2e-harness/__project__/chant.config.ts +4 -0
  332. package/src/e2e-harness/__project__/src/compose.ts +33 -0
  333. package/src/e2e-harness/bucket.ts +69 -0
  334. package/src/e2e-harness/claim.test.ts +150 -0
  335. package/src/e2e-harness/claim.ts +140 -0
  336. package/src/e2e-harness/driver.test.ts +304 -0
  337. package/src/e2e-harness/driver.ts +294 -0
  338. package/src/e2e-harness/forgejo.ts +267 -0
  339. package/src/e2e-harness/git.ts +96 -0
  340. package/src/e2e-harness/index.ts +49 -0
  341. package/src/e2e-harness/jobs.ts +35 -0
  342. package/src/e2e-harness/pins.ts +52 -0
  343. package/src/e2e-harness/ports.ts +130 -0
  344. package/src/e2e-harness/reports.ts +79 -0
  345. package/src/e2e-harness/safe-run-cli.test.ts +102 -0
  346. package/src/e2e-harness/safe-run-cli.ts +54 -0
  347. package/src/e2e-harness/safe-run.ts +198 -0
  348. package/src/e2e-harness/scenario.ts +89 -0
  349. package/src/e2e-harness/schemas/README.md +62 -0
  350. package/src/e2e-harness/schemas/demo-cycle.schema.json +282 -0
  351. package/src/e2e-harness/schemas/demo-step.schema.json +245 -0
  352. package/src/e2e-harness/schemas/e2e-claim-row.schema.json +33 -0
  353. package/src/e2e-harness/schemas/e2e-claims.schema.json +18 -0
  354. package/src/e2e-harness/schemas/e2e-scenario.schema.json +150 -0
  355. package/src/e2e-harness/schemas/index.ts +220 -0
  356. package/src/e2e-harness/schemas.test.ts +145 -0
  357. package/src/e2e-harness/stack.test.ts +124 -0
  358. package/src/e2e-harness/stack.ts +306 -0
  359. package/src/e2e-harness/steps.ts +30 -0
  360. package/src/e2e-harness.ts +2 -0
  361. package/src/exit-codes.test.ts +3 -2
  362. package/src/exit-codes.ts +7 -1
  363. package/src/gate-decision-bundle.test.ts +0 -2
  364. package/src/lexicon.ts +57 -0
  365. package/src/lifecycle/control-entries-ledger.test.ts +2 -3
  366. package/src/lifecycle/gate-ledger.ts +2 -3
  367. package/src/lifecycle/gated-request.ts +1 -2
  368. package/src/lifecycle/git.test.ts +155 -0
  369. package/src/lifecycle/git.ts +213 -17
  370. package/src/lifecycle/lock-rows.test.ts +6 -1
  371. package/src/lifecycle/lock-rows.ts +58 -7
  372. package/src/lifecycle/query.ts +4 -5
  373. package/src/lifecycle/release-catalog.test.ts +3 -4
  374. package/src/lifecycle/release-catalog.ts +1 -1
  375. package/src/lifecycle/release-ledger.ts +1 -2
  376. package/src/lifecycle/release-status.test.ts +3 -4
  377. package/src/lifecycle/release-status.ts +1 -2
  378. package/src/lifecycle/resource-lock-wait.test.ts +292 -0
  379. package/src/lifecycle/resource-lock.ts +261 -7
  380. package/src/lifecycle/wave-plans.ts +33 -5
  381. package/src/op/approval-status.test.ts +134 -0
  382. package/src/op/approval-status.ts +235 -0
  383. package/src/op/gate-review.test.ts +2 -1
  384. package/src/op/gate.test.ts +7 -5
  385. package/src/op/gate.ts +20 -4
  386. package/src/op/index.ts +2 -0
  387. package/src/op/op-waves-after-plan.test.ts +11 -0
  388. package/src/op/op-waves-capability-spec.ts +20 -0
  389. package/src/op/op-waves-ledger-lock.test.ts +208 -0
  390. package/src/op/op-waves-parallelism.test.ts +89 -0
  391. package/src/op/op-waves-pull-request.test.ts +78 -1
  392. package/src/op/op-waves-release-port.ts +1 -1
  393. package/src/op/op-waves-release.ts +2 -3
  394. package/src/op/op-waves-run.ts +196 -31
  395. package/src/op/op-waves-stand-down.ts +1 -2
  396. package/src/op/op-waves.ts +81 -6
  397. package/src/op/runtime.ts +6 -3
  398. package/src/otlp.ts +1 -2
  399. package/src/parallelism.test.ts +38 -0
  400. package/src/parallelism.ts +33 -0
  401. package/src/policy-source.ts +1 -2
  402. package/src/pr-forge-bundle.test.ts +1 -1
  403. package/src/pr-forge.ts +54 -35
  404. package/src/pr-loop-bundle.test.ts +0 -2
  405. package/src/pr-loop-narrowed.test.ts +63 -0
  406. package/src/pr-loop.ts +30 -4
  407. package/src/pr-merge.test.ts +100 -0
  408. package/src/pr-merge.ts +105 -0
  409. package/src/pr-post-stale.test.ts +163 -0
  410. package/src/pr-post.ts +159 -5
  411. package/src/pr-report-url.ts +1 -2
  412. package/src/product-subpaths-plain-node.e2e.test.ts +1 -0
  413. package/src/release-floors.ts +1 -1
  414. package/src/run-event.ts +1 -2
  415. package/src/scheduled-op-cloud.ts +68 -0
  416. package/src/stage-hooks-bundle.test.ts +0 -2
  417. package/src/workspace/ci-lock-grain.ts +1 -2
  418. package/src/workspace/ci-run.ts +5 -1
  419. package/src/workspace/pr-report.schema.json +5 -0
@@ -24,6 +24,19 @@
24
24
  * for one release), or, for a run on this host outside CI, when its
25
25
  * process is. Anything nobody can answer counts as alive.
26
26
  * - A release never throws: a row left held is taken over once its run is gone.
27
+ * - A take may wait (ruling for ci-products 2026-10-28, "Ledger lock"): the
28
+ * `target` and `repo` grains, a stock Pulumi stack's `stack` row, a
29
+ * Terraform root's `root` row or the `repo` row. A waiting run adds itself
30
+ * to `waiting` in the file, and takes its rows only once no live run holds
31
+ * any of them and no live waiter for a row that meets one of them comes
32
+ * first. First is the older commit (`commitAt`, the commit time of the
33
+ * commit the run applies), then the lower run id (both numbers, else by
34
+ * text), then the commit sha: the run that started first among runs of one
35
+ * commit. A waiter that is gone is dropped by the next writer, as a holder
36
+ * is. A wait that reaches its deadline (`CHANT_LOCK_WAIT` seconds, which
37
+ * the waves pipelines set from the job's timeout) leaves the queue and
38
+ * fails with {@link LockWaitTimeoutError}, the table's `held`, exit 5. A
39
+ * take on the resource grain never waits: a held row refuses it at once.
27
40
  *
28
41
  * The writes go through chant's ledger code (./git.ts) with the same
29
42
  * read-then-CAS and push the target locks use, in place of terragucci's raw
@@ -35,6 +48,7 @@
35
48
  * exit 5, and names the run that holds it.
36
49
  */
37
50
  import { hostname } from "node:os";
51
+ import { getRuntime } from "../runtime-adapter";
38
52
  import { pushLifecycleStatus, readBlobBySha, readPathSha, RefCASConflictError, writeBlobToPath } from "./git";
39
53
  import { lockRowsConflict, sortedLockRows, type LockRow } from "./lock-rows";
40
54
  import { dropRefusedWrite, fetchForLocks, localTip, LOCKS_DIR, targetLockGateProblem } from "./target-lock";
@@ -57,12 +71,21 @@ export interface LockRowHolder {
57
71
  sha?: string;
58
72
  }
59
73
 
74
+ /** A run waiting for rows: who it is, the rows it waits for, and the commit time that orders it. */
75
+ export interface LockRowWaiter extends LockRowHolder {
76
+ keys: string[];
77
+ /** The commit time (ISO 8601) of the commit the run applies. Absent sorts after every waiter that has one. */
78
+ commitAt?: string;
79
+ }
80
+
60
81
  /** `_locks/rows/<gate>.json`. */
61
82
  export interface LockRowsFile {
62
83
  version: 1;
63
84
  holders: Record<string, LockRowHolder>;
64
85
  /** Row key to the run that holds it. */
65
86
  rows: Record<string, string>;
87
+ /** The runs waiting for rows (ruling for ci-products 2026-10-28), by run. Left out of the file when empty. */
88
+ waiting?: Record<string, LockRowWaiter>;
66
89
  }
67
90
 
68
91
  /** A row another run holds, conflicting with `wanted`. */
@@ -161,7 +184,24 @@ export function parseLockRows(text: string | null): LockRowsFile {
161
184
  }
162
185
  const rows: Record<string, string> = {};
163
186
  for (const [k, id] of Object.entries(doc.rows as Record<string, unknown>)) if (typeof id === "string" && holders[id]) rows[k] = id;
164
- return { version: 1, holders, rows };
187
+ const waiting: Record<string, LockRowWaiter> = {};
188
+ const rawWaiting = (doc as { waiting?: unknown }).waiting;
189
+ if (rawWaiting && typeof rawWaiting === "object") {
190
+ for (const [id, raw] of Object.entries(rawWaiting as Record<string, Record<string, unknown>>)) {
191
+ if (typeof raw?.run !== "string" || typeof raw.at !== "string" || !Array.isArray(raw.keys)) continue;
192
+ const keys = (raw.keys as unknown[]).filter((k): k is string => typeof k === "string");
193
+ if (keys.length === 0) continue;
194
+ waiting[id] = {
195
+ run: raw.run,
196
+ at: raw.at,
197
+ keys,
198
+ ...(typeof raw.url === "string" ? { url: raw.url } : {}),
199
+ ...(typeof raw.sha === "string" ? { sha: raw.sha } : {}),
200
+ ...(typeof raw.commitAt === "string" ? { commitAt: raw.commitAt } : {}),
201
+ };
202
+ }
203
+ }
204
+ return { version: 1, holders, rows, ...(Object.keys(waiting).length > 0 ? { waiting } : {}) };
165
205
  }
166
206
  } catch {
167
207
  // An unreadable file holds no rows.
@@ -172,7 +212,8 @@ export function parseLockRows(text: string | null): LockRowsFile {
172
212
  /** The file's text, keys sorted, so two writes of the same rows are the same blob. */
173
213
  export function renderLockRows(file: LockRowsFile): string {
174
214
  const sort = <T>(r: Record<string, T>) => Object.fromEntries(Object.keys(r).sort().map((k) => [k, r[k]]));
175
- return `${JSON.stringify({ version: 1, holders: sort(file.holders), rows: sort(file.rows) }, null, 2)}\n`;
215
+ const waiting = file.waiting && Object.keys(file.waiting).length > 0 ? { waiting: sort(file.waiting) } : {};
216
+ return `${JSON.stringify({ version: 1, holders: sort(file.holders), rows: sort(file.rows), ...waiting }, null, 2)}\n`;
176
217
  }
177
218
 
178
219
  /** Who else holds a row that meets any of `keys`, split into runs still going and runs that are gone. */
@@ -197,19 +238,68 @@ export async function heldLockRowsIn(file: LockRowsFile, keys: readonly string[]
197
238
  * `gone`. Pure, so the decision can be checked without git.
198
239
  */
199
240
  export function withRowsTaken(file: LockRowsFile, keys: readonly string[], me: LockRowHolder, gone: readonly string[]): LockRowsFile {
200
- const next: LockRowsFile = { version: 1, holders: { ...file.holders }, rows: { ...file.rows } };
241
+ const next = copyRows(file);
201
242
  for (const id of gone) {
202
243
  delete next.holders[id];
203
244
  for (const [k, h] of Object.entries(next.rows)) if (h === id) delete next.rows[k];
245
+ delete next.waiting?.[id];
204
246
  }
205
- next.holders[me.run] = me;
247
+ delete next.waiting?.[me.run];
248
+ next.holders[me.run] = { run: me.run, at: me.at, ...(me.url ? { url: me.url } : {}), ...(me.sha ? { sha: me.sha } : {}) };
206
249
  for (const k of keys) next.rows[k] = me.run;
250
+ return tidyWaiting(next);
251
+ }
252
+
253
+ function copyRows(file: LockRowsFile): LockRowsFile {
254
+ return { version: 1, holders: { ...file.holders }, rows: { ...file.rows }, ...(file.waiting ? { waiting: { ...file.waiting } } : {}) };
255
+ }
256
+
257
+ function tidyWaiting(file: LockRowsFile): LockRowsFile {
258
+ if (file.waiting && Object.keys(file.waiting).length === 0) delete file.waiting;
259
+ return file;
260
+ }
261
+
262
+ /** The rows file with `me` in the queue for `keys`, less the waiters in `gone`. Pure. */
263
+ export function withWaiter(file: LockRowsFile, me: LockRowWaiter, gone: readonly string[] = []): LockRowsFile {
264
+ const next = copyRows(file);
265
+ next.waiting = { ...(next.waiting ?? {}) };
266
+ for (const id of gone) delete next.waiting[id];
267
+ next.waiting[me.run] = { ...me, keys: [...new Set(me.keys)].sort() };
207
268
  return next;
208
269
  }
209
270
 
271
+ /** The rows file with `me` out of the queue. Pure. */
272
+ export function withoutWaiter(file: LockRowsFile, me: string): LockRowsFile {
273
+ const next = copyRows(file);
274
+ delete next.waiting?.[me];
275
+ return tidyWaiting(next);
276
+ }
277
+
278
+ /**
279
+ * Whether waiter `a` goes before waiter `b`: the older commit first, then the
280
+ * lower run id (as numbers when both are, else as text), then the commit
281
+ * sha. A waiter with no commit time goes after every one that has one.
282
+ */
283
+ export function waiterBefore(a: Pick<LockRowWaiter, "run" | "commitAt" | "sha">, b: Pick<LockRowWaiter, "run" | "commitAt" | "sha">): boolean {
284
+ const time = (w: { commitAt?: string }) => {
285
+ const t = w.commitAt ? new Date(w.commitAt).getTime() : NaN;
286
+ return Number.isFinite(t) ? t : Number.POSITIVE_INFINITY;
287
+ };
288
+ const ta = time(a);
289
+ const tb = time(b);
290
+ if (ta !== tb) return ta < tb;
291
+ if (a.run !== b.run) {
292
+ const na = Number(a.run);
293
+ const nb = Number(b.run);
294
+ if (/^\d+$/.test(a.run) && /^\d+$/.test(b.run) && na !== nb) return na < nb;
295
+ return a.run < b.run;
296
+ }
297
+ return (a.sha ?? "") < (b.sha ?? "");
298
+ }
299
+
210
300
  /** The rows file after `me` lets go of `keys`; its holder entry goes once it holds no row. */
211
301
  export function withRowsReleased(file: LockRowsFile, keys: readonly string[], me: string): LockRowsFile {
212
- const next: LockRowsFile = { version: 1, holders: { ...file.holders }, rows: { ...file.rows } };
302
+ const next = copyRows(file);
213
303
  for (const k of keys) if (next.rows[k] === me) delete next.rows[k];
214
304
  if (!Object.values(next.rows).includes(me)) delete next.holders[me];
215
305
  return next;
@@ -292,6 +382,161 @@ export async function takeLockRows(gate: string, rows: readonly LockRow[], me: L
292
382
  throw new Error(`could not hold the rows of ${gate}: ${STATE_BRANCH} kept moving; check that the job may push to it`);
293
383
  }
294
384
 
385
+ /** A wait for rows reached its deadline (ruling for ci-products 2026-10-28): nothing applied. Exit 5, as a held row is. */
386
+ export class LockWaitTimeoutError extends Error {
387
+ readonly lockRowsHeld = true;
388
+ constructor(
389
+ message: string,
390
+ public readonly held: HeldLockRow[],
391
+ public readonly ahead: LockRowWaiter[],
392
+ public readonly waitedSeconds: number,
393
+ ) {
394
+ super(message);
395
+ this.name = "LockWaitTimeoutError";
396
+ }
397
+ }
398
+
399
+ /** How a take waits for its rows. */
400
+ export interface LockRowsWait {
401
+ /** When the wait gives up, in ms since the epoch. */
402
+ deadline: number;
403
+ /** The commit time (ISO 8601) of the commit the run applies, which orders the queue. */
404
+ commitAt?: string;
405
+ /** How long between reads of the rows file, in ms. Default `CHANT_LOCK_POLL` seconds, else 10 s. */
406
+ pollMs?: number;
407
+ /** Where the wait's lines go. Default: none. */
408
+ log?: (line: string) => void;
409
+ /** The clock and the pause, for tests. */
410
+ now?: () => number;
411
+ sleep?: (ms: number) => Promise<void>;
412
+ }
413
+
414
+ /** The default wait when a job names no timeout: just under three hours, a Forgejo runner's default job timeout. */
415
+ export const DEFAULT_LOCK_WAIT_SECONDS = 3 * 3600 - 300;
416
+
417
+ /** How long a take waits, in seconds: `CHANT_LOCK_WAIT`, else {@link DEFAULT_LOCK_WAIT_SECONDS}. */
418
+ export function lockWaitSeconds(env: Record<string, string | undefined>): number {
419
+ const n = Number(env.CHANT_LOCK_WAIT);
420
+ return env.CHANT_LOCK_WAIT !== undefined && Number.isFinite(n) && n >= 0 ? n : DEFAULT_LOCK_WAIT_SECONDS;
421
+ }
422
+
423
+ /** The poll interval in ms: `CHANT_LOCK_POLL` seconds, else 10 s. */
424
+ export function lockPollMs(env: Record<string, string | undefined>): number {
425
+ const n = Number(env.CHANT_LOCK_POLL);
426
+ return env.CHANT_LOCK_POLL !== undefined && Number.isFinite(n) && n > 0 ? n * 1000 : 10_000;
427
+ }
428
+
429
+ /** The commit time of `rev` in `cwd` (ISO 8601), or undefined when git cannot say. */
430
+ export async function commitTimeOf(rev: string, cwd?: string): Promise<string | undefined> {
431
+ const out = await getRuntime().spawn(["git", "show", "-s", "--format=%cI", rev], { cwd });
432
+ const t = out.exitCode === 0 ? out.stdout.trim() : "";
433
+ return t && Number.isFinite(new Date(t).getTime()) ? t : undefined;
434
+ }
435
+
436
+ /** The live waiters for a row that meets one of `keys` who go before `me`, and the waiters that are gone. */
437
+ export async function waitersAhead(file: LockRowsFile, keys: readonly string[], me: LockRowWaiter, alive: LockLiveness): Promise<{ ahead: LockRowWaiter[]; gone: string[] }> {
438
+ const ahead: LockRowWaiter[] = [];
439
+ const gone: string[] = [];
440
+ for (const [id, w] of Object.entries(file.waiting ?? {})) {
441
+ if (id === me.run || w.run === me.run) continue;
442
+ if (!w.keys.some((k) => keys.some((mine) => lockRowsConflict(k, mine)))) continue;
443
+ const verdict = await alive(w);
444
+ if (verdict === "dead") {
445
+ gone.push(id);
446
+ continue;
447
+ }
448
+ if (waiterBefore(w, me)) ahead.push(w);
449
+ }
450
+ return { ahead: ahead.sort((a, b) => (waiterBefore(a, b) ? -1 : 1)), gone: gone.sort() };
451
+ }
452
+
453
+ function describeWait(held: readonly HeldLockRow[], ahead: readonly LockRowWaiter[], rows: readonly LockRow[]): string {
454
+ const parts: string[] = [];
455
+ if (held.length > 0) parts.push(describeHeldLockRows(held, rows));
456
+ if (ahead.length > 0) parts.push(`${ahead.map((w) => `run ${w.run}${w.url ? ` (${w.url})` : ""}`).join(", ")} ${ahead.length === 1 ? "waits" : "wait"} ahead of it with an older commit`);
457
+ return parts.join("; ");
458
+ }
459
+
460
+ /**
461
+ * Take `rows` for `me`, waiting in the queue until no live run holds any of
462
+ * them and no live waiter that goes first ({@link waiterBefore}) waits for a
463
+ * row that meets one of them. Throws {@link LockWaitTimeoutError} at the
464
+ * deadline, after leaving the queue.
465
+ */
466
+ export async function waitLockRows(gate: string, rows: readonly LockRow[], me: LockRowHolder, wait: LockRowsWait, opts: LockRowsOptions = {}): Promise<{ ok: true; tookOver: LockRowHolder[]; pushed: boolean; waitedSeconds: number; waited: boolean }> {
467
+ checkGate(gate);
468
+ const keys = sortedLockRows(rows).map((r) => r.key);
469
+ if (keys.length === 0) return { ok: true, tookOver: [], pushed: false, waitedSeconds: 0, waited: false };
470
+ const alive = opts.alive ?? forgeLockLiveness(process.env);
471
+ const now = wait.now ?? Date.now;
472
+ const sleep = wait.sleep ?? pause;
473
+ const poll = wait.pollMs ?? lockPollMs(process.env);
474
+ const stale = lockStaleSeconds(process.env) * 1000;
475
+ const started = now();
476
+ const waiter = (): LockRowWaiter => ({ ...me, keys, ...(wait.commitAt ? { commitAt: wait.commitAt } : {}) });
477
+ let queued: LockRowWaiter | undefined;
478
+ let said = "";
479
+ await fetchForLocks(opts.cwd);
480
+ for (let raced = 0; ; ) {
481
+ const { sha, file } = await readCurrent(gate, opts.cwd);
482
+ const mine = queued ?? waiter();
483
+ const { live, gone } = await heldLockRowsIn(file, keys, me.run, alive);
484
+ const { ahead, gone: goneWaiters } = await waitersAhead(file, keys, mine, alive);
485
+ if (live.length === 0 && ahead.length === 0) {
486
+ const next = withRowsTaken(file, keys, me, gone);
487
+ for (const id of goneWaiters) delete next.waiting?.[id];
488
+ const took = gone.length ? `, taken over from run ${gone.join(", ")}` : "";
489
+ const wrote = await writeAndPush(gate, sha, tidyWaiting(next), `Hold ${keys.length} row${keys.length === 1 ? "" : "s"} of ${gate} for run ${me.run}${took}`, opts.cwd);
490
+ if (wrote) return { ok: true, tookOver: gone.map((id) => file.holders[id]!), pushed: wrote.pushed, waitedSeconds: Math.round((now() - started) / 1000), waited: queued !== undefined };
491
+ if (++raced >= ATTEMPTS) throw new Error(`could not hold the rows of ${gate}: ${STATE_BRANCH} kept moving; check that the job may push to it`);
492
+ await sleep(200 + Math.floor(Math.random() * 800));
493
+ continue;
494
+ }
495
+ const why = describeWait(live, ahead, rows);
496
+ if (now() >= wait.deadline) {
497
+ await leaveQueue(gate, me.run, opts.cwd);
498
+ const waited = Math.round((now() - started) / 1000);
499
+ throw new LockWaitTimeoutError(`waited ${waited}s for ${keys.join(", ")} of ${gate} and gave up at the job's deadline: ${why}`, live, ahead, waited);
500
+ }
501
+ const inFile = file.waiting?.[me.run];
502
+ const refresh = inFile ? now() - new Date(inFile.at).getTime() > stale / 2 : true;
503
+ if (!inFile || refresh || goneWaiters.length > 0) {
504
+ const entry: LockRowWaiter = { ...waiter(), at: new Date(now()).toISOString() };
505
+ const wrote = await writeAndPush(gate, sha, withWaiter(file, entry, goneWaiters), `Run ${me.run} waits for ${keys.length} row${keys.length === 1 ? "" : "s"} of ${gate}`, opts.cwd);
506
+ if (!wrote) {
507
+ if (++raced >= ATTEMPTS) throw new Error(`could not join the queue for the rows of ${gate}: ${STATE_BRANCH} kept moving; check that the job may push to it`);
508
+ await sleep(200 + Math.floor(Math.random() * 800));
509
+ continue;
510
+ }
511
+ queued = entry;
512
+ } else {
513
+ queued ??= inFile;
514
+ }
515
+ raced = 0;
516
+ if (why !== said) {
517
+ wait.log?.(`waits for ${keys.join(", ")} of ${gate}: ${why}`);
518
+ said = why;
519
+ }
520
+ await sleep(Math.max(0, Math.min(poll, wait.deadline - now())));
521
+ await fetchForLocks(opts.cwd);
522
+ }
523
+ }
524
+
525
+ /** Take run `me` out of `gate`'s queue. Never throws. */
526
+ async function leaveQueue(gate: string, me: string, cwd?: string): Promise<void> {
527
+ try {
528
+ await fetchForLocks(cwd);
529
+ for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
530
+ const { sha, file } = await readCurrent(gate, cwd);
531
+ if (!file.waiting?.[me]) return;
532
+ if (await writeAndPush(gate, sha, withoutWaiter(file, me), `Run ${me} stops waiting for rows of ${gate}`, cwd)) return;
533
+ await pause(200 + Math.floor(Math.random() * 800));
534
+ }
535
+ } catch {
536
+ // A waiter left behind is dropped once its run is gone.
537
+ }
538
+ }
539
+
295
540
  /** Let go of `keys` where run `me` still holds them. Never throws: a row left held is taken over once the run is gone. */
296
541
  export async function releaseLockRows(gate: string, keys: readonly string[], me: string, opts: { cwd?: string } = {}): Promise<boolean> {
297
542
  try {
@@ -342,12 +587,21 @@ export interface LockRowsLease {
342
587
  export async function leaseLockRows(
343
588
  gate: string,
344
589
  rows: readonly LockRow[],
345
- opts: LockRowsOptions & { holder?: LockRowHolder } = {},
346
- ): Promise<{ ok: true; lease: LockRowsLease; tookOver: LockRowHolder[] } | { ok: false; held: HeldLockRow[]; message: string }> {
590
+ opts: LockRowsOptions & { holder?: LockRowHolder; wait?: LockRowsWait } = {},
591
+ ): Promise<{ ok: true; lease: LockRowsLease; tookOver: LockRowHolder[]; waitedSeconds?: number; waited?: boolean } | { ok: false; held: HeldLockRow[]; message: string; timedOut?: true }> {
347
592
  const holder = opts.holder ?? lockRowHolder(process.env);
348
593
  const keys = sortedLockRows(rows).map((r) => r.key);
349
594
  const lease: LockRowsLease = { gate, holder, keys, release: () => (keys.length === 0 ? Promise.resolve(true) : releaseLockRows(gate, keys, holder.run, { ...(opts.cwd ? { cwd: opts.cwd } : {}) })) };
350
595
  if (keys.length === 0) return { ok: true, lease, tookOver: [] };
596
+ if (opts.wait) {
597
+ try {
598
+ const waited = await waitLockRows(gate, rows, holder, opts.wait, opts);
599
+ return { ok: true, lease, tookOver: waited.tookOver, ...(waited.waited ? { waited: true, waitedSeconds: waited.waitedSeconds } : {}) };
600
+ } catch (err) {
601
+ if (err instanceof LockWaitTimeoutError) return { ok: false, held: err.held, message: err.message, timedOut: true };
602
+ throw err;
603
+ }
604
+ }
351
605
  const taken = await takeLockRows(gate, rows, holder, opts);
352
606
  if (!taken.ok) return { ok: false, held: taken.held, message: describeHeldLockRows(taken.held, rows) };
353
607
  return { ok: true, lease, tookOver: taken.tookOver };
@@ -1,6 +1,6 @@
1
1
  /**
2
- * The plans an op-waves `pr-review` wave records for a pull request's head
3
- * (#3684, #3865): `_wave-plans/<name>/<head>.json` on `chant/lifecycle`,
2
+ * The plans an op-waves `pr-review` or `pull-request` wave records for a
3
+ * pull request's head (#3684, #3865, #4630): `_wave-plans/<name>/<head>.json` on `chant/lifecycle`,
4
4
  * written by `chant run wave --record-plans` (`../op/op-waves-run.ts`) and read
5
5
  * after the merge, where the review of that head approves the digests it
6
6
  * planned and only those (`../op/gate-review.ts`).
@@ -22,7 +22,28 @@ export interface HeadPlans {
22
22
  /** The commit the waves were planned at: a pull request's head. */
23
23
  head: string;
24
24
  timestamp: string;
25
- waves: Array<{ wave: number; name: string; digest: string }>;
25
+ waves: Array<HeadPlanWave>;
26
+ }
27
+
28
+ /**
29
+ * One wave's plan at the head. `changes` and `destructive` (#4630) are the
30
+ * plan's facts a gate policy reads: some run changes something, some run's
31
+ * plan is destructive. A record from an older chant has neither, and a
32
+ * reader takes such a wave as changing.
33
+ */
34
+ export interface HeadPlanWave {
35
+ wave: number;
36
+ name: string;
37
+ digest: string;
38
+ changes?: boolean;
39
+ destructive?: boolean;
40
+ /**
41
+ * The digest of the wave's change set at the head, when its plans file
42
+ * gave one (#4630, `pull-request` waves). The document is stored under
43
+ * `_change-sets/`, and the approval status checks the pull request's own
44
+ * approval against it.
45
+ */
46
+ changeSet?: string;
26
47
  }
27
48
 
28
49
  /** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
@@ -50,9 +71,16 @@ export function parseHeadPlans(text: string | null): HeadPlans | null {
50
71
  const waves: HeadPlans["waves"] = [];
51
72
  for (const w of r.waves) {
52
73
  if (w === null || typeof w !== "object") return null;
53
- const { wave, name, digest } = w as Record<string, unknown>;
74
+ const { wave, name, digest, changes, destructive, changeSet } = w as Record<string, unknown>;
54
75
  if (typeof wave !== "number" || typeof name !== "string" || typeof digest !== "string") return null;
55
- waves.push({ wave, name, digest });
76
+ waves.push({
77
+ wave,
78
+ name,
79
+ digest,
80
+ ...(typeof changes === "boolean" ? { changes } : {}),
81
+ ...(typeof destructive === "boolean" ? { destructive } : {}),
82
+ ...(typeof changeSet === "string" && changeSet !== "" ? { changeSet } : {}),
83
+ });
56
84
  }
57
85
  return { version: 1, name: r.name, head: r.head, timestamp: r.timestamp, waves };
58
86
  }
@@ -0,0 +1,134 @@
1
+ /**
2
+ * #4630: `<product>/approval` on an open pull request's head, from the
3
+ * policy at base, the head's recorded plans and the forge's reviews, on
4
+ * fake GitHub, GitLab and Forgejo forges.
5
+ */
6
+
7
+ import { describe, expect, test } from "vitest";
8
+ import { assertProductWords } from "../ci-product-words";
9
+ import type { HeadPlans } from "../lifecycle/wave-plans";
10
+ import { parseHeadPlans } from "../lifecycle/wave-plans";
11
+ import type { ForgeStatus, PrApprovalResult } from "../pr-forge";
12
+ import { approvalStatusOf, headWaveHolds, postApprovalStatus, postOpenApprovalStatuses } from "./approval-status";
13
+ import type { OpWavesSpec } from "./op-waves";
14
+ import type { OpWaveShowAtBase } from "./op-waves-run";
15
+
16
+ const HEAD = "a".repeat(40);
17
+ const BASE = "b".repeat(40);
18
+
19
+ const SPEC: OpWavesSpec = {
20
+ name: "plywood-up",
21
+ op: "plywood-up",
22
+ plan: ["./bin/plan", "{target}", "{plan}"],
23
+ waves: [
24
+ { name: "dev", runs: [{ target: "dev" }], gate: "never", approval: "pr-review" },
25
+ { name: "prod", runs: [{ target: "prod" }], gate: "on-destructive", approval: "pr-review" },
26
+ ],
27
+ };
28
+
29
+ /** The spec as it stands at base: what the policy is read from. */
30
+ const atBase = (spec: OpWavesSpec | null): OpWaveShowAtBase => () => ({ sha: BASE, text: spec ? JSON.stringify(spec) : null });
31
+
32
+ const plans = (waves: HeadPlans["waves"]): HeadPlans => ({ version: 1, name: SPEC.name, head: HEAD, timestamp: "2026-10-28T00:00:00Z", waves });
33
+
34
+ function fakeForge(kind: "github" | "gitlab" | "forgejo", approval: PrApprovalResult) {
35
+ const statuses: Array<{ sha: string; status: ForgeStatus }> = [];
36
+ const asked: Array<{ pr: number; head: string }> = [];
37
+ const forge = {
38
+ kind,
39
+ runUrl: "https://ci.example/run/1",
40
+ async prApproved(pr: number, head: string) {
41
+ asked.push({ pr, head });
42
+ return approval;
43
+ },
44
+ async setStatus(sha: string, status: ForgeStatus) {
45
+ statuses.push({ sha, status });
46
+ },
47
+ async openPullRequests() {
48
+ return [
49
+ { number: 3, head: "feature", headSha: HEAD, base: "main", baseSha: BASE, fork: false },
50
+ { number: 4, head: "fork-branch", headSha: "c".repeat(40), base: "main", fork: true },
51
+ ];
52
+ },
53
+ };
54
+ return { forge, statuses, asked };
55
+ }
56
+
57
+ const approved: PrApprovalResult = { passed: true, reason: "approved", approvers: ["github:lee"], excluded: [] };
58
+ const notApproved: PrApprovalResult = { passed: false, reason: "no writer other than the author approved a1b2c3d4", approvers: [], excluded: [] };
59
+
60
+ describe("which waves the gate will hold (#4630)", () => {
61
+ test("never holds nothing, on-destructive holds a destructive plan, always holds a change; no facts read as a change", () => {
62
+ expect(headWaveHolds("never", { changes: true, destructive: true })).toBe(false);
63
+ expect(headWaveHolds("on-destructive", { changes: true, destructive: false })).toBe(false);
64
+ expect(headWaveHolds("on-destructive", { changes: true, destructive: true })).toBe(true);
65
+ expect(headWaveHolds("always", { changes: false })).toBe(false);
66
+ expect(headWaveHolds("always", {})).toBe(true);
67
+ });
68
+
69
+ test("the plans record keeps the facts, and an older record without them still parses", () => {
70
+ const text = JSON.stringify(plans([{ wave: 1, name: "dev", digest: "d1", changes: true, destructive: false }]));
71
+ expect(parseHeadPlans(text)?.waves[0]).toEqual({ wave: 1, name: "dev", digest: "d1", changes: true, destructive: false });
72
+ expect(parseHeadPlans(JSON.stringify(plans([{ wave: 1, name: "dev", digest: "d1" }])))?.waves[0]).toEqual({ wave: 1, name: "dev", digest: "d1" });
73
+ });
74
+ });
75
+
76
+ describe("<product>/approval on the head (#4630)", () => {
77
+ for (const kind of ["github", "gitlab", "forgejo"] as const) {
78
+ test(`pending while a held wave has no approving review, success once it has (${kind})`, async () => {
79
+ const recorded = plans([
80
+ { wave: 1, name: "dev", digest: "d1", changes: true, destructive: true },
81
+ { wave: 2, name: "prod", digest: "d2", changes: true, destructive: true },
82
+ ]);
83
+ const words = assertProductWords({ product: "plywood" });
84
+ const waiting = fakeForge(kind, notApproved);
85
+ const status = await postApprovalStatus({ spec: SPEC, specFile: "waves.json", forge: waiting.forge, pr: 3, head: HEAD, base: BASE, show: atBase(SPEC), readPlans: async () => recorded }, words);
86
+ expect(status).toMatchObject({ state: "pending", waits: [2] });
87
+ expect(waiting.statuses).toEqual([{ sha: HEAD, status: { context: "plywood/approval", state: "pending", description: expect.stringContaining("wave 2 wait"), url: "https://ci.example/run/1" } }]);
88
+ expect(waiting.asked).toEqual([{ pr: 3, head: HEAD }]);
89
+
90
+ const done = fakeForge(kind, approved);
91
+ const ok = await postApprovalStatus({ spec: SPEC, specFile: "waves.json", forge: done.forge, pr: 3, head: HEAD, base: BASE, show: atBase(SPEC), readPlans: async () => recorded }, words);
92
+ expect(ok).toMatchObject({ state: "success", approvers: ["github:lee"] });
93
+ expect(done.statuses[0]!.status.description).toContain("by github:lee");
94
+ });
95
+ }
96
+
97
+ test("a plan no gate holds is success without asking for reviews", async () => {
98
+ const { forge, asked } = fakeForge("github", notApproved);
99
+ const status = await approvalStatusOf({
100
+ spec: SPEC,
101
+ specFile: "waves.json",
102
+ forge,
103
+ pr: 3,
104
+ head: HEAD,
105
+ base: BASE,
106
+ show: atBase(SPEC),
107
+ readPlans: async () => plans([{ wave: 1, name: "dev", digest: "d1", changes: true }, { wave: 2, name: "prod", digest: "d2", changes: true, destructive: false }]),
108
+ });
109
+ expect(status).toMatchObject({ state: "success", waits: [] });
110
+ expect(asked).toEqual([]);
111
+ });
112
+
113
+ test("the policy is read at base: a head that loosens it still waits", async () => {
114
+ const loosened: OpWavesSpec = { ...SPEC, waves: SPEC.waves.map((w) => ({ ...w, gate: "never" as const })) };
115
+ const strict: OpWavesSpec = { ...SPEC, waves: SPEC.waves.map((w) => ({ ...w, gate: "always" as const })) };
116
+ const { forge } = fakeForge("forgejo", notApproved);
117
+ const status = await approvalStatusOf({ spec: loosened, specFile: "waves.json", forge, pr: 3, head: HEAD, base: BASE, show: atBase(strict), readPlans: async () => plans([{ wave: 1, name: "dev", digest: "d1", changes: true }, { wave: 2, name: "prod", digest: "d2", changes: true }]) });
118
+ expect(status).toMatchObject({ state: "pending", waits: [1, 2] });
119
+ });
120
+
121
+ test("plans not recorded yet are pending; no pr-review wave at base is success", async () => {
122
+ const { forge } = fakeForge("github", approved);
123
+ expect(await approvalStatusOf({ spec: SPEC, specFile: "waves.json", forge, pr: 3, head: HEAD, base: BASE, show: atBase(SPEC), readPlans: async () => null })).toMatchObject({ state: "pending", description: expect.stringContaining("not recorded yet") });
124
+ const ledgerOnly: OpWavesSpec = { ...SPEC, waves: SPEC.waves.map(({ approval: _a, ...w }) => w) };
125
+ expect(await approvalStatusOf({ spec: SPEC, specFile: "waves.json", forge, pr: 3, head: HEAD, base: BASE, show: atBase(ledgerOnly), readPlans: async () => null })).toMatchObject({ state: "success" });
126
+ });
127
+
128
+ test("--open posts on every open merge request from the repository, and leaves forks out", async () => {
129
+ const { forge, statuses } = fakeForge("gitlab", notApproved);
130
+ const done = await postOpenApprovalStatuses({ spec: SPEC, specFile: "waves.json", forge, branch: "main", show: atBase(SPEC), readPlans: async () => plans([{ wave: 2, name: "prod", digest: "d2", changes: true, destructive: true }]) }, assertProductWords({ product: "plywood" }));
131
+ expect(done.posted.map((p) => p.pr)).toEqual([3]);
132
+ expect(statuses.map((s) => s.sha)).toEqual([HEAD]);
133
+ });
134
+ });