@intentius/chant 0.124.31 → 0.124.33

package/src/pr-loop.ts

@@ -28,6 +28,16 @@
  * and decides the gate against the new digest. The same plan applies; a moved
  * plan stops with both digests named and nothing applied.
  *
+ * ## A gate per wave on merge
+ *
+ * With `--wave-gate <gate>` (#4003) the apply runs a wave at a time, and
+ * plans each wave after the one before it applied. Wave 1 applies under the
+ * pull request's approval. A later wave whose new plan the approved change
+ * set covers (`planCoveredBy`) applies under that approval too; one whose
+ * plan moved waits at `<gate>-wave-<k>`, under the same op, for an approval
+ * of its new plan. The report's `waves` says which wave applied under which
+ * approval.
+ *
  * ## Inside a workspace member
  *
  * Each workspace member that generates the pipeline (#3465) runs its own
@@ -49,6 +59,18 @@ export const PR_REPORT_CONTRACT = 1;
 /** The first chant whose report can carry `deployedOutputs` (#4104). */
 export const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
 
+/** The first chant whose report can carry `waveGate` and `waves` (#4003). */
+export const PR_REPORT_WAVES_FLOOR = "0.124.32";
+/**
+ * The first chant whose report can carry `plannedOutputs`, `rounds`, a
+ * member's `unknownInputs`, `buildInputs`, `round` and `held`, and the `waiting` statuses
+ * (#3999).
+ */
+export const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
+
+/** The chant that writes the `record` stage and the `recorded` status (#4168 step 1). */
+export const PR_REPORT_RECORD_FLOOR = "0.124.33";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -60,6 +82,16 @@ export function prOp(pr: number, member?: string): string {
   return member ? `pr-${pr}-${member}` : `pr-${pr}`;
 }
 
+/**
+ * The gate a round of an apply waits on (#3999): the pull request's own
+ * gate for the first, and `<gate>-round-<n>` for each one planned after an
+ * upstream applied. A workspace's `identity.gates` entry for `gate` covers
+ * every round.
+ */
+export function prRoundGate(gate: string, round: number): string {
+  return round <= 1 ? gate : `${gate}-round-${round}`;
+}
+
 /** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
 export const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
 
@@ -68,11 +100,14 @@ export function prNoteMarker(env: string, member?: string): string {
   return member ? `<!-- chant-pr:${env}:${member} -->` : `<!-- chant-pr:${env} -->`;
 }
 
-/** The status contexts the two stages set on the commit. */
-export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply" } as const;
+/** The status contexts the stages set on the commit. */
+export const PR_STATUS_CONTEXTS = { plan: "chant/plan", apply: "chant/apply", record: "chant/record" } as const;
+
+/** A pull-request loop stage: plan on the pull request, then record (#4168) or, opted in, apply on merge. */
+export type PrStage = keyof typeof PR_STATUS_CONTEXTS;
 
 /** A stage's status context: `chant/plan`, or `chant/plan/<member>` for a workspace member's pipeline. */
-export function prStatusContext(stage: "plan" | "apply", member?: string): string {
+export function prStatusContext(stage: PrStage, member?: string): string {
   return member ? `${PR_STATUS_CONTEXTS[stage]}/${member}` : PR_STATUS_CONTEXTS[stage];
 }
 
@@ -95,7 +130,13 @@ export type PrMemberStatus =
   /** The apply failed. */
   | "failed"
   /** Not applied because a member it depends on failed. */
-  | "blocked";
+  | "blocked"
+  /**
+   * Apply stage (#3999): held back because its plan read an upstream output
+   * that applied as another value, or was known only after apply. It waits
+   * on an approval of the plan the apply made for it afterwards (`rounds`).
+   */
+  | "waiting";
 
 export interface PrMember {
   /** The member's name in the change set: a root, for a terraform-family step. */
@@ -110,9 +151,48 @@ export interface PrMember {
   /**
    * Components this one depends on whose outputs changed when they applied
    * (apply stage). Its applied plan read the values from before, so the next
-   * run plans it again.
+   * run plans it again. Not written since #3999, which holds such a member
+   * back and plans it again in the same apply (`held`, `round`).
    */
   inputsMoved?: string[];
+  /**
+   * The upstream outputs its plan read that the change's plans could not
+   * say (#3999), as `<component>.<output>`, sorted: known only after that
+   * upstream applies. The approval does not cover what this member does
+   * with them; the apply plans it again once they are known.
+   */
+  unknownInputs?: string[];
+  /**
+   * The published artifact identities its plan read from a build in the
+   * same change (#3999), as `<component>.publish.<field>`, sorted: an image
+   * digest, say. Known only after the build runs, but never approved again:
+   * the build's provenance and attestation bind the digest, so the member
+   * applies without a later round.
+   */
+  buildInputs?: string[];
+  /** Apply stage (#3999): the round whose plan it applied or waits on, when not the first. */
+  round?: number;
+  /** Apply stage (#3999): why the first round's plan did not apply. */
+  held?: string;
+}
+
+/** A round of plans an apply made after an upstream applied (#3999), the report's `rounds`. */
+export interface PrRound {
+  /** 2 for the first plan made after an upstream applied, and on. */
+  round: number;
+  /** The gate it waits on: {@link prRoundGate}. */
+  gate: string;
+  /** The change-set digest of what the round planned. What its gate binds. */
+  digest: string;
+  /** The components planned again, in apply order. */
+  components: string[];
+  approval: PrApproval;
+  /** `waiting`: no approval stands for `digest`. `plan-failed`: a member failed to plan, so the round did not apply. */
+  status: "applied" | "failed" | "waiting" | "plan-failed";
+  /** With `waiting`: why an approval that stands does not count (`--require-review`). */
+  message?: string;
+  /** The change-set document the round planned. */
+  changeSet: ChangeSetDocument;
 }
 
 /** Where the approval stands for the planned digest. */
@@ -133,6 +213,12 @@ export interface PrApproval {
 export type PrStatus =
   /** Plan stage: every member planned. */
   | "planned"
+  /**
+   * Record stage (#4168): every member planned on the merged commit and the
+   * plan is kept with the merge record. Nothing applied; `approval` says
+   * whether the plan is the one approved.
+   */
+  | "recorded"
   /** Plan stage: a member failed to plan. Apply stage: the same, so nothing applied. */
   | "plan-failed"
   /** Nothing the change touches is deployed by a component. */
@@ -141,8 +227,19 @@ export type PrStatus =
   | "applied"
   /** Apply stage: a member failed to apply. Its dependents did not run. */
   | "failed"
+  /**
+   * Apply stage with `--wave-gate` and `--wave` (#4003): this wave applied,
+   * and a later wave of the change is still to run.
+   */
+  | "wave-applied"
   /** Apply stage: nothing applied, see `refusal`. */
-  | "refused";
+  | "refused"
+  /**
+   * Apply stage (#3999): the approved plans applied, except members held
+   * back after an upstream applied. They wait on the approval of the plan
+   * the last of `rounds` made.
+   */
+  | "waiting";
 
 /** Why an apply refused. */
 export type PrRefusal =
@@ -152,8 +249,45 @@ export type PrRefusal =
   | "plan-changed"
   /** The approval names someone who has not approved the pull request on the forge. */
   | "not-a-reviewer"
+  /** The approval names the pull request's author, or an author or committer of one of its commits (#4000). */
+  | "author-approved"
   /** No pull request merged this commit, so there is no approval to read. */
-  | "no-pull-request";
+  | "no-pull-request"
+  /** `--wave-gate` (#4003): the wave's new plan is not one the pull request approved, and no approval stands for it. */
+  | "wave-not-approved"
+  /** `--wave-gate`: an approval of the wave's gate stands for another digest, so its plan moved since. */
+  | "wave-plan-changed"
+  /** `--wave-gate` with `--wave <k>`: an earlier wave has work left, or no record says it applied. */
+  | "earlier-wave";
+
+/**
+ * One wave of an apply with `--wave-gate` (#4003): what it planned, where it
+ * got to, and which approval it applied or waits under.
+ */
+export interface PrWave {
+  /** 1-based, from the derivation (`selection.waves`). */
+  wave: number;
+  /** The components planned in it on the run that reached it. */
+  components: string[];
+  /** `applied`; `failed` or `plan-failed`; or `waiting` at its gate. */
+  status: "applied" | "failed" | "plan-failed" | "waiting";
+  /**
+   * `pull-request`: the approved change set covers the wave's plan, so it
+   * applies under the pull request's approval. `wave`: its plan moved, so it
+   * needs an approval of its own gate.
+   */
+  approval: "pull-request" | "wave";
+  /** The gate it applied or waits under: the pull request's, or `<wave gate>-wave-<k>`. */
+  gate: string;
+  /** The digest that gate binds: the pull request's change set, or the wave's new plan. */
+  digest: string;
+  /** Who approved that digest. */
+  approvedBy?: string[];
+  /** Waiting: an approval of the wave's gate stands for this other digest. */
+  approved?: string;
+  /** Why the approved change set does not cover the wave's plan, one line per member. */
+  moved?: string[];
+}
 
 /**
  * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
@@ -162,7 +296,7 @@ export type PrRefusal =
 export interface PrReport {
   $schema: typeof PR_REPORT_SCHEMA_ID;
   contract: typeof PR_REPORT_CONTRACT;
-  stage: "plan" | "apply";
+  stage: PrStage;
   /** The pull or merge request number, when known. */
   pr: number | null;
   env: string;
@@ -194,7 +328,28 @@ export interface PrReport {
    * {@link PR_REPORT_DEPLOYED_OUTPUTS_FLOOR}.
    */
   deployedOutputs?: Record<string, string[]>;
+  /**
+   * Per dependency in the change that a member was planned against (#3999),
+   * the names of the outputs its plan knows, sorted. An output it reads that
+   * is not here is known only after apply (a member's `unknownInputs`).
+   * Absent when no member read one. Added within contract 1 by chant
+   * {@link PR_REPORT_PLANNED_OUTPUTS_FLOOR}.
+   */
+  plannedOutputs?: Record<string, string[]>;
+  /**
+   * Apply stage (#3999): the rounds planned after an upstream applied, in
+   * order, each with its own gate and digest. Absent when nothing was held.
+   */
+  rounds?: PrRound[];
   approval: PrApproval;
+  /**
+   * The wave gate's base name with `--wave-gate` (#4003): wave k waits on
+   * `<waveGate>-wave-<k>` when its plan moved. Added within contract 1 by
+   * chant {@link PR_REPORT_WAVES_FLOOR}.
+   */
+  waveGate?: string;
+  /** With `waveGate`: each wave reached so far, in order. */
+  waves?: PrWave[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -252,6 +407,7 @@ const STATUS_WORDS: Record<PrMemberStatus, string> = {
   applied: "applied",
   failed: "apply failed",
   blocked: "blocked",
+  waiting: "waiting on its new plan",
 };
 
 function headline(report: PrReport): string {
@@ -262,15 +418,61 @@ function headline(report: PrReport): string {
       return "Nothing to plan: no component deploys what this change touches.";
     case "planned":
       return `Planned ${members}.`;
+    case "recorded":
+      return `Recorded the plan of ${members} on merge. Nothing applied: a release that carries this commit deploys it.`;
     case "plan-failed":
       return `Planning failed for ${report.members.filter((m) => m.status === "plan-failed").length} of ${members}, so nothing can apply.`;
     case "applied":
       return `Applied ${members}.`;
     case "failed":
       return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
-    case "refused":
-      return "The apply refused.";
+    case "wave-applied": {
+      const applied = (report.waves ?? []).filter((w) => w.status === "applied").map((w) => w.wave);
+      const total = report.selection.waves.length;
+      return `Applied wave ${applied.at(-1) ?? "?"} of ${total}. The next wave runs in its own job.`;
+    }
+    case "refused": {
+      const waiting = report.waves?.find((w) => w.status === "waiting");
+      return waiting ? `Wave ${waiting.wave} waits at its gate ${code(waiting.gate)}; nothing in it applied.` : "The apply refused.";
+    }
+    case "waiting":
+      return `Applied ${report.members.filter((m) => m.status === "applied").length} of ${members}; ${report.members.filter((m) => m.status === "waiting").length} wait on an approval of the plan made after their upstream applied.`;
+  }
+}
+
+/** Who a wave applied or waits under, as a table cell. */
+function waveApproval(w: PrWave): string {
+  const whose = w.approval === "pull-request" ? "the pull request's" : "its own";
+  const by = w.approvedBy?.length ? ` by ${w.approvedBy.map(code).join(", ")}` : w.status === "waiting" ? ", not approved yet" : "";
+  return `${whose} ${code(w.gate)}${by}`;
+}
+
+/**
+ * The waves of an apply with `--wave-gate` (#4003): a row per wave reached,
+ * saying which approval it applied under, then for a wave that waits the
+ * reason its plan moved and the approve command for its new plan.
+ */
+function waveLines(report: PrReport, approver: string): string[] {
+  const waves = report.waves ?? [];
+  if (waves.length === 0) return [];
+  const out = ["", "| Wave | Components | Status | Approval |", "|---:|---|---|---|"];
+  for (const w of waves) out.push(`| ${w.wave} | ${w.components.map(code).join(", ")} | ${w.status} | ${waveApproval(w)} |`);
+  for (const w of waves.filter((x) => x.status === "waiting")) {
+    out.push("", `Wave ${w.wave} was planned after the waves before it applied, and the approved plan does not cover it:`, "");
+    for (const why of w.moved ?? []) out.push(`- ${why}`);
+    if (w.approved) out.push("", `An approval of ${code(w.gate)} stands for ${code(w.approved)}, not for the plan now.`);
+    out.push(
+      "",
+      `Read wave ${w.wave}'s plan, ${code(w.digest)}, and approve it with:`,
+      "",
+      "```",
+      prApproveCommand({ op: report.op, gate: w.gate, digest: w.digest }, approver),
+      "```",
+      "",
+      "Then run the wave's apply job again.",
+    );
   }
+  return out;
 }
 
 function approvalLines(report: PrReport, approver: string): string[] {
@@ -280,7 +482,7 @@ function approvalLines(report: PrReport, approver: string): string[] {
   const lines =
     a.status === "changed"
       ? [`An approval stands for ${code(a.approved ?? "(none)")}, not for this digest: the plan changed since it was approved.`]
-      : ["Not approved yet."];
+      : [report.stage === "record" ? "No approval stands for this plan. The release gate decides before it deploys." : "Not approved yet."];
   if (report.stage === "plan" && report.status === "planned") {
     lines.push(
       "",
@@ -290,7 +492,7 @@ function approvalLines(report: PrReport, approver: string): string[] {
       prApproveCommand(report, approver),
       "```",
       "",
-      "It applies on merge if the plan is still this one. If it moved, the apply refuses and names both digests.",
+      "On merge the plan is recorded, and a release deploys it. With apply on merge it applies if the plan is still this one; if it moved, the apply refuses and names both digests.",
     );
   }
   return lines;
@@ -306,7 +508,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   const limit = options.limit ?? GITHUB_COMMENT_LIMIT;
   const out: string[] = [
     prNoteMarker(report.env, report.member),
-    `### chant ${report.stage === "plan" ? "plan" : "apply"} for ${code(report.env)}${report.member ? ` in member ${code(report.member)}` : ""}`,
+    `### chant ${report.stage} for ${code(report.env)}${report.member ? ` in member ${code(report.member)}` : ""}`,
     "",
     `${headline(report)} Head ${code(short(report.head))}, measured from ${code(short(report.base))}.`,
   ];
@@ -332,6 +534,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
       out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
     }
   }
+  out.push(...waveLines(report, options.approver ?? "<you>"));
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }
@@ -340,9 +543,43 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     const each = deployed.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none yet"})`);
     out.push("", `Planned against outputs read from the deployed estate: ${each.join("; ")}.`);
   }
+  const planned = Object.entries(report.plannedOutputs ?? {});
+  if (planned.length > 0) {
+    const each = planned.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none known"})`);
+    out.push("", `Planned against the outputs this change's plans say its upstreams will have: ${each.join("; ")}.`);
+  }
+  const unknown = [...new Set(report.members.flatMap((m) => (m.unknownInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+  if (unknown.length > 0) {
+    out.push(
+      "",
+      `Known only after apply: ${unknown.join("; ")}. This approval does not cover what those members do with them. ` +
+        "The apply plans them again once their upstream applied and asks for an approval of that plan.",
+    );
+  }
+  const fromBuild = [...new Set(report.members.flatMap((m) => (m.buildInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+  if (fromBuild.length > 0) {
+    out.push(
+      "",
+      `From this pull request's build: ${fromBuild.join("; ")}. The image digest comes from this pull request's build, whose provenance binds it, ` +
+        "so those members apply with it once the build ran, without a second approval.",
+    );
+  }
+  for (const r of report.rounds ?? []) {
+    const what = `Round ${r.round} planned ${r.components.map(code).join(", ")} again after their upstream applied, digest ${code(r.digest)}`;
+    if (r.status === "waiting") {
+      if (r.message) out.push("", `> ${r.message}`);
+      out.push("", `${what}. Not approved yet. Approve it, then run the apply again with the same \`--resume\` record:`, "", "```", prApproveCommand({ op: report.op, gate: r.gate, digest: r.digest }, options.approver ?? "<you>"), "```");
+    } else {
+      out.push("", `${what}: ${r.status === "applied" ? `applied, approved by ${(r.approval.approvedBy ?? []).map(code).join(", ")}` : r.status === "plan-failed" ? "a member failed to plan" : "the apply failed"}.`);
+    }
+  }
   if (report.status !== "nothing") {
     out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
   }
+  // #4003: with a gate per wave, a later wave's plan on merge may differ from this one.
+  if (report.stage === "plan" && report.status === "planned" && report.waveGate) {
+    out.push("", `On merge each wave after the first is planned again once the waves before it apply, and a wave whose plan moved stops at its own gate, ${code(`${report.waveGate}-wave-<k>`)}, for approval.`);
+  }
   const head = out.join("\n") + "\n";
   if (report.status === "nothing" || report.changeSet.members.length === 0) return head;
   const room = limit - [...head].length - 1;
@@ -371,22 +608,46 @@ export function prStatusDescription(report: PrReport): string {
     case "plan-failed":
       text = `a member failed to plan${digest}`;
       break;
+    case "recorded":
+      text = `recorded ${n} member${n === 1 ? "" : "s"}: ${report.approval.status === "approved" ? "the approved plan" : report.approval.status === "changed" ? "the plan differs from the approved one" : "no approval for this plan"}${digest}`;
+      break;
     case "applied":
       text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
       break;
+    case "wave-applied": {
+      const last = (report.waves ?? []).filter((w) => w.status === "applied").at(-1);
+      text = `applied wave ${last?.wave ?? "?"} of ${report.selection.waves.length}${last ? ` under ${last.approval === "pull-request" ? "the pull request's approval" : `${last.gate}`}` : ""}`;
+      break;
+    }
     case "failed":
       text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
       break;
-    case "refused":
-      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+    case "waiting":
+      text = `waiting: ${report.members.filter((m) => m.status === "waiting").map((m) => m.member).join(", ")} planned again after an upstream applied, not approved yet`;
       break;
+    case "refused": {
+      const waiting = report.waves?.find((w) => w.status === "waiting");
+      if (waiting && (report.refusal === "wave-not-approved" || report.refusal === "wave-plan-changed")) {
+        text = `wave ${waiting.wave} waits at ${waiting.gate}: ${report.refusal === "wave-plan-changed" ? "its plan changed after its approval" : "its plan moved, approve it"}`;
+        break;
+      }
+      if (report.refusal === "earlier-wave") {
+        text = "refused: an earlier wave has not applied";
+        break;
+      }
+      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+      break;
+    }
   }
   return text.length > 140 ? text.slice(0, 137) + "..." : text;
 }
 
 /** The commit status state for a report: success, failure, or pending while it waits on approval. */
 export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
-  if (report.status === "planned" || report.status === "applied" || report.status === "nothing") return "success";
-  if (report.status === "refused" && report.refusal === "not-approved") return "pending";
+  // #4168 decision 1: a merge whose plan differs from the approved one is recorded, and its status fails.
+  if (report.status === "recorded") return report.approval.status === "changed" ? "failure" : "success";
+  if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing") return "success";
+  if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved")) return "pending";
+  if (report.status === "waiting") return "pending";
   return "failure";
 }

package/src/pr-report-url.ts

@@ -44,17 +44,17 @@ export type ReportTarget =
   | { scheme: "file"; url: string; dir: string }
   | { scheme: "s3"; url: string; bucket: string; prefix: string };
 
-/** `--report-url` read, or why it can't be. */
-export function parseReportUrl(raw: string): ReportTarget | { error: string } {
+/** `--report-url` read, or why it can't be. `name` is what the error calls the value: the flag, or `ci.reportUrl` (#4160). */
+export function parseReportUrl(raw: string, name = "--report-url"): ReportTarget | { error: string } {
   const url = raw.trim();
   if (url.startsWith("file://")) {
     let dir: string;
     try {
       dir = fileURLToPath(url);
     } catch (err) {
-      return { error: `--report-url ${url}: ${err instanceof Error ? err.message : String(err)}` };
+      return { error: `${name} ${url}: ${err instanceof Error ? err.message : String(err)}` };
     }
-    if (!isAbsolute(dir)) return { error: `--report-url ${url}: a file URL names an absolute directory` };
+    if (!isAbsolute(dir)) return { error: `${name} ${url}: a file URL names an absolute directory` };
     return { scheme: "file", url: url.replace(/\/+$/, ""), dir };
   }
   const s3 = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
@@ -62,7 +62,7 @@ export function parseReportUrl(raw: string): ReportTarget | { error: string } {
     const prefix = s3[2]!.replace(/\/+$/, "");
     return { scheme: "s3", url: `s3://${s3[1]}${prefix ? `/${prefix}` : ""}`, bucket: s3[1]!, prefix };
   }
-  return { error: `--report-url ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
+  return { error: `${name} ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
 }
 
 /** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */
@@ -71,7 +71,7 @@ export function reportKey(pr: number | null, commit: string, member?: string): s
 }
 
 /** The events file of a stage. */
-export const reportEventsFile = (stage: "plan" | "apply"): string => `pr-${stage}.events.jsonl`;
+export const reportEventsFile = (stage: "plan" | "apply" | "record"): string => `pr-${stage}.events.jsonl`;
 
 /** Puts one object: `key` below the URL. Rejects with a line a person can read. */
 export type ReportPut = (key: string, body: string, contentType: string) => Promise<void>;
@@ -194,7 +194,7 @@ const messageOf = (err: unknown): string => (err instanceof Error ? err.message
 export function openPrReportUpload(input: {
   target: ReportTarget;
   key: string;
-  stage: "plan" | "apply";
+  stage: "plan" | "apply" | "record";
   warn: (message: string) => void;
   put?: ReportPut;
 }): PrReportUpload {

package/src/runner-start-bundle.test.ts

@@ -0,0 +1,29 @@
+/**
+ * `@intentius/chant/runner-start` bundles small (#4147): a stage that runs
+ * as one bundled file checks its runner before it trades for credentials,
+ * so the verifier reaches nothing but itself, the DSSE helpers and
+ * `node:crypto` and `node:fs`.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+test("the runner-start verifier holds itself and the DSSE helpers, and imports only node:crypto and node:fs", async () => {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", "runner-start.ts")],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  const inputs = Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/")).sort();
+  const imports = [...new Set(Object.values(result.metafile.outputs).flatMap((o) => o.imports.map((i) => i.path)))].sort();
+  expect(inputs).toEqual(["packages/core/src/runner-start.ts", "packages/core/src/workspace/trust/dsse.ts"]);
+  expect(imports).toEqual(["node:crypto", "node:fs"]);
+  expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(24 * 1024);
+});