@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
@@ -38,12 +38,36 @@
38
38
  *
39
39
  * Decline records nothing and says who declined. The type-the-name prompt
40
40
  * of `chant approve` (#4575) is for a terminal; a signed click is the
41
- * person's confirmation here. The relay starts no job: the resume job
42
- * applies the wave once the approval stands.
41
+ * person's confirmation here. A click starts no job: the resume job applies
42
+ * the wave once the approval stands.
43
+ *
44
+ * A production alert (#5329) reaches `POST /alert/<source>` when the relay
45
+ * has a secret for that source (`./ci-agent-alert.ts` lists them and how
46
+ * each proves a delivery). The relay:
47
+ *
48
+ * 1. refuses a delivery whose signature or shared token does not verify,
49
+ * or that is older than its maximum age, with 401, and logs why;
50
+ * 2. maps each firing alert to an alert record and writes it as a fact
51
+ * under `_alerts/` on `chant/lifecycle`, signed with the relay key
52
+ * (`./agent-facts.ts`). A delivery the ledger holds already, by the
53
+ * source's id or the `Idempotency-Key` header, is recorded once;
54
+ * 3. starts the alert agent's workflow with no inputs, with a token that
55
+ * can do that and nothing else: a GitHub or Forgejo token for
56
+ * `workflow_dispatch`, or a GitLab pipeline trigger token
57
+ * (`./notify-relay-repo.ts` refuses one that can push). The agent job
58
+ * reads the facts and checks each signature itself, and its schedule
59
+ * picks up a fact whose start did not arrive.
60
+ *
61
+ * That is all the relay may do: record an approval or a decision point's
62
+ * answer that a signed click asks for, record alert facts, and start the
63
+ * alert agent's workflow. It never approves on its own, merges, applies,
64
+ * or pushes anywhere but `chant/lifecycle`.
43
65
  */
44
66
  import { createHmac, timingSafeEqual } from "node:crypto";
45
67
  import { createServer } from "node:http";
46
68
  import { readRelayToken, RELAY_APPROVE_ACTION, RELAY_DECLINE_ACTION } from "./notify.js";
69
+ import { signAgentFact } from "./agent-facts.js";
70
+ import { ALERT_SOURCES, alertKey, readAlertDelivery } from "./ci-agent-alert.js";
47
71
  /**
48
72
  * The first chant whose relay answers a gate's decision point and whose
49
73
  * `sendNotify` hands a product's own render the signed buttons
@@ -74,7 +98,17 @@ export const RELAY_ENV = {
74
98
  port: "CHANT_RELAY_PORT",
75
99
  /** Comma-separated address prefixes a Slack response_url may have. */
76
100
  slackResponse: "CHANT_RELAY_SLACK_RESPONSE",
101
+ /** The secret every alert source shares, unless `CHANT_ALERT_SECRET_<SOURCE>` names one of its own (#5329). */
102
+ alertSecret: "CHANT_ALERT_SECRET",
103
+ /** How old an alert delivery may be, in seconds. */
104
+ alertMaxAge: "CHANT_ALERT_MAX_AGE",
105
+ /** The token the relay starts the alert agent's workflow with: `workflow_dispatch` on GitHub and Forgejo, a pipeline trigger token on GitLab. */
106
+ alertDispatchToken: "CHANT_ALERT_DISPATCH_TOKEN",
107
+ /** The alert agent's workflow file on GitHub and Forgejo, such as `chant-alert-agent.yml`. */
108
+ alertWorkflow: "CHANT_ALERT_WORKFLOW",
77
109
  };
110
+ /** The variable holding one alert source's own secret: `CHANT_ALERT_SECRET_PAGERDUTY` and so on. */
111
+ export const alertSecretEnv = (source) => `${RELAY_ENV.alertSecret}_${source.toUpperCase()}`;
78
112
  /** The variables that stand in for `--repo`, the default `--token-env`, and `--forge` (#4759). */
79
113
  export const RELAY_REPO_ENV = {
80
114
  /** The repository's https clone address. */
@@ -283,7 +317,7 @@ export async function decideRelayClick(click, settings, deps) {
283
317
  const json = (status, body) => ({ status, headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
284
318
  const plain = (status, body) => ({ status, headers: { "content-type": "text/plain" }, body });
285
319
  /**
286
- * One request: `POST /slack`, `POST /teams`, `GET /healthz`. A Slack answer
320
+ * One request: `POST /slack`, `POST /teams`, `POST /alert/<source>`, `GET /healthz`. A Slack answer
287
321
  * goes to the click's response_url, in the message's thread, when that is
288
322
  * Slack's; a Teams answer is the reply Teams posts under the message.
289
323
  */
@@ -292,6 +326,10 @@ export async function handleRelayRequest(req, settings, deps, options = {}) {
292
326
  const path = req.path.split("?")[0];
293
327
  if (req.method === "GET" && path === "/healthz")
294
328
  return plain(200, "ok");
329
+ const alertSource = /^\/alert\/([a-z]+)$/.exec(path)?.[1];
330
+ if (req.method === "POST" && alertSource && ALERT_SOURCES.includes(alertSource) && settings.alertSecrets?.[alertSource]) {
331
+ return handleAlertRequest(alertSource, req, settings, deps, log, options.now);
332
+ }
295
333
  if (req.method !== "POST" || (path !== "/slack" && path !== "/teams"))
296
334
  return plain(404, "not found");
297
335
  if (path === "/slack") {
@@ -335,6 +373,61 @@ export async function handleRelayRequest(req, settings, deps, options = {}) {
335
373
  log(`teams: ${click.chatUser} ${click.action}: ${answer.outcome}: ${answer.text}`);
336
374
  return json(200, { type: "message", text: answer.text });
337
375
  }
376
+ /**
377
+ * `POST /alert/<source>[?member=<name>]` (#5329): check the delivery, record
378
+ * its firing alerts as signed facts, and start the alert agent's workflow
379
+ * when one was new. A fact that could not be written answers 500, so the
380
+ * source sends it again; a start that did not go through is logged, and
381
+ * the agent's schedule picks the fact up.
382
+ */
383
+ async function handleAlertRequest(source, req, settings, deps, log, nowMs) {
384
+ const now = deps.now ? deps.now() : new Date(nowMs ?? Date.now());
385
+ const member = new URLSearchParams(req.path.split("?")[1] ?? "").get("member") ?? undefined;
386
+ const read = readAlertDelivery(source, { headers: req.headers, body: req.body, ...(member !== undefined ? { member } : {}) }, settings.alertSecrets?.[source], { now, ...(settings.alertMaxAgeSeconds !== undefined ? { maxAgeSeconds: settings.alertMaxAgeSeconds } : {}) });
387
+ if (!read.ok) {
388
+ log(`alert ${source}: refused a delivery: ${read.reason}`);
389
+ return plain(read.status, read.reason);
390
+ }
391
+ if (read.alerts.length === 0) {
392
+ log(`alert ${source}: nothing firing (${read.ignored} not firing, ${read.stale} stale)`);
393
+ return json(200, { recorded: 0, duplicates: 0, ignored: read.ignored, stale: read.stale });
394
+ }
395
+ if (!settings.key || !deps.recordAlerts)
396
+ return plain(503, "the relay records no alerts: it has no relay key or no ledger");
397
+ const received = now.toISOString();
398
+ const facts = read.alerts.map((a, n) => signAgentFact(settings.key, {
399
+ trigger: "alert",
400
+ member: a.member,
401
+ key: alertKey(a),
402
+ ...(read.idempotencyKey ? { idempotencyKey: read.alerts.length === 1 ? read.idempotencyKey : `${read.idempotencyKey}#${n}` } : {}),
403
+ at: a.at,
404
+ received,
405
+ by: deps.principal,
406
+ data: { ...a },
407
+ }));
408
+ let out;
409
+ try {
410
+ out = await deps.recordAlerts(facts);
411
+ }
412
+ catch (e) {
413
+ log(`alert ${source}: could not record ${facts.length} alert${facts.length === 1 ? "" : "s"}: ${e.message}`);
414
+ return plain(500, "the alert was not recorded; send it again");
415
+ }
416
+ log(`alert ${source}: recorded ${out.recorded.length}, ${out.duplicates.length} already recorded`);
417
+ let started = false;
418
+ if (out.recorded.length > 0 && deps.dispatch) {
419
+ try {
420
+ const d = await deps.dispatch();
421
+ started = d.ok;
422
+ if (!d.ok)
423
+ log(`alert ${source}: the agent's workflow did not start (${d.error}); its schedule picks the alert up`);
424
+ }
425
+ catch (e) {
426
+ log(`alert ${source}: the agent's workflow did not start (${e.message}); its schedule picks the alert up`);
427
+ }
428
+ }
429
+ return json(200, { recorded: out.recorded.length, duplicates: out.duplicates.length, ignored: read.ignored, stale: read.stale, started });
430
+ }
338
431
  /** The largest request body the relay reads. Slack and Teams send a few kilobytes. */
339
432
  const MAX_BODY = 256 * 1024;
340
433
  function readBody(req) {
package/dist/notify.d.ts CHANGED
@@ -37,8 +37,11 @@ export declare const NOTIFY_SCHEMA_ID = "https://intentius.io/chant/schemas/noti
37
37
  * What happened. The `ci.` events come from `chant ci tick` (#4645): a branch red after its retry, a bisect's culprit, the branch green again,
38
38
  * and a branch with no green commit for `staleAfter` hours (#4678);
39
39
  * and from `chant ci quarantine report` (#4677): a quarantined test passed in the scheduled run.
40
+ * `urgent` (#5355): a promote passed a stage's gate on its urgent rule.
41
+ * `soak` (#5326): a soak check failed, so the next stage or wave is held.
42
+ * `rollback-requested` (#5328): a stage's verify or soak failed, and the stage requested its rollback to its previous release, which waits for an approval.
40
43
  */
41
- export declare const NOTIFY_EVENTS: readonly ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green", "ci.quarantine-passed", "ci.stale"];
44
+ export declare const NOTIFY_EVENTS: readonly ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green", "ci.quarantine-passed", "ci.stale", "urgent", "soak", "rollback-requested"];
42
45
  export type NotifyEventKind = (typeof NOTIFY_EVENTS)[number];
43
46
  /** Where the run is: the CI run's page, the forge, the repository and commit. */
44
47
  export interface NotifyRun {
@@ -103,6 +106,10 @@ export interface NotifyEvent {
103
106
  };
104
107
  /** On the `ci.` events (#4645): the branch and commit, and what failed or what was red. */
105
108
  ci?: NotifyCi;
109
+ /** On `soak` (#5326): what soaks, what it holds, and the checks that failed. */
110
+ soak?: NotifySoak;
111
+ /** On `rollback-requested` (#5328): what failed, the release the stage goes back to, its gate, and each member's state. */
112
+ rollback?: NotifyRollback;
106
113
  run?: NotifyRun;
107
114
  /** A report page for the run. */
108
115
  reportUrl?: string;
@@ -147,6 +154,55 @@ export interface NotifyCi {
147
154
  lastGreen?: string;
148
155
  hours?: number;
149
156
  }
157
+ /**
158
+ * The soak's part of a `soak` event (#5326): the stage (or the wave's
159
+ * environment) that soaks, the stage or wave it holds, when the clock
160
+ * started and is due, and each check that failed with what its failure does.
161
+ */
162
+ export interface NotifySoak {
163
+ stage: string;
164
+ /** On a wave's soak: the wave that soaks. */
165
+ wave?: number;
166
+ /** The stage a promotion waits to go into, or the wave that waits, as `wave <k>`. */
167
+ holds: string;
168
+ clockStart: string | null;
169
+ due: string | null;
170
+ checks: {
171
+ name: string;
172
+ kind: string;
173
+ onFail: "restart" | "hold";
174
+ status: "failed" | "unknown";
175
+ detail: string;
176
+ member?: string;
177
+ targets?: string[];
178
+ }[];
179
+ }
180
+ /**
181
+ * The rollback's part of a `rollback-requested` event (#5328): the stage,
182
+ * whether its verify or a soak check failed, the release that failed and the
183
+ * one the stage goes back to, the gate the rollback waits at, and each
184
+ * member's state with whether the rollback restores it (`requested`) or why
185
+ * not.
186
+ */
187
+ export interface NotifyRollback {
188
+ stage: string;
189
+ failure: "verify" | "soak";
190
+ failed: {
191
+ digest: string;
192
+ label: string | null;
193
+ };
194
+ to: {
195
+ digest: string;
196
+ label: string | null;
197
+ };
198
+ gate: string;
199
+ members: {
200
+ member: string;
201
+ state: "applied" | "left-applied" | "rolled-back" | "not-applied";
202
+ rollback?: string;
203
+ }[];
204
+ detail?: string[];
205
+ }
150
206
  /** What a product fills in; {@link makeNotifyEvent} adds the rest. */
151
207
  export type NotifyFields = Omit<NotifyEvent, "schema" | "id" | "at" | "project" | "targets" | "run"> & {
152
208
  id?: string;
package/dist/notify.js CHANGED
@@ -38,8 +38,11 @@ export const NOTIFY_SCHEMA_ID = "https://intentius.io/chant/schemas/notify/v1/no
38
38
  * What happened. The `ci.` events come from `chant ci tick` (#4645): a branch red after its retry, a bisect's culprit, the branch green again,
39
39
  * and a branch with no green commit for `staleAfter` hours (#4678);
40
40
  * and from `chant ci quarantine report` (#4677): a quarantined test passed in the scheduled run.
41
+ * `urgent` (#5355): a promote passed a stage's gate on its urgent rule.
42
+ * `soak` (#5326): a soak check failed, so the next stage or wave is held.
43
+ * `rollback-requested` (#5328): a stage's verify or soak failed, and the stage requested its rollback to its previous release, which waits for an approval.
41
44
  */
42
- export const NOTIFY_EVENTS = ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green", "ci.quarantine-passed", "ci.stale"];
45
+ export const NOTIFY_EVENTS = ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green", "ci.quarantine-passed", "ci.stale", "urgent", "soak", "rollback-requested"];
43
46
  /** The CI run, from its environment: GitHub Actions, Forgejo Actions or GitLab CI. */
44
47
  export function ciRun(env) {
45
48
  const out = {};
@@ -100,6 +103,9 @@ const HEADLINE = {
100
103
  "ci.green": "is green again",
101
104
  "ci.quarantine-passed": "passed a quarantined test",
102
105
  "ci.stale": "has no green commit",
106
+ urgent: "was promoted on its urgent rule",
107
+ soak: "failed a soak check",
108
+ "rollback-requested": "requested a rollback",
103
109
  };
104
110
  /** The first line of every chat message: `<source>: <summary>`, or what happened to what when there is no summary. */
105
111
  export function notifyHeadline(e) {
@@ -8,7 +8,7 @@
8
8
  "properties": {
9
9
  "schema": { "const": "chant.notify/v1" },
10
10
  "id": { "type": "string", "minLength": 1, "description": "The same for every send of one event about one digest (else drift fingerprint, else commit), so a receiver can drop a repeat; random when there is none. The delivery header carries it too." },
11
- "event": { "enum": ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green", "ci.quarantine-passed", "ci.stale"], "description": "The ci. events come from chant ci tick (#4645, ci.stale #4678), and ci.quarantine-passed from chant ci quarantine report (#4677), and carry ci." },
11
+ "event": { "enum": ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green", "ci.quarantine-passed", "ci.stale", "urgent", "soak", "rollback-requested"], "description": "The ci. events come from chant ci tick (#4645, ci.stale #4678), and ci.quarantine-passed from chant ci quarantine report (#4677), and carry ci. urgent (#5355): a promote passed a stage's gate on its urgent rule. soak (#5326) comes from a soak whose check failed, and carries soak. rollback-requested (#5328) comes from a stage whose verify or soak failed and which requested its rollback, and carries rollback." },
12
12
  "at": { "type": "string", "description": "When it was sent, ISO 8601 UTC." },
13
13
  "source": { "type": "string", "minLength": 1, "description": "The product that sent it: chant, terragucci, sql-yodeler." },
14
14
  "project": { "type": "string", "description": "What the run belongs to: the repository, or a name the product gives." },
@@ -88,11 +88,69 @@
88
88
  }
89
89
  }
90
90
  },
91
+ "soak": {
92
+ "type": "object",
93
+ "description": "On soak (#5326): the stage (or the wave's environment) that soaks, what it holds (the stage a promotion waits to go into, or wave <k>), when its clock started and is due, and each check that failed or could not be read, with what its failure does: restart starts the soak over once the check passes, hold keeps the elapsed time.",
94
+ "required": ["stage", "holds", "clockStart", "due", "checks"],
95
+ "properties": {
96
+ "stage": { "type": "string" },
97
+ "wave": { "type": "integer", "minimum": 1 },
98
+ "holds": { "type": "string" },
99
+ "clockStart": { "type": ["string", "null"] },
100
+ "due": { "type": ["string", "null"] },
101
+ "checks": {
102
+ "type": "array",
103
+ "items": {
104
+ "type": "object",
105
+ "required": ["name", "kind", "onFail", "status", "detail"],
106
+ "properties": {
107
+ "name": { "type": "string" },
108
+ "kind": { "type": "string" },
109
+ "onFail": { "enum": ["restart", "hold"] },
110
+ "status": { "enum": ["failed", "unknown"] },
111
+ "detail": { "type": "string" },
112
+ "member": { "type": "string" },
113
+ "targets": { "type": "array", "items": { "type": "string" } }
114
+ }
115
+ }
116
+ }
117
+ }
118
+ },
119
+ "rollback": {
120
+ "type": "object",
121
+ "description": "On rollback-requested (#5328): the stage, whether its verify or a soak check failed, the release that failed and the release the stage goes back to, the gate the rollback waits at, and each member's state with whether the rollback restores it (requested) or why not.",
122
+ "required": ["stage", "failure", "failed", "to", "gate", "members"],
123
+ "properties": {
124
+ "stage": { "type": "string" },
125
+ "failure": { "enum": ["verify", "soak"] },
126
+ "failed": { "$ref": "#/$defs/stageRelease" },
127
+ "to": { "$ref": "#/$defs/stageRelease" },
128
+ "gate": { "type": "string" },
129
+ "members": {
130
+ "type": "array",
131
+ "items": {
132
+ "type": "object",
133
+ "required": ["member", "state"],
134
+ "properties": {
135
+ "member": { "type": "string" },
136
+ "state": { "enum": ["applied", "left-applied", "rolled-back", "not-applied"] },
137
+ "rollback": { "type": "string" }
138
+ }
139
+ }
140
+ },
141
+ "detail": { "type": "array", "items": { "type": "string" } }
142
+ }
143
+ },
91
144
  "reportUrl": { "type": "string" },
92
145
  "rerunUrl": { "type": "string", "description": "On drift (#4818): the page where a person runs the check again, which the Slack and Teams messages open from a button." },
93
146
  "detail": { "type": "object", "description": "The product's own record of the outcome, carried whole (terragucci.outcome/v1)." }
94
147
  },
95
148
  "allOf": [
96
- { "if": { "required": ["event"], "properties": { "event": { "const": "drift" } } }, "then": { "required": ["drift"], "properties": { "drift": { "type": "object" } } } }
97
- ]
149
+ { "if": { "required": ["event"], "properties": { "event": { "const": "drift" } } }, "then": { "required": ["drift"], "properties": { "drift": { "type": "object" } } } },
150
+ { "if": { "required": ["event"], "properties": { "event": { "const": "soak" } } }, "then": { "required": ["soak"], "properties": { "soak": { "type": "object" } } } },
151
+ { "if": { "required": ["event"], "properties": { "event": { "const": "rollback-requested" } } }, "then": { "required": ["rollback"], "properties": { "rollback": { "type": "object" } } } }
152
+ ],
153
+ "$defs": {
154
+ "stageRelease": { "type": "object", "required": ["digest", "label"], "properties": { "digest": { "type": "string" }, "label": { "type": ["string", "null"] } } }
155
+ }
98
156
  }
@@ -33,6 +33,7 @@
33
33
  */
34
34
  import type { ResourceMetadata } from "./lexicon.js";
35
35
  import type { IREdge } from "./graph-ir.js";
36
+ import type { EngineFacts } from "./engine-facts.js";
36
37
  /**
37
38
  * Why a declared entity was not observed. Total: a lexicon that cannot observe
38
39
  * an entity must pick one of these, and consumers may switch exhaustively.
@@ -168,6 +169,35 @@ export interface ObservationResult {
168
169
  * instance node ids built from them.
169
170
  */
170
171
  edges?: IREdge[];
172
+ /**
173
+ * An ownership engine's facts (#4520) about what the read does not return
174
+ * as present (#5333), keyed by the graph node id the declared graph gives
175
+ * it: an entity name, or an instance node id (`./instance-nodes.ts`). The
176
+ * case it exists for is a choudoufu live root, whose `live-graph` describes
177
+ * a pending create (`ownership: "pending"`) and the objects `--owned`
178
+ * filters out (`unowned`, `foreign`), none of which is a live node.
179
+ *
180
+ * Additive metadata like {@link annotations}: nothing classifies on it, and
181
+ * an entity here is still absent or not observed. `chant graph --live
182
+ * --overlay` puts each entry on the declared node of that id
183
+ * (`carryEngineFacts` in ./graph-ir.ts), the way a present node carries
184
+ * `ResourceMetadata.facts`.
185
+ */
186
+ engineFacts?: Record<string, EngineFacts>;
187
+ /**
188
+ * Live objects the read found that no declared entity names (#5429), keyed
189
+ * by the node id the live graph gives them. The case it exists for is a
190
+ * choudoufu live root: an object the estate's marker binds that no block of
191
+ * the configuration declares, which `live-plan` lists in `bound[]` (with a
192
+ * `not-in-configuration` gap in `live-graph`) and `live-ls` lists as an
193
+ * item with `declared: false`.
194
+ *
195
+ * Kept apart from {@link resources} so the change set and the live diff
196
+ * read exactly what they read before: nothing classifies on this map.
197
+ * `chant graph --live` draws each entry as a live node, so the overlay
198
+ * paints it the way it paints any provisioned node nothing declares.
199
+ */
200
+ undeclared?: Record<string, ResourceMetadata>;
171
201
  }
172
202
  /**
173
203
  * The read a root was asked for and the one that answered. `depth` is the read
@@ -205,6 +235,10 @@ export interface NormalizedObservation {
205
235
  stackExports?: Record<string, Record<string, unknown>>;
206
236
  /** Observed relationships (chant#4528). Absent when the lexicon reported none. */
207
237
  edges?: IREdge[];
238
+ /** Engine facts about what the read does not return as present, by node id (#5333). Absent when the lexicon reported none. */
239
+ engineFacts?: Record<string, EngineFacts>;
240
+ /** Live objects no declared entity names, by node id (#5429). Absent when the lexicon reported none. */
241
+ undeclared?: Record<string, ResourceMetadata>;
208
242
  }
209
243
  /** True when `value` is the versioned {@link ObservationResult} envelope. */
210
244
  export declare function isObservationResult(value: unknown): value is ObservationResult;
@@ -104,6 +104,8 @@ export function normalizeObservation(value) {
104
104
  ...(value.rootReads && Object.keys(value.rootReads).length > 0 ? { rootReads: value.rootReads } : {}),
105
105
  ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
106
106
  ...(Array.isArray(value.edges) && value.edges.length > 0 ? { edges: value.edges } : {}),
107
+ ...(value.engineFacts && Object.keys(value.engineFacts).length > 0 ? { engineFacts: value.engineFacts } : {}),
108
+ ...(value.undeclared && Object.keys(value.undeclared).length > 0 ? { undeclared: value.undeclared } : {}),
107
109
  };
108
110
  }
109
111
  return { resources: value, unobserved: {}, queried: {}, sources: {}, notes: [] };
@@ -156,6 +158,10 @@ export function mergeObservations(parts) {
156
158
  // and two parts reporting the same edge is one edge.
157
159
  const edges = [];
158
160
  const edgeKeys = new Set();
161
+ // Engine facts (#5333) merge like annotations: per node, disjoint parts.
162
+ const engineFacts = {};
163
+ // Undeclared live objects (#5429) merge per node, like engine facts.
164
+ const undeclared = {};
159
165
  for (const part of parts) {
160
166
  Object.assign(resources, part.resources);
161
167
  Object.assign(unobserved, part.unobserved);
@@ -163,6 +169,8 @@ export function mergeObservations(parts) {
163
169
  Object.assign(sources, part.sources);
164
170
  Object.assign(annotations, part.annotations ?? {});
165
171
  Object.assign(rootReads, part.rootReads ?? {});
172
+ Object.assign(engineFacts, part.engineFacts ?? {});
173
+ Object.assign(undeclared, part.undeclared ?? {});
166
174
  for (const n of part.notes)
167
175
  notes.add(n);
168
176
  Object.assign(stackExports, part.stackExports ?? {});
@@ -176,8 +184,11 @@ export function mergeObservations(parts) {
176
184
  }
177
185
  // Present wins: a stack that could not be read does not un-observe a resource
178
186
  // another stack returned.
179
- for (const name of Object.keys(resources))
187
+ for (const name of Object.keys(resources)) {
180
188
  delete unobserved[name];
189
+ delete engineFacts[name];
190
+ delete undeclared[name];
191
+ }
181
192
  return {
182
193
  resources,
183
194
  unobserved,
@@ -188,6 +199,8 @@ export function mergeObservations(parts) {
188
199
  ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}),
189
200
  ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
190
201
  ...(edges.length > 0 ? { edges } : {}),
202
+ ...(Object.keys(engineFacts).length > 0 ? { engineFacts } : {}),
203
+ ...(Object.keys(undeclared).length > 0 ? { undeclared } : {}),
191
204
  };
192
205
  }
193
206
  /** One-line human phrasing of a reason, for CLI output. */
@@ -90,6 +90,12 @@ export interface ReviewAgentArgs {
90
90
  keyEnv?: string;
91
91
  /** Minutes the command may run. Default: 10. */
92
92
  timeout?: number;
93
+ /**
94
+ * Questions the review answers from 0 to 1 (#5325). Default: `ci.risk.questions`
95
+ * in `chant.workspace.json` on the base branch, so a pull request cannot
96
+ * change what it is asked.
97
+ */
98
+ questions?: ReviewQuestion[];
93
99
  }
94
100
  export interface ReviewAgentResult {
95
101
  mode: ReviewAgentMode;
@@ -104,6 +110,8 @@ export interface ReviewAgentResult {
104
110
  mergeRequest?: string;
105
111
  /** `handoff` mode: the file the review was written to. */
106
112
  recordFile?: string;
113
+ /** The answers to the questions (#5325), when any were asked. */
114
+ answers?: ReviewAnswers;
107
115
  }
108
116
  /** The note's hidden marker, keyed on the Op. Its prefix differs from every `reconcilePr` and behaviour marker. */
109
117
  export declare function reviewMarker(op: string): string;
@@ -112,12 +120,36 @@ export declare function reviewMarker(op: string): string;
112
120
  * read and the risk it named. A gate policy reads it back with
113
121
  * {@link parseReviewResult}, and counts it only for the head it is applying.
114
122
  */
115
- export declare function reviewResultMarker(head: string, risk: ReviewRisk | "unknown"): string;
116
- /** The head and risk a review note's first result line holds, or undefined when it has none. */
123
+ export declare function reviewResultMarker(head: string, risk: ReviewRisk | "unknown", answers?: ReviewAnswers): string;
124
+ /**
125
+ * The review's answer to each question a team wrote (#5325), by the
126
+ * question's id: from 0 (no concern) to 1, or `unknown` when the review gave
127
+ * none, or the plan was larger than the prompt carries.
128
+ */
129
+ export type ReviewAnswers = Record<string, number | "unknown">;
130
+ /** A question as the review agent asks it: its id and its text. */
131
+ export interface ReviewQuestion {
132
+ id: string;
133
+ text: string;
134
+ }
135
+ /** Answers read back as untrusted data: each id and value checked, anything else dropped. */
136
+ export declare function readReviewAnswers(value: unknown): ReviewAnswers | undefined;
137
+ /** The head, risk and answers a review note's first result line holds, or undefined when it has none. */
117
138
  export declare function parseReviewResult(body: string): {
118
139
  head: string;
119
140
  risk: ReviewRisk | "unknown";
141
+ answers?: ReviewAnswers;
120
142
  } | undefined;
143
+ /** Why every answer is `unknown` when the change set did not fit the prompt. */
144
+ export declare const REVIEW_TOO_LARGE = "the plan is larger than the review's prompt carries";
145
+ /** Whether a change set is cut in the prompt: too large for the model's context, so no answer about it stands. */
146
+ export declare function changeSetTooLarge(doc: ChangeSetDocument): boolean;
147
+ /**
148
+ * The review's answers to `questions`: each `answer <id>: <0 to 1>` line the
149
+ * review ends with, the last one for an id winning. A question with no such
150
+ * line is `unknown`, and with `tooLarge` every one is.
151
+ */
152
+ export declare function answersOf(review: string, questions: readonly ReviewQuestion[], tooLarge?: boolean): ReviewAnswers;
121
153
  /** The prefix every Op's review note starts with, for a reader that does not know the Op. */
122
154
  export declare const REVIEW_MARKER_PREFIX = "<!-- chant-review:";
123
155
  /**
@@ -138,6 +170,8 @@ export interface ReviewPromptParts {
138
170
  instructions?: string;
139
171
  instructionsPath: string;
140
172
  base: string;
173
+ /** Questions to answer (#5325), from the base branch. */
174
+ questions?: readonly ReviewQuestion[];
141
175
  }
142
176
  /** The review's prompt. Everything the author wrote and everything made from the change is quoted as data. */
143
177
  export declare function reviewPrompt(p: ReviewPromptParts): string;
@@ -150,6 +184,7 @@ export declare function reviewNoteBody(o: {
150
184
  digest: string;
151
185
  instructions: "base" | "none";
152
186
  head?: string;
187
+ answers?: ReviewAnswers;
153
188
  }): string;
154
189
  /** The variables the review command sees: the model key and process basics. Never a forge or cloud token. */
155
190
  export declare function reviewCommandEnv(env: Record<string, string | undefined>, keyEnv: string): Record<string, string>;
@@ -202,6 +237,8 @@ export interface ReviewRecord {
202
237
  exitCode: number | null;
203
238
  digest: string;
204
239
  instructions: "base" | "none";
240
+ /** The answers to the questions (#5325), when any were asked. */
241
+ answers?: ReviewAnswers;
205
242
  }
206
243
  /** A record read back as untrusted data: each field is checked, and a wrong one is dropped or refused, never passed on. */
207
244
  export declare function readReviewRecord(text: string): ReviewRecord | undefined;