@intentius/chant-lexicon-fly 0.17.0 → 0.18.1

package/src/emulator-freshness-cli.ts

@@ -0,0 +1,49 @@
+/**
+ * CLI for the emulator-freshness check (#808 T2). Fetches the latest mudflaps /
+ * spritzer releases, compares to the pinned tags, prints a report, and — when
+ * run in CI — writes `behind` + a Markdown `body` to `$GITHUB_OUTPUT` so the
+ * weekly workflow can open/refresh a single "N releases behind" notice issue.
+ *
+ * Advisory only: exits 0 whether or not a pin is behind (the bump is a human
+ * decision per the #808 policy). A hard failure (network/API) exits 1.
+ */
+
+import { appendFileSync } from "node:fs";
+import { checkFreshness, formatResult, type FreshnessResult } from "./emulator-freshness";
+
+function issueBody(behind: FreshnessResult[]): string {
+  const rows = behind.map((r) => `- **${r.name}** — pinned \`${r.pinned}\`, latest \`${r.latest}\``).join("\n");
+  return [
+    "The pinned Fly emulator image(s) are behind their latest upstream release:",
+    "",
+    rows,
+    "",
+    "The tag lives in `lexicons/fly/src/op/activities/emulator-images.ts` (single source).",
+    "",
+    "Per the #808 bump policy this is **advisory** — move the pin only when a consuming",
+    "test needs the newer emulator (a fidelity fix the fly activities exercise), not on",
+    "every release. Close this issue once reviewed or bumped.",
+  ].join("\n");
+}
+
+async function main(): Promise<void> {
+  const results = await checkFreshness();
+  for (const r of results) console.error(formatResult(r));
+
+  const behind = results.filter((r) => r.behind);
+  console.log(JSON.stringify({ behind: behind.length > 0, results }, null, 2));
+
+  const out = process.env.GITHUB_OUTPUT;
+  if (out) {
+    appendFileSync(out, `behind=${behind.length > 0}\n`);
+    if (behind.length > 0) {
+      // Multiline output via the GITHUB_OUTPUT heredoc form.
+      appendFileSync(out, `body<<FRESHNESS_EOF\n${issueBody(behind)}\nFRESHNESS_EOF\n`);
+    }
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/emulator-freshness.test.ts

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "vitest";
+import {
+  parseVersion,
+  compare,
+  latestRelease,
+  checkFreshness,
+  formatResult,
+  EMULATOR_PINS,
+} from "./emulator-freshness";
+
+describe("parseVersion", () => {
+  test("extracts the version from a ghcr image ref, stripping a leading v", () => {
+    expect(parseVersion("ghcr.io/intentius/mudflaps:0.3.1")).toBe("0.3.1");
+    expect(parseVersion("ghcr.io/intentius/spritzer:v1.2.0")).toBe("1.2.0");
+  });
+});
+
+describe("compare", () => {
+  test("not behind when pinned equals latest", () => {
+    expect(compare("mudflaps", "0.3.1", "v0.3.1").behind).toBe(false);
+  });
+  test("behind when latest is a newer patch/minor/major", () => {
+    expect(compare("m", "0.3.1", "v0.3.2").behind).toBe(true);
+    expect(compare("m", "0.3.1", "v0.4.0").behind).toBe(true);
+    expect(compare("m", "0.3.1", "v1.0.0").behind).toBe(true);
+  });
+  test("not behind when pinned is ahead of latest", () => {
+    expect(compare("m", "0.4.0", "v0.3.9").behind).toBe(false);
+  });
+  test("normalizes the leading v out of the reported versions", () => {
+    const r = compare("m", "0.3.1", "v0.3.2");
+    expect(r.pinned).toBe("0.3.1");
+    expect(r.latest).toBe("0.3.2");
+  });
+});
+
+describe("EMULATOR_PINS", () => {
+  test("tracks mudflaps and spritzer from the single-source image constants", () => {
+    expect(EMULATOR_PINS.map((p) => p.name).sort()).toEqual(["mudflaps", "spritzer"]);
+    for (const p of EMULATOR_PINS) {
+      expect(p.repo).toMatch(/^intentius\//);
+      expect(p.pinned).toMatch(/^\d+\.\d+\.\d+$/);
+    }
+  });
+});
+
+describe("latestRelease + checkFreshness (mocked fetch)", () => {
+  const mkFetch = (tags: Record<string, string>): typeof fetch =>
+    (async (url: string | URL | Request) => {
+      const u = String(url);
+      const repo = u.match(/repos\/([^/]+\/[^/]+)\/releases/)?.[1] ?? "";
+      return { ok: true, status: 200, json: async () => ({ tag_name: tags[repo] }) } as Response;
+    }) as unknown as typeof fetch;
+
+  test("latestRelease returns the tag_name", async () => {
+    const f = mkFetch({ "intentius/mudflaps": "v0.9.0" });
+    expect(await latestRelease("intentius/mudflaps", f)).toBe("v0.9.0");
+  });
+
+  test("checkFreshness flags a pin behind its latest release", async () => {
+    // Force both upstreams to a high version so the check reports behind
+    // regardless of the currently-pinned tag.
+    const f = mkFetch({ "intentius/mudflaps": "v99.0.0", "intentius/spritzer": "v99.0.0" });
+    const results = await checkFreshness(f);
+    expect(results).toHaveLength(2);
+    expect(results.every((r) => r.behind)).toBe(true);
+  });
+
+  test("checkFreshness reports current when latest matches the pin", async () => {
+    const pins = Object.fromEntries(EMULATOR_PINS.map((p) => [p.repo, `v${p.pinned}`]));
+    const results = await checkFreshness(mkFetch(pins));
+    expect(results.every((r) => !r.behind)).toBe(true);
+  });
+
+  test("latestRelease throws on a non-ok response", async () => {
+    const f = (async () => ({ ok: false, status: 404 }) as Response) as unknown as typeof fetch;
+    await expect(latestRelease("intentius/nope", f)).rejects.toThrow(/HTTP 404/);
+  });
+});
+
+describe("formatResult", () => {
+  test("marks behind vs current distinctly", () => {
+    expect(formatResult({ name: "m", pinned: "0.3.1", latest: "0.4.0", behind: true })).toMatch(/behind/);
+    expect(formatResult({ name: "m", pinned: "0.3.1", latest: "0.3.1", behind: false })).toMatch(/current/);
+  });
+});

package/src/emulator-freshness.ts

@@ -0,0 +1,87 @@
+/**
+ * Emulator-freshness check (#808 T2, second half).
+ *
+ * mudflaps (Machines) and spritzer (Sprites) are pinned to a single source
+ * (./op/activities/emulator-images.ts). Their upstream repos cut GitHub releases,
+ * so this compares each pinned tag against the latest release and reports how far
+ * behind it is. A weekly workflow surfaces a "N releases behind" notice — never
+ * an auto-bump. Per the bump policy (#808), the tag moves only when a consuming
+ * test needs the newer emulator, so this is advisory, not gating on the pin.
+ */
+
+import { MUDFLAPS_IMAGE, SPRITZER_IMAGE } from "./op/activities/emulator-images";
+
+export interface EmulatorPin {
+  /** Short name, e.g. "mudflaps". */
+  name: string;
+  /** GitHub repo "owner/name" whose releases publish the emulator. */
+  repo: string;
+  /** Pinned version, no leading "v" (e.g. "0.3.1"). */
+  pinned: string;
+}
+
+export interface FreshnessResult {
+  name: string;
+  pinned: string;
+  latest: string;
+  /** True when the latest release is newer than the pinned version. */
+  behind: boolean;
+}
+
+/** Parse the version tag from a ghcr image ref (".../mudflaps:0.3.1" → "0.3.1"). */
+export function parseVersion(image: string): string {
+  const tag = image.slice(image.lastIndexOf(":") + 1);
+  return tag.replace(/^v/, "");
+}
+
+function toParts(v: string): number[] {
+  return v.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+}
+
+/** Compare pinned vs latest as dotted numeric versions; `behind` when latest > pinned. */
+export function compare(name: string, pinned: string, latest: string): FreshnessResult {
+  const p = toParts(pinned);
+  const l = toParts(latest);
+  let behind = false;
+  for (let i = 0; i < Math.max(p.length, l.length); i++) {
+    const a = p[i] ?? 0;
+    const b = l[i] ?? 0;
+    if (b > a) {
+      behind = true;
+      break;
+    }
+    if (b < a) break;
+  }
+  return { name, pinned: pinned.replace(/^v/, ""), latest: latest.replace(/^v/, ""), behind };
+}
+
+/** The emulator pins to check, read from the single-source image constants. */
+export const EMULATOR_PINS: readonly EmulatorPin[] = [
+  { name: "mudflaps", repo: "intentius/mudflaps", pinned: parseVersion(MUDFLAPS_IMAGE) },
+  { name: "spritzer", repo: "intentius/spritzer", pinned: parseVersion(SPRITZER_IMAGE) },
+] as const;
+
+/** Fetch the latest release tag for a repo via the GitHub REST API. */
+export async function latestRelease(repo: string, fetchImpl: typeof fetch = fetch): Promise<string> {
+  const headers: Record<string, string> = { Accept: "application/vnd.github+json" };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const res = await fetchImpl(`https://api.github.com/repos/${repo}/releases/latest`, { headers });
+  if (!res.ok) throw new Error(`releases/latest ${repo}: HTTP ${res.status}`);
+  const body = (await res.json()) as { tag_name?: string };
+  if (!body.tag_name) throw new Error(`releases/latest ${repo}: no tag_name`);
+  return body.tag_name;
+}
+
+/** Check every emulator pin against its latest release. */
+export async function checkFreshness(fetchImpl: typeof fetch = fetch): Promise<FreshnessResult[]> {
+  return Promise.all(
+    EMULATOR_PINS.map(async (p) => compare(p.name, p.pinned, await latestRelease(p.repo, fetchImpl))),
+  );
+}
+
+/** One-line human summary of a result. */
+export function formatResult(r: FreshnessResult): string {
+  return r.behind
+    ? `⚠ ${r.name}: pinned ${r.pinned}, latest ${r.latest} — behind`
+    : `✓ ${r.name}: pinned ${r.pinned} is current (latest ${r.latest})`;
+}

package/src/index.ts

@@ -17,6 +17,21 @@ export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
 export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy";
 export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composites/fly-deploy";
 
+// Sprite Op step builders (re-exported from core for single-import convenience).
+// These author `activity("spriteCreate", ...)` steps; `loadActivities(["fly"])`
+// binds them to the implementations in ./op/activities/sprites.ts. The `spritesUp`
+// /`spritesDown` builders boot/tear down the spritzer emulator as modeled steps.
+export {
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  listCheckpoints,
+  spriteDestroy,
+  spritesUp,
+  spritesDown,
+} from "@intentius/chant/op";
+
 // Generated resources — export everything from generated index.
 // Provides `App`, `Machine`, `Volume`, and the property types
 // (`MachineConfig`, `MachineGuest`, `MachineService`, ...) for authoring.

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

@@ -0,0 +1,21 @@
+/**
+ * Single source of truth for the Fly emulator image pins (#808 T2).
+ *
+ * mudflaps (Machines API) and spritzer (Sprites API) are the local fakes fly's
+ * activities are exercised against. These tags were previously duplicated across
+ * flaps.ts, sprites-emulator.ts, the fly-deploy composite, and tests — and had
+ * already drifted (the composite's docstring said mudflaps 0.3.0 while the
+ * activity pinned 0.3.1). Pin each here so a bump touches one line and the
+ * emulator-freshness check (#808 T2) has a single target to compare against the
+ * latest GHCR release.
+ *
+ * Bump policy (#808): move these only when a consuming test needs a newer
+ * emulator (a fidelity fix the activities exercise), not on every emulator
+ * release. For new upstream API surface the emulator leads, then fly bumps here.
+ */
+
+/** Pinned mudflaps (Fly Machines / flaps emulator) image. */
+export const MUDFLAPS_IMAGE = "ghcr.io/intentius/mudflaps:0.4.0";
+
+/** Pinned spritzer (Fly Sprites emulator) image. */
+export const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.3.1";

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

@@ -6,11 +6,12 @@ import {
   flapsHealthUrl,
   flapsEndpoint,
 } from "./flaps";
+import { MUDFLAPS_IMAGE } from "./emulator-images";
 
 describe("flaps (mudflaps) lifecycle commands", () => {
   test("run command uses defaults and maps the port", () => {
     expect(flapsRunCommand({})).toBe(
-      "docker run -d --rm --name chant-mudflaps -p 4280:4280 ghcr.io/intentius/mudflaps:0.3.1",
+      `docker run -d --rm --name chant-mudflaps -p 4280:4280 ${MUDFLAPS_IMAGE}`,
     );
   });
 

package/src/op/activities/flaps.ts

@@ -1,11 +1,12 @@
 import { emulatorLifecycle } from "@intentius/chant/op";
+import { MUDFLAPS_IMAGE } from "./emulator-images";
 
 export interface FlapsUpArgs {
   /** Container name. Default: `chant-mudflaps`. */
   name?: string;
   /** Host port mapped to the emulator's `:4280`. Default: `4280`. */
   port?: number;
-  /** Image. Default: `ghcr.io/intentius/mudflaps:0.3.1`. */
+  /** Image. Default: the pinned mudflaps image ({@link MUDFLAPS_IMAGE}). */
   image?: string;
   /** Readiness timeout in ms. Default: `60000`. */
   timeoutMs?: number;
@@ -23,7 +24,7 @@ export interface FlapsDownArgs {
 // with FLY_FLAPS_BASE_URL. Shared lifecycle: emulatorLifecycle (#746).
 const flaps = emulatorLifecycle({
   name: "chant-mudflaps",
-  image: "ghcr.io/intentius/mudflaps:0.3.1",
+  image: MUDFLAPS_IMAGE,
   containerPort: 4280,
   healthPath: "/_mudflaps/health",
 });

package/src/op/activities/index.ts

@@ -46,3 +46,56 @@ export {
   flapsEndpoint,
 } from "./flaps";
 export type { FlapsUpArgs, FlapsDownArgs } from "./flaps";
+
+// Sprites (sprites.dev) — the other Fly product: imperative, checkpointable
+// sandbox activities. `loadActivities(["fly"])` provides these; the fake lives
+// in `sprites-fake.ts` and is imported only by tests (not an activity). Unlike
+// Machines, Sprites have no desired state to reconcile — they are runtime
+// primitives driven inside an Op, with checkpoint-as-compensation as the
+// headline capability.
+export {
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  listCheckpoints,
+  spriteDestroy,
+  resolveSpritesEndpoint,
+  defaultSpritesHttp,
+  spriteCreateBody,
+  parseCreateResponse,
+  accumulateExecFrames,
+  parseCheckpointNdjson,
+  pickCheckpointByComment,
+  splitCommand,
+  spriteExecWsUrl,
+  DEFAULT_SPRITES_BASE_URL,
+} from "./sprites";
+export type {
+  SpritesHttp,
+  SpriteCreateArgs,
+  SpriteCreateResult,
+  SpriteExecArgs,
+  SpriteExecResult,
+  SpriteCheckpointArgs,
+  SpriteCheckpointResult,
+  SpriteRestoreArgs,
+  ListCheckpointsArgs,
+  Checkpoint,
+  SpriteDestroyArgs,
+} from "./sprites";
+
+// spritzer (the Sprites API emulator) Docker lifecycle — the twin of mudflaps
+// above. `spritesUp`/`spritesDown` resolve by name so an Op can boot/tear down
+// the emulator as a modeled step; the sprite activities target it via
+// SPRITES_BASE_URL.
+export {
+  spritesUp,
+  spritesDown,
+  spritesRunCommand,
+  spritesRmCommand,
+  spritesExistsCommand,
+  spritesHealthUrl,
+  spritesEndpoint,
+} from "./sprites-emulator";
+export type { SpritesUpArgs, SpritesDownArgs } from "./sprites-emulator";

package/src/op/activities/machines-contract.docker.integration.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { flapsUp, flapsDown } from "./flaps";
+import { MACHINES_CONTRACT, normalizeEndpoint, contractKeys } from "./machines-contract";
+
+// Fidelity check: every flaps endpoint the flyApply applier depends on
+// (MACHINES_CONTRACT) must be served by the pinned mudflaps image — the twin of
+// the Sprites contract ⊆ spritzer check (#808 T3). mudflaps enumerates its
+// implemented paths at `/_mudflaps/health` and answers roadmap endpoints
+// (machines/{id}/signal, /exec, /ps) with 501; flyApply must never depend on one.
+// Docker required; skipped in CI unless FLY_DOCKER=1 (GitHub runners have Docker,
+// so relying on absence would pull the image on every run).
+
+const CONTAINER = "chant-mudflaps-contract-it";
+const PORT = 4283;
+
+let available = false;
+let endpoint = "";
+
+/** Parse a mudflaps health `implemented` entry ("METHOD path (note)") to a normalized key. */
+function normalizeImplemented(entry: string): string {
+  const stripped = entry.replace(/\s*\(.*\)\s*$/, "").trim();
+  const sp = stripped.indexOf(" ");
+  return normalizeEndpoint(stripped.slice(0, sp), stripped.slice(sp + 1));
+}
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.FLY_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await flapsUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 });
+    endpoint = up.endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) await flapsDown({ name: CONTAINER });
+});
+
+describe("Machines contract ⊆ mudflaps implemented paths", () => {
+  test("the pinned mudflaps serves every endpoint flyApply depends on", async (ctx) => {
+    if (!available) ctx.skip();
+
+    const res = await fetch(`${endpoint}/_mudflaps/health`);
+    expect(res.ok).toBe(true);
+    const health = (await res.json()) as { implemented?: string[] };
+    expect(Array.isArray(health.implemented)).toBe(true);
+
+    const served = new Set((health.implemented ?? []).map(normalizeImplemented));
+
+    const missing = [...contractKeys()].filter((k) => !served.has(k));
+    // A non-empty list means flyApply calls something mudflaps can't serve — a
+    // real fidelity gap between the applier and the pinned emulator.
+    expect(missing, `mudflaps is missing contract endpoints: ${missing.join(", ")}`).toEqual([]);
+  });
+
+  test("flyApply never depends on a mudflaps roadmap (501) endpoint", async (ctx) => {
+    if (!available) ctx.skip();
+    const res = await fetch(`${endpoint}/_mudflaps/health`);
+    const health = (await res.json()) as { unimplemented?: string[] };
+    const roadmap = new Set((health.unimplemented ?? []).map(normalizeImplemented));
+
+    for (const e of MACHINES_CONTRACT) {
+      const key = normalizeEndpoint(e.method, e.path);
+      expect(roadmap.has(key), `${e.op} → ${e.method} ${e.path} is a mudflaps roadmap endpoint`).toBe(false);
+    }
+  });
+});

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

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { MACHINES_CONTRACT, normalizeEndpoint, contractKeys } from "./machines-contract";
+
+describe("MACHINES_CONTRACT", () => {
+  test("covers the flyApply resource operations (apps, machines, leases, volumes, ips, certs, secrets)", () => {
+    for (const area of ["/machines", "/lease", "/volumes", "/ip_assignments", "/certificates", "/secrets"]) {
+      expect(MACHINES_CONTRACT.some((e) => e.path.includes(area)), area).toBe(true);
+    }
+    expect(MACHINES_CONTRACT.some((e) => e.path === "/v1/apps"), "apps").toBe(true);
+  });
+
+  test("every entry has a v1/apps path and a known method", () => {
+    for (const e of MACHINES_CONTRACT) {
+      expect(e.path.startsWith("/v1/apps")).toBe(true);
+      expect(["GET", "POST", "PUT", "DELETE"]).toContain(e.method);
+    }
+  });
+
+  test("normalizeEndpoint collapses param names ({id} ≡ {vol} ≡ {hostname})", () => {
+    expect(normalizeEndpoint("DELETE", "/v1/apps/{app}/volumes/{id}")).toBe(
+      normalizeEndpoint("DELETE", "/v1/apps/{app}/volumes/{vol}"),
+    );
+    expect(normalizeEndpoint("GET", "/v1/apps/{app}")).toBe("GET /v1/apps/{}");
+  });
+
+  test("contractKeys is the deduped normalized set", () => {
+    const keys = contractKeys();
+    expect(keys.has("POST /v1/apps")).toBe(true);
+    expect(keys.has("DELETE /v1/apps/{}/machines/{}")).toBe(true);
+    // lease acquire (POST) and release (DELETE) are distinct keys
+    expect(keys.has("POST /v1/apps/{}/machines/{}/lease")).toBe(true);
+    expect(keys.has("DELETE /v1/apps/{}/machines/{}/lease")).toBe(true);
+  });
+
+  test("every contract path segment appears in the fly-apply.ts source (drift anchor)", () => {
+    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "fly-apply.ts"), "utf-8");
+    const segments = new Set(
+      MACHINES_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 fly-apply.ts`).toContain(seg);
+    }
+  });
+});

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

@@ -0,0 +1,73 @@
+/**
+ * Fly Machines (flaps) API contract — the endpoint set the `flyApply` applier
+ * (./fly-apply.ts) depends on, and the mudflaps counterpart of the hand-authored
+ * Sprites contract (./sprites-contract.ts, #808 T3).
+ *
+ * Unlike Sprites, Machines *does* ship a machine-readable OpenAPI that the fly
+ * resource surface drift-checks against (docs.machines.dev, the rolling-upgrade
+ * path #813). This contract serves a different fidelity axis: it pins the exact
+ * endpoints flyApply calls so the docker-gated coverage test can prove the pinned
+ * mudflaps emulator serves them all. mudflaps carries roadmap endpoints that
+ * answer 501 (currently machines/{id}/signal, /exec, /ps) — flyApply must never
+ * depend on one; if it ever does, the coverage test fails instead of the applier
+ * silently passing against a fake that can't model the call.
+ *
+ * Param names match ./fly-apply.ts's URL builders (`{app}`, `{id}`); the coverage
+ * check normalizes param names before comparing, since mudflaps spells volume
+ * ids `{vol}` and cert hostnames `{hostname}`.
+ */
+
+/** One flaps endpoint the flyApply applier calls. */
+export interface MachinesEndpoint {
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  /** Path template under the flaps base, e.g. `/v1/apps/{app}/machines/{id}`. */
+  path: string;
+  /** The applier operation that calls it. */
+  op: string;
+}
+
+/**
+ * The flaps endpoints ./fly-apply.ts depends on. Keep in sync with the applier —
+ * the unit test asserts every path segment appears in fly-apply.ts.
+ */
+export const MACHINES_CONTRACT: readonly MachinesEndpoint[] = [
+  // Apps
+  { method: "POST", path: "/v1/apps", op: "createApp" },
+  { method: "GET", path: "/v1/apps/{app}", op: "getApp" },
+  { method: "DELETE", path: "/v1/apps/{app}", op: "deleteApp" },
+  // Machines
+  { method: "GET", path: "/v1/apps/{app}/machines", op: "listMachines" },
+  { method: "POST", path: "/v1/apps/{app}/machines", op: "createMachine" },
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}", op: "updateMachine" },
+  { method: "DELETE", path: "/v1/apps/{app}/machines/{id}", op: "destroyMachine" },
+  { method: "GET", path: "/v1/apps/{app}/machines/{id}/wait", op: "waitForMachine" },
+  // Leases
+  { method: "POST", path: "/v1/apps/{app}/machines/{id}/lease", op: "acquireLease" },
+  { method: "DELETE", path: "/v1/apps/{app}/machines/{id}/lease", op: "releaseLease" },
+  // Volumes
+  { method: "GET", path: "/v1/apps/{app}/volumes", op: "listVolumes" },
+  { method: "POST", path: "/v1/apps/{app}/volumes", op: "createVolume" },
+  { method: "DELETE", path: "/v1/apps/{app}/volumes/{id}", op: "deleteVolume" },
+  // IP assignments
+  { method: "GET", path: "/v1/apps/{app}/ip_assignments", op: "listIps" },
+  { method: "POST", path: "/v1/apps/{app}/ip_assignments", op: "allocateIp" },
+  { method: "DELETE", path: "/v1/apps/{app}/ip_assignments/{ip}", op: "releaseIp" },
+  // Certificates
+  { method: "GET", path: "/v1/apps/{app}/certificates", op: "listCerts" },
+  { method: "POST", path: "/v1/apps/{app}/certificates", op: "addCert" },
+  { method: "DELETE", path: "/v1/apps/{app}/certificates/{hostname}", op: "deleteCert" },
+  // Secrets
+  { method: "GET", path: "/v1/apps/{app}/secrets", op: "listSecrets" },
+  { method: "POST", path: "/v1/apps/{app}/secrets/{name}", op: "setSecret" },
+  { method: "DELETE", path: "/v1/apps/{app}/secrets/{name}", op: "deleteSecret" },
+] as const;
+
+/** Normalize a `METHOD path` key: collapse every `{param}` to `{}` so param names match. */
+export function normalizeEndpoint(method: string, path: string): string {
+  return `${method.toUpperCase()} ${path.replace(/\{[^}]+\}/g, "{}")}`;
+}
+
+/** The contract as a set of normalized `METHOD path` keys. */
+export function contractKeys(): Set<string> {
+  return new Set(MACHINES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
+}

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

@@ -0,0 +1,74 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { spritesUp, spritesDown } from "./sprites-emulator";
+import { SPRITES_CONTRACT, normalizeEndpoint, contractKeys } from "./sprites-contract";
+
+// Fidelity check (#808 T3): every endpoint the fly sprite activities depend on
+// (SPRITES_CONTRACT) must be served by the pinned spritzer image. Sprites has no
+// OpenAPI to diff, so spritzer's `/_spritzer/health` implemented-paths list is
+// the machine-readable oracle. If an activity ever calls something the emulator
+// doesn't model, this fails instead of the tests silently passing against a
+// partial fake. Docker required; skipped in CI unless SPRITES_DOCKER=1 (GitHub
+// runners have Docker, so relying on absence would pull the image every run).
+
+const CONTAINER = "chant-spritzer-contract-it";
+const PORT = 4293;
+
+let available = false;
+let endpoint = "";
+
+/** Parse a spritzer health `implemented` entry ("METHOD path (note)") to a normalized key. */
+function normalizeImplemented(entry: string): string {
+  const stripped = entry.replace(/\s*\(.*\)\s*$/, "").trim();
+  const sp = stripped.indexOf(" ");
+  const method = stripped.slice(0, sp);
+  const path = stripped.slice(sp + 1);
+  return normalizeEndpoint(method, path);
+}
+
+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;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) await spritesDown({ name: CONTAINER });
+});
+
+describe("Sprites contract ⊆ spritzer implemented paths (#808 T3)", () => {
+  test("the pinned spritzer serves every endpoint the fly activities depend on", async (ctx) => {
+    if (!available) ctx.skip();
+
+    const res = await fetch(`${endpoint}/_spritzer/health`);
+    expect(res.ok).toBe(true);
+    const health = (await res.json()) as { implemented?: string[] };
+    expect(Array.isArray(health.implemented)).toBe(true);
+
+    const served = new Set((health.implemented ?? []).map(normalizeImplemented));
+
+    const missing = [...contractKeys()].filter((k) => !served.has(k));
+    // A non-empty list means an activity calls something spritzer can't serve —
+    // a real fidelity gap between the contract and the pinned emulator.
+    expect(missing, `spritzer is missing contract endpoints: ${missing.join(", ")}`).toEqual([]);
+  });
+
+  test("each contract endpoint maps to a served path (per-activity report)", async (ctx) => {
+    if (!available) ctx.skip();
+    const res = await fetch(`${endpoint}/_spritzer/health`);
+    const health = (await res.json()) as { implemented?: string[] };
+    const served = new Set((health.implemented ?? []).map(normalizeImplemented));
+
+    for (const e of SPRITES_CONTRACT) {
+      const key = normalizeEndpoint(e.method, e.path);
+      expect(served.has(key), `${e.activity} → ${e.method} ${e.path} not served by spritzer`).toBe(true);
+    }
+  });
+});