@intentius/chant 0.124.58 → 0.124.60

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 (91) hide show
  1. package/dist/ci-product.d.ts.map +1 -1
  2. package/dist/ci-product.js +1 -2
  3. package/dist/cli/handlers/lifecycle-drift.d.ts +2 -1
  4. package/dist/cli/handlers/lifecycle-drift.d.ts.map +1 -1
  5. package/dist/cli/handlers/lifecycle-drift.js +4 -2
  6. package/dist/cli/handlers/lock.d.ts.map +1 -1
  7. package/dist/cli/handlers/lock.js +45 -2
  8. package/dist/cli/main.d.ts.map +1 -1
  9. package/dist/cli/main.js +5 -1
  10. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  11. package/dist/cli/mcp/product-tools.js +1 -2
  12. package/dist/cli/parse-args.d.ts.map +1 -1
  13. package/dist/cli/parse-args.js +18 -0
  14. package/dist/cli/registry.d.ts +6 -0
  15. package/dist/cli/registry.d.ts.map +1 -1
  16. package/dist/components/capability.d.ts +11 -0
  17. package/dist/components/capability.d.ts.map +1 -1
  18. package/dist/drift-record.d.ts +5 -0
  19. package/dist/drift-record.d.ts.map +1 -1
  20. package/dist/e2e-harness/index.d.ts.map +1 -1
  21. package/dist/e2e-harness/index.js +1 -2
  22. package/dist/lifecycle/lock-beat.d.ts +27 -0
  23. package/dist/lifecycle/lock-beat.d.ts.map +1 -0
  24. package/dist/lifecycle/lock-beat.js +84 -0
  25. package/dist/lifecycle/resource-lock.d.ts +54 -1
  26. package/dist/lifecycle/resource-lock.d.ts.map +1 -1
  27. package/dist/lifecycle/resource-lock.js +128 -7
  28. package/dist/lifecycle/wave-plans.d.ts +19 -0
  29. package/dist/lifecycle/wave-plans.d.ts.map +1 -1
  30. package/dist/lifecycle/wave-plans.js +25 -1
  31. package/dist/op/activities/activity-contracts.d.ts +4 -4
  32. package/dist/op/gate-review.d.ts +1 -1
  33. package/dist/op/gate-review.d.ts.map +1 -1
  34. package/dist/op/index.d.ts +2 -1
  35. package/dist/op/index.d.ts.map +1 -1
  36. package/dist/op/index.js +2 -1
  37. package/dist/op/op-waves-capability.d.ts +2 -0
  38. package/dist/op/op-waves-capability.d.ts.map +1 -1
  39. package/dist/op/op-waves-capability.js +1 -0
  40. package/dist/op/op-waves-notify.d.ts.map +1 -1
  41. package/dist/op/op-waves-notify.js +11 -0
  42. package/dist/op/op-waves-preview.d.ts +45 -0
  43. package/dist/op/op-waves-preview.d.ts.map +1 -0
  44. package/dist/op/op-waves-preview.js +37 -0
  45. package/dist/op/op-waves-run.d.ts +46 -1
  46. package/dist/op/op-waves-run.d.ts.map +1 -1
  47. package/dist/op/op-waves-run.js +124 -7
  48. package/dist/op/op-waves.d.ts +12 -1
  49. package/dist/op/op-waves.d.ts.map +1 -1
  50. package/dist/op/op-waves.js +9 -2
  51. package/dist/release-floors.d.ts +1 -1
  52. package/dist/release-floors.js +1 -1
  53. package/dist/template-request/template-request.d.ts.map +1 -1
  54. package/dist/template-request/template-request.js +1 -2
  55. package/dist/wave-runtime.mjs +299 -299
  56. package/dist/workspace/drift-cli.d.ts +13 -1
  57. package/dist/workspace/drift-cli.d.ts.map +1 -1
  58. package/dist/workspace/drift-cli.js +19 -3
  59. package/package.json +1 -1
  60. package/src/ci-product.ts +1 -2
  61. package/src/cli/handlers/lifecycle-drift.test.ts +52 -0
  62. package/src/cli/handlers/lifecycle-drift.ts +4 -2
  63. package/src/cli/handlers/lock.ts +41 -2
  64. package/src/cli/main.ts +5 -1
  65. package/src/cli/mcp/product-tools.test.ts +1 -2
  66. package/src/cli/mcp/product-tools.ts +1 -2
  67. package/src/cli/parse-args.ts +12 -0
  68. package/src/cli/registry.ts +6 -0
  69. package/src/components/capability.ts +11 -0
  70. package/src/drift-record.ts +5 -0
  71. package/src/e2e-harness/index.ts +1 -2
  72. package/src/lifecycle/ledger-readers.test.ts +10 -0
  73. package/src/lifecycle/lock-beat.ts +99 -0
  74. package/src/lifecycle/resource-lock-liveness.test.ts +289 -0
  75. package/src/lifecycle/resource-lock.ts +143 -8
  76. package/src/lifecycle/wave-plans.ts +41 -1
  77. package/src/op/gate-review.test.ts +1 -1
  78. package/src/op/gate-review.ts +1 -1
  79. package/src/op/index.ts +2 -0
  80. package/src/op/op-waves-capability.ts +3 -0
  81. package/src/op/op-waves-notify.ts +11 -0
  82. package/src/op/op-waves-preview.test.ts +284 -0
  83. package/src/op/op-waves-preview.ts +70 -0
  84. package/src/op/op-waves-run.ts +166 -8
  85. package/src/op/op-waves.test.ts +11 -1
  86. package/src/op/op-waves.ts +20 -3
  87. package/src/release-floors.ts +1 -1
  88. package/src/template-request/template-request.test.ts +1 -2
  89. package/src/template-request/template-request.ts +1 -2
  90. package/src/workspace/drift-cli.test.ts +35 -1
  91. package/src/workspace/drift-cli.ts +21 -3
