@intentius/chant 0.124.25 → 0.124.26

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" };
+}

package/src/op/gate.ts

@@ -55,6 +55,8 @@ import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requ
 import { parseDuration } from "./duration";
 import { resolveGateRunLocator } from "./gate-run-locator";
 import { refuseGateWithoutRecording } from "../lifecycle/no-record";
+import { gateCheckpointDigest, gateCheckpointText, readGateCheckpointText, writeGateCheckpoint, type GateCheckpoint } from "../lifecycle/gate-checkpoint";
+import type { ResolvedGateAlias } from "./gate-alias";
 
 /**
  * What appending a pending fact learned about reaching the remote.
@@ -100,6 +102,15 @@ export interface GateLedgerPort {
   readApplied?(op: string): Promise<AppliedGateRecord[]>;
   /** Record that a wave is about to apply under an approval (#3784), which spends it. */
   appendApplied?(record: AppliedGateRecord): Promise<{ pushed: boolean; pushWarning?: string }>;
+  /**
+   * Store the checkpoint of a run that stops at a gate that resumes (#3947),
+   * at `_gates/<op>/checkpoints/<runId>.json`. Written before the pending
+   * fact that names its digest, and pushed with it. Absent on a port that
+   * keeps none, and the gate then doesn't resume.
+   */
+  writeCheckpoint?(checkpoint: GateCheckpoint): Promise<void>;
+  /** The text of a run's checkpoint, or null when there is none (#3947). */
+  readCheckpoint?(op: string, runId: string): Promise<string | null>;
 }
 
 /** A workspace's rule for which approvals of a gate count (#3163): a signed approval, from a class when it names one. */
@@ -148,6 +159,13 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { record } = await appendPendingGate(input, opts);
       return { record, ...(await pushLifecycleReport(opts)) };
     },
