@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
@@ -82,6 +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 { movedSincePreview } from "./op-waves-preview";
85
86
  import { isLifecycleLocalNote } from "../lifecycle/local-note";
86
87
  import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
87
88
  import type { TrustPolicy } from "../workspace/trust/policy";
@@ -186,6 +187,14 @@ export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldFinished, OpWaveHoldRequest
186
187
  /** What a run's plan command writes to `{plan}`. */
187
188
  export interface OpWavePlanFile {
188
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>;
189
198
  /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
190
199
  destructive?: boolean;
191
200
  /** The plan changes nothing. */
@@ -259,6 +268,8 @@ export interface OpWaveRunsFile {
259
268
  /** One run's plan, as the decision records it. */
260
269
  export interface OpWaveMember extends WaveMember {
261
270
  op: string;
271
+ /** The digest of each resource the plan changes (plywood#55), when the plan gave them. */
272
+ resources?: Record<string, string>;
262
273
  destructive?: boolean;
263
274
  empty?: boolean;
264
275
  /** The product's policy denied the plan (#3821). */
@@ -357,6 +368,8 @@ export interface OpWaveDecision {
357
368
  waitingSince?: string;
358
369
  /** While waiting: the newest approval of this gate for another digest, which the plans moved away from. */
359
370
  mismatch?: GateDigestMismatch;
371
+ /** Under `approvals.preview` at base: what the merged pull request's head recorded for this wave, and how the plans now compare with it. */
372
+ preview?: OpWavePreview;
360
373
  /**
361
374
  * Why a `refused` wave applies nothing: the runs the policy denied, and
362
375
  * whether an override stands for an earlier plan or other rules (#3821,
@@ -364,7 +377,7 @@ export interface OpWaveDecision {
364
377
  * it does not pass on (#3836, exit 8), with every run and the `message`.
365
378
  */
366
379
  refused?: {
367
- reason: "policy" | "override-moved" | "point";
380
+ reason: "policy" | "override-moved" | "point" | "moved";
368
381
  runs: string[];
369
382
  message?: string;
370
383
  /** Where the plans file said its overriders come from (#3848), when it did. */
@@ -391,6 +404,36 @@ export interface OpWaveDecision {
391
404
  ciPolicySource?: ResolvedGatePolicySource;
392
405
  }
393
406
 
407
+ /**
408
+ * The plans the merged pull request previewed for a wave, against the plans
409
+ * the wave made now. `matched`: the same set digest, so the wave applies
410
+ * what the pull request showed. `moved`: the head recorded another digest,
411
+ * so a record moved since. `unrecorded`: nothing was recorded to compare
412
+ * with (no merged pull request, no record for its head, or none for this
413
+ * wave).
414
+ */
415
+ export interface OpWavePreview {
416
+ status: "matched" | "moved" | "unrecorded";
417
+ /** The pull request that merged the applied commit. */
418
+ pr?: number;
419
+ /** Its head commit, which `--record-plans` recorded the plans at. */
420
+ head?: string;
421
+ /** The digest the head recorded for this wave. */
422
+ recorded?: string;
423
+ /** Why the plans do not match, for `moved` and `unrecorded`. */
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[];
433
+ /** Set when an approval of the digest planned now let a wave that did not match apply. */
434
+ approvedAnyway?: true;
435
+ }
436
+
394
437
  /**
395
438
  * What an apply call writes to `CHANT_APPLY_OUTCOME` when it applied nothing
396
439
  * for a reason that is not a failure (#3821). `stood-down`: a newer run (a
@@ -584,6 +627,8 @@ export interface OpWaveBaseRules {
584
627
  holdsRefused?: string;
585
628
  /** `approvals.pullRequest.gate` at base (#4550): the pull request's gate a `pull-request` wave takes its approval from. */
586
629
  pullRequestGate?: string;
630
+ /** `approvals.preview` at base: the wave applies what the merged pull request's head recorded, or refuses (exit 4). */
631
+ preview?: boolean;
587
632
  }
588
633
 
589
634
  const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -616,7 +661,7 @@ export function readOpWavePolicy(
616
661
  const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
617
662
  const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
618
663
  // #3836: the gate's decision point, the spec's for a wave the base does not have yet.
619
- const asks = { ...pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`), ...quorumAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...holdsAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...pullRequestGateAtBase(spec) };
664
+ const asks = { ...pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`), ...quorumAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...holdsAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`), ...pullRequestGateAtBase(spec), ...(spec.approvals?.preview === true ? { preview: true } : {}) };
620
665
  const wave = spec.waves.find((w) => w.name === name);
621
666
  if (!wave) return { ...absent, spend, neverOverMcp, ...asks };
622
667
  const policy = wave.gate ?? "always";
@@ -680,6 +725,9 @@ function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWav
680
725
  return { point: opWavePointAt(spec, name)! };
681
726
  }
682
727
 
728
+ /** The first chant whose Op waves spec takes `approvals.preview`: a merged wave applies the plans its pull request previewed, or exits 4. */
729
+ export const OP_WAVES_PREVIEW_FLOOR = "0.124.59";
730
+
683
731
  /** The first chant whose op entry exports {@link opWavePlanPath} (terragucci#1304). */
684
732
  export const OP_WAVE_PLAN_PATH_FLOOR = "0.124.56";
685
733
 
@@ -920,6 +968,15 @@ function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpW
920
968
  return member(run.target, op, file);
921
969
  }
922
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
+
923
980
  function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember {
924
981
  for (const key of ["denied", "held"] as const) {
925
982
  const value = file[key] as unknown;
@@ -933,6 +990,7 @@ function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember
933
990
  member: target,
934
991
  planDigest: file.planDigest,
935
992
  op,
993
+ ...(resourcesOf(file.resources, target) ? { resources: resourcesOf(file.resources, target)! } : {}),
936
994
  ...(file.destructive === true ? { destructive: true } : {}),
937
995
  ...(file.empty === true ? { empty: true } : {}),
938
996
  ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
@@ -1083,6 +1141,7 @@ async function planWaveRuns(
1083
1141
  const members = plans.map((p) => ({
1084
1142
  member: p.target,
1085
1143
  planDigest: p.planDigest,
1144
+ ...(p.resources ? { resources: p.resources } : {}),
1086
1145
  op: runs.find((r) => r.target === p.target)?.op ?? spec.op,
1087
1146
  ...(p.destructive ? { destructive: true } : {}),
1088
1147
  ...(p.empty ? { empty: true } : {}),
@@ -1935,7 +1994,7 @@ function opWaveRunStatus(result: RunOpWaveResult): { status: OpRunRecordInput["s
1935
1994
  case CHANT_EXIT.waiting:
1936
1995
  return { status: d?.point?.question ? "waiting" : "gated" };
1937
1996
  case CHANT_EXIT.moved:
1938
- return { status: "fail", failure: { code: "moved", reason: `plans moved since the decision: ${result.moved.join(", ") || "(none named)"}` } };
1997
+ return { status: "fail", failure: { code: "moved", reason: d?.refused?.reason === "moved" ? d.refused.message ?? "the plans are not the ones the pull request previewed" : `plans moved since the decision: ${result.moved.join(", ") || "(none named)"}` } };
1939
1998
  case CHANT_EXIT.denied:
1940
1999
  return { status: "fail", failure: { code: "denied", reason: d?.refused?.message ?? `the policy denied ${d?.refused?.runs.join(", ") ?? "a run"}, and no override counts` } };
1941
2000
  case CHANT_EXIT.declined:
@@ -2241,12 +2300,12 @@ function writeOpWaveOutcome(options: RunOpWaveOptions, dir: string, result: RunO
2241
2300
  const otherwise: WaveMemberOutcome["status"] =
2242
2301
  result.exitCode === 0 ? (options.decide ? "decided" : "unchanged")
2243
2302
  : result.exitCode === CHANT_EXIT.waiting ? "waiting"
2244
- : result.exitCode === CHANT_EXIT.denied || result.exitCode === CHANT_EXIT.declined ? "refused"
2303
+ : result.exitCode === CHANT_EXIT.denied || result.exitCode === CHANT_EXIT.declined || result.decision?.refused?.reason === "moved" ? "refused"
2245
2304
  : result.exitCode >= CHANT_EXIT.moved && result.exitCode <= CHANT_EXIT.superseded ? "not-applied"
2246
2305
  : "failed";
2247
2306
  for (const t of targets) {
2248
2307
  const by = result.blocked?.[t];
2249
- out[t] = by !== undefined ? { status: "blocked", by } : applied.has(t) ? { status: "applied" } : failed.has(t) ? { status: "failed" } : moved.has(t) ? { status: "not-applied" } : { status: otherwise };
2308
+ out[t] = by !== undefined ? { status: "blocked", by } : applied.has(t) ? { status: "applied" } : failed.has(t) ? { status: "failed" } : moved.has(t) && result.decision?.refused?.reason !== "moved" ? { status: "not-applied" } : { status: otherwise };
2250
2309
  }
2251
2310
  }
2252
2311
  const part = { ...(options.group !== undefined ? { group: options.group } : {}), ...(options.share !== undefined ? { share: options.share } : {}) };
@@ -2354,7 +2413,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2354
2413
  result.decision = decision;
2355
2414
  ctx.gateRule = { approval: decision.approval, base: decision.base, neverOverMcp: decision.neverOverMcp === true };
2356
2415
  if (decision.status === "waiting" || decision.status === "refused") {
2357
- log(`wave ${k} (${wave.name}) is ${decision.status === "refused" ? "refused by its policy" : `waiting on ${decision.heldOn?.gate ?? decision.gate}`}; nothing applied. ${decision.approve ?? ""}`.trim());
2416
+ log(`wave ${k} (${wave.name}) is ${decision.status === "refused" ? (decision.refused?.reason === "moved" ? "refused, its plans moved since the pull request previewed them" : "refused by its policy") : `waiting on ${decision.heldOn?.gate ?? decision.gate}`}; nothing applied. ${decision.approve ?? ""}`.trim());
2358
2417
  return { end: { ...result, exitCode: decision.status === "refused" ? refusedExit(decision) : CHANT_EXIT.waiting } };
2359
2418
  }
2360
2419
  // The share runs the hooks its deciding job read at base, around its own slice.
@@ -2560,12 +2619,26 @@ async function decideOpWave(
2560
2619
  if (was.overridesSpentAt) decision.overridesSpentAt = was.overridesSpentAt;
2561
2620
  }
2562
2621
  if (members.some((m) => m.denied && !m.override)) await settleDenials(ctx, decision, overriders, overridersSource);
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.
2623
+ let unseen = false;
2624
+ if (planned.rules.preview && !kept && decision.status !== "refused") {
2625
+ const seen = await previewOf(options, ctx, digest, members);
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`) };
2627
+ decision.preview = seen.preview;
2628
+ unseen = seen.preview.status !== "matched";
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})`);
2630
+ else log(`wave ${k} (${wave.name}): ${seen.preview.reason}`);
2631
+ }
2563
2632
  if (kept && was.status === "approved" && decision.status !== "refused") {
2564
2633
  // #3821: planned again after the apply asked to, to the same digest: the approval this job found still holds, and is not spent twice.
2565
2634
  for (const key of ["via", "approvedBy", "approvedAt", "review", "spentAt"] as const) if (was[key] !== undefined) (decision as unknown as Record<string, unknown>)[key] = was[key];
2566
2635
  decision.status = "approved";
2567
2636
  log(`wave ${k} (${wave.name}): planned again to the same digest, so the approval by ${was.approvedBy} still holds`);
2568
- } else if (decision.status !== "refused" && (opWaveNeedsApproval(policy, members) || holds.length > 0)) await settleGate(options, ctx, decision);
2637
+ } else if (decision.status !== "refused" && (unseen || opWaveNeedsApproval(policy, members) || holds.length > 0)) {
2638
+ await settleGate(options, ctx, decision);
2639
+ // Plans nobody previewed apply only under an approval of these very plans, whatever the gate policy says.
2640
+ if (unseen) refuseUnseen(ctx, decision);
2641
+ }
2569
2642
  const code = await decided(ctx, decision, recordPath);
2570
2643
  if (code.exitCode !== 0) return { end: code };
2571
2644
  log(
@@ -2583,6 +2656,85 @@ async function decideOpWave(
2583
2656
  return { go: { runs: wave.runs, earlierHolds: [], recordPath } };
2584
2657
  }
2585
2658
 
2659
+ /**
2660
+ * Compare the wave's set digest with the one the merged pull request's head
2661
+ * recorded for it (`--record-plans`): the plans its reviewers saw. The pull
2662
+ * request is the one the forge says produced the applied commit. Resolves to
2663
+ * `error` only when the forge or the ledger cannot be read, which fails the
2664
+ * wave: a missing answer never stands in for a match.
2665
+ */
2666
+ async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: string, members: readonly OpWaveMember[]): Promise<{ preview: OpWavePreview } | { error: string }> {
2667
+ const { spec, k, cwd } = ctx;
2668
+ const review = await import("./gate-review");
2669
+ const head = options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim();
2670
+ let merged: MergedReview | null;
2671
+ try {
2672
+ merged = await (options.reviews ?? review.reviewSourceFromEnv()).mergedReview(head);
2673
+ } catch (err) {
2674
+ return { error: `the merged pull request could not be read from the forge (${err instanceof Error ? err.message : String(err)})` };
2675
+ }
2676
+ if (!merged) return { preview: { status: "unrecorded", reason: `no merged pull request produced ${head.slice(0, 12)}, so no plans were previewed for it` } };
2677
+ let plans: HeadPlans | null;
2678
+ try {
2679
+ plans = await (options.headPlans ?? ((name, h) => readHeadPlans(name, h, cwd)))(spec.name, merged.head);
2680
+ } catch (err) {
2681
+ return { error: `the plans recorded for #${merged.pr} could not be read (${err instanceof Error ? err.message : String(err)})` };
2682
+ }
2683
+ const seen = { pr: merged.pr, head: merged.head };
2684
+ const recordedWave = plans?.waves.find((w) => w.wave === k);
2685
+ const recorded = recordedWave?.digest;
2686
+ if (recorded === undefined) {
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` } };
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
+ }
2706
+ if (!samePlanDigest(recorded, digest)) {
2707
+ return {
2708
+ preview: {
2709
+ status: "moved",
2710
+ ...seen,
2711
+ recorded,
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`,
2714
+ },
2715
+ };
2716
+ }
2717
+ return { preview: { status: "matched", ...seen, recorded, compared: "wave" } };
2718
+ }
2719
+
2720
+ /**
2721
+ * The gate was asked about plans the pull request did not preview. An
2722
+ * approval of exactly these plans lets the wave apply, since a person saw
2723
+ * them; with none, the wave is refused as moved (exit 4) and the approval
2724
+ * that would let it through is named.
2725
+ */
2726
+ function refuseUnseen(ctx: WaveContext, decision: OpWaveDecision): void {
2727
+ const preview = decision.preview!;
2728
+ if (decision.status === "approved") {
2729
+ preview.approvedAnyway = true;
2730
+ ctx.log(`wave ${ctx.k} (${ctx.wave.name}): ${preview.reason}; it applies under the approval of ${decision.digest} by ${decision.approvedBy}`);
2731
+ return;
2732
+ }
2733
+ const how = decision.approve ? ` Approve these plans to apply them: ${decision.approve}` : "";
2734
+ decision.status = "refused";
2735
+ decision.refused = { reason: "moved", runs: decision.members.map((m) => m.member).sort(), message: `${preview.reason}.${how}` };
2736
+ }
2737
+
2586
2738
  /** Apply a decided wave, or a share's unmoved runs (exit 4 when any moved). */
