@intentius/chant 0.124.13 → 0.124.15

package/src/cli/compiled-cli.e2e.test.ts

@@ -0,0 +1,165 @@
+/**
+ * The installed CLI runs compiled JS with plain node (#3878). This packs core
+ * (its prepack builds dist/) and the render lexicon the way a release does,
+ * installs both into a scratch project with npm, and runs the package's own
+ * `bin/chant`.
+ *
+ * Each run is traced through a load hook that NODE_OPTIONS hands to the CLI's
+ * node, so the test can say what loaded: none of chant's TypeScript source,
+ * ever, and tsx only for a command that imports TypeScript (here the
+ * lexicon and the project source).
+ *
+ * End to end because it packs, installs from the registry and spawns the CLI.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+
+const coreRoot = resolve(import.meta.dirname, "..", "..");
+const renderRoot = resolve(coreRoot, "..", "..", "lexicons", "render");
+const version = (JSON.parse(readFileSync(join(coreRoot, "package.json"), "utf-8")) as { version: string }).version;
+
+let scratch: string;
+let project: string;
+let waves: string;
+let chant: string;
+let tracer: string;
+
+const TRACER = `
+import { registerHooks } from "node:module";
+import { appendFileSync } from "node:fs";
+const out = process.env.CHANT_TRACE_OUT;
+const seen = { chantSrc: 0, chantDist: 0, tsx: 0 };
+registerHooks({
+  load(url, context, next) {
+    if (url.includes("/@intentius/chant/src/")) seen.chantSrc++;
+    else if (url.includes("/@intentius/chant/dist/")) seen.chantDist++;
+    else if (url.includes("/node_modules/tsx/")) seen.tsx++;
+    return next(url, context);
+  },
+});
+process.on("exit", () => { if (out) appendFileSync(out, JSON.stringify(seen) + "\\n"); });
+`;
+
+function pack(dir: string, ignoreScripts = false): string {
+  const args = ["pack", "--json", "--pack-destination", scratch, ...(ignoreScripts ? ["--ignore-scripts"] : [])];
+  const packed = JSON.parse(execFileSync("npm", args, { cwd: dir, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] })) as { filename: string }[];
+  return join(scratch, packed[0].filename);
+}
+
+interface Run {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  loaded: { chantSrc: number; chantDist: number; tsx: number };
+}
+
+function run(cwd: string, args: string[]): Run {
+  const traceOut = join(scratch, `trace-${Math.random().toString(36).slice(2)}.jsonl`);
+  const env: NodeJS.ProcessEnv = { ...process.env, NODE_OPTIONS: `--import ${tracer}`, CHANT_TRACE_OUT: traceOut };
+  delete env.CHANT_ENV;
+  const result = spawnSync(chant, args, { cwd, env, encoding: "utf-8" });
+  const lines = readFileSync(traceOut, "utf-8").trim().split("\n");
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr, loaded: JSON.parse(lines[0]!) as Run["loaded"] };
+}
+
+beforeAll(() => {
+  scratch = mkdtempSync(join(tmpdir(), "chant-compiled-cli-"));
+  tracer = join(scratch, "trace.mjs");
+  writeFileSync(tracer, TRACER);
+  const core = pack(coreRoot);
+  // The lexicon's prepack regenerates it from upstream specs; the checkout's
+  // generated source and dist are what this test needs, so pack them as they are.
+  const render = pack(renderRoot, true);
+
+  project = join(scratch, "project");
+  mkdirSync(join(project, "src"), { recursive: true });
+  writeFileSync(join(project, "package.json"), JSON.stringify({ name: "compiled-cli-e2e", private: true, type: "module" }));
+  execFileSync("npm", ["install", "--no-audit", "--no-fund", "--prefer-offline", core, render], { cwd: project, stdio: "ignore" });
+  writeFileSync(join(project, "chant.config.ts"), `import type { ChantConfig } from "@intentius/chant";\nexport default { lexicons: ["render"] } satisfies ChantConfig;\n`);
+  writeFileSync(
+    join(project, "src", "infra.ts"),
+    `import { Postgres, Render } from "@intentius/chant-lexicon-render";\n` +
+      `export const db = new Postgres({ name: "e2e-db", plan: "free", version: "16", region: Render.Region });\n`,
+  );
+  chant = join(project, "node_modules", ".bin", "chant");
+
+  // A waves spec whose plan writes a fixed digest and whose apply does nothing,
+  // in a repository with the history `run wave` reads its gate policy from.
+  waves = join(scratch, "waves");
+  mkdirSync(waves);
+  writeFileSync(join(waves, "plan.mjs"), `import { writeFileSync } from "node:fs";\nwriteFileSync(process.argv[3], JSON.stringify({ planDigest: "sha256:" + "a".repeat(64) }));\n`);
+  writeFileSync(
+    join(waves, "waves.json"),
+    JSON.stringify({
+      name: "smoke",
+      op: "smoke",
+      plan: ["node", "plan.mjs", "{target}", "{plan}"],
+      apply: ["node", "-e", "0", "{target}", "{plan}"],
+      waves: [{ name: "dev", runs: [{ target: "dev" }], gate: "never" }],
+    }),
+  );
+  const git = (...args: string[]) => execFileSync("git", ["-c", "user.email=e2e@chant", "-c", "user.name=e2e", ...args], { cwd: waves, stdio: "ignore" });
+  git("init", "-q", "-b", "main");
+  git("add", "-A");
+  git("commit", "-qm", "spec");
+  writeFileSync(join(waves, ".gitignore"), ".chant/\n");
+  git("add", "-A");
+  git("commit", "-qm", "ignore");
+}, 600_000);
+
+afterAll(() => {
+  if (scratch) rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("the installed chant CLI (#3878)", () => {
+  test("--version runs compiled JS and loads no TypeScript loader", () => {
+    const r = run(project, ["--version"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stdout.trim()).toBe(version);
+    expect(r.loaded.chantDist).toBeGreaterThan(0);
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
+  });
+
+  test("run wave plans and applies a wave without loading tsx", () => {
+    const r = run(waves, ["run", "wave", "--spec", "waves.json", "--wave", "1", "--json"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(JSON.parse(r.stdout)).toMatchObject({ exitCode: 0 });
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
+  });
+
+  test("build loads the TypeScript lexicon and project through tsx, against the one compiled core", () => {
+    const r = run(project, ["build", "src", "-o", "out/render.json"]);
+    expect(r.status, r.stderr).toBe(0);
+    const built = JSON.parse(readFileSync(join(project, "out", "render.json"), "utf-8")) as Record<string, { body?: { name?: string } }>;
+    expect(built.db?.body?.name).toBe("e2e-db");
+    expect(r.loaded.tsx).toBeGreaterThan(0);
+    expect(r.loaded.chantSrc).toBe(0);
+  });
+
+  test("lint passes on the project", () => {
+    const r = run(project, ["lint", "src"]);
+    expect(r.status, r.stdout + r.stderr).toBe(0);
+    expect(r.loaded.chantSrc).toBe(0);
+  });
+
+  test("build --sandbox bundles chant's source for the sandboxed child", () => {
+    writeFileSync(
+      join(project, "src", "made.ts"),
+      `import { Postgres, Render } from "@intentius/chant-lexicon-render";\n` +
+        `function make(name: string) { const n = [1, 2].map((i) => i * 2).length; return new Postgres({ name: name + n, plan: "free", version: "16", region: Render.Region }); }\n` +
+        `export const made = make("made");\n`,
+    );
+    try {
+      const r = run(project, ["build", "src", "--sandbox", "-o", "out/sandbox.json"]);
+      expect(r.status, r.stderr).toBe(0);
+      const built = JSON.parse(readFileSync(join(project, "out", "sandbox.json"), "utf-8")) as Record<string, { body?: { name?: string } }>;
+      expect(built.made?.body?.name).toBe("made2");
+    } finally {
+      rmSync(join(project, "src", "made.ts"));
+    }
+  });
+});

package/src/cli/main.ts

@@ -3,7 +3,6 @@
 import { resolve } from "node:path";
 import { isEntryPoint } from "./is-entry-point";
 import { formatSuccess, formatError } from "./format";
-import { loadPlugins, resolveProjectLexicons } from "./plugins";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 import { loadChantConfigUpward } from "../config";
 import { findProjectRoot, findWorkspaceRoot } from "../project-root";
@@ -14,34 +13,118 @@ import { armSandboxConfigEvaluation } from "../config-sandbox";
 import { armSandboxPolicyExecution } from "../lint/policy-import";
 import { ENV_VAR, unknownEnvError } from "../env";
 import { initRuntime } from "../runtime-adapter";
-import { runBuild } from "./handlers/build";
-import { runLint } from "./handlers/lint";
-import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDevSurfaceDiff, runDevPinnedUpgrade, runDevRollingUpgrade, runDevUnknown } from "./handlers/dev";
-import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
-import { runInit, runInitLexicon } from "./handlers/init";
-import { runList, runDescribe, runImport, runAudit, runUpdate, runDoctor } from "./handlers/misc";
-import { runVendor } from "./handlers/vendor";
-import { runMigrate } from "./handlers/migrate";
-import { runCarveAdvise, runCarveUnknown } from "./handlers/carve";
-import { runCarveEmit } from "./handlers/carve-emit";
-import { runCarveBridge } from "./handlers/carve-bridge";
-import { runCarveApply } from "./handlers/carve-apply";
-import { runCarveStatus } from "./handlers/carve-status";
-import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
-import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
-import { runComponentsFanOut } from "./handlers/fan-out";
-import { runComponentsPromote, runComponentsRollback, runComponentsRedeploy } from "./handlers/promote";
-import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
-import { runGraph } from "./handlers/graph";
-import { runExplain } from "./handlers/explain";
-import { runSearch } from "./handlers/search";
-import { runOp, runOpList, runOpStatus, runOpApprove, runOpSignalRenamed, runOpCancel, runOpLog } from "./handlers/run";
-import { runOpWaveCommand } from "./handlers/run-wave";
-import { runOperator, runOperatorStatus, runOperatorLog, runApprove } from "./handlers/operator";
-import { runEmulator, formatEmulatorHelp } from "./handlers/emulator";
+import { installCompiledCli } from "../ts-loader";
 import { splitJoinedFlags, dispatchCommandGroup, collectCommandGroups, formatCommandGroupsHelp, type CommandGroup } from "./command-group";
 import type { LexiconPlugin } from "../lexicon";
 
+/**
+ * #3878 — each command's handler module loads when that command runs, not on
+ * every start: together they pull in most of chant (the TypeScript compiler
+ * among it), and `chant --version` or `chant run wave` need almost none of it.
+ */
+type Handler = CommandDef["handler"];
+const handlerModules = new Map<Handler, () => Promise<unknown>>();
+function lazyHandler<M>(load: () => Promise<M>, pick: (module: M) => Handler): Handler {
+  const handler: Handler = async (ctx) => pick(await load())(ctx);
+  handlerModules.set(handler, load);
+  return handler;
+}
+const buildHandlers = () => import("./handlers/build");
+const runBuild = lazyHandler(buildHandlers, (m) => m.runBuild);
+const lintHandlers = () => import("./handlers/lint");
+const runLint = lazyHandler(lintHandlers, (m) => m.runLint);
+const devHandlers = () => import("./handlers/dev");
+const runDevGenerate = lazyHandler(devHandlers, (m) => m.runDevGenerate);
+const runDevPublish = lazyHandler(devHandlers, (m) => m.runDevPublish);
+const runDevOnboard = lazyHandler(devHandlers, (m) => m.runDevOnboard);
+const runDevCheckLexicon = lazyHandler(devHandlers, (m) => m.runDevCheckLexicon);
+const runDevSurfaceDiff = lazyHandler(devHandlers, (m) => m.runDevSurfaceDiff);
+const runDevPinnedUpgrade = lazyHandler(devHandlers, (m) => m.runDevPinnedUpgrade);
+const runDevRollingUpgrade = lazyHandler(devHandlers, (m) => m.runDevRollingUpgrade);
+const runDevUnknown = lazyHandler(devHandlers, (m) => m.runDevUnknown);
+const serveHandlers = () => import("./handlers/serve");
+const runServeLsp = lazyHandler(serveHandlers, (m) => m.runServeLsp);
+const runServeMcp = lazyHandler(serveHandlers, (m) => m.runServeMcp);
+const runServeUnknown = lazyHandler(serveHandlers, (m) => m.runServeUnknown);
+const initHandlers = () => import("./handlers/init");
+const runInit = lazyHandler(initHandlers, (m) => m.runInit);
+const runInitLexicon = lazyHandler(initHandlers, (m) => m.runInitLexicon);
+const miscHandlers = () => import("./handlers/misc");
+const runList = lazyHandler(miscHandlers, (m) => m.runList);
+const runDescribe = lazyHandler(miscHandlers, (m) => m.runDescribe);
+const runImport = lazyHandler(miscHandlers, (m) => m.runImport);
+const runAudit = lazyHandler(miscHandlers, (m) => m.runAudit);
+const runUpdate = lazyHandler(miscHandlers, (m) => m.runUpdate);
+const runDoctor = lazyHandler(miscHandlers, (m) => m.runDoctor);
+const vendorHandlers = () => import("./handlers/vendor");
+const runVendor = lazyHandler(vendorHandlers, (m) => m.runVendor);
+const migrateHandlers = () => import("./handlers/migrate");
+const runMigrate = lazyHandler(migrateHandlers, (m) => m.runMigrate);
+const carveHandlers = () => import("./handlers/carve");
+const runCarveAdvise = lazyHandler(carveHandlers, (m) => m.runCarveAdvise);
+const runCarveUnknown = lazyHandler(carveHandlers, (m) => m.runCarveUnknown);
+const carveEmitHandlers = () => import("./handlers/carve-emit");
+const runCarveEmit = lazyHandler(carveEmitHandlers, (m) => m.runCarveEmit);
+const carveBridgeHandlers = () => import("./handlers/carve-bridge");
+const runCarveBridge = lazyHandler(carveBridgeHandlers, (m) => m.runCarveBridge);
+const carveApplyHandlers = () => import("./handlers/carve-apply");
+const runCarveApply = lazyHandler(carveApplyHandlers, (m) => m.runCarveApply);
+const carveStatusHandlers = () => import("./handlers/carve-status");
+const runCarveStatus = lazyHandler(carveStatusHandlers, (m) => m.runCarveStatus);
+const lifecycleHandlers = () => import("./handlers/lifecycle");
+const runLifecycleSnapshot = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleSnapshot);
+const runLifecycleShow = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleShow);
+const runLifecycleDiff = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleDiff);
+const runLifecycleRollback = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleRollback);
+const runLifecyclePlan = lazyHandler(lifecycleHandlers, (m) => m.runLifecyclePlan);
+const runLifecycleAffected = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleAffected);
+const runLifecycleLog = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleLog);
+const runLifecycleTeardown = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleTeardown);
+const runLifecycleWhoami = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleWhoami);
+const runLifecycleUnknown = lazyHandler(lifecycleHandlers, (m) => m.runLifecycleUnknown);
+const componentsHandlers = () => import("./handlers/components");
+const runComponentsStatus = lazyHandler(componentsHandlers, (m) => m.runComponentsStatus);
+const runComponentsReleaseRecord = lazyHandler(componentsHandlers, (m) => m.runComponentsReleaseRecord);
+const runComponentsExport = lazyHandler(componentsHandlers, (m) => m.runComponentsExport);
+const runComponentsUnknown = lazyHandler(componentsHandlers, (m) => m.runComponentsUnknown);
+const fanOutHandlers = () => import("./handlers/fan-out");
+const runComponentsFanOut = lazyHandler(fanOutHandlers, (m) => m.runComponentsFanOut);
+const promoteHandlers = () => import("./handlers/promote");
+const runComponentsPromote = lazyHandler(promoteHandlers, (m) => m.runComponentsPromote);
+const runComponentsRollback = lazyHandler(promoteHandlers, (m) => m.runComponentsRollback);
+const runComponentsRedeploy = lazyHandler(promoteHandlers, (m) => m.runComponentsRedeploy);
+const scenarioHandlers = () => import("./handlers/scenario");
+const runScenarioCheck = lazyHandler(scenarioHandlers, (m) => m.runScenarioCheck);
+const runScenarioUnknown = lazyHandler(scenarioHandlers, (m) => m.runScenarioUnknown);
+const graphHandlers = () => import("./handlers/graph");
+const runGraph = lazyHandler(graphHandlers, (m) => m.runGraph);
+const explainHandlers = () => import("./handlers/explain");
+const runExplain = lazyHandler(explainHandlers, (m) => m.runExplain);
+const searchHandlers = () => import("./handlers/search");
+const runSearch = lazyHandler(searchHandlers, (m) => m.runSearch);
+const runHandlers = () => import("./handlers/run");
+const runOp = lazyHandler(runHandlers, (m) => m.runOp);
+const runOpList = lazyHandler(runHandlers, (m) => m.runOpList);
+const runOpStatus = lazyHandler(runHandlers, (m) => m.runOpStatus);
+const runOpApprove = lazyHandler(runHandlers, (m) => m.runOpApprove);
+const runOpSignalRenamed = lazyHandler(runHandlers, (m) => m.runOpSignalRenamed);
+const runOpCancel = lazyHandler(runHandlers, (m) => m.runOpCancel);
+const runOpLog = lazyHandler(runHandlers, (m) => m.runOpLog);
+const runWaveHandlers = () => import("./handlers/run-wave");
+const runOpWaveCommand = lazyHandler(runWaveHandlers, (m) => m.runOpWaveCommand);
+const operatorHandlers = () => import("./handlers/operator");
+const runOperator = lazyHandler(operatorHandlers, (m) => m.runOperator);
+const runOperatorStatus = lazyHandler(operatorHandlers, (m) => m.runOperatorStatus);
+const runOperatorLog = lazyHandler(operatorHandlers, (m) => m.runOperatorLog);
+const runApprove = lazyHandler(operatorHandlers, (m) => m.runApprove);
+const emulatorHandlers = () => import("./handlers/emulator");
+const runEmulator = lazyHandler(emulatorHandlers, (m) => m.runEmulator);
+
+/** The lexicon plugin loader, which imports the lint, fold and build machinery: loaded when a command needs plugins (#3878). */
+const loadPlugins: typeof import("./plugins").loadPlugins = async (...a) => (await import("./plugins")).loadPlugins(...a);
+const resolveProjectLexicons: typeof import("./plugins").resolveProjectLexicons = async (...a) =>
+  (await import("./plugins")).resolveProjectLexicons(...a);
+
 /**
  * Long-form flags that are pure booleans in {@link parseArgs} — their branch
  * below sets a field to `true` and never consumes a following array element.
@@ -2002,6 +2085,9 @@ export const commandRegistry: CommandDef[] = [
  * Main entry point
  */
 async function main(): Promise<void> {
+  // #3878 — run from dist/ with plain node, TypeScript loads only when
+  // something imports it. A no-op from source.
+  installCompiledCli();
   const rawArgv = process.argv.slice(2);
 
   let args: ParsedArgs;
@@ -2035,7 +2121,7 @@ async function main(): Promise<void> {
   // ports and sign-in each configured lexicon's emulator uses, not the
   // global command list it used to print.
   if (args.help && args.command === "emulator") {
-    console.log(formatEmulatorHelp(await loadPluginsBestEffort().catch(() => [])));
+    console.log((await emulatorHandlers()).formatEmulatorHelp(await loadPluginsBestEffort().catch(() => [])));
     await flushAndExit(0);
     return;
   }
@@ -2080,6 +2166,14 @@ async function main(): Promise<void> {
   // command gets no `--env` check against the declared environments either.
   const earlyMatch = resolveCommand(args, commandRegistry);
   const runsNoConfig = earlyMatch != null && commandRunsNoConfig(earlyMatch.def, args);
+  // #3878 — load the command's own modules (and the plugin loader, when it
+  // needs plugins) before anything imports TypeScript: once a chant.config.ts
+  // has registered tsx, every module after it is resolved and loaded through
+  // tsx's hooks, which costs far more than plain node.
+  await Promise.all([
+    earlyMatch ? handlerModules.get(earlyMatch.def.handler)?.() : undefined,
+    earlyMatch?.def.requiresPlugins ? import("./plugins") : undefined,
+  ]);
   const projectPath0 = resolve(args.path === "." ? "." : args.path);
   let loadedConfig;
   try {

package/src/cli/mcp/workspace-tools.ts

@@ -51,7 +51,7 @@ const AGENT_ENV = "CHANT_AGENT";
 export type ChantCommand = string[];
 
 /**
- * The chant this process runs as: node with the same flags (the tsx loader
+ * The chant this process runs as: node with the same flags (from source, the tsx loader
  * `bin/chant` registers) and the same entry script.
  */
 export function ownChantCommand(): ChantCommand {

package/src/codegen/pinned-upgrade.ts

@@ -29,6 +29,7 @@ import { regenLexicon, type RegenResult } from "./lexicon-regen";
 import { fetchWithRetry } from "./fetch";
 import { isLexiconPlugin, type UpstreamPin } from "../lexicon";
 import { importLexiconPackage } from "../lexicon-module";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 // ── Public types ──────────────────────────────────────────────────────
 
@@ -251,6 +252,7 @@ export async function loadUpstreamPins(lexicon: LexiconId, lexiconDir?: string):
   const entry = lexiconDir ? lexiconEntry(lexiconDir) : null;
   if (entry) {
     try {
+      ensureTypeScriptLoader();
       const pins = pinsOf((await import(pathToFileURL(entry).href)) as Record<string, unknown>);
       if (pins.length > 0) return pins;
     } catch {

package/src/components/discover.ts

@@ -50,6 +50,7 @@ import { setBuildParams } from "../params";
 import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
 import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 /** One discovered component, paired with the file it was exported from. */
 export interface DiscoveredComponent {
@@ -212,6 +213,7 @@ async function importAndCollectComponents(
       // `filePath` (e.g. from `chant build --components --generate`, which passes
       // a bare "." path) would otherwise be treated by `import()` as a bare
       // package specifier and fail with "Cannot find package 'x.component.ts'".
+      ensureTypeScriptLoader();
       const exports = await import(pathToFileURL(resolve(filePath)).href);
       modules.push({ file: filePath, exports });
     } catch (err) {

package/src/components/pr-pipeline.ts

@@ -38,6 +38,7 @@
 
 import type { ForgeKind } from "../pr-forge";
 import { PR_APPLY_GATE } from "../pr-loop";
+import { CI_IMAGE, GITHUB_JOB_TOKEN } from "../ci-jobs";
 
 /** Where both jobs write their reports, kept as a CI artifact. */
 export const PR_LOOP_REPORT_DIR = ".chant/pr";
@@ -55,7 +56,7 @@ export const PR_APPLY_RECORD = ".chant/pr-resume/pr-apply.json";
  * `PR_LOOP_SETUP` adds OpenTofu on top of it. A caller who sets `image`
  * brings both and gets no setup lines.
  */
-export const PR_LOOP_IMAGE = "node:22";
+export const PR_LOOP_IMAGE = CI_IMAGE;
 
 /** Installs OpenTofu into `PR_LOOP_IMAGE`. */
 export const PR_LOOP_SETUP = [
@@ -113,7 +114,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
     ...(member ? ["--member", member] : []),
   ];
   const github = forge !== "gitlab";
-  const token: Record<string, string> = github ? { GITHUB_TOKEN: "${{ github.token }}" } : {};
+  const token: Record<string, string> = github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {};
   return [
     {
       jobName: "plan",

package/src/components/sandbox/driver.ts

@@ -1,6 +1,7 @@
 import { join, resolve } from "node:path";
 import { params as currentBuildParams } from "../../params";
 import { sendFunctionSource } from "../../discovery/sandbox/driver";
+import { chantSourceDir } from "../../ts-loader";
 
 /**
  * chant #1051 — generates the source of the "driver" module that runs INSIDE
@@ -25,7 +26,8 @@ import { sendFunctionSource } from "../../discovery/sandbox/driver";
  * for the full identity-correctness argument).
  */
 
-const HERE = import.meta.dirname;
+// #3878: the TypeScript source, also when this module runs compiled from dist/.
+const HERE = chantSourceDir(import.meta.url);
 const COMPONENTS_DIR = join(HERE, "..");
 
 /** Absolute paths to chant's OWN trusted modules the generated driver imports — resolved relative to THIS file's own location on disk, exactly like `../../discovery/sandbox/driver.ts` does for the entity path (works whether chant runs from the monorepo or a consumer's `node_modules`). */

package/src/composite.ts

@@ -115,11 +115,23 @@ export class CompositeRegistry {
  * });
  * export const storage = SecureStorage({ name: "data" });
  * ```
+ *
+ * `D` (chant#3787) lets a lexicon give the definition a more precise call
+ * signature than `(props: P) => M`, such as a generic one whose members' types
+ * depend on the literal props it is called with. It is a type only: the value
+ * is the same definition, and `D` must still be a `CompositeDefinition<P, M>`,
+ * so an intersection with the precise signature first is the usual form. It
+ * is passed as a type argument rather than by casting the result, because the
+ * fold recognizes a composite by its `export const X = Composite(...)` shape.
  */
-export function Composite<P, M extends CompositeFactoryMembers = CompositeMembers>(
+export function Composite<
+  P,
+  M extends CompositeFactoryMembers = CompositeMembers,
+  D extends CompositeDefinition<P, M> = CompositeDefinition<P, M>,
+>(
   factory: (props: P) => M,
   name?: string,
-): CompositeDefinition<P, M> {
+): D {
   const id = Symbol();
   const compositeName = name ?? "anonymous";
 
@@ -163,7 +175,7 @@ export function Composite<P, M extends CompositeFactoryMembers = CompositeMember
 
   CompositeRegistry.register(definition as CompositeDefinition<unknown>);
 
-  return definition;
+  return definition as D;
 }
 
 /** Non-enumerable, symbol-keyed: invisible to serializers, spreads and comparisons, like provenance. */

package/src/config-import.ts

@@ -1,5 +1,6 @@
 import { createRequire } from "node:module";
 import { join } from "node:path";
+import { ensureTypeScriptLoader } from "./ts-loader";
 
 /**
  * The single place chant evaluates a project's `chant.config.ts` **in the CLI's
@@ -29,6 +30,7 @@ export type ConfigModuleNamespace = Record<string, unknown>;
  * evaluate the file once — the behavior `loadChantConfig` has always had.
  */
 export async function importConfigModule(configPath: string): Promise<ConfigModuleNamespace> {
+  ensureTypeScriptLoader();
   return (await import(configPath)) as ConfigModuleNamespace;
 }
 
@@ -39,5 +41,6 @@ export async function importConfigModule(configPath: string): Promise<ConfigModu
  */
 export function requireConfigModule(configPath: string, dir: string): ConfigModuleNamespace {
   const req = createRequire(join(dir, "package.json"));
+  ensureTypeScriptLoader();
   return req(configPath) as ConfigModuleNamespace;
 }

package/src/discovery/collect.ts

@@ -4,6 +4,7 @@ import { isCompositeInstance, expandComposite, compositeOfMember } from "../comp
 import { isLexiconOutput } from "../lexicon-output";
 import { DiscoveryError } from "../errors";
 import { setProvenance, type EntityProvenance } from "../provenance";
+import { expandHostComposite, hostCompositeName } from "./host-composite";
 
 /**
  * The entity key for an export. `export default` is per-module — the `Op` pattern
@@ -119,6 +120,18 @@ function enumerateEntries(
             provenance: { sourceFile: file, compositeInstance: name },
           });
         }
+      } else if (hostCompositeName(value) !== undefined) {
+        // chant#3612 — a host composite instance the fold resolved, expanded
+        // here rather than by one caller, so `build()` and `foldProject`
+        // report the same entities for it. See ./host-composite.ts.
+        for (const [expandedName, entity] of expandHostComposite(name, value as Record<string, unknown>)) {
+          entries.push({
+            bareKey: expandedName,
+            value: entity,
+            file,
+            provenance: { sourceFile: file, compositeInstance: name },
+          });
+        }
       } else if (isLexiconOutput(value)) {
         // LexiconOutput is not a Declarable but build() expects to find them in
         // the entities map so it can collect and pass them to serializers.
@@ -133,7 +146,8 @@ function enumerateEntries(
 /**
  * Collects all declarable entities from imported modules.
  * CompositeInstance exports are expanded into individual entities
- * with `{exportName}_{memberName}` naming.
+ * with `{exportName}_{memberName}` naming, and so are host composite
+ * instances the fold resolved (chant#3612, ./host-composite.ts).
  * LexiconOutput exports are also collected so that build() can
  * extract them and pass them to the serializer.
  *

package/src/discovery/fold-build-parity.test.ts

@@ -0,0 +1,71 @@
+/**
+ * chant#3612 — `build()` and `foldProject` report the same entities, under the
+ * same names, with the same provenance, for projects that use composites.
+ *
+ * The two share `collectEntities` and `foldProvenanceOfEntities`; what could
+ * still differ is what each hands them. These fixtures are real examples, one
+ * per lexicon whose composites a project calls, built the way `chant build`
+ * builds them (fold on, the plugins' intrinsics, the lexicon names).
+ */
+import { describe, test, expect, beforeAll } from "vitest";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "../build";
+import { foldProject, type FoldProvenance } from "../index";
+import { findInfraFiles } from "./files";
+import { loadPlugins, resolveProjectLexicons } from "../cli/plugins";
+import type { LexiconPlugin } from "../lexicon";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+
+const FIXTURES = [
+  "lexicons/aws/examples/fargate-alb",
+  "lexicons/aws/examples/lambda-function",
+  "lexicons/aws/examples/multi-service-alb",
+  "lexicons/k8s/examples/batch-workers",
+  "lexicons/k8s/examples/web-platform",
+  "lexicons/sql/examples/postgres-composites",
+];
+
+describe("build() and foldProject agree on composite-using projects (chant#3612)", () => {
+  // Loading a lexicon (aws's generated barrel above all) is the slow part, and
+  // it is not what the tests measure, so it happens once, up front.
+  const pluginsOf = new Map<string, LexiconPlugin[]>();
+  beforeAll(async () => {
+    for (const fixture of FIXTURES) {
+      const project = join(repoRoot, fixture);
+      pluginsOf.set(fixture, await loadPlugins(await resolveProjectLexicons(project)));
+    }
+  }, 60_000);
+
+  test.each(FIXTURES)("%s", async (fixture) => {
+    const src = join(repoRoot, fixture, "src");
+    const plugins = pluginsOf.get(fixture)!;
+    const intrinsics = plugins.flatMap((p) => p.intrinsics?.() ?? []);
+    const lexicons = plugins.map((p) => p.name);
+
+    const built = await build(src, plugins.map((p) => p.serializer), undefined, { fold: true, intrinsics, lexicons });
+    expect(built.errors).toEqual([]);
+
+    const files = await findInfraFiles(src);
+    const verdicts = await foldProject(files, intrinsics, { lexicons });
+    // Same verdict per file. A file that runs (a `chant.config.ts` in `src`)
+    // has no fold provenance in foldProject, so it is left out of both sides.
+    const mode = new Map(built.foldDecisions.map((d) => [d.file, d.mode]));
+    const folded: FoldProvenance = {};
+    for (const [file, verdict] of verdicts) {
+      expect({ file, verdict: verdict.verdict }).toEqual({ file, verdict: mode.get(file) });
+      Object.assign(folded, verdict.foldProvenance);
+    }
+    const foldedFiles = new Set(files.filter((file) => verdicts.get(file)!.verdict === "fold"));
+    expect(foldedFiles.size).toBeGreaterThan(0);
+    const fromBuild = Object.fromEntries(
+      Object.entries(built.foldProvenance).filter(([, record]) => foldedFiles.has(record.sourceFile ?? "")),
+    );
+
+    // The fixture has to exercise a composite, or the comparison proves nothing.
+    expect(Object.values(fromBuild).some((record) => record.composite !== undefined)).toBe(true);
+    expect(Object.keys(folded).sort()).toEqual(Object.keys(fromBuild).sort());
+    expect(folded).toEqual(fromBuild);
+  });
+});