@intentius/chant 0.124.56 → 0.124.58

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 (199) hide show
  1. package/dist/ci-audit/index.d.ts.map +1 -1
  2. package/dist/ci-audit/index.js +1 -2
  3. package/dist/ci-product-words.d.ts +47 -2
  4. package/dist/ci-product-words.d.ts.map +1 -1
  5. package/dist/ci-product-words.js +59 -1
  6. package/dist/ci-product.d.ts +26 -2
  7. package/dist/ci-product.d.ts.map +1 -1
  8. package/dist/ci-product.js +30 -7
  9. package/dist/cli/commands/init.d.ts +2 -0
  10. package/dist/cli/commands/init.d.ts.map +1 -1
  11. package/dist/cli/commands/init.js +1 -1
  12. package/dist/cli/handlers/build.d.ts.map +1 -1
  13. package/dist/cli/handlers/build.js +5 -1
  14. package/dist/cli/handlers/init.d.ts.map +1 -1
  15. package/dist/cli/handlers/init.js +16 -0
  16. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  17. package/dist/cli/handlers/lifecycle.js +14 -0
  18. package/dist/cli/handlers/pr.d.ts.map +1 -1
  19. package/dist/cli/handlers/pr.js +90 -35
  20. package/dist/cli/handlers/serve.d.ts.map +1 -1
  21. package/dist/cli/handlers/serve.js +9 -0
  22. package/dist/cli/main.d.ts.map +1 -1
  23. package/dist/cli/main.js +6 -2
  24. package/dist/cli/mcp/product-tools.d.ts +40 -7
  25. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  26. package/dist/cli/mcp/product-tools.js +59 -15
  27. package/dist/cli/mcp/read-only.d.ts +2 -1
  28. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  29. package/dist/cli/mcp/read-only.js +2 -1
  30. package/dist/cli/mcp/server.d.ts +11 -0
  31. package/dist/cli/mcp/server.d.ts.map +1 -1
  32. package/dist/cli/mcp/server.js +15 -3
  33. package/dist/cli/mcp-config.d.ts +4 -1
  34. package/dist/cli/mcp-config.d.ts.map +1 -1
  35. package/dist/cli/mcp-config.js +6 -2
  36. package/dist/cli/parse-args.d.ts.map +1 -1
  37. package/dist/cli/parse-args.js +9 -0
  38. package/dist/cli/registry.d.ts +8 -0
  39. package/dist/cli/registry.d.ts.map +1 -1
  40. package/dist/components/auto-release.d.ts +5 -2
  41. package/dist/components/auto-release.d.ts.map +1 -1
  42. package/dist/components/auto-release.js +9 -4
  43. package/dist/components/capability.d.ts +10 -0
  44. package/dist/components/capability.d.ts.map +1 -1
  45. package/dist/components/deploy-units.d.ts +12 -0
  46. package/dist/components/deploy-units.d.ts.map +1 -1
  47. package/dist/components/deploy-units.js +20 -1
  48. package/dist/components/pr-pipeline.d.ts +64 -2
  49. package/dist/components/pr-pipeline.d.ts.map +1 -1
  50. package/dist/components/pr-pipeline.js +66 -5
  51. package/dist/components/product-pipeline.d.ts +18 -1
  52. package/dist/components/product-pipeline.d.ts.map +1 -1
  53. package/dist/components/product-pipeline.js +8 -2
  54. package/dist/components/row-lease.d.ts +22 -1
  55. package/dist/components/row-lease.d.ts.map +1 -1
  56. package/dist/components/row-lease.js +32 -6
  57. package/dist/e2e-harness/driver.d.ts.map +1 -1
  58. package/dist/e2e-harness/driver.js +97 -0
  59. package/dist/e2e-harness/forgejo.d.ts +5 -1
  60. package/dist/e2e-harness/forgejo.d.ts.map +1 -1
  61. package/dist/e2e-harness/forgejo.js +35 -0
  62. package/dist/e2e-harness/index.d.ts +7 -0
  63. package/dist/e2e-harness/index.d.ts.map +1 -1
  64. package/dist/e2e-harness/index.js +11 -2
  65. package/dist/e2e-harness/ports.d.ts +31 -0
  66. package/dist/e2e-harness/ports.d.ts.map +1 -1
  67. package/dist/e2e-harness/scenario.d.ts.map +1 -1
  68. package/dist/e2e-harness/scenario.js +9 -5
  69. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  70. package/dist/e2e-harness/schemas/index.d.ts +22 -1
  71. package/dist/e2e-harness/schemas/index.d.ts.map +1 -1
  72. package/dist/e2e-harness/schemas/index.js +1 -1
  73. package/dist/e2e-harness/steps.d.ts.map +1 -1
  74. package/dist/e2e-harness/steps.js +4 -0
  75. package/dist/lexicon.d.ts +9 -0
  76. package/dist/lexicon.d.ts.map +1 -1
  77. package/dist/lifecycle/git.d.ts +39 -3
  78. package/dist/lifecycle/git.d.ts.map +1 -1
  79. package/dist/lifecycle/git.js +223 -15
  80. package/dist/lifecycle/lock-rows.d.ts +23 -0
  81. package/dist/lifecycle/lock-rows.d.ts.map +1 -1
  82. package/dist/lifecycle/lock-rows.js +47 -8
  83. package/dist/lifecycle/resource-lock.d.ts +70 -0
  84. package/dist/lifecycle/resource-lock.d.ts.map +1 -1
  85. package/dist/lifecycle/resource-lock.js +241 -5
  86. package/dist/mcp/types.d.ts +9 -0
  87. package/dist/mcp/types.d.ts.map +1 -1
  88. package/dist/op/gate.js +21 -4
  89. package/dist/op/op-waves-release-port.js +1 -1
  90. package/dist/op/op-waves-release.d.ts +2 -1
  91. package/dist/op/op-waves-release.d.ts.map +1 -1
  92. package/dist/op/op-waves-run.d.ts +8 -0
  93. package/dist/op/op-waves-run.d.ts.map +1 -1
  94. package/dist/op/op-waves-run.js +101 -29
  95. package/dist/op/op-waves.d.ts +18 -0
  96. package/dist/op/op-waves.d.ts.map +1 -1
  97. package/dist/op/op-waves.js +16 -0
  98. package/dist/pr-loop.d.ts.map +1 -1
  99. package/dist/pr-loop.js +1 -2
  100. package/dist/release-floors.d.ts +1 -1
  101. package/dist/release-floors.js +1 -1
  102. package/dist/template-request/index.d.ts +9 -0
  103. package/dist/template-request/index.d.ts.map +1 -0
  104. package/dist/template-request/index.js +8 -0
  105. package/dist/template-request/request-body.d.ts +21 -0
  106. package/dist/template-request/request-body.d.ts.map +1 -0
  107. package/dist/template-request/request-body.js +86 -0
  108. package/dist/template-request/template-request.d.ts +100 -0
  109. package/dist/template-request/template-request.d.ts.map +1 -0
  110. package/dist/template-request/template-request.js +150 -0
  111. package/dist/template-request/template-request.schema.json +100 -0
  112. package/dist/template-request/template-spec.d.ts +83 -0
  113. package/dist/template-request/template-spec.d.ts.map +1 -0
  114. package/dist/template-request/template-spec.js +146 -0
  115. package/dist/template-request/template.schema.json +114 -0
  116. package/dist/template-request/validate.d.ts +4 -0
  117. package/dist/template-request/validate.d.ts.map +1 -0
  118. package/dist/template-request/validate.js +21 -0
  119. package/dist/wave-runtime.mjs +310 -300
  120. package/package.json +8 -1
  121. package/src/ci-audit/index.ts +1 -2
  122. package/src/ci-product-words.test.ts +23 -0
  123. package/src/ci-product-words.ts +68 -3
  124. package/src/ci-product.ts +36 -6
  125. package/src/cli/commands/init.ts +3 -1
  126. package/src/cli/handlers/build.ts +5 -1
  127. package/src/cli/handlers/init.ts +18 -0
  128. package/src/cli/handlers/lifecycle.ts +13 -0
  129. package/src/cli/handlers/pr-before-merge.test.ts +1 -1
  130. package/src/cli/handlers/pr-deploy-inputs.test.ts +1 -1
  131. package/src/cli/handlers/pr-endpoint.test.ts +1 -1
  132. package/src/cli/handlers/pr-green.test.ts +1 -1
  133. package/src/cli/handlers/pr-plan-comment-targets.test.ts +1 -1
  134. package/src/cli/handlers/pr-plan-flags.test.ts +1 -1
  135. package/src/cli/handlers/pr-plan-targets.test.ts +1 -1
  136. package/src/cli/handlers/pr-record.test.ts +34 -2
  137. package/src/cli/handlers/pr-waves-blocked.test.ts +1 -1
  138. package/src/cli/handlers/pr-waves.test.ts +1 -1
  139. package/src/cli/handlers/pr.test.ts +1 -1
  140. package/src/cli/handlers/pr.ts +86 -31
  141. package/src/cli/handlers/serve.ts +9 -0
  142. package/src/cli/main.ts +6 -2
  143. package/src/cli/mcp/product-tools.test.ts +57 -1
  144. package/src/cli/mcp/product-tools.ts +67 -15
  145. package/src/cli/mcp/read-only.ts +2 -1
  146. package/src/cli/mcp/server.ts +20 -5
  147. package/src/cli/mcp-config.test.ts +52 -2
  148. package/src/cli/mcp-config.ts +6 -3
  149. package/src/cli/parse-args.ts +7 -0
  150. package/src/cli/registry.ts +8 -0
  151. package/src/components/auto-release.test.ts +4 -2
  152. package/src/components/auto-release.ts +9 -5
  153. package/src/components/capability.ts +10 -0
  154. package/src/components/deploy-units.test.ts +18 -1
  155. package/src/components/deploy-units.ts +26 -1
  156. package/src/components/pr-pipeline.ts +99 -5
  157. package/src/components/product-actions.test.ts +76 -0
  158. package/src/components/product-pipeline.ts +21 -2
  159. package/src/components/row-lease.test.ts +61 -1
  160. package/src/components/row-lease.ts +48 -7
  161. package/src/e2e-harness/driver.test.ts +163 -0
  162. package/src/e2e-harness/driver.ts +86 -1
  163. package/src/e2e-harness/forgejo.ts +42 -1
  164. package/src/e2e-harness/index.ts +12 -2
  165. package/src/e2e-harness/ports.ts +33 -0
  166. package/src/e2e-harness/scenario.ts +8 -6
  167. package/src/e2e-harness/schemas/README.md +11 -2
  168. package/src/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  169. package/src/e2e-harness/schemas/index.ts +5 -1
  170. package/src/e2e-harness/schemas.test.ts +44 -1
  171. package/src/e2e-harness/steps.ts +4 -0
  172. package/src/lexicon.ts +9 -0
  173. package/src/lifecycle/git.test.ts +155 -0
  174. package/src/lifecycle/git.ts +213 -17
  175. package/src/lifecycle/lock-rows.test.ts +6 -1
  176. package/src/lifecycle/lock-rows.ts +58 -7
  177. package/src/lifecycle/resource-lock-wait.test.ts +292 -0
  178. package/src/lifecycle/resource-lock.ts +261 -7
  179. package/src/mcp/types.ts +9 -0
  180. package/src/op/gate.test.ts +7 -5
  181. package/src/op/gate.ts +20 -4
  182. package/src/op/op-waves-after-plan.test.ts +1 -2
  183. package/src/op/op-waves-ledger-lock.test.ts +208 -0
  184. package/src/op/op-waves-release-port.ts +1 -1
  185. package/src/op/op-waves-release.ts +1 -1
  186. package/src/op/op-waves-run.ts +104 -29
  187. package/src/op/op-waves.ts +18 -0
  188. package/src/pr-loop-bundle.test.ts +0 -2
  189. package/src/pr-loop.ts +1 -2
  190. package/src/release-floors.ts +1 -1
  191. package/src/template-request/__fixtures__/request-body.md +41 -0
  192. package/src/template-request/index.ts +8 -0
  193. package/src/template-request/request-body.ts +91 -0
  194. package/src/template-request/template-request.schema.json +100 -0
  195. package/src/template-request/template-request.test.ts +316 -0
  196. package/src/template-request/template-request.ts +235 -0
  197. package/src/template-request/template-spec.ts +176 -0
  198. package/src/template-request/template.schema.json +114 -0
  199. package/src/template-request/validate.ts +28 -0
