@wenathlan/saddle 1.8.17 → 2.0.2

package/dist/index.js

@@ -1,124 +1,1020 @@
 /**
- * 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 "./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.
+ */
+/* ── Section 1: the e2ugh virtual-hardware engine core ── */
+import { randomInt, randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/* ------------------------------------------------------------------ */
+/* Section 1: reference versions                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 const engineversions = {
+    /** npm latest confirmed 2026-08-23 (v12 shipped july 2026). */
+    npm: '12.0.2',
+    /** python stable confirmed 2026-08-23. */
+    python: '3.14.7',
+    nodecurrent: '26.7.0',
+    nodelts: '24.19.0',
+    typescript: '7.0.2',
+    docker: '29.7.2',
+    compose: '5.5.0',
+    mesaa: '26.2.1',
+    qemu: '11.1.0',
+    firecracker: '1.16.1',
+    kata: '4.1.0',
+    gvisor: 'release-20260817.0',
+    cloudhypervisor: '53.0',
+    criu: '4.2.1',
+    /* v3-VERIFY corrections (worklog 2026-08-23): kernel "7.2.1" never
+     * existed (mainline 7.2, stable 7.1.9, longterm 6.18.45) and wgpu
+     * moved from 24.x to 30.x; wasmtime 48.0.0 LTS confirmed. */
+    kernelmainline: '7.2',
+    kernelstable: '7.1.9',
+    kernellongterm: '6.18.45',
+    wasmtime: '48.0.0',
+    wgpu: '30.x',
+};
+/**
+ * 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 const enginelimits = {
+    minvcpu: 1,
+    maxvcpu: 192,
+    minramgb: 1,
+    maxramgb: 1024,
+    minvramgb: 8,
+    maxvramgb: 96,
+    minport: 30000,
+    maxport: 59999,
+};
+/* ------------------------------------------------------------------ */
+/* Section 3: random port allocation and host resolution               */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 function randomPort(override) {
+    try {
+        if (typeof override === 'number') {
+            if (!Number.isInteger(override) ||
+                override < enginelimits.minport ||
+                override > enginelimits.maxport) {
+                throw new RangeError(`port must be an integer between ${enginelimits.minport} and ${enginelimits.maxport}`);
+            }
+            return override;
+        }
+        return 30000 + randomInt(30000);
+    }
+    catch (cause) {
+        throw new engineerror('randomPort failed', { cause: cause });
+    }
+}
+/**
+ * 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 function resolveHost(preferred) {
+    try {
+        const fromenv = process.env.virtualenginehost ?? process.env.vhehost;
+        const chosen = preferred ?? fromenv;
+        if (typeof chosen !== 'string' || chosen.trim().length === 0) {
+            throw new engineerror('host is required: pass an explicit host or set virtualenginehost; the engine never assumes a default address');
+        }
+        return chosen.trim();
+    }
+    catch (cause) {
+        if (cause instanceof engineerror) {
+            throw cause;
+        }
+        throw new engineerror('resolveHost failed', { cause: cause });
+    }
+}
+/**
+ * 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 function buildEndpoint(host, port) {
+    try {
+        const resolvedhost = resolveHost(host);
+        const resolvedport = randomPort(port);
+        return {
+            host: resolvedhost,
+            port: resolvedport,
+            url: `http://${resolvedhost}:${resolvedport}`,
+        };
+    }
+    catch (cause) {
+        throw new engineerror('buildEndpoint failed', { cause: cause });
+    }
+}
+/**
+ * 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 const specschema = [
+    { key: 'model', kind: 'string', pattern: /\S+/, description: 'non-empty processor model name' },
+    {
+        key: 'vcpus',
+        kind: 'number',
+        min: enginelimits.minvcpu,
+        max: enginelimits.maxvcpu,
+        description: 'vCPU count between 1 and 192',
+    },
+    {
+        key: 'ramgb',
+        kind: 'number',
+        min: enginelimits.minramgb,
+        max: enginelimits.maxramgb,
+        description: 'guest RAM in GB between 1 and 1024',
+    },
+    {
+        key: 'vramgb',
+        kind: 'number',
+        min: enginelimits.minvramgb,
+        max: enginelimits.maxvramgb,
+        description: 'virtualized VRAM in GB between 8 and 96',
+    },
+    {
+        key: 'mig',
+        kind: 'enum',
+        values: ['1g.24gb', '2g.48gb', '4g.96gb', 'off'],
+        description: 'MIG slicing profile',
+    },
+    {
+        key: 'runtime',
+        kind: 'enum',
+        values: ['qemu', 'firecracker', 'docker', 'gvisor'],
+        description: 'execution backend',
+    },
+    {
+        key: 'host',
+        kind: 'string',
+        pattern: /\S+/,
+        description: 'user chosen bind host, never defaulted',
+    },
+    {
+        key: 'port',
+        kind: 'number',
+        min: enginelimits.minport,
+        max: enginelimits.maxport,
+        description: 'port between 30000 and 59999',
+    },
+    {
+        key: 'metricsintervalms',
+        kind: 'number',
+        min: 100,
+        max: 3600000,
+        description: 'sampling interval in milliseconds',
+    },
+];
+/**
+ * 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 function validateSpec(spec) {
+    const errors = [];
+    const warnings = [];
+    try {
+        for (const rule of specschema) {
+            const value = spec[rule.key];
+            if (value === undefined) {
+                if (rule.optional !== true) {
+                    errors.push(`${rule.key}: missing required field (${rule.description})`);
+                }
+                continue;
+            }
+            switch (rule.kind) {
+                case 'number': {
+                    if (typeof value !== 'number' || !Number.isFinite(value)) {
+                        errors.push(`${rule.key}: expected a finite number`);
+                        break;
+                    }
+                    if (rule.min !== undefined && value < rule.min) {
+                        errors.push(`${rule.key}: ${value} is below the minimum ${rule.min}`);
+                    }
+                    if (rule.max !== undefined && value > rule.max) {
+                        errors.push(`${rule.key}: ${value} is above the maximum ${rule.max}`);
+                    }
+                    break;
+                }
+                case 'string': {
+                    if (typeof value !== 'string') {
+                        errors.push(`${rule.key}: expected a string`);
+                        break;
+                    }
+                    if (rule.pattern !== undefined && !rule.pattern.test(value)) {
+                        errors.push(`${rule.key}: fails pattern ${String(rule.pattern)} (${rule.description})`);
+                    }
+                    break;
+                }
+                case 'boolean': {
+                    if (typeof value !== 'boolean') {
+                        errors.push(`${rule.key}: expected a boolean`);
+                    }
+                    break;
+                }
+                case 'enum': {
+                    if (typeof value !== 'string' || rule.values?.includes(value) !== true) {
+                        errors.push(`${rule.key}: expected one of ${rule.values?.join(', ') ?? 'nothing'}`);
+                    }
+                    break;
+                }
+                default: {
+                    errors.push(`${rule.key}: unknown rule kind`);
+                }
+            }
+        }
+        if (typeof spec.vramgb === 'number' &&
+            typeof spec.ramgb === 'number' &&
+            spec.vramgb > spec.ramgb) {
+            warnings.push('vramgb exceeds ramgb: legitimate for GPU-first layouts, confirm this is intended');
+        }
+        if (spec.mig === 'off' && typeof spec.vramgb === 'number' && spec.vramgb >= 96) {
+            warnings.push('vramgb of 96 GB without MIG slicing dedicates the whole device to one guest');
+        }
+        if (typeof spec.vcpus === 'number' && spec.vcpus > 64 && spec.runtime === 'firecracker') {
+            warnings.push('firecracker boots fastest with small vCPU counts; large counts increase restore time');
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors, warnings, normalized: null };
+        }
+        const normalized = {
+            model: String(spec.model),
+            vcpus: Number(spec.vcpus),
+            ramgb: Number(spec.ramgb),
+            vramgb: Number(spec.vramgb),
+            mig: spec.mig,
+            runtime: spec.runtime,
+            host: String(spec.host),
+            port: Number(spec.port),
+            metricsintervalms: Number(spec.metricsintervalms),
+        };
+        return { valid: true, errors, warnings, normalized: Object.freeze(normalized) };
+    }
+    catch (cause) {
+        return {
+            valid: false,
+            errors: [`validateSpec crashed: ${cause.message}`],
+            warnings,
+            normalized: 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 class InternalMemory {
+    #gauges;
+    #counters;
+    #labels;
+    #series;
+    #probes;
+    constructor() {
+        this.#gauges = new Map();
+        this.#counters = new Map();
+        this.#labels = new Map();
+        this.#series = new Map();
+        this.#probes = new WeakMap();
+    }
+    /** Number of distinct gauges currently registered. */
+    get gaugecount() {
+        return this.#gauges.size;
+    }
+    /** Private accessor that folds counters and gauges into one size metric. */
+    get #totalslots() {
+        return this.#gauges.size + this.#counters.size + this.#labels.size + this.#series.size;
+    }
+    /** Reports how many storage slots are live across all containers. */
+    get slotcount() {
+        return this.#totalslots;
+    }
+    /** Sets a gauge value, creating it when missing. */
+    setgauge(name, value) {
+        try {
+            if (!Number.isFinite(value)) {
+                throw new TypeError(`gauge ${name} must be a finite number`);
+            }
+            this.#gauges.set(name, value);
+            return this;
+        }
+        catch (cause) {
+            throw new engineerror('setgauge failed', { cause: cause });
+        }
+    }
+    /** Reads a gauge, returning the fallback when the gauge is absent. */
+    readgauge(name, fallback = 0) {
+        return this.#gauges.get(name) ?? fallback;
+    }
+    /** Increments a counter by delta (default 1) and returns the new total. */
+    bump(name, delta = 1) {
+        const next = (this.#counters.get(name) ?? 0) + delta;
+        this.#counters.set(name, next);
+        return next;
+    }
+    /** Reads a counter without mutating it. */
+    readcounter(name) {
+        return this.#counters.get(name) ?? 0;
+    }
+    /** Attaches a human readable label for observability tooling. */
+    setlabel(name, value) {
+        this.#labels.set(name, value);
+        return this;
+    }
+    /** Returns a frozen copy of all labels. */
+    readlabels() {
+        return Object.freeze({ ...Object.fromEntries(this.#labels) });
+    }
+    /** Pushes a sample into the rolling series of one engine. */
+    pushsample(engineid, sample, keep = 720) {
+        try {
+            const bucket = this.#series.get(engineid) ?? [];
+            bucket.push(sample);
+            while (bucket.length > keep) {
+                bucket.shift();
+            }
+            this.#series.set(engineid, bucket);
+            return bucket.length;
+        }
+        catch (cause) {
+            throw new engineerror('pushsample failed', { cause: cause });
+        }
+    }
+    /** Computes cpu and memory averages plus peaks for one engine. */
+    aggregate(engineid) {
+        const bucket = this.#series.get(engineid) ?? [];
+        if (bucket.length === 0) {
+            return { count: 0, cpuavg: 0, cpupeak: 0, memavggb: 0, newest: null };
+        }
+        let cpusum = 0;
+        let cpupeak = 0;
+        let memsum = 0;
+        for (const sample of bucket) {
+            cpusum += sample.cpuutilization;
+            cpupeak = Math.max(cpupeak, sample.cpuutilization);
+            memsum += sample.memusedgb;
+        }
+        return {
+            count: bucket.length,
+            cpuavg: Number((cpusum / bucket.length).toFixed(4)),
+            cpupeak,
+            memavggb: Number((memsum / bucket.length).toFixed(4)),
+            newest: bucket[bucket.length - 1] ?? null,
+        };
+    }
+    /** Stores an ephemeral probe keyed by a weak object reference. */
+    attachprobe(owner, sample) {
+        this.#probes.set(owner, sample);
+    }
+    /** Reads an ephemeral probe; returns null when the owner is gone. */
+    readprobe(owner) {
+        return this.#probes.get(owner) ?? null;
+    }
+    /** Drops every container, leaving the store empty but reusable. */
+    clear() {
+        this.#gauges.clear();
+        this.#counters.clear();
+        this.#labels.clear();
+        this.#series.clear();
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Section 6: disposable MetricsStore for using declarations           */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 class MetricsStore {
+    #memory;
+    #engineid;
+    #snapshotdir;
+    #disposed;
+    constructor(engineid, snapshotdir) {
+        this.#memory = new InternalMemory();
+        this.#engineid = engineid;
+        this.#snapshotdir = snapshotdir ?? null;
+        this.#disposed = false;
+    }
+    /** Direct access to the underlying InternalMemory containers. */
+    get memory() {
+        return this.#memory;
+    }
+    /** Engine identifier this store is bound to. */
+    get engineid() {
+        return this.#engineid;
+    }
+    /** True once a disposer has run for this instance. */
+    get disposed() {
+        return this.#disposed;
+    }
+    /** Records a sample into the rolling series. */
+    record(sample) {
+        if (this.#disposed) {
+            throw new engineerror('MetricsStore is disposed and cannot record');
+        }
+        this.#memory.pushsample(this.#engineid, sample);
+        this.#memory.setgauge('lastcpu', sample.cpuutilization);
+        this.#memory.setgauge('lastmemgb', sample.memusedgb);
+        return this;
+    }
+    /** Persists the current aggregate snapshot to the configured directory. */
+    flush() {
+        try {
+            if (this.#snapshotdir === null) {
+                return null;
+            }
+            const aggregate = this.#memory.aggregate(this.#engineid);
+            const payload = JSON.stringify({ engineid: this.#engineid, at: Date.now(), aggregate, labels: this.#memory.readlabels() }, null, 2);
+            mkdirSync(this.#snapshotdir, { recursive: true });
+            const file = join(this.#snapshotdir, `${this.#engineid}.metrics.json`);
+            writeFileSync(file, payload, 'utf8');
+            return file;
+        }
+        catch (cause) {
+            throw new engineerror('MetricsStore.flush failed', { cause: cause });
+        }
+    }
+    /** Loads a previously persisted snapshot, returning null when missing. */
+    restore() {
+        try {
+            if (this.#snapshotdir === null) {
+                return null;
+            }
+            const file = join(this.#snapshotdir, `${this.#engineid}.metrics.json`);
+            const raw = readFileSync(file, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Synchronous disposer used by `using store = new MetricsStore(...)`. */
+    [Symbol.dispose]() {
+        if (this.#disposed) {
+            return;
+        }
+        try {
+            this.flush();
+        }
+        catch {
+            /* persistence failures must never mask scope exit */
+        }
+        finally {
+            this.#disposed = true;
+        }
+    }
+    /** Asynchronous disposer used by `await using` declarations. */
+    async [Symbol.asyncDispose]() {
+        this[Symbol.dispose]();
+    }
+}
+/**
+ * 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 class enginebus {
+    #emitter;
+    constructor() {
+        this.#emitter = new EventEmitter();
+        this.#emitter.setMaxListeners(0);
+    }
+    /** Subscribes a typed listener to one topic. */
+    subscribe(topic, listener) {
+        this.#emitter.on(topic, listener);
+        return this;
+    }
+    /** Removes a previously subscribed listener. */
+    unsubscribe(topic, listener) {
+        this.#emitter.off(topic, listener);
+        return this;
+    }
+    /** Publishes one event; the boolean mirrors EventEmitter emit results. */
+    publish(topic, payload) {
+        return this.#emitter.emit(topic, payload);
+    }
+    /** Waits until one topic fires, resolving with its payload. */
+    waitfor(topic) {
+        return new Promise((resolve) => {
+            this.#emitter.once(topic, (payload) => {
+                resolve(payload);
+            });
+        });
+    }
+    /** Returns how many listeners are attached to one topic. */
+    listenercount(topic) {
+        return this.#emitter.listenerCount(topic);
+    }
+}
+/** Process-wide bus shared by factories in this module. */
+export const engineeventbus = new enginebus();
+/* ------------------------------------------------------------------ */
+/* Section 8: error type and safe execution helpers                    */
+/* ------------------------------------------------------------------ */
+/** Error thrown by every engine subsystem with an optional cause chain. */
+export class engineerror extends Error {
+    /** Machine readable subsystem tag. */
+    subsystem;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'engineerror';
+        this.subsystem = options?.subsystem ?? 'core';
+    }
+}
+/**
+ * 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 function safecall(label, action, fallback) {
+    try {
+        return { ok: true, value: action() };
+    }
+    catch (cause) {
+        const error = cause instanceof Error
+            ? cause
+            : new engineerror(`safecall ${label} failed`, { cause: cause });
+        engineeventbus.publish('engine:error', { engineid: label, error });
+        if (fallback !== undefined) {
+            try {
+                return { ok: true, value: fallback() };
+            }
+            catch (inner) {
+                return {
+                    ok: false,
+                    error: new engineerror(`safecall ${label} fallback failed`, { cause: inner }),
+                };
+            }
+        }
+        return { ok: false, error };
+    }
+}
+/**
+ * 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 class VirtualEngine {
+    #id;
+    #spec;
+    #state;
+    #memory;
+    #bus;
+    #createdat;
+    #startedat;
+    #endpoint;
+    constructor(spec, bus) {
+        this.#id = randomUUID();
+        this.#spec = spec;
+        this.#state = 'created';
+        this.#memory = new InternalMemory();
+        this.#bus = bus;
+        this.#createdat = Date.now();
+        this.#startedat = null;
+        this.#endpoint = null;
+        this.#memory.setlabel('model', spec.model);
+        this.#memory.setlabel('runtime', spec.runtime);
+    }
+    /** Unique identifier of this engine instance. */
+    get id() {
+        return this.#id;
+    }
+    /** Frozen specification the engine was created with. */
+    get spec() {
+        return this.#spec;
+    }
+    /** Current lifecycle state. */
+    get state() {
+        return this.#state;
+    }
+    /** Milliseconds elapsed since creation. */
+    get uptimems() {
+        return Date.now() - this.#createdat;
+    }
+    /** Endpoint after a successful start, otherwise null. */
+    get endpoint() {
+        return this.#endpoint;
+    }
+    /** Internal metrics store of this engine. */
+    get memory() {
+        return this.#memory;
+    }
+    #transition(to) {
+        const from = this.#state;
+        this.#state = to;
+        this.#bus.publish('engine:statechanged', { engineid: this.#id, from, to });
+    }
+    /** Moves the engine to running, binding the resolved endpoint. */
+    start() {
+        try {
+            if (this.#state === 'running') {
+                throw new engineerror('engine is already running');
+            }
+            this.#transition('starting');
+            this.#bus.publish('engine:starting', { engineid: this.#id, spec: this.#spec });
+            this.#endpoint = buildEndpoint(this.#spec.host, this.#spec.port);
+            this.#startedat = Date.now();
+            this.#memory.setgauge('port', this.#endpoint.port);
+            this.#memory.bump('starts');
+            this.#transition('running');
+            this.#bus.publish('engine:running', { engineid: this.#id, endpoint: this.#endpoint });
+            return this.#endpoint;
+        }
+        catch (cause) {
+            this.#transition('degraded');
+            const error = cause instanceof Error ? cause : new engineerror('start failed', { cause: cause });
+            this.#bus.publish('engine:error', { engineid: this.#id, error });
+            throw error;
+        }
+    }
+    /** Stops a running engine and publishes the measured uptime. */
+    stop() {
+        if (this.#state === 'stopped') {
+            return;
+        }
+        const started = this.#startedat ?? this.#createdat;
+        this.#memory.bump('stops');
+        this.#transition('stopped');
+        this.#bus.publish('engine:stopped', { engineid: this.#id, uptimems: Date.now() - started });
+    }
+    /** Builds an immutable snapshot of the engine state. */
+    snapshot() {
+        return Object.freeze({
+            engineid: this.#id,
+            state: this.#state,
+            spec: this.#spec,
+            uptimems: this.uptimems,
+            metrics: this.#memory.aggregate(this.#id),
+            versions: engineversions,
+        });
+    }
+    /** Runs structural health checks over spec, state and metrics. */
+    healthcheck() {
+        const checks = [];
+        const validation = validateSpec(this.#spec);
+        checks.push({
+            name: 'spec',
+            passed: validation.valid,
+            detail: validation.valid
+                ? 'specification passes the rule table'
+                : validation.errors.join('; '),
+        });
+        checks.push({
+            name: 'state',
+            passed: this.#state === 'running' || this.#state === 'created',
+            detail: `current state is ${this.#state}`,
+        });
+        checks.push({
+            name: 'endpoint',
+            passed: this.#state !== 'running' || this.#endpoint !== null,
+            detail: this.#endpoint === null
+                ? 'no endpoint bound'
+                : `bound to ${this.#endpoint.host}:${this.#endpoint.port}`,
+        });
+        checks.push({
+            name: 'samples',
+            passed: true,
+            detail: `${this.#memory.aggregate(this.#id).count} samples retained`,
+        });
+        const healthy = checks.every((check) => check.passed);
+        return Object.freeze({ engineid: this.#id, healthy, state: this.#state, checks });
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Section 10: registry and main factory                               */
+/* ------------------------------------------------------------------ */
+/** Registry of live engines keyed by engine id. */
+export const engineRegistry = new Map();
+/** Ephemeral health probes; WeakMap keeps engines garbage collectable. */
+const healthprobes = new WeakMap();
+/**
+ * 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 function createVirtualEngine(options) {
+    try {
+        const host = resolveHost(options.host);
+        const candidate = {
+            model: options.model ?? 'AMD EPYC 9965',
+            vcpus: options.vcpus ?? 8,
+            ramgb: options.ramgb ?? 16,
+            vramgb: options.vramgb ?? 24,
+            mig: options.mig ?? '1g.24gb',
+            runtime: options.runtime ?? 'qemu',
+            host,
+            port: randomPort(options.port),
+            metricsintervalms: options.metricsintervalms ?? 1000,
+        };
+        const validation = validateSpec(candidate);
+        if (!validation.valid || validation.normalized === null) {
+            throw new engineerror(`invalid engine specification: ${validation.errors.join('; ')}`);
+        }
+        const engine = new VirtualEngine(validation.normalized, engineeventbus);
+        engineRegistry.set(engine.id, engine);
+        engine.memory.setgauge('vcpus', validation.normalized.vcpus);
+        engine.memory.setgauge('ramgb', validation.normalized.ramgb);
+        engine.memory.setgauge('vramgb', validation.normalized.vramgb);
+        engineeventbus.publish('engine:created', { engineid: engine.id, at: Date.now() });
+        return engine;
+    }
+    catch (cause) {
+        if (cause instanceof engineerror) {
+            throw cause;
+        }
+        throw new engineerror('createVirtualEngine failed', { cause: cause });
+    }
+}
+/** Registers a fresh health probe for an engine and returns it. */
+export function probeengine(engine) {
+    const report = engine.healthcheck();
+    healthprobes.set(engine, report);
+    return report;
+}
+/** Reads the latest health probe recorded for an engine, if any. */
+export function lastprobe(engine) {
+    return healthprobes.get(engine) ?? null;
+}
+/** Removes an engine from the registry; returns true when it existed. */
+export function disposeengine(engineid) {
+    return engineRegistry.delete(engineid);
+}
+/**
+ * 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 function startsampling(engine, store) {
+    let _tick = 0;
+    const total = engine.spec.ramgb;
+    const vtotal = engine.spec.vramgb;
+    const timer = setInterval(() => {
+        _tick += 1;
+        const sample = {
+            at: Date.now(),
+            cpuutilization: Number((randomInt(5, 95) + Math.random()).toFixed(4)),
+            memusedgb: Number((total * (randomInt(20, 80) / 100)).toFixed(3)),
+            memtotalgb: total,
+            vramusedgb: Number((vtotal * (randomInt(10, 90) / 100)).toFixed(3)),
+            vramtotalgb: vtotal,
+            iops: randomInt(1000, 250000),
+        };
+        store.record(sample);
+        engineeventbus.publish('metrics:sample', { engineid: engine.id, sample });
+    }, engine.spec.metricsintervalms);
+    const handle = {
+        stop: () => {
+            clearInterval(timer);
+        },
+        [Symbol.dispose]: () => {
+            clearInterval(timer);
+        },
+    };
+    return handle;
+}
+/**
+ * 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 const defaultplan = {
+    name: 'aether-lab',
+    cpu: 'AMD Ryzen 9 9950X3D',
+    gpu: 'NVIDIA GeForce RTX 5090',
+    sockets: 1,
+    dies: 2,
+    cores: 8,
+    threads: 2,
+    vcpus: 16,
+    memorygib: 64,
+    vramgib: 32,
+    overcommit: 4,
+    gpumode: 'vfio',
+    mttg: true,
+    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 function plantopology(candidate) {
+    return candidate.sockets * candidate.dies * candidate.cores * candidate.threads;
+}
+/**
+ * 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 function qemuargv(candidate) {
+    const maxcpus = Math.max(candidate.vcpus, plantopology(candidate));
+    const args = [
+        'qemu-system-x86_64',
+        '-nodefaults',
+        '-machine',
+        'q35,accel=kvm,kernel-irqchip=split,hpet=off',
+        '-cpu',
+        'host,kvm=on,l3-cache=on,topoext=on,+x2apic',
+        '-smp',
+        `cpus=${Math.min(candidate.vcpus, plantopology(candidate))},sockets=${candidate.sockets},dies=${candidate.dies},cores=${candidate.cores},threads=${candidate.threads},maxcpus=${maxcpus}`,
+        '-m',
+        `${candidate.memorygib}G,slots=4,maxmem=${Math.max(candidate.memorygib * 2, candidate.memorygib + 32)}G`,
+        '-name',
+        `${candidate.name},debug-threads=on`,
+        '-nographic',
+        '-serial',
+        'mon:stdio',
+        '-device',
+        'virtio-balloon-pci,deflate-on-oom=on,free-page-reporting=on',
+        '-device',
+        'virtio-net-pci,netdev=n0,mq=on,vectors=10',
+        '-netdev',
+        'tap,id=n0,vhost=on,queues=4,script=no,downscript=no',
+    ];
+    if (candidate.gpumode === 'vfio') {
+        args.push('-device', 'vfio-pci,host=01:00.0,multifunction=on,x-vga=on', '-vga', 'none');
+    }
+    else if (candidate.gpumode === 'virtio') {
+        args.push('-device', 'virtio-gpu-gl,hostmem=8G,blob=on,venus=on');
+    }
+    if (candidate.mttg) {
+        args.push('-fw_cfg', `name=opt/aetherforge/mttg,string=${candidate.mttgthreads}`);
+    }
+    return args;
+}
+/** renders the plan argv as a copy-pasteable shell command. */
+export function qemucommand(candidate) {
+    return qemuargv(candidate)
+        .map((token) => (token.includes(' ') || token.includes(',') ? `'${token}'` : token))
+        .join(' \\\n  ');
+}
+/**
+ * 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 function dockerrun(candidate) {
+    const cpus = (candidate.vcpus / Math.max(1, candidate.overcommit)).toFixed(2);
+    return [
+        `docker run --rm -it --name ${candidate.name}`,
+        `  --cpus=${cpus} --memory=${candidate.memorygib}g --pids-limit=0`,
+        `  -e AETHER_MTTG_THREADS=${candidate.mttgthreads}`,
+        candidate.gpumode === 'none' || candidate.gpumode === 'virtio' ? '' : '  --gpus all',
+        '  ghcr.io/aetherforge/runtime:5',
+    ]
+        .filter(Boolean)
+        .join(' \\\n');
+}
+/** renders the vm.config.toml block of a plan. */
+export function plantoml(candidate) {
+    return `# generated by the saddle v6 planner
+[machine]
+name = "${candidate.name}"
+[cpu]
+model = "${candidate.cpu}"
+sockets = ${candidate.sockets}
+dies = ${candidate.dies}
+cores = ${candidate.cores}
+threads = ${candidate.threads}
+vcpus = ${candidate.vcpus}
+overcommit = ${candidate.overcommit}
+[memory]
+gib = ${candidate.memorygib}
+[gpu]
+model = "${candidate.gpu}"
+mode = "${candidate.gpumode}"
+vram_gib = ${candidate.vramgib}
+[mttg]
+enabled = ${candidate.mttg}
+virtual_threads = ${candidate.mttgthreads}
+`;
+}
+/**
+ * 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 function planlint(candidate) {
+    const notes = [];
+    if (candidate.mttg && candidate.mttgthreads < candidate.vcpus) {
+        notes.push('mttg threads must cover the vcpu count');
+    }
+    if (candidate.overcommit > 64) {
+        notes.push('overcommit ceiling is 64x');
+    }
+    if (candidate.vcpus > 4096) {
+        notes.push('vcpu ceiling is 4096');
+    }
+    if (plantopology(candidate) !== candidate.vcpus) {
+        notes.push(`topology product ${plantopology(candidate)} differs from vcpus ${candidate.vcpus}`);
+    }
+    return notes;
+}
+/* ------------------------------------------------------------------ */
+/* Section 13: export barrel (v2 modules)                              */
+/* ------------------------------------------------------------------ */
+/** 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 memory tier catalog and virtual memory manager. */
+export * from './virtualmemory.js';
+/* ── Section 2: the saddle domain routing barrel ── */
+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.js.map