@intentius/chant 0.124.15 → 0.124.17

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);
+  });
+});

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

@@ -0,0 +1,177 @@
+/**
+ * The wave-job runtime runs alone (#3896). `dist/wave-runtime.mjs` is copied
+ * into an empty directory, the way a product's CI image carries it, and run
+ * with plain node, nothing installed beside it, through a gated wave's whole
+ * life: `run wave` waits at a ledger gate, `approve` records the resolution,
+ * `run resume --dry-run` finds it, `run wave` applies; then a wave whose gate
+ * asks a decision point waits, `workspace points` lists the open question,
+ * `workspace points answer` answers it, and `run wave` applies.
+ *
+ * End to end because it builds the bundle and spawns node for each command.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { copyFileSync, cpSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+// @ts-expect-error: a plain .mjs script with no type declarations
+import { buildWaveRuntime } from "../scripts/build-wave-runtime.mjs";
+import { REPO } from "./workspace/__fixtures__/decide-workspace";
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+const SPEC = {
+  name: "smoke",
+  op: "smoke",
+  plan: ["node", "plan.mjs", "{target}", "{plan}"],
+  apply: ["node", "apply.mjs", "{target}", "{plan}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "always" },
+    { name: "prod", runs: [{ target: "prod" }], gate: "always", point: "prod-apply" },
+  ],
+};
+
+let scratch: string;
+let runtimeDir: string;
+let runtime: string;
+let repo: string;
+
+/** The job's environment: no CI variables, so nothing names a CI job to resume. */
+function jobEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (/^(CI|GITHUB_|GITLAB_|FORGEJO_|GITEA_|CHANT_|NODE_OPTIONS$|VITEST)/.test(k)) continue;
+    env[k] = v;
+  }
+  return env;
+}
+
+function chant(...args: string[]): { status: number | null; stdout: string; stderr: string } {
+  const r = spawnSync(process.execPath, [runtime, ...args], { cwd: repo, env: jobEnv(), encoding: "utf-8" });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr };
+}
+
+const git = (...args: string[]) =>
+  execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd: repo, stdio: "ignore" });
+
+beforeAll(async () => {
+  scratch = realpathSync(mkdtempSync(join(tmpdir(), "chant-wave-runtime-")));
+  const built = join(scratch, "build", "wave-runtime.mjs");
+  mkdirSync(dirname(built), { recursive: true });
+  await buildWaveRuntime({ outfile: built });
+  runtimeDir = join(scratch, "image");
+  mkdirSync(runtimeDir);
+  runtime = join(runtimeDir, "wave-runtime.mjs");
+  copyFileSync(built, runtime);
+
+  repo = join(scratch, "repo");
+  const files: Record<string, string> = {
+    "chant.workspace.json": JSON.stringify({
+      name: "wave-runtime",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+      records: [{ kind: "answers/answer.kind.mjs" }],
+    }),
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/points.json": JSON.stringify(POINTS),
+    "plan.mjs": `import { writeFileSync } from "node:fs";\nwriteFileSync(process.argv[3], JSON.stringify({ planDigest: "sha256:" + (process.argv[2] === "dev" ? "a" : "b").repeat(64) }));\n`,
+    "apply.mjs": `import { appendFileSync } from "node:fs";\nappendFileSync("applied.log", process.argv[2] + "\\n");\n`,
+    "waves.json": JSON.stringify(SPEC),
+  };
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(repo, path)), { recursive: true });
+    writeFileSync(join(repo, path), text);
+  }
+  cpSync(join(REPO, "reference-workspace", "answers", "answer.kind.mjs"), join(repo, "answers", "answer.kind.mjs"));
+  cpSync(join(REPO, "reference-workspace", "answers", "answer.schema.json"), join(repo, "answers", "answer.schema.json"));
+  git("init", "-q", "-b", "main");
+  git("add", "-A");
+  git("commit", "-qm", "spec");
+  // The gate policy is read at HEAD^1, so the spec needs a commit under the head.
+  writeFileSync(join(repo, ".gitignore"), ".chant/\napplied.log\n");
+  git("add", "-A");
+  git("commit", "-qm", "ignore");
+}, 120_000);
+
+afterAll(() => {
+  if (scratch) rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("the wave-job runtime, alone in a directory (#3896)", () => {
+  test("is one file, with no package beside it to resolve", () => {
+    expect(readdirSync(runtimeDir)).toEqual(["wave-runtime.mjs"]);
+    const resolveBeside = createRequire(runtime).resolve;
+    for (const pkg of ["@intentius/chant", "typescript", "esbuild", "tsx", "zod", "ajv"]) {
+      expect(() => resolveBeside(pkg), pkg).toThrow();
+    }
+    const version = (JSON.parse(readFileSync(join(REPO, "packages", "core", "package.json"), "utf-8")) as { version: string }).version;
+    expect(chant("--version").stdout.trim()).toBe(version);
+    const other = chant("build");
+    expect(other.status).toBe(1);
+    expect(other.stderr).toContain("is not part of chant's wave-job runtime");
+  });
+
+  test("a ledger gate: run wave waits, approve, run resume --dry-run, run wave applies", () => {
+    const waiting = chant("run", "wave", "--spec", "waves.json", "--wave", "1", "--json");
+    expect(waiting.status, waiting.stderr).toBe(3);
+    const decision = (JSON.parse(waiting.stdout) as { decision: { status: string; gate: string; digest: string } }).decision;
+    expect(decision).toMatchObject({ status: "waiting", gate: "smoke-wave-1" });
+
+    const approved = chant("approve", "smoke", "smoke-wave-1", "--actor", "alice");
+    expect(approved.status, approved.stderr).toBe(0);
+    expect(approved.stderr).toContain(`Gate "smoke-wave-1" on "smoke" resolved by alice`);
+    expect(approved.stderr).toContain(`This approves the plan ${decision.digest}`);
+
+    const resume = chant("run", "resume", "--dry-run");
+    expect(resume.status, resume.stderr).toBe(0);
+    expect(resume.stderr).toContain("smoke / smoke-wave-1, approved by alice");
+
+    const applied = chant("run", "wave", "--spec", "waves.json", "--wave", "1");
+    expect(applied.status, applied.stderr).toBe(0);
+    expect(applied.stderr).toContain("approved by alice");
+    expect(readFileSync(join(repo, "applied.log"), "utf-8")).toBe("dev\n");
+  });
+
+  test("a gate that asks a decision point: run wave waits, points lists and answers, run wave applies", () => {
+    const waiting = chant("run", "wave", "--spec", "waves.json", "--wave", "2", "--json");
+    expect(waiting.status, waiting.stderr).toBe(3);
+    const id = (JSON.parse(waiting.stdout) as { decision: { point: { question: { id: string } } } }).decision.point.question.id;
+    expect(id).toMatch(/^prod-apply-[0-9a-f]{12}$/);
+
+    const open = chant("workspace", "points", "--open");
+    expect(open.status, open.stderr).toBe(0);
+    expect(open.stdout).toContain(`${id}  escalated`);
+
+    const answered = chant("workspace", "points", "answer", id, "--answer", "true", "--by", "alice");
+    expect(answered.status, answered.stderr).toBe(0);
+    expect(readFileSync(join(repo, "answers", `${id}.md`), "utf-8")).toMatch(/state: "answered"\nanswer: true/);
+
+    const applied = chant("run", "wave", "--spec", "waves.json", "--wave", "2");
+    expect(applied.status, applied.stderr).toBe(0);
+    expect(readFileSync(join(repo, "applied.log"), "utf-8")).toBe("dev\nprod\n");
+
+    // The ledger the runtime wrote is the full CLI's: pending, resolution, pending citing the question, resolution citing the answer.
+    const ledger = execFileSync("git", ["show", "chant/lifecycle:_gates/smoke.jsonl"], { cwd: repo, encoding: "utf-8" })
+      .trim()
+      .split("\n")
+      .map((l) => JSON.parse(l) as { kind?: string; gate: string; resolvedBy?: string; answer?: { id: string } });
+    expect(ledger.map((l) => [l.gate, l.kind ?? "resolution", l.resolvedBy ?? null])).toEqual([
+      ["smoke-wave-1", "pending", null],
+      ["smoke-wave-1", "resolution", "alice"],
+      ["smoke-wave-2", "pending", null],
+      ["smoke-wave-2", "resolution", "alice"],
+    ]);
+    expect(ledger[3]!.answer?.id).toBe(id);
+  });
+});

package/src/wave-runtime.ts

@@ -0,0 +1,104 @@
+/**
+ * The slim wave-job runtime (#3896): the four commands a generated Op waves
+ * pipeline runs, and nothing else.
+ *
+ *   chant run wave --spec <file> --wave <k> [--decide | --share <i> | --record-plans]
+ *   chant run resume [--gate <op>/<gate>] [--dry-run]
+ *   chant approve <op> <gate> [...]
+ *   chant workspace points ask|answer|list|... [...]
+ *
+ * `scripts/build-runtime.mjs` bundles this file with esbuild into
+ * `dist/wave-runtime.mjs`: one self-contained ES module whose only imports are
+ * `node:` builtins, with no TypeScript compiler, esbuild, tsx or zod in it. A
+ * product copies that one file into its CI image and runs it with plain node,
+ * or runs it from an installed `@intentius/chant`
+ * (`node node_modules/@intentius/chant/dist/wave-runtime.mjs run wave ...`).
+ *
+ * The handlers are the full CLI's own (`./cli/main.ts` dispatches to the same
+ * functions), parsed by the same `parseArgs`, so flags, output, exit codes and
+ * the ledgers each command writes are the same. What the runtime does not do:
+ * evaluate `chant.config.ts` (which needs a TypeScript loader). None of the
+ * four commands reads the config; the full CLI loads it only to check `--env`
+ * against the declared `environments`, a check the runtime skips.
+ */
+
+import { parseArgs } from "./cli/parse-args";
+import { resolveCommand, type CommandDef, type ParsedArgs } from "./cli/registry";
+import { formatError } from "./cli/format";
+import { flushAndExit } from "./cli/flush";
+import { CHANT_VERSION } from "./cli/version";
+import { isEntryPoint } from "./cli/is-entry-point";
+import { ENV_VAR } from "./env";
+import { initRuntime } from "./runtime-adapter";
+import { runOpWaveCommand } from "./cli/handlers/run-wave";
+import { runResumeCommand } from "./cli/handlers/gate-resume";
+import { runApprove } from "./cli/handlers/approve";
+import { runWorkspacePoints } from "./workspace/points-cli";
+
+/** The commands the runtime carries, under the names the full CLI registers them by. */
+export const RUNTIME_COMMANDS: CommandDef[] = [
+  { name: "run wave", handler: runOpWaveCommand },
+  { name: "run resume", handler: runResumeCommand },
+  { name: "approve", handler: runApprove },
+  { name: "workspace points", handler: runWorkspacePoints },
+];
+
+const HELP = `
+chant runtime ${CHANT_VERSION} - the wave-job commands of chant, in one file
+
+Usage: node wave-runtime.mjs <command> [options]
+
+Commands:
+  run wave --spec <file> --wave <k>   Plan, gate and apply wave k of an Op waves spec
+                                      (--decide, --share <i>, --record-plans, --base <ref>, --json)
+  run resume                          Start the CI jobs that wait at gates whose approval arrived
+                                      (--gate <op>/<gate>, --dry-run, --json)
+  approve <op> <gate>                 Record a gate's resolution on the lifecycle ledger
+                                      (--actor, --plan, --note, --url, --sign, --expire, --resume, ...)
+  workspace points <verb>             Ask, answer and list decision points
+
+Flags, output, exit codes and ledger formats are the full chant CLI's;
+see "chant --help" in @intentius/chant for every flag. This runtime does
+not evaluate chant.config.ts, so --env is not checked against the
+declared environments.
+`;
+
+/** Parse, dispatch and return the exit code. Exported for tests. */
+export async function runRuntime(argv: string[]): Promise<number> {
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+  const match = resolveCommand(args, RUNTIME_COMMANDS);
+  if (args.version && (!args.command || match)) {
+    console.log(CHANT_VERSION);
+    return 0;
+  }
+  if (args.help || !args.command) {
+    console.log(HELP);
+    return args.help ? 0 : 1;
+  }
+  if (!match) {
+    const name = args.path && args.path !== "." ? `${args.command} ${args.path}` : args.command;
+    console.error(formatError({
+      message: `"${name}" is not part of chant's wave-job runtime`,
+      hint: "It runs run wave, run resume, approve and workspace points. Every other command needs the full @intentius/chant CLI.",
+    }));
+    return 1;
+  }
+  if (args.env) process.env[ENV_VAR] = args.env;
+  initRuntime();
+  return match.def.handler({ args, plugins: [], serializers: [] });
+}
+
+if (isEntryPoint(process.argv[1], import.meta.url)) {
+  runRuntime(process.argv.slice(2)).then(flushAndExit, async (err) => {
+    const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    if (verbose && err instanceof Error && err.stack) console.error(err.stack);
+    else console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    await flushAndExit(1);
+  });
+}

package/src/workspace/ajv2020.ts

@@ -0,0 +1,17 @@
+/**
+ * The Ajv 2020-12 validator class, loaded on first use: ajv costs start-up
+ * time, and most commands validate nothing with it. One loader for every
+ * schema check in workspace/, so the slim wave-job runtime (#3896,
+ * `../../scripts/build-wave-runtime.mjs`) can swap in a bundled ajv here
+ * instead of a `require` resolved next to an installed chant.
+ */
+import { createRequire } from "node:module";
+
+export type Ajv2020Class = new (opts: object) => { compile(schema: object): unknown };
+
+export function loadAjv2020(): Ajv2020Class {
+  const require = createRequire(import.meta.url);
+  // ajv is CommonJS; its class is the default export, or that export's own default.
+  const mod = require("ajv/dist/2020") as { default?: unknown };
+  return (mod.default ?? mod) as Ajv2020Class;
+}

package/src/workspace/declaration.ts

@@ -16,15 +16,14 @@
  * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
  */
 
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
 import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import type { ReasonCode } from "./reason-codes";
 import { joinPath, type WorkspaceTree } from "./tree";
+import { loadAjv2020 } from "./ajv2020";
+import { readChantPackageVersion } from "../package-version";
 
 export const DECLARATION_SCHEMA_ID = schema.$id;
 export const DECLARATION_FILES = ["chant.workspace.json", "chant.workspace.jsonc"] as const;
@@ -601,9 +600,7 @@ let readerVersionCache: string | undefined;
  * well under a millisecond.
  */
 export function readerVersion(): string {
-  readerVersionCache ??= (
-    JSON.parse(readFileSync(fileURLToPath(new URL("../../package.json", import.meta.url)), "utf-8")) as { version: string }
-  ).version;
+  readerVersionCache ??= readChantPackageVersion();
   return readerVersionCache;
 }
 
@@ -638,10 +635,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
   return compiled;
 }

package/src/workspace/kinds.ts

@@ -18,13 +18,13 @@
  */
 
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";
 import { dataExportTarget, findInstalledPackage } from "./class-data";
+import { loadAjv2020 } from "./ajv2020";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -353,10 +353,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
   return compiled;
 }

