@intentius/chant 0.78.0 → 0.79.0

package/dist/op/types.d.ts

@@ -7,6 +7,7 @@
 import type { EffectReceiptRef } from "./receipt-store.js";
 import type { ActivityProfileName } from "./activity-profiles.js";
 import type { StepOutputRef } from "./step-output-ref.js";
+import type { GateApproval } from "./gate-approval.js";
 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. */
     name: string;
@@ -184,6 +185,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;
 }
 /**
  * A human approval decided against the gate ledger. The name lives on `gate`;

package/dist/op/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/op/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACvB,2JAA2J;IAC3J,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,UAAU,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;CAC1D;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAA;CAAE,GAAG,gBAAgB,EAAE,CAI1H;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,4EAA4E;IAC5E,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,EAAE,KAAK,CAAC,YAAY,GAAG,QAAQ,CAAC,CAAC;IACtC,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GACjC,CACI;IACE,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACD;IACE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;CACpB,CACJ,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/op/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.78.0",
+  "version": "0.79.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/operator.test.ts

@@ -17,6 +17,7 @@ const readGateLedgerMock = vi.fn();
 const readRunLedgerMock = vi.fn();
 const pushLifecycleMock = vi.fn();
 const requireLifecycleLedgerMock = vi.fn();
+const loadGatePolicyEvaluatorMock = vi.fn();
 
 vi.mock("../../op/operator", async () => {
   const actual = await vi.importActual<typeof import("../../op/operator")>("../../op/operator");
@@ -69,6 +70,11 @@ vi.mock("../../lifecycle/git", async () => {
   };
 });
 
+vi.mock("../../op/gate-approval", async () => {
+  const actual = await vi.importActual<typeof import("../../op/gate-approval")>("../../op/gate-approval");
+  return { ...actual, loadGatePolicyEvaluator: (...args: unknown[]) => loadGatePolicyEvaluatorMock(...args) };
+});
+
 // Imported after the mocks above are registered.
 const { runOperator, runOperatorStatus, runOperatorLog, runApprove } = await import("./operator");
 
@@ -979,3 +985,82 @@ describe("runApprove — a push that does not land is reported (#2309 review)",
     errSpy.mockRestore();
   });
 });
+
+describe("runApprove — a gate with an approval policy (#2508)", () => {
+  const TEXT = "permit (principal is Chant::Agent, action, resource);\n";
+  const POLICY = { kind: "gate-policy" as const, lexicon: "cedar", name: "ship", version: "sha256:v1", text: TEXT };
+
+  function seedPolicyGate(mode: "log-only" | "enforce"): void {
+    readGateLedgerMock.mockResolvedValue({
+      resolutions: [],
+      pending: [{
+        version: 1, kind: "pending", op: "fountain-apply", gate: "rollout-gate",
+        timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z", planDigest: PLAN_A,
+        approval: { quorum: { count: 2, roles: ["maintainer"] }, policy: POLICY, mode, context: { risk: "low" } },
+      }],
+      malformed: 0,
+    });
+    appendGateResolutionMock.mockImplementation(async (input: Record<string, unknown>) => ({
+      commit: "sha",
+      record: { version: 1, ...input },
+    }));
+  }
+
+  test("evaluates the policy for an agent's approval and records the decision next to it", async () => {
+    seedPolicyGate("enforce");
+    const evaluateGatePolicy = vi.fn().mockResolvedValue({ decision: "allow", determining: ["agent-low-risk"], errors: [] });
+    loadGatePolicyEvaluatorMock.mockResolvedValue({ evaluateGatePolicy });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "release-bot", agent: true }))).toBe(0);
+
+    expect(loadGatePolicyEvaluatorMock).toHaveBeenCalledWith("cedar");
+    expect(evaluateGatePolicy).toHaveBeenCalledWith(POLICY, {
+      principal: { kind: "agent", name: "release-bot", roles: [] },
+      action: "PassGate",
+      resource: { op: "fountain-apply", gate: "rollout-gate" },
+      context: { risk: "low", planDigest: PLAN_A },
+    });
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({
+      approver: { kind: "agent" },
+      policyDecision: {
+        policy: "ship", version: "sha256:v1", mode: "enforce",
+        decision: "allow", determining: ["agent-low-risk"], errors: [],
+      },
+    }));
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("In enforce mode this permit passes the gate on its own");
+    expect(out).toContain("An agent's approval does not count toward the quorum");
+    errSpy.mockRestore();
+  });
+
+  test("records a human's roles, and reports quorum progress with a log-only decision", async () => {
+    seedPolicyGate("log-only");
+    loadGatePolicyEvaluatorMock.mockResolvedValue({
+      evaluateGatePolicy: async () => ({ decision: "deny", determining: [], errors: [] }),
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex", roles: ["maintainer"] }))).toBe(0);
+
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({
+      approver: { kind: "human", roles: ["maintainer"] },
+    }));
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toContain("log-only mode, so the decision is recorded and does not change the outcome");
+    expect(out).toContain("Quorum: 1 of 2 human approval(s) with role maintainer for this plan (alex)");
+    errSpy.mockRestore();
+  });
+
+  test("refuses, and writes nothing, when the policy cannot be evaluated", async () => {
+    seedPolicyGate("enforce");
+    loadGatePolicyEvaluatorMock.mockRejectedValue(new Error("@intentius/chant-lexicon-cedar/gate-policy could not be loaded"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(1);
+
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain('declares policy "ship", which could not be evaluated');
+    errSpy.mockRestore();
+  });
+});

package/src/cli/handlers/operator.ts

@@ -38,6 +38,11 @@ import {
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
 import { isPlanDigest } from "../../lifecycle/plan-digest";
+import {
+  gatePolicyRequest, loadGatePolicyEvaluator,
+  type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
+} from "../../op/gate-approval";
+import { approverOf, tallyGateApprovals } from "../../op/gate";
 import { FAN_OUT_GATE_OP } from "../../op/gate-name";
 import { pushLifecycle, requireLifecycleLedger } from "../../lifecycle/git";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
@@ -698,6 +703,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     url: ctx.args.url,
     plan: ctx.args.plan,
     allowSameOrigin: ctx.args.allowSameOrigin,
+    ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
+    ...(ctx.args.agent ? { agent: true } : {}),
   });
   if (!outcome.ok) return 1;
 
@@ -739,6 +746,15 @@ export interface GateApprovalOptions {
    * stays one command: run, read what it planned, approve it.
    */
   plan?: string;
