@volter/twin-fly 0.1.0

package/dist/src/fly-capabilities.js

@@ -0,0 +1,1212 @@
+// fly capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from Fly's first-party Machines API OpenAPI (live-fetched docs.machines.dev/swagger/doc.json,
+// "Machines API 1.0" — 68 paths across the tags Apps / Machines / Volumes / Secrets /
+// TLS Certificates / Tokens / Organizations / Platform / Postgres Clusters) cross-checked
+// against superfly/fly-go (flyctl's own client) — see spec-sources.json — NOT from what this
+// twin has built. Many entries start `todo` and coverage reads honestly partial.
+//
+// THE EXECUTION-PLANE DOCTRINE (the point of this pack): the control plane is twinned; the
+// execution plane is REAL — a created/started machine actually runs config.image as a local
+// Docker container through the injected `FlyContainerRuntime` seam. EVERY verify below runs
+// OFFLINE: the seam is exercised with recording/failing FAKE runtimes (or the pure-ledger
+// virtual default), never a live Docker daemon — the real-Docker proof lives in
+// fly-docker.integration.test.ts, which self-skips loudly without a daemon and is NOT a
+// capability proof. Real Fly runs Firecracker on Fly hardware; this twin runs containers —
+// genuine compute, and the control-plane surface is identical.
+//
+// `verify()` (required to count as done) is ground truth and drives the KERNEL-BACKED handler
+// on a FRESH temp root — never a spawned mock. Negative paths assert Fly's own status codes
+// (docs response table: 401 / 404 / 408 / 422).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, verifyBoundary } from '@volter/world-tooling';
+import { handleFlyTwinRequest } from "./fly-twin.js";
+import { checkFlyConformance } from "./fly-conformance.js";
+import { liveFlyExecute, syncFlyFromReal } from "./fly-connector.js";
+import { FlyBudget, FlyBudgetError, FLY_BUDGET_CEILING, FLY_CALL_WEIGHTS } from "./fly-budget.js";
+// (fly is an API-first vendor with no product UI to mirror — docs/contributing/architecture.md C1b: an integrator
+// CALLS the Machines API / drives flyctl; fly.io's dashboard is incidental key/billing/log
+// tooling, not where the work happens. No mirror, no UI capabilities — see README ## Coverage.)
+const OCCURRED_AT = '2026-01-01T00:00:00.000Z';
+/** A recording fake execution plane: every lifecycle call is recorded; overrides inject
+ *  failures/exits so the seam's folds are provable offline. */
+function fakeRuntime(overrides = {}) {
+    const calls = [];
+    let starts = 0;
+    const rec = (op) => (...args) => { calls.push({ op, args }); };
+    const runtime = {
+        kind: 'fake',
+        async run(spec) {
+            calls.push({ op: 'run', args: [spec] });
+            return { containerRef: `fake:${spec.machineId}`, publishedPorts: spec.ports.map((p, i) => ({ internal: p.internal, host: 41000 + i })) };
+        },
+        async stop(...args) { rec('stop')(...args); },
+        // start is a RECREATE, not a resume (Fly resets a stopped Machine's rootfs): the fake hands
+        // back a FRESH handle, exactly as a real plane that relaunched the image would.
+        async start(ref, spec) {
+            calls.push({ op: 'start', args: [ref, spec] });
+            starts += 1;
+            // A DIFFERENT host port than `run`'s: a recreated container gets fresh ephemeral ports, so
+            // a verify can tell "the new handle was re-ledgered" from "the old one was kept".
+            return { containerRef: `fake:${spec.machineId}:start${starts}`, publishedPorts: spec.ports.map((p, i) => ({ internal: p.internal, host: 42000 + i })) };
+        },
+        async remove(...args) { rec('remove')(...args); },
+        async pause(...args) { rec('pause')(...args); },
+        async unpause(...args) { rec('unpause')(...args); },
+        async signal(...args) { rec('signal')(...args); },
+        async exec(_ref, cmd) {
+            calls.push({ op: 'exec', args: [cmd] });
+            return { exitCode: 0, stdout: `ran:${cmd.join(' ')}`, stderr: '' };
+        },
+        async inspect() { return { running: true }; },
+        ...overrides,
+    };
+    return { runtime, calls };
+}
+async function withRoot(steps, opts = {}) {
+    const root = mkdtempSync(join(tmpdir(), 'fly-cap-'));
+    const h = (s) => handleFlyTwinRequest({
+        method: s.m,
+        path: s.p,
+        body: s.b === undefined ? undefined : JSON.stringify(s.b),
+        root,
+        occurredAt: s.at ?? OCCURRED_AT,
+        headers: { authorization: 'Bearer twin-test-token', ...(s.h ?? {}) },
+        ...(opts.runtime ? { runtime: opts.runtime } : {}),
+    });
+    try {
+        return await verifyBoundary('fly.withRoot', () => steps(h, root));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** Seed an app + a started machine (virtual runtime unless injected); returns the machine id. */
+async function seedMachine(h, app = 'twin-app', config = { image: 'nginx:alpine' }, extra = {}) {
+    await h({ m: 'POST', p: '/v1/apps', b: { app_name: app, org_slug: 'personal' } });
+    const r = await h({ m: 'POST', p: `/v1/apps/${app}/machines`, b: { config, ...extra } });
+    return String(r.body.id ?? '');
+}
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+export const FLY_CAPABILITIES = [
+    // ── THE HONEST CARVE-OUTS (what a local twin genuinely cannot be) ───────────────────────────
+    // ── AUTH (faked-but-enforced, D2) ─────────────────────────────────────────────────────────
+    done('fly.auth.bearer_required_401', 'auth', 'A missing/empty Authorization: Bearer token -> 401 (docs response table), never a served resource', 'api', 'core', () => withRoot(async (h) => {
+        const bare = await handleFlyTwinRequest({ method: 'GET', path: '/v1/apps?org_slug=personal', occurredAt: OCCURRED_AT });
+        const withTok = await h({ m: 'GET', p: '/v1/apps?org_slug=personal' });
+        return bare.status === 401 && typeof bare.body.error === 'string' && withTok.status === 200;
+    })),
+    done('fly.auth.read_only_rejects_writes', 'auth', 'readOnly twin rejects every write with 405 while reads still serve (D3) — including the runtime-exit fold, which must NOT persist state on a read-only GET', 'api', 'common', () => {
+        const { runtime } = fakeRuntime({ async inspect() { return { running: false, exitCode: 1 }; } });
+        return withRoot(async (h, root) => {
+            const id = await seedMachine(h, 'ro-app');
+            const write = await handleFlyTwinRequest({ method: 'POST', path: '/v1/apps', body: JSON.stringify({ app_name: 'ro-2', org_slug: 'personal' }), root, readOnly: true, occurredAt: OCCURRED_AT, headers: { authorization: 'Bearer t' } });
+            const read = await handleFlyTwinRequest({ method: 'GET', path: '/v1/apps/ro-app', root, readOnly: true, occurredAt: OCCURRED_AT, headers: { authorization: 'Bearer t' } });
+            // The fold is a WRITE: on a read-only twin a GET must serve control-plane state as-is and
+            // append nothing, even when the (injected) execution plane reports the container exited.
+            const roGet = await handleFlyTwinRequest({ method: 'GET', path: `/v1/apps/ro-app/machines/${id}`, root, readOnly: true, runtime, occurredAt: OCCURRED_AT, headers: { authorization: 'Bearer t' } });
+            const rb = roGet.body;
+            return write.status === 405 && read.status === 200 && read.body.name === 'ro-app'
+                && rb.state === 'started' && rb.events.every((e) => e.type !== 'exit');
+        }, { runtime });
+    }),
+    // ── ERRORS (vendor envelope + unmodeled honesty) ──────────────────────────────────────────
+    done('fly.errors.envelope_shape', 'errors', 'Errors use Fly\'s ErrorResponse envelope: {error: string} with the HTTP status', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/apps/no-such-app' });
+        return r.status === 404 && typeof r.body.error === 'string' && r.body.error.length > 0;
+    })),
+    done('fly.errors.unmodeled_fails_like_vendor', 'errors', 'Unmodeled-but-real routes (machine ps, org listings, certificates) fail 404 in the vendor envelope — never a fabricated success', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const ps = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/ps` });
+        const orgs = await h({ m: 'GET', p: '/v1/orgs/personal/machines' });
+        const certs = await h({ m: 'GET', p: '/v1/apps/twin-app/certificates' });
+        return [ps, orgs, certs].every((r) => r.status === 404 && typeof r.body.error === 'string');
+    })),
+    // ── APPS ──────────────────────────────────────────────────────────────────────────────────
+    done('fly.apps.create', 'apps', 'POST /v1/apps creates an app (201); GET shows name/org/status pending', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'my-app', org_slug: 'acme' } });
+        const got = await h({ m: 'GET', p: '/v1/apps/my-app' });
+        const b = got.body;
+        return r.status === 201 && got.status === 200 && b.name === 'my-app' && b.organization?.slug === 'acme' && b.status === 'pending' && b.machine_count === 0;
+    })),
+    done('fly.apps.create_name_taken_422', 'apps', 'Creating a taken app name -> 422 "Validation failed: Name has already been taken" with status name_taken (DOCUMENTED: docs response table + ErrorResponse.status enum)', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'dup-app', org_slug: 'acme' } });
+        const r = await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'dup-app', org_slug: 'acme' } });
+        const b = r.body;
+        return r.status === 422 && typeof b.error === 'string' && b.error.includes('already been taken') && b.status === 'name_taken';
+    })),
+    done('fly.apps.create_invalid_name_422', 'apps', 'An app name with uppercase/invalid characters -> 422 validation error', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'Bad_Name!', org_slug: 'acme' } });
+        return r.status === 422 && typeof r.body.error === 'string';
+    })),
+    done('fly.apps.list', 'apps', 'GET /v1/apps?org_slug= lists the org\'s apps as {total_apps, apps:[{id,name,machine_count,network,status}]}', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'list-a', org_slug: 'org-one' } });
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'list-b', org_slug: 'org-one' } });
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'other-org', org_slug: 'org-two' } });
+        const r = await h({ m: 'GET', p: '/v1/apps?org_slug=org-one' });
+        const b = r.body;
+        const names = b.apps.map((a) => a.name).sort();
+        return r.status === 200 && b.total_apps === 2 && names.join(',') === 'list-a,list-b';
+    })),
+    done('fly.apps.list_requires_org_slug', 'apps', 'GET /v1/apps without org_slug -> 400 (the OpenAPI marks the param required)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/apps' });
+        return r.status === 400 && typeof r.body.error === 'string';
+    })),
+    done('fly.apps.get_unknown_404', 'apps', 'GET /v1/apps/{unknown} -> 404 {error}', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/apps/never-created' });
+        return r.status === 404 && typeof r.body.error === 'string';
+    })),
+    done('fly.apps.get_machine_count', 'apps', 'App show counts its live machines/volumes (machine_count/volume_count track creates and destroys; a pending_destroy volume counts until purged)', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h, 'count-app');
+        await h({ m: 'POST', p: `/v1/apps/count-app/volumes`, b: { name: 'v_one', size_gb: 1 } });
+        const before = await h({ m: 'GET', p: '/v1/apps/count-app' });
+        await h({ m: 'POST', p: `/v1/apps/count-app/machines/${id}/stop` });
+        await h({ m: 'DELETE', p: `/v1/apps/count-app/machines/${id}` });
+        const vols = await h({ m: 'GET', p: '/v1/apps/count-app/volumes' });
+        await h({ m: 'DELETE', p: `/v1/apps/count-app/volumes/${vols.body[0].id}` });
+        // A deleted volume is pending_destroy and still counted until the purge window passes.
+        const after = await h({ m: 'GET', p: '/v1/apps/count-app', at: new Date(Date.parse(OCCURRED_AT) + 61_000).toISOString() });
+        return before.body.machine_count === 1 && before.body.volume_count === 1
+            && after.body.machine_count === 0 && after.body.volume_count === 0;
+    })),
+    done('fly.apps.delete_202', 'apps', 'DELETE /v1/apps/{name} -> 202 and the app 404s afterwards (its machines are destroyed with it)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h, 'doomed-app');
+        const del = await h({ m: 'DELETE', p: '/v1/apps/doomed-app' });
+        const got = await h({ m: 'GET', p: '/v1/apps/doomed-app' });
+        const machine = await h({ m: 'GET', p: `/v1/apps/doomed-app/machines/${id}` });
+        return del.status === 202 && got.status === 404 && machine.status === 404;
+    })),
+    done('fly.apps.recreate_after_delete', 'apps', 'Deleting an app destroys its VOLUMES and SECRETS with it (the execution plane is reaped too) and frees the name: the recreated app starts EMPTY on every projection — machines (even include_deleted), volumes, secrets, machine_count/volume_count', 'api', 'common', () => {
+        const removed = [];
+        const { runtime } = fakeRuntime({
+            async remove(ref) { removed.push(`c:${ref}`); },
+            async removeVolume(id) { removed.push(`v:${id}`); },
+        });
+        return withRoot(async (h) => {
+            const mid = await seedMachine(h, 'phoenix-app');
+            await h({ m: 'POST', p: '/v1/apps/phoenix-app/volumes', b: { name: 'ghost_vol', size_gb: 1 } });
+            await h({ m: 'POST', p: '/v1/apps/phoenix-app/secrets/GHOST_KEY', b: { value: 'first-life-credential' } });
+            await h({ m: 'DELETE', p: '/v1/apps/phoenix-app' });
+            const re = await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'phoenix-app', org_slug: 'personal' } });
+            const machines = await h({ m: 'GET', p: '/v1/apps/phoenix-app/machines' });
+            const withDeleted = await h({ m: 'GET', p: '/v1/apps/phoenix-app/machines?include_deleted=true' });
+            const volumes = await h({ m: 'GET', p: '/v1/apps/phoenix-app/volumes' });
+            const secrets = await h({ m: 'GET', p: '/v1/apps/phoenix-app/secrets' });
+            const ghost = await h({ m: 'GET', p: '/v1/apps/phoenix-app/secrets/GHOST_KEY?show_secrets=true' });
+            const app = await h({ m: 'GET', p: '/v1/apps/phoenix-app' });
+            const oldMachine = await h({ m: 'GET', p: `/v1/apps/phoenix-app/machines/${mid}` });
+            return re.status === 201 && machines.body.length === 0
+                && withDeleted.body.length === 0
+                && volumes.body.length === 0
+                && secrets.body.secrets.length === 0
+                && ghost.status === 404
+                && app.body.machine_count === 0 && app.body.volume_count === 0
+                && oldMachine.status === 404
+                && removed.some((r) => r.startsWith('c:fake:')) && removed.some((r) => r.startsWith('v:vol_'));
+        }, { runtime });
+    }),
+    todo('fly.apps.deploy_token', 'apps', 'POST /v1/apps/{name}/deploy_token mints a deploy token', 'api', 'niche'),
+    // ── MACHINES — CRUD + lifecycle ───────────────────────────────────────────────────────────
+    done('fly.machines.create', 'machines', 'POST machines with {config:{image}} creates AND starts a machine (Machine shape: 14-hex id, name, region, instance_id, config echoed, image_ref parsed)', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const r = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { name: 'web-1', region: 'lhr', config: { image: 'nginx:1.27', env: { A: 'b' } } } });
+        const b = r.body;
+        return r.status === 200 && /^[0-9a-f]{14}$/.test(b.id) && b.name === 'web-1' && b.region === 'lhr'
+            && b.state === 'started' && b.config?.image === 'nginx:1.27' && b.config?.env?.A === 'b'
+            && b.image_ref?.repository === 'library/nginx' && b.image_ref?.tag === '1.27'
+            && typeof b.instance_id === 'string' && b.instance_id.length === 26;
+    })),
+    done('fly.machines.create_skip_launch', 'machines', 'skip_launch:true leaves the machine in state created (no start event, nothing launched)', 'api', 'common', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1', { image: 'nginx:alpine' }, { skip_launch: true });
+            const got = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}` });
+            const b = got.body;
+            const eventTypes = b.events.map((e) => e.type);
+            return b.state === 'created' && eventTypes.includes('launch') && !eventTypes.includes('start') && calls.every((c) => c.op !== 'run');
+        }, { runtime });
+    }),
+    done('fly.machines.create_requires_image_422', 'machines', 'A config without an image -> 422 {error}; no machine is created', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const r = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { env: { A: 'b' } } } });
+        const list = await h({ m: 'GET', p: '/v1/apps/a1/machines' });
+        return r.status === 422 && typeof r.body.error === 'string' && list.body.length === 0;
+    })),
+    done('fly.machines.create_unknown_app_404', 'machines', 'Creating a machine under an app that does not exist -> 404', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/apps/ghost/machines', b: { config: { image: 'nginx' } } });
+        return r.status === 404 && typeof r.body.error === 'string';
+    })),
+    done('fly.machines.create_name_conflict_422', 'machines', 'A duplicate machine name within the app -> 422 already_exists (⚠ exact message doc-unverified; the uniqueness fact is fly-documented)', 'api', 'common', () => withRoot(async (h) => {
+        await seedMachine(h, 'a1', { image: 'nginx' }, { name: 'web' });
+        const r = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { name: 'web', config: { image: 'nginx' } } });
+        return r.status === 422 && String(r.body.error).includes('already');
+    })),
+    done('fly.machines.generated_name_and_default_region', 'machines', 'Omitting name/region generates a Fly-style adjective-noun-NNNN name and defaults the region', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const b = got.body;
+        return /^[a-z]+-[a-z]+-\d{4}$/.test(b.name) && typeof b.region === 'string' && b.region.length > 0;
+    })),
+    done('fly.machines.get', 'machines', 'GET machines/{id} returns the full Machine (config, image_ref, events, private_ip, version=instance_id, host_status ok)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const r = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const b = r.body;
+        return r.status === 200 && b.id === id && Array.isArray(b.events) && b.events.length >= 2
+            && b.version === b.instance_id && b.host_status === 'ok' && b.cordoned === false
+            && String(b.private_ip).startsWith('fdaa:');
+    })),
+    done('fly.machines.get_unknown_404', 'machines', 'GET machines/{unknown} -> 404 "machine not found"-style {error}', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const r = await h({ m: 'GET', p: '/v1/apps/a1/machines/00000000000000' });
+        return r.status === 404 && typeof r.body.error === 'string';
+    })),
+    done('fly.machines.list', 'machines', 'GET machines lists live machines; ?state= and ?region= filter; destroyed machines appear only with include_deleted=true', 'api', 'core', () => withRoot(async (h) => {
+        const a = await seedMachine(h, 'a1', { image: 'nginx' }, { name: 'm-a', region: 'lhr' });
+        await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { name: 'm-b', region: 'iad', config: { image: 'nginx' } } });
+        await h({ m: 'POST', p: `/v1/apps/a1/machines/${a}/stop` });
+        await h({ m: 'DELETE', p: `/v1/apps/a1/machines/${a}` });
+        const live = await h({ m: 'GET', p: '/v1/apps/a1/machines' });
+        const withDeleted = await h({ m: 'GET', p: '/v1/apps/a1/machines?include_deleted=true' });
+        const lhr = await h({ m: 'GET', p: '/v1/apps/a1/machines?region=lhr&include_deleted=true' });
+        const started = await h({ m: 'GET', p: '/v1/apps/a1/machines?state=started' });
+        // ?state= is documented as a COMMA-SEPARATED list.
+        const multi = await h({ m: 'GET', p: '/v1/apps/a1/machines?state=started,destroyed&include_deleted=true' });
+        return live.body.length === 1 && withDeleted.body.length === 2
+            && lhr.body.every((m) => m.region === 'lhr') && lhr.body.length === 1
+            && started.body.length === 1 && started.body[0].name === 'm-b'
+            && multi.body.length === 2;
+    })),
+    done('fly.machines.update_replaces_config', 'machines', 'POST machines/{id} replaces config, mints a NEW instance_id/version and appends an update event (the old version stays in /versions)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const before = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const up = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}`, b: { config: { image: 'redis:7', env: { NEW: 'yes' } } } });
+        const b = up.body;
+        const versions = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/versions` });
+        return up.status === 200 && b.config?.image === 'redis:7' && b.instance_id !== before.body.instance_id
+            && versions.body.length === 2
+            && b.events.some((e) => e.type === 'update');
+    })),
+    done('fly.machines.update_requires_image_422', 'machines', 'An update whose config drops the image -> 422; the machine keeps its old config', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const r = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}`, b: { config: { env: { A: 'b' } } } });
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        return r.status === 422 && got.body.config?.image === 'nginx:alpine';
+    })),
+    done('fly.machines.delete_stopped', 'machines', 'DELETE a stopped machine destroys it: destroy event, state destroyed (readable via include_deleted), gone from the live list', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const del = await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}` });
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const b = got.body;
+        return del.status === 200 && b.state === 'destroyed' && b.events.some((e) => e.type === 'destroy');
+    })),
+    done('fly.machines.delete_active_needs_force', 'machines', 'DELETE a STARTED machine -> 400 without force; ?force=true kills and destroys it (⚠ exact 400 message doc-unverified; the force semantics are documented)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const refused = await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}` });
+        const forced = await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}?force=true` });
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        return refused.status === 400 && typeof refused.body.error === 'string'
+            && forced.status === 200 && got.body.state === 'destroyed';
+    })),
+    // ── STOP AND START ARE TWO CAPABILITIES, not one lifecycle ────────────────────────────────
+    // These verbs read as ONE behaviour and were once ONE manifest entry
+    // (`fly.machines.start_stop_lifecycle`). They are not one thing to whatever SCOPES access to
+    // this vendor: a scoping consumer names capability ids out of this manifest (that is what
+    // `fly-spec-census.json` publishes them for), and one id covering both verbs makes "may stop,
+    // may not start" — and its reverse, which is the interesting one, since starting a machine is
+    // how a stopped service comes back — inexpressible. The split therefore belongs HERE, in the
+    // twin that owns the vocabulary, and not in the consumer that speaks it. Same routes, same
+    // twin behaviour, two verifies: each verb's own semantics, each verb's own idempotence.
+    done('fly.machines.stop', 'machines', 'POST machines/{id}/stop -> stopped, with a stop event; idempotent when the machine is already stopped', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const stop = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const stopped = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const stopAgain = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        return stop.status === 200 && stopped.body.state === 'stopped'
+            && stopped.body.events.some((e) => e.type === 'stop')
+            && stopAgain.status === 200;
+    })),
+    done('fly.machines.start', 'machines', 'POST machines/{id}/start on a stopped machine -> started with {previous_state:"stopped"} and a start event; idempotent when already started', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const start = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/start`, at: '2026-01-01T00:00:01.000Z' });
+        const started = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const startAgain = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/start` });
+        return start.status === 200 && start.body.previous_state === 'stopped'
+            && started.body.state === 'started'
+            && started.body.events.some((e) => e.type === 'start')
+            && startAgain.status === 200 && startAgain.body.previous_state === 'started';
+    })),
+    done('fly.machines.restart', 'machines', 'POST restart on a started machine restarts it (restart + start events, still started)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const r = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/restart` });
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const b = got.body;
+        return r.status === 200 && b.state === 'started' && b.events.some((e) => e.type === 'restart');
+    })),
+    done('fly.machines.signal', 'machines', 'POST signal delivers a valid signal to a started machine; an invalid signal -> 400; a stopped machine -> 400', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const ok = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/signal`, b: { signal: 'SIGHUP' } });
+        const bad = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/signal`, b: { signal: 'SIGNOPE' } });
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const stopped = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/signal`, b: { signal: 'SIGHUP' } });
+        return ok.status === 200 && bad.status === 400 && stopped.status === 400;
+    })),
+    done('fly.machines.suspend_resume', 'machines', 'POST suspend -> suspended (suspend event); start resumes -> started with previous_state suspended; suspending a stopped machine -> 400', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const sus = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/suspend` });
+        const suspended = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const resume = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/start`, at: '2026-01-01T00:00:01.000Z' });
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const badSus = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/suspend` });
+        return sus.status === 200 && suspended.body.state === 'suspended'
+            && resume.status === 200 && resume.body.previous_state === 'suspended'
+            && badSus.status === 400;
+    })),
+    done('fly.machines.cordon_uncordon', 'machines', 'cordon/uncordon flip the machine\'s cordoned flag', 'api', 'niche', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/cordon` });
+        const on = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/uncordon` });
+        const off = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        return on.body.cordoned === true && off.body.cordoned === false;
+    })),
+    done('fly.machines.wait', 'machines', 'GET wait?state= answers {ok:true} when the machine is in the desired state; a state it is not in -> 408 with Fly\'s real timeout message; an invalid state -> 400', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const ok = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/wait?state=started` });
+        const timeout = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/wait?state=stopped&timeout=1` });
+        const invalid = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/wait?state=warp-speed` });
+        return ok.status === 200 && ok.body.ok === true
+            && timeout.status === 408 && String(timeout.body.error).includes('timeout reached waiting for machine')
+            && invalid.status === 400;
+    })),
+    done('fly.machines.wait_destroyed', 'machines', 'wait?state=destroyed resolves ok once a machine is destroyed (the reap-rehearsal wait flyctl uses)', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const before = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/wait?state=destroyed` });
+        await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}?force=true` });
+        const after = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/wait?state=destroyed` });
+        return before.status === 408 && after.status === 200 && after.body.ok === true;
+    })),
+    done('fly.machines.events_ledger', 'machines', 'GET events returns the machine\'s ledgered MachineEvent stream (type/status/source/timestamp), newest first, ?limit= trims', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop`, at: '2026-01-01T00:00:05.000Z' });
+        const r = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/events` });
+        const events = r.body;
+        const limited = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/events?limit=1` });
+        return r.status === 200 && events.length === 3
+            && events[0].type === 'stop' && events[events.length - 1].type === 'launch'
+            && events.every((e) => typeof e.timestamp === 'number' && (e.source === 'user' || e.source === 'flyd') && typeof e.status === 'string')
+            && limited.body.length === 1 && limited.body[0].type === 'stop';
+    })),
+    done('fly.machines.metadata', 'machines', 'Machine metadata: GET map, GET single {value}, POST upsert (204), DELETE (204), unknown key -> 404', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h, 'twin-app', { image: 'nginx', metadata: { fly_platform_version: 'v2' } });
+        const map = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/metadata` });
+        const set = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/metadata/role`, b: { value: 'worker' } });
+        const single = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/metadata/role` });
+        const del = await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}/metadata/role` });
+        const gone = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/metadata/role` });
+        return map.body.fly_platform_version === 'v2' && set.status === 204
+            && single.status === 200 && single.body.value === 'worker'
+            && del.status === 204 && gone.status === 404;
+    })),
+    done('fly.machines.recreate_name_after_destroy', 'machines', 'Destroying a machine frees its name for a new create (dirty-state: uniqueness is over LIVE machines only)', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h, 'a1', { image: 'nginx' }, { name: 'reborn' });
+        await h({ m: 'DELETE', p: `/v1/apps/a1/machines/${id}?force=true` });
+        const re = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { name: 'reborn', config: { image: 'nginx' } } });
+        const b = re.body;
+        return re.status === 200 && b.name === 'reborn' && b.id !== id && b.state === 'started';
+    })),
+    todo('fly.machines.ps', 'machines', 'GET machines/{id}/ps lists guest processes (ProcessStat)', 'api', 'niche'),
+    todo('fly.machines.memory_endpoints', 'machines', 'GET/PUT machines/{id}/memory + POST memory/reclaim', 'api', 'niche'),
+    todo('fly.machines.metadata_bulk_put_412', 'machines', 'PUT/PATCH machines/{id}/metadata full-replace with 412 conflict semantics (deploys write fly_process_group/fly_release_id in bulk)', 'api', 'common'),
+    todo('fly.machines.list_summary', 'machines', 'machines list ?summary=true trims config from the rows (what flyctl uses on large apps)', 'api', 'common'),
+    todo('fly.machines.create_skip_flags', 'machines', 'CreateMachineRequest.skip_secrets / skip_service_registration / min_secrets_version', 'api', 'niche'),
+    todo('fly.apps.list_app_role_filter', 'apps', 'GET /v1/apps ?app_role= filter', 'api', 'niche'),
+    todo('fly.machines.auto_destroy', 'machines', 'config.auto_destroy destroys the machine when its process exits cleanly', 'api', 'niche'),
+    todo('fly.machines.stop_timeout_signal_body', 'machines', 'stop body {signal,timeout} honors Go duration strings ("30s") in addition to numbers', 'api', 'niche'),
+    todo('fly.machines.standbys', 'machines', 'config.standbys: a standby machine starts when its watched machine fails', 'api', 'niche'),
+    todo('fly.machines.schedule', 'machines', 'config.schedule (hourly/daily/…) scheduled starts', 'api', 'niche'),
+    // ── LEASES ────────────────────────────────────────────────────────────────────────────────
+    done('fly.leases.acquire_wrapped', 'leases', 'POST lease -> 201 {status:"success", data:{nonce,expires_at,owner,version}} (the fly-go MachineLease WRAP, which the OpenAPI omits)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const r = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        const b = r.body;
+        return r.status === 201 && b.status === 'success' && typeof b.data?.nonce === 'string' && b.data.nonce.length > 0
+            && b.data.expires_at === Math.floor(Date.parse(OCCURRED_AT) / 1000) + 300 && typeof b.data.owner === 'string';
+    })),
+    done('fly.leases.get', 'leases', 'GET lease shows the live lease (wrapped); with none held -> 404', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const none = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/lease` });
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/lease` });
+        return none.status === 404 && got.status === 200 && got.body.data?.expires_at > 0;
+    })),
+    done('fly.leases.mutation_guard', 'leases', 'A live lease BLOCKS state-mutating machine ops without the fly-machine-lease-nonce header (400 naming the holder) and admits them with it', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const lease = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        const nonce = lease.body.data.nonce;
+        const blocked = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const wrong = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop`, h: { 'fly-machine-lease-nonce': 'not-the-nonce' } });
+        const metaBlocked = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/metadata/role`, b: { value: 'x' } });
+        const allowed = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop`, h: { 'fly-machine-lease-nonce': nonce } });
+        const state = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        return blocked.status === 400 && String(blocked.body.error).includes('lease currently held')
+            && wrong.status === 400 && metaBlocked.status === 400
+            && allowed.status === 200 && state.body.state === 'stopped';
+    })),
+    done('fly.leases.release', 'leases', 'DELETE lease with the nonce releases it (mutations flow again); a WRONG nonce -> 400 and the lease survives', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const lease = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        const nonce = lease.body.data.nonce;
+        const wrong = await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}/lease`, h: { 'fly-machine-lease-nonce': 'bogus' } });
+        const stillHeld = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/lease` });
+        const released = await h({ m: 'DELETE', p: `/v1/apps/twin-app/machines/${id}/lease`, h: { 'fly-machine-lease-nonce': nonce } });
+        const freed = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        return wrong.status === 400 && stillHeld.status === 200 && released.status === 200 && freed.status === 200;
+    })),
+    done('fly.leases.refresh_keeps_nonce', 'leases', 'POST lease WITH the current nonce refreshes the ttl and keeps the same nonce (fly-go RefreshLease)', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const first = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 60 } });
+        const nonce = first.body.data.nonce;
+        const refreshed = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 600 }, h: { 'fly-machine-lease-nonce': nonce } });
+        const b = refreshed.body;
+        return refreshed.status === 201 && b.data.nonce === nonce && b.data.expires_at === Math.floor(Date.parse(OCCURRED_AT) / 1000) + 600;
+    })),
+    done('fly.leases.conflict_409', 'leases', 'Acquiring a lease already held by someone else (no/wrong nonce) -> 409 (⚠ status doc-unverified; the conflict fact is the point)', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        const r = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        return r.status === 409 && typeof r.body.error === 'string';
+    })),
+    done('fly.leases.expiry', 'leases', 'An expired lease no longer guards or serves ANYWHERE: the lease read 404s, the machine view (even with include_leases=true) drops it, and mutations flow (clock-driven via occurredAt, deterministic)', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 60 } });
+        const later = '2026-01-01T00:02:00.000Z'; // ttl 60s, read 120s on
+        const expired = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}/lease`, at: later });
+        const view = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}?include_leases=true`, at: later });
+        const mutate = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop`, at: later });
+        return expired.status === 404 && view.body.lease === undefined && mutate.status === 200;
+    })),
+    done('fly.leases.include_leases_param', 'leases', 'Machine.lease is served only behind ?include_leases=true (machines get + list declare the param) and only while the lease is LIVE', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/lease`, b: { ttl: 300 } });
+        const bare = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const asked = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}?include_leases=true` });
+        const list = await h({ m: 'GET', p: '/v1/apps/twin-app/machines?include_leases=true' });
+        const lb = asked.body.lease;
+        return bare.body.lease === undefined
+            && lb !== undefined && typeof lb.owner === 'string' && typeof lb.expires_at === 'number'
+            && list.body[0].lease !== undefined;
+    })),
+    done('fly.leases.nonce_on_create', 'leases', 'CreateMachineRequest.lease_ttl mints a lease at create: the Machine reply carries `nonce` (spec: "only ever returned on machine creation")', 'api', 'niche', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const r = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'nginx' }, lease_ttl: 120 } });
+        const b = r.body;
+        const blocked = await h({ m: 'POST', p: `/v1/apps/a1/machines/${b.id}/stop` });
+        return typeof b.nonce === 'string' && b.nonce.length > 0 && blocked.status === 400;
+    })),
+    // ── EXECUTION (the real-plane seam: control plane -> container runtime) ───────────────────
+    done('fly.execution.container_launch_on_create', 'execution', 'Machine create drives the execution plane: runtime.run() receives the machine\'s image and guest CPU/memory limits, and the container ref is ledgered (twin_runtime tags the plane)', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1', { image: 'ghcr.io/acme/worker:v3', guest: { memory_mb: 768, cpus: 2 } });
+            const runs = calls.filter((c) => c.op === 'run');
+            const spec = runs[0]?.args[0];
+            const got = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}` });
+            return runs.length === 1 && spec?.image === 'ghcr.io/acme/worker:v3' && spec.machineId === id
+                && spec.memoryMiB === 768 && spec.cpus === 2
+                && got.body.twin_runtime === 'fake';
+        }, { runtime });
+    }),
+    done('fly.execution.env_passthrough', 'execution', 'config.env reaches the container spec verbatim, layered OVER Fly\'s documented runtime env (user value wins a collision)', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            await seedMachine(h, 'a1', { image: 'nginx', env: { DATABASE_URL: 'postgres://x', FLY_PROCESS_GROUP: 'worker' } });
+            const spec = calls.find((c) => c.op === 'run')?.args[0];
+            return spec.env.DATABASE_URL === 'postgres://x' && spec.env.FLY_PROCESS_GROUP === 'worker';
+        }, { runtime });
+    }),
+    done('fly.execution.fly_runtime_env', 'execution', 'The container boots with Fly\'s documented machine runtime environment: FLY_APP_NAME, FLY_MACHINE_ID, FLY_REGION, FLY_PRIVATE_IP, FLY_MACHINE_VERSION, FLY_VM_MEMORY_MB (fly.io/docs/machines/runtime-environment)', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1', { image: 'nginx', guest: { memory_mb: 512 } });
+            const got = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}` });
+            const b = got.body;
+            const spec = calls.find((c) => c.op === 'run')?.args[0];
+            return spec.env.FLY_APP_NAME === 'a1' && spec.env.FLY_MACHINE_ID === id
+                && spec.env.FLY_REGION === b.region && spec.env.FLY_PRIVATE_IP === b.private_ip
+                && spec.env.FLY_MACHINE_VERSION === b.instance_id && spec.env.FLY_VM_MEMORY_MB === '512';
+        }, { runtime });
+    }),
+    done('fly.execution.ports_published', 'execution', 'Every service internal_port lands in the container spec and the runtime\'s published loopback ports are ledgered as twin_local_ports (disclosed additive field)', 'api', 'core', () => {
+        const { runtime } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1', {
+                image: 'nginx',
+                services: [
+                    { internal_port: 8080, protocol: 'tcp', ports: [{ port: 443, handlers: ['tls', 'http'] }] },
+                    { internal_port: 9000, protocol: 'tcp', ports: [{ port: 9000 }] },
+                ],
+            });
+            const got = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}` });
+            const ports = got.body.twin_local_ports;
+            return ports.length === 2 && ports[0].internal === 8080 && ports[0].host === 41000 && ports[1].internal === 9000;
+        }, { runtime });
+    }),
+    done('fly.execution.mounts_to_volumes', 'execution', 'config.mounts resolve to the app\'s volumes: the container spec mounts the volume id at the path, and the volume shows attached_machine_id', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+            const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+            const volId = vol.body.id;
+            const mr = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg:16', mounts: [{ volume: volId, path: '/data' }] } } });
+            const spec = calls.find((c) => c.op === 'run')?.args[0];
+            const volAfter = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}` });
+            return spec.mounts.length === 1 && spec.mounts[0].volumeId === volId && spec.mounts[0].path === '/data'
+                && volAfter.body.attached_machine_id === mr.body.id;
+        }, { runtime });
+    }),
+    done('fly.execution.stop_reaches_runtime', 'execution', 'POST stop drives runtime.stop() with the StopRequest\'s signal/timeout; destroy (force) drives runtime.remove()', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1');
+            await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/stop`, b: { signal: 'SIGINT', timeout: 15 } });
+            const stop = calls.find((c) => c.op === 'stop');
+            await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/start`, at: '2026-01-01T00:00:01.000Z' });
+            await h({ m: 'DELETE', p: `/v1/apps/a1/machines/${id}?force=true` });
+            const removed = calls.some((c) => c.op === 'remove');
+            return stop !== undefined && stop.args[1].signal === 'SIGINT' && stop.args[1].timeoutSeconds === 15 && removed;
+        }, { runtime });
+    }),
+    done('fly.execution.rootfs_reset_on_start', 'execution', 'stop\u2192start RESETS the machine\'s root filesystem like the vendor ("Stopped Machines that are restarted are completely reset to their original state"): the plane is asked to RECREATE the container from the machine\'s spec \u2014 runtime.start() receives the full container spec (image, env, ports, mounts), never a bare resume \u2014 and the new handle\'s published ports are re-ledgered, while config.mounts stay mounted so volume data survives', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+            const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+            const volId = vol.body.id;
+            const cr = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: {
+                        image: 'app:v1',
+                        mounts: [{ volume: volId, path: '/data' }],
+                        services: [{ internal_port: 8080, protocol: 'tcp', ports: [{ port: 80 }] }],
+                    } } });
+            const id = cr.body.id;
+            await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/stop` });
+            const started = await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/start`, at: '2026-01-01T00:00:01.000Z' });
+            const after = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}`, at: '2026-01-01T00:00:02.000Z' });
+            const start = calls.find((c) => c.op === 'start');
+            const spec = start?.args[1];
+            const ports = after.body.twin_local_ports;
+            return started.status === 200 && after.body.state === 'started'
+                // The plane was handed the whole spec — the image is what a reset restarts FROM.
+                && spec?.image === 'app:v1' && spec.machineId === id
+                // …with the mount wiring intact, so volume-backed data is what survives the reset.
+                && spec.mounts.length === 1 && spec.mounts[0].volumeId === volId && spec.mounts[0].path === '/data'
+                && spec.ports.length === 1 && spec.ports[0].internal === 8080
+                // The recreated container's NEW published port is what the machine now advertises.
+                && ports.length === 1 && ports[0].host === 42000
+                // The plane owns the recreate: the handler does not double-launch behind its back.
+                && calls.filter((c) => c.op === 'run').length === 1;
+        }, { runtime });
+    }),
+    done('fly.execution.exit_fold', 'execution', 'Under restart policy `no`, a container that EXITED folds the machine to stopped on the next read, with exit code and OOM cause ledgered into the event\'s fly-go-shaped request payload — and no relaunch is attempted', 'api', 'core', () => {
+        let exited = false;
+        const { runtime, calls } = fakeRuntime({ async inspect() { return exited ? { running: false, exitCode: 137, oomKilled: true } : { running: true }; } });
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1', { image: 'nginx:alpine', restart: { policy: 'no' } });
+            const before = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}` });
+            exited = true;
+            const after = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}`, at: '2026-01-01T00:00:09.000Z' });
+            const b = after.body;
+            const exit = b.events.find((e) => e.type === 'exit');
+            return before.body.state === 'started' && b.state === 'stopped'
+                && exit !== undefined && exit.source === 'flyd'
+                && exit.request?.exit_event?.exit_code === 137
+                && exit.request?.exit_event?.oom_killed === true
+                && calls.filter((c) => c.op === 'run').length === 1; // policy no: never relaunched
+        }, { runtime });
+    }),
+    done('fly.execution.restart_failure_diagnostic', 'execution', 'If automatic restart is refused, the machine stops with the sanitized causal failure retained on the machine and its final exit event instead of silently discarding the catch', 'api', 'core', () => {
+        let exited = false;
+        let runs = 0;
+        const { runtime } = fakeRuntime({
+            async inspect() { return exited ? { running: false, exitCode: 137, oomKilled: true } : { running: true }; },
+            async run(spec) {
+                runs += 1;
+                if (runs > 1)
+                    throw new Error(`World "demo": service "machine-provider": machine "${spec.machineId}": resource admission refused`);
+                return { containerRef: `fake:${spec.machineId}` };
+            },
+        });
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'diag');
+            exited = true;
+            const got = await h({ m: 'GET', p: `/v1/apps/diag/machines/${id}`, at: '2026-01-01T00:00:09.000Z' });
+            const body = got.body;
+            const finalExit = body.events.find((event) => event.type === 'exit' && event.status === 'stopped');
+            return body.state === 'stopped'
+                && String(body.twin_last_failure).includes('resource admission refused')
+                && String(finalExit?.request?.restart_error).includes('resource admission refused');
+        }, { runtime });
+    }),
+    done('fly.machines.restart_policy', 'machines', 'config.restart drives what an EXIT does (fly.MachineRestart): the DEFAULT (no policy set) is on-failure — a non-zero exit relaunches the container (bounded by max_retries), a CLEAN exit stops; policy `always` relaunches even a clean exit', 'api', 'core', () => {
+        // Leg 1: default policy + exit 1 → relaunch (run called twice, still started, flyd start event).
+        const l1 = (() => {
+            let exited = false;
+            const { runtime, calls } = fakeRuntime({ async inspect() { return exited ? { running: false, exitCode: 1 } : { running: true }; } });
+            return withRoot(async (h) => {
+                const id = await seedMachine(h, 'a1');
+                exited = true;
+                const got = await h({ m: 'GET', p: `/v1/apps/a1/machines/${id}`, at: '2026-01-01T00:00:09.000Z' });
+                const b = got.body;
+                // The relaunch must REAP the exited container first (deterministic docker names — a
+                // run-into-conflict would make on-failure inert on the real plane) and must ledger the
+                // exit CODE into the restarting event's fly-go request payload.
+                return b.state === 'started' && calls.filter((c) => c.op === 'run').length === 2
+                    && calls.some((c) => c.op === 'remove')
+                    && b.events.some((e) => e.type === 'exit' && e.status === 'restarting' && e.request?.exit_event?.exit_code === 1);
+            }, { runtime });
+        })();
+        // Leg 2: default policy + CLEAN exit → stopped, no relaunch.
+        const l2 = (() => {
+            let exited = false;
+            const { runtime, calls } = fakeRuntime({ async inspect() { return exited ? { running: false, exitCode: 0 } : { running: true }; } });
+            return withRoot(async (h) => {
+                const id = await seedMachine(h, 'a2');
+                exited = true;
+                const got = await h({ m: 'GET', p: `/v1/apps/a2/machines/${id}`, at: '2026-01-01T00:00:09.000Z' });
+                return got.body.state === 'stopped' && calls.filter((c) => c.op === 'run').length === 1;
+            }, { runtime });
+        })();
+        // Leg 3: on-failure with max_retries 1 — the SECOND exit is not retried (dirty-state bound),
+        // and an explicit operator RESTART restores the supervision budget (the reset is load-bearing:
+        // without it a once-exhausted machine gets zero flyd supervision forever).
+        const l3 = (() => {
+            const { runtime, calls } = fakeRuntime({ async inspect() { return { running: false, exitCode: 1 }; } });
+            return withRoot(async (h) => {
+                const id = await seedMachine(h, 'a3', { image: 'nginx:alpine', restart: { policy: 'on-failure', max_retries: 1 } });
+                const first = await h({ m: 'GET', p: `/v1/apps/a3/machines/${id}`, at: '2026-01-01T00:00:05.000Z' });
+                const second = await h({ m: 'GET', p: `/v1/apps/a3/machines/${id}`, at: '2026-01-01T00:00:09.000Z' });
+                const runsBeforeRestart = calls.filter((c) => c.op === 'run').length;
+                await h({ m: 'POST', p: `/v1/apps/a3/machines/${id}/restart`, at: '2026-01-01T00:00:12.000Z' });
+                const afterRestart = await h({ m: 'GET', p: `/v1/apps/a3/machines/${id}`, at: '2026-01-01T00:00:15.000Z' });
+                return first.body.state === 'started' && second.body.state === 'stopped'
+                    && runsBeforeRestart === 2 // create + exactly ONE retry
+                    && afterRestart.body.state === 'started' // budget restored: flyd retried again
+                    && calls.filter((c) => c.op === 'run').length === 4; // + restart's run + the restored retry
+            }, { runtime });
+        })();
+        // Leg 4: policy always + clean exit → relaunched.
+        const l4 = (() => {
+            let exited = false;
+            const { runtime, calls } = fakeRuntime({ async inspect() { return exited ? { running: false, exitCode: 0 } : { running: true }; } });
+            return withRoot(async (h) => {
+                const id = await seedMachine(h, 'a4', { image: 'nginx:alpine', restart: { policy: 'always' } });
+                exited = true;
+                const got = await h({ m: 'GET', p: `/v1/apps/a4/machines/${id}`, at: '2026-01-01T00:00:09.000Z' });
+                return got.body.state === 'started' && calls.filter((c) => c.op === 'run').length === 2;
+            }, { runtime });
+        })();
+        return Promise.all([l1, l2, l3, l4]).then((legs) => legs.every(Boolean));
+    }),
+    done('fly.execution.launch_failure_faithful', 'execution', 'A launch the execution plane REFUSES (bad image) -> 422 "failed to launch VM: …" and the machine lands in state failed — never a fake started — with its mounts ATTACHED (consistent with the persisted config, so no second machine can claim them through the failure window)', 'api', 'core', () => {
+        const { runtime } = fakeRuntime({ async run() { throw new Error('pull access denied for no/such-image'); } });
+        return withRoot(async (h) => {
+            await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+            const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+            const volId = vol.body.id;
+            const r = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'no/such-image', mounts: [{ volume: volId, path: '/d' }] } } });
+            const list = await h({ m: 'GET', p: '/v1/apps/a1/machines?state=failed' });
+            const failedId = (list.body[0] ?? {}).id;
+            // Attach happened BEFORE the launch, so the failed machine still holds its volume and a
+            // second machine cannot steal it while the config claims it (§9 round two, finding 2).
+            const volAfter = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}` });
+            const thief = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'no/such-image', mounts: [{ volume: volId, path: '/d' }] } } });
+            return r.status === 422 && String(r.body.error).includes('failed to launch VM')
+                && String(r.body.error).includes('pull access denied')
+                && list.body.length === 1
+                && volAfter.body.attached_machine_id === failedId
+                && thief.status === 422;
+        }, { runtime });
+    }),
+    done('fly.execution.exec_roundtrip', 'execution', 'POST exec on a started machine runs the command through the execution plane and answers the flydv1.ExecResponse shape {exit_code, stdout, stderr}', 'api', 'core', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1');
+            const r = await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/exec`, b: { command: ['uname', '-a'] } });
+            const b = r.body;
+            const execCall = calls.find((c) => c.op === 'exec');
+            return r.status === 200 && b.exit_code === 0 && b.stdout === 'ran:uname -a' && b.stderr === ''
+                && Array.isArray(execCall?.args[0]) && execCall.args[0].join(' ') === 'uname -a';
+        }, { runtime });
+    }),
+    done('fly.execution.exec_virtual_refuses', 'execution', 'exec against the pure-ledger virtual plane refuses loudly (vendor-enveloped 400 naming the virtual runtime) — never a fabricated {exit_code:0}', 'api', 'common', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const r = await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/exec`, b: { command: ['ls'] } });
+        return r.status === 400 && String(r.body.error).includes('virtual');
+    })),
+    done('fly.execution.update_relaunches', 'execution', 'Updating a STARTED machine reaps the old container (runtime.remove) and launches the new config (runtime.run with the new image)', 'api', 'common', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1', { image: 'app:v1' });
+            await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}`, b: { config: { image: 'app:v2' } } });
+            const runs = calls.filter((c) => c.op === 'run').map((c) => c.args[0].image);
+            return runs.join(',') === 'app:v1,app:v2' && calls.some((c) => c.op === 'remove');
+        }, { runtime });
+    }),
+    done('fly.execution.suspend_pauses', 'execution', 'suspend drives runtime.pause() and resume drives runtime.unpause() when the plane supports them', 'api', 'niche', () => {
+        const { runtime, calls } = fakeRuntime();
+        return withRoot(async (h) => {
+            const id = await seedMachine(h, 'a1');
+            await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/suspend` });
+            await h({ m: 'POST', p: `/v1/apps/a1/machines/${id}/start`, at: '2026-01-01T00:00:01.000Z' });
+            return calls.some((c) => c.op === 'pause') && calls.some((c) => c.op === 'unpause');
+        }, { runtime });
+    }),
+    done('fly.execution.virtual_default_offline', 'execution', 'With NO runtime injected the pure-ledger virtual plane serves the whole lifecycle offline (container ref virtual:<id>, no Docker anywhere)', 'api', 'core', () => withRoot(async (h) => {
+        const id = await seedMachine(h);
+        const got = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        const b = got.body;
+        await h({ m: 'POST', p: `/v1/apps/twin-app/machines/${id}/stop` });
+        const stopped = await h({ m: 'GET', p: `/v1/apps/twin-app/machines/${id}` });
+        return b.state === 'started' && b.twin_runtime === 'virtual' && stopped.body.state === 'stopped';
+    })),
+    // ── VOLUMES ───────────────────────────────────────────────────────────────────────────────
+    done('fly.volumes.create', 'volumes', 'POST volumes creates a volume: vol_-prefixed id, size_gb/region/fstype/zone echoed, state created', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const r = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'pg_data', size_gb: 10, region: 'lhr' } });
+        const b = r.body;
+        return r.status === 200 && /^vol_[0-9a-hj-km-np-tv-z]{20}$/.test(b.id) && b.name === 'pg_data'
+            && b.size_gb === 10 && b.region === 'lhr' && b.state === 'created' && b.fstype === 'ext4'
+            && b.attached_machine_id === null;
+    })),
+    done('fly.volumes.create_requires_name_422', 'volumes', 'A volume create without a name -> 422; an invalid name (dashes) -> 422', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const missing = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { size_gb: 1 } });
+        const invalid = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'bad-name', size_gb: 1 } });
+        return missing.status === 422 && invalid.status === 422;
+    })),
+    done('fly.volumes.get_and_list', 'volumes', 'GET volumes/{id} returns the Volume; the list is a BARE array (fly-go decodes []Volume); unknown id -> 404', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const created = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 3 } });
+        const id = created.body.id;
+        const got = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${id}` });
+        const list = await h({ m: 'GET', p: '/v1/apps/a1/volumes' });
+        const missing = await h({ m: 'GET', p: '/v1/apps/a1/volumes/vol_00000000000000000000' });
+        return got.status === 200 && got.body.id === id && got.body.bytes_total === 3 * 1024 * 1024 * 1024
+            && Array.isArray(list.body) && list.body.some((v) => v.id === id)
+            && missing.status === 404;
+    })),
+    done('fly.volumes.update', 'volumes', 'PUT volumes/{id} updates snapshot_retention/auto_backup_enabled and returns the Volume', 'api', 'niche', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const created = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+        const id = created.body.id;
+        const r = await h({ m: 'PUT', p: `/v1/apps/a1/volumes/${id}`, b: { snapshot_retention: 14, auto_backup_enabled: false } });
+        const b = r.body;
+        return r.status === 200 && b.snapshot_retention === 14 && b.auto_backup_enabled === false;
+    })),
+    done('fly.volumes.delete', 'volumes', 'DELETE volumes/{id} on an unattached volume returns the Volume as pending_destroy and it stays listed (live-verified 2026-09-03) until the platform purges it (⚠ purge window doc-unverified; 60 s of world time modeled), after which it is gone from the list', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const created = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+        const id = created.body.id;
+        const del = await h({ m: 'DELETE', p: `/v1/apps/a1/volumes/${id}` });
+        const list = await h({ m: 'GET', p: '/v1/apps/a1/volumes' });
+        const later = new Date(Date.parse(OCCURRED_AT) + 61_000).toISOString();
+        const purged = await h({ m: 'GET', p: '/v1/apps/a1/volumes', at: later });
+        return del.status === 200 && del.body.state === 'pending_destroy'
+            && list.body.length === 1 && list.body[0].state === 'pending_destroy'
+            && purged.body.length === 0;
+    })),
+    done('fly.volumes.delete_attached_400', 'volumes', 'Deleting a volume that is ATTACHED to a machine -> 400 naming the machine (attach semantics enforced)', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+        const volId = vol.body.id;
+        const m = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg:16', mounts: [{ volume: volId, path: '/data' }] } } });
+        const refused = await h({ m: 'DELETE', p: `/v1/apps/a1/volumes/${volId}` });
+        return refused.status === 400 && String(refused.body.error).includes(String(m.body.id));
+    })),
+    done('fly.volumes.detach_on_machine_destroy', 'volumes', 'Attachments RECONCILE: destroying the machine detaches its volumes, and an UPDATE that drops the mount detaches too (attached_machine_id null again; delete then succeeds) — dirty-state attach/detach round-trip on both paths', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+        const volId = vol.body.id;
+        const m = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg:16', mounts: [{ volume: volId, path: '/data' }] } } });
+        const mid = m.body.id;
+        // UPDATE drops the mount → the volume detaches without destroying the machine.
+        await h({ m: 'POST', p: `/v1/apps/a1/machines/${mid}`, b: { config: { image: 'pg:16' } } });
+        const dropped = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}` });
+        // Re-attach via update, then destroy the machine → detached again, delete succeeds.
+        await h({ m: 'POST', p: `/v1/apps/a1/machines/${mid}`, b: { config: { image: 'pg:16', mounts: [{ volume: volId, path: '/data' }] } } });
+        const reattached = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}` });
+        await h({ m: 'DELETE', p: `/v1/apps/a1/machines/${mid}?force=true` });
+        const after = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}` });
+        const del = await h({ m: 'DELETE', p: `/v1/apps/a1/volumes/${volId}` });
+        return dropped.body.attached_machine_id === null
+            && reattached.body.attached_machine_id === mid
+            && after.body.attached_machine_id === null && del.status === 200;
+    })),
+    done('fly.volumes.mount_unknown_404', 'volumes', 'The mount rulebook holds on CREATE **and UPDATE**: an unknown volume -> 404, a volume attached to another machine -> 422 — on both paths (a machine keeps its own attachment across updates)', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const unknown = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg', mounts: [{ volume: 'vol_nope00000000000000', path: '/d' }] } } });
+        const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 1 } });
+        const volId = vol.body.id;
+        const owner = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg', mounts: [{ volume: volId, path: '/d' }] } } });
+        const taken = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg', mounts: [{ volume: volId, path: '/d' }] } } });
+        // UPDATE legs: a second machine cannot STEAL the attached volume via update, nor mount an
+        // unknown one; the owner CAN keep its own attachment through an update.
+        const thief = await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg' } } });
+        const steal = await h({ m: 'POST', p: `/v1/apps/a1/machines/${thief.body.id}`, b: { config: { image: 'pg', mounts: [{ volume: volId, path: '/d' }] } } });
+        const ghost = await h({ m: 'POST', p: `/v1/apps/a1/machines/${thief.body.id}`, b: { config: { image: 'pg', mounts: [{ volume: 'vol_nope00000000000000', path: '/d' }] } } });
+        const keepOwn = await h({ m: 'POST', p: `/v1/apps/a1/machines/${owner.body.id}`, b: { config: { image: 'pg:16', mounts: [{ volume: volId, path: '/d' }] } } });
+        return unknown.status === 404 && taken.status === 422
+            && steal.status === 422 && ghost.status === 404 && keepOwn.status === 200;
+    })),
+    done('fly.volumes.extend', 'volumes', 'PUT extend grows size_gb -> {needs_restart, volume}; needs_restart true iff attached (BOTH branches asserted); shrinking -> 400', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 2 } });
+        const volId = vol.body.id;
+        const grown = await h({ m: 'PUT', p: `/v1/apps/a1/volumes/${volId}/extend`, b: { size_gb: 5 } });
+        const shrink = await h({ m: 'PUT', p: `/v1/apps/a1/volumes/${volId}/extend`, b: { size_gb: 1 } });
+        await h({ m: 'POST', p: '/v1/apps/a1/machines', b: { config: { image: 'pg:16', mounts: [{ volume: volId, path: '/d' }] } } });
+        const attachedGrow = await h({ m: 'PUT', p: `/v1/apps/a1/volumes/${volId}/extend`, b: { size_gb: 8 } });
+        const gb = grown.body;
+        const ab = attachedGrow.body;
+        return grown.status === 200 && gb.volume.size_gb === 5 && gb.needs_restart === false
+            && shrink.status === 400
+            && attachedGrow.status === 200 && ab.needs_restart === true && ab.volume.size_gb === 8;
+    })),
+    done('fly.volumes.snapshots', 'volumes', 'GET snapshots lists (bare array); POST snapshots appends a vs_-prefixed snapshot with the volume\'s size recorded', 'api', 'niche', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const vol = await h({ m: 'POST', p: '/v1/apps/a1/volumes', b: { name: 'data', size_gb: 2 } });
+        const volId = vol.body.id;
+        const empty = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}/snapshots` });
+        await h({ m: 'POST', p: `/v1/apps/a1/volumes/${volId}/snapshots` });
+        const one = await h({ m: 'GET', p: `/v1/apps/a1/volumes/${volId}/snapshots` });
+        const snap = one.body[0];
+        return Array.isArray(empty.body) && empty.body.length === 0
+            && one.body.length === 1 && String(snap.id).startsWith('vs_') && snap.volume_size === 2 * 1024 * 1024 * 1024;
+    })),
+    todo('fly.volumes.fork_from_source', 'volumes', 'CreateVolumeRequest.source_volume_id forks an existing volume', 'api', 'niche'),
+    todo('fly.volumes.restore_from_snapshot', 'volumes', 'CreateVolumeRequest.snapshot_id restores a volume from a snapshot', 'api', 'niche'),
+    todo('fly.volumes.list_summary', 'volumes', 'volumes list ?summary=true', 'api', 'niche'),
+    todo('fly.volumes.docker_volume_materialization', 'volumes', 'The docker execution plane materializes volumes as named docker volumes at machine-run time (proven only in the self-skipping real-Docker integration test today)', 'api', 'common'),
+    // ── SECRETS (app secrets API) ─────────────────────────────────────────────────────────────
+    done('fly.secrets.set_and_list', 'secrets', 'POST secrets/{name} {value} -> 201 with digest and NO value; the list wraps {secrets:[…]} hiding values; show_secrets=true reveals them', 'api', 'core', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const set = await h({ m: 'POST', p: '/v1/apps/a1/secrets/DATABASE_URL', b: { value: 'postgres://secret' } });
+        const list = await h({ m: 'GET', p: '/v1/apps/a1/secrets' });
+        const shown = await h({ m: 'GET', p: '/v1/apps/a1/secrets/DATABASE_URL?show_secrets=true' });
+        const sb = set.body;
+        const row = list.body.secrets[0];
+        return set.status === 201 && sb.name === 'DATABASE_URL' && typeof sb.digest === 'string' && sb.value === undefined
+            && row.name === 'DATABASE_URL' && row.value === undefined
+            && shown.body.value === 'postgres://secret';
+    })),
+    done('fly.secrets.bulk_update', 'secrets', 'POST secrets {values:{…}} bulk-upserts -> {secrets, version}, and the app-wide version MOVES FORWARD on every update operation', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const r = await h({ m: 'POST', p: '/v1/apps/a1/secrets', b: { values: { A: '1', B: '2' } } });
+        const r2 = await h({ m: 'POST', p: '/v1/apps/a1/secrets', b: { values: { A: '3' } } });
+        const b = r.body;
+        return r.status === 200 && b.secrets.length === 2 && typeof b.version === 'number'
+            && r2.body.version > b.version;
+    })),
+    done('fly.secrets.delete_and_404', 'secrets', 'DELETE secrets/{name} -> {version}; the secret 404s afterwards; deleting/reading an unknown name -> 404', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        await h({ m: 'POST', p: '/v1/apps/a1/secrets/DOOMED', b: { value: 'x' } });
+        const del = await h({ m: 'DELETE', p: '/v1/apps/a1/secrets/DOOMED' });
+        const gone = await h({ m: 'GET', p: '/v1/apps/a1/secrets/DOOMED' });
+        const never = await h({ m: 'DELETE', p: '/v1/apps/a1/secrets/NEVER_WAS' });
+        return del.status === 200 && typeof del.body.version === 'number' && gone.status === 404 && never.status === 404;
+    })),
+    done('fly.secrets.version_bumps', 'secrets', 'The app secrets version is a MONOTONIC app-wide counter: every set/delete bumps it and it NEVER goes backwards, even across a delete + re-add (dirty-state: no tombstone swallow, no version regression)', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/apps', b: { app_name: 'a1', org_slug: 'personal' } });
+        const v1 = await h({ m: 'POST', p: '/v1/apps/a1/secrets/KEY', b: { value: 'one' } });
+        const v2 = await h({ m: 'POST', p: '/v1/apps/a1/secrets/KEY', b: { value: 'two' } });
+        const v3 = await h({ m: 'DELETE', p: '/v1/apps/a1/secrets/KEY' });
+        const re = await h({ m: 'POST', p: '/v1/apps/a1/secrets/KEY', b: { value: 'three' } });
+        const shown = await h({ m: 'GET', p: '/v1/apps/a1/secrets/KEY?show_secrets=true' });
+        return v1.body.version === 1 && v2.body.version === 2
+            && v3.body.version === 3
+            && re.status === 201 && re.body.version === 4
+            && shown.body.value === 'three';
+    })),
+    todo('fly.secrets.min_version_filter', 'secrets', 'secrets list/get ?min_version= filtering', 'api', 'niche'),
+    todo('fly.secrets.generate', 'secrets', 'POST secretkeys/{name}/generate mints a random secret value server-side', 'api', 'niche'),
+    // ── SECRETKEYS (typed keys: encrypt/decrypt/sign/verify) ──────────────────────────────────
+    todo('fly.secretkeys.list', 'secretkeys', 'GET secretkeys lists typed secret keys', 'api', 'niche'),
+    todo('fly.secretkeys.set', 'secretkeys', 'POST secretkeys/{name} creates a typed key', 'api', 'niche'),
+    todo('fly.secretkeys.sign_verify', 'secretkeys', 'POST secretkeys/{name}/sign + /verify round-trip', 'api', 'niche'),
+    todo('fly.secretkeys.encrypt_decrypt', 'secretkeys', 'POST secretkeys/{name}/encrypt + /decrypt round-trip', 'api', 'niche'),
+    // ── TLS CERTIFICATES (metadata CRUD) ─────────────────────────────────────────────────────
+    todo('fly.certificates.list', 'certificates', 'GET certificates lists an app\'s certificates', 'api', 'niche'),
+    todo('fly.certificates.add_acme', 'certificates', 'POST certificates/acme registers a hostname for managed issuance', 'api', 'niche'),
+    todo('fly.certificates.get', 'certificates', 'GET certificates/{hostname} shows cert status + DNS requirements', 'api', 'niche'),
+    todo('fly.certificates.check', 'certificates', 'POST certificates/{hostname}/check re-validates DNS', 'api', 'niche'),
+    todo('fly.certificates.delete', 'certificates', 'DELETE certificates/{hostname}', 'api', 'niche'),
+    todo('fly.certificates.custom', 'certificates', 'POST certificates/custom + the per-hostname custom/acme DELETE variants', 'api', 'niche'),
+    // ── IP ASSIGNMENTS ────────────────────────────────────────────────────────────────────────
+    todo('fly.ip_assignments.list', 'ip_assignments', 'GET ip_assignments lists the app\'s allocated IPs', 'api', 'niche'),
+    todo('fly.ip_assignments.create', 'ip_assignments', 'POST ip_assignments allocates a (shared/dedicated) IP', 'api', 'niche'),
+    todo('fly.ip_assignments.delete', 'ip_assignments', 'DELETE ip_assignments/{ip} releases an IP', 'api', 'niche'),
+    // ── TOKENS ────────────────────────────────────────────────────────────────────────────────
+    todo('fly.tokens.current', 'tokens', 'GET tokens/current introspects the presented token', 'api', 'niche'),
+    todo('fly.tokens.authenticate', 'tokens', 'POST tokens/authenticate validates a token', 'api', 'niche'),
+    todo('fly.tokens.authorize', 'tokens', 'POST tokens/authorize checks a token against a resource action', 'api', 'niche'),
+    todo('fly.tokens.kms', 'tokens', 'POST tokens/kms mints a KMS-scoped token', 'api', 'niche'),
+    // ── ORGANIZATIONS ─────────────────────────────────────────────────────────────────────────
+    todo('fly.orgs.machines_list', 'orgs', 'GET orgs/{slug}/machines lists machines across the org (cursor-paginated)', 'api', 'common'),
+    todo('fly.orgs.volumes_list', 'orgs', 'GET orgs/{slug}/volumes lists volumes across the org (cursor-paginated)', 'api', 'niche'),
+    // ── PLATFORM ──────────────────────────────────────────────────────────────────────────────
+    todo('fly.platform.regions', 'platform', 'GET platform/regions lists Fly regions with capability flags', 'api', 'niche'),
+    todo('fly.platform.placements', 'platform', 'POST platform/placements previews regional capacity for a guest spec', 'api', 'niche'),
+    // ── MANAGED POSTGRES ──────────────────────────────────────────────────────────────────────
+    todo('fly.postgres.clusters_crud', 'postgres', 'POST/GET/DELETE /v1/postgres clusters (Managed Postgres)', 'api', 'niche'),
+    todo('fly.postgres.databases', 'postgres', 'Cluster databases list/create/delete', 'api', 'niche'),
+    todo('fly.postgres.users', 'postgres', 'Cluster users CRUD + credentials + rotate_password', 'api', 'niche'),
+    todo('fly.postgres.backups', 'postgres', 'Cluster backups list/create + restore/fork', 'api', 'niche'),
+    todo('fly.postgres.attachments', 'postgres', 'Attach/detach a cluster to an app (connection-string injection)', 'api', 'niche'),
+    todo('fly.postgres.extensions', 'postgres', 'Database extensions list/enable/disable', 'api', 'niche'),
+    // ── CONNECTOR (pull over the injected executor; D6/D7/D8) ─────────────────────────────────
+    done('fly.connector.pull_apps_machines_volumes', 'connector', 'syncFlyFromReal pulls the org\'s apps, then each app\'s machines + volumes, and folds them through syncPull — the twin then SERVES the pulled state (fresh-root proof; app rows are keyed by NAME, so a pulled app whose name a LOCAL create already claimed keeps the local row — local writes win the projection; disclosed in pull-audit.json)', 'connector', 'core', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-conn-'));
+        const exec = async (_m, path) => {
+            if (/^\/v1\/apps\/[^/?]+$/.test(path))
+                return { status: 200, body: { id: path.split('/')[3], name: path.split('/')[3], network: 'default', status: 'deployed', internal_numeric_id: 424242, organization: { slug: 'acme', name: 'acme' } } };
+            if (path.startsWith('/v1/apps?'))
+                return { status: 200, body: { total_apps: 1, apps: [{ id: 'real-app', name: 'real-app', network: 'default', status: 'deployed', machine_count: 1 }] } };
+            if (path.endsWith('/machines'))
+                return { status: 200, body: [{ id: 'e28697ce9d3986', name: 'real-web', state: 'started', region: 'sjc', instance_id: '01JGXREALINSTANCE0000000AB', private_ip: 'fdaa:0:1:a7b::2', config: { image: 'real/app:v9' }, created_at: '2026-01-01T00:00:00Z', events: [] }] };
+            if (path.endsWith('/volumes'))
+                return { status: 200, body: [{ id: 'vol_realrealrealrealreal', name: 'real_data', state: 'created', region: 'sjc', size_gb: 7 }] };
+            return { status: 404, body: { error: 'not found' } };
+        };
+        return verifyBoundary('fly.connector.pull', async () => {
+            try {
+                const res = await syncFlyFromReal(exec, { root, occurredAt: OCCURRED_AT, orgSlug: 'acme' });
+                const machine = await handleFlyTwinRequest({ method: 'GET', path: '/v1/apps/real-app/machines/e28697ce9d3986', root, occurredAt: OCCURRED_AT, headers: { authorization: 'Bearer t' } });
+                const vol = await handleFlyTwinRequest({ method: 'GET', path: '/v1/apps/real-app/volumes/vol_realrealrealrealreal', root, occurredAt: OCCURRED_AT, headers: { authorization: 'Bearer t' } });
+                const mb = machine.body;
+                return res.observed === 3 && res.deltasAppended > 0
+                    && machine.status === 200 && mb.name === 'real-web' && mb.state === 'started'
+                    && mb.config?.image === 'real/app:v9' && mb.twin_runtime === 'real-fly'
+                    && vol.status === 200 && vol.body.size_gb === 7;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.pull_idempotent', 'connector', 'A re-pull of IDENTICAL real state appends ZERO deltas (syncPull shadow-diff, D6)', 'connector', 'core', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-conn-'));
+        const exec = async (_m, path) => {
+            if (/^\/v1\/apps\/[^/?]+$/.test(path))
+                return { status: 200, body: { id: path.split('/')[3], name: path.split('/')[3], network: 'default', status: 'deployed', internal_numeric_id: 424242, organization: { slug: 'acme', name: 'acme' } } };
+            if (path.startsWith('/v1/apps?'))
+                return { status: 200, body: { total_apps: 1, apps: [{ id: 'same-app', name: 'same-app' }] } };
+            if (path.endsWith('/machines'))
+                return { status: 200, body: [{ id: 'aaaaaaaaaaaaaa', name: 'w', state: 'stopped', region: 'iad', config: { image: 'x:1' }, events: [] }] };
+            if (path.endsWith('/volumes'))
+                return { status: 200, body: [] };
+            return { status: 404, body: { error: 'not found' } };
+        };
+        return verifyBoundary('fly.connector.idempotent', async () => {
+            try {
+                const first = await syncFlyFromReal(exec, { root, occurredAt: OCCURRED_AT });
+                const again = await syncFlyFromReal(exec, { root, occurredAt: '2026-01-01T00:10:00.000Z' });
+                return first.deltasAppended > 0 && again.deltasAppended === 0 && again.observed === 2;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.pull_refuses_failure', 'connector', 'A refused pull (401/500 from the vendor) THROWS instead of folding an empty account over real observed state (ADDING_A_TWIN §6)', 'connector', 'core', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-conn-'));
+        return verifyBoundary('fly.connector.refusal', async () => {
+            try {
+                const seeded = async (_m, path) => {
+                    if (/^\/v1\/apps\/[^/?]+$/.test(path))
+                        return { status: 200, body: { id: path.split('/')[3], name: path.split('/')[3], network: 'default', status: 'deployed', internal_numeric_id: 424242, organization: { slug: 'acme', name: 'acme' } } };
+                    if (path.startsWith('/v1/apps?'))
+                        return { status: 200, body: { total_apps: 1, apps: [{ id: 'keep-app', name: 'keep-app' }] } };
+                    if (path.endsWith('/machines'))
+                        return { status: 200, body: [{ id: 'bbbbbbbbbbbbbb', name: 'keep', state: 'started', region: 'iad', config: { image: 'x:1' }, events: [] }] };
+                    if (path.endsWith('/volumes'))
+                        return { status: 200, body: [] };
+                    return { status: 404, body: { error: 'not found' } };
+                };
+                await syncFlyFromReal(seeded, { root, occurredAt: OCCURRED_AT });
+                const refusing = async () => ({ status: 401, body: { error: 'unauthorized' } });
+                let threw = false;
+                try {
+                    await syncFlyFromReal(refusing, { root, occurredAt: '2026-01-01T01:00:00.000Z' });
+                }
+                catch (e) {
+                    threw = e instanceof Error && e.message.includes('refused');
+                }
+                const still = await handleFlyTwinRequest({ method: 'GET', path: '/v1/apps/keep-app/machines/bbbbbbbbbbbbbb', root, occurredAt: OCCURRED_AT, headers: { authorization: 'Bearer t' } });
+                return threw && still.status === 200 && still.body.name === 'keep';
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.budget_ceiling_fail_closed', 'connector', 'liveFlyExecute charges the shared FlyBudget BEFORE each request: past the ceiling it THROWS FlyBudgetError and the counting fake fetch proves the refused call NEVER went out (D8)', 'connector', 'core', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-budget-'));
+        return verifyBoundary('fly.connector.budget', async () => {
+            try {
+                let calls = 0;
+                const fakeFetch = (async () => {
+                    calls++;
+                    return new Response(JSON.stringify([]), { status: 200, headers: { 'content-type': 'application/json' } });
+                });
+                const budget = new FlyBudget({ path: join(root, 'ledger.json'), now: () => Date.parse(OCCURRED_AT) });
+                const exec = liveFlyExecute('fm2_faketoken', 'https://api.machines.test', { fetchImpl: fakeFetch, budget });
+                const allowed = Math.floor(FLY_BUDGET_CEILING / FLY_CALL_WEIGHTS.other);
+                for (let i = 0; i < allowed; i++)
+                    await exec('GET', '/v1/apps/a/machines');
+                if (calls !== allowed)
+                    return false;
+                let refused = false;
+                try {
+                    await exec('GET', '/v1/apps/a/machines');
+                }
+                catch (e) {
+                    refused = e instanceof FlyBudgetError;
+                }
+                // The count is the proof: the refused call must never have reached the fake vendor.
+                return refused && calls === allowed;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.budget_persists_across_processes', 'connector', 'A FRESH FlyBudget over the SAME ledger file starts with the window already spent — a new process gets no new allowance (D8 persistence)', 'connector', 'core', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-budget-'));
+        return verifyBoundary('fly.connector.budget_persist', async () => {
+            try {
+                let calls = 0;
+                const fakeFetch = (async () => { calls++; return new Response('[]', { status: 200 }); });
+                const path = join(root, 'ledger.json');
+                const now = () => Date.parse(OCCURRED_AT);
+                const exec1 = liveFlyExecute('fm2_tok', 'https://api.machines.test', { fetchImpl: fakeFetch, budget: new FlyBudget({ path, now }) });
+                const allowed = Math.floor(FLY_BUDGET_CEILING / FLY_CALL_WEIGHTS.other);
+                for (let i = 0; i < allowed; i++)
+                    await exec1('GET', '/v1/apps/a/machines');
+                // "New process": a fresh budget instance over the same ledger.
+                const exec2 = liveFlyExecute('fm2_tok', 'https://api.machines.test', { fetchImpl: fakeFetch, budget: new FlyBudget({ path, now }) });
+                let refused = false;
+                try {
+                    await exec2('GET', '/v1/apps/a/machines');
+                }
+                catch (e) {
+                    refused = e instanceof FlyBudgetError;
+                }
+                return refused && calls === allowed;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.budget_cooldown_on_429', 'connector', 'A vendor 429 with Retry-After arms a PERSISTED cooldown: the next call is refused without touching the vendor (count unchanged)', 'connector', 'common', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-budget-'));
+        return verifyBoundary('fly.connector.cooldown', async () => {
+            try {
+                let calls = 0;
+                const fakeFetch = (async () => {
+                    calls++;
+                    return new Response(JSON.stringify({ error: 'rate limited' }), { status: 429, headers: { 'retry-after': '30' } });
+                });
+                const budget = new FlyBudget({ path: join(root, 'ledger.json'), now: () => Date.parse(OCCURRED_AT) });
+                const exec = liveFlyExecute('fm2_tok', 'https://api.machines.test', { fetchImpl: fakeFetch, budget });
+                await exec('GET', '/v1/apps/a/machines'); // the 429 lands and arms the cooldown
+                let refused = false;
+                try {
+                    await exec('GET', '/v1/apps/a/machines');
+                }
+                catch (e) {
+                    refused = e instanceof FlyBudgetError;
+                }
+                return refused && calls === 1;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.create_weighs_heavier', 'connector', 'Machine/app/volume creation POSTs are priced at weight 3 (billable provisioning) while reads cost 2 — the declared rules, exercised through the live executor\'s own pricing', 'connector', 'common', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-budget-'));
+        return verifyBoundary('fly.connector.weights', async () => {
+            try {
+                let calls = 0;
+                const fakeFetch = (async () => { calls++; return new Response('{}', { status: 200 }); });
+                const budget = new FlyBudget({ path: join(root, 'ledger.json'), now: () => Date.parse(OCCURRED_AT) });
+                const exec = liveFlyExecute('fm2_tok', 'https://api.machines.test', { fetchImpl: fakeFetch, budget });
+                const allowedCreates = Math.floor(FLY_BUDGET_CEILING / FLY_CALL_WEIGHTS.create);
+                for (let i = 0; i < allowedCreates; i++)
+                    await exec('POST', '/v1/apps/a/machines', { config: { image: 'x' } });
+                let refused = false;
+                try {
+                    await exec('POST', '/v1/apps/a/machines', { config: { image: 'x' } });
+                }
+                catch (e) {
+                    refused = e instanceof FlyBudgetError;
+                }
+                return refused && calls === allowedCreates && allowedCreates === 20;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    done('fly.connector.push', 'connector', 'performFlyAction carries ONE entry across through the kernel\'s executor — a machine the twin created becomes POST /v1/apps/{app}/machines with its mount\'s volume resolved to the vendor\'s id, and the answer\'s id comes back as the externalId; the twin\'s own entries (a lease, a purge) cross nothing (protocol 2)', 'connector', 'common', () => {
+        const root = mkdtempSync(join(tmpdir(), 'fly-perform-'));
+        return verifyBoundary('fly.connector.perform', async () => {
+            try {
+                const { performFlyAction } = await import("./fly-connector.js");
+                const auth = { authorization: 'Bearer t' };
+                await handleFlyTwinRequest({ method: 'POST', path: '/v1/apps', body: JSON.stringify({ app_name: 'a1', org_slug: 'acme' }), root, occurredAt: OCCURRED_AT, headers: auth });
+                const vol = await handleFlyTwinRequest({ method: 'POST', path: '/v1/apps/a1/volumes', body: JSON.stringify({ name: 'data', region: 'sjc', size_gb: 1 }), root, occurredAt: OCCURRED_AT, headers: auth });
+                const volId = String(vol.body.id ?? '');
+                const made = await handleFlyTwinRequest({ method: 'POST', path: '/v1/apps/a1/machines', body: JSON.stringify({ name: 'web', region: 'sjc', config: { image: 'app:v1', mounts: [{ volume: volId, path: '/data' }] } }), root, occurredAt: OCCURRED_AT, headers: auth });
+                const m = made.body;
+                if (made.status !== 200 || typeof m.id !== 'string')
+                    return false;
+                const wire = [];
+                const execute = async (r) => { wire.push(r); return { status: 200, headers: {}, body: JSON.stringify({ id: 'e2real0000000001' }) }; };
+                const ctx = { resolve: (_t, l) => (l === volId ? 'vol_real' : l), service: 'fly', root };
+                const out = await performFlyAction(execute, { operation: 'machine.create', subject: { type: 'machine', id: m.id }, fields: { app_name: 'a1', name: m.name, region: m.region, config: m.config } }, ctx);
+                const own = await performFlyAction(execute, { operation: 'machine.purge', subject: { type: 'machine', id: m.id }, fields: { app_name: 'a1' } }, ctx);
+                const sent = wire[0] ? JSON.parse(Buffer.from(wire[0].body ?? '{}').toString()) : undefined;
+                return out.externalId === 'e2real0000000001' && wire.length === 1 && wire[0].method === 'POST' && wire[0].path === '/v1/apps/a1/machines'
+                    && sent?.config?.mounts?.[0]?.volume === 'vol_real' && own.externalId === m.id && wire.length === 1;
+            }
+            finally {
+                rmSync(root, { recursive: true, force: true });
+            }
+        });
+    }),
+    todo('fly.connector.org_inventory_pull', 'connector', 'Pull via /v1/orgs/{slug}/machines (cursor-paginated org-wide inventory) instead of per-app walks', 'connector', 'niche'),
+    // ── CONFORMANCE ───────────────────────────────────────────────────────────────────────────
+    done('fly.conformance.endpoint_probes', 'conformance', 'checkFlyConformance drives ONE real request per claimed endpoint (status set + body predicate, census bijection with the snapshot) and reports clean', 'api', 'common', async () => {
+        const report = await checkFlyConformance();
+        return report.ok && report.endpointsProbed >= 40 && report.violations.length === 0 && report.endpointsChecked === report.endpointsProbed;
+    }),
+];
+// Areas census (TWIN-87): enumerated TOP-DOWN from the first-party OpenAPI's tags — Apps,
+// Machines, Volumes, Secrets, TLS Certificates, Tokens, Organizations, Platform, Postgres
+// Clusters — with the Machines tag split into its lifecycle subfamilies (machines / execution /
+// leases), the secrets tag's typed-key endpoints as secretkeys, the Apps-tag ip_assignments
+// family surfaced by path, and the twin-lifecycle areas (auth/errors/connector/conformance)
+// that every pack carries.
+export const FLY_AREAS = [
+    'apps', 'machines', 'execution', 'leases', 'volumes', 'secrets', 'secretkeys',
+    'certificates', 'ip_assignments', 'tokens', 'orgs', 'platform', 'postgres',
+    'auth', 'errors', 'connector', 'conformance',
+];
+export async function flyCapabilities() {
+    return checkCapabilities('fly', FLY_CAPABILITIES);
+}