@intentius/chant-lexicon-fly 0.90.0 → 0.91.0

package/dist/op/activities/machines-fake.d.ts

@@ -0,0 +1,53 @@
+/**
+ * An in-memory Fly Machines (flaps) API, as a {@link FlyHttp} (#2736).
+ *
+ * The twin of ./sprites-fake.ts for the Machines side: the endpoints the
+ * applier (./fly-apply.ts) and the release activities (./machine-release.ts)
+ * call, answered from memory with the response shapes flaps and mudflaps use.
+ * Unit tests inject it where the default client would reach the network; the
+ * docker-gated tests run the same activities against the pinned mudflaps.
+ *
+ * Not an activity: nothing in ./index.ts exports it, so `loadActivities`
+ * never binds it.
+ */
+import type { FlyHttp } from "./fly-apply.js";
+/** One Machine the fake holds. */
+export interface FakeMachine {
+    id: string;
+    name: string;
+    state: string;
+    instance_id: string;
+    config: Record<string, unknown> & {
+        metadata?: Record<string, string>;
+    };
+}
+/** What an `exec` answers: the Machines API's exec envelope. */
+export interface FakeExecResult {
+    exit_code: number;
+    stdout?: string;
+    stderr?: string;
+}
+export interface MachinesFake {
+    http: FlyHttp;
+    apps: Set<string>;
+    machines: Map<string, FakeMachine[]>;
+    /** Every exec, in order: the app, the machine id and the command. */
+    execs: Array<{
+        app: string;
+        id: string;
+        command: string[];
+    }>;
+    /** Every call, as `METHOD path` (no base, no query). */
+    calls: string[];
+    /** The live machine named `name` in `app`, if any. */
+    machine(app: string, name: string): FakeMachine | undefined;
+}
+export interface MachinesFakeOptions {
+    /** Answer an exec. Default: exit 0 with no output. */
+    exec?: (app: string, machine: FakeMachine, command: string[]) => FakeExecResult;
+    /** The state a created or updated machine settles in. Default `started`. */
+    settle?: (machine: FakeMachine) => string;
+}
+/** A fresh in-memory flaps. */
+export declare function createMachinesFake(options?: MachinesFakeOptions): MachinesFake;
+//# sourceMappingURL=machines-fake.d.ts.map

package/dist/op/activities/machines-fake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machines-fake.d.ts","sourceRoot":"","sources":["../../../src/op/activities/machines-fake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,kCAAkC;AAClC,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CACzE;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;IACrC,qEAAqE;IACrE,KAAK,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC7D,wDAAwD;IACxD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,sDAAsD;IACtD,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,CAAC;IAChF,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;CAC3C;AAOD,+BAA+B;AAC/B,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CA4GlF"}

package/dist/op/builders.d.ts

@@ -33,6 +33,7 @@ import type { SpriteApplyNetworkPolicyArgs, SpriteApplyServicesArgs } from "./ac
 import type { SpriteServiceCreateArgs, SpriteServiceGetArgs, SpriteServiceListArgs, SpriteServiceStartArgs, SpriteServiceStopArgs, SpriteServiceDeleteArgs, SpriteServiceLogsArgs } from "./activities/sprite-services.js";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks.js";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator.js";
+import type { FlyMachineReleaseArgs, FlyMachineExecArgs, FlyMachineStateArgs, FlyMachineVerifyArgs, FlyMachineRestoreArgs } from "./activities/machine-release.js";
 type StepOpts = {
     profile?: ActivityStep["profile"];
 };
