@intentius/chant 0.124.85 → 0.124.86

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 (254) hide show
  1. package/dist/bundle-check.d.ts +102 -0
  2. package/dist/bundle-check.d.ts.map +1 -0
  3. package/dist/bundle-check.js +310 -0
  4. package/dist/chant-install.d.ts +100 -0
  5. package/dist/chant-install.d.ts.map +1 -0
  6. package/dist/chant-install.js +158 -0
  7. package/dist/ci-commit.d.ts +19 -6
  8. package/dist/ci-commit.d.ts.map +1 -1
  9. package/dist/ci-commit.js +23 -4
  10. package/dist/ci-evidence-jobs.d.ts +54 -0
  11. package/dist/ci-evidence-jobs.d.ts.map +1 -0
  12. package/dist/ci-evidence-jobs.js +55 -0
  13. package/dist/ci-image.d.ts +274 -0
  14. package/dist/ci-image.d.ts.map +1 -0
  15. package/dist/ci-image.js +635 -0
  16. package/dist/ci-login.d.ts +150 -0
  17. package/dist/ci-login.d.ts.map +1 -0
  18. package/dist/ci-login.js +240 -0
  19. package/dist/ci-product.d.ts +16 -0
  20. package/dist/ci-product.d.ts.map +1 -1
  21. package/dist/ci-product.js +17 -0
  22. package/dist/cli/commands/import-index.js +2 -2
  23. package/dist/cli/handlers/build.d.ts +8 -0
  24. package/dist/cli/handlers/build.d.ts.map +1 -1
  25. package/dist/cli/handlers/build.js +22 -4
  26. package/dist/cli/handlers/ci-check.d.ts.map +1 -1
  27. package/dist/cli/handlers/ci-check.js +57 -2
  28. package/dist/cli/handlers/ci-evidence.d.ts +3 -0
  29. package/dist/cli/handlers/ci-evidence.d.ts.map +1 -0
  30. package/dist/cli/handlers/ci-evidence.js +171 -0
  31. package/dist/cli/handlers/components.js +3 -3
  32. package/dist/cli/handlers/dead-guards.d.ts +3 -0
  33. package/dist/cli/handlers/dead-guards.d.ts.map +1 -0
  34. package/dist/cli/handlers/dead-guards.js +35 -0
  35. package/dist/cli/handlers/graph.js +4 -4
  36. package/dist/cli/handlers/lifecycle.d.ts +2 -1
  37. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  38. package/dist/cli/handlers/lifecycle.js +5 -4
  39. package/dist/cli/handlers/local-chant.d.ts +16 -0
  40. package/dist/cli/handlers/local-chant.d.ts.map +1 -0
  41. package/dist/cli/handlers/local-chant.js +109 -0
  42. package/dist/cli/handlers/operator.js +2 -2
  43. package/dist/cli/handlers/search.js +5 -5
  44. package/dist/cli/main.d.ts.map +1 -1
  45. package/dist/cli/main.js +38 -0
  46. package/dist/cli/parse-args.d.ts.map +1 -1
  47. package/dist/cli/parse-args.js +28 -0
  48. package/dist/cli/registry.d.ts +16 -0
  49. package/dist/cli/registry.d.ts.map +1 -1
  50. package/dist/components/check-hooks.d.ts +49 -0
  51. package/dist/components/check-hooks.d.ts.map +1 -1
  52. package/dist/components/check-hooks.js +64 -4
  53. package/dist/components/check-steps.d.ts +17 -0
  54. package/dist/components/check-steps.d.ts.map +1 -1
  55. package/dist/components/check-steps.js +37 -5
  56. package/dist/components/product-pipeline.d.ts +23 -0
  57. package/dist/components/product-pipeline.d.ts.map +1 -1
  58. package/dist/components/product-pipeline.js +6 -2
  59. package/dist/components/product-plan.d.ts +137 -0
  60. package/dist/components/product-plan.d.ts.map +1 -0
  61. package/dist/components/product-plan.js +143 -0
  62. package/dist/components/release-compile.d.ts.map +1 -1
  63. package/dist/components/release-compile.js +2 -2
  64. package/dist/config.d.ts +39 -1
  65. package/dist/config.d.ts.map +1 -1
  66. package/dist/config.js +35 -3
  67. package/dist/dead-guards.d.ts +82 -0
  68. package/dist/dead-guards.d.ts.map +1 -0
  69. package/dist/dead-guards.js +436 -0
  70. package/dist/discovery/files.d.ts +3 -1
  71. package/dist/discovery/files.d.ts.map +1 -1
  72. package/dist/discovery/files.js +5 -3
  73. package/dist/drift-issue.d.ts +152 -0
  74. package/dist/drift-issue.d.ts.map +1 -0
  75. package/dist/drift-issue.js +167 -0
  76. package/dist/floor-table.d.ts +30 -0
  77. package/dist/floor-table.d.ts.map +1 -0
  78. package/dist/floor-table.data.d.ts +3 -0
  79. package/dist/floor-table.data.d.ts.map +1 -0
  80. package/dist/floor-table.data.js +178 -0
  81. package/dist/floor-table.js +56 -0
  82. package/dist/forge-flags.d.ts +90 -0
  83. package/dist/forge-flags.d.ts.map +1 -0
  84. package/dist/forge-flags.js +184 -0
  85. package/dist/lexicon.d.ts +69 -0
  86. package/dist/lexicon.d.ts.map +1 -1
  87. package/dist/lifecycle/gated-op.d.ts +7 -1
  88. package/dist/lifecycle/gated-op.d.ts.map +1 -1
  89. package/dist/lifecycle/gated-op.js +7 -4
  90. package/dist/local-chant.d.ts +98 -0
  91. package/dist/local-chant.d.ts.map +1 -0
  92. package/dist/local-chant.js +307 -0
  93. package/dist/op/activities/predict-behaviour.js +2 -2
  94. package/dist/op/op-waves-evidence-spec.d.ts +13 -0
  95. package/dist/op/op-waves-evidence-spec.d.ts.map +1 -0
  96. package/dist/op/op-waves-evidence-spec.js +21 -0
  97. package/dist/op/op-waves-evidence.d.ts +38 -0
  98. package/dist/op/op-waves-evidence.d.ts.map +1 -0
  99. package/dist/op/op-waves-evidence.js +57 -0
  100. package/dist/op/op-waves-run.d.ts +4 -0
  101. package/dist/op/op-waves-run.d.ts.map +1 -1
  102. package/dist/op/op-waves-run.js +24 -1
  103. package/dist/op/op-waves.d.ts +17 -1
  104. package/dist/op/op-waves.d.ts.map +1 -1
  105. package/dist/op/op-waves.js +23 -0
  106. package/dist/op/schedule-overdue.d.ts +41 -9
  107. package/dist/op/schedule-overdue.d.ts.map +1 -1
  108. package/dist/op/schedule-overdue.js +154 -25
  109. package/dist/plan-summary.d.ts +25 -0
  110. package/dist/plan-summary.d.ts.map +1 -1
  111. package/dist/plan-summary.js +31 -0
  112. package/dist/pr-plan-note.d.ts +35 -0
  113. package/dist/pr-plan-note.d.ts.map +1 -1
  114. package/dist/pr-plan-note.js +10 -0
  115. package/dist/pr-post.d.ts +23 -0
  116. package/dist/pr-post.d.ts.map +1 -1
  117. package/dist/pr-post.js +125 -3
  118. package/dist/release-floors.d.ts +31 -1
  119. package/dist/release-floors.d.ts.map +1 -1
  120. package/dist/release-floors.js +31 -1
  121. package/dist/state-migration.d.ts +24 -0
  122. package/dist/state-migration.d.ts.map +1 -1
  123. package/dist/state-migration.js +100 -5
  124. package/dist/wave-runtime.mjs +305 -298
  125. package/dist/workspace/lexicon-outputs.d.ts.map +1 -1
  126. package/dist/workspace/lexicon-outputs.js +21 -7
  127. package/dist/workspace/reason-codes.d.ts +3 -0
  128. package/dist/workspace/reason-codes.d.ts.map +1 -1
  129. package/dist/workspace/reason-codes.js +4 -0
  130. package/dist/workspace/ref-gate.schema.json +85 -0
  131. package/dist/workspace/search-contract.d.ts +1 -1
  132. package/dist/workspace/search-contract.d.ts.map +1 -1
  133. package/dist/workspace/trust/check-evidence-report.d.ts +51 -0
  134. package/dist/workspace/trust/check-evidence-report.d.ts.map +1 -0
  135. package/dist/workspace/trust/check-evidence-report.js +102 -0
  136. package/dist/workspace/trust/check-evidence.d.ts +126 -0
  137. package/dist/workspace/trust/check-evidence.d.ts.map +1 -0
  138. package/dist/workspace/trust/check-evidence.js +237 -0
  139. package/dist/workspace/trust/local-evidence.d.ts +120 -0
  140. package/dist/workspace/trust/local-evidence.d.ts.map +1 -0
  141. package/dist/workspace/trust/local-evidence.js +259 -0
  142. package/dist/workspace/trust/policy.d.ts +84 -0
  143. package/dist/workspace/trust/policy.d.ts.map +1 -1
  144. package/dist/workspace/trust/policy.js +94 -1
  145. package/dist/workspace/trust/ref-gate-cli.d.ts +33 -0
  146. package/dist/workspace/trust/ref-gate-cli.d.ts.map +1 -0
  147. package/dist/workspace/trust/ref-gate-cli.js +234 -0
  148. package/dist/workspace/trust/ref-gate-fixture.d.ts +38 -0
  149. package/dist/workspace/trust/ref-gate-fixture.d.ts.map +1 -0
  150. package/dist/workspace/trust/ref-gate-fixture.js +97 -0
  151. package/dist/workspace/trust/ref-gate.d.ts +187 -0
  152. package/dist/workspace/trust/ref-gate.d.ts.map +1 -0
  153. package/dist/workspace/trust/ref-gate.js +430 -0
  154. package/dist/workspace/trust/trust-files.d.ts.map +1 -1
  155. package/dist/workspace/trust/trust-files.js +18 -1
  156. package/package.json +1 -1
  157. package/src/bundle-check.test.ts +140 -0
  158. package/src/bundle-check.ts +352 -0
  159. package/src/chant-install.test.ts +112 -0
  160. package/src/chant-install.ts +179 -0
  161. package/src/ci-commit.test.ts +45 -0
  162. package/src/ci-commit.ts +38 -4
  163. package/src/ci-evidence-jobs.ts +67 -0
  164. package/src/ci-image.test.ts +506 -0
  165. package/src/ci-image.ts +822 -0
  166. package/src/ci-login.test.ts +235 -0
  167. package/src/ci-login.ts +307 -0
  168. package/src/ci-product.ts +18 -0
  169. package/src/cli/commands/__fixtures__/source-dir-include/chant.config.json +1 -0
  170. package/src/cli/commands/__fixtures__/source-dir-include/infra.ts +1 -0
  171. package/src/cli/commands/__fixtures__/source-dir-include/scripts/run-on-load.ts +3 -0
  172. package/src/cli/commands/__fixtures__/source-dir-root/chant.config.json +1 -0
  173. package/src/cli/commands/__fixtures__/source-dir-root/infra.test.ts +1 -0
  174. package/src/cli/commands/__fixtures__/source-dir-root/infra.ts +1 -0
  175. package/src/cli/commands/__fixtures__/source-dir-root/scripts/run-on-load.ts +3 -0
  176. package/src/cli/commands/__fixtures__/source-dir-scoped/app.ts +3 -0
  177. package/src/cli/commands/__fixtures__/source-dir-scoped/chant.config.json +1 -0
  178. package/src/cli/commands/__fixtures__/source-dir-scoped/infra/net.ts +1 -0
  179. package/src/cli/commands/__fixtures__/source-dir-scoped/scripts/run-on-load.ts +3 -0
  180. package/src/cli/commands/import-index.ts +2 -2
  181. package/src/cli/handlers/build-source-dir.test.ts +64 -0
  182. package/src/cli/handlers/build.ts +21 -4
  183. package/src/cli/handlers/ci-check.ts +56 -3
  184. package/src/cli/handlers/ci-evidence.ts +162 -0
  185. package/src/cli/handlers/components.ts +3 -3
  186. package/src/cli/handlers/dead-guards.ts +37 -0
  187. package/src/cli/handlers/graph.ts +4 -4
  188. package/src/cli/handlers/lifecycle.ts +5 -4
  189. package/src/cli/handlers/local-chant.ts +106 -0
  190. package/src/cli/handlers/operator.ts +2 -2
  191. package/src/cli/handlers/search.ts +5 -5
  192. package/src/cli/main.test.ts +7 -0
  193. package/src/cli/main.ts +38 -0
  194. package/src/cli/parse-args.ts +21 -0
  195. package/src/cli/registry.ts +16 -0
  196. package/src/components/check-evidence-stage.test.ts +80 -0
  197. package/src/components/check-hooks.ts +84 -4
  198. package/src/components/check-local-evidence-stage.test.ts +141 -0
  199. package/src/components/check-steps.ts +56 -6
  200. package/src/components/product-pipeline.ts +28 -3
  201. package/src/components/product-plan.test.ts +87 -0
  202. package/src/components/product-plan.ts +226 -0
  203. package/src/components/release-compile.ts +2 -2
  204. package/src/config.ts +44 -3
  205. package/src/dead-guards.test.ts +206 -0
  206. package/src/dead-guards.ts +446 -0
  207. package/src/discovery/files.ts +5 -3
  208. package/src/drift-issue-bundle.test.ts +31 -0
  209. package/src/drift-issue.test.ts +206 -0
  210. package/src/drift-issue.ts +274 -0
  211. package/src/fit-note.test.ts +44 -0
  212. package/src/floor-table.data.ts +180 -0
  213. package/src/floor-table.ts +77 -0
  214. package/src/forge-flags.test.ts +110 -0
  215. package/src/forge-flags.ts +208 -0
  216. package/src/gate-decision-bundle.test.ts +1 -0
  217. package/src/lexicon.ts +68 -0
  218. package/src/lifecycle/gated-op.ts +10 -5
  219. package/src/local-chant.e2e.test.ts +94 -0
  220. package/src/local-chant.test.ts +162 -0
  221. package/src/local-chant.ts +341 -0
  222. package/src/op/activities/predict-behaviour.ts +2 -2
  223. package/src/op/op-waves-evidence-spec.ts +24 -0
  224. package/src/op/op-waves-evidence.test.ts +130 -0
  225. package/src/op/op-waves-evidence.ts +57 -0
  226. package/src/op/op-waves-run.ts +25 -1
  227. package/src/op/op-waves.ts +31 -1
  228. package/src/op/schedule-overdue.test.ts +85 -0
  229. package/src/op/schedule-overdue.ts +162 -26
  230. package/src/plan-summary.ts +40 -0
  231. package/src/pr-plan-note.ts +34 -0
  232. package/src/pr-post-plan-note.test.ts +146 -0
  233. package/src/pr-post.ts +127 -3
  234. package/src/release-floors.ts +44 -1
  235. package/src/stage-hooks-bundle.test.ts +1 -0
  236. package/src/state-migration.test.ts +52 -1
  237. package/src/state-migration.ts +107 -5
  238. package/src/workspace/lexicon-outputs.ts +23 -6
  239. package/src/workspace/reason-codes.test.ts +3 -0
  240. package/src/workspace/reason-codes.ts +4 -0
  241. package/src/workspace/ref-gate.schema.json +85 -0
  242. package/src/workspace/trust/check-evidence-report.ts +106 -0
  243. package/src/workspace/trust/check-evidence.test.ts +133 -0
  244. package/src/workspace/trust/check-evidence.ts +257 -0
  245. package/src/workspace/trust/local-evidence.test.ts +127 -0
  246. package/src/workspace/trust/local-evidence.ts +266 -0
  247. package/src/workspace/trust/policy.ts +134 -1
  248. package/src/workspace/trust/ref-gate-cli.ts +244 -0
  249. package/src/workspace/trust/ref-gate-fixture.ts +125 -0
  250. package/src/workspace/trust/ref-gate.e2e.test.ts +76 -0
  251. package/src/workspace/trust/ref-gate.test.ts +247 -0
  252. package/src/workspace/trust/ref-gate.ts +538 -0
  253. package/src/workspace/trust/trust-files.test.ts +16 -0
  254. package/src/workspace/trust/trust-files.ts +41 -1
