@intentius/chant 0.124.40 → 0.124.42

package/src/components/pr-policy.ts

@@ -0,0 +1,211 @@
+/**
+ * Gate-time policy on the pull-request path (#4294): `ci.policy` in the
+ * workspace declaration, run by `chant components pr-plan` and `pr-apply`
+ * over the change-set document the gate binds (`CapabilityPlan.changeSet`,
+ * composed by `planPrSet`).
+ *
+ * The settings and the policy directory are both read at the base the job
+ * measures the change from, so a pull request cannot loosen, edit or delete
+ * the policy that judges it. The engine and its result shapes are
+ * `../gate-policy.ts`.
+ *
+ * - deny: pr-apply applies nothing unless an override counts
+ *   (`../override-gate.ts`, subject the gate's op, such as `pr-12`). The
+ *   first refusal records the denial on `_gates/policy-override.jsonl`, so
+ *   `chant approve policy-override <op> --rule <id> --reason <text>` can
+ *   answer it. The gate's own approval is still needed. The override is
+ *   spent just before anything applies.
+ * - hold: the plan needs a person's approval of its own digest. pr-apply
+ *   always asks for one, so a hold changes one path: a green commit's plan
+ *   no longer applies under the approvals of the merges it carries.
+ * - error: the policy did not run or gave no readable answer. pr-apply
+ *   applies nothing.
+ */
+
+import { readDeclaration, WorkspaceReadError } from "../workspace/declaration";
+import { locateWorkspace } from "../workspace/which-chant";
+import type { WorkspaceTree } from "../workspace/tree";
+import {
+  checkGatePolicy,
+  DEFAULT_POLICY_PATH,
+  exportGatePolicy,
+  type GatePolicyExec,
+  type GatePolicySettings,
+  type GatePolicyVerdict,
+} from "../gate-policy";
+import type { ChangeSetDocument } from "../change-set";
+import type { GateLedgerPort } from "../op/gate";
+import type { PrPolicyReport } from "../pr-loop";
+
+/** `ci.policy` as read at base. */
+export interface PrLoopPolicy {
+  /** Absent when the declaration at base sets none. */
+  settings?: GatePolicySettings;
+  /** The commit it was read at. */
+  base: string;
+  /** The tree of the declaration's directory at base, where the policy directory is read. */
+  tree?: WorkspaceTree;
+  /** A line for the log when no policy runs because the base has no declaration, or could not be read. */
+  note?: string;
+}
+
+/** Whether the working tree's declaration names a `ci.policy`. */
+function checkoutNamesPolicy(cwd: string): boolean {
+  try {
+    return readDeclaration(locateWorkspace(cwd).tree).ci?.policy !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The policy a pull-request job in `cwd` runs, from the declaration at
+ * `base`. Throws when the declaration at base cannot be read and the
+ * working tree's names a policy: running none would let the change waive it.
+ */
+export function prLoopPolicyAt(cwd: string, base: string): PrLoopPolicy {
+  try {
+    const located = locateWorkspace(cwd, base);
+    const settings = readDeclaration(located.tree).ci?.policy;
+    return { base, ...(settings ? { settings, tree: located.tree } : {}) };
+  } catch (err) {
+    const missing = err instanceof WorkspaceReadError && (err.code === "declaration-missing" || err.code === "not-a-git-repository");
+    const why = err instanceof Error ? err.message : String(err);
+    if (checkoutNamesPolicy(cwd)) {
+      if (missing) return { base, note: `ci.policy: the base ${base.slice(0, 12)} has no workspace declaration, so the policy this change declares runs once it merges` };
+      throw new Error(`ci.policy is read from the workspace declaration at ${base.slice(0, 12)}, and it could not be read (${why}), so the policy cannot be run`);
+    }
+    return missing ? { base } : { base, note: `ci.policy: the declaration at ${base.slice(0, 12)} could not be read (${why}); this checkout names no policy, so none runs` };
+  }
+}
+
+/** What the engine reads as `input`. */
+export interface PrPolicyInput {
+  version: 1;
+  stage: "plan" | "apply";
+  /** The gate's op, `pr-<n>`. */
+  op: string;
+  gate: string;
+  env: string;
+  pr: number | null;
+  base: string;
+  head: string;
+  /** The change-set document the gate binds. Its `entries` are every change the plan proposes. */
+  changeSet: ChangeSetDocument;
+}
+
+/** Run the policy over `input`. Undefined when the base sets no policy. */
+export function runPrPolicy(read: PrLoopPolicy, input: PrPolicyInput, exec?: GatePolicyExec): GatePolicyVerdict | undefined {
+  if (!read.settings || !read.tree) return undefined;
+  const engine = read.settings.engine ?? "conftest";
+  const path = read.settings.path ?? DEFAULT_POLICY_PATH;
+  const exported = exportGatePolicy(read.tree, path);
+  if ("error" in exported) return { result: "error", engine, denials: [], rules: [], holds: [], warnings: [], error: exported.error };
+  try {
+    return checkGatePolicy({ settings: read.settings, input, policyDir: exported.dir, cwd: process.cwd(), ...(exec ? { exec } : {}) });
+  } finally {
+    exported.cleanup();
+  }
+}
+
+/** The verdict as the report keeps it. */
+export function prPolicyReport(verdict: GatePolicyVerdict, base: string): PrPolicyReport {
+  return {
+    result: verdict.result,
+    engine: verdict.engine,
+    base,
+    denials: verdict.denials,
+    ...(verdict.rules.length > 0 ? { rules: verdict.rules } : {}),
+    holds: verdict.holds,
+    warnings: verdict.warnings,
+    ...(verdict.error !== undefined ? { error: verdict.error } : {}),
+  };
+}
+
+export interface PrPolicyOverrideInput {
+  port: GateLedgerPort;
+  /** The override's subject: the gate's op. */
+  subject: string;
+  /** The digest the gate binds: the change-set document's. */
+  digest: string;
+  rules: readonly string[];
+  /** The commit the overriders and signers are read at. */
+  base: string;
+  cwd: string;
+  /** Count only sealed overrides, as a sealed gate counts only sealed approvals. */
+  sealed: boolean;
+  /** Record the denial when no override counts and none stands. The plan stage records nothing. */
+  record: boolean;
+  description?: string;
+  now?: string;
+}
+
+/** Where an override of a denial stands. */
+export type PrPolicyOverride =
+  | { status: "overridden"; override: NonNullable<PrPolicyReport["override"]> }
+  | { status: "none"; refusals: string[]; command: string; overriders: string[]; recorded: boolean; moved?: { by: string } };
+
+/**
+ * Decide a denied plan against the override ledger, as an Op waves job
+ * decides a denied run (`settleDenials` in `../op/op-waves-run.ts`).
+ */
+export async function decidePrPolicyOverride(input: PrPolicyOverrideInput): Promise<PrPolicyOverride> {
+  const og = await import("../override-gate");
+  const overriders = og.overridersAt(input.cwd, input.base).principals;
+  const signers = input.sealed ? (await import("../gate-decision")).gateSignersAt(input.cwd, input.base) : undefined;
+  const ledger = await input.port.read(og.OVERRIDE_OP);
+  const applied = ((await input.port.readApplied?.(og.OVERRIDE_OP)) ?? []) as unknown as import("../override-gate").AppliedOverrideRecord[];
+  const now = input.now ?? new Date().toISOString();
+  const verdict = og.decideOverride({
+    ledger,
+    applied,
+    subject: input.subject,
+    planDigest: input.digest,
+    rules: input.rules,
+    overriders,
+    mode: input.sealed ? "sealed" : "ledger",
+    ...(signers ? { signers } : {}),
+    now,
+  });
+  if (verdict.status === "overridden") {
+    const o = verdict.override;
+    return { status: "overridden", override: { by: o.by, at: o.at, reason: o.reason, digest: o.digest } };
+  }
+  let recorded = false;
+  if (input.record && !verdict.standing) {
+    const { version: _v, kind: _k, ...fact } = og.overridePending({
+      subject: input.subject,
+      planDigest: input.digest,
+      rules: input.rules,
+      timestamp: now,
+      expiresAt: new Date(new Date(now).getTime() + 48 * 3600 * 1000).toISOString(),
+      ...(input.description ? { description: input.description } : {}),
+    });
+    await input.port.appendPending(fact);
+    recorded = true;
+  }
+  return {
+    status: "none",
+    refusals: verdict.refusals,
+    command: og.overrideCommand(input.subject, input.rules, input.sealed),
+    overriders,
+    recorded,
+    ...(verdict.status === "moved" ? { moved: { by: verdict.by } } : {}),
+  };
+}
+
+/**
+ * Spend the override the apply runs under: append its applied record before
+ * anything applies. Throws when it could not be written or did not reach the
+ * remote, and the caller applies nothing.
+ */
+export async function spendPrPolicyOverride(port: GateLedgerPort, subject: string, override: NonNullable<PrPolicyReport["override"]>, at: { now?: string; commit?: string } = {}): Promise<void> {
+  const og = await import("../override-gate");
+  if (!port.appendApplied) throw new Error("this gate ledger cannot record an applied override");
+  const record = og.appliedOverride({ subject, digest: override.digest, at: override.at, by: override.by }, { timestamp: at.now ?? new Date().toISOString(), ...(at.commit ? { commit: at.commit } : {}) });
+  const pushed = await port.appendApplied(record as unknown as Parameters<NonNullable<GateLedgerPort["appendApplied"]>>[0]);
+  const { isLifecycleLocalNote } = await import("../lifecycle/local-note");
+  if (!pushed.pushed && !isLifecycleLocalNote(pushed.pushWarning)) {
+    throw new Error(`the applied record did not reach the remote the next run reads: ${pushed.pushWarning ?? "the push did not land"}`);
+  }
+}

package/src/components/pr-run.ts

@@ -110,6 +110,8 @@ export interface PrPlanSetOptions {
   vars?: Record<string, unknown>;
   /** Outputs supplied by the caller (`--seed-outputs`). They win over outputs read here. */
   seededOutputs?: Record<string, Record<string, unknown>>;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /**
    * Where the planning's events go (#4041): a `plan` phase with no
    * component, and in it one `plan` step per component, started as its wave
@@ -384,6 +386,8 @@ export interface PrApplyOptions {
   vars?: Record<string, unknown>;
   /** The set {@link planPrSet} planned and the gate approved, or {@link resumePrSet}'s set. */
   set: PrPlanSet;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   onProgress?: (event: RunProgressEvent) => void;
   /** Where the apply's events go (#4041): the fan-out's run events. */
   onRunEvent?: RunEventSink;
@@ -467,6 +471,7 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
       env: options.env,
       ...(options.vars ? { vars: options.vars } : {}),
       plans,
+      ...(options.targets ? { targets: options.targets } : {}),
       componentOutputs: outputs,
       hold: (name, now) => heldReason(byName.get(name)!, read, now, inChange),
       ...(options.onProgress ? { onProgress: options.onProgress } : {}),
@@ -491,6 +496,7 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
       env: options.env,
       ...(options.vars ? { vars: options.vars } : {}),
       seededOutputs: run.componentOutputs,
+      ...(options.targets ? { targets: options.targets } : {}),
     });
     for (const name of plan.order) roundOf.set(name, { round, set });
     const record = (status: PrRound["status"], approval: PrApproval, message?: string): void => {
@@ -514,7 +520,7 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
 
   const completed = new Set(run.completed);
   const held = new Map((run.held ?? []).map((h) => [h.component, h]));
-  const blocked = new Set(run.blocked.map((b) => b.component));
+  const blocked = new Map(run.blocked.map((b) => [b.component, b.blockedBy]));
   const errorOf = (component: string): string | undefined => {
     const result = [...run.results].reverse().find((r) => r.component === component);
     if (result?.status === "gated") return `stopped at its own gate ${result.gate?.gate ?? ""}`.trim();
@@ -529,7 +535,10 @@ export async function applyPrSet(options: PrApplyOptions): Promise<PrApplyResult
     const h = held.get(m.component);
     if (h) return { ...asPlanned, status: "waiting", held: h.heldBy ? `${h.heldBy} is held: ${h.reason}` : h.reason };
     if (fresh?.status === "plan-failed") return { ...asPlanned, status: "plan-failed", ...(fresh.error ? { error: fresh.error } : {}) };
-    if (blocked.has(m.component)) return { ...asPlanned, status: "blocked" };
+    if (blocked.has(m.component)) {
+      const by = blocked.get(m.component);
+      return { ...asPlanned, status: "blocked", ...(by ? { blockedBy: by } : {}) };
+    }
     const error = errorOf(m.component);
     return { ...asPlanned, status: "failed", ...(error ? { error } : {}) };
   });
@@ -623,6 +632,8 @@ export interface PrResumeOptions {
   env: string;
   vars?: Record<string, unknown>;
   seededOutputs?: Record<string, Record<string, unknown>>;
+  /** The addresses each component narrows to (#4300), by component: its steps' `DeployContext.targets`. */
+  targets?: Readonly<Record<string, readonly string[]>>;
   /** The approved set, from the attempt record. */
   record: PrApplyRecord;
   /** Components an earlier attempt applied. */
@@ -674,6 +685,7 @@ export async function resumePrSet(options: PrResumeOptions): Promise<PrResume> {
     env: options.env,
     ...(options.vars ? { vars: options.vars } : {}),
     seededOutputs: { ...(options.seededOutputs ?? {}), ...options.record.planOutputs },
+    ...(options.targets ? { targets: options.targets } : {}),
   });
   const reasons = fresh.doc.members
     .map((m) => planCoveredBy(options.record.changeSet, fresh.doc, m.member))

package/src/components/wave-plan.ts

@@ -27,11 +27,11 @@
  * `@<component>.publish.*`) resolves.
  */
 
