@intentius/chant 0.124.14 → 0.124.16

package/dist/gate-decision.d.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,8 +28,9 @@
  * 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.
@@ -90,15 +92,24 @@ 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 declare function identityGateAdmissionAt(repo: string, base: string, gate: string, opts?: {
     classes?: readonly ClassGrant[];
+    packages?: string;
 }): IdentityGateAdmission | null;
 /** What a pull request's review says about a wave, under `pr-review`. */
 export interface ReviewApproval {

package/dist/gate-decision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-decision.d.ts","sourceRoot":"","sources":["../src/gate-decision.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate-decision.d.ts","sourceRoot":"","sources":["../src/gate-decision.ts"],"names":[],"mappings":"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"}

package/dist/gate-decision.js

@@ -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,13 +28,16 @@
  * 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, latestResolutionForPlan, } from "./lifecycle/gate-ledger-select.js";
 import { samePlanDigest } from "./lifecycle/plan-digest.js";
 import { isApprovalSpent } from "./lifecycle/gate-applied.js";
@@ -41,6 +45,7 @@ import { gateSealRefusal } from "./workspace/trust/gate-seal.js";
 import { DEFAULT_SIGNERS_PATH, TRUST_CONFIG_PATH, parseAllowedSigners, trustConfigProblems, } from "./workspace/trust/trust-files.js";
 import { parseJsonText } from "./workspace/jsonc.js";
 import { CORE_CLASSES, admitApprover } from "./workspace/identity-gate-rule.js";
+import { diskFiles, findInstalledPackage, mergePinClasses, parseClassDataByHand, readClassFiles } from "./workspace/class-data.js";
 export { GATE_APPROVAL_SOURCES } from "./op/op-waves.js";
 export { isPendingGateExpired, latestPendingGate, latestResolutionForPlan, latestResolutionSince, } from "./lifecycle/gate-ledger-select.js";
 export { GATE_SEAL_NAMESPACE, gateSealPayload, gateSealRefusal, sshKeyFingerprint, verifySshSignatureWith, } from "./workspace/trust/gate-seal.js";
@@ -141,6 +146,49 @@ export function identityGatesAt(repo, base) {
     const declaration = declarationAt(repo, base);
     return declaration === null ? [] : identityGatesOf(declaration.value);
 }
+/**
+ * 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, base, pins, packages) {
+    const reads = [];
+    const unread = [];
+    (Array.isArray(pins) ? pins : []).forEach((raw, i) => {
+        const pin = (raw !== null && typeof raw === "object" ? raw : {});
+        if (typeof pin.path === "string" && pin.path) {
+            const dir = posix.normalize(pin.path);
+            const files = (path) => 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;
+        try {
+            installed = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).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)`
@@ -149,11 +197,19 @@ export function identityGatesAt(repo, base) {
  * 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, base, gate, opts = {}) {
@@ -163,16 +219,13 @@ export function identityGateAdmissionAt(repo, base, gate, opts = {}) {
         return null;
     const { signers, roles } = trustAt(repo, base);
     const pins = declaration.value.pins;
-    const rule = {
-        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 = { gate, class: want, signers, roles, classes: [...CORE_CLASSES, ...pinned.classes] };
     return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
 /**

package/dist/gated-waves.d.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
@@ -96,6 +101,20 @@ export declare function waveSetDigest(members: readonly WaveMember[]): string;
  * on a resumed attempt and its approval still applies.
  */
 export declare function waveGateName(gate: string, wave: number): string;
+/** 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 declare function waveDigestMembers<M extends WaveMember & {
+    empty?: boolean;
+}>(members: readonly M[], options?: {
+    over?: WaveDigestOver;
+    extras?: readonly WaveMember[];
+}): WaveMember[];
 /** Where a wave got to. */
 export type WaveStatus = 
 /** Planned, and its gate is not approved for this digest. Nothing in it ran. */

package/dist/gated-waves.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gated-waves.d.ts","sourceRoot":"","sources":["../src/gated-waves.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gated-waves.d.ts","sourceRoot":"","sources":["../src/gated-waves.ts"],"names":[],"mappings":"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"}

package/dist/gated-waves.js

