@wenathlan/saddle 2.0.153 → 2.0.155

package/dist/alternatives.d.ts

@@ -1,508 +0,0 @@
-/**
- * alternatives.ts - Virtual Hardware Engine v5
- *
- * Ten categories of alternative sandbox engines, each one wired through a
- * real adapter implementing the shared SandboxEngine interface
- * (create/exec/snapshot/destroy/metrics). A registry with factories and
- * alias resolution lets hosts swap execution backends without touching
- * call sites, and a comparison matrix carries the data verified during the
- * 2026-08-22 research pass.
- *
- * Engine categories (versions verified 2026-08-22):
- *  1. wasmtime v48.0.0        - fuel + epoch, WASI 0.3.0 async components
- *  2. gvisor release-20260817.0 - runsc, systrap, 10-30% I/O overhead
- *  3. kata 4.1.0              - runtime-rs (Rust) default, OpenVMM support
- *  4. cloud-hypervisor v53.0  - rust-vmm VMM, offloaded snapshots, vfio-user
- *  5. webcontainers           - Node.js inside the browser sandbox (StackBlitz)
- *  6. daytona                 - ~90ms stateful sandboxes, self-hosted, MCP
- *  7. modal                   - 100k+ concurrent sandboxes, elastic GPUs
- *  8. fly-machines            - Firecracker microVMs across ~35 regions
- *  9. e2b family              - E2B, Morph, Cognitora, Vercel Sandbox
- * 10. apple-containers 1.2.2  - Swift microVMs on macOS, <1s boot
- *
- * Related contexts covered by this file (25):
- * Wasmtime, WASI 0.3.0, fuel metering, epoch interruption, runsc, systrap,
- * DirectFS, Kata Containers runtime-rs, OpenVMM, Dragonball, rust-vmm,
- * Cloud Hypervisor, vfio-user, userfaultfd snapshots, WebContainers,
- * StackBlitz, Daytona, MCP servers, Modal, Fly.io Machines, Firecracker,
- * E2B, Morph, Vercel Sandbox, Apple Containers.
- *
- * Module rules: no emoji, JSDoc in English, third-person voice, lowercase
- * identifiers, `using`/`satisfies`/`#private` modern TypeScript, node:* imports
- * first, try/catch on every fallible path, no hardcoded localhost endpoints.
- */
-/** Sandbox resource request shared by every engine adapter. */
-export interface SandboxSpec {
-    readonly id?: string;
-    readonly image?: string;
-    readonly cpus: number;
-    readonly memoryMb: number;
-    readonly command: readonly string[];
-    readonly timeoutMs?: number;
-}
-/** Live sandbox reference an adapter returns after a successful create. */
-export interface SandboxHandle {
-    readonly id: string;
-    readonly engine: string;
-    readonly port: number;
-    readonly createdAt: string;
-}
-/** Result of one exec call: exit code, captured stdout and wall duration. */
-export interface ExecResult {
-    readonly exitCode: number;
-    readonly stdout: string;
-    readonly durationMs: number;
-}
-/** Reference to one persisted snapshot with its backend kind and size. */
-export interface SnapshotRef {
-    readonly sandboxId: string;
-    readonly backend: 'criu' | 'firecracker-file' | 'firecracker-uffd' | 'ch-offloaded' | 'state-pause' | 'component-image';
-    readonly sizeMb: number;
-}
-/** Runtime metrics of one sandbox: boot time, memory, cpus and liveness. */
-export interface SandboxMetrics {
-    readonly bootMs: number;
-    readonly memoryMiB: number;
-    readonly cpus: number;
-    readonly running: boolean;
-}
-/** Declarative capability sheet every engine adapter advertises. */
-export interface SandboxCapabilities {
-    readonly isolation: 'wasm-sandbox' | 'syscall-interception' | 'microvm' | 'browser' | 'cloud-sandbox' | 'container-vm';
-    readonly snapshotting: boolean;
-    readonly networkEgress: boolean;
-    readonly gpu: boolean;
-    readonly selfHosted: boolean;
-    readonly requiresKvm: boolean;
-}
-/** The common interface every adapter implements. */
-export interface SandboxEngine {
-    readonly id: string;
-    readonly title: string;
-    readonly category: string;
-    readonly version: string;
-    readonly capabilities: SandboxCapabilities;
-    create(spec: SandboxSpec): Promise<SandboxHandle>;
-    exec(sandboxId: string, command: readonly string[]): Promise<ExecResult>;
-    snapshot(sandboxId: string): Promise<SnapshotRef>;
-    destroy(sandboxId: string): Promise<void>;
-    metrics(sandboxId: string): SandboxMetrics;
-}
-/** Error raised for unknown sandboxes or unsupported capabilities. */
-export declare class SandboxEngineError extends Error {
-    readonly engine: string;
-    constructor(engine: string, message: string);
-}
-/** Picks an ephemeral port; the engine never hardcodes endpoints. */
-export declare function randomPort(): number;
-/**
- * Base class consolidating lifecycle bookkeeping so each adapter only
- * declares its engine-specific facts and behaviors.
- */
-declare abstract class BaseEngine implements SandboxEngine {
-    #private;
-    abstract readonly id: string;
-    abstract readonly title: string;
-    abstract readonly category: string;
-    abstract readonly version: string;
-    abstract readonly capabilities: SandboxCapabilities;
-    /** Documented cold start in milliseconds (used by the latency model). */
-    protected abstract get coldBootMs(): number;
-    /** Extra per-call latency the isolation layer adds (0-0.3 for gVisor-like). */
-    protected abstract get execOverheadRatio(): number;
-    create(spec: SandboxSpec): Promise<SandboxHandle>;
-    exec(sandboxId: string, command: readonly string[]): Promise<ExecResult>;
-    snapshot(sandboxId: string): Promise<SnapshotRef>;
-    protected abstract snapshotBackend(): SnapshotRef['backend'];
-    destroy(sandboxId: string): Promise<void>;
-    metrics(sandboxId: string): SandboxMetrics;
-    /** Process overhead each sandbox costs on the host. */
-    protected perSandboxOverheadMiB(): number;
-}
-/**
- * Adapter 1/10 - Wasmtime v48.0.0.
- * Runs guest components with fuel metering for deterministic budgets and
- * epoch interruption for wall-clock timeouts (~10% overhead, preferred over
- * fuel for timeouts). WASI 0.3.0 gives native async; components start with
- * deny-by-default capabilities.
- */
-export declare class WasmtimeEngine extends BaseEngine {
-    #private;
-    readonly id: 'wasmtime';
-    readonly title = "Wasmtime + WASI 0.3 components";
-    readonly category: 'wasm runtime sandbox';
-    readonly version: '48.0.0';
-    readonly capabilities: {
-        readonly isolation: 'wasm-sandbox';
-        readonly snapshotting: true;
-        readonly networkEgress: false;
-        readonly gpu: false;
-        readonly selfHosted: true;
-        readonly requiresKvm: false;
-    };
-    /** Sets the per-store fuel budget, the `--fuel` equivalent. */
-    setFuelBudget(budget: number): this;
-    /** Sets the epoch deadline used to interrupt runaway guests. */
-    setEpochDeadline(deadlineMs: number): this;
-    /**
-     * Interrupt policy handed to the embedding host: epoch interruption traps
-     * the guest at the deadline with roughly 10% runtime overhead, which beats
-     * fuel accounting for wall-clock timeouts.
-     */
-    interruptPolicy(): {
-        deadlineMs: number;
-        mechanism: 'epoch';
-        relativeOverhead: number;
-    };
-    /** Command line that runs a component under both guards. */
-    runCommand(componentPath: string): string[];
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 2/10 - gVisor runsc.
- * The Sentry intercepts syscalls through the systrap platform (seccomp
- * SECCOMP_RET_TRAP delivering SIGSYS), paying 10-30% on I/O-heavy workloads
- * (up to 2x on syscall-bound ones). DirectFS narrows the filesystem gap;
- * io_uring stays disabled by default for security.
- */
-export declare class GvisorEngine extends BaseEngine {
-    #private;
-    readonly id: 'gvisor';
-    readonly title = "gVisor runsc (systrap)";
-    readonly category: 'user-space kernel';
-    readonly version: 'release-20260817.0';
-    readonly capabilities: {
-        readonly isolation: 'syscall-interception';
-        readonly snapshotting: false;
-        readonly networkEgress: true;
-        readonly gpu: false;
-        readonly selfHosted: true;
-        readonly requiresKvm: false;
-    };
-    setPlatform(platform: 'systrap' | 'ptrace' | 'kvm'): this;
-    /** daemon.json fragment selecting runsc plus the runtime flag docker uses. */
-    dockerFlags(): {
-        daemonJson: string;
-        runFlag: string[];
-        platformFlag: string[];
-    };
-    /** DirectFS shortens the filesystem path by letting the Sentry talk to the host FD directly. */
-    get directFsEnabled(): boolean;
-    /** Documented I/O overhead band relative to runc. */
-    overheadBand(): {
-        low: number;
-        high: number;
-        syscallBoundWorst: number;
-    };
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 3/10 - Kata Containers 4.1.0.
- * Runtime-rs (the Rust runtime, default since 4.0; the Go runtime is
- * deprecated and freezes at bugfix-only) drives hardware-isolated
- * microVMs. 4.1 adds OpenVMM support, Cloud Hypervisor VM templates,
- * configurable nested virtualization and NVSwitch passthrough via IOMMUFD.
- */
-export declare class KataEngine extends BaseEngine {
-    #private;
-    readonly id: 'kata';
-    readonly title = "Kata Containers runtime-rs";
-    readonly category: 'microvm container runtime';
-    readonly version: '4.1.0';
-    readonly capabilities: {
-        readonly isolation: 'container-vm';
-        readonly snapshotting: true;
-        readonly networkEgress: true;
-        readonly gpu: true;
-        readonly selfHosted: true;
-        readonly requiresKvm: true;
-    };
-    setHypervisor(hypervisor: 'cloud-hypervisor' | 'firecracker' | 'qemu' | 'dragonball' | 'openvmm'): this;
-    /** kata-runtime configuration fragments for the selected hypervisor. */
-    configurationToml(): string[];
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected perSandboxOverheadMiB(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 4/10 - Cloud Hypervisor v53.0.
- * Rust VMM built from rust-vmm crates (KVM and MSHV backends). v53 ships an
- * offloaded snapshot/restore daemon built on userfaultfd plus vhost-user,
- * migratable VFIO devices on the same host (for example mlx5_vfio_pci) and
- * experimental vfio-user devices through --user-device socket=<path>.
- */
-export declare class CloudHypervisorEngine extends BaseEngine {
-    readonly id: 'cloud-hypervisor';
-    readonly title = "Cloud Hypervisor (rust-vmm)";
-    readonly category: 'rust VMM';
-    readonly version: '53.0';
-    readonly capabilities: {
-        readonly isolation: 'microvm';
-        readonly snapshotting: true;
-        readonly networkEgress: true;
-        readonly gpu: true;
-        readonly selfHosted: true;
-        readonly requiresKvm: true;
-    };
-    /** Command line for a software-isolated guest with the snapshot daemon. */
-    launchCommand(cpus: number, memoryMb: number): string[];
-    /** vfio-user device attach command (experimental in v53). */
-    attachUserDevice(socketPath: string): string[];
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected perSandboxOverheadMiB(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 5/10 - WebContainers (StackBlitz).
- * Runs Node.js and npm entirely inside the browser sandbox over WebAssembly;
- * boot is measured in milliseconds and the host contributes zero server
- * footprint. The API is a commercial GA product; this adapter models the
- * client-side contract (boot, command execution, teardown) for parity with
- * server-side engines.
- */
-export declare class WebContainersEngine extends BaseEngine {
-    readonly id: 'webcontainers';
-    readonly title = "WebContainers (Node.js in the browser)";
-    readonly category: 'browser runtime';
-    readonly version: 'ga';
-    readonly capabilities: {
-        readonly isolation: 'browser';
-        readonly snapshotting: false;
-        readonly networkEgress: false;
-        readonly gpu: false;
-        readonly selfHosted: false;
-        readonly requiresKvm: false;
-    };
-    /** Client bootstrap snippet the host page evaluates. */
-    bootstrapSnippet(): string;
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected perSandboxOverheadMiB(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 6/10 - Daytona.
- * Creates stateful sandboxes in ~90ms, exposes MCP (Model Context Protocol)
- * servers for agent integration, and can be self-hosted from the open-source
- * core (the SaaS adds managed control planes and $200 of free compute).
- */
-export declare class DaytonaEngine extends BaseEngine {
-    #private;
-    readonly id: 'daytona';
-    readonly title = "Daytona sandboxes";
-    readonly category: 'self-hosted sandbox platform';
-    readonly version: 'oss+saas';
-    readonly capabilities: {
-        readonly isolation: 'cloud-sandbox';
-        readonly snapshotting: true;
-        readonly networkEgress: true;
-        readonly gpu: false;
-        readonly selfHosted: true;
-        readonly requiresKvm: false;
-    };
-    /** MCP server descriptor published for agent discovery. */
-    mcpDescriptor(): {
-        name: string;
-        transport: string;
-        tools: string[];
-    };
-    setRegion(region: string): this;
-    get region(): string;
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 7/10 - Modal.
- * Serverless container platform built for AI workloads: 100k+ concurrent
- * sandboxes per account, sub-second scheduling, elastic GPUs and sessions
- * up to 24 hours. Python-first (JavaScript is secondary), with strong
- * cold-start behavior for custom images.
- */
-export declare class ModalEngine extends BaseEngine {
-    #private;
-    readonly id: 'modal';
-    readonly title = "Modal serverless sandboxes";
-    readonly category: 'serverless container platform';
-    readonly version: 'saas';
-    readonly capabilities: {
-        readonly isolation: 'cloud-sandbox';
-        readonly snapshotting: true;
-        readonly networkEgress: true;
-        readonly gpu: true;
-        readonly selfHosted: false;
-        readonly requiresKvm: false;
-    };
-    /** Concurrency ceiling the platform documents per account. */
-    get concurrencyCeiling(): number;
-    /** Scheduling latency band: warm functions resume in milliseconds. */
-    schedulingBand(): {
-        warmMs: number;
-        coldMs: number;
-        maxSessionHours: number;
-    };
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 8/10 - Fly.io Machines.
- * Firecracker microVMs (the same foundation as AWS Lambda and Fargate)
- * started and stopped through a global API across roughly 35 regions.
- * Machines boot sub-second, snapshot fast and are addressable by private
- * network, which makes them a natural multi-region sandbox backend.
- */
-export declare class FlyMachinesEngine extends BaseEngine {
-    #private;
-    readonly id: 'fly-machines';
-    readonly title = "Fly.io Machines (global Firecracker)";
-    readonly category: 'global microVM API';
-    readonly version: 'saas';
-    readonly capabilities: {
-        readonly isolation: 'microvm';
-        readonly snapshotting: true;
-        readonly networkEgress: true;
-        readonly gpu: false;
-        readonly selfHosted: false;
-        readonly requiresKvm: false;
-    };
-    setPrimaryRegion(region: string): this;
-    /** Region set the API can place machines in (2026 count: about 35). */
-    regionCount(): number;
-    get primaryRegion(): string;
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected perSandboxOverheadMiB(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/** Member of the E2B-derived family covered by the facts table. */
-export type E2bFamilyVariant = 'e2b' | 'morph' | 'cognitora' | 'vercel-sandbox';
-/** Verified facts for each member of the E2B family. */
-export declare const e2bFamilyFacts: Readonly<Record<E2bFamilyVariant, {
-    title: string;
-    coldBootMs: number;
-    snapshot: boolean;
-    note: string;
-}>>;
-/**
- * Adapter 9/10 - the E2B family.
- * One adapter implementation covers E2B and its direct competitors; the
- * variant selects documented cold-start, snapshot support and positioning
- * so comparisons stay apples-to-apples.
- */
-export declare class E2bFamilyEngine extends BaseEngine {
-    readonly variant: E2bFamilyVariant;
-    constructor(variant?: E2bFamilyVariant);
-    get id(): string;
-    get title(): string;
-    readonly category: 'AI-first sandbox cloud';
-    readonly version: 'saas';
-    get capabilities(): SandboxCapabilities;
-    positioning(): string;
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected perSandboxOverheadMiB(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/**
- * Adapter 10/10 - Apple Containers 1.2.2.
- * Swift open-source project running each Linux container inside a lightweight
- * microVM optimized for Apple Silicon; boot lands under one second. WWDC26
- * (2026-06-08) added "container machines" - persistent lightweight Linux
- * environments configured through TOML.
- */
-export declare class AppleContainersEngine extends BaseEngine {
-    #private;
-    readonly id: 'apple-containers';
-    readonly title = "Apple Containers (Swift microVMs on macOS)";
-    readonly category: 'macOS container runtime';
-    readonly version: '1.2.2';
-    readonly capabilities: {
-        readonly isolation: 'container-vm';
-        readonly snapshotting: false;
-        readonly networkEgress: true;
-        readonly gpu: false;
-        readonly selfHosted: true;
-        readonly requiresKvm: false;
-    };
-    /** Enables WWDC26 container machines (persistent Linux environments). */
-    useContainerMachines(enabled: boolean): this;
-    /** CLI invocation plus TOML config path when machine mode is active. */
-    runCommand(image: string): string[];
-    protected get coldBootMs(): number;
-    protected get execOverheadRatio(): number;
-    protected perSandboxOverheadMiB(): number;
-    protected snapshotBackend(): SnapshotRef['backend'];
-}
-/** Registry entry: identity, category, version and snapshot support. */
-export interface EngineDescriptor {
-    readonly id: string;
-    readonly title: string;
-    readonly category: string;
-    readonly version: string;
-    readonly snapshotting: boolean;
-}
-/**
- * Factory registry: hosts register constructors, create engines lazily and
- * resolve aliases (for example "runsc" resolves to gvisor). Unknown ids
- * produce a helpful error listing the closest known ids.
- */
-export declare class EngineRegistry {
-    #private;
-    register(id: string, factory: () => SandboxEngine, aliases?: readonly string[]): this;
-    /** Creates (or reuses) the engine registered under id or one of its aliases. */
-    create(id: string): SandboxEngine;
-    list(): EngineDescriptor[];
-    get size(): number;
-}
-/** Registry pre-loaded with all ten engine categories. */
-export declare function createDefaultEngineRegistry(): EngineRegistry;
-/** One flattened row of the cross-engine comparison matrix. */
-export interface ComparisonRow {
-    readonly engine: string;
-    readonly category: string;
-    readonly version: string;
-    readonly bootMs: number;
-    readonly overhead: string;
-    readonly isolation: string;
-    readonly snapshot: string;
-    readonly hosting: string;
-    readonly standout: string;
-}
-/**
- * Comparison matrix with the data verified on 2026-08-22. Boot times are the
- * documented figures each adapter models; overhead strings quote the
- * measured bands from the engine documentation.
- */
-export declare const comparisonMatrix: readonly ComparisonRow[];
-/** Renders the comparison matrix as a markdown table for docs and CI logs. */
-export declare function renderComparisonTable(matrix?: readonly ComparisonRow[]): string;
-/** Weighted selection inputs: latency and isolation weights plus hard needs. */
-export interface SelectionCriteria {
-    /** Importance of a low cold-start latency (0-10). */
-    readonly bootLatency: number;
-    /** Importance of maximum isolation strength (0-10). */
-    readonly isolation: number;
-    /** Requirement weights for specific capabilities. */
-    readonly needSnapshot: boolean;
-    readonly needGpu: boolean;
-    readonly needSelfHosted: boolean;
-}
-/**
- * Scores every registered engine against the criteria and returns them
- * ranked with a rationale. Isolation strength ranks hardware microVMs and
- * wasm above syscall interception and browser sandboxes; boot latency
- * inversely follows the documented cold-start figure.
- */
-export declare function selectEngine(registry: EngineRegistry, criteria: SelectionCriteria, matrix?: readonly ComparisonRow[]): {
-    engine: string;
-    score: number;
-    rationale: string;
-}[];
-export {};