@intentius/chant 0.124.15 → 0.124.16

package/src/components/fan-out-record.ts

@@ -27,9 +27,8 @@
  * per-wave CI job hands to the next.
  */
 
-import { dirname } from "node:path";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { readWaveRecords, type WaveRecord } from "../gated-waves";
+import { existsSync, readFileSync } from "node:fs";
+import { readWaveRecords, writeWaveRecordFile, type WaveRecord } from "../wave-engine";
 import type { ChangeSetDocument } from "../change-set";
 import type { PrMember } from "../pr-loop";
 
@@ -126,8 +125,5 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
  * write leaves the previous record whole rather than half a JSON document.
  */
 export function writeFanOutAttempt(path: string, attempt: FanOutAttempt): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, JSON.stringify(attempt, null, 2) + "\n");
-  renameSync(temporary, path);
+  writeWaveRecordFile(path, attempt);
 }

package/src/components/fan-out-run.ts

@@ -31,8 +31,10 @@
  * ## Or one approval per wave
  *
  * `waveGate` (#3049) is the other mode. Each wave is planned once the waves
- * before it applied, and its gate binds that wave's set digest
- * (`../gated-waves.ts`). See {@link runGatedWaves}.
+ * before it applied, and its gate binds that wave's set digest. Gate names,
+ * the digest and the gate decision come from the wave engine
+ * (`../wave-engine.ts`, #3766), which `chant run wave` uses too. See
+ * {@link runGatedWaves}.
  */
 
 import {
@@ -50,7 +52,7 @@ import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
-import { waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../gated-waves";
+import { decideWaveGate, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
 /**
  * One gate per wave (#3049), each bound to its wave's set digest. The other
@@ -452,10 +454,10 @@ async function runGatedWaves(
       continue;
     }
 
-    const check = await evaluateGate(gates.port, {
+    const check = await decideWaveGate(gates.port, {
       op: waveGate.op,
       gate: gateName,
-      planDigest: digest,
+      digest,
       description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
       ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
       ...(options.now ? { now: options.now } : {}),

package/src/gate-decision-bundle.test.ts

@@ -46,6 +46,7 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/notify.ts",
       "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/op-waves.ts",
+      "packages/core/src/wave-layout.ts",
       "packages/core/src/workspace/class-data.ts",
       "packages/core/src/workspace/identity-gate-rule.ts",
       "packages/core/src/workspace/jsonc.ts",

package/src/gated-waves.ts

@@ -2,12 +2,17 @@
  * Gated waves (#3049): one change rolled out across many roots, a wave at a
  * time, each wave behind its own gate bound to that wave's set digest.
  *
- * `chant components fan-out --wave-gate` is the runner. This module holds the
- * parts that need no runner: how a set of roots is cut into waves, what a
- * wave's digest is, what its gate is called, and what the attempt record says
- * about each wave. They are kept apart from the runner because terragucci
- * calls them from its CI stages as one bundled file with no TypeScript
- * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * Two runners use it (#3766): `chant components fan-out --wave-gate` and the
+ * Op waves spec's `chant run wave` (`./op/op-waves-run.ts`). This module
+ * holds the parts that need no runner: how a set of roots is cut into waves,
+ * what a wave's digest is and which members it covers, what its gate is
+ * called, and what the attempt record says about each wave. A gate name
+ * pattern and the share split of a wide wave are in `./wave-layout.ts`;
+ * `./wave-engine.ts` puts them together with the gate decision call and the
+ * record file writer, which need the gate ledger and the filesystem.
+ *
+ * They are kept apart from the runners because terragucci calls them from
+ * its CI stages as one bundled file with no TypeScript toolchain (#3421). Everything here imports `./change-set` and nothing else,
  * and `gated-waves-bundle.test.ts` holds that.
  *
  * ## The set digest
@@ -144,6 +149,23 @@ export function waveGateName(gate: string, wave: number): string {
   return `${gate}-wave-${wave}`;
 }
 
+/** Which members a wave's set digest covers (#3821). */
+export type WaveDigestOver = "all" | "changing";
+
+/**
+ * The members a wave's set digest is taken over (#3821, #3766). `all` (the
+ * default): every member. `changing`: the members whose plan is not
+ * `empty`, or every member when all of them are empty. `extras`, members
+ * that are no run (such as a wave's cost), are always in it.
+ */
+export function waveDigestMembers<M extends WaveMember & { empty?: boolean }>(
+  members: readonly M[],
+  options: { over?: WaveDigestOver; extras?: readonly WaveMember[] } = {},
+): WaveMember[] {
+  const changing = options.over === "changing" ? members.filter((m) => m.empty !== true) : [];
+  return [...(changing.length > 0 ? changing : members), ...(options.extras ?? [])];
+}
+
 /** Where a wave got to. */
 export type WaveStatus =
   /** Planned, and its gate is not approved for this digest. Nothing in it ran. */

package/src/op/op-waves-run.ts

@@ -51,7 +51,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix } from "node:path";
-import { waveSetDigest, type WaveMember } from "../gated-waves";
+import { decideWaveGate, waveDigestMembers, waveSetDigest, writeWaveRecordFile, type WaveMember } from "../wave-engine";
 import type { ReviewApproval } from "../gate-decision";
 import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type GateDigestMismatch, type GateLedgerPort } from "./gate";
 import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -817,8 +817,7 @@ function pendingFields(value: unknown, where: string): Record<string, unknown> |
  * file's members that are no run (a cost), are always in it.
  */
 export function opWaveSetDigest(spec: Pick<OpWavesSpec, "digest">, members: ReadonlyArray<WaveMember & { empty?: boolean }>, extras: readonly WaveMember[] = []): string {
-  const changing = spec.digest?.over === "changing" ? members.filter((m) => m.empty !== true) : [];
-  return waveSetDigest([...(changing.length > 0 ? changing : members), ...extras]);
+  return waveSetDigest(waveDigestMembers(members, { ...(spec.digest?.over ? { over: spec.digest.over } : {}), extras }));
 }
 
 /** What one moment's hooks came to. */
@@ -1627,10 +1626,10 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
   // #3784: under the spend rule at base, an approval a wave already applied under counts for nothing.
   const spent: AppliedGateRecord[] | undefined = decision.spend === "base" ? ((await ledger.readApplied?.(spec.name)) ?? []).filter((a) => a.gate === gate) : undefined;
   const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
-  const check = await evaluateGate(port, {
+  const check = await decideWaveGate(port, {
     op: spec.name,
     gate,
-    planDigest: digest,
+    digest,
     description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
@@ -1728,7 +1727,7 @@ async function settlePointGate(options: RunOpWaveOptions, ctx: WaveContext, deci
 /** Write the decision record, with every hook's outcome so far (#3804). */
 function writeRecord(recordPath: string, decision: OpWaveDecision, result: RunOpWaveResult): void {
   if (result.hooks.length > 0) decision.outcomes = [...result.hooks];
-  writeFileSync(recordPath, JSON.stringify(decision, null, 2) + "\n");
+  writeWaveRecordFile(recordPath, decision);
 }
 
 /**

package/src/op/op-waves.ts

@@ -69,6 +69,7 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
+import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout";
 
 /**
  * The variables a wave job reads its notify secrets from, for the lexicons
@@ -361,11 +362,11 @@ export interface OpWavesDigest {
 export const OP_WAVES_DIGEST_OVER = ["all", "changing"] as const;
 
 /** The default gate name pattern. */
-export const OP_WAVE_DEFAULT_GATE_NAME = "{gate}-wave-{k}";
+export const OP_WAVE_DEFAULT_GATE_NAME = WAVE_GATE_NAME_PATTERN;
 
 /** The gate wave `k` waits on (#3821): the spec's `gateName` pattern, by default `<gate>-wave-<k>`. */
 export function opWaveGateName(spec: Pick<OpWavesSpec, "name" | "gate" | "gateName">, k: number): string {
-  return (spec.gateName ?? OP_WAVE_DEFAULT_GATE_NAME).replaceAll("{gate}", spec.gate ?? spec.name).replaceAll("{k}", String(k));
+  return waveGateNameFrom(spec.gateName, spec.gate ?? spec.name, k);
 }
 
 /** Where a wave reads who may override a policy denial (#3821). */
@@ -638,12 +639,7 @@ export function opWaveApplyHooksRunBy(spec: Pick<OpWavesSpec, "hooks" | "waves">
  * by target, cut into contiguous slices whose sizes differ by at most one.
  */
 export function opWaveShare<T extends { target: string }>(runs: readonly T[], share: number, shares: number): T[] {
-  const sorted = [...runs].sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
-  const base = Math.floor(sorted.length / shares);
-  const extra = sorted.length % shares;
-  const start = (share - 1) * base + Math.min(share - 1, extra);
-  const size = base + (share <= extra ? 1 : 0);
-  return sorted.slice(start, start + size);
+  return waveShare(runs, share, shares, (run) => run.target);
 }
 
 /**

package/src/package-version.ts

@@ -0,0 +1,11 @@
+/**
+ * `@intentius/chant`'s own version, read from its package.json as a file. The
+ * path is the same from `src/` and `dist/`. The slim wave-job runtime (#3896)
+ * has no package.json beside it, and its build writes the version in here.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function readChantPackageVersion(): string {
+  return (JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf-8")) as { version: string }).version;
+}

package/src/wave-engine.test.ts

@@ -0,0 +1,107 @@
+/**
+ * One wave engine under both runners (#3766): the same runs, planned to the
+ * same digests, are the same set digest and the same gate name whether
+ * `chant run wave` (an Op waves spec) or `chant components fan-out
+ * --wave-gate` decides the wave. An approval recorded through one matches a
+ * wave the other plans.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "vitest";
+import { memoryGateLedgerPort } from "./op/gate";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op/op-waves-run";
+import { opWaveGateName, opWaveShare, type OpWavesSpec } from "./op/op-waves";
+import { planFanOut } from "./components/fan-out";
+import { runFanOut } from "./components/fan-out-run";
+import { CapabilityRegistry } from "./components/capability";
+import type { DriverComponent } from "./components/driver";
+import { waveGateName, waveGateNameFrom, waveSetDigest, waveShare, WAVE_GATE_NAME_PATTERN } from "./wave-engine";
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+/** The runs both runners plan: a member name and its plan digest. */
+const RUNS: Record<string, string> = { "tenant-b": digest("b"), "tenant-a": digest("a"), "tenant-c": digest("c") };
+const NOW = "2026-10-11T00:00:00Z";
+
+async function throughOpWaves(): Promise<{ digest: string; gate: string; pending: string | undefined }> {
+  const spec: OpWavesSpec = {
+    name: "rollout",
+    op: "migrate",
+    plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+    apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+    waves: [{ name: "tenants", runs: Object.keys(RUNS).map((target) => ({ target })) }],
+  };
+  const cwd = mkdtempSync(join(tmpdir(), "wave-engine-"));
+  try {
+    const exec: OpWaveExec = (argv, dir) => {
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ planDigest: RUNS[argv[2]!] }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd, exec, show, gates, now: NOW });
+    expect(result.exitCode).toBe(3);
+    return { digest: result.decision!.digest, gate: result.decision!.gate, pending: gates.appended[0]?.planDigest };
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+async function throughFanOut(): Promise<{ digest: string; gate: string; pending: string | undefined }> {
+  const components: DriverComponent[] = Object.keys(RUNS).map((name) => ({ name, deploy: [{ phase: "Apply", steps: [] }] }));
+  const plan = planFanOut({ components, changed: Object.keys(RUNS) });
+  const gates = memoryGateLedgerPort();
+  const result = await runFanOut(plan, components, new CapabilityRegistry(), {
+    env: "prod",
+    gates,
+    now: NOW,
+    waveGate: {
+      op: "rollout",
+      gate: "rollout",
+      planComponent: async (component) => ({
+        component: component.name,
+        members: [{ member: component.name, planDigest: RUNS[component.name]! }],
+        plans: {},
+        parts: [],
+      }),
+    },
+  });
+  expect(result.status).toBe("gated");
+  const wave = result.waves![0]!;
+  return { digest: wave.digest, gate: wave.gate, pending: gates.appended[0]?.planDigest };
+}
+
+describe("one wave engine (#3766)", () => {
+  test("the same runs bind the same set digest and gate through both runners", async () => {
+    const expected = waveSetDigest(Object.entries(RUNS).map(([member, planDigest]) => ({ member, planDigest })));
+    const op = await throughOpWaves();
+    const fan = await throughFanOut();
+    expect(op.digest).toBe(expected);
+    expect(fan.digest).toBe(expected);
+    expect(op.pending).toBe(expected);
+    expect(fan.pending).toBe(expected);
+    expect(op.gate).toBe("rollout-wave-1");
+    expect(fan.gate).toBe(op.gate);
+  });
+
+  test("gate names: the default pattern is waveGateName's name, and a spec's pattern still wins", () => {
+    for (const k of [1, 2, 12]) {
+      expect(waveGateNameFrom(undefined, "deploy", k)).toBe(waveGateName("deploy", k));
+      expect(waveGateNameFrom(WAVE_GATE_NAME_PATTERN, "deploy", k)).toBe(`deploy-wave-${k}`);
+      expect(opWaveGateName({ name: "deploy" }, k)).toBe(waveGateName("deploy", k));
+    }
+    expect(opWaveGateName({ name: "x", gate: "tg", gateName: "wave-{k}" }, 3)).toBe("wave-3");
+    expect(opWaveGateName({ name: "x", gateName: "{gate}/{k}" }, 3)).toBe("x/3");
+  });
+
+  test("the share split is the Op waves split by target", () => {
+    const runs = ["t5", "t1", "t4", "t2", "t3"].map((target) => ({ target }));
+    for (const shares of [1, 2, 3, 5]) {
+      for (let share = 1; share <= shares; share++) {
+        expect(waveShare(runs, share, shares, (r) => r.target)).toEqual(opWaveShare(runs, share, shares));
+      }
+    }
+    expect(opWaveShare(runs, 1, 2).map((r) => r.target)).toEqual(["t1", "t2", "t3"]);
+  });
+});

package/src/wave-engine.ts

@@ -0,0 +1,98 @@
+/**
+ * The wave engine (#3766): what `chant run wave` (the Op waves spec,
+ * `./op/op-waves-run.ts`) and `chant components fan-out --wave-gate`
+ * (`./components/fan-out-run.ts`) share once a wave is planned.
+ *
+ * - Gate naming: {@link waveGateName} and {@link waveGateNameFrom}.
+ * - The set digest: {@link waveSetDigest} over {@link waveDigestMembers}.
+ * - The share split of a wide wave: {@link waveShare}.
+ * - The gate decision call: {@link decideWaveGate}.
+ * - The record file a wave job hands the next one: {@link writeWaveRecordFile}.
+ *
+ * The parts that need neither the gate ledger nor the filesystem live in
+ * `./gated-waves.ts`, which terragucci bundles on its own (#3421), and
+ * `./wave-layout.ts`, which imports nothing so the Op waves spec module can
+ * use it without the change-set code; this module re-exports both so a
+ * runner imports the engine from one place.
+ *
+ * What stays with each entry point: how a wave is planned (Op runs' plan
+ * commands, or each component's capabilities), the gate policy, approval
+ * mode, decision point, hooks and spend rule (Op waves only), and the shape
+ * of the record each writes. Those shapes are read by jobs and approvals
+ * already in the wild, so the engine writes what it is handed.
+ */
+
+import { dirname } from "node:path";
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { evaluateGate, type GateCheck, type GateLedgerPort } from "./op/gate";
+import type { AppliedGateRecord } from "./lifecycle/gate-applied";
+
+export { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "./wave-layout";
+export {
+  layerWaves,
+  waveGateName,
+  waveDigestMembers,
+  waveSetDigest,
+  readWaveRecords,
+  withWaveRecord,
+  describeChangedWave,
+  type WaveDigestOver,
+  type WaveMember,
+  type WaveNode,
+  type WaveRecord,
+  type WaveStatus,
+} from "./gated-waves";
+
+/** What a wave asks its gate. */
+export interface WaveGateRequest {
+  /** The op the gate is recorded under: the fan-out's op, or the Op waves spec's name. */
+  op: string;
+  /** The wave's full gate name. */
+  gate: string;
+  /** The wave's set digest. */
+  digest: string;
+  /** The pending fact's description. */
+  description: string;
+  /** The pending fact's expiry, as a gate's `timeout`. */
+  timeout?: string;
+  now?: string;
+  /** Approvals a wave already applied under, which count for nothing (#3784). */
+  spent?: readonly AppliedGateRecord[];
+  /** Fields the pending fact carries (#3821). */
+  fields?: Record<string, unknown>;
+  /** The pending fact carries `neverOverMcp` (#3821). */
+  neverOverMcp?: boolean;
+}
+
+/**
+ * Decide a wave's gate: an approval of `digest` under `gate` on `op`'s
+ * ledger, or the pending fact that stands for it. A field left out of the
+ * request is left out of the call, so each entry point's pending facts are
+ * the ones it always wrote.
+ */
+export function decideWaveGate(port: GateLedgerPort, request: WaveGateRequest): Promise<GateCheck> {
+  return evaluateGate(port, {
+    op: request.op,
+    gate: request.gate,
+    planDigest: request.digest,
+    description: request.description,
+    ...(request.timeout ? { timeout: request.timeout } : {}),
+    ...(request.now !== undefined ? { now: request.now } : {}),
+    ...(request.spent ? { spent: request.spent } : {}),
+    ...(request.fields ? { fields: request.fields } : {}),
+    ...(request.neverOverMcp ? { neverOverMcp: true } : {}),
+  });
+}
+
+/**
+ * Write a wave record file as indented JSON, through a temporary file and a
+ * rename, so a job killed during the write leaves the previous record whole.
+ * The fan-out attempt record and an Op wave's decision record both go
+ * through it.
+ */
+export function writeWaveRecordFile(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n");
+  renameSync(temporary, path);
+}

package/src/wave-layout.ts

@@ -0,0 +1,44 @@
+/**
+ * Wave gate names and the share split of a wide wave (#3766), the parts of
+ * the wave engine (`./wave-engine.ts`) that the Op waves spec module
+ * (`./op/op-waves.ts`) needs. That module is in the gate-decision bundle
+ * (`./gate-decision.ts` re-exports a constant from it), so this imports
+ * nothing and keeps the change-set digest code out of that bundle.
+ */
+
+/** The default wave gate name pattern: `{gate}` is the base gate name, `{k}` the wave's number. */
+export const WAVE_GATE_NAME_PATTERN = "{gate}-wave-{k}";
+
+/**
+ * The gate wave `k` waits on under a name pattern (#3821). With the default
+ * pattern this is `waveGateName(gate, k)` from `./gated-waves.ts`; an Op
+ * waves spec's `gateName` names another (such as `"wave-{k}"`) so approvals
+ * already on the ledger under a product's old names keep matching.
+ *
+ * `{gate}` is filled in before `{k}`, as `opWaveGateName` always did, so a
+ * base gate name holding the text `{k}` is filled in too. That is the one
+ * input on which this and `waveGateName` differ, and each entry point keeps
+ * the one it shipped with.
+ */
+export function waveGateNameFrom(pattern: string | undefined, gate: string, k: number): string {
+  return (pattern ?? WAVE_GATE_NAME_PATTERN).replaceAll("{gate}", gate).replaceAll("{k}", String(k));
+}
+
+/**
+ * Share `share` (1-based) of `shares` of a wide wave (#3679): the items
+ * sorted by `keyOf`, cut into contiguous slices whose sizes differ by at most
+ * one. The deciding job and every share job cut the same way, so each item
+ * is applied by exactly one share.
+ */
+export function waveShare<T>(items: readonly T[], share: number, shares: number, keyOf: (item: T) => string): T[] {
+  const sorted = [...items].sort((a, b) => {
+    const x = keyOf(a);
+    const y = keyOf(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  const base = Math.floor(sorted.length / shares);
+  const extra = sorted.length % shares;
+  const start = (share - 1) * base + Math.min(share - 1, extra);
+  const size = base + (share <= extra ? 1 : 0);
+  return sorted.slice(start, start + size);
+}

package/src/wave-runtime-bundle.test.ts

@@ -0,0 +1,70 @@
+/**
+ * The wave-job runtime bundles to one self-contained file (#3896). A product
+ * copies `dist/wave-runtime.mjs` into its CI image with no npm install of
+ * chant, so the file may import nothing but `node:` builtins, and it carries
+ * no TypeScript compiler, esbuild or tsx: those three are the 33 MB a wave
+ * job's image has no use for. This builds it the way `npm run build` does and
+ * reads esbuild's own list of what went in.
+ */
+
+import { builtinModules } from "node:module";
+import { describe, expect, test } from "vitest";
+// @ts-expect-error: a plain .mjs script with no type declarations
+import { buildWaveRuntime, LEFT_OUT } from "../scripts/build-wave-runtime.mjs";
+
+interface Metafile {
+  inputs: Record<string, { bytes: number; imports: { path: string; kind: string; external?: boolean }[] }>;
+  outputs: Record<string, { imports: { path: string; kind: string; external?: boolean }[]; inputs: Record<string, { bytesInOutput: number }> }>;
+}
+
+const built = (await buildWaveRuntime({ write: false })) as { bytes: number; metafile: Metafile; text: string };
+const output = Object.values(built.metafile.outputs)[0]!;
+const inputs = Object.keys(output.inputs);
+
+describe("the wave-job runtime bundle (#3896)", () => {
+  test("leaves out the TypeScript compiler, esbuild and tsx", () => {
+    expect(LEFT_OUT).toEqual(["typescript", "esbuild", "tsx"]);
+    for (const name of LEFT_OUT as string[]) {
+      expect(inputs.filter((i) => i.includes(`node_modules/${name}/`)), name).toEqual([]);
+    }
+  });
+
+  test("imports nothing but node: builtins, so it runs with no node_modules", () => {
+    const builtins = new Set(builtinModules);
+    const imported = output.imports.map((i) => i.path);
+    expect(imported.filter((p) => !builtins.has(p.replace(/^node:/, "").split("/")[0]!))).toEqual([]);
+    // zod, ajv, js-yaml and picomatch are inlined; nothing reads them from disk.
+    for (const pkg of ["zod", "ajv", "js-yaml", "picomatch"]) {
+      expect(inputs.some((i) => i.includes(`node_modules/${pkg}/`)), pkg).toBe(true);
+    }
+    expect(built.text).not.toMatch(/createRequire\(import\.meta\.url\)\("\.\.\/\.\.\/package\.json"\)/);
+  });
+
+  test("a left-out package is reached only through import(), never on start", () => {
+    // The build refuses otherwise; this pins the four commands' own modules as the static graph.
+    const entry = Object.keys(built.metafile.inputs).find((k) => k.endsWith("src/wave-runtime.ts"))!;
+    const seen = new Set([entry]);
+    const queue = [entry];
+    while (queue.length) {
+      for (const im of built.metafile.inputs[queue.shift()!]?.imports ?? []) {
+        if (im.kind === "dynamic-import" || seen.has(im.path)) continue;
+        seen.add(im.path);
+        queue.push(im.path);
+      }
+    }
+    for (const handler of ["cli/handlers/run-wave.ts", "cli/handlers/gate-resume.ts", "cli/handlers/approve.ts", "workspace/points-cli.ts", "cli/parse-args.ts"]) {
+      expect([...seen].some((k) => k.endsWith(`src/${handler}`)), handler).toBe(true);
+    }
+    expect([...seen].filter((k) => k.startsWith("chant-wave-runtime-left-out:"))).toEqual([]);
+    // Neither the full CLI's dispatch nor the operator loop is in it, and the build and plugin loader load on no start.
+    expect(inputs.filter((i) => /src\/cli\/main\.ts$|src\/cli\/handlers\/operator\.ts$/.test(i))).toEqual([]);
+    expect([...seen].filter((i) => /src\/cli\/plugins\.ts$|src\/build\.ts$/.test(i))).toEqual([]);
+  });
+
+  test("carries its version and stays small", () => {
+    expect(built.text).toContain('"workspace points"');
+    expect(built.text.startsWith("#!/usr/bin/env node\n")).toBe(true);
+    // About 1.45 MB minified today (440 KB gzipped), zod's inlined schemas about 300 KB of it.
+    expect(built.bytes).toBeLessThan(2 * 1024 * 1024);
+  });
+});