package/src/pr-post.ts CHANGED
@@ -37,6 +37,8 @@ import { forgePrincipalOf, type PrForge } from "./pr-forge";
37
37
  import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "./plan-summary";
38
38
  import { activeProductWords, commentLine, type CiProductWords } from "./ci-product-words";
39
39
  import { controlEdgeFactsFromEnv, remarkCrossStackEdges, type ControlEdgeFacts } from "./control/edges";
40
+ import { checkEvidenceNoteLine } from "./workspace/trust/check-evidence-report";
41
+ import { isPlanNote, planNoteMarker, PR_PLAN_NOTE_CONTRACT, PR_PLAN_NOTE_FILE, renderPlanNote, type PrPlanNoteHandoff, type PrPlanNoteWords } from "./pr-plan-note";
40
42
 
41
43
  /** The plan report's file under the report directory. */
42
44
  export const PR_PLAN_REPORT_FILE = "pr-plan.json";
@@ -82,6 +84,12 @@ export interface PlanPostInput {
82
84
  * Forgejo: the note, without its hidden lines, is added to it.
83
85
  */
84
86
  summaryFile?: string;
87
+ /**
88
+ * The words a product's plan note hand-off renders with (#4799). Default:
89
+ * the JSON in `CHANT_PLAN_NOTE_WORDS`, which the generated note job sets
90
+ * from the pipeline, never from the report.
91
+ */
92
+ noteWords?: PrPlanNoteWords;
85
93
  }
