@intentius/chant 0.124.14 → 0.124.16

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/__fixtures__/contract-repo.ts

@@ -4,7 +4,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
@@ -56,6 +56,22 @@ export function repo(files: Record<string, string | { text: string; mode: number
   return root;
 }
 
+/**
+ * Build a fixture repository once per test file and hand each caller a copy of
+ * it. A repo costs a dozen git processes (init, add, commit, config), and a
+ * file copy none, so a file whose tests each start from the same repo builds
+ * it once (#3880). The template is rebuilt if {@link cleanScratch} removed it.
+ */
+export function repoFixture(build: () => string, prefix = "chant-contract-copy-"): () => string {
+  let template: string | undefined;
+  return () => {
+    if (template === undefined || !existsSync(template)) template = build();
+    const root = scratchDir(prefix);
+    cpSync(template, root, { recursive: true });
+    return root;
+  };
+}
+
 export function commitAll(root: string, message = "next"): string {
   git(root, "add", "-A");
   git(root, "commit", "-q", "-m", message);

package/src/workspace/__fixtures__/sessions.ts

@@ -7,19 +7,19 @@
 import { cpSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { sessionSeal } from "../record-sessions";
-import { commitAll, git, REPO, scratchDir } from "./contract-repo";
+import { commitAll, git, REPO, repoFixture, scratchDir } from "./contract-repo";
 
 export const SESSIONS_KIND = "design/sessions/session.kind.mjs";
 export const DECISIONS_KIND = "decisions/decision.kind.mjs";
 
 /** A git repository holding a copy of the reference workspace's decisions and design member. */
-export function sessionsRepo(): string {
+export const sessionsRepo = repoFixture(() => {
   const root = scratchDir("chant-sessions-");
   for (const d of ["decisions", "design"]) cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
   git(root, "init", "-q");
   commitAll(root, "reference");
   return root;
-}
+}, "chant-sessions-");
 
 /** A session file's text, sealed when it is closed. */
 export function sessionText(s: { id: string; state: "open" | "closed"; verdicts?: { record: string; principal: string; verdict: string }[]; agenda?: string[] }): string {

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/change-set.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
   "title": "change-set document",
-  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu and warden members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu, warden and sql members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
   "type": "object",
   "required": [
     "$schema",
@@ -87,7 +87,8 @@
             "tofu",
             "choudoufu",
             "chant",
-            "warden"
+            "warden",
+            "sql"
           ]
         },
         "scope": {
@@ -171,7 +172,8 @@
             "tofu",
             "choudoufu",
             "chant",
-            "warden"
+            "warden",
+            "sql"
           ]
         },
         "address": {

package/src/workspace/ci-green-workflow.test.ts

@@ -124,15 +124,15 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
   });
 
-  test("--token-secret checks out with the secret, so the push uses it, and nothing else changes", () => {
+  test("--token-secret checks out with the secret, or the Actions token where it is unset (#3624), and nothing else changes", () => {
     const plain = renderCiGreenWorkflow(base);
     const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
     const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN }}" } });
+    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
     // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
     expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
-    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN }}\n", "")).toBe(plain);
+    expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN || github.token }}\n", "")).toBe(plain);
   });
 
   test("--app-id-var and --app-key-secret mint an App token before the checkout and check out with it", () => {
@@ -228,7 +228,7 @@ describe("chant ci workflow (#3573)", () => {
       const withToken = readFileSync(file, "utf-8");
       expect(withToken.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --token-secret CI_GREEN_TOKEN (in the workspace root)`);
       const steps = (parseYAMLDocument(withToken) as Yaml).jobs.tick.steps;
-      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN }}");
+      expect(steps[0].with.token).toBe("${{ secrets.CI_GREEN_TOKEN || github.token }}");
       expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
 
       const app = { args: { ciAppIdVar: "CI_GREEN_APP_ID", ciAppKeySecret: "CI_GREEN_APP_KEY" } } as unknown as CommandContext;

package/src/workspace/ci-green-workflow.ts

@@ -27,7 +27,9 @@
  * commit whose workflow files differ from the default branch's as an update
  * to those workflows, and the Actions token can never hold the `workflows`
  * permission, so it is refused there. `--token-secret <NAME>` checks out
- * with `secrets.<NAME>` instead, and `--app-id-var <VAR> --app-key-secret
+ * with `secrets.<NAME>` instead, falling back to the Actions token where the
+ * secret is unset (#3624), so a fork or a fresh clone still tags the commits
+ * that change no workflow file; and `--app-id-var <VAR> --app-key-secret
  * <NAME>` mints a GitHub App token first and checks out with that. The
  * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
  * a fine-grained personal access token can't call the Checks API.
@@ -44,6 +46,7 @@ import { GENERATED_MARKER } from "../discovery/files";
 import { parseYAMLDocument } from "../yaml";
 import type { CiGreen } from "./declaration";
 import { matchesCheckRun } from "./ci-green";
+import { githubSecretOrJobToken } from "../ci-jobs";
 
 /** Where the workflow goes, relative to the repository root. */
 export const CI_GREEN_WORKFLOW_FILE = ".github/workflows/chant-ci-green.yml";
@@ -185,7 +188,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
           `          private-key: \${{ secrets.${push.appKeySecret} }}`,
         ]
       : [];
-  const token = !push ? [] : ["secret" in push ? `          token: \${{ secrets.${push.secret} }}` : "          token: ${{ steps.app-token.outputs.token }}"];
+  const token = !push ? [] : ["secret" in push ? `          token: ${githubSecretOrJobToken(push.secret)}` : "          token: ${{ steps.app-token.outputs.token }}"];
   const lines = [
     `name: ${CI_GREEN_WORKFLOW_NAME}`,
     "",