@intentius/chant 0.90.0 → 0.93.0

package/src/op/activities/shell.test.ts

@@ -13,7 +13,7 @@ import { z } from "zod";
 import { shellCmd } from "./shell";
 import { shellCmdContract } from "./activity-contracts";
 import { shell } from "../builders";
-import { phase } from "../builders";
+import { activity, phase } from "../builders";
 import { collectStepOutputRefs, stepOutput, validateStepOutputRefs } from "../step-output-ref";
 import { ACTIVITY_PROFILES } from "../activity-profiles";
 import { runOpLocally } from "../local-executor";
@@ -154,3 +154,93 @@ describe("a reference reaching the command (#2414)", () => {
     expect(seen.map((s) => s.stdout)).toEqual(["db.internal", "reached db.internal"]);
   });
 });
+
+describe("structured output (#2787)", () => {
+  test("with json, stdout is parsed and published as json; empty stdout is null", async () => {
+    expect(await shellCmd({ cmd: `echo '["W-3","W-7"]'`, json: true })).toMatchObject({ stdout: '["W-3","W-7"]', json: ["W-3", "W-7"] });
+    expect(await shellCmd({ cmd: `echo '{"ids":["W-1"],"tier":"small"}'`, json: true })).toMatchObject({ json: { ids: ["W-1"], tier: "small" } });
+    expect((await shellCmd({ cmd: "true", json: true })).json).toBeNull();
+    // Without json, nothing is parsed, and there is no json field.
+    expect(await shellCmd({ cmd: `echo '[1]'` })).toEqual({ stdout: "[1]", stderr: "", exitCode: 0 });
+  });
+
+  test("stdout that is not JSON fails the step rather than reaching the next one as a string", async () => {
+    await expect(shellCmd({ cmd: "echo W-3", json: true })).rejects.toThrow(/stdout is not JSON.*W-3/);
+  });
+
+  test("an okExit code still publishes the parsed output", async () => {
+    expect(await shellCmd({ cmd: `echo '[]'; exit 3`, okExit: [0, 3], json: true })).toMatchObject({ exitCode: 3, json: [] });
+  });
+
+  test("the contract takes json, and a reference to the whole parsed value passes OPS013", () => {
+    const pick = shell("node pick.mjs", { id: "pick", json: true });
+    expect(pick.args).toEqual({ cmd: "node pick.mjs", json: true });
+    expect(shellCmdContract.args.safeParse(pick.args).success).toBe(true);
+    const contracts = new Map([["shellCmd", shellCmdContract]]);
+    const whole = activity("recordItems", { items: pick.out.json });
+    expect(validateStepOutputRefs({ name: "dispatch", phases: [phase("Pick", [pick]), phase("Build", [whole])] }, contracts)).toEqual([]);
+    expect(stepOutput(pick, "json")).toMatchObject({ step: "pick", path: "json" });
+    // The parsed value's shape is the command's, so a path under it can't be checked at build time.
+    const deeper = activity("recordItems", { items: pick.out["json.ids"] });
+    const issues = validateStepOutputRefs({ name: "dispatch", phases: [phase("Pick", [pick]), phase("Build", [deeper])] }, contracts);
+    expect(issues.map((i) => i.message)).toEqual([expect.stringMatching(/path "json.ids", which does not exist/)]);
+  });
+});
+
+describe("a step's own timeout (#2787)", () => {
+  test("shell() carries it on the step, beside the profile it keeps", () => {
+    const build = shell("./build.sh", { id: "build", timeout: "45m" });
+    expect(build).toMatchObject({ fn: "shellCmd", profile: "atMostOnce", timeout: "45m", id: "build" });
+    expect(build.args).toEqual({ cmd: "./build.sh" });
+  });
+
+  test("the executor stops the one attempt at the step's timeout, not the profile's", async () => {
+    const slow = shell("sleep 5", { timeout: "300ms" });
+    const started = Date.now();
+    const result = await runOpLocally(
+      { name: "build", overview: "", phases: [phase("Go", [slow])] },
+      new Map([["shellCmd", shellCmd as unknown as ActivityFn]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort() },
+    ).catch((err: { result?: { status: string; records: { error?: string }[] } }) => err.result!);
+    expect(Date.now() - started).toBeLessThan(4_000);
+    expect(result.status).toBe("fail");
+    expect(result.records[0].error).toMatch(/timed out after 300ms/);
+  });
+
+  test("the profile's retries are kept: a retrying profile retries each attempt under the step's timeout", async () => {
+    let calls = 0;
+    const flaky: ActivityFn = async (_args, signal) => {
+      calls++;
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 1_000);
+        signal?.addEventListener("abort", () => { clearTimeout(t); reject(new Error("aborted")); });
+      });
+      return {};
+    };
+    const result = await runOpLocally(
+      { name: "retry", overview: "", phases: [{ name: "Go", steps: [{ kind: "activity", fn: "flaky", profile: "fastIdempotent", timeout: "100ms" }] }] },
+      new Map([["flaky", flaky]]),
+      { fastIdempotent: { timeout: "10s", retry: { maximumAttempts: 2, initialInterval: "10ms" } } },
+      undefined,
+      { gates: memoryGateLedgerPort() },
+    ).catch((err: { result?: { status: string } }) => err.result!);
+    expect(result.status).toBe("fail");
+    expect(calls).toBe(2);
+  });
+
+  test("a timeout that is not a duration, or longer than six hours, fails the step at run time", async () => {
+    for (const timeout of ["forever", "7h", "0m"]) {
+      const result = await runOpLocally(
+        { name: "bad", overview: "", phases: [phase("Go", [shell("true", { timeout })])] },
+        new Map([["shellCmd", shellCmd as unknown as ActivityFn]]),
+        ACTIVITY_PROFILES,
+        undefined,
+        { gates: memoryGateLedgerPort() },
+      ).catch((err: { result?: { status: string; records: { error?: string }[] } }) => err.result!);
+      expect(result.status, timeout).toBe("fail");
+      expect(result.records[0].error, timeout).toMatch(/timeout/);
+    }
+  });
+});

