@intentius/chant 0.124.108 → 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 (342) 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/release.js +4 -2
  80. package/dist/cli/handlers/replan.d.ts +54 -0
  81. package/dist/cli/handlers/replan.js +177 -0
  82. package/dist/cli/handlers/run-generate.d.ts +5 -0
  83. package/dist/cli/handlers/run-generate.js +31 -4
  84. package/dist/cli/handlers/run-wave.js +15 -2
  85. package/dist/cli/handlers/run.js +4 -2
  86. package/dist/cli/handlers/stage.d.ts +35 -0
  87. package/dist/cli/handlers/stage.js +90 -0
  88. package/dist/cli/lsp/server.js +4 -0
  89. package/dist/cli/main.js +88 -8
  90. package/dist/cli/parse-args.js +35 -2
  91. package/dist/cli/registry.d.ts +12 -0
  92. package/dist/components/auto-release.d.ts +2 -0
  93. package/dist/components/auto-release.js +1 -0
  94. package/dist/components/capability.d.ts +40 -0
  95. package/dist/components/cli-support.d.ts +21 -1
  96. package/dist/components/cli-support.js +28 -6
  97. package/dist/components/component.d.ts +23 -4
  98. package/dist/components/component.schema.json +28 -0
  99. package/dist/components/declared-reads.d.ts +44 -4
  100. package/dist/components/declared-reads.js +80 -3
  101. package/dist/components/discover.d.ts +8 -0
  102. package/dist/components/discover.js +1 -1
  103. package/dist/components/driver.d.ts +13 -0
  104. package/dist/components/driver.js +23 -2
  105. package/dist/components/environment-sets.d.ts +229 -0
  106. package/dist/components/environment-sets.js +338 -0
  107. package/dist/components/fan-out-canary.d.ts +47 -0
  108. package/dist/components/fan-out-canary.js +58 -0
  109. package/dist/components/fan-out-run.d.ts +17 -0
  110. package/dist/components/fan-out-run.js +14 -1
  111. package/dist/components/fan-out-support.d.ts +7 -0
  112. package/dist/components/fan-out-support.js +1 -1
  113. package/dist/components/groups.d.ts +8 -1
  114. package/dist/components/groups.js +19 -1
  115. package/dist/components/index.d.ts +5 -2
  116. package/dist/components/index.js +4 -1
  117. package/dist/components/pr-cost.d.ts +28 -0
  118. package/dist/components/pr-cost.js +53 -0
  119. package/dist/components/pr-pipeline.d.ts +33 -0
  120. package/dist/components/pr-pipeline.js +32 -5
  121. package/dist/components/pr-policy.d.ts +33 -2
  122. package/dist/components/pr-policy.js +5 -2
  123. package/dist/components/pr-risk.d.ts +42 -0
  124. package/dist/components/pr-risk.js +74 -0
  125. package/dist/components/product-pipeline.d.ts +43 -0
  126. package/dist/components/product-pipeline.js +67 -1
  127. package/dist/components/promote.d.ts +6 -0
  128. package/dist/components/promote.js +13 -0
  129. package/dist/components/release-compile.js +3 -1
  130. package/dist/components/release-gate.d.ts +6 -1
  131. package/dist/components/release-gate.js +10 -2
  132. package/dist/components/step-environments.d.ts +236 -0
  133. package/dist/components/step-environments.js +392 -0
  134. package/dist/components/upstream-replan.d.ts +201 -0
  135. package/dist/components/upstream-replan.js +249 -0
  136. package/dist/components/verify-step.d.ts +30 -0
  137. package/dist/components/verify-step.js +27 -0
  138. package/dist/components/wave-plan.js +6 -2
  139. package/dist/config-environments.d.ts +4 -2
  140. package/dist/control/dispatch.d.ts +15 -0
  141. package/dist/control/dispatch.js +28 -4
  142. package/dist/cost-estimate.d.ts +188 -0
  143. package/dist/cost-estimate.js +363 -0
  144. package/dist/drift-record.d.ts +36 -0
  145. package/dist/drift-record.js +44 -0
  146. package/dist/engine-facts.d.ts +105 -0
  147. package/dist/engine-facts.js +111 -0
  148. package/dist/exit-codes.d.ts +4 -3
  149. package/dist/exit-codes.js +4 -3
  150. package/dist/flag-params.d.ts +2 -2
  151. package/dist/flag-params.js +9 -4
  152. package/dist/floor-table.data.js +53 -0
  153. package/dist/forge-token-vars.d.ts +12 -0
  154. package/dist/forge-token-vars.js +25 -0
  155. package/dist/gate-decision.d.ts +3 -1
  156. package/dist/gate-decision.js +3 -1
  157. package/dist/gated-waves.d.ts +2 -0
  158. package/dist/gated-waves.js +1 -0
  159. package/dist/graph-ir.d.ts +30 -0
  160. package/dist/graph-ir.js +33 -1
  161. package/dist/graph-refs.d.ts +26 -0
  162. package/dist/graph-refs.js +34 -3
  163. package/dist/graph-schema/graph.schema.json +136 -0
  164. package/dist/health.d.ts +65 -0
  165. package/dist/health.js +62 -0
  166. package/dist/lexicon.d.ts +188 -1
  167. package/dist/lifecycle/disruption.d.ts +14 -1
  168. package/dist/lifecycle/disruption.js +5 -1
  169. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  170. package/dist/lifecycle/gate-change-set.js +2 -1
  171. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  172. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  173. package/dist/lifecycle/gate-rejection.js +93 -0
  174. package/dist/lifecycle/gate-seal.d.ts +3 -3
  175. package/dist/lifecycle/gate-seal.js +5 -5
  176. package/dist/lifecycle/observe.d.ts +17 -0
  177. package/dist/lifecycle/observe.js +10 -1
  178. package/dist/lifecycle/release-cut.js +4 -0
  179. package/dist/lifecycle/release-ledger.d.ts +8 -0
  180. package/dist/lifecycle/release-risk.d.ts +137 -0
  181. package/dist/lifecycle/release-risk.js +214 -0
  182. package/dist/lifecycle/release-store.d.ts +9 -0
  183. package/dist/lifecycle/release-store.js +4 -0
  184. package/dist/lifecycle/stage-log.d.ts +85 -0
  185. package/dist/lifecycle/stage-log.js +141 -0
  186. package/dist/lint/canary-checks.d.ts +31 -0
  187. package/dist/lint/canary-checks.js +45 -0
  188. package/dist/lint/rule.d.ts +1 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  190. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  191. package/dist/lint/rules/index.d.ts +1 -0
  192. package/dist/lint/rules/index.js +3 -0
  193. package/dist/notify-relay-repo.d.ts +54 -0
  194. package/dist/notify-relay-repo.js +84 -0
  195. package/dist/notify-relay.d.ts +53 -3
  196. package/dist/notify-relay.js +96 -3
  197. package/dist/notify.d.ts +57 -1
  198. package/dist/notify.js +7 -1
  199. package/dist/notify.schema.json +61 -3
  200. package/dist/observation.d.ts +34 -0
  201. package/dist/observation.js +14 -1
  202. package/dist/op/activities/review-agent.d.ts +39 -2
  203. package/dist/op/activities/review-agent.js +88 -5
  204. package/dist/op/agent-permit.d.ts +88 -0
  205. package/dist/op/agent-permit.js +97 -0
  206. package/dist/op/gate-approval-base.d.ts +8 -0
  207. package/dist/op/gate-approval-base.js +9 -0
  208. package/dist/op/gate-approval.d.ts +30 -1
  209. package/dist/op/gate-approval.js +23 -2
  210. package/dist/op/gate-quorum.d.ts +114 -8
  211. package/dist/op/gate-quorum.js +198 -21
  212. package/dist/op/gate-reject.d.ts +79 -0
  213. package/dist/op/gate-reject.js +96 -0
  214. package/dist/op/gate-summary.js +1 -1
  215. package/dist/op/gate.d.ts +28 -3
  216. package/dist/op/gate.js +55 -13
  217. package/dist/op/generate-pipeline.d.ts +15 -1
  218. package/dist/op/generate-pipeline.js +32 -5
  219. package/dist/op/index.d.ts +11 -6
  220. package/dist/op/index.js +10 -5
  221. package/dist/op/local-executor.d.ts +2 -0
  222. package/dist/op/local-executor.js +23 -4
  223. package/dist/op/op-waves-after-plan.d.ts +23 -0
  224. package/dist/op/op-waves-after-plan.js +12 -1
  225. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  226. package/dist/op/op-waves-capability-spec.js +46 -6
  227. package/dist/op/op-waves-capability.d.ts +21 -13
  228. package/dist/op/op-waves-capability.js +22 -59
  229. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  230. package/dist/op/op-waves-environment-sets.js +82 -0
  231. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  232. package/dist/op/op-waves-quorum-warnings.js +90 -0
  233. package/dist/op/op-waves-release-port.d.ts +7 -0
  234. package/dist/op/op-waves-release-port.js +15 -3
  235. package/dist/op/op-waves-release.d.ts +15 -0
  236. package/dist/op/op-waves-release.js +15 -0
  237. package/dist/op/op-waves-run.d.ts +37 -3
  238. package/dist/op/op-waves-run.js +141 -18
  239. package/dist/op/op-waves-soak.d.ts +57 -0
  240. package/dist/op/op-waves-soak.js +111 -0
  241. package/dist/op/op-waves-split.d.ts +4 -0
  242. package/dist/op/op-waves-split.js +4 -0
  243. package/dist/op/op-waves.d.ts +67 -4
  244. package/dist/op/op-waves.js +71 -3
  245. package/dist/pipeline/agent-ajv.d.ts +4 -0
  246. package/dist/pipeline/agent-ajv.js +14 -0
  247. package/dist/pipeline/agent-steps.d.ts +329 -0
  248. package/dist/pipeline/agent-steps.js +602 -0
  249. package/dist/pipeline/artifacts.d.ts +264 -0
  250. package/dist/pipeline/artifacts.js +425 -0
  251. package/dist/pipeline/diff.d.ts +45 -0
  252. package/dist/pipeline/diff.js +177 -0
  253. package/dist/pipeline/fold.d.ts +43 -0
  254. package/dist/pipeline/fold.js +140 -0
  255. package/dist/pipeline/generate.d.ts +52 -0
  256. package/dist/pipeline/generate.js +120 -0
  257. package/dist/pipeline/product.d.ts +225 -0
  258. package/dist/pipeline/product.js +257 -0
  259. package/dist/pipeline/promote.d.ts +404 -0
  260. package/dist/pipeline/promote.js +694 -0
  261. package/dist/pipeline/read.d.ts +37 -0
  262. package/dist/pipeline/read.js +58 -0
  263. package/dist/pipeline/rendered.d.ts +25 -0
  264. package/dist/pipeline/rendered.js +53 -0
  265. package/dist/pipeline/soak-checks.d.ts +80 -0
  266. package/dist/pipeline/soak-checks.js +254 -0
  267. package/dist/pipeline/soak-gate.d.ts +97 -0
  268. package/dist/pipeline/soak-gate.js +176 -0
  269. package/dist/pipeline/soak-sources.d.ts +17 -0
  270. package/dist/pipeline/soak-sources.js +42 -0
  271. package/dist/pipeline/soak.d.ts +260 -0
  272. package/dist/pipeline/soak.js +378 -0
  273. package/dist/pipeline/spec.d.ts +724 -0
  274. package/dist/pipeline/spec.js +567 -0
  275. package/dist/pipeline/stage-ledger.d.ts +187 -0
  276. package/dist/pipeline/stage-ledger.js +185 -0
  277. package/dist/pipeline/stage-waves.d.ts +114 -0
  278. package/dist/pipeline/stage-waves.js +161 -0
  279. package/dist/pipeline/stages.d.ts +64 -0
  280. package/dist/pipeline/stages.js +174 -0
  281. package/dist/pipeline/verify-rollback.d.ts +277 -0
  282. package/dist/pipeline/verify-rollback.js +393 -0
  283. package/dist/pipeline.d.ts +142 -0
  284. package/dist/pipeline.js +143 -0
  285. package/dist/pr-loop.d.ts +22 -0
  286. package/dist/pr-loop.js +8 -0
  287. package/dist/pr-plan-note.d.ts +15 -1
  288. package/dist/pr-plan-note.js +8 -0
  289. package/dist/pr-post.d.ts +31 -0
  290. package/dist/pr-post.js +89 -0
  291. package/dist/release-floors.d.ts +1 -1
  292. package/dist/release-floors.js +1 -1
  293. package/dist/report-store/audit.schema.json +50 -0
  294. package/dist/report-store/dora.schema.json +331 -0
  295. package/dist/report-store/estate.schema.json +96 -0
  296. package/dist/report-store/run.schema.json +14 -0
  297. package/dist/report-store.d.ts +151 -0
  298. package/dist/report-store.js +344 -0
  299. package/dist/run-event.d.ts +7 -2
  300. package/dist/wave-runtime.mjs +458 -404
  301. package/dist/workspace/catalog-edges.js +3 -3
  302. package/dist/workspace/change-set.schema.json +4 -0
  303. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  304. package/dist/workspace/ci-cloud-identity.js +30 -0
  305. package/dist/workspace/ci-run.js +17 -2
  306. package/dist/workspace/ci-secrets.d.ts +3 -1
  307. package/dist/workspace/ci-secrets.js +7 -1
  308. package/dist/workspace/compose-graph.d.ts +1 -1
  309. package/dist/workspace/compose-graph.js +3 -1
  310. package/dist/workspace/declaration.d.ts +27 -0
  311. package/dist/workspace/declaration.js +35 -0
  312. package/dist/workspace/declaration.schema.json +56 -0
  313. package/dist/workspace/graph-cli.js +26 -0
  314. package/dist/workspace/graph.schema.json +5 -1
  315. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  316. package/dist/workspace/identity-gate-rule.js +2 -2
  317. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  318. package/dist/workspace/identity-reject-rule.js +24 -0
  319. package/dist/workspace/identity.d.ts +3 -0
  320. package/dist/workspace/identity.js +2 -1
  321. package/dist/workspace/nested-graph.js +2 -0
  322. package/dist/workspace/pr-report.schema.json +65 -0
  323. package/dist/workspace/promotion-order.d.ts +19 -4
  324. package/dist/workspace/promotion-order.js +26 -4
  325. package/dist/workspace/release-train.d.ts +14 -0
  326. package/dist/workspace/release-train.js +32 -0
  327. package/dist/workspace/run-event.schema.json +2 -2
  328. package/dist/workspace/stack-read-edges.d.ts +19 -0
  329. package/dist/workspace/stack-read-edges.js +54 -0
  330. package/dist/workspace/status-gates.d.ts +51 -1
  331. package/dist/workspace/status-gates.js +60 -0
  332. package/dist/workspace/status-stages.d.ts +223 -0
  333. package/dist/workspace/status-stages.js +279 -0
  334. package/dist/workspace/status.d.ts +45 -1
  335. package/dist/workspace/status.js +109 -5
  336. package/dist/workspace/status.schema.json +283 -2
  337. package/dist/workspace/train-cut.js +5 -2
  338. package/dist/workspace/train-shell.d.ts +18 -0
  339. package/dist/workspace/train-shell.js +43 -0
  340. package/dist/workspace/trust/seal.d.ts +7 -0
  341. package/dist/workspace/trust/seal.js +9 -0
  342. package/package.json +5 -1
