@volter/twin-fly 0.1.0

package/src/fly-machines.ts

@@ -0,0 +1,383 @@
+// 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 container-runtime seam ────────────────────────────────────────────────────────────────
+
+/** One port the execution plane should expose on loopback. `internal` is the service's
+ *  internal_port from the machine config; the runtime picks (and reports) the host port. */
+export type FlyPortSpec = { internal: number };
+
+/** What the control plane asks the execution plane to run. Derived from fly.MachineConfig. */
+export type FlyContainerSpec = {
+  machineId: string;
+  appName: string;
+  machineName: string;
+  /** The docker image to run (fly.MachineConfig.image). */
+  image: string;
+  /** Guest limits from fly.MachineConfig.guest. A real execution runtime MUST enforce them. */
+  memoryMiB: number;
+  cpus: number;
+  /** config.env merged UNDER Fly's documented FLY_* runtime environment (flyRuntimeEnv). */
+  env: Record<string, string>;
+  /** init.cmd / init.entrypoint (fly.MachineInit). */
+  cmd?: string[];
+  entrypoint?: string[];
+  /** Every service's internal_port, deduped. */
+  ports: FlyPortSpec[];
+  /** config.mounts resolved to volume ids: mount a named local volume at `path`. */
+  mounts: Array<{ volumeId: string; path: string }>;
+};
+
+export type FlyExecResult = { exitCode: number; stdout: string; stderr: string };
+
+/**
+ * The execution plane, injected. `fly-docker.ts` is the real one (docker CLI over the local
+ * daemon); `VIRTUAL_FLY_RUNTIME` below is the offline default (pure ledger, nothing runs);
+ * tests inject recording/failing fakes. Optional members are capabilities a runtime may lack —
+ * the handler degrades honestly (exec without a runtime that can exec → Fly-shaped 400, never a
+ * fabricated success).
+ */
+export interface FlyContainerRuntime {
+  /** 'virtual' | 'docker' | a test fake's own tag. Recorded on the machine row (twin-only). */
+  readonly kind: string;
+  /** Launch the container. Returns the runtime's handle + any published loopback ports. */
+  run(spec: FlyContainerSpec): Promise<{ containerRef: string; publishedPorts?: Array<{ internal: number; host: number }> }>;
+  /** Stop the container (SIGTERM by default; `signal`/`timeoutSeconds` from Fly's StopRequest). */
+  stop(containerRef: string, opts?: { signal?: string; timeoutSeconds?: number }): Promise<void>;
+  /** Start a STOPPED container. Fly RESETS a stopped Machine's root filesystem on start —
+   *  "Stopped Machines that are restarted are completely reset to their original state so that
+   *  they start clean on the next run" (fly.io/docs/machines/api/machines-resource) — so a
+   *  faithful execution plane RECREATES the container from `spec` instead of resuming the old
+   *  writable layer; only mounted volumes survive. It therefore returns a NEW handle and NEW
+   *  published ports, exactly like `run`. Absent → the handler removes and re-runs the spec,
+   *  which is the same semantics by another route. */
+  start?(containerRef: string, spec: FlyContainerSpec): Promise<{ containerRef: string; publishedPorts?: Array<{ internal: number; host: number }> }>;
+  /** Remove the container (docker rm -f). */
+  remove(containerRef: string): Promise<void>;
+  /** Suspend/resume (docker pause/unpause). Optional; absent → suspend degrades to stop. */
+  pause?(containerRef: string): Promise<void>;
+  unpause?(containerRef: string): Promise<void>;
+  /** Deliver a signal without a state transition (docker kill --signal). */
+  signal?(containerRef: string, signal: string): Promise<void>;
+  /** Run a command inside the machine (docker exec). Absent → Fly-shaped 400 (see fly-twin.ts). */
+  exec?(containerRef: string, cmd: string[], opts?: { timeoutSeconds?: number }): Promise<FlyExecResult>;
+  /** Is the container still running? Absent → the control-plane state is taken as-is. */
+  inspect?(containerRef: string): Promise<{ running: boolean; exitCode?: number; oomKilled?: boolean }>;
+  /** Materialize/destroy a named local volume (docker volume create/rm). Optional. */
+  createVolume?(volumeId: string): Promise<void>;
+  removeVolume?(volumeId: string): Promise<void>;
+  /** Reclaim every backing resource owned by this runtime instance. */
+  cleanup?(): Promise<void>;
+}
+
+/**
+ * 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: FlyContainerRuntime = {
+  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: string, spec: FlyContainerSpec) {
+    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: { id: string; app_name: string; region: string; instance_id: string; image: string; memory_mb: number; private_ip: string }): Record<string, string> {
+  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',
+] as const;
+export type FlyMachineState = typeof FLY_MACHINE_STATES[number];
+
+// ── 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?: string): string {
+  return occurredAt ?? new Date().toISOString();
+}
+export function nowEpochMs(occurredAt?: string): number {
+  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: string, root?: string): Array<Record<string, unknown>> {
+  return projectResources(SERVICE, root)
+    .filter((r) => r.type === type && (r as Record<string, unknown>).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: string, root?: string): number {
+  return projectResources(SERVICE, root).filter((r) => r.type === type).length;
+}
+export function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
+  return rows(type, root).find((r) => r.id === id);
+}
+function view(r: Record<string, unknown>): Record<string, unknown> {
+  // 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: string,
+  id: string,
+  fields: Record<string, unknown>,
+  op: string,
+  root: string | undefined,
+  occurredAt: string | undefined,
+): Promise<Record<string, unknown>> {
+  const current = getRow(type, id, root);
+  const rev = typeof current?._rev === 'number' ? (current._rev as number) + 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: number, seed: string): string {
+  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: number, seed: string): string {
+  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: string): string {
+  return entropyHex(14, seed);
+}
+export function newInstanceId(occurredAt: string | undefined, seed: string): string {
+  // 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: string): string {
+  return `vol_${entropyB32(20, seed)}`;
+}
+export function newLeaseNonce(seed: string): string {
+  return entropyHex(24, seed);
+}
+/** An app's internal numeric id — the same seeded source, read as a 24-bit integer. */
+export function newAppNumericId(seed: string): number {
+  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: string): string {
+  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: string): string {
+  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`;
+}
+
+// ── MachineEvent stream (fly-go MachineEvent: {id?, type, status, source, timestamp}) ─────────
+export type FlyMachineEvent = {
+  id: string;
+  type: string;
+  status: string;
+  source: 'flyd' | 'user';
+  timestamp: number;
+  /** fly-go MachineEvent.request — used for the exit payload ({exit_event:{exit_code}}), which is
+   *  what flyctl reads to say WHY a machine died. Populated by the runtime-exit fold. */
+  request?: Record<string, unknown>;
+};
+export function machineEvent(type: string, status: string, source: 'flyd' | 'user', occurredAt: string | undefined, seq: number, request?: Record<string, unknown>): FlyMachineEvent {
+  // 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: string): Record<string, unknown> {
+  // "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: Record<string, unknown>): FlyContainerSpec {
+  const config = (m.config ?? {}) as Record<string, any>;
+  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: Record<string, string> = { ...base };
+  for (const [k, v] of Object.entries((config.env ?? {}) as Record<string, unknown>)) env[k] = String(v);
+  const ports: FlyPortSpec[] = [];
+  for (const svc of (config.services ?? []) as Array<Record<string, any>>) {
+    const p = Number(svc.internal_port ?? 0);
+    if (p > 0 && !ports.some((x) => x.internal === p)) ports.push({ internal: p });
+  }
+  const mounts: Array<{ volumeId: string; path: string }> = [];
+  for (const mt of (config.mounts ?? []) as Array<Record<string, any>>) {
+    if (mt.volume && mt.path) mounts.push({ volumeId: String(mt.volume), path: String(mt.path) });
+  }
+  const init = (config.init ?? {}) as Record<string, any>;
+  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/src/fly-runtime-choice.ts

@@ -0,0 +1,38 @@
+// 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, type FlyContainerRuntime } from './fly-machines.ts';
+
+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 async function resolveFlyRuntime(
+  choice: FlyServerRuntimeChoice | undefined,
+  root = process.cwd(),
+  options: FlyLocalExecutionOptions = {},
+): Promise<FlyContainerRuntime> {
+  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.ts');
+    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/src/fly-server.ts

@@ -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, type FlyContainerRuntime } from './fly-machines.ts';
+import { worldNow, statefulTwinManifest} from '@volter/world-core';
+import { handleFlyTwinRequest } from './fly-twin.ts';
+
+/** 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 function createFlyTwinFetch(options: FlyTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  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: Request): Promise<Response> {
+    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: Record<string, string> = {};
+    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: { cleanupOwnedOnStart?: boolean; root?: string; port?: number; readOnly?: boolean; runtime?: FlyContainerRuntime } = {},
+): Promise<{ port: number; runtimeKind: string; stop: () => Promise<void> }> {
+  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: Promise<void> | undefined;
+  const stop = (): Promise<void> => {
+    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: string[] = [];
+      const machines = rows('machine', root)
+        .map((machine) => machine._container_ref)
+        .filter((value): value is string => 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 };
+}