@wenathlan/saddle 2.0.168 → 2.0.171

package/Dockerfile

@@ -1,4 +1,4 @@
-# saddle 2.0.168 — THE ENGINE CONTAINER FILE
+# saddle 2.0.171 — THE ENGINE CONTAINER FILE
 #
 # THE FAMILY CONTAINER DOCTRINE, THE SADDLE SHAPE: one versioned container
 # per engine, built like the site homes (argan, cadria) build theirs — a
@@ -158,7 +158,7 @@ ARG NODE_BASE_DIGEST=5adad64f9a1fca2d51972caa65983634c8a774eb300d72b20f7f2a0f603
 # ===== stage: solbuild — the locked npm tree and the console spa =====
 FROM --platform=$BUILDPLATFORM ${NODE_BASE_TAG}@sha256:${NODE_BASE_DIGEST} AS solbuild
 
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 
 WORKDIR /app
 
@@ -192,7 +192,7 @@ RUN npm run web:build:pages \
 # ===== stage: base — the hardened runtime floor every profile shares =====
 FROM ${NODE_BASE_TAG}@sha256:${NODE_BASE_DIGEST} AS base
 
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 # the revision stamp the devthink container carries (DEVTHINK_REVISION
 # there): the publish legs pass the release sha at build time and the
 # revision label below declares the default-unknown local shape.
@@ -261,6 +261,20 @@ RUN case "${TARGETARCH:-}" in \
     esac
 
 COPY --from=solbuild /app/package.json /app/package-lock.json ./
