@wenathlan/saddle 2.0.154 → 2.0.159

package/dist/sandboxenvprofile.d.ts

@@ -1,29 +0,0 @@
-/**
- * sandboxenvprofile.ts — the configuration adapter of the sandbox spec
- * plane.
- *
- * the declarative spec (sandboxprofile.ts) never holds capacities: the
- * limits table is a parameter. this module is the adapter that turns
- * configuration into that parameter: it reads the SADDLE_SPEC_LIMITS
- * json environment variable ({ "bases": { ... } }), merges it over a
- * documented development bootstrap table (so a partial override stays
- * safe) and returns the effective limits table. production deployments
- * can equally hand the database sourced table straight to
- * resolvesandboxspec and skip this adapter entirely.
- *
- * the module is browser-pure: zero dom, zero node builtins; it imports
- * only the vocabulary and types of sandboxprofile.ts. the bootstrap table
- * is a documented convenience, never a product rule — every field it
- * carries is overridable.
- */
-import type { sandboxspeclimits } from './sandboxprofile.ts';
-/**
- * reads the limits table from the SADDLE_SPEC_LIMITS environment json;
- * the bootstrap table fills every base the json does not define, so a
- * partial override stays safe. broken json falls back to the bootstrap
- * table (the spec plane never becomes unavailable over config drift).
- *
- * @param env the environment record (process.env shaped).
- * @returns the effective limits table.
- */
-export declare function specenvlimits(env: Record<string, string | undefined>): sandboxspeclimits;

package/dist/sandboxenvprofile.js

@@ -1,89 +0,0 @@
-/**
- * sandboxenvprofile.ts — the configuration adapter of the sandbox spec
- * plane.
- *
- * the declarative spec (sandboxprofile.ts) never holds capacities: the
- * limits table is a parameter. this module is the adapter that turns
- * configuration into that parameter: it reads the SADDLE_SPEC_LIMITS
- * json environment variable ({ "bases": { ... } }), merges it over a
- * documented development bootstrap table (so a partial override stays
- * safe) and returns the effective limits table. production deployments
- * can equally hand the database sourced table straight to
- * resolvesandboxspec and skip this adapter entirely.
- *
- * the module is browser-pure: zero dom, zero node builtins; it imports
- * only the vocabulary and types of sandboxprofile.ts. the bootstrap table
- * is a documented convenience, never a product rule — every field it
- * carries is overridable.
- */
-import { SANDBOXBASES } from './sandboxprofile.ts';
-/** documented development bootstrap table; production overrides it with
- * the SADDLE_SPEC_LIMITS json (or the database table). fields: maxvcpus/
- * maxramgb/maxvgpus/maxdiskgb/maxtimeoutseconds/defaultvcpus/
- * defaultramgb. */
-const bootstraplimits = {
-    bases: {
-        lite: {
-            maxvcpus: 4,
-            maxramgb: 8,
-            maxvgpus: 0,
-            maxdiskgb: 32,
-            maxtimeoutseconds: 900,
-            defaultvcpus: 2,
-            defaultramgb: 4,
-        },
-        balanced: {
-            maxvcpus: 16,
-            maxramgb: 32,
-            maxvgpus: 1,
-            maxdiskgb: 128,
-            maxtimeoutseconds: 3600,
-            defaultvcpus: 8,
-            defaultramgb: 16,
-        },
-        max: {
-            maxvcpus: 64,
-            maxramgb: 256,
-            maxvgpus: 2,
-            maxdiskgb: 512,
-            maxtimeoutseconds: 14400,
-            defaultvcpus: 32,
-            defaultramgb: 64,
-        },
-    },
-    defaulttimeoutseconds: 900,
-};
-/**
- * reads the limits table from the SADDLE_SPEC_LIMITS environment json;
- * the bootstrap table fills every base the json does not define, so a
- * partial override stays safe. broken json falls back to the bootstrap
- * table (the spec plane never becomes unavailable over config drift).
- *
- * @param env the environment record (process.env shaped).
- * @returns the effective limits table.
- */
-export function specenvlimits(env) {
-    const raw = env.SADDLE_SPEC_LIMITS;
-    if (raw === undefined || raw.trim() === '') {
-        return bootstraplimits;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        const bases = { ...bootstraplimits.bases };
-        if (typeof parsed?.bases === 'object' && parsed.bases !== null) {
-            for (const key of SANDBOXBASES) {
-                const override = parsed.bases[key];
-                if (typeof override === 'object' && override !== null) {
-                    bases[key] = {
-                        ...bootstraplimits.bases[key],
-                        ...override,
-                    };
-                }
-            }
-        }
-        return { ...bootstraplimits, bases };
-    }
-    catch {
-        return bootstraplimits;
-    }
-}

