@intentius/chant 0.22.0 → 0.23.0

package/src/components/cli-support.ts

@@ -23,6 +23,7 @@
  */
 
 import { discoverComponents } from "./discover";
+import type { BuildParamProvenance } from "../provenance";
 import { projectToJson, type Archetype } from "./component";
 import {
   resolveComponentGraph,
@@ -185,6 +186,8 @@ export interface GenerateComponentsResult {
   /** Every generated job, for a machine-readable view (`--format json`). */
   jobs?: Array<{ jobName: string; component: string; stage: string; needs: string[] }>;
   error?: string;
+  /** This invocation's resolved build-time parameters (chant #1108) — the generate-mode counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Empty when the project declares/supplies none. */
+  buildParams?: BuildParamProvenance[];
 }
 
 /**
@@ -221,6 +224,15 @@ export async function generateComponentsPipeline(
   lexicon: GenerateLexicon,
   options?: ComponentPipelineOptions,
   sandbox?: boolean,
+  /**
+   * chant #1108 — this invocation's resolved build-time parameter values
+   * (../cli/handlers/build.ts resolves them, the same sequence `chant build`
+   * runs, BEFORE calling this function), forwarded into discovery so a
+   * `params.<name>` reference inside a discovered `*.component.ts` file
+   * resolves instead of reading `{}`. See `discoverComponents`'s
+   * `buildParams` option (./discover.ts) for the full doc.
+   */
+  buildParams?: BuildParamProvenance[],
 ): Promise<GenerateComponentsResult> {
   const plugin = await loadLexiconPlugin(lexicon);
   if (!plugin?.generateComponentPipeline) {
@@ -230,7 +242,7 @@ export async function generateComponentsPipeline(
     };
   }
 
-  const result = await discoverComponents(path, { sandbox });
+  const result = await discoverComponents(path, { sandbox, buildParams });
   if (result.errors.length > 0) {
     return { success: false, error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -243,7 +255,7 @@ export async function generateComponentsPipeline(
 
   try {
     const { yaml, stages, jobs } = plugin.generateComponentPipeline(driverComponents, options);
-    return { success: true, yaml, stages, jobs };
+    return { success: true, yaml, stages, jobs, buildParams };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, error: err.message };
@@ -344,6 +356,21 @@ export interface RunComponentsOptions {
    * `--progress-json`, in which case nothing changes.
    */
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * chant #1108 — this run's resolved build-time parameter values, resolved
+   * the exact same way `chant build` resolves them
+   * (../cli/build-params-cli.ts's `resolveCliBuildParams`, driven by
+   * `--param`/`--params-file`/a declared `env` mapping/`chant.config.ts`'s
+   * `buildParams` defaults). The CLI handler (../cli/handlers/run.ts)
+   * resolves + logs these BEFORE calling `runComponents`, the same
+   * sequencing `chant build` uses — this function only forwards the
+   * already-resolved values into discovery (`resolveComponentTargets` below,
+   * then `discoverComponents`); it does not resolve them itself, so
+   * `runComponents` stays free of CLI-flag-parsing/formatting concerns.
+   * Default: none — `params.*` stays `{}`, matching every caller (including
+   * every test in `cli-support.test.ts`) that doesn't supply this.
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -356,6 +383,8 @@ export interface RunComponentsResult {
   error?: string;
   /** Set when a selected component (or one of its `deploy`/`rollback` phases) contains a `gate` the local executor cannot run. */
   gateUnsupported?: { component: string; signalName: string };
+  /** This run's resolved build-time parameters (chant #1108) — the component-driver counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Present only once the run actually reached dispatch (mirrors `BuildResult.buildParams`, which is likewise absent on an early-error return). */
+  buildParams?: BuildParamProvenance[];
 }
 
 /**
@@ -404,8 +433,10 @@ export async function resolveComponentTargets(
   path: string,
   selector: string,
   sandbox?: boolean,
+  /** chant #1108 — this invocation's resolved build-time parameter values, forwarded into `discoverComponents` so a `params.<name>` reference inside a discovered `*.component.ts` file resolves instead of reading `{}`. See `discoverComponents`'s `buildParams` option (./discover.ts). */
+  buildParams?: BuildParamProvenance[],
 ): Promise<ResolvedComponentTargets> {
-  const result = await discoverComponents(path, { sandbox });
+  const result = await discoverComponents(path, { sandbox, buildParams });
   if (result.errors.length > 0) {
     return { success: false, targets: [], error: result.errors.map((e) => e.message).join("\n") };
   }
@@ -433,7 +464,7 @@ export async function runComponents(
   selector: string,
   options: RunComponentsOptions = {},
 ): Promise<RunComponentsResult> {
-  const resolved = await resolveComponentTargets(path, selector, options.sandbox);
+  const resolved = await resolveComponentTargets(path, selector, options.sandbox, options.buildParams);
   if (!resolved.success) {
     return { success: false, selected: [], error: resolved.error };
   }
@@ -479,7 +510,7 @@ export async function runComponents(
   try {
     if (selector === "all") {
       const run = await runInterpretDriver(resolvedTargets, registry, { env, componentOutputs: seedOutputs, onProgress });
-      return { success: true, run, selected };
+      return { success: true, run, selected, buildParams: options.buildParams };
     }
 
     // Single-component invocation: run just this component, bypassing
@@ -518,7 +549,7 @@ export async function runComponents(
       failedComponent: componentResult.ok ? undefined : componentResult.component,
       componentOutputs,
     };
-    return { success: componentResult.ok, run, selected };
+    return { success: componentResult.ok, run, selected, buildParams: options.buildParams };
   } catch (err) {
     if (err instanceof DriverRunFailure) {
       return { success: false, run: err.result, selected, error: err.message };

package/src/components/discover.test.ts

@@ -11,9 +11,11 @@
 
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { mkdir, writeFile, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { join, dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import { discoverComponents } from "./discover";
+import { params } from "../params";
 
 describe("discoverComponents", () => {
   let testDir: string;
@@ -349,4 +351,64 @@ describe("discoverComponents", () => {
     expect(result.components.has("first-svc")).toBe(true);
     expect(result.components.has("nested-svc")).toBe(false);
   });
+
+  // ── chant #1108 — build-time parameters populated before import ────────────
+
+  describe("buildParams (chant #1108)", () => {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    const paramsPath = resolvePath(thisDir, "../params");
+
+    test("with no buildParams option, params.* stays empty (matches every non-run/generate caller today)", async () => {
+      await writeFile(
+        join(testDir, "svc.component.ts"),
+        `
+          export const svc = {
+            name: "svc",
+            dependsOn: [],
+            deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }],
+          };
+        `,
+      );
+
+      const result = await discoverComponents(testDir);
+
+      expect(result.components.has("svc")).toBe(true);
+      expect(params).toEqual({});
+    });
+
+    test("populates params.* BEFORE importing *.component.ts, so a live import observes the resolved value", async () => {
+      await writeFile(
+        join(testDir, "svc.component.ts"),
+        `
+          import { params } from ${JSON.stringify(paramsPath)};
+          export const svc = {
+            name: "svc",
+            dependsOn: [],
+            deploy: [{ phase: "Apply", steps: [{ kind: "shell", command: String(params.tier) }] }],
+          };
+        `,
+      );
+
+      const result = await discoverComponents(testDir, {
+        buildParams: [{ name: "tier", value: "production", source: "cli" }],
+      });
+
+      expect(result.errors).toEqual([]);
+      const svc = result.components.get("svc");
+      expect((svc?.component.deploy[0].steps[0] as { command?: unknown }).command).toBe("production");
+    });
+
+    test("a second call with no buildParams resets params.* — no stale leak from a prior call in the same process", async () => {
+      await writeFile(
+        join(testDir, "a.component.ts"),
+        `export const a = { name: "a", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell" }] }] };`,
+      );
+
+      await discoverComponents(testDir, { buildParams: [{ name: "tier", value: "production", source: "cli" }] });
+      expect(params).toEqual({ tier: "production" });
+
+      await discoverComponents(testDir);
+      expect(params).toEqual({});
+    });
+  });
 });

package/src/components/discover.ts

@@ -46,6 +46,9 @@ import { pathToFileURL } from "node:url";
 import { existsSync } from "node:fs";
 import { DiscoveryError } from "../errors";
 import { isComponent, type Component } from "./component";
+import type { BuildParamProvenance } from "../provenance";
+import { buildParamValues } from "../build-params";
+import { setBuildParams } from "../params";
 
 /** One discovered component, paired with the file it was exported from. */
 export interface DiscoveredComponent {
@@ -75,6 +78,34 @@ export interface ComponentDiscoveryOptions {
    * requested.
    */
   sandbox?: boolean;
+
+  /**
+   * chant #1108 — this invocation's resolved build-time parameter values
+   * (../build-params.ts's `resolveBuildParams`, driven by the CLI's
+   * `--param`/`--params-file`/a declared `env` mapping/`chant.config.ts`'s
+   * `buildParams` defaults — see ../cli/build-params-cli.ts's
+   * `resolveCliBuildParams`, the exact resolution `chant build` runs).
+   * Populated into ../params.ts's shared `params` object (`setBuildParams`,
+   * below) before any `*.component.ts` file is scanned/imported, mirroring
+   * ../discovery/index.ts's `discover()` — the lexicon-resource counterpart
+   * of this function, and the thing chant #1108 exists to bring this one to
+   * parity with. Before #1108, no caller populated this, so a live `import {
+   * params } from "@intentius/chant/params"` inside a component file (e.g. a
+   * naming helper deriving a stack name) always saw `{}`.
+   *
+   * Default: none — `params` stays `{}`, matching every caller that doesn't
+   * resolve build-time parameters today (`chant list/describe/graph/lint
+   * --components`, `chant components status`); only the run and generate
+   * call sites (../cli/handlers/run.ts, ../cli/handlers/build.ts) pass a
+   * resolved value.
+   *
+   * Only takes effect for the in-process (non-sandboxed) import path below —
+   * `{ sandbox: true }`'s child process gets its own, unpopulated `params`
+   * module instance, the same pre-existing gap `discover({ sandbox: true })`
+   * has for lexicon resources (chant #1045 Phase 2 never threaded
+   * `buildParams` into its sandboxed child either; out of scope here too).
+   */
+  buildParams?: BuildParamProvenance[];
 }
 
 /** One already-imported `*.component.ts` module — the input to {@link collectComponents}. */
@@ -240,6 +271,17 @@ export async function discoverComponents(
   path: string,
   options?: ComponentDiscoveryOptions,
 ): Promise<ComponentDiscoveryResult> {
+  // chant #1108 — populate the shared build-time-parameters object BEFORE
+  // scanning/importing any *.component.ts file below, so a live `import {
+  // params } from "@intentius/chant/params"` inside a component file
+  // observes this invocation's resolved values instead of an empty object.
+  // Unconditional (not just when `buildParams` is set) so a stale value from
+  // a PRIOR discoverComponents() call in the same process (tests, several
+  // `--components` subcommands run back-to-back) never leaks into a call
+  // that supplied none — mirrors ../discovery/index.ts's `discover()`,
+  // identical rationale.
+  setBuildParams(buildParamValues(options?.buildParams ?? []));
+
   const sourceFiles = await findComponentFiles(path);
 
   if (options?.sandbox && sourceFiles.length > 0) {

package/src/discovery/fold-import.ts

@@ -20,7 +20,7 @@ import {
   type FoldedHelperCall,
   type SymbolicValue,
 } from "../fold/fold";
-import { isChantOwnedSpecifier } from "../fold/foldable-helpers";
+import { isChantOwnedSpecifier, isFoldableHelperName } from "../fold/foldable-helpers";
 import { briefNodeText, callExpressionMessage } from "../fold/subset";
 import { importModule } from "./import";
 import type { IntrinsicDef } from "../lexicon";
@@ -74,16 +74,29 @@ export type FoldedEntity = [name: string, entity: Declarable | CompositeInstance
 export type FoldFileResult =
   | {
       ok: true;
+      /**
+       * The `Declarable`/`CompositeInstance` subset of {@link
+       * FoldFileResult.exportedValues} — how many resources this file
+       * contributed, for the `[fold:fold] x.ts — N resource(s)` decision
+       * line. chant #1112: NOT what discovery collects from. Collection
+       * reads `exportedValues`, so that `./collect.ts` stays the single
+       * owner of which exports become entities — see {@link
+       * applyResolvedValue}.
+       */
       entities: FoldedEntity[];
       /**
        * chant #1020 — EVERY exported name's fully-resolved value, not just
-       * the `Declarable`/`CompositeInstance` ones already in `entities`: a
-       * plain value folds too (a string, a number, a plain object), it just
-       * contributes nothing to `entities` (see {@link applyResolvedValue}).
-       * This is the table another file's cross-file reference resolves
-       * against — see `buildExternals` below and the module doc on
-       * `planFoldTaint` for why a resource/composite value here MUST be the
-       * exact same object every referencing file sees.
+       * the `Declarable`/`CompositeInstance` ones also listed in `entities`:
+       * a plain value folds too (a string, a number, a plain object). A
+       * successful fold means `scanExports` recognized every export the file
+       * has (anything else disqualifies the whole file), so this IS the
+       * file's complete export namespace — the same table the run path gets
+       * from actually importing it. Two consumers: `discover()` passes it
+       * straight to `collectEntities` (chant #1112), and another file's
+       * cross-file reference resolves against it — see `buildExternals`
+       * below and the module doc on `planFoldTaint` for why a
+       * resource/composite value here MUST be the exact same object every
+       * referencing file sees.
        */
       exportedValues: Map<string, unknown>;
       /**
@@ -190,6 +203,20 @@ export interface FoldSession {
    * established one.
    */
   readonly lexiconPackages: ReadonlySet<string>;
+  /**
+   * chant #1093 — this build asked for the #1045 sandbox
+   * (`DiscoveryOptions.sandbox`, `chant build --sandbox`), so fold must not
+   * import or invoke a module the CLI process isn't already trusted to
+   * execute. See {@link isTrustedExecutableBinding} for what that allowlist
+   * is and {@link sandboxedExecutionRefusal} for what happens at each site
+   * that would otherwise execute one.
+   *
+   * `false` (the default, plain `--fold`) leaves every resolution path
+   * exactly as it was: fold already trusts the code enough to fall back to
+   * an in-process `importModule` when it can't fold something, so gating
+   * only the fold half would buy nothing there.
+   */
+  readonly sandbox: boolean;
 }
 
 /**
@@ -210,11 +237,15 @@ export function lexiconPackageName(lexiconName: string): string {
  * @param lexicons - chant #1063: the lexicon NAMES active for this build
  *   (`["aws", "k8s"]`). Converted to package specifiers via
  *   {@link lexiconPackageName}; see {@link FoldSession.lexiconPackages}.
+ * @param sandbox - chant #1093: this build asked for the #1045 sandbox, so
+ *   fold may not import or invoke anything outside the trusted allowlist —
+ *   see {@link FoldSession.sandbox}.
  */
 export function createFoldSession(
   intrinsics: readonly IntrinsicDef[] = [],
   buildParams?: Readonly<Record<string, BuildParamValue>>,
   lexicons: readonly string[] = [],
+  sandbox = false,
 ): FoldSession {
   return {
     intrinsics,
@@ -224,6 +255,7 @@ export function createFoldSession(
     resolvePathCache: new Map(),
     buildParams,
     lexiconPackages: new Set(lexicons.map(lexiconPackageName)),
+    sandbox,
   };
 }
 
@@ -1007,6 +1039,16 @@ interface ResolveCtx {
    * {@link resolveModulePathMemoized} with this map.
    */
   resolvePathCache: Map<string, string>;
+  /**
+   * chant #1063 — this build's active lexicon PACKAGE specifiers (see
+   * {@link FoldSession.lexiconPackages}). Threaded down here, not just used
+   * in `buildExternals`, because chant #1093's trust check
+   * ({@link isTrustedExecutableBinding}) needs the same allowlist at every
+   * site that imports and executes a module.
+   */
+  lexiconPackages: ReadonlySet<string>;
+  /** chant #1093 — see {@link FoldSession.sandbox}. */
+  sandbox: boolean;
 }
 
 /** `{ value }` when `node`'s shape was recognized and resolved (value may itself be `undefined`/`null` — e.g. an optional composite member that wasn't created); `undefined` when the shape isn't one the live resolver understands (a plain literal, etc.) — callers fall back to the original, unchanged handling for that shape. */
@@ -1116,6 +1158,14 @@ async function resolveCallExpression(node: ts.CallExpression, ctx: ResolveCtx):
     throw cheapError(callExpressionMessage(node));
   }
 
+  // chant #1093 — THE gap this check exists for. Invoking the callee runs
+  // project code (the factory body, and its whole module's top level) in the
+  // CLI's own process; under --sandbox that has to happen in the child
+  // instead, so refuse here and let the file fall back to the sandboxed run
+  // path. See {@link sandboxedExecutionRefusal}.
+  const refusal = sandboxedExecutionRefusal(binding, ctx, calleeName, "composite factory");
+  if (refusal) throw cheapError(refusal);
+
   let modulePath: string;
   try {
     modulePath = resolveModulePathMemoized(binding.specifier, ctx.file, ctx.resolvePathCache);
@@ -1152,6 +1202,22 @@ async function resolveCallExpression(node: ts.CallExpression, ctx: ResolveCtx):
     throw cheapError(`"${binding.imported}" from "${binding.specifier}" is not a function`);
   }
 
+  // chant #1112 — ONE rule for a registered authoring helper's arguments,
+  // applied at BOTH sites that can invoke one. `reviveHelperCall` (the
+  // nested-value site, #1082) already revives a helper's arguments with
+  // `requireLiveRefs`, because a helper reads THROUGH its ref (`output()`
+  // derefs the `WeakRef` parent) and a look-alike `{__attrRef}` envelope
+  // makes it produce a wrong result rather than none. This site — a
+  // top-level `export const oArn = output(bucket.Arn, "oArn")` — took the
+  // composite-factory rule (`false`) instead, which is right for a factory
+  // (its props keep the envelope, and the serializer's own walker resolves
+  // it) and wrong for a helper. It went unnoticed while the resulting
+  // `LexiconOutput` was being discarded anyway; with the export namespace
+  // now collected in full, a same-file `output(...)` would reach the
+  // serializer holding an inert envelope where the run path has a real
+  // reference. Rejected here instead, which falls the file back to run —
+  // absent output, never a wrong one.
+  const helperArgs = isFoldableHelperName(calleeName);
   const args: unknown[] = [];
   for (const argNode of node.arguments) {
     const live = await resolveLiveValue(argNode, ctx);
@@ -1162,7 +1228,7 @@ async function resolveCallExpression(node: ts.CallExpression, ctx: ResolveCtx):
     args.push(
       live !== undefined
         ? live.value
-        : await reviveFoldedValue(fold(argNode, ctx.consts, ctx.intrinsics, ctx.externals), ctx, false),
+        : await reviveFoldedValue(fold(argNode, ctx.consts, ctx.intrinsics, ctx.externals), ctx, helperArgs),
     );
   }
 
@@ -1170,17 +1236,23 @@ async function resolveCallExpression(node: ts.CallExpression, ctx: ResolveCtx):
 }
 
 /**
- * Record one exported name's fully-resolved value: into `entities` when
- * it's a real `Declarable`/`CompositeInstance` (`collectEntities`, and
- * therefore serialization, only cares about these), and — chant #1020 —
- * unconditionally into `exportedValues` too, so a plain value (a string, a
- * number, a plain object, `undefined`/`null`) is still available for
- * ANOTHER file's cross-file reference to this export, exactly as it would
- * be if this file were actually imported and its real `exports` object read
- * directly. A plain value contributing nothing to `entities` isn't a
- * failure: the run path's real `exports` object would contain it too, and
- * `collectEntities` already silently ignores a non-Declarable/array/
- * CompositeInstance export the same way (see enumerateEntries, ../collect.ts).
+ * Record one exported name's fully-resolved value: unconditionally into
+ * `exportedValues` (chant #1020) — the file's export namespace, which is
+ * what discovery hands to `collectEntities` and what another file's
+ * cross-file reference resolves against — and, additionally, into `entities`
+ * when the value is a real `Declarable`/`CompositeInstance`.
+ *
+ * chant #1112 — `entities` is a REPORTING subset, not a filter. It used to
+ * be the only thing discovery passed on, which made this function a second
+ * owner of the "which export becomes an entity" decision; it had one fewer
+ * case than the real owner (`enumerateEntries`, ../collect.ts), so a
+ * `LexiconOutput` export folded fine and was then thrown away, and the
+ * template silently lost its `Outputs` section. Discovery now passes
+ * `exportedValues` — the whole namespace, exactly like the run path's real
+ * `exports` object — and `collectEntities` filters it, so nothing here can
+ * fall behind what collection understands. What `entities` still answers is
+ * "how many resources did this file contribute", for the `[fold:fold] x.ts —
+ * N resource(s)` decision line.
  */
 function applyResolvedValue(
   name: string,
@@ -1234,6 +1306,14 @@ async function resolveImportedExport(name: string, ctx: ResolveCtx): Promise<unk
     throw cheapError(`"${name}" is not a resolvable import`);
   }
 
+  // chant #1093 — reached for an intrinsic tag and for a symbolic chain's root
+  // (`AWS.StackName`), both of which are resolved BY NAME out of the file's own
+  // imports: nothing guarantees the module behind that name is a lexicon's.
+  // `reviveHelperCall` checks chant-ownership before it gets here; this covers
+  // the paths that don't.
+  const refusal = sandboxedExecutionRefusal(binding, ctx, name, "import");
+  if (refusal) throw cheapError(refusal);
+
   let modulePath: string;
   try {
     modulePath = resolveModulePathMemoized(binding.specifier, ctx.file, ctx.resolvePathCache);
@@ -1434,6 +1514,15 @@ async function reviveHelperCall(call: FoldedHelperCall, ctx: ResolveCtx): Promis
  * pathological cold-resolution cost chant#1020 measured (see
  * {@link fastResolveBareSpecifier}), and a bare specifier chant publishes is
  * already covered by the text arm.
+ *
+ * Not the same question as chant#1093's {@link isTrustedExecutableBinding}
+ * below, and deliberately not shared with it: this one asks "may this NAME be
+ * invoked as one of chant's registered authoring helpers", and a text match
+ * is the right answer for it — a project that shadows `@intentius/chant` in
+ * its own `node_modules` gets its own copy of `output()` invoked either way,
+ * fold or run, so fold cannot diverge from run by trusting the text here.
+ * #1093's question is "may this module execute in the CLI's process at all",
+ * where a specifier the project controls the text of proves nothing.
  */
 function isChantOwnedHelperBinding(binding: ImportBinding, ctx: ResolveCtx): boolean {
   if (isChantOwnedSpecifier(binding.specifier)) return true;
@@ -1448,6 +1537,89 @@ function isChantOwnedHelperBinding(binding: ImportBinding, ctx: ResolveCtx): boo
   return targetPath === root || targetPath.startsWith(root + sep);
 }
 
+/**
+ * chant #1093 — the closed allowlist of modules fold may import AND EXECUTE
+ * in the CLI's own process when the #1045 sandbox is active. Exactly two
+ * arms, and neither of them trusts text the project controls:
+ *
+ *  1. **An ACTIVE lexicon package of this build** — matched against
+ *     {@link FoldSession.lexiconPackages}, a closed set built from the
+ *     lexicon names the BUILD resolved and `loadPlugins` already imported
+ *     (../cli/plugins.ts), not from anything the file under fold says.
+ *  2. **chant-core's own executing tree** — the specifier is RESOLVED and the
+ *     resulting path checked against {@link chantCoreRoot}. A text match is
+ *     not enough here: `@intentius/chant` and `@intentius/chant-lexicon-evil`
+ *     are both strings an untrusted repo can write into its own source and
+ *     back with its own `node_modules` directory, and
+ *     {@link isChantOwnedSpecifier} would accept either. Resolution happens
+ *     before the decision rather than after, so an allowed binding pays
+ *     exactly the resolution it was about to pay anyway (the memoized one —
+ *     see {@link resolveModulePathMemoized}); a bare specifier that isn't
+ *     even chant-shaped is rejected on text alone, so no arbitrary bare
+ *     specifier is ever resolved here (chant#1020's cold-resolution cost).
+ *
+ * This is deliberately the boundary chant #1045 drew: "the boundary is around
+ * executing PROJECT SOURCE, which is the untrusted input" — not around chant
+ * itself or the lexicon packages, which the CLI has already imported and
+ * executed in its own process before discovery starts, to get the serializers
+ * and lint rules it cannot run without. Fold reaching the same already-loaded
+ * module (the identical un-cache-busted `import()` of the identical resolved
+ * path) adds no execution the process wasn't already performing.
+ *
+ * Everything else is out: a sibling project file, a project-local helper
+ * module, an arbitrary npm dependency, a lexicon this build didn't load. A
+ * build that supplied no lexicon list keeps only arm 2, rather than falling
+ * back to something more permissive — the same stance
+ * {@link FoldSession.lexiconPackages} takes for #1063.
+ */
+function isTrustedExecutableBinding(binding: ImportBinding, ctx: ResolveCtx): boolean {
+  if (activeLexiconPackage(binding.specifier, ctx.lexiconPackages) !== undefined) return true;
+  // Only a chant-shaped or project-relative specifier is worth resolving; any
+  // other bare specifier is untrusted by definition, and resolving it to find
+  // that out would cost the pathological cold `require.resolve` (chant#1020).
+  if (!isProjectFileSpecifier(binding.specifier) && !isChantOwnedSpecifier(binding.specifier)) return false;
+  let targetPath: string;
+  try {
+    targetPath = resolveModulePathMemoized(binding.specifier, ctx.file, ctx.resolvePathCache);
+  } catch {
+    return false;
+  }
+  const root = chantCoreRoot();
+  return targetPath === root || targetPath.startsWith(root + sep);
+}
+
+/**
+ * chant #1093 — the one-line fold-fallback reason for a resolution that would
+ * import and execute an untrusted module in the CLI's own process, or
+ * `undefined` when the import may proceed (the sandbox wasn't asked for, or
+ * the module is on {@link isTrustedExecutableBinding}'s allowlist).
+ *
+ * A refusal is not a failure to fold something folder-shaped — the shape is
+ * perfectly foldable and folds fine under plain `--fold`. It is a deliberate
+ * demotion: the file falls back to the run path, and under `--sandbox` the
+ * run path is the sandboxed child (`./index.ts` queues every run-fallback
+ * file for `./sandbox/run.ts`). So the factory/constructor/intrinsic still
+ * executes, with the same arguments, in the same module graph as the rest of
+ * that file — just behind Node's Permission Model and a scrubbed environment
+ * instead of inside the CLI. Coverage drops; the boundary holds.
+ *
+ * @param what - What the binding is being resolved AS, for the message
+ *   ("composite factory", "constructor", …).
+ */
+function sandboxedExecutionRefusal(
+  binding: ImportBinding,
+  ctx: ResolveCtx,
+  name: string,
+  what: string,
+): string | undefined {
+  if (!ctx.sandbox) return undefined;
+  if (isTrustedExecutableBinding(binding, ctx)) return undefined;
+  return (
+    `${what} "${name}" is imported from "${binding.specifier}", which is neither chant's own nor an active lexicon — ` +
+    `under --sandbox it is executed in the sandboxed child, not in this process`
+  );
+}
+
 /**
  * chant-core's own module root — `packages/core/src` in this repo,
  * `<pkg>/dist` in a published install — derived from THIS module's location.
@@ -1533,6 +1705,14 @@ async function resolveResourceEntity(
     return { ok: false, reason: `constructor "${typeName}" for "${name}" is not a resolvable import` };
   }
 
+  // chant #1093 — a resource class is a lexicon export in every corpus entry
+  // today, but nothing forces that: `new Thing(...)` where `Thing` comes from
+  // a project file (or an arbitrary dependency) would import and run that
+  // module here, in the CLI's process. Same refusal as the composite-factory
+  // path above.
+  const refusal = sandboxedExecutionRefusal(binding, ctx, typeName, "constructor");
+  if (refusal) return { ok: false, reason: refusal };
+
   let modulePath: string;
   try {
     modulePath = resolveModulePathMemoized(binding.specifier, ctx.file, ctx.resolvePathCache);
@@ -1903,6 +2083,8 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
       crossFileFailures: failures,
       importCache: session.importCache,
       resolvePathCache: session.resolvePathCache,
+      lexiconPackages: session.lexiconPackages,
+      sandbox: session.sandbox,
     };
 
     const entities: FoldedEntity[] = [];