@intentius/chant 0.124.109 → 0.124.110

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 (338) hide show
  1. package/dist/__golden__/wave-loop/fan-out-applied.json +12 -6
  2. package/dist/__golden__/wave-loop/fan-out-apply-fails.json +8 -4
  3. package/dist/__golden__/wave-loop/fan-out-gated.json +4 -2
  4. package/dist/__golden__/wave-loop/fan-out-no-members.json +16 -8
  5. package/dist/__golden__/wave-loop/fan-out-plan-fails.json +8 -4
  6. package/dist/__golden__/wave-loop/fan-out-same-root.json +4 -2
  7. package/dist/agent-facts.d.ts +130 -0
  8. package/dist/agent-facts.js +196 -0
  9. package/dist/change-risk.d.ts +216 -0
  10. package/dist/change-risk.js +304 -0
  11. package/dist/change-set.d.ts +8 -0
  12. package/dist/ci-agent-alert.d.ts +139 -0
  13. package/dist/ci-agent-alert.js +342 -0
  14. package/dist/ci-agent-triggers.d.ts +152 -0
  15. package/dist/ci-agent-triggers.js +232 -0
  16. package/dist/ci-agent-verify-failed.d.ts +149 -0
  17. package/dist/ci-agent-verify-failed.js +191 -0
  18. package/dist/ci-agent.d.ts +136 -8
  19. package/dist/ci-agent.js +353 -26
  20. package/dist/ci-comment-commands.d.ts +8 -0
  21. package/dist/ci-comment-commands.js +17 -1
  22. package/dist/ci-comment-reject.d.ts +70 -0
  23. package/dist/ci-comment-reject.js +135 -0
  24. package/dist/ci-comment-replies.d.ts +3 -1
  25. package/dist/ci-comment-replies.js +6 -0
  26. package/dist/ci-estate/delivery.d.ts +25 -3
  27. package/dist/ci-estate/delivery.js +28 -9
  28. package/dist/ci-estate/page.d.ts +7 -3
  29. package/dist/ci-estate/page.js +19 -4
  30. package/dist/ci-estate/rows.d.ts +14 -2
  31. package/dist/ci-estate/rows.js +9 -1
  32. package/dist/ci-estate.d.ts +5 -2
  33. package/dist/ci-estate.js +3 -2
  34. package/dist/ci-handover.d.ts +2 -7
  35. package/dist/ci-handover.js +3 -20
  36. package/dist/ci-jobs.d.ts +6 -0
  37. package/dist/ci-jobs.js +17 -0
  38. package/dist/ci-note-commands.d.ts +2 -0
  39. package/dist/ci-note-commands.js +12 -1
  40. package/dist/ci-product-words.d.ts +151 -1
  41. package/dist/ci-product-words.js +1390 -3
  42. package/dist/ci-product.d.ts +100 -4
  43. package/dist/ci-product.js +99 -3
  44. package/dist/ci-respond-run.d.ts +9 -0
  45. package/dist/ci-respond-run.js +35 -4
  46. package/dist/ci-respond-summary-env.d.ts +56 -0
  47. package/dist/ci-respond-summary-env.js +81 -0
  48. package/dist/ci-respond-summary.d.ts +103 -0
  49. package/dist/ci-respond-summary.js +243 -0
  50. package/dist/ci-respond.d.ts +4 -2
  51. package/dist/ci-respond.js +4 -2
  52. package/dist/cli/command-group.js +1 -1
  53. package/dist/cli/commands/lint.js +21 -3
  54. package/dist/cli/handlers/agent.js +49 -4
  55. package/dist/cli/handlers/approve.js +3 -1
  56. package/dist/cli/handlers/build.d.ts +97 -1
  57. package/dist/cli/handlers/build.js +251 -3
  58. package/dist/cli/handlers/fan-out.js +55 -0
  59. package/dist/cli/handlers/graph.d.ts +14 -0
  60. package/dist/cli/handlers/graph.js +58 -3
  61. package/dist/cli/handlers/lifecycle-health.d.ts +7 -0
  62. package/dist/cli/handlers/lifecycle-health.js +47 -9
  63. package/dist/cli/handlers/lifecycle.js +4 -1
  64. package/dist/cli/handlers/notify-relay.d.ts +2 -2
  65. package/dist/cli/handlers/notify-relay.js +67 -7
  66. package/dist/cli/handlers/pipeline-agent.d.ts +30 -0
  67. package/dist/cli/handlers/pipeline-agent.js +255 -0
  68. package/dist/cli/handlers/pipeline-artifacts.d.ts +39 -0
  69. package/dist/cli/handlers/pipeline-artifacts.js +203 -0
  70. package/dist/cli/handlers/pipeline.d.ts +16 -0
  71. package/dist/cli/handlers/pipeline.js +112 -0
  72. package/dist/cli/handlers/pr-comment.js +4 -0
  73. package/dist/cli/handlers/pr-notes.js +4 -1
  74. package/dist/cli/handlers/pr.d.ts +20 -0
  75. package/dist/cli/handlers/pr.js +114 -11
  76. package/dist/cli/handlers/promote.js +792 -47
  77. package/dist/cli/handlers/reject.d.ts +84 -0
  78. package/dist/cli/handlers/reject.js +216 -0
  79. package/dist/cli/handlers/replan.d.ts +54 -0
  80. package/dist/cli/handlers/replan.js +177 -0
  81. package/dist/cli/handlers/run-generate.d.ts +5 -0
  82. package/dist/cli/handlers/run-generate.js +31 -4
  83. package/dist/cli/handlers/run-wave.js +15 -2
  84. package/dist/cli/handlers/run.js +4 -2
  85. package/dist/cli/handlers/stage.d.ts +35 -0
  86. package/dist/cli/handlers/stage.js +90 -0
  87. package/dist/cli/lsp/server.js +4 -0
  88. package/dist/cli/main.js +88 -8
  89. package/dist/cli/parse-args.js +35 -2
  90. package/dist/cli/registry.d.ts +12 -0
  91. package/dist/components/auto-release.d.ts +2 -0
  92. package/dist/components/auto-release.js +1 -0
  93. package/dist/components/capability.d.ts +40 -0
  94. package/dist/components/cli-support.d.ts +21 -1
  95. package/dist/components/cli-support.js +28 -6
  96. package/dist/components/component.d.ts +23 -4
  97. package/dist/components/component.schema.json +28 -0
  98. package/dist/components/declared-reads.d.ts +44 -4
  99. package/dist/components/declared-reads.js +80 -3
  100. package/dist/components/discover.d.ts +8 -0
  101. package/dist/components/discover.js +1 -1
  102. package/dist/components/driver.d.ts +13 -0
  103. package/dist/components/driver.js +23 -2
  104. package/dist/components/environment-sets.d.ts +229 -0
  105. package/dist/components/environment-sets.js +338 -0
  106. package/dist/components/fan-out-canary.d.ts +47 -0
  107. package/dist/components/fan-out-canary.js +58 -0
  108. package/dist/components/fan-out-run.d.ts +17 -0
  109. package/dist/components/fan-out-run.js +14 -1
  110. package/dist/components/fan-out-support.d.ts +7 -0
  111. package/dist/components/fan-out-support.js +1 -1
  112. package/dist/components/groups.d.ts +8 -1
  113. package/dist/components/groups.js +19 -1
  114. package/dist/components/index.d.ts +5 -2
  115. package/dist/components/index.js +4 -1
  116. package/dist/components/pr-cost.d.ts +28 -0
  117. package/dist/components/pr-cost.js +53 -0
  118. package/dist/components/pr-pipeline.d.ts +33 -0
  119. package/dist/components/pr-pipeline.js +32 -5
  120. package/dist/components/pr-policy.d.ts +33 -2
  121. package/dist/components/pr-policy.js +5 -2
  122. package/dist/components/pr-risk.d.ts +42 -0
  123. package/dist/components/pr-risk.js +74 -0
  124. package/dist/components/product-pipeline.d.ts +43 -0
  125. package/dist/components/product-pipeline.js +67 -1
  126. package/dist/components/promote.d.ts +6 -0
  127. package/dist/components/promote.js +13 -0
  128. package/dist/components/release-compile.js +3 -1
  129. package/dist/components/release-gate.d.ts +6 -1
  130. package/dist/components/release-gate.js +10 -2
  131. package/dist/components/step-environments.d.ts +236 -0
  132. package/dist/components/step-environments.js +392 -0
  133. package/dist/components/upstream-replan.d.ts +201 -0
  134. package/dist/components/upstream-replan.js +249 -0
  135. package/dist/components/verify-step.d.ts +30 -0
  136. package/dist/components/verify-step.js +27 -0
  137. package/dist/components/wave-plan.js +6 -2
  138. package/dist/config-environments.d.ts +4 -2
  139. package/dist/control/dispatch.d.ts +15 -0
  140. package/dist/control/dispatch.js +28 -4
  141. package/dist/cost-estimate.d.ts +188 -0
  142. package/dist/cost-estimate.js +363 -0
  143. package/dist/drift-record.d.ts +36 -0
  144. package/dist/drift-record.js +44 -0
  145. package/dist/engine-facts.d.ts +105 -0
  146. package/dist/engine-facts.js +111 -0
  147. package/dist/exit-codes.d.ts +4 -3
  148. package/dist/exit-codes.js +4 -3
  149. package/dist/flag-params.d.ts +2 -2
  150. package/dist/flag-params.js +9 -4
  151. package/dist/floor-table.data.js +53 -0
  152. package/dist/forge-token-vars.d.ts +12 -0
  153. package/dist/forge-token-vars.js +25 -0
  154. package/dist/gate-decision.d.ts +3 -1
  155. package/dist/gate-decision.js +3 -1
  156. package/dist/gated-waves.d.ts +2 -0
  157. package/dist/gated-waves.js +1 -0
  158. package/dist/graph-ir.d.ts +30 -0
  159. package/dist/graph-ir.js +33 -1
  160. package/dist/graph-refs.d.ts +26 -0
  161. package/dist/graph-refs.js +34 -3
  162. package/dist/graph-schema/graph.schema.json +136 -0
  163. package/dist/health.d.ts +65 -0
  164. package/dist/health.js +62 -0
  165. package/dist/lexicon.d.ts +188 -1
  166. package/dist/lifecycle/disruption.d.ts +14 -1
  167. package/dist/lifecycle/disruption.js +5 -1
  168. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  169. package/dist/lifecycle/gate-change-set.js +2 -1
  170. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  171. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  172. package/dist/lifecycle/gate-rejection.js +93 -0
  173. package/dist/lifecycle/gate-seal.d.ts +3 -3
  174. package/dist/lifecycle/gate-seal.js +5 -5
  175. package/dist/lifecycle/observe.d.ts +17 -0
  176. package/dist/lifecycle/observe.js +10 -1
  177. package/dist/lifecycle/release-cut.js +4 -0
  178. package/dist/lifecycle/release-ledger.d.ts +8 -0
  179. package/dist/lifecycle/release-risk.d.ts +137 -0
  180. package/dist/lifecycle/release-risk.js +214 -0
  181. package/dist/lifecycle/release-store.d.ts +9 -0
  182. package/dist/lifecycle/release-store.js +4 -0
  183. package/dist/lifecycle/stage-log.d.ts +85 -0
  184. package/dist/lifecycle/stage-log.js +141 -0
  185. package/dist/lint/canary-checks.d.ts +31 -0
  186. package/dist/lint/canary-checks.js +45 -0
  187. package/dist/lint/rule.d.ts +1 -0
  188. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  190. package/dist/lint/rules/index.d.ts +1 -0
  191. package/dist/lint/rules/index.js +3 -0
  192. package/dist/notify-relay-repo.d.ts +54 -0
  193. package/dist/notify-relay-repo.js +84 -0
  194. package/dist/notify-relay.d.ts +53 -3
  195. package/dist/notify-relay.js +96 -3
  196. package/dist/notify.d.ts +57 -1
  197. package/dist/notify.js +7 -1
  198. package/dist/notify.schema.json +61 -3
  199. package/dist/observation.d.ts +34 -0
  200. package/dist/observation.js +14 -1
  201. package/dist/op/activities/review-agent.d.ts +39 -2
  202. package/dist/op/activities/review-agent.js +88 -5
  203. package/dist/op/agent-permit.d.ts +88 -0
  204. package/dist/op/agent-permit.js +97 -0
  205. package/dist/op/gate-approval-base.d.ts +8 -0
  206. package/dist/op/gate-approval-base.js +9 -0
  207. package/dist/op/gate-approval.d.ts +30 -1
  208. package/dist/op/gate-approval.js +23 -2
  209. package/dist/op/gate-quorum.d.ts +114 -8
  210. package/dist/op/gate-quorum.js +198 -21
  211. package/dist/op/gate-reject.d.ts +79 -0
  212. package/dist/op/gate-reject.js +96 -0
  213. package/dist/op/gate-summary.js +1 -1
  214. package/dist/op/gate.d.ts +28 -3
  215. package/dist/op/gate.js +55 -13
  216. package/dist/op/generate-pipeline.d.ts +15 -1
  217. package/dist/op/generate-pipeline.js +32 -5
  218. package/dist/op/index.d.ts +11 -6
  219. package/dist/op/index.js +10 -5
  220. package/dist/op/local-executor.d.ts +2 -0
  221. package/dist/op/local-executor.js +23 -4
  222. package/dist/op/op-waves-after-plan.d.ts +23 -0
  223. package/dist/op/op-waves-after-plan.js +12 -1
  224. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  225. package/dist/op/op-waves-capability-spec.js +46 -6
  226. package/dist/op/op-waves-capability.d.ts +21 -13
  227. package/dist/op/op-waves-capability.js +22 -59
  228. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  229. package/dist/op/op-waves-environment-sets.js +82 -0
  230. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  231. package/dist/op/op-waves-quorum-warnings.js +90 -0
  232. package/dist/op/op-waves-release-port.d.ts +7 -0
  233. package/dist/op/op-waves-release-port.js +15 -3
  234. package/dist/op/op-waves-release.d.ts +15 -0
  235. package/dist/op/op-waves-release.js +15 -0
  236. package/dist/op/op-waves-run.d.ts +37 -3
  237. package/dist/op/op-waves-run.js +141 -18
  238. package/dist/op/op-waves-soak.d.ts +57 -0
  239. package/dist/op/op-waves-soak.js +111 -0
  240. package/dist/op/op-waves-split.d.ts +4 -0
  241. package/dist/op/op-waves-split.js +4 -0
  242. package/dist/op/op-waves.d.ts +67 -4
  243. package/dist/op/op-waves.js +71 -3
  244. package/dist/pipeline/agent-ajv.d.ts +4 -0
  245. package/dist/pipeline/agent-ajv.js +14 -0
  246. package/dist/pipeline/agent-steps.d.ts +329 -0
  247. package/dist/pipeline/agent-steps.js +602 -0
  248. package/dist/pipeline/artifacts.d.ts +264 -0
  249. package/dist/pipeline/artifacts.js +425 -0
  250. package/dist/pipeline/diff.d.ts +45 -0
  251. package/dist/pipeline/diff.js +177 -0
  252. package/dist/pipeline/fold.d.ts +43 -0
  253. package/dist/pipeline/fold.js +140 -0
  254. package/dist/pipeline/generate.d.ts +52 -0
  255. package/dist/pipeline/generate.js +120 -0
  256. package/dist/pipeline/product.d.ts +225 -0
  257. package/dist/pipeline/product.js +257 -0
  258. package/dist/pipeline/promote.d.ts +404 -0
  259. package/dist/pipeline/promote.js +694 -0
  260. package/dist/pipeline/read.d.ts +37 -0
  261. package/dist/pipeline/read.js +58 -0
  262. package/dist/pipeline/rendered.d.ts +25 -0
  263. package/dist/pipeline/rendered.js +53 -0
  264. package/dist/pipeline/soak-checks.d.ts +80 -0
  265. package/dist/pipeline/soak-checks.js +254 -0
  266. package/dist/pipeline/soak-gate.d.ts +97 -0
  267. package/dist/pipeline/soak-gate.js +176 -0
  268. package/dist/pipeline/soak-sources.d.ts +17 -0
  269. package/dist/pipeline/soak-sources.js +42 -0
  270. package/dist/pipeline/soak.d.ts +260 -0
  271. package/dist/pipeline/soak.js +378 -0
  272. package/dist/pipeline/spec.d.ts +724 -0
  273. package/dist/pipeline/spec.js +567 -0
  274. package/dist/pipeline/stage-ledger.d.ts +187 -0
  275. package/dist/pipeline/stage-ledger.js +185 -0
  276. package/dist/pipeline/stage-waves.d.ts +114 -0
  277. package/dist/pipeline/stage-waves.js +161 -0
  278. package/dist/pipeline/stages.d.ts +64 -0
  279. package/dist/pipeline/stages.js +174 -0
  280. package/dist/pipeline/verify-rollback.d.ts +277 -0
  281. package/dist/pipeline/verify-rollback.js +393 -0
  282. package/dist/pipeline.d.ts +142 -0
  283. package/dist/pipeline.js +143 -0
  284. package/dist/pr-loop.d.ts +22 -0
  285. package/dist/pr-loop.js +8 -0
  286. package/dist/pr-plan-note.d.ts +15 -1
  287. package/dist/pr-plan-note.js +8 -0
  288. package/dist/pr-post.d.ts +31 -0
  289. package/dist/pr-post.js +89 -0
  290. package/dist/release-floors.d.ts +1 -1
  291. package/dist/release-floors.js +1 -1
  292. package/dist/report-store/audit.schema.json +50 -0
  293. package/dist/report-store/dora.schema.json +331 -0
  294. package/dist/report-store/estate.schema.json +96 -0
  295. package/dist/report-store/run.schema.json +14 -0
  296. package/dist/report-store.d.ts +151 -0
  297. package/dist/report-store.js +344 -0
  298. package/dist/run-event.d.ts +7 -2
  299. package/dist/wave-runtime.mjs +458 -404
  300. package/dist/workspace/catalog-edges.js +3 -3
  301. package/dist/workspace/change-set.schema.json +4 -0
  302. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  303. package/dist/workspace/ci-cloud-identity.js +30 -0
  304. package/dist/workspace/ci-run.js +17 -2
  305. package/dist/workspace/ci-secrets.d.ts +3 -1
  306. package/dist/workspace/ci-secrets.js +7 -1
  307. package/dist/workspace/compose-graph.d.ts +1 -1
  308. package/dist/workspace/compose-graph.js +3 -1
  309. package/dist/workspace/declaration.d.ts +27 -0
  310. package/dist/workspace/declaration.js +35 -0
  311. package/dist/workspace/declaration.schema.json +56 -0
  312. package/dist/workspace/graph-cli.js +26 -0
  313. package/dist/workspace/graph.schema.json +5 -1
  314. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  315. package/dist/workspace/identity-gate-rule.js +2 -2
  316. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  317. package/dist/workspace/identity-reject-rule.js +24 -0
  318. package/dist/workspace/identity.d.ts +3 -0
  319. package/dist/workspace/identity.js +2 -1
  320. package/dist/workspace/nested-graph.js +2 -0
  321. package/dist/workspace/pr-report.schema.json +65 -0
  322. package/dist/workspace/promotion-order.d.ts +19 -4
  323. package/dist/workspace/promotion-order.js +26 -4
  324. package/dist/workspace/release-train.d.ts +14 -0
  325. package/dist/workspace/release-train.js +32 -0
  326. package/dist/workspace/run-event.schema.json +2 -2
  327. package/dist/workspace/stack-read-edges.d.ts +19 -0
  328. package/dist/workspace/stack-read-edges.js +54 -0
  329. package/dist/workspace/status-gates.d.ts +51 -1
  330. package/dist/workspace/status-gates.js +60 -0
  331. package/dist/workspace/status-stages.d.ts +223 -0
  332. package/dist/workspace/status-stages.js +279 -0
  333. package/dist/workspace/status.d.ts +45 -1
  334. package/dist/workspace/status.js +109 -5
  335. package/dist/workspace/status.schema.json +283 -2
  336. package/dist/workspace/trust/seal.d.ts +7 -0
  337. package/dist/workspace/trust/seal.js +9 -0
  338. package/package.json +5 -1