package/src/workspace/lineage-migrations.ts

@@ -26,6 +26,7 @@ import { z } from "zod";
 import { LockError, type Lineage } from "./lineage-lock";
 import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError, type Version } from "./lineage-version";
 import { ensureTypeScriptLoader } from "../ts-loader";
+import { esModuleNamespace } from "../module-interop";
 
 /** Where a template keeps its migrations, relative to the template's directory. */
 export const MIGRATIONS_DIR = ".chant/migrations";
@@ -283,7 +284,7 @@ export async function runMigration(m: LoadedMigration, opts: RunMigrationOptions
       writeFileSync(abs, data);
     }
     ensureTypeScriptLoader();
-    const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
+    const mod = esModuleNamespace((await import(pathToFileURL(file).href)) as { default?: unknown });
     if (typeof mod.default !== "function") throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
     await (mod.default as (ctx: { dir: string }) => unknown)({ dir: opts.dir });
   } else {

package/src/workspace/points.ts

@@ -33,12 +33,12 @@
  */
 
 import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import schema from "./decision-points.schema.json" with { type: "json" };
 import type { ReasonCode } from "./reason-codes";
 import type { RecordSource } from "./record-source";
 import type { LoadedRecordKind, ReadRecordsOptions, RecordEntry } from "./records";
+import { loadAjv2020 } from "./ajv2020";
 
 export const DECISION_POINTS_SCHEMA_ID = schema.$id;
 
@@ -200,10 +200,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: false }).compile(schema);
   return compiled;
 }

package/src/workspace/principal-classes.ts

@@ -22,13 +22,13 @@
  * installed package, which must be at the version the base pins.
  */
 
-import { createRequire } from "node:module";
 import { checkClassData, diskFiles, mergePinClasses, readClassFiles, type ClassData, type PackageFiles, type PinClassRead } from "./class-data";
 import { pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
 import schema from "./workspace-principals.schema.json" with { type: "json" };
 import type { TrustPolicy } from "./trust/policy";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, grantedClasses, type PrincipalClass } from "./identity-gate-rule";
+import { loadAjv2020 } from "./ajv2020";
 
 export const PRINCIPALS_SCHEMA_ID = schema.$id;
 
@@ -99,10 +99,7 @@ type Validate = ((data: unknown) => boolean) & { errors?: AjvError[] | null };
 let compiled: Validate | undefined;
 function validator(): Validate {
   if (compiled) return compiled;
-  const require = createRequire(import.meta.url);
-  // ajv is CommonJS; its class is the default export, or that export's own default.
-  const mod = require("ajv/dist/2020") as { default?: unknown };
-  const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): Validate };
+  const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): Validate };
   compiled = new Ajv({ allErrors: true, strict: true }).compile(schema);
   return compiled;
 }