@intentius/chant-lexicon-fly 0.124.31 → 0.124.33

package/dist/op/activities/fly-release-step.js

@@ -0,0 +1,21 @@
+/**
+ * `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.
+ */
+export async function flyRelease(args) {
+    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.js");
+    return flyReleaseCapability.run({ env: environment, component: component ?? "app" }, input);
+}

package/dist/op/activities/fly-rollback-step.js

@@ -0,0 +1,22 @@
+/**
+ * `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.
+ */
+export async function flyRollback(args) {
+    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.js");
+    return flyRollbackCapability.run({ env: environment, component: component ?? "app" }, input);
+}

package/dist/op/activities/index.js

@@ -0,0 +1,53 @@
+/**
+ * fly Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `fly` lexicon. Contributes the native flaps
+ * applier (`flyApply`), which speaks the Fly Machines REST API directly (no
+ * flyctl, no state file), and the mudflaps emulator lifecycle it is tested
+ * against.
+ */
+export { flyApply, toApplyResult, flyDelete, applyApp, applyMachine, destroyMachine, deleteApp, listMachines, listVolumes, listIps, listCerts, listSecrets, checkSecretExists, pruneMachines, waitForMachine, acquireLease, releaseLease, withLease, resolveEndpoint, parsePlan, isAppRequest, isMachineRequest, isVolumeRequest, isIpRequest, isCertRequest, isSecretRequest, isValuelessSecret, machineAppSegment, resourceAppSegment, secretNameSegment, ipType, declaredIpType, resolveApp, appNameFromRequest, isChantOwned, configEqual, isLeaseConflict, defaultFlyHttp, DEFAULT_FLAPS_BASE_URL, LEASE_NONCE_HEADER, } from "./fly-apply.js";
+// 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.js";
+// The fly-release capability as an Op step (#2782): a release Op's ship phase.
+export { flyRelease } from "./fly-release-step.js";
+// The fly-rollback capability as an Op step (#2800): a rollback Op's restore.
+export { flyRollback } from "./fly-rollback-step.js";
+// mudflaps (Fly Machines API emulator) lifecycle — boots/tears down the local
+// flaps target flyApply is exercised against.
+export { flapsUp, flapsDown, flapsRunCommand, flapsRmCommand, flapsExistsCommand, flapsHealthUrl, flapsEndpoint, } from "./flaps.js";
+// 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, spriteDelete, spriteUrl, resolveSpritesEndpoint, resolveSpritesToken, defaultSpritesHttp, spriteCreateBody, parseCreateResponse, accumulateExecFrames, parseCheckpointNdjson, pickCheckpointByComment, splitCommand, spriteExecWsUrl, DEFAULT_SPRITES_BASE_URL, } from "./sprites.js";
+// Sprite Services activities (#2711) — imperative create/get/list/start/stop/
+// delete/logs for one background service at a time, the single-service
+// primitives underneath `spriteApplyServices`'s batch reconcile.
+// `loadActivities(["fly"])` binds these; the step builders live in core.
+export { spriteServiceCreate, spriteServiceGet, spriteServiceList, spriteServiceStart, spriteServiceStop, spriteServiceDelete, spriteServiceLogs, spriteServiceCreateBody, parseServiceLogNdjson, } from "./sprite-services.js";
+// 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, resolveDeclaredServices, findSpriteEnv, parseServicesList, probeHealth, } from "./sprite-service-converge.js";
+// Sprite filesystem activities (#848) — imperative file I/O over the fs API.
+// `loadActivities(["fly"])` binds these; the step builders live in core.
+export { spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove, spriteFsUrl, defaultSpritesRawHttp, } from "./sprite-fs.js";
+// Sprite config reconcile activities (#849) — the desired-state a Sprite carries:
+// its outbound network policy and its background services. `loadActivities(["fly"])`
+// binds these; the step builders live in core. Apply-activities, not a declarable
+// resource — a Sprite has no build→plan→apply pipeline.
+export { spriteApplyNetworkPolicy, spriteApplyServices, validateNetworkRules, networkRulesEqual, validateServices, serviceConfigEqual, parseServiceDefinitions, listedServiceDiffers, spriteEnvCreateArgs, } from "./sprite-config.js";
+// A box's declared services (#2880), read from its box block with `box: true`.
+export { boxServices, expandServiceCommand, inStartOrder, serviceCommandArgv } from "./box-services.js";
+// Sprite keep-alive Tasks activities (#847) — a hold that stops a Sprite pausing
+// mid-session. `loadActivities(["fly"])` binds these; step builders live in core.
+export { spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease, spriteTasksUrl, spriteTaskUrl, } from "./sprite-tasks.js";
+// 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.js";