86
94
 
87
95
  /** What {@link postPlanReport} did. */
@@ -171,6 +179,8 @@ const cut = (text: string, max = 140): string => (text.length > max ? `${text.sl
171
179
  * the caller's sets a failed status and posts no note.
172
180
  */
173
181
  export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResult> {
182
+ // #4799: a product's plan verb wrote its plan note hand-off in place of pr-plan's report.
183
+ if (!existsSync(join(input.dir, PR_PLAN_REPORT_FILE)) && existsSync(join(input.dir, PR_PLAN_NOTE_FILE))) return postPlanNoteHandoff(input);
174
184
  const warnings: string[] = [];
175
185
  const context = prStatusContext("plan", input.member);
176
186
  const read = readPlanReport(input);
@@ -211,11 +221,39 @@ export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResu
211
221
  description = cut(`the plan job failed; ${description}`);
212
222
  }
213
223
  }
224
+ note = await postOutcome(input, context, state, description, note, refused, warnings);
225
+ if (input.description && "report" in read && !failedJob) {
226
+ try {
227
+ await input.description(read.report);
228
+ } catch (err) {
229
+ warnings.push(`the description check did not run: ${err instanceof Error ? err.message : String(err)}`);
230
+ }
231
+ }
232
+ return { state, description: cut(description), noted: note !== undefined, ...(refused ? { refused } : {}), warnings };
233
+ }
234
+
235
+ /**
236
+ * Set the plan status, post the note when there is one, and add it to the
237
+ * job summary (#4295, #4628). Returns the note, or undefined when posting
238
+ * it failed.
239
+ */
240
+ async function postOutcome(
241
+ input: PlanPostInput,
242
+ context: string,
243
+ state: PlanPostResult["state"],
244
+ description: string,
245
+ note: string | undefined,
246
+ refused: string | undefined,
247
+ warnings: string[],
248
+ ): Promise<string | undefined> {
214
249
  try {
215
250
  await input.forge.setStatus(input.head, { context, state, description: cut(description), ...(input.forge.runUrl ? { url: input.forge.runUrl } : {}) });
216
251
  } catch (err) {
217
252
  warnings.push(`could not set the ${context} status: ${err instanceof Error ? err.message : String(err)}`);
218
253
  }
254
+ // #4870: the checks the note job signed evidence for, when it signed any.
255
+ const evidence = note !== undefined ? checkEvidenceNoteLine(input.dir) : undefined;
256
+ if (note !== undefined && evidence) note = `${note}${note.endsWith("\n") ? "" : "\n"}\n${evidence}\n`;
219
257
  if (note !== undefined) {
220
258
  try {
221
259
  await upsertPlanNote(input.forge, input.pr, prNoteMarker(input.env, input.member), note);
@@ -232,13 +270,96 @@ export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResu
232
270
  warnings.push(`could not write the job summary: ${err instanceof Error ? err.message : String(err)}`);
233
271
  }
234
272
  }
235
- if (input.description && "report" in read && !failedJob) {
273
+ return note;
274
+ }
275
+
276
+ /**
277
+ * Read a product's plan note hand-off under `dir` (#4799) and check it is the
278
+ * one the caller ran, as {@link readPlanReport} checks a report.
279
+ */
280
+ export function readPlanNoteHandoff(input: Pick<PlanPostInput, "dir" | "pr" | "head" | "env" | "member">): { handoff: PrPlanNoteHandoff } | { refused: string } {
281
+ let doc: unknown;
282
+ try {
283
+ doc = JSON.parse(readFileSync(join(input.dir, PR_PLAN_NOTE_FILE), "utf-8"));
284
+ } catch (err) {
285
+ return { refused: `the plan note does not read: ${err instanceof Error ? err.message : String(err)}` };
286
+ }
287
+ if (!doc || typeof doc !== "object" || Array.isArray(doc)) return { refused: "the plan note is not an object" };
288
+ const r = doc as Record<string, unknown>;
289
+ if (r.kind !== "plan-note-handoff") return { refused: `the file is not a plan note hand-off (kind ${JSON.stringify(r.kind)})` };
290
+ if (r.contract !== PR_PLAN_NOTE_CONTRACT) return { refused: `the plan note follows contract ${JSON.stringify(r.contract)}, and this chant reads ${PR_PLAN_NOTE_CONTRACT}` };
291
+ if (r.pr !== input.pr) return { refused: `the plan note is for pull request ${JSON.stringify(r.pr)}, not ${input.pr}` };
292
+ if (typeof r.head !== "string" || !SHA.test(r.head) || r.head !== input.head) return { refused: `the plan note is for head ${JSON.stringify(r.head)}, not ${input.head}` };
293
+ if (r.env !== input.env) return { refused: `the plan note is for environment ${JSON.stringify(r.env)}, not ${input.env}` };
294
+ if ((r.member ?? undefined) !== input.member) return { refused: `the plan note is for ${JSON.stringify(r.member ?? null)}, not ${JSON.stringify(input.member ?? null)}` };
295
+ if (r.state !== "success" && r.state !== "failure" && r.state !== "pending") return { refused: `the plan note's state ${JSON.stringify(r.state)} is not success, failure or pending` };
296
+ if (typeof r.description !== "string") return { refused: "the plan note has no description" };
297
+ if (!isPlanNote(r.note) || r.note.head !== r.head || !Array.isArray(r.note.waves) || !Array.isArray(r.note.groups) || !Array.isArray(r.note.named)) {
298
+ return { refused: "the plan note's note is not a plan note for its head" };
299
+ }
300
+ return { handoff: doc as PrPlanNoteHandoff };
301
+ }
302
+
303
+ /** The note words from `CHANT_PLAN_NOTE_WORDS` (#4799), or undefined when unset or not an object. */
304
+ function noteWordsFromEnv(): PrPlanNoteWords | undefined {
305
+ const raw = process.env.CHANT_PLAN_NOTE_WORDS;
306
+ if (!raw) return undefined;
307
+ try {
308
+ const w = JSON.parse(raw) as unknown;
309
+ return w && typeof w === "object" && !Array.isArray(w) ? (w as PrPlanNoteWords) : undefined;
310
+ } catch {
311
+ return undefined;
312
+ }
313
+ }
314
+
315
+ /**
316
+ * The note for a product's plan note hand-off (#4799): rendered here with
317
+ * the pipeline's note words, every `<!--` after the marker line defused as
318
+ * {@link planNoteFor} does, except the waves marker chant itself rendered
319
+ * from the note's waves, which the product reads back.
320
+ */
321
+ export function planNoteHandoffNote(handoff: PrPlanNoteHandoff, forge: Pick<PrForge, "kind">, marker: string, noteWords?: PrPlanNoteWords, baseTip?: string): string {
322
+ const words = activeProductWords();
323
+ const rendered = renderPlanNote(handoff.note, { limit: forge.kind === "gitlab" ? GITLAB_NOTE_LIMIT : GITHUB_COMMENT_LIMIT, words, ...(noteWords ? { note: noteWords } : {}) });
324
+ let body = rendered.split("<!--").join("&lt;!--");
325
+ const n = handoff.note;
326
+ const previews = n.previews ?? [];
327
+ const waves = planNoteMarker(noteWords?.marker ?? `${words.product}:waves`, { head: n.head, waves: n.waves.map((x) => ({ number: x.number, digest: x.digest ?? null, waits: x.waits === true })), ...(previews.length ? { previews } : {}) });
328
+ body = body.replace(`&lt;!--${waves.slice(4)}`, waves);
329
+ const tip = baseTip && SHA.test(baseTip) ? `${body.endsWith("\n") ? "" : "\n"}${prNoteTipMarker(baseTip)}\n` : "";
330
+ return `${marker}\n${body}${tip}`;
331
+ }
332
+
333
+ /** {@link postPlanReport} for a product's plan note hand-off (#4799). */
334
+ async function postPlanNoteHandoff(input: PlanPostInput): Promise<PlanPostResult> {
335
+ const warnings: string[] = [];
336
+ const context = prStatusContext("plan", input.member);
337
+ const read = readPlanNoteHandoff(input);
338
+ const failedJob = input.result === "failure" || input.result === "cancelled";
339
+ let state: PlanPostResult["state"];
340
+ let description: string;
341
+ let note: string | undefined;
342
+ let refused: string | undefined;
343
+ if ("refused" in read) {
344
+ refused = read.refused;
345
+ state = "failure";
346
+ description = cut(read.refused);
347
+ } else {
348
+ state = read.handoff.state;
349
+ description = read.handoff.description;
236
350
  try {
237
- await input.description(read.report);
351
+ note = planNoteHandoffNote(read.handoff, input.forge, prNoteMarker(input.env, input.member), input.noteWords ?? noteWordsFromEnv(), input.baseTip);
238
352
  } catch (err) {
239
- warnings.push(`the description check did not run: ${err instanceof Error ? err.message : String(err)}`);
353
+ refused = `the plan note does not render: ${err instanceof Error ? err.message : String(err)}`;
354
+ state = "failure";
355
+ description = cut(refused);
356
+ }
357
+ if (failedJob && state !== "failure") {
358
+ state = "failure";
359
+ description = cut(`the plan job failed; ${description}`);
240
360
  }
241
361
  }
362
+ note = await postOutcome(input, context, state, description, note, refused, warnings);
242
363
  return { state, description: cut(description), noted: note !== undefined, ...(refused ? { refused } : {}), warnings };
243
364
  }