package/src/op/activities/shell.ts

@@ -1,5 +1,7 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
+import { GateWait, asPendingGate } from "../gate-wait";
+import type { PendingGateRecord } from "../../lifecycle/gate-ledger";
 
 const execAsync = promisify(exec);
 
@@ -19,6 +21,33 @@ export interface ShellCmdArgs {
    * step can branch on instead of a failed Op.
    */
   okExit?: number[];
+  /**
+   * The exit code that means the command stopped at a gate of its own
+   * (#2779), such as `chant workspace upgrade`'s 3. On it the step does not
+   * fail and does not pass: the run ends `gated` at the command's gate, as it
+   * would at a pending `gate` step, and a work lease is released `gated`.
+   *
+   * The gate is read from the command's stdout when that is JSON carrying a
+   * `pending` fact, as `chant workspace upgrade --json` prints; otherwise
+   * `gate` names it, and the newest pending fact for it on the gate ledger is
+   * the one the run stops at. It is read before `okExit`, so a code in both
+   * stops the run.
+   */
+  gatedExit?: number;
+  /**
+   * The gate the command records, for `gatedExit`, when its stdout doesn't
+   * carry it: the op it is recorded under and its name, the two arguments
+   * `chant approve` takes (`{ op: "workspace-upgrade", gate: "." }`).
+   */
+  gate?: { op: string; gate: string };
+  /**
+   * Parse stdout as JSON and publish it as `json` (#2787), so a later step,
+   * or `workLease.item`, reads a list or an object rather than a string:
+   * `pick.out.json`. Stdout that is not JSON fails the step, since a value
+   * the author said was JSON and isn't would otherwise reach the next step as
+   * something else. Empty stdout is `null`.
+   */
+  json?: boolean;
 }
 
 /**
@@ -51,6 +80,20 @@ export interface ShellCmdResult {
   stdout: string;
   stderr: string;
   exitCode: number;
+  /** Stdout parsed as JSON, present when the step set `json` (#2787). */
+  json?: unknown;
+}
+
+/** `result` with its stdout parsed as JSON, when the step asked for it. */
+function withJson(result: ShellCmdResult, args: ShellCmdArgs): ShellCmdResult {
+  if (!args.json) return result;
+  if (result.stdout === "") return { ...result, json: null };
+  try {
+    return { ...result, json: JSON.parse(result.stdout) };
+  } catch (err) {
+    const shown = result.stdout.length > 200 ? `${result.stdout.slice(0, 200)}...` : result.stdout;
+    throw new Error(`the step sets json, and its stdout is not JSON (${err instanceof Error ? err.message : String(err)}): ${shown}`);
+  }
 }
 
 /** Node hangs the exit status off the error as `code`, and a signal kill as `signal`. */