@@ -0,0 +1,257 @@
1
+ /**
2
+ * The helpers a product writes `.chant/pipeline.ts` with (#5324).
3
+ *
4
+ * A committed TypeScript file cannot read `terragucci.yml`, `plywood.yml` or
5
+ * `yodel.config.ts` itself, so the product writes the file from its config,
6
+ * the way it renders its workflows: {@link pipelineFromConfig} maps the
7
+ * vocabulary's keys (`promotion`, `environments.<name>.gate`, `.hold`,
8
+ * `.freeze`, `.failure_tolerance`, `.risk`, `.replan_dependents`, `.publish`, `.reads`, `.after`, `.queue`,
9
+ * `.urgent`, `.pause_after_rollback`, `.hooks.<when>`, `.agent_steps`, `.on_verify_fail`,
10
+ * `approval_rules`, `release.cut`) onto a
11
+ * declaration, {@link pipelineSource} writes the file's text, and
12
+ * {@link checkPipelineFile} is what `<product> ci --check` runs: it fails
13
+ * when the committed file is not the one the config writes now.
14
+ *
15
+ * The file is generated output. Hand edits are overwritten the next time the
16
+ * product writes it, and fail the check until then.
17
+ */
18
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
19
+ import { dirname, join } from "node:path";
20
+ import { OP_WAVE_HOOK_MOMENTS } from "../op/op-waves.js";
21
+ import { foldPipelineSource, pipelineFindingLine, PIPELINE_MODULE } from "./fold.js";
22
+ import { lineDiff } from "./diff.js";
23
+ import { asPipelineSpec, PIPELINE_FILE } from "./spec.js";
24
+ /**
25
+ * The first chant whose `pipelineFromConfig` maps a stage's hooks (#5421):
26
+ * `environments.<name>.hooks.<when>` in a product's config onto a stage's
27
+ * `hooks` in `.chant/pipeline.ts`, with `<when>` one of `before-observe`,
28
+ * `before-plan`, `after-plan`, `after-gate`, `before-apply` and
29
+ * `after-apply`. A product feature-detects the key on this name before it
30
+ * writes it.
31
+ */
32
+ export const STAGE_HOOKS_KEY_FLOOR = "0.124.110";
33
+ /** A stage's `gate.holds.risk` from `environments.<name>.risk` (#5325). */
34
+ function riskOf(risk, stage) {
35
+ if (!risk)
36
+ return undefined;
37
+ const approveAbove = risk.approve_above ?? risk.approveAbove;
38
+ const rules = rulesOf(risk.approval_rules ?? risk.approvalRules);
39
+ if (rules?.some((n) => "all" in n || "any" in n))
40
+ throw new Error(`environments.${stage}.risk.approval_rules holds a group; a risk hold takes rules only`);
41
+ const out = {
42
+ ...(approveAbove !== undefined ? { approveAbove } : {}),
43
+ ...(rules && rules.length > 0 ? { quorum: rules } : {}),
44
+ };
45
+ return Object.keys(out).length > 0 ? out : undefined;
46
+ }
47
+ const SOAK_CHECK_WORDS = { on_fail: "onFail", timeout_seconds: "timeoutSeconds" };
48
+ function soakChecksOf(checks) {
49
+ return checks.map((c) => Object.fromEntries(Object.entries(c).map(([k, v]) => [SOAK_CHECK_WORDS[k] ?? k, structuredClone(v)])));
50
+ }
51
+ /** A stage's `soak` from `environments.<name>.soak` (#5326). */
52
+ function soakOf(soak) {
53
+ if (!soak)
54
+ return undefined;
55
+ return {
56
+ duration: soak.duration,
57
+ ...(soak.checks ? { checks: soakChecksOf(soak.checks) } : {}),
58
+ ...(soak.overrides ? { overrides: soak.overrides.map((o) => ({ members: [...o.members], ...(o.duration !== undefined ? { duration: o.duration } : {}), ...(o.checks ? { checks: soakChecksOf(o.checks) } : {}) })) } : {}),
59
+ };
60
+ }
61
+ /** A stage's `agentSteps` from `environments.<name>.agent_steps` (#5358). The schema is kept as written. */
62
+ function agentStepsOf(steps) {
63
+ if (!steps || Object.keys(steps).length === 0)
64
+ return undefined;
65
+ return Object.fromEntries(Object.entries(steps).map(([name, c]) => {
66
+ const keyEnv = c.key_secret ?? c.keySecret;
67
+ const maxRuns = c.max_runs ?? c.maxRuns;
68
+ const maxCostUsd = c.max_cost_usd ?? c.maxCostUsd;
69
+ return [
70
+ name,
71
+ {
72
+ prompt: c.prompt,
73
+ ...(c.reads && Object.keys(c.reads).length > 0 ? { reads: Object.fromEntries(Object.entries(c.reads).map(([k, r]) => [k, "step" in r ? { step: r.step } : { stage: r.stage, artifact: r.artifact }])) } : {}),
74
+ schema: structuredClone(c.schema),
75
+ ...(c.command ? { command: c.command } : {}),
76
+ ...(keyEnv ? { keyEnv } : {}),
77
+ ...(c.timeout !== undefined ? { timeout: c.timeout } : {}),
78
+ ...(maxRuns !== undefined ? { maxRuns } : {}),
79
+ ...(maxCostUsd !== undefined ? { maxCostUsd } : {}),
80
+ },
81
+ ];
82
+ }));
83
+ }
84
+ function rulesOf(config) {
85
+ if (config === undefined)
86
+ return undefined;
87
+ const list = Array.isArray(config) ? config : Object.keys(config).sort().map((k) => config[k]);
88
+ return list.map((r) => {
89
+ // #5354: a rule or group is named by its own `name`. A map's key stays the config's own label, so a spec written before names stays the same.
90
+ const named = r.name !== undefined ? { name: r.name } : {};
91
+ if ("all" in r)
92
+ return { ...named, all: rulesOf(r.all) ?? [] };
93
+ if ("any" in r)
94
+ return { ...named, any: rulesOf(r.any) ?? [] };
95
+ const rule = {
96
+ ...named,
97
+ count: r.count,
98
+ ...(r.roles ? { roles: [...r.roles] } : {}),
99
+ ...(r.not_author ?? r.notAuthor ? { notAuthor: true } : {}),
100
+ ...(r.targets ? { targets: [...r.targets] } : {}),
101
+ ...(r.proven ? { proven: true } : {}),
102
+ };
103
+ return rule;
104
+ });
105
+ }
106
+ const SECRET_WORDS = { forge_secret: "forgeSecret", aws_secrets_manager: "awsSecretsManager", gcp_secret_manager: "gcpSecretManager", azure_key_vault: "azureKeyVault", json_key: "jsonKey" };
107
+ /** A secret's place in camelCase, as a set's secret takes it (#5348): a product's snake_case keys renamed, a string kept. */
108
+ function secretRefOf(ref) {
109
+ if (ref === null || typeof ref !== "object" || Array.isArray(ref))
110
+ return ref;
111
+ return Object.fromEntries(Object.entries(ref).map(([k, v]) => [SECRET_WORDS[k] ?? k, v]));
112
+ }
113
+ /** A stage's `publish` from `environments.<name>.publish` (#5356). */
114
+ function publishOf(publish) {
115
+ if (!publish || Object.keys(publish).length === 0)
116
+ return undefined;
117
+ return Object.fromEntries(Object.entries(publish).map(([name, source]) => [name, (source && "secret" in source ? { secret: secretRefOf(source.secret) } : { member: source?.member, output: source?.output })]));
118
+ }
119
+ /** A stage's `hooks` from `environments.<name>.hooks.<when>` (#5421). Throws on a `<when>` that is not a moment. */
120
+ function hooksOf(hooks, stage) {
121
+ if (!hooks)
122
+ return undefined;
123
+ const out = {};
124
+ for (const [when, list] of Object.entries(hooks)) {
125
+ if (!OP_WAVE_HOOK_MOMENTS.includes(when))
126
+ throw new Error(`environments.${stage}.hooks.${when}: <when> is one of ${OP_WAVE_HOOK_MOMENTS.join(", ")}`);
127
+ if (!Array.isArray(list) || list.length === 0)
128
+ continue;
129
+ const mapped = list.map((h) => {
130
+ const onFailure = h.on_failure ?? h.onFailure;
131
+ const perRun = h.per_run ?? h.perRun;
132
+ return {
133
+ ...(h.name !== undefined ? { name: h.name } : {}),
134
+ command: [...h.command],
135
+ ...(onFailure !== undefined ? { onFailure } : {}),
136
+ ...(perRun ? { perRun: true } : {}),
137
+ ...(h.targets && h.targets.length > 0 ? { targets: [...h.targets] } : {}),
138
+ };
139
+ });
140
+ const [side, step] = when.split("-");
141
+ const group = (out[side] ?? (out[side] = {}));
142
+ group[step] = mapped;
143
+ }
144
+ return Object.keys(out).length > 0 ? out : undefined;
145
+ }
146
+ function holdOf(hold) {
147
+ if (hold === undefined || hold === false)
148
+ return undefined;
149
+ if (hold === true)
150
+ return true;
151
+ return { ...(hold.reason ? { reason: hold.reason } : {}), ...(hold.until ? { until: hold.until } : {}), ...(hold.description ? { description: hold.description } : {}) };
152
+ }
153
+ /**
154
+ * A declaration from a product's config, in the vocabulary's keys. Throws
155
+ * when `promotion` names a stage `waves` has none for, or the declaration
156
+ * does not check.
157
+ */
158
+ export function pipelineFromConfig(input) {
159
+ const stages = input.promotion.map((name) => {
160
+ const env = input.environments?.[name] ?? {};
161
+ const waves = input.waves[name];
162
+ if (!waves || waves.length === 0)
163
+ throw new Error(`promotion names ${name}, and no waves were given for it`);
164
+ const policy = env.gate ?? input.gate;
165
+ const approvalRaw = env.approval ?? input.approval;
166
+ const approval = typeof approvalRaw === "object" ? approvalRaw.mode : approvalRaw;
167
+ const quorum = rulesOf(env.approval_rules ?? env.approvalRules ?? input.approvalRules);
168
+ const risk = riskOf(env.risk, name);
169
+ const gate = { ...(policy ? { policy } : {}), ...(approval ? { approval } : {}), ...(quorum ? { quorum } : {}), ...(env.urgent ? { urgent: { role: env.urgent.role } } : {}), ...(risk ? { holds: { risk } } : {}) };
170
+ const replan = env.replan_dependents ?? env.replanDependents;
171
+ const pauseAfterRollback = env.pause_after_rollback ?? env.pauseAfterRollback;
172
+ const onVerifyFail = env.on_verify_fail ?? env.onVerifyFail;
173
+ const hold = holdOf(env.hold);
174
+ const hooks = hooksOf(env.hooks, name);
175
+ const tolerance = env.failure_tolerance ?? env.failureTolerance;
176
+ const forgeRaw = env.forge_environment ?? env.forgeEnvironment;
177
+ const forge = typeof forgeRaw === "string" ? { name: forgeRaw } : forgeRaw;
178
+ return {
179
+ name,
180
+ ...(env.canary ? { canary: true } : {}),
181
+ ...(replan && replan.length > 0 ? { replanDependents: [...replan] } : {}),
182
+ waves: waves.map((w) => structuredClone(w)),
183
+ ...(Object.keys(gate).length > 0 ? { gate } : {}),
184
+ ...(hooks ? { hooks } : {}),
185
+ ...(hold ? { hold } : {}),
186
+ ...(env.freeze && env.freeze.length > 0 ? { freeze: env.freeze.map((w) => ({ ...w })) } : {}),
187
+ ...(tolerance !== undefined ? { failureTolerance: tolerance } : {}),
188
+ ...(forge ? { forgeEnvironment: forge } : {}),
189
+ ...(publishOf(env.publish) ? { publish: publishOf(env.publish) } : {}),
190
+ ...(agentStepsOf(env.agent_steps ?? env.agentSteps) ? { agentSteps: agentStepsOf(env.agent_steps ?? env.agentSteps) } : {}),
191
+ ...(env.reads && Object.keys(env.reads).length > 0 ? { reads: Object.fromEntries(Object.entries(env.reads).map(([k, r]) => [k, { stage: r.stage, artifact: r.artifact }])) } : {}),
192
+ ...(env.after && env.after.length > 0 ? { after: [...env.after] } : {}),
193
+ ...(env.queue !== undefined ? { queue: env.queue } : {}),
194
+ ...(pauseAfterRollback ? { pauseAfterRollback: true } : {}),
195
+ ...(env.soak ? { soak: soakOf(env.soak) } : {}),
196
+ // #5328: `hold` is the default, so it is left out; any other value is written, and the check refuses one it does not know.
197
+ ...(onVerifyFail !== undefined && onVerifyFail !== "hold" ? { onVerifyFail } : {}),
198
+ };
199
+ });
200
+ const declaration = {
201
+ name: input.name,
202
+ stages,
203
+ ...(input.defaults ? { defaults: structuredClone(input.defaults) } : {}),
204
+ ...(input.release ? { release: { ...input.release } } : {}),
205
+ ...(input.control ? { control: structuredClone(input.control) } : {}),
206
+ ...(input.recheck ? { recheck: { schedule: input.recheck.schedule } } : {}),
207
+ };
208
+ asPipelineSpec(declaration);
209
+ return declaration;
210
+ }
211
+ /**
212
+ * The text of `.chant/pipeline.ts` for a declaration: a header naming the
213
+ * product and the command that writes it, the helper's import, and the
214
+ * declaration as one object literal. Folds to the declaration. Throws on a
215
+ * declaration that does not check.
216
+ */
217
+ export function pipelineSource(declaration, options) {
218
+ const { kind: _kind, ...plain } = asPipelineSpec(structuredClone(declaration));
219
+ return [
220
+ `// Written by ${options.product} from ${options.config}. Change the config and run \`${options.command}\`;`,
221
+ `// \`${options.product} ci --check\` fails while this file differs from what the config writes.`,
222
+ `import { pipeline } from "${PIPELINE_MODULE}";`,
223
+ "",
224
+ `export default pipeline(${JSON.stringify(plain, null, 2)});`,
225
+ "",
226
+ ].join("\n");
227
+ }
228
+ /**
229
+ * Whether the committed `.chant/pipeline.ts` in `dir` is `expected`, the
230
+ * text {@link pipelineSource} writes from the config now. A stale file's
231
+ * result carries the line diff and a message naming the command.
232
+ */
233
+ export function checkPipelineFile(dir, expected, options) {
234
+ const file = join(dir, PIPELINE_FILE);
235
+ if (!existsSync(file))
236
+ return { status: "missing", file: PIPELINE_FILE, message: `${PIPELINE_FILE} is missing; run \`${options.command}\` to write it` };
237
+ const actual = readFileSync(file, "utf-8");
238
+ if (actual === expected)
239
+ return { status: "current", file: PIPELINE_FILE };
240
+ const folded = foldPipelineSource(actual, PIPELINE_FILE);
241
+ const why = "finding" in folded ? `, and it does not fold: ${pipelineFindingLine(PIPELINE_FILE, folded.finding)}` : "";
242
+ return {
243
+ status: "stale",
244
+ file: PIPELINE_FILE,
245
+ message: `${PIPELINE_FILE} is not what the config writes${why}; run \`${options.command}\` and commit it`,
246
+ diff: lineDiff(actual.split("\n"), expected.split("\n")),
247
+ };
248
+ }
249
+ /** Write `text` to `.chant/pipeline.ts` in `dir`, creating `.chant`. Returns whether the file changed. */
250
+ export function writePipelineFile(dir, text) {
251
+ const file = join(dir, PIPELINE_FILE);
252
+ if (existsSync(file) && readFileSync(file, "utf-8") === text)
253
+ return false;
254
+ mkdirSync(dirname(file), { recursive: true });
255
+ writeFileSync(file, text);
256
+ return true;
257
+ }
@@ -0,0 +1,404 @@
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 { type GateLedgerPort } from "../op/gate.js";
72
+ import { type PipelineSpec, type PipelineStage } from "./spec.js";
73
+ import { type StageLine, type StageLogPort } from "../lifecycle/stage-log.js";
74
+ import { type GateSigners } from "../lifecycle/gate-seal.js";
75
+ import type { GateResolutionRecord } from "../lifecycle/gate-ledger.js";
76
+ import { type PolicyAgentAnswer, type StageAgentAnswerPort } from "./agent-steps.js";
77
+ import { type ReleaseRisk } from "../lifecycle/release-risk.js";
78
+ import { type ChangeRiskReason } from "../change-risk.js";
79
+ import { type SoakGateInput, type SoakGateOutcome } from "./soak-gate.js";
80
+ import type { SoakCheckReader } from "./soak.js";
81
+ /** A refusal or a wait, with the exit code the promote ends with. */
82
+ export interface PipelinePromoteStop {
83
+ exitCode: number;
84
+ message: string;
85
+ hint?: string;
86
+ code?: "pipeline-stage-held" | "promote-skips-environment" | "promote-no-previous-environment" | "pipeline-gate-waiting" | "pipeline-from-not-upstream" | "pipeline-join-needs-release" | "pipeline-upstream-waiting" | "pipeline-release-replaced" | "pipeline-stage-busy" | "pipeline-release-rejected" | "pipeline-stage-paused" | "pipeline-release-superseded" | "pipeline-no-urgent-rule" | "pipeline-urgent-skips" | "pipeline-urgent-upstream" | "pipeline-soak-waiting" | "pipeline-agent-step-holding" | "pipeline-agent-step-no-release" | "pipeline-agent-policy-denied";
87
+ /** Lines the promote prints before the stop, such as a rejection that does not count and why (#5354). */
88
+ lines?: string[];
89
+ }
90
+ /**
91
+ * What proves who approved or rejected at a stage's gate (#5354): the
92
+ * signers and passkeys, and the role grants, at the commit the gate is read
93
+ * at. Absent, nothing proves anyone: a `sealed` gate passes nothing, and
94
+ * counts no rejection.
95
+ */
96
+ export interface PipelineGateProof {
97
+ signers: GateSigners;
98
+ roles: Readonly<Record<string, readonly string[]>>;
99
+ }
100
+ /** The digest a stage gate binds when there is no release: the components and digests promoted, in order. */
101
+ export declare function promotedDigest(items: readonly {
102
+ component: string;
103
+ digest: string;
104
+ }[]): string;
105
+ /**
106
+ * The order and holds part, before anything is planned: the stage promoted
107
+ * from, or a stop. `undefined` when the pipeline has no stage `to`, so the
108
+ * pipeline has nothing to say about it.
109
+ */
110
+ export declare function pipelinePromoteSource(input: {
111
+ spec: PipelineSpec;
112
+ to: string;
113
+ from?: string;
114
+ allowSkip?: boolean;
115
+ /** `--urgent` (#5355): the stage must declare an urgent rule, and no stage is skipped. */
116
+ urgent?: boolean;
117
+ now: Date;
118
+ }): {
119
+ from: string;
120
+ skipped: PipelineStage[];
121
+ upstreams?: string[];
122
+ } | PipelinePromoteStop | undefined;
123
+ /** What {@link pipelinePromoteGates} decided: every gate passed, or the stop. */
124
+ export type PipelineGatesOutcome = {
125
+ passed: true;
126
+ lines: string[];
127
+ urgent?: {
128
+ approval: GateResolutionRecord;
129
+ role: string;
130
+ };
131
+ } | ({
132
+ passed: false;
133
+ } & PipelinePromoteStop);
134
+ /**
135
+ * The rejections a promote reads before the soak (#5326, #5354): those at
136
+ * each skipped stage's gate and skip gate, then at the target stage's gate
137
+ * (and its urgent gate under `--urgent`). A rejection stops the promote
138
+ * with exit 8 before any soak is read or recorded, so a rejected release
139
+ * never leaves a soak's pending fact. {@link pipelinePromoteGates} reads them
140
+ * again, with the same answer, before its approvals.
141
+ */
142
+ export declare function pipelinePromoteRejected(input: {
143
+ spec: PipelineSpec;
144
+ to: string;
145
+ skipped: readonly PipelineStage[];
146
+ digest: string;
147
+ releaseDigest?: string;
148
+ port: GateLedgerPort;
149
+ proof?: PipelineGateProof;
150
+ urgent?: boolean;
151
+ }): Promise<({
152
+ passed: false;
153
+ } & PipelinePromoteStop) | undefined>;
154
+ /**
155
+ * The gates part, once the promote knows what it deploys: each skipped
156
+ * stage's skip gate, then the target stage's gate. `digest` is the release's
157
+ * digest, or {@link promotedDigest}. Records each skip it passes.
158
+ */
159
+ export declare function pipelinePromoteGates(input: {
160
+ spec: PipelineSpec;
161
+ to: string;
162
+ skipped: readonly PipelineStage[];
163
+ digest: string;
164
+ releaseDigest?: string;
165
+ port: GateLedgerPort;
166
+ actor?: string;
167
+ gitSha?: string;
168
+ now: Date;
169
+ /** What proves an approver or a rejecter (#5354). */
170
+ proof?: PipelineGateProof;
171
+ /**
172
+ * `--urgent` (#5355): after the stage's rejections, its urgent rule
173
+ * ({@link pipelineUrgentGate}) stands in for its gate. A rejection at
174
+ * `<stage>` or at `<stage>-urgent` stops it, and nothing is skipped.
175
+ */
176
+ urgent?: boolean;
177
+ /** The change risk the release's cut carries (#5387). Absent: the release carries none, and each gate is as it was. */
178
+ risk?: ReleaseRisk;
179
+ /**
180
+ * The reasons the target stage's agent steps add to the risk its gate
181
+ * reads (#5358), from {@link pipelinePromoteAgentSteps}. They only raise
182
+ * the score. Absent: none.
183
+ */
184
+ agentRisk?: readonly ChangeRiskReason[];
185
+ }): Promise<PipelineGatesOutcome>;
186
+ /** How {@link pipelineStageEntry} ended: the stage's gate passed and the release entered, or the stop. */
187
+ export type PipelineEntryOutcome = {
188
+ passed: true;
189
+ lines: string[];
190
+ entered?: StageLine;
191
+ urgent?: {
192
+ approval: GateResolutionRecord;
193
+ role: string;
194
+ };
195
+ } | ({
196
+ passed: false;
197
+ } & PipelinePromoteStop);
198
+ /** The release a promote deploys, as the stage log names it. */
199
+ export interface PipelineEntryRelease {
200
+ releaseDigest: string;
201
+ label?: string;
202
+ /** The commit it was cut from: the first stage counts as applied when its ledger holds a deploy of it. */
203
+ commit: string;
204
+ /** When it was cut, which orders it against another release waiting. */
205
+ cutAt?: string;
206
+ /** The change risk its cut carries (#5387), which each stage gate with `holds.risk` reads. */
207
+ risk?: ReleaseRisk;
208
+ }
209
+ /**
210
+ * Take a release into stage `to` (#5353): the upstream stages a stage with
211
+ * `after` waits on, its queue, and then {@link pipelinePromoteGates}. With
212
+ * a pipeline that declares neither `after` nor `queue`, this is
213
+ * {@link pipelinePromoteGates} and writes no stage line.
214
+ *
215
+ * - Each upstream the release has not applied in stops the promote with
216
+ * exit 3, or with `allowSkip` goes through that stage's skip gate.
217
+ * - Under `queue: "replace"`, a release replaced at the stage is refused
218
+ * (exit 1). A newer release replaces each older one waiting; one older
219
+ * than a release waiting is replaced itself and refused. The release
220
+ * then waits, its gate is read, and while another release is in the
221
+ * stage it exits 3. A release already in the stage carries on without
222
+ * its gate read again.
223
+ * - Once the gate passes, the release's `entered` line is written; the
224
+ * caller writes its `finished` line with {@link pipelineStageFinished}.
225
+ */
226
+ export declare function pipelineStageEntry(input: {
227
+ spec: PipelineSpec;
228
+ to: string;
229
+ skipped: readonly PipelineStage[];
230
+ /** The stages `to` follows, from {@link pipelinePromoteSource}, when it names `after`. */
231
+ upstreams?: readonly string[];
232
+ allowSkip?: boolean;
233
+ digest: string;
234
+ release?: PipelineEntryRelease;
235
+ /** The commits the first stage's ledger records deploys of. */
236
+ firstStageCommits?: ReadonlySet<string>;
237
+ port: GateLedgerPort;
238
+ log: StageLogPort;
239
+ /** `--urgent` (#5355): the stage's urgent rule ({@link pipelineUrgentGate}) in place of its gate. */
240
+ urgent?: boolean;
241
+ actor?: string;
242
+ gitSha?: string;
243
+ runId?: string;
244
+ now: Date;
245
+ /** What proves an approver or a rejecter (#5354), handed to {@link pipelinePromoteGates}. */
246
+ proof?: PipelineGateProof;
247
+ /** The reasons the stage's agent steps add to its gate's risk (#5358), handed to {@link pipelinePromoteGates}. */
248
+ agentRisk?: readonly ChangeRiskReason[];
249
+ }): Promise<PipelineEntryOutcome>;
250
+ /** Write the `finished` line for a release that entered a stage (#5353): `applied` when its deploy did, else `failed`. */
251
+ export declare function pipelineStageFinished(log: StageLogPort, entered: StageLine, result: "applied" | "failed", now: Date): Promise<void>;
252
+ /** The gate an urgent promote into `stage` is approved at (#5355). */
253
+ export declare function urgentGateName(stage: string): string;
254
+ /**
255
+ * The stages a release must have succeeded in before an urgent promote into
256
+ * `to` (#5355), in the pipeline's order. A stage with `after` (#5353) takes
257
+ * the stages it names and every stage those follow, by
258
+ * {@link stageUpstreams}. A stage without `after` takes every stage before it.
259
+ */
260
+ export declare function urgentUpstreamStages(spec: Pick<PipelineSpec, "stages">, to: string): string[];
261
+ /**
262
+ * The stages upstream of `to` ({@link urgentUpstreamStages}) in which the
263
+ * release has not succeeded, each with the components it lacks there
264
+ * (#5355). `missingIn` answers for one stage. Empty when it succeeded in
265
+ * every one.
266
+ */
267
+ export declare function pipelineUrgentUpstream(input: {
268
+ spec: PipelineSpec;
269
+ to: string;
270
+ missingIn: (stage: string) => Promise<string[]>;
271
+ }): Promise<{
272
+ stage: string;
273
+ missing: string[];
274
+ }[]>;
275
+ /** The refusal for a release that has not succeeded in every stage before the one an urgent promote goes to. */
276
+ export declare function urgentUpstreamStop(release: string, missing: readonly {
277
+ stage: string;
278
+ missing: string[];
279
+ }[]): PipelinePromoteStop;
280
+ /** What {@link pipelineUrgentGate} decided: passed on an approval, or the stop. */
281
+ export type PipelineUrgentOutcome = {
282
+ passed: true;
283
+ lines: string[];
284
+ approval: GateResolutionRecord;
285
+ role: string;
286
+ } | ({
287
+ passed: false;
288
+ } & PipelinePromoteStop);
289
+ /**
290
+ * The urgent rule of stage `to` (#5355), in place of its gate: one approval
291
+ * of `<stage>-urgent` bound to the release's digest, from an approver the
292
+ * port's judge proves and gives the rule's role. The quorum rule is
293
+ * `{ count: 1, roles: [role], proven: true }`, so an unproven line never
294
+ * counts. The approval is spent on `_gates/<pipeline>/applied.jsonl`.
295
+ */
296
+ export declare function pipelineUrgentGate(input: {
297
+ spec: PipelineSpec;
298
+ to: string;
299
+ digest: string;
300
+ releaseDigest?: string;
301
+ port: GateLedgerPort;
302
+ gitSha?: string;
303
+ now: Date;
304
+ }): Promise<PipelineUrgentOutcome>;
305
+ /**
306
+ * The soak that held a promotion (#5328): the stage whose soak it is, which
307
+ * is the stage a failed check of it rolls back, and the members that stage
308
+ * applied of what is promoted.
309
+ */
310
+ export interface SoakHeldBy {
311
+ stage: string;
312
+ members: string[];
313
+ }
314
+ /**
315
+ * Every soak in front of a promotion into `to`, in order (#5326, #5327):
316
+ * the soak of each stage promoted from (`upstreams` on a join, else
317
+ * `from`), then the soak of each canary stage `to` follows and is not one
318
+ * of those ({@link canaryStagesBefore}). Each is read through its own gate
319
+ * by {@link pipelinePromoteSoak}; the first that holds stops the promote.
320
+ * `items` gives what a stage applied of what is promoted, and `read` its
321
+ * check reader. A canary with nothing applied says so in `notes` and
322
+ * holds, since its clock cannot start. `lines` are the passed soaks' lines.
323
+ * On a hold, `heldBy` names the stage whose soak held ({@link SoakHeldBy}).
324
+ */
325
+ export declare function pipelinePromoteSoaks(input: {
326
+ spec: PipelineSpec;
327
+ from: string;
328
+ to: string;
329
+ upstreams?: readonly string[];
330
+ items: (stage: string) => Promise<readonly {
331
+ component: string;
332
+ source: {
333
+ timestamp: string;
334
+ };
335
+ }[]>;
336
+ digest: string;
337
+ releaseDigest?: string;
338
+ port: GateLedgerPort;
339
+ read: (stage: string) => SoakCheckReader;
340
+ now: Date;
341
+ gitSha?: string;
342
+ notify?: SoakGateInput["notify"];
343
+ }): Promise<SoakGateOutcome & {
344
+ notes: string[];
345
+ heldBy?: SoakHeldBy;
346
+ }>;
347
+ /**
348
+ * The soak of stage `from` in front of a promotion into `to` (#5326): each
349
+ * promoted component is a member that applied in `from` at its source
350
+ * record's time. Passed when `from` declares no soak or is no stage of the
351
+ * pipeline.
352
+ */
353
+ export declare function pipelinePromoteSoak(input: {
354
+ spec: PipelineSpec;
355
+ from: string;
356
+ to: string;
357
+ items: readonly {
358
+ component: string;
359
+ source: {
360
+ timestamp: string;
361
+ };
362
+ }[];
363
+ digest: string;
364
+ releaseDigest?: string;
365
+ port: GateLedgerPort;
366
+ read: SoakCheckReader;
367
+ now: Date;
368
+ gitSha?: string;
369
+ notify?: SoakGateInput["notify"];
370
+ }): Promise<SoakGateOutcome>;
371
+ /** What a stage gate's policy said of the agent answers: a verdict, or undefined when no policy is named at base. */
372
+ export type AgentPolicyVerdict = {
373
+ result: "passed" | "denied" | "held" | "error";
374
+ reasons: string[];
375
+ } | undefined;
376
+ /** What {@link pipelinePromoteAgentSteps} decided. `agent` is what the policy read as `input.agent`. */
377
+ export type PipelineAgentStepsOutcome = {
378
+ passed: true;
379
+ lines: string[];
380
+ agent: Record<string, PolicyAgentAnswer>;
381
+ /** The reasons the answers' levels add to the risk the stage gate reads (#5325): hand them to {@link pipelineStageEntry} as `agentRisk`. */
382
+ risk: ChangeRiskReason[];
383
+ } | ({
384
+ passed: false;
385
+ } & PipelinePromoteStop);
386
+ /**
387
+ * The agent steps part of a promote (#5358), before the stage's gate: every
388
+ * step of the stage `to` needs an answer for the release that matches its
389
+ * schema, or the promote holds (exit 3) and says why. With
390
+ * `gate.holds.policy`, `policy` runs the workspace's `ci.policy` with the
391
+ * answers as `input.agent`: a deny refuses the promote, a hold is printed,
392
+ * and the gate still waits for a person either way. Nothing here passes a
393
+ * gate.
394
+ */
395
+ export declare function pipelinePromoteAgentSteps(input: {
396
+ spec: PipelineSpec;
397
+ to: string;
398
+ release?: {
399
+ digest: string;
400
+ label?: string | null;
401
+ };
402
+ port: StageAgentAnswerPort;
403
+ policy?: (agent: Record<string, PolicyAgentAnswer>) => Promise<AgentPolicyVerdict>;
404
+ }): Promise<PipelineAgentStepsOutcome>;