@wenathlan/saddle 2.0.151 → 2.0.152

package/dist/render.d.ts

@@ -0,0 +1,380 @@
+/**
+ * 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, };