@intentius/chant 0.124.94 → 0.124.95

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 (39) hide show
  1. package/dist/ci-comment-commands.d.ts +12 -1
  2. package/dist/ci-comment-commands.d.ts.map +1 -1
  3. package/dist/ci-comment-commands.js +29 -0
  4. package/dist/ci-note-commands.d.ts +1 -1
  5. package/dist/ci-note-commands.d.ts.map +1 -1
  6. package/dist/ci-note-commands.js +11 -1
  7. package/dist/ci-product.d.ts +2 -0
  8. package/dist/ci-product.d.ts.map +1 -1
  9. package/dist/ci-product.js +5 -4
  10. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  11. package/dist/cli/handlers/pr-comment.js +11 -4
  12. package/dist/components/product-pipeline.d.ts.map +1 -1
  13. package/dist/components/product-pipeline.js +4 -2
  14. package/dist/components/product-plan.d.ts +6 -0
  15. package/dist/components/product-plan.d.ts.map +1 -1
  16. package/dist/components/product-plan.js +9 -1
  17. package/dist/floor-table.data.d.ts.map +1 -1
  18. package/dist/floor-table.data.js +9 -7
  19. package/dist/op/before-merge-decide.d.ts +39 -2
  20. package/dist/op/before-merge-decide.d.ts.map +1 -1
  21. package/dist/op/before-merge-decide.js +59 -0
  22. package/dist/release-floors.d.ts +5 -1
  23. package/dist/release-floors.d.ts.map +1 -1
  24. package/dist/release-floors.js +9 -5
  25. package/dist/wave-runtime.mjs +182 -182
  26. package/package.json +1 -1
  27. package/src/ci-comment-commands.test.ts +147 -0
  28. package/src/ci-comment-commands.ts +29 -1
  29. package/src/ci-note-commands.ts +12 -2
  30. package/src/ci-product.ts +5 -4
  31. package/src/cli/handlers/pr-comment.ts +10 -4
  32. package/src/components/product-pipeline.ts +4 -2
  33. package/src/components/product-plan.ts +9 -2
  34. package/src/floor-table.data.ts +9 -7
  35. package/src/op/before-merge-decide.ts +74 -2
  36. package/src/op/op-waves-remainder.test.ts +2 -3
  37. package/src/op/op-waves-render-spec.test.ts +1 -2
  38. package/src/op/op-waves-split-resume.test.ts +2 -3
  39. package/src/release-floors.ts +11 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant",
3
- "version": "0.124.94",
3
+ "version": "0.124.95",
4
4
  "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://intentius.io/chant",
@@ -451,3 +451,150 @@ describe("the comment job's apply before merge on the waves (#4984)", () => {
451
451
  expect(() => commentJobsFromEnv(JSON.stringify({ ...jobs, wavesBeforeMerge: { ...bm, requires: ["green"] } }))).toThrow("requires is a list of approved, mergeable, undiverged, checks");
452
452
  });
453
453
  });
