@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/host/layout.js

@@ -0,0 +1,100 @@
+// Layout of the control SharedArrayBuffer every Worker of one wmd machine shares.
+//
+// All cells are Int32 so Atomics.wait/notify work on them. The control block is
+// tiny and created once per boot by boot.js; Workers get it in their init message
+// and never use postMessage for anything that has to be synchronous (thread spawn,
+// the fd table, the clock base, the exit flag).
+
+export const CTL_NEXT_TID = 0 // last tid handed out; the _start thread is tid 1, first spawn gets 2
+export const CTL_EXIT = 1 // 0 running, 1 proc_exit called (or a thread trapped)
+export const CTL_EXIT_CODE = 2
+export const CTL_POOL_GEN = 3 // bumped by the page every time pool slots are added
+export const CTL_FD_LOCK = 4 // spin lock over the fd table
+export const CTL_POOL_N = 5 // number of pool slots in use (registered Workers)
+export const CTL_SPAWN_FAIL = 6 // count of thread-spawn calls that found no idle Worker
+export const CTL_LIVE_THREADS = 7 // spawned threads currently running
+export const CTL_TRAPS = 8 // threads that trapped (W21 review A2: a trap after an exit 0 still fails the run)
+// P-B8 test hook (bootWmd({stallHook: true}), vm.stallThread): the thread with tid CTL_STALL_TID
+// blocks for CTL_STALL_MS at its next host call, as if the browser had stopped its Worker.
+export const CTL_STALL_TID = 9 // 0: none armed
+export const CTL_STALL_MS = 10
+export const CTL_STALL_TAKEN = 11 // stalls started
+export const CTL_STALL_DONE = 12 // stalls ended
+export const CTL_STALL_WAKE = 13 // the stalled thread waits on this cell; bumped to end a stall early
+export const CTL_MONO_LOCK = 14 // spin lock over F64_LAST_MONO (clock.js)
+
+// Float64 cells (byte offsets, 8-aligned) inside the same buffer.
+export const F64_START_MS = 64 // absolute ms (timeOrigin + now) when the machine started
+export const F64_LAST_MONO = 72 // highest monotonic ns any Worker has returned (a Number, under CTL_MONO_LOCK)
+
+// Counters of calls to the stub wmd.* imports (wmd-imports.js), one Int32 cell per
+// name. A guest in --mode jit calls jit_compile thousands of times a second: counting
+// in shared memory instead of one postMessage per call keeps the page responsive. The
+// page reads them on demand (vm.stats().hostCalls) and in a batched event.
+export const HOST_CALL_NAMES = ['jit_load', 'jit_compile', 'jit_known', 'jit_sync', 'jit_note', 'jit_flush', 'snapshot', 'chan_open']
+export const HOST_CALL_BASE = 20 // Int32 cells 20..27 (bytes 80..111, between F64_LAST_MONO and the pool)
+// P-B8 stall hook: when the last stall started and ended (absolute ms, Float64; bytes 112..127)
+export const F64_STALL_AT = 112
+export const F64_STALL_END = 120
+const HOST_CALL_INDEX = new Map(HOST_CALL_NAMES.map((n, i) => [n, HOST_CALL_BASE + i]))
+
+export function noteHostCall(ctl, name) {
+  const i = HOST_CALL_INDEX.get(name)
+  if (i !== undefined) Atomics.add(ctl, i, 1)
+}
+
+/** {name: count} of the stub calls made so far (only names called at least once). */
+export function hostCallCounts(ctl) {
+  const out = {}
+  for (const [n, i] of HOST_CALL_INDEX) {
+    const c = Atomics.load(ctl, i)
+    if (c) out[n] = c
+  }
+  return out
+}
+
+// Pool slots: SLOT_INTS Int32 cells each.
+export const POOL_BASE = 32
+export const POOL_MAX = 128
+export const SLOT_INTS = 4
+export const SLOT_STATE = 0
+export const SLOT_TID = 1
+export const SLOT_ARG = 2
+export const SLOT_RUNS = 3 // how many threads this Worker has run
+
+export const ST_IDLE = 0 // Worker is waiting for work
+export const ST_CLAIMED = 1 // a spawner owns the slot and is filling tid/arg
+export const ST_GO = 2 // tid/arg written; Worker should start
+export const ST_RUNNING = 3
+export const ST_DEAD = 4 // Worker failed to start or was terminated
+export const ST_STARTING = 5 // slot assigned, Worker not parked yet
+
+// The process-wide WASI fd table: FD_MAX entries of FD_INTS cells.
+export const FD_BASE = POOL_BASE + POOL_MAX * SLOT_INTS
+export const FD_MAX = 64
+export const FD_INTS = 4
+export const FD_KIND = 0 // 0 free, 1 regular file (fds 0-2 are stdio, 3 the preopen; not stored)
+export const FD_FILE = 1 // index into the file list
+export const FD_POS_LO = 2
+export const FD_POS_HI = 3
+
+// P-B9 (checkpoints): after the fd table.
+export const CKPT_BASE = FD_BASE + FD_MAX * FD_INTS
+export const CTL_CK_HOSTREQ = CKPT_BASE // guest address of the machine's host_req word (wmd.ctl_attach); 0: not attached yet
+export const CTL_CK_ATTACHES = CKPT_BASE + 1 // wmd.ctl_attach calls so far (one more after each checkpoint: the vCPUs run again)
+export const CTL_CK_GO = CKPT_BASE + 2 // page -> vCPU 0 inside wmd.point: 0 wait, 1 return 0 (taken), 2 return -1 (failed)
+export const CTL_CK_POINTS = CKPT_BASE + 3 // wmd.point calls so far
+export const CTL_CK_RESTORED = CKPT_BASE + 4 // restore: the page has written the checkpoint's memory; the main thread may call vm_resume (1)
+
+export const CTL_INTS = CKPT_BASE + 8
+export const CTL_BYTES = CTL_INTS * 4
+
+export const slotIndex = (slot, field) => POOL_BASE + slot * SLOT_INTS + field
+export const fdIndex = (fd, field) => FD_BASE + fd * FD_INTS + field
+
+export function createControl() {
+  const sab = new SharedArrayBuffer(CTL_BYTES)
+  const ctl = new Int32Array(sab)
+  ctl[CTL_NEXT_TID] = 1
+  return sab
+}

