@intentius/chant 0.124.13 → 0.124.15

package/dist/lifecycle/gate-audit.js

@@ -0,0 +1,415 @@
+/**
+ * An audit trail from the gate ledger (#3764, decision #3756). Pure: ledger
+ * lines (and, if the product has them, the applies that ran under a gate) go
+ * in; typed entries and the gaps they show come out. It reads no git, no
+ * clock and no file, so it bundles into a product's single CI file
+ * (`gate-audit-bundle.test.ts` holds the import graph).
+ *
+ * Both products derived this themselves: terragucci's `report/audit.ts` and
+ * SQL Yodeler's `report/audit.ts` each parse `_gates/<op>.jsonl`. Storage
+ * (an append-only record, a bucket, a history table) and rendering stay with
+ * them.
+ *
+ * ## Entries
+ *
+ * | kind                 | source line                                                      |
+ * |----------------------|------------------------------------------------------------------|
+ * | `approval-requested` | a pending fact of a gate that is not an override                 |
+ * | `approved`           | a resolution of such a gate (seal, approver, review, relay)      |
+ * | `override-requested` | a pending fact of an override gate: a denial that waits          |
+ * | `override-recorded`  | a resolution of an override gate (reason in `note`)              |
+ * | `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
+ * Yodeler's `yodel override`). chant's override gate (#3760,
+ * `../override-gate.ts`) records under the op `policy-override`, so the
+ * default reads it, and its `overrideAuditApplies` turns applied records into
+ * applies that cite the override they spent. {@link GateAuditOptions.isOverride}
+ * replaces the rule. Anything a line carries beyond the typed fields is kept in
+ * `detail`, and `kind` is checked against {@link GATE_AUDIT_KINDS} only by
+ * the type, never by the reader.
+ *
+ * ## Gaps
+ *
+ * - `approval-without-request`: a resolution with no pending fact of its gate
+ *   before it (or none for its digest). Overrides are exempt: both products
+ *   may record one without a denial on file.
+ * - `unsealed`: an approval or override with neither a seal nor a pull
+ *   request review, where {@link GateAuditOptions.sealed} says the gate needs
+ *   one.
+ * - `approval`: an apply with a digest that no approval of its gate holds
+ *   for that digest, recorded at or before the apply. Needs `approval:
+ *   "not-required"` to be waived, as a baseline or a policy that asked for
+ *   no approval does.
+ * - `override`: an apply cites an override that no line holds.
+ * - `malformed-line`: a line that is not a gate record. Its content is lost
+ *   to the trail, so it is said.
+ *
+ * ## Sources and ids
+ *
+ * Every ledger entry's `source` names the line it came from: `path`, `line`
+ * (the line's own `line` when given, which {@link gateLedgerLines} fills
+ * with the file's line number, else its 1-based place in `ledger.lines`),
+ * and `text`, exactly as passed in, when the line was given as text. When the
+ * line came from {@link gateLedgerLinesFromLog}, `source.author` is the
+ * author of the commit that added it (or, for a revocation, removed it), and
+ * resolutions also carry it as `committedBy`. Under `approval: ledger` that
+ * is the only check on who pushed an approval: anyone who can push may write
+ * any `resolvedBy`.
+ *
+ * The default `id` is a digest over the source and the record. A product
+ * that already holds ids of its own (an append-only record whose ids
+ * customers keep) passes {@link GateAuditOptions.id}, which gets each entry
+ * with its default id and returns the id to use. `under` links follow it.
+ *
+ * ## Seal and review
+ *
+ * `seal` names how the approval came to be: `review` when the line came
+ * through a forge review (`via: "pr-review"`, or a `review` field), else
+ * `sealed` when it carries an ssh seal, else `unsigned`. A pull request
+ * approval that `chant approve` also sealed is still `review`: the review is
+ * what authorised it, and the seal attests who wrote the line. That fact is
+ * kept apart as `sealed: true` with its `signer`, on any entry whose line
+ * holds a seal. terragucci classifies the same way.
+ */
+import { canonicalJson } from "../effect-receipt.js";
+import { contentDigest } from "../content-digest.js";
+import { samePlanDigest } from "./plan-digest.js";
+export const GATE_AUDIT_KINDS = [
+    "approval-requested",
+    "approved",
+    "override-requested",
+    "override-recorded",
+    "revoked",
+    "applied",
+    "override-spent",
+    "hook",
+];
+export const POLICY_OVERRIDE_OP = "policy-override";
+/** The default {@link GateAuditOptions.isOverride}. */
+export function isOverrideGate(op, gate) {
+    return op === POLICY_OVERRIDE_OP || gate.startsWith("override-");
+}
+const KNOWN = new Set([
+    "version", "kind", "op", "gate", "resolvedBy", "relayedBy", "timestamp", "note", "url", "planDigest", "environment",
+    "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;
+function rowOf(line) {
+    let v = line.record;
+    if (v === undefined && line.text !== undefined) {
+        try {
+            v = JSON.parse(line.text);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+function sealOf(r) {
+    const s = r.seal;
+    const signed = s && s.signature ? { sealed: true, ...(str(s.signer) ? { signer: str(s.signer) } : {}) } : undefined;
+    if (r.review || r.via === "pr-review")
+        return { seal: "review", ...signed };
+    return signed ? { seal: "sealed", ...signed } : { seal: "unsigned" };
+}
+function reviewOf(r) {
+    const rv = (r.review ?? undefined);
+    const pr = typeof rv?.pr === "number" ? rv.pr : typeof r.pr === "number" ? r.pr : undefined;
+    const head = str(rv?.head) ?? str(r.head);
+    const approvers = strings(rv?.approvers) ?? strings(r.reviewers);
+    if (pr === undefined && head === undefined && approvers === undefined)
+        return undefined;
+    return { ...(pr !== undefined ? { pr } : {}), ...(head ? { head } : {}), ...(approvers ? { approvers } : {}) };
+}
+function approverOf(r) {
+    const a = r.approver;
+    if (!a || typeof a.kind !== "string")
+        return undefined;
+    const roles = strings(a.roles);
+    return { kind: a.kind, ...(roles ? { roles } : {}) };
+}
+const drop = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+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;
+    const rekey = input.id;
+    const keyed = (e) => (rekey ? { ...e, id: rekey(e) } : e);
+    const entries = [];
+    const gaps = [];
+    for (const ledger of input.ledgers) {
+        const path = ledger.path ?? `_gates/${ledger.op}.jsonl`;
+        const parsed = [];
+        for (const [i, line] of ledger.lines.entries()) {
+            const r = rowOf(line);
+            const pending = r?.kind === "pending";
+            const ok = r && r.version === 1 && typeof r.gate === "string" && typeof r.timestamp === "string" && (pending || typeof r.resolvedBy === "string");
+            if (!r || !ok) {
+                gaps.push({ kind: "malformed-line", op: ledger.op, detail: `${path} holds a line that is not a gate record${line.commit ? ` (commit ${line.commit})` : ""}: ${(line.text ?? JSON.stringify(line.record) ?? "").slice(0, 80)}` });
+                continue;
+            }
+            parsed.push({ line, n: line.line ?? i + 1, r, pending });
+        }
+        // Each denial an override answers: the newest pending fact of its gate and digest.
+        const denials = new Map();
+        const requests = [];
+        for (const p of parsed) {
+            if (!p.pending || p.line.removed)
+                continue;
+            const digest = str(p.r.planDigest);
+            denials.set(`${String(p.r.gate)}\n${digest ?? ""}`, p.r);
+            requests.push({ op: ledger.op, gate: String(p.r.gate), at: time(String(p.r.timestamp)), ...(digest ? { digest } : {}), ...(str(p.r.environment) ? { environment: str(p.r.environment) } : {}) });
+        }
+        for (const { line, n, r, pending } of parsed) {
+            const gate = String(r.gate);
+            const override = isOverride(ledger.op, gate);
+            const removed = line.removed;
+            if (pending && removed)
+                continue;
+            const digest = str(r.planDigest);
+            const author = removed ?? line.added;
+            const source = {
+                path,
+                op: ledger.op,
+                line: n,
+                ...(line.text !== undefined ? { text: line.text } : {}),
+                ...(line.commit ? { commit: line.commit } : {}),
+                ...(author ? { author } : {}),
+                change: removed ? "removed" : "added",
+            };
+            const id = idOf(removed ? "removed" : "ledger", path, line.commit ?? null, r);
+            const extra = Object.fromEntries(Object.entries(r).filter(([k]) => !KNOWN.has(k)));
+            const base = { id, gate, op: ledger.op, ...(digest ? { digest } : {}), source };
+            if (pending) {
+                entries.push(keyed({
+                    ...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), heldBy: heldByOf(r.heldBy), approvalMode: modeOf(r.approvalMode) }),
+                    detail: extra,
+                }));
+                continue;
+            }
+            const { seal, sealed, signer } = sealOf(r);
+            if (removed) {
+                entries.push(keyed({
+                    ...base,
+                    kind: "revoked",
+                    at: removed.at,
+                    ...(removed.by ? { by: removed.by } : {}),
+                    subject: override ? "override" : "approval",
+                    seal,
+                    ...(sealed ? { sealed } : {}),
+                    detail: { ...extra, approvedBy: r.resolvedBy, approvedAt: r.timestamp, ...(signer ? { signer } : {}) },
+                }));
+                continue;
+            }
+            const denial = override ? denials.get(`${gate}\n${digest ?? ""}`) : undefined;
+            const rules = strings(denial?.rules) ?? (override && gate.startsWith("override-") ? [gate.slice("override-".length)] : undefined);
+            const entry = keyed({
+                ...base,
+                kind: override ? "override-recorded" : "approved",
+                at: String(r.timestamp),
+                by: String(r.resolvedBy),
+                seal,
+                ...drop({ sealed, signer, committedBy: line.added?.by, relayedBy: str(r.relayedBy), approver: approverOf(r), note: str(r.note), url: str(r.url), review: reviewOf(r), rules }),
+                detail: extra,
+            });
+            entries.push(entry);
+            if (!override) {
+                const at = time(entry.at);
+                const env = str(r.environment);
+                const asked = requests.some((q) => q.gate === gate && q.at <= at && compatible(q.digest, digest) && (q.environment === undefined || env === undefined || q.environment === env));
+                if (!asked) {
+                    gaps.push({ kind: "approval-without-request", op: ledger.op, gate, ...(digest ? { digest } : {}), detail: `${path} holds an approval of ${gate} by ${entry.by} at ${entry.at} with no pending fact of that gate${digest ? " and digest" : ""} before it` });
+                }
+            }
+            if (seal === "unsigned" && input.sealed?.(ledger.op, gate)) {
+                gaps.push({ kind: "unsealed", op: ledger.op, gate, ...(digest ? { digest } : {}), detail: `${path} holds ${override ? "an override" : "an approval"} of ${gate} by ${entry.by} at ${entry.at} with no seal and no review, and the gate needs one` });
+            }
+        }
+    }
+    const held = entries.filter((e) => e.kind === "approved" || e.kind === "override-recorded");
+    for (const a of input.applies ?? []) {
+        const base = { gate: a.gate, ...(a.op ? { op: a.op } : {}), ...(a.digest ? { digest: a.digest } : {}), source: { path: a.ref, ...(a.op ? { op: a.op } : {}), change: "apply" } };
+        const at = time(a.at);
+        const find = (kind, gate, digest, before) => held
+            .filter((e) => e.kind === kind && e.gate === gate && (a.op === undefined || e.op === a.op) && (digest === undefined ? true : e.digest !== undefined && samePlanDigest(e.digest, digest)) && (!before || time(e.at) <= at))
+            .sort((x, y) => time(y.at) - time(x.at))[0];
+        const approval = a.digest !== undefined && a.approval !== "not-required" ? find("approved", a.gate, a.digest, true) : undefined;
+        if (a.digest !== undefined && a.approval !== "not-required" && !approval) {
+            gaps.push({ kind: "approval", ...(a.op ? { op: a.op } : {}), gate: a.gate, digest: a.digest, detail: `${a.ref} applied under ${a.digest}, but the ledger holds no approval of ${a.gate} for that digest before ${a.at}` });
+        }
+        entries.push(keyed({
+            ...base,
+            id: idOf("apply", a.ref, a.at, a.gate, a.digest ?? null),
+            kind: "applied",
+            at: a.at,
+            ...(a.by ? { by: a.by } : {}),
+            ...(approval ? { under: approval.id } : {}),
+            detail: { ...(a.detail ?? {}), approval: a.approval ?? "required" },
+        }));
+        for (const o of a.overrides ?? []) {
+            const recorded = find("override-recorded", o.gate, o.digest, false);
+            if (!recorded) {
+                gaps.push({ kind: "override", ...(a.op ? { op: a.op } : {}), gate: o.gate, ...(o.digest ? { digest: o.digest } : {}), detail: `${a.ref} cites the override ${o.gate}${o.digest ? ` for ${o.digest}` : ""}, but the ledger holds none` });
+                continue;
+            }
+            entries.push(keyed({
+                ...base,
+                id: idOf("spent", a.ref, a.at, recorded.id),
+                kind: "override-spent",
+                gate: o.gate,
+                at: a.at,
+                ...(recorded.by ? { by: recorded.by } : {}),
+                ...(recorded.digest ? { digest: recorded.digest } : {}),
+                under: recorded.id,
+                detail: {},
+            }));
+        }
+    }
+    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 };
+}
+/** The lines of one ledger file's text, all added, each with its line number. Blank lines are skipped. */
+export function gateLedgerLines(content) {
+    return content.split("\n").flatMap((l, i) => (l.trim() ? [{ text: l.trim(), line: i + 1 }] : []));
+}
+/**
+ * The lines each commit added to and removed from a ledger file, oldest first,
+ * from `git log -p --unified=0 --no-renames` written with
+ * `--format=%x1e%H%x1f%an%x1f%aI` over the file (append `%x1f%ae` for the
+ * author's email). The caller runs git; this reads the text. Each line keeps
+ * its commit and that commit's date and author, as `added` or `removed`. A
+ * line removed and added again in one commit (a newline fixed at the end of
+ * the file) is neither. A removed line is what {@link deriveGateAudit}
+ * reports as a revocation.
+ */
+export function gateLedgerLinesFromLog(log) {
+    const out = [];
+    for (const block of log.split("\x1e").slice(1)) {
+        const [head = "", ...rest] = block.split("\n");
+        const [commit = "", author = "", date = "", email = ""] = head.split("\x1f");
+        const net = new Map();
+        const order = [];
+        for (const l of rest) {
+            const sign = l[0];
+            if ((sign !== "+" && sign !== "-") || l[1] !== "{")
+                continue;
+            const text = l.slice(1).trim();
+            if (!net.has(text))
+                order.push(text);
+            net.set(text, (net.get(text) ?? 0) + (sign === "+" ? 1 : -1));
+        }
+        const when = Date.parse(date.trim());
+        const at = Number.isNaN(when) ? date.trim() : new Date(when).toISOString();
+        const by = { at, ...(author ? { by: author } : {}), ...(email.trim() ? { email: email.trim() } : {}) };
+        for (const text of order) {
+            const n = net.get(text);
+            for (let i = 0; i < Math.abs(n); i++) {
+                out.push({ text, commit: commit.trim(), ...(n > 0 ? { added: { ...by } } : { removed: { ...by } }) });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The thin reader: each op's ledger through a {@link GateLedgerPort} (the git
+ * port, or the in-memory one in a test), as input for {@link deriveGateAudit}.
+ * The port holds the file as it stands, so nothing here is revoked; add
+ * history through {@link gateLedgerLinesFromLog} for that.
+ */
+export async function readGateAuditLedgers(port, ops) {
+    const out = [];
+    for (const op of ops) {
+        const { resolutions, pending } = await port.read(op);
+        out.push({ op, lines: [...pending, ...resolutions].map((record) => ({ record })) });
+    }
+    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-select.js

@@ -0,0 +1,89 @@
+/**
+ * The rules a gate is decided by, over gate ledger lines already read (#2119,
+ * #2300): the pending fact a resolution must be newer than, and the
+ * resolution that answers a gate for a plan. They read no git, so
+ * `@intentius/chant/gate-decision` bundles them without the ledger's git
+ * code (#3763). `./gate-ledger.ts` re-exports them.
+ */
+import { samePlanDigest } from "./plan-digest.js";
+/** Whether a pending fact has aged out of relevance at `nowIso`. */
+export function isPendingGateExpired(record, nowIso) {
+    return new Date(record.expiresAt).getTime() <= new Date(nowIso).getTime();
+}
+/** The most recent pending fact for `gate`, expired or not — the anchor {@link latestResolutionSince} measures a resolution against. `undefined` when the gate has never been recorded pending. */
+export function latestPendingGate(records, gate) {
+    let latest;
+    for (const r of records) {
+        if (r.gate !== gate)
+            continue;
+        if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime())
+            latest = r;
+    }
+    return latest;
+}
+/** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */
+export function latestResolutionSince(records, gate, sinceIso) {
+    const since = new Date(sinceIso).getTime();
+    let latest;
+    for (const r of records) {
+        if (r.gate !== gate)
+            continue;
+        if (new Date(r.timestamp).getTime() < since)
+            continue;
+        if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime())
+            latest = r;
+    }
+    return latest;
+}
+/**
+ * The resolution that answers `gate` for the plan `planDigest` identifies
+ * (#2300).
+ *
+ * The criterion is the digest; recency is only the tiebreak between several
+ * resolutions that all match it. That inversion is the whole point of the
+ * issue: {@link latestResolutionSince} asks "is there a newer approval",
+ * which a run answers yes to no matter what has changed since, and this asks
+ * "is there an approval of *this*".
+ *
+ * - `planDigest` `undefined` — the gate binds no plan (an Op `gate` step
+ *   authored with no `plan`). Falls straight through to
+ *   {@link latestResolutionSince}: gates that never claimed to bind a plan
+ *   behave exactly as they did before #2300.
+ * - A resolution whose `planDigest` equals `planDigest` answers the gate.
+ * - A resolution for a different plan does not, and comes back as
+ *   `mismatched` so the caller can name both digests.
+ * - A resolution with no `planDigest` at all — every record written before
+ *   #2300 — does not either, and comes back as `mismatched` with an absent
+ *   `planDigest`. This is the safe reading of the migration: such a record
+ *   proves someone approved something, and nothing about what. Accepting it
+ *   once would silently apply the very change this check exists to catch, on
+ *   exactly the estates that have been running longest. The cost is one
+ *   further `chant approve` per gate after the upgrade, which the refusal
+ *   says out loud.
+ */
+export function latestResolutionForPlan(records, gate, sinceIso, planDigest) {
+    if (planDigest === undefined) {
+        const resolution = latestResolutionSince(records, gate, sinceIso);
+        return resolution ? { resolution } : {};
+    }
+    const since = new Date(sinceIso).getTime();
+    let matched;
+    let mismatched;
+    for (const r of records) {
+        if (r.gate !== gate)
+            continue;
+        if (new Date(r.timestamp).getTime() < since)
+            continue;
+        const newest = (best) => !best || new Date(r.timestamp).getTime() >= new Date(best.timestamp).getTime();
+        if (samePlanDigest(r.planDigest, planDigest)) {
+            if (newest(matched))
+                matched = r;
+        }
+        else if (newest(mismatched)) {
+            mismatched = r;
+        }
+    }
+    if (matched)
+        return { resolution: matched };
+    return mismatched ? { mismatched } : {};
+}

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>`,

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

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