454
+
455
+ describe("lock and unlock before merge, by the reach line (#5061)", () => {
456
+ const bm = { workflow: "tf-apply.yml", plan: ["terragucci/plan"], pipelineFiles: [".github/workflows/"], locks: { gate: "tf-apply" } };
457
+ const jobs: CommentJobs = { applyOnMerge: true, waves: { op: "tf-apply", count: 2 }, wavesBeforeMerge: bm };
458
+
459
+ /** A checkout of the default branch whose origin is itself, so the base fetch works. */
460
+ async function checkout() {
461
+ const { spawnSync } = await import("node:child_process");
462
+ const { mkdtempSync, writeFileSync } = await import("node:fs");
463
+ const { tmpdir } = await import("node:os");
464
+ const { join } = await import("node:path");
465
+ const dir = mkdtempSync(join(tmpdir(), "chant-cc-locks-"));
466
+ const git = (...args: string[]) => {
467
+ const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
468
+ if (r.status !== 0) throw new Error(r.stderr);
469
+ return r.stdout.trim();
470
+ };
471
+ git("init", "-q", "-b", "main");
472
+ writeFileSync(join(dir, "main.tf"), "1");
473
+ git("add", ".");
474
+ git("commit", "-q", "-m", "base");
475
+ git("remote", "add", "origin", dir);
476
+ const run: NonNullable<AnswerCommentOptions["beforeMerge"]>["git"] = (argv, o) => {
477
+ const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8", ...(o.cwd ? { cwd: o.cwd } : {}) });
478
+ return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
479
+ };
480
+ return { dir, baseSha: git("rev-parse", "HEAD"), git: run };
481
+ }
482
+
483
+ /** The comment job with the lock and unlock the handler gives it, each call kept. */
484
+ async function locking(body: string, o: { forge?: "github" | "forgejo"; pr?: Partial<PullRequestDetail>; jobs?: CommentJobs; held?: string; released?: string[]; reached?: string[]; permission?: string; event?: Record<string, unknown> } = {}) {
485
+ const c = await checkout();
486
+ const head = "c".repeat(40);
487
+ const s = setup({ pr: { state: "open", headSha: head, mergeCommit: undefined, ...o.pr }, ...(o.permission ? { permission: o.permission } : {}) }, o.jobs ?? jobs, body, { ...(o.forge ? { forge: o.forge } : {}), ...(o.event ? { event: o.event } : {}) });
488
+ const locked: Array<[number, string, string, string, string | undefined]> = [];
489
+ const unlocked: number[] = [];
490
+ const got = await answerProductComment({
491
+ ...s.opts,
492
+ beforeMerge: {
493
+ requires: async () => null,
494
+ statuses: async () => [],
495
+ git: c.git,
496
+ cwd: c.dir,
497
+ lock: async (pr, h, base, by, asked) => {
498
+ locked.push([pr, h, base, by, asked]);
499
+ return o.held ? { ok: false, text: o.held } : { ok: true, targets: o.reached ?? ["envs/dev", "envs/prod"] };
500
+ },
501
+ unlock: async (pr) => (unlocked.push(pr), o.released ?? ["envs/dev"]),
502
+ record: async () => {
503
+ throw new Error("a lock records no decision");
504
+ },
505
+ stop: async () => {
506
+ throw new Error("a lock writes no wave stop");
507
+ },
508
+ },
509
+ });
510
+ return { got, posted: s.posted, locked, unlocked, dispatched: s.dispatched, head, baseSha: c.baseSha };
511
+ }
512
+
513
+ for (const forge of ["github", "forgejo"] as const) {
514
+ test(`${forge}: /terragucci lock takes the locks of what the reach line prints, measured from the default branch, and applies nothing`, async () => {
515
+ const r = await locking("/terragucci lock", { forge });
516
+ expect(r.locked).toEqual([[12, r.head, r.baseSha, "alice", "lock"]]);
517
+ expect(r.dispatched).toEqual([]);
518
+ expect(r.got).toMatchObject({ command: "lock", ran: false, replied: true });
519
+ expect(r.posted).toEqual([`terragucci: locked \`envs/dev\`, \`envs/prod\` for pull request 12 at ${r.head.slice(0, 8)} for alice, and nothing is applied; the locks hold until it merges or closes, or \`/terragucci unlock\` releases them`]);
520
+ });
521
+
522
+ test(`${forge}: a lock another open pull request holds is refused with its holder named`, async () => {
523
+ const held = "`envs/dev` is locked by pull request 9 (alice, apply), so pull request 12 takes no lock. It can once that pull request merges or closes, or someone with write access unlocks it";
524
+ const r = await locking("/terragucci lock", { forge, held });
525
+ expect(r.posted).toEqual([`terragucci: ${held}`]);
526
+ expect(r.got.fail).toBeUndefined();
527
+ });
528
+
529
+ test(`${forge}: /terragucci unlock releases the pull request's locks`, async () => {
530
+ const r = await locking("/terragucci unlock", { forge });
531
+ expect(r.unlocked).toEqual([12]);
532
+ expect(r.locked).toEqual([]);
533
+ expect(r.posted).toEqual(["terragucci: released `envs/dev`, which pull request 12 held, for alice"]);
534
+ const none = await locking("/terragucci unlock", { forge, released: [] });
535
+ expect(none.posted).toEqual(["terragucci: pull request 12 holds no lock, so there is nothing to unlock"]);
536
+ });
537
+
538
+ test(`${forge}: a fork is refused, and someone without write access gets nothing`, async () => {
539
+ const fork = await locking("/terragucci lock", { forge, pr: { sameRepo: false } });
540
+ expect(fork.locked).toEqual([]);
541
+ expect(fork.posted).toEqual([`terragucci: ${tgInput.replies!.fork}`]);
542
+ const forkUnlock = await locking("/terragucci unlock", { forge, pr: { sameRepo: false } });
543
+ expect(forkUnlock.unlocked).toEqual([]);
544
+ const reader = await locking("/terragucci lock", forge === "github" ? { forge, permission: "read" } : { forge, event: { repository: { full_name: "acme/infra", default_branch: "main", permissions: { push: false } } } });
545
+ expect(reader.locked).toEqual([]);
546
+ expect(reader.posted).toEqual([]);
547
+ expect(reader.got.replied).toBe(false);
548
+ });
549
+ }
550
+
551
+ test("a closed pull request takes no lock, one into another branch neither, and reaching nothing locks nothing", async () => {
552
+ expect((await locking("/terragucci lock", { pr: { state: "closed" } })).posted).toEqual(["terragucci: pull request 12 is not open, so it takes no lock"]);
553
+ expect((await locking("/terragucci lock", { pr: { base: "release" } })).posted).toEqual(["terragucci: pull request 12 targets release, not the default branch main, so it takes no lock"]);
554
+ const r = await locking("/terragucci lock", { reached: [] });
555
+ expect(r.posted).toEqual([`terragucci: pull request 12 reaches nothing at ${r.head.slice(0, 8)}, so it takes no lock`]);
556
+ });
557
+
558
+ test("with the comment lock jobs of locks: \"plan\", or without the reach line, nothing changes", async () => {
559
+ const planLocks = await locking("/terragucci lock", { jobs: { ...jobs, locks: true } });
560
+ expect(planLocks.got).toMatchObject({ replied: false, reason: "another job answers this comment" });
561
+ expect(planLocks.locked).toEqual([]);
562
+ const { locks: _l, ...noReach } = bm;
563
+ const without = await locking("/terragucci unlock", { jobs: { ...jobs, wavesBeforeMerge: noReach } });
564
+ expect(without.unlocked).toEqual([]);
565
+ expect(without.posted).toEqual([`terragucci: ${tgInput.replies!.unlock}`]);
566
+ });
567
+
568
+ test("GitLab's note poll locks and unlocks the same way through chantNoteRuns", async () => {
569
+ const c = await checkout();
570
+ const head = "d".repeat(40);
571
+ const mr: PullRequestDetail = { number: 3, title: "", body: "", state: "open", head: "feature", headSha: head, base: "main", sameRepo: true };
572
+ const locked: unknown[] = [];
573
+ const unlocked: number[] = [];
574
+ const deps = {
575
+ requires: async () => null,
576
+ statuses: async () => [],
577
+ git: c.git,
578
+ cwd: c.dir,
579
+ lock: async (pr: number, h: string, base: string, by: string, asked?: "apply" | "lock") => (locked.push([pr, h, base, by, asked]), { ok: true as const, targets: ["envs/dev"] }),
580
+ unlock: async (pr: number) => (unlocked.push(pr), ["envs/dev"]),
581
+ record: async () => {
582
+ throw new Error("no decision");
583
+ },
584
+ stop: async () => {},
585
+ };
586
+ const glJobs = { applyOnMerge: true, waves: { op: "tf-apply", count: 2 }, wavesBeforeMerge: { plan: ["terragucci/plan"], pipelineFiles: [".gitlab-ci.yml"], locks: { gate: "tf-apply" } } };
587
+ const runs = chantNoteRuns(glJobs, { beforeMerge: deps });
588
+ const ask = (body: string, m = mr): Omit<NoteCommand, "parsed"> => ({ mr: m, note: { id: 41, body, system: false, author: "bob" }, role: "developer", base: "main", words: tg });
589
+ expect(await runs({ ...ask("/terragucci lock"), parsed: { kind: "lock" } })).toEqual({ kind: "reply", text: `locked \`envs/dev\` for !3 at ${head.slice(0, 8)} for bob, and nothing is applied; the locks hold until it merges or closes, or \`/terragucci unlock\` releases them` });
590
+ expect(locked).toEqual([[3, head, c.baseSha, "bob", "lock"]]);
591
+ expect(await runs({ ...ask("/terragucci unlock"), parsed: { kind: "unlock" } })).toEqual({ kind: "reply", text: "released `envs/dev`, which !3 held, for bob" });
592
+ expect(unlocked).toEqual([3]);
593
+ expect(await runs({ ...ask("/terragucci lock", { ...mr, sameRepo: false }), parsed: { kind: "lock" } })).toEqual({ kind: "reply", text: tgInput.replies!.fork });
594
+ // With locks: "plan" the lock job runs, as before; without the reach line the product's sentence.
595
+ expect((await chantNoteRuns({ ...glJobs, locks: true }, { beforeMerge: deps })({ ...ask("/terragucci lock"), parsed: { kind: "lock" } })).kind).toBe("pipeline");
596
+ const { lock: _lock, unlock: _unlock, ...noReach } = deps;
597
+ expect(await chantNoteRuns(glJobs, { beforeMerge: noReach })({ ...ask("/terragucci lock"), parsed: { kind: "lock" } })).toEqual({ kind: "reply", text: tgInput.replies!.lock });
598
+ expect(locked).toHaveLength(1);
599
+ });
600
+ });
@@ -36,6 +36,10 @@
36
36
  * open pull request: the decision before merge
37
37
  * (./op/before-merge-decide.ts) records the head on `chant/lifecycle`
38
38
  * and dispatches the waves workflow on the default branch for it.