package/dist/sandboxprofile.d.ts

@@ -1,137 +0,0 @@
-/**
- * sandboxprofile.ts — the declarative sandbox specification of saddle.
- *
- * a saddle sandbox is declared, never assembled: one request names the
- * base (max, balanced or lite), the guest operating system (android,
- * grapheneos, linux, omarchy, windows), the cpu architecture (arm64 or
- * amd64), the runtime form (runtime-node, full-docker, published) and
- * the optional resource wishes (vcpus, ramgb, vgpu, diskgb, timeout,
- * networking). this module owns that vocabulary: it validates one
- * declared spec against a caller supplied limits table and resolves it
- * into concrete values the engine surface consumes.
- *
- * nothing about capacities lives in code: the limits table is a plain
- * parameter (config, environment or database). the environment adapter
- * lives in sandboxenvprofile.ts (SADDLE_SPEC_LIMITS json over a
- * documented bootstrap table).
- *
- * the module is browser-pure like sandbox.ts: zero imports, zero dom,
- * zero node builtins, deterministic verdicts. errors are typed and
- * traceable — every sandboxspecerror carries a machine readable code,
- * the offending field, the received value and the expectation missed.
- *
- * competitor sources shaping the contract: opensandbox-group/
- * opensandbox (declared timeoutSeconds bounded by the server side
- * max_sandbox_timeout_seconds; declared resources on the create
- * request) and daytonaio/daytona (per-sandbox cpu/memory/disk quota
- * fields with min=1 validation; gpu admission before create).
- *
- * wire points (kept honest): webserver.ts createsandbox validates the
- * optional base/os/arch/form fields here before building the engine
- * spec; sandbox.ts createSandboxState stays the hardware identity
- * layer and receives the resolved vcpus/ramgb untouched.
- */
-/** the three runtime bases of the saddle fleet. */
-export type sandboxbaseid = 'max' | 'balanced' | 'lite';
-/** the guest operating systems a sandbox can boot. */
-export type sandboxosid = 'android' | 'grapheneos' | 'linux' | 'omarchy' | 'windows';
-/** the guest cpu architectures (amd64 == the x86_64 of the engine bank). */
-export type sandboxarchid = 'arm64' | 'amd64';
-/** the runtime forms of a published sandbox. */
-export type sandboxformid = 'runtime-node' | 'full-docker' | 'published';
-/** the networking modes of a sandbox. */
-export type sandboxnetworkid = 'nat' | 'bridged' | 'isolated';
-/** the os family a guest belongs to (android builds on the linux kernel). */
-export type sandboxosfamily = 'android' | 'linux' | 'windows';
-/** fixed product vocabulary; only the capacities are configuration. */
-export declare const SANDBOXBASES: readonly sandboxbaseid[];
-export declare const SANDBOXOSES: readonly sandboxosid[];
-export declare const SANDBOXARCHES: readonly sandboxarchid[];
-export declare const SANDBOXFORMS: readonly sandboxformid[];
-export declare const SANDBOXNETWORKS: readonly sandboxnetworkid[];
-/** one base row of the limits table: ceilings and defaults per base. */
-export type sandboxbaselimit = {
-    readonly maxvcpus: number;
-    readonly maxramgb: number;
-    readonly maxvgpus: number;
-    readonly maxdiskgb: number;
-    readonly maxtimeoutseconds: number;
-    readonly defaultvcpus: number;
-    readonly defaultramgb: number;
-};
-/** the full limits table handed to the resolver by the caller. */
-export type sandboxspeclimits = {
-    readonly bases: Readonly<Record<sandboxbaseid, sandboxbaselimit>>;
-    readonly defaulttimeoutseconds?: number;
-};
-/** the declared request shape (every field is optional or unknown). */
-export type sandboxspecinput = Record<string, unknown>;
-/** the resolved spec: concrete values validated against the limits. */
-export type resolvedsandboxspec = {
-    readonly base: sandboxbaseid;
-    readonly os: sandboxosid;
-    readonly arch: sandboxarchid;
-    readonly form: sandboxformid;
-    readonly networking: sandboxnetworkid;
-    readonly family: sandboxosfamily;
-    readonly vcpus: number;
-    readonly ramgb: number;
-    readonly vgpu: boolean;
-    readonly diskgb: number | null;
-    readonly timeoutseconds: number;
-};
-/** every failure code the resolver can produce. */
-export type sandboxspecerrorcode = 'invalid-spec' | 'missing-base' | 'invalid-base' | 'invalid-os' | 'invalid-arch' | 'invalid-form' | 'invalid-networking' | 'invalid-vcpus' | 'invalid-ramgb' | 'invalid-vgpu' | 'invalid-diskgb' | 'invalid-timeout' | 'timeout-above-limit' | 'vgpu-not-available' | 'unknown-base-limits';
-/** the typed spec failure: code, field, received value and expectation. */
-export declare class sandboxspecerror extends Error {
-    /** machine readable failure code. */
-    readonly code: sandboxspecerrorcode;
-    /** the declared field that failed (or 'spec' for envelope failures). */
-    readonly field: string;
-    /** the received value, json-safe. */
-    readonly value: unknown;
-    /** the expectation the value missed. */
-    readonly expected: string;
-    constructor(code: sandboxspecerrorcode, field: string, value: unknown, expected: string, message?: string);
-}
-/**
- * validates one declared spec against the limits table and resolves it
- * into concrete values. the verdict is a discriminated result so
- * callers surface the typed error without try/catch.
- *
- * @param input the declared spec (unknown json is tolerated).
- * @param limits the limits table (config, env or database sourced).
- * @returns the resolved spec or the typed, traceable error.
- */
-export declare function resolvesandboxspec(input: unknown, limits: sandboxspeclimits): {
-    ok: true;
-    value: resolvedsandboxspec;
-} | {
-    ok: false;
-    error: sandboxspecerror;
-};
-/** maps a guest os onto its kernel family (grapheneos builds on aosp). */
-export declare function osfamily(os: sandboxosid): sandboxosfamily;
-/** the structural shape consumed by sandbox.ts createSandboxState. */
-export type sandboxenginespec = {
-    readonly model: string;
-    readonly vcpus: number;
-    readonly ramgb: number;
-    readonly gpu: string;
-    readonly mig: string;
-};
-/**
- * bridges a resolved spec onto the engine surface: vcpus and ramgb come
- * from the resolved spec, the cpu model and gpu identity stay caller
- * choices (the reviewed catalog of sandbox.ts remains the only source
- * of processor and gpu identity).
- *
- * @param resolved the resolved spec produced by resolvesandboxspec.
- * @param options the caller picked engine identities (model, gpu, mig).
- * @returns the engine spec object.
- */
-export declare function enginespecfor(resolved: resolvedsandboxspec, options?: {
-    model?: string;
-    gpu?: string;
-    mig?: string;
-}): sandboxenginespec;

