@intentius/chant 0.124.12 → 0.124.14

package/dist/lifecycle/disruption.js

@@ -0,0 +1,135 @@
+/** Every level, most disruptive last — also the guard core validates a lexicon's answer against. */
+export const DISRUPTION_LEVELS = [
+    "in-place",
+    "rolling",
+    "replace",
+    "destroy",
+    "unknown",
+];
+/** Ordering for "the worst thing in this plan", with `unknown` above every confident verdict. */
+const DISRUPTION_RANK = {
+    "in-place": 0,
+    rolling: 1,
+    replace: 2,
+    destroy: 3,
+    unknown: 4,
+};
+/** The verdict every fallback path produces. */
+export function unknownDisruption(detail) {
+    return { disruption: "unknown", detail };
+}
+/**
+ * Annotate one lexicon's change set with a disruption verdict per `update`.
+ *
+ * Only `update` entries are asked about: every other action already carries its
+ * blast radius in the action itself. Called once per lexicon, before the plan
+ * merges the change sets, so `classify` is always the lexicon that produced the
+ * entries — the only party that can map its own observation's attribute paths
+ * back onto spec properties.
+ *
+ * Returns a new change set; the input is not mutated.
+ */
+export async function annotateDisruption(cs, environment, classify) {
+    const updates = cs.entries.filter((e) => e.action === "update");
+    if (updates.length === 0)
+        return cs;
+    const who = updates[0].lexicon ? `the ${updates[0].lexicon} lexicon` : "this lexicon";
+    let verdicts = {};
+    let fallback;
+    if (!classify) {
+        fallback = `${who} does not classify disruption — replacement semantics are spec knowledge it has not published`;
+    }
+    else {
+        try {
+            verdicts = (await classify({
+                environment,
+                changes: updates.map((e) => ({
+                    name: e.name,
+                    ...(e.type ? { type: e.type } : {}),
+                    deltas: e.deltas ?? [],
+                })),
+            })) ?? {};
+        }
+        catch (err) {
+            // A broken classifier is not evidence of anything. It must not be able to
+            // leave a confident verdict behind, and it must not fail the plan either.
+            verdicts = {};
+            fallback = `${who}'s disruption classifier failed: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    const entries = cs.entries.map((e) => {
+        if (e.action !== "update")
+            return e;
+        const verdict = resolveVerdict(verdicts[e.name], fallback, who);
+        const annotated = {
+            ...e,
+            disruption: verdict.disruption,
+            ...(verdict.because && verdict.because.length > 0 ? { disruptionBecause: verdict.because } : {}),
+            ...(verdict.detail ? { disruptionDetail: verdict.detail } : {}),
+        };
+        return annotated;
+    });
+    return { ...cs, entries };
+}
+function resolveVerdict(verdict, fallback, who) {
+    if (fallback)
+        return unknownDisruption(fallback);
+    if (!verdict)
+        return unknownDisruption(`${who} returned no verdict for this change`);
+    if (!DISRUPTION_LEVELS.includes(verdict.disruption)) {
+        return unknownDisruption(`${who} returned "${String(verdict.disruption)}", which is not a disruption level`);
+    }
+    return verdict;
+}
+/** Count `update` entries per level. Entries with no verdict at all are not counted. */
+export function summarizeDisruption(cs) {
+    const counts = {
+        "in-place": 0,
+        rolling: 0,
+        replace: 0,
+        destroy: 0,
+        unknown: 0,
+    };
+    for (const e of cs.entries) {
+        if (e.action === "update" && e.disruption)
+            counts[e.disruption]++;
+    }
+    return counts;
+}
+/** The most disruptive verdict in the set, or undefined when nothing was classified. */
+export function worstDisruption(cs) {
+    let worst;
+    for (const e of cs.entries) {
+        if (e.action !== "update" || !e.disruption)
+            continue;
+        if (!worst || DISRUPTION_RANK[e.disruption] > DISRUPTION_RANK[worst])
+            worst = e.disruption;
+    }
+    return worst;
+}
+/**
+ * Warnings a plan should print on stderr — so a `--json` or `--report gitlab-mr`
+ * consumer, whose shape has no column for disruption, still hears about the
+ * expensive rows. Same discipline as the unobserved warning (#1089).
+ */
+export function disruptionNotices(cs) {
+    const counts = summarizeDisruption(cs);
+    const notices = [];
+    const replacing = counts.replace + counts.destroy;
+    if (replacing > 0) {
+        notices.push(`${replacing} update(s) replace the resource rather than mutating it in place` +
+            (counts.destroy > 0
+                ? `, ${counts.destroy} of them by deleting it first — that window has nothing in it.`
+                : "."));
+    }
+    if (counts.unknown > 0) {
+        notices.push(`${counts.unknown} update(s) could not be classified — no lexicon could say whether applying them replaces the resource. Unknown is not "in place".`);
+    }
+    return notices;
+}
+/** Render one entry's verdict for the human plan, or "" when there is none. */
+export function renderDisruption(entry) {
+    if (!entry.disruption)
+        return "";
+    return ` — ${entry.disruption}${entry.disruptionDetail ? `: ${entry.disruptionDetail}` : ""}`;
+}

package/dist/lifecycle/gate-applied.js

@@ -0,0 +1,113 @@
+/**
+ * The approvals a wave applied under, and the rule that spends them (#3784).
+ *
+ * terragucci's wave gate writes one line to `_gates/<op>/applied.jsonl` on
+ * `chant/lifecycle` before a wave applies under an approval: the gate, the
+ * digest, and the approval's own timestamp. From then on that approval is
+ * spent. It does not let the same digest through again, and it no longer
+ * stands as the approval of another digest either. Op waves write the same
+ * line, in the same file, when their spec sets `approvals.spend`, and
+ * `decideGateApproval` (`../gate-decision.ts`) and `evaluateGate`
+ * (`../op/gate.ts`) take the lines to leave spent approvals out.
+ *
+ * The file sits in a directory under `_gates/`, so the readers of
+ * `_gates/<op>.jsonl` never see its lines. {@link appliedGateApplies} hands
+ * them to `gate-audit` as applies, each tied to the approval it ran under.
+ *
+ * Pure: no git, no clock, no file. It bundles into `@intentius/chant/gate-decision`.
+ */
+import { samePlanDigest } from "./plan-digest.js";
+/** Where the applied lines of `op` live on `chant/lifecycle`: the directory and the file, as `writeBlobToPath` takes them. */
+export function appliedGatePath(op) {
+    return { dir: `_gates/${op}`, file: "applied.jsonl" };
+}
+/** The applied lines of an `applied.jsonl` file, oldest first. A line that is not one is skipped. */
+export function parseAppliedGateLines(text) {
+    const out = [];
+    for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (r?.version === 1 && r.kind === "applied" && typeof r.op === "string" && typeof r.gate === "string" &&
+            typeof r.planDigest === "string" && typeof r.approvedAt === "string" && typeof r.timestamp === "string") {
+            out.push({ approvedBy: "", ...r });
+        }
+    }
+    return out;
+}
+const time = (iso) => new Date(iso).getTime();
+/**
+ * Every line of an `applied.jsonl` file a resume reads (#3858): the
+ * `applied` and `changes` lines, and the `finished` lines that say how an
+ * apply ended. Oldest first; a line that is none of them is skipped.
+ */
+export function parseAppliedGateFile(text) {
+    const applied = [];
+    const finished = [];
+    for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (r?.version !== 1 || typeof r.gate !== "string" || typeof r.planDigest !== "string" || typeof r.timestamp !== "string")
+            continue;
+        if ((r.kind === "applied" || r.kind === "changes") && typeof r.approvedAt === "string") {
+            applied.push({ op: "", approvedBy: "", ...r });
+        }
+        else if (r.kind === "finished" && typeof r.applied === "string" && (r.result === "applied" || r.result === "failed")) {
+            finished.push({ op: "", ...r });
+        }
+    }
+    return { applied, finished };
+}
+/** The finished line for the apply `line` names, or undefined while it has none. */
+export function finishedApply(finished, line) {
+    return finished.find((f) => f.gate === line.gate && samePlanDigest(f.planDigest, line.planDigest) && time(f.applied) === time(line.timestamp));
+}
+/**
+ * Whether an approval is spent: a wave applied under an approval of the same
+ * gate and digest made at or after it. One that names no digest is never
+ * spent. With `review`, an approval that came from a pull request's review
+ * is spent too when a wave applied this digest under a review of the same
+ * head, so the review cannot be recorded again to pass the digest twice. A
+ * review not yet recorded has no `timestamp`.
+ */
+export function isApprovalSpent(applied, approval) {
+    const digest = approval.planDigest;
+    if (digest === undefined)
+        return false;
+    return applied.some((a) => a.gate === approval.gate &&
+        samePlanDigest(a.planDigest, digest) &&
+        ((approval.timestamp !== undefined && time(a.approvedAt) >= time(approval.timestamp)) ||
+            (approval.review?.head !== undefined && a.review?.head === approval.review.head)));
+}
+/**
+ * The applied lines as `gate-audit` applies: each an `applied` entry tied to
+ * the approval it ran under. `ref` names the file, `_gates/<op>/applied.jsonl`
+ * by default; each line's index is appended so ids stay stable.
+ */
+export function appliedGateApplies(records, ref) {
+    return records.map((r, i) => ({
+        ref: `${ref ?? `_gates/${r.op}/applied.jsonl`}#${i + 1}`,
+        at: r.timestamp,
+        gate: r.gate,
+        op: r.op,
+        digest: r.planDigest,
+        approval: "required",
+        detail: {
+            approvedAt: r.approvedAt,
+            approvedBy: r.approvedBy,
+            ...(r.wave ? { wave: r.wave } : {}),
+            ...(r.review ? { review: r.review } : {}),
+            ...(r.runId ? { runId: r.runId } : {}),
+            ...(r.commit ? { commit: r.commit } : {}),
+        },
+    }));
+}

package/dist/lifecycle/gate-audit.js

@@ -0,0 +1,341 @@
+/**
+ * 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                  |
+ *
+ * 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",
+];
+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", "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 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);
+/** 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) }),
+                    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: {},
+            }));
+        }
+    }
+    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;
+}

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 } : {};
+}