@intentius/chant 0.25.0 → 0.26.0

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

@@ -0,0 +1,277 @@
+import type { Declarable } from "../../declarable";
+import type { SerializerResult } from "../../serializer";
+import type { PostSynthContext, PostSynthDiagnostic } from "../../lint/post-synth";
+import { decodeEntitySet, encodeEntitySet, type EntitySetWire } from "../entity-wire-codec";
+import { scanValueWireSafety, type ConfigWireOffender } from "./config-wire";
+
+/**
+ * chant #1131 — what a build result looks like on its way INTO the sandboxed
+ * policy child, and what a `PostSynthDiagnostic` must look like on its way back
+ * out.
+ *
+ * A project's `lint.policies` checks are project-authored functions chant calls
+ * over the finished build. #1113 put `chant.config.ts` behind the `--sandbox`
+ * boundary but could not take the policies with it, because the config declares
+ * them as *paths*: the modules were still imported and their `check` functions
+ * still invoked in the CLI's own process, with the CLI's filesystem, network,
+ * environment and process-spawn access, after discovery was over.
+ *
+ * The shape of the fix is forced by what a policy is. It is not data that can
+ * be evaluated somewhere and carried back — it is a callback over the resolved
+ * resources, so it has to run somewhere it can see them. It also cannot run in
+ * the #1045 discovery child, because that child only ever sees the run-fallback
+ * *subset*: folded files are collected in the parent, and serialization happens
+ * in the parent, so no complete view of the build exists on that side. What
+ * does exist, after the parent has merged and serialized, is a build result
+ * that is *nearly* data already — which is what this module makes explicit.
+ *
+ * So: one more child, after the merge, handed the encoded build result,
+ * importing the policy modules inside the boundary and returning plain
+ * diagnostics. Same bundling (`./bundle.ts`), same spawn and `--permission`
+ * profile (`./fork.ts`), same error classification (`./child-errors.ts`), same
+ * "only JSON crosses, and anything else is named, never dropped" contract
+ * (`./config-wire.ts`, whose walk is reused directly).
+ *
+ * ## What crosses, and what that costs
+ *
+ * `PostSynthContext` gives a check five things. Four of them are already data:
+ * `outputs` (each lexicon's serialized text), `warnings`, `errors`,
+ * `sourceFileCount`. The fifth, `entities`, is a live `Map<string, Declarable>`
+ * whose cross-entity references are object identity and `WeakRef`s — the exact
+ * problem chant #1045 Phase 1 solved for discovery, so this reuses that codec
+ * (`../entity-wire-codec.ts`) rather than inventing a second one.
+ *
+ * That reuse is what makes the round trip cheap AND what defines its limits.
+ * `encodeEntitySet`/`decodeEntitySet` is documented as producing entities
+ * "behaviorally indistinguishable" from the in-process ones for chant's own
+ * consumers (serializers, the dependency graph, cross-lexicon detection), and
+ * a policy is a consumer of the same shape. Where it is NOT identical is
+ * written down in `docs/.../architecture/sandbox.mdx` and pinned by
+ * `./policy-wire.test.ts`:
+ *
+ *  - An intrinsic (`Sub`, `Ref`, gitlab's `!reference`, …) decodes to a
+ *    marker-bearing wrapper exposing `toJSON()`/`toYAML()`, not to an instance
+ *    of the lexicon's own intrinsic class.
+ *  - A decoded entity is a plain marker-bearing object, not an instance of the
+ *    lexicon's resource class, and its `lexicon`/`entityType`/`kind`/`props`/
+ *    `attributes` are non-enumerable (so `Object.keys(entity)` sees only the
+ *    per-attribute/extra fields). Reads — `entity.props`, `entity.entityType`,
+ *    `isDeclarable(entity)`, `instanceof AttrRef` — all still work.
+ *  - A `ChildProjectInstance` (`nestedStack()`) has no wire form at all;
+ *    `encodeEntitySet` throws rather than mis-encoding it, so a `--sandbox`
+ *    build that both uses `nestedStack()` and declares `lint.policies` fails
+ *    loudly. (No corpus entry uses `nestedStack()`.)
+ *  - `errors` cross as the plain objects `DiscoveryError`/`BuildError`'s own
+ *    `toJSON()` produces, not as `Error` instances. In practice this is never
+ *    observable: `chant build` runs policies only when the build produced no
+ *    errors at all, so the array is always empty at that point.
+ *
+ * Crucially, the first two are NOT new under `--sandbox`: a sandboxed build
+ * already merges decoded entities for every run-fallback file (`./run.ts`), so
+ * a policy running in-process on a `--sandbox` build is already looking at
+ * decoded entities for part of the set. Encoding is idempotent over a decoded
+ * entity (verified in `./policy-wire.test.ts`), so this child widens that from
+ * "the run-fallback subset" to "all of them" and changes nothing else.
+ */
+
+/** Wire form of one lexicon's serialized output — already data on both sides; carried as-is. */
+export type PolicyOutputWire = string | { primary: string; files?: Record<string, string>; warnings?: string[] };
+
+/** A build result as pure JSON, for the sandboxed policy child. */
+export interface PolicyBuildResultWire {
+  /** `../entity-wire-codec.ts`'s format — the same one the #1045 discovery child returns. */
+  entities: EntitySetWire;
+  /** `Map` entries as pairs; a `Map` itself JSON-stringifies to `{}`. */
+  outputs: Array<[string, PolicyOutputWire]>;
+  warnings: string[];
+  /** `DiscoveryError`/`BuildError`'s own `toJSON()` output. Always empty in practice — see the module doc. */
+  errors: Array<Record<string, unknown>>;
+  sourceFileCount: number;
+  /** `BuildResult.dependencies` (`Map<string, Set<string>>`) as pairs of arrays. Not part of `PostSynthContext`'s declared surface; carried so `ctx.buildResult` is not silently narrower than the object the in-process path passes. */
+  dependencies: Array<[string, string[]]>;
+  /** `BuildResult.manifest` — plain data (lexicons, cross-lexicon outputs, deploy order, stack graph). Same "not declared, still carried" reasoning as {@link dependencies}. */
+  manifest?: unknown;
+  /** `BuildResult.foldDecisions` — plain data. */
+  foldDecisions?: unknown[];
+  /** `BuildResult.buildParams` — plain data (#1064 provenance records). */
+  buildParams?: unknown[];
+}
+
+/** The subset of `BuildResult` this module knows how to carry. Structurally satisfied by `../../build.ts`'s `BuildResult`. */
+export interface EncodablePolicyBuildResult {
+  outputs: Map<string, string | SerializerResult>;
+  entities: Map<string, Declarable>;
+  warnings: string[];
+  errors: ReadonlyArray<{ name: string; message: string; toJSON?: () => unknown }>;
+  sourceFileCount: number;
+  dependencies?: Map<string, Set<string>>;
+  manifest?: unknown;
+  foldDecisions?: unknown[];
+  buildParams?: unknown[];
+}
+
+/**
+ * Encode a merged, serialized build result for the policy child.
+ *
+ * Runs in the PARENT. Throws — never drops — when the result holds something
+ * the wire cannot represent: `encodeEntitySet`'s own refusals (a `nestedStack()`
+ * child project, an `AttrRef` that never got a logical name) propagate, and the
+ * finished payload is walked by `./config-wire.ts`'s scan so a serializer that
+ * somehow produced a non-data output is named by key path rather than silently
+ * mangled by `JSON.stringify`.
+ */
+export function encodePolicyBuildResult(result: EncodablePolicyBuildResult): PolicyBuildResultWire {
+  const wire: PolicyBuildResultWire = {
+    entities: encodeEntitySet(result.entities),
+    outputs: [...result.outputs].map(([name, output]) => [name, encodeOutput(output)]),
+    warnings: [...result.warnings],
+    errors: result.errors.map((err) =>
+      typeof err.toJSON === "function"
+        ? (err.toJSON() as Record<string, unknown>)
+        : { name: err.name, message: err.message },
+    ),
+    sourceFileCount: result.sourceFileCount,
+    dependencies: result.dependencies ? [...result.dependencies].map(([name, deps]) => [name, [...deps]]) : [],
+  };
+  if (result.manifest !== undefined) wire.manifest = result.manifest;
+  if (result.foldDecisions !== undefined) wire.foldDecisions = result.foldDecisions;
+  if (result.buildParams !== undefined) wire.buildParams = result.buildParams;
+
+  const offenders = scanValueWireSafety(wire, "buildResult");
+  if (offenders.length > 0) {
+    throw new Error(formatPolicyWireOffenders("the build result", offenders));
+  }
+  return wire;
+}
+
+function encodeOutput(output: string | SerializerResult): PolicyOutputWire {
+  if (typeof output === "string") return output;
+  const encoded: { primary: string; files?: Record<string, string>; warnings?: string[] } = { primary: output.primary };
+  if (output.files !== undefined) encoded.files = { ...output.files };
+  if (output.warnings !== undefined) encoded.warnings = [...output.warnings];
+  return encoded;
+}
+
+/**
+ * Rebuild the `PostSynthContext["buildResult"]` a check expects, from the wire.
+ *
+ * Runs INSIDE the child. The maps and the live entity graph are reconstructed
+ * here (`decodeEntitySet`), so a check sees the same kind of object it sees
+ * in-process — `ctx.entities` is a real `Map`, its values are real
+ * `Declarable`s, and an `AttrRef` between two of them is a real `AttrRef`
+ * carrying its resolved logical name.
+ */
+export function decodePolicyBuildResult(wire: PolicyBuildResultWire): PostSynthContext["buildResult"] {
+  const decoded = {
+    outputs: new Map<string, string | SerializerResult>(wire.outputs),
+    entities: decodeEntitySet(wire.entities),
+    warnings: wire.warnings ?? [],
+    errors: (wire.errors ?? []) as unknown as Array<{ message: string; name: string }>,
+    sourceFileCount: wire.sourceFileCount ?? 0,
+    dependencies: new Map<string, Set<string>>((wire.dependencies ?? []).map(([n, d]) => [n, new Set(d)])),
+    manifest: wire.manifest,
+    foldDecisions: wire.foldDecisions ?? [],
+    buildParams: wire.buildParams ?? [],
+  };
+  return decoded as unknown as PostSynthContext["buildResult"];
+}
+
+/** One thing a policy returned that cannot cross back, with the policy module it came from. */
+export interface PolicyDiagnosticOffender extends ConfigWireOffender {
+  /** Absolute path of the `lint.policies` module whose check returned it. */
+  policy: string;
+}
+
+/**
+ * Validate what one policy module's checks returned, INSIDE the child, before
+ * it goes anywhere near the IPC channel.
+ *
+ * Two separate questions, both answered here rather than by hoping
+ * `JSON.stringify` behaves:
+ *
+ *  1. Is it data? A `PostSynthDiagnostic` is declared as five plain fields, but
+ *     a check is arbitrary project code and can return anything. A function, a
+ *     `Date`, a class instance, a circular reference — `JSON.stringify` would
+ *     drop or rewrite each of them without a word, and the CLI would print a
+ *     diagnostic that is not the one the policy produced.
+ *  2. Is it a diagnostic? A missing `checkId`, or a `severity` outside
+ *     `error`/`warning`/`info`, is reported here instead of turning into an
+ *     undefined-shaped line in the build's error list.
+ */
+export function scanPolicyDiagnostics(
+  diagnostics: unknown,
+  policyPath: string,
+): PolicyDiagnosticOffender[] {
+  const out: PolicyDiagnosticOffender[] = [];
+  if (!Array.isArray(diagnostics)) {
+    out.push({ policy: policyPath, path: "<return value>", found: describeShape(diagnostics) });
+    return out;
+  }
+
+  for (const offender of scanValueWireSafety(diagnostics, "")) {
+    out.push({ policy: policyPath, ...offender });
+  }
+  if (out.length > 0) return out;
+
+  const severities = new Set(["error", "warning", "info"]);
+  diagnostics.forEach((diag, i) => {
+    const d = diag as Partial<PostSynthDiagnostic> | null;
+    if (d === null || typeof d !== "object" || Array.isArray(d)) {
+      out.push({ policy: policyPath, path: `[${i}]`, found: describeShape(diag) });
+      return;
+    }
+    if (typeof d.checkId !== "string" || d.checkId.length === 0) {
+      out.push({ policy: policyPath, path: `[${i}].checkId`, found: "not a non-empty string" });
+    }
+    if (typeof d.message !== "string") {
+      out.push({ policy: policyPath, path: `[${i}].message`, found: "not a string" });
+    }
+    if (typeof d.severity !== "string" || !severities.has(d.severity)) {
+      out.push({ policy: policyPath, path: `[${i}].severity`, found: `not one of "error", "warning", "info"` });
+    }
+  });
+  return out;
+}
+
+/**
+ * Thrown INSIDE the child by the per-check wrapper `./driver.ts` generates,
+ * when a check returns something that cannot cross back. Carries the offenders
+ * so the driver can report them as data rather than as a message string it
+ * would then have to parse.
+ *
+ * A class rather than a tagged object because the driver tests it with
+ * `instanceof`: both halves come from this one module, bundled once, so there
+ * is exactly one class identity inside the child.
+ */
+export class PolicyWireError extends Error {
+  readonly offenders: PolicyDiagnosticOffender[];
+
+  constructor(offenders: PolicyDiagnosticOffender[]) {
+    super(formatPolicyWireOffenders("a policy check's return value", offenders));
+    this.name = "PolicyWireError";
+    this.offenders = offenders;
+  }
+}
+
+function describeShape(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  if (value === undefined) return "undefined";
+  return `a ${typeof value}`;
+}
+
+/** Render offenders as the body of a build error — one line each, naming the policy module. */
+export function formatPolicyWireOffenders(
+  subject: string,
+  offenders: ReadonlyArray<ConfigWireOffender & { policy?: string }>,
+): string {
+  const lines = offenders.map((o) => {
+    const where = o.policy ? `${o.policy}${o.path ? ` ${o.path}` : ""}` : o.path || "<root>";
+    return `  ${where}: ${o.found}`;
+  });
+  return [
+    `Cannot run lint.policies inside the --sandbox boundary: ${subject} holds values that are not data.`,
+    ...lines,
+    `Under --sandbox a policy check runs in an isolated child process and only JSON crosses back, so every value a check returns must be a string, number, boolean, null, array or plain object, and every diagnostic must have a string checkId, a string message, and a severity of "error", "warning" or "info". Return plain diagnostics, or drop --sandbox for this build.`,
+  ].join("\n");
+}

