@intentius/chant-lexicon-fly 0.90.0 → 0.93.0

package/src/composites/fly-site.ts

@@ -0,0 +1,140 @@
+/**
+ * FlySite composite: a Fly app that serves one app's releases.
+ *
+ * It declares the App, the Machine that serves (behind Fly's proxy on 443 and
+ * 80), and, when asked for, a Volume the app's data lives on, mounted into the
+ * Machine, a public IP, and the app's Secrets. It is the fly lexicon's home
+ * for chud's `FlySite` and `ChudLocalSite` sites (ws-056, #2809): a repo that
+ * `chant workspace upgrade` takes off the chud lexicon declares its Fly site
+ * with it, so `chant workspace graph --composites` lists the site as a
+ * composite instance, and a component that names `FlySite` in its
+ * `composites` deploys it.
+ *
+ * The Machine is the one a release ships to: `chant build --lexicon fly`
+ * serializes the site into a plan with exactly one Machine, so the
+ * `fly-release` steps (a component's deploy, or an Op's `flyRelease`) find it
+ * without being told its name. `image` is what the Machine runs until a
+ * release puts its own image, or its files and start command, on it.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import type { Declarable } from "@intentius/chant/declarable";
+import { Fly } from "../pseudo";
+import {
+  App,
+  IPAddress,
+  Machine,
+  MachineConfig,
+  MachineGuest,
+  MachineMount,
+  MachinePort,
+  MachineService,
+  Secret,
+  Volume,
+} from "../generated/index";
+
+export interface FlySiteProps {
+  /** The App's name. Fly app names are global. */
+  app: string;
+  /** The owning org (default: `Fly.OrgSlug`, which the build resolves from `FLY_ORG`). */
+  org?: string | Declarable;
+  /** Region of the Machine and the Volume (default: `Fly.Region`, from `FLY_REGION`). */
+  region?: string | Declarable;
+  /** The Machine's name (default: "web"). */
+  machine?: string;
+  /** The image the Machine runs until a release replaces it. */
+  image: string;
+  /** The port the app listens on inside the Machine (default: 8080). Fly's proxy sends 443 (TLS) and 80 to it. */
+  port?: number;
+  /** The Machine's env. */
+  env?: Record<string, string>;
+  /** Guest CPU kind (default: "shared"). */
+  cpuKind?: string;
+  /** Guest CPUs (default: 1). */
+  cpus?: number;
+  /** Guest memory in MB (default: 256). */
+  memoryMb?: number;
+  /** A Volume for the app's data, mounted at `path`. It outlives releases. Omitted: no Volume. */
+  volume?: { name: string; sizeGb: number; path: string };
+  /** A public IP of this type (for example "shared_v4"). Omitted: none. */
+  ip?: "shared_v4" | "v4" | "v6";
+  /**
+   * The app's Secrets, by name. An undefined value declares the Secret
+   * without a value, so the release checks the app already has it.
+   */
+  secrets?: Record<string, string | undefined>;
+  /** Per-member defaults for fine-grained overrides. */
+  defaults?: {
+    app?: Partial<Record<string, unknown>>;
+    machine?: Partial<Record<string, unknown>>;
+    volume?: Partial<Record<string, unknown>>;
+  };
+}
+
+/** `APP_SECRET` -> `appSecret`: a Secret's member name, never one of the other members'. */
+function memberName(secret: string): string {
+  const words = secret.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  const name = words.map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join("") || "secret";
+  return ["app", "machine", "volume", "ip"].includes(name) ? `${name}Secret` : name;
+}
+
+/**
+ * Create a FlySite composite. Returns the App and the Machine, and the
+ * Volume, IP and Secrets it was asked for.
+ *
+ * @example
+ * ```ts
+ * import { FlySite } from "@intentius/chant-lexicon-fly";
+ *
+ * export const flySite = FlySite({
+ *   app: "notes",
+ *   region: "iad",
+ *   image: "node:22-slim",
+ *   env: { PORT: "8080", APP_DATA: "/data" },
+ *   volume: { name: "data", sizeGb: 1, path: "/data" },
+ *   ip: "shared_v4",
+ *   secrets: { APP_SECRET: process.env.APP_SECRET || undefined },
+ * });
+ * ```
+ */
+export const FlySite = Composite((props: FlySiteProps) => {
+  const { port = 8080, cpuKind = "shared", cpus = 1, memoryMb = 256, defaults: defs } = props;
+  const region = props.region ?? Fly.Region;
+
+  const app = new App(mergeDefaults({ name: props.app, org_slug: props.org ?? Fly.OrgSlug } as Record<string, unknown>, defs?.app) as ConstructorParameters<typeof App>[0]);
+
+  const volume = props.volume
+    ? new Volume(mergeDefaults({ name: props.volume.name, region, size_gb: props.volume.sizeGb } as Record<string, unknown>, defs?.volume) as ConstructorParameters<typeof Volume>[0])
+    : undefined;
+
+  const config = new MachineConfig({
+    image: props.image,
+    guest: new MachineGuest({ cpu_kind: cpuKind, cpus, memory_mb: memoryMb }),
+    ...(props.volume ? { mounts: [new MachineMount({ volume: props.volume.name, path: props.volume.path })] } : {}),
+    services: [
+      new MachineService({
+        protocol: "tcp",
+        internal_port: port,
+        ports: [new MachinePort({ port: 443, handlers: ["tls", "http"] }), new MachinePort({ port: 80, handlers: ["http"] })],
+      }),
+    ],
+    ...(props.env ? { env: props.env } : {}),
+  });
+
+  const machine = new Machine(mergeDefaults({ name: props.machine ?? "web", region, config } as Record<string, unknown>, defs?.machine) as ConstructorParameters<typeof Machine>[0]);
+
+  const ip = props.ip ? new IPAddress({ type: props.ip }) : undefined;
+
+  const secrets: Record<string, Declarable> = {};
+  for (const [name, value] of Object.entries(props.secrets ?? {})) {
+    secrets[memberName(name)] = new Secret({ name, value } as ConstructorParameters<typeof Secret>[0]);
+  }
+
+  return {
+    app,
+    machine,
+    ...(volume ? { volume } : {}),
+    ...(ip ? { ip } : {}),
+    ...secrets,
+  };
+}, "FlySite");

