@intentius/chant-lexicon-fly 0.17.0 → 0.18.1

package/src/op/activities/sprites-contract.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { SPRITES_CONTRACT, normalizeEndpoint, contractKeys } from "./sprites-contract";
+
+describe("SPRITES_CONTRACT", () => {
+  test("covers every sprite activity that calls the Sprites API", () => {
+    const activities = new Set(SPRITES_CONTRACT.map((e) => e.activity));
+    // The six ./sprites.ts activities that make an HTTP/WS call.
+    expect(activities).toEqual(
+      new Set([
+        "spriteCreate",
+        "spriteExec",
+        "spriteCheckpoint",
+        "listCheckpoints",
+        "spriteRestore",
+        "spriteDestroy",
+      ]),
+    );
+  });
+
+  test("every entry has a v1 path and a known method", () => {
+    for (const e of SPRITES_CONTRACT) {
+      expect(e.path.startsWith("/v1/sprites")).toBe(true);
+      expect(["GET", "POST", "DELETE", "WS"]).toContain(e.method);
+    }
+  });
+
+  test("normalizeEndpoint collapses param names and maps WS→GET", () => {
+    // {cp} and {cid} must compare equal (spritzer spells it {cid}).
+    expect(normalizeEndpoint("POST", "/v1/sprites/{id}/checkpoints/{cp}/restore")).toBe(
+      normalizeEndpoint("POST", "/v1/sprites/{id}/checkpoints/{cid}/restore"),
+    );
+    // The exec WebSocket is registered as a GET on the emulator.
+    expect(normalizeEndpoint("WS", "/v1/sprites/{id}/exec")).toBe("GET /v1/sprites/{}/exec");
+  });
+
+  test("contractKeys is the deduped normalized set", () => {
+    const keys = contractKeys();
+    expect(keys.has("POST /v1/sprites")).toBe(true);
+    expect(keys.has("DELETE /v1/sprites/{}")).toBe(true);
+    expect(keys.size).toBe(SPRITES_CONTRACT.length);
+  });
+
+  test("every contract path segment appears in the sprites.ts source (drift anchor)", () => {
+    // Anchors the hand-authored contract to the activity implementations: if an
+    // activity's endpoint path changes, a segment goes missing here and the
+    // contract must be updated in the same change.
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "sprites.ts"), "utf-8");
+    const segments = new Set(
+      SPRITES_CONTRACT.flatMap((e) =>
+        e.path.split("/").filter((s) => s.length > 0 && !s.startsWith("{")),
+      ),
+    );
+    for (const seg of segments) {
+      expect(src, `path segment "${seg}" from the contract is absent from sprites.ts`).toContain(seg);
+    }
+  });
+});

package/src/op/activities/sprites-contract.ts