+  /** `--role` (#2508) — roles the approver claims. */
+  roles?: string[];
+  /**
+   * `--agent` (#2508) — record this as an agent's approval. On a
+   * model-authored channel it is one whether or not this is set.
+   */
+  agent?: boolean;
+  /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
+  evaluator?: GatePolicyEvaluator;
 }
 
 export type GateApprovalOutcome =
@@ -841,7 +857,8 @@ export async function recordGateApproval(
   // resolved over the same one has no second party in it. Refused by default,
   // the way #2300 refuses a plan nobody approved.
   const origin = opts.origin ?? currentGateOrigin();
-  const standingForOrigin = latestPendingGate((await readGateLedger(opName)).pending, gate);
+  const ledger = await readGateLedger(opName);
+  const standingForOrigin = latestPendingGate(ledger.pending, gate);
   const refusal = sameOriginRefusal(standingForOrigin?.origin, origin);
   if (refusal && !opts.allowSameOrigin) {
     console.error(formatError({
@@ -862,11 +879,58 @@ export async function recordGateApproval(
       ? UNATTESTED_APPROVER
       : process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown");
 
+  // #2508: who this is, as the gate's quorum and policy read it. A model on
+  // MCP or ACP is an agent whatever it claims, the same reasoning that gives
+  // it `UNATTESTED_APPROVER` for a name.
+  const approver: GateApprover = {
+    kind: opts.agent || isModelAuthored(origin) ? "agent" : "human",
+    ...(opts.roles && opts.roles.length > 0 ? { roles: [...new Set(opts.roles)] } : {}),
+  };
+
+  // #2508: a gate with a policy has it evaluated for this approval now, while
+  // the approver is known, against the context the gated run recorded. The
+  // decision is written next to the approval, so a pass can be traced to the
+  // rule that allowed it.
+  const approval = standingForOrigin?.approval;
+  let policyDecision: GatePolicyDecision | undefined;
+  if (approval?.policy) {
+    try {
+      const evaluator = opts.evaluator ?? (await loadGatePolicyEvaluator(approval.policy.lexicon));
+      const answer = await evaluator.evaluateGatePolicy(
+        approval.policy,
+        gatePolicyRequest({
+          op: opName,
+          gate,
+          resolvedBy,
+          approver,
+          ...(planDigest !== undefined ? { planDigest } : {}),
+          ...(approval.context ? { context: approval.context } : {}),
+        }),
+      );
+      policyDecision = {
+        policy: approval.policy.name,
+        version: approval.policy.version,
+        mode: approval.mode,
+        decision: answer.decision,
+        determining: answer.determining,
+        errors: answer.errors,
+      };
+    } catch (err) {
+      console.error(formatError({
+        message: `Gate "${gate}" on "${opName}" declares policy "${approval.policy.name}", which could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
+        hint: `Install the ${approval.policy.lexicon} lexicon in this project, or approve from a checkout that has it.`,
+      }));
+      return { ok: false };
+    }
+  }
+
   const { record } = await appendGateResolution({
     op: opName,
     gate,
     resolvedBy,
     timestamp: new Date().toISOString(),
+    approver,
+    ...(policyDecision ? { policyDecision } : {}),
     ...(opts.note ? { note: opts.note } : {}),
     ...(url ? { url } : {}),
     ...(planDigest !== undefined ? { planDigest } : {}),
@@ -889,5 +953,56 @@ export async function recordGateApproval(
         "differs refuses rather than applying it.",
     ));
   }
+  if (approval) {
+    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin)) {
+      console.error(formatInfo(line));
+    }
+  }
   return { ok: true, record };
 }
+
+/**
+ * What a just-recorded approval did to a gate with an `approval` block
+ * (#2508): the policy's decision and whether it binds, then the quorum count
+ * for this plan. The run decides the gate from the ledger; these lines only
+ * say what it will find.
+ */
+export function describeApprovalProgress(
+  approval: ResolvedGateApproval,
+  record: GateResolutionRecord,
+  prior: GateResolutionRecord[],
+  standing: PendingGateRecord | undefined,
+): string[] {
+  const lines: string[] = [];
+  const decision = record.policyDecision;
+  if (decision) {
+    const rules = decision.determining.length > 0 ? ` (${decision.determining.join(", ")})` : "";
+    const binds =
+      approval.mode === "enforce"
+        ? decision.decision === "allow"
+          ? "In enforce mode this permit passes the gate on its own."
+          : "In enforce mode only a permit passes the gate on its own, so this approval counts only toward the quorum."
+        : "The gate is in log-only mode, so the decision is recorded and does not change the outcome.";
+    lines.push(`Policy "${decision.policy}" ${decision.version}: ${decision.decision}${rules}. ${binds}`);
+    for (const error of decision.errors) lines.push(`Policy evaluation error: ${error}`);
+  }
+
+  const tally = tallyGateApprovals(
+    [...prior, record],
+    record.gate,
+    standing?.timestamp ?? new Date(0).toISOString(),
+    record.planDigest,
+    approval,
+  );
+  const roles = approval.quorum?.roles ? ` with role ${approval.quorum.roles.join(" or ")}` : "";
+  const who = tally.counted.map((r) => r.resolvedBy).join(", ") || "none yet";
+  lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);
+  if (!tally.counted.includes(record)) {
+    lines.push(
+      approverOf(record).kind === "agent"
+        ? "An agent's approval does not count toward the quorum."
+        : `This approval does not count toward the quorum: the approver claims none of its roles (${approval.quorum?.roles?.join(", ")}).`,
+    );
+  }
+  return lines;
+}

package/src/cli/main.ts

@@ -51,6 +51,7 @@ import type { LexiconPlugin } from "../lexicon";
 const BOOLEAN_FLAGS = new Set([
   "--help",
   "--agents",
+  "--agent",
   "--all-projects",
   "--force",
   "--fix",
@@ -419,6 +420,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.note = args[++i];
     } else if (arg === "--expire") {
       result.expire = true;
+    } else if (arg === "--role") {
+      // #2508 — a role the approver holds, for a gate whose quorum names
+      // roles. Repeatable, and a comma list works too.
+      const value = args[++i] ?? "";
+      result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
+    } else if (arg === "--agent") {
+      // #2508 — record the approval as an agent's rather than a person's.
+      result.agent = true;
     } else if (arg === "--allow-same-origin") {
       // chant#2384 — record a resolution the same-origin rule would refuse,
       // deliberately. Flagged on the record, not just accepted quietly.

package/src/cli/registry.ts

@@ -364,6 +364,10 @@ export interface ParsedArgs {
    * on a model-authored channel.
    */
   allowSameOrigin?: boolean;
+  /** `chant approve --role <name>` (#2508) — roles the approver claims, for a gate whose quorum counts only some roles. Repeatable; a comma list also works. */
+  roles?: string[];
+  /** `chant approve --agent` (#2508) — record the approval as an agent's. An agent never counts toward a quorum; it passes a gate only through a policy permit in `enforce` mode. */
+  agent?: boolean;
   /** `chant approve <op> <gate> --plan <digest>` (#2300) — the plan this approval is for, as `sha256:<64 hex>`. Omitted, the digest is taken from the gate's standing pending fact, which is the plan the run that stopped at the gate actually produced; pass it to approve a plan explicitly, or to approve one before any run has recorded a pending fact. */
   plan?: string;
   /** `chant operator log --op <name>` (#2029) — restrict the tick history to one ConvergeOp by name. Omitted, every discovered ConvergeOp's ticks are merged into one timeline. */

package/src/lifecycle/gate-ledger.ts

@@ -43,6 +43,7 @@
  */
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
+import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 const DIR = "_gates";
@@ -160,6 +161,21 @@ export interface GateResolutionRecord {
    * later should see which approvals had a second party and which did not.
    */
   sameOriginOverride?: boolean;
+  /**
+   * Whether a person or an agent recorded this, and the roles they claimed
+   * (#2508). Only a human approval counts toward a gate's quorum; an agent
+   * passes a gate only through a policy permit in `enforce` mode.
+   *
+   * Absent on every resolution written before #2508, and read as a human with
+   * no roles. Roles are claimed, not verified, the same local trust boundary
+   * as `resolvedBy`.
+   */
+  approver?: GateApprover;
+  /**
+   * The gate policy's decision for this approval (#2508), evaluated when it
+   * was recorded. Present only when the gate declared a policy.
+   */
+  policyDecision?: GatePolicyDecision;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -212,6 +228,12 @@ export interface PendingGateRecord {
    * and resolved over MCP has one author, not two.
    */
   origin?: GateOrigin;
+  /**
+   * The gate's quorum and policy (#2508), with its context resolved against
+   * this run. `chant approve` reads it to evaluate the policy against the plan
+   * the run produced, and `chant operator status` to show quorum progress.
+   */
+  approval?: ResolvedGateApproval;
 }
 
 export type PendingGateInput = Omit<PendingGateRecord, "version" | "kind">;

package/src/lint/rules/op/index.ts

@@ -12,12 +12,14 @@ import type { PostSynthCheck } from "../../post-synth";
 import { ops012 } from "./ops012-activity-contract";
 import { ops013 } from "./ops013-step-output-ref";
 import { ops014 } from "./ops014-converge-rule-refusals";
+import { ops015 } from "./ops015-gate-approval";
 
 export { ops012 } from "./ops012-activity-contract";
 export { ops013 } from "./ops013-step-output-ref";
 export { ops014 } from "./ops014-converge-rule-refusals";
+export { ops015 } from "./ops015-gate-approval";
 
-/** Core's own post-synth checks over the Op model — OPS012, OPS013, OPS014. */
+/** Core's own post-synth checks over the Op model — OPS012, OPS013, OPS014, OPS015. */
 export function coreOpChecks(): PostSynthCheck[] {
-  return [ops012, ops013, ops014];
+  return [ops012, ops013, ops014, ops015];
 }

package/src/lint/rules/op/ops015-gate-approval.test.ts

@@ -0,0 +1,67 @@
+/**
+ * OPS015 (#2508) — a gate's approval block, checked over the build output.
+ */
+
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "../../post-synth";
+import { DECLARABLE_MARKER } from "../../../declarable";
+import { gatePolicyVersion } from "../../../op/gate-approval";
+import { ops015 } from "./ops015-gate-approval";
+
+const TEXT = "permit (principal, action, resource);\n";
+const POLICY = { kind: "gate-policy", lexicon: "cedar", name: "ship", version: gatePolicyVersion(TEXT), text: TEXT };
+
+function ctxWith(phases: unknown[], onFailure?: unknown[]): PostSynthContext {
+  const entities = new Map<string, unknown>([["release", {
+    [DECLARABLE_MARKER]: true,
+    entityType: "Chant::Op",
+    lexicon: "chant",
+    kind: "resource",
+    props: { name: "release", overview: "test", phases, ...(onFailure ? { onFailure } : {}) },
+    attributes: {},
+  }]]);
+  return {
+    outputs: new Map([["chant", ""]]),
+    entities: entities as Map<string, never>,
+    buildResult: { outputs: new Map([["chant", ""]]), entities: entities as Map<string, never>, warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+const gateStep = (approval: unknown) => ({ kind: "gate", gate: "ship", approval });
+
+describe("OPS015", () => {
+  test("a well-formed approval block passes", () => {
+    const ctx = ctxWith([{ name: "Apply", steps: [gateStep({ quorum: { count: 2 }, policy: POLICY, mode: "enforce" })] }]);
+    expect(ops015.check(ctx)).toEqual([]);
+  });
+
+  test("a gate with no approval block is not this rule's concern", () => {
+    expect(ops015.check(ctxWith([{ name: "Apply", steps: [{ kind: "gate", gate: "ship" }] }]))).toEqual([]);
+  });
+
+  test("a policy that is not a gate policy set is refused, naming the op and gate", () => {
+    const ctx = ctxWith([{ name: "Apply", steps: [gateStep({ policy: "dist/ship.cedar" })] }]);
+    const [diag] = ops015.check(ctx);
+    expect(diag?.checkId).toBe("OPS015");
+    expect(diag?.severity).toBe("error");
+    expect(diag?.message).toContain('Op "release", gate "ship"');
+    expect(diag?.message).toContain("does not resolve to a gate policy set");
+  });
+
+  test("a policy whose text was edited after it was stamped is refused", () => {
+    const ctx = ctxWith([{ name: "Apply", steps: [gateStep({ policy: { ...POLICY, text: "forbid (principal, action, resource);\n" } })] }]);
+    expect(ops015.check(ctx)[0]?.message).toContain("not the digest of its text");
+  });
+
+  test("reports every problem, including a gate nested in an effect step and one in onFailure", () => {
+    const ctx = ctxWith(
+      [{ name: "Apply", steps: [{ kind: "effect", receipt: {}, steps: [gateStep({ quorum: { count: 0 }, mode: "enforce" })] }] }],
+      [{ name: "Rollback", steps: [gateStep({ mode: "sometimes" })] }],
+    );
+    const messages = ops015.check(ctx).map((d) => d.message);
+    expect(messages).toHaveLength(3);
+    expect(messages.join("\n")).toContain("quorum.count");
+    expect(messages.join("\n")).toContain("needs an `approval.policy`");
+    expect(messages.join("\n")).toContain("approval.mode");
+  });
+});

package/src/lint/rules/op/ops015-gate-approval.ts

@@ -0,0 +1,57 @@
+/**
+ * OPS015: a gate's `approval` block (#2508) must be well formed. The quorum
+ * count is an integer of at least 1, roles are named, the mode is `log-only`
+ * or `enforce`, `enforce` has a policy to enforce, and `policy` resolves to a
+ * gate policy set a lexicon rendered, with a version that is still the digest
+ * of its text.
+ *
+ * `gate()` already throws on the first of these. This check runs over the
+ * build output, so it also covers a gate step written without the builder and
+ * reports every problem rather than the first.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import type { OpConfig, PhaseDefinition, StepDefinition } from "../../../op/types";
+import { gateApprovalProblems } from "../../../op/gate-approval";
+import { gateName } from "../../../op/gate-name";
+import { isOpEntity } from "./support";
+
+function* gateSteps(phases: PhaseDefinition[] | undefined): Generator<StepDefinition & { kind: "gate" }> {
+  for (const phase of phases ?? []) {
+    for (const step of phase.steps ?? []) {
+      if (step.kind === "gate") yield step;
+      else if (step.kind === "effect") {
+        for (const nested of step.steps ?? []) if (nested.kind === "gate") yield nested;
+      }
+    }
+  }
+}
+
+export const ops015: PostSynthCheck = {
+  id: "OPS015",
+  description:
+    "A gate's approval block is well formed: quorum count at least 1, roles named, mode log-only or enforce, enforce has a policy, and policy resolves to a gate policy set whose version is the digest of its text",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [entityKey, entity] of ctx.entities) {
+      if (!isOpEntity(entity)) continue;
+      const rec = entity as unknown as Record<string, unknown>;
+      const props = ((entity as { props?: Record<string, unknown> }).props ?? {}) as unknown as OpConfig;
+      if (!Array.isArray(props.phases)) continue;
+
+      for (const step of [...gateSteps(props.phases), ...gateSteps(props.onFailure)]) {
+        if (step.approval === undefined) continue;
+        for (const problem of gateApprovalProblems(step.approval)) {
+          diagnostics.push({
+            checkId: "OPS015",
+            severity: "error",
+            message: `Op "${props.name}", gate "${gateName(step)}": ${problem}`,
+            entity: entityKey,
+            lexicon: typeof rec.lexicon === "string" ? rec.lexicon : undefined,
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/op/builders.ts

@@ -2,6 +2,7 @@ import { OpResource } from "./resource";
 import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
 import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
 import { receiptCheckInput } from "./receipt-store";
+import { gateApprovalProblems } from "./gate-approval";
 import { makeOutProxy, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
 import type { ChantBuildArgs } from "./activities/build";
 import type { ShellCmdArgs } from "./activities/shell";
@@ -112,17 +113,25 @@ export function activity(
  * Plan phase's own digest, `plan.out.planDigest`. Then a resolution counts
  * only for that plan, and a run whose fresh plan differs is refused by name
  * instead of applying a change nobody approved. See {@link GateStep.plan}.
+ *
+ * Pass `approval` to require a quorum of human approvers, or to evaluate a
+ * policy for each approval (#2508). See {@link GateStep.approval}.
  */
 export function gate(
   name: string,
-  opts?: { timeout?: string; description?: string; plan?: GateStep["plan"] },
+  opts?: { timeout?: string; description?: string; plan?: GateStep["plan"]; approval?: GateStep["approval"] },
 ): GateStep {
+  if (opts?.approval !== undefined) {
+    const problems = gateApprovalProblems(opts.approval);
+    if (problems.length > 0) throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
+  }
   return {
     kind: "gate",
     gate: name,
     ...(opts?.timeout ? { timeout: opts.timeout } : {}),
     ...(opts?.description ? { description: opts.description } : {}),
     ...(opts?.plan !== undefined ? { plan: opts.plan } : {}),
+    ...(opts?.approval !== undefined ? { approval: opts.approval } : {}),
   };
 }