package/src/host/monitor.js

@@ -0,0 +1,110 @@
+// Page-side monitors of a running machine (no wasm, no Workers; unit-tested):
+//
+//   createPanicScanner  finds "Kernel panic - not syncing" in the console, so a panic
+//                       the guest maps to exit 0 (PSCI SYSTEM_RESET) is reported as a failure.
+//   createWatchdog      "the guest made no progress": no console output and no new
+//                       threads for limitMs after the vCPU started.
+//   createThrottleMeter compares a fixed calibration loop (run in its own Worker,
+//                       calib-worker.js) against the fastest run seen: when the browser
+//                       deprioritises the page's process (a minimised window), every
+//                       Worker slows down and so does the guest.
+
+const PANIC_RE = /Kernel panic - not syncing/
+
+export function createPanicScanner() {
+  let buf = ''
+  const s = {
+    line: null,
+    /** Feed console text; returns the panic line the first time one completes. */
+    push(text) {
+      if (s.line) return null
+      buf += text
+      let nl
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const l = buf.slice(0, nl).replace(/\r$/, '')
+        buf = buf.slice(nl + 1)
+        if (PANIC_RE.test(l)) {
+          s.line = l
+          buf = ''
+          return l
+        }
+      }
+      if (buf.length > 4096) buf = buf.slice(-256) // a very long line: keep a tail only
+      return null
+    },
+  }
+  return s
+}
+
+/**
+ * Default no-progress limit for a boot's argv. Interpreter boots of the arm64 kernel
+ * write to the console at least every few seconds; the amd64 decompressor is silent for
+ * about 75 s in Chromium (more in Firefox), so x86 gets 300 s. User-mode programs may
+ * legitimately run silent: off.
+ */
+export function watchdogDefaultMs(args) {
+  if (!args.includes('--machine')) return 0
+  const i = args.indexOf('--arch')
+  return i >= 0 && args[i + 1] === 'x86' ? 300_000 : 60_000
+}
+
+/**
+ * @param {{limitMs:number, tickMs?:number, now?:()=>number}} o
+ * check(ratio) is called every tickMs; returns true once nothing has progressed for
+ * limitMs * max(1, ratio). A check that comes much later than tickMs means the page's
+ * own thread was stalled (messages from the Workers were not delivered either), so
+ * the silence count restarts.
+ */
+export function createWatchdog({ limitMs, tickMs = 250, now = () => performance.now() }) {
+  let armed = false
+  let last = 0
+  let lastCheck = 0
+  return {
+    start() {
+      armed = limitMs > 0
+      last = lastCheck = now()
+    },
+    progress() {
+      last = now()
+    },
+    idleMs: () => now() - last,
+    check(ratio = 1) {
+      if (!armed) return false
+      const t = now()
+      const gap = t - lastCheck
+      lastCheck = t
+      if (gap > 4 * tickMs + 1000) last = t // page stalled: give the guest the benefit of the doubt
+      return t - last > limitMs * Math.max(1, ratio)
+    },
+  }
+}
+
+/**
+ * @param {{threshold?:number, window?:number, baselineMs?:number}} o
+ * sample(ms) takes one calibration time. ratio = median of the last `window` samples /
+ * the best (lowest) time seen, including an optional baseline from an earlier run.
+ * Returns {changed, ...state}; state().throttled flips when the ratio crosses threshold.
+ */
+export function createThrottleMeter({ threshold = 2, window = 3, baselineMs } = {}) {
+  let best = baselineMs > 0 ? baselineMs : Infinity
+  const recent = []
+  const st = { throttled: false, ratio: 1, maxRatio: 1, sampleMs: null, baselineMs: null, samples: 0, throttledSamples: 0 }
+  return {
+    sample(ms) {
+      best = Math.min(best, ms)
+      recent.push(ms)
+      if (recent.length > window) recent.shift()
+      const med = [...recent].sort((a, b) => a - b)[recent.length >> 1]
+      st.samples++
+      st.sampleMs = ms
+      st.baselineMs = best
+      st.ratio = Math.round((med / best) * 100) / 100
+      st.maxRatio = Math.max(st.maxRatio, st.ratio)
+      const was = st.throttled
+      st.throttled = recent.length >= Math.min(window, 2) && st.ratio >= threshold
+      if (st.throttled) st.throttledSamples++
+      return { changed: was !== st.throttled, ...st }
+    },
+    state: () => ({ ...st }),
+  }
+}

