@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
@@ -35,6 +35,10 @@ function qualifyObservation(obs, stackName) {
35
35
  // Which read answered (#2267) is per entity, so it re-keys with them.
36
36
  sources: q(obs.sources),
37
37
  ...(obs.annotations ? { annotations: q(obs.annotations) } : {}),
38
+ // Engine facts (#5333) are keyed by node id, so they re-key the same way.
39
+ ...(obs.engineFacts ? { engineFacts: q(obs.engineFacts) } : {}),
40
+ // Undeclared live objects (#5429) are keyed by node id too.
41
+ ...(obs.undeclared ? { undeclared: q(obs.undeclared) } : {}),
38
42
  notes: obs.notes,
39
43
  // Exports are already keyed by stack (#1279); nothing to qualify.
40
44
  ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
@@ -93,6 +97,8 @@ export async function observeResources(environment, plugins, buildResult, opts)
93
97
  const errors = [];
94
98
  const notes = [];
95
99
  const annotations = {};
100
+ const engineFacts = {};
101
+ const undeclared = [];
96
102
  const sources = {};
97
103
  const rootReads = {};
98
104
  for (const plugin of plugins) {
@@ -192,6 +198,9 @@ export async function observeResources(environment, plugins, buildResult, opts)
192
198
  notes.push(line);
193
199
  }
194
200
  Object.assign(annotations, observed.annotations ?? {});
201
+ Object.assign(engineFacts, observed.engineFacts ?? {});
202
+ if (observed.undeclared)
203
+ undeclared.push({ lexicon: plugin.name, resources: observed.undeclared });
195
204
  Object.assign(sources, observed.sources);
196
205
  Object.assign(rootReads, observed.rootReads ?? {});
197
206
  // What the estate depends on but does not declare (#1273). Read after the
@@ -248,7 +257,7 @@ export async function observeResources(environment, plugins, buildResult, opts)
248
257
  }, environment, entityNames.length);
249
258
  }
250
259
  }
251
- return { observations, warnings, errors, notes, annotations, ...(Object.keys(sources).length > 0 ? { sources } : {}), ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}) };
260
+ return { observations, warnings, errors, notes, annotations, ...(Object.keys(engineFacts).length > 0 ? { engineFacts } : {}), ...(undeclared.length > 0 ? { undeclared } : {}), ...(Object.keys(sources).length > 0 ? { sources } : {}), ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}) };
252
261
  }
253
262
  /**
254
263
  * The subset of an observation belonging to one stack.
@@ -688,6 +688,9 @@ export async function cutRelease(req) {
688
688
  const { recordOverridesApplied } = await import("./override-ledger.js");
689
689
  await recordOverridesApplied([appliedOverride({ subject: greenOverrideSubject(commit), digest: p.override.digest, at: p.override.at, by: p.override.by }, { timestamp, runId, commit })], { cwd });
690
690
  }
691
+ // #5387: the change risk the waves that applied the commit scored, bound to the release on its cut line.
692
+ const { readReleaseRisk } = await import("./release-risk.js");
693
+ const risk = await readReleaseRisk(commit, { cwd });
691
694
  const outcome = await appendCut({
692
695
  releaseDigest: release.releaseDigest,
693
696
  label: req.label,
@@ -703,6 +706,7 @@ export async function cutRelease(req) {
703
706
  ...(p.override ? { override: p.override } : {}),
704
707
  ...(p.green ? { green: p.green } : {}),
705
708
  ...(req.intents && req.intents.length > 0 ? { intents: [...req.intents] } : {}),
709
+ ...(risk ? { risk } : {}),
706
710
  }, { cwd });
707
711
  return {
708
712
  release,
@@ -178,6 +178,14 @@ export interface ReleaseRecord {
178
178
  * written before 0.124.28, whose gate cannot be recovered from the record.
179
179
  */
180
180
  admission?: ReleaseAdmission;
181
+ /**
182
+ * Optional: the gate steps of the component that did not apply in this
183
+ * environment (#5401), because their `environments` name others, sorted
184
+ * and distinct. Written from chant `GATE_ENVIRONMENTS_FLOOR`
185
+ * (../components/step-environments.ts); absent when every gate applied
186
+ * and on every record written before.
187
+ */
188
+ gatesSkipped?: string[];
181
189
  /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
