@intentius/chant 0.124.12 → 0.124.14

package/src/gate-decision-identity.test.ts

@@ -0,0 +1,176 @@
+/**
+ * #3862: `identityGateAdmissionAt` judges an `identity.gates` approval from a
+ * bare clone at a base commit as chant's `gateAdmission(cwd, gate, base)`
+ * does: the seal against the signers at base, and the class against the role
+ * grants at base. Each fixture is judged both ways and the answers compared,
+ * reasons included.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import {
+  admitApprover,
+  CORE_CLASSES,
+  decideGateApproval,
+  GATE_SEAL_NAMESPACE,
+  gateSealPayload,
+  identityGateAdmissionAt,
+  type GateResolutionRecord,
+} from "./gate-decision";
+import { gateAdmission } from "./workspace/identity";
+import { hasSshKeygen, TestRepo, type Key } from "./workspace/trust/test-repo";
+import { evaluateGate, memoryGateLedgerPort } from "./op/gate";
+
+const D1 = "sha256:" + "a".repeat(64);
+const GATES = { ship: {}, deploy: { class: "human" }, release: { class: "runner" }, ops: { class: "operator" } };
+const NAMES = [...Object.keys(GATES), "undeclared"];
+
+describe.skipIf(!hasSshKeygen)("identity.gates read at base, as chant reads it", () => {
+  const repos: TestRepo[] = [];
+  afterEach(() => {
+    while (repos.length) repos.pop()!.cleanup();
+  });
+  // Keys and seals are made once, by ssh-keygen, and shared by every fixture.
+  let signer: TestRepo;
+  let k: Record<"alice" | "bob" | "carol" | "mallory", Key>;
+  const sigs = new Map<string, string>();
+  beforeAll(() => {
+    signer = new TestRepo("3862-keys");
+    k = { alice: signer.key("alice"), bob: signer.key("bob"), carol: signer.key("carol"), mallory: signer.key("mallory") };
+  });
+  afterAll(() => signer.cleanup());
+  const sign = (key: Key, payload: Buffer): string => {
+    const id = `${key.name}\n${payload.toString("utf-8")}`;
+    if (!sigs.has(id)) sigs.set(id, signer.sshSign(key, payload, GATE_SEAL_NAMESPACE));
+    return sigs.get(id)!;
+  };
+
+  function setup(files: (k: Record<string, Key>) => Record<string, string>, declaration: Record<string, unknown> = {}) {
+    const r = new TestRepo("3862-identity");
+    repos.push(r);
+    r.write("chant.workspace.json", JSON.stringify({ name: "acme", schema: 1, members: [], identity: { gates: GATES }, ...declaration }));
+    for (const [path, text] of Object.entries(files(k))) r.write(path, text);
+    const base = r.commit("base");
+    // The change being applied lists mallory and makes alice a runner; neither counts at base.
+    r.write(".chant/allowed_signers", `alice ${k.alice.pub}\nbob ${k.bob.pub}\nmallory ${k.mallory.pub}\n`);
+    r.write(".chant/trust.json", JSON.stringify({ schema: 1, roles: { runner: ["alice", "bob"] } }));
+    r.commit("widens the policy");
+    const approval = (gate: string, resolvedBy: string, extra: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+      version: 1, op: "web", gate, resolvedBy, timestamp: "2026-10-11T11:00:00.000Z", planDigest: D1, ...extra,
+    });
+    const seal = (a: GateResolutionRecord, key: Key, signer = a.resolvedBy): GateResolutionRecord => ({
+      ...a,
+      seal: { signer, key: "k", signature: sign(key, gateSealPayload(a)) },
+    });
+    const made = new Map<string, GateResolutionRecord[]>();
+    const approvals = (gate: string): GateResolutionRecord[] => made.get(gate) ?? (made.set(gate, approvalsOf(gate)), made.get(gate)!);
+    const approvalsOf = (gate: string): GateResolutionRecord[] => [
+      approval(gate, "alice"),
+      seal(approval(gate, "alice"), k.alice),
+      seal(approval(gate, "BOB "), k.bob, "bob"),
+      seal(approval(gate, "mallory"), k.mallory),
+      seal(approval(gate, "carol"), k.carol),
+      seal(approval(gate, "alice"), k.bob),
+      seal(approval(gate, "alice"), k.alice, "bob"),
+      { ...approval(gate, "alice"), seal: { signer: "alice" } as unknown as GateResolutionRecord["seal"] },
+      { ...seal(approval(gate, "alice"), k.alice), planDigest: "sha256:" + "b".repeat(64) },
+    ];
+    return { r, base, approvals };
+  }
+
+  /** Every approval of every gate, judged by both readers: the pairs, and the reasons gate-decision gave. */
+  function judgeBoth(r: TestRepo, base: string, approvals: (gate: string) => GateResolutionRecord[]) {
+    const ours: Record<string, (string | null)[] | null> = {};
+    for (const gate of NAMES) {
+      const here = identityGateAdmissionAt(r.dir, base, gate);
+      const chant = gateAdmission(r.dir, gate, base);
+      expect(here === null, gate).toBe(chant === null);
+      if (here === null || chant === null) {
+        ours[gate] = null;
+        continue;
+      }
+      expect(here.requirement).toEqual({ gate, class: chant.requirement.class });
+      const reasons = approvals(gate).map((a) => here.refuses(a));
+      expect(reasons, gate).toEqual(approvals(gate).map((a) => chant.refuses(a)));
+      ours[gate] = reasons;
+    }
+    return ours;
+  }
+
+  test("signers, role grants and classes at base, approval by approval", () => {
+    const { r, base, approvals } = setup((k) => ({
+      ".chant/allowed_signers": `alice ${k.alice.pub}\nbob ${k.bob.pub}\ncarol namespaces="git" ${k.carol.pub}\n`,
+      ".chant/trust.json": JSON.stringify({ schema: 1, roles: { runner: ["Bob"] } }),
+    }));
+    const ours = judgeBoth(r, base, approvals);
+    expect(ours.undeclared).toBeNull();
+    const passed = (gate: string) => ours[gate]!.flatMap((reason, i) => (reason === null ? [i] : []));
+    // Any signer: alice and bob, each with their own key. Not mallory (listed after base), not carol (no chant-gate namespace).
+    expect(passed("ship")).toEqual([1, 2]);
+    // human: alice; bob holds the runner role at base.
+    expect(passed("deploy")).toEqual([1]);
+    expect(ours.deploy![2]).toMatch(/^BOB  is not in the class human that gate deploy needs/);
+    // runner: bob, by the grant at base; alice's grant comes after base.
+    expect(passed("release")).toEqual([2]);
+    expect(ours.release![1]).toBe("alice is not in the class runner that gate release needs: no role grant at base puts them there");
+    // operator: no pinned package supplies it.
+    expect(passed("ops")).toEqual([]);
+    expect(ours.ops![1]).toMatch(/names the class operator, which no pinned package supplies, .*known classes: human, agent, runner, service/);
+    expect(ours.ship![0]).toBe("the approval by alice is not signed; gate ship needs chant approve --sign");
+    expect(ours.ship![3]).toBe("mallory has no key in .chant/allowed_signers at base, so the seal can't count");
+    expect(ours.ship![4]).toMatch(/^the seal does not verify for carol against \.chant\/allowed_signers at base/);
+  });
+
+  test("a signers path trust.json names", () => {
+    const named = setup((k) => ({
+      ".chant/trust.json": JSON.stringify({ schema: 1, signers: "ops/signers", roles: { runner: ["alice"] } }),
+      "ops/signers": `alice ${k.alice.pub}\n`,
+    }));
+    expect(judgeBoth(named.r, named.base, named.approvals).release![1]).toBeNull();
+  });
+
+  test("no signers file at base, and a trust.json chant refuses", () => {
+    const none = setup(() => ({ "README.md": "x\n" }));
+    expect(judgeBoth(none.r, none.base, none.approvals).ship![1]).toBe("gate ship needs a signed approval, and there is no signers file (.chant/allowed_signers) at base to check one against");
+
+    const invalid = setup((k) => ({
+      ".chant/trust.json": JSON.stringify({ schema: 1, roles: { Admin: ["alice"] } }),
+      ".chant/allowed_signers": `alice ${k.alice.pub}\n`,
+    }));
+    expect(judgeBoth(invalid.r, invalid.base, invalid.approvals).ship![1]).toMatch(/no signers file/);
+  });
+
+  test("a domain class the caller read from a pin, and a pin this reader does not load", () => {
+    const { r, base, approvals } = setup(
+      (k) => ({ ".chant/allowed_signers": `alice ${k.alice.pub}\n`, ".chant/trust.json": JSON.stringify({ schema: 1, roles: { operator: ["alice"] } }) }),
+      { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] },
+    );
+    const unread = identityGateAdmissionAt(r.dir, base, "ops")!;
+    expect(unread.refuses(approvals("ops")[1])).toMatch(/is not a core class, and this reader does not load the classes the pinned packages in chant\.workspace\.json at base supply/);
+    const read = identityGateAdmissionAt(r.dir, base, "ops", { classes: [{ name: "operator", role: "operator" }] })!;
+    expect(read.refuses(approvals("ops")[1])).toBeNull();
+    expect(read.refuses(approvals("ops")[0])).toMatch(/not signed/);
+  });
+
+  test("passed to decideGateApproval as refuses, it counts what chant's wave gate counts", async () => {
+    const { r, base, approvals } = setup((k) => ({
+      ".chant/allowed_signers": `alice ${k.alice.pub}\nbob ${k.bob.pub}\n`,
+      ".chant/trust.json": JSON.stringify({ schema: 1, roles: { runner: ["bob"] } }),
+    }));
+    const here = identityGateAdmissionAt(r.dir, base, "release")!;
+    const chant = gateAdmission(r.dir, "release", base)!;
+    for (const resolutions of [approvals("release").slice(0, 2), approvals("release")]) {
+      const decided = decideGateApproval({ ledger: { pending: [], resolutions }, gate: "release", planDigest: D1, refuses: here.refuses, now: "2026-10-11T12:00:00.000Z" });
+      const port = { ...memoryGateLedgerPort({ pending: [], resolutions }), approvalRule: async () => chant };
+      const check = await evaluateGate(port, { op: "web", gate: "release", planDigest: D1, now: "2026-10-11T12:00:00.000Z" });
+      expect(decided.status === "approved" && decided.via === "ledger" ? decided.resolution : null).toEqual(check.satisfied ? check.resolution : null);
+    }
+  });
+});
+
+describe("admitApprover", () => {
+  test("is the rule gateAdmission judges by: a class it does not know refuses before the seal is read", () => {
+    const rule = { gate: "ship", class: "operator", signers: { signersPath: ".chant/allowed_signers", active: false, signers: [] }, roles: {}, classes: CORE_CLASSES };
+    expect(admitApprover(rule, { op: "web", gate: "ship", resolvedBy: "alice", timestamp: "t" })).toMatch(/no pinned package supplies/);
+    expect(admitApprover({ ...rule, class: null }, { op: "web", gate: "ship", resolvedBy: "alice", timestamp: "t" })).toMatch(/no signers file/);
+  });
+});