package/src/describe-resources.test.ts

@@ -126,13 +126,28 @@ describe("describeResources: live machines → ResourceMetadata verdicts", () =>
   });
 
   test("with no readable plan, declared entities are unobserved rather than absent (#1089)", async () => {
+    // Nothing a plan can be rebuilt from (a Secret keys no read): no plan at all.
+    const secrets = entities([["token", "Fly::Machines::Secret"]]);
     const res = await describeResources(
-      { environment: "prod", buildOutput: "", entityNames: ["web"], entities: ENTS, endpoint: ENDPOINT },
+      { environment: "prod", buildOutput: "", entityNames: ["token"], entities: secrets, endpoint: ENDPOINT },
       fakeHttp([]),
     );
     expect(res.resources).toEqual({});
-    expect(res.unobserved?.web?.reason).toBe("read-failed");
-    expect(res.unobserved?.app?.reason).toBe("read-failed");
+    expect(res.unobserved?.token?.reason).toBe("read-failed");
+  });
+
+  test("with no build output, the plan is rebuilt from the declared entities (status --live, #2736)", async () => {
+    const declared = new Map([
+      ["shopApp", { entityType: "Fly::Machines::App", props: { name: APP, org_slug: "personal" } as Record<string, unknown> }],
+      ["web", { entityType: "Fly::Machines::Machine", props: { name: "web" } as Record<string, unknown> }],
+    ]);
+    const res = await describeResources(
+      { environment: "prod", buildOutput: "", entityNames: ["shopApp", "web"], entities: declared, endpoint: ENDPOINT },
+      fakeHttp([liveMachine("web", "nginx:1", { id: "m-web" })]),
+    );
+    expect(res.resources.web?.physicalId).toBe("m-web");
+    expect(res.resources.shopApp?.physicalId).toBe(APP);
+    expect(res.unobserved ?? {}).toEqual({});
   });
 
   test("the owned filter records a withheld declared machine as `filtered`, not absent (#1089)", async () => {

package/src/describe-resources.ts

@@ -31,6 +31,7 @@ import type { ObservationResult, ResourceMetadata, UnobservedEntity } from "@int
 import { normalizeObservation, observation, unobservedAll } from "@intentius/chant/observation";
 import { readOwnership } from "@intentius/chant/ownership";
 import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
+import { readMachineRelease } from "./release-metadata";
 import {
   buildChangeSet,
   renderChangeSet,
@@ -99,6 +100,59 @@ function serializedName(req: FlapsRequest, entityName: string): string {
   return typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
 }
 
+/** The release attributes of a Machine whose metadata names one (#2736). */
+function releaseAttributes(metadata: Record<string, string> | undefined): Record<string, unknown> {
+  const release = readMachineRelease(metadata);
+  return release ? { digest: release.digest, release } : {};
+}
+
+/** A string prop, or undefined. */
+function stringProp(props: Record<string, unknown>, key: string): string | undefined {
+  const v = props[key];
+  return typeof v === "string" && v ? v : undefined;
+}
+
+/**
+ * A plan rebuilt from declared entities (#2736), for a caller that has the
+ * entities and no serialized build. It holds only what a read is keyed by:
+ * each App's name, and each Machine, Volume, IP and Certificate with the App it
+ * belongs to (an `app` prop naming it, else the sole declared App). Returns ""
+ * when there are no entities to rebuild from.
+ */
+export function planFromEntities(
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>,
+): string {
+  const plan: FlyPlan = {};
+  const apps: string[] = [];
+  for (const [name, { entityType, props }] of entities) {
+    if (entityType !== TYPE.app) continue;
+    const appName = stringProp(props, "name") ?? name;
+    apps.push(appName);
+    plan[name] = { endpoint: "/v1/apps", method: "POST", body: { app_name: appName } };
+  }
+  const soleApp = apps.length === 1 ? apps[0] : "{app}";
+  const owning = (props: Record<string, unknown>): string => {
+    const app = props.app;
+    if (typeof app === "string" && app) return app;
+    const ref = app && typeof app === "object" ? (app as { props?: Record<string, unknown> }).props : undefined;
+    return (ref && stringProp(ref, "name")) ?? soleApp;
+  };
+  for (const [name, { entityType, props }] of entities) {
+    const app = owning(props);
+    const base = `/v1/apps/${app}`;
+    if (entityType === TYPE.machine) {
+      plan[name] = { endpoint: `${base}/machines`, method: "POST", body: { name: stringProp(props, "name") ?? name } };
+    } else if (entityType === TYPE.volume) {
+      plan[name] = { endpoint: `${base}/volumes`, method: "POST", body: { name: stringProp(props, "name") ?? name } };
+    } else if (entityType === TYPE.ip) {
+      plan[name] = { endpoint: `${base}/ip_assignments`, method: "POST", body: { type: props.type } };
+    } else if (entityType === TYPE.cert) {
+      plan[name] = { endpoint: `${base}/certificates`, method: "POST", body: { hostname: props.hostname } };
+    }
+  }
+  return Object.keys(plan).length ? JSON.stringify(plan) : "";
+}
+
 /**
  * List live Fly resources over flaps and return them keyed by chant entity name,
  * each tagged with an ownership verdict the core change set reads to decide
@@ -116,10 +170,13 @@ export async function describeResources(
   const result: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
 
-  // Without a readable plan there is nothing to key a read by, so chant never
-  // asks flaps anything — every declared entity is unobserved, not absent
-  // (#1089). Returning an empty map here used to plan a create for each.
-  if (!options.buildOutput) {
+  // `chant components status --live` hands over the declared entities with no
+  // serialized build (#2736): the plan is rebuilt from their props, enough to
+  // key each read by. Without either there is nothing to key a read by, so
+  // chant never asks flaps anything — every declared entity is unobserved, not
+  // absent (#1089). Returning an empty map here used to plan a create for each.
+  const buildOutput = options.buildOutput || planFromEntities(options.entities);
+  if (!buildOutput) {
     return observation(
       result,
       unobservedAll(options.entities.keys(), "read-failed", "no fly plan in the build output to read back", options.entities),
@@ -128,7 +185,7 @@ export async function describeResources(
 
   let plan: FlyPlan;
   try {
-    plan = parsePlan(options.buildOutput);
+    plan = parsePlan(buildOutput);
   } catch (err) {
     return observation(
       result,
@@ -318,11 +375,18 @@ export async function describeResources(
         // boundary types (volumes/ips/certs) get their verdict inferred at the
         // app boundary and carry no marker of their own — absent, not guessed.
         marker: readOwnership(m.config?.metadata, FLY_METADATA_OWNERSHIP_KEYS),
+        // The release the Machine serves (#2736): `digest` is the identity
+        // attribute core's status join compares with the release ledger
+        // (LIVE_IDENTITY_ATTRIBUTES); `release` carries the rest of what its
+        // metadata records. The commit is reported inside `release`, not as
+        // the `gitSha` identity: a rollback serves an earlier commit under the
+        // digest the ledger records again, so only the digest is the join.
         attributes: pruneUndefined({
           app,
           machineName: m.name,
           instanceId: m.instance_id,
           config: m.config,
+          ...releaseAttributes(m.config?.metadata),
         }),
       };
     }

package/src/index.ts

@@ -16,6 +16,12 @@ export { Fly, Region, OrgSlug, AppName, PseudoParameter } from "./pseudo";
 // Ownership marker convention (machine config.metadata keys)
 export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
 
+// The release a Machine serves, in its metadata (#2736): read by
+// describeResources and compared with the release ledger by
+// `chant components status --live`.
+export { RELEASE_METADATA_KEYS, readMachineRelease, withReleaseMetadata } from "./release-metadata";
+export type { MachineRelease } from "./release-metadata";
+
 // Deploy Op composite + typed step builders (#744). `flyDeploy` returns a
 // `boot → build → flyApply → wait → teardown` Op; the step builders wrap the
 // generic `activity()` so the fly activities resolve by name without a core change.
@@ -26,6 +32,10 @@ export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composite
 export { FlyOtelCollector } from "./composites/fly-otel-collector";
 export type { FlyOtelCollectorProps } from "./composites/fly-otel-collector";
 
+// A Fly app that serves one app's releases: App, Machine, and its Volume, IP and Secrets (#2809, ws-056).
+export { FlySite } from "./composites/fly-site";
+export type { FlySiteProps } from "./composites/fly-site";
+
 // Sprite Op step builders. chant #1288 Stage 2: these author
 // `activity("spriteCreate", ...)` steps with authoring-time types derived
 // from this lexicon's own `Sprite*Args` interfaces (`./op/builders.ts`),
@@ -58,11 +68,21 @@ export {
   spriteServiceStop,
   spriteServiceDelete,
   spriteServiceLogs,
+  spriteServicesObserve,
+  spriteServiceRestart,
   spriteTaskCreate,
   spriteTaskRefresh,
   spriteTaskRelease,
   spritesUp,
   spritesDown,
+  flyMachineRelease,
+  flyMachineExec,
+  flyMachineRestart,
+  flyMachineStop,
+  flyMachineVerify,
+  flyMachineRestore,
+  flyRelease,
+  flyRollback,
 } from "./op/builders";
 
 // Generated resources — export everything from generated index.

package/src/op/activities/fly-apply.ts

@@ -797,7 +797,14 @@ export async function pruneSecrets(
 
 export interface FlyApplyArgs {
   /** Path to the #738 serializer's JSON output (entity name → flaps request). */
-  planPath: string;
+  planPath?: string;
+  /**
+   * The plan itself, in place of `planPath` (#2736): a caller that changes the
+   * declared plan before applying it (the release a Machine serves, stamped
+   * into its metadata) passes it here rather than writing a file that may
+   * hold Secret values.
+   */
+  plan?: FlyPlan;
   /** flaps endpoint override (D3). Default: `FLY_FLAPS_BASE_URL` env, else real Fly. */
   endpoint?: string;
   /** Bearer token for real Fly. Default: `FLY_API_TOKEN`. mudflaps ignores it. */
@@ -835,6 +842,11 @@ export interface FlyApplyArgs {
  * because the serializer produced it and the two being out of sync is a bug in
  * the lexicon, not a resource the user declined.
  */
+function readPlanFile(planPath: string | undefined): FlyPlan {
+  if (!planPath) throw new Error("flyApply needs a plan: pass planPath (the fly build output) or plan");
+  return parsePlan(readFileSync(planPath, "utf8"));
+}
+
 export function toApplyResult(result: {
   apps: Array<{ app: string; created: boolean }>;
   machines: Array<{ app: string; name: string; action: "created" | "updated" | "noop" }>;
@@ -892,7 +904,7 @@ export async function flyApply(
   prunedCerts: Array<{ app: string; hostname: string }>;
   prunedSecrets: Array<{ app: string; name: string }>;
 }> {
-  const plan = parsePlan(readFileSync(args.planPath, "utf8"));
+  const plan = args.plan ?? readPlanFile(args.planPath);
   const ctx: ApplyCtx = { base: resolveEndpoint(args) };
   const opts = args.wait ?? {};
 
@@ -1046,7 +1058,7 @@ export async function flyDelete(
   signal?: AbortSignal,
   http: FlyHttp = defaultFlyHttp(args.token),
 ): Promise<{ machines: Array<{ app: string; name: string }>; apps: Array<{ app: string; deleted: boolean }> }> {
-  const plan = parsePlan(readFileSync(args.planPath, "utf8"));
+  const plan = args.plan ?? readPlanFile(args.planPath);
   const ctx: ApplyCtx = { base: resolveEndpoint(args) };
   const opts = args.wait ?? {};
 

package/src/op/activities/fly-release-step.ts

@@ -0,0 +1,32 @@
+/**
+ * `flyRelease`: the `fly-release` capability (../../components/fly-release.ts)
+ * as an Op activity (#2782), so an Op's ship phase runs the same site steps a
+ * component's deploy does: upload and start, each migration once per
+ * environment under a receipt in chant's lifecycle receipt store, verify, and
+ * restore on a failure after the Machine changed.
+ *
+ * An Op has no environment of its own, so the step names the one it ships to
+ * (`environment`); the receipts and the recorded Machine configs are that
+ * environment's, as they are for the component.
+ *
+ * Retrying a release that already serves changes nothing: the apply finds the
+ * Machine's config unchanged, and every migration's receipt matches.
+ */
+
+import type { FlyReleaseInput, FlyReleaseOutput } from "../../components/fly-release";
+
+export interface FlyReleaseArgs extends FlyReleaseInput {
+  /** The environment the release ships to: its receipts and recorded configs. (`env` is the Machine's env, as for the capability.) */
+  environment: string;
+  /** The component the release belongs to, for attribution. Default `app`. */
+  component?: string;
+}
+
+export type FlyReleaseResult = FlyReleaseOutput;
+
+export async function flyRelease(args: FlyReleaseArgs): Promise<FlyReleaseResult> {
+  const { environment, component, ...input } = args;
+  if (!environment) throw new Error("flyRelease: name the environment the release ships to (environment)");
+  const { flyReleaseCapability } = await import("../../components/fly-release");
+  return flyReleaseCapability.run({ env: environment, component: component ?? "app" }, input);
+}

package/src/op/activities/fly-rollback-step.ts

@@ -0,0 +1,33 @@
+/**
+ * `flyRollback`: the `fly-rollback` capability (../../components/fly-release.ts)
+ * as an Op activity (#2800), so a rollback Op puts an earlier release back on
+ * the Machine the way the release Op's `flyRelease` put it there.
+ *
+ * It restores the Machine config `fly-release` recorded for the release it
+ * goes back to (files included), in the environment `environment` names, and
+ * checks that the Machine is started with that release. Given `source`, the
+ * archive is read only once it hashes to its digest, before any flaps call,
+ * and the recorded config must carry exactly that tree, or nothing changes.
+ * A release with no recorded config is refused by name.
+ *
+ * Running it again once the Machine serves the release changes nothing.
+ * Migrations are not undone: the data stays where the later release left it.
+ */
+
+import type { FlyRollbackInput, FlyRollbackOutput } from "../../components/fly-release";
+
+export interface FlyRollbackArgs extends FlyRollbackInput {
+  /** The environment whose recorded Machine configs are read. */
+  environment: string;
+  /** The component the release belongs to, for attribution. Default `app`. */
+  component?: string;
+}
+
+export type FlyRollbackResult = FlyRollbackOutput;
+
+export async function flyRollback(args: FlyRollbackArgs): Promise<FlyRollbackResult> {
+  const { environment, component, ...input } = args;
+  if (!environment) throw new Error("flyRollback: name the environment whose release it restores (environment)");
+  const { flyRollbackCapability } = await import("../../components/fly-release");
+  return flyRollbackCapability.run({ env: environment, component: component ?? "app" }, input);
+}

package/src/op/activities/index.ts

@@ -35,6 +35,36 @@ export {
 } from "./fly-apply";
 export type { FlyApplyArgs, FlyPlan, FlapsRequest, FlapsMachine, FlyHttp, WaitOpts, ApplyCtx } from "./fly-apply";
 
+// The release a Machine serves and the site steps over the Machines API
+// (#2736, ws-056): upload and start, exec (migrations), restart, stop, verify,
+// restore. `loadActivities(["fly"])` binds these by name; the `fly-release`
+// and `fly-rollback` capabilities compose them.
+export {
+  flyMachineRelease,
+  flyMachineExec,
+  flyMachineRestart,
+  flyMachineStop,
+  flyMachineVerify,
+  flyMachineRestore,
+} from "./machine-release";
+// The fly-release capability as an Op step (#2782): a release Op's ship phase.
+export { flyRelease } from "./fly-release-step";
+export type { FlyReleaseArgs, FlyReleaseResult } from "./fly-release-step";
+// The fly-rollback capability as an Op step (#2800): a rollback Op's restore.
+export { flyRollback } from "./fly-rollback-step";
+export type { FlyRollbackArgs, FlyRollbackResult } from "./fly-rollback-step";
+export type {
+  MachineRelease,
+  FlyMachineReleaseArgs,
+  FlyMachineReleaseResult,
+  MachineFile,
+  FlyMachineExecArgs,
+  FlyMachineExecResult,
+  FlyMachineStateArgs,
+  FlyMachineVerifyArgs,
+  FlyMachineRestoreArgs,
+} from "./machine-release";
+
 // mudflaps (Fly Machines API emulator) lifecycle — boots/tears down the local
 // flaps target flyApply is exercised against.
 export {
@@ -120,6 +150,24 @@ export type {
   SpriteServiceLogsResult,
 } from "./sprite-services";
 
+// A sprite's services as resources a ConvergeOp observes and converges (#2778):
+// the observer step and the restart a converge rule dispatches.
+export {
+  spriteServicesObserve,
+  spriteServiceRestart,
+  declaredServices,
+  findSpriteEnv,
+  parseServicesList,
+  probeHealth,
+} from "./sprite-service-converge";
+export type {
+  DeclaredSpriteService,
+  SpriteServicesObserveArgs,
+  SpriteServicesObserveResult,
+  SpriteServiceRestartArgs,
+  SpriteServiceRestartResult,
+} from "./sprite-service-converge";
+
 // Sprite filesystem activities (#848) — imperative file I/O over the fs API.
 // `loadActivities(["fly"])` binds these; the step builders live in core.
 export {

package/src/op/activities/machine-release.integration.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { flapsUp, flapsDown } from "./flaps";
+import { defaultFlyHttp, deleteApp } from "./fly-apply";
+import { findMachine } from "./machine-release";
+import { readMachineRelease } from "../../release-metadata";
+import { createFlyReleaseCapability, createFlyRollbackCapability } from "../../components/fly-release";
+import { memoryMachineConfigStore } from "../../release-store";
+import { describeResources } from "../../describe-resources";
+import type { EffectReceiptRef } from "@intentius/chant/op/receipt-store";
+
+// A release, a migration, a second release and a rollback against a live
+// mudflaps container (#2736): the `fly-release` / `fly-rollback` capabilities
+// over the real Machines wire protocol, then describeResources reading the
+// release back the way `chant components status --live` does. Docker is
+// required; the suite skips in CI unless a job opts in with FLY_IT=1, like
+// ./fly-apply.integration.test.ts. No Fly credentials: mudflaps ignores tokens.
+
+const APP = "chant-release-it";
+const CONTAINER = "chant-mudflaps-release-it";
+const PORT = 4284;
+const WAIT = { intervalMs: 50, timeoutSecs: 5, deadlineMs: 30_000 };
+const http = defaultFlyHttp();
+
+let endpoint = "";
+let available = false;
+let tmp = "";
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.FLY_IT) return;
+  tmp = mkdtempSync(join(tmpdir(), "fly-release-it-"));
+  try {
+    endpoint = (await flapsUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 })).endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (available) {
+    await deleteApp({ base: endpoint }, APP, http).catch(() => undefined);
+    await flapsDown({ name: CONTAINER });
+  }
+  if (tmp) rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("fly-release against mudflaps", () => {
+  test("release, migrate, release again, roll back; the Machine's metadata names each release", async (ctx) => {
+    if (!available) ctx.skip();
+    const planPath = join(tmp, "fly.json");
+    writeFileSync(
+      planPath,
+      JSON.stringify({
+        app: { endpoint: "/v1/apps", method: "POST", body: { app_name: APP, org_slug: "personal" } },
+        web: {
+          endpoint: `/v1/apps/${APP}/machines`,
+          method: "POST",
+          body: { name: "web", region: "iad", config: { image: "nginx:1", metadata: { "managed-by": "chant" } } },
+        },
+      }),
+    );
+    const configs = memoryMachineConfigStore();
+    const receipts = new Map<string, string>();
+    const deps = {
+      http,
+      configStore: () => configs,
+      receiptStore: () => ({
+        read: async (r: EffectReceiptRef) => receipts.get(r.name),
+        write: async (r: EffectReceiptRef, v: string) => void receipts.set(r.name, v),
+      }),
+      headCommit: async () => "1111111111111111111111111111111111111111",
+      log: () => undefined,
+    };
+    const release = createFlyReleaseCapability(deps);
+    const rollback = createFlyRollbackCapability(deps);
+    const c = { env: "it", component: "web" };
+    const common = { plan: planPath, endpoint, wait: WAIT, verify: { intervalMs: 100, timeoutMs: 10_000 } };
+
+    const one = await release.run(c, { ...common, digest: "sha256:one", image: "nginx:1", migrations: [{ name: "001.sql", command: "echo migrate 001" }] });
+    expect(one.migrations).toEqual([{ name: "001.sql", fired: true }]);
+    const two = await release.run(c, { ...common, digest: "sha256:two", image: "nginx:2", migrations: [{ name: "001.sql", command: "echo migrate 001" }] });
+    expect(two.migrations).toEqual([{ name: "001.sql", fired: false }]);
+    expect(two.previous?.digest).toBe("sha256:one");
+
+    let m = await findMachine({ base: endpoint }, APP, "web", http);
+    expect(readMachineRelease(m?.config?.metadata)).toMatchObject({ digest: "sha256:two", previousDigest: "sha256:one" });
+    expect(m?.config?.image).toBe("nginx:2");
+
+    const observed = await describeResources(
+      {
+        environment: "it",
+        buildOutput: "",
+        entityNames: ["app", "web"],
+        entities: new Map([
+          ["app", { entityType: "Fly::Machines::App", props: { name: APP } }],
+          ["web", { entityType: "Fly::Machines::Machine", props: { name: "web" } }],
+        ]),
+        endpoint,
+      },
+      http,
+    );
+    expect((observed.resources.web?.attributes as { digest?: string }).digest).toBe("sha256:two");
+
+    const back = await rollback.run(c, { plan: planPath, endpoint, wait: WAIT, verify: { intervalMs: 100, timeoutMs: 10_000 } });
+    expect(back.digest).toBe("sha256:one");
+    m = await findMachine({ base: endpoint }, APP, "web", http);
+    expect(m?.config?.image).toBe("nginx:1");
+    expect(readMachineRelease(m?.config?.metadata)?.digest).toBe("sha256:one");
+  }, 120_000);
+});