package/src/host/p9mount.js

@@ -0,0 +1,27 @@
+// The 9P mount options the browser guest uses for its root (P-B3/P-B4 adversarial F1).
+//
+// cache=mmap, not the native engine's cache=loose. Linux 6.1's v9fs with cache=loose
+// writes into the page cache and sends the data later, one 4 KiB page per Twrite
+// (fs/9p/vfs_addr.c v9fs_vfs_writepage). When the server refuses that write (the upper's
+// memory cap: ENOSPC, or any other error but EAGAIN) the page is dropped, the error is
+// only recorded for a later fsync(2)/close(2) (mapping_set_error), and write(2) never
+// fails: a writer that does not fsync loses its data silently, and one past the dirty
+// limit sits in balance_dirty_pages while writeback drains the failing pages one round
+// at a time. The cap therefore cannot be enforced at write(2) under cache=loose. With
+// cache=mmap (and cache=none) write(2) is a Twrite of up to msize bytes
+// (v9fs_file_write_iter), so ENOSPC reaches the writer at once; mmap keeps shared
+// writable mappings working (cache=none refuses them with EINVAL, wmd D-062).
+// The measurements behind the choice are in README "P-B3/P-B4 adversarial review".
+
+export const P9_CACHE_DEFAULT = 'mmap'
+export const P9_MSIZE_DEFAULT = 262144
+
+/** "trans=virtio,version=9p2000.L,msize=...,cache=..." for mount -t 9p. */
+export function p9MountOptions({ msize = P9_MSIZE_DEFAULT, cache = P9_CACHE_DEFAULT } = {}) {
+  return `trans=virtio,version=9p2000.L,msize=${msize},cache=${cache}`
+}
+
+/** Kernel command line words for wmd's Go init (cmdline.go wmd.p9msize / wmd.p9cache). */
+export function p9InitCmdline({ msize = P9_MSIZE_DEFAULT, cache = P9_CACHE_DEFAULT } = {}) {
+  return `wmd.p9msize=${msize} wmd.p9cache=${cache}`
+}

