@intentius/chant 0.51.0 → 0.52.1

package/src/lexicon.ts

@@ -1163,10 +1163,10 @@ export interface LexiconPlugin {
    * where the wrong delete gets proposed.
    *
    * Declared per read path, because the answer differs by path. aws stamps tags
-   * at synthesis and reads them on the deep observation and on live export,
-   * while its `describeResources` is sourced from `describe-stack-resources`,
-   * which returns no tags — so an `owned: true` thin read against aws can only
-   * answer `unknown`, and does.
+   * at synthesis and reads them per resource on the deep observation and on
+   * live export, while its `describeResources` is sourced from
+   * `describe-stack-resources`, which returns no per-resource tags — so that
+   * path resolves the verdict from the stack's own tags (#1998).
    *
    * Absent means no channel anywhere: every verdict must be `unknown`.
    */
@@ -1417,11 +1417,12 @@ export interface ResourceMetadata {
    *
    * Set only when the live model actually carries the channel and the
    * managed-by marker is present — an absent channel means an absent field,
-   * never a guess. In particular aws's thin read is sourced from
-   * `describe-stack-resources`, which returns no tags at all, so aws never
-   * populates this here; aws teardown is stack-level and reads the stack's own
-   * tags instead (later PR). A populated `marker` does not by itself imply an
-   * {@link ownership} verdict on paths that do not declare a marker channel.
+   * never a guess. The granularity is whatever the channel reads at: aws's thin
+   * read is sourced from `describe-stack-resources`, which returns no
+   * per-resource tags, so it reads the STACK's own tags and every member of a
+   * marked stack carries that stack's identity (#1998). A populated `marker`
+   * does not by itself imply an {@link ownership} verdict on paths that do not
+   * declare a marker channel.
    */
   marker?: OwnershipMarker;
   /**

package/src/lifecycle/assert-live.ts

@@ -15,9 +15,8 @@
  *
  * Marker verification is best-effort by the same logic {@link
  * ResourceMetadata.marker}'s own contract states: a lexicon with no marker
- * channel on this read path (aws's thin `describeResources`, `ownership:
- * "unknown"`) reports no marker at all, which is not the same claim as
- * "foreign". Enforcing a match whenever the channel exists — a present
+ * channel on this read path reports no marker at all, which is not the same
+ * claim as "foreign". Enforcing a match whenever the channel exists — a present
  * mismatch, or `ownership: "foreign"` with no marker to show — catches the
  * case the harness cares about (a same-named leftover from another env);
  * an absent channel is passed through unverified rather than making every

package/src/lifecycle/change-set.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, test } from "vitest";
-import { buildChangeSet, renderChangeSet, summarize, gitlabMrReport } from "./change-set";
+import {
+  buildChangeSet,
+  renderChangeSet,
+  renderChangeSetMarkdown,
+  summarize,
+  gitlabMrReport,
+  unobservedPlanNotice,
+  type ChangeSet,
+  type ChangeSetEntry,
+} from "./change-set";
 import type { ResourceMetadata } from "../lexicon";
 
 const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
@@ -446,3 +455,137 @@ describe("buildChangeSet: not-observed is not absent (#1089)", () => {
     expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
   });
 });
+
+// ── Markdown report (#1983) ──────────────────────────────────────────────
+
+function entry(overrides: Partial<ChangeSetEntry> = {}): ChangeSetEntry {
+  return {
+    name: "db",
+    type: "AWS::RDS::DBInstance",
+    lexicon: "aws",
+    action: "update",
+    evidence: { declared: true, inSnapshot: true, live: true, observed: true },
+    ownership: "unknown",
+    ...overrides,
+  };
+}
+
+function set(entries: ChangeSetEntry[]): ChangeSet {
+  return { env: "prod", entries };
+}
+
+describe("unobservedPlanNotice (#1983)", () => {
+  test("empty when nothing is unobserved", () => {
+    expect(unobservedPlanNotice(set([entry({ action: "noop" })]))).toEqual([]);
+  });
+
+  test("one notice naming the count, matching the CLI's stderr wording", () => {
+    const cs = set([
+      entry({ name: "a", action: "unobserved", unobservedReason: "no-binding" }),
+      entry({ name: "b", action: "unobserved", unobservedReason: "read-failed" }),
+      entry({ name: "c", action: "noop" }),
+    ]);
+    expect(unobservedPlanNotice(cs)).toEqual([
+      "2 declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.",
+    ]);
+  });
+});
+
+describe("renderChangeSetMarkdown (#1983)", () => {
+  test("empty plan: header only, no ANSI, deterministic", () => {
+    const out = renderChangeSetMarkdown(set([]));
+    expect(out).toBe(
+      "## Plan for `prod`\n\n0 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 0 noop, 0 unobserved\n",
+    );
+    expect(out).not.toMatch(/\x1b\[/);
+  });
+
+  test("counts header and grouped sections, attributed to lexicon", () => {
+    const cs = set([
+      entry({ name: "new-bucket", type: "S3::Bucket", lexicon: "aws", action: "create", evidence: { declared: true, inSnapshot: false, live: false, observed: true } }),
+      entry({ name: "web", type: "K8s::Apps::Deployment", lexicon: "k8s", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true } }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("## Plan for `prod`");
+    expect(out).toContain("1 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 1 noop, 0 unobserved");
+    expect(out).toContain("### CREATE");
+    expect(out).toContain("- `new-bucket` (S3::Bucket) `aws`");
+    expect(out).toContain("### NOOP");
+    expect(out).toContain("- `web` (K8s::Apps::Deployment) `k8s`");
+  });
+
+  test("deltas render in a fenced block, forced path marked", () => {
+    const cs = set([
+      entry({
+        deltas: [
+          { path: "attributes.DBInstanceIdentifier", oldValue: "app-db", newValue: "app-db-2" },
+          { path: "attributes.AllocatedStorage", oldValue: 20, newValue: 40 },
+        ],
+        disruption: "destroy",
+        disruptionBecause: ["attributes.DBInstanceIdentifier"],
+        disruptionDetail: "DBInstanceIdentifier is create-only",
+      }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("**destroy**: DBInstanceIdentifier is create-only");
+    expect(out).toContain("```");
+    expect(out).toContain("! attributes.DBInstanceIdentifier: app-db → app-db-2");
+    expect(out).toContain("attributes.AllocatedStorage: 20 → 40");
+  });
+
+  test("disruption count rides the header, same as the human render", () => {
+    const cs = set([entry({ disruption: "in-place" }), entry({ name: "web", disruption: "destroy" })]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("**Disruption:** 1 in-place, 1 destroy");
+  });
+
+  test("unobserved renders both the prominent notice and its own section, same wording as the human render", () => {
+    const cs = set([
+      entry({ name: "crd-widget", action: "unobserved", unobservedReason: "no-binding", unobservedDetail: "no kubectl context for prod" }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain(
+      "> **1 declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.**",
+    );
+    expect(out).toContain("### UNOBSERVED (declared; chant could not read live state — no action proposed)");
+    expect(out).toContain("- `crd-widget`");
+    expect(out).toContain("no binding for this environment");
+    expect(out).toContain("no kubectl context for prod");
+  });
+
+  test("a clean plan (no holes) carries no unobserved notice at all", () => {
+    const out = renderChangeSetMarkdown(set([entry({ action: "noop" })]));
+    expect(out).not.toContain("could not be observed");
+    expect(out).not.toContain("UNOBSERVED");
+  });
+
+  test("effect entries render as their own line, no deltas", () => {
+    const cs = set([
+      entry({
+        name: "receipt-x",
+        action: "effect",
+        effect: "seed-admin",
+        effectReason: "receipt-absent",
+        effectDetail: "no receipt recorded yet",
+        deltas: undefined,
+      }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("- effect will fire: `seed-admin` — receipt `receipt-x`");
+    expect(out).toContain("no receipt recorded yet");
+  });
+
+  test("a group past the fold threshold collapses into <details>, a small one does not", () => {
+    const many = Array.from({ length: 25 }, (_, i) =>
+      entry({ name: `bucket-${i}`, action: "create", evidence: { declared: true, inSnapshot: false, live: false, observed: true }, deltas: undefined }),
+    );
+    const out = renderChangeSetMarkdown(set(many));
+    expect(out).toContain("<details><summary>25 entries — click to expand</summary>");
+    expect(out).toContain("</details>");
+    expect(out).toContain("- `bucket-0`");
+    expect(out).toContain("- `bucket-24`");
+
+    const few = renderChangeSetMarkdown(set(many.slice(0, 3)));
+    expect(few).not.toContain("<details>");
+  });
+});

package/src/lifecycle/change-set.ts

@@ -325,6 +325,45 @@ export function gitlabMrReport(cs: ChangeSet): GitlabMrReport {
   return { create: counts.create, update: counts.update, delete: counts.delete };
 }
 
+/**
+ * Warning a plan should print when it carries a hole — a declared entity the
+ * lexicon could not observe (#1089). The `--json` and `--report gitlab-mr`
+ * shapes have no column for `unobserved`, so both the CLI (on stderr) and the
+ * `markdown` report (in the body, since a reviewer never sees a job's stderr)
+ * read this same wording rather than drifting apart. Empty when the plan has
+ * no hole. Same discipline as {@link disruptionNotices} in `./disruption`.
+ */
+export function unobservedPlanNotice(cs: ChangeSet): string[] {
+  const count = summarize(cs).unobserved;
+  return count > 0
+    ? [
+        `${count} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
+      ]
+    : [];
+}
+
+/**
+ * Section heading text for one action group — shared between {@link renderChangeSet}
+ * and {@link renderChangeSetMarkdown} so the wording never drifts between the
+ * terminal render and the reviewer-facing one.
+ */
+function actionSectionLabel(action: ChangeAction, hasDisruption: boolean): string {
+  switch (action) {
+    case "unobserved":
+      return "UNOBSERVED (declared; chant could not read live state — no action proposed)";
+    case "runtime":
+      return "RUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate)";
+    case "effect":
+      return "EFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt)";
+    case "update":
+      return hasDisruption
+        ? "UPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe)"
+        : "UPDATE";
+    default:
+      return action.toUpperCase();
+  }
+}
+
 /** Human-readable render of a change set. Pure — returns a string. */
 export function renderChangeSet(cs: ChangeSet): string {
   const counts = summarize(cs);
@@ -344,17 +383,7 @@ export function renderChangeSet(cs: ChangeSet): string {
   for (const action of ACTION_ORDER) {
     const group = cs.entries.filter((e) => e.action === action);
     if (group.length === 0) continue;
-    lines.push(
-      action === "unobserved"
-        ? "\nUNOBSERVED (declared; chant could not read live state — no action proposed):"
-        : action === "runtime"
-          ? "\nRUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate):"
-          : action === "effect"
-            ? "\nEFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt):"
-            : action === "update" && disruptionParts.length > 0
-              ? "\nUPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe):"
-              : `\n${action.toUpperCase()}:`,
-    );
+    lines.push(`\n${actionSectionLabel(action, disruptionParts.length > 0)}:`);
     for (const e of group) {
       if (e.action === "effect") {
         lines.push(
@@ -381,6 +410,99 @@ export function renderChangeSet(cs: ChangeSet): string {
   return lines.join("\n");
 }
 
+/**
+ * Entries beyond this in one action group are collapsed into a `<details>`
+ * block in {@link renderChangeSetMarkdown} — a group's worth of rows is fine
+ * to read inline, a hundred-entry plan is not (#1983).
+ */
+const MARKDOWN_FOLD_THRESHOLD = 20;
+
+/** One entry's markdown, mirroring the rows {@link renderChangeSet} prints. */
+function renderMarkdownEntry(e: ChangeSetEntry): string[] {
+  if (e.action === "effect") {
+    return [
+      `- effect will fire: \`${e.effect ?? e.name}\` — receipt \`${e.name}\`${e.type ? ` (${e.type})` : ""}` +
+        `${e.effectDetail ? ` — ${e.effectDetail}` : ""}`,
+    ];
+  }
+  const lexicon = e.lexicon ? ` \`${e.lexicon}\`` : "";
+  const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
+  const why = e.unobservedReason
+    ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+    : "";
+  const owner = e.runtimeOwner ? ` — owned by \`${e.runtimeOwner}\`` : "";
+  // Bolded rather than the plain-text render's bare " — destroy: ..." — a
+  // reviewer scanning a wall of "update" rows should see disruption without
+  // reading every one (#1665).
+  const disruption = e.disruption
+    ? ` — **${e.disruption}**${e.disruptionDetail ? `: ${e.disruptionDetail}` : ""}`
+    : "";
+  const lines = [`- \`${e.name}\`${e.type ? ` (${e.type})` : ""}${lexicon}${own}${why}${owner}${disruption}`];
+
+  if (e.deltas && e.deltas.length > 0) {
+    const forced = new Set(e.disruptionBecause ?? []);
+    lines.push("  ```");
+    for (const d of e.deltas) {
+      lines.push(`  ${forced.has(d.path) ? "! " : "  "}${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+    }
+    lines.push("  ```");
+  }
+  return lines;
+}
+
+/**
+ * Markdown projection of a change set (#1983) — sized for a PR/MR comment
+ * rather than a terminal. A scannable counts header, entries grouped by
+ * action and attributed to their lexicon, deltas in a fenced block, and any
+ * group past {@link MARKDOWN_FOLD_THRESHOLD} folded into a `<details>` so a
+ * large plan doesn't bury the comment. Pure — no ANSI, no I/O — and
+ * deterministic: same entry ordering as {@link renderChangeSet}.
+ *
+ * Both a hole (#1089) and an expensive verdict (#1665) are surfaced IN the
+ * body, not left to stderr the way `--json` and `--report gitlab-mr` leave
+ * them: a reviewer reading a comment never sees the job's log, so a plan
+ * carrying either must not read as clean.
+ */
+export function renderChangeSetMarkdown(cs: ChangeSet): string {
+  const counts = summarize(cs);
+  const lines: string[] = [`## Plan for \`${cs.env}\``, "", ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ")];
+
+  const disruption = summarizeDisruption(cs);
+  const disruptionParts = (Object.entries(disruption) as Array<[Disruption, number]>)
+    .filter(([, n]) => n > 0)
+    .map(([level, n]) => `${n} ${level}`);
+  if (disruptionParts.length > 0) {
+    lines.push("", `**Disruption:** ${disruptionParts.join(", ")}`);
+  }
+
+  for (const notice of unobservedPlanNotice(cs)) {
+    lines.push("", `> **${notice}**`);
+  }
+
+  for (const action of ACTION_ORDER) {
+    const group = cs.entries.filter((e) => e.action === action);
+    if (group.length === 0) continue;
+
+    lines.push("", `### ${actionSectionLabel(action, disruptionParts.length > 0)}`);
+
+    const body = group.flatMap((e) => renderMarkdownEntry(e));
+    if (group.length > MARKDOWN_FOLD_THRESHOLD) {
+      lines.push(
+        "",
+        `<details><summary>${group.length} entries — click to expand</summary>`,
+        "",
+        ...body,
+        "",
+        "</details>",
+      );
+    } else {
+      lines.push("", ...body);
+    }
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
 function fmt(v: unknown): string {
   if (v === undefined) return "<unset>";
   if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;

package/src/lint/policy-build-parity.test.ts

@@ -0,0 +1,232 @@
+/**
+ * chant #2002 — the `policyGate` Op step must gate on the build `chant build`
+ * produces, not on a different one.
+ *
+ * `evaluateProjectPolicies` used to assemble `build()`'s options itself, two of
+ * them against `buildCommand`'s nine. It built with fold off (the path #1134
+ * retired as the default), without the project's config (so serializers lost
+ * their lexicon-scoped dialect settings) and without `buildRoots` (so
+ * config-declared roots contributed nothing) — a gate could pass a build `chant
+ * build` fails. Both callers now assemble through
+ * `../cli/build-options.ts`'s `resolveProjectBuildOptions`, and the first test
+ * below fails if either ever grows an option the other does not get.
+ *
+ * `build()` is wrapped rather than replaced: every assertion here is about a
+ * real build of a real fixture, and the wrapper only records what each caller
+ * asked for.
+ */
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { BuildOptions, BuildResult } from "../build";
+
+const recorder = vi.hoisted(() => ({
+  options: [] as (BuildOptions | undefined)[],
+  results: [] as BuildResult[],
+}));
+
+vi.mock("../build", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../build")>();
+  return {
+    ...actual,
+    build: async (...args: Parameters<typeof actual.build>) => {
+      recorder.options.push(args[3]);
+      const result = await actual.build(...args);
+      recorder.results.push(result);
+      return result;
+    },
+  };
+});
+
+const { evaluateProjectPolicies } = await import("./policy");
+const { buildCommand } = await import("../cli/commands/build");
+const { resolveProjectLexicons, loadPlugins } = await import("../cli/plugins");
+
+/** Run `chant build` over a fixture the way `cli/main.ts` drives it. */
+async function runChantBuild(dir: string): Promise<{ options: BuildOptions; result: BuildResult }> {
+  const plugins = await loadPlugins(await resolveProjectLexicons(dir));
+  recorder.options.length = 0;
+  recorder.results.length = 0;
+  const outcome = await buildCommand({
+    path: dir,
+    format: "json",
+    output: join(dir, "out", "build.json"),
+    serializers: plugins.map((p) => p.serializer),
+    plugins,
+  });
+  expect(outcome.errors).toEqual([]);
+  return { options: recorder.options[0]!, result: recorder.results[0]! };
+}
+
+/** Run the `policyGate` step's entry point over the same fixture. */
+async function runPolicyGate(dir: string): Promise<{ options: BuildOptions; result: BuildResult }> {
+  recorder.options.length = 0;
+  recorder.results.length = 0;
+  await evaluateProjectPolicies({ path: dir });
+  return { options: recorder.options[0]!, result: recorder.results[0]! };
+}
+
+/** Build-root contributors are freshly bound closures — compare their count. */
+function comparable(options: BuildOptions): Record<string, unknown> {
+  return { ...options, buildRoots: options.buildRoots?.length ?? 0 };
+}
+
+const TRIVIAL_POLICY =
+  `export const check = {\n` +
+  `  id: "ORG-PARITY",\n` +
+  `  description: "records nothing; the build is what is under test",\n` +
+  `  check: () => [],\n` +
+  `};\n`;
+
+describe("policyGate builds the same project chant build does (chant #2002)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-policy-parity-${Date.now()}-${Math.random()}`);
+    await mkdir(join(testDir, "policies"), { recursive: true });
+    await writeFile(join(testDir, "policies", "org.ts"), TRIVIAL_POLICY);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * A forgejo project: `forgejo.runnerLabels` is read by the serializer off
+   * `SerializeContext.config` (lexicons/forgejo/src/serializer.ts), so a build
+   * that drops `config` emits the default label instead of the project's.
+   */
+  async function writeForgejoProject(): Promise<void> {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default {\n` +
+        `  lexicons: ["forgejo"],\n` +
+        `  forgejo: { runnerLabels: { "ubuntu-latest": "self-hosted-arm64" } },\n` +
+        `  lint: { policies: ["policies/org.ts"] },\n` +
+        `};\n`,
+    );
+    await writeFile(
+      join(testDir, "ci.ts"),
+      `import { Workflow, Job, Step } from "@intentius/chant-lexicon-github";\n` +
+        `export const workflow = new Workflow({ name: "CI", on: { push: {} } });\n` +
+        `export const buildJob = new Job({\n` +
+        `  "runs-on": "ubuntu-latest",\n` +
+        `  steps: [new Step({ name: "Build", run: "npm run build" })],\n` +
+        `});\n`,
+    );
+  }
+
+  test("both callers hand build() the identical option set", async () => {
+    await writeForgejoProject();
+
+    const cli = await runChantBuild(testDir);
+    const gate = await runPolicyGate(testDir);
+
+    // The drift this issue is about is an option one caller passes and the
+    // other does not, so the key sets are asserted on their own — a new option
+    // added at one call site fails here even if its value happens to match.
+    expect(Object.keys(gate.options).sort()).toEqual(Object.keys(cli.options).sort());
+    expect(comparable(gate.options)).toEqual(comparable(cli.options));
+    expect(gate.options.fold).toBe(true);
+  });
+
+  test("the project's lexicon-scoped dialect settings reach the gate's serializers", async () => {
+    await writeForgejoProject();
+
+    const cli = await runChantBuild(testDir);
+    const gate = await runPolicyGate(testDir);
+
+    expect([...gate.result.outputs.entries()]).toEqual([...cli.result.outputs.entries()]);
+    const emitted = JSON.stringify([...gate.result.outputs.values()]);
+    // The project's own label, not `DEFAULT_RUNNER_LABELS`' "docker" — which is
+    // what the gate emitted while it built without `config`.
+    expect(emitted).toContain("self-hosted-arm64");
+    expect(emitted).not.toContain("docker");
+  });
+
+  test("entities from a config-declared build root are in the set the gate sees", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["cedar"], lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    // cedar's buildRoots hook contributes the project's schema as an entity
+    // (lexicons/cedar/src/schema-artifact.ts). Without `buildRoots` the gate
+    // never saw it, so a policy over it could not fail.
+    await writeFile(join(testDir, "schema.cedarschema"), `entity User;\n`);
+
+    const cli = await runChantBuild(testDir);
+    const gate = await runPolicyGate(testDir);
+
+    expect([...gate.result.entities.keys()].sort()).toEqual([...cli.result.entities.keys()].sort());
+    expect([...gate.result.entities.keys()]).toContain("cedarSchema");
+    expect([...gate.result.outputs.entries()]).toEqual([...cli.result.outputs.entries()]);
+  });
+
+  test("a foldable source module does not execute during the gate's build", async () => {
+    delete process.env.CHANT_2002_SOURCE_RAN;
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    await writeFile(
+      join(testDir, "ns.ts"),
+      // Module-level: runs if and only if the file is imported. Fold reads the
+      // constructor call statically and never imports the module.
+      `process.env.CHANT_2002_SOURCE_RAN = "1";\n` +
+        `import { Namespace } from "@intentius/chant-lexicon-k8s";\n` +
+        `export const ns = new Namespace({ metadata: { name: "demo" } });\n`,
+    );
+
+    const gate = await runPolicyGate(testDir);
+
+    expect(gate.options.fold).toBe(true);
+    expect(gate.result.foldDecisions.find((d) => d.file.endsWith("ns.ts"))?.mode).toBe("fold");
+    expect(process.env.CHANT_2002_SOURCE_RAN).toBeUndefined();
+  });
+
+  test("build.fold: false is honoured too — the config decides, not the gate", async () => {
+    delete process.env.CHANT_2002_SOURCE_RAN;
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], build: { fold: false }, lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    // No lexicon import: with fold off every discovered file is imported, and
+    // this fixture lives outside the repo where a bare `@intentius/*`
+    // specifier does not resolve. The marker is all this test needs.
+    await writeFile(join(testDir, "marker.ts"), `process.env.CHANT_2002_SOURCE_RAN = "1";\nexport const value = 1;\n`);
+
+    const gate = await runPolicyGate(testDir);
+
+    expect(gate.options.fold).toBe(false);
+    expect(process.env.CHANT_2002_SOURCE_RAN).toBe("1");
+    delete process.env.CHANT_2002_SOURCE_RAN;
+  });
+
+  test("build.sandbox: true is reported as a divergence rather than silently ignored", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], build: { sandbox: true }, lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+    const stderr: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderr.push(s); });
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.warnings).toHaveLength(1);
+    expect(evaluation.warnings[0]).toContain("build.sandbox is enabled");
+    expect(stderr.join("\n")).toContain("build.sandbox is enabled");
+  });
+
+  test("no sandbox opt-in, no warning", async () => {
+    await writeFile(
+      join(testDir, "chant.config.ts"),
+      `export default { lexicons: ["k8s"], lint: { policies: ["policies/org.ts"] } };\n`,
+    );
+
+    const evaluation = await evaluateProjectPolicies({ path: testDir });
+
+    expect(evaluation.warnings).toEqual([]);
+  });
+});