@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,176 @@
1
+ /**
2
+ * The soak at a gate (#5326): what a promote into the next stage, and the
3
+ * next wave's job, run before their own gate.
4
+ *
5
+ * The soak has a gate of its own on the gate ledger: `<stage>-soak` under
6
+ * the pipeline's op for a stage, `<gate>-wave-<k>-soak` under the spec's op
7
+ * for wave `k`. Its approval is how a person ends the soak early, bound to
8
+ * the release's digest (or the wave's). A product maps its own comment,
9
+ * such as `/terragucci skip-soak`, onto that approval. The approval names
10
+ * who, and the promote records it as spent on `_gates/<op>/applied.jsonl`.
11
+ *
12
+ * A soak that holds records the gate's pending fact with the soak's state
13
+ * on it (`soak`: the clock, the time left, the holds, the checks that
14
+ * failed), and the run exits 3. The next run reads that state back: a
15
+ * `restart` check that failed and now passes starts the clock over.
16
+ *
17
+ * Ending a soak early, or a soak passing, opens nothing by itself: the next
18
+ * stage's gate, or the next wave's, still waits for its approval. A soak
19
+ * only ever adds a wait.
20
+ *
21
+ * A check that starts failing also records a `verify-failed` fact for the
22
+ * agent (#5339, `../ci-agent-verify-failed.ts`), when the job's
23
+ * `CHANT_AGENT_FACTS` names `verify-failed` and it holds the relay key. The
24
+ * fact is read from the same change the notice is sent for, and the soak's
25
+ * outcome is the same with or without it.
26
+ */
27
+ import { createHash } from "node:crypto";
28
+ import { approveCommand, evaluateGate } from "../op/gate.js";
29
+ import { makeNotifyEvent, sendNotify } from "../notify.js";
30
+ import { decideSoak, soakHoldLines } from "./soak.js";
31
+ /** How long a soak's pending fact stands before a run records it again. Longer than any soak a stage declares in practice. */
32
+ export const SOAK_FACT_EXPIRY = "30d";
33
+ /** The gate a stage's soak is ended early through. */
34
+ export function stageSoakGate(stage) {
35
+ return `${stage}-soak`;
36
+ }
37
+ /** The gate wave `k`'s soak is ended early through, from the wave's own gate name. */
38
+ export function waveSoakGate(waveGate) {
39
+ return `${waveGate}-soak`;
40
+ }
41
+ /** The gate ledger with every read and no write: an early end is looked for without recording a fact. */
42
+ function readOnly(port) {
43
+ const { appendResolution: _r, appendApplied: _a, appendFinished: _f, storeRequestAttachment: _s, writeCheckpoint: _c, ...reads } = port;
44
+ return {
45
+ ...reads,
46
+ async appendPending(input) {
47
+ return { record: { version: 1, kind: "pending", ...input }, pushed: false, pushWarning: "not recorded" };
48
+ },
49
+ };
50
+ }
51
+ function sameState(a, b) {
52
+ return (a.restartedAt ?? "") === (b.restartedAt ?? "") && JSON.stringify(a.failing ?? []) === JSON.stringify(b.failing ?? []);
53
+ }
54
+ /** Decide the soak in front of a gate, read and record its fact, and notify a failed check. See the module comment. */
55
+ export async function soakAtGate(input) {
56
+ const { port, op, gate, digest, stage } = input;
57
+ const now = input.now.toISOString();
58
+ const approval = input.quorum && input.quorum.length > 0 ? { approval: { quorum: input.quorum, mode: "enforce" } } : {};
59
+ const gateInput = {
60
+ op,
61
+ gate,
62
+ planDigest: digest,
63
+ environment: stage,
64
+ now,
65
+ ...(input.releaseDigest ? { releaseDigest: input.releaseDigest } : {}),
66
+ ...(input.gitSha ? { gitSha: input.gitSha } : {}),
67
+ ...approval,
68
+ };
69
+ if (!input.soak)
70
+ return { passed: true, lines: [], decision: await decideSoak({ soak: undefined, subjects: [], environment: stage, now: input.now, read: input.read }) };
71
+ // A person's early end wins over everything else.
72
+ const early = await evaluateGate(readOnly(port), gateInput);
73
+ const ledger = await port.read(op);
74
+ const facts = ledger.pending.filter((p) => p.gate === gate && p.environment === stage && p.planDigest === digest && p.soak);
75
+ const last = facts.sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)).at(-1)?.soak;
76
+ const prior = { ...(last?.restartedAt ? { restartedAt: last.restartedAt } : {}), ...(last?.failing ? { failing: [...last.failing] } : {}) };
77
+ const decision = await decideSoak({
78
+ soak: input.soak,
79
+ subjects: input.subjects,
80
+ environment: stage,
81
+ now: input.now,
82
+ state: prior,
83
+ read: input.read,
84
+ ...(early.satisfied ? { ended: { by: early.resolution.resolvedBy } } : {}),
85
+ });
86
+ if (decision.outcome === "release") {
87
+ if (decision.via === "ended" && early.satisfied) {
88
+ await port.appendApplied?.({ version: 1, kind: "applied", op, gate, planDigest: digest, approvedAt: early.resolution.timestamp, approvedBy: early.resolution.resolvedBy, timestamp: now, ...(input.gitSha ? { commit: input.gitSha } : {}) });
89
+ return { passed: true, lines: [`the soak of ${stage} was ended early by ${early.resolution.resolvedBy} through ${op} ${gate}`], decision };
90
+ }
91
+ const rule = decision.rules[0]?.rule;
92
+ return { passed: true, lines: [`${stage} soaked${rule && rule.durationMs > 0 ? ` for ${rule.duration}` : ""} since ${decision.clockStart}, and its checks pass`], decision };
93
+ }
94
+ const lines = soakHoldLines(decision);
95
+ const time = decision.holds.find((h) => h.reason === "time");
96
+ const soakFact = {
97
+ stage,
98
+ ...(input.wave !== undefined ? { wave: input.wave } : {}),
99
+ ...(input.to !== undefined ? { to: input.to } : {}),
100
+ clockStart: decision.clockStart,
101
+ due: decision.due,
102
+ ...(time && time.reason === "time" ? { leftMs: time.leftMs } : {}),
103
+ holds: lines,
104
+ ...decision.state,
105
+ };
106
+ const description = `${input.holds} waits for the soak of ${stage}: ${lines.join("; ")}`;
107
+ const got = await evaluateGate(port, { ...gateInput, description, timeout: SOAK_FACT_EXPIRY, fields: { soak: soakFact } });
108
+ if (got.satisfied) {
109
+ // Approved between the read above and now: ended early all the same.
110
+ await port.appendApplied?.({ version: 1, kind: "applied", op, gate, planDigest: digest, approvedAt: got.resolution.timestamp, approvedBy: got.resolution.resolvedBy, timestamp: now, ...(input.gitSha ? { commit: input.gitSha } : {}) });
111
+ return { passed: true, lines: [`the soak of ${stage} was ended early by ${got.resolution.resolvedBy} through ${op} ${gate}`], decision: { ...decision, outcome: "release", via: "ended", holds: [], endedBy: { by: got.resolution.resolvedBy } } };
112
+ }
113
+ let recorded = got.recorded ? got.pending : undefined;
114
+ if (!got.recorded && !sameState(prior, decision.state)) {
115
+ // The standing fact is reused while it lives; a change in the clock's state is recorded on a fresh one, so the next run reads it.
116
+ const { version: _v, kind: _k, ...standing } = got.pending;
117
+ recorded = (await port.appendPending({ ...standing, timestamp: now, description, soak: soakFact })).record;
118
+ }
119
+ // A check newly failed: tell people, once per change.
120
+ const checks = decision.holds.filter((h) => h.reason === "check");
121
+ const fresh = (decision.state.failing ?? []).filter((f) => !(prior.failing ?? []).includes(f));
122
+ // #5339: a check that newly failed (not one that reads unknown) is a fact for the verify-failed agent. Recording never changes the soak.
123
+ const newlyFailed = checks.filter((h) => h.reason === "check" && h.status === "failed" && fresh.includes(h.member ? `${h.check}@${h.member}` : h.check));
124
+ if (newlyFailed.length > 0) {
125
+ const { recordVerifyFailed, soakFailedRecords } = await import("../ci-agent-verify-failed.js");
126
+ const records = soakFailedRecords({
127
+ stage,
128
+ holds: input.holds,
129
+ ...(input.wave !== undefined ? { wave: input.wave } : {}),
130
+ ...(input.releaseDigest ? { releaseDigest: input.releaseDigest } : {}),
131
+ checks: newlyFailed.flatMap((h) => (h.reason === "check" ? [{ check: h.check, kind: h.kind, detail: h.detail, ...(h.member ? { member: h.member } : {}), ...(h.targets ? { targets: h.targets } : {}) }] : [])),
132
+ });
133
+ const line = await recordVerifyFailed(records, { ...(input.agentFacts?.env ? { env: input.agentFacts.env } : {}), ...(input.agentFacts?.cwd ? { cwd: input.agentFacts.cwd } : {}), now: input.now });
134
+ if (line)
135
+ (input.agentFacts?.say ?? ((l) => console.error(l)))(line);
136
+ }
137
+ if (input.notify && checks.length > 0 && fresh.length > 0) {
138
+ const event = makeNotifyEvent({
139
+ source: input.notify.source,
140
+ event: "soak",
141
+ summary: `${input.holds} is held: a soak check of ${stage} failed`,
142
+ environment: stage,
143
+ ...(input.notify.project ? { project: input.notify.project } : {}),
144
+ targets: [...new Set(checks.flatMap((h) => (h.reason === "check" ? (h.targets ?? []) : [])))],
145
+ digest,
146
+ // The id covers the failing checks, so a receiver drops a repeat and hears a new failure.
147
+ id: createHash("sha256").update(JSON.stringify([input.notify.source, op, gate, digest, decision.state.failing ?? []])).digest("hex"),
148
+ soak: {
149
+ stage,
150
+ ...(input.wave !== undefined ? { wave: input.wave } : {}),
151
+ holds: input.holds,
152
+ clockStart: decision.clockStart,
153
+ due: decision.due,
154
+ checks: checks.map((h) => (h.reason === "check" ? { name: h.check, kind: h.kind, onFail: h.onFail, status: h.status, detail: h.detail, ...(h.member ? { member: h.member } : {}), ...(h.targets ? { targets: h.targets } : {}) } : undefined)).filter((c) => c !== undefined),
155
+ },
156
+ reason: lines.join("; "),
157
+ exitCode: 3,
158
+ }, { now: input.now });
159
+ try {
160
+ await (input.notify.send ?? sendNotify)(input.notify.config, event);
161
+ }
162
+ catch {
163
+ // A notice never changes the outcome.
164
+ }
165
+ }
166
+ return {
167
+ passed: false,
168
+ exitCode: 3,
169
+ code: "pipeline-soak-waiting",
170
+ message: `${input.holds} waits for the soak of ${stage}: ${lines.join("; ")}`,
171
+ hint: `Run it again once the soak is up, or end the soak early with: ${approveCommand(op, gate, stage, digest)}`,
172
+ lines,
173
+ decision,
174
+ ...(recorded ? { recorded } : {}),
175
+ };
176
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * The soak's sources in a job (#5326): HTTP through `fetch`, commands
3
+ * through `spawnSync`, `lifecycle health` through the product's bin, the
4
+ * applies and policy denials from the op's run records on `chant/lifecycle`,
5
+ * and the drift issue from the forge the job runs on. A source that cannot
6
+ * be reached reads `unknown`, which holds.
7
+ */
8
+ import { type SoakSources } from "./soak-checks.js";
9
+ export interface JobSoakSourcesOptions {
10
+ /** The op whose run records hold the applies and denials. */
11
+ op: string;
12
+ /** The member's directory, where commands and `lifecycle health` run. */
13
+ cwd: string;
14
+ env?: NodeJS.ProcessEnv;
15
+ }
16
+ /** The sources a promote or a wave job reads its soak's checks from. */
17
+ export declare function jobSoakSources(options: JobSoakSourcesOptions): SoakSources;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * The soak's sources in a job (#5326): HTTP through `fetch`, commands
3
+ * through `spawnSync`, `lifecycle health` through the product's bin, the
4
+ * applies and policy denials from the op's run records on `chant/lifecycle`,
5
+ * and the drift issue from the forge the job runs on. A source that cannot
6
+ * be reached reads `unknown`, which holds.
7
+ */
8
+ import { activeProductWords } from "../ci-product-words.js";
9
+ import { driftIssueMarker } from "../drift-issue.js";
10
+ import { readRunLedger } from "../lifecycle/run-ledger.js";
11
+ import { opWaveBinArgv } from "../op/op-waves.js";
12
+ import { forgeClient, forgeTargetFromEnv } from "../pr-forge.js";
13
+ import { runRecordSoakSources, spawnSoakExec } from "./soak-checks.js";
14
+ /** The sources a promote or a wave job reads its soak's checks from. */
15
+ export function jobSoakSources(options) {
16
+ const words = activeProductWords();
17
+ const env = options.env ?? process.env;
18
+ const records = new Map();
19
+ const ledger = (environment) => {
20
+ let got = records.get(environment);
21
+ if (!got) {
22
+ got = readRunLedger(environment, options.op, { cwd: options.cwd }).then((r) => runRecordSoakSources(r.records));
23
+ records.set(environment, got);
24
+ }
25
+ return got;
26
+ };
27
+ return {
28
+ fetch: async (url, init) => {
29
+ const res = await globalThis.fetch(url, { ...(init.signal ? { signal: init.signal } : {}), ...(init.headers ? { headers: init.headers } : {}) });
30
+ return { status: res.status, text: () => res.text() };
31
+ },
32
+ exec: spawnSoakExec(options.cwd),
33
+ healthCommand: (environment) => [...opWaveBinArgv(words.bin), "lifecycle", "health", environment, "--json"],
34
+ applies: async (environment, member, targets) => (await ledger(environment)).applies(environment, member, targets),
35
+ denials: async (environment, member, targets) => (await ledger(environment)).denials(environment, member, targets),
36
+ driftIssue: async (environment) => {
37
+ const forge = forgeClient(forgeTargetFromEnv(env));
38
+ const issue = await forge.findIssue(driftIssueMarker(words.product, environment));
39
+ return issue ? { body: issue.body, ...(issue.url ? { url: issue.url } : {}) } : null;
40
+ },
41
+ };
42
+ }
@@ -0,0 +1,260 @@
1
+ /**
2
+ * Soak (#5326): checks that must keep passing for a while after a stage or
3
+ * a wave applied, before the next stage's gate or the next wave opens.
4
+ *
5
+ * No process waits. A promote into the next stage, or the next wave's job,
6
+ * reads the soak when it runs: when the clock started (the last apply the
7
+ * ledger recorded), how long the soak is, and what each check says now. A
8
+ * soak that is not over records its pending fact and exits 3 with the time
9
+ * left; a later run, by hand or from the pipeline's scheduled re-run, reads
10
+ * the clock and the checks again.
11
+ *
12
+ * The decision here is pure: {@link decideSoak} takes the soak, the members
13
+ * that applied and when, the time, a person's early end, the state the last
14
+ * run left, and a reader for the checks. `./soak-checks.ts` holds the
15
+ * readers chant ships, and `./soak-gate.ts` the part a promote and a wave
16
+ * job run, which reads and writes the gate ledger.
17
+ *
18
+ * A soak only holds. It adds a wait in front of a gate and never stands in
19
+ * for an approval: once it passes, or a person ends it, the next stage's own
20
+ * gate still decides.
21
+ *
22
+ * The rules, in the order they apply:
23
+ *
24
+ * 1. No soak: nothing is held.
25
+ * 2. A person ended the soak through its gate: nothing is held, whatever
26
+ * else is true.
27
+ * 3. An apply with no usable time: held, since no clock can be counted.
28
+ * 4. Each `restart` check is read on every run. One that fails holds; once
29
+ * it passes again the clock starts over at that run.
30
+ * 5. Before the clock is up, held for the time left. A `hold` check is not
31
+ * read yet: its failure would keep the elapsed time and hold all the same.
32
+ * 6. Once the clock is up, each `hold` check is read. One that fails holds
33
+ * until it passes or a person ends the soak; the elapsed time is kept.
34
+ * 7. Otherwise the soak passed.
35
+ *
36
+ * `unknown` never counts as passing: a check that cannot be read holds.
37
+ */
38
+ /** What a failing check does. */
39
+ export type SoakOnFail = "restart" | "hold";
40
+ /** The check kinds, in the order the per-member ones report. */
41
+ export declare const SOAK_CHECK_KINDS: readonly ["drift", "apply", "policy", "http", "prometheus", "cloudwatch-alarm", "command", "health"];
42
+ export type SoakCheckKind = (typeof SOAK_CHECK_KINDS)[number];
43
+ /** The kinds read once per member that applied, over that member's targets. The rest are read once per soak. */
44
+ export declare const SOAK_MEMBER_KINDS: readonly SoakCheckKind[];
45
+ interface SoakCheckCommon {
46
+ /** The check's name in the output, the ledger and the notice. Default: its kind and a short digest of its settings. */
47
+ name?: string;
48
+ /** What a failure does. Default `restart`. */
49
+ onFail?: SoakOnFail;
50
+ }
51
+ /** An HTTP request whose status (and body, when given) must match. */
52
+ export interface SoakHttpCheck extends SoakCheckCommon {
53
+ kind: "http";
54
+ url: string;
55
+ /** The statuses that pass. Default 200. */
56
+ status?: number | number[];
57
+ /** A regular expression the body must match. */
58
+ body?: string;
59
+ /** Seconds before the request counts as failed. Default 10. */
60
+ timeoutSeconds?: number;
61
+ }
62
+ /** A Prometheus instant query whose every sample must stay within `min` and `max`. A query with no sample is unknown. */
63
+ export interface SoakPrometheusCheck extends SoakCheckCommon {
64
+ kind: "prometheus";
65
+ /** The server's base URL, such as `https://prometheus.example`. */
66
+ url: string;
67
+ query: string;
68
+ /** The highest value that passes. */
69
+ max?: number;
70
+ /** The lowest value that passes. */
71
+ min?: number;
72
+ timeoutSeconds?: number;
73
+ }
74
+ /** A CloudWatch alarm that must be in state `OK`, read with the AWS CLI the job is logged in with. */
75
+ export interface SoakCloudwatchCheck extends SoakCheckCommon {
76
+ kind: "cloudwatch-alarm";
77
+ alarm: string;
78
+ region?: string;
79
+ }
80
+ /** A command that must exit 0. */
81
+ export interface SoakCommandCheck extends SoakCheckCommon {
82
+ kind: "command";
83
+ command: string[];
84
+ timeoutSeconds?: number;
85
+ }
86
+ /**
87
+ * `chant lifecycle health` for the stage's environment. Every resource read
88
+ * must be healthy: unhealthy, unknown, not read and not deployed all fail.
89
+ * `covers` scopes the check to resources whose name or type a glob matches,
90
+ * so a soak can pass on what it can observe; a scope that matches nothing
91
+ * fails. Absent, every resource counts.
92
+ */
93
+ export interface SoakHealthCheck extends SoakCheckCommon {
94
+ kind: "health";
95
+ covers?: string[];
96
+ }
97
+ /** No open drift issue of the member's environment names one of its targets (in a code span). */
98
+ export interface SoakDriftCheck extends SoakCheckCommon {
99
+ kind: "drift";
100
+ }
101
+ /** The newest apply of each of the member's targets did not fail. One still running, or none on record, passes. */
102
+ export interface SoakApplyCheck extends SoakCheckCommon {
103
+ kind: "apply";
104
+ }
105
+ /** No policy denial of one of the member's targets was recorded since the clock started. A target's newest denial is the one read. */
106
+ export interface SoakPolicyCheck extends SoakCheckCommon {
107
+ kind: "policy";
108
+ }
109
+ export type SoakCheck = SoakHttpCheck | SoakPrometheusCheck | SoakCloudwatchCheck | SoakCommandCheck | SoakHealthCheck | SoakDriftCheck | SoakApplyCheck | SoakPolicyCheck;
110
+ /** Checks and a duration for the members a glob names, in place of the soak's own. */
111
+ export interface SoakOverride {
112
+ /** Member names or globs: `*` stays within one `/` segment, `**` crosses them. */
113
+ members: string[];
114
+ duration?: string;
115
+ checks?: SoakCheck[];
116
+ }
117
+ /** A stage's or a wave's soak. */
118
+ export interface Soak {
119
+ /** How long the checks must pass after the last apply: `<n>m`, `<n>h`, `<n>d`, or `0`. */
120
+ duration: string;
121
+ checks?: SoakCheck[];
122
+ /** The first override whose glob names a member decides that member's duration and checks; a field it leaves out is the soak's. */
123
+ overrides?: SoakOverride[];
124
+ }
125
+ /** The rule one member soaks under, after overrides. */
126
+ export interface SoakRule {
127
+ /** As written. */
128
+ duration: string;
129
+ durationMs: number;
130
+ checks: SoakCheck[];
131
+ }
132
+ /** A soak duration in milliseconds, or undefined when it is not `<n>m`, `<n>h`, `<n>d` or `0`. */
133
+ export declare function soakDurationMs(value: string): number | undefined;
134
+ /**
135
+ * Whether `glob` names `name`: `*` matches within one `/` segment, `**`
136
+ * across them (and `a/**\/b` also matches `a/b`), `?` one character other
137
+ * than `/`. A glob with no wildcard matches only the same name.
138
+ */
139
+ export declare function soakGlobMatch(glob: string, name: string): boolean;
140
+ /** The rule for a member known by `names` (its name, and any other spelling of it): the first override whose glob names one of them, else the soak's own. */
141
+ export declare function soakRuleFor(soak: Soak, names: readonly string[]): SoakRule;
142
+ /** What a failure of `check` does. */
143
+ export declare function soakOnFail(check: Pick<SoakCheck, "onFail">): SoakOnFail;
144
+ /** The check's name: its own, else its kind and a short digest of its settings, so the same check keeps its name from run to run. */
145
+ export declare function soakCheckName(check: SoakCheck): string;
146
+ /** Everything wrong with a soak, one line each; empty when it reads. */
147
+ export declare function soakProblems(soak: unknown, where: string): string[];
148
+ /** What a check is asked about. */
149
+ export interface SoakCheckContext {
150
+ /** The environment that soaks: the stage's name, or the wave's environment. */
151
+ environment: string;
152
+ /** On a per-member check: the member, and the targets of it that applied. */
153
+ member?: string;
154
+ targets: string[];
155
+ /** When the clock started, ISO 8601. A policy denial counts from here. */
156
+ since: string;
157
+ now: Date;
158
+ }
159
+ /** What a check found. `unknown` holds, as `failed` does. */
160
+ export interface SoakCheckResult {
161
+ status: "passed" | "failed" | "unknown";
162
+ /** On a per-member check that failed: the targets it found. */
163
+ targets?: string[];
164
+ /** One line a person reads. */
165
+ detail: string;
166
+ }
167
+ /** Reads one check. A reader never throws: an error is `unknown`. */
168
+ export type SoakCheckReader = (check: SoakCheck, context: SoakCheckContext) => Promise<SoakCheckResult>;
169
+ /** One member that applied in the stage or wave that soaks. */
170
+ export interface SoakSubject {
171
+ member: string;
172
+ /** Other spellings an override glob may match, beside `member`. */
173
+ names?: string[];
174
+ /** The member's targets that applied. */
175
+ targets: string[];
176
+ /** When it applied, ISO 8601, from the ledger. Absent or not a time: the clock cannot be counted. */
177
+ appliedAt?: string;
178
+ }
179
+ /** What the last run of this soak recorded (on its pending fact), so a run knows a check passing again. */
180
+ export interface SoakClockState {
181
+ /** When a `restart` check last passed again after failing, ISO 8601: the clock starts over there. */
182
+ restartedAt?: string;
183
+ /** The checks that failed on the last run, by name. */
184
+ failing?: string[];
185
+ }
186
+ /** Why a soak holds. */
187
+ export type SoakHold = {
188
+ reason: "time";
189
+ due: string;
190
+ leftMs: number;
191
+ } | {
192
+ reason: "clock-unknown";
193
+ members: string[];
194
+ } | {
195
+ reason: "check";
196
+ check: string;
197
+ kind: SoakCheckKind;
198
+ onFail: SoakOnFail;
199
+ status: "failed" | "unknown";
200
+ member?: string;
201
+ targets?: string[];
202
+ detail: string;
203
+ };
204
+ /** What {@link decideSoak} decided. */
205
+ export interface SoakDecision {
206
+ outcome: "hold" | "release";
207
+ /** On a release: no soak, a person ended it, or it soaked. */
208
+ via?: "no-soak" | "ended" | "soaked";
209
+ /** Each member's rule, in subject order; empty with no soak. */
210
+ rules: {
211
+ member: string;
212
+ rule: SoakRule;
213
+ }[];
214
+ /** When the clock started: the last apply, or a later restart. Null when nothing counted it. */
215
+ clockStart: string | null;
216
+ /** When the soak is up: the clock start and the longest duration. Null where `clockStart` is. */
217
+ due: string | null;
218
+ /** Why it holds, in the order reported; empty on a release. */
219
+ holds: SoakHold[];
220
+ /** On `ended`: who, and where. */
221
+ endedBy?: {
222
+ by: string;
223
+ url?: string;
224
+ };
225
+ /** The state to record for the next run. */
226
+ state: SoakClockState;
227
+ }
228
+ export interface DecideSoakInput {
229
+ /** The soak, or undefined when the stage or wave declares none. */
230
+ soak: Soak | undefined;
231
+ subjects: readonly SoakSubject[];
232
+ environment: string;
233
+ now: Date;
234
+ /** A person ended the soak (through its gate). */
235
+ ended?: {
236
+ by: string;
237
+ url?: string;
238
+ };
239
+ /** What the last run recorded. */
240
+ state?: SoakClockState;
241
+ read: SoakCheckReader;
242
+ }
243
+ /** Decide a soak at `input.now`. See the module comment for the order. */
244
+ export declare function decideSoak(input: DecideSoakInput): Promise<SoakDecision>;
245
+ /** A span of milliseconds as a person reads it: `2h 5m`, `3d 4h`, `40s`. */
246
+ export declare function soakSpan(ms: number): string;
247
+ /** One line per hold: what the next stage or wave waits for. */
248
+ export declare function soakHoldLines(decision: Pick<SoakDecision, "holds">): string[];
249
+ /**
250
+ * How many checks a soak reads, its own and its overrides' (#5327). A
251
+ * canary with none holds nothing but a timer, so a pipeline refuses it and
252
+ * existing config warns.
253
+ */
254
+ export declare function soakCheckCount(soak: {
255
+ checks?: unknown;
256
+ overrides?: unknown;
257
+ } | undefined): number;
258
+ /** How a soak reads in the plan note and the docs: its duration and its checks. */
259
+ export declare function soakSummary(soak: Soak): string;
260
+ export {};