package/dist/sandboxprofile.js

@@ -1,241 +0,0 @@
-/**
- * sandboxprofile.ts — the declarative sandbox specification of saddle.
- *
- * a saddle sandbox is declared, never assembled: one request names the
- * base (max, balanced or lite), the guest operating system (android,
- * grapheneos, linux, omarchy, windows), the cpu architecture (arm64 or
- * amd64), the runtime form (runtime-node, full-docker, published) and
- * the optional resource wishes (vcpus, ramgb, vgpu, diskgb, timeout,
- * networking). this module owns that vocabulary: it validates one
- * declared spec against a caller supplied limits table and resolves it
- * into concrete values the engine surface consumes.
- *
- * nothing about capacities lives in code: the limits table is a plain
- * parameter (config, environment or database). the environment adapter
- * lives in sandboxenvprofile.ts (SADDLE_SPEC_LIMITS json over a
- * documented bootstrap table).
- *
- * the module is browser-pure like sandbox.ts: zero imports, zero dom,
- * zero node builtins, deterministic verdicts. errors are typed and
- * traceable — every sandboxspecerror carries a machine readable code,
- * the offending field, the received value and the expectation missed.
- *
- * competitor sources shaping the contract: opensandbox-group/
- * opensandbox (declared timeoutSeconds bounded by the server side
- * max_sandbox_timeout_seconds; declared resources on the create
- * request) and daytonaio/daytona (per-sandbox cpu/memory/disk quota
- * fields with min=1 validation; gpu admission before create).
- *
- * wire points (kept honest): webserver.ts createsandbox validates the
- * optional base/os/arch/form fields here before building the engine
- * spec; sandbox.ts createSandboxState stays the hardware identity
- * layer and receives the resolved vcpus/ramgb untouched.
- */
-/** fixed product vocabulary; only the capacities are configuration. */
-export const SANDBOXBASES = ['max', 'balanced', 'lite'];
-export const SANDBOXOSES = [
-    'android',
-    'grapheneos',
-    'linux',
-    'omarchy',
-    'windows',
-];
-export const SANDBOXARCHES = ['arm64', 'amd64'];
-export const SANDBOXFORMS = ['runtime-node', 'full-docker', 'published'];
-export const SANDBOXNETWORKS = ['nat', 'bridged', 'isolated'];
-/** the typed spec failure: code, field, received value and expectation. */
-export class sandboxspecerror extends Error {
-    /** machine readable failure code. */
-    code;
-    /** the declared field that failed (or 'spec' for envelope failures). */
-    field;
-    /** the received value, json-safe. */
-    value;
-    /** the expectation the value missed. */
-    expected;
-    constructor(code, field, value, expected, message) {
-        super(message ?? `sandbox spec field "${field}" ${expected} (received ${show(value)})`);
-        this.name = 'sandboxspecerror';
-        this.code = code;
-        this.field = field;
-        this.value = value;
-        this.expected = expected;
-    }
-}
-/** renders a json-safe preview of any received value for error messages. */
-function show(value) {
-    if (typeof value === 'string') {
-        return JSON.stringify(value);
-    }
-    if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
-        return String(value);
-    }
-    if (value === undefined) {
-        return 'undefined';
-    }
-    return Array.isArray(value) ? 'an array' : typeof value;
-}
-/** picks the matching member of a fixed vocabulary; undefined otherwise. */
-function memberof(vocabulary, value) {
-    return typeof value === 'string'
-        ? vocabulary.find((item) => item === value)
-        : undefined;
-}
-/** validates a positive integer wish; null when the shape is wrong. */
-function positiveinteger(value) {
-    return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : null;
-}
-/* ------------------------------------------------------------------ */
-/* the resolver                                                        */
-/* ------------------------------------------------------------------ */
-/**
- * validates one declared spec against the limits table and resolves it
- * into concrete values. the verdict is a discriminated result so
- * callers surface the typed error without try/catch.
- *
- * @param input the declared spec (unknown json is tolerated).
- * @param limits the limits table (config, env or database sourced).
- * @returns the resolved spec or the typed, traceable error.
- */
-export function resolvesandboxspec(input, limits) {
-    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
-        return {
-            ok: false,
-            error: new sandboxspecerror('invalid-spec', 'spec', input, 'a plain object'),
-        };
-    }
-    const declared = input;
-    const base = memberof(SANDBOXBASES, declared.base);
-    if (base === undefined) {
-        return {
-            ok: false,
-            error: declared.base === undefined
-                ? new sandboxspecerror('missing-base', 'base', undefined, `one of ${SANDBOXBASES.join(', ')}`)
-                : new sandboxspecerror('invalid-base', 'base', declared.base, `one of ${SANDBOXBASES.join(', ')}`),
-        };
-    }
-    const row = limits.bases[base];
-    if (row === undefined) {
-        return {
-            ok: false,
-            error: new sandboxspecerror('unknown-base-limits', 'base', base, 'a base present in the limits table'),
-        };
-    }
-    // fixed vocabularies: a present but unknown member is a typed error.
-    const words = [
-        ['os', SANDBOXOSES, 'invalid-os'],
-        ['arch', SANDBOXARCHES, 'invalid-arch'],
-        ['form', SANDBOXFORMS, 'invalid-form'],
-        ['networking', SANDBOXNETWORKS, 'invalid-networking'],
-    ];
-    for (const [field, vocabulary, code] of words) {
-        if (declared[field] !== undefined && !memberof(vocabulary, declared[field])) {
-            return {
-                ok: false,
-                error: new sandboxspecerror(code, field, declared[field], `one of ${vocabulary.join(', ')}`),
-            };
-        }
-    }
-    // resource wishes: positive integers bounded by the base ceiling.
-    const ceilings = [
-        ['vcpus', 'invalid-vcpus', row.maxvcpus],
-        ['ramgb', 'invalid-ramgb', row.maxramgb],
-        ['diskgb', 'invalid-diskgb', row.maxdiskgb],
-    ];
-    for (const [field, code, ceiling] of ceilings) {
-        if (declared[field] === undefined) {
-            continue;
-        }
-        const wish = positiveinteger(declared[field]);
-        if (wish === null) {
-            return {
-                ok: false,
-                error: new sandboxspecerror(code, field, declared[field], 'a positive integer'),
-            };
-        }
-        if (wish > ceiling) {
-            return {
-                ok: false,
-                error: new sandboxspecerror(code, field, declared[field], `an integer between 1 and ${ceiling} on the ${base} base`),
-            };
-        }
-    }
-    let vgpu = false;
-    if (declared.vgpu !== undefined && typeof declared.vgpu !== 'boolean') {
-        return {
-            ok: false,
-            error: new sandboxspecerror('invalid-vgpu', 'vgpu', declared.vgpu, 'a boolean'),
-        };
-    }
-    vgpu = declared.vgpu === true;
-    if (vgpu && row.maxvgpus < 1) {
-        return {
-            ok: false,
-            error: new sandboxspecerror('vgpu-not-available', 'vgpu', true, `a base with vgpu slices (the ${base} base exposes none)`),
-        };
-    }
-    const defaulttimeout = limits.defaulttimeoutseconds ?? 900;
-    let timeoutseconds = defaulttimeout;
-    if (declared.timeoutseconds !== undefined) {
-        const wish = positiveinteger(declared.timeoutseconds);
-        if (wish === null) {
-            return {
-                ok: false,
-                error: new sandboxspecerror('invalid-timeout', 'timeoutseconds', declared.timeoutseconds, 'a positive integer of seconds'),
-            };
-        }
-        if (wish > row.maxtimeoutseconds) {
-            return {
-                ok: false,
-                error: new sandboxspecerror('timeout-above-limit', 'timeoutseconds', declared.timeoutseconds, `at most ${row.maxtimeoutseconds} seconds on the ${base} base`),
-            };
-        }
-        timeoutseconds = wish;
-    }
-    const os = (memberof(SANDBOXOSES, declared.os) ?? 'linux');
-    return {
-        ok: true,
-        value: {
-            base,
-            os,
-            arch: (memberof(SANDBOXARCHES, declared.arch) ?? 'amd64'),
-            form: (memberof(SANDBOXFORMS, declared.form) ?? 'runtime-node'),
-            networking: (memberof(SANDBOXNETWORKS, declared.networking) ?? 'nat'),
-            family: osfamily(os),
-            vcpus: declared.vcpus ?? row.defaultvcpus,
-            ramgb: declared.ramgb ?? row.defaultramgb,
-            vgpu,
-            diskgb: declared.diskgb ?? null,
-            timeoutseconds,
-        },
-    };
-}
-/* ------------------------------------------------------------------ */
-/* helpers and bridges                                                 */
-/* ------------------------------------------------------------------ */
-/** maps a guest os onto its kernel family (grapheneos builds on aosp). */
-export function osfamily(os) {
-    if (os === 'android' || os === 'grapheneos') {
-        return 'android';
-    }
-    return os === 'windows' ? 'windows' : 'linux';
-}
-/**
- * bridges a resolved spec onto the engine surface: vcpus and ramgb come
- * from the resolved spec, the cpu model and gpu identity stay caller
- * choices (the reviewed catalog of sandbox.ts remains the only source
- * of processor and gpu identity).
- *
- * @param resolved the resolved spec produced by resolvesandboxspec.
- * @param options the caller picked engine identities (model, gpu, mig).
- * @returns the engine spec object.
- */
-export function enginespecfor(resolved, options) {
-    return {
-        model: options?.model ?? '',
-        vcpus: resolved.vcpus,
-        ramgb: resolved.ramgb,
-        gpu: resolved.vgpu ? (options?.gpu ?? '') : '',
-        mig: options?.mig ?? 'off',
-    };
-}

