@intentius/chant 0.24.0 → 0.26.0

package/src/discovery/sandbox/config-run.ts

@@ -0,0 +1,130 @@
+import { realpathSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { bundleDriver } from "./bundle";
+import { generateConfigDriverSource } from "./driver";
+import { formatConfigWireOffenders, type ConfigWireOffender } from "./config-wire";
+import { forkSandboxed } from "./fork";
+import { ENV_VAR } from "../../env";
+
+/**
+ * chant #1113 — evaluates a project's `chant.config.ts` inside the same
+ * sandboxed child `--sandbox` already uses for run-fallback source, and brings
+ * back plain JSON.
+ *
+ * This closes the residual chant #1093 documented and #1113 filed: `loadConfig`
+ * imported the project's own `chant.config.ts` into the CLI process, so a
+ * hostile repo's config executed with full CLI trust even under `--sandbox`.
+ * The config is project-authored code like any other file in the repo; the
+ * only reason it was ever treated differently is that the CLI has to read it
+ * before it knows anything else about the project.
+ *
+ * Deliberately the same machinery, not a parallel one:
+ *  - `./bundle.ts` bundles the generated driver (`./driver.ts`'s
+ *    `generateConfigDriverSource`) with esbuild, so the child needs no runtime
+ *    module resolution and no TypeScript loader.
+ *  - `./fork.ts` spawns it with the identical `--permission` profile
+ *    `runFallbackFilesSandboxed` uses — one function, so the two cannot drift.
+ *  - `./child-errors.ts` classifies whatever it throws, so a permission denial
+ *    names the config file instead of leaking `ERR_ACCESS_DENIED`.
+ *
+ * The one deliberate difference from the run-fallback child is `CHANT_ENV`.
+ * `../../cli/main.ts` sets it from `--env` *before* loading the config,
+ * specifically because a config may branch on the environment; dropping it
+ * would silently produce a different configuration under `--sandbox` than
+ * without. It is a value the user typed on the command line, not an ambient
+ * secret, so forwarding exactly that one key — and nothing else from
+ * `process.env` — keeps the scrub meaningful while keeping `--env` honest.
+ */
+
+/** How long to wait for the config child. A config is one small module; anything approaching this is hung, not slow. */
+const CONFIG_CHILD_TIMEOUT_MS = 60_000;
+
+interface ConfigChildResponse {
+  kind: "chant-config";
+  ok: boolean;
+  config?: unknown;
+  offenders?: ConfigWireOffender[];
+  error?: { name: string; file: string; message: string; type: string };
+}
+
+function isConfigChildResponse(value: unknown): value is ConfigChildResponse {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === "chant-config" &&
+    typeof (value as { ok?: unknown }).ok === "boolean"
+  );
+}
+
+export interface SandboxConfigResult {
+  /** The evaluated configuration, as plain JSON. Interpreted (default/config/namespace selection already applied in the child; Zod validation still to come) by `../../config.ts`'s `normalizeConfig`, in the parent, unchanged. */
+  config: unknown;
+  /** esbuild bundling wall-clock time. */
+  bundleMs: number;
+  /** Bundle size in bytes. */
+  bundleBytes: number;
+}
+
+/**
+ * Evaluate `configPath` in a sandboxed child and return its configuration as
+ * plain data.
+ *
+ * Throws — rather than degrading to an in-process import or to defaults — when
+ * the config cannot be evaluated inside the boundary or cannot cross it as
+ * JSON. Under `--sandbox` a config that "almost" loaded is not a safe thing to
+ * proceed with, and quietly falling back would give away the property the flag
+ * exists to provide.
+ *
+ * @param configPath - Absolute path to the project's `chant.config.ts`.
+ * @param projectRoot - Directory the child is granted `--allow-fs-read` for
+ *   (the config's own project root, i.e. `findProjectConfig`'s `dir`).
+ */
+export async function evaluateConfigSandboxed(
+  configPath: string,
+  projectRoot: string,
+): Promise<SandboxConfigResult> {
+  const driverSource = generateConfigDriverSource(configPath);
+  const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+
+  try {
+    let projectRealpath: string;
+    try {
+      projectRealpath = realpathSync(resolve(projectRoot));
+    } catch {
+      projectRealpath = resolve(projectRoot);
+    }
+
+    const env: Record<string, string> = { PATH: process.env.PATH ?? "" };
+    // See the module doc: the one forwarded variable, and only when set.
+    const activeEnv = process.env[ENV_VAR];
+    if (activeEnv) env[ENV_VAR] = activeEnv;
+
+    const response = await forkSandboxed(
+      {
+        bundlePath,
+        bundleDir,
+        projectRealpath,
+        externalReadPaths,
+        env,
+        timeoutMs: CONFIG_CHILD_TIMEOUT_MS,
+        label: `sandboxed evaluation of ${configPath}`,
+      },
+      isConfigChildResponse,
+    );
+
+    if (!response.ok) {
+      if (response.offenders && response.offenders.length > 0) {
+        throw new Error(formatConfigWireOffenders(configPath, response.offenders));
+      }
+      throw new Error(
+        response.error?.message
+          ? `Failed to evaluate ${configPath} inside the --sandbox boundary: ${response.error.message}`
+          : `Failed to evaluate ${configPath} inside the --sandbox boundary`,
+      );
+    }
+
+    return { config: response.config ?? {}, bundleMs: durationMs, bundleBytes: bytes };
+  } finally {
+    rmSync(bundleDir, { recursive: true, force: true });
+  }
+}

