@intentius/chant 0.106.4 → 0.107.1

package/src/op/gate-plan-context.ts

@@ -0,0 +1,229 @@
+/**
+ * The plan summary a gate's policy reads (#3182).
+ *
+ * A gate's Cedar request used to carry `planDigest` and whatever the Op put
+ * in `approval.context` by hand, so a rule like "deny an agent a plan that
+ * deletes a database" needed every Op to compute and pass the plan's deletes
+ * itself. A gate whose `plan` names the step that planned the change now gets
+ * `context.plan` from that step's change-set document (#3181), with no code in
+ * the Op:
+ *
+ * - `terraformPlan` returns `changeSet`, one member's part;
+ * - `lifecyclePlanChangeSet` and `readChangeSetPart` return `part`;
+ * - `composeChangeSet` returns `document`, the whole run's change set.
+ *
+ * {@link gatePlanSummary} is the summary, shaped for Cedar: flat counts
+ * (`no-op` is not a Cedar identifier), sets of names, and no nulls or floats.
+ * The cedar lexicon's `GATE_CEDAR_SCHEMA` declares it as `Chant::PlanSummary`,
+ * and its policy pack is written against it.
+ *
+ * The summary rides on the pending fact with the rest of the resolved context,
+ * so `chant approve` evaluates the policy against the plan the run produced.
+ * It comes from the same step result as the digest the gate binds, and a new
+ * plan is a new digest, so an approval never stands on a summary of another
+ * plan.
+ *
+ * Imports types only, so the module bundles without TypeScript (#3421).
+ */
+
+import type { ChangeSetEntry, ChangeSetMember, ChangeSetPart, ChangeSetDocument } from "../change-set";
+
+/** The `approval.context` key the summary lands under. An authored context may not use it. */
+export const GATE_PLAN_CONTEXT_KEY = "plan";
+
+/** How many addresses each address set carries before it is cut and {@link GatePlanSummary.truncated} is set. */
+export const GATE_PLAN_ADDRESS_LIMIT = 500;
+
+/** The attributes that hold a resource's tags or labels, read in this order. */
+const TAG_ATTRIBUTES = ["tags", "tags_all", "labels"] as const;
+
+/**
+ * `context.plan` on a gate's Cedar request. Counts are over entries; type,
+ * address, region, scope and member sets are over the changes only (create,
+ * update, replace and delete), so a resource the plan only reads or leaves
+ * alone does not count as touched.
+ */
+export interface GatePlanSummary {
+  /** Every member the change set names. */
+  members: string[];
+  /** Members with at least one change. */
+  membersChanged: string[];
+  /** Members that failed to plan. A plan with a failed member says nothing about it. */
+  failedMembers: string[];
+  /** How many members failed to plan. */
+  failed: number;
+  /** Resources a planner could not read. */
+  holes: number;
+  entries: number;
+  /** creates + updates + replaces + deletes. */
+  changes: number;
+  creates: number;
+  updates: number;
+  replaces: number;
+  deletes: number;
+  reads: number;
+  noOps: number;
+  forgets: number;
+  /** Types with a change. */
+  types: string[];
+  createdTypes: string[];
+  updatedTypes: string[];
+  replacedTypes: string[];
+  deletedTypes: string[];
+  /** Addresses deleted, as each planner writes them. */
+  deleted: string[];
+  /** Addresses replaced. */
+  replaced: string[];
+  /** Regions a change lands in, where the planner reports one. */
+  regions: string[];
+  /** Estates, environments or orgs a change lands in. */
+  scopes: string[];
+  lexicons: string[];
+  /** Creates that carry tags or labels. */
+  taggedCreates: number;
+  /** Creates that carry no tags or labels attribute at all: a type with no tags, or tags left unset. */
+  untaggedCreates: number;
+  /**
+   * The tag keys every tagged create carries: the intersection over
+   * {@link taggedCreates}. A required-tags rule checks this contains its keys.
+   */
+  createTagKeys: string[];
+  /** At least one change, and every change an update of tags or labels only. */
+  tagOnly: boolean;
+  /** An address set was cut at {@link GATE_PLAN_ADDRESS_LIMIT}. The counts are whole. */
+  truncated: boolean;
+}
+
+type Json = Record<string, unknown>;
+const isObject = (v: unknown): v is Json => v !== null && typeof v === "object" && !Array.isArray(v);
+
+function isMember(v: unknown): v is ChangeSetMember {
+  return isObject(v) && typeof v.member === "string";
+}
+
+function isPart(v: unknown): v is ChangeSetPart {
+  return isObject(v) && isMember(v.member) && Array.isArray(v.entries);
+}
+
+function isDocument(v: unknown): v is ChangeSetDocument {
+  return isObject(v) && Array.isArray(v.members) && v.members.every(isMember) && Array.isArray(v.entries);
+}
+
+/** The members and entries a step result carries, when it carries a change set. */
+export function changeSetOfResult(result: unknown): { members: ChangeSetMember[]; entries: ChangeSetEntry[] } | undefined {
+  if (isDocument(result)) return result;
+  if (isPart(result)) return { members: [result.member], entries: result.entries };
+  if (!isObject(result)) return undefined;
+  if (isDocument(result.document)) return result.document;
+  for (const key of ["changeSet", "part"] as const) {
+    const part = result[key];
+    if (isPart(part)) return { members: [part.member], entries: part.entries };
+  }
+  return undefined;
+}
+
+const CHANGES = new Set(["create", "update", "replace", "delete"]);
+
+function tagKeysOf(entry: ChangeSetEntry): string[] | undefined {
+  let keys: Set<string> | undefined;
+  for (const name of TAG_ATTRIBUTES) {
+    const attr = entry.attributes.find((a) => a.path === name);
+    if (!attr) continue;
+    keys ??= new Set();
+    if (isObject(attr.after)) for (const k of Object.keys(attr.after)) keys.add(k);
+  }
+  return keys ? [...keys] : undefined;
+}
+
+function isTagOnlyUpdate(entry: ChangeSetEntry): boolean {
+  return (
+    entry.action === "update" &&
+    entry.attributes.length > 0 &&
+    entry.attributes.every((a) => (TAG_ATTRIBUTES as readonly string[]).includes(a.path))
+  );
+}
+
+const sorted = (s: Set<string>): string[] => [...s].sort();
+
+/** The plan summary of a change set's members and entries. */
+export function gatePlanSummary(changeSet: { members: ReadonlyArray<ChangeSetMember>; entries: ReadonlyArray<ChangeSetEntry> }): GatePlanSummary {
+  const count = { create: 0, update: 0, replace: 0, delete: 0, read: 0, "no-op": 0, forget: 0 };
+  const typesBy = { create: new Set<string>(), update: new Set<string>(), replace: new Set<string>(), delete: new Set<string>() };
+  const types = new Set<string>();
+  const membersChanged = new Set<string>();
+  const regions = new Set<string>();
+  const scopes = new Set<string>();
+  const lexicons = new Set<string>();
+  const deleted: string[] = [];
+  const replaced: string[] = [];
+  let taggedCreates = 0;
+  let untaggedCreates = 0;
+  let createTagKeys: Set<string> | undefined;
+  let tagOnly = true;
+
+  for (const e of changeSet.entries) {
+    if (e.action in count) count[e.action]++;
+    if (!CHANGES.has(e.action)) continue;
+    const action = e.action as keyof typeof typesBy;
+    typesBy[action].add(e.type);
+    types.add(e.type);
+    membersChanged.add(e.member);
+    lexicons.add(e.lexicon);
+    if (e.region) regions.add(e.region);
+    if (e.scope) scopes.add(e.scope);
+    if (action === "delete") deleted.push(e.address);
+    if (action === "replace") replaced.push(e.address);
+    if (!isTagOnlyUpdate(e)) tagOnly = false;
+    if (action === "create") {
+      const keys = tagKeysOf(e);
+      if (keys === undefined) {
+        untaggedCreates++;
+      } else {
+        taggedCreates++;
+        createTagKeys = createTagKeys === undefined ? new Set(keys) : new Set(keys.filter((k) => createTagKeys!.has(k)));
+      }
+    }
+  }
+
+  const failedMembers = new Set(changeSet.members.filter((m) => m.status === "failed").map((m) => m.member));
+  const changes = count.create + count.update + count.replace + count.delete;
+  const cap = (list: string[]) => [...new Set(list)].sort().slice(0, GATE_PLAN_ADDRESS_LIMIT);
+  const truncated = new Set(deleted).size > GATE_PLAN_ADDRESS_LIMIT || new Set(replaced).size > GATE_PLAN_ADDRESS_LIMIT;
+  return {
+    members: sorted(new Set(changeSet.members.map((m) => m.member))),
+    membersChanged: sorted(membersChanged),
+    failedMembers: sorted(failedMembers),
+    failed: failedMembers.size,
+    holes: changeSet.members.reduce((n, m) => n + (Array.isArray(m.holes) ? m.holes.length : 0), 0),
+    entries: changeSet.entries.length,
+    changes,
+    creates: count.create,
+    updates: count.update,
+    replaces: count.replace,
+    deletes: count.delete,
+    reads: count.read,
+    noOps: count["no-op"],
+    forgets: count.forget,
+    types: sorted(types),
+    createdTypes: sorted(typesBy.create),
+    updatedTypes: sorted(typesBy.update),
+    replacedTypes: sorted(typesBy.replace),
+    deletedTypes: sorted(typesBy.delete),
+    deleted: cap(deleted),
+    replaced: cap(replaced),
+    regions: sorted(regions),
+    scopes: sorted(scopes),
+    lexicons: sorted(lexicons),
+    taggedCreates,
+    untaggedCreates,
+    createTagKeys: createTagKeys ? sorted(createTagKeys) : [],
+    tagOnly: changes > 0 && tagOnly,
+    truncated,
+  };
+}
+
+/** The summary of a step result, when the result carries a change set. */
+export function gatePlanSummaryOfResult(result: unknown): GatePlanSummary | undefined {
+  const changeSet = changeSetOfResult(result);
+  return changeSet ? gatePlanSummary(changeSet) : undefined;
+}

