@intentius/chant 0.124.59 → 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant",
3
- "version": "0.124.59",
3
+ "version": "0.124.60",
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",
@@ -153,6 +153,17 @@ export interface CapabilityPlan {
153
153
  * still counts toward the digest, with no entries.
154
154
  */
155
155
  changeSet?: ChangeSetPart;
156
+ /**
157
+ * The digest of each resource the plan changes, by the resource's address
158
+ * in the engine (a URN, a terraform address), with the values the engine
159
+ * made up while planning left out (plywood#55, plywood#56). A resource the
160
+ * plan leaves alone is not in it. A merged wave under `approvals.preview`
161
+ * compares these with the ones its pull request recorded, resource by
162
+ * resource, so a change another merge made to a resource the pull request
163
+ * never touched does not read as a moved plan. Absent: the member is
164
+ * compared as a whole by its `planDigest`.
165
+ */
166
+ resourceDigests?: Record<string, string>;
156
167
  /**
157
168
  * The outputs `run` will expose once it applies this plan (#3999), as far
158
169
  * as the plan can tell. A pull request's plan reads a dependent's
@@ -73,6 +73,16 @@ describe("wave plans readers", () => {
73
73
  expect(await listWavePlanSpecs(port)).toEqual(["other", "ship"]);
74
74
  });
75
75
 
76
+ test("the parser reads each run's resources, and a record from 0.124.59 without them (plywood#55)", () => {
77
+ const record = (members?: unknown) => JSON.stringify({ version: 1, name: "a", head: "b", timestamp: "t", waves: [{ wave: 1, name: "x", digest: "d", ...(members === undefined ? {} : { members }) }] });
78
+ expect(parseHeadPlans(record())!.waves[0]!.members).toBeUndefined();
79
+ const runs = [{ member: "shop/dev", planDigest: "p", resources: { "urn:a": "d1" } }, { member: "shop/qa", planDigest: "q", empty: true }];
80
+ expect(parseHeadPlans(record(runs))!.waves[0]!.members).toEqual(runs);
81
+ expect(parseHeadPlans(record("nope"))).toBeNull();
82
+ expect(parseHeadPlans(record([{ member: "m" }]))).toBeNull();
83
+ expect(parseHeadPlans(record([{ member: "m", planDigest: "p", resources: { a: 1 } }]))).toBeNull();
84
+ });
85
+
76
86
  test("the parser refuses a record of another shape", () => {
77
87
  expect(parseHeadPlans(null)).toBeNull();
78
88
  expect(parseHeadPlans("[]")).toBeNull();
@@ -25,6 +25,20 @@ export interface HeadPlans {
25
25
  waves: Array<HeadPlanWave>;
26
26
  }
27
27
 
28
+ /**
29
+ * One run's plan at the head (plywood#55), kept so a merged wave can compare
30
+ * the resources the pull request changed, and only those, with the ones it
31
+ * plans now. `resources` is the digest of each resource the plan changes, by
32
+ * address; a run whose plan gave none is compared as a whole by `planDigest`.
33
+ * `empty` is a plan that changes nothing.
34
+ */
35
+ export interface HeadPlanMember {
36
+ member: string;
37
+ planDigest: string;
38
+ resources?: Record<string, string>;
39
+ empty?: true;
40
+ }
41
+
28
42
  /**
29
43
  * One wave's plan at the head. `changes` and `destructive` (#4630) are the
30
44
  * plan's facts a gate policy reads: some run changes something, some run's
@@ -44,6 +58,12 @@ export interface HeadPlanWave {
44
58
  * approval against it.
45
59
  */
46
60
  changeSet?: string;
61
+ /**
62
+ * Each run's plan at the head (plywood#55). A record from chant 0.124.59
63
+ * has none: it holds the wave's set digest only, and a merged wave
64
+ * compares that whole digest, as it did.
65
+ */
66
+ members?: HeadPlanMember[];
47
67
  }
48
68
 