package/src/host/ram-mem.js

@@ -0,0 +1,125 @@
+// Guest RAM outside memory 0: the flat layout (guest/vm/include/vm/ram.h).
+//
+// vm.wasm's memory 0 is a wasm32 memory: 4 GiB at most, for guest RAM and the emulator's own
+// heap, so a browser guest stopped at 1536 MiB (boot.js MAX_BROWSER_RAM_MIB). With a memory64
+// the page makes a second shared memory that holds all of guest RAM. Translated code imports it
+// as env.win and reads it with 64-bit addresses; vm.wasm's C code, which can only address memory
+// 0, reaches it through wmd.ram_rw and wmd.ram_cas. Those two are exports of a small wasm module
+// made here (memory.copy between the two memories, a compare-and-swap on the RAM memory): a
+// wasm-to-wasm call, so no i64 argument becomes a BigInt (D-419) and a page-table walk pays a
+// call, not a trip through JS.
+
+const PAGE = 65536
+
+/** Whether this engine makes a shared 64-bit memory (Chrome 133, Firefox 134; not Safari). */
+export function haveMemory64() {
+  try {
+    const m = new WebAssembly.Memory({ address: 'i64', initial: 1n, maximum: 1n, shared: true })
+    return m.buffer instanceof SharedArrayBuffer && m.buffer.byteLength === PAGE
+  } catch {
+    return false
+  }
+}
+
+/** The shared memory64 that holds a guest's RAM of `mib` MiB. Throws when the engine cannot make it. */
+export function createRamMemory(mib) {
+  const pages = BigInt(mib) * 16n
+  try {
+    return new WebAssembly.Memory({ address: 'i64', initial: pages, maximum: pages, shared: true })
+  } catch (err) {
+    throw new Error(`--ram ${mib}: the browser could not make a ${mib} MiB memory for the guest (${err && err.message ? err.message : err})`)
+  }
+}
+
+const leb = n => {
+  // unsigned LEB128 of a Number (exact to 2^53)
+  const o = []
+  do {
+    let b = n % 128
+    n = Math.floor(n / 128)
+    if (n) b |= 0x80
+    o.push(b)
+  } while (n)
+  return o
+}
+const vec = items => [...leb(items.length), ...items.flat()]
+const str = s => vec([...new TextEncoder().encode(s)].map(b => [b]))
+const sec = (id, body) => [id, ...leb(body.length), ...body]
+const I32 = 0x7f
+const I64 = 0x7e
+
+/**
+ * The helper module's bytes, for a RAM memory of `pages` 64 KiB pages:
+ *   (import "env" "memory" (memory 0 65536 shared))
+ *   (import "env" "ram" (memory i64 pages pages shared))
+ *   (func (export "ram_rw") (param $off i64) (param $ptr i32) (param $len i32) (param $write i32) (result i32))
+ *   (func (export "ram_cas") (param $off i64) (param $size i32) (param $expect i64) (param $desired i64) (result i64))
+ */
+export function ramHelperBytes(pages) {
+  const get = i => [0x20, i]
+  const copy = (dst, src) => [0xfc, 0x0a, dst, src]
+  const rw = [
+    0x00, // no locals
+    ...get(3), 0x04, 0x40, // if write
+    ...get(0), ...get(1), ...get(2), ...copy(1, 0),
+    0x05, // else
+    ...get(1), ...get(0), ...get(2), ...copy(0, 1),
+    0x0b,
+    0x41, 0x00, // i32.const 0
+    0x0b,
+  ]
+  // cmpxchg on memory 1: opcode, then memarg (align | 0x40: a memory index follows), index, offset
+  const cx = (op, align) => [...get(0), ...get(2), ...get(3), 0xfe, op, align | 0x40, 0x01, 0x00]
+  const is = n => [...get(1), 0x41, n, 0x46, 0x04, I64] // if (size == n) (result i64)
+  const cas = [
+    0x00,
+    ...is(8), ...cx(0x49, 3),
+    0x05, ...is(4), ...cx(0x4e, 2),
+    0x05, ...is(2), ...cx(0x4d, 1),
+    0x05, ...cx(0x4c, 0),
+    0x0b, 0x0b, 0x0b,
+    0x0b,
+  ]
+  const body = b => [...leb(b.length), ...b]
+  return new Uint8Array([
+    0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
+    ...sec(1, vec([
+      [0x60, ...vec([[I64], [I32], [I32], [I32]]), ...vec([[I32]])],
+      [0x60, ...vec([[I64], [I32], [I64], [I64]]), ...vec([[I64]])],
+    ])),
+    ...sec(2, vec([
+      [...str('env'), ...str('memory'), 0x02, 0x03, ...leb(0), ...leb(65536)],
+      [...str('env'), ...str('ram'), 0x02, 0x07, ...leb(pages), ...leb(pages)],
+    ])),
+    ...sec(3, vec([[0], [1]])),
+    ...sec(7, vec([
+      [...str('ram_rw'), 0x00, 0],
+      [...str('ram_cas'), 0x00, 1],
+    ])),
+    ...sec(10, vec([body(rw), body(cas)])),
+  ])
+}
+
+let helperModule = null // one compile per thread; the page size is in the bytes
+let helperPages = -1
+
+/**
+ * vm.wasm's wmd.ram_map2, wmd.ram_rw and wmd.ram_cas for a machine whose RAM is `ram` (a shared
+ * memory64, createRamMemory) and whose memory 0 is `memory`. ram_rw and ram_cas are wasm
+ * functions: hand them to vm.wasm as they are, not through a JS wrapper.
+ */
+export function createRamImports({ memory, ram }) {
+  const bytes = ram.buffer.byteLength
+  const pages = bytes / PAGE
+  if (!helperModule || helperPages !== pages) {
+    helperModule = new WebAssembly.Module(ramHelperBytes(pages))
+    helperPages = pages
+  }
+  const { exports } = new WebAssembly.Instance(helperModule, { env: { memory, ram } })
+  return {
+    // 1: the RAM memory exists and memory 0 does not show it (the flat layout); -1: a size vm.wasm did not get
+    ram_map2: (_off, _lowLen, total) => (Number(total) === bytes ? 1 : -1),
+    ram_rw: exports.ram_rw,
+    ram_cas: exports.ram_cas,
+  }
+}