package/dist/op/activities/machine-release.js

@@ -0,0 +1,236 @@
+/**
+ * The release a Fly Machine serves, and the Machines activities that put one
+ * there (#2736, ws-056).
+ *
+ * chud's `Chud::FlySite` ran a site as one App served by one Machine and kept
+ * the release in the Machine's metadata. That moves here: the App and the
+ * Machine are this lexicon's own resources, and a release is the declared
+ * Machine with {@link RELEASE_METADATA_KEYS} stamped into its
+ * `config.metadata`. Because the record is on the Machine itself, any checkout
+ * can read which release is serving (`describeResources` reports it, and
+ * `chant components status --live` compares it with the release ledger).
+ *
+ * The site steps are activities over the Machines API, each usable from an
+ * Op by name and composed by the `fly-release` and `fly-rollback` capabilities
+ * (../../components/fly-release.ts):
+ *
+ * - {@link flyMachineRelease}: upload and start. Apply the declared plan with
+ *   the Machine serving the release (its image or env overridden when the
+ *   release says so), and report the release and config it replaced.
+ * - {@link flyMachineExec}: run a command inside the Machine (a migration).
+ * - {@link flyMachineRestart}, {@link flyMachineStop}: under a lease, then
+ *   wait for the Machine to settle.
+ * - {@link flyMachineVerify}: the Machine is started with this release in its
+ *   metadata, and, given a URL, its health endpoint answers.
+ * - {@link flyMachineRestore}: put a recorded Machine config back (restore on
+ *   a failed release, and rollback).
+ *
+ * Every activity takes the flaps endpoint and token the way `flyApply` does
+ * (`FLY_FLAPS_BASE_URL`, `FLY_API_TOKEN`), so the same code reaches mudflaps
+ * or a real Fly org, and an injectable `http` for tests (./machines-fake.ts).
+ */
+import { appNameFromRequest, defaultFlyHttp, flyApply, isAppRequest, isMachineRequest, listMachines, machineAppSegment, resolveApp, resolveEndpoint, waitForMachine, withLease, LEASE_NONCE_HEADER, } from "./fly-apply.js";
+import { parsePlan } from "./fly-apply.js";
+import { readFileSync } from "node:fs";
+import { readMachineRelease, withReleaseMetadata } from "../../release-metadata.js";
+export { RELEASE_METADATA_KEYS, readMachineRelease, withReleaseMetadata } from "../../release-metadata.js";
+/**
+ * The Machine a release targets: the plan's one Machine, or the one `machine`
+ * names (an entity name or a Machine name). Pure.
+ */
+export function releaseTarget(plan, machine) {
+    const appNames = Object.values(plan).filter(isAppRequest).map(appNameFromRequest);
+    const soleApp = appNames.length === 1 ? appNames[0] : undefined;
+    const machines = Object.entries(plan)
+        .filter(([, req]) => isMachineRequest(req))
+        .map(([entity, request]) => ({
+        entity,
+        request,
+        name: typeof request.body.name === "string" && request.body.name ? request.body.name : entity,
+    }));
+    const picked = machine ? machines.filter((m) => m.entity === machine || m.name === machine) : machines;
+    if (picked.length !== 1) {
+        throw new Error(machine
+            ? `the fly plan declares no Machine named "${machine}" (declared: ${machines.map((m) => m.entity).join(", ") || "none"})`
+            : `the fly plan declares ${machines.length} Machines (${machines.map((m) => m.entity).join(", ")}): name the one that serves the release`);
+    }
+    const [m] = picked;
+    return { app: resolveApp(machineAppSegment(m.request.endpoint), soleApp), entity: m.entity, name: m.name, request: m.request };
+}
+const TERMINAL = new Set(["destroyed", "destroying"]);
+/** The live Machine named `name` (or with id `name`) in `app`; undefined when there is none. */
+export async function findMachine(ctx, app, name, http, signal) {
+    const live = (await listMachines(ctx, app, http, signal)).filter((m) => !TERMINAL.has(m.state));
+    return live.find((m) => m.name === name) ?? live.find((m) => m.id === name);
+}
+async function mustFindMachine(ctx, app, name, http, signal) {
+    const m = await findMachine(ctx, app, name, http, signal);
+    if (!m)
+        throw new Error(`no machine ${name} on app ${app}`);
+    return m;
+}
+const machinePath = (ctx, app, id) => `${ctx.base}/v1/apps/${encodeURIComponent(app)}/machines/${encodeURIComponent(id)}`;
+/**
+ * Upload and start: apply the declared plan (the App, its Volumes, IPs,
+ * Secrets) with the Machine serving `release`. The Machine is updated in place
+ * under a lease, so the release serves from here on. A Machine that already
+ * serves this release keeps the `previousDigest` it shipped with, so running a
+ * release twice never makes it its own predecessor.
+ */
+export async function flyMachineRelease(args, signal, http = defaultFlyHttp(args.token)) {
+    const plan = args.plan ?? parsePlan(readFileSync(requirePlanPath(args.planPath), "utf8"));
+    const target = releaseTarget(plan, args.machine);
+    const ctx = { base: resolveEndpoint(args) };
+    const live = await findMachine(ctx, target.app, target.name, http, signal).catch(() => undefined);
+    const liveConfig = live?.config;
+    const liveRelease = readMachineRelease(liveConfig?.metadata);
+    const previousDigest = liveRelease && liveRelease.digest !== args.release.digest ? liveRelease.digest : liveRelease?.previousDigest ?? args.release.previousDigest;
+    const release = { ...args.release, ...(previousDigest ? { previousDigest } : {}) };
+    if (!previousDigest)
+        delete release.previousDigest;
+    const declared = (target.request.body.config ?? {});
+    const declaredFiles = declared.files ?? [];
+    const releasePaths = new Set((args.files ?? []).map((f) => f.guest_path));
+    const cmd = typeof args.cmd === "string" ? ["sh", "-c", args.cmd] : args.cmd;
+    const config = withReleaseMetadata({
+        ...declared,
+        ...(args.image ? { image: args.image } : {}),
+        ...(args.env ? { env: { ...(declared.env ?? {}), ...args.env } } : {}),
+        ...(args.files ? { files: [...declaredFiles.filter((f) => !releasePaths.has(f.guest_path)), ...args.files] } : {}),
+        ...(cmd ? { init: { ...(declared.init ?? {}), cmd } } : {}),
+    }, release);
+    const request = { ...target.request, body: { ...target.request.body, config } };
+    const applied = await flyApply({ plan: { ...plan, [target.entity]: request }, endpoint: args.endpoint, token: args.token, wait: args.wait }, signal, http);
+    const action = applied.machines.find((m) => m.app === target.app && m.name === target.name)?.action ?? "noop";
+    const now = await mustFindMachine(ctx, target.app, target.name, http, signal);
+    return {
+        app: target.app,
+        machine: { id: now.id, name: target.name },
+        action,
+        release,
+        config,
+        previous: live ? { ...(liveRelease ? { release: liveRelease } : {}), config: liveConfig ?? {} } : null,
+    };
+}
+function requirePlanPath(planPath) {
+    if (!planPath)
+        throw new Error("pass planPath (the fly build output) or plan");
+    return planPath;
+}
+/**
+ * Run a command inside the Machine (the Machines API's exec). A non-zero exit
+ * throws, with the command's output, so the step fails rather than going on
+ * over a half-migrated database.
+ */
+export async function flyMachineExec(args, signal, http = defaultFlyHttp(args.token)) {
+    const ctx = { base: resolveEndpoint(args) };
+    const m = await mustFindMachine(ctx, args.app, args.machine, http, signal);
+    const command = typeof args.command === "string" ? ["sh", "-c", args.command] : args.command;
+    const res = await http("POST", `${machinePath(ctx, args.app, m.id)}/exec`, { command, timeout: args.timeoutSecs ?? 120 }, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`exec on ${args.app}/${m.id} failed (${res.status}): ${res.text}`);
+    let out = {};
+    try {
+        out = JSON.parse(res.text);
+    }
+    catch {
+        throw new Error(`exec on ${args.app}/${m.id} answered no exec result: ${res.text}`);
+    }
+    const result = { exitCode: out.exit_code ?? 0, stdout: out.stdout ?? "", stderr: out.stderr ?? "" };
+    if (result.exitCode !== 0) {
+        const said = [result.stderr, result.stdout].filter(Boolean).join("\n").trim().slice(-2000);
+        throw new Error(`${command.join(" ")} exited ${result.exitCode} on ${args.app}/${m.id}${said ? `: ${said}` : ""}`);
+    }
+    return result;
+}
+async function transition(args, verb, signal, http) {
+    const ctx = { base: resolveEndpoint(args) };
+    const m = await mustFindMachine(ctx, args.app, args.machine, http, signal);
+    const state = verb === "stop" ? "stopped" : "started";
+    if (verb === "stop" && m.state !== "started")
+        return { id: m.id, state: m.state };
+    const res = await withLease(ctx, args.app, m.id, http, signal, (nonce) => http("POST", `${machinePath(ctx, args.app, m.id)}/${verb}`, undefined, { [LEASE_NONCE_HEADER]: nonce }, signal));
+    if (res.status >= 300)
+        throw new Error(`${verb} of machine ${args.app}/${m.id} failed (${res.status}): ${res.text}`);
+    await waitForMachine(ctx, args.app, m.id, "", http, signal, { ...(args.wait ?? {}), state });
+    return { id: m.id, state };
+}
+/** Restart the Machine under a lease (the app starts again on migrated data), and wait for it to be started. */
+export async function flyMachineRestart(args, signal, http = defaultFlyHttp(args.token)) {
+    return transition(args, "restart", signal, http);
+}
+/** Stop the Machine under a lease, and wait for it to be stopped. A Machine that is not started is left alone. */
+export async function flyMachineStop(args, signal, http = defaultFlyHttp(args.token)) {
+    return transition(args, "stop", signal, http);
+}
+/**
+ * The Machine is started and its metadata names release `digest`. Given a
+ * `url`, its health endpoint answers 2xx too, and when that answer is JSON
+ * naming a `revision` or `digest`, it is this release's (the commit or the
+ * digest). Retries until `timeoutMs`, then throws the last reason.
+ */
+export async function flyMachineVerify(args, signal, http = defaultFlyHttp(args.token), fetchImpl = fetch) {
+    const ctx = { base: resolveEndpoint(args) };
+    const deadline = Date.now() + (args.timeoutMs ?? 120000);
+    const interval = args.intervalMs ?? 1000;
+    let why = "";
+    for (;;) {
+        if (signal?.aborted)
+            throw new Error("flyMachineVerify aborted");
+        try {
+            const m = await mustFindMachine(ctx, args.app, args.machine, http, signal);
+            if (m.state !== "started")
+                throw new Error(`machine ${args.app}/${m.id} is ${m.state}`);
+            const release = readMachineRelease(m.config?.metadata);
+            if (release?.digest !== args.digest) {
+                throw new Error(`machine ${args.app}/${m.id} serves ${release?.digest ?? "no release"}, expected ${args.digest}`);
+            }
+            if (args.url) {
+                const url = `${args.url.replace(/\/$/, "")}${args.healthPath ?? "/health"}`;
+                const res = await fetchImpl(url, { signal: AbortSignal.timeout(5000) });
+                if (!res.ok)
+                    throw new Error(`${url} answered ${res.status}`);
+                let body;
+                try {
+                    body = (await res.json());
+                }
+                catch {
+                    body = undefined;
+                }
+                const reported = typeof body?.revision === "string" ? body.revision : typeof body?.digest === "string" ? body.digest : undefined;
+                if (reported !== undefined && reported !== release.gitSha && reported !== release.digest) {
+                    throw new Error(`${url} reports ${reported}, expected ${release.gitSha ?? release.digest}`);
+                }
+            }
+            return { id: m.id, release };
+        }
+        catch (err) {
+            why = err instanceof Error ? err.message : String(err);
+        }
+        if (Date.now() + interval > deadline)
+            throw new Error(`verify ${args.app}/${args.machine}: ${why}`);
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}
+/**
+ * Put a recorded Machine config back: update the Machine to exactly `config`
+ * under a lease and wait for it to be started. Used on a failed release (the
+ * config it replaced) and by a rollback (the config an earlier release applied).
+ */
+export async function flyMachineRestore(args, signal, http = defaultFlyHttp(args.token)) {
+    const ctx = { base: resolveEndpoint(args) };
+    const m = await mustFindMachine(ctx, args.app, args.machine, http, signal);
+    const res = await withLease(ctx, args.app, m.id, http, signal, (nonce) => http("POST", machinePath(ctx, args.app, m.id), { name: m.name, config: args.config }, { [LEASE_NONCE_HEADER]: nonce }, signal));
+    if (res.status >= 300)
+        throw new Error(`restore of machine ${args.app}/${m.id} failed (${res.status}): ${res.text}`);
+    let instance = "";
+    try {
+        instance = JSON.parse(res.text).instance_id ?? "";
+    }
+    catch {
+        instance = "";
+    }
+    await waitForMachine(ctx, args.app, m.id, instance, http, signal, args.wait ?? {});
+    const release = readMachineRelease(args.config.metadata);
+    return { id: m.id, ...(release ? { release } : {}) };
+}

package/dist/op/activities/machines-contract.js

@@ -0,0 +1,81 @@
+/**
+ * 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}`.
+ */
+/**
+ * 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 = [
+    // 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" },
+    // A running machine is stopped before the destroy (#3115); `?force=true` is a
+    // query, so it stays out of the path template.
+    { method: "POST", path: "/v1/apps/{app}/machines/{id}/stop", op: "stopForDestroy" },
+    { 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" },
+    // Created at /acme: flaps has no POST on the list path (#3114).
+    { method: "POST", path: "/v1/apps/{app}/certificates/acme", 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" },
+];
+/** Normalize a `METHOD path` key: collapse every `{param}` to `{}` so param names match. */
+export function normalizeEndpoint(method, path) {
+    return `${method.toUpperCase()} ${path.replace(/\{[^}]+\}/g, "{}")}`;
+}
+/** The contract as a set of normalized `METHOD path` keys. */
+export function contractKeys() {
+    return new Set(MACHINES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
+}
+/**
+ * The flaps endpoints the release activities (./machine-release.ts, #2736)
+ * add beyond the applier's: getting one Machine back, exec (a migration),
+ * restart and stop. The applier's own contract above stays exec-free; these
+ * are the site steps', and the docker-gated coverage test holds the pinned
+ * mudflaps to them the same way.
+ */
+export const MACHINE_RELEASE_CONTRACT = [
+    { method: "GET", path: "/v1/apps/{app}/machines", op: "findMachine" },
+    { method: "POST", path: "/v1/apps/{app}/machines/{id}", op: "flyMachineRestore" },
+    { method: "POST", path: "/v1/apps/{app}/machines/{id}/exec", op: "flyMachineExec" },
+    { method: "POST", path: "/v1/apps/{app}/machines/{id}/restart", op: "flyMachineRestart" },
+    { method: "POST", path: "/v1/apps/{app}/machines/{id}/stop", op: "flyMachineStop" },
+    { method: "POST", path: "/v1/apps/{app}/machines/{id}/lease", op: "withLease" },
+    { method: "GET", path: "/v1/apps/{app}/machines/{id}/wait", op: "waitForMachine" },
+];

package/dist/op/activities/machines-fake.js

@@ -0,0 +1,203 @@
+/**
+ * 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.
+ * It runs nothing; ./machines-local.ts is the opt-in mode that runs each
+ * started Machine's files and command on this host (#2831).
+ *
+ * Not an activity: nothing in ./index.ts exports it, so `loadActivities`
+ * never binds it.
+ */
+const json = (status, body) => ({ status, text: body === undefined ? "" : JSON.stringify(body) });
+/** Fly's certificate-list page size: 25 when no `limit` is given, 500 at most. */
+export const CERT_PAGE_DEFAULT = 25;
+export const CERT_PAGE_MAX = 500;
+// The fake's cursor is an offset in disguise; callers must treat it as opaque.
+const offsetCursor = (offset) => Buffer.from(`certs:${offset}`).toString("base64url");
+const cursorOffset = (cursor) => {
+    const m = /^certs:(\d+)$/.exec(Buffer.from(cursor, "base64url").toString());
+    return m ? Number(m[1]) : undefined;
+};
+let seq = 0;
+const nextId = (prefix) => `${prefix}${(++seq).toString(16).padStart(10, "0")}`;
+/**
+ * A fresh in-memory flaps. Like the real API, a bare DELETE on a machine that
+ * is not stopped, suspended, failed or created answers 412; `?force=true`
+ * destroys it in any state.
+ */
+export function createMachinesFake(options = {}) {
+    const apps = new Set();
+    const machines = new Map();
+    const certs = new Map();
+    const execs = [];
+    const calls = [];
+    const settle = options.settle ?? (() => "started");
+    const list = (app) => machines.get(app) ?? [];
+    const find = (app, id) => list(app).find((m) => m.id === id);
+    const http = async (method, url, body) => {
+        const { pathname, searchParams } = new URL(url);
+        calls.push(`${method} ${pathname}`);
+        const seg = pathname.split("/").filter(Boolean).map(decodeURIComponent);
+        // seg: ["v1", "apps", app?, kind?, id?, action?]
+        if (seg[0] !== "v1" || seg[1] !== "apps")
+            return json(404, { error: "not found" });
+        const app = seg[2];
+        const b = (body ?? {});
+        if (!app) {
+            if (method === "POST") {
+                const name = String(b.app_name);
+                if (apps.has(name))
+                    return json(409, { error: "app exists" });
+                apps.add(name);
+                return json(201, { name, status: "deployed" });
+            }
+            return json(200, [...apps].map((name) => ({ name })));
+        }
+        if (seg.length === 3) {
+            if (method === "GET")
+                return apps.has(app) ? json(200, { name: app, status: "deployed" }) : json(404, { error: "app not found" });
+            if (method === "DELETE") {
+                apps.delete(app);
+                machines.delete(app);
+                certs.delete(app);
+                return json(202, undefined);
+            }
+        }
+        if (!apps.has(app))
+            return json(404, { error: "app not found" });
+        const kind = seg[3];
+        if (kind === "machines") {
+            const id = seg[4];
+            const action = seg[5];
+            if (!id) {
+                if (method === "GET")
+                    return json(200, list(app));
+                if (method === "POST") {
+                    const m = {
+                        id: nextId("m"),
+                        name: String(b.name ?? ""),
+                        state: "created",
+                        instance_id: nextId("I"),
+                        config: structuredClone((b.config ?? {})),
+                    };
+                    m.state = settle(m);
+                    machines.set(app, [...list(app), m]);
+                    return json(200, m);
+                }
+            }
+            const m = id ? find(app, id) : undefined;
+            if (!m)
+                return action === "wait" ? json(200, { ok: true }) : json(404, { error: "machine not found" });
+            if (!action) {
+                if (method === "GET")
+                    return json(200, m);
+                if (method === "POST") {
+                    m.config = structuredClone((b.config ?? {}));
+                    m.instance_id = nextId("I");
+                    m.state = settle(m);
+                    return json(200, m);
+                }
+                if (method === "DELETE") {
+                    // Real flaps destroys a running machine only with ?force=true and
+                    // answers a bare DELETE with 412 (#3115). mudflaps does not (yet).
+                    if (searchParams.get("force") !== "true" && !["stopped", "suspended", "failed", "created"].includes(m.state)) {
+                        return json(412, {
+                            error: "failed_precondition: unable to destroy machine, not currently stopped, suspended, failed or created",
+                        });
+                    }
+                    machines.set(app, list(app).filter((x) => x !== m));
+                    return json(200, { ok: true });
+                }
+            }
+            if (action === "lease") {
+                if (method === "POST")
+                    return json(200, { data: { nonce: nextId("n") } });
+                return json(200, { ok: true });
+            }
+            if (action === "wait") {
+                const want = searchParams.get("state") ?? "started";
+                return json(200, { ok: m.state === want });
+            }
+            if (action === "restart" || action === "start") {
+                m.state = "started";
+                return json(200, { ok: true });
+            }
+            if (action === "stop") {
+                m.state = "stopped";
+                return json(200, { ok: true });
+            }
+            if (action === "exec" && method === "POST") {
+                const command = b.command ?? String(b.cmd ?? "").split(" ");
+                execs.push({ app, id: m.id, command });
+                return json(200, (await options.exec?.(app, m, command)) ?? { exit_code: 0, stdout: "", stderr: "" });
+            }
+            return json(404, { error: `no ${method} ${action}` });
+        }
+        if (kind === "ip_assignments")
+            return method === "GET" ? json(200, { ips: [] }) : json(200, {});
+        if (kind === "certificates")
+            return certificates(app, method, seg.slice(4), b, searchParams);
+        if (kind === "volumes" || kind === "secrets")
+            return method === "GET" ? json(200, []) : json(200, {});
+        return json(404, { error: "not found" });
+    };
+    // Certificates, as the real API routes them (#3114): listed at
+    // `.../certificates`, created only at `.../certificates/acme`, read and
+    // deleted at `.../certificates/{hostname}`. A POST to the bare list path is
+    // the 404 flaps gives, so an applier that posts there fails here too.
+    // The list pages like Fly's (#3224): `limit` defaults to 25 and is capped at
+    // 500, and `next_cursor` is present while certificates remain. mudflaps
+    // returns the whole list in one page (INTENTIUS/mudflaps#71).
+    function certificates(app, method, rest, b, q) {
+        const hostnames = certs.get(app) ?? [];
+        const detail = (hostname) => ({ hostname, acme_requested: true, configured: false, status: "pending" });
+        if (rest.length === 0) {
+            if (method !== "GET")
+                return { status: 404, text: "404 page not found" };
+            const limit = Math.min(CERT_PAGE_MAX, Math.max(1, Number(q.get("limit")) || CERT_PAGE_DEFAULT));
+            const cursor = q.get("cursor");
+            const from = cursor === null ? 0 : cursorOffset(cursor);
+            if (from === undefined)
+                return json(400, { error: `invalid cursor ${cursor}` });
+            const page = hostnames.slice(from, from + limit);
+            const more = from + limit < hostnames.length;
+            return json(200, {
+                certificates: page.map(detail),
+                ...(more ? { next_cursor: offsetCursor(from + limit) } : {}),
+                total_count: hostnames.length,
+            });
+        }
+        if (rest.length === 1 && rest[0] === "acme" && method === "POST") {
+            const hostname = typeof b.hostname === "string" ? b.hostname : "";
+            if (!hostname)
+                return json(422, { error: "hostname is required" });
+            if (hostnames.includes(hostname))
+                return json(422, { error: `certificate ${hostname} already exists` });
+            certs.set(app, [...hostnames, hostname]);
+            return json(201, detail(hostname));
+        }
+        if (rest.length === 1 && (method === "GET" || method === "DELETE")) {
+            const hostname = rest[0];
+            if (!hostnames.includes(hostname))
+                return json(404, { error: "certificate not found" });
+            if (method === "GET")
+                return json(200, detail(hostname));
+            certs.set(app, hostnames.filter((h) => h !== hostname));
+            return json(204, undefined);
+        }
+        return { status: 404, text: "404 page not found" };
+    }
+    return {
+        http,
+        apps,
+        machines,
+        certs,
+        execs,
+        calls,
+        machine: (app, name) => list(app).find((m) => m.name === name && !["destroyed", "destroying"].includes(m.state)),
+    };
+}