@@ -78,7 +121,7 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
       signal,
     });
     if (stderr) console.error(stderr);
-    return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 };
+    return withJson({ stdout: stdout.trim(), stderr: stderr.trim(), exitCode: 0 }, args);
   } catch (err) {
     const failure = err as ExecFailure;
     const exitCode = typeof failure.code === "number" ? failure.code : undefined;
@@ -86,10 +129,15 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
     // not an exit status the author declared anything about, so it rethrows
     // even if `okExit` happens to contain the code.
     const died = failure.killed === true || typeof failure.signal === "string" || signal?.aborted === true;
+    if (exitCode !== undefined && !died && args.gatedExit !== undefined && exitCode === args.gatedExit) {
+      const stderrText = (failure.stderr ?? "").trim();
+      if (stderrText) console.error(stderrText);
+      throw new GateWait(await commandGate(args, (failure.stdout ?? "").trim(), exitCode));
+    }
     if (exitCode !== undefined && !died && okExit.includes(exitCode)) {
       const stderrText = (failure.stderr ?? "").trim();
       if (stderrText) console.error(stderrText);
-      return { stdout: (failure.stdout ?? "").trim(), stderr: stderrText, exitCode };
+      return withJson({ stdout: (failure.stdout ?? "").trim(), stderr: stderrText, exitCode }, args);
     }
     if (exitCode !== undefined && !died) {
       // `local-executor` records `error` as message text, so the code has to
@@ -99,3 +147,44 @@ export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promis
     throw failure;
   }
 }
