@wenathlan/saddle 2.0.154 → 2.0.155

package/dist/virtualcpu.d.ts

@@ -1,315 +0,0 @@
-/**
- * virtualcpu - virtual processor bank and procfs generators.
- *
- * This module embeds the BEST_VIRTUAL_PROCESSORS bank with real, verified
- * specifications of the strongest server, workstation and desktop processors
- * available on 2026-08-22 (AMD EPYC 9965 Turin, Ryzen 9 9950X3D, Threadripper
- * PRO 9995WX, Threadripper 7980X, Intel Core Ultra 9 285K, AMD EPYC 9955) and
- * converts any of them into byte-accurate procfs texts: generateVirtualCpuinfo
- * renders a complete /proc/cpuinfo payload with vendor identity, family,
- * model, topology, cache sizes and the full Zen 5 flag set (avx512f, avx512bw,
- * avx512cd, avx512dq, avx512vl, avx512_bf16, sha_ni and friends), while
- * generateVirtualLscpu renders the util-linux summary with NUMA ranges and
- * vulnerability lines. The module also owns the cpuRegistry, a fluent
- * virtualcpubuilder, a processor factory, topology solving, capability
- * scoring, the marchFlag/validateCpuCount helpers absorbed from the v2 stub
- * and the boards() socket index.
- *
- * /proc/meminfo generation (generateVirtualMeminfo, meminfoptions and
- * pagealign) moved to virtualmemory.ts in the v2 reorganization so every
- * memory concern lives in one module.
- *
- * Data sources (verified 2026-08-22): amd.com product pages (EPYC 9965,
- * EPYC 9955, Ryzen 9 9950X3D, Threadripper PRO 9995WX), intel.com ARK
- * (Core Ultra 9 285K), techpowerup.com CPU database and the QEMU 11.1.0
- * target/i386 CPU model table (EPYC-v5).
- *
- * Contexts (24): hardwareerror, vendorid, vendorprofile, ZEN5FLAGS,
- * ARROWLAKEFLAGS, vendorprofiles, virtualcpuspec, BEST_VIRTUAL_PROCESSORS,
- * cpuRegistry, solvetopology, generateVirtualCpuinfo, generateVirtualLscpu,
- * virtualcpubuilder, createVirtualProcessor, validateCpuCount, marchFlag,
- * boards, cpuscore, compareVirtualProcessors, listBestVirtualProcessors,
- * serializeprovisionedcpu, modellease, stableModelId, virtualcpudemo.
- *
- * Patterns: registry (cpuRegistry), builder (virtualcpubuilder), factory
- * (createVirtualProcessor), proxy-free disposable lease (modellease).
- * 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.
- */
-/** Error thrown by every hardware subsystem with an optional cause chain. */
-export declare class hardwareerror extends Error {
-    /** Machine readable subsystem tag. */
-    readonly subsystem: string;
-    constructor(message: string, options?: {
-        cause?: Error;
-        subsystem?: string;
-    });
-}
-/** Supported CPU vendors. */
-export type vendorid = 'amd' | 'intel';
-/** Static vendor profile rendered into every cpuinfo block. */
-export type vendorprofile = {
-    readonly vendorid: string;
-    readonly flags: readonly string[];
-    readonly bugs: readonly string[];
-    readonly tlbsize: string | null;
-    readonly cpuidlevel: number;
-    readonly powermanagement: string;
-};
-/**
- * Complete Zen 5 flag set as observed in production /proc/cpuinfo dumps of
- * AMD Turin and Granite Ridge machines. Includes the full AVX-512 family
- * (avx512f, avx512dq, avx512cd, avx512bw, avx512vl, avx512_bf16, avx512vbmi,
- * avx512vbmi2, avx512ifma, avx512vnni, avx512vp2intersect, avx512vpopcntdq,
- * avx512bitalg), the vector crypto extensions (sha_ni, gfni, vaes,
- * vpclmulqdq) and the modern memory extensions (movdiri, movdir64b, fsrm,
- * serialize, cldemote).
- */
-export declare const ZEN5FLAGS: readonly string[];
-/**
- * Arrow Lake flag set for the Core Ultra 9 285K. Arrow Lake ships AVX2 with
- * AVX-VNNI and the SHA extensions but no AVX-512 execution units, and it
- * reports no hyper-threading, so the ht flag is absent on purpose.
- */
-export declare const ARROWLAKEFLAGS: readonly string[];
-/** Vendor strategy table: identity strings and per-vendor cpuinfo details. */
-export declare const vendorprofiles: Readonly<Record<vendorid, vendorprofile>>;
-/** Complete description of one virtual processor model. */
-export type virtualcpuspec = {
-    readonly model: string;
-    readonly displayname: string;
-    readonly vendor: vendorid;
-    readonly cores: number;
-    readonly threads: number;
-    readonly baseclockmhz: number;
-    readonly boostclockmhz: number;
-    readonly allcoreclockmhz: number;
-    readonly l3mb: number;
-    readonly l2mb: number;
-    readonly socket: string;
-    readonly tdpwatts: number;
-    readonly maxtdpwatts: number;
-    readonly pcie: string;
-    readonly maxmemorygb: number;
-    readonly memorytype: string;
-    readonly memorychannels: number;
-    readonly microarch: string;
-    readonly cpufamily: number;
-    readonly cpumodel: number;
-    readonly stepping: number;
-    readonly physicalline: string;
-    readonly virtualline: string;
-    readonly launch: string;
-};
-/**
- * BEST_VIRTUAL_PROCESSORS: the bank of real, verified top-end processors
- * embedded as immutable data. Every entry was cross-checked against vendor
- * pages and the TechPowerUp database on 2026-08-22.
- */
-export declare const BEST_VIRTUAL_PROCESSORS: readonly virtualcpuspec[];
-/**
- * Registry of every known virtual processor. Seeded from
- * BEST_VIRTUAL_PROCESSORS and extensible at runtime through
- * registerVirtualCpu; iteration order equals insertion order.
- */
-export declare const cpuRegistry: ReadonlyMap<string, virtualcpuspec>;
-/** Normalizes a model string for case-insensitive registry lookups. */
-export declare function normalizemodel(model: string): string;
-/**
- * Registers a custom processor spec in the cpuRegistry. Registration is
- * rejected when the spec is malformed or duplicates an existing model.
- */
-export declare function registerVirtualCpu(spec: virtualcpuspec): string;
-/**
- * Looks up a processor by exact (case-insensitive) model name.
- *
- * @param model Model name such as "AMD EPYC 9965".
- */
-export declare function getVirtualCpu(model: string): virtualcpuspec;
-/**
- * Searches the registry by substring, returning every spec whose model name
- * contains the fragment (case-insensitive). The const type parameter keeps
- * literal fragment types intact for logging callers.
- */
-export declare function findVirtualCpus<const T extends string>(fragment: T): virtualcpuspec[];
-/** Lists every registered model name in registry order. */
-export declare function listVirtualCpus(): string[];
-/** Removes a custom model from the registry; returns true when it existed. */
-export declare function removeVirtualCpu(model: string): boolean;
-/** Derives a stable, deterministic identifier for a model name via sha256. */
-export declare function stableModelId(model: string): string;
-/** Resolved package topology for a requested vCPU count. */
-export type topologysolution = {
-    readonly vcpus: number;
-    readonly threadspercore: number;
-    readonly coresonline: number;
-    readonly siblings: number;
-    readonly sockets: number;
-    readonly fullypopulated: boolean;
-};
-/**
- * Solves the package topology for a requested vCPU count against a spec.
- * Symmetric multithreading parts round core counts up so partial
- * configurations stay coherent, and heterogeneous parts (Arrow Lake)
- * report one thread per core.
- */
-export declare function solvetopology(spec: virtualcpuspec, vcpus: number): topologysolution;
-/** Optional overrides accepted by generateVirtualCpuinfo. */
-export type cpuinfoptions = {
-    readonly family?: number;
-    readonly modelnumber?: number;
-    readonly stepping?: number;
-    readonly microcode?: string;
-    readonly maxmhz?: number;
-    readonly minmhz?: number;
-    readonly extraflags?: readonly string[];
-};
-/**
- * Generates a complete, byte-realistic /proc/cpuinfo text for a registered
- * processor model with an arbitrary vCPU count. Each logical processor block
- * carries processor index, vendor_id (AuthenticAMD or GenuineIntel), cpu
- * family, model, model name, stepping, microcode, cpu MHz with natural
- * jitter, cache size, physical id, siblings, core id, cpu cores, apicid,
- * initial apicid, fpu markers, cpuid level, wp, the full vendor flag set,
- * known bug list, bogomips, TLB size, clflush size, cache alignment,
- * address sizes and the power management hint line.
- *
- * @param model Processor model name present in the cpuRegistry.
- * @param vcpus Number of logical processors to render (1 to model threads).
- * @param options Optional family, model, stepping, microcode and flag tweaks.
- */
-export declare function generateVirtualCpuinfo(model: string, vcpus: number, options?: cpuinfoptions): string;
-/**
- * Generates an lscpu-style summary block for a registered model, covering
- * architecture, endianness, address sizes, vendor, family, model, per-core
- * threading, socket topology, frequency range, caches and NUMA nodes. The
- * text mirrors the column layout produced by util-linux lscpu on 2026
- * distributions.
- */
-export declare function generateVirtualLscpu(model: string, vcpus: number, numanodes?: number): string;
-/** A fully provisioned virtual processor ready for spoofing. */
-export type provisionedcpu = {
-    readonly id: string;
-    readonly spec: virtualcpuspec;
-    readonly vcpus: number;
-    readonly topology: topologysolution;
-    readonly cpuinfotext: string;
-    readonly lscputext: string;
-    readonly createdat: number;
-};
-/**
- * Fluent builder for virtual processors. The builder starts empty, collects
- * every field through chainable with* methods, validates the result and
- * produces a provisionedcpu that bundles the spec, the solved topology and
- * the generated cpuinfo and lscpu texts.
- */
-export declare class virtualcpubuilder {
-    #private;
-    constructor();
-    /** Sets the model name; when present in the registry it seeds defaults. */
-    withmodel(model: string): this;
-    /** Sets the number of online vCPUs. */
-    withvcpus(vcpus: number): this;
-    /** Sets base, single-core boost and all-core boost clocks in MHz. */
-    withclocks(base: number, boost: number, allcore: number): this;
-    /** Sets L3 and L2 cache sizes in MB. */
-    withcache(l3mb: number, l2mb: number): this;
-    /** Sets package, socket, TDP and PCIe lanes. */
-    withpackage(socket: string, tdpwatts: number, maxtdpwatts: number, pcie: string): this;
-    /** Sets maximum memory, memory type and channel count. */
-    withmemory(maxmemorygb: number, memorytype: string, memorychannels: number): this;
-    /** Sets core and thread counts plus the vendor identity. */
-    withtopology(cores: number, threads: number, vendor: vendorid): this;
-    /** Sets CPUID family, model and stepping. */
-    withcpuid(cpufamily: number, cpumodel: number, stepping: number): this;
-    /** Sets the number of NUMA nodes advertised in lscpu output. */
-    withnumanodes(numanodes: number): this;
-    /** Validates the accumulated spec and produces the provisioned bundle. */
-    build(): provisionedcpu;
-}
-/**
- * Factory that provisions a registered processor model for spoofing. The
- * factory resolves the spec from the cpuRegistry, solves the topology for
- * the requested vCPU count and bundles the generated cpuinfo and lscpu
- * texts into a frozen provisionedcpu record.
- *
- * @param model Exact model name in the registry.
- * @param vcpus Number of online vCPUs (1 to the model thread count).
- */
-export declare function createVirtualProcessor(model: string, vcpus: number): provisionedcpu;
-/**
- * Hard vCPU bounds of the virtualcpu module. The ceiling of 192 matches the
- * strongest bank part (EPYC 9965, 192 cores) and the memory limits published
- * by virtualmemory.ts.
- */
-export declare const cpucountlimits: {
-    readonly min: 1;
-    readonly max: 192;
-};
-/**
- * Validates a vCPU count against the 1 to 192 modularity range. The check is
- * pure: it returns true when the count is an integer inside the bounds.
- */
-export declare function validateCpuCount(n: number): boolean;
-/**
- * Reference gcc march tuning string for Zen 5 targets: znver4 codegen with
- * native tuning, LTO, the AVX-512 foundation plus byte/word lanes and the
- * 512-bit preferred vector width that matches ZEN5FLAGS. This is the only
- * occurrence of the flag string in the whole pool, confirmed by grep on the
- * 2026-08-22 merge pass.
- */
-export declare function marchFlag(): string;
-/**
- * Socket families advertised by the bank, in the order the v4 helper
- * documented them: SP5 LGA6096 (EPYC), TR5 (Threadripper) and AM5
- * (Ryzen). The helper derives the live list from the cpuRegistry so custom
- * registrations extend it automatically; the canonical trio is returned as
- * the fallback whenever the registry carries no socket data.
- */
-export declare function boards(): readonly string[];
-/** Weights applied by cpuscore; larger specs always score higher. */
-export declare const cpuscoreweights: {
-    readonly core: 10;
-    readonly thread: 4;
-    readonly l3mb: 0.5;
-    readonly boostmhz: 1.5;
-    readonly memorychannels: 8;
-    readonly tdpwatts: 0.2;
-};
-/**
- * Computes a scalar capability score for a processor spec. The score blends
- * core count, thread count, L3 capacity, boost clock, memory channels and
- * sustainable power, which produces a stable ordering of the bank.
- */
-export declare function cpuscore(spec: virtualcpuspec): number;
-/** Compares two specs by capability score, descending. */
-export declare function compareVirtualProcessors(a: virtualcpuspec, b: virtualcpuspec): number;
-/** Returns the bank sorted by capability score, strongest first. */
-export declare function listBestVirtualProcessors(): virtualcpuspec[];
-/** Serializes a provisioned processor to a JSON-safe object. */
-export declare function serializeprovisionedcpu(provisioned: provisionedcpu): Record<string, unknown>;
-/**
- * Lease over a runtime-registered custom model. The lease removes the model
- * from the cpuRegistry when disposed through a `using` declaration, which
- * keeps speculative registrations from polluting the global bank.
- */
-export declare class modellease {
-    #private;
-    readonly model: string;
-    readonly spec: virtualcpuspec;
-    constructor(spec: virtualcpuspec);
-    /** True while the leased model is still registered. */
-    get active(): boolean;
-    /** Releases the lease, removing the model from the registry. */
-    release(): void;
-    /** Synchronous disposer so leases compose with `using` declarations. */
-    [Symbol.dispose](): void;
-}
-/**
- * End-to-end demo of the virtualcpu pipeline: provisions the EPYC 9965 at a
- * random vCPU count, registers a leased custom model through a `using`
- * declaration and returns the serialized summary plus the first cpuinfo
- * block for eyeball verification.
- */
-export declare function virtualcpudemo(): Record<string, unknown>;