@intentius/chant 0.25.0 → 0.27.0

package/src/cli/main.ts

@@ -7,6 +7,7 @@ import { loadPlugins, resolveProjectLexicons } from "./plugins";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 import { loadChantConfigUpward } from "../config";
 import { armSandboxConfigEvaluation } from "../config-sandbox";
+import { armSandboxPolicyExecution } from "../lint/policy-import";
 import { ENV_VAR, unknownEnvError } from "../env";
 import { initRuntime } from "../runtime-adapter";
 import { runBuild } from "./handlers/build";
@@ -27,10 +28,61 @@ import { runGraph } from "./handlers/graph";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 import { runEmulator } from "./handlers/emulator";
 
+/**
+ * Long-form flags that are pure booleans in {@link parseArgs} — their branch
+ * below sets a field to `true` and never consumes a following array element.
+ * Used only to reject a joined `--flag=value` form for these (chant #1127):
+ * a boolean has no value to assign, and silently reinterpreting the joined
+ * value as the next positional argument (path, component name, ...) would be
+ * exactly the kind of silent misparse this issue exists to close. `--report`
+ * is deliberately excluded — it's context-sensitive (bare boolean vs a SARIF
+ * path, decided by lookahead), so a joined value for it is legitimate and
+ * already handled correctly once split.
+ */
+const BOOLEAN_FLAGS = new Set([
+  "--help",
+  "--force",
+  "--fix",
+  "--watch",
+  "--verbose",
+  "--live",
+  "--overlay",
+  "--owned",
+  "--verbatim",
+  "--apply-rewrites",
+  "--write",
+  "--strict",
+  "--validate",
+  "--use-composites",
+  "--stacks",
+  "--components",
+  "--up",
+  "--down",
+  "--include-dependents",
+  "--local",
+  "--temporal",
+  "--json",
+  "--progress-json",
+  "--update-snapshot",
+  "--run-examples",
+  "--check",
+  "--bump",
+  "--no-release-record",
+  "--fold",
+  "--no-fold",
+  "--sandbox",
+]);
+
 /**
  * Parse command line arguments
  */
 export function parseArgs(args: string[]): ParsedArgs {
+  // Local mutable copy — chant #1127's joined-`--flag=value` splitting below
+  // rewrites the array in place (one token becomes two), so this must not
+  // mutate whatever array the caller passed in (e.g. `process.argv.slice(2)`
+  // is already a fresh copy, but callers shouldn't have to know that).
+  args = args.slice();
+
   const result: ParsedArgs = {
     command: "",
     path: ".",
@@ -67,7 +119,29 @@ export function parseArgs(args: string[]): ParsedArgs {
 
   let i = 0;
   while (i < args.length) {
-    const arg = args[i];
+    let arg = args[i];
+
+    // chant #1127 — generic joined `--flag=value` support. Every value-taking
+    // flag below is matched by an exact `arg === "--flag"` check and then
+    // consumes the *next* array element (`args[++i]`) as its value; a joined
+    // token like `--env=prod` never matches any of those, doesn't match the
+    // trailing positional branch either (it starts with `-`), and used to
+    // vanish with no error. Splitting the token at its FIRST `=` and
+    // re-dispatching as two array elements makes every flag below see the
+    // exact shape it already handles — including a flag like `--param`
+    // whose own value legitimately contains `=` (`--param=tier=production`
+    // splits to flag `--param`, value `tier=production`, not further split
+    // on the second `=`).
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const eq = arg.indexOf("=");
+      const flag = arg.slice(0, eq);
+      const value = arg.slice(eq + 1);
+      if (BOOLEAN_FLAGS.has(flag)) {
+        throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
+      }
+      args.splice(i, 1, flag, value);
+      arg = args[i];
+    }
 
     if (arg === "--help" || arg === "-h") {
       result.help = true;
@@ -221,22 +295,35 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.noReleaseRecord = true;
     } else if (arg === "--fold") {
       result.fold = true;
+    } else if (arg === "--no-fold") {
+      // chant #1134 — fold is the default build path; this is the explicit
+      // opt-out, and like --fold it beats chant.config.ts's build.fold.
+      result.fold = false;
     } else if (arg === "--sandbox") {
       result.sandbox = true;
     } else if (arg === "--param") {
+      // chant #1118/#1127 — `--param name=value` (space-separated) and
+      // `--param=name=value` (joined, split above at its first `=` into flag
+      // `--param` + value `name=value`) both land here and behave
+      // identically; there is no separate joined-form error anymore (the
+      // #1118 hard error this superseded only existed because the parser
+      // didn't support joined forms at all — now that it does, the joined
+      // form is just as valid as the space-separated one).
       (result.param ??= []).push(args[++i]);
-    } else if (arg.startsWith("--param=")) {
-      // chant #1118 — this parser never supports an `--flag=value` joined
-      // form for any value-taking flag (every branch above is an exact `===`
-      // match, so a joined token falls through unrecognized and is silently
-      // dropped — see the "ignores unknown flags" case below). `--param
-      // name=value` (space-separated) is the only accepted form. Rather than
-      // teach the parser joined forms generally, `--param=name=value` is
-      // called out as a hard error instead of a silent no-op: a dropped
-      // `--param` can silently change what a build measures/deploys.
-      throw new Error(`${arg} is not supported. Use --param name=value (space-separated) instead.`);
     } else if (arg === "--params-file") {
       result.paramsFile = args[++i];
+    } else if (arg.startsWith("--")) {
+      // chant #1127 — every recognized flag is matched above; anything left
+      // starting with `--` is unrecognized, whether it arrived bare
+      // (`--bogus`) or joined (`--bogus=value`, already split into
+      // `--bogus` + `value` above). This used to fall through silently (the
+      // "ignores unknown flags" case) — a typo'd or misremembered flag would
+      // vanish with no diagnostic, exactly like the silent-drop this issue
+      // closes for joined values. Point at --help rather than enumerating
+      // every flag here: this parser's flag set is one flat list shared by
+      // every command, not scoped per-command, so "the command's known
+      // flags" isn't something this loop can name in isolation.
+      throw new Error(`Unknown flag: ${arg}\nRun "chant --help" to see supported flags.`);
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -432,8 +519,11 @@ Options:
                         to run per-file for anything else outside the fold
                         subset (a cross-file-only reference, a re-export,
                         \`export default\`, ...). Logs which path each file
-                        took. Default: off (also settable via
-                        chant.config.ts's build.fold: true; #1022)
+                        took. DEFAULT since #1134 — this flag forces it on
+                        over a chant.config.ts \`build.fold: false\`.
+  --no-fold             (build) Opt out of folding for this invocation: every
+                        source module is imported and run, the pre-#1134
+                        behavior. Beats chant.config.ts's build.fold.
   --sandbox             (build) Run run-fallback source files (or every
                         file, without --fold) together, isolated, in one
                         sandboxed child process instead of in-process
@@ -608,6 +698,14 @@ async function main(): Promise<void> {
   // `../config-sandbox.ts`.
   if (args.sandbox) armSandboxConfigEvaluation();
 
+  // chant #1131 — the same for `lint.policies`. Armed from the flag here so
+  // the mode is set for the whole invocation, not just `chant build`; the build
+  // command arms it again from the RESOLVED value (a project's own
+  // `build.sandbox: true` also sandboxes its policies — unlike the config,
+  // policies have no bootstrap limit, since they load long after the config is
+  // known). See `../lint/policy-sandbox.ts`.
+  if (args.sandbox) armSandboxPolicyExecution();
+
   // Initialize runtime adapter early — before plugins or commands run.
   // chant #1117 — walks up from `args.path` to the project root: for a
   // subdirectory build/command (`chant build src/<stack> --env prod`) the

package/src/config.test.ts

@@ -1,5 +1,11 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { loadChantConfig, DEFAULT_CHANT_CONFIG, resolveAutoReleaseDisabled, resolveSbomFormat } from "./config";
+import {
+  loadChantConfig,
+  DEFAULT_CHANT_CONFIG,
+  resolveAutoReleaseDisabled,
+  resolveFoldEnabled,
+  resolveSbomFormat,
+} from "./config";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
 
@@ -128,6 +134,27 @@ describe("loadChantConfig", () => {
   });
 });
 
+describe("resolveFoldEnabled (#1134 — fold is the default build path)", () => {
+  test("default (no flag, no config) → fold ON", () => {
+    expect(resolveFoldEnabled({})).toBe(true);
+  });
+
+  test("config build.fold: false turns it off; true keeps it on", () => {
+    expect(resolveFoldEnabled({ build: { fold: false } })).toBe(false);
+    expect(resolveFoldEnabled({ build: { fold: true } })).toBe(true);
+    expect(resolveFoldEnabled({ build: {} })).toBe(true);
+  });
+
+  test("--fold (flag true) beats config false", () => {
+    expect(resolveFoldEnabled({ build: { fold: false } }, true)).toBe(true);
+  });
+
+  test("--no-fold (flag false) beats config true and the default", () => {
+    expect(resolveFoldEnabled({ build: { fold: true } }, false)).toBe(false);
+    expect(resolveFoldEnabled({}, false)).toBe(false);
+  });
+});
+
 describe("resolveAutoReleaseDisabled", () => {
   test("default (no flag, no config) → not disabled", () => {
     expect(resolveAutoReleaseDisabled({})).toBe(false);

package/src/config.ts

@@ -139,12 +139,12 @@ export interface ChantConfig {
    */
   build?: {
     /**
-     * Opt-in: fold source modules statically instead of importing/running
-     * them, falling back to run per-file for anything the folder can't
-     * represent (composite factory calls, non-`new` exports, …). Default
-     * `false`. The `--fold` CLI flag overrides this per-invocation (a flag
-     * of `true` always wins; the flag cannot force fold *off* when this is
-     * `true`). See {@link resolveFoldEnabled}.
+     * Fold source modules statically instead of importing/running them,
+     * falling back to run per-file for anything the folder can't represent.
+     * DEFAULT `true` since chant #1134 — set `false` to make this project
+     * run every module (the pre-#1134 behavior). The `--fold`/`--no-fold`
+     * CLI flags override this per-invocation in either direction. See
+     * {@link resolveFoldEnabled}.
      */
     fold?: boolean;
 
@@ -353,14 +353,18 @@ export function resolveAutoReleaseDisabled(config: ChantConfig, cliFlag?: boolea
 
 /**
  * Whether `chant build` should use the fold path (#1022, epic #1019)
- * instead of running each source module. Opt-in: off unless the CLI's
- * `--fold` flag was passed (`cliFlag`) or the project config sets
- * `build.fold: true` — the flag always wins for that one invocation,
- * regardless of config.
+ * instead of running each source module. DEFAULT-ON since chant #1134: fold
+ * is the build path unless something turns it off. Precedence, most specific
+ * wins: an explicit CLI flag (`--fold` → true, `--no-fold` → false, arriving
+ * here as `cliFlag`), then the project config's `build.fold`, then the
+ * default of `true`. The epic's evidence base for the flip — coverage,
+ * byte-identity, and the sandbox execution boundary — is recorded on #1134
+ * and #1090.
  */
 export function resolveFoldEnabled(config: ChantConfig, cliFlag?: boolean): boolean {
-  if (cliFlag) return true;
-  return config.build?.fold === true;
+  if (cliFlag !== undefined) return cliFlag;
+  if (config.build?.fold !== undefined) return config.build.fold;
+  return true;
 }
 
 /**

package/src/discovery/entity-wire-codec.ts

@@ -23,20 +23,25 @@
  * value) becomes a name-keyed marker instead. {@link decodeEntitySet} is the
  * inverse — it rebuilds a live `Map<string, Declarable>` whose entities are
  * BEHAVIORALLY indistinguishable from what `discover()` would have produced
- * in-process: real `AttrRef` instances (several call sites downstream key off
- * `instanceof AttrRef`, not just duck typing — `intrinsic-interpolation.ts`'s
+ * in-process: real `AttrRef` instances, not a duck-typed `{__attrRef}`
+ * envelope alone. `new AttrRef(...)` here is plain, direct construction from
+ * this module's own class — this codec runs inside the same module graph as
+ * every downstream reader (`intrinsic-interpolation.ts`'s
  * `defaultInterpolationSerializer`, `discovery/graph.ts`'s
  * `buildDependencyGraph`, `build.ts`'s `detectCrossLexiconRefs`/
- * `computeStackGraph` — so a plain `{__attrRef}` envelope alone is not
- * enough), and whole-entity embeds restored to the SAME object reference
- * (not a structurally-equal clone), so `entityNames.get(decl)` keeps working
- * by identity exactly as it does today.
+ * `computeStackGraph`, all converted to `isAttrRefLike` duck-typing by chant
+ * #1137 for the OTHER hazard, a separately-loaded lexicon copy) — so there is
+ * no dual-package boundary to duck-type across here, and building the real
+ * class is simply less code than hand-assembling a shape-alike stand-in with
+ * matching methods, and whole-entity embeds restored to the SAME object
+ * reference (not a structurally-equal clone), so `entityNames.get(decl)`
+ * keeps working by identity exactly as it does today.
  *
  * `serializer-walker.ts`'s `walkValue` needs NO changes for this: it already
  * falls back to reading a plain `{__attrRef}` envelope (added for intrinsics
  * whose own `toJSON()` embeds one). `decodeEntitySet` goes further and
- * reconstructs the real class so every OTHER `instanceof AttrRef` call site
- * keeps working too, not just the walker.
+ * reconstructs the real class, both simpler here and a belt-and-suspenders
+ * match for any call site that still checks `instanceof AttrRef` directly.
  *
  * Naming happens exactly once, inside the boundary — `resolveAttrRefs`
  * (./resolve.ts) runs as part of `discover()`, before `encodeEntitySet` is
@@ -85,7 +90,7 @@ import { isChildProject } from "../child-project";
  *   form. `refs` additionally captures any `AttrRef`/whole-entity reference
  *   found while walking the intrinsic's OWN fields (not through `toJSON()`)
  *   — `buildDependencyGraph` and `detectCrossLexiconRefs`/`computeStackGraph`
- *   walk raw entity property trees looking for `instanceof AttrRef`/a
+ *   walk raw entity property trees looking for an `AttrRef`-like value/a
  *   tracked `Declarable`, not through `toJSON()`, so a ref nested inside e.g.
  *   a `Sub` template needs to still be discoverable post-decode for
  *   cross-lexicon output auto-detection and dependency ordering to keep

package/src/discovery/graph.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { buildDependencyGraph } from "./graph";
 import { DECLARABLE_MARKER, type Declarable } from "../declarable";
 import { AttrRef } from "../attrref";
@@ -513,4 +513,43 @@ describe("buildDependencyGraph", () => {
     expect(graph.get("Entity3")?.has("Entity2")).toBe(true);
     expect(graph.get("Entity3")?.size).toBe(1);
   });
+
+  // chant #1137 — `findDependencies` used to check `value instanceof
+  // AttrRef`, which returns false for an AttrRef built by a SEPARATELY-
+  // LOADED copy of `../attrref` (the same dual-npm-copy hazard #1122 fixed
+  // for `LexiconOutput`). `vi.resetModules()` + a fresh dynamic import
+  // reproduces that split module graph exactly. Before the fix, a foreign
+  // AttrRef here recurses into the object's own (unhelpful) fields instead
+  // of being recorded as a dependency, silently dropping the edge — which
+  // can misorder the file-discovery build order this graph exists to compute.
+  test("detects dependency from an AttrRef built by a second, separately-loaded copy", async () => {
+    const parent: Declarable = {
+      lexicon: "test",
+      entityType: "parent",
+      [DECLARABLE_MARKER]: true,
+    };
+
+    vi.resetModules();
+    const secondCopy = await import("../attrref");
+    expect(secondCopy.AttrRef).not.toBe(AttrRef);
+
+    const foreignRef = new secondCopy.AttrRef(parent, "someAttr");
+    expect(foreignRef instanceof AttrRef).toBe(false); // the historic bug
+
+    const child: Declarable & { ref: AttrRef } = {
+      lexicon: "test",
+      entityType: "child",
+      [DECLARABLE_MARKER]: true,
+      ref: foreignRef,
+    };
+
+    const entities = new Map([
+      ["Parent", parent],
+      ["Child", child],
+    ]);
+    const graph = buildDependencyGraph(entities);
+
+    expect(graph.get("Child")?.has("Parent")).toBe(true);
+    vi.resetModules();
+  });
 });

package/src/discovery/graph.ts

@@ -1,6 +1,7 @@
 import type { Declarable } from "../declarable";
 import { isDeclarable } from "../declarable";
 import { AttrRef } from "../attrref";
+import { isAttrRefLike } from "../utils";
 
 /**
  * Builds a dependency graph from a collection of entities
@@ -95,8 +96,13 @@ function findDependencies(
     return;
   }
 
-  // Check if this is an AttrRef
-  if (value instanceof AttrRef) {
+  // Check if this is an AttrRef. Duck-type, not `instanceof` (chant #1137):
+  // a lexicon built against a separate copy of `@intentius/chant` produces
+  // AttrRefs that fail `instanceof AttrRef` here but carry the same shape.
+  // Without this, the dependency edge is silently dropped instead of
+  // recorded, which can misorder — or fail to detect a cycle in — the
+  // file-discovery build order this graph exists to compute.
+  if (isAttrRefLike(value)) {
     if (visited.has(value)) {
       return;
     }

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

@@ -18,6 +18,12 @@
  * 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
@@ -133,6 +139,21 @@ function walk(
   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

package/src/discovery/sandbox/driver.ts

@@ -43,6 +43,9 @@ 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`. */
@@ -213,3 +216,132 @@ export function generateConfigDriverSource(configPath: string): string {
     `});`,
   ].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");
+}

package/src/discovery/sandbox/fork.ts

@@ -45,6 +45,24 @@ export interface SandboxForkOptions {
   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>;
 }
 
 /**
@@ -56,7 +74,7 @@ export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
 ): Promise<T> {
-  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label } = options;
+  const { bundlePath, bundleDir, projectRealpath, externalReadPaths, env, timeoutMs, label, send } = options;
 
   return new Promise((resolvePromise, reject) => {
     const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map(
@@ -78,6 +96,16 @@ export function forkSandboxed<T>(
       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();
     });
@@ -86,6 +114,16 @@ export function forkSandboxed<T>(
       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);
     });