@wenathlan/saddle 2.0.153 → 2.0.155

package/dist/sandbox.js

@@ -1,1721 +0,0 @@
-/**
- * sandbox.ts — browser-pure port of the saddle virtual hardware engine.
- *
- * this module is a lightweight rewrite of the engine generators
- * (virtualcpu.ts, virtualmemory.ts, virtualgpu.ts and render.ts) that runs
- * unchanged in the browser and in node: it imports nothing, touches no
- * node:* builtin and no dom api at module scope, and produces the exact
- * same procfs payloads, the 89-character nvidia-smi summary table, the
- * mesa software-stack summaries (rusticl opencl 3.1, lavapipe vulkan 1.4,
- * llvmpipe opengl 4.6) and the boot dmesg sequence the native engine emits.
- *
- * contexts (22): cpudata, gpudata, migprofiles, vendortables, topology,
- * cpuinfo, lscpu, pagealign, meminfo, freeh, smiformat, smitable, smilist,
- * clinfo, vulkaninfo, glxinfo, mesaenv, bootsequence, sandboxstate,
- * virtualfs, dispatcher, commands.
- *
- * rules: lowercase identifiers, english jsdoc in third person, no emoji,
- * zero dependencies, and deterministic fallbacks when crypto randomness
- * is unavailable.
- */
-/* ------------------------------------------------------------------ */
-/* context: shared helpers                                             */
-/* ------------------------------------------------------------------ */
-/** inclusive pseudo-random integer between min and max; deterministic
- * fallback when crypto randomness is unavailable. */
-function rnd(min, max) {
-    try {
-        const span = max - min + 1;
-        if (typeof globalThis.crypto?.getRandomValues === 'function') {
-            const buf = new Uint32Array(1);
-            globalThis.crypto.getRandomValues(buf);
-            return min + (buf[0] % span);
-        }
-    }
-    catch {
-        /* falls through to math.random */
-    }
-    return min + Math.floor(Math.random() * (max - min + 1));
-}
-/** right-pad helper that never exceeds the target width. */
-function pad(text, width) {
-    return text.length >= width ? text.slice(0, width) : text + ' '.repeat(width - text.length);
-}
-/** left-pad helper for right-aligned columns. */
-function padstart(text, width) {
-    return text.length >= width
-        ? text.slice(text.length - width)
-        : ' '.repeat(width - text.length) + text;
-}
-/**
- * formats one byte count with binary units (512 B, 4 KiB, 16 MiB, 1.5 GiB);
- * whole numbers drop the decimal so the default quota reads "16 MiB".
- *
- * @param {number} bytes the byte count.
- * @returns {string} the human readable size.
- */
-function humanbytes(bytes) {
-    const value = Math.max(0, Math.round(bytes));
-    const unit = (size, suffix) => {
-        const scaled = value / size;
-        const rounded = Math.round(scaled * 10) / 10;
-        return `${Number.isInteger(rounded) ? rounded : rounded.toFixed(1)} ${suffix}`;
-    };
-    if (value >= 1024 * 1024 * 1024) {
-        return unit(1024 * 1024 * 1024, 'GiB');
-    }
-    if (value >= 1024 * 1024) {
-        return unit(1024 * 1024, 'MiB');
-    }
-    if (value >= 1024) {
-        return unit(1024, 'KiB');
-    }
-    return `${value} B`;
-}
-/** lowercases a model string for case-insensitive lookups. */
-function normalizemodel(model) {
-    return String(model ?? '').trim().toLowerCase();
-}
-/** generates a random uuid-shaped hex token with a prefix. */
-function token(prefix) {
-    const raw = typeof globalThis.crypto?.randomUUID === 'function'
-        ? globalThis.crypto.randomUUID().replace(/-/g, '')
-        : Array.from({ length: 32 }, () => '0123456789abcdef'[rnd(0, 15)]).join('');
-    return `${prefix}${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20, 32)}`;
-}
-/* ------------------------------------------------------------------ */
-/* context: cpudata — the processor bank (specs verified 2026-08-22)   */
-/* ------------------------------------------------------------------ */
-/**
- * cpudata carries the six engine-bank processors (amd epyc 9965, ryzen 9
- * 9950x3d, threadripper pro 9995wx, threadripper 7980x, core ultra 9
- * 285k, epyc 9955) plus the two web showcase additions intel xeon 6980p
- * granite rapids and apple m3 ultra. every field mirrors the vendor pages
- * and the techpowerup database as pinned by best_virtual_processors.
- */
-export const cpudata = [
-    {
-        model: 'AMD EPYC 9965',
-        displayname: 'AMD EPYC 9965 192-Core Processor',
-        vendor: 'amd',
-        arch: 'x86_64',
-        cores: 192,
-        threads: 384,
-        baseclockmhz: 2250,
-        boostclockmhz: 3700,
-        allcoreclockmhz: 3350,
-        l3mb: 384,
-        l2mb: 192,
-        socket: 'SP5 (LGA6096)',
-        tdpwatts: 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',
-        arch: 'x86_64',
-        cores: 16,
-        threads: 32,
-        baseclockmhz: 4300,
-        boostclockmhz: 5700,
-        allcoreclockmhz: 5400,
-        l3mb: 128,
-        l2mb: 16,
-        socket: 'AM5',
-        tdpwatts: 170,
-        pcie: 'PCIe 5.0 x24',
-        maxmemorygb: 192,
-        memorytype: 'DDR5-5600',
-        memorychannels: 2,
-        microarch: 'Zen 5 X3D (3D V-Cache on one CCD)',
-        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',
-        arch: 'x86_64',
-        cores: 96,
-        threads: 192,
-        baseclockmhz: 2500,
-        boostclockmhz: 5400,
-        allcoreclockmhz: 4100,
-        l3mb: 384,
-        l2mb: 96,
-        socket: 'sTR5 (LGA4844)',
-        tdpwatts: 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',
-        arch: 'x86_64',
-        cores: 64,
-        threads: 128,
-        baseclockmhz: 3200,
-        boostclockmhz: 5100,
-        allcoreclockmhz: 4400,
-        l3mb: 256,
-        l2mb: 64,
-        socket: 'sTR5',
-        tdpwatts: 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',
-        arch: 'x86_64',
-        cores: 24,
-        threads: 24,
-        baseclockmhz: 3700,
-        boostclockmhz: 5700,
-        allcoreclockmhz: 5400,
-        l3mb: 36,
-        l2mb: 36,
-        socket: 'LGA1851',
-        tdpwatts: 125,
-        pcie: 'PCIe 5.0 x20 + PCIe 4.0 x4',
-        maxmemorygb: 192,
-        memorytype: 'DDR5-6400',
-        memorychannels: 2,
-        microarch: 'Arrow Lake (8P + 16E, 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',
-        arch: 'x86_64',
-        cores: 128,
-        threads: 256,
-        baseclockmhz: 2600,
-        boostclockmhz: 3750,
-        allcoreclockmhz: 3450,
-        l3mb: 384,
-        l2mb: 128,
-        socket: 'SP5',
-        tdpwatts: 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',
-    },
-    {
-        model: 'Intel Xeon 6980P',
-        displayname: 'Intel(R) Xeon(R) Platinum 6980P',
-        vendor: 'intel',
-        arch: 'x86_64',
-        cores: 128,
-        threads: 256,
-        baseclockmhz: 2200,
-        boostclockmhz: 3900,
-        allcoreclockmhz: 3300,
-        l3mb: 504,
-        l2mb: 128,
-        socket: 'LGA4710',
-        tdpwatts: 350,
-        pcie: 'PCIe 5.0 x128 + CXL 2.0 x16',
-        maxmemorygb: 6144,
-        memorytype: 'DDR5-6400 / MRDIMM-8800',
-        memorychannels: 12,
-        microarch: 'Granite Rapids (Intel 3)',
-        cpufamily: 6,
-        cpumodel: 173,
-        stepping: 2,
-        physicalline: '46 bits physical',
-        virtualline: '57 bits virtual',
-        launch: '2025-02',
-    },
-    {
-        model: 'Apple M3 Ultra',
-        displayname: 'Apple M3 Ultra (24P + 8E, 32-core CPU)',
-        vendor: 'apple',
-        arch: 'arm64',
-        cores: 32,
-        threads: 32,
-        baseclockmhz: 1000,
-        boostclockmhz: 4050,
-        allcoreclockmhz: 3400,
-        l3mb: 96,
-        l2mb: 96,
-        socket: 'soldered (UltraFusion interconnect)',
-        tdpwatts: 140,
-        pcie: 'PCIe 4.0 x8 + Thunderbolt 5 x2',
-        maxmemorygb: 512,
-        memorytype: 'LPDDR5 unified 819 GB/s',
-        memorychannels: 16,
-        microarch: 'Everest (3nm, two M3 Max dies fused)',
-        cpufamily: 0,
-        cpumodel: 0,
-        stepping: 0,
-        physicalline: '44 bits physical',
-        virtualline: '48 bits virtual',
-        launch: '2025-03',
-    },
-];
-/** resolves a processor spec by model name, case-insensitive; returns
- * undefined for unknown models so callers can shape friendly errors. */
-export function getcpu(model) {
-    const needle = normalizemodel(model);
-    return cpudata.find((spec) => normalizemodel(spec.model) === needle);
-}
-/**
- * resolves a catalog entry by its slug id (epyc-9965) as served by the
- * /api/v1/specs/cpus endpoint; returns undefined for unknown ids.
- * @param {string} id the catalog id.
- * @returns {object | undefined} the matching cpu entry.
- */
-export function getcpubyid(id) {
-    const key = String(id).toLowerCase().replace(/\s+/g, '-');
-    const strip = (name) => name
-        .toLowerCase()
-        .replace(/\s+/g, '-')
-        .replace(/^(amd|intel|apple|nvidia)-/, '');
-    return cpudata.find((entry) => {
-        const slug = entry.model.toLowerCase().replace(/\s+/g, '-');
-        return slug === key || slug.endsWith(key) || strip(entry.model) === strip(key);
-    });
-}
-/* ------------------------------------------------------------------ */
-/* context: vendortables — flag sets and identity strings              */
-/* ------------------------------------------------------------------ */
-/** zen 5 flag set exactly as generatevirtualcpuinfo renders it (avx-512
- * family, sha_ni, gfni and friends). */
-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',
-    '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 / granite rapids flag set: avx2 with avx_vnni and no avx-512
- * execution units; the ht flag is appended per model because arrow lake
- * ships without hyper-threading while xeon 6 keeps it. */
-const intelflags = [
-    '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', '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',
-];
-/** arm64 feature line rendered for apple silicon cpuinfo blocks. */
-const armfeatures = [
-    'fp', 'asimd', 'aes', 'pmull', 'sha1', 'sha2', 'sha3', 'sha512', 'crc32',
-    'atomics', 'fphp', 'asimdhp', 'cpuid', 'asimdrdm', 'jscvt', 'fcma',
-    'lrcpc', 'dcpop', 'sm3', 'sm4', 'asimddp', 'uscat', 'ilrcpc', 'flagm',
-    'ssbs', 'sb', 'paca', 'pacg', 'dcpodp', 'flagm2', 'frint', 'ecs', 'wfxt',
-    'bti',
-];
-/** vendor identity table consumed by cpuinfo and lscpu. */
-const vendortables = {
-    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: intelflags,
-        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]',
-    },
-    apple: {
-        vendorid: 'Apple',
-        flags: armfeatures,
-        bugs: '',
-        tlbsize: null,
-        cpuidlevel: 0,
-        powermanagement: '',
-    },
-};
-/* ------------------------------------------------------------------ */
-/* context: topology                                                   */
-/* ------------------------------------------------------------------ */
-/**
- * solves the package topology for a vcpu count against a spec; mirrors
- * solvetopology from virtualcpu.ts (smt parts round core counts up,
- * heterogeneous parts report one thread per core and the count is clamped
- * to the model thread ceiling).
- */
-export function solvetopology(spec, vcpus) {
-    const threadspercore = Math.max(1, Math.round(spec.threads / spec.cores));
-    const count = Math.max(1, Math.min(Math.round(vcpus) || 1, spec.threads));
-    return {
-        vcpus: count,
-        threadspercore,
-        coresonline: Math.ceil(count / threadspercore),
-        siblings: count,
-        sockets: 1,
-        fullypopulated: count === spec.threads,
-    };
-}
-/* ------------------------------------------------------------------ */
-/* context: cpuinfo — /proc/cpuinfo generation                         */
-/* ------------------------------------------------------------------ */
-/** per-key tab alignment the kernel uses on x86 cpuinfo lines. */
-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 /proc/cpuinfo text for a bank model with an
- * arbitrary vcpu count; x86_64 models render the full zen 5 / intel flag
- * set per logical processor and the apple model renders the arm64 cpuinfo
- * block shape instead.
- *
- * @param {string} model model name present in cpudata.
- * @param {number} vcpus number of logical processors to render.
- * @returns {string} the full procfs payload.
- */
-export function cpuinfo(model, vcpus) {
-    const spec = getcpu(model);
-    if (spec === undefined) {
-        throw new Error(`unknown processor model "${model}"; known models: ${cpudata.map((entry) => entry.model).join(', ')}`);
-    }
-    const topology = solvetopology(spec, vcpus);
-    const table = vendortables[spec.vendor];
-    const blocks = [];
-    for (let processor = 0; processor < topology.vcpus; processor += 1) {
-        if (spec.vendor === 'apple') {
-            blocks.push([
-                `processor\t: ${processor}`,
-                'BogoMIPS\t: 48.00',
-                `Features\t: ${table.flags.join(' ')}`,
-                'CPU implementer\t: 0x41',
-                'CPU architecture: 8',
-                'CPU variant\t: 0x2',
-                'CPU part\t: 0x612',
-                `CPU revision\t: ${processor % 2 === 0 ? 0 : 3}`,
-                '',
-                `MIDR_EL1\t: 0x0000000041026${processor % 2 === 0 ? '00' : '03'}`,
-                'Revidr_EL1\t: 0x00000000',
-                `CPU affinity\t: ${processor}`,
-            ].join('\n'));
-            continue;
-        }
-        const currentmhz = rnd(Math.round(spec.baseclockmhz), Math.round(spec.boostclockmhz) + 1);
-        const bogomips = (spec.baseclockmhz * 2 + rnd(-40, 41) / 100).toFixed(2);
-        const coreid = Math.floor(processor / topology.threadspercore);
-        const flags = spec.vendor === 'intel' && topology.threadspercore === 2
-            ? `${table.flags.join(' ')} ht`
-            : table.flags.join(' ');
-        const rows = [
-            line('processor', processor),
-            line('vendor_id', table.vendorid),
-            line('cpu family', spec.cpufamily),
-            line('model', spec.cpumodel),
-            line('model name', spec.displayname),
-            line('stepping', spec.stepping),
-            line('microcode', '0xffffffff'),
-            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', table.cpuidlevel),
-            line('wp', 'yes'),
-            line('flags', flags),
-            line('bugs', table.bugs),
-            line('bogomips', bogomips),
-        ];
-        if (table.tlbsize !== null) {
-            rows.push(line('TLB size', table.tlbsize));
-        }
-        rows.push(line('clflush size', 64), line('cache_alignment', 64), line('address sizes', `${spec.physicalline}, ${spec.virtualline}`), line('power management', table.powermanagement));
-        blocks.push(rows.join('\n'));
-    }
-    return blocks.join('\n\n');
-}
-/**
- * generates the util-linux lscpu summary for a bank model with numa node
- * ranges and vulnerability lines, mirroring generatevirtuallscpu.
- *
- * @param {string} model model name present in cpudata.
- * @param {number} vcpus logical processor count.
- * @param {number} [numanodes=1] number of numa nodes to spread over.
- * @returns {string} the lscpu text block.
- */
-export function lscpu(model, vcpus, numanodes = 1) {
-    const spec = getcpu(model);
-    if (spec === undefined) {
-        throw new Error(`unknown processor model "${model}"`);
-    }
-    const topology = solvetopology(spec, vcpus);
-    const corespersocket = Math.ceil(topology.coresonline / numanodes) * numanodes;
-    const rows = [
-        ['Architecture:', spec.arch === 'arm64' ? 'aarch64' : '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}`],
-    ];
-    if (spec.vendor === 'apple') {
-        rows.push(['Vendor ID:', 'Apple'], ['Model name:', spec.displayname], ['Thread(s) per core:', '1'], ['Core(s) per socket:', String(topology.coresonline)], ['Socket(s):', '1'], ['Cluster(s)-wide:', '24 performance + 8 efficiency cores'], ['Frequency boost:', 'enabled'], ['CPU max MHz:', `${spec.boostclockmhz}.0000`], ['CPU min MHz:', '600.0000']);
-    }
-    else {
-        rows.push(['Vendor ID:', vendortables[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)`]);
-    }
-    rows.push(['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}`]);
-    }
-    if (spec.vendor !== 'apple') {
-        rows.push(['Vulnerability Itlb multihit:', 'Not affected'], ['Vulnerability L1tf:', 'Not affected'], ['Vulnerability Mds:', 'Not affected'], ['Vulnerability Meltdown:', 'Not affected'], [
-            'Vulnerability Spectre v1:',
-            'Mitigation; usercopy/swapgs barriers and __user pointer sanitization',
-        ], [
-            'Vulnerability Spectre v2:',
-            spec.vendor === 'amd' ? 'Mitigation; Retpolines, IBPB' : 'Mitigation; Enhanced IBRS',
-        ]);
-    }
-    return rows.map(([key, value]) => `${key.padEnd(28)}${value}`).join('\n');
-}
-/* ------------------------------------------------------------------ */
-/* context: gpudata and migprofiles                                    */
-/* ------------------------------------------------------------------ */
-/**
- * gpudata mirrors the verified gpu_bank: seven real identities with
- * vrammib (physical capacity) and smireportedmib (the value after the
- * firmware carveout) cross-checked on 2026-08-22.
- */
-export const gpudata = [
-    {
-        id: 'rtx5090', name: 'NVIDIA GeForce RTX 5090', vendor: 'nvidia',
-        pcivendor: '10DE', pcidevice: '2B85', vrammib: 32768,
-        smireportedmib: 32607, memtype: 'GDDR7', busbits: 512,
-        bandwidthgbs: 1792, tdpwatts: 575, arch: 'GB202 Blackwell',
-        smarch: 'sm_120', smcount: 170, mig: false, driver: '575.57.08',
-        cuda: '12.9',
-    },
-    {
-        id: 'rtxpro6000', name: 'NVIDIA RTX PRO 6000 Blackwell', vendor: 'nvidia',
-        pcivendor: '10DE', pcidevice: '26B5', vrammib: 98304,
-        smireportedmib: 98304, memtype: 'GDDR7 ECC', busbits: 512,
-        bandwidthgbs: 1792, tdpwatts: 600, arch: 'GB202 Blackwell workstation',
-        smarch: 'sm_120', smcount: 188, mig: true, driver: '575.57.08',
-        cuda: '12.9',
-    },
-    {
-        id: 'b200', name: 'NVIDIA B200', vendor: 'nvidia',
-        pcivendor: '10DE', pcidevice: '2665', vrammib: 196608,
-        smireportedmib: 184320, memtype: 'HBM3e', busbits: 8192,
-        bandwidthgbs: 8000, tdpwatts: 1000, arch: 'GB100 Blackwell dual-die',
-        smarch: 'sm_100', smcount: 208, mig: true, driver: '575.57.08',
-        cuda: '12.9',
-    },
-    {
-        id: 'h100', name: 'NVIDIA H100 80GB HBM3', vendor: 'nvidia',
-        pcivendor: '10DE', pcidevice: '2330', vrammib: 81920,
-        smireportedmib: 81559, memtype: 'HBM3', busbits: 6144,
-        bandwidthgbs: 3350, tdpwatts: 700, arch: 'GH100 Hopper SXM5',
-        smarch: 'sm_90', smcount: 132, mig: true, driver: '575.57.08',
-        cuda: '12.9',
-    },
-    {
-        id: 'a100', name: 'NVIDIA A100-SXM4-40GB', vendor: 'nvidia',
-        pcivendor: '10DE', pcidevice: '20B0', vrammib: 40960,
-        smireportedmib: 40536, memtype: 'HBM2e', busbits: 5120,
-        bandwidthgbs: 1555, tdpwatts: 400, arch: 'GA100 Ampere SXM4',
-        smarch: 'sm_80', smcount: 108, mig: true, driver: '575.57.08',
-        cuda: '12.9',
-    },
-    {
-        id: 'rx9070xt', name: 'AMD Radeon RX 9070 XT', vendor: 'amd',
-        pcivendor: '1002', pcidevice: '748E', vrammib: 16384,
-        smireportedmib: 16384, memtype: 'GDDR6', busbits: 256,
-        bandwidthgbs: 640, tdpwatts: 304, arch: 'Navi 48 RDNA 4',
-        smarch: 'gfx1201', smcount: 64, mig: false,
-        driver: 'mesa 26.2.1 / rusticl', cuda: null,
-    },
-    {
-        id: 'mi350x', name: 'AMD Instinct MI350X', vendor: 'amd',
-        pcivendor: '1002', pcidevice: '75A0', vrammib: 294912,
-        smireportedmib: 294912, memtype: 'HBM3e', busbits: 8192,
-        bandwidthgbs: 8000, tdpwatts: 1000, arch: 'CDNA 4 Aqua Vanjaram',
-        smarch: 'gfx950', smcount: 304, mig: false, driver: 'rocm 7.x',
-        cuda: null,
-    },
-];
-/** resolves a gpu spec by id or name, case-insensitive. */
-export function getgpu(gpu) {
-    const needle = normalizemodel(gpu);
-    return gpudata.find((spec) => normalizemodel(spec.id) === needle || normalizemodel(spec.name) === needle);
-}
-/**
- * migprofiles mirrors the mig catalog of the 96 gb-class virtual device:
- * 1g.24gb exposes 24 gb slices (4 instances), 2g.48gb 48 gb slices (2
- * instances) and 4g.96gb dedicates the full device to one instance.
- */
-export const migprofiles = [
-    { id: '1g.24gb', slicegb: 24, maxinstances: 4 },
-    { id: '2g.48gb', slicegb: 48, maxinstances: 2 },
-    { id: '4g.96gb', slicegb: 96, maxinstances: 1 },
-];
-/** resolves a mig profile by id; null for 'off' and unknown names. */
-export function getmig(id) {
-    if (id === 'off' || id === undefined || id === null || id === '') {
-        return null;
-    }
-    return migprofiles.find((profile) => profile.id === id) ?? null;
-}
-/* ------------------------------------------------------------------ */
-/* context: meminfo and free — /proc/meminfo generation                */
-/* ------------------------------------------------------------------ */
-/** rounds a kb value down to the nearest 4 kb page boundary. */
-export function pagealign(kb) {
-    return Math.floor(kb / 4) * 4;
-}
-/**
- * generates a complete /proc/meminfo text for the requested total ram in
- * gb, mirroring generatevirtualmeminfo: memtotal, memfree, memavailable,
- * buffers, cached, the anon/file split, swap, slab, commit accounting
- * under vm.overcommit_memory=2 semantics and the direct map breakdown.
- *
- * @param {number} ramgb total guest ram in gb (positive number).
- * @param {{swapgb?: number, vcpus?: number, freefraction?: number,
- *   availablefraction?: number}} [options] optional overrides.
- * @returns {string} the full meminfo payload.
- */
-export function meminfo(ramgb, options = {}) {
-    if (!Number.isFinite(ramgb) || ramgb <= 0) {
-        throw new Error(`ramgb must be a positive number, received ${ramgb}`);
-    }
-    const vcpus = options.vcpus ?? 8;
-    const totalkb = pagealign(ramgb * 1024 * 1024 - 131072);
-    const freefraction = options.freefraction ?? rnd(38, 68) / 1000;
-    const availablefraction = options.availablefraction ?? rnd(860, 930) / 1000;
-    const memfree = pagealign(totalkb * freefraction);
-    const memavailable = pagealign(totalkb * availablefraction);
-    const buffers = pagealign(totalkb * (rnd(50, 80) / 10000));
-    const cached = pagealign(totalkb * (rnd(300, 420) / 1000));
-    const activeanon = pagealign(totalkb * (rnd(240, 320) / 1000));
-    const inactiveanon = pagealign(totalkb * (rnd(60, 120) / 1000));
-    const active = pagealign(activeanon + cached * 0.55);
-    const inactive = pagealign(inactiveanon + cached * 0.4);
-    const swapgb = options.swapgb ?? Math.min(Math.max(Math.round(ramgb / 8), 2), 128);
-    const swaptotal = swapgb * 1024 * 1024;
-    const swapfree = pagealign(swaptotal * (rnd(850, 980) / 1000));
-    const commitlimit = pagealign(swaptotal + (totalkb * 50) / 100);
-    const committedas = pagealign(totalkb * (rnd(95, 160) / 100));
-    const slab = pagealign(totalkb * (rnd(190, 240) / 10000));
-    const sreclaimable = pagealign(slab * 0.64);
-    const anonhuge = pagealign(activeanon * (rnd(20, 45) / 100));
-    const directmap1g = ramgb >= 64 ? pagealign(totalkb * 0.8) : 0;
-    const directmap2m = directmap1g > 0 ? pagealign(totalkb * 0.15) : pagealign(totalkb * 0.9);
-    const rows = [
-        ['MemTotal', totalkb], ['MemFree', memfree],
-        ['MemAvailable', memavailable], ['Buffers', buffers], ['Cached', cached],
-        ['SwapCached', 0], ['Active', active], ['Inactive', inactive],
-        ['Active(anon)', activeanon], ['Inactive(anon)', inactiveanon],
-        ['Active(file)', pagealign(active - activeanon)],
-        ['Inactive(file)', pagealign(inactive - inactiveanon)],
-        ['Unevictable', pagealign(rnd(16384, 65536))],
-        ['Mlocked', pagealign(rnd(4096, 16384))],
-        ['SwapTotal', swaptotal], ['SwapFree', swapfree],
-        ['Dirty', pagealign(rnd(20480, 262144))], ['Writeback', 0],
-        ['AnonPages', pagealign(activeanon * 1.08)],
-        ['Mapped', pagealign(totalkb * (rnd(20, 42) / 1000))],
-        ['Shmem', pagealign(totalkb * (rnd(5, 12) / 1000))],
-        ['KReclaimable', sreclaimable], ['Slab', slab],
-        ['SReclaimable', sreclaimable],
-        ['SUnreclaim', pagealign(slab - sreclaimable)],
-        ['KernelStack', pagealign(vcpus * 320)],
-        ['PageTables', pagealign(totalkb * (rnd(30, 60) / 10000))],
-        ['SecPageTables', pagealign(totalkb * (rnd(8, 16) / 10000))],
-        ['NFS_Unstable', 0], ['Bounce', 0], ['WritebackTmp', 0],
-        ['CommitLimit', commitlimit], ['Committed_AS', committedas],
-        ['VmallocTotal', 34359738367],
-        ['VmallocUsed', pagealign(rnd(49152, 131072))], ['VmallocChunk', 0],
-        ['Percpu', pagealign(vcpus * rnd(20480, 40960))],
-        ['HardwareCorrupted', 0], ['AnonHugePages', anonhuge],
-        ['ShmemHugePages', 0], ['ShmemPmdMapped', 0], ['FileHugePages', 0],
-        ['FilePmdMapped', 0], ['Unaccepted', 0], ['HugePages_Total', 0],
-        ['HugePages_Free', 0], ['HugePages_Rsvd', 0], ['HugePages_Surp', 0],
-        ['Hugepagesize', 2048], ['Hugetlb', 0],
-        ['DirectMap4k', pagealign(rnd(131072, 262144))],
-        ['DirectMap2M', directmap2m], ['DirectMap1G', directmap1g],
-    ];
-    return rows
-        .map(([key, value]) => `${key}:${String(value).padStart(24 - key.length - 1)} kB`)
-        .join('\n');
-}
-/** converts a kb value to the largest human unit for free -h. */
-function human(kb) {
-    if (kb >= 1024 * 1024) {
-        const gb = kb / (1024 * 1024);
-        return `${gb >= 100 ? Math.round(gb) : gb.toFixed(1)}Gi`;
-    }
-    if (kb >= 1024) {
-        return `${(kb / 1024).toFixed(1)}Mi`;
-    }
-    return `${Math.round(kb)}Ki`;
-}
-/**
- * renders the free -h table derived from a memoized meminfo snapshot so
- * cat /proc/meminfo and free -h always agree inside one sandbox.
- *
- * @param {string} meminfotext a payload previously returned by meminfo().
- * @returns {string} the free -h table.
- */
-export function freeh(meminfotext) {
-    const map = {};
-    for (const row of meminfotext.split('\n')) {
-        const match = /^([A-Za-z_()]+):\s*(\d+)\skB$/.exec(row);
-        if (match !== null) {
-            map[match[1]] = Number(match[2]);
-        }
-    }
-    const total = map.MemTotal ?? 0;
-    const freekb = map.MemFree ?? 0;
-    const buffers = map.Buffers ?? 0;
-    const cached = (map.Cached ?? 0) + (map.SReclaimable ?? 0);
-    const available = map.MemAvailable ?? 0;
-    const used = Math.max(0, total - freekb - buffers - cached);
-    const swap = map.SwapTotal ?? 0;
-    const swapfreekb = map.SwapFree ?? 0;
-    const swapused = swap - swapfreekb;
-    const w = (text) => padstart(String(text), 13);
-    return [
-        `${w('total')}${w('used')}${w('free')}${w('shared')}${w('buff/cache')}${w('available')}`,
-        ['Mem:', w(human(total)), w(human(used)), w(human(freekb)),
-            w(human(map.Shmem ?? 0)), w(human(buffers + cached)), w(human(available))].join(''),
-        ['Swap:', w(human(swap)), w(human(swapused)), w(human(swapfreekb))].join(''),
-    ].join('\n');
-}
-/* ------------------------------------------------------------------ */
-/* context: smiformat — the exact 89-char summary table                */
-/* ------------------------------------------------------------------ */
-const smiwidth = 89;
-const smicolumns = [40, 24, 21];
-const procwidth = 75;
-const smidriver = '575.57.08';
-const cudaversion = '12.9';
-const weekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
-const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
-/** formats the nvidia-smi timestamp "weekday month day hh:mm:ss year". */
-function formatstamp(date) {
-    const two = (value) => String(value).padStart(2, '0');
-    return `${weekdays[date.getDay()]} ${months[date.getMonth()]} ${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())} ${date.getFullYear()}`;
-}
-/** full-width border line: "+" plus 87 fill characters plus "+". */
-function smiborder(fill) {
-    return `+${fill.repeat(smiwidth - 2)}+`;
-}
-/** full-width content line padded to the 89-char table width. */
-function smifull(content) {
-    return `|${pad(content, smiwidth - 2)}|`;
-}
-/** three-column separator: pipes at fixed offsets 1, 42 and 67. */
-function smisep(fill) {
-    return `|${fill.repeat(smicolumns[0])}+${fill.repeat(smicolumns[1])}+${fill.repeat(smicolumns[2])}|`;
-}
-/** three-column data row within the 89-char width. */
-function smirow(left, mid, right) {
-    return `|${pad(left, smicolumns[0])}|${pad(mid, smicolumns[1])}|${pad(right, smicolumns[2])}|`;
-}
-/** process table content line within the 75-char width. */
-function procline(content) {
-    return `|${pad(content, procwidth - 2)}|`;
-}
-/**
- * renders the complete virtual nvidia-smi adapter report; the summary
- * table is exactly 89 characters wide and the header pins driver
- * 575.57.08 and cuda 12.9 exactly as the native smiadapterbuilder does.
- * when a mig profile is active the memory column reflects the slice size
- * and a mig line joins the table.
- *
- * @param {string} gpu gpu id or name present in gpudata.
- * @param {string} [migprofile='off'] one of 1g.24gb, 2g.48gb, 4g.96gb or off.
- * @returns {string} the full report text.
- */
-export function nvidiaSmiTable(gpu, migprofile = 'off') {
-    const spec = getgpu(gpu);
-    if (spec === undefined) {
-        throw new Error(`unknown gpu "${gpu}"; known gpus: ${gpudata.map((entry) => entry.id).join(', ')}`);
-    }
-    const mig = getmig(migprofile);
-    const vrammib = mig !== null ? mig.slicegb * 1024 : spec.smireportedmib;
-    const memusedmib = rnd(0, 24);
-    const util = rnd(0, 3);
-    const temperature = rnd(38, 47);
-    const fanspeed = rnd(24, 38);
-    const powerw = Math.max(10, Math.round(spec.tdpwatts * 0.04));
-    const head = ` NVIDIA-SMI ${smidriver} ${' '.repeat(13)}Driver Version: ${smidriver}${' '.repeat(6)}CUDA Version: ${cudaversion}`;
-    const lines = [
-        formatstamp(new Date()),
-        smiborder('-'),
-        smifull(head),
-        smisep('-'),
-        smirow(`${pad(' GPU  Name', 27)}${pad('Persistence-M', 13)}`, pad(' Bus-Id          Disp.A', 24), ` ${padstart('Volatile Uncorr. ECC', 20)}`),
-        smirow(pad(' Fan  Temp   Perf      Pwr:Usage/Cap', 40), pad('         Memory-Usage', 24), ` ${padstart('GPU-Util  Compute M.', 20)}`),
-        smisep('='),
-        smirow(`${pad(`   0  ${spec.name}`, 36)}${pad('Off', 4)}`, pad('   00000000:01:00.0  Off', 24), ` ${padstart('N/A', 20)}`),
-        smirow(pad(` ${fanspeed}%   ${temperature}C  P0    ${powerw}W / ${spec.tdpwatts}W`, 40), padstart(`${memusedmib}MiB / ${vrammib}MiB`, 24), `${padstart(`${util}%`, 10)}${pad('  Default', 11)}`),
-    ];
-    if (mig !== null) {
-        lines.push(smifull(` MIG: enabled, profile ${mig.id}, ${mig.maxinstances} instance(s) of ${mig.slicegb} GB`));
-    }
-    lines.push(smirow('', '', ''), smiborder('-'), '', 'Processes:', procline(`${pad(' GPU  GI  CI', 20)}${pad('PID', 7)}${pad('Type', 8)}${pad('Process name', 27)}${pad('GPU Memory', 11)}`), procline('='.repeat(procwidth - 2)));
-    if (mig !== null) {
-        for (let instance = 0; instance < mig.maxinstances; instance += 1) {
-            lines.push(procline(`${pad(` 0    ${instance}    0`, 20)}${pad(String(1200 + instance), 7)}${pad('MIG', 8)}${pad('mig-worker', 27)}${pad(`${rnd(0, 512)}MiB`, 11)}`));
-        }
-    }
-    else {
-        lines.push(procline('  No running processes found'));
-    }
-    lines.push(`+${'-'.repeat(procwidth - 2)}+`);
-    return lines.join('\n');
-}
-/**
- * renders the nvidia-smi -l device listing; with an active mig profile
- * the mig device lines follow the parent gpu line.
- *
- * @param {string} gpu gpu id or name present in gpudata.
- * @param {string} [migprofile='off'] mig profile id or off.
- * @returns {string} the -l listing.
- */
-export function nvidiaSmiList(gpu, migprofile = 'off') {
-    const spec = getgpu(gpu);
-    if (spec === undefined) {
-        throw new Error(`unknown gpu "${gpu}"`);
-    }
-    const mig = getmig(migprofile);
-    const lines = [`GPU 0: ${spec.name} (UUID: ${token('GPU-')})`];
-    if (mig !== null) {
-        for (let instance = 0; instance < mig.maxinstances; instance += 1) {
-            lines.push(`  MIG ${mig.id}     Device  ${instance}: (UUID: ${token('MIG-')})`);
-        }
-    }
-    return lines.join('\n');
-}
-/* ------------------------------------------------------------------ */
-/* context: mesa stack summaries                                       */
-/* ------------------------------------------------------------------ */
-/** the software rendering stack pinned from primary sources. */
-const mesastack = {
-    mesa: '26.2.1', llvm: '22.1.8', gl: '4.6', gles: '3.2', vulkan: '1.4',
-    opencl: '3.1',
-};
-/**
- * renders the clinfo summary for the rusticl platform on llvmpipe: opencl
- * 3.1 (same-day spec support in mesa 26.2), fp16 default since 25.2 and
- * fp64 through rusticl_features.
- *
- * @param {number} [vcpus=8] vcpu count reported as compute units.
- * @returns {string} the clinfo summary block.
- */
-export function clinfoSummary(vcpus = 8) {
-    const units = Math.max(1, Math.min(vcpus, 32));
-    return [
-        'Number of platforms                               1',
-        '  Platform Name                                   rusticl',
-        '  Platform Vendor                                 Mesa/X.org',
-        '  Platform Version                                OpenCL 3.1',
-        '  Platform Profile                                FULL_PROFILE',
-        '  Platform Extensions                             cl_khr_fp64 cl_khr_fp16 cl_khr_icd cl_khr_command_buffer',
-        'Number of devices                                 1',
-        '  Device Name                                     llvmpipe (CPU)',
-        '  Device Vendor                                   Mesa/X.org',
-        '  Device Vendor ID                                0x10005 (Mesa)',
-        '  Device Version                                  OpenCL 3.1',
-        '  Device Type                                     GPU',
-        `  Max compute units                               ${units}`,
-        '  Max work item dimensions                        3',
-        '  Max work group size                             1024',
-        '  Preferred vector width char/int/float           16/16/16',
-        '  Max clock frequency                             3700MHz',
-        '  Address bits                                    64',
-        '  Half precision support                          cl_khr_fp16 (default since mesa 25.2)',
-        '  Double precision support                        cl_khr_fp64 (rusticl_features=fp64)',
-        '  Device available                                Yes',
-        '  Compiler available                              Yes',
-        '  SPIR versions                                   1.2',
-    ].join('\n');
-}
-/**
- * renders the vulkaninfo --summary block for lavapipe: vulkan 1.4 surface
- * since mesa 25.1, khronos-conformant on the vulkan 1.3 cts, selected
- * through vk_driver_files (vk_icd_filenames is deprecated).
- *
- * @returns {string} the vulkan summary block.
- */
-export function vulkanSummary() {
-    return [
-        '==========',
-        'VULKANINFO',
-        '==========',
-        '',
-        'Instance Extensions: count=10',
-        'VK_KHR_surface                            : extension revision 25',
-        'VK_KHR_get_physical_device_properties2    : extension revision 2',
-        'VK_EXT_headless_surface                   : extension revision 1',
-        '',
-        'API Version: 1.4.313',
-        '',
-        'GPU0:',
-        '    apiVersion        = 1.4.313',
-        '    driverVersion     = 26.2.1',
-        '    vendorID          = 0x10005',
-        '    deviceID          = 0x0000',
-        '    deviceType        = CPU',
-        '    deviceName        = llvmpipe (CPU (x86_64))',
-        '    driverName        = mesa_llvmpipe',
-        `    driverInfo        = Mesa ${mesastack.mesa} (LLVM ${mesastack.llvm})`,
-        '    conformantVersion = 1.3.0.0',
-        '',
-        'Device Extensions: count=204',
-        'VK_KHR_8bit_storage VK_KHR_16bit_storage VK_KHR_shader_float16_int8',
-        'VK_KHR_spirv_1_4 VK_KHR_storage_buffer_storage_class',
-    ].join('\n');
-}
-/**
- * renders the glxinfo header block for llvmpipe: opengl 4.6 core profile
- * 100% (161/161 extensions tracked by mesamatrix) and the llvmpipe
- * renderer string with the llvm version.
- *
- * @returns {string} the glxinfo block.
- */
-export function glxinfoSummary() {
-    return [
-        'name of display: :0',
-        'display: :0  screen: 0',
-        'direct rendering: Yes',
-        'server glx vendor string: SGI',
-        'client glx vendor string: Mesa Project and SGI',
-        'OpenGL vendor string: Mesa',
-        `OpenGL renderer string: llvmpipe (LLVM ${mesastack.llvm}, 256 bits)`,
-        `OpenGL core profile version string: ${mesastack.gl} (Core Profile) Mesa ${mesastack.mesa}`,
-        'OpenGL core profile shading language version string: 4.60',
-        '',
-        'OpenGL core profile context flags: (none)',
-        'OpenGL core profile profile mask: core profile',
-        '',
-        'OpenGL core profile extensions: 161',
-        `OpenGL version string: ${mesastack.gl} (Compatibility Profile) Mesa ${mesastack.mesa}`,
-        'OpenGL shading language version string: 4.60',
-        'OpenGL context flags: (none)',
-        '',
-        'Extended renderer info (GLX_MESA_query_renderer):',
-        '    Vendor: Mesa/X.org (0x1002)',
-        `    Device: llvmpipe (LLVM ${mesastack.llvm}, 256 bits) (0xffffffff)`,
-        `    Version: ${mesastack.mesa}`,
-        '    Accelerated: no',
-        '    Video memory: 32768MB',
-        '    Unified memory: yes',
-        '    Texture from pixmap: yes',
-    ].join('\n');
-}
-/**
- * assembles the validated mesa environment exactly as mesaenvbuilder +
- * renderenv('opengl') do: llvmpipe forced, gl 4.6, glsl 460, vector width
- * 512 to exercise the avx-512 paths, lavapipe through vk_driver_files and
- * rusticl opencl 3.1 with the fp64 feature.
- *
- * @param {number} [vcpus=8] vcpu count used for lp_num_threads (0 uses
- *   every core up to the lp_max_threads=32 ceiling).
- * @returns {Record<string, string>} the environment record.
- */
-export function mesaenv(vcpus = 8) {
-    const threads = vcpus <= 0 ? 0 : Math.min(vcpus, 32);
-    return {
-        LIBGL_ALWAYS_SOFTWARE: 'true',
-        GALLIUM_DRIVER: 'llvmpipe',
-        MESA_GL_VERSION_OVERRIDE: mesastack.gl,
-        MESA_GLSL_VERSION_OVERRIDE: '460',
-        MESA_GLES_VERSION_OVERRIDE: mesastack.gles,
-        MESA_VK_VERSION_OVERRIDE: mesastack.vulkan,
-        LP_NUM_THREADS: String(threads),
-        LP_NATIVE_VECTOR_WIDTH: '512',
-        MESA_NO_ERROR: '1',
-        VK_DRIVER_FILES: '/usr/share/vulkan/icd.d/lvp_icd.x86_64.json',
-        MESA_VK_WSI_HEADLESS_SWAPCHAIN: '1',
-        RUSTICL_ENABLE: 'llvmpipe',
-        RUSTICL_DEVICE_TYPE: 'gpu',
-        RUSTICL_CL_VERSION: mesastack.opencl,
-        RUSTICL_FEATURES: 'fp64',
-    };
-}
-/* ------------------------------------------------------------------ */
-/* context: bootsequence — dmesg-style boot lines                      */
-/* ------------------------------------------------------------------ */
-/**
- * renders the firecracker-style boot log for a sandbox: kernel banner,
- * 125 ms microvm bring-up, memory sizing, vcpu online lines, the mesa
- * software stack bring-up and the virtual gpu identity binding. every
- * line carries the kernel [    0.000000] timestamp style.
- *
- * @param {string} model cpu model name present in cpudata.
- * @param {number} vcpus logical processor count.
- * @param {number} [ramgb=32] guest ram in gb.
- * @param {string} [gpu='rtx5090'] gpu id present in gpudata.
- * @param {number} [quota=16777216] persistent workspace quota in bytes.
- * @returns {string[]} ordered dmesg lines.
- */
-export function bootSequence(model, vcpus, ramgb = 32, gpu = 'rtx5090', quota = 16 * 1024 * 1024) {
-    const spec = getcpu(model) ?? cpudata[0];
-    const gpuspec = getgpu(gpu) ?? gpudata[0];
-    const topology = solvetopology(spec, vcpus);
-    const arch = spec.arch === 'arm64' ? 'aarch64' : 'x86_64';
-    const stamp = (seconds) => `[${seconds.toFixed(6).padStart(12)}]`;
-    const onlinetime = 0.039 + 0.00042 * topology.vcpus;
-    return [
-        `${stamp(0)} Linux version 6.12.0-saddle (root@saddle) (gcc 15.1.0, ld 2.44) #1 SMP PREEMPT_DYNAMIC ${arch}`,
-        `${stamp(0.000049)} Command line: root=/dev/vda rw console=ttyS0 reboot=k panic=1 pci=off i8042.noaux i8042.nomux i8042.nopnp i8042.dumbkbd`,
-        `${stamp(0.004201)} BIOS-provided physical RAM map (virtio-mem + memfd hugetlb backend)`,
-        `${stamp(0.008913)} Memory: ${pagealign(ramgb * 1024 * 1024 - 131072)}K available (${ramgb} GB guest plan, 4 kB pages)`,
-        `${stamp(0.012451)} firecracker: microvm vm_state=Running boot_time=125ms vmm=fc v1.16.1`,
-        `${stamp(0.02133)} virtio_blk virtio1: [vda] 8589934592 512-byte logical blocks (8.6 GB)`,
-        `${stamp(0.038774)} smpboot: ${topology.coresonline} cores, ${topology.vcpus} threads online (${spec.model})`,
-        `${stamp(0.039001)} cpu cpu0: ${spec.microarch}, boost ${spec.boostclockmhz} MHz, l3 ${spec.l3mb} MB`,
-        `${stamp(onlinetime)} smp: brought up ${topology.vcpus} cpus, cpu mask 0-${topology.vcpus - 1}`,
-        `${stamp(onlinetime + 0.0148)} NUMA: ${Math.max(1, Math.round(topology.vcpus / 64))} node(s), interleave enabled`,
-        `${stamp(onlinetime + 0.0283)} hugepage: 2048 kB pages reserved, thp=always`,
-        `${stamp(onlinetime + 0.0422)} docker: engine 29.7.2 ready, containerd 2.3.1, memswap=-1 shm=2g`,
-        `${stamp(onlinetime + 0.0551)} qemu-system-${arch}: bridge 11.1.0 attached (qmp unix:/run/saddle/qemu-0.sock)`,
-        `${stamp(onlinetime + 0.0784)} mesa ${mesastack.mesa}: llvmpipe rasterizer, lp_num_threads=${Math.min(topology.vcpus, 32)}, lp_max_threads=32`,
-        `${stamp(onlinetime + 0.0789)} llvmpipe: avx-512 vector width 512 selected by gallivm (llvm ${mesastack.llvm})`,
-        `${stamp(onlinetime + 0.0812)} lavapipe: vulkan ${mesastack.vulkan}, icd lvp_icd.${arch}.json, wsi headless`,
-        `${stamp(onlinetime + 0.0837)} rusticl: opencl ${mesastack.opencl} on llvmpipe, features fp64 (fp16 default since 25.2)`,
-        `${stamp(onlinetime + 0.091)} virtualgpu: identity ${gpuspec.name} [${gpuspec.pcivendor}:${gpuspec.pcidevice}] ${gpuspec.memtype} ${gpuspec.vrammib / 1024} GB`,
-        `${stamp(onlinetime + 0.0922)} nvml shim: FAKE_MODEL="${gpuspec.name}" FAKE_VRAM=${gpuspec.smireportedmib} (fake-nvidia-smi adapter ready)`,
-        `${stamp(onlinetime + 0.1045)} saddle: virtual hardware engine v2.0.127, sandbox created -> running`,
-        `${stamp(onlinetime + 0.1047)} saddle: persistent workspace: ${humanbytes(quota)} quota, data stays with the sandbox id`,
-        `${stamp(onlinetime + 0.1046)} Freeing unused kernel image memory`,
-    ];
-}
-/* ------------------------------------------------------------------ */
-/* context: sandboxstate and dispatcher                                */
-/* ------------------------------------------------------------------ */
-/**
- * creates the state object shared by the browser terminal and the api
- * exec endpoint: resolved specs, a stable hostname, the boot timestamp and
- * a memoized meminfo snapshot so memory reports stay consistent within
- * one sandbox session.
- *
- * @param {{model: string, vcpus: number, ramgb: number, gpu: string,
- *   mig?: string, id?: string}} spec the sandbox specification.
- * @returns {object} the sandbox state consumed by dispatch.
- */
-export function createSandboxState(spec) {
-    // the reviewed catalog is the only source of processor identity; ram
-    // accepts any user chosen plan up to the 18 tb virtual ceiling.
-    const cpu = getcpu(spec.model) ?? cpudata[0];
-    const gpu = getgpu(spec.gpu) ?? gpudata[0];
-    const topology = solvetopology(cpu, spec.vcpus ?? 8);
-    const ramgb = Math.max(1, Math.min(Math.round(spec.ramgb ?? 32), 18432));
-    const id = spec.id ?? token('sb-');
-    return {
-        model: cpu.model,
-        cpuspec: cpu,
-        gpuspec: gpu,
-        vcpus: topology.vcpus,
-        ramgb,
-        gpu: gpu.id,
-        mig: getmig(spec.mig) === null ? 'off' : spec.mig,
-        id,
-        hostname: `saddle-${id.replace(/^sb-/, '').slice(0, 8)}`,
-        boottime: Date.now(),
-        kernel: cpu.arch === 'arm64' ? '6.12.0-saddle-aarch64' : '6.12.0-saddle',
-        memsnapshot: meminfo(ramgb, { vcpus: topology.vcpus }),
-        history: [],
-        files: new Map(),
-    };
-}
-/** the supported command list, reused by help and the terminal. */
-export const commands = [
-    'help', 'lscpu', 'cat /proc/cpuinfo', 'cat /proc/meminfo', 'free -h',
-    'nvidia-smi', 'nvidia-smi -L', 'clinfo', 'vulkaninfo --summary',
-    'glxinfo', 'uname -a', 'ls /etc/virtual', 'env', 'docker --version',
-    'qemu-system-x86_64 --version', 'uptime', 'whoami', 'neofetch', 'clear',
-    'echo', 'echo <text> > <file>', 'echo <text> >> <file>', 'touch <file>',
-    'cat <file>', 'ls', 'rm <file>', 'df -h', 'stat <file>', 'pwd',
-    'history', 'streaming', 'man <command>',
-];
-/** renders the help text with every supported command. */
-function helpText() {
-    const rows = [
-        ['help', 'this command list'],
-        ['lscpu', 'virtual processor topology summary'],
-        ['cat /proc/cpuinfo', 'full procfs cpuinfo payload'],
-        ['cat /proc/meminfo', 'full procfs meminfo payload'],
-        ['free -h', 'human readable memory table'],
-        ['nvidia-smi', 'virtual gpu adapter report (89-char table)'],
-        ['nvidia-smi -L', 'virtual gpu device listing'],
-        ['clinfo', 'rusticl opencl 3.1 summary on llvmpipe'],
-        ['vulkaninfo --summary', 'lavapipe vulkan 1.4 summary'],
-        ['glxinfo', 'llvmpipe opengl 4.6 summary'],
-        ['uname -a', 'kernel and architecture line'],
-        ['ls /etc/virtual', 'virtual hardware definition files'],
-        ['env', 'mesa llvmpipe environment variables'],
-        ['docker --version', 'docker engine version'],
-        ['qemu-system-x86_64 --version', 'qemu bridge version'],
-        ['uptime', 'sandbox uptime and load average'],
-        ['whoami', 'current user'],
-        ['neofetch', 'saddle ascii logo and sandbox specs'],
-        ['clear', 'clear the terminal'],
-        ['echo <text>', 'print text'],
-        ['echo <text> > <file>', 'write text to a workspace file'],
-        ['echo <text> >> <file>', 'append text to a workspace file'],
-        ['touch <file>', 'create an empty workspace file'],
-        ['cat <file>', 'print a persistent workspace file'],
-        ['ls', 'list the workspace root with sizes and dates'],
-        ['rm <file>', 'delete one workspace file'],
-        ['df -h', 'workspace quota usage as a filesystem table'],
-        ['stat <file>', 'size and timestamps of one workspace file'],
-        ['pwd', 'print the working directory (always /)'],
-        ['history', 'streaming', 'the last 50 commands of this session'],
-        ['man <command>', 'short manual for one command'],
-    ];
-    return rows.map(([name, about]) => `  ${pad(name, 32)}${about}`).join('\n');
-}
-/** renders the neofetch block: the saddle ascii logo beside sandbox specs. */
-function neofetch(state) {
-    const cpu = state.cpuspec;
-    const gpu = state.gpuspec;
-    const logo = [
-        '      ``-://////:-``          ',
-        '    ./+++++++++++++/-.        ',
-        '   -+++++++++++++++++++-`     ',
-        '  ./+++ saddle sandbox ++/.    ',
-        '  -+++++++++++++++++++++-`    ',
-        '   `-:/+++++++++++++/-.       ',
-        '      .-://////:-.            ',
-        '                              ',
-    ];
-    const uptime = Math.max(1, Math.round((Date.now() - state.boottime) / 1000));
-    const mins = Math.floor(uptime / 60);
-    const hours = Math.floor(mins / 60);
-    const uptimeText = hours > 0 ? `${hours} hour(s), ${mins % 60} min` : `${mins} min`;
-    const total = pagealign(state.ramgb * 1024 * 1024 - 131072);
-    const mig = getmig(state.mig);
-    const info = [
-        `root@${state.hostname}`,
-        '-----------------',
-        'OS: saddle linux (virtual hardware engine v2.0.127)',
-        'Host: firecracker microvm (125 ms boot)',
-        `Kernel: ${state.kernel}`,
-        `Uptime: ${uptimeText}`,
-        'Packages: 412 (dpkg), 8 (snap)',
-        'Shell: bash 5.2.37',
-        `CPU: ${cpu.displayname} (${state.vcpus}) @ ${cpu.boostclockmhz}.00MHz`,
-        `GPU: ${gpu.name} [${gpu.pcivendor}:${gpu.pcidevice}]`,
-        `Memory: ${human(Math.round(total * 0.31))} / ${human(total)}`,
-        `vRAM: ${gpu.memtype} ${gpu.vrammib / 1024} GB${mig !== null ? ` (MIG ${mig.id})` : ''}`,
-        'Renderer: llvmpipe (LLVM 22.1.8) / lavapipe 1.4 / rusticl 3.1',
-    ];
-    const rows = Math.max(logo.length, info.length);
-    const out = [];
-    for (let index = 0; index < rows; index += 1) {
-        out.push(`${(logo[index] ?? '').padEnd(30)}${info[index] ?? ''}`);
-    }
-    return out.join('\n');
-}
-/** renders the uptime line with a load average derived from the vcpus. */
-function uptimeLine(state) {
-    const totalSeconds = Math.max(0, Math.floor((Date.now() - state.boottime) / 1000));
-    const now = new Date();
-    const mins = Math.max(1, Math.round(totalSeconds / 60));
-    const load = (decay) => (Math.random() * state.vcpus * 0.18 * Math.exp(-decay / 30)).toFixed(2);
-    return ` ${now.toTimeString().slice(0, 8)} up ${mins} min,  1 user,  load average: ${load(1)}, ${load(5)}, ${load(15)}`;
-}
-/** renders the env listing: the mesa stack plus the sandbox variables. */
-function envText(state) {
-    const mig = getmig(state.mig);
-    const entries = {
-        ...mesaenv(state.vcpus),
-        FAKE_MODEL: state.gpuspec.name,
-        FAKE_VRAM: String(mig !== null ? mig.slicegb * 1024 : state.gpuspec.smireportedmib),
-        SADDLE_VERSION: '2.0.127',
-        SADDLE_SANDBOX: state.id,
-        SADDLE_STATE: 'running',
-        SADDLE_CPU: state.model,
-        SADDLE_GPU: state.gpu,
-        SADDLE_MIG: state.mig,
-        HOSTNAME: state.hostname,
-        TERM: 'xterm-256color',
-        SHELL: '/bin/bash',
-        USER: 'root',
-        HOME: '/root',
-        PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
-        LANG: 'C.UTF-8',
-    };
-    return Object.keys(entries)
-        .sort()
-        .map((key) => `${key}=${entries[key]}`)
-        .join('\n');
-}
-/* ------------------------------------------------------------------ */
-/* context: virtualfs — the persistent workspace filesystem            */
-/* ------------------------------------------------------------------ */
-/** the default workspace quota mirrored from the api contract. */
-const defaultquota = 16 * 1024 * 1024;
-/** the per-session history cap shown by the history command. */
-const historycap = 50;
-/**
- * normalizes one workspace path: the working directory is always the
- * sandbox root, so relative names gain the leading slash, duplicated
- * slashes collapse, trailing slashes drop and any traversal attempt
- * ("..") or oversized path is rejected.
- *
- * @param {string} input the raw path typed by the user.
- * @returns {{ok: true, path: string} | {ok: false, error: string}} the verdict.
- */
-function normalizepath(input) {
-    const raw = String(input ?? '').trim();
-    if (raw.length === 0) {
-        return { ok: false, error: 'empty path' };
-    }
-    if (raw.includes('..')) {
-        return { ok: false, error: 'path traversal is not allowed' };
-    }
-    let path = raw.replace(/\/+/, '/');
-    if (!path.startsWith('/')) {
-        path = `/${path}`;
-    }
-    if (path.length > 1 && path.endsWith('/')) {
-        path = path.slice(0, -1);
-    }
-    if (path.length > 128) {
-        return { ok: false, error: 'path is too long (max 128 characters)' };
-    }
-    return { ok: true, path };
-}
-/**
- * builds the fallback filesystem for contexts without callbacks (the
- * browser terminal): a per-state map that lives exactly as long as the
- * sandbox session and mirrors the {write, read, list, del} contract.
- *
- * @param {object} state a state built by createsandboxstate.
- * @returns {{write: Function, read: Function, list: Function, del: Function}}
- *   the in-memory filesystem adapter.
- */
-function memoryfs(state) {
-    return {
-        write(path, content) {
-            const text = content === null || content === undefined ? '' : String(content);
-            const size = new TextEncoder().encode(text).length;
-            const updatedat = new Date().toISOString();
-            state.files.set(path, { content: text, size, updatedat });
-            return { path, size, updatedat };
-        },
-        read(path) {
-            const entry = state.files.get(path);
-            return entry === undefined ? null : { path, ...entry };
-        },
-        list() {
-            return [...state.files.entries()]
-                .map(([path, entry]) => ({ path, size: entry.size, updatedat: entry.updatedat }))
-                .sort((a, b) => (a.path < b.path ? -1 : 1));
-        },
-        del(path) {
-            return state.files.delete(path);
-        },
-    };
-}
-/**
- * renders one ls row in the long listing style with size and date.
- *
- * @param {{path: string, size: number, updatedat: string}} file the file row.
- * @returns {string} the formatted line.
- */
-function lsrow(file) {
-    const when = String(file.updatedat ?? '').slice(0, 16).replace('T', ' ');
-    return `-rw-r--r-- 1 root root ${padstart(String(file.size), 9)} ${when} ${file.path}`;
-}
-/** the short manual pages served by the man command. */
-const manualpages = {
-    streaming: 'streaming: shows the streaming memory plan - any workload size runs inside a small hot window (mmap layers, evict after last consumer)',
-    quantum: 'quantum: quantum layer summary - simulator, bb84, grover, dna vault, optical planner',
-    tiers: 'tiers: shows the layered virtual memory - l1 ram to l4 buckets, the free pool and the npm-as-disk farm',
-    touch: 'touch <file> - create an empty file in the persistent workspace (or refresh its timestamp)',
-    echo: 'echo <text> - print text; echo <text> > <file> writes and echo <text> >> <file> appends (stored verbatim, no implicit newline)',
-    cat: 'cat <file> - print one persistent workspace file (also /proc/cpuinfo and /proc/meminfo)',
-    ls: 'ls [path] - list the persistent workspace root with sizes and dates; ls /etc/virtual keeps the hardware table',
-    rm: 'rm <file> - delete one persistent workspace file',
-    df: 'df [-h] - workspace quota usage as a filesystem table; the quota is fixed per sandbox id',
-    stat: 'stat <file> - size and timestamps of one persistent workspace file',
-    pwd: 'pwd - print the working directory; the sandbox is always rooted at /',
-    history: 'history - the last 50 commands typed in this session',
-    man: 'man <command> - this short manual',
-};
-/**
- * dispatches one shell command against a sandbox state; the return shape
- * matches the api exec contract {output, exitCode}. the optional context
- * carries the persistent filesystem callbacks {write, read, list, del}
- * bound to the sandbox id by the api host; without a context the same
- * commands run on the per-session in-memory workspace so the browser
- * terminal keeps working unchanged.
- *
- * @param {string} command the raw command line typed by the user.
- * @param {object} state a state built by createsandboxstate.
- * @param {{fs?: {write: Function, read: Function, list: Function,
- *   del: Function}, quota?: number}} [context] the optional filesystem
- *   context provided by the api host.
- * @returns {{output: string, exitCode: number, clear?: boolean}} the result.
- */
-export function dispatch(command, state, context) {
-    const raw = String(command ?? '').trim();
-    if (raw.length === 0) {
-        return { output: '', exitCode: 0 };
-    }
-    try {
-        if (!Array.isArray(state.history)) {
-            state.history = [];
-        }
-        state.history.push(raw);
-        if (state.history.length > historycap) {
-            state.history.splice(0, state.history.length - historycap);
-        }
-    }
-    catch {
-        /* history is best effort; a frozen state must not break exec */
-    }
-    const fs = context?.fs ?? memoryfs(state);
-    const argv = raw.split(/\s+/);
-    const head = argv[0];
-    const rest = argv.slice(1).join(' ');
-    try {
-        /* echo is the one command with output redirection: the text is
-         * stored verbatim ("echo a > f" then "echo b >> f" yields "ab").
-         * The split is a linear scan off the last '>' — the lazy regex it
-         * replaces walked every boundary of a space run and the redos gate
-         * refused the polynomial detour: the operator is the last '>' doubled
-         * or single, the filename the single whitespace-free token after it
-         * and the command everything before the operator. */
-        const gt = raw.lastIndexOf('>');
-        let redirect = null;
-        if (gt >= 0) {
-            const file = raw.slice(gt + 1).trim();
-            if (file.length > 0 && !/\s/.test(file)) {
-                const doubled = gt > 0 && raw[gt - 1] === '>';
-                redirect = {
-                    command: raw.slice(0, doubled ? gt - 1 : gt).trim(),
-                    operator: doubled ? '>>' : '>',
-                    file,
-                };
-            }
-        }
-        if (redirect !== null) {
-            const commandpart = redirect.command;
-            const redirhead = commandpart.split(/\s+/)[0];
-            if (redirhead !== 'echo') {
-                return {
-                    output: `bash: output redirection is only supported for echo (got ${redirhead})`,
-                    exitCode: 1,
-                };
-            }
-            const text = commandpart.slice(redirhead.length).trim();
-            const norm = normalizepath(redirect.file);
-            if (!norm.ok) {
-                return { output: `bash: echo: ${redirect.file}: ${norm.error}`, exitCode: 1 };
-            }
-            try {
-                if (redirect.operator === '>>') {
-                    const existing = fs.read(norm.path);
-                    fs.write(norm.path, `${existing === null ? '' : existing.content}${text}`);
-                }
-                else {
-                    fs.write(norm.path, text);
-                }
-                return { output: '', exitCode: 0 };
-            }
-            catch (writeerror) {
-                return {
-                    output: `bash: echo: ${writeerror instanceof Error ? writeerror.message : String(writeerror)}`,
-                    exitCode: 1,
-                };
-            }
-        }
-        switch (head) {
-            case 'help':
-                return { output: `saddle sandbox commands:\n${helpText()}`, exitCode: 0 };
-            case 'lscpu':
-                return { output: lscpu(state.model, state.vcpus, 1), exitCode: 0 };
-            case 'cat': {
-                if (argv[1] === '/proc/cpuinfo') {
-                    return { output: cpuinfo(state.model, state.vcpus), exitCode: 0 };
-                }
-                if (argv[1] === '/proc/meminfo') {
-                    return { output: state.memsnapshot, exitCode: 0 };
-                }
-                if (argv[1] === undefined) {
-                    return { output: 'cat: missing file operand', exitCode: 1 };
-                }
-                const catnorm = normalizepath(argv[1]);
-                if (!catnorm.ok) {
-                    return { output: `cat: ${argv[1]}: ${catnorm.error}`, exitCode: 1 };
-                }
-                const catfile = fs.read(catnorm.path);
-                if (catfile === null) {
-                    return {
-                        output: `cat: ${argv[1]}: No such file or directory`,
-                        exitCode: 1,
-                    };
-                }
-                return { output: catfile.content, exitCode: 0 };
-            }
-            case 'free':
-                return { output: freeh(state.memsnapshot), exitCode: 0 };
-            case 'nvidia-smi':
-                if (argv[1] === '-L') {
-                    return { output: nvidiaSmiList(state.gpu, state.mig), exitCode: 0 };
-                }
-                return { output: nvidiaSmiTable(state.gpu, state.mig), exitCode: 0 };
-            case 'clinfo':
-                return { output: clinfoSummary(state.vcpus), exitCode: 0 };
-            case 'vulkaninfo':
-                return { output: vulkanSummary(), exitCode: 0 };
-            case 'glxinfo':
-                return { output: glxinfoSummary(), exitCode: 0 };
-            case 'uname':
-                return {
-                    output: `Linux ${state.hostname} ${state.kernel} #1 SMP PREEMPT_DYNAMIC ${state.cpuspec.arch === 'arm64' ? 'aarch64' : 'x86_64'} GNU/Linux`,
-                    exitCode: 0,
-                };
-            case 'ls': {
-                const target = argv[1] ?? '/';
-                if (target === '/etc/virtual') {
-                    return {
-                        output: [
-                            'boards.json    cores.json    gpus.json',
-                            'processors.json    virtualhardware.json    vm.config.json',
-                            'cpuinfo    meminfo    lscpu    nvidia-smi',
-                        ].join('\n'),
-                        exitCode: 0,
-                    };
-                }
-                const lsnorm = normalizepath(target);
-                if (!lsnorm.ok) {
-                    return { output: `ls: ${target}: ${lsnorm.error}`, exitCode: 2 };
-                }
-                const rows = fs.list().filter((entry) => lsnorm.path === '/' || entry.path === lsnorm.path);
-                if (rows.length === 0) {
-                    if (lsnorm.path !== '/') {
-                        return {
-                            output: `ls: cannot access '${target}': No such file or directory`,
-                            exitCode: 2,
-                        };
-                    }
-                    return { output: '', exitCode: 0 };
-                }
-                const blocks = Math.max(1, Math.ceil(rows.reduce((sum, row) => sum + row.size, 0) / 1024));
-                return {
-                    output: [`total ${blocks}`, ...rows.map(lsrow)].join('\n'),
-                    exitCode: 0,
-                };
-            }
-            case 'env':
-                return { output: envText(state), exitCode: 0 };
-            case 'docker':
-                return { output: 'Docker version 29.7.2, build 5ea4c1f', exitCode: 0 };
-            case 'qemu-system-x86_64':
-                return {
-                    output: [
-                        'QEMU emulator version 11.1.0 (saddle bridge)',
-                        'Copyright (c) 2003-2026 Fabrice Bellard and the QEMU Project developers',
-                    ].join('\n'),
-                    exitCode: 0,
-                };
-            case 'uptime':
-                return { output: uptimeLine(state), exitCode: 0 };
-            case 'whoami':
-                return { output: 'root', exitCode: 0 };
-            case 'neofetch':
-                return { output: neofetch(state), exitCode: 0 };
-            case 'echo':
-                return { output: rest, exitCode: 0 };
-            case 'touch': {
-                if (argv[1] === undefined) {
-                    return { output: 'touch: missing file operand', exitCode: 1 };
-                }
-                const touchnorm = normalizepath(argv[1]);
-                if (!touchnorm.ok) {
-                    return { output: `touch: ${argv[1]}: ${touchnorm.error}`, exitCode: 1 };
-                }
-                try {
-                    const existing = fs.read(touchnorm.path);
-                    fs.write(touchnorm.path, existing === null ? '' : existing.content);
-                    return { output: '', exitCode: 0 };
-                }
-                catch (toucherror) {
-                    return {
-                        output: `touch: ${toucherror instanceof Error ? toucherror.message : String(toucherror)}`,
-                        exitCode: 1,
-                    };
-                }
-            }
-            case 'rm': {
-                if (argv[1] === undefined) {
-                    return { output: 'rm: missing operand', exitCode: 1 };
-                }
-                const rmnorm = normalizepath(argv[1]);
-                if (!rmnorm.ok) {
-                    return { output: `rm: ${argv[1]}: ${rmnorm.error}`, exitCode: 1 };
-                }
-                try {
-                    const removed = fs.del(rmnorm.path);
-                    if (!removed) {
-                        return {
-                            output: `rm: cannot remove '${argv[1]}': No such file or directory`,
-                            exitCode: 1,
-                        };
-                    }
-                    return { output: '', exitCode: 0 };
-                }
-                catch (rmerror) {
-                    return {
-                        output: `rm: ${rmerror instanceof Error ? rmerror.message : String(rmerror)}`,
-                        exitCode: 1,
-                    };
-                }
-            }
-            case 'quantum':
-                return { output: quantumdemo(), exitCode: 0 };
-            case 'tiers':
-                return { output: tiersdemo(), exitCode: 0 };
-            case 'streaming':
-                return { output: streamingdemo(), exitCode: 0 };
-            case 'df': {
-                const rows = fs.list();
-                const used = rows.reduce((sum, row) => sum + row.size, 0);
-                const quota = Number(context?.quota ?? defaultquota);
-                const avail = Math.max(0, quota - used);
-                const percent = quota > 0 ? Math.min(100, Math.floor((used / quota) * 100)) : 0;
-                const col = (text, width) => padstart(String(text), width);
-                return {
-                    output: [
-                        `Filesystem ${col('Size', 10)}${col('Used', 10)}${col('Avail', 10)}${col('Use%', 6)} Mounted on`,
-                        `${pad(state.id, 11)}${col(humanbytes(quota), 10)}${col(humanbytes(used), 10)}${col(humanbytes(avail), 10)}${col(`${percent}%`, 6)} /`,
-                    ].join('\n'),
-                    exitCode: 0,
-                };
-            }
-            case 'stat': {
-                if (argv[1] === undefined) {
-                    return { output: 'stat: missing operand', exitCode: 1 };
-                }
-                const statnorm = normalizepath(argv[1]);
-                if (!statnorm.ok) {
-                    return { output: `stat: ${argv[1]}: ${statnorm.error}`, exitCode: 1 };
-                }
-                const file = fs.read(statnorm.path);
-                if (file === null) {
-                    return {
-                        output: `stat: cannot stat '${argv[1]}': No such file or directory`,
-                        exitCode: 1,
-                    };
-                }
-                return {
-                    output: [
-                        `  File: ${file.path ?? statnorm.path}`,
-                        `  Size: ${padstart(String(file.size), 10)}\tBlocks: ${padstart(String(Math.ceil(file.size / 512)), 6)}          IO Block: 4096   regular file`,
-                        `Device: saddle/virtual\tInode: ${padstart(String(state.files instanceof Map ? state.files.size + 1 : 1), 12)}   Links: 1`,
-                        `Modify: ${file.updatedat}`,
-                    ].join('\n'),
-                    exitCode: 0,
-                };
-            }
-            case 'pwd':
-                return { output: '/', exitCode: 0 };
-            case 'history': {
-                const lines = (Array.isArray(state.history) ? state.history : [])
-                    .map((entry, index) => `${padstart(String(index + 1), 5)}  ${entry}`);
-                return { output: lines.join('\n'), exitCode: 0 };
-            }
-            case 'man': {
-                const topic = argv[1];
-                if (topic === undefined) {
-                    return { output: 'What manual page do you want?', exitCode: 1 };
-                }
-                const page = manualpages[topic];
-                if (page === undefined) {
-                    return { output: `man: no manual for ${topic} (try: ${Object.keys(manualpages).join(', ')})`, exitCode: 1 };
-                }
-                return { output: `${topic.toUpperCase()}(1)\n\n  ${page}`, exitCode: 0 };
-            }
-            case 'clear':
-                return { output: '', exitCode: 0, clear: true };
-            default:
-                return {
-                    output: `bash: ${head}: command not found (try "help")`,
-                    exitCode: 127,
-                };
-        }
-    }
-    catch (error) {
-        return {
-            output: `bash: ${head}: engine error: ${error instanceof Error ? error.message : String(error)}`,
-            exitCode: 1,
-        };
-    }
-}
-/**
- * renders the streaming plan for a workload larger than any host: the
- * demo the terminal shows for "how does a 1.5 tb model run here" - layers
- * stream through a fixed window, the workload size is unbounded.
- * @param {number} totalbytes workload size in bytes.
- * @param {number} windowbytes hot-set budget in bytes.
- * @returns {string} the plan summary lines.
- */
-/**
- * renders the layered virtual memory architecture: everything is vram and
- * the only physical layer is the free pool (github, npm cdn and friends -
- * the saddle storage doctrine applied to this engine).
- * @returns {string} the tier summary lines.
- */
-/**
- * renders the quantum layer summary: a classical statevector simulator
- * (1-20 qubits), the bb84/e91 key exchange, grover search, dna and 5d
- * optical storage planners - every "quantum" capability is software.
- * @returns {string} the quantum summary lines.
- */
-export function quantumdemo() {
-    return [
-        'saddle quantum layer (100 percent classical simulation)',
-        '  simulator   statevector, float64 interleaved re/im, 1-20 qubits',
-        '  gates       h x y z s t rx ry rz cnot cz toffoli swap',
-        '  algorithms  bellstate, ghz, grover2 (provable), grover3, deutsch, teleport',
-        '  protocols   bb84 (1984) with intercept-resend detection, e91 (1991) + chsh',
-        '  randomness  quantum-inspired (csprng) with honest anu qrng fallback note',
-        '  storage     dna vault (goldman 2013, 215 pb/g, 4 strands, roundtrip proven)',
-        '              5d quartz planner (360 tb/disc, 13.8 billion years at room)',
-        '              qram bucket-brigade model (giovannetti prl 2008)',
-        '  engine: import { quantumsim, runbb84, dnavaultencode } from ./quantum',
-    ].join('\n');
-}
-export function tiersdemo() {
-    const ladder = ['ram ~100ns', 'zram ~500ns', 'tmpfs ~1us', 'mmap ~5us', 'sqlite ~10us', 'r2 ~50us'];
-    return [
-        'saddle tiered virtual memory (everything is vram)',
-        '  l1 ram      working set, ephemeral            ~100 ns',
-        '  l2 vram     compute-bound identity layer       spoofed',
-        '  l3 storage  repos as ram (sqlite kv, lru)     ~10 us',
-        '  l4 buckets  hf 10tb + kaggle 20tb + terabox   ~50 us',
-        '  physical    github artifacts + ghcr + npm cdn (the only disks)',
-        `  ladder      ${ladder.join(' | ')}`,
-        '  autoscale   <64mb memfs / <1gb mmap / larger sqlite+r2',
-        '  pool        >33 tb free across accounts (see tiers.ts FREEPOOL)',
-        '  npm-as-disk 200 mb chunks as .bin.js packages on the cdn farm',
-        '  vdr         64-bit bigint addressing up to 9.22 eb',
-        '  engine: import { creatiersengine } from the package (./tiers)',
-    ].join('\n');
-}
-export function streamingdemo(totalbytes = 1649267441664, windowbytes = 4 * 1024 * 1024 * 1024) {
-    const layerbytes = 512 * 1024 * 1024;
-    const count = Math.ceil(totalbytes / layerbytes);
-    const batches = Math.ceil(count / Math.max(1, Math.floor(windowbytes / layerbytes)));
-    const fmt = (b) => (b >= 1024 ** 4 ? (b / 1024 ** 4).toFixed(2) + ' TB' : (b / 1024 ** 3).toFixed(1) + ' GB');
-    return [
-        'saddle streaming memory plan',
-        `  workload:  ${fmt(totalbytes)} decomposed into ${count} layers of ${layerbytes / 1024 ** 2} MiB`,
-        `  window:    ${fmt(windowbytes)} hot-set budget (peak resident)`,
-        `  batches:   ${batches} load/run/evict passes over the weights`,
-        '  technique: mmap + page cache streams each layer on demand; eviction',
-        '             after the last consumer keeps the resident set inside the',
-        '             window - the workload size is unbounded, only the window',
-        '             is fixed. this is how engines run models larger than ram.',
-    ].join('\n');
-}