@intentius/chant 0.124.13 → 0.124.15

package/src/op/activities/activity-contracts.ts

@@ -271,7 +271,7 @@ export const lifecyclePlanChangeSetContract = activityContract(
 
 export const readChangeSetPartContract = activityContract(
   "readChangeSetPart",
-  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden"]), file: z.string(), lexicon: z.string().optional() }),
+  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden", "sql"]), file: z.string(), lexicon: z.string().optional() }),
   z.object({ part: changeSetPart }),
 );
 

package/src/op/activities/change-set.ts

@@ -25,6 +25,7 @@ import { promisify } from "node:util";
 import {
   composeChangeSet as compose,
   lifecyclePlanPart,
+  readChangeSetPartFile,
   reconcilePlanPart,
   type ChangeSetDocument,
   type ChangeSetPart,
@@ -87,8 +88,12 @@ export async function lifecyclePlanChangeSet(args: LifecyclePlanChangeSetArgs, s
 
 export interface ReadChangeSetPartArgs {
   member: string;
-  /** Which planner wrote the file: `chant` (`lifecycle plan --json`) or `warden` (its reconcile change sets). */
-  planner: "chant" | "warden";
+  /**
+   * Which planner wrote the file: `chant` (`lifecycle plan --json`), `warden`
+   * (its reconcile change sets), or `sql` (a part the sql lexicon's
+   * `change-set` adapters produced, written as JSON).
+   */
+  planner: "chant" | "warden" | "sql";
   /** The plan file, relative to the current directory. */
   file: string;
   /** The lexicon the entries belong to, when the plan does not say. */
@@ -98,7 +103,8 @@ export interface ReadChangeSetPartArgs {
 /**
  * A plan another step or job wrote to a file, as a member's part. A warden
  * plan is the reconcile `ChangeSet` (`@intentius/chant/reconcile`), or an
- * array of them, one per cycle and org.
+ * array of them, one per cycle and org. A sql plan is already a part
+ * (`@intentius/chant-lexicon-sql/change-set`), renamed to `member` here.
  */
 export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<ChangeSetPartResult> {
   const plan: unknown = JSON.parse(readFileSync(resolve(args.file), "utf-8"));
@@ -108,6 +114,8 @@ export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<Ch
       return { part: lifecyclePlanPart({ member: args.member, plan: plan as LifecycleChangeSet, ...lexicon }) };
     case "warden":
       return { part: reconcilePlanPart({ member: args.member, plan: plan as ReconcileChangeSet | ReconcileChangeSet[], ...lexicon }) };
+    case "sql":
+      return { part: readChangeSetPartFile(plan, "sql", args.member, args.lexicon) };
     default:
       throw new Error(`readChangeSetPart: no adapter for planner ${String(args.planner)}; terraform-family plans come from terraformPlan's changeSet`);
   }

package/src/op/activities/lexicon-upgrade.test.ts

@@ -317,6 +317,8 @@ describe("lexiconUpgrade issue mode", () => {
 
     vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
     vi.stubEnv("GITHUB_API_URL", "");
+    // A Forgejo run, since CHANT_FORGEJO_TOKEN is only read there (#3807).
+    vi.stubEnv("FORGEJO_ACTIONS", "true");
     // The cross-instance case (#2320): a Forgejo token that must outrank the
     // job's own `github.token`, on the path that used to forward neither.
     vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-cross-instance");

package/src/op/activities/reconcile.test.ts

@@ -21,6 +21,7 @@ import {
   ghCredentialEnv,
   githubShapedForgeFrom,
 } from "./reconcile";
+import { FORGE_TOKEN_ORDER } from "../../pr-forge";
 
 // ── The `gh` stub (chant #2291) ──────────────────────────────────────────────
 //
@@ -338,12 +339,46 @@ describe("commentTokenFrom (#2291)", () => {
     expect(commentTokenFrom({ GITHUB_TOKEN: "ghs_y" })).toEqual({ value: "ghs_y", source: "GITHUB_TOKEN" });
   });
 
-  test("CHANT_FORGEJO_TOKEN wins over both, for the cross-instance case", () => {
+  test("on Forgejo CHANT_FORGEJO_TOKEN wins, then FORGEJO_TOKEN, then GH_TOKEN, then GITHUB_TOKEN", () => {
+    const base = { FORGEJO_ACTIONS: "true" };
+    const all = { CHANT_FORGEJO_TOKEN: "a", FORGEJO_TOKEN: "b", GH_TOKEN: "c", GITHUB_TOKEN: "d" };
+    expect(commentTokenFrom({ ...base, ...all })?.source).toBe("CHANT_FORGEJO_TOKEN");
+    expect(commentTokenFrom({ ...base, FORGEJO_TOKEN: "b", GH_TOKEN: "c", GITHUB_TOKEN: "d" })?.source).toBe("FORGEJO_TOKEN");
+    expect(commentTokenFrom({ ...base, GH_TOKEN: "c", GITHUB_TOKEN: "d" })?.source).toBe("GH_TOKEN");
+  });
+
+  test("a /api/v1 API base is Forgejo even without FORGEJO_ACTIONS", () => {
     expect(
-      commentTokenFrom({ CHANT_FORGEJO_TOKEN: "a", GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source,
+      commentTokenFrom({ GITHUB_API_URL: "https://f.example/api/v1", CHANT_FORGEJO_TOKEN: "a", GH_TOKEN: "b" })?.source,
     ).toBe("CHANT_FORGEJO_TOKEN");
   });
 
+  test("on GitHub CHANT_GITHUB_TOKEN wins, then GH_TOKEN, then GITHUB_TOKEN (#3807)", () => {
+    const base = { GITHUB_ACTIONS: "true" };
+    expect(commentTokenFrom({ ...base, CHANT_GITHUB_TOKEN: "a", GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source).toBe("CHANT_GITHUB_TOKEN");
+    expect(commentTokenFrom({ ...base, GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source).toBe("GH_TOKEN");
+  });
+
+  test("on GitHub CHANT_FORGEJO_TOKEN and FORGEJO_TOKEN are not read (#3807)", () => {
+    expect(
+      commentTokenFrom({ GITHUB_ACTIONS: "true", CHANT_FORGEJO_TOKEN: "a", FORGEJO_TOKEN: "b", GH_TOKEN: "c" }),
+    ).toEqual({ value: "c", source: "GH_TOKEN" });
+    expect(commentTokenFrom({ GITHUB_ACTIONS: "true", CHANT_FORGEJO_TOKEN: "a" })).toBeUndefined();
+  });
+
+  test("agrees with FORGE_TOKEN_ORDER for each forge", () => {
+    for (const [kind, env] of [
+      ["github", { GITHUB_ACTIONS: "true" }],
+      ["forgejo", { FORGEJO_ACTIONS: "true" }],
+    ] as const) {
+      for (const name of FORGE_TOKEN_ORDER[kind]) {
+        const rest = FORGE_TOKEN_ORDER[kind].slice(FORGE_TOKEN_ORDER[kind].indexOf(name));
+        const vars = Object.fromEntries(rest.map((n) => [n, `v-${n}`]));
+        expect(commentTokenFrom({ ...env, ...vars })?.source).toBe(name);
+      }
+    }
+  });
+
   test("no token at all is undefined rather than an empty value", () => {
     expect(commentTokenFrom({})).toBeUndefined();
     expect(commentTokenFrom({ GH_TOKEN: "", GITHUB_TOKEN: "" })).toBeUndefined();
@@ -469,6 +504,31 @@ describe("reconcilePr comment mode posts through the forge client (#2291, #3757)
     }
   });
 
+  test("on a GitHub run CHANT_FORGEJO_TOKEN is ignored and GH_TOKEN is sent (#3807)", async () => {
+    stubPrEnv("https://api.github.com");
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-token-set-on-github");
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      expect(forgeCalls.length).toBeGreaterThan(0);
+      for (const call of forgeCalls) expect(call.authorization).toBe("Bearer forgejo-actions-token");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  test("on a GitHub run CHANT_GITHUB_TOKEN outranks GH_TOKEN (#3807)", async () => {
+    stubPrEnv("https://api.github.com");
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("CHANT_GITHUB_TOKEN", "other-github-token");
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      for (const call of forgeCalls) expect(call.authorization).toBe("Bearer other-github-token");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   test("FORGEJO_ACTIONS marks a Forgejo run whatever its API base looks like", async () => {
     stubPrEnv("https://code.example/api/forgejo");
     vi.stubEnv("FORGEJO_ACTIONS", "true");

package/src/op/activities/reconcile.ts

@@ -1,7 +1,15 @@
 import { exec } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
-import { ForgeApiError, forgejoForge, githubForge, type ForgeFetch, type GithubShapedForge } from "../../pr-forge";
+import {
+  detectForge,
+  FORGE_TOKEN_ORDER,
+  ForgeApiError,
+  forgejoForge,
+  githubForge,
+  type ForgeFetch,
+  type GithubShapedForge,
+} from "../../pr-forge";
 import { ghHostEnv } from "./gh-host";
 import { restPullRequestForge } from "./forge-pull-request";
 
@@ -49,9 +57,11 @@ const execAsync = promisify(exec);
  * of opening a second one.
  *
  * Both modes resolve the GitHub/Forgejo credential the same way, through
- * {@link commentTokenFrom}: `CHANT_FORGEJO_TOKEN`, then `GH_TOKEN`, then
- * `GITHUB_TOKEN` (chant #2320), refusing by name before any call when none
- * is set ({@link noCommentTokenMessage}, {@link noIssueTokenMessage}).
+ * {@link commentTokenFrom}, in pr-forge's `FORGE_TOKEN_ORDER` for the forge the
+ * run is on (chant #2320, #3807): `CHANT_GITHUB_TOKEN`, `GH_TOKEN`,
+ * `GITHUB_TOKEN` on GitHub; `CHANT_FORGEJO_TOKEN`, `FORGEJO_TOKEN`,
+ * `GH_TOKEN`, `GITHUB_TOKEN` on Forgejo. It refuses by name before any call
+ * when none is set ({@link noCommentTokenMessage}, {@link noIssueTokenMessage}).
  *
  * Until #3757 these two modes shelled to `gh api`. That reached Forgejo only
  * after two fixes: a full URL, because `gh` resolves a relative path against
@@ -451,24 +461,38 @@ export interface CommentToken {
   source: string;
 }
 
+/**
+ * Which GitHub-shaped forge a run is on: Forgejo when `detectForge` says so
+ * (`FORGEJO_ACTIONS`/`GITEA_ACTIONS`, or a `GITHUB_API_URL` ending in
+ * `/api/v1`), or when the API base ends in `/api/v1`, which is how a step
+ * posting to some other Forgejo instance names it. GitHub serves `/api/v3`
+ * or `api.github.com`, never `/api/v1`. Anything else is GitHub.
+ */
+export function githubShapedKindFrom(env: Record<string, string | undefined>): "github" | "forgejo" {
+  if (detectForge(env) === "forgejo") return "forgejo";
+  return /\/api\/v1$/.test(githubApiBaseFrom(env)) ? "forgejo" : "github";
+}
+
 /**
  * Resolve the token the `comment` and `issue` modes post with on GitHub and
- * Forgejo, most specific first (chant #2291). The generated workflow sets
- * `GH_TOKEN` and `GITHUB_TOKEN` to `${{ github.token }}` for every
- * non-`report` finding mode — on
- * Forgejo the same way as on GitHub, and the real-instance read confirmed
- * `github.token` is populated there and good for a 200 read and a 201 write,
- * authored as `forgejo-actions`. So the common case needs nothing set beyond
- * what the generator already emits.
+ * Forgejo (chant #2291), in pr-forge's `FORGE_TOKEN_ORDER` for the forge the
+ * run is on (#3807), so this and `forgeTargetFromEnv` cannot drift apart.
+ * GitHub reads `CHANT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`; Forgejo reads
+ * `CHANT_FORGEJO_TOKEN`, `FORGEJO_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`. The
+ * generated workflow sets `GH_TOKEN` and `GITHUB_TOKEN` to
+ * `${{ github.token }}` for every non-`report` finding mode, on Forgejo the
+ * same way as on GitHub, so the common case needs nothing set beyond what the
+ * generator already emits.
  *
- * `CHANT_FORGEJO_TOKEN` is checked first for the case that ambient token
- * cannot cover: a run posting to a Forgejo instance other than the one the
- * job executes on, where `github.token`'s scope stops at its own instance.
- * A run with none of the three is refused by name before any call, in place
- * of the forge's own opaque 401.
+ * The chant-specific variable comes first for the case that ambient token
+ * cannot cover: a run posting to an instance other than the one the job
+ * executes on, where `github.token`'s scope stops at its own instance.
+ * `CHANT_FORGEJO_TOKEN` is no longer read on a GitHub run. A run with none of
+ * the names is refused by name before any call, in place of the forge's own
+ * opaque 401.
  */
 export function commentTokenFrom(env: Record<string, string | undefined>): CommentToken | undefined {
-  for (const source of ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
+  for (const source of FORGE_TOKEN_ORDER[githubShapedKindFrom(env)]) {
     const value = env[source]?.trim();
     if (value) return { value, source };
   }
@@ -543,8 +567,8 @@ export function noCommentTokenMessage(repo: string, number: number): string {
   return (
     `reconcilePr mode "comment" has pull request ${repo}#${number} to post its finding on and no token to ` +
     "post it with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions " +
-    "or Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
-    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+    "or Forgejo Actions run — set CHANT_GITHUB_TOKEN (GitHub) or CHANT_FORGEJO_TOKEN (Forgejo) to post " +
+    "against a different instance than the one the job runs on. It is read first where the two must differ."
   );
 }
 
@@ -553,8 +577,8 @@ export function noIssueTokenMessage(repo: string): string {
   return (
     `reconcilePr mode "issue" has repository ${repo} to open or edit its finding in and no token to do it ` +
     "with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions or " +
-    "Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
-    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+    "Forgejo Actions run — set CHANT_GITHUB_TOKEN (GitHub) or CHANT_FORGEJO_TOKEN (Forgejo) to post " +
+    "against a different instance than the one the job runs on. It is read first where the two must differ."
   );
 }
 
@@ -582,7 +606,7 @@ export function githubShapedForgeFrom(
   signal?: AbortSignal,
 ): GithubShapedForge {
   const apiBase = githubApiBaseFrom(env);
-  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true" || /\/api\/v1$/.test(apiBase);
+  const forgejo = githubShapedKindFrom(env) === "forgejo";
   // Read at call time, so a test that stubs the global sees its stub.
   const fetchImpl: ForgeFetch = (url, init) => globalThis.fetch(url, { ...init, ...(signal ? { signal } : {}) });
   const opts = { apiBase, repo, token: token.value, fetch: fetchImpl };

package/src/op/builders.ts

@@ -428,7 +428,7 @@ export const lifecyclePlanChangeSet = (args: WithStepRefs<LifecyclePlanChangeSet
   return activity("lifecyclePlanChangeSet", rest, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
 };
 
-/** A member's change-set part from a plan file a chant or warden run wrote (#3181). Its `part` feeds {@link composeChangeSet}. */
+/** A member's change-set part from a plan file a chant, warden or sql run wrote (#3181, #3767). Its `part` feeds {@link composeChangeSet}. */
 export const readChangeSetPart = (args: WithStepRefs<ReadChangeSetPartArgs> & StepOpts): NamedActivityStep => {
   const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
   return activity("readChangeSetPart", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });

package/src/op/discover.ts

@@ -6,6 +6,7 @@ import { walkDiscovery, workspaceMemberDirs } from "../discovery/walk";
 import { hasDiscoveryMarkerSync } from "../discovery/files";
 import { resolveDiscoveryGlobs } from "../config";
 import { isStewardDeclaration, type StewardDeclaration } from "./steward";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -150,6 +151,7 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   for (const filePath of files) {
     try {
+      ensureTypeScriptLoader();
       const mod = (await import(filePath)) as Record<string, unknown>;
       const exported = opsExportedBy(mod);
 
@@ -220,6 +222,7 @@ export async function discoverStewards(opts?: { cwd?: string }): Promise<Steward
   for (const filePath of files) {
     let mod: Record<string, unknown>;
     try {
+      ensureTypeScriptLoader();
       mod = (await import(filePath)) as Record<string, unknown>;
     } catch (err) {
       errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);

package/src/op/op-waves-run.ts

@@ -130,7 +130,7 @@ export interface OpWavePlansFile {
 /** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
 export const OP_WAVE_PENDING_RESERVED = [
   "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
-  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer",
+  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy",
 ] as const;
 
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
@@ -835,6 +835,7 @@ interface HooksOutcome {
 interface OtherGateHold {
   label: string;
   name: string;
+  moment: OpWaveHookMoment;
   target?: string;
   argv: string[];
   env: Record<string, string>;
@@ -914,7 +915,7 @@ function runHookList(
         out.outcomes.push({ ...base, outcome: "held" });
         const request = readHoldRequest(join(cwd, holdPath), log, label);
         if (request) {
-          out.otherGates.push({ label, name, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
+          out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
           log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
           continue;
         }
@@ -1068,7 +1069,7 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold): Promise<O
     description: hold.request.description ?? `wave ${k} (${wave.name}) of ${spec.name} is held on it by ${hold.label}`,
     now,
     // #3839: the wave a hold belongs to, as a field, whatever the hook's own description says.
-    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name } },
+    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name }, heldBy: { hook: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}) } },
     ...(neverOverMcp ? { neverOverMcp: true } : {}),
   });
   const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };

package/src/op/op-waves.test.ts

@@ -910,6 +910,8 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     expect(gates.appended[0]).toMatchObject({ op: "tf-migrate", gate: "split-queues", planDigest: digest("m"), members: [] });
     // #3839: the hold names its wave as a field, even when the hook wrote the description.
     expect(gates.appended[0]).toMatchObject({ description: "move the queues", wave: { number: 1, name: expect.any(String), op: tg.name } });
+    // #3886: and the hook that holds it, as a field.
+    expect(gates.appended[0]).toMatchObject({ heldBy: { hook: "migrate", moment: expect.any(String) } });
     expect(h.calls.some((c) => c.startsWith("tg plan"))).toBe(false);
     expect(h.envs.find((e) => e.CHANT_HOOK === "after-gate")).toMatchObject({ CHANT_GATE_STATUS: "waiting", CHANT_GATE_OP: "tf-migrate", CHANT_GATE: "split-queues" });
     h.done();

package/src/op/work-lease-run.test.ts

@@ -4,7 +4,7 @@
  * when it ends, and a lost lease stopping the run. An Op that changes the
  * checkout runs its leased steps in a worktree of its own.
  */
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -230,6 +230,11 @@ describe("a run under a work lease", () => {
   }, 30_000);
 
   test("a lease lost mid-step stops the step and the run, which fails lease-lost and releases nothing", async () => {
+    // The heartbeat is the only timer faked: the test fires its beat itself
+    // once the thief holds the lease, instead of waiting a wall-clock second
+    // for a renewal that a loaded machine can delay past any fixed bound.
+    vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+    try {
     await withTestDir(async (dir) => {
       await initRepo(dir);
       const log: string[] = [];
@@ -241,9 +246,9 @@ describe("a run under a work lease", () => {
             // The lease runs out from under this run and another worker takes it.
             await releaseWorkLease(lease.item, lease.holder, { cwd: dir, token: lease.token });
             expect((await claimWorkLease(lease.item, "thief", { cwd: dir, ttlMs: 60_000 })).ok).toBe(true);
-            await new Promise<void>((resolve, reject) => {
-              const t = setTimeout(() => reject(new Error("never stopped")), 20_000);
-              signal?.addEventListener("abort", () => { clearTimeout(t); log.push("stopped"); reject(new Error("aborted")); }, { once: true });
+            await new Promise<void>((_resolve, reject) => {
+              signal?.addEventListener("abort", () => { log.push("stopped"); reject(new Error("aborted")); }, { once: true });
+              void vi.advanceTimersByTimeAsync(1_000);
             });
             return {};
           },
@@ -270,6 +275,9 @@ describe("a run under a work lease", () => {
       expect((await listWorkLeases({ cwd: dir, memberPrefix: "" }))[0]).toMatchObject({ holder: "thief", state: "active" });
       expect((await readRunLedger("local", "dispatch", { cwd: dir })).records.at(-1)?.status).toBe("fail");
     });
+    } finally {
+      vi.useRealTimers();
+    }
   }, 30_000);
 
   test("a run whose lease was lost before it is recorded is never recorded as done", async () => {

package/src/ts-loader.test.ts

@@ -0,0 +1,23 @@
+import { join, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { chantSourceDir, ensureTypeScriptLoader } from "./ts-loader";
+
+describe("ts-loader (#3878)", () => {
+  const pkg = join(sep, "x", "node_modules", "@intentius", "chant");
+
+  test("chantSourceDir maps a compiled module's directory to its source directory", () => {
+    const url = pathToFileURL(join(pkg, "dist", "discovery", "sandbox", "driver.js")).href;
+    expect(chantSourceDir(url)).toBe(join(pkg, "src", "discovery", "sandbox"));
+    expect(chantSourceDir(pathToFileURL(join(pkg, "dist", "params.js")).href)).toBe(join(pkg, "src"));
+  });
+
+  test("chantSourceDir leaves a source module's directory alone", () => {
+    const url = pathToFileURL(join(pkg, "src", "discovery", "sandbox", "driver.ts")).href;
+    expect(chantSourceDir(url)).toBe(join(pkg, "src", "discovery", "sandbox"));
+  });
+
+  test("from source, the TypeScript loader is already there and nothing is registered", () => {
+    expect(ensureTypeScriptLoader()).toBe(false);
+  });
+});

package/src/ts-loader.ts

@@ -0,0 +1,122 @@
+/**
+ * #3878 — TypeScript loading for the compiled CLI.
+ *
+ * An installed chant runs `dist/cli/main.js` with plain `node`, so chant's own
+ * modules need no loader. Everything else chant imports at run time still can
+ * be TypeScript: a project's `chant.config.ts` and source files, `*.op.ts`,
+ * policies and lint rules, and the lexicon packages, which ship `src/*.ts`.
+ * {@link ensureTypeScriptLoader} registers tsx for those, the first time one of
+ * them is about to be imported, so a command that imports none (`--version`,
+ * `run wave` on a project with no `chant.config.ts`) never loads tsx at all.
+ *
+ * {@link installCompiledCli} also points every resolution of chant's own
+ * source at the compiled file next to it. A lexicon or project file imports
+ * `@intentius/chant`, and the package exports resolve that to `src/*.ts`;
+ * without the redirect that import would load a second copy of core,
+ * transpiled, beside the one the CLI runs, with its own registries and
+ * classes.
+ *
+ * Run from source (the repository's `bin/chant` through tsx, vitest), this
+ * module is itself TypeScript, the TypeScript loader is already there, and
+ * both functions do nothing.
+ */
+
+import { existsSync } from "node:fs";
+import * as nodeModule from "node:module";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// `module.registerHooks` (Node 22.15+, 24) is newer than the @types/node the
+// repository pins, so its shape is declared here.
+interface ResolveResult {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+type NextResolve = (specifier: string, context?: unknown) => ResolveResult;
+const { createRequire, registerHooks } = nodeModule as unknown as {
+  createRequire: typeof nodeModule.createRequire;
+  registerHooks: (hooks: { resolve: (specifier: string, context: unknown, nextResolve: NextResolve) => ResolveResult }) => unknown;
+};
+
+interface CompiledCliState {
+  /** Whether tsx has been registered in this process. */
+  tsx: boolean;
+}
+
+const STATE = Symbol.for("chant.compiledCli");
+
+function compiledState(): CompiledCliState | undefined {
+  return (globalThis as { [STATE]?: CompiledCliState })[STATE];
+}
+
+/** True when this module runs as compiled JavaScript, from `<package>/dist`. */
+function runsCompiled(): boolean {
+  return import.meta.url.endsWith(".js");
+}
+
+/**
+ * Called once by the CLI's `main()`. Compiled, it records that TypeScript
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
+ * source it does nothing.
+ */
+export function installCompiledCli(): void {
+  if (!runsCompiled() || compiledState()) return;
+  (globalThis as { [STATE]?: CompiledCliState })[STATE] = { tsx: false };
+
+  const distDir = dirname(fileURLToPath(import.meta.url));
+  const srcUrl = pathToFileURL(join(dirname(distDir), "src") + sep).href;
+  const distUrl = pathToFileURL(distDir + sep).href;
+  const compiled = new Map<string, string | null>();
+
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const result = nextResolve(specifier, context);
+      if (!result.url.startsWith(srcUrl)) return result;
+      const path = result.url.slice(srcUrl.length).replace(/[?#].*$/, "");
+      if (!path.endsWith(".ts") || path.endsWith(".d.ts")) return result;
+      let target = compiled.get(path);
+      if (target === undefined) {
+        const js = distUrl + path.slice(0, -3) + ".js";
+        target = existsSync(fileURLToPath(js)) ? js : null;
+        compiled.set(path, target);
+      }
+      return target === null ? result : { ...result, url: target, format: "module" };
+    },
+  });
+}
+
+/**
+ * Register tsx for the ESM and CommonJS loaders, once, before importing
+ * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
+ * is already loading chant itself. Returns whether the compiled CLI's tsx
+ * registration covers this process, so a caller that registers its own
+ * CommonJS hook from source knows not to add a second one.
+ */
+export function ensureTypeScriptLoader(): boolean {
+  const state = compiledState();
+  if (!state) return false;
+  if (state.tsx) return true;
+  state.tsx = true;
+  const require = createRequire(import.meta.url);
+  (require("tsx/cjs/api") as { register: () => unknown }).register();
+  (require("tsx/esm/api") as { register: () => unknown }).register();
+  return true;
+}
+
+/**
+ * The source directory for a module of chant's own: `dirname` of `moduleUrl`
+ * from source, and the matching directory under `<package>/src` when the
+ * module runs from `<package>/dist`. The sandbox drivers hand chant's own
+ * modules to esbuild by path, and must name the TypeScript source the
+ * project's own `@intentius/chant/*` imports resolve to. String arithmetic
+ * only: no filesystem access, so it is safe inside a sandboxed child.
+ */
+export function chantSourceDir(moduleUrl: string): string {
+  const dir = dirname(fileURLToPath(moduleUrl));
+  if (!moduleUrl.endsWith(".js")) return dir;
+  const marker = `${sep}dist${sep}`;
+  const at = (dir + sep).lastIndexOf(marker);
+  if (at < 0) return dir;
+  return dir.slice(0, at) + `${sep}src` + dir.slice(at + marker.length - 1);
+}

package/src/workspace/__fixtures__/contract-repo.ts

@@ -4,7 +4,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { chmodSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
@@ -56,6 +56,22 @@ export function repo(files: Record<string, string | { text: string; mode: number
   return root;
 }
 
+/**
+ * Build a fixture repository once per test file and hand each caller a copy of
+ * it. A repo costs a dozen git processes (init, add, commit, config), and a
+ * file copy none, so a file whose tests each start from the same repo builds
+ * it once (#3880). The template is rebuilt if {@link cleanScratch} removed it.
+ */
+export function repoFixture(build: () => string, prefix = "chant-contract-copy-"): () => string {
+  let template: string | undefined;
+  return () => {
+    if (template === undefined || !existsSync(template)) template = build();
+    const root = scratchDir(prefix);
+    cpSync(template, root, { recursive: true });
+    return root;
+  };
+}
+
 export function commitAll(root: string, message = "next"): string {
   git(root, "add", "-A");
   git(root, "commit", "-q", "-m", message);

package/src/workspace/__fixtures__/sessions.ts

@@ -7,19 +7,19 @@
 import { cpSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { sessionSeal } from "../record-sessions";
-import { commitAll, git, REPO, scratchDir } from "./contract-repo";
+import { commitAll, git, REPO, repoFixture, scratchDir } from "./contract-repo";
 
 export const SESSIONS_KIND = "design/sessions/session.kind.mjs";
 export const DECISIONS_KIND = "decisions/decision.kind.mjs";
 
 /** A git repository holding a copy of the reference workspace's decisions and design member. */
-export function sessionsRepo(): string {
+export const sessionsRepo = repoFixture(() => {
   const root = scratchDir("chant-sessions-");
   for (const d of ["decisions", "design"]) cpSync(join(REPO, "reference-workspace", d), join(root, d), { recursive: true });
   git(root, "init", "-q");
   commitAll(root, "reference");
   return root;
-}
+}, "chant-sessions-");
 
 /** A session file's text, sealed when it is closed. */
 export function sessionText(s: { id: string; state: "open" | "closed"; verdicts?: { record: string; principal: string; verdict: string }[]; agenda?: string[] }): string {

package/src/workspace/change-set.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json",
   "title": "change-set document",
-  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu and warden members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
+  "description": "One change set across planners (#3181): what a combined run's chant, terraform, tofu, choudoufu, warden and sql members will change, a summary, and the digest a gate binds. Written by the composeChangeSet Op activity and by composeChangeSet in @intentius/chant/change-set. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version.",
   "type": "object",
   "required": [
     "$schema",
@@ -87,7 +87,8 @@
             "tofu",
             "choudoufu",
             "chant",
-            "warden"
+            "warden",
+            "sql"
           ]
         },
         "scope": {
@@ -171,7 +172,8 @@
             "tofu",
             "choudoufu",
             "chant",
-            "warden"
+            "warden",
+            "sql"
           ]
         },
         "address": {

package/src/workspace/chant-migrations/chud-lexicon-exit.ts

@@ -47,7 +47,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, posix } from "node:path";
 import yaml from "js-yaml";
-import answerSchema from "../point-answer.schema.json";
+import answerSchema from "../point-answer.schema.json" with { type: "json" };
 import { fileHash } from "../lineage-lock";
 import { DECISION_POINTS_SCHEMA_ID, POINT_INPUT_OUTPUT_NAMES, parsePoints, PointsError } from "../points";
 import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, NotMoved, PlanConflict, PlannedChange } from "../chant-migrations";