@intentius/chant 0.124.24 → 0.124.26

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

@@ -0,0 +1,284 @@
+/**
+ * #3947: a run resumes at the approved gate instead of re-running from the
+ * first phase. Each test drives the loop through the executor against an
+ * in-memory gate ledger: a run stops at the gate and stores a checkpoint, an
+ * approval copies its digest, and the next run either picks up at the gate
+ * or starts at the first phase and says why.
+ */
+
+import { describe, expect, test } from "vitest";
+import { runOpLocally, type OpRunResult } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { stepOutput } from "./step-output-ref";
+import { activityContract } from "./activity-contract";
+import { resumeGatesOf, validateGateResume } from "./gate-checkpoint";
+import { renderHuman } from "./local-output";
+import { gateCheckpointDigest, gateCheckpointText, parseGateCheckpoint } from "../lifecycle/gate-checkpoint";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { z } from "zod";
+
+const PLAN = `jcs1-sha256:${"a".repeat(64)}`;
+const MOVED = `jcs1-sha256:${"b".repeat(64)}`;
+const COMMIT = "1".repeat(40);
+
+/**
+ * An Op shaped like loomster's upgrade: a snapshot step whose id the apply
+ * and the rollback both read, a plan, the gate, then the apply. `noise` runs
+ * before the gate and nothing reads it, so the checkpoint leaves it out.
+ */
+function upgradeOp(gate: Record<string, unknown> = {}): OpConfig {
+  return {
+    name: "upgrade",
+    overview: "upgrade a stack",
+    phases: [
+      {
+        name: "Prepare",
+        steps: [
+          { kind: "activity", id: "snapshot", fn: "snapshot" },
+          { kind: "activity", id: "noise", fn: "noise" },
+        ],
+      },
+      { name: "Plan", steps: [{ kind: "activity", id: "plan", fn: "plan", args: { stack: stepOutput("snapshot", "stack") } }] },
+      {
+        name: "Gate",
+        steps: [{ kind: "gate", gate: "approve-upgrade", plan: stepOutput("plan", "planDigest"), resume: true, ...gate }],
+      },
+      { name: "Apply", steps: [{ kind: "activity", fn: "apply", args: { snapshot: stepOutput("snapshot", "id") } }] },
+    ],
+    onFailure: [{ name: "Rollback", steps: [{ kind: "activity", fn: "rollback", args: { to: stepOutput("snapshot", "id") } }] }],
+  };
+}
+
+/** Activities that count their calls; `plan` returns whatever `digest.value` holds. */
+function harness() {
+  const calls: Record<string, Array<Record<string, unknown>>> = {};
+  const digest = { value: PLAN };
+  let snapshots = 0;
+  const track = (name: string, fn: ActivityFn): ActivityFn => async (args, signal) => {
+    (calls[name] ??= []).push(args);
+    return fn(args, signal);
+  };
+  const activities = new Map<string, ActivityFn>([
+    ["snapshot", track("snapshot", async () => ({ id: `snap-${++snapshots}`, stack: "web" }))],
+    ["noise", track("noise", async () => ({ big: "x".repeat(10) }))],
+    ["plan", track("plan", async () => ({ planDigest: digest.value }))],
+    ["apply", track("apply", async () => ({ ok: true }))],
+    ["rollback", track("rollback", async () => ({ ok: true }))],
+  ]);
+  return { calls, digest, activities };
+}
+
+const at = (minute: number) => `2026-10-12T12:${String(minute).padStart(2, "0")}:00.000Z`;
+
+async function stopAtGate(config: OpConfig, h: ReturnType<typeof harness>, port = memoryGateLedgerPort()) {
+  const first = await runOpLocally(config, h.activities, {}, undefined, { gates: port, now: at(0), runId: "run-1", commit: COMMIT });
+  return { port, first };
+}
+
+async function approve(port: ReturnType<typeof memoryGateLedgerPort>, first: OpRunResult, over: Record<string, unknown> = {}) {
+  await port.appendResolution!({
+    op: "upgrade",
+    gate: "approve-upgrade",
+    resolvedBy: "alex",
+    timestamp: at(5),
+    planDigest: first.gate!.planDigest!,
+    ...(first.gate!.checkpointDigest ? { checkpointDigest: first.gate!.checkpointDigest } : {}),
+    ...over,
+  });
+}
+
+describe("which outputs cross a gate that resumes", () => {
+  test("the checkpoint stores what a later step or the rollback reads, and not the plan step or an unread output", () => {
+    const [gate] = resumeGatesOf(upgradeOp());
+    expect(gate!.name).toBe("approve-upgrade");
+    expect(gate!.planStep?.step.id).toBe("plan");
+    expect(gate!.stored).toEqual(["snapshot"]);
+  });
+
+  test("a gate without resume, or in an Op with a work lease, is not one", () => {
+    const plain = upgradeOp({ resume: false });
+    expect(resumeGatesOf(plain)).toEqual([]);
+    expect(resumeGatesOf({ ...upgradeOp(), workLease: { item: "x" } })).toEqual([]);
+  });
+});
+
+describe("a run that stops at a gate that resumes", () => {
+  test("stores a checkpoint of the crossing outputs and puts its digest on the pending fact", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    expect(first.status).toBe("gated");
+    const text = port.checkpoints.get("upgrade/run-1")!;
+    const checkpoint = parseGateCheckpoint(text)!;
+    expect(checkpoint).toMatchObject({ op: "upgrade", gate: "approve-upgrade", runId: "run-1", commit: COMMIT, planDigest: PLAN });
+    expect(checkpoint.outputs).toEqual({ snapshot: { id: "snap-1", stack: "web" } });
+    expect(first.gate?.checkpointDigest).toBe(gateCheckpointDigest(checkpoint));
+
+    const lines: string[] = [];
+    renderHuman(first, (l) => lines.push(l));
+    expect(lines.some((l) => l.includes("resume  :") && l.includes(first.gate!.checkpointDigest!))).toBe(true);
+  });
+
+  test("a later run that finds the fact standing writes no second checkpoint", async () => {
+    const h = harness();
+    const { port } = await stopAtGate(upgradeOp(), h);
+    const again = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(1), runId: "run-2", commit: COMMIT });
+    expect(again.status).toBe("gated");
+    expect(port.appended).toHaveLength(1);
+    expect([...port.checkpoints.keys()]).toEqual(["upgrade/run-1"]);
+  });
+
+  test("a secret output is never stored, and the run says the gate won't resume", async () => {
+    const h = harness();
+    const contracts = new Map([["snapshot", activityContract("snapshot", z.object({}), z.object({ id: z.string(), stack: z.string() }), { secret: ["id"] })]]);
+    const port = memoryGateLedgerPort();
+    const first = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(0), runId: "run-1", commit: COMMIT, contracts });
+    expect(first.status).toBe("gated");
+    expect(port.checkpoints.size).toBe(0);
+    expect(first.gate?.checkpointDigest).toBeUndefined();
+    expect(first.resumeNotes?.[0]).toContain(`step "snapshot"'s output "id" is secret`);
+  });
+});
+
+describe("the run after the approval", () => {
+  test("resumes at the gate: re-runs only the plan step, and the apply and rollback read the checkpoint", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await approve(port, first);
+
+    const second = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: COMMIT });
+    expect(second.status).toBe("ok");
+    expect(second.resumed).toEqual({ gate: "approve-upgrade", run: "run-1", checkpoint: first.gate!.checkpointDigest });
+    expect(h.calls.snapshot).toHaveLength(1);
+    expect(h.calls.noise).toHaveLength(1);
+    expect(h.calls.plan).toHaveLength(2);
+    expect(h.calls.plan![1]).toEqual({ stack: "web" });
+    // The apply got the first run's snapshot, not a fresh one.
+    expect(h.calls.apply).toEqual([{ snapshot: "snap-1" }]);
+
+    const snapshot = second.records.find((r) => r.fn === "snapshot");
+    expect(snapshot).toMatchObject({ status: "skipped", resumed: { run: "run-1", gate: "approve-upgrade" } });
+    expect(second.records.find((r) => r.fn === "gate:approve-upgrade")?.status).toBe("ok");
+    expect(second.record.resumed).toEqual(second.resumed);
+    expect(second.record.phases[0]?.steps[0]?.resumed).toEqual({ run: "run-1", gate: "approve-upgrade" });
+
+    const lines: string[] = [];
+    renderHuman(second, (l) => lines.push(l));
+    expect(lines[0]).toContain(`[resume] at gate "approve-upgrade", from run run-1's checkpoint`);
+  });
+
+  test("a failure after the resumed gate compensates with the checkpoint's value", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await approve(port, first);
+    h.activities.set("apply", async () => {
+      throw new Error("apply failed");
+    });
+    await expect(
+      runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: COMMIT }),
+    ).rejects.toThrow();
+    expect(h.calls.rollback).toEqual([{ to: "snap-1" }]);
+  });
+
+  test("starts at the first phase when the plan moved since the approval", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await approve(port, first);
+    h.digest.value = MOVED;
+
+    const second = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: COMMIT });
+    expect(second.status).toBe("gated");
+    expect(second.resumed).toBeUndefined();
+    expect(second.resumeNotes?.[0]).toContain("the plan moved since the approval");
+    expect(h.calls.snapshot).toHaveLength(2);
+    expect(h.calls.apply).toBeUndefined();
+  });
+
+  test("starts at the first phase at another commit", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await approve(port, first);
+
+    const second = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: "2".repeat(40) });
+    expect(second.status).toBe("ok");
+    expect(second.resumed).toBeUndefined();
+    expect(second.resumeNotes?.[0]).toContain("was at commit 111111111111, and this one is at 222222222222");
+    expect(h.calls.snapshot).toHaveLength(2);
+    expect(h.calls.apply).toEqual([{ snapshot: "snap-2" }]);
+  });
+
+  test("starts at the first phase when the checkpoint file changed after the approval", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await approve(port, first);
+    const tampered = parseGateCheckpoint(port.checkpoints.get("upgrade/run-1")!)!;
+    tampered.outputs = { snapshot: { id: "snap-evil", stack: "web" } };
+    port.checkpoints.set("upgrade/run-1", gateCheckpointText(tampered));
+
+    const second = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: COMMIT });
+    expect(second.resumeNotes?.[0]).toContain("does not match the digest the approver saw");
+    expect(h.calls.apply).toEqual([{ snapshot: "snap-2" }]);
+  });
+
+  test("starts at the first phase in another environment, or once the pending fact expired", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await approve(port, first);
+
+    const other = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: COMMIT, env: "prod" });
+    expect(other.resumeNotes?.[0]).toContain("for environment (none), and this one is for prod");
+
+    const late = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: "2026-10-20T00:00:00.000Z", runId: "run-3", commit: COMMIT });
+    expect(late.resumed).toBeUndefined();
+    expect(late.resumeNotes?.[0]).toContain("its pending fact expired");
+  });
+
+  test("an approval that copied no checkpoint passes the gate the old way, from the first phase", async () => {
+    const h = harness();
+    const { port, first } = await stopAtGate(upgradeOp(), h);
+    await port.appendResolution!({ op: "upgrade", gate: "approve-upgrade", resolvedBy: "alex", timestamp: at(5), planDigest: first.gate!.planDigest! });
+
+    const second = await runOpLocally(upgradeOp(), h.activities, {}, undefined, { gates: port, now: at(10), runId: "run-2", commit: COMMIT });
+    expect(second.status).toBe("ok");
+    expect(second.resumed).toBeUndefined();
+    expect(second.resumeNotes).toBeUndefined();
+    expect(h.calls.snapshot).toHaveLength(2);
+  });
+
+  test("a gate without resume starts at the first phase as before and stores nothing", async () => {
+    const h = harness();
+    const port = memoryGateLedgerPort();
+    const first = await runOpLocally(upgradeOp({ resume: false }), h.activities, {}, undefined, { gates: port, now: at(0), runId: "run-1", commit: COMMIT });
+    expect(first.gate?.checkpointDigest).toBeUndefined();
+    expect(port.checkpoints.size).toBe(0);
+  });
+});
+
+describe("OPS016's check", () => {
+  test("a well-placed gate passes", () => {
+    expect(validateGateResume(upgradeOp())).toEqual([]);
+  });
+
+  test("refuses a resume gate in onFailure, inside an effect, with a decision point, or under a work lease", () => {
+    const config = upgradeOp({ point: "prod-apply" });
+    config.onFailure = [{ name: "Rollback", steps: [{ kind: "gate", gate: "late", resume: true }] }];
+    config.phases.push({
+      name: "Effect",
+      steps: [{ kind: "effect", receipt: { name: "r" } as never, steps: [{ kind: "gate", gate: "inner", resume: true }] }],
+    });
+    const messages = validateGateResume({ ...config, workLease: { item: "x" } }).map((i) => i.message);
+    expect(messages).toContain("resume is supported only on a gate at the top of a main phase, not in onFailure or inside an effect");
+    expect(messages).toContain("a gate can't resume in an Op that runs under a workLease");
+    expect(messages).toContain("a gate that asks a decision point can't resume");
+  });
+
+  test("refuses a plan step that doesn't run before the gate", () => {
+    const config = upgradeOp({ plan: stepOutput("apply-later", "planDigest") });
+    expect(validateGateResume(config)[0]?.message).toContain(`its plan names step "apply-later"`);
+  });
+
+  test("refuses a secret output read after the gate", () => {
+    const contracts = new Map([["snapshot", activityContract("snapshot", z.object({}), z.object({ id: z.string() }), { secret: true })]]);
+    expect(validateGateResume(upgradeOp(), contracts)[0]?.message).toContain(`can't resume: step "snapshot"'s output "id" is secret`);
+  });
+});