+    async writeCheckpoint(checkpoint) {
+      await writeGateCheckpoint(checkpoint, opts);
+    },
+    async readCheckpoint(op, runId) {
+      await requireLifecycleLedger(opts);
+      return readGateCheckpointText(op, runId, opts);
+    },
     async readApplied(op) {
       await requireLifecycleLedger(opts);
       const { dir, file } = appliedGatePath(op);
@@ -181,16 +199,30 @@ 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[]; applied?: AppliedGateRecord[] } = {},
-): GateLedgerPort & { appended: PendingGateRecord[]; resolved: GateResolutionRecord[]; applied: AppliedGateRecord[] } {
+): GateLedgerPort & {
+  appended: PendingGateRecord[];
+  resolved: GateResolutionRecord[];
+  applied: AppliedGateRecord[];
+  /** Checkpoint texts by `<op>/<runId>` (#3947). */
+  checkpoints: Map<string, string>;
+} {
   const resolutions = [...(seed.resolutions ?? [])];
   const pending = [...(seed.pending ?? [])];
   const appended: PendingGateRecord[] = [];
   const resolved: GateResolutionRecord[] = [];
   const applied: AppliedGateRecord[] = [...(seed.applied ?? [])];
+  const checkpoints = new Map<string, string>();
   return {
     appended,
     resolved,
     applied,
+    checkpoints,
+    async writeCheckpoint(checkpoint) {
+      checkpoints.set(`${checkpoint.op}/${checkpoint.runId}`, gateCheckpointText(checkpoint));
+    },
+    async readCheckpoint(op, runId) {
+      return checkpoints.get(`${op}/${runId}`) ?? null;
+    },
     async readApplied(op) {
       return applied.filter((a) => a.op === op);
     },
@@ -271,6 +303,24 @@ export interface GateCheckInput {
   fields?: Record<string, unknown>;
   /** The pending fact it records carries `neverOverMcp` (#3821, chant#3485). */
   neverOverMcp?: boolean;
+  /**
+   * The checkpoint of a run at a gate that resumes (#3947). Given, a pending
+   * fact this records first stores it through the port's `writeCheckpoint`
+   * and carries its digest as `checkpointDigest`. A standing fact with no
+   * checkpoint is recorded again, so the gate gets one.
+   */
+  checkpoint?: GateCheckpoint;
+  /**
+   * The gate's old names (#3949), each with its Op filled in
+   * (`resolveGateAliases` in `./gate-alias.ts`). Read only on a gate bound
+   * to a plan. A person's approval recorded under one counts toward this
+   * gate when it answers that name's standing pending fact, the fact hasn't
+   * expired, it is for `planDigest` and `environment`, neither name has
+   * spent it, and it passes this gate's approval rule. An approval this
+   * counts is written again under this gate (`carriedFrom`), and a line
+   * carried earlier counts only while its alias is still declared.
+   */
+  aliases?: readonly ResolvedGateAlias[];
 }
 
 /**
@@ -335,11 +385,14 @@ export type GateCheck =
       /**
        * Set on a gate that declares `approval` (#2508). `"quorum"` when enough
        * human approvals were recorded, `"policy"` when an `enforce`-mode permit
-       * passed it on its own.
+       * passed it on its own. `"alias"` (#3949) when an approval recorded
+       * under one of the gate's aliases counted, on any gate.
        */
-      via?: "quorum" | "policy";
+      via?: "quorum" | "policy" | "alias";
       /** Every approval that counted toward the quorum. Set with `via`. */
       approvals?: GateResolutionRecord[];
+      /** The approvals this run carried from an alias and wrote under the gate's name (#3949). Set when `via` is `"alias"`. */
+      carried?: GateResolutionRecord[];
     }
   | {
       satisfied: false;
@@ -500,6 +553,103 @@ export function humanQuorumSince(pending: readonly PendingGateRecord[], standing
   return anchor.timestamp;
 }
 
+/**
+ * The approvals that answer `standing` (#3949): of its gate, environment and
+ * plan, recorded since it, or on a gate with an `approval` block since the
+ * human quorum's anchor ({@link humanQuorumSince}). The rule
+ * `resolutionAnswering` (`./gate-resume.ts`) decides by, without the tally:
+ * each one counts on its own toward a gate an alias names.
+ */
+export function approvalsAnswering(
+  resolutions: readonly GateResolutionRecord[],
+  standing: PendingGateRecord,
+  pending: readonly PendingGateRecord[] = [standing],
+): GateResolutionRecord[] {
+  const since = new Date(standing.approval ? humanQuorumSince(pending, standing) : standing.timestamp).getTime();
+  return resolutions.filter(
+    (r) =>
+      r.gate === standing.gate && r.environment === standing.environment && samePlanDigest(r.planDigest, standing.planDigest) &&
+      new Date(r.timestamp).getTime() >= since,
+  );
+}
+
+/**
+ * The line a run writes for an approval it carries from an alias (#3949):
+ * the approval under `op`/`gate` at `now`, citing the line it came from.
+ * The approver, plan, environment, relay and seal are the original's. A
+ * policy decision is left behind, since it was evaluated against another
+ * gate, and so is a checkpoint digest, which moves onto `carriedFrom`: the
+ * approver saw that checkpoint, not one this gate stores, so a carried
+ * approval never lets a run resume.
+ */
+export function carriedApproval(r: GateResolutionRecord, op: string, gate: string, now: string): GateResolutionInput {
+  return {
+    op,
+    gate,
+    resolvedBy: r.resolvedBy,
+    ...(r.relayedBy !== undefined ? { relayedBy: r.relayedBy } : {}),
+    timestamp: now,
+    ...(r.note ? { note: r.note } : {}),
+    ...(r.url ? { url: r.url } : {}),
+    ...(r.planDigest !== undefined ? { planDigest: r.planDigest } : {}),
+    ...(r.environment !== undefined ? { environment: r.environment } : {}),
+    ...(r.origin ? { origin: r.origin } : {}),
+    ...(r.sameOriginOverride ? { sameOriginOverride: true } : {}),
+    approver: approverOf(r),
+    ...(r.seal ? { seal: r.seal } : {}),
+    carriedFrom: {
+      op: r.op,
+      gate: r.gate,
+      timestamp: r.timestamp,
+      ...(r.checkpointDigest !== undefined ? { checkpointDigest: r.checkpointDigest } : {}),
+    },
+  };
+}
+
+/**
+ * The approvals recorded under `input.aliases` that may count toward this
+ * gate (#3949), oldest first. Each answers its alias's standing pending
+ * fact, which hasn't expired and was recorded for this plan and
+ * environment. Each is a person's, is spent under neither name, hasn't been
+ * carried already (`ledger` is this gate's own, so a carried line that was
+ * spent keeps its original from being carried again), and passes `rule`,
+ * whose seal check reads the names the approval was signed under. One the
+ * rule refuses is added to `refused`.
+ */
+async function aliasApprovals(
+  port: GateLedgerPort,
+  input: GateCheckInput & { aliases: readonly ResolvedGateAlias[] },
+  ledger: readonly GateResolutionRecord[],
+  rule: GateApprovalRule | null,
+  now: string,
+  refused: GateRefusedApproval[],
+): Promise<GateResolutionRecord[]> {
+  const at = (iso: string) => new Date(iso).getTime();
+  const carried = ledger.filter((r) => r.gate === input.gate && r.carriedFrom !== undefined);
+  const wasCarried = (r: GateResolutionRecord) =>
+    carried.some((c) => c.carriedFrom!.op === r.op && c.carriedFrom!.gate === r.gate && at(c.carriedFrom!.timestamp) === at(r.timestamp) && c.resolvedBy === r.resolvedBy);
+  const ledgers = new Map<string, Awaited<ReturnType<GateLedgerPort["read"]>>>();
+  const out: GateResolutionRecord[] = [];
+  for (const alias of input.aliases) {
+    let other = ledgers.get(alias.op);
+    if (!other) ledgers.set(alias.op, (other = await port.read(alias.op)));
+    const pending = other.pending.filter((p) => p.environment === input.environment);
+    const standing = latestPendingGate(pending, alias.gate);
+    if (!standing || isPendingGateExpired(standing, now) || !samePlanDigest(standing.planDigest, input.planDigest)) continue;
+    const spent = alias.op === input.op && input.spent ? input.spent : ((await port.readApplied?.(alias.op)) ?? []);
+    for (const r of approvalsAnswering(other.resolutions, standing, pending)) {
+      if (r.carriedFrom !== undefined || approverOf(r).kind !== "human" || isApprovalSpent(spent, r) || wasCarried(r)) continue;
+      const reason = rule?.refuses(r) ?? null;
+      if (reason !== null) {
+        refused.push({ resolution: r, reason: `carried from ${alias.op}/${alias.gate}: ${reason}` });
+        continue;
+      }
+      out.push(r);
+    }
+  }
+  return out.sort((a, b) => at(a.timestamp) - at(b.timestamp));
+}
+
 /** Whether two resolved approval blocks are the same, so a standing pending fact still describes this gate. */
 function sameApproval(a: ResolvedGateApproval | undefined, b: ResolvedGateApproval | undefined): boolean {
   return JSON.stringify(a ?? null, sortedJsonReplacer) === JSON.stringify(b ?? null, sortedJsonReplacer);
@@ -546,6 +696,9 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   const rule = (await port.approvalRule?.(input.gate)) ?? null;
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;
+  // #3949: aliases admit only approvals of this run's plan, and carrying one writes a line.
+  const aliases = input.planDigest !== undefined && port.appendResolution ? (input.aliases ?? []) : [];
+  const aliased = (from: { op: string; gate: string }) => aliases.some((a) => a.op === from.op && a.gate === from.gate);
   // #3841: an approval of this plan the rule refuses is named, so a wait says why.
   const refused: GateRefusedApproval[] = [];
   const resolutions = (
@@ -553,6 +706,8 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       ? ledger.resolutions
       : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)
   )
+    // #3949: a carried approval counts only while the gate still names its alias.
+    .filter((r) => r.gate !== input.gate || r.carriedFrom === undefined || aliased(r.carriedFrom))
     .filter((r) => input.spent === undefined || r.gate !== input.gate || !isApprovalSpent(input.spent, r))
     .filter((r) => {
       if (rule === null || r.gate !== input.gate) return true;
@@ -561,8 +716,16 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
       if (samePlanDigest(r.planDigest, input.planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime()) refused.push({ resolution: r, reason });
       return false;
     });
+  const fromAliases = aliases.length > 0 ? await aliasApprovals(port, { ...input, aliases }, ledger.resolutions, rule, now, refused) : [];
   refused.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime());
 
+  // #3949: write the approvals that counted from an alias under this gate.
+  const carry = async (records: readonly GateResolutionRecord[]): Promise<GateResolutionRecord[]> => {
+    const written: GateResolutionRecord[] = [];
+    for (const r of records) written.push((await port.appendResolution!(carriedApproval(r, input.op, input.gate, now))).record);
+    return written;
+  };
+
   let mismatched: GateResolutionRecord | undefined;
   let quorum: GateQuorumProgress | undefined;
   if (input.approval) {
@@ -587,9 +750,28 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     }
     mismatched = tally.mismatched;
     quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need };
+    // #3949: old and new approvals add up toward one quorum, each approver once.
+    const counted = new Set(tally.counted.map((r) => r.resolvedBy));
+    const extra = fromAliases.filter((r) => !counted.has(r.resolvedBy));
+    if (extra.length > 0) {
+      const asCarried = new Map(extra.map((r) => [{ version: 1, ...carriedApproval(r, input.op, input.gate, now) } as GateResolutionRecord, r]));
+      const combined = tallyGateApprovals([...resolutions, ...asCarried.keys()], input.gate, since, input.planDigest, input.approval, humansSince);
+      if (combined.counted.length >= combined.need) {
+        const written = await carry(combined.counted.filter((r) => asCarried.has(r)).map((r) => asCarried.get(r)!));
+        const approvals = [...combined.counted.filter((r) => !asCarried.has(r)), ...written];
+        return { satisfied: true, resolution: written[written.length - 1]!, via: "alias", approvals, carried: written };
+      }
+      quorum = { approvers: combined.counted.map((r) => r.resolvedBy), need: combined.need };
+    }
   } else {
     const found = latestResolutionForPlan(resolutions, input.gate, since, input.planDigest);
     if (found.resolution) return { satisfied: true, resolution: found.resolution };
+    // #3949: else the newest approval an alias admits passes it, written under this gate.
+    const newest = fromAliases[fromAliases.length - 1];
+    if (newest) {
+      const written = await carry([newest]);
+      return { satisfied: true, resolution: written[0]!, via: "alias", carried: written };
+    }
     mismatched = found.mismatched;
   }
 
