@intentius/chant 0.124.57 → 0.124.59

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 (163) hide show
  1. package/dist/ci-product-words.d.ts +47 -2
  2. package/dist/ci-product-words.d.ts.map +1 -1
  3. package/dist/ci-product-words.js +59 -1
  4. package/dist/ci-product.d.ts +26 -2
  5. package/dist/ci-product.d.ts.map +1 -1
  6. package/dist/ci-product.js +25 -2
  7. package/dist/cli/commands/init.d.ts +2 -0
  8. package/dist/cli/commands/init.d.ts.map +1 -1
  9. package/dist/cli/commands/init.js +1 -1
  10. package/dist/cli/handlers/build.d.ts.map +1 -1
  11. package/dist/cli/handlers/build.js +5 -1
  12. package/dist/cli/handlers/init.d.ts.map +1 -1
  13. package/dist/cli/handlers/init.js +16 -0
  14. package/dist/cli/handlers/lifecycle-drift.d.ts +2 -1
  15. package/dist/cli/handlers/lifecycle-drift.d.ts.map +1 -1
  16. package/dist/cli/handlers/lifecycle-drift.js +4 -2
  17. package/dist/cli/handlers/lock.d.ts.map +1 -1
  18. package/dist/cli/handlers/lock.js +45 -2
  19. package/dist/cli/handlers/serve.d.ts.map +1 -1
  20. package/dist/cli/handlers/serve.js +9 -0
  21. package/dist/cli/main.d.ts.map +1 -1
  22. package/dist/cli/main.js +11 -3
  23. package/dist/cli/mcp/product-tools.d.ts +40 -7
  24. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  25. package/dist/cli/mcp/product-tools.js +58 -15
  26. package/dist/cli/mcp/read-only.d.ts +2 -1
  27. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  28. package/dist/cli/mcp/read-only.js +2 -1
  29. package/dist/cli/mcp/server.d.ts +11 -0
  30. package/dist/cli/mcp/server.d.ts.map +1 -1
  31. package/dist/cli/mcp/server.js +15 -3
  32. package/dist/cli/mcp-config.d.ts +4 -1
  33. package/dist/cli/mcp-config.d.ts.map +1 -1
  34. package/dist/cli/mcp-config.js +6 -2
  35. package/dist/cli/parse-args.d.ts.map +1 -1
  36. package/dist/cli/parse-args.js +27 -0
  37. package/dist/cli/registry.d.ts +14 -0
  38. package/dist/cli/registry.d.ts.map +1 -1
  39. package/dist/components/pr-pipeline.d.ts +56 -0
  40. package/dist/components/pr-pipeline.d.ts.map +1 -1
  41. package/dist/components/pr-pipeline.js +55 -2
  42. package/dist/components/product-pipeline.d.ts +18 -1
  43. package/dist/components/product-pipeline.d.ts.map +1 -1
  44. package/dist/components/product-pipeline.js +8 -2
  45. package/dist/drift-record.d.ts +5 -0
  46. package/dist/drift-record.d.ts.map +1 -1
  47. package/dist/e2e-harness/driver.d.ts.map +1 -1
  48. package/dist/e2e-harness/driver.js +97 -0
  49. package/dist/e2e-harness/forgejo.d.ts +5 -1
  50. package/dist/e2e-harness/forgejo.d.ts.map +1 -1
  51. package/dist/e2e-harness/forgejo.js +35 -0
  52. package/dist/e2e-harness/index.d.ts +7 -0
  53. package/dist/e2e-harness/index.d.ts.map +1 -1
  54. package/dist/e2e-harness/index.js +10 -1
  55. package/dist/e2e-harness/ports.d.ts +31 -0
  56. package/dist/e2e-harness/ports.d.ts.map +1 -1
  57. package/dist/e2e-harness/scenario.d.ts.map +1 -1
  58. package/dist/e2e-harness/scenario.js +9 -5
  59. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  60. package/dist/e2e-harness/schemas/index.d.ts +22 -1
  61. package/dist/e2e-harness/schemas/index.d.ts.map +1 -1
  62. package/dist/e2e-harness/schemas/index.js +1 -1
  63. package/dist/e2e-harness/steps.d.ts.map +1 -1
  64. package/dist/e2e-harness/steps.js +4 -0
  65. package/dist/lifecycle/lock-beat.d.ts +27 -0
  66. package/dist/lifecycle/lock-beat.d.ts.map +1 -0
  67. package/dist/lifecycle/lock-beat.js +84 -0
  68. package/dist/lifecycle/resource-lock.d.ts +54 -1
  69. package/dist/lifecycle/resource-lock.d.ts.map +1 -1
  70. package/dist/lifecycle/resource-lock.js +128 -7
  71. package/dist/mcp/types.d.ts +9 -0
  72. package/dist/mcp/types.d.ts.map +1 -1
  73. package/dist/op/activities/activity-contracts.d.ts +4 -4
  74. package/dist/op/index.d.ts +1 -1
  75. package/dist/op/index.d.ts.map +1 -1
  76. package/dist/op/index.js +1 -1
  77. package/dist/op/op-waves-notify.d.ts.map +1 -1
  78. package/dist/op/op-waves-notify.js +11 -0
  79. package/dist/op/op-waves-run.d.ts +28 -1
  80. package/dist/op/op-waves-run.d.ts.map +1 -1
  81. package/dist/op/op-waves-run.js +92 -7
  82. package/dist/op/op-waves.d.ts +12 -1
  83. package/dist/op/op-waves.d.ts.map +1 -1
  84. package/dist/op/op-waves.js +9 -2
  85. package/dist/release-floors.d.ts +1 -1
  86. package/dist/release-floors.js +1 -1
  87. package/dist/template-request/index.d.ts +9 -0
  88. package/dist/template-request/index.d.ts.map +1 -0
  89. package/dist/template-request/index.js +8 -0
  90. package/dist/template-request/request-body.d.ts +21 -0
  91. package/dist/template-request/request-body.d.ts.map +1 -0
  92. package/dist/template-request/request-body.js +86 -0
  93. package/dist/template-request/template-request.d.ts +100 -0
  94. package/dist/template-request/template-request.d.ts.map +1 -0
  95. package/dist/template-request/template-request.js +149 -0
  96. package/dist/template-request/template-request.schema.json +100 -0
  97. package/dist/template-request/template-spec.d.ts +83 -0
  98. package/dist/template-request/template-spec.d.ts.map +1 -0
  99. package/dist/template-request/template-spec.js +146 -0
  100. package/dist/template-request/template.schema.json +114 -0
  101. package/dist/template-request/validate.d.ts +4 -0
  102. package/dist/template-request/validate.d.ts.map +1 -0
  103. package/dist/template-request/validate.js +21 -0
  104. package/dist/wave-runtime.mjs +298 -298
  105. package/dist/workspace/drift-cli.d.ts +13 -1
  106. package/dist/workspace/drift-cli.d.ts.map +1 -1
  107. package/dist/workspace/drift-cli.js +19 -3
  108. package/package.json +8 -1
  109. package/src/ci-product-words.test.ts +23 -0
  110. package/src/ci-product-words.ts +68 -3
  111. package/src/ci-product.ts +31 -1
  112. package/src/cli/commands/init.ts +3 -1
  113. package/src/cli/handlers/build.ts +5 -1
  114. package/src/cli/handlers/init.ts +18 -0
  115. package/src/cli/handlers/lifecycle-drift.test.ts +52 -0
  116. package/src/cli/handlers/lifecycle-drift.ts +4 -2
  117. package/src/cli/handlers/lock.ts +41 -2
  118. package/src/cli/handlers/serve.ts +9 -0
  119. package/src/cli/main.ts +11 -3
  120. package/src/cli/mcp/product-tools.test.ts +56 -1
  121. package/src/cli/mcp/product-tools.ts +66 -15
  122. package/src/cli/mcp/read-only.ts +2 -1
  123. package/src/cli/mcp/server.ts +20 -5
  124. package/src/cli/mcp-config.test.ts +52 -2
  125. package/src/cli/mcp-config.ts +6 -3
  126. package/src/cli/parse-args.ts +19 -0
  127. package/src/cli/registry.ts +14 -0
  128. package/src/components/pr-pipeline.ts +87 -2
  129. package/src/components/product-actions.test.ts +76 -0
  130. package/src/components/product-pipeline.ts +21 -2
  131. package/src/drift-record.ts +5 -0
  132. package/src/e2e-harness/driver.test.ts +163 -0
  133. package/src/e2e-harness/driver.ts +86 -1
  134. package/src/e2e-harness/forgejo.ts +42 -1
  135. package/src/e2e-harness/index.ts +11 -1
  136. package/src/e2e-harness/ports.ts +33 -0
  137. package/src/e2e-harness/scenario.ts +8 -6
  138. package/src/e2e-harness/schemas/README.md +11 -2
  139. package/src/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  140. package/src/e2e-harness/schemas/index.ts +5 -1
  141. package/src/e2e-harness/schemas.test.ts +44 -1
  142. package/src/e2e-harness/steps.ts +4 -0
  143. package/src/lifecycle/lock-beat.ts +99 -0
  144. package/src/lifecycle/resource-lock-liveness.test.ts +289 -0
  145. package/src/lifecycle/resource-lock.ts +143 -8
  146. package/src/mcp/types.ts +9 -0
  147. package/src/op/index.ts +1 -0
  148. package/src/op/op-waves-notify.ts +11 -0
  149. package/src/op/op-waves-preview.test.ts +167 -0
  150. package/src/op/op-waves-run.ts +116 -8
  151. package/src/op/op-waves.ts +20 -3
  152. package/src/release-floors.ts +1 -1
  153. package/src/template-request/__fixtures__/request-body.md +41 -0
  154. package/src/template-request/index.ts +8 -0
  155. package/src/template-request/request-body.ts +91 -0
  156. package/src/template-request/template-request.schema.json +100 -0
  157. package/src/template-request/template-request.test.ts +315 -0
  158. package/src/template-request/template-request.ts +234 -0
  159. package/src/template-request/template-spec.ts +176 -0
  160. package/src/template-request/template.schema.json +114 -0
  161. package/src/template-request/validate.ts +28 -0
  162. package/src/workspace/drift-cli.test.ts +35 -1
  163. 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 { NEXT_RELEASE } from "../release-floors";
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";
@@ -357,6 +358,8 @@ export interface OpWaveDecision {
357
358
  waitingSince?: string;
358
359
  /** While waiting: the newest approval of this gate for another digest, which the plans moved away from. */
359
360
  mismatch?: GateDigestMismatch;
361
+ /** Under `approvals.preview` at base: what the merged pull request's head recorded for this wave, and how the plans now compare with it. */
362
+ preview?: OpWavePreview;
360
363
  /**
361
364
  * Why a `refused` wave applies nothing: the runs the policy denied, and
362
365
  * whether an override stands for an earlier plan or other rules (#3821,
@@ -364,7 +367,7 @@ export interface OpWaveDecision {
364
367
  * it does not pass on (#3836, exit 8), with every run and the `message`.
365
368
  */
366
369
  refused?: {
367
- reason: "policy" | "override-moved" | "point";
370
+ reason: "policy" | "override-moved" | "point" | "moved";
368
371
  runs: string[];
369
372
  message?: string;
370
373
  /** Where the plans file said its overriders come from (#3848), when it did. */
@@ -391,6 +394,28 @@ export interface OpWaveDecision {
391
394
  ciPolicySource?: ResolvedGatePolicySource;
392
395
  }
393
396
 
397
+ /**
398
+ * The plans the merged pull request previewed for a wave, against the plans
399
+ * the wave made now. `matched`: the same set digest, so the wave applies
400
+ * what the pull request showed. `moved`: the head recorded another digest,
401
+ * so a record moved since. `unrecorded`: nothing was recorded to compare
402
+ * with (no merged pull request, no record for its head, or none for this
403
+ * wave).
404
+ */
405
+ export interface OpWavePreview {
406
+ status: "matched" | "moved" | "unrecorded";
407
+ /** The pull request that merged the applied commit. */
408
+ pr?: number;
409
+ /** Its head commit, which `--record-plans` recorded the plans at. */
410
+ head?: string;
411
+ /** The digest the head recorded for this wave. */
412
+ recorded?: string;
413
+ /** Why the plans do not match, for `moved` and `unrecorded`. */
414
+ reason?: string;
415
+ /** Set when an approval of the digest planned now let a wave that did not match apply. */
416
+ approvedAnyway?: true;
417
+ }
418
+
394
419
  /**
395
420
  * What an apply call writes to `CHANT_APPLY_OUTCOME` when it applied nothing
396
421
  * for a reason that is not a failure (#3821). `stood-down`: a newer run (a
@@ -584,6 +609,8 @@ export interface OpWaveBaseRules {
584
609
  holdsRefused?: string;
585
610
  /** `approvals.pullRequest.gate` at base (#4550): the pull request's gate a `pull-request` wave takes its approval from. */
586
611
  pullRequestGate?: string;
612
+ /** `approvals.preview` at base: the wave applies what the merged pull request's head recorded, or refuses (exit 4). */
613
+ preview?: boolean;
587
614
  }
588
615
 
589
616
  const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -616,7 +643,7 @@ export function readOpWavePolicy(
616
643
  const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
617
644
  const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
618
645
  // #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) };
646
+ 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
647
  const wave = spec.waves.find((w) => w.name === name);
621
648
  if (!wave) return { ...absent, spend, neverOverMcp, ...asks };
622
649
  const policy = wave.gate ?? "always";
@@ -680,6 +707,9 @@ function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWav
680
707
  return { point: opWavePointAt(spec, name)! };
681
708
  }
682
709
 
710
+ /** 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;
712
+
683
713
  /** The first chant whose op entry exports {@link opWavePlanPath} (terragucci#1304). */
684
714
  export const OP_WAVE_PLAN_PATH_FLOOR = "0.124.56";
685
715
 
@@ -1935,7 +1965,7 @@ function opWaveRunStatus(result: RunOpWaveResult): { status: OpRunRecordInput["s
1935
1965
  case CHANT_EXIT.waiting:
1936
1966
  return { status: d?.point?.question ? "waiting" : "gated" };
1937
1967
  case CHANT_EXIT.moved:
1938
- return { status: "fail", failure: { code: "moved", reason: `plans moved since the decision: ${result.moved.join(", ") || "(none named)"}` } };
1968
+ 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
1969
  case CHANT_EXIT.denied:
1940
1970
  return { status: "fail", failure: { code: "denied", reason: d?.refused?.message ?? `the policy denied ${d?.refused?.runs.join(", ") ?? "a run"}, and no override counts` } };
1941
1971
  case CHANT_EXIT.declined:
@@ -2241,12 +2271,12 @@ function writeOpWaveOutcome(options: RunOpWaveOptions, dir: string, result: RunO
2241
2271
  const otherwise: WaveMemberOutcome["status"] =
2242
2272
  result.exitCode === 0 ? (options.decide ? "decided" : "unchanged")
2243
2273
  : result.exitCode === CHANT_EXIT.waiting ? "waiting"
2244
- : result.exitCode === CHANT_EXIT.denied || result.exitCode === CHANT_EXIT.declined ? "refused"
2274
+ : result.exitCode === CHANT_EXIT.denied || result.exitCode === CHANT_EXIT.declined || result.decision?.refused?.reason === "moved" ? "refused"
2245
2275
  : result.exitCode >= CHANT_EXIT.moved && result.exitCode <= CHANT_EXIT.superseded ? "not-applied"
2246
2276
  : "failed";
2247
2277
  for (const t of targets) {
2248
2278
  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 };
2279
+ 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
2280
  }
2251
2281
  }
2252
2282
  const part = { ...(options.group !== undefined ? { group: options.group } : {}), ...(options.share !== undefined ? { share: options.share } : {}) };
@@ -2354,7 +2384,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
2354
2384
  result.decision = decision;
2355
2385
  ctx.gateRule = { approval: decision.approval, base: decision.base, neverOverMcp: decision.neverOverMcp === true };
2356
2386
  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());
2387
+ 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
2388
  return { end: { ...result, exitCode: decision.status === "refused" ? refusedExit(decision) : CHANT_EXIT.waiting } };
2359
2389
  }