-import { resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
+import { assertTargetsAccepted, resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { componentDeployInputs, type ComponentDeployInputs } from "./deploy-inputs";
 import { computePlanDigest } from "../lifecycle/plan-digest";
-import type { CapabilityRegistry, DeployContext, PlannedOutputs } from "./capability";
+import type { CapabilityPlan, CapabilityRegistry, DeployContext, PlannedOutputs } from "./capability";
 import type { WaveMember } from "../gated-waves";
 import type { ChangeSetPart } from "../change-set";
 
@@ -101,12 +101,13 @@ export async function planWaveComponent(
     const plans: Record<string, unknown> = {};
     const parts: ChangeSetPart[] = [];
     let outputs: PlannedOutputs | undefined;
+    assertTargetsAccepted(component, registry, ctx);
     for (const step of capabilitySteps(component.deploy)) {
       const capability = registry.resolve(step.kind);
       if (!capability.plan) continue;
       const { kind: _kind, ...rest } = step;
       const input = resolveStepInput(rest, {}, componentOutputs);
-      const planned = await capability.plan(planContext(ctx, rest, componentOutputs), input as never);
+      const planned = bindTargets(step.kind, ctx, await capability.plan(planContext(ctx, rest, componentOutputs), input as never));
       const member = { member: planned.member, planDigest: planned.planDigest };
       members.push(member);
       parts.push(planned.changeSet ?? emptyPart(member));
@@ -124,6 +125,7 @@ export async function planWaveComponent(
           component,
           ...(ctx.vars ? { vars: ctx.vars } : {}),
           inputs: read.inputs,
+          ...(ctx.targets ? { targets: ctx.targets } : {}),
         }),
       };
       members.push(member);
@@ -145,6 +147,39 @@ export async function planWaveComponent(
   }
 }
 
+/**
+ * A member's digest with its targets in it (#4300), the way terragucci's
+ * cone plan digest binds a cone: the digest over the plan's own digest and
+ * the sorted targets, so an approval of one narrowing covers no other.
+ */
+export function targetedPlanDigest(planDigest: string, targets: readonly string[]): string {
+  return computePlanDigest("capability-targets", { plan: planDigest, targets: [...new Set(targets)].sort() });
+}
+
+/**
+ * A step's plan made with `ctx.targets` (#4300), its digest bound to them.
+ * The plan must give back the targets it was asked for, which says it planned
+ * those alone; one that gives back others, or none, refuses. Without
+ * `ctx.targets`, the plan as it came.
+ */
+export function bindTargets(kind: string, ctx: DeployContext, planned: CapabilityPlan): CapabilityPlan {
+  const asked = ctx.targets;
+  if (!asked || asked.length === 0) return planned;
+  const want = [...new Set(asked)].sort();
+  const got = [...new Set(planned.targets ?? [])].sort();
+  if (got.length !== want.length || got.some((t, i) => t !== want[i])) {
+    throw new Error(
+      `component "${ctx.component}": ${kind} was asked to plan ${want.join(", ")} but its plan of ${planned.member} ` +
+        (got.length === 0 ? "names no targets" : `names ${got.join(", ")}`),
+    );
+  }
+  const planDigest = targetedPlanDigest(planned.planDigest, want);
+  const changeSet = planned.changeSet
+    ? { ...planned.changeSet, member: { ...planned.changeSet.member, planDigest } }
+    : undefined;
+  return { ...planned, planDigest, targets: want, ...(changeSet ? { changeSet } : {}) };
+}
+
 /** `next` over `prior`, as a later step's outputs win over an earlier one's in a run. */
 function mergePlannedOutputs(prior: PlannedOutputs | undefined, next: PlannedOutputs): PlannedOutputs {
   const known = { ...(prior?.known ?? {}), ...next.known };

package/src/gate-decision-bundle.test.ts

@@ -41,20 +41,21 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/intrinsic.ts",
       "packages/core/src/lifecycle/gate-applied.ts",
       "packages/core/src/lifecycle/gate-ledger-select.ts",
+      "packages/core/src/lifecycle/gate-seal.ts",
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/notify-verify.ts",
       "packages/core/src/notify.ts",
       "packages/core/src/op/gate-point.ts",
+      "packages/core/src/op/gate-quorum.ts",
       "packages/core/src/op/op-waves.ts",
       "packages/core/src/wave-layout.ts",
       "packages/core/src/workspace/class-data.ts",
       "packages/core/src/workspace/identity-gate-rule.ts",
       "packages/core/src/workspace/jsonc.ts",
-      "packages/core/src/workspace/trust/gate-seal.ts",
       "packages/core/src/workspace/trust/trust-files.ts",
     ]);
