@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/orchestrator.d.ts

@@ -0,0 +1,1339 @@
+/**
+ * orchestrator.ts — merged sandbox and vm orchestration for saddle v6.
+ *
+ * this file is the heaviest merge of the v2 effort (map T6): the v5
+ * orchestrator (six runtime strategies — docker 29.7.2, firecracker 1.16.1,
+ * qemu 11.1.0, cloud hypervisor 53.0, gvisor release-20260817.0, kata
+ * 4.1.0 — plus warm pool, criu 4.2.1 checkpointer and compose 5.5.0
+ * rendering) absorbs the unique subsystems of the two Meta orchestrators:
+ *
+ * from src_core_orchestrator (SADDLE v5): branded ids, Result helpers,
+ * RBAC with four default roles, resource reservations with TTL, affinity
+ * rules and NUMA aware placement, CFS-like vCPU scheduler with NUMA
+ * rebalancing, balloon controller with pressure scoring, SR-IOV GPU
+ * assignment with VFs, passage routing with latency estimation, the MTTG
+ * job queue with dependencies/retry/anti-starvation, the docker bridge
+ * with IPAM, the full spawnqemu with monitor/qmp sockets and the
+ * sleep-3600 CI fallback, health monitoring, autoscale, live migration
+ * with precopy stages, disk snapshots, checkpoints, config hot-reload,
+ * the plugin system, graceful shutdown, the audit ring, bully leader
+ * election and the OTel/Prometheus recorder.
+ *
+ * from coreorchestrator (SADDLE v6): the twelve phase guards folded into
+ * the single lifecycle machine, vCPU topology validation and pinning,
+ * vRAM balloon bounds with hugepages, GPU passthrough requests reading
+ * gpus.json, passage protocols vsock/vhost-user/ivshmem/vfio-user with
+ * latency budgets, tenant quotas with preemption, label affinity
+ * selectors In/NotIn/Exists, node drain, append-only JSONL audit per
+ * tenant, the OTLP HTTP exporter, qemu version probing, the hardware view
+ * bootstrap and the process error catcher.
+ *
+ * risk resolution (mandatory, from worklog v2-A1): exactly ONE event bus —
+ * sandboxevents extends enginebus from index.ts and every topic of the
+ * union lives in enginetopics; exactly ONE lifecycle state machine — the
+ * v5 machine extended to fifteen states absorbing VmState and VmPhase;
+ * exactly ONE metrics component — sandboxmetrics extends the MetricsStore
+ * of index.ts and the Meta OTel recorder folds into it (labels, ring and
+ * the Prometheus exporter). no class with an equivalent role is
+ * duplicated: TypedEventBus, SaddleEventBus and OtelRecorder disappear,
+ * their capabilities live inside sandboxevents and sandboxmetrics.
+ *
+ * contexts (25): runtimecatalog, performetrics, kvmdetector,
+ * lifecyclestate, sandboxspec, runhelper, portallocator+hostresolver,
+ * priorityqueue, runtimestrategy, dockerruntime, gvisor+kata,
+ * firecrackerruntime+fcapi, qemuruntime+spawnqemu, clhruntime,
+ * runtimeregistry, sandboxbuilder, sandboxhandle, sandboxevents,
+ * sandboxmetrics, sandboxfactory, sandboxproxy, warmpool, cricheckpointer,
+ * rbac+reservations+affinity, numa scheduler+balloon+gpu and the
+ * orchestrator facade (passage, docker bridge, health, autoscale,
+ * migration, snapshots, checkpoints, hot-reload, plugins, audit, leader
+ * election, otel exporter, drain, dumpstate).
+ *
+ * patterns: strategy (runtimes), factory, builder, registry, observer
+ * (single bus), proxy. rules: lowercase identifiers, english jsdoc third
+ * person, no emoji, try/catch catcher on every fallible path, node:*
+ * built-ins only, no hardcoded localhost (host resolved from interfaces
+ * or user choice, ports drawn with crypto.randomInt(30000) + 30000 unless
+ * the user pins one), internal state in Map/WeakMap containers.
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { enginetopicname, enginetopics } from './index.js';
+import { enginebus, MetricsStore } from './index.js';
+/** pinned runtime versions used across the engine; the v5 anchors
+ * replace every stale Meta version (qemu 9.1.2, docker 27.3, node
+ * 22.12.3, typescript 5.6.3) found in the merged sources. */
+declare const runtimecatalog: {
+    docker: string;
+    compose: string;
+    firecracker: string;
+    qemu: string;
+    cloudhypervisor: string;
+    gvisor: string;
+    kata: string;
+    criu: string;
+};
+/** toolchain stack reported by dumpstate and the version probe. */
+declare const stackcatalog: {
+    nodecurrent: string;
+    nodelts: string;
+    typescript: string;
+    qemu: string;
+    docker: string;
+    buildx: string;
+    criu: string;
+    otelsdk: string;
+};
+/** runtime selector; every value maps to one strategy implementation. */
+type sandboxruntime = 'docker' | 'firecracker' | 'qemu' | 'cloudhypervisor' | 'gvisor' | 'kata';
+/** verified performance envelope of the microvm runtimes. */
+declare const performetrics: {
+    firecrackercoldbootms: number;
+    firecrackermemorymib: number;
+    firecrackerthroughputvmspersecond: number;
+    firecrackerrestorems: number;
+    firecrackerbackends: string;
+    qemumttcg: string;
+    gvisoroverhead: string;
+    livedowntimems: string;
+};
+/** returns true when /dev/kvm is readable and writable; github actions
+ * hosted runners never expose it, which is why the qemu strategy falls
+ * back to tcg and the firecracker strategy refuses to start there. */
+declare function kvmavailable(): boolean;
+/**
+ * lifecycle states of a sandbox or vm. the v5 seven state machine is
+ * extended with the unique states of the Meta machines: scheduling,
+ * binding and provisioning (from VmPhase), paused, degraded, migrating
+ * and draining (from VmState/VmPhase); terminating maps to draining and
+ * terminated maps to destroyed.
+ */
+type lifecyclestate = 'pending' | 'creating' | 'scheduling' | 'binding' | 'provisioning' | 'running' | 'degraded' | 'paused' | 'snapshotted' | 'migrating' | 'restoring' | 'draining' | 'stopped' | 'destroyed' | 'failed';
+/**
+ * allowed transitions; destroyed is terminal and failed may recover into
+ * provisioning for a retry or fall to destroyed. the guard map merges the
+ * v5 forward edges with the twelve phase guards of coreorchestrator.
+ */
+declare const transitions: Record<lifecyclestate, readonly lifecyclestate[]>;
+/** checks whether a state transition is legal. */
+declare function cantransition(from: lifecyclestate, to: lifecyclestate): boolean;
+/**
+ * legacy Meta phase names mapped onto the single machine; kept so old
+ * configs and docs keep working without a second state machine.
+ */
+declare function lifecyclefromphase(phase: string): lifecyclestate;
+/** brands a primitive so ids of different domains never mix. */
+type brand<t, b extends string> = t & {
+    readonly brand: b;
+};
+/** branded identifiers used by the vm plane. */
+type vmid = brand<string, 'vmid'>;
+type VcpuId = brand<string, 'VcpuId'>;
+type gpuid = brand<string, 'gpuid'>;
+type vfid = brand<string, 'vfid'>;
+type snapshotid = brand<string, 'snapshotid'>;
+type checkpointid = brand<string, 'checkpointid'>;
+type pluginid = brand<string, 'pluginid'>;
+type userid = brand<string, 'userid'>;
+type roleid = brand<string, 'roleid'>;
+/** mints a fresh branded vm id. */
+declare const createvmid: (seed?: string) => vmid;
+/** recursively readonly view of a type. */
+type deepreadonly<t> = {
+    readonly [key in keyof t]: deepreadonly<t[key]>;
+};
+/** a value or a promise of it. */
+type awaitable<t> = t | Promise<t>;
+/** discriminated result used by every fallible vm plane operation. */
+type result<t, e = Error> = {
+    readonly ok: true;
+    readonly value: t;
+} | {
+    readonly ok: false;
+    readonly error: e;
+};
+/** host port mapping; host is always randomized unless pinned by the user. */
+interface portmapping {
+    readonly host: number;
+    readonly container: number;
+}
+/** full sandbox specification produced by the builder. */
+interface sandboxspec {
+    readonly id: string;
+    readonly host: string;
+    readonly image: string;
+    readonly runtime: sandboxruntime;
+    readonly cpus: number;
+    readonly memorymib: number;
+    readonly shm: string;
+    readonly memoryswap: number;
+    readonly autoremove: boolean;
+    readonly env: Record<string, string>;
+    readonly gpuspoof: string | null;
+    readonly ports: readonly portmapping[];
+    readonly workdir: string | null;
+    readonly command: readonly string[];
+}
+/** numa node identifier and cpu set alias. */
+type numanodeid = number;
+type cpuset = number[];
+/** vCPU topology hints (coreorchestrator unique). */
+interface vcputopology {
+    readonly sockets: number;
+    readonly corespersocket: number;
+    readonly threadspercore: number;
+    readonly pinnedcpus?: readonly number[];
+    readonly isolated?: boolean;
+    readonly overcommitratio?: number;
+}
+/** vRAM balloon semantics with hugepages choice (coreorchestrator). */
+interface vramballoon {
+    requestedmib: number;
+    minmib: number;
+    maxmib: number;
+    currentmib: number;
+    readonly balloondriver: 'virtio-balloon' | 'none';
+    readonly hugepages: 'none' | '2mib' | '1gib';
+}
+/** gpu passthrough request shape (coreorchestrator). */
+interface gpupassthroughrequest {
+    readonly id: string;
+    readonly vendor: 'nvidia' | 'amd' | 'intel' | 'generic';
+    readonly model?: string;
+    readonly count: number;
+    readonly vfio: boolean;
+    readonly sriovvfcount?: number;
+    readonly memorymib?: number;
+    readonly uuid?: string;
+    readonly deviceids?: readonly string[];
+}
+/** label selector used by the affinity resolver. */
+interface affinityselector {
+    readonly key: string;
+    readonly operator: 'in' | 'notin' | 'exists';
+    readonly values?: readonly string[];
+}
+/** definition accepted by createvm; missing fields fall to sane defaults. */
+interface vmdefinition {
+    readonly id?: vmid;
+    readonly name: string;
+    readonly tenantid?: string;
+    readonly vcpus: number;
+    readonly vrammib: number;
+    readonly diskgb?: number;
+    readonly ostype?: 'linux' | 'windows' | 'bsd';
+    readonly arch?: 'x86_64' | 'aarch64';
+    readonly image?: string;
+    readonly qemubinary?: string;
+    readonly machine?: string;
+    readonly accel?: 'kvm' | 'tcg';
+    readonly extraargs?: readonly string[];
+    readonly dockerruntime?: 'runc' | 'crun' | 'kata';
+    readonly dockernetwork?: 'bridge' | 'host' | 'none' | 'passage';
+    readonly vcputopology?: vcputopology;
+    readonly gpu?: readonly gpupassthroughrequest[];
+    readonly labels?: Record<string, string>;
+    readonly affinity?: readonly affinityselector[];
+    readonly antiaffinity?: readonly string[];
+    readonly checkpointenabled?: boolean;
+    readonly rbacroles?: readonly string[];
+}
+/** the single vm record stored by the orchestrator (merged VmInstance +
+ * VmSpec shapes from the two Meta sources). */
+interface vmrecord {
+    readonly id: vmid;
+    readonly name: string;
+    readonly tenantid: string;
+    readonly vcpus: number;
+    vrammib: number;
+    readonly diskgb: number;
+    readonly ostype: 'linux' | 'windows' | 'bsd';
+    readonly arch: 'x86_64' | 'aarch64';
+    readonly image: string;
+    readonly qemubinary: string;
+    readonly machine: string;
+    readonly accel: 'kvm' | 'tcg';
+    readonly extraargs: readonly string[];
+    readonly dockerruntime: 'runc' | 'crun' | 'kata';
+    readonly dockernetwork: 'bridge' | 'host' | 'none' | 'passage';
+    readonly vcputopology?: vcputopology;
+    vramballoon?: vramballoon;
+    gpu: gpupassthroughrequest[];
+    readonly labels: Record<string, string>;
+    readonly affinity: readonly affinityselector[];
+    readonly antiaffinity: readonly string[];
+    readonly checkpointenabled: boolean;
+    readonly rbacroles: readonly string[];
+    state: lifecyclestate;
+    readonly createdat: Date;
+    startedat?: Date;
+    qemupid?: number;
+    dockerid?: string;
+    numanode: numanodeid;
+    readonly vcpupins: Map<number, cpuset>;
+    metrics: {
+        cputimens: bigint;
+        memrssmb: number;
+    };
+}
+/** balloon controller state per vm (src_core unique). */
+interface balloonstate {
+    readonly vmid: vmid;
+    targetmib: number;
+    actualmib: number;
+    deflatedmib: number;
+    lastadjust: Date;
+    pressurescore: number;
+}
+/** gpu assignment bookkeeping (src_core unique). */
+interface gpuassignment {
+    readonly vmid: vmid;
+    readonly gpuid: gpuid;
+    readonly vfid?: vfid;
+    readonly pciaddr: string;
+    readonly iommugroup: number;
+    readonly bounddriver: 'vfio-pci' | 'nvidia' | 'amdgpu';
+}
+/** SR-IOV physical function view (src_core unique). */
+interface sriovpf {
+    readonly pfpci: string;
+    readonly totalvfs: number;
+    activevfs: number;
+    readonly vfs: {
+        readonly vfid: vfid;
+        readonly pci: string;
+        assignedto?: vmid;
+        readonly vlan?: number;
+    }[];
+    readonly driver: string;
+}
+/** merged passage route: encap/latency view of src_core plus the
+ * protocol/latency budget/numa awareness of coreorchestrator. */
+interface passageroute {
+    readonly id: string;
+    readonly srcvm: vmid;
+    readonly dstvm: vmid;
+    readonly passage: string;
+    protocol: 'vxlan' | 'vlan' | 'sr-iov' | 'direct' | 'vsock' | 'vhost-user' | 'ivshmem' | 'vfio-user';
+    latencyus: number;
+    bandwidthgbps: number;
+    readonly latencybudgetus?: number;
+    readonly numaaware?: boolean;
+}
+/** merged MTTG job: tenant/QoS/deadline of v6 plus dependencies and
+ * retries of src_core. */
+interface mttgjob {
+    readonly id: string;
+    readonly tenant: string;
+    readonly qos: 'guaranteed' | 'burstable' | 'besteffort';
+    readonly priority: number;
+    readonly groupid: string;
+    readonly payloadref: string;
+    readonly dependencies: readonly string[];
+    retries: number;
+    readonly createdat: Date;
+    readonly deadlinems?: number;
+    wrappedvmid?: string;
+}
+/** health probe recorded from outside (coreorchestrator). */
+interface healthprobe {
+    readonly vmid: string;
+    readonly ok: boolean;
+    readonly latencyms: number;
+    readonly reason?: string;
+    readonly cpustealpct?: number;
+    readonly mempressure?: number;
+    readonly lastseen: string;
+}
+/** health check definition (src_core). */
+interface healthcheck {
+    readonly id: string;
+    readonly target: vmid | 'host' | `gpu:${string}`;
+    readonly intervalms: number;
+    readonly timeoutms: number;
+    laststatus: 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
+    lastcheck: Date;
+    failurecount: number;
+}
+/** autoscale policy (src_core). */
+interface autoscalepolicy {
+    readonly id: string;
+    readonly vmgroup: string;
+    readonly metric: 'cpu' | 'mem' | 'gpu' | 'queue_depth';
+    readonly thresholdhigh: number;
+    readonly thresholdlow: number;
+    readonly minreplicas: number;
+    readonly maxreplicas: number;
+    readonly cooldowensec: number;
+}
+/** migration type and job (src_core, vfio check of coreorchestrator). */
+type migrationtype = 'cold' | 'warm' | 'live' | 'postcopy';
+interface migrationjob {
+    readonly id: string;
+    readonly vmid: vmid;
+    readonly type: migrationtype;
+    readonly sourcehost: string;
+    readonly desthost: string;
+    state: 'pending' | 'precopy' | 'dirtyiter' | 'stopcopy' | 'completed' | 'failed';
+    readonly bandwidthmbps: number;
+    downtimems?: number;
+    progress: number;
+}
+/** disk snapshot (src_core, meta json sidecar of coreorchestrator). */
+interface vmsnapshot {
+    readonly id: snapshotid;
+    readonly vmid: vmid;
+    readonly name: string;
+    readonly createdat: Date;
+    readonly sizemb: number;
+    readonly qcow2path: string;
+    readonly rampath?: string;
+    readonly parentid?: snapshotid;
+}
+/** checkpoint record (src_core merged with the passage checksum of v6). */
+interface vmcheckpoint {
+    readonly id: checkpointid;
+    readonly vmid: vmid;
+    readonly method: 'criu' | 'qemu_savevm' | 'docker_checkpoint';
+    readonly path: string;
+    readonly incremental: boolean;
+    readonly createdat: Date;
+    passagechecksum?: string;
+}
+/** one OTel style metric point (folded into sandboxmetrics). */
+interface otelpoint {
+    readonly name: string;
+    readonly type: 'counter' | 'gauge' | 'histogram';
+    readonly value: number;
+    readonly labels: Record<string, string>;
+    readonly timestamp: number;
+}
+/** plugin contract (src_core shape, onEvent hook of coreorchestrator). */
+interface plugincontract {
+    readonly id: pluginid;
+    readonly name: string;
+    readonly version: string;
+    readonly hooks: readonly string[];
+    activate: (context: plugincontext) => Promise<void>;
+    deactivate: () => Promise<void>;
+    onevent?: (event: string, payload: unknown) => Promise<void>;
+}
+/** context handed to a plugin on activation. */
+interface plugincontext {
+    readonly orchestrator: orchestrator;
+    readonly log: (message: string) => void;
+    readonly registerhook: (hook: enginetopicname, handler: (payload: unknown) => void) => void;
+}
+/** RBAC role and permission union (src_core). */
+interface rbacrole {
+    readonly id: roleid;
+    readonly name: 'admin' | 'operator' | 'viewer' | 'scheduler';
+    readonly permissions: readonly permission[];
+}
+type permission = 'vm:create' | 'vm:start' | 'vm:stop' | 'vm:delete' | 'vm:migrate' | 'gpu:assign' | 'config:write' | 'snapshot:create' | 'metrics:read' | 'plugin:manage' | '*';
+/** RBAC principal of the v6 grant/check cache. */
+interface rbacprincipal {
+    readonly subject: string;
+    readonly roles: readonly string[];
+    readonly tenant: string;
+    readonly issuedat: string;
+}
+/** resource reservation with TTL (src_core). */
+interface reservation {
+    readonly id: string;
+    readonly resources: {
+        readonly cpus: readonly number[];
+        readonly memorymb: number;
+        readonly gpus?: readonly gpuid[];
+    };
+    readonly owner: vmid | userid;
+    readonly expiresat: Date;
+    readonly priority: number;
+}
+/** affinity rule (src_core). */
+interface affinityrule {
+    readonly id: string;
+    readonly type: 'affinity' | 'anti-affinity';
+    readonly scope: 'vm' | 'host' | 'numa';
+    readonly subjects: readonly vmid[];
+    readonly weight: number;
+}
+/** per-tenant quota row (coreorchestrator). */
+interface quotastate {
+    vcpu: number;
+    vram: number;
+    gpu: number;
+    usedvcpu: number;
+    usedvram: number;
+    usedgpu: number;
+}
+/** docker bridge mapping (src_core). */
+interface dockerbridgemapping {
+    readonly vmid: vmid;
+    readonly containerid: string;
+    readonly bridge: string;
+    readonly vethhost: string;
+    readonly vethguest: string;
+    readonly ipam: {
+        readonly ipv4: string;
+        readonly mac: string;
+    };
+}
+/** leader election state (src_core). */
+interface leaderstate {
+    readonly nodeid: string;
+    term: number;
+    isleader: boolean;
+    leaderid?: string;
+    leaseexpiry?: Date;
+    voters: readonly string[];
+}
+/** audit entry (ring view; the JSONL line mirrors it on disk). */
+interface auditentry {
+    readonly id: string;
+    readonly timestamp: Date;
+    readonly userid: userid;
+    readonly action: string;
+    readonly target: string;
+    readonly result: 'success' | 'failure';
+    readonly detail?: Record<string, unknown>;
+}
+/** drain task for one vm (src_core). */
+interface draintask {
+    readonly vmid: vmid;
+    readonly timeoutsec: number;
+    readonly signal: 'SIGTERM' | 'SIGQUIT';
+    readonly fallback: 'SIGKILL' | 'snapshot';
+}
+/** NUMA topology view owned by this module (heuristic + cores.json). */
+interface numatopologyview {
+    readonly nodes: {
+        readonly id: numanodeid;
+        readonly cpus: readonly number[];
+        readonly memorymb: number;
+        readonly distances: Record<numanodeid, number>;
+        readonly hugepages: {
+            readonly '2m': number;
+            readonly '1g': number;
+        };
+    }[];
+    readonly totalmemorymb: number;
+}
+/** run queue of one NUMA node (src_core scheduler). */
+interface runqueue {
+    readonly numanode: numanodeid;
+    tasks: vcputask[];
+    load: number;
+    readonly capacity: number;
+}
+/** one schedulable vCPU (src_core). */
+interface vcputask {
+    readonly id: VcpuId;
+    readonly vmid: vmid;
+    priority: number;
+    affinity: cpuset;
+    numanode: numanodeid;
+    readonly shares: number;
+    readonly burstms: number;
+}
+/** flat config file names watched by the hot reloader. */
+type configfilename = 'vm.config' | 'gpu.config' | 'passage.config' | 'qemu.config' | 'mttg.config' | 'docker.config' | 'boards.json' | 'cores.json' | 'processors.json' | 'gpus.json' | 'vcpus.json' | 'vram.json' | 'amdryzenxseries.json' | 'nvidiablackwell.json';
+/** QEMU process bookkeeping absorbed from spawnqemu (src_core). */
+interface qemuprocess {
+    readonly vmid: vmid;
+    readonly pid: number;
+    readonly cmdline: readonly string[];
+    readonly child: ChildProcess;
+    readonly monitorsocket: string;
+    readonly qmpsocket: string;
+}
+/**
+ * error envelope of the orchestrator (coreorchestrator OrchestratorError
+ * renamed lowercase); carries a machine readable code, a retryability
+ * flag and free form context.
+ */
+declare class orchestratorerror extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: string, retryable?: boolean, context?: Record<string, unknown>);
+}
+/** result of a completed child process. */
+interface runresult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** parses a "kernel[:rootfs]" image descriptor for the vm runtimes. */
+declare function vmimage(image: string): {
+    readonly kernel: string;
+    readonly rootfs: string | null;
+};
+/** allocates a host port: an explicit port always wins (user choice),
+ * then VHE_PORT, otherwise a random port in [30000, 59999] drawn with
+ * crypto.randomInt(30000) + 30000. */
+declare function allocport(explicit?: number): number;
+/** resolves the bind host: explicit host always wins (user choice), then
+ * VHE_HOST, then the first non-internal ipv4 interface, then "0.0.0.0";
+ * "localhost" and loopback addresses are never returned implicitly. */
+declare function resolvehost(explicit?: string): string;
+/**
+ * priority queue over items carrying a numeric priority and a string id;
+ * higher priorities pop first and the list view stays stable enough for
+ * the dependency checks of the MTTG pipeline.
+ */
+declare class priorityqueue<t extends {
+    readonly priority: number;
+    readonly id: string;
+}> {
+    #private;
+    /** inserts an item keeping the heap sorted by descending priority. */
+    push(item: t): void;
+    /** removes and returns the highest priority item. */
+    pop(): t | undefined;
+    /** returns the highest priority item without removing it. */
+    peek(): t | undefined;
+    /** number of queued items. */
+    get size(): number;
+    /** removes an item by id; true when it existed. */
+    remove(id: string): boolean;
+    /** snapshot of the current ordering. */
+    list(): readonly t[];
+}
+/** live handle over a sandbox process; disposal stops the process. */
+declare class sandboxhandle {
+    #private;
+    constructor(id: string, runtime: sandboxruntime, child: ChildProcess);
+    get id(): string;
+    get runtime(): sandboxruntime;
+    get pid(): number | undefined;
+    get exited(): boolean;
+    /** resolves after a startup grace period or rejects on early exit. */
+    started(gracems?: number): Promise<void>;
+    /** stops the sandbox; SIGTERM first, SIGKILL after a grace period. */
+    stop(): Promise<void>;
+    /** `using` disposal hook: stops the sandbox without awaiting. */
+    [Symbol.dispose](): void;
+}
+/** strategy contract implemented by every runtime. */
+declare abstract class runtimestrategy {
+    abstract readonly name: sandboxruntime;
+    abstract readonly needskvm: boolean;
+    /** probes the runtime binary; returns false when missing. */
+    detect(): Promise<boolean>;
+    /** full launch argv including the binary at position zero. */
+    abstract buildcommand(spec: sandboxspec): readonly string[];
+    /** spawns the sandbox and returns a live handle. */
+    launch(spec: sandboxspec): Promise<sandboxhandle>;
+    /** optional snapshot support (firecracker api); null when unsupported. */
+    createsnapshot(id: string, targetdir: string): Promise<string | null>;
+    protected abstract binary(): string;
+    protected versionargs(): readonly string[];
+}
+/** docker strategy; memory-swap -1 grants unlimited swap, shm-size 2g
+ * fixes the 64MB default that crashes pytorch dataloaders, --cpus maps
+ * to the engine NanoCpus field (cpus * 1e9) and --rm enables autoremove. */
+declare class dockerruntime extends runtimestrategy {
+    #private;
+    readonly name: sandboxruntime;
+    readonly needskvm = false;
+    constructor(engineruntime?: string | null);
+    protected binary(): string;
+    protected versionargs(): readonly string[];
+    buildcommand(spec: sandboxspec): readonly string[];
+}
+/** gvisor strategy: runsc oci runtime on the systrap platform (seccomp
+ * RET_TRAP delivering SIGSYS that the sentry emulates); expect 10-30%
+ * overhead and io_uring disabled by default inside the sandbox. */
+declare class gvisorruntime extends dockerruntime {
+    readonly name: sandboxruntime;
+    constructor();
+}
+/** kata containers strategy: runtime-rs (rust) is the default runtime
+ * since kata 4.0; supported hypervisors are qemu, cloud hypervisor,
+ * firecracker, dragonball and openvmm (kata 4.1). */
+declare class kataruntime extends dockerruntime {
+    readonly name: sandboxruntime;
+    constructor();
+}
+/** performs one http request over the firecracker api unix socket; the
+ * vmm exposes machine-config, boot-source, drives, actions and
+ * snapshot/create on that socket. */
+declare function fcrequest(socket: string, method: string, apipath: string, body?: unknown): Promise<number>;
+/** firecracker strategy; requires /dev/kvm, drives the vmm over its api
+ * socket and supports full snapshots with file or uffd backends. */
+declare class firecrackerruntime extends runtimestrategy {
+    #private;
+    readonly name: sandboxruntime;
+    readonly needskvm = true;
+    constructor(backend?: 'file' | 'uffd');
+    protected binary(): string;
+    /** per-sandbox api socket path. */
+    socketpath(id: string): string;
+    /** machine-config payload (PUT /machine-config). */
+    machineconfig(spec: sandboxspec): Record<string, unknown>;
+    /** boot-source payload (PUT /boot-source). */
+    bootsource(spec: sandboxspec): Record<string, unknown>;
+    /** drives payload for the root filesystem (PUT /drives/rootfs). */
+    drivepayload(spec: sandboxspec): Record<string, unknown> | null;
+    buildcommand(spec: sandboxspec): readonly string[];
+    /** restore argv: --restore-file replays a snapshot with the configured
+     * backend (file maps privately with copy-on-write; uffd faults pages
+     * in from a userspace handler). */
+    restorecommand(id: string, snapshotfile: string): readonly string[];
+    /** creates a full snapshot through PATCH /snapshot/create. */
+    createsnapshot(id: string, targetdir: string): Promise<string | null>;
+    /** launches a fresh microVM: spawns the vmm, applies machine-config,
+     * boot-source and drives, then issues InstanceStart. */
+    launch(spec: sandboxspec): Promise<sandboxhandle>;
+}
+/**
+ * qemu strategy: mttcg with one host thread per vCPU and a 1024 MiB
+ * translation-block cache; the EPYC-v5 cpu model is confirmed in
+ * target/i386/cpu.c; without /dev/kvm (github actions hosted runners)
+ * the engine keeps tcg and only swaps the cpu model.
+ *
+ * the class also absorbs spawnqemu from the Meta source: the vm plane
+ * launches qemu with monitor and qmp unix sockets, a numa pin line,
+ * vfio devices for every gpu assignment, extra args from qemu.config
+ * and, when the binary is absent (CI), a "sleep 3600" stand-in process
+ * so scheduling and lifecycle still exercise end to end.
+ */
+declare class qemuruntime extends runtimestrategy {
+    #private;
+    readonly name: sandboxruntime;
+    readonly needskvm = false;
+    constructor(machine?: 'q35' | 'microvm');
+    protected binary(): string;
+    buildcommand(spec: sandboxspec): readonly string[];
+    /** monitor and qmp socket paths for one vm (spawnqemu merge). */
+    socketsfor(vmidvalue: string): {
+        readonly monitor: string;
+        readonly qmp: string;
+    };
+    /**
+     * builds the vm plane argv: strategy flags plus the name/uuid, dual
+     * unix sockets, virtio balloon, the per-numa bridge netdev, the numa
+     * pin line and one vfio-pci device per assigned gpu.
+     */
+    buildvmcommand(vm: vmrecord, assignments: readonly gpuassignment[]): readonly string[];
+    /**
+     * spawns qemu for a vm record; when the binary does not exist the
+     * method spawns "sleep 3600" instead so CI environments without qemu
+     * still run the scheduling and lifecycle paths (spawnqemu merge).
+     */
+    spawn(vm: vmrecord, assignments: readonly gpuassignment[], onexit: (vmidvalue: vmid, code: number | null) => void): Promise<qemuprocess>;
+    /** probes the installed qemu version banner (coreorchestrator). */
+    probeversion(): Promise<string>;
+}
+/** cloud hypervisor strategy: rust vmm; vfio-user devices are
+ * experimental in v53 and attach through --user-device socket=<path>. */
+declare class clhruntime extends runtimestrategy {
+    #private;
+    readonly name: sandboxruntime;
+    readonly needskvm = true;
+    constructor(vfiousersocket?: string | null);
+    protected binary(): string;
+    buildcommand(spec: sandboxspec): readonly string[];
+}
+/** registry of runtime strategies; the factory resolves exclusively
+ * through this registry. */
+declare class runtimeregistry {
+    #private;
+    register(strategy: runtimestrategy): this;
+    get(name: sandboxruntime): runtimestrategy;
+    names(): readonly sandboxruntime[];
+    /** probes every registered runtime and returns availability. */
+    detectall(): Promise<Record<string, boolean>>;
+}
+/** fluent builder for sandbox specs; defaults mirror the engine
+ * baseline: 2 vCPUs, 2048 MiB, shm 2g, unlimited swap, autoremove on. */
+declare class sandboxbuilder {
+    #private;
+    withid(id: string): this;
+    withhost(host?: string): this;
+    withimage(image: string): this;
+    withruntime(runtime: sandboxruntime): this;
+    /** vCPU count; build() clamps it to the host core count. */
+    withcpus(count: number): this;
+    withmemory(mib: number): this;
+    withshm(shm: string): this;
+    /** -1 keeps unlimited swap (docker semantics). */
+    withswap(limit: number): this;
+    withoutautoremove(): this;
+    withenv(key: string, value: string): this;
+    withgpuspoof(name: string): this;
+    /** maps a container port; the host port is randomized unless pinned. */
+    withport(container: number, host?: number): this;
+    withworkdir(workdir: string): this;
+    withcommand(...command: string[]): this;
+    /** freezes the spec after validation. */
+    build(): sandboxspec;
+}
+/** legacy short names kept for v5 callers; each maps to a sandbox:*
+ * topic on the single bus. */
+type sandboxeventname = 'created' | 'started' | 'stopped' | 'snapshotted' | 'restored' | 'destroyed' | 'pooled' | 'error';
+/** one replay ledger record. */
+interface replayrecord {
+    readonly at: string;
+    readonly payload: unknown;
+}
+/**
+ * the single event bus of the engine. sandboxevents extends enginebus
+ * (from index.ts) instead of owning another EventEmitter, keeps the v5
+ * short-name emit/on api and adds the replay ledger of the Meta v6 bus:
+ * every publish is recorded in a 200 slot ring so newcomer plugins can
+ * catch up with recent history. the full topic topology (sandbox:* plus
+ * vm:*, gpu:*, passage:*, mttg:*, health:*, autoscale:*, rbac:*,
+ * leader:* and friends) is declared once in enginetopics.
+ */
+declare class sandboxevents extends enginebus {
+    #private;
+    /**
+     * publishes on the single bus while recording the replay ledger;
+     * listener failures are isolated by the underlying emitter. the
+     * override keeps the generic topic typing of enginebus so payloads
+     * stay checked at every call site.
+     */
+    publish<t extends enginetopicname>(topic: t, payload: enginetopics[t]): boolean;
+    /** replays the most recent records of one topic for late joiners. */
+    replay(topic: enginetopicname, count?: number): readonly replayrecord[];
+    /** legacy v5 emit: publishes onto the sandbox:<name> topic. */
+    emit(name: sandboxeventname, payload: unknown): boolean;
+    /** legacy v5 on: subscribes to the sandbox:<name> topic. */
+    on(name: sandboxeventname, listener: (payload: unknown) => void): this;
+}
+/** immutable metrics snapshot. */
+interface metricsview {
+    readonly counters: Record<string, number>;
+    readonly gauges: Record<string, number>;
+    readonly bootms: readonly number[];
+    readonly bootmsavg: number;
+}
+/**
+ * the single metrics component of the engine. sandboxmetrics extends the
+ * MetricsStore of index.ts (so every sample also lands in the disposable
+ * InternalMemory-backed store and can flush to disk), keeps the v5
+ * counters/gauges/boot histogram api and absorbs the Meta OTel recorder:
+ * labeled counter/gauge/histogram points in a 10000 slot ring plus the
+ * Prometheus text exporter with "# TYPE" headers.
+ */
+declare class sandboxmetrics extends MetricsStore {
+    #private;
+    constructor(engineid?: string, snapshotdir?: string);
+    /** increments a counter and records an OTel counter point. */
+    inc(key: string, delta?: number, labels?: Record<string, string>): void;
+    /** sets a gauge and records an OTel gauge point. */
+    gauge(key: string, value: number, labels?: Record<string, string>): void;
+    /** records an OTel histogram point (boot latencies and friends). */
+    histogram(key: string, value: number, labels?: Record<string, string>): void;
+    /** pushes one boot latency sample into the 512 slot histogram. */
+    observeboot(ms: number): void;
+    /** raw OTel ring access (Meta getMetricsSnapshot). */
+    otelsnapshot(): readonly otelpoint[];
+    /** aggregates the counters, gauges and boot histogram view. */
+    snapshot(): metricsview;
+    /**
+     * renders the Prometheus text exposition format: one "# TYPE" header
+     * per metric name followed by its last twenty labeled samples.
+     */
+    exportprometheus(): string;
+}
+/** picks the strategy from the registry, enforces the kvm requirement
+ * and wraps the live handle in a proxy. */
+declare class sandboxfactory {
+    #private;
+    constructor(registry: runtimeregistry, events: sandboxevents, metrics: sandboxmetrics);
+    create(spec: sandboxspec): Promise<sandboxproxy>;
+}
+/** guards lifecycle transitions, records metrics and emits events on
+ * every call that reaches the underlying handle. */
+declare class sandboxproxy {
+    #private;
+    constructor(spec: sandboxspec, handle: sandboxhandle, strategy: runtimestrategy, events: sandboxevents, metrics: sandboxmetrics);
+    get id(): string;
+    get runtime(): sandboxruntime;
+    get state(): lifecyclestate;
+    get host(): string;
+    get ports(): readonly portmapping[];
+    /** guards the transition to running and records the boot latency. */
+    start(): Promise<void>;
+    /** creates a snapshot when the runtime supports it. */
+    snapshot(targetdir?: string): Promise<string | null>;
+    /** pauses a running sandbox (qemu stop through the qmp socket). */
+    pause(): Promise<void>;
+    /** resumes a paused sandbox. */
+    resume(): Promise<void>;
+    /** stops and destroys the sandbox; idempotent. */
+    destroy(): Promise<void>;
+    /** `using` disposal hook: destroys the sandbox without awaiting. */
+    [Symbol.dispose](): void;
+    /** pid of the underlying sandbox process, when alive. */
+    get pid(): number | undefined;
+    /** delegates to the criu checkpointer for process-tree snapshots. */
+    criucheckpoint(checkpointer: cricheckpointer, dir: string): Promise<void>;
+}
+/** warm pool options: keep min sandboxes pre-booted, cap at max. */
+interface warmpooloptions {
+    readonly min: number;
+    readonly max: number;
+    readonly template: () => Promise<sandboxproxy>;
+    readonly events: sandboxevents;
+    readonly metrics: sandboxmetrics;
+}
+/** keeps pre-booted sandboxes ready so acquires skip the cold start;
+ * firecracker cold boot is 125ms but a snapshot restore is ~4ms, and the
+ * pool turns creation into a pointer pop. */
+declare class warmpool {
+    #private;
+    constructor(options: warmpooloptions);
+    /** fills the pool up to the configured minimum. */
+    prewarm(): Promise<void>;
+    /** acquires a warm sandbox or falls back to a fresh create. */
+    acquire(): Promise<sandboxproxy>;
+    /** returns a sandbox to the pool or destroys it above the cap. */
+    release(sandbox: sandboxproxy): Promise<void>;
+    /** schedules background refills. */
+    startrefill(intervalms?: number): void;
+    /** stops refills and destroys every warm sandbox. */
+    drain(): Promise<void>;
+}
+/** process-tree checkpoint/restore through criu 4.2.1; selinux relabel
+ * on restore is provided by security.ts (criurelabel). */
+declare class cricheckpointer {
+    checkpoint(handle: sandboxhandle, dir: string): Promise<void>;
+    restore(dir: string): Promise<void>;
+}
+/** renders a docker compose 5.5.0 service block equivalent to the
+ * engine flags: memswap_limit -1 and shm_size 2g. */
+declare function composeyaml(spec: sandboxspec): string;
+/** orchestrator options; every piece can be injected (user choice). */
+interface orchestratoroptions {
+    readonly firecrackerbackend?: 'file' | 'uffd';
+    readonly qemumachine?: 'q35' | 'microvm';
+    readonly clhvfiousersocket?: string | null;
+    readonly nodeid?: string;
+    readonly rootdir?: string;
+    readonly enablehotreload?: boolean;
+    readonly kvmenabled?: boolean;
+}
+/**
+ * facade that ties the registry, factory, warm pool, events and metrics
+ * into one lifecycle api (create, start, snapshot, restore, destroy) and
+ * additionally owns the vm plane absorbed from the Meta orchestrators:
+ * lifecycle with the single state machine, the NUMA scheduler, balloon,
+ * gpu assignment, passage routing, the MTTG queue, the docker bridge,
+ * health, autoscale, migration, snapshots, checkpoints, hot-reload,
+ * plugins, RBAC, reservations, quotas, affinity, audit, drain and
+ * leader election.
+ */
+declare class orchestrator {
+    #private;
+    readonly version = "2.0.0-saddle-20260822";
+    readonly stack: Readonly<Record<string, string>>;
+    constructor(options?: orchestratoroptions);
+    get events(): sandboxevents;
+    get metrics(): sandboxmetrics;
+    /** v6 alias over the single event bus. */
+    geteventbus(): sandboxevents;
+    /**
+     * routes unhandled rejections and uncaught exceptions of the host
+     * process onto the single bus; explicit opt-in because it changes
+     * process-wide behavior.
+     */
+    installerrorcatcher(): void;
+    /**
+     * returns the NUMA view as {nodes, map}; an explicit numa section in
+     * cores.json wins over the heuristic (coreorchestrator getNumaTopology).
+     */
+    getnumatopology(): Promise<{
+        readonly nodes: number;
+        readonly map: Record<number, number[]>;
+    }>;
+    /**
+     * asserts that a user holds a permission through one of its roles; the
+     * system actor bypasses everything and roleless users may still read
+     * metrics (viewer fallback). denials publish rbac:denied and throw an
+     * orchestratorerror with ERR_RBAC_DENIED.
+     */
+    assertpermission(user: userid, perm: permission): void;
+    /** assigns an extra role to a user. */
+    assignrole(user: userid, role: roleid): void;
+    /** grants subject actions over a resource key (v6 cache). */
+    grantrbac(principal: rbacprincipal, resource: string, actions: readonly string[]): void;
+    /** checks a grant through subject, roles and wildcards (v6). */
+    checkrbac(principal: rbacprincipal, resource: string, action: string): boolean;
+    /**
+     * reserves cpus/memory/gpus for an owner with a TTL (default 300s);
+     * overlapping cpu sets of equal or higher priority block the request.
+     */
+    reserveresources(owner: vmid | userid, resources: reservation['resources'], ttlsec?: number, priority?: number): reservation;
+    /** releases a reservation by id; true when it existed. */
+    releasereservation(id: string): boolean;
+    /** registers an affinity or anti-affinity rule. */
+    addaffinityrule(rule: affinityrule): void;
+    /** removes an affinity rule by id. */
+    removeaffinityrule(ruleid: string): boolean;
+    /**
+     * evaluates whether a vm definition may land on a node described by
+     * labels: In/NotIn/Exists selectors must all pass and antiaffinity
+     * targets must not overlap the candidate pin set (coreorchestrator).
+     */
+    resolveaffinity(record: vmrecord, nodelabels: Record<string, string>): boolean;
+    /**
+     * periodic scheduler tick: sorts run queues by priority, recomputes
+     * loads and rebalances when the max/min spread exceeds 20 percent.
+     */
+    scheduletick(): void;
+    /** repins one vCPU of a vm onto an explicit cpu set. */
+    setvcpuaffinity(id: vmid, vcpuindex: number, target: cpuset): result<void>;
+    /**
+     * validates the topology of a vm, warns on overcommit above 1.5x the
+     * host cpus, computes the pin set (explicit pins or a random rotation)
+     * and walks the machine through scheduling and binding
+     * (coreorchestrator scheduleVcpu).
+     */
+    schedulevcpu(vm: vmrecord): Promise<void>;
+    /** guarded transition on the single machine; publishes vm:phase. */
+    transitionvm(id: vmid, to: lifecyclestate): Promise<vmrecord>;
+    /**
+     * creates a vm record: quota enforcement, NUMA placement, vCPU pins,
+     * balloon initialization and the scheduling/binding walkthrough.
+     */
+    createvm(definition: vmdefinition, actor?: userid): Promise<result<vmrecord>>;
+    /**
+     * starts a vm: vCPU tasks enter the run queues, qemu spawns with the
+     * monitor/qmp socket layout and the docker bridge attaches for bridge
+     * or passage network modes.
+     */
+    startvm(id: vmid, actor?: userid): Promise<result<vmrecord>>;
+    /** stops a vm through the drain path, kills qemu and unschedules its
+     * vCPU tasks. */
+    stopvm(id: vmid, actor?: userid, reason?: string): Promise<result<void>>;
+    /** destroys a vm: stops it when running, releases gpus, frees
+     * reservations and quota and forgets every side table. */
+    destroyvm(id: vmid, actor?: userid): Promise<result<void>>;
+    /** pauses a running vm (qmp stop semantics). */
+    pausevm(id: vmid, actor?: userid): Promise<result<void>>;
+    /** lists vm records with optional state and numa filters. */
+    listvms(filter?: {
+        readonly state?: lifecyclestate;
+        readonly numa?: numanodeid;
+    }): readonly vmrecord[];
+    /** sets the vcpu/vram/gpu quota of a tenant and publishes quota:set. */
+    setquota(tenantid: string, quota: {
+        readonly vcpu: number;
+        readonly vram: number;
+        readonly gpu: number;
+    }): void;
+    /**
+     * walks the balloon of a vm towards a target with pressure scoring
+     * and a gradual 100 MB per 500 ms adjustment; bounds come from the
+     * vramballoon descriptor (0.5x .. 1.5x of the requested size).
+     */
+    balloonvm(id: vmid, targetmb: number, actor?: userid): Promise<result<balloonstate>>;
+    /** strict v6 balloon write with explicit bounds errors. */
+    balloonvram(id: vmid, targetmib: number): Promise<vramballoon>;
+    /** returns the balloon state of a vm, when present. */
+    getballoonstate(id: vmid): balloonstate | undefined;
+    /** registers a gpu; sriov enabled gpus get a PF view with 7 VFs
+     * (Blackwell typical). */
+    registergpu(gpu: {
+        readonly id: gpuid;
+        readonly model: string;
+        readonly pciaddr: string;
+        readonly mode: 'none' | 'passthrough' | 'vgpu' | 'mdev';
+        readonly vrammb: number;
+        readonly sriovenabled: boolean;
+        readonly mdevprofiles?: readonly string[];
+    }): void;
+    /**
+     * assigns a gpu (or one of its VFs) to a vm; the iommu group is read
+     * from the last id bytes or drawn randomly when unavailable.
+     */
+    assigngpu(id: vmid, gpu: gpuid, actor?: userid, usevf?: boolean): Promise<result<gpuassignment>>;
+    /** releases a gpu assignment and frees its VF, if any. */
+    releasegpu(gpu: gpuid, actor?: userid): result<void>;
+    /** lists the SR-IOV physical functions known to the engine. */
+    listsriov(): readonly sriovpf[];
+    /**
+     * provisions VFs on a PF through the sysfs sriov_numvfs knob; when the
+     * sysfs node is absent (containers) the call reports the simulated
+     * outcome instead of failing (coreorchestrator).
+     */
+    provisionsriov(pf: string, vfcount: number): Promise<readonly string[]>;
+    /**
+     * attaches gpu passthrough requests to a vm by filtering the flat
+     * gpus.json catalog (coreorchestrator); vfio must be requested.
+     */
+    attachgpupassthrough(id: vmid, requests: readonly gpupassthroughrequest[]): Promise<readonly string[]>;
+    /**
+     * adds a passage route between two vms; the default latency follows
+     * the numa distance (15us same node, 45us remote) plus 20us of vxlan
+     * encapsulation, and ivshmem routes are capped at 50000 Mbps.
+     */
+    addpassageroute(route: Omit<passageroute, 'latencyus'> & {
+        readonly latencyus?: number;
+    }): result<passageroute>;
+    /** v6 alias returning the first route between two vms. */
+    resolvepassageroute(src: vmid, dst: vmid): passageroute | undefined;
+    /** every route between two vms (src_core). */
+    resolvepassage(src: vmid, dst: vmid): readonly passageroute[];
+    /** removes a passage route by id. */
+    removepassageroute(routeid: string): boolean;
+    /** enqueues an MTTG job; unresolved dependencies are logged so the
+     * pipeline can trace the wait chain. */
+    enqueuemttg<const t extends Omit<mttgjob, 'createdat' | 'retries'>>(job: t): void;
+    /**
+     * drains the MTTG queue with a bounded concurrency (default 4):
+     * dependencies requeue at a lower priority (anti-starvation) and
+     * failures retry up to three times with priority decay.
+     */
+    processmttgqueue(handler: (job: mttgjob) => awaitable<void>, concurrency?: number): Promise<void>;
+    /** dequeues the next job by priority and deadline (v6). */
+    dequeuemttg(): Promise<mttgjob | undefined>;
+    /**
+     * preempts up to three besteffort jobs of lower priority when a
+     * guaranteed job arrives (coreorchestrator QoS preemption).
+     */
+    preemptifneeded(incoming: mttgjob): Promise<readonly mttgjob[]>;
+    /** returns the docker bridge mapping of a vm, when attached. */
+    getdockerbridge(id: vmid): dockerbridgemapping | undefined;
+    /**
+     * builds the docker run sidecar argv of a vm from docker.config
+     * (coreorchestrator); the network name falls back to the numa bridge.
+     */
+    builddockerbridgeargs(id: vmid): Promise<readonly string[]>;
+    /** starts the periodic health monitor. */
+    starthealthmonitor(intervalms?: number): void;
+    /** stops the periodic health monitor. */
+    stophealthmonitor(): void;
+    /** registers a health check over a vm, the host or a gpu. */
+    registerhealthcheck(check: Omit<healthcheck, 'laststatus' | 'lastcheck' | 'failurecount'>): void;
+    /**
+     * records an external health probe (v6); a failing probe moves a
+     * running vm to degraded.
+     */
+    recordhealth(probe: healthprobe): Promise<void>;
+    /** returns the currently failing health probes. */
+    failingvms(): readonly healthprobe[];
+    /** registers an autoscale policy. */
+    registerautoscalepolicy(policy: autoscalepolicy): void;
+    /** starts the periodic autoscaler. */
+    startautoscaler(intervalms?: number): void;
+    /** stops the periodic autoscaler. */
+    stopautoscaler(): void;
+    /**
+     * tenant view of autoscaling (v6): averages the cpu steal of the
+     * tenant probes and proposes one step up above 75 percent or one step
+     * down below 20 percent.
+     */
+    evaluatetenantautoscale(tenantid: string): Promise<{
+        readonly desired: number;
+        readonly current: number;
+        readonly action: 'up' | 'down' | 'none';
+    }>;
+    /**
+     * migrates a running vm to another host; live migrations walk the
+     * precopy, dirty iteration and stop-copy stages with a 50-250ms
+     * downtime window; vfio attached vms require the vfio-migration label.
+     */
+    startmigration(id: vmid, desthost: string, type?: migrationtype, actor?: userid): Promise<result<migrationjob>>;
+    /** v6 alias for startmigration with the live type. */
+    startlivemigration(id: vmid, targethost: string): Promise<migrationjob>;
+    /**
+     * creates a disk snapshot: a qcow2 artifact (with a metadata payload
+     * in the simulated layout), an optional ram image and a json sidecar;
+     * the vm walks running -> snapshotted -> running on the single
+     * machine.
+     */
+    createsnapshot(id: vmid, name: string, includeram?: boolean, actor?: userid): Promise<result<vmsnapshot>>;
+    /** lists snapshots, optionally filtered by vm. */
+    listsnapshots(id?: vmid): readonly vmsnapshot[];
+    /** restores a snapshot; the vm walks back to stopped. */
+    restoresnapshot(snapshot: snapshotid, actor?: userid): Promise<result<void>>;
+    /**
+     * checkpoints a vm with criu, qemu savevm or docker checkpoint
+     * semantics; the passage routes touching the vm are checksummed so the
+     * restore can verify the network plan (v6).
+     */
+    checkpointvm(id: vmid, method?: vmcheckpoint['method'], incremental?: boolean, actor?: userid): Promise<result<vmcheckpoint>>;
+    /** restores a checkpoint; the vm walks provisioning -> running. */
+    restorecheckpoint(checkpoint: checkpointid, actor?: userid): Promise<result<void>>;
+    /** refreshes the runtime gauges and returns the OTel ring tail. */
+    getmetricssnapshot(): readonly otelpoint[];
+    /** renders the Prometheus exposition of the single metrics store. */
+    exportprometheus(): string;
+    /**
+     * starts the OTLP style HTTP exporter serving /metrics and /health;
+     * the bind host is a user choice (explicit argument or resolvehost)
+     * and the port is random in [30000, 59999] unless pinned — the engine
+     * never binds a loopback default.
+     */
+    startotelexporter(host?: string, port?: number): Promise<{
+        readonly host: string;
+        readonly port: number;
+        readonly close: () => void;
+    }>;
+    /** the six dotted config names every deployment must carry. */
+    static mandatoryconfigs(): readonly configfilename[];
+    /**
+     * watches the six dotted configs plus the eight json catalogs; missing
+     * files are created with the default contents before watching starts.
+     */
+    enablehotreload(files?: readonly configfilename[]): void;
+    /** closes every config watcher. */
+    disablehotreload(): void;
+    /**
+     * loads one config file with caching; json files parse into objects
+     * and key=value files parse into a raw string record.
+     */
+    loadconfig(name: configfilename): Promise<unknown>;
+    handleconfigreload(name: configfilename, fullpath: string): Promise<void>;
+    /**
+     * bootstraps the hardware view from the eight flat json catalogs and
+     * reports the missing ones (coreorchestrator).
+     */
+    bootstraphardwareview(): Promise<Record<string, unknown>>;
+    /**
+     * activates a plugin with a context that exposes the orchestrator, a
+     * prefixed logger and typed hook registration on the single bus.
+     */
+    loadplugin(plugin: plugincontract, actor?: userid): Promise<result<void>>;
+    /** deactivates a plugin and forgets it. */
+    unloadplugin(id: pluginid, actor?: userid): Promise<result<void>>;
+    /** v6 alias for loadplugin under the system actor. */
+    registerplugin(plugin: plugincontract): Promise<void>;
+    /** v6 alias for unloadplugin under the system actor. */
+    unregisterplugin(id: pluginid): Promise<void>;
+    /** lists loaded plugins. */
+    listplugins(): readonly plugincontract[];
+    /** filters the in-memory audit ring by user, action and since date. */
+    getauditlog(filter?: {
+        readonly userid?: userid;
+        readonly action?: string;
+        readonly since?: Date;
+    }): readonly auditentry[];
+    /**
+     * appends one audit line to the tenant JSONL file under audit/
+     * (coreorchestrator); the ring mirrors the entry for fast queries.
+     */
+    auditlog(entry: {
+        readonly actor: string;
+        readonly action: string;
+        readonly resource: string;
+        readonly tenant: string;
+        readonly meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * drains one vm: signals the guest for a graceful stop and waits up
+     * to the task timeout (capped at two seconds in simulated mode).
+     */
+    drainvm(id: vmid, task: draintask): Promise<result<void>>;
+    /**
+     * graceful shutdown of the whole orchestrator: monitors stop, hot
+     * reload closes, running vms drain with concurrency four against an
+     * overall timeout and leftover qemu processes get SIGKILL.
+     */
+    gracefulshutdown(timeoutsec?: number): Promise<void>;
+    /**
+     * drains a node identified by a label pair: running vms that carry the
+     * label migrate away (or terminate when migration fails) unless they
+     * are marked drain-protected (coreorchestrator).
+     */
+    drainnode(labelkey: string, labelvalue: string): Promise<readonly string[]>;
+    /**
+     * starts the bully leader election over the peers with a lease in
+     * seconds; the highest node id wins whenever the lease expires.
+     */
+    startleaderelection(peers: readonly string[], leasesec?: number): void;
+    /** returns a readonly view of the leader state. */
+    getleaderstate(): deepreadonly<leaderstate>;
+    /** true when this node currently holds leadership. */
+    isleader(): boolean;
+    /** fresh spec builder (builder pattern entry point). */
+    builder(): sandboxbuilder;
+    /** probes every runtime binary. */
+    detectruntimes(): Promise<Record<string, boolean>>;
+    /** creates a sandbox through the strategy for its runtime. */
+    create(spec: sandboxspec): Promise<sandboxproxy>;
+    /** restores a firecracker sandbox from a snapshot file. */
+    restore(spec: sandboxspec, snapshotfile: string): Promise<sandboxproxy>;
+    /** enables the warm pool with a template spec. */
+    enablewarmpool(min: number, max: number, template: sandboxspec): Promise<void>;
+    /** acquires a warm sandbox. */
+    createpooled(): Promise<sandboxproxy>;
+    /** disables the warm pool and destroys the warm sandboxes. */
+    disablewarmpool(): Promise<void>;
+    /** criu checkpoint of a live sandbox process tree. */
+    checkpoint(sandbox: sandboxproxy, dir?: string): Promise<void>;
+    /** criu restore of a checkpointed image directory. */
+    criurestore(dir: string): Promise<void>;
+    /** destroys every active sandbox. */
+    destroyall(): Promise<void>;
+    /** compose 5.5.0 rendering of a spec. */
+    composeyaml(spec: sandboxspec): string;
+    /**
+     * prepares the runtime directories, materializes the default flat
+     * configs, optionally enables hot-reload and starts the health
+     * monitor, the autoscaler and the scheduler tick.
+     */
+    start(): Promise<void>;
+    /** graceful shutdown plus scheduler teardown. */
+    stop(): Promise<void>;
+    /** full diagnostics dump of both planes. */
+    dumpstate(): Record<string, unknown>;
+    [Symbol.dispose](): void;
+}
+/**
+ * returns the singleton orchestrator, creating it on the first call with
+ * options; later calls ignore their options and always return the same
+ * instance.
+ */
+declare function getorchestrator(options?: orchestratoroptions): orchestrator;
+/**
+ * end-to-end demo: a vm is created and scheduled, an mttg job flows
+ * through the queue, a passage route resolves and the metrics snapshot
+ * is returned; the vm plane is destroyed before returning so the demo
+ * leaves no state behind.
+ */
+export declare function orchestratordemo(): Promise<metricsview>;
+/** one kustomize overlay of the planned GitOps repository. */
+export interface fluxkustomization {
+    readonly path: string;
+    readonly resources: readonly string[];
+    readonly yaml: string;
+}
+/** the planned Flux GitOps repository layout for SADDLE CRDs. */
+export interface fluxgitopsplan {
+    readonly repo: string;
+    readonly branches: readonly string[];
+    readonly clusters: readonly string[];
+    readonly kustomizations: readonly fluxkustomization[];
+    readonly bootstrapargv: readonly string[];
+    readonly syncpolicy: {
+        readonly interval: string;
+        readonly prune: boolean;
+        readonly selfheal: boolean;
+    };
+}
+/**
+ * plans the Flux GitOps repository layout for SADDLE CRDs (ledger
+ * F-064): branch model (main promoted through staging), one
+ * flux-system bootstrap per cluster, an infrastructure layer holding
+ * the VirtualMachine CRD (buildvmcrdmanifest in compute.ts) plus OPA
+ * gatekeeper policies, and an apps layer holding the per-cluster
+ * VirtualMachine custom resources. the planner emits the full
+ * kustomization.yaml content for each overlay and the exact flux
+ * bootstrap argv (with the GHCR image repository and sync intervals),
+ * so `flux bootstrap` plus a git push is everything the operator runs.
+ */
+export declare function planfluxgitops(opts?: {
+    repo?: string;
+    clusters?: readonly string[];
+    interval?: string;
+    prune?: boolean;
+    selfheal?: boolean;
+}): fluxgitopsplan;
+export type { affinityrule, affinityselector, autoscalepolicy, awaitable, balloonstate, brand, checkpointid, configfilename, cpuset, deepreadonly, dockerbridgemapping, draintask, gpuassignment, gpupassthroughrequest, healthcheck, healthprobe, leaderstate, lifecyclestate, metricsview, migrationjob, migrationtype, mttgjob, numanodeid, numatopologyview, orchestratoroptions, otelpoint, passageroute, permission, plugincontext, plugincontract, portmapping, quotastate, rbacprincipal, rbacrole, replayrecord, reservation, result, roleid, runqueue, runresult, sandboxeventname, sandboxruntime, sandboxspec, snapshotid, sriovpf, userid, VcpuId, vcputask, vcputopology, vmcheckpoint, vmdefinition, vmid, vmrecord, vmsnapshot, vramballoon, };
+export { allocport, cantransition, clhruntime, composeyaml, createvmid, cricheckpointer, dockerruntime, fcrequest, firecrackerruntime, getorchestrator, gvisorruntime, kataruntime, kvmavailable, lifecyclefromphase, orchestrator, orchestratorerror, performetrics, priorityqueue, qemuruntime, resolvehost, runtimecatalog, runtimeregistry, sandboxbuilder, sandboxevents, sandboxfactory, sandboxhandle, sandboxmetrics, sandboxproxy, stackcatalog, transitions, vmimage, warmpool, };
+//# sourceMappingURL=orchestrator.d.ts.map