@sandbox-kit/modal 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandbox-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# `@sandbox-kit/modal`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Modal provider for [`@sandbox-kit/sandbox`](https://www.npmjs.com/package/@sandbox-kit/sandbox).
+Use the shared client API; this package supplies the `modal()` provider.
+
+## Install
+
+```sh
+npm install @sandbox-kit/sandbox @sandbox-kit/modal
+```
+
+Requires Node.js 20, 22, or 24.15+, and a Modal token pair.
+
+## Quick start
+
+```ts
+import { modal } from "@sandbox-kit/modal";
+import { Client } from "@sandbox-kit/sandbox";
+
+await using client = new Client({
+  provider: modal(),
+  auth: {
+    tokenPair: {
+      id: process.env.MODAL_TOKEN_ID!,
+      secret: process.env.MODAL_TOKEN_SECRET!,
+    },
+  },
+  scope: {
+    appName: process.env.MODAL_APP_NAME!,
+    environment: process.env.MODAL_ENVIRONMENT ?? "main",
+  },
+  timeout: 120_000,
+});
+
+const sandbox = await client.create({
+  source: { image: { reference: "alpine:3.21" } },
+  resources: { cpuCores: 0.5, memoryMib: 512n },
+  lifetime: { maximumLifetime: 5 * 60_000 },
+});
+console.log(sandbox.id);
+```
+
+Closing the client releases local SDK resources only. Reclaim sandboxes with
+idle/max lifetime policies or `terminate`.
+
+## Configuration
+
+| Setting        | Notes                                                      |
+| -------------- | ---------------------------------------------------------- |
+| Token pair     | `auth: { tokenPair: { id, secret } }`                      |
+| OAuth refresh  | Supported with client ID and exactly one secret or JWT key |
+| Omitted `auth` | Modal SDK environment / profile credentials                |
+| App            | `scope.appName` — required                                 |
+| Environment    | `scope.environment` (default often `main`)                 |
+| Region         | `region` — default placement preference                    |
+| Endpoint       | Not supported                                              |
+
+## What you can do
+
+**Create** from a registry image with runtime (command, workdir, PTY), gVisor or
+Linux VM isolation, CPU/memory, placement, network policy and ports, secrets,
+OIDC workload identity, readiness probes, timeouts, labels, and verbose mode.
+
+**Lifecycle** on the handle: `attach`, `terminate`, and local `close`.
+Provider-verified `get` / `refresh`, start, stop, pause, archive, and delete are
+unsupported.
+
+When you set resources, Modal requires at least 0.125 CPU cores and 128 MiB
+memory. Omitted values keep Modal defaults. Disk size cannot be raised at create.
+
+## Examples
+
+| Example    | Project                                                                                                                           |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Creation   | [create-modal-sandbox](https://github.com/sandbox-kit/kit/tree/main/examples/typescript/modal/create-modal-sandbox)               |
+| Resources  | [create-modal-with-resources](https://github.com/sandbox-kit/kit/tree/main/examples/typescript/modal/create-modal-with-resources) |
+| Attach     | [attach-modal-sandbox](https://github.com/sandbox-kit/kit/tree/main/examples/typescript/modal/attach-modal-sandbox)               |
+| Full index | [TypeScript examples](https://github.com/sandbox-kit/kit/tree/main/examples/typescript)                                           |
+
+## License
+
+MIT

package/dist/checks/provider_checks.d.ts

@@ -0,0 +1,2 @@
+import type { CreateOptions } from "@sandbox-kit/sandbox";
+export declare function validateProviderCreate(request: CreateOptions): void;

package/dist/checks/provider_checks.js

@@ -0,0 +1,86 @@
+import { ErrorKind, CreateFieldEnvironment, CreateFieldNetworkInboundCidrsEntries, CreateFieldNetworkOutboundCidrsEntries, CreateFieldNetworkOutboundDomainsEntries, CreateFieldPlacementCloud, CreateFieldResourcesCpuCores, CreateFieldResourcesMemoryMib, CreateFieldRuntimeWorkingDirectory, validCidr, validDomain, validEnvName, } from "@sandbox-kit/sandbox";
+import { providerError } from "#errors.js";
+// validateProviderCreate rejects creation settings this provider cannot honor.
+// Rules are inventoried in specs/providers/modal.yaml checks.
+export function validateProviderCreate(request) {
+    const cpuCores = request.resources?.cpuCores;
+    if (cpuCores !== undefined && cpuCores < 0.125) {
+        providerError({
+            kind: ErrorKind.InvalidArgument,
+            operation: "create",
+            field: CreateFieldResourcesCpuCores,
+            message: "resources.cpu_cores is outside supported values",
+        });
+    }
+    const memoryMib = request.resources?.memoryMib;
+    if (memoryMib !== undefined && memoryMib < BigInt("128")) {
+        providerError({
+            kind: ErrorKind.InvalidArgument,
+            operation: "create",
+            field: CreateFieldResourcesMemoryMib,
+            message: "resources.memory_mib is outside supported values",
+        });
+    }
+    const workingDirectory = request.runtime?.workingDirectory;
+    if (workingDirectory !== undefined && !workingDirectory.startsWith("/")) {
+        providerError({
+            kind: ErrorKind.InvalidArgument,
+            operation: "create",
+            field: CreateFieldRuntimeWorkingDirectory,
+            message: "runtime.working_directory is outside supported values",
+        });
+    }
+    const cloud = request.placement?.cloud;
+    if (cloud !== undefined &&
+        cloud !== "aws" &&
+        cloud !== "gcp" &&
+        cloud !== "oci" &&
+        cloud !== "auto") {
+        providerError({
+            kind: ErrorKind.Unsupported,
+            operation: "create",
+            field: CreateFieldPlacementCloud,
+            message: "placement.cloud is outside supported values",
+        });
+    }
+    for (const value of request.network?.outboundCidrs ?? []) {
+        if (value !== "" && !validCidr(value)) {
+            providerError({
+                kind: ErrorKind.InvalidArgument,
+                operation: "create",
+                field: CreateFieldNetworkOutboundCidrsEntries,
+                message: "network.outbound_cidrs.entries is outside supported values",
+            });
+        }
+    }
+    for (const value of request.network?.inboundCidrs ?? []) {
+        if (!validCidr(value)) {
+            providerError({
+                kind: ErrorKind.InvalidArgument,
+                operation: "create",
+                field: CreateFieldNetworkInboundCidrsEntries,
+                message: "network.inbound_cidrs.entries is outside supported values",
+            });
+        }
+    }
+    for (const value of request.network?.outboundDomains ?? []) {
+        if (value !== "" && !validDomain(value)) {
+            providerError({
+                kind: ErrorKind.InvalidArgument,
+                operation: "create",
+                field: CreateFieldNetworkOutboundDomainsEntries,
+                message: "network.outbound_domains.entries is outside supported values",
+            });
+        }
+    }
+    for (const value of Object.keys(request.environment ?? {})) {
+        if (!validEnvName(value)) {
+            providerError({
+                kind: ErrorKind.InvalidArgument,
+                operation: "create",
+                field: CreateFieldEnvironment,
+                message: "environment is outside supported values",
+            });
+        }
+    }
+}

package/dist/config/provider_config.d.ts

@@ -0,0 +1,8 @@
+import type { ModalClientParams as NativeClientConfig } from "modal";
+import { type Config, type Scope } from "@sandbox-kit/sandbox";
+export declare function mapGeneratedClientConfig(config: Config): NativeClientConfig;
+export interface ProviderState {
+    readonly scope?: Scope;
+    readonly region?: string;
+}
+export declare function captureProviderState(config: Config): ProviderState;

package/dist/config/provider_config.js

@@ -0,0 +1,45 @@
+// Client configuration composition for the native SDK constructor.
+// Kept in sync with specs/providers/modal.yaml client: rules (not emitted).
+import { ErrorKind, ConfigFieldAuth, ConfigFieldEndpoint, ConfigFieldScopeProjectId, } from "@sandbox-kit/sandbox";
+import { mapClientScope, mapOAuthAuth, mapTokenPairCredentials, } from "#mappings/provider_mappings.js";
+import { providerError } from "#errors.js";
+export function mapGeneratedClientConfig(config) {
+    const source = config;
+    const target = {};
+    if (source.endpoint !== undefined)
+        unsupported(ConfigFieldEndpoint, "Endpoint cannot be configured through this SDK's public client constructor");
+    if (source.scope !== undefined) {
+        const mapped = mapClientScope(source.scope, "initialize");
+        Object.assign(target, mapped);
+        if (source.scope.organizationId !== undefined)
+            unsupported("scope.organizationId", "unsupported client configuration field");
+        if (source.scope.projectId !== undefined)
+            unsupported(ConfigFieldScopeProjectId, "unsupported client configuration field");
+    }
+    if (source.auth?.tokenPair !== undefined) {
+        Object.assign(target, mapTokenPairCredentials(source.auth.tokenPair, "initialize"));
+    }
+    else if (source.auth?.oauthRefresh !== undefined) {
+        Object.assign(target, mapOAuthAuth(source.auth.oauthRefresh, "initialize"));
+    }
+    else if (source.auth !== undefined) {
+        unsupported(ConfigFieldAuth, "unsupported authentication mode");
+    }
+    return target;
+}
+export function captureProviderState(config) {
+    return {
+        ...(config.scope === undefined
+            ? {}
+            : { scope: structuredClone(config.scope) }),
+        ...(config.region === undefined ? {} : { region: config.region }),
+    };
+}
+function unsupported(field, message) {
+    providerError({
+        kind: ErrorKind.Unsupported,
+        operation: "initialize",
+        field,
+        message,
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+import { SandboxError, type ErrorInfo } from "@sandbox-kit/sandbox";
+/** Inputs for throwing a Modal-scoped validation or mapping error. */
+export interface ProviderErrorInput {
+    kind: ErrorInfo["kind"];
+    operation: string;
+    field: string;
+    message: string;
+}
+export declare function mapModalError(error: unknown, operation: string): SandboxError;
+/** Local throw helper for mappings, checks, and config. */
+export declare function providerError(input: ProviderErrorInput): never;

package/dist/errors.js

@@ -0,0 +1,56 @@
+// Native Modal error translation is handwritten.
+// Classification order: existing SandboxError, abort/timeout DOMException,
+// then native Modal types, then unknown. Cause stays on SandboxError.cause.
+import { AlreadyExistsError, ClientClosedError, ConflictError, InvalidError, NotFoundError, ResourceExhaustedError, SandboxTimeoutError, TimeoutError, } from "modal";
+import { ErrorKind, SandboxError, sandboxError, } from "@sandbox-kit/sandbox";
+export function mapModalError(error, operation) {
+    if (error instanceof SandboxError)
+        return error;
+    if (error instanceof DOMException && error.name === "AbortError")
+        return create({ kind: ErrorKind.Canceled, error, operation });
+    if (error instanceof DOMException && error.name === "TimeoutError")
+        return create({ kind: ErrorKind.Timeout, error, operation });
+    let kind = ErrorKind.Unknown;
+    if (kind === ErrorKind.Unknown && error instanceof InvalidError)
+        kind = ErrorKind.InvalidArgument;
+    if (kind === ErrorKind.Unknown && error instanceof NotFoundError)
+        kind = ErrorKind.NotFound;
+    if (kind === ErrorKind.Unknown && error instanceof AlreadyExistsError)
+        kind = ErrorKind.AlreadyExists;
+    if (kind === ErrorKind.Unknown && error instanceof ConflictError)
+        kind = ErrorKind.Conflict;
+    if (kind === ErrorKind.Unknown && error instanceof ResourceExhaustedError)
+        kind = ErrorKind.ResourceExhausted;
+    if (kind === ErrorKind.Unknown && error instanceof TimeoutError)
+        kind = ErrorKind.Timeout;
+    if (kind === ErrorKind.Unknown && error instanceof SandboxTimeoutError)
+        kind = ErrorKind.Timeout;
+    if (kind === ErrorKind.Unknown && error instanceof ClientClosedError)
+        kind = ErrorKind.FailedPrecondition;
+    return create({ kind, error, operation });
+}
+function create(input) {
+    const { kind, error, operation, statusCode, providerCode, providerSource } = input;
+    return sandboxError({
+        kind,
+        provider: "modal",
+        operation,
+        field: "",
+        message: error instanceof Error
+            ? error.message
+            : "sandbox-kit modal: provider operation failed",
+        ...(statusCode === undefined ? {} : { statusCode }),
+        ...(providerCode === undefined ? {} : { providerCode }),
+        ...(providerSource === undefined ? {} : { providerSource }),
+    }, error);
+}
+/** Local throw helper for mappings, checks, and config. */
+export function providerError(input) {
+    throw sandboxError({
+        kind: input.kind,
+        provider: "modal",
+        operation: input.operation,
+        field: input.field,
+        message: "sandbox-kit modal: " + input.message,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { providerName } from "./provider.js";
+export { modal } from "./modal.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { providerName } from "./provider.js";
+export { modal } from "./modal.js";

package/dist/mappings/mappings.d.ts

@@ -0,0 +1,16 @@
+import { type ModalClientParams, type Sandbox, type SandboxCreateParams } from "modal";
+import { type Config, type CreateOptions, type SandboxInfo } from "@sandbox-kit/sandbox";
+import type { ProviderState } from "#config/provider_config.js";
+export interface ModalCreatePlan {
+    readonly app: string;
+    readonly environment?: string;
+    readonly image: string;
+    readonly params: SandboxCreateParams;
+    readonly secretNames: readonly string[];
+    readonly proxyName?: string;
+    readonly waitUntilReady: boolean;
+    readonly readyTimeoutMs?: number;
+}
+export declare function mapClientConfig(config: Config): ModalClientParams;
+export declare function mapCreateRequest(request: CreateOptions, config: ProviderState): ModalCreatePlan;
+export declare function mapSandboxInfo(value: Sandbox, request?: CreateOptions): SandboxInfo;

package/dist/mappings/mappings.js

@@ -0,0 +1,315 @@
+// Provider-specific orchestration around generated portable field mappings.
+import { Probe, } from "modal";
+import { EgressMode, ErrorKind, IsolationKind, PolicyMode, PortTransport, SecretInjection, SandboxState, ValueOrigin, WaitCondition, CreateFieldIsolation, CreateFieldIsolationKind, CreateFieldLifetime, CreateFieldLifetimeIdleTerminateAfter, CreateFieldLifetimeIdleTerminateMode, CreateFieldNetwork, CreateFieldNetworkEgress, CreateFieldNetworkPortsPort, CreateFieldNetworkPortsTransport, CreateFieldPlacementTarget, CreateFieldProvisioningTimeout, CreateFieldProvisioningWaitFor, CreateFieldReadiness, CreateFieldRuntime, CreateFieldSecuritySecretsEnvironmentVariable, CreateFieldSecuritySecretsInjection, CreateFieldSource, ConfigFieldScopeAppName, CreateFieldName, CreateFieldNetworkInboundCidrs, CreateFieldNetworkProxyReference, CreateFieldProvisioningQueueTimeout, CreateFieldResourcesCpuLimitCores, CreateFieldResourcesDiskMib, CreateFieldResourcesMemoryLimitMib, CreateFieldResourcesMemoryMib, CreateFieldSecurityPublicAccess, CreateFieldSecuritySecretsReference, CreateFieldSourceImageReference, } from "@sandbox-kit/sandbox";
+import { mapCommonCreateFields as generatedMapCommonCreateFields, mapIdleDuration as generatedMapIdleDuration, mapLifetimeDuration as generatedMapLifetimeDuration, mapResources as generatedMapResources, mapSandboxIdentity as generatedMapSandboxIdentity, } from "./provider_mappings.js";
+import { validateProviderCreate } from "#checks/provider_checks.js";
+import { mapGeneratedClientConfig } from "#config/provider_config.js";
+import { providerError } from "#errors.js";
+export function mapClientConfig(config) {
+    const result = mapGeneratedClientConfig(config);
+    if (config.timeout !== undefined)
+        result.timeoutMs = finiteDurationMs(config.timeout, "timeout", true);
+    return result;
+}
+export function mapCreateRequest(request, config) {
+    validateProviderCreate(request);
+    const app = config.scope?.appName === undefined
+        ? invalid(ConfigFieldScopeAppName, "Modal app name is required")
+        : nonblank(config.scope.appName, ConfigFieldScopeAppName);
+    if (request.source?.image === undefined)
+        unsupported(CreateFieldSource, "Modal requires an explicit image source");
+    const params = generatedMapCommonCreateFields(request);
+    if (request.name !== undefined)
+        params.name = nonblank(request.name, CreateFieldName);
+    if (config.region !== undefined)
+        params.regions = [nonblankConfig(config.region, "region")];
+    mapRuntime(request, params);
+    mapIsolation(request, params);
+    mapResources(request, params);
+    mapPlacement(request, params);
+    mapNetwork(request, params);
+    const secretNames = mapSecurity(request, params);
+    mapLifetime(request, params);
+    mapReadiness(request, params);
+    const wait = mapProvisioning(request, params);
+    mapObservability(request, params);
+    if (request.providerOptions !== undefined)
+        unsupported("providerOptions", "Modal provider options are not mapped");
+    return {
+        app,
+        ...(config.scope?.environment === undefined
+            ? {}
+            : { environment: config.scope.environment }),
+        image: nonblank(request.source.image.reference, CreateFieldSourceImageReference),
+        params,
+        secretNames,
+        ...(request.network?.proxyReference === undefined
+            ? {}
+            : {
+                proxyName: nonblank(request.network.proxyReference, CreateFieldNetworkProxyReference),
+            }),
+        ...wait,
+    };
+}
+function mapRuntime(r, p) {
+    const v = r.runtime;
+    if (!v)
+        return;
+    if (v.workingDirectory !== undefined)
+        p.workdir = v.workingDirectory;
+    if (v.entrypoint !== undefined)
+        p.command = [...v.entrypoint];
+    if (v.pty !== undefined)
+        p.pty = v.pty;
+    if (v.language !== undefined ||
+        v.version !== undefined ||
+        v.user !== undefined)
+        unsupported(CreateFieldRuntime, "language, version, and user must come from the Modal image");
+}
+function mapIsolation(r, p) {
+    const v = r.isolation;
+    if (!v)
+        return;
+    const kind = v.kind ?? IsolationKind.Default;
+    if (kind === IsolationKind.LinuxVm)
+        p.runtime = "vm";
+    else if (kind === IsolationKind.Container)
+        p.runtime = "gvisor";
+    else if (kind !== IsolationKind.Default)
+        unsupported(CreateFieldIsolationKind, "requested Modal isolation is unsupported");
+    if (v.providerKind !== undefined || v.nestedVirtualization !== undefined)
+        unsupported(CreateFieldIsolation, "provider kind and nested virtualization are unsupported");
+}
+function mapResources(r, p) {
+    const v = r.resources;
+    if (!v)
+        return;
+    if (v.cpuLimitCores !== undefined)
+        positive(v.cpuLimitCores, CreateFieldResourcesCpuLimitCores);
+    if (v.memoryMib !== undefined)
+        integer(v.memoryMib, CreateFieldResourcesMemoryMib, 128);
+    if (v.memoryLimitMib !== undefined)
+        integer(v.memoryLimitMib, CreateFieldResourcesMemoryLimitMib, 1);
+    if (v.diskMib !== undefined)
+        unsupported(CreateFieldResourcesDiskMib, "Modal disk override is unsupported");
+    Object.assign(p, generatedMapResources(v));
+}
+function mapPlacement(r, p) {
+    const v = r.placement;
+    if (!v)
+        return;
+    if (v.cloud !== undefined)
+        p.cloud = v.cloud;
+    if (v.regions !== undefined)
+        p.regions = [...v.regions];
+    if (v.target !== undefined)
+        unsupported(CreateFieldPlacementTarget, "Modal placement target is unsupported");
+}
+function mapNetwork(r, p) {
+    const v = r.network;
+    if (!v)
+        return;
+    const egress = v.egress ?? EgressMode.Default;
+    if (egress === EgressMode.BlockAll)
+        p.blockNetwork = true;
+    else if (egress !== EgressMode.Default &&
+        egress !== EgressMode.AllowAll &&
+        egress !== EgressMode.Restricted)
+        invalid(CreateFieldNetworkEgress, "unknown egress mode");
+    if (v.outboundCidrs !== undefined)
+        p.outboundCidrAllowlist = [...v.outboundCidrs];
+    if (v.outboundDomains !== undefined)
+        p.outboundDomainAllowlist = [...v.outboundDomains];
+    if (v.inboundCidrs !== undefined) {
+        if (!v.inboundCidrs.length)
+            unsupported(CreateFieldNetworkInboundCidrs, "empty inbound deny-all is not representable");
+        p.inboundCidrAllowlist = [...v.inboundCidrs];
+    }
+    if (v.privateNetwork !== undefined)
+        p.i6pn = v.privateNetwork;
+    if (v.customDomain !== undefined)
+        p.customDomain = v.customDomain;
+    if (v.ports) {
+        p.encryptedPorts = [];
+        p.h2Ports = [];
+        p.unencryptedPorts = [];
+        for (const x of v.ports) {
+            const port = x.port;
+            if (port === undefined)
+                invalid(CreateFieldNetworkPortsPort, "port is required");
+            const transport = x.transport ?? PortTransport.Default;
+            if (transport === PortTransport.Tls)
+                p.encryptedPorts.push(port);
+            else if (transport === PortTransport.Http2Tls)
+                p.h2Ports.push(port);
+            else if (transport === PortTransport.Plain)
+                p.unencryptedPorts.push(port);
+            else
+                invalid(CreateFieldNetworkPortsTransport, "explicit transport is required");
+        }
+    }
+    if (v.linkedSandbox !== undefined || v.outboundProxyUrl !== undefined)
+        unsupported(CreateFieldNetwork, "linked sandbox and outbound proxy URL mappings are unsupported");
+}
+function mapSecurity(r, p) {
+    const v = r.security;
+    if (!v)
+        return [];
+    if (v.workloadIdentity !== undefined)
+        p.includeOidcIdentityToken = v.workloadIdentity;
+    if (v.publicAccess !== undefined)
+        unsupported(CreateFieldSecurityPublicAccess, "Modal public access is represented by ports");
+    const names = [];
+    for (const s of v.secrets ?? []) {
+        if (s.environmentVariable !== undefined)
+            unsupported(CreateFieldSecuritySecretsEnvironmentVariable, "per-variable secret renaming is unsupported");
+        const injection = s.injection ?? SecretInjection.Default;
+        if (injection !== SecretInjection.Default &&
+            injection !== SecretInjection.Environment)
+            unsupported(CreateFieldSecuritySecretsInjection, "egress-placeholder injection is unsupported");
+        names.push(nonblank(s.reference, CreateFieldSecuritySecretsReference));
+    }
+    return names;
+}
+function mapLifetime(r, p) {
+    const v = r.lifetime;
+    if (!v)
+        return;
+    if (v.maximumLifetime !== undefined)
+        finiteDurationMs(v.maximumLifetime, "lifetime.maximumLifetime", false);
+    Object.assign(p, generatedMapLifetimeDuration(v));
+    if (v.idleTerminate) {
+        const mode = v.idleTerminate.mode ?? PolicyMode.Default;
+        if (mode === PolicyMode.Disabled)
+            p.idleTimeoutMs = 0;
+        else if (mode === PolicyMode.After) {
+            if (v.idleTerminate.after === undefined)
+                invalid(CreateFieldLifetimeIdleTerminateAfter, "duration is required");
+            finiteDurationMs(v.idleTerminate.after, "lifetime.idleTerminate.after", false);
+            Object.assign(p, generatedMapIdleDuration(v.idleTerminate));
+        }
+        else if (mode !== PolicyMode.Default)
+            invalid(CreateFieldLifetimeIdleTerminateMode, "unknown policy mode");
+    }
+    if (v.ephemeral !== undefined ||
+        v.idleStop !== undefined ||
+        v.idlePause !== undefined ||
+        v.stoppedArchive !== undefined ||
+        v.stoppedDelete !== undefined)
+        unsupported(CreateFieldLifetime, "requested lifecycle policy is unsupported by Modal");
+}
+function mapReadiness(r, p) {
+    const v = r.readiness;
+    if (!v)
+        return;
+    if (v.tcpPort !== undefined) {
+        p.readinessProbe = Probe.withTcp(v.tcpPort);
+    }
+    else if (v.command !== undefined)
+        p.readinessProbe = Probe.withExec([...(v.command.argv ?? [])]);
+    else
+        invalid(CreateFieldReadiness, "probe is required");
+}
+function mapProvisioning(r, _p) {
+    const v = r.provisioning;
+    if (!v)
+        return { waitUntilReady: false };
+    if (v.queueTimeout !== undefined)
+        unsupported(CreateFieldProvisioningQueueTimeout, "Modal queue timeout is unsupported");
+    const waitFor = v.waitFor ?? WaitCondition.Default;
+    if (waitFor === WaitCondition.Default || waitFor === WaitCondition.Scheduled)
+        return { waitUntilReady: false };
+    if (waitFor === WaitCondition.Ready) {
+        if (v.timeout === undefined || v.timeout <= 0)
+            invalid(CreateFieldProvisioningTimeout, "ready wait requires a positive timeout");
+        if (!r.readiness)
+            invalid(CreateFieldReadiness, "ready wait requires a probe");
+        return { waitUntilReady: true, readyTimeoutMs: v.timeout };
+    }
+    unsupported(CreateFieldProvisioningWaitFor, "requested wait condition is unsupported");
+}
+function mapObservability(r, p) {
+    const v = r.observability;
+    if (!v)
+        return;
+    if (v.verbose !== undefined)
+        p.verbose = v.verbose;
+    if (v.telemetryEndpoint !== undefined)
+        unsupported("observability.telemetryEndpoint", "per-sandbox telemetry endpoint is unsupported");
+}
+export function mapSandboxInfo(value, request) {
+    const mapped = generatedMapSandboxIdentity(value);
+    const origins = { ...(mapped.origins ?? {}) };
+    const result = {
+        id: mapped.id ?? value.sandboxId,
+        provider: "modal",
+        state: SandboxState.Running,
+        labels: {},
+        origins,
+    };
+    if (request?.name !== undefined) {
+        mutable(result).name = request.name;
+        origins.name = ValueOrigin.Request;
+    }
+    if (request?.labels !== undefined) {
+        mutable(result).labels = { ...request.labels };
+        origins.labels = ValueOrigin.Request;
+    }
+    if (request?.isolation !== undefined) {
+        mutable(result).isolation = { ...request.isolation };
+        origins.isolation = ValueOrigin.Request;
+    }
+    return result;
+}
+function mutable(v) {
+    return v;
+}
+function nonblank(v, f) {
+    if (!v.trim())
+        invalid(f, "must not be blank");
+    return v;
+}
+function nonblankConfig(v, f) {
+    if (!v.trim())
+        configInvalid(f, "must not be blank");
+    return v;
+}
+function positive(v, f) {
+    if (!Number.isFinite(v) || v <= 0)
+        invalid(f, "must be positive");
+    return v;
+}
+function integer(v, f, min) {
+    if (v < BigInt(min) || v > 2147483647n)
+        invalid(f, "is outside the supported range");
+    return Number(v);
+}
+function finiteDurationMs(v, f, zero) {
+    if (!Number.isFinite(v) || v < 0 || (!zero && v === 0))
+        invalid(f, "must be a finite positive duration");
+    return v;
+}
+function invalid(field, message) {
+    providerError({
+        kind: ErrorKind.InvalidArgument,
+        operation: "create",
+        field,
+        message,
+    });
+}
+function unsupported(field, message) {
+    providerError({
+        kind: ErrorKind.Unsupported,
+        operation: "create",
+        field,
+        message,
+    });
+}
+function configInvalid(field, message) {
+    providerError({
+        kind: ErrorKind.InvalidArgument,
+        operation: "initialize",
+        field,
+        message,
+    });
+}