@volter/twin-fly 0.1.0

package/dist/src/fly-twin.js

@@ -0,0 +1,1272 @@
+// Fly.io MACHINES API twin REQUEST HANDLER — the canonical api.machines.dev/v1 surface.
+//
+// Contract: handleFlyTwinRequest({ method, path, body, headers, root, readOnly, runtime,
+// occurredAt }) -> { status, body }. State is the kernel event/action log (D1); reads are the
+// projection. No real Fly is ever called (D4) — the only genuinely-external thing this pack
+// touches is the LOCAL Docker daemon, and only through the injected `FlyContainerRuntime` seam
+// (fly-machines.ts), which defaults to the pure-ledger VIRTUAL runtime so every verify and the
+// whole gate run with no Docker anywhere.
+//
+// GROUNDING: surface + schemas from Fly's first-party OpenAPI (live-fetched
+// docs.machines.dev/swagger/doc.json, "Machines API 1.0") cross-checked against superfly/fly-go
+// (flyctl's own client). Facts taken from fly-go over the OpenAPI where they disagree:
+//   - lease responses are WRAPPED {status:"success", data:{...}} (fly-go MachineLease), not the
+//     OpenAPI's bare Lease schema;
+//   - the lease nonce travels in the `fly-machine-lease-nonce` header (flaps NonceHeader);
+//   - volumes list / snapshots list are BARE arrays (flaps_volumes.go decodes []Volume);
+//   - machine start answers {previous_state,...} (fly-go MachineStartResponse).
+// Error envelope: {error: string} with the HTTP status (OpenAPI ErrorResponse; its optional
+// `status` enum — name_taken etc. — is included where the spec grounds it, e.g. app-name 422).
+// The docs' response-code table (fly.io/docs/machines/api/working-with-machines-api): 401
+// missing/invalid credentials, 404 not found, 408 wait timeout, 422 validation.
+//
+// AUTH is faked-but-ENFORCED (D2): a missing/empty Bearer token -> 401 like the vendor; any
+// non-empty token is accepted (the twin has no account database — disclosed). `readOnly` rejects
+// writes with 405 (D3). An unmodeled operation FAILS like Fly (404 {error}, never a fabricated
+// success) — including the vendor's own routes this twin has not modeled yet (certificates,
+// tokens, Managed Postgres, orgs listings: all enumerated as todos in fly-capabilities.ts).
+//
+// ⚠ doc-unverified modeling choices (no live account to probe; each disclosed here + in
+// spec-sources.json): exact error STRINGS for negative paths (except wait's
+// "timeout reached waiting for machine's state to change" and the 422 app-name-taken family,
+// which are documented); {ok:true} action-reply bodies for stop/restart/cordon/uncordon/
+// suspend/signal/delete; 409 for lease conflicts; idempotent 200 for start-on-started /
+// stop-on-stopped; 404 for DELETE of an unknown secret and for lease reads/releases with no live
+// lease; on-failure restart max_retries defaulting to 10 when config.restart is absent.
+import { containerSpecOf, getRow, imageRefOf, machineEvent, machinePrivateIp, countRows, newAppNumericId, newInstanceId, newLeaseNonce, newMachineId, newMachineName, newVolumeId, nowEpochMs, nowIso, rows, VIRTUAL_FLY_RUNTIME, write, } from "./fly-machines.js";
+import { createHash } from 'node:crypto';
+import { resolveSubjectId } from '@volter/world-core';
+import { SERVICE } from "./fly-machines.js";
+export const FLY_RESOURCE_TYPES = ['app', 'machine', 'volume', 'secret'];
+/** The public + internal Machines API hosts (fly.io/docs/machines/api/working-with-machines-api). */
+export const FLY_API_HOST = 'api.machines.dev';
+export const FLY_INTERNAL_API_HOST = '_api.internal';
+// Fly's error envelope (OpenAPI ErrorResponse): {error, status?, details?}.
+function err(message, status = 404, code) {
+    return { status, body: { error: message, ...(code ? { status: code } : {}) } };
+}
+function parseBody(req) {
+    if (!req.body)
+        return {};
+    try {
+        const v = JSON.parse(req.body);
+        return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+function lowerHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h ?? {}))
+        if (v !== undefined)
+            out[k.toLowerCase()] = v;
+    return out;
+}
+// ── views ─────────────────────────────────────────────────────────────────────────────────────
+function appView(a, root, occurredAt) {
+    const machines = rows('machine', root).filter((m) => m.app_name === a.id && m._purged !== true && m.state !== 'destroyed');
+    const volumes = rows('volume', root).filter((v) => v.app_name === a.id && !volumeGone(v, occurredAt));
+    return {
+        id: String(a.id),
+        name: String(a.id),
+        internal_numeric_id: a.internal_numeric_id,
+        machine_count: machines.length,
+        volume_count: volumes.length,
+        network: a.network ?? 'default',
+        organization: { name: a.org_name ?? String(a.org_slug), slug: String(a.org_slug) },
+        status: a.status ?? 'pending',
+    };
+}
+function appListView(a, root) {
+    const v = appView(a, root);
+    return { id: v.id, name: v.name, machine_count: v.machine_count, network: v.network, status: v.status };
+}
+function machineView(m, opts = {}) {
+    const events = ([...(m.events ?? [])]).reverse(); // newest first
+    // The vendor gates Machine.lease behind ?include_leases=true, and an EXPIRED lease is not a
+    // lease — leaseIsLive is the same clock the lease endpoints use (§9 round one, finding 5).
+    const lease = opts.includeLeases && leaseIsLive(m, opts.occurredAt)
+        ? { description: m.lease_description ?? '', expires_at: m.lease_expires_at, owner: String(m.lease_owner ?? 'twin@local') }
+        : undefined;
+    return {
+        id: String(m.id),
+        name: String(m.name),
+        state: String(m.state),
+        region: String(m.region),
+        instance_id: String(m.instance_id),
+        version: String(m.instance_id),
+        private_ip: String(m.private_ip),
+        created_at: String(m.created_at),
+        updated_at: String(m.machine_updated_at ?? m.created_at),
+        config: m.config ?? {},
+        image_ref: m.image_ref ?? {},
+        events,
+        checks: [],
+        host_status: 'ok',
+        cordoned: m.cordoned === true,
+        ...(lease ? { lease } : {}),
+        ...(opts.nonce ? { nonce: opts.nonce } : {}),
+        // Twin-only ADDITIVE observability (disclosed, README ## Coverage): which execution plane ran
+        // this machine and where its published loopback ports landed. Never replaces a real field.
+        // (stored `_`-prefixed: the twin's own bookkeeping, outside the vendor's shape — protocol 2 shape parity)
+        ...(m._twin_runtime ? { twin_runtime: m._twin_runtime } : {}),
+        ...(Array.isArray(m._twin_local_ports) && m._twin_local_ports.length > 0 ? { twin_local_ports: m._twin_local_ports } : {}),
+        ...(typeof m._twin_last_failure === 'string' ? { twin_last_failure: m._twin_last_failure } : {}),
+    };
+}
+function volumeView(v) {
+    const sizeGb = Number(v.size_gb ?? 1);
+    const blockSize = 4096;
+    const blocks = Math.floor((sizeGb * 1024 * 1024 * 1024) / blockSize);
+    return {
+        id: String(v.id),
+        name: String(v.name),
+        app_name: undefined, // not in the Volume schema — kept off the wire
+        state: String(v.state),
+        region: String(v.region),
+        size_gb: sizeGb,
+        encrypted: v.encrypted !== false,
+        fstype: String(v.fstype ?? 'ext4'),
+        zone: String(v.zone),
+        snapshot_retention: Number(v.snapshot_retention ?? 5),
+        auto_backup_enabled: v.auto_backup_enabled !== false,
+        block_size: blockSize,
+        blocks,
+        blocks_free: blocks,
+        blocks_avail: blocks,
+        bytes_total: sizeGb * 1024 * 1024 * 1024,
+        bytes_used: 0,
+        attached_machine_id: v.attached_machine_id ?? null,
+        attached_alloc_id: null,
+        created_at: String(v.created_at),
+        host_status: 'ok',
+    };
+}
+function secretView(s, showSecrets) {
+    return {
+        name: String(s.secret_name),
+        digest: String(s.digest),
+        created_at: String(s.created_at),
+        updated_at: String(s.secret_updated_at ?? s.created_at),
+        ...(showSecrets ? { value: String(s.value) } : {}),
+    };
+}
+/** Rows that still belong to the CURRENT life of their app. An app DELETE purges its machines
+ *  and volumes (`_purged`): real Fly destroys an app's volumes with it, and a re-created name is
+ *  a brand-new app that must start EMPTY — without the flag, the first life's rows would bleed
+ *  back into the recreated app (§9 round one, finding 1). */
+function liveAppRows(type, appName, root) {
+    return rows(type, root).filter((r) => r.app_name === appName && r._purged !== true);
+}
+// ── machine event/state helpers ───────────────────────────────────────────────────────────────
+function pushEvent(m, type, status, source, occurredAt) {
+    const events = [...(m.events ?? [])];
+    events.push(machineEvent(type, status, source, occurredAt, events.length));
+    return events;
+}
+function leaseIsLive(m, occurredAt) {
+    return typeof m.lease_nonce === 'string' && m.lease_nonce.length > 0
+        && typeof m.lease_expires_at === 'number' && m.lease_expires_at * 1000 > nowEpochMs(occurredAt);
+}
+/** A live lease guards every state-mutating machine op: the request must carry the nonce in the
+ *  `fly-machine-lease-nonce` header (fly-go flaps NonceHeader). */
+function leaseBlocks(m, headers, occurredAt) {
+    if (!leaseIsLive(m, occurredAt))
+        return undefined;
+    const nonce = headers['fly-machine-lease-nonce'];
+    if (nonce === m.lease_nonce)
+        return undefined;
+    return err(`machine ID ${m.id} lease currently held by ${m.lease_owner ?? 'twin@local'}, expires at ${new Date(m.lease_expires_at * 1000).toISOString()}`, 400);
+}
+/** on-failure's retry cap when config.restart is absent (⚠ doc-unverified default — the spec
+ *  names on-failure as the default policy but publishes no default max_retries; 10 is this
+ *  twin's disclosed choice). */
+const FLY_DEFAULT_MAX_RETRIES = 10;
+/** Ask the execution plane whether a started machine's container is still alive, and fold an
+ *  exit back into the control plane HONORING the vendor's restart policy (fly.MachineRestart:
+ *  `no` → stop; `always` → restart; `on-failure` — THE DEFAULT when no policy is set — → restart
+ *  on a non-zero exit, up to max_retries). The exit code is ledgered into the event's
+ *  fly-go-shaped request payload ({exit_event:{exit_code}}). Offline-provable with fake runtimes.
+ *  READ-ONLY twins never write here (§9 round one, finding 4): the fold is skipped and the
+ *  control-plane state is served as-is.
+ *
+ *  DELIBERATE: the fold runs BEFORE any lease check (it is dispatched ahead of the per-action
+ *  handlers) and is not itself lease-guarded — flyd is the PLATFORM, not a user, and observing
+ *  that a container died is true regardless of who holds the machine lease or whether the
+ *  triggering request is then refused. A lease guards user MUTATIONS, not reality. */
+async function foldRuntimeExit(m, req, runtime) {
+    if (req.readOnly)
+        return m;
+    if (m.state !== 'started' || !runtime.inspect || typeof m._container_ref !== 'string')
+        return m;
+    let live;
+    try {
+        live = await runtime.inspect(m._container_ref);
+    }
+    catch {
+        return m;
+    } // an un-inspectable container is not evidence of an exit
+    if (live.running)
+        return m;
+    const exitCode = typeof live.exitCode === 'number' ? live.exitCode : 0;
+    const exitRequest = { exit_event: { exit_code: exitCode, oom_killed: live.oomKilled === true, requested_stop: false } };
+    const config = (m.config ?? {});
+    const policy = typeof config.restart?.policy === 'string' ? config.restart.policy : 'on-failure';
+    const maxRetries = typeof config.restart?.max_retries === 'number' ? config.restart.max_retries : FLY_DEFAULT_MAX_RETRIES;
+    const attempts = typeof m._flyd_restart_attempts === 'number' ? m._flyd_restart_attempts : 0;
+    const shouldRestart = policy === 'always' || (policy === 'on-failure' && exitCode !== 0 && attempts < maxRetries);
+    if (shouldRestart) {
+        const priorEvents = m.events ?? [];
+        let events = [...priorEvents, machineEvent('exit', 'restarting', 'flyd', req.occurredAt, priorEvents.length, exitRequest)];
+        try {
+            // Reap the exited container FIRST (§9 round two, finding 3): the docker plane names
+            // containers deterministically (fly-twin-<machineId>), so a relaunch without a reap dies
+            // on a name conflict — silently, since the catch below folds to stopped.
+            try {
+                await runtime.remove(m._container_ref);
+            }
+            catch { /* already gone */ }
+            const launched = await runtime.run(containerSpecOf(m));
+            events = [...events, machineEvent('start', 'started', 'flyd', req.occurredAt, events.length)];
+            return write('machine', String(m.id), {
+                ...m, state: 'started', events,
+                _container_ref: launched.containerRef,
+                _twin_local_ports: launched.publishedPorts ?? m._twin_local_ports ?? [],
+                _flyd_restart_attempts: attempts + 1,
+                _twin_last_failure: null,
+                machine_updated_at: nowIso(req.occurredAt),
+            }, 'machine.flyd_restart', req.root, req.occurredAt);
+        }
+        catch (error) {
+            // Retain and forward the causal restart refusal. Discarding this catch used to turn a
+            // capacity failure into an unexplained stopped machine with only the original exit code.
+            const restartError = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[machine ${String(m.id)}] automatic restart failed: ${restartError}\n`);
+            const stoppedEvents = [...events, machineEvent('exit', 'stopped', 'flyd', req.occurredAt, events.length, {
+                    ...exitRequest,
+                    restart_error: restartError,
+                })];
+            return write('machine', String(m.id), {
+                ...m,
+                state: 'stopped',
+                events: stoppedEvents,
+                _twin_last_failure: restartError,
+                machine_updated_at: nowIso(req.occurredAt),
+            }, 'machine.exit', req.root, req.occurredAt);
+        }
+    }
+    const priorEvents = m.events ?? [];
+    const events = [...priorEvents, machineEvent('exit', 'stopped', 'flyd', req.occurredAt, priorEvents.length, exitRequest)];
+    return write('machine', String(m.id), { ...m, state: 'stopped', events, machine_updated_at: nowIso(req.occurredAt) }, 'machine.exit', req.root, req.occurredAt);
+}
+// ── the handler ───────────────────────────────────────────────────────────────────────────────
+export async function handleFlyTwinRequest(req) {
+    const runtime = req.runtime ?? VIRTUAL_FLY_RUNTIME;
+    const headers = lowerHeaders(req.headers);
+    const [pathOnly, queryString = ''] = req.path.split('?', 2);
+    const params = new URLSearchParams(queryString);
+    const seg = pathOnly.replace(/^\/+/, '').replace(/\/+$/, '').split('/').filter(Boolean);
+    const method = req.method.toUpperCase();
+    // Auth: faked-but-enforced. Missing/empty Bearer -> the vendor's 401 (docs response table).
+    const auth = headers['authorization'] ?? '';
+    const token = auth.startsWith('Bearer ') ? auth.slice('Bearer '.length).trim() : '';
+    if (token.length === 0)
+        return err('unauthorized', 401);
+    if (req.readOnly && method !== 'GET' && method !== 'HEAD') {
+        return err('read-only twin: writes are disabled', 405);
+    }
+    if (seg[0] !== 'v1')
+        return err('not found', 404);
+    if (seg[1] === 'apps') {
+        // /v1/apps
+        if (seg.length === 2) {
+            if (method === 'GET') {
+                const orgSlug = params.get('org_slug');
+                if (!orgSlug)
+                    return err('org_slug is required', 400);
+                const apps = rows('app', req.root).filter((a) => a.org_slug === orgSlug && a.deleted !== true);
+                return { status: 200, body: { total_apps: apps.length, apps: apps.map((a) => appListView(a, req.root)) } };
+            }
+            if (method === 'POST')
+                return createApp(req);
+            return err('not found', 404);
+        }
+        // protocol 2: an app's name is Fly's id, so a landing adopts it as it stands — but the alias map is the one
+        // truth about what an id became, and the boundary asks it once, for the app as for its machines and volumes
+        const appName = resolveSubjectId(SERVICE, 'app', decodeURIComponent(seg[2]), req.root);
+        const app = getRow('app', appName, req.root);
+        const appLive = app && app.deleted !== true ? app : undefined;
+        // /v1/apps/{app_name}
+        if (seg.length === 3) {
+            if (method === 'GET')
+                return appLive ? { status: 200, body: appView(appLive, req.root, req.occurredAt) } : err('app not found', 404);
+            if (method === 'DELETE') {
+                if (!appLive)
+                    return err('app not found', 404);
+                // Destroy the app's machines (force) so the execution plane is reaped with it, destroy
+                // its volumes (real Fly destroys an app's volumes with the app), and PURGE both: a
+                // re-created app of the same name is a brand-new app and must start empty (§9 finding 1).
+                for (const m of liveAppRows('machine', appName, req.root)) {
+                    if (m.state !== 'destroyed')
+                        await destroyMachineRow(m, req, runtime);
+                    const fresh = getRow('machine', String(m.id), req.root) ?? m;
+                    await write('machine', String(m.id), { ...fresh, _purged: true }, 'machine.purge', req.root, req.occurredAt);
+                }
+                for (const v of liveAppRows('volume', appName, req.root)) {
+                    if (runtime.removeVolume) {
+                        try {
+                            await runtime.removeVolume(String(v.id));
+                        }
+                        catch { /* never materialized */ }
+                    }
+                    await write('volume', String(v.id), { ...v, state: 'destroyed', attached_machine_id: null, _purged: true }, 'volume.purge', req.root, req.occurredAt);
+                }
+                // Secrets die with the app too (§9 round two, finding 1): a recreated name must not
+                // inherit the first life's secret VALUES — that leak is a credential disclosure, and it
+                // would also silently regress the recreated app's fresh _secrets_version counter.
+                for (const sec of rows('secret', req.root).filter((x) => x.app_name === appName && x.deleted !== true)) {
+                    await write('secret', String(sec.id), { ...sec, deleted: true }, 'secret.purge', req.root, req.occurredAt);
+                }
+                await write('app', appName, { ...appLive, deleted: true }, 'app.delete', req.root, req.occurredAt);
+                return { status: 202, body: {} };
+            }
+            return err('not found', 404);
+        }
+        if (!appLive)
+            return err('app not found', 404);
+        // protocol 2: after a landing adopted Fly's id for a machine or a volume, a caller on a branch may still
+        // address it by the local id — resolved through the alias map once, here at the boundary
+        if (seg[4] && (seg[3] === 'machines' || seg[3] === 'volumes'))
+            seg[4] = resolveSubjectId(SERVICE, seg[3] === 'machines' ? 'machine' : 'volume', decodeURIComponent(seg[4]), req.root);
+        if (seg[3] === 'machines')
+            return handleMachines(req, runtime, appName, seg, params, headers, method);
+        if (seg[3] === 'volumes')
+            return handleVolumes(req, runtime, appName, seg, method);
+        if (seg[3] === 'secrets')
+            return handleSecrets(req, appName, seg, params, method);
+        // Real-but-unmodeled app sub-surfaces (certificates, ip_assignments, deploy_token,
+        // secretkeys): enumerated as todos in the manifest; until modeled they fail like the vendor.
+        return err('not found', 404);
+    }
+    // /v1/orgs/*, /v1/platform/*, /v1/tokens/*, /v1/postgres/*: real vendor surface, not modeled
+    // yet (todos in fly-capabilities.ts) — fail like the vendor, never fabricate.
+    return err('not found', 404);
+}
+// ── apps ──────────────────────────────────────────────────────────────────────────────────────
+async function createApp(req) {
+    const b = parseBody(req);
+    const name = typeof b.app_name === 'string' && b.app_name ? b.app_name : (typeof b.name === 'string' ? b.name : '');
+    if (!name)
+        return err('app name required', 422);
+    if (!/^[a-z0-9-]+$/.test(name))
+        return err(`Validation failed: Name '${name}' must contain only lowercase letters, numbers, and dashes`, 422);
+    const orgSlug = typeof b.org_slug === 'string' && b.org_slug ? b.org_slug : 'personal';
+    // the name is the id: a name a landing adopted (the alias map's one truth) is taken exactly as one it never touched
+    const existing = getRow('app', resolveSubjectId(SERVICE, 'app', name, req.root), req.root);
+    if (existing && existing.deleted !== true) {
+        // 422 name-taken is DOCUMENTED (docs response-code table: "Validation failed (for example,
+        // an app name that is already taken)"; ErrorResponse.status enum carries name_taken).
+        return err('Validation failed: Name has already been taken', 422, 'name_taken');
+    }
+    // Not a name hash: real Fly mints a fresh internal id, so a deleted+recreated name must not
+    // resurrect the old one (§9 round one, finding 13). The seed carries the ORDINAL this app row
+    // takes over every app the tree ever held (a deleted app is a tombstone the tree keeps), so the count
+    // only grows — a recreated name mints at a higher ordinal and gets a different id, while two
+    // identical worlds still agree byte for byte (R9).
+    const numericId = newAppNumericId(`app:${name}:${nowIso(req.occurredAt)}:${countRows('app', req.root)}`);
+    await write('app', name, {
+        org_slug: orgSlug,
+        org_name: orgSlug,
+        network: typeof b.network === 'string' && b.network ? b.network : 'default',
+        internal_numeric_id: numericId,
+        status: 'pending',
+        _created_at: nowIso(req.occurredAt), // the App schema carries no created_at: the twin's own note, off the wire
+    }, 'app.create', req.root, req.occurredAt);
+    return { status: 201, body: {} }; // OpenAPI CreateAppResponse: {token?} — no token minted locally
+}
+// ── machines ──────────────────────────────────────────────────────────────────────────────────
+async function handleMachines(req, runtime, appName, seg, params, headers, method) {
+    // /v1/apps/{app}/machines
+    if (seg.length === 4) {
+        if (method === 'GET') {
+            const includeDeleted = params.get('include_deleted') === 'true';
+            const includeLeases = params.get('include_leases') === 'true';
+            const state = params.get('state');
+            const region = params.get('region');
+            let ms = liveAppRows('machine', appName, req.root);
+            const refreshed = [];
+            for (const m of ms)
+                refreshed.push(await foldRuntimeExit(m, req, runtime));
+            ms = refreshed;
+            if (!includeDeleted)
+                ms = ms.filter((m) => m.state !== 'destroyed');
+            if (state) {
+                // The vendor documents ?state= as a COMMA-SEPARATED list (§9 round one, finding 6).
+                const wanted = new Set(state.split(',').map((x) => x.trim()).filter(Boolean));
+                ms = ms.filter((m) => wanted.has(String(m.state)));
+            }
+            if (region)
+                ms = ms.filter((m) => m.region === region);
+            return { status: 200, body: ms.map((m) => machineView(m, { includeLeases, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) })) };
+        }
+        if (method === 'POST')
+            return createMachine(req, runtime, appName);
+        return err('not found', 404);
+    }
+    const machineId = seg[4];
+    let m = getRow('machine', machineId, req.root);
+    if (!m || m.app_name !== appName || m._purged === true)
+        return err('machine not found', 404);
+    m = await foldRuntimeExit(m, req, runtime);
+    // /v1/apps/{app}/machines/{id}
+    if (seg.length === 5) {
+        if (method === 'GET') {
+            const includeLeases = params.get('include_leases') === 'true';
+            return { status: 200, body: machineView(m, { includeLeases, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) }) };
+        }
+        if (method === 'POST')
+            return updateMachine(req, runtime, m, headers, params);
+        if (method === 'DELETE') {
+            const blocked = leaseBlocks(m, headers, req.occurredAt);
+            if (blocked)
+                return blocked;
+            if (m.state === 'destroyed')
+                return { status: 200, body: { ok: true } };
+            const force = params.get('force') === 'true';
+            if (m.state === 'started' && !force) {
+                return err(`machine ${m.id} is active: stop it first or pass force=true`, 400);
+            }
+            await destroyMachineRow(m, req, runtime);
+            return { status: 200, body: { ok: true } };
+        }
+        return err('not found', 404);
+    }
+    const action = seg[5];
+    if (seg.length === 6) {
+        // Lifecycle verbs are POST-only in the vendor's OpenAPI; any other method must 404, not
+        // act — a method-blind dispatch would also let a readOnly twin mutate state via GET, since
+        // the readOnly guard above only intercepts non-GET methods.
+        const lifecycle = action === 'start' || action === 'stop' || action === 'restart'
+            || action === 'signal' || action === 'suspend' || action === 'cordon' || action === 'uncordon';
+        if (lifecycle && method !== 'POST')
+            return err('not found', 404);
+        switch (action) {
+            case 'start': return startMachine(req, runtime, m, headers);
+            case 'stop': return stopMachine(req, runtime, m, headers);
+            case 'restart': return restartMachine(req, runtime, m, headers);
+            case 'signal': return signalMachine(req, runtime, m, headers);
+            case 'suspend': return suspendMachine(req, runtime, m, headers);
+            case 'cordon': return cordonMachine(req, m, headers, true);
+            case 'uncordon': return cordonMachine(req, m, headers, false);
+            case 'wait': return method === 'GET' ? waitMachine(req, m, params) : err('not found', 404);
+            case 'events': {
+                if (method !== 'GET')
+                    return err('not found', 404);
+                const limitRaw = params.get('limit');
+                const limit = limitRaw ? Number(limitRaw) : undefined;
+                const events = ([...(m.events ?? [])]).reverse();
+                return { status: 200, body: limit && Number.isFinite(limit) && limit > 0 ? events.slice(0, limit) : events };
+            }
+            case 'versions': {
+                if (method !== 'GET')
+                    return err('not found', 404);
+                return { status: 200, body: (m._config_history ?? []) };
+            }
+            case 'exec': {
+                if (method !== 'POST')
+                    return err('not found', 404);
+                const execBlocked = leaseBlocks(m, headers, req.occurredAt);
+                if (execBlocked)
+                    return execBlocked;
+                return execMachine(req, runtime, m);
+            }
+            case 'lease': return leaseMachine(req, m, params, headers, method);
+            case 'metadata': {
+                if (method === 'GET') {
+                    const config = (m.config ?? {});
+                    return { status: 200, body: (config.metadata ?? {}) };
+                }
+                // PUT/PATCH full metadata replace (412 version semantics): real surface, not modeled yet.
+                return err('not found', 404);
+            }
+            default: return err('not found', 404); // incl. ps / memory / memory-reclaim: real, unmodeled todos
+        }
+    }
+    if (seg.length === 7 && action === 'metadata') {
+        const key = decodeURIComponent(seg[6]);
+        const config = { ...(m.config ?? {}) };
+        const metadata = { ...(config.metadata ?? {}) };
+        if (method === 'GET') {
+            // OpenAPI: GET metadata/{key} -> 200 metadataValueResponse | 404
+            if (!(key in metadata))
+                return err('metadata key not found', 404);
+            return { status: 200, body: { value: metadata[key] } };
+        }
+        if (method === 'POST') {
+            const metaBlocked = leaseBlocks(m, headers, req.occurredAt);
+            if (metaBlocked)
+                return metaBlocked;
+            const b = parseBody(req);
+            if (typeof b.value !== 'string')
+                return err('value is required', 400);
+            metadata[key] = b.value;
+            config.metadata = metadata;
+            await write('machine', String(m.id), { ...m, config, machine_updated_at: nowIso(req.occurredAt) }, 'machine.metadata_set', req.root, req.occurredAt);
+            return { status: 204, body: null };
+        }
+        if (method === 'DELETE') {
+            const metaBlocked = leaseBlocks(m, headers, req.occurredAt);
+            if (metaBlocked)
+                return metaBlocked;
+            delete metadata[key];
+            config.metadata = metadata;
+            await write('machine', String(m.id), { ...m, config, machine_updated_at: nowIso(req.occurredAt) }, 'machine.metadata_delete', req.root, req.occurredAt);
+            return { status: 204, body: null };
+        }
+        return err('not found', 404);
+    }
+    return err('not found', 404);
+}
+/** Live-verified 2026-09-03 against api.machines.dev: a config.guest.memory_mb that is not a
+ *  256 MiB increment (a 128 MiB request) is refused with exactly this 400 body. */
+function guestConfigError(config) {
+    const guest = config.guest;
+    if (!guest || typeof guest !== 'object')
+        return undefined;
+    const memory = guest.memory_mb;
+    if (memory === undefined)
+        return undefined;
+    if (typeof memory !== 'number' || !Number.isInteger(memory) || memory <= 0 || memory % 256 !== 0) {
+        return err('invalid config.guest.memory_mb, must be in 256 MiB increment', 400);
+    }
+    return undefined;
+}
+/** A deleted volume is not gone at once: DELETE leaves it listed as pending_destroy (live-verified
+ *  2026-09-03: the row stayed in the list and a mount of it was refused) until the platform purges
+ *  it. The purge delay is ⚠ doc-unverified; 60 s of WORLD time is the modeled window. */
+const VOLUME_PURGE_MS = 60_000;
+function volumeGone(v, occurredAt) {
+    if (v._purged === true || v.state === 'destroyed')
+        return true;
+    if (v.state !== 'pending_destroy')
+        return false;
+    const requested = Date.parse(String(v._destroy_requested_at ?? ''));
+    return Number.isFinite(requested) && Date.parse(nowIso(occurredAt)) - requested >= VOLUME_PURGE_MS;
+}
+/** Resolve a config's mounts against the app's volumes — the ONE mount rulebook, shared by
+ *  create AND update (§9 round one, finding 2: the first draft enforced it only on create, so an
+ *  update could steal an attached volume or mount a nonexistent one). `selfId` is the machine
+ *  whose own attachments are legitimate on an update. */
+function resolveMounts(config, appName, selfId, req) {
+    const mounts = Array.isArray(config.mounts) ? config.mounts : [];
+    const volumes = [];
+    for (const mt of mounts) {
+        // a mount names its volume by id; an adopted volume answers to its local id too (alias-aware), and the
+        // config is stored with the id the tree holds so the reference follows the adoption
+        if (typeof mt.volume === 'string' && mt.volume)
+            mt.volume = resolveSubjectId(SERVICE, 'volume', mt.volume, req.root);
+        const vol = getRow('volume', String(mt.volume ?? ''), req.root);
+        if (!vol || vol.app_name !== appName || volumeGone(vol, req.occurredAt)) {
+            return { error: err(`volume ${mt.volume} not found`, 404), volumes: [] };
+        }
+        // Live-verified 2026-09-03: mounting a volume that is pending_destroy -> exactly this 400.
+        if (vol.state === 'pending_destroy')
+            return { error: err('volume not found', 400), volumes: [] };
+        const attachedTo = typeof vol.attached_machine_id === 'string' ? vol.attached_machine_id : '';
+        if (attachedTo && attachedTo !== selfId) {
+            return { error: err(`volume ${vol.id} already attached to machine ${attachedTo}`, 422), volumes: [] };
+        }
+        volumes.push(vol);
+    }
+    return { volumes };
+}
+async function createMachine(req, runtime, appName) {
+    const b = parseBody(req);
+    const config = b.config;
+    if (!config || typeof config !== 'object')
+        return err('machine config is required', 400);
+    const image = typeof config.image === 'string' ? config.image.trim() : '';
+    if (!image)
+        return err('you must provide an image for the machine', 422);
+    const guestError = guestConfigError(config);
+    if (guestError)
+        return guestError;
+    // ONE seed per created machine, off the state this write lands on (R9 — see fly-machines.ts's
+    // `entropyHex`): the app, the world instant and the ordinal this machine row takes. Each id
+    // draws from its own sub-seed so the name, the machine id, the instance id and the lease nonce
+    // are independent of one another.
+    const seed = `machine:${appName}:${nowIso(req.occurredAt)}:${rows('machine', req.root).length}`;
+    const name = typeof b.name === 'string' && b.name ? b.name : newMachineName(`${seed}:name`);
+    const clash = liveAppRows('machine', appName, req.root).find((x) => x.name === name && x.state !== 'destroyed');
+    if (clash)
+        return err(`already_exists: unique machine name violation, machine name "${name}" already taken`, 422);
+    // Mounts must reference an existing, unattached volume of this app (attach semantics).
+    const resolved = resolveMounts(config, appName, undefined, req);
+    if (resolved.error)
+        return resolved.error;
+    const mountVolumes = resolved.volumes;
+    const id = newMachineId(`${seed}:id`);
+    const instanceId = newInstanceId(req.occurredAt, `${seed}:instance`);
+    const region = typeof b.region === 'string' && b.region ? b.region : 'iad';
+    const createdAt = nowIso(req.occurredAt);
+    const base = {
+        app_name: appName,
+        name,
+        region,
+        instance_id: instanceId,
+        private_ip: machinePrivateIp(id),
+        created_at: createdAt,
+        machine_updated_at: createdAt,
+        config,
+        image_ref: imageRefOf(image),
+        cordoned: false,
+        _config_history: [{ version: instanceId, user_config: config }],
+        _container_ref: null,
+        _twin_runtime: runtime.kind,
+        _twin_local_ports: [],
+    };
+    let events = [machineEvent('launch', 'created', 'user', req.occurredAt, 0)];
+    let state = 'created';
+    let leaseFields = {};
+    let nonce;
+    if (typeof b.lease_ttl === 'number' && b.lease_ttl > 0) {
+        nonce = newLeaseNonce(`${seed}:lease`);
+        leaseFields = {
+            lease_nonce: nonce,
+            lease_owner: 'twin@local',
+            lease_description: '',
+            lease_expires_at: Math.floor(nowEpochMs(req.occurredAt) / 1000) + Math.floor(b.lease_ttl),
+        };
+    }
+    if (b.skip_launch === true) {
+        const m = await write('machine', id, { ...base, ...leaseFields, state, events }, 'machine.create', req.root, req.occurredAt);
+        await attachVolumes(mountVolumes, id, req);
+        return { status: 200, body: machineView(m, nonce ? { nonce } : {}) };
+    }
+    // Attach BEFORE launching (the updateMachine order — §9 round two, finding 2): a launch that
+    // fails must leave attachments consistent with the persisted config, or the failed machine's
+    // mounts are claimable by a second machine while the first still holds them in config.
+    await attachVolumes(mountVolumes, id, req);
+    // The execution plane actually runs the image (real Docker when serving with the docker
+    // runtime; the virtual ledger otherwise).
+    let launched;
+    try {
+        launched = await runtime.run(containerSpecOf({ ...base, id, state, events }));
+    }
+    catch (e) {
+        // Launch failure: the machine is persisted in state `failed` (start event status failed) and
+        // the request fails with a 422 — a disclosed modeling of Fly's launch-failure surface.
+        events = [...events, machineEvent('start', 'failed', 'flyd', req.occurredAt, events.length)];
+        const failure = e instanceof Error ? e.message : String(e);
+        await write('machine', id, { ...base, ...leaseFields, state: 'failed', events, _twin_last_failure: failure }, 'machine.create', req.root, req.occurredAt);
+        return err(`failed to launch VM: ${failure}`, 422);
+    }
+    events = [...events, machineEvent('start', 'started', 'flyd', req.occurredAt, events.length)];
+    state = 'started';
+    const m = await write('machine', id, {
+        ...base, ...leaseFields, state, events,
+        _container_ref: launched.containerRef,
+        _twin_local_ports: launched.publishedPorts ?? [],
+    }, 'machine.create', req.root, req.occurredAt);
+    return { status: 200, body: machineView(m, nonce ? { nonce } : {}) };
+}
+async function attachVolumes(vols, machineId, req) {
+    for (const vol of vols) {
+        await write('volume', String(vol.id), { ...vol, attached_machine_id: machineId }, 'volume.attach', req.root, req.occurredAt);
+    }
+}
+async function detachVolumesOf(machineId, req) {
+    for (const vol of rows('volume', req.root).filter((v) => v.attached_machine_id === machineId)) {
+        await write('volume', String(vol.id), { ...vol, attached_machine_id: null }, 'volume.detach', req.root, req.occurredAt);
+    }
+}
+async function updateMachine(req, runtime, m, headers, params) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    if (m.state === 'destroyed')
+        return err('machine not found', 404);
+    const b = parseBody(req);
+    const config = b.config;
+    if (!config || typeof config !== 'object')
+        return err('machine config is required', 400);
+    const image = typeof config.image === 'string' ? config.image.trim() : '';
+    if (!image)
+        return err('you must provide an image for the machine', 422);
+    const guestError = guestConfigError(config);
+    if (guestError)
+        return guestError;
+    // The SAME mount rulebook as create (§9 finding 2): unknown volume → 404, a volume attached to
+    // ANOTHER machine → 422; this machine's own attachments are legitimate. Attachments are then
+    // RECONCILED — volumes dropped from the config detach, added ones attach.
+    const appName = String(m.app_name);
+    const resolved = resolveMounts(config, appName, String(m.id), req);
+    if (resolved.error)
+        return resolved.error;
+    const nextVolumeIds = new Set(resolved.volumes.map((v) => String(v.id)));
+    for (const vol of rows('volume', req.root).filter((v) => v.attached_machine_id === String(m.id) && !nextVolumeIds.has(String(v.id)))) {
+        await write('volume', String(vol.id), { ...vol, attached_machine_id: null }, 'volume.detach', req.root, req.occurredAt);
+    }
+    await attachVolumes(resolved.volumes.filter((v) => !v.attached_machine_id), String(m.id), req);
+    const wasStarted = m.state === 'started';
+    // A new instance/version per update, seeded off the machine and how many versions it already
+    // has — so re-applying the same update to two identical worlds yields the same version (R9).
+    const historyLength = (m._config_history ?? []).length;
+    const instanceId = newInstanceId(req.occurredAt, `instance:${String(m.id)}:${nowIso(req.occurredAt)}:${historyLength}`);
+    const history = [...(m._config_history ?? []), { version: instanceId, user_config: config }];
+    let events = pushEvent(m, 'update', wasStarted ? 'started' : String(m.state), 'user', req.occurredAt);
+    let containerRef = m._container_ref;
+    let localPorts = m._twin_local_ports ?? [];
+    if (wasStarted) {
+        // An update REPLACES the running machine (new instance/version): reap the old container and
+        // launch the new config.
+        if (typeof containerRef === 'string' && containerRef) {
+            try {
+                await runtime.remove(containerRef);
+            }
+            catch { /* already gone */ }
+        }
+        const next = { ...m, config, instance_id: instanceId, image_ref: imageRefOf(image) };
+        try {
+            const launched = await runtime.run(containerSpecOf(next));
+            containerRef = launched.containerRef;
+            localPorts = launched.publishedPorts ?? [];
+        }
+        catch (e) {
+            events = [...events, machineEvent('start', 'failed', 'flyd', req.occurredAt, events.length)];
+            const failure = e instanceof Error ? e.message : String(e);
+            await write('machine', String(m.id), { ...m, config, instance_id: instanceId, image_ref: imageRefOf(image), _config_history: history, state: 'failed', events, _container_ref: null, _twin_local_ports: [], _flyd_restart_attempts: 0, _twin_last_failure: failure, machine_updated_at: nowIso(req.occurredAt) }, 'machine.update', req.root, req.occurredAt);
+            return err(`failed to launch VM: ${failure}`, 422);
+        }
+    }
+    const updated = await write('machine', String(m.id), {
+        ...m,
+        config,
+        instance_id: instanceId,
+        image_ref: imageRefOf(image),
+        _config_history: history,
+        events,
+        _container_ref: containerRef,
+        _twin_local_ports: localPorts,
+        _flyd_restart_attempts: 0,
+        _twin_last_failure: null,
+        machine_updated_at: nowIso(req.occurredAt),
+    }, 'machine.update', req.root, req.occurredAt);
+    return { status: 200, body: machineView(updated, { includeLeases: params?.get('include_leases') === 'true', ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}) }) };
+}
+async function destroyMachineRow(m, req, runtime) {
+    if (typeof m._container_ref === 'string' && m._container_ref) {
+        try {
+            await runtime.remove(m._container_ref);
+        }
+        catch { /* container already gone */ }
+    }
+    const events = pushEvent(m, 'destroy', 'destroyed', 'user', req.occurredAt);
+    await write('machine', String(m.id), { ...m, state: 'destroyed', events, _container_ref: null, machine_updated_at: nowIso(req.occurredAt) }, 'machine.destroy', req.root, req.occurredAt);
+    await detachVolumesOf(String(m.id), req);
+}
+async function startMachine(req, runtime, m, headers) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    const prev = String(m.state);
+    if (prev === 'destroyed' || prev === 'destroying')
+        return err('machine not found', 404);
+    if (prev === 'started')
+        return { status: 200, body: { previous_state: 'started' } };
+    if (prev !== 'created' && prev !== 'stopped' && prev !== 'suspended' && prev !== 'failed') {
+        return err(`machine cannot be started from state ${prev}`, 400);
+    }
+    let containerRef = m._container_ref;
+    let localPorts = m._twin_local_ports ?? [];
+    try {
+        if (prev === 'suspended' && runtime.unpause && typeof containerRef === 'string' && containerRef) {
+            await runtime.unpause(containerRef);
+        }
+        else if (prev === 'stopped' && runtime.start && typeof containerRef === 'string' && containerRef) {
+            // A stopped Machine that starts again is RESET to its original state on real Fly (only
+            // mounted volumes survive), so this is a relaunch, not a resume: re-consult the mount
+            // rulebook exactly like a fresh launch, and take the plane's NEW handle and ports.
+            const check = resolveMounts((m.config ?? {}), String(m.app_name), String(m.id), req);
+            if (check.error)
+                return check.error;
+            const restarted = await runtime.start(containerRef, containerSpecOf(m));
+            containerRef = restarted.containerRef;
+            localPorts = restarted.publishedPorts ?? [];
+        }
+        else {
+            // Fresh launch (created/failed, or a runtime without start): the machine's mounts may have
+            // been destroyed or claimed since the config was written — re-consult the rulebook, and
+            // reap any stale container (deterministic names) before running.
+            const check = resolveMounts((m.config ?? {}), String(m.app_name), String(m.id), req);
+            if (check.error)
+                return check.error;
+            if (typeof containerRef === 'string' && containerRef) {
+                try {
+                    await runtime.remove(containerRef);
+                }
+                catch { /* already gone */ }
+            }
+            const launched = await runtime.run(containerSpecOf(m));
+            containerRef = launched.containerRef;
+            localPorts = launched.publishedPorts ?? [];
+        }
+    }
+    catch (e) {
+        const failure = e instanceof Error ? e.message : String(e);
+        const events = [...(m.events ?? []), machineEvent('start', 'failed', 'flyd', req.occurredAt, (m.events ?? []).length, { failure })];
+        await write('machine', String(m.id), { ...m, events, _twin_last_failure: failure, machine_updated_at: nowIso(req.occurredAt) }, 'machine.start_failure', req.root, req.occurredAt);
+        return err(`failed to start VM: ${failure}`, 422);
+    }
+    const events = pushEvent(m, 'start', 'started', 'user', req.occurredAt);
+    await write('machine', String(m.id), { ...m, state: 'started', events, _container_ref: containerRef, _twin_local_ports: localPorts, _flyd_restart_attempts: 0, _twin_last_failure: null, machine_updated_at: nowIso(req.occurredAt) }, 'machine.start', req.root, req.occurredAt);
+    return { status: 200, body: { previous_state: prev } };
+}
+async function stopMachine(req, runtime, m, headers) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    const prev = String(m.state);
+    if (prev === 'destroyed' || prev === 'destroying')
+        return err('machine not found', 404);
+    if (prev === 'stopped' || prev === 'created')
+        return { status: 200, body: { ok: true } };
+    const b = parseBody(req);
+    if (typeof m._container_ref === 'string' && m._container_ref) {
+        const timeout = typeof b.timeout === 'string' ? parseInt(b.timeout, 10) : (typeof b.timeout === 'number' ? b.timeout : undefined);
+        try {
+            await runtime.stop(m._container_ref, {
+                ...(typeof b.signal === 'string' ? { signal: b.signal } : {}),
+                ...(timeout !== undefined && Number.isFinite(timeout) ? { timeoutSeconds: timeout } : {}),
+            });
+        }
+        catch { /* container already stopped */ }
+    }
+    const events = pushEvent(m, 'stop', 'stopped', 'user', req.occurredAt);
+    await write('machine', String(m.id), { ...m, state: 'stopped', events, machine_updated_at: nowIso(req.occurredAt) }, 'machine.stop', req.root, req.occurredAt);
+    return { status: 200, body: { ok: true } };
+}
+async function restartMachine(req, runtime, m, headers) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    const prev = String(m.state);
+    if (prev === 'destroyed' || prev === 'destroying')
+        return err('machine not found', 404);
+    let containerRef = m._container_ref;
+    let localPorts = m._twin_local_ports ?? [];
+    try {
+        if (prev === 'started' && typeof containerRef === 'string' && containerRef) {
+            await runtime.stop(containerRef);
+            // A restart is a stop→start: same vendor rootfs reset, so the plane relaunches rather
+            // than resuming, and the machine picks up the new handle/ports.
+            if (runtime.start) {
+                const restarted = await runtime.start(containerRef, containerSpecOf(m));
+                containerRef = restarted.containerRef;
+                localPorts = restarted.publishedPorts ?? [];
+            }
+            else {
+                await runtime.remove(containerRef);
+                const launched = await runtime.run(containerSpecOf(m));
+                containerRef = launched.containerRef;
+                localPorts = launched.publishedPorts ?? [];
+            }
+        }
+        else {
+            // Relaunch of a non-started machine: re-consult the mount rulebook (its volumes may have
+            // been destroyed/claimed since) and reap any stale container first (deterministic names).
+            const check = resolveMounts((m.config ?? {}), String(m.app_name), String(m.id), req);
+            if (check.error)
+                return check.error;
+            if (typeof containerRef === 'string' && containerRef) {
+                try {
+                    await runtime.remove(containerRef);
+                }
+                catch { /* already gone */ }
+            }
+            const launched = await runtime.run(containerSpecOf(m));
+            containerRef = launched.containerRef;
+            localPorts = launched.publishedPorts ?? [];
+        }
+    }
+    catch (e) {
+        const failure = e instanceof Error ? e.message : String(e);
+        const events = [...(m.events ?? []), machineEvent('restart', 'failed', 'flyd', req.occurredAt, (m.events ?? []).length, { failure })];
+        await write('machine', String(m.id), { ...m, events, _twin_last_failure: failure, machine_updated_at: nowIso(req.occurredAt) }, 'machine.restart_failure', req.root, req.occurredAt);
+        return err(`failed to restart VM: ${failure}`, 422);
+    }
+    let events = pushEvent(m, 'restart', 'stopping', 'user', req.occurredAt);
+    events = [...events, machineEvent('start', 'started', 'flyd', req.occurredAt, events.length)];
+    // _flyd_restart_attempts resets: an explicit operator restart restores the supervision budget.
+    await write('machine', String(m.id), { ...m, state: 'started', events, _container_ref: containerRef, _twin_local_ports: localPorts, _flyd_restart_attempts: 0, _twin_last_failure: null, machine_updated_at: nowIso(req.occurredAt) }, 'machine.restart', req.root, req.occurredAt);
+    return { status: 200, body: { ok: true } };
+}
+const FLY_SIGNALS = new Set(['SIGABRT', 'SIGALRM', 'SIGFPE', 'SIGHUP', 'SIGILL', 'SIGINT', 'SIGKILL', 'SIGPIPE', 'SIGQUIT', 'SIGSEGV', 'SIGTERM', 'SIGTRAP', 'SIGUSR1', 'SIGUSR2']);
+async function signalMachine(req, runtime, m, headers) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    if (m.state !== 'started')
+        return err('machine is not started', 400);
+    const b = parseBody(req);
+    // fly-go's Kill() sends {signal: 9} (a number); the OpenAPI SignalRequest is a string enum.
+    const signal = typeof b.signal === 'number'
+        ? { 1: 'SIGHUP', 2: 'SIGINT', 3: 'SIGQUIT', 9: 'SIGKILL', 15: 'SIGTERM' }[b.signal]
+        : (typeof b.signal === 'string' ? b.signal.toUpperCase() : undefined);
+    if (!signal || !FLY_SIGNALS.has(signal))
+        return err('invalid signal', 400);
+    if (runtime.signal && typeof m._container_ref === 'string' && m._container_ref) {
+        try {
+            await runtime.signal(m._container_ref, signal);
+        }
+        catch { /* container gone; fold on next read */ }
+    }
+    return { status: 200, body: { ok: true } };
+}
+async function suspendMachine(req, runtime, m, headers) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    if (m.state !== 'started')
+        return err('machine must be started to suspend', 400);
+    if (typeof m._container_ref === 'string' && m._container_ref) {
+        try {
+            if (runtime.pause)
+                await runtime.pause(m._container_ref);
+            else
+                await runtime.stop(m._container_ref); // documented fallback: suspend falls back to stop
+        }
+        catch { /* container gone; fold on next read */ }
+    }
+    const events = pushEvent(m, 'suspend', 'suspended', 'user', req.occurredAt);
+    await write('machine', String(m.id), { ...m, state: 'suspended', events, machine_updated_at: nowIso(req.occurredAt) }, 'machine.suspend', req.root, req.occurredAt);
+    return { status: 200, body: { ok: true } };
+}
+async function cordonMachine(req, m, headers, cordoned) {
+    const blocked = leaseBlocks(m, headers, req.occurredAt);
+    if (blocked)
+        return blocked;
+    if (m.state === 'destroyed')
+        return err('machine not found', 404);
+    await write('machine', String(m.id), { ...m, cordoned, machine_updated_at: nowIso(req.occurredAt) }, cordoned ? 'machine.cordon' : 'machine.uncordon', req.root, req.occurredAt);
+    return { status: 200, body: { ok: true } };
+}
+async function waitMachine(req, m, params) {
+    const desired = params.get('state') ?? 'started';
+    // Only the states a client can genuinely wait FOR (the spec's filterable set + destroyed);
+    // transient/internal states (starting, replacing, failed, …) are a 400, not an eternal 408.
+    const WAITABLE = ['created', 'started', 'stopped', 'suspended', 'destroyed'];
+    if (!WAITABLE.includes(desired)) {
+        return err(`invalid desired state ${desired}`, 400);
+    }
+    if (String(m.state) === desired) {
+        return { status: 200, body: { ok: true } };
+    }
+    // Local transitions complete synchronously, so a mismatched state cannot change while a wait
+    // is pending — answer Fly's own timeout immediately (docs response table: 408; the message is
+    // flaps' real one).
+    return err("timeout reached waiting for machine's state to change", 408);
+}
+async function execMachine(req, runtime, m) {
+    if (m.state !== 'started')
+        return err('machine is not started', 400);
+    const b = parseBody(req);
+    const command = Array.isArray(b.command) && b.command.length > 0
+        ? b.command.map(String)
+        : (typeof b.cmd === 'string' && b.cmd.trim() ? b.cmd.trim().split(/\s+/) : []);
+    if (command.length === 0)
+        return err('command is required', 400);
+    if (!runtime.exec || typeof m._container_ref !== 'string' || !m._container_ref) {
+        // The virtual plane cannot execute anything, and inventing output would be a fabricated
+        // success — fail loudly inside the vendor envelope (serve with --local-execution for real exec).
+        return err('exec unavailable: the twin execution plane is virtual (serve with a docker runtime for real exec)', 400);
+    }
+    try {
+        const out = await runtime.exec(m._container_ref, command, typeof b.timeout === 'number' ? { timeoutSeconds: b.timeout } : {});
+        return { status: 200, body: { exit_code: out.exitCode, stdout: out.stdout, stderr: out.stderr } };
+    }
+    catch (e) {
+        return err(`exec failed: ${e instanceof Error ? e.message : String(e)}`, 400);
+    }
+}
+// Lease wire shape: fly-go MachineLease — {status, data:{nonce,expires_at,owner,description?,version}}.
+function leaseData(m) {
+    return {
+        nonce: String(m.lease_nonce),
+        expires_at: Number(m.lease_expires_at),
+        owner: String(m.lease_owner ?? 'twin@local'),
+        description: String(m.lease_description ?? ''),
+        version: String(m.instance_id),
+    };
+}
+async function leaseMachine(req, m, params, headers, method) {
+    if (method === 'GET') {
+        if (!leaseIsLive(m, req.occurredAt))
+            return err('lease not found', 404);
+        return { status: 200, body: { status: 'success', data: leaseData(m) } };
+    }
+    if (method === 'POST') {
+        const b = parseBody(req);
+        // fly-go AcquireLease sends ?ttl=; the OpenAPI CreateLeaseRequest carries {ttl, description}.
+        const ttlRaw = params.get('ttl') ?? (typeof b.ttl === 'number' ? String(b.ttl) : undefined);
+        const ttl = ttlRaw !== undefined ? parseInt(String(ttlRaw), 10) : 60;
+        if (!Number.isFinite(ttl) || ttl <= 0)
+            return err('invalid lease ttl', 400);
+        const nonce = headers['fly-machine-lease-nonce'];
+        if (leaseIsLive(m, req.occurredAt) && nonce !== m.lease_nonce) {
+            return err(`machine ID ${m.id} lease currently held by ${m.lease_owner ?? 'twin@local'}`, 409);
+        }
+        const isRefresh = leaseIsLive(m, req.occurredAt) && nonce === m.lease_nonce;
+        const updated = await write('machine', String(m.id), {
+            ...m,
+            lease_nonce: isRefresh ? m.lease_nonce : newLeaseNonce(`lease:${String(m.id)}:${nowIso(req.occurredAt)}:${String(m._rev ?? 0)}`),
+            lease_owner: 'twin@local',
+            lease_description: typeof b.description === 'string' ? b.description : String(m.lease_description ?? ''),
+            lease_expires_at: Math.floor(nowEpochMs(req.occurredAt) / 1000) + ttl,
+        }, 'machine.lease_acquire', req.root, req.occurredAt);
+        return { status: 201, body: { status: 'success', data: leaseData(updated) } };
+    }
+    if (method === 'DELETE') {
+        // ⚠ doc-unverified status: with no live lease there is nothing to release — served as the
+        // same 404 the GET gives, never a fabricated success.
+        if (!leaseIsLive(m, req.occurredAt))
+            return err('lease not found', 404);
+        const nonce = headers['fly-machine-lease-nonce'];
+        if (nonce !== m.lease_nonce)
+            return err('invalid lease nonce', 400);
+        await write('machine', String(m.id), { ...m, lease_nonce: null, lease_expires_at: null, lease_description: null }, 'machine.lease_release', req.root, req.occurredAt);
+        return { status: 200, body: { status: 'success' } };
+    }
+    return err('not found', 404);
+}
+// ── volumes ───────────────────────────────────────────────────────────────────────────────────
+async function handleVolumes(req, runtime, appName, seg, method) {
+    if (seg.length === 4) {
+        if (method === 'GET') {
+            const vols = liveAppRows('volume', appName, req.root).filter((v) => !volumeGone(v, req.occurredAt));
+            return { status: 200, body: vols.map(volumeView) }; // BARE array (flaps_volumes.go)
+        }
+        if (method === 'POST') {
+            const b = parseBody(req);
+            const name = typeof b.name === 'string' ? b.name.trim() : '';
+            if (!name)
+                return err('volume name is required', 422);
+            if (!/^[a-z0-9_]+$/.test(name))
+                return err(`Validation failed: Name '${name}' must contain only lowercase letters, numbers, and underscores`, 422);
+            const sizeGb = typeof b.size_gb === 'number' && b.size_gb > 0 ? Math.floor(b.size_gb) : 1;
+            const id = newVolumeId(`volume:${appName}:${name}:${nowIso(req.occurredAt)}:${rows('volume', req.root).length}`);
+            const zone = createHash('sha256').update(id).digest('hex').slice(0, 4);
+            if (runtime.createVolume) {
+                try {
+                    await runtime.createVolume(id);
+                }
+                catch { /* volume materializes lazily at machine run */ }
+            }
+            const v = await write('volume', id, {
+                app_name: appName,
+                name,
+                region: typeof b.region === 'string' && b.region ? b.region : 'iad',
+                size_gb: sizeGb,
+                encrypted: b.encrypted !== false,
+                fstype: typeof b.fstype === 'string' && b.fstype ? b.fstype : 'ext4',
+                snapshot_retention: typeof b.snapshot_retention === 'number' ? b.snapshot_retention : 5,
+                auto_backup_enabled: b.auto_backup_enabled !== false,
+                zone,
+                state: 'created',
+                attached_machine_id: null,
+                created_at: nowIso(req.occurredAt),
+                snapshots: [],
+            }, 'volume.create', req.root, req.occurredAt);
+            return { status: 200, body: volumeView(v) };
+        }
+        return err('not found', 404);
+    }
+    const volumeId = seg[4];
+    const v = getRow('volume', volumeId, req.root);
+    if (!v || v.app_name !== appName || volumeGone(v, req.occurredAt))
+        return err('volume not found', 404);
+    if (seg.length === 5) {
+        if (method === 'GET')
+            return { status: 200, body: volumeView(v) };
+        if (method === 'PUT') {
+            const b = parseBody(req);
+            const updated = await write('volume', volumeId, {
+                ...v,
+                ...(typeof b.snapshot_retention === 'number' ? { snapshot_retention: b.snapshot_retention } : {}),
+                ...(typeof b.auto_backup_enabled === 'boolean' ? { auto_backup_enabled: b.auto_backup_enabled } : {}),
+            }, 'volume.update', req.root, req.occurredAt);
+            return { status: 200, body: volumeView(updated) };
+        }
+        if (method === 'DELETE') {
+            if (typeof v.attached_machine_id === 'string' && v.attached_machine_id) {
+                return err(`volume ${v.id} is attached to machine ${v.attached_machine_id}`, 400);
+            }
+            if (runtime.removeVolume) {
+                try {
+                    await runtime.removeVolume(volumeId);
+                }
+                catch { /* never materialized */ }
+            }
+            const pending = await write('volume', volumeId, { ...v, state: 'pending_destroy', _destroy_requested_at: nowIso(req.occurredAt) }, 'volume.delete', req.root, req.occurredAt);
+            return { status: 200, body: volumeView(pending) }; // returns the Volume (flaps DeleteVolume)
+        }
+        return err('not found', 404);
+    }
+    if (seg.length === 6 && seg[5] === 'extend' && method === 'PUT') {
+        const b = parseBody(req);
+        const sizeGb = typeof b.size_gb === 'number' ? Math.floor(b.size_gb) : NaN;
+        if (!Number.isFinite(sizeGb) || sizeGb <= Number(v.size_gb ?? 1)) {
+            return err('volumes can only be extended: size_gb must be larger than the current size', 400);
+        }
+        const updated = await write('volume', volumeId, { ...v, size_gb: sizeGb }, 'volume.extend', req.root, req.occurredAt);
+        const attached = typeof v.attached_machine_id === 'string' && v.attached_machine_id.length > 0;
+        return { status: 200, body: { needs_restart: attached, volume: volumeView(updated) } };
+    }
+    if (seg.length === 6 && seg[5] === 'snapshots') {
+        if (method === 'GET') {
+            return { status: 200, body: (v.snapshots ?? []) }; // BARE array
+        }
+        if (method === 'POST') {
+            const snapshots = [...(v.snapshots ?? [])];
+            snapshots.push({
+                id: `vs_${createHash('sha256').update(`${volumeId}:${snapshots.length}`).digest('hex').slice(0, 20)}`,
+                created_at: nowIso(req.occurredAt),
+                digest: '',
+                retention_days: Number(v.snapshot_retention ?? 5),
+                size: 0,
+                status: 'created',
+                volume_size: Number(v.size_gb ?? 1) * 1024 * 1024 * 1024,
+            });
+            await write('volume', volumeId, { ...v, snapshots }, 'volume.snapshot', req.root, req.occurredAt);
+            return { status: 200, body: {} };
+        }
+    }
+    return err('not found', 404);
+}
+// ── app secrets ───────────────────────────────────────────────────────────────────────────────
+function secretKid(appName, name) {
+    return `${appName}/${name}`;
+}
+/** The app-wide secrets version is a MONOTONIC counter kept on the app row and bumped by every
+ *  set/bulk/delete (§9 round one, finding 7: the first draft derived it from max(per-secret
+ *  version), which went BACKWARDS after deletes — unbuildable ground for ?min_version= and
+ *  CreateMachineRequest.min_secrets_version). */
+async function bumpSecretsVersion(req, appName) {
+    const app = getRow('app', appName, req.root);
+    const version = (typeof app?._secrets_version === 'number' ? app._secrets_version : 0) + 1;
+    if (app)
+        await write('app', appName, { ...app, _secrets_version: version }, 'app._secrets_version', req.root, req.occurredAt);
+    return version;
+}
+async function handleSecrets(req, appName, seg, params, method) {
+    const showSecrets = params.get('show_secrets') === 'true';
+    const appSecrets = () => rows('secret', req.root).filter((s) => s.app_name === appName && s.deleted !== true);
+    if (seg.length === 4) {
+        if (method === 'GET') {
+            return { status: 200, body: { secrets: appSecrets().map((s) => secretView(s, showSecrets)) } };
+        }
+        if (method === 'POST') {
+            // Secrets_update: bulk {values} upsert -> {secrets, version} (ONE version bump per update
+            // operation, like the vendor's release-versioned secrets).
+            const b = parseBody(req);
+            const values = b.values;
+            if (!values || typeof values !== 'object' || Array.isArray(values))
+                return err('values object is required', 400);
+            for (const [name, value] of Object.entries(values)) {
+                await writeSecret(req, appName, name, String(value));
+            }
+            const version = await bumpSecretsVersion(req, appName);
+            return { status: 200, body: { secrets: appSecrets().map((s) => secretView(s, false)), version } };
+        }
+        return err('not found', 404);
+    }
+    const name = decodeURIComponent(seg[4]);
+    const existing = getRow('secret', secretKid(appName, name), req.root);
+    const live = existing && existing.deleted !== true ? existing : undefined;
+    if (seg.length === 5) {
+        if (method === 'GET') {
+            if (!live)
+                return err('secret not found', 404);
+            return { status: 200, body: secretView(live, showSecrets) };
+        }
+        if (method === 'POST') {
+            const b = parseBody(req);
+            if (typeof b.value !== 'string' || b.value.length === 0)
+                return err('value is required', 400);
+            const s = await writeSecret(req, appName, name, b.value);
+            const version = await bumpSecretsVersion(req, appName);
+            return { status: 201, body: { ...secretView(s, false), version } };
+        }
+        if (method === 'DELETE') {
+            // ⚠ doc-unverified status: the spec documents only 200 for Secret_delete; an unknown name
+            // is served the twin's 404 rather than a fabricated success.
+            if (!live)
+                return err('secret not found', 404);
+            await write('secret', secretKid(appName, name), { ...live, deleted: true }, 'secret.delete', req.root, req.occurredAt);
+            const version = await bumpSecretsVersion(req, appName);
+            return { status: 200, body: { version } };
+        }
+        return err('not found', 404);
+    }
+    return err('not found', 404); // encrypt/decrypt/sign/verify (secretkeys) — real, unmodeled todos
+}
+async function writeSecret(req, appName, name, value) {
+    const existing = getRow('secret', secretKid(appName, name), req.root);
+    return write('secret', secretKid(appName, name), {
+        app_name: appName,
+        secret_name: name,
+        value,
+        digest: createHash('sha256').update(value).digest('hex').slice(0, 32),
+        created_at: existing && existing.deleted !== true ? existing.created_at : nowIso(req.occurredAt),
+        secret_updated_at: nowIso(req.occurredAt),
+    }, 'secret.set', req.root, req.occurredAt);
+}
+// ── conformance snapshot (dev tooling reads this; fly-conformance.ts probes every entry) ──────
+export function flyTwinSnapshot() {
+    return {
+        implementedEndpoints: [
+            'GET /v1/apps',
+            'POST /v1/apps',
+            'GET /v1/apps/{app_name}',
+            'DELETE /v1/apps/{app_name}',
+            'GET /v1/apps/{app_name}/machines',
+            'POST /v1/apps/{app_name}/machines',
+            'GET /v1/apps/{app_name}/machines/{machine_id}',
+            'POST /v1/apps/{app_name}/machines/{machine_id}',
+            'DELETE /v1/apps/{app_name}/machines/{machine_id}',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/start',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/stop',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/restart',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/signal',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/suspend',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/cordon',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/uncordon',
+            'GET /v1/apps/{app_name}/machines/{machine_id}/wait',
+            'GET /v1/apps/{app_name}/machines/{machine_id}/events',
+            'GET /v1/apps/{app_name}/machines/{machine_id}/versions',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/exec',
+            'GET /v1/apps/{app_name}/machines/{machine_id}/lease',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/lease',
+            'DELETE /v1/apps/{app_name}/machines/{machine_id}/lease',
+            'GET /v1/apps/{app_name}/machines/{machine_id}/metadata',
+            'GET /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}',
+            'POST /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}',
+            'DELETE /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}',
+            'GET /v1/apps/{app_name}/volumes',
+            'POST /v1/apps/{app_name}/volumes',
+            'GET /v1/apps/{app_name}/volumes/{volume_id}',
+            'PUT /v1/apps/{app_name}/volumes/{volume_id}',
+            'DELETE /v1/apps/{app_name}/volumes/{volume_id}',
+            'PUT /v1/apps/{app_name}/volumes/{volume_id}/extend',
+            'GET /v1/apps/{app_name}/volumes/{volume_id}/snapshots',
+            'POST /v1/apps/{app_name}/volumes/{volume_id}/snapshots',
+            'GET /v1/apps/{app_name}/secrets',
+            'POST /v1/apps/{app_name}/secrets',
+            'GET /v1/apps/{app_name}/secrets/{secret_name}',
+            'POST /v1/apps/{app_name}/secrets/{secret_name}',
+            'DELETE /v1/apps/{app_name}/secrets/{secret_name}',
+        ],
+        resourceTypes: [...FLY_RESOURCE_TYPES],
+    };
+}