@wenathlan/saddle 2.0.151 → 2.0.152

package/dist/runall.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/runall.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WS_ROOT = join(__dirname, '.');
+let passed = 0;
+let failed = 0;
+async function run(label, cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        console.log(`\n── ${label} ──\n`);
+        const proc = spawn(cmd, args, {
+            cwd: WS_ROOT,
+            stdio: ['ignore', 'inherit', 'inherit'],
+            env: { ...process.env },
+            ...opts,
+        });
+        proc.on('close', (code) => {
+            if (code === 0)
+                passed++;
+            else
+                failed++;
+            resolve(code === 0);
+        });
+    });
+}
+console.log('='.repeat(55));
+console.log('  DevThink Saddle — the sandbox engine test runner');
+console.log('='.repeat(55));
+console.log(`  CWD: ${WS_ROOT}`);
+console.log('='.repeat(55));
+const start = Date.now();
+await run('Vitest (the engine suites)', 'npx', ['vitest', 'run']);
+const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+console.log();
+console.log('='.repeat(55));
+console.log(`  Results: ${passed} passed, ${failed} failed, ${elapsed}s`);
+console.log('='.repeat(55));
+process.exit(failed > 0 ? 1 : 0);

package/dist/runtimeprobe.d.ts

@@ -0,0 +1,4 @@
+/**
+ * runtime probe exercises only root-safe contracts and produces serializable evidence for CI matrices.
+ */
+export {};

package/dist/runtimeprobe.js

@@ -0,0 +1,8 @@
+/**
+ * runtime probe exercises only root-safe contracts and produces serializable evidence for CI matrices.
+ */
+import { memorystorage, runtimecontract, sha256 } from "./dist/index.js";
+const storage = memorystorage({ maxbytes: 1024 });
+await storage.put({ key: "probe.txt", data: new TextEncoder().encode("saddle") });
+const value = await storage.get("probe.txt");
+console.log(JSON.stringify({ contract: runtimecontract(), digest: sha256("saddle"), text: new TextDecoder().decode(value), head: await storage.head("probe.txt") }));

package/dist/sandbox.d.ts

