@intentius/chant 0.24.0 → 0.26.0

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

@@ -0,0 +1,310 @@
+import { describe, test, expect } from "vitest";
+import { AttrRef } from "../../attrref";
+import { CHILD_PROJECT_MARKER } from "../../child-project";
+import { DECLARABLE_MARKER, type Declarable } from "../../declarable";
+import { INTRINSIC_MARKER, type Intrinsic } from "../../intrinsic";
+import { DiscoveryError } from "../../errors";
+import { createResource } from "../../runtime";
+import { resolveAttrRefs } from "../resolve";
+import { isAttrRefLike } from "../../utils";
+import type { PostSynthCheck } from "../../lint/post-synth";
+import { runPostSynthChecks } from "../../lint/post-synth";
+import {
+  decodePolicyBuildResult,
+  encodePolicyBuildResult,
+  scanPolicyDiagnostics,
+  type EncodablePolicyBuildResult,
+} from "./policy-wire";
+
+/**
+ * chant #1131 — the contract between the CLI process and the sandboxed policy
+ * child, in both directions.
+ *
+ * These tests are the "document the difference precisely and pin it" half of
+ * the brief. A policy check under `--sandbox` no longer sees the parent's own
+ * live objects; it sees what survived `encodePolicyBuildResult` →
+ * `JSON.parse(JSON.stringify(...))` → `decodePolicyBuildResult`. Everything
+ * that is the SAME is asserted here so a regression is caught, and everything
+ * that is NARROWER is asserted here too, so the narrowing can never quietly
+ * change without a test failing.
+ */
+
+/** What the IPC channel actually does to the payload. Every test goes through it — an in-memory hand-off would prove nothing. */
+function overTheWire(result: EncodablePolicyBuildResult) {
+  const wire = encodePolicyBuildResult(result);
+  return decodePolicyBuildResult(JSON.parse(JSON.stringify(wire)));
+}
+
+function emptyResult(overrides: Partial<EncodablePolicyBuildResult> = {}): EncodablePolicyBuildResult {
+  return {
+    outputs: new Map(),
+    entities: new Map(),
+    warnings: [],
+    errors: [],
+    sourceFileCount: 0,
+    ...overrides,
+  };
+}
+
+describe("the build result a sandboxed policy sees (chant #1131)", () => {
+  test("outputs — the surface the reference policy corpus actually reads — cross exactly", () => {
+    const result = emptyResult({
+      outputs: new Map<string, string | { primary: string; files?: Record<string, string>; warnings?: string[] }>([
+        ["k8s", "apiVersion: v1\nkind: Service\n"],
+        ["aws", { primary: '{"Resources":{}}', files: { "net.template.json": "{}" }, warnings: ["dropped a key"] }],
+      ]),
+      warnings: ["a build warning"],
+      sourceFileCount: 3,
+    });
+
+    const decoded = overTheWire(result);
+
+    expect(decoded.outputs.get("k8s")).toBe("apiVersion: v1\nkind: Service\n");
+    expect(decoded.outputs.get("aws")).toEqual({
+      primary: '{"Resources":{}}',
+      files: { "net.template.json": "{}" },
+      warnings: ["dropped a key"],
+    });
+    expect(decoded.outputs).toBeInstanceOf(Map);
+    expect(decoded.warnings).toEqual(["a build warning"]);
+    expect(decoded.sourceFileCount).toBe(3);
+  });
+
+  test("entities cross as a live Map of Declarables, with AttrRefs still resolved and still AttrRefs", () => {
+    const Vpc = createResource("Test::Vpc", "test", { vpcId: "VpcId" });
+    const Subnet = createResource("Test::Subnet", "test", { subnetId: "SubnetId" });
+    const vpc = new Vpc({ CidrBlock: "10.0.0.0/16" });
+    const subnet = new Subnet({ VpcId: (vpc as unknown as Record<string, AttrRef>).vpcId });
+    const entities = new Map<string, Declarable>([
+      ["Vpc", vpc as unknown as Declarable],
+      ["Subnet", subnet as unknown as Declarable],
+    ]);
+    resolveAttrRefs(entities);
+
+    const decoded = overTheWire(emptyResult({ entities }));
+
+    expect([...decoded.entities.keys()]).toEqual(["Vpc", "Subnet"]);
+    const decodedSubnet = decoded.entities.get("Subnet") as unknown as { props: { VpcId: unknown } };
+    expect(isAttrRefLike(decodedSubnet.props.VpcId)).toBe(true);
+    // A real AttrRef, not a `{__attrRef}` envelope — several chant call sites
+    // (and any policy doing the same) test `instanceof`, not duck typing.
+    expect(decodedSubnet.props.VpcId).toBeInstanceOf(AttrRef);
+    expect((decodedSubnet.props.VpcId as AttrRef).getLogicalName()).toBe("Vpc");
+    // The WeakRef points at the DECODED parent — self-consistent inside the
+    // child, which is all a check over `ctx.entities` can observe.
+    expect((decodedSubnet.props.VpcId as AttrRef).parent.deref()).toBe(decoded.entities.get("Vpc"));
+  });
+
+  test("a decoded entity's own enumerable keys match the original's", () => {
+    // `createResource` defines lexicon/entityType/kind/props/attributes
+    // non-enumerable and the per-attribute AttrRefs enumerable; the decoder
+    // reproduces exactly that split. So `Object.keys(entity)` — which a policy
+    // walking an entity generically would use — is the same on both sides.
+    const Bucket = createResource("Test::Bucket", "test", { arn: "Arn", name: "Name" });
+    const bucket = new Bucket({ Versioning: true });
+    const entities = new Map<string, Declarable>([["Bucket", bucket as unknown as Declarable]]);
+    resolveAttrRefs(entities);
+
+    const decoded = overTheWire(emptyResult({ entities }));
+
+    expect(Object.keys(decoded.entities.get("Bucket") as object)).toEqual(Object.keys(bucket as object));
+    expect((decoded.entities.get("Bucket") as unknown as { props: unknown }).props).toEqual({ Versioning: true });
+    expect(DECLARABLE_MARKER in (decoded.entities.get("Bucket") as object)).toBe(true);
+  });
+
+  test("encoding is idempotent over an already-decoded entity — the run-fallback subset pays nothing extra", () => {
+    // Under `--sandbox` the parent's merged entities ALREADY include decoded
+    // ones for every run-fallback file (`./run.ts`). If a second round trip
+    // narrowed them further, this child would be doing real damage to part of
+    // the set. It does not: encode∘decode∘encode === encode.
+    const Queue = createResource("Test::Queue", "test", { url: "Url" });
+    const Fn = createResource("Test::Fn", "test", {});
+    const queue = new Queue({ Fifo: true });
+    const fn = new Fn({ QueueUrl: (queue as unknown as Record<string, AttrRef>).url });
+    const entities = new Map<string, Declarable>([
+      ["Queue", queue as unknown as Declarable],
+      ["Fn", fn as unknown as Declarable],
+    ]);
+    resolveAttrRefs(entities);
+
+    const once = encodePolicyBuildResult(emptyResult({ entities }));
+    const twice = encodePolicyBuildResult(emptyResult({ entities: decodePolicyBuildResult(once).entities }));
+
+    expect(twice.entities).toEqual(once.entities);
+  });
+
+  test("NARROWER: an intrinsic decodes to a toJSON()-bearing wrapper, not to its own class", () => {
+    class Sub implements Intrinsic {
+      readonly [INTRINSIC_MARKER] = true as const;
+      constructor(readonly template: string) {}
+      toJSON(): unknown {
+        return { "Fn::Sub": this.template };
+      }
+    }
+    const Fn = createResource("Test::Fn", "test", {});
+    const fn = new Fn({ Name: new Sub("${AWS::StackName}-fn") });
+    const entities = new Map<string, Declarable>([["Fn", fn as unknown as Declarable]]);
+    resolveAttrRefs(entities);
+
+    const decoded = overTheWire(emptyResult({ entities }));
+    const name = (decoded.entities.get("Fn") as unknown as { props: { Name: Intrinsic & { template?: string } } }).props.Name;
+
+    // What still works: the marker, and the serialized form every serializer
+    // and every output-reading check goes through.
+    expect(INTRINSIC_MARKER in (name as object)).toBe(true);
+    expect(name.toJSON()).toEqual({ "Fn::Sub": "${AWS::StackName}-fn" });
+    // What does NOT: the class, and its own fields. A policy that reaches into
+    // an intrinsic's internals rather than its `toJSON()` sees nothing under
+    // `--sandbox`. Documented in docs/.../architecture/sandbox.mdx.
+    expect(name).not.toBeInstanceOf(Sub);
+    expect(name.template).toBeUndefined();
+  });
+
+  test("NARROWER: errors cross as plain objects, not Error instances", () => {
+    const result = emptyResult({ errors: [new DiscoveryError("/p/a.ts", "boom", "import")] });
+
+    const decoded = overTheWire(result);
+
+    expect(decoded.errors).toEqual([
+      { name: "DiscoveryError", file: "/p/a.ts", message: "boom", type: "import" },
+    ]);
+    expect(decoded.errors[0]).not.toBeInstanceOf(Error);
+    // Never observable in practice: `chant build` runs policies only when the
+    // build produced no errors at all, so this array is always empty there.
+  });
+
+  test("REFUSED, not dropped: a nestedStack() child project has no wire form", () => {
+    const child = { [DECLARABLE_MARKER]: true, [CHILD_PROJECT_MARKER]: true, lexicon: "test", entityType: "Test::Child" };
+    const entities = new Map<string, Declarable>([["Child", child as unknown as Declarable]]);
+
+    expect(() => encodePolicyBuildResult(emptyResult({ entities }))).toThrow(/child project \(nestedStack\(\)\)/);
+  });
+
+  test("REFUSED, not dropped: a serializer output that is not data is named by key path", () => {
+    const outputs = new Map<string, string | { primary: string }>([
+      ["weird", { primary: "ok", extra: () => 1 } as unknown as { primary: string }],
+    ]);
+
+    // `encodeOutput` copies only the declared fields, so a stray function on a
+    // SerializerResult never reaches the wire in the first place. The scan is
+    // the backstop for the fields that ARE carried.
+    const encoded = encodePolicyBuildResult(emptyResult({ outputs }));
+    expect(encoded.outputs).toEqual([["weird", { primary: "ok" }]]);
+
+    expect(() =>
+      encodePolicyBuildResult(emptyResult({ manifest: { generatedAt: new Date(0) } })),
+    ).toThrow(/buildResult\.manifest\.generatedAt: a Date/);
+  });
+
+  test("the undeclared-but-carried fields (dependencies, manifest, foldDecisions, buildParams) cross too", () => {
+    const result = emptyResult({
+      dependencies: new Map([["Subnet", new Set(["Vpc"])]]),
+      manifest: { lexicons: ["test"], outputs: {}, deployOrder: ["test"] },
+      foldDecisions: [{ file: "/p/a.ts", mode: "fold", resourceCount: 1 }],
+      buildParams: [{ name: "tier", value: "prod", source: "cli" }],
+    });
+
+    const decoded = overTheWire(result) as unknown as {
+      dependencies: Map<string, Set<string>>;
+      manifest: unknown;
+      foldDecisions: unknown[];
+      buildParams: unknown[];
+    };
+
+    expect(decoded.dependencies.get("Subnet")).toEqual(new Set(["Vpc"]));
+    expect(decoded.manifest).toEqual({ lexicons: ["test"], outputs: {}, deployOrder: ["test"] });
+    expect(decoded.foldDecisions).toEqual([{ file: "/p/a.ts", mode: "fold", resourceCount: 1 }]);
+    expect(decoded.buildParams).toEqual([{ name: "tier", value: "prod", source: "cli" }]);
+  });
+
+  test("a check run over the decoded result produces what it produces over the original", () => {
+    const Ingress = createResource("Test::Ingress", "test", {});
+    const entities = new Map<string, Declarable>([
+      ["Ing", new Ingress({ tls: [] }) as unknown as Declarable],
+    ]);
+    resolveAttrRefs(entities);
+    const result = emptyResult({ entities, outputs: new Map([["test", "kind: Ingress\n"]]) });
+
+    const check: PostSynthCheck = {
+      id: "T",
+      description: "reads both surfaces",
+      check(ctx) {
+        const out: Array<{ checkId: string; severity: "error"; message: string; entity?: string }> = [];
+        for (const [name, entity] of ctx.entities) {
+          const props = (entity as unknown as { props?: { tls?: unknown[] } }).props;
+          if (Array.isArray(props?.tls) && props.tls.length === 0) {
+            out.push({ checkId: "T", severity: "error", message: `${name} has no TLS in ${ctx.env}`, entity: name });
+          }
+        }
+        for (const [, o] of ctx.outputs) {
+          if (typeof o === "string" && o.includes("Ingress")) {
+            out.push({ checkId: "T", severity: "error", message: "output mentions Ingress" });
+          }
+        }
+        return out;
+      },
+    };
+
+    const inProcess = runPostSynthChecks([check], result as unknown as Parameters<typeof runPostSynthChecks>[1], "prod");
+    const sandboxed = runPostSynthChecks([check], overTheWire(result), "prod");
+
+    expect(sandboxed).toEqual(inProcess);
+  });
+});
+
+describe("what a policy is allowed to return (chant #1131)", () => {
+  const P = "/p/policies/org.ts";
+
+  test("plain diagnostics pass", () => {
+    expect(
+      scanPolicyDiagnostics(
+        [
+          { checkId: "A", severity: "error", message: "m", entity: "E", lexicon: "k8s" },
+          { checkId: "B", severity: "info", message: "n" },
+        ],
+        P,
+      ),
+    ).toEqual([]);
+    expect(scanPolicyDiagnostics([], P)).toEqual([]);
+  });
+
+  test("a function on a diagnostic is named, with the policy that produced it", () => {
+    const offenders = scanPolicyDiagnostics([{ checkId: "A", severity: "error", message: "m", fix: () => 1 }], P);
+
+    expect(offenders).toEqual([{ policy: P, path: "[0].fix", found: "a function" }]);
+  });
+
+  test("a Date, a class instance and a circular reference are each named", () => {
+    expect(scanPolicyDiagnostics([{ checkId: "A", severity: "error", message: "m", at: new Date(0) }], P)[0]).toMatchObject({
+      path: "[0].at",
+      found: "a Date",
+    });
+    expect(scanPolicyDiagnostics([{ checkId: "A", severity: "error", message: "m", err: new Error("x") }], P)[0]).toMatchObject({
+      found: "an Error",
+    });
+    const circular: Record<string, unknown> = { checkId: "A", severity: "error", message: "m" };
+    circular.self = circular;
+    expect(scanPolicyDiagnostics([circular], P)[0]).toMatchObject({ found: "a circular reference" });
+  });
+
+  test("a value that is data but is not a diagnostic is named too", () => {
+    expect(scanPolicyDiagnostics([{ severity: "error", message: "m" }], P)).toEqual([
+      { policy: P, path: "[0].checkId", found: "not a non-empty string" },
+    ]);
+    expect(scanPolicyDiagnostics([{ checkId: "A", severity: "fatal", message: "m" }], P)).toEqual([
+      { policy: P, path: "[0].severity", found: `not one of "error", "warning", "info"` },
+    ]);
+    expect(scanPolicyDiagnostics(["just a string"], P)).toEqual([
+      { policy: P, path: "[0]", found: "a string" },
+    ]);
+  });
+
+  test("a check that does not return an array at all is named", () => {
+    expect(scanPolicyDiagnostics(undefined, P)).toEqual([
+      { policy: P, path: "<return value>", found: "undefined" },
+    ]);
+    expect(scanPolicyDiagnostics({ checkId: "A" }, P)).toEqual([
+      { policy: P, path: "<return value>", found: "a object" },
+    ]);
+  });
+});

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");
+}