-    // About 43 KB unminified today, 7 KB of it the pinned classes read as data (#3888).
+    // About 49 KB unminified today: 7 KB of it the pinned classes read as data (#3888), 6 KB the approval rules (#4290).
     const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
-    expect(bytes).toBeLessThan(48 * 1024);
+    expect(bytes).toBeLessThan(54 * 1024);
   });
 });

package/src/gate-decision.ts

@@ -27,6 +27,11 @@
  * counts for nothing, as terragucci's wave gate has it: the caller hands in
  * the lines of `_gates/<op>/applied.jsonl` ({@link parseAppliedGateLines}).
  *
+ * Approval rules (#4290), a quorum as a list of `{ targets, count, roles,
+ * notAuthor }`, are judged with `./op/gate-quorum.ts`, re-exported here:
+ * {@link trustRolesAt} and {@link gateSignersAt} read what
+ * `trustQuorumJudge` judges by, at base.
+ *
  * The module reads the ledger lines and the review it is handed; reading
  * them is the caller's. It imports no TypeScript, esbuild, zod, ajv, lint,
  * fold or codegen module, no package's code, and none of chant's git ledger
@@ -46,7 +51,7 @@ import {
 } from "./lifecycle/gate-ledger-select";
 import { samePlanDigest } from "./lifecycle/plan-digest";
 import { isApprovalSpent, type AppliedGateRecord } from "./lifecycle/gate-applied";
-import { gateSealRefusal, type GateSigners, type SealedGateApproval } from "./workspace/trust/gate-seal";
+import { gateSealRefusal, type GateSigners, type SealedGateApproval } from "./lifecycle/gate-seal";
 import {
   DEFAULT_SIGNERS_PATH,
   TRUST_CONFIG_PATH,
@@ -79,7 +84,7 @@ export {
   type GateSigners,
   type SealedGateApproval,
   type SshSignatureCheck,
-} from "./workspace/trust/gate-seal";
+} from "./lifecycle/gate-seal";
 export {
   DEFAULT_SIGNERS_PATH,
   TRUST_CONFIG_PATH,
@@ -105,6 +110,28 @@ export {
   type AppliedGateRecord,
 } from "./lifecycle/gate-applied";
 export type { MergedReview } from "./op/gate-review";
+export {
+  quorumNeed,
+  quorumProblems,
+  quorumRuleLine,
+  quorumRuleProgress,
+  quorumRules,
+  quorumRulesFor,
+  quorumWaiting,
+  rolesOf,
+  ruleNeedsProof,
+  samePrincipal,
+  targetGlobMatch,
+  trustQuorumJudge,
+  UNPROVEN_JUDGE,
+  type GateQuorumJudge,
+  type GateQuorumRule,
+  type GateQuorumRuleProgress,
+  type GateQuorumSpec,
+  type QuorumApprover,
+  type QuorumJudgement,
+  type TrustQuorumInput,
+} from "./op/gate-quorum";
 
 // ── reading at base ──────────────────────────────────────────────────────
 
@@ -172,6 +199,16 @@ export function gateSignersAt(repo: string, base: string): GateSigners {
   return trustAt(repo, base).signers;
 }
 
+/**
+ * The role grants of `.chant/trust.json` at `base` (#4290): role name to the
+ * principals that hold it, as chant reads them. A missing file gives none,
+ * and so does one that is not valid, which turns chant's trust off.
+ * {@link trustQuorumJudge} takes them with {@link gateSignersAt}'s signers.
+ */
+export function trustRolesAt(repo: string, base: string): Record<string, string[]> {
+  return trustAt(repo, base).roles;
+}
+
 /** A gate the declaration at base names under `identity.gates`, and the principal class its signer must be in, if any. */
 export interface IdentityGate {
   gate: string;

package/src/gate-policy-bundle.test.ts

@@ -0,0 +1,28 @@
+/**
+ * The gate policy bundles alone (#4294), as the override gate does: a
+ * product runs the engine and reads its answer from one bundled file with
+ * no TypeScript toolchain. This bundles `@intentius/chant/gate-policy` and
+ * reads esbuild's list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+describe("the gate-policy bundle", () => {
+  test("holds the policy module and nothing else", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "gate-policy.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    expect(Object.keys(result.metafile.inputs).map((i) => i.replace(/^.*?packages\//, "packages/"))).toEqual(["packages/core/src/gate-policy.ts"]);
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(16 * 1024);
+  });
+});

package/src/gate-policy.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  assertGatePolicySettings,
+  checkGatePolicy,
+  conftestFindings,
+  exportGatePolicy,
+  gatePolicyArgv,
+  opaFindings,
+  type GatePolicyExec,
+  type GatePolicyTree,
+} from "./gate-policy";
+
+/** conftest's JSON for one input: a deny with its query, an older deny without one, and a warning. */
+const CONFTEST_DENY = JSON.stringify([
+  {
+    filename: "input.json",
+    namespace: "main",
+    successes: 2,
+    failures: [
+      { msg: "bucket logs is public", metadata: { query: "data.main.deny_public_bucket" } },
+      { msg: { msg: "no owner tag" } },
+    ],
+    warnings: [{ msg: "the plan deletes 3 resources" }],
+  },
+]);
+
+const opa = (value: unknown): string => JSON.stringify({ result: [{ expressions: [{ value, text: "data.main", location: { row: 1, col: 1 } }] }] });
+
+describe("reading the engine's answer (#4294)", () => {
+  test("conftest: failures deny by their query, warnings are advice", () => {
+    expect(conftestFindings(CONFTEST_DENY)).toEqual({
+      denials: [
+        { rule: "main.deny_public_bucket", message: "bucket logs is public" },
+        { rule: "main.deny", message: "no owner tag" },
+      ],
+      holds: [],
+      warnings: ["the plan deletes 3 resources"],
+    });
+    expect(conftestFindings(JSON.stringify([{ filename: "input.json", namespace: "main", successes: 1 }]))).toEqual({ denials: [], holds: [], warnings: [] });
+    expect(conftestFindings("not json")).toBeUndefined();
+    expect(conftestFindings(JSON.stringify({ result: [] }))).toBeUndefined();
+  });
+
+  test("opa: deny, violation, hold and warn rules by name; a child package one level down; allow_unattended is no rule", () => {
+    const found = opaFindings(
+      opa({
+        deny: ["public bucket"],
+        violation_size: "too many deletes",
+        hold_iam: ["an IAM role changes"],
+        hold: true,
+        warn: ["consider tags"],
+        allow_unattended: true,
+        allow_unattended_docs: ["docs only"],
+        other: 3,
+        aws: { deny_region: ["us-west-1 is not allowed"] },
+      }),
+    );
+    expect(found).toEqual({
+      denials: [
+        { rule: "main.aws.deny_region", message: "us-west-1 is not allowed" },
+        { rule: "main.deny", message: "public bucket" },
+        { rule: "main.violation_size", message: "too many deletes" },
+      ],
+      holds: [
+        { rule: "main.hold", message: "hold" },
+        { rule: "main.hold_iam", message: "an IAM role changes" },
+      ],
+      warnings: ["consider tags"],
+    });
+  });
+
+  test("opa: an undefined query matches nothing, an array is a deny set, errors and other shapes are no answer", () => {
+    expect(opaFindings(JSON.stringify({}))).toEqual({ denials: [], holds: [], warnings: [] });
+    expect(opaFindings(opa(["a", { msg: "b" }]), "policy.deny")).toEqual({ denials: [{ rule: "policy.deny", message: "a" }, { rule: "policy.deny", message: "b" }], holds: [], warnings: [] });
+    expect(opaFindings(JSON.stringify({ errors: [{ message: "rego_parse_error" }] }))).toBeUndefined();
+    expect(opaFindings(opa(7))).toBeUndefined();
+    expect(opaFindings("{")).toBeUndefined();
+  });
+});
+
+describe("running the engine (#4294)", () => {
+  const fake = (out: { status: number | null; stdout?: string; stderr?: string }, seen: string[][] = []): GatePolicyExec => (argv) => {
+    seen.push(argv);
+    return { status: out.status, stdout: out.stdout ?? "", stderr: out.stderr ?? "" };
+  };
+
+  test("the engines' own argv, and a command's placeholders filled", () => {
+    expect(gatePolicyArgv({}, { policy: "/p", input: "/i.json" })).toEqual(["conftest", "test", "--no-color", "--output", "json", "--policy", "/p", "--all-namespaces", "/i.json"]);
+    expect(gatePolicyArgv({ engine: "conftest", namespace: "infra" }, { policy: "/p", input: "/i.json" })).toContain("--namespace");
+    expect(gatePolicyArgv({ engine: "opa" }, { policy: "/p", input: "/i.json" })).toEqual(["opa", "eval", "--format", "json", "--data", "/p", "--input", "/i.json", "data.main"]);
+    expect(gatePolicyArgv({ engine: "opa", command: ["./bin/check", "--rules={policy}", "{input}"] }, { policy: "/p", input: "/i.json" })).toEqual(["./bin/check", "--rules=/p", "/i.json"]);
+  });
+
+  test("the input is written to the file the engine reads, and a denial is a verdict with its sorted rules", () => {
+    let input: unknown;
+    const exec: GatePolicyExec = (argv) => {
+      input = JSON.parse(readFileSync(argv[argv.length - 1]!, "utf-8"));
+      return { status: 1, stdout: CONFTEST_DENY, stderr: "" };
+    };
+    const verdict = checkGatePolicy({ settings: {}, input: { changeSet: { entries: [] } }, policyDir: "/p", exec });
+    expect(input).toEqual({ changeSet: { entries: [] } });
+    expect(verdict).toMatchObject({ result: "denied", engine: "conftest", rules: ["main.deny", "main.deny_public_bucket"], warnings: ["the plan deletes 3 resources"] });
+  });
+
+  test("a hold with no denial is held; nothing is passed", () => {
+    expect(checkGatePolicy({ settings: { engine: "opa" }, input: {}, policyDir: "/p", exec: fake({ status: 0, stdout: opa({ hold_iam: ["iam"] }) }) })).toMatchObject({ result: "held", holds: [{ rule: "main.hold_iam" }] });
+    expect(checkGatePolicy({ settings: { engine: "opa" }, input: {}, policyDir: "/p", exec: fake({ status: 0, stdout: opa({ deny: [], warn: [] }) }) })).toMatchObject({ result: "passed", denials: [], holds: [] });
+    expect(checkGatePolicy({ settings: { engine: "opa" }, input: {}, policyDir: "/p", exec: fake({ status: 0, stdout: opa({ deny: ["x"], hold: true }) }) }).result).toBe("denied");
+  });
+
+  test("an engine that does not start, prints no result or fails without a denial is an error", () => {
+    expect(checkGatePolicy({ settings: {}, input: {}, policyDir: "/p", exec: fake({ status: null, stderr: "spawn conftest ENOENT" }) })).toMatchObject({ result: "error", error: expect.stringContaining("did not run") });
+    expect(checkGatePolicy({ settings: {}, input: {}, policyDir: "/p", exec: fake({ status: 2, stdout: "Error: rego_parse_error" }) })).toMatchObject({ result: "error", error: expect.stringContaining("gave no conftest result") });
+    expect(checkGatePolicy({ settings: {}, input: {}, policyDir: "/p", exec: fake({ status: 2, stdout: "[]", stderr: "could not load policy" }) })).toMatchObject({ result: "error", error: expect.stringContaining("exited 2") });
+  });
+});
+
+describe("the policy at base (#4294)", () => {
+  const files: Record<string, string> = { "policy/main.rego": "package main\n", "policy/lib/util.rego": "package lib\n", "src/app.ts": "" };
+  const tree: GatePolicyTree = {
+    stat: (p) => (files[p] !== undefined ? "file" : Object.keys(files).some((f) => f.startsWith(`${p}/`)) ? "dir" : undefined),
+    list: (p) => {
+      const names = new Map<string, "file" | "dir">();
+      for (const f of Object.keys(files).filter((f) => f.startsWith(`${p}/`))) {
+        const rest = f.slice(p.length + 1).split("/");
+        names.set(rest[0]!, rest.length > 1 ? "dir" : "file");
+      }
+      return names.size ? [...names].map(([name, type]) => ({ name, type })) : undefined;
+    },
+    read: (p) => files[p]!,
+  };
+
+  test("the directory is copied out of the tree, and removed again", () => {
+    const out = exportGatePolicy(tree, "./policy/");
+    if ("error" in out) throw new Error(out.error);
+    expect(readFileSync(join(out.dir, "main.rego"), "utf-8")).toBe("package main\n");
+    expect(readFileSync(join(out.dir, "lib", "util.rego"), "utf-8")).toBe("package lib\n");
+    expect(existsSync(join(out.dir, "app.ts"))).toBe(false);
+    out.cleanup();
+    expect(existsSync(out.dir)).toBe(false);
+  });
+
+  test("a directory the base does not have is an error", () => {
+    expect(exportGatePolicy(tree, "rules")).toEqual({ error: "the policy directory rules does not exist at base" });
+  });
+});
+
+describe("ci.policy settings (#4294)", () => {
+  test("the four settings are read, and an unattended outcome is refused", () => {
+    expect(() => assertGatePolicySettings("ci.policy", { engine: "opa", path: "policy", namespace: "main", command: ["opa", "eval", "{input}"] })).not.toThrow();
+    expect(() => assertGatePolicySettings("ci.policy", {})).not.toThrow();
+    expect(() => assertGatePolicySettings("ci.policy", { engine: "sentinel" })).toThrow(/conftest or opa/);
+    expect(() => assertGatePolicySettings("ci.policy", { path: "../elsewhere" })).toThrow(/inside the workspace/);
+    expect(() => assertGatePolicySettings("ci.policy", { command: ["check"] })).toThrow(/\{input\}/);
+    expect(() => assertGatePolicySettings("ci.policy", { outcomes: ["deny", "allow_unattended"] })).toThrow(/no unattended outcome/);
+    expect(() => assertGatePolicySettings("ci.policy", { allow_unattended: true })).toThrow(/no unattended outcome/);
+    expect(() => assertGatePolicySettings("ci.policy", { rules: [] })).toThrow(/not a setting/);
+    expect(() => assertGatePolicySettings("ci.policy", [])).toThrow(/must be/);
+  });
+});