@intentius/chant 0.106.3 → 0.107.1

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

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 {