package/src/op/gate-point-run.ts

@@ -0,0 +1,207 @@
+/**
+ * Reaching a gate that asks a declared decision point (#3170). The shape of
+ * the declaration is in `./gate-point.ts`.
+ *
+ * The run asks the point with the gate's own `gate.*` inputs (those the point
+ * declares) and the authored ones, through the `decide` activity's path
+ * (`./activities/decide.ts`), so the chain, the model's threshold, the reuse
+ * of an answer the same inputs already have and the escalation to people are
+ * the decide activity's. Then:
+ *
+ * - The question is open (escalated to people, or a model's proposal waiting
+ *   for a person): the run records a pending fact on the gate ledger that
+ *   cites the question, as a plain gate records one, and ends `waiting` on
+ *   the question. A person answers it with `chant workspace points answer
+ *   <id>` (or through hud), and the next run, or the local operator's next
+ *   round, asks again and finds the answer.
+ * - It is answered with an answer the gate passes on (`pass`, default yes):
+ *   the run appends a resolution to the gate ledger that cites the answer
+ *   record, once per answer and plan, and walks through.
+ * - It is answered otherwise: the gate step fails, naming the record. `points
+ *   retract` takes the answer back and asks people again.
+ *
+ * `chant approve` does not pass such a gate: only the point's answer does.
+ * The answer record names the gate in its `constrains` (`gate:<op>/<gate>`)
+ * and, when the point declares them, in its `gate.*` inputs.
+ */
+
+import { isPendingGateExpired, latestPendingGate, DEFAULT_GATE_EXPIRY, resolveApprovalUrl, type GateAnswerRef, type GateResolutionRecord, type PendingGateRecord } from "../lifecycle/gate-ledger";
+import { samePlanDigest } from "../lifecycle/plan-digest";
+import { parseDuration } from "./duration";
+import type { GateLedgerPort } from "./gate";
+import { DEFAULT_GATE_POINT_PASS, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts } from "./gate-point";
+import { isPointWait, type WaitingPoint } from "./steward-points";
+
+/** The question a gate's point was asked, as the gate reads it. */
+export interface GatePointQuestion {
+  /** The answer record's id: what `points answer` takes. */
+  id: string;
+  point: string;
+  /** The record, from the repository root. */
+  path: string;
+  state: "escalated" | "proposed" | "answered";
+  /** The answer, or null while the question is open. */
+  answer: string | boolean | null;
+  /** The decider that gave the recorded state: table, model or quorum. */
+  decider: string;
+  answeredBy: string[];
+  subject: string | null;
+  /** The steward whose turn asked it, or null. */
+  steward: string | null;
+}
+
+/** What a gate asks its point with. */
+export interface GatePointRequest {
+  point: string;
+  /** The authored inputs, references resolved. */
+  inputs: Record<string, unknown>;
+  facts: GatePointFacts;
+  /** What the answer record's `constrains` names: {@link gateSubject}. */
+  subject: string;
+}
+
+/** How a gate asks its point. A test passes a stub; {@link workspaceGatePointAsker} is the real one. */
+export interface GatePointAsker {
+  ask(request: GatePointRequest): Promise<GatePointQuestion>;
+}
+
+/**
+ * The real asker: the workspace that holds `cwd`. It reads the point's
+ * declared inputs from `points`, adds the `gate.*` ones the point declares,
+ * and asks through the decide activity. A point with no model decider is
+ * asked with no backends, so the run needs no `decide.backends`.
+ */
+export function workspaceGatePointAsker(cwd: string): GatePointAsker {
+  return {
+    async ask(request) {
+      const { workspacePoints } = await import("../workspace/points-cli");
+      const doc = await workspacePoints({ cwd });
+      if ("error" in doc) throw new Error(`decision point ${request.point}: ${doc.error.code}: ${doc.error.message}`);
+      const point = doc.points.find((p) => p.name === request.point);
+      if (!point) {
+        const bad = doc.sources.find((s) => s.reason);
+        throw new Error(`gate "${request.facts.name}" asks decision point ${request.point}, and no points file declares it${bad ? ` (${bad.kind}: ${bad.reason!.message})` : ""}`);
+      }
+      const inputs = gatePointInputs(request.point, point.inputs.map((i) => i.name), request.facts, request.inputs);
+      const { runDecide } = await import("./activities/decide");
+      const asksModel = point.deciders.some((d) => d.kind === "model");
+      try {
+        const r = await runDecide({ point: request.point, inputs, subject: request.subject, cwd, ...(asksModel ? {} : { backends: {} }) });
+        return { id: r.id, point: request.point, path: r.path, state: r.state, answer: r.answer, decider: r.decider, answeredBy: r.answeredBy, subject: request.subject, steward: null };
+      } catch (err) {
+        if (!isPointWait(err)) throw err;
+        const q = err.question;
+        return { id: q.id, point: q.point, path: q.path, state: q.state, answer: null, decider: "quorum", answeredBy: [], subject: q.subject, steward: q.steward };
+      }
+    },
+  };
+}
+
+/** What the run needs to decide a gate that asks a point. */
+export interface PointGateInput {
+  op: string;
+  gate: string;
+  point: GatePoint;
+  /** The authored inputs, references resolved. */
+  inputs?: Record<string, unknown>;
+  description?: string;
+  timeout?: string;
+  runId?: string;
+  planDigest?: string;
+  /** The environment the run was started for: the `gate.env` input. Op gate facts on the ledger record none. */
+  env?: string;
+  now?: string;
+}
+
+/** What reaching a gate that asks a point decided. */
+export type PointGateCheck =
+  | {
+      satisfied: true;
+      /** The resolution that cites the answer: this run's, or one an earlier run wrote for the same answer and plan. */
+      resolution: GateResolutionRecord;
+      answer: GateAnswerRef;
+      /** Whether this run appended the resolution. */
+      recorded: boolean;
+      pushed?: boolean;
+      pushWarning?: string;
+    }
+  | {
+      satisfied: false;
+      /** The question is answered, with an answer the gate does not pass on. */
+      refused: string;
+      answer: GateAnswerRef;
+    }
+  | {
+      satisfied: false;
+      /** The open question the run waits on. */
+      waiting: WaitingPoint;
+      /** The pending fact that cites it. */
+      pending: PendingGateRecord;
+      recorded: boolean;
+      pushed?: boolean;
+      pushWarning?: string;
+    };
+
+/** Who a resolution written for an answer is by: the people who answered, or the decider that did. */
+function resolvedByOf(q: GatePointQuestion): string {
+  return q.answeredBy.length > 0 ? q.answeredBy.join(", ") : q.decider;
+}
+
+/** Decide a gate that asks a point: ask it, then record the pending fact or the resolution that cites the answer. */
+export async function evaluatePointGate(port: GateLedgerPort, asker: GatePointAsker, input: PointGateInput): Promise<PointGateCheck> {
+  const now = input.now ?? new Date().toISOString();
+  const facts: GatePointFacts = { component: input.op, name: input.gate, env: input.env ?? null, planDigest: input.planDigest ?? null };
+  const q = await asker.ask({ point: input.point.name, inputs: input.inputs ?? {}, facts, subject: gateSubject(input.op, input.gate, input.env) });
+  const ref: GateAnswerRef = { point: q.point, id: q.id, path: q.path };
+
+  if (q.state === "answered" && q.answer !== null) {
+    const answer: GateAnswerRef = { ...ref, answer: q.answer, decider: q.decider, ...(q.answeredBy.length > 0 ? { answeredBy: q.answeredBy } : {}) };
+    const pass = input.point.pass ?? DEFAULT_GATE_POINT_PASS;
+    if (!pass.includes(q.answer)) {
+      return {
+        satisfied: false,
+        answer,
+        refused:
+          `decision point ${q.point} answered ${JSON.stringify(q.answer)} (${q.id}, by ${resolvedByOf(q)}), and gate "${input.gate}" passes only on ${pass.map((a) => JSON.stringify(a)).join(" or ")}. ` +
+          `To ask again, take the answer back: chant workspace points retract ${q.id} --by <name>`,
+      };
+    }
+    const ledger = await port.read(input.op);
+    const standing = ledger.resolutions.find(
+      (r) => r.gate === input.gate && r.answer?.id === q.id && r.environment === undefined && samePlanDigest(r.planDigest, input.planDigest),
+    );
+    if (standing) return { satisfied: true, resolution: standing, answer, recorded: false };
+    if (!port.appendResolution) throw new Error(`gate "${input.gate}" asks decision point ${q.point}, and this gate ledger cannot record the resolution that cites its answer`);
+    const { record, pushed, pushWarning } = await port.appendResolution({
+      op: input.op,
+      gate: input.gate,
+      resolvedBy: resolvedByOf(q),
+      timestamp: now,
+      note: `answered through decision point ${q.point} (${q.id})`,
+      ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+      approver: { kind: q.decider === "quorum" || q.answeredBy.length > 0 ? "human" : "agent" },
+      answer,
+    });
+    return { satisfied: true, resolution: record, answer, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
+  }
+
+  const waiting: WaitingPoint = { id: q.id, point: q.point, state: q.state === "proposed" ? "proposed" : "escalated", path: q.path, subject: q.subject, steward: q.steward };
+  const ledger = await port.read(input.op);
+  const standing = latestPendingGate(ledger.pending.filter((p) => p.environment === undefined), input.gate);
+  if (standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) && standing.answer?.id === q.id) {
+    return { satisfied: false, waiting, pending: standing, recorded: false };
+  }
+  const url = resolveApprovalUrl();
+  const { record, pushed, pushWarning } = await port.appendPending({
+    op: input.op,
+    gate: input.gate,
+    timestamp: now,
+    expiresAt: new Date(new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY)).toISOString(),
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(url ? { url } : {}),
+    ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    answer: ref,
+  });
+  return { satisfied: false, waiting, pending: record, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
+}