244
365
 
@@ -323,6 +444,9 @@ export async function postOpenPlanReports(input: OpenPlanPostInput): Promise<{ p
323
444
  try {
324
445
  const text = await forge.jobArtifact(job.id, `${input.artifactDir.replace(/\/+$/, "")}/${PR_PLAN_REPORT_FILE}`);
325
446
  if (text !== undefined) writeFileSync(join(dir, PR_PLAN_REPORT_FILE), text);
447
+ // #4799: a product's plan verb writes its plan note hand-off in place of the report.
448
+ const handoff = text === undefined ? await forge.jobArtifact(job.id, `${input.artifactDir.replace(/\/+$/, "")}/${PR_PLAN_NOTE_FILE}`) : undefined;
449
+ if (handoff !== undefined) writeFileSync(join(dir, PR_PLAN_NOTE_FILE), handoff);
326
450
  const posted = await postPlanReport({
327
451
  // The status links to the plan job it reports on, which is how the next run knows it is posted.
328
452
  forge: job.url ? { ...forge, runUrl: job.url } : forge,
@@ -19,7 +19,35 @@
19
19
  * this constant to the next patch (#4501). The check fails while a floor
20
20
  * still names this constant after its version shipped.
21
21
  */
22
- export const NEXT_RELEASE = "0.124.85";
22
+ export const NEXT_RELEASE = "0.124.86";
23
+
24
+ /** The first chant with `chant dev local` and `chant dev bundle-check`, `@intentius/chant/local-chant` and `@intentius/chant/bundle-check` (`chantRuntimeTarget`, `chantExternalPlugin`, `checkBundle`): a product built against a chant checkout, and its bundle checked, without its own scripts (#4787). */
25
+ export const LOCAL_CHANT_FLOOR = NEXT_RELEASE;
26
+
27
+ /** The first chant with `chant workspace ref-gate` (pre-receive, pre-push, check, status, attach, install) and `refs` in `.chant/trust.json`, the checks a ref update needs evidence for (#4867). */
28
+ export const REF_GATE_FLOOR = NEXT_RELEASE;
29
+
30
+ /** The first chant whose overdue check finds a schedule in any pipeline file, and whose `ScheduledWatch` takes a product's `files` and GitLab `schedule` selector (#4789). */
31
+ export const OVERDUE_PIPELINE_FILES_FLOOR = NEXT_RELEASE;
32
+
33
+ /** The first chant whose `terraformApplyCapabilityWith` takes `onCommand`, a hook around each engine command `terraform-apply` runs for a root, its reads' upstreams included (#4865). */
34
+ export const TERRAFORM_APPLY_COMMAND_HOOK_FLOOR = NEXT_RELEASE;
35
+
36
+ /** The first chant with `@intentius/chant/forge-flags` (`forgeTargetWith`, `forgeTargetFromFlags`, `apiBaseOf`), `@intentius/chant/chant-install` (`bundledChant`, `chantArgv`, `installChantResolveFallback`) and `noteLimit` and `fitNote` in `@intentius/chant/plan-summary` (#4800). */
37
+ export const PRODUCT_HELPERS_FLOOR = NEXT_RELEASE;
38
+
39
+ /** The first chant with `@intentius/chant/ci-image`: `productImageStages`, `productImageDockerfile` and `derivedImageDockerfile` for a product's CI image, and `ciToolFetchScript`, `ciToolInstallLine` and `installCiTool`, the digest-checked engine installs, with the terraform lexicon's `choudoufuInstallLine` checked the same way (#4784). */
40
+ export const CI_IMAGE_FLOOR = NEXT_RELEASE;
41
+
42
+ /** The first chant with `@intentius/chant/drift-issue`, whose `keepDriftIssue` keeps one drift issue per environment from a product's words and the drift records (#4790). */
43
+ export const DRIFT_ISSUE_FLOOR = NEXT_RELEASE;
44
+
45
+ /** The first chant whose `chant build` with no path builds the config's `sourceDir`, whose root build leaves a top-level `scripts/` out, and whose `@intentius/chant/config` exports `resolveSourceDir`, the one source-dir rule every command shares (#4794). */
46
+ export const SOURCE_DIR_RULE_FLOOR = NEXT_RELEASE;
47
+ /** The first chant whose pulumi lexicon runs `gatedStackExport`, `gatedStackCancel` and `gatedStackMove` on core's `exportStateVersion`, `releaseStateLock` and `runStateMigration`: export by version, the live-run check before a cancel (`liveRuns`, `forge`), and the check that nothing moved between a move's plan and its write (#4808). */
48
+ export const PULUMI_STACK_OPS_ON_CORE_FLOOR = NEXT_RELEASE;
49
+ /** The first chant whose terraform lexicon's state stores read versions (`version`, `hasVersion`, `readVersion`, `isAt`, `listVersions`), with `readStateVersion` and `listStateVersions`, and lock and write a GitLab-managed http backend's state (#4793). */
50
+ export const TERRAFORM_STATE_VERSION_READS_FLOOR = NEXT_RELEASE;
23
51
 
24
52
  /** The first chant whose terraform lexicon's `terraform-apply` reads take `dir` and `workspace`, and read an upstream with `resolveRoot`'s binary and `readEnv` (terragucci issue 1303). */
25
53
  export const TERRAFORM_APPLY_INSTANCE_READS_FLOOR = "0.124.80";
@@ -59,3 +87,18 @@ export const PR_FORGE_READS_FLOOR = "0.124.78";
59
87
 
60
88
  /** The first chant whose GitLab `scheduledRuns` takes `schedule`, the selector of an Op's `gitlab.scheduleRule` (#4813). */
61
89
  export const SCHEDULED_RUNS_SELECTOR_FLOOR = "0.124.78";
90
+
91
+ /** The first chant whose Op waves pipeline takes `waveJobs` and `recordPlans`, a product's login, report, artifact and plans-job inputs, so it edits nothing chant wrote (#4791). */
92
+ export const OP_WAVES_JOB_INPUTS_FLOOR = NEXT_RELEASE;
93
+
94
+ /** The first chant with `@intentius/chant/floor-table` (`FLOOR_TABLE`, `floorVersion`, `chantMeets`), every floor as one table, and `chant dev dead-guards` with `@intentius/chant/dead-guards` (`findDeadGuards`), which fails on a feature-detect the product's chant pin meets (#4792). */
95
+ export const FLOOR_TABLE_FLOOR = NEXT_RELEASE;
96
+
97
+ /** The first chant with `@intentius/chant/ci-login`: `githubCloudLogin`, `gitlabCloudLogin` and `forgejoCloudLogin` render a job's AWS, GCP and Azure login from the OIDC token file, per target too (#4788). */
98
+ export const CLOUD_LOGIN_FLOOR = NEXT_RELEASE;
99
+
100
+ /** The first chant whose generated pipelines sign evidence for each named check they run, with `chant ci evidence`, `ci check` signing each hook, and an Op waves spec's `evidence.requires` (#4870). */
101
+ export const CHECK_EVIDENCE_FLOOR = NEXT_RELEASE;
102
+
103
+ /** The first chant that accepts local evidence (#4868): `local` in `.chant/trust.json`, `chant ci evidence sign --local`, and `chant ci check` skipping a hook whose current local evidence the policy at base accepts. */
104
+ export const LOCAL_EVIDENCE_FLOOR = NEXT_RELEASE;
@@ -36,6 +36,7 @@ describe("the stage-hooks bundle", () => {
36
36
  "packages/core/src/op/gate-point.ts",
37
37
  "packages/core/src/op/gate-quorum.ts",
38
38
  "packages/core/src/op/op-waves-capability-spec.ts",
39
+ "packages/core/src/op/op-waves-evidence-spec.ts",
39
40
  "packages/core/src/op/op-waves-release.ts",
40
41
  "packages/core/src/op/op-waves.ts",
41
42
  "packages/core/src/op/stage-hooks.ts",
@@ -4,7 +4,8 @@
4
4
  */
5
5
  import { describe, expect, test } from "vitest";
6
6
  import { fakeLedger } from "./__fixtures__/gated-ledger";
7
- import { runStateMigration, STATE_MIGRATION_FLOOR, writeStateMigration, type MigrationRootPlan, type MigrationStateAt, type StateMigrationEngine } from "./state-migration";
7
+ import { NEXT_RELEASE } from "./release-floors";
8
+ import { runStateMigration, STATE_MIGRATION_FLOOR, STATE_MIGRATION_SOURCE_FLOOR, writeStateMigration, type MigrationRootPlan, type MigrationStateAt, type StateMigrationEngine } from "./state-migration";
8
9
 
9
10
  const plan = (proof: string[] = []): MigrationRootPlan[] => [
10
11
  { root: "queues", location: "s3://acme/queues.tfstate", before: { version_id: "q1", digest: "sha256:q-before" }, after: { digest: "sha256:q-after" }, proof: { changes: [], summary: "No changes." } },
@@ -131,3 +132,53 @@ describe("runStateMigration", () => {
131
132
  expect(STATE_MIGRATION_FLOOR).toBe("0.124.77");
132
133
  });
133
134
  });
135
+
136
+ describe("a root's source and an approval the states moved away from (#4806)", () => {
137
+ const withSource = (): MigrationRootPlan[] => plan().map((r) => (r.root === "queues" ? { ...r, before: { digest: null }, source: { location: "old.tfstate", digest: "sha256:q-after" } } : r));
138
+ const sourced = (now: MigrationStateAt) => {
139
+ const e = engine();
140
+ e.current = async (root) => (root === "queues" ? { digest: null } : { version_id: "p1", digest: "sha256:p-before" });
141
+ return Object.assign(e, { source: async () => now });
142
+ };
143
+
144
+ test("the request binds the source, the finished line names it, and a source that moved refuses the write", async () => {
145
+ const ledger = fakeLedger();
146
+ ledger.approve("bo");
147
+ const ok = await runStateMigration(base(ledger, sourced({ digest: "sha256:q-after" }), withSource()));
148
+ expect(ok.status).toBe("applied");
149
+ expect(ledger.details[0]).toMatchObject({ "queues.source": "old.tfstate" });
150
+
151
+ const other = fakeLedger();
152
+ other.approve("bo");
153
+ const e = sourced({ digest: "sha256:q-written-since" });
154
+ const moved = await runStateMigration(base(other, e, withSource()));
155
+ expect(moved.status === "moved" && moved.result.moved).toEqual(["queues"]);
156
+ expect(e.calls).not.toContain("write");
157
+
158
+ const plain = fakeLedger();
159
+ const a = await runStateMigration(base(plain, engine(), withSource()));
160
+ const b = await runStateMigration(base(fakeLedger(), engine(), plan()));
161
+ expect(a.status === "waiting" && b.status === "waiting" && a.digest !== b.digest).toBe(true);
162
+ });
163
+
164
+ test("a request that waits while an approval of an earlier one stands answers approval-moved, naming the roots that moved", async () => {
165
+ const ledger = fakeLedger();
166
+ const earlier = plan().map((r) => (r.root === "platform" ? { ...r, before: { version_id: "p0", digest: "sha256:p-older" } } : r));
167
+ const attachment = `${JSON.stringify({ name: "move-queues", roots: [...earlier].sort((x, y) => (x.root < y.root ? -1 : 1)).map((r) => ({ root: r.root, location: r.location, before: { version_id: r.before.version_id, digest: r.before.digest }, after: r.after.digest })) })}\n`;
168
+ const read = ledger.readGatedRequests;
169
+ ledger.readGatedRequests = async (op) => [
170
+ ...(await read(op)),
171
+ { op, gate: "move-queues", digest: "sha256:earlier", request: { kind: "migrate", subject: "move-queues", by: "ana", fields: {} }, pending: { timestamp: "2026-11-08T08:00:00Z" } as never, approvals: [{ resolvedBy: "bo", timestamp: "2026-11-08T08:30:00Z" } as never] } as never,
172
+ ];
173
+ const r = await runStateMigration({ ...base(ledger, engine()), readAttachment: async (_op, d) => (d === "sha256:earlier" ? attachment : undefined) });
174
+ expect(r).toMatchObject({ status: "approval-moved", exit: 4, approved: "sha256:earlier", approvedBy: "bo", moved: ["platform"] });
175
+
176
+ const own = fakeLedger();
177
+ own.readGatedRequests = async (op) => [{ op, gate: "move-queues", digest: "sha256:earlier", request: { kind: "migrate", subject: "move-queues", by: "ana", fields: {} }, pending: { timestamp: "2026-11-08T08:00:00Z" } as never, approvals: [{ resolvedBy: "ana", timestamp: "2026-11-08T08:30:00Z" } as never] } as never];
178
+ expect((await runStateMigration(base(own, engine()))).status).toBe("waiting");
179
+ });
180
+
181
+ test("its floor is the next release", () => {
182
+ expect(STATE_MIGRATION_SOURCE_FLOOR).toBe(NEXT_RELEASE);
183
+ });
184
+ });
@@ -28,14 +28,28 @@
28
28
  * released whatever happens. The finished line holds each root's
29
29
  * location and its version and digest before and after, never a
30
30
  * state's contents.
31
+ *
32
+ * A root whose new state is read from somewhere else (a backend move, #4806)
33
+ * names that place as its `source`: the request binds it, and under the
34
+ * locks the engine reads it again, so a source that moved refuses the write
35
+ * as a root's own state does. A request that waits while an approval of an
36
+ * earlier request of the same migration stands, made since that request was
37
+ * asked, answers `approval-moved` and names the roots whose state moved
38
+ * between the two (#4806).
31
39
  */
32
40
  import { CHANT_EXIT } from "./exit-codes";
33
- import { gatedOp, type GatedRequestLedger } from "./lifecycle/gated-op";
41
+ import { chantGatedLedger, gatedOp, type GatedRequestLedger } from "./lifecycle/gated-op";
34
42
  import type { GatedRequestRules } from "./lifecycle/gated-request";
43
+ import { gatedRequestAttachmentPath } from "./lifecycle/gated-request-digest";
44
+ import { samePlanDigest } from "./lifecycle/plan-digest";
45
+ import { NEXT_RELEASE } from "./release-floors";
35
46
 
36
47
  /** The first chant with the engine-neutral state migration (#4762). */
37
48
  export const STATE_MIGRATION_FLOOR = "0.124.77";
38
49
 
50
+ /** The first chant whose migration binds a root's `source` (an engine's `source` read under the locks) and answers `approval-moved`, and whose terraform lexicon plans backend moves (`planTerraformMigration`'s `backends`) and choudoufu estate migrations (`planEstateMigration`) onto it (#4806). */
51
+ export const STATE_MIGRATION_SOURCE_FLOOR = NEXT_RELEASE;
52
+
39
53
  /** A state as a migration binds it: its version id, when the store keeps versions, and its digest, null for no state. */
40
54
  export interface MigrationStateAt {
41
55
  version_id?: string;
@@ -62,6 +76,15 @@ export interface MigrationRootPlan {
62
76
  proof: MigrationCheck;
63
77
  /** The plan against the real state, after the write. */
64
78
  verify?: MigrationCheck;
79
+ /** Where the new state is read from, when that is not the root's own state (a backend move, #4806): the request binds it, and the write is refused when it moved. */
80
+ source?: MigrationSource;
81
+ }
82
+
83
+ /** A state a migration reads its new state from: where it is, its version id when its store keeps versions, and its digest. */
84
+ export interface MigrationSource {
85
+ location?: string;
86
+ version_id?: string;
87
+ digest: string;
65
88
  }
66
89
 
67
90
  /** The engine's half of a migration's write. */
@@ -70,6 +93,8 @@ export interface StateMigrationEngine {
70
93
  lock(): Promise<() => Promise<void>>;
71
94
  /** A root's state now, read under the locks. */
72
95
  current(root: string): Promise<MigrationStateAt>;
96
+ /** A root's source now, read under the locks; called for each root whose plan names a `source` (#4806). */
97
+ source?(root: string): Promise<MigrationStateAt>;
73
98
  /** Write every new state, in the engine's order. Throws at the first that fails. */
74
99
  write(): Promise<void>;
75
100
  /** After the write: the root planned against its real state, its version now, and its version before when only the write named it (a snapshot). */
@@ -103,6 +128,8 @@ export interface StateMigrationInput {
103
128
  base?: string;
104
129
  /** How long a request waits for its approval. Default 48h. */
105
130
  expiry?: string;
131
+ /** Reads an earlier request's attachment by its digest, to name the roots that moved since its approval. Default: the attachment on chant/lifecycle. */
132
+ readAttachment?: (op: string, digest: string) => Promise<string | undefined>;
106
133
  now?: string;
107
134
  runId?: string;
108
135
  commit?: string;
@@ -122,6 +149,8 @@ export interface StateMigrationResult {
122
149
  export type StateMigrationOutcome =
123
150
  | { status: "proof-failed"; exit: 1; roots: MigrationRootPlan[]; failing: string[] }
124
151
  | { status: "waiting"; exit: 3; digest: string; command: string }
152
+ /** It waits, and an approval of an earlier request of this migration stands: the states moved since, and `moved` names the roots whose state is not the one that request bound. Nothing was written. */
153
+ | { status: "approval-moved"; exit: 4; digest: string; command: string; approved: string; approvedBy: string; moved: string[] }
125
154
  | { status: "refused"; exit: 3; digest: string; command: string; by: string; reason: string }
126
155
  /** It applied already; a migration applies once. */
127
156
  | { status: "spent"; exit: 0; digest: string }
@@ -132,6 +161,15 @@ export type StateMigrationOutcome =
132
161
 
133
162
  const same = (a: MigrationStateAt, b: MigrationStateAt): boolean => (a.version_id ?? undefined) === (b.version_id ?? undefined) && a.digest === b.digest;
134
163
 
164
+ /** What a request's attachment binds of each root: its location and state before, its new state's digest, and its source when it has one. */
165
+ const boundRoot = (r: MigrationRootPlan) => ({
166
+ root: r.root,
167
+ location: r.location ?? null,
168
+ before: { version_id: r.before.version_id ?? null, digest: r.before.digest },
169
+ after: r.after.digest,
170
+ ...(r.source ? { source: { location: r.source.location ?? null, version_id: r.source.version_id ?? null, digest: r.source.digest } } : {}),
171
+ });
172
+
135
173
  /** The finished line's flat facts: how it ended, and each root's location, versions and digests. */
136
174
  export function migrationFacts(result: StateMigrationResult): Record<string, string | number | boolean> {
137
175
  const out: Record<string, string | number | boolean> = {
@@ -146,6 +184,8 @@ export function migrationFacts(result: StateMigrationResult): Record<string, str
146
184
  if (r.after.version_id) out[`${r.root}.after`] = r.after.version_id;
147
185
  if (r.before.digest) out[`${r.root}.before_digest`] = r.before.digest;
148
186
  if (r.after.digest) out[`${r.root}.after_digest`] = r.after.digest;
187
+ if (r.source?.location) out[`${r.root}.source`] = r.source.location;
188
+ if (r.source?.version_id) out[`${r.root}.source_version`] = r.source.version_id;
149
189
  }
150
190
  return out;
151
191
  }
@@ -160,7 +200,10 @@ export async function writeStateMigration(engine: StateMigrationEngine, roots: M
160
200
  const release = await engine.lock();
161
201
  try {
162
202
  const moved: string[] = [];
163
- for (const r of roots) if (!same(await engine.current(r.root), r.before)) moved.push(r.root);
203
+ for (const r of roots) {
204
+ if (!same(await engine.current(r.root), r.before)) moved.push(r.root);
205
+ else if (r.source && engine.source && !same(await engine.source(r.root), r.source)) moved.push(r.root);
206
+ }
164
207
  if (moved.length > 0) return { status: "moved", roots, moved };
165
208
  try {
166
209
  await engine.write();
@@ -193,7 +236,8 @@ export async function runStateMigration(input: StateMigrationInput): Promise<Sta
193
236
  if (failing.length > 0) return { status: "proof-failed", exit: CHANT_EXIT.failed, roots: input.roots, failing };
194
237
  const roots = [...input.roots].sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0));
195
238
  // The attachment binds each root's state before and after; the proof's wording is the engine's, not the migration.
196
- const attachment = `${JSON.stringify({ name: input.name, roots: roots.map((r) => ({ root: r.root, location: r.location ?? null, before: { version_id: r.before.version_id ?? null, digest: r.before.digest }, after: r.after.digest })) }, null, 2)}\n`;
239
+ const attachment = `${JSON.stringify({ name: input.name, roots: roots.map(boundRoot) }, null, 2)}\n`;
240
+ const now = input.now ?? new Date().toISOString();
197
241
  const result = await gatedOp(
198
242
  {
199
243
  op: input.words.op,
@@ -204,7 +248,7 @@ export async function runStateMigration(input: StateMigrationInput): Promise<Sta
204
248
  attachment,
205
249
  ...(input.base ? { base: input.base } : {}),
206
250
  ...(input.cwd ? { cwd: input.cwd } : {}),
207
- ...(input.now ? { now: input.now } : {}),
251
+ now,
208
252
  ...(input.runId ? { runId: input.runId } : {}),
209
253
  ...(input.commit ? { commit: input.commit } : {}),
210
254
  ...(input.ledger ? { ledger: input.ledger } : {}),
@@ -216,8 +260,11 @@ export async function runStateMigration(input: StateMigrationInput): Promise<Sta
216
260
  );
217
261
  const command = (fallback: string): string => (input.words.approveCommand ? input.words.approveCommand(input.name, result.digest) : fallback);
218
262
  switch (result.status) {
219
- case "waiting":
263
+ case "waiting": {
264
+ const stood = await approvalMovedFrom(input, roots, result.digest, now);
265
+ if (stood) return { status: "approval-moved", exit: CHANT_EXIT.moved, digest: result.digest, command: command(result.command), ...stood };
220
266
  return { status: "waiting", exit: CHANT_EXIT.waiting, digest: result.digest, command: command(result.command) };
267
+ }
221
268
  case "refused":
222
269
  return { status: "refused", exit: CHANT_EXIT.waiting, digest: result.digest, command: command(result.command), by: result.by, reason: result.reason };
223
270
  case "spent":
@@ -234,3 +281,58 @@ export async function runStateMigration(input: StateMigrationInput): Promise<Sta
234
281
  }
235
282
  }
236
283
  }
284
+
285
+ /** An earlier request's attachment on chant/lifecycle, by its digest. */
286
+ async function ledgerAttachment(op: string, digest: string, cwd?: string): Promise<string | undefined> {
287
+ const { readBlobFromPath } = await import("./lifecycle/git");
288
+ const { dir, file } = gatedRequestAttachmentPath(op, digest);
289
+ return (await readBlobFromPath(dir, file, cwd ? { cwd } : undefined)) ?? undefined;
290
+ }
291
+
292
+ /**
293
+ * The approval a waiting request moved away from (#4806): a state written
294
+ * after an approval changes the request's digest, so the migration asks
295
+ * again. The approval that stands is the newest of another request of the
296
+ * migration, unspent, not its requester's own, and made since the newest
297
+ * pending fact before this run (`now` is this run's: a pending fact of that
298
+ * time is the one this run asked). The roots that moved are those whose
299
+ * bound state differs from that request's attachment, or every root when
300
+ * the attachment cannot be read. Undefined when no approval stands.
301
+ *
302
+ * Lifted from terragucci's `movedSinceChantApproval` and `beforeMembers`.
303
+ */
304
+ async function approvalMovedFrom(input: StateMigrationInput, roots: MigrationRootPlan[], digest: string, now: string): Promise<{ approved: string; approvedBy: string; moved: string[] } | undefined> {
305
+ const ledger = input.ledger ?? chantGatedLedger;
306
+ let requests: Awaited<ReturnType<GatedRequestLedger["readGatedRequests"]>>;
307
+ try {
308
+ requests = await ledger.readGatedRequests(input.words.op, input.cwd ? { cwd: input.cwd } : undefined);
309
+ } catch {
310
+ return undefined;
311
+ }
312
+ const t = (s: string | undefined): number => (s ? Date.parse(s) : 0);
313
+ const mine = requests.filter((r) => r.gate === input.name);
314
+ const asked = (r: (typeof mine)[number]): boolean => samePlanDigest(r.digest, digest) && t(r.pending.timestamp) === t(now);
315
+ const since = Math.max(0, ...mine.filter((r) => !asked(r)).map((r) => t(r.pending.timestamp)).filter((x) => !Number.isNaN(x)));
316
+ let prior: (typeof mine)[number] | undefined;
317
+ let approval: (typeof mine)[number]["approvals"][number] | undefined;
318
+ for (const r of mine) {
319
+ if (samePlanDigest(r.digest, digest) || r.applied) continue;
320
+ const requester = r.request.by.toLowerCase();
321
+ for (const a of r.approvals) {
322
+ if (a.resolvedBy.toLowerCase() === requester || t(a.timestamp) < since) continue;
323
+ if (!approval || t(a.timestamp) >= t(approval.timestamp)) [prior, approval] = [r, a];
324
+ }
325
+ }
326
+ if (!prior || !approval) return undefined;
327
+ let stored: { roots?: unknown } | undefined;
328
+ try {
329
+ const text = input.readAttachment ? await input.readAttachment(input.words.op, prior.digest) : await ledgerAttachment(input.words.op, prior.digest, input.cwd);
330
+ stored = text ? (JSON.parse(text) as { roots?: unknown }) : undefined;
331
+ } catch {
332
+ stored = undefined;
333
+ }
334
+ const was = new Map<string, string>();
335
+ if (Array.isArray(stored?.roots)) for (const r of stored.roots as Array<{ root?: unknown }>) if (typeof r.root === "string") was.set(r.root, JSON.stringify({ ...r, after: null }));
336
+ const moved = Array.isArray(stored?.roots) ? roots.filter((r) => was.get(r.root) !== JSON.stringify({ ...boundRoot(r), after: null })).map((r) => r.root) : roots.map((r) => r.root);
337
+ return { approved: prior.digest, approvedBy: approval.resolvedBy, moved };
338
+ }
@@ -34,6 +34,8 @@
34
34
  */
35
35
 
36
36
  import { join, posix } from "node:path";
37
+ import { ROOT_SOURCE_EXCLUDES, resolveSourceDir } from "../config";
38
+ import { compileDiscoveryFilter } from "../discovery/files";
37
39
  import type { StaticFieldsRead } from "../config-static";
38
40
  import { isDeclarable, type Declarable } from "../declarable";
39
41
  import type { LexiconUnreadSource, LexiconWorkspaceLinks, LexiconWorkspaceOutput } from "../graph-ir";
@@ -84,12 +86,23 @@ function staticSourceDir(read: StaticFieldsRead): string | undefined {
84
86
  return dir === "." || dir === "" ? undefined : dir;
85
87
  }
86
88
 
89
+ /** The `include` globs a member's config sets, read without running it. */
90
+ function staticInclude(read: StaticFieldsRead): string[] {
91
+ const value = read.status === "read" ? read.fields.include : undefined;
92
+ return Array.isArray(value) ? value.filter((g): g is string => typeof g === "string") : [];
93
+ }
94
+
87
95
  /**
88
96
  * Only the files under the member's `sourceDir`, when its config sets one, as
89
- * a build reads them (#3941). Without one, every source file of the member.
97
+ * a build reads them (#3941). Without one, every source file of the member
98
+ * but its top-level `scripts/`, which a root build leaves out (#4794,
99
+ * `ROOT_SOURCE_EXCLUDES`) unless `include` brings it back.
90
100
  */
91
- function withinSourceDir(files: string[], member: string, sourceDir: string | undefined): string[] {
92
- if (!sourceDir) return files;
101
+ function withinSourceDir(files: string[], member: string, sourceDir: string | undefined, include: string[] = []): string[] {
102
+ if (!sourceDir) {
103
+ const skipped = compileDiscoveryFilter({ root: member || ".", exclude: [...ROOT_SOURCE_EXCLUDES], include });
104
+ return skipped ? files.filter((f) => !skipped(f)) : files;
105
+ }
93
106
  const prefix = `${member ? `${member}/` : ""}${sourceDir}/`;
94
107
  return files.filter((f) => f.startsWith(prefix));
95
108
  }
@@ -207,10 +220,13 @@ async function foldMember(
207
220
  const what = hook === "workspaceOutputs" ? "outputs" : "links";
208
221
  const dir = memberDirOnDisk(root, m.dir);
209
222
  const { readConfigFieldsStatically } = await import("../config-static");
223
+ // Read apart, so an `include` that can't be read statically never costs the member its `sourceDir`.
224
+ const sourceDir = staticSourceDir(readConfigFieldsStatically(dir, ["sourceDir"]));
210
225
  const files = withinSourceDir(
211
226
  sourceFiles(tree, memberDir(m.dir), memberExcludes(declaration, groups, m)),
212
227
  memberDir(m.dir),
213
- staticSourceDir(readConfigFieldsStatically(dir, ["sourceDir"])),
228
+ sourceDir,
229
+ sourceDir ? [] : staticInclude(readConfigFieldsStatically(dir, ["include"])),
214
230
  );
215
231
  let names: string[];
216
232
  try {
@@ -280,9 +296,10 @@ async function foldMember(
280
296
  if (typeof plugin.buildRoots !== "function") continue;
281
297
  const read = readConfigFieldsStatically(dir, [name, "sourceDir"]);
282
298
  const config = read.status === "read" ? read.fields : {};
283
- const sourceDir = typeof config.sourceDir === "string" ? join(dir, config.sourceDir) : undefined;
299
+ // #4794: the build's own rule, so the hook reads the directory a build of the member would.
300
+ const sourceDir = resolveSourceDir(dir, config);
284
301
  try {
285
- const contributed = await plugin.buildRoots({ projectRoot: dir, config, entities, ...(sourceDir ? { sourceDir } : {}) });
302
+ const contributed = await plugin.buildRoots({ projectRoot: dir, config, entities, sourceDir });
286
303
  for (const [key, entity] of contributed.entities) if (!entities.has(key)) entities.set(key, entity);
287
304
  } catch (err) {
288
305
  gaps.push(`lexicon "${name}" could not read the member's other source files, so their declarations were not read (${firstLine(err)})`);
@@ -59,6 +59,7 @@ import { CI_GREEN_ERROR_CODES } from "./ci-green";
59
59
  import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
60
60
  import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
61
61
  import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
62
+ import { REF_GATE_CHECK_CODES, REF_GATE_ERROR_CODES } from "./trust/ref-gate";
62
63
  import { METRICS_ERROR_CODES, METRICS_REASON_CODES } from "./delivery-metrics";
63
64
  import { SEARCH_ERROR_CODES, SEARCH_MEMBER_REASON_CODES, WORKSPACE_SEARCH_ERROR_CODES } from "./search-contract";
64
65
  import { CAPABILITIES_ERROR_CODES, CAPABILITY_SUPPORT_CODES } from "./capabilities-contract";
@@ -142,6 +143,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
142
143
  ROTATION_REFUSAL_CODES,
143
144
  SIGNERS_ERROR_CODES,
144
145
  EVIDENCE_ERROR_CODES,
146
+ REF_GATE_ERROR_CODES,
147
+ REF_GATE_CHECK_CODES,
145
148
  METRICS_ERROR_CODES,
146
149
  METRICS_REASON_CODES,
147
150
  SEARCH_ERROR_CODES,
@@ -382,6 +382,10 @@ export const REASONS = {
382
382
  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM, or the key given to trust runner add is not an ssh-ed25519 public key or an Ed25519 key in PEM.",
383
383
  "runner-key-is-signer": "The key given to evidence sign, runs sign or trust runner add is a person's key in the signers file, or trust runner add names a signer. Evidence and run statements are signed by a service or CI identity.",
384
384
  "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign or runs sign.",
385
+ // The ref gate (workspace ref-gate, #4867): why an update can't be decided, and why a required check has no current evidence.
386
+ "ref-update-invalid": "The hook's standard input is not the lines git hands a pre-receive or pre-push hook.",
387
+ "ref-evidence-missing": "No runner evidence for a check the policy at base requires for the ref is attached to the pushed commit.",
388
+ "ref-evidence-stale": "Evidence for a required check verifies, but a record it names changed after it was signed, or it names no records and was signed over another tree.",
385
389
  // The lineage lock (check).
386
390
  "lock-invalid": "The lineage lock can't be read.",
387
391
  "manual-step-open": "A scope in the lineage lock has an open manual step.",