@volter/twin-fly 0.1.0

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

@@ -0,0 +1,8 @@
+export type FlyConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    endpointsProbed: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkFlyConformance(): Promise<FlyConformanceReport>;

package/dist/src/fly-conformance.js

@@ -0,0 +1,142 @@
+// fly conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// The tinybird PROBES pattern (ADDING_A_TWIN §6 "conformance teeth"): ONE REAL REQUEST per
+// claimed endpoint, each declaring the OUTCOME a live handler produces — an expected status set
+// plus a predicate over the body — driven against a throwaway root, with the endpoint census a
+// two-way bijection with `flyTwinSnapshot()`. A deleted handler branch falls through to the
+// router's 404/405 or answers the wrong shape, and either way this goes red. Two constants
+// asserting about each other (the tinybird round-one false-green) is exactly what this is not:
+// every expectation below is a LITERAL, never an import from the handler.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleFlyTwinRequest, flyTwinSnapshot } from "./fly-twin.js";
+const isObject = (b) => !!b && typeof b === 'object' && !Array.isArray(b);
+const hasKeys = (...keys) => (b) => isObject(b) && keys.every((k) => b[k] !== undefined);
+// Fixture ids minted by seeding, addressed by the probes.
+const APP = 'probe-app';
+const fx = { machineId: '', stoppedMachineId: '', volumeId: '', doomedVolumeId: '', leaseNonce: '' };
+/** A representative request per declared endpoint. DESTRUCTIVE probes target throwaway fixtures
+ *  of their own; the shared fixture machine's probes are ORDER-DEPENDENT by design (probes run in
+ *  declaration order) and each order dependency is stated inline where it is load-bearing. */
+const PROBES = {
+    'GET /v1/apps': { method: 'GET', path: '/v1/apps?org_slug=personal', status: [200], expect: (b) => isObject(b) && Array.isArray(b.apps) && typeof b.total_apps === 'number' },
+    'POST /v1/apps': { method: 'POST', path: '/v1/apps', body: { app_name: 'probe-app-created', org_slug: 'personal' }, status: [201] },
+    'GET /v1/apps/{app_name}': { method: 'GET', path: `/v1/apps/${APP}`, status: [200], expect: (b) => isObject(b) && b.name === APP && isObject(b.organization) },
+    'DELETE /v1/apps/{app_name}': { method: 'DELETE', path: '/v1/apps/probe-app-doomed', status: [202] },
+    'GET /v1/apps/{app_name}/machines': { method: 'GET', path: `/v1/apps/${APP}/machines`, status: [200], expect: (b) => Array.isArray(b) && b.some((m) => m.id === fx.machineId) },
+    'POST /v1/apps/{app_name}/machines': { method: 'POST', path: `/v1/apps/${APP}/machines`, body: { config: { image: 'nginx:alpine' } }, status: [200], expect: (b) => isObject(b) && b.state === 'started' && typeof b.id === 'string' },
+    'GET /v1/apps/{app_name}/machines/{machine_id}': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}`, status: [200], expect: (b) => isObject(b) && b.id === fx.machineId && Array.isArray(b.events) },
+    'POST /v1/apps/{app_name}/machines/{machine_id}': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}`, body: { config: { image: 'nginx:1.27-alpine', metadata: { probe_key: 'probe-value' } } }, status: [200], expect: (b) => isObject(b) && isObject(b.config) && b.config.image === 'nginx:1.27-alpine' },
+    'DELETE /v1/apps/{app_name}/machines/{machine_id}': { method: 'DELETE', path: () => `/v1/apps/${APP}/machines/${fx.stoppedMachineId}`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    // ORDER: stop first, so the start probe below exercises the REAL start path (previous_state
+    // "stopped"), not the idempotent already-started short-circuit.
+    'POST /v1/apps/{app_name}/machines/{machine_id}/stop': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/stop`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/start': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/start`, status: [200], expect: (b) => isObject(b) && b.previous_state === 'stopped' },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/restart': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/restart`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/signal': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/signal`, body: { signal: 'SIGTERM' }, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    // Probes run in declaration order, so exec probes while the machine is still STARTED (signal
+    // above leaves it started; suspend below takes it out of exec's reach). The default (virtual)
+    // execution plane cannot execute; the honest, documented outcome is the vendor-enveloped 400
+    // naming the virtual plane — never a fabricated {exit_code:0}.
+    'POST /v1/apps/{app_name}/machines/{machine_id}/exec': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/exec`, body: { command: ['echo', 'hi'] }, status: [400], expect: (b) => isObject(b) && typeof b.error === 'string' && b.error.includes('virtual') },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/suspend': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/suspend`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/cordon': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/cordon`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/uncordon': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/uncordon`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    // After suspend the fixture machine is suspended, so wait?state=suspended is the honest probe
+    // of the wait mechanism itself (already-there → 200 {ok:true}).
+    'GET /v1/apps/{app_name}/machines/{machine_id}/wait': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/wait?state=suspended`, status: [200], expect: (b) => isObject(b) && b.ok === true },
+    'GET /v1/apps/{app_name}/machines/{machine_id}/events': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/events`, status: [200], expect: (b) => Array.isArray(b) && b.length > 0 && hasKeys('type', 'status', 'timestamp')(b[0]) },
+    'GET /v1/apps/{app_name}/machines/{machine_id}/versions': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/versions`, status: [200], expect: (b) => Array.isArray(b) && b.length > 0 && hasKeys('version', 'user_config')(b[0]) },
+    'GET /v1/apps/{app_name}/machines/{machine_id}/lease': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/lease`, status: [200], expect: (b) => isObject(b) && b.status === 'success' && isObject(b.data) && typeof b.data.nonce === 'string' },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/lease': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/lease`, headers: () => ({ 'fly-machine-lease-nonce': fx.leaseNonce }), body: { ttl: 60 }, status: [201], expect: (b) => isObject(b) && b.status === 'success' },
+    'DELETE /v1/apps/{app_name}/machines/{machine_id}/lease': { method: 'DELETE', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/lease`, headers: () => ({ 'fly-machine-lease-nonce': fx.leaseNonce }), status: [200], expect: (b) => isObject(b) && b.status === 'success' },
+    'GET /v1/apps/{app_name}/machines/{machine_id}/metadata': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/metadata`, status: [200], expect: (b) => isObject(b) && b.probe_key === 'probe-value' },
+    'GET /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}': { method: 'GET', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/metadata/probe_key`, status: [200], expect: (b) => isObject(b) && b.value === 'probe-value' },
+    'POST /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}': { method: 'POST', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/metadata/probe_key2`, body: { value: 'v2' }, status: [204] },
+    'DELETE /v1/apps/{app_name}/machines/{machine_id}/metadata/{key}': { method: 'DELETE', path: () => `/v1/apps/${APP}/machines/${fx.machineId}/metadata/probe_key2`, status: [204] },
+    'GET /v1/apps/{app_name}/volumes': { method: 'GET', path: `/v1/apps/${APP}/volumes`, status: [200], expect: (b) => Array.isArray(b) && b.some((v) => v.id === fx.volumeId) },
+    'POST /v1/apps/{app_name}/volumes': { method: 'POST', path: `/v1/apps/${APP}/volumes`, body: { name: 'probe_vol_created', size_gb: 1 }, status: [200], expect: (b) => isObject(b) && typeof b.id === 'string' && b.id.startsWith('vol_') },
+    'GET /v1/apps/{app_name}/volumes/{volume_id}': { method: 'GET', path: () => `/v1/apps/${APP}/volumes/${fx.volumeId}`, status: [200], expect: (b) => isObject(b) && b.id === fx.volumeId && b.name === 'probe_vol' },
+    'PUT /v1/apps/{app_name}/volumes/{volume_id}': { method: 'PUT', path: () => `/v1/apps/${APP}/volumes/${fx.volumeId}`, body: { snapshot_retention: 9 }, status: [200], expect: (b) => isObject(b) && b.snapshot_retention === 9 },
+    'DELETE /v1/apps/{app_name}/volumes/{volume_id}': { method: 'DELETE', path: () => `/v1/apps/${APP}/volumes/${fx.doomedVolumeId}`, status: [200], expect: (b) => isObject(b) && b.state === 'pending_destroy' },
+    'PUT /v1/apps/{app_name}/volumes/{volume_id}/extend': { method: 'PUT', path: () => `/v1/apps/${APP}/volumes/${fx.volumeId}/extend`, body: { size_gb: 4 }, status: [200], expect: (b) => isObject(b) && isObject(b.volume) && b.volume.size_gb === 4 && typeof b.needs_restart === 'boolean' },
+    // ORDER: POST first — the GET after it is what gives the (empty-bodied) create its teeth: a
+    // handler stubbed to `return {status:200, body:{}}` would leave the list empty and go red here.
+    'POST /v1/apps/{app_name}/volumes/{volume_id}/snapshots': { method: 'POST', path: () => `/v1/apps/${APP}/volumes/${fx.volumeId}/snapshots`, status: [200] },
+    'GET /v1/apps/{app_name}/volumes/{volume_id}/snapshots': { method: 'GET', path: () => `/v1/apps/${APP}/volumes/${fx.volumeId}/snapshots`, status: [200], expect: (b) => Array.isArray(b) && b.length === 1 && String(b[0].id).startsWith('vs_') },
+    'GET /v1/apps/{app_name}/secrets': { method: 'GET', path: `/v1/apps/${APP}/secrets`, status: [200], expect: (b) => isObject(b) && Array.isArray(b.secrets) },
+    'POST /v1/apps/{app_name}/secrets': { method: 'POST', path: `/v1/apps/${APP}/secrets`, body: { values: { PROBE_BULK: 'x' } }, status: [200], expect: (b) => isObject(b) && Array.isArray(b.secrets) && typeof b.version === 'number' },
+    'GET /v1/apps/{app_name}/secrets/{secret_name}': { method: 'GET', path: `/v1/apps/${APP}/secrets/PROBE_SECRET`, status: [200], expect: (b) => isObject(b) && b.name === 'PROBE_SECRET' && b.value === undefined },
+    'POST /v1/apps/{app_name}/secrets/{secret_name}': { method: 'POST', path: `/v1/apps/${APP}/secrets/PROBE_SECRET_CREATED`, body: { value: 's3cret' }, status: [201], expect: (b) => isObject(b) && b.name === 'PROBE_SECRET_CREATED' && typeof b.digest === 'string' },
+    'DELETE /v1/apps/{app_name}/secrets/{secret_name}': { method: 'DELETE', path: `/v1/apps/${APP}/secrets/PROBE_SECRET_DOOMED`, status: [200], expect: (b) => isObject(b) && typeof b.version === 'number' },
+};
+export async function checkFlyConformance() {
+    const snapshot = flyTwinSnapshot();
+    const violations = [];
+    const root = mkdtempSync(join(tmpdir(), 'fly-conformance-'));
+    const at = '2026-02-01T00:00:00.000Z';
+    const call = (method, path, body, headers) => handleFlyTwinRequest({
+        method, path, ...(body !== undefined ? { body: JSON.stringify(body) } : {}), root, occurredAt: at,
+        headers: { authorization: 'Bearer probe-token', ...(headers ?? {}) },
+    });
+    let probed = 0;
+    try {
+        // Seed the fixtures the probes address, through the twin's own write path.
+        await call('POST', '/v1/apps', { app_name: APP, org_slug: 'personal' });
+        await call('POST', '/v1/apps', { app_name: 'probe-app-doomed', org_slug: 'personal' });
+        const m = await call('POST', `/v1/apps/${APP}/machines`, { config: { image: 'nginx:alpine', metadata: { probe_key: 'probe-value' } } });
+        fx.machineId = String(m.body.id);
+        const m2 = await call('POST', `/v1/apps/${APP}/machines`, { config: { image: 'nginx:alpine' }, skip_launch: true });
+        fx.stoppedMachineId = String(m2.body.id);
+        const v = await call('POST', `/v1/apps/${APP}/volumes`, { name: 'probe_vol', size_gb: 2 });
+        fx.volumeId = String(v.body.id);
+        const doomed = await call('POST', `/v1/apps/${APP}/volumes`, { name: 'probe_vol_doomed', size_gb: 1 });
+        fx.doomedVolumeId = String(doomed.body.id);
+        const lease = await call('POST', `/v1/apps/${APP}/machines/${fx.machineId}/lease`, { ttl: 3600 });
+        fx.leaseNonce = String(lease.body.data.nonce);
+        await call('POST', `/v1/apps/${APP}/secrets/PROBE_SECRET`, { value: 'hidden' });
+        await call('POST', `/v1/apps/${APP}/secrets/PROBE_SECRET_DOOMED`, { value: 'doomed' });
+        // Two-way bijection: every snapshot endpoint has a probe, every probe names a snapshot endpoint.
+        for (const endpoint of snapshot.implementedEndpoints) {
+            if (!PROBES[endpoint])
+                violations.push(`endpoint '${endpoint}' is claimed but has no probe`);
+        }
+        for (const key of Object.keys(PROBES)) {
+            if (!snapshot.implementedEndpoints.includes(key))
+                violations.push(`probe '${key}' targets an endpoint the snapshot does not claim`);
+        }
+        for (const [endpoint, probe] of Object.entries(PROBES)) {
+            probed++;
+            const path = typeof probe.path === 'function' ? probe.path() : probe.path;
+            const headers = typeof probe.headers === 'function' ? probe.headers() : probe.headers;
+            // The lease-guard means every state-mutating probe on the leased fixture machine must carry
+            // the nonce; passing it unconditionally is harmless for the rest.
+            const withNonce = fx.leaseNonce ? { 'fly-machine-lease-nonce': fx.leaseNonce, ...(headers ?? {}) } : headers;
+            const res = await call(probe.method, path, probe.body, withNonce);
+            if (!probe.status.includes(res.status)) {
+                violations.push(`${endpoint}: expected status ${probe.status.join('/')} but got ${res.status} (${JSON.stringify(res.body)?.slice(0, 200)})`);
+                continue;
+            }
+            if (probe.expect && !probe.expect(res.body)) {
+                violations.push(`${endpoint}: status ok but the body failed the probe's shape predicate (${JSON.stringify(res.body)?.slice(0, 200)})`);
+            }
+        }
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+    // LITERAL census (never the constant the handler itself exports — that was tinybird's
+    // two-constants false-green): the resource types this twin is expected to project.
+    for (const type of ['app', 'machine', 'volume', 'secret']) {
+        if (!snapshot.resourceTypes.includes(type))
+            violations.push(`resource type '${type}' missing from snapshot`);
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        endpointsProbed: probed,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

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

@@ -0,0 +1,75 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { FlyBudget, type FlyBudgetOptions } from './fly-budget.js';
+/**
+ * The injected real-Fly boundary. One Machines API call:
+ *   method — 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+ *   path   — e.g. '/v1/apps?org_slug=personal' or '/v1/apps/my-app/machines'
+ * Returns the HTTP status + parsed JSON body. Status-bearing BY DESIGN: a refused/failed pull
+ * must be distinguishable from a genuinely empty account (ADDING_A_TWIN §6 — "a REFUSED pull is
+ * NOT an empty account"), so every pull helper below THROWS on a non-2xx instead of folding an
+ * empty list over real observed state.
+ */
+export type FlyExecute = (method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>) => Promise<{
+    status: number;
+    body: any;
+}>;
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveFlyOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: FlyBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: FlyBudgetOptions;
+};
+/**
+ * A live executor against real Fly (token = a Fly.io API token, `fly tokens deploy` / org token).
+ * Never imported by the pack's own runtime path — only constructed by a caller opting into real
+ * I/O. THIS IS THE ONE PLACE this pack issues a live api.machines.dev request, and the Machines
+ * API is a particularly bad place to burst: its writes PROVISION AND BILL real compute. EVERY
+ * call is guarded: the budget is charged BEFORE the request goes out (`checkBudget` THROWS
+ * `FlyBudgetError` instead of returning when the ceiling or a persisted cooldown says stop) and
+ * the response is fed back (`recordCall`) so a `Retry-After`/429 becomes a persisted cooldown
+ * that makes every later call fail fast WITHOUT touching Fly. There is deliberately no option
+ * that disables the guard; an injected `budget` must be an UNMODIFIED FlyBudget
+ * (`assertBudgetGuardIntact` — method identity, not `instanceof`; a subclass overriding
+ * `checkBudget` or a Proxy trapping it is refused).
+ */
+export declare function liveFlyExecute(token: string, base?: string, opts?: LiveFlyOptions): FlyExecute;
+export declare function mapApp(orgSlug: string, a: Record<string, unknown>): SyncResource;
+export declare function mapMachine(appName: string, m: Record<string, unknown>): SyncResource;
+export declare function mapVolume(appName: string, v: Record<string, unknown>): SyncResource;
+export declare function pullFlyApps(execute: FlyExecute, orgSlug: string): Promise<SyncResource[]>;
+export declare function pullFlyMachines(execute: FlyExecute, appName: string): Promise<SyncResource[]>;
+export declare function pullFlyVolumes(execute: FlyExecute, appName: string): Promise<SyncResource[]>;
+/**
+ * D7 entry point: pull the real account's apps (and each app's machines + volumes) and fold them
+ * into the twin via ONE `observeResources` batch (the fold's own diff). Returns `{observed, deltasAppended}` — a
+ * re-pull of identical state appends ZERO deltas. `occurredAt` defaults to a MOVING now (never a
+ * pinned constant — a pinned pull default makes a reverting vendor value collide with its own
+ * earlier observation and vanish as a phantom delta; ADDING_A_TWIN §6).
+ */
+export declare function syncFlyFromReal(execute: FlyExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+    orgSlug?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The pack's executor over the kernel's: the same Machines API call, carried by the head. */
+export declare function flyExecuteOver(execute: RemoteExecute): FlyExecute;
+/** The refresh adapter: pull the org's apps, machines and volumes through the executor and fold them into the root. */
+export declare function syncFlyFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+    orgSlug?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** The perform adapter: one entry crosses to Fly through the executor — an app, a volume, a machine and its
+ *  lifecycle, a secret. An entry that is the twin's own (a lease, a purge, flyd's fold of a container exit, a
+ *  snapshot) crosses nothing. A referenced id (a mount's volume, a path's machine) is the vendor's by then. */
+export declare function performFlyAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/fly-connector.js

@@ -0,0 +1,277 @@
+// fly CONNECTOR — the live-vendor pull path that gives the fly twin the "git for SaaS"
+// lifecycle over an INJECTED executor (the auth boundary).
+//
+// PULL (real → twin): fetch the real account's apps (then each app's machines + volumes) over
+// the injected executor, map → SyncResource[], fold into the tree via `observeResources`
+// (shadow-diff dedup, so a re-pull of identical state appends nothing) — D6/D7.
+//
+// PERFORM (twin → real) is the head's, at protocol 2: `performFlyAction` carries ONE entry across
+// through the kernel's executor — and only when the head is bound to a real state system, an
+// operator's deliberate act, because a performed machine-create provisions real BILLABLE compute.
+//
+// The vendor I/O is an INJECTED executor: a fake in tests, `liveFlyExecute(token)` in prod —
+// the ONE place this pack issues a live api.machines.dev request, and therefore the one place
+// the rate budget is enforced (D8). The pack imports NO SDK and holds NO token.
+import { assertBudgetGuardIntact, observeResources } from '@volter/world-core';
+import { FlyBudget, FlyBudgetError, flyCallWeight } from "./fly-budget.js";
+const SERVICE = 'fly';
+/**
+ * A live executor against real Fly (token = a Fly.io API token, `fly tokens deploy` / org token).
+ * Never imported by the pack's own runtime path — only constructed by a caller opting into real
+ * I/O. THIS IS THE ONE PLACE this pack issues a live api.machines.dev request, and the Machines
+ * API is a particularly bad place to burst: its writes PROVISION AND BILL real compute. EVERY
+ * call is guarded: the budget is charged BEFORE the request goes out (`checkBudget` THROWS
+ * `FlyBudgetError` instead of returning when the ceiling or a persisted cooldown says stop) and
+ * the response is fed back (`recordCall`) so a `Retry-After`/429 becomes a persisted cooldown
+ * that makes every later call fail fast WITHOUT touching Fly. There is deliberately no option
+ * that disables the guard; an injected `budget` must be an UNMODIFIED FlyBudget
+ * (`assertBudgetGuardIntact` — method identity, not `instanceof`; a subclass overriding
+ * `checkBudget` or a Proxy trapping it is refused).
+ */
+export function liveFlyExecute(token, base = 'https://api.machines.dev', opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    // The default ledger is keyed by a hash of THIS token — Fly scopes limits under the account
+    // the token names, so a cwd-scoped ledger would hand the same token a fresh allowance per
+    // checkout/worktree/CI leg.
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, FlyBudget, 'liveFlyExecute')
+        : new FlyBudget({ token, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, reqBody) => {
+        const headers = { Authorization: `Bearer ${token}` };
+        const init = { method, headers };
+        if (method !== 'GET' && reqBody) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(reqBody);
+        }
+        const weight = flyCallWeight(method, path.split('?')[0] ?? path);
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${base}${path}`, init);
+        const resHeaders = {};
+        res.headers.forEach((v, k) => { resHeaders[k.toLowerCase()] = v; });
+        const text = await res.text();
+        // Settles the reservation and, on a back-off signal, arms the persisted cooldown (may itself
+        // throw a louder refusal — the cooldown is persisted first either way).
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer Fly ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof FlyBudgetError) || !res.ok)
+                throw error;
+        }
+        let body = {};
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = { error: text };
+            }
+        }
+        return { status: res.status, body };
+    };
+}
+/** A non-2xx pull reply is a REFUSAL, never an empty account — throw, don't fold. */
+function refuse(what, res) {
+    const msg = res.body && typeof res.body === 'object' && typeof res.body.error === 'string' ? res.body.error : JSON.stringify(res.body);
+    throw new Error(`fly pull ${what} refused: HTTP ${res.status} ${msg}`);
+}
+// ── Mapping (real Fly → twin SyncResource) — pure, no client (the mutation-test connector
+// sweep leaves map* real by convention) ───────────────────────────────────────────────────────
+export function mapApp(orgSlug, a) {
+    return {
+        type: 'app',
+        id: String(a.name ?? a.id),
+        fields: {
+            org_slug: orgSlug,
+            org_name: a.organization?.name ?? orgSlug,
+            network: a.network ?? 'default',
+            internal_numeric_id: a.internal_numeric_id ?? null,
+            status: a.status ?? 'pending',
+        },
+    };
+}
+export function mapMachine(appName, m) {
+    return {
+        type: 'machine',
+        id: String(m.id),
+        fields: {
+            app_name: appName,
+            name: m.name ?? '',
+            region: m.region ?? '',
+            state: m.state ?? 'stopped',
+            instance_id: m.instance_id ?? '',
+            private_ip: m.private_ip ?? '',
+            created_at: m.created_at ?? null,
+            machine_updated_at: m.updated_at ?? null,
+            config: m.config ?? {},
+            image_ref: m.image_ref ?? {},
+            events: Array.isArray(m.events) ? [...m.events].reverse() : [], // the wire is newest-first; the row is in order
+            cordoned: m.cordoned === true,
+            // A pulled machine runs on REAL Fly, not on any local execution plane: the runtime kind records
+            // the fact honestly. The twin's own bookkeeping (`_`-prefixed) is outside the vendor's shape.
+            _twin_runtime: 'real-fly',
+        },
+    };
+}
+export function mapVolume(appName, v) {
+    return {
+        type: 'volume',
+        id: String(v.id),
+        fields: {
+            app_name: appName,
+            name: v.name ?? '',
+            region: v.region ?? '',
+            size_gb: v.size_gb ?? 1,
+            encrypted: v.encrypted !== false,
+            fstype: v.fstype ?? 'ext4',
+            snapshot_retention: v.snapshot_retention ?? 5,
+            auto_backup_enabled: v.auto_backup_enabled !== false,
+            zone: v.zone ?? '',
+            state: v.state ?? 'created',
+            attached_machine_id: v.attached_machine_id ?? null,
+            created_at: v.created_at ?? null,
+            snapshots: [],
+        },
+    };
+}
+// ── PULL ──────────────────────────────────────────────────────────────────────────────────────
+export async function pullFlyApps(execute, orgSlug) {
+    const res = await execute('GET', `/v1/apps?org_slug=${encodeURIComponent(orgSlug)}`);
+    if (res.status < 200 || res.status >= 300)
+        refuse('apps', res);
+    const apps = Array.isArray(res.body?.apps) ? res.body.apps : [];
+    // the list is the short shape (id, name, machine_count, network, status); the App itself — its internal
+    // numeric id, its organization — answers at /v1/apps/{name}, one read per app
+    const out = [];
+    for (const a of apps) {
+        const name = String(a.name ?? a.id);
+        const detail = await execute('GET', `/v1/apps/${encodeURIComponent(name)}`);
+        if (detail.status < 200 || detail.status >= 300)
+            refuse(`app ${name}`, detail);
+        out.push(mapApp(orgSlug, { ...a, ...detail.body }));
+    }
+    return out;
+}
+export async function pullFlyMachines(execute, appName) {
+    const res = await execute('GET', `/v1/apps/${encodeURIComponent(appName)}/machines`);
+    if (res.status < 200 || res.status >= 300)
+        refuse(`machines of ${appName}`, res);
+    const machines = Array.isArray(res.body) ? res.body : [];
+    return machines.map((m) => mapMachine(appName, m));
+}
+export async function pullFlyVolumes(execute, appName) {
+    const res = await execute('GET', `/v1/apps/${encodeURIComponent(appName)}/volumes`);
+    if (res.status < 200 || res.status >= 300)
+        refuse(`volumes of ${appName}`, res);
+    const volumes = Array.isArray(res.body) ? res.body : [];
+    return volumes.map((v) => mapVolume(appName, v));
+}
+/**
+ * D7 entry point: pull the real account's apps (and each app's machines + volumes) and fold them
+ * into the twin via ONE `observeResources` batch (the fold's own diff). Returns `{observed, deltasAppended}` — a
+ * re-pull of identical state appends ZERO deltas. `occurredAt` defaults to a MOVING now (never a
+ * pinned constant — a pinned pull default makes a reverting vendor value collide with its own
+ * earlier observation and vanish as a phantom delta; ADDING_A_TWIN §6).
+ */
+export async function syncFlyFromReal(execute, opts = {}) {
+    const orgSlug = opts.orgSlug ?? 'personal';
+    const occurredAt = opts.occurredAt ?? new Date().toISOString();
+    const apps = await pullFlyApps(execute, orgSlug);
+    const nested = [];
+    for (const app of apps) {
+        const appName = app.id;
+        const [machines, volumes] = await Promise.all([
+            pullFlyMachines(execute, appName),
+            pullFlyVolumes(execute, appName),
+        ]);
+        nested.push(...machines, ...volumes);
+    }
+    const resources = [...apps, ...nested];
+    // protocol 2: an observation lands on the head through the kernel's fold — one batch, one instant
+    const report = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: occurredAt, batch: `obs:${SERVICE}:${occurredAt}` });
+    return { observed: report.observed, deltasAppended: report.appended };
+}
+// ── PROTOCOL 2: the state system's two adapters, over the kernel's executor ──────────
+/** The pack's executor over the kernel's: the same Machines API call, carried by the head. */
+export function flyExecuteOver(execute) {
+    return async (method, path, body) => {
+        // the wire wants a bearer: at a real boundary the kernel's executor sets the sealed credential over this
+        // header (executor.ts — a pack never holds one); at the twin's own wire, refreshed from itself, any bearer is a bearer
+        const res = await execute({ method, path, headers: { accept: 'application/json', authorization: 'Bearer twin', ...(body ? { 'content-type': 'application/json' } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        let parsed = {};
+        if (res.body) {
+            try {
+                parsed = JSON.parse(res.body);
+            }
+            catch {
+                parsed = { error: res.body };
+            }
+        }
+        return { status: res.status, body: parsed };
+    };
+}
+/** The refresh adapter: pull the org's apps, machines and volumes through the executor and fold them into the root. */
+export async function syncFlyFromRemote(execute, opts = {}) {
+    return syncFlyFromReal(flyExecuteOver(execute), { ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.orgSlug !== undefined ? { orgSlug: opts.orgSlug } : {}), occurredAt: opts.occurredAt ?? new Date().toISOString() });
+}
+/** The perform adapter: one entry crosses to Fly through the executor — an app, a volume, a machine and its
+ *  lifecycle, a secret. An entry that is the twin's own (a lease, a purge, flyd's fold of a container exit, a
+ *  snapshot) crosses nothing. A referenced id (a mount's volume, a path's machine) is the vendor's by then. */
+export async function performFlyAction(execute, action, ctx) {
+    const fly = flyExecuteOver(execute);
+    const op = action.operation ?? `${action.subject.type}.update`;
+    const f = action.fields ?? {};
+    const app = encodeURIComponent(String(f.app_name ?? ''));
+    const answer = async (method, path, body) => {
+        const res = await fly(method, path, body);
+        if (res.status < 200 || res.status >= 300)
+            throw new Error(`fly perform ${op} refused: HTTP ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`);
+        return (res.body ?? {});
+    };
+    const machineId = () => encodeURIComponent(ctx.resolve('machine', action.subject.id));
+    const volumeId = () => encodeURIComponent(ctx.resolve('volume', action.subject.id));
+    switch (op) {
+        case 'app.create':
+            await answer('POST', '/v1/apps', { app_name: action.subject.id, org_slug: f.org_slug ?? 'personal', network: f.network ?? 'default' });
+            return { externalId: action.subject.id };
+        case 'app.delete':
+            await answer('DELETE', `/v1/apps/${encodeURIComponent(action.subject.id)}`);
+            return { externalId: action.subject.id };
+        case 'volume.create': {
+            const v = await answer('POST', `/v1/apps/${app}/volumes`, { name: f.name, region: f.region, size_gb: f.size_gb, encrypted: f.encrypted, fstype: f.fstype, snapshot_retention: f.snapshot_retention, auto_backup_enabled: f.auto_backup_enabled });
+            return { externalId: String(v.id ?? action.subject.id), data: v };
+        }
+        case 'volume.delete':
+            await answer('DELETE', `/v1/apps/${app}/volumes/${volumeId()}`);
+            return { externalId: ctx.resolve('volume', action.subject.id) };
+        case 'machine.create': {
+            const config = { ...(f.config ?? {}) };
+            if (Array.isArray(config.mounts))
+                config.mounts = config.mounts.map((m) => (typeof m.volume === 'string' ? { ...m, volume: ctx.resolve('volume', m.volume) } : m));
+            const m = await answer('POST', `/v1/apps/${app}/machines`, { name: f.name, region: f.region, config, ...(f.state === 'created' ? { skip_launch: true } : {}) });
+            return { externalId: String(m.id ?? action.subject.id), data: m };
+        }
+        case 'machine.update':
+            await answer('POST', `/v1/apps/${app}/machines/${machineId()}`, { config: f.config });
+            return { externalId: ctx.resolve('machine', action.subject.id) };
+        case 'machine.start':
+        case 'machine.stop':
+        case 'machine.suspend':
+        case 'machine.restart':
+        case 'machine.cordon':
+        case 'machine.uncordon':
+            await answer('POST', `/v1/apps/${app}/machines/${machineId()}/${op.slice('machine.'.length)}`);
+            return { externalId: ctx.resolve('machine', action.subject.id) };
+        case 'machine.destroy':
+            await answer('DELETE', `/v1/apps/${app}/machines/${machineId()}?force=true`);
+            return { externalId: ctx.resolve('machine', action.subject.id) };
+        case 'secret.set':
+            await answer('POST', `/v1/apps/${app}/secrets`, { values: { [String(f.secret_name)]: f.value } });
+            return { externalId: action.subject.id };
+        default: return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at Fly to write` } };
+    }
+}

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