@@ -116,6 +116,8 @@ export interface OpWaveStepPlan {
116
116
  /** The capability's member, the key `run` finds its artifact under. */
117
117
  member: string;
118
118
  planDigest: string;
119
+ /** The digest of each resource the plan changes, when the capability gave them (plywood#55). */
120
+ resources?: Record<string, string>;
119
121
  artifact?: unknown;
120
122
  part?: ChangeSetPart;
121
123
  empty: boolean;
@@ -166,6 +168,7 @@ export async function planOpWaveStep(
166
168
  target: run.target,
167
169
  member: planned.member,
168
170
  planDigest: planned.planDigest,
171
+ ...(planned.resourceDigests ? { resources: planned.resourceDigests } : {}),
169
172
  ...(planned.artifact !== undefined ? { artifact: planned.artifact } : {}),
170
173
  ...(planned.changeSet ? { part: planned.changeSet } : {}),
171
174
  ...effects,
@@ -114,6 +114,17 @@ export function opWaveNotifyFields(
114
114
  reason: result.outcome.reason ?? `another run${holder ? `, ${holder.run},` : ""} holds what the apply changes; apply again once it is done`,
115
115
  };
116
116
  }
117
+ if (result.exitCode === CHANT_EXIT.moved && decision?.refused?.reason === "moved") {
118
+ // The plans moved since the pull request previewed them (`approvals.preview`), or were never previewed.
119
+ return {
120
+ ...base,
121
+ event: "refused",
122
+ status: "moved",
123
+ summary: `${label} refused: ${decision.preview?.status === "unrecorded" ? "its plans were not previewed" : "its plans moved since the pull request previewed them"}`,
124
+ targets: decision.refused.runs,
125
+ reason: decision.refused.message ?? "the plans are not the ones the pull request previewed, so nothing was applied",
126
+ };
127
+ }
117
128
  if (result.exitCode === CHANT_EXIT.moved) {
118
129
  return {
119
130
  ...base,
@@ -0,0 +1,284 @@
1
+ import { afterEach, describe, expect, test } from "vitest";
2
+ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { tmpdir } from "node:os";
5
+ import { assertOpWavesSpec, opWavesPostsApprovalStatus, type OpWavesSpec } from "./op-waves";
6
+ import { OP_WAVES_PREVIEW_FLOOR, readOpWavePolicy, runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
7
+ import { memoryGateLedgerPort } from "./gate";
8
+ import { waveSetDigest } from "../gated-waves";
9
+ import type { HeadPlanMember, HeadPlans, MergedReview, ReviewSource } from "./gate-review";
10
+ import { movedSincePreview, shortAddress } from "./op-waves-preview";
11
+
12
+ const spec: OpWavesSpec = {
13
+ name: "records",
14
+ op: "dns",
15
+ plan: ["tool", "plan", "{target}", "--out", "{plan}"],
16
+ apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
17
+ approvals: { preview: true },
18
+ waves: [{ name: "dev", runs: [{ target: "zone" }], gate: "on-destructive" }],
19
+ };
20
+
21
+ const digest = (n: string) => `sha256:${n.repeat(64)}`;
22
+ const setOf = (n: string) => waveSetDigest([{ member: "zone", planDigest: digest(n) }]);
23
+ const merged: MergedReview = { pr: 7, head: "h".repeat(40), author: "github:dev", approvers: ["github:rev"], refused: [] };
24
+ const reviews = (m: MergedReview | null): ReviewSource => ({ kind: "github", mergedReview: async () => m });
25
+ const recorded = (wave: number, set: string | undefined): ((name: string, head: string) => Promise<HeadPlans | null>) => async (name, head) =>
26
+ set === undefined ? null : { version: 1, name, head, timestamp: "2026-10-30T00:00:00Z", waves: [{ wave, name: "dev", digest: set }] };
27
+
28
+ /** A record as chant after 0.124.59 writes it: the set digest, and each run's resources. */
29
+ const recordedRuns = (wave: number, members: HeadPlanMember[]): ((name: string, head: string) => Promise<HeadPlans | null>) => async (name, head) => ({
30
+ version: 1,
31
+ name,
32
+ head,
33
+ timestamp: "2026-10-30T00:00:00Z",
34
+ waves: [{ wave, name: "dev", digest: waveSetDigest(members.map((m) => ({ member: m.member, planDigest: m.planDigest }))), members }],
35
+ });
36
+
37
+ const dirs: string[] = [];
38
+ afterEach(() => {
39
+ for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
40
+ });
41
+
42
+ function harness(plan: { planDigest: string; destructive?: boolean; resources?: Record<string, string> }, atBase: OpWavesSpec = spec) {
43
+ const cwd = mkdtempSync(join(tmpdir(), "op-waves-preview-"));
44
+ dirs.push(cwd);
45
+ const calls: string[] = [];
46
+ const exec: OpWaveExec = (argv, dir) => {
47
+ calls.push(argv.join(" "));
48
+ if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify(plan));
49
+ return 0;
50
+ };
51
+ const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(atBase) });
52
+ return { cwd, exec, show, applied: () => calls.some((c) => c.startsWith("tool apply")) };
53
+ }
54
+
55
+ const run = (h: ReturnType<typeof harness>, extra: Partial<Parameters<typeof runOpWave>[0]> = {}) =>
56
+ runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), head: "m".repeat(40), now: "2026-10-30T01:00:00Z", log: () => {}, ...extra });
57
+
58
+ describe("a wave applies the plans its pull request previewed (approvals.preview)", () => {
59
+ test("a record that moved between the preview and the merge returns 4 and applies nothing", async () => {
60
+ const h = harness({ planDigest: digest("b") });
61
+ const logs: string[] = [];
62
+ const result = await run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")), log: (l) => logs.push(l) });
63
+ expect(result.exitCode).toBe(4);
64
+ expect(result.moved).toEqual(["zone"]);
65
+ expect(result.decision).toMatchObject({ status: "refused", refused: { reason: "moved", runs: ["zone"] }, preview: { status: "moved", pr: 7, recorded: setOf("a") } });
66
+ expect(result.decision?.refused?.message).toMatch(/the head hhhhhhhhhhhh planned/);
67
+ expect(h.applied()).toBe(false);
68
+ expect(logs.some((l) => /plans moved since #7 previewed them/.test(l))).toBe(true);
69
+ });
70
+
71
+ test("an unchanged record applies, though the gate asks for no approval", async () => {
72
+ const h = harness({ planDigest: digest("a") });
73
+ const result = await run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
74
+ expect(result).toMatchObject({ exitCode: 0, applied: ["zone"], decision: { status: "not-required", preview: { status: "matched", pr: 7 } } });
75
+ expect(h.applied()).toBe(true);
76
+ });
77
+
78
+ test("a destructive change still waits for its approval when the preview matches", async () => {
79
+ const h = harness({ planDigest: digest("a"), destructive: true });
80
+ const gates = memoryGateLedgerPort();
81
+ const result = await run(h, { gates, reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
82
+ expect(result.exitCode).toBe(3);
83
+ expect(result.decision).toMatchObject({ status: "waiting", preview: { status: "matched" } });
84
+ expect(h.applied()).toBe(false);
85
+ const approved = memoryGateLedgerPort({
86
+ resolutions: [{ version: 1, op: "records", gate: "records-wave-1", resolvedBy: "alice", timestamp: "2026-10-30T00:30:00Z", planDigest: setOf("a") }],
87
+ });
88
+ const again = await run(h, { gates: approved, reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
89
+ expect(again).toMatchObject({ exitCode: 0, applied: ["zone"], decision: { status: "approved", approvedBy: "alice" } });
90
+ });
91
+
92
+ test("with no approval required, the wave compares with the digest of the preview it was shown", async () => {
93
+ // gate: never needs nothing, yet the preview still binds the plans.
94
+ const never: OpWavesSpec = { ...spec, waves: [{ ...spec.waves[0]!, gate: "never" }] };
95
+ const moved = harness({ planDigest: digest("c") }, never);
96
+ const refused = await run(moved, { spec: never, reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
97
+ expect(refused).toMatchObject({ exitCode: 4, decision: { policy: "never", preview: { status: "moved" } } });
98
+ expect(moved.applied()).toBe(false);
99
+ const same = harness({ planDigest: digest("a") }, never);
100
+ expect(await run(same, { spec: never, reviews: reviews(merged), headPlans: recorded(1, setOf("a")) })).toMatchObject({ exitCode: 0, applied: ["zone"] });
101
+ });
102
+
103
+ test("plans nobody previewed refuse too: no merged pull request, or no record for its head", async () => {
104
+ const direct = harness({ planDigest: digest("a") });
105
+ const none = await run(direct, { reviews: reviews(null), headPlans: recorded(1, setOf("a")) });
106
+ expect(none).toMatchObject({ exitCode: 4, decision: { preview: { status: "unrecorded" } } });
107
+ expect(none.decision?.refused?.message).toMatch(/no merged pull request produced/);
108
+ const unrecorded = harness({ planDigest: digest("a") });
109
+ const missing = await run(unrecorded, { reviews: reviews(merged), headPlans: recorded(1, undefined) });
110
+ expect(missing).toMatchObject({ exitCode: 4, decision: { preview: { status: "unrecorded" } } });
111
+ expect(missing.decision?.refused?.message).toMatch(/--record-plans/);
112
+ expect(direct.applied() || unrecorded.applied()).toBe(false);
113
+ });
114
+
115
+ test("an approval of the plans made now lets a moved wave apply, and the refusal names the command", async () => {
116
+ const h = harness({ planDigest: digest("b") });
117
+ const refused = await run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
118
+ expect(refused.decision?.refused?.message).toContain(`chant approve records records-wave-1 ${setOf("b")}`.split(" ").slice(0, 3).join(" "));
119
+ expect(refused.decision?.approve).toContain(setOf("b"));
120
+ const approved = memoryGateLedgerPort({
121
+ resolutions: [{ version: 1, op: "records", gate: "records-wave-1", resolvedBy: "alice", timestamp: "2026-10-30T00:45:00Z", planDigest: setOf("b") }],
122
+ });
123
+ const result = await run(h, { gates: approved, reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
124
+ expect(result).toMatchObject({ exitCode: 0, applied: ["zone"], decision: { status: "approved", approvedBy: "alice", preview: { status: "moved", approvedAnyway: true } } });
125
+ });
126
+
127
+ test("a forge that cannot be read fails the wave and applies nothing", async () => {
128
+ const h = harness({ planDigest: digest("a") });
129
+ const broken: ReviewSource = { kind: "github", mergedReview: async () => { throw new Error("403"); } };
130
+ const result = await run(h, { reviews: broken, headPlans: recorded(1, setOf("a")) });
131
+ expect(result.exitCode).toBe(1);
132
+ expect(h.applied()).toBe(false);
133
+ });
134
+
135
+ test("a change cannot switch it off: the setting is read at base", async () => {
136
+ const h = harness({ planDigest: digest("b") });
137
+ const off: OpWavesSpec = { ...spec, approvals: { preview: false } };
138
+ const result = await run(h, { spec: off, reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
139
+ expect(result.exitCode).toBe(4);
140
+ const without = harness({ planDigest: digest("b") }, { ...spec, approvals: {} });
141
+ expect(await run(without, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) })).toMatchObject({ exitCode: 0, applied: ["zone"] });
142
+ });
143
+
144
+ test("a spec without it keeps the behaviour it had", async () => {
145
+ const plain: OpWavesSpec = { ...spec, approvals: {} };
146
+ const h = harness({ planDigest: digest("b") }, plain);
147
+ const result = await run(h, { spec: plain });
148
+ expect(result).toMatchObject({ exitCode: 0, applied: ["zone"], decision: { status: "not-required" } });
149
+ expect(result.decision?.preview).toBeUndefined();
150
+ });
151
+
152
+ test("a share job ends on a moved decision with 4", async () => {
153
+ const wide: OpWavesSpec = { ...spec, waves: [{ name: "dev", runs: [{ target: "zone" }, { target: "zone2" }], gate: "on-destructive", shares: 2 }] };
154
+ const h = harness({ planDigest: digest("b") }, wide);
155
+ const decided = await run(h, { spec: wide, decide: true, reviews: reviews(merged), headPlans: recorded(1, waveSetDigest([{ member: "zone", planDigest: digest("a") }, { member: "zone2", planDigest: digest("a") }])) });
156
+ expect(decided.exitCode).toBe(4);
157
+ const share = await run(h, { spec: wide, share: 1 });
158
+ expect(share.exitCode).toBe(4);
159
+ expect(h.applied()).toBe(false);
160
+ });
161
+ });
162
+
163
+ describe("the setting", () => {
164
+ test("its floor is the release that shipped it", () => {
165
+ expect(OP_WAVES_PREVIEW_FLOOR).toBe("0.124.59");
166
+ });
167
+
168
+ test("is a boolean, is read at base, and makes the head record its plans", () => {
169
+ expect(() => assertOpWavesSpec(spec)).not.toThrow();
170
+ expect(() => assertOpWavesSpec({ ...spec, approvals: { preview: "yes" } } as unknown as OpWavesSpec)).toThrow(/approvals.preview must be true or false/);
171
+ expect(readOpWavePolicy("waves.json", "dev", "HEAD", "/", () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) })).preview).toBe(true);
172
+ expect(readOpWavePolicy("waves.json", "dev", "HEAD", "/", () => ({ sha: "b".repeat(40), text: JSON.stringify({ ...spec, approvals: {} }) })).preview).toBeUndefined();
173
+ expect(opWavesPostsApprovalStatus(spec)).toBe(true);
174
+ expect(opWavesPostsApprovalStatus({ ...spec, approvals: {} })).toBe(false);
175
+ });
176
+ });
177
+
178
+ describe("a wave compares the resources its pull request's plan changed (plywood#55)", () => {
179
+ // shop/dev holds an events queue and a set of worker queues. One pull request changes the events queue (EV), another adds a worker (WK).
180
+ const stack = "zone";
181
+ const EV = "urn:pulumi:dev::shop::aws:sqs/queue:Queue::events";
182
+ const WK = "urn:pulumi:dev::shop::aws:sqs/queue:Queue::worker-3";
183
+ const eventsPr: MergedReview = { pr: 3, head: "e".repeat(40), author: "github:dev", approvers: ["github:rev"], refused: [] };
184
+ const workersPr: MergedReview = { pr: 4, head: "w".repeat(40), author: "github:dev", approvers: ["github:rev"], refused: [] };
185
+ // What each pull request previewed against main before either merged.
186
+ const previewedEvents: HeadPlanMember[] = [{ member: stack, planDigest: digest("1"), resources: { [EV]: digest("e") } }];
187
+ const previewedWorkers: HeadPlanMember[] = [{ member: stack, planDigest: digest("2"), resources: { [WK]: digest("w") } }];
188
+
189
+ test("two pull requests that touch different resources both apply when merged in sequence", async () => {
190
+ // The first merge plans the events change alone.
191
+ const first = harness({ planDigest: digest("3"), resources: { [EV]: digest("e") } });
192
+ const one = await run(first, { reviews: reviews(eventsPr), headPlans: recordedRuns(1, previewedEvents) });
193
+ expect(one).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "not-required", preview: { status: "matched", pr: 3, compared: "resources" } } });
194
+ expect(first.applied()).toBe(true);
195
+ // The second merge plans while the first one's step is still in its plan: its set digest is neither pull request's.
196
+ const second = harness({ planDigest: digest("4"), resources: { [EV]: digest("e"), [WK]: digest("w") } });
197
+ const two = await run(second, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
198
+ expect(two).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "not-required", preview: { status: "matched", pr: 4, compared: "resources" } } });
199
+ expect(two.decision?.digest).not.toBe(two.decision?.preview?.recorded);
200
+ expect(second.applied()).toBe(true);
201
+ });
202
+
203
+ test("the second merge applies too when the first one has applied before it plans", async () => {
204
+ // The events queue is unchanged now but its recorded inputs are the new ones, so the stack's plan digest moved.
205
+ const second = harness({ planDigest: digest("5"), resources: { [WK]: digest("w") } });
206
+ const result = await run(second, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
207
+ expect(result).toMatchObject({ exitCode: 0, applied: [stack], decision: { preview: { status: "matched", compared: "resources" } } });
208
+ expect(second.applied()).toBe(true);
209
+ });
210
+
211
+ test("a pull request whose touched resource moved after another merge still returns 4", async () => {
212
+ // The other merge changed the worker queue the second pull request planned a change to.
213
+ const h = harness({ planDigest: digest("6"), resources: { [EV]: digest("e"), [WK]: digest("x") } });
214
+ const logs: string[] = [];
215
+ const result = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers), log: (l) => logs.push(l) });
216
+ expect(result.exitCode).toBe(4);
217
+ expect(result.moved).toEqual([stack]);
218
+ expect(result.decision).toMatchObject({ status: "refused", refused: { reason: "moved" }, preview: { status: "moved", compared: "resources", moved: [`${stack}: aws:sqs/queue:Queue::worker-3 is planned differently`] } });
219
+ expect(result.decision?.refused?.message).toMatch(/worker-3 is planned differently/);
220
+ expect(h.applied()).toBe(false);
221
+ });
222
+
223
+ test("a resource the pull request changed that the merge no longer changes returns 4", async () => {
224
+ const h = harness({ planDigest: digest("7"), resources: { [EV]: digest("e") } });
225
+ const result = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
226
+ expect(result).toMatchObject({ exitCode: 4, decision: { preview: { status: "moved", moved: [`${stack}: aws:sqs/queue:Queue::worker-3 is no longer changed by the plans`] } } });
227
+ expect(h.applied()).toBe(false);
228
+ });
229
+
230
+ test("a run the pull request changed that the wave no longer plans returns 4", () => {
231
+ expect(movedSincePreview(previewedWorkers, [])).toEqual([`${stack} is no longer in the wave`]);
232
+ });
233
+
234
+ test("a destructive change another merge added still waits for its approval", async () => {
235
+ const h = harness({ planDigest: digest("8"), destructive: true, resources: { [EV]: digest("d"), [WK]: digest("w") } });
236
+ const result = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
237
+ expect(result).toMatchObject({ exitCode: 3, decision: { status: "waiting", preview: { status: "matched" } } });
238
+ expect(h.applied()).toBe(false);
239
+ const approved = memoryGateLedgerPort({
240
+ resolutions: [{ version: 1, op: "records", gate: "records-wave-1", resolvedBy: "alice", timestamp: "2026-10-30T00:30:00Z", planDigest: result.decision!.digest }],
241
+ });
242
+ expect(await run(h, { gates: approved, reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) })).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "approved" } });
243
+ });
244
+
245
+ test("an approval of the digest planned now lets a moved resource through", async () => {
246
+ const h = harness({ planDigest: digest("6"), resources: { [WK]: digest("x") } });
247
+ const refused = await run(h, { reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
248
+ expect(refused.exitCode).toBe(4);
249
+ const approved = memoryGateLedgerPort({
250
+ resolutions: [{ version: 1, op: "records", gate: "records-wave-1", resolvedBy: "alice", timestamp: "2026-10-30T00:30:00Z", planDigest: refused.decision!.digest }],
251
+ });
252
+ const result = await run(h, { gates: approved, reviews: reviews(workersPr), headPlans: recordedRuns(1, previewedWorkers) });
253
+ expect(result).toMatchObject({ exitCode: 0, applied: [stack], decision: { status: "approved", preview: { status: "moved", approvedAnyway: true } } });
254
+ });
255
+
256
+ test("a run recorded with no resources is compared whole, and one that changed nothing is not compared", async () => {
257
+ const whole: HeadPlanMember[] = [{ member: stack, planDigest: digest("a") }];
258
+ const moved = harness({ planDigest: digest("b") });
259
+ expect(await run(moved, { reviews: reviews(merged), headPlans: recordedRuns(1, whole) })).toMatchObject({ exitCode: 4, decision: { preview: { compared: "resources", moved: [`${stack}: its plan is another digest`] } } });
260
+ const same = harness({ planDigest: digest("a") });
261
+ expect(await run(same, { reviews: reviews(merged), headPlans: recordedRuns(1, whole) })).toMatchObject({ exitCode: 0, applied: [stack] });
262
+ const nothing = harness({ planDigest: digest("c"), resources: { [EV]: digest("e") } });
263
+ expect(await run(nothing, { reviews: reviews(merged), headPlans: recordedRuns(1, [{ member: stack, planDigest: digest("a"), empty: true }]) })).toMatchObject({ exitCode: 0, applied: [stack] });
264
+ });
265
+
266
+ test("a record written by 0.124.59 holds the set digest only, and is compared whole with a message saying so", async () => {
267
+ const h = harness({ planDigest: digest("b"), resources: { [WK]: digest("w") } });
268
+ const result = await run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) });
269
+ expect(result).toMatchObject({ exitCode: 4, decision: { preview: { status: "moved", compared: "wave", recorded: setOf("a") } } });
270
+ expect(result.decision?.refused?.message).toMatch(/written by chant 0\.124\.59, which keeps the wave's digest only/);
271
+ const same = harness({ planDigest: digest("a"), resources: { [WK]: digest("w") } });
272
+ expect(await run(same, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) })).toMatchObject({ exitCode: 0, applied: [stack], decision: { preview: { status: "matched", compared: "wave" } } });
273
+ });
274
+
275
+ test("the plan file's resources are checked", async () => {
276
+ const h = harness({ planDigest: digest("a"), resources: { [WK]: 5 as unknown as string } });
277
+ await expect(run(h, { reviews: reviews(merged), headPlans: recorded(1, setOf("a")) })).rejects.toThrow(/map of a resource's address to its digest/);
278
+ });
279
+
280
+ test("an address reads short", () => {
281
+ expect(shortAddress(EV)).toBe("aws:sqs/queue:Queue::events");
282
+ expect(shortAddress("aws_s3_bucket.logs")).toBe("aws_s3_bucket.logs");
283
+ });
284
+ });
@@ -0,0 +1,70 @@
1
+ /**
2
+ * What `approvals.preview` compares (plywood#55): the resources a pull
3
+ * request's plan changed, and only those.
4
+ *
5
+ * A wave's set digest covers every run's whole plan. Two pull requests that
6
+ * change different resources of one stack, merged one after the other, never
7
+ * share a set digest: the second merge plans with the first one's change in
8
+ * it, either still waiting to apply (the plan holds that step) or applied
9
+ * (the plan holds that resource's new inputs where the pull request saw the
10
+ * old ones). Comparing the set refused the second merge's wave although
11
+ * nothing it previewed had moved.
12
+ *
13
+ * The record a pull request's head keeps (`HeadPlanWave.members`) holds, for
14
+ * each run, the digest of each resource its plan changes. The merged wave
15
+ * compares those resources with the ones it plans now:
16
+ *
17
+ * - a resource the pull request changed that the merge plans with another
18
+ * digest, or no longer changes, has moved;
19
+ * - a resource the merge changes that the pull request did not is another
20
+ * change's, which that change's own preview and gate answer for, and is not
21
+ * compared;
22
+ * - a run recorded with no resource digests (its plan command gave none) is
23
+ * compared whole, by its plan digest, unless its plan changed nothing;
24
+ * - a run the pull request's plan changed that the wave no longer plans has
25
+ * moved.
26
+ *
27
+ * The wave's gate still reads the plans the merge made, so a destructive
28
+ * change the merge adds waits for its approval whoever previewed it.
29
+ */
30
+ import type { HeadPlanMember } from "../lifecycle/wave-plans";
31
+ import { samePlanDigest } from "../lifecycle/plan-digest";
32
+
33
+ /** What the wave plans now for one run, as far as the comparison reads it. */
34
+ export interface PlannedRunDigests {
35
+ member: string;
36
+ planDigest: string;
37
+ resources?: Record<string, string>;
38
+ }
39
+
40
+ /** A resource address as a person reads it: a Pulumi URN is its type and name. */
41
+ export function shortAddress(address: string): string {
42
+ if (!address.startsWith("urn:pulumi:")) return address;
43
+ const parts = address.split("::");
44
+ return parts.length >= 3 ? parts.slice(-2).join("::") : address;
45
+ }
46
+
47
+ /**
48
+ * The runs and resources of the pull request's plan that the wave's plans now
49
+ * disagree with, as sentences naming each. Empty: nothing the pull request
50
+ * previewed has moved.
51
+ */
52
+ export function movedSincePreview(recorded: readonly HeadPlanMember[], now: readonly PlannedRunDigests[]): string[] {
53
+ const byMember = new Map(now.map((m) => [m.member, m]));
54
+ const moved: string[] = [];
55
+ for (const before of recorded) {
56
+ const fresh = byMember.get(before.member);
57
+ if (before.resources && fresh?.resources) {
58
+ for (const [address, digest] of Object.entries(before.resources)) {
59
+ const found = fresh.resources[address];
60
+ if (found === undefined) moved.push(`${before.member}: ${shortAddress(address)} is no longer changed by the plans`);
61
+ else if (!samePlanDigest(found, digest)) moved.push(`${before.member}: ${shortAddress(address)} is planned differently`);
62
+ }
63
+ continue;
64
+ }
65
+ if (before.empty === true) continue;
66
+ if (!fresh) moved.push(`${before.member} is no longer in the wave`);
67
+ else if (!samePlanDigest(before.planDigest, fresh.planDigest)) moved.push(`${before.member}: its plan is another digest`);
68
+ }
69
+ return moved;
70
+ }