@volter/twin-fly 0.1.0

package/src/fly-conformance.ts

@@ -0,0 +1,168 @@
+// 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.ts';
+
+export type FlyConformanceReport = {
+  ok: boolean;
+  endpointsChecked: number;
+  endpointsProbed: number;
+  resourceTypesChecked: number;
+  violations: string[];
+};
+
+type Probe = {
+  method: string;
+  /** A literal path, or a thunk resolved after seeding (fixture ids are minted by seed). */
+  path: string | (() => string);
+  body?: unknown;
+  headers?: Record<string, string> | (() => Record<string, string>);
+  /** The status(es) a WORKING handler answers with. */
+  status: number[];
+  /** What a working handler's body must look like. Omitted only for the empty-body statuses. */
+  expect?: (body: unknown) => boolean;
+};
+
+const isObject = (b: unknown): b is Record<string, unknown> => !!b && typeof b === 'object' && !Array.isArray(b);
+const hasKeys = (...keys: string[]) => (b: unknown) => 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: Record<string, Probe> = {
+  '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 as Record<string, unknown>).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 as Record<string, unknown>).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 as string).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 as Record<string, unknown>).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 as Record<string, unknown>).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 as string).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 as Record<string, unknown>).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] as Record<string, unknown>).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(): Promise<FlyConformanceReport> {
+  const snapshot = flyTwinSnapshot();
+  const violations: string[] = [];
+  const root = mkdtempSync(join(tmpdir(), 'fly-conformance-'));
+  const at = '2026-02-01T00:00:00.000Z';
+  const call = (method: string, path: string, body?: unknown, headers?: Record<string, string>) =>
+    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 as Record<string, unknown>).id);
+    const m2 = await call('POST', `/v1/apps/${APP}/machines`, { config: { image: 'nginx:alpine' }, skip_launch: true });
+    fx.stoppedMachineId = String((m2.body as Record<string, unknown>).id);
+    const v = await call('POST', `/v1/apps/${APP}/volumes`, { name: 'probe_vol', size_gb: 2 });
+    fx.volumeId = String((v.body as Record<string, unknown>).id);
+    const doomed = await call('POST', `/v1/apps/${APP}/volumes`, { name: 'probe_vol_doomed', size_gb: 1 });
+    fx.doomedVolumeId = String((doomed.body as Record<string, unknown>).id);
+    const lease = await call('POST', `/v1/apps/${APP}/machines/${fx.machineId}/lease`, { ttl: 3600 });
+    fx.leaseNonce = String(((lease.body as Record<string, unknown>).data as Record<string, unknown>).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/src/fly-connector.ts

@@ -0,0 +1,278 @@
+// 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 type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { FlyBudget, FlyBudgetError, flyCallWeight, type FlyBudgetOptions } from './fly-budget.ts';
+
+const SERVICE = 'fly';
+
+/**
+ * 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 function liveFlyExecute(
+  token: string,
+  base = 'https://api.machines.dev',
+  opts: LiveFlyOptions = {},
+): FlyExecute {
+  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: Record<string, string> = { Authorization: `Bearer ${token}` };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { 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: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { 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: unknown = {};
+    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: string, res: { status: number; body: any }): never {
+  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: string, a: Record<string, unknown>): SyncResource {
+  return {
+    type: 'app',
+    id: String(a.name ?? a.id),
+    fields: {
+      org_slug: orgSlug,
+      org_name: (a.organization as Record<string, unknown> | undefined)?.name ?? orgSlug,
+      network: a.network ?? 'default',
+      internal_numeric_id: a.internal_numeric_id ?? null,
+      status: a.status ?? 'pending',
+    },
+  };
+}
+
+export function mapMachine(appName: string, m: Record<string, unknown>): SyncResource {
+  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 as unknown[])].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: string, v: Record<string, unknown>): SyncResource {
+  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 as string | null) ?? null,
+      created_at: v.created_at ?? null,
+      snapshots: [],
+    },
+  };
+}
+
+// ── PULL ──────────────────────────────────────────────────────────────────────────────────────
+export async function pullFlyApps(execute: FlyExecute, orgSlug: string): Promise<SyncResource[]> {
+  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 as Record<string, unknown>[]) : [];
+  // 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: SyncResource[] = [];
+  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 as Record<string, unknown>) }));
+  }
+  return out;
+}
+
+export async function pullFlyMachines(execute: FlyExecute, appName: string): Promise<SyncResource[]> {
+  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 as Record<string, unknown>[]) : [];
+  return machines.map((m) => mapMachine(appName, m));
+}
+
+export async function pullFlyVolumes(execute: FlyExecute, appName: string): Promise<SyncResource[]> {
+  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 as Record<string, unknown>[]) : [];
+  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: FlyExecute,
+  opts: { root?: string; occurredAt?: string; orgSlug?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const orgSlug = opts.orgSlug ?? 'personal';
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const apps = await pullFlyApps(execute, orgSlug);
+  const nested: SyncResource[] = [];
+  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: RemoteExecute): FlyExecute {
+  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: unknown = {};
+    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: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string; orgSlug?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  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: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  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: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: Record<string, unknown>): Promise<Record<string, unknown>> => {
+    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 ?? {}) as Record<string, unknown>;
+  };
+  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 ?? {}) as Record<string, unknown>) };
+      if (Array.isArray(config.mounts)) config.mounts = (config.mounts as Array<Record<string, unknown>>).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` } };
+  }
+}