@intentius/chant 0.19.1 → 0.21.0

package/dist/discovery/entity-wire.d.ts

@@ -0,0 +1,50 @@
+/**
+ * chant #1045 (Phase 1) — the JSON wire format for a discovered, named,
+ * ref-resolved entity set, plus (below) the standalone `discover()` +
+ * encode entry point.
+ *
+ * The codec itself — {@link WireValue}, {@link EntitySetWire},
+ * {@link encodeEntitySet}, {@link decodeEntitySet}, and friends — lives in
+ * `./entity-wire-codec.ts` (chant #1045 Phase 2 split this out) and is
+ * re-exported here unchanged. That file has NO dependency on `discover()` (or
+ * anything that pulls in the `typescript` compiler package), which matters
+ * because chant #1045 Phase 2's sandboxed child bundles JUST the codec —
+ * bundling this file, `discoverEntitySetJson` and all, would drag `discover`
+ * → `fold-import` → `typescript` (a multi-megabyte CJS package that doesn't
+ * survive ESM bundling on its own) into a driver that only ever needs to
+ * encode, never to discover. See `./sandbox/driver.ts`.
+ */
+export type { WireValue, WireDeclarableEntity, WireLexiconOutputEntity, WireEntity, EntitySetWire, } from "./entity-wire-codec.js";
+export { encodeEntitySet, decodeEntitySet } from "./entity-wire-codec.js";
+import type { FoldDecision } from "./index.js";
+import { type DiscoveryOptions } from "./index.js";
+import { type EntitySetWire } from "./entity-wire-codec.js";
+/** A discovery run's full result as pure JSON — {@link encodeEntitySet} plus the already-JSON-safe rest of {@link DiscoveryResult} (`./index.ts`). */
+export interface DiscoveredEntitiesJson {
+    entitySet: EntitySetWire;
+    sourceFiles: string[];
+    /** `DiscoveryError.toJSON()` output — see `../errors.ts`. */
+    errors: Array<{
+        name: string;
+        file: string;
+        message: string;
+        type: string;
+    }>;
+    foldDecisions: FoldDecision[];
+}
+/**
+ * Run discovery over `path` — scanning files, importing/folding modules,
+ * naming entities, and resolving `AttrRef`s (all unchanged, reusing
+ * `discover()` as-is) — and return the result as pure JSON via
+ * {@link encodeEntitySet}. This is the boundary chant#1045 Phase 2 moved into
+ * a sandboxed child process for the run-fallback subset — see
+ * `./sandbox/run.ts` — Phase 1 only proved the data can cross it losslessly
+ * (see the fold-vs-JSON differential in `examples/`).
+ *
+ * Reuses `discover()` unchanged, so the fold/run-fallback split and the
+ * `planFoldTaint` identity-taint invariant (`./fold-import.ts`) are exactly
+ * what they are today — this function only serializes whatever `discover()`
+ * already decided to produce.
+ */
+export declare function discoverEntitySetJson(path: string, options?: DiscoveryOptions): Promise<DiscoveredEntitiesJson>;
+//# sourceMappingURL=entity-wire.d.ts.map

package/dist/discovery/entity-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-wire.d.ts","sourceRoot":"","sources":["../../src/discovery/entity-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EACV,SAAS,EACT,oBAAoB,EACpB,uBAAuB,EACvB,UAAU,EACV,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAY,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAO1E,sJAAsJ;AACtJ,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,6DAA6D;IAC7D,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7E,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAQrH"}

package/dist/discovery/fold-import.d.ts

