@intentius/chant 0.124.14 → 0.124.16

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

@@ -139,18 +139,71 @@ describe.skipIf(!hasSshKeygen)("identity.gates read at base, as chant reads it",
     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" }] },
+  /** A plugin publishing `classes` at ./workspace-principals, as files under `dir`. */
+  const plugin = (dir: string, classes: unknown[], version = "1.0.0"): Record<string, string> => ({
+    [`${dir}/package.json`]: JSON.stringify({ name: "@acme/ops-classes", version, exports: { "./workspace-principals": "./principals.json" } }),
+    [`${dir}/principals.json`]: JSON.stringify({ schema: 1, classes }),
+  });
+  const OPERATOR = { name: "operator", description: "people who apply infrastructure", role: "operator" };
+  const operatorPolicy = (k: Record<string, Key>) => ({
+    ".chant/allowed_signers": `alice ${k.alice.pub}\nbob ${k.bob.pub}\n`,
+    ".chant/trust.json": JSON.stringify({ schema: 1, roles: { operator: ["alice"], runner: ["bob"] } }),
+  });
+  const install = (r: TestRepo, files: Record<string, string>) => {
+    for (const [path, text] of Object.entries(files)) r.write(path, text);
+  };
+
+  test("a class only a pinned package supplies, read from the installed package as chant reads it (#3888)", () => {
+    const { r, base, approvals } = setup(operatorPolicy, { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] });
+    install(r, plugin("node_modules/@acme/ops-classes", [OPERATOR]));
+    const ours = judgeBoth(r, base, approvals);
+    // alice holds the operator role at base, so she is an operator and no longer human.
+    expect(ours.ops![1]).toBeNull();
+    expect(ours.ops![2]).toBe("BOB  is not in the class operator that gate ops needs: no role grant at base puts them there");
+    expect(ours.deploy![1]).toMatch(/^alice is not in the class human that gate deploy needs/);
+
+    // A bare clone holds no node_modules; the caller names where the packages are installed.
+    const bare = `${r.dir}.git`;
+    r.git(["clone", "-q", "--bare", r.dir, bare]);
+    const fromBare = identityGateAdmissionAt(bare, base, "ops", { packages: r.dir })!;
+    expect(approvals("ops").map((a) => fromBare.refuses(a))).toEqual(ours.ops);
+  });
+
+  test("a path pin's class is read at base, so the change being applied can't remap it", () => {
+    const { r, base, approvals } = setup((k) => ({ ...operatorPolicy(k), ...plugin("plugins/ops", [OPERATOR]) }), { pins: [{ path: "plugins/ops" }] });
+    // After base the plugin moves the operator class to bob's role; base still says operator.
+    install(r, plugin("plugins/ops", [{ ...OPERATOR, role: "runner-ops" }]));
+    r.commit("remaps operator");
+    const ours = judgeBoth(r, base, approvals);
+    expect(ours.ops![1]).toBeNull();
+  });
+
+  test("a pin it cannot read refuses a gate whose class the pin could change, and says why", () => {
+    const { r, base, approvals } = setup(operatorPolicy, { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] });
+    const missing = identityGateAdmissionAt(r.dir, base, "ops")!;
+    expect(missing.refuses(approvals("ops")[1])).toBe(
+      `identity.gates.ops names the class operator, and the pins in chant.workspace.json at base could not all be read, so no approval can show it is in that class: @acme/ops-classes is not installed under ${r.dir}`,
     );
-    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/);
+    // human is everyone in no other class, so an unread pin leaves it unknown too; runner and no class are not affected.
+    expect(identityGateAdmissionAt(r.dir, base, "deploy")!.refuses(approvals("deploy")[1])).toMatch(/names the class human, and the pins .* could not all be read/);
+    expect(identityGateAdmissionAt(r.dir, base, "release")!.refuses(approvals("release")[2])).toBeNull();
+    expect(identityGateAdmissionAt(r.dir, base, "ship")!.refuses(approvals("ship")[1])).toBeNull();
+
+    install(r, plugin("node_modules/@acme/ops-classes", [OPERATOR], "2.0.0"));
+    expect(identityGateAdmissionAt(r.dir, base, "ops")!.refuses(approvals("ops")[1])).toMatch(/: @acme\/ops-classes is pinned at 1\.0\.0, and 2\.0\.0 is installed under /);
+
+    // A class the caller read stands for the pins, as before.
     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("an installed package that supplies no such class refuses as chant does", () => {
+    const { r, base, approvals } = setup(operatorPolicy, { pins: [{ package: "@acme/ops-classes", version: "1.0.0" }] });
+    install(r, plugin("node_modules/@acme/ops-classes", [{ ...OPERATOR, name: "deployer" }]));
+    expect(judgeBoth(r, base, approvals).ops![1]).toMatch(/names the class operator, which no pinned package supplies, .*known classes: human, agent, runner, service, deployer/);
+  });
+
   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`,

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/gated-waves.ts

@@ -2,12 +2,17 @@
  * Gated waves (#3049): one change rolled out across many roots, a wave at a
  * time, each wave behind its own gate bound to that wave's set digest.
  *
- * `chant components fan-out --wave-gate` is the runner. This module holds the
- * parts that need no runner: how a set of roots is cut into waves, what a
- * wave's digest is, what its gate is called, and what the attempt record says
- * about each wave. They are kept apart from the runner because terragucci
- * calls them from its CI stages as one bundled file with no TypeScript
- * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * Two runners use it (#3766): `chant components fan-out --wave-gate` and the
+ * Op waves spec's `chant run wave` (`./op/op-waves-run.ts`). This module
+ * holds the parts that need no runner: how a set of roots is cut into waves,
+ * what a wave's digest is and which members it covers, what its gate is
+ * called, and what the attempt record says about each wave. A gate name
+ * pattern and the share split of a wide wave are in `./wave-layout.ts`;
+ * `./wave-engine.ts` puts them together with the gate decision call and the
+ * record file writer, which need the gate ledger and the filesystem.
+ *
+ * They are kept apart from the runners because terragucci calls them from
+ * its CI stages as one bundled file with no TypeScript toolchain (#3421). Everything here imports `./change-set` and nothing else,
  * and `gated-waves-bundle.test.ts` holds that.
  *
  * ## The set digest
@@ -144,6 +149,23 @@ export function waveGateName(gate: string, wave: number): string {
   return `${gate}-wave-${wave}`;
 }
 
+/** Which members a wave's set digest covers (#3821). */
+export type WaveDigestOver = "all" | "changing";
+
+/**
+ * The members a wave's set digest is taken over (#3821, #3766). `all` (the
+ * default): every member. `changing`: the members whose plan is not
+ * `empty`, or every member when all of them are empty. `extras`, members
+ * that are no run (such as a wave's cost), are always in it.
+ */
+export function waveDigestMembers<M extends WaveMember & { empty?: boolean }>(
+  members: readonly M[],
+  options: { over?: WaveDigestOver; extras?: readonly WaveMember[] } = {},
+): WaveMember[] {
+  const changing = options.over === "changing" ? members.filter((m) => m.empty !== true) : [];
+  return [...(changing.length > 0 ? changing : members), ...(options.extras ?? [])];
+}
+
 /** Where a wave got to. */
 export type WaveStatus =
   /** Planned, and its gate is not approved for this digest. Nothing in it ran. */

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