@intentius/chant 0.24.0 → 0.26.0

package/src/discovery/sandbox/fork.ts

@@ -0,0 +1,148 @@
+import { fork } from "node:child_process";
+
+/**
+ * The one place chant starts a sandboxed child process.
+ *
+ * Extracted from `./run.ts` by chant #1113, which added a SECOND thing that
+ * has to run behind the same boundary (`chant.config.ts` evaluation, see
+ * `./config-run.ts`). Both callers must get the identical `--permission`
+ * profile and the identical environment scrub — if the two drifted, the
+ * weaker one would silently become the boundary. Keeping the spawn itself in
+ * one function is the cheapest way to make "same profile" a fact rather than
+ * a claim.
+ *
+ * Isolation mechanics (verified on Node v24.13.1 — see the chant#1045 PR
+ * description for the full write-up):
+ *  - `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted
+ *    external package dirs>]` — no filesystem write, no child-process, no
+ *    worker-thread access. Bundling with esbuild first (`./bundle.ts`) means
+ *    the child needs NO TypeScript loader (no `tsx`, so no `--allow-worker`
+ *    and no writable temp dir either).
+ *  - The env is a spawn-time scrub, not `--permission`: Node's Permission
+ *    Model does not gate `process.env` at all (confirmed: every key stays
+ *    readable even under `--permission`). See {@link SandboxForkOptions.env}.
+ *  - Network egress is NOT addressed — Node has no flag for it. See
+ *    `docs/.../architecture/sandbox.mdx` for the residual-risk statement.
+ */
+
+export interface SandboxForkOptions {
+  /** Absolute, realpath'd path to the bundled ESM entry file to run. */
+  bundlePath: string;
+  /** Absolute, realpath'd directory holding {@link bundlePath} — granted `--allow-fs-read`. */
+  bundleDir: string;
+  /** Absolute, realpath'd project directory — granted `--allow-fs-read`. */
+  projectRealpath: string;
+  /** Additional directories to grant `--allow-fs-read` (the resolved locations of `./bundle.ts`'s deliberately-unbundled trusted packages). */
+  externalReadPaths: readonly string[];
+  /**
+   * The child's ENTIRE environment. Callers pass an explicit, closed set —
+   * never a spread of `process.env`. `./run.ts` passes `PATH` only;
+   * `./config-run.ts` adds `CHANT_ENV` (see its doc for why that one
+   * variable, and only that one, is forwarded).
+   */
+  env: Record<string, string>;
+  /** How long to wait for the child's one IPC message before killing it. */
+  timeoutMs: number;
+  /** What timed out / exited early, for the error message (e.g. `"sandboxed run"`). */
+  label: string;
+  /**
+   * chant #1131 — an optional payload sent to the child over the SAME IPC
+   * channel its response comes back on, immediately after the fork.
+   *
+   * The run and config children are fully described by their generated driver
+   * source, so they need nothing inbound. The policy child does: its input is
+   * the finished build result, which exists only after the parent has merged
+   * and serialized, long after the bundle was built. Sending it rather than
+   * baking it into a source literal keeps the bundle small (esbuild would
+   * otherwise parse a multi-megabyte literal) and keeps it off disk.
+   *
+   * Safe to send before the child has booted: `child.send` writes to the IPC
+   * pipe and Node queues the message until the child's channel is read, and
+   * the driver registers its `process.on("message", …)` synchronously at module
+   * top level — before the event loop can deliver anything. This is NOT a
+   * second protocol: same channel, same JSON, same one-message-back response.
+   */
+  send?: Record<string, unknown>;
+}
+
+/**
+ * Fork `bundlePath` under `--permission` with a scrubbed environment, and
+ * resolve with the first IPC message that satisfies `isResponse` (or reject
+ * on crash / timeout / fork error).
+ */
+export function forkSandboxed<T>(
+  options: SandboxForkOptions,
+  isResponse: (value: unknown) => value is T,
+): Promise<T> {
+  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send } = options;
+
+  return new Promise((resolvePromise, reject) => {
+    const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
+      (p) => `--allow-fs-read=${p}`,
+    );
+    const child = fork(bundlePath, [], {
+      execArgv: ["--permission", ...readAllowances],
+      env,
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+
+    let settled = false;
+    let stderrBuf = "";
+
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    if (send !== undefined) {
+      child.send(send, (err) => {
+        if (settled || !err) return;
+        settled = true;
+        clearTimeout(timeout);
+        child.kill();
+        reject(new Error(`${label}: failed to send the child its input: ${err.message}`));
+      });
+    }
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+    });
+
+    child.on("message", (msg: unknown) => {
+      if (settled || !isResponse(msg)) return;
+      settled = true;
+      clearTimeout(timeout);
+      // chant #1131 — the child's entire job is to send this one message, so
+      // once it has arrived there is nothing left to wait for. Killing it here
+      // rather than hoping it exits on its own closes a real hang: an open
+      // handle on the child side (a `setInterval` in project source, an
+      // `http.Server` a policy started, or simply an IPC listener the driver
+      // registered to RECEIVE its input) keeps the child's event loop alive,
+      // and a live IPC channel then keeps the PARENT's alive too. `chant build`
+      // never noticed because `cli/main.ts` ends with `process.exit`; anything
+      // embedding chant as a library would have hung forever.
+      child.kill();
+      resolvePromise(msg);
+    });
+
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    child.on("exit", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      reject(
+        new Error(
+          `${label}: child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`,
+        ),
+      );
+    });
+  });
+}

