@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/virtualcpu.js

@@ -0,0 +1,1180 @@
+/**
+ * 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.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { createHash, randomInt } from 'node:crypto';
+/* ------------------------------------------------------------------ */
+/* Section 1: errors                                                   */
+/* ------------------------------------------------------------------ */
+/** Error thrown by every hardware subsystem with an optional cause chain. */
+export class hardwareerror extends Error {
+    /** Machine readable subsystem tag. */
+    subsystem;
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'hardwareerror';
+        this.subsystem = options?.subsystem ?? 'virtualcpu';
+    }
+}
+/**
+ * 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 const ZEN5FLAGS = [
+    'fpu',
+    'vme',
+    'de',
+    'pse',
+    'tsc',
+    'msr',
+    'pae',
+    'mce',
+    'cx8',
+    'apic',
+    'sep',
+    'mtrr',
+    'pge',
+    'mca',
+    'cmov',
+    'pat',
+    'pse36',
+    'clflush',
+    'mmx',
+    'fxsr',
+    'sse',
+    'sse2',
+    'ht',
+    'syscall',
+    'nx',
+    'mmxext',
+    'fxsr_opt',
+    'pdpe1gb',
+    'rdtscp',
+    'lm',
+    'constant_tsc',
+    'rep_good',
+    'amd_lbr_v2',
+    'nopl',
+    'nonstop_tsc',
+    'cpuid',
+    'extd_apicid',
+    'aperfmperf',
+    'rapl',
+    'pni',
+    'pclmulqdq',
+    'monitor',
+    'ssse3',
+    'fma',
+    'cx16',
+    'sse4_1',
+    'sse4_2',
+    'x2apic',
+    'movbe',
+    'popcnt',
+    'aes',
+    'xsave',
+    'avx',
+    'f16c',
+    'rdrand',
+    'lahf_lm',
+    'cmp_legacy',
+    'svm',
+    'extapic',
+    'cr8_legacy',
+    'abm',
+    'sse4a',
+    'misalignsse',
+    '3dnowprefetch',
+    'osvw',
+    'ibs',
+    'skinit',
+    'wdt',
+    'tce',
+    'topoext',
+    'perfctr_core',
+    'perfctr_nb',
+    'bpext',
+    'perfctr_llc',
+    'mwaitx',
+    'cpb',
+    'cat_l3',
+    'cdp_l3',
+    'hw_pstate',
+    'ssbd',
+    'mba',
+    'perfmon_v2',
+    'ibrs',
+    'ibpb',
+    'stibp',
+    'vmmcall',
+    'fsgsbase',
+    'bmi1',
+    'avx2',
+    'smep',
+    'bmi2',
+    'erms',
+    'invpcid',
+    'cqm',
+    'rdt_a',
+    'avx512f',
+    'avx512dq',
+    'rdseed',
+    'adx',
+    'smap',
+    'clflushopt',
+    'clwb',
+    'avx512vl',
+    'avx512bw',
+    'avx512cd',
+    'avx512_bf16',
+    'avx512vbmi',
+    'avx512vbmi2',
+    'avx512ifma',
+    'avx512vp2intersect',
+    'sha_ni',
+    'gfni',
+    'vaes',
+    'vpclmulqdq',
+    'avx512vpopcntdq',
+    'avx512vnni',
+    'avx512bitalg',
+    'rdpid',
+    'movdiri',
+    'movdir64b',
+    'fsrm',
+    'cldemote',
+    'serialize',
+    'flush_l1d',
+    'arch_capabilities',
+];
+/**
+ * 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 const ARROWLAKEFLAGS = [
+    'fpu',
+    'vme',
+    'de',
+    'pse',
+    'tsc',
+    'msr',
+    'pae',
+    'mce',
+    'cx8',
+    'apic',
+    'sep',
+    'mtrr',
+    'pge',
+    'mca',
+    'cmov',
+    'pat',
+    'pse36',
+    'clflush',
+    'mmx',
+    'fxsr',
+    'sse',
+    'sse2',
+    'syscall',
+    'nx',
+    'pdpe1gb',
+    'rdtscp',
+    'lm',
+    'constant_tsc',
+    'arch_perfmon',
+    'rep_good',
+    'nopl',
+    'xtopology',
+    'nonstop_tsc',
+    'cpuid',
+    'aperfmperf',
+    'tsc_known_freq',
+    'pni',
+    'pclmulqdq',
+    'monitor',
+    'ssse3',
+    'fma',
+    'cx16',
+    'sse4_1',
+    'sse4_2',
+    'x2apic',
+    'movbe',
+    'popcnt',
+    'aes',
+    'xsave',
+    'avx',
+    'f16c',
+    'rdrand',
+    'lahf_lm',
+    'abm',
+    '3dnowprefetch',
+    'cpuid_fault',
+    'epb',
+    'invpcid_single',
+    'ssbd',
+    'ibrs',
+    'ibpb',
+    'stibp',
+    'ibrs_enhanced',
+    'tpr_shadow',
+    'vnmi',
+    'flexpriority',
+    'ept',
+    'vpid',
+    'ept_ad',
+    'fsgsbase',
+    'tsc_adjust',
+    'bmi1',
+    'avx2',
+    'smep',
+    'bmi2',
+    'erms',
+    'invpcid',
+    'rdseed',
+    'adx',
+    'smap',
+    'clflushopt',
+    'clwb',
+    'sha_ni',
+    'xsaveopt',
+    'xsavec',
+    'xgetbv1',
+    'xsaves',
+    'split_lock_detect',
+    'user_shstk',
+    'avx_vnni',
+    'waitpkg',
+    'gfni',
+    'vaes',
+    'vpclmulqdq',
+    'rdpid',
+    'movdiri',
+    'movdir64b',
+    'fsrm',
+    'md_clear',
+    'serialize',
+    'tsxldtrk',
+    'la57',
+    'cldemote',
+    'arch_capabilities',
+];
+/** Vendor strategy table: identity strings and per-vendor cpuinfo details. */
+export const vendorprofiles = {
+    amd: {
+        vendorid: 'AuthenticAMD',
+        flags: ZEN5FLAGS,
+        bugs: ['sysret_ss_attrs', 'spectre_v1', 'spectre_v2', 'spec_store_bypass', 'srso'],
+        tlbsize: '3584 2M/4M pages',
+        cpuidlevel: 16,
+        powermanagement: 'ts ttp tm hwpstate cpb eff_freq_ro [13] [14]',
+    },
+    intel: {
+        vendorid: 'GenuineIntel',
+        flags: ARROWLAKEFLAGS,
+        bugs: ['spectre_v1', 'spectre_v2', 'spec_store_bypass', 'swapgs', 'eibrs_pbrsb'],
+        tlbsize: null,
+        cpuidlevel: 32,
+        powermanagement: 'ts ttp tm hwpstate cpb eff_freq_ro [8] [9] [10] [11] [12] [13] [14]',
+    },
+};
+/**
+ * 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 const BEST_VIRTUAL_PROCESSORS = [
+    {
+        model: 'AMD EPYC 9965',
+        displayname: 'AMD EPYC 9965 192-Core Processor',
+        vendor: 'amd',
+        cores: 192,
+        threads: 384,
+        baseclockmhz: 2250,
+        boostclockmhz: 3700,
+        allcoreclockmhz: 3350,
+        l3mb: 384,
+        l2mb: 192,
+        socket: 'SP5 (LGA6096)',
+        tdpwatts: 500,
+        maxtdpwatts: 500,
+        pcie: 'PCIe 5.0 x128',
+        maxmemorygb: 6144,
+        memorytype: 'DDR5-6400 ECC RDIMM',
+        memorychannels: 12,
+        microarch: 'Zen 5c (Turin)',
+        cpufamily: 25,
+        cpumodel: 17,
+        stepping: 2,
+        physicalline: '52 bits physical',
+        virtualline: '57 bits virtual',
+        launch: '2024-10-10',
+    },
+    {
+        model: 'AMD Ryzen 9 9950X3D',
+        displayname: 'AMD Ryzen 9 9950X3D 16-Core Processor',
+        vendor: 'amd',
+        cores: 16,
+        threads: 32,
+        baseclockmhz: 4300,
+        boostclockmhz: 5700,
+        allcoreclockmhz: 5400,
+        l3mb: 128,
+        l2mb: 16,
+        socket: 'AM5',
+        tdpwatts: 170,
+        maxtdpwatts: 200,
+        pcie: 'PCIe 5.0 x24',
+        maxmemorygb: 192,
+        memorytype: 'DDR5-5600',
+        memorychannels: 2,
+        microarch: 'Zen 5 X3D (3D V-Cache on one CCD, 144 MB total cache with L2)',
+        cpufamily: 25,
+        cpumodel: 17,
+        stepping: 2,
+        physicalline: '48 bits physical',
+        virtualline: '57 bits virtual',
+        launch: '2025-03-12',
+    },
+    {
+        model: 'AMD Threadripper PRO 9995WX',
+        displayname: 'AMD Ryzen Threadripper PRO 9995WX 96-Core Processor',
+        vendor: 'amd',
+        cores: 96,
+        threads: 192,
+        baseclockmhz: 2500,
+        boostclockmhz: 5400,
+        allcoreclockmhz: 4100,
+        l3mb: 384,
+        l2mb: 96,
+        socket: 'sTR5 (LGA4844)',
+        tdpwatts: 350,
+        maxtdpwatts: 350,
+        pcie: 'PCIe 5.0 x128',
+        maxmemorygb: 2048,
+        memorytype: 'DDR5-6400 ECC RDIMM',
+        memorychannels: 8,
+        microarch: 'Zen 5 (Shimada Peak, WRX90)',
+        cpufamily: 25,
+        cpumodel: 17,
+        stepping: 2,
+        physicalline: '52 bits physical',
+        virtualline: '57 bits virtual',
+        launch: '2025-07',
+    },
+    {
+        model: 'AMD Threadripper 7980X',
+        displayname: 'AMD Ryzen Threadripper 7980X 64-Core Processor',
+        vendor: 'amd',
+        cores: 64,
+        threads: 128,
+        baseclockmhz: 3200,
+        boostclockmhz: 5100,
+        allcoreclockmhz: 4400,
+        l3mb: 256,
+        l2mb: 64,
+        socket: 'sTR5',
+        tdpwatts: 350,
+        maxtdpwatts: 350,
+        pcie: 'PCIe 5.0 x48',
+        maxmemorygb: 1024,
+        memorytype: 'DDR5-6400',
+        memorychannels: 4,
+        microarch: 'Zen 5 (TRX50)',
+        cpufamily: 25,
+        cpumodel: 17,
+        stepping: 2,
+        physicalline: '52 bits physical',
+        virtualline: '57 bits virtual',
+        launch: '2023-10',
+    },
+    {
+        model: 'Intel Core Ultra 9 285K',
+        displayname: 'Intel(R) Core(TM) Ultra 9 285K',
+        vendor: 'intel',
+        cores: 24,
+        threads: 24,
+        baseclockmhz: 3700,
+        boostclockmhz: 5700,
+        allcoreclockmhz: 5400,
+        l3mb: 36,
+        l2mb: 36,
+        socket: 'LGA1851',
+        tdpwatts: 125,
+        maxtdpwatts: 250,
+        pcie: 'PCIe 5.0 x20 + PCIe 4.0 x4',
+        maxmemorygb: 192,
+        memorytype: 'DDR5-6400',
+        memorychannels: 2,
+        microarch: 'Arrow Lake (8 Performance + 16 Efficient cores, no hyper-threading)',
+        cpufamily: 6,
+        cpumodel: 191,
+        stepping: 2,
+        physicalline: '46 bits physical',
+        virtualline: '57 bits virtual',
+        launch: '2024-10-24',
+    },
+    {
+        model: 'AMD EPYC 9955',
+        displayname: 'AMD EPYC 9955 128-Core Processor',
+        vendor: 'amd',
+        cores: 128,
+        threads: 256,
+        baseclockmhz: 2600,
+        boostclockmhz: 3750,
+        allcoreclockmhz: 3450,
+        l3mb: 384,
+        l2mb: 128,
+        socket: 'SP5',
+        tdpwatts: 400,
+        maxtdpwatts: 400,
+        pcie: 'PCIe 5.0 x128',
+        maxmemorygb: 6144,
+        memorytype: 'DDR5-6400 ECC RDIMM',
+        memorychannels: 12,
+        microarch: 'Zen 5c (Turin dense)',
+        cpufamily: 25,
+        cpumodel: 17,
+        stepping: 2,
+        physicalline: '52 bits physical',
+        virtualline: '57 bits virtual',
+        launch: '2024-10-10',
+    },
+];
+/* ------------------------------------------------------------------ */
+/* Section 4: cpuRegistry                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Registry of every known virtual processor. Seeded from
+ * BEST_VIRTUAL_PROCESSORS and extensible at runtime through
+ * registerVirtualCpu; iteration order equals insertion order.
+ */
+export const cpuRegistry = new Map(BEST_VIRTUAL_PROCESSORS.map((spec) => [spec.model.toLowerCase(), spec]));
+/** Normalizes a model string for case-insensitive registry lookups. */
+export function normalizemodel(model) {
+    return model.trim().toLowerCase();
+}
+/**
+ * Registers a custom processor spec in the cpuRegistry. Registration is
+ * rejected when the spec is malformed or duplicates an existing model.
+ */
+export function registerVirtualCpu(spec) {
+    try {
+        const key = normalizemodel(spec.model);
+        if (key.length === 0) {
+            throw new hardwareerror('model name must not be empty');
+        }
+        if (cpuRegistry.has(key)) {
+            throw new hardwareerror(`model ${spec.model} is already registered`);
+        }
+        cpuRegistry.set(key, spec);
+        return key;
+    }
+    catch (cause) {
+        if (cause instanceof hardwareerror) {
+            throw cause;
+        }
+        throw new hardwareerror('registerVirtualCpu failed', { cause: cause });
+    }
+}
+/**
+ * Looks up a processor by exact (case-insensitive) model name.
+ *
+ * @param model Model name such as "AMD EPYC 9965".
+ */
+export function getVirtualCpu(model) {
+    const found = cpuRegistry.get(normalizemodel(model));
+    if (found === undefined) {
+        throw new hardwareerror(`unknown processor model "${model}"; known models: ${listVirtualCpus().join(', ')}`);
+    }
+    return found;
+}
+/**
+ * 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 function findVirtualCpus(fragment) {
+    const needle = normalizemodel(fragment);
+    const results = [];
+    for (const spec of cpuRegistry.values()) {
+        if (normalizemodel(spec.model).includes(needle)) {
+            results.push(spec);
+        }
+    }
+    return results;
+}
+/** Lists every registered model name in registry order. */
+export function listVirtualCpus() {
+    return [...cpuRegistry.values()].map((spec) => spec.model);
+}
+/** Removes a custom model from the registry; returns true when it existed. */
+export function removeVirtualCpu(model) {
+    return cpuRegistry.delete(normalizemodel(model));
+}
+/** Derives a stable, deterministic identifier for a model name via sha256. */
+export function stableModelId(model) {
+    return createHash('sha256').update(`virtualengine:${model}`).digest('hex').slice(0, 12);
+}
+/**
+ * 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 function solvetopology(spec, vcpus) {
+    try {
+        const threadspercore = Math.max(1, Math.round(spec.threads / spec.cores));
+        if (!Number.isInteger(vcpus) || vcpus < 1) {
+            throw new hardwareerror(`vcpus must be a positive integer, received ${vcpus}`);
+        }
+        if (vcpus > spec.threads) {
+            throw new hardwareerror(`model ${spec.model} exposes at most ${spec.threads} threads; ${vcpus} were requested`);
+        }
+        const coresonline = Math.ceil(vcpus / threadspercore);
+        return {
+            vcpus,
+            threadspercore,
+            coresonline,
+            siblings: vcpus,
+            sockets: 1,
+            fullypopulated: vcpus === spec.threads,
+        };
+    }
+    catch (cause) {
+        if (cause instanceof hardwareerror) {
+            throw cause;
+        }
+        throw new hardwareerror('solvetopology failed', { cause: cause });
+    }
+}
+/** Renders one scalar cpuinfo line with the per-key tab alignment the kernel uses. */
+const keytabs = {
+    processor: '\t',
+    vendor_id: '\t',
+    'cpu family': '\t',
+    model: '\t\t',
+    'model name': '\t',
+    stepping: '\t',
+    microcode: '\t',
+    'cpu MHz': '\t\t',
+    'cache size': '\t',
+    'physical id': '\t',
+    siblings: '\t',
+    'core id': '\t\t',
+    'cpu cores': '\t',
+    apicid: '\t\t',
+    'initial apicid': '\t',
+    fpu: '\t\t',
+    fpu_exception: '\t',
+    'cpuid level': '\t',
+    wp: '\t\t',
+    flags: '\t\t',
+    bugs: '\t\t',
+    bogomips: '\t',
+    'TLB size': '\t',
+    'clflush size': '\t',
+    cache_alignment: '',
+    'address sizes': '\t',
+    'power management': '',
+};
+/** Renders one cpuinfo line exactly as procfs does: key, tabs, colon, value. */
+function line(key, value) {
+    const tabs = keytabs[key] ?? '\t';
+    return `${key}${tabs}: ${value}`;
+}
+/**
+ * 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 function generateVirtualCpuinfo(model, vcpus, options) {
+    try {
+        const spec = getVirtualCpu(model);
+        const topology = solvetopology(spec, vcpus);
+        const profile = vendorprofiles[spec.vendor];
+        const family = options?.family ?? spec.cpufamily;
+        const modelnumber = options?.modelnumber ?? spec.cpumodel;
+        const stepping = options?.stepping ?? spec.stepping;
+        const microcode = options?.microcode ?? '0xffffffff';
+        const flags = [...profile.flags, ...(options?.extraflags ?? [])].join(' ');
+        const bugs = profile.bugs.join(' ');
+        const maxmhz = options?.maxmhz ?? spec.boostclockmhz;
+        const minmhz = options?.minmhz ?? spec.baseclockmhz;
+        const blocks = [];
+        for (let processor = 0; processor < topology.vcpus; processor += 1) {
+            const currentmhz = randomInt(Math.round(minmhz), Math.round(maxmhz + 1));
+            const bogomips = (spec.baseclockmhz * 2 + randomInt(-40, 41) / 100).toFixed(2);
+            const coreid = Math.floor(processor / topology.threadspercore);
+            const lines = [
+                line('processor', processor),
+                line('vendor_id', profile.vendorid),
+                line('cpu family', family),
+                line('model', modelnumber),
+                line('model name', spec.displayname),
+                line('stepping', stepping),
+                line('microcode', microcode),
+                line('cpu MHz', currentmhz.toFixed(3)),
+                line('cache size', `${spec.l3mb} MB`),
+                line('physical id', 0),
+                line('siblings', topology.siblings),
+                line('core id', coreid),
+                line('cpu cores', topology.coresonline),
+                line('apicid', processor),
+                line('initial apicid', processor),
+                line('fpu', 'yes'),
+                line('fpu_exception', 'yes'),
+                line('cpuid level', profile.cpuidlevel),
+                line('wp', 'yes'),
+                line('flags', flags),
+                line('bugs', bugs),
+                line('bogomips', bogomips),
+            ];
+            if (profile.tlbsize !== null) {
+                lines.push(line('TLB size', profile.tlbsize));
+            }
+            lines.push(line('clflush size', 64), line('cache_alignment', 64), line('address sizes', `${spec.physicalline}, ${spec.virtualline}`), line('power management', profile.powermanagement));
+            blocks.push(lines.join('\n'));
+        }
+        return blocks.join('\n\n');
+    }
+    catch (cause) {
+        if (cause instanceof hardwareerror) {
+            throw cause;
+        }
+        throw new hardwareerror('generateVirtualCpuinfo failed', { cause: cause });
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Section 7: lscpu summary generation                                 */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 function generateVirtualLscpu(model, vcpus, numanodes = 1) {
+    try {
+        const spec = getVirtualCpu(model);
+        const topology = solvetopology(spec, vcpus);
+        const corespersocket = Math.ceil(topology.coresonline / numanodes) * numanodes;
+        const rows = [
+            ['Architecture:', 'x86_64'],
+            ['CPU op-mode(s):', '32-bit, 64-bit'],
+            ['Byte Order:', 'Little Endian'],
+            ['Address sizes:', `${spec.physicalline}, ${spec.virtualline}`],
+            ['CPU(s):', String(topology.vcpus)],
+            ['On-line CPU(s) list:', topology.vcpus === 1 ? '0' : `0-${topology.vcpus - 1}`],
+            ['Vendor ID:', vendorprofiles[spec.vendor].vendorid],
+            ['Model name:', spec.displayname],
+            ['CPU family:', String(spec.cpufamily)],
+            ['Model:', String(spec.cpumodel)],
+            ['Thread(s) per core:', String(topology.threadspercore)],
+            ['Core(s) per socket:', String(corespersocket)],
+            ['Socket(s):', '1'],
+            ['Stepping:', String(spec.stepping)],
+            ['Frequency boost:', 'enabled'],
+            ['CPU max MHz:', `${spec.boostclockmhz}.0000`],
+            ['CPU min MHz:', `${(spec.baseclockmhz * 0.62).toFixed(4)}`],
+            ['BogoMIPS:', `${(spec.baseclockmhz * 2).toFixed(2)}`],
+            [
+                'L1d cache:',
+                `${Math.round((spec.l2mb / spec.cores) * 1024)} KiB (${spec.cores} instances)`,
+            ],
+            ['L2 cache:', `${spec.l2mb} MiB (${spec.cores} instances)`],
+            ['L3 cache:', `${spec.l3mb} MiB (${Math.max(1, Math.round(spec.cores / 8))} instances)`],
+            ['NUMA node(s):', String(numanodes)],
+        ];
+        const pernode = Math.ceil(topology.vcpus / numanodes);
+        for (let node = 0; node < numanodes; node += 1) {
+            const start = node * pernode;
+            const end = Math.min(start + pernode, topology.vcpus) - 1;
+            rows.push([`NUMA node${node} CPU(s):`, start === end ? String(start) : `${start}-${end}`]);
+        }
+        rows.push(['Vulnerability Itlb multihit:', 'Not affected']);
+        rows.push([
+            'Vulnerability L1tf:',
+            vendorprofiles[spec.vendor].bugs.includes('l1tf') ? 'Mitigation; VMX flush' : 'Not affected',
+        ]);
+        rows.push(['Vulnerability Mds:', 'Not affected']);
+        rows.push(['Vulnerability Meltdown:', 'Not affected']);
+        rows.push([
+            'Vulnerability Spectre v1:',
+            'Mitigation; usercopy/swapgs barriers and __user pointer sanitization',
+        ]);
+        rows.push([
+            'Vulnerability Spectre v2:',
+            spec.vendor === 'amd' ? 'Mitigation; Retpolines, IBPB' : 'Mitigation; Enhanced IBRS',
+        ]);
+        return rows.map(([key, value]) => `${key.padEnd(28)}${value}`).join('\n');
+    }
+    catch (cause) {
+        if (cause instanceof hardwareerror) {
+            throw cause;
+        }
+        throw new hardwareerror('generateVirtualLscpu failed', { cause: cause });
+    }
+}
+/**
+ * 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 class virtualcpubuilder {
+    #spec;
+    #vcpus;
+    #numanodes;
+    constructor() {
+        this.#spec = {};
+        this.#vcpus = 1;
+        this.#numanodes = 1;
+    }
+    /** Sets the model name; when present in the registry it seeds defaults. */
+    withmodel(model) {
+        this.#spec.model = model;
+        const known = cpuRegistry.get(normalizemodel(model));
+        if (known !== undefined) {
+            this.#spec = { ...known };
+        }
+        return this;
+    }
+    /** Sets the number of online vCPUs. */
+    withvcpus(vcpus) {
+        this.#vcpus = vcpus;
+        return this;
+    }
+    /** Sets base, single-core boost and all-core boost clocks in MHz. */
+    withclocks(base, boost, allcore) {
+        this.#spec.baseclockmhz = base;
+        this.#spec.boostclockmhz = boost;
+        this.#spec.allcoreclockmhz = allcore;
+        return this;
+    }
+    /** Sets L3 and L2 cache sizes in MB. */
+    withcache(l3mb, l2mb) {
+        this.#spec.l3mb = l3mb;
+        this.#spec.l2mb = l2mb;
+        return this;
+    }
+    /** Sets package, socket, TDP and PCIe lanes. */
+    withpackage(socket, tdpwatts, maxtdpwatts, pcie) {
+        this.#spec.socket = socket;
+        this.#spec.tdpwatts = tdpwatts;
+        this.#spec.maxtdpwatts = maxtdpwatts;
+        this.#spec.pcie = pcie;
+        return this;
+    }
+    /** Sets maximum memory, memory type and channel count. */
+    withmemory(maxmemorygb, memorytype, memorychannels) {
+        this.#spec.maxmemorygb = maxmemorygb;
+        this.#spec.memorytype = memorytype;
+        this.#spec.memorychannels = memorychannels;
+        return this;
+    }
+    /** Sets core and thread counts plus the vendor identity. */
+    withtopology(cores, threads, vendor) {
+        this.#spec.cores = cores;
+        this.#spec.threads = threads;
+        this.#spec.vendor = vendor;
+        return this;
+    }
+    /** Sets CPUID family, model and stepping. */
+    withcpuid(cpufamily, cpumodel, stepping) {
+        this.#spec.cpufamily = cpufamily;
+        this.#spec.cpumodel = cpumodel;
+        this.#spec.stepping = stepping;
+        return this;
+    }
+    /** Sets the number of NUMA nodes advertised in lscpu output. */
+    withnumanodes(numanodes) {
+        this.#numanodes = Math.max(1, numanodes);
+        return this;
+    }
+    /** Validates the accumulated spec and produces the provisioned bundle. */
+    build() {
+        try {
+            const defaults = {
+                model: 'custom virtual processor',
+                displayname: 'custom virtual processor',
+                vendor: 'amd',
+                cores: 8,
+                threads: 16,
+                baseclockmhz: 3200,
+                boostclockmhz: 5200,
+                allcoreclockmhz: 4600,
+                l3mb: 64,
+                l2mb: 8,
+                socket: 'virtual',
+                tdpwatts: 120,
+                maxtdpwatts: 160,
+                pcie: 'PCIe 5.0 x16',
+                maxmemorygb: 128,
+                memorytype: 'DDR5-5600',
+                memorychannels: 2,
+                microarch: 'virtual',
+                cpufamily: 25,
+                cpumodel: 17,
+                stepping: 1,
+                physicalline: '48 bits physical',
+                virtualline: '57 bits virtual',
+                launch: '2026-08-22',
+            };
+            const spec = {
+                ...defaults,
+                ...this.#spec,
+                model: this.#spec.model ?? defaults.model,
+            };
+            if (!cpuRegistry.has(normalizemodel(spec.model))) {
+                registerVirtualCpu(spec);
+            }
+            const topology = solvetopology(spec, this.#vcpus);
+            return Object.freeze({
+                id: stableModelId(spec.model),
+                spec: Object.freeze(spec),
+                vcpus: topology.vcpus,
+                topology: Object.freeze(topology),
+                cpuinfotext: generateVirtualCpuinfo(spec.model, topology.vcpus),
+                lscputext: generateVirtualLscpu(spec.model, topology.vcpus, this.#numanodes),
+                createdat: Date.now(),
+            });
+        }
+        catch (cause) {
+            throw new hardwareerror('virtualcpubuilder.build failed', { cause: cause });
+        }
+    }
+}
+/**
+ * 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 function createVirtualProcessor(model, vcpus) {
+    try {
+        return new virtualcpubuilder().withmodel(model).withvcpus(vcpus).build();
+    }
+    catch (cause) {
+        if (cause instanceof hardwareerror) {
+            throw cause;
+        }
+        throw new hardwareerror('createVirtualProcessor failed', { cause: cause });
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Section 9: stub helpers absorbed in v2 (validateCpuCount, marchFlag) */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 const cpucountlimits = {
+    min: 1,
+    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 function validateCpuCount(n) {
+    try {
+        return Number.isInteger(n) && n >= cpucountlimits.min && n <= cpucountlimits.max;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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 function marchFlag() {
+    return '-march=znver4 -mtune=native -O3 -flto -mavx512f -mavx512bw -mprefer-vector-width=512';
+}
+/* ------------------------------------------------------------------ */
+/* Section 10: boards (socket index of the bank)                       */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 function boards() {
+    try {
+        const sockets = [];
+        for (const spec of cpuRegistry.values()) {
+            const socket = spec.socket.split(' ')[0];
+            if (socket.length > 0 && !sockets.includes(socket)) {
+                sockets.push(socket);
+            }
+        }
+        if (sockets.length === 0) {
+            return ['SP5', 'TR5', 'AM5'];
+        }
+        return sockets;
+    }
+    catch {
+        return ['SP5', 'TR5', 'AM5'];
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Section 11: capability scoring                                      */
+/* ------------------------------------------------------------------ */
+/** Weights applied by cpuscore; larger specs always score higher. */
+export const cpuscoreweights = {
+    core: 10,
+    thread: 4,
+    l3mb: 0.5,
+    boostmhz: 1.5,
+    memorychannels: 8,
+    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 function cpuscore(spec) {
+    const score = spec.cores * cpuscoreweights.core +
+        spec.threads * cpuscoreweights.thread +
+        spec.l3mb * cpuscoreweights.l3mb +
+        spec.boostclockmhz * cpuscoreweights.boostmhz +
+        spec.memorychannels * cpuscoreweights.memorychannels +
+        spec.tdpwatts * cpuscoreweights.tdpwatts;
+    return Number(score.toFixed(2));
+}
+/** Compares two specs by capability score, descending. */
+export function compareVirtualProcessors(a, b) {
+    return cpuscore(b) - cpuscore(a);
+}
+/** Returns the bank sorted by capability score, strongest first. */
+export function listBestVirtualProcessors() {
+    return [...cpuRegistry.values()].sort(compareVirtualProcessors);
+}
+/** Serializes a provisioned processor to a JSON-safe object. */
+export function serializeprovisionedcpu(provisioned) {
+    try {
+        return {
+            id: provisioned.id,
+            model: provisioned.spec.model,
+            vendor: provisioned.spec.vendor,
+            vcpus: provisioned.vcpus,
+            coresonline: provisioned.topology.coresonline,
+            threadspercore: provisioned.topology.threadspercore,
+            score: cpuscore(provisioned.spec),
+            createdat: provisioned.createdat,
+        };
+    }
+    catch (cause) {
+        throw new hardwareerror('serializeprovisionedcpu failed', { cause: cause });
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Section 12: disposable registry lease and demo                       */
+/* ------------------------------------------------------------------ */
+/**
+ * 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 class modellease {
+    model;
+    spec;
+    #released;
+    constructor(spec) {
+        this.model = spec.model;
+        this.spec = spec;
+        this.#released = false;
+        registerVirtualCpu(spec);
+    }
+    /** True while the leased model is still registered. */
+    get active() {
+        return !this.#released;
+    }
+    /** Releases the lease, removing the model from the registry. */
+    release() {
+        if (!this.#released) {
+            removeVirtualCpu(this.model);
+            this.#released = true;
+        }
+    }
+    /** Synchronous disposer so leases compose with `using` declarations. */
+    [Symbol.dispose]() {
+        try {
+            this.release();
+        }
+        catch {
+            /* double release is a no-op by construction */
+        }
+    }
+}
+/**
+ * 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 function virtualcpudemo() {
+    try {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const leased = __addDisposableResource(env_1, new modellease({
+                model: 'virtual engineering sample',
+                displayname: 'Virtual Engineering Sample 32-Core Processor',
+                vendor: 'amd',
+                cores: 32,
+                threads: 64,
+                baseclockmhz: 3000,
+                boostclockmhz: 5000,
+                allcoreclockmhz: 4300,
+                l3mb: 128,
+                l2mb: 32,
+                socket: 'virtual',
+                tdpwatts: 180,
+                maxtdpwatts: 220,
+                pcie: 'PCIe 5.0 x32',
+                maxmemorygb: 512,
+                memorytype: 'DDR5-5600',
+                memorychannels: 4,
+                microarch: 'virtual',
+                cpufamily: 25,
+                cpumodel: 17,
+                stepping: 1,
+                physicalline: '48 bits physical',
+                virtualline: '57 bits virtual',
+                launch: '2026-08-22',
+            }), false);
+            const vcpus = randomInt(8, 65);
+            const provisioned = createVirtualProcessor('AMD EPYC 9965', vcpus);
+            return {
+                leasedmodel: leased.model,
+                leasedactive: leased.active,
+                summary: serializeprovisionedcpu(provisioned),
+                march: marchFlag(),
+                cpuinfohead: provisioned.cpuinfotext.split('\n').slice(0, 5).join('\n'),
+            };
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    catch (cause) {
+        throw new hardwareerror('virtualcpudemo failed', { cause: cause });
+    }
+}
+//# sourceMappingURL=virtualcpu.js.map