@intentius/chant 0.79.0 → 0.81.0

package/src/discovery/files.ts

@@ -1,6 +1,9 @@
-import { readdir, stat, open } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join, relative } from "node:path";
+import { open } from "node:fs/promises";
+import { relative, sep, isAbsolute } from "node:path";
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
+import { resolveDiscoveryGlobs, type DiscoveryGlobs } from "../config";
+import { readHead, walkDiscovery, workspaceMemberDirs } from "./walk";
 
 /**
  * Marker chant writes at the top of files it generates (a hosting lexicon's
@@ -12,13 +15,38 @@ import { join, relative } from "node:path";
  */
 export const GENERATED_MARKER = "Generated by chant — do not edit directly";
 
-/** True when a file's header carries the {@link GENERATED_MARKER}. Reads only the head. */
-async function isGeneratedFile(file: string): Promise<boolean> {
+/**
+ * Comment a hand-written file carries to keep discovery out of it (#2519): a
+ * runnable script with top-level side effects, say, that lives next to the
+ * project's declarations. It must be a comment of its own (`// chant-discovery-skip`
+ * or inside a block comment) within the first {@link SKIP_MARKER_HEAD_BYTES}
+ * bytes of the file. See {@link hasSkipMarker}.
+ */
+export const SKIP_MARKER = "chant-discovery-skip";
+
+/** How much of a file's head {@link hasSkipMarker} reads: room for a shebang and a license header. */
+const SKIP_MARKER_HEAD_BYTES = 1024;
+
+/** {@link SKIP_MARKER} opening a `//`, `/*` or ` * ` comment line, as a whole word. */
+const SKIP_MARKER_PATTERN = /^[ \t]*(?:\/\/|\/\*+|\*)[ \t]*chant-discovery-skip(?![\w-])/m;
+
+/** True when `head`, the start of a file, carries the {@link SKIP_MARKER} comment. */
+export function hasSkipMarker(head: string): boolean {
+  return SKIP_MARKER_PATTERN.test(head.slice(0, SKIP_MARKER_HEAD_BYTES));
+}
+
+/**
+ * Whether a file's head carries the {@link GENERATED_MARKER} or the
+ * {@link SKIP_MARKER}. Reads only the head. The generated marker is looked for
+ * in the first 256 bytes, as it always was.
+ */
+export async function hasDiscoveryMarker(file: string): Promise<boolean> {
   let fh;
   try {
     fh = await open(file, "r");
-    const { buffer, bytesRead } = await fh.read({ buffer: Buffer.alloc(256), position: 0 });
-    return buffer.toString("utf8", 0, bytesRead).includes(GENERATED_MARKER);
+    const { buffer, bytesRead } = await fh.read({ buffer: Buffer.alloc(SKIP_MARKER_HEAD_BYTES), position: 0 });
+    if (buffer.toString("utf8", 0, Math.min(bytesRead, 256)).includes(GENERATED_MARKER)) return true;
+    return hasSkipMarker(buffer.toString("utf8", 0, bytesRead));
   } catch {
     return false;
   } finally {
@@ -26,61 +54,65 @@ async function isGeneratedFile(file: string): Promise<boolean> {
   }
 }
 
+/** Whether a file's head carries the {@link GENERATED_MARKER} or the {@link SKIP_MARKER}. The synchronous form of {@link hasDiscoveryMarker}. */
+export function hasDiscoveryMarkerSync(file: string): boolean {
+  const head = readHead(file, SKIP_MARKER_HEAD_BYTES);
+  return head.slice(0, 256).includes(GENERATED_MARKER) || hasSkipMarker(head);
+}
+
 /**
- * Recursively find all TypeScript infrastructure files in a directory
- * @param path - The directory path to search
- * @returns Array of file paths to .ts files (excluding test files and chant-generated files)
+ * Compile a project's `exclude`/`include` globs (#2519) into a predicate that
+ * is true for a file discovery must skip, or `undefined` when there is nothing
+ * to skip.
+ *
+ * Each pattern is matched, with picomatch and dot files included, against the
+ * file's path relative to `globs.root` (forward slashes) and against the path
+ * of every directory above it, so a pattern naming a directory covers
+ * everything under it. A file is skipped when some `exclude` pattern matches
+ * and no `include` pattern does: `include` always wins. Files outside
+ * `globs.root` are never skipped. The discovery walk (`./walk.ts`) applies the
+ * same rule, and also lets `include` re-admit what its default rules skip.
  */
-export async function findInfraFiles(path: string): Promise<string[]> {
-  const files: string[] = [];
-  let sourceRoot: string | null = null;
-
-  async function scanDirectory(dir: string): Promise<void> {
-    let entries;
-
-    try {
-      entries = await readdir(dir, { withFileTypes: true });
-    } catch (error) {
-      // Skip directories we can't read
-      return;
-    }
-
-    for (const entry of entries) {
-      const fullPath = join(dir, entry.name);
+export function compileDiscoveryFilter(globs: DiscoveryGlobs | undefined): ((file: string) => boolean) | undefined {
+  if (!globs || globs.exclude.length === 0) return undefined;
+  const excluded = picomatch(globs.exclude, { dot: true });
+  const included = globs.include.length > 0 ? picomatch(globs.include, { dot: true }) : () => false;
+  return (file: string): boolean => {
+    const rel = relative(globs.root, file);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return false;
+    const parts = rel.split(sep);
+    const candidates = parts.map((_, i) => parts.slice(0, i + 1).join("/"));
+    return candidates.some((c) => excluded(c)) && !candidates.some((c) => included(c));
+  };
+}
 
-      // Skip node_modules
-      if (entry.isDirectory() && entry.name === "node_modules") {
-        continue;
-      }
+/** Options for {@link findInfraFiles}. */
+export interface FindInfraFilesOptions {
+  /**
+   * The project's discovery globs. Omitted, they are read from the project
+   * config `path` belongs to ({@link resolveDiscoveryGlobs}); `null` applies none.
+   */
+  globs?: DiscoveryGlobs | null;
+}
 
-      if (entry.isDirectory()) {
-        // Child project boundary — a directory with its own chant.config.ts
-        // is a separate scope, but only if we've already found the project's
-        // own source root. The first config directory is the source root, not
-        // a child project.
-        const configPath = join(fullPath, "chant.config.ts");
-        if (existsSync(configPath)) {
-          if (sourceRoot === null) {
-            sourceRoot = fullPath;
-          } else {
-            continue;
-          }
-        }
-        await scanDirectory(fullPath);
-      } else if (entry.isFile()) {
-        // Include only .ts files, exclude test files and chant-generated files
-        if (
-          entry.name.endsWith(".ts") &&
-          !entry.name.endsWith(".test.ts") &&
-          !entry.name.endsWith(".spec.ts") &&
-          !(await isGeneratedFile(fullPath))
-        ) {
-          files.push(fullPath);
-        }
-      }
-    }
-  }
+/** A TypeScript source file by name: `.ts`, not a test or spec. */
+export function isSourceFileName(name: string): boolean {
+  return name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".spec.ts");
+}
 
-  await scanDirectory(path);
-  return files;
+/**
+ * Find every TypeScript infrastructure file under `path`, through the one
+ * discovery walk (`./walk.ts`, #2527): test and spec files, chant-generated
+ * files, skip-marked files and whatever the walk's rules and the project's
+ * globs skip are left out.
+ */
+export async function findInfraFiles(path: string, options?: FindInfraFilesOptions): Promise<string[]> {
+  const globs = options?.globs === null ? undefined : (options?.globs ?? (await resolveDiscoveryGlobs(path)));
+  return walkDiscovery({
+    walker: "source",
+    root: path,
+    globs,
+    excludeDirs: await workspaceMemberDirs(path),
+    accept: (name, full) => isSourceFileName(name) && !hasDiscoveryMarkerSync(full),
+  });
 }

package/src/discovery/fold-import.ts

@@ -27,6 +27,7 @@ import {
   type FoldedCompositeStepCall,
 } from "../fold/fold";
 import { isChantOwnedSpecifier, isFoldableHelperName } from "../fold/foldable-helpers";
+import { lexiconModulePath, lexiconModuleRoot } from "../lexicon-module";
 import {
   briefNodeText,
   callExpressionMessage,
@@ -247,6 +248,32 @@ export interface FoldSession {
    * established one.
    */
   readonly lexiconPackages: ReadonlySet<string>;
+  /**
+   * chant#2577 — the absolute module paths of this build's lexicons that
+   * `chant.config.ts` declares by path (#2520), each resolved to the file an
+   * import of it reaches. Such a lexicon has no package specifier, so a
+   * project imports it by a relative or absolute path. A binding whose path
+   * resolves to one of these is treated exactly like a binding of a
+   * {@link lexiconPackages} entry: its data exports resolve as values, and
+   * under `--sandbox` it is on {@link isTrustedExecutableBinding}'s allowlist,
+   * because `loadPlugins` has already imported and run it in this process.
+   *
+   * Only the declared module itself is in the set. The other files of a
+   * multi-file path lexicon are covered by {@link lexiconRoots}.
+   */
+  readonly lexiconModules: ReadonlySet<string>;
+  /**
+   * chant#2590 — the directory trusted for each path-declared lexicon that has
+   * one (`../lexicon-module.ts`'s `pathLexiconRoot`: the declared `root`, or
+   * the module's own directory, inside the project and not containing its
+   * source directory). A file under one of these gets what a subpath of an
+   * active lexicon package gets: a place on the `--sandbox` trust list, and
+   * no fold as a project file. Its data exports are not read as values,
+   * which is also how a package subpath is treated. A directory that holds
+   * any of the build's own source files is dropped, so the build's source is
+   * never trusted this way.
+   */
+  readonly lexiconRoots: readonly string[];
   /**
    * chant #1093 — this build asked for the #1045 sandbox
    * (`DiscoveryOptions.sandbox`, `chant build --sandbox`), so fold must not
@@ -326,7 +353,24 @@ export function createFoldSession(
   lexiconPackages: readonly string[] = [],
   /** chant#2455 — `ι = executing`. Mutually exclusive with `sandbox`. */
   executing = false,
+  /**
+   * chant#2590 — the build's own source files. A path lexicon's trusted
+   * directory that holds any of them is dropped (see {@link FoldSession.lexiconRoots}).
+   */
+  sourceFiles: readonly string[] = [],
 ): FoldSession {
+  // chant#2577 — a lexicon declared by path is that module and no package, so
+  // its name contributes the module path and not `@intentius/chant-lexicon-<name>`.
+  const packages = new Set(lexiconPackages);
+  const modules = new Set<string>();
+  const roots: string[] = [];
+  for (const name of lexicons) {
+    const modulePath = lexiconModulePath(name);
+    if (modulePath === undefined) packages.add(lexiconPackageName(name));
+    else modules.add(resolveModulePath(modulePath, modulePath));
+    const root = lexiconModuleRoot(name);
+    if (root !== undefined && !sourceFiles.some((file) => isUnderDirectory(resolvePath(file), root))) roots.push(root);
+  }
   return {
     intrinsics,
     cache: new Map(),
@@ -334,7 +378,9 @@ export function createFoldSession(
     importCache: new Map(),
     resolvePathCache: new Map(),
     buildParams,
-    lexiconPackages: new Set([...lexicons.map(lexiconPackageName), ...lexiconPackages]),
+    lexiconPackages: packages,
+    lexiconModules: modules,
+    lexiconRoots: roots,
     sandbox,
     executing,
     factoryModules: new Map(),
@@ -1104,6 +1150,39 @@ function activeLexiconPackage(specifier: string, lexiconPackages: ReadonlySet<st
   return lexiconPackages.has(specifier) ? specifier : undefined;
 }
 
+/**
+ * chant#2577 — the path-declared counterpart of {@link activeLexiconPackage}:
+ * the resolved module path when a relative or absolute `specifier` reaches
+ * one of this build's {@link FoldSession.lexiconModules}, `undefined`
+ * otherwise. A bare specifier is never resolved here, and a build with no
+ * path-declared lexicon resolves nothing.
+ */
+function activeLexiconModule(
+  specifier: string,
+  fromFile: string,
+  lexiconModules: ReadonlySet<string>,
+  resolvePathCache: Map<string, string>,
+): string | undefined {
+  if (lexiconModules.size === 0 || !isProjectFileSpecifier(specifier)) return undefined;
+  let modulePath: string;
+  try {
+    modulePath = resolveModulePathMemoized(specifier, fromFile, resolvePathCache);
+  } catch {
+    return undefined;
+  }
+  return lexiconModules.has(modulePath) ? modulePath : undefined;
+}
+
+/** chant#2590 — true when absolute `file` lies under absolute directory `dir`. */
+function isUnderDirectory(file: string, dir: string): boolean {
+  return file.startsWith(dir.endsWith(sep) ? dir : dir + sep);
+}
+
+/** chant#2590 — true when `path` lies under one of the build's trusted path-lexicon directories. */
+function inPathLexiconRoot(path: string, roots: readonly string[]): boolean {
+  return roots.some((root) => isUnderDirectory(path, root));
+}
+
 /**
  * chant #1995 — the package-ROOT portion of a bare subpath specifier
  * (`@intentius/chant-lexicon-azure/generated/index` ->
@@ -1168,13 +1247,17 @@ async function resolveActiveLexiconExport(
   fromFile: string,
   session: FoldSession,
 ): Promise<{ value: unknown } | undefined> {
-  if (!activeLexiconPackage(binding.specifier, session.lexiconPackages)) return undefined;
-
-  let modulePath: string;
-  try {
-    modulePath = resolveModulePathMemoized(binding.specifier, fromFile, session.resolvePathCache);
-  } catch {
-    return undefined;
+  let modulePath: string | undefined;
+  if (activeLexiconPackage(binding.specifier, session.lexiconPackages)) {
+    try {
+      modulePath = resolveModulePathMemoized(binding.specifier, fromFile, session.resolvePathCache);
+    } catch {
+      return undefined;
+    }
+  } else {
+    // chant#2577 — a lexicon declared by path, imported by its path.
+    modulePath = activeLexiconModule(binding.specifier, fromFile, session.lexiconModules, session.resolvePathCache);
+    if (modulePath === undefined) return undefined;
   }
 
   let mod: Record<string, unknown>;
@@ -1278,6 +1361,10 @@ interface ResolveCtx {
    * site that imports and executes a module.
    */
   lexiconPackages: ReadonlySet<string>;
+  /** chant#2577 — see {@link FoldSession.lexiconModules}. */
+  lexiconModules: ReadonlySet<string>;
+  /** chant#2590 — see {@link FoldSession.lexiconRoots}. */
+  lexiconRoots: readonly string[];
   /** chant #1093 — see {@link FoldSession.sandbox}. */
   sandbox: boolean;
   /** chant#2455 — see {@link FoldSession.executing}. */
@@ -2053,7 +2140,10 @@ function findCompositeDefinition(
       // chant build the set holds only `@intentius/chant-lexicon-*`, and no
       // lexicon exports a `Composite`, so nothing about a chant project moves.
       const chantOwned = isChantOwnedHelperBinding(compositeBinding, { ...ctx, file: scope.file });
-      const hostOwned = activeLexiconPackage(compositeBinding.specifier, ctx.lexiconPackages) !== undefined;
+      const hostOwned =
+        activeLexiconPackage(compositeBinding.specifier, ctx.lexiconPackages) !== undefined ||
+        activeLexiconModule(compositeBinding.specifier, scope.file, ctx.lexiconModules, ctx.resolvePathCache) !==
+          undefined;
       if (!chantOwned && !hostOwned) return undefined;
 
       const [fnArg, nameArg] = init.arguments;
@@ -2425,6 +2515,8 @@ async function interpretCompositeFactory(
     importCache: ctx.importCache,
     resolvePathCache: ctx.resolvePathCache,
     lexiconPackages: ctx.lexiconPackages,
+    lexiconModules: ctx.lexiconModules,
+    lexiconRoots: ctx.lexiconRoots,
     sandbox: ctx.sandbox,
     executing: ctx.executing,
     session: ctx.session,
@@ -3048,6 +3140,12 @@ function isTrustedExecutableBinding(binding: ImportBinding, ctx: ResolveCtx): bo
   } catch {
     return false;
   }
+  // chant#2577 — arm 1 for a lexicon declared by path: the module
+  // `loadPlugins` already imported, reached by the path the project imports it by.
+  if (ctx.lexiconModules.has(targetPath)) return true;
+  // chant#2590 — the subpath case of the same arm: another file of a
+  // multi-file path lexicon, under its trusted directory.
+  if (inPathLexiconRoot(targetPath, ctx.lexiconRoots)) return true;
   const root = chantCoreRoot();
   return targetPath === root || targetPath.startsWith(root + sep);
 }
@@ -3607,6 +3705,20 @@ async function buildExternals(
     } catch {
       continue;
     }
+    // chant#2577 — a path-declared lexicon is a lexicon, not a project file:
+    // resolve its data export the way the bare-specifier branch above does,
+    // with no `liveSources` edge for the same reason.
+    if (session.lexiconModules.has(targetPath)) {
+      const lexiconExport = await resolveActiveLexiconExport(binding, file, session);
+      if (lexiconExport) externals.set(localName, lexiconExport.value);
+      continue;
+    }
+    // chant#2590 — another file of a multi-file path lexicon is a lexicon
+    // subpath, not a project file: it is not folded, and like a package
+    // subpath (see the bare-specifier branch above) its data exports are not
+    // read as values. A constructor or composite from it resolves through the
+    // import path, where `isTrustedExecutableBinding` admits it.
+    if (inPathLexiconRoot(targetPath, session.lexiconRoots)) continue;
     const result = await foldFileMemoized(targetPath, session);
     if (!result.ok) {
       failures.set(localName, locatedMessage(binding.specifierNode, result.reason));
@@ -3632,6 +3744,9 @@ async function buildExternals(
     } catch {
       continue;
     }
+    // chant#2577 — a namespace import of a lexicon is left alone, as the
+    // bare-specifier check above leaves a package's alone.
+    if (session.lexiconModules.has(targetPath) || inPathLexiconRoot(targetPath, session.lexiconRoots)) continue;
     const result = await foldFileMemoized(targetPath, session);
     if (!result.ok) {
       failures.set(localName, locatedMessage(binding.specifierNode, result.reason));
@@ -3738,6 +3853,8 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
       importCache: session.importCache,
       resolvePathCache: session.resolvePathCache,
       lexiconPackages: session.lexiconPackages,
+      lexiconModules: session.lexiconModules,
+      lexiconRoots: session.lexiconRoots,
       sandbox: session.sandbox,
       executing: session.executing,
       session,
@@ -4267,6 +4384,7 @@ export async function foldProject(
     options.sandbox ?? false,
     options.lexiconPackages ?? [],
     options.executing ?? false,
+    files,
   );
   const attempts = new Map<string, FoldFileResult>();
   for (const file of files) attempts.set(file, await tryFoldFile(file, intrinsics, session));

package/src/discovery/index.ts

@@ -291,6 +291,7 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
         options.sandbox === true,
         [],
         options.executing === true,
+        files,
       )
     : undefined;
   if (options?.fold) {

package/src/discovery/sandbox/driver.ts

@@ -70,6 +70,49 @@ function lit(value: unknown): string {
   return JSON.stringify(value);
 }
 
+/**
+ * chant#2461 — the `send` every driver uses, as generated source lines.
+ *
+ * `process.send` is asynchronous: it queues the message on the IPC channel and
+ * returns. Node's contract is that the optional callback runs once the message
+ * has been written, or with an error if it could not be. Without the callback a
+ * failed send is not reported to the caller at all, so the driver could return
+ * from `main()` believing it had answered.
+ *
+ * So `send` returns a promise that settles only when the write has completed,
+ * and every call site awaits it before `main()` returns. A send that fails, or
+ * throws synchronously (a payload that cannot be serialized), writes the reason
+ * to stderr with a synchronous `writeSync` and exits 1. That way a result that
+ * never left the child cannot end as exit 0 with empty stderr, which is the
+ * signature that looks like success went missing.
+ *
+ * `before` is spliced in at the top of the function body (the run driver marks
+ * itself `reported` there).
+ */
+export function sendFunctionSource(before: readonly string[] = []): string[] {
+  return [
+    `function send(payload) {`,
+    ...before.map((line) => `  ${line}`),
+    `  if (typeof process.send !== "function") {`,
+    `    console.log(JSON.stringify(payload));`,
+    `    return Promise.resolve();`,
+    `  }`,
+    `  return new Promise((resolve) => {`,
+    `    const lost = (err) => {`,
+    `      writeSync(2, "chant: the sandboxed child could not hand its result to the parent: " +`,
+    `        (err && err.message ? err.message : String(err)) + " (chant#2461)\\n");`,
+    `      process.exit(1);`,
+    `    };`,
+    `    try {`,
+    `      process.send(payload, (err) => (err ? lost(err) : resolve()));`,
+    `    } catch (err) {`,
+    `      lost(err);`,
+    `    }`,
+    `  });`,
+    `}`,
+  ];
+}
+
 /**
  * Generate the driver module's full TypeScript source. Written to a tmp file
  * and bundled (see `./bundle.ts`) before being handed to a sandboxed child —
@@ -117,11 +160,7 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     `    "Nothing is thrown, so nothing else can name it (chant#2461).\\n");`,
     `});`,
     ``,
-    `function send(payload) {`,
-    `  reported = true;`,
-    `  if (typeof process.send === "function") process.send(payload);`,
-    `  else console.log(JSON.stringify(payload));`,
-    `}`,
+    ...sendFunctionSource([`reported = true;`]),
     ``,
     // collectEntities (bundled, real DiscoveryError instances) already names
     // the exact offending file on a same-directory duplicate — reuse that
@@ -156,7 +195,7 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     `    entities = collectEntities(modules, BUILD_ROOT);`,
     `  } catch (err) {`,
     `    errors.push(classifyChildError(errFile(err), err, "resolution").toJSON());`,
-    `    send({ entitySet: { entities: [] }, errors, provenanceByName: {} });`,
+    `    await send({ entitySet: { entities: [] }, errors, provenanceByName: {} });`,
     `    return;`,
     `  }`,
     ``,
@@ -178,18 +217,20 @@ export function generateDriverSource(options: GenerateDriverOptions): string {
     `    errors.push(classifyChildError("", err, "resolution").toJSON());`,
     `  }`,
     ``,
+    `  let entitySet;`,
     `  try {`,
-    `    const entitySet = encodeEntitySet(entities);`,
-    `    send({ entitySet, errors, provenanceByName });`,
+    `    entitySet = encodeEntitySet(entities);`,
     `  } catch (err) {`,
     `    errors.push(classifyChildError("", err, "resolution").toJSON());`,
-    `    send({ entitySet: { entities: [] }, errors, provenanceByName });`,
+    `    await send({ entitySet: { entities: [] }, errors, provenanceByName });`,
+    `    return;`,
     `  }`,
+    `  await send({ entitySet, errors, provenanceByName });`,
     `}`,
     ``,
-    `main().catch((err) => {`,
-    `  send({ entitySet: { entities: [] }, errors: [classifyChildError("", err).toJSON()], provenanceByName: {}, fatal: true });`,
-    `});`,
+    `main().catch((err) =>`,
+    `  send({ entitySet: { entities: [] }, errors: [classifyChildError("", err).toJSON()], provenanceByName: {}, fatal: true }),`,
+    `);`,
   );
 
   return lines.join("\n");
@@ -218,18 +259,16 @@ export function generateConfigDriverSource(configPath: string): string {
   return [
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { scanConfigWireSafety } from ${lit(CONFIG_WIRE_MODULE)};`,
+    `import { writeSync } from "node:fs";`,
     ``,
-    `function send(payload) {`,
-    `  if (typeof process.send === "function") process.send(payload);`,
-    `  else console.log(JSON.stringify(payload));`,
-    `}`,
+    ...sendFunctionSource(),
     ``,
     `async function main() {`,
     `  let namespace;`,
     `  try {`,
     `    namespace = await import(${lit(configPath)});`,
     `  } catch (err) {`,
-    `    send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
+    `    await send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
     `    return;`,
     `  }`,
     ``,
@@ -240,24 +279,26 @@ export function generateConfigDriverSource(configPath: string): string {
     ``,
     `  const offenders = scanConfigWireSafety(selected);`,
     `  if (offenders.length > 0) {`,
-    `    send({ kind: "chant-config", ok: false, offenders });`,
+    `    await send({ kind: "chant-config", ok: false, offenders });`,
     `    return;`,
     `  }`,
     ``,
+    `  let config;`,
     `  try {`,
     // Round-trip here, not just at the IPC boundary: this is what proves the
     // payload really is JSON before it leaves the child, and turns anything
     // the scan somehow missed into a named error instead of a quiet drop.
-    `    const config = JSON.parse(JSON.stringify(selected ?? {}));`,
-    `    send({ kind: "chant-config", ok: true, config });`,
+    `    config = JSON.parse(JSON.stringify(selected ?? {}));`,
     `  } catch (err) {`,
-    `    send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err, "resolution").toJSON() });`,
+    `    await send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err, "resolution").toJSON() });`,
+    `    return;`,
     `  }`,
+    `  await send({ kind: "chant-config", ok: true, config });`,
     `}`,
     ``,
-    `main().catch((err) => {`,
-    `  send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() });`,
-    `});`,
+    `main().catch((err) =>`,
+    `  send({ kind: "chant-config", ok: false, error: classifyChildError(${lit(configPath)}, err).toJSON() }),`,
+    `);`,
   ].join("\n");
 }
 
@@ -294,18 +335,15 @@ export function generatePolicyDriverSource(policyPaths: readonly string[]): stri
     `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
     `import { decodePolicyBuildResult, scanPolicyDiagnostics, PolicyWireError } from ${lit(POLICY_WIRE_MODULE)};`,
     `import { runPostSynthChecks, isPostSynthCheck } from ${lit(POST_SYNTH_MODULE)};`,
+    `import { writeSync } from "node:fs";`,
     ``,
-    `function send(payload) {`,
-    `  if (typeof process.send === "function") process.send(payload);`,
-    `  else console.log(JSON.stringify(payload));`,
-    `}`,
+    ...sendFunctionSource(),
     ``,
     `function fail(file, err, type) {`,
     `  if (err instanceof PolicyWireError) {`,
-    `    send({ kind: "chant-policy", ok: false, offenders: err.offenders });`,
-    `    return;`,
+    `    return send({ kind: "chant-policy", ok: false, offenders: err.offenders });`,
     `  }`,
-    `  send({ kind: "chant-policy", ok: false, error: classifyChildError(file, err, type).toJSON() });`,
+    `  return send({ kind: "chant-policy", ok: false, error: classifyChildError(file, err, type).toJSON() });`,
     `}`,
     ``,
     // The wrapper described in the doc above: same id/description so any
@@ -329,7 +367,7 @@ export function generatePolicyDriverSource(policyPaths: readonly string[]): stri
     `  try {`,
     `    buildResult = decodePolicyBuildResult(request.buildResult);`,
     `  } catch (err) {`,
-    `    fail("", err, "resolution");`,
+    `    await fail("", err, "resolution");`,
     `    return;`,
     `  }`,
     ``,
@@ -347,7 +385,7 @@ export function generatePolicyDriverSource(policyPaths: readonly string[]): stri
       `      if (isPostSynthCheck(value)) checks.push(guard(value, ${lit(policyPath)}));`,
       `    }`,
       `  } catch (err) {`,
-      `    fail(${lit(policyPath)}, err, "import");`,
+      `    await fail(${lit(policyPath)}, err, "import");`,
       `    return;`,
       `  }`,
     );
@@ -359,11 +397,11 @@ export function generatePolicyDriverSource(policyPaths: readonly string[]): stri
     `  try {`,
     `    diagnostics = runPostSynthChecks(checks, buildResult, request.env ?? undefined);`,
     `  } catch (err) {`,
-    `    fail("", err, "resolution");`,
+    `    await fail("", err, "resolution");`,
     `    return;`,
     `  }`,
     ``,
-    `  send({ kind: "chant-policy", ok: true, diagnostics });`,
+    `  await send({ kind: "chant-policy", ok: true, diagnostics });`,
     `}`,
     ``,
     // Registered synchronously at module top level — see the doc above on why