@intentius/chant 0.106.4 → 0.107.1

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

@@ -0,0 +1,235 @@
+/**
+ * A gate that asks a declared decision point (#3170), against a stub asker
+ * and an in-memory gate ledger: the declaration's checks, the `gate.*`
+ * inputs, an open question ending the run `waiting` with a pending fact that
+ * cites it, an answer passing the gate with a resolution that cites the
+ * record (once), an answer the gate does not pass on failing the step, and a
+ * plain gate deciding as before. The end-to-end run through `chant workspace
+ * points answer` is in `./gate-point.e2e.test.ts`.
+ */
+
+import { describe, expect, test } from "vitest";
+import { gate, Op, phase, activity } from "./builders";
+import { memoryGateLedgerPort } from "./gate";
+import { gatePointInputs, gatePointProblems, gateSubject, type GatePointFacts } from "./gate-point";
+import { evaluatePointGate, type GatePointAsker, type GatePointQuestion, type GatePointRequest } from "./gate-point-run";
+import { runOpLocally } from "./local-executor";
+import { stepOutput } from "./step-output-ref";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+
+const PLAN = `sha256:${"a".repeat(64)}`;
+const OTHER = `sha256:${"b".repeat(64)}`;
+const NOW = "2026-10-06T10:00:00.000Z";
+const LATER = "2026-10-06T11:00:00.000Z";
+
+/** A stub asker: the question's state comes from `answers`, by plan digest, and every request is kept. */
+function stubAsker(answers: Map<string | null, Partial<GatePointQuestion>>): GatePointAsker & { asked: GatePointRequest[] } {
+  const asked: GatePointRequest[] = [];
+  return {
+    asked,
+    async ask(request) {
+      asked.push(request);
+      const id = `${request.point}-${(request.facts.planDigest ?? "none").slice(7, 19)}`;
+      const given = answers.get(request.facts.planDigest) ?? {};
+      return {
+        id,
+        point: request.point,
+        path: `answers/${id}.md`,
+        state: "escalated",
+        answer: null,
+        decider: "quorum",
+        answeredBy: [],
+        subject: request.subject,
+        steward: null,
+        ...given,
+      };
+    },
+  };
+}
+
+const facts = (over: Partial<GatePointFacts> = {}): GatePointFacts => ({ component: "prod-apply", name: "apply", env: null, planDigest: PLAN, ...over });
+
+describe("a gate's point declaration (#3170)", () => {
+  test("gate() takes a point by name or as { name, inputs, pass }", () => {
+    expect(gate("apply", { point: "prod-apply" }).point).toBe("prod-apply");
+    expect(gate("apply", { point: { name: "prod-apply", pass: ["apply"] } }).point).toEqual({ name: "prod-apply", pass: ["apply"] });
+  });
+
+  test("gate() refuses a point beside an approval block, a bad name, and a gate.* input given by hand", () => {
+    expect(() => gate("apply", { point: "prod-apply", approval: { quorum: { count: 2 } } })).toThrow(/give `approval` or `point`, not both/);
+    expect(() => gate("apply", { point: "Prod Apply" })).toThrow(/decision point's name/);
+    expect(() => gate("apply", { point: { name: "prod-apply", inputs: { "gate.planDigest": PLAN } } })).toThrow(/which the gate passes itself/);
+    expect(gatePointProblems({ name: "prod-apply", pass: [] })).toEqual(["`point.pass` is a non-empty list of the answers that pass the gate"]);
+    expect(gatePointProblems({ name: "prod-apply", quorum: 2 })).toEqual(["`point` takes name, inputs and pass, not quorum"]);
+  });
+
+  test("the gate passes the gate.* inputs the point declares, beside the authored ones", () => {
+    expect(gatePointInputs("prod-apply", ["gate.component", "gate.planDigest", "record.size"], facts(), { "record.size": 3 })).toEqual({
+      "record.size": 3,
+      "gate.component": "prod-apply",
+      "gate.planDigest": PLAN,
+    });
+    // gate.env is null without --env, so it is left out even when declared.
+    expect(gatePointInputs("prod-apply", ["gate.env", "gate.planDigest"], facts())).toEqual({ "gate.planDigest": PLAN });
+  });
+
+  test("a plan-bound gate refuses a point that does not declare gate.planDigest", () => {
+    expect(() => gatePointInputs("prod-apply", ["gate.component"], facts())).toThrow(/does not declare the input gate.planDigest/);
+    // A gate that binds no plan needs no such input.
+    expect(gatePointInputs("prod-apply", ["gate.component"], facts({ planDigest: null }))).toEqual({ "gate.component": "prod-apply" });
+  });
+
+  test("the answer record names the gate as gate:<op>/<gate>, with @<env> when the run names one", () => {
+    expect(gateSubject("prod-apply", "apply")).toBe("gate:prod-apply/apply");
+    expect(gateSubject("prod-apply", "apply", "prod")).toBe("gate:prod-apply/apply@prod");
+  });
+});
+
+describe("evaluatePointGate (#3170)", () => {
+  test("an open question records one pending fact that cites it, and a second run leaves it standing", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map());
+    const input = { op: "prod-apply", gate: "apply", point: { name: "prod-apply" }, planDigest: PLAN, now: NOW };
+    const first = await evaluatePointGate(port, asker, input);
+    if (first.satisfied || !("waiting" in first)) throw new Error("expected the gate to wait");
+    expect(first.recorded).toBe(true);
+    expect(first.waiting).toMatchObject({ id: "prod-apply-aaaaaaaaaaaa", point: "prod-apply", state: "escalated" });
+    expect(first.pending).toMatchObject({ op: "prod-apply", gate: "apply", planDigest: PLAN, answer: { point: "prod-apply", id: "prod-apply-aaaaaaaaaaaa", path: "answers/prod-apply-aaaaaaaaaaaa.md" } });
+    expect(asker.asked[0]).toMatchObject({ point: "prod-apply", subject: "gate:prod-apply/apply", facts: { component: "prod-apply", name: "apply", planDigest: PLAN } });
+
+    const second = await evaluatePointGate(port, asker, { ...input, now: LATER });
+    if (second.satisfied || !("waiting" in second)) throw new Error("expected the gate to wait");
+    expect(second.recorded).toBe(false);
+    expect(port.appended).toHaveLength(1);
+  });
+
+  test("an answer it passes on writes one resolution citing the answer record, and a retry reuses it", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map([[PLAN, { state: "answered", answer: true, answeredBy: ["alice"] }]]));
+    const input = { op: "prod-apply", gate: "apply", point: { name: "prod-apply" }, planDigest: PLAN, now: NOW };
+    const first = await evaluatePointGate(port, asker, input);
+    if (!first.satisfied) throw new Error("expected the gate to pass");
+    expect(first.recorded).toBe(true);
+    expect(first.resolution).toMatchObject({
+      op: "prod-apply",
+      gate: "apply",
+      resolvedBy: "alice",
+      planDigest: PLAN,
+      approver: { kind: "human" },
+      answer: { point: "prod-apply", id: "prod-apply-aaaaaaaaaaaa", path: "answers/prod-apply-aaaaaaaaaaaa.md", answer: true, decider: "quorum", answeredBy: ["alice"] },
+    });
+    const again = await evaluatePointGate(port, asker, { ...input, now: LATER });
+    if (!again.satisfied) throw new Error("expected the gate to pass");
+    expect(again.recorded).toBe(false);
+    expect(port.resolved).toHaveLength(1);
+  });
+
+  test("an answer for one plan does not pass another: the new plan is a new question", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map([[PLAN, { state: "answered", answer: true, answeredBy: ["alice"] }]]));
+    const passed = await evaluatePointGate(port, asker, { op: "prod-apply", gate: "apply", point: { name: "prod-apply" }, planDigest: PLAN, now: NOW });
+    expect(passed.satisfied).toBe(true);
+    const moved = await evaluatePointGate(port, asker, { op: "prod-apply", gate: "apply", point: { name: "prod-apply" }, planDigest: OTHER, now: LATER });
+    if (moved.satisfied || !("waiting" in moved)) throw new Error("expected the gate to wait on the new plan's question");
+    expect(moved.waiting.id).toBe("prod-apply-bbbbbbbbbbbb");
+    expect(moved.pending.planDigest).toBe(OTHER);
+  });
+
+  test("a table's answer passes the gate, recorded as the decider's", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map([[PLAN, { state: "answered", answer: true, decider: "table" }]]));
+    const check = await evaluatePointGate(port, asker, { op: "prod-apply", gate: "apply", point: { name: "prod-apply" }, planDigest: PLAN, now: NOW });
+    if (!check.satisfied) throw new Error("expected the gate to pass");
+    expect(check.resolution).toMatchObject({ resolvedBy: "table", approver: { kind: "agent" }, answer: { decider: "table", answer: true } });
+  });
+
+  test("an answer the gate does not pass on is refused, naming the record and how to ask again", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map([[PLAN, { state: "answered", answer: false, answeredBy: ["alice"] }]]));
+    const check = await evaluatePointGate(port, asker, { op: "prod-apply", gate: "apply", point: { name: "prod-apply" }, planDigest: PLAN, now: NOW });
+    if (check.satisfied || !("refused" in check)) throw new Error("expected a refusal");
+    expect(check.refused).toContain("prod-apply-aaaaaaaaaaaa");
+    expect(check.refused).toContain("chant workspace points retract prod-apply-aaaaaaaaaaaa");
+    expect(port.resolved).toHaveLength(0);
+  });
+
+  test("pass names the answers a choice point passes on", async () => {
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map([[PLAN, { state: "answered", answer: "apply", answeredBy: ["alice"] }]]));
+    const check = await evaluatePointGate(port, asker, { op: "prod-apply", gate: "apply", point: { name: "prod-route", pass: ["apply"] }, planDigest: PLAN, now: NOW });
+    expect(check.satisfied).toBe(true);
+  });
+});
+
+describe("a run reaching a gate that asks a point (#3170)", () => {
+  const applied: string[] = [];
+  const activities = new Map<string, ActivityFn>([
+    ["plan", async () => ({ planDigest: PLAN })],
+    ["apply", async () => {
+      applied.push("apply");
+      return { ok: true };
+    }],
+  ]);
+  const opWith = (gateStep: ReturnType<typeof gate>): OpConfig =>
+    (Op({
+      name: "prod-apply",
+      overview: "Plan, gate and apply.",
+      phases: [
+        phase("Plan", [activity("plan", {}, { id: "plan" })]),
+        phase("Approve", [gateStep]),
+        phase("Apply", [activity("apply", {})]),
+      ],
+    }) as unknown as { props: OpConfig }).props;
+
+  test("an open question ends the run waiting on it, and its answer lets the next run apply", async () => {
+    applied.length = 0;
+    const port = memoryGateLedgerPort();
+    const answers = new Map<string | null, Partial<GatePointQuestion>>();
+    const asker = stubAsker(answers);
+    const config = opWith(gate("apply", { plan: stepOutput("plan", "planDigest"), point: "prod-apply" }));
+
+    const first = await runOpLocally(config, activities, {}, undefined, { gates: port, points: asker, now: NOW });
+    expect(first.status).toBe("waiting");
+    expect(first.point).toMatchObject({ id: "prod-apply-aaaaaaaaaaaa", point: "prod-apply" });
+    expect(first.records.find((r) => r.fn === "gate:apply")).toMatchObject({ status: "skipped", point: { id: "prod-apply-aaaaaaaaaaaa" } });
+    expect(applied).toEqual([]);
+
+    answers.set(PLAN, { state: "answered", answer: true, answeredBy: ["alice"] });
+    const second = await runOpLocally(config, activities, {}, undefined, { gates: port, points: asker, now: LATER });
+    expect(second.status).toBe("ok");
+    expect(applied).toEqual(["apply"]);
+    const step = second.records.find((r) => r.fn === "gate:apply");
+    expect(step?.approval).toMatchObject({ gate: "apply", resolvedBy: "alice", via: "point", answer: { id: "prod-apply-aaaaaaaaaaaa", answer: true } });
+    expect(port.resolved[0].answer?.id).toBe("prod-apply-aaaaaaaaaaaa");
+  });
+
+  test("a no fails the run at the gate and applies nothing", async () => {
+    applied.length = 0;
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map([[PLAN, { state: "answered", answer: false, answeredBy: ["alice"] }]]));
+    const config = opWith(gate("apply", { plan: stepOutput("plan", "planDigest"), point: "prod-apply" }));
+    const failed = await runOpLocally(config, activities, {}, undefined, { gates: port, points: asker, now: NOW }).then(
+      () => {
+        throw new Error("expected the run to fail");
+      },
+      (err: { result?: { status: string; records: Array<{ fn: string; status: string; error?: string }> } }) => err.result,
+    );
+    expect(failed?.status).toBe("fail");
+    expect(failed?.records.find((r) => r.fn === "gate:apply")).toMatchObject({ status: "fail" });
+    expect(applied).toEqual([]);
+  });
+
+  test("a plain gate still records a pending fact and ends gated, and never asks a point", async () => {
+    applied.length = 0;
+    const port = memoryGateLedgerPort();
+    const asker = stubAsker(new Map());
+    const config = opWith(gate("apply", { plan: stepOutput("plan", "planDigest") }));
+    const result = await runOpLocally(config, activities, {}, undefined, { gates: port, points: asker, now: NOW });
+    expect(result.status).toBe("gated");
+    expect(result.gate).toMatchObject({ gate: "apply", planDigest: PLAN });
+    expect(result.gate?.answer).toBeUndefined();
+    expect(asker.asked).toHaveLength(0);
+    expect(applied).toEqual([]);
+  });
+});

