@intentius/chant 0.49.0 → 0.50.0

package/src/components/verbs/sign.test.ts

@@ -122,6 +122,25 @@ describe("buildProvenanceStatement — SLSA in-toto statement from #614 provenan
       }),
     ).toThrow(SignTargetNotDigestError);
   });
+
+  it("reserved parameter keys win over caller-supplied collisions (#1943)", () => {
+    const statement = buildProvenanceStatement({
+      imageRef: DIGEST_REF,
+      provenance: { sourceRef: "abc123def", artifactDigest: DIGEST_REF.split("@")[1]! },
+      builderId: "builder",
+      externalParameters: { sourceRef: "spoofed", agent: "reviewer" },
+      internalParameters: { artifactDigest: "spoofed", spriteId: "s-1" },
+    });
+
+    expect(statement.predicate.buildDefinition.externalParameters).toEqual({
+      sourceRef: "abc123def",
+      agent: "reviewer",
+    });
+    expect(statement.predicate.buildDefinition.internalParameters).toEqual({
+      artifactDigest: DIGEST_REF.split("@")[1]!,
+      spriteId: "s-1",
+    });
+  });
 });
 
 describe("attest-provenance — keyless cosign attest (#622)", () => {

package/src/components/verbs/sign.ts

@@ -40,6 +40,19 @@
  * `requireTool` throws `ToolNotAvailableError` with an actionable message if
  * `cosign` is absent, and no test here ever spawns a real process or talks
  * to Rekor/Fulcio.
+ *
+ * **#1943 extension (`run-agent` interop).** `BuildProvenanceStatementInput`
+ * gained two optional merge fields, `externalParameters`/`internalParameters`
+ * — additive only, every existing call site's statement is byte-identical
+ * without them. `run-agent` (./run-agent.ts's `buildRunAgentProvenanceStatement`)
+ * is the first caller to use them, plus `buildType` (already overridable,
+ * unchanged here) set to a `run-agent`-specific recipe URI. `predicateType`
+ * stays `"https://slsa.dev/provenance/v1"` for every caller, `run-agent`
+ * included — see ./run-agent.ts's own doc comment ("Attestation interop")
+ * for why a turn is attested as an SLSA-shaped provenance predicate rather
+ * than under a minted `run-agent`-specific `predicateType`, and why that
+ * decision means `sign`/`attestProvenance`/`../verbs/verify.ts` needed zero
+ * changes to their `cosign` invocations to attest/verify a turn.
  */
 
 import type { Capability } from "../capability";
@@ -235,6 +248,23 @@ export interface BuildProvenanceStatementInput {
   finishedOn?: string;
   /** CI invocation/run id, when available (e.g. a GitHub Actions run id). */
   invocationId?: string;
+  /**
+   * Additional `buildDefinition.externalParameters` merged in alongside the
+   * `{ sourceRef }` default (#1943: `run-agent`'s provenance statement folds
+   * in the fountain-supplied *declared* facts — the agent selector today,
+   * more once fountain `Agent` resolution lands — without run-agent needing
+   * its own predicate builder). `sourceRef` is reserved by this function: a
+   * caller-supplied `sourceRef` is overridden, never signed; any other key
+   * name is the caller's choice.
+   */
+  externalParameters?: Record<string, unknown>;
+  /**
+   * Additional `buildDefinition.internalParameters` merged in alongside the
+   * `{ artifactDigest }` default (#1943: `run-agent` folds in what actually
+   * happened — sprite id, checkpoint id, turn status/exit code — the
+   * *imperative* facts a build's `internalParameters` are for).
+   */
+  internalParameters?: Record<string, unknown>;
 }
 
 const DEFAULT_BUILD_TYPE = "https://chant.dev/build-archive/v1";
@@ -263,8 +293,10 @@ export function buildProvenanceStatement(input: BuildProvenanceStatementInput):
     predicate: {
       buildDefinition: {
         buildType: input.buildType ?? DEFAULT_BUILD_TYPE,
-        externalParameters: { sourceRef: input.provenance.sourceRef },
-        internalParameters: { artifactDigest: input.provenance.artifactDigest },
+        // Reserved keys spread LAST so a caller-supplied key can never clobber
+        // them into a signed statement that disagrees with resolvedDependencies.
+        externalParameters: { ...input.externalParameters, sourceRef: input.provenance.sourceRef },
+        internalParameters: { ...input.internalParameters, artifactDigest: input.provenance.artifactDigest },
         resolvedDependencies: [{ uri: input.provenance.sourceRef, digest: { sha256: digest } }],
       },
       runDetails: {

package/src/composite.ts

@@ -1,5 +1,5 @@
 import { isDeclarable, type Declarable } from "./declarable";
-import { setProvenance } from "./provenance";
+import { setPathProvenance, setProvenance } from "./provenance";
 
 /**
  * Marker symbol for Composite type identification.
@@ -150,10 +150,16 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
 /**
  * Expands a CompositeInstance into a flat Map of prefixed entity names to Declarables.
  * Handles nested composites recursively.
+ *
+ * @param instanceName - The composite INSTANCE every member belongs to (chant
+ *   #1443), which at the top call is the export name and stays that name
+ *   through nesting — `prefix` grows per member and is not an instance
+ *   identity. Defaults to `prefix` so the top call needs no extra argument.
  */
 export function expandComposite(
   prefix: string,
   instance: CompositeInstance,
+  instanceName: string = prefix,
 ): Map<string, Declarable> {
   const result = new Map<string, Declarable>();
   const shared = (instance as unknown as Record<symbol, unknown>)[SHARED_PROPS] as Record<string, unknown> | undefined;
@@ -164,7 +170,7 @@ export function expandComposite(
     const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
 
     if (isCompositeInstance(member)) {
-      const nested = expandComposite(fullName, member);
+      const nested = expandComposite(fullName, member, instanceName);
       for (const [nestedName, nestedEntity] of nested) {
         // Inner composite already stamped; `??=` keeps the most-specific one.
         if (compositeName) setProvenance(nestedEntity, { composite: compositeName });
@@ -176,6 +182,15 @@ export function expandComposite(
     }
   }
 
+  // Whole-entity origin (chant #1443). Recorded after the loop so a nested
+  // member carries its INNER composite here — the recursive call above already
+  // ran and `setPathProvenance` keeps the first writer.
+  if (compositeName) {
+    for (const entity of result.values()) {
+      setPathProvenance(entity, "", { kind: "composite", composite: compositeName, instance: instanceName });
+    }
+  }
+
   if (shared) {
     for (const entity of result.values()) {
       if ("props" in entity) {
@@ -211,6 +226,20 @@ export function expandComposite(
         Object.defineProperty(entity, "props", {
           value: merged, enumerable: false, configurable: true,
         });
+        // A key the member did not set is the propagating instance's alone, so
+        // it is attributable exactly (chant #1443). A key both sides wrote —
+        // an override, or the array concatenation above — is left to the
+        // whole-entity origin rather than credited to one contributor.
+        if (compositeName) {
+          for (const k of Object.keys(shared)) {
+            if (shared[k] === undefined || existing[k] !== undefined) continue;
+            setPathProvenance(entity, k, {
+              kind: "composite",
+              composite: compositeName,
+              instance: instanceName,
+            });
+          }
+        }
       }
     }
   }

package/src/discovery/collect.ts

@@ -34,6 +34,15 @@ function stackPrefix(file: string, buildRoot: string | undefined): string {
   return segments.map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
 }
 
+/**
+ * Whole-entity origin for a declarable a file exported directly (chant #1443).
+ * A composite's members get theirs from `expandComposite`, which knows the
+ * composite and the instance; a direct export has nothing between the source
+ * file and the resource. Merged key-by-key, so a path the fold path already
+ * attributed to a build parameter is not overwritten.
+ */
+const AUTHORED_ROOT: EntityProvenance["paths"] = { "": { kind: "authored" } };
+
 /** One entity to be placed into the map, produced by {@link enumerateEntries}. */
 interface PendingEntry {
   /** The un-disambiguated map key this entity would take (export name, indexed
@@ -73,12 +82,12 @@ function enumerateEntries(
     for (const [rawName, value] of sortedExports) {
       const name = exportKey(rawName, file);
       if (isDeclarable(value)) {
-        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file } });
+        entries.push({ bareKey: name, value, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
       } else if (Array.isArray(value)) {
         for (let i = 0; i < value.length; i++) {
           const item = value[i];
           if (isDeclarable(item)) {
-            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file } });
+            entries.push({ bareKey: `${name}_${i}`, value: item, file, provenance: { sourceFile: file, paths: AUTHORED_ROOT } });
           } else if (isCompositeInstance(item)) {
             const indexedName = `${name}_${i}`;
             for (const [expandedName, entity] of expandComposite(indexedName, item)) {

package/src/discovery/fold-import.test.ts

@@ -9,6 +9,7 @@ import { isCompositeInstance } from "../composite";
 import { isAttrRefLike } from "../utils";
 import { isIntrinsic } from "../intrinsic";
 import { params as sharedParams } from "../params";
+import { getPathProvenance } from "../provenance";
 import type { AttrRef } from "../attrref";
 import type { IntrinsicDef } from "../lexicon";
 
@@ -1153,6 +1154,59 @@ describe("tryFoldFile — build-time parameters (chant #1064)", () => {
 
     setBuildParams({});
   });
+
+  // chant #1443 — fold substitutes `params.<name>` away, so the emitted value
+  // is a literal and unattributable. These record which parameters the
+  // AUTHORED expression read, before that happens.
+  test("a folded resource records which build parameters each of its paths reads", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        const suffix = params.env === "prod" ? "" : "-dev";
+        export const bucket = new Bucket({
+          name: \`assets\${suffix}\`,
+          fixed: "never-moves",
+          nested: { region: params.region },
+        });
+      `,
+    );
+
+    const session = createFoldSession([], { env: "prod", region: "us-east-1" });
+    const result = await tryFoldFile(file, [], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    expect(getPathProvenance(entity as object)).toEqual({
+      name: { kind: "build-param", params: ["env"] },
+      "nested.region": { kind: "build-param", params: ["region"] },
+    });
+  });
+
+  test("a folded resource that reads no parameter records no path origins", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const other = params.env;
+        export const bucket = new Bucket({ name: "static" });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [], createFoldSession([], { env: "prod" }));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const entity = result.entities.find(([name]) => name === "bucket")![1];
+    expect(getPathProvenance(entity as object)).toBeUndefined();
+  });
 });
 
 /**

package/src/discovery/fold-import.ts

@@ -22,6 +22,7 @@ import {
   type FoldedIntrinsic,
   type FoldedHelperCall,
   type SymbolicValue,
+  type FoldedCompositeStepCall,
 } from "../fold/fold";
 import { isChantOwnedSpecifier, isFoldableHelperName } from "../fold/foldable-helpers";
 import {
@@ -37,7 +38,9 @@ import {
   SUPPORTED_UNARY_OPERATORS,
 } from "../fold/subset";
 import { importModule } from "./import";
-import type { IntrinsicDef } from "../lexicon";
+import { collectParamDependencies } from "./param-deps";
+import { setPathProvenance } from "../provenance";
+import { intrinsicCallFoldsEagerly, type IntrinsicDef } from "../lexicon";
 import type { BuildParamValue } from "../build-params";
 
 /**
@@ -1096,19 +1099,25 @@ function activeLexiconPackage(specifier: string, lexiconPackages: ReadonlySet<st
  * 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
+ * Callable exports are otherwise 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.
+ * binding an arbitrary one as a plain identifier value here would widen what
+ * folds in unmeasured ways. The one exception (chant #1966) is a function its
+ * lexicon registered with {@link IntrinsicDef.foldsEagerly} — the same
+ * per-name, lexicon-declared opt-in `foldsAsCall` is for an intrinsic's
+ * envelope-and-revive form, admitting this one because `fold()`
+ * (../fold/fold.ts) needs to CALL it eagerly — synchronously, before
+ * revival — to support a lexicon's own string-building helpers used inline
+ * (`matrix("os").toString()`, `` `${inputs("x")}` ``), where an envelope
+ * would still be a plain object when the enclosing template folds.
  *
  * 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.
+ * lexicon, an export the package doesn't have, a non-admitted 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,
@@ -1133,7 +1142,10 @@ async function resolveActiveLexiconExport(
 
   if (!(binding.imported in mod)) return undefined;
   const value = mod[binding.imported];
-  if (typeof value === "function") return undefined;
+  if (typeof value === "function") {
+    const eager = session.intrinsics.some((i) => i.name === binding.imported && intrinsicCallFoldsEagerly(i));
+    if (!eager) return undefined;
+  }
   return { value };
 }
 
@@ -1415,19 +1427,19 @@ async function resolveImportedCall(
 }
 
 /**
- * Arm 2 — import the module the callee came from and call it, in this process.
- * Unchanged from #1022 in both behavior and ORDER (refusal, resolve, import,
- * callable check, arguments, call); #1023 only factored it out so the
- * interpretation arm above can fall back into it.
- *
- * @param args - Already-evaluated arguments, when the caller has them.
+ * Arm 2 — import the module the callee came from and call it, in this
+ * process, given ALREADY-RESOLVED argument values. Factored out of
+ * {@link invokeImportedCallee} (chant #1174) so a caller with no raw
+ * `ts.CallExpression` node — {@link resolveCompositeCall}, the nested-value
+ * counterpart to {@link resolveCallExpression} — can reach the identical
+ * refusal/resolve/import/callable-check/call sequence #1022 established,
+ * without inventing a second copy of it.
  */
-async function invokeImportedCallee(
-  node: ts.CallExpression,
+async function invokeResolvedCallee(
   calleeName: string,
   binding: ImportBinding,
   ctx: ResolveCtx,
-  args?: readonly unknown[],
+  args: readonly unknown[],
 ): Promise<unknown> {
   // 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
@@ -1473,12 +1485,67 @@ async function invokeImportedCallee(
     throw cheapError(`"${binding.imported}" from "${binding.specifier}" is not a function`);
   }
 
-  const callArgs = args ?? (await resolveCallArguments(node, calleeName, ctx));
-
   executionCounts.factoryInvocations += 1;
   if (isProjectFileSpecifier(binding.specifier)) executionCounts.projectFactoryInvocations += 1;
 
-  return (Fn as (...fnArgs: unknown[]) => unknown)(...callArgs);
+  return (Fn as (...fnArgs: unknown[]) => unknown)(...args);
+}
+
+/**
+ * Arm 2's original entry point — a raw call-expression node in hand. Resolves
+ * arguments (unless the caller already has them) and delegates to
+ * {@link invokeResolvedCallee}. Unchanged from #1022 in both behavior and
+ * ORDER (refusal, resolve, import, callable check, arguments, call); #1023
+ * factored the body out once already, #1174 a second time.
+ *
+ * @param args - Already-evaluated arguments, when the caller has them.
+ */
+async function invokeImportedCallee(
+  node: ts.CallExpression,
+  calleeName: string,
+  binding: ImportBinding,
+  ctx: ResolveCtx,
+  args?: readonly unknown[],
+): Promise<unknown> {
+  const callArgs = args ?? (await resolveCallArguments(node, calleeName, ctx));
+  return invokeResolvedCallee(calleeName, binding, ctx, callArgs);
+}
+
+/**
+ * Resolve a composite-factory call used as a NESTED value — chant #1174's
+ * `<Identifier>(...).step` idiom ({@link FoldedCompositeStepCall}) — given
+ * its callee NAME and already-REVIVED argument values. The nested-value
+ * counterpart to {@link resolveCallExpression}, which the top-level
+ * declarator path (`export const x = Checkout({...})`) already used: the
+ * raw `ts.CallExpression` node isn't needed here because
+ * {@link resolveInterpretableFactory} only needs the import `binding`, and
+ * {@link interpretCompositeFactory}/{@link invokeResolvedCallee} only need
+ * the resolved argument values — which `fold()`'s envelope already folded
+ * and {@link reviveFoldedValue} has already revived by the time this runs.
+ *
+ * Same two arms, same order, as the top-level path: interpret a project-file
+ * registered `Composite` (chant #1023) when its body qualifies, otherwise
+ * import and invoke for real — which is the arm every lexicon-package
+ * composite (`Checkout`, `SetupNode`, …) always takes, exactly as it does
+ * today for a top-level `export const x = Checkout({...})`. An unbound
+ * callee name throws the same "function call as a value" message `fold()`
+ * itself would have, for a caller with no `FoldedCompositeStepCall` special
+ * case to fall into.
+ */
+async function resolveCompositeCall(calleeName: string, args: readonly unknown[], ctx: ResolveCtx): Promise<unknown> {
+  const binding = ctx.imports.get(calleeName);
+  if (!binding) throw cheapError(`unresolved identifier: ${calleeName}`);
+
+  const factory = await resolveInterpretableFactory(binding, ctx);
+  if (factory) {
+    const interpreted = await interpretCompositeFactory(factory, args, ctx);
+    if (interpreted) return interpreted.value;
+    // Declined — falls through to arm 2 with the SAME arguments, so a nested
+    // composite-call argument (or a live cross-file reference) is not
+    // resolved a second time. Identical discipline to `resolveImportedCall`.
+  }
+
+  return invokeResolvedCallee(calleeName, binding, ctx, args);
 }
 
 /**
@@ -2502,6 +2569,24 @@ async function reviveFoldedValue(value: FoldedValue, ctx: ResolveCtx, requireLiv
     return reviveHelperCall(value as FoldedHelperCall, ctx);
   }
 
+  if ("__compositeStep" in value) {
+    // chant #1174 — `<Identifier>(...).step`, see {@link FoldedCompositeStepCall}.
+    // Arguments revive with `requireLiveRefs: false` — the same rule
+    // `resolveCallArguments` applies to a NON-helper callee's arguments
+    // (a composite factory stores its props, it doesn't inspect them the way
+    // an intrinsic/helper does), so a `{__attrRef}` among them stays the
+    // symbolic envelope the composite's own resource construction resolves
+    // by name, exactly as a top-level resource's props would.
+    const call = value as FoldedCompositeStepCall;
+    const revivedArgs: unknown[] = [];
+    for (const a of call.args) revivedArgs.push(await reviveFoldedValue(a, ctx, false));
+    const result = await resolveCompositeCall(call.__compositeStep, revivedArgs, ctx);
+    if (!isIndexableObject(result)) {
+      throw cheapError(`composite call \`${call.__compositeStep}(...)\` did not resolve to an object with a "step" member`);
+    }
+    return (result as Record<string, unknown>).step;
+  }
+
   if ("__attrRef" in value) {
     if (requireLiveRefs) {
       throw cheapError(
@@ -2889,6 +2974,46 @@ async function constructFoldedResource(
  * performs unconditionally for the same file, and through the same
  * already-memoized `importModule`.
  */
+/**
+ * The local names this file bound to the build's parameter object (chant
+ * #1443). Object identity against {@link FoldSession.buildParams}, which
+ * `buildExternals` substituted directly, so an unrelated import that happens to
+ * be called `params` is not mistaken for it.
+ */
+function paramLocalNames(ctx: ResolveCtx): Set<string> {
+  const out = new Set<string>();
+  const buildParams = ctx.session.buildParams;
+  if (!buildParams) return out;
+  for (const [name, value] of ctx.externals) {
+    if (value === buildParams) out.add(name);
+  }
+  return out;
+}
+
+/**
+ * chant #1443 — record which build parameters each of a resource's authored
+ * property expressions reads, before fold substitutes them away. Best-effort
+ * and additive: a file with no `params` import, or a constructor called with no
+ * object literal, records nothing.
+ */
+function stampParamDependencies(entity: unknown, node: ts.NewExpression, ctx: ResolveCtx): void {
+  if (typeof entity !== "object" || entity === null) return;
+  const paramLocals = paramLocalNames(ctx);
+  if (paramLocals.size === 0) return;
+  // The same argument `foldResource` treats as props: the first object literal.
+  let propsArg: ts.ObjectLiteralExpression | undefined;
+  for (const argument of node.arguments ?? []) {
+    if (ts.isObjectLiteralExpression(argument)) {
+      propsArg = argument;
+      break;
+    }
+  }
+  if (!propsArg) return;
+  for (const [path, origin] of Object.entries(collectParamDependencies(propsArg, ctx.consts, paramLocals))) {
+    setPathProvenance(entity, path, origin);
+  }
+}
+
 async function preresolveResourceConsts(ctx: ResolveCtx): Promise<Map<ts.Expression, unknown>> {
   const built = new Map<ts.Expression, unknown>();
   for (const [name, initializer] of ctx.consts) {
@@ -2896,6 +3021,7 @@ async function preresolveResourceConsts(ctx: ResolveCtx): Promise<Map<ts.Express
     try {
       const spec = foldResource(initializer, ctx.consts, ctx.intrinsics, ctx.externals);
       const instance = await constructFoldedResource(spec, ctx, false);
+      stampParamDependencies(instance, initializer, ctx);
       built.set(initializer, instance);
       ctx.externals.set(name, instance);
     } catch {
@@ -2933,6 +3059,7 @@ async function resolveResourceEntity(
 
   try {
     const entity = (await instantiateFoldedResource(spec.__resource, ctorArgs, ctx, ` for "${name}"`)) as Declarable;
+    stampParamDependencies(entity, node, ctx);
     return { ok: true, entity };
   } catch (err) {
     return { ok: false, reason: err instanceof Error ? err.message : String(err) };
@@ -3552,22 +3679,21 @@ export async function tryFoldFile(
  * so the exact same forced-taint safety net still applies to that remaining
  * boundary, unchanged.
  */
-export async function planFoldTaint(
-  files: readonly string[],
-  wouldFold: ReadonlyMap<string, boolean>,
-  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
-): Promise<Set<string>> {
+/**
+ * file -> set of OTHER files in `files` that it relatively imports OR
+ * re-exports from, regardless of that file's own fold outcome. Extracted
+ * from {@link planFoldTaint} (chant #1083) so a second consumer — the fold
+ * blocker dominator ranking (`./fold-rank.ts`) — can walk the exact same
+ * project-file edges instead of re-parsing every file with its own
+ * specifier-resolution logic. chant #1020 — this counts a namespace import
+ * (`import * as ns from "./x"`, previously skipped — see `collectImports`)
+ * and a re-export (`export { x } from "./y"`, which `collectImports` never
+ * saw at all, since it only looks at `import` declarations): both are real
+ * cross-file value dependencies fold's own resolution follows, so both need
+ * the same edge an ordinary named import already gets.
+ */
+export async function buildProjectImportEdges(files: readonly string[]): Promise<Map<string, Set<string>>> {
   const fileSet = new Set(files);
-
-  // file -> set of OTHER discovered files it relatively imports OR re-exports
-  // from, regardless of that file's own fold outcome (taint needs the full
-  // edge set to propagate transitively). chant #1020 — this now ALSO counts
-  // a namespace import (`import * as ns from "./x"`, previously skipped —
-  // see `collectImports`) and a re-export (`export { x } from "./y"`, which
-  // `collectImports` never saw at all, since it only looks at `import`
-  // declarations): both are real cross-file value dependencies my own new
-  // resolution follows, so both need the same identity guarantee an
-  // ordinary named import already got.
   const edges = new Map<string, Set<string>>();
   for (const file of files) {
     const targets = new Set<string>();
@@ -3600,10 +3726,24 @@ export async function planFoldTaint(
     } catch {
       // Unreadable/unparseable — no edges contributed; tryFoldFile's own
       // top-level catch already turns this into a "run" decision for the
-      // file itself, which is enough to seed it as tainted below.
+      // file itself, which is enough to seed it as tainted below (or, for
+      // the dominator ranking, leaves it a childless node).
     }
     edges.set(file, targets);
   }
+  return edges;
+}
+
+export async function planFoldTaint(
+  files: readonly string[],
+  wouldFold: ReadonlyMap<string, boolean>,
+  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
+): Promise<Set<string>> {
+  const fileSet = new Set(files);
+
+  // file -> set of OTHER discovered files it relatively imports OR re-exports
+  // from — see {@link buildProjectImportEdges}.
+  const edges = await buildProjectImportEdges(files);
 
   // chant #1044 — reverse edges: consumed-file -> the folded files that
   // captured its objects. Same taint set, same fixpoint walk; see this