@@ -0,0 +1,121 @@
+import type { FlyContainerRuntime, FlyContainerSpec, FlyExecResult } from './fly-machines.js';
+export declare const FLY_DOCKER_LABEL = "dev.volter.fly-twin";
+/** MiB of writable storage admission keeps FREE beyond the machine's own need — the DEFAULT of a
+ *  configured mechanism value, not a constant. A World whose host disk is smaller than the
+ *  reserve configures it down (`world-fly serve --storage-reserve-mib N`,
+ *  `FlyDockerRuntimeOptions.storageReserveMiB`); the runtime never lowers its own floor. */
+export declare const DEFAULT_STORAGE_RESERVE_MIB = 2048;
+/** Options of the REAL execution plane. Configuration reaches this runtime the way the plane
+ *  itself does — resolved at the HOST BOUNDARY (cli.ts via fly-runtime-choice.ts) and handed in,
+ *  never read from the process here. */
+export interface FlyDockerRuntimeOptions {
+    /** MiB kept free beyond a machine's own writable-storage need (default 2048). */
+    storageReserveMiB?: number;
+}
+/**
+ * The writable-storage floor for ONE machine: its own need (never below an image pull plus a
+ * writable layer) plus the reserve the host keeps free. Pure arithmetic, so the admission rule is
+ * checkable without a daemon.
+ */
+export declare function writableStorageFloorMiB(memoryMiB: number, reserveMiB?: number): {
+    requiredMiB: number;
+    reserveMiB: number;
+    floorMiB: number;
+};
+/** What the writable-storage probe measured, and the SUBSTRATE it measured it on (named in the
+ *  capacity log so a refusal is diagnosable; the caller's error stays in World vocabulary). */
+export type WritableStorage = {
+    availableMiB: number;
+    substrate: string;
+};
+/**
+ * The host facts the writable-storage probe reads. Injected — the same seam doctrine the
+ * execution plane itself uses — so every branch (host-visible docker root, Colima, OrbStack,
+ * Docker Desktop) is provable OFFLINE against fakes, with no daemon anywhere.
+ */
+export interface StorageProbeHost {
+    readonly platform: string;
+    readonly home: string;
+    /** Does this HOST path exist? */
+    exists(path: string): boolean;
+    /** Free MiB on the host volume holding `path`; undefined when it cannot be read. */
+    freeMiB(path: string): number | undefined;
+    /** Entries of a host directory; [] when unreadable. */
+    entries(path: string): string[];
+    docker(args: string[]): {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+    run(command: string, args: string[], timeoutMs: number): {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    warn(line: string): void;
+}
+/**
+ * How much writable storage the local execution substrate can still take, measured INSIDE that
+ * substrate when the docker root is not host-visible. Honest by construction: every branch either
+ * MEASURES a real filesystem or returns undefined (admission then refuses) — capacity is never
+ * assumed, defaulted or fabricated.
+ */
+export declare function probeWritableStorage(rootDir: string, host?: StorageProbeHost): WritableStorage | undefined;
+/** Is a Docker DAEMON actually reachable (not just the binary present)? */
+export declare function dockerAvailable(): boolean;
+export declare function flyContainerName(machineId: string): string;
+export declare function flyVolumeName(volumeId: string): string;
+export declare class FlyDockerRuntime implements FlyContainerRuntime {
+    #private;
+    readonly kind = "docker";
+    constructor(root?: string, options?: FlyDockerRuntimeOptions);
+    run(spec: FlyContainerSpec): Promise<{
+        containerRef: string;
+        publishedPorts?: Array<{
+            internal: number;
+            host: number;
+        }>;
+    }>;
+    stop(containerRef: string, opts?: {
+        signal?: string;
+        timeoutSeconds?: number;
+    }): Promise<void>;
+    /**
+     * Start a STOPPED machine — by RECREATING the container, never `docker start`.
+     *
+     * Real Fly resets the root filesystem on stop→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). `docker start` resumes the old writable layer,
+     * which would make this twin MORE FORGIVING than the vendor at exactly the point where the
+     * difference bites: an app that writes state outside a volume would pass local rehearsal and
+     * lose that state on the first real stop/start cycle.
+     *
+     * So the old container is removed and a fresh one is run from `spec.image` with the same
+     * env/ports/mounts wiring. `docker rm -v` removes only ANONYMOUS volumes, so the named
+     * `fly-twin-<volume id>` volumes (this twin's mapping of Fly volumes) carry over — mounted
+     * data survives, everything else starts clean, exactly like the vendor. The new container gets
+     * a new handle and new ephemeral loopback ports; both are returned and re-ledgered.
+     */
+    start(containerRef: string, spec: FlyContainerSpec): Promise<{
+        containerRef: string;
+        publishedPorts?: Array<{
+            internal: number;
+            host: number;
+        }>;
+    }>;
+    remove(containerRef: string): Promise<void>;
+    pause(containerRef: string): Promise<void>;
+    unpause(containerRef: string): Promise<void>;
+    signal(containerRef: string, signal: string): Promise<void>;
+    exec(containerRef: string, cmd: string[], opts?: {
+        timeoutSeconds?: number;
+    }): Promise<FlyExecResult>;
+    inspect(containerRef: string): Promise<{
+        running: boolean;
+        exitCode?: number;
+        oomKilled?: boolean;
+    }>;
+    createVolume(volumeId: string): Promise<void>;
+    removeVolume(volumeId: string): Promise<void>;
+    cleanup(): Promise<void>;
+}