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

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"}

package/dist/ids.js

@@ -11,6 +11,7 @@
  *
  * @module
  */
+import { createHash } from 'node:crypto';
 import { t } from '@molecule/api-i18n';
 /** Separator between the app name and the Machine id in a composite sandbox id. */
 const ID_SEPARATOR = ':';
@@ -41,33 +42,46 @@ export function parseSandboxId(id) {
     }
     return { app: id.slice(0, index), machineId: id.slice(index + 1) };
 }
-/**
- * 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.
- * @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.
- */
-export function appNameForProject(prefix, projectId) {
-    const sanitize = (value) => value
+/** Normalize one prefix/project component for a Fly DNS label. */
+function sanitizeAppNamePart(value) {
+    return value
         .toLowerCase()
         .replace(/[^a-z0-9-]+/g, '-')
         .replace(/-+/g, '-')
         .replace(/^-|-$/g, '');
-    const safePrefix = sanitize(prefix) || 'mol-sandbox';
-    const safeProject = sanitize(projectId);
+}
+/** The one namespace mapping shared by app naming and fleet discovery. */
+export function appNameNamespace(prefix) {
+    const safePrefix = sanitizeAppNamePart(prefix) || 'mol-sandbox';
+    // appNameForProject uses a 20-character digest, leaving 42 characters plus
+    // the separating hyphen inside Fly's 63-character DNS-label limit.
+    const hashedPrefix = safePrefix.slice(0, 42).replace(/-+$/, '');
+    return {
+        prefix: safePrefix,
+        hashedPrefix,
+        searchPrefixes: [...new Set([`${safePrefix}-`, `${hashedPrefix}-`])],
+    };
+}
+/**
+ * Derive the collision-free app name for a complete prefix/project identity.
+ * @param prefix - Configured app-name prefix.
+ * @param projectId - Complete project or deploy identity.
+ * @returns A DNS-safe app name no longer than 63 characters.
+ */
+export function appNameForProject(prefix, projectId) {
+    const namespace = appNameNamespace(prefix);
+    const safePrefix = namespace.prefix;
+    const safeProject = sanitizeAppNamePart(projectId);
     if (!safeProject) {
         throw new Error(t('codeSandbox.flyio.error.badProjectId', { projectId }, {
             defaultValue: `Cannot derive a Fly app name from projectId "${projectId}" — no DNS-safe characters.`,
         }));
     }
-    return `${safePrefix}-${safeProject}`.slice(0, 63).replace(/-+$/, '');
+    const readable = `${safePrefix}-${safeProject}`;
+    if (readable.length <= 63)
+        return readable;
+    const digest = createHash('sha256').update(`${prefix}\0${projectId}`).digest('hex').slice(0, 20);
+    return `${namespace.hashedPrefix}-${digest}`;
 }
 /**
  * Maps a Fly Machine state onto the core `Sandbox['status']` union.

package/dist/index.d.ts

@@ -7,6 +7,10 @@
  * 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.
+ *
  * @example
  * ```typescript
  * import { bond } from '@molecule/api-bond'
@@ -86,6 +90,21 @@
  * 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
@@ -229,10 +248,19 @@
  * 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
@@ -360,6 +388,7 @@ export * from './egress.js';
 export * from './exec.js';
 export * from './flycast.js';
 export * from './ids.js';
+export * from './lifecycle.js';
 export * from './provider.js';
 export * from './storage.js';
 export * from './templates.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmWG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+XG;AAEH,cAAc,UAAU,CAAA;AACxB,cAAc,oBAAoB,CAAA;AAClC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAMjE;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,eAUrB,CAAA"}

package/dist/index.js

@@ -7,6 +7,10 @@
  * 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.
+ *
  * @example
  * ```typescript
  * import { bond } from '@molecule/api-bond'
@@ -86,6 +90,21 @@
  * 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
@@ -229,10 +248,19 @@
  * 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
@@ -360,6 +388,7 @@ export * from './egress.js';
 export * from './exec.js';
 export * from './flycast.js';
 export * from './ids.js';
+export * from './lifecycle.js';
 export * from './provider.js';
 export * from './storage.js';
 export * from './templates.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Durable ownership records for Fly create attempts.
+ *
+ * The bond owns provisioning and reconciliation; the application owns durable
+ * storage. Every write is recorded before Fly is called, so a lost response is
+ * still represented by an attempt that a later reconciler can settle.
+ *
+ * Rollout rule: a journal-aware writer that ignores provenance must never run
+ * beside this code. Pre-journal providers that delete listed Machines are also
+ * unsafe beside it; durable journals fence new creates until those writers drain.
+ *
+ * @module
+ */
+/** Durable lifecycle state; only failed/abandoned attempts are automatically reclaimed. */
+export type FlyCreateAttemptState = 'creating' | 'serving' | 'failed' | 'abandoned';
+/** A volume name generated for one attempt, or an existing durable workspace. */
+export 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;
+}
+/** An address on another Fly app which must be released before forgetting intent. */
+export 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;
+}
+/** The complete durable responsibility for one create attempt. */
+export 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[];
+}
+/**
+ * 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.
+ */
+export 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>;
+}
+/** Attempts forgotten after completed cleanup, and attempts retained after errors. */
+export interface FlyCreateReconcileSummary {
+    deleted: number;
+    failed: number;
+}
+/** Fly-specific lifecycle capabilities exposed by the provider. */
+export 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>;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle.js

@@ -0,0 +1,14 @@
+/**
+ * Durable ownership records for Fly create attempts.
+ *
+ * The bond owns provisioning and reconciliation; the application owns durable
+ * storage. Every write is recorded before Fly is called, so a lost response is
+ * still represented by an attempt that a later reconciler can settle.
+ *
+ * Rollout rule: a journal-aware writer that ignores provenance must never run
+ * beside this code. Pre-journal providers that delete listed Machines are also
+ * unsafe beside it; durable journals fence new creates until those writers drain.
+ *
+ * @module
+ */
+export {};

package/dist/provider.d.ts

@@ -8,6 +8,7 @@
  */
 import type { SandboxProvider } from '@molecule/api-code-sandbox';
 import { FlyApiClient } from './api.js';
+import type { FlyCreateAttemptProvider } from './lifecycle.js';
 import { type ObjectStore } from './storage.js';
 import type { FlyioConfig } from './types.js';
 /**
@@ -64,5 +65,5 @@ export declare function isMachineWarmingUp(state: string | null | undefined): bo
  *   template settings (or their env fallbacks) on first use when omitted.
  * @returns A `SandboxProvider` backed by Fly Machines.
  */
-export declare function createProvider(config?: FlyioConfig, client?: FlyApiClient, store?: ObjectStore | null): SandboxProvider;
+export declare function createProvider(config?: FlyioConfig, client?: FlyApiClient, store?: ObjectStore | null): SandboxProvider & FlyCreateAttemptProvider;
 //# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAaV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EAAE,YAAY,EAAgC,MAAM,UAAU,CAAA;AAwBrE,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAkBnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E;AAwzFD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,CAEjB"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAaV,eAAe,EAGhB,MAAM,4BAA4B,CAAA;AAGnC,OAAO,EACL,YAAY,EAKb,MAAM,UAAU,CAAA;AA8BjB,OAAO,KAAK,EAEV,wBAAwB,EAEzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAEhG,OAAO,KAAK,EAIV,WAAW,EAUZ,MAAM,YAAY,CAAA;AAyBnB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAIjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E;AAgyID;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,CAAC,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,YAAY,EACrB,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,GACzB,eAAe,GAAG,wBAAwB,CAE5C"}