@@ -614,13 +796,24 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // The same holds for the approval block (#2508): a pending fact recorded
   // under another policy version or another context would have `chant
   // approve` evaluate the policy against something this run no longer has.
+  // #3947: and for the checkpoint, so a gate that resumes gets one. A fact
+  // that already carries a checkpoint stands: an approval copies that one.
   if (
     standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) &&
-    sameApproval(standing.approval, input.approval)
+    sameApproval(standing.approval, input.approval) &&
+    (input.checkpoint === undefined || port.writeCheckpoint === undefined || standing.checkpointDigest !== undefined)
   ) {
     return { satisfied: false, pending: standing, recorded: false, ...asMismatch };
   }
 
+  // The checkpoint is written before the fact that names it, so a fact never
+  // points at a file that isn't there.
+  let checkpointDigest: string | undefined;
+  if (input.checkpoint !== undefined && port.writeCheckpoint) {
+    checkpointDigest = gateCheckpointDigest(input.checkpoint);
+    await port.writeCheckpoint(input.checkpoint);
+  }
+
   const url = resolveApprovalUrl();
   // #3683: in CI, where this job runs, so an approval can start it again.
   const resume = resolveGateRunLocator();
@@ -637,6 +830,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(url ? { url } : {}),
     ...(resume ? { resume } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+    ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
     ...(env !== undefined ? { environment: env } : {}),
     ...(input.approval ? { approval: input.approval } : {}),
     ...(input.neverOverMcp ? { neverOverMcp: true as const } : {}),

package/src/op/index.ts

@@ -156,9 +156,12 @@ export type {
 export { renderHuman, renderJson } from "./local-output";
 export {
   activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES,
-  pathExistsInSchema,
+  pathExistsInSchema, readsSecretOutput,
 } from "./activity-contract";
 export type { ActivityContract, ActivityContractIssue } from "./activity-contract";
+export { validateGateResume, resumeGatesOf, decideGateResume } from "./gate-checkpoint";
+export type { ResumeGate, GateResumeDecision } from "./gate-checkpoint";
+export type { GateCheckpoint } from "../lifecycle/gate-checkpoint";
 export { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope, makeOutProxy } from "./step-output-ref";
 export type { StepOutputRef, WithStepRefs } from "./step-output-ref";
 export type { NamedActivityStep } from "./builders";