@intentius/chant 0.78.0 → 0.80.0

package/src/op/gate-approval.ts

@@ -0,0 +1,260 @@
+/**
+ * Gate approval policy as data (#2508).
+ *
+ * A gate used to pass on one recorded approval. This module lets a gate say
+ * more than that, as data that survives into the build output:
+ *
+ * - `quorum`: how many distinct human approvers the gate needs, and
+ *   optionally which roles count toward it.
+ * - `policy`: a policy set a lexicon rendered (the cedar lexicon's
+ *   `gatePolicy()`), evaluated for each approval as a `PassGate` request.
+ * - `mode`: `"log-only"` records the policy's decision next to the approval
+ *   and lets only the quorum bind. `"enforce"` lets a permit pass the gate on
+ *   its own, which is how an agent principal passes a low-risk plan.
+ * - `context`: plan attributes handed to the policy (risk labels, changed
+ *   paths), resolved at run time like a gate's `plan`.
+ *
+ * Core does not know Cedar. A {@link GatePolicyRef} names the lexicon that
+ * made it, and {@link loadGatePolicyEvaluator} imports that lexicon's
+ * `gate-policy` module by the same `@intentius/chant-lexicon-<name>/...`
+ * convention the activity registry uses (`./activity-registry.ts`).
+ *
+ * The policy is evaluated when an approval is recorded (`chant approve`),
+ * because that is the moment the approver is known. The decision is written
+ * on the resolution with the policy's version, and a run counts a recorded
+ * permit only while the gate still declares that same version. Editing the
+ * policy invalidates every permit recorded under the old one, the way a new
+ * plan invalidates every approval recorded for the old plan (#2300).
+ *
+ * The trust boundary is unchanged from `../lifecycle/gate-ledger.ts`: a
+ * resolution is a local fact, not a signed one, and roles on it are what the
+ * approver claimed.
+ */
+
+import { createHash } from "node:crypto";
+import { lexiconModulePath } from "../lexicon-module";
+import { isStepOutputRef, type StepOutputRef } from "./step-output-ref";
+
+/** What a policy's decision does to the gate. */
+export type GateApprovalMode = "log-only" | "enforce";
+
+export const GATE_APPROVAL_MODES: readonly GateApprovalMode[] = ["log-only", "enforce"];
+
+/**
+ * A policy set a lexicon rendered for a gate — plain data, so it lands in the
+ * Op's build output unchanged. Build one with the owning lexicon's helper
+ * (the cedar lexicon's `gatePolicy()`) rather than by hand.
+ */
+export interface GatePolicyRef {
+  kind: "gate-policy";
+  /** The lexicon whose `gate-policy` module evaluates {@link GatePolicyRef.text}. */
+  lexicon: string;
+  /** A name for the policy set, carried into every recorded decision. */
+  name: string;
+  /** Content digest of {@link GatePolicyRef.text}. A recorded permit counts only under the version it was evaluated against. */
+  version: string;
+  /** The policy set, in the lexicon's own language. */
+  text: string;
+}
+
+/** How many distinct human approvers a gate needs, and which roles count. */
+export interface GateQuorum {
+  /** At least 1. */
+  count: number;
+  /** When set, only an approver holding one of these roles counts toward {@link GateQuorum.count}. */
+  roles?: string[];
+}
+
+/** A value a gate hands its policy as context. */
+export type GateContextValue = string | number | boolean | string[] | StepOutputRef;
+
+/** The `approval` block on a `gate` step. */
+export interface GateApproval {
+  quorum?: GateQuorum;
+  policy?: GatePolicyRef;
+  /** Default `"log-only"`, so a new policy is observed against real gate traffic before it binds. */
+  mode?: GateApprovalMode;
+  /** Plan attributes handed to the policy as Cedar `context`. A {@link StepOutputRef} is resolved at run time. */
+  context?: Record<string, GateContextValue>;
+}
+
+/**
+ * {@link GateApproval} as a run resolved it: context references replaced with
+ * the values they pointed at, mode defaulted. This is what a pending fact
+ * carries, so `chant approve` evaluates the policy against the plan the run
+ * actually produced.
+ */
+export interface ResolvedGateApproval {
+  quorum?: GateQuorum;
+  policy?: GatePolicyRef;
+  mode: GateApprovalMode;
+  context?: Record<string, unknown>;
+}
+
+/** Who recorded an approval. Absent on every resolution written before #2508, which reads as a human with no roles. */
+export interface GateApprover {
+  kind: "human" | "agent";
+  roles?: string[];
+}
+
+/** One `PassGate` question put to a policy. */
+export interface GatePolicyRequest {
+  principal: { kind: GateApprover["kind"]; name: string; roles: string[] };
+  action: "PassGate";
+  resource: { op: string; gate: string };
+  /** The plan digest, when the gate binds one, plus the gate's declared context. */
+  context: Record<string, unknown>;
+}
+
+/** What a lexicon's evaluator answers. */
+export interface GatePolicyAnswer {
+  decision: "allow" | "deny";
+  /** Ids of the policies that determined the decision. */
+  determining: string[];
+  /** Per-policy evaluation errors. A policy that errors does not apply. */
+  errors: string[];
+}
+
+/** A policy's decision, as recorded on a resolution. */
+export interface GatePolicyDecision extends GatePolicyAnswer {
+  policy: string;
+  version: string;
+  /** The gate's mode when the decision was recorded. A run reads the gate's current mode, not this. */
+  mode: GateApprovalMode;
+}
+
+/** What a lexicon's `gate-policy` module exports. */
+export interface GatePolicyEvaluator {
+  evaluateGatePolicy(policy: GatePolicyRef, request: GatePolicyRequest): Promise<GatePolicyAnswer> | GatePolicyAnswer;
+}
+
+/** The version of a gate policy: `sha256:` and the hex digest of its text. A lexicon's helper stamps it, and OPS015 checks it still matches. */
+export function gatePolicyVersion(text: string): string {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+
+export function isGatePolicyRef(value: unknown): value is GatePolicyRef {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.kind === "gate-policy" &&
+    typeof v.lexicon === "string" && v.lexicon !== "" &&
+    typeof v.name === "string" && v.name !== "" &&
+    typeof v.version === "string" && v.version !== "" &&
+    typeof v.text === "string" && v.text.trim() !== ""
+  );
+}
+
+/**
+ * Everything wrong with an `approval` block, one line each. The `gate()`
+ * builder throws on the first; OPS015 reports all of them over the build
+ * output, where a block could have been written without the builder.
+ */
+export function gateApprovalProblems(approval: unknown): string[] {
+  if (typeof approval !== "object" || approval === null || Array.isArray(approval)) {
+    return ["`approval` must be an object"];
+  }
+  const a = approval as Record<string, unknown>;
+  const problems: string[] = [];
+
+  if (a.quorum !== undefined) {
+    const q = a.quorum as Record<string, unknown> | null;
+    if (typeof q !== "object" || q === null) {
+      problems.push("`approval.quorum` must be an object");
+    } else {
+      if (typeof q.count !== "number" || !Number.isInteger(q.count) || q.count < 1) {
+        problems.push("`approval.quorum.count` must be an integer of at least 1");
+      }
+      if (q.roles !== undefined) {
+        if (!Array.isArray(q.roles) || q.roles.length === 0 || q.roles.some((r) => typeof r !== "string" || r === "")) {
+          problems.push("`approval.quorum.roles` must be a non-empty list of role names");
+        }
+      }
+    }
+  }
+
+  if (a.policy !== undefined) {
+    if (!isGatePolicyRef(a.policy)) {
+      problems.push(
+        "`approval.policy` does not resolve to a gate policy set. Build it with the lexicon's helper, " +
+          "for example `gatePolicy(\"ship\", policies)` from @intentius/chant-lexicon-cedar",
+      );
+    } else if (a.policy.version !== gatePolicyVersion(a.policy.text)) {
+      problems.push(
+        `\`approval.policy\` "${a.policy.name}" has a version that is not the digest of its text, ` +
+          "so a recorded decision could not be traced to the rule that made it",
+      );
+    }
+  }
+
+  if (a.mode !== undefined && !GATE_APPROVAL_MODES.includes(a.mode as GateApprovalMode)) {
+    problems.push(`\`approval.mode\` must be one of ${GATE_APPROVAL_MODES.map((m) => `"${m}"`).join(", ")}`);
+  }
+  if (a.mode === "enforce" && a.policy === undefined) {
+    problems.push("`approval.mode: \"enforce\"` needs an `approval.policy` to enforce");
+  }
+
+  if (a.context !== undefined) {
+    if (typeof a.context !== "object" || a.context === null || Array.isArray(a.context)) {
+      problems.push("`approval.context` must be an object of plan attributes");
+    } else if (a.policy === undefined) {
+      problems.push("`approval.context` is only read by a policy, and this gate declares none");
+    } else {
+      for (const [key, value] of Object.entries(a.context)) {
+        if (!isContextValue(value)) {
+          problems.push(
+            `\`approval.context.${key}\` must be a string, number, boolean, list of strings, or a step output reference`,
+          );
+        }
+      }
+    }
+  }
+
+  return problems;
+}
+
+function isContextValue(value: unknown): boolean {
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every((v) => typeof v === "string");
+  return isStepOutputRef(value);
+}
+
+/** Import `lexicon`'s evaluator. Throws a message that names the package when it is not installed or exports none. */
+export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePolicyEvaluator> {
+  // chant #2520 — a lexicon declared by module path exports its evaluator from that module.
+  const spec = lexiconModulePath(lexicon) ?? `@intentius/chant-lexicon-${lexicon}/gate-policy`;
+  let mod: Partial<GatePolicyEvaluator>;
+  try {
+    mod = (await import(spec)) as Partial<GatePolicyEvaluator>;
+  } catch (err) {
+    throw new Error(
+      `the gate's policy is evaluated by ${spec}, which could not be loaded: ` +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+  if (typeof mod.evaluateGatePolicy !== "function") {
+    throw new Error(`${spec} exports no evaluateGatePolicy function`);
+  }
+  return mod as GatePolicyEvaluator;
+}
+
+/** The request a policy is asked about one approval. */
+export function gatePolicyRequest(input: {
+  op: string;
+  gate: string;
+  resolvedBy: string;
+  approver: GateApprover;
+  planDigest?: string;
+  context?: Record<string, unknown>;
+}): GatePolicyRequest {
+  return {
+    principal: { kind: input.approver.kind, name: input.resolvedBy, roles: input.approver.roles ?? [] },
+    action: "PassGate",
+    resource: { op: input.op, gate: input.gate },
+    context: {
+      ...(input.context ?? {}),
+      ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    },
+  };
+}

package/src/op/gate.ts

@@ -45,6 +45,9 @@ import {
   type PendingGateRecord,
 } from "../lifecycle/gate-ledger";
 import { describePlanDigest } from "../lifecycle/plan-digest";
+import { isModelAuthored } from "../lifecycle/gate-origin";
+import { sortedJsonReplacer } from "../utils";
+import type { GateApprover, ResolvedGateApproval } from "./gate-approval";
 import { pushLifecycle, requireLifecycleLedger } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 
@@ -167,6 +170,13 @@ export interface GateCheckInput {
    * the standing pending fact satisfies the gate whatever has changed since.
    */
   planDigest?: string;
+  /**
+   * The gate's quorum and policy (#2508), context already resolved. Absent,
+   * one approval passes the gate, which is the rule every gate had before.
+   * Present, {@link tallyGateApprovals} decides, and the pending fact carries
+   * it so `chant approve` can evaluate the policy.
+   */
+  approval?: ResolvedGateApproval;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
 }
@@ -212,9 +222,28 @@ export function describeGateMismatch(op: string, gate: string, mismatch: GateDig
   );
 }
 
+/** How far a gate with a quorum has got (#2508). */
+export interface GateQuorumProgress {
+  /** Approvers whose approval counts toward the quorum, oldest first. */
+  approvers: string[];
+  need: number;
+}
+
 /** Either the gate is answered, or it is a standing fact. */
 export type GateCheck =
-  | { satisfied: true; resolution: GateResolutionRecord }
+  | {
+      satisfied: true;
+      /** The approval that completed the gate: the newest counted one, or the permit that passed it. */
+      resolution: GateResolutionRecord;
+      /**
+       * Set on a gate that declares `approval` (#2508). `"quorum"` when enough
+       * human approvals were recorded, `"policy"` when an `enforce`-mode permit
+       * passed it on its own.
+       */
+      via?: "quorum" | "policy";
+      /** Every approval that counted toward the quorum. Set with `via`. */
+      approvals?: GateResolutionRecord[];
+    }
   | {
       satisfied: false;
       pending: PendingGateRecord;
@@ -230,8 +259,93 @@ export type GateCheck =
       pushWarning?: string;
       /** Present when a resolution stands for this gate but for another plan (#2300). */
       mismatch?: GateDigestMismatch;
+      /** Present on a gate with a quorum (#2508): who has approved this plan so far. */
+      quorum?: GateQuorumProgress;
     };
 
+/** How a recorded approval reads: its own `approver`, or for a record written before #2508, a human unless a model-authored channel wrote it. */
+export function approverOf(record: GateResolutionRecord): GateApprover {
+  if (record.approver) return record.approver;
+  return { kind: isModelAuthored(record.origin) ? "agent" : "human" };
+}
+
+/** What {@link tallyGateApprovals} found. */
+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. */
+  need: number;
+  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, and only under the gate's current policy version. */
+  permit?: GateResolutionRecord;
+  /** The newest approval of this gate for a different plan, when the gate binds one. */
+  mismatched?: GateResolutionRecord;
+}
+
+/**
+ * Tally the approvals that answer a gate with an `approval` block (#2508).
+ *
+ * An approval counts only if it is newer than `sinceIso` (the standing pending
+ * fact) and, on a plan-bound gate, recorded for `planDigest`. So a changed
+ * plan invalidates every approval collected for the old one, the rule #2300
+ * set for a single approval.
+ *
+ * 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
+ * only through a recorded `allow` in `enforce` mode, evaluated under the
+ * policy version the gate declares now. A `log-only` decision never changes
+ * the outcome, and a `deny` never removes a human's approval: a policy can add
+ * a way through the gate but cannot take one away.
+ */
+export function tallyGateApprovals(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+  planDigest: string | undefined,
+  approval: ResolvedGateApproval,
+): GateTally {
+  const since = new Date(sinceIso).getTime();
+  const at = (r: GateResolutionRecord) => new Date(r.timestamp).getTime();
+  const roles = approval.quorum?.roles;
+
+  const byActor = new Map<string, GateResolutionRecord>();
+  let permit: GateResolutionRecord | undefined;
+  let mismatched: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate || at(r) < since) continue;
+    if (planDigest !== undefined && r.planDigest !== planDigest) {
+      if (!mismatched || at(r) >= at(mismatched)) mismatched = r;
+      continue;
+    }
+
+    const decision = r.policyDecision;
+    if (
+      approval.mode === "enforce" && approval.policy && decision?.decision === "allow" &&
+      decision.version === approval.policy.version && (!permit || at(r) >= at(permit))
+    ) {
+      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);
+  }
+
+  const counted = [...byActor.values()].sort((a, b) => at(a) - at(b));
+  return {
+    counted,
+    need: approval.quorum?.count ?? 1,
+    ...(permit ? { permit } : {}),
+    ...(mismatched ? { mismatched } : {}),
+  };
+}
+
+/** Whether two resolved approval blocks are the same, so a standing pending fact still describes this gate. */
+function sameApproval(a: ResolvedGateApproval | undefined, b: ResolvedGateApproval | undefined): boolean {
+  return JSON.stringify(a ?? null, sortedJsonReplacer) === JSON.stringify(b ?? null, sortedJsonReplacer);
+}
+
 /** The beginning of time — the anchor for a gate that has never been recorded pending, so any resolution for it counts. */
 const EPOCH = new Date(0).toISOString();
 
