@intentius/chant 0.78.0 → 0.80.0

package/src/lint/rules/comp/comp003-mutating-no-rollback.ts

@@ -24,9 +24,8 @@
  * component.schema.json), a component may attach a `noRollback: "<reason>"`
  * string property directly on the step to declare the compensation gap is
  * intentional and understood, or supply its own explicit compensation via a
- * component-level `rollback` field (as the ALB/ECS pilot does with
- * `rollback-previous`) or a sibling `rollback-previous`/`snapshot-before` step
- * in the same phase.
+ * component-level `rollback` field or a sibling
+ * `rollback-previous`/`snapshot-before` step in the same phase.
  *
  * Triggers on: a bare `{ kind: "run-migration", ... }` step with no
  * `noRollback` reason, no component-level `rollback`, and no sibling

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/activity-contract-registry.ts

@@ -36,6 +36,7 @@
 
 import * as coreContracts from "./activities/activity-contracts";
 import { collectActivityContracts, type ActivityContract } from "./activity-contract";
+import { importLexiconModule } from "../lexicon-module";
 
 /**
  * The shape {@link loadActivityContracts} reads off a plugin: an optional
@@ -74,16 +75,29 @@ export async function loadActivityContracts(
 
   for (const entry of lexicons) {
     const name = typeof entry === "string" ? entry : entry.name;
+    let contributor: LexiconActivityContractContributor | undefined = typeof entry === "string" ? undefined : entry;
     try {
-      const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
-      collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+      // chant #2520 — a lexicon declared by module path has no subpath to
+      // import. Its plugin's `activityContracts()` member stands in for it;
+      // given only the name, the plugin is read from the declared module.
+      const local = await importLexiconModule(name);
+      if (local !== undefined) {
+        contributor ??= Object.values(local).find(
+          (v): v is LexiconActivityContractContributor =>
+            typeof v === "object" && v !== null && (v as { name?: unknown }).name === name &&
+            typeof (v as { activityContracts?: unknown }).activityContracts === "function",
+        );
+      } else {
+        const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
+        collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+      }
     } catch {
       // Lexicon absent or declares no contracts at the conventional subpath.
     }
 
-    if (typeof entry !== "string" && typeof entry.activityContracts === "function") {
+    if (contributor !== undefined && typeof contributor.activityContracts === "function") {
       try {
-        for (const contract of entry.activityContracts()) contracts.set(contract.name, contract);
+        for (const contract of contributor.activityContracts()) contracts.set(contract.name, contract);
       } catch {
         // A plugin member that throws contributes nothing, the same as one that is absent.
       }

package/src/op/activity-registry.ts

@@ -12,6 +12,7 @@
 
 import * as baseActivities from "./activities";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
+import { importLexiconModule } from "../lexicon-module";
 
 export type { ActivityProfile } from "./activity-profiles";
 
@@ -52,6 +53,16 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
 
   for (const name of lexicons) {
     try {
+      // chant #2520 — a lexicon declared by module path has no subpath to
+      // import; its plugin's `activities()` member stands in for it.
+      const local = await importLexiconModule(name);
+      if (local !== undefined) {
+        const plugin = Object.values(local).find((v) => isActivityContributor(v) && v.name === name) as
+          | ActivityContributor
+          | undefined;
+        if (plugin) collectActivities(await plugin.activities(), activities);
+        continue;
+      }
       const spec = `@intentius/chant-lexicon-${name}/op/activities`;
       collectActivities((await import(spec)) as Record<string, unknown>, activities);
     } catch {
@@ -62,6 +73,21 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
   return activities;
 }
 
+/** A plugin-shaped export with an `activities()` member (`LexiconPlugin.activities`). Structural, so this layer does not import `../lexicon.ts`. */
+interface ActivityContributor {
+  name: string;
+  activities(): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+
+function isActivityContributor(value: unknown): value is ActivityContributor {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { name?: unknown }).name === "string" &&
+    typeof (value as { activities?: unknown }).activities === "function"
+  );
+}
+
 /**
  * The built-in profile table. Kept async because it is awaited on the CLI's
  * run path alongside {@link loadActivities}, and because a hosted runtime may

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

package/src/op/discover-convergence.test.ts

@@ -0,0 +1,70 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverOps } from "./discover";
+import { resetDiscoveryWarnings } from "../discovery/convergence";
+
+/**
+ * chant#2527's warning release for Op discovery. The upward search for the
+ * Op root stays as it is; what changes next release is the downward walk,
+ * which stops at child projects. Today an Op in a child project is
+ * discovered, and it still is here, with a warning naming it.
+ */
+let fakeGitRoot = "";
+vi.mock("../runtime-adapter", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../runtime-adapter")>()),
+  getRuntime: () => ({
+    spawn: async (cmd: string[]) =>
+      cmd[0] === "git" && cmd[1] === "rev-parse"
+        ? { stdout: fakeGitRoot, stderr: "", exitCode: 0 }
+        : { stdout: "", stderr: "", exitCode: 0 },
+  }),
+}));
+
+const OP_FILE = (name: string): string =>
+  `export default { props: { name: ${JSON.stringify(name)}, overview: "t", phases: [{ name: "Run", steps: [] }] } };\n`;
+
+describe("discoverOps — an Op in a child project (#2527 warning release)", () => {
+  let root: string;
+  let stderr: string[];
+
+  beforeEach(() => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-2527-ops-")));
+    fakeGitRoot = root;
+    resetDiscoveryWarnings();
+    stderr = [];
+    vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => void stderr.push(args.join(" ")));
+    vi.spyOn(process, "cwd").mockReturnValue(root);
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    mkdirSync(join(root, "ops"), { recursive: true });
+    writeFileSync(join(root, "ops", "mine.op.ts"), OP_FILE("mine"));
+    mkdirSync(join(root, "child", "ops"), { recursive: true });
+    writeFileSync(join(root, "child", "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    writeFileSync(join(root, "child", "ops", "theirs.op.ts"), OP_FILE("theirs"));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test("is still discovered, and the warning names it with the include glob", async () => {
+    const { ops, errors } = await discoverOps({ cwd: root });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()].sort()).toEqual(["mine", "theirs"]);
+    expect(stderr).toEqual([
+      "warning: Op discovery under the current directory changes in the next release (chant#2527):\n" +
+        "  child/ops/theirs.op.ts: child/ is a child project with its own chant.config. " +
+        "Discovery stops at child projects from the next release. " +
+        'To keep reading it after the change, add "child" to include in chant.config.json, which the next release honours.',
+    ]);
+  });
+
+  test("with the glob in the config, nothing is printed", async () => {
+    writeFileSync(join(root, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], include: ["child"] }));
+    const { ops } = await discoverOps({ cwd: root });
+    expect([...ops.keys()].sort()).toEqual(["mine", "theirs"]);
+    expect(stderr).toEqual([]);
+  });
+});

package/src/op/discover.ts

@@ -3,6 +3,7 @@ import { readdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import type { OpConfig } from "./types";
+import { warnDiscoveryChanges } from "../discovery/convergence";
 
 export interface DiscoveredOp {
   config: OpConfig;
@@ -148,6 +149,9 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   const root = await findDiscoveryRoot(opts?.cwd);
   const files = await collectOpFiles(root);
+  // #2527's warning release: Op discovery stops at child projects below the
+  // root next release, and skips git-ignored files. `files` is unchanged.
+  await warnDiscoveryChanges({ walker: "ops", root, files });
 
   const nameToFile = new Map<string, string>();
 

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);
+  });
+});