package/src/intrinsic-interpolation.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test, vi } from "vitest";
 import { buildInterpolatedString, defaultInterpolationSerializer } from "./intrinsic-interpolation";
 import { AttrRef } from "./attrref";
 import { INTRINSIC_MARKER } from "./intrinsic";
@@ -54,6 +54,32 @@ describe("defaultInterpolationSerializer", () => {
     expect(() => serialize(ref)).toThrow("logical name not set");
   });
 
+  // chant #1137 — this dispatch 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`). Because AttrRef also implements Intrinsic, the miss
+  // was not loud: a foreign AttrRef fell into the generic Intrinsic branch
+  // below instead, whose `toJSON()` returns the `{__attrRef}` wire envelope
+  // (not a `Ref`), silently stringified to `[object Object]` in the
+  // interpolated output. `vi.resetModules()` + a fresh dynamic import
+  // reproduces the split module graph exactly.
+  test("serializes an AttrRef built by a second, separately-loaded copy of AttrRef", async () => {
+    vi.resetModules();
+    const secondCopy = await import("./attrref");
+    expect(secondCopy.AttrRef).not.toBe(AttrRef);
+
+    const parent = {};
+    const foreignRef = new secondCopy.AttrRef(parent, "Arn");
+    foreignRef._setLogicalName("MyBucket");
+
+    // The historic bug: instanceof fails across separately-loaded copies of
+    // chant-core, even though the two classes are structurally identical.
+    expect(foreignRef instanceof AttrRef).toBe(false);
+
+    expect(serialize(foreignRef)).toBe("${MyBucket.Arn}");
+    vi.resetModules();
+  });
+
   test("serializes Intrinsic with Ref toJSON", () => {
     const intrinsic = {
       [INTRINSIC_MARKER]: true as const,

package/src/intrinsic-interpolation.ts

@@ -9,6 +9,7 @@
 import { AttrRef } from "./attrref";
 import { INTRINSIC_MARKER } from "./intrinsic";
 import { DECLARABLE_MARKER } from "./declarable";
+import { isAttrRefLike } from "./utils";
 
 export type InterpolationValueSerializer = (value: unknown) => string;
 
@@ -26,8 +27,15 @@ export function defaultInterpolationSerializer(
   serializeRef: (refName: string) => string,
 ): InterpolationValueSerializer {
   return (value: unknown): string => {
-    // Handle AttrRef
-    if (value instanceof AttrRef) {
+    // Handle 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 — and
+    // since AttrRef also implements Intrinsic, missing this branch does not
+    // fail loud. The value instead falls into the generic Intrinsic branch
+    // below, which calls `toJSON()` (returning the `{__attrRef}` wire
+    // envelope, not a `Ref`) and silently stringifies it to `[object
+    // Object]` in the interpolated output.
+    if (isAttrRefLike(value)) {
       const logicalName = value.getLogicalName();
       if (!logicalName) {
         throw new Error(

package/src/lexicon-output.test.ts

@@ -87,6 +87,42 @@ describe("LexiconOutput", () => {
     expect(lo.getOutputValue()).toEqual({ "Fn::GetAtt": ["myBucket", "Arn"] });
   });
 
+  // chant #1137 — the constructor used to check `ref 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
+  // `isLexiconOutput` itself). Because AttrRef also implements Intrinsic,
+  // the miss was not loud: a foreign AttrRef fell into the `isIntrinsic(ref)`
+  // branch instead, stored as `_intrinsic` rather than recognized as an
+  // AttrRef-sourced output — so `getOutputValue()` called the foreign
+  // AttrRef's own `toJSON()` (the `{__attrRef}` wire envelope) instead of
+  // emitting `Fn::GetAtt`, a broken Output with no error at synth time.
+  // `vi.resetModules()` + a fresh dynamic import reproduces the split
+  // module graph exactly.
+  test("recognizes an AttrRef built by a second, separately-loaded copy of AttrRef", async () => {
+    const bucket = new MockResource();
+
+    vi.resetModules();
+    const secondCopy = await import("./attrref");
+    expect(secondCopy.AttrRef).not.toBe(AttrRef);
+
+    const foreignRef = new secondCopy.AttrRef(bucket, "Arn");
+
+    // The historic bug: instanceof fails across separately-loaded copies of
+    // chant-core, even though the two classes are structurally identical.
+    expect(foreignRef instanceof AttrRef).toBe(false);
+
+    const lo = new LexiconOutput(foreignRef, "BucketArn");
+    lo._setSourceEntity("myBucket");
+
+    // The fix: recognized as AttrRef-sourced, not misfiled as a generic
+    // Intrinsic — sourceAttribute is set and getOutputValue() emits a real
+    // Fn::GetAtt, not the foreign AttrRef's own wire-envelope toJSON().
+    expect(lo.sourceLexicon).toBe("testdom");
+    expect(lo.sourceAttribute).toBe("Arn");
+    expect(lo.getOutputValue()).toEqual({ "Fn::GetAtt": ["myBucket", "Arn"] });
+    vi.resetModules();
+  });
+
   test("getOutputValue() returns intrinsic toJSON for Intrinsic-based output", () => {
     const mockIntrinsic = { [INTRINSIC_MARKER]: true as const, toJSON: () => ({ "Fn::Sub": "http://${Param}/path" }) };
     const lo = new LexiconOutput(mockIntrinsic, "MyUrl");

package/src/lexicon-output.ts

@@ -1,5 +1,6 @@
 import { INTRINSIC_MARKER, isIntrinsic, type Intrinsic } from "./intrinsic";
 import { AttrRef } from "./attrref";
+import { isAttrRefLike } from "./utils";
 
 /** A value `output()` accepts that is already fully resolved — not a
  * reference to anything, just data the author computed (a literal, a prop,
@@ -100,7 +101,16 @@ export class LexiconOutput implements Intrinsic {
       value: true,
       enumerable: false,
     });
-    if (ref instanceof 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 — and since AttrRef
+    // also implements Intrinsic, missing this branch does not fail loud.
+    // The value instead falls into the `isIntrinsic(ref)` branch below,
+    // stored as `_intrinsic` rather than an AttrRef-sourced output, so
+    // `getOutputValue()` later calls the foreign AttrRef's own `toJSON()`
+    // (the `{__attrRef}` wire envelope) instead of emitting `Fn::GetAtt` —
+    // a broken Output emitted with no error at synth time.
+    if (isAttrRefLike(ref)) {
       const parent = ref.parent.deref();
       if (!parent) {
         throw new Error("Cannot create LexiconOutput: parent entity has been garbage collected");
@@ -132,7 +142,7 @@ export class LexiconOutput implements Intrinsic {
       // a reference to anything. The `string` arm of the exported type
       // exists for a documented reason: a generated resource's attribute
       // accessor is typed `string` at the TypeScript level but is a real
-      // `AttrRef` at runtime, caught by `instanceof AttrRef` above — so
+      // `AttrRef` at runtime, caught by the `isAttrRefLike` check above — so
       // anything that reaches this branch genuinely has no source entity
       // or attribute, and is recorded to be emitted as a plain `Value`
       // rather than a fabricated `Fn::GetAtt` (chant #1121).

package/src/lint/policy-import.ts

@@ -0,0 +1,70 @@
+/**
+ * The single place chant imports a project's `lint.policies` module **in the
+ * CLI's own process** — and the flag that says it may not.
+ *
+ * The third member of the same family as `../discovery/import.ts`'s
+ * `importModule` (project source) and `../config-import.ts`'s
+ * `importConfigModule` (`chant.config.ts`): one narrow module whose only job is
+ * "execute project-authored code here", so that "did any project code run in
+ * this process?" has one place to look and one place to instrument — see
+ * `examples/sandbox-execution-boundary.test.ts`, which spies on all three.
+ *
+ * Before chant #1131 `./policy.ts` called `await import(resolved)` inline,
+ * which is why the corpus boundary gate could not see it even after #1113 put
+ * the config behind the boundary: there was nothing named to wrap.
+ *
+ * The armed flag lives here rather than in `./policy-sandbox.ts` (which owns
+ * the *decision* and documents the reasoning, and re-exports these three
+ * functions as its public surface) for one structural reason: `./policy.ts`
+ * needs to consult it, `./policy-sandbox.ts` needs to call `./policy.ts`, and a
+ * flag on a leaf module with no imports of its own breaks what would otherwise
+ * be an import cycle. It also puts the check on the narrowest possible thing —
+ * the function that actually executes project code — rather than on a caller
+ * that might forget to ask.
+ */
+
+/** Whether this process must run project policy modules inside the sandbox boundary instead of here. */
+let armed = false;
+
+/**
+ * Arm sandboxed policy execution for the rest of this process. See
+ * `./policy-sandbox.ts` for what arms it and why it is a process mode rather
+ * than a threaded option. Idempotent; there is deliberately no disarm.
+ */
+export function armSandboxPolicyExecution(): void {
+  armed = true;
+}
+
+/** Whether {@link armSandboxPolicyExecution} has been called. */
+export function isSandboxPolicyExecutionArmed(): boolean {
+  return armed;
+}
+
+/** Test-only reset — vitest gives each test file its own module registry, so this exists for suites that arm and disarm within one file. */
+export function resetSandboxPolicyExecutionForTests(): void {
+  armed = false;
+}
+
+/** The shape a policy module evaluates to — chant reads its exported values and keeps the `PostSynthCheck`-shaped ones. */
+export type PolicyModuleNamespace = Record<string, unknown>;
+
+/**
+ * Import a policy module into THIS process and return its module namespace.
+ * Node's ESM registry caches it, so repeated loads within one CLI invocation
+ * evaluate the file once.
+ *
+ * Refuses while armed. Under `--sandbox` the policy modules are imported inside
+ * a child process (`../discovery/sandbox/policy-run.ts`); arriving here anyway
+ * means something is about to execute project-authored code in the CLI's own
+ * process, which is exactly what the flag promises does not happen. Falling
+ * through would make `--sandbox` mean less than it says with nothing visible to
+ * notice, so this throws instead.
+ */
+export async function importPolicyModule(policyPath: string): Promise<PolicyModuleNamespace> {
+  if (armed) {
+    throw new Error(
+      `Refusing to import the policy module ${policyPath} into the chant process under --sandbox: it is project-authored code and must be imported inside the sandbox boundary (packages/core/src/lint/policy-sandbox.ts's runProjectPolicies).`,
+    );
+  }
+  return (await import(policyPath)) as PolicyModuleNamespace;
+}

package/src/lint/policy-sandbox.ts

@@ -0,0 +1,123 @@
+import { resolve } from "node:path";
+import {
+  runPostSynthChecks,
+  type PostSynthCheck,
+  type PostSynthContext,
+  type PostSynthDiagnostic,
+} from "./post-synth";
+import { loadPolicyChecks } from "./policy";
+import {
+  armSandboxPolicyExecution,
+  isSandboxPolicyExecutionArmed,
+  resetSandboxPolicyExecutionForTests,
+} from "./policy-import";
+import type { EncodablePolicyBuildResult } from "../discovery/sandbox/policy-wire";
+
+/**
+ * chant #1131 — decides WHERE a project's `lint.policies` checks run.
+ *
+ * A policy is project-authored code. Every other piece of project code moved
+ * behind the `--sandbox` boundary in chant #1045 (run-fallback source), #1093
+ * (composite factories, constructors, intrinsic tags) and #1113
+ * (`chant.config.ts`), and all three had to leave this one out: the config
+ * declares its policies as *paths*, so putting the config behind the boundary
+ * did not put them there with it. `chant build` imported each policy module and
+ * called its `check` function in the CLI's own process, after discovery was
+ * over, with the CLI's filesystem, network, environment and process-spawn
+ * access. This module closes it.
+ *
+ * ## Why an armed process mode rather than a threaded option
+ *
+ * The same reason `../config-sandbox.ts` gives. `./policy.ts`'s
+ * `loadPolicyChecks` is exported from chant-core's public surface and called
+ * from more than one place (`../cli/commands/build.ts` for a build, and
+ * `evaluateProjectPolicies` for the `policyGate` Op step). Threading a
+ * `sandbox` flag to each is fail-OPEN: miss one and project code executes in
+ * the CLI process with nothing to notice. Arming the process once, before any
+ * policy is loaded, is fail-CLOSED — `loadPolicyChecks` REFUSES while armed, so
+ * a call site nobody remembered gets a loud error rather than a silent
+ * execution.
+ *
+ * ## What arms it
+ *
+ * Both ways of turning sandboxing on, unlike `../config-sandbox.ts`. That
+ * asymmetry is not an oversight: the config has a bootstrap limit (reading
+ * `build.sandbox` out of `chant.config.ts` means running it, so only the CLI
+ * flag, known before any config is touched, can cover the config's own
+ * evaluation). Policies have no such limit — they are loaded long after the
+ * config is known — so `build.sandbox: true` in a project's config sandboxes
+ * them just as `--sandbox` does, and `../cli/commands/build.ts` arms this from
+ * the RESOLVED value.
+ *
+ * There is deliberately no disarm: a security mode that can be turned off
+ * partway through a process is not one.
+ */
+
+/**
+ * The mode itself lives on `./policy-import.ts` — the leaf module that actually
+ * performs an in-process policy import, so the refusal sits on the narrowest
+ * possible thing and `./policy.ts` can consult it without importing this file
+ * (which imports `./policy.ts`). Re-exported here because this is where the
+ * decision is documented and where callers look.
+ *
+ * `armSandboxPolicyExecution` is called from `../cli/commands/build.ts` once
+ * `build.sandbox`/`--sandbox` has resolved, and from `../cli/main.ts` off the
+ * parsed flag.
+ */
+export { armSandboxPolicyExecution, isSandboxPolicyExecutionArmed, resetSandboxPolicyExecutionForTests };
+
+export interface ProjectPolicyRun {
+  /** `lint.policies` as declared in the config — relative paths, resolved against {@link configDir}. */
+  policies: readonly string[];
+  /** The `chant.config.*` directory (`lint.policies` paths are relative to it), also the child's read allowance. */
+  configDir: string;
+  /** The merged, serialized build result the checks run over. */
+  buildResult: EncodablePolicyBuildResult & PostSynthContext["buildResult"];
+  /** `--env`, else `ownership.env`. Becomes `ctx.env`. */
+  env?: string;
+  /**
+   * Checks the caller already loaded into THIS process, before the build ran.
+   *
+   * `chant build` has always loaded `lint.policies` up front rather than at the
+   * point of use, so a policy path that doesn't resolve fails the command
+   * immediately — including when the build itself goes on to fail, which is
+   * exactly when a typo'd path would otherwise go unnoticed. Preserving that
+   * for the unsandboxed path is the whole reason this field exists.
+   *
+   * Ignored when armed: under `--sandbox` there is nothing loaded here to pass,
+   * and `loadPolicyChecks` refuses outright.
+   */
+  preloaded?: PostSynthCheck[];
+}
+
+/**
+ * Run a project's organizational policy checks over a finished build and return
+ * their diagnostics. Sandboxed in a post-merge child when armed, in-process
+ * otherwise.
+ *
+ * The unarmed path is byte-for-byte what `chant build` has always done: load
+ * the modules, hand every check one `PostSynthContext`, concatenate what they
+ * return. The armed path does the same thing on the other side of a process
+ * boundary — see `../discovery/sandbox/policy-run.ts`.
+ */
+export async function runProjectPolicies(run: ProjectPolicyRun): Promise<PostSynthDiagnostic[]> {
+  if (run.policies.length === 0) return [];
+
+  if (!isSandboxPolicyExecutionArmed()) {
+    const checks = run.preloaded ?? (await loadPolicyChecks([...run.policies], run.configDir));
+    if (checks.length === 0) return [];
+    return runPostSynthChecks(checks, run.buildResult, run.env);
+  }
+
+  // Dynamic, not static, for the same reason `../config-sandbox.ts` imports
+  // `../discovery/sandbox/config-run` dynamically: this pulls in `esbuild`, a
+  // large CJS package no unsandboxed build should pay to load.
+  const { runPoliciesSandboxed } = await import("../discovery/sandbox/policy-run");
+  const { diagnostics } = await runPoliciesSandboxed({
+    policyPaths: run.policies.map((p) => resolve(run.configDir, p)),
+    buildResult: run.buildResult,
+    env: run.env,
+    projectRoot: run.configDir,
+  });
+  return diagnostics;
+}

package/src/lint/policy.ts

@@ -9,15 +9,33 @@ import { resolveProjectLexicons, loadPlugins } from "../cli/plugins";
 import { build } from "../build";
 import { runPostSynthChecks, isPostSynthCheck } from "./post-synth";
 import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+import { importPolicyModule, isSandboxPolicyExecutionArmed } from "./policy-import";
 
-/** Load project policy checks (one or more `PostSynthCheck` exports) from files. */
+/**
+ * Load project policy checks (one or more `PostSynthCheck` exports) from files,
+ * **into this process**.
+ *
+ * chant #1131 — refuses while `./policy-sandbox.ts` is armed. Under `--sandbox`
+ * the policy modules are imported and their checks run inside a child process
+ * (`runProjectPolicies`); reaching this function anyway means a call site is
+ * about to execute project-authored code in the CLI's own process, which is
+ * precisely the thing the flag promises does not happen. Failing loudly is the
+ * only honest option — falling through would make `--sandbox` mean less than it
+ * says without anything visible to notice.
+ */
 export async function loadPolicyChecks(paths: string[], configDir: string): Promise<PostSynthCheck[]> {
+  if (isSandboxPolicyExecutionArmed()) {
+    throw new Error(
+      `Cannot load lint.policies (${paths.join(", ")}) in the chant process under --sandbox: a policy module is project-authored code, and it must be imported inside the sandbox boundary. This is a chant bug — the caller should route through runProjectPolicies() (packages/core/src/lint/policy-sandbox.ts).`,
+    );
+  }
+
   const checks: PostSynthCheck[] = [];
   for (const p of paths) {
     const resolved = resolve(configDir, p);
     let mod: Record<string, unknown>;
     try {
-      mod = (await import(resolved)) as Record<string, unknown>;
+      mod = await importPolicyModule(resolved);
     } catch (err) {
       throw new Error(
         `Failed to load policy "${p}": ${err instanceof Error ? err.message : String(err)}`,