@@ -0,0 +1,355 @@
+/**
+ * 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.
+ */
+/** reviewed processor catalog entry (mirrors the vendor pages). */
+export type CpuSpec = {
+    model: string;
+    displayname: string;
+    vendor: string;
+    arch: string;
+    cores: number;
+    threads: number;
+    baseclockmhz: number;
+    boostclockmhz: number;
+    allcoreclockmhz: number;
+    l3mb: number;
+    l2mb: number;
+    socket: string;
+    tdpwatts: number;
+    pcie: string;
+    maxmemorygb: number;
+    memorytype: string;
+    memorychannels: number;
+    microarch: string;
+    cpufamily: number;
+    cpumodel: number;
+    stepping: number;
+    physicalline: string;
+    virtualline: string;
+    launch: string;
+};
+/** reviewed virtual gpu catalog entry. */
+export type GpuSpec = {
+    id: string;
+    name: string;
+    vendor: string;
+    pcivendor: string;
+    pcidevice: string;
+    vrammib: number;
+    smireportedmib: number;
+    memtype: string;
+    busbits: number;
+    bandwidthgbs: number;
+    tdpwatts: number;
+    arch: string;
+    smarch: string;
+    smcount: number;
+    mig: boolean;
+    driver: string;
+    cuda: string | null;
+};
+/** one mig slicing profile of the 96 gb-class device. */
+export type MigProfile = {
+    id: string;
+    slicegb: number;
+    maxinstances: number;
+};
+/** sandbox specification accepted by createSandboxState. */
+export type SandboxSpec = {
+    model: string;
+    vcpus?: number;
+    ramgb?: number;
+    gpu: string;
+    mig?: string;
+    id?: string;
+};
+/** resolved smp topology for a virtual cpu spec. */
+export type CpuTopology = {
+    threadspercore: number;
+    coresonline: number;
+    vcpus: number;
+    siblings: number;
+    sockets: number;
+    fullypopulated: boolean;
+};
+/** one persistent workspace file entry. */
+export type SandboxFile = {
+    content: string;
+    size: number;
+    updatedat: string;
+};
+/** the filesystem contract shared by the api host and the memoryfs. */
+export type SandboxFs = {
+    write: (path: string, content: string) => {
+        path: string;
+        size: number;
+        updatedat: string;
+    };
+    read: (path: string) => (SandboxFile & {
+        path: string;
+    }) | null;
+    list: () => Array<{
+        path: string;
+        size: number;
+        updatedat: string;
+    }>;
+    del: (path: string) => boolean;
+};
+/** state object shared by the browser terminal and the api exec endpoint. */
+export type SandboxState = {
+    model: string;
+    cpuspec: CpuSpec;
+    gpuspec: GpuSpec;
+    vcpus: number;
+    ramgb: number;
+    gpu: string;
+    mig: string;
+    id: string;
+    hostname: string;
+    boottime: number;
+    kernel: string;
+    memsnapshot: string;
+    history: string[];
+    files: Map<string, SandboxFile>;
+};
+/** command result matching the api exec contract; clear is set by the
+ * clear command so the terminal can wipe the screen. */
+export type DispatchResult = {
+    output: string;
+    exitCode: number;
+    clear?: boolean;
+};
+/** optional exec context provided by the api host. */
+export type DispatchContext = {
+    fs?: SandboxFs;
+    quota?: number;
+};
+/**
+ * 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 declare const cpudata: CpuSpec[];
+/** resolves a processor spec by model name, case-insensitive; returns
+ * undefined for unknown models so callers can shape friendly errors. */
+export declare function getcpu(model: string): CpuSpec | undefined;
+/**
+ * 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 declare function getcpubyid(id: string): CpuSpec | undefined;
+/**
+ * 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 declare function solvetopology(spec: CpuSpec, vcpus: number): CpuTopology;
+/**
+ * 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 declare function cpuinfo(model: string, vcpus: number): string;
+/**
+ * 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 declare function lscpu(model: string, vcpus: number, numanodes?: number): string;
+/**
+ * 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 declare const gpudata: GpuSpec[];
+/** resolves a gpu spec by id or name, case-insensitive. */
+export declare function getgpu(gpu: string): GpuSpec | undefined;
+/**
+ * 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 declare const migprofiles: MigProfile[];
+/** resolves a mig profile by id; null for 'off' and unknown names. */
+export declare function getmig(id: string | null | undefined): MigProfile | null;
+/** rounds a kb value down to the nearest 4 kb page boundary. */
+export declare function pagealign(kb: number): number;
+/**
+ * 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 declare function meminfo(ramgb: number, options?: {
+    swapgb?: number;
+    vcpus?: number;
+    freefraction?: number;
+    availablefraction?: number;
+}): string;
+/**
+ * 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 declare function freeh(meminfotext: string): string;
+/**
+ * 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 declare function nvidiaSmiTable(gpu: string, migprofile?: string): string;
+/**
+ * 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 declare function nvidiaSmiList(gpu: string, migprofile?: string): string;
+/**
+ * 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 declare function clinfoSummary(vcpus?: number): string;
+/**
+ * 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 declare function vulkanSummary(): string;
+/**
+ * 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 declare function glxinfoSummary(): string;
+/**
+ * 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 declare function mesaenv(vcpus?: number): Record<string, string>;
+/**
+ * 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 declare function bootSequence(model: string, vcpus: number, ramgb?: number, gpu?: string, quota?: number): string[];
+/**
+ * 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 declare function createSandboxState(spec: SandboxSpec): SandboxState;
+/** the supported command list, reused by help and the terminal. */
+export declare const commands: string[];
+/**
+ * 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 declare function dispatch(command: string, state: SandboxState, context?: DispatchContext): DispatchResult;
+/**
+ * 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 declare function quantumdemo(): string;
+export declare function tiersdemo(): string;
+export declare function streamingdemo(totalbytes?: number, windowbytes?: number): string;