package/src/discovery/sandbox/config-wire.test.ts

@@ -0,0 +1,110 @@
+import { describe, test, expect } from "vitest";
+import { scanConfigWireSafety, formatConfigWireOffenders } from "./config-wire";
+
+/**
+ * chant #1113 — the contract for what a `chant.config.ts` may hold if it is to
+ * be evaluated inside the `--sandbox` boundary. Only JSON crosses a process
+ * boundary, and `JSON.stringify` is lossy without complaining, so this scan is
+ * what turns "silently dropped" into "named and refused".
+ */
+describe("scanConfigWireSafety", () => {
+  test("a real ChantConfig has nothing that cannot cross", () => {
+    expect(
+      scanConfigWireSafety({
+        lexicons: ["aws", "k8s"],
+        environments: ["staging", "prod"],
+        sourceDir: "src",
+        stacks: [{ name: "net", src: "src/net" }],
+        ownership: { stack: "storefront", env: "prod", enabled: true },
+        build: { fold: true, sandbox: true },
+        buildParams: { tier: { type: "string", default: "light", enum: ["light", "prod"] } },
+        lint: { rules: { COR001: "error", COR002: ["warning", { max: 3 }] }, policies: ["policies/org.ts"] },
+        vulnPolicy: { failSeverity: "critical", license: { allow: ["MIT"], deny: [] } },
+        // A lexicon's passthrough extension (the temporal lexicon's shape) —
+        // still pure data.
+        temporal: { profiles: { local: { address: "localhost:7233", tls: false } }, defaultProfile: "local" },
+      }),
+    ).toEqual([]);
+  });
+
+  test("null, empty objects and empty arrays are data", () => {
+    expect(scanConfigWireSafety({ a: null, b: {}, c: [], d: 0, e: false, f: "" })).toEqual([]);
+  });
+
+  test.each([
+    ["a function", { hooks: { before: () => 1 } }, "hooks.before", "a function"],
+    ["a Date", { meta: { at: new Date(0) } }, "meta.at", "a Date"],
+    ["a RegExp", { match: /x/ }, "match", "a RegExp"],
+    ["a Map", { m: new Map() }, "m", "a Map"],
+    ["a Set", { s: new Set() }, "s", "a Set"],
+    ["a bigint", { n: 1n }, "n", "a bigint"],
+    ["NaN", { n: Number.NaN }, "n", "NaN"],
+    ["Infinity", { n: Number.POSITIVE_INFINITY }, "n", "a non-finite number"],
+    ["a symbol", { s: Symbol("x") }, "s", "a symbol"],
+  ])("%s is reported with its key path", (_label, config, path, found) => {
+    expect(scanConfigWireSafety(config)).toEqual([{ path, found }]);
+  });
+
+  test("array positions are reported with an index", () => {
+    expect(scanConfigWireSafety({ stacks: [{ name: "a", src: "s" }, { name: "b", src: () => "s" }] })).toEqual([
+      { path: "stacks[1].src", found: "a function" },
+    ]);
+  });
+
+  test("a class instance is reported by its constructor name", () => {
+    class Policy {
+      value = 1;
+    }
+    expect(scanConfigWireSafety({ p: new Policy() })).toEqual([{ path: "p", found: "a Policy instance" }]);
+  });
+
+  test("a circular reference is reported, not walked forever", () => {
+    const a: Record<string, unknown> = { name: "a" };
+    a.self = a;
+    expect(scanConfigWireSafety({ a })).toEqual([{ path: "a.self", found: "a circular reference" }]);
+  });
+
+  test("every offender is reported, not just the first", () => {
+    expect(scanConfigWireSafety({ a: () => 1, b: { c: new Date(0) } })).toEqual([
+      { path: "a", found: "a function" },
+      { path: "b.c", found: "a Date" },
+    ]);
+  });
+
+  /**
+   * The one accepted lossy case, and its boundary: `{ x: undefined }` reads
+   * identically to `{}` for every consumer of `ChantConfig` (every field is
+   * optional), while an `undefined` in an ARRAY becomes `null` and changes the
+   * element — so only the latter is reported. See the module doc.
+   */
+  test("an undefined property is dropped like an omitted key; an undefined array slot is not", () => {
+    expect(scanConfigWireSafety({ sourceDir: undefined, lexicons: ["aws"] })).toEqual([]);
+    expect(scanConfigWireSafety({ lexicons: ["aws", undefined] })).toEqual([
+      { path: "lexicons[1]", found: "undefined" },
+    ]);
+  });
+
+  test("a module namespace (a config of top-level named exports) is walked, not rejected wholesale", () => {
+    const namespace = Object.create(null) as Record<string, unknown>;
+    namespace.lexicons = ["aws"];
+    expect(scanConfigWireSafety(namespace)).toEqual([]);
+  });
+
+  test("a non-object config says nothing about serializability — normalizeConfig rejects it", () => {
+    expect(scanConfigWireSafety("nope")).toEqual([]);
+    expect(scanConfigWireSafety(null)).toEqual([]);
+  });
+});
+
+describe("formatConfigWireOffenders", () => {
+  test("names the config file, every offending key, and what to do", () => {
+    const message = formatConfigWireOffenders("/p/chant.config.ts", [
+      { path: "hooks.before", found: "a function" },
+      { path: "meta.at", found: "a Date" },
+    ]);
+    expect(message).toContain("/p/chant.config.ts");
+    expect(message).toContain("hooks.before: a function");
+    expect(message).toContain("meta.at: a Date");
+    expect(message).toContain("drop --sandbox");
+  });
+});