@@ -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
@@ -106,6 +111,16 @@ export function waveSetDigest(members) {
 export function waveGateName(gate, wave) {
     return `${gate}-wave-${wave}`;
 }
+/**
+ * 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(members, options = {}) {
+    const changing = options.over === "changing" ? members.filter((m) => m.empty !== true) : [];
+    return [...(changing.length > 0 ? changing : members), ...(options.extras ?? [])];
+}
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
 /**

package/dist/lifecycle/gate-audit.d.ts

@@ -1,5 +1,7 @@
 import type { GateLedgerPort } from "../op/gate.js";
-export declare const GATE_AUDIT_KINDS: readonly ["approval-requested", "approved", "override-requested", "override-recorded", "revoked", "applied", "override-spent"];
+import type { LedgerReadPort } from "./ledger-port.js";
+import type { GateApprovalSource } from "../op/op-waves.js";
+export declare const GATE_AUDIT_KINDS: readonly ["approval-requested", "approved", "override-requested", "override-recorded", "revoked", "applied", "override-spent", "hook"];
 export type GateAuditKind = (typeof GATE_AUDIT_KINDS)[number];
 /** How an approval was authorised: a forge review, an ssh seal, or neither. A review wins; a review that is also sealed has `sealed: true` beside it. */
 export type GateAuditSeal = "sealed" | "review" | "unsigned";
@@ -63,7 +65,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 {
     /** `sha256:` over where the entry came from: the same sources give the same id. */
@@ -111,8 +113,27 @@ export interface GateAuditEntry {
         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. */
@@ -128,6 +149,40 @@ export interface GateAuditGap {
     digest?: string;
     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;
@@ -143,6 +198,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 declare const POLICY_OVERRIDE_OP = "policy-override";
 /** The default {@link GateAuditOptions.isOverride}. */
@@ -172,4 +229,14 @@ export declare function gateLedgerLinesFromLog(log: string): GateLedgerLine[];
  * history through {@link gateLedgerLinesFromLog} for that.
  */
 export declare function readGateAuditLedgers(port: Pick<GateLedgerPort, "read">, ops: readonly string[]): Promise<GateAuditLedger[]>;
+/**
+ * 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 declare function readGateAuditDecisions(port: Pick<LedgerReadPort, "read" | "list">, dir: string, at: string): Promise<GateAuditDecision[]>;
 //# sourceMappingURL=gate-audit.d.ts.map

package/dist/lifecycle/gate-audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-audit.d.ts","sourceRoot":"","sources":["../../src/lifecycle/gate-audit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gate-audit.d.ts","sourceRoot":"","sources":["../../src/lifecycle/gate-audit.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/gate-audit.js

@@ -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
@@ -86,6 +87,7 @@ export const GATE_AUDIT_KINDS = [
     "revoked",
     "applied",
     "override-spent",
+    "hook",
 ];
 export const POLICY_OVERRIDE_OP = "policy-override";
 /** The default {@link GateAuditOptions.isOverride}. */
@@ -94,12 +96,17 @@ export function isOverrideGate(op, gate) {
 }
 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) => {
     const w = v;
     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) => {
+    const h = v;
+    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) => (v === "ledger" || v === "pr-review" || v === "sealed" ? v : undefined);
 const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
 const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : undefined);
 const time = (iso) => Date.parse(iso) || 0;
@@ -142,6 +149,24 @@ const drop = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !==
 const idOf = (...parts) => contentDigest(canonicalJson(parts));
 /** Whether two digests, either absent, can be the same plan: absent matches anything, as an old line records none. */
 const compatible = (a, b) => a === undefined || b === undefined || samePlanDigest(a, b);
+function decisionOf(d) {
+    let v = d.record;
+    if (v === undefined && d.text !== undefined) {
+        try {
+            v = JSON.parse(d.text);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const r = v;
+    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 && typeof o === "object" && typeof o.moment === "string" && typeof o.name === "string" && typeof o.exit === "number" && typeof o.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) {
     const isOverride = input.isOverride ?? isOverrideGate;
@@ -197,7 +222,7 @@ export function deriveGateAudit(input) {
                     ...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;
@@ -280,6 +305,35 @@ export function deriveGateAudit(input) {
             }));
         }
     }
+    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 };
 }
@@ -339,3 +393,23 @@ export async function readGateAuditLedgers(port, ops) {
     }
     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, dir, at) {
+    const out = [];
+    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/dist/lifecycle/gate-ledger.d.ts

@@ -166,6 +166,19 @@ 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;
@@ -234,6 +247,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>`,