@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/registry/wasi-mem.js

@@ -0,0 +1,355 @@
+// W71: the WASI preview1 host wmdpack.wasm (cmd/wmdpack-wasm, union.PackLayer for wasip1) runs on in a
+// Worker: one thread, an in-memory filesystem behind one preopen ("/"), stdin from bytes. It implements
+// exactly the imports Go's wasip1 port links; anything else answers ENOSYS.
+//
+//   const fs = new MemFs({ maxFileBytes })
+//   fs.addFile('below/0.pack', bytes)                  // read-only inputs
+//   const r = runWasi(module, { args: ['wmdpack', '/out.pack', '/below/0.pack'], stdin: layerBytes, fs })
+//   r.code, r.stdout, r.stderr; fs.take('out.pack')    // the files the program wrote
+//
+// Paths are relative to the preopen ("/out.pack" in argv is "out.pack" here). Directories exist when a file
+// path under them does (no empty directories are needed by the converter).
+
+const E = Object.freeze({ SUCCESS: 0, BADF: 8, EXIST: 20, FBIG: 22, INVAL: 28, ISDIR: 31, NOENT: 44, NOSYS: 52, NOTDIR: 54, SPIPE: 70 })
+const FT = Object.freeze({ CHAR: 2, DIR: 3, FILE: 4 })
+const OFLAG = Object.freeze({ CREAT: 1, DIRECTORY: 2, EXCL: 4, TRUNC: 8 })
+const FDFLAG_APPEND = 1
+const PREOPEN = 3
+
+class ExitSignal extends Error {
+  constructor(code) {
+    super(`exit ${code}`)
+    this.code = code
+  }
+}
+
+/** Normalizes a path under the preopen; null when it climbs out. */
+export function cleanPath(p) {
+  const out = []
+  for (const part of p.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') {
+      if (!out.length) return null
+      out.pop()
+      continue
+    }
+    out.push(part)
+  }
+  return out.join('/')
+}
+
+/** A file: its bytes (data[0..size)) and whether the program may change it. */
+class MemFile {
+  constructor(data, size, readonly) {
+    this.data = data
+    this.size = size
+    this.readonly = readonly
+  }
+  ensure(n, max) {
+    if (n > max) return false
+    if (n <= this.data.length) return true
+    const grown = new Uint8Array(Math.min(max, Math.max(n, Math.ceil(this.data.length * 1.5), 1 << 20)))
+    grown.set(this.data.subarray(0, this.size))
+    this.data = grown
+    return true
+  }
+}
+
+export class MemFs {
+  /** @param {{maxFileBytes?: number}} [o] a write past maxFileBytes fails with EFBIG */
+  constructor({ maxFileBytes = 4 * 2 ** 30 } = {}) {
+    this.files = new Map()
+    this.maxFileBytes = maxFileBytes
+  }
+  /** A read-only input file (the bytes are not copied). */
+  addFile(path, bytes) {
+    this.files.set(cleanPath(path), new MemFile(bytes, bytes.length, true))
+  }
+  /** The bytes of a file the program wrote, exactly its size; the file is removed from the fs. */
+  take(path) {
+    const p = cleanPath(path)
+    const f = this.files.get(p)
+    if (!f) return null
+    this.files.delete(p)
+    if (f.size === f.data.length) return f.data
+    const b = f.data.buffer
+    // ArrayBuffer.prototype.transfer (2024 engines) shrinks without a second copy
+    if (typeof b.transfer === 'function' && f.data.byteOffset === 0 && !(typeof SharedArrayBuffer !== 'undefined' && b instanceof SharedArrayBuffer)) {
+      return new Uint8Array(b.transfer(f.size))
+    }
+    return f.data.slice(0, f.size)
+  }
+  isDir(p) {
+    if (p === '') return true
+    const pre = `${p}/`
+    for (const k of this.files.keys()) if (k.startsWith(pre)) return true
+    return false
+  }
+}
+
+/**
+ * Runs a wasip1 command to its end.
+ * @param {WebAssembly.Module} module
+ * @param {{args: string[], env?: string[], stdin?: Uint8Array, fs: MemFs}} o
+ * @returns {{code: number, stdout: string, stderr: string}}
+ */
+export function runWasi(module, { args, env = [], stdin = new Uint8Array(0), fs }) {
+  const enc = new TextEncoder()
+  const argv = args.map(a => enc.encode(`${a}\0`))
+  const envv = env.map(a => enc.encode(`${a}\0`))
+  const out = { 1: [], 2: [] }
+  let stdinPos = 0
+  // fd -> {kind: 'file', path, file, pos, append} | {kind: 'dir', path}
+  const fds = new Map([[PREOPEN, { kind: 'dir', path: '' }]])
+  let nextFd = 4
+  let memory = null
+  const u8 = () => new Uint8Array(memory.buffer)
+  const dv = () => new DataView(memory.buffer)
+  const str = (ptr, len) => new TextDecoder().decode(u8().subarray(ptr, ptr + len))
+  const resolve = (dirfd, ptr, len) => {
+    const d = fds.get(dirfd)
+    if (!d || d.kind !== 'dir') return { err: E.BADF }
+    const p = cleanPath(`${d.path}/${str(ptr, len)}`)
+    return p === null ? { err: E.INVAL } : { p }
+  }
+  const iovs = (ptr, n) => {
+    const v = dv()
+    const list = []
+    for (let i = 0; i < n; i++) list.push([v.getUint32(ptr + i * 8, true), v.getUint32(ptr + i * 8 + 4, true)])
+    return list
+  }
+  const putStrings = (list, ptrs, buf) => {
+    const v = dv()
+    const m = u8()
+    let o = buf
+    list.forEach((s, i) => {
+      v.setUint32(ptrs + i * 4, o, true)
+      m.set(s, o)
+      o += s.length
+    })
+    return E.SUCCESS
+  }
+  const sizes = (list, countPtr, sizePtr) => {
+    dv().setUint32(countPtr, list.length, true)
+    dv().setUint32(sizePtr, list.reduce((n, s) => n + s.length, 0), true)
+    return E.SUCCESS
+  }
+  const filestat = (ptr, type, size) => {
+    const v = dv()
+    for (let i = 0; i < 64; i += 8) v.setBigUint64(ptr + i, 0n, true)
+    v.setUint8(ptr + 16, type)
+    v.setBigUint64(ptr + 24, 1n, true)
+    v.setBigUint64(ptr + 32, BigInt(size), true)
+    return E.SUCCESS
+  }
+  const readInto = (src, srcSize, pos, list) => {
+    const m = u8()
+    let n = 0
+    for (const [p, len] of list) {
+      const k = Math.max(0, Math.min(len, srcSize - pos - n))
+      if (k > 0) m.set(src.subarray(pos + n, pos + n + k), p)
+      n += k
+      if (k < len) break
+    }
+    return n
+  }
+
+  const wasi = {
+    args_sizes_get: (c, s) => sizes(argv, c, s),
+    args_get: (p, b) => putStrings(argv, p, b),
+    environ_sizes_get: (c, s) => sizes(envv, c, s),
+    environ_get: (p, b) => putStrings(envv, p, b),
+    clock_time_get: (_id, _prec, ptr) => {
+      dv().setBigUint64(ptr, BigInt(Math.round((performance.timeOrigin + performance.now()) * 1e6)), true)
+      return E.SUCCESS
+    },
+    random_get: (ptr, len) => {
+      for (let o = 0; o < len; o += 65536) crypto.getRandomValues(u8().subarray(ptr + o, ptr + Math.min(len, o + 65536)))
+      return E.SUCCESS
+    },
+    sched_yield: () => E.SUCCESS,
+    // Go's scheduler polls with clock timeouts when it is idle: report every subscription as due
+    // (one thread, nothing to wait for).
+    poll_oneoff: (inPtr, outPtr, n, neventsPtr) => {
+      const v = dv()
+      for (let i = 0; i < n; i++) {
+        const s = inPtr + i * 48
+        const e = outPtr + i * 32
+        v.setBigUint64(e, v.getBigUint64(s, true), true) // userdata
+        v.setUint16(e + 8, E.SUCCESS, true)
+        v.setUint8(e + 10, v.getUint8(s + 8)) // type
+        for (let k = 16; k < 32; k += 8) v.setBigUint64(e + k, 0n, true)
+      }
+      v.setUint32(neventsPtr, n, true)
+      return E.SUCCESS
+    },
+    proc_exit: code => {
+      throw new ExitSignal(code)
+    },
+    fd_write: (fd, iovPtr, n, nwritten) => {
+      const m = u8()
+      let total = 0
+      if (fd === 1 || fd === 2) {
+        for (const [p, len] of iovs(iovPtr, n)) {
+          out[fd].push(m.slice(p, p + len))
+          total += len
+        }
+        dv().setUint32(nwritten, total, true)
+        return E.SUCCESS
+      }
+      const f = fds.get(fd)
+      if (!f || f.kind !== 'file' || f.file.readonly) return E.BADF
+      const list = iovs(iovPtr, n)
+      const want = list.reduce((a, [, len]) => a + len, 0)
+      if (f.append) f.pos = f.file.size
+      if (!f.file.ensure(f.pos + want, fs.maxFileBytes)) return E.FBIG
+      const mm = u8()
+      for (const [p, len] of list) {
+        f.file.data.set(mm.subarray(p, p + len), f.pos)
+        f.pos += len
+        total += len
+      }
+      if (f.pos > f.file.size) f.file.size = f.pos
+      dv().setUint32(nwritten, total, true)
+      return E.SUCCESS
+    },
+    fd_read: (fd, iovPtr, n, nread) => {
+      if (fd === 0) {
+        const k = readInto(stdin, stdin.length, stdinPos, iovs(iovPtr, n))
+        stdinPos += k
+        dv().setUint32(nread, k, true)
+        return E.SUCCESS
+      }
+      const f = fds.get(fd)
+      if (!f) return E.BADF
+      if (f.kind !== 'file') return E.ISDIR
+      const k = readInto(f.file.data, f.file.size, f.pos, iovs(iovPtr, n))
+      f.pos += k
+      dv().setUint32(nread, k, true)
+      return E.SUCCESS
+    },
+    fd_pread: (fd, iovPtr, n, offset, nread) => {
+      const f = fds.get(fd)
+      if (!f) return E.BADF
+      if (f.kind !== 'file') return E.ISDIR
+      const k = readInto(f.file.data, f.file.size, Number(offset), iovs(iovPtr, n))
+      dv().setUint32(nread, k, true)
+      return E.SUCCESS
+    },
+    fd_seek: (fd, offset, whence, newPtr) => {
+      const f = fds.get(fd)
+      if (fd <= 2) return E.SPIPE
+      if (!f || f.kind !== 'file') return E.BADF
+      const base = whence === 0 ? 0 : whence === 1 ? f.pos : whence === 2 ? f.file.size : -1
+      if (base < 0) return E.INVAL
+      const pos = base + Number(offset)
+      if (pos < 0) return E.INVAL
+      f.pos = pos
+      dv().setBigUint64(newPtr, BigInt(pos), true)
+      return E.SUCCESS
+    },
+    fd_close: fd => {
+      if (fd <= PREOPEN) return E.SUCCESS
+      return fds.delete(fd) ? E.SUCCESS : E.BADF
+    },
+    fd_fdstat_get: (fd, ptr) => {
+      const v = dv()
+      const f = fds.get(fd)
+      const type = fd <= 2 ? FT.CHAR : f?.kind === 'dir' ? FT.DIR : f ? FT.FILE : -1
+      if (type < 0) return E.BADF
+      v.setUint8(ptr, type)
+      v.setUint16(ptr + 2, f?.append ? FDFLAG_APPEND : 0, true)
+      v.setBigUint64(ptr + 8, 0xffffffffffffffffn, true)
+      v.setBigUint64(ptr + 16, 0xffffffffffffffffn, true)
+      return E.SUCCESS
+    },
+    fd_fdstat_set_flags: () => E.SUCCESS,
+    fd_prestat_get: (fd, ptr) => {
+      if (fd !== PREOPEN) return E.BADF
+      dv().setUint32(ptr, 0, true) // directory
+      dv().setUint32(ptr + 4, 1, true) // "/"
+      return E.SUCCESS
+    },
+    fd_prestat_dir_name: (fd, ptr, len) => {
+      if (fd !== PREOPEN) return E.BADF
+      if (len >= 1) u8()[ptr] = 0x2f
+      return E.SUCCESS
+    },
+    fd_filestat_get: (fd, ptr) => {
+      if (fd <= 2) return filestat(ptr, FT.CHAR, 0)
+      const f = fds.get(fd)
+      if (!f) return E.BADF
+      return f.kind === 'dir' ? filestat(ptr, FT.DIR, 0) : filestat(ptr, FT.FILE, f.file.size)
+    },
+    path_filestat_get: (dirfd, _flags, ptr, len, out) => {
+      const r = resolve(dirfd, ptr, len)
+      if (r.err) return r.err
+      const f = fs.files.get(r.p)
+      if (f) return filestat(out, FT.FILE, f.size)
+      return fs.isDir(r.p) ? filestat(out, FT.DIR, 0) : E.NOENT
+    },
+    path_open: (dirfd, _dirflags, ptr, len, oflags, _rb, _ri, fdflags, fdOut) => {
+      const r = resolve(dirfd, ptr, len)
+      if (r.err) return r.err
+      let f = fs.files.get(r.p)
+      if (!f && fs.isDir(r.p)) {
+        if (oflags & OFLAG.CREAT) return E.ISDIR
+        const fd = nextFd++
+        fds.set(fd, { kind: 'dir', path: r.p })
+        dv().setUint32(fdOut, fd, true)
+        return E.SUCCESS
+      }
+      if (oflags & OFLAG.DIRECTORY) return f ? E.NOTDIR : E.NOENT
+      if (f && oflags & OFLAG.CREAT && oflags & OFLAG.EXCL) return E.EXIST
+      if (!f) {
+        if (!(oflags & OFLAG.CREAT)) return E.NOENT
+        const parent = r.p.includes('/') ? r.p.slice(0, r.p.lastIndexOf('/')) : ''
+        if (parent && fs.files.has(parent)) return E.NOTDIR
+        f = new MemFile(new Uint8Array(0), 0, false)
+        fs.files.set(r.p, f)
+      } else if (oflags & OFLAG.TRUNC) {
+        if (f.readonly) return E.BADF
+        f.size = 0
+      }
+      const fd = nextFd++
+      fds.set(fd, { kind: 'file', path: r.p, file: f, pos: 0, append: !!(fdflags & FDFLAG_APPEND) })
+      dv().setUint32(fdOut, fd, true)
+      return E.SUCCESS
+    },
+    path_rename: (fd1, p1, l1, fd2, p2, l2) => {
+      const a = resolve(fd1, p1, l1)
+      const b = resolve(fd2, p2, l2)
+      if (a.err || b.err) return a.err || b.err
+      const f = fs.files.get(a.p)
+      if (!f) return E.NOENT
+      fs.files.delete(a.p)
+      fs.files.set(b.p, f)
+      return E.SUCCESS
+    },
+    path_unlink_file: (dirfd, ptr, len) => {
+      const r = resolve(dirfd, ptr, len)
+      if (r.err) return r.err
+      if (!fs.files.has(r.p)) return fs.isDir(r.p) ? E.ISDIR : E.NOENT
+      fs.files.delete(r.p)
+      return E.SUCCESS
+    },
+    path_remove_directory: () => E.NOSYS,
+    path_readlink: () => E.INVAL,
+    fd_readdir: () => E.NOSYS,
+  }
+
+  const inst = new WebAssembly.Instance(module, {
+    wasi_snapshot_preview1: new Proxy(wasi, { get: (t, k) => t[k] || (() => E.NOSYS) }),
+  })
+  memory = inst.exports.memory
+  let code = 0
+  try {
+    inst.exports._start()
+  } catch (e) {
+    if (!(e instanceof ExitSignal)) throw e
+    code = e.code
+  }
+  const text = parts => new TextDecoder().decode(parts.length === 1 ? parts[0] : new Uint8Array(parts.flatMap(p => [...p])))
+  // memBytes: the module's linear memory when it ended (wasm memory only grows: its peak)
+  return { code, stdout: text(out[1]), stderr: text(out[2]), memBytes: memory.buffer.byteLength }
+}