package/src/discovery/sandbox/config-wire.ts

@@ -0,0 +1,195 @@
+/**
+ * chant #1113 — what a `chant.config.ts` may contain if it is to be evaluated
+ * inside the sandbox boundary and handed back to the CLI as data.
+ *
+ * Under `--sandbox` the config file is evaluated in a child process (see
+ * `./config-run.ts`), so the only thing that can come back is what survives a
+ * process boundary: JSON. Node's IPC channel serializes with `JSON.stringify`
+ * by default, and `JSON.stringify` is *lossy without complaining* — a function
+ * property vanishes, a `Date` becomes a string, a `Map` becomes `{}`, `NaN`
+ * becomes `null`. Silently handing the CLI a config that differs from the one
+ * the project wrote is the worst available outcome for a security feature, so
+ * this module walks the value FIRST and reports every offending key path.
+ * `./config-run.ts` turns a non-empty report into a build error that names the
+ * keys; nothing is ever dropped quietly.
+ *
+ * This module is bundled INTO the generated config driver (`./driver.ts`'s
+ * `generateConfigDriverSource`) and runs inside the sandboxed child, next to
+ * the project code it is inspecting — so it must not import anything, and must
+ * not touch the filesystem, the environment or the process.
+ *
+ * chant #1131 reuses the same walk for the OTHER direction: a `lint.policies`
+ * check runs inside a sandboxed child and its `PostSynthDiagnostic[]` has to
+ * come back as data (`./policy-wire.ts`). That is the same "JSON is lossy
+ * without complaining" problem with a different root value, so the walk is
+ * exported as {@link scanValueWireSafety} rather than copied.
+ *
+ * ## What `ChantConfig` legally holds
+ *
+ * Every field of `ChantConfig` (`../../config.ts`) is JSON data: string arrays
+ * (`lexicons`, `capabilities`, `environments`), strings (`sourceDir`), nested
+ * plain objects of strings/booleans (`ownership`, `build`, `release`, `sbom`,
+ * `signing`, `vulnPolicy`), arrays of plain objects (`stacks`), and records of
+ * plain objects (`buildParams`). `lint` is a `LintConfig`, whose rule values
+ * are a severity string or a `[severity, options]` tuple, and whose `plugins`
+ * / `policies` are file *paths* — chant loads those modules itself, they are
+ * not functions embedded in the config. So the declared type admits nothing
+ * that fails the check below.
+ *
+ * The one way to get there is `ChantConfigSchema`'s `.passthrough()`, which
+ * accepts unknown extra keys of any type (that is how a lexicon extends the
+ * config — `temporal:` in the temporal lexicon's `TemporalChantConfig`, itself
+ * pure data). A project that parks a function under such a key gets a clear
+ * error naming it, rather than a config that silently lost it.
+ *
+ * ## The one accepted lossy case: `undefined` object properties
+ *
+ * `{ sourceDir: undefined }` and `{}` are indistinguishable to every reader of
+ * `ChantConfig` — each field is optional and every resolver tests
+ * `config.x === undefined` / `?.` — so an `undefined`-valued property is
+ * dropped rather than rejected, exactly as omitting the key would be. An
+ * `undefined` inside an ARRAY is a different story (`JSON.stringify` rewrites
+ * it to `null`, changing the element), and is reported.
+ */
+
+/** One value in the config that cannot cross the sandbox boundary as data. */
+export interface ConfigWireOffender {
+  /** Dotted/bracketed path from the config root, e.g. `lint.rules.foo` or `stacks[0].name`. */
+  path: string;
+  /** What was found there, phrased for an error message (e.g. `a function`, `a Date`). */
+  found: string;
+}
+
+/** Deepest nesting `scanConfigWireSafety` will walk before reporting the path as too deep (also the cycle backstop for exotic self-referential structures). */
+const MAX_DEPTH = 64;
+
+function describe(value: unknown): string {
+  const t = typeof value;
+  if (t === "function") return "a function";
+  if (t === "symbol") return "a symbol";
+  if (t === "bigint") return "a bigint";
+  if (t === "number") return Number.isNaN(value) ? "NaN" : "a non-finite number";
+  if (value instanceof Date) return "a Date";
+  if (value instanceof RegExp) return "a RegExp";
+  if (value instanceof Map) return "a Map";
+  if (value instanceof Set) return "a Set";
+  if (value instanceof Promise) return "a Promise";
+  if (value instanceof Error) return "an Error";
+  const ctor = (value as { constructor?: { name?: unknown } })?.constructor?.name;
+  return typeof ctor === "string" && ctor !== "Object" ? `a ${ctor} instance` : "a non-plain object";
+}
+
+/** A plain object literal (or a null-prototype object) — anything else with `typeof "object"` is a class instance chant refuses to guess at. */
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+function walk(
+  value: unknown,
+  path: string,
+  depth: number,
+  seen: Set<object>,
+  out: ConfigWireOffender[],
+): void {
+  if (value === null) return;
+
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return;
+  if (t === "number") {
+    if (!Number.isFinite(value as number)) out.push({ path, found: describe(value) });
+    return;
+  }
+  if (t === "function" || t === "symbol" || t === "bigint" || t === "undefined") {
+    // `undefined` reaches here only from an array slot — an object property
+    // holding `undefined` is skipped by the caller (see the module doc).
+    out.push({ path, found: t === "undefined" ? "undefined" : describe(value) });
+    return;
+  }
+
+  const obj = value as object;
+  if (seen.has(obj)) {
+    out.push({ path, found: "a circular reference" });
+    return;
+  }
+  if (depth > MAX_DEPTH) {
+    out.push({ path, found: `nested more than ${MAX_DEPTH} levels deep` });
+    return;
+  }
+
+  if (Array.isArray(obj)) {
+    seen.add(obj);
+    for (let i = 0; i < obj.length; i++) walk(obj[i], `${path}[${i}]`, depth + 1, seen, out);
+    seen.delete(obj);
+    return;
+  }
+
+  if (!isPlainObject(obj)) {
+    out.push({ path, found: describe(obj) });
+    return;
+  }
+
+  seen.add(obj);
+  for (const key of Object.keys(obj)) {
+    const child = (obj as Record<string, unknown>)[key];
+    if (child === undefined) continue; // dropped, equivalent to omitting the key — see the module doc
+    const childPath = path ? `${path}.${key}` : key;
+    walk(child, childPath, depth + 1, seen, out);
+  }
+  seen.delete(obj);
+}
+
+/**
+ * chant #1131 — report every value ANYWHERE in `value` that cannot cross the
+ * sandbox boundary as JSON, with paths rooted at `rootPath`.
+ *
+ * {@link scanConfigWireSafety} is the config-shaped entry point (it tolerates a
+ * module namespace object at the root); this one takes the value as given, so
+ * an array root (`diagnostics`) or a plain object root both work. Same rules,
+ * same `undefined`-object-property allowance — see the module doc.
+ */
+export function scanValueWireSafety(value: unknown, rootPath = ""): ConfigWireOffender[] {
+  const out: ConfigWireOffender[] = [];
+  walk(value, rootPath, 0, new Set<object>(), out);
+  return out;
+}
+
+/**
+ * Report every value in `config` that cannot cross the sandbox boundary as
+ * JSON. An empty array means a `JSON.parse(JSON.stringify(config))` round-trip
+ * preserves the configuration exactly (modulo `undefined` object properties,
+ * which are dropped — see the module doc).
+ *
+ * `config` itself may be a module namespace object (`await import(...)` with
+ * no `default` export), which is not a plain object; its own enumerable keys
+ * are walked the same way rather than being reported wholesale.
+ */
+export function scanConfigWireSafety(config: unknown): ConfigWireOffender[] {
+  const out: ConfigWireOffender[] = [];
+  if (config === null || typeof config !== "object") {
+    // A non-object config is what `normalizeConfig` already rejects in the
+    // parent; nothing to say about serializability.
+    return out;
+  }
+  const seen = new Set<object>();
+  seen.add(config);
+  for (const key of Object.keys(config as Record<string, unknown>)) {
+    const child = (config as Record<string, unknown>)[key];
+    if (child === undefined) continue;
+    walk(child, key, 1, seen, out);
+  }
+  return out;
+}
+
+/** Render a {@link ConfigWireOffender} list as the body of a build error — one line per offending key, most specific information first. */
+export function formatConfigWireOffenders(
+  configPath: string,
+  offenders: readonly ConfigWireOffender[],
+): string {
+  const lines = offenders.map((o) => `  ${o.path || "<root>"}: ${o.found}`);
+  return [
+    `Cannot evaluate ${configPath} inside the --sandbox boundary: it holds values that are not data.`,
+    ...lines,
+    `Under --sandbox the config is evaluated in an isolated child process and only JSON crosses back, so every value must be a string, number, boolean, null, array or plain object. Move the offending value out of chant.config.ts (lint rule plugins and policy checks are referenced by path, not embedded), or drop --sandbox for this build.`,
+  ].join("\n");
+}