2360
2390
  // The share runs the hooks its deciding job read at base, around its own slice.
@@ -2560,12 +2590,26 @@ async function decideOpWave(
2560
2590
  if (was.overridesSpentAt) decision.overridesSpentAt = was.overridesSpentAt;
2561
2591
  }
2562
2592
  if (members.some((m) => m.denied && !m.override)) await settleDenials(ctx, decision, overriders, overridersSource);
2593
+ // `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
+ let unseen = false;
2595
+ if (planned.rules.preview && !kept && decision.status !== "refused") {
2596
+ const seen = await previewOf(options, ctx, digest);
2597
+ 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
+ decision.preview = seen.preview;
2599
+ 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})`);
2601
+ else log(`wave ${k} (${wave.name}): ${seen.preview.reason}`);
2602
+ }
2563
2603
  if (kept && was.status === "approved" && decision.status !== "refused") {
2564
2604
  // #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
2605
  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
2606
  decision.status = "approved";
2567
2607
  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);
2608
+ } else if (decision.status !== "refused" && (unseen || opWaveNeedsApproval(policy, members) || holds.length > 0)) {
2609
+ await settleGate(options, ctx, decision);
2610
+ // Plans nobody previewed apply only under an approval of these very plans, whatever the gate policy says.
2611
+ if (unseen) refuseUnseen(ctx, decision);
2612
+ }
2569
2613
  const code = await decided(ctx, decision, recordPath);
2570
2614
  if (code.exitCode !== 0) return { end: code };
2571
2615
  log(
@@ -2583,6 +2627,66 @@ async function decideOpWave(
2583
2627
  return { go: { runs: wave.runs, earlierHolds: [], recordPath } };
2584
2628
  }
2585
2629
 
2630
+ /**
2631
+ * Compare the wave's set digest with the one the merged pull request's head
2632
+ * recorded for it (`--record-plans`): the plans its reviewers saw. The pull
2633
+ * request is the one the forge says produced the applied commit. Resolves to
2634
+ * `error` only when the forge or the ledger cannot be read, which fails the
2635
+ * wave: a missing answer never stands in for a match.
2636
+ */
2637
+ async function previewOf(options: RunOpWaveOptions, ctx: WaveContext, digest: string): Promise<{ preview: OpWavePreview } | { error: string }> {
2638
+ const { spec, k, cwd } = ctx;
2639
+ const review = await import("./gate-review");
2640
+ const head = options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim();
2641
+ let merged: MergedReview | null;
2642
+ try {
2643
+ merged = await (options.reviews ?? review.reviewSourceFromEnv()).mergedReview(head);
2644
+ } catch (err) {
2645
+ return { error: `the merged pull request could not be read from the forge (${err instanceof Error ? err.message : String(err)})` };
2646
+ }
2647
+ if (!merged) return { preview: { status: "unrecorded", reason: `no merged pull request produced ${head.slice(0, 12)}, so no plans were previewed for it` } };
2648
+ let plans: HeadPlans | null;
2649
+ try {
2650
+ plans = await (options.headPlans ?? ((name, h) => readHeadPlans(name, h, cwd)))(spec.name, merged.head);
2651
+ } catch (err) {
2652
+ return { error: `the plans recorded for #${merged.pr} could not be read (${err instanceof Error ? err.message : String(err)})` };
2653
+ }
2654
+ const seen = { pr: merged.pr, head: merged.head };
2655
+ const recorded = plans?.waves.find((w) => w.wave === k)?.digest;
2656
+ if (recorded === undefined) {
2657
+ 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
+ }
2659
+ if (!samePlanDigest(recorded, digest)) {
2660
+ return {
2661
+ preview: {
2662
+ status: "moved",
2663
+ ...seen,
2664
+ 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}`,
2666
+ },
2667
+ };
2668
+ }
2669
+ return { preview: { status: "matched", ...seen, recorded } };
2670
+ }
2671
+
2672
+ /**
2673
+ * The gate was asked about plans the pull request did not preview. An
2674
+ * approval of exactly these plans lets the wave apply, since a person saw
2675
+ * them; with none, the wave is refused as moved (exit 4) and the approval
2676
+ * that would let it through is named.
2677
+ */
2678
+ function refuseUnseen(ctx: WaveContext, decision: OpWaveDecision): void {
2679
+ const preview = decision.preview!;
2680
+ if (decision.status === "approved") {
2681
+ preview.approvedAnyway = true;
2682
+ ctx.log(`wave ${ctx.k} (${ctx.wave.name}): ${preview.reason}; it applies under the approval of ${decision.digest} by ${decision.approvedBy}`);
2683
+ return;
2684
+ }
2685
+ const how = decision.approve ? ` Approve these plans to apply them: ${decision.approve}` : "";
2686
+ decision.status = "refused";
2687
+ decision.refused = { reason: "moved", runs: decision.members.map((m) => m.member).sort(), message: `${preview.reason}.${how}` };
2688
+ }
2689
+
2586
2690
  /** Apply a decided wave, or a share's unmoved runs (exit 4 when any moved). */
2587
2691
  async function applyOpWave(options: RunOpWaveOptions, planned: OpWavePlanned, decidedWave: OpWaveDecided): Promise<RunOpWaveResult> {
2588
2692
  const { ctx, decision } = planned;
@@ -2617,6 +2721,10 @@ async function decided(ctx: WaveContext, decision: OpWaveDecision, recordPath: s
2617
2721
  log(`Nothing in wave ${k} (${wave.name}) or after it ran: ${decision.refused.message}`);
2618
2722
  return { ...result, exitCode: CHANT_EXIT.declined };
2619
2723
  }
2724
+ if (decision.status === "refused" && decision.refused?.reason === "moved") {
2725
+ log(`Nothing in wave ${k} (${wave.name}) or after it ran: ${decision.refused.message}`);
2726
+ return { ...result, moved: [...decision.refused.runs], exitCode: CHANT_EXIT.moved };
2727
+ }
2620
2728
  if (decision.status === "refused") {
2621
2729
  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
2730
  return { ...result, exitCode: CHANT_EXIT.denied };
@@ -2787,7 +2895,7 @@ async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promi
2787
2895
 
2788
2896
  /** The exit code of a refused wave: 8 when its decision point refused it (#3836), 7 when the product's policy did (#3821). */
2789
2897
  function refusedExit(decision: OpWaveDecision): number {
2790
- return decision.refused?.reason === "point" ? CHANT_EXIT.declined : CHANT_EXIT.denied;
2898
+ return decision.refused?.reason === "point" ? CHANT_EXIT.declined : decision.refused?.reason === "moved" ? CHANT_EXIT.moved : CHANT_EXIT.denied;
2791
2899
  }
2792
2900
 
2793
2901
  function failed(ctx: WaveContext, line: string): RunOpWaveResult {
@@ -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.57";
22
+ export const NEXT_RELEASE = "0.124.59";
@@ -0,0 +1,41 @@
1
+ ### terragucci request: app `orders` from bucket
2
+
3
+ | | |
4
+ | --- | --- |
5
+ | Template | `acme/bucket/aws` |
6
+ | Version | `1.0.0` |
7
+ | Requested by | `alice` |
8
+ | Claimed by (as given by the client; the forge does not vouch for it) | `bob` |
9
+ | Through | an agent over MCP |
10
+
11
+ | Input | Value |
12
+ | --- | --- |
13
+ | `bucket_name` | `"orders-data"` |
14
+ | `readers` | `["svc-a","svc-b"]` |
15
+ | `tags` | `{"team":"pay\|ments"}` |
16
+
17
+ Nothing was applied or approved. This pull request only adds files; it is planned like any other, and a person reviews and merges it.
18
+
19
+ ```json https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json
20
+ {
21
+ "$schema": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json",
22
+ "contract": 1,
23
+ "kind": "app",
24
+ "template": "acme/bucket/aws",
25
+ "version": "1.0.0",
26
+ "app": "orders",
27
+ "inputs": {
28
+ "bucket_name": "orders-data",
29
+ "tags": {
30
+ "team": "pay|ments"
31
+ },
32
+ "readers": [
33
+ "svc-a",
34
+ "svc-b"
35
+ ]
36
+ },
37
+ "requestedBy": "alice",
38
+ "claimedBy": "bob",
39
+ "via": "mcp"
40
+ }
41
+ ```
@@ -0,0 +1,8 @@
1
+ /**
2
+ * `@intentius/chant/template-request` (#4651): the template request
3
+ * document (template-request/v1), template.yml/v1 with its engine-neutral
4
+ * input kinds, the refusals, the branch and the pull request body.
5
+ */
6
+ export * from "./template-spec";
7
+ export * from "./template-request";
8
+ export * from "./request-body";
@@ -0,0 +1,91 @@
1
+ /**
2
+ * The pull request body for a template request (#4651), and the read that
3
+ * recovers the request from it. The body names the template, the version,
4
+ * each input on its own row, the requester (and the claimed requester, when
5
+ * the client names one) and where the request came from,
6
+ * and says that nothing was applied or approved. The request itself follows
7
+ * in a fenced block whose info string is `json` and the schema id, so behold
8
+ * and an audit read it from the pull request without a second file.
9
+ */
10
+
11
+ import { activeProductWords, type CiProductWords } from "../ci-product-words";
12
+ import { TEMPLATE_REQUEST_SCHEMA_ID, templateName, validateTemplateRequest, type TemplateRequest, type TemplateRequestVia } from "./template-request";
13
+
14
+ const VIA: Record<TemplateRequestVia, string> = {
15
+ form: "the request form",
16
+ mcp: "an agent over MCP",
17
+ cli: "the command line",
18
+ };
19
+
20
+ /** Text in a table cell's code span, with `|` escaped so the row holds and a fence longer than any backticks inside. */
21
+ function code(text: string): string {
22
+ const escaped = text.replace(/\|/g, "\\|").replace(/\n/g, " ");
23
+ const ticks = Math.max(0, ...[...escaped.matchAll(/`+/g)].map((m) => m[0].length));
24
+ const fence = "`".repeat(ticks + 1);
25
+ return ticks > 0 ? `${fence} ${escaped} ${fence}` : `${fence}${escaped}${fence}`;
26
+ }
27
+
28
+ /** A fence longer than any run of backticks in `text`, at least three. */
29
+ function fenceFor(text: string): string {
30
+ const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
31
+ return "`".repeat(Math.max(3, longest + 1));
32
+ }
33
+
34
+ /** The request's pull request body, in the product's words (default: the active ones). */
35
+ export function requestBody(request: TemplateRequest, words: CiProductWords = activeProductWords()): string {
36
+ const what = request.kind === "addon" && request.addon !== undefined ? `add-on ${code(request.addon)} for app ${code(request.app)}` : `app ${code(request.app)}`;
37
+ const lines: string[] = [
38
+ `### ${words.product} request: ${what} from ${templateName(request.template)}`,
39
+ "",
40
+ "| | |",
41
+ "| --- | --- |",
42
+ `| Template | ${code(request.template)} |`,
43
+ `| Version | ${code(request.version)} |`,
44
+ `| Requested by | ${code(request.requestedBy)} |`,
45
+ ...(request.claimedBy !== undefined ? [`| Claimed by (as given by the client; the forge does not vouch for it) | ${code(request.claimedBy)} |`] : []),
46
+ `| Through | ${VIA[request.via]} |`,
47
+ "",
48
+ ];
49
+ const names = Object.keys(request.inputs).sort();
50
+ if (names.length > 0) {
51
+ lines.push("| Input | Value |", "| --- | --- |");
52
+ for (const name of names) lines.push(`| ${code(name)} | ${code(JSON.stringify(request.inputs[name]) ?? "null")} |`);
53
+ } else {
54
+ lines.push("The request gives no inputs; every input takes its default.");
55
+ }
56
+ const [, applied] = words.verbs.apply;
57
+ const [, planned] = words.verbs.plan;
58
+ lines.push(
59
+ "",
60
+ `Nothing was ${applied} or approved. This pull request only adds files; it is ${planned} like any other, and a person reviews and merges it.`,
61
+ "",
62
+ );
63
+ const json = JSON.stringify(request, null, 2);
64
+ const fence = fenceFor(json);
65
+ lines.push(`${fence}json ${TEMPLATE_REQUEST_SCHEMA_ID}`, json, fence, "");
66
+ return lines.join("\n");
67
+ }
68
+
69
+ /**
70
+ * The request a pull request body carries: the first fenced block whose info
71
+ * string is `json` and the template-request/v1 schema id, parsed and
72
+ * checked against the schema. Undefined when the body has no such block, or
73
+ * the block is not a valid request.
74
+ */
75
+ export function parseRequestBody(body: string): TemplateRequest | undefined {
76
+ const lines = body.replace(/\r\n/g, "\n").split("\n");
77
+ for (let i = 0; i < lines.length; i++) {
78
+ const open = /^(`{3,})json[ \t]+(\S+)[ \t]*$/.exec(lines[i]!);
79
+ if (!open || open[2] !== TEMPLATE_REQUEST_SCHEMA_ID) continue;
80
+ const fence = open[1]!;
81
+ const end = lines.findIndex((l, j) => j > i && l.trimEnd() === fence);
82
+ if (end < 0) return undefined;
83
+ try {
84
+ const doc: unknown = JSON.parse(lines.slice(i + 1, end).join("\n"));
85
+ return validateTemplateRequest(doc).length === 0 ? (doc as TemplateRequest) : undefined;
86
+ } catch {
87
+ return undefined;
88
+ }
89
+ }
90
+ return undefined;
91
+ }
@@ -0,0 +1,100 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json",
4
+ "title": "chant template request",
5
+ "description": "A request for an app, or an add-on to an app, made from one version of a template in a release catalog, version 1 of its contract. A product turns it into a pull request on the branch requestBranch names, with requestBody as the body; the body carries this document in a fenced block whose info string is `json` and this schema's id, so a reader recovers it from the pull request alone. checkTemplateRequest refuses a request against the catalog and the version's template.yml (template.schema.json). Readers ignore fields they do not know; a field is only ever added within a version.",
6
+ "type": "object",
7
+ "required": [
8
+ "$schema",
9
+ "contract",
10
+ "kind",
11
+ "template",
12
+ "version",
13
+ "app",
14
+ "inputs",
15
+ "requestedBy",
16
+ "via"
17
+ ],
18
+ "properties": {
19
+ "$schema": {
20
+ "const": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json"
21
+ },
22
+ "contract": {
23
+ "const": 1
24
+ },
25
+ "kind": {
26
+ "enum": [
27
+ "app",
28
+ "addon"
29
+ ],
30
+ "description": "app: a new app. addon: an add-on to the app named in `app`, which must exist."
31
+ },
32
+ "template": {
33
+ "type": "string",
34
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$",
35
+ "description": "The template's address, such as `acme/bucket/aws` (namespace, name, system). The branch uses its name: the second-to-last segment of an address with three or more, else the last."
36
+ },
37
+ "version": {
38
+ "type": "string",
39
+ "minLength": 1,
40
+ "description": "The version in the catalog, or its digest for a release that names no version."
41
+ },
42
+ "app": {
43
+ "type": "string",
44
+ "pattern": "^[a-z][a-z0-9-]{0,39}$",
45
+ "description": "The app's name: a lowercase letter, then up to 39 lowercase letters, digits and -."
46
+ },
47
+ "addon": {
48
+ "type": "string",
49
+ "pattern": "^[a-z][a-z0-9-]{0,39}$",
50
+ "description": "For kind addon: the add-on's name, with the same rule as `app`."
51
+ },
52
+ "inputs": {
53
+ "type": "object",
54
+ "description": "The values given, by input name. An input left out takes its default. A sensitive input is never here. In an add-on request, a string `app.<output>` names an output of the app's module, for an input of any kind; the engine's renderer resolves it. In an app request it is a plain string and is checked against the input's kind.",
55
+ "additionalProperties": true
56
+ },
57
+ "requestedBy": {
58
+ "type": "string",
59
+ "minLength": 1,
60
+ "description": "Who asked, as the forge vouches for it: the login of the run's actor, a person or the identity an agent runs as."
61
+ },
62
+ "claimedBy": {
63
+ "type": "string",
64
+ "minLength": 1,
65
+ "description": "The person the client says filled the form or asked the agent, when it names one. The forge does not vouch for it, so a reader shows it as claimed, next to requestedBy."
66
+ },
67
+ "via": {
68
+ "enum": [
69
+ "form",
70
+ "mcp",
71
+ "cli"
72
+ ],
73
+ "description": "Where the request came from: a form, an agent over MCP, or the command line."
74
+ }
75
+ },
76
+ "allOf": [
77
+ {
78
+ "if": {
79
+ "properties": {
80
+ "kind": {
81
+ "const": "addon"
82
+ }
83
+ }
84
+ },
85
+ "then": {
86
+ "properties": {
87
+ "addon": true
88
+ },
89
+ "required": [
90
+ "addon"
91
+ ]
92
+ },
93
+ "else": {
94
+ "properties": {
95
+ "addon": false
96
+ }
97
+ }
98
+ }
99
+ ]
100
+ }