package/src/gate-decision.ts

@@ -16,6 +16,12 @@
  *   approving review, when its head planned this digest
  *   ({@link reviewApproval}).
  *
+ * A gate the declaration at base names under `identity.gates` counts only a
+ * sealed approval from its class: {@link identityGateAdmissionAt} reads that
+ * rule from a bare clone at base and judges by `admitApprover`, the function
+ * chant's `gateAdmission` judges by (#3862); pass its `refuses` to
+ * {@link decideGateApproval}.
+ *
  * With `spend` (#3784), an approval a wave already applied under is spent and
  * counts for nothing, as terragucci's wave gate has it: the caller hands in
  * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
@@ -36,7 +42,7 @@ import {
 } from "./lifecycle/gate-ledger-select";
 import { samePlanDigest } from "./lifecycle/plan-digest";
 import { isApprovalSpent, type AppliedGateRecord } from "./lifecycle/gate-applied";
-import { gateSealRefusal, type GateSigners } from "./workspace/trust/gate-seal";
+import { gateSealRefusal, type GateSigners, type SealedGateApproval } from "./workspace/trust/gate-seal";
 import {
   DEFAULT_SIGNERS_PATH,
   TRUST_CONFIG_PATH,
@@ -44,6 +50,7 @@ import {
   trustConfigProblems,
 } from "./workspace/trust/trust-files";
 import { parseJsonText } from "./workspace/jsonc";
+import { CORE_CLASSES, admitApprover, type ClassGrant, type GateAdmissionRule } from "./workspace/identity-gate-rule";
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
 import type { MergedReview } from "./op/gate-review";
 import type { GateApprovalSource } from "./op/op-waves";
@@ -75,6 +82,14 @@ export {
   type SignerSet,
 } from "./workspace/trust/trust-files";
 export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+export {
+  CORE_CLASSES,
+  admitApprover,
+  grantedClasses,
+  type ClassGrant,
+  type GateAdmissionRule,
+  type PrincipalClass,
+} from "./workspace/identity-gate-rule";
 export {
   appliedGateApplies,
   appliedGatePath,
@@ -117,17 +132,12 @@ export function baseCommit(repo: string): string {
   return parent;
 }
 
-/**
- * The signers at `base`: the file `.chant/trust.json` names there, else
- * `.chant/allowed_signers`, read as chant's trust policy reads it. A
- * trust.json that is not valid (`trustConfigProblems`) turns attestation
- * off, as it does in chant, so a sealed gate passes nothing. `base` is a
- * commit the repository holds, such as {@link baseCommit}'s answer.
- */
-export function gateSignersAt(repo: string, base: string): GateSigners {
-  const off = (problems: string[]): GateSigners => ({ base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems });
+/** The signers and role grants at `base`, as chant's trust policy reads them. */
+function trustAt(repo: string, base: string): { signers: GateSigners; roles: Record<string, string[]> } {
+  const off = (problems: string[]) => ({ signers: { base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems }, roles: {} });
   const configText = showAt(repo, base, TRUST_CONFIG_PATH);
   let signersPath = DEFAULT_SIGNERS_PATH;
+  let roles: Record<string, string[]> = {};
   if (configText !== undefined) {
     let raw: unknown;
     try {
@@ -138,9 +148,21 @@ export function gateSignersAt(repo: string, base: string): GateSigners {
     const problems = trustConfigProblems(raw);
     if (problems.length > 0) return off([`${TRUST_CONFIG_PATH} is invalid: ${problems.join("; ")}`]);
     signersPath = (raw as { signers?: string }).signers ?? DEFAULT_SIGNERS_PATH;
+    roles = (raw as { roles?: Record<string, string[]> }).roles ?? {};
   }
   const text = showAt(repo, base, signersPath);
-  return { base, signersPath, active: text !== undefined, signers: text === undefined ? [] : parseAllowedSigners(text).signers, problems: [] };
+  return { signers: { base, signersPath, active: text !== undefined, signers: text === undefined ? [] : parseAllowedSigners(text).signers, problems: [] }, roles };
+}
+
+/**
+ * The signers at `base`: the file `.chant/trust.json` names there, else
+ * `.chant/allowed_signers`, read as chant's trust policy reads it. A
+ * trust.json that is not valid (`trustConfigProblems`) turns attestation
+ * off, as it does in chant, so a sealed gate passes nothing. `base` is a
+ * commit the repository holds, such as {@link baseCommit}'s answer.
+ */
+export function gateSignersAt(repo: string, base: string): GateSigners {
+  return trustAt(repo, base).signers;
 }
 
 /** A gate the declaration at base names under `identity.gates`, and the principal class its signer must be in, if any. */
@@ -149,23 +171,79 @@ export interface IdentityGate {
   class: string | null;
 }
 
-/**
- * The gates `chant.workspace.json` (or `.jsonc`) at `base` names under
- * `identity.gates`: each counts only a sealed approval, from its class when
- * it names one. chant checks the class against the role grants at base; this
- * reads the names. Empty when there is no declaration at base. Throws when
- * the declaration there cannot be parsed, since the gate cannot be decided.
- */
-export function identityGatesAt(repo: string, base: string): IdentityGate[] {
+/** The declaration at `base`, parsed, or null when there is none. Throws when it cannot be parsed. */
+function declarationAt(repo: string, base: string): { file: string; value: unknown } | null {
   for (const file of ["chant.workspace.json", "chant.workspace.jsonc"]) {
     const text = showAt(repo, base, file);
     if (text === undefined) continue;
     const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
     if (!parsed.ok) throw new Error(`${file} at base is not valid JSON (${parsed.message}), so the gate cannot be decided`);
-    const gates = (parsed.value as { identity?: { gates?: Record<string, { class?: unknown } | null> } } | null)?.identity?.gates ?? {};
-    return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+    return { file, value: parsed.value };
   }
-  return [];
+  return null;
+}
+
+function identityGatesOf(declaration: unknown): IdentityGate[] {
+  const gates = (declaration as { identity?: { gates?: Record<string, { class?: unknown } | null> } } | null)?.identity?.gates ?? {};
+  return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+}
+
+/**
+ * The gates `chant.workspace.json` (or `.jsonc`) at `base` names under
+ * `identity.gates`: each counts only a sealed approval, from its class when
+ * it names one. {@link identityGateAdmissionAt} judges an approval by one.
+ * Empty when there is no declaration at base. Throws when the declaration
+ * there cannot be parsed, since the gate cannot be decided.
+ */
+export function identityGatesAt(repo: string, base: string): IdentityGate[] {
+  const declaration = declarationAt(repo, base);
+  return declaration === null ? [] : identityGatesOf(declaration.value);
+}
+
+/** An `identity.gates` gate at base, and the judge for its approvals. */
+export interface IdentityGateAdmission {
+  requirement: IdentityGate;
+  /** Why `approval` does not count toward the gate, or null when it does. Pass it to {@link decideGateApproval} as `refuses`. */
+  refuses(approval: SealedGateApproval): string | null;
+}
+
+/**
+ * The `identity.gates` rule for `gate` at `base`, or null when the
+ * declaration there names none: what chant's `gateAdmission(cwd, gate, base)`
+ * answers, read from a bare clone. An approval counts when its seal verifies
+ * for its approver against the signers at base and, when the gate names a
+ * class, the role grants in `.chant/trust.json` at base put the approver in
+ * it. Both judge with the same function ({@link admitApprover}).
+ *
+ * The classes are the four core ones, then `classes`, the domain classes the
+ * caller read from the pinned packages (`./workspace-principals`), in pin
+ * order. This reader loads no package. A gate whose class is in neither
+ * refuses every approval, and when the declaration at base pins anything the
+ * reason says the pins were not read, since one of them may supply it.
+ * Throws when the declaration at base cannot be parsed.
+ */
+export function identityGateAdmissionAt(
+  repo: string,
+  base: string,
+  gate: string,
+  opts: { classes?: readonly ClassGrant[] } = {},
+): IdentityGateAdmission | null {
+  const declaration = declarationAt(repo, base);
+  const requirement = declaration === null ? undefined : identityGatesOf(declaration.value).find((g) => g.gate === gate);
+  if (!requirement) return null;
+  const { signers, roles } = trustAt(repo, base);
+  const pins = (declaration!.value as { pins?: unknown }).pins;
+  const rule: GateAdmissionRule = {
+    gate,
+    class: requirement.class,
+    signers,
+    roles,
+    classes: [...CORE_CLASSES, ...(opts.classes ?? [])],
+    ...(Array.isArray(pins) && pins.length > 0
+      ? { unknownClass: `is not a core class, and this reader does not load the classes the pinned packages in ${declaration!.file} at base supply` }
+      : {}),
+  };
+  return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
 
 // ── pr-review ────────────────────────────────────────────────────────────

package/src/lexicon-module.ts

@@ -27,6 +27,7 @@
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
+import { ensureTypeScriptLoader } from "./ts-loader";
 
 /**
  * One `lexicons` entry: a package-backed name, or a name plus the module that
@@ -179,6 +180,7 @@ export async function importLexiconModule(name: string): Promise<Record<string,
   const path = modulePaths.get(name);
   if (path === undefined) return undefined;
   try {
+    ensureTypeScriptLoader();
     return (await import(path)) as Record<string, unknown>;
   } catch (err) {
     throw new Error(
@@ -259,6 +261,7 @@ export function resolveFromProject(spec: string, fromDir: string = process.cwd()
  */
 export async function importLexiconPackage(spec: string, fromDir: string = process.cwd()): Promise<Record<string, unknown>> {
   try {
+    ensureTypeScriptLoader();
     return (await import(spec)) as Record<string, unknown>;
   } catch (err) {
     const pkg = packageNameOf(spec);

package/src/lifecycle/gate-ledger.ts

@@ -45,6 +45,7 @@ import { isNeverOverMcpGateOp } from "../op/gate-name";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
+import type { GateApprovalSource } from "../op/op-waves";
 import type { GateRunLocator } from "../op/gate-run-locator";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
@@ -288,6 +289,13 @@ export interface PendingGateRecord {
    * the run produced, and `chant operator status` to show quorum progress.
    */
   approval?: ResolvedGateApproval;
+  /**
+   * The approval mode an Op wave asked under (#3861): `ledger`, `pr-review` or
+   * `sealed`, as read at base. It says which approvals count for the gate, so a
+   * reader (behold, gate-audit) decides under the mode the wave used rather
+   * than inferring it from config. Not the quorum block in `approval`.
+   */
+  approvalMode?: GateApprovalSource;
   /**
    * The open question this gate waits on, on a gate that asks a decision
    * point (#3170). It is answered with `chant workspace points answer <id>`,

package/src/lint/config.ts

@@ -6,7 +6,7 @@ import type { Severity, RuleConfig } from "./rule";
 import type { PostSynthDiagnostic } from "./post-synth";
 import { moduleDir, getRuntime } from "../runtime-adapter";
 import { canonicalRuleId, type RuleMeta } from "../audit/catalog";
-import strictPreset from "./presets/strict.json";
+import strictPreset from "./presets/strict.json" with { type: "json" };
 
 // chant #1117 — the upward config-discovery walk moved to a shared module
 // (`../project-root`) so `chant build`/`lint.policies` use the identical walk

package/src/lint/discover.ts

@@ -10,17 +10,35 @@ import { join } from "path";
 import { createRequire } from "module";
 import type { LintRule } from "./rule";
 import type { PostSynthCheck } from "./post-synth";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
-// Register tsx so createRequire can load TypeScript files in Node.js ESM context.
-// This is a no-op if tsx is not available or already registered.
-try {
-  const _req = createRequire(import.meta.url);
-  const { register } = _req("tsx/cjs/api") as { register: () => void };
-  register();
-} catch {
-  // tsx not available; only pre-compiled .js files can be require()'d
+let cjsTypeScript = false;
+
+/**
+ * Register tsx so createRequire can load TypeScript files in Node.js ESM
+ * context. Does nothing when tsx is not available; then only pre-compiled .js
+ * files can be require()'d.
+ *
+ * From source this runs when the module loads, as it always has: vitest and
+ * the source CLI rely on tsx's CommonJS hook being in place from then on. The
+ * compiled CLI imports this module on every start and most commands read no
+ * rule directory, so there it waits for the first one (#3878).
+ */
+function registerTypeScriptRequire(): void {
+  if (cjsTypeScript) return;
+  cjsTypeScript = true;
+  if (ensureTypeScriptLoader()) return;
+  try {
+    const _req = createRequire(import.meta.url);
+    const { register } = _req("tsx/cjs/api") as { register: () => void };
+    register();
+  } catch {
+    // tsx not available; only pre-compiled .js files can be require()'d
+  }
 }
 
+if (!import.meta.url.endsWith(".js")) registerTypeScriptRequire();
+
 /**
  * Discover lint rules from a directory.
  *
@@ -32,6 +50,7 @@ try {
  * @param importMetaUrl - The caller's import.meta.url (for createRequire)
  */
 export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[] {
+  registerTypeScriptRequire();
   const require = createRequire(importMetaUrl);
   const rules: LintRule[] = [];
 
@@ -62,6 +81,7 @@ export function discoverLintRules(dir: string, importMetaUrl: string): LintRule[
  * @param importMetaUrl - The caller's import.meta.url (for createRequire)
  */
 export function discoverPostSynthChecks(dir: string, importMetaUrl: string): PostSynthCheck[] {
+  registerTypeScriptRequire();
   const require = createRequire(importMetaUrl);
   const checks: PostSynthCheck[] = [];
 

package/src/lint/policy-import.ts

@@ -17,12 +17,14 @@
  * the *decision* and documents the reasoning, and re-exports these three
  * functions as its public surface) for one structural reason: `./policy.ts`
  * needs to consult it, `./policy-sandbox.ts` needs to call `./policy.ts`, and a
- * flag on a leaf module with no imports of its own breaks what would otherwise
+ * flag on a leaf module (its one import, `../ts-loader`, is a leaf too) breaks what would otherwise
  * be an import cycle. It also puts the check on the narrowest possible thing —
  * the function that actually executes project code — rather than on a caller
  * that might forget to ask.
  */
 
+import { ensureTypeScriptLoader } from "../ts-loader";
+
 /** Whether this process must run project policy modules inside the sandbox boundary instead of here. */
 let armed = false;
 
@@ -66,5 +68,6 @@ export async function importPolicyModule(policyPath: string): Promise<PolicyModu
       `Refusing to import the policy module ${policyPath} into the chant process under --sandbox: it is project-authored code and must be imported inside the sandbox boundary (packages/core/src/lint/policy-sandbox.ts's runProjectPolicies).`,
     );
   }
+  ensureTypeScriptLoader();
   return (await import(policyPath)) as PolicyModuleNamespace;
 }

package/src/lint/rule-loader.ts

@@ -1,6 +1,7 @@
 import { readdirSync, existsSync } from "fs";
 import { dirname, join, resolve } from "path";
 import type { LintRule } from "./rule";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 /**
  * Type guard to check if a value conforms to the LintRule interface.
@@ -82,6 +83,7 @@ export async function loadLocalRules(projectDir: string): Promise<LintRule[]> {
     const filePath = resolve(rulesDir, file);
     let mod: Record<string, unknown>;
     try {
+      ensureTypeScriptLoader();
       mod = await import(filePath);
     } catch (err) {
       throw new Error(

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-point.test.ts

@@ -254,6 +254,7 @@ describe("a wave gate that asks a decision point (#3836)", () => {
       members,
       description: "wave 1 of 1: vpc, nat",
       neverOverMcp: true,
+      approvalMode: "ledger",
       answer: { point: "prod-apply" },
     });
     expect(waiting.decision?.pendingFact).toMatchObject({ commit: "c".repeat(40), neverOverMcp: true });

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", "answer",
+  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer",
 ] as const;
 
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
@@ -1068,7 +1068,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, 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 } },
     ...(neverOverMcp ? { neverOverMcp: true } : {}),
   });
   const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };
@@ -1633,7 +1633,8 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
-    ...(decision.pending ? { fields: decision.pending } : {}),
+    // #3861: the approval mode the wave asked under, for readers deciding which approvals count.
+    fields: { ...decision.pending, approvalMode: approval },
     ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
   });
   if (check.satisfied) {
@@ -1697,7 +1698,7 @@ async function settlePointGate(options: RunOpWaveOptions, ctx: WaveContext, deci
     planDigest: digest,
     ...(options.now ? { now: options.now } : {}),
     // #3863: the plans file's pending fields and the spec's neverOverMcp, as settleGate passes them.
-    ...(decision.pending ? { fields: decision.pending } : {}),
+    fields: { ...decision.pending, approvalMode: decision.approval },
     ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
   });
   if (check.satisfied) {

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

@@ -739,8 +739,22 @@ describe("a product's wave gate moved onto the waves (#3821)", () => {
     const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: () => ({ sha: "b".repeat(40), text: JSON.stringify({ ...tg, neverOverMcp: true }) }), gates });
     expect(result.exitCode).toBe(3);
     expect(gates.appended[0]).toMatchObject({ commit: "c".repeat(40), members, description: "wave 1 of 3: vpc, dns, nat", neverOverMcp: true, gate: "wave-1", op: "tf-apply" });
+    // #3861: the approval mode the wave asked under, and a plans file may not set it.
+    expect(gates.appended[0]).toMatchObject({ approvalMode: "ledger" });
     h.done();
 
+    const mode = harness(plans, { pending: { approvalMode: "sealed" } });
+    await expect(runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: mode.cwd, exec: mode.exec, show: mode.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/sets approvalMode, which chant writes itself/);
+    mode.done();
+
+    // A sealed spec at base records "sealed".
+    const sealedSpec: OpWavesSpec = { ...tg, waves: [{ ...tg.waves[0]!, approval: "sealed" }] };
+    const sh = harness(plans, {}, sealedSpec);
+    const sealedGates = memoryGateLedgerPort();
+    await runOpWave({ spec: sealedSpec, specFile: "waves.json", wave: 1, cwd: sh.cwd, exec: sh.exec, show: () => ({ sha: "b".repeat(40), text: JSON.stringify(sealedSpec) }), gates: sealedGates });
+    expect(sealedGates.appended[0]).toMatchObject({ approvalMode: "sealed" });
+    sh.done();
+
     const bad = harness(plans, { pending: { gate: "other" } });
     await expect(runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: bad.cwd, exec: bad.exec, show: bad.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/sets gate, which chant writes itself/);
     bad.done();

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);
+  });
+});