package/src/discovery/sandbox/policy-boundary.test.ts

@@ -0,0 +1,325 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm, realpath, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+import type { Declarable } from "../../declarable";
+import { createResource } from "../../runtime";
+import { resolveAttrRefs } from "../resolve";
+import { ENV_VAR } from "../../env";
+import { loadPolicyChecks } from "../../lint/policy";
+import {
+  armSandboxPolicyExecution,
+  isSandboxPolicyExecutionArmed,
+  resetSandboxPolicyExecutionForTests,
+  runProjectPolicies,
+  type ProjectPolicyRun,
+} from "../../lint/policy-sandbox";
+
+/**
+ * chant #1131 — a `lint.policies` module is project-authored code, and under
+ * `--sandbox` neither its top level nor its `check` function may run in the
+ * CLI's process.
+ *
+ * Same shape of proof as `./fold-boundary.test.ts` (#1093) and
+ * `./config-boundary.test.ts` (#1113): the fixture policy sets a `globalThis`
+ * marker at module top level and another inside `check`, and a marker set in
+ * the sandboxed child cannot reach this process. **The unarmed half is asserted
+ * first**, so the probe is proven capable of firing before the armed half
+ * asserts it stays clean.
+ *
+ * Fixtures go to a fresh tmpdir per test — never the source tree — so no two
+ * tests share a module path and nothing bleeds through Node's module cache.
+ */
+
+const TOP_MARKER = "__chant1131PolicyTopLevel";
+const CHECK_MARKER = "__chant1131PolicyCheckRan";
+
+type MarkerHost = Record<string, boolean | undefined>;
+
+function marker(name: string): boolean | undefined {
+  return (globalThis as unknown as MarkerHost)[name];
+}
+
+/** A small, realistic build result: two entities with a cross-reference, plus one lexicon's serialized output. */
+function buildResultFixture(): ProjectPolicyRun["buildResult"] {
+  const Vpc = createResource("Test::Vpc", "test", { vpcId: "VpcId" });
+  const Ingress = createResource("Test::Ingress", "test", {});
+  const vpc = new Vpc({ CidrBlock: "10.0.0.0/16" });
+  const ingress = new Ingress({ VpcId: (vpc as unknown as Record<string, unknown>).vpcId, tls: [] });
+  const entities = new Map<string, Declarable>([
+    ["Vpc", vpc as unknown as Declarable],
+    ["Ingress", ingress as unknown as Declarable],
+  ]);
+  resolveAttrRefs(entities);
+
+  return {
+    outputs: new Map<string, string>([["test", "kind: Ingress\nmetadata:\n  name: storefront\n"]]),
+    entities,
+    warnings: [],
+    errors: [],
+    sourceFileCount: 2,
+  } as unknown as ProjectPolicyRun["buildResult"];
+}
+
+describe("lint.policies execution under --sandbox (chant #1131)", () => {
+  let testDir: string;
+  let savedEnv: string | undefined;
+
+  beforeEach(async () => {
+    const dir = join(tmpdir(), `chant-1131-policy-${Date.now()}-${Math.random()}`);
+    await mkdir(dir, { recursive: true });
+    testDir = await realpath(dir);
+    delete (globalThis as unknown as MarkerHost)[TOP_MARKER];
+    delete (globalThis as unknown as MarkerHost)[CHECK_MARKER];
+    savedEnv = process.env[ENV_VAR];
+    resetSandboxPolicyExecutionForTests();
+  });
+
+  afterEach(async () => {
+    delete (globalThis as unknown as MarkerHost)[TOP_MARKER];
+    delete (globalThis as unknown as MarkerHost)[CHECK_MARKER];
+    if (savedEnv === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = savedEnv;
+    resetSandboxPolicyExecutionForTests();
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  /** A policy that announces its own execution twice: once at module top level, once per check call. */
+  async function writeMarkerPolicy(name = "org.ts", body?: string): Promise<string> {
+    await writeFile(
+      join(testDir, name),
+      body ??
+        `globalThis[${JSON.stringify(TOP_MARKER)}] = true;\n` +
+          `export const tlsRequired = {\n` +
+          `  id: "ORG-TLS",\n` +
+          `  description: "ingress must terminate TLS",\n` +
+          `  check(ctx) {\n` +
+          `    globalThis[${JSON.stringify(CHECK_MARKER)}] = true;\n` +
+          `    const out = [];\n` +
+          `    for (const [entityName, entity] of ctx.entities) {\n` +
+          `      const tls = entity.props && entity.props.tls;\n` +
+          `      if (Array.isArray(tls) && tls.length === 0) {\n` +
+          `        out.push({ checkId: "ORG-TLS", severity: "error", message: entityName + " has no TLS in " + ctx.env, entity: entityName });\n` +
+          `      }\n` +
+          `    }\n` +
+          `    if (ctx.outputs.get("test").includes("storefront")) {\n` +
+          `      out.push({ checkId: "ORG-TLS", severity: "warning", message: "saw storefront in the output" });\n` +
+          `    }\n` +
+          `    return out;\n` +
+          `  },\n` +
+          `};\n`,
+    );
+    return name;
+  }
+
+  function run(policies: string[], env = "prod"): ReturnType<typeof runProjectPolicies> {
+    return runProjectPolicies({ policies, configDir: testDir, buildResult: buildResultFixture(), env });
+  }
+
+  test("without --sandbox the policy DOES run in this process (both probes fire)", async () => {
+    await writeMarkerPolicy();
+
+    const diags = await run(["org.ts"]);
+
+    expect(isSandboxPolicyExecutionArmed()).toBe(false);
+    expect(marker(TOP_MARKER), "the policy module's top level ran in this process").toBe(true);
+    expect(marker(CHECK_MARKER), "the check function ran in this process").toBe(true);
+    expect(diags).toEqual([
+      { checkId: "ORG-TLS", severity: "error", message: "Ingress has no TLS in prod", entity: "Ingress" },
+      { checkId: "ORG-TLS", severity: "warning", message: "saw storefront in the output" },
+    ]);
+  });
+
+  test("armed, the same policy runs in the child: no markers here, IDENTICAL diagnostics", async () => {
+    await writeMarkerPolicy();
+    const plain = await run(["org.ts"]);
+
+    delete (globalThis as unknown as MarkerHost)[TOP_MARKER];
+    delete (globalThis as unknown as MarkerHost)[CHECK_MARKER];
+    armSandboxPolicyExecution();
+    const sandboxed = await run(["org.ts"]);
+
+    expect(marker(TOP_MARKER), "the policy module's top level must NOT run in the CLI process").toBeUndefined();
+    expect(marker(CHECK_MARKER), "the check function must NOT run in the CLI process").toBeUndefined();
+    expect(sandboxed).toEqual(plain);
+  });
+
+  test("several policy modules keep their declaration order across the boundary", async () => {
+    for (const [file, id] of [
+      ["a.ts", "A"],
+      ["b.ts", "B"],
+    ] as const) {
+      await writeFile(
+        join(testDir, file),
+        `export const c = { id: ${JSON.stringify(id)}, description: "d", check: () => [{ checkId: ${JSON.stringify(id)}, severity: "info", message: "m" }] };\n`,
+      );
+    }
+
+    const plain = await run(["a.ts", "b.ts"]);
+    armSandboxPolicyExecution();
+    const sandboxed = await run(["a.ts", "b.ts"]);
+
+    expect(plain.map((d) => d.checkId)).toEqual(["A", "B"]);
+    expect(sandboxed).toEqual(plain);
+  });
+
+  test("a policy that reads outside the project is denied, naming the policy file", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `import { readFileSync } from "node:fs";\n` +
+        `const stolen = readFileSync("/etc/hosts", "utf-8");\n` +
+        `export const c = { id: "X", description: "d", check: () => [{ checkId: "X", severity: "info", message: stolen.slice(0, 3) }] };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/sandbox denied FileSystemRead \(\/etc\/hosts\)/);
+    await expect(run(["org.ts"])).rejects.toThrow(/org\.ts/);
+  });
+
+  test("a policy that writes a file is denied — the boundary costs this pattern, deliberately", async () => {
+    // A policy that drops a compliance report next to the build is a plausible
+    // thing to have written. Under `--sandbox` it fails, loudly, rather than
+    // succeeding and making the flag a lie.
+    await writeMarkerPolicy(
+      "org.ts",
+      `import { writeFileSync } from "node:fs";\n` +
+        `export const c = { id: "X", description: "d", check: () => { writeFileSync(${JSON.stringify(join(testDir, "report.json"))}, "{}"); return []; } };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/sandbox denied FileSystemWrite/);
+    await expect(readFile(join(testDir, "report.json"))).rejects.toThrow();
+  });
+
+  test("a policy that tries to spawn a process is denied", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `import { execSync } from "node:child_process";\n` +
+        `export const c = { id: "X", description: "d", check: () => { execSync("echo pwned"); return []; } };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/sandbox denied/);
+  });
+
+  test("the child's environment is scrubbed — but --env still reaches a policy", async () => {
+    process.env[ENV_VAR] = "prod";
+    process.env.CHANT_1131_SECRET = "hunter2";
+    try {
+      await writeMarkerPolicy(
+        "org.ts",
+        `export const c = {\n` +
+          `  id: "ENV", description: "d",\n` +
+          `  check: (ctx) => [\n` +
+          `    { checkId: "ENV", severity: "info", message: "ctx.env=" + ctx.env },\n` +
+          `    { checkId: "ENV", severity: "info", message: "CHANT_ENV=" + (process.env[${JSON.stringify(ENV_VAR)}] ?? "unset") },\n` +
+          `    { checkId: "ENV", severity: "info", message: "secret=" + (process.env.CHANT_1131_SECRET ?? "scrubbed") },\n` +
+          `  ],\n` +
+          `};\n`,
+      );
+      armSandboxPolicyExecution();
+
+      const diags = await run(["org.ts"], "prod");
+
+      expect(diags.map((d) => d.message)).toEqual(["ctx.env=prod", "CHANT_ENV=prod", "secret=scrubbed"]);
+    } finally {
+      delete process.env.CHANT_1131_SECRET;
+    }
+  });
+
+  test("a diagnostic that is not data is refused, naming the policy module and the key path", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `export const c = { id: "X", description: "d", check: () => [{ checkId: "X", severity: "error", message: "m", fix: () => 1 }] };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    const promise = run(["org.ts"]);
+    await expect(promise).rejects.toThrow(/org\.ts \[0\]\.fix: a function/);
+    await expect(run(["org.ts"])).rejects.toThrow(/Cannot run lint\.policies inside the --sandbox boundary/);
+  });
+
+  test("a diagnostic with a bad severity is refused rather than printed as one", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `export const c = { id: "X", description: "d", check: () => [{ checkId: "X", severity: "fatal", message: "m" }] };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/severity: not one of "error", "warning", "info"/);
+  });
+
+  test("a policy module that throws at import fails naming the file", async () => {
+    await writeMarkerPolicy("org.ts", `throw new Error("policy exploded");\n`);
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/policy exploded/);
+  });
+
+  test("a check that throws fails the build rather than silently producing nothing", async () => {
+    await writeMarkerPolicy(
+      "org.ts",
+      `export const c = { id: "X", description: "d", check: () => { throw new Error("check exploded"); } };\n`,
+    );
+    armSandboxPolicyExecution();
+
+    await expect(run(["org.ts"])).rejects.toThrow(/check exploded/);
+  });
+
+  test("armed, loadPolicyChecks refuses rather than importing project code here", async () => {
+    await writeMarkerPolicy();
+    armSandboxPolicyExecution();
+
+    await expect(loadPolicyChecks(["org.ts"], testDir)).rejects.toThrow(/Cannot load lint\.policies .* under --sandbox/);
+    expect(marker(TOP_MARKER)).toBeUndefined();
+  });
+
+  test("no policies declared means no child at all", async () => {
+    armSandboxPolicyExecution();
+
+    expect(await run([])).toEqual([]);
+  });
+
+  test("a program that runs a policy child EXITS — the child is not left holding the event loop", async () => {
+    // Found the hard way while measuring #1131's cost: unlike the run and
+    // config drivers, the policy driver keeps a `message` listener registered
+    // in order to RECEIVE its input, and a `message` listener refs the IPC
+    // channel — so the child stayed alive after answering, and its live channel
+    // kept the parent alive too. `chant build` hid it (`cli/main.ts` ends in
+    // `process.exit`); anything embedding chant as a library hung forever.
+    //
+    // Asserted the only way that actually proves it: run a real program in a
+    // real process and require it to exit on its own.
+    await writeFile(
+      join(testDir, "org.ts"),
+      `export const c = { id: "X", description: "d", check: () => [] };\n`,
+    );
+    const script = join(testDir, "driver.mts");
+    await writeFile(
+      script,
+      `import { runPoliciesSandboxed } from ${JSON.stringify(join(import.meta.dirname, "policy-run.ts"))};\n` +
+        `await runPoliciesSandboxed({\n` +
+        `  policyPaths: [${JSON.stringify(join(testDir, "org.ts"))}],\n` +
+        `  buildResult: { outputs: new Map(), entities: new Map(), warnings: [], errors: [], sourceFileCount: 0 },\n` +
+        `  projectRoot: ${JSON.stringify(testDir)},\n` +
+        `});\n` +
+        `console.log("done");\n`,
+    );
+
+    const exited = await new Promise<{ code: number | null; timedOut: boolean }>((resolvePromise) => {
+      const child = spawn(process.execPath, ["--import", "tsx", script], { stdio: "ignore" });
+      const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        resolvePromise({ code: null, timedOut: true });
+      }, 60_000);
+      child.on("exit", (code) => {
+        clearTimeout(timer);
+        resolvePromise({ code, timedOut: false });
+      });
+    });
+
+    expect(exited.timedOut, "the process did not exit — a sandbox child is holding the event loop open").toBe(false);
+    expect(exited.code).toBe(0);
+  });
+});

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

@@ -0,0 +1,180 @@
+import { realpathSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import type { PostSynthDiagnostic } from "../../lint/post-synth";
+import { bundleDriver } from "./bundle";
+import { generatePolicyDriverSource } from "./driver";
+import { forkSandboxed } from "./fork";
+import {
+  encodePolicyBuildResult,
+  formatPolicyWireOffenders,
+  type EncodablePolicyBuildResult,
+  type PolicyDiagnosticOffender,
+} from "./policy-wire";
+import { ENV_VAR } from "../../env";
+
+/**
+ * chant #1131 — runs a project's `lint.policies` checks inside a sandboxed
+ * child, over the build result the parent has already merged and serialized,
+ * and brings back plain `PostSynthDiagnostic`s.
+ *
+ * This closes the last residual chant #1093 and #1113 documented. `--sandbox`
+ * isolated project *source* (#1045), then project *fold-time* code (#1093),
+ * then the project's `chant.config.ts` (#1113) — but `chant build` still
+ * imported every `lint.policies` module and called its `check` function in the
+ * CLI's own process, after discovery, with the CLI's full filesystem, network,
+ * environment and process-spawn access. The config crossing as data did not
+ * take the policies with it: they are declared in it as *paths*.
+ *
+ * ## Why a second child rather than the first one
+ *
+ * A policy is a callback over the *whole* resolved build, and no such thing
+ * exists inside the #1045 discovery child. That child sees only the
+ * run-fallback subset — folded files are collected in the parent, the merge
+ * happens in the parent, and serialization (which is what most policies
+ * actually read) happens later still. Running policies there would hand them a
+ * partial, unserialized view and call it the same check. So the boundary moves
+ * to where the complete result exists: after the merge, in a child of its own.
+ *
+ * Deliberately the same machinery, not a parallel one — the same three modules
+ * `./config-run.ts` reuses:
+ *  - `./bundle.ts` bundles the generated driver (`./driver.ts`'s
+ *    `generatePolicyDriverSource`) with esbuild, so the child needs no runtime
+ *    module resolution and no TypeScript loader.
+ *  - `./fork.ts` spawns it with the identical `--permission` profile the
+ *    run-fallback and config children get — one function, so the three cannot
+ *    drift.
+ *  - `./child-errors.ts` (inside the driver) classifies whatever it throws, so
+ *    a permission denial names the policy file instead of leaking
+ *    `ERR_ACCESS_DENIED`.
+ *
+ * The one addition is direction: the policy child receives its input over the
+ * same IPC channel it answers on (`SandboxForkOptions.send`). See that field's
+ * doc for why sending before the child boots is safe.
+ *
+ * ## What the child can and cannot do
+ *
+ * Exactly what a run-fallback file can: read the bundle directory and the
+ * project directory, nothing else; no writes, no spawning, no worker threads;
+ * an environment of `PATH` plus `CHANT_ENV` when set. That last one matches
+ * `./config-run.ts` for the same reason — `--env` is a value the user typed on
+ * the command line, and a policy that branches on the environment is the
+ * documented pattern (`ctx.env` carries it too, so this is belt-and-braces for
+ * a policy reading `process.env.CHANT_ENV` directly rather than a new
+ * capability).
+ *
+ * A policy that writes a report file, shells out to a scanner, or reads
+ * `~/.aws/credentials` therefore now FAILS, loudly, naming the file and the
+ * operation. That is the point of the flag, and it is a real behavior change
+ * for such a policy under `--sandbox` — see `docs/.../architecture/sandbox.mdx`.
+ */
+
+/** A policy child is one bundle, one import per policy module, and a pass over data. Generous relative to that, tight enough that a hung policy is reported rather than waited on. */
+const POLICY_CHILD_TIMEOUT_MS = 120_000;
+
+interface PolicyChildResponse {
+  kind: "chant-policy";
+  ok: boolean;
+  diagnostics?: PostSynthDiagnostic[];
+  offenders?: PolicyDiagnosticOffender[];
+  error?: { name: string; file: string; message: string; type: string };
+}
+
+function isPolicyChildResponse(value: unknown): value is PolicyChildResponse {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === "chant-policy" &&
+    typeof (value as { ok?: unknown }).ok === "boolean"
+  );
+}
+
+export interface SandboxPolicyResult {
+  /** What the policy pack reported — plain data, validated inside the child before it crossed (see `./policy-wire.ts`'s `scanPolicyDiagnostics`). */
+  diagnostics: PostSynthDiagnostic[];
+  /** esbuild bundling wall-clock time. */
+  bundleMs: number;
+  /** Bundle size in bytes. */
+  bundleBytes: number;
+  /** Encoded build-result payload size in bytes — what crossed the IPC channel. */
+  payloadBytes: number;
+}
+
+export interface SandboxPolicyOptions {
+  /** Absolute paths to the project's `lint.policies` modules, in declaration order. */
+  policyPaths: readonly string[];
+  /** The merged, serialized build result the checks run over. */
+  buildResult: EncodablePolicyBuildResult;
+  /** The environment/stack this build was evaluated for (`--env`, else `ownership.env`) — becomes `ctx.env`. */
+  env?: string;
+  /** Directory the child is granted `--allow-fs-read` for: the project root (the `chant.config.*` directory, which `lint.policies` paths are resolved against). */
+  projectRoot: string;
+}
+
+/**
+ * Evaluate `policyPaths` against `buildResult` inside a sandboxed child.
+ *
+ * Throws — rather than degrading to an in-process run — when the policies
+ * cannot be evaluated inside the boundary or their diagnostics cannot cross it
+ * as JSON. Under `--sandbox` a policy pack that "almost" ran is not a safe
+ * thing to proceed with, and quietly falling back would give away the property
+ * the flag exists to provide.
+ */
+export async function runPoliciesSandboxed(options: SandboxPolicyOptions): Promise<SandboxPolicyResult> {
+  const { policyPaths, buildResult, env, projectRoot } = options;
+
+  // Encoded FIRST, in the parent, before anything is bundled or spawned: this
+  // is where a build result that cannot cross is rejected by name (a
+  // `nestedStack()` child project, a serializer output that isn't data), and
+  // there is no point paying for a bundle to find that out.
+  const payload = {
+    kind: "chant-policy-request" as const,
+    buildResult: encodePolicyBuildResult(buildResult),
+    env: env ?? null,
+  };
+  const payloadBytes = Buffer.byteLength(JSON.stringify(payload), "utf-8");
+
+  const driverSource = generatePolicyDriverSource(policyPaths);
+  const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+
+  try {
+    let projectRealpath: string;
+    try {
+      projectRealpath = realpathSync(resolve(projectRoot));
+    } catch {
+      projectRealpath = resolve(projectRoot);
+    }
+
+    const childEnv: Record<string, string> = { PATH: process.env.PATH ?? "" };
+    const activeEnv = process.env[ENV_VAR];
+    if (activeEnv) childEnv[ENV_VAR] = activeEnv;
+
+    const response = await forkSandboxed(
+      {
+        bundlePath,
+        bundleDir,
+        projectRealpath,
+        externalReadPaths,
+        env: childEnv,
+        timeoutMs: POLICY_CHILD_TIMEOUT_MS,
+        label: `sandboxed evaluation of lint.policies (${policyPaths.length} module(s))`,
+        send: payload,
+      },
+      isPolicyChildResponse,
+    );
+
+    if (!response.ok) {
+      if (response.offenders && response.offenders.length > 0) {
+        throw new Error(formatPolicyWireOffenders("a policy check's return value", response.offenders));
+      }
+      throw new Error(
+        response.error?.message
+          ? `Failed to run lint.policies inside the --sandbox boundary: ${response.error.message}`
+          : `Failed to run lint.policies inside the --sandbox boundary`,
+      );
+    }
+
+    return { diagnostics: response.diagnostics ?? [], bundleMs: durationMs, bundleBytes: bytes, payloadBytes };
+  } finally {
+    rmSync(bundleDir, { recursive: true, force: true });
+  }
+}