@intentius/chant 0.124.108 → 0.124.110

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (342) hide show
  1. package/dist/__golden__/wave-loop/fan-out-applied.json +12 -6
  2. package/dist/__golden__/wave-loop/fan-out-apply-fails.json +8 -4
  3. package/dist/__golden__/wave-loop/fan-out-gated.json +4 -2
  4. package/dist/__golden__/wave-loop/fan-out-no-members.json +16 -8
  5. package/dist/__golden__/wave-loop/fan-out-plan-fails.json +8 -4
  6. package/dist/__golden__/wave-loop/fan-out-same-root.json +4 -2
  7. package/dist/agent-facts.d.ts +130 -0
  8. package/dist/agent-facts.js +196 -0
  9. package/dist/change-risk.d.ts +216 -0
  10. package/dist/change-risk.js +304 -0
  11. package/dist/change-set.d.ts +8 -0
  12. package/dist/ci-agent-alert.d.ts +139 -0
  13. package/dist/ci-agent-alert.js +342 -0
  14. package/dist/ci-agent-triggers.d.ts +152 -0
  15. package/dist/ci-agent-triggers.js +232 -0
  16. package/dist/ci-agent-verify-failed.d.ts +149 -0
  17. package/dist/ci-agent-verify-failed.js +191 -0
  18. package/dist/ci-agent.d.ts +136 -8
  19. package/dist/ci-agent.js +353 -26
  20. package/dist/ci-comment-commands.d.ts +8 -0
  21. package/dist/ci-comment-commands.js +17 -1
  22. package/dist/ci-comment-reject.d.ts +70 -0
  23. package/dist/ci-comment-reject.js +135 -0
  24. package/dist/ci-comment-replies.d.ts +3 -1
  25. package/dist/ci-comment-replies.js +6 -0
  26. package/dist/ci-estate/delivery.d.ts +25 -3
  27. package/dist/ci-estate/delivery.js +28 -9
  28. package/dist/ci-estate/page.d.ts +7 -3
  29. package/dist/ci-estate/page.js +19 -4
  30. package/dist/ci-estate/rows.d.ts +14 -2
  31. package/dist/ci-estate/rows.js +9 -1
  32. package/dist/ci-estate.d.ts +5 -2
  33. package/dist/ci-estate.js +3 -2
  34. package/dist/ci-handover.d.ts +2 -7
  35. package/dist/ci-handover.js +3 -20
  36. package/dist/ci-jobs.d.ts +6 -0
  37. package/dist/ci-jobs.js +17 -0
  38. package/dist/ci-note-commands.d.ts +2 -0
  39. package/dist/ci-note-commands.js +12 -1
  40. package/dist/ci-product-words.d.ts +151 -1
  41. package/dist/ci-product-words.js +1390 -3
  42. package/dist/ci-product.d.ts +100 -4
  43. package/dist/ci-product.js +99 -3
  44. package/dist/ci-respond-run.d.ts +9 -0
  45. package/dist/ci-respond-run.js +35 -4
  46. package/dist/ci-respond-summary-env.d.ts +56 -0
  47. package/dist/ci-respond-summary-env.js +81 -0
  48. package/dist/ci-respond-summary.d.ts +103 -0
  49. package/dist/ci-respond-summary.js +243 -0
  50. package/dist/ci-respond.d.ts +4 -2
  51. package/dist/ci-respond.js +4 -2
  52. package/dist/cli/command-group.js +1 -1
  53. package/dist/cli/commands/lint.js +21 -3
  54. package/dist/cli/handlers/agent.js +49 -4
  55. package/dist/cli/handlers/approve.js +3 -1
  56. package/dist/cli/handlers/build.d.ts +97 -1
  57. package/dist/cli/handlers/build.js +251 -3
  58. package/dist/cli/handlers/fan-out.js +55 -0
  59. package/dist/cli/handlers/graph.d.ts +14 -0
  60. package/dist/cli/handlers/graph.js +58 -3
  61. package/dist/cli/handlers/lifecycle-health.d.ts +7 -0
  62. package/dist/cli/handlers/lifecycle-health.js +47 -9
  63. package/dist/cli/handlers/lifecycle.js +4 -1
  64. package/dist/cli/handlers/notify-relay.d.ts +2 -2
  65. package/dist/cli/handlers/notify-relay.js +67 -7
  66. package/dist/cli/handlers/pipeline-agent.d.ts +30 -0
  67. package/dist/cli/handlers/pipeline-agent.js +255 -0
  68. package/dist/cli/handlers/pipeline-artifacts.d.ts +39 -0
  69. package/dist/cli/handlers/pipeline-artifacts.js +203 -0
  70. package/dist/cli/handlers/pipeline.d.ts +16 -0
  71. package/dist/cli/handlers/pipeline.js +112 -0
  72. package/dist/cli/handlers/pr-comment.js +4 -0
  73. package/dist/cli/handlers/pr-notes.js +4 -1
  74. package/dist/cli/handlers/pr.d.ts +20 -0
  75. package/dist/cli/handlers/pr.js +114 -11
  76. package/dist/cli/handlers/promote.js +792 -47
  77. package/dist/cli/handlers/reject.d.ts +84 -0
  78. package/dist/cli/handlers/reject.js +216 -0
  79. package/dist/cli/handlers/release.js +4 -2
  80. package/dist/cli/handlers/replan.d.ts +54 -0
  81. package/dist/cli/handlers/replan.js +177 -0
  82. package/dist/cli/handlers/run-generate.d.ts +5 -0
  83. package/dist/cli/handlers/run-generate.js +31 -4
  84. package/dist/cli/handlers/run-wave.js +15 -2
  85. package/dist/cli/handlers/run.js +4 -2
  86. package/dist/cli/handlers/stage.d.ts +35 -0
  87. package/dist/cli/handlers/stage.js +90 -0
  88. package/dist/cli/lsp/server.js +4 -0
  89. package/dist/cli/main.js +88 -8
  90. package/dist/cli/parse-args.js +35 -2
  91. package/dist/cli/registry.d.ts +12 -0
  92. package/dist/components/auto-release.d.ts +2 -0
  93. package/dist/components/auto-release.js +1 -0
  94. package/dist/components/capability.d.ts +40 -0
  95. package/dist/components/cli-support.d.ts +21 -1
  96. package/dist/components/cli-support.js +28 -6
  97. package/dist/components/component.d.ts +23 -4
  98. package/dist/components/component.schema.json +28 -0
  99. package/dist/components/declared-reads.d.ts +44 -4
  100. package/dist/components/declared-reads.js +80 -3
  101. package/dist/components/discover.d.ts +8 -0
  102. package/dist/components/discover.js +1 -1
  103. package/dist/components/driver.d.ts +13 -0
  104. package/dist/components/driver.js +23 -2
  105. package/dist/components/environment-sets.d.ts +229 -0
  106. package/dist/components/environment-sets.js +338 -0
  107. package/dist/components/fan-out-canary.d.ts +47 -0
  108. package/dist/components/fan-out-canary.js +58 -0
  109. package/dist/components/fan-out-run.d.ts +17 -0
  110. package/dist/components/fan-out-run.js +14 -1
  111. package/dist/components/fan-out-support.d.ts +7 -0
  112. package/dist/components/fan-out-support.js +1 -1
  113. package/dist/components/groups.d.ts +8 -1
  114. package/dist/components/groups.js +19 -1
  115. package/dist/components/index.d.ts +5 -2
  116. package/dist/components/index.js +4 -1
  117. package/dist/components/pr-cost.d.ts +28 -0
  118. package/dist/components/pr-cost.js +53 -0
  119. package/dist/components/pr-pipeline.d.ts +33 -0
  120. package/dist/components/pr-pipeline.js +32 -5
  121. package/dist/components/pr-policy.d.ts +33 -2
  122. package/dist/components/pr-policy.js +5 -2
  123. package/dist/components/pr-risk.d.ts +42 -0
  124. package/dist/components/pr-risk.js +74 -0
  125. package/dist/components/product-pipeline.d.ts +43 -0
  126. package/dist/components/product-pipeline.js +67 -1
  127. package/dist/components/promote.d.ts +6 -0
  128. package/dist/components/promote.js +13 -0
  129. package/dist/components/release-compile.js +3 -1
  130. package/dist/components/release-gate.d.ts +6 -1
  131. package/dist/components/release-gate.js +10 -2
  132. package/dist/components/step-environments.d.ts +236 -0
  133. package/dist/components/step-environments.js +392 -0
  134. package/dist/components/upstream-replan.d.ts +201 -0
  135. package/dist/components/upstream-replan.js +249 -0
  136. package/dist/components/verify-step.d.ts +30 -0
  137. package/dist/components/verify-step.js +27 -0
  138. package/dist/components/wave-plan.js +6 -2
  139. package/dist/config-environments.d.ts +4 -2
  140. package/dist/control/dispatch.d.ts +15 -0
  141. package/dist/control/dispatch.js +28 -4
  142. package/dist/cost-estimate.d.ts +188 -0
  143. package/dist/cost-estimate.js +363 -0
  144. package/dist/drift-record.d.ts +36 -0
  145. package/dist/drift-record.js +44 -0
  146. package/dist/engine-facts.d.ts +105 -0
  147. package/dist/engine-facts.js +111 -0
  148. package/dist/exit-codes.d.ts +4 -3
  149. package/dist/exit-codes.js +4 -3
  150. package/dist/flag-params.d.ts +2 -2
  151. package/dist/flag-params.js +9 -4
  152. package/dist/floor-table.data.js +53 -0
  153. package/dist/forge-token-vars.d.ts +12 -0
  154. package/dist/forge-token-vars.js +25 -0
  155. package/dist/gate-decision.d.ts +3 -1
  156. package/dist/gate-decision.js +3 -1
  157. package/dist/gated-waves.d.ts +2 -0
  158. package/dist/gated-waves.js +1 -0
  159. package/dist/graph-ir.d.ts +30 -0
  160. package/dist/graph-ir.js +33 -1
  161. package/dist/graph-refs.d.ts +26 -0
  162. package/dist/graph-refs.js +34 -3
  163. package/dist/graph-schema/graph.schema.json +136 -0
  164. package/dist/health.d.ts +65 -0
  165. package/dist/health.js +62 -0
  166. package/dist/lexicon.d.ts +188 -1
  167. package/dist/lifecycle/disruption.d.ts +14 -1
  168. package/dist/lifecycle/disruption.js +5 -1
  169. package/dist/lifecycle/gate-change-set.d.ts +8 -0
  170. package/dist/lifecycle/gate-change-set.js +2 -1
  171. package/dist/lifecycle/gate-ledger.d.ts +26 -0
  172. package/dist/lifecycle/gate-rejection.d.ts +82 -0
  173. package/dist/lifecycle/gate-rejection.js +93 -0
  174. package/dist/lifecycle/gate-seal.d.ts +3 -3
  175. package/dist/lifecycle/gate-seal.js +5 -5
  176. package/dist/lifecycle/observe.d.ts +17 -0
  177. package/dist/lifecycle/observe.js +10 -1
  178. package/dist/lifecycle/release-cut.js +4 -0
  179. package/dist/lifecycle/release-ledger.d.ts +8 -0
  180. package/dist/lifecycle/release-risk.d.ts +137 -0
  181. package/dist/lifecycle/release-risk.js +214 -0
  182. package/dist/lifecycle/release-store.d.ts +9 -0
  183. package/dist/lifecycle/release-store.js +4 -0
  184. package/dist/lifecycle/stage-log.d.ts +85 -0
  185. package/dist/lifecycle/stage-log.js +141 -0
  186. package/dist/lint/canary-checks.d.ts +31 -0
  187. package/dist/lint/canary-checks.js +45 -0
  188. package/dist/lint/rule.d.ts +1 -0
  189. package/dist/lint/rules/evl012-pipeline-fold.d.ts +14 -0
  190. package/dist/lint/rules/evl012-pipeline-fold.js +30 -0
  191. package/dist/lint/rules/index.d.ts +1 -0
  192. package/dist/lint/rules/index.js +3 -0
  193. package/dist/notify-relay-repo.d.ts +54 -0
  194. package/dist/notify-relay-repo.js +84 -0
  195. package/dist/notify-relay.d.ts +53 -3
  196. package/dist/notify-relay.js +96 -3
  197. package/dist/notify.d.ts +57 -1
  198. package/dist/notify.js +7 -1
  199. package/dist/notify.schema.json +61 -3
  200. package/dist/observation.d.ts +34 -0
  201. package/dist/observation.js +14 -1
  202. package/dist/op/activities/review-agent.d.ts +39 -2
  203. package/dist/op/activities/review-agent.js +88 -5
  204. package/dist/op/agent-permit.d.ts +88 -0
  205. package/dist/op/agent-permit.js +97 -0
  206. package/dist/op/gate-approval-base.d.ts +8 -0
  207. package/dist/op/gate-approval-base.js +9 -0
  208. package/dist/op/gate-approval.d.ts +30 -1
  209. package/dist/op/gate-approval.js +23 -2
  210. package/dist/op/gate-quorum.d.ts +114 -8
  211. package/dist/op/gate-quorum.js +198 -21
  212. package/dist/op/gate-reject.d.ts +79 -0
  213. package/dist/op/gate-reject.js +96 -0
  214. package/dist/op/gate-summary.js +1 -1
  215. package/dist/op/gate.d.ts +28 -3
  216. package/dist/op/gate.js +55 -13
  217. package/dist/op/generate-pipeline.d.ts +15 -1
  218. package/dist/op/generate-pipeline.js +32 -5
  219. package/dist/op/index.d.ts +11 -6
  220. package/dist/op/index.js +10 -5
  221. package/dist/op/local-executor.d.ts +2 -0
  222. package/dist/op/local-executor.js +23 -4
  223. package/dist/op/op-waves-after-plan.d.ts +23 -0
  224. package/dist/op/op-waves-after-plan.js +12 -1
  225. package/dist/op/op-waves-capability-spec.d.ts +14 -0
  226. package/dist/op/op-waves-capability-spec.js +46 -6
  227. package/dist/op/op-waves-capability.d.ts +21 -13
  228. package/dist/op/op-waves-capability.js +22 -59
  229. package/dist/op/op-waves-environment-sets.d.ts +41 -0
  230. package/dist/op/op-waves-environment-sets.js +82 -0
  231. package/dist/op/op-waves-quorum-warnings.d.ts +53 -0
  232. package/dist/op/op-waves-quorum-warnings.js +90 -0
  233. package/dist/op/op-waves-release-port.d.ts +7 -0
  234. package/dist/op/op-waves-release-port.js +15 -3
  235. package/dist/op/op-waves-release.d.ts +15 -0
  236. package/dist/op/op-waves-release.js +15 -0
  237. package/dist/op/op-waves-run.d.ts +37 -3
  238. package/dist/op/op-waves-run.js +141 -18
  239. package/dist/op/op-waves-soak.d.ts +57 -0
  240. package/dist/op/op-waves-soak.js +111 -0
  241. package/dist/op/op-waves-split.d.ts +4 -0
  242. package/dist/op/op-waves-split.js +4 -0
  243. package/dist/op/op-waves.d.ts +67 -4
  244. package/dist/op/op-waves.js +71 -3
  245. package/dist/pipeline/agent-ajv.d.ts +4 -0
  246. package/dist/pipeline/agent-ajv.js +14 -0
  247. package/dist/pipeline/agent-steps.d.ts +329 -0
  248. package/dist/pipeline/agent-steps.js +602 -0
  249. package/dist/pipeline/artifacts.d.ts +264 -0
  250. package/dist/pipeline/artifacts.js +425 -0
  251. package/dist/pipeline/diff.d.ts +45 -0
  252. package/dist/pipeline/diff.js +177 -0
  253. package/dist/pipeline/fold.d.ts +43 -0
  254. package/dist/pipeline/fold.js +140 -0
  255. package/dist/pipeline/generate.d.ts +52 -0
  256. package/dist/pipeline/generate.js +120 -0
  257. package/dist/pipeline/product.d.ts +225 -0
  258. package/dist/pipeline/product.js +257 -0
  259. package/dist/pipeline/promote.d.ts +404 -0
  260. package/dist/pipeline/promote.js +694 -0
  261. package/dist/pipeline/read.d.ts +37 -0
  262. package/dist/pipeline/read.js +58 -0
  263. package/dist/pipeline/rendered.d.ts +25 -0
  264. package/dist/pipeline/rendered.js +53 -0
  265. package/dist/pipeline/soak-checks.d.ts +80 -0
  266. package/dist/pipeline/soak-checks.js +254 -0
  267. package/dist/pipeline/soak-gate.d.ts +97 -0
  268. package/dist/pipeline/soak-gate.js +176 -0
  269. package/dist/pipeline/soak-sources.d.ts +17 -0
  270. package/dist/pipeline/soak-sources.js +42 -0
  271. package/dist/pipeline/soak.d.ts +260 -0
  272. package/dist/pipeline/soak.js +378 -0
  273. package/dist/pipeline/spec.d.ts +724 -0
  274. package/dist/pipeline/spec.js +567 -0
  275. package/dist/pipeline/stage-ledger.d.ts +187 -0
  276. package/dist/pipeline/stage-ledger.js +185 -0
  277. package/dist/pipeline/stage-waves.d.ts +114 -0
  278. package/dist/pipeline/stage-waves.js +161 -0
  279. package/dist/pipeline/stages.d.ts +64 -0
  280. package/dist/pipeline/stages.js +174 -0
  281. package/dist/pipeline/verify-rollback.d.ts +277 -0
  282. package/dist/pipeline/verify-rollback.js +393 -0
  283. package/dist/pipeline.d.ts +142 -0
  284. package/dist/pipeline.js +143 -0
  285. package/dist/pr-loop.d.ts +22 -0
  286. package/dist/pr-loop.js +8 -0
  287. package/dist/pr-plan-note.d.ts +15 -1
  288. package/dist/pr-plan-note.js +8 -0
  289. package/dist/pr-post.d.ts +31 -0
  290. package/dist/pr-post.js +89 -0
  291. package/dist/release-floors.d.ts +1 -1
  292. package/dist/release-floors.js +1 -1
  293. package/dist/report-store/audit.schema.json +50 -0
  294. package/dist/report-store/dora.schema.json +331 -0
  295. package/dist/report-store/estate.schema.json +96 -0
  296. package/dist/report-store/run.schema.json +14 -0
  297. package/dist/report-store.d.ts +151 -0
  298. package/dist/report-store.js +344 -0
  299. package/dist/run-event.d.ts +7 -2
  300. package/dist/wave-runtime.mjs +458 -404
  301. package/dist/workspace/catalog-edges.js +3 -3
  302. package/dist/workspace/change-set.schema.json +4 -0
  303. package/dist/workspace/ci-cloud-identity.d.ts +4 -0
  304. package/dist/workspace/ci-cloud-identity.js +30 -0
  305. package/dist/workspace/ci-run.js +17 -2
  306. package/dist/workspace/ci-secrets.d.ts +3 -1
  307. package/dist/workspace/ci-secrets.js +7 -1
  308. package/dist/workspace/compose-graph.d.ts +1 -1
  309. package/dist/workspace/compose-graph.js +3 -1
  310. package/dist/workspace/declaration.d.ts +27 -0
  311. package/dist/workspace/declaration.js +35 -0
  312. package/dist/workspace/declaration.schema.json +56 -0
  313. package/dist/workspace/graph-cli.js +26 -0
  314. package/dist/workspace/graph.schema.json +5 -1
  315. package/dist/workspace/identity-gate-rule.d.ts +4 -0
  316. package/dist/workspace/identity-gate-rule.js +2 -2
  317. package/dist/workspace/identity-reject-rule.d.ts +14 -0
  318. package/dist/workspace/identity-reject-rule.js +24 -0
  319. package/dist/workspace/identity.d.ts +3 -0
  320. package/dist/workspace/identity.js +2 -1
  321. package/dist/workspace/nested-graph.js +2 -0
  322. package/dist/workspace/pr-report.schema.json +65 -0
  323. package/dist/workspace/promotion-order.d.ts +19 -4
  324. package/dist/workspace/promotion-order.js +26 -4
  325. package/dist/workspace/release-train.d.ts +14 -0
  326. package/dist/workspace/release-train.js +32 -0
  327. package/dist/workspace/run-event.schema.json +2 -2
  328. package/dist/workspace/stack-read-edges.d.ts +19 -0
  329. package/dist/workspace/stack-read-edges.js +54 -0
  330. package/dist/workspace/status-gates.d.ts +51 -1
  331. package/dist/workspace/status-gates.js +60 -0
  332. package/dist/workspace/status-stages.d.ts +223 -0
  333. package/dist/workspace/status-stages.js +279 -0
  334. package/dist/workspace/status.d.ts +45 -1
  335. package/dist/workspace/status.js +109 -5
  336. package/dist/workspace/status.schema.json +283 -2
  337. package/dist/workspace/train-cut.js +5 -2
  338. package/dist/workspace/train-shell.d.ts +18 -0
  339. package/dist/workspace/train-shell.js +43 -0
  340. package/dist/workspace/trust/seal.d.ts +7 -0
  341. package/dist/workspace/trust/seal.js +9 -0
  342. package/package.json +5 -1