package/src/worker.js

@@ -0,0 +1,315 @@
+// One Worker = one wasm thread of vm.wasm (the runner's one-Store-per-thread model,
+// runner/src/host.rs, spawn.rs).
+//
+// role "main": instantiate vm.wasm and call _start (tid 1, vCPU 0).
+// role "pool": park on a pool slot; for each spawn request instantiate vm.wasm again
+// (same shared memory, a fresh table) and call wasi_thread_start(tid, start_arg).
+//
+// Messages to the page: {t:'ready'|'exit'|'trap'|'need'|'thread'}; output goes through
+// the shared stdio rings (host/stdio.js).
+
+import { createClock } from './host/clock.js'
+import { knownLookup } from './host/jit-cache.js'
+import { createFs } from './host/fs.js'
+import { gcNudge, gcNudger, jitYielder, needsGcNudge } from './host/gcnudge.js'
+import { shimI64Imports } from './host/i64shim.js'
+import {
+  CTL_EXIT,
+  CTL_EXIT_CODE,
+  CTL_CK_RESTORED,
+  CTL_POOL_GEN,
+  CTL_STALL_DONE,
+  CTL_STALL_MS,
+  CTL_STALL_TAKEN,
+  CTL_STALL_TID,
+  CTL_STALL_WAKE,
+  CTL_TRAPS,
+  F64_STALL_AT,
+  F64_STALL_END,
+  SLOT_STATE,
+  ST_IDLE,
+  slotIndex,
+} from './host/layout.js'
+import { createThreadSpawn, threadDone, waitForWork } from './host/threads.js'
+import { WasiExit, createWasi } from './host/wasi.js'
+import { createJitDoor, poolProbe, TABLE_MIN } from './host/jit.js'
+import { stdioWriter } from './host/stdio.js'
+import { createWmdImports } from './host/wmd-imports.js'
+import { createRamImports } from './host/ram-mem.js'
+import { createChanImports } from './host/chan.js'
+import { createCkptImports } from './host/ckpt-point.js'
+
+const enc = new TextEncoder()
+
+self.onmessage = e => {
+  const m = e.data
+  if (m.t !== 'init') return
+  run(m).catch(err => fatal(m, err, 0))
+}
+
+// JSPI: lets a vCPU's jit_sync wait (its wasm stack suspended, the Worker's event loop
+// running) for a Module another Worker compiled, instead of compiling its own copy.
+// W32: how often a WebKit JIT thread yields to its event loop at a wmd.jit_yield point
+export const YIELD_MS = 2000
+export const haveJspi = () => typeof WebAssembly.Suspending === 'function' && typeof WebAssembly.promising === 'function'
+
+/**
+ * W77: the JIT door's side of the page's module cache (host/jit-cache.js): the index table
+ * the page read before the guest started, module reads and notes over the cache port.
+ */
+function jitCacheClient({ sab, port }) {
+  const waiting = new Map()
+  let next = 1
+  port.onmessage = e => {
+    const r = waiting.get(e.data.id)
+    if (!r) return
+    waiting.delete(e.data.id)
+    r(e.data.bytes || null)
+  }
+  return {
+    lookup: knownLookup(sab),
+    request(hl, hh, len) {
+      const id = next++
+      return new Promise(resolve => {
+        waiting.set(id, resolve)
+        port.postMessage({ t: 'get', id, hl, hh, len })
+      })
+    },
+    note(msg) {
+      port.postMessage({ t: 'note', ...msg })
+    },
+  }
+}
+
+function fatal(m, err, tid) {
+  if (err instanceof WasiExit) return
+  const ctl = new Int32Array(m.ctlSab)
+  Atomics.add(ctl, CTL_TRAPS, 1) // counted even when another thread's exit won CTL_EXIT
+  // A trap on any thread ends the machine, as in the runner (exit status 4).
+  if (Atomics.compareExchange(ctl, CTL_EXIT, 0, 1) === 0) {
+    Atomics.store(ctl, CTL_EXIT_CODE, 4)
+    Atomics.notify(ctl, CTL_EXIT)
+  }
+  self.postMessage({
+    t: 'trap',
+    role: m.role,
+    slot: m.slot,
+    tid,
+    message: String(err && err.message ? err.message : err),
+    stack: err && err.stack ? String(err.stack) : '',
+  })
+}
+
+async function run(m) {
+  const { module, memory, ctlSab, role, slot } = m
+  const ctl = new Int32Array(ctlSab)
+  const clock = createClock(ctlSab)
+  const fs = createFs({ ctlSab, preopen: m.preopen, files: m.files })
+
+  // stdout/stderr go into the shared rings (host/stdio.js); the page drains them.
+  const write = stdioWriter(m.stdio)
+  const wasi = createWasi({
+    memory,
+    args: m.args,
+    env: m.env,
+    fs,
+    clock,
+    ctl,
+    write,
+    onExit: code => self.postMessage({ t: 'exit', code, role, slot }),
+  })
+  const threadSpawn = createThreadSpawn(ctl, {
+    requestWorkers: why => self.postMessage({ t: 'need', why }),
+    waitMs: m.spawnWaitMs ?? 10000,
+  })
+  // The JIT door (P-B2): one per Worker over the machine's shared slot list. With a
+  // hub port (sharing, P-B2 adversarial F1) the imports that sync may return a Promise:
+  // they are wrapped in WebAssembly.Suspending and the guest entry points in
+  // WebAssembly.promising, so the wasm stack suspends while the Module arrives.
+  // Only a module that imports the door gets one: a synthetic guest (the P-B1 review's
+  // test/e2e/review-synth/*.wat) has no wmd.* imports and no vm_helper_* exports.
+  // vm.wasm's table import minimum, read from its bytes on the page (tableMinOf); the JIT
+  // slots start right after it.
+  const tableMin = m.tableMin ?? TABLE_MIN
+  const wantsJit = !!m.jit && WebAssembly.Module.imports(module).some(i => i.module === 'wmd' && i.name === 'jit_load')
+  const sharing = wantsJit && !!m.jitPort
+  if (sharing && !haveJspi()) throw new Error('JIT module sharing needs JSPI (WebAssembly.Suspending) in this Worker')
+  const jit = wantsJit
+    ? createJitDoor({
+        store: m.jit,
+        memory,
+        ram: m.ram || null,
+        log: s => write(2, enc.encode(`${s}\n`)),
+        compileOnCompile: m.jitOpts?.compileOnCompile,
+        brk: m.jitOpts?.brk,
+        maxLiveBytes: m.jitOpts?.maxLiveBytes,
+        codePool: m.jitOpts?.codePool !== false && needsGcNudge() ? poolProbe : null,
+        share: sharing ? { port: m.jitPort, waitMs: m.jitOpts?.shareWaitMs } : null,
+        tableMin,
+        cache: m.jitCache ? jitCacheClient(m.jitCache) : null,
+      })
+    : null
+  let jitImports = jit?.imports
+  if (sharing) {
+    const S = f => new WebAssembly.Suspending(f)
+    jitImports = { ...jitImports, load: S(jitImports.load), sync: S(jitImports.sync), flush: S(jitImports.flush) }
+    // W77, D-513: a hit on a module this Worker has not got yet waits for it (the page's bytes, the hub's Module)
+    jitImports.known = S(jitImports.known)
+    // W32: WebKit gives released JIT code back only from a thread's event loop; vm.wasm calls
+    // wmd.jit_yield where no JIT block is on its stack (host/gcnudge.js jitYielder)
+    if (needsGcNudge()) {
+      const ms = m.jitOpts?.yieldMs ?? 0
+      jitImports.yield = S(jitYielder({ every: m.jitOpts?.yieldEvery ?? YIELD_MS, delay: fn => setTimeout(fn, ms) }))
+    }
+  }
+  const enter = f => (sharing ? WebAssembly.promising(f) : f)
+  // P-B3: channels over the chan block's rings, when the boot has channel services.
+  const chan = m.chan ? createChanImports({ sab: m.chan, memory, exiting: () => Atomics.load(ctl, CTL_EXIT) !== 0 }) : {}
+  let heapTopFn = null // vm.wasm's vm_heap_top export, once the main thread has instantiated (null: a full scan)
+  // P-B9: checkpoint support: wmd.ctl_attach and wmd.point (host/ckpt-point.js)
+  const ckpt = m.ckpt ? createCkptImports({ memory, ctl, scanLimit: m.ckptScanLimit ?? null, verifyBound: !!m.ckptVerifyBound, useHeapTop: !!m.ckptUseHeapTop, heapTop: () => heapTopFn?.() ?? null, post: (msg, transfer) => self.postMessage(msg, transfer || []) }) : null
+  // the flat layout: guest RAM is the page's memory64 (host/ram-mem.js)
+  const ramImports = m.ram ? createRamImports({ memory, ram: m.ram }) : null
+  const wmd = createWmdImports({
+    jit: jitImports,
+    chan,
+    ckpt,
+    ram: ramImports,
+    counters: ctl, // stub calls (chan_open, snapshot, jit_* without a door) are counted in ctl, read by the page
+  })
+
+  // Once the machine has ended (a trap on any thread, or proc_exit), every other thread
+  // stops at its next host call instead of running on until the page terminates its
+  // Worker: after a trap the guest's memory may hold garbage (P-B11 review finding 4: a
+  // second vCPU went on to interpret freed IR and printed "vreg out of range"). The JIT
+  // door's imports are left as they are.
+  const stopped = () => Atomics.load(ctl, CTL_EXIT) !== 0
+  // P-B8 test hook (bootWmd({stallHook: true}), vm.stallThread): the thread the page names
+  // blocks at its next host call for the time asked, as if the browser had stopped its
+  // Worker (a GC pause, an OS deschedule). A vCPU reads the guest's clock through
+  // clock_time_get many times a second, so it is reached within milliseconds; the guest
+  // state it stops in (a lock held, an interrupt pending) is wherever that call was.
+  let myTid = role === 'main' ? 1 : 0
+  const f64 = new Float64Array(ctlSab)
+  const maybeStall = () => {
+    if (Atomics.load(ctl, CTL_STALL_TID) !== myTid || !myTid) return
+    if (Atomics.compareExchange(ctl, CTL_STALL_TID, myTid, 0) !== myTid) return
+    const ms = Atomics.load(ctl, CTL_STALL_MS)
+    const wake = Atomics.load(ctl, CTL_STALL_WAKE)
+    f64[F64_STALL_AT / 8] = performance.timeOrigin + performance.now()
+    Atomics.add(ctl, CTL_STALL_TAKEN, 1)
+    Atomics.wait(ctl, CTL_STALL_WAKE, wake, ms)
+    f64[F64_STALL_END / 8] = performance.timeOrigin + performance.now()
+    Atomics.add(ctl, CTL_STALL_DONE, 1)
+  }
+  const stallHook = !!m.stallHook
+  // D-419: WebKit collects this thread's garbage only when nudged (host/gcnudge.js)
+  const nudge = gcNudger()
+  // W32: an idle pool Worker yields to its event loop (below). The vm.wasm threads' own yield
+  // points are not here: a JSPI suspension from clock_time_get trapped in WebKit ("JSPI stack scan
+  // failed: unrecognized type of Wasm frame: RestoreFrameMode") when a JIT block chain was on the
+  // stack (blocks tail-call across instances), so vm.wasm must choose where it yields.
+  const idleYield = sharing && !!nudge
+  const guard = (fns, skip = () => false) =>
+    Object.fromEntries(
+      Object.entries(fns).map(([k, f]) =>
+        typeof f !== 'function' || (skip(k) && !nudge)
+          ? [k, f]
+          : skip(k)
+            ? [k, (a, b, c, d, e, g, h, i, j) => (nudge(), f(a, b, c, d, e, g, h, i, j))] // the JIT door's compile thread allocates most
+          : // fixed arity, not (...a): an argument array per call is garbage, which WebKit
+            // collects late in a thread holding the guest's memory (W40, D-419). Nine covers
+            // every import (path_open has nine parameters).
+            [k, (a, b, c, d, e, g, h, i, j) => {
+              nudge?.()
+              if (stallHook) maybeStall()
+              if (stopped()) throw new WasiExit(Atomics.load(ctl, CTL_EXIT_CODE))
+              return f(a, b, c, d, e, g, h, i, j)
+            }],
+      ),
+    )
+  const wasiG = guard(wasi, k => k === 'proc_exit')
+  const wmdG = guard(wmd, k => k.startsWith('jit_'))
+  const spawnG = guard({ 'thread-spawn': threadSpawn })
+
+  function instantiate() {
+    const table = new WebAssembly.Table({ element: 'anyfunc', initial: tableMin })
+    // D-419: the imports with i64 parameters go through a wasm shim: JS gets Numbers, no BigInts
+    const instance = new WebAssembly.Instance(module, shimI64Imports({
+      env: { memory, __indirect_function_table: table },
+      // ram_rw and ram_cas stay wasm functions (no guard, no BigInt): a page-table walk calls them
+      wmd: ramImports ? { ...wmdG, ram_rw: ramImports.ram_rw, ram_cas: ramImports.ram_cas } : wmdG,
+      wasi_snapshot_preview1: wasiG,
+      wasi: spawnG,
+    }))
+    if (table.length !== tableMin) throw new Error(`table size ${table.length} after instantiation, want ${tableMin}`)
+    jit?.attach(instance, table)
+    return instance
+  }
+
+  if (role === 'main') {
+    const inst = instantiate()
+    if (typeof inst.exports.vm_heap_top === 'function') heapTopFn = () => Number(inst.exports.vm_heap_top())
+    self.postMessage({ t: 'ready', role, at: performance.timeOrigin + performance.now() })
+    try {
+      if (m.resume) {
+        // P-B9: a restored machine. The page wrote the checkpoint's memory; this is vm.wasm's
+        // resume entry (guest/vm/src/main_wasm.c vm_resume), the way the runner's resume() does it:
+        // bring this thread's table up to date, write the new host ports where the guest reads
+        // them, and call vm_resume instead of _start.
+        // The instance is made on a memory the checkpoint has not touched yet, as the runner's resume() does
+        // (instantiate, then restore the pages): vm.wasm's start function (__wasm_init_memory) initialises the
+        // static data AND this thread's TLS base (__tls_base) only for the first instance on a memory; on a
+        // memory that already holds the checkpoint (its init flag set) it skips both and the main thread would
+        // run with __tls_base 0. The page writes the pages now and wakes us.
+        self.postMessage({ t: 'resume-instantiated' })
+        const r = Atomics.wait(ctl, CTL_CK_RESTORED, 0, 120_000)
+        if (r === 'timed-out') throw new Error('the page did not restore the checkpoint memory in 120 s')
+        if (Atomics.load(ctl, CTL_CK_RESTORED) === 2) throw new Error('the page could not restore the checkpoint memory (see its message)')
+        await jit?.syncAsync()
+        const at = (await enter(inst.exports.vm_resume_args)()) >>> 0
+        const ports = m.resume.ports // net, p9, console, control (0: none), then stats
+        new Int32Array(memory.buffer, at, 5).set([ports.net | 0, ports.p9 | 0, ports.console | 0, ports.control | 0, m.resume.stats ? 1 : 0])
+        const code = await enter(inst.exports.vm_resume)()
+        wasi.proc_exit(code)
+        return
+      }
+      await enter(inst.exports._start)()
+      // wasi-libc's _start always ends in proc_exit; returning means exit(0).
+      wasi.proc_exit(0)
+    } catch (err) {
+      fatal(m, err, 1)
+    }
+    return
+  }
+
+  // Pool Worker: announce, then loop serving spawn requests.
+  Atomics.store(ctl, slotIndex(slot, SLOT_STATE), ST_IDLE)
+  Atomics.add(ctl, CTL_POOL_GEN, 1)
+  Atomics.notify(ctl, CTL_POOL_GEN)
+  self.postMessage({ t: 'ready', role, slot })
+  for (;;) {
+    let work = waitForWork(ctl, slot, 1000, idleYield ? 5 : Infinity)
+    // W32: an idle pool Worker yields to its event loop every 5 s, so WebKit sweeps the
+    // Instance of the thread it ran last (see idleYield above)
+    while (work === undefined) {
+      gcNudge()
+      await new Promise(r => setTimeout(r, 0))
+      work = waitForWork(ctl, slot, 1000, 5)
+    }
+    if (!work) return
+    self.postMessage({ t: 'thread', ev: 'start', tid: work.tid, slot })
+    myTid = work.tid
+    let inst
+    try {
+      inst = instantiate()
+      await jit?.syncAsync() // a new thread's table starts with every live slot (spawn.rs)
+      await enter(inst.exports.wasi_thread_start)(work.tid, work.arg)
+    } catch (err) {
+      fatal(m, err, work.tid)
+      return
+    }
+    threadDone(ctl, slot)
+    self.postMessage({ t: 'thread', ev: 'end', tid: work.tid, slot })
+  }
+}