39
+ * - with `wavesBeforeMerge`, the product plan's reach line and no comment
40
+ * lock jobs (#5061), `/<product> lock` and `/<product> unlock`: the lock
41
+ * takes the locks of what the reach line prints at stage apply without
42
+ * applying, and the unlock releases the pull request's locks.
39
43
  *
40
44
  * Who asked comes first. On GitHub the commenter's permission is read from
41
45
  * the forge; Forgejo answers 403 when a job's token asks for another user's
@@ -113,7 +117,17 @@ export interface CommentJobs extends Omit<ChantNoteJobs, "members"> {
113
117
  }
114
118
 
115
119
  /** What the decision before merge reads and writes with (#4984), the comment job's handler's. */
116
- export type CommentBeforeMerge = Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "record" | "stop" | "now">;
120
+ export type CommentBeforeMerge = Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "unlock" | "record" | "stop" | "now">;
121
+
122
+ /**
123
+ * Whether `/<product> lock` and `/<product> unlock` are the comment job's
124
+ * (the note poll's on GitLab) under the waves before merge (#5061): the
125
+ * pipeline has the product plan's reach line and no comment lock jobs of
126
+ * `locks: "plan"`, and the job has the lock and unlock to answer with.
127
+ */
128
+ export function locksBeforeMerge(jobs: Pick<CommentJobs, "locks" | "wavesBeforeMerge">, deps: Pick<CommentBeforeMerge, "lock" | "unlock"> | undefined): deps is Required<Pick<CommentBeforeMerge, "lock" | "unlock">> {
129
+ return !jobs.locks && jobs.wavesBeforeMerge?.locks !== undefined && deps?.lock !== undefined && deps.unlock !== undefined;
130
+ }
117
131
 
118
132
  /** Writes a wave stop for op `op` at `sha` on `chant/lifecycle`, or clears it (#4979). */
119
133
  export type CommentWaveStops = (op: string, sha: string, stop: { through: number; at: string; by?: string; pr?: number } | null) => Promise<void>;
@@ -298,6 +312,20 @@ export async function answerProductComment(o: AnswerCommentOptions): Promise<Com
298
312
  }
299
313
  // A command another job answers starts that job on this same comment.
300
314
  if (parsed.kind !== "apply" && answeredElsewhere(parsed, o.jobs, true)) return silent("another job answers this comment", command);
