@intentius/chant 0.77.0 → 0.79.0

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/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) } : {}),
         },
       },
     };

package/src/op/op-ir.ts

@@ -144,6 +144,8 @@ export interface OpIRGateStep {
    * Absent on a gate that binds no plan.
    */
   plan?: GateStep["plan"];
+  /** Quorum, roles and policy (#2508), carried as authored. Absent on a gate that passes on one approval. */
+  approval?: GateStep["approval"];
 }
 
 export interface OpIREffectStep {
@@ -240,6 +242,7 @@ function irGateStep(step: GateStep): OpIRGateStep {
     timeout: step.timeout ?? "48h",
     ...(step.description ? { description: step.description } : {}),
     ...(step.plan !== undefined ? { plan: step.plan } : {}),
+    ...(step.approval !== undefined ? { approval: step.approval } : {}),
   };
 }
 
@@ -389,6 +392,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       timeout: step.timeout,
       ...(step.description ? { description: step.description } : {}),
       ...(step.plan !== undefined ? { plan: step.plan } : {}),
+      ...(step.approval !== undefined ? { approval: step.approval } : {}),
     };
   }
   return {

package/src/op/types.ts

@@ -8,6 +8,7 @@
 import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityProfileName } from "./activity-profiles";
 import type { StepOutputRef } from "./step-output-ref";
+import type { GateApproval } from "./gate-approval";
 
 export interface OpConfig {
   /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
@@ -196,6 +197,12 @@ export interface GateStepBase {
    * phase publishes no digest is not thereby unrunnable.
    */
   plan?: string | StepOutputRef;
+  /**
+   * Quorum, roles and a policy for who may pass this gate (#2508). Absent,
+   * the gate passes on one approval, as every gate did before. See
+   * `./gate-approval.ts`.
+   */
+  approval?: GateApproval;
 }
 
 /**