@@ -0,0 +1,61 @@
+/**
+ * Hand-authored Fly Sprites API contract (#808 T3).
+ *
+ * The Fly Machines API ships a machine-readable OpenAPI (docs.machines.dev) that
+ * the fly resource surface generates + drift-checks against. The Sprites API
+ * (api.sprites.dev) ships no such spec at any conventional path, so there is
+ * nothing to diff automatically. This module is the manual stand-in: the exact
+ * endpoint set the fly sprite activities (./sprites.ts) depend on, maintained by
+ * hand from https://docs.sprites.dev.
+ *
+ * It anchors two fidelity checks:
+ *   1. Coverage — every endpoint here must be served by the pinned spritzer
+ *      emulator (its `/_spritzer/health` enumerates implemented paths). If an
+ *      activity ever calls something spritzer doesn't model, the docker-gated
+ *      contract test fails instead of silently passing against a partial fake.
+ *   2. Drift anchor — when the Sprites API changes, a human updates this file;
+ *      reviewers see exactly which activity/endpoint moved.
+ *
+ * Path params are written with names matching ./sprites.ts (`{id}`, `{cp}`);
+ * the coverage check normalizes param names before comparing, since spritzer
+ * spells the checkpoint id `{cid}`.
+ */
+
+/** One endpoint the fly sprite activities call. */
+export interface SpritesEndpoint {
+  /** HTTP method, or "WS" for the control-WebSocket exec channel. */
+  method: "GET" | "POST" | "DELETE" | "WS";
+  /** Path template under the Sprites base, e.g. `/v1/sprites/{id}/checkpoint`. */
+  path: string;
+  /** The fly activity that calls it (./sprites.ts export). */
+  activity: string;
+}
+
+/**
+ * The Sprites endpoints ./sprites.ts depends on. Keep in sync with the activity
+ * implementations — the unit test asserts every sprite activity is represented.
+ */
+export const SPRITES_CONTRACT: readonly SpritesEndpoint[] = [
+  { method: "POST", path: "/v1/sprites", activity: "spriteCreate" },
+  { method: "WS", path: "/v1/sprites/{id}/exec", activity: "spriteExec" },
+  { method: "POST", path: "/v1/sprites/{id}/checkpoint", activity: "spriteCheckpoint" },
+  { method: "GET", path: "/v1/sprites/{id}/checkpoints", activity: "listCheckpoints" },
+  { method: "POST", path: "/v1/sprites/{id}/checkpoints/{cp}/restore", activity: "spriteRestore" },
+  { method: "DELETE", path: "/v1/sprites/{id}", activity: "spriteDestroy" },
+] as const;
+
+/**
+ * Normalize a `METHOD path` key for comparison across sources: collapse every
+ * `{param}` to `{}` (so `{cp}` and `{cid}` match) and treat the WebSocket exec
+ * channel as a `GET` (spritzer registers it as `GET .../exec`).
+ */
+export function normalizeEndpoint(method: string, path: string): string {
+  const m = method === "WS" ? "GET" : method.toUpperCase();
+  const p = path.replace(/\{[^}]+\}/g, "{}");
+  return `${m} ${p}`;
+}
+
+/** The contract as a set of normalized `METHOD path` keys. */
+export function contractKeys(): Set<string> {
+  return new Set(SPRITES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
+}

package/src/op/activities/sprites-emulator.ts

@@ -0,0 +1,46 @@
+import { emulatorLifecycle } from "@intentius/chant/op";
+import { SPRITZER_IMAGE } from "./emulator-images";
+
+export interface SpritesUpArgs {
+  /** Container name. Default: `chant-spritzer`. */
+  name?: string;
+  /** Host port mapped to the emulator's `:4290`. Default: `4290`. */
+  port?: number;
+  /** Image. Default: the pinned spritzer image ({@link SPRITZER_IMAGE}). */
+  image?: string;
+  /** Readiness timeout in ms. Default: `60000`. */
+  timeoutMs?: number;
+  /** Health poll interval in ms. Default: `2000`. */
+  intervalMs?: number;
+}
+
+export interface SpritesDownArgs {
+  /** Container name to remove. Default: `chant-spritzer`. */
+  name?: string;
+}
+
+// spritzer is a stateful fake of the Fly Sprites API — a plain 200 on its health
+// endpoint means ready. The local target for the sprite activities; point them
+// there with SPRITES_BASE_URL. Shared lifecycle: emulatorLifecycle (the same
+// helper that boots mudflaps for fly).
+const spritzer = emulatorLifecycle({
+  name: "chant-spritzer",
+  image: SPRITZER_IMAGE,
+  containerPort: 4290,
+  healthPath: "/_spritzer/health",
+});
+
+export const spritesExistsCommand = spritzer.existsCommand;
+export const spritesRmCommand = spritzer.rmCommand;
+export const spritesHealthUrl = spritzer.healthUrl;
+/** The Sprites endpoint URL (what the sprite activities' `SPRITES_BASE_URL`/`endpoint` points at). */
+export const spritesEndpoint = spritzer.endpoint;
+export const spritesRunCommand = (args: SpritesUpArgs = {}): string => spritzer.runCommand(args);
+
+/** Boot a local spritzer (Fly Sprites API emulator) in Docker and return its endpoint. */
+export const spritesUp = (args: SpritesUpArgs = {}, signal?: AbortSignal): Promise<{ endpoint: string }> =>
+  spritzer.up(args, signal);
+
+/** Stop and remove the local spritzer container (no-op if already gone). */
+export const spritesDown = (args: SpritesDownArgs = {}, signal?: AbortSignal): Promise<void> =>
+  spritzer.down(args, signal);

package/src/op/activities/sprites-fake.ts

@@ -0,0 +1,314 @@
+/**
+ * In-process Sprites fake (#762, #766, S7) — a fake of the faithful Sprites API
+ * surface for offline, Docker-free integration tests.
+ *
+ * It models the lifecycle state machine and checkpoint/restore semantics, not
+ * real Firecracker VMs or real code execution (that fidelity is out of scope).
+ * A sprite's filesystem is a `Record<string, string>`; `exec` runs a small
+ * scripted interpreter that can write/modify an `fs` key so checkpoint/restore
+ * is observable; `checkpoint` deep-copies `fs` under a version id; `restore`
+ * replaces `fs` with that copy. Started in-process by a test and reached via
+ * `SPRITES_BASE_URL`, so the same activities that hit real Sprites hit the fake.
+ *
+ * The wire surface matches the released `spritzer:0.3.1` image so the CI
+ * fake-based test and the docker test exercise the same protocol:
+ *  - `exec` over the control WebSocket with `[StreamID][payload]` binary framing;
+ *  - `POST /checkpoint` (singular) returning NDJSON progress + a `complete` event;
+ *  - `GET /checkpoints` returning a bare array of `{ id, comment, create_time, is_auto }`;
+ *  - `POST /checkpoints/{id}/restore` returning NDJSON.
+ * Checkpoint ids are server versions (`v1`, `v2`, ...).
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+import { WebSocketServer, type WebSocket } from "ws";
+
+type SpriteStatus = "starting" | "running" | "paused" | "destroyed";
+
+interface StoredCheckpoint {
+  id: string;
+  comment: string;
+  create_time: string;
+  is_auto: boolean;
+  fs: Record<string, string>;
+}
+
+interface SpriteState {
+  id: string;
+  status: SpriteStatus;
+  url: string;
+  /** Filesystem model: path → contents. */
+  fs: Record<string, string>;
+  /** Checkpoints in creation order; each holds a full copy of `fs` at that time. */
+  checkpoints: StoredCheckpoint[];
+  /** Monotonic version counter for `v<N>` ids. */
+  version: number;
+  policy?: unknown;
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Run one command against a sprite's `fs`. Not a real shell: it recognizes a
+ * small set of forms so a test (and the example `guarded-task` Op) can write a
+ * key, then overwrite/fail it, and prove restore rewinds. Segments split on
+ * `;` run in order; the exit code is the last segment's (shell `;` semantics).
+ */
+export function fakeExec(sprite: SpriteState, cmd: string): ExecResult {
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+
+  for (const raw of cmd.split(";")) {
+    const seg = raw.trim();
+    if (!seg) continue;
+
+    let m: RegExpMatchArray | null;
+    if ((m = seg.match(/^echo\s+(.+?)\s*>\s*(\S+)$/))) {
+      sprite.fs[m[2]] = unquote(m[1]);
+      exitCode = 0;
+    } else if ((m = seg.match(/^echo\s+(.+)$/))) {
+      stdout += `${unquote(m[1])}\n`;
+      exitCode = 0;
+    } else if ((m = seg.match(/^cat\s+(\S+)$/))) {
+      stdout += sprite.fs[m[1]] ?? "";
+      exitCode = 0;
+    } else if ((m = seg.match(/^rm\s+(?:-f\s+)?(\S+)$/))) {
+      delete sprite.fs[m[1]];
+      exitCode = 0;
+    } else if (seg === "false") {
+      exitCode = 1;
+    } else if (seg === "true") {
+      exitCode = 0;
+    } else if (seg === "./risky.sh") {
+      // A scripted failing job: mutates the workspace, then exits non-zero, so
+      // the example guarded-task Op demonstrates checkpoint-as-compensation.
+      sprite.fs["/work/output"] = "partial-corrupt";
+      stderr += "risky.sh: failed\n";
+      exitCode = 1;
+    } else {
+      // Unknown command → echo it back (a no-op success), never real execution.
+      stdout += `${seg}\n`;
+      exitCode = 0;
+    }
+  }
+
+  return { stdout, stderr, exitCode };
+}
+
+function unquote(s: string): string {
+  const t = s.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+/** A full copy of an `fs` map. Values are strings, so a shallow spread copies them. */
+function copyFs(fs: Record<string, string>): Record<string, string> {
+  return { ...fs };
+}
+
+// Stream ids for the non-PTY exec framing (mirror sprites.ts).
+const STREAM_STDOUT = 1;
+const STREAM_STDERR = 2;
+const STREAM_EXIT = 3;
+
+function frame(stream: number, payload: Buffer): Buffer {
+  return Buffer.concat([Buffer.of(stream), payload]);
+}
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  if (chunks.length === 0) return undefined;
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Start the in-process Sprites fake on an ephemeral port. Returns its base
+ * `url` (feed it to `SPRITES_BASE_URL`) and a `close()`.
+ */
+export function createSpritesFake(): Promise<{ url: string; close(): Promise<void> }> {
+  const sprites = new Map<string, SpriteState>();
+
+  const server: Server = createServer((req, res) => {
+    void handle(req, res).catch((err) => {
+      res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+    });
+  });
+
+  // The control WebSocket exec endpoint. noServer + a manual `upgrade` handler so
+  // the same http server serves both the REST/NDJSON routes and the exec socket.
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const m = url.pathname.match(/^\/v1\/sprites\/([^/]+)\/exec\/?$/);
+    if (!m) {
+      socket.destroy();
+      return;
+    }
+    const id = decodeURIComponent(m[1]);
+    wss.handleUpgrade(req, socket, head, (ws) => runExec(ws, sprites.get(id), url));
+  });
+
+  function runExec(ws: WebSocket, sprite: SpriteState | undefined, url: URL): void {
+    if (!sprite || sprite.status === "destroyed") {
+      ws.send(frame(STREAM_STDERR, Buffer.from(`no sprite\n`)));
+      ws.send(frame(STREAM_EXIT, Buffer.of(127)));
+      ws.close();
+      return;
+    }
+    // argv arrives as repeated `cmd` params; reconstruct the script the small
+    // interpreter understands (the tokens round-trip for the space-separated
+    // command forms the example Ops use).
+    const argv = url.searchParams.getAll("cmd");
+    const script = argv.join(" ");
+    const result = fakeExec(sprite, script);
+    if (result.stdout) ws.send(frame(STREAM_STDOUT, Buffer.from(result.stdout)));
+    if (result.stderr) ws.send(frame(STREAM_STDERR, Buffer.from(result.stderr)));
+    ws.send(frame(STREAM_EXIT, Buffer.of(result.exitCode & 0xff)));
+    ws.close();
+  }
+
+  async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const method = req.method ?? "GET";
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const path = url.pathname;
+    const host = req.headers.host ?? "localhost";
+    const send = (status: number, body: unknown): void => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(body ?? {}));
+    };
+    // NDJSON progress stream: an `info` line then a terminal `complete` line.
+    const sendNdjson = (status: number, events: Array<Record<string, unknown>>): void => {
+      res.writeHead(status, { "content-type": "application/x-ndjson" });
+      res.end(events.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    };
+
+    // POST /v1/sprites — create.
+    if (method === "POST" && /^\/v1\/sprites\/?$/.test(path)) {
+      const body = ((await readBody(req)) ?? {}) as { name?: string; policy?: unknown };
+      const id = body.name;
+      if (!id) return send(400, { error: "name is required" });
+      const sprite: SpriteState = {
+        id,
+        status: "running",
+        url: `http://${host}/s/${encodeURIComponent(id)}`,
+        fs: {},
+        checkpoints: [],
+        version: 0,
+        policy: body.policy,
+      };
+      sprites.set(id, sprite);
+      return send(201, { id: sprite.id, url: sprite.url });
+    }
+
+    const m = path.match(/^\/v1\/sprites\/([^/]+)(\/checkpoint|\/checkpoints(?:\/([^/]+)(\/restore)?)?)?\/?$/);
+    if (m) {
+      const id = decodeURIComponent(m[1]);
+      const sub = m[2];
+      const cpId = m[3] ? decodeURIComponent(m[3]) : undefined;
+      const isRestore = Boolean(m[4]);
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+
+      // POST /v1/sprites/{id}/checkpoint — snapshot fs under a new version id.
+      if (method === "POST" && sub === "/checkpoint") {
+        const body = ((await readBody(req)) ?? {}) as { comment?: string };
+        sprite.version += 1;
+        const cp: StoredCheckpoint = {
+          id: `v${sprite.version}`,
+          comment: body.comment ?? "",
+          create_time: new Date().toISOString(),
+          is_auto: false,
+          fs: copyFs(sprite.fs),
+        };
+        sprite.checkpoints.push(cp);
+        // Mirror real Sprites: `{type, data}` progress lines carrying the
+        // version id in the message text, not a structured field.
+        return sendNdjson(200, [
+          { type: "info", data: "Creating checkpoint..." },
+          { type: "info", data: "Checkpoint created successfully" },
+          { type: "info", data: `  ID: ${cp.id}` },
+          { type: "complete", data: `Checkpoint ${cp.id} created successfully` },
+        ]);
+      }
+
+      // GET /v1/sprites/{id}/checkpoints — bare array (auto excluded).
+      if (method === "GET" && sub === "/checkpoints" && !cpId) {
+        return send(
+          200,
+          sprite.checkpoints
+            .filter((c) => !c.is_auto)
+            .map((c) => ({ id: c.id, comment: c.comment, create_time: c.create_time, is_auto: c.is_auto })),
+        );
+      }
+
+      // GET /v1/sprites/{id}/checkpoints/{cp} — a single checkpoint.
+      if (method === "GET" && cpId && !isRestore) {
+        const cp = sprite.checkpoints.find((c) => c.id === cpId);
+        if (!cp) return send(404, { error: `no checkpoint ${cpId} for sprite ${id}` });
+        return send(200, { id: cp.id, comment: cp.comment, create_time: cp.create_time });
+      }
+
+      // POST /v1/sprites/{id}/checkpoints/{cp}/restore — replace fs with the snapshot.
+      if (method === "POST" && cpId && isRestore) {
+        const cp = sprite.checkpoints.find((c) => c.id === cpId);
+        if (!cp) return send(404, { error: `no checkpoint ${cpId} for sprite ${id}` });
+        sprite.fs = copyFs(cp.fs);
+        sprite.status = "running";
+        return sendNdjson(200, [
+          { type: "info", data: `Restoring checkpoint ${cpId}...` },
+          { type: "complete", data: `Checkpoint ${cpId} restored successfully` },
+        ]);
+      }
+
+      // DELETE /v1/sprites/{id}
+      if (method === "DELETE" && !sub) {
+        sprite.status = "destroyed";
+        return send(200, {});
+      }
+
+      // GET /v1/sprites/{id} — inspection (fs + checkpoint ids), used by tests/verify.
+      if (method === "GET" && !sub) {
+        return send(200, {
+          id: sprite.id,
+          status: sprite.status,
+          url: sprite.url,
+          fs: sprite.fs,
+          checkpoints: sprite.checkpoints.map((c) => c.id),
+        });
+      }
+    }
+
+    return send(404, { error: `not found: ${method} ${path}` });
+  }
+
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      resolve({
+        url: `http://127.0.0.1:${port}`,
+        close: () =>
+          new Promise<void>((res, rej) => {
+            wss.close();
+            server.close((err) => (err ? rej(err) : res()));
+          }),
+      });
+    });
+  });
+}