+
+/** The pending fact a command's stdout carries: the whole of it as JSON, or its last line. */
+function pendingFromStdout(stdout: string): PendingGateRecord | undefined {
+  const lines = stdout.split("\n");
+  for (const text of [stdout, lines[lines.length - 1] ?? ""]) {
+    try {
+      const parsed = JSON.parse(text) as { pending?: unknown } | null;
+      const pending = asPendingGate(parsed?.pending);
+      if (pending) return pending;
+    } catch {
+      // Not JSON: try the next reading, then the step's own `gate`.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The gate a command stopped at (#2779): the pending fact its stdout
+ * carries, or the newest one the gate ledger holds for the step's `gate`.
+ * Throws when neither names one, since a run can't be `gated` at a gate
+ * nobody can approve.
+ */
+async function commandGate(args: ShellCmdArgs, stdout: string, exitCode: number): Promise<PendingGateRecord> {
+  const fromStdout = pendingFromStdout(stdout);
+  if (fromStdout) return fromStdout;
+  const named = args.gate;
+  if (!named) {
+    throw new Error(
+      `command exited ${exitCode}, its gatedExit, and named no gate: its stdout carries no \`pending\` gate fact as JSON, and the step has no \`gate\``,
+    );
+  }
+  const { readGateLedger, latestPendingGate } = await import("../../lifecycle/gate-ledger");
+  const { pending } = await readGateLedger(named.op, args.cwd ? { cwd: args.cwd } : undefined);
+  const latest = latestPendingGate(pending, named.gate);
+  if (!latest) {
+    throw new Error(
+      `command exited ${exitCode}, its gatedExit, but the gate ledger holds no pending fact for ${named.op} / ${named.gate}, so there is no gate to stop at`,
+    );
+  }
+  return latest;
+}

package/src/op/activities/source-release.test.ts

@@ -0,0 +1,118 @@
+/**
+ * chant #2782 — the source-release activities: a tree of HEAD archived to the
+ * same bytes every time, a release plan named by its own digest, and a release
+ * recorded in the ledger once.
+ */
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readSourceArchive } from "../source-archive";
+import { sourceArchive, releasePlan, releaseRecord, readReleasePlan, releasePlanDigest } from "./source-release";
+import { readReleaseLedger } from "../../lifecycle/release-ledger";
+import { readReleasePlan as readPersistedPlan } from "../../lifecycle/plan-ledger";
+import { appendGateResolution } from "../../lifecycle/gate-ledger";
+
+function git(args: string[], cwd: string): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+function repo(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  mkdirSync(join(dir, "app/migrations"), { recursive: true });
+  mkdirSync(join(dir, "delivery"), { recursive: true });
+  writeFileSync(join(dir, "app/server.js"), "console.log('hi');\n");
+  writeFileSync(join(dir, "app/run.sh"), "#!/bin/sh\nnode server.js\n");
+  chmodSync(join(dir, "app/run.sh"), 0o755);
+  writeFileSync(join(dir, "app/migrations/0001_init.sql"), "CREATE TABLE t (id INTEGER);\n");
+  writeFileSync(join(dir, "delivery/README.md"), "delivery\n");
+  git(["add", "-A"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("sourceArchive", () => {
+  test("archives a directory of HEAD to the same bytes each time, and reads back only at its digest", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      const cwd = join(dir, "delivery");
+      writeFileSync(join(dir, "app/uncommitted.js"), "not shipped\n");
+      const a = await sourceArchive({ path: "../app", cwd });
+      const b = await sourceArchive({ path: "../app", cwd, out: "dist/again.tar" });
+      expect(a.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+      expect(b.digest).toBe(a.digest);
+      expect(a.commit).toBe(git(["rev-parse", "HEAD"], dir));
+      expect(a.dir).toBe("app");
+      expect(a.files).toBe(3);
+      expect(a.archive).toBe(join(cwd, "dist/releases", `${a.commit}.tar`));
+
+      const files = readSourceArchive({ archive: a.archive, digest: a.digest, dir: a.dir });
+      expect(files.map((f) => f.path).sort()).toEqual(["migrations/0001_init.sql", "run.sh", "server.js"]);
+      expect(files.find((f) => f.path === "run.sh")!.executable).toBe(true);
+      expect(files.find((f) => f.path === "server.js")!.executable).toBe(false);
+      expect(files.find((f) => f.path === "server.js")!.data.toString()).toBe("console.log('hi');\n");
+
+      // Any other bytes are refused, naming both digests.
+      writeFileSync(a.archive, Buffer.concat([readFileSync(a.archive), Buffer.from("x")]));
+      expect(() => readSourceArchive({ archive: a.archive, digest: a.digest, dir: a.dir })).toThrow(/not the approved sha256:/);
+    });
+  });
+
+  test("a directory not in the commit is refused", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      await expect(sourceArchive({ path: "../nope", cwd: join(dir, "delivery") })).rejects.toThrow(/not in commit/);
+    });
+  });
+});
+
+describe("releasePlan", () => {
+  test("is named by its own canonical content, so the same release plans the same digest", async () => {
+    await withTestDir(async (dir) => {
+      const one = await releasePlan({ component: "app", env: "fly", gitSha: "abc", content: { artifact: { digest: "sha256:1" }, shipSkip: false }, cwd: dir });
+      const two = await releasePlan({ component: "app", env: "fly", gitSha: "abc", content: { shipSkip: false, artifact: { digest: "sha256:1" } }, cwd: dir });
+      expect(two.digest).toBe(one.digest);
+      const other = await releasePlan({ component: "app", env: "fly", gitSha: "abd", content: { artifact: { digest: "sha256:1" }, shipSkip: false }, cwd: dir });
+      expect(other.digest).not.toBe(one.digest);
+      const plan = readReleasePlan(one.file, one.digest);
+      expect(plan).toMatchObject({ digest: one.digest, component: "app", env: "fly", gitSha: "abc", shipSkip: false });
+      expect(releasePlanDigest(plan)).toBe(one.digest);
+      expect(() => readReleasePlan(one.file, other.digest)).toThrow(/not the approved/);
+    });
+  });
+});
+
+describe("releaseRecord", () => {
+  test("persists the plan, records the release with the gate's approver, and records a retry once", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      const gitSha = git(["rev-parse", "HEAD"], dir);
+      const plan = await releasePlan({ component: "app", env: "fly", gitSha, content: { artifact: { digest: "sha256:1" } }, cwd: dir });
+      await appendGateResolution(
+        { op: "release", gate: "ship", resolvedBy: "alice", timestamp: "2026-09-25T00:00:00Z", planDigest: plan.digest },
+        { cwd: dir },
+      );
+      const first = await releaseRecord({ plan: plan.file, digest: plan.digest, approval: { op: "release", gate: "ship" }, actor: "bob", cwd: dir });
+      expect(first).toEqual({ recorded: true, digest: plan.digest, env: "fly", component: "app", approver: "alice" });
+      const again = await releaseRecord({ plan: plan.file, digest: plan.digest, approval: { op: "release", gate: "ship" }, actor: "bob", cwd: dir });
+      expect(again.recorded).toBe(false);
+
+      const { records } = await readReleaseLedger("fly", { cwd: dir });
+      expect(records).toHaveLength(1);
+      expect(records[0]).toMatchObject({ component: "app", env: "fly", digest: plan.digest, gitSha, actor: "bob", approver: "alice" });
+      expect(await readPersistedPlan(plan.digest, { cwd: dir })).toMatchObject({ digest: plan.digest, component: "app" });
+    });
+  });
+
+  test("refuses a plan that is not the approved digest", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      const plan = await releasePlan({ component: "app", env: "fly", gitSha: "abc", content: {}, cwd: dir });
+      await expect(releaseRecord({ plan: plan.file, digest: "sha256:other", actor: "bob", cwd: dir })).rejects.toThrow(/not the approved/);
+    });
+  });
+});

