@intentius/chant 0.124.40 → 0.124.41

package/src/op/gate-quorum.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "vitest";
+import {
+  quorumProblems,
+  quorumRuleLine,
+  quorumRuleProgress,
+  quorumRulesFor,
+  rolesOf,
+  targetGlobMatch,
+  trustQuorumJudge,
+  type GateQuorumJudge,
+  type GateQuorumRule,
+} from "./gate-quorum";
+import { evaluateGate, memoryGateLedgerPort, tallyGateApprovals } from "./gate";
+import { gateApprovalProblems } from "./gate-approval";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { gatesInLedger } from "../workspace/status-gates";
+import { resolutionAnswering } from "./gate-resume";
+
+const digest = `sha256:${"a".repeat(64)}`;
+const approval = (who: string, at: string, extra: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+  version: 1,
+  op: "ship",
+  gate: "prod",
+  resolvedBy: who,
+  timestamp: at,
+  planDigest: digest,
+  ...extra,
+});
+
+/** A judge that proves the names in `proven`, gives roles from `roles`, and knows `authors`. */
+const judgeOf = (proven: string[], roles: Record<string, string[]>, authors?: string[]): GateQuorumJudge => (r) => {
+  const ok = proven.includes(r.resolvedBy);
+  return { proven: ok, roles: ok ? rolesOf(r.resolvedBy, roles) : [], ...(authors ? { author: authors.includes(r.resolvedBy) } : {}) };
+};
+
+describe("approval rules (#4290)", () => {
+  test("targets globs read * within a segment and ** across segments", () => {
+    expect(targetGlobMatch("prod-*", "prod-eu")).toBe(true);
+    expect(targetGlobMatch("prod-*", "staging")).toBe(false);
+    expect(targetGlobMatch("envs/prod/**", "envs/prod/eu/db")).toBe(true);
+    expect(targetGlobMatch("envs/*/db", "envs/prod/eu/db")).toBe(false);
+    expect(targetGlobMatch("envs/**/db", "envs/db")).toBe(true);
+  });
+
+  test("a gate takes the rules with no targets, and those a glob of matches one of its targets", () => {
+    const rules: GateQuorumRule[] = [{ count: 1 }, { targets: ["prod-*"], count: 2 }, { targets: ["dev"], count: 3 }];
+    expect(quorumRulesFor(rules, ["prod-eu", "staging"])).toEqual([{ count: 1 }, { targets: ["prod-*"], count: 2 }]);
+    expect(quorumRulesFor(rules, [])).toEqual([{ count: 1 }]);
+  });
+
+  test("a role counts only for a proven approver that trust.json grants it", () => {
+    const rule: GateQuorumRule = { count: 2, roles: ["platform"] };
+    const judge = judgeOf(["github:alice", "github:bob"], { platform: ["github:alice", "github:carol"] });
+    const approvers = ["github:alice", "github:bob", "github:carol"].map((who, i) => ({ who, at: `2026-10-22T0${i}:00:00Z`, judged: judge(approval(who, "")) }));
+    const p = quorumRuleProgress(rule, approvers);
+    // bob is proven but holds no role; carol holds the role but is not proven.
+    expect(p.approvers).toEqual(["github:alice"]);
+    expect(p.met).toBe(false);
+    expect(quorumRuleLine(p)).toBe("every target: 1 of 2 approvals (github:alice), needs 1 more from platform");
+  });
+
+  test("notAuthor needs a proven approver who is not the author, and waits when the author is unknown", () => {
+    const rule: GateQuorumRule = { count: 1, notAuthor: true };
+    const at = "2026-10-22T00:00:00Z";
+    const byAuthor = judgeOf(["github:alice"], {}, ["github:alice"]);
+    expect(quorumRuleProgress(rule, [{ who: "github:alice", at, judged: byAuthor(approval("github:alice", at)) }]).met).toBe(false);
+    const byOther = judgeOf(["github:bob"], {}, ["github:alice"]);
+    expect(quorumRuleProgress(rule, [{ who: "github:bob", at, judged: byOther(approval("github:bob", at)) }]).met).toBe(true);
+    const unknown = judgeOf(["github:bob"], {});
+    const p = quorumRuleProgress(rule, [{ who: "github:bob", at, judged: unknown(approval("github:bob", at)) }]);
+    expect(p).toMatchObject({ met: false, authorUnknown: true });
+    expect(quorumRuleLine(p)).toMatch(/author is not known/);
+  });
+
+  test("the trust judge proves a reviewer of the live review, never a claimed role", () => {
+    const judge = trustQuorumJudge({
+      signers: { base: null, signersPath: ".chant/allowed_signers", active: false, signers: [], problems: [] },
+      roles: { platform: ["github:alice"] },
+      authors: ["github:dana"],
+      review: { head: "h1", approvers: ["github:alice"] },
+    });
+    expect(judge(approval("github:alice", "", { review: { pr: 1, head: "h1", approvers: ["github:alice"] } }))).toEqual({ proven: true, roles: ["platform"], author: false });
+    // A review line for another head proves nothing, and a claimed role is ignored.
+    expect(judge(approval("github:alice", "", { review: { pr: 1, head: "h0", approvers: ["github:alice"] }, approver: { kind: "human", roles: ["platform"] } }))).toEqual({ proven: false, roles: [], author: false });
+  });
+
+  test("the tally passes once every rule is met, each approver once", () => {
+    const rules: GateQuorumRule[] = [{ count: 2 }, { count: 1, roles: ["platform"] }];
+    const judge = judgeOf(["github:alice"], { platform: ["github:alice"] });
+    const records = [approval("github:bob", "2026-10-22T01:00:00Z"), approval("github:bob", "2026-10-22T02:00:00Z")];
+    const one = tallyGateApprovals(records, "prod", "2026-10-22T00:00:00Z", digest, { mode: "log-only", quorum: rules }, undefined, judge);
+    expect(one).toMatchObject({ met: false, need: 2 });
+    expect(one.counted.map((r) => r.resolvedBy)).toEqual(["github:bob"]);
+    const both = tallyGateApprovals([...records, approval("github:alice", "2026-10-22T03:00:00Z")], "prod", "2026-10-22T00:00:00Z", digest, { mode: "log-only", quorum: rules }, undefined, judge);
+    expect(both.met).toBe(true);
+    expect(both.rules?.map((r) => r.met)).toEqual([true, true]);
+  });
+
+  test("an agent never counts toward a rule", () => {
+    const records = [approval("bot", "2026-10-22T01:00:00Z", { approver: { kind: "agent" } })];
+    expect(tallyGateApprovals(records, "prod", "2026-10-22T00:00:00Z", digest, { mode: "log-only", quorum: [{ count: 1 }] }).met).toBe(false);
+  });
+
+  test("evaluateGate asks the port's judge for rules naming roles, and with none no role counts", async () => {
+    const quorum: GateQuorumRule[] = [{ count: 1, roles: ["platform"] }];
+    const seeded = { resolutions: [approval("github:alice", "2026-10-22T01:00:00Z", { approver: { kind: "human", roles: ["platform"] } })] };
+    const input = { op: "ship", gate: "prod", planDigest: digest, approval: { mode: "log-only" as const, quorum }, now: "2026-10-22T02:00:00Z" };
+    const bare = await evaluateGate(memoryGateLedgerPort(seeded), input);
+    expect(bare.satisfied).toBe(false);
+    if (!bare.satisfied) expect(bare.quorum?.rules?.[0]).toMatchObject({ met: false, approvers: [] });
+    const port = { ...memoryGateLedgerPort(seeded), quorumJudge: async () => judgeOf(["github:alice"], { platform: ["github:alice"] }) };
+    expect((await evaluateGate(port, input)).satisfied).toBe(true);
+  });
+
+  test("an Op gate's block takes a list of rules, and refuses notAuthor", () => {
+    expect(gateApprovalProblems({ quorum: [{ targets: ["prod"], count: 2, roles: ["platform"] }, { count: 1 }] })).toEqual([]);
+    expect(gateApprovalProblems({ quorum: [{ count: 1, notAuthor: true }] })).toEqual([expect.stringMatching(/notAuthor` is not read here/)]);
+    expect(gateApprovalProblems({ quorum: [] })).toEqual(["`approval.quorum` must name at least one rule"]);
+    expect(quorumProblems([{ count: 0, targets: [], who: 1 }], "approvals.quorum", { notAuthor: true })).toEqual([
+      "`approvals.quorum[0].count` must be an integer of at least 1",
+      "`approvals.quorum[0].targets` must be a non-empty list of globs",
+      "`approvals.quorum[0].who` is not a quorum field; use targets, count, roles or notAuthor",
+    ]);
+  });
+
+  test("workspace status and the resume check count a role rule with the judge, as the run does", () => {
+    const quorum: GateQuorumRule[] = [{ count: 1, roles: ["platform"] }];
+    const standing: PendingGateRecord = {
+      version: 1, kind: "pending", op: "ship", gate: "prod", timestamp: "2026-10-22T00:00:00Z", expiresAt: "2026-10-24T00:00:00Z", planDigest: digest, approval: { mode: "log-only", quorum },
+    };
+    const alice = approval("github:alice", "2026-10-22T01:00:00Z");
+    const judge = judgeOf(["github:alice"], { platform: ["github:alice"] });
+    const content = [standing, alice].map((r) => JSON.stringify(r)).join("\n") + "\n";
+    expect(gatesInLedger("ship", content, [], "2026-10-22T02:00:00Z").gates[0]?.state).toBe("pending");
+    expect(gatesInLedger("ship", content, [], "2026-10-22T02:00:00Z", () => null, judge).gates[0]?.state).toBe("approved");
+    expect(resolutionAnswering([alice], standing)).toBeUndefined();
+    expect(resolutionAnswering([alice], standing, [standing], judge)?.resolvedBy).toBe("github:alice");
+  });
+});

package/src/op/gate-quorum.ts

@@ -0,0 +1,248 @@
+/**
+ * Approval rules (#4290): a gate's quorum as a list of rules, each with the
+ * targets it covers, how many approvers it needs, the roles that count, and
+ * whether one of them must not be the change's author.
+ *
+ *   quorum: [
+ *     { targets: ["prod-*"], count: 2, roles: ["platform"], notAuthor: true },
+ *     { count: 1 },
+ *   ]
+ *
+ * A gate takes every rule whose `targets` glob matches one of its targets
+ * (a rule with no `targets` covers every target), and passes once each rule
+ * it takes is met by distinct human approvers of its plan. A gate that takes
+ * no rule needs one human approval, the rule every gate had before.
+ *
+ * Roles come from `.chant/trust.json` at base (`roles`: role name to the
+ * principals that hold it), never from the approver's own claim. An
+ * approver counts toward `roles`, and as someone who is not the author, only
+ * when the approval proves who they are: a seal that verifies against the
+ * signers file at base, or under `pr-review` the forge review of the merged
+ * pull request. The judge of a gate decides that ({@link GateQuorumJudge});
+ * with none, no approval proves anything, so a rule naming roles or
+ * `notAuthor` is never met.
+ *
+ * This module is pure: no git, no file reads, no package, so
+ * `@intentius/chant/gate-decision` bundles it. The judge is built by the
+ * caller from the trust policy it read at base ({@link trustQuorumJudge}).
+ */
+
+import { gateSealRefusal, type GateSigners } from "../lifecycle/gate-seal";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+
+/** One approval rule. */
+export interface GateQuorumRule {
+  /** Globs over the gate's targets (an Op wave's run targets, an Op gate's environment). Absent, the rule covers every target. */
+  targets?: string[];
+  /** Distinct human approvers the rule needs. At least 1. */
+  count: number;
+  /** When set, only an approver `.chant/trust.json` at base gives one of these roles counts, and only with a proven approval. */
+  roles?: string[];
+  /** When true, at least one counted approver is proven and is not the change's author. */
+  notAuthor?: boolean;
+}
+
+/** A gate's quorum: one rule (the form before #4290), or a list of them. */
+export type GateQuorumSpec = GateQuorumRule | readonly GateQuorumRule[];
+
+/** What a judge says about one approval. */
+export interface QuorumJudgement {
+  /** The approval proves who `resolvedBy` is: a verified seal, or the forge's review. */
+  proven: boolean;
+  /** The roles `.chant/trust.json` at base gives the approver. Empty unless `proven`. */
+  roles: string[];
+  /** Whether the approver is the change's author. Undefined when nobody knows who the author is. */
+  author?: boolean;
+}
+
+/** Judges one approval for the rules. */
+export type GateQuorumJudge = (approval: GateResolutionRecord) => QuorumJudgement;
+
+/** The judge with nothing to judge by: no approval proves anyone, and nobody's author is known. */
+export const UNPROVEN_JUDGE: GateQuorumJudge = () => ({ proven: false, roles: [] });
+
+/** How far one rule is met. */
+export interface GateQuorumRuleProgress {
+  targets?: string[];
+  count: number;
+  roles?: string[];
+  notAuthor?: boolean;
+  /** The approvers it counts, oldest first. */
+  approvers: string[];
+  met: boolean;
+  /** Why the author could not be told apart, when `notAuthor` is set and nobody knows the author. */
+  authorUnknown?: boolean;
+}
+
+/** The rules of a quorum, as a list. Absent, none. */
+export function quorumRules(quorum: GateQuorumSpec | undefined): GateQuorumRule[] {
+  if (quorum === undefined) return [];
+  return Array.isArray(quorum) ? [...(quorum as readonly GateQuorumRule[])] : [quorum as GateQuorumRule];
+}
+
+/**
+ * Whether `target` matches `glob`: `*` within a `/` segment, `**` across
+ * segments (and `a/**\/b` across none), `?` one character. The same reading
+ * as the terraform lexicon's unit globs, so a Terragrunt root's glob means
+ * one thing in both.
+ */
+export function targetGlobMatch(glob: string, target: string): boolean {
+  const g = glob.replace(/\\/g, "/").replace(/\/+$/, "");
+  let re = "";
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i]!;
+    if (c === "*" && g[i + 1] === "*") {
+      if (g[i + 2] === "/") {
+        re += "(?:.*/)?";
+        i += 2;
+      } else {
+        re += ".*";
+        i += 1;
+      }
+    } else if (c === "*") re += "[^/]*";
+    else if (c === "?") re += "[^/]";
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`).test(target.replace(/\\/g, "/").replace(/\/+$/, ""));
+}
+
+/** The rules a gate whose targets are `targets` takes: those with no `targets`, and those a glob of matches one. */
+export function quorumRulesFor(rules: readonly GateQuorumRule[], targets: readonly string[]): GateQuorumRule[] {
+  return rules.filter((r) => r.targets === undefined || r.targets.some((g) => targets.some((t) => targetGlobMatch(g, t))));
+}
+
+/** The most approvers any rule needs, 1 with none. */
+export function quorumNeed(rules: readonly GateQuorumRule[]): number {
+  return rules.reduce((n, r) => Math.max(n, r.count), 1);
+}
+
+/**
+ * Everything wrong with a quorum, one line each. `where` names it
+ * (`approval.quorum`). With `notAuthor: false`, a rule naming `notAuthor` is
+ * refused, since that caller has no author to judge by.
+ */
+export function quorumProblems(value: unknown, where: string, opts: { notAuthor: boolean }): string[] {
+  const list = Array.isArray(value) ? value : [value];
+  const problems: string[] = [];
+  if (Array.isArray(value) && value.length === 0) problems.push(`\`${where}\` must name at least one rule`);
+  list.forEach((rule, i) => {
+    const at = Array.isArray(value) ? `${where}[${i}]` : where;
+    if (typeof rule !== "object" || rule === null || Array.isArray(rule)) {
+      problems.push(`\`${at}\` must be an object`);
+      return;
+    }
+    const q = rule as Record<string, unknown>;
+    if (typeof q.count !== "number" || !Number.isInteger(q.count) || q.count < 1) problems.push(`\`${at}.count\` must be an integer of at least 1`);
+    if (q.roles !== undefined && (!Array.isArray(q.roles) || q.roles.length === 0 || q.roles.some((r) => typeof r !== "string" || r === ""))) {
+      problems.push(`\`${at}.roles\` must be a non-empty list of role names`);
+    }
+    if (q.targets !== undefined && (!Array.isArray(q.targets) || q.targets.length === 0 || q.targets.some((t) => typeof t !== "string" || t === ""))) {
+      problems.push(`\`${at}.targets\` must be a non-empty list of globs`);
+    }
+    if (q.notAuthor !== undefined && typeof q.notAuthor !== "boolean") problems.push(`\`${at}.notAuthor\` must be true or false`);
+    if (q.notAuthor === true && !opts.notAuthor) {
+      problems.push(`\`${at}.notAuthor\` is not read here: an Op gate has no author to judge by. An Op waves spec's \`approvals.quorum\` reads it from the merged pull request`);
+    }
+    const known = new Set(["targets", "count", "roles", "notAuthor"]);
+    for (const key of Object.keys(q)) if (!known.has(key)) problems.push(`\`${at}.${key}\` is not a quorum field; use targets, count, roles or notAuthor`);
+  });
+  return problems;
+}
+
+const norm = (s: string): string => s.normalize("NFKC").trim().toLowerCase();
+
+/** Whether two principals name the same person, compared trimmed and lower-cased. */
+export const samePrincipal = (a: string, b: string): boolean => norm(a) === norm(b);
+
+/** The roles `roles` (`.chant/trust.json`'s role grants) gives `who`, sorted. */
+export function rolesOf(who: string, roles: Readonly<Record<string, readonly string[]>>): string[] {
+  return Object.entries(roles)
+    .filter(([, principals]) => principals.some((p) => samePrincipal(p, who)))
+    .map(([role]) => role)
+    .sort();
+}
+
+/** One approver as a rule counts them. */
+export interface QuorumApprover {
+  who: string;
+  at: string;
+  judged: QuorumJudgement;
+}
+
+/** How far `rule` is met by `approvers`: each counted once, by name, oldest first. */
+export function quorumRuleProgress(rule: GateQuorumRule, approvers: readonly QuorumApprover[]): GateQuorumRuleProgress {
+  const seen = new Set<string>();
+  const counted: QuorumApprover[] = [];
+  for (const a of [...approvers].sort((x, y) => Date.parse(x.at) - Date.parse(y.at))) {
+    if (seen.has(norm(a.who))) continue;
+    if (rule.roles?.length && !(a.judged.proven && a.judged.roles.some((r) => rule.roles!.includes(r)))) continue;
+    seen.add(norm(a.who));
+    counted.push(a);
+  }
+  const notAuthor = !rule.notAuthor || counted.some((a) => a.judged.proven && a.judged.author === false);
+  const authorUnknown = rule.notAuthor === true && !notAuthor && counted.some((a) => a.judged.proven && a.judged.author === undefined);
+  return {
+    ...(rule.targets ? { targets: [...rule.targets] } : {}),
+    count: rule.count,
+    ...(rule.roles?.length ? { roles: [...rule.roles] } : {}),
+    ...(rule.notAuthor ? { notAuthor: true } : {}),
+    approvers: counted.map((a) => a.who),
+    met: counted.length >= rule.count && notAuthor,
+    ...(authorUnknown ? { authorUnknown: true } : {}),
+  };
+}
+
+/**
+ * Where a rule stands, in one line: `prod-*: 1 of 2 approvals (github:alice),
+ * needs 1 more from platform`.
+ */
+export function quorumRuleLine(p: GateQuorumRuleProgress): string {
+  const scope = p.targets ? p.targets.join(", ") : "every target";
+  const have = `${p.approvers.length} of ${p.count} approval${p.count === 1 ? "" : "s"}${p.approvers.length ? ` (${p.approvers.join(", ")})` : ""}`;
+  if (p.met) return `${scope}: ${have}, met`;
+  const more = p.count - p.approvers.length;
+  const needs: string[] = [];
+  if (more > 0) needs.push(`${more} more${p.roles?.length ? ` from ${p.roles.join(" or ")}` : ""}`);
+  if (p.notAuthor) needs.push(more > 0 ? "one of them not the author" : "an approver who is not the author");
+  const unknown = p.authorUnknown ? " (the change's author is not known, so no approver can show they are someone else)" : "";
+  return `${scope}: ${have}, needs ${needs.join(", ")}${unknown}`;
+}
+
+/** The rules that are not met, one line each joined by `; `. */
+export function quorumWaiting(progress: readonly GateQuorumRuleProgress[]): string {
+  return progress.filter((p) => !p.met).map(quorumRuleLine).join("; ");
+}
+
+/** Whether a rule needs a proven approver: it names roles, or `notAuthor`. */
+export const ruleNeedsProof = (rule: GateQuorumRule): boolean => (rule.roles?.length ?? 0) > 0 || rule.notAuthor === true;
+
+/** What {@link trustQuorumJudge} judges by. */
+export interface TrustQuorumInput {
+  /** The signers at base: an approval whose seal verifies for its approver against them is proven. */
+  signers: GateSigners;
+  /** `.chant/trust.json`'s role grants at base. */
+  roles: Readonly<Record<string, readonly string[]>>;
+  /** The change's authors, as principals. Absent, nobody knows who they are. */
+  authors?: readonly string[];
+  /**
+   * Under `pr-review`, the merged pull request's review, read from the forge
+   * in this run: a resolution that names this review's head and one of its
+   * approvers as `resolvedBy` is proven.
+   */
+  review?: { head: string; approvers: readonly string[] };
+}
+
+/** The judge a gate's rules are met by: proof from a seal or the live review, roles from trust.json at base. */
+export function trustQuorumJudge(input: TrustQuorumInput): GateQuorumJudge {
+  return (r) => {
+    const sealed = r.seal !== undefined && r.seal !== null && gateSealRefusal(input.signers, r) === null;
+    const reviewed =
+      input.review !== undefined && r.review?.head === input.review.head && input.review.approvers.some((a) => samePrincipal(a, r.resolvedBy));
+    const proven = sealed || reviewed;
+    return {
+      proven,
+      roles: proven ? rolesOf(r.resolvedBy, input.roles) : [],
+      ...(input.authors !== undefined ? { author: input.authors.some((a) => samePrincipal(a, r.resolvedBy)) } : {}),
+    };
+  };
+}

package/src/op/gate-resume.ts

@@ -11,6 +11,7 @@
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { latestResolutionForPlan } from "../lifecycle/gate-ledger";
 import { humanQuorumSince, tallyGateApprovals } from "./gate";
+import type { GateQuorumJudge } from "./gate-quorum";
 
 export {
   isGateRunLocator,
@@ -28,19 +29,21 @@ export {
  * gate ledger's pending facts, which place the human quorum's anchor (#3206);
  * without them it is `standing` itself. A workspace's
  * `identity.gates` rule is not applied here: the resumed job applies it, and
- * waits again when the approval does not count.
+ * waits again when the approval does not count. `judge` proves approvers
+ * for approval rules that name roles (#4290); absent, none is proven.
  */
 export function resolutionAnswering(
   resolutions: readonly GateResolutionRecord[],
   standing: PendingGateRecord,
   pending: readonly PendingGateRecord[] = [standing],
+  judge?: GateQuorumJudge,
 ): GateResolutionRecord | undefined {
   const env = standing.environment;
   const mine = resolutions.filter((r) => env === undefined || r.environment === env);
   if (standing.approval) {
-    const tally = tallyGateApprovals(mine, standing.gate, standing.timestamp, standing.planDigest, standing.approval, humanQuorumSince(pending, standing));
+    const tally = tallyGateApprovals(mine, standing.gate, standing.timestamp, standing.planDigest, standing.approval, humanQuorumSince(pending, standing), judge);
     if (tally.permit) return tally.permit;
-    return tally.counted.length >= tally.need ? tally.counted[tally.counted.length - 1] : undefined;
+    return tally.met ? tally.counted[tally.counted.length - 1] : undefined;
   }
   return latestResolutionForPlan(mine, standing.gate, standing.timestamp, standing.planDigest).resolution;
 }

package/src/op/gate-review.ts

@@ -30,7 +30,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { gateSealRefusal } from "../workspace/trust/gate-seal";
+import { gateSealRefusal } from "../lifecycle/gate-seal";
 import { readTrustPolicy, type TrustPolicy } from "../workspace/trust/policy";
 import { gitRevisionSource } from "../workspace/record-source";
 import { forgePrincipalOf, ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";

package/src/op/gate.ts

@@ -51,6 +51,10 @@ import { isModelAuthored } from "../lifecycle/gate-origin";
 import { appliedGatePath, isApprovalSpent, parseAppliedGateLines, type AppliedGateRecord } from "../lifecycle/gate-applied";
 import { sortedJsonReplacer } from "../utils";
 import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
+import {
+  quorumNeed, quorumRuleProgress, quorumRules, ruleNeedsProof, samePrincipal, trustQuorumJudge, UNPROVEN_JUDGE,
+  type GateQuorumJudge, type GateQuorumRuleProgress,
+} from "./gate-quorum";
 import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 import { ciRunIdFromEnv, resolveGateRunLocator } from "./gate-run-locator";
@@ -99,6 +103,14 @@ export interface GateLedgerPort {
    * Absent, every approval is judged as before.
    */
   approvalRule?(gate: string, at?: { base?: string }): Promise<GateApprovalRule | null>;
+  /**
+   * The judge a gate's approval rules are met by (#4290): which approvals
+   * prove their approver (a seal verified against the signers at base) and
+   * the roles `.chant/trust.json` at base gives them. `at.base` as for
+   * {@link GateLedgerPort.approvalRule}. Absent, no approval proves anyone,
+   * so a rule naming roles is never met.
+   */
+  quorumJudge?(gate: string, at?: { base?: string }): Promise<GateQuorumJudge>;
   /** The approvals a wave applied under (#3784), from `_gates/<op>/applied.jsonl`. Absent on a port that never spends approvals. */
   readApplied?(op: string): Promise<AppliedGateRecord[]>;
   /** Record that a wave is about to apply under an approval (#3784), which spends it. */
@@ -152,6 +164,12 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { gateAdmission } = await import("../workspace/identity");
       return gateAdmission(opts?.cwd ?? process.cwd(), gate, at?.base);
     },
+    async quorumJudge(_gate, at) {
+      // #4290: the signers and role grants at base, never the approver's claim.
+      const { scopeSource } = await import("../workspace/write-scope");
+      const { policy } = scopeSource(opts?.cwd ?? process.cwd(), at?.base);
+      return trustQuorumJudge({ signers: policy, roles: policy.roles });
+    },
     async appendResolution(input) {
       const { record } = await appendGateResolution(input, opts);
       return { record, ...(await pushLifecycleReport(opts)) };
@@ -293,6 +311,13 @@ export interface GateCheckInput {
    * it so `chant approve` can evaluate the policy.
    */
   approval?: ResolvedGateApproval;
+  /**
+   * Judges approvals for `approval.quorum`'s rules (#4290). Absent, the
+   * port's {@link GateLedgerPort.quorumJudge} at its default base, else no
+   * approval proves anyone. A wave passes one that knows the change's author
+   * and the merged pull request's review.
+   */
+  judge?: GateQuorumJudge;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
   /**
@@ -399,6 +424,8 @@ export interface GateQuorumProgress {
   /** Approvers whose approval counts toward the quorum, oldest first. */
   approvers: string[];
   need: number;
+  /** Where each approval rule the gate takes stands (#4290). Absent when it takes none. */
+  rules?: GateQuorumRuleProgress[];
 }
 
 /** Either the gate is answered, or it is a standing fact. */
@@ -464,8 +491,12 @@ export function approverOf(record: GateResolutionRecord): GateApprover {
 export interface GateTally {
   /** Distinct human approvers of this plan who count toward the quorum, one record each (their newest), oldest first. */
   counted: GateResolutionRecord[];
-  /** The quorum's count, 1 when the gate declares none. */
+  /** The most approvers a rule needs, 1 when the gate declares none. */
   need: number;
+  /** Every rule is met (#4290); with no rules, one human approved. */
+  met: boolean;
+  /** Where each rule stands (#4290). Absent when the gate takes no rule. */
+  rules?: GateQuorumRuleProgress[];
   /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, only for a permit recorded under `enforce`, and only under the gate's current policy version and resolved context. */
   permit?: GateResolutionRecord;
   /** The newest approval of this gate for a different plan, when the gate binds one. */
@@ -483,8 +514,12 @@ export interface GateTally {
  * pending fact re-recorded for a changed mode or context keeps a partly
  * filled quorum (#3206). It defaults to `sinceIso`.
  *
- * Of those, only a human's counts toward the quorum, once per `resolvedBy`,
- * and only with one of the quorum's roles when it names any. An agent counts
+ * Of those, only a human's counts toward the quorum, once per `resolvedBy`.
+ * The quorum is a list of rules (#4290, `./gate-quorum.ts`), already the ones
+ * the gate takes: each is met by distinct humans, counting toward `roles`
+ * only an approver `judge` proves and gives one of them (roles from
+ * `.chant/trust.json` at base, never the approver's claim), and the gate
+ * passes when every rule is met. With no rule, one human passes it. An agent counts
  * only through a recorded `allow` in `enforce` mode, evaluated under the
  * policy version the gate declares now, recorded while the gate was in
  * `enforce` (#2512), and evaluated under the context the gate resolves now
@@ -499,14 +534,16 @@ export function tallyGateApprovals(
   planDigest: string | undefined,
   approval: ResolvedGateApproval,
   humansSinceIso: string = sinceIso,
+  judge: GateQuorumJudge = UNPROVEN_JUDGE,
 ): GateTally {
   const since = new Date(sinceIso).getTime();
   const humansSince = Math.min(since, new Date(humansSinceIso).getTime());
   const at = (r: GateResolutionRecord) => new Date(r.timestamp).getTime();
-  const roles = approval.quorum?.roles;
+  const rules = quorumRules(approval.quorum);
   const context = gateContextDigest(approval.context);
 
-  const byActor = new Map<string, GateResolutionRecord>();
+  // Each human once: their newest approval, or their newest proven one when they have one.
+  const byActor = new Map<string, { record: GateResolutionRecord; proven: boolean }>();
   let permit: GateResolutionRecord | undefined;
   let mismatched: GateResolutionRecord | undefined;
   for (const r of records) {
@@ -534,20 +571,20 @@ export function tallyGateApprovals(
       permit = r;
     }
 
-    const approver = approverOf(r);
-    if (approver.kind !== "human") continue;
-    if (roles && !(approver.roles ?? []).some((role) => roles.includes(role))) continue;
-    const prior = byActor.get(r.resolvedBy);
-    if (!prior || at(r) >= at(prior)) byActor.set(r.resolvedBy, r);
+    if (approverOf(r).kind !== "human") continue;
+    const key = r.resolvedBy.normalize("NFKC").trim().toLowerCase();
+    const proven = rules.some(ruleNeedsProof) && judge(r).proven;
+    const prior = byActor.get(key);
+    if (!prior || (proven && !prior.proven) || (proven === prior.proven && at(r) >= at(prior.record))) byActor.set(key, { record: r, proven });
   }
 
-  const counted = [...byActor.values()].sort((a, b) => at(a) - at(b));
-  return {
-    counted,
-    need: approval.quorum?.count ?? 1,
-    ...(permit ? { permit } : {}),
-    ...(mismatched ? { mismatched } : {}),
-  };
+  const humans = [...byActor.values()].map((v) => v.record).sort((a, b) => at(a) - at(b));
+  const extra = { ...(permit ? { permit } : {}), ...(mismatched ? { mismatched } : {}) };
+  if (rules.length === 0) return { counted: humans, need: 1, met: humans.length >= 1, ...extra };
+  const approvers = humans.map((r) => ({ who: r.resolvedBy, at: r.timestamp, judged: judge(r) }));
+  const progress = rules.map((rule) => quorumRuleProgress(rule, approvers));
+  const counted = humans.filter((r) => progress.some((p) => p.approvers.some((a) => samePrincipal(a, r.resolvedBy))));
+  return { counted, need: quorumNeed(rules), met: progress.every((p) => p.met), rules: progress, ...extra };
 }
 
 /**
@@ -807,11 +844,15 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       standing.approval?.policy?.version === input.approval.policy?.version
         ? humanQuorumSince(pending, standing)
         : since;
-    const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval, humansSince);
+    // #4290: who an approval proves, and their roles at base, for rules that read them.
+    const judge = quorumRules(input.approval.quorum).some(ruleNeedsProof)
+      ? (input.judge ?? (await port.quorumJudge?.(input.gate)) ?? UNPROVEN_JUDGE)
+      : UNPROVEN_JUDGE;
+    const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval, humansSince, judge);
     if (tally.permit) {
       return { satisfied: true, resolution: tally.permit, via: "policy", approvals: tally.counted };
     }
-    if (tally.counted.length >= tally.need) {
+    if (tally.met) {
       return {
         satisfied: true,
         resolution: tally.counted[tally.counted.length - 1]!,
@@ -820,19 +861,19 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       };
     }
     mismatched = tally.mismatched;
-    quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need };
+    quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need, ...(tally.rules ? { rules: tally.rules } : {}) };
     // #3949: old and new approvals add up toward one quorum, each approver once.
     const counted = new Set(tally.counted.map((r) => r.resolvedBy));
     const extra = fromAliases.filter((r) => !counted.has(r.resolvedBy));
     if (extra.length > 0) {
       const asCarried = new Map(extra.map((r) => [{ version: 1, ...carriedApproval(r, input.op, input.gate, now) } as GateResolutionRecord, r]));
-      const combined = tallyGateApprovals([...resolutions, ...asCarried.keys()], input.gate, since, input.planDigest, input.approval, humansSince);
-      if (combined.counted.length >= combined.need) {
+      const combined = tallyGateApprovals([...resolutions, ...asCarried.keys()], input.gate, since, input.planDigest, input.approval, humansSince, judge);
+      if (combined.met) {
         const written = await carry(combined.counted.filter((r) => asCarried.has(r)).map((r) => asCarried.get(r)!));
         const approvals = [...combined.counted.filter((r) => !asCarried.has(r)), ...written];
         return { satisfied: true, resolution: written[written.length - 1]!, via: "alias", approvals, carried: written };
       }
-      quorum = { approvers: combined.counted.map((r) => r.resolvedBy), need: combined.need };
+      quorum = { approvers: combined.counted.map((r) => r.resolvedBy), need: combined.need, ...(combined.rules ? { rules: combined.rules } : {}) };
     }
   } else {
     const found = latestResolutionForPlan(resolutions, input.gate, since, input.planDigest);