@wenathlan/saddle 2.0.154 → 2.0.159

package/dist/render.d.ts

@@ -1,380 +0,0 @@
-/**
- * render.ts — software rendering stack and gpu identity spoofing for the
- * virtual hardware engine.
- *
- * the module pins the 100% software graphics pipeline verified against
- * primary sources on 2026-08-22:
- * - mesa 26.2.1 stable (released 2026-08-20) with the 26.3-devel mainline
- *   open since 2026-07-15; llvm 22.1.8 (2026-07-10) is the reference
- *   compiler backend and mesa 26.2 is already llvm-22 ready
- * - llvmpipe: opengl 4.6 core profile 100% (161/161 extensions tracked by
- *   mesamatrix), opengl es 3.2 100%, avx-512 selected at runtime by gallivm
- *   (mesa mr !17813), rasterizer thread ceiling lp_max_threads = 32 (mr
- *   31551 raised the previous 16; docs state "up to 32 at this time")
- * - lavapipe: vulkan 1.4 surface since mesa 25.1, khronos-conformant on the
- *   vulkan 1.3 cts (submission 2022-07-19); icd manifest
- *   /usr/share/vulkan/icd.d/lvp_icd.x86_64.json selected through
- *   vk_driver_files (vk_icd_filenames is deprecated by the vulkan loader)
- * - rusticl: opencl 3.1 with same-day spec support in mesa 26.2; sole mesa
- *   opencl frontend since clover was deleted in mesa 25.2; cl_khr_fp16 is
- *   default since mesa 25.2 so only fp64 still needs rusticl_features
- * - xvfb headless glx recipe (man xvfb(1)):
- *   "xvfb :99 -ac -screen 0 1920x1080x24 -nolisten tcp +extension glx
- *    +render -noreset"
- *
- * contexts (25): versioncatalog, llvmpipefacts, cpucapsdomain, lpperfdomain,
- * lavapipefacts, rusticlfacts, xvfbrecipe, gpuspoofdata, pciid, gpuregistry,
- * gpuprofilebuilder, mesaenvbuilder, renderenv, threadadvisor, smiformat,
- * smiadapter, rendertargets, rendererbase, llvmpiperenderer, lavapiperenderer,
- * rusticlrenderer, xvfbdisplay, rendererfactory, rendererproxy, renderprobe
- *
- * patterns: builder (mesaenvbuilder, gpuprofilebuilder), registry
- * (gpuregistry), factory (rendererfactory), proxy (rendererproxy).
- * rules: lowercase identifiers, english jsdoc, third person, no emoji,
- * try/catch catcher on every fallible path, node:* built-ins only, and no
- * hardcoded localhost address anywhere.
- *
- * domain split (v2): this module keeps the software identity stack — mesa
- * environment builders, llvmpipe/lavapipe/rusticl renderers, xvfb and the
- * virtual nvidia-smi adapter renderer. the physical gpu side (vfio passthrough, vgpu
- * slicing, MIG layouts, the verified gpu bank) lives in virtualgpu.ts, and
- * the paravirtual virtio-gpu venus path (`-device virtio-gpu-pci,venus=true`
- * with `hostmem=8g`, or `virtio-gpu-gl blob=on venus=on`) is emitted by the
- * virtualization module that owns the QEMU command line.
- */
-import type { ChildProcess } from 'node:child_process';
-/** stack pinned from primary sources (mesa3d.org, llvm releases, docs.nvidia.com). */
-declare const mesastack: {
-    mesa: string;
-    mesadevel: string;
-    llvm: string;
-    gl: string;
-    gles: string;
-    vulkan: string;
-    opencl: string;
-    smidriver: string;
-    cudaversion: string;
-};
-declare const llvmpipe: {
-    glcoreprofile: string;
-    glcoreextensions: string;
-    glesprofile: string;
-    glesextensions: string;
-    avx512: string;
-    threadceiling: number;
-    threadnote: string;
-};
-/** valid values for gallium_override_cpu_caps (docs.mesa3d.org/envvars).
- * no avx2/avx512 value exists: avx-512 is detected at runtime by gallivm. */
-declare const cpucapsdomain: readonly ['nosse', 'sse', 'sse2', 'sse3', 'ssse3', 'sse4.1', 'avx'];
-type cpucaps = (typeof cpucapsdomain)[number];
-/** valid stages for lp_perf selective no-ops (docs: "see the source code"). */
-declare const lpperfdomain: readonly ['no_blend', 'no_depth', 'no_alphatest', 'no_tex', 'no_linear', 'no_mipmaps', 'no_mip_linear', 'tex_mem'];
-type lpperfstage = (typeof lpperfdomain)[number];
-declare const lavapipe: {
-    vulkan: string;
-    conformance: string;
-    icdmanifest: string;
-    icdenv: string;
-    deprecatedicdenv: string;
-    extensions: string;
-};
-declare const rusticl: {
-    opencl: string;
-    clovernote: string;
-    fp16note: string;
-    features: string;
-    devicetype: string;
-};
-/** default xvfb geometry documented in the project research. */
-declare const defaultgeometry = "1920x1080x24";
-/** builds the validated headless glx argv for xvfb (man xvfb(1)). */
-declare function xvfbargs(display: string, geometry: string): readonly string[];
-/** picks a random x display number in the 90-99 range; the documented
- * example uses :99, so the random pick avoids colliding with it. */
-declare function randomdisplay(): string;
-/** gpu identity used for spoofing; every field comes from vendor pages,
- * techpowerup and the pci id databases confirmed in the project research.
- * physical passthrough identities live in virtualgpu.ts; this table only
- * feeds the software identity stack (the smi adapter and friends). */
-interface gpuspoof {
-    readonly name: string;
-    readonly vendor: 'nvidia' | 'amd';
-    readonly pcivendor: string;
-    readonly pcidevice: string;
-    readonly vrammib: number;
-    readonly memtype: string;
-    readonly bandwidthgbs: number;
-    readonly tdpw: number;
-    readonly arch: string;
-    readonly driver: string;
-    readonly cuda: string | null;
-}
-declare const gpuspoofdata: {
-    rtx5090: {
-        name: string;
-        vendor: "nvidia";
-        pcivendor: string;
-        pcidevice: string;
-        vrammib: number;
-        memtype: string;
-        bandwidthgbs: number;
-        tdpw: number;
-        arch: string;
-        driver: string;
-        cuda: string;
-    };
-    rtxpro6000: {
-        name: string;
-        vendor: "nvidia";
-        pcivendor: string;
-        pcidevice: string;
-        vrammib: number;
-        memtype: string;
-        bandwidthgbs: number;
-        tdpw: number;
-        arch: string;
-        driver: string;
-        cuda: string;
-    };
-    b200: {
-        name: string;
-        vendor: "nvidia";
-        pcivendor: string;
-        pcidevice: string;
-        vrammib: number;
-        memtype: string;
-        bandwidthgbs: number;
-        tdpw: number;
-        arch: string;
-        driver: string;
-        cuda: string;
-    };
-    rx9070xt: {
-        name: string;
-        vendor: "amd";
-        pcivendor: string;
-        pcidevice: string;
-        vrammib: number;
-        memtype: string;
-        bandwidthgbs: number;
-        tdpw: number;
-        arch: string;
-        driver: string;
-        cuda: any;
-    };
-    mi350x: {
-        name: string;
-        vendor: "amd";
-        pcivendor: string;
-        pcidevice: string;
-        vrammib: number;
-        memtype: string;
-        bandwidthgbs: number;
-        tdpw: number;
-        arch: string;
-        driver: string;
-        cuda: any;
-    };
-};
-/** renders the canonical "vendor:device" pci id of a virtual identity profile. */
-declare function pciid(profile: gpuspoof): string;
-/** registry of named gpu profiles; the whole engine resolves virtual identity
- * identities exclusively through this registry. */
-declare class gpuregistry {
-    #private;
-    /** registers a profile under a name; returns the registry for chaining. */
-    register(name: string, profile: gpuspoof): this;
-    /** lists every registered profile name. */
-    names(): readonly string[];
-    /** resolves a profile or undefined when absent. */
-    get(name: string): gpuspoof | undefined;
-    /** resolves a profile or throws with the list of known names. */
-    require(name: string): gpuspoof;
-}
-/** default registry seeded with the five verified gpu identities. */
-declare const defaultgpuregistry: gpuregistry;
-/** fluent builder for custom virtual identity profiles; defaults mirror the rtx 5090. */
-declare class gpuprofilebuilder {
-    #private;
-    withname(name: string): this;
-    withvendor(vendor: gpuspoof['vendor']): this;
-    withpcidevice(device: string): this;
-    withvram(mib: number): this;
-    withmemtype(memtype: string): this;
-    withbandwidth(gbs: number): this;
-    withtdp(w: number): this;
-    witharch(arch: string): this;
-    withdriver(driver: string, cuda: string | null): this;
-    /** validates the profile shape and freezes it into a gpuspoof. */
-    build(): gpuspoof;
-}
-/** fluent builder that assembles the complete validated mesa environment;
- * every variable below is documented at docs.mesa3d.org/envvars.html. */
-declare class mesaenvbuilder {
-    #private;
-    /** forces the software path: llvmpipe through the gallium loader. */
-    software(): this;
-    /** spoofs glgetstring(gl_version); 4.6 is the llvmpipe maximum. */
-    glversion(version?: string): this;
-    /** spoofs gl_shading_language_version (460 matches gl 4.6). */
-    glslversion(version?: string): this;
-    /** spoofs the gles version reported by the software driver. */
-    glesversion(version?: string): this;
-    /** spoofs the vulkan apiversion; cannot exceed the driver instance version. */
-    vulkanversion(version?: string): this;
-    /** sets lp_num_threads; 0 lets llvmpipe use every core up to the
-     * lp_max_threads=32 ceiling, 1..32 pins an explicit thread count. */
-    threads(count?: number): this;
-    /** sets lp_native_vector_width; 512 exercises the avx-512 paths even
-     * though gallivm picks avx-512 automatically at runtime. */
-    vectorwidth(width: 128 | 256 | 512): this;
-    /** overrides reported cpu caps; avx is the highest documented value
-     * (there is no avx2/avx512 entry in the envvars documentation). */
-    cpucaps(caps: cpucaps): this;
-    /** adds one lp_perf selective no-op stage (benchmarking aid). */
-    perf(stage: lpperfstage): this;
-    /** disables gl error checking (gl_khr_no_error) to cut cpu overhead. */
-    noerror(enabled?: boolean): this;
-    /** pins lavapipe through vk_driver_files and enables the headless wsi
-     * swapchain; vk_icd_filenames is deprecated and never emitted. */
-    lavapipe(icd?: string): this;
-    /** enables rusticl on llvmpipe with the gpu device type virtual identity, opencl
-     * 3.1 and the fp64 feature (fp16 is default since mesa 25.2). */
-    rusticl(): this;
-    /** escape hatch for extra variables; caller keeps full choice. */
-    set(key: string, value: string): this;
-    /** freezes the environment into a plain record (lp_perf joined last). */
-    build(): Record<string, string>;
-}
-/** render target selector used by the factory and the presets. */
-type rendertarget = 'opengl' | 'gles' | 'vulkan' | 'opencl' | 'xvfb';
-/** one-call environment assembly per render target. */
-declare function renderenv(target: rendertarget): Record<string, string>;
-/** advisory thread count: one rasterizer thread per host core bounded by
- * the compile-time lp_max_threads=32 ceiling. */
-declare function advisethreads(hostcores?: number): number;
-/** process row of the nvidia-smi processes table. */
-interface smiprocess {
-    readonly gpu: number;
-    readonly gi: number;
-    readonly ci: number;
-    readonly pid: number;
-    readonly type: 'C' | 'G' | 'C+G';
-    readonly name: string;
-    readonly memorymib: number;
-}
-/** builds a full virtual nvidia-smi adapter report; the header pins driver
- * 575.57.08 and cuda 12.9 exactly as verified in the project research.
- * notes: perf states span p0-p12, compute modes are default or exclusive
- * process, mig is reported as n/a when disabled and fan speed may legally
- * exceed 100% per the nvidia-smi documentation. */
-declare class smiadapterbuilder {
-    #private;
-    constructor(profile: gpuspoof, index?: number);
-    withmemused(mib: number): this;
-    withutil(percent: number): this;
-    withtemperature(celsius: number): this;
-    withfanspeed(percent: number): this;
-    withpower(watts: number): this;
-    withecc(text: string): this;
-    withcomputemode(mode: 'Default' | 'Exclusive Process'): this;
-    withprocess(entry: smiprocess): this;
-    /** renders the complete report; the summary table is exactly 89 chars. */
-    build(): string;
-}
-/** result of a completed child process. */
-interface runresult {
-    readonly code: number;
-    readonly stdout: string;
-    readonly stderr: string;
-}
-/** runs a command to completion under a merged environment; every spawn
- * path is wrapped in a try/catch catcher for later tracing. */
-declare function run(command: string, args: readonly string[], env?: Record<string, string>): Promise<runresult>;
-/** shared renderer state: environment, optional child process and a
- * trace buffer used as the embedded debugger for later tracing. */
-declare abstract class rendererbase {
-    #private;
-    protected constructor(label: string, vars: Record<string, string>);
-    get label(): string;
-    /** environment copy for the render target. */
-    get env(): Record<string, string>;
-    /** whether the owned helper process is alive. */
-    get running(): boolean;
-    /** accumulated trace entries (error catcher output). */
-    get traces(): readonly string[];
-    /** records a trace entry; never throws. */
-    protected note(message: string): void;
-    /** spawns a long-lived helper under the renderer environment. */
-    protected launch(command: string, args: readonly string[]): ChildProcess;
-    /** verifies the virtualized context with the target-specific info tool. */
-    abstract verify(): Promise<string>;
-    /** terminates the helper; escalates to SIGKILL after a grace period. */
-    stop(): Promise<void>;
-    /** `using` disposal hook: stops the helper without awaiting. */
-    [Symbol.dispose](): void;
-}
-/** options for the xvfb headless display server. */
-interface xvfboptions {
-    readonly display?: string;
-    readonly geometry?: string;
-    readonly env?: Record<string, string>;
-}
-/** headless glx display server; the child is terminated on dispose. */
-declare class xvfbdisplay extends rendererbase {
-    #private;
-    constructor(options?: xvfboptions);
-    /** display number without the leading colon (for example "94"). */
-    get displaynumber(): string;
-    /** geometry string in the widthxheightxdepth form. */
-    get geometry(): string;
-    /** boots xvfb and waits for the socket grace period. */
-    start(): Promise<void>;
-    /** reports the served display. */
-    verify(): Promise<string>;
-}
-/** creates concrete renderers per target; the preset environment can be
- * overridden per call (user choice), for example to merge an xvfb display. */
-declare class rendererfactory {
-    #private;
-    constructor();
-    /** registers a custom builder for a target (extensibility hook). */
-    register(target: rendertarget, builder: (env?: Record<string, string>) => rendererbase): this;
-    /** instantiates the renderer for a target. */
-    create(target: rendertarget, env?: Record<string, string>): rendererbase;
-}
-/** proxy that guards the renderer environment, keeps an audit trail and
- * delegates lifecycle calls to the wrapped renderer. */
-declare class rendererproxy {
-    #private;
-    constructor(inner: rendererbase, frozen?: readonly string[]);
-    get label(): string;
-    /** environment copy; reads are recorded in the audit trail. */
-    get env(): Record<string, string>;
-    /** accumulated audit entries. */
-    get audit(): readonly string[];
-    /** merges overrides over the renderer environment while refusing to
-     * clobber the frozen virtual identity keys; returns the merged copy. */
-    patchenv(overrides: Record<string, string>): Record<string, string>;
-    /** delegates verification. */
-    verify(): Promise<string>;
-    /** delegates disposal. */
-    [Symbol.dispose](): void;
-}
-/** probe report across the three software apis. */
-interface probereport {
-    readonly opengl: string;
-    readonly vulkan: string;
-    readonly opencl: string;
-    readonly notes: readonly string[];
-}
-/** probes glxinfo, vulkaninfo and clinfo under the given environment and
- * parses the virtualized version strings; failures degrade into notes. */
-declare function renderprobe(env: Record<string, string>): Promise<probereport>;
-/** boots xvfb, assembles the full software environment (opengl + vulkan +
- * opencl presets) and probes all three apis; every resource is released
- * through the `using` disposal at scope exit. */
-export declare function renderdemo(profilename?: string): Promise<probereport>;
-export type { cpucaps, gpuspoof, lpperfstage, probereport, rendertarget, runresult, smiprocess, xvfboptions, };
-export { advisethreads, cpucapsdomain, defaultgeometry, defaultgpuregistry, gpuprofilebuilder, gpuregistry, gpuspoofdata, lavapipe, llvmpipe, mesaenvbuilder, mesastack, pciid, randomdisplay, renderenv, rendererfactory, rendererproxy, renderprobe, run, rusticl, smiadapterbuilder, xvfbargs, xvfbdisplay, };