2587
2739
  async function applyOpWave(options: RunOpWaveOptions, planned: OpWavePlanned, decidedWave: OpWaveDecided): Promise<RunOpWaveResult> {
2588
2740
  const { ctx, decision } = planned;
@@ -2617,6 +2769,10 @@ async function decided(ctx: WaveContext, decision: OpWaveDecision, recordPath: s
2617
2769
  log(`Nothing in wave ${k} (${wave.name}) or after it ran: ${decision.refused.message}`);
2618
2770
  return { ...result, exitCode: CHANT_EXIT.declined };
2619
2771
  }
2772
+ if (decision.status === "refused" && decision.refused?.reason === "moved") {
2773
+ log(`Nothing in wave ${k} (${wave.name}) or after it ran: ${decision.refused.message}`);
2774
+ return { ...result, moved: [...decision.refused.runs], exitCode: CHANT_EXIT.moved };
2775
+ }
2620
2776
  if (decision.status === "refused") {
2621
2777
  log(`Nothing in wave ${k} (${wave.name}) or after it ran: the policy denied ${decision.refused?.runs.join(", ")}, and no override counts for ${decision.refused?.runs.length === 1 ? "it" : "them"}.`);
2622
2778
  return { ...result, exitCode: CHANT_EXIT.denied };
@@ -2787,7 +2943,7 @@ async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promi
2787
2943
 
2788
2944
  /** The exit code of a refused wave: 8 when its decision point refused it (#3836), 7 when the product's policy did (#3821). */
2789
2945
  function refusedExit(decision: OpWaveDecision): number {
2790
- return decision.refused?.reason === "point" ? CHANT_EXIT.declined : CHANT_EXIT.denied;
2946
+ return decision.refused?.reason === "point" ? CHANT_EXIT.declined : decision.refused?.reason === "moved" ? CHANT_EXIT.moved : CHANT_EXIT.denied;
2791
2947
  }
2792
2948
 
2793
2949
  function failed(ctx: WaveContext, line: string): RunOpWaveResult {
@@ -3836,6 +3992,8 @@ export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Pr
3836
3992
  digest: opWaveSetDigest(spec, members, extras),
3837
3993
  changes: !members.every((m) => m.empty === true),
3838
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 } : {}) })),
3839
3997
  // #4630: a pull-request wave's change set, which the pull request's own approval must cover.
