@wenathlan/saddle 2.0.153 → 2.0.155

package/dist/packager/targetcli.js

@@ -1,4 +0,0 @@
-// generated by scripts.buildengine.ts - the thin CLI wrapper that
-// activates the target manifest CLI absorbed into distribution.ts
-// (Section 7); its CLI main runs when argv[1] ends with targetcli.js.
-import "../distribution.js";

package/dist/paths.d.ts

@@ -1,2 +0,0 @@
-/** Builds a public URL without depending on a trailing slash in Vite's base value. */
-export declare function assetpath(relativepath: string): string;

package/dist/paths.js

@@ -1,14 +0,0 @@
-/** Resolves public asset paths for root hosting and repository subpath hosting. */
-const rawbaseurl = import.meta.env.BASE_URL || '/';
-// A relative base ("./") must survive as the relative prefix — folding it into
-// a domain-absolute path ("/./") would resolve against the host root and miss
-// the application subpath on static hosting.
-const baseurl = rawbaseurl === './'
-    ? './'
-    : rawbaseurl === '/'
-        ? '/'
-        : `/${rawbaseurl.replace(/^\/+|\/+$/g, '')}/`;
-/** Builds a public URL without depending on a trailing slash in Vite's base value. */
-export function assetpath(relativepath) {
-    return `${baseurl}${relativepath.replace(/^\/+/, '')}`;
-}

package/dist/performance.d.ts