182
190
  manifestDigest?: string;
183
191
  /**
@@ -0,0 +1,137 @@
1
+ /**
2
+ * The change risk a release carries (#5387), and how a later stage's gate
3
+ * reads it.
4
+ *
5
+ * #5325 scores a change set where a wave plans it. A promote into a later
6
+ * stage plans nothing, so the score travels with the release:
7
+ *
8
+ * 1. A wave of the first stage that scores its change set under `holds.risk`
9
+ * writes its record beside its release records once it applied, one line
10
+ * per wave in `_releases/risk/<commit>.jsonl` on `chant/lifecycle`.
11
+ * 2. `chant release cut` reads the lines of the commit it cuts, keeps the
12
+ * newest per wave, and writes them on the cut line as the release's
13
+ * `risk`, so the record is bound to the release digest. The release's
14
+ * score is the chance that at least one wave's score bites:
15
+ * `1 - (1 - s1) * (1 - s2) * ...`, so a wave only ever raises it.
16
+ * 3. `chant components promote --release` reads the cut's record, and each
17
+ * stage gate it passes reads it under that stage's `holds.risk`
18
+ * ({@link stageRiskRead}). Over `approveAbove`, or with a question
19
+ * answered above its own threshold, the gate takes the risk's `quorum`
20
+ * rules on top of its own, and a gate whose policy is `never` waits for an
21
+ * approval of its own.
22
+ *
23
+ * A release with no record reads as no score: the stage's gate is what it
24
+ * was before, so a release cut before this, or a pipeline whose first stage
25
+ * scores nothing, promotes as it did. The record only ever adds approvals:
26
+ * a score within the threshold asks for nothing more and passes no gate, and
27
+ * nothing reads the score as leave to apply unattended.
28
+ */
29
+ import { type ChangeRisk, type ChangeRiskLevel, type ChangeRiskReason, type ChangeRiskSettings } from "../change-risk.js";
30
+ import type { GateQuorumRule } from "../op/gate-quorum.js";
31
+ import type { PipelineSpec } from "../pipeline/spec.js";
32
+ import { type LedgerLocation } from "./git.js";
33
+ /** The directory on `chant/lifecycle` that holds each commit's wave scores. */
34
+ export declare const RELEASE_RISK_DIR = "_releases/risk";
35
+ /** The settings a stage gate reads the record under: its `holds.risk`. */
36
+ export type StageRiskSettings = Omit<ChangeRiskSettings, "questions">;
37
+ /** One wave's score, as its release records carry it. */
38
+ export interface WaveRisk {
39
+ /** The op-waves spec that scored it, such as `shop-dev`. */
40
+ op: string;
41
+ /** The wave's number, from 1. */
42
+ wave: number;
43
+ /** The wave's name. */
44
+ name: string;
45
+ /** The digest the wave's gate decided. */
46
+ digest: string;
47
+ /** The wave's record, as `scoreChangeRisk` gave it. */
48
+ risk: ChangeRisk;
49
+ }
50
+ /** One line of `_releases/risk/<commit>.jsonl`. */
51
+ export interface WaveRiskLine extends WaveRisk {
52
+ version: 1;
53
+ /** The commit the wave applied. */
54
+ commit: string;
55
+ timestamp: string;
56
+ }
57
+ /** The change risk a release carries (#5387), on its cut line. */
58
+ export interface ReleaseRisk {
59
+ version: 1;
60
+ /** The commit the release was cut from, which the waves scored. */
61
+ commit: string;
62
+ /** From 0 to 1, to four places: `1 - (1 - s1) * (1 - s2) * ...` over the waves' scores. */
63
+ score: number;
64
+ level: ChangeRiskLevel;
65
+ /** Each wave's record, the newest per wave, by spec then wave. */
66
+ waves: WaveRisk[];
67
+ }
68
+ /** Whether `v` reads as a {@link ReleaseRisk}. */
69
+ export declare function isReleaseRisk(v: unknown): v is ReleaseRisk;
70
+ /** Parse the lines of a commit's risk file. A line that is not a wave's score is skipped. */
71
+ export declare function parseWaveRiskLines(text: string | null): WaveRiskLine[];
72
+ /**
73
+ * The record a release cut from `commit` carries: the newest line per wave,
74
+ * by spec then wave, and their scores combined. Undefined when no wave of
75
+ * the commit was scored.
76
+ */
77
+ export declare function releaseRiskOf(commit: string, lines: readonly WaveRiskLine[]): ReleaseRisk | undefined;
78
+ /** The wave scores recorded for `commit`, oldest first. Empty when none is. */
79
+ export declare function readWaveRisk(commit: string, opts?: LedgerLocation): Promise<WaveRiskLine[]>;
80
+ /** The record a release cut from `commit` binds, read from the ledger. Undefined when no wave of the commit was scored. */
81
+ export declare function readReleaseRisk(commit: string, opts?: LedgerLocation): Promise<ReleaseRisk | undefined>;
82
+ /** Append wave scores to their commits' files on the local `chant/lifecycle`. Does not push; the release records written after them do. */
83
+ export declare function appendWaveRisk(lines: readonly WaveRiskLine[], opts?: {
84
+ cwd?: string;
85
+ }): Promise<void>;
86
+ /** A stage's `holds.risk`: its gate's `holds`, else the pipeline defaults', as the stage's op-waves spec takes them. */
87
+ export declare function stageRiskSettings(spec: Pick<PipelineSpec, "stages" | "defaults">, stage: string): StageRiskSettings | undefined;
88
+ /**
89
+ * A score and its reasons read under a stage's settings: over when the score
90
+ * is above `approveAbove`, or a question's answer is above its own threshold
91
+ * (an `unknown` answer is above every one), as `scoreChangeRisk` decides it.
92
+ */
93
+ export declare function riskAtThreshold(at: {
94
+ score: number;
95
+ reasons: readonly ChangeRiskReason[];
96
+ }, settings: StageRiskSettings): ChangeRisk;
97
+ /** A release's record as one stage's gate reads it. */
98
+ export declare function releaseRiskAt(record: ReleaseRisk, settings: StageRiskSettings): ChangeRisk;
99
+ /** How a stage gate read the release's risk (#5387). */
100
+ export interface StageRiskRead {
101
+ stage: string;
102
+ settings: StageRiskSettings;
103
+ /** The record read under the stage's settings. Absent when the release carries none: the gate is then as it was. */
104
+ risk?: ChangeRisk;
105
+ /** The rules an over record adds to the gate's own. Empty when it is not over or names none. */
106
+ rules: GateQuorumRule[];
107
+ /** The line the promote prints. */
108
+ line: string;
109
+ }
110
+ /**
111
+ * How stage `stage` reads `record` (#5387). Undefined when the stage sets no
112
+ * `holds.risk`, so the record is not read at all.
113
+ *
114
+ * `extra` are reasons the stage adds at its own gate (#5358): its agent
115
+ * steps' levels (`agentStepRiskReasons`). Each raises the score as a reason
116
+ * of the record would, `1 - (1 - score) * (1 - contribution)`, and never
117
+ * lowers it.
118
+ */
119
+ export declare function stageRiskRead(spec: Pick<PipelineSpec, "stages" | "defaults">, stage: string, record: ReleaseRisk | undefined, extra?: readonly ChangeRiskReason[]): StageRiskRead | undefined;
120
+ /** The Cedar context a stage gate that read a record carries, `context.changeRisk`. */
121
+ export declare function stageRiskContext(read: StageRiskRead): Record<string, unknown> | undefined;
122
+ /** One later stage's reading of a score, for the plan note and `workspace status`. */
123
+ export interface StageRiskView {
124
+ stage: string;
125
+ /** The stage's threshold, or null when its `holds.risk` sets none. */
126
+ approveAbove: number | null;
127
+ over: boolean;
128
+ /** The rules an over score adds to the stage's gate. */
129
+ quorum: GateQuorumRule[];
130
+ }
131
+ /** How each stage after the first that sets `holds.risk` reads a score and its reasons. Empty when none sets it. */
132
+ export declare function laterStageRisk(spec: Pick<PipelineSpec, "stages" | "defaults">, at: {
133
+ score: number;
134
+ reasons: readonly ChangeRiskReason[];
135
+ }): StageRiskView[];
136
+ /** The plan note's lines for {@link laterStageRisk}: a table of each later stage and what the score asks for there. Empty when no later stage reads it. */
137
+ export declare function laterStageRiskLines(views: readonly StageRiskView[], score: number): string[];
@@ -0,0 +1,214 @@
1
+ /**
2
+ * The change risk a release carries (#5387), and how a later stage's gate
3
+ * reads it.
4
+ *
5
+ * #5325 scores a change set where a wave plans it. A promote into a later
6
+ * stage plans nothing, so the score travels with the release:
7
+ *
8
+ * 1. A wave of the first stage that scores its change set under `holds.risk`
9
+ * writes its record beside its release records once it applied, one line
10
+ * per wave in `_releases/risk/<commit>.jsonl` on `chant/lifecycle`.
11
+ * 2. `chant release cut` reads the lines of the commit it cuts, keeps the
12
+ * newest per wave, and writes them on the cut line as the release's
13
+ * `risk`, so the record is bound to the release digest. The release's
14
+ * score is the chance that at least one wave's score bites:
15
+ * `1 - (1 - s1) * (1 - s2) * ...`, so a wave only ever raises it.
16
+ * 3. `chant components promote --release` reads the cut's record, and each
17
+ * stage gate it passes reads it under that stage's `holds.risk`
18
+ * ({@link stageRiskRead}). Over `approveAbove`, or with a question
19
+ * answered above its own threshold, the gate takes the risk's `quorum`
20
+ * rules on top of its own, and a gate whose policy is `never` waits for an
21
+ * approval of its own.
22
+ *
23
+ * A release with no record reads as no score: the stage's gate is what it
24
+ * was before, so a release cut before this, or a pipeline whose first stage
25
+ * scores nothing, promotes as it did. The record only ever adds approvals:
26
+ * a score within the threshold asks for nothing more and passes no gate, and
27
+ * nothing reads the score as leave to apply unattended.
28
+ */
29
+ import { CHANGE_RISK_CONTEXT_KEY, changeRiskContext, changeRiskLevel, changeRiskQuorum } from "../change-risk.js";
30
+ import { sortedJsonReplacer } from "../utils.js";
31
+ import { ledgerDir, readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles } from "./git.js";
32
+ /** The directory on `chant/lifecycle` that holds each commit's wave scores. */
33
+ export const RELEASE_RISK_DIR = "_releases/risk";
34
+ const round = (n) => Math.round(n * 10000) / 10000;
35
+ const isMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
36
+ const unit = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
37
+ const LEVELS = new Set(["low", "medium", "high"]);
38
+ function isChangeRisk(v) {
39
+ return isMap(v) && unit(v.score) && LEVELS.has(v.level) && Array.isArray(v.reasons) && v.reasons.every((r) => isMap(r) && typeof r.id === "string" && typeof r.contribution === "number");
40
+ }
41
+ function isWaveRisk(v) {
42
+ return isMap(v) && typeof v.op === "string" && Number.isInteger(v.wave) && typeof v.name === "string" && typeof v.digest === "string" && isChangeRisk(v.risk);
43
+ }
44
+ /** Whether `v` reads as a {@link ReleaseRisk}. */
45
+ export function isReleaseRisk(v) {
46
+ return isMap(v) && v.version === 1 && typeof v.commit === "string" && unit(v.score) && LEVELS.has(v.level) && Array.isArray(v.waves) && v.waves.length > 0 && v.waves.every(isWaveRisk);
47
+ }
48
+ /** Parse the lines of a commit's risk file. A line that is not a wave's score is skipped. */
49
+ export function parseWaveRiskLines(text) {
50
+ const out = [];
51
+ for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
52
+ try {
53
+ const v = JSON.parse(line);
54
+ if (isMap(v) && v.version === 1 && typeof v.commit === "string" && typeof v.timestamp === "string" && isWaveRisk(v))
55
+ out.push(v);
56
+ }
57
+ catch {
58
+ // Not a line of this file.
59
+ }
60
+ }
61
+ return out;
62
+ }
63
+ /**
64
+ * The record a release cut from `commit` carries: the newest line per wave,
65
+ * by spec then wave, and their scores combined. Undefined when no wave of
66
+ * the commit was scored.
67
+ */
68
+ export function releaseRiskOf(commit, lines) {
69
+ const newest = new Map();
70
+ for (const l of lines) {
71
+ if (l.commit !== commit)
72
+ continue;
73
+ const key = JSON.stringify([l.op, l.wave]);
74
+ const prior = newest.get(key);
75
+ if (!prior || l.timestamp >= prior.timestamp)
76
+ newest.set(key, l);
77
+ }
78
+ if (newest.size === 0)
79
+ return undefined;
80
+ const waves = [...newest.values()]
81
+ .sort((a, b) => (a.op === b.op ? a.wave - b.wave : a.op < b.op ? -1 : 1))
82
+ .map(({ op, wave, name, digest, risk }) => ({ op, wave, name, digest, risk }));
83
+ const score = round(1 - waves.reduce((p, w) => p * (1 - Math.min(1, Math.max(0, w.risk.score))), 1));
84
+ return { version: 1, commit, score, level: changeRiskLevel(score), waves };
85
+ }
86
+ function fileOf(commit) {
87
+ return `${commit}.jsonl`;
88
+ }
89
+ /** The wave scores recorded for `commit`, oldest first. Empty when none is. */
90
+ export async function readWaveRisk(commit, opts) {
91
+ return parseWaveRiskLines(await readBlobFromPath(RELEASE_RISK_DIR, fileOf(commit), opts));
92
+ }
93
+ /** The record a release cut from `commit` binds, read from the ledger. Undefined when no wave of the commit was scored. */
94
+ export async function readReleaseRisk(commit, opts) {
95
+ return releaseRiskOf(commit, await readWaveRisk(commit, opts));
96
+ }
97
+ const APPEND_ATTEMPTS = 5;
98
+ /** Append wave scores to their commits' files on the local `chant/lifecycle`. Does not push; the release records written after them do. */
99
+ export async function appendWaveRisk(lines, opts) {
100
+ const byCommit = new Map();
101
+ for (const l of lines)
102
+ byCommit.set(l.commit, [...(byCommit.get(l.commit) ?? []), l]);
103
+ for (const [commit, own] of byCommit) {
104
+ let lastErr;
105
+ let written = false;
106
+ for (let attempt = 1; attempt <= APPEND_ATTEMPTS && !written; attempt++) {
107
+ const priorSha = await readPathSha(RELEASE_RISK_DIR, fileOf(commit), opts);
108
+ const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
109
+ const added = own.map((l) => JSON.stringify(l, sortedJsonReplacer)).join("\n");
110
+ const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${added}\n`;
111
+ try {
112
+ const dir = await ledgerDir(RELEASE_RISK_DIR, opts);
113
+ await writeLedgerFiles([{ path: `${dir}/${fileOf(commit)}`, content, expectPriorSha: priorSha }], `Change risk of ${commit.slice(0, 12)}`, opts);
114
+ written = true;
115
+ }
116
+ catch (err) {
117
+ if (!(err instanceof RefCASConflictError))
118
+ throw err;
119
+ lastErr = err;
120
+ }
121
+ }
122
+ if (!written)
123
+ throw lastErr;
124
+ }
125
+ }
126
+ /** A stage's `holds.risk`: its gate's `holds`, else the pipeline defaults', as the stage's op-waves spec takes them. */
127
+ export function stageRiskSettings(spec, stage) {
128
+ const s = spec.stages.find((x) => x.name === stage);
129
+ if (!s)
130
+ return undefined;
131
+ return (s.gate?.holds ?? spec.defaults?.holds)?.risk;
132
+ }
133
+ /**
134
+ * A score and its reasons read under a stage's settings: over when the score
135
+ * is above `approveAbove`, or a question's answer is above its own threshold
136
+ * (an `unknown` answer is above every one), as `scoreChangeRisk` decides it.
137
+ */
138
+ export function riskAtThreshold(at, settings) {
139
+ const overBy = [];
140
+ const approveAbove = settings.approveAbove ?? null;
141
+ if (approveAbove !== null && at.score > approveAbove)
142
+ overBy.push(`the score ${at.score} is above ${approveAbove}`);
143
+ for (const r of at.reasons) {
144
+ if (r.approveAbove === undefined)
145
+ continue;
146
+ if (r.answer === "unknown")
147
+ overBy.push(`${r.id} has no answer, which counts above its threshold of ${r.approveAbove}`);
148
+ else if (typeof r.answer === "number" && r.answer > r.approveAbove)
149
+ overBy.push(`${r.id} was answered ${r.answer}, above its threshold of ${r.approveAbove}`);
150
+ }
151
+ return { version: 1, score: at.score, level: changeRiskLevel(at.score), reasons: [...at.reasons], approveAbove, over: overBy.length > 0, overBy };
152
+ }
153
+ /** A release's record as one stage's gate reads it. */
154
+ export function releaseRiskAt(record, settings) {
155
+ return riskAtThreshold({ score: record.score, reasons: record.waves.flatMap((w) => w.risk.reasons ?? []) }, settings);
156
+ }
157
+ const rulesLine = (rules) => rules
158
+ .map((r) => `${r.count} approval${r.count === 1 ? "" : "s"}${r.roles?.length ? ` with the role ${r.roles.join(" or ")}` : ""}${r.proven ? ", proven" : ""}${r.notAuthor ? ", not the author" : ""}`)
159
+ .join(" and ");
160
+ /**
161
+ * How stage `stage` reads `record` (#5387). Undefined when the stage sets no
162
+ * `holds.risk`, so the record is not read at all.
163
+ *
164
+ * `extra` are reasons the stage adds at its own gate (#5358): its agent
165
+ * steps' levels (`agentStepRiskReasons`). Each raises the score as a reason
166
+ * of the record would, `1 - (1 - score) * (1 - contribution)`, and never
167
+ * lowers it.
168
+ */
169
+ export function stageRiskRead(spec, stage, record, extra = []) {
170
+ const settings = stageRiskSettings(spec, stage);
171
+ if (!settings)
172
+ return undefined;
173
+ if (!record && extra.length === 0) {
174
+ return { stage, settings, rules: [], line: `stage ${stage}: the release carries no change risk, so holds.risk reads no score and the gate is as it would be without it` };
175
+ }
176
+ const base = record ? { score: record.score, reasons: record.waves.flatMap((w) => w.risk.reasons ?? []) } : { score: 0, reasons: [] };
177
+ const score = round(1 - extra.reduce((p, r) => p * (1 - Math.min(1, Math.max(0, r.contribution))), 1 - base.score));
178
+ const risk = riskAtThreshold({ score, reasons: [...base.reasons, ...extra] }, settings);
179
+ const rules = changeRiskQuorum(risk, settings);
180
+ const head = `stage ${stage}: the release's change risk is ${risk.score.toFixed(2)} (${risk.level})`;
181
+ const line = risk.over
182
+ ? `${head}: ${risk.overBy.join("; ")}, so the gate waits for ${rules.length > 0 ? `${rulesLine(rules)} on top of its own rules` : "an approval of its own"}`
183
+ : risk.approveAbove !== null
184
+ ? `${head}, within ${risk.approveAbove}: it asks for nothing more, and approves nothing`
185
+ : `${head}; holds.risk sets no approveAbove, so the score asks for nothing more, and approves nothing`;
186
+ return { stage, settings, risk, rules, line };
187
+ }
188
+ /** The Cedar context a stage gate that read a record carries, `context.changeRisk`. */
189
+ export function stageRiskContext(read) {
190
+ return read.risk ? { [CHANGE_RISK_CONTEXT_KEY]: changeRiskContext(read.risk) } : undefined;
191
+ }
192
+ /** How each stage after the first that sets `holds.risk` reads a score and its reasons. Empty when none sets it. */
193
+ export function laterStageRisk(spec, at) {
194
+ const out = [];
195
+ for (const s of spec.stages.slice(1)) {
196
+ const settings = stageRiskSettings(spec, s.name);
197
+ if (!settings)
198
+ continue;
199
+ const risk = riskAtThreshold(at, settings);
200
+ out.push({ stage: s.name, approveAbove: risk.approveAbove, over: risk.over, quorum: changeRiskQuorum(risk, settings) });
201
+ }
202
+ return out;
203
+ }
204
+ /** The plan note's lines for {@link laterStageRisk}: a table of each later stage and what the score asks for there. Empty when no later stage reads it. */
205
+ export function laterStageRiskLines(views, score) {
206
+ if (views.length === 0)
207
+ return [];
208
+ const out = ["", `**Risk at each later stage:** ${score.toFixed(2)}, as the release carries it into each stage's gate.`, "", "| Stage | approveAbove | Asks for |", "|---|---:|---|"];
209
+ for (const v of views) {
210
+ const asks = !v.over ? "nothing more" : v.quorum.length > 0 ? `${rulesLine(v.quorum)} on top of the gate's own` : "an approval of its own";
211
+ out.push(`| ${v.stage} | ${v.approveAbove ?? "-"} | ${asks} |`);
212
+ }
213
+ return out;
214
+ }
@@ -41,6 +41,7 @@
41
41
  */
42
42
  import { type LedgerLocation } from "./git.js";
43
43
  import type { RunOrigin } from "./release-ledger.js";
44
+ import { type ReleaseRisk } from "./release-risk.js";
44
45
  /** The directory on `chant/lifecycle` that holds releases, cuts and template bytes. */
45
46
  export declare const RELEASES_DIR = "_releases";
46
47
  /** The cut log inside {@link RELEASES_DIR}. */
@@ -215,6 +216,14 @@ export interface ReleaseCut {
215
216
  * there were none, and on every cut written before #5159.
216
217
  */
217
218
  intents?: ReleaseCutIntent[];
219
+ /**
220
+ * The change risk the release carries (#5387, `./release-risk.ts`): the
221
+ * scores the waves that applied its commit recorded, bound to the release
222
+ * digest here, which a later stage's gate reads at promote. Outside the
223
+ * signature, like `intents`. Absent when no wave of the commit was scored,
224
+ * and on every cut written before chant's `RELEASE_RISK_FLOOR`.
225
+ */
226
+ risk?: ReleaseRisk;
218
227
  }
219
228
  /** One intent file a cut consumed (#5159). */
220
229
  export interface ReleaseCutIntent {
@@ -43,6 +43,7 @@ import { sortedJsonReplacer } from "../utils.js";
43
43
  import { contentDigest, sha256Hex } from "../content-digest.js";
44
44
  import { computePlanDigest } from "./plan-digest.js";
45
45
  import { ledgerDir, listFilesInDir, readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles, } from "./git.js";
46
+ import { isReleaseRisk } from "./release-risk.js";
46
47
  /** The directory on `chant/lifecycle` that holds releases, cuts and template bytes. */
47
48
  export const RELEASES_DIR = "_releases";
48
49
  /** The cut log inside {@link RELEASES_DIR}. */
@@ -285,6 +286,8 @@ export function parseCuts(text) {
285
286
  (c.override === undefined || isCutOverride(c.override)) &&
286
287
  (c.green === undefined || isCutGreen(c.green)) &&
287
288
  (c.intents === undefined || isCutIntents(c.intents)) &&
289
+ // #5387: a record that does not read makes the cut unreadable, so a release never promotes as if it carried none.
290
+ (c.risk === undefined || isReleaseRisk(c.risk)) &&
288
291
  (c.composed === undefined || (typeof c.composed === "object" && c.composed !== null && typeof c.composed.base === "string" && Array.isArray(c.composed.sources)));
289
292
  if (!ok) {
290
293
  malformed++;
@@ -362,6 +365,7 @@ export async function appendCut(input, opts) {
362
365
  ...(input.override ? { override: input.override } : {}),
363
366
  ...(input.green ? { green: input.green } : {}),
364
367
  ...(input.intents && input.intents.length > 0 ? { intents: input.intents } : {}),
368
+ ...(input.risk ? { risk: input.risk } : {}),
365
369
  };
366
370
  const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${JSON.stringify(cut, sortedJsonReplacer)}\n`;
367
371
  try {
@@ -0,0 +1,85 @@
1
+ /**
2
+ * A pipeline's stage log (#5353): which release is in each stage, which
3
+ * waits for it, which one a newer release replaced, and how each ended.
4
+ *
5
+ * The lines sit in `_gates/<pipeline>/stages.jsonl` on `chant/lifecycle`,
6
+ * beside the pipeline's gate ledger, under the member's ledger prefix. A
7
+ * promote into a stage of a pipeline that declares `after` or `queue` on
8
+ * any stage writes them; any other pipeline writes none.
9
+ *
10
+ * - `waiting`: a release reached a stage with `queue: "replace"` and waits
11
+ * for its gate, or for the release in the stage to finish.
12
+ * - `replaced`: a waiting release was replaced by a newer one (`by`). It is
13
+ * never let into that stage afterwards.
14
+ * - `entered`: a release passed the stage's gate and its deploy started.
15
+ * - `finished`: that deploy ended, `applied` or `failed`.
16
+ *
17
+ * A stage's release has succeeded there once a `finished` line with result
18
+ * `applied` names it; a stage with several upstream stages reads that for
19
+ * each of them. The reading half is pure; the git half is the port.
20
+ */
21
+ /** One line of `stages.jsonl`. */
22
+ export interface StageLine {
23
+ version: 1;
24
+ kind: "waiting" | "replaced" | "entered" | "finished";
25
+ /** The pipeline's name, the op its stage gates are recorded under. */
26
+ op: string;
27
+ /** The stage, which is its environment's name. */
28
+ stage: string;
29
+ /** The digest the stage gate binds: the release's, or the promoted digests'. */
30
+ digest: string;
31
+ timestamp: string;
32
+ /** The release's label, when it has one. */
33
+ label?: string;
34
+ /** When the release was cut, which orders two releases waiting for one stage. */
35
+ cutAt?: string;
36
+ /** On `replaced`: the digest of the release that replaced it. */
37
+ by?: string;
38
+ /** On `replaced`: that release's label, when it has one. */
39
+ byLabel?: string;
40
+ /** On `finished`: how the deploy ended. */
41
+ result?: "applied" | "failed";
42
+ actor?: string;
43
+ runId?: string;
44
+ }
45
+ /** Where a pipeline's stage log lives, as `writeBlobToPath` takes it. */
46
+ export declare function stageLogPath(op: string): {
47
+ dir: string;
48
+ file: string;
49
+ };
50
+ /** The lines of a `stages.jsonl` file, oldest first. A line that is not one is skipped. */
51
+ export declare function parseStageLines(text: string): StageLine[];
52
+ /** One stage as its log reads: the release in it, the one waiting, and the ones replaced. */
53
+ export interface StageQueue {
54
+ stage: string;
55
+ /** The `entered` line of the release whose deploy has not finished, or null. */
56
+ inStage: StageLine | null;
57
+ /** The `waiting` lines of releases neither replaced, entered nor finished since, oldest first. */
58
+ waiting: StageLine[];
59
+ /** Every `replaced` line, oldest first. */
60
+ replaced: StageLine[];
61
+ }
62
+ /** Stage `stage` as `lines` record it. */
63
+ export declare function stageQueueOf(lines: readonly StageLine[], stage: string): StageQueue;
64
+ /** The `replaced` line that keeps `digest` out of `stage`, or undefined. */
65
+ export declare function replacedIn(lines: readonly StageLine[], stage: string, digest: string): StageLine | undefined;
66
+ /** Whether the release `digest` was applied in `stage`: a `finished` line with result `applied` names it. */
67
+ export declare function succeededIn(lines: readonly StageLine[], stage: string, digest: string): boolean;
68
+ /** Every stage the log names, in the order first met. */
69
+ export declare function stagesInLog(lines: readonly StageLine[]): string[];
70
+ /** Reads and appends a pipeline's stage log. */
71
+ export interface StageLogPort {
72
+ read(op: string): Promise<StageLine[]>;
73
+ append(line: StageLine): Promise<{
74
+ pushed: boolean;
75
+ pushWarning?: string;
76
+ }>;
77
+ }
78
+ /** The log held in memory, for tests and for a caller that read it already. */
79
+ export declare function memoryStageLogPort(seed?: StageLine[]): StageLogPort & {
80
+ lines: StageLine[];
81
+ };
82
+ /** The log on `chant/lifecycle`: each append lands on top of the remote's ledger, retrying a concurrent writer, then pushes. */
83
+ export declare function gitStageLogPort(opts?: {
84
+ cwd?: string;
85
+ }): StageLogPort;