@@ -74,7 +74,12 @@ describe("resolvePlannedLock", () => {
74
74
 
75
75
  test("the declared grain wins over the default, and the step's own over both", async () => {
76
76
  expect(await resolvePlannedLock(choudoufu, {}, { member: "net" }, "target")).toEqual({ grain: "target", source: "declared", rows: [] });
77
- expect(await resolvePlannedLock(choudoufu, { lockGrain: "repo" }, { member: "net" }, "resource")).toEqual({ grain: "repo", source: "step", rows: [] });
77
+ expect(await resolvePlannedLock(choudoufu, { lockGrain: "repo" }, { member: "net" }, "resource")).toEqual({
78
+ grain: "repo",
79
+ source: "step",
80
+ rows: [],
81
+ queue: [{ key: "repo", target: "net", address: "the repository" }],
82
+ });
78
83
  });
79
84
 
80
85
  test("resource is refused by name where the lexicon refuses it, and where no hook names rows", async () => {
@@ -6,14 +6,20 @@
6
6
  * `ci.lockGrain` (ruling A) says what one apply holds while it applies, and,
7
7
  * under `ci.locks`, what a pull request's target locks name (ruling D):
8
8
  *
9
- * - `target`: the component, member, root or stack. The apply takes no row
10
- * lease; the engine's own lock keeps one target's applies apart.
9
+ * - `target`: the component, member, root or stack. A lexicon that names
10
+ * the target's row (`targetLockRow`: `stack <project>/<stack>` for stock
11
+ * Pulumi, `root <root>` for Terraform, tofu and Terragrunt) has the apply
12
+ * wait for that row on the ledger, oldest commit first, up to the job's
13
+ * timeout (ruling for ci-products 2026-10-28, "Ledger lock"). Any other
14
+ * lexicon takes no row lease, and the engine's own lock keeps one
15
+ * target's applies apart.
11
16
  * - `resource`: one row per resource the plan changes, from the lexicon's
12
17
  * `lockRows` hook. The apply leases those rows before it applies and lets
13
18
  * go after, and a pull request under `ci.locks` locks the same keys in
14
19
  * place of its component names.
15
- * - `repo`: one apply at a time in the repository, which the pipeline keeps
16
- * (a concurrency group, a resource group, the lock tag on Forgejo).
20
+ * - `repo`: one apply at a time in the repository: the apply waits for the
21
+ * `repo` row, which meets every other row, in the same queue. The waves
22
+ * pipelines carry no concurrency group of their own.
17
23
  *
18
24
  * Absent, each member takes its lexicon's `defaultLockGrain`, else `target`.
19
25
  *
@@ -21,7 +27,10 @@
21
27
  * of cover (ruling C): a `stack <project>/<stack>` row conflicts with every
22
28
  * `urn urn:pulumi:<stack>::<project>::...` row of that stack, which is how a
23
29
  * plunge apply whose components may register children only at apply locks
24
- * the whole stack and still meets a run holding one of its resources.
30
+ * the whole stack and still meets a run holding one of its resources. A
31
+ * waiting grain's rows ({@link PlannedLock.queue}) use the same keys: a stock
32
+ * stack waits on `stack <project>/<stack>`, so a plunge run on that stack's
33
+ * URNs meets it too, and the `repo` row meets every row.
25
34
  */
26
35
  import { parsePulumiUrn } from "../pulumi-urn";
27
36
 
@@ -48,6 +57,13 @@ export interface PlannedLock {
48
57
  source: "step" | "declared" | "lexicon" | "default";
49
58
  /** The rows, sorted by key. Empty on any grain but `resource`. */
50
59
  rows: LockRow[];
60
+ /**
61
+ * The rows the apply waits for on the `target` and `repo` grains (ruling
62
+ * for ci-products 2026-10-28): the target's own row, from the lexicon's
63
+ * `targetLockRow`, or the `repo` row. Absent when the grain is `resource`
64
+ * or the lexicon names no target row.
65
+ */
66
+ queue?: LockRow[];
51
67
  }
52
68
 
53
69
  /** A lexicon refused the grain asked of a member, by name (#4552: `resource` on Terraform, tofu, Terragrunt and stock Pulumi). */
@@ -67,6 +83,19 @@ export function stackRowKey(project: string, stack: string): string {
67
83
  return `stack ${project}/${stack}`;
68
84
  }
69
85
 
86
+ /** The key of the row that stands for a whole Terraform, tofu or Terragrunt root. A choudoufu root keys its resources `root <root> <address>` on the resource grain and never takes this row. */
87
+ export function rootRowKey(root: string): string {
88
+ return `root ${root}`;
89
+ }
90
+
91
+ /** The key of the row a `repo`-grain apply waits for: it meets every other row. */
92
+ export const REPO_ROW_KEY = "repo";
93
+
94
+ /** The row a `repo`-grain apply waits for. */
95
+ export function repoLockRow(target: string): LockRow {
96
+ return { key: REPO_ROW_KEY, target, address: "the repository" };
97
+ }
98
+
70
99
  /** The key of a URN's row. */
71
100
  export function urnRowKey(urn: string): string {
72
101
  return `urn ${urn}`;
@@ -86,7 +115,7 @@ export function lockRowCover(key: string): string | undefined {
86
115
 
87
116
  /** Whether a holder of row `a` keeps row `b` from being taken: the same key, or one covers the other. */
88
117
  export function lockRowsConflict(a: string, b: string): boolean {
89
- return a === b || lockRowCover(a) === b || lockRowCover(b) === a;
118
+ return a === b || a === REPO_ROW_KEY || b === REPO_ROW_KEY || lockRowCover(a) === b || lockRowCover(b) === a;
90
119
  }
91
120
 
92
121
  /** Rows deduplicated by key and sorted, so two takes of the same rows write the same file. */
@@ -102,6 +131,7 @@ export interface LockGrainHooks {
102
131
  defaultLockGrain?(input: never, plan?: never): LockGrain | Promise<LockGrain>;
103
132
  lockGrainRefusal?(input: never, grain: LockGrain, plan?: never): string | undefined | Promise<string | undefined>;
104
133
  lockRows?(input: never, plan: never): LockRow[] | Promise<LockRow[]>;
134
+ targetLockRow?(input: never, plan?: never): LockRow | undefined | Promise<LockRow | undefined>;
105
135
  }
106
136
 
107
137
  /**
@@ -118,11 +148,32 @@ export async function resolvePlannedLock(capability: LockGrainHooks, input: unkn
118
148
  const grain: LockGrain = step ?? declared ?? (capability.defaultLockGrain ? await capability.defaultLockGrain(input as never, plan as never) : "target");
119
149
  const refused = capability.lockGrainRefusal ? await capability.lockGrainRefusal(input as never, grain, plan as never) : undefined;
120
150
  if (refused) throw new LockGrainRefusedError(plan.member, grain, refused);
121
- if (grain !== "resource") return { grain, source, rows: [] };
151
+ if (grain !== "resource") {
152
+ const queue = await queueRowsOf(capability, input, plan.member, grain, plan);
153
+ return { grain, source, rows: [], ...(queue.length > 0 ? { queue } : {}) };
154
+ }
122
155
  if (!capability.lockRows) throw new LockGrainRefusedError(plan.member, grain, `${capability.kind} names no rows for its resources; set ci.lockGrain to target`);
123
156
  return { grain, source, rows: sortedLockRows(await capability.lockRows(input as never, plan as never)) };
124
157
  }
125
158
 
159
+ /**
160
+ * The rows an apply on the `target` or `repo` grain waits for (ruling for
161
+ * ci-products 2026-10-28): the `repo` row, or the target's row from the
162
+ * lexicon's `targetLockRow`. Empty for `resource`, and for a lexicon that
163
+ * names no target row.
164
+ */
165
+ export async function queueRowsOf(capability: LockGrainHooks, input: unknown, member: string, grain: LockGrain, plan?: unknown): Promise<LockRow[]> {
166
+ if (grain === "repo") return [repoLockRow(member)];
167
+ if (grain !== "target" || !capability.targetLockRow) return [];
168
+ const row = await capability.targetLockRow(input as never, plan as never);
169
+ return row ? [row] : [];
170
+ }
171
+
172
+ /** Every row the waiting members of `locks` wait for, deduplicated and sorted. */
173
+ export function queueRowsOfLocks(locks: Readonly<Record<string, PlannedLock>> | undefined): LockRow[] {
174
+ return sortedLockRows(Object.values(locks ?? {}).flatMap((l) => l.queue ?? []));
175
+ }
176
+
126
177
  /**
127
178
  * A member's grain before anything planned (#4594), by the order
128
179
  * {@link resolvePlannedLock} uses: the step input's own `lockGrain`, else the
@@ -0,0 +1,292 @@
1
+ /**
2
+ * The ruling for ci-products (2026-10-28), "Ledger lock": a stock Pulumi
3
+ * stack or a Terraform root waits for its row on chant's ledger, oldest
4
+ * commit first, up to the job's timeout, and plunge stacks on the resource
5
+ * grain lease their resource rows and never wait on another stack.
6
+ *
7
+ * Each test has a bare remote and one clone per writer, as two pushes'
8
+ * wave jobs have on a forge. The waits use a pause the test drives, so the
9
+ * order of reads is fixed and nothing sleeps.
10
+ */
11
+ import { afterAll, describe, expect, test } from "vitest";
12
+ import { execFileSync } from "node:child_process";
13
+ import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
14
+ import { tmpdir } from "node:os";
15
+ import { join } from "node:path";
16
+ import { rootRowKey, stackRowKey, urnRowKey, type LockRow } from "./lock-rows";
17
+ import {
18
+ leaseLockRows,
19
+ lockWaitSeconds,
20
+ DEFAULT_LOCK_WAIT_SECONDS,
21
+ parseLockRows,
22
+ readLockRows,
23
+ renderLockRows,
24
+ waiterBefore,
25
+ withWaiter,
26
+ withRowsTaken,
27
+ type LockRowHolder,
28
+ } from "./resource-lock";
29
+
30
+ const dirs: string[] = [];
31
+ afterAll(() => {
32
+ for (const d of dirs) rmSync(d, { recursive: true, force: true });
33
+ });
34
+
35
+ function tmp(prefix: string): string {
36
+ const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
37
+ dirs.push(d);
38
+ return d;
39
+ }
40
+
41
+ function git(cwd: string, ...args: string[]): string {
42
+ return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
43
+ }
44
+
45
+ /** A bare remote with one commit on main, and `n` clones of it, each a writer. */
46
+ function writers(n: number): { remote: string; clones: string[] } {
47
+ const remote = tmp("chant-lock-wait-remote-");
48
+ git(remote, "init", "-q", "--bare", "-b", "main");
49
+ const seed = tmp("chant-lock-wait-seed-");
50
+ git(seed, "init", "-q", "-b", "main");
51
+ git(seed, "config", "user.email", "seed@chant.dev");
52
+ git(seed, "config", "user.name", "Seed");
53
+ git(seed, "config", "commit.gpgsign", "false");
54
+ writeFileSync(join(seed, "README.md"), "# t\n");
55
+ git(seed, "add", "README.md");
56
+ git(seed, "commit", "-q", "-m", "init");
57
+ git(seed, "remote", "add", "origin", remote);
58
+ git(seed, "push", "-q", "origin", "main");
59
+ const clones: string[] = [];
60
+ for (let i = 0; i < n; i++) {
61
+ const c = tmp(`chant-lock-wait-clone-${i}-`);
62
+ git(c, "clone", "-q", remote, ".");
63
+ git(c, "config", "user.email", `w${i}@chant.dev`);
64
+ git(c, "config", "user.name", `Writer ${i}`);
65
+ git(c, "config", "commit.gpgsign", "false");
66
+ clones.push(c);
67
+ }
68
+ return { remote, clones };
69
+ }
70
+
71
+ const holder = (run: string, sha?: string): LockRowHolder => ({ run, at: new Date().toISOString(), ...(sha ? { sha } : {}) });
72
+ const alive = async () => "alive" as const;
73
+ const stackRow = (stack: string): LockRow => ({ key: stackRowKey("shop", stack), target: `shop/${stack}`, address: `shop/${stack}` });
74
+ const urnRow = (stack: string, name: string): LockRow => {
75
+ const urn = `urn:pulumi:${stack}::shop::aws:sqs/queue:Queue::${name}`;
76
+ return { key: urnRowKey(urn), target: `shop/${stack}`, address: urn };
77
+ };
78
+
79
+ /** A promise and its resolver. */
80
+ function signal(): { promise: Promise<void>; fire: () => void } {
81
+ let fire!: () => void;
82
+ const promise = new Promise<void>((r) => (fire = r));
83
+ return { promise, fire };
84
+ }
85
+
86
+ describe("the queue in the rows file", () => {
87
+ test("a waiter round-trips, and the file leaves `waiting` out when nobody waits", () => {
88
+ const empty = parseLockRows(null);
89
+ expect(renderLockRows(empty)).not.toContain("waiting");
90
+ const queued = withWaiter(empty, { run: "12", at: "2026-10-28T10:00:00.000Z", keys: ["stack shop/staging"], commitAt: "2026-10-28T09:59:00Z" });
91
+ const back = parseLockRows(renderLockRows(queued));
92
+ expect(back.waiting).toEqual({ "12": { run: "12", at: "2026-10-28T10:00:00.000Z", keys: ["stack shop/staging"], commitAt: "2026-10-28T09:59:00Z" } });
93
+ // Taking the rows takes the run out of the queue.
94
+ const took = withRowsTaken(back, ["stack shop/staging"], holder("12"), []);
95
+ expect(took.waiting).toBeUndefined();
96
+ expect(took.rows).toEqual({ "stack shop/staging": "12" });
97
+ });
98
+
99
+ test("the older commit goes first, then the lower run id, then the commit sha; no commit time goes last", () => {
100
+ expect(waiterBefore({ run: "20", commitAt: "2026-10-28T10:00:00Z" }, { run: "9", commitAt: "2026-10-28T10:05:00Z" })).toBe(true);
101
+ expect(waiterBefore({ run: "9", commitAt: "2026-10-28T10:00:00Z" }, { run: "20", commitAt: "2026-10-28T10:00:00Z" })).toBe(true);
102
+ expect(waiterBefore({ run: "20", commitAt: "2026-10-28T10:00:00Z" }, { run: "9", commitAt: "2026-10-28T10:00:00Z" })).toBe(false);
103
+ expect(waiterBefore({ run: "local:a:1", commitAt: "2026-10-28T10:00:00Z" }, { run: "local:b:1", commitAt: "2026-10-28T10:00:00Z" })).toBe(true);
104
+ expect(waiterBefore({ run: "7", commitAt: "2026-10-28T10:00:00Z", sha: "aaa" }, { run: "7", commitAt: "2026-10-28T10:00:00Z", sha: "bbb" })).toBe(true);
105
+ expect(waiterBefore({ run: "1" }, { run: "2", commitAt: "2026-10-28T10:00:00Z" })).toBe(false);
106
+ });
107
+
108
+ test("CHANT_LOCK_WAIT sets the wait; the default sits under a Forgejo runner's three hours", () => {
109
+ expect(lockWaitSeconds({ CHANT_LOCK_WAIT: "600" })).toBe(600);
110
+ expect(lockWaitSeconds({})).toBe(DEFAULT_LOCK_WAIT_SECONDS);
111
+ expect(DEFAULT_LOCK_WAIT_SECONDS).toBeLessThan(3 * 3600);
112
+ });
113
+
114
+ test("a root row is the root's key, apart from a choudoufu root's resource rows", () => {
115
+ expect(rootRowKey("stacks/net")).toBe("root stacks/net");
116
+ });
117
+ });
118
+
119
+ describe("two writers on a bare-remote ledger", () => {
120
+ test("the second writer waits for the stack row the first holds, then takes it once the first lets go", async () => {
121
+ const { remote, clones } = writers(2);
122
+ const [a, b] = clones as [string, string];
123
+ const first = await leaseLockRows("pr-apply", [stackRow("staging")], { cwd: a, alive, holder: holder("101") });
124
+ expect(first.ok).toBe(true);
125
+ if (!first.ok) return;
126
+
127
+ const lines: string[] = [];
128
+ let pauses = 0;
129
+ let queuedOnRemote: unknown;
130
+ const second = await leaseLockRows("pr-apply", [stackRow("staging")], {
131
+ cwd: b,
132
+ alive,
133
+ holder: holder("102"),
134
+ wait: {
135
+ deadline: Date.now() + 60_000,
136
+ pollMs: 0,
137
+ commitAt: "2026-10-28T10:05:00Z",
138
+ log: (l) => lines.push(l),
139
+ sleep: async () => {
140
+ pauses++;
141
+ if (pauses === 1) {
142
+ // While B waits, the remote's file names it in the queue, behind A's hold.
143
+ queuedOnRemote = parseLockRows(git(remote, "show", "chant/lifecycle:_locks/rows/pr-apply.json")).waiting;
144
+ expect(await first.lease.release()).toBe(true);
145
+ }
146
+ },
147
+ },
148
+ });
149
+ expect(second.ok).toBe(true);
150
+ expect(pauses).toBe(1);
151
+ expect(queuedOnRemote).toMatchObject({ "102": { run: "102", keys: ["stack shop/staging"], commitAt: "2026-10-28T10:05:00Z" } });
152
+ expect(lines.join("\n")).toContain("run 101 is applying shop/staging");
153
+ const now = await readLockRows("pr-apply", { cwd: a });
154
+ expect(now.rows).toEqual({ "stack shop/staging": "102" });
155
+ expect(now.waiting).toBeUndefined();
156
+ });
157
+
158
+ test("two plunge stacks on the resource grain lease their URN rows side by side and never wait", async () => {
159
+ const { clones } = writers(2);
160
+ const [a, b] = clones as [string, string];
161
+ // Two pushes on one plunge stack that change disjoint resources (pw-disjoint), and a second stack beside them.
162
+ const events = await leaseLockRows("pr-apply", [urnRow("dev", "events")], { cwd: a, alive, holder: holder("201") });
163
+ const worker = await leaseLockRows("pr-apply", [urnRow("dev", "worker-3"), urnRow("prod-us", "orders")], { cwd: b, alive, holder: holder("202") });
164
+ expect(events.ok).toBe(true);
165
+ expect(worker.ok).toBe(true);
166
+ const now = await readLockRows("pr-apply", { cwd: a });
167
+ expect(Object.values(now.rows).sort()).toEqual(["201", "202", "202"]);
168
+ expect(now.waiting).toBeUndefined();
169
+ // A resource-grain take on a URN another run holds is refused at once, held, with no wait.
170
+ const clash = await leaseLockRows("pr-apply", [urnRow("dev", "events")], { cwd: b, alive, holder: holder("203") });
171
+ expect(clash.ok).toBe(false);
172
+ if (!clash.ok) expect(clash.timedOut).toBeUndefined();
173
+ });
174
+
175
+ test("a wait that reaches the job's deadline fails by name and leaves the queue", async () => {
176
+ const { clones } = writers(2);
177
+ const [a, b] = clones as [string, string];
178
+ const first = await leaseLockRows("pr-apply", [stackRow("prod-eu")], { cwd: a, alive, holder: holder("301") });
179
+ expect(first.ok).toBe(true);
180
+ let clock = 1_000_000;
181
+ let pauses = 0;
182
+ const second = await leaseLockRows("pr-apply", [stackRow("prod-eu")], {
183
+ cwd: b,
184
+ alive,
185
+ holder: holder("302"),
186
+ wait: {
187
+ deadline: clock + 30_000,
188
+ pollMs: 10_000,
189
+ now: () => clock,
190
+ sleep: async (ms) => {
191
+ pauses++;
192
+ clock += ms;
193
+ },
194
+ },
195
+ });
196
+ expect(second.ok).toBe(false);
197
+ if (second.ok) return;
198
+ expect(second.timedOut).toBe(true);
199
+ expect(second.message).toMatch(/^waited 30s for stack shop\/prod-eu of pr-apply and gave up at the job's deadline: run 301 is applying shop\/prod-eu/);
200
+ expect(pauses).toBe(3);
201
+ const now = await readLockRows("pr-apply", { cwd: a });
202
+ expect(now.rows).toEqual({ "stack shop/prod-eu": "301" });
203
+ expect(now.waiting).toBeUndefined();
204
+ });
205
+
206
+ test("of two waiters, the older commit takes the row first, whichever joined the queue first", async () => {
207
+ const { clones } = writers(3);
208
+ const [a, b, c] = clones as [string, string, string];
209
+ const holding = await leaseLockRows("pr-apply", [stackRow("staging")], { cwd: a, alive, holder: holder("401") });
210
+ expect(holding.ok).toBe(true);
211
+ if (!holding.ok) return;
212
+
213
+ const order: string[] = [];
214
+ const cJoined = signal();
215
+ const aReleased = signal();
216
+ const bSawC = signal();
217
+ const cTook = signal();
218
+ const cReleased = signal();
219
+ const bLines: string[] = [];
220
+ let bPauses = 0;
221
+ let cPauses = 0;
222
+ let older: Promise<Awaited<ReturnType<typeof leaseLockRows>>> | undefined;
223
+
224
+ const startOlder = () =>
225
+ leaseLockRows("pr-apply", [stackRow("staging")], {
226
+ cwd: c,
227
+ alive,
228
+ holder: holder("403"),
229
+ wait: {
230
+ deadline: Date.now() + 60_000,
231
+ pollMs: 0,
232
+ commitAt: "2026-10-28T10:00:00Z",
233
+ sleep: async () => {
234
+ cPauses++;
235
+ if (cPauses === 1) {
236
+ cJoined.fire();
237
+ await aReleased.promise;
238
+ // C reads again only once B has read the free row and stayed behind C.
239
+ await bSawC.promise;
240
+ }
241
+ },
242
+ },
243
+ });
244
+
245
+ // B, the newer commit, joins the queue first.
246
+ const newer = leaseLockRows("pr-apply", [stackRow("staging")], {
247
+ cwd: b,
248
+ alive,
249
+ holder: holder("402"),
250
+ wait: {
251
+ deadline: Date.now() + 60_000,
252
+ pollMs: 0,
253
+ commitAt: "2026-10-28T10:05:00Z",
254
+ log: (l) => bLines.push(l),
255
+ sleep: async () => {
256
+ bPauses++;
257
+ if (bPauses === 1) {
258
+ older = startOlder().then((r) => {
259
+ order.push("403");
260
+ cTook.fire();
261
+ return r;
262
+ });
263
+ await cJoined.promise;
264
+ expect(await holding.lease.release()).toBe(true);
265
+ aReleased.fire();
266
+ } else if (bPauses === 2) {
267
+ bSawC.fire();
268
+ await cTook.promise;
269
+ } else if (bPauses === 3) {
270
+ await cReleased.promise;
271
+ }
272
+ },
273
+ },
274
+ }).then((r) => {
275
+ order.push("402");
276
+ return r;
277
+ });
278
+
279
+ await cTook.promise;
280
+ const c1 = await older!;
281
+ expect(c1.ok).toBe(true);
282
+ if (c1.ok) expect(await c1.lease.release()).toBe(true);
283
+ cReleased.fire();
284
+ const b1 = await newer;
285
+ expect(b1.ok).toBe(true);
286
+ expect(order).toEqual(["403", "402"]);
287
+ expect(bLines.join("\n")).toContain("run 403 waits ahead of it with an older commit");
288
+ const now = await readLockRows("pr-apply", { cwd: a });
289
+ expect(now.rows).toEqual({ "stack shop/staging": "402" });
290
+ expect(now.waiting).toBeUndefined();
291
+ });
292
+ });