3840
3998
  ...(changeSet ? { changeSet: changeSet.digest } : {}),
3841
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)", () => {
@@ -691,6 +691,17 @@ export interface OpWavesOverride {
691
691
 
692
692
  /** What happens to an approval once a wave applies under it (#3784). */
693
693
  export interface OpWavesApprovals {
694
+ /**
695
+ * Apply what the pull request previewed, or refuse. With `preview: true`
696
+ * (read at the base commit, like the policy) a merged wave compares the
697
+ * set digest it plans now with the digest the merged pull request's head
698
+ * recorded for it (`chant run wave --record-plans`), whatever its gate
699
+ * policy and approval mode, and applies only on a match. A different
700
+ * digest, or no record to compare with, refuses the wave with the moved
701
+ * code (4) unless an approval of the digest it plans now stands. Default
702
+ * false: a wave that needs no approval applies what it plans.
703
+ */
704
+ preview?: boolean;
694
705
  /**
695
706
  * Spend it. Before a wave applies under an approval it records that in
696
707
  * `_gates/<name>/applied.jsonl` on `chant/lifecycle`, and from then on the
@@ -802,8 +813,9 @@ export const OP_WAVES_APPROVAL_STATUS_VAR = "CHANT_APPROVAL_STATUS";
802
813
  * from the pull request, by its review (`pr-review`) or by its own approval
803
814
  * (`pull-request`, under the 2026-10-28 ruling).
804
815
  */
805
- export function opWavesPostsApprovalStatus(spec: Pick<OpWavesSpec, "waves">): boolean {
806
- return spec.waves.some((w) => w.approval === "pr-review" || w.approval === "pull-request");
816
+ export function opWavesPostsApprovalStatus(spec: Pick<OpWavesSpec, "waves" | "approvals">): boolean {
817
+ // `approvals.preview` compares the merged wave with the head's recorded plans, so the head must record them.
818
+ return spec.approvals?.preview === true || spec.waves.some((w) => w.approval === "pr-review" || w.approval === "pull-request");
807
819
  }
808
820
 
809
821
  /**
@@ -954,7 +966,12 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
954
966
  }
955
967
  continue;
956
968
  }
957
- if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend, approvals.quorum, approvals.reviewLedger, approvals.involved and approvals.pullRequest.`);
969
+ if (key === "preview") {
970
+ // The pull request's recorded plans are what the merged wave applies, read at base.
971
+ if (typeof value !== "boolean") throw new Error(`${where}: approvals.preview must be true or false.`);
972
+ continue;
973
+ }
974
+ if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend, approvals.preview, approvals.quorum, approvals.reviewLedger, approvals.involved and approvals.pullRequest.`);
958
975
  if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
959
976
  }
960
977
  if ((a as OpWavesApprovals).quorum?.length && (spec.point !== undefined || spec.waves.some((w) => w.point !== undefined))) {
@@ -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.58";
22
+ export const NEXT_RELEASE = "0.124.60";
@@ -10,7 +10,6 @@ import templateSchema from "./template.schema.json";
10
10
  import pkg from "../../package.json";
11
11
  import { buildReleaseCatalog } from "../lifecycle/release-catalog";
12
12
  import type { ReleaseRecord } from "../lifecycle/release-ledger";
13
- import { NEXT_RELEASE } from "../release-floors";
14
13
  import { resolveProductWords } from "../ci-product-words";
15
14
  import {
16
15
  checkTemplateRequest,
@@ -121,7 +120,7 @@ describe("schemas", () => {
121
120
  });
122
121
 
123
122
  test("the floor is the next release", () => {
124
- expect(TEMPLATE_REQUEST_FLOOR).toBe(NEXT_RELEASE);
123
+ expect(TEMPLATE_REQUEST_FLOOR).toBe("0.124.58");
125
124
  });
126
125
 
127
126
  test("the package exports ./template-request and its schemas", () => {
@@ -12,13 +12,12 @@
12
12
  */
13
13
 
14
14
  import schema from "./template-request.schema.json" with { type: "json" };
15
- import { NEXT_RELEASE } from "../release-floors";
16
15
  import { catalogVersion, type AttestationState, type CatalogComponent, type ReleaseCatalog } from "../lifecycle/release-catalog";
17
16
  import { inputKindProblem, inputRequired, isAppOutputRef, type TemplateSpec } from "./template-spec";
18
17
  import { schemaProblems } from "./validate";
19
18
 
20
19
  /** The first chant that writes and reads template-request/v1 and template.yml/v1 (#4651). */
21
- export const TEMPLATE_REQUEST_FLOOR = NEXT_RELEASE;
20
+ export const TEMPLATE_REQUEST_FLOOR = "0.124.58";
22
21
 
23
22
  /** The request document's `$schema`. */
24
23
  export const TEMPLATE_REQUEST_SCHEMA_ID: string = schema.$id;
@@ -4,10 +4,14 @@
4
4
  * and each member kind answers the reads the table says.
5
5
  */
6
6
 
7
+ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
8
+ import { tmpdir } from "node:os";
9
+ import { join } from "node:path";
7
10
  import { describe, expect, test } from "vitest";
8
11
  import { driftRecord, driftRecordLine, driftSettle, driftStart, type DriftRecord } from "../drift-record";
9
12
  import { readContractSchema } from "./conformance";
10
- import { DRIFT_CONTRACT_VERSION, DRIFT_ERROR_CODES, DRIFT_READS_BY_KIND, DRIFT_RESOURCE_KINDS, driftReadDocument } from "./drift-cli";
13
+ import { DRIFT_CONTRACT_VERSION, DRIFT_ERROR_CODES, DRIFT_READS_BY_KIND, DRIFT_RESOURCE_KINDS, DRIFT_STACK_KINDS, driftReadDocument, readWorkspaceDrift } from "./drift-cli";
14
+ import { parseArgs } from "../cli/parse-args";
11
15
  import driftSchema from "./drift.schema.json";
12
16
 
13
17
  const at = "2026-10-25T09:00:00Z";
@@ -63,3 +67,33 @@ describe("chant workspace drift's document", () => {
63
67
  expect(DRIFT_ERROR_CODES).toContain("no-drift-read");
64
68
  });
65
69
  });
70
+
71
+ describe("chant workspace drift --stack", () => {
72
+ test("is parsed beside --member and --resource", () => {
73
+ const args = parseArgs(["workspace", "drift", "--member", "shop", "--stack", "prod-eu", "--resource", "urn:x"]);
74
+ expect(args.carveStack).toBe("prod-eu");
75
+ expect(args.members).toEqual(["shop"]);
76
+ expect(parseArgs(["workspace", "drift", "--member", "shop"]).carveStack).toBeUndefined();
77
+ });
78
+
79
+ test("only a pulumi member keeps one export per stack", () => {
80
+ expect(DRIFT_STACK_KINDS).toEqual(["pulumi"]);
81
+ for (const kind of DRIFT_STACK_KINDS) expect(DRIFT_READS_BY_KIND[kind]).toBeDefined();
82
+ });
83
+
84
+ test("a member of another kind refuses it with read-unsupported before anything runs", async () => {
85
+ const root = mkdtempSync(join(tmpdir(), "drift-stack-"));
86
+ try {
87
+ mkdirSync(join(root, "infra"));
88
+ writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "infra", dir: "infra", kind: "terraform" }] }));
89
+ const answer = await readWorkspaceDrift({ cwd: root, member: "infra", stack: "prod-eu" });
90
+ expect("error" in answer && answer.error.code).toBe("read-unsupported");
91
+ expect("error" in answer && answer.error.message).toMatch(/--stack reads a stack's export from the index store.*infra is kind terraform/);
92
+ const doc = driftReadDocument("infra", answer);
93
+ const { validate } = readContractSchema("drift");
94
+ expect(validate(doc), JSON.stringify(validate.errors)).toBe(true);
95
+ } finally {
96
+ rmSync(root, { recursive: true, force: true });
97
+ }
98
+ });
99
+ });
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * `chant workspace drift [dir] --member <name> [--read <read>] [--resource
3
- * <addr>] [--env <env>] [--stream] [-o <file>]` (behold#995): one member's
3
+ * <addr>] [--stack <name>] [--env <env>] [--stream] [-o <file>]` (behold#995): one member's
4
4
  * drift, read by the engine that owns it, as chant's drift record
5
5
  * (`../drift-record.ts`, #4451).
6
6
  *
@@ -13,6 +13,14 @@
13
13
  * | `choudoufu` | `ownership` | the same, through `choudoufu live-plan -json` (and `live-ls`), or `--read plan` for live-plan with a plan beside it; `--resource <addr>` passes `choudoufu live-plan -resource=<addr>`'s stream through |
14
14
  * | `pulumi` | `refresh` | `chant lifecycle drift` in the member's reader project: the pulumi lexicon's `readDrift`, `pulumi refresh --preview-only --json --target <urn>` per resource in the checked-in export, or `plunge drift --resource <urn> --stream` for a member on plunge; `--resource <urn>` reads that URN alone (#4455) |
15
15
  *
16
+ * `--stack <name>` reads that stack's export for a `pulumi` member, from the
17
+ * index store (`refs/chant/snapshots`), where a member of several stacks
18
+ * holds one export each. Without it the member reads the export its store
19
+ * holds, which is the right one only for a member of one stack. A store with
20
+ * no export for the stack answers `no-drift-read`, naming the stack; it never
21
+ * falls back to another stack's export or the checked-in file. Any other kind
22
+ * answers `read-unsupported`.
23
+ *
16
24
  * Any other kind has no drift read and answers `no-drift-read`. A member of
17
25
  * a package's kind runs in the reader project `workspace graph` writes for it
18
26
  * (`./kind-readers.ts`), under the member's own toolchain, so chant core
@@ -111,7 +119,10 @@ export const DRIFT_RESOURCE_KINDS: readonly string[] = ["choudoufu", "pulumi"];
111
119
  const MEMBER_REFUSED_EXITS: readonly number[] = [1, 3];
112
120
 
113
121
  const USAGE =
114
- "chant workspace drift [dir] --member <name> [--read <state|plan|refresh|live-read|ownership>] [--resource <addr>] [--env <env>] [--components] [--stream] [-o <file>]";
122
+ "chant workspace drift [dir] --member <name> [--read <state|plan|refresh|live-read|ownership>] [--resource <addr>] [--stack <name>] [--env <env>] [--components] [--stream] [-o <file>]";
123
+
124
+ /** The kinds whose engine keeps one export per stack, for `--stack`. */
125
+ export const DRIFT_STACK_KINDS: readonly string[] = ["pulumi"];
115
126
 
116
127
  /** The document `workspace drift` prints: a drift document with the read contract's head. */
117
128
  export type WorkspaceDriftDocument = DriftDocument & {
@@ -127,6 +138,8 @@ export interface DriftQuery {
127
138
  member: string;
128
139
  read?: string;
129
140
  resource?: string;
141
+ /** The stack whose stored export is read (`--stack`), for a pulumi member. */
142
+ stack?: string;
130
143
  env?: string;
131
144
  components?: boolean;
132
145
  }
@@ -229,7 +242,7 @@ interface LexiconDiff {
229
242
  /** The command line the member runs. */
230
243
  function memberArgv(kind: string, query: DriftQuery, read: DriftRead): string[] {
231
244
  if (kind === "chant") return ["lifecycle", "diff", query.env!, "--live", "--json"];
232
- return ["lifecycle", "drift", ".", "--member", query.member, "--read", read, ...(query.resource !== undefined ? ["--resource", query.resource] : [])];
245
+ return ["lifecycle", "drift", ".", "--member", query.member, "--read", read, ...(query.resource !== undefined ? ["--resource", query.resource] : []), ...(query.stack !== undefined ? ["--stack", query.stack] : [])];
233
246
  }
234
247
 
235
248
  /**
@@ -255,6 +268,10 @@ export async function readWorkspaceDrift(query: DriftQuery): Promise<DriftReadRe
255
268
  if (query.resource !== undefined && !DRIFT_RESOURCE_KINDS.includes(entry.kind)) {
256
269
  throw new DriftReadFailure("resource-unsupported", `--resource reads one resource through choudoufu live-plan -resource, pulumi refresh --target or plunge drift --resource; ${query.member} is kind ${entry.kind}`);
257
270
  }
271
+ if (query.stack !== undefined && !DRIFT_STACK_KINDS.includes(entry.kind)) {
272
+ throw new DriftReadFailure("read-unsupported", `--stack reads a stack's export from the index store, which a ${DRIFT_STACK_KINDS.join(" or ")} member has; ${query.member} is kind ${entry.kind}`);
273
+ }
274
+ if (query.stack !== undefined && query.stack.trim() === "") throw new DriftReadFailure("read-unsupported", "--stack needs a stack name");
258
275
  if (entry.kind === "chant" && !query.env) throw new DriftReadFailure("env-required", `${query.member} is a chant member, read live through chant lifecycle diff <env> --live: add --env <env>`);
259
276
 
260
277
  const { registry: kinds, problems } = loadKindRegistry(declaration.pins, located.rootOnDisk);
@@ -349,6 +366,7 @@ export async function runWorkspaceDrift(ctx: CommandContext): Promise<number> {
349
366
  member: members[0],
350
367
  ...(args.driftRead !== undefined ? { read: args.driftRead } : {}),
351
368
  ...(args.resource !== undefined ? { resource: args.resource } : {}),
369
+ ...(args.carveStack !== undefined ? { stack: args.carveStack } : {}),
352
370
  ...(args.env !== undefined ? { env: args.env } : {}),
353
371
  ...(args.components ? { components: true } : {}),
354
372
  });