49
69
  /** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
@@ -71,8 +91,10 @@ export function parseHeadPlans(text: string | null): HeadPlans | null {
71
91
  const waves: HeadPlans["waves"] = [];
72
92
  for (const w of r.waves) {
73
93
  if (w === null || typeof w !== "object") return null;
74
- const { wave, name, digest, changes, destructive, changeSet } = w as Record<string, unknown>;
94
+ const { wave, name, digest, changes, destructive, changeSet, members } = w as Record<string, unknown>;
75
95
  if (typeof wave !== "number" || typeof name !== "string" || typeof digest !== "string") return null;
96
+ const runs = members === undefined ? undefined : parseHeadPlanMembers(members);
97
+ if (runs === null) return null;
76
98
  waves.push({
77
99
  wave,
78
100
  name,
@@ -80,11 +102,29 @@ export function parseHeadPlans(text: string | null): HeadPlans | null {
80
102
  ...(typeof changes === "boolean" ? { changes } : {}),
81
103
  ...(typeof destructive === "boolean" ? { destructive } : {}),
82
104
  ...(typeof changeSet === "string" && changeSet !== "" ? { changeSet } : {}),
105
+ ...(runs ? { members: runs } : {}),
83
106
  });
84
107
  }
85
108
  return { version: 1, name: r.name, head: r.head, timestamp: r.timestamp, waves };
86
109
  }
87
110
 
111
+ function parseHeadPlanMembers(value: unknown): HeadPlanMember[] | null {
112
+ if (!Array.isArray(value)) return null;
113
+ const out: HeadPlanMember[] = [];
114
+ for (const m of value) {
115
+ if (m === null || typeof m !== "object") return null;
116
+ const { member, planDigest, resources, empty } = m as Record<string, unknown>;
117
+ if (typeof member !== "string" || typeof planDigest !== "string") return null;
118
+ let digests: Record<string, string> | undefined;
119
+ if (resources !== undefined) {
120
+ if (resources === null || typeof resources !== "object" || Array.isArray(resources) || !Object.values(resources).every((d) => typeof d === "string")) return null;
121
+ digests = resources as Record<string, string>;
122
+ }
123
+ out.push({ member, planDigest, ...(digests ? { resources: digests } : {}), ...(empty === true ? { empty: true as const } : {}) });
124
+ }
125
+ return out;
126
+ }
127
+
88
128
  /** The record for `head` of the spec `name`, or null when none was recorded or it cannot be read. */
89
129
  export async function readHeadPlans(port: LedgerReadPort, name: string, head: string): Promise<HeadPlans | null> {
90
130
  const { dir, file } = headPlansPath(name, head);
@@ -178,7 +178,7 @@ describe("a pr-review wave (#3684)", () => {
178
178
  let written: unknown;
179
179
  const recorded = await recordOpWaveHeadPlans({ spec: spec("pr-review"), cwd: h.cwd, exec: h.exec, head: HEAD, now: "t", write: async (p) => void (written = p) });
180
180
  // #4630: the record keeps whether the wave changes anything and whether it is destructive.
181
- expect(recorded.waves).toEqual([{ wave: 1, name: "prod", digest: set(digest("a")), changes: true, destructive: false }]);
181
+ expect(recorded.waves).toEqual([{ wave: 1, name: "prod", digest: set(digest("a")), changes: true, destructive: false, members: [{ member: "prod", planDigest: digest("a") }] }]);
182
182
  expect(written).toEqual(recorded);
183
183
  });
184
184
  });