package/src/host/stdio.js

@@ -0,0 +1,143 @@
+// stdout/stderr from every Worker to the page through one SharedArrayBuffer: a byte ring
+// per fd. Writers (any thread, inside fd_write) copy under a spin lock and move the
+// fd's write position; the page drains on a timer. No postMessage per write: a guest
+// that writes megabytes a second (vm.wasm dumping the IR of every block whose compile
+// failed) cannot flood the page's event loop. If the page falls a full ring behind, it
+// skips to the newest ring's worth of bytes and counts what it skipped; stdioText()
+// (what bootWmd delivers) then puts a visible marker line into the text at that point.
+//
+// The ring size is a power of two per fd, set by createStdio(ringBytes) and stored in
+// the header, so writers and the reader agree on it. RING (4 MiB) is the library
+// default; bootWmd uses BOOT_RING (32 MiB, see there).
+
+export const RING = 1 << 22 // default bytes per fd for createStdio()
+// bootWmd's default. The guest console runs at about 0.33 MB/s in JIT mode, so 32 MiB
+// covers a page that serves no events for about 100 s: a 10-25 s main-thread stall, or
+// Chromium's intensive throttling of hidden tabs (timers run once a minute after 5
+// minutes hidden). It costs 64 MiB of SharedArrayBuffer (pages are touched only as
+// the ring fills), against the guest's 640 MiB shared memory.
+export const BOOT_RING = 1 << 25
+const H_LOCK = 0
+const H_W1 = 1 // bytes ever written to fd 1, mod 2^32
+const H_W2 = 2 // ... fd 2
+const H_RING = 3 // ring bytes per fd
+const F_FIRST = 2 // Float64 index (byte 16): absolute ms of the first stdout byte
+const HDR = 32
+
+/** The text put into a delivered stream where `n` bytes were skipped. */
+export const dropMarker = (n, fd) => `\n[wmd-web: ${n} bytes of ${fd === 2 ? 'stderr' : 'stdout'} were dropped]\n`
+/** Matches a dropMarker line (boot gates fail on it). */
+export const DROP_MARKER_RE = /\[wmd-web: (\d+) bytes of (stdout|stderr) were dropped\]/
+
+export function createStdio(ringBytes = RING) {
+  if (!(ringBytes >= 4096 && ringBytes <= 1 << 30 && (ringBytes & (ringBytes - 1)) === 0)) {
+    throw new Error(`stdio ring size must be a power of two from 4 KiB to 1 GiB, got ${ringBytes}`)
+  }
+  const sab = new SharedArrayBuffer(HDR + 2 * ringBytes)
+  new Int32Array(sab, 0, HDR / 4)[H_RING] = ringBytes
+  return sab
+}
+
+const ringOf = sab => new Int32Array(sab, 0, HDR / 4)[H_RING] || RING
+
+/** Writer side (a Worker): returns write(fd, bytes) for fds 1 and 2. */
+export function stdioWriter(sab, now = () => performance.timeOrigin + performance.now()) {
+  const hdr = new Int32Array(sab, 0, HDR / 4)
+  const f64 = new Float64Array(sab, 0, HDR / 8)
+  const RING = ringOf(sab)
+  const rings = { 1: new Uint8Array(sab, HDR, RING), 2: new Uint8Array(sab, HDR + RING, RING) }
+  return function write(fd, bytes) {
+    const ring = rings[fd]
+    if (!ring || !bytes.length) return
+    const src = bytes.length > RING ? bytes.subarray(bytes.length - RING) : bytes
+    const skipped = bytes.length - src.length
+    while (Atomics.compareExchange(hdr, H_LOCK, 0, 1) !== 0) {}
+    try {
+      const cell = fd === 1 ? H_W1 : H_W2
+      const w = (Atomics.load(hdr, cell) >>> 0) + skipped
+      const at = w % RING
+      const first = Math.min(src.length, RING - at)
+      ring.set(src.subarray(0, first), at)
+      if (first < src.length) ring.set(src.subarray(first), 0)
+      if (fd === 1 && f64[F_FIRST] === 0) f64[F_FIRST] = now()
+      Atomics.store(hdr, cell, (w + src.length) | 0)
+    } finally {
+      Atomics.store(hdr, H_LOCK, 0)
+    }
+  }
+}
+
+/** Reader side (the page): drain() returns {1: Uint8Array, 2: Uint8Array} of new bytes. */
+export function stdioReader(sab) {
+  const hdr = new Int32Array(sab, 0, HDR / 4)
+  const f64 = new Float64Array(sab, 0, HDR / 8)
+  const RING = ringOf(sab)
+  const rings = { 1: new Uint8Array(sab, HDR, RING), 2: new Uint8Array(sab, HDR + RING, RING) }
+  const read = { 1: 0, 2: 0 }
+  const dropped = { 1: 0, 2: 0 }
+  function take(fd) {
+    const w = Atomics.load(hdr, fd === 1 ? H_W1 : H_W2) >>> 0
+    let avail = (w - read[fd]) >>> 0
+    if (!avail) return null
+    if (avail > RING) {
+      dropped[fd] += avail - RING
+      avail = RING
+    }
+    const start = (w - avail) >>> 0
+    const at = start % RING
+    const out = new Uint8Array(avail)
+    const first = Math.min(avail, RING - at)
+    out.set(rings[fd].subarray(at, at + first), 0)
+    if (first < avail) out.set(rings[fd].subarray(0, avail - first), first)
+    // a writer may have wrapped over what we just copied: re-check and drop that part
+    const w2 = Atomics.load(hdr, fd === 1 ? H_W1 : H_W2) >>> 0
+    const over = ((w2 - start) >>> 0) - RING
+    read[fd] = w
+    if (over >= avail) {
+      dropped[fd] += avail
+      return null
+    }
+    if (over > 0) {
+      dropped[fd] += over
+      return out.subarray(over)
+    }
+    return out
+  }
+  return {
+    drain: () => ({ 1: take(1), 2: take(2) }),
+    firstStdoutAt: () => f64[F_FIRST] || undefined,
+    dropped,
+    ringBytes: RING,
+  }
+}
+
+/**
+ * Text side of a reader (what bootWmd delivers): drain() returns {1: string, 2: string}
+ * decoded with streaming TextDecoders. Where the reader skipped bytes, the text has a
+ * dropMarker line at that point, so the loss is visible in the stream itself (a gate
+ * line can never vanish silently). `skips` counts the marker lines per fd.
+ */
+export function stdioText(reader) {
+  const dec = { 1: new TextDecoder(), 2: new TextDecoder() }
+  const seen = { 1: 0, 2: 0 }
+  const skips = { 1: 0, 2: 0 }
+  const one = (fd, bytes) => {
+    let text = ''
+    const lost = reader.dropped[fd] - seen[fd]
+    if (lost > 0) {
+      seen[fd] = reader.dropped[fd]
+      skips[fd]++
+      // what the decoder held belonged to bytes before the skip: end that sequence
+      text = dec[fd].decode() + dropMarker(lost, fd)
+    }
+    if (bytes) text += dec[fd].decode(bytes, { stream: true })
+    return text
+  }
+  return {
+    drain() {
+      const got = reader.drain()
+      return { 1: one(1, got[1]), 2: one(2, got[2]) }
+    },
+    skips,
+  }
+}