package/src/op/gate-point.ts

@@ -0,0 +1,119 @@
+/**
+ * A gate that asks a declared decision point (#3170): the declaration's
+ * shape. What a run does when it reaches one is in `./gate-point-run.ts`.
+ *
+ * A plain gate is a pair of facts on the gate ledger: the run records a
+ * pending fact, and `chant approve` records the resolution. A gate that names
+ * a point asks it instead, the way the `decide` activity does (#2740): the
+ * point's deciders (a table, a model, people) and its quorum decide, the
+ * answer is an answer record in the workspace, and an open question is
+ * answered with `chant workspace points answer` or through hud. The run then
+ * passes the gate on that answer and writes the resolution itself, citing the
+ * record. So the gate ledger and the workspace's decision history both show
+ * the approval, and each names the other.
+ *
+ * This module imports nothing at run time, so the `gate` builder can check a
+ * declaration without loading the ledger or the workspace.
+ */
+
+/**
+ * The decision point a gate asks (#3170). `gate("apply", { point:
+ * "prod-apply" })` is `{ name: "prod-apply" }`.
+ */
+export interface GatePoint {
+  /** The point's name, as the workspace's points file declares it. */
+  name: string;
+  /**
+   * Inputs besides the gate's own `gate.*` ones, by the point's input names.
+   * A step-output reference resolves when the run reaches the gate. Only
+   * inputs the point declares may be given.
+   */
+  inputs?: Record<string, unknown>;
+  /** The answers that pass the gate. Default `[true]`: a noul point's yes. Any other answer fails the step. */
+  pass?: Array<string | boolean>;
+}
+
+/** The answers a gate passes on when it names none: a noul point's yes. */
+export const DEFAULT_GATE_POINT_PASS: ReadonlyArray<string | boolean> = [true];
+
+/** A gate's `point` as a {@link GatePoint}, or undefined for a plain gate. */
+export function gatePointOf(point: string | GatePoint | undefined): GatePoint | undefined {
+  if (point === undefined) return undefined;
+  return typeof point === "string" ? { name: point } : point;
+}
+
+const POINT_NAME = /^[a-z][a-z0-9-]*$/;
+
+/** What is wrong with a gate's `point`, empty when nothing is. `withApproval` is whether the gate also declares `approval`. */
+export function gatePointProblems(point: unknown, withApproval = false): string[] {
+  const problems: string[] = [];
+  if (withApproval) problems.push("a gate that asks a decision point takes its quorum from the point: give `approval` or `point`, not both");
+  const p = typeof point === "string" ? { name: point } : point;
+  if (p === null || typeof p !== "object" || Array.isArray(p)) return [...problems, "`point` is a decision point's name or { name, inputs?, pass? }"];
+  const { name, inputs, pass, ...rest } = p as Record<string, unknown>;
+  if (typeof name !== "string" || !POINT_NAME.test(name)) problems.push("`point.name` is a decision point's name: lower case letters, digits and hyphens, starting with a letter");
+  if (inputs !== undefined && (inputs === null || typeof inputs !== "object" || Array.isArray(inputs))) problems.push("`point.inputs` is an object of input name to value");
+  if (inputs && typeof inputs === "object") {
+    const own = Object.keys(inputs).filter((k) => k in GATE_POINT_INPUTS);
+    if (own.length > 0) problems.push(`\`point.inputs\` gives ${own.join(", ")}, which the gate passes itself`);
+  }
+  if (pass !== undefined && (!Array.isArray(pass) || pass.length === 0 || pass.some((a) => typeof a !== "string" && typeof a !== "boolean"))) {
+    problems.push("`point.pass` is a non-empty list of the answers that pass the gate");
+  }
+  const extra = Object.keys(rest);
+  if (extra.length > 0) problems.push(`\`point\` takes name, inputs and pass, not ${extra.join(", ")}`);
+  return problems;
+}
+
+/**
+ * What the run knows about the gate it reached: the fields the `status` read
+ * contract lists a gate with, which a point reads as its `gate.*` inputs.
+ */
+export interface GatePointFacts {
+  /** The op the gate is recorded under. */
+  component: string;
+  /** The gate's name. */
+  name: string;
+  /** The environment the run was started for, or null. */
+  env: string | null;
+  /** The plan the gate binds, or null when it binds none. */
+  planDigest: string | null;
+}
+
+/** The `gate.*` inputs a gate passes to its point, each from a {@link GatePointFacts} field. */
+export const GATE_POINT_INPUTS: Readonly<Record<string, keyof GatePointFacts>> = {
+  "gate.component": "component",
+  "gate.name": "name",
+  "gate.env": "env",
+  "gate.planDigest": "planDigest",
+};
+
+/**
+ * The inputs a gate asks its point with: the `gate.*` inputs the point
+ * declares, from `facts`, and the authored ones. A gate that binds a plan
+ * asks a point that declares `gate.planDigest`, so each plan is its own
+ * question and an answer for one plan never passes another: it throws
+ * otherwise, naming the input to declare.
+ */
+export function gatePointInputs(point: string, declared: readonly string[], facts: GatePointFacts, authored: Record<string, unknown> = {}): Record<string, unknown> {
+  if (facts.planDigest !== null && !declared.includes("gate.planDigest")) {
+    throw new Error(
+      `gate "${facts.name}" binds a plan and asks decision point ${point}, which does not declare the input gate.planDigest: ` +
+        `declare it in the points file, so each plan is its own question and an answer for one plan never passes another`,
+    );
+  }
+  const inputs: Record<string, unknown> = {};
+  for (const [input, field] of Object.entries(GATE_POINT_INPUTS)) {
+    if (declared.includes(input) && facts[field] !== null) inputs[input] = facts[field];
+  }
+  return { ...authored, ...inputs };
+}
+
+/**
+ * What an answer record's `constrains` names a gate by: `gate:<op>/<gate>`,
+ * with `@<env>` when the run names an environment. It is how the record
+ * names the gate ledger entry that cites it.
+ */
+export function gateSubject(op: string, gate: string, env?: string | null): string {
+  return `gate:${op}/${gate}${env ? `@${env}` : ""}`;
+}