package/src/op/gate-checkpoint.ts

@@ -0,0 +1,322 @@
+/**
+ * Resuming a run at an approved gate (#3947, epic #3946).
+ *
+ * Before this, a run that stopped at a gate kept nothing but its record:
+ * after `chant approve`, the next `chant run <op>` began again at the first
+ * phase and recomputed every step before the gate, so a value could not be
+ * carried across a gate with `stepOutput`. A gate with `resume: true` keeps
+ * the outputs the steps after it need, and the next run starts at the gate.
+ *
+ * Stopping. The run works out which outputs cross the gate from the Op's own
+ * references ({@link resumeGatesOf}): an output of a step before the gate
+ * that a step at or after it references, in the main phases, `onFailure` or
+ * the gate's own `approval` context. It writes them to a checkpoint
+ * (`../lifecycle/gate-checkpoint.ts`) and puts the checkpoint's digest on
+ * the pending fact. An output an activity contract marks secret is never
+ * stored, and the gate then doesn't resume ({@link checkpointBlocked}).
+ *
+ * Resuming. {@link decideGateResume} picks the last resume gate whose
+ * standing pending fact carries a checkpoint and has an approval that copied
+ * it. It resumes there only when the fact hasn't expired, the checkpoint file
+ * matches the digest the approver saw and names the fact's run, and this run
+ * is at the same commit and environment. Any failed check starts the run at
+ * the first phase and the reason is reported. The executor then re-runs the
+ * step that produced the gate's `plan`, and starts at the first phase if the
+ * digest moved, so live drift between the approval and the apply is still
+ * caught (`./local-executor.ts`).
+ */
+
+import type { ActivityStep, GateStep, OpConfig, StepDefinition } from "./types";
+import { WORK_LEASE_STEP_ID } from "./types";
+import { collectStepOutputRefs, isStepOutputRef, type StepOutputRef } from "./step-output-ref";
+import { gateName } from "./gate-name";
+import { readsSecretOutput, type ActivityContract, type ActivityContractIssue } from "./activity-contract";
+import type { GateLedgerPort } from "./gate";
+import { isPendingGateExpired, latestPendingGate, type PendingGateRecord } from "../lifecycle/gate-ledger";
+import { isApprovalSpent } from "../lifecycle/gate-applied";
+import { samePlanDigest } from "../lifecycle/plan-digest";
+import {
+  checkpointOutputs,
+  gateCheckpointDigest,
+  gateCheckpointPath,
+  isCheckpointRunId,
+  parseGateCheckpoint,
+  type GateCheckpoint,
+} from "../lifecycle/gate-checkpoint";
+
+/** A top-level activity step of a main phase, where it sits. */
+interface Producer {
+  step: ActivityStep;
+  phaseIndex: number;
+  stepIndex: number;
+}
+
+/** A gate that resumes, and what resuming at it needs. */
+export interface ResumeGate {
+  step: GateStep;
+  name: string;
+  phaseIndex: number;
+  /** The gate's index among its phase's steps. */
+  stepIndex: number;
+  /** The step the gate's `plan` names, which a resumed run runs again. Absent when the plan is a literal or there is none. */
+  planStep?: Producer;
+  /** Ids of the steps before the gate whose outputs the checkpoint stores, in authored order. The plan step is not among them. */
+  stored: string[];
+  /** The references that read a stored output, for the secret check. */
+  crossing: StepOutputRef[];
+}
+
+/** The step-output references a step reads when it runs: its args, a gate's plan, approval context and point inputs, and an effect's receipt and nested steps. */
+function refsOfStep(step: StepDefinition): StepOutputRef[] {
+  if (step.kind === "activity") return collectStepOutputRefs(step.args);
+  if (step.kind === "gate") {
+    const point = typeof step.point === "object" ? step.point.inputs : undefined;
+    return [
+      ...(isStepOutputRef(step.plan) ? [step.plan] : []),
+      ...collectStepOutputRefs(step.approval?.context),
+      ...collectStepOutputRefs(point),
+    ];
+  }
+  return [...collectStepOutputRefs(step.receipt), ...step.steps.flatMap(refsOfStep)];
+}
+
+/** Every gate step of `config` with `resume: true` that isn't at the top of a main phase. */
+function misplacedResumeGates(config: Pick<OpConfig, "phases" | "onFailure">): Array<{ phase: string; gate: GateStep }> {
+  const out: Array<{ phase: string; gate: GateStep }> = [];
+  for (const phase of config.phases) {
+    for (const step of phase.steps) {
+      if (step.kind === "effect") for (const n of step.steps) if (n.kind === "gate" && n.resume) out.push({ phase: phase.name, gate: n });
+    }
+  }
+  for (const phase of config.onFailure ?? []) {
+    for (const step of phase.steps) {
+      if (step.kind === "gate" && step.resume) out.push({ phase: phase.name, gate: step });
+      if (step.kind === "effect") for (const n of step.steps) if (n.kind === "gate" && n.resume) out.push({ phase: phase.name, gate: n });
+    }
+  }
+  return out;
+}
+
+/**
+ * The gates of `config` that resume, at the top of a main phase, in authored
+ * order, each with the outputs a checkpoint at it stores. A gate that asks a
+ * decision point, or one in an Op with a `workLease`, is left out: OPS016
+ * refuses both, and a run treats them as gates that don't resume.
+ */
+export function resumeGatesOf(config: Pick<OpConfig, "phases" | "onFailure" | "workLease">): ResumeGate[] {
+  if (config.workLease) return [];
+  const out: ResumeGate[] = [];
+  config.phases.forEach((phase, phaseIndex) => {
+    phase.steps.forEach((step, stepIndex) => {
+      if (step.kind !== "gate" || !step.resume || step.point !== undefined) return;
+      // The steps that have finished when the run reaches the gate. In a
+      // parallel phase the gates are decided before any activity starts.
+      const before = new Map<string, Producer>();
+      config.phases.forEach((p, pi) => {
+        if (pi > phaseIndex) return;
+        p.steps.forEach((s, si) => {
+          if (s.kind !== "activity" || !s.id) return;
+          if (pi === phaseIndex && (p.parallel || si >= stepIndex)) return;
+          before.set(s.id, { step: s, phaseIndex: pi, stepIndex: si });
+        });
+      });
+      const planStep = isStepOutputRef(step.plan) ? before.get(step.plan.step) : undefined;
+
+      // What reads them: the gate and every step after it, the compensation
+      // phases, the work lease, and the plan step, which runs again.
+      const after: StepDefinition[] = [
+        ...(phase.parallel ? phase.steps : phase.steps.slice(stepIndex)),
+        ...config.phases.slice(phaseIndex + 1).flatMap((p) => p.steps),
+        ...(config.onFailure ?? []).flatMap((p) => p.steps),
+        ...(planStep ? [planStep.step] : []),
+      ];
+      const crossing = after.flatMap(refsOfStep).filter((ref) =>
+        ref.step !== WORK_LEASE_STEP_ID && ref.step !== planStep?.step.id && before.has(ref.step),
+      );
+      const ids = new Set(crossing.map((r) => r.step));
+      const stored = [...before.values()]
+        .filter((p) => ids.has(p.step.id!))
+        .sort((a, b) => a.phaseIndex - b.phaseIndex || a.stepIndex - b.stepIndex)
+        .map((p) => p.step.id!);
+      out.push({ step, name: gateName(step), phaseIndex, stepIndex, ...(planStep ? { planStep } : {}), stored, crossing });
+    });
+  });
+  return out;
+}
+
+/** The step id that produced `ref`, and its activity, among the steps before `gate`. */
+function producerOf(config: Pick<OpConfig, "phases">, ref: StepOutputRef): ActivityStep | undefined {
+  for (const phase of config.phases) {
+    for (const step of phase.steps) if (step.kind === "activity" && step.id === ref.step) return step;
+  }
+  return undefined;
+}
+
+/**
+ * Why a checkpoint at `gate` can't hold what the steps after it read, or
+ * undefined when it can (#3947): a reference to an output the producer's
+ * contract marks secret. Secret outputs are never stored.
+ */
+export function checkpointBlocked(
+  config: Pick<OpConfig, "phases">,
+  gate: ResumeGate,
+  contracts: ReadonlyMap<string, Pick<ActivityContract, "secret">> | undefined,
+): string | undefined {
+  if (!contracts) return undefined;
+  for (const ref of gate.crossing) {
+    const producer = producerOf(config, ref);
+    if (producer && readsSecretOutput(contracts.get(producer.fn), ref.path)) {
+      const what = ref.path ? `output "${ref.path}"` : "output";
+      return `step "${ref.step}"'s ${what} is secret (the ${producer.fn} contract marks it), and a checkpoint never stores a secret`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * OPS016's check (#3947): what is wrong with the gates of `config` that set
+ * `resume`. A gate that resumes must sit at the top of a main phase, must not
+ * ask a decision point, must not be in an Op with a `workLease`, must name a
+ * plan step that runs before it when its plan is a reference, and must not
+ * need a secret output after it.
+ */
+export function validateGateResume(
+  config: Pick<OpConfig, "name" | "phases" | "onFailure" | "workLease">,
+  contracts?: ReadonlyMap<string, ActivityContract>,
+): ActivityContractIssue[] {
+  const issues: ActivityContractIssue[] = [];
+  const issue = (phase: string, gate: GateStep, message: string) =>
+    issues.push({ opName: config.name, phase, fn: `gate:${gateName(gate)}`, message });
+
+  for (const { phase, gate } of misplacedResumeGates(config)) {
+    issue(phase, gate, "resume is supported only on a gate at the top of a main phase, not in onFailure or inside an effect");
+  }
+  config.phases.forEach((phase) => {
+    for (const step of phase.steps) {
+      if (step.kind !== "gate" || !step.resume) continue;
+      if (config.workLease) issue(phase.name, step, "a gate can't resume in an Op that runs under a workLease");
+      if (step.point !== undefined) issue(phase.name, step, "a gate that asks a decision point can't resume");
+    }
+  });
+  for (const gate of resumeGatesOf(config)) {
+    const phase = config.phases[gate.phaseIndex]!.name;
+    if (isStepOutputRef(gate.step.plan) && !gate.planStep) {
+      issue(phase, gate.step, `its plan names step "${gate.step.plan.step}", which must be an activity that runs before the gate at the top of a main phase, so a resumed run can run it again`);
+    }
+    const blocked = checkpointBlocked(config, gate, contracts);
+    if (blocked) issue(phase, gate.step, `can't resume: ${blocked}`);
+  }
+  return issues;
+}
+
+/**
+ * Build the checkpoint a run stores when it stops at `gate`, or say why it
+ * stores none: a secret output, an unknown commit, a run id that can't name
+ * a file, or an output JSON can't hold.
+ */
+export function buildGateCheckpoint(
+  config: Pick<OpConfig, "name" | "phases">,
+  gate: ResumeGate,
+  input: {
+    runId: string;
+    commit: string | undefined;
+    environment?: string;
+    planDigest?: string;
+    outputs: ReadonlyMap<string, unknown>;
+    contracts?: ReadonlyMap<string, Pick<ActivityContract, "secret">>;
+  },
+): { checkpoint: GateCheckpoint } | { blocked: string } {
+  const secret = checkpointBlocked(config, gate, input.contracts);
+  if (secret) return { blocked: secret };
+  if (input.commit === undefined) return { blocked: "the commit this run is at could not be read, and a resumed run must be at the same one" };
+  if (!isCheckpointRunId(input.runId)) return { blocked: `the run id "${input.runId}" can't name a checkpoint file` };
+  const stored = checkpointOutputs(input.outputs, gate.stored);
+  if ("unstorable" in stored) return { blocked: `step "${stored.unstorable}"'s output can't be stored as JSON` };
+  return {
+    checkpoint: {
+      version: 1,
+      op: config.name,
+      gate: gate.name,
+      runId: input.runId,
+      commit: input.commit,
+      ...(input.environment !== undefined ? { environment: input.environment } : {}),
+      ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+      outputs: stored.outputs,
+    },
+  };
+}
+
+/** What {@link decideGateResume} found. */
+export type GateResumeDecision =
+  | { kind: "none" }
+  | { kind: "refused"; gate: string; reason: string }
+  | { kind: "resume"; gate: ResumeGate; checkpoint: GateCheckpoint; digest: string; pending: PendingGateRecord };
+
+/**
+ * Decide whether this run resumes, and at which gate. The last resume gate
+ * whose standing pending fact carries a checkpoint, and which an approval
+ * recorded since then copied, is the candidate. Approved gates are tried
+ * from the last one back, so a run that resumed at one gate and stopped at a
+ * later one resumes at the later one next time.
+ *
+ * Reads the gate ledger and the checkpoint file and writes nothing. A gate
+ * with no checkpoint, or none an approval copied, is not a candidate: the run
+ * starts at the first phase as before, and says nothing.
+ */
+export async function decideGateResume(
+  port: GateLedgerPort,
+  config: Pick<OpConfig, "name" | "phases" | "onFailure" | "workLease">,
+  input: { now: string; commit: string | undefined; environment?: string },
+): Promise<GateResumeDecision> {
+  const gates = resumeGatesOf(config);
+  if (gates.length === 0) return { kind: "none" };
+  const ledger = await port.read(config.name);
+  const spent = port.readApplied ? await port.readApplied(config.name) : [];
+  const at = (iso: string) => new Date(iso).getTime();
+
+  for (const gate of [...gates].reverse()) {
+    const standing = latestPendingGate(ledger.pending, gate.name);
+    const digest = standing?.checkpointDigest;
+    if (!standing || digest === undefined) continue;
+    // #3949: an approval carried from an alias never saw this gate's
+    // checkpoint, so it doesn't let the run resume. The run starts at the
+    // first phase and the carried approval passes the gate when it gets there.
+    const approved = ledger.resolutions.some(
+      (r) =>
+        r.gate === gate.name && r.carriedFrom === undefined && r.checkpointDigest === digest && at(r.timestamp) >= at(standing.timestamp) &&
+        samePlanDigest(r.planDigest, standing.planDigest) && !isApprovalSpent(spent, r),
+    );
+    if (!approved) continue;
+
+    const refuse = (reason: string): GateResumeDecision => ({ kind: "refused", gate: gate.name, reason });
+    if (isPendingGateExpired(standing, input.now)) return refuse(`its pending fact expired at ${standing.expiresAt}`);
+    if (!standing.runId) return refuse("its pending fact names no run");
+    const { dir, file } = gateCheckpointPath(config.name, standing.runId);
+    const text = port.readCheckpoint ? await port.readCheckpoint(config.name, standing.runId) : null;
+    if (text === null) return refuse(`the checkpoint ${dir}/${file} is not on the ledger`);
+    const checkpoint = parseGateCheckpoint(text);
+    if (checkpoint === null) return refuse(`${dir}/${file} is not a checkpoint`);
+    let actual: string;
+    try {
+      actual = gateCheckpointDigest(checkpoint);
+    } catch {
+      return refuse(`${dir}/${file} is not a checkpoint`);
+    }
+    if (actual !== digest) return refuse(`${dir}/${file} does not match the digest the approver saw (${digest}, the file is ${actual})`);
+    if (checkpoint.op !== config.name || checkpoint.gate !== gate.name || checkpoint.runId !== standing.runId) {
+      return refuse(`${dir}/${file} is for ${checkpoint.op} / ${checkpoint.gate}, run ${checkpoint.runId}`);
+    }
+    if (!samePlanDigest(checkpoint.planDigest, standing.planDigest)) return refuse(`${dir}/${file} names another plan than the pending fact`);
+    if (input.commit === undefined) return refuse("the commit this run is at could not be read");
+    if (input.commit !== checkpoint.commit) {
+      return refuse(`the run that stopped there was at commit ${checkpoint.commit.slice(0, 12)}, and this one is at ${input.commit.slice(0, 12)}`);
+    }
+    if (input.environment !== checkpoint.environment) {
+      return refuse(`the run that stopped there was for environment ${checkpoint.environment ?? "(none)"}, and this one is for ${input.environment ?? "(none)"}`);
+    }
+    const missing = gate.stored.find((id) => !(id in checkpoint.outputs));
+    if (missing !== undefined) return refuse(`${dir}/${file} holds no output for step "${missing}"`);
+    return { kind: "resume", gate, checkpoint, digest, pending: standing };
+  }
+  return { kind: "none" };
+}