@@ -263,13 +377,30 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   const { resolutions, pending } = await port.read(input.op);
 
   const standing = latestPendingGate(pending, input.gate);
-  const { resolution, mismatched } = latestResolutionForPlan(
-    resolutions,
-    input.gate,
-    standing?.timestamp ?? EPOCH,
-    input.planDigest,
-  );
-  if (resolution) return { satisfied: true, resolution };
+  const since = standing?.timestamp ?? EPOCH;
+
+  let mismatched: GateResolutionRecord | undefined;
+  let quorum: GateQuorumProgress | undefined;
+  if (input.approval) {
+    const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval);
+    if (tally.permit) {
+      return { satisfied: true, resolution: tally.permit, via: "policy", approvals: tally.counted };
+    }
+    if (tally.counted.length >= tally.need) {
+      return {
+        satisfied: true,
+        resolution: tally.counted[tally.counted.length - 1]!,
+        via: "quorum",
+        approvals: tally.counted,
+      };
+    }
+    mismatched = tally.mismatched;
+    quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need };
+  } else {
+    const found = latestResolutionForPlan(resolutions, input.gate, since, input.planDigest);
+    if (found.resolution) return { satisfied: true, resolution: found.resolution };
+    mismatched = found.mismatched;
+  }
 
   // `input.planDigest` is defined whenever `mismatched` is — `latestResolutionForPlan`
   // returns a mismatch only on the plan-bound path.
