@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/compute.d.ts

@@ -0,0 +1,1161 @@
+/**
+ * compute.ts — compute, WebAssembly, WebGPU and AI workload domain for saddle v6.
+ *
+ * the module absorbs the compute-facing families of the removed
+ * future.ts file (55-feature ledger, v2) into their proper domain:
+ * - wasm/wasmtime (8): WIT bindings generator, WASI 0.3.0 async runtime
+ *   with cancellation, fuel metering, epoch interruption, wasi:nn
+ *   backend with real softmax, deny-by-default component ACL,
+ *   component registry, linear memory pool
+ * - webgpu (4): forced fallback adapter over lavapipe, compute pipeline
+ *   builder with the 256-invocation limit, WGSL shader cache, matmul
+ *   dispatch planner
+ * - node 26 (7): Temporal-aware scheduler, Float16 tensor storage with
+ *   own binary16 conversion, Error.isError guard, node:sqlite sync
+ *   store with memory fallback, disposable module.register hook chain,
+ *   Perfetto trace sink, private key store with loader indirection
+ * - ai workloads (6): DataLoader /dev/shm planner, TF CUDA
+ *   forward-compatibility matrix, ONNX WebGPU EP session builder, LLM
+ *   inference on lavapipe, headless Stable Diffusion, VRAM budget
+ *
+ * omnihypercore verified additions (research pass 2026-08-23):
+ * - wasm canary validator: module validation with smoke execution and
+ *   automatic rollback to the last healthy revision
+ * - WASI-GFX: the wasi:gfx proposal bringing wgpu 30.x WebGPU into wasm
+ *   components ("wgpu virt wgpu 30"), planned as capability grants
+ * - ChatOps dashboard: chat command builders (/vm create, /gpu attach,
+ *   /migrate) emitting JSON command envelopes plus a WebGPU dashboard
+ *   spec
+ * - GPU telemetry via eBPF: bpf program builder for GPU UAPI counters
+ *   (DRM_IOCTL tracepoints feeding per-engine utilization maps)
+ * - AI live migration pre-copy predictor: dirty page estimation with
+ *   simple online learning, the AI-flavoured companion of the
+ *   checkpoint family that now lives in virtualization.ts
+ *
+ * v4-FIX3 additions (portal 0-reference absorption, 2026-08-23):
+ * - PartyKit edge presence channel builder (rooms, wss endpoints,
+ *   join/leave/update presence, 100 ms heartbeat)
+ * - L3AF 2.1 xBPF marketplace app manager emitting l3afd configs
+ * - GreenHyper RAPL power-aware binpacking governor over
+ *   /sys/class/powercap intel-rapl constraint files
+ * - StateVector 2-round sync: lamport state vectors with
+ *   last-writer-wins merge (CRDT convergence without a coordinator)
+ * - libp2p + BitTorrent v2 content addressing: sha2-256 multihashes,
+ *   base32 CIDv1 raw, 16 KiB merkle roots, magnet links, multiaddrs
+ * - Tailscale tailnet endpoint planner with the CGNAT 100.64.0.0/10
+ *   guard, MagicDNS names, DERP fallback and six mesh milestones
+ * - MAX9 catalogued as a legacy build/delivery variant (zip level 9,
+ *   51% ratio, :max9 tag) - NOT an NVIDIA Maxwell GPU
+ * - roadmapbacklog: the thirteen v4 future.ts items that were still
+ *   unabsorbed (AMX, dual-X3D, WebTransport, Turborepo GHCR, pnpm v9,
+ *   QUIC/H3, WebRTC mesh, OPFS, WebCodecs+WebGPU, SAB cross-origin,
+ *   WASM JSPI, GHCR gha reuse, Nix flakes) plus backlogCount()
+ *
+ * version anchors (worklog v3-VERIFY, 2026-08-23): wasmtime 48.0.0 LTS
+ * (confirmed, supported until 2028-08), spin 3.6.0 (spinframework),
+ * wasmcloud tracked as latest 2.x without a pin (release page did not
+ * expose the version), wgpu 30.x (corrected from 24.x), kernel stable
+ * 7.1.9 / longterm 6.18.45. ports never hardcoded; loopback never used.
+ *
+ * contexts (25+9): witbindings, wasi03async, fuel, epoch, wasinn,
+ * componentacl, componentregistry, wasmmempool, lavapipe, pipelines,
+ * shadercache, temporal, float16, errorguard, sqlitestore, modulehooks,
+ * perfetto, keystore, aiplanners, inference, canary, wasigfx, chatops,
+ * ebpfgpu, aimigration, portalsync, l3afmanager, greenhyper,
+ * statevector, p2pcontent, tailscaleplan, max9variant, roadmapbacklog
+ * (the featureledger appendix closes the file)
+ *
+ * rules: lowercase identifiers, english jsdoc third person, no emoji,
+ * try/catch catcher on every fallible path, node:* built-ins first,
+ * zero runtime dependencies, `using`/`satisfies`/`#private`/const type
+ * parameters throughout.
+ */
+/** WIT primitive and compound type names. */
+export type wittype = 'u8' | 'u16' | 'u32' | 'u64' | 's8' | 's16' | 's32' | 's64' | 'f32' | 'f64' | 'bool' | 'string' | 'timestamp' | `list<${string}>` | `option<${string}>` | `result<${string}, ${string}>`;
+/** one WIT function parameter. */
+export interface witparam {
+    readonly name: string;
+    readonly type: wittype;
+}
+/** one WIT function. */
+export interface witfunction {
+    readonly name: string;
+    readonly params: readonly witparam[];
+    readonly result: wittype | null;
+}
+/** one WIT interface (a named function group). */
+export interface witinterface {
+    readonly name: string;
+    readonly functions: readonly witfunction[];
+}
+/** one WIT world (the component contract). */
+export interface witworld {
+    readonly name: string;
+    readonly interfaces: readonly witinterface[];
+}
+/**
+ * converts a WIT world definition into a typed typescript interface
+ * block, so components loaded by the engine keep static typing end to
+ * end; guest calls return promises per the WASI 0.3 async convention.
+ */
+export declare function wittotypescript(world: witworld): string;
+/** content hash of a WIT world, used to invalidate generated bindings. */
+export declare function witworldhash(world: witworld): string;
+/** one queued WASI 0.3 component call. */
+export interface wasicall {
+    readonly component: string;
+    readonly functionName: string;
+    readonly payload: Uint8Array;
+    readonly deadlineMs: number;
+}
+/**
+ * models the native async calls of WASI 0.3.0: every guest call is
+ * queued, runs under an epoch deadline, and can be cancelled with the
+ * cancelled-by-host semantics of the component model.
+ */
+export declare class wasiasyncruntime implements Disposable {
+    #private;
+    invoke(call: wasicall): {
+        id: string;
+        promise: Promise<Uint8Array>;
+    };
+    cancel(callId: string): boolean;
+    get queued(): number;
+    [Symbol.dispose](): void;
+}
+/**
+ * wraps deterministic instruction budgets exactly like `wasmtime --fuel`:
+ * fuel is consumed per instruction batch, refunded on early exit, and
+ * exhausts with a trap.
+ */
+export declare class fuelmeter {
+    #private;
+    readonly budget: number;
+    constructor(budget: number);
+    consume(instructions: number): boolean;
+    refund(instructions: number): void;
+    get consumed(): number;
+    get remaining(): number;
+    get exhausted(): boolean;
+}
+/** runs a callback under a fuel budget; throws a trap when it is hit. */
+export declare function withfuel<T>(budget: number, fn: (meter: fuelmeter) => T): T;
+/**
+ * epoch interruption, preferred over fuel for wall-clock timeouts
+ * because it costs roughly 10 percent overhead instead of
+ * per-instruction accounting; the deadline is stored in epoch ticks
+ * and checked at epoch callback points.
+ */
+export declare class epochinterruption {
+    #private;
+    constructor(tickMs?: number);
+    setdeadline(timeoutMs: number): void;
+    tick(): void;
+    get expired(): boolean;
+    /** measured overhead of epoch interruption relative to fuel metering. */
+    static get relativeoverhead(): number;
+}
+/** one registered inference graph. */
+export interface nngraph {
+    readonly name: string;
+    readonly tensorType: 'f16' | 'f32' | 'u8';
+    readonly dims: readonly number[];
+}
+/**
+ * a wasi:nn backend: graphs declare tensor shapes and execution runs a
+ * real numerically stable softmax over the input tensor, enough to
+ * smoke-test serving pipelines before a real backend (onnx runtime,
+ * burns or candle) attaches.
+ */
+export declare class wasinnbackend {
+    #private;
+    load(name: string, dims: readonly number[], tensorType?: nngraph['tensorType']): nngraph;
+    execute(graphName: string, tensor: Float32Array): Float32Array;
+    list(): readonly string[];
+}
+/** WASI capability names a component may be granted. */
+export type wascapability = 'wasi:io' | 'wasi:clocks' | 'wasi:random' | 'wasi:nn' | 'wasi:sockets' | 'wasi:filesystem' | 'wasi:http' | 'wasi:gfx';
+/**
+ * components start with zero ambient authority: every capability must
+ * be granted explicitly before a component may use it, the mirror of
+ * the wasmtime deny-by-default model.
+ */
+export declare class componentacl {
+    #private;
+    grant(component: string, capability: wascapability): this;
+    assert(component: string, capability: wascapability): void;
+    grantsfor(component: string): readonly wascapability[];
+}
+/** one instantiated component with its deterministic guards. */
+export interface componentinstance {
+    readonly id: string;
+    readonly name: string;
+    readonly fuel: fuelmeter;
+    readonly epoch: epochinterruption;
+}
+/**
+ * keeps named component instances together with their fuel meter,
+ * epoch interrupter and revision tag, and disposes them
+ * deterministically via `using`.
+ */
+export declare class componentregistry implements Disposable {
+    #private;
+    instantiate(name: string, fuelBudget?: number): componentinstance;
+    get(name: string): componentinstance | undefined;
+    [Symbol.dispose](): void;
+}
+/** a pooled memory ticket returned via `using`. */
+export interface poolticket extends Disposable {
+    readonly bytes: ArrayBuffer;
+}
+/**
+ * recycles 64 KiB-paged ArrayBuffers across component activations so
+ * short-lived guests stop pressuring the GC; tickets return to the
+ * pool through `using` declarations.
+ */
+export declare class wasmmempool {
+    #private;
+    acquire(minPages: number): poolticket;
+    get pooled(): number;
+    resetall(): void;
+    [Symbol.dispose](): void;
+}
+/** adapter request plan for a pure-software host. */
+export interface adapterplan {
+    readonly adapterOptions: {
+        readonly forceFallbackAdapter: boolean;
+        readonly powerPreference: 'high-performance';
+    };
+    readonly expectedDriver: 'lavapipe';
+    readonly vulkanVersion: '1.4';
+    readonly icd: string;
+    readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * requests an adapter with forceFallbackAdapter (wgpu 30.x semantics),
+ * which lands on lavapipe in a pure-software host; the environment
+ * uses VK_DRIVER_FILES, the loader knob that replaced the deprecated
+ * VK_ICD_FILENAMES in the 2026 loaders.
+ */
+export declare function forcefallbackadapterplan(icdPath?: string): adapterplan;
+/** one bind group entry of a compute pipeline. */
+export interface gpubinding {
+    readonly name: string;
+    readonly type: 'uniform' | 'storage' | 'read-only-storage';
+    readonly visibility: 'compute';
+}
+/** built compute pipeline descriptor. */
+export interface computepipelinedescriptor {
+    readonly label: string;
+    readonly entryPoint: string;
+    readonly bindings: readonly gpubinding[];
+    readonly workgroup: readonly [number, number, number];
+}
+/**
+ * produces a WebGPU compute pipeline descriptor (bindings, entry
+ * point, workgroup shape) with validation of the 256-invocation
+ * workgroup limit.
+ */
+export declare class computepipelinebuilder {
+    #private;
+    bind(binding: gpubinding): this;
+    workgroupsize(size: [number, number, number]): this;
+    build(label: string, entryPoint?: string): computepipelinedescriptor;
+}
+/** matmul dispatch plan over tiled workgroups. */
+export interface matmulplan {
+    readonly workgroups: readonly [number, number, number];
+    readonly flops: number;
+    readonly estimatedMs: number;
+}
+/**
+ * decomposes a GEMM (m x n by n x k) into dispatchable workgroups and
+ * estimates runtime from a virtual device throughput number.
+ */
+export declare function planmatmul2d(m: number, n: number, k: number, tileX?: number, tileY?: number, virtualGflops?: number): matmulplan;
+/**
+ * content-addressed cache keyed by sha256 of the shader source,
+ * mirroring the on-disk Mesa shader cache semantics
+ * (MESA_SHADER_CACHE_DIR / MESA_SHADER_CACHE_MAX_SIZE).
+ */
+export declare class wgslshadercache {
+    #private;
+    getorcompile(source: string): string;
+    stats(): {
+        entries: number;
+        hits: number;
+    };
+}
+/**
+ * uses the default-on Temporal API of node 26 when present and falls
+ * back to Date arithmetic otherwise; deadlines are stored as ISO
+ * strings, the native currency of Temporal.Instant. a failing task
+ * emits a process warning instead of breaking the loop.
+ */
+export declare class temporalscheduler {
+    #private;
+    schedule(delayMs: number, task: () => void, taskName?: `${string}-${string}-${string}-${string}-${string}`): string;
+    cancel(taskName: string): boolean;
+    /** true when the host exposes the Temporal API (node 26+ default). */
+    static get hastemporal(): boolean;
+    get pending(): readonly string[];
+}
+/**
+ * implements IEEE 754 binary16 conversion so half-precision tensors
+ * work before V8 exposes the typed array natively; the native
+ * Float16Array of node 26 is detected automatically.
+ */
+export declare class float16tensor {
+    #private;
+    private constructor();
+    static fromfloat32array(values: Float32Array): float16tensor;
+    tofloat32array(): Float32Array;
+    get length(): number;
+    get bytes(): number;
+    static get nativesupported(): boolean;
+}
+/** converts an IEEE 754 single-precision value to binary16 bits. */
+export declare function f32tof16(value: number): number;
+/** converts binary16 bits to an IEEE 754 single-precision value. */
+export declare function f16tof32(bits: number): number;
+/**
+ * wraps the V8 Error.isError builtin (node 26) with a structured
+ * fallback, then validates error payloads crossing sandbox boundaries.
+ */
+export declare function iserrorvalue(value: unknown): boolean;
+/** asserts that a value is a real Error inside a boundary context. */
+export declare function asserterrorvalue(value: unknown, context: string): asserts value is Error;
+/**
+ * persistent key-value store over DatabaseSync (node:sqlite, node 26);
+ * degrades to an in-memory map when the module is unavailable so the
+ * same code runs on node 24 LTS and inside restricted runtimes.
+ */
+export declare class sqlitesyncstore implements Disposable {
+    #private;
+    constructor(path?: string);
+    open(): Promise<'sqlite' | 'memory-fallback'>;
+    set(key: string, value: string): void;
+    get(key: string): string | undefined;
+    delete(key: string): void;
+    [Symbol.dispose](): void;
+}
+/** one loader hook, disposable like node 26 registrations. */
+export interface loaderhook {
+    readonly name: string;
+    resolve(specifier: string, parentURL: string | undefined): string;
+    [Symbol.dispose](): void;
+}
+/**
+ * reproduces the node 26 pattern where module.register() hooks are
+ * disposable: disposing the registration unloads the hook. specifiers
+ * resolve through the chain in registration order.
+ */
+export declare class modulehookchain implements Disposable {
+    #private;
+    register(hook: loaderhook): this;
+    resolve(specifier: string, parentURL?: string): string;
+    [Symbol.dispose](): void;
+}
+/** a hook that rewrites specifiers with a prefix, disposable via using. */
+export declare function createprefixhook(prefix: string): loaderhook;
+/** one chrome/perfetto trace event. */
+export interface traceevent {
+    readonly name: string;
+    readonly ph: 'B' | 'E' | 'C' | 'i';
+    readonly ts: number;
+    readonly pid: number;
+    readonly tid: number;
+    readonly args?: Readonly<Record<string, number | string>>;
+}
+/**
+ * emits Perfetto trace packets (JSON tp httpd dialect) for counters,
+ * slices and instant events, matching the Perfetto support shipped in
+ * node 26.7.0.
+ */
+export declare class perfettotracesink {
+    #private;
+    begin(name: string, args?: Record<string, number | string>): void;
+    end(name: string): void;
+    counter(name: string, value: number): void;
+    /** serializes the collected packets in Perfetto JSON trace format. */
+    flush(): string;
+    get eventcount(): number;
+}
+/** one key loader registered with the store. */
+export interface keyloader {
+    readonly name: string;
+    load(keyId: string): Uint8Array | undefined;
+}
+/**
+ * follows the node 26 STORE loaders for private keys: material never
+ * crosses the API boundary directly; callers hold opaque ids and the
+ * store resolves them through registered loaders only when an
+ * operation requires it.
+ */
+export declare class privatekeystore {
+    #private;
+    registerloader(loader: keyloader): this;
+    registerkey(keyId: string, alg: 'ML-DSA-65' | 'Ed25519' | 'ML-KEM-768'): this;
+    /** returns a redacted descriptor; material is never included. */
+    describe(keyId: string): {
+        keyId: string;
+        alg: string;
+        createdAt: string;
+    } | undefined;
+    sign(keyId: string, message: Uint8Array): Uint8Array;
+}
+/** dataloader plan: workers, shm and docker arguments. */
+export interface dataloaderplan {
+    readonly workers: number;
+    readonly shmBytes: number;
+    readonly dockerArgs: readonly string[];
+    readonly pinMemory: boolean;
+}
+/**
+ * sizes /dev/shm and the worker fleet so DataLoader workers never hit
+ * the bus error undersized shm causes; the engine passes --shm-size 2g
+ * by default and grows it from this planner when needed.
+ */
+export declare function plandataloader(opts: {
+    gpus: number;
+    batchSize: number;
+    sampleBytes: number;
+    maxShmBytes?: number;
+}): dataloaderplan;
+/** tf/cuda compatibility verdict with notes. */
+export interface tfcudacheck {
+    readonly compatible: boolean;
+    readonly notes: readonly string[];
+}
+/**
+ * answers whether a tensorflow build runs on a given cuda/driver pair,
+ * including the forward-compatibility packages nvidia ships for
+ * blackwell (sm_120).
+ */
+export declare function checktfcuda(tfVersion: string, cudaVersion: number, arch: string): tfcudacheck;
+/** onnx session options with execution providers and env. */
+export interface onnxsessionoptions {
+    readonly executionProviders: readonly {
+        name: string;
+        options?: Readonly<Record<string, string>>;
+    }[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/**
+ * produces the session options for the WebGPU execution provider,
+ * including the lavapipe fallback path for pure-software hosts.
+ */
+export declare function buildonnxwebgpusession(softwareFallback: boolean): onnxsessionoptions;
+/** llm serving plan: weights, kv cache, throughput. */
+export interface llmplan {
+    readonly weightsGb: number;
+    readonly kvCacheGb: number;
+    readonly totalGb: number;
+    readonly estimatedTokensPerSec: number;
+}
+/**
+ * plans token-generation workloads for vulkan-served models on the
+ * software pipeline: weight footprint by quantization, KV-cache
+ * sizing and a throughput estimate from virtual FLOPS.
+ */
+export declare function planllminference(opts: {
+    paramsBillions: number;
+    quantBytesPerWeight: number;
+    contextTokens: number;
+    layers: number;
+    kvBytesPerTokenPerLayer: number;
+    virtualGflops: number;
+}): llmplan;
+/** headless txt2img pipeline plan. */
+export interface stablediffusionplan {
+    readonly env: Readonly<Record<string, string>>;
+    readonly vramEstimateGb: number;
+    readonly pipeline: 'txt2img';
+}
+/**
+ * configures a text-to-image pipeline that needs no X server: vulkan
+ * runs headless through the WSI headless swapchain and the lavapipe
+ * ICD.
+ */
+export declare function planstablediffusion(opts: {
+    resolution: 512 | 768 | 1024;
+    steps: number;
+}): stablediffusionplan;
+/** one vram allocation request. */
+export interface vramallocation {
+    readonly weightsGb: number;
+    readonly kvCacheGb: number;
+    readonly activationsGb: number;
+    readonly workspaceGb: number;
+}
+/**
+ * accounts for weights, KV cache, activations and workspace against
+ * the spoofed or physical VRAM ceiling, warning before OOM instead of
+ * after.
+ */
+export declare class vrambudgetplanner {
+    #private;
+    constructor(totalGb: number);
+    fits(allocation: vramallocation): {
+        fits: boolean;
+        usedGb: number;
+        freeGb: number;
+        warning?: string;
+    };
+}
+/** verdict of one canary validation run. */
+export interface canaryverdict {
+    readonly component: string;
+    readonly revision: string;
+    readonly passed: boolean;
+    readonly checks: readonly string[];
+    readonly rolledBackTo: string | null;
+}
+/**
+ * validates a new wasm component revision before it replaces the
+ * healthy one: structural validation (magic header, known world hash),
+ * a smoke execution under a fuel budget and epoch deadline, and
+ * automatic rollback to the last healthy revision when any check
+ * fails. the validator is the deployment safety net of the component
+ * registry above.
+ */
+export declare class wasmcanaryvalidator {
+    #private;
+    /** registers the currently healthy revision of a component. */
+    markhealthy(component: string, revision: string, worldHash: string): void;
+    validate(opts: {
+        component: string;
+        revision: string;
+        bytes: Uint8Array;
+        worldHash: string;
+        fuelBudget?: number;
+        smoke?: () => void;
+    }): canaryverdict;
+    healthyrevision(component: string): string | undefined;
+}
+/** one wasi:gfx capability request for a component. */
+export interface wasigfxgrant {
+    readonly component: string;
+    readonly adapter: 'fallback-lavapipe' | 'native';
+    readonly maxTextureDimension2d: number;
+    readonly features: readonly ('shader-f16' | 'timestamp-query' | 'indirect-first-instance')[];
+}
+/** compiled wasi:gfx import plan. */
+export interface wasigfxplan {
+    readonly grants: readonly wasigfxgrant[];
+    readonly runtime: {
+        readonly wgpu: string;
+        readonly witWorld: string;
+        readonly notes: readonly string[];
+    };
+}
+/**
+ * plans the wasi:gfx interface (the WebGPU-in-wasm proposal riding on
+ * wgpu 30.x — "wgpu virt wgpu 30" in the omnihypercore notes): each
+ * component receives a capability grant bound to an adapter choice
+ * (lavapipe fallback for software hosts, native otherwise) and the
+ * feature set compiled into the import namespace wasi:gfx/graphics.
+ */
+export declare function planwasigfx(grants: readonly wasigfxgrant[]): wasigfxplan;
+/** one chat command envelope. */
+export interface chatcommand {
+    readonly command: '/vm' | '/gpu' | '/migrate';
+    readonly action: string;
+    readonly args: Readonly<Record<string, string | number>>;
+    readonly confirmRequired: boolean;
+}
+/** webgpu dashboard specification rendered by the chat frontend. */
+export interface dashboardspec {
+    readonly panels: readonly {
+        kind: 'gauge' | 'chart' | 'tensor';
+        readonly metric: string;
+    }[];
+    readonly renderer: 'webgpu-lavapipe';
+    readonly fpsTarget: number;
+}
+/**
+ * builds ChatOps command envelopes for the infrastructure chat: /vm
+ * create|start|stop, /gpu attach|detach and /migrate begin|cancel;
+ * destructive actions always require confirmation. the companion
+ * dashboard spec renders engine telemetry through WebGPU on the
+ * lavapipe fallback adapter, reusing the compute surface above.
+ */
+export declare class chatopsdashboard {
+    vmcreate(name: string, vcpus: number, ramGb: number): chatcommand;
+    vmstop(name: string): chatcommand;
+    gpuattach(vm: string, gpuId: string, migProfile?: string): chatcommand;
+    migratebegin(vm: string, targetHost: string): chatcommand;
+    /** renders the telemetry dashboard spec for the chat frontend. */
+    dashboardspec(): dashboardspec;
+}
+/** one generated bpf telemetry program. */
+export interface bpfprogram {
+    readonly name: string;
+    readonly section: string;
+    readonly source: string;
+    readonly counters: readonly string[];
+}
+/**
+ * builds eBPF programs that count GPU UAPI activity: DRM ioctl
+ * tracepoints (drm_ioctl enter/exit with the ioctl nr argument) feed
+ * per-file utilization counters, and the vendor UAPI ioctls the engine
+ * spoofs map onto named counters. the programs attach with the libbpf
+ * 1.6.0 toolchain already used by the passage stack in
+ * virtualization.ts (ebpfprogram), so GPU telemetry joins the same
+ * loader.
+ */
+export declare class ebpfgputelemetry {
+    #private;
+    /** registers a vendor UAPI ioctl number under a counter name. */
+    registercounter(name: string, ioctlNr: number): this;
+    /** builds the tracepoint program counting the registered ioctls. */
+    build(): bpfprogram;
+    listcounters(): readonly string[];
+}
+/** prediction for one migration window. */
+export interface dirtyprediction {
+    readonly predictedMb: number;
+    readonly transferMs: number;
+    readonly readyToCutover: boolean;
+}
+/**
+ * predicts the dirty-page volume of the next pre-copy round for AI
+ * workloads (large KV caches, sustained gradient writes): an online
+ * linear model maps [dirtyMb observed, writeRate mbps, elapsedMs] to
+ * the next round's dirty set, with a least-mean-squares update on
+ * every completed round. when the predicted transfer time drops below
+ * the downtime budget, the migration is ready to cutover. the state
+ * machine it feeds lives in virtualization.ts (checkpoint family).
+ */
+export declare class aimigrationpredictor {
+    #private;
+    constructor(budgetMs?: number, bandwidthMbps?: number);
+    /** predicts the next round from the last observation. */
+    predict(observedDirtyMb: number, writeRateMbps: number, elapsedMs: number): dirtyprediction;
+    /** least-mean-squares step after a completed round. */
+    learn(observedDirtyMb: number, actualNextDirtyMb: number, writeRateMbps: number, elapsedMs: number): number;
+    get rounds(): number;
+}
+/** one PartyKit realtime channel contract for the engine dashboard. */
+export interface partykitchannel {
+    readonly appid: string;
+    readonly room: string;
+    readonly protocol: 'wss';
+    readonly url: string;
+    readonly presence: readonly ('join' | 'leave' | 'update')[];
+    readonly heartbeatms: 100;
+    readonly maxconnections: 256;
+}
+/**
+ * builds PartyKit edge-presence realtime channels: one room per
+ * sandbox or GPU monitor, the wss endpoint rooted at the edge host
+ * (never a loopback), presence events join/leave/update and a 100 ms
+ * heartbeat. room names are normalized to lowercase without spaces so
+ * they can travel in URL segments. the builder emits connection
+ * descriptors only; the websocket itself stays with the caller.
+ */
+export declare class partykitchannelbuilder {
+    #private;
+    constructor(host?: string);
+    /** builds one channel for a room such as "sandbox-42-gpu-0". */
+    room(rawroom: string): partykitchannel;
+}
+/** one L3AF 2.1 marketplace application (an xBPF kernel package). */
+export interface l3afapp {
+    readonly name: string;
+    readonly version: '2.1';
+    readonly artifacturl: string;
+    readonly config: Readonly<Record<string, string | number>>;
+    readonly command: 'start' | 'stop' | 'update';
+    readonly monitoringport: number;
+}
+/** l3afd-style config document emitted by the manager. */
+export interface l3afdconfig {
+    readonly ebpftype: 'xdp' | 'tc' | 'kprobe';
+    readonly kernels: readonly l3afapp[];
+}
+/**
+ * manages L3AF 2.1 xBPF marketplace applications: each app is an
+ * eBPF kernel package fetched from a marketplace artifact URL with a
+ * flat config map, started and stopped through l3afd with a per-app
+ * monitoring port. the manager validates names (lowercase, no dots)
+ * and keeps an ordered kernel chain per interface type so the emitted
+ * l3afd config drops straight into /etc/l3af/l3afd.cfg.
+ */
+export declare class l3afappmanager {
+    #private;
+    /** registers one marketplace app for deployment. */
+    deploy(app: Omit<l3afapp, 'version' | 'command'>): l3afapp;
+    /** marks every deployed kernel for stop (chain teardown). */
+    stopall(): readonly l3afapp[];
+    /** emits the l3afd config document for one interface type. */
+    config(ebpftype: l3afdconfig['ebpftype']): l3afdconfig;
+    get count(): number;
+}
+/** one RAPL power domain exposed by the host. */
+export interface raplzone {
+    readonly name: string;
+    readonly package: number;
+    readonly budgetw: number;
+    readonly usedw: number;
+}
+/** one greenhyper placement decision. */
+export interface greenhyperplacement {
+    readonly zone: string;
+    readonly vmwatts: number;
+    readonly raplfile: string;
+    readonly headroomw: number;
+    readonly reason: string;
+}
+/**
+ * greenhyper power governor: binpacks VM placements into RAPL zones
+ * while respecting the package power budget. the governor reads the
+ * intel-rapl constraint files (/sys/class/powercap), picks the zone
+ * with the smallest headroom that still fits the VM (best-fit
+ * decreasing) and lowers the constraint when the fleet is idle. pure
+ * planning: the caller applies the microvolts decision.
+ */
+export declare class greenhyperpowergovernor {
+    #private;
+    constructor(zones: readonly raplzone[]);
+    /** best-fit placement of one VM with a watt draw estimate. */
+    place(vmwatts: number, vmname: string): greenhyperplacement;
+    /** releases the watts of one VM back to the zone pool. */
+    release(zonename: string, vmwatts: number): void;
+    /** fleet idle check: every zone under 10% draw. */
+    idle(): boolean;
+}
+/** one replicated key with its lamport clock. */
+export interface statevectorentry {
+    readonly key: string;
+    readonly value: string;
+    readonly clock: number;
+}
+/** the outcome of a two-round exchange. */
+export interface statevectorroundtrip {
+    readonly round1keys: readonly string[];
+    readonly round2deltas: readonly statevectorentry[];
+    readonly converged: boolean;
+}
+/**
+ * statevector 2-round sync, the CRDT companion of the Automerge/Yjs
+ * rows already absorbed: round 1 exchanges bare state vectors (key to
+ * clock) so each peer learns which keys it is missing or stale on;
+ * round 2 ships only those deltas. concurrent writes win on the higher
+ * lamport clock, ties break lexicographically on the value, so the
+ * merge is commutative, associative and idempotent (convergence holds
+ * without a coordinator).
+ */
+export declare class statevectorsync {
+    #private;
+    /** writes one key and advances its lamport clock. */
+    set(key: string, value: string): statevectorentry;
+    /** bare state vector: key to clock, no payloads. */
+    statevector(): ReadonlyMap<string, number>;
+    /** keys this peer must send to a remote holding the given vector. */
+    diff(remote: ReadonlyMap<string, number>): readonly string[];
+    /** applies remote deltas with last-writer-wins semantics. */
+    merge(deltas: readonly statevectorentry[]): number;
+    /** runs the full two-round exchange against a remote peer. */
+    roundtrip(remote: statevectorsync): statevectorroundtrip;
+    /** full entry snapshot used by the reverse leg of the exchange. */
+    snapshot(): readonly statevectorentry[];
+    get size(): number;
+}
+/** block size of the BitTorrent v2 merkle tree. */
+export declare const bittorrentv2blockbytes = 16384;
+/** one p2p artifact address in both ecosystems. */
+export interface p2partifact {
+    readonly multihashhex: string;
+    readonly cidv1raw: string;
+    readonly bittorrentv2roothex: string;
+    readonly magnet: string;
+    readonly multiaddr: string;
+    readonly pieceleaves: number;
+}
+/**
+ * content addressing across libp2p and BitTorrent v2: the same bytes
+ * are hashed into a sha2-256 multihash (base32 CIDv1 raw for libp2p
+ * /ipfs/ addressing) and into the BitTorrent v2 merkle root built
+ * over 16 KiB block leaves (the v2 spec fixed the leaf size), yielding
+ * the magnet link and a libp2p multiaddr for the seed peer.
+ */
+export declare function p2pcontentaddress(payload: Uint8Array, peerid?: string): p2partifact;
+/** one planned tailnet endpoint. */
+export interface tailnetendpoint {
+    readonly hostname: string;
+    readonly magicdns: string;
+    readonly ip: string;
+    readonly isCgnat: boolean;
+    readonly derpFallback: string;
+    readonly milestones: readonly string[];
+}
+/**
+ * plans tailnet endpoints for engine nodes: every node gets a
+ * CGNAT-range address (100.64.0.0/10), a MagicDNS name, a DERP relay
+ * fallback for the no-direct-path case and the six-mesh-milestone
+ * checklist (subnet routes, acls, derp regions, magicdns, key expiry,
+ * tailscale ssh). the planner rejects addresses outside the CGNAT
+ * range so a tailnet identity can never leak onto public space.
+ */
+export declare class tailscaleendpointplanner {
+    #private;
+    constructor(tailnet?: string, derp?: string);
+    /** plans one endpoint from a CGNAT octet quad. */
+    plan(hostname: string, ip: string): tailnetendpoint;
+    /** checks one ipv4 address against the CGNAT range. */
+    iscgnat(ip: string): boolean;
+}
+/** the six tailscale mesh milestones of the portal sheet. */
+export declare const tailscalemeshmilestones: readonly string[];
+/**
+ * the MAX9 delivery variant of the saddle v5 portal: a hardened
+ * build flavor using zip compression level 9 with a measured 51%
+ * archive ratio, the docker tag :max9, the max9 branch and the
+ * omni-hypercore-v5-FINAL-...-MAX9.zip artifact. the name is NOT an
+ * NVIDIA Maxwell generation despite the gpu-like sound; it is pure
+ * build/delivery branding and is catalogued here as legacy provenance
+ * of the delivery pipeline (374 contexts claim of the portal).
+ */
+export declare const max9buildvariant: {
+    readonly kind: 'build/delivery variant';
+    readonly compressionlevel: 9;
+    readonly measuredratio: '51%';
+    readonly dockertag: ':max9';
+    readonly branch: 'max9';
+    readonly artifact: 'omni-hypercore-v5-FINAL-...-MAX9.zip';
+    readonly note: 'not a GPU generation; legacy portal branding for the level-9 hardened zip';
+};
+/** one roadmap backlog row. */
+export interface roadmapbacklogitem {
+    readonly id: string;
+    readonly title: string;
+    readonly origin: 'future.ts v4';
+}
+/**
+ * the thirteen roadmap backlog items of the v4 future.ts ledger that
+ * no v3 module had absorbed (grep-verified zero matches before this
+ * merge): AMX tile real support, dual-X3D detection, WebTransport
+ * datagram relay, Turborepo remote cache on GHCR, pnpm v9
+ * content-addressable store, QUIC + HTTP/3 control plane, P2P WebRTC
+ * mesh, OPFS browser sandboxes, WebCodecs + WebGPU encode,
+ * SharedArrayBuffer cross-origin isolation, WASM JSPI scheduling,
+ * GHCR gha layer reuse and Nix flakes hermetic builds.
+ */
+export declare const roadmapbacklog: readonly roadmapbacklogitem[];
+/** returns the roadmap backlog size (thirteen items). */
+export declare function backlogCount(): number;
+/** origin of one feature: the v2 future.ts ledger or the v3 additions. */
+export type computefeatureorigin = 'future.ts' | 'omnihypercore-v3' | 'portal-v5' | 'v4fix3';
+/** one ledger row: id, origin, name and export name. */
+export interface computefeaturemeta {
+    readonly id: string;
+    readonly origin: computefeatureorigin;
+    readonly name: string;
+    readonly exportname: string;
+}
+/**
+ * the compute-domain ledger: twenty-five features absorbed from the
+ * removed future.ts (wasm 001-008, webgpu 009-012, node26 013-019,
+ * ai-workloads 045-050) plus five omnihypercore additions. the full
+ * 55-feature redistribution map lives in the worklog (task v3-B1).
+ */
+export declare const computefeatureindex: readonly computefeaturemeta[];
+/** returns the ledger count split by origin. */
+export declare function computefeaturecount(): {
+    total: number;
+    absorbed: number;
+    added: number;
+};
+/** version anchors of the compute domain (worklog v3-VERIFY). */
+export declare const computerversions: {
+    readonly wasmtime: '48.0.0';
+    readonly wasmtimeSupport: 'LTS until 2028-08';
+    readonly wasi: '0.2.8 / 0.3.0';
+    readonly spin: '3.6.0';
+    readonly spinrepo: 'spinframework/spin';
+    readonly wasmcloud: 'latest 2.x';
+    readonly wasmcloudNote: 'release page did not expose the version; left unpinned on purpose';
+    readonly wgpu: '30.x';
+    readonly kernelstable: '7.1.9';
+    readonly kernellongterm: '6.18.45';
+};
+/** one tile partition handed to a guest queue. */
+export interface nputilepartition {
+    readonly guest: string;
+    readonly tiles: number;
+    readonly opspersec: number;
+    readonly kind: 'amxtmul' | 'xdnaaie';
+}
+/** the planned NPU surface: tiles, partitions, flags and loadout math. */
+export interface nputileplan {
+    readonly vendor: 'intel' | 'amd';
+    readonly totaltiles: number;
+    readonly partitions: readonly nputilepartition[];
+    readonly qemuflags: readonly string[];
+    readonly xdnaenv: readonly string[];
+    readonly utilization: number;
+}
+/**
+ * plans Intel AMX and AMD XDNA NPU tile partitioning (ledger F-016):
+ * Intel Sapphire Rapids exposes 8 TMUL tiles (each computing one 16x64
+ * by 64x16 int8/bf16 product per instruction via +amx-tile,+amx-int8,
+ * +amx-bf16 cpu flags), AMD Strix Halo exposes 32 XDNA2 AI-engine tiles
+ * routed through the xdna driver environment. the planner validates
+ * that guest partitions never double-book a tile, computes honest peak
+ * ops per partition and emits the QEMU cpu flags (Intel) or the xdna
+ * device environment (AMD) the guest needs to see the accelerator.
+ */
+export declare function plannputiles(opts: {
+    vendor: 'intel' | 'amd';
+    guests: readonly {
+        guest: string;
+        tiles: number;
+        share?: number;
+    }[];
+}): nputileplan;
+/** one node of the planned Ray + vLLM inference cluster. */
+export interface rayvllmnode {
+    readonly role: 'head' | 'worker';
+    readonly gpus: number;
+    readonly cpus: number;
+    readonly memorygb: number;
+    readonly rayargv: readonly string[];
+    readonly vllmargv: readonly string[];
+}
+/** the distributed inference plan across head and workers. */
+export interface rayvllmplan {
+    readonly model: string;
+    readonly tensorparallel: number;
+    readonly pipelineparallel: number;
+    readonly totalgpus: number;
+    readonly nodes: readonly rayvllmnode[];
+    readonly headaddress: string;
+}
+/**
+ * plans a Ray + vLLM distributed inference cluster (ledger F-061): ray
+ * start argv for head (with the dashboard port and object-store size)
+ * and workers (joining via the head address), vllm serve argv with
+ * tensor/pipeline parallelism derived from the per-node GPU count, fp8
+ * kv-cache, chunked prefill and gpu-memory-utilization budgeting. the
+ * planner validates that tensor parallelism divides every worker GPU
+ * count and that the cluster-wide GPU total matches the shard geometry.
+ */
+export declare function planrayvllmcluster(opts: {
+    model: string;
+    nodes: readonly {
+        role: 'head' | 'worker';
+        gpus: number;
+        cpus: number;
+        memorygb: number;
+    }[];
+    tensorparallel?: number;
+    pipelineparallel?: number;
+}): rayvllmplan;
+/** the generated VirtualMachine CRD plus one sample custom resource. */
+export interface crdmanifestplan {
+    readonly crd: string;
+    readonly sample: string;
+    readonly group: string;
+    readonly version: string;
+    readonly kind: string;
+    readonly shortnames: readonly string[];
+}
+/**
+ * builds the Kubernetes CRD manifest for SADDLE VirtualMachine custom
+ * resources (ledger F-062): a complete apiextensions.k8s.io/v1
+ * CustomResourceDefinition yaml string — group, names with short
+ * aliases, scope, one served/storage version, printer columns and an
+ * OpenAPI v3 schema for the vm spec (cpus, memorymb, gpu profile,
+ * runtime, migration mode) — plus a ready-to-apply sample custom
+ * resource. the string is generated, not fetched, so the engine stays
+ * dependency-free; `kubectl apply -f` is the only external step.
+ */
+export declare function buildvmcrdmanifest(opts?: {
+    group?: string;
+    version?: string;
+    kind?: string;
+}): crdmanifestplan;
+/** one cell of the federated hierarchy with its quota vector. */
+export interface federatedcell {
+    readonly name: string;
+    readonly nodes: number;
+    readonly vcpu: number;
+    readonly vramgb: number;
+    readonly gpus: number;
+}
+/** the federated quota plan for up to 10k nodes. */
+export interface federatedquotaplan {
+    readonly clusters: readonly federatedcell[];
+    readonly cells: readonly federatedcell[];
+    readonly totalnodes: number;
+    readonly totals: {
+        vcpu: number;
+        vramgb: number;
+        gpus: number;
+    };
+    readonly headroom: {
+        vcpu: number;
+        vramgb: number;
+        gpus: number;
+    };
+    readonly placementhints: readonly string[];
+}
+/**
+ * plans federated cluster quotas for global scheduling at 10k-node
+ * scale (ledger F-065): the fleet folds into two levels — clusters
+ * (about 250 nodes each, matching the etcd object budget) and cells
+ * (about 2500 nodes each, one scheduling domain) — the planner
+ * validates node counts, sums the vcpu/vram/gpu vectors, reserves a 10%
+ * headroom per resource for drains and migrations, and emits placement
+ * hints so the global scheduler prefers the cell with the highest
+ * headroom ratio instead of a raw bin-pack.
+ */
+export declare function planfederatedquota(clusters: readonly {
+    name: string;
+    nodes: number;
+    vcpusPerNode: number;
+    vramgbPerNode: number;
+}[], gpusPerCell?: number): federatedquotaplan;
+/** the planned browser-facing WebTransport passage endpoint. */
+export interface webtransportplan {
+    readonly url: string;
+    readonly port: number;
+    readonly datagramflow: 'unreliable' | 'partial-reliable';
+    readonly quicparams: readonly string[];
+    readonly headers: readonly string[];
+    readonly browserapi: readonly string[];
+}
+/**
+ * plans the WebTransport datagram relay endpoint (backlog rb-03): the
+ * browser-facing twin of the QUIC passage gateway. the planner emits the
+ * wt:// (with https fallback) URL, the QUIC transport parameters a
+ * browser requires for datagrams (max_datagram_frame_size, the
+ * datagram receive queue window), the connection headers (including the
+ * COOP/COEP pair cross-origin isolation needs) and the exact
+ * WebTransportBrowser API calls the sandbox tier uses to open a
+ * bidirectional stream plus an unreliable datagram lane.
+ */
+export declare function planwebtransportendpoint(opts?: {
+    host?: string;
+    port?: number;
+    flow?: 'unreliable' | 'partial-reliable';
+}): webtransportplan;
+/** one guest disk image kept inside the browser OPFS bucket. */
+export interface opfsbucket {
+    readonly guest: string;
+    readonly sizemb: number;
+    readonly handle: string;
+    readonly seed: 'empty' | 'alpine' | 'custom';
+}
+/** the OPFS-backed browser sandbox storage plan. */
+export interface opfsstorageplan {
+    readonly root: string;
+    readonly buckets: readonly opfsbucket[];
+    readonly totalsizemb: number;
+    readonly quotamb: number;
+    readonly fits: boolean;
+    readonly browserapi: readonly string[];
+    readonly eviction: readonly string[];
+}
+/**
+ * plans Origin Private File System guest disks (backlog rb-08): each
+ * sandbox gets one OPFS bucket holding its sparse disk image plus a
+ * metadata sidecar; the planner validates sizes against the browser
+ * storage quota (navigator.storage.estimate), lays out the directory
+ * tree, and defines the least-recently-booted eviction order used when a
+ * new bucket would overflow the quota. the browserapi lines are the
+ * exact calls the sandbox tier performs (getDirectory, createSyncAccess
+ * handle, persistence request).
+ */
+export declare function planopfsstorage(guests: readonly {
+    guest: string;
+    sizemb: number;
+    seed?: 'empty' | 'alpine' | 'custom';
+}[], quotamb?: number): opfsstorageplan;
+/** one encode stage of the planned browser pipeline. */
+export interface webcodecsstage {
+    readonly name: 'capture' | 'encode' | 'decode' | 'render';
+    readonly api: string;
+    readonly config: readonly string[];
+}
+/** the WebCodecs + WebGPU hardware-free encode pipeline plan. */
+export interface webcodecspipelineplan {
+    readonly codec: string;
+    readonly width: number;
+    readonly height: number;
+    readonly fps: number;
+    readonly bitratembps: number;
+    readonly gpucanvas: boolean;
+    readonly stages: readonly webcodecsstage[];
+    readonly videoencoderinit: string;
+}
+/**
+ * plans the WebCodecs + WebGPU encode pipeline (backlog rb-09): a
+ * hardware-free encode lane that runs entirely inside the browser tier
+ * over the lavapipe-backed adapter. VideoFrame capture comes from a
+ * WebGPU canvas (or an OffscreenCanvas fallback), the VideoEncoder is
+ * configured with avc1/hevc/vp09/av01 at the requested geometry, and
+ * the decode side feeds a VideoFrameRenderer that draws into the
+ * configured GPU device. the planner validates codec/geometry pairs
+ * against the level tables the encode presets in media.ts already
+ * carry and falls back to vp09 when a codec level cannot carry the
+ * requested framerate.
+ */
+export declare function planwebcodecspipeline(opts?: {
+    codec?: 'avc' | 'hevc' | 'vp9' | 'av1';
+    width?: number;
+    height?: number;
+    fps?: number;
+    gpucanvas?: boolean;
+}): webcodecspipelineplan;
+/**
+ * shape of one streaming layer: a self-contained slice of a workload that
+ * can be loaded, processed and evicted independently. models, datasets
+ * and checkpoints decompose this way (gguf tensors, safetensors shards,
+ * csv/parquet row groups, video segments).
+ */
+export interface streaminglayer {
+    readonly id: string;
+    readonly bytes: number;
+    readonly dependencies: readonly string[];
+}
+/**
+ * plans a streaming execution for a workload larger than any single host:
+ * layers are grouped into batches that fit the execution window (host ram
+ * reserved for the hot set), loaded on demand (mmap semantics: the page
+ * cache pages them in as touched), evicted after the last consumer, so a
+ * 1.5 tb workload runs on an 8 gb host with the disk as the source of
+ * truth. this is the technique production inference engines use for
+ * models bigger than ram - nothing about it touches new hardware.
+ *
+ * @param layers the decomposed workload slices.
+ * @param windowbytes the hot-set budget (defaults to a conservative 4 GiB).
+ * @param eviction 'lru' | 'layerdone' - page cache style or strict.
+ * @returns the ordered execution plan with loads, evictions and peak.
+ */
+export declare function planstreamingexecution(layers: readonly streaminglayer[], windowbytes?: number, eviction?: 'lru' | 'layerdone'): {
+    readonly batches: readonly {
+        readonly load: readonly string[];
+        readonly run: readonly string[];
+        readonly evict: readonly string[];
+        readonly windowpeak: number;
+    }[];
+    readonly totalbytes: number;
+    readonly hostwindow: number;
+    readonly peakhostusage: number;
+    readonly passes: number;
+    readonly summary: string;
+};
+/**
+ * convenience planner for a large model checkpoint: splits the weights
+ * file into virtual layers of a chosen size and plans the streaming run
+ * (the exact pattern an inference engine uses when the model is larger
+ * than ram; mmap + madvise willneed per batch).
+ *
+ * @param totalbytes the checkpoint size.
+ * @param layerbytes the per-layer slice (default 512 MiB).
+ * @param windowbytes the hot-set budget (default 4 GiB).
+ */
+export declare function planmodelstreaming(totalbytes: number, layerbytes?: number, windowbytes?: number): ReturnType<typeof planstreamingexecution>;
+//# sourceMappingURL=compute.d.ts.map