@intentius/chant-lexicon-fly 0.90.0 → 0.91.0

package/src/components/fly-release.ts

@@ -0,0 +1,341 @@
+/**
+ * `fly-release` and `fly-rollback`: a component deploying to Fly with this
+ * lexicon alone (#2736, ws-056), in place of chud's `Chud::FlySite`.
+ *
+ * A component declares its App and Machine as this lexicon's resources, builds
+ * them (`chant build --lexicon fly -o <plan>`), and deploys with one step:
+ *
+ * ```ts
+ * { kind: "fly-release", plan: "dist/fly.json", digest: "@app.publish.digest",
+ *   image: "@app.publish.uri", migrations: [{ name: "001_init.sql", command: "node migrate.js 001_init.sql" }] }
+ * ```
+ *
+ * `fly-release` runs the site steps in order, as the Machines activities
+ * (../op/activities/machine-release.ts):
+ *
+ * 1. upload and start: apply the plan with the Machine serving the release,
+ *    its digest and commit in the Machine's metadata;
+ * 2. migrate: each migration runs inside the Machine once per environment,
+ *    witnessed by a receipt in chant's lifecycle receipt store
+ *    (`@intentius/chant/op/lifecycle-receipt-store`), then the Machine restarts
+ *    on the migrated data;
+ * 3. verify: the Machine is started with this release, and its health
+ *    endpoint answers when a URL is given;
+ * 4. on a failure after the Machine changed, restore: the config it replaced
+ *    goes back (or, on a first release, the Machine is stopped), and the step
+ *    fails.
+ *
+ * Its output carries `uri` and `digest`, so `chant run --components` records
+ * the release in the ledger, and the Machine's metadata carries the same
+ * digest, which `chant components status --live` compares with it.
+ *
+ * Each release's Machine config is kept on the lifecycle branch
+ * (../release-store.ts). `fly-rollback` puts back the config of the release
+ * the serving one replaced (or the digest it is given), which is also the
+ * saga compensation `fly-release` declares.
+ */
+
+import { createHash } from "node:crypto";
+import type { Capability, DeployContext } from "@intentius/chant/components/capability";
+import type { ReceiptStore, EffectReceiptRef } from "@intentius/chant/op/receipt-store";
+import {
+  findMachine,
+  flyMachineExec,
+  flyMachineRelease,
+  flyMachineRestart,
+  flyMachineRestore,
+  flyMachineStop,
+  flyMachineVerify,
+  readMachineRelease,
+  releaseTarget,
+  type MachineRelease,
+} from "../op/activities/machine-release";
+import { defaultFlyHttp, parsePlan, resolveEndpoint, type FlyHttp, type WaitOpts } from "../op/activities/fly-apply";
+import type { MachineConfigStore } from "../release-store";
+import { readFileSync } from "node:fs";
+
+/** One migration, run inside the Machine once per environment. */
+export interface FlyMigration {
+  /** Its name: the receipt is named after it, so a name fires once. */
+  name: string;
+  /** The command, run in the Machine: an argv, or a string run with `sh -c`. */
+  command: string[] | string;
+  /** A digest of the migration's content. A migration whose content changes fires again. Default: a digest of the command. */
+  sha?: string;
+}
+
+/** Health check after the release serves. */
+export interface FlyVerify {
+  /** The app's public URL. Without it, only the Machine's state and metadata are checked. */
+  url?: string;
+  /** Default `/health`. */
+  healthPath?: string;
+  timeoutMs?: number;
+  intervalMs?: number;
+}
+
+export interface FlyReleaseInput {
+  /** Path to the fly build output (`chant build --lexicon fly -o <path>`). */
+  plan: string;
+  /** The Machine that serves, when the plan declares more than one (entity or Machine name). */
+  machine?: string;
+  /** The release's digest: what the ledger records and the Machine's metadata names. */
+  digest: string;
+  /** The commit it was built from. Default: `git rev-parse HEAD`, as the ledger records. */
+  gitSha?: string;
+  /** A human label for the release. */
+  release?: string;
+  /** An image to run in place of the declared one. */
+  image?: string;
+  /** Env added to the declared Machine's env. */
+  env?: Record<string, string>;
+  /** Migrations, in order. */
+  migrations?: FlyMigration[];
+  verify?: FlyVerify;
+  /** flaps endpoint override. Default: `FLY_FLAPS_BASE_URL`, else real Fly. */
+  endpoint?: string;
+  wait?: WaitOpts;
+}
+
+export interface FlyReleaseOutput {
+  /** `fly://<app>/<machine>`: where the release was promoted. */
+  uri: string;
+  digest: string;
+  gitSha?: string;
+  app: string;
+  machine: { id: string; name: string };
+  /** The release the Machine served before this one, when it named one. */
+  previous: MachineRelease | null;
+  /** Each migration, and whether it fired this run. */
+  migrations: Array<{ name: string; fired: boolean }>;
+}
+
+export interface FlyRollbackInput {
+  /** Path to the fly build output, naming the App and Machine. */
+  plan: string;
+  machine?: string;
+  /** The release digest to go back to. Default: the one the serving release replaced. */
+  to?: string;
+  verify?: FlyVerify;
+  endpoint?: string;
+  wait?: WaitOpts;
+}
+
+export interface FlyRollbackOutput {
+  uri: string;
+  /** The release serving now. */
+  digest: string;
+  gitSha?: string;
+  app: string;
+  machine: { id: string; name: string };
+  /** The release it replaced. */
+  previous: MachineRelease | null;
+}
+
+/** What the capabilities reach the world through. Every field has a default; tests replace them. */
+export interface FlyReleaseDeps {
+  http?: FlyHttp;
+  /** The Machine configs each release applied. Default: the lifecycle branch, per environment. */
+  configStore?: (ctx: DeployContext) => MachineConfigStore | Promise<MachineConfigStore>;
+  /** Migration receipts. Default: chant's lifecycle receipt store, per environment. */
+  receiptStore?: (ctx: DeployContext) => ReceiptStore | Promise<ReceiptStore>;
+  /** The commit a release defaults to. Default: `git rev-parse HEAD`. */
+  headCommit?: () => Promise<string>;
+  fetch?: typeof fetch;
+  log?: (line: string) => void;
+}
+
+async function defaultConfigStore(ctx: DeployContext): Promise<MachineConfigStore> {
+  const { lifecycleMachineConfigStore } = await import("../release-store");
+  return lifecycleMachineConfigStore(ctx.env);
+}
+
+async function defaultReceiptStore(ctx: DeployContext): Promise<ReceiptStore> {
+  const { lifecycleReceiptStore } = await import("@intentius/chant/op/lifecycle-receipt-store");
+  return lifecycleReceiptStore({ environment: ctx.env });
+}
+
+async function defaultHeadCommit(): Promise<string> {
+  const { getHeadCommit } = await import("@intentius/chant/lifecycle/git");
+  return getHeadCommit();
+}
+
+const sha256 = (s: string) => `sha256:${createHash("sha256").update(s).digest("hex")}`;
+
+/** The receipt a migration fires under on an app. */
+export function migrationReceipt(app: string, migration: FlyMigration): { ref: EffectReceiptRef; expectation: string } {
+  const command = typeof migration.command === "string" ? migration.command : JSON.stringify(migration.command);
+  return {
+    ref: { name: `fly-migration:${app}/${migration.name}`, effect: "fly-migrate", flavor: "hash", inputs: { app, migration: migration.name } },
+    expectation: migration.sha ?? sha256(command),
+  };
+}
+
+function loadTarget(planPath: string, machine?: string) {
+  const plan = parsePlan(readFileSync(planPath, "utf8"));
+  return { plan, target: releaseTarget(plan, machine) };
+}
+
+const uriOf = (app: string, machine: string) => `fly://${app}/${machine}`;
+
+/** Build the `fly-release` capability. */
+export function createFlyReleaseCapability(deps: FlyReleaseDeps = {}): Capability<FlyReleaseInput, FlyReleaseOutput> {
+  const log = deps.log ?? ((line: string) => console.error(line));
+  const httpFor = () => deps.http ?? defaultFlyHttp();
+
+  async function rollBack(ctx: DeployContext, input: FlyReleaseInput, output?: FlyReleaseOutput): Promise<void> {
+    if (!output) return;
+    const http = httpFor();
+    const target = { app: output.app, machine: output.machine.name, endpoint: input.endpoint };
+    if (!output.previous) {
+      await flyMachineStop({ ...target, wait: input.wait }, undefined, http);
+      log(`fly-release: nothing served before ${output.digest}; stopped ${output.app}/${output.machine.name}`);
+      return;
+    }
+    const store = await (deps.configStore ?? defaultConfigStore)(ctx);
+    const config = await store.read({ app: output.app, machine: output.machine.name, digest: output.previous.digest });
+    if (!config) {
+      throw new Error(`fly-release: no recorded Machine config for ${output.previous.digest} on ${output.app}/${output.machine.name}; nothing to roll back to`);
+    }
+    await flyMachineRestore({ ...target, config, wait: input.wait }, undefined, http);
+    log(`fly-release: rolled ${output.app}/${output.machine.name} back to ${output.previous.digest}`);
+  }
+
+  return {
+    kind: "fly-release",
+    rollbackPolicy: "native",
+    async run(ctx, input) {
+      if (!input.digest) throw new Error("fly-release: a release needs its digest");
+      const http = httpFor();
+      const { plan } = loadTarget(input.plan, input.machine);
+      const gitSha = input.gitSha ?? (await (deps.headCommit ?? defaultHeadCommit)());
+      const configs = await (deps.configStore ?? defaultConfigStore)(ctx);
+
+      const released = await flyMachineRelease(
+        {
+          plan,
+          machine: input.machine,
+          release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
+          image: input.image,
+          env: input.env,
+          endpoint: input.endpoint,
+          wait: input.wait,
+        },
+        undefined,
+        http,
+      );
+      const where = { app: released.app, machine: released.machine.name, endpoint: input.endpoint };
+      log(`fly-release: ${released.app}/${released.machine.name} ${released.action}, serving ${input.digest}`);
+
+      // The config the Machine served before is kept too, so a Machine
+      // released before chant recorded configs can still be rolled back to.
+      const replaced = released.previous?.release;
+      const previousRelease: MachineRelease | null =
+        replaced && replaced.digest !== input.digest
+          ? replaced
+          : released.release.previousDigest
+            ? { digest: released.release.previousDigest }
+            : null;
+      if (replaced && previousRelease?.digest === replaced.digest && !(await configs.read({ app: released.app, machine: released.machine.name, digest: previousRelease.digest }))) {
+        await configs.write({ app: released.app, machine: released.machine.name, digest: previousRelease.digest }, released.previous!.config);
+      }
+
+      const migrations: FlyReleaseOutput["migrations"] = [];
+      try {
+        if (input.migrations?.length) {
+          const receipts = await (deps.receiptStore ?? defaultReceiptStore)(ctx);
+          for (const migration of input.migrations) {
+            const { ref, expectation } = migrationReceipt(released.app, migration);
+            if ((await receipts.read(ref)) === expectation) {
+              migrations.push({ name: migration.name, fired: false });
+              continue;
+            }
+            log(`fly-release: migrating ${migration.name} on ${released.app}/${released.machine.name}`);
+            await flyMachineExec({ ...where, command: migration.command }, undefined, http);
+            // The receipt is written last, on success only: a failed migration fires again next run.
+            await receipts.write(ref, expectation);
+            migrations.push({ name: migration.name, fired: true });
+          }
+          if (migrations.some((m) => m.fired)) await flyMachineRestart({ ...where, wait: input.wait }, undefined, http);
+        }
+        await flyMachineVerify({ ...where, digest: input.digest, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
+      } catch (err) {
+        // Restore: the Machine changed, so put back what it served (or stop it
+        // when it served nothing), then fail the step.
+        try {
+          if (released.previous) {
+            await flyMachineRestore({ ...where, config: released.previous.config, wait: input.wait }, undefined, http);
+            log(`fly-release: restored ${released.app}/${released.machine.name} to ${previousRelease?.digest ?? "its previous config"}`);
+          } else {
+            await flyMachineStop({ ...where, wait: input.wait }, undefined, http);
+            log(`fly-release: nothing had been released on ${released.app}/${released.machine.name}; stopped it`);
+          }
+        } catch (restoreErr) {
+          log(`fly-release: restore failed: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+        }
+        throw err;
+      }
+
+      await configs.write({ app: released.app, machine: released.machine.name, digest: input.digest }, released.config);
+      return {
+        uri: uriOf(released.app, released.machine.name),
+        digest: input.digest,
+        ...(gitSha ? { gitSha } : {}),
+        app: released.app,
+        machine: released.machine,
+        previous: previousRelease,
+        migrations,
+      };
+    },
+    rollback: rollBack,
+  };
+}
+
+/** Build the `fly-rollback` capability. */
+export function createFlyRollbackCapability(deps: FlyReleaseDeps = {}): Capability<FlyRollbackInput, FlyRollbackOutput> {
+  const log = deps.log ?? ((line: string) => console.error(line));
+  const httpFor = () => deps.http ?? defaultFlyHttp();
+
+  async function restoreTo(ctx: DeployContext, input: FlyRollbackInput, app: string, machine: string, digest: string) {
+    const store = await (deps.configStore ?? defaultConfigStore)(ctx);
+    const config = await store.read({ app, machine, digest });
+    if (!config) throw new Error(`fly-rollback: no recorded Machine config for ${digest} on ${app}/${machine}`);
+    const http = httpFor();
+    await flyMachineRestore({ app, machine, config, endpoint: input.endpoint, wait: input.wait }, undefined, http);
+    await flyMachineVerify({ app, machine, digest, endpoint: input.endpoint, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
+    return readMachineRelease((config as { metadata?: Record<string, string> }).metadata);
+  }
+
+  return {
+    kind: "fly-rollback",
+    rollbackPolicy: "native",
+    async run(ctx, input) {
+      const http = httpFor();
+      const { target } = loadTarget(input.plan, input.machine);
+      const live = await findMachine({ base: resolveEndpoint(input) }, target.app, target.name, http);
+      if (!live) throw new Error(`fly-rollback: no machine ${target.name} on app ${target.app}`);
+      const serving = readMachineRelease(live.config?.metadata);
+      const to = input.to ?? serving?.previousDigest;
+      if (!to) throw new Error(`fly-rollback: ${target.app}/${target.name} serves ${serving?.digest ?? "no release"}, with no release before it to roll back to`);
+      const restored = await restoreTo(ctx, input, target.app, target.name, to);
+      log(`fly-rollback: ${target.app}/${target.name} serves ${to} again (was ${serving?.digest ?? "no release"})`);
+      return {
+        uri: uriOf(target.app, target.name),
+        digest: to,
+        ...(restored?.gitSha ? { gitSha: restored.gitSha } : {}),
+        app: target.app,
+        machine: { id: live.id, name: target.name },
+        previous: serving ?? null,
+      };
+    },
+    async rollback(ctx, input, output) {
+      if (!output?.previous) return;
+      await restoreTo(ctx, input, output.app, output.machine.name, output.previous.digest);
+    },
+  };
+}
+
+/** The default `fly-release` capability. */
+export const flyReleaseCapability = createFlyReleaseCapability();
+/** The default `fly-rollback` capability. */
+export const flyRollbackCapability = createFlyRollbackCapability();

package/src/components/index.ts

@@ -12,3 +12,19 @@ export {
   createFlySpriteActivities,
   parseSpriteExecFailure,
 } from "./run-agent";
+export {
+  flyReleaseCapability,
+  flyRollbackCapability,
+  createFlyReleaseCapability,
+  createFlyRollbackCapability,
+  migrationReceipt,
+} from "./fly-release";
+export type {
+  FlyReleaseInput,
+  FlyReleaseOutput,
+  FlyRollbackInput,
+  FlyRollbackOutput,
+  FlyMigration,
+  FlyVerify,
+  FlyReleaseDeps,
+} from "./fly-release";

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.
@@ -63,6 +69,12 @@ export {
   spriteTaskRelease,
   spritesUp,
   spritesDown,
+  flyMachineRelease,
+  flyMachineExec,
+  flyMachineRestart,
+  flyMachineStop,
+  flyMachineVerify,
+  flyMachineRestore,
 } 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/index.ts

@@ -35,6 +35,29 @@ 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";
+export type {
+  MachineRelease,
+  FlyMachineReleaseArgs,
+  FlyMachineReleaseResult,
+  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 {