@intentius/chant 0.80.0 → 0.81.0

package/src/discovery/sandbox/fork-diagnostic.test.ts

@@ -1,9 +1,12 @@
-import { describe, test, expect } from "vitest";
-import { fork } from "node:child_process";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { describe, test, expect, vi } from "vitest";
+import { fork, type ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runFallbackFilesSandboxed } from "./run";
+import { forkSandboxed, settleOnExitAfterChannelDrains } from "./fork";
+import { generateConfigDriverSource, generateDriverSource, generatePolicyDriverSource, sendFunctionSource } from "./driver";
 
 /**
  * chant#2461 — a child that ends without a usable result says which way it did.
@@ -22,13 +25,13 @@ import { runFallbackFilesSandboxed } from "./run";
  *   - a payload the parent's `isResponse` refuses, which used to be dropped in
  *     silence and then reported as though nothing had been sent
  *
- * A third mechanism was proposed in the issue and is NOT covered, because it
- * was measured and does not happen: `process.send` racing the child's reap so
- * that `exit` is dispatched before an already-queued `message`. With the parent
- * blocked so both were certainly pending, `message` won 60 times out of 60. The
- * live IPC channel keeps the child alive until the payload flushes, and the
- * driver has no `process.exit()` to cut that short. The last test here records
- * that, so the disproof is not lost with the transcript.
+ * A third mechanism, the one the issue first proposed, was ruled out early on
+ * a test that blocked the parent (`message` won 60 of 60) and turned out to be
+ * the real one: under concurrent load the parent can handle a child's `exit`
+ * before the `message` it had already written. A stress run of the real
+ * `evaluateConfigSandboxed` lost 3 of 800 that way. The parent now waits for
+ * the IPC channel to drain before it reads an exit, and the drivers await
+ * their `process.send` callback; both are pinned below.
  */
 function runChild(source: string): Promise<{ code: number | null; message: unknown; stderr: string }> {
   const dir = mkdtempSync(join(tmpdir(), "chant-fork-diag-"));
@@ -62,9 +65,9 @@ describe("why a sandboxed child ends without a result (chant#2461)", () => {
     expect(r.stderr.trim()).toBe("");
   });
 
-  test("a child that sends and falls off the end always gets its message through", async () => {
-    // The disproof, kept as a test. If this ever fails, the race the issue
-    // proposed is real after all and the diagnostic's wording needs revisiting.
+  test("a child that sends and falls off the end gets its message through", async () => {
+    // Usually true even on a bare `exit` handler; the drain wait is what makes
+    // it true every time. See the settleOnExitAfterChannelDrains tests below.
     const results = await Promise.all(
       Array.from({ length: 12 }, () => runChild("process.send({ ok: true });\n")),
     );
@@ -123,3 +126,123 @@ describe("why a sandboxed child ends without a result (chant#2461)", () => {
     }
   }, 120_000);
 });
+
+/** A stand-in for a ChildProcess: just the events and the `connected` flag the helper reads. */
+function fakeChild(connected: boolean): ChildProcess & EventEmitter {
+  const child = new EventEmitter() as ChildProcess & EventEmitter;
+  (child as { connected: boolean }).connected = connected;
+  return child;
+}
+
+describe("settleOnExitAfterChannelDrains (chant#2461)", () => {
+  test("an exit handled before the last message waits for the channel, so the message wins", () => {
+    // The observed ordering: exit first, the already-written message after,
+    // then the channel's EOF. Settling on exit alone dropped the message.
+    const child = fakeChild(true);
+    const order: string[] = [];
+    child.on("message", () => order.push("message"));
+    settleOnExitAfterChannelDrains(child, (code) => order.push(`exit:${code}`));
+
+    child.emit("exit", 0, null);
+    child.emit("message", { ok: true });
+    expect(order).toEqual(["message"]);
+
+    child.emit("disconnect");
+    expect(order).toEqual(["message", "exit:0"]);
+  });
+
+  test("a channel that has already closed settles on exit straight away", () => {
+    const child = fakeChild(false);
+    const onExit = vi.fn();
+    settleOnExitAfterChannelDrains(child, onExit);
+    child.emit("exit", 3, null);
+    expect(onExit).toHaveBeenCalledWith(3, null);
+  });
+
+  test("a channel that never reports closed is bounded by the grace period", () => {
+    vi.useFakeTimers();
+    try {
+      const child = fakeChild(true);
+      const onExit = vi.fn();
+      settleOnExitAfterChannelDrains(child, onExit, 50);
+      child.emit("exit", 0, null);
+      vi.advanceTimersByTime(49);
+      expect(onExit).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(1);
+      expect(onExit).toHaveBeenCalledTimes(1);
+      child.emit("disconnect");
+      expect(onExit).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  test("real sandboxed children that send and return all resolve, many at once", async () => {
+    // The shape of the stress harness, small enough for CI: a --permission
+    // child that sends and returns, through forkSandboxed's settle logic.
+    const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-2461-many-")));
+    try {
+      const file = join(dir, "child.mjs");
+      writeFileSync(file, 'process.send({ kind: "chant-config", ok: true, config: { pad: "x".repeat(65536) } });\n');
+      const isResponse = (v: unknown): v is { kind: string } =>
+        typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "chant-config";
+      const results = await Promise.all(
+        Array.from({ length: 32 }, () =>
+          forkSandboxed(
+            { bundlePath: file, bundleDir: dir, projectRealpath: dir, externalReadPaths: [], env: { PATH: process.env.PATH ?? "" }, timeoutMs: 60_000, label: "many", outputPrefix: "[t]" },
+            isResponse,
+          ),
+        ),
+      );
+      expect(results.every((r) => r.kind === "chant-config")).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  }, 120_000);
+});
+
+describe("driver send awaits delivery and fails loudly (chant#2461)", () => {
+  const harness = (body: string): string =>
+    ['import { writeSync } from "node:fs";', ...sendFunctionSource(), body].join("\n");
+
+  test("a send that succeeds resolves, and the code after it runs", async () => {
+    const r = await runChild(harness('await send({ ok: 1 }); writeSync(2, "after\\n");'));
+    expect(r.code).toBe(0);
+    expect(r.message).toEqual({ ok: 1 });
+    expect(r.stderr).toBe("after\n");
+  });
+
+  test("a send on a closed channel exits non-zero with the reason on stderr", async () => {
+    const r = await runChild(harness('process.disconnect(); await send({ ok: 1 }); writeSync(2, "unreachable\\n");'));
+    expect(r.code).toBe(1);
+    expect(r.message).toBeUndefined();
+    expect(r.stderr).toContain("could not hand its result to the parent");
+    expect(r.stderr).toContain("chant#2461");
+    expect(r.stderr).not.toContain("unreachable");
+  });
+
+  test("a payload that cannot be serialized exits non-zero with the reason on stderr", async () => {
+    const r = await runChild(harness("await send({ big: 1n });"));
+    expect(r.code).toBe(1);
+    expect(r.message).toBeUndefined();
+    expect(r.stderr).toContain("could not hand its result to the parent");
+  });
+
+  test("every driver awaits or returns every send", () => {
+    // A bare `send(...)` statement would let main() return before the write
+    // completes. The only unawaited call allowed is main().catch's, whose
+    // promise is the last thing the module does.
+    const sources = {
+      config: generateConfigDriverSource("/tmp/project/chant.config.ts"),
+      run: generateDriverSource({ files: ["/tmp/project/a.ts"], buildRoot: "/tmp/project" }),
+      policy: generatePolicyDriverSource(["/tmp/project/policy.ts"]),
+    };
+    for (const [name, source] of Object.entries(sources)) {
+      const bare = source
+        .split("\n")
+        .filter((line) => /^\s*(send|fail)\(/.test(line))
+        .filter((line) => !/^\s*send\(\{[^\n]*fatal: true|^\s*send\(\{ kind: "chant-config", ok: false, error: classifyChildError\([^)]*, err\)\.toJSON\(\) \}\),$/.test(line));
+      expect({ name, bare }).toEqual({ name, bare: [] });
+    }
+  });
+});

package/src/discovery/sandbox/fork.ts

@@ -1,4 +1,4 @@
-import { fork } from "node:child_process";
+import { fork, type ChildProcess } from "node:child_process";
 
 /**
  * The one place chant starts a sandboxed child process.
@@ -131,38 +131,33 @@ function lineBuffered(emit: (line: string) => void) {
  * chant#2461 — this used to be one sentence, `child exited before reporting
  * results (code N, signal S)`, for three unrelated situations. The one that
  * was observed in the wild is the hardest to read: exit code 0, empty stderr,
- * no message. That reads like the child was cut off, and it was not — it ran
- * to completion and sent nothing.
+ * no message. That reads like the child was cut off, and it was not: it ran
+ * to completion.
  *
- * Two mechanisms produce it, and the driver decides which is possible.
+ * The observed case turned out to be the parent's fault. A config child that
+ * sent its result and exited could have its `exit` dispatched here BEFORE its
+ * already-written `message`, and the old `exit` handler settled on the spot.
+ * The payload arrived a moment later and was ignored. Stress runs of the real
+ * `evaluateConfigSandboxed`, 24 at a time under 16 CPU hogs, lost 3 of 800 and
+ * 13 of 1500 that way. An earlier test that blocked the parent had seen
+ * `message` win 60 of 60, which is why this was ruled out for a while.
+ * {@link settleOnExitAfterChannelDrains} closes it by not reading the exit
+ * until the IPC channel has drained. Every driver also awaits its
+ * `process.send` callback and exits 1 with a stderr line if the send fails
+ * (see `./driver.ts`'s `sendFunctionSource`), so a result that never left the
+ * child cannot look like exit 0 either.
  *
- * The first is an `await` that never settles. `main().catch(...)` catches a
- * REJECTION, and a promise that never settles is not one, so if nothing keeps
- * the loop alive Node drains it and exits 0 having sent nothing and written
- * nothing. Nothing else in the process reports that.
- *
- * On the RUN path that is not hypothetical, and it is reproducible: the driver
- * does `await import(<project file>)` for each run-fallback file, module scope
- * is arbitrary project source, and a file whose top level awaits something that
- * never settles makes that import never complete. A fixture doing exactly that
- * yields this error, which is how the wording here was checked rather than
- * guessed.
- *
- * The second is the payload being lost between `process.send` and exit.
- *
- * For the CONFIG driver the first is impossible, which is worth stating because
- * it was the working hypothesis until the bundle was read. Its `await
- * import(configPath)` bundles to `await Promise.resolve().then(() =>
- * (init_chant_config(), chant_config_exports))` — one microtask over
- * synchronous code — and the bundle has no runtime imports, no dynamic
- * `import(`, and exactly one `process.send`. There is nothing there to hang on.
- * So a config child that exits 0 with nothing sent DID send, and the payload
- * did not arrive.
- *
- * The exit/message race originally proposed in chant#2461 is a third thing and
- * is not it: with the parent blocked so a queued payload and the reap were both
- * pending, `message` was dispatched first 60 times out of 60, because the live
- * IPC channel keeps the child alive until the payload flushes.
+ * With both of those in place, exit 0 with nothing on stderr and nothing
+ * received has one known cause left: an `await` that never settles.
+ * `main().catch(...)` catches a REJECTION, and a promise that never settles is
+ * not one, so if nothing keeps the loop alive Node drains it and exits 0
+ * having sent nothing. On the RUN path that is reproducible: the driver does
+ * `await import(<project file>)` per run-fallback file, module scope is
+ * arbitrary project source, and a file whose top level never settles makes
+ * that import never complete (the run driver names the file on stderr in that
+ * case). The CONFIG driver bundles to one microtask over synchronous code with
+ * no runtime imports, so on that path the cause is not known, and the message
+ * says so rather than guessing.
  */
 function describeSilentExit(
   label: string,
@@ -190,21 +185,64 @@ function describeSilentExit(
   if (stderr) return `${head}: ${stderr}`;
   if (code !== 0 || signal !== null) return head;
 
-  // Exit 0, nothing on stderr, nothing sent. The child finished normally and
-  // the parent has nothing. Two mechanisms produce exactly this, and which one
-  // it is depends on the driver — see this function's doc.
+  // Exit 0, nothing on stderr, and nothing received even after the IPC
+  // channel drained. See this function's doc for what is and is not left.
   return (
-    `${head}. It exited cleanly with nothing on stderr and sent no message, so the child drained ` +
-    `its loop without sending: something it awaited never settled. On the run path the usual ` +
-    `cause is a project file with a top-level \`await\` that does not settle — module scope is ` +
-    `arbitrary project source, and an import of such a file never completes. A promise that ` +
-    `never settles is not a rejection, so the driver's own \`main().catch\` does not see it ` +
-    `either, which is why nothing is written anywhere. The config driver bundles to one ` +
-    `microtask over synchronous code with no runtime I/O, so on THAT path nothing can hang and ` +
-    `the payload was lost between \`process.send\` and exit instead (chant#2461).`
+    `${head}. It exited cleanly with nothing on stderr, and no message arrived even after its ` +
+    `IPC channel closed, so it never sent one: something it awaited never settled. On the run ` +
+    `path the usual cause is a project file with a top-level \`await\` that does not settle. ` +
+    `Module scope is arbitrary project source, an import of such a file never completes, and a ` +
+    `promise that never settles is not a rejection, so the driver's own \`main().catch\` does ` +
+    `not see it either. The config driver has nothing to await that can hang, and a failed ` +
+    `send exits non-zero with a reason on stderr, so on the config path this has no known ` +
+    `cause: please report it with the command that produced it (chant#2461).`
   );
 }
 
+/** How long {@link settleOnExitAfterChannelDrains} waits, after exit, for the IPC channel to report closed. Normally it takes well under a millisecond; this only bounds a channel that never does. */
+const EXIT_DRAIN_GRACE_MS = 2_000;
+
+/**
+ * chant#2461 — call `onExit` once `child` has exited AND its IPC channel has
+ * drained, so a message the child wrote before exiting is always dispatched
+ * first.
+ *
+ * Node does not order `exit` after `message`. The child's exit and the last
+ * bytes on the IPC socket reach the parent's event loop as separate events,
+ * and under load the exit can be handled first even though the child wrote
+ * the message before it exited. Settling on `exit` alone then drops a payload
+ * that is already sitting in the socket. The channel reports `disconnect`
+ * only after it has read EOF, which comes after every message the child
+ * wrote, so waiting for it is exact.
+ *
+ * This is deliberately not `close`. `close` also waits for stdout and stderr
+ * to end, and a grandchild holding those pipes would turn a fast failure into
+ * the full timeout. The wait here is on the IPC channel alone, and is bounded
+ * by `graceMs` in case that channel never reports closed.
+ */
+export function settleOnExitAfterChannelDrains(
+  child: ChildProcess,
+  onExit: (code: number | null, signal: NodeJS.Signals | null) => void,
+  graceMs = EXIT_DRAIN_GRACE_MS,
+): void {
+  child.on("exit", (code, signal) => {
+    let done = false;
+    let grace: NodeJS.Timeout | undefined;
+    const finish = (): void => {
+      if (done) return;
+      done = true;
+      if (grace !== undefined) clearTimeout(grace);
+      onExit(code, signal);
+    };
+    if (!child.connected) {
+      finish();
+      return;
+    }
+    child.once("disconnect", finish);
+    grace = setTimeout(finish, graceMs);
+  });
+}
+
 export function forkSandboxed<T>(
   options: SandboxForkOptions,
   isResponse: (value: unknown) => value is T,
@@ -298,7 +336,9 @@ export function forkSandboxed<T>(
       reject(err);
     });
 
-    child.on("exit", (code, signal) => {
+    // chant#2461 — not `child.on("exit")`: a payload can still be in the IPC
+    // socket when the exit is handled. See settleOnExitAfterChannelDrains.
+    settleOnExitAfterChannelDrains(child, (code, signal) => {
       if (settled) return;
       settled = true;
       clearTimeout(timeout);

package/src/discovery/sandbox/path-lexicon-multifile.test.ts

@@ -0,0 +1,285 @@
+/**
+ * chant#2590 — every file of a multi-file lexicon declared by path gets the
+ * fold trust a subpath of the same lexicon installed as a package gets, with
+ * and without `--sandbox`.
+ *
+ * The lexicon is three files: `resources.ts`, `composites.ts` (which imports
+ * `./resources`) and `index.ts` (which re-exports both and holds the plugin).
+ * It is written once as the package `@intentius/chant-lexicon-demo` and once
+ * as `./lexicon/` named by path. One project file imports the lexicon's entry
+ * and one imports a constructor from its `resources` file directly, by
+ * package subpath or by path. Outputs and fold verdicts are compared.
+ *
+ * The rest of the file covers the bounds of the trusted directory.
+ */
+import { describe, test, expect, beforeAll, afterAll, afterEach } from "vitest";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { build } from "../../build";
+import { loadChantConfig } from "../../config";
+import { lexiconModuleRoot, pathLexiconRoot, resetLexiconModules } from "../../lexicon-module";
+import { createFoldSession } from "../fold-import";
+import type { LexiconPlugin } from "../../lexicon";
+
+const runtimePath = resolve(import.meta.dirname, "../../runtime");
+const compositePath = resolve(import.meta.dirname, "../../composite");
+
+const RESOURCES = `
+import { createResource } from ${JSON.stringify(runtimePath)};
+
+export const Bucket = createResource("Demo::Bucket", "demo", { arn: "Arn" });
+export const Role = createResource("Demo::Role", "demo", {});
+`;
+
+const COMPOSITES = `
+import { Composite } from ${JSON.stringify(compositePath)};
+import { Bucket, Role } from "./resources";
+
+export const WebApp = Composite((props) => {
+  const bucket = new Bucket({ bucketName: props.name });
+  const role = new Role({ resource: bucket.arn });
+  return { bucket, role };
+}, "WebApp");
+`;
+
+const INDEX = `
+export * from "./resources";
+export * from "./composites";
+
+export const Regions = { primary: "us-east-1" };
+
+function plain(value) {
+  if (value && typeof value === "object" && typeof value.getLogicalName === "function") {
+    return { ref: value.getLogicalName(), attr: value.attribute };
+  }
+  if (Array.isArray(value)) return value.map(plain);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plain(v)]));
+  }
+  return value;
+}
+
+export const demoPlugin = {
+  name: "demo",
+  serializer: {
+    name: "demo",
+    rulePrefix: "DEMO",
+    serialize: (entities) =>
+      JSON.stringify(
+        Object.fromEntries(
+          [...entities.keys()].sort().map((name) => {
+            const entity = entities.get(name);
+            return [name, { type: entity.entityType, props: plain(entity.props) }];
+          }),
+        ),
+      ),
+  },
+  generate: async () => {},
+  validate: async () => {},
+  coverage: async () => {},
+  package: async () => {},
+};
+`;
+
+function mainSource(entry: string): string {
+  return `
+import { Bucket, Regions, WebApp } from ${JSON.stringify(entry)};
+
+export const logs = new Bucket({ bucketName: Regions.primary });
+export const web = WebApp({ name: "data" });
+`;
+}
+
+function rolesSource(resources: string): string {
+  return `
+import { Role } from ${JSON.stringify(resources)};
+
+export const deployer = new Role({ resource: "deploy" });
+`;
+}
+
+async function writeLexicon(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "resources.ts"), RESOURCES);
+  await writeFile(join(dir, "composites.ts"), COMPOSITES);
+  await writeFile(join(dir, "index.ts"), INDEX);
+}
+
+let root: string;
+
+beforeAll(async () => {
+  root = await realpath(await mkdtemp(join(tmpdir(), "chant-2590-")));
+
+  const pkg = join(root, "pkg");
+  const pkgDir = join(pkg, "node_modules", "@intentius", "chant-lexicon-demo");
+  await writeLexicon(pkgDir);
+  await writeFile(
+    join(pkgDir, "package.json"),
+    JSON.stringify({
+      name: "@intentius/chant-lexicon-demo",
+      type: "module",
+      exports: { ".": "./index.ts", "./resources": "./resources.ts" },
+    }),
+  );
+  await mkdir(join(pkg, "src"));
+  await writeFile(join(pkg, "src", "main.ts"), mainSource("@intentius/chant-lexicon-demo"));
+  await writeFile(join(pkg, "src", "roles.ts"), rolesSource("@intentius/chant-lexicon-demo/resources"));
+  await writeFile(join(pkg, "chant.config.ts"), `export default { lexicons: ["demo"] };\n`);
+
+  const path = join(root, "path");
+  await writeLexicon(join(path, "lexicon"));
+  await mkdir(join(path, "src"));
+  await writeFile(join(path, "src", "main.ts"), mainSource("../lexicon"));
+  await writeFile(join(path, "src", "roles.ts"), rolesSource("../lexicon/resources"));
+  await writeFile(
+    join(path, "chant.config.ts"),
+    `export default { lexicons: [{ name: "demo", module: "./lexicon/index.ts" }] };\n`,
+  );
+
+  // The same lexicon with its module at the project root: only the module
+  // file is trusted, so its sibling stays a project file.
+  const flat = join(root, "flat");
+  await mkdir(join(flat, "src"), { recursive: true });
+  await writeFile(join(flat, "resources.ts"), RESOURCES);
+  await writeFile(join(flat, "composites.ts"), COMPOSITES);
+  await writeFile(join(flat, "demo.ts"), INDEX);
+  await writeFile(join(flat, "src", "roles.ts"), rolesSource("../resources"));
+  await writeFile(join(flat, "chant.config.ts"), `export default { lexicons: [{ name: "demo", module: "./demo.ts" }] };\n`);
+});
+
+afterAll(async () => {
+  await rm(root, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  resetLexiconModules();
+});
+
+async function buildProject(project: "pkg" | "path" | "flat", modes: { fold: boolean; sandbox: boolean }) {
+  const dir = join(root, project);
+  const lexiconFile = {
+    pkg: join(dir, "node_modules", "@intentius", "chant-lexicon-demo", "index.ts"),
+    path: join(dir, "lexicon", "index.ts"),
+    flat: join(dir, "demo.ts"),
+  }[project];
+  await loadChantConfig(dir);
+  const plugin = (await import(lexiconFile)).demoPlugin as LexiconPlugin;
+  const result = await build(join(dir, "src"), [plugin.serializer], undefined, {
+    ...modes,
+    lexicons: [plugin.name],
+  });
+  return {
+    errors: result.errors,
+    output: result.outputs.get("demo") as string,
+    decisions: result.foldDecisions
+      .map((d) => ({ file: d.file.slice(dir.length), mode: d.mode, reason: d.reason }))
+      .sort((a, b) => a.file.localeCompare(b.file)),
+  };
+}
+
+describe("a multi-file lexicon declared by path folds like the same lexicon installed as a package (chant#2590)", () => {
+  for (const modes of [
+    { fold: true, sandbox: true },
+    { fold: true, sandbox: false },
+  ]) {
+    test(
+      `--fold${modes.sandbox ? " --sandbox" : ""}: same output, same fold verdicts`,
+      async () => {
+        const asPackage = await buildProject("pkg", modes);
+        const byPath = await buildProject("path", modes);
+
+        expect(asPackage.errors).toEqual([]);
+        expect(byPath.errors).toEqual([]);
+        expect(byPath.output).toBe(asPackage.output);
+        expect(JSON.parse(byPath.output)).toEqual({
+          deployer: { type: "Demo::Role", props: { resource: "deploy" } },
+          logs: { type: "Demo::Bucket", props: { bucketName: "us-east-1" } },
+          webBucket: { type: "Demo::Bucket", props: { bucketName: "data" } },
+          webRole: { type: "Demo::Role", props: { resource: { ref: "webBucket", attr: "Arn" } } },
+        });
+        expect(byPath.decisions).toEqual(asPackage.decisions);
+        expect(byPath.decisions).toEqual([
+          { file: "/src/main.ts", mode: "fold", reason: undefined },
+          { file: "/src/roles.ts", mode: "fold", reason: undefined },
+        ]);
+      },
+      60_000,
+    );
+  }
+
+  test("a module at the project root trusts only itself: under --sandbox its sibling runs in the child", async () => {
+    const flat = await buildProject("flat", { fold: true, sandbox: true });
+    expect(flat.errors).toEqual([]);
+    expect(JSON.parse(flat.output)).toEqual({ deployer: { type: "Demo::Role", props: { resource: "deploy" } } });
+    expect(flat.decisions).toHaveLength(1);
+    expect(flat.decisions[0]).toMatchObject({ file: "/src/roles.ts", mode: "run" });
+    expect(flat.decisions[0].reason).toContain("neither chant's own nor an active lexicon");
+  }, 60_000);
+});
+
+describe("the trusted directory's bounds (chant#2590)", () => {
+  const project = "/p";
+
+  test("defaults to the module's own directory", () => {
+    expect(pathLexiconRoot({ module: "./lexicon/index.ts" }, project)).toEqual({ root: "/p/lexicon" });
+  });
+
+  test("a module at the project root gets no directory", () => {
+    expect(pathLexiconRoot({ module: "./demo.ts" }, project)).toEqual({});
+  });
+
+  test("a module outside the project gets no directory", () => {
+    expect(pathLexiconRoot({ module: "/elsewhere/demo.ts" }, project)).toEqual({});
+  });
+
+  test("the module's directory is dropped when it contains the source directory", () => {
+    expect(pathLexiconRoot({ module: "./infra/lexicon.ts" }, project, "infra/src")).toEqual({});
+    expect(pathLexiconRoot({ module: "./infra/lexicon.ts" }, project, "infra")).toEqual({});
+  });
+
+  test("a declared root is used when it holds the module", () => {
+    expect(pathLexiconRoot({ module: "./lexicon/src/index.ts", root: "./lexicon" }, project)).toEqual({
+      root: "/p/lexicon",
+    });
+  });
+
+  test("a declared root outside the project, over the source, or not holding the module is a problem", () => {
+    expect(pathLexiconRoot({ module: "./lexicon/index.ts", root: ".." }, project).problem).toContain("outside the project");
+    expect(pathLexiconRoot({ module: "./lexicon/index.ts", root: "." }, project).problem).toContain(
+      "contains the project's source directory",
+    );
+    expect(pathLexiconRoot({ module: "./lexicon/index.ts", root: "./other" }, project).problem).toContain(
+      "is not inside",
+    );
+  });
+
+  test("the config loader refuses a declared root that breaks a rule", async () => {
+    const dir = join(root, "bad-root");
+    await mkdir(join(dir, "lexicon"), { recursive: true });
+    await writeFile(
+      join(dir, "chant.config.json"),
+      JSON.stringify({ lexicons: [{ name: "demo", module: "./lexicon/index.ts", root: "." }] }),
+    );
+    await expect(loadChantConfig(dir)).rejects.toThrow(/lexicons\.0\.root: .*contains the project's source directory/);
+  });
+
+  test("the config loader records a declared root", async () => {
+    const dir = join(root, "good-root");
+    await mkdir(join(dir, "lexicon", "src"), { recursive: true });
+    await writeFile(
+      join(dir, "chant.config.json"),
+      JSON.stringify({ lexicons: [{ name: "demo", module: "./lexicon/src/index.ts", root: "./lexicon" }] }),
+    );
+    await loadChantConfig(dir);
+    expect(lexiconModuleRoot("demo")).toBe(join(dir, "lexicon"));
+  });
+
+  test("a fold session drops a directory holding any of the build's own source files", async () => {
+    const dir = join(root, "path");
+    await loadChantConfig(dir);
+    expect(createFoldSession([], undefined, ["demo"]).lexiconRoots).toEqual([join(dir, "lexicon")]);
+    const session = createFoldSession([], undefined, ["demo"], true, [], false, [join(dir, "lexicon", "extra.ts")]);
+    expect(session.lexiconRoots).toEqual([]);
+  });
+});