@intentius/chant 0.124.13 → 0.124.15

package/src/gate-decision.ts

@@ -18,8 +18,9 @@
  *
  * 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
+ * rule from a bare clone at base, with the principal classes the pinned
+ * packages supply read as data (#3888), 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
@@ -27,14 +28,17 @@
  * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
  *
  * The module reads the ledger lines and the review it is handed; reading
- * them is the caller's. It imports no TypeScript, esbuild, zod, lint, fold or
- * codegen module, and none of chant's git ledger code, which
+ * them is the caller's. It imports no TypeScript, esbuild, zod, ajv, lint,
+ * fold or codegen module, no package's code, and none of chant's git ledger
+ * code, which
  * `gate-decision-bundle.test.ts` holds it to. Its rules are chant's own:
  * `./lifecycle/gate-ledger-select.ts` is what `evaluateGate` decides by, and
  * `gate-decision.test.ts` decides the same ledgers both ways.
  */
 
 import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, posix } from "node:path";
 import {
   isPendingGateExpired,
   latestPendingGate,
@@ -50,7 +54,8 @@ 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 { CORE_CLASSES, admitApprover, type ClassGrant, type GateAdmissionRule, type PrincipalClass } from "./workspace/identity-gate-rule";
+import { diskFiles, findInstalledPackage, mergePinClasses, parseClassDataByHand, readClassFiles, type PinClassRead } from "./workspace/class-data";
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
 import type { MergedReview } from "./op/gate-review";
 import type { GateApprovalSource } from "./op/op-waves";
@@ -207,6 +212,56 @@ export interface IdentityGateAdmission {
   refuses(approval: SealedGateApproval): string | null;
 }
 
+/** The domain classes the pins of the declaration at base supply, as chant's `loadClassRegistry` reads them, and the pins that could not be read. */
+interface PinnedClasses {
+  classes: PrincipalClass[];
+  /** Pins whose classes are not known, one line each: a package pin that is not installed, or not at its pinned version. */
+  unread: string[];
+}
+
+/**
+ * Read the classes each pin supplies, as chant's `gateAdmission(cwd, gate,
+ * base)` reads them: a path pin's `./workspace-principals` file from `base`
+ * itself, so a change can't remap a class by editing its own copy of the
+ * plugin; a package pin's from the package installed under `packages` (its
+ * `node_modules` or a parent's), which must be at the pinned version. Reads
+ * data only and imports no package.
+ */
+function pinnedClassesAt(repo: string, base: string, pins: unknown, packages: string): PinnedClasses {
+  const reads: PinClassRead[] = [];
+  const unread: string[] = [];
+  (Array.isArray(pins) ? pins : []).forEach((raw: unknown, i) => {
+    const pin = (raw !== null && typeof raw === "object" ? raw : {}) as { package?: unknown; version?: unknown; path?: unknown };
+    if (typeof pin.path === "string" && pin.path) {
+      const dir = posix.normalize(pin.path);
+      const files = (path: string) => showAt(repo, base, dir === "." ? path : posix.join(dir, path));
+      reads.push({ pin: i, source: pin.path, read: readClassFiles(files, pin.path, parseClassDataByHand) });
+      return;
+    }
+    if (typeof pin.package !== "string" || !pin.package) return;
+    const dir = findInstalledPackage(pin.package, packages);
+    if (!dir) {
+      unread.push(`${pin.package} is not installed under ${packages}`);
+      return;
+    }
+    let installed: unknown;
+    try {
+      installed = (JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown }).version;
+    } catch {
+      installed = undefined;
+    }
+    if (typeof pin.version === "string" && pin.version && installed !== pin.version) {
+      unread.push(`${pin.package} is pinned at ${pin.version}, and ${String(installed ?? "an unknown version")} is installed under ${packages}`);
+      return;
+    }
+    reads.push({ pin: i, source: pin.package, read: readClassFiles(diskFiles(dir), pin.package, parseClassDataByHand) });
+  });
+  return { classes: mergePinClasses(reads).classes, unread };
+}
+
+/** The core classes whose members no domain class can change: every one but `human`, which is the principals in no other class. */
+const PIN_FREE = new Set(CORE_CLASSES.filter((c) => c.role !== null).map((c) => c.name));
+
 /**
  * The `identity.gates` rule for `gate` at `base`, or null when the
  * declaration there names none: what chant's `gateAdmission(cwd, gate, base)`
@@ -215,34 +270,39 @@ export interface IdentityGateAdmission {
  * 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.
+ * The classes are the four core ones, then the domain classes the
+ * declaration's pins supply, in pin order (#3888), read as chant reads them:
+ * a path pin's `./workspace-principals` file at `base`, and a package pin's
+ * from the package installed under `packages` (default `repo`) at the
+ * pinned version. A bare clone has no `node_modules`, so a caller that reads
+ * one passes the directory its packages are installed under. Only data is
+ * read; no package is imported. `classes`, when given, stands for every
+ * domain class instead and no pin is read.
+ *
+ * When a pin can't be read (its package is not installed, or not at the
+ * pinned version), a gate whose class it could change (a domain class, or
+ * `human`) refuses every approval and says which pins were not read; a gate
+ * naming `agent`, `runner` or `service`, or no class, is judged as usual.
  * Throws when the declaration at base cannot be parsed.
  */
 export function identityGateAdmissionAt(
   repo: string,
   base: string,
   gate: string,
-  opts: { classes?: readonly ClassGrant[] } = {},
+  opts: { classes?: readonly ClassGrant[]; packages?: string } = {},
 ): 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` }
-      : {}),
-  };
+  const pinned = opts.classes ? { classes: opts.classes, unread: [] } : pinnedClassesAt(repo, base, pins, opts.packages ?? repo);
+  const want = requirement.class;
+  if (want !== null && !PIN_FREE.has(want) && pinned.unread.length > 0) {
+    const reason = `identity.gates.${gate} names the class ${want}, and the pins in ${declaration!.file} at base could not all be read, so no approval can show it is in that class: ${pinned.unread.join("; ")}`;
+    return { requirement, refuses: () => reason };
+  }
+  const rule: GateAdmissionRule = { gate, class: want, signers, roles, classes: [...CORE_CLASSES, ...pinned.classes] };
   return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
 

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

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { deriveGateAudit, gateLedgerLines, gateLedgerLinesFromLog, readGateAuditLedgers, isOverrideGate } from "./gate-audit";
+import { readGateAuditDecisions, deriveGateAudit, gateLedgerLines, gateLedgerLinesFromLog, readGateAuditLedgers, isOverrideGate } from "./gate-audit";
 import { memoryGateLedgerPort } from "../op/gate";
 
 const D1 = "jcs1-sha256:" + "a".repeat(64);
@@ -12,6 +12,15 @@ const resolution = (o: Record<string, unknown> = {}) =>
 const ledger = (op: string, ...texts: string[]) => ({ op, lines: texts.map((text) => ({ text })) });
 
 describe("lifecycle/gate-audit", () => {
+  test("a hold's heldBy and approvalMode are surfaced (#3886, #3887)", () => {
+    const { entries } = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ approvalMode: "sealed", heldBy: { hook: "migrate", moment: "before-apply", target: "vpc" } }))] });
+    expect(entries[0]).toMatchObject({ approvalMode: "sealed", heldBy: { hook: "migrate", moment: "before-apply", target: "vpc" } });
+    expect(entries[0]!.detail).toEqual({});
+    const bad = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ approvalMode: "x", heldBy: { hook: 1 } }))] });
+    expect(bad.entries[0]!.heldBy).toBeUndefined();
+    expect(bad.entries[0]!.approvalMode).toBeUndefined();
+  });
+
   test("a pending fact's wave is surfaced (#3839)", () => {
     const { entries } = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ wave: { number: 2, name: "prod", op: "tg" } }))] });
     expect(entries[0]).toMatchObject({ wave: { number: 2, name: "prod", op: "tg" } });
@@ -179,4 +188,49 @@ describe("lifecycle/gate-audit", () => {
     expect(fromPort.entries.map((e) => e.kind)).toEqual(["approval-requested", "approved"]);
     expect(fromPort.entries.map((e) => e.at)).toEqual(fromText.entries.map((e) => e.at));
   });
+
+  describe("op-wave decision records (#3810)", () => {
+    const outcomes = [
+      { moment: "before-plan", name: "lint", exit: 0, outcome: "passed" },
+      { moment: "after-plan", name: "cost", target: "prod", exit: 2, outcome: "held" },
+      { moment: "before-apply", name: "backup", exit: 1, outcome: "failed" },
+      { moment: "after-apply", name: "skip", exit: 0, outcome: "skipped", reason: "nothing applied" },
+    ];
+    const record = { wave: 1, name: "prod", op: "tf-apply", gate: "wave-1", digest: D1, heldBy: ["cost"], outcomes };
+
+    test("each outcome becomes a hook entry linked to the approval and the apply", () => {
+      const { entries, gaps } = deriveGateAudit({
+        ledgers: [ledger("tf-apply", pending(), resolution())],
+        applies: [{ ref: "reports/1", at: "2026-10-01T12:00:00.000Z", gate: "wave-1", digest: D1 }],
+        decisions: [{ ref: "wave-1.json", at: "2026-10-01T12:05:00.000Z", record }],
+      });
+      expect(gaps).toEqual([]);
+      const hooks = entries.filter((e) => e.kind === "hook");
+      expect(hooks.map((h) => h.hook?.outcome)).toEqual(["passed", "held", "failed", "skipped"]);
+      expect(hooks[1]!.hook).toMatchObject({ moment: "after-plan", name: "cost", target: "prod", exit: 2 });
+      expect(hooks[3]!.hook?.reason).toBe("nothing applied");
+      const approved = entries.find((e) => e.kind === "approved")!;
+      const applied = entries.find((e) => e.kind === "applied")!;
+      for (const h of hooks) expect(h).toMatchObject({ under: approved.id, applied: applied.id, gate: "wave-1", digest: D1, wave: { number: 1, name: "prod" } });
+      expect(new Set(hooks.map((h) => h.id)).size).toBe(4);
+    });
+
+    test("text input, no approval on file, and a malformed record", () => {
+      const { entries, gaps } = deriveGateAudit({
+        ledgers: [],
+        decisions: [{ ref: "a.json", at: "2026-10-01T12:00:00.000Z", text: JSON.stringify(record) }, { ref: "b.json", at: "2026-10-01T12:00:00.000Z", text: "nope" }],
+      });
+      expect(entries.filter((e) => e.kind === "hook")).toHaveLength(4);
+      expect(entries[0]).not.toHaveProperty("under");
+      expect(gaps.map((g) => g.kind)).toEqual(["malformed-line"]);
+    });
+
+    test("readGateAuditDecisions reads the json files under a directory", async () => {
+      const files: Record<string, string> = { "w1.json": JSON.stringify(record), "notes.txt": "x" };
+      const port = { list: async () => Object.keys(files), read: async (_d: string, f: string) => files[f] ?? null };
+      const got = await readGateAuditDecisions(port, "_wave-decisions/tf", "2026-10-01T12:00:00.000Z");
+      expect(got.map((d) => d.ref)).toEqual(["_wave-decisions/tf/w1.json"]);
+      expect(deriveGateAudit({ ledgers: [], decisions: got }).entries).toHaveLength(4);
+    });
+  });
 });

package/src/lifecycle/gate-audit.ts

@@ -21,6 +21,7 @@
  * | `revoked`            | a resolution a commit removed from the file (`subject` says which) |
  * | `applied`            | an apply the caller passes in, with the approval it ran under    |
  * | `override-spent`     | an override an apply the caller passes in cites                  |
+ * | `hook`               | a hook outcome in an op-wave decision record the caller passes in |
  *
  * An override gate is, by default, any gate of the op `policy-override`
  * (terragucci writes one gate per root) or named `override-<rule>` (SQL
@@ -79,6 +80,8 @@ import { canonicalJson } from "../effect-receipt";
 import { contentDigest } from "../content-digest";
 import { samePlanDigest } from "./plan-digest";
 import type { GateLedgerPort } from "../op/gate";
+import type { LedgerReadPort } from "./ledger-port";
+import type { GateApprovalSource } from "../op/op-waves";
 
 export const GATE_AUDIT_KINDS = [
   "approval-requested",
@@ -88,6 +91,7 @@ export const GATE_AUDIT_KINDS = [
   "revoked",
   "applied",
   "override-spent",
+  "hook",
 ] as const;
 export type GateAuditKind = (typeof GATE_AUDIT_KINDS)[number];
 
@@ -155,7 +159,7 @@ export interface GateAuditSource {
   commit?: string;
   /** The commit that added the line, or for a revocation removed it, when the line came from history. */
   author?: GateLedgerCommit;
-  change: "added" | "removed" | "apply";
+  change: "added" | "removed" | "apply" | "decision";
 }
 
 export interface GateAuditEntry {
@@ -193,8 +197,16 @@ export interface GateAuditEntry {
   description?: string;
   /** Pending facts an op wave wrote for a policy denial or a hold (#3839): the wave they belong to. */
   wave?: { number: number; name: string; op?: string };
+  /** Pending facts of a hold (#3886): the hook that holds the wave. */
+  heldBy?: { hook: string; moment: string; target?: string };
+  /** Pending facts of an op wave (#3861): the approval mode the wave asked under. */
+  approvalMode?: GateApprovalSource;
   /** Overrides: the rules the denial named (from the denial line when there is one). */
   rules?: string[];
+  /** A hook entry: the hook's moment, name, run, how it came out, and why a moment was skipped (#3810). */
+  hook?: { moment: string; name: string; target?: string; outcome: "passed" | "failed" | "held" | "skipped"; exit: number; reason?: string };
+  /** A hook entry: the applied entry of the same wave and digest, if the caller passed that apply in. */
+  applied?: string;
   /** A revoked entry: what was revoked. */
   subject?: "approval" | "override";
   /** An applied entry: the approval entry it ran under, if one is held. An override-spent entry: the override entry. */
@@ -212,6 +224,35 @@ export interface GateAuditGap {
   detail: string;
 }
 
+/**
+ * An op-wave decision record (`.chant/op-waves/<name>/wave-<k>.json`, written
+ * by `chant run wave`), as far as the audit reads it: the wave's gate and
+ * digest, and the `outcomes` of its hooks (#3804, #3811, #3847). Typed
+ * structurally so this file imports nothing from `../op/`.
+ */
+export interface WaveDecisionRecord {
+  wave: number;
+  name: string;
+  op: string;
+  gate: string;
+  digest?: string;
+  heldBy?: string[];
+  heldOn?: unknown;
+  outcomes?: ReadonlyArray<{ moment: string; name: string; target?: string; exit: number; outcome: string; reason?: string }>;
+}
+
+/**
+ * A decision record the caller passes in. The record carries no time and no
+ * place, so `ref` (a file path, an artifact, a row) and `at` (when it was
+ * written) come from the caller. Give the parsed `record`, or its `text`.
+ */
+export interface GateAuditDecision {
+  ref: string;
+  at: string;
+  record?: unknown;
+  text?: string;
+}
+
 export interface GateAuditOptions {
   /** Whether a gate is an override gate. Default: op `policy-override`, or a gate named `override-...`. */
   isOverride?: (op: string, gate: string) => boolean;
@@ -228,6 +269,8 @@ export interface GateAuditOptions {
 export interface GateAuditInput extends GateAuditOptions {
   ledgers: readonly GateAuditLedger[];
   applies?: readonly GateAuditApply[];
+  /** Op-wave decision records: each hook outcome in them becomes a `hook` entry linked to the wave's approval and apply (#3810). */
+  decisions?: readonly GateAuditDecision[];
 }
 
 export const POLICY_OVERRIDE_OP = "policy-override";
@@ -241,13 +284,18 @@ type Row = Record<string, unknown>;
 
 const KNOWN = new Set([
   "version", "kind", "op", "gate", "resolvedBy", "relayedBy", "timestamp", "note", "url", "planDigest", "environment",
-  "approver", "seal", "review", "runId", "expiresAt", "description", "wave", "rules", "pr", "head", "reviewers",
+  "approver", "seal", "review", "runId", "expiresAt", "description", "wave", "heldBy", "approvalMode", "rules", "pr", "head", "reviewers",
 ]);
 
 const waveOf = (v: unknown): { number: number; name: string; op?: string } | undefined => {
   const w = v as { number?: unknown; name?: unknown; op?: unknown } | null;
   return w && typeof w === "object" && typeof w.number === "number" && typeof w.name === "string" ? { number: w.number, name: w.name, ...(typeof w.op === "string" ? { op: w.op } : {}) } : undefined;
 };
+const heldByOf = (v: unknown): { hook: string; moment: string; target?: string } | undefined => {
+  const h = v as { hook?: unknown; moment?: unknown; target?: unknown } | null;
+  return h && typeof h === "object" && typeof h.hook === "string" && typeof h.moment === "string" ? { hook: h.hook, moment: h.moment, ...(typeof h.target === "string" ? { target: h.target } : {}) } : undefined;
+};
+const modeOf = (v: unknown): GateApprovalSource | undefined => (v === "ledger" || v === "pr-review" || v === "sealed" ? v : undefined);
 const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
 const strings = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : undefined);
 const time = (iso: string): number => Date.parse(iso) || 0;
@@ -302,6 +350,23 @@ interface Seen {
 /** Whether two digests, either absent, can be the same plan: absent matches anything, as an old line records none. */
 const compatible = (a: string | undefined, b: string | undefined): boolean => a === undefined || b === undefined || samePlanDigest(a, b);
 
+function decisionOf(d: GateAuditDecision): WaveDecisionRecord | undefined {
+  let v: unknown = d.record;
+  if (v === undefined && d.text !== undefined) {
+    try {
+      v = JSON.parse(d.text);
+    } catch {
+      return undefined;
+    }
+  }
+  const r = v as Row | null;
+  if (!r || typeof r !== "object" || typeof r.wave !== "number" || typeof r.name !== "string" || typeof r.op !== "string" || typeof r.gate !== "string") return undefined;
+  const outcomes = Array.isArray(r.outcomes)
+    ? r.outcomes.filter((o): o is NonNullable<WaveDecisionRecord["outcomes"]>[number] => !!o && typeof o === "object" && typeof (o as Row).moment === "string" && typeof (o as Row).name === "string" && typeof (o as Row).exit === "number" && typeof (o as Row).outcome === "string")
+    : undefined;
+  return { wave: r.wave, name: r.name, op: r.op, gate: r.gate, ...(str(r.digest) ? { digest: str(r.digest) } : {}), ...(strings(r.heldBy) ? { heldBy: strings(r.heldBy) } : {}), ...(r.heldOn !== undefined ? { heldOn: r.heldOn } : {}), ...(outcomes ? { outcomes } : {}) };
+}
+
 /** The entries `input` adds up to, oldest first, and the gaps they show. */
 export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntry[]; gaps: GateAuditGap[] } {
   const isOverride = input.isOverride ?? isOverrideGate;
@@ -359,7 +424,7 @@ export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntr
           ...base,
           kind: override ? "override-requested" : "approval-requested",
           at: String(r.timestamp),
-          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules), wave: waveOf(r.wave) }),
+          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules), wave: waveOf(r.wave), heldBy: heldByOf(r.heldBy), approvalMode: modeOf(r.approvalMode) }),
           detail: extra,
         }));
         continue;
@@ -450,6 +515,35 @@ export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntr
     }
   }
 
+  for (const d of input.decisions ?? []) {
+    const rec = decisionOf(d);
+    if (!rec) {
+      gaps.push({ kind: "malformed-line", detail: `${d.ref} is not an op-wave decision record` });
+      continue;
+    }
+    const approval = rec.digest === undefined ? undefined : entries
+      .filter((e) => e.kind === "approved" && e.gate === rec.gate && e.op === rec.op && e.digest !== undefined && samePlanDigest(e.digest, rec.digest!))
+      .sort((x, y) => time(y.at) - time(x.at))[0];
+    const applied = rec.digest === undefined ? undefined : entries.find((e) => e.kind === "applied" && e.gate === rec.gate && e.digest !== undefined && samePlanDigest(e.digest, rec.digest!));
+    for (const [i, o] of (rec.outcomes ?? []).entries()) {
+      if (o.outcome !== "passed" && o.outcome !== "failed" && o.outcome !== "held" && o.outcome !== "skipped") continue;
+      entries.push(keyed({
+        id: idOf("hook", d.ref, d.at, i, o),
+        kind: "hook",
+        at: d.at,
+        gate: rec.gate,
+        op: rec.op,
+        ...(rec.digest ? { digest: rec.digest } : {}),
+        ...(approval ? { under: approval.id } : {}),
+        ...(applied ? { applied: applied.id } : {}),
+        hook: { moment: o.moment, name: o.name, ...(o.target ? { target: o.target } : {}), outcome: o.outcome, exit: o.exit, ...(o.reason ? { reason: o.reason } : {}) },
+        wave: { number: rec.wave, name: rec.name, op: rec.op },
+        detail: drop({ heldBy: rec.heldBy?.length ? rec.heldBy : undefined, heldOn: o.outcome === "held" ? rec.heldOn : undefined }),
+        source: { path: d.ref, op: rec.op, change: "decision" },
+      }));
+    }
+  }
+
   entries.sort((x, y) => time(x.at) - time(y.at));
   return { entries, gaps };
 }
@@ -510,3 +604,22 @@ export async function readGateAuditLedgers(port: Pick<GateLedgerPort, "read">, o
   }
   return out;
 }
+
+/**
+ * The thin reader for decision records kept on the ledger branch: every
+ * `.json` file directly under `dir` (such as a product's `_wave-decisions/<name>`),
+ * as input for {@link GateAuditInput.decisions}. A decision record holds no
+ * time, so `at` stamps them all: when the product collected them. Where the
+ * records live is the product's business; chant writes them to
+ * `.chant/op-waves/<name>/wave-<k>.json` in the job, and a product that
+ * collects them elsewhere passes them in directly.
+ */
+export async function readGateAuditDecisions(port: Pick<LedgerReadPort, "read" | "list">, dir: string, at: string): Promise<GateAuditDecision[]> {
+  const out: GateAuditDecision[] = [];
+  for (const file of (await port.list(dir)).sort()) {
+    if (!file.endsWith(".json")) continue;
+    const text = await port.read(dir, file);
+    if (text !== null) out.push({ ref: `${dir}/${file}`, at, text });
+  }
+  return out;
+}

package/src/lifecycle/gate-ledger.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import {
   appendGateResolution, appendPendingGate, readGateResolutions, readGateLedger,
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
-  resolveApprovalUrl, isApprovalUrl, latestResolutionForPlan,
+  resolveApprovalUrl, isApprovalUrl, latestResolutionForPlan, parseGateLedger,
   type PendingGateRecord, type GateResolutionRecord,
 } from "./gate-ledger";
 import { readBlobFromPath, writeBlobToPath } from "./git";
@@ -484,3 +484,22 @@ describe("gate ledger newline termination (#3849)", () => {
     });
   });
 });
+
+describe("pending fact wave and heldBy (#3886, #3887)", () => {
+  const line = (o: Record<string, unknown>) =>
+    JSON.stringify({ version: 1, kind: "pending", op: "tg", gate: "g", timestamp: "2026-10-01T00:00:00Z", expiresAt: "2026-10-02T00:00:00Z", ...o });
+  test("the reader types wave, heldBy and approvalMode", () => {
+    const { pending } = parseGateLedger(line({ approvalMode: "pr-review", wave: { number: 2, name: "prod", op: "tg" }, heldBy: { hook: "migrate", moment: "before-apply", target: "vpc" } }));
+    const p: PendingGateRecord = pending[0]!;
+    expect(p.wave).toEqual({ number: 2, name: "prod", op: "tg" });
+    expect(p.heldBy).toEqual({ hook: "migrate", moment: "before-apply", target: "vpc" });
+    expect(p.approvalMode).toBe("pr-review");
+  });
+  test("a wave or heldBy of the wrong shape is dropped, the line is kept", () => {
+    const { pending, malformed } = parseGateLedger(line({ wave: { number: "2" }, heldBy: "migrate" }));
+    expect(malformed).toBe(0);
+    expect(pending).toHaveLength(1);
+    expect(pending[0]!.wave).toBeUndefined();
+    expect(pending[0]!.heldBy).toBeUndefined();
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -228,6 +228,21 @@ export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">
  * ledger by a line a minute. Once `expiresAt` passes, the fact is stale and
  * the next run records a fresh one.
  */
+export interface PendingGateWave {
+  number: number;
+  name: string;
+  /** The Op waves spec's name. */
+  op?: string;
+}
+
+/** The hook that holds a wave on a gate (#3886): which hook asked, at which moment, and for which run. */
+export interface PendingGateHeldBy {
+  hook: string;
+  moment: string;
+  /** The run, for a `perRun` hook. */
+  target?: string;
+}
+
 export interface PendingGateRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
   version: 1;
@@ -296,6 +311,17 @@ export interface PendingGateRecord {
    * than inferring it from config. Not the quorum block in `approval`.
    */
   approvalMode?: GateApprovalSource;
+  /**
+   * The Op wave this gate belongs to (#3839): a hold on another gate or a
+   * policy denial. Absent on a gate that is not a wave's.
+   */
+  wave?: PendingGateWave;
+  /**
+   * The hook that holds the wave on this gate (#3886), on a hold only: its
+   * name, the moment it ran at and its run. A reader names the holder from it
+   * rather than from `description`, which the hook writes.
+   */
+  heldBy?: PendingGateHeldBy;
   /**
    * 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>`,
@@ -449,7 +475,13 @@ export function parseGateLedger(
           malformed++;
           continue;
         }
-        pending.push(parsed as PendingGateRecord);
+        // #3887: a `wave` or `heldBy` of the wrong shape is dropped, so a reader can trust the type.
+        const rec = parsed as PendingGateRecord;
+        const w = (parsed as { wave?: unknown }).wave as Partial<PendingGateWave> | null | undefined;
+        if (w !== undefined && !(w && typeof w === "object" && typeof w.number === "number" && typeof w.name === "string")) delete rec.wave;
+        const h = (parsed as { heldBy?: unknown }).heldBy as Partial<PendingGateHeldBy> | null | undefined;
+        if (h !== undefined && !(h && typeof h === "object" && typeof h.hook === "string" && typeof h.moment === "string")) delete rec.heldBy;
+        pending.push(rec);
         continue;
       }
       if (typeof parsed.resolvedBy !== "string") {

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(