@@ -88,5 +89,17 @@ export declare const spriteTaskRelease: (args: WithStepRefs<SpriteTaskReleaseArg
 export declare const spritesUp: (args?: WithStepRefs<SpritesUpArgs> & StepOpts) => NamedActivityStep;
 /** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
 export declare const spritesDown: (args?: WithStepRefs<SpritesDownArgs> & StepOpts) => NamedActivityStep;
+/** Apply the plan with the Machine serving a release (its digest in the Machine's metadata). Defaults to the `longInfra` profile. */
+export declare const flyMachineRelease: (args: WithStepRefs<FlyMachineReleaseArgs> & StepOpts) => NamedActivityStep;
+/** Run a command inside a Machine (a migration). Defaults to the `atMostOnce` profile: chant cannot know the command is safe to repeat. */
+export declare const flyMachineExec: (args: WithStepRefs<FlyMachineExecArgs> & StepOpts) => NamedActivityStep;
+/** Restart a Machine under a lease and wait for it to be started. Defaults to the `longInfra` profile. */
+export declare const flyMachineRestart: (args: WithStepRefs<FlyMachineStateArgs> & StepOpts) => NamedActivityStep;
+/** Stop a Machine under a lease. Defaults to the `longInfra` profile. */
+export declare const flyMachineStop: (args: WithStepRefs<FlyMachineStateArgs> & StepOpts) => NamedActivityStep;
+/** Check a Machine is started with a release, and its health endpoint answers. Defaults to the `longInfra` profile. */
+export declare const flyMachineVerify: (args: WithStepRefs<FlyMachineVerifyArgs> & StepOpts) => NamedActivityStep;
+/** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
+export declare const flyMachineRestore: (args: WithStepRefs<FlyMachineRestoreArgs> & StepOpts) => NamedActivityStep;
 export {};
 //# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"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"}

package/dist/release-metadata.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The release a Fly Machine serves, as its metadata records it (#2736, ws-056).
+ *
+ * Pure: the keys, a reader, and a writer over a Machine config. The Machines
+ * activities (./op/activities/machine-release.ts) stamp these on a release,
+ * `describeResources` (./describe-resources.ts) reads them back, and
+ * `chant components status --live` compares the digest with the release
+ * ledger.
+ */
+/**
+ * The Machine metadata keys that say which release it serves. Fly metadata is
+ * a string map, so each field is its own key.
+ *
+ * - `digest`: the release's digest, the release ledger's join key.
+ * - `gitSha`: the commit the release was built from.
+ * - `release`: an optional human label (a tag, a release id).
+ * - `previousDigest`: the release this one replaced when it first shipped, so
+ *   a rollback knows where to go back to with no history of its own.
+ */
+export declare const RELEASE_METADATA_KEYS: {
+    readonly digest: "chant-release-digest";
+    readonly gitSha: "chant-release-git-sha";
+    readonly release: "chant-release";
+    readonly previousDigest: "chant-release-previous-digest";
+};
+/** A release, as a Machine's metadata records it. */
+export interface MachineRelease {
+    /** The release's digest (`sha256:...`): what the release ledger records. */
+    digest: string;
+    /** The commit it was built from. */
+    gitSha?: string;
+    /** A human label for it. */
+    release?: string;
+    /** The digest of the release it replaced, when there was one. */
+    previousDigest?: string;
+}
+export type MachineConfig = Record<string, unknown> & {
+    metadata?: Record<string, string>;
+    env?: Record<string, string>;
+};
+/** The release a Machine's metadata names, or undefined when it names none. Pure. */
+export declare function readMachineRelease(metadata: Record<string, string> | null | undefined): MachineRelease | undefined;
+/**
+ * A Machine config serving `release`: a copy of `config` with the release's
+ * metadata keys set (and any it does not carry removed). Pure.
+ */
+export declare function withReleaseMetadata(config: MachineConfig | undefined, release: MachineRelease): MachineConfig;
+//# sourceMappingURL=release-metadata.d.ts.map

package/dist/release-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-metadata.d.ts","sourceRoot":"","sources":["../src/release-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB;;;;;CAKxB,CAAC;AAEX,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAE1H,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAYlH;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,aAAa,CAU7G"}

package/dist/release-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where a Fly release's Machine config is kept, so a rollback can put it back
+ * (#2736, ws-056).
+ *
+ * The Machine's metadata says which release it serves and which one it
+ * replaced; the config that earlier release applied is kept on the
+ * `chant/lifecycle` branch beside the release ledger, one file per release at
+ * `<env>/fly/<app>/<machine>/<digest>.json`. It is written through core's
+ * ledger plumbing, so a workspace member's copy lands under its own prefix,
+ * and every checkout that fetches the branch can roll back.
+ *
+ * Not exported from the package entry point: it spawns git, which stays off
+ * the build path. The `fly-release` and `fly-rollback` capabilities import it.
+ */
+/** Which Machine and release a config belongs to. */
+export interface MachineConfigRef {
+    app: string;
+    machine: string;
+    digest: string;
+}
+/** A store of the Machine config each release applied. */
+export interface MachineConfigStore {
+    read(ref: MachineConfigRef): Promise<Record<string, unknown> | undefined>;
+    write(ref: MachineConfigRef, config: Record<string, unknown>): Promise<void>;
+}
+/** The file a release's Machine config is kept in, under the environment's ledger directory. */
+export declare function machineConfigFile(ref: MachineConfigRef): string;
+/** The lifecycle-branch store for `environment`. */
+export declare function lifecycleMachineConfigStore(environment: string, opts?: {
+    cwd?: string;
+}): MachineConfigStore;
+/** An in-memory store, for tests and for a caller with nowhere to keep configs. */
+export declare function memoryMachineConfigStore(): MachineConfigStore & {
+    entries: Map<string, Record<string, unknown>>;
+};
+//# sourceMappingURL=release-store.d.ts.map

package/dist/release-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-store.d.ts","sourceRoot":"","sources":["../src/release-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IAC1E,KAAK,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9E;AAID,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAE/D;AAED,oDAAoD;AACpD,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,kBAAkB,CAgB5G;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,IAAI,kBAAkB,GAAG;IAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,CAYjH"}

package/dist/skills/chant-fly-ops.md

@@ -53,3 +53,36 @@ Each prune logs the resource and endpoint it removed, so a prune run is auditabl
 ## Re-applying is safe
 
 A re-apply of an unchanged stack is a no-op per resource: machines whose config is structurally equal to live are skipped, volumes and certificates that already exist are skipped, and an IP of an already-present family is skipped. Only apply-only secrets are always re-set, because flaps exposes no value to diff against.
+
+## Releases on a Machine
+
+A component can deploy to Fly with this lexicon alone. It declares an `App` and the `Machine` that serves, builds them with `chant build --lexicon fly -o dist/fly.json`, and deploys with the `fly-release` step. Here a `Publish` phase (`publish-image`, elided) pushes the image, and the release serves it by digest:
+
+```ts
+import { phase, type Component } from "@intentius/chant/components";
+
+export const web: Component = {
+  name: "web",
+  deploy: [
+    phase("Publish", [/* publish-image */]),
+    phase("Release", [
+      {
+        kind: "fly-release",
+        plan: "dist/fly.json",
+        digest: "@Publish.digest",
+        image: "@Publish.uri",
+        migrations: [{ name: "001_init.sql", command: "node migrate.js 001_init.sql" }],
+        verify: { url: "https://web.example.com", healthPath: "/health" },
+      },
+    ]),
+  ],
+};
+```
+
+The step updates the Machine in place with the release in its `config.metadata`: `chant-release-digest`, `chant-release-git-sha` (the commit, `git rev-parse HEAD` unless given), and `chant-release-previous-digest` (the release it replaced). Each migration then runs inside the Machine through the Machines API's exec, once per environment: its receipt is kept on `chant/lifecycle` at `<env>/receipts/`, and a migration fires again only when its `sha` (or command) changes. After a migration fires, the Machine restarts, and the step checks that it is started with this release and, given a `url`, that its health endpoint answers with this commit or digest. If anything fails after the Machine changed, the step puts back the config the Machine served before (on a first release, it stops the Machine) and fails.
+
+The step's output carries `uri` and `digest`, so `chant run --components web --env prod` records the release in the ledger. `chant components status prod --live` reads the Machine's metadata back and compares its digest with the ledger's: the row is `reconciled` when they agree and `drifted` when the Machine serves something the ledger does not name. The component joins the Machine by name: name the component after the Machine entity, or list it in `liveNames`.
+
+Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
+
+The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "type": "module",
   "files": [
     "src/",
@@ -63,7 +63,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.90.0",
+    "@intentius/chant": "^0.91.0",
     "typescript": "^5.9.3"
   },
   "description": "Fly.io Machines lexicon for chant — declarative IaC in TypeScript",

package/src/components/capability-plugin.ts

@@ -2,8 +2,9 @@
  * `flyCapabilityPlugin` — the fly lexicon's capability plugin (#1942, epic
  * #1564 phase 2).
  *
- * One leaf so far: `run-agent`, the sprite-lifecycle-backed agent-turn verb
- * (`./run-agent.ts`). Contributed through core's `CapabilityPlugin` contract
+ * Leaves: `run-agent`, the sprite-lifecycle-backed agent-turn verb
+ * (`./run-agent.ts`), and `fly-release` / `fly-rollback`, a release served by
+ * a Fly Machine (`./fly-release.ts`, #2736). Contributed through core's `CapabilityPlugin` contract
  * the same way aws contributes `cfn-deploy` and helm contributes
  * `helm-upgrade` (docs/components/cloud-boundary) — a project declaring
  * `lexicons: ["fly"]` gets `run-agent` registered automatically when it runs
@@ -15,9 +16,12 @@
 import type { Capability } from "@intentius/chant/components/capability";
 import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
 import { flyRunAgentCapability } from "./run-agent";
+import { flyReleaseCapability, flyRollbackCapability } from "./fly-release";
 
 export const FLY_VERB_FAMILIES = {
   agentExecution: ["run-agent"],
+  // A release served by a Fly Machine, and going back to an earlier one (#2736).
+  apply: ["fly-release", "fly-rollback"],
 } as const;
 
 export const flyCapabilityPlugin: CapabilityPlugin = {
@@ -28,7 +32,11 @@ export const flyCapabilityPlugin: CapabilityPlugin = {
     return ownPackageVersion(import.meta.url);
   },
   capabilities(): Array<Capability<never, unknown>> {
-    return [flyRunAgentCapability as Capability<never, unknown>];
+    return [
+      flyRunAgentCapability as Capability<never, unknown>,
+      flyReleaseCapability as Capability<never, unknown>,
+      flyRollbackCapability as Capability<never, unknown>,
+    ];
   },
   families(): Record<string, readonly string[]> {
     return FLY_VERB_FAMILIES;

package/src/components/fly-release.test.ts

@@ -0,0 +1,244 @@
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach } from "vitest";
+import type { DeployContext } from "@intentius/chant/components/capability";
+import type { EffectReceiptRef, ReceiptStore } from "@intentius/chant/op/receipt-store";
+import { buildChangeSet } from "@intentius/chant/lifecycle/change-set";
+import { liveEvidenceFromChangeSet, reconcileStatus, type EntityLiveRead } from "@intentius/chant/lifecycle/status";
+import type { ReleaseRecord } from "@intentius/chant/lifecycle/release-ledger";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { createFlyReleaseCapability, createFlyRollbackCapability, migrationReceipt, type FlyReleaseDeps } from "./fly-release";
+import { flyCapabilityPlugin } from "./capability-plugin";
+import { createMachinesFake, type MachinesFake } from "../op/activities/machines-fake";
+import { memoryMachineConfigStore } from "../release-store";
+import { readMachineRelease } from "../release-metadata";
+import { describeResources } from "../describe-resources";
+
+const ENDPOINT = "http://flaps.test";
+const NO_WAIT = { intervalMs: 0, deadlineMs: 2_000 };
+const CTX: DeployContext = { env: "prod", component: "shop" };
+
+const PLAN = {
+  shop: { endpoint: "/v1/apps", method: "POST", body: { app_name: "shop", org_slug: "personal" } },
+  web: {
+    endpoint: "/v1/apps/shop/machines",
+    method: "POST",
+    body: { name: "web", config: { image: "shop:declared", metadata: { "managed-by": "chant" } } },
+  },
+};
+
+function memoryReceipts(): ReceiptStore & { values: Map<string, string> } {
+  const values = new Map<string, string>();
+  return {
+    values,
+    read: async (r: EffectReceiptRef) => values.get(r.name),
+    write: async (r: EffectReceiptRef, v: string) => void values.set(r.name, v),
+  };
+}
+
+let dir: string;
+let planPath: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "fly-release-"));
+  planPath = join(dir, "fly.json");
+  writeFileSync(planPath, JSON.stringify(PLAN));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function setup(fake: MachinesFake = createMachinesFake()) {
+  const configs = memoryMachineConfigStore();
+  const receipts = memoryReceipts();
+  const lines: string[] = [];
+  const deps: FlyReleaseDeps = {
+    http: fake.http,
+    configStore: () => configs,
+    receiptStore: () => receipts,
+    headCommit: async () => "0000000000000000000000000000000000000000",
+    log: (l) => lines.push(l),
+  };
+  return {
+    fake,
+    configs,
+    receipts,
+    lines,
+    release: createFlyReleaseCapability(deps),
+    rollback: createFlyRollbackCapability(deps),
+  };
+}
+
+const input = (digest: string, extra: Record<string, unknown> = {}) => ({
+  plan: planPath,
+  digest,
+  gitSha: `${digest.slice(7, 14)}`,
+  endpoint: ENDPOINT,
+  wait: NO_WAIT,
+  verify: { intervalMs: 1, timeoutMs: 20 },
+  ...extra,
+});
+
+describe("fly-release", () => {
+  test("is registered by the fly capability plugin, with a native rollback", () => {
+    const kinds = flyCapabilityPlugin.capabilities().map((c) => c.kind);
+    expect(kinds).toEqual(expect.arrayContaining(["fly-release", "fly-rollback"]));
+    const release = flyCapabilityPlugin.capabilities().find((c) => c.kind === "fly-release");
+    expect(release?.rollbackPolicy).toBe("native");
+  });
+
+  test("serves the release, records it on the Machine, and returns what the ledger records", async () => {
+    const s = setup();
+    const out = await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { image: "shop@sha256:img" }));
+    expect(out).toMatchObject({ uri: "fly://shop/web", digest: "sha256:aaaaaaaaaaaa", app: "shop", previous: null, migrations: [] });
+    const m = s.fake.machine("shop", "web")!;
+    expect(m.config.image).toBe("shop@sha256:img");
+    expect(readMachineRelease(m.config.metadata)).toEqual({ digest: "sha256:aaaaaaaaaaaa", gitSha: "aaaaaaa" });
+    // The config it applied is kept for a later rollback.
+    expect(await s.configs.read({ app: "shop", machine: "web", digest: "sha256:aaaaaaaaaaaa" })).toEqual(m.config);
+  });
+
+  test("the commit defaults to HEAD, as the ledger records it", async () => {
+    const s = setup();
+    const out = await s.release.run(CTX, { ...input("sha256:aaaaaaaaaaaa"), gitSha: undefined });
+    expect(out.gitSha).toBe("0000000000000000000000000000000000000000");
+  });
+
+  test("each migration fires once per environment, then the Machine restarts", async () => {
+    const s = setup();
+    const migrations = [
+      { name: "001_init.sql", command: "node migrate.js 001_init.sql", sha: "sha256:m1" },
+      { name: "002_add.sql", command: ["node", "migrate.js", "002_add.sql"] },
+    ];
+    const first = await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { migrations }));
+    expect(first.migrations).toEqual([
+      { name: "001_init.sql", fired: true },
+      { name: "002_add.sql", fired: true },
+    ]);
+    expect(s.fake.execs.map((e) => e.command)).toEqual([
+      ["sh", "-c", "node migrate.js 001_init.sql"],
+      ["node", "migrate.js", "002_add.sql"],
+    ]);
+    expect(s.fake.calls.some((c) => c.endsWith("/restart"))).toBe(true);
+    expect(s.receipts.values.get("fly-migration:shop/001_init.sql")).toBe("sha256:m1");
+
+    const second = await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { migrations: [...migrations, { name: "003.sql", command: "m 3" }] }));
+    expect(second.migrations).toEqual([
+      { name: "001_init.sql", fired: false },
+      { name: "002_add.sql", fired: false },
+      { name: "003.sql", fired: true },
+    ]);
+    expect(s.fake.execs).toHaveLength(3);
+  });
+
+  test("a failed migration restores the previous release's config, leaves its receipt unwritten, and fails", async () => {
+    const fake = createMachinesFake({ exec: (_a, _m, cmd) => (cmd.join(" ").includes("boom") ? { exit_code: 1, stderr: "boom" } : { exit_code: 0 }) });
+    const s = setup(fake);
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { image: "shop:1" }));
+    const before = structuredClone(fake.machine("shop", "web")!.config);
+    await expect(
+      s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { image: "shop:2", migrations: [{ name: "004.sql", command: "boom" }] })),
+    ).rejects.toThrow(/exited 1/);
+    expect(fake.machine("shop", "web")!.config).toEqual(before);
+    expect(s.receipts.values.has("fly-migration:shop/004.sql")).toBe(false);
+    expect(await s.configs.read({ app: "shop", machine: "web", digest: "sha256:bbbbbbbbbbbb" })).toBeUndefined();
+  });
+
+  test("a failed first release stops the Machine: nothing was served before", async () => {
+    const fake = createMachinesFake({ exec: () => ({ exit_code: 2 }) });
+    const s = setup(fake);
+    await expect(s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { migrations: [{ name: "1", command: "x" }] }))).rejects.toThrow();
+    expect(fake.machine("shop", "web")!.state).toBe("stopped");
+  });
+
+  test("its saga rollback puts back the previous release's Machine config", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { image: "shop:1" }));
+    const one = structuredClone(s.fake.machine("shop", "web")!.config);
+    const i2 = input("sha256:bbbbbbbbbbbb", { image: "shop:2" });
+    const out = await s.release.run(CTX, i2);
+    expect(out.previous?.digest).toBe("sha256:aaaaaaaaaaaa");
+    await s.release.rollback!(CTX, i2, out);
+    expect(s.fake.machine("shop", "web")!.config).toEqual(one);
+  });
+
+  test("a Machine released before configs were kept can still be rolled back to", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { image: "shop:1" }));
+    s.configs.entries.clear();
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { image: "shop:2" }));
+    expect(await s.configs.read({ app: "shop", machine: "web", digest: "sha256:aaaaaaaaaaaa" })).toBeDefined();
+  });
+});
+
+describe("fly-rollback", () => {
+  test("restores the previous release's Machine config, and names it for the ledger", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa", { image: "shop:1" }));
+    const one = structuredClone(s.fake.machine("shop", "web")!.config);
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb", { image: "shop:2" }));
+    const back = await s.rollback.run(CTX, { plan: planPath, endpoint: ENDPOINT, wait: NO_WAIT, verify: { intervalMs: 1, timeoutMs: 20 } });
+    expect(back).toMatchObject({ uri: "fly://shop/web", digest: "sha256:aaaaaaaaaaaa", gitSha: "aaaaaaa", previous: { digest: "sha256:bbbbbbbbbbbb" } });
+    expect(s.fake.machine("shop", "web")!.config).toEqual(one);
+  });
+
+  test("with no release before the serving one, it refuses", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa"));
+    await expect(s.rollback.run(CTX, { plan: planPath, endpoint: ENDPOINT })).rejects.toThrow(/no release before it/);
+  });
+
+  test("to a digest with no recorded config, it refuses", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa"));
+    await expect(s.rollback.run(CTX, { plan: planPath, endpoint: ENDPOINT, to: "sha256:zzz" })).rejects.toThrow(/no recorded Machine config/);
+  });
+});
+
+describe("components status --live over a Fly release", () => {
+  const record = (digest: string): ReleaseRecord => ({
+    version: 1,
+    component: "web",
+    env: "prod",
+    digest,
+    gitSha: "0000000",
+    runId: "run-1",
+    timestamp: "2026-09-25T00:00:00.000Z",
+    actor: "lex00",
+  });
+
+  async function status(fake: MachinesFake, recorded: string) {
+    const entities = new Map([
+      ["shop", { entityType: "Fly::Machines::App", props: { name: "shop" } as Record<string, unknown> }],
+      ["web", { entityType: "Fly::Machines::Machine", props: { name: "web" } as Record<string, unknown> }],
+    ]);
+    const observed = normalizeObservation(
+      await describeResources({ environment: "prod", buildOutput: "", entityNames: ["shop", "web"], entities, endpoint: ENDPOINT }, fake.http),
+    );
+    const cs = buildChangeSet("prod", { declared: new Set(entities.keys()), observedNow: observed.resources, observedThen: undefined, unobserved: observed.unobserved }, { lexicon: "fly" });
+    const observations = new Map<string, EntityLiveRead>(cs.entries.map((e) => [e.name, { now: observed.resources[e.name] }]));
+    const evidence = liveEvidenceFromChangeSet(cs, undefined, { observations });
+    return reconcileStatus("prod", [record(recorded)], { liveEvidence: evidence }).find((r) => r.component === "web")!;
+  }
+
+  test("the Machine's release is compared with the ledger: reconciled when they agree, drifted when not", async () => {
+    const s = setup();
+    await s.release.run(CTX, input("sha256:aaaaaaaaaaaa"));
+    await s.release.run(CTX, input("sha256:bbbbbbbbbbbb"));
+
+    const agreed = await status(s.fake, "sha256:bbbbbbbbbbbb");
+    expect(agreed.reconciliation).toBe("reconciled");
+
+    // The Machine rolled back with no ledger record: live and recorded disagree.
+    await s.rollback.run(CTX, { plan: planPath, endpoint: ENDPOINT, wait: NO_WAIT, verify: { intervalMs: 1, timeoutMs: 20 } });
+    const drifted = await status(s.fake, "sha256:bbbbbbbbbbbb");
+    expect(drifted.reconciliation).toBe("drifted");
+    expect(drifted.detail).toContain("reports digest sha256:aaaaaaaaaaaa");
+  });
+
+  test("the migration receipt is named for the app and migration", () => {
+    expect(migrationReceipt("shop", { name: "001.sql", command: "x", sha: "sha256:1" })).toMatchObject({
+      ref: { name: "fly-migration:shop/001.sql", effect: "fly-migrate", flavor: "hash" },
+      expectation: "sha256:1",
+    });
+  });
+});