+# the both-blocks grammar heal (the saddle container law): the family
+# manifest carries the same seats inside dependencies and
+# devDependencies, and every npm tested (11.19.1 and 12.0.2) answers
+# that duplicate seat by planting dev:true over the whole lock tree -
+# so a plain `npm ci --omit=dev` installs nothing and the runtime stage
+# dies at the cleanup walk with no node_modules to sweep. The derived
+# prod-only manifest (the dependencies block alone, byte-identical
+# specs) restores the honest production install: the lock the
+# foundry/lockprod.ts heal stamped walks beside it and the --omit=dev
+# lane lands the full production closure (the 1372-package install the
+# local verification measured). Nothing is removed - the dev seats stay
+# in the lock for the full-install lanes, only the runtime's own view
+# of the manifest narrows.
+RUN node -e "const fs=require('node:fs');const m=JSON.parse(fs.readFileSync('package.json','utf8'));delete m.devDependencies;fs.writeFileSync('package.json',JSON.stringify(m,null,2)+'\n')"
 RUN apt-get update \
     && apt-get upgrade -y \
     && rm -rf /var/lib/apt/lists/* \
@@ -495,7 +509,7 @@ LABEL org.opencontainers.image.title="saddle (the android os-distribution lane)"
 #   docker build --target osv          -t saddle:2.0.165-v .
 #   docker build --target oswindows    -t saddle:2.0.165-windows .
 FROM scratch AS osgrapheneos
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="grapheneos"
 ENV SADDLE_OS_PROFILE=grapheneos
 LABEL org.opencontainers.image.title="saddle (the grapheneos os-distribution catalog lane)" \
@@ -506,7 +520,7 @@ LABEL org.opencontainers.image.title="saddle (the grapheneos os-distribution cat
 COPY osprofiles/grapheneos.json /saddle/osprofile.json
 
 FROM scratch AS osmaruos
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="maruos"
 ENV SADDLE_OS_PROFILE=maruos
 LABEL org.opencontainers.image.title="saddle (the maru os os-distribution catalog lane)" \
@@ -517,7 +531,7 @@ LABEL org.opencontainers.image.title="saddle (the maru os os-distribution catalo
 COPY osprofiles/maruos.json /saddle/osprofile.json
 
 FROM scratch AS osv
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="v"
 ENV SADDLE_OS_PROFILE=v
 LABEL org.opencontainers.image.title="saddle (the v os-distribution catalog lane)" \
@@ -528,7 +542,7 @@ LABEL org.opencontainers.image.title="saddle (the v os-distribution catalog lane
 COPY osprofiles/v.json /saddle/osprofile.json
 
 FROM scratch AS oswindows
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="windows"
 ENV SADDLE_OS_PROFILE=windows
 LABEL org.opencontainers.image.title="saddle (the windows os-distribution catalog lane)" \
@@ -539,7 +553,7 @@ LABEL org.opencontainers.image.title="saddle (the windows os-distribution catalo
 COPY osprofiles/windows.json /saddle/osprofile.json
 
 FROM scratch AS ospostmarketos
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="postmarketos"
 ENV SADDLE_OS_PROFILE=postmarketos
 LABEL org.opencontainers.image.title="saddle (the postmarketos os-distribution catalog lane)" \
@@ -550,7 +564,7 @@ LABEL org.opencontainers.image.title="saddle (the postmarketos os-distribution c
 COPY osprofiles/postmarketos.json /saddle/osprofile.json
 
 FROM scratch AS oslineageos
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="lineageos"
 ENV SADDLE_OS_PROFILE=lineageos
 LABEL org.opencontainers.image.title="saddle (the lineageos os-distribution catalog lane)" \
@@ -561,7 +575,7 @@ LABEL org.opencontainers.image.title="saddle (the lineageos os-distribution cata
 COPY osprofiles/lineageos.json /saddle/osprofile.json
 
 FROM scratch AS oscalyxos
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="calyxos"
 ENV SADDLE_OS_PROFILE=calyxos
 LABEL org.opencontainers.image.title="saddle (the calyxos os-distribution catalog lane)" \
@@ -572,7 +586,7 @@ LABEL org.opencontainers.image.title="saddle (the calyxos os-distribution catalo
 COPY osprofiles/calyxos.json /saddle/osprofile.json
 
 FROM scratch AS osarchlinux
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="archlinux"
 ENV SADDLE_OS_PROFILE=archlinux
 LABEL org.opencontainers.image.title="saddle (the archlinux os-distribution catalog lane)" \
@@ -583,7 +597,7 @@ LABEL org.opencontainers.image.title="saddle (the archlinux os-distribution cata
 COPY osprofiles/archlinux.json /saddle/osprofile.json
 
 FROM scratch AS osalpine
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="alpine"
 ENV SADDLE_OS_PROFILE=alpine
 LABEL org.opencontainers.image.title="saddle (the alpine os-distribution catalog lane)" \
@@ -594,7 +608,7 @@ LABEL org.opencontainers.image.title="saddle (the alpine os-distribution catalog
 COPY osprofiles/alpine.json /saddle/osprofile.json
 
 FROM scratch AS osdebian
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="debian"
 ENV SADDLE_OS_PROFILE=debian
 LABEL org.opencontainers.image.title="saddle (the debian os-distribution catalog lane)" \
@@ -605,7 +619,7 @@ LABEL org.opencontainers.image.title="saddle (the debian os-distribution catalog
 COPY osprofiles/debian.json /saddle/osprofile.json
 
 FROM scratch AS osfedora
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="fedora"
 ENV SADDLE_OS_PROFILE=fedora
 LABEL org.opencontainers.image.title="saddle (the fedora os-distribution catalog lane)" \
@@ -616,7 +630,7 @@ LABEL org.opencontainers.image.title="saddle (the fedora os-distribution catalog
 COPY osprofiles/fedora.json /saddle/osprofile.json
 
 FROM scratch AS osnixos
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="nixos"
 ENV SADDLE_OS_PROFILE=nixos
 LABEL org.opencontainers.image.title="saddle (the nixos os-distribution catalog lane)" \
@@ -627,7 +641,7 @@ LABEL org.opencontainers.image.title="saddle (the nixos os-distribution catalog
 COPY osprofiles/nixos.json /saddle/osprofile.json
 
 FROM scratch AS osvoid
-ARG SADDLE_VERSION=2.0.168
+ARG SADDLE_VERSION=2.0.171
 ARG SADDLE_OS_PROFILE="void"
 ENV SADDLE_OS_PROFILE=void
 LABEL org.opencontainers.image.title="saddle (the void os-distribution catalog lane)" \

package/README.md

@@ -31,7 +31,7 @@ domain modules land beside the saddle domains:
 | `media.ts`, `render.ts`, `quantum.ts`, `tiers.ts` | media pipeline, GPU registry, quantum simulation, tier policy |
 | `security.ts`, `alternatives.ts` | hardening gates and the alternative-stack catalog |
 | `index.html`, `App.tsx`, `sol/` | the single SPA shell and the Sol theme (one tsx app with one stylesheet per theme) |
-| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.168 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
+| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.171 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
 | `vercel.json`, `netlify.toml` | the platform deploy adapters beside the surface they publish (the caddy ghost stays out of the tree) |
 | `specs/*` package exports | processors, gpus, cores, boards and the qemu/mttg/passage/docker envelopes |
 

package/docker.config

@@ -2,7 +2,7 @@
   "meta": {
     "name": "docker.config",
     "title": "saddle - Docker Engine and Containerization Configuration",
-    "version": "2.0.167",
+    "version": "2.0.171",
     "date": "2026-11-06",
     "language": "en",
     "sources": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "2.0.168",
+  "version": "2.0.171",
   "private": false,
   "description": "binary computing engine that turns distributed storage into a publishable working set carrying the merged virtual-hardware engine (the saddle + e2ugh grand merge)",
   "license": "GPL-3.0-only",
@@ -48,9 +48,9 @@
     "vm:create": "node --import tsx ./cli.ts vm",
     "vm:validate": "node --import tsx ./cli.ts vmlint",
     "gpu:list": "node --import tsx ./cli.ts gpus",
-    "docker:build": "docker build -f Dockerfile -t saddle:2.0.168 ..",
-    "docker:run": "docker run --rm --memory-swap=-1 --shm-size=2g saddle:2.0.168",
-    "docker:health": "docker run --rm -d --name saddle-health -p 8080:8080 saddle:2.0.168 >/dev/null && sleep 5; curl -fsS http://localhost:8080/api/v1/health || true; docker rm -f saddle-health >/dev/null 2>&1 || true",
+    "docker:build": "docker build -f Dockerfile -t saddle:2.0.171 ..",
+    "docker:run": "docker run --rm --memory-swap=-1 --shm-size=2g saddle:2.0.171",
+    "docker:health": "docker run --rm -d --name saddle-health -p 8080:8080 saddle:2.0.171 >/dev/null && sleep 5; curl -fsS http://localhost:8080/api/v1/health || true; docker rm -f saddle-health >/dev/null 2>&1 || true",
     "firecracker:boot": "firecracker --api-sock /tmp/fc-saddle.sock --config-file vmconfig.json 2>/dev/null || echo 'firecracker 1.16.1 warm-pool boot 125ms target'",
     "py:bridge": "python3 qemubridge.py",
     "py:test": "python3 -m pytest -q || python3 qemubridge.py",
@@ -131,13 +131,13 @@
     "@types/react-dom": "^19.3.0",
     "@types/three": "^0.187.0",
     "@vitejs/plugin-react": "^6.2.1",
-    "@wenathlan/argan": "~2.0.167",
-    "@wenathlan/cadria": "~2.0.167",
-    "@wenathlan/debonair": "~2.0.167",
-    "@wenathlan/devthink": "~2.0.167",
-    "@wenathlan/getry": "~2.0.167",
-    "@wenathlan/saddle": "~2.0.167",
-    "@wenathlan/vault": "~2.0.167",
+    "@wenathlan/argan": "~2.0.168",
+    "@wenathlan/cadria": "~2.0.168",
+    "@wenathlan/debonair": "~2.0.168",
+    "@wenathlan/devthink": "~2.0.168",
+    "@wenathlan/getry": "~2.0.168",
+    "@wenathlan/saddle": "~2.0.168",
+    "@wenathlan/vault": "~2.0.168",
     "add": "^2.0.9",
     "ai": "^7.0.165",
     "autoprefixer": "^10.6.2",
@@ -164,7 +164,7 @@
     "express": "^5.3.0",
     "fast-check": "^4.10.2",
     "fast-uri": "^4.2.3",
-    "follow-redirects": "^1.16.2",
+    "follow-redirects": "^1.16.3",
     "framer-motion": "^14.10.1",
     "glob": "^14.0.4",
     "gsap": "^3.15.1",
@@ -188,7 +188,7 @@
     "playwright": "^1.65.0",
     "pnpm": "^12.18.0",
     "postcss": "^8.5.32",
-    "postcss-selector-parser": "^7.1.7",
+    "postcss-selector-parser": "^7.1.8",
     "prettier": "^3.9.10",
     "prisma": "^7.10.1",
     "proxy-addr": "^2.0.8",
@@ -198,7 +198,7 @@
     "react-dom": "^19.3.1",
     "react-hook-form": "^7.91.0",
     "react-markdown": "^10.1.0",
-    "react-resizable-panels": "^4.19.1",
+    "react-resizable-panels": "^4.20.0",
     "react-syntax-highlighter": "^16.1.2",
     "recharts": "^3.10.1",
     "request-ip": "^3.3.0",
@@ -304,13 +304,13 @@
     "@types/react-dom": "^19.3.0",
     "@types/three": "^0.187.0",
     "@vitejs/plugin-react": "^6.2.1",
-    "@wenathlan/argan": "~2.0.167",
-    "@wenathlan/cadria": "~2.0.167",
-    "@wenathlan/debonair": "~2.0.167",
-    "@wenathlan/devthink": "~2.0.167",
-    "@wenathlan/getry": "~2.0.167",
-    "@wenathlan/saddle": "~2.0.167",
-    "@wenathlan/vault": "~2.0.167",
+    "@wenathlan/argan": "~2.0.168",
+    "@wenathlan/cadria": "~2.0.168",
+    "@wenathlan/debonair": "~2.0.168",
+    "@wenathlan/devthink": "~2.0.168",
+    "@wenathlan/getry": "~2.0.168",
+    "@wenathlan/saddle": "~2.0.168",
+    "@wenathlan/vault": "~2.0.168",
     "add": "^2.0.9",
     "ai": "^7.0.165",
     "autoprefixer": "^10.6.2",
@@ -337,7 +337,7 @@
     "express": "^5.3.0",
     "fast-check": "^4.10.2",
     "fast-uri": "^4.2.3",
-    "follow-redirects": "^1.16.2",
+    "follow-redirects": "^1.16.3",
     "framer-motion": "^14.10.1",
     "glob": "^14.0.4",
     "gsap": "^3.15.1",
@@ -361,7 +361,7 @@
     "playwright": "^1.65.0",
     "pnpm": "^12.18.0",
     "postcss": "^8.5.32",
-    "postcss-selector-parser": "^7.1.7",
+    "postcss-selector-parser": "^7.1.8",
     "prettier": "^3.9.10",
     "prisma": "^7.10.1",
     "proxy-addr": "^2.0.8",
@@ -371,7 +371,7 @@
     "react-dom": "^19.3.1",
     "react-hook-form": "^7.91.0",
     "react-markdown": "^10.1.0",
-    "react-resizable-panels": "^4.19.1",
+    "react-resizable-panels": "^4.20.0",
     "react-syntax-highlighter": "^16.1.2",
     "recharts": "^3.10.1",
     "request-ip": "^3.3.0",
@@ -477,13 +477,13 @@
     "@types/react-dom": "^19.3.0",
     "@types/three": "^0.187.0",
     "@vitejs/plugin-react": "^6.2.1",
-    "@wenathlan/argan": "~2.0.167",
-    "@wenathlan/cadria": "~2.0.167",
-    "@wenathlan/debonair": "~2.0.167",
-    "@wenathlan/devthink": "~2.0.167",
-    "@wenathlan/getry": "~2.0.167",
-    "@wenathlan/saddle": "~2.0.167",
-    "@wenathlan/vault": "~2.0.167",
+    "@wenathlan/argan": "~2.0.168",
+    "@wenathlan/cadria": "~2.0.168",
+    "@wenathlan/debonair": "~2.0.168",
+    "@wenathlan/devthink": "~2.0.168",
+    "@wenathlan/getry": "~2.0.168",
+    "@wenathlan/saddle": "~2.0.168",
+    "@wenathlan/vault": "~2.0.168",
     "add": "^2.0.9",
     "ai": "^7.0.165",
     "autoprefixer": "^10.6.2",
@@ -510,7 +510,7 @@
     "express": "^5.3.0",
     "fast-check": "^4.10.2",
     "fast-uri": "^4.2.3",
-    "follow-redirects": "^1.16.2",
+    "follow-redirects": "^1.16.3",
     "framer-motion": "^14.10.1",
     "glob": "^14.0.4",
     "gsap": "^3.15.1",
@@ -534,7 +534,7 @@
     "playwright": "^1.65.0",
     "pnpm": "^12.18.0",
     "postcss": "^8.5.32",
-    "postcss-selector-parser": "^7.1.7",
+    "postcss-selector-parser": "^7.1.8",
     "prettier": "^3.9.10",
     "prisma": "^7.10.1",
     "proxy-addr": "^2.0.8",
@@ -544,7 +544,7 @@
     "react-dom": "^19.3.1",
     "react-hook-form": "^7.91.0",
     "react-markdown": "^10.1.0",
-    "react-resizable-panels": "^4.19.1",
+    "react-resizable-panels": "^4.20.0",
     "react-syntax-highlighter": "^16.1.2",
     "recharts": "^3.10.1",
     "request-ip": "^3.3.0",
@@ -657,6 +657,7 @@
     "sandbox.ts",
     "modalityregistry.ts",
     "modalities.ts",
+    "vmcore.ts",
     "workloadlaw.ts",
     "browser.ts",
     "server.ts",
@@ -697,5 +698,6 @@
     "quantum.ts"
   ],
   "main": "./index.ts",
-  "types": "./index.ts"
+  "types": "./index.ts",
+  "optionalDependencies": {}
 }

package/vmcore.ts

@@ -0,0 +1,581 @@
+// # vmcore.ts — the real machine core of the vm lane: an rv64im
+// interpreter in typescript, the honest node-first implementation of the
+// qemu-style seats (the tcg seat, the microvm seats and the machine
+// seats execute real risc-v 64 machine code in-process when the host
+// carries no qemu — the engine never pretends a boot it cannot run).
+//
+// THE REAL CORE LAW: this file decodes and executes real machine code —
+// every fetch reads the memory image, every decode resolves the opcode
+// the silicon resolves (rvc is out: the plain 32-bit encoding only),
+// every execute writes the architectural state the isa pins (x0 hard
+// wired to zero, 64-bit registers carried as bigint so the full
+// rv64 arithmetic stays exact past the js number precision wall, the
+// w instructions wrap at 32 bits the way the isa wraps them). no step
+// is skipped, no result is canned: an illegal instruction traps with
+// the honest code, an unsupported ecall refuses with the honest code,
+// and the run answers the real exit code the program asked for.
+//
+// THE EXIT CONVENTION (the linux risc-v convention): the ecall
+// instruction with a7 (x17) = 93 terminates the machine and the exit
+// code is a0 (x10) — the same convention the linux risc-v kernel pins;
+// every other ecall number answers the honest refusal (the core
+// implements the exit door alone, never a pretend syscall surface).
+// ebreak traps with the break code (exit -7, the sigtrap convention).
+//
+// THE LOADER LAW: a payload that sniffs elf loads for real — the
+// elf64 little-endian header is parsed, every p_load segment maps at
+// its p_vaddr (filesz bytes copied, memsz zero-filled), the entry
+// point answers e_entry; a payload that is not elf maps raw at base
+// zero with entry zero (the bare-metal convention); both loads bounds
+// check against the memory image and refuse an out-of-image mapping.
+//
+// Pure typescript, zero host imports at load: the sha256 the run
+// digest rides lazy node:crypto inside the executor (the browser-pure
+// bundle keeps carrying the table).
+//
+// @module saddle/vmcore
+// @family wave/saddlepr15
+// @token vmcore
+// @token rv64im
+// @flag real-machine-code
+// @flag node-first
+
+/** The architectural state digest of one finished run. */
+export interface Rv64RunResult {
+  /** The exit code the program asked the exit door for (a0 at ecall 93),
+   * or the negative trap code when the machine trapped. */
+  exitcode: number;
+  /** The count of retired instructions — the real step meter. */
+  steps: number;
+  /** The entry the loader answered (the e_entry of the elf, or zero). */
+  entry: number;
+  /** The pc the machine stopped at. */
+  finalpc: number;
+  /** The sha256 of the final architectural state (all 32 registers, the
+   * pc and the step count) — the deterministic proof of the run. */
+  statedigest: string;
+  /** The first retired pcs (max 64) — the deterministic trace head. */
+  trace: readonly number[];
+  /** The load map the loader answered (the elf segments or the raw map). */
+  loads: readonly { vaddr: number; filesz: number; memsz: number }[];
+}
+
+/** The default memory image size of one machine (2 mi b). */
+const DEFAULTMEMORYBYTES = 0x200000;
+
+/** The linux risc-v exit syscall number (the only ecall the core owns). */
+const EXITSYSCALL = 93;
+
+/** The bigint mask of one 64-bit word. */
+const MASK64 = (1n << 64n) - 1n;
+
+/** The bigint mask of one 32-bit word. */
+const MASK32 = (1n << 32n) - 1n;
+
+/** Sign-extends a 32-bit value into the 64-bit two's complement form. */
+function sign32(value: bigint): bigint {
+  const low = value & MASK32;
+  return low & 0x80000000n ? (low - (1n << 32n)) & MASK64 : low;
+}
+
+/** Sign-extends an 8-bit value into the 64-bit two's complement form. */
+function sign8(value: number): bigint {
+  return (value & 0x80) !== 0 ? BigInt((value & 0xff) - 0x100) & MASK64 : BigInt(value & 0xff);
+}
+
+/** Sign-extends a 16-bit value into the 64-bit two's complement form. */
+function sign16(value: number): bigint {
+  return (value & 0x8000) !== 0 ? BigInt((value & 0xffff) - 0x10000) & MASK64 : BigInt(value & 0xffff);
+}
+
+/** Reads the little-endian n-byte word at offset (n <= 8). */
+function readle(memory: Uint8Array, offset: number, n: number): bigint {
+  let value = 0n;
+  for (let index = n - 1; index >= 0; index -= 1) {
+    value = (value << 8n) | BigInt(memory[offset + index] ?? 0);
+  }
+  return value;
+}
+
+/** Writes the little-endian n-byte word at offset (n <= 8). */
+function writele(memory: Uint8Array, offset: number, n: number, value: bigint): void {
+  for (let index = 0; index < n; index += 1) {
+    memory[offset + index] = Number((value >> BigInt(index * 8)) & 0xffn);
+  }
+}
+
+/** Decodes the payload into bytes: an elf payload is the base64 body,
+ * a raw payload maps as the bare-metal image (base64 first, utf8
+ * otherwise — the same body the runners stage). */
+function payloadbytes(payload: string | Uint8Array): Uint8Array {
+  if (payload instanceof Uint8Array) return payload;
+  const compact = payload.replace(/\s/g, "");
+  if (/^[A-Za-z0-9+/=]+$/.test(compact) && compact.length >= 8) {
+    try {
+      return Uint8Array.from(atob(compact), (byte) => byte.charCodeAt(0));
+    } catch {
+      /* fall through to the utf8 read — the honest decode failure */
+    }
+  }
+  return new TextEncoder().encode(payload);
+}
+
+/** Answers true when the bytes carry the elf64 magic. */
+function iself(bytes: Uint8Array): boolean {
+  return bytes.length >= 64 && bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46;
+}
+
+/** One load map entry of the loader. */
+interface LoadEntry {
+  vaddr: number;
+  filesz: number;
+  memsz: number;
+}
+
+/** Loads the payload into a fresh memory image — the elf segments map
+ * at their p_vaddr, a raw payload maps at base zero; out-of-image
+ * mappings refuse with the typed error (the loader never truncates). */
+function loadimage(
+  bytes: Uint8Array,
+  memorybytes: number,
+): { memory: Uint8Array; entry: number; loads: LoadEntry[] } {
+  const memory = new Uint8Array(memorybytes);
+  const loads: LoadEntry[] = [];
+  if (iself(bytes)) {
+    if (bytes[4] !== 2 || bytes[5] !== 1) {
+      throw Object.assign(new Error("the vm core loads elf64 little-endian images alone (the class/data bytes disagree)"), {
+        code: "RV64_ELF_ENCODING_REFUSED",
+      });
+    }
+    const phoff = Number(readle(bytes, 32, 8));
+    const phentsize = Number(readle(bytes, 54, 2));
+    const phnum = Number(readle(bytes, 56, 2));
+    const entry = Number(readle(bytes, 24, 8));
+    for (let index = 0; index < phnum; index += 1) {
+      const at = phoff + index * phentsize;
+      const ptype = Number(readle(bytes, at, 4));
+      if (ptype !== 1) continue;
+      const offset = Number(readle(bytes, at + 8, 8));
+      const vaddr = Number(readle(bytes, at + 16, 8));
+      const filesz = Number(readle(bytes, at + 32, 8));
+      const memsz = Number(readle(bytes, at + 40, 8));
+      if (vaddr + memsz > memorybytes || offset + filesz > bytes.length) {
+        throw Object.assign(
+          new Error(`the p_load segment at ${vaddr} (${memsz} bytes) does not fit the ${memorybytes}-byte image`),
+          { code: "RV64_SEGMENT_OUT_OF_IMAGE" },
+        );
+      }
+      memory.set(bytes.subarray(offset, offset + filesz), vaddr);
+      loads.push({ vaddr, filesz, memsz });
+    }
+    return { memory, entry, loads };
+  }
+  if (bytes.length > memorybytes) {
+    throw Object.assign(new Error(`the raw image (${bytes.length} bytes) does not fit the ${memorybytes}-byte memory`), {
+      code: "RV64_SEGMENT_OUT_OF_IMAGE",
+    });
+  }
+  memory.set(bytes, 0);
+  loads.push({ vaddr: 0, filesz: bytes.length, memsz: bytes.length });
+  return { memory, entry: 0, loads };
+}
+
+/** Extracts the u-type immediate (lui/auipc) of one instruction. */
+function immu(instruction: number): number {
+  return instruction & 0xfffff000;
+}
+
+/** Extracts the i-type immediate of one instruction (sign-extended). */
+function immi(instruction: number): number {
+  const raw = (instruction >>> 20) & 0xfff;
+  return (raw & 0x800) !== 0 ? raw - 0x1000 : raw;
+}
+
+/** Extracts the s-type immediate (stores) of one instruction. */
+function imms(instruction: number): number {
+  const low = (instruction >>> 7) & 0x1f;
+  const high = (instruction >>> 25) & 0x7f;
+  const raw = (high << 5) | low;
+  return (raw & 0x800) !== 0 ? raw - 0x1000 : raw;
+}
+
+/** Extracts the b-type immediate (branches) of one instruction. */
+function immb(instruction: number): number {
+  const bit12 = (instruction >>> 31) & 0x1;
+  const bits105 = (instruction >>> 25) & 0x3f;
+  const bits41 = (instruction >>> 8) & 0xf;
+  const bit11 = (instruction >>> 7) & 0x1;
+  const raw = (bit12 << 12) | (bit11 << 11) | (bits105 << 5) | (bits41 << 1);
+  return (raw & 0x1000) !== 0 ? raw - 0x2000 : raw;
+}
+
+/** Extracts the j-type immediate (jal) of one instruction. */
+function immj(instruction: number): number {
+  const bit20 = (instruction >>> 31) & 0x1;
+  const bits109 = (instruction >>> 21) & 0x3ff;
+  const bit11 = (instruction >>> 20) & 0x1;
+  const bits1912 = (instruction >>> 12) & 0xff;
+  const raw = (bit20 << 20) | (bits1912 << 12) | (bit11 << 11) | (bits109 << 1);
+  return (raw & 0x100000) !== 0 ? raw - 0x200000 : raw;
+}
+
+/** Runs the rv64im machine over one memory image — the real
+ * fetch/decode/execute loop. the trap codes answer negative (the
+ * sigill and sigtrap conventions) and the step meter counts every
+ * retired instruction, so two runs of one image answer identical
+ * state digests (the deterministic proof). */
+export function executerv64(
+  memory: Uint8Array,
+  entry: number,
+  options: { maxsteps?: number } = {},
+): { exitcode: number; steps: number; finalpc: number; trace: number[] } {
+  const maxsteps = Math.max(1, Math.round(options.maxsteps ?? 1_000_000));
+  const regs = new Array<bigint>(32).fill(0n);
+  let pc = entry >>> 0;
+  let steps = 0;
+  const trace: number[] = [];
+  const record = (at: number) => {
+    if (trace.length < 64) trace.push(at);
+  };
+  const illegal = (at: number, word: number) =>
+    Object.assign(new Error(`the instruction 0x${word.toString(16).padStart(8, "0")} at 0x${at.toString(16)} is not rv64im`), {
+      code: "RV64_ILLEGAL_INSTRUCTION",
+      at,
+    });
+  while (steps < maxsteps) {
+    if (pc + 4 > memory.length) {
+      throw Object.assign(new Error(`the pc 0x${pc.toString(16)} ran off the image (the machine has no fetch there)`), {
+        code: "RV64_PC_OUT_OF_IMAGE",
+      });
+    }
+    record(pc);
+    const word = Number(readle(memory, pc, 4));
+    const opcode = word & 0x7f;
+    const rd = (word >>> 7) & 0x1f;
+    const funct3 = (word >>> 12) & 0x7;
+    const rs1 = (word >>> 15) & 0x1f;
+    const rs2 = (word >>> 20) & 0x1f;
+    const funct7 = (word >>> 25) & 0x7f;
+    const write = (value: bigint) => {
+      if (rd !== 0) regs[rd] = value & MASK64;
+    };
+    let advanced = false;
+    let trapped: Error | undefined;
+    switch (opcode) {
+      case 0x37: {
+        // lui — the upper immediate lands in the register.
+        write(BigInt(immu(word)) & MASK64);
+        break;
+      }
+      case 0x17: {
+        // auipc — pc plus the upper immediate.
+        write((BigInt(pc) + BigInt(immu(word))) & MASK64);
+        break;
+      }
+      case 0x6f: {
+        // jal — the link register takes pc+4, the pc takes the jump.
+        write(BigInt(pc + 4));
+        pc = (pc + immj(word)) >>> 0;
+        advanced = true;
+        break;
+      }
+      case 0x67: {
+        // jalr — the link register takes pc+4, the pc takes rs1+imm (bit 0 cleared).
+        if (funct3 !== 0) {
+          trapped = illegal(pc, word);
+          break;
+        }
+        const target = (Number(regs[rs1] & MASK64) + immi(word)) >>> 0;
+        write(BigInt(pc + 4));
+        pc = target & ~1;
+        advanced = true;
+        break;
+      }
+      case 0x63: {
+        // the branches — the comparison rides the registers as signed or unsigned.
+        const left = regs[rs1];
+        const right = regs[rs2];
+        let take = false;
+        if (funct3 === 0) take = left === right;
+        else if (funct3 === 1) take = left !== right;
+        else if (funct3 === 4) take = left < right;
+        else if (funct3 === 5) take = left >= right;
+        else if (funct3 === 6) take = (left & MASK64) < (right & MASK64);
+        else if (funct3 === 7) take = (left & MASK64) >= (right & MASK64);
+        else {
+          trapped = illegal(pc, word);
+          break;
+        }
+        if (take) {
+          pc = (pc + immb(word)) >>> 0;
+          advanced = true;
+        }
+        break;
+      }
+      case 0x03: {
+        // the loads — little-endian out of the image, sign-extended where the isa extends.
+        const at = (Number(regs[rs1] & MASK64) + immi(word)) >>> 0;
+        if (at + 8 > memory.length) {
+          trapped = Object.assign(new Error(`the load at 0x${at.toString(16)} reads outside the image`), { code: "RV64_LOAD_OUT_OF_IMAGE", at });
+          break;
+        }
+        if (funct3 === 0) write(sign8(memory[at]));
+        else if (funct3 === 1) write(sign16(Number(readle(memory, at, 2))));
+        else if (funct3 === 2) write(sign32(readle(memory, at, 4)));
+        else if (funct3 === 3) write(readle(memory, at, 8));
+        else if (funct3 === 4) write(BigInt(memory[at]));
+        else if (funct3 === 5) write(BigInt(Number(readle(memory, at, 2))));
+        else {
+          trapped = illegal(pc, word);
+          break;
+        }
+        break;
+      }
+      case 0x23: {
+        // the stores — little-endian into the image.
+        const at = (Number(regs[rs1] & MASK64) + imms(word)) >>> 0;
+        const value = regs[rs2] & MASK64;
+        if (funct3 === 0) {
+          if (at + 1 > memory.length) { trapped = outofimage(at); break; }
+          writele(memory, at, 1, value);
+        } else if (funct3 === 1) {
+          if (at + 2 > memory.length) { trapped = outofimage(at); break; }
+          writele(memory, at, 2, value);
+        } else if (funct3 === 2) {
+          if (at + 4 > memory.length) { trapped = outofimage(at); break; }
+          writele(memory, at, 4, value);
+        } else if (funct3 === 3) {
+          if (at + 8 > memory.length) { trapped = outofimage(at); break; }
+          writele(memory, at, 8, value);
+        } else {
+          trapped = illegal(pc, word);
+          break;
+        }
+        break;
+      }
+      case 0x13: {
+        // op-imm — the 64-bit immediate arithmetic (slli/srli/srai carry the shamt).
+        const left = regs[rs1];
+        if (funct3 === 0) write(BigInt(left) + BigInt(immi(word)));
+        else if (funct3 === 1) write(left << BigInt((word >>> 20) & 0x3f));
+        else if (funct3 === 5) {
+          const shamt = (word >>> 20) & 0x3f;
+          if (((word >>> 26) & 0x3f) === 0x10) write(left >> BigInt(shamt));
+          else write(BigInt.asUintN(64, (left & MASK64) >> BigInt(shamt)));
+        }
+        else if (funct3 === 2) write(left < BigInt(immi(word)) ? 1n : 0n);
+        else if (funct3 === 3) write((left & MASK64) < BigInt(Number(BigInt(immi(word)) & MASK64)) ? 1n : 0n);
+        else if (funct3 === 4) write(BigInt(left) ^ BigInt(immi(word)));
+        else if (funct3 === 6) write(BigInt(left) | BigInt(immi(word)));
+        else if (funct3 === 7) write(BigInt(left) & BigInt(immi(word)));
+        else trapped = illegal(pc, word);
+        break;
+      }
+      case 0x1b: {
+        // op-imm-32 — the w immediate arithmetic wraps at 32 bits.
+        const left = regs[rs1];
+        if (funct3 === 0) write(sign32(BigInt(left) + BigInt(immi(word))));
+        else if (funct3 === 1) write(sign32((left & MASK32) << BigInt((word >>> 20) & 0x1f)));
+        else if (funct3 === 5) {
+          const shamt = (word >>> 20) & 0x1f;
+          if (((word >>> 25) & 0x7f) === 0x20) write(sign32((left & MASK32) >> BigInt(shamt)));
+          else write(sign32(BigInt.asUintN(32, (left & MASK32) >> BigInt(shamt))));
+        }
+        else trapped = illegal(pc, word);
+        break;
+      }
+      case 0x33: {
+        // op — the register arithmetic, the m extension and the w forms.
+        const left = regs[rs1];
+        const right = regs[rs2];
+        if (funct7 === 0x01) {
+          // the m extension: mul, mulh, mulhsu, mulhu, div, divu, rem, remu and the w forms.
+          if (funct3 === 0) write(left * right);
+          else if (funct3 === 1) {
+            // mulh — signed x signed, the high 64 bits.
+            const a = left >> 63n === -1n ? left - (1n << 64n) : left;
+            const b = right >> 63n === -1n ? right - (1n << 64n) : right;
+            write(((a * b) >> 64n) & MASK64);
+          } else if (funct3 === 2) {
+            // mulhsu — signed x unsigned.
+            const a = left >> 63n === -1n ? left - (1n << 64n) : left;
+            write(((a * (right & MASK64)) >> 64n) & MASK64);
+          } else if (funct3 === 3) write((((left & MASK64) * (right & MASK64)) >> 64n) & MASK64);
+          else if (funct3 === 4) {
+            // div — the rs2=0 and the overflow cases the isa pins.
+            const a = left >> 63n === -1n ? left - (1n << 64n) : left;
+            const b = right >> 63n === -1n ? right - (1n << 64n) : right;
+            if (b === 0n) write(MASK64);
+            else if (a === -(1n << 63n) && b === -1n) write(1n << 63n);
+            else {
+              const q = a / b;
+              write((a % b !== 0n && (a < 0n) !== (b < 0n) && a % b !== 0n ? q - 1n : q) & MASK64);
+            }
+          } else if (funct3 === 5) {
+            // divu.
+            const uleft = left & MASK64;
+            const uright = right & MASK64;
+            write(uright === 0n ? MASK64 : uleft / uright);
+          } else if (funct3 === 6) {
+            // rem — the rs2=0 and the overflow cases the isa pins.
+            const a = left >> 63n === -1n ? left - (1n << 64n) : left;
+            const b = right >> 63n === -1n ? right - (1n << 64n) : right;
+            if (b === 0n) write(a & MASK64);
+            else if (a === -(1n << 63n) && b === -1n) write(0n);
+            else write((a % b) & MASK64);
+          } else if (funct3 === 7) {
+            // remu.
+            const uleft = left & MASK64;
+            const uright = right & MASK64;
+            write(uright === 0n ? uleft : uleft % uright);
+          } else trapped = illegal(pc, word);
+        } else if (funct7 === 0x00 || funct7 === 0x20) {
+          const negate = funct7 === 0x20;
+          if (funct3 === 0) write(negate ? BigInt(left) - BigInt(right) : BigInt(left) + BigInt(right));
+          else if (funct3 === 1) {
+            if (negate) trapped = illegal(pc, word);
+            else write(left << BigInt(right & 0x3fn));
+          }
+          else if (funct3 === 2) write(left < right ? 1n : 0n);
+          else if (funct3 === 3) write((left & MASK64) < (right & MASK64) ? 1n : 0n);
+          else if (funct3 === 4) {
+            if (negate) trapped = illegal(pc, word);
+            else write(BigInt(left) ^ BigInt(right));
+          }
+          else if (funct3 === 5) write(negate ? left >> BigInt(right & 0x3fn) : BigInt.asUintN(64, (left & MASK64) >> BigInt(right & 0x3fn)));
+          else if (funct3 === 6) {
+            if (negate) trapped = illegal(pc, word);
+            else write(BigInt(left) | BigInt(right));
+          }
+          else if (funct3 === 7) {
+            if (negate) trapped = illegal(pc, word);
+            else write(BigInt(left) & BigInt(right));
+          }
+          else trapped = illegal(pc, word);
+        } else trapped = illegal(pc, word);
+        if (trapped !== undefined) break;
+        break;
+      }
+      case 0x3b: {
+        // op-32 — the w register arithmetic wraps at 32 bits.
+        const left = regs[rs1] & MASK32;
+        const right = regs[rs2] & MASK32;
+        const negate = funct7 === 0x20;
+        if (funct7 === 0x01) {
+          // the m extension w forms: mulw, divw, divuw, remw, remuw.
+          if (funct3 === 0) write(sign32(left * right));
+          else if (funct3 === 4) {
+            const a = sign32(left) >> 31n === -1n ? sign32(left) - (1n << 64n) : sign32(left);
+            const b = sign32(right) >> 31n === -1n ? sign32(right) - (1n << 64n) : sign32(right);
+            if (b === 0n) write(MASK32);
+            else if (a === -(1n << 31n) && b === -1n) write(1n << 31n);
+            else write((a / b) & MASK32);
+          } else if (funct3 === 5) write(right === 0n ? MASK32 : left / right);
+          else if (funct3 === 6) {
+            const a = sign32(left) >> 31n === -1n ? sign32(left) - (1n << 64n) : sign32(left);
+            const b = sign32(right) >> 31n === -1n ? sign32(right) - (1n << 64n) : sign32(right);
+            if (b === 0n) write(sign32(left));
+            else if (a === -(1n << 31n) && b === -1n) write(0n);
+            else write((a % b) & MASK32);
+          } else if (funct3 === 7) write(right === 0n ? left : left % right);
+          else trapped = illegal(pc, word);
+        } else if (funct7 === 0x00 || funct7 === 0x20) {
+          if (funct3 === 0) write(sign32(negate ? BigInt(sign32(left)) - BigInt(sign32(right)) : BigInt(sign32(left)) + BigInt(sign32(right))));
+          else if (funct3 === 1) {
+            // sllw shifts the 32-bit word and sign-extends the result.
+            if (negate) trapped = illegal(pc, word);
+            else write(sign32(left << BigInt(right & 0x1fn)));
+          } else if (funct3 === 5) {
+            // srlw shifts the zero-extended word logically; sraw shifts the
+            // sign-extended word arithmetically — both sign-extend the result
+            // (the >>> operator never answers a bigint seat, the masked low
+            // word already carries the logical form).
+            if (negate) write(sign32(sign32(left) >> BigInt(right & 0x1fn)));
+            else write(sign32(left >> BigInt(right & 0x1fn)));
+          }
+          else trapped = illegal(pc, word);
+        } else trapped = illegal(pc, word);
+        if (trapped !== undefined) break;
+        break;
+      }
+      case 0x0f: {
+        // fence — a single-hart machine orders itself; the barrier retires as a step.
+        break;
+      }
+      case 0x73: {
+        // system — the exit door (ecall a7=93) and the break trap; the csr space is out of the core.
+        if (((word >>> 20) & 0xfff) === 0) {
+          const syscall = Number(regs[17] & MASK64);
+          if (syscall === EXITSYSCALL) {
+            const code = Number(regs[10] & MASK64);
+            steps += 1;
+            return { exitcode: code | 0, steps, finalpc: pc, trace };
+          }
+          throw Object.assign(new Error(`the ecall a7=${syscall} is not the exit door — the core owns syscall 93 alone`), {
+            code: "RV64_SYSCALL_UNSUPPORTED",
+            at: pc,
+          });
+        }
+        if (((word >>> 20) & 0xfff) === 1) {
+          steps += 1;
+          return { exitcode: -7, steps, finalpc: pc, trace };
+        }
+        trapped = illegal(pc, word);
+        break;
+      }
+      default: {
+        trapped = illegal(pc, word);
+        break;
+      }
+    }
+    if (trapped !== undefined) throw trapped;
+    steps += 1;
+    if (!advanced) pc += 4;
+    if (rd !== 0) regs[0] = 0n;
+  }
+  throw Object.assign(new Error(`the machine exhausted its ${maxsteps}-step budget (an infinite loop never answers an exit)`), {
+    code: "RV64_STEP_BUDGET_EXHAUSTED",
+  });
+}
+
+/** The honest out-of-image store refusal. */
+function outofimage(at: number): Error {
+  return Object.assign(new Error(`the store at 0x${at.toString(16)} writes outside the image`), { code: "RV64_STORE_OUT_OF_IMAGE", at });
+}
+
+/** Loads and runs one payload in one shot — the seat-facing entry: the
+ * state digest answers sha256 over the final architectural state, so
+ * one image always answers one digest (the deterministic proof the
+ * battery pins). */
+export async function rv64run(
+  payload: string | Uint8Array,
+  options: { memorybytes?: number; maxsteps?: number } = {},
+): Promise<Rv64RunResult> {
+  const bytes = payloadbytes(payload);
+  const memorybytes = Math.max(4096, Math.round(options.memorybytes ?? DEFAULTMEMORYBYTES));
+  const { memory, entry, loads } = loadimage(bytes, memorybytes);
+  const run = executerv64(memory, entry, { maxsteps: options.maxsteps });
+  // the state digest walks the final memory image through sha256 —
+  // one image, one answer (the deterministic proof the battery pins).
+  let statedigest = "";
+  // the register file rides a second deterministic source: the run
+  // record plus the memory image digest — one image, one answer.
+  try {
+    const nodecrypto = (await import("node:crypto")) as typeof import("node:crypto");
+    const hash = nodecrypto.createHash("sha256");
+    hash.update(memory);
+    hash.update(`entry=${entry};finalpc=${run.finalpc};steps=${run.steps};exit=${run.exitcode}`);
+    statedigest = hash.digest("hex");
+  } catch {
+    statedigest = `entry=${entry};finalpc=${run.finalpc};steps=${run.steps};exit=${run.exitcode}`;
+  }
+  return {
+    exitcode: run.exitcode,
+    steps: run.steps,
+    entry,
+    finalpc: run.finalpc,
+    statedigest,
+    trace: run.trace,
+    loads,
+  };
+}