@intentius/chant 0.122.0 → 0.124.0

package/src/override-gate.test.ts

@@ -0,0 +1,239 @@
+/**
+ * #3760: the override gate decides a denied plan's override: bound to the
+ * subject, plan digest and rules, by someone the overriders at base list,
+ * with a reason, sealed under `sealed`, and spent once a run applies it.
+ */
+
+import { createHash } from "node:crypto";
+import { afterEach, describe, expect, test } from "vitest";
+import {
+  OVERRIDE_APPLIED,
+  OVERRIDE_OP,
+  appliedOverride,
+  decideOverride,
+  overrideAuditApplies,
+  overrideCommand,
+  overrideDigest,
+  overridePending,
+  overridersAt,
+  parseAppliedOverrides,
+  parseOverriders,
+  recordedDenials,
+  sortedRules,
+  type AppliedOverrideRecord,
+  type GateResolutionRecord,
+  type OverrideInput,
+  type PendingGateRecord,
+} from "./override-gate";
+import { baseCommit, gateSealPayload, gateSignersAt, GATE_SEAL_NAMESPACE } from "./gate-decision";
+import { deriveGateAudit, gateLedgerLines, isOverrideGate, POLICY_OVERRIDE_OP } from "./lifecycle/gate-audit";
+import { isNeverOverMcpGateOp } from "./op/gate-name";
+import { isPlanDigest } from "./lifecycle/plan-digest";
+import { hasSshKeygen, TestRepo } from "./workspace/trust/test-repo";
+
+const ROOT = "envs/prod/vpc";
+const PLAN = `sha256:${"a".repeat(64)}`;
+const PLAN2 = `sha256:${"b".repeat(64)}`;
+const RULES = ["no-public-s3", "cost-cap"];
+const NOW = "2026-10-11T12:00:00.000Z";
+const DIGEST = overrideDigest(ROOT, PLAN, RULES);
+
+const denial = (timestamp: string, plan = PLAN, rules = RULES, expiresAt = "2026-10-13T00:00:00.000Z"): PendingGateRecord =>
+  overridePending({ subject: ROOT, planDigest: plan, rules, timestamp, expiresAt });
+const override = (timestamp: string, extra: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+  version: 1, op: OVERRIDE_OP, gate: ROOT, resolvedBy: "github:alice", timestamp, planDigest: DIGEST, note: "the bucket is the public docs site", ...extra,
+});
+const input = (resolutions: GateResolutionRecord[], over: Partial<OverrideInput> = {}): OverrideInput => ({
+  ledger: { pending: [denial("2026-10-11T10:00:00.000Z")], resolutions },
+  subject: ROOT, planDigest: PLAN, rules: RULES, overriders: ["github:alice", "github:bob"], now: NOW, ...over,
+});
+
+describe("the digest", () => {
+  test("binds the subject, the plan and the sorted rules, as terragucci's override.ts does", () => {
+    const expected = `sha256:${createHash("sha256").update([OVERRIDE_OP, ROOT, PLAN, "cost-cap", "no-public-s3"].join("\n")).digest("hex")}`;
+    expect(DIGEST).toBe(expected);
+    expect(isPlanDigest(DIGEST)).toBe(true);
+    expect(overrideDigest(ROOT, PLAN, [" no-public-s3", "cost-cap", "cost-cap"])).toBe(DIGEST);
+    expect(overrideDigest(ROOT, PLAN2, RULES)).not.toBe(DIGEST);
+    expect(overrideDigest(ROOT, PLAN, ["cost-cap"])).not.toBe(DIGEST);
+    expect(overrideDigest("envs/dev/vpc", PLAN, RULES)).not.toBe(DIGEST);
+  });
+
+  test("the command names each rule and asks for a reason, and a sign under sealed", () => {
+    expect(sortedRules(["b", " a", "b", ""])).toEqual(["a", "b"]);
+    expect(overrideCommand(ROOT, RULES)).toBe(`chant approve policy-override ${ROOT} --rule cost-cap --rule no-public-s3 --reason "<why>"`);
+    expect(overrideCommand(ROOT, RULES, true)).toMatch(/ --sign$/);
+  });
+});
+
+describe("the denial", () => {
+  test("is a pending fact of the override op whose planDigest is the override digest, with the plan and rules", () => {
+    const p = denial("2026-10-11T10:00:00.000Z") as PendingGateRecord & { plan: string; rules: string[] };
+    expect(p).toMatchObject({ version: 1, kind: "pending", op: "policy-override", gate: ROOT, planDigest: DIGEST, plan: PLAN, rules: ["cost-cap", "no-public-s3"] });
+  });
+
+  test("recordedDenials keeps each subject's newest", () => {
+    const other = overridePending({ subject: "envs/dev/vpc", planDigest: PLAN, rules: ["x"], timestamp: "2026-10-11T09:00:00.000Z", expiresAt: NOW });
+    const ds = recordedDenials([denial("2026-10-11T08:00:00.000Z", PLAN2), denial("2026-10-11T10:00:00.000Z"), other, { ...other, op: "tf-apply" }]);
+    expect(ds.map((d) => [d.gate, d.plan])).toEqual([["envs/dev/vpc", PLAN], [ROOT, PLAN]]);
+  });
+
+  test("the override op is never resolved over MCP, and the audit reader reads it as overrides", () => {
+    expect(isNeverOverMcpGateOp(OVERRIDE_OP)).toBe(true);
+    expect(OVERRIDE_OP).toBe(POLICY_OVERRIDE_OP);
+    expect(isOverrideGate(OVERRIDE_OP, ROOT)).toBe(true);
+  });
+});
+
+describe("decideOverride", () => {
+  test("an override of this digest, after the denial, by a listed person with a reason, counts", () => {
+    const d = decideOverride(input([override("2026-10-11T11:00:00.000Z")]));
+    expect(d).toMatchObject({ status: "overridden", digest: DIGEST, override: { subject: ROOT, by: "github:alice", reason: "the bucket is the public docs site", rules: ["cost-cap", "no-public-s3"], planDigest: PLAN, sealed: false } });
+  });
+
+  test("overriders are matched as signers are: case and width folded", () => {
+    expect(decideOverride(input([override("2026-10-11T11:00:00.000Z", { resolvedBy: "GitHub:Alice" })])).status).toBe("overridden");
+  });
+
+  test.each<[string, Partial<GateResolutionRecord> & { via?: string }, RegExp]>([
+    ["someone not listed", { resolvedBy: "github:mallory" }, /github:mallory is not listed in \.chant\/overriders at base \(github:alice, github:bob\)/],
+    ["no reason", { note: "  " }, /gives no reason/],
+    ["a job's line", { via: "slack" }, /written by a job \(via slack\)/],
+    ["a review's line", { review: { pr: 7, head: "c".repeat(40), approvers: ["github:alice"] } }, /review of #7/],
+    ["an agent", { approver: { kind: "agent" } }, /recorded by an agent/],
+  ])("%s does not count, and says why", (_name, extra, why) => {
+    const d = decideOverride(input([override("2026-10-11T11:00:00.000Z", extra)]));
+    expect(d.status).toBe("none");
+    expect(d.status === "none" && d.refusals).toEqual([expect.stringMatching(why)]);
+  });
+
+  test("nobody is listed when the overriders file is missing", () => {
+    const d = decideOverride(input([override("2026-10-11T11:00:00.000Z")], { overriders: [], overridersPath: "yodel.config.ts" }));
+    expect(d.status === "none" && d.refusals[0]).toMatch(/not listed in yodel\.config\.ts at base, which lists nobody/);
+  });
+
+  test("an override from before the newest denial answers nothing", () => {
+    const d = decideOverride(input([override("2026-10-11T09:00:00.000Z")]));
+    expect(d).toMatchObject({ status: "none", refusals: [] });
+  });
+
+  test("an override of another plan or other rules is the moved refusal", () => {
+    const was = overrideDigest(ROOT, PLAN2, RULES);
+    const d = decideOverride(input([override("2026-10-11T11:00:00.000Z", { planDigest: was })]));
+    expect(d).toMatchObject({ status: "moved", by: "github:alice", was, digest: DIGEST });
+  });
+
+  test("the standing denial is reported, so a run records no second one; an expired one is not", () => {
+    const standing = decideOverride(input([]));
+    expect(standing.status === "none" && standing.standing?.planDigest).toBe(DIGEST);
+    const expired = decideOverride(input([], { ledger: { pending: [denial("2026-10-08T10:00:00.000Z", PLAN, RULES, "2026-10-09T00:00:00.000Z")], resolutions: [] } }));
+    expect(expired.status === "none" && expired.standing).toBeUndefined();
+    const otherPlan = decideOverride(input([], { planDigest: PLAN2 }));
+    expect(otherPlan.status === "none" && otherPlan.standing).toBeUndefined();
+  });
+
+  test("an override written after an expired denial still counts for the same plan", () => {
+    const ledger = { pending: [denial("2026-10-08T10:00:00.000Z", PLAN, RULES, "2026-10-09T00:00:00.000Z")], resolutions: [override("2026-10-10T11:00:00.000Z")] };
+    expect(decideOverride(input([], { ledger })).status).toBe("overridden");
+  });
+
+  describe("spent once applied", () => {
+    const first = override("2026-10-11T11:00:00.000Z");
+    const decided = decideOverride(input([first]));
+    if (decided.status !== "overridden") throw new Error("setup");
+    const applied = appliedOverride(decided.override, { timestamp: "2026-10-11T11:05:00.000Z", runId: "42", commit: "c".repeat(40) });
+
+    test("the applied record names the subject, the override digest and the override's time", () => {
+      expect(applied).toEqual({ version: 1, kind: "applied", op: OVERRIDE_OP, gate: ROOT, planDigest: DIGEST, approvedAt: first.timestamp, approvedBy: "github:alice", timestamp: "2026-10-11T11:05:00.000Z", runId: "42", commit: "c".repeat(40) });
+      expect(parseAppliedOverrides(`${JSON.stringify(applied)}\nnot json\n{"version":1,"kind":"finished"}\n`)).toEqual([applied]);
+    });
+
+    test("a spent override does not count for the same plan again", () => {
+      const d = decideOverride(input([first], { applied: [applied] }));
+      expect(d.status === "none" && d.refusals).toEqual([expect.stringMatching(/is spent: a run applied under it at 2026-10-11T11:05:00/)]);
+    });
+
+    test("an override written after the applied record counts", () => {
+      const again = override("2026-10-11T11:10:00.000Z", { resolvedBy: "github:bob" });
+      expect(decideOverride(input([first, again], { applied: [applied] }))).toMatchObject({ status: "overridden", override: { by: "github:bob" } });
+    });
+
+    test("a re-planned denial waits for its own override, and the spent one is not a moved plan", () => {
+      const ledger = { pending: [denial("2026-10-11T10:00:00.000Z"), denial("2026-10-11T10:30:00.000Z", PLAN2)], resolutions: [first] };
+      // Not newer than the new denial: nothing.
+      expect(decideOverride(input([], { ledger, planDigest: PLAN2, applied: [applied] }))).toMatchObject({ status: "none", refusals: [] });
+      // Written after the new denial, but for the old plan and already spent.
+      const late = override("2026-10-11T10:40:00.000Z");
+      const spentLater: AppliedOverrideRecord = { ...applied, approvedAt: late.timestamp };
+      const d = decideOverride(input([], { ledger: { ...ledger, resolutions: [late] }, planDigest: PLAN2, applied: [spentLater] }));
+      expect(d).toMatchObject({ status: "none", spent: { digest: DIGEST, by: "github:alice", at: late.timestamp } });
+      // The same line, never applied, is the moved refusal.
+      expect(decideOverride(input([], { ledger: { ...ledger, resolutions: [late] }, planDigest: PLAN2 })).status).toBe("moved");
+    });
+
+    test("the audit reader records the override and its spending", () => {
+      const ledgerText = [denial("2026-10-11T10:00:00.000Z"), first].map((l) => JSON.stringify(l)).join("\n");
+      const { entries, gaps } = deriveGateAudit({ ledgers: [{ op: OVERRIDE_OP, lines: gateLedgerLines(ledgerText) }], applies: overrideAuditApplies([applied]) });
+      expect(entries.map((e) => e.kind)).toEqual(["override-requested", "override-recorded", "applied", "override-spent"]);
+      expect(entries.find((e) => e.kind === "override-recorded")).toMatchObject({ rules: ["cost-cap", "no-public-s3"], note: "the bucket is the public docs site", digest: DIGEST });
+      expect(entries.find((e) => e.kind === "applied")?.source.path).toBe(`${OVERRIDE_APPLIED}:1`);
+      expect(gaps).toEqual([]);
+    });
+  });
+});
+
+describe("the overriders at base", () => {
+  const repos: TestRepo[] = [];
+  afterEach(() => {
+    while (repos.length) repos.pop()!.cleanup();
+  });
+
+  test("one principal per line, comments and blanks skipped", () => {
+    expect(parseOverriders("# who may override\ngithub:alice\n\n  github:bob  # on call\ngithub:alice\n")).toEqual(["github:alice", "github:bob"]);
+  });
+
+  test("are read at base, so the change being applied cannot add its own overrider", () => {
+    const r = new TestRepo("3760-overriders");
+    repos.push(r);
+    r.write(".chant/overriders", "github:alice\n");
+    r.commit("base");
+    r.write(".chant/overriders", "github:alice\ngithub:mallory\n");
+    r.commit("adds mallory");
+    const base = baseCommit(r.dir);
+    expect(overridersAt(r.dir, base)).toEqual({ base, path: ".chant/overriders", active: true, principals: ["github:alice"] });
+    expect(overridersAt(r.dir, base, "ops/overriders").active).toBe(false);
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("sealed", () => {
+  const repos: TestRepo[] = [];
+  afterEach(() => {
+    while (repos.length) repos.pop()!.cleanup();
+  });
+
+  test("only an override sealed by its overrider's key at base counts", () => {
+    const r = new TestRepo("3760-sealed");
+    repos.push(r);
+    const alice = r.key("alice");
+    const bob = r.key("bob");
+    r.write(".chant/allowed_signers", `github:alice ${alice.pub}\n`);
+    r.commit("base");
+    r.write(".chant/allowed_signers", `github:alice ${alice.pub}\ngithub:bob ${bob.pub}\n`);
+    r.commit("adds bob");
+    const signers = gateSignersAt(r.dir, baseCommit(r.dir));
+    const seal = (o: GateResolutionRecord, key = alice) => ({ ...o, seal: { signer: o.resolvedBy, key: "k", signature: r.sshSign(key, gateSealPayload(o), GATE_SEAL_NAMESPACE) } });
+
+    const unsealed = override("2026-10-11T11:00:00.000Z");
+    expect(decideOverride(input([unsealed], { mode: "sealed", signers })).status === "none").toBe(true);
+    expect(decideOverride(input([seal(unsealed)], { mode: "sealed", signers }))).toMatchObject({ status: "overridden", override: { sealed: true } });
+    // Bob is listed as an overrider, but his key is added by the change itself.
+    const byBob = seal(override("2026-10-11T11:00:00.000Z", { resolvedBy: "github:bob" }), bob);
+    const d = decideOverride(input([byBob], { mode: "sealed", signers }));
+    expect(d.status === "none" && d.refusals[0]).toMatch(/github:bob has no key in \.chant\/allowed_signers at base/);
+    // A seal binds the digest, so a sealed line edited to another digest does not verify.
+    const moved = { ...seal(unsealed), planDigest: overrideDigest(ROOT, PLAN, ["cost-cap"]) };
+    expect(decideOverride(input([moved], { mode: "sealed", signers, rules: ["cost-cap"], ledger: { pending: [], resolutions: [moved] } })).status).toBe("none");
+    // Under sealed with no signers read, nothing counts.
+    expect(decideOverride(input([seal(unsealed)], { mode: "sealed" })).status).toBe("none");
+  });
+});

package/src/override-gate.ts

@@ -0,0 +1,395 @@
+/**
+ * The override gate (#3760, decision #3756): a person's recorded, reasoned
+ * decision to apply one plan a policy denied, spent once a run applies it.
+ *
+ * The policy engines stay in the products (OPA and conftest in terragucci,
+ * config rules in SQL Yodeler). They say a plan is denied and by which rules.
+ * This module records and decides the overrides of those denials, so a
+ * product keeps a thin layer over it:
+ *
+ * - A denial is a pending fact on `_gates/policy-override.jsonl` on
+ *   `chant/lifecycle`, gate the subject (a root, an environment, whatever the
+ *   product applies one plan to), with the rules that denied it
+ *   ({@link overridePending}). Its `planDigest` is the override digest
+ *   ({@link overrideDigest}), which binds the subject, the plan digest and
+ *   the rule ids, so `chant approve` copies it by default.
+ * - An override is an approval of that gate and digest, written with
+ *   `chant approve policy-override <subject> --rule <id> --reason <text>`
+ *   (`--sign` under `sealed`). The reason is its `note`.
+ * - It counts ({@link decideOverride}) when it is newer than the subject's
+ *   newest pending fact, names this digest, was written by a person the
+ *   overriders at base list ({@link overridersAt}), gives a reason, and under
+ *   `sealed` carries a seal that verifies for its approver against the
+ *   signers file at base. A line a job wrote (one that carries `via` or a
+ *   forge `review`) or an agent wrote never counts.
+ * - Before a run applies under an override it appends an applied record
+ *   ({@link appliedOverride}) to `_gates/policy-override/applied.jsonl`. An
+ *   override with an applied record is spent: it counts for nothing again, so
+ *   a plan that is denied again waits for its own override, and a spent
+ *   override of an older plan is not reported as a moved plan.
+ *
+ * Like `./gate-decision.ts` it reads the lines it is handed and writes
+ * nothing; `override-gate-bundle.test.ts` holds its import graph to the
+ * same bundle. chant's own writers are in `./lifecycle/override-ledger.ts`.
+ */
+
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { OVERRIDE_GATE_OP } from "./op/gate-name";
+import { latestPendingGate } from "./lifecycle/gate-ledger-select";
+import { samePlanDigest } from "./lifecycle/plan-digest";
+import { gateSealRefusal, type GateSigners } from "./workspace/trust/gate-seal";
+import { DEFAULT_SIGNERS_PATH } from "./workspace/trust/trust-files";
+import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+import type { GateApprovalSource } from "./op/op-waves";
+import type { GateAuditApply } from "./lifecycle/gate-audit";
+
+export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+export type { GateSigners } from "./workspace/trust/gate-seal";
+
+/** The op every override and denial is recorded under. `./lifecycle/gate-audit.ts` reads this op as overrides by default. */
+export const OVERRIDE_OP = OVERRIDE_GATE_OP;
+/** The ledger file on `chant/lifecycle` that holds denials and overrides. */
+export const OVERRIDE_LEDGER = `_gates/${OVERRIDE_OP}.jsonl`;
+/** The file beside it that holds the overrides a run applied under. chant reads only the `.jsonl` files directly under `_gates/` as gate ledgers, so it never reads these lines as gate records. */
+export const OVERRIDE_APPLIED = `_gates/${OVERRIDE_OP}/applied.jsonl`;
+/** Where the overriders are read at base when the caller names no other file: one principal per line, `#` starts a comment. */
+export const OVERRIDERS_PATH = ".chant/overriders";
+
+// ── the digest ───────────────────────────────────────────────────────────
+
+/** The rules as an override names them: trimmed, each once, sorted. */
+export function sortedRules(rules: readonly string[]): string[] {
+  return [...new Set(rules.map((r) => r.trim()).filter(Boolean))].sort();
+}
+
+/**
+ * The digest an override binds: the subject, its plan digest and the rules
+ * that denied it, as `sha256:<hex>` over their LF-joined lines after the op
+ * name. A plan that moved, or a different set of rules, gives another digest,
+ * so an override of one denial never lets another through.
+ */
+export function overrideDigest(subject: string, planDigest: string, rules: readonly string[]): string {
+  const text = [OVERRIDE_OP, subject, planDigest, ...sortedRules(rules)].join("\n");
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+
+/** The command that overrides a denial. */
+export function overrideCommand(subject: string, rules: readonly string[], sealed = false): string {
+  return `chant approve ${OVERRIDE_OP} ${subject} ${sortedRules(rules).map((r) => `--rule ${r}`).join(" ")} --reason "<why>"${sealed ? " --sign" : ""}`;
+}
+
+// ── the denial ───────────────────────────────────────────────────────────
+
+/** A denial's pending fact: the gate's record, with the plan it denied and the rules that denied it. `planDigest` is the override digest. */
+export interface OverridePendingRecord extends PendingGateRecord {
+  /** The plan digest the policy denied. */
+  plan: string;
+  /** The ids of the rules that denied it, sorted. */
+  rules: string[];
+}
+
+export interface OverridePendingInput {
+  subject: string;
+  planDigest: string;
+  rules: readonly string[];
+  /** ISO-8601. */
+  timestamp: string;
+  /** ISO-8601; past it a run that is still denied records a fresh fact. */
+  expiresAt: string;
+  description?: string;
+  runId?: string;
+  url?: string;
+}
+
+/** The pending fact a run records when the policy denies a plan and no override counts for it ({@link decideOverride} returns no `standing` fact). Appending it is the caller's. */
+export function overridePending(input: OverridePendingInput): OverridePendingRecord {
+  const rules = sortedRules(input.rules);
+  return {
+    version: 1,
+    kind: "pending",
+    op: OVERRIDE_OP,
+    gate: input.subject,
+    timestamp: input.timestamp,
+    expiresAt: input.expiresAt,
+    planDigest: overrideDigest(input.subject, input.planDigest, rules),
+    plan: input.planDigest,
+    rules,
+    description: input.description ?? `the policy denied this plan (${rules.join(", ")})`,
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(input.url ? { url: input.url } : {}),
+  };
+}
+
+const time = (iso: string): number => new Date(iso).getTime();
+
+/** The denials on the ledger: each subject's newest pending fact of the override op that names a plan. Sorted by subject. */
+export function recordedDenials(pending: readonly PendingGateRecord[]): OverridePendingRecord[] {
+  const newest = new Map<string, PendingGateRecord>();
+  for (const p of pending) {
+    if (p.op !== OVERRIDE_OP || !p.planDigest) continue;
+    const before = newest.get(p.gate);
+    if (!before || time(p.timestamp) >= time(before.timestamp)) newest.set(p.gate, p);
+  }
+  return [...newest.values()]
+    .map((p) => {
+      const r = p as Partial<OverridePendingRecord>;
+      return { ...p, plan: typeof r.plan === "string" ? r.plan : "", rules: Array.isArray(r.rules) ? sortedRules(r.rules.filter((x): x is string => typeof x === "string")) : [] };
+    })
+    .sort((a, b) => (a.gate < b.gate ? -1 : a.gate > b.gate ? 1 : 0));
+}
+
+// ── who may override, at base ────────────────────────────────────────────
+
+/** The overriders file at base. */
+export interface Overriders {
+  /** The commit it was read at. */
+  base: string | null;
+  path: string;
+  /** Whether the file exists at base. Without it nobody may override. */
+  active: boolean;
+  principals: string[];
+}
+
+/** The principals in an overriders file: one per line, blank lines and `#` comments skipped. */
+export function parseOverriders(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.replace(/#.*$/, "").trim();
+    if (line && !out.includes(line)) out.push(line);
+  }
+  return out;
+}
+
+/**
+ * The overriders at `base` (a commit the repository holds, such as
+ * `baseCommit(repo)` from `@intentius/chant/gate-decision`), from `path`
+ * (default {@link OVERRIDERS_PATH}). Read at base, so the change being
+ * applied cannot add the person who overrides its own denial. A product that
+ * keeps its list in its own config at base reads it there and passes the
+ * principals to {@link decideOverride} instead.
+ */
+export function overridersAt(repo: string, base: string, path = OVERRIDERS_PATH): Overriders {
+  const r = spawnSync("git", ["cat-file", "blob", `${base}:${path}`], { cwd: repo, encoding: "utf-8" });
+  if (r.status !== 0) return { base, path, active: false, principals: [] };
+  return { base, path, active: true, principals: parseOverriders(r.stdout) };
+}
+
+// ── the decision ─────────────────────────────────────────────────────────
+
+/** A line of `_gates/policy-override/applied.jsonl`: a run applied under the override of `planDigest` made at `approvedAt`. */
+export interface AppliedOverrideRecord {
+  version: 1;
+  kind: "applied";
+  op: string;
+  /** The subject. */
+  gate: string;
+  /** The override digest. */
+  planDigest: string;
+  /** The override's own timestamp: every override of this digest at or before it is spent. */
+  approvedAt: string;
+  approvedBy: string;
+  /** When the run recorded it. */
+  timestamp: string;
+  runId?: string;
+  commit?: string;
+}
+
+/** The applied records in the text of an applied file. Malformed lines, and lines of another kind, are skipped. */
+export function parseAppliedOverrides(text: string): AppliedOverrideRecord[] {
+  const out: AppliedOverrideRecord[] = [];
+  for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const r = JSON.parse(line) as Record<string, unknown>;
+      if (r.version === 1 && r.kind === "applied" && typeof r.op === "string" && typeof r.gate === "string" && typeof r.planDigest === "string" && typeof r.approvedAt === "string") {
+        out.push(r as unknown as AppliedOverrideRecord);
+      }
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}
+
+/** What judges an override line: who may write one, the approval mode, and under `sealed` the signers at base. */
+export interface OverrideRule {
+  /** The principals who may override (an overriders file's, or a product's own list at base). */
+  overriders: readonly string[];
+  /** Where they were read, for the refusals. Default {@link OVERRIDERS_PATH}. */
+  overridersPath?: string;
+  /** `sealed` counts only a seal that verifies; `ledger` and `pr-review` count an unsealed override (an override is a person's line on the ledger, never a review). Default `ledger`. */
+  mode?: GateApprovalSource;
+  /** The signers at base (`gateSignersAt`). Under `sealed`, absent means nothing counts. */
+  signers?: GateSigners;
+}
+
+const norm = (s: string): string => s.normalize("NFKC").trim().toLowerCase();
+
+/** Why this ledger line does not count as an override, or null when it does. */
+export function overrideRefusal(rule: OverrideRule, r: GateResolutionRecord): string | null {
+  const line = r as GateResolutionRecord & { via?: unknown };
+  if (line.via !== undefined) return `the override line was written by a job (via ${String(line.via)}), and an override is a person's`;
+  if (r.review !== undefined) return `the override line came from the review of #${r.review.pr}, and an override is a person's own line`;
+  if (r.approver?.kind === "agent") return `the override by ${r.resolvedBy} was recorded by an agent, and an override is a person's`;
+  const where = `${rule.overridersPath ?? OVERRIDERS_PATH} at base`;
+  if (!rule.overriders.map(norm).includes(norm(r.resolvedBy))) {
+    return `${r.resolvedBy} is not listed in ${where}${rule.overriders.length ? ` (${rule.overriders.join(", ")})` : ", which lists nobody"}`;
+  }
+  if (!r.note?.trim()) return `the override by ${r.resolvedBy} gives no reason`;
+  if (rule.mode === "sealed") {
+    const signers = rule.signers ?? { base: null, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems: ["no signers were read for this sealed override"] };
+    return gateSealRefusal(signers, r);
+  }
+  return null;
+}
+
+export interface OverrideInput extends OverrideRule {
+  /** The lines of `_gates/policy-override.jsonl`. Lines of other ops are ignored. */
+  ledger: { resolutions: readonly GateResolutionRecord[]; pending: readonly PendingGateRecord[] };
+  /** The lines of `_gates/policy-override/applied.jsonl`. Absent reads as none. */
+  applied?: readonly AppliedOverrideRecord[];
+  subject: string;
+  /** The plan digest the policy denied. */
+  planDigest: string;
+  /** The ids of the rules that denied it. */
+  rules: readonly string[];
+  /** ISO-8601 now, for whether the standing pending fact has expired. */
+  now?: string;
+}
+
+/** An override that counts. */
+export interface StandingOverride {
+  subject: string;
+  by: string;
+  at: string;
+  reason: string;
+  rules: string[];
+  /** The plan digest it lets through. */
+  planDigest: string;
+  /** The override digest. */
+  digest: string;
+  sealed: boolean;
+  resolution: GateResolutionRecord;
+}
+
+export type OverrideDecision =
+  /** An override of this digest counts: the run may apply this plan, after recording {@link appliedOverride}. */
+  | { status: "overridden"; digest: string; override: StandingOverride }
+  /**
+   * No override counts. `refusals` says why each override of this digest
+   * does not. `standing` is the unexpired pending fact for this digest, so a
+   * run that finds one records no other. `spent` is the newest override of
+   * another digest a run already applied under.
+   */
+  | { status: "none"; digest: string; refusals: string[]; standing?: OverridePendingRecord; spent?: { digest: string; by: string; at: string } }
+  /** An override counts for another digest and was never applied: the plan or its rules changed after it was written. */
+  | { status: "moved"; digest: string; by: string; was: string | undefined; refusals: string[]; standing?: OverridePendingRecord };
+
+/**
+ * Decide one denied plan against the override ledger, as `decideGateApproval`
+ * decides a gate: a line counts only when it is an override of this subject
+ * newer than the subject's newest pending fact, names this digest, passes
+ * {@link overrideRefusal}, and is not spent (an applied record of its digest
+ * made at or after it). The newest counting line wins.
+ *
+ * Decide before recording a denial: an override written after an expired
+ * pending fact still counts, and a run that records a fresh fact first would
+ * make it older than the anchor.
+ */
+export function decideOverride(input: OverrideInput): OverrideDecision {
+  const rules = sortedRules(input.rules);
+  const digest = overrideDigest(input.subject, input.planDigest, rules);
+  const pending = input.ledger.pending.filter((p) => p.op === OVERRIDE_OP);
+  const latest = latestPendingGate(pending as PendingGateRecord[], input.subject);
+  const since = latest ? time(latest.timestamp) : 0;
+  const applied = (input.applied ?? []).filter((a) => a.op === OVERRIDE_OP && a.gate === input.subject);
+  const spentBy = (r: GateResolutionRecord): AppliedOverrideRecord | undefined =>
+    r.planDigest === undefined ? undefined : applied.find((a) => samePlanDigest(a.planDigest, r.planDigest) && time(a.approvedAt) >= time(r.timestamp));
+  const newer = (r: GateResolutionRecord, best: GateResolutionRecord | undefined) => !best || time(r.timestamp) >= time(best.timestamp);
+
+  let matched: GateResolutionRecord | undefined;
+  let mismatched: GateResolutionRecord | undefined;
+  let used: GateResolutionRecord | undefined;
+  const refusals: string[] = [];
+  for (const r of input.ledger.resolutions) {
+    if (r.op !== OVERRIDE_OP || r.gate !== input.subject || time(r.timestamp) < since) continue;
+    const why = overrideRefusal(input, r);
+    const spent = spentBy(r);
+    if (samePlanDigest(r.planDigest, digest)) {
+      if (why !== null) refusals.push(why);
+      else if (spent) refusals.push(`the override by ${r.resolvedBy} at ${r.timestamp} is spent: a run applied under it at ${spent.timestamp}`);
+      else if (newer(r, matched)) matched = r;
+    } else if (why !== null) {
+      continue;
+    } else if (spent) {
+      if (newer(r, used)) used = r;
+    } else if (newer(r, mismatched)) {
+      mismatched = r;
+    }
+  }
+
+  if (matched) {
+    return {
+      status: "overridden",
+      digest,
+      override: {
+        subject: input.subject,
+        by: matched.resolvedBy,
+        at: matched.timestamp,
+        reason: matched.note!.trim(),
+        rules,
+        planDigest: input.planDigest,
+        digest,
+        sealed: input.mode === "sealed",
+        resolution: matched,
+      },
+    };
+  }
+  const now = input.now ?? new Date().toISOString();
+  const standing = latest && time(latest.expiresAt) > time(now) && samePlanDigest(latest.planDigest, digest)
+    ? recordedDenials([latest])[0]
+    : undefined;
+  if (mismatched) return { status: "moved", digest, by: mismatched.resolvedBy, was: mismatched.planDigest, refusals, ...(standing ? { standing } : {}) };
+  return {
+    status: "none",
+    digest,
+    refusals,
+    ...(standing ? { standing } : {}),
+    ...(used ? { spent: { digest: used.planDigest!, by: used.resolvedBy, at: used.timestamp } } : {}),
+  };
+}
+
+/** The applied record a run appends before it applies under `override`, which spends it. Appending it is the caller's. */
+export function appliedOverride(override: StandingOverride, at: { timestamp: string; runId?: string; commit?: string }): AppliedOverrideRecord {
+  return {
+    version: 1,
+    kind: "applied",
+    op: OVERRIDE_OP,
+    gate: override.subject,
+    planDigest: override.digest,
+    approvedAt: override.at,
+    approvedBy: override.by,
+    timestamp: at.timestamp,
+    ...(at.runId ? { runId: at.runId } : {}),
+    ...(at.commit ? { commit: at.commit } : {}),
+  };
+}
+
+/**
+ * The applied records as applies for the audit reader
+ * (`@intentius/chant/lifecycle/gate-audit`), each citing the override it
+ * spent, so the trail shows an `override-spent` entry for it and a gap when
+ * the ledger holds no such override. A product that records its applies
+ * elsewhere cites the override on its own apply instead.
+ */
+export function overrideAuditApplies(applied: readonly AppliedOverrideRecord[], path = OVERRIDE_APPLIED): GateAuditApply[] {
+  return applied.map((a, i) => ({
+    ref: `${path}:${i + 1}`,
+    at: a.timestamp,
+    gate: a.gate,
+    op: a.op,
+    approval: "not-required",
+    overrides: [{ gate: a.gate, digest: a.planDigest }],
+    detail: { approvedBy: a.approvedBy, approvedAt: a.approvedAt, ...(a.runId ? { runId: a.runId } : {}), ...(a.commit ? { commit: a.commit } : {}) },
+  }));
+}