@intentius/chant 0.19.1 → 0.21.0

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

@@ -0,0 +1,1598 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, writeFile, rm } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { tryFoldFile, createFoldSession } from "./fold-import";
+import { isDeclarable } from "../declarable";
+import { isCompositeInstance } from "../composite";
+import { isAttrRefLike } from "../utils";
+import { params as sharedParams } from "../params";
+import type { AttrRef } from "../attrref";
+import type { IntrinsicDef } from "../lexicon";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+/** Absolute path to `packages/core/src/runtime.ts` — the real `createResource`
+ * factory, imported by fixture files below exactly as a lexicon package
+ * would be imported by real chant source. */
+const runtimePath = resolve(thisDir, "../runtime");
+/** Absolute path to `packages/core/src/composite.ts` — the real `Composite`
+ * factory, used to build a genuine composite fixture. */
+const compositePath = resolve(thisDir, "../composite");
+/** Absolute path to `packages/core/src/intrinsic.ts` — the real `Intrinsic`
+ * marker/interface every lexicon's own intrinsic classes (AWS's `Sub`,
+ * gitlab's `reference`, …) implement. Used below to build a tagged-template
+ * intrinsic fixture that is structurally identical to a real lexicon's,
+ * not a simplified stand-in. */
+const intrinsicPath = resolve(thisDir, "../intrinsic");
+/** Absolute path to `packages/core/src/params.ts` — chant #1064's build-time-parameters
+ * runtime module. A real project imports this as the bare specifier
+ * "@intentius/chant/params"; fixture files below use the absolute path instead
+ * (same convention as `runtimePath` etc. above), but {@link buildExternals}'s
+ * recognition is specifier-shape-agnostic — see fold-import.ts's own comment —
+ * so this exercises the identical code path a real bare import would take. */
+const paramsPath = resolve(thisDir, "../params");
+
+describe("tryFoldFile", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  async function writeResourceDefs(): Promise<void> {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+  }
+
+  test("folds a leaf resource to a real Declarable with zero module execution", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        throw new Error("must never execute — sentinel for #1022 fold verification");
+        export const bucket = new Bucket({ name: "my-bucket", versioned: true });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toHaveLength(1);
+    const [name, entity] = result.entities[0];
+    expect(name).toBe("bucket");
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    expect(entity.lexicon).toBe("aws");
+    expect(entity.entityType).toBe("Test::Bucket");
+    expect((entity as unknown as { props: unknown }).props).toEqual({
+      name: "my-bucket",
+      versioned: true,
+    });
+  });
+
+  test("folds multiple leaf resources from one file", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        export const a = new Bucket({ name: "a" });
+        export const b = new Bucket({ name: "b" });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities.map(([name]) => name).sort()).toEqual(["a", "b"]);
+  });
+
+  // chant #1023 (epic #1019 Phase 5): a bare composite factory call, resolved
+  // through the file's own imports, now folds — the factory is invoked for
+  // real with statically-folded props, exactly as `#1022`'s resource
+  // constructors already were. This used to be the canonical fallback case;
+  // flipping it to fold is the point of #1023.
+  test("folds a top-level composite factory call, zero module execution", async () => {
+    await writeResourceDefs();
+    await writeFile(
+      join(testDir, "composites.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        import { Composite } from ${JSON.stringify(compositePath)};
+        const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+        export const MyStack = Composite<{ name: string }>((props) => {
+          const bucket = new Bucket({ name: props.name });
+          return { bucket };
+        }, "MyStack");
+      `,
+    );
+    const file = join(testDir, "stack.ts");
+    await writeFile(
+      file,
+      `
+        import { MyStack } from "./composites";
+        throw new Error("must never execute — sentinel for #1023 fold verification");
+        export const stack = MyStack({ name: "composite-bucket" });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toHaveLength(1);
+    const [name, entity] = result.entities[0];
+    expect(name).toBe("stack");
+    expect(isCompositeInstance(entity)).toBe(true);
+    const bucket = (entity as unknown as { bucket: unknown }).bucket;
+    if (!isDeclarable(bucket)) throw new Error("expected the composite's `bucket` member to be a Declarable");
+    expect(bucket.entityType).toBe("Test::Bucket");
+    expect((bucket as unknown as { props: unknown }).props).toEqual({ name: "composite-bucket" });
+  });
+
+  test("falls back when the composite factory is defined locally (not resolvable via import)", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "stack.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Composite } from ${JSON.stringify(compositePath)};
+        const LocalStack = Composite<{ name: string }>((props) => {
+          const bucket = new Bucket({ name: props.name });
+          return { bucket };
+        }, "LocalStack");
+        export const stack = LocalStack({ name: "composite-bucket" });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("LocalStack");
+  });
+
+  test("falls back when a prop value is not foldable", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        function computeName(): string { return "dynamic"; }
+        export const bucket = new Bucket({ name: computeName() });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("computeName");
+  });
+
+  test("falls back when the resource constructor is not a resolvable import", async () => {
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("not a resolvable import");
+  });
+
+  test("falls back on `export default`", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        const bucket = new Bucket({ name: "my-bucket" });
+        export default bucket;
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("export default");
+  });
+
+  test("falls back when there are no exports at all", async () => {
+    const file = join(testDir, "main.ts");
+    await writeFile(file, `const helperValue = 5;`);
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toBe("no foldable resource exports");
+  });
+
+  // chant #1020: a plain-value-only export now folds too (contributing
+  // nothing to `entities` — only Declarable/CompositeInstance land there —
+  // but recorded in `exportedValues`). This is intentional, not a relaxed
+  // subset: `fold()` already reduced a bare literal trivially; the only
+  // change is that `tryFoldFile` now ALSO tries it for a "single" declarator
+  // instead of only the composite-call spine. It matters for #1020's own
+  // acceptance criterion — a config/params file that exports nothing but
+  // plain consts must be safe to fold (0 entities either way), or
+  // `planFoldTaint` would needlessly force every file that imports one of
+  // its constants back to run too.
+  test("a plain-value-only export now folds — zero entities, but the value is recorded for cross-file reference", async () => {
+    const file = join(testDir, "main.ts");
+    await writeFile(file, `export const helperValue = 5;`);
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toEqual([]);
+    expect(result.exportedValues.get("helperValue")).toBe(5);
+  });
+
+  // #1025 differential regression: the constructor's optional second
+  // argument (CFN-style resource attributes — DependsOn, Condition,
+  // DeletionPolicy, …) was folded by fold.ts's `foldResource` but then
+  // dropped on the floor here — only `entry.spec.props` was ever passed to
+  // `new ResourceCtor(...)`. Confirms the fix actually reaches the
+  // constructed `Declarable`, not just the intermediate `FoldedResource`
+  // spec (see fold.test.ts for that narrower unit).
+  test("passes the folded second argument through as the constructed entity's attributes", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        export const bucket = new Bucket(
+          { name: "my-bucket" },
+          { DeletionPolicy: "Retain", DependsOn: "otherResource" },
+        );
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    expect((entity as unknown as { attributes: unknown }).attributes).toEqual({
+      DeletionPolicy: "Retain",
+      DependsOn: "otherResource",
+    });
+  });
+});
+
+// chant #1020 (epic #1019) — cross-file resolution: an imported binding now
+// folds by resolving it to its `export const` initializer and folding it in
+// the DEFINING module's own scope, instead of failing the whole importing
+// file on the first identifier it doesn't recognize.
+describe("tryFoldFile — cross-file resolution (chant #1020)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-crossfile-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  async function writeResourceDefs(): Promise<void> {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+        export const Vpc = createResource("Test::Vpc", "aws", { vpcId: "VpcId" });
+        export const Alb = createResource("Test::Alb", "aws", { albArn: "AlbArn" });
+      `,
+    );
+  }
+
+  test("an imported plain const folds identically to an inline one", async () => {
+    await writeResourceDefs();
+    await writeFile(join(testDir, "config.ts"), `export const REGION = "us-east-1";`);
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { REGION } from "./config";
+        export const bucket = new Bucket({ name: "b", region: REGION });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    expect((entity as unknown as { props: unknown }).props).toEqual({ name: "b", region: "us-east-1" });
+  });
+
+  test("config.ts's own fold succeeds with zero entities — a plain-const-only file must not be tainted merely for existing", async () => {
+    const file = join(testDir, "config.ts");
+    await writeFile(file, `export const REGION = "us-east-1";\nexport const RETRIES = 3;`);
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toEqual([]);
+    expect(result.exportedValues.get("REGION")).toBe("us-east-1");
+    expect(result.exportedValues.get("RETRIES")).toBe(3);
+  });
+
+  test("a cross-file resource attribute reference folds to a real AttrRef", async () => {
+    await writeResourceDefs();
+    await writeFile(
+      join(testDir, "network.ts"),
+      `
+        import { Vpc } from "./resources";
+        export const vpc = new Vpc({ cidr: "10.0.0.0/16" });
+      `,
+    );
+    const file = join(testDir, "alb.ts");
+    await writeFile(
+      file,
+      `
+        import { Alb } from "./resources";
+        import { vpc } from "./network";
+        export const alb = new Alb({ vpcId: vpc.vpcId });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    const vpcId = (entity as unknown as { props: { vpcId: unknown } }).props.vpcId;
+    expect(isAttrRefLike(vpcId)).toBe(true);
+  });
+
+  // The hard part (see planFoldTaint's module doc): fold and run must never
+  // disagree about object identity. If `alb.ts` reached into `network.ts`
+  // and built a SECOND copy of `network.vpc`, that copy would never match
+  // discover()'s entities map by identity and serialization would crash, not
+  // drift. Asserted with `toBe` — identity, not `toEqual`'s structural check.
+  test("a cross-file reference shares the EXACT SAME entity instance as the defining file's own fold — not a duplicate", async () => {
+    await writeResourceDefs();
+    const networkFile = join(testDir, "network.ts");
+    await writeFile(
+      networkFile,
+      `
+        import { Vpc } from "./resources";
+        export const vpc = new Vpc({ cidr: "10.0.0.0/16" });
+      `,
+    );
+    const albFile = join(testDir, "alb.ts");
+    await writeFile(
+      albFile,
+      `
+        import { Alb } from "./resources";
+        import { vpc } from "./network";
+        export const alb = new Alb({ vpcId: vpc.vpcId });
+      `,
+    );
+
+    // One shared session, exactly as `discover()` gives its own per-file
+    // loop — this is what a real build does; two independent `tryFoldFile`
+    // calls with no session would each fold `network.ts` on their own and
+    // legitimately produce two different (if structurally equal) objects.
+    const session = createFoldSession();
+    const networkResult = await tryFoldFile(networkFile, [], session);
+    const albResult = await tryFoldFile(albFile, [], session);
+
+    expect(networkResult.ok).toBe(true);
+    expect(albResult.ok).toBe(true);
+    if (!networkResult.ok || !albResult.ok) return;
+
+    const [, vpcEntity] = networkResult.entities[0];
+    const [, albEntity] = albResult.entities[0];
+    const vpcIdRef = (albEntity as unknown as { props: { vpcId: AttrRef } }).props.vpcId;
+    expect(vpcIdRef.parent.deref()).toBe(vpcEntity);
+  });
+
+  // A diamond — TWO paths reaching the SAME module (b.ts and c.ts both
+  // import hub.ts; neither imports the other) — is the case that silently
+  // degrades to duplicated (or, nested a few levels deep, EXPONENTIAL) work
+  // without a resolution memo, yet produces no error at all: each path just
+  // independently re-resolves the shared module. Distinct from the reference
+  // CYCLE tests below, which fail loudly; this one must instead prove the
+  // hub was folded exactly once and every referrer shares that one object.
+  // An explicit test timeout below turns a reintroduced non-terminating bug
+  // into a fast, clearly-labeled failure instead of a hung test run.
+  test(
+    "a diamond (two independent paths reaching the same module) resolves without re-resolving the shared module",
+    async () => {
+      await writeResourceDefs();
+      await writeFile(
+        join(testDir, "hub.ts"),
+        `
+          import { Vpc } from "./resources";
+          export const vpc = new Vpc({ cidr: "10.0.0.0/16" });
+        `,
+      );
+      await writeFile(
+        join(testDir, "b.ts"),
+        `
+          import { Alb } from "./resources";
+          import { vpc } from "./hub";
+          export const b = new Alb({ vpcId: vpc.vpcId });
+        `,
+      );
+      await writeFile(
+        join(testDir, "c.ts"),
+        `
+          import { Alb } from "./resources";
+          import { vpc } from "./hub";
+          export const c = new Alb({ vpcId: vpc.vpcId });
+        `,
+      );
+
+      const session = createFoldSession();
+      const hubResult = await tryFoldFile(join(testDir, "hub.ts"), [], session);
+      const bResult = await tryFoldFile(join(testDir, "b.ts"), [], session);
+      const cResult = await tryFoldFile(join(testDir, "c.ts"), [], session);
+
+      expect(hubResult.ok).toBe(true);
+      expect(bResult.ok).toBe(true);
+      expect(cResult.ok).toBe(true);
+      if (!hubResult.ok || !bResult.ok || !cResult.ok) return;
+
+      const [, hubVpc] = hubResult.entities[0];
+      const [, bEntity] = bResult.entities[0];
+      const [, cEntity] = cResult.entities[0];
+      const bVpcId = (bEntity as unknown as { props: { vpcId: AttrRef } }).props.vpcId;
+      const cVpcId = (cEntity as unknown as { props: { vpcId: AttrRef } }).props.vpcId;
+      // If the hub were re-resolved once per path (the un-memoized failure
+      // mode), each path would construct its OWN, distinct `Vpc` instance —
+      // these `toBe` checks would fail (not hang) in that case.
+      expect(bVpcId.parent.deref()).toBe(hubVpc);
+      expect(cVpcId.parent.deref()).toBe(hubVpc);
+      // hub.ts/b.ts/c.ts (3) plus the two shared fixture-support files each
+      // of them transitively imports — resources.ts, and (via its own
+      // absolute-path import, see `runtimePath`'s doc above) runtime.ts
+      // itself — each attempted/cached exactly ONCE too, not once per
+      // referrer. The point of this count isn't the literal number 5; it's
+      // that it's flat regardless of how many paths (b.ts AND c.ts) lead to
+      // the SAME file, which is what a broken/missing memo would violate.
+      expect(session.cache.size).toBe(5);
+    },
+    5000,
+  );
+
+  // A wider fan-out (many files, all reaching one shared hub, plus a short
+  // dependency chain) than the minimal diamond above — cheap enough to stay
+  // well under the explicit timeout if resolution is O(files), but would
+  // measurably blow up if the hub (or the chain) were re-resolved once per
+  // referrer instead of once per session.
+  test(
+    "a wide fan-out to one shared hub resolves promptly (no combinatorial blowup)",
+    async () => {
+      await writeResourceDefs();
+      await writeFile(
+        join(testDir, "hub.ts"),
+        `
+          import { Vpc } from "./resources";
+          export const vpc = new Vpc({ cidr: "10.0.0.0/16" });
+        `,
+      );
+      const FANOUT = 15;
+      const files: string[] = [];
+      for (let i = 0; i < FANOUT; i++) {
+        const f = join(testDir, `leaf${i}.ts`);
+        await writeFile(
+          f,
+          `
+            import { Alb } from "./resources";
+            import { vpc } from "./hub";
+            export const leaf = new Alb({ vpcId: vpc.vpcId });
+          `,
+        );
+        files.push(f);
+      }
+
+      const session = createFoldSession();
+      const hubResult = await tryFoldFile(join(testDir, "hub.ts"), [], session);
+      expect(hubResult.ok).toBe(true);
+      if (!hubResult.ok) return;
+      const [, hubVpc] = hubResult.entities[0];
+
+      for (const f of files) {
+        const result = await tryFoldFile(f, [], session);
+        expect(result.ok).toBe(true);
+        if (!result.ok) continue;
+        const [, entity] = result.entities[0];
+        const vpcId = (entity as unknown as { props: { vpcId: AttrRef } }).props.vpcId;
+        expect(vpcId.parent.deref()).toBe(hubVpc);
+      }
+
+      // hub.ts + the two shared fixture-support files (resources.ts,
+      // runtime.ts — see the diamond test above) + FANOUT leaves. Flat in
+      // FANOUT's shared dependencies regardless of FANOUT's size is exactly
+      // the property a broken memo would violate.
+      expect(session.cache.size).toBe(FANOUT + 3);
+    },
+    5000,
+  );
+
+  test("a namespace import's member access resolves cross-file (import * as ns)", async () => {
+    await writeResourceDefs();
+    await writeFile(
+      join(testDir, "ecr.ts"),
+      `
+        import { Bucket } from "./resources";
+        export const apiRepo = new Bucket({ name: "api-repo" });
+        export const uiRepo = new Bucket({ name: "ui-repo" });
+      `,
+    );
+    const file = join(testDir, "outputs.ts");
+    await writeFile(
+      file,
+      `
+        import { Alb } from "./resources";
+        import * as ecr from "./ecr";
+        export const alb = new Alb({ albArn: ecr.apiRepo.arn });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    const albArn = (entity as unknown as { props: { albArn: unknown } }).props.albArn;
+    expect(isAttrRefLike(albArn)).toBe(true);
+  });
+
+  test("a re-export chain (`export { x } from \"./y\"`) resolves cross-file, sharing the same instance", async () => {
+    await writeResourceDefs();
+    const implFile = join(testDir, "impl.ts");
+    await writeFile(
+      implFile,
+      `
+        import { Bucket } from "./resources";
+        export const bucket = new Bucket({ name: "impl-bucket" });
+      `,
+    );
+    const barrelFile = join(testDir, "barrel.ts");
+    await writeFile(barrelFile, `export { bucket } from "./impl";`);
+
+    const session = createFoldSession();
+    const implResult = await tryFoldFile(implFile, [], session);
+    const barrelResult = await tryFoldFile(barrelFile, [], session);
+
+    expect(implResult.ok).toBe(true);
+    expect(barrelResult.ok).toBe(true);
+    if (!implResult.ok || !barrelResult.ok) return;
+    expect(barrelResult.entities).toHaveLength(1);
+    const [name, barrelBucket] = barrelResult.entities[0];
+    expect(name).toBe("bucket");
+    const [, implBucket] = implResult.entities[0];
+    expect(barrelBucket).toBe(implBucket);
+  });
+
+  test("a re-export chain resolves transitively through more than one hop", async () => {
+    await writeResourceDefs();
+    await writeFile(
+      join(testDir, "impl.ts"),
+      `
+        import { Bucket } from "./resources";
+        export const bucket = new Bucket({ name: "impl-bucket" });
+      `,
+    );
+    await writeFile(join(testDir, "mid-barrel.ts"), `export { bucket } from "./impl";`);
+    const topBarrel = join(testDir, "top-barrel.ts");
+    await writeFile(topBarrel, `export { bucket as sharedBucket } from "./mid-barrel";`);
+
+    const result = await tryFoldFile(topBarrel);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toHaveLength(1);
+    const [name, entity] = result.entities[0];
+    expect(name).toBe("sharedBucket");
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    expect((entity as unknown as { props: unknown }).props).toEqual({ name: "impl-bucket" });
+  });
+
+  // Explicit timeouts throughout this describe's cycle tests: a regression
+  // that broke cycle detection (rather than just mis-formatting its message)
+  // would hang, not fail — a bounded test timeout turns that into a fast,
+  // clearly-labeled failure instead of a stuck test run.
+  test(
+    "an import cycle produces a located FoldError naming the cycle path",
+    async () => {
+      await writeFile(
+        join(testDir, "a.ts"),
+        `
+        import { B_VALUE } from "./b";
+        export const A_VALUE = "a-" + B_VALUE;
+      `,
+      );
+      await writeFile(
+        join(testDir, "b.ts"),
+        `
+        import { A_VALUE } from "./a";
+        export const B_VALUE = "b-" + A_VALUE;
+      `,
+      );
+
+      const result = await tryFoldFile(join(testDir, "a.ts"));
+
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toContain("import cycle");
+      expect(result.reason).toContain("a.ts");
+      expect(result.reason).toContain("b.ts");
+      // Located — "line:col - message", the same `FoldError` formatting as
+      // every other fold rejection, not a bare unpositioned string.
+      expect(result.reason).toMatch(/\d+:\d+ - /);
+    },
+    5000,
+  );
+
+  test(
+    "a self-cycle (a file whose own re-export chain reaches back to itself) is also detected",
+    async () => {
+      await writeFile(join(testDir, "a.ts"), `export { x } from "./b";`);
+      const file = join(testDir, "b.ts");
+      await writeFile(file, `export { x } from "./a";`);
+
+      const result = await tryFoldFile(file);
+
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toContain("import cycle");
+    },
+    5000,
+  );
+
+  // A 3-file cycle where the loop closes several hops away from where it
+  // started (a -> b -> c -> a), not just a direct pair — proves cycle
+  // detection walks the whole `stack`, not just the immediate caller.
+  test(
+    "a longer cycle (three files) is detected, not just a direct pair",
+    async () => {
+      await writeFile(join(testDir, "a.ts"), `import { c } from "./c";\nexport const a = "a" + c;`);
+      await writeFile(join(testDir, "b.ts"), `import { a } from "./a";\nexport const b = "b" + a;`);
+      await writeFile(join(testDir, "c.ts"), `import { b } from "./b";\nexport const c = "c" + b;`);
+
+      const result = await tryFoldFile(join(testDir, "b.ts"));
+
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.reason).toContain("import cycle");
+    },
+    5000,
+  );
+});
+
+// chant #1039 — the CLI fold path hardcoded `intrinsics` to `[]` at both
+// `fold-import.ts` call sites, so a registered lexicon intrinsic tagged
+// template (e.g. AWS `Sub`\`...\`) never folded in production even though
+// `tryFoldFile` accepted an `intrinsics` parameter. These tests exercise
+// that parameter end-to-end with a REAL tagged-template intrinsic — built on
+// the same `Intrinsic`/`INTRINSIC_MARKER` contract every lexicon's own
+// intrinsic classes implement (see `intrinsicPath` above), not a fabricated
+// shape — rather than the hand-rolled `IntrinsicDef` used by `fold.test.ts`'s
+// narrower unit tests of the reducer alone.
+describe("tryFoldFile — registered intrinsic tagged templates (#1039)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-intrinsic-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  const SUB: IntrinsicDef = { name: "Sub", isTag: true, outputKey: "Test::Sub" };
+
+  /** A tagged-template intrinsic + pseudo-parameter namespace, shaped exactly like a real lexicon's (AWS's `Sub`/`AWS.StackName`): a class implementing `Intrinsic`, and a factory function invoked as `Sub`\`...\``. */
+  async function writeIntrinsicDefs(): Promise<void> {
+    await writeFile(
+      join(testDir, "intrinsics.ts"),
+      `
+        import { INTRINSIC_MARKER } from ${JSON.stringify(intrinsicPath)};
+
+        export class SubIntrinsic {
+          constructor(strings, values) {
+            this[INTRINSIC_MARKER] = true;
+            this.strings = strings;
+            this.values = values;
+          }
+          toJSON() {
+            let out = "";
+            for (let i = 0; i < this.strings.length; i++) {
+              out += this.strings[i];
+              if (i < this.values.length) out += String(this.values[i]);
+            }
+            return { "Test::Sub": out };
+          }
+        }
+
+        export function Sub(strings, ...values) {
+          return new SubIntrinsic(strings, values);
+        }
+
+        export const NS = { Region: "NS::Region" };
+      `,
+    );
+  }
+
+  async function writeResourceDefs(): Promise<void> {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+  }
+
+  test("a registered tag folds end-to-end to the real intrinsic's value — zero module execution", async () => {
+    await writeIntrinsicDefs();
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Sub, NS } from "./intrinsics";
+        throw new Error("must never execute — sentinel for #1039 fold verification");
+        export const bucket = new Bucket({ name: Sub\`\${NS.Region}-data\` });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [SUB]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toHaveLength(1);
+    const [name, entity] = result.entities[0];
+    expect(name).toBe("bucket");
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    // The revived value must be a genuine, live `SubIntrinsic` instance —
+    // constructed by actually invoking the real `Sub` tag function through
+    // this file's own imports, with "NS::Region" resolved via its `NS`
+    // import — not the raw `{ __intrinsic, strings, values }` / `{ __symbol
+    // }` envelope fold() produces internally (that envelope is meant to be
+    // replayed, not serialized — see fold-import.ts's "Intrinsic revival"
+    // section). A serializer calls `.toJSON()` on it exactly like it would
+    // for any other lexicon intrinsic (e.g. AWS's real `Sub`).
+    const bucketName = (entity as unknown as { props: { name: unknown } }).props.name;
+    expect(bucketName).toBeInstanceOf(Object);
+    expect((bucketName as { toJSON(): unknown }).toJSON()).toEqual({ "Test::Sub": "NS::Region-data" });
+  });
+
+  test("an unregistered tag still falls back to run when no intrinsics are passed", async () => {
+    await writeIntrinsicDefs();
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Sub, NS } from "./intrinsics";
+        export const bucket = new Bucket({ name: Sub\`\${NS.Region}-data\` });
+      `,
+    );
+
+    // No second argument — reproduces the exact pre-#1039 production bug
+    // (the CLI fold path hardcoded this to `[]`).
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("unregistered tagged template intrinsic: Sub");
+  });
+
+  test("a same-file resource reference inside a folded intrinsic's interpolation falls back to run rather than folding to the wrong value", async () => {
+    await writeIntrinsicDefs();
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Sub } from "./intrinsics";
+        export const a = new Bucket({ name: "a" });
+        export const b = new Bucket({ name: Sub\`\${a.arn}-clone\` });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [SUB]);
+
+    // Reviving would need a genuine live `AttrRef` wired to the sibling
+    // entity (a WeakRef into an object this file's fold hasn't necessarily
+    // constructed yet) — out of scope for #1039, same call as the existing
+    // "nested `new Type(...)` as a value" rejection. Falling back to run is
+    // always safe; silently folding to the raw envelope would not be.
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("not foldable");
+  });
+});
+
+describe("tryFoldFile — build-time parameters (chant #1064)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-buildparams-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  async function writeResourceDefs(): Promise<void> {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+  }
+
+  test("a direct params.<name> declarator folds to a LITERAL, not a symbolic node", async () => {
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const tier = params.tier;
+      `,
+    );
+
+    const session = createFoldSession([], { tier: "production" });
+    const result = await tryFoldFile(file, [], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.exportedValues.get("tier")).toBe("production");
+  });
+
+  test("params.<name> nested inside a resource's props folds through the general reducer", async () => {
+    await writeResourceDefs();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const bucket = new Bucket({ name: params.env });
+      `,
+    );
+
+    const session = createFoldSession([], { env: "staging" });
+    const result = await tryFoldFile(file, [], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toHaveLength(1);
+    const [, entity] = result.entities[0];
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    expect((entity as unknown as { props: { name: unknown } }).props.name).toBe("staging");
+  });
+
+  test("a nullish-coalesced default still folds to a literal (loomster's `params.x ?? \"default\"` pattern)", async () => {
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const project = params.project ?? "loom";
+      `,
+    );
+
+    // No "project" key supplied — falls through to the literal default.
+    const session = createFoldSession([], {});
+    const result = await tryFoldFile(file, [], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.exportedValues.get("project")).toBe("loom");
+  });
+
+  test("an unrelated import also named `params` (not resolving to ../params.ts) is unaffected", async () => {
+    await writeFile(
+      join(testDir, "local-config.ts"),
+      `export const params = { tier: "should-not-be-used" };`,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { params } from "./local-config";
+        export const tier = params.tier;
+      `,
+    );
+
+    const session = createFoldSession([], { tier: "production" });
+    const result = await tryFoldFile(file, [], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    // Resolved via the ORDINARY cross-file project resolution, not the
+    // build-time-parameters substitution — proves the two never collide.
+    expect(result.exportedValues.get("tier")).toBe("should-not-be-used");
+  });
+
+  test("a `params`-named import from an unrelated BARE specifier is left alone (text-match only, never resolved)", async () => {
+    // Regression guard: buildExternals must recognize the build-time-params
+    // bare specifier by an exact TEXT match, never by resolving an arbitrary
+    // bare specifier just because the imported binding happens to be named
+    // "params" — resolving every such specifier would reintroduce the exact
+    // cold bare-specifier-resolution cost chant#1020 already fixed (up to
+    // ~361s for a genuinely new package's first resolution in a process).
+    // "left-pad" is never installed in this repo, so if this DID try to
+    // resolve it, it would throw (caught) rather than hang — this test
+    // mainly documents the invariant; the perf regression itself was only
+    // observable via a real corpus/CI run, not a unit test.
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { params } from "left-pad";
+        export const tier = params.tier;
+      `,
+    );
+
+    const session = createFoldSession([], { tier: "production" });
+    const result = await tryFoldFile(file, [], session);
+
+    // Not substituted from build-time parameters (would be "production" if
+    // it were) — falls back to run via the ordinary unresolved-bare-specifier
+    // path, exactly as any other unimportable bare specifier would.
+    expect(result.ok).toBe(false);
+  });
+
+  test("without a FoldSession buildParams, params.<name> is an unresolved identifier (matches an ordinary bare import)", async () => {
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const tier = params.tier;
+      `,
+    );
+
+    // No session passed at all — tryFoldFile creates a private one with no buildParams.
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+  });
+
+  test("real end-to-end parity: the fold path substitutes without ever importing ../params.ts, while a real run-fallback import sees the same values via setBuildParams", async () => {
+    // Simulates what discover() does before either fold or run touches a file.
+    const { setBuildParams } = await import("../params");
+    setBuildParams({ tier: "production-ha" });
+
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { params } from ${JSON.stringify(paramsPath)};
+        export const tier = params.tier;
+      `,
+    );
+
+    const session = createFoldSession([], { tier: "production-ha" });
+    const folded = await tryFoldFile(file, [], session);
+    expect(folded.ok).toBe(true);
+    if (folded.ok) expect(folded.exportedValues.get("tier")).toBe("production-ha");
+
+    // A real import of the shared module (what a run-fallback file's own
+    // `import()` would do) observes the identical value — same object,
+    // mutated in place, not re-bound.
+    expect(sharedParams.tier).toBe("production-ha");
+
+    setBuildParams({});
+  });
+});
+
+/**
+ * chant #1082 — registered authoring helpers, and constructor argument
+ * positions.
+ *
+ * Fixtures import chant-core's REAL helpers by absolute path (the convention
+ * every other suite in this file uses), which is also the second arm of the
+ * provenance check: a specifier that resolves inside chant-core's own tree
+ * counts as chant's own, exactly like the `@intentius/chant*` package
+ * specifier a real project writes.
+ */
+describe("tryFoldFile — registered authoring helpers (#1082)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-helpers-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  /** Absolute path to the real component-authoring helpers (`phase`, `gate`, `stackOutput`). */
+  const componentPath = resolve(thisDir, "../components/component");
+  /** Absolute path to the real `output()` / `LexiconOutput`. */
+  const lexiconOutputPath = resolve(thisDir, "../lexicon-output");
+
+  test("a component authored with phase()/gate()/stackOutput() folds to the real plain data — zero module execution", async () => {
+    const file = join(testDir, "web.component.ts");
+    await writeFile(
+      file,
+      `
+        import { phase, gate, stackOutput } from ${JSON.stringify(componentPath)};
+        throw new Error("must never execute — sentinel for #1082 fold verification");
+        export const web = {
+          name: "web",
+          dependsOn: ["shared-foundation"],
+          deploy: [
+            phase("Apply", [
+              { kind: "cfn-deploy", stack: "web", inputs: { pVpcId: stackOutput("shared-foundation", "oVpcId") } },
+              gate("approve", { timeout: "24h" }),
+            ], { parallel: true }),
+          ],
+        };
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    // The revived value is what the real helpers return, not an envelope:
+    // `phase()`'s `{ phase, steps, parallel }`, `gate()`'s `{ kind: "gate", … }`,
+    // `stackOutput()`'s `{ stackOutput: { stack, name } }`.
+    expect(result.exportedValues.get("web")).toEqual({
+      name: "web",
+      dependsOn: ["shared-foundation"],
+      deploy: [
+        {
+          phase: "Apply",
+          parallel: true,
+          steps: [
+            {
+              kind: "cfn-deploy",
+              stack: "web",
+              inputs: { pVpcId: { stackOutput: { stack: "shared-foundation", name: "oVpcId" } } },
+            },
+            { kind: "gate", signalName: "approve", timeout: "24h" },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("a nested (fan-out) phase folds — helper envelopes revive bottom-up", async () => {
+    const file = join(testDir, "fanout.component.ts");
+    await writeFile(
+      file,
+      `
+        import { phase } from ${JSON.stringify(componentPath)};
+        export const fanout = { deploy: [phase("Outer", [phase("Inner", [{ kind: "noop" }])])] };
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.exportedValues.get("fanout")).toEqual({
+      deploy: [{ phase: "Outer", steps: [{ phase: "Inner", steps: [{ kind: "noop" }] }] }],
+    });
+  });
+
+  test("a registered NAME imported from the project's own code does NOT fold — the allowlist is chant's, not the name's", async () => {
+    await writeFile(
+      join(testDir, "helpers.ts"),
+      `export function phase(name, steps) { return { phase: name, steps, mine: true }; }`,
+    );
+    const file = join(testDir, "web.component.ts");
+    await writeFile(
+      file,
+      `
+        import { phase } from "./helpers";
+        export const web = { deploy: [phase("Apply", [])] };
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("./helpers");
+    expect(result.reason).toContain("not chant's own");
+  });
+
+  test("a registered name declared in the file itself does NOT fold — it is not an import at all", async () => {
+    const file = join(testDir, "local.component.ts");
+    await writeFile(
+      file,
+      `
+        function phase(name, steps) { return { phase: name, steps }; }
+        export const web = { deploy: [phase("Apply", [])] };
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("is not a resolvable import");
+  });
+
+  test("an UNREGISTERED chant import called as a value still falls back — registration is per-helper, not per-module", async () => {
+    const file = join(testDir, "unregistered.component.ts");
+    await writeFile(
+      file,
+      `
+        import { inferArchetype } from ${JSON.stringify(componentPath)};
+        export const web = { archetype: inferArchetype({ deploy: [] }) };
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("inferArchetype(...)");
+  });
+
+  test("output() folds against a REAL cross-file AttrRef, producing a genuine LexiconOutput", async () => {
+    await writeFile(
+      join(testDir, "defs.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { Bucket } from "./defs";
+        export const bucket = new Bucket({ name: "my-bucket" });
+      `,
+    );
+    const file = join(testDir, "outputs.ts");
+    await writeFile(
+      file,
+      `
+        import { output } from ${JSON.stringify(lexiconOutputPath)};
+        import { bucket } from "./resources";
+        export const oArn = bucket ? output(bucket.arn, "oArn") : undefined;
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const oArn = result.exportedValues.get("oArn") as { outputName: string; sourceLexicon: string };
+    // A genuine LexiconOutput built from the real AttrRef — it read the ref's
+    // parent through its WeakRef to learn the lexicon, which is only possible
+    // with a live reference, never with a `{ __attrRef }` envelope.
+    expect(oArn.outputName).toBe("oArn");
+    expect(oArn.sourceLexicon).toBe("aws");
+  });
+
+  test("output() over a SAME-FILE resource reference falls back rather than wrapping a symbolic envelope", async () => {
+    await writeFile(
+      join(testDir, "defs.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    const file = join(testDir, "same-file-outputs.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./defs";
+        import { output } from ${JSON.stringify(lexiconOutputPath)};
+        const enabled = true;
+        export const bucket = new Bucket({ name: "my-bucket" });
+        export const oArn = enabled ? output(bucket.arn, "oArn") : undefined;
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    // `bucket.arn` folds to a `{ __attrRef }` envelope, and `LexiconOutput`'s
+    // constructor needs a real `AttrRef` (it derefs the parent to learn the
+    // lexicon). Constructing it from the envelope would silently produce a
+    // wrong output, so the whole file falls back to run instead.
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("same-file resource reference");
+  });
+});
+
+describe("tryFoldFile — constructor argument positions (#1082)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-ctorargs-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  /** A `(type, props)` constructor, structurally identical to the real AWS deploy-time `Parameter` (lexicons/aws/src/parameter.ts). */
+  async function writeParameterDef(): Promise<void> {
+    await writeFile(
+      join(testDir, "parameter.ts"),
+      `
+        import { DECLARABLE_MARKER } from ${JSON.stringify(resolve(thisDir, "../declarable"))};
+
+        export class Parameter {
+          constructor(type, options) {
+            this[DECLARABLE_MARKER] = true;
+            this.lexicon = "aws";
+            this.entityType = "AWS::CloudFormation::Parameter";
+            this.parameterType = type;
+            this.description = options?.description;
+            this.defaultValue = options?.defaultValue;
+          }
+        }
+      `,
+    );
+  }
+
+  test("`new Parameter(\"String\", {...})` folds — the props object need not be the first argument", async () => {
+    await writeParameterDef();
+    const file = join(testDir, "params.ts");
+    await writeFile(
+      file,
+      `
+        import { Parameter } from "./parameter";
+        throw new Error("must never execute — sentinel for #1082 fold verification");
+        export const pVpcId = new Parameter("AWS::EC2::VPC::Id", { description: "vpc id" });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.entities).toHaveLength(1);
+    const [name, entity] = result.entities[0];
+    expect(name).toBe("pVpcId");
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    // Both arguments reached the real constructor, in the right positions.
+    expect((entity as unknown as { parameterType: string }).parameterType).toBe("AWS::EC2::VPC::Id");
+    expect((entity as unknown as { description: string }).description).toBe("vpc id");
+  });
+
+  test("a constructor called with only a non-object argument folds too — no props object is invented", async () => {
+    await writeParameterDef();
+    const file = join(testDir, "params.ts");
+    await writeFile(
+      file,
+      `
+        import { Parameter } from "./parameter";
+        export const pName = new Parameter("String");
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    expect((entity as unknown as { parameterType: string }).parameterType).toBe("String");
+    expect((entity as unknown as { description?: string }).description).toBeUndefined();
+  });
+
+  test("a non-foldable argument in any position still falls the file back to run", async () => {
+    await writeParameterDef();
+    const file = join(testDir, "params.ts");
+    await writeFile(
+      file,
+      `
+        import { Parameter } from "./parameter";
+        export const pName = new Parameter(computeType(), { description: "x" });
+      `,
+    );
+
+    const result = await tryFoldFile(file);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("computeType(...)");
+  });
+});
+
+/**
+ * chant #1044 — registered lexicon intrinsics in PLAIN-CALL form, end to end.
+ *
+ * The unit tests in ../fold/fold.test.ts cover the reducer's half (a call
+ * reduces to a `{__intrinsic, args}` envelope, executing nothing). These
+ * cover the other half: the envelope is revived by resolving the name
+ * through THIS FILE'S OWN imports and invoking the real function, so what
+ * lands in a resource's props is a genuine live intrinsic instance — the
+ * same object the run path would have built.
+ */
+describe("tryFoldFile — registered call-form intrinsics (#1044)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-callintrinsic-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  const REF: IntrinsicDef = { name: "Ref", isTag: false, foldsAsCall: true, outputKey: "Test::Ref" };
+  const NOT_OPTED_IN: IntrinsicDef = { name: "Ref", isTag: false };
+
+  /** A plain-call intrinsic shaped exactly like aws's real `Ref`: a factory returning a class that implements the `Intrinsic` contract and resolves its target at `toJSON()` time. */
+  async function writeCallIntrinsicDefs(): Promise<void> {
+    await writeFile(
+      join(testDir, "intrinsics.ts"),
+      `
+        import { INTRINSIC_MARKER } from ${JSON.stringify(intrinsicPath)};
+
+        export class RefIntrinsic {
+          constructor(target) {
+            this[INTRINSIC_MARKER] = true;
+            this.target = target;
+          }
+          toJSON() {
+            return { "Test::Ref": typeof this.target === "string" ? this.target : this.target.logicalHint };
+          }
+        }
+
+        export function Ref(target) {
+          return new RefIntrinsic(target);
+        }
+
+        export const NS = { Region: "NS::Region" };
+      `,
+    );
+  }
+
+  test("an opted-in call folds end-to-end to the real intrinsic instance — zero module execution", async () => {
+    await writeCallIntrinsicDefs();
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Ref } from "./intrinsics";
+        throw new Error("must never execute — sentinel for #1044 fold verification");
+        export const bucket = new Bucket({ name: Ref("environment") });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [REF]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    const name = (entity as unknown as { props: { name: unknown } }).props.name;
+    // A genuine live instance built by the file's own `Ref`, not the
+    // `{ __intrinsic, args }` envelope the reducer produced internally.
+    expect((name as { toJSON(): unknown }).toJSON()).toEqual({ "Test::Ref": "environment" });
+  });
+
+  test("a call-form intrinsic folds inside a registered tag's interpolation, and a symbolic argument resolves through the file's own import", async () => {
+    await writeFile(
+      join(testDir, "intrinsics.ts"),
+      `
+        import { INTRINSIC_MARKER } from ${JSON.stringify(intrinsicPath)};
+        export class RefIntrinsic {
+          constructor(target) { this[INTRINSIC_MARKER] = true; this.target = target; }
+          toJSON() { return { "Test::Ref": this.target }; }
+        }
+        export function Ref(target) { return new RefIntrinsic(target); }
+        export class SubIntrinsic {
+          constructor(strings, values) { this[INTRINSIC_MARKER] = true; this.strings = strings; this.values = values; }
+          toJSON() {
+            let out = "";
+            for (let i = 0; i < this.strings.length; i++) {
+              out += this.strings[i];
+              if (i < this.values.length) out += JSON.stringify(this.values[i].toJSON ? this.values[i].toJSON() : this.values[i]);
+            }
+            return { "Test::Sub": out };
+          }
+        }
+        export function Sub(strings, ...values) { return new SubIntrinsic(strings, values); }
+        export const NS = { Region: "NS::Region" };
+      `,
+    );
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Sub, Ref, NS } from "./intrinsics";
+        export const bucket = new Bucket({ name: Sub\`\${Ref(NS.Region)}-fn\` });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [REF, { name: "Sub", isTag: true }]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const [, entity] = result.entities[0];
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    const name = (entity as unknown as { props: { name: unknown } }).props.name;
+    expect((name as { toJSON(): unknown }).toJSON()).toEqual({
+      "Test::Sub": `{"Test::Ref":"NS::Region"}-fn`,
+    });
+  });
+
+  test("a cross-file resource passed to an intrinsic call arrives as the SHARED live instance, not a re-imported copy", async () => {
+    await writeCallIntrinsicDefs();
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Param = createResource("Test::Param", "aws", {});
+      `,
+    );
+    await writeFile(
+      join(testDir, "params.ts"),
+      `
+        import { Param } from "./resources";
+        export const environment = new Param({ logicalHint: "EnvParam" });
+      `,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Param } from "./resources";
+        import { environment } from "./params";
+        import { Ref } from "./intrinsics";
+        export const other = new Param({ name: Ref(environment) });
+      `,
+    );
+
+    const session = createFoldSession([REF]);
+    const paramsResult = await tryFoldFile(join(testDir, "params.ts"), [REF], session);
+    const result = await tryFoldFile(file, [REF], session);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok || !paramsResult.ok) return;
+    const [, entity] = result.entities[0];
+    if (!isDeclarable(entity)) throw new Error("expected a Declarable");
+    const ref = (entity as unknown as { props: { name: { target: unknown } } }).props.name;
+    // Identity, not equality: the SAME object params.ts's own fold produced
+    // and discovery will collect. A second instance would serialize with no
+    // logical name at all (see planFoldTaint's doc).
+    expect(ref.target).toBe(paramsResult.exportedValues.get("environment"));
+  });
+
+  test("a REGISTERED intrinsic with no opt-in still falls the file back to run", async () => {
+    await writeCallIntrinsicDefs();
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Ref } from "./intrinsics";
+        export const bucket = new Bucket({ name: Ref("environment") });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [NOT_OPTED_IN]);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("function call as a value is not foldable: Ref(...)");
+  });
+
+  test("an opted-in NAME that this file never imported falls back — the registry is not permission to invoke a name", async () => {
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        export const bucket = new Bucket({ name: Ref("environment") });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [REF]);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain(`"Ref" is not a resolvable import`);
+  });
+
+  test("a same-file resource reference passed to an intrinsic call falls back rather than folding to the wrong value", async () => {
+    await writeCallIntrinsicDefs();
+    await writeFile(
+      join(testDir, "resources.ts"),
+      `
+        import { createResource } from ${JSON.stringify(runtimePath)};
+        export const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });
+      `,
+    );
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Bucket } from "./resources";
+        import { Ref } from "./intrinsics";
+        export const source = new Bucket({ name: "src" });
+        export const bucket = new Bucket({ name: Ref(source.arn) });
+      `,
+    );
+
+    const result = await tryFoldFile(file, [REF]);
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.reason).toContain("same-file resource reference");
+  });
+});