package/src/discovery/sandbox/driver.ts

@@ -41,6 +41,11 @@ const RESOLVE_MODULE = join(DISCOVERY_DIR, "resolve.ts");
 const ENTITY_WIRE_CODEC_MODULE = join(DISCOVERY_DIR, "entity-wire-codec.ts");
 const CHILD_ERRORS_MODULE = join(HERE, "child-errors.ts");
 const PROVENANCE_MODULE = join(dirname(DISCOVERY_DIR), "provenance.ts");
+// chant #1113 — the config driver's serializability contract (see ./config-wire.ts).
+const CONFIG_WIRE_MODULE = join(HERE, "config-wire.ts");
+// chant #1131 — the policy driver's build-result decoding + diagnostics contract.
+const POLICY_WIRE_MODULE = join(HERE, "policy-wire.ts");
+const POST_SYNTH_MODULE = join(dirname(DISCOVERY_DIR), "lint", "post-synth.ts");
 
 export interface GenerateDriverOptions {
   /** Absolute paths to the run-fallback files this build decided NOT to fold — see `discover()`'s fold/taint loop in `../index.ts`. */
@@ -145,3 +150,198 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
 
   return lines.join("\n");
 }
+
+/**
+ * chant #1113 — generate the driver module that evaluates a project's
+ * `chant.config.ts` INSIDE the sandboxed child and hands back plain JSON.
+ *
+ * Same machinery as {@link generateDriverSource} above, deliberately: one
+ * literal-specifier dynamic `import()` esbuild can trace and inline, one IPC
+ * message back, `./child-errors.ts` for classification so a permission denial
+ * names the config file rather than leaking `ERR_ACCESS_DENIED`. The only
+ * difference is what crosses — a config is data, not an entity graph, so there
+ * is no naming/`AttrRef` step and no `EntitySetWire`; the child instead runs
+ * `./config-wire.ts`'s serializability scan and refuses to hand back a config
+ * that `JSON.stringify` would silently mangle.
+ *
+ * The child returns the raw module namespace's chosen export as-is — the
+ * `default ?? config ?? namespace` selection and Zod validation
+ * (`normalizeConfig`) stay in the parent, where they were, so `--sandbox`
+ * changes where the file is *evaluated* and nothing about how its result is
+ * interpreted.
+ */
+export function generateConfigDriverSource(configPath: string): string {
+  return [
+    `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    `import { scanConfigWireSafety } from ${lit(CONFIG_WIRE_MODULE)};`,
+    ``,
+    `function send(payload) {`,
+    `  if (typeof process.send === "function") process.send(payload);`,
+    `  else console.log(JSON.stringify(payload));`,
+    `}`,
+    ``,
+    `async function main() {`,
+    `  let namespace;`,
+    `  try {`,
+    `    namespace = await import(${lit(configPath)});`,
+    `  } catch (err) {`,
+    `    send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
+    `    return;`,
+    `  }`,
+    ``,
+    // Mirrors loadChantConfig's own selection so the scan sees exactly the
+    // object the parent will normalize. A namespace object is not a plain
+    // object; scanConfigWireSafety walks its own keys rather than rejecting it.
+    `  const selected = namespace.default ?? namespace.config ?? namespace;`,
+    ``,
+    `  const offenders = scanConfigWireSafety(selected);`,
+    `  if (offenders.length > 0) {`,
+    `    send({ kind: "chant-config", ok: false, offenders });`,
+    `    return;`,
+    `  }`,
+    ``,
+    `  try {`,
+    // Round-trip here, not just at the IPC boundary: this is what proves the
+    // payload really is JSON before it leaves the child, and turns anything
+    // the scan somehow missed into a named error instead of a quiet drop.
+    `    const config = JSON.parse(JSON.stringify(selected ?? {}));`,
+    `    send({ kind: "chant-config", ok: true, config });`,
+    `  } catch (err) {`,
+    `    send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err, "resolution").toJSON() });`,
+    `  }`,
+    `}`,
+    ``,
+    `main().catch((err) => {`,
+    `  send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
+    `});`,
+  ].join("\n");
+}
+
+/**
+ * chant #1131 — generate the driver module that imports a project's
+ * `lint.policies` modules INSIDE the sandboxed child, runs their checks over
+ * the build result the parent hands it, and sends back plain
+ * `PostSynthDiagnostic`s.
+ *
+ * Same machinery again: literal-specifier dynamic `import()`s esbuild can trace
+ * and inline, `./child-errors.ts` for classification so a permission denial
+ * names the policy file, one IPC message back. Two things are specific to this
+ * one:
+ *
+ *  - **It receives before it sends.** The run and config drivers are fully
+ *    parameterized by their generated source; a policy check needs the finished
+ *    build result, which is neither known at bundle time nor something to bake
+ *    into a source literal. It arrives as one IPC message (see `./fork.ts`'s
+ *    `send`). The `process.on("message", …)` registration is top-level and
+ *    synchronous, so it is in place before the event loop can deliver anything
+ *    — a message the parent sent before the child finished booting is queued on
+ *    the channel, not lost.
+ *  - **Checks run wrapped, not raw.** `runPostSynthChecks` (chant's own, from
+ *    `../../lint/post-synth.ts`) is invoked ONCE over every check from every
+ *    policy module, exactly as `cli/commands/build.ts` invokes it in-process —
+ *    so the checks share one `PostSynthContext` and run in one order, and the
+ *    diagnostics come back in the same sequence. The wrapper around each check
+ *    is what makes a bad return value attributable: it scans that check's own
+ *    output and throws a `PolicyWireError` naming the module the check was
+ *    loaded from, rather than reporting an offending index in a merged array.
+ */
+export function generatePolicyDriverSource(policyPaths: readonly string[]): string {
+  const lines: string[] = [
+    `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+    `import { decodePolicyBuildResult, scanPolicyDiagnostics, PolicyWireError } from ${lit(POLICY_WIRE_MODULE)};`,
+    `import { runPostSynthChecks, isPostSynthCheck } from ${lit(POST_SYNTH_MODULE)};`,
+    ``,
+    `function send(payload) {`,
+    `  if (typeof process.send === "function") process.send(payload);`,
+    `  else console.log(JSON.stringify(payload));`,
+    `}`,
+    ``,
+    `function fail(file, err, type) {`,
+    `  if (err instanceof PolicyWireError) {`,
+    `    send({ kind: "chant-policy", ok: false, offenders: err.offenders });`,
+    `    return;`,
+    `  }`,
+    `  send({ kind: "chant-policy", ok: false, error: classifyChildError(file, err, type).toJSON() });`,
+    `}`,
+    ``,
+    // The wrapper described in the doc above: same id/description so any
+    // chant-side reporting keyed off them is unchanged, same ctx, same return
+    // value — plus the per-check serializability scan.
+    `function guard(check, policy) {`,
+    `  return {`,
+    `    id: check.id,`,
+    `    description: check.description,`,
+    `    check(ctx) {`,
+    `      const produced = check.check(ctx);`,
+    `      const offenders = scanPolicyDiagnostics(produced, policy);`,
+    `      if (offenders.length > 0) throw new PolicyWireError(offenders);`,
+    `      return produced;`,
+    `    },`,
+    `  };`,
+    `}`,
+    ``,
+    `async function main(request) {`,
+    `  let buildResult;`,
+    `  try {`,
+    `    buildResult = decodePolicyBuildResult(request.buildResult);`,
+    `  } catch (err) {`,
+    `    fail("", err, "resolution");`,
+    `    return;`,
+    `  }`,
+    ``,
+    `  const checks = [];`,
+  ];
+
+  // One block per policy module, in the order `lint.policies` declares them —
+  // the same order `loadPolicyChecks` collects in, so the diagnostics sequence
+  // matches the in-process one exactly.
+  for (const policyPath of policyPaths) {
+    lines.push(
+      `  try {`,
+      `    const mod = await import(${lit(policyPath)});`,
+      `    for (const value of Object.values(mod)) {`,
+      `      if (isPostSynthCheck(value)) checks.push(guard(value, ${lit(policyPath)}));`,
+      `    }`,
+      `  } catch (err) {`,
+      `    fail(${lit(policyPath)}, err, "import");`,
+      `    return;`,
+      `  }`,
+    );
+  }
+
+  lines.push(
+    ``,
+    `  let diagnostics;`,
+    `  try {`,
+    `    diagnostics = runPostSynthChecks(checks, buildResult, request.env ?? undefined);`,
+    `  } catch (err) {`,
+    `    fail("", err, "resolution");`,
+    `    return;`,
+    `  }`,
+    ``,
+    `  send({ kind: "chant-policy", ok: true, diagnostics });`,
+    `}`,
+    ``,
+    // Registered synchronously at module top level — see the doc above on why
+    // that is what makes the parent's send-before-boot safe.
+    //
+    // Removed again as soon as the input arrives, and that is not tidiness: a
+    // `message` listener REFS the IPC channel, so leaving it registered would
+    // keep this child's event loop alive after it had already answered — and a
+    // live channel keeps the PARENT's alive too. `chant build` would not have
+    // noticed (`cli/main.ts` ends in `process.exit`); anything embedding chant
+    // as a library would have hung. `./fork.ts` kills the child on receipt as
+    // the other half of the same fix.
+    `let started = false;`,
+    `function onRequest(request) {`,
+    `  if (started) return;`,
+    `  if (!request || request.kind !== "chant-policy-request") return;`,
+    `  started = true;`,
+    `  process.off("message", onRequest);`,
+    `  main(request).catch((err) => fail("", err, "resolution"));`,
+    `}`,
+    `process.on("message", onRequest);`,
+  );
+
+  return lines.join("\n");
+}