315
+ // #5061: the waves before merge with the reach line and no plan locks: the lock and unlock are this job's.
316
+ if ((parsed.kind === "lock" || parsed.kind === "unlock") && o.beforeMerge && locksBeforeMerge(o.jobs, o.beforeMerge)) {
317
+ let pr: PullRequestDetail | undefined;
318
+ try {
319
+ pr = await o.reads.pullRequest(n);
320
+ } catch (err) {
321
+ return broke(`could not read ${t.at(n)} (${message(err)})`, command);
322
+ }
323
+ if (!pr) return broke(`the forge has no ${t.at(n)}`, command);
324
+ const { decideLocksBeforeMerge } = await import("./op/before-merge-decide");
325
+ const bm = o.beforeMerge;
326
+ const done = await decideLocksBeforeMerge({ forge: o.forge, pr, user, base: o.base, kind: parsed.kind, words: o.words, git: bm.git, ...(bm.cwd ? { cwd: bm.cwd } : {}), lock: bm.lock!, unlock: bm.unlock! });
327
+ return done.kind === "fail" ? broke(done.reason, command) : reply(done.text);
328
+ }
301
329
  switch (parsed.kind) {
302
330
  case "plan":
303
331
  case "lock":
@@ -498,7 +498,7 @@ export interface ChantNoteJobs {
498
498
  /** What {@link chantNoteRuns} reads and writes with besides the jobs (#4984). */
499
499
  export interface ChantNoteRunsOptions {
500
500
  /** With `jobs.wavesBeforeMerge`: what the decision before merge reads and writes with. */
501
- beforeMerge?: Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "record" | "stop" | "now">;
501
+ beforeMerge?: Pick<DecideBeforeMergeInput, "requires" | "statuses" | "git" | "cwd" | "lock" | "unlock" | "record" | "stop" | "now">;
502
502
  }
503
503
 
504
504
  /**
@@ -543,10 +543,20 @@ export function chantNoteRuns(jobs: ChantNoteJobs, opts: ChantNoteRunsOptions =
543
543
  if (!mr.mergeCommit) return { kind: "fail", reason: `${at} has no merge commit` };
544
544
  return { kind: "retry", sha: mr.mergeCommit, ...(jobs.waves ? { stop: { op: jobs.waves.op, through: parsed.wave !== undefined && parsed.wave < jobs.waves.count ? parsed.wave : null } } : {}) };
545
545
  case "lock":
546
- case "unlock":
546
+ case "unlock": {
547
+ // #5061: the waves before merge with the reach line and no plan locks: the poll locks and unlocks here.
548
+ const bm = opts.beforeMerge;
549
+ if (!jobs.locks && jobs.wavesBeforeMerge?.locks !== undefined && bm?.lock && bm.unlock) {
550
+ const { lock, unlock } = bm;
551
+ return import("./op/before-merge-decide").then(async ({ decideLocksBeforeMerge }) => {
552
+ const done = await decideLocksBeforeMerge({ forge: "gitlab", pr: mr, user: note.author ?? "", base, kind: parsed.kind as "lock" | "unlock", words, git: bm.git, ...(bm.cwd ? { cwd: bm.cwd } : {}), lock, unlock });
553
+ return done.kind === "fail" ? { kind: "fail" as const, reason: done.reason } : { kind: "reply" as const, text: done.text };
554
+ });
555
+ }
547
556
  if (!jobs.locks) return { kind: "reply", text: notRunReply(words, parsed.kind, "gitlab") };
548
557
  if (parsed.kind === "lock" && !open) return { kind: "reply", text: `${at} is not open, so it takes no lock` };
549
558
  return { kind: "pipeline", ref: base, variables: { [parsed.kind === "lock" ? GITLAB_LOCK_PR_VAR : GITLAB_UNLOCK_PR_VAR]: iid }, doing: `${parsed.kind} the ${words.noun[1]} of ${at}` };
559
+ }
550
560
  case "agent":
551
561
  if (!jobs.agent) return { kind: "reply", text: notRunReply(words, "agent", "gitlab") };
552
562
  if (!open) return { kind: "reply", text: `${at} is not open, so the agent does not run` };
package/src/ci-product.ts CHANGED
@@ -13,7 +13,6 @@ import type { CiProductWords, CiProductWordsInput } from "./ci-product-words";
13
13
  import type { ProductMcpHook } from "./cli/mcp/product-tools";
14
14
  import type { ProductWaveHook } from "./op/op-waves-after-plan";
15
15
  import { OTLP_EXPORTER_FLOOR } from "./otlp";
16
- import { NEXT_RELEASE } from "./release-floors";
17
16
 
18
17
  /**
19
18
  * The first chant with the product pipeline (#4550): the words, the
@@ -308,17 +307,17 @@ export const NOTE_POLL_NAMES_FLOOR = "0.124.93";
308
307
  /**
309
308
  * The first chant whose Op waves generators take `commandToken` (#5044), GitHub and Forgejo: the jobs that run only the default branch's code (a push's wave, deciding, share and job group jobs; a split wave's gate and record jobs) hand their command step the job's token as `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and a failed apply's triage and a product's hooks can read the forge, and ask for `permissions` beside chant's own. A split wave's plan and applying jobs never get it; GitLab refuses it. Without it no wave job holds a token, as before.
310
309
  */
311
- export const OP_WAVES_COMMAND_TOKEN_FLOOR = NEXT_RELEASE;
310
+ export const OP_WAVES_COMMAND_TOKEN_FLOOR = "0.124.94";
312
311
 
313
312
  /**
314
313
  * The first chant whose GitLab Op waves generator takes `cache` (#5045): the `cache:` entry or entries of each job that runs the wave's command (the wave's own, deciding, share and job group jobs, the policy job, a split wave's plan and applying jobs), such as terragucci's Terragrunt sources and providers cache. The gate and record jobs take none; GitHub and Forgejo refuse it, since a wave's `setup` step does this there. Without it no wave job has a cache, as before.
315
314
  */
316
- export const OP_WAVES_GITLAB_CACHE_FLOOR = NEXT_RELEASE;
315
+ export const OP_WAVES_GITLAB_CACHE_FLOOR = "0.124.94";
317
316
 
318
317
  /**
319
318
  * The first chant whose Op waves generators take `controlGroup` and `resumeGroup` (#5053): the control job's group (GitHub and Forgejo `concurrency` with `cancel-in-progress: false`, GitLab `resource_group`), with `{commit}` standing for the commit it tells the control repo about, so a push's run and a resume's run send one dispatch per commit; and the GitLab resume job's `resource_group`. Without them neither job has a group, as before.
320
319
  */
321
- export const OP_WAVES_GROUPS_FLOOR = NEXT_RELEASE;
320
+ export const OP_WAVES_GROUPS_FLOOR = "0.124.94";
322
321
  export { opWavesArtifacts, opWavesCommandToken, opWavesControlGroup, opWavesDispatchInputs, opWavesGitlabCache, opWavesNamer, opWavesResumeGroup, opWavesResumeWorkflowFile, opWavesWorkflowFile, type OpWavesArtifactNames, type OpWavesCommandToken, type OpWavesDispatchInput, type OpWavesJobNames, type OpWavesJobRef, type OpWavesJobRole, type OpWavesStageNames, type OpWavesStageRef } from "./op/op-waves-names";
323
322
 
324
323
  /**
@@ -536,6 +535,8 @@ export { MCP_TOOL_ANNOTATIONS_FLOOR, PRODUCT_MCP_PROPOSE_FLOOR, PRODUCT_TOOL_PRO
536
535
  export { OP_WAVES_REMAINDER_FLOOR } from "./release-floors";
537
536
  export { OP_WAVES_SPLIT_RESUME_FLOOR } from "./release-floors";
538
537
  export { OP_WAVES_REMAINDER_PARITY_FLOOR } from "./release-floors";
538
+ /** #5061: the waves before merge lock and unlock on a comment by the reach line. */
539
+ export { WAVES_BEFORE_MERGE_LOCKS_FLOOR } from "./release-floors";
539
540
  export type { McpToolContribution, ToolAnnotations } from "./mcp/types";
540
541
  export {
541
542
  activeOtlp,
@@ -106,13 +106,14 @@ export async function beforeMergeDeps(forge: PrForge, jobs: CommentJobs, env: No
106
106
  const { checkPrRequires, unmetRequires } = await import("../../pr-requires");
107
107
  const { productStatusContext, activeProductWords } = await import("../../ci-product-words");
108
108
  const { LOCK_REACH_ENV, reachedTargets } = await import("../../lifecycle/reach-locks");
109
- const { takeTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
109
+ const { takeTargetLocks, releaseTargetLocks, describeHeldTargetLocks } = await import("../../lifecycle/target-lock");
110
110
  const { recordBeforeMerge } = await import("../../op/before-merge-store");
111
111
  const { setWaveStop } = await import("../../op/wave-stop");
112
112
  const { PR_APPLY_GATE } = await import("../../pr-loop");
113
113
  const words = activeProductWords();
114
114
  const line = env[LOCK_REACH_ENV];
115
115
  const name = (n: number) => (forge.kind === "gitlab" ? `!${n}` : `pull request ${n}`);
116
+ const gate = bm.locks?.gate ?? PR_APPLY_GATE;
116
117
  return {
117
118
  // The plan and apply statuses never hold the apply back: the plan status is asked for by name (#5003: the product plan's own names too).
118
119
  requires: async (pr, head) => unmetRequires(await checkPrRequires(forge, pr, head, { ignore: [...new Set([productStatusContext(words, "apply"), productStatusContext(words, "plan"), `${productStatusContext(words, "plan")}/`, ...bm.plan])], ...(bm.requires ? { only: bm.requires } : {}) })),
@@ -124,18 +125,23 @@ export async function beforeMergeDeps(forge: PrForge, jobs: CommentJobs, env: No
124
125
  // #4979's reach line says what the change reaches; the locks go up at stage apply, refused while another holds one.
125
126
  ...(line && line.trim()
126
127
  ? {
127
- lock: async (pr: number, head: string, base: string, by: string) => {
128
+ lock: async (pr: number, head: string, base: string, by: string, asked: "apply" | "lock" = "apply") => {
128
129
  const reached = reachedTargets({ forge: forge.kind, pr, head, base, line });
129
130
  if ("error" in reached) throw new Error(reached.error);
130
- if ("moved" in reached) return { ok: false as const, text: `${name(pr)} moved while this comment was read, so nothing is ${words.verbs.apply[1]}; comment again once its checks pass` };
131
+ const nothing = asked === "lock" ? "nothing is locked" : `nothing is ${words.verbs.apply[1]}`;
132
+ if ("moved" in reached) return { ok: false as const, text: `${name(pr)} moved while this comment was read, so ${nothing}; comment again once its checks pass` };
131
133
  const isOpen = forge.pullRequestOpen?.bind(forge);
132
- const r = await takeTargetLocks(bm.locks?.gate ?? PR_APPLY_GATE, reached.targets, { pr, by, at: new Date().toISOString(), stage: "apply", head }, { ...(isOpen ? { isOpen } : {}) });
134
+ const r = await takeTargetLocks(gate, reached.targets, { pr, by, at: new Date().toISOString(), stage: "apply", head }, { ...(isOpen ? { isOpen } : {}) });
133
135
  if (!r.ok) {
134
136
  const request = forge.kind === "gitlab" ? "merge request" : "pull request";
137
+ // #5061: a lock comment is refused as an apply is, with the holder named.
138
+ if (asked === "lock") return { ok: false as const, text: `${describeHeldTargetLocks(r.held, name)}, so ${name(pr)} takes no lock. It can once that ${request} merges or closes, or someone with write access unlocks it` };
135
139
  return { ok: false as const, text: `${describeHeldTargetLocks(r.held, name)}, so ${name(pr)} is not ${words.verbs.apply[1]}. It ${words.verbs.apply[0]}s once that ${request} merges or closes, or someone with write access unlocks it` };
136
140
  }
137
141
  return { ok: true as const, targets: r.taken };
138
142
  },
143
+ // #5061: `/<product> unlock` releases every lock the pull request holds in the reach line's lock file.
144
+ unlock: async (pr: number) => (await releaseTargetLocks(gate, pr)).released,
139
145
  }
140
146
  : {}),
141
147
  record: (d) => recordBeforeMerge(op, d),
@@ -455,7 +455,8 @@ export function productWavesSpec(spec: OpWavesSpec, wordsIn: CiProductWordsInput
455
455
  export function productPipelineJobs(forge: ForgeKind, env: string, options: ProductPipelineOptions): ProductPipelineJobs {
456
456
  const jobs: CiProductCommand[] = ["plan"];
457
457
  if (options.applyBeforeMerge || options.waves || options.componentWaves) jobs.push("apply");
458
- if (options.locks === "plan") jobs.push("lock", "unlock");
458
+ // #5061: the waves before merge with the reach line lock and unlock on a comment, in the comment job or the note poll.
459
+ if (options.locks === "plan" || (options.wavesBeforeMerge && options.productPlan?.reach)) jobs.push("lock", "unlock");
459
460
  if (options.agent) jobs.push("agent");
460
461
  if (options.commits?.length) jobs.push("commit");
461
462
  // #4654: the action command, answered by the product's own workflow (`actions`) or by the pipeline's action job.
@@ -507,7 +508,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
507
508
  const locks = prCommentLockJobs(forge, { locks: options.locks, words });
508
509
  if (locks.length > 0) out.locks = locks.map((job) => ({ ...job, ...defaultRunner }));
509
510
  // #4979: the product plan's reach says what the lock job locks.
510
- const reachLock = productPlan ? productPlanReachLock(forge, { ...prLoop, plan: productPlan }, words) : undefined;
511
+ // #5061: with the waves before merge the reach line is the comment job's (the note poll's), so it needs no locks: "plan".
512
+ const reachLock = productPlan ? productPlanReachLock(forge, { ...prLoop, plan: productPlan, ...(wavesBeforeMerge ? { beforeMerge: true } : {}) }, words) : undefined;
511
513
  if (reachLock) out.reachLock = reachLock;
512
514
  const action = prActionJob(forge, prLoop);
513
515
  if (action) out.action = { ...action, ...(prLoopRunner(options, "apply") !== undefined ? { runner: prLoopRunner(options, "apply")! } : {}) };
@@ -441,17 +441,24 @@ export interface ProductPlanReachLock {
441
441
  * --reach` through the words' bin, with the reach line as
442
442
  * {@link LOCK_REACH_ENV}. On GitHub and Forgejo it locks the pull request of
443
443
  * the event; on GitLab every open merge request into the branch.
444
+ *
445
+ * With `beforeMerge` (#5061, the product pipeline's `wavesBeforeMerge`) the
446
+ * reach line is also what the comment job (the note poll on GitLab) locks
447
+ * when it decides an apply or answers `/<product> lock`, so without
448
+ * `locks: "plan"` the reach is checked and no lock job is written.
444
449
  */
445
- export function productPlanReachLock(forge: ForgeKind, loop: Pick<PrLoopPipelineOptions, "locks" | "runners"> & { plan: Pick<ProductPlanOptions, "reach"> }, words: CiProductWords): ProductPlanReachLock | undefined {
450
+ export function productPlanReachLock(forge: ForgeKind, loop: Pick<PrLoopPipelineOptions, "locks" | "runners"> & { plan: Pick<ProductPlanOptions, "reach">; beforeMerge?: boolean }, words: CiProductWords): ProductPlanReachLock | undefined {
446
451
  const reach = loop.plan.reach;
447
452
  if (!reach) return undefined;
448
- if (loop.locks !== "plan") throw new Error("the product plan's reach says what the lock job locks, and there is none without locks: \"plan\"; set locks: \"plan\", or drop reach");
453
+ if (loop.locks !== "plan" && !loop.beforeMerge) throw new Error("the product plan's reach says what the lock job locks, and there is none without locks: \"plan\"; set locks: \"plan\", or drop reach");
449
454
  if (!reach.command.trim()) throw new Error("the product plan's reach.command is empty; give the line that prints the targets a change reaches");
450
455
  if (/[\r\n]/.test(reach.command)) throw new Error("the product plan's reach.command is one shell line");
451
456
  if (reach.gate !== undefined) {
452
457
  // The lock file's name, as ../lifecycle/target-lock.ts takes it.
453
458
  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(reach.gate)) throw new Error(`the product plan's reach.gate ${JSON.stringify(reach.gate)} is not a lock file name: letters, digits, '.', '_' and '-', starting with a letter or digit`);
454
459
  }
460
+ // #5061: the waves before merge lock by the reach line themselves; there is no plan lock job to write.
461
+ if (loop.locks !== "plan") return undefined;
455
462
  const gate = reach.gate !== undefined ? ["--gate", reach.gate] : [];
456
463
  const github = forge !== "gitlab";
457
464
  const line = github
@@ -62,9 +62,9 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
62
62
  { name: "OP_WAVES_RESUME_NAMES_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves resume keeps a product's names (#5034): `resumeWorkflowFile` names the GitHub and Forgejo resume workflow's file (such as terragucci's `terragucci-resume.yml`; default `<spec>-resume.yml`, refused on GitLab and when it is the waves' own file), and `jobNames` is called for the resume job with the role `resume` (GitHub and Forgejo `resume`, GitLab `<spec>-resume` by default).", issue: "#5034", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
63
63
  { name: "WAVES_BEFORE_MERGE_ENVIRONMENT_FLOOR", version: "0.124.93", gates: "The first chant whose Op waves before merge take `beforeMerge.environment` (#5037): the forge environment the job after the last wave runs in, so a merge token scoped to it reaches that job alone (GitLab `environment: { name, action: access }`, GitHub `environment: <name>`; Forgejo refuses it), with the product pipeline's `wavesBeforeMerge.environment` carried through `waves.pipeline`.", issue: "#5037", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
64
64
  { name: "NOTE_POLL_NAMES_FLOOR", version: "0.124.93", gates: "The first chant whose GitLab note poll keeps a product's names (#5038): the product pipeline's `noteCommandsJob` gives its job's name (default `note-commands`), its stage (default the job's name) and the variable and value a pipeline schedule starts it with (default `CHANT_NOTE_COMMANDS=1`), such as terragucci's `comments` job and `TERRAGUCCI_SCHEDULE=comments`, rendered in the job, its stage, its rule, its resource group and the workflow's rules.", issue: "#5038", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
65
- { name: "OP_WAVES_COMMAND_TOKEN_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators take `commandToken` (#5044), GitHub and Forgejo: the jobs that run only the default branch's code (a push's wave, deciding, share and job group jobs; a split wave's gate and record jobs) hand their command step the job's token as `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and a failed apply's triage and a product's hooks can read the forge, and ask for `permissions` beside chant's own.", issue: "#5044", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
66
- { name: "OP_WAVES_GITLAB_CACHE_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose GitLab Op waves generator takes `cache` (#5045): the `cache:` entry or entries of each job that runs the wave's command (the wave's own, deciding, share and job group jobs, the policy job, a split wave's plan and applying jobs), such as terragucci's Terragrunt sources and providers cache.", issue: "#5045", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
67
- { name: "OP_WAVES_GROUPS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators take `controlGroup` and `resumeGroup` (#5053): the control job's group (GitHub and Forgejo `concurrency` with `cancel-in-progress: false`, GitLab `resource_group`), with `{commit}` standing for the commit it tells the control repo about, so a push's run and a resume's run send one dispatch per commit; and the GitLab resume job's `resource_group`.", issue: "#5053", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
65
+ { name: "OP_WAVES_COMMAND_TOKEN_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves generators take `commandToken` (#5044), GitHub and Forgejo: the jobs that run only the default branch's code (a push's wave, deciding, share and job group jobs; a split wave's gate and record jobs) hand their command step the job's token as `GITHUB_TOKEN`, so the spec's `respond` posts a refused wave's diff and a failed apply's triage and a product's hooks can read the forge, and ask for `permissions` beside chant's own.", issue: "#5044", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
66
+ { name: "OP_WAVES_GITLAB_CACHE_FLOOR", version: "0.124.94", gates: "The first chant whose GitLab Op waves generator takes `cache` (#5045): the `cache:` entry or entries of each job that runs the wave's command (the wave's own, deciding, share and job group jobs, the policy job, a split wave's plan and applying jobs), such as terragucci's Terragrunt sources and providers cache.", issue: "#5045", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
67
+ { name: "OP_WAVES_GROUPS_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves generators take `controlGroup` and `resumeGroup` (#5053): the control job's group (GitHub and Forgejo `concurrency` with `cancel-in-progress: false`, GitLab `resource_group`), with `{commit}` standing for the commit it tells the control repo about, so a push's run and a resume's run send one dispatch per commit; and the GitLab resume job's `resource_group`.", issue: "#5053", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
68
68
  { name: "PRODUCT_ACTIONS_FLOOR", version: "0.124.58", gates: "Day-2 actions in the product pipeline (#4654): the `action` comment command counted as answered by the product's own workflow (`productPipelineJobs(forge, env, { words, actions: true })`), or the pipeline's own action job (`actionJob`, `build --pr-loop --action-job`), which answers the comment and a dispatch with a member and an action input, and runs the product's action verb with `--from-event`.", issue: "#4654", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
69
69
  { name: "APPROVAL_STATUS_FLOOR", version: "0.124.56", gates: "The approval status before merge (#4630): under a `pr-review` wave, the op waves generators add a job that posts `<product>/approval` on each open pull request's head.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
70
70
  { name: "APPROVAL_STATUS_PULL_REQUEST_FLOOR", version: "0.124.56", gates: "The approval status for `pull-request` waves too (#4630, 2026-10-28 ruling): the generators add the record-plans and approval-status jobs for a spec whose waves take the pull request's own approval, and the status reads that approval's coverage of each wave's change set.", issue: "#4630", file: "ci-product.ts", modules: ["@intentius/chant/ci-product"] },
@@ -237,10 +237,12 @@ export const FLOOR_ROWS: readonly FloorRow[] = [
237
237
  { name: "BEFORE_MERGE_REF_GATE_FLOOR", version: "0.124.89", gates: "The first chant whose `chant components pr-apply --before-merge` waits for the ref gate's status: the status the policy at base sets for the target branch is passed as `require` to the `checks` require (#4966).", issue: "#4966", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
238
238
  { name: "TARGET_SIGNED_CHECKS_FLOOR", version: "0.124.89", gates: "The first chant whose product plan with `targets` and `evidence` signs each target's plan job as `plan:<target>` and `policy:<target>` (`ci evidence sign --member <target>`, `targetEvidenceCheck`, `productPlanEvidenceChecks`), and whose `refGateInitPlan` takes `targets` and names those checks in the `refs` rule (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/ref-gate-init","@intentius/chant/release-floors"] },
239
239
  { name: "RUNTIME_WAVES_SPEC_FLOOR", version: "0.124.89", gates: "The first chant whose Op waves generators take `renderSpec` (the wave jobs run `chant run wave --render-spec`, and `CHANT_WAVES_SPEC_COMMAND` names the product command that prints the spec at the commit in `CHANT_WAVES_SPEC_AT`), so a product whose spec is built from its config at base renders its wave jobs, policy step, evidence job and cloud trade through chant (#4982).", issue: "#4982", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
240
- { name: "RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves `renderSpec` takes `runsAtHead` (the jobs carry `CHANT_WAVES_SPEC_RUNS=head`): the job's own spec is rendered at the applied commit, with `CHANT_WAVES_SPEC_BASE` set to the base commit beside `CHANT_WAVES_SPEC_AT`, so the runs a change adds apply at its merge, while the gate policy, holds, hooks and evidence rules still come from the render at base (#5046).", issue: "#5046", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
241
- { name: "OP_WAVES_REMAINDER_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves keep the record of an apply under an approval themselves (#5047): with `approvals.spend`, `approvals.remainder` writes each change the approved plans make, the commit and the run on the applied line (a split wave's gate job writes it), the job that applies the whole wave or the record job writes how the apply ended, and a wave run again at that commit applies the rest under the same approval when its plans make only changes the stopped apply did not finish; a wave that plans no change closes a stopped apply, and `approvals.spendStanding` spends an approval of the digest a wave its gate let through applies.", issue: "#5047", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
242
- { name: "OP_WAVES_SPLIT_RESUME_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `chant run resume` starts a killed split apply again on GitLab and Forgejo (#5052): under `approvals.remainder` the gate job's applied line names its run there too, GitLab's with the wave's applying and record jobs by name (`retry`), which the resume retries, and Forgejo's with the run's dispatch inputs (`inputs`), which the resume dispatches with, so the new run applies the rest at the same decided head or commit.", issue: "#5052", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-split-resume","@intentius/chant/release-floors"] },
243
- { name: "OP_WAVES_REMAINDER_PARITY_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose `approvals.remainder` resumes the waves terragucci's own records resume (#5056): the terraform step gives a live choudoufu root's plan (`live-plan-set`) its `resourceDigests`, so its applied line names the changes, and the cover leaves out the cost member `(monthly cost)`, whose digest follows from the plans, on both sides.", issue: "#5056", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
240
+ { name: "RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves `renderSpec` takes `runsAtHead` (the jobs carry `CHANT_WAVES_SPEC_RUNS=head`): the job's own spec is rendered at the applied commit, with `CHANT_WAVES_SPEC_BASE` set to the base commit beside `CHANT_WAVES_SPEC_AT`, so the runs a change adds apply at its merge, while the gate policy, holds, hooks and evidence rules still come from the render at base (#5046).", issue: "#5046", file: "release-floors.ts", modules: ["@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-render-spec","@intentius/chant/release-floors"] },
241
+ { name: "OP_WAVES_REMAINDER_FLOOR", version: "0.124.94", gates: "The first chant whose Op waves keep the record of an apply under an approval themselves (#5047): with `approvals.spend`, `approvals.remainder` writes each change the approved plans make, the commit and the run on the applied line (a split wave's gate job writes it), the job that applies the whole wave or the record job writes how the apply ended, and a wave run again at that commit applies the rest under the same approval when its plans make only changes the stopped apply did not finish; a wave that plans no change closes a stopped apply, and `approvals.spendStanding` spends an approval of the digest a wave its gate let through applies.", issue: "#5047", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op","@intentius/chant/op/index","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
242
+ { name: "OP_WAVES_SPLIT_RESUME_FLOOR", version: "0.124.94", gates: "The first chant whose `chant run resume` starts a killed split apply again on GitLab and Forgejo (#5052): under `approvals.remainder` the gate job's applied line names its run there too, GitLab's with the wave's applying and record jobs by name (`retry`), which the resume retries, and Forgejo's with the run's dispatch inputs (`inputs`), which the resume dispatches with, so the new run applies the rest at the same decided head or commit.", issue: "#5052", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-split-resume","@intentius/chant/release-floors"] },
243
+ { name: "OP_WAVES_REMAINDER_PARITY_FLOOR", version: "0.124.94", gates: "The first chant whose `approvals.remainder` resumes the waves terragucci's own records resume (#5056): the terraform step gives a live choudoufu root's plan (`live-plan-set`) its `resourceDigests`, so its applied line names the changes, and the cover leaves out the cost member `(monthly cost)`, whose digest follows from the plans, on both sides.", issue: "#5056", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/op/op-waves-remainder","@intentius/chant/release-floors"] },
244
+ { name: "OP_WAVES_CONTROL_BEFORE_MERGE_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose Op waves generators, in a product's workflow (`runIf`) with `beforeMerge` and a spec `control`, run the control job on the default branch's push, outside the product's `runIf` and after its `firstWaveNeeds` jobs, and tell the control repo the waves applied at the pushed commit without adding up outcomes, on GitHub, Forgejo and GitLab (#5060).", issue: "#5060", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
245
+ { name: "WAVES_BEFORE_MERGE_LOCKS_FLOOR", version: NEXT_RELEASE, gates: "The first chant whose waves before merge lock and unlock on a comment by the product plan's reach line (#5061): with `wavesBeforeMerge` and `productPlan.reach`, and no `locks: \"plan\"`, the comment job (GitHub, Forgejo) and the note poll (GitLab, `chantNoteRuns`) answer `/<product> lock` on an open pull request by taking the locks of what the reach line prints at stage `apply` in `_locks/<reach.gate>.json` without applying (`decideLocksBeforeMerge`), refused with the holder named, and `/<product> unlock` by releasing the pull request's locks; and the product plan takes `reach` without `locks: \"plan\"` under `wavesBeforeMerge`, writing no reach lock job.", issue: "#5061", file: "release-floors.ts", modules: ["@intentius/chant/ci-product","@intentius/chant/release-floors"] },
244
246
  { name: "GITLAB_WAVE_EVIDENCE_RETRY_FLOOR", version: "0.124.89", gates: "The first chant whose `chant run resume` (`resumeGateRun`) on GitLab retries a wave job's `<wave job>-evidence` with the wave job when the evidence job already ran, and whose `ci evidence sign --from-job` waits for a job it reads to finish, so a resumed wave's evidence job signs from the new try (#4978).", issue: "#4978", file: "release-floors.ts", modules: ["@intentius/chant/ci-evidence-jobs","@intentius/chant/release-floors"] },
245
247
  { name: "TERRAFORM_COMMAND_TRACE_FLOOR", version: "0.124.91", gates: "The first chant whose terraform lexicon's engine runs carry what a product's own command tracing read: `runBinary` and the engine runner's `exec` and `execSync` answer stderr apart (`Ran.stderr`) and a spawn failure's message (`Ran.error`), a hook's `after` gets a binary that could not be started as a null code with `error`, `commandTrace` ends that span with the message, and `composeCommandHooks` runs a product's own hook and `commandTrace` as one `onCommand` (#5007).", issue: "#5007", file: "release-floors.ts", modules: ["@intentius/chant/release-floors"] },
246
248
  { name: "RUN_EVENT_FLOOR", version: "0.124.28", gates: "The first chant that writes contract version 1 of the run-event stream.", file: "run-event.ts", modules: ["@intentius/chant","@intentius/chant/index","@intentius/chant/run-event"] },
@@ -84,8 +84,15 @@ export interface DecideBeforeMergeInput {
84
84
  /** Git in the job's checkout of the default branch. */
85
85
  git: ReachRun;
86
86
  cwd?: string;
87
- /** Take the locks of what the change reaches at stage apply, for `by`; a refusal is the reply. Absent: the pipeline has no reach line, so nothing is locked. */
88
- lock?(pr: number, head: string, base: string, by: string): Promise<{ ok: true; targets: string[] } | { ok: false; text: string }>;
87
+ /**
88
+ * Take the locks of what the change reaches at stage apply, for `by`; a
89
+ * refusal is the reply, worded for an apply, or for `/<product> lock` when
90
+ * `asked` is `lock` (#5061). Absent: the pipeline has no reach line, so
91
+ * nothing is locked.
92
+ */
93
+ lock?(pr: number, head: string, base: string, by: string, asked?: "apply" | "lock"): Promise<{ ok: true; targets: string[] } | { ok: false; text: string }>;
94
+ /** With `lock` (#5061): release every lock pull request `pr` holds in the reach line's lock file, answering the targets released. Not read by the apply's decision. */
95
+ unlock?(pr: number): Promise<string[]>;
89
96
  /** Write the decision on chant/lifecycle. */
90
97
  record(d: BeforeMergeDecision): Promise<BeforeMergeRecord>;
91
98
  /** Write the head's wave stop, or clear it (null). */
@@ -190,3 +197,68 @@ export async function decideWavesBeforeMerge(i: DecideBeforeMergeInput): Promise
190
197
  const link = started.url ? ` (${started.url})` : "";
191
198
  return { kind: "ran", text: `started the waves of ${i.op}${link} on ${at}'s head ${short(head)}${through} for ${i.user}${locks}; each wave's gate decides, and the run says when the head applied`, ...(started.url ? { url: started.url } : {}) };
192
199
  }
200
+
201
+ /** What {@link decideLocksBeforeMerge} takes (#5061): the comment, and the lock and unlock of the reach line. */
202
+ export interface LocksBeforeMergeInput {
203
+ forge: ForgeKind;
204
+ pr: PullRequestDetail;
205
+ user: string;
206
+ /** The default branch. */
207
+ base: string;
208
+ kind: "lock" | "unlock";
209
+ words: CiProductWords;
210
+ git: ReachRun;
211
+ cwd?: string;
212
+ lock: NonNullable<DecideBeforeMergeInput["lock"]>;
213
+ unlock: NonNullable<DecideBeforeMergeInput["unlock"]>;
214
+ }
215
+
216
+ /**
217
+ * `/<product> lock` and `/<product> unlock` on a pull request whose waves
218
+ * run before merge with the product plan's reach line and no plan locks
219
+ * (#5061), moved from terragucci's own comment job. `lock` takes the locks
220
+ * of what the reach line prints at stage apply, as an apply would, without
221
+ * applying; `unlock` releases every lock the pull request holds. The reach
222
+ * line runs in the job's checkout of the default branch, so none of the
223
+ * change's code runs.
224
+ */
225
+ export async function decideLocksBeforeMerge(i: LocksBeforeMergeInput): Promise<{ kind: "reply"; text: string } | { kind: "fail"; reason: string }> {
226
+ const t = commentTerms(i.forge);
227
+ const at = t.at(i.pr.number);
228
+ const typed = (kind: "lock" | "unlock") => `/${i.words.product} ${Object.entries(i.words.commands).find(([, c]) => c === kind)?.[0] ?? kind}`;
229
+ const reply = (text: string) => ({ kind: "reply" as const, text });
230
+ const fail = (reason: string) => ({ kind: "fail" as const, reason });
231
+ const list = (xs: readonly string[]) => xs.map((x) => `\`${x}\``).join(", ");
232
+
233
+ if (!i.pr.sameRepo) return reply(forkReply(i.words, i.forge));
234
+ if (i.kind === "unlock") {
235
+ let released: string[];
236
+ try {
237
+ released = await i.unlock(i.pr.number);
238
+ } catch (e) {
239
+ return fail(`could not release the locks of ${at} (${message(e)})`);
240
+ }
241
+ return reply(released.length > 0 ? `released ${list(released)}, which ${at} held, for ${i.user}` : `${at} holds no lock, so there is nothing to unlock`);
242
+ }
243
+ if (i.pr.state !== "open") return reply(`${at} is not open, so it takes no lock`);
244
+ if (i.pr.base !== undefined && i.pr.base !== i.base) return reply(`${at} targets ${i.pr.base}, not the default branch ${i.base}, so it takes no lock`);
245
+ const head = i.pr.headSha;
246
+ if (!head || !SHA.test(head)) return fail(`${at} names no head commit`);
247
+ if (!BRANCH.test(i.base) || i.base.split("/").some((s) => s === ".." || s === "")) return fail(`the default branch ${JSON.stringify(i.base)} is not a branch name this job passes on`);
248
+ // The default branch's commit the change is measured from; the reach line fetches the head itself.
249
+ const baseRef = `refs/remotes/origin/${i.base}`;
250
+ const run = (args: string[]) => i.git(["git", ...args], { ...(i.cwd ? { cwd: i.cwd } : {}) });
251
+ const fetched = run(["fetch", "-q", "--no-tags", "origin", `+refs/heads/${i.base}:${baseRef}`]);
252
+ if (fetched.status !== 0) return fail(`could not fetch ${i.base} (${fetched.stderr.trim() || `git exited ${fetched.status}`})`);
253
+ const baseSha = run(["rev-parse", baseRef]).stdout.trim();
254
+ if (!SHA.test(baseSha)) return fail(`could not read the commit of ${i.base}`);
255
+ let l;
256
+ try {
257
+ l = await i.lock(i.pr.number, head, baseSha, i.user, "lock");
258
+ } catch (e) {
259
+ return fail(`could not take the locks of ${at} (${message(e)})`);
260
+ }
261
+ if (!l.ok) return reply(l.text);
262
+ if (l.targets.length === 0) return reply(`${at} reaches nothing at ${short(head)}, so it takes no lock`);
263
+ return reply(`locked ${list(l.targets)} for ${at} at ${short(head)} for ${i.user}, and nothing is ${i.words.verbs.apply[1]}; the locks hold until it merges or closes, or \`${typed("unlock")}\` releases them`);
264
+ }
@@ -21,7 +21,6 @@ import { opWaveRunRecordFileName } from "./op-waves-split";
21
21
  import { memoryGateLedgerPort } from "./gate";
22
22
  import { CapabilityRegistry, type Capability } from "../components/capability";
23
23
  import { CHANT_EXIT } from "../exit-codes";
24
- import { NEXT_RELEASE } from "../release-floors";
25
24
  import {
26
25
  OP_WAVES_REMAINDER_FLOOR,
27
26
  OP_WAVES_REMAINDER_PARITY_FLOOR,
@@ -171,7 +170,7 @@ describe("the stopped-apply record (#5047)", () => {
171
170
  expect(opWaveStoppedApply([first, line("2026-11-04T00:00:00Z", "d".repeat(40), approved)], [], "g", HEAD)).toBeUndefined();
172
171
  expect(opWaveUnfinishedApply([first], [], "g")).toBe(first);
173
172
  expect(opWaveUnfinishedApply([first], [fin(first, "failed")], "g")).toBeUndefined();
174
- expect(OP_WAVES_REMAINDER_FLOOR).toBe(NEXT_RELEASE);
173
+ expect(OP_WAVES_REMAINDER_FLOOR).toBe("0.124.94");
175
174
  });
176
175
 
177
176
  test("#5056: the cost member's digest follows from the plans, so the rest covers it moved; any other extra still has to match", () => {
@@ -184,7 +183,7 @@ describe("the stopped-apply record (#5047)", () => {
184
183
  // A change is still compared, and another extra still has to be the approved one.
185
184
  expect(opWaveCoverRemainder(approved, [{ ...approved[1]!, digest: "9" }], { now: [cost("sha256:less")], approved: [cost("sha256:all")] })).toMatchObject({ covered: false });
186
185
  expect(opWaveCoverRemainder(approved, [approved[1]!], { now: [cost("sha256:less"), { member: "migrate:m1", planDigest: "m" }], approved: [cost("sha256:all")] })).toMatchObject({ covered: false, why: "migrate:m1 is not as the approved set held it" });
187
- expect(OP_WAVES_REMAINDER_PARITY_FLOOR).toBe(NEXT_RELEASE);
186
+ expect(OP_WAVES_REMAINDER_PARITY_FLOOR).toBe("0.124.94");
188
187
  });
189
188
 
190
189
  test("the spec takes approvals.remainder and approvals.spendStanding beside approvals.spend alone", () => {
@@ -28,7 +28,6 @@ import {
28
28
  RUNTIME_WAVES_SPEC_FLOOR,
29
29
  RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR,
30
30
  } from "./op-waves-render-spec";
31
- import { NEXT_RELEASE } from "../release-floors";
32
31
  import type { OpWavesSpec } from "./op-waves";
33
32
  import { parseArgs } from "../cli/parse-args";
34
33
  import { runOpWaveCommand } from "../cli/handlers/run-wave";
@@ -219,7 +218,7 @@ describe("a waves spec the job renders at run time (#4982)", () => {
219
218
  expect(() => opWavesSpecRunsAtHead({ [OP_WAVES_SPEC_RUNS_ENV]: "base" })).toThrow(/CHANT_WAVES_SPEC_RUNS is head or unset/);
220
219
  expect(opWavesRenderSpecEnv({ command: ["terragucci", "waves-spec"], runsAtHead: true })).toEqual({ CHANT_WAVES_SPEC_COMMAND: '["terragucci","waves-spec"]', CHANT_WAVES_SPEC_RUNS: "head" });
221
220
  expect(opWavesRenderSpecEnv({ command: ["terragucci", "waves-spec"], runsAtHead: false })).toEqual({ CHANT_WAVES_SPEC_COMMAND: '["terragucci","waves-spec"]' });
222
- expect(RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR).toBe(NEXT_RELEASE);
221
+ expect(RUNTIME_WAVES_SPEC_RUNS_AT_HEAD_FLOOR).toBe("0.124.94");
223
222
  });
224
223
 
225
224
  test("chant run wave --render-spec with CHANT_WAVES_SPEC_RUNS=head writes the spec rendered at HEAD (#5046)", async () => {
@@ -7,7 +7,6 @@
7
7
  import { describe, expect, test } from "vitest";
8
8
  import type { ForgeFetch } from "../pr-forge";
9
9
  import { resumeGateRun, type GateRunLocator } from "../gate-resume-run";
10
- import { NEXT_RELEASE } from "../release-floors";
11
10
  import { OP_WAVES_RESUME_ENV, OP_WAVES_SPLIT_RESUME_FLOOR, opWaveSplitResumeEnv, opWaveSplitResumeLocator, parseOpWaveSplitResume } from "./op-waves-split-resume";
12
11
 
13
12
  function fakeForge(routes: Record<string, unknown>) {
@@ -42,8 +41,8 @@ const FORGEJO_ENV = {
42
41
  };
43
42
 
44
43
  describe("the gate job's resume target (#5052)", () => {
45
- test("the floor is NEXT_RELEASE", () => {
46
- expect(OP_WAVES_SPLIT_RESUME_FLOOR).toBe(NEXT_RELEASE);
44
+ test("the floor is the release that shipped it", () => {
45
+ expect(OP_WAVES_SPLIT_RESUME_FLOOR).toBe("0.124.94");
47
46
  });
48
47
 
49
48
  test("GitLab: the wave's applying and record jobs; Forgejo: the product's input names; GitHub and other jobs: nothing", () => {