@intentius/chant 0.20.0 → 0.22.0

package/src/discovery/fold-import.ts

@@ -1,12 +1,13 @@
 import * as ts from "typescript";
 import { readFile } from "node:fs/promises";
 import { existsSync, statSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, basename, join, isAbsolute, resolve as resolvePath } from "node:path";
+import { dirname, basename, join, sep, isAbsolute, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { isDeclarable, type Declarable } from "../declarable";
 import { isCompositeInstance, type CompositeInstance } from "../composite";
 import { isAttrRefLike } from "../utils";
+import { isIntrinsic } from "../intrinsic";
 import {
   collectConsts,
   foldResource,
@@ -16,8 +17,11 @@ import {
   type FoldedResource,
   type FoldedValue,
   type FoldedIntrinsic,
+  type FoldedHelperCall,
   type SymbolicValue,
 } from "../fold/fold";
+import { isChantOwnedSpecifier } from "../fold/foldable-helpers";
+import { briefNodeText, callExpressionMessage } from "../fold/subset";
 import { importModule } from "./import";
 import type { IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
@@ -82,6 +86,20 @@ export type FoldFileResult =
        * 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 };
 
@@ -155,14 +173,58 @@ export interface FoldSession {
    * doesn't use build-time parameters pays nothing extra here.
    */
   readonly buildParams?: Readonly<Record<string, BuildParamValue>>;
+  /**
+   * chant #1063 — the exact package specifiers of the lexicons LOADED for
+   * this build (`@intentius/chant-lexicon-aws`, …), derived from the lexicon
+   * names the build already resolved (`resolveProjectLexicons` ->
+   * `loadPlugins`, see ../cli/plugins.ts). This is the entire allowlist
+   * {@link buildExternals} will follow a bare import specifier into — see
+   * {@link activeLexiconPackage} for why the set is matched by TEXT and
+   * built from names the build already knows, rather than by resolving
+   * specifiers to find out what they are.
+   *
+   * Empty when the caller supplied no lexicon list, which disables
+   * lexicon-package resolution entirely rather than falling back to
+   * something more permissive: "an active lexicon of this build" is the
+   * boundary, and a build that can't say what its lexicons are hasn't
+   * established one.
+   */
+  readonly lexiconPackages: ReadonlySet<string>;
+}
+
+/**
+ * chant #1063 — the package specifier a lexicon NAME (`"aws"`, `"gitlab"`)
+ * is installed under. The one naming convention the whole CLI already
+ * depends on: `loadPlugin(name)` imports exactly this
+ * (../cli/plugins.ts), `detectLexicons` scans source for exactly this
+ * (../detectLexicon.ts), and `chant init` writes exactly this into
+ * package.json.
+ */
+export function lexiconPackageName(lexiconName: string): string {
+  return `@intentius/chant-lexicon-${lexiconName}`;
 }
 
-/** Create a fresh, empty {@link FoldSession}. */
+/**
+ * Create a fresh, empty {@link FoldSession}.
+ *
+ * @param lexicons - chant #1063: the lexicon NAMES active for this build
+ *   (`["aws", "k8s"]`). Converted to package specifiers via
+ *   {@link lexiconPackageName}; see {@link FoldSession.lexiconPackages}.
+ */
 export function createFoldSession(
   intrinsics: readonly IntrinsicDef[] = [],
   buildParams?: Readonly<Record<string, BuildParamValue>>,
+  lexicons: readonly string[] = [],
 ): FoldSession {
-  return { intrinsics, cache: new Map(), stack: [], importCache: new Map(), resolvePathCache: new Map(), buildParams };
+  return {
+    intrinsics,
+    cache: new Map(),
+    stack: [],
+    importCache: new Map(),
+    resolvePathCache: new Map(),
+    buildParams,
+    lexiconPackages: new Set(lexicons.map(lexiconPackageName)),
+  };
 }
 
 /**
@@ -789,6 +851,100 @@ function paramsModulePath(): string | null {
   return paramsModulePathMemo;
 }
 
+/**
+ * chant #1063 — is `specifier` a bare import of a package that is an ACTIVE
+ * LEXICON of this build? Returns the specifier itself when so, `undefined`
+ * otherwise.
+ *
+ * Three deliberate restrictions, each of which is the point rather than an
+ * omission:
+ *
+ *  - **Text only, no resolution.** The answer is a `Set.has` on a set built
+ *    from the lexicon names the build ALREADY resolved before discovery ran
+ *    (`resolveProjectLexicons` -> `loadPlugins`). Nothing is probed, read, or
+ *    resolved to decide whether a specifier is in scope — so an import of
+ *    some unrelated package costs a string comparison and is then left alone,
+ *    never resolved "just to find out what it is". That matters here more
+ *    than anywhere: `resolveModulePath`'s bare branch can fall through to
+ *    `createRequire(fromFile).resolve(specifier)`, measured at up to ~361s
+ *    for the first resolution of a genuinely new bare specifier in a process
+ *    (see {@link bareSpecifierPathCache}/{@link fastResolveBareSpecifier} —
+ *    this exact class of cost regressed twice during chant#1020).
+ *
+ *  - **Exact package specifier, no subpaths.** `@intentius/chant-lexicon-aws`
+ *    matches; `@intentius/chant-lexicon-aws/actions` does not. Every lexicon
+ *    re-exports its whole public surface from its barrel and every example
+ *    imports it that way, so subpaths buy nothing — and they would cost
+ *    something real: {@link fastResolveBareSpecifier} only recognizes a
+ *    package ROOT (it looks for `<node_modules>/<specifier>/package.json`),
+ *    so a subpath specifier falls through to exactly the slow
+ *    `createRequire().resolve()` path this restriction exists to avoid.
+ *
+ *  - **Lexicons of THIS build only.** Not "any `@intentius/chant-lexicon-*`
+ *    package on disk", and emphatically not "any bare specifier". A lexicon
+ *    the build did not load is as out of scope as `node:fs`.
+ */
+function activeLexiconPackage(specifier: string, lexiconPackages: ReadonlySet<string>): string | undefined {
+  return lexiconPackages.has(specifier) ? specifier : undefined;
+}
+
+/**
+ * chant #1063 — resolve one named import binding against an active lexicon
+ * package's REAL exports, for {@link buildExternals}.
+ *
+ * The lexicon module is imported (through the session-wide
+ * {@link FoldSession.importCache}, so at most one real `import()` per package
+ * per build) and the requested export read straight off it. That is the same
+ * module object the run path gets — `importModule` is a plain dynamic
+ * `import()` with no cache-busting — so what fold captures here is not a
+ * reconstruction of the lexicon's data but the identical value, down to
+ * object identity for `Azure.ResourceGroupLocation`-style singletons. It is
+ * also the same two-step (resolve path, then import) that
+ * `resolveImportedExport` has always used to reach a lexicon's constructors
+ * and intrinsic functions; the only thing new is that a plain DATA export is
+ * now reachable too.
+ *
+ * Callable exports are deliberately excluded. A lexicon's functions — its
+ * resource classes, composite factories, intrinsic implementations — already
+ * have dedicated resolution paths that know how to INVOKE them
+ * (`resolveResourceEntity`, `resolveCallExpression`, `reviveFoldedValue`), and
+ * binding them as plain identifier values here would widen what folds in ways
+ * this issue neither needs nor measured: none of the references #1063 exists
+ * to unblock (`Azure`, `GCP`, `S3Actions`, gitlab's `CI`) is a function.
+ *
+ * Returns `undefined` — never throws — for a package that isn't an active
+ * lexicon, an export the package doesn't have, a callable export, or an
+ * import that fails. The binding is then simply absent from `externals`,
+ * exactly as before, and `fold()`'s ordinary "unresolved identifier" failure
+ * still fires if the name is actually referenced.
+ */
+async function resolveActiveLexiconExport(
+  binding: ImportBinding,
+  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 mod: Record<string, unknown>;
+  try {
+    mod = await importModuleMemoized(modulePath, session.importCache);
+  } catch {
+    return undefined;
+  }
+
+  if (!(binding.imported in mod)) return undefined;
+  const value = mod[binding.imported];
+  if (typeof value === "function") return undefined;
+  return { value };
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 // Resolution: given the scan + import map, compute the REAL runtime value
 // (Declarable | CompositeInstance) each foldable export would have had if
@@ -946,13 +1102,18 @@ async function resolveLiveValue(node: ts.Expression, ctx: ResolveCtx): Promise<L
  * `isDeclarable`/`isCompositeInstance` value for a top-level export).
  */
 async function resolveCallExpression(node: ts.CallExpression, ctx: ResolveCtx): Promise<unknown> {
+  // chant #1054 — reuses ../fold/subset's `callExpressionMessage` (the SAME
+  // builder `fold()` throws with for a call used as a prop value) rather
+  // than a hand-written "call expression as a value" copy: the two used to
+  // say different things for the identical rejection, which silently broke
+  // any tooling grouping fallback reasons by text.
   if (!ts.isIdentifier(node.expression)) {
-    throw cheapError(`call expression as a value is not foldable: ${node.expression.getText()}(...)`);
+    throw cheapError(callExpressionMessage(node));
   }
   const calleeName = node.expression.text;
   const binding = ctx.imports.get(calleeName);
   if (!binding) {
-    throw cheapError(`call expression as a value is not foldable: ${calleeName}(...)`);
+    throw cheapError(callExpressionMessage(node));
   }
 
   let modulePath: string;
@@ -1114,13 +1275,23 @@ async function resolveSymbolicValue(text: string, ctx: ResolveCtx): Promise<unkn
 }
 
 /**
- * Revive a folded value tree: replace any `{__intrinsic}`/`{__symbol}`
- * envelope with the real value it represents. `insideIntrinsic` tracks
- * whether the CURRENT node is (transitively) one of a `{__intrinsic}`'s own
- * `values` — see the module-doc note above on why `{__attrRef}` is only
- * rejected there, not everywhere.
+ * Revive a folded value tree: replace any
+ * `{__intrinsic}`/`{__helper}`/`{__symbol}` envelope with the real value it
+ * represents.
+ *
+ * `requireLiveRefs` tracks whether the CURRENT node is (transitively) an
+ * argument being handed to a real function that will inspect it — a
+ * `{__intrinsic}`'s own interpolated `values`, or a `{__helper}` call's
+ * arguments (chant #1082). In that position a symbolic `{__attrRef}` envelope
+ * is rejected rather than passed along: the receiving implementation needs a
+ * genuine `AttrRef` instance (`instanceof` checks, `WeakRef` derefs — see
+ * `SubIntrinsic`, and `LexiconOutput`'s constructor in ../lexicon-output.ts),
+ * and handing it a look-alike plain object produces output that is wrong
+ * rather than absent. Everywhere else the envelope is left untouched, because
+ * the serializer's generic walker already understands it — see the module-doc
+ * note above.
  */
-async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntrinsic: boolean): Promise<unknown> {
+async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, requireLiveRefs: boolean): Promise<unknown> {
   if (value === null || typeof value !== "object") return value;
 
   // chant #1020 — a REAL, already-constructed live object reached via
@@ -1135,13 +1306,23 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntr
   // destroying the very identity #1020 exists to preserve. Passed through
   // completely unchanged, exactly like `resolveCallExpression`'s own
   // `live.value` passthrough for a composite-call argument.
-  if (isAttrRefLike(value) || isDeclarable(value) || isCompositeInstance(value)) {
+  // chant #1063 adds the third kind of real object cross-file resolution can
+  // now put here: a live `Intrinsic` instance read off an active lexicon
+  // package (`Azure.ResourceGroupLocation`, `GCP.ProjectId` — see
+  // `resolveActiveLexiconExport`). Same hazard, same fix: the generic walk
+  // below would rebuild it as a plain `{}` copy, dropping the prototype that
+  // carries `toJSON()` and so serializing `{}` where the run path emits
+  // `[resourceGroup().location]`. `isIntrinsic` keys off
+  // `Symbol.for("chant.intrinsic")` (../intrinsic.ts), a GLOBAL symbol, so it
+  // holds across separately-loaded copies of chant-core the way a bare
+  // `instanceof` would not.
+  if (isAttrRefLike(value) || isDeclarable(value) || isCompositeInstance(value) || isIntrinsic(value)) {
     return value;
   }
 
   if (Array.isArray(value)) {
     const revived: unknown[] = [];
-    for (const el of value) revived.push(await reviveFoldedValue(el, ctx, insideIntrinsic));
+    for (const el of value) revived.push(await reviveFoldedValue(el, ctx, requireLiveRefs));
     return revived;
   }
 
@@ -1154,17 +1335,33 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntr
     const intrinsic = value as FoldedIntrinsic;
     const Fn = await resolveImportedExport(intrinsic.__intrinsic, ctx);
     if (typeof Fn !== "function") {
-      throw cheapError(`intrinsic tag "${intrinsic.__intrinsic}" did not resolve to a function`);
+      throw cheapError(`intrinsic "${intrinsic.__intrinsic}" did not resolve to a function`);
     }
-    const revivedValues: unknown[] = [];
-    for (const v of intrinsic.values) revivedValues.push(await reviveFoldedValue(v, ctx, true));
-    return (Fn as (...fnArgs: unknown[]) => unknown)(intrinsic.strings, ...revivedValues);
+    // Two authored forms, one envelope family (../fold/fold.ts's
+    // `FoldedIntrinsic`): the tagged template replays as
+    // `Name(strings, ...values)`, the plain call (chant #1044) as
+    // `Name(...args)`. Both hand their interior to the REAL function the
+    // file itself imported, with `requireLiveRefs` — an intrinsic inspects
+    // what it is given (`SubIntrinsic`'s `instanceof` checks, `Ref`'s
+    // `getLogicalName`), so a look-alike `{__attrRef}` envelope must be
+    // rejected here rather than silently serialized as something else.
+    const revived: unknown[] = [];
+    if ("args" in intrinsic) {
+      for (const a of intrinsic.args) revived.push(await reviveFoldedValue(a, ctx, true));
+      return (Fn as (...fnArgs: unknown[]) => unknown)(...revived);
+    }
+    for (const v of intrinsic.values) revived.push(await reviveFoldedValue(v, ctx, true));
+    return (Fn as (...fnArgs: unknown[]) => unknown)(intrinsic.strings, ...revived);
+  }
+
+  if ("__helper" in value) {
+    return reviveHelperCall(value as FoldedHelperCall, ctx);
   }
 
   if ("__attrRef" in value) {
-    if (insideIntrinsic) {
+    if (requireLiveRefs) {
       throw cheapError(
-        "a same-file resource reference inside a folded intrinsic's interpolation is not foldable yet",
+        "a same-file resource reference passed to a folded intrinsic or authoring helper is not foldable yet",
       );
     }
     return value;
@@ -1178,11 +1375,93 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, insideIntr
 
   const revived: Record<string, unknown> = {};
   for (const [key, v] of Object.entries(value)) {
-    revived[key] = await reviveFoldedValue(v as FoldedValue, ctx, insideIntrinsic);
+    revived[key] = await reviveFoldedValue(v as FoldedValue, ctx, requireLiveRefs);
   }
   return revived;
 }
 
+/**
+ * chant #1082 — the provenance half of the registered-authoring-helper check
+ * (the shape/name half is `fold()`'s, see ../fold/foldable-helpers.ts's module
+ * doc). Being in the allowlist is not permission to invoke whatever the name
+ * happens to be bound to: the name must be bound by THIS FILE'S OWN `import`,
+ * and that import must actually come from chant. Only then is the real
+ * function called, with the folded arguments — the same function the run path
+ * would have called, from the same module the source itself named, so fold
+ * cannot diverge from run by construction.
+ *
+ * Anything short of that throws, which falls the whole file back to run: a
+ * local `function phase(...)`, a `phase` imported from the project's own
+ * helpers, a chant-owned import that turns out not to be a function.
+ */
+async function reviveHelperCall(call: FoldedHelperCall, ctx: ResolveCtx): Promise<unknown> {
+  const name = call.__helper;
+  const binding = ctx.imports.get(name);
+  if (!binding) {
+    throw cheapError(`authoring helper "${name}(...)" is not a resolvable import`);
+  }
+  if (!isChantOwnedHelperBinding(binding, ctx)) {
+    throw cheapError(
+      `"${name}" is imported from "${binding.specifier}", which is not chant's own — ` +
+        `only chant's registered authoring helpers fold as calls`,
+    );
+  }
+
+  const Fn = await resolveImportedExport(name, ctx);
+  if (typeof Fn !== "function") {
+    throw cheapError(`authoring helper "${name}" did not resolve to a function`);
+  }
+
+  // `requireLiveRefs` — a helper receives its arguments as real values and may
+  // inspect them (`output()` derefs the ref's `WeakRef` parent), so a symbolic
+  // `{__attrRef}` envelope is rejected here rather than silently wrapped into
+  // a wrong result. A ref that resolved cross-file to a genuine live `AttrRef`
+  // passes straight through (see `reviveFoldedValue`'s early return).
+  const args: unknown[] = [];
+  for (const arg of call.args) args.push(await reviveFoldedValue(arg, ctx, true));
+  return (Fn as (...fnArgs: unknown[]) => unknown)(...args);
+}
+
+/**
+ * True when `binding` names a helper import chant itself owns: a published
+ * chant package specifier ({@link isChantOwnedSpecifier}), or — for in-repo
+ * and test callers, which import chant-core by relative/absolute path the way
+ * this module's own fixtures do — a specifier that resolves to a file inside
+ * chant-core's own tree.
+ *
+ * The path arm resolves only for a relative/absolute specifier, never a bare
+ * one: resolving an arbitrary bare specifier here would reintroduce the
+ * pathological cold-resolution cost chant#1020 measured (see
+ * {@link fastResolveBareSpecifier}), and a bare specifier chant publishes is
+ * already covered by the text arm.
+ */
+function isChantOwnedHelperBinding(binding: ImportBinding, ctx: ResolveCtx): boolean {
+  if (isChantOwnedSpecifier(binding.specifier)) return true;
+  if (!isProjectFileSpecifier(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-core's own module root — `packages/core/src` in this repo,
+ * `<pkg>/dist` in a published install — derived from THIS module's location.
+ * Pure string arithmetic on `import.meta.url`, no filesystem access at all, so
+ * it is safe in the #1045 sandbox child (which locks reads to an allowlist);
+ * lazy and memoized purely to avoid doing it per call.
+ */
+let chantCoreRootMemo: string | undefined;
+function chantCoreRoot(): string {
+  // .../<root>/discovery/fold-import.ts -> .../<root>
+  chantCoreRootMemo ??= dirname(dirname(fileURLToPath(import.meta.url)));
+  return chantCoreRootMemo;
+}
+
 /** Revive every value in a folded props/attributes object (see {@link reviveFoldedValue}). */
 async function reviveFoldedProps(
   props: { [key: string]: FoldedValue },
@@ -1220,11 +1499,27 @@ async function resolveResourceEntity(
   // real runtime values before constructing the entity. A no-op walk when
   // this file used no registered intrinsics (the overwhelming majority of
   // cases today).
-  let props: Record<string, unknown>;
-  let attributes: Record<string, unknown> | undefined;
+  //
+  // chant #1082 — when `spec.args` is present the constructor's argument list
+  // isn't the classic `(props)`/`(props, attributes)` shape (AWS's `Parameter`
+  // is `(type, props)`), so revive the whole list and spread it below instead
+  // of reviving `spec.props`, which in that case is only a view onto one of
+  // its entries and would be double-counted.
+  let ctorArgs: unknown[];
   try {
-    props = await reviveFoldedProps(spec.props, ctx);
-    attributes = spec.attributes ? await reviveFoldedProps(spec.attributes, ctx) : undefined;
+    if (spec.args) {
+      ctorArgs = [];
+      for (const arg of spec.args) ctorArgs.push(await reviveFoldedValue(arg, ctx, false));
+    } else {
+      const props = await reviveFoldedProps(spec.props, ctx);
+      // The runtime constructor's optional second argument (`attributes` —
+      // CFN's DependsOn/Condition/DeletionPolicy/…, see createResource in
+      // ../runtime.ts) is only present in `spec` when the source actually
+      // passed one (see foldResource in ../fold/fold.ts). Passing `undefined`
+      // when it's absent matches the run path's own default
+      // (`attributes ?? {}` inside the constructor).
+      ctorArgs = [props, spec.attributes ? await reviveFoldedProps(spec.attributes, ctx) : undefined];
+    }
   } catch (err) {
     return {
       ok: false,
@@ -1264,17 +1559,10 @@ async function resolveResourceEntity(
     return { ok: false, reason: `"${binding.imported}" from "${binding.specifier}" is not a constructor` };
   }
 
-  // The runtime constructor's optional second argument (`attributes` —
-  // CFN's DependsOn/Condition/DeletionPolicy/…, see createResource in
-  // ../runtime.ts) is only present in `spec` when the source actually passed
-  // one (see foldResource in ../fold/fold.ts). Passing `undefined` when it's
-  // absent matches the run path's own default (`attributes ?? {}` inside the
-  // constructor).
-  const ResourceCtor = Ctor as new (
-    props: Record<string, unknown>,
-    attributes?: Record<string, unknown>,
-  ) => Declarable;
-  const entity = new ResourceCtor(props, attributes);
+  // Constructed with exactly the arguments the source wrote (see the revival
+  // block above for how `ctorArgs` was built for each of the two shapes).
+  const ResourceCtor = Ctor as new (...ctorArguments: unknown[]) => Declarable;
+  const entity = new ResourceCtor(...ctorArgs);
   return { ok: true, entity };
 }
 
@@ -1310,6 +1598,18 @@ function describeFoldFailure(err: unknown, ctx: ResolveCtx): string {
   return err.message;
 }
 
+/**
+ * chant #1054 — a short, single-line label for a destructured export's
+ * source expression, for a fold fallback reason: the callee plus `(...)`
+ * for the common composite-call source (`GkeCluster(...)`), or a brief,
+ * bounded rendering of whatever else it is otherwise. Never the source's own
+ * `getText()` — for a real composite call that's the entire multi-line
+ * argument list.
+ */
+function describeDestructureSource(node: ts.Expression): string {
+  return ts.isCallExpression(node) ? `${briefNodeText(node.expression)}(...)` : briefNodeText(node);
+}
+
 /** Build a located `FoldError`'s formatted "line:col - message" string anchored at `node` — for a cross-file failure detected here in fold-import.ts (an import cycle, a name genuinely absent from the target module's exports) rather than inside `fold()` itself. */
 function locatedMessage(node: ts.Node, message: string): string {
   const { line, column } = locate(node);
@@ -1394,9 +1694,11 @@ async function buildExternals(
   imports: Map<string, ImportBinding>,
   namespaceImports: Map<string, NamespaceImportBinding>,
   session: FoldSession,
-): Promise<{ externals: Map<string, unknown>; failures: Map<string, string> }> {
+): Promise<{ externals: Map<string, unknown>; failures: Map<string, string>; liveSources: Set<string> }> {
   const externals = new Map<string, unknown>();
   const failures = new Map<string, string>();
+  // chant #1044 — see `FoldFileResult.liveSources`.
+  const liveSources = new Set<string>();
 
   for (const [localName, binding] of imports) {
     // chant #1064 — a named `params` import that resolves to chant-core's own
@@ -1450,10 +1752,36 @@ async function buildExternals(
     }
 
     if (!isProjectFileSpecifier(binding.specifier)) {
-      // Every other bare specifier (a lexicon/vendor package) is left alone
-      // here, exactly as before #1064: it resolves lazily, through the
-      // pre-existing `importModule` mechanism, only once a constructor/
-      // composite-factory/intrinsic tag actually consumes it.
+      // chant #1063 — a bare specifier naming one of THIS BUILD's active
+      // lexicon packages resolves to that package's real export, so a plain
+      // data export a lexicon publishes (`Azure`/`GCP`'s pseudo-parameter
+      // namespaces, AWS's `S3Actions`, gitlab's `CI`) is an ordinary
+      // identifier value here rather than fold's most common remaining
+      // "unresolved identifier" failure. See
+      // {@link resolveActiveLexiconExport} for the allowlist, the no-cold-
+      // resolution rule, and why callable exports stay out.
+      //
+      // No `liveSources` edge is recorded for what comes back, unlike the
+      // project-file case just below. `liveSources` (chant #1044) exists so
+      // that a folded file which captured ANOTHER FILE's objects is
+      // invalidated when that file is forced back to run — a fold/run
+      // disagreement about identity. A lexicon package has no such duality:
+      // it is not a discovered source file, `planFoldTaint` never considers
+      // it (it filters to the discovered `files` set), it never falls back to
+      // run, and both paths reach it through the identical un-cache-busted
+      // `import()` of the identical resolved path — so the object fold
+      // captures IS the object the run path holds. There is nothing for the
+      // two sides to disagree about, hence nothing to taint.
+      const lexiconExport = await resolveActiveLexiconExport(binding, file, session);
+      if (lexiconExport) {
+        externals.set(localName, lexiconExport.value);
+        continue;
+      }
+      // Every other bare specifier (a non-lexicon vendor package, a lexicon
+      // this build didn't load) is left alone here, exactly as before #1064:
+      // it resolves lazily, through the pre-existing `importModule`
+      // mechanism, only once a constructor/composite-factory/intrinsic tag
+      // actually consumes it.
       continue;
     }
     let targetPath: string;
@@ -1468,7 +1796,9 @@ async function buildExternals(
       continue;
     }
     if (result.exportedValues.has(binding.imported)) {
-      externals.set(localName, result.exportedValues.get(binding.imported));
+      const value = result.exportedValues.get(binding.imported);
+      externals.set(localName, value);
+      if (hasObjectIdentity(value)) liveSources.add(targetPath);
     } else {
       failures.set(
         localName,
@@ -1494,9 +1824,28 @@ async function buildExternals(
     // access on it (`ns.someExport`) is then just an ordinary bracket index,
     // exactly like on a real composite instance (see `isIndexableObject`).
     externals.set(localName, Object.fromEntries(result.exportedValues));
+    for (const value of result.exportedValues.values()) {
+      if (hasObjectIdentity(value)) {
+        liveSources.add(targetPath);
+        break;
+      }
+    }
   }
 
-  return { externals, failures };
+  return { externals, failures, liveSources };
+}
+
+/**
+ * True when `value` is something whose IDENTITY matters across the
+ * fold/run boundary — any object or function, as opposed to a primitive
+ * (chant #1044). Deliberately coarse: an object that merely *contains* a
+ * `Declarable` is as identity-bearing as the Declarable itself, and cheaply
+ * treating every object as such avoids a deep walk whose only payoff would
+ * be keeping a handful of extra files folded inside an entry that already
+ * falls back. See {@link FoldFileResult.liveSources}.
+ */
+function hasObjectIdentity(value: unknown): boolean {
+  return value !== null && (typeof value === "object" || typeof value === "function");
 }
 
 /**
@@ -1540,7 +1889,7 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
     if (scan.declarators.length === 0) return { ok: false, reason: "no foldable resource exports" };
 
     const collected = collectImports(sourceFile);
-    const { externals, failures } = await buildExternals(file, collected.named, collected.namespaces, session);
+    const { externals, failures, liveSources } = await buildExternals(file, collected.named, collected.namespaces, session);
 
     const ctx: ResolveCtx = {
       file,
@@ -1580,18 +1929,26 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
 
       if (decl.kind === "destructure") {
         let value: unknown;
+        // chant #1054 — identify the destructured export by its BINDING
+        // NAMES and the source's callee (`"cluster, nodePool" (destructured
+        // from GkeCluster(...))`), never `decl.node.getText()`: for a real
+        // composite call that's the entire multi-line source, which buries
+        // the actual error after it and breaks any line-oriented consumer of
+        // `[fold:run]` output.
+        const boundNames = decl.elements.map((el) => el.bindingName).join(", ");
+        const source = describeDestructureSource(decl.node);
         try {
           value = (await resolveDeclaratorValue(decl.node, ctx)).value;
         } catch (err) {
           return {
             ok: false,
-            reason: `destructured export from "${decl.node.getText()}" is not foldable: ${describeFoldFailure(err, ctx)}`,
+            reason: `"${boundNames}" (destructured from ${source}) is not foldable: ${describeFoldFailure(err, ctx)}`,
           };
         }
         if (!isIndexableObject(value)) {
           return {
             ok: false,
-            reason: `destructured export from "${decl.node.getText()}" is not foldable (not a composite call or object)`,
+            reason: `"${boundNames}" (destructured from ${source}) is not foldable: not a composite call or object`,
           };
         }
         for (const { propKey, bindingName } of decl.elements) {
@@ -1644,11 +2001,16 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
             reason: locatedMessage(decl.specifierNode, `"${imported}" is not exported by "${decl.specifier}"`),
           };
         }
-        applyResolvedValue(exportedName, result.exportedValues.get(imported), entities, exportedValues);
+        const value = result.exportedValues.get(imported);
+        // chant #1044 — a re-export hands another file's OBJECT straight
+        // through under this file's name, so it is a live-identity edge
+        // exactly like an imported binding is (see `liveSources`).
+        if (hasObjectIdentity(value)) liveSources.add(targetPath);
+        applyResolvedValue(exportedName, value, entities, exportedValues);
       }
     }
 
-    return { ok: true, entities, exportedValues };
+    return { ok: true, entities, exportedValues, liveSources };
   } catch (err) {
     // Any unexpected failure degrades to "fall back to run" rather than
     // taking discovery down with it — fold is opt-in, not a new failure mode.
@@ -1725,6 +2087,21 @@ export async function tryFoldFile(
  * 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
@@ -1740,6 +2117,7 @@ export async function tryFoldFile(
 export async function planFoldTaint(
   files: readonly string[],
   wouldFold: ReadonlyMap<string, boolean>,
+  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
 ): Promise<Set<string>> {
   const fileSet = new Set(files);
 
@@ -1789,6 +2167,22 @@ export async function planFoldTaint(
     edges.set(file, targets);
   }
 
+  // chant #1044 — reverse edges: consumed-file -> the folded files that
+  // captured its objects. Same taint set, same fixpoint walk; see this
+  // function's doc for the crash this closes.
+  for (const [consumer, sources] of liveSources ?? []) {
+    if (!fileSet.has(consumer)) continue;
+    for (const source of sources) {
+      if (!fileSet.has(source)) continue;
+      let back = edges.get(source);
+      if (!back) {
+        back = new Set<string>();
+        edges.set(source, back);
+      }
+      back.add(consumer);
+    }
+  }
+
   const tainted = new Set<string>(files.filter((f) => wouldFold.get(f) !== true));
   const queue = [...tainted];
   while (queue.length > 0) {