@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/index.d.ts

@@ -1,125 +1,735 @@
 /**
- * public entry point exports stable factories and leaves adapters replaceable.
- */
-export * from "./core/errors.js";
-export * from "./core/events.js";
-export * from "./core/ids.js";
-export * from "./core/hash.js";
-export * from "./domain/artifacts.js";
-export * from "./domain/jobs.js";
-export * from "./domain/providers.js";
-export * from "./domain/runtime.js";
-export * from "./domain/sessions.js";
-export * from "./memory/modes.js";
-export * from "./memory/objects.js";
-export * from "./memory/targets.js";
-export * from "./memory/transforms.js";
-export * from "./memory/engine.js";
-export * from "./memory/planner.js";
-export * from "./runners/inprocess.js";
-export * from "./runners/scheduler.js";
-export * from "./runtime/engine.js";
-export * from "./storage/adapter.js";
-export * from "./storage/cache.js";
-export * from "./storage/content.js";
-export * from "./storage/memory.js";
-export * from "./storage/pool.js";
-export * from "./storage/sync.js";
-export * from "./runners/health.js";
-export * from "./runners/chain.js";
-export * from "./runners/heartbeat.js";
-export * from "./workflow/triggers.js";
-export * from "./dispatch/resumable.js";
-export * from "./scrape/semantic.js";
-export * from "./scrape/crawl.js";
-export * from "./ai/provenance.js";
-export * from "./observability/metrics.js";
-export * from "./api/auth.js";
-export * from "./api/contracts.js";
-export * from "./mcp/browser.js";
-export * from "./apps/registry.js";
-export * from "./bot/permissions.js";
-export * from "./webhook/delivery.js";
-export * from "./delivery/manifest.js";
-export * from "./storage/chunked.js";
-export * from "./storage/s3compatible.js";
-export * from "./modes/modes.js";
-export * from "./adapters/transport.js";
-export * from "./adapters/github.js";
-export * from "./adapters/socket.js";
-export * from "./adapters/forge.js";
-export * from "./adapters/gitlab.js";
-export * from "./adapters/forgejo.js";
-export * from "./adapters/huggingface.js";
-export * from "./persistence/schema.js";
-export * from "./persistence/adapter.js";
-export * from "./persistence/memory.js";
-export * from "./persistence/sql.js";
-export * from "./persistence/drizzle.js";
-export * from "./persistence/prisma.js";
-export * from "./queue/idempotency.js";
-export * from "./queue/queue.js";
-export * from "./queue/saga.js";
-export * from "./dispatch/workflow.js";
-export * from "./sessions/replay.js";
-export * from "./scrape/robots.js";
-export * from "./scrape/cache.js";
-export * from "./scrape/extract.js";
-export * from "./scrape/scraper.js";
-export * from "./packager/manifest.js";
-export * from "./bot/commands.js";
-export * from "./bot/adapter.js";
-export * from "./bot/bot.js";
-export * from "./protocol/json.js";
-export * from "./protocol/ndjson.js";
-export * from "./protocol/sse.js";
-export * from "./protocol/blocks.js";
-export * from "./workflow/manifest.js";
-export * from "./workflow/templates.js";
-export * from "./workflow/registry.js";
-export * from "./scrape/schema.js";
-export * from "./scrape/normalize.js";
-export * from "./mcp/server.js";
-export * from "./runtime/detect.js";
-export * from "./runtime/abort.js";
-export * from "./runtime/compatibility.js";
-export * from "./runtime/worker.js";
-export * from "./packager/publish.js";
-export * from "./browser/fingerprint.js";
-export * from "./browser/session.js";
-export * from "./browser/index.js";
-export * from "./proxy/pool.js";
-export * from "./captcha/contract.js";
-export * from "./captcha/guard.js";
-export * from "./ai/tokens.js";
-export * from "./ai/chunk.js";
-export * from "./ai/rag.js";
-export * from "./ai/llmstxt.js";
-export * from "./webhook/signature.js";
-export * from "./webhook/receiver.js";
-export * from "./surfaces/manifest.js";
-export * from "./surfaces/n8n.js";
-export * from "./surfaces/adapters.js";
-export * from "./surfaces/controls.js";
-export * from "./surfaces/operations.js";
-export * from "./surfaces/requirements.js";
-export * from "./library/public.js";
-export * from "./runtime/retry.js";
-export * from "./storage/githubcontents.js";
-export * from "./storage/filehosting.js";
-export * from "./persistence/migrations.js";
-export * from "./mcp/transport.js";
-export * from "./api/security.js";
-export * from "./modes/matrix.js";
-export * from "./modes/resolve.js";
-export * from "./binary/build.js";
-export * from "./binary/archive.js";
-export * from "./binary/transform.js";
-export * from "./isolation/contracts.js";
-export * from "./api/rate.js";
-export * from "./api/http.js";
-export * from "./api/service.js";
-export * from "./api/control.js";
-export * from "./extension/index.js";
-export * from "./release/evidence.js";
+ * index.ts — the stable public API of the saddle grand merge (v2.0.0).
+ *
+ * Section 1 carries the e2ugh virtual-hardware engine core (the library-first
+ * entry point of the merged e2ugh repository: the main factory
+ * createVirtualEngine, the dependency-free specification validator
+ * validateSpec, the random endpoint allocator randomPort, the Map-based
+ * internal memory store InternalMemory, the disposable metrics store
+ * MetricsStore, the strongly typed event bus enginebus, and the plan planner
+ * absorbed from the former architect.ts).
+ *
+ * Section 2 routes the saddle domain surface through the root-level domain
+ * files of the consolidation: one optimized TypeScript file per correlated
+ * domain, every former nested folder of both repositories folded at the
+ * repository root.
+ */
+import type { migprofileid } from './virtualmemory.js';
+/**
+ * Frozen table of the reference toolchain versions that the engine targets.
+ * Every value was confirmed against primary sources on 2026-08-22 and is
+ * embedded here so generated documentation and workflows can cite exact
+ * versions without a network round trip. the v2 merge adds the microvm
+ * runtime anchors so every module (orchestrator, virtualization, security)
+ * cites the same ledger.
+ */
+export declare const engineversions: {
+    /** npm latest confirmed 2026-08-23 (v12 shipped july 2026). */
+    readonly npm: '12.0.2';
+    /** python stable confirmed 2026-08-23. */
+    readonly python: '3.14.7';
+    readonly nodecurrent: '26.7.0';
+    readonly nodelts: '24.19.0';
+    readonly typescript: '7.0.2';
+    readonly docker: '29.7.2';
+    readonly compose: '5.5.0';
+    readonly mesaa: '26.2.1';
+    readonly qemu: '11.1.0';
+    readonly firecracker: '1.16.1';
+    readonly kata: '4.1.0';
+    readonly gvisor: 'release-20260817.0';
+    readonly cloudhypervisor: '53.0';
+    readonly criu: '4.2.1';
+    readonly kernelmainline: '7.2';
+    readonly kernelstable: '7.1.9';
+    readonly kernellongterm: '6.18.45';
+    readonly wasmtime: '48.0.0';
+    readonly wgpu: '30.x';
+};
+/** Union of every key available in the engineversions table. */
+export type engineversionkey = keyof typeof engineversions;
+/** Numeric bounds applied to every engine specification. */
+export type enginelimits = {
+    readonly minvcpu: number;
+    readonly maxvcpu: number;
+    readonly minramgb: number;
+    readonly maxramgb: number;
+    readonly minvramgb: number;
+    readonly maxvramgb: number;
+    readonly minport: number;
+    readonly maxport: number;
+};
+/**
+ * Hard limits of the virtual hardware generation. Values mirror the extremes
+ * of the embedded processor bank: 1 to 192 vCPUs (EPYC 9965 class), 1 to
+ * 1024 GB of guest RAM, 8 to 96 GB of virtualized VRAM (RTX PRO 6000 class with
+ * MIG slicing) and the random port range 30000-59999.
+ */
+export declare const enginelimits: {
+    readonly minvcpu: 1;
+    readonly maxvcpu: 192;
+    readonly minramgb: 1;
+    readonly maxramgb: 1024;
+    readonly minvramgb: 8;
+    readonly maxvramgb: 96;
+    readonly minport: 30000;
+    readonly maxport: 59999;
+};
+/** Runtime backend that executes the virtual machine workload. */
+export type engineruntime = 'qemu' | 'firecracker' | 'docker' | 'gvisor';
+/** Lifecycle states of a virtual engine instance. */
+export type enginestate = 'created' | 'starting' | 'running' | 'degraded' | 'stopped';
+/** Full declarative specification of one virtual hardware machine. */
+export type enginespec = {
+    readonly model: string;
+    readonly vcpus: number;
+    readonly ramgb: number;
+    readonly vramgb: number;
+    readonly mig: migprofileid;
+    readonly runtime: engineruntime;
+    readonly host: string;
+    readonly port: number;
+    readonly metricsintervalms: number;
+};
+/** Resolved network endpoint of a running engine. */
+export type engineendpoint = {
+    readonly host: string;
+    readonly port: number;
+    readonly url: string;
+};
+/** Options accepted by createVirtualEngine; every field is optional. */
+export type engineoptions = {
+    readonly model?: string;
+    readonly vcpus?: number;
+    readonly ramgb?: number;
+    readonly vramgb?: number;
+    readonly mig?: migprofileid;
+    readonly runtime?: engineruntime;
+    readonly host?: string;
+    readonly port?: number;
+    readonly metricsintervalms?: number;
+};
+/**
+ * Returns a random TCP port in the 30000-59999 range using a
+ * cryptographically secure generator (node:crypto randomInt). The user may
+ * override the random draw by passing an explicit port, which is validated
+ * against the engine limits before being returned.
+ *
+ * @param override Explicit port chosen by the user; when omitted a random
+ *   port is drawn, which keeps the library free of fixed addresses.
+ */
+export declare function randomPort(override?: number): number;
+/**
+ * Resolves the bind host from explicit preference or the environment
+ * variables `virtualenginehost` or `vhehost`. No default address such as
+ * localhost is ever assumed implicitly: when neither argument nor
+ * environment provides a host the function fails loudly, keeping the
+ * address 100 percent a user choice (an explicit loopback is honored
+ * because it is the explicit decision of the caller).
+ *
+ * @param preferred Host explicitly chosen by the caller; wins over env.
+ */
+export declare function resolveHost(preferred?: string): string;
+/**
+ * Combines a host and a port into an endpoint descriptor. The port falls
+ * back to randomPort when omitted so the endpoint is always concrete.
+ */
+export declare function buildEndpoint(host: string, port?: number): engineendpoint;
+/** Kinds of primitives understood by the built-in rule engine. */
+export type rulekind = 'number' | 'string' | 'boolean' | 'enum';
+/** One validation rule bound to a specification field. */
+export type specrule = {
+    readonly key: keyof enginespec;
+    readonly kind: rulekind;
+    readonly min?: number;
+    readonly max?: number;
+    readonly pattern?: RegExp;
+    readonly values?: readonly string[];
+    readonly optional?: boolean;
+    readonly description: string;
+};
+/** Result of running validateSpec over a candidate specification. */
+export type specvalidationresult = {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+    readonly normalized: enginespec | null;
+};
+/**
+ * Default rule table derived from enginelimits. It behaves like a small
+ * dependency-free schema: each entry describes bounds and shape for one
+ * field of enginespec and validateSpec walks the table collecting errors.
+ */
+export declare const specschema: readonly specrule[];
+/**
+ * Validates a candidate specification against the rule table. The function
+ * is zod-like in spirit but has zero external dependencies: it type-checks
+ * each field, enforces numeric bounds, matches string patterns and rejects
+ * unknown enum values, then returns the errors, soft warnings and a frozen
+ * normalized copy when everything passes.
+ *
+ * @param spec Candidate specification; the const type parameter preserves
+ *   literal inference for callers that pass object literals.
+ */
+export declare function validateSpec<const T extends enginespec>(spec: T): specvalidationresult;
+/** One immutable metric sample. */
+export type metricssample = {
+    readonly at: number;
+    readonly cpuutilization: number;
+    readonly memusedgb: number;
+    readonly memtotalgb: number;
+    readonly vramusedgb: number;
+    readonly vramtotalgb: number;
+    readonly iops: number;
+};
+/** Aggregate view over the stored samples of one engine. */
+export type metricsaggregate = {
+    readonly count: number;
+    readonly cpuavg: number;
+    readonly cpupeak: number;
+    readonly memavggb: number;
+    readonly newest: metricssample | null;
+};
+/**
+ * Map-based internal memory store used by every engine instance. Gauges,
+ * counters, labels and rolling samples live in plain Map containers which
+ * guarantees deterministic iteration, cheap snapshots and no binding to any
+ * runtime-specific global. The store also owns a WeakMap side table for
+ * ephemeral probes that must never keep engines alive.
+ */
+export declare class InternalMemory {
+    #private;
+    constructor();
+    /** Number of distinct gauges currently registered. */
+    get gaugecount(): number;
+    /** Reports how many storage slots are live across all containers. */
+    get slotcount(): number;
+    /** Sets a gauge value, creating it when missing. */
+    setgauge(name: string, value: number): this;
+    /** Reads a gauge, returning the fallback when the gauge is absent. */
+    readgauge(name: string, fallback?: number): number;
+    /** Increments a counter by delta (default 1) and returns the new total. */
+    bump(name: string, delta?: number): number;
+    /** Reads a counter without mutating it. */
+    readcounter(name: string): number;
+    /** Attaches a human readable label for observability tooling. */
+    setlabel(name: string, value: string): this;
+    /** Returns a frozen copy of all labels. */
+    readlabels(): Readonly<Record<string, string>>;
+    /** Pushes a sample into the rolling series of one engine. */
+    pushsample(engineid: string, sample: metricssample, keep?: number): number;
+    /** Computes cpu and memory averages plus peaks for one engine. */
+    aggregate(engineid: string): metricsaggregate;
+    /** Stores an ephemeral probe keyed by a weak object reference. */
+    attachprobe(owner: object, sample: metricssample): void;
+    /** Reads an ephemeral probe; returns null when the owner is gone. */
+    readprobe(owner: object): metricssample | null;
+    /** Drops every container, leaving the store empty but reusable. */
+    clear(): void;
+}
+/**
+ * Disposable metrics facade. Instances are designed for explicit resource
+ * management: `using store = new MetricsStore()` flushes the snapshot to
+ * disk on scope exit through Symbol.dispose, while `await using` performs
+ * the same through Symbol.asyncDispose after letting pending samples
+ * settle. Both disposers are idempotent so double disposal is harmless.
+ * The v2 orchestrator subclasses this store (sandboxmetrics) so the whole
+ * engine keeps exactly one metrics component.
+ */
+export declare class MetricsStore {
+    #private;
+    constructor(engineid: string, snapshotdir?: string);
+    /** Direct access to the underlying InternalMemory containers. */
+    get memory(): InternalMemory;
+    /** Engine identifier this store is bound to. */
+    get engineid(): string;
+    /** True once a disposer has run for this instance. */
+    get disposed(): boolean;
+    /** Records a sample into the rolling series. */
+    record(sample: metricssample): this;
+    /** Persists the current aggregate snapshot to the configured directory. */
+    flush(): string | null;
+    /** Loads a previously persisted snapshot, returning null when missing. */
+    restore(): Record<string, unknown> | null;
+    /** Synchronous disposer used by `using store = new MetricsStore(...)`. */
+    [Symbol.dispose](): void;
+    /** Asynchronous disposer used by `await using` declarations. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Map of every event topic emitted by the engine to its payload type.
+ *
+ * The v2 merge collapses the three buses of the pool (the v5 enginebus,
+ * the Meta TypedEventBus and the Meta SaddleEventBus) into this single
+ * topology: the original engine:* and metrics:* topics plus the full
+ * sandbox:* and vm plane surface (vm, vcpu, vram, gpu, sriov, passage,
+ * mttg, docker, qemu, health, autoscale, numa, migration, snapshot,
+ * checkpoint, config, plugin, rbac, audit, leader, quota, preemption,
+ * drain and system) that orchestrator.ts publishes through sandboxevents,
+ * a subclass of enginebus. no second bus exists anywhere in the library.
+ */
+export type enginetopics = {
+    readonly 'engine:created': {
+        readonly engineid: string;
+        readonly at: number;
+    };
+    readonly 'engine:starting': {
+        readonly engineid: string;
+        readonly spec: enginespec;
+    };
+    readonly 'engine:running': {
+        readonly engineid: string;
+        readonly endpoint: engineendpoint;
+    };
+    readonly 'engine:stopped': {
+        readonly engineid: string;
+        readonly uptimems: number;
+    };
+    readonly 'engine:error': {
+        readonly engineid: string;
+        readonly error: Error;
+    };
+    readonly 'metrics:sample': {
+        readonly engineid: string;
+        readonly sample: metricssample;
+    };
+    readonly 'engine:statechanged': {
+        readonly engineid: string;
+        readonly from: enginestate;
+        readonly to: enginestate;
+    };
+    readonly 'sandbox:created': {
+        readonly id: string;
+        readonly runtime: string;
+        readonly host: string;
+        readonly ports: readonly {
+            readonly host: number;
+            readonly container: number;
+        }[];
+    };
+    readonly 'sandbox:started': {
+        readonly id: string;
+        readonly runtime: string;
+        readonly bootms: number;
+    };
+    readonly 'sandbox:stopped': {
+        readonly id: string;
+        readonly reason: string;
+    };
+    readonly 'sandbox:snapshotted': {
+        readonly id: string;
+        readonly file: string;
+    };
+    readonly 'sandbox:restored': {
+        readonly id: string;
+        readonly snapshotfile: string;
+    };
+    readonly 'sandbox:destroyed': {
+        readonly id: string;
+    };
+    readonly 'sandbox:pooled': {
+        readonly size: number;
+    };
+    readonly 'sandbox:error': {
+        readonly id?: string;
+        readonly phase: string;
+        readonly message: string;
+    };
+    readonly 'vm:created': {
+        readonly vmid: string;
+        readonly tenantid: string;
+    };
+    readonly 'vm:started': {
+        readonly vmid: string;
+        readonly pid: number;
+    };
+    readonly 'vm:stopped': {
+        readonly vmid: string;
+        readonly reason: string;
+    };
+    readonly 'vm:error': {
+        readonly vmid: string;
+        readonly error: string;
+    };
+    readonly 'vm:phase': {
+        readonly vmid: string;
+        readonly to: string;
+    };
+    readonly 'vcpu:scheduled': {
+        readonly vmid: string;
+        readonly vcpuid: string;
+        readonly cpu: number;
+    };
+    readonly 'sched:overcommitwarn': {
+        readonly vmid: string;
+        readonly requested: number;
+        readonly host: number;
+        readonly overcommit: number;
+    };
+    readonly 'vram:adjusted': {
+        readonly vmid: string;
+        readonly targetmib: number;
+        readonly actualmib: number;
+    };
+    readonly 'gpu:assigned': {
+        readonly vmid: string;
+        readonly gpuid: string;
+        readonly vfid?: string;
+    };
+    readonly 'gpu:released': {
+        readonly gpuid: string;
+        readonly vmid: string;
+    };
+    readonly 'sriov:vfcreated': {
+        readonly pf: string;
+        readonly vfid: string;
+    };
+    readonly 'passage:routecreated': {
+        readonly id: string;
+        readonly srcvm: string;
+        readonly dstvm: string;
+        readonly protocol: string;
+    };
+    readonly 'mttg:jobdone': {
+        readonly jobid: string;
+        readonly durationms: number;
+    };
+    readonly 'mttg:enqueued': {
+        readonly jobid: string;
+        readonly tenant: string;
+        readonly qos: string;
+    };
+    readonly 'mttg:preempted': {
+        readonly incoming: string;
+        readonly preempted: readonly string[];
+    };
+    readonly 'docker:attached': {
+        readonly vmid: string;
+        readonly bridge: string;
+        readonly ipv4: string;
+    };
+    readonly 'qemu:exit': {
+        readonly vmid: string;
+        readonly code: number | null;
+    };
+    readonly 'qemu:versionmismatch': {
+        readonly expected: string;
+        readonly got: string;
+    };
+    readonly 'health:change': {
+        readonly checkid: string;
+        readonly old: string;
+        readonly new: string;
+    };
+    readonly 'autoscale:trigger': {
+        readonly policyid: string;
+        readonly action: string;
+        readonly count: number;
+    };
+    readonly 'numa:rebalance': {
+        readonly moves: number;
+        readonly from: number;
+        readonly to: number;
+    };
+    readonly 'migration:progress': {
+        readonly jobid: string;
+        readonly vmid: string;
+        readonly state: string;
+        readonly progress: number;
+    };
+    readonly 'snapshot:created': {
+        readonly snapshotid: string;
+        readonly vmid: string;
+    };
+    readonly 'checkpoint:created': {
+        readonly checkpointid: string;
+        readonly vmid: string;
+        readonly method: string;
+    };
+    readonly 'config:reloaded': {
+        readonly file: string;
+    };
+    readonly 'plugin:loaded': {
+        readonly pluginid: string;
+    };
+    readonly 'plugin:unloaded': {
+        readonly pluginid: string;
+    };
+    readonly 'rbac:denied': {
+        readonly userid: string;
+        readonly action: string;
+    };
+    readonly 'audit:entry': {
+        readonly actor: string;
+        readonly action: string;
+        readonly target: string;
+        readonly result: string;
+    };
+    readonly 'leader:changed': {
+        readonly leader: string;
+        readonly term: number;
+    };
+    readonly 'quota:set': {
+        readonly tenantid: string;
+        readonly vcpu: number;
+        readonly vrammib: number;
+        readonly gpu: number;
+    };
+    readonly 'node:drained': {
+        readonly labelkey: string;
+        readonly labelvalue: string;
+        readonly drained: readonly string[];
+    };
+    readonly 'system:error': {
+        readonly kind: string;
+        readonly message: string;
+    };
+    readonly 'otel:exporterstarted': {
+        readonly host: string;
+        readonly port: number;
+    };
+};
+/** Union of all topic names; template literal types keep it extensible. */
+export type enginetopicname = keyof enginetopics;
+/**
+ * Strongly typed observer bus built on node:events EventEmitter. Publish and
+ * subscribe are generic over the topic map so listeners receive exactly the
+ * payload type of the topic they choose; the underlying EventEmitter is kept
+ * private so external code cannot bypass typing. This class is the single
+ * bus of the engine: orchestrator.ts extends it (sandboxevents) and every
+ * subsystem publishes here instead of creating its own emitter.
+ */
+export declare class enginebus {
+    #private;
+    constructor();
+    /** Subscribes a typed listener to one topic. */
+    subscribe<t extends enginetopicname>(topic: t, listener: (payload: enginetopics[t]) => void): this;
+    /** Removes a previously subscribed listener. */
+    unsubscribe<t extends enginetopicname>(topic: t, listener: (payload: enginetopics[t]) => void): this;
+    /** Publishes one event; the boolean mirrors EventEmitter emit results. */
+    publish<t extends enginetopicname>(topic: t, payload: enginetopics[t]): boolean;
+    /** Waits until one topic fires, resolving with its payload. */
+    waitfor<t extends enginetopicname>(topic: t): Promise<enginetopics[t]>;
+    /** Returns how many listeners are attached to one topic. */
+    listenercount(topic: enginetopicname): number;
+}
+/** Process-wide bus shared by factories in this module. */
+export declare const engineeventbus: enginebus;
+/** Error thrown by every engine subsystem with an optional cause chain. */
+export declare class engineerror extends Error {
+    /** Machine readable subsystem tag. */
+    readonly subsystem: string;
+    constructor(message: string, options?: {
+        cause?: Error;
+        subsystem?: string;
+    });
+}
+/** Outcome shape returned by safecall. */
+export type safeoutcome<t> = {
+    readonly ok: true;
+    readonly value: t;
+} | {
+    readonly ok: false;
+    readonly error: Error;
+};
+/**
+ * Runs an action inside a try/catch catcher and reports the outcome as a
+ * discriminated union instead of throwing, which lets library callers decide
+ * how failures surface. The fallback runs only when the action throws.
+ */
+export declare function safecall<t>(label: string, action: () => t, fallback?: () => t): safeoutcome<t>;
+/** Point-in-time snapshot of an engine. */
+export type enginesnapshot = {
+    readonly engineid: string;
+    readonly state: enginestate;
+    readonly spec: enginespec;
+    readonly uptimems: number;
+    readonly metrics: metricsaggregate;
+    readonly versions: typeof engineversions;
+};
+/** Health report produced by periodic probing. */
+export type healthreport = {
+    readonly engineid: string;
+    readonly healthy: boolean;
+    readonly state: enginestate;
+    readonly checks: readonly {
+        readonly name: string;
+        readonly passed: boolean;
+        readonly detail: string;
+    }[];
+};
+/**
+ * Facade object returned by createVirtualEngine. The class keeps its state
+ * machine private and exposes only intentful operations, emitting typed
+ * events on every transition so orchestrators can react without polling.
+ */
+export declare class VirtualEngine {
+    #private;
+    constructor(spec: enginespec, bus: enginebus);
+    /** Unique identifier of this engine instance. */
+    get id(): string;
+    /** Frozen specification the engine was created with. */
+    get spec(): enginespec;
+    /** Current lifecycle state. */
+    get state(): enginestate;
+    /** Milliseconds elapsed since creation. */
+    get uptimems(): number;
+    /** Endpoint after a successful start, otherwise null. */
+    get endpoint(): engineendpoint | null;
+    /** Internal metrics store of this engine. */
+    get memory(): InternalMemory;
+    /** Moves the engine to running, binding the resolved endpoint. */
+    start(): engineendpoint;
+    /** Stops a running engine and publishes the measured uptime. */
+    stop(): void;
+    /** Builds an immutable snapshot of the engine state. */
+    snapshot(): enginesnapshot;
+    /** Runs structural health checks over spec, state and metrics. */
+    healthcheck(): healthreport;
+}
+/** Registry of live engines keyed by engine id. */
+export declare const engineRegistry: ReadonlyMap<string, VirtualEngine>;
+/**
+ * Creates a fully wired virtual engine from user options. The factory
+ * resolves the host (user choice only), draws a random port in the
+ * 30000-59999 range when none is given, validates the merged specification
+ * with validateSpec, registers the instance in engineRegistry and emits the
+ * engine:created topic. Failures are converted to engineerror instances so
+ * callers always see a typed cause chain.
+ *
+ * @param options Partial specification; only the host is mandatory because
+ *   the library refuses to assume any default address.
+ */
+export declare function createVirtualEngine(options: engineoptions): VirtualEngine;
+/** Registers a fresh health probe for an engine and returns it. */
+export declare function probeengine(engine: VirtualEngine): healthreport;
+/** Reads the latest health probe recorded for an engine, if any. */
+export declare function lastprobe(engine: VirtualEngine): healthreport | null;
+/** Removes an engine from the registry; returns true when it existed. */
+export declare function disposeengine(engineid: string): boolean;
+/** Handle returned by startsampling; disposable for `using` blocks. */
+export type samplinghandle = {
+    readonly stop: () => void;
+};
+/**
+ * Starts a periodic sampling loop that fabricates metric samples with the
+ * node:crypto random generator and records them into the engine metrics
+ * store, emitting a metrics:sample event per iteration. The returned handle
+ * implements Symbol.dispose so it composes with `using` declarations.
+ */
+export declare function startsampling(engine: VirtualEngine, store: MetricsStore): samplinghandle & Disposable;
+/**
+ * GPU mode of a plan. this mirrors the GpuMode enum of forge.hpp (the C++
+ * control plane) and stays intentionally distinct from the runtime gpu
+ * assignment modes of orchestrator.ts (none/passthrough/vgpu/mdev).
+ */
+export type plangpumode = 'vfio' | 'vgpu' | 'mig' | 'virtio' | 'none';
+/** Declarative machine plan consumed by the argv renderers below. */
+export type plan = {
+    readonly name: string;
+    readonly cpu: string;
+    readonly gpu: string;
+    readonly sockets: number;
+    readonly dies: number;
+    readonly cores: number;
+    readonly threads: 1 | 2;
+    readonly vcpus: number;
+    readonly memorygib: number;
+    readonly vramgib: number;
+    readonly overcommit: number;
+    readonly gpumode: plangpumode;
+    readonly mttg: boolean;
+    readonly mttgthreads: number;
+};
+/**
+ * Default plan: a desktop zen5 lab (9950X3D with two CCDs) paired with an
+ * RTX 5090, 65536 multiplexed MTTG threads and a 4x cpu overcommit.
+ */
+export declare const defaultplan: {
+    readonly name: 'aether-lab';
+    readonly cpu: 'AMD Ryzen 9 9950X3D';
+    readonly gpu: 'NVIDIA GeForce RTX 5090';
+    readonly sockets: 1;
+    readonly dies: 2;
+    readonly cores: 8;
+    readonly threads: 2;
+    readonly vcpus: 16;
+    readonly memorygib: 64;
+    readonly vramgib: 32;
+    readonly overcommit: 4;
+    readonly gpumode: 'vfio';
+    readonly mttg: true;
+    readonly mttgthreads: 65536;
+};
+/**
+ * Returns the topology product of a plan (sockets x dies x cores x
+ * threads); distinct from solvetopology of virtualcpu.ts which maps a
+ * processor spec to its physical package view.
+ */
+export declare function plantopology(candidate: plan): number;
+/**
+ * Renders the lean qemu argv of a plan: maxcpus headroom, hotplug memory
+ * slots (maxmem), topology-aware -smp, the mttg thread count exported
+ * through -fw_cfg, and per-gpu-mode device selection. the complete
+ * "turbo" argv (TDX/SEV/vfio romfile/venus) lives in buildqemucmd of
+ * virtualization.ts; the runtime strategy argv lives in orchestrator.ts.
+ */
+export declare function qemuargv(candidate: plan): readonly string[];
+/** renders the plan argv as a copy-pasteable shell command. */
+export declare function qemucommand(candidate: plan): string;
+/**
+ * renders the docker run command of a plan: cpu divided by the overcommit
+ * factor, unbounded pids cgroup (--pids-limit=0) and the MTTG thread
+ * budget exported through AETHER_MTTG_THREADS.
+ */
+export declare function dockerrun(candidate: plan): string;
+/** renders the vm.config.toml block of a plan. */
+export declare function plantoml(candidate: plan): string;
+/**
+ * lints a plan: the MTTG thread budget must cover the vCPUs, the
+ * overcommit ceiling is 64x, the vCPU ceiling is 4096 and the topology
+ * product must equal the vCPU count.
+ */
+export declare function planlint(candidate: plan): readonly string[];
+/** Re-exports the compute domain (wasm/wasmtime 48 lts, webgpu on
+ * lavapipe, node 26 runtime surface, ai workload planners, wasm canary,
+ * wasi:gfx, chatops, gpu ebpf telemetry, ai migration predictor). */
+export * from './compute.js';
+/** Re-exports the media pipeline and transcode domain (24-stage
+ * pipeline, ffmpeg 7.1 NVENC p1-p7 command synthesis, createoptimal
+ * encoder policy, passage ed25519+chacha20-poly1305 channel, 30
+ * transcode modes). */
+export * from './media.js';
+export { bellstate, deutsch, dnacapacity, dnavaultdecode, dnavaultencode, ghzstate, grover2, grover3, opticalplan, qteleport, quantuminspiredrandom, quantumregistry, quantumsim, runbb84, rune91, } from './quantum.js';
+/** Re-exports the scheduling and allocation domain (typecheck sharding,
+ * shared-memory cache, project graph, MIG/vCPU/RAM/GPU/NUMA/PCI
+ * allocation, aipsched, psi lstm, tenant QoS, anomaly detector,
+ * hot reload, otel, health, shutdown, plugin hooks). */
+export * from './scheduler.js';
+export { cgroupsv2slice, creatiersengine, FREEPOOL, githubstorage, LATENCYLADDER, npmchunkregistry, plannpmchunks, publishplan, rambufferbackend, reassembleplan, sqlitekv, sqlitel3backend, swapfilerecipe, sysctldropin, TIERS, tierserror, tmpfsrecipe, zramrecipe, } from './tiers.js';
+/** Re-exports the virtual processor bank and cpuinfo generators. */
+export * from './virtualcpu.js';
+/** Re-exports the gpu passthrough surface (vfio, rom dump, vgpu data). */
+export * from './virtualgpu.js';
+/** Re-exports the virtualization surface (qemu turbo argv, passage,
+ * mttg cgroups, mttg grid, checkpoint and restore, virtualizationcore
+ * bridge). */
+export * from './virtualization.js';
+/** Re-exports the MIG profile union declared by the memory module. */
+export type { migprofileid } from './virtualmemory.js';
+/** Re-exports the memory tier catalog and virtual memory manager. */
+export * from './virtualmemory.js';
+export * from "./foundation.js";
+export * from "./isolation.js";
+export * from "./virtual.js";
+export * from "./execution.js";
+export * from "./browser.js";
+export * from "./acquisition.js";
+export * from "./communication.js";
+export * from "./integration.js";
+export * from "./automation.js";
+export * from "./intelligence.js";
+export * from "./distribution.js";
+export * from "./modes.js";
+export * from "./operations.js";
 //# sourceMappingURL=index.d.ts.map