@molecule/api-code-sandbox-flyio 1.3.6 → 1.3.9

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-26T04:22:26.020Z
+Generated: 2026-11-04T14:19:55.149Z
 -->
 
 # @molecule/api-code-sandbox-flyio
@@ -16,6 +16,10 @@ SCALE-TO-ZERO: `sleep()` maps to Fly's `suspend`, which snapshots the microVM's
 memory to disk, and a suspended Machine bills for storage only. Waking is a
 resume from that snapshot rather than a cold boot.
 
+`FLY_REGION` is the API Machine's own location and is IGNORED for tenant
+placement. Set the provider's `region` default, or pass one create's
+`SandboxConfig.region` for a project whose placement was recorded at creation.
+
 > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
 > It is written to be read by coding agents as much as by people, and is generated from this
 > package's source — edit `src/index.ts` JSDoc, not this file.
@@ -87,13 +91,15 @@ npm install @molecule/api-code-sandbox-flyio @aws-sdk/client-s3 @aws-sdk/s3-requ
 Options for a single Fly API request.
 
 ```typescript
-interface FlyRequestOptions {
+interface FlyRequestOptions<T = unknown> {
   /** HTTP method. Defaults to `GET`. */
   method?: string
   /** JSON request body. Omitted entirely when undefined. */
   body?: unknown
   /** Per-request timeout in ms. Defaults to the client's configured timeout. */
   timeoutMs?: number
+  /** Cancels in-flight provisioning when the owning lifecycle lock is lost. */
+  signal?: AbortSignal
   /** Max attempts for a retryable failure. Defaults to 4. Pass 1 to disable retries. */
   attempts?: number
   /**
@@ -108,6 +114,19 @@ interface FlyRequestOptions {
    * under exec-burst load, not a real absence, so it is worth repeating.
    */
   retryStatuses?: number[]
+  /**
+   * Restricts retries opted into by `retryStatuses` using the response error.
+   * Return false to surface that response immediately. The client's standard
+   * transport, 429 and 5xx retries are unaffected.
+   */
+  retryWhen?: (error: FlyApiError) => boolean
+  /**
+   * Reconciles a retryable failure before the client backs off or throws.
+   * Returning a value completes the request; `undefined` keeps the normal
+   * retry/exhaustion path. This lets an ambiguous write look for the resource
+   * it may have created without adding a second POST retry loop.
+   */
+  reconcile?: (error: FlyApiError) => Promise<T | undefined>
 }
 ```
 