@@ -71,7 +71,7 @@ export function bothRules(a: GateApprovalRule | null, b: GateApprovalRule | null
71
71
  // ── pr-review ─────────────────────────────────────────────────────────────
72
72
 
73
73
  // The record and its reader live apart, so a bundle can import them without git (#3865).
74
- export { HEAD_PLANS_DIR, headPlansPath, type HeadPlans } from "../lifecycle/wave-plans";
74
+ export { HEAD_PLANS_DIR, headPlansPath, type HeadPlans, type HeadPlanMember } from "../lifecycle/wave-plans";
75
75
 
76
76
 
77
77
  /** The merged pull request's review, as a `pr-review` gate reads it. */
package/src/op/index.ts CHANGED
@@ -92,6 +92,7 @@ export {
92
92
  runOpWaveApplyHooks,
93
93
  opWaveResourceLines,
94
94
  } from "./op-waves-run";
95
+ export { movedSincePreview, shortAddress, type PlannedRunDigests } from "./op-waves-preview";
95
96
  export type {
96
97
  OpWaveBaseRules,
97
98
  OpWaveDecision,
@@ -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,
@@ -5,9 +5,9 @@ import { tmpdir } from "node:os";
5
5
  import { assertOpWavesSpec, opWavesPostsApprovalStatus, type OpWavesSpec } from "./op-waves";
6
6
  import { OP_WAVES_PREVIEW_FLOOR, readOpWavePolicy, runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
7
7
  import { memoryGateLedgerPort } from "./gate";
8
- import { NEXT_RELEASE } from "../release-floors";
9
8
  import { waveSetDigest } from "../gated-waves";
10
- import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
9
+ import type { HeadPlanMember, HeadPlans, MergedReview, ReviewSource } from "./gate-review";
10
+ import { movedSincePreview, shortAddress } from "./op-waves-preview";
11
11
 
12
12
  const spec: OpWavesSpec = {
13
13
  name: "records",
@@ -25,12 +25,21 @@ const reviews = (m: MergedReview | null): ReviewSource => ({ kind: "github", mer
25
25
  const recorded = (wave: number, set: string | undefined): ((name: string, head: string) => Promise<HeadPlans | null>) => async (name, head) =>
26
26
  set === undefined ? null : { version: 1, name, head, timestamp: "2026-10-30T00:00:00Z", waves: [{ wave, name: "dev", digest: set }] };
27
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
+
28
37
  const dirs: string[] = [];
29
38
  afterEach(() => {
30
39
  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
31
40
  });
32
41
 
33
- function harness(plan: { planDigest: string; destructive?: boolean }, atBase: OpWavesSpec = spec) {
42
+ function harness(plan: { planDigest: string; destructive?: boolean; resources?: Record<string, string> }, atBase: OpWavesSpec = spec) {
34
43
  const cwd = mkdtempSync(join(tmpdir(), "op-waves-preview-"));
35
44
  dirs.push(cwd);
36
45
  const calls: string[] = [];
@@ -152,8 +161,8 @@ describe("a wave applies the plans its pull request previewed (approvals.preview
152
161
  });
153
162
 
154
163
  describe("the setting", () => {
155
- test("its floor is the next release", () => {
156
- expect(OP_WAVES_PREVIEW_FLOOR).toBe(NEXT_RELEASE);
164
+ test("its floor is the release that shipped it", () => {
165
+ expect(OP_WAVES_PREVIEW_FLOOR).toBe("0.124.59");
157
166
  });
158
167
 
159
168
  test("is a boolean, is read at base, and makes the head record its plans", () => {
@@ -165,3 +174,111 @@ describe("the setting", () => {
165
174
  expect(opWavesPostsApprovalStatus({ ...spec, approvals: {} })).toBe(false);
166
175
  });
167
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
+ }
@@ -82,7 +82,7 @@ import type { GatePointAsker } from "../point-decision";
82
82
  import type { WaitingPoint } from "./steward-points";
83
83
  import { isApprovalSpent, type AppliedGateRecord, type FinishedGateRecord } from "../lifecycle/gate-applied";
84
84
  import { samePlanDigest } from "../lifecycle/plan-digest";
85
- import { NEXT_RELEASE } from "../release-floors";
85
+ import { movedSincePreview } from "./op-waves-preview";
86
86
  import { isLifecycleLocalNote } from "../lifecycle/local-note";
87
87
  import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
88
88
  import type { TrustPolicy } from "../workspace/trust/policy";
@@ -187,6 +187,14 @@ export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldFinished, OpWaveHoldRequest
187
187
  /** What a run's plan command writes to `{plan}`. */
188
188
  export interface OpWavePlanFile {
189
189
  planDigest: string;
190
+ /**
191
+ * The digest of each resource this plan changes, by the resource's address
192
+ * (plywood#55). A merged wave under `approvals.preview` compares the ones
193
+ * its pull request recorded with the ones it plans now, resource by
194
+ * resource, and leaves a resource the pull request's plan did not change
195
+ * out. Absent: the run is compared as a whole, by `planDigest`.
196
+ */
197
+ resources?: Record<string, string>;
190
198
  /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
191
199
  destructive?: boolean;
192
200
  /** The plan changes nothing. */
@@ -260,6 +268,8 @@ export interface OpWaveRunsFile {
260
268
  /** One run's plan, as the decision records it. */
261
269
  export interface OpWaveMember extends WaveMember {
262
270
  op: string;
271
+ /** The digest of each resource the plan changes (plywood#55), when the plan gave them. */
272
+ resources?: Record<string, string>;
263
273
  destructive?: boolean;
264
274
  empty?: boolean;
265
275
  /** The product's policy denied the plan (#3821). */
@@ -412,6 +422,14 @@ export interface OpWavePreview {
412
422
  recorded?: string;
413
423
  /** Why the plans do not match, for `moved` and `unrecorded`. */
414
424
  reason?: string;
425
+ /**
426
+ * What was compared: `resources`, the resources the pull request's plan
427
+ * changed (plywood#55), or `wave`, the wave's whole set digest, which is
428
+ * all a record from chant 0.124.59 holds.
429
+ */
430
+ compared?: "resources" | "wave";
431
+ /** For `moved` under `resources`: each run or resource of the pull request's plan that is not as it was previewed. */
432
+ moved?: string[];
415
433
  /** Set when an approval of the digest planned now let a wave that did not match apply. */
416
434
  approvedAnyway?: true;
417
435
  }
@@ -708,7 +726,7 @@ function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWav
708
726
  }
709
727
 
710
728
  /** The first chant whose Op waves spec takes `approvals.preview`: a merged wave applies the plans its pull request previewed, or exits 4. */
711
- export const OP_WAVES_PREVIEW_FLOOR = NEXT_RELEASE;
729
+ export const OP_WAVES_PREVIEW_FLOOR = "0.124.59";
712
730
 
713
731
  /** The first chant whose op entry exports {@link opWavePlanPath} (terragucci#1304). */
714
732
  export const OP_WAVE_PLAN_PATH_FLOOR = "0.124.56";
@@ -950,6 +968,15 @@ function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpW
950
968
  return member(run.target, op, file);
951
969
  }
952
970
 
971
+ /** A plan file's `resources`: a map of address to digest, or nothing. Anything else is a mistake the wave names. */
972
+ function resourcesOf(value: unknown, target: string): Record<string, string> | undefined {
973
+ if (value === undefined) return undefined;
974
+ if (value === null || typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((d) => typeof d === "string" && d !== "")) {
975
+ throw new Error(`the plan of ${target} has resources ${JSON.stringify(value)}; it is a map of a resource's address to its digest`);
976
+ }
977
+ return Object.fromEntries(Object.entries(value as Record<string, string>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
978
+ }
979
+
953
980
  function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember {
954
981
  for (const key of ["denied", "held"] as const) {
955
982
  const value = file[key] as unknown;
@@ -963,6 +990,7 @@ function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember
963
990
  member: target,
964
991
  planDigest: file.planDigest,
965
992
  op,
993
+ ...(resourcesOf(file.resources, target) ? { resources: resourcesOf(file.resources, target)! } : {}),
966
994
  ...(file.destructive === true ? { destructive: true } : {}),
967
995
  ...(file.empty === true ? { empty: true } : {}),
968
996
  ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
@@ -1113,6 +1141,7 @@ async function planWaveRuns(
1113
1141
  const members = plans.map((p) => ({
1114
1142
  member: p.target,
1115
1143
  planDigest: p.planDigest,
1144
+ ...(p.resources ? { resources: p.resources } : {}),
1116
1145
  op: runs.find((r) => r.target === p.target)?.op ?? spec.op,
1117
1146
  ...(p.destructive ? { destructive: true } : {}),
1118
1147
  ...(p.empty ? { empty: true } : {}),
@@ -2593,11 +2622,11 @@ async function decideOpWave(
2593
2622
  // `approvals.preview` at base: the merged wave applies what the pull request previewed. Planned again to a digest this job already let through, it has been judged.
2594
2623
  let unseen = false;
2595
2624
  if (planned.rules.preview && !kept && decision.status !== "refused") {
2596
- const seen = await previewOf(options, ctx, digest);
2625
+ const seen = await previewOf(options, ctx, digest, members);
2597
2626
  if ("error" in seen) return { end: failed(ctx, `wave ${k} (${wave.name}): ${seen.error}, so it cannot be compared with what the pull request previewed and nothing in it was applied`) };
2598
2627
  decision.preview = seen.preview;
2599
2628
  unseen = seen.preview.status !== "matched";
2600
- if (!unseen) log(`wave ${k} (${wave.name}): the plans are the ones pull request #${seen.preview.pr} previewed at ${seen.preview.head?.slice(0, 12)} (${digest})`);
2629
+ if (!unseen) log(`wave ${k} (${wave.name}): the plans are the ones pull request #${seen.preview.pr} previewed at ${seen.preview.head?.slice(0, 12)} (${seen.preview.compared === "resources" ? `${seen.preview.recorded}, compared resource by resource; the wave now plans ${digest}` : digest})`);
2601
2630
  else log(`wave ${k} (${wave.name}): ${seen.preview.reason}`);
2602
2631
  }
2603
2632
  if (kept && was.status === "approved" && decision.status !== "refused") {
@@ -2634,7 +2663,7 @@ async function decideOpWave(
2634
2663
  * `error` only when the forge or the ledger cannot be read, which fails the
2635
2664
  * wave: a missing answer never stands in for a match.
2636
2665
  */
2637
- async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: string): Promise<{ preview: OpWavePreview } | { error: string }> {
2666
+ async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: string, members: readonly OpWaveMember[]): Promise<{ preview: OpWavePreview } | { error: string }> {
2638
2667
  const { spec, k, cwd } = ctx;
2639
2668
  const review = await import("./gate-review");
2640
2669
  const head = options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim();
@@ -2652,21 +2681,40 @@ async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: st
2652
2681
  return { error: `the plans recorded for #${merged.pr} could not be read (${err instanceof Error ? err.message : String(err)})` };
2653
2682
  }
2654
2683
  const seen = { pr: merged.pr, head: merged.head };
2655
- const recorded = plans?.waves.find((w) => w.wave === k)?.digest;
2684
+ const recordedWave = plans?.waves.find((w) => w.wave === k);
2685
+ const recorded = recordedWave?.digest;
2656
2686
  if (recorded === undefined) {
2657
2687
  return { preview: { status: "unrecorded", ...seen, reason: `no plans are recorded for wave ${k} at the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`), so nothing was previewed` } };
2658
2688
  }
2689
+ // plywood#55: a record that holds each run's resources is compared resource by resource, over the ones the pull request's plan changed.
2690
+ if (recordedWave!.members) {
2691
+ const moved = movedSincePreview(recordedWave!.members, members);
2692
+ if (moved.length > 0) {
2693
+ return {
2694
+ preview: {
2695
+ status: "moved",
2696
+ ...seen,
2697
+ recorded,
2698
+ compared: "resources",
2699
+ moved,
2700
+ reason: `the plans moved since #${merged.pr} previewed them: ${moved.join("; ")} (the head ${merged.head.slice(0, 12)} planned ${recorded}, and the merge plans ${digest})`,
2701
+ },
2702
+ };
2703
+ }
2704
+ return { preview: { status: "matched", ...seen, recorded, compared: "resources" } };
2705
+ }
2659
2706
  if (!samePlanDigest(recorded, digest)) {
2660
2707
  return {
2661
2708
  preview: {
2662
2709
  status: "moved",
2663
2710
  ...seen,
2664
2711
  recorded,
2665
- reason: `the plans moved since #${merged.pr} previewed them: the head ${merged.head.slice(0, 12)} planned ${recorded}, and the merge plans ${digest}`,
2712
+ compared: "wave",
2713
+ reason: `the plans moved since #${merged.pr} previewed them: the head ${merged.head.slice(0, 12)} planned ${recorded}, and the merge plans ${digest}. The record was written by chant 0.124.59, which keeps the wave's digest only, so the whole wave was compared; a later chant records each resource and compares those`,
2666
2714
  },
2667
2715
  };
2668
2716
  }
2669
- return { preview: { status: "matched", ...seen, recorded } };
2717
+ return { preview: { status: "matched", ...seen, recorded, compared: "wave" } };
2670
2718
  }
2671
2719
 
2672
2720
  /**
@@ -3944,6 +3992,8 @@ export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Pr
3944
3992
  digest: opWaveSetDigest(spec, members, extras),
3945
3993
  changes: !members.every((m) => m.empty === true),
3946
3994
  destructive: members.some((m) => m.destructive === true),
3995
+ // plywood#55: each run's resources, which a merged wave under `approvals.preview` compares with its own.
3996
+ members: members.map((m) => ({ member: m.member, planDigest: m.planDigest, ...(m.resources ? { resources: m.resources } : {}), ...(m.empty ? { empty: true as const } : {}) })),
3947
3997
  // #4630: a pull-request wave's change set, which the pull request's own approval must cover.
3948
3998
  ...(changeSet ? { changeSet: changeSet.digest } : {}),
3949
3999
  });
@@ -140,7 +140,7 @@ describe("runOpWave with wave-level commands (#3762)", () => {
140
140
  { name: "apps", runs: [{ target: "a1" }, { target: "a2" }, { target: "a3" }], gate: "never", shares: 2 },
141
141
  ],
142
142
  };
143
- function harness(plans: Record<string, { planDigest: string; destructive?: boolean; empty?: boolean }>, atBase: OpWavesSpec | null = waveSpec) {
143
+ function harness(plans: Record<string, { planDigest: string; destructive?: boolean; empty?: boolean; resources?: Record<string, string> }>, atBase: OpWavesSpec | null = waveSpec) {
144
144
  const cwd = mkdtempSync(join(tmpdir(), "op-waves-wave-"));
145
145
  const calls: string[] = [];
146
146
  const applied: OpWaveRunsFile[] = [];
@@ -211,6 +211,16 @@ describe("runOpWave with wave-level commands (#3762)", () => {
211
211
  expect(h.calls.filter((c) => c.startsWith("tg plan"))).toHaveLength(2);
212
212
  h.done();
213
213
  });
214
+
215
+ test("--record-plans keeps each run's plan and resources for the merged wave to compare (plywood#55)", async () => {
216
+ const h = harness({ vpc: { planDigest: digest("1"), resources: { "aws_vpc.main": digest("a") } }, dns: { planDigest: digest("2"), empty: true }, a1: { planDigest: digest("1") }, a2: { planDigest: digest("2") }, a3: { planDigest: digest("3") } });
217
+ const plans = await recordOpWaveHeadPlans({ spec: waveSpec, cwd: h.cwd, exec: h.exec, head: "c".repeat(40), now: "t", write: async () => {} });
218
+ expect(plans.waves[0]!.members).toEqual([
219
+ { member: "vpc", planDigest: digest("1"), resources: { "aws_vpc.main": digest("a") } },
220
+ { member: "dns", planDigest: digest("2"), empty: true },
221
+ ]);
222
+ h.done();
223
+ });
214
224
  });
215
225
 
216
226
  describe("runOpWave hooks (#3762)", () => {
@@ -19,4 +19,4 @@
19
19
  * this constant to the next patch (#4501). The check fails while a floor
20
20
  * still names this constant after its version shipped.
21
21
  */
22
- export const NEXT_RELEASE = "0.124.59";
22
+ export const NEXT_RELEASE = "0.124.60";