@@ -281,14 +412,20 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
         timestamp: mismatched.timestamp,
       }
     : undefined;
-  const asMismatch = mismatch ? { mismatch } : {};
+  const asMismatch = { ...(mismatch ? { mismatch } : {}), ...(quorum ? { quorum } : {}) };
 
   // A standing fact only stands for the plan it was recorded against. When
   // the plan has moved, re-recording is what gives `chant approve` (which
   // defaults to the newest pending fact's digest) the current plan to
   // approve; leaving the old fact standing would make the common path
   // approve a plan that is no longer the one being run.
-  if (standing && !isPendingGateExpired(standing, now) && standing.planDigest === input.planDigest) {
+  // The same holds for the approval block (#2508): a pending fact recorded
+  // under another policy version or another context would have `chant
+  // approve` evaluate the policy against something this run no longer has.
+  if (
+    standing && !isPendingGateExpired(standing, now) && standing.planDigest === input.planDigest &&
+    sameApproval(standing.approval, input.approval)
+  ) {
     return { satisfied: false, pending: standing, recorded: false, ...asMismatch };
   }
 
@@ -304,6 +441,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(input.runId ? { runId: input.runId } : {}),
     ...(url ? { url } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    ...(input.approval ? { approval: input.approval } : {}),
   });
   return {
     satisfied: false,

package/src/op/generate-pipeline.ts

@@ -17,6 +17,7 @@
  */
 
 import { discoverOps, type DiscoveredOp } from "./discover";
+import { lexiconModulePath } from "../lexicon-module";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -36,7 +37,7 @@ import {
 async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   let mod: Record<string, unknown>;
   try {
-    mod = (await import(`@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+    mod = (await import(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
   } catch {
     return null;
   }

package/src/op/index.ts

@@ -53,7 +53,15 @@ export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failu
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch } from "./gate";
-export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch } from "./gate";
+export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch, GateQuorumProgress, GateTally } from "./gate";
+export { tallyGateApprovals, approverOf } from "./gate";
+export {
+  gateApprovalProblems, gatePolicyRequest, gatePolicyVersion, isGatePolicyRef, loadGatePolicyEvaluator, GATE_APPROVAL_MODES,
+} from "./gate-approval";
+export type {
+  GateApproval, GateApprovalMode, GateApprover, GateContextValue, GatePolicyAnswer, GatePolicyDecision,
+  GatePolicyEvaluator, GatePolicyRef, GatePolicyRequest, GateQuorum, ResolvedGateApproval,
+} from "./gate-approval";
 export {
   computePlanDigest, isPlanDigest, describePlanDigest, PLAN_DIGEST_ALGORITHM,
 } from "../lifecycle/plan-digest";

package/src/op/local-executor.test.ts

@@ -835,3 +835,69 @@ describe("runOpLocally — a gate approves a plan, not the next run (#2300)", ()
     expect(second.status).toBe("ok");
   });
 });
+
+/**
+ * #2508: a gate with an approval block. The run resolves the block's context
+ * from the Plan phase, the pending fact carries it for `chant approve`, and the
+ * gate passes only once the quorum is met.
+ */
+describe("runOpLocally — a gate with a quorum and a policy context (#2508)", () => {
+  const NOW = "2026-09-20T12:00:00.000Z";
+
+  test("records the resolved context on the pending fact, then passes on the second approver", async () => {
+    const resolutions: GateResolutionRecord[] = [];
+    const pending: PendingGateRecord[] = [];
+    const gates: GateLedgerPort = {
+      async read() {
+        return { resolutions: [...resolutions], pending: [...pending] };
+      },
+      async appendPending(input) {
+        const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+        pending.push(record);
+        return { record, pushed: true };
+      },
+    };
+    const applied: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["assess", async () => ({ risk: "low", paths: ["src/a.ts"] })],
+      ["ship", async () => { applied.push("ship"); return {}; }],
+    ]);
+    const config = op({
+      name: "release",
+      phases: [
+        { name: "Plan", steps: [{ kind: "activity", fn: "assess", id: "assess", args: {} }] },
+        {
+          name: "Gate",
+          steps: [{
+            kind: "gate",
+            gate: "ship",
+            approval: {
+              quorum: { count: 2 },
+              context: { risk: stepOutput("assess", "risk"), paths: stepOutput("assess", "paths"), missing: stepOutput("assess", "nope") },
+            },
+          }],
+        },
+        { name: "Apply", steps: [{ kind: "activity", fn: "ship", args: {} }] },
+      ],
+    });
+    const approve = (resolvedBy: string, at: string) =>
+      resolutions.push({ version: 1, op: "release", gate: "ship", resolvedBy, timestamp: at, approver: { kind: "human" } });
+
+    const first = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: NOW });
+    expect(first.status).toBe("gated");
+    expect(first.gate?.approval).toEqual({ quorum: { count: 2 }, mode: "log-only", context: { risk: "low", paths: ["src/a.ts"] } });
+
+    approve("alex", "2026-09-20T12:05:00.000Z");
+    const second = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-09-20T12:06:00.000Z" });
+    expect(second.status).toBe("gated");
+    expect(pending).toHaveLength(1);
+
+    approve("sam", "2026-09-20T12:07:00.000Z");
+    const third = await runOpLocally(config, activities, PROFILES, undefined, { gates, now: "2026-09-20T12:08:00.000Z" });
+    expect(third.status).toBe("ok");
+    expect(applied).toEqual(["ship"]);
+    expect(third.records.find((r) => r.fn === "gate:ship")?.approval).toMatchObject({
+      resolvedBy: "sam", via: "quorum", approvers: ["alex", "sam"],
+    });
+  });
+});

package/src/op/local-executor.ts

@@ -27,6 +27,7 @@ import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
 import { describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
+import type { ResolvedGateApproval } from "./gate-approval";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger";
 import type { OpRunRecord } from "./runtime";
@@ -57,7 +58,16 @@ export interface StepRecord {
   outcomes?: Array<{ name: string; value: unknown }>;
   error?: string;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
-  approval?: { gate: string; resolvedBy: string; timestamp: string; url?: string };
+  approval?: {
+    gate: string;
+    resolvedBy: string;
+    timestamp: string;
+    url?: string;
+    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. */
+    via?: "quorum" | "policy";
+    /** On a gate with a quorum (#2508): every approver who counted toward it. */
+    approvers?: string[];
+  };
   /**
    * Why a step declined to proceed on something that is not a failure
    * (#2300): a gate holding a standing approval for a *different* plan. Names
@@ -394,6 +404,35 @@ function gateFn(step: GateStep): string {
   return `gate:${gateName(step)}`;
 }
 
+/**
+ * A gate's `approval` block as this run resolves it (#2508): each context
+ * value that is a step-output reference is replaced by what that step
+ * returned, the same walk `plan` goes through. A reference that resolves to
+ * nothing is dropped rather than failing the run, so a policy reading it sees
+ * the attribute as absent.
+ */
+function resolveGateApproval(
+  step: GateStep,
+  resultsById: ReadonlyMap<string, unknown>,
+): ResolvedGateApproval | undefined {
+  const authored = step.approval;
+  if (!authored) return undefined;
+  let context: Record<string, unknown> | undefined;
+  if (authored.context) {
+    context = {};
+    for (const [key, value] of Object.entries(authored.context)) {
+      const resolved = resolveStepOutputRefs(value, resultsById);
+      if (resolved !== undefined && resolved !== null) context[key] = resolved;
+    }
+  }
+  return {
+    ...(authored.quorum ? { quorum: authored.quorum } : {}),
+    ...(authored.policy ? { policy: authored.policy } : {}),
+    mode: authored.mode ?? "log-only",
+    ...(context ? { context } : {}),
+  };
+}
+
 /**
  * Decide one gate against the ledger. A resolution newer than the gate's
  * newest pending fact passes it, and the approver lands on the step record; a
@@ -414,6 +453,7 @@ async function runGateStep(
   // a run over a missing digest.
   const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
   const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
+  const approval = resolveGateApproval(step, resultsById);
   let check: GateCheck;
   try {
     check = await evaluateGate(gates.port, {
@@ -423,6 +463,7 @@ async function runGateStep(
       ...(step.timeout ? { timeout: step.timeout } : {}),
       ...(gates.runId ? { runId: gates.runId } : {}),
       ...(planDigest !== undefined ? { planDigest } : {}),
+      ...(approval ? { approval } : {}),
       ...(gates.now ? { now: gates.now } : {}),
     });
   } catch (err) {
@@ -460,6 +501,8 @@ async function runGateStep(
           resolvedBy: resolution.resolvedBy,
           timestamp: resolution.timestamp,
           ...(resolution.url ? { url: resolution.url } : {}),
+          ...(check.via ? { via: check.via } : {}),
+          ...(check.approvals ? { approvers: check.approvals.map((r) => r.resolvedBy) } : {}),
         },
       },
     };