bios-sdk 0.1.1-dev.10 → 0.1.1-dev.16

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BiOSConfig, ApiErrorBody } from './types.js';
+import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement } from './types.js';
 /**
  * Typed error thrown by every SDK method when the API returns a non-2xx status.
  *
@@ -12,6 +12,22 @@ import type { BiOSConfig, ApiErrorBody } from './types.js';
  *   }
  * }
  * ```
+ *
+ * Availability rejections are self-recoverable: when the selected GPU is no
+ * longer bookable at submit time the API answers 409 with a machine code and
+ * the currently bookable alternatives, and the SDK surfaces them typed:
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.training.create({ ...req, gpu_type: 'A100_80GB' });
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.code === 'SELECTED_GPU_UNAVAILABLE') {
+ *     const next = err.availableGpus?.[0];
+ *     if (next) await client.training.create({ ...req, gpu_type: next.gpu_type });
+ *   }
+ * }
+ * ```
  */
 export declare class ApiError extends Error {
     /** HTTP status code (e.g. 401, 404, 500). */
@@ -20,8 +36,48 @@ export declare class ApiError extends Error {
     readonly code: string | undefined;
     /** Server-assigned request ID for support / debugging. */
     readonly requestId: string | undefined;
+    /**
+     * The full parsed error response body. Availability rejections carry
+     * structured recovery data here (`available_gpus`, `checked_at`).
+     */
+    readonly body: ApiErrorBody;
+    /**
+     * Bookable-now GPU alternatives on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE); undefined otherwise.
+     * Every entry fit the requested model when `checkedAt` was stamped —
+     * resubmit with one of these and nothing else changed.
+     */
+    readonly availableGpus: AvailableGpuAlternative[] | undefined;
+    /** Availability snapshot time behind an availability rejection. */
+    readonly checkedAt: string | undefined;
     constructor(status: number, body: ApiErrorBody);
 }
+/**
+ * Typed 409 for the standard CAPACITY_UNAVAILABLE contract (ONE code family
+ * across training and inference). Carries the rejection class (`reason`), the
+ * explicit server-computed `minimumRequirement` (min_gpus / valid_counts —
+ * never pick below them), and the canonical bookable-now alternatives via
+ * {@link ApiError.availableGpus}. Instanceof-compatible with ApiError so
+ * existing handlers keep working.
+ */
+export declare class CapacityUnavailableError extends ApiError {
+    /** insufficient_stock | below_model_minimum | invalid_gpu_count | model_too_large. */
+    readonly reason: string | undefined;
+    /** The explicit minimum block for the model (selected type + per-type table). */
+    readonly minimumRequirement: CapacityMinimumRequirement | undefined;
+    /** The selection the rejection was about. */
+    readonly selected: ApiErrorBody['selected'];
+    /** Whether the capacity queue may be joined instead. */
+    readonly queueEligible: boolean;
+    constructor(status: number, body: ApiErrorBody);
+}
+/**
+ * Map a non-2xx body to the most specific typed error. The service is the
+ * authority: a CAPACITY_UNAVAILABLE code becomes {@link CapacityUnavailableError}
+ * so callers read `.availableGpus`/`.minimumRequirement` without string
+ * matching. @internal
+ */
+export declare function buildApiError(status: number, body: ApiErrorBody): ApiError;
 /** Default API key from `BIOS_API_KEY` when the config omits one. @internal */
 export declare function envApiKey(): string | undefined;
 /** Default base URL from `BIOS_BASE_URL` when the config omits one. @internal */

package/dist/client.js

@@ -15,6 +15,22 @@ import { VERSION } from './index.js';
  *   }
  * }
  * ```
+ *
+ * Availability rejections are self-recoverable: when the selected GPU is no
+ * longer bookable at submit time the API answers 409 with a machine code and
+ * the currently bookable alternatives, and the SDK surfaces them typed:
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.training.create({ ...req, gpu_type: 'A100_80GB' });
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.code === 'SELECTED_GPU_UNAVAILABLE') {
+ *     const next = err.availableGpus?.[0];
+ *     if (next) await client.training.create({ ...req, gpu_type: next.gpu_type });
+ *   }
+ * }
+ * ```
  */
 export class ApiError extends Error {
     /** HTTP status code (e.g. 401, 404, 500). */
@@ -23,6 +39,20 @@ export class ApiError extends Error {
     code;
     /** Server-assigned request ID for support / debugging. */
     requestId;
+    /**
+     * The full parsed error response body. Availability rejections carry
+     * structured recovery data here (`available_gpus`, `checked_at`).
+     */
+    body;
+    /**
+     * Bookable-now GPU alternatives on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE); undefined otherwise.
+     * Every entry fit the requested model when `checkedAt` was stamped —
+     * resubmit with one of these and nothing else changed.
+     */
+    availableGpus;
+    /** Availability snapshot time behind an availability rejection. */
+    checkedAt;
     constructor(status, body) {
         const err = body.error;
         const nested = typeof err === 'object' && err !== null ? err : null;
@@ -36,7 +66,65 @@ export class ApiError extends Error {
         this.status = status;
         this.code = (nested ? String(nested.code || '') : body.code) || undefined;
         this.requestId = body.request_id;
+        this.body = body;
+        const flat = nestedErrorBody(body);
+        const alts = flat.available_gpus ?? flat.available_alternatives;
+        this.availableGpus = Array.isArray(alts) && alts.length > 0 ? alts : undefined;
+        this.checkedAt = flat.checked_at;
+    }
+}
+/**
+ * Flatten the standard `{ error: { ... } }` envelope over the legacy top-level
+ * fields so structured capacity data is found in either shape. @internal
+ */
+function nestedErrorBody(body) {
+    const err = body.error;
+    if (typeof err === 'object' && err !== null) {
+        return { ...body, ...err };
+    }
+    return body;
+}
+/**
+ * Typed 409 for the standard CAPACITY_UNAVAILABLE contract (ONE code family
+ * across training and inference). Carries the rejection class (`reason`), the
+ * explicit server-computed `minimumRequirement` (min_gpus / valid_counts —
+ * never pick below them), and the canonical bookable-now alternatives via
+ * {@link ApiError.availableGpus}. Instanceof-compatible with ApiError so
+ * existing handlers keep working.
+ */
+export class CapacityUnavailableError extends ApiError {
+    /** insufficient_stock | below_model_minimum | invalid_gpu_count | model_too_large. */
+    reason;
+    /** The explicit minimum block for the model (selected type + per-type table). */
+    minimumRequirement;
+    /** The selection the rejection was about. */
+    selected;
+    /** Whether the capacity queue may be joined instead. */
+    queueEligible;
+    constructor(status, body) {
+        super(status, body);
+        this.name = 'CapacityUnavailableError';
+        const flat = nestedErrorBody(body);
+        this.reason = flat.reason;
+        this.minimumRequirement = flat.minimum_requirement;
+        this.selected = flat.selected;
+        this.queueEligible = flat.queue_eligible === true;
+    }
+}
+/**
+ * Map a non-2xx body to the most specific typed error. The service is the
+ * authority: a CAPACITY_UNAVAILABLE code becomes {@link CapacityUnavailableError}
+ * so callers read `.availableGpus`/`.minimumRequirement` without string
+ * matching. @internal
+ */
+export function buildApiError(status, body) {
+    const err = body.error;
+    const nested = typeof err === 'object' && err !== null ? err : null;
+    const code = (nested ? String(nested.code || '') : body.code) || undefined;
+    if (code === 'CAPACITY_UNAVAILABLE') {
+        return new CapacityUnavailableError(status, body);
     }
+    return new ApiError(status, body);
 }
 // ============================================================================
 // Environment defaults
@@ -140,7 +228,7 @@ export class HttpClient {
         }
         const data = await res.json().catch(() => ({}));
         if (!res.ok) {
-            throw new ApiError(res.status, data);
+            throw buildApiError(res.status, data);
         }
         return data;
     }
@@ -195,7 +283,7 @@ export class HttpClient {
         }
         const data = await res.json().catch(() => ({}));
         if (!res.ok) {
-            throw new ApiError(res.status, data);
+            throw buildApiError(res.status, data);
         }
         return data;
     }