package/src/op/activities/source-release.ts

@@ -0,0 +1,168 @@
+/**
+ * The release activities an Op ships a source tree with (#2782): archive the
+ * tree, plan the release, and record it once it serves.
+ *
+ * - {@link sourceArchive}: one directory of HEAD as a tar (../source-archive.ts),
+ *   named by its sha256. The same commit archives to the same bytes.
+ * - {@link releasePlan}: what a release will ship, as a JSON object named by
+ *   the sha256 of its own canonical form. The ship gate binds to that digest
+ *   (`gate("ship", { plan: plan.out.digest })`), the step that ships reads the
+ *   plan back by it, and the release ledger records it (ws-055: a release
+ *   record's digest names its plan). Nothing in a plan changes from one run of
+ *   the same commit to the next, so a retried release plans the same digest
+ *   and its approval still holds.
+ * - {@link releaseRecord}: persist the plan to `_plans/<digest>.json` on
+ *   chant/lifecycle and append the release record, as `chant components
+ *   release --release-plan` does. When the environment's latest record for
+ *   the component already names this digest, nothing is written, so a
+ *   retried release records once.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { sortedJsonReplacer } from "../../utils";
+import { archiveSourceTree, sha256Digest, type SourceArchive } from "../source-archive";
+
+// ── sourceArchive ─────────────────────────────────────────────────────────────
+
+export interface SourceArchiveArgs {
+  /** The directory to archive, relative to the Op's working directory (the app member: `../app`). */
+  path: string;
+  /** The commit. Default: HEAD. */
+  ref?: string;
+  /** Where to write the archive. Default: `dist/releases/<commit>.tar`. */
+  out?: string;
+  cwd?: string;
+}
+
+export type SourceArchiveResult = SourceArchive;
+
+/** Archive a directory of a commit (default HEAD); see ../source-archive.ts. */
+export async function sourceArchive(args: SourceArchiveArgs): Promise<SourceArchiveResult> {
+  return archiveSourceTree({ dir: args.path, ref: args.ref, out: args.out, cwd: args.cwd });
+}
+
+// ── releasePlan ───────────────────────────────────────────────────────────────
+
+export interface ReleasePlanArgs {
+  /** The component the release is recorded under. */
+  component: string;
+  /** The environment it ships to. */
+  env: string;
+  /** The commit it ships. */
+  gitSha: string;
+  /** What ships and why: the artifact, the answers the release asked, the target. Any JSON. */
+  content: Record<string, unknown>;
+  /** Where plans are written. Default: `dist/plans`. */
+  dir?: string;
+  cwd?: string;
+}
+
+export interface ReleasePlanResult {
+  /** `sha256:` of the plan's canonical JSON, without this field. */
+  digest: string;
+  /** Where the plan was written: `<dir>/<digest>.json`. (Not `path`: that name is reserved on a step's `.out`.) */
+  file: string;
+  gitSha: string;
+}
+
+/** The digest of a plan: sha256 of its canonical JSON (keys sorted), `digest` left out. Pure. */
+export function releasePlanDigest(plan: Record<string, unknown>): string {
+  const { digest: _digest, ...rest } = plan;
+  return sha256Digest(JSON.stringify(rest, sortedJsonReplacer));
+}
+
+/** Write a release plan, named by its own digest. */
+export async function releasePlan(args: ReleasePlanArgs): Promise<ReleasePlanResult> {
+  if (!args.component || !args.env || !args.gitSha) throw new Error("releasePlan: a plan names its component, its environment and its commit");
+  const body = { component: args.component, env: args.env, gitSha: args.gitSha, ...args.content };
+  const digest = releasePlanDigest(body);
+  const dir = resolve(args.cwd ?? process.cwd(), args.dir ?? join("dist", "plans"));
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${digest.replace(":", "_")}.json`);
+  writeFileSync(file, JSON.stringify({ digest, ...body }, sortedJsonReplacer, 2) + "\n");
+  return { digest, file, gitSha: args.gitSha };
+}
+
+/** A plan `releasePlan` wrote, checked against its digest. */
+export function readReleasePlan(path: string, digest?: string): Record<string, unknown> & { digest: string } {
+  const plan = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown> & { digest: string };
+  const actual = releasePlanDigest(plan);
+  if (plan.digest !== actual) throw new Error(`${path} names digest ${plan.digest}, but its content is ${actual}`);
+  if (digest !== undefined && digest !== actual) throw new Error(`${path} is plan ${actual}, not the approved ${digest}`);
+  return plan;
+}
+
+// ── releaseRecord ─────────────────────────────────────────────────────────────
+
+export interface ReleaseRecordArgs {
+  /** The plan `releasePlan` wrote. Its component, environment, commit and digest are what is recorded. */
+  plan: string;
+  /** The digest the gate approved. The plan must be that one. */
+  digest?: string;
+  /** Who approved it: the resolution bound to this digest on this Op's gate is looked up. */
+  approval?: { op: string; gate: string };
+  /** Who ran the release. Default: GITHUB_ACTOR, GITLAB_USER_LOGIN, USER. */
+  actor?: string;
+  runId?: string;
+  cwd?: string;
+}
+
+export interface ReleaseRecordResult {
+  /** False when the latest record already named this release. */
+  recorded: boolean;
+  digest: string;
+  env: string;
+  component: string;
+  approver: string | null;
+}
+
+/** Persist the plan and record the release in the ledger, once. */
+export async function releaseRecord(args: ReleaseRecordArgs): Promise<ReleaseRecordResult> {
+  const cwd = args.cwd;
+  const opts = cwd ? { cwd } : undefined;
+  const plan = readReleasePlan(resolve(cwd ?? process.cwd(), args.plan), args.digest);
+  const component = plan.component as string;
+  const env = plan.env as string;
+  const gitSha = plan.gitSha as string;
+
+  const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId } = await import("../../lifecycle/release-ledger");
+  const { persistReleasePlan } = await import("../../lifecycle/plan-ledger");
+  const { pushLifecycle } = await import("../../lifecycle/git");
+
+  let approver: string | null = null;
+  if (args.approval) {
+    const { readGateLedger } = await import("../../lifecycle/gate-ledger");
+    const { resolutions } = await readGateLedger(args.approval.op, opts);
+    const bound = resolutions.filter((r) => r.gate === args.approval!.gate && r.planDigest === plan.digest);
+    approver = bound.length > 0 ? [...new Set(bound.map((r) => r.resolvedBy))].join(", ") : null;
+  }
+
+  const latest = latestPerComponent((await readReleaseLedger(env, opts)).records).get(component);
+  if (latest?.digest === plan.digest && latest.gitSha === gitSha) {
+    await persistReleasePlan(plan, opts);
+    await pushLifecycle(opts);
+    return { recorded: false, digest: plan.digest, env, component, approver };
+  }
+
+  const actor = args.actor || process.env.GITHUB_ACTOR || process.env.GITLAB_USER_LOGIN || process.env.USER;
+  if (!actor) throw new Error("releaseRecord: no actor: pass one, or set GITHUB_ACTOR, GITLAB_USER_LOGIN or USER");
+  const { runId, runOrigin } = resolveRunId(args.runId);
+  await persistReleasePlan(plan, opts);
+  await appendReleaseRecord(
+    {
+      component,
+      env,
+      digest: plan.digest,
+      gitSha,
+      runId,
+      ...(runOrigin ? { runOrigin } : {}),
+      timestamp: new Date().toISOString(),
+      actor,
+      ...(approver ? { approver } : {}),
+    },
+    opts,
+  );
+  await pushLifecycle(opts);
+  return { recorded: true, digest: plan.digest, env, component, approver };
+}

package/src/op/activities/source-rollback.test.ts

@@ -0,0 +1,131 @@
+/**
+ * chant #2800 — the rollback activities for a source release: the release
+ * before the latest one picked from the ledger, its tree archived again and
+ * checked against the digest its plan recorded, and the rollback recorded
+ * once with the release it restores.
+ */
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sourceArchive, releasePlan, releaseRecord } from "./source-release";
+import { pickRollback, releaseRollbackPlan, releaseRollbackRecord } from "./source-rollback";
+import { readReleaseLedger, type ReleaseRecord } from "../../lifecycle/release-ledger";
+import { appendGateResolution } from "../../lifecycle/gate-ledger";
+
+function git(args: string[], cwd: string): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+function repo(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  mkdirSync(join(dir, "app"), { recursive: true });
+  mkdirSync(join(dir, "delivery"), { recursive: true });
+  writeFileSync(join(dir, "delivery/README.md"), "delivery\n");
+}
+
+/** Commit the app as `body`, then plan and record its release as the release Op does. */
+async function release(dir: string, body: string, recordedDigest?: string): Promise<{ digest: string; archive: string; gitSha: string }> {
+  writeFileSync(join(dir, "app/server.js"), body);
+  git(["add", "-A"], dir);
+  git(["commit", "-q", "-m", body], dir);
+  const cwd = join(dir, "delivery");
+  const archive = await sourceArchive({ path: "../app", cwd });
+  const plan = await releasePlan({ component: "app", env: "fly", gitSha: archive.commit, content: { artifact: { kind: "source-tree", digest: recordedDigest ?? archive.digest, dir: archive.dir } }, cwd });
+  await releaseRecord({ plan: plan.file, digest: plan.digest, actor: "releaser", cwd });
+  return { digest: plan.digest, archive: archive.digest, gitSha: archive.commit };
+}
+
+const rec = (digest: string, timestamp: string, extra: Partial<ReleaseRecord> = {}): ReleaseRecord => ({
+  version: 1,
+  component: "app",
+  env: "fly",
+  digest,
+  gitSha: digest.slice(-4),
+  runId: `run-${timestamp}`,
+  timestamp,
+  actor: "a",
+  ...extra,
+});
+
+describe("pickRollback", () => {
+  test("goes back to what the site served before the latest release, and a rollback's own record does not move it", () => {
+    const a = rec("sha256:a", "1");
+    const b = rec("sha256:b", "2");
+    expect(pickRollback([a, b], "app", "fly")).toEqual({ target: a, replaced: b });
+    // After the rollback, the same rollback is planned again.
+    const back = rec("sha256:a", "3", { restores: { env: "fly", runId: a.runId, timestamp: a.timestamp } });
+    expect(pickRollback([a, b, back], "app", "fly")).toEqual({ target: a, replaced: b });
+    // A release after the rollback goes back to what the rollback served.
+    const c = rec("sha256:c", "4");
+    expect(pickRollback([a, b, back, c], "app", "fly")).toMatchObject({ target: { digest: "sha256:a", timestamp: "3" }, replaced: c });
+    // A redeploy of the same digest is not an earlier release.
+    expect(pickRollback([a, b, rec("sha256:b", "5")], "app", "fly")).toMatchObject({ target: a });
+  });
+
+  test("names what is missing", () => {
+    expect(pickRollback([], "app", "fly")).toEqual({ error: 'no release of "app" is recorded in "fly"' });
+    expect(pickRollback([rec("sha256:a", "1")], "app", "fly")).toMatchObject({ error: expect.stringMatching(/no release in "fly" before sha256:a/) });
+    expect(pickRollback([rec("sha256:a", "1"), rec("sha256:b", "2")], "app", "fly", "sha256:z")).toMatchObject({ error: expect.stringMatching(/has digest sha256:z/) });
+    expect(pickRollback([rec("sha256:a", "1"), rec("sha256:b", "2")], "app", "fly", "sha256:a")).toMatchObject({ target: { digest: "sha256:a" } });
+  });
+});
+
+describe("releaseRollbackPlan and releaseRollbackRecord", () => {
+  test("plan the previous release with its tree archived again, record it once with the approver, and plan the same rollback after", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      const cwd = join(dir, "delivery");
+      const a = await release(dir, "console.log('a');\n");
+      const b = await release(dir, "console.log('b');\n");
+
+      const plan = await releaseRollbackPlan({ component: "app", env: "fly", cwd });
+      expect(plan).toMatchObject({ to: a.digest, from: b.digest, gitSha: a.gitSha, archiveDigest: a.archive, dir: "app" });
+      expect(plan.archive).toBe(join(cwd, "dist/releases", `${a.gitSha}.tar`));
+
+      await appendGateResolution({ op: "rollback", gate: "rollback", resolvedBy: "alice", timestamp: "2026-09-25T00:00:03Z", planDigest: plan.digest }, { cwd });
+      const first = await releaseRollbackRecord({ plan: plan.file, digest: plan.digest, approval: { op: "rollback", gate: "rollback" }, actor: "bob", cwd });
+      expect(first).toEqual({ recorded: true, digest: a.digest, env: "fly", component: "app", approver: "alice" });
+
+      const { records } = await readReleaseLedger("fly", { cwd });
+      expect(records).toHaveLength(3);
+      expect(records[2]).toMatchObject({ component: "app", digest: a.digest, gitSha: a.gitSha, actor: "bob", approver: "alice", restores: { env: "fly", runId: records[0].runId, timestamp: records[0].timestamp } });
+
+      // Again: the same plan digest, so the approval holds, and nothing more is recorded.
+      const again = await releaseRollbackPlan({ component: "app", env: "fly", cwd });
+      expect(again.digest).toBe(plan.digest);
+      expect((await releaseRollbackRecord({ plan: again.file, digest: again.digest, actor: "bob", cwd })).recorded).toBe(false);
+      expect((await readReleaseLedger("fly", { cwd })).records).toHaveLength(3);
+    });
+  });
+
+  test("a release whose tree does not archive to the digest its plan recorded is refused", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      const cwd = join(dir, "delivery");
+      await release(dir, "console.log('a');\n", "sha256:0000");
+      await release(dir, "console.log('b');\n");
+      await expect(releaseRollbackPlan({ component: "app", env: "fly", cwd })).rejects.toThrow(/archives to sha256:[0-9a-f]{64}, not the sha256:0000 release sha256:[0-9a-f]{64} recorded/);
+    });
+  });
+
+  test("a release with no recorded plan is refused by name", async () => {
+    await withTestDir(async (dir) => {
+      repo(dir);
+      writeFileSync(join(dir, "app/server.js"), "x\n");
+      git(["add", "-A"], dir);
+      git(["commit", "-q", "-m", "x"], dir);
+      const cwd = join(dir, "delivery");
+      const { appendReleaseRecord } = await import("../../lifecycle/release-ledger");
+      for (const [d, t] of [["sha256:aa", "2026-09-25T00:00:01Z"], ["sha256:bb", "2026-09-25T00:00:02Z"]]) {
+        await appendReleaseRecord({ component: "app", env: "fly", digest: d, gitSha: "abc", runId: t, timestamp: t, actor: "a" }, { cwd });
+      }
+      await expect(releaseRollbackPlan({ component: "app", env: "fly", cwd })).rejects.toThrow(/no plan is recorded for sha256:aa/);
+    });
+  });
+});