package/src/host/threads.js

@@ -0,0 +1,109 @@
+// wasi.thread-spawn over a pool of pre-started Workers (host-interface.md §6).
+//
+// thread-spawn is called from inside wasm on a Worker that cannot return to its
+// event loop, and it must return the new tid synchronously. So the page starts
+// Workers ahead of time; each one has the compiled vm.wasm Module and parks on its
+// slot in the control buffer with Atomics.wait. Spawning claims an idle slot with a
+// compare-exchange, writes tid and start_arg, flips the slot to GO and notifies.
+//
+// If no slot is idle the spawner asks the page for more Workers (postMessage is
+// fine from a busy Worker: the page's event loop is free) and waits on the pool
+// generation cell for up to `waitMs`; if still none it returns -11 (EAGAIN), which
+// pthread_create reports as a failure, and the page shows "thread pool exhausted".
+
+import {
+  CTL_EXIT,
+  CTL_LIVE_THREADS,
+  CTL_NEXT_TID,
+  CTL_POOL_GEN,
+  CTL_POOL_N,
+  CTL_SPAWN_FAIL,
+  SLOT_ARG,
+  SLOT_RUNS,
+  SLOT_STATE,
+  SLOT_TID,
+  ST_CLAIMED,
+  ST_GO,
+  ST_IDLE,
+  ST_RUNNING,
+  slotIndex,
+} from './layout.js'
+
+export const EAGAIN = -11
+
+/** Count slots in a given state (used by the page to keep spare Workers). */
+export function countSlots(ctl, state) {
+  const n = Atomics.load(ctl, CTL_POOL_N)
+  let c = 0
+  for (let i = 0; i < n; i++) if (Atomics.load(ctl, slotIndex(i, SLOT_STATE)) === state) c++
+  return c
+}
+
+function claimIdle(ctl) {
+  const n = Atomics.load(ctl, CTL_POOL_N)
+  for (let i = 0; i < n; i++) {
+    if (Atomics.compareExchange(ctl, slotIndex(i, SLOT_STATE), ST_IDLE, ST_CLAIMED) === ST_IDLE) return i
+  }
+  return -1
+}
+
+/**
+ * The `wasi.thread-spawn` import.
+ * @param {Int32Array} ctl
+ * @param {{ requestWorkers:(why:string)=>void, waitMs?:number }} o
+ */
+export function createThreadSpawn(ctl, { requestWorkers, waitMs = 10000 }) {
+  return function threadSpawn(startArg) {
+    let slot = claimIdle(ctl)
+    if (slot < 0) {
+      const deadline = Date.now() + waitMs
+      requestWorkers('no idle worker')
+      while (slot < 0 && Date.now() < deadline && !Atomics.load(ctl, CTL_EXIT)) {
+        const gen = Atomics.load(ctl, CTL_POOL_GEN)
+        slot = claimIdle(ctl)
+        if (slot >= 0) break
+        Atomics.wait(ctl, CTL_POOL_GEN, gen, Math.max(1, deadline - Date.now()))
+        slot = claimIdle(ctl)
+      }
+      if (slot < 0) {
+        Atomics.add(ctl, CTL_SPAWN_FAIL, 1)
+        requestWorkers('exhausted')
+        return EAGAIN
+      }
+    }
+    const tid = Atomics.add(ctl, CTL_NEXT_TID, 1) + 1
+    Atomics.store(ctl, slotIndex(slot, SLOT_TID), tid)
+    Atomics.store(ctl, slotIndex(slot, SLOT_ARG), startArg)
+    Atomics.add(ctl, CTL_LIVE_THREADS, 1)
+    Atomics.store(ctl, slotIndex(slot, SLOT_STATE), ST_GO)
+    Atomics.notify(ctl, slotIndex(slot, SLOT_STATE))
+    // Keep spares: the page tops the pool up asynchronously.
+    requestWorkers('spawned')
+    return tid
+  }
+}
+
+/**
+ * Park a pool Worker until a spawn request arrives. Returns {tid, arg}, or null once
+ * the machine has exited. Wakes every `pollMs` to notice an exit; after `maxPolls` waits
+ * with no work it returns undefined.
+ */
+export function waitForWork(ctl, slot, pollMs = 1000, maxPolls = Infinity) {
+  const st = slotIndex(slot, SLOT_STATE)
+  for (let n = 0; ; n++) {
+    const s = Atomics.load(ctl, st)
+    if (s === ST_GO) break
+    if (Atomics.load(ctl, CTL_EXIT)) return null
+    if (n >= maxPolls) return undefined // no work yet (W32: the caller yields to its event loop, then waits again)
+    Atomics.wait(ctl, st, s, pollMs)
+  }
+  Atomics.store(ctl, st, ST_RUNNING)
+  Atomics.add(ctl, slotIndex(slot, SLOT_RUNS), 1)
+  return { tid: Atomics.load(ctl, slotIndex(slot, SLOT_TID)), arg: Atomics.load(ctl, slotIndex(slot, SLOT_ARG)) }
+}
+
+/** A pool Worker finished a thread: make the slot reusable. */
+export function threadDone(ctl, slot) {
+  Atomics.sub(ctl, CTL_LIVE_THREADS, 1)
+  Atomics.store(ctl, slotIndex(slot, SLOT_STATE), ST_IDLE)
+}