@@ -0,0 +1,239 @@
+import { type Declarable } from "../declarable.js";
+import { type CompositeInstance } from "../composite.js";
+import type { IntrinsicDef } from "../lexicon.js";
+import type { BuildParamValue } from "../build-params.js";
+/**
+ * Bridges the static folder ({@link ../fold/fold}, #1026) into discovery
+ * (#1022/#1023, epic #1019): attempts to fold one source file into real
+ * `Declarable`/`CompositeInstance` instances with zero execution of the
+ * file's own top-level code, so `discover()` can skip `importModule` for it
+ * entirely.
+ *
+ * The folder only reduces expressions to plain values — it has no notion of
+ * lexicon resource classes or composites. This module supplies that missing
+ * piece: it reads the file's `import` declarations to learn which module
+ * each `new Type(...)` constructor or bare composite-factory call names,
+ * resolves and imports *that* module (a trusted lexicon/vendor module, not
+ * the file under fold), and constructs the real resource/composite instance
+ * from the folded props. Importing the lexicon module is not a regression on
+ * "no module execution" — the run path already imports it to get the same
+ * class/function; the only thing skipped here is executing the file's *own*
+ * statements.
+ *
+ * chant #1023 (epic #1019 Phase 5) extends this from leaf resources
+ * (`new Type(...)`) to composite factory calls — `SomeComposite({...})`,
+ * `propagate(SomeComposite({...}), {...})`, member access on the result
+ * (`web.deployment`), and destructuring (`const { a, b } = SomeComposite(...)`
+ * or `export const { a, b } = SomeComposite(...)`). A composite factory is a
+ * pure function of its props (EVL009/EVL010 guarantee its body only
+ * references props, sibling members, and imports), so — exactly like a
+ * resource constructor — it's safe to resolve through the file's imports and
+ * actually invoke with statically-folded props: no need to pre-verify "is
+ * this specifically a registered composite" via a shared registry (which
+ * would be unreliable across separately-loaded module instances of
+ * `@intentius/chant` anyway) — {@link resolveCallExpression} just resolves,
+ * invokes, and lets the RESULT speak. If it satisfies
+ * {@link isCompositeInstance} (or, for a plain resource-returning helper,
+ * {@link isDeclarable}), it's used. Nested composites and `propagate()`'d
+ * shared props need no special-casing: a nested composite is just another
+ * member the real factory call already produced (real JS execution inside a
+ * trusted module), and `propagate` is just another resolvable imported
+ * function that receives a live `CompositeInstance` plus folded shared props
+ * and returns it — `expandComposite()` (invoked downstream by
+ * `collectEntities`, unchanged) does the recursive expansion and the shared-
+ * prop merge exactly as it does for the run path.
+ */
+/** One exported `const` name folded to a real, constructed `Declarable` or `CompositeInstance`. */
+export type FoldedEntity = [name: string, entity: Declarable | CompositeInstance];
+export type FoldFileResult = {
+    ok: true;
+    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.
+     */
+    exportedValues: Map<string, unknown>;
+    /**
+     * chant #1044 — the OTHER project files whose exported OBJECTS this
+     * fold consumed (a cross-file `Declarable`, composite instance, or any
+     * other non-primitive reached through `buildExternals`/a re-export).
+     *
+     * Object identity is the thing that cannot survive one side of the
+     * build folding while the other runs, so `planFoldTaint` needs to know
+     * who consumed whose objects: if a file here is forced back to run, the
+     * instance THIS file already captured is not the instance discovery
+     * will collect, and serialization fails on an entity with no logical
+     * name. A primitive (string, number, boolean, null) is never recorded —
+     * it has no identity to disagree about.
+     */
+    liveSources: ReadonlySet<string>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * A per-build memo (chant #1020) so a project file imported by several
+ * others is folded exactly ONCE — every referrer resolves against the SAME
+ * `FoldFileResult`, and therefore the SAME constructed
+ * `Declarable`/`CompositeInstance` objects, no matter how many files
+ * cross-file-reference it or in what order discovery visits them. Also
+ * tracks the current resolution call chain (`stack`) so a genuine reference
+ * cycle (fileA needs fileB needs fileA) is DETECTED — rather than an
+ * infinite recursion / a promise awaiting itself forever — and reported as a
+ * located `FoldError` naming the cycle path.
+ *
+ * `discover()` creates exactly one session per `{ fold: true }` build and
+ * passes it to every top-level `tryFoldFile` call, so its own per-file loop
+ * and any cross-file reference reaching into the same file share the
+ * identical cache. Callers that don't care about cross-file sharing (unit
+ * tests exercising a single file in isolation) can omit it — {@link tryFoldFile}
+ * creates a private, single-call session on their behalf.
+ */
+export interface FoldSession {
+    readonly intrinsics: readonly IntrinsicDef[];
+    readonly cache: Map<string, Promise<FoldFileResult>>;
+    readonly stack: string[];
+    /**
+     * Per-build memo (chant #1020 hang fix) for {@link importModule} itself —
+     * keyed by resolved absolute module path, shared session-wide exactly like
+     * {@link cache} above. Cross-file resolution means MANY files in one
+     * directory can each independently resolve the SAME constructor/composite-
+     * factory import (e.g. every file that constructs an AWS resource imports
+     * the same lexicon barrel) — before this, every one of those calls issued
+     * its own `await import(path)`, relying entirely on the runtime's own
+     * module cache to make the repeats cheap. That assumption holds for a
+     * plain `node`/`tsx` process, but NOT for a real dynamic import running
+     * inside a vitest worker: `vite-node`'s own SSR module graph can take a
+     * real, non-trivial amount of wall-clock time to re-resolve/re-register an
+     * already-loaded module on EVERY call, not just the first — harmless at
+     * single-digit call counts, but #1020's cross-file resolution can issue
+     * several times as many `importModule` calls for the same handful of large
+     * lexicon barrels within one `discover()` pass as the pre-#1020 single-file
+     * fold did. Memoizing the import itself (not just the path resolution)
+     * caps it at exactly one real `import()` per unique path per session,
+     * regardless of how many files reference it — this is what actually keeps
+     * a session-local retry (e.g. `sandbox-differential.test.ts`'s
+     * `vi.resetModules()` + rebuild path, which reruns fold from a cold
+     * module cache) from compounding into a multi-minute stall. Purely a cache
+     * over an idempotent operation (the same resolved path always yields the
+     * same module namespace object) — doesn't change what folds.
+     */
+    readonly importCache: Map<string, Promise<Record<string, unknown>>>;
+    /**
+     * Per-build memo (chant #1020 hang fix) for {@link resolveModulePath}'s
+     * RELATIVE/absolute-specifier branch only — keyed by
+     * `${dirname(fromFile)}\0${specifier}`. See {@link resolveModulePathMemoized}'s
+     * doc for the full story, including why bare (package) specifiers are
+     * memoized in a separate, process-wide cache instead of this session-
+     * scoped one: a relative specifier resolves against PROJECT source, which
+     * `chant build --watch` can legitimately change between rebuilds (a new
+     * sibling file appearing mid-session), so this cache is intentionally
+     * thrown away with the rest of the session at the end of every
+     * `discover()` call, unlike the bare-specifier one.
+     */
+    readonly resolvePathCache: Map<string, string>;
+    /**
+     * chant #1064 — this build's resolved build-time parameter values (see
+     * ../build-params.ts), consulted only by {@link buildExternals}'s one
+     * recognized bare-specifier case: a named `params` import resolving to
+     * ../params.ts. `undefined` when the build supplied none (no `chant.config.ts`
+     * `buildParams` declared, or the caller didn't pass any) — a project that
+     * doesn't use build-time parameters pays nothing extra here.
+     */
+    readonly buildParams?: Readonly<Record<string, BuildParamValue>>;
+}
+/** Create a fresh, empty {@link FoldSession}. */
+export declare function createFoldSession(intrinsics?: readonly IntrinsicDef[], buildParams?: Readonly<Record<string, BuildParamValue>>): FoldSession;
+/**
+ * Attempt to fold one source file with zero execution of its own top-level
+ * code. Returns the folded, instantiated entities on success, or a reason
+ * to fall back to the run path (`importModule`) on the first construct
+ * outside the fold subset.
+ *
+ * @param intrinsics - Lexicon-registered intrinsic tags (chant #1039), e.g.
+ *   AWS's `Sub`. Threaded down to {@link fold}/{@link foldResource} so a
+ *   registered tagged template folds instead of unconditionally throwing
+ *   "unregistered tagged template intrinsic". Defaults to none — the caller
+ *   (`discover()`, ultimately `chant build --fold`) is expected to pass the
+ *   target lexicons' combined `intrinsics()`. Ignored when `session` is
+ *   given (its own `intrinsics`, fixed at creation, apply instead).
+ * @param session - chant #1020: share ONE {@link FoldSession} across every
+ *   file in a build (as `discover()` does) so a project file imported by
+ *   several others folds exactly once and every referrer shares the same
+ *   constructed entities — see {@link FoldSession}'s doc. Omit for a
+ *   standalone, single-file fold attempt (creates a private session scoped
+ *   to just this call — a cross-file reference reachable from `file` still
+ *   resolves, just without sharing its cache with any other top-level call).
+ */
+export declare function tryFoldFile(file: string, intrinsics?: readonly IntrinsicDef[], session?: FoldSession): Promise<FoldFileResult>;
+/**
+ * A file that folds successfully in isolation must still be forced back to
+ * run if some OTHER discovered file — one that itself falls back to run —
+ * imports it (directly, or transitively through another sibling file it
+ * imports). Composite folding is what makes this reachable: `network.ts`
+ * exporting `export const network = VpcDefault({})` folds cleanly on its
+ * own (no cross-file reference needed), landing its Declarables (`vpc`, its
+ * subnets, …) in `entities` as ONE set of real objects, built by literally
+ * invoking `VpcDefault` from inside `tryFoldFile` — bypassing `network.ts`
+ * as a module entirely (that's the whole point of folding it).
+ *
+ * Before chant #1020, a sibling file like `alb.ts` that did
+ * `import { network } from "./network"; ... vpcId: network.vpc.VpcId`
+ * could never fold that cross-file reference and fell back to run — but
+ * running `alb.ts` for real re-executes `import "./network"` for real too,
+ * which (via Node's module cache) produces the SAME `network.ts` module
+ * instance for every OTHER run-fallback file that imports it, but a
+ * DIFFERENT one than the object `tryFoldFile("network.ts")` already built.
+ * `alb.ts`'s AttrRef for `network.vpc.VpcId` then points at an object
+ * that's never in the `entities` map (only the folded one is), so it can
+ * never be assigned a logical name and serialization fails outright — not
+ * drift, a crash.
+ *
+ * The fix: fold and run must never disagree about which object identity a
+ * given file's exports have. Since `network.ts` itself doesn't need
+ * anything cross-file to fold (only a file's own successful fold could ever
+ * reach this taint — an unresolvable cross-file reference already fails
+ * that file's OWN fold attempt), the safe rule is to force `network.ts`
+ * back to run too, so both `alb.ts`'s real import and `network.ts`'s own
+ * discovery entry resolve through the exact same `importModule` call and
+ * share the exact same singleton module instance. This has to propagate
+ * transitively (if `alb.ts` itself is only reachable by importing a file
+ * that imports `network.ts`), so this is a forward-reachability walk over
+ * the discovered files' relative-import graph, seeded from every file that
+ * doesn't fold on its own.
+ *
+ * chant #1044 adds the OTHER half of the same hazard, in the opposite
+ * direction along the same edges. Forward taint covers "a run file imports a
+ * folded file"; it does not cover "a FOLDED file consumed the objects of a
+ * file that later got forced to run". Once a plain-call intrinsic can fold,
+ * that second case is easy to reach: in `lexicons/aws/examples/lambda-api`,
+ * `health-api.ts` folds and captures `params.ts`'s real `Parameter` instance
+ * through `Ref(environment)`, while `params.ts` itself is forced to run
+ * because a DIFFERENT sibling (`data-bucket.ts`) imports it and falls back.
+ * Discovery then collects the run instance and serializes the folded one —
+ * the same "Logical name not set" crash described above, arriving from the
+ * other side. So `liveSources` (see {@link FoldFileResult}) contributes
+ * reverse edges here: a tainted file taints every folded file that captured
+ * one of its objects. Only object identity propagates — a file that imported
+ * a plain string from a tainted file has nothing to disagree about.
+ *
+ * chant #1020 changes the calculus but not this function: `alb.ts` can now
+ * often fold `network.vpc.VpcId` too (see `buildExternals`/`foldFileMemoized`
+ * above), by reusing THE EXACT SAME `tryFoldFile("network.ts")` call (memoized
+ * per `FoldSession`) that `discover()`'s own per-file loop also uses — so
+ * `alb.ts` and `network.ts` share one real `vpc` object without ever
+ * disagreeing. This invariant is still needed for whatever STILL falls back
+ * after #1020 (a call-as-a-value construct, #1044; a shape #1020 doesn't
+ * cover): the edge collection below is unconditional — it doesn't care
+ * whether an edge happens to ALSO be used for cross-file value resolution —
+ * so the exact same forced-taint safety net still applies to that remaining
+ * boundary, unchanged.
+ */
+export declare function planFoldTaint(files: readonly string[], wouldFold: ReadonlyMap<string, boolean>, liveSources?: ReadonlyMap<string, ReadonlySet<string>>): Promise<Set<string>>;
+//# sourceMappingURL=fold-import.d.ts.map

package/dist/discovery/fold-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-import.d.ts","sourceRoot":"","sources":["../../src/discovery/fold-import.ts"],"names":[],"mappings":"AAMA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAgB3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,mGAAmG;AACnG,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,iBAAiB,CAAC,CAAC;AAElF,MAAM,MAAM,cAAc,GACtB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB;;;;;;;;;OASG;IACH,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAClC,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CAClE;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAC/B,UAAU,GAAE,SAAS,YAAY,EAAO,EACxC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GACtD,WAAW,CAEb;AAsmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,SAAS,YAAY,EAAO,EACxC,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,cAAc,CAAC,CAEzB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,GACrD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CA8EtB"}

package/dist/discovery/index.d.ts

@@ -1,5 +1,72 @@
 import type { Declarable } from "../declarable.js";
 import type { DiscoveryError } from "../errors.js";
+import type { IntrinsicDef } from "../lexicon.js";
+import type { BuildParamProvenance } from "../provenance.js";
+/**
+ * Per-file fold-vs-run outcome (chant #1022, epic #1019), populated only
+ * when {@link DiscoveryOptions.fold} was requested. Lets a caller (`chant
+ * build --fold`) report which files skipped module execution and which
+ * fell back to the run path, and why.
+ */
+export interface FoldDecision {
+    /** Absolute path of the source file this decision covers. */
+    file: string;
+    /** "fold" — folded statically, zero execution. "run" — imported/executed as before. */
+    mode: "fold" | "run";
+    /** Why the file fell back to run. Present only when `mode === "run"` and fold was requested. */
+    reason?: string;
+    /** Number of entities the fold produced. Present only when `mode === "fold"`. */
+    resourceCount?: number;
+}
+/**
+ * Optional inputs to {@link discover}.
+ */
+export interface DiscoveryOptions {
+    /**
+     * chant #1022/#1023 (epic #1019) — opt-in: for each source file, try to
+     * fold it to `Declarable`/`CompositeInstance` entities statically (no
+     * module execution) before falling back to importing/running it. Anything
+     * the folder can't represent (a non-`new`, non-composite-call export, a
+     * cross-file-only reference, …) falls back per-file — see
+     * {@link planFoldTaint} for the one case where a file that WOULD fold in
+     * isolation is still forced back to run, to keep fold and run from ever
+     * disagreeing about a shared entity's identity. Default `false` — behavior
+     * is unchanged unless requested.
+     */
+    fold?: boolean;
+    /**
+     * chant #1039 — lexicon-registered intrinsic tags (e.g. AWS's `Sub`) to
+     * recognize while folding. Threaded down to `tryFoldFile`/the static
+     * folder so a registered tagged template folds instead of falling back to
+     * run. Only meaningful when {@link fold} is set; ignored otherwise.
+     * Default: none (an intrinsic-using file still folds up to that point,
+     * then falls back to run at the unregistered tag).
+     */
+    intrinsics?: IntrinsicDef[];
+    /**
+     * chant #1045 Phase 2 — opt-in: whatever would otherwise reach the
+     * in-process `importModule` step (every file, when {@link fold} isn't set;
+     * only the per-file run-fallback remainder, when it is) instead runs
+     * together, isolated, in one sandboxed child process — see
+     * `./sandbox/run.ts`. Folded files are unaffected: fold already executes
+     * zero of a file's own top-level code, so it stays in this process exactly
+     * as it does today. Default `false` — behavior, including performance
+     * (no bundling, no child process, no IPC), is unchanged unless requested.
+     */
+    sandbox?: boolean;
+    /**
+     * chant #1064 — this build's resolved build-time parameter values (see
+     * ../build-params.ts's `resolveBuildParams`, driven by the CLI's
+     * `--param`/`--params-file`/declared `env` mapping/`chant.config.ts`
+     * defaults). Populated into `../params.ts`'s shared `params` object
+     * (`setBuildParams`, below) before any project file is imported or folded,
+     * and threaded into the fold session so a `params.<name>` reference
+     * resolves to a literal instead of an unresolved identifier. Default: none
+     * — `params` stays empty, matching a project that declares no
+     * `buildParams` at all.
+     */
+    buildParams?: BuildParamProvenance[];
+}
 /**
  * Result of the discovery process
  */
@@ -12,6 +79,11 @@ export interface DiscoveryResult {
     sourceFiles: string[];
     /** Array of errors encountered during discovery */
     errors: DiscoveryError[];
+    /**
+     * Per-file fold-vs-run decisions (#1022). Empty unless
+     * {@link DiscoveryOptions.fold} was set.
+     */
+    foldDecisions: FoldDecision[];
 }
 /**
  * Discovers all declarable entities in a directory by scanning files,
@@ -19,7 +91,8 @@ export interface DiscoveryResult {
  * a dependency graph.
  *
  * @param path - The directory path to discover entities in
+ * @param options - Optional discovery behavior, e.g. {@link DiscoveryOptions.fold}
  * @returns DiscoveryResult with entities, dependencies, sourceFiles, and errors
  */
-export declare function discover(path: string): Promise<DiscoveryResult>;
+export declare function discover(path: string, options?: DiscoveryOptions): Promise<DiscoveryResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/discovery/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAOhD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAqGrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAI1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAE5B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;OAGG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAoQjG"}

package/dist/discovery/sandbox/bundle.d.ts

@@ -0,0 +1,18 @@
+export interface BundleResult {
+    /** Absolute, REALPATH'd path to the bundled entry file — this and {@link bundleDir} are what the caller grants `--allow-fs-read` to. macOS's `/tmp` is a symlink to `/private/tmp`; an un-canonicalized path here would silently fail to match Node's own (already-canonicalized) permission check. */
+    bundlePath: string;
+    /** Absolute, REALPATH'd directory containing {@link bundlePath} — remove with `rmSync(bundleDir, { recursive: true, force: true })` once done. */
+    bundleDir: string;
+    /** Directories the child ALSO needs `--allow-fs-read` for — the resolved locations of {@link EXTERNAL_PACKAGES}, which are deliberately left unbundled (see {@link externalTrustedPackagesPlugin}'s doc). Empty when none of those packages were actually imported. */
+    externalReadPaths: string[];
+    /** Wall-clock bundling time — chant#1045 asks this be measured and reported, not silently accepted. */
+    durationMs: number;
+    /** Bundle size in bytes. */
+    bytes: number;
+}
+/**
+ * Bundle `driverSource` (see {@link import("./driver.js").generateDriverSource})
+ * into a single self-contained ESM file.
+ */
+export declare function bundleDriver(driverSource: string): Promise<BundleResult>;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/discovery/sandbox/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/discovery/sandbox/bundle.ts"],"names":[],"mappings":"AA4KA,MAAM,WAAW,YAAY;IAC3B,uSAAuS;IACvS,UAAU,EAAE,MAAM,CAAC;IACnB,kJAAkJ;IAClJ,SAAS,EAAE,MAAM,CAAC;IAClB,uQAAuQ;IACvQ,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA4B9E"}

package/dist/discovery/sandbox/child-errors.d.ts

@@ -0,0 +1,15 @@
+import { DiscoveryError, type DiscoveryErrorType } from "../../errors.js";
+/**
+ * Classify one error raised while executing run-fallback project source (or
+ * chant's own collect/resolve/encode step) inside the sandboxed child.
+ *
+ * @param file - The project source file being executed when `err` was
+ *   thrown, or `""` for an error not attributable to one specific file (e.g.
+ *   `collectEntities`/`resolveAttrRefs` over the whole batch).
+ * @param fallbackType - The {@link DiscoveryErrorType} to use when `err`
+ *   isn't a permission denial — mirrors how `discover()` itself types a
+ *   plain import failure `"import"` vs. a collection/resolution failure
+ *   `"resolution"`.
+ */
+export declare function classifyChildError(file: string, err: unknown, fallbackType?: DiscoveryErrorType): DiscoveryError;
+//# sourceMappingURL=child-errors.d.ts.map

package/dist/discovery/sandbox/child-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-errors.d.ts","sourceRoot":"","sources":["../../../src/discovery/sandbox/child-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAkCvE;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,EACZ,YAAY,GAAE,kBAA6B,GAC1C,cAAc,CAchB"}

package/dist/discovery/sandbox/driver.d.ts

@@ -0,0 +1,13 @@
+export interface GenerateDriverOptions {
+    /** Absolute paths to the run-fallback files this build decided NOT to fold — see `discover()`'s fold/taint loop in `../index.ts`. */
+    files: readonly string[];
+    /** The build root — threaded to `collectEntities` exactly as `discover()` threads its own `path` argument, so cross-directory stack-prefix disambiguation (chant #932) is computed the same way for this subset. */
+    buildRoot: string;
+}
+/**
+ * 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 —
+ * never executed directly by the parent process.
+ */
+export declare function generateDriverSource(options: GenerateDriverOptions): string;
+//# sourceMappingURL=driver.d.ts.map

package/dist/discovery/sandbox/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../src/discovery/sandbox/driver.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,qBAAqB;IACpC,qIAAqI;IACrI,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,oNAAoN;IACpN,SAAS,EAAE,MAAM,CAAC;CACnB;AAOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAqF3E"}

package/dist/discovery/sandbox/run.d.ts

@@ -0,0 +1,69 @@
+import type { Declarable } from "../../declarable.js";
+import { DiscoveryError } from "../../errors.js";
+/**
+ * chant #1045 Phase 2 — runs every run-fallback file for a build TOGETHER, as
+ * one bundled module graph, inside one sandboxed child process, and returns
+ * the same shape `discover()`'s own in-process run path would have produced:
+ * a named, ref-resolved entities map plus any errors.
+ *
+ * Isolation mechanics (verified on Node v24.13.1 — see the chant#1045 PR
+ * description for the full write-up):
+ *  - `--permission --allow-fs-read=<bundle dir>,<project dir>[,<trusted
+ *    external package dirs>]` — no filesystem write, no child-process, no
+ *    worker-thread access. Bundling with esbuild first (not a packaging
+ *    change — see `./bundle.ts`) means the child needs NO TypeScript loader
+ *    (no `tsx`, so no `--allow-worker` and no writable temp dir either),
+ *    unlike the plain `tsx`-based run path. The "trusted external package
+ *    dirs" allowance is narrow and specific: `./bundle.ts` deliberately
+ *    leaves a couple of chant/lexicon-internal dependencies (`typescript`)
+ *    unbundled and resolves them to their real, fixed location instead —
+ *    project source never controls what's installed there.
+ *  - The env is a spawn-time scrub (`env: {}` below, plus `PATH` — see the
+ *    option below), not `--permission`: Node's Permission Model does not gate
+ *    `process.env` at all (confirmed: every key stays readable even under
+ *    `--permission`).
+ *  - Network egress is NOT addressed here — Node has no flag for it. See the
+ *    chant#1045 PR description / docs for the residual-risk statement and
+ *    deployment guidance (a container with no egress, a network namespace).
+ *    This function does not claim to close that gap.
+ *
+ * What does NOT run inside the child: fold (`tryFoldFile`, `../fold-import`)
+ * stays exactly where it is today, in the parent, unsandboxed — fold already
+ * executes zero of the file's own top-level code (chant #1022/#1023), so
+ * isolating it buys nothing and would only cost a bundle+spawn per build.
+ * Only genuine run-fallback files are handed to this function.
+ */
+export interface SandboxRunResult {
+    /** Named, ref-resolved entities from the run-fallback set — decoded from the child's `EntitySetWire` response, functionally indistinguishable from what `importModule` + `collectEntities` + `resolveAttrRefs` would have produced in-process for this same file set (see `../entity-wire.ts`'s `decodeEntitySet` doc). */
+    entities: Map<string, Declarable>;
+    /** Import/collection/resolution/permission errors, already chant-shaped (see `./child-errors.ts` — a permission denial names the file and the operation, never a raw `ERR_ACCESS_DENIED`). */
+    errors: DiscoveryError[];
+    /** esbuild bundling wall-clock time — chant#1045 asks this be measured, not silently accepted. */
+    bundleMs: number;
+    /** Bundle size in bytes. */
+    bundleBytes: number;
+    /**
+     * Entity name → declaring file, for every entity in {@link entities} whose
+     * provenance (`../../provenance.ts`) named one. The wire format itself
+     * doesn't carry this (`encodeEntitySet` intentionally drops build metadata,
+     * not declared configuration) — it rides back as a small side channel so a
+     * parent-side merge collision against the fold-only set (a bare name
+     * genuinely exported by both a folded and a run-fallback file in the same
+     * directory) can name the real file, not the entity name. See `../index.ts`.
+     */
+    provenanceByName: Record<string, string>;
+}
+/**
+ * Run `files` (already decided "run" by `discover()`'s fold/taint pass)
+ * together, isolated, in one sandboxed child process. Returns the same
+ * `{ entities, errors }` shape the parent's own `collectEntities` +
+ * `resolveAttrRefs` would have — see `../index.ts`'s `discover()`, which
+ * merges this result into the entities it collected from folded files.
+ *
+ * @param files - Absolute paths to run-fallback files.
+ * @param buildRoot - The directory `discover()` was pointed at — threaded to
+ *   `collectEntities` inside the child (stack-prefix disambiguation, #932)
+ *   and used to compute the project-directory read allowance.
+ */
+export declare function runFallbackFilesSandboxed(files: readonly string[], buildRoot: string): Promise<SandboxRunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/discovery/sandbox/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/discovery/sandbox/run.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAC;AAMvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,2TAA2T;IAC3T,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8LAA8L;IAC9L,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAsC3B"}

package/dist/errors.d.ts

@@ -1,7 +1,15 @@
 /**
  * Error types for chant discovery, build, and lint failures
  */
-export type DiscoveryErrorType = "import" | "resolution" | "circular";
+/**
+ * `"permission"` (chant #1045 Phase 2) — a run-fallback file executing inside
+ * the sandboxed child (`./discovery/sandbox/`) hit Node's Permission Model
+ * (`ERR_ACCESS_DENIED`) — filesystem, child-process, or worker-thread access
+ * outside the sandbox's allowlist. Distinct from `"import"` (a module simply
+ * failed to load/execute for an ordinary reason) so a permission denial is
+ * recognizable as a sandbox boundary hit, not a generic import failure.
+ */
+export type DiscoveryErrorType = "import" | "resolution" | "circular" | "permission";
 /**
  * Error during file discovery or module import
  */

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAC;AAEtE;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB;IAOnE,MAAM;;;;;;CAQP;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAM/C,MAAM;;;;;CAOP;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM;IAUjB,MAAM;;;;;;;;CAUP"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAErF;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;gBAEtB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB;IAOnE,MAAM;;;;;;CAQP;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAM/C,MAAM;;;;;CAOP;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM;IAUjB,MAAM;;;;;;;;CAUP"}