@@ -0,0 +1,141 @@
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
+ import { readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, pushLifecycleRebasing, LifecyclePushLostError, RefCASConflictError } from "./git.js";
22
+ import { sortedJsonReplacer } from "../utils.js";
23
+ /** Where a pipeline's stage log lives, as `writeBlobToPath` takes it. */
24
+ export function stageLogPath(op) {
25
+ return { dir: `_gates/${op}`, file: "stages.jsonl" };
26
+ }
27
+ /** The lines of a `stages.jsonl` file, oldest first. A line that is not one is skipped. */
28
+ export function parseStageLines(text) {
29
+ const out = [];
30
+ for (const raw of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
31
+ let r;
32
+ try {
33
+ r = JSON.parse(raw);
34
+ }
35
+ catch {
36
+ continue;
37
+ }
38
+ if (r?.version !== 1 || !["waiting", "replaced", "entered", "finished"].includes(r.kind))
39
+ continue;
40
+ if (typeof r.op !== "string" || typeof r.stage !== "string" || typeof r.digest !== "string" || typeof r.timestamp !== "string")
41
+ continue;
42
+ if (r.kind === "finished" && r.result !== "applied" && r.result !== "failed")
43
+ continue;
44
+ if (r.kind === "replaced" && typeof r.by !== "string")
45
+ continue;
46
+ out.push(r);
47
+ }
48
+ return out;
49
+ }
50
+ const at = (iso) => Date.parse(iso);
51
+ /** Stage `stage` as `lines` record it. */
52
+ export function stageQueueOf(lines, stage) {
53
+ const own = lines.filter((l) => l.stage === stage);
54
+ let inStage = null;
55
+ const waiting = new Map();
56
+ const replaced = [];
57
+ for (const line of own) {
58
+ if (line.kind === "waiting") {
59
+ if (!waiting.has(line.digest))
60
+ waiting.set(line.digest, line);
61
+ }
62
+ else if (line.kind === "replaced") {
63
+ waiting.delete(line.digest);
64
+ replaced.push(line);
65
+ }
66
+ else if (line.kind === "entered") {
67
+ waiting.delete(line.digest);
68
+ inStage = line;
69
+ }
70
+ else {
71
+ waiting.delete(line.digest);
72
+ if (inStage?.digest === line.digest)
73
+ inStage = null;
74
+ }
75
+ }
76
+ return { stage, inStage, waiting: [...waiting.values()].sort((a, b) => at(a.timestamp) - at(b.timestamp)), replaced };
77
+ }
78
+ /** The `replaced` line that keeps `digest` out of `stage`, or undefined. */
79
+ export function replacedIn(lines, stage, digest) {
80
+ return lines.find((l) => l.kind === "replaced" && l.stage === stage && l.digest === digest);
81
+ }
82
+ /** Whether the release `digest` was applied in `stage`: a `finished` line with result `applied` names it. */
83
+ export function succeededIn(lines, stage, digest) {
84
+ return lines.some((l) => l.kind === "finished" && l.result === "applied" && l.stage === stage && l.digest === digest);
85
+ }
86
+ /** Every stage the log names, in the order first met. */
87
+ export function stagesInLog(lines) {
88
+ return [...new Set(lines.map((l) => l.stage))];
89
+ }
90
+ /** The log held in memory, for tests and for a caller that read it already. */
91
+ export function memoryStageLogPort(seed = []) {
92
+ const lines = [...seed];
93
+ return {
94
+ lines,
95
+ async read(op) {
96
+ return lines.filter((l) => l.op === op);
97
+ },
98
+ async append(line) {
99
+ lines.push(line);
100
+ return { pushed: true };
101
+ },
102
+ };
103
+ }
104
+ /** The log on `chant/lifecycle`: each append lands on top of the remote's ledger, retrying a concurrent writer, then pushes. */
105
+ export function gitStageLogPort(opts) {
106
+ return {
107
+ async read(op) {
108
+ await requireLifecycleLedger(opts);
109
+ const { dir, file } = stageLogPath(op);
110
+ const text = await readBlobFromPath(dir, file, opts);
111
+ return text ? parseStageLines(text) : [];
112
+ },
113
+ async append(line) {
114
+ const { dir, file } = stageLogPath(line.op);
115
+ const json = JSON.stringify(line, sortedJsonReplacer);
116
+ await requireLifecycleLedger(opts);
117
+ let lastErr;
118
+ for (let attempt = 1; attempt <= 5; attempt++) {
119
+ try {
120
+ const prior = await readPathSha(dir, file, opts);
121
+ const existing = prior ? await readBlobBySha(prior, opts) : null;
122
+ await writeBlobToPath(dir, file, existing ? `${existing.replace(/\n$/, "")}\n${json}\n` : `${json}\n`, `Stage ${line.stage} of ${line.op}: ${line.kind} ${line.digest}`, { ...opts, expectPriorPathSha: prior });
123
+ try {
124
+ return await pushLifecycleRebasing(opts);
125
+ }
126
+ catch (err) {
127
+ if (err instanceof LifecyclePushLostError)
128
+ return { pushed: false, pushWarning: `LifecyclePushLostError: ${err.message}` };
129
+ throw err;
130
+ }
131
+ }
132
+ catch (err) {
133
+ if (!(err instanceof RefCASConflictError))
134
+ throw err;
135
+ lastErr = err;
136
+ }
137
+ }
138
+ throw lastErr;
139
+ },
140
+ };
141
+ }
@@ -0,0 +1,31 @@
1
+ import type { LintDiagnostic } from "./rule.js";
2
+ import type { EnvironmentDeclaration } from "../config-environments.js";
3
+ /**
4
+ * COR027: Canary Without Soak Checks (#5327)
5
+ *
6
+ * A canary holds the steps after it through its soak: a pipeline stage
7
+ * marked `canary` reads its soak's checks before any later stage opens its
8
+ * gate. An entry of a member's `environments` in `chant.config.ts` can be
9
+ * marked `canary: true`, and it carries no soak, so it holds nothing. That
10
+ * existing config keeps working and is a warning; in `.chant/pipeline.ts` a
11
+ * canary stage with no soak checks is refused by the spec check (EVL012).
12
+ *
13
+ * A member with a `.chant/pipeline.ts` promotes by its pipeline, whose own
14
+ * check covers its canary, so the warning is for a member without one.
15
+ * Run by `chant lint` over the project config, like the COMP checks, since
16
+ * it reads the loaded config and not one source file.
17
+ */
18
+ export declare const CANARY_WITHOUT_SOAK_CHECK_ID = "COR027";
19
+ /** What {@link canaryConfigDiagnostics} reads. */
20
+ export interface CanaryConfigInput {
21
+ /** The member's `chant.config.ts`, for the diagnostic's file. */
22
+ configPath: string;
23
+ /** Its text, to point at the `canary` line; absent, the diagnostics point at line 1. */
24
+ configText?: string;
25
+ /** The loaded config's `environments`. */
26
+ environments: readonly EnvironmentDeclaration[] | undefined;
27
+ /** Whether the member has a `.chant/pipeline.ts`. */
28
+ hasPipeline: boolean;
29
+ }
30
+ /** One COR027 warning per `environments` entry marked canary, in a member with no pipeline. */
31
+ export declare function canaryConfigDiagnostics(input: CanaryConfigInput): LintDiagnostic[];
@@ -0,0 +1,45 @@
1
+ /**
2
+ * COR027: Canary Without Soak Checks (#5327)
3
+ *
4
+ * A canary holds the steps after it through its soak: a pipeline stage
5
+ * marked `canary` reads its soak's checks before any later stage opens its
6
+ * gate. An entry of a member's `environments` in `chant.config.ts` can be
7
+ * marked `canary: true`, and it carries no soak, so it holds nothing. That
8
+ * existing config keeps working and is a warning; in `.chant/pipeline.ts` a
9
+ * canary stage with no soak checks is refused by the spec check (EVL012).
10
+ *
11
+ * A member with a `.chant/pipeline.ts` promotes by its pipeline, whose own
12
+ * check covers its canary, so the warning is for a member without one.
13
+ * Run by `chant lint` over the project config, like the COMP checks, since
14
+ * it reads the loaded config and not one source file.
15
+ */
16
+ export const CANARY_WITHOUT_SOAK_CHECK_ID = "COR027";
17
+ /** The line of the `n`-th `canary: true` in `text`, 1-based; 1 when there is none. */
18
+ function canaryLine(text, n) {
19
+ if (text === undefined)
20
+ return 1;
21
+ const lines = text.split("\n");
22
+ let seen = 0;
23
+ for (let i = 0; i < lines.length; i++) {
24
+ const found = lines[i].match(/\bcanary\s*:\s*true\b/g)?.length ?? 0;
25
+ if (seen + found > n)
26
+ return i + 1;
27
+ seen += found;
28
+ }
29
+ return 1;
30
+ }
31
+ /** One COR027 warning per `environments` entry marked canary, in a member with no pipeline. */
32
+ export function canaryConfigDiagnostics(input) {
33
+ if (input.hasPipeline)
34
+ return [];
35
+ const canaries = (input.environments ?? []).filter((e) => typeof e !== "string" && e.canary === true);
36
+ return canaries.map((entry, n) => ({
37
+ file: input.configPath,
38
+ line: canaryLine(input.configText, n),
39
+ column: 1,
40
+ ruleId: CANARY_WITHOUT_SOAK_CHECK_ID,
41
+ severity: "warning",
42
+ message: `Environment "${entry.name}" is marked canary, and an environments entry has no soak checks, so the environments after it go on without waiting for it. ` +
43
+ `Declare the stages in .chant/pipeline.ts, mark the stage canary and give it a soak with checks.`,
44
+ }));
45
+ }
@@ -73,6 +73,7 @@ export interface LintProjectConfig {
73
73
  environments?: Array<string | {
74
74
  name: string;
75
75
  endpoint?: string;
76
+ canary?: boolean;
76
77
  }>;
77
78
  /** Ownership marking config — `env` is a literal or a build-parameter reference (#1396). */
78
79
  ownership?: {
@@ -0,0 +1,14 @@
1
+ import type { LintRule } from "../rule.js";
2
+ /**
3
+ * EVL012: a pipeline declaration that does not fold (#5324).
4
+ *
5
+ * A member's `.chant/pipeline.ts` is folded, never run. This rule runs the
6
+ * same fold `chant build` runs and reports its finding at the same line, so
7
+ * `chant lint`, the LSP and the build agree. A subset violation keeps the
8
+ * rule id the classifier gives it (EVL001, EVL003); a file whose shape is
9
+ * not a pipeline declaration, or a declaration the spec check refuses, is
10
+ * EVL012.
11
+ */
12
+ /** Whether `path` is a member's pipeline declaration. */
13
+ export declare function isPipelineFile(path: string): boolean;
14
+ export declare const evl012PipelineFoldRule: LintRule;
@@ -0,0 +1,30 @@
1
+ import { foldPipelineSource, PIPELINE_FOLD_RULE } from "../../pipeline/fold.js";
2
+ /**
3
+ * EVL012: a pipeline declaration that does not fold (#5324).
4
+ *
5
+ * A member's `.chant/pipeline.ts` is folded, never run. This rule runs the
6
+ * same fold `chant build` runs and reports its finding at the same line, so
7
+ * `chant lint`, the LSP and the build agree. A subset violation keeps the
8
+ * rule id the classifier gives it (EVL001, EVL003); a file whose shape is
9
+ * not a pipeline declaration, or a declaration the spec check refuses, is
10
+ * EVL012.
11
+ */
12
+ /** Whether `path` is a member's pipeline declaration. */
13
+ export function isPipelineFile(path) {
14
+ return /(^|[\\/])\.chant[\\/]pipeline\.ts$/.test(path);
15
+ }
16
+ export const evl012PipelineFoldRule = {
17
+ id: PIPELINE_FOLD_RULE,
18
+ severity: "error",
19
+ category: "correctness",
20
+ description: "A pipeline declaration (.chant/pipeline.ts) folds to its spec without running: literals, consts and `export default pipeline({ ... })`",
21
+ check(context) {
22
+ if (!isPipelineFile(context.filePath))
23
+ return [];
24
+ const folded = foldPipelineSource(context.sourceFile.getFullText(), context.filePath);
25
+ if ("spec" in folded)
26
+ return [];
27
+ const { finding } = folded;
28
+ return [{ file: context.filePath, line: finding.line, column: finding.column, ruleId: finding.ruleId, severity: "error", message: `The pipeline does not fold: ${finding.message}` }];
29
+ },
30
+ };
@@ -23,6 +23,7 @@ export { evl007InvalidSiblingsRule } from "./evl007-invalid-siblings.js";
23
23
  export { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant.js";
24
24
  export { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform.js";
25
25
  export { evl011SymbolicInTemplateRule } from "./evl011-symbolic-in-template.js";
26
+ export { evl012PipelineFoldRule, isPipelineFile } from "./evl012-pipeline-fold.js";
26
27
  export { cor017CompositeNameMatchRule } from "./cor017-composite-name-match.js";
27
28
  export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type.js";
28
29
  export { cor021EnvLiteralNameRule } from "./cor021-env-literal-name.js";
@@ -22,6 +22,7 @@ export { evl007InvalidSiblingsRule } from "./evl007-invalid-siblings.js";
22
22
  export { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant.js";
23
23
  export { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform.js";
24
24
  export { evl011SymbolicInTemplateRule } from "./evl011-symbolic-in-template.js";
25
+ export { evl012PipelineFoldRule, isPipelineFile } from "./evl012-pipeline-fold.js";
25
26
  export { cor017CompositeNameMatchRule } from "./cor017-composite-name-match.js";
26
27
  export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type.js";
27
28
  export { cor021EnvLiteralNameRule } from "./cor021-env-literal-name.js";
@@ -55,6 +56,7 @@ import { cor021EnvLiteralNameRule } from "./cor021-env-literal-name.js";
55
56
  import { cor022ReceiptLeafRule } from "./cor022-receipt-leaf.js";
56
57
  import { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer.js";
57
58
  import { noLiteralKeyRule } from "./sys001-no-literal-key.js";
59
+ import { evl012PipelineFoldRule } from "./evl012-pipeline-fold.js";
58
60
  /**
59
61
  * Load all core lint rules (COR + EVL + SYS001).
60
62
  */
@@ -80,6 +82,7 @@ export function loadCoreRules() {
80
82
  evl009CompositeNoConstantRule,
81
83
  evl010CompositeNoTransformRule,
82
84
  evl011SymbolicInTemplateRule,
85
+ evl012PipelineFoldRule,
83
86
  cor017CompositeNameMatchRule,
84
87
  cor018CompositePreferLexiconTypeRule,
85
88
  cor021EnvLiteralNameRule,
@@ -128,3 +128,57 @@ export declare function prepareRelayCheckout(o: {
128
128
  }): Promise<RelayCheckout | {
129
129
  error: string;
130
130
  }>;
131
+ /**
132
+ * What a dispatch token reaches, as {@link readDispatchReach} reads it.
133
+ *
134
+ * - GitHub: whether it is a classic token, whether its account administers
135
+ * the repository, and what a ref creation that cannot succeed answered
136
+ * (an all-zero commit): 403 or 404 when the token cannot write contents,
137
+ * 422 when it can and only the commit was wrong.
138
+ * - Forgejo: whether its user administers the repository or may push.
139
+ * - GitLab: whether it is a pipeline trigger token (`glptt-`), and whether
140
+ * the API takes it as an access token.
141
+ */
142
+ export type DispatchReach = {
143
+ kind: "github";
144
+ classic: boolean;
145
+ admin: boolean;
146
+ refWrite: number;
147
+ } | {
148
+ kind: "forgejo";
149
+ admin: boolean;
150
+ push: boolean;
151
+ } | {
152
+ kind: "gitlab";
153
+ trigger: boolean;
154
+ apiToken: boolean;
155
+ };
156
+ /** Read what a dispatch token reaches in `repo`. Throws when a read the check needs is refused. */
157
+ export declare function readDispatchReach(repo: RelayRepo, token: string, fetchImpl?: ForgeFetch): Promise<DispatchReach>;
158
+ /** Why a token reaching `reach` can do more than start a workflow, or null when it can only do that. */
159
+ export declare function dispatchTokenVerdict(reach: DispatchReach, repoPath: string): string | null;
160
+ /** Read what the dispatch token reaches, and judge it. Never throws. */
161
+ export declare function checkDispatchToken(repo: RelayRepo, token: string, fetchImpl?: ForgeFetch): Promise<{
162
+ ok: true;
163
+ } | {
164
+ error: string;
165
+ }>;
166
+ /** A workflow file name the dispatch names, such as `chant-alert-agent.yml`. */
167
+ export declare const WORKFLOW_FILE: RegExp;
168
+ /**
169
+ * Start the alert agent's workflow on `branch` with no inputs: a
170
+ * `workflow_dispatch` of `workflow` on GitHub and Forgejo, a pipeline from
171
+ * the trigger token on GitLab.
172
+ */
173
+ export declare function dispatchAgentWorkflow(o: {
174
+ repo: RelayRepo;
175
+ token: string;
176
+ branch: string;
177
+ workflow?: string;
178
+ fetch?: ForgeFetch;
179
+ }): Promise<{
180
+ ok: true;
181
+ } | {
182
+ ok: false;
183
+ error: string;
184
+ }>;
@@ -200,3 +200,87 @@ export async function prepareRelayCheckout(o) {
200
200
  return cloned;
201
201
  return { dir: cloned.dir, branch: probe.branch, repo, user: checked.user, gitEnv };
202
202
  }
203
+ /** Read what a dispatch token reaches in `repo`. Throws when a read the check needs is refused. */
204
+ export async function readDispatchReach(repo, token, fetchImpl = globalThis.fetch) {
205
+ if (repo.forge === "gitlab") {
206
+ const res = await fetchImpl(`${repo.apiBase}/personal_access_tokens/self`, { method: "GET", headers: authHeaders("gitlab", token) });
207
+ return { kind: "gitlab", trigger: token.startsWith("glptt-"), apiToken: res.ok };
208
+ }
209
+ const headers = authHeaders(repo.forge, token);
210
+ const at = `${repo.apiBase}/repos/${repo.path}`;
211
+ const r = await fetchImpl(at, { method: "GET", headers });
212
+ if (!r.ok)
213
+ throw new Error(`GET /repos/${repo.path} answered ${r.status}`);
214
+ const text = await r.text();
215
+ const body = text ? JSON.parse(text) : null;
216
+ const perms = isObject(body) && isObject(body.permissions) ? body.permissions : {};
217
+ if (repo.forge === "forgejo")
218
+ return { kind: "forgejo", admin: perms.admin === true, push: perms.push !== false };
219
+ const classic = Boolean(r.headers?.get("x-oauth-scopes"));
220
+ const probe = await fetchImpl(`${at}/git/refs`, { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify({ ref: "refs/chant/dispatch-probe", sha: "0".repeat(40) }) });
221
+ return { kind: "github", classic, admin: perms.admin === true, refWrite: probe.status };
222
+ }
223
+ /** Why a token reaching `reach` can do more than start a workflow, or null when it can only do that. */
224
+ export function dispatchTokenVerdict(reach, repoPath) {
225
+ if (reach.kind === "gitlab") {
226
+ if (reach.apiToken)
227
+ return "GitLab takes the token as an access token; give the relay a pipeline trigger token (Settings > CI/CD > Pipeline trigger tokens)";
228
+ if (!reach.trigger)
229
+ return "the token is not a GitLab pipeline trigger token (glptt-)";
230
+ return null;
231
+ }
232
+ if (reach.kind === "forgejo") {
233
+ if (reach.admin)
234
+ return `the token's user administers ${repoPath}`;
235
+ if (reach.push)
236
+ return `the token's user may push to ${repoPath}; give the relay a user with Actions write and Code read`;
237
+ return null;
238
+ }
239
+ if (reach.classic)
240
+ return "a classic token reaches every repo its account can; give the relay a fine-grained token for this repo with Actions: Read and write, and nothing else";
241
+ if (reach.admin)
242
+ return `the token's account administers ${repoPath}`;
243
+ if (reach.refWrite !== 403 && reach.refWrite !== 404)
244
+ return `the token can write ${repoPath}'s contents (creating a ref answered ${reach.refWrite}); give it Actions: Read and write, and Contents no more than read`;
245
+ return null;
246
+ }
247
+ /** Read what the dispatch token reaches, and judge it. Never throws. */
248
+ export async function checkDispatchToken(repo, token, fetchImpl) {
249
+ if (!token)
250
+ return { error: "the dispatch token is empty" };
251
+ try {
252
+ const why = dispatchTokenVerdict(await readDispatchReach(repo, token, fetchImpl), repo.path);
253
+ return why ? { error: why } : { ok: true };
254
+ }
255
+ catch (e) {
256
+ return { error: `the forge could not be read with the dispatch token (${e.message})` };
257
+ }
258
+ }
259
+ /** A workflow file name the dispatch names, such as `chant-alert-agent.yml`. */
260
+ export const WORKFLOW_FILE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,199}\.ya?ml$/;
261
+ /**
262
+ * Start the alert agent's workflow on `branch` with no inputs: a
263
+ * `workflow_dispatch` of `workflow` on GitHub and Forgejo, a pipeline from
264
+ * the trigger token on GitLab.
265
+ */
266
+ export async function dispatchAgentWorkflow(o) {
267
+ const fetchImpl = o.fetch ?? globalThis.fetch;
268
+ try {
269
+ if (o.repo.forge === "gitlab") {
270
+ const body = new URLSearchParams({ token: o.token, ref: o.branch }).toString();
271
+ const res = await fetchImpl(`${o.repo.apiBase}/projects/${encodeURIComponent(o.repo.path)}/trigger/pipeline`, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" }, body });
272
+ return res.ok ? { ok: true } : { ok: false, error: `the pipeline trigger answered ${res.status}` };
273
+ }
274
+ if (!o.workflow || !WORKFLOW_FILE.test(o.workflow))
275
+ return { ok: false, error: "no workflow file is named to start" };
276
+ const res = await fetchImpl(`${o.repo.apiBase}/repos/${o.repo.path}/actions/workflows/${encodeURIComponent(o.workflow)}/dispatches`, {
277
+ method: "POST",
278
+ headers: { ...authHeaders(o.repo.forge, o.token), "Content-Type": "application/json" },
279
+ body: JSON.stringify({ ref: o.branch }),
280
+ });
281
+ return res.ok ? { ok: true } : { ok: false, error: `workflow_dispatch of ${o.workflow} answered ${res.status}` };
282
+ }
283
+ catch (e) {
284
+ return { ok: false, error: e.message };
285
+ }
286
+ }
@@ -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 { type Server } from "node:http";
45
67
  import type { CiProductWords } from "./ci-product-words.js";
46
68
  import type { GatedRequest } from "./lifecycle/gated-request-digest.js";
69
+ import { type AgentFact } from "./agent-facts.js";
70
+ import { type AlertSource } 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 declare const RELAY_ENV: {
74
98
  readonly port: "CHANT_RELAY_PORT";
75
99
  /** Comma-separated address prefixes a Slack response_url may have. */
76
100
  readonly slackResponse: "CHANT_RELAY_SLACK_RESPONSE";
101
+ /** The secret every alert source shares, unless `CHANT_ALERT_SECRET_<SOURCE>` names one of its own (#5329). */
102
+ readonly alertSecret: "CHANT_ALERT_SECRET";
103
+ /** How old an alert delivery may be, in seconds. */
104
+ readonly 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
+ readonly alertDispatchToken: "CHANT_ALERT_DISPATCH_TOKEN";
107
+ /** The alert agent's workflow file on GitHub and Forgejo, such as `chant-alert-agent.yml`. */
108
+ readonly 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 declare const alertSecretEnv: (source: AlertSource) => string;
78
112
  /** The variables that stand in for `--repo`, the default `--token-env`, and `--forge` (#4759). */
79
113
  export declare const RELAY_REPO_ENV: {
80
114
  /** The repository's https clone address. */
@@ -200,6 +234,18 @@ export interface RelayDeps {
200
234
  principal: string;
201
235
  words: CiProductWords;
202
236
  now?: () => Date;
237
+ /** Write alert facts under `_alerts/` and push them (#5329): the ones the ledger held already come back as duplicates. */
238
+ recordAlerts?(facts: AgentFact[]): Promise<{
239
+ recorded: AgentFact[];
240
+ duplicates: AgentFact[];
241
+ }>;
242
+ /** Start the alert agent's workflow with no inputs. Absent: the agent's schedule picks the facts up. */
243
+ dispatch?(): Promise<{
244
+ ok: true;
245
+ } | {
246
+ ok: false;
247
+ error: string;
248
+ }>;
203
249
  }
204
250
  export interface RelaySettings {
205
251
  /** The relay key: buttons it did not sign are refused. */
@@ -208,6 +254,10 @@ export interface RelaySettings {
208
254
  teamsSecret?: string;
209
255
  maxAgeSeconds?: number;
210
256
  slackResponse?: string[];
257
+ /** The alert sources the relay reads, by their secret (#5329). A source with none answers 404: alerts are off until a secret is set. */
258
+ alertSecrets?: Partial<Record<AlertSource, string>>;
259
+ /** How old an alert delivery may be, in seconds. */
260
+ alertMaxAgeSeconds?: number;
211
261
  }
212
262
  /** The relay's answer to a click, and the line for the thread. */
213
263
  export interface RelayAnswer {
@@ -243,7 +293,7 @@ export type RelayFetch = (url: string, init: {
243
293
  status: number;
244
294
  }>;
245
295
  /**
246
- * One request: `POST /slack`, `POST /teams`, `GET /healthz`. A Slack answer
296
+ * One request: `POST /slack`, `POST /teams`, `POST /alert/<source>`, `GET /healthz`. A Slack answer
247
297
  * goes to the click's response_url, in the message's thread, when that is
248
298
  * Slack's; a Teams answer is the reply Teams posts under the message.
249
299
  */