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

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-01T09:52:42.927Z
 -->
 
 # @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.
@@ -337,7 +533,11 @@ interface FlyioConfig {
    * creation.
    */
   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`). Defaults to
+   * `iad`; `SandboxConfig.region` overrides it for one recorded project create.
+   * The API Machine's own `FLY_REGION` is never a tenant-placement fallback.
+   */
   region?: string
   /**
    * OCI image every sandbox Machine runs. Must be pullable by Fly — a tag in
@@ -403,6 +603,8 @@ interface FlyioConfig {
   ipAssignmentType?: string
   /** Prefix for the Machine metadata keys this provider owns. Defaults to `molecule-sandbox`. */
   metadataPrefix?: string
+  /** Durable create-attempt ownership. Required for automatic failed-create reconciliation. */
+  createAttemptJournal?: FlyCreateAttemptJournal
   /** Timeout for a single Machines API request, in ms. Defaults to 30000. */
   requestTimeoutMs?: number
   /**
@@ -442,10 +644,6 @@ interface FlyioConfig {
    * 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
 ```
 
@@ -470,7 +668,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 +757,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 +982,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 +1010,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 +1140,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 +1155,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 +1169,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 +1200,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 +1215,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`, {
@@ -1465,24 +1698,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.
+
+```typescript
+function appNameNamespace(prefix: string): {
+  prefix: string
+  hashedPrefix: string
+  searchPrefixes: string[]
+}
+```
 
-Derives a Fly app name for a project.
+#### `appNameForProject(prefix, projectId)`
 
-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.
+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 +1827,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 +2491,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 +2649,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

package/dist/api.d.ts

@@ -43,13 +43,15 @@ export declare class FlyApiError extends Error {
     });
 }
 /** Options for a single Fly API request. */
-export interface FlyRequestOptions {
+export 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;
     /**
@@ -64,6 +66,19 @@ export 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>;
 }
 /**
  * Decides whether a failed attempt is worth repeating.
@@ -147,6 +162,6 @@ export declare class FlyApiClient {
      * @throws {FlyApiError} On a non-2xx status that is not listed in `nullOn`,
      *   or when every retryable attempt is exhausted.
      */
-    request<T>(path: string, options?: FlyRequestOptions): Promise<T | null>;
+    request<T>(path: string, options?: FlyRequestOptions<T>): Promise<T | null>;
 }
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAgBhC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0DAA0D;IAC1D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAQhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAoBjE;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,KAAK,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC/B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC;AAgDD,kFAAkF;AAClF,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7C;;;OAGG;gBACS,OAAO,EAAE,mBAAmB;IASxC;;;;;;;;;;OAUG;IACG,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAiFnF"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -216,9 +216,15 @@ export class FlyApiClient {
         }
         let lastError;
         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
@@ -226,18 +232,23 @@ export class FlyApiClient {
             let status = 0;
             let retryAfter = 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;
@@ -256,6 +267,8 @@ export class FlyApiClient {
                 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
@@ -265,7 +278,15 @@ export class FlyApiClient {
             finally {
                 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);

package/dist/ids.d.ts

@@ -31,18 +31,17 @@ export declare function parseSandboxId(id: string): {
     app: string;
     machineId: string;
 };
+/** The one namespace mapping shared by app naming and fleet discovery. */
+export declare function appNameNamespace(prefix: string): {
+    prefix: string;
+    hashedPrefix: string;
+    searchPrefixes: string[];
+};
 /**
- * Derives a Fly app name for a project.
- *
- * 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.
+ * Derive the collision-free app name for a complete prefix/project identity.
  * @param prefix - Configured app-name prefix.
- * @param projectId - The project id from `SandboxConfig`.
- * @returns A syntactically valid Fly app name.
- * @throws {Error} When `projectId` has no characters usable in a DNS label.
+ * @param projectId - Complete project or deploy identity.
+ * @returns A DNS-safe app name no longer than 63 characters.
  */
 export declare function appNameForProject(prefix: string, projectId: string): string;
 /**

package/dist/ids.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAKjD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAgB7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAqB3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,GACrB,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAiBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAE7D"}
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAKjD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAgB7E;AAWD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG;IAChD,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB,CAUA;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAmB3E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,GACrB,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAiBjD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAE7D"}