@@ -176,6 +195,183 @@ interface EgressProbeContext {
 }
 ```
 
+#### `FlyCreateVolumeIntent`
+
+A volume name generated for one attempt, or an existing durable workspace.
+
+```typescript
+interface FlyCreateVolumeIntent {
+  /** Fly's resource ID. Once known, this—not the name—is the ownership key. */
+  id?: string
+  /** The current Fly name, unique for a newly-created attempt volume. */
+  name: string
+  /** Caller-level workspace identity, stable across create attempts. */
+  logicalName?: string
+  /** Once bound, only explicit destruction or a reference-checked failed-create sweep may delete it. */
+  workspace: boolean
+  /** False until an ambiguous create is adopted or definitely rejected. */
+  resolved?: boolean
+  /** Recorded before this attempt's create POST; automatic deletion also requires a resolved Fly ID. */
+  createdByAttemptId?: string
+  /** Recorded when this attempt adopted an existing/listed volume; never automatic-delete authority. */
+  adoptedByAttemptId?: string
+}
+```
+
+#### `FlyCreateAddressIntent`
+
+An address on another Fly app which must be released before forgetting intent.
+
+```typescript
+interface FlyCreateAddressIntent {
+  targetApp: string
+  network: string
+  ip?: string
+  /** True only after Fly returned this allocation to this attempt. */
+  owned: boolean
+  /** False while a lost response leaves allocation ownership unknown. */
+  resolved: boolean
+}
+```
+
+#### `FlyCreateAttempt`
+
+The complete durable responsibility for one create attempt.
+
+```typescript
+interface FlyCreateAttempt {
+  attemptId: string
+  projectId: string
+  appName: string
+  state: FlyCreateAttemptState
+  /** Monotonic fencing token, incremented whenever lifecycle ownership is reacquired. */
+  generation?: number
+  sandboxId?: string
+  /** Fly definitively rejected the Machine POST; an unknown outcome is never marked. */
+  machineCreateFailed?: boolean
+  /**
+   * Durable Machine POST lifecycle. New attempts start at not-started; pending is
+   * written before dispatch. NULL is a legacy unknown, never proof of no POST.
+   */
+  machineCreateOutcome?: 'not-started' | 'pending' | 'rejected' | 'unknown' | 'accepted'
+  /** The exact Machine ID returned by this attempt's accepted POST response, or an observation without delete provenance. */
+  machineId?: string
+  /** Accepted-POST provenance; name, metadata, sandboxId and adoption never supply it. */
+  machineCreatedByAttemptId?: string
+  /** This attempt's app-create intent, recorded before the POST. */
+  appCreatedByAttemptId?: string
+  /** True only when the app POST itself was accepted; a pending/unknown create cannot be deleted. */
+  appCreateResolved?: boolean
+  /** True when explicit destruction identity-validated and adopted a pre-journal Machine. */
+  machineAdopted?: boolean
+  volumes: FlyCreateVolumeIntent[]
+  addresses: FlyCreateAddressIntent[]
+}
+```
+
+#### `FlyCreateAttemptJournal`
+
+Application-supplied durable journal used by create and its reconciler.
+A journal-aware writer that ignores provenance must never run beside this
+contract; {@link assertCreateAllowed} is the durable rollout boundary.
+
+```typescript
+interface FlyCreateAttemptJournal {
+  begin(
+    attempt: Pick<FlyCreateAttempt, 'attemptId' | 'projectId' | 'appName'> & {
+      ownerProjectId?: string
+      /** Legacy adoption persists its observed serving state and identity in the INSERT. */
+      state?: FlyCreateAttemptState
+      sandboxId?: string
+      machineAdopted?: boolean
+    },
+  ): Promise<void>
+  /** Refuse provisioning until pre-journal and provenance-ignoring writers have drained. */
+  assertCreateAllowed(): Promise<void>
+  /** Re-read one attempt, including after a lifecycle lock has been acquired. */
+  get(attemptId: string): Promise<FlyCreateAttempt | null>
+  /** Re-read every durable attempt for an app, including creating/serving attempts. */
+  forApp(appName: string): Promise<FlyCreateAttempt[]>
+  /** Find the durable workspace binding for a logical caller workspace. */
+  findWorkspace(projectId: string, logicalName: string): Promise<FlyCreateVolumeIntent | null>
+  /** Record app-create intent/acceptance, or clear it when the app was adopted. */
+  recordAppProvenance(
+    attemptId: string,
+    generation: number,
+    outcome: 'pending' | 'created' | 'adopted',
+  ): Promise<void>
+  /** Record an intent or transfer a Fly-ID binding to this attempt. */
+  recordVolume(attemptId: string, volume: FlyCreateVolumeIntent): Promise<void>
+  markVolumeWorkspace(attemptId: string, name: string, workspace?: boolean): Promise<void>
+  recordAddress(attemptId: string, address: FlyCreateAddressIntent): Promise<void>
+  markState(attemptId: string, state: FlyCreateAttemptState, sandboxId?: string): Promise<void>
+  /** Record that explicit destruction adopted this pre-journal Machine. */
+  markMachineAdopted(attemptId: string): Promise<void>
+  /** Record POST intent before dispatch and an ambiguous outcome before recovery reads. */
+  recordMachineCreateOutcome(
+    attemptId: string,
+    generation: number,
+    outcome: 'pending' | 'unknown',
+  ): Promise<void>
+  /** Persist a recovered exact ID as observation only, never accepted-POST authority. */
+  recordMachineObservation(attemptId: string, generation: number, machineId: string): Promise<void>
+  /** Record only the exact ID from this generation's accepted Machine POST response. */
+  recordMachineProvenance(attemptId: string, generation: number, machineId: string): Promise<void>
+  /** Record a definitive rejection only while this create generation still owns the attempt. */
+  markMachineCreateFailed(attemptId: string, generation: number): Promise<void>
+  /** Throw unless this generation is still the attempt's durable fencing token. */
+  assertGeneration(attemptId: string, generation: number): Promise<void>
+  /** Atomically retire this exact generation while its lifecycle lock session is live. */
+  retire(attemptId: string, generation: number): Promise<void>
+  /** Re-authorize one destructive request against the retired row on the lock session. */
+  authorizeDestruction(attemptId: string, generation: number): Promise<void>
+  /** Failed/abandoned attempts, plus creating attempts whose updatedAt is at/before cutoff. */
+  reclaimable(cutoff: Date): Promise<FlyCreateAttempt[]>
+  /** Acquire the same lifecycle lock the application uses for create/destroy. */
+  withLock?<T>(
+    attempt: FlyCreateAttempt,
+    body: (signal: AbortSignal, generation: number) => Promise<T>,
+  ): Promise<T>
+  forget(attemptId: string, generation?: number): Promise<void>
+}
+```
+
+#### `FlyCreateReconcileSummary`
+
+Attempts forgotten after completed cleanup, and attempts retained after errors.
+
+```typescript
+interface FlyCreateReconcileSummary {
+  deleted: number
+  failed: number
+}
+```
+
+#### `FlyCreateAttemptProvider`
+
+Fly-specific lifecycle capabilities exposed by the provider.
+
+```typescript
+interface FlyCreateAttemptProvider {
+  /** Explicit retirement is fenced by the caller's live lifecycle lock. */
+  destroy(id: string, signal: AbortSignal): Promise<void>
+  /** Deliberately retire exact recorded resources for one shared-app attempt. */
+  destroyAttempt(attemptId: string, signal: AbortSignal): Promise<void>
+  /** Per-project app retirement is fenced by the caller's live lifecycle lock. */
+  destroyApp(
+    projectId: string,
+    expectedAppName: string | undefined,
+    signal: AbortSignal,
+  ): Promise<void>
+  reconcileCreateAttempts(options?: {
+    now?: number
+    createTimeoutMs?: number
+    /** Restrict a pass to one durable attempt. Every attempt is still locked. */
+    attemptId?: string
+  }): Promise<FlyCreateReconcileSummary>
+}
+```
+
 #### `StoredObject`
 
 One object as this bond needs to see it.
@@ -288,167 +484,95 @@ Every option is also readable from an environment variable (see
 
 ```typescript
 interface FlyioConfig {
-  /**
-   * Fly API token (sent as `Authorization: Bearer <token>`). Falls back to
-   * `FLY_API_TOKEN`, then `FLY_ACCESS_TOKEN`. Required — the provider throws a
-   * named error on the first API call if none is resolvable.
-   */
+  /** Fly API token (sent as `Authorization: Bearer <token>`). */
   apiToken?: string
-  /**
-   * Machines API base URL, INCLUDING the `/v1` path segment. Defaults to
-   * `FLY_API_HOSTNAME` (with `/v1` appended when the value has no path) or
-   * `https://api.machines.dev/v1`. From inside a Fly private network the
-   * documented internal endpoint is `http://_api.internal:4280/v1`.
-   */
+  /** Machines API base URL, INCLUDING the `/v1` path segment. */
   apiUrl?: string
-  /**
-   * Fly organization slug that owns the sandbox apps. Falls back to
-   * `FLY_ORG_SLUG`, then `personal`. Required for app creation and for
-   * {@link FlyioConfig.appPerProject} listing.
-   */
+  /** Fly organization slug that owns the sandbox apps. */
   orgSlug?: string
-  /**
-   * Shared Fly app that holds every sandbox Machine. Only used when
-   * `appPerProject` is `false`. Falls back to `FLY_SANDBOX_APP`.
-   *
-   * A shared app puts every tenant on ONE 6PN private network, where each
-   * sandbox can reach every other sandbox's dev-server ports by private IPv6.
-   * That is the same cross-tenant exposure the Docker bond's `bridge` network
-   * has, so this mode is REFUSED in production.
-   */
+  /** Shared Fly app that holds every sandbox Machine. */
   appName?: string
-  /**
-   * Name prefix for the per-project Fly app when `appPerProject` is `true`
-   * (default). The app is `<appPrefix>-<sanitized projectId>`. Falls back to
-   * `FLY_SANDBOX_APP_PREFIX`, then `mol-sandbox`.
-   */
+  /** Name prefix for the per-project Fly app when `appPerProject` is `true` (default). */
   appPrefix?: string
-  /**
-   * Create one Fly app — on its own custom 6PN private network — per project,
-   * so tenants are network-isolated from each other. Defaults to `true`.
-   * Set `false` (or `FLY_SANDBOX_APP_PER_PROJECT=false`) only for a
-   * single-tenant deployment; it is refused in production.
-   */
+  /** Create one Fly app — on its own custom 6PN private network — per project, so tenants are network-isolated from each other. */
   appPerProject?: boolean
-  /**
-   * Custom 6PN network name for a per-project app. Defaults to the app name, so
-   * every project lands on its own private network. Ignored when
-   * `appPerProject` is `false`. A Fly app's network CANNOT be changed after
-   * creation.
-   */
+  /** Custom 6PN network name for a per-project app. */
   network?: string
-  /** Fly region for Machines and volumes (e.g. `iad`). Falls back to `FLY_REGION`, then `iad`. */
+  /** Default Fly region for Machines and volumes (e.g. `iad`). */
   region?: string
-  /**
-   * OCI image every sandbox Machine runs. Must be pullable by Fly — a tag in
-   * the org's `registry.fly.io` repository or a public registry. A LOCAL
-   * `molecule-sandbox:latest` is not reachable by Fly; push it first. Falls
-   * back to `FLY_SANDBOX_IMAGE`, then `registry.fly.io/molecule-sandbox:latest`.
-   */
+  /** OCI image every sandbox Machine runs. */
   baseImage?: string
-  /** Default vCPU count (`guest.cpus`). Defaults to 1. */
+  /** Default vCPU count (`guest.cpus`). */
   defaultCpu?: number
-  /** Default `guest.cpu_kind` — `shared` or `performance`. Defaults to `shared`. */
+  /** Default `guest.cpu_kind` — `shared` or `performance`. */
   defaultCpuKind?: string
-  /** Default memory in MB (`guest.memory_mb`). Defaults to 1024. */
+  /** Default memory in MB (`guest.memory_mb`). */
   defaultMemoryMB?: number
-  /**
-   * Size in GB of the volume created for a sandbox's `/workspace` when
-   * `SandboxConfig.volumeName` is set. Fly volumes are sized in whole GB, so the
-   * core's `resources.diskMB` is rounded UP to the next GB. Defaults to 10.
-   */
+  /** Size in GB of the volume created for a sandbox's `/workspace` when `SandboxConfig.volumeName` is set. */
   defaultVolumeGB?: number
-  /** Internal port the preview service forwards to (the Vite dev server). Defaults to 5173. */
+  /** Internal port the preview service forwards to (the Vite dev server). */
   previewPort?: number
-  /**
-   * Preview URL template. Placeholders `{app}`, `{machineId}` and `{port}` are
-   * all replaced globally. Defaults to `https://{app}.fly.dev`.
-   *
-   * For a control plane that runs on the SAME Fly 6PN, the private form
-   * `http://{machineId}.vm.{app}.internal:{port}` reaches the Machine with no
-   * public exposure at all — but it does NOT work across custom 6PNs, which is
-   * exactly what `appPerProject` creates. See the module `@remarks`.
-   */
+  /** Preview URL template. */
   previewUrlTemplate?: string
-  /**
-   * Attach a public Fly Proxy service (`80` → http, `443` → tls+http) forwarding
-   * to {@link FlyioConfig.previewPort}. Defaults to `true`. Set `false` for a
-   * fully private sandbox reached only over 6PN/Flycast.
-   */
+  /** Attach a public Fly Proxy service (`80` → http, `443` → tls+http) forwarding to {@link FlyioConfig.previewPort}. */
   publicService?: boolean
-  /**
-   * Fly Proxy idle behaviour for the preview service. Defaults to `'off'` —
-   * never idle the Machine — because the autostop timer counts the PROXY
-   * service's idle time, not the workload's, so a sandbox with nobody looking at
-   * its preview is suspended out from under a build that is still running.
-   * `suspend` is the scale-to-zero mapping (resume from a memory snapshot on the
-   * next request) and `stop` is a full stop with a cold boot on wake; opt into
-   * either deliberately.
-   *
-   * This is the provider's STEADY-STATE policy, reported as
-   * `SandboxProvider.defaultIdleAction`. A caller can override it for one sandbox
-   * with `SandboxConfig.idleAction` and restore this value afterwards with
-   * `Sandbox.setIdleAction` — which is what a production deploy does so its
-   * destination cannot suspend mid-copy.
-   */
+  /** Fly Proxy idle behaviour for the preview service. */
   autostop?: 'off' | 'stop' | 'suspend'
-  /**
-   * Allocate a shared Anycast IPv4 for a newly-created app so `<app>.fly.dev`
-   * serves traffic. Defaults to `false` (opt-in). See the module `@remarks` —
-   * the accepted `type` values for the IP-assignment endpoint are NOT enumerated
-   * in Fly's OpenAPI specification.
-   */
+  /** Allocate a shared Anycast IPv4 for a newly-created app so `<app>.fly.dev` serves traffic. */
   assignSharedIpv4?: boolean
-  /** IP type requested when {@link FlyioConfig.assignSharedIpv4} is on. Defaults to `shared_v4`. */
+  /** IP type requested when {@link FlyioConfig.assignSharedIpv4} is on. */
   ipAssignmentType?: string
-  /** Prefix for the Machine metadata keys this provider owns. Defaults to `molecule-sandbox`. */
+  /** Prefix for the Machine metadata keys this provider owns. */
   metadataPrefix?: string
-  /** Timeout for a single Machines API request, in ms. Defaults to 30000. */
+  /** Durable create-attempt ownership. */
+  createAttemptJournal?: FlyCreateAttemptJournal
+  /** Timeout for a single Machines API request, in ms. */
   requestTimeoutMs?: number
-  /**
-   * TOTAL budget, in seconds, that `create()`/`start()`/`wake()` block waiting
-   * for the Machine to actually reach `started`. Fly's `GET .../wait` blocks
-   * for at most 60 seconds per call, so a larger budget is spent as consecutive
-   * wait rounds. Defaults to 180 — a Machine whose image is not yet cached on
-   * its host (every first boot after an image push) pulls it before starting,
-   * and that alone can exceed a single 60 s round.
-   *
-   * Without this wait, `start()` resolves the moment Fly ACCEPTS the request,
-   * and the caller's very next `exec` hits a Machine that is not running yet.
-   */
+  /** TOTAL budget, in seconds, that `create()`/`start()`/`wake()` block waiting for the Machine to actually reach `started`. */
   startTimeoutSeconds?: number
-  /**
-   * Ports a sandbox Machine may open outbound connections on. Setting this makes
-   * the provider apply a Fly **network policy** to every app it provisions;
-   * leaving it unset applies no policy at all, and `verifyEgress()` will then
-   * observe (correctly) that egress is `open`. Falls back to
-   * `FLY_SANDBOX_EGRESS_ALLOWED_PORTS` (`tcp:3128,udp:53`).
-   *
-   * Read {@link https://fly.io/docs/machines/guides-examples/network-policies/}
-   * before choosing a value, because the mechanism is narrower than it looks:
-   * rules match protocol and port ONLY — no host, no CIDR, no ranges — so this
-   * can never be a host allowlist. `tcp:443` lets a sandbox reach EVERY host on
-   * the internet that listens on 443. To get a host allowlist, allow only the
-   * port of an egress proxy you control and route sandbox traffic through it.
-   *
-   * An empty array is rejected rather than treated as "deny all": Fly documents
-   * the deny default as a consequence of an `allow` rule existing, and says
-   * nothing about a rule with no ports.
-   */
+  /** Ports a sandbox Machine may open outbound connections on. */
   egressAllowedPorts?: FlyNetworkPolicyPort[]
-  /** Name of the egress policy this provider owns on each app. Defaults to `molecule-sandbox-egress`. */
+  /** Name of the egress policy this provider owns on each app. */
   egressPolicyName?: string
-  /**
-   * Apps every sandbox must be able to reach ACROSS its per-project 6PN — the
-   * tenant Postgres cluster and the control plane's egress proxy. For each one,
-   * this provider allocates a **Flycast** private address into the project's own
-   * network when the project's app is created, and releases it on `destroy()`.
-   * Falls back to `FLY_SANDBOX_PRIVATE_SERVICES` (`<app>:<port>` pairs).
-   *
-   * Without this, a project with a database DOES NOT WORK on Fly: per-project
-// … truncated — the full declaration is in node_modules/@molecule/api-code-sandbox-flyio/dist/types.d.ts
+  /** Apps every sandbox must be able to reach ACROSS its per-project 6PN — the tenant Postgres cluster and the control plane's egress proxy. */
+  privateServices?: FlyPrivateService[]
+  /** Per-create regional overrides for {@link FlyioConfig.privateServices}. */
+  privateServicesByRegion?: Record<string, FlyPrivateService[]>
+  /** `type` sent to `POST /apps/{app}/ip_assignments` when allocating a Flycast address. */
+  privateIpAssignmentType?: string
+  /** Literal `ip:port` targets `verifyEgress()` attempts raw TCP connections to. */
+  egressProbeTargets?: string[]
+  /** Per-connection timeout for the egress probe, in ms. */
+  egressProbeTimeoutMs?: number
+  /** Image the throwaway `verifyEgress()` probe Machine runs. */
+  egressProbeImage?: string
+  /** Bucket holding sandbox templates. */
+  templateBucket?: string
+  /** S3 endpoint for {@link FlyioConfig.templateBucket}, e.g. Tigris's `https://t3.storage.dev`. */
+  templateEndpoint?: string
+  /** Region used to sign template-store requests. */
+  templateRegion?: string
+  /** Access key for the template store. */
+  templateAccessKeyId?: string
+  /** Secret key for the template store. */
+  templateSecretAccessKey?: string
+  /** Session token for temporary template-store credentials. */
+  templateSessionToken?: string
+  /** Key prefix every template object lives under. */
+  templatePrefix?: string
+  /** Address the template bucket path-style (`https://endpoint/bucket/key`) instead of virtual-host style. */
+  templateForcePathStyle?: boolean
+  /** Lifetime of the presigned capture/restore URL handed to a sandbox, in seconds. */
+  templateUrlExpirySeconds?: number
+  /** Wall-clock budget for one capture or restore transfer, in ms. */
+  templateTransferTimeoutMs?: number
+  /** Largest template archive this provider will store, in bytes. */
+  templateMaxArchiveBytes?: number
+}
 ```
 
+_(Member comments are shortened to their first sentence to fit; the full declaration is in `node_modules/@molecule/api-code-sandbox-flyio/dist/types.d.ts`.)_
+
 #### `ProcessEnv`
 
 Environment variables the Fly.io sandbox provider reads. Every one is
@@ -470,7 +594,11 @@ interface ProcessEnv {
   FLY_SANDBOX_APP_PREFIX?: string
   /** `false` disables per-project apps (refused in production). */
   FLY_SANDBOX_APP_PER_PROJECT?: string
-  /** Fly region for Machines and volumes (default `iad`). */
+  /**
+   * The API Machine's own region, not a tenant-placement setting; ignored.
+   *
+   * @deprecated Use `FlyioConfig.region` or one create's `SandboxConfig.region`.
+   */
   FLY_REGION?: string
   /** OCI image for sandbox Machines. */
   FLY_SANDBOX_IMAGE?: string
@@ -555,16 +683,20 @@ interface FlyPrivateService {
 An IP assignment, as returned by `POST`/`GET /v1/apps/{app}/ip_assignments`
 (`IPAssignment` in https://docs.machines.dev/openapi.json).
 
-Note what is NOT here: the assignment's **network**. Fly's own schema is
-`{created_at, ip, region, service_name, shared}`, so a listing cannot tell you
-which 6PN a private address serves — which is why this provider records the
-addresses it allocated in the sandbox Machine's metadata instead of
-rediscovering them.
+Current Fly schema includes the assignment's network identity, allowing a
+lost allocation response to be resolved by target app and 6PN. Durable
+records remain authoritative for what this provider must release.
 
 ```typescript
 interface FlyIpAssignment {
   /** The allocated address. Required for a later `DELETE .../ip_assignments/{ip}`. */
   ip?: string
+  /**
+   * Private 6PN identity. GET returns `{name, org_slug}` (null for non-Flycast
+   * assignments); only the POST request body uses separate string fields.
+   * The string form remains accepted for older cached/test responses.
+   */
+  network?: string | { name?: string | null; org_slug?: string | null } | null
   /** Region the address was allocated in, when Fly reports one. */
   region?: string
   /** Service the address is bound to, when the assignment names one. */
@@ -776,6 +908,8 @@ interface FlyVolume {
   size_gb?: number
   region?: string
   attached_machine_id?: string
+  /** RFC 3339 creation time; required as proof before an old attempt is reaped. */
+  created_at?: string
 }
 ```
 
@@ -802,6 +936,14 @@ Runs one exec call against a Machine. Injected so this module stays transport-fr
 type RawExec = (command: string[], timeoutSeconds: number) => Promise<FlyExecResponse>
 ```
 
+#### `FlyCreateAttemptState`
+
+Durable lifecycle state; only failed/abandoned attempts are automatically reclaimed.
+
+```typescript
+type FlyCreateAttemptState = 'creating' | 'serving' | 'failed' | 'abandoned'
+```
+
 #### `FlyMachineState`
 
 A Fly Machine state, as documented at https://fly.io/docs/machines/machine-states/.
@@ -924,7 +1066,7 @@ class FlyApiClient {
    * @throws {FlyApiError} On a non-2xx status that is not listed in `nullOn`,
    *   or when every retryable attempt is exhausted.
    */
-  async request<T>(path: string, options: FlyRequestOptions = {}): Promise<T | null> {
+  async request<T>(path: string, options: FlyRequestOptions<T> = {}): Promise<T | null> {
     const method = options.method ?? 'GET'
     const attempts = options.attempts ?? DEFAULT_ATTEMPTS
     const token = this.token()
@@ -939,9 +1081,13 @@ class FlyApiClient {
 
     let lastError: FlyApiError | undefined
     for (let attempt = 1; attempt <= attempts; attempt++) {
+      if (options.signal?.aborted) throw options.signal.reason
       // Pace EVERY network call (including retries) through the process-wide
       // limiter so a boot's burst of exec calls never trips Fly's account 429.
       await paceFlyRequest(this.sleep)
+      // Pacing is cancellable too: ownership protection starts only when this
+      // request really enters fetch, never while it is still waiting for a slot.
+      if (options.signal?.aborted) throw options.signal.reason
       const controller = new AbortController()
       const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? this.timeoutMs)
       // Initialized to 0 ("no answer received"), which is the value that
@@ -949,18 +1095,22 @@ class FlyApiClient {
       let status = 0
       let retryAfter: string | null = null
       try {
-        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        const pendingResponse = this.fetchImpl(`${this.baseUrl}${path}`, {
           method,
           headers: {
             Authorization: `Bearer ${token}`,
             ...(options.body === undefined ? {} : { 'Content-Type': 'application/json' }),
           },
           ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
-          signal: controller.signal,
+          signal: options.signal
+            ? AbortSignal.any([controller.signal, options.signal])
+            : controller.signal,
         })
+        const response = await pendingResponse
         status = response.status
         retryAfter = response.headers?.get?.('retry-after') ?? null
         const text = await response.text()
+        if (options.signal?.aborted) throw options.signal.reason
 
         if (status >= 200 && status < 300) {
           if (!text.trim()) return null
@@ -976,6 +1126,7 @@ class FlyApiClient {
         if (options.nullOn?.includes(status)) return null
         lastError = new FlyApiError(method, path, status, text.slice(0, 500))
       } catch (error) {
+        if (options.signal?.aborted) throw options.signal.reason
         if (error instanceof FlyApiError) throw error
         // Transport-level failure (abort/timeout, DNS, connection reset) — no
         // status was ever received, so it is modelled as status 0 and retried.
@@ -990,8 +1141,16 @@ class FlyApiClient {
         clearTimeout(timer)
       }
 
-      const retryable =
-        isRetryableStatus(status) || (options.retryStatuses?.includes(status) ?? false)
+      const extraRetry = Boolean(
+        options.retryStatuses?.includes(status) &&
+        lastError &&
+        (options.retryWhen?.(lastError) ?? true),
+      )
+      const retryable = isRetryableStatus(status) || extraRetry
+      if (retryable && lastError && options.reconcile) {
+        const recovered = await options.reconcile(lastError)
+        if (recovered !== undefined) return recovered
+      }
       if (!retryable || attempt === attempts) break
       const delay = retryDelayMs(attempt, retryAfter)
       logger.warn(`Fly API transient failure on ${method} ${path} — retrying`, {
@@ -1372,8 +1531,15 @@ its own 6PN: under a policy allowing only `udp:53`, `molecule-pg-tenant.flycast`
 and `molecule-api.flycast` both RESOLVED and every TCP connect to them was
 dropped; re-applying the policy with `tcp:443` opened 443 and nothing else.
 Fly's sentence is about INGRESS — a Machine's egress TOWARD a Flycast address
+is filtered like any other. Drop a declared service's port and every database
+connection in the fleet goes with it.
 
-_(description truncated — read the full text in `node_modules/@molecule/api-code-sandbox-flyio/dist/flycast.d.ts`.)_
+The cost of each derived port, stated plainly because a Fly policy has no
+destination field of any kind (also measured — see the `egress.ts` module
+description): the port is opened to EVERY host on the internet, not only to
+the private service it was derived for. That residual cannot be closed at this
+layer; it is named in `verifyEgress()`'s verdict and in
+`docs/sandbox-egress-enforcement.md`.
 
 ```typescript
 function mergeEgressPorts(
@@ -1465,24 +1631,30 @@ function parseSandboxId(id: string): { app: string; machineId: string }
 
 **Returns:** The app name and Machine id.
 
-#### `appNameForProject(prefix, projectId)`
+#### `appNameNamespace(prefix)`
+
+The one namespace mapping shared by app naming and fleet discovery.
 
-Derives a Fly app name for a project.
+```typescript
+function appNameNamespace(prefix: string): {
+  prefix: string
+  hashedPrefix: string
+  searchPrefixes: string[]
+}
+```
 
-Fly app names are globally unique DNS labels: lowercase alphanumerics and
-hyphens, no leading/trailing hyphen, at most 63 characters (they become
-`<app>.fly.dev`). Project ids are uuids, so `<prefix>-<uuid>` fits with room
-to spare; longer ids are truncated rather than rejected, and the trailing
-hyphen that truncation can leave is stripped.
+#### `appNameForProject(prefix, projectId)`
+
+Derive the collision-free app name for a complete prefix/project identity.
 
 ```typescript
 function appNameForProject(prefix: string, projectId: string): string
 ```
 
 - `prefix` — Configured app-name prefix.
-- `projectId` — The project id from `SandboxConfig`.
+- `projectId` — Complete project or deploy identity.
 
-**Returns:** A syntactically valid Fly app name.
+**Returns:** A DNS-safe app name no longer than 63 characters.
 
 #### `mapMachineState(state)`
 
@@ -1588,7 +1760,7 @@ function createProvider(
   config?: FlyioConfig,
   client?: FlyApiClient,
   store?: ObjectStore | null,
-): SandboxProvider
+): SandboxProvider & FlyCreateAttemptProvider
 ```
 
 - `config` — Optional Fly configuration: API token/URL, org slug, app naming and isolation mode, region, base image, guest sizing, preview service, and the preview URL template. Every field has an env fallback.
@@ -2252,6 +2424,21 @@ refused, a leading `/` stripped, a write through a symlink refused, and
 setuid/setgid dropped by `--no-same-permissions` — were verified by running
 GNU tar 1.35 against crafted archives rather than inferred from its manual.
 
+**Lifecycle ownership.** Create NEVER deletes a Machine, volume, app or
+address. Configure `createAttemptJournal` to record every intended resource
+before its Fly write. Workspace ownership is durable immediately: an
+ambiguous create retains it for a later create or an explicit sweep, never
+infers deletion from a missing listing or an uncertain dispatch. The
+reconciler settles only retired attempt generations and skips serving
+Machines, attached volumes and bound workspaces. The one automatic exception
+is a durably recorded, definitive Machine-create rejection: under the same
+lifecycle lock, a fresh listing must show no Machine reference (and no
+Machines or untracked volumes in a per-project app) before the fenced sweep
+deletes the failed attempt's volume. The empty app remains KEEP until
+deliberate retirement through `destroyApp()`. Ambiguous outcomes and
+referenced resources stay KEPT and are reported. Deployed callers must
+serialize lifecycle operations per app through their lifecycle-lock adapter.
+
 **Absence vs failure: `get()` only answers `null` for a REAL absence.**
 `get()` (and each read shaped like it — `list()`, `find()`, `getTemplate()`)
 reserves `null`/`[]` for a positive not-found answer — Fly answered 404 for
@@ -2395,10 +2582,19 @@ deliberately NOT implemented: they receive only a name, while a Fly volume
 needs an app, a region and a size, and a volume created in the wrong app can
 never be mounted. So passing `SandboxConfig.volumeName` provisions the volume
 inside the project's app, mounted at `/workspace`; `resources.diskMB` is
-rounded UP to whole GB. Fly documents that "a volume can be attached to only
-one Machine", which matches one sandbox per project. Fly does not document the
-legal character set for volume names, so names are conservatively reduced to
-`[A-Za-z0-9_]` — an assumption, flagged as such.
+rounded UP to whole GB. Creation sends the Machine's exact guest as Fly's
+`compute` placement hint, so Fly can choose a volume host that can run that
+Machine. If Machine creation still answers `412 volume_placement_capacity`,
+the provider preserves the volume and propagates the error for the caller's
+bounded retry, which adopts it by its durable Fly ID. Create itself never
+deletes its app or volume; only explicit retirement or the reference-checked
+definitive-failure sweep above can do so. Volume creates retain transport and
+429 backoff. After an ambiguous failure, bounded lookups by name adopt a
+volume whose response was lost before any POST replay, preventing duplicates.
+Fly documents that "a volume can be attached to only one Machine", which
+matches one sandbox per project. Fly does
+not document the legal character set for volume names, so names are
+conservatively reduced to `[A-Za-z0-9_]` — an assumption, flagged as such.
 
 **Warm start: templates are tar archives in object storage.** Fly cannot
 `commit` a running Machine — it PULLS images from a registry — and the