package/src/op/gate.ts

@@ -33,6 +33,7 @@
  */
 
 import {
+  appendGateResolution,
   appendPendingGate,
   isPendingGateExpired,
   latestPendingGate,
@@ -40,6 +41,7 @@ import {
   readGateLedger,
   resolveApprovalUrl,
   DEFAULT_GATE_EXPIRY,
+  type GateResolutionInput,
   type GateResolutionRecord,
   type PendingGateInput,
   type PendingGateRecord,
@@ -74,6 +76,12 @@ export interface PendingGatePush {
 export interface GateLedgerPort {
   read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
   appendPending(input: PendingGateInput): Promise<PendingGatePush>;
+  /**
+   * Append a resolution the run itself writes (#3170): a gate that asks a
+   * decision point records the answer that passed it. Absent on a port that
+   * only plain gates use.
+   */
+  appendResolution?(input: GateResolutionInput): Promise<{ record: GateResolutionRecord; pushed: boolean; pushWarning?: string }>;
   /**
    * The rule a workspace sets for approvals of `gate` (#3163, ws-080), or
    * null when none applies: the declaration's `identity.gates`, read at base.
@@ -120,6 +128,15 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { gateAdmission } = await import("../workspace/identity");
       return gateAdmission(opts?.cwd ?? process.cwd(), gate);
     },
+    async appendResolution(input) {
+      const { record } = await appendGateResolution(input, opts);
+      try {
+        const pushed = await pushLifecycle(opts);
+        return pushed ? { record, pushed } : { record, pushed, pushWarning: "no remote is configured for chant/lifecycle — the resolution was recorded locally only" };
+      } catch (err) {
+        return { record, pushed: false, pushWarning: err instanceof Error ? err.message : String(err) };
+      }
+    },
     async appendPending(input) {
       const { record } = await appendPendingGate(input, opts);
       try {
@@ -146,15 +163,23 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
 /** A gate ledger held in memory — what a test, or a caller that has already read the ledger, hands {@link evaluateGate}. */
 export function memoryGateLedgerPort(
   seed: { resolutions?: GateResolutionRecord[]; pending?: PendingGateRecord[] } = {},
-): GateLedgerPort & { appended: PendingGateRecord[] } {
+): GateLedgerPort & { appended: PendingGateRecord[]; resolved: GateResolutionRecord[] } {
   const resolutions = [...(seed.resolutions ?? [])];
   const pending = [...(seed.pending ?? [])];
   const appended: PendingGateRecord[] = [];
+  const resolved: GateResolutionRecord[] = [];
   return {
     appended,
+    resolved,
     async read() {
       return { resolutions: [...resolutions], pending: [...pending] };
     },
+    async appendResolution(input) {
+      const record: GateResolutionRecord = { version: 1, ...input };
+      resolutions.push(record);
+      resolved.push(record);
+      return { record, pushed: true };
+    },
     async appendPending(input) {
       const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
       pending.push(record);

package/src/op/index.ts

@@ -72,11 +72,19 @@ export type {
   GateApproval, GateApprovalMode, GateApprover, GateContextValue, GatePolicyAnswer, GatePolicyDecision,
   GatePolicyEvaluator, GatePolicyRef, GatePolicyRequest, GateQuorum, ResolvedGateApproval,
 } from "./gate-approval";
+export {
+  gatePlanSummary, gatePlanSummaryOfResult, changeSetOfResult, GATE_PLAN_CONTEXT_KEY, GATE_PLAN_ADDRESS_LIMIT,
+} from "./gate-plan-context";
+export type { GatePlanSummary } from "./gate-plan-context";
 export {
   computePlanDigest, isPlanDigest, describePlanDigest, samePlanDigest, PLAN_DIGEST_ALGORITHM, PLAN_DIGEST_PREFIX,
 } from "../lifecycle/plan-digest";
 export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name";
 export type { GateNamed } from "./gate-name";
+export { gatePointOf, gatePointProblems, gatePointInputs, gateSubject, GATE_POINT_INPUTS, DEFAULT_GATE_POINT_PASS } from "./gate-point";
+export type { GatePoint, GatePointFacts } from "./gate-point";
+export { evaluatePointGate, workspaceGatePointAsker } from "./gate-point-run";
+export type { GatePointAsker, GatePointQuestion, GatePointRequest, PointGateCheck, PointGateInput } from "./gate-point-run";
 export { createLocalOpRuntime } from "./runtimes/local";
 export { runStateOf } from "./runtime";
 export type {

package/src/op/local-executor.ts

@@ -28,9 +28,12 @@ import { parseDuration } from "./duration";
 import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
+import { gatePointOf } from "./gate-point";
+import { evaluatePointGate, workspaceGatePointAsker, type GatePointAsker } from "./gate-point-run";
 import type { ResolvedGateApproval } from "./gate-approval";
+import { GATE_PLAN_CONTEXT_KEY, gatePlanSummaryOfResult } from "./gate-plan-context";
 import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
-import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPointWait, type WaitingPoint } from "./steward-points";
 import { isGateWait } from "./gate-wait";
 import { currentStewardTurn, enterStewardTurn } from "./steward-turn";
@@ -72,10 +75,12 @@ export interface StepRecord {
     resolvedBy: string;
     timestamp: string;
     url?: string;
-    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. */
-    via?: "quorum" | "policy";
+    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. `"point"` on a gate that asks a decision point (#3170). */
+    via?: "quorum" | "policy" | "point";
     /** On a gate with a quorum (#2508): every approver who counted toward it. */
     approvers?: string[];
+    /** On a gate that asks a decision point (#3170): the answer record that passed it, which the gate ledger's resolution cites too. */
+    answer?: GateAnswerRef;
   };
   /**
    * Why a step declined to proceed on something that is not a failure
@@ -489,6 +494,10 @@ interface GateContext {
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
+  /** How a gate that names a decision point asks it (#3170). */
+  points?: GatePointAsker;
+  /** The environment the run was started for, a point gate's `gate.env` input. */
+  env?: string;
 }
 
 /**
@@ -584,6 +593,13 @@ function resolveGateApproval(
       if (resolved !== undefined && resolved !== null) context[key] = resolved;
     }
   }
+  // #3182: a policy also sees what the plan does. When the gate's `plan`
+  // names the step that planned it and that step returned a change set, its
+  // summary lands under `context.plan` with no context code in the Op.
+  if (authored.policy && isStepOutputRef(step.plan)) {
+    const summary = gatePlanSummaryOfResult(resultsById.get(step.plan.step));
+    if (summary) context = { ...(context ?? {}), [GATE_PLAN_CONTEXT_KEY]: summary };
+  }
   return {
     ...(authored.quorum ? { quorum: authored.quorum } : {}),
     ...(authored.policy ? { policy: authored.policy } : {}),
@@ -604,6 +620,7 @@ async function runGateStep(
   gates: GateContext,
   resultsById: ReadonlyMap<string, unknown> = new Map(),
 ): Promise<{ record: StepRecord; pending?: PendingGateRecord; pushed?: boolean; pushWarning?: string }> {
+  if (step.point !== undefined) return runPointGateStep(step, phaseName, gates, resultsById);
   const start = Date.now();
   // #2300: `plan` is authored as a reference into the Plan phase's result
   // (`plan.out.planDigest`), and is resolved here through the same walk an
@@ -689,6 +706,57 @@ async function runGateStep(
   };
 }
 
+/**
+ * Decide a gate that asks a decision point (#3170, `./gate-point-run.ts`).
+ * An answer it passes on lands on the step record as the approval, citing
+ * the answer record; an open question puts the question on the record, as an
+ * activity's open point does, and the caller ends the run `waiting`; any
+ * other answer fails the step.
+ */
+async function runPointGateStep(
+  step: GateStep,
+  phaseName: string,
+  gates: GateContext,
+  resultsById: ReadonlyMap<string, unknown>,
+): Promise<{ record: StepRecord; pushed?: boolean; pushWarning?: string }> {
+  const start = Date.now();
+  const point = gatePointOf(step.point)!;
+  const base = { phase: phaseName, fn: gateFn(step), args: {} };
+  const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
+  const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
+  const inputs = point.inputs ? (resolveStepOutputRefs(point.inputs, resultsById) as Record<string, unknown>) : undefined;
+  try {
+    const check = await evaluatePointGate(gates.port, gates.points ?? workspaceGatePointAsker(process.cwd()), {
+      op: gates.op,
+      gate: gateName(step),
+      point,
+      ...(inputs ? { inputs } : {}),
+      ...(step.description ? { description: step.description } : {}),
+      ...(step.timeout ? { timeout: step.timeout } : {}),
+      ...(gates.runId ? { runId: gates.runId } : {}),
+      ...(planDigest !== undefined ? { planDigest } : {}),
+      ...(gates.env !== undefined ? { env: gates.env } : {}),
+      ...(gates.now ? { now: gates.now } : {}),
+    });
+    if (check.satisfied) {
+      const approval: NonNullable<StepRecord["approval"]> = {
+        gate: gateName(step),
+        resolvedBy: check.resolution.resolvedBy,
+        timestamp: check.resolution.timestamp,
+        via: "point",
+        ...(check.answer.answeredBy ? { approvers: check.answer.answeredBy } : {}),
+        answer: check.answer,
+      };
+      gates.passed?.push({ gate: gateName(step), approval });
+      return { record: { ...base, status: "ok", durationMs: Date.now() - start, approval }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+    }
+    if ("refused" in check) return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: check.refused } };
+    return { record: { ...base, status: "skipped", durationMs: Date.now() - start, point: check.waiting }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+  } catch (err) {
+    return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(err) } };
+  }
+}
+
 /**
  * Run one effect step: read-compare-run-write. On a match the nested steps are
  * recorded as skipped ("effect already applied") and nothing is written. On a
@@ -778,6 +846,11 @@ async function runEffectStep(
         skipRest(i + 1);
         return { records, failed: false, pending, pushed, ...(pushWarning ? { pushWarning } : {}) };
       }
+      if (record.point) {
+        // A gate's open decision point (#3170): as for an activity's.
+        skipRest(i + 1);
+        return { records, failed: false, point: record.point };
+      }
       continue;
     }
     const ran = await runStep(nested, phaseName, activities, profiles, resultsById, signal);
@@ -866,6 +939,13 @@ async function runPhase(
         }
         throw new GateStop(gateRecords, pending, phase.name, pushed, pushWarning);
       }
+      if (record.point) {
+        // A gate's open decision point (#3170): nothing fans out.
+        for (const skipped of phase.steps.filter(isActivity)) {
+          pushRecord(gateRecords, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+        }
+        throw new PointStop(gateRecords, record.point, phase.name);
+      }
     }
     const steps = phase.steps.filter(isActivity);
     const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
@@ -921,6 +1001,12 @@ async function runPhase(
         skipRemaining(i + 1);
         throw new GateStop(records, pending, phase.name, pushed, pushWarning);
       }
+      if (record.point) {
+        // A gate that asks a decision point (#3170) and found it open: the
+        // run waits on the question, as at an activity's open point.
+        skipRemaining(i + 1);
+        throw new PointStop(records, record.point, phase.name);
+      }
       continue;
     }
     if (isEffect(step)) {
@@ -980,6 +1066,11 @@ export interface RunOpOptions {
   now?: string;
   /** Identifies this run on any pending fact it records. */
   runId?: string;
+  /**
+   * How a gate that names a decision point asks it (#3170). Defaults to the
+   * workspace holding `cwd` (`workspaceGatePointAsker`); a test passes a stub.
+   */
+  points?: GatePointAsker;
   /**
    * The environment the run was started for (`--env`, #2522). The executor
    * only hands it to activities through the run context (`./run-context.ts`).
@@ -1102,6 +1193,8 @@ async function runOpInTurn(
     runId,
     ...(options.onRecord ? { onRecord: options.onRecord } : {}),
     passed: run.passedGates,
+    points: options.points ?? workspaceGatePointAsker(options.cwd ?? process.cwd()),
+    ...(options.env !== undefined ? { env: options.env } : {}),
   };
 
   // Effect steps are ordered (read-compare-run-write): refuse them in a

package/src/op/op-ir.ts

@@ -149,6 +149,8 @@ export interface OpIRGateStep {
   plan?: GateStep["plan"];
   /** Quorum, roles and policy (#2508), carried as authored. Absent on a gate that passes on one approval. */
   approval?: GateStep["approval"];
+  /** The decision point the gate asks (#3170), carried as authored. Absent on a gate that `chant approve` passes. */
+  point?: GateStep["point"];
 }
 
 export interface OpIREffectStep {
@@ -258,6 +260,7 @@ function irGateStep(step: GateStep): OpIRGateStep {
     ...(step.description ? { description: step.description } : {}),
     ...(step.plan !== undefined ? { plan: step.plan } : {}),
     ...(step.approval !== undefined ? { approval: step.approval } : {}),
+    ...(step.point !== undefined ? { point: step.point } : {}),
   };
 }
 
@@ -412,6 +415,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       ...(step.description ? { description: step.description } : {}),
       ...(step.plan !== undefined ? { plan: step.plan } : {}),
       ...(step.approval !== undefined ? { approval: step.approval } : {}),
+      ...(step.point !== undefined ? { point: step.point } : {}),
     };
   }
   return {