@intentius/chant 0.124.24 → 0.124.26

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

package/src/op/local-executor.test.ts

@@ -459,6 +459,71 @@ describe("runOpLocally — gate as fact (#2119)", () => {
   });
 });
 
+describe("runOpLocally — step-output references in onFailure (#3948)", () => {
+  const failing: ActivityFn = async () => { throw new Error("boom"); };
+
+  test("a compensation step receives the value a main-phase step returned", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => ({ previous: "v1" })],
+      ["migrate", failing],
+      ["restore", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] },
+        { name: "Migrate", steps: [{ kind: "activity", fn: "migrate" }] },
+      ],
+      onFailure: [{ name: "Rollback", steps: [{ kind: "activity", fn: "restore", args: { revision: stepOutput("deploy", "previous") } }] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    expect(received).toEqual([{ revision: "v1" }]);
+  });
+
+  test("a compensation step whose source step did not complete is skipped, and the record says why (A6)", async () => {
+    const ran: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", failing],
+      ["restore", async () => void ran.push("restore")],
+      ["notify", async () => void ran.push("notify")],
+    ]);
+    const config = op({
+      phases: [{ name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] }],
+      onFailure: [{ name: "Rollback", steps: [
+        { kind: "activity", fn: "restore", args: { revision: stepOutput("deploy", "previous") } },
+        { kind: "activity", fn: "notify" },
+      ] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    // The skip is not a failure of compensation: the next step still runs.
+    expect(ran).toEqual(["notify"]);
+    const restore = err.result.records.find((r: { fn: string }) => r.fn === "restore");
+    expect(restore.status).toBe("skipped");
+    expect(restore.refusal).toMatch(/step "deploy" did not complete/);
+  });
+
+  test("the skip applies in a parallel compensation phase too", async () => {
+    const ran: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", failing],
+      ["restore", async () => void ran.push("restore")],
+      ["notify", async () => void ran.push("notify")],
+    ]);
+    const config = op({
+      phases: [{ name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] }],
+      onFailure: [{ name: "Rollback", parallel: true, steps: [
+        { kind: "activity", fn: "restore", args: { revision: stepOutput("deploy") } },
+        { kind: "activity", fn: "notify" },
+      ] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(ran).toEqual(["notify"]);
+    expect(err.result.records.find((r: { fn: string }) => r.fn === "restore").status).toBe("skipped");
+  });
+});
+
 describe("runOpLocally — step-output references (#1290)", () => {
   test("a later step receives the producer's resolved value, not the placeholder", async () => {
     const received: unknown[] = [];