@@ -0,0 +1,694 @@
1
+ /**
2
+ * What a promote reads from the folded pipeline (#5324).
3
+ *
4
+ * `chant components promote --to <stage>` in a member with a pipeline reads
5
+ * it at the default branch's tip (`./read.ts`'s `promoteBase`):
6
+ *
7
+ * 1. A held stage, or one in a freeze window, refuses with exit 3 and says
8
+ * until when.
9
+ * 2. `--from` defaults to the stage before; a promote that skips a stage is
10
+ * refused, as with `environments`. `--allow-skip` passes only through
11
+ * each skipped stage's gate: gate `<stage>-skip` under the pipeline's
12
+ * op, bound to the promoted digest, unless that stage's gate policy is
13
+ * `never`. A held skipped stage refuses too. Each skip is recorded on
14
+ * `_gates/<pipeline>/applied.jsonl`, which spends the approval it went
15
+ * through.
16
+ * 3. The target stage's gate: gate `<stage>` under the pipeline's op, bound
17
+ * to the release's digest (or the promoted digests'), with the stage's
18
+ * quorum rules. A policy of `never` lets it through; `always` and
19
+ * `on-destructive` wait, since a promote has no plan to call destructive
20
+ * before it is gated.
21
+ *
22
+ * Before the gates, the soak of the stage promoted from (#5326,
23
+ * `./soak-gate.ts`): while it holds, the promote records the soak's pending
24
+ * fact (gate `<from>-soak`) and exits 3 with the time left. Its clock starts
25
+ * at the newest apply of the promoted components in the `from` stage's
26
+ * release ledger. Then the soak of each canary stage `to` follows (#5327,
27
+ * `canaryStagesBefore`), through the canary's own gate `<canary>-soak` and
28
+ * its own clock: a promote from a later stage reads it again, and a skip
29
+ * past the canary finds no apply there and holds until a person ends the
30
+ * canary's soak early.
31
+ *
32
+ * A gate that waits records its pending fact and the promote exits 3, as a
33
+ * gated run does; `chant approve <pipeline> <gate> --plan <digest>` passes it.
34
+ *
35
+ * A stage that names `after` (#5353) follows those stages: `--from`
36
+ * defaults to the first it names and must be one of them, and the stage
37
+ * opens for a release only once that release applied in each, read from
38
+ * the stage log (`../lifecycle/stage-log.ts`); the first stage counts when
39
+ * its ledger holds a deploy of the release's commit. Until then the promote
40
+ * exits 3. `--allow-skip` takes each stage still missing through its skip
41
+ * gate. A stage with `queue: "replace"` takes one release at a time: a
42
+ * newer release waiting replaces an older one, and a release that waits
43
+ * while another is in the stage exits 3 until that one finishes.
44
+ *
45
+ * A release rejected at a stage's gate (#5354, `chant reject <pipeline>
46
+ * <stage>`) does not enter the stage, and is not skipped past it: the
47
+ * promote exits 8 and says who rejected it and why, before any approval is
48
+ * read, so more approvals never clear it. A rejection counts by the proof
49
+ * rules the gate's approvals count by (`../op/gate-reject.ts`): the gate's
50
+ * `approval` mode (a `sealed` gate counts sealed approvals and rejections
51
+ * only), the workspace's `identity.gates` rule, and the gate's rules.
52
+ * The urgent path (#5355), `promote --urgent --release <label>` into a stage
53
+ * whose gate declares `urgent: { role }`: the stage's gate passes on one
54
+ * approval of gate `<stage>-urgent`, bound to the release's digest, from an
55
+ * approver who holds the role and whose approval a seal against the signers
56
+ * at base proves. A plain `chant approve` line never counts, whatever the
57
+ * stage's approval mode. Holds, freeze windows and a pause still refuse it.
58
+ * It skips no stage, `--allow-skip` or not, and the release must have
59
+ * succeeded in every stage upstream of the one promoted to
60
+ * ({@link urgentUpstreamStages}).
61
+ *
62
+ * A promote under a release reads the change risk its cut carries (#5387,
63
+ * `../lifecycle/release-risk.ts`) at each gate whose stage sets
64
+ * `holds.risk`. Over the stage's threshold the gate takes the risk's
65
+ * `quorum` rules on top of its own, and a gate whose policy is `never` waits
66
+ * for an approval of its own. The gate then counts only people's approvals,
67
+ * and a permit that reads the score only from a person `.chant/trust.json`
68
+ * at base proves. A release with no record, or a stage with no `holds.risk`,
69
+ * has the gate it had before.
70
+ */
71
+ import { createHash } from "node:crypto";
72
+ import { approveCommand, evaluateGate } from "../op/gate.js";
73
+ import { canaryStagesBefore, pipelineTracksStages, stageUpstreams } from "./spec.js";
74
+ import { replacedIn, stageQueueOf, succeededIn } from "../lifecycle/stage-log.js";
75
+ import { gateRejections, rejectionLine } from "../op/gate-reject.js";
76
+ import { gateSealRefusal } from "../lifecycle/gate-seal.js";
77
+ import { agentStepGateRule, agentStepRiskLevels, readStageAgentAnswers, stageAgentPolicyInput, stageAgentStepsHold, stageAgentSteps } from "./agent-steps.js";
78
+ import { stageHeldAt, stageHeldLine } from "./stages.js";
79
+ import { stageRiskContext, stageRiskRead } from "../lifecycle/release-risk.js";
80
+ import { agentStepRiskReasons } from "../change-risk.js";
81
+ import { soakAtGate, stageSoakGate } from "./soak-gate.js";
82
+ const NO_PROOF = { signers: { base: null, signersPath: ".chant/allowed_signers", active: false, signers: [], problems: [] }, roles: {} };
83
+ /** The digest a stage gate binds when there is no release: the components and digests promoted, in order. */
84
+ export function promotedDigest(items) {
85
+ const canonical = JSON.stringify([...items].map((i) => [i.component, i.digest]).sort());
86
+ return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
87
+ }
88
+ /**
89
+ * The order and holds part, before anything is planned: the stage promoted
90
+ * from, or a stop. `undefined` when the pipeline has no stage `to`, so the
91
+ * pipeline has nothing to say about it.
92
+ */
93
+ export function pipelinePromoteSource(input) {
94
+ const { spec, to, now } = input;
95
+ const names = spec.stages.map((s) => s.name);
96
+ const toAt = names.indexOf(to);
97
+ if (toAt < 0)
98
+ return undefined;
99
+ const held = stageHeldAt(spec.stages[toAt], now);
100
+ if (held)
101
+ return { exitCode: 3, code: "pipeline-stage-held", message: stageHeldLine(held), hint: held.until ? `Promote again after ${held.until}.` : "Lift the hold in the pipeline's config and merge the change." };
102
+ // #5355: --urgent takes the stage's urgent rule, so a stage without one has no urgent path.
103
+ if (input.urgent && !spec.stages[toAt].gate?.urgent) {
104
+ return { exitCode: 1, code: "pipeline-no-urgent-rule", message: `stage "${to}" of the pipeline "${spec.name}" declares no urgent rule, so --urgent has no gate to pass`, hint: `Promote without --urgent, or declare gate.urgent: { role } on the stage.` };
105
+ }
106
+ // #5353: a stage that names its upstream stages opens on the release's outcome in each, read once the release is known.
107
+ const after = spec.stages[toAt].after;
108
+ if (after !== undefined) {
109
+ const from = input.from ?? after[0];
110
+ if (!after.includes(from)) {
111
+ return {
112
+ exitCode: 1,
113
+ code: "pipeline-from-not-upstream",
114
+ message: `stage "${to}" follows ${after.join(", ")} in the pipeline "${spec.name}", so a release is promoted into it from one of them, not from ${from}`,
115
+ hint: `Promote from ${after[0]}, or leave out --from.`,
116
+ };
117
+ }
118
+ return { from, skipped: [], upstreams: [...after] };
119
+ }
120
+ const from = input.from ?? (toAt > 0 ? names[toAt - 1] : undefined);
121
+ if (from === undefined) {
122
+ return { exitCode: 1, code: "promote-no-previous-environment", message: `"${to}" is the first stage of the pipeline "${spec.name}" (${names.join(", ")}): a merge applies it, so there is nothing to promote from` };
123
+ }
124
+ const fromAt = names.indexOf(from);
125
+ const skipped = fromAt >= 0 && fromAt < toAt - 1 ? spec.stages.slice(fromAt + 1, toAt) : [];
126
+ if (input.urgent) {
127
+ if (skipped.length > 0) {
128
+ return {
129
+ exitCode: 1,
130
+ code: "pipeline-urgent-skips",
131
+ message: `promoting ${from} to ${to} skips ${skipped.map((s) => s.name).join(", ")}, and the urgent path skips no stage`,
132
+ hint: `Promote the release to ${skipped[0].name} first.`,
133
+ };
134
+ }
135
+ }
136
+ if (skipped.length > 0 && !input.allowSkip) {
137
+ return {
138
+ exitCode: 1,
139
+ code: "promote-skips-environment",
140
+ message: `promoting ${from} to ${to} skips ${skipped.map((s) => s.name).join(", ")} in the pipeline's stage order (${names.join(", ")})`,
141
+ hint: `Promote to ${skipped[0].name} first, or pass --allow-skip to go through the gate of each stage skipped.`,
142
+ };
143
+ }
144
+ for (const s of skipped) {
145
+ const h = stageHeldAt(s, now);
146
+ if (h)
147
+ return { exitCode: 3, code: "pipeline-stage-held", message: `${stageHeldLine(h)}; a skip goes through it, so nothing is promoted past it either` };
148
+ }
149
+ return { from, skipped };
150
+ }
151
+ /**
152
+ * The reader of the rejections at a stage's gates (#5354): the pipeline's
153
+ * rejection ledger read once, each rejection that does not count noted in
154
+ * `lines`, and the stop for the first gate a standing rejection names.
155
+ */
156
+ function rejectionReader(input) {
157
+ const { spec, port, digest, lines } = input;
158
+ const proof = input.proof ?? NO_PROOF;
159
+ let rejectionLedger;
160
+ const rejectedAt = async (stage, gate) => {
161
+ rejectionLedger ?? (rejectionLedger = (await port.readRejections?.(spec.name)) ?? []);
162
+ const identity = await input.identityOf(gate);
163
+ const found = gateRejections(rejectionLedger, {
164
+ gate,
165
+ planDigest: digest,
166
+ environment: stage.name,
167
+ ...(input.releaseDigest !== undefined ? { releaseDigest: input.releaseDigest } : {}),
168
+ mode: stage.gate?.approval ?? "ledger",
169
+ ...(stage.gate?.quorum ? { quorum: stage.gate.quorum } : {}),
170
+ signers: proof.signers,
171
+ roles: proof.roles,
172
+ identity: identity ? (identity.refusesRejection ?? (() => `the workspace's rule for gate ${gate} judges no rejection here`)) : null,
173
+ });
174
+ for (const { rejection, why } of found.ignored)
175
+ lines.push(`${spec.name} ${gate}: the rejection by ${rejection.rejectedBy} does not count: ${why}`);
176
+ return found.standing;
177
+ };
178
+ return async (stage, gates) => {
179
+ for (const gate of gates) {
180
+ const standing = await rejectedAt(stage, gate);
181
+ if (standing.length === 0)
182
+ continue;
183
+ const what = input.releaseDigest !== undefined ? `release ${input.releaseDigest}` : `the promotion ${digest}`;
184
+ return {
185
+ passed: false,
186
+ exitCode: 8,
187
+ code: "pipeline-release-rejected",
188
+ message: `${what} was rejected at ${spec.name} ${gate}, so it does not enter stage ${stage.name}: ${standing.map(rejectionLine).join("; ")}`,
189
+ hint: "A rejection stands for this release, and more approvals do not clear it. Cut a new release with the change it asks for, and promote that one.",
190
+ lines: [...lines],
191
+ };
192
+ }
193
+ return undefined;
194
+ };
195
+ }
196
+ /**
197
+ * The rejections a promote reads before the soak (#5326, #5354): those at
198
+ * each skipped stage's gate and skip gate, then at the target stage's gate
199
+ * (and its urgent gate under `--urgent`). A rejection stops the promote
200
+ * with exit 8 before any soak is read or recorded, so a rejected release
201
+ * never leaves a soak's pending fact. {@link pipelinePromoteGates} reads them
202
+ * again, with the same answer, before its approvals.
203
+ */
204
+ export async function pipelinePromoteRejected(input) {
205
+ const rules = {};
206
+ const identityOf = async (gate) => (gate in rules ? rules[gate] : (rules[gate] = (await input.port.approvalRule?.(gate)) ?? null));
207
+ const rejected = rejectionReader({ ...input, identityOf, lines: [] });
208
+ for (const stage of input.skipped) {
209
+ const stop = await rejected(stage, [stage.name, `${stage.name}-skip`]);
210
+ if (stop)
211
+ return stop;
212
+ }
213
+ const stage = input.spec.stages.find((s) => s.name === input.to);
214
+ if (!stage)
215
+ return undefined;
216
+ return rejected(stage, input.urgent ? [stage.name, urgentGateName(stage.name)] : [stage.name]);
217
+ }
218
+ /**
219
+ * The gates part, once the promote knows what it deploys: each skipped
220
+ * stage's skip gate, then the target stage's gate. `digest` is the release's
221
+ * digest, or {@link promotedDigest}. Records each skip it passes.
222
+ */
223
+ export async function pipelinePromoteGates(input) {
224
+ const { spec, port, digest } = input;
225
+ const proof = input.proof ?? NO_PROOF;
226
+ const now = input.now.toISOString();
227
+ const lines = [];
228
+ const rules = {};
229
+ // #3163: the workspace's identity.gates rule for a gate, read once.
230
+ const identityOf = async (gate) => (gate in rules ? rules[gate] : (rules[gate] = (await port.approvalRule?.(gate)) ?? null));
231
+ // #5354: under `sealed`, only an approval whose seal verifies at base counts, as a wave's sealed gate counts it.
232
+ const ruleFor = async (stage, gate) => {
233
+ const own = await identityOf(gate);
234
+ if (stage.gate?.approval !== "sealed")
235
+ return own;
236
+ const sealed = { requirement: { gate, class: null }, refuses: (a) => gateSealRefusal(proof.signers, a) };
237
+ return own ? { requirement: own.requirement, refuses: (a) => own.refuses(a) ?? sealed.refuses(a) } : sealed;
238
+ };
239
+ // #5354: the rejections of the pipeline's gates, read once.
240
+ const rejected = rejectionReader({ ...input, identityOf, lines });
241
+ // #5387: each stage's reading of the release's risk, once, its line printed whatever the gate does.
242
+ const reads = new Map();
243
+ const riskOf = (stage) => {
244
+ if (!reads.has(stage.name)) {
245
+ const read = stageRiskRead(spec, stage.name, input.risk, stage.name === input.to ? (input.agentRisk ?? []) : []);
246
+ reads.set(stage.name, read);
247
+ if (read)
248
+ lines.push(read.line);
249
+ }
250
+ return reads.get(stage.name);
251
+ };
252
+ const riskOver = (stage) => riskOf(stage)?.risk?.over === true;
253
+ const check = async (stage, gate) => {
254
+ const read = riskOf(stage);
255
+ // #5358: a stage with agent steps counts a person's approval only, and refuses an agent's by name.
256
+ const agentRead = stageAgentSteps(spec, stage.name).length > 0 && gate === stage.name;
257
+ const own = await ruleFor(stage, gate);
258
+ const rule = agentRead ? bothRules(own, agentStepGateRule(gate)) : own;
259
+ // #5387: an over risk adds its rules; a gate that read a record counts people only, and a permit that reads it only from a proven one.
260
+ const rules = [...(stage.gate?.quorum ?? []), ...(read?.rules ?? [])];
261
+ const context = read ? stageRiskContext(read) : undefined;
262
+ const approval = read?.risk
263
+ ? { ...(rules.length > 0 ? { quorum: rules } : {}), mode: "enforce", risk: read.settings, ...(context ? { context } : {}) }
264
+ : rules.length > 0
265
+ ? { quorum: rules, mode: "enforce" }
266
+ : agentRead
267
+ ? { mode: "log-only" }
268
+ : undefined;
269
+ return evaluateGate(port, {
270
+ rule,
271
+ op: spec.name,
272
+ gate,
273
+ planDigest: digest,
274
+ environment: stage.name,
275
+ now,
276
+ description: gate.endsWith("-skip") ? `skip stage ${stage.name} of the pipeline ${spec.name}` : `promote into stage ${stage.name} of the pipeline ${spec.name}`,
277
+ ...(input.gitSha ? { gitSha: input.gitSha } : {}),
278
+ ...(approval ? { approval } : {}),
279
+ });
280
+ };
281
+ // #5358: an approval the gate's rule refused is named, so a wait says why it did not count.
282
+ const waiting = (gate, stage, refused = []) => ({
283
+ passed: false,
284
+ lines: [...lines, ...refused.map((r) => `${spec.name} ${gate}: an approval does not count: ${r.reason}`)],
285
+ exitCode: 3,
286
+ code: "pipeline-gate-waiting",
287
+ message: `${spec.name} ${gate} waits for an approval of ${digest}${reads.get(stage.name)?.risk?.over ? `; ${reads.get(stage.name).line}` : ""}`,
288
+ hint: approveCommand(spec.name, gate, stage.name, digest, stage.gate?.approval === "sealed"),
289
+ });
290
+ if (input.urgent && input.skipped.length > 0) {
291
+ return { passed: false, exitCode: 1, code: "pipeline-urgent-skips", message: `the urgent path skips no stage, and ${input.skipped.map((s) => s.name).join(", ")} would be skipped`, hint: `Promote the release to ${input.skipped[0].name} first.` };
292
+ }
293
+ for (const stage of input.skipped) {
294
+ const gate = `${stage.name}-skip`;
295
+ // #5354: a release rejected at a stage is not skipped past it either.
296
+ const stop = await rejected(stage, [stage.name, gate]);
297
+ if (stop)
298
+ return stop;
299
+ if (stage.gate?.policy === "never" && !riskOver(stage)) {
300
+ await port.appendApplied?.({ version: 1, kind: "applied", op: spec.name, gate, planDigest: digest, approvedAt: now, approvedBy: "gate-policy-never", timestamp: now, ...(input.gitSha ? { commit: input.gitSha } : {}) });
301
+ lines.push(`skipped ${stage.name}: its gate never waits`);
302
+ continue;
303
+ }
304
+ const got = await check(stage, gate);
305
+ if (!got.satisfied)
306
+ return waiting(gate, stage);
307
+ await port.appendApplied?.({ version: 1, kind: "applied", op: spec.name, gate, planDigest: digest, approvedAt: got.resolution.timestamp, approvedBy: got.resolution.resolvedBy, timestamp: now, ...(input.gitSha ? { commit: input.gitSha } : {}) });
308
+ lines.push(`skipped ${stage.name} through ${spec.name} ${gate}, approved by ${got.resolution.resolvedBy}`);
309
+ }
310
+ const stage = spec.stages.find((s) => s.name === input.to);
311
+ // #5354: a rejection stops the stage whatever its policy, before any approval is read.
312
+ // #5355: on the urgent path too, at the stage's gate or its urgent gate.
313
+ const stop = await rejected(stage, input.urgent ? [stage.name, urgentGateName(stage.name)] : [stage.name]);
314
+ if (stop)
315
+ return stop;
316
+ if (input.urgent) {
317
+ const got = await pipelineUrgentGate({ spec, to: stage.name, digest, port, ...(input.releaseDigest !== undefined ? { releaseDigest: input.releaseDigest } : {}), ...(input.gitSha ? { gitSha: input.gitSha } : {}), now: input.now });
318
+ if (!got.passed)
319
+ return { ...got, lines: [...lines, ...(got.lines ?? [])] };
320
+ return { passed: true, lines: [...lines, ...got.lines], urgent: { approval: got.approval, role: got.role } };
321
+ }
322
+ // #5358: `chant build` refuses never on a stage whose policy reads agent answers; a spec written around the build still waits.
323
+ const answersReachPolicy = stageAgentSteps(spec, stage.name).length > 0 && stage.gate?.holds?.policy === true;
324
+ if (stage.gate?.policy === "never" && !riskOver(stage) && !answersReachPolicy) {
325
+ lines.push(`stage ${stage.name}: its gate never waits`);
326
+ return { passed: true, lines };
327
+ }
328
+ const got = await check(stage, stage.name);
329
+ if (!got.satisfied)
330
+ return waiting(stage.name, stage, got.refused ?? []);
331
+ lines.push(`stage ${stage.name}: ${spec.name} ${stage.name} approved by ${got.resolution.resolvedBy}`);
332
+ return { passed: true, lines };
333
+ }
334
+ const releaseName = (digest, label) => (label ? `${label} (${digest})` : digest);
335
+ /**
336
+ * Take a release into stage `to` (#5353): the upstream stages a stage with
337
+ * `after` waits on, its queue, and then {@link pipelinePromoteGates}. With
338
+ * a pipeline that declares neither `after` nor `queue`, this is
339
+ * {@link pipelinePromoteGates} and writes no stage line.
340
+ *
341
+ * - Each upstream the release has not applied in stops the promote with
342
+ * exit 3, or with `allowSkip` goes through that stage's skip gate.
343
+ * - Under `queue: "replace"`, a release replaced at the stage is refused
344
+ * (exit 1). A newer release replaces each older one waiting; one older
345
+ * than a release waiting is replaced itself and refused. The release
346
+ * then waits, its gate is read, and while another release is in the
347
+ * stage it exits 3. A release already in the stage carries on without
348
+ * its gate read again.
349
+ * - Once the gate passes, the release's `entered` line is written; the
350
+ * caller writes its `finished` line with {@link pipelineStageFinished}.
351
+ */
352
+ export async function pipelineStageEntry(input) {
353
+ const { spec, to, digest, log } = input;
354
+ // #5355: under --urgent the stage's urgent rule stands in for its gate, after its rejections, and nothing is skipped.
355
+ let urgent;
356
+ const gates = async (skipped) => {
357
+ const got = await pipelinePromoteGates({ spec, to, skipped, digest, port: input.port, ...(input.release ? { releaseDigest: input.release.releaseDigest } : {}), ...(input.release?.risk ? { risk: input.release.risk } : {}), ...(input.actor ? { actor: input.actor } : {}), ...(input.gitSha ? { gitSha: input.gitSha } : {}), ...(input.proof ? { proof: input.proof } : {}), ...(input.urgent ? { urgent: true } : {}), ...(input.agentRisk?.length ? { agentRisk: input.agentRisk } : {}), now: input.now });
358
+ if (got.passed && got.urgent)
359
+ urgent = got.urgent;
360
+ return got;
361
+ };
362
+ const withUrgent = (out) => (out.passed && urgent ? { ...out, urgent } : out);
363
+ if (!pipelineTracksStages(spec))
364
+ return withUrgent(await gates(input.skipped));
365
+ const timestamp = input.now.toISOString();
366
+ const stage = spec.stages.find((s) => s.name === to);
367
+ const base = {
368
+ version: 1,
369
+ op: spec.name,
370
+ stage: to,
371
+ digest,
372
+ timestamp,
373
+ ...(input.release?.label ? { label: input.release.label } : {}),
374
+ ...(input.release?.cutAt ? { cutAt: input.release.cutAt } : {}),
375
+ ...(input.actor ? { actor: input.actor } : {}),
376
+ ...(input.runId ? { runId: input.runId } : {}),
377
+ };
378
+ const lines = await log.read(spec.name);
379
+ const name = releaseName(digest, input.release?.label);
380
+ const skipped = [...input.skipped];
381
+ if (input.upstreams) {
382
+ if (!input.release) {
383
+ return {
384
+ passed: false,
385
+ exitCode: 1,
386
+ code: "pipeline-join-needs-release",
387
+ message: `stage "${to}" follows ${input.upstreams.join(", ")}, and opens only for a release that applied in each, so the promote names one`,
388
+ hint: `Promote with --release <label|digest>; \`chant release list\` lists them.`,
389
+ };
390
+ }
391
+ const first = spec.stages[0].name;
392
+ const applied = (up) => (up === first ? input.firstStageCommits?.has(input.release.commit) === true : succeededIn(lines, up, digest));
393
+ const missing = input.upstreams.filter((up) => !applied(up));
394
+ if (missing.length > 0 && !input.allowSkip) {
395
+ return {
396
+ passed: false,
397
+ exitCode: 3,
398
+ code: "pipeline-upstream-waiting",
399
+ message: `stage "${to}" opens once release ${name} applied in ${input.upstreams.join(", ")}; it has not applied in ${missing.join(", ")} yet`,
400
+ hint: `Promote it to ${missing.join(" and ")} first, or pass --allow-skip to go through the gate of each stage missing.`,
401
+ };
402
+ }
403
+ for (const up of missing) {
404
+ const s = spec.stages.find((x) => x.name === up);
405
+ const h = stageHeldAt(s, input.now);
406
+ if (h)
407
+ return { passed: false, exitCode: 3, code: "pipeline-stage-held", message: `${stageHeldLine(h)}; a skip goes through it, so nothing is promoted past it either` };
408
+ skipped.push(s);
409
+ }
410
+ }
411
+ if (stage.queue === "replace") {
412
+ const replaced = replacedIn(lines, to, digest);
413
+ if (replaced) {
414
+ return {
415
+ passed: false,
416
+ exitCode: 1,
417
+ code: "pipeline-release-replaced",
418
+ message: `release ${name} was replaced at stage "${to}" by ${releaseName(replaced.by, replaced.byLabel)} at ${replaced.timestamp}, so it does not enter that stage`,
419
+ hint: `Promote ${replaced.byLabel ?? replaced.by} or a newer release into ${to}.`,
420
+ };
421
+ }
422
+ const queue = stageQueueOf(lines, to);
423
+ if (queue.inStage?.digest === digest) {
424
+ // The release in the stage: its gate passed when it entered, and its deploy carries on.
425
+ return { passed: true, lines: [`stage ${to}: release ${name} is in the stage; its deploy carries on`], entered: queue.inStage };
426
+ }
427
+ const newerThan = (other) => (input.release?.cutAt && other.cutAt ? Date.parse(input.release.cutAt) >= Date.parse(other.cutAt) : true);
428
+ const others = queue.waiting.filter((w) => w.digest !== digest);
429
+ const newer = others.find((w) => !newerThan(w));
430
+ if (newer) {
431
+ await log.append({ ...base, kind: "replaced", by: newer.digest, ...(newer.label ? { byLabel: newer.label } : {}) });
432
+ return {
433
+ passed: false,
434
+ exitCode: 1,
435
+ code: "pipeline-release-replaced",
436
+ message: `release ${releaseName(newer.digest, newer.label)}, cut after ${name}, waits for stage "${to}", so ${name} is replaced and does not enter it`,
437
+ hint: `Promote ${newer.label ?? newer.digest} into ${to}.`,
438
+ };
439
+ }
440
+ const notes = [];
441
+ for (const w of others) {
442
+ await log.append({ ...w, kind: "replaced", timestamp, by: digest, ...(input.release?.label ? { byLabel: input.release.label } : {}) });
443
+ notes.push(`stage ${to}: release ${releaseName(w.digest, w.label)}, which waited, is replaced by ${name}`);
444
+ }
445
+ if (!queue.waiting.some((w) => w.digest === digest))
446
+ await log.append({ ...base, kind: "waiting" });
447
+ const got = await gates(skipped);
448
+ if (!got.passed)
449
+ return got;
450
+ if (queue.inStage) {
451
+ return {
452
+ passed: false,
453
+ exitCode: 3,
454
+ code: "pipeline-stage-busy",
455
+ message: `stage "${to}" takes one release at a time, and release ${releaseName(queue.inStage.digest, queue.inStage.label)} is in it since ${queue.inStage.timestamp}; ${name} waits for it to finish`,
456
+ hint: "Run the same promote again once that release's deploy has finished.",
457
+ };
458
+ }
459
+ const entered = { ...base, kind: "entered" };
460
+ await log.append(entered);
461
+ return withUrgent({ passed: true, lines: [...notes, ...got.lines], entered });
462
+ }
463
+ const got = await gates(skipped);
464
+ if (!got.passed)
465
+ return got;
466
+ const entered = { ...base, kind: "entered" };
467
+ await log.append(entered);
468
+ return withUrgent({ passed: true, lines: got.lines, entered });
469
+ }
470
+ /** Write the `finished` line for a release that entered a stage (#5353): `applied` when its deploy did, else `failed`. */
471
+ export async function pipelineStageFinished(log, entered, result, now) {
472
+ await log.append({ ...entered, kind: "finished", result, timestamp: now.toISOString() });
473
+ }
474
+ /** The gate an urgent promote into `stage` is approved at (#5355). */
475
+ export function urgentGateName(stage) {
476
+ return `${stage}-urgent`;
477
+ }
478
+ /**
479
+ * The stages a release must have succeeded in before an urgent promote into
480
+ * `to` (#5355), in the pipeline's order. A stage with `after` (#5353) takes
481
+ * the stages it names and every stage those follow, by
482
+ * {@link stageUpstreams}. A stage without `after` takes every stage before it.
483
+ */
484
+ export function urgentUpstreamStages(spec, to) {
485
+ const at = spec.stages.findIndex((s) => s.name === to);
486
+ if (at < 0)
487
+ return [];
488
+ const stage = spec.stages[at];
489
+ if (stage.after === undefined)
490
+ return spec.stages.slice(0, at).map((s) => s.name);
491
+ const seen = new Set();
492
+ const visit = (name) => {
493
+ if (seen.has(name))
494
+ return;
495
+ seen.add(name);
496
+ for (const up of stageUpstreams(spec, name))
497
+ visit(up);
498
+ };
499
+ for (const up of stage.after)
500
+ visit(up);
501
+ return spec.stages.map((s) => s.name).filter((n) => seen.has(n));
502
+ }
503
+ /**
504
+ * The stages upstream of `to` ({@link urgentUpstreamStages}) in which the
505
+ * release has not succeeded, each with the components it lacks there
506
+ * (#5355). `missingIn` answers for one stage. Empty when it succeeded in
507
+ * every one.
508
+ */
509
+ export async function pipelineUrgentUpstream(input) {
510
+ const out = [];
511
+ for (const stage of urgentUpstreamStages(input.spec, input.to).map((name) => ({ name }))) {
512
+ const missing = await input.missingIn(stage.name);
513
+ if (missing.length > 0)
514
+ out.push({ stage: stage.name, missing });
515
+ }
516
+ return out;
517
+ }
518
+ /** The refusal for a release that has not succeeded in every stage before the one an urgent promote goes to. */
519
+ export function urgentUpstreamStop(release, missing) {
520
+ return {
521
+ exitCode: 1,
522
+ code: "pipeline-urgent-upstream",
523
+ message: `release ${release} has not succeeded in ${missing.map((m) => `${m.stage} (${m.missing.join(", ")})`).join("; ")}, and the urgent path takes only a release every upstream stage ran`,
524
+ hint: "Promote the release through each earlier stage first.",
525
+ };
526
+ }
527
+ /**
528
+ * The urgent rule of stage `to` (#5355), in place of its gate: one approval
529
+ * of `<stage>-urgent` bound to the release's digest, from an approver the
530
+ * port's judge proves and gives the rule's role. The quorum rule is
531
+ * `{ count: 1, roles: [role], proven: true }`, so an unproven line never
532
+ * counts. The approval is spent on `_gates/<pipeline>/applied.jsonl`.
533
+ */
534
+ export async function pipelineUrgentGate(input) {
535
+ const { spec, port, digest } = input;
536
+ const stage = spec.stages.find((s) => s.name === input.to);
537
+ const rule = stage?.gate?.urgent;
538
+ if (!stage || !rule)
539
+ return { passed: false, exitCode: 1, code: "pipeline-no-urgent-rule", message: `stage "${input.to}" of the pipeline "${spec.name}" declares no urgent rule` };
540
+ const gate = urgentGateName(stage.name);
541
+ const now = input.now.toISOString();
542
+ const got = await evaluateGate(port, {
543
+ op: spec.name,
544
+ gate,
545
+ planDigest: digest,
546
+ environment: stage.name,
547
+ ...(input.releaseDigest !== undefined ? { releaseDigest: input.releaseDigest } : {}),
548
+ now,
549
+ description: `urgent promote into stage ${stage.name} of the pipeline ${spec.name}: one proven approval from ${rule.role}`,
550
+ ...(input.gitSha ? { gitSha: input.gitSha } : {}),
551
+ approval: { quorum: [{ count: 1, roles: [rule.role], proven: true }], mode: "enforce" },
552
+ });
553
+ if (!got.satisfied) {
554
+ return {
555
+ passed: false,
556
+ exitCode: 3,
557
+ code: "pipeline-gate-waiting",
558
+ message: `${spec.name} ${gate} waits for one proven approval from ${rule.role} of ${digest}`,
559
+ hint: approveCommand(spec.name, gate, stage.name, digest, true),
560
+ };
561
+ }
562
+ const approval = got.resolution;
563
+ await port.appendApplied?.({ version: 1, kind: "applied", op: spec.name, gate, planDigest: digest, approvedAt: approval.timestamp, approvedBy: approval.resolvedBy, timestamp: now, ...(input.gitSha ? { commit: input.gitSha } : {}) });
564
+ return { passed: true, approval, role: rule.role, lines: [`stage ${stage.name}: urgent, ${spec.name} ${gate} approved by ${approval.resolvedBy} (${rule.role})`] };
565
+ }
566
+ /**
567
+ * Every soak in front of a promotion into `to`, in order (#5326, #5327):
568
+ * the soak of each stage promoted from (`upstreams` on a join, else
569
+ * `from`), then the soak of each canary stage `to` follows and is not one
570
+ * of those ({@link canaryStagesBefore}). Each is read through its own gate
571
+ * by {@link pipelinePromoteSoak}; the first that holds stops the promote.
572
+ * `items` gives what a stage applied of what is promoted, and `read` its
573
+ * check reader. A canary with nothing applied says so in `notes` and
574
+ * holds, since its clock cannot start. `lines` are the passed soaks' lines.
575
+ * On a hold, `heldBy` names the stage whose soak held ({@link SoakHeldBy}).
576
+ */
577
+ export async function pipelinePromoteSoaks(input) {
578
+ const sources = input.upstreams ? [...input.upstreams] : [input.from];
579
+ const canaries = canaryStagesBefore(input.spec, input.to).map((s) => s.name).filter((name) => !sources.includes(name));
580
+ const notes = [];
581
+ const lines = [];
582
+ let last;
583
+ for (const source of [...sources, ...canaries]) {
584
+ const items = await input.items(source);
585
+ if (canaries.includes(source) && items.length === 0) {
586
+ notes.push(`the canary stage ${source} has no apply of what this promote deploys, so its soak cannot start; promote through ${source} first, or end its soak early through its gate`);
587
+ }
588
+ const soak = await pipelinePromoteSoak({
589
+ spec: input.spec,
590
+ from: source,
591
+ to: input.to,
592
+ items,
593
+ digest: input.digest,
594
+ ...(input.releaseDigest !== undefined ? { releaseDigest: input.releaseDigest } : {}),
595
+ port: input.port,
596
+ read: input.read(source),
597
+ now: input.now,
598
+ ...(input.gitSha ? { gitSha: input.gitSha } : {}),
599
+ ...(input.notify ? { notify: input.notify } : {}),
600
+ });
601
+ // #5328: the stage whose soak held, which may be a canary upstream and not the stage promoted from.
602
+ if (!soak.passed)
603
+ return { ...soak, notes, heldBy: { stage: source, members: items.map((i) => i.component) } };
604
+ lines.push(...soak.lines);
605
+ last = soak;
606
+ }
607
+ return { passed: true, lines, decision: last.decision, notes };
608
+ }
609
+ /**
610
+ * The soak of stage `from` in front of a promotion into `to` (#5326): each
611
+ * promoted component is a member that applied in `from` at its source
612
+ * record's time. Passed when `from` declares no soak or is no stage of the
613
+ * pipeline.
614
+ */
615
+ export async function pipelinePromoteSoak(input) {
616
+ const stage = input.spec.stages.find((s) => s.name === input.from);
617
+ return soakAtGate({
618
+ op: input.spec.name,
619
+ gate: stageSoakGate(input.from),
620
+ soak: stage?.soak,
621
+ stage: input.from,
622
+ holds: `stage ${input.to}`,
623
+ to: input.to,
624
+ digest: input.digest,
625
+ ...(input.releaseDigest ? { releaseDigest: input.releaseDigest } : {}),
626
+ subjects: input.items.map((i) => ({ member: i.component, targets: [i.component], appliedAt: i.source.timestamp })),
627
+ ...(stage?.gate?.quorum ? { quorum: stage.gate.quorum } : {}),
628
+ port: input.port,
629
+ read: input.read,
630
+ now: input.now,
631
+ ...(input.gitSha ? { gitSha: input.gitSha } : {}),
632
+ ...(input.notify ? { notify: input.notify } : {}),
633
+ });
634
+ }
635
+ /** Both rules at once: an approval counts only when neither refuses it. */
636
+ function bothRules(a, b) {
637
+ if (!a)
638
+ return b;
639
+ return { requirement: a.requirement, refuses: (r) => a.refuses(r) ?? b.refuses(r) };
640
+ }
641
+ /**
642
+ * The agent steps part of a promote (#5358), before the stage's gate: every
643
+ * step of the stage `to` needs an answer for the release that matches its
644
+ * schema, or the promote holds (exit 3) and says why. With
645
+ * `gate.holds.policy`, `policy` runs the workspace's `ci.policy` with the
646
+ * answers as `input.agent`: a deny refuses the promote, a hold is printed,
647
+ * and the gate still waits for a person either way. Nothing here passes a
648
+ * gate.
649
+ */
650
+ export async function pipelinePromoteAgentSteps(input) {
651
+ const { spec, to } = input;
652
+ const steps = stageAgentSteps(spec, to);
653
+ if (steps.length === 0)
654
+ return { passed: true, lines: [], agent: {}, risk: [] };
655
+ if (!input.release) {
656
+ return {
657
+ passed: false,
658
+ exitCode: 1,
659
+ code: "pipeline-agent-step-no-release",
660
+ message: `stage "${to}" has agent steps, which answer for the release it takes; promote a release with --release <label|digest>`,
661
+ };
662
+ }
663
+ const name = input.release.label ?? input.release.digest;
664
+ const answers = await readStageAgentAnswers(input.port, { stage: to, release: input.release.digest });
665
+ const hold = stageAgentStepsHold(spec, to, input.release.digest, answers);
666
+ if (hold.length > 0) {
667
+ return {
668
+ passed: false,
669
+ exitCode: 3,
670
+ code: "pipeline-agent-step-holding",
671
+ message: `stage "${to}" holds for release ${name}: ${hold.join("; ")}`,
672
+ hint: `Run the stage's agent steps for the release and record them: chant pipeline agent run --stage ${to} --release ${name}, then chant pipeline agent record --stage ${to} --release ${name}`,
673
+ };
674
+ }
675
+ const agent = stageAgentPolicyInput(answers);
676
+ const lines = steps.map(([step]) => `agent step ${step}: answered for release ${name}${agent[step]?.costUsd !== undefined ? `, ${agent[step].costUsd.toFixed(2)} USD` : ""}`);
677
+ const stage = spec.stages.find((s) => s.name === to);
678
+ if (stage.gate?.holds?.policy === true && input.policy) {
679
+ const verdict = await input.policy(agent);
680
+ if (verdict?.result === "denied" || verdict?.result === "error") {
681
+ return {
682
+ passed: false,
683
+ exitCode: 1,
684
+ code: "pipeline-agent-policy-denied",
685
+ message: `stage "${to}"'s policy ${verdict.result === "denied" ? "denies" : "could not read"} release ${name} with its agent steps' answers${verdict.reasons.length ? `: ${verdict.reasons.join("; ")}` : ""}`,
686
+ };
687
+ }
688
+ if (verdict?.result === "held")
689
+ lines.push(`stage ${to}: the policy holds on its agent steps' answers${verdict.reasons.length ? ` (${verdict.reasons.join("; ")})` : ""}; the gate waits for a person's approval`);
690
+ else if (verdict)
691
+ lines.push(`stage ${to}: the policy read its agent steps' answers and passed them; the gate still waits for a person's approval`);
692
+ }
693
+ return { passed: true, lines, agent, risk: agentStepRiskReasons(agentStepRiskLevels(answers)) };
694
+ }