package/src/op/activities/sprites.docker.integration.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import {
+  loadActivities,
+  runOpLocally,
+  OpRunFailure,
+  phase,
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  spriteDestroy,
+  type ActivityFn,
+  type ActivityProfile,
+  type OpConfig,
+} from "@intentius/chant/op";
+import { spritesUp, spritesDown } from "./sprites-emulator";
+
+// The checkpoint-as-compensation loop against the REAL spritzer image
+// (ghcr.io/intentius/spritzer), booted via `spritesUp` — the twin of fly's
+// mudflaps integration test. Proves the image is wire-compatible with the
+// in-process fake the CI test uses. Docker required; deterministically skipped
+// in CI (GitHub runners have Docker, so relying on absence would pull the image
+// on every run). Run locally, or opt in with SPRITES_DOCKER=1.
+
+const CONTAINER = "chant-spritzer-it";
+const PORT = 4292;
+const PROFILES: Record<string, ActivityProfile> = {
+  longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 3, initialInterval: "50ms", backoffCoefficient: 1 } },
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 2, initialInterval: "50ms", backoffCoefficient: 1 } },
+};
+
+let available = false;
+let endpoint = "";
+let activities: Map<string, ActivityFn>;
+let prevBaseUrl: string | undefined;
+
+async function inspect(id: string): Promise<{ status: string; fs: Record<string, string>; checkpoints: string[] }> {
+  const res = await fetch(`${endpoint}/v1/sprites/${id}`);
+  return (await res.json()) as { status: string; fs: Record<string, string>; checkpoints: string[] };
+}
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.SPRITES_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await spritesUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 });
+    endpoint = up.endpoint;
+    prevBaseUrl = process.env.SPRITES_BASE_URL;
+    process.env.SPRITES_BASE_URL = endpoint;
+    activities = await loadActivities(["fly"]);
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  if (available) await spritesDown({ name: CONTAINER });
+});
+
+describe("sprites against the live spritzer image (#786)", () => {
+  test("guarded-task: Run fails, onFailure Restore rewinds the sprite to the checkpoint", async (ctx) => {
+    if (!available) ctx.skip();
+    const op: OpConfig = {
+      name: "guarded-task",
+      overview: "checkpoint, run a risky step, restore on failure",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: "guard-1" })]),
+        phase("Seed", [spriteExec({ id: "guard-1", cmd: "echo good > /state" })]),
+        phase("Checkpoint", [spriteCheckpoint({ id: "guard-1", comment: "pre-run" })]),
+        phase("Run", [spriteExec({ id: "guard-1", cmd: "echo bad > /state; false" })]),
+        phase("Destroy", [spriteDestroy({ id: "guard-1" })]),
+      ],
+      onFailure: [phase("Restore", [spriteRestore({ id: "guard-1", comment: "pre-run" })])],
+    };
+
+    let failure: OpRunFailure | undefined;
+    try {
+      await runOpLocally(op, activities, PROFILES);
+    } catch (err) {
+      failure = err as OpRunFailure;
+    }
+    expect(failure).toBeInstanceOf(OpRunFailure); // the risky Run failed
+    const records = failure!.result.records;
+    expect(records.find((r) => r.phase === "Run")?.status).toBe("fail");
+    // Compensation ran against the live image.
+    const restore = records.find((r) => r.phase === "Restore");
+    expect(restore?.fn).toBe("spriteRestore");
+    expect(restore?.status).toBe("ok");
+
+    const state = await inspect("guard-1");
+    expect(state.fs["/state"]).toBe("good"); // rewound past the "bad" write
+  });
+});