@intentius/chant 0.77.0 → 0.79.0

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

@@ -0,0 +1,258 @@
+/**
+ * Gate approval policy (#2508): quorum, roles, and a policy decision that is
+ * logged or enforced. The rules are decided by `evaluateGate`, driven here
+ * through `memoryGateLedgerPort`; the Cedar evaluation itself is the cedar
+ * lexicon's and is tested there.
+ */
+import { describe, test, expect } from "vitest";
+import { evaluateGate, memoryGateLedgerPort, tallyGateApprovals } from "./gate";
+import { gate } from "./builders";
+import { gateApprovalProblems, gatePolicyRequest, gatePolicyVersion, type GatePolicyRef, type ResolvedGateApproval } from "./gate-approval";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+
+const PLAN_A = `sha256:${"a".repeat(64)}`;
+const PLAN_B = `sha256:${"b".repeat(64)}`;
+const TEXT = 'permit (principal is Chant::Agent, action, resource) when { context.risk == "low" };\n';
+const POLICY: GatePolicyRef = { kind: "gate-policy", lexicon: "cedar", name: "ship", version: gatePolicyVersion(TEXT), text: TEXT };
+
+const PENDING: PendingGateRecord = {
+  version: 1, kind: "pending", op: "release", gate: "ship",
+  timestamp: "2026-09-01T00:00:00.000Z", expiresAt: "2026-09-03T00:00:00.000Z", planDigest: PLAN_A,
+};
+const NOW = "2026-09-01T12:00:00.000Z";
+
+function approval(overrides: Partial<GateResolutionRecord> & { resolvedBy: string; timestamp: string }): GateResolutionRecord {
+  return { version: 1, op: "release", gate: "ship", planDigest: PLAN_A, approver: { kind: "human" }, ...overrides };
+}
+
+function allow(mode: "log-only" | "enforce" = "enforce"): GateResolutionRecord["policyDecision"] {
+  return { policy: "ship", version: POLICY.version, mode, decision: "allow", determining: ["ship-0"], errors: [] };
+}
+
+async function decide(resolutions: GateResolutionRecord[], approvalBlock: ResolvedGateApproval, planDigest = PLAN_A) {
+  const port = memoryGateLedgerPort({ resolutions, pending: [{ ...PENDING, approval: approvalBlock, planDigest }] });
+  const check = await evaluateGate(port, { op: "release", gate: "ship", planDigest, approval: approvalBlock, now: NOW });
+  return { check, port };
+}
+
+describe("gate approval — quorum (#2508)", () => {
+  const twoMaintainers: ResolvedGateApproval = { quorum: { count: 2, roles: ["maintainer"] }, mode: "log-only" };
+
+  test("quorum not met: one approval of two leaves the gate standing and reports progress", async () => {
+    const { check, port } = await decide(
+      [approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } })],
+      twoMaintainers,
+    );
+    expect(check.satisfied).toBe(false);
+    if (check.satisfied) return;
+    expect(check.quorum).toEqual({ approvers: ["alex"], need: 2 });
+    // The standing fact still describes this gate, so nothing new is appended.
+    expect(check.recorded).toBe(false);
+    expect(port.appended).toHaveLength(0);
+  });
+
+  test("quorum met: two distinct maintainers pass the gate, and both are named", async () => {
+    const { check } = await decide(
+      [
+        approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } }),
+        approval({ resolvedBy: "sam", timestamp: "2026-09-01T02:00:00.000Z", approver: { kind: "human", roles: ["maintainer", "sre"] } }),
+      ],
+      twoMaintainers,
+    );
+    expect(check.satisfied).toBe(true);
+    if (!check.satisfied) return;
+    expect(check.via).toBe("quorum");
+    expect(check.approvals?.map((r) => r.resolvedBy)).toEqual(["alex", "sam"]);
+    expect(check.resolution.resolvedBy).toBe("sam");
+  });
+
+  test("the same person approving twice counts once", async () => {
+    const { check } = await decide(
+      [
+        approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } }),
+        approval({ resolvedBy: "alex", timestamp: "2026-09-01T02:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } }),
+      ],
+      twoMaintainers,
+    );
+    expect(check.satisfied).toBe(false);
+  });
+
+  test("an approver without one of the quorum's roles does not count", async () => {
+    const { check } = await decide(
+      [
+        approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } }),
+        approval({ resolvedBy: "pat", timestamp: "2026-09-01T02:00:00.000Z", approver: { kind: "human", roles: ["viewer"] } }),
+      ],
+      twoMaintainers,
+    );
+    expect(check.satisfied).toBe(false);
+    if (check.satisfied) return;
+    expect(check.quorum?.approvers).toEqual(["alex"]);
+  });
+
+  test("a changed plan invalidates every collected approval", async () => {
+    const { check, port } = await decide(
+      [
+        approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } }),
+        approval({ resolvedBy: "sam", timestamp: "2026-09-01T02:00:00.000Z", approver: { kind: "human", roles: ["maintainer"] } }),
+      ],
+      twoMaintainers,
+      PLAN_B,
+    );
+    expect(check.satisfied).toBe(false);
+    if (check.satisfied) return;
+    expect(check.mismatch?.approved).toBe(PLAN_A);
+    expect(check.mismatch?.planned).toBe(PLAN_B);
+    expect(check.quorum).toEqual({ approvers: [], need: 2 });
+    expect(port.appended).toHaveLength(0);
+  });
+
+  test("an approval older than the standing pending fact does not count", async () => {
+    const { check } = await decide(
+      [approval({ resolvedBy: "alex", timestamp: "2026-08-31T00:00:00.000Z" })],
+      { quorum: { count: 1 }, mode: "log-only" },
+    );
+    expect(check.satisfied).toBe(false);
+  });
+
+  test("a resolution written before #2508 reads as a human, and one from a model channel as an agent", () => {
+    const legacy: GateResolutionRecord = { version: 1, op: "release", gate: "ship", resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", planDigest: PLAN_A };
+    const fromMcp: GateResolutionRecord = { ...legacy, resolvedBy: "unattested", origin: "mcp", timestamp: "2026-09-01T02:00:00.000Z" };
+    const tally = tallyGateApprovals([legacy, fromMcp], "ship", PENDING.timestamp, PLAN_A, { quorum: { count: 2 }, mode: "log-only" });
+    expect(tally.counted.map((r) => r.resolvedBy)).toEqual(["alex"]);
+  });
+});
+
+describe("gate approval — policy decisions (#2508)", () => {
+  test("log-only: an agent's permit is recorded but does not pass the gate", async () => {
+    const block: ResolvedGateApproval = { policy: POLICY, mode: "log-only", context: { risk: "low" } };
+    const { check } = await decide(
+      [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") })],
+      block,
+    );
+    expect(check.satisfied).toBe(false);
+    if (check.satisfied) return;
+    expect(check.quorum).toEqual({ approvers: [], need: 1 });
+  });
+
+  test("log-only: a human's approval passes even when the policy recorded a deny", async () => {
+    const block: ResolvedGateApproval = { policy: POLICY, mode: "log-only" };
+    const { check } = await decide(
+      [approval({
+        resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z",
+        policyDecision: { ...allow("log-only")!, decision: "deny", determining: [] },
+      })],
+      block,
+    );
+    expect(check.satisfied).toBe(true);
+    if (!check.satisfied) return;
+    expect(check.via).toBe("quorum");
+    expect(check.resolution.policyDecision?.decision).toBe("deny");
+  });
+
+  test("enforce: an agent's permit passes the gate on its own", async () => {
+    const block: ResolvedGateApproval = { quorum: { count: 2 }, policy: POLICY, mode: "enforce" };
+    const { check } = await decide(
+      [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow() })],
+      block,
+    );
+    expect(check.satisfied).toBe(true);
+    if (!check.satisfied) return;
+    expect(check.via).toBe("policy");
+    expect(check.resolution.resolvedBy).toBe("release-bot");
+  });
+
+  test("enforce: a permit recorded under an older policy version does not count", async () => {
+    const block: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
+    const { check } = await decide(
+      [approval({
+        resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" },
+        policyDecision: { ...allow()!, version: gatePolicyVersion("permit (principal, action, resource);\n") },
+      })],
+      block,
+    );
+    expect(check.satisfied).toBe(false);
+  });
+
+  test("enforce: a deny-by-default policy keeps the old behaviour, where only a human's approval counts", async () => {
+    const block: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
+    const deny = { ...allow()!, decision: "deny" as const, determining: ["floor"] };
+    const agentOnly = await decide(
+      [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: deny })],
+      block,
+    );
+    expect(agentOnly.check.satisfied).toBe(false);
+
+    const withHuman = await decide(
+      [
+        approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: deny }),
+        approval({ resolvedBy: "alex", timestamp: "2026-09-01T02:00:00.000Z", policyDecision: deny }),
+      ],
+      block,
+    );
+    expect(withHuman.check.satisfied).toBe(true);
+    if (!withHuman.check.satisfied) return;
+    expect(withHuman.check.via).toBe("quorum");
+  });
+
+  test("a changed approval block re-records the pending fact, so approve evaluates the current context", async () => {
+    const port = memoryGateLedgerPort({
+      pending: [{ ...PENDING, approval: { policy: POLICY, mode: "log-only", context: { risk: "high" } } }],
+    });
+    const check = await evaluateGate(port, {
+      op: "release", gate: "ship", planDigest: PLAN_A, now: NOW,
+      approval: { policy: POLICY, mode: "log-only", context: { risk: "low" } },
+    });
+    expect(check.satisfied).toBe(false);
+    if (check.satisfied) return;
+    expect(check.recorded).toBe(true);
+    expect(port.appended[0]?.approval?.context).toEqual({ risk: "low" });
+  });
+
+  test("a gate with no approval block decides exactly as before", async () => {
+    const port = memoryGateLedgerPort({
+      resolutions: [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" } })],
+      pending: [PENDING],
+    });
+    const check = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, now: NOW });
+    expect(check.satisfied).toBe(true);
+    if (!check.satisfied) return;
+    expect(check.via).toBeUndefined();
+  });
+});
+
+describe("gate approval — the request a policy is asked (#2508)", () => {
+  test("carries the approver, the gate and the context, with the plan digest", () => {
+    expect(gatePolicyRequest({
+      op: "release", gate: "ship", resolvedBy: "release-bot", approver: { kind: "agent", roles: ["deployer"] },
+      planDigest: PLAN_A, context: { risk: "low" },
+    })).toEqual({
+      principal: { kind: "agent", name: "release-bot", roles: ["deployer"] },
+      action: "PassGate",
+      resource: { op: "release", gate: "ship" },
+      context: { risk: "low", planDigest: PLAN_A },
+    });
+  });
+});
+
+describe("gate approval — the approval block is checked where it is written (#2508)", () => {
+  test("a well-formed block passes, and lands on the step", () => {
+    const step = gate("ship", { approval: { quorum: { count: 2, roles: ["maintainer"] }, policy: POLICY, mode: "enforce", context: { risk: "low" } } });
+    expect(step.approval?.quorum?.count).toBe(2);
+    expect(gateApprovalProblems(step.approval)).toEqual([]);
+  });
+
+  test.each([
+    [{ quorum: { count: 0 } }, "quorum.count"],
+    [{ quorum: { count: 2, roles: [] } }, "quorum.roles"],
+    [{ mode: "enforce" }, "needs an `approval.policy`"],
+    [{ mode: "strict" }, "approval.mode"],
+    [{ policy: { name: "ship" } }, "does not resolve to a gate policy set"],
+    [{ policy: { ...POLICY, version: "sha256:stale" } }, "not the digest of its text"],
+    [{ context: { risk: "low" } }, "declares none"],
+    [{ policy: POLICY, context: { risk: { level: 1 } } }, "approval.context.risk"],
+  ])("rejects %j", (block, expected) => {
+    expect(gateApprovalProblems(block).join("\n")).toContain(expected);
+    expect(() => gate("ship", { approval: block as never })).toThrow(expected);
+  });
+});

package/src/op/gate-approval.ts

@@ -0,0 +1,258 @@
+/**
+ * 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 { 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> {
+  const spec = `@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 } : {}),
+    },
+  };
+}