package/dist/index.d.ts

@@ -56,11 +56,11 @@ export declare class BiOS {
     constructor(config: BiOSConfig);
     introspect(): Promise<ApiKeyIntrospection>;
 }
-export { ApiError } from './client.js';
+export { ApiError, CapacityUnavailableError } from './client.js';
 export { Models } from './resources/models.js';
 export { Datasets } from './resources/datasets.js';
 export { Training } from './resources/training.js';
 export { Wallet } from './resources/wallet.js';
 export { GPU, type GPURecommendation } from './resources/gpu.js';
 export { Inference, validateChatRequest, parseSSE, type ChatMessage, type FunctionTool, type ChatCompletionParams, type ChatCompletionResponse, type ChatCompletionChunk, } from './resources/inference.js';
-export type { BiOSConfig, PaginatedResponse, ApiErrorBody, Model, ModelSearchParams, ModelSearchResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, } from './types.js';
+export type { BiOSConfig, PaginatedResponse, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, InferenceBookingAccepted, Model, ModelSearchParams, ModelSearchResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, } from './types.js';

package/dist/index.js

@@ -74,7 +74,7 @@ export class BiOS {
 // ---------------------------------------------------------------------------
 // Re-exports
 // ---------------------------------------------------------------------------
-export { ApiError } from './client.js';
+export { ApiError, CapacityUnavailableError } from './client.js';
 export { Models } from './resources/models.js';
 export { Datasets } from './resources/datasets.js';
 export { Training } from './resources/training.js';

package/dist/resources/gpu-priorities.d.ts

@@ -10,5 +10,14 @@ export interface NormalizedGPUPlacement {
     gpuType: string | undefined;
     gpuCount: number | undefined;
 }
-/** Validate the ranked placement contract shared by training and deployments. */
-export declare function normalizeGPUPlacement(choices: GPUChoice[] | undefined, queueEnabled: boolean, gpuType: string | undefined, gpuCount: number | undefined, queueField: 'queueIfUnavailable' | 'allowCapacityQueue'): NormalizedGPUPlacement;
+/**
+ * Validate the ranked placement contract shared by training and deployments.
+ *
+ * `rankedImmediate=true` lets a launch WITHOUT the queue carry 1-5 ranked
+ * choices (best first): only the selected rung is booked up front, the extras
+ * become backups / the after-start replacement ladder (book-first §4 — backup
+ * rungs are decoupled from queue consent; the queue itself stays opt-in).
+ * With `rankedImmediate=false` a non-queued launch still needs exactly one
+ * choice. Queueing always needs 3 to 5 choices.
+ */
+export declare function normalizeGPUPlacement(choices: GPUChoice[] | undefined, queueEnabled: boolean, gpuType: string | undefined, gpuCount: number | undefined, queueField: 'queueIfUnavailable' | 'allowCapacityQueue', rankedImmediate?: boolean): NormalizedGPUPlacement;

package/dist/resources/gpu-priorities.js

@@ -1,5 +1,14 @@
-/** Validate the ranked placement contract shared by training and deployments. */
-export function normalizeGPUPlacement(choices, queueEnabled, gpuType, gpuCount, queueField) {
+/**
+ * Validate the ranked placement contract shared by training and deployments.
+ *
+ * `rankedImmediate=true` lets a launch WITHOUT the queue carry 1-5 ranked
+ * choices (best first): only the selected rung is booked up front, the extras
+ * become backups / the after-start replacement ladder (book-first §4 — backup
+ * rungs are decoupled from queue consent; the queue itself stays opt-in).
+ * With `rankedImmediate=false` a non-queued launch still needs exactly one
+ * choice. Queueing always needs 3 to 5 choices.
+ */
+export function normalizeGPUPlacement(choices, queueEnabled, gpuType, gpuCount, queueField, rankedImmediate = false) {
     if (choices === undefined) {
         if (queueEnabled) {
             throw new Error(`BiOS: ${queueField}=true requires 3 to 5 gpuPriorities`);
@@ -15,7 +24,7 @@ export function normalizeGPUPlacement(choices, queueEnabled, gpuType, gpuCount,
     if (queueEnabled && choices.length < 3) {
         throw new Error(`BiOS: ${queueField}=true requires 3 to 5 gpuPriorities`);
     }
-    if (!queueEnabled && choices.length !== 1) {
+    if (!queueEnabled && !rankedImmediate && choices.length !== 1) {
         throw new Error(`BiOS: gpuPriorities must contain exactly one choice when ${queueField} is false`);
     }
     const seen = new Set();

package/dist/resources/inference.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { InferenceDeployment, InferenceCreateParams, InferenceCreateResponse, InferenceDeleteResponse, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceLifecycleResponse, InferenceListParams, InferenceListResponse, InferenceNotificationListResponse, InferencePreflightResponse, InferenceUpdateResponse, InferenceUpdateParams } from '../types.js';
+import type { InferenceDeployment, InferenceBookingAccepted, InferenceCreateParams, InferenceCreateResponse, InferenceDeleteResponse, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceLifecycleResponse, InferenceListParams, InferenceListResponse, InferenceNotificationListResponse, InferencePreflightResponse, InferenceUpdateResponse, InferenceUpdateParams } from '../types.js';
 declare function buildInferenceRequest(params: InferenceCreateParams): Record<string, unknown>;
 export interface ChatMessage extends Record<string, unknown> {
     role: 'system' | 'developer' | 'user' | 'assistant' | 'tool' | 'function';
@@ -53,8 +53,50 @@ export declare class Inference {
     private get http();
     /** Side-effect-free validation with authoritative stock, prices, alternatives, and hold terms. */
     preflight(params: InferenceCreateParams): Promise<InferencePreflightResponse>;
-    /** Create after preflight. Reuse idempotencyKey after a timeout to recover the same deployment and inference key. */
+    /**
+     * Create after preflight. Reuse idempotencyKey after a timeout to recover
+     * the same deployment and inference key.
+     *
+     * Pre-submit validation (book-first §2): the chosen gpuType/gpuCount are
+     * checked against the server's MODEL-ADDRESSED gpu-options (computed
+     * min_gpus/valid_counts) before any POST; a below-minimum or TP-invalid
+     * selection throws the typed {@link CapacityUnavailableError} with the
+     * standard body. The server stays the enforcement floor; an unreadable
+     * sizing endpoint never blocks the create.
+     *
+     * Book-before-reveal (book-first §1): a non-queued create answers 202 with
+     * a booking handle while a vendor-accepted GPU is booked (30-40s typical).
+     * By default this method POLLS the booking to its terminal outcome and
+     * returns the full create payload (the one-time inference_key exactly
+     * once); a definitive miss throws {@link CapacityUnavailableError} with
+     * FRESH alternatives + the minimum block, and NO deployment exists. Pass
+     * `{ waitForBooking: false }` to receive the raw 202 body and poll
+     * {@link getBooking} yourself. Transient 503s during the poll are retried —
+     * a market outage is never a capacity verdict.
+     */
     create(params: InferenceCreateParams, idempotencyKey: string): Promise<InferenceCreateResponse>;
+    create(params: InferenceCreateParams, idempotencyKey: string, options: {
+        waitForBooking?: boolean;
+        bookingTimeoutMs?: number;
+    }): Promise<InferenceCreateResponse | InferenceBookingAccepted>;
+    /**
+     * Poll a pre-reveal booking handle once: `{ booking: {...} }` while pending,
+     * or the full create payload after the vendor accepted (the one-time
+     * inference_key is present exactly once). Throws
+     * {@link CapacityUnavailableError} on the definitive 409 miss and ApiError
+     * 503 on a transient market outage (retry — never a capacity verdict).
+     */
+    getBooking(handle: string): Promise<InferenceCreateResponse | InferenceBookingAccepted>;
+    /** Poll a booking handle to its terminal outcome (see {@link create}). */
+    waitForBooking(handle: string, timeoutMs?: number, pollIntervalMs?: number): Promise<InferenceCreateResponse>;
+    /**
+     * Advisory model-addressed min/valid-count check before any POST. Throws the
+     * typed CapacityUnavailableError only when the selection can NEVER be booked
+     * for this model; every failure to ANSWER (endpoint unreachable, unknown
+     * shape) is silent — the create gate re-validates authoritatively and
+     * unknown never fails closed. @internal
+     */
+    private validateGpuSelectionBeforeSubmit;
     /** Fetch one bounded newest-first page. Reuse next_cursor with unchanged filters. */
     listPage(params?: InferenceListParams): Promise<InferenceListResponse>;
     /** Compatibility helper returning only one bounded page. Prefer listPage for pagination. */
@@ -72,7 +114,14 @@ export declare class Inference {
     restart(id: string): Promise<InferenceLifecycleResponse>;
     update(id: string, params: InferenceUpdateParams): Promise<InferenceUpdateResponse>;
     delete(id: string): Promise<InferenceDeleteResponse>;
-    /** Model-fit GPU choices joined to the authoritative deployment market snapshot. */
+    /**
+     * Model-fit GPU choices joined to the authoritative deployment market
+     * snapshot. MODEL-ADDRESSED (recommended, book-first §2): pass `model` (or
+     * `inferenceId`) and the SERVER resolves the facts and computes
+     * min_gpus/valid_counts/bookable_counts — the same single implementation the
+     * create gate enforces, so client facts can never understate a minimum. The
+     * client-fact params (`paramsB` & friends) are DEPRECATED, kept one release.
+     */
     getGPUOptions(params: InferenceGPUOptionsParams): Promise<InferenceGPUOptionsResponse>;
     private prepare;
     private abortContext;

package/dist/resources/inference.js

@@ -1,4 +1,4 @@
-import { ApiError, envBaseUrl } from '../client.js';
+import { ApiError, CapacityUnavailableError, envBaseUrl } from '../client.js';
 import { normalizeGPUPlacement } from './gpu-priorities.js';
 const FUNCTION_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool', 'function']);
@@ -21,7 +21,12 @@ function inferenceIdempotencyKey(value) {
 }
 function buildInferenceRequest(params) {
     const queueEnabled = params.allowCapacityQueue ?? false;
-    const placement = normalizeGPUPlacement(params.gpuPriorities, queueEnabled, params.gpuType, params.gpuCount, 'allowCapacityQueue');
+    const placement = normalizeGPUPlacement(params.gpuPriorities, queueEnabled, params.gpuType, params.gpuCount, 'allowCapacityQueue', 
+    // Backup rungs are decoupled from queue consent (book-first §4): a
+    // non-queued deployment may rank 1-5 placements. Only the selected rung
+    // is booked up front; the extras become the after-start replacement
+    // ladder if a GPU is ever lost.
+    true);
     if (!params.name?.trim())
         throw new Error('BiOS: deployment name is required');
     if (!placement.gpuType)
@@ -298,10 +303,141 @@ export class Inference {
     preflight(params) {
         return this.http.fetchPost('/api/inference/preflight', buildInferenceRequest(params));
     }
-    /** Create after preflight. Reuse idempotencyKey after a timeout to recover the same deployment and inference key. */
-    create(params, idempotencyKey) {
-        return this.http.fetchPost('/api/inference', buildInferenceRequest(params), {
-            'Idempotency-Key': inferenceIdempotencyKey(idempotencyKey),
+    async create(params, idempotencyKey, options) {
+        const body = buildInferenceRequest(params);
+        // Validate the RESOLVED placement (gpu_type/gpu_count may come from the
+        // first ranked priority rather than the top-level fields).
+        await this.validateGpuSelectionBeforeSubmit(params, String(body.gpu_type ?? ''), Number(body.gpu_count ?? NaN));
+        const response = await this.http.fetchPost('/api/inference', body, { 'Idempotency-Key': inferenceIdempotencyKey(idempotencyKey) });
+        const handle = response?.booking?.handle;
+        if (handle && (options?.waitForBooking ?? true)) {
+            return this.waitForBooking(handle, options?.bookingTimeoutMs ?? 300_000);
+        }
+        return response;
+    }
+    /**
+     * Poll a pre-reveal booking handle once: `{ booking: {...} }` while pending,
+     * or the full create payload after the vendor accepted (the one-time
+     * inference_key is present exactly once). Throws
+     * {@link CapacityUnavailableError} on the definitive 409 miss and ApiError
+     * 503 on a transient market outage (retry — never a capacity verdict).
+     */
+    getBooking(handle) {
+        return this.http.fetchGet(`/api/inference/bookings/${encodeURIComponent(handle)}`);
+    }
+    /** Poll a booking handle to its terminal outcome (see {@link create}). */
+    async waitForBooking(handle, timeoutMs = 300_000, pollIntervalMs = 2_000) {
+        const deadline = Date.now() + Math.max(timeoutMs, pollIntervalMs);
+        for (;;) {
+            if (Date.now() > deadline) {
+                throw new ApiError(408, {
+                    error: {
+                        code: 'BOOKING_POLL_TIMEOUT',
+                        message: `BiOS: the GPU booking did not conclude within ${Math.round(timeoutMs / 1000)}s. `
+                            + `Nothing was charged and no deployment exists until a GPU is confirmed; `
+                            + `poll getBooking('${handle}') to continue waiting.`,
+                    },
+                });
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+            let outcome;
+            try {
+                outcome = await this.getBooking(handle);
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 503)
+                    continue; // transient — never fail-closed
+                throw err;
+            }
+            if (outcome?.booking?.status === 'booking')
+                continue;
+            return outcome;
+        }
+    }
+    /**
+     * Advisory model-addressed min/valid-count check before any POST. Throws the
+     * typed CapacityUnavailableError only when the selection can NEVER be booked
+     * for this model; every failure to ANSWER (endpoint unreachable, unknown
+     * shape) is silent — the create gate re-validates authoritatively and
+     * unknown never fails closed. @internal
+     */
+    async validateGpuSelectionBeforeSubmit(params, gpuType, gpuCount) {
+        const model = params.hfModelId || params.baseModelId;
+        if (!model || !gpuType || !Number.isInteger(gpuCount))
+            return;
+        let options;
+        try {
+            options = await this.getGPUOptions({
+                model,
+                revision: params.hfModelRevision || params.baseModelRevision,
+                quant: params.quant,
+                contextLength: params.contextLength,
+                hfIntegrationId: params.hfIntegrationId,
+            });
+        }
+        catch {
+            return; // advisory only — the create gate is the enforcement floor
+        }
+        const chosen = options?.options?.find(option => option.gpu_type === gpuType);
+        if (!chosen)
+            return;
+        const minGpus = chosen.min_gpus || 0;
+        const validCounts = (chosen.valid_counts || []).filter(count => Number.isInteger(count));
+        let reason;
+        let message = '';
+        if (chosen.selectable === false) {
+            reason = 'model_too_large';
+            message = `BiOS: this model cannot be served on ${gpuType} at any supported GPU count`;
+        }
+        else if (minGpus > 0 && gpuCount < minGpus) {
+            reason = 'below_model_minimum';
+            message = `BiOS: ${gpuType} needs at least ${minGpus} GPU(s) for this model (you chose ${gpuCount})`;
+        }
+        else if (validCounts.length > 0 && !validCounts.includes(gpuCount)) {
+            reason = 'invalid_gpu_count';
+            message = `BiOS: ${gpuCount} GPUs is not a valid tensor-parallel size for this model on ${gpuType} — valid choices: ${validCounts.join(', ')}`;
+        }
+        if (!reason)
+            return;
+        const selectableOptions = (options.options || []).filter((option) => !!option && option.selectable !== false);
+        const alternatives = selectableOptions
+            .filter(option => option.market?.availability_status === 'available')
+            .map(option => ({
+            gpu_type: option.gpu_type,
+            gpu_count: option.min_gpus,
+            min_gpus: option.min_gpus,
+            valid_counts: option.valid_counts,
+            tier: 'secure',
+            available_count: option.market?.available_count ?? undefined,
+            price_hour_cents: (option.market?.price_per_gpu_hour_cents || 0) * (option.min_gpus || 1),
+        }));
+        throw new CapacityUnavailableError(409, {
+            error: {
+                code: 'CAPACITY_UNAVAILABLE',
+                message,
+            },
+            reason,
+            checked_at: options.availability_checked_at,
+            queue_eligible: params.allowCapacityQueue === true,
+            selected: {
+                gpu_type: gpuType,
+                gpu_count: gpuCount,
+                tier: params.gpuTier || 'secure',
+                availability_status: 'unknown',
+            },
+            minimum_requirement: {
+                selected_gpu_min: minGpus,
+                selected_valid_counts: validCounts,
+                per_type: selectableOptions
+                    .filter(option => (option.min_gpus || 0) >= 1)
+                    .map(option => ({
+                    gpu_type: option.gpu_type,
+                    min_gpus: option.min_gpus,
+                    valid_counts: option.valid_counts || [],
+                })),
+            },
+            available_gpus: alternatives,
+            available_alternatives: alternatives,
         });
     }
     /** Fetch one bounded newest-first page. Reuse next_cursor with unchanged filters. */
@@ -386,12 +522,32 @@ export class Inference {
     delete(id) {
         return this.http.fetchDelete(`/api/inference/${encodeURIComponent(id)}`);
     }
-    /** Model-fit GPU choices joined to the authoritative deployment market snapshot. */
+    /**
+     * Model-fit GPU choices joined to the authoritative deployment market
+     * snapshot. MODEL-ADDRESSED (recommended, book-first §2): pass `model` (or
+     * `inferenceId`) and the SERVER resolves the facts and computes
+     * min_gpus/valid_counts/bookable_counts — the same single implementation the
+     * create gate enforces, so client facts can never understate a minimum. The
+     * client-fact params (`paramsB` & friends) are DEPRECATED, kept one release.
+     */
     getGPUOptions(params) {
         if (params.gpuTier !== undefined && params.gpuTier !== 'secure') {
             throw new Error('BiOS: gpuTier must be secure; other deployment capacity tiers are not supported');
         }
-        const query = new URLSearchParams({ params_b: String(params.paramsB) });
+        if (params.model === undefined && params.inferenceId === undefined && params.paramsB === undefined) {
+            throw new Error('BiOS: pass model (or inferenceId) for server-resolved sizing, or the deprecated paramsB client facts');
+        }
+        const query = new URLSearchParams();
+        if (params.model !== undefined)
+            query.set('model', params.model);
+        if (params.revision !== undefined)
+            query.set('revision', params.revision);
+        if (params.inferenceId !== undefined)
+            query.set('inference_id', params.inferenceId);
+        if (params.hfIntegrationId !== undefined)
+            query.set('hf_integration_id', params.hfIntegrationId);
+        if (params.paramsB !== undefined)
+            query.set('params_b', String(params.paramsB));
         if (params.activeParamsB !== undefined)
             query.set('active_params_b', String(params.activeParamsB));
         if (params.isMoe !== undefined)

package/dist/types.d.ts

@@ -38,6 +38,66 @@ export interface ApiErrorBody {
     message?: string;
     code?: string;
     request_id?: string;
+    /**
+     * Bookable-now GPU alternatives, present on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE): each entry fits the
+     * requested model's minimum requirements and was in stock at `checked_at`.
+     * Pick one and resubmit — nothing else about the request needs to change.
+     */
+    available_gpus?: AvailableGpuAlternative[];
+    /** Same contract as `available_gpus`; some surfaces use this field name. */
+    available_alternatives?: AvailableGpuAlternative[];
+    /** When the availability snapshot behind the rejection was taken. */
+    checked_at?: string;
+    /**
+     * Rejection class on the standard CAPACITY_UNAVAILABLE contract:
+     * insufficient_stock | below_model_minimum | invalid_gpu_count |
+     * model_too_large.
+     */
+    reason?: string;
+    /**
+     * Explicit server-computed minimum block on CAPACITY_UNAVAILABLE: the
+     * selected type's minimum + valid counts and the per-type table for the
+     * model. Client-supplied facts can never lower these.
+     */
+    minimum_requirement?: CapacityMinimumRequirement;
+    /** The selection the rejection was about. */
+    selected?: {
+        gpu_type: string;
+        gpu_count: number;
+        tier?: string;
+        availability_status?: 'available' | 'out_of_stock' | 'unknown';
+        available_count?: number;
+    };
+    /** Whether the capacity queue may be joined for this request. */
+    queue_eligible?: boolean;
+}
+/** The explicit minimum-requirement block of the standard capacity contract. */
+export interface CapacityMinimumRequirement {
+    selected_gpu_min: number;
+    selected_valid_counts?: number[];
+    per_type: Array<{
+        gpu_type: string;
+        min_gpus: number;
+        valid_counts: number[];
+    }>;
+}
+/** One bookable-now GPU alternative carried on an availability rejection. */
+export interface AvailableGpuAlternative {
+    gpu_type: string;
+    gpu_count?: number;
+    /** The model's minimum GPU count for this type (never pick below it). */
+    min_gpus?: number;
+    /** Every pickable count for this type (>= min and tensor-parallel-valid). */
+    valid_counts?: number[];
+    available_count?: number;
+    price_per_hour_cents?: number;
+    /** Total hourly price at `gpu_count` on the inference contract. */
+    price_hour_cents?: number;
+    provider?: string;
+    region?: string;
+    tier?: string;
+    recommended?: boolean;
 }
 /** A model returned from the HuggingFace-backed model search. */
 export interface Model {
@@ -1040,6 +1100,18 @@ export interface InferenceNotificationSummary {
 export interface InferenceNotificationListResponse {
     notifications: InferenceNotification[];
 }
+/**
+ * 202 body of a book-before-reveal create: no id, no key — only the opaque
+ * handle to poll (`inference.getBooking` / `inference.waitForBooking`).
+ */
+export interface InferenceBookingAccepted {
+    booking: {
+        handle: string;
+        status: 'booking';
+        estimated_seconds: number;
+        poll_url: string;
+    };
+}
 export interface InferenceCreateResponse {
     id: string;
     deployment_id: string;
@@ -1155,6 +1227,12 @@ export interface InferenceGPUOption {
     min_gpus: number;
     recommended_gpus: number;
     valid_counts?: number[];
+    /**
+     * valid_counts filtered to counts live single-vendor stock can fill RIGHT
+     * NOW (book-first contract). Absent when availability is unknown — never
+     * fabricated. Offer/submit only these when present.
+     */
+    bookable_counts?: number[];
     selectable: boolean;
     reason?: string;
     market?: InferenceGPUOptionMarket;
@@ -1173,7 +1251,21 @@ export interface InferenceGPUAlternative {
     availability_status: 'available' | 'out_of_stock' | 'unknown';
 }
 export interface InferenceGPUOptionsParams {
-    paramsB: number;
+    /**
+     * MODEL-ADDRESSED sizing (recommended): the SERVER resolves the model facts
+     * from this HF repo id (optionally with `revision`) and computes
+     * min_gpus/valid_counts/bookable_counts — the same single implementation the
+     * create gate enforces. When set, the deprecated client-fact params below
+     * are unnecessary.
+     */
+    model?: string;
+    revision?: string;
+    /** Size from an existing deployment's pinned facts instead of a model id. */
+    inferenceId?: string;
+    /** HF integration for gated models when using `model`. */
+    hfIntegrationId?: string;
+    /** DEPRECATED client-fact path; required only when `model`/`inferenceId` are absent. */
+    paramsB?: number;
     activeParamsB?: number;
     isMoe?: boolean;
     quant?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bios-sdk",
-  "version": "0.1.1-dev.10",
+  "version": "0.1.1-dev.16",
   "description": "Official TypeScript SDK for the BIOS training and deployment platform API",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test test/contracts.test.mjs",
+    "test": "npm run build && node --test test/contracts.test.mjs test/capacity-contract.test.mjs",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build"
   },