package/dist/sandboxqueue.d.ts

@@ -1,108 +0,0 @@
-/**
- * sandboxqueue.ts — the sandbox lifecycle queue of saddle.
- *
- * one sandbox walks a single linear machine: creating -> starting ->
- * running -> stopping -> stopped, with the supervision states cancelled,
- * failed and timedout closing the paths out. every intermediate state
- * carries a per-state time budget; the health-check tick reaps entries
- * whose budget expired (the ttl reaper pattern of webserver.ts and the
- * pool reaper of opensandbox). transitions are validated by a pure
- * transition table so both callers and tests exercise the same guard.
- *
- * the module is deliberately pure: no timers of its own, no dom, no node
- * builtins, an injectable clock. hosts drive it — webserver.ts ramps
- * the api lifecycle with a timeout, the ttl reaper sweeps every minute,
- * and orchestrator.ts owns the fifteen state vm plane machine; this
- * module is the queue-level complement those surfaces can delegate to
- * (wire point documented in the webserver statemachine context: the
- * api states map as created->creating, expired->timedout,
- * destroyed->stopped).
- *
- * studied competitors shaping the contract: daytonaio/daytona (sandbox
- * states creating/starting/started/stopping/stopped/error with the
- * -ing intermediates) and opensandbox-group/opensandbox (Creating ->
- * Running -> Deleting -> Deleted with 409 on state conflicting
- * operations and a pool acquisition that fails fast with Retry-After).
- */
-/** every phase of the sandbox lifecycle queue. */
-export type sandboxphase = 'creating' | 'starting' | 'running' | 'stopping' | 'stopped' | 'cancelled' | 'failed' | 'timedout';
-/** phases that end the queue entry (no further transition is legal). */
-export declare const SANDBOXTERMINALPHASES: readonly sandboxphase[];
-/** per-state time budgets in milliseconds; a state without a budget
- * never times out (running typically relies on the host ttl instead). */
-export type sandboxphasebudgets = {
-    readonly creating?: number;
-    readonly starting?: number;
-    readonly running?: number;
-    readonly stopping?: number;
-};
-/** one queue entry: identity, phase, bookkeeping. */
-export type sandboxqueueentry = {
-    readonly id: string;
-    state: sandboxphase;
-    /** epoch ms of the last phase change. */
-    enteredat: number;
-    /** epoch ms the current phase budget expires; null when unbounded. */
-    deadline: number | null;
-};
-/** one recorded lifecycle event (bounded ring, newest last). */
-export type sandboxqueueevent = {
-    readonly id: string;
-    readonly from: sandboxphase;
-    readonly to: sandboxphase;
-    readonly at: number;
-    readonly reason: 'requested' | 'timeout' | 'cancel';
-};
-/** failure codes carried by sandboxqueueerror. */
-export type sandboxqueueerrorcode = 'unknown-sandbox' | 'duplicate-sandbox' | 'invalid-transition' | 'terminal-phase';
-/** the typed queue failure, traceable to the entry and both phases. */
-export declare class sandboxqueueerror extends Error {
-    /** machine readable failure code. */
-    readonly code: sandboxqueueerrorcode;
-    /** the entry the failure belongs to. */
-    readonly id: string;
-    /** the phase the entry was in (or from), when known. */
-    readonly from: sandboxphase | null;
-    /** the requested target phase, when known. */
-    readonly to: sandboxphase | null;
-    constructor(code: sandboxqueueerrorcode, id: string, from: sandboxphase | null, to: sandboxphase | null, message?: string);
-}
-/** checks whether a phase change is legal on the single machine. */
-export declare function cansandboxstep(from: sandboxphase, to: sandboxphase): boolean;
-/** reports whether a phase is terminal. */
-export declare function issandboxterminal(phase: sandboxphase): boolean;
-/** options of createsandboxqueue (all optional, sane defaults). */
-export type sandboxqueueoptions = {
-    /** per-state budgets; the defaults mirror the 125 ms api ramp. */
-    readonly budgets?: sandboxphasebudgets;
-    /** event ring capacity (default 100). */
-    readonly eventcap?: number;
-};
-/** a read-only status view answered by status(). */
-export type sandboxqueuestatus = {
-    readonly id: string;
-    readonly state: sandboxphase;
-    readonly enteredat: number;
-    readonly deadline: number | null;
-    readonly age: number;
-    readonly terminal: boolean;
-};
-/**
- * creates the lifecycle queue. the queue validates every transition,
- * stamps deadlines from the budgets and reaps expired entries on the
- * health-check tick; the host decides when to tick.
- *
- * @param options the budgets and event ring capacity.
- * @returns the queue facade (add, step, cancel, healthcheck, status,
- *   list, events, size).
- */
-export declare function createsandboxqueue(options?: sandboxqueueoptions): {
-    add: (id: string, now?: number) => sandboxqueueentry;
-    step: (id: string, to: sandboxphase, now?: number) => sandboxqueueentry;
-    cancel: (id: string, now?: number) => sandboxqueueentry;
-    healthcheck: (now?: number) => string[];
-    status: (id: string, now?: number) => sandboxqueuestatus;
-    list: (now?: number) => sandboxqueuestatus[];
-    events: () => sandboxqueueevent[];
-    size: () => number;
-};