@intentius/chant 0.124.9 → 0.124.11

package/src/cli/main.ts

@@ -952,9 +952,14 @@ Ops:
                         --record-plans (no --wave), in a pull request's
                         pipeline: plan every wave at its head and record the
                         digests a pr-review approval mode compares
-  run resume [--op <name>]  Start again each CI job that waits at a gate an
-                        approval now answers, through the forge's API
-                        (#3683); approves nothing. --dry-run lists them
+  run resume [--op <name>] [--gate <name>]  Start again each CI job that
+                        waits at a gate an approval now answers, through the
+                        forge's API (#3683); approves nothing. --gate resumes
+                        that gate's job alone (#3854). Skips an approval a
+                        wave already applied under; restarts an apply that
+                        stopped once its run is gone (#3858). --dry-run
+                        starts nothing; with --json it says per gate whether
+                        it would resume and why
   run --generate <provider>  Write one CI pipeline file per scheduled Op for
                         github, gitlab or forgejo (#2533), from every Op that
                         declares a schedule or from --spec <file.json>.

package/src/codegen/pinned-upgrade.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, beforeAll } from "vitest";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
@@ -185,6 +185,13 @@ function makeWorkingLexicon(
 }
 
 describe("checkPinnedUpgrade — no upgrade paths", () => {
+  // The first checkPinnedUpgrade loads the k8s lexicon plugin from source, which
+  // takes 1.6s on a quiet machine and over the 5s unit budget on a loaded CI
+  // shard. beforeAll is outside the per-test budget, so pay it there once.
+  beforeAll(async () => {
+    await loadUpstreamPin("k8s");
+  }, 60_000);
+
   test("reports no upgrade when upstream equals pin", async () => {
     const root = mkdtempSync(join(tmpdir(), "chant-up-"));
     try {

package/src/codegen/publish-order.test.ts

@@ -11,9 +11,10 @@
  * import existed. Half a release shipped and the failure only surfaced from
  * npm, after the tag.
  *
- * publish-packages.sh now derives the order instead of assuming one. This
- * asserts the derivation is actually topological, so the next lexicon that
- * depends on an alphabetically earlier one fails here rather than mid-release.
+ * publish-packages.sh now derives the order instead of assuming one, as
+ * dependency layers that pack and publish in parallel (#3857). This asserts
+ * the derivation is actually topological, so the next lexicon that depends on
+ * an alphabetically earlier one fails here rather than mid-release.
  */
 
 import { describe, expect, it } from "vitest";
@@ -34,7 +35,9 @@ function ask(fn: string): string[] {
     .filter(Boolean);
 }
 
-const publishOrder = () => ask("publishable_dirs");
+/** `layer dir name version deps` rows, in publish order. */
+const publishLayers = () => ask("publish_layers").map((line) => line.split("\t"));
+const publishOrder = () => publishLayers().map((row) => row[1]);
 
 function manifest(dir: string) {
   return JSON.parse(readFileSync(join(REPO, dir, "package.json"), "utf8"));
@@ -81,6 +84,19 @@ describe("publish order", () => {
     }
   });
 
+  it("puts every package in a later layer than its dependencies", () => {
+    // #3857: a layer publishes in parallel, so a dependency in the same layer
+    // would race its dependent rather than precede it.
+    const rows = publishLayers();
+    const layer = new Map(rows.map(([l, d]) => [d, Number(l)]));
+    for (const [l, dir, name, , deps] of rows) {
+      for (const dep of deps ? deps.split(",") : []) {
+        expect(layer.get(dep), `${name} (${dir}) is in layer ${l}, not after its dependency ${dep}`)
+          .toBeLessThan(Number(l));
+      }
+    }
+  });
+
   it("puts the two packages that stranded chant-v0.34.0 after what they import", () => {
     // The specific regression, named, so the failure says what broke rather
     // than only that some invariant did.

package/src/gate-decision-bundle.test.ts

@@ -44,6 +44,7 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/notify-verify.ts",
       "packages/core/src/notify.ts",
+      "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/op-waves.ts",
       "packages/core/src/workspace/jsonc.ts",
       "packages/core/src/workspace/trust/gate-seal.ts",

package/src/gate-resume-run-bundle.test.ts

@@ -0,0 +1,49 @@
+/**
+ * The gate resume bundles small (#3854).
+ *
+ * terragucci ships one bundled file, and importing `resumeGateRun` from
+ * `@intentius/chant/op/gate-resume` brought Ajv along, through `./op/gate`
+ * and the workspace's identity rules. `@intentius/chant/gate-resume-run` holds
+ * the forge calls, the token lookup and the run locator alone. This bundles it
+ * the way terragucci would and reads esbuild's own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [/node_modules\//, /\/src\/workspace\//, /\/src\/lifecycle\//, /\/src\/cli\//, /\/src\/op\/gate\.ts$/];
+
+describe("the gate-resume-run bundle", () => {
+  test("holds the forge calls and the locator, and no package, workspace, ledger or git code", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "gate-resume-run.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/gate-resume-run.ts",
+      "packages/core/src/op/gate-run-locator.ts",
+      "packages/core/src/pr-forge.ts",
+    ]);
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(40 * 1024);
+  });
+
+  test("@intentius/chant/op/gate-resume still exports what it did", async () => {
+    const mod = await import("./op/gate-resume");
+    for (const name of ["resumeGateRun", "resumeTokenFromEnv", "resolutionAnswering", "isGateRunLocator", "resolveGateRunLocator"]) {
+      expect(typeof (mod as Record<string, unknown>)[name], name).toBe("function");
+    }
+  });
+});

package/src/gate-resume-run.ts

@@ -0,0 +1,171 @@
+/**
+ * Resume the job that waits at a gate (#3683), bundle-safe (#3854).
+ *
+ * A CI job that reaches a gate nobody approved records a pending fact on
+ * `chant/lifecycle` and exits 3. Nothing re-runs it when the approval lands,
+ * because a push to the ledger branch starts no pipeline. This module closes
+ * that loop through the forge's API.
+ *
+ * When the job runs in CI, the pending fact it records carries a
+ * {@link GateRunLocator}, read from the job's environment by
+ * {@link resolveGateRunLocator}: which forge, the API base, the repository,
+ * the run, and what the forge needs to start it again. After an approval,
+ * {@link resumeGateRun} starts it again:
+ *
+ * | Forge | Call | Token |
+ * |---|---|---|
+ * | GitHub | `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs` | `actions: write` (the job's `GITHUB_TOKEN` with that permission, or a fine-grained token with Actions read and write) |
+ * | GitLab | `POST /projects/{id}/jobs/{job}/retry` | a project or personal access token with the `api` scope and the Developer role; `CI_JOB_TOKEN` cannot retry jobs |
+ * | Forgejo | `POST /repos/{repo}/actions/workflows/{file}/dispatches` on the run's branch | a token with the `write:repository` scope; Forgejo has no API to re-run a run, so it starts a new run of the workflow |
+ *
+ * GitHub re-runs the failed job and the jobs that need it, at the same
+ * commit. GitLab retries the job, and the jobs it skipped run after it. A
+ * Forgejo dispatch runs the whole workflow again at the branch's head, so the
+ * jobs before the gate run again too; they must be safe to repeat (a wave
+ * whose runs already applied plans nothing and applies nothing new).
+ *
+ * Resuming approves nothing. The resumed job decides the gate again from the
+ * ledger, so resuming a run whose approval does not count only makes it wait
+ * again. {@link resumeGateRun} skips a run that is still going, that ended
+ * well, or that was already resumed (a later GitHub attempt, a newer GitLab
+ * job of the same name, a newer Forgejo run of the workflow), so a scheduled
+ * resume job can call it every few minutes without starting a run twice.
+ *
+ * This module imports no workspace, ledger, schema or git code, so a product
+ * that ships one bundled file (terragucci) can import it as
+ * `@intentius/chant/gate-resume-run` and resume a job in process. Which
+ * approval answers a pending fact is `./op/gate-resume.ts`'s
+ * `resolutionAnswering`, which reads the gate's quorum rules and does pull the
+ * workspace in; that module re-exports everything here.
+ */
+
+import { ForgeApiError, type ForgeFetch, type ForgeKind } from "./pr-forge";
+import type { GateRunLocator } from "./op/gate-run-locator";
+
+export { isGateRunLocator, resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
+
+/** What {@link resumeGateRun} did. */
+export type GateResumeOutcome =
+  | { status: "resumed"; forge: ForgeKind; how: string; url?: string }
+  | { status: "skipped"; forge: ForgeKind; reason: string; url?: string }
+  /** Under `dryRun` (#3858): the run is gone and would be started again; nothing was started. */
+  | { status: "would-resume"; forge: ForgeKind; how: string; url?: string };
+
+export interface ResumeGateRunOptions {
+  token: string;
+  /** The approval's time. A Forgejo run of the workflow created after it means the run was already resumed. */
+  since?: string;
+  fetch?: ForgeFetch;
+  /**
+   * Read the run as a resume would, and start nothing (#3858): say
+   * `would-resume` where it would start it. The calls are reads, so a token
+   * with read access to the forge's runs is enough.
+   */
+  dryRun?: boolean;
+}
+
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+function client(base: string, headers: Record<string, string>, fetchImpl: ForgeFetch) {
+  return async (method: string, path: string, body?: unknown): Promise<unknown> => {
+    const url = `${trimSlash(base)}${path}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    if (!res.ok) throw new ForgeApiError(method, url, res.status, text);
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  };
+}
+
+/**
+ * Start the job a pending fact's locator names again, or say why not. Throws
+ * {@link ForgeApiError} when the forge refuses a call, such as a token
+ * without the access the table in the module doc lists.
+ */
+export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOptions): Promise<GateResumeOutcome> {
+  const fetchImpl = opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch);
+  const url = loc.url ? { url: loc.url } : {};
+  const skip = (reason: string): GateResumeOutcome => ({ status: "skipped", forge: loc.forge, reason, ...url });
+  const wouldResume = (how: string): GateResumeOutcome => ({ status: "would-resume", forge: loc.forge, how: `would ${how}`, ...url });
+
+  if (loc.forge === "github") {
+    const call = client(loc.api, { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }, fetchImpl);
+    const path = `/repos/${loc.repo}/actions/runs/${loc.run}`;
+    const run = await call("GET", path);
+    if (!isObject(run)) throw new Error(`GET ${path} returned no run`);
+    if (run.status !== "completed") return skip(`run ${loc.run} is ${String(run.status)}, not finished`);
+    const attempt = typeof run.run_attempt === "number" ? run.run_attempt : undefined;
+    if (loc.attempt !== undefined && attempt !== undefined && attempt > loc.attempt) {
+      return skip(`run ${loc.run} was already re-run (attempt ${attempt}; attempt ${loc.attempt} waited)`);
+    }
+    if (run.conclusion === "success") return skip(`run ${loc.run} succeeded`);
+    if (opts.dryRun) return wouldResume(`re-run the failed jobs of run ${loc.run}`);
+    await call("POST", `${path}/rerun-failed-jobs`, {});
+    return { status: "resumed", forge: "github", how: `re-ran the failed jobs of run ${loc.run}`, ...url };
+  }
+
+  if (loc.forge === "gitlab") {
+    const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
+    const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
+    const job = await call("GET", `${project}/jobs/${loc.job}`);
+    if (!isObject(job)) throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
+    const status = String(job.status);
+    if (status === "success") return skip(`job ${loc.job} succeeded`);
+    if (!["failed", "canceled", "skipped"].includes(status)) return skip(`job ${loc.job} is ${status}, not finished`);
+    const name = loc.jobName ?? (typeof job.name === "string" ? job.name : undefined);
+    if (name) {
+      // The pipeline's jobs list leaves retried jobs out, so the job of this name is its newest try.
+      const jobs = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
+      const newest = Array.isArray(jobs) ? jobs.find((j) => isObject(j) && j.name === name) : undefined;
+      if (isObject(newest) && String(newest.id) !== String(loc.job)) {
+        return skip(`job ${loc.job} (${name}) was already retried as job ${String(newest.id)}`);
+      }
+    }
+    if (opts.dryRun) return wouldResume(`retry job ${loc.job}`);
+    const retried = await call("POST", `${project}/jobs/${loc.job}/retry`);
+    const id = isObject(retried) && retried.id !== undefined ? ` as job ${String(retried.id)}` : "";
+    return { status: "resumed", forge: "gitlab", how: `retried job ${loc.job}${id}`, ...url };
+  }
+
+  const call = client(loc.api, { Authorization: `token ${opts.token}`, Accept: "application/json" }, fetchImpl);
+  const repo = `/repos/${loc.repo}`;
+  const run = await call("GET", `${repo}/actions/runs/${loc.run}`);
+  if (!isObject(run)) throw new Error(`GET ${repo}/actions/runs/${loc.run} returned no run`);
+  const status = String(run.status);
+  if (status === "success") return skip(`run ${loc.run} succeeded`);
+  if (["waiting", "running", "blocked", "unknown"].includes(status)) return skip(`run ${loc.run} is ${status}, not finished`);
+  const listed = await call("GET", `${repo}/actions/runs?workflow_id=${encodeURIComponent(loc.workflow!)}&limit=50`);
+  const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
+  // Forgejo reports `created` in whole seconds.
+  const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
+  const later = runs.find(
+    (r) =>
+      isObject(r) && Number(r.id) > Number(loc.run) &&
+      (r.prettyref === undefined || r.prettyref === loc.ref) &&
+      (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)),
+  );
+  if (isObject(later)) return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
+  if (opts.dryRun) return wouldResume(`dispatch ${loc.workflow} on ${loc.ref}`);
+  await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref });
+  return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
+}
+
+/**
+ * The token a resume uses: `CHANT_FORGE_TOKEN`, else the forge's own
+ * (`GITHUB_TOKEN` or `GH_TOKEN` on GitHub and Forgejo, `GITLAB_TOKEN` on
+ * GitLab), the same order the pull-request loop reads (`../pr-forge.ts`).
+ */
+export function resumeTokenFromEnv(forge: ForgeKind, env: Record<string, string | undefined> = process.env): string | undefined {
+  if (env.CHANT_FORGE_TOKEN) return env.CHANT_FORGE_TOKEN;
+  return forge === "gitlab" ? env.GITLAB_TOKEN : env.GITHUB_TOKEN ?? env.GH_TOKEN;
+}

package/src/lifecycle/gate-applied.ts

@@ -19,6 +19,7 @@
 
 import { samePlanDigest } from "./plan-digest";
 import type { GateAuditApply } from "./gate-audit";
+import type { GateRunLocator } from "../op/gate-run-locator";
 
 /** One approval a wave applied under: the approval of `planDigest` made at `approvedAt` was used. */
 export interface AppliedGateRecord {
@@ -38,6 +39,37 @@ export interface AppliedGateRecord {
   review?: { pr?: number; head?: string };
   runId?: string;
   commit?: string;
+  /**
+   * Where the run applying runs (#3858), as a pending fact's `resume` names
+   * it. A line that carries one and has no {@link FinishedGateRecord} is an
+   * apply that may have stopped: `chant run resume` starts that run again
+   * once it is gone, and the wave applies the rest under the same approval.
+   */
+  resume?: GateRunLocator;
+}
+
+/**
+ * A line of `applied.jsonl` that a wave applying under an approval writes
+ * (#3858): chant's own `applied` line, or a product's `changes` line beside
+ * it (terragucci's, which names the changes the approved plans make). Both
+ * name the approval the apply ran under.
+ */
+export type AppliedGateLine = Omit<AppliedGateRecord, "kind"> & { kind: "applied" | "changes" };
+
+/**
+ * How the apply an applied line names ended, in the same file (#3858). A
+ * product writes it when the apply finishes; an apply that was killed writes
+ * none. `applied` is that line's `timestamp`.
+ */
+export interface FinishedGateRecord {
+  version: 1;
+  kind: "finished";
+  op: string;
+  gate: string;
+  planDigest: string;
+  applied: string;
+  result: "applied" | "failed";
+  timestamp: string;
 }
 
 /** Where the applied lines of `op` live on `chant/lifecycle`: the directory and the file, as `writeBlobToPath` takes them. */
@@ -67,6 +99,36 @@ export function parseAppliedGateLines(text: string): AppliedGateRecord[] {
 
 const time = (iso: string): number => new Date(iso).getTime();
 
+/**
+ * Every line of an `applied.jsonl` file a resume reads (#3858): the
+ * `applied` and `changes` lines, and the `finished` lines that say how an
+ * apply ended. Oldest first; a line that is none of them is skipped.
+ */
+export function parseAppliedGateFile(text: string): { applied: AppliedGateLine[]; finished: FinishedGateRecord[] } {
+  const applied: AppliedGateLine[] = [];
+  const finished: FinishedGateRecord[] = [];
+  for (const line of text.split("\n").map((l) => l.trim()).filter(Boolean)) {
+    let r: Record<string, unknown>;
+    try {
+      r = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (r?.version !== 1 || typeof r.gate !== "string" || typeof r.planDigest !== "string" || typeof r.timestamp !== "string") continue;
+    if ((r.kind === "applied" || r.kind === "changes") && typeof r.approvedAt === "string") {
+      applied.push({ op: "", approvedBy: "", ...r } as unknown as AppliedGateLine);
+    } else if (r.kind === "finished" && typeof r.applied === "string" && (r.result === "applied" || r.result === "failed")) {
+      finished.push({ op: "", ...r } as unknown as FinishedGateRecord);
+    }
+  }
+  return { applied, finished };
+}
+
+/** The finished line for the apply `line` names, or undefined while it has none. */
+export function finishedApply(finished: readonly FinishedGateRecord[], line: Pick<AppliedGateLine, "gate" | "planDigest" | "timestamp">): FinishedGateRecord | undefined {
+  return finished.find((f) => f.gate === line.gate && samePlanDigest(f.planDigest, line.planDigest) && time(f.applied) === time(line.timestamp));
+}
+
 /**
  * Whether an approval is spent: a wave applied under an approval of the same
  * gate and digest made at or after it. One that names no digest is never
@@ -76,7 +138,7 @@ const time = (iso: string): number => new Date(iso).getTime();
  * review not yet recorded has no `timestamp`.
  */
 export function isApprovalSpent(
-  applied: readonly AppliedGateRecord[],
+  applied: readonly Pick<AppliedGateRecord, "gate" | "planDigest" | "approvedAt" | "review">[],
   approval: { gate: string; planDigest?: string; timestamp?: string; review?: { pr?: number; head?: string } },
 ): boolean {
   const digest = approval.planDigest;

package/src/lifecycle/gate-audit.test.ts

@@ -12,6 +12,12 @@ const resolution = (o: Record<string, unknown> = {}) =>
 const ledger = (op: string, ...texts: string[]) => ({ op, lines: texts.map((text) => ({ text })) });
 
 describe("lifecycle/gate-audit", () => {
+  test("a pending fact's wave is surfaced (#3839)", () => {
+    const { entries } = deriveGateAudit({ ledgers: [ledger("tf-apply", pending({ wave: { number: 2, name: "prod", op: "tg" } }))] });
+    expect(entries[0]).toMatchObject({ wave: { number: 2, name: "prod", op: "tg" } });
+    expect(entries[0]!.detail).not.toHaveProperty("wave");
+  });
+
   test("a request, then an approval with its seal and approver", () => {
     const seal = { signer: "alex", key: "SHA256:k", signature: "-----BEGIN" };
     const { entries, gaps } = deriveGateAudit({

package/src/lifecycle/gate-audit.ts

@@ -191,6 +191,8 @@ export interface GateAuditEntry {
   runId?: string;
   expiresAt?: string;
   description?: string;
+  /** Pending facts an op wave wrote for a policy denial or a hold (#3839): the wave they belong to. */
+  wave?: { number: number; name: string; op?: string };
   /** Overrides: the rules the denial named (from the denial line when there is one). */
   rules?: string[];
   /** A revoked entry: what was revoked. */
@@ -239,9 +241,13 @@ type Row = Record<string, unknown>;
 
 const KNOWN = new Set([
   "version", "kind", "op", "gate", "resolvedBy", "relayedBy", "timestamp", "note", "url", "planDigest", "environment",
-  "approver", "seal", "review", "runId", "expiresAt", "description", "rules", "pr", "head", "reviewers",
+  "approver", "seal", "review", "runId", "expiresAt", "description", "wave", "rules", "pr", "head", "reviewers",
 ]);
 
+const waveOf = (v: unknown): { number: number; name: string; op?: string } | undefined => {
+  const w = v as { number?: unknown; name?: unknown; op?: unknown } | null;
+  return w && typeof w === "object" && typeof w.number === "number" && typeof w.name === "string" ? { number: w.number, name: w.name, ...(typeof w.op === "string" ? { op: w.op } : {}) } : undefined;
+};
 const str = (v: unknown): string | undefined => (typeof v === "string" && v !== "" ? v : undefined);
 const strings = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : undefined);
 const time = (iso: string): number => Date.parse(iso) || 0;
@@ -353,7 +359,7 @@ export function deriveGateAudit(input: GateAuditInput): { entries: GateAuditEntr
           ...base,
           kind: override ? "override-requested" : "approval-requested",
           at: String(r.timestamp),
-          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules) }),
+          ...drop({ runId: str(r.runId), expiresAt: str(r.expiresAt), description: str(r.description), url: str(r.url), rules: strings(r.rules), wave: waveOf(r.wave) }),
           detail: extra,
         }));
         continue;

package/src/lifecycle/gate-ledger.test.ts

@@ -446,7 +446,13 @@ describe("gate ledger newline termination (#3849)", () => {
   test("every append ends the file in a newline, with no blank or merged lines", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
-      await appendPendingGate({ op: "nl-op", gate: "g1", planDigest: "sha256:" + "a".repeat(64) } as never, { cwd: dir });
+      await appendPendingGate(
+        {
+          op: "nl-op", gate: "g1", planDigest: "sha256:" + "a".repeat(64),
+          timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-08T00:00:00.000Z",
+        },
+        { cwd: dir },
+      );
       const one = await readBlobFromPath("_gates", "nl-op.jsonl", { cwd: dir });
       expect(one!.endsWith("\n")).toBe(true);
       await appendGateResolution(

package/src/lifecycle/gate-ledger.ts

@@ -45,7 +45,7 @@ import { isNeverOverMcpGateOp } from "../op/gate-name";
 import { sortedJsonReplacer } from "../utils";
 import { currentGateOrigin, type GateOrigin } from "./gate-origin";
 import type { GateApprover, GatePolicyDecision, ResolvedGateApproval } from "../op/gate-approval";
-import type { GateRunLocator } from "../op/gate-resume";
+import type { GateRunLocator } from "../op/gate-run-locator";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
 
 // The facts a pending record is written with live apart, so a bundle can import them without git (#3816).

package/src/op/gate-resume-plan-bundle.test.ts

@@ -0,0 +1,49 @@
+/**
+ * The resume plan bundles small (#3858).
+ *
+ * A product that resumes in its own job, such as terragucci's, decides what
+ * to resume with `@intentius/chant/op/gate-resume-plan` and ships as one
+ * bundled file. This bundles it the way such a product would and reads
+ * esbuild's own list of what went in: no git ledger, no gate evaluation, no
+ * workspace, CLI or Ajv code.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "../workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [
+  /node_modules\//,
+  /\/src\/cli\//,
+  /\/src\/workspace\//,
+  /\/src\/fold\//,
+  /\/src\/lint\//,
+  /\/src\/codegen\//,
+  /\/src\/op\/activities\//,
+  /\/src\/op\/gate\.ts$/,
+  /\/src\/op\/gate-resume\.ts$/,
+  /\/src\/lifecycle\/git\.ts$/,
+  /\/src\/lifecycle\/gate-ledger\.ts$/,
+];
+
+describe("the gate-resume-plan bundle", () => {
+  test("holds the resume decision and its pure helpers only", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "op", "gate-resume-plan.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(32 * 1024);
+  });
+});

package/src/op/gate-resume-plan.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "vitest";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { parseAppliedGateFile } from "../lifecycle/gate-applied";
+import { planGateResumes } from "./gate-resume-plan";
+import type { GateRunLocator } from "./gate-run-locator";
+
+const DIGEST = `sha256:${"a".repeat(64)}`;
+const OTHER = `sha256:${"b".repeat(64)}`;
+const NOW = "2026-10-01T06:00:00Z";
+const waited: GateRunLocator = { forge: "github", api: "https://api.github.com", repo: "acme/infra", run: "42", attempt: 1 };
+const applying: GateRunLocator = { forge: "github", api: "https://api.github.com", repo: "acme/infra", run: "57", attempt: 1 };
+
+const pending = (gate: string, timestamp: string, extra: Partial<PendingGateRecord> = {}): PendingGateRecord => ({
+  version: 1,
+  kind: "pending",
+  op: "tf-apply",
+  gate,
+  timestamp,
+  expiresAt: "2026-10-03T00:00:00Z",
+  planDigest: DIGEST,
+  resume: waited,
+  ...extra,
+});
+const approval = (gate: string, timestamp: string, by = "alice"): GateResolutionRecord => ({ version: 1, op: "tf-apply", gate, resolvedBy: by, timestamp, planDigest: DIGEST });
+
+const file = (...lines: object[]) => parseAppliedGateFile(lines.map((l) => JSON.stringify(l)).join("\n"));
+const appliedLine = (gate: string, approvedAt: string, timestamp: string, extra: Record<string, unknown> = {}) => ({
+  version: 1, kind: "applied", op: "tf-apply", gate, planDigest: DIGEST, approvedAt, approvedBy: "alice", timestamp, ...extra,
+});
+
+describe("planGateResumes (#3858)", () => {
+  test("an approval that answers a standing fact and is not spent: resumable, approved", () => {
+    const [c] = planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], now: NOW });
+    expect(c).toMatchObject({ source: "pending", gate: "wave-1", resumable: true, reason: "approved", approvedBy: "alice", approvedAt: "2026-10-01T01:00:00Z", run: waited });
+  });
+
+  test("nothing answers it: not resumable", () => {
+    expect(planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [], now: NOW })).toMatchObject([
+      { resumable: false, reason: "not-approved" },
+    ]);
+  });
+
+  test("an approval a wave already applied under is spent: not resumable, and the report names the apply", () => {
+    const lines = file(appliedLine("wave-1", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z", { wave: { number: 1, name: "network" } }));
+    const [c] = planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], ...lines, now: NOW });
+    expect(c).toMatchObject({ resumable: false, reason: "spent", spent: { appliedAt: "2026-10-01T02:00:00Z", approvedAt: "2026-10-01T01:00:00Z", wave: { number: 1 } } });
+    expect(c!.message).toContain("spent");
+  });
+
+  test("a spent approval of another digest, or an older one, spends nothing here", () => {
+    const lines = file(appliedLine("wave-1", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z", { planDigest: OTHER }), appliedLine("wave-1", "2026-09-30T00:00:00Z", "2026-09-30T01:00:00Z"));
+    const [c] = planGateResumes({ op: "tf-apply", pending: [pending("wave-1", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], ...lines, now: NOW });
+    expect(c).toMatchObject({ resumable: true, reason: "approved" });
+  });
+
+  test("a decision point's answer the gate passes on: answered, unless the resolution citing it is spent", () => {
+    const answer = { point: "prod-apply", id: "q-1", path: "points/q-1.json" };
+    const fact = pending("wave-1", "2026-10-01T00:00:00Z", { answer });
+    const questions = new Map([["q-1", { id: "q-1", state: "answered" as const, answer: true, answeredBy: ["alice"], answeredOn: "2026-10-01T01:00:00Z" }]]);
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [], questions, now: NOW })).toMatchObject([{ resumable: true, reason: "answered", approvedBy: "alice" }]);
+
+    const cited: GateResolutionRecord = { ...approval("wave-1", "2026-10-01T03:00:00Z", "alice"), answer };
+    const lines = file(appliedLine("wave-1", "2026-10-01T03:00:00Z", "2026-10-01T03:00:01Z"));
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [cited], ...lines, questions, now: NOW })).toMatchObject([{ resumable: false, reason: "spent" }]);
+  });
+
+  test("an apply that recorded its run and never finished is a stopped apply", () => {
+    // terragucci's shape: chant's `applied` line, then the product's `changes` line with the run.
+    const lines = file(
+      appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z"),
+      appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:01Z", { kind: "changes", resume: applying, changes: [{ address: "aws_s3_bucket.a" }] }),
+    );
+    const out = planGateResumes({ op: "tf-apply", pending: [pending("wave-2", "2026-10-01T00:00:00Z")], resolutions: [approval("wave-2", "2026-10-01T01:00:00Z")], ...lines, now: NOW });
+    expect(out).toMatchObject([
+      { source: "pending", reason: "spent", resumable: false },
+      { source: "stopped", gate: "wave-2", reason: "stopped", resumable: true, run: applying, approvedBy: "alice", stopped: { appliedAt: "2026-10-01T02:00:01Z", approvedAt: "2026-10-01T01:00:00Z", kind: "changes" } },
+    ]);
+  });
+
+  test("a finished line, a newer pending fact, or no run locator: not a stopped apply", () => {
+    const changes = appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:01Z", { kind: "changes", resume: applying });
+    const finished = { version: 1, kind: "finished", op: "tf-apply", gate: "wave-2", planDigest: DIGEST, applied: "2026-10-01T02:00:01Z", result: "failed", timestamp: "2026-10-01T02:30:00Z" };
+    const stopped = (lines: ReturnType<typeof file>, p: PendingGateRecord[] = []) =>
+      planGateResumes({ op: "tf-apply", pending: p, resolutions: [], ...lines, now: NOW }).filter((c) => c.source === "stopped");
+    expect(stopped(file(changes))).toHaveLength(1);
+    expect(stopped(file(changes, finished))).toEqual([]);
+    expect(stopped(file(changes), [pending("wave-2", "2026-10-01T03:00:00Z")])).toEqual([]);
+    expect(stopped(file(appliedLine("wave-2", "2026-10-01T01:00:00Z", "2026-10-01T02:00:00Z")))).toEqual([]);
+    // A newer apply under another approval, with no run, supersedes the stopped one.
+    expect(stopped(file(changes, appliedLine("wave-2", "2026-10-01T04:00:00Z", "2026-10-01T05:00:00Z")))).toEqual([]);
+  });
+
+  test("a gate filter, and an expired fact, leave facts out", () => {
+    const facts = [pending("wave-1", "2026-10-01T00:00:00Z"), pending("wave-2", "2026-10-01T00:00:00Z", { expiresAt: "2026-10-01T05:00:00Z" })];
+    expect(planGateResumes({ op: "tf-apply", pending: facts, resolutions: [], now: NOW }).map((c) => c.gate)).toEqual(["wave-1"]);
+    expect(planGateResumes({ op: "tf-apply", pending: facts, resolutions: [], now: NOW, gate: "wave-2" })).toEqual([]);
+  });
+
+  test("a fact with an approval block needs the tally to be answered", () => {
+    const fact = pending("wave-1", "2026-10-01T00:00:00Z", { approval: { mode: "off" } as unknown as PendingGateRecord["approval"] });
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [approval("wave-1", "2026-10-01T01:00:00Z")], now: NOW })).toMatchObject([
+      { resumable: false, reason: "not-approved", message: expect.stringContaining("tally") },
+    ]);
+    const answering = () => approval("wave-1", "2026-10-01T01:00:00Z");
+    expect(planGateResumes({ op: "tf-apply", pending: [fact], resolutions: [], now: NOW, answering })).toMatchObject([{ resumable: true, reason: "approved" }]);
+  });
+});