@volter/twin-fly 0.1.0

package/dist/src/fly-machines.js

@@ -0,0 +1,293 @@
+// fly MACHINE LIFECYCLE + the CONTAINER-RUNTIME SEAM — the novel core of this pack.
+//
+// Fly.io's defining product idea is "a REST call gives you a running VM in seconds". This twin
+// splits that into two planes, per the repo's real-plane doctrine (supabase: twin the control
+// plane, run the real engine):
+//
+//   CONTROL PLANE (this file + fly-twin.ts): apps/machines/volumes/secrets as kernel-backed
+//   rows; the machine lifecycle state machine (created → starting → started → stopping → stopped
+//   → destroying → destroyed, plus suspended) with a ledgered MachineEvent stream — all fully
+//   verifiable OFFLINE and deterministically.
+//
+//   EXECUTION PLANE (the `FlyContainerRuntime` seam): when a machine is created/started the twin
+//   ACTUALLY runs `config.image` as a real local Docker container (fly-docker.ts implements the
+//   seam over the `docker` CLI): config.env → container env (plus Fly's documented FLY_* runtime
+//   environment), services/internal_port → published loopback ports, config.mounts → named
+//   docker volumes, stop → docker stop, start → RECREATE the container from the image (Fly
+//   resets a stopped Machine's rootfs), destroy → docker rm. The seam is INJECTED: verifies and
+//   unit tests inject a fake (or use the VIRTUAL runtime below), so the whole gate stays green on
+//   a machine with no Docker daemon; the real-Docker proof lives in
+//   fly-docker.integration.test.ts, which self-skips LOUDLY when `docker info` fails and is
+//   never counted as a capability proof.
+//
+// STATE-TRANSITION HONESTY (disclosed, README ## Coverage): a local `docker run`/`stop` completes
+// synchronously, so the transient `starting`/`stopping`/`destroying` states are modeled but never
+// observable — each API call lands on its terminal state (started/stopped/destroyed) before it
+// returns, with the transition recorded in the machine's `events` array. The `wait` endpoint is
+// therefore an immediate state check: already-there → 200 {ok:true}, otherwise Fly's own 408
+// timeout — nothing in this twin changes state between two requests except the runtime-exit fold
+// below.
+//
+// RUNTIME-EXIT FOLD: on every machine read the handler asks the runtime (when it can,
+// `inspect()`) whether the container is still running; a container that exited folds the machine
+// to `stopped` with an `exit` event — the genuine execution plane reflecting back into the
+// twinned control plane. Proven offline with a fake runtime whose inspect() reports not-running.
+//
+// GROUNDING: the Machines API surface, request/response schemas, states and event shape are from
+// Fly's first-party OpenAPI (live-fetched from docs.machines.dev/swagger/doc.json, OpenAPI 3.0.1
+// "Machines API 1.0") cross-checked against superfly/fly-go (flyctl's own client — machine_types.go,
+// flaps/flaps_machines.go). Where the two disagree the Go client wins (it is what flyctl actually
+// speaks): e.g. lease responses are WRAPPED `{status:"success", data:{...}}` (fly-go MachineLease),
+// not the OpenAPI's bare Lease schema. See spec-sources.json for the full citation + every
+// ⚠ doc-unverified modeling choice.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { createHash } from 'node:crypto';
+export const SERVICE = 'fly';
+/**
+ * The offline default: a pure-ledger execution plane. Nothing runs, nothing listens; every
+ * lifecycle call succeeds and `inspect` reports the container as still running (so control-plane
+ * state is authoritative). This is what makes the ENTIRE control plane — states, events, wait,
+ * leases — verifiable with no Docker daemon anywhere near the gate.
+ */
+export const VIRTUAL_FLY_RUNTIME = {
+    kind: 'virtual',
+    async run(spec) {
+        return { containerRef: `virtual:${spec.machineId}` };
+    },
+    async stop() { },
+    // Nothing runs, so nothing has a filesystem to reset — the virtual plane models no state that
+    // could survive a stop→start, and hands back the same stable ledger handle.
+    async start(_containerRef, spec) {
+        return { containerRef: `virtual:${spec.machineId}` };
+    },
+    async remove() { },
+    async pause() { },
+    async unpause() { },
+    async signal() { },
+    async inspect() {
+        return { running: true };
+    },
+};
+// ── Fly's documented machine runtime environment (fly.io/docs/machines/runtime-environment):
+// the env vars every real Fly machine boots with. The execution plane injects these UNDER the
+// user's config.env (user env wins on collision, matching a user's ability to override). ────────
+export function flyRuntimeEnv(m) {
+    return {
+        FLY_APP_NAME: m.app_name,
+        FLY_MACHINE_ID: m.id,
+        FLY_ALLOC_ID: m.id,
+        FLY_REGION: m.region,
+        FLY_IMAGE_REF: m.image,
+        FLY_MACHINE_VERSION: m.instance_id,
+        FLY_PRIVATE_IP: m.private_ip,
+        FLY_PROCESS_GROUP: 'app',
+        FLY_VM_MEMORY_MB: String(m.memory_mb),
+        PRIMARY_REGION: m.region,
+    };
+}
+// ── machine states (fly-go machine_types.go MachineState* constants; the transient trio +
+// `suspending`/`replacing`/`failed` appear in Fly's states documentation) ─────────────────────
+export const FLY_MACHINE_STATES = [
+    'created', 'starting', 'started', 'stopping', 'stopped',
+    'suspending', 'suspended', 'destroying', 'destroyed', 'replacing', 'failed',
+];
+// ── kernel-backed rows (kernel-backed projection rows) ─────────────────────────────
+// Kernel META reserves `type`/`id`/`updatedAt` inside `fields` — every field below is snake_case
+// (created_at, instance_id, image_ref, …) so nothing collides; the bare vendor id is re-attached
+// AFTER projection, never written inside `fields`.
+export function nowIso(occurredAt) {
+    return occurredAt ?? new Date().toISOString();
+}
+export function nowEpochMs(occurredAt) {
+    return Date.parse(nowIso(occurredAt));
+}
+/** The live rows of a type (protocol 2: a subject's id is the vendor's — an app's name, a machine's id, a volume's id —
+ *  with no type prefix; a delete is the kernel's tombstone `deleted: true`, cleared by the subject's next write). */
+export function rows(type, root) {
+    return projectResources(SERVICE, root)
+        .filter((r) => r.type === type && r.deleted !== true)
+        .map((r) => ({ ...r }));
+}
+/** Every row of a type the tree has ever held, tombstoned ones included — the ordinal an id seed takes. */
+export function countRows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type).length;
+}
+export function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+function view(r) {
+    // the row as the tree holds it, its own bookkeeping (`_`-prefixed) included — the wire views pick their fields
+    const { type: _t, updatedAt: _u, ...rest } = r;
+    return rest;
+}
+/**
+ * The one kernel write choke point. Every write folds a per-subject `_rev` ordinal into `fields`
+ * (read-modify-write off the current projection): the kernel dedupes actions by content +
+ * millisecond timestamp, so without `rev` a machine returning to a PREVIOUS value under a pinned
+ * clock (start→stop→start in one verify) would silently land as `replayed` — reply and stored
+ * state disagreeing (the upstash lesson, ADDING_A_TWIN §5).
+ */
+export async function write(type, id, fields, op, root, occurredAt) {
+    const current = getRow(type, id, root);
+    const rev = typeof current?._rev === 'number' ? current._rev + 1 : 1;
+    const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: id, fields: { ...fields, _rev: rev }, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
+    return view({ ...resource, id });
+}
+// ── id minting — entropy-based, NEVER a row count (the count-mint collision class three §9
+// reviews found independently; ADDING_A_TWIN §5). Shapes are vendor-faithful:
+//   machine id: 14 lowercase hex chars            (e.g. `d8d1e2ea044148` — flyctl's own shape)
+//   instance id: 26-char Crockford-base32 ULID-ish (`01JGXW…` — "unique for each version")
+//   volume id:  `vol_` + 20 lowercase base32      (fly-go VolumeIDPrefix-compatible)
+//   lease nonce: 24 hex chars
+// ────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * The pack's id byte source — SEEDED, never random (R9).
+ *
+ * Real Fly mints machine ids, instance ids, volume ids and lease nonces from entropy, and this
+ * file used to do the same (`randomUUID()`), which made every one of them differ between two
+ * identical worlds the moment a caller listed machines or volumes. They are now a digest of the
+ * SEED the caller derives from the state the write is about to land on: the world instant plus
+ * the ordinal the new row takes among the rows of its type.
+ *
+ * That ordinal is the reason this does not resurrect the §9 round-one finding it replaced (a
+ * NAME hash, which made a deleted-and-recreated app inherit its predecessor's internal id).
+ * A destroyed machine or volume stays a row (`_purged`, state `destroyed`) and a deleted app is a tombstone the tree
+ * keeps, so `countRows(type)` only ever grows: recreating a destroyed name mints at a higher ordinal, hence a fresh id.
+ */
+function entropyHex(len, seed) {
+    let out = '';
+    for (let round = 0; out.length < len; round += 1)
+        out += createHash('sha256').update(`${round}:${seed}`).digest('hex');
+    return out.slice(0, len);
+}
+const B32 = '0123456789abcdefghjkmnpqrstvwxyz';
+function entropyB32(len, seed) {
+    const hex = entropyHex(len * 2, seed);
+    let out = '';
+    for (let i = 0; i < len; i++)
+        out += B32[parseInt(hex.slice(i * 2, i * 2 + 2), 16) % 32];
+    return out;
+}
+export function newMachineId(seed) {
+    return entropyHex(14, seed);
+}
+export function newInstanceId(occurredAt, seed) {
+    // ULID-like: time prefix (10 chars) + seeded tail (16 chars), uppercase Crockford base32.
+    const t = nowEpochMs(occurredAt);
+    const A = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+    let time = '';
+    let ms = t;
+    for (let i = 0; i < 10; i++) {
+        time = A[ms % 32] + time;
+        ms = Math.floor(ms / 32);
+    }
+    return time + entropyB32(16, seed).toUpperCase();
+}
+export function newVolumeId(seed) {
+    return `vol_${entropyB32(20, seed)}`;
+}
+export function newLeaseNonce(seed) {
+    return entropyHex(24, seed);
+}
+/** An app's internal numeric id — the same seeded source, read as a 24-bit integer. */
+export function newAppNumericId(seed) {
+    return parseInt(entropyHex(6, seed), 16);
+}
+/** Fly machine names default to adjective-noun-number; the twin's default is the same shape. */
+const NAME_ADJ = ['ancient', 'bold', 'calm', 'divine', 'empty', 'frosty', 'green', 'hidden', 'icy', 'jolly', 'late', 'misty', 'nameless', 'odd', 'purple', 'quiet', 'rough', 'shy', 'twilight', 'young'];
+const NAME_NOUN = ['breeze', 'cherry', 'dawn', 'feather', 'glitter', 'haze', 'leaf', 'meadow', 'night', 'paper', 'rain', 'shadow', 'silence', 'smoke', 'star', 'sun', 'thunder', 'violet', 'water', 'wind'];
+export function newMachineName(seed) {
+    const h = entropyHex(8, seed);
+    const a = NAME_ADJ[parseInt(h.slice(0, 2), 16) % NAME_ADJ.length];
+    const n = NAME_NOUN[parseInt(h.slice(2, 4), 16) % NAME_NOUN.length];
+    return `${a}-${n}-${(parseInt(h.slice(4, 8), 16) % 9000) + 1000}`;
+}
+/** 6PN address: deterministic per machine id (fdaa:… shape, fly-go's "internal 6PN address").
+ *  Ledgered only — nothing routes it locally; published loopback ports are the local
+ *  reachability story. */
+export function machinePrivateIp(machineId) {
+    const h = createHash('sha256').update(machineId).digest('hex');
+    return `fdaa:0:${h.slice(0, 4)}:a7b:${h.slice(4, 8)}:${h.slice(8, 12)}:${h.slice(12, 16)}:2`;
+}
+export function machineEvent(type, status, source, occurredAt, seq, request) {
+    // Event id: entropy-free WITHIN a machine write (derived from type+status+seq+time) so a
+    // pinned-clock verify sees stable events, but unique across the stream via seq.
+    const t = nowEpochMs(occurredAt);
+    const id = createHash('sha256').update(`${type}:${status}:${seq}:${t}`).digest('hex').slice(0, 26);
+    return { id, type, status, source, timestamp: t, ...(request ? { request } : {}) };
+}
+// ── image_ref (fly-go ImageRef {registry, repository, tag, digest, labels}) ───────────────────
+export function imageRefOf(image) {
+    // "registry/repository:tag" | "repository:tag" | bare repository. Digest is the local twin's
+    // deterministic stand-in (sha256 of the image string) — a real registry digest needs a real
+    // pull, which only the docker execution plane does; the ledgered digest is disclosed as
+    // twin-derived (spec-sources.json).
+    let rest = image;
+    let tag = 'latest';
+    const at = rest.indexOf('@');
+    let digest = '';
+    if (at !== -1) {
+        digest = rest.slice(at + 1);
+        rest = rest.slice(0, at);
+    }
+    const colon = rest.lastIndexOf(':');
+    if (colon !== -1 && !rest.slice(colon + 1).includes('/')) {
+        tag = rest.slice(colon + 1);
+        rest = rest.slice(0, colon);
+    }
+    const firstSeg = rest.split('/')[0] ?? '';
+    const hasRegistry = firstSeg.includes('.') || firstSeg.includes(':') || firstSeg === 'localhost';
+    const registry = hasRegistry ? firstSeg : 'registry-1.docker.io';
+    const repository = hasRegistry ? rest.split('/').slice(1).join('/') : (rest.includes('/') ? rest : `library/${rest}`);
+    return {
+        registry,
+        repository,
+        tag,
+        digest: digest || `sha256:${createHash('sha256').update(image).digest('hex')}`,
+        labels: {},
+    };
+}
+// ── container-spec derivation from a machine row ──────────────────────────────────────────────
+export function containerSpecOf(m) {
+    const config = (m.config ?? {});
+    const image = String(config.image ?? '');
+    const memoryMb = Number(config.guest?.memory_mb ?? 256);
+    const cpus = Number(config.guest?.cpus ?? 1);
+    const base = flyRuntimeEnv({
+        id: String(m.id),
+        app_name: String(m.app_name),
+        region: String(m.region),
+        instance_id: String(m.instance_id),
+        image,
+        memory_mb: memoryMb,
+        private_ip: String(m.private_ip),
+    });
+    const env = { ...base };
+    for (const [k, v] of Object.entries((config.env ?? {})))
+        env[k] = String(v);
+    const ports = [];
+    for (const svc of (config.services ?? [])) {
+        const p = Number(svc.internal_port ?? 0);
+        if (p > 0 && !ports.some((x) => x.internal === p))
+            ports.push({ internal: p });
+    }
+    const mounts = [];
+    for (const mt of (config.mounts ?? [])) {
+        if (mt.volume && mt.path)
+            mounts.push({ volumeId: String(mt.volume), path: String(mt.path) });
+    }
+    const init = (config.init ?? {});
+    return {
+        machineId: String(m.id),
+        appName: String(m.app_name),
+        machineName: String(m.name),
+        image,
+        memoryMiB: Number.isFinite(memoryMb) && memoryMb > 0 ? Math.floor(memoryMb) : 256,
+        cpus: Number.isFinite(cpus) && cpus > 0 ? cpus : 1,
+        env,
+        ...(Array.isArray(init.cmd) && init.cmd.length > 0 ? { cmd: init.cmd.map(String) } : {}),
+        ...(Array.isArray(init.entrypoint) && init.entrypoint.length > 0 ? { entrypoint: init.entrypoint.map(String) } : {}),
+        ports,
+        mounts,
+    };
+}

package/dist/src/fly-runtime-choice.d.ts

@@ -0,0 +1,12 @@
+import { type FlyContainerRuntime } from './fly-machines.js';
+export type FlyServerRuntimeChoice = 'virtual' | 'docker' | FlyContainerRuntime;
+/** Configuration of the LOCAL EXECUTION plane, declared here at the host boundary so a caller can
+ *  name it without importing the docker module (structurally the docker runtime's own options).
+ *  Ignored by the virtual plane, which runs nothing and therefore admits nothing. */
+export interface FlyLocalExecutionOptions {
+    /** MiB of writable storage admission keeps FREE beyond a machine's own need. Mechanism, not
+     *  policy: a World on a small disk configures the reserve down rather than the runtime quietly
+     *  lowering its floor. Omitted => the runtime's 2048 MiB default. */
+    storageReserveMiB?: number;
+}
+export declare function resolveFlyRuntime(choice: FlyServerRuntimeChoice | undefined, root?: string, options?: FlyLocalExecutionOptions): Promise<FlyContainerRuntime>;

package/dist/src/fly-runtime-choice.js

@@ -0,0 +1,21 @@
+// The execution-plane CHOICE, resolved at the host boundary (cli.ts, tests) — dev plane, never
+// imported by the serve path. 'virtual' is the pure ledger (offline default, nothing runs);
+// 'docker' is fly-docker.ts (machines genuinely run as local containers), a lazy import so the
+// docker module enters no graph unless asked for; a FlyContainerRuntime object injects a custom
+// plane. Absent capability FAILS with the fix, never a silent downgrade to virtual.
+import { VIRTUAL_FLY_RUNTIME } from "./fly-machines.js";
+export async function resolveFlyRuntime(choice, root = process.cwd(), options = {}) {
+    if (choice === undefined || choice === 'virtual')
+        return VIRTUAL_FLY_RUNTIME;
+    if (choice === 'docker') {
+        // Lazy import so the docker module never enters the graph unless asked for.
+        const { FlyDockerRuntime, dockerAvailable } = await import("./fly-docker.js");
+        if (!dockerAvailable()) {
+            // Absent capability => FAIL with the fix, never a silent downgrade to virtual (a caller who
+            // asked for real machines must not think they got them).
+            throw new Error('machine provider: the configured local execution runtime is unavailable');
+        }
+        return new FlyDockerRuntime(root, options);
+    }
+    return choice;
+}

package/dist/src/fly-server.d.ts

@@ -0,0 +1,31 @@
+import { type FlyContainerRuntime } from './fly-machines.js';
+/** Options every Fly-twin HTTP surface needs, independent of who owns the socket. The
+ *  execution plane arrives PRE-RESOLVED: `resolveFlyRuntime` is async (the docker plane is a
+ *  lazy import), and a fetch factory must be synchronous to mount in-process. Omitting it
+ *  selects the offline default — the pure ledger, nothing runs. */
+export interface FlyTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+    runtime?: FlyContainerRuntime;
+}
+/**
+ * The pack's whole HTTP surface as a plain fetch (runtime contract R12b): `createFlyTwinServer`
+ * is `Bun.serve` around this closure, and a Worker/DO entry mounts the same closure in-process,
+ * so the standalone and hosted lanes execute identical serving bytes.
+ *
+ * Hand-rolled rather than the kernel adapter (`createTwinFetchFromHandler`): the handler takes
+ * this pack's `runtime` (the execution plane) as a per-instance argument and lower-cases its
+ * header map, which the adapter's fixed request shape does not thread.
+ */
+export declare function createFlyTwinFetch(options?: FlyTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createFlyTwinServer(options?: {
+    cleanupOwnedOnStart?: boolean;
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    runtime?: FlyContainerRuntime;
+}): Promise<{
+    port: number;
+    runtimeKind: string;
+    stop: () => Promise<void>;
+}>;

package/dist/src/fly-server.js

@@ -0,0 +1,116 @@
+// fly twin HTTP server — serve the Machines API twin handler over plain HTTP so any unmodified
+// Machines API client (flyctl's flaps transport, fly-admin, plain fetch — Fly ships no canonical
+// npm SDK) works against it by pointing FLY_API_HOSTNAME at http://127.0.0.1:<port>, exactly the
+// env var Fly's own docs use for the base URL. Writable by default; pass readOnly to reject
+// writes with 405. State is the kernel projection (no side-store) — see fly-twin.ts.
+//
+// The EXECUTION PLANE arrives INJECTED and pre-resolved (a FlyContainerRuntime): the pure-ledger
+// virtual runtime is the default — nothing runs — and the real docker plane is a dev-plane
+// adapter the HOST BOUNDARY resolves (cli.ts via fly-runtime-choice.ts). This module never names
+// fly-docker.ts, so the serve closure carries no process, cwd or child_process (R4, R12b): the
+// engine is a provider behind a door, never the serve path's business.
+import { serveHttp } from '@volter/world-core';
+import { rows, VIRTUAL_FLY_RUNTIME } from "./fly-machines.js";
+import { worldNow, statefulTwinManifest } from '@volter/world-core';
+import { handleFlyTwinRequest } from "./fly-twin.js";
+/**
+ * The pack's whole HTTP surface as a plain fetch (runtime contract R12b): `createFlyTwinServer`
+ * is `Bun.serve` around this closure, and a Worker/DO entry mounts the same closure in-process,
+ * so the standalone and hosted lanes execute identical serving bytes.
+ *
+ * Hand-rolled rather than the kernel adapter (`createTwinFetchFromHandler`): the handler takes
+ * this pack's `runtime` (the execution plane) as a per-instance argument and lower-cases its
+ * header map, which the adapter's fixed request shape does not thread.
+ */
+export function createFlyTwinFetch(options = {}) {
+    const readOnly = options.readOnly ?? false;
+    const root = options.root; // undefined resolves through the kernel's projectRoot — the serve path never reads the process (R4)
+    const runtime = options.runtime ?? VIRTUAL_FLY_RUNTIME;
+    return async function flyTwinFetch(request) {
+        const url = new URL(request.url);
+        // GET /twin — the discovery manifest (education inside the twin). Constants only: no
+        // clock, no state, so every replay of this door is byte-identical (R9).
+        if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+            return Response.json(statefulTwinManifest({ vendor: 'fly', twinOf: "Fly.io's Machines API (api.machines.dev/v1)", stores: 'apps, machines and volumes — with --docker each Machine runs as a real local container' }));
+        }
+        const body = request.method !== 'GET' && request.method !== 'HEAD' ? await request.text() : '';
+        const headers = {};
+        request.headers.forEach((value, key) => { headers[key.toLowerCase()] = value; });
+        const { status, body: out } = await handleFlyTwinRequest({
+            method: request.method,
+            path: url.pathname + (url.search || ''),
+            body,
+            headers,
+            readOnly,
+            runtime,
+            occurredAt: worldNow(),
+            root,
+        });
+        if (status === 204 || out === null)
+            return new Response(null, { status });
+        return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json' } });
+    };
+}
+export async function createFlyTwinServer(options = {}) {
+    const readOnly = options.readOnly ?? false;
+    const root = options.root; // undefined resolves through the kernel's projectRoot — the serve path never reads the process (R4)
+    const runtime = options.runtime ?? VIRTUAL_FLY_RUNTIME;
+    // A freshly claimed World instance has no retained provider ledger, but an
+    // abrupt prior runner termination may have prevented the old service's stop
+    // hook. Reclaim only resources bearing this exact World-service owner before
+    // accepting new demand. Standalone/persistent providers opt out by default.
+    if (options.cleanupOwnedOnStart)
+        await runtime.cleanup?.();
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createFlyTwinFetch({ root, readOnly, runtime }),
+    });
+    let stopPromise;
+    const stop = () => {
+        if (stopPromise)
+            return stopPromise;
+        stopPromise = (async () => {
+            server.stop(true);
+            // A World owns the full lifecycle, including resources created behind a
+            // service boundary. Give every recorded Machine a graceful shutdown
+            // before removal, then let the runtime sweep any owner-labelled residue
+            // left by an interrupted API operation.
+            const failures = [];
+            const machines = rows('machine', root)
+                .map((machine) => machine._container_ref)
+                .filter((value) => typeof value === 'string' && value.length > 0);
+            await Promise.all(machines.map(async (containerRef) => {
+                try {
+                    await runtime.stop(containerRef, { timeoutSeconds: 3 });
+                }
+                catch { /* already stopped or gone */ }
+                try {
+                    await runtime.remove(containerRef);
+                }
+                catch (error) {
+                    failures.push(error instanceof Error ? error.message : String(error));
+                }
+            }));
+            if (runtime.removeVolume) {
+                const volumes = rows('volume', root).map((volume) => String(volume.id));
+                await Promise.all(volumes.map(async (volumeId) => {
+                    try {
+                        await runtime.removeVolume(volumeId);
+                    }
+                    catch { /* never materialized or already gone */ }
+                }));
+            }
+            try {
+                await runtime.cleanup?.();
+            }
+            catch (error) {
+                failures.push(error instanceof Error ? error.message : String(error));
+            }
+            if (failures.length > 0)
+                throw new Error(`world service cleanup failed: ${failures.join('; ')}`);
+        })();
+        return stopPromise;
+    };
+    return { port: server.port ?? options.port ?? 0, runtimeKind: runtime.kind, stop };
+}

package/dist/src/fly-twin.d.ts

@@ -0,0 +1,25 @@
+import { type FlyContainerRuntime } from './fly-machines.js';
+export type FlyRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    headers?: Record<string, string | undefined>;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** The execution plane. Defaults to the pure-ledger VIRTUAL runtime (offline). */
+    runtime?: FlyContainerRuntime;
+};
+export type FlyResponse = {
+    status: number;
+    body: unknown;
+};
+export declare const FLY_RESOURCE_TYPES: readonly ["app", "machine", "volume", "secret"];
+/** The public + internal Machines API hosts (fly.io/docs/machines/api/working-with-machines-api). */
+export declare const FLY_API_HOST = "api.machines.dev";
+export declare const FLY_INTERNAL_API_HOST = "_api.internal";
+export declare function handleFlyTwinRequest(req: FlyRequest): Promise<FlyResponse>;
+export declare function flyTwinSnapshot(): {
+    implementedEndpoints: string[];
+    resourceTypes: string[];
+};