@@ -1,415 +0,0 @@
-/**
- * performance.ts - Virtual Hardware Engine v5
- *
- * Seven composable optimization layers plus a measurement harness: percentile
- * metrics (p50/p95/p99), regression detection and profile mode. Every layer
- * emits a concrete patch (environment variables, process arguments, docker
- * flags, planned kernel writes) so the same code drives local runs, CI jobs
- * and documentation.
- *
- * Layer index:
- * 1. cpu      - AVX-512 vector width, LP thread saturation, OMP presets
- * 2. gpu      - Rusticl OpenCL 3.1 virtual identity, lavapipe Vulkan 1.4, LP_PERF flags
- * 3. memory   - unlimited swap, 2g shm, overcommit, KSM, 1G huge pages, tmpfs cache
- * 4. microvm  - Firecracker warm pool (3-5ms restores, 150 VMs/s, <5 MiB per VM)
- * 5. tcg      - QEMU 11.1 MTTCG, thread=multi, tb-size 1024, EPYC-v5, nitro accel
- * 6. build    - buildx gha cache (103s to 25s measured), multi-stage, LLVM -O3
- * 7. network  - keepalive, connection pooling, TAP pre-setup
- *
- * Related contexts covered by this file (25):
- * LLVMpipe, Gallivm, AVX-512, MR !17813, LP_MAX_THREADS, MR 31551, OpenMP,
- * Rusticl, OpenCL 3.1, RUSTICL_DEVICE_TYPE, lavapipe, Vulkan 1.4, LP_PERF,
- * Docker memory-swap, ShmSize, vm.overcommit_memory, KSM, huge pages, tmpfs,
- * Firecracker snapshots, QEMU MTTCG, buildx type=gha, LLVM -O3 -flto, undici
- * keepalive, TAP/tun devices.
- *
- * Module rules: no emoji, JSDoc in English, third-person voice, lowercase
- * identifiers, `using`/`satisfies`/`#private` modern TypeScript, node:* imports
- * first, try/catch on every fallible path, no hardcoded localhost endpoints.
- */
-import { EventEmitter } from 'node:events';
-/** Hardware facts a layer tunes against. */
-export interface LayerTarget {
-    readonly cpus: number;
-    readonly memoryGb: number;
-    readonly gpus: number;
-    readonly headless: boolean;
-}
-/** Concrete output of applying one layer to one target. */
-export interface LayerPatch {
-    readonly layer: PerformanceLayerId;
-    readonly env: Readonly<Record<string, string>>;
-    readonly args: readonly string[];
-    readonly dockerArgs: readonly string[];
-    readonly kernelWrites: readonly {
-        path: string;
-        content: string;
-    }[];
-    readonly mounts: readonly string[];
-    readonly notes: readonly string[];
-}
-/**
- * Identifies one of the seven tuning layers (cpu, gpu, memory, microvm,
- * tcg, build, network) addressed by the performance engine.
- */
-export type PerformanceLayerId = 'cpu' | 'gpu' | 'memory' | 'microvm' | 'tcg' | 'build' | 'network';
-/**
- * Contract every tuning layer implements: an id, a human title, the file
- * contexts the layer contributes to and the apply() that turns one target
- * into a concrete patch.
- */
-export interface PerformanceLayer {
-    readonly id: PerformanceLayerId;
-    readonly title: string;
-    readonly contexts: readonly string[];
-    apply(target: LayerTarget): LayerPatch;
-}
-/** Picks an ephemeral port for local listeners; never a hardcoded endpoint. */
-export declare function randomPort(): number;
-/** OMP thread presets the engine validates against (up to the 192c EPYC 9965). */
-export declare const ompPresets: readonly [1, 2, 4, 8, 16, 32, 64, 96, 128, 192];
-/**
- * Picks the largest OMP preset that does not exceed the available CPUs.
- * Presets exist so benchmark grids compare identical thread counts across
- * hosts (1, 2, 4, 8, 16, 32, 64, 96, 128, 192).
- */
-export declare function pickOmpThreads(cpus: number): number;
-/**
- * LLVMpipe rasterization threads: `LP_NUM_THREADS=0` selects every core
- * automatically, capped by the compile-time ceiling LP_MAX_THREADS=32 that
- * Mesa carries since MR 31551.
- */
-export declare function llvmpipeThreads(cpus: number): {
-    envValue: string;
-    effective: number;
-};
-/**
- * Layer 1/7 - CPU.
- * AVX-512 reaches LLVMpipe through Gallivm (MR !17813) with runtime CPU
- * detection; forcing LP_NATIVE_VECTOR_WIDTH=512 keeps the JIT on 512-bit
- * vectors for the whole process lifetime. MESA_NO_ERROR removes per-draw
- * error checks that pure-software rasterization does not need.
- */
-export declare class CpuLayer implements PerformanceLayer {
-    #private;
-    readonly id: 'cpu';
-    readonly title = "CPU vector width and thread saturation";
-    readonly contexts: string[];
-    /** Docs note 128-bit JIT is occasionally faster; this switch supports A/B runs. */
-    setVectorWidth(width: 128 | 256 | 512): this;
-    apply(target: LayerTarget): LayerPatch;
-}
-/** Tuning profile switch for the LP_PERF no-op flags of LLVMpipe. */
-export type LlvmpipePerfProfile = 'balanced' | 'benchmark' | 'no-depth' | 'no-tex';
-/**
- * Layer 2/7 - GPU.
- * Presents the software rasterizer as a real GPU: Rusticl reports
- * CL_DEVICE_TYPE_GPU with OpenCL 3.1 (the Mesa 26.2 level), lavapipe serves
- * Vulkan 1.4, and the Vulkan loader selects the lavapipe ICD through
- * VK_DRIVER_FILES (VK_ICD_FILENAMES is deprecated in 2026 loaders).
- */
-export declare class GpuLayer implements PerformanceLayer {
-    #private;
-    readonly id: 'gpu';
-    readonly title = "Rusticl GPU virtual identity and lavapipe Vulkan 1.4";
-    readonly contexts: string[];
-    setProfile(profile: LlvmpipePerfProfile): this;
-    setIcdPath(path: string): this;
-    apply(target: LayerTarget): LayerPatch;
-}
-/**
- * Plans the vm.overcommit_memory=2 (never overcommit) setting together with
- * the commit floor the engine reserves for guest memory backends.
- */
-export declare function planOvercommit(reserveGb: number): {
-    path: string;
-    content: string;
-    rationale: string;
-};
-/** Plans Kernel Samepage Merging: deduplicates identical guest pages (N:N sandboxes share one kernel image). */
-export declare function planKsm(pagesToScan?: number, sleepMs?: number): {
-    writes: {
-        path: string;
-        content: string;
-    }[];
-    expectedSaving: string;
-};
-/** Plans 1 GiB huge page reservations backing QEMU guest memory. */
-export declare function planHugePages1g(guestGb: number): {
-    writes: {
-        path: string;
-        content: string;
-    }[];
-    bootArgs: string[];
-};
-/** Plans the 20G tmpfs that backs the Mesa shader cache in hot loops. */
-export declare function planShaderTmpfs(sizeGb?: number): {
-    mounts: string[];
-    env: Record<string, string>;
-};
-/**
- * Layer 3/7 - memory.
- * Docker runs with unlimited swap (--memory-swap -1) and 2g of shared memory
- * so PyTorch DataLoaders never bus-error; the kernel side enables strict
- * overcommit accounting, KSM dedup and 1 GiB huge pages, while a 20G tmpfs
- * keeps the shader cache entirely in RAM (tmpfs is up to 4x faster than
- * overlayfs on small files).
- */
-export declare class MemoryLayer implements PerformanceLayer {
-    #private;
-    readonly id: 'memory';
-    readonly title = "unlimited swap, 2g shm, overcommit, KSM, huge pages, tmpfs cache";
-    readonly contexts: string[];
-    setShmSize(size: string): this;
-    apply(target: LayerTarget): LayerPatch;
-}
-/**
- * Layer 4/7 - microVM.
- * Keeps Firecracker microVMs pre-restored from snapshots: acquiring a sandbox
- * costs one restore (3-5ms with File backend, ~1ms more with Uffd), each VM
- * stays under 5 MiB of overhead, and a host sustains roughly 150 microVM
- * creations per second. The pool refills in the background so bursts never
- * hit the cold path.
- */
-export declare class FirecrackerWarmPool extends EventEmitter implements PerformanceLayer, Disposable {
-    #private;
-    readonly id: 'microvm';
-    readonly title = "Firecracker warm pool (3-5ms restores, 150 VMs/s, <5 MiB per VM)";
-    readonly contexts: string[];
-    readonly targetSize: number;
-    constructor(targetSize?: number, restoreMs?: number);
-    get warmCount(): number;
-    get restoreMs(): number;
-    /** Fills the pool up to the target size; returns the number added. */
-    refill(): number;
-    /**
-     * Acquires a warm VM or synthesizes a cold one when the pool is empty.
-     * Cold boots cost ~125ms; warm restores cost the modeled restore time.
-     */
-    acquire(): {
-        vmId: string;
-        apiPort: number;
-        bootMs: number;
-    };
-    /** Sustained creation capacity of one host and the per-VM overhead. */
-    capacity(): {
-        vmsPerSec: number;
-        memoryPerVmMib: number;
-    };
-    apply(target: LayerTarget): LayerPatch;
-    [Symbol.dispose](): void;
-}
-/**
- * Shape of the options accepted by buildQemuTcgArgs: vcpus, memoryMb and
- * the optional machine/cpuModel/tbSizeMiB/kernel/initrd/append overrides.
- */
-export interface TcgOptions {
-    readonly vcpus: number;
-    readonly memoryMb: number;
-    readonly machine?: 'microvm' | 'q35';
-    readonly cpuModel?: string;
-    readonly tbSizeMiB?: number;
-    readonly kernel?: string;
-    readonly initrd?: string;
-    readonly append?: string;
-}
-/**
- * Builds the QEMU 11.1 command line for software virtualization.
- * MTTCG (`thread=multi`) binds one host thread per vCPU (the default when
- * host and guest are both x86_64), tb-size caches translation blocks and
- * EPYC-v5 is the newest AMD server model in target/i386/cpu.c.
- */
-export declare function buildQemuTcgArgs(opts: TcgOptions): string[];
-/**
- * Layer 5/7 - TCG.
- * Used where KVM is unavailable (GitHub-hosted runners expose no /dev/kvm):
- * MTTCG keeps a 1:1 vCPU-to-host-thread mapping, the translation block cache
- * is sized at 1024 MiB for compile-heavy guests, and the microvm machine
- * with a direct -kernel boot trims device enumeration to a minimum. QEMU
- * 11.1 also ships the nitro accelerator for AWS enclave-shaped guests.
- */
-export declare class TcgLayer implements PerformanceLayer {
-    #private;
-    readonly id: 'tcg';
-    readonly title = "QEMU 11.1 MTTCG, tb-size 1024, EPYC-v5, nitro accel";
-    readonly contexts: string[];
-    setTbSizeMiB(mib: number): this;
-    setMachine(machine: 'microvm' | 'q35'): this;
-    apply(target: LayerTarget): LayerPatch;
-}
-/** buildx cache configuration: measured 103s cold down to 25s warm on gha. */
-export declare function buildxCacheConfig(scope: string): {
-    cacheFrom: string;
-    cacheTo: string;
-    measured: {
-        coldSec: number;
-        warmSec: number;
-    };
-};
-/** LLVM maximum-optimization flags for native components (software GPU shims, overlay hooks). */
-export declare function llvmNativeCflags(march?: string): {
-    cflags: string;
-    cxxflags: string;
-    ldflags: string;
-};
-/** Plans a multi-stage Dockerfile stage graph with cache-mount annotations. */
-export declare function planMultiStage(stages: readonly string[]): {
-    dockerfile: string[];
-    cacheMounts: readonly string[];
-};
-/**
- * Layer 6/7 - build.
- * The build layer moves compile time out of the critical path: buildx gha
- * caching took the engine image from 103s cold to 25s warm, multi-stage
- * builds keep the final image at runtime-only layers, and native components
- * compile with LLVM -O3 -march=native -flto against the host ISA.
- */
-export declare class BuildLayer implements PerformanceLayer {
-    #private;
-    readonly id: 'build';
-    readonly title = "buildx gha cache (103s to 25s), multi-stage, LLVM -O3 -march=native -flto";
-    readonly contexts: string[];
-    setScope(scope: string): this;
-    apply(target: LayerTarget): LayerPatch;
-}
-/** undici-style connection pool tuning for the engine control plane. */
-export declare function poolingConfig(cores: number): {
-    keepAliveTimeoutMs: number;
-    keepAliveMaxTimeoutMs: number;
-    connectionsPerOrigin: number;
-    pipelining: number;
-};
-/** Plans TAP device pre-setup so VM boot does not pay interface creation cost. */
-export declare function planTapPreSetup(tapName: string): {
-    commands: string[];
-    savedBootMs: number;
-};
-/**
- * Layer 7 of 7 - network.
- * The control plane keeps HTTP connections alive and pooled (undici Agent
- * semantics: keepAliveTimeout 4s, per-origin connection floors scaled to
- * cores), and TAP devices are created before the VM starts so the boot path
- * skips interface setup entirely.
- */
-export declare class NetworkLayer implements PerformanceLayer {
-    #private;
-    readonly id: 'network';
-    readonly title = "keepalive, connection pooling, TAP pre-setup";
-    readonly contexts: string[];
-    setTapName(name: string): this;
-    apply(target: LayerTarget): LayerPatch;
-}
-/**
- * Composes the seven layers into one target-specific profile. The stack is
- * the single entry point the engine uses to configure a run: it merges
- * environment variables, collects process arguments, docker flags, kernel
- * writes and mounts, and renders a human-readable report.
- */
-export declare class PerformanceStack {
-    #private;
-    add(layer: PerformanceLayer): this;
-    applyAll(target: LayerTarget): LayerPatch[];
-    /** Merges every patch environment into a single flat record. */
-    composeEnv(patches: readonly LayerPatch[]): Record<string, string>;
-    /** Markdown report of what each layer would do for the given target. */
-    report(target: LayerTarget): string;
-}
-/** Stack with all seven layers in canonical order. */
-export declare function createDefaultStack(): PerformanceStack;
-/**
- * Outcome of one benchmark: raw samples plus p50/p95/p99, mean, min, max
- * and stdev, all in milliseconds with three decimal places.
- */
-export interface BenchmarkResult {
-    readonly name: string;
-    readonly iterations: number;
-    readonly samplesMs: readonly number[];
-    readonly p50: number;
-    readonly p95: number;
-    readonly p99: number;
-    readonly mean: number;
-    readonly min: number;
-    readonly max: number;
-    readonly stdev: number;
-}
-/** Computes p50/p95/p99 from an already collected sample set. */
-export declare function percentiles(samples: readonly number[]): {
-    p50: number;
-    p95: number;
-    p99: number;
-};
-/**
- * Benchmark harness with warmup, outlier-free percentile reporting and a
- * post-run GC hint. Each iteration is timed with performance.now().
- */
-export declare class BenchmarkHarness {
-    #private;
-    run(name: string, fn: (iteration: number) => void | Promise<void>, opts?: {
-        iterations?: number;
-        warmup?: number;
-    }): Promise<BenchmarkResult>;
-    summarize(name: string, samplesMs: readonly number[]): BenchmarkResult;
-    result(name: string): BenchmarkResult | undefined;
-    get names(): string[];
-}
-/** Regression verdict scale: ok (within threshold), warn (under 2x), fail (beyond). */
-export type RegressionVerdict = 'ok' | 'warn' | 'fail';
-/**
- * Per-metric comparison produced by RegressionDetector.compare: verdict
- * plus one check row per percentile with baseline, current and delta %.
- */
-export interface RegressionReport {
-    readonly verdict: RegressionVerdict;
-    readonly checks: readonly {
-        metric: 'p50' | 'p95' | 'p99' | 'mean';
-        baseline: number;
-        current: number;
-        deltaPct: number;
-    }[];
-}
-/**
- * Regression detector: compares a current benchmark against a stored
- * baseline and flags any percentile that degraded beyond the threshold
- * (default 10%). Verdicts: ok (all within threshold), warn (regressed but
- * under twice the threshold), fail (at least one metric beyond 2x).
- */
-export declare class RegressionDetector {
-    readonly thresholdPct: number;
-    constructor(thresholdPct?: number);
-    compare(baseline: BenchmarkResult, current: BenchmarkResult): RegressionReport;
-}
-/** One measured profile phase: name, duration in ms and mark count. */
-export interface ProfilePhase {
-    readonly name: string;
-    readonly durationMs: number;
-    readonly marks: number;
-}
-/**
- * Profile mode: wraps named phases with performance.mark/measure pairs and
- * accumulates a phase timeline. The report is plain text so CI logs stay
- * grep-friendly.
- */
-export declare class ProfileMode {
-    #private;
-    setEnabled(enabled: boolean): this;
-    phase<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
-    report(): string;
-    get phases(): readonly ProfilePhase[];
-}
-/**
- * Convenience wrapper: profiles a benchmark scenario across the seven-layer
- * stack, detects regressions against an optional baseline and returns both
- * the patch profile and the measurement in one call.
- */
-export declare function profileScenario(opts: {
-    name: string;
-    target: LayerTarget;
-    fn: (iteration: number) => void | Promise<void>;
-    baseline?: BenchmarkResult;
-    iterations?: number;
-}): Promise<{
-    patches: readonly LayerPatch[];
-    env: Record<string, string>;
-    result: BenchmarkResult;
-    regression: RegressionReport | null;
-}>;