@intentius/chant 0.57.0 → 0.59.0

package/src/lifecycle/gate-ledger.ts

@@ -15,26 +15,24 @@
  * second non-env top-level directory.
  *
  * `chant approve <op> <gate>` (`../cli/handlers/operator.ts`) is what
- * appends here — issue #1485's "resolution is an out-of-band act that
- * writes the counterpart fact". Per the issue's own leaning on open
+ * appends a resolution — issue #1485's "resolution is an out-of-band act
+ * that writes the counterpart fact". Per that issue's leaning on open
  * question 3 ("local trust in v1, signature as an additive follow-up"),
  * this record is *not* itself an authorization check — anyone who can run
  * `chant approve` locally can write one, the same trust boundary a local
- * `git commit` already has. What it changes: `chant operator status` (and
- * any future gate-aware dispatch retry) can tell a resolved gate from a
- * still-pending one by finding a resolution newer than the tick that
- * recorded it. It does **not** (v1) retroactively make a gated op's local
- * dispatch succeed — the local executor still refuses any op containing a
- * gate outright (`../op/local-executor.ts`'s `LocalGateUnsupportedError`),
- * unconditionally, gate resolution or not. Wiring an approved gate back
- * into the local executor's dispatch path is the GateStep semantic change
- * issue #1485 itself flags as open question 1 ("suspension → fact... does
- * it land as its own issue first? Leaning: yes, split it out") — deferred
- * here for the same reason the issue defers it: it touches both the local
- * executor and the generated Temporal workflow, and has migration impact on
- * shipped ops. `chant approve` in v1 is the durable, queryable record of
- * "this gate is cleared" that a human (or a future auto-resume path) reads;
- * it is not itself the unblock.
+ * commit already has.
+ *
+ * Since #2119 the file carries both halves of the loop. A `gate` step the
+ * local executor reaches (`../op/local-executor.ts`) appends a
+ * {@link PendingGateRecord} and ends that run with status `gated`; `chant
+ * approve` appends the {@link GateResolutionRecord} that answers it; the next
+ * run reads both, finds a resolution newer than the pending fact, and walks
+ * through the gate carrying the approver. A resolution older than the newest
+ * pending fact is not an answer to it — {@link latestResolutionSince} applies
+ * that rule for the executor and for `chant operator status` alike. Both kinds
+ * of line share one file, told apart by {@link GateLedgerRecord}'s `kind`
+ * (absent on the resolution lines written before #2119, which is why
+ * `"resolution"` is the default reading).
  */
 import { sortedJsonReplacer } from "../utils";
 import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
@@ -98,11 +96,13 @@ export function isApprovalUrl(raw: string): boolean {
 export interface GateResolutionRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
   version: 1;
+  /** Discriminator against {@link PendingGateRecord}, which shares this file. Absent on every line written before #2119, so a reader must treat "no kind" as `"resolution"`. */
+  kind?: "resolution";
   /** The dispatched op the gate belongs to. */
   op: string;
   /** The gate's signal name (matches `ConvergeRuleOutcome.gateName`). */
   gate: string;
-  /** Who resolved it — an actor name, the same convention `components release --actor` and `run signal --approver` use. */
+  /** Who resolved it — an actor name, the same convention `components release --actor` and `run approve --approver` use. */
   resolvedBy: string;
   /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
   timestamp: string;
@@ -121,18 +121,99 @@ export interface GateResolutionRecord {
   url?: string;
 }
 
-export type GateResolutionInput = Omit<GateResolutionRecord, "version">;
+export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
+
+/**
+ * One immutable pending-gate record (#2119) — what an executor writes when a
+ * run reaches a `gate` step with no resolution standing against it. The run
+ * ends here with status `gated`; this line is the durable trace of that, and
+ * the anchor a later {@link GateResolutionRecord} has to be newer than to
+ * count as its answer.
+ *
+ * Idempotent by design: a run that finds a live (unexpired) pending fact for
+ * the same gate reuses it rather than appending a second one, so a converge
+ * loop ticking every minute against an unapproved gate does not grow the
+ * ledger by a line a minute. Once `expiresAt` passes, the fact is stale and
+ * the next run records a fresh one.
+ */
+export interface PendingGateRecord {
+  /** Schema version, so an incompatible future shape is detected before being misread. */
+  version: 1;
+  kind: "pending";
+  /** The op (or, on the component driver, the component) the gate belongs to. */
+  op: string;
+  /** The gate's name (matches `GateStep.gate`). */
+  gate: string;
+  /** The gate's human-readable description, when it declared one — what `chant operator status` shows a reader who wasn't there for the run. */
+  description?: string;
+  /** The run that reached the gate, when the caller identifies its runs. */
+  runId?: string;
+  /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
+  timestamp: string;
+  /** ISO-8601 expiry, from the gate's `timeout` (default {@link DEFAULT_GATE_EXPIRY}). Past it, the fact is stale and a run re-records it. */
+  expiresAt: string;
+  /** The address approval happens at, when the run knew one — see {@link resolveApprovalUrl}. */
+  url?: string;
+}
+
+export type PendingGateInput = Omit<PendingGateRecord, "version" | "kind">;
+
+/** Either kind of line in `_gates/<op>.jsonl`. */
+export type GateLedgerRecord = GateResolutionRecord | PendingGateRecord;
+
+/** The default a gate's pending fact expires after when its `GateStep` declares no `timeout` — the same 48h `GateStep.timeout` documents as its own default. */
+export const DEFAULT_GATE_EXPIRY = "48h";
+
+/** Whether a pending fact has aged out of relevance at `nowIso`. */
+export function isPendingGateExpired(record: PendingGateRecord, nowIso: string): boolean {
+  return new Date(record.expiresAt).getTime() <= new Date(nowIso).getTime();
+}
 
 function filename(op: string): string {
   return `${op}.jsonl`;
 }
 
+/**
+ * Where an Op's gate ledger lives, as a path a human can go and read:
+ * `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch. Exported so a
+ * renderer that tells someone a gate is pending can name the file the pending
+ * fact was appended to (#2243) rather than describing it in prose that drifts
+ * from `DIR`.
+ */
+export function gateLedgerPath(op: string): string {
+  return `${DIR}/${filename(op)}`;
+}
+
 /** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
 export async function appendGateResolution(
   input: GateResolutionInput,
   opts?: { cwd?: string },
 ): Promise<{ commit: string; record: GateResolutionRecord }> {
   const record: GateResolutionRecord = { version: 1, ...input };
+  const commit = await appendGateLine(record, "Gate resolution record", opts);
+  return { commit, record };
+}
+
+/**
+ * Append one immutable pending-gate record (#2119) — the fact a run leaves
+ * behind when it reaches a gate nobody has approved. Same file, same
+ * append-and-retry discipline, same "does not push" contract as
+ * {@link appendGateResolution}.
+ */
+export async function appendPendingGate(
+  input: PendingGateInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: PendingGateRecord }> {
+  const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+  const commit = await appendGateLine(record, "Pending gate record", opts);
+  return { commit, record };
+}
+
+async function appendGateLine(
+  record: GateLedgerRecord,
+  message: string,
+  opts?: { cwd?: string },
+): Promise<string> {
   const json = JSON.stringify(record, sortedJsonReplacer);
 
   let lastErr: unknown;
@@ -141,11 +222,10 @@ export async function appendGateResolution(
       const priorSha = await readPathSha(DIR, filename(record.op), opts);
       const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
       const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
-      const commit = await writeBlobToPath(DIR, filename(record.op), content, "Gate resolution record", {
+      return await writeBlobToPath(DIR, filename(record.op), content, message, {
         ...opts,
         expectPriorPathSha: priorSha,
       });
-      return { commit, record };
     } catch (err) {
       if (!(err instanceof RefCASConflictError)) throw err;
       lastErr = err;
@@ -154,36 +234,74 @@ export async function appendGateResolution(
   throw lastErr;
 }
 
-/** Read every gate-resolution record for `op`, oldest first. Malformed lines are skipped, not thrown on, the same graceful-degradation stance `readConvergeLedger` takes. Returns `[]` (never throws) when `op` has no resolutions recorded yet. */
-export async function readGateResolutions(
+/**
+ * Read every line of `op`'s gate file, oldest first, split into the two kinds
+ * (#2119). Malformed lines are skipped and counted, not thrown on — the same
+ * graceful-degradation stance `readConvergeLedger` takes. Returns empty arrays
+ * (never throws) when `op` has nothing recorded yet.
+ */
+export async function readGateLedger(
   op: string,
   opts?: { cwd?: string },
-): Promise<{ records: GateResolutionRecord[]; malformed: number }> {
+): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[]; malformed: number }> {
   const content = await readBlobFromPath(DIR, filename(op), opts);
-  if (!content) return { records: [], malformed: 0 };
+  if (!content) return { resolutions: [], pending: [], malformed: 0 };
 
   const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
-  const records: GateResolutionRecord[] = [];
+  const resolutions: GateResolutionRecord[] = [];
+  const pending: PendingGateRecord[] = [];
   let malformed = 0;
   for (const line of lines) {
     try {
-      const parsed = JSON.parse(line) as Partial<GateResolutionRecord>;
-      if (
-        parsed.version !== 1 ||
-        typeof parsed.op !== "string" ||
-        typeof parsed.gate !== "string" ||
-        typeof parsed.resolvedBy !== "string" ||
-        typeof parsed.timestamp !== "string"
-      ) {
+      const parsed = JSON.parse(line) as Partial<Omit<GateResolutionRecord, "kind">> &
+        Partial<Omit<PendingGateRecord, "kind">> & { kind?: string };
+      const common =
+        parsed.version === 1 && typeof parsed.op === "string" &&
+        typeof parsed.gate === "string" && typeof parsed.timestamp === "string";
+      if (!common) {
         malformed++;
         continue;
       }
-      records.push(parsed as GateResolutionRecord);
+      if (parsed.kind === "pending") {
+        if (typeof parsed.expiresAt !== "string") {
+          malformed++;
+          continue;
+        }
+        pending.push(parsed as PendingGateRecord);
+        continue;
+      }
+      if (typeof parsed.resolvedBy !== "string") {
+        malformed++;
+        continue;
+      }
+      resolutions.push(parsed as GateResolutionRecord);
     } catch {
       malformed++;
     }
   }
-  return { records, malformed };
+  return { resolutions, pending, malformed };
+}
+
+/** Read every gate-*resolution* record for `op`, oldest first — {@link readGateLedger} narrowed to the half every caller before #2119 wanted. Pending facts are not malformed lines and are not counted as such. */
+export async function readGateResolutions(
+  op: string,
+  opts?: { cwd?: string },
+): Promise<{ records: GateResolutionRecord[]; malformed: number }> {
+  const { resolutions, malformed } = await readGateLedger(op, opts);
+  return { records: resolutions, malformed };
+}
+
+/** The most recent pending fact for `gate`, expired or not — the anchor {@link latestResolutionSince} measures a resolution against. `undefined` when the gate has never been recorded pending. */
+export function latestPendingGate(
+  records: PendingGateRecord[],
+  gate: string,
+): PendingGateRecord | undefined {
+  let latest: PendingGateRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
+  }
+  return latest;
 }
 
 /** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */

package/src/lifecycle/index.ts

@@ -20,5 +20,6 @@ export * from "./teardown";
 export * from "./assert-live";
 export * from "./symptoms";
 export * from "./converge-ledger";
+export * from "./run-ledger";
 export * from "./scenario";
 export * from "./scenario-eval";

package/src/lifecycle/release-ledger.ts

@@ -98,8 +98,8 @@ export interface ReleaseRecord {
   /**
    * Who approved the change at its durable approval gate (#1035). Populated for
    * a gated change — the same identity the approver supplied when they cleared
-   * the Temporal gate (`chant run signal ... --approver`, carried in the gate
-   * signal payload and thus the workflow history). Optional and omitted for an
+   * the gate (`chant approve <op> <gate> --approver`, recorded on the gate
+   * resolution fact). Optional and omitted for an
    * ungated change (nothing to approve), so `actor` alone answers "who made
    * it" while `approver` answers "who approved it" only where a gate exists.
    * Distinct from `actor`: the approver is deliberately a different person than

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

@@ -0,0 +1,268 @@
+/**
+ * Run ledger tests (#2118) — the same git fixture `converge-ledger.test.ts`
+ * uses, so the two ledgers are exercised against one real orphan branch and a
+ * change to the shared plumbing under them fails in both places.
+ */
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  appendRunRecord,
+  readRunLedger,
+  buildRunRecord,
+  runEnvOf,
+  DEFAULT_RUN_ENV,
+} from "./run-ledger";
+import type { OpRunRecordInput } from "../op/runtime";
+import { appendConvergeRecord, readConvergeLedger } from "./converge-ledger";
+import { runOpLocally, OpRunFailure } from "../op/local-executor";
+import type { ActivityFn } from "../op/activity-registry";
+import type { OpConfig } from "../op/types";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function makeInput(overrides?: Partial<OpRunRecordInput>): OpRunRecordInput {
+  return {
+    op: "alb-deploy",
+    env: "staging",
+    started: "2026-01-01T00:00:00.000Z",
+    ended: "2026-01-01T00:00:12.000Z",
+    status: "ok",
+    labels: { Apply: "true", Env: "staging" },
+    outcomes: {},
+    phases: [{ name: "Apply", status: "ok", steps: [{ fn: "kubectlApply", status: "ok", durationMs: 12_000 }] }],
+    ...overrides,
+  };
+}
+
+const NO_PROFILES = {};
+
+function opConfig(overrides?: Partial<OpConfig>): OpConfig {
+  return {
+    name: "alb-deploy",
+    overview: "deploy the alb",
+    labels: { Env: "staging" },
+    phases: [{ name: "Apply", steps: [{ kind: "activity", fn: "ok", args: {} }] }],
+    ...overrides,
+  };
+}
+
+describe("runEnvOf", () => {
+  test("reads labels.Env", () => {
+    expect(runEnvOf({ labels: { Env: "prod" } })).toBe("prod");
+  });
+
+  test("falls back to the default env when the Op declares no labels", () => {
+    expect(runEnvOf({})).toBe(DEFAULT_RUN_ENV);
+    expect(runEnvOf({ labels: { Apply: "true" } })).toBe(DEFAULT_RUN_ENV);
+  });
+});
+
+describe("buildRunRecord", () => {
+  test("groups step records into phases in execution order and folds outcomes", () => {
+    const input = buildRunRecord(
+      { name: "watch", labels: { Watch: "true", Env: "prod" } },
+      [
+        { phase: "Snapshot", fn: "lifecycleSnapshot", status: "ok", durationMs: 5 },
+        { phase: "Diff", fn: "lifecycleDiff", status: "ok", durationMs: 7, outcome: { name: "Drift", value: true } },
+        { phase: "Diff", fn: "report", status: "skipped", durationMs: 0 },
+      ],
+      { started: "2026-01-01T00:00:00.000Z", ended: "2026-01-01T00:00:01.000Z", status: "ok" },
+    );
+
+    expect(input.env).toBe("prod");
+    expect(input.status).toBe("ok");
+    expect(input.labels).toEqual({ Watch: "true", Env: "prod" });
+    expect(input.outcomes).toEqual({ Drift: true });
+    expect(input.phases.map((p) => [p.name, p.status])).toEqual([["Snapshot", "ok"], ["Diff", "ok"]]);
+    expect(input.phases[1].steps.map((s) => s.status)).toEqual(["ok", "skipped"]);
+  });
+
+  test("a phase with a failed step is fail; a phase whose steps all skipped is skipped", () => {
+    const input = buildRunRecord(
+      { name: "deploy" },
+      [
+        { phase: "Apply", fn: "kubectlApply", status: "fail", durationMs: 3, error: "boom" },
+        { phase: "Verify", fn: "httpCheck", status: "skipped", durationMs: 0 },
+      ],
+      { started: "2026-01-01T00:00:00.000Z", ended: "2026-01-01T00:00:01.000Z", status: "fail" },
+    );
+
+    expect(input.status).toBe("fail");
+    expect(input.env).toBe(DEFAULT_RUN_ENV);
+    expect(input.phases.map((p) => [p.name, p.status])).toEqual([["Apply", "fail"], ["Verify", "skipped"]]);
+    expect(input.phases[0].steps[0].error).toBe("boom");
+  });
+});
+
+describe("appendRunRecord / readRunLedger", () => {
+  test("round-trips a single record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const { record } = await appendRunRecord(makeInput(), { cwd: dir });
+      expect(record.version).toBe(1);
+      expect(record.id).toMatch(/^[0-9a-f-]{36}$/);
+
+      const { records, malformed } = await readRunLedger("staging", "alb-deploy", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(records).toEqual([record]);
+    });
+  });
+
+  test("appends without clobbering prior records", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendRunRecord(makeInput({ ended: "2026-01-01T00:00:12.000Z" }), { cwd: dir });
+      await appendRunRecord(makeInput({ ended: "2026-01-01T00:10:12.000Z" }), { cwd: dir });
+      await appendRunRecord(makeInput({ ended: "2026-01-01T00:20:12.000Z" }), { cwd: dir });
+
+      const { records } = await readRunLedger("staging", "alb-deploy", { cwd: dir });
+      expect(records.map((r) => r.ended)).toEqual([
+        "2026-01-01T00:00:12.000Z",
+        "2026-01-01T00:10:12.000Z",
+        "2026-01-01T00:20:12.000Z",
+      ]);
+    });
+  });
+
+  test("one op's ledger is not another's, and neither disturbs the converge ledger in the same env", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendRunRecord(makeInput({ op: "alb-deploy" }), { cwd: dir });
+      await appendRunRecord(makeInput({ op: "alb-teardown" }), { cwd: dir });
+      await appendConvergeRecord(
+        {
+          op: "staging-converge",
+          env: "staging",
+          timestamp: "2026-01-01T00:00:00.000Z",
+          firedRuleIds: [],
+          outcomes: [],
+          summary: { drifted: 0, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0 },
+          log: "converge(staging): drifted=0",
+        },
+        { cwd: dir },
+      );
+
+      expect((await readRunLedger("staging", "alb-deploy", { cwd: dir })).records).toHaveLength(1);
+      expect((await readRunLedger("staging", "alb-teardown", { cwd: dir })).records).toHaveLength(1);
+      expect((await readConvergeLedger("staging", { cwd: dir })).records).toHaveLength(1);
+    });
+  });
+
+  test("an unwritten ledger reads empty — never throws", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const { records, malformed } = await readRunLedger("nowhere", "nothing", { cwd: dir });
+      expect(records).toEqual([]);
+      expect(malformed).toBe(0);
+    });
+  });
+
+  test("skips malformed lines but reports the count", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendRunRecord(makeInput(), { cwd: dir });
+
+      const { readBlobFromPath, writeBlobToPath } = await import("./git");
+      const existing = await readBlobFromPath("staging", "runs__alb-deploy.jsonl", { cwd: dir });
+      const corrupted = `${existing}\n${JSON.stringify({ version: 1, op: "alb-deploy", env: "staging" })}`;
+      await writeBlobToPath("staging", "runs__alb-deploy.jsonl", corrupted, "corrupt", { cwd: dir });
+
+      const { records, malformed } = await readRunLedger("staging", "alb-deploy", { cwd: dir });
+      expect(records).toHaveLength(1);
+      expect(malformed).toBe(1);
+    });
+  });
+
+  test("a gated record written by hand round-trips (#2119 produces these; the type carries the status now)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendRunRecord(
+        makeInput({
+          status: "gated",
+          phases: [
+            { name: "Plan", status: "ok", steps: [{ fn: "terraformPlan", status: "ok", durationMs: 900 }] },
+            { name: "Approve", status: "skipped", steps: [{ fn: "gate:approve-apply", status: "skipped", durationMs: 0 }] },
+          ],
+        }),
+        { cwd: dir },
+      );
+
+      const { records } = await readRunLedger("staging", "alb-deploy", { cwd: dir });
+      expect(records[0].status).toBe("gated");
+      expect(records[0].phases[1]).toMatchObject({ name: "Approve", status: "skipped" });
+    });
+  });
+});
+
+describe("runOpLocally → the run ledger", () => {
+  test("a successful run appends exactly one record, and the result carries the same document", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const activities = new Map<string, ActivityFn>([["ok", async () => ({ drifted: false })]]);
+      const config = opConfig({
+        phases: [
+          {
+            name: "Apply",
+            steps: [{ kind: "activity", fn: "ok", args: {}, outcomeAttribute: { name: "Drift", from: "drifted" } }],
+          },
+        ],
+      });
+
+      const result = await runOpLocally(config, activities, NO_PROFILES, undefined, { ledger: { cwd: dir } });
+
+      const { records } = await readRunLedger("staging", "alb-deploy", { cwd: dir });
+      expect(records).toHaveLength(1);
+      expect(records[0]).toEqual(result.record);
+      expect(records[0].status).toBe("ok");
+      expect(records[0].outcomes).toEqual({ Drift: false });
+      expect(records[0].labels).toEqual({ Env: "staging" });
+    });
+  });
+
+  test("a failed run appends a fail record and still rejects with OpRunFailure", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const activities = new Map<string, ActivityFn>([
+        ["ok", async () => { throw new Error("boom"); }],
+      ]);
+
+      const err = await runOpLocally(opConfig(), activities, NO_PROFILES, undefined, { ledger: { cwd: dir } })
+        .catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(OpRunFailure);
+
+      const { records } = await readRunLedger("staging", "alb-deploy", { cwd: dir });
+      expect(records).toHaveLength(1);
+      expect(records[0].status).toBe("fail");
+      expect(records[0].phases[0].steps[0].error).toContain("boom");
+      expect((err as OpRunFailure).result.record).toEqual(records[0]);
+    });
+  });
+
+  test("without the ledger option a run writes nothing, but still carries its record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const activities = new Map<string, ActivityFn>([["ok", async () => ({})]]);
+
+      const result = await runOpLocally(opConfig(), activities, NO_PROFILES);
+
+      expect(result.record.op).toBe("alb-deploy");
+      expect(result.record.status).toBe("ok");
+      expect((await readRunLedger("staging", "alb-deploy", { cwd: dir })).records).toEqual([]);
+    });
+  });
+});