package/src/op/gate-point.e2e.test.ts

@@ -0,0 +1,166 @@
+/**
+ * #3170's Done when, end to end: an infra apply Op's gate (`ApplyOp` with
+ * `gate.point`) is answered through `chant workspace points answer`, the run
+ * proceeds on that answer, and the answer record and the gate ledger entry
+ * reference each other.
+ *
+ * The workspace is real (a git repository with the reference workspace's
+ * answer kind and a points file), the point is asked through the decide
+ * activity's path, and the answer goes through the command's own handler,
+ * `runWorkspacePoints`. The gate ledger is the in-memory port, and the build,
+ * plan and apply activities are stubs: the plan's digest is what the gate
+ * binds.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { cleanScratch, workspace } from "../workspace/__fixtures__/decide-workspace";
+import { runWorkspacePoints } from "../workspace/points-cli";
+import { workspacePoints } from "../workspace/points-cli";
+import type { CommandContext } from "../cli/registry";
+import { ApplyOp } from "./composites/apply-op";
+import { memoryGateLedgerPort } from "./gate";
+import { runOpLocally } from "./local-executor";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+
+const PLAN_A = `jcs1-sha256:${"1".repeat(64)}`;
+const PLAN_B = `jcs1-sha256:${"2".repeat(64)}`;
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+let root: string;
+let plan = PLAN_A;
+const applied: string[] = [];
+const activities = new Map<string, ActivityFn>([
+  ["chantBuild", async () => ({ ok: true })],
+  ["lifecycleDiff", async () => ({ planDigest: plan, drifted: true })],
+  ["nativeApply", async () => {
+    applied.push(plan);
+    return { ok: true };
+  }],
+]);
+
+const config = (): OpConfig =>
+  (ApplyOp({ name: "prod-apply", env: "prod", target: "kubectl", gate: { gate: "approve-apply", point: "prod-apply" } }).op as unknown as { props: OpConfig }).props;
+
+/** `chant workspace points answer <id> --answer <value> --by <name>`, through the command's handler, in the workspace. Returns the document it prints. */
+async function pointsAnswer(id: string, answer: string, by: string): Promise<Record<string, unknown>> {
+  const printed: string[] = [];
+  const log = vi.spyOn(console, "log").mockImplementation((line: unknown) => {
+    printed.push(String(line));
+  });
+  const was = process.cwd();
+  process.chdir(root);
+  try {
+    const ctx = { args: { extraPositional: "answer", extraPositional2: id, answer, bys: [by] }, plugins: [], serializers: [] } as unknown as CommandContext;
+    const code = await runWorkspacePoints(ctx);
+    expect(code).toBe(0);
+  } finally {
+    process.chdir(was);
+    log.mockRestore();
+  }
+  return JSON.parse(printed.join("\n")) as Record<string, unknown>;
+}
+
+beforeAll(() => {
+  root = workspace(POINTS);
+});
+
+afterAll(cleanScratch);
+
+describe("an infra apply Op's gate answered through chant workspace points answer (#3170)", () => {
+  test("the run waits on the point, proceeds on its answer, and the answer record and the ledger entry cite each other", async () => {
+    const port = memoryGateLedgerPort();
+    const op = config();
+
+    // 1. The run reaches the gate: the point is asked, the question is open
+    //    for people, the run ends waiting on it, and nothing is applied.
+    const first = await runOpLocally(op, activities, {}, undefined, { gates: port, cwd: root, now: "2026-10-06T10:00:00.000Z" });
+    expect(first.status).toBe("waiting");
+    expect(applied).toEqual([]);
+    const question = first.point!;
+    expect(question).toMatchObject({ point: "prod-apply", state: "escalated", subject: "gate:prod-apply/approve-apply" });
+
+    // The pending fact on the gate ledger names the question.
+    expect(port.appended).toHaveLength(1);
+    expect(port.appended[0]).toMatchObject({ op: "prod-apply", gate: "approve-apply", planDigest: PLAN_A, answer: { point: "prod-apply", id: question.id, path: question.path } });
+
+    // The question is open in the workspace, asked with the gate's facts.
+    const open = await workspacePoints({ cwd: root, open: true });
+    if ("error" in open) throw new Error(open.error.message);
+    expect(open.questions.find((q) => q.id === question.id)).toMatchObject({
+      state: "escalated",
+      subject: "gate:prod-apply/approve-apply",
+      inputs: { "gate.component": "prod-apply", "gate.planDigest": PLAN_A },
+    });
+
+    // 2. A person answers it through the command.
+    const doc = await pointsAnswer(question.id, "yes", "alice");
+    expect(doc).toMatchObject({ verb: "answer", id: question.id, written: true, question: { state: "answered", answer: true, answeredBy: ["alice"] } });
+
+    // 3. The next run proceeds on the answer and applies the plan.
+    const second = await runOpLocally(op, activities, {}, undefined, { gates: port, cwd: root, now: "2026-10-06T10:05:00.000Z" });
+    expect(second.status).toBe("ok");
+    expect(applied).toEqual([PLAN_A]);
+    const gateStep = second.records.find((r) => r.fn === "gate:approve-apply");
+    expect(gateStep?.approval).toMatchObject({ gate: "approve-apply", resolvedBy: "alice", via: "point", answer: { id: question.id, path: question.path, answer: true } });
+
+    // 4. The ledger entry cites the answer record...
+    expect(port.resolved).toHaveLength(1);
+    const resolution = port.resolved[0];
+    expect(resolution).toMatchObject({
+      op: "prod-apply",
+      gate: "approve-apply",
+      resolvedBy: "alice",
+      planDigest: PLAN_A,
+      answer: { point: "prod-apply", id: question.id, path: question.path, answer: true, decider: "quorum", answeredBy: ["alice"] },
+    });
+    // ...and the answer record names the gate and the plan the entry is for.
+    const text = readFileSync(join(root, resolution.answer!.path), "utf-8");
+    expect(text).toContain(`id: "${question.id}"`);
+    expect(text).toContain("gate:prod-apply/approve-apply");
+    expect(text).toContain(PLAN_A);
+    const answered = await workspacePoints({ cwd: root });
+    if ("error" in answered) throw new Error(answered.error.message);
+    expect(answered.questions.find((q) => q.id === resolution.answer!.id)).toMatchObject({
+      state: "answered",
+      subject: `gate:${resolution.op}/${resolution.gate}`,
+      inputs: { "gate.component": resolution.op, "gate.planDigest": resolution.planDigest },
+      answeredBy: ["alice"],
+    });
+  });
+
+  test("a retry of the answered plan writes no second resolution, and a new plan is a new question", async () => {
+    const port = memoryGateLedgerPort();
+    const op = config();
+    plan = PLAN_A;
+    applied.length = 0;
+
+    // The answer from the first test stands for PLAN_A: this ledger has no
+    // pending fact yet, and the run passes at once, citing the same record.
+    const retry = await runOpLocally(op, activities, {}, undefined, { gates: port, cwd: root, now: "2026-10-06T11:00:00.000Z" });
+    expect(retry.status).toBe("ok");
+    expect(port.resolved).toHaveLength(1);
+    const again = await runOpLocally(op, activities, {}, undefined, { gates: port, cwd: root, now: "2026-10-06T11:01:00.000Z" });
+    expect(again.status).toBe("ok");
+    expect(port.resolved).toHaveLength(1);
+
+    // Another plan asks another question, and waits on it.
+    plan = PLAN_B;
+    const moved = await runOpLocally(op, activities, {}, undefined, { gates: port, cwd: root, now: "2026-10-06T11:02:00.000Z" });
+    expect(moved.status).toBe("waiting");
+    expect(moved.point?.id).not.toBe(port.resolved[0].answer?.id);
+    expect(applied).toEqual([PLAN_A, PLAN_A]);
+  });
+});