@intentius/chant 0.122.0 → 0.124.0

package/src/gate-decision.test.ts

@@ -0,0 +1,237 @@
+/**
+ * #3763: `@intentius/chant/gate-decision` decides a plan-bound gate as chant's
+ * own wave gate does. Each ledger is decided both ways, by
+ * {@link decideGateApproval} and by `evaluateGate` with the port `chant run
+ * wave` builds, and the seal rule is read at a real base commit.
+ */
+
+import { describe, expect, test, afterEach } from "vitest";
+import {
+  baseCommit,
+  decideGateApproval,
+  gateSealPayload,
+  gateSignersAt,
+  identityGatesAt,
+  reviewApproval,
+  appliedGateApplies,
+  parseAppliedGateLines,
+  GATE_SEAL_NAMESPACE,
+  type AppliedGateRecord,
+  type GateApprovalInput,
+  type GateResolutionRecord,
+  type MergedReview,
+  type PendingGateRecord,
+} from "./gate-decision";
+import { evaluateGate, memoryGateLedgerPort, type GateLedgerPort } from "./op/gate";
+import { sealedApprovalRule, trustPolicyAt } from "./op/gate-review";
+import { hasSshKeygen, TestRepo } from "./workspace/trust/test-repo";
+import { deriveGateAudit } from "./lifecycle/gate-audit";
+
+const GATE = "migrations-wave-1";
+const D1 = "jcs1-sha256:1111";
+const D2 = "jcs1-sha256:2222";
+const NOW = "2026-10-11T12:00:00.000Z";
+
+const pending = (timestamp: string, planDigest = D1, extra: Partial<PendingGateRecord> = {}): PendingGateRecord => ({
+  version: 1, kind: "pending", op: "migrations", gate: GATE, timestamp, expiresAt: "2026-10-13T00:00:00.000Z", planDigest, ...extra,
+});
+const approved = (timestamp: string, planDigest: string | undefined = D1, extra: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+  version: 1, op: "migrations", gate: GATE, resolvedBy: "alice", timestamp, ...(planDigest ? { planDigest } : {}), ...extra,
+});
+
+/** evaluateGate's answer, reduced to what decideGateApproval also says. */
+async function evaluated(port: GateLedgerPort, input: { planDigest: string; environment?: string }) {
+  const check = await evaluateGate(port, { op: "migrations", gate: GATE, now: NOW, ...input });
+  return check.satisfied
+    ? { status: "approved", by: check.resolution.resolvedBy, at: check.resolution.timestamp }
+    : { status: "waiting", mismatched: check.mismatch?.resolvedBy ?? null, recorded: check.recorded };
+}
+
+function decided(input: GateApprovalInput) {
+  const d = decideGateApproval({ now: NOW, ...input });
+  return d.status === "approved"
+    ? { status: "approved", by: d.via === "ledger" ? d.resolution.resolvedBy : d.review.approvers?.[0], at: d.via === "ledger" ? d.resolution.timestamp : undefined }
+    : { status: "waiting", mismatched: d.mismatched?.resolvedBy ?? null, recorded: d.standing === undefined };
+}
+
+describe("under ledger, the decision is evaluateGate's", () => {
+  const ledgers: Array<[string, { resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }, { planDigest: string; environment?: string }]> = [
+    ["an approval of this digest after the pending fact", { pending: [pending("2026-10-11T10:00:00.000Z")], resolutions: [approved("2026-10-11T11:00:00.000Z")] }, { planDigest: D1 }],
+    ["an approval from before the gate last asked", { pending: [pending("2026-10-11T10:00:00.000Z")], resolutions: [approved("2026-10-11T09:00:00.000Z")] }, { planDigest: D1 }],
+    ["an approval of another digest", { pending: [pending("2026-10-11T10:00:00.000Z", D2)], resolutions: [approved("2026-10-11T11:00:00.000Z")] }, { planDigest: D2 }],
+    ["an approval that names no plan", { pending: [], resolutions: [approved("2026-10-11T11:00:00.000Z", undefined)] }, { planDigest: D1 }],
+    ["the newest of several", { pending: [], resolutions: [approved("2026-10-11T08:00:00.000Z"), approved("2026-10-11T11:00:00.000Z", D1, { resolvedBy: "bob" }), approved("2026-10-11T11:30:00.000Z", D2)] }, { planDigest: D1 }],
+    ["a standing pending fact for this digest", { pending: [pending("2026-10-11T10:00:00.000Z")], resolutions: [] }, { planDigest: D1 }],
+    ["an expired pending fact", { pending: [{ ...pending("2026-10-08T10:00:00.000Z"), expiresAt: "2026-10-09T00:00:00.000Z" }], resolutions: [] }, { planDigest: D1 }],
+    ["another environment's approval", { pending: [], resolutions: [approved("2026-10-11T11:00:00.000Z", D1, { environment: "staging" })] }, { planDigest: D1, environment: "prod" }],
+    ["this environment's approval", { pending: [pending("2026-10-11T10:00:00.000Z", D1, { environment: "staging" })], resolutions: [approved("2026-10-11T09:00:00.000Z", D1, { environment: "prod" })] }, { planDigest: D1, environment: "prod" }],
+  ];
+
+  test.each(ledgers)("%s", async (_name, ledger, input) => {
+    expect(decided({ ledger, gate: GATE, ...input })).toEqual(await evaluated(memoryGateLedgerPort(ledger), input));
+  });
+});
+
+describe("pr-review", () => {
+  const merged = (over: Partial<MergedReview> = {}): MergedReview => ({ pr: 7, head: "c".repeat(40), author: "github:carol", approvers: ["github:bob"], refused: [], ...over });
+
+  test("a writer's review of a head that planned this digest approves it", () => {
+    expect(reviewApproval(merged(), D1, D1)).toEqual({ approved: true, review: { pr: 7, head: "c".repeat(40), approvers: ["github:bob"] } });
+  });
+
+  test("a review approves nothing when nobody counted, no plans were recorded, or the plan moved", () => {
+    expect(reviewApproval(merged({ approvers: [], refused: ["github:carol is the author, whose own review never counts"] }), D1, D1).review.reason).toBe(
+      "no writer other than its author approved the head of #7: github:carol is the author, whose own review never counts",
+    );
+    expect(reviewApproval(merged(), undefined, D1).review.reason).toMatch(/no plans are recorded for the head cccccccccccc of #7/);
+    expect(reviewApproval(merged(), D2, D1).review.reason).toBe(`the plan moved after the review: the head planned ${D2}, and the merge plans ${D1}`);
+  });
+
+  test("the ledger is read first, and the review only when no approval counts", () => {
+    const ledger = { pending: [], resolutions: [approved("2026-10-11T11:00:00.000Z")] };
+    const review = reviewApproval(merged(), D1, D1);
+    expect(decideGateApproval({ ledger, gate: GATE, planDigest: D1, mode: "pr-review", review, now: NOW })).toMatchObject({ status: "approved", via: "ledger" });
+    expect(decideGateApproval({ ledger: { pending: [], resolutions: [] }, gate: GATE, planDigest: D1, mode: "pr-review", review, now: NOW })).toMatchObject({ status: "approved", via: "pr-review" });
+    const moved = reviewApproval(merged(), D2, D1);
+    expect(decideGateApproval({ ledger: { pending: [], resolutions: [] }, gate: GATE, planDigest: D1, mode: "pr-review", review: moved, now: NOW })).toMatchObject({ status: "waiting", review: { reason: expect.stringMatching(/plan moved/) } });
+    // Under ledger, a review is not consulted.
+    expect(decideGateApproval({ ledger: { pending: [], resolutions: [] }, gate: GATE, planDigest: D1, mode: "ledger", review, now: NOW }).status).toBe("waiting");
+  });
+});
+
+describe("spent approvals (#3784)", () => {
+  const appliedUnder = (r: GateResolutionRecord, timestamp = "2026-10-11T11:30:00.000Z", extra: Partial<AppliedGateRecord> = {}): AppliedGateRecord => ({
+    version: 1, kind: "applied", op: "migrations", gate: GATE, planDigest: r.planDigest!, approvedAt: r.timestamp, approvedBy: r.resolvedBy, timestamp, ...extra,
+  });
+  const a1 = approved("2026-10-11T11:00:00.000Z");
+
+  test("with spend, an approval a wave applied under does not pass the same digest twice", () => {
+    const ledger = { pending: [pending("2026-10-11T10:00:00.000Z")], resolutions: [a1], applied: [appliedUnder(a1)] };
+    expect(decideGateApproval({ ledger, gate: GATE, planDigest: D1, now: NOW })).toMatchObject({ status: "approved" });
+    expect(decideGateApproval({ ledger, gate: GATE, planDigest: D1, spend: true, now: NOW })).toMatchObject({ status: "waiting", spent: a1, standing: { planDigest: D1 } });
+    // A newer approval of the digest is not spent by the older apply.
+    const again = approved("2026-10-11T11:45:00.000Z", D1, { resolvedBy: "bob" });
+    expect(decideGateApproval({ ledger: { ...ledger, resolutions: [a1, again] }, gate: GATE, planDigest: D1, spend: true, now: NOW })).toMatchObject({ status: "approved", resolution: { resolvedBy: "bob" } });
+  });
+
+  test("a spent approval of another digest stands as no mismatch, as in terragucci's decideGate", () => {
+    const a2 = approved("2026-10-11T11:00:00.000Z", D2);
+    const ledger = { pending: [], resolutions: [a2], applied: [appliedUnder(a2)] };
+    expect(decideGateApproval({ ledger, gate: GATE, planDigest: D1, now: NOW })).toMatchObject({ status: "waiting", mismatched: a2 });
+    const d = decideGateApproval({ ledger, gate: GATE, planDigest: D1, spend: true, now: NOW });
+    expect(d).toMatchObject({ status: "waiting", spent: a2 });
+    expect(d).not.toHaveProperty("mismatched");
+  });
+
+  test("decideGateApproval and evaluateGate spend the same approvals", async () => {
+    const ledger = { pending: [], resolutions: [a1] };
+    const spent = [appliedUnder(a1)];
+    expect(decided({ ledger: { ...ledger, applied: spent }, gate: GATE, planDigest: D1, spend: true })).toEqual(
+      await evaluatedSpending(memoryGateLedgerPort(ledger), { planDigest: D1, spent }),
+    );
+  });
+
+  test("a pull request review a wave applied this digest under is spent", () => {
+    const head = "c".repeat(40);
+    const review = reviewApproval({ pr: 7, head, author: "github:carol", approvers: ["github:bob"], refused: [] }, D1, D1);
+    const recorded = approved("2026-10-11T11:00:00.000Z", D1, { resolvedBy: "github:bob", review: { pr: 7, head, approvers: ["github:bob"] } });
+    const ledger = { pending: [], resolutions: [recorded], applied: [appliedUnder(recorded, undefined, { review: { pr: 7, head } })] };
+    const d = decideGateApproval({ ledger, gate: GATE, planDigest: D1, mode: "pr-review", review, spend: true, now: NOW });
+    expect(d).toMatchObject({ status: "waiting", review: { reason: expect.stringMatching(/review is spent/) } });
+  });
+
+  test("the applied lines parse, and gate-audit reads them as applies under their approval", () => {
+    const line = appliedUnder(a1);
+    const text = `${JSON.stringify(line)}\nnot json\n${JSON.stringify({ ...line, kind: "finished" })}\n`;
+    expect(parseAppliedGateLines(text)).toEqual([line]);
+    const audit = deriveGateAudit({
+      ledgers: [{ op: "migrations", lines: [{ record: pending("2026-10-11T10:00:00.000Z") }, { record: a1 }] }],
+      applies: appliedGateApplies(parseAppliedGateLines(text)),
+    });
+    const approvedEntry = audit.entries.find((e) => e.kind === "approved")!;
+    expect(audit.entries.find((e) => e.kind === "applied")).toMatchObject({ gate: GATE, digest: D1, under: approvedEntry.id, detail: { approvedAt: a1.timestamp, approvedBy: "alice" } });
+    expect(audit.gaps).toEqual([]);
+  });
+});
+
+async function evaluatedSpending(port: GateLedgerPort, input: { planDigest: string; spent: AppliedGateRecord[] }) {
+  const check = await evaluateGate(port, { op: "migrations", gate: GATE, now: NOW, ...input });
+  return check.satisfied
+    ? { status: "approved", by: check.resolution.resolvedBy, at: check.resolution.timestamp }
+    : { status: "waiting", mismatched: check.mismatch?.resolvedBy ?? null, recorded: check.recorded };
+}
+
+describe.skipIf(!hasSshKeygen)("sealed, read at base", () => {
+  const repos: TestRepo[] = [];
+  afterEach(() => {
+    while (repos.length) repos.pop()!.cleanup();
+  });
+
+  function setup(files: Record<string, string>) {
+    const r = new TestRepo("3763-sealed");
+    repos.push(r);
+    const alice = r.key("alice");
+    const mallory = r.key("mallory");
+    for (const [path, text] of Object.entries(files)) r.write(path, text.replace("<alice>", alice.pub));
+    const base = r.commit("base");
+    // The change being applied adds mallory, who must not count.
+    r.write(".chant/allowed_signers", `alice ${alice.pub}\nmallory ${mallory.pub}\n`);
+    r.commit("adds mallory");
+    const seal = (a: GateResolutionRecord, key = alice, signer = a.resolvedBy) => ({ ...a, seal: { signer, key: "k", signature: r.sshSign(key, gateSealPayload(a), GATE_SEAL_NAMESPACE) } });
+    return { r, base, alice, mallory, seal };
+  }
+
+  test("only a seal by a signer at base counts, as it does for chant run wave", async () => {
+    const { r, base, mallory, seal } = setup({ ".chant/allowed_signers": "alice <alice>\n" });
+    expect(baseCommit(r.dir)).toBe(base);
+    const signers = gateSignersAt(r.dir, base);
+    expect(signers).toMatchObject({ base, active: true, signersPath: ".chant/allowed_signers" });
+    expect(signers.signers.map((s) => s.principal)).toEqual(["alice"]);
+
+    const rule = sealedApprovalRule(GATE, trustPolicyAt(r.dir, base));
+    const chantWave = (ledger: { resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }): GateLedgerPort => ({
+      ...memoryGateLedgerPort(ledger),
+      approvalRule: async (g) => (g === GATE ? rule : null),
+    });
+
+    const unsigned = approved("2026-10-11T11:00:00.000Z");
+    const byMallory = seal(approved("2026-10-11T11:10:00.000Z", D1, { resolvedBy: "mallory" }), mallory);
+    const byAlice = seal(approved("2026-10-11T11:20:00.000Z"));
+    const ledgers = [[unsigned], [unsigned, byMallory], [unsigned, byMallory, byAlice], [{ ...byAlice, planDigest: D2 }]];
+    for (const resolutions of ledgers) {
+      const ledger = { pending: [], resolutions };
+      expect(decided({ ledger, gate: GATE, planDigest: D1, mode: "sealed", signers })).toEqual(await evaluated(chantWave(ledger), { planDigest: D1 }));
+    }
+
+    const waiting = decideGateApproval({ ledger: { pending: [], resolutions: [unsigned, byMallory] }, gate: GATE, planDigest: D1, mode: "sealed", signers, now: NOW });
+    expect(waiting.status === "waiting" && waiting.uncounted.map((u) => u.reason)).toEqual([
+      `the approval of gate ${GATE} by alice carries no seal`,
+      "mallory has no key in .chant/allowed_signers at base, so the seal can't count",
+    ]);
+    // With no signers handed in, a sealed gate passes nothing.
+    expect(decideGateApproval({ ledger: { pending: [], resolutions: [byAlice] }, gate: GATE, planDigest: D1, mode: "sealed", now: NOW }).status).toBe("waiting");
+  });
+
+  test("the signers path trust.json names, and a trust.json chant would refuse", () => {
+    const named = setup({ ".chant/trust.json": JSON.stringify({ schema: 1, signers: "ops/signers" }), "ops/signers": "alice <alice>\n" });
+    expect(gateSignersAt(named.r.dir, named.base)).toMatchObject({ active: true, signersPath: "ops/signers" });
+    expect(trustPolicyAt(named.r.dir, named.base)).toMatchObject({ active: true, signersPath: "ops/signers" });
+
+    const invalid = setup({ ".chant/trust.json": JSON.stringify({ schema: 1, roles: { Admin: ["alice"] } }), ".chant/allowed_signers": "alice <alice>\n" });
+    expect(gateSignersAt(invalid.r.dir, invalid.base)).toMatchObject({ active: false, problems: [expect.stringMatching(/trust\.json is invalid: roles/)] });
+    expect(trustPolicyAt(invalid.r.dir, invalid.base).active).toBe(false);
+
+    const none = setup({ "README.md": "x\n" });
+    expect(gateSignersAt(none.r.dir, none.base)).toMatchObject({ active: false, signers: [] });
+  });
+
+  test("identity.gates at base", () => {
+    const { r, base } = setup({
+      "chant.workspace.json": JSON.stringify({ identity: { gates: { [GATE]: {}, deploy: { class: "human" } } } }),
+      ".chant/allowed_signers": "alice <alice>\n",
+    });
+    expect(identityGatesAt(r.dir, base)).toEqual([{ gate: GATE, class: null }, { gate: "deploy", class: "human" }]);
+    const empty = setup({ "README.md": "x\n" });
+    expect(identityGatesAt(empty.r.dir, empty.base)).toEqual([]);
+  });
+});

package/src/gate-decision.ts

@@ -0,0 +1,321 @@
+/**
+ * A gate's decision for a plan digest, and the seal check it needs, for a
+ * tool that runs from one bundled file (#3763, decision #3756).
+ *
+ * `@intentius/chant/gate-decision` holds what a tool needs to decide a
+ * plan-bound gate the way chant's own wave gate does (`chant run wave`,
+ * `./op/op-waves-run.ts`) under each approval mode:
+ *
+ * - `ledger`: an approval of this digest on `chant/lifecycle`, newer than the
+ *   gate's newest pending fact ({@link decideGateApproval}).
+ * - `sealed`: the same, counting only an approval whose seal verifies for its
+ *   approver against the signers file at base ({@link gateSignersAt},
+ *   {@link gateSealRefusal}). The seal is checked with node:crypto, so the job
+ *   needs no ssh-keygen.
+ * - `pr-review`: the same as `ledger`, or else the merged pull request's
+ *   approving review, when its head planned this digest
+ *   ({@link reviewApproval}).
+ *
+ * With `spend` (#3784), an approval a wave already applied under is spent and
+ * counts for nothing, as terragucci's wave gate has it: the caller hands in
+ * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
+ *
+ * The module reads the ledger lines and the review it is handed; reading
+ * them is the caller's. It imports no TypeScript, esbuild, zod, lint, fold or
+ * codegen module, and none of chant's git ledger code, which
+ * `gate-decision-bundle.test.ts` holds it to. Its rules are chant's own:
+ * `./lifecycle/gate-ledger-select.ts` is what `evaluateGate` decides by, and
+ * `gate-decision.test.ts` decides the same ledgers both ways.
+ */
+
+import { spawnSync } from "node:child_process";
+import {
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionForPlan,
+} from "./lifecycle/gate-ledger-select";
+import { samePlanDigest } from "./lifecycle/plan-digest";
+import { isApprovalSpent, type AppliedGateRecord } from "./lifecycle/gate-applied";
+import { gateSealRefusal, type GateSigners } from "./workspace/trust/gate-seal";
+import {
+  DEFAULT_SIGNERS_PATH,
+  TRUST_CONFIG_PATH,
+  parseAllowedSigners,
+  trustConfigProblems,
+} from "./workspace/trust/trust-files";
+import { parseJsonText } from "./workspace/jsonc";
+import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+import type { MergedReview } from "./op/gate-review";
+import type { GateApprovalSource } from "./op/op-waves";
+
+export { GATE_APPROVAL_SOURCES, type GateApprovalSource } from "./op/op-waves";
+export {
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionForPlan,
+  latestResolutionSince,
+  type PlanBoundResolution,
+} from "./lifecycle/gate-ledger-select";
+export {
+  GATE_SEAL_NAMESPACE,
+  gateSealPayload,
+  gateSealRefusal,
+  sshKeyFingerprint,
+  verifySshSignatureWith,
+  type GateSigners,
+  type SealedGateApproval,
+  type SshSignatureCheck,
+} from "./workspace/trust/gate-seal";
+export {
+  DEFAULT_SIGNERS_PATH,
+  TRUST_CONFIG_PATH,
+  parseAllowedSigners,
+  trustConfigProblems,
+  type Signer,
+  type SignerSet,
+} from "./workspace/trust/trust-files";
+export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
+export {
+  appliedGateApplies,
+  appliedGatePath,
+  isApprovalSpent,
+  parseAppliedGateLines,
+  type AppliedGateRecord,
+} from "./lifecycle/gate-applied";
+export type { MergedReview } from "./op/gate-review";
+
+// ── reading at base ──────────────────────────────────────────────────────
+
+function git(repo: string, args: string[]) {
+  return spawnSync("git", args, { cwd: repo, encoding: "utf-8" });
+}
+
+/** A file's text at `base`, or undefined when `base` holds no file at `path`. */
+function showAt(repo: string, base: string, path: string): string | undefined {
+  const r = git(repo, ["cat-file", "blob", `${base}:${path}`]);
+  return r.status === 0 ? r.stdout : undefined;
+}
+
+/**
+ * The commit a gate's rule is read at when the default branch applies its
+ * own commit: the first parent of HEAD, the branch as it stood before the
+ * merge, so a merge that adds a signer or drops a gate does not judge its own
+ * apply. A shallow checkout fetches that one commit from `origin`. A root
+ * commit has no parent and is its own base. Throws when it cannot be read.
+ */
+export function baseCommit(repo: string): string {
+  const head = git(repo, ["rev-parse", "--verify", "-q", "HEAD^{commit}"]);
+  const sha = head.stdout.trim();
+  if (head.status !== 0 || !sha) throw new Error(`${repo} has no commit checked out, so the gate cannot be decided`);
+  // The commit object's first `parent` line: a shallow clone keeps it even when it lacks the parent itself.
+  const header = git(repo, ["cat-file", "commit", sha]).stdout.split("\n\n")[0] ?? "";
+  const parent = /^parent ([0-9a-f]{40,64})$/m.exec(header)?.[1];
+  if (!parent) return sha;
+  const has = () => git(repo, ["cat-file", "-e", `${parent}^{commit}`]).status === 0;
+  if (!has()) git(repo, ["fetch", "-q", "--depth=1", "origin", parent]);
+  if (!has()) throw new Error(`cannot fetch ${parent.slice(0, 12)}, the commit before this one, so the gate cannot be decided`);
+  return parent;
+}
+
+/**
+ * The signers at `base`: the file `.chant/trust.json` names there, else
+ * `.chant/allowed_signers`, read as chant's trust policy reads it. A
+ * trust.json that is not valid (`trustConfigProblems`) turns attestation
+ * off, as it does in chant, so a sealed gate passes nothing. `base` is a
+ * commit the repository holds, such as {@link baseCommit}'s answer.
+ */
+export function gateSignersAt(repo: string, base: string): GateSigners {
+  const off = (problems: string[]): GateSigners => ({ base, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems });
+  const configText = showAt(repo, base, TRUST_CONFIG_PATH);
+  let signersPath = DEFAULT_SIGNERS_PATH;
+  if (configText !== undefined) {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(configText);
+    } catch (err) {
+      return off([`${TRUST_CONFIG_PATH} is not JSON: ${err instanceof Error ? err.message : String(err)}`]);
+    }
+    const problems = trustConfigProblems(raw);
+    if (problems.length > 0) return off([`${TRUST_CONFIG_PATH} is invalid: ${problems.join("; ")}`]);
+    signersPath = (raw as { signers?: string }).signers ?? DEFAULT_SIGNERS_PATH;
+  }
+  const text = showAt(repo, base, signersPath);
+  return { base, signersPath, active: text !== undefined, signers: text === undefined ? [] : parseAllowedSigners(text).signers, problems: [] };
+}
+
+/** A gate the declaration at base names under `identity.gates`, and the principal class its signer must be in, if any. */
+export interface IdentityGate {
+  gate: string;
+  class: string | null;
+}
+
+/**
+ * The gates `chant.workspace.json` (or `.jsonc`) at `base` names under
+ * `identity.gates`: each counts only a sealed approval, from its class when
+ * it names one. chant checks the class against the role grants at base; this
+ * reads the names. Empty when there is no declaration at base. Throws when
+ * the declaration there cannot be parsed, since the gate cannot be decided.
+ */
+export function identityGatesAt(repo: string, base: string): IdentityGate[] {
+  for (const file of ["chant.workspace.json", "chant.workspace.jsonc"]) {
+    const text = showAt(repo, base, file);
+    if (text === undefined) continue;
+    const parsed = parseJsonText(text, { jsonc: file.endsWith(".jsonc") });
+    if (!parsed.ok) throw new Error(`${file} at base is not valid JSON (${parsed.message}), so the gate cannot be decided`);
+    const gates = (parsed.value as { identity?: { gates?: Record<string, { class?: unknown } | null> } } | null)?.identity?.gates ?? {};
+    return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+  }
+  return [];
+}
+
+// ── pr-review ────────────────────────────────────────────────────────────
+
+/** What a pull request's review says about a wave, under `pr-review`. */
+export interface ReviewApproval {
+  approved: boolean;
+  review: { pr?: number; head?: string; approvers?: string[]; url?: string; reason?: string };
+}
+
+/**
+ * Whether the merged pull request's review approves `digest` (#3684): a
+ * writer other than its author approved its head, and the head planned this
+ * digest (`headDigest`, from the plans `chant run wave --record-plans`
+ * recorded for the head; undefined when none were). Reading the review and
+ * the plans is the caller's; under `pr-review` the caller records the
+ * approval on the ledger when this approves.
+ */
+export function reviewApproval(merged: MergedReview, headDigest: string | undefined, digest: string): ReviewApproval {
+  const seen = { pr: merged.pr, head: merged.head, ...(merged.url ? { url: merged.url } : {}) };
+  if (merged.approvers.length === 0) {
+    const why = merged.refused.length > 0 ? merged.refused.join("; ") : "nobody approved it";
+    return { approved: false, review: { ...seen, reason: `no writer other than its author approved the head of #${merged.pr}: ${why}` } };
+  }
+  if (headDigest === undefined) {
+    return {
+      approved: false,
+      review: { ...seen, approvers: merged.approvers, reason: `no plans are recorded for the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`)` },
+    };
+  }
+  if (headDigest !== digest) {
+    return {
+      approved: false,
+      review: { ...seen, approvers: merged.approvers, reason: `the plan moved after the review: the head planned ${headDigest}, and the merge plans ${digest}` },
+    };
+  }
+  return { approved: true, review: { ...seen, approvers: merged.approvers } };
+}
+
+// ── the decision ─────────────────────────────────────────────────────────
+
+/** The gate ledger lines of one op, as `chant/lifecycle` holds them in `_gates/<op>.jsonl`. */
+export interface GateLedgerLines {
+  resolutions: GateResolutionRecord[];
+  pending: PendingGateRecord[];
+  /** The approvals a wave applied under, from `_gates/<op>/applied.jsonl`. Read only with `spend`. */
+  applied?: AppliedGateRecord[];
+}
+
+export interface GateApprovalInput {
+  ledger: GateLedgerLines;
+  gate: string;
+  /** The digest the gate binds: the plan, or a wave's set digest. */
+  planDigest: string;
+  /** On a component gate, the environment: only its pending facts and approvals count. */
+  environment?: string;
+  /** Which approvals count. Default `ledger`. */
+  mode?: GateApprovalSource;
+  /** The signers at base, which a `sealed` gate checks seals against ({@link gateSignersAt}). Absent under `sealed`, nothing counts. */
+  signers?: GateSigners;
+  /** Another rule an approval must pass, such as chant's `identity.gates` rule: why it does not count, or null. */
+  refuses?: (approval: GateResolutionRecord) => string | null;
+  /** Under `pr-review`, what the merged pull request's review says ({@link reviewApproval}); consulted only when no approval on the ledger counts. */
+  review?: ReviewApproval;
+  /** ISO-8601 now, for whether the standing pending fact has expired. */
+  now?: string;
+  /**
+   * An approval a wave applied under is spent (#3784): it neither passes the
+   * digest again nor stands as the approval of another. Default false.
+   */
+  spend?: boolean;
+}
+
+/** An approval of this gate and digest that a rule did not count, and why. */
+export interface UncountedApproval {
+  resolution: GateResolutionRecord;
+  reason: string;
+}
+
+export type GateApprovalDecision =
+  | { status: "approved"; via: "ledger"; resolution: GateResolutionRecord }
+  | { status: "approved"; via: "pr-review"; review: ReviewApproval["review"] }
+  | {
+      status: "waiting";
+      /** The pending fact that still stands for this digest, unexpired: a caller that records one need not record another. */
+      standing?: PendingGateRecord;
+      /** The newest counted approval of this gate for another digest, or for none: the plan moved since it. */
+      mismatched?: GateResolutionRecord;
+      /** Approvals of this digest the mode or `refuses` did not count, newest last. */
+      uncounted: UncountedApproval[];
+      /** Under `pr-review`, why the review did not approve. */
+      review?: ReviewApproval["review"];
+      /** With `spend`, the newest approval of this gate a wave already applied under, which therefore counted for nothing. */
+      spent?: GateResolutionRecord;
+    };
+
+const EPOCH = new Date(0).toISOString();
+
+/**
+ * Decide a plan-bound gate against its ledger lines, as chant's wave gate
+ * does: an approval counts when it names this gate and digest (and
+ * environment, when set), is newer than the gate's newest pending fact, and
+ * passes the mode's rule: any under `ledger` and `pr-review`, a verified seal
+ * under `sealed`. With none, `pr-review` takes the review's answer. Writes
+ * nothing: recording a pending fact, or the review's approval, is the
+ * caller's.
+ */
+export function decideGateApproval(input: GateApprovalInput): GateApprovalDecision {
+  const { gate, planDigest, environment: env } = input;
+  const mode = input.mode ?? "ledger";
+  const pending = env === undefined ? input.ledger.pending : input.ledger.pending.filter((p) => p.environment === env);
+  const mine = (env === undefined ? input.ledger.resolutions : input.ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)).filter(
+    (r) => r.gate === gate,
+  );
+  const sealed = mode === "sealed";
+  const noSigners: GateSigners = { base: null, signersPath: DEFAULT_SIGNERS_PATH, active: false, signers: [], problems: ["no signers were read for this sealed gate"] };
+  const why = (r: GateResolutionRecord): string | null =>
+    input.refuses?.(r) ?? (sealed ? gateSealRefusal(input.signers ?? noSigners, r) : null);
+
+  const standingFact = latestPendingGate(pending, gate);
+  const since = standingFact?.timestamp ?? EPOCH;
+  const counted: GateResolutionRecord[] = [];
+  const uncounted: UncountedApproval[] = [];
+  let spent: GateResolutionRecord | undefined;
+  for (const r of mine) {
+    if (input.spend && isApprovalSpent(input.ledger.applied ?? [], r)) {
+      if (new Date(r.timestamp).getTime() >= new Date(since).getTime() && (!spent || new Date(r.timestamp).getTime() >= new Date(spent.timestamp).getTime())) spent = r;
+      continue;
+    }
+    const reason = why(r);
+    if (reason === null) counted.push(r);
+    else if (samePlanDigest(r.planDigest, planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime()) uncounted.push({ resolution: r, reason });
+  }
+  const found = latestResolutionForPlan(counted, gate, since, planDigest);
+  if (found.resolution) return { status: "approved", via: "ledger", resolution: found.resolution };
+  const reviewSpent =
+    input.spend === true && input.review?.approved === true &&
+    isApprovalSpent(input.ledger.applied ?? [], { gate, planDigest, review: { ...(input.review.review.head ? { head: input.review.review.head } : {}) } });
+  if (mode === "pr-review" && input.review?.approved && !reviewSpent) return { status: "approved", via: "pr-review", review: input.review.review };
+
+  const now = input.now ?? new Date().toISOString();
+  const standing = standingFact && !isPendingGateExpired(standingFact, now) && samePlanDigest(standingFact.planDigest, planDigest) ? standingFact : undefined;
+  return {
+    status: "waiting",
+    ...(standing ? { standing } : {}),
+    ...(found.mismatched ? { mismatched: found.mismatched } : {}),
+    uncounted: uncounted.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime()),
+    ...(mode === "pr-review" && input.review
+      ? { review: reviewSpent ? { ...input.review.review, reason: `a wave already applied this digest under the review of ${input.review.review.head?.slice(0, 12) ?? "its head"}, so the review is spent` } : input.review.review }
+      : {}),
+    ...(spent ? { spent } : {}),
+  };
+}