@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/host/base-io.js

@@ -0,0 +1,93 @@
+// P-B6: the base snapshot cache's Worker: one OPFS file per base snapshot in the directory `wmd-base`, written through
+// FileSystemSyncAccessHandle (the one OPFS write API all three browsers give a Worker). The page reads a cached file with
+// getFile().stream() (base-cache.js).
+//
+// in:  {id, op:'open', name}              -> {}   creates (or empties) the file; an earlier open handle of this Worker is closed
+//      {id, op:'write', name, at, buf}    -> {}   (buf is transferred)
+//      {id, op:'commit', name, magic}     -> {}   flush, then the 8 magic bytes at 0 (the file is valid only from here)
+//      {id, op:'abort', name}             -> {}   close and delete
+//      {id, op:'list'}                    -> {items:[{name,size}]}
+//      {id, op:'delete', name} | {id, op:'clear'}
+// out: {id, ok:true, ...} or {id, ok:false, code, error}
+const DIR = 'wmd-base'
+const handles = new Map()
+async function dir() {
+  return (await navigator.storage.getDirectory()).getDirectoryHandle(DIR, { create: true })
+}
+const check = n => {
+  if (!/^[A-Za-z0-9._-]{1,120}$/.test(n) || n.startsWith('.')) throw Object.assign(new Error(`bad cache file name ${JSON.stringify(n)}`), { code: 'malformed' })
+  return n
+}
+function writeAll(h, u8, at) {
+  let done = 0
+  while (done < u8.length) {
+    const n = h.write(done ? u8.subarray(done) : u8, { at: at + done })
+    if (!(n > 0)) throw Object.assign(new Error(`write stopped at ${at + done} (storage full?)`), { code: 'quota' })
+    done += n
+  }
+}
+async function handle(m) {
+  switch (m.op) {
+    case 'open': {
+      const name = check(m.name)
+      handles.get(name)?.close()
+      handles.delete(name)
+      const h = await (await (await dir()).getFileHandle(name, { create: true })).createSyncAccessHandle()
+      h.truncate(0)
+      handles.set(name, h)
+      return {}
+    }
+    case 'write': {
+      const h = handles.get(check(m.name))
+      if (!h) throw Object.assign(new Error(`cache file ${m.name} is not open`), { code: 'io' })
+      writeAll(h, new Uint8Array(m.buf), m.at)
+      return {}
+    }
+    case 'commit': {
+      const name = check(m.name)
+      const h = handles.get(name)
+      if (!h) throw Object.assign(new Error(`cache file ${name} is not open`), { code: 'io' })
+      h.flush()
+      writeAll(h, new Uint8Array(m.magic), 0)
+      h.flush()
+      h.close()
+      handles.delete(name)
+      return {}
+    }
+    case 'abort': {
+      const name = check(m.name)
+      try {
+        handles.get(name)?.close()
+      } catch {}
+      handles.delete(name)
+      await (await dir()).removeEntry(name).catch(() => {})
+      return {}
+    }
+    case 'list': {
+      const d = await dir()
+      const items = []
+      for await (const [n, fh] of d.entries()) items.push({ name: n, size: (await fh.getFile()).size })
+      return { items }
+    }
+    case 'delete':
+      for (const [n, h] of handles) if (n === m.name) (h.close(), handles.delete(n))
+      await (await dir()).removeEntry(check(m.name)).catch(() => {})
+      return {}
+    case 'clear': {
+      for (const h of handles.values()) try { h.close() } catch {}
+      handles.clear()
+      await (await navigator.storage.getDirectory()).removeEntry(DIR, { recursive: true }).catch(() => {})
+      return {}
+    }
+    default:
+      throw new Error(`base-io: unknown op ${m.op}`)
+  }
+}
+self.onmessage = async e => {
+  const m = e.data
+  try {
+    self.postMessage({ id: m.id, ok: true, ...(await handle(m)) })
+  } catch (err) {
+    self.postMessage({ id: m.id, ok: false, code: err.code || (err.name === 'QuotaExceededError' ? 'quota' : 'io'), error: err && err.message ? `${err.name}: ${err.message}` : String(err) })
+  }
+}

package/src/host/boot-events.js

@@ -0,0 +1,209 @@
+// W24: the start-up events bootWmd's onEvent gets for wmn's engine start-up screen (wmn D-211, ROADMAP 7.14).
+//
+//   {t:'boot', stage:'download', state:'progress'|'done', file, bytes, total, cached, atMs, tookMs?}   per file
+//   {t:'boot', stage:'download', state:'done', fileBytes, layerBytes, atMs, tookMs}                    all files in
+//   {t:'boot', stage:'compile', state:'start'|'done', moduleBytes, reused, atMs, tookMs?}
+//   {t:'boot', stage:'memory', state:'done', initialBytes, maxBytes, ringBytes, atMs, tookMs}
+//   {t:'boot', stage:'workers', state:'progress'|'done', workers:[{id, role, state, atMs, tid?}], vcpus, jitShared, atMs, tookMs?}
+//   {t:'boot', stage:'kernel', state:'start'|'done', atMs, tookMs?}
+//   {t:'boot', stage:'restore', state:'progress'|'done', bytes, total, source, atMs, tookMs?}
+//   {t:'boot', stage:'control', state:'done', atMs, tookMs}
+//   {t:'heap', bytes, maxBytes, atMs}
+//   {t:'layer', port, usedBytes, capBytes, kind, atMs}
+//   {t:'exit', code, reason, oom, atMs}
+//
+// atMs: milliseconds from bootWmd's t0, on the page's clock; tookMs: the stage's own duration. Sizes are bytes.
+// Progress-like events (download and restore progress, workers progress, heap, layer) are sent at most `perSec` times a
+// second per kind (a download's kind is its file, a layer's its port): the latest one waits and goes out when the
+// interval allows, and a 'start' or 'done' of the same kind replaces a waiting one. Every other event goes out at once.
+
+export function createBootEvents({ emit, t0, now, perSec = 4 }) {
+  const gap = 1000 / perSec
+  const kinds = new Map() // kind -> {last, pending, timer}
+  let closed = false
+  const at = () => Math.round(now() - t0)
+
+  function send(e) {
+    if (closed) return
+    try {
+      emit(e)
+    } catch {} // a caller's handler that throws must not break the boot
+  }
+  function flush(k) {
+    const s = kinds.get(k)
+    s.timer = 0
+    if (!s.pending) return
+    const e = s.pending
+    s.pending = null
+    s.last = now()
+    send(e)
+  }
+  /** A progress-like event: throttled per kind. */
+  function progress(kind, e) {
+    if (closed) return
+    let s = kinds.get(kind)
+    if (!s) kinds.set(kind, (s = { last: -Infinity, pending: null, timer: 0 }))
+    const ev = { ...e, atMs: at() }
+    const wait = s.last + gap - now()
+    if (wait <= 0 && !s.timer) {
+      s.last = now()
+      send(ev)
+      return
+    }
+    s.pending = ev
+    if (!s.timer) s.timer = setTimeout(() => flush(kind), Math.max(0, wait))
+  }
+  /** An event that always goes out now; a waiting progress event of the same kind is dropped (this one supersedes it). */
+  function now_(kind, e) {
+    if (closed) return
+    const s = kinds.get(kind)
+    if (s) {
+      clearTimeout(s.timer)
+      s.timer = 0
+      s.pending = null
+    }
+    send({ ...e, atMs: at() })
+  }
+  /** Stop: waiting events are dropped, nothing more is sent. */
+  function close() {
+    for (const s of kinds.values()) clearTimeout(s.timer)
+    kinds.clear()
+    closed = true
+  }
+  return { progress, now: now_, close, at }
+}
+
+/**
+ * The name a boot file gets in download events: "kernel" or "initramfs" when vm.wasm's --kernel or --initrd names it (as
+ * `${preopen}/${path}`), otherwise its preopen path.
+ */
+export function bootFileName(path, args, preopen) {
+  const full = `${preopen.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`
+  for (let i = 0; i + 1 < args.length; i++) {
+    if (args[i + 1] !== full) continue
+    if (args[i] === '--kernel') return 'kernel'
+    if (args[i] === '--initrd') return 'initramfs'
+  }
+  return path
+}
+
+/** vCPUs vm.wasm runs: its --cpus (default 1), clamped to 1..64 as vm.wasm does (main_wasm.c, VM_MAX_VCPUS). */
+export function vcpusOf(args) {
+  let n = 1
+  for (let i = 0; i + 1 < args.length; i++) if (args[i] === '--cpus') n = parseInt(args[i + 1], 10) || 0
+  return Math.max(1, Math.min(64, n))
+}
+
+/**
+ * Whether a response came without the network, from the page's Resource Timing entry for `url`: true when the body arrived
+ * with nothing transferred (a service worker's Cache Storage; bootWmd's fetches bypass the HTTP cache), false when bytes
+ * were transferred, null when the browser has no entry to say (a full timing buffer, a browser that does not record it).
+ * Firefox and WebKit report a service worker's cached response with decodedBodySize 0 too (W24 probe, page/w24/), as every
+ * browser does for a cross-origin file without Timing-Allow-Origin: so a zero-size entry counts as cached only when the
+ * response was same-origin (`finalUrl`, after redirects) and `bytes` were read.
+ */
+export function cachedFromTiming(url, { bytes = 0, finalUrl = url, before = 0 } = {}, perf = globalThis.performance) {
+  let list
+  let sameOrigin = false
+  try {
+    const base = globalThis.location?.href
+    list = perf?.getEntriesByName?.(new URL(url, base).href, 'resource')
+    sameOrigin = !!globalThis.location && new URL(finalUrl || url, base).origin === globalThis.location.origin
+  } catch {
+    return null
+  }
+  // `before`: the entries for this URL before this fetch (timingCount): an earlier boot's entry is not this one's
+  const e = list && list.length > before ? list[list.length - 1] : null
+  if (!e || typeof e.transferSize !== 'number') return null
+  if (e.transferSize > 0) return false
+  if (e.decodedBodySize > 0) return true
+  return sameOrigin && bytes > 0 ? true : null
+}
+
+/** How many Resource Timing entries the page holds for `url` now (cachedFromTiming's `before`). */
+export function timingCount(url, perf = globalThis.performance) {
+  try {
+    return perf?.getEntriesByName?.(new URL(url, globalThis.location?.href).href, 'resource')?.length ?? 0
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Read a response's body, calling onBytes(received, total) as it comes. total is the Content-Length when the body is not
+ * content-encoded (an encoded length is not the decoded size), else null. Returns a SharedArrayBuffer (shared) or an
+ * ArrayBuffer of the body.
+ */
+export async function readBody(r, { shared, onBytes }) {
+  const enc = r.headers.get('content-encoding')
+  const lenHdr = r.headers.get('content-length')
+  const len = lenHdr === null || lenHdr.trim() === '' ? NaN : Number(lenHdr)
+  const total = (!enc || enc === 'identity') && Number.isSafeInteger(len) && len >= 0 ? len : null
+  if (!r.body || !r.body.getReader) {
+    const ab = await r.arrayBuffer()
+    onBytes?.(ab.byteLength, total)
+    return shared ? toSab(new Uint8Array(ab)) : ab
+  }
+  const rd = r.body.getReader()
+  const parts = []
+  let n = 0
+  onBytes?.(0, total)
+  for (;;) {
+    const { done, value } = await rd.read()
+    if (done) break
+    parts.push(value)
+    n += value.byteLength
+    onBytes?.(n, total)
+  }
+  const buf = shared ? new SharedArrayBuffer(n) : new ArrayBuffer(n)
+  const u8 = new Uint8Array(buf)
+  let off = 0
+  for (const p of parts) {
+    u8.set(p, off)
+    off += p.byteLength
+  }
+  return buf
+}
+
+function toSab(u8) {
+  const sab = new SharedArrayBuffer(u8.byteLength)
+  new Uint8Array(sab).set(u8)
+  return sab
+}
+
+/**
+ * The Workers list of the 'workers' stage. roles: 'vcpu' (the main Worker: vCPU 0), 'pool' (a thread-pool Worker, which
+ * runs the guest's other threads: further vCPUs and vm.wasm's own threads; tid is the guest thread it runs now), 'jit-hub',
+ * 'chan-service', 'net'. onChange(list, allReady) after each change.
+ */
+export function createWorkerList(at) {
+  const ws = new Map()
+  return {
+    set(id, role, state, extra) {
+      const w = ws.get(id) || { id, role }
+      const next = { ...w, ...extra, role, state, atMs: at() }
+      if (next.tid === undefined) delete next.tid
+      ws.set(id, next)
+    },
+    tid(id, tid) {
+      const w = ws.get(id)
+      if (!w) return false
+      const next = { ...w }
+      if (tid == null) delete next.tid
+      else next.tid = tid
+      ws.set(id, next)
+      return true
+    },
+    endAll() {
+      for (const [id, w] of ws) {
+        if (w.state === 'failed' || w.state === 'ended') continue
+        const next = { ...w, state: 'ended', atMs: at() }
+        delete next.tid
+        ws.set(id, next)
+      }
+    },
+    list: () => [...ws.values()].map(w => ({ ...w })),
+    allReady: () => ws.size > 0 && [...ws.values()].every(w => w.state === 'ready'),
+    has: id => ws.has(id),
+  }
+}

package/src/host/chan-service.js

@@ -0,0 +1,300 @@
+// P-B3: the channel service Worker. Serves every channel of one machine (ChanHost in
+// chan-services.js) off the page's main thread.
+//
+// It never blocks: it waits on the chan block's doorbell with Atomics.waitAsync, so its
+// event loop stays free for the page's messages (console input, stats requests). After
+// any work it spins on the doorbell for 200 us before going back to waitAsync: a request
+// that arrives within that time is served without a wakeup through the event loop. W51:
+// while it is serving 9P requests the spin may be longer, up to spinUs (5 ms), adapting as the
+// vm's halt poll (D-307) does: a doorbell that came within spinUs after the spin gave up
+// doubles the window (a longer spin would have caught it), a longer wait halves it, so a
+// guest whose 9P traffic stops costs no spinning. Other traffic keeps the 200 us spin.
+// Safari wakes a parked waiter 1-2 ms late when other threads are busy, which was most of
+// its 9P round trip (P-B3: 1075 us p50 with a 200 us spin, 220 us with 5 ms). A spin never
+// runs past the 10 ms yield, so messages wait at most about 10 ms as before.
+//
+// Death: the Worker holds a Web Lock for its whole life. The page asks for the same lock;
+// the browser grants it when this Worker ends for any reason (terminated, closed,
+// crashed), and the page then marks the service dead in the chan block (markServiceDead),
+// which wakes every guest thread waiting on a channel. An exception inside the loop marks
+// it dead from here first.
+//
+// Messages in: {t:'init', sab, services:[{port, kind, layers:[SharedArrayBuffer|ArrayBuffer],
+//                at, files, maxUpperBytes, yamux}], lockName, spinUs, consoleInputBytes}
+//              (init's netPort: P-B10, a MessagePort to the network Worker, src/net/net-worker.js)
+//              {t:'ctl', op, k, bytes?, n?}   P-B11: a control-session stream op (ChanHost.controlInput)
+//              {t:'console', bytes}           page -> guest console bytes (held up to
+//                                             consoleInputBytes; boot.js's gate keeps under it)
+//              {t:'stats'}                    reply {t:'stats', stats}
+//              {t:'collect', files:[{port, path}]}  reply {t:'collected', files: {"port:path": text|null}}
+//              {t:'export-upper', id, port}   W62: reply {t:'upper', id, bytes, entries, files, whiteouts,
+//                                             opaque, dataBytes, ms} (the pack, transferred) or {t:'upper', id, error}
+//              test hooks: {t:'die'} (self.close() at once), {t:'crash'} (throw in the loop),
+//              {t:'stall', ms} (busy for ms inside the loop)
+// Messages out: {t:'ready'}, {t:'locked'}, {t:'stats', stats}, {t:'console-bytes', n},
+//               {t:'ctl', evs:[...]} (P-B11: control session events, ChanHost.takeCtlEvents),
+//               {t:'error', message}, {t:'upper-full', port, used, max} (a 9P write was
+//               refused with ENOSPC for maxUpperBytes; at most one per port every 10 s)
+
+import { H_DOORBELL, H_SVC, SVC_RUNNING, markServiceDead } from './chan.js'
+import { ChanHost } from './chan-services.js'
+import { Pack, bytesSource } from '../fs/pack.js'
+import { Overlay } from '../fs/overlay.js'
+import { seedEntry } from '../fs/seed.js'
+import { exportUpper } from '../fs/upper-pack.js'
+
+let host = null
+let sab = null
+const svcAt = {} // port -> where its layers show (W62: the upper is exported from there)
+let crash = false
+let stallMs = 0
+let spinUs = 5000 // longest spin (W51)
+const SPIN_BASE_US = 200 // the spin after any work
+let spinCur = 0 // W51: the window after 9P work, us (adapts between 0 and spinUs)
+const spin = { hits: 0, sleeps: 0 }
+let lastP9 = 0
+let lastP9At = -Infinity
+
+const nowMs = () => performance.now()
+
+self.onmessage = e => {
+  const m = e.data
+  try {
+    switch (m.t) {
+      case 'init':
+        init(m)
+        break
+      case 'console':
+        host?.consoleInput(new Uint8Array(m.bytes).slice())
+        kick()
+        break
+      case 'ctl':
+        if (host) {
+          host.controlInput(m)
+          postCtl()
+          kick()
+        }
+        break
+      case 'stats':
+        self.postMessage({ t: 'stats', stats: host ? withSpin(host.snapshot()) : null, id: m.id })
+        break
+      case 'snap': {
+        // P-B9: the 9P trees and fid tables as bytes (the guest is stopped at its checkpoint point)
+        const t0 = nowMs()
+        try {
+          const ports = host.snapshotState()
+          const out = {}
+          const transfer = []
+          for (const [port, d] of Object.entries(ports)) {
+            const segments = d.segments.map(u => u.buffer)
+            out[port] = { segments, bytes: d.bytes, fids: d.fids, inodes: d.inodes }
+            transfer.push(...segments)
+          }
+          self.postMessage({ t: 'snap', ports: out, ms: nowMs() - t0 }, transfer)
+        } catch (err) {
+          self.postMessage({ t: 'snap', error: err && err.message ? `${err.name}: ${err.message}` : String(err) })
+        }
+        break
+      }
+      case 'export-upper': {
+        const t0 = nowMs()
+        try {
+          if (!host) throw new Error('the channel service has not started')
+          const r = exportUpper(host.fsFor(m.port), { at: svcAt[m.port] || '' })
+          self.postMessage({ t: 'upper', id: m.id, ...r, ms: nowMs() - t0 }, [r.bytes.buffer])
+        } catch (err) {
+          self.postMessage({ t: 'upper', id: m.id, error: err && err.message ? `${err.name}: ${err.message}` : String(err) })
+        }
+        break
+      }
+      case 'collect': {
+        // files out of the 9P trees, e.g. bundle/exitcode once the guest has ended
+        const files = {}
+        for (const f of m.files || []) {
+          try {
+            files[`${f.port}:${f.path}`] = new TextDecoder().decode(host.fsFor(f.port).readFile(f.path))
+          } catch (e) {
+            files[`${f.port}:${f.path}`] = null
+          }
+        }
+        self.postMessage({ t: 'collected', files })
+        break
+      }
+      case 'die':
+        self.close() // ends at once, mid-whatever; the lock tells the page
+        break
+      case 'crash':
+        crash = true
+        kick()
+        break
+      case 'stall':
+        stallMs = m.ms
+        kick()
+        break
+    }
+  } catch (err) {
+    fail(err)
+  }
+}
+
+/** Control events for the page (data bytes transferred). */
+function postCtl() {
+  const evs = host?.takeCtlEvents()
+  if (!evs) return
+  const transfer = []
+  for (const e of evs) if (e.bytes) transfer.push(e.bytes.buffer)
+  self.postMessage({ t: 'ctl', evs }, transfer)
+}
+
+function kick() {
+  if (!sab) return
+  const i32 = new Int32Array(sab)
+  Atomics.add(i32, H_DOORBELL, 1)
+  Atomics.notify(i32, H_DOORBELL)
+}
+
+function fail(err) {
+  if (sab) markServiceDead(sab)
+  // Firefox and WebKit stacks do not include the message
+  self.postMessage({ t: 'error', message: err && err.message !== undefined ? `${err.name || 'Error'}: ${err.message}\n${err.stack || ''}` : String(err) })
+  self.close()
+}
+
+const FULL_NOTE_MS = 10_000
+
+function buildFs(svc) {
+  const layers = (svc.layers || []).map((b, i) => {
+    const u8 = new Uint8Array(b)
+    try {
+      return new Pack(bytesSource(u8), `layer ${i}`)
+    } catch (e) {
+      // what arrived, so a bad transfer can be told from a bad file
+      const show = a => Array.from(a, x => x.toString(16).padStart(2, '0')).join('')
+      let nonzero = 0
+      for (let k = 0; k < u8.length; k += 4096) if (u8[k]) nonzero++
+      throw new Error(`${e.message} (${u8.length} bytes${b instanceof SharedArrayBuffer ? ', shared' : ''}; first 8 ${show(u8.subarray(0, 8))}, last 8 ${show(u8.subarray(-8))}; ${nonzero} of ${Math.ceil(u8.length / 4096)} pages start non-zero)`)
+    }
+  })
+  let noted = -Infinity
+  const onFull = f => {
+    const t = nowMs()
+    if (t - noted < FULL_NOTE_MS) return
+    noted = t
+    self.postMessage({ t: 'upper-full', port: svc.port, used: f.used, max: f.maxUpperBytes, hits: f.fullHits })
+  }
+  const fs = new Overlay({ layers, at: svc.at || '', maxUpperBytes: svc.maxUpperBytes ?? Infinity, onFull })
+  // a restored tree comes whole from the checkpoint (ChanHost restore), the bundle files included
+  for (const [path, f] of Object.entries(svc.restore ? {} : svc.files || {})) {
+    seedEntry(fs, path, f)
+  }
+  return fs
+}
+
+function init(m) {
+  sab = m.sab
+  spinUs = m.spinUs ?? spinUs
+  const fs = {}
+  for (const svc of m.services || []) {
+    if (svc.kind !== '9p' && svc.kind !== 2) continue
+    fs[svc.port] = buildFs(svc)
+    svcAt[svc.port] = svc.at || ''
+  }
+  const yamuxPorts = (m.services || []).filter(s => (s.kind === 'control' || s.kind === 3) && s.yamux).map(s => s.port)
+  let netPost = null
+  if (m.netPort) {
+    // P-B10: the net channel's frames go to and come from the network Worker
+    const p = m.netPort
+    netPost = (msg, transfer) => p.postMessage(msg, transfer || [])
+    p.onmessage = e => {
+      try {
+        host?.netMessage(e.data)
+        kick()
+      } catch (err) {
+        fail(err)
+      }
+    }
+  }
+  const restore = {}
+  for (const svc of m.services || []) if (svc.restore) restore[svc.port] = new Uint8Array(svc.restore)
+  host = new ChanHost(sab, { fs, consoleInputBytes: m.consoleInputBytes, yamuxPorts, netPost, restore })
+  if (m.lockName && self.navigator?.locks?.request) {
+    self.navigator.locks.request(m.lockName, () => {
+      self.postMessage({ t: 'locked' })
+      return new Promise(() => {}) // held until this Worker ends
+    })
+  }
+  Atomics.store(new Int32Array(sab), H_SVC, SVC_RUNNING)
+  self.postMessage({ t: 'ready' })
+  setInterval(() => host && !host.stopped && maybePostStats(), 250) // stats while idle (and keeps a Bun Worker alive)
+  loop().catch(fail)
+}
+
+let lastStats = ''
+const withSpin = s => ({ ...s, spin: { ...spin, curUs: spinCur } })
+let lastStatsAt = 0
+function maybePostStats() {
+  const t = nowMs()
+  if (t - lastStatsAt < 250) return
+  lastStatsAt = t
+  const s = host.snapshot()
+  const key = JSON.stringify(s) // the spin counters alone do not make news
+  if (key === lastStats) return
+  lastStats = key
+  self.postMessage({ t: 'stats', stats: withSpin(s) })
+}
+
+// A macrotask without setTimeout's clamping, to let messages in during long busy runs.
+const yieldChan = new MessageChannel()
+const yieldQ = []
+yieldChan.port1.onmessage = () => yieldQ.shift()?.()
+const yieldTask = () => new Promise(r => (yieldQ.push(r), yieldChan.port2.postMessage(0)))
+
+async function loop() {
+  const i32 = new Int32Array(sab)
+  let lastYield = nowMs()
+  for (;;) {
+    if (crash) throw new Error('chan service: crash requested (test hook)')
+    if (stallMs) {
+      const end = nowMs() + stallMs
+      stallMs = 0
+      while (nowMs() < end) {}
+    }
+    const bell = Atomics.load(i32, H_DOORBELL)
+    const work = host.step()
+    postCtl()
+    if (host.stopped) return
+    const t = nowMs()
+    if (t - lastYield > 10) {
+      maybePostStats()
+      await yieldTask()
+      lastYield = nowMs()
+      continue
+    }
+    if (work) continue
+    // spin on the doorbell for a little while: the next request often comes at once
+    // 9P work within the last 2 spinUs: the guest's next request is likely on its way (the
+    // doorbell also rings for other things, such as the guest reading a reply)
+    const p9 = host.p9Requests()
+    if (p9 !== lastP9) (lastP9 = p9), (lastP9At = t)
+    const p9Served = t - lastP9At < (2 * spinUs) / 1000
+    const spinWin = Math.min(spinUs, p9Served ? Math.max(spinCur, SPIN_BASE_US) : SPIN_BASE_US)
+    const capped = lastYield + 10 < t + spinWin / 1000 // the yield, not the window, ends this spin
+    const spinEnd = capped ? lastYield + 10 : t + spinWin / 1000
+    if (Atomics.load(i32, H_DOORBELL) !== bell) continue // rang during the step: not a spin hit
+    while (Atomics.load(i32, H_DOORBELL) === bell && nowMs() < spinEnd) {}
+    if (Atomics.load(i32, H_DOORBELL) !== bell) {
+      spin.hits++
+      continue
+    }
+    maybePostStats()
+    const w = Atomics.waitAsync(i32, H_DOORBELL, bell, 500)
+    if (w.async) await w.value
+    lastYield = nowMs()
+    if (!p9Served || capped) continue
+    // adapt (after 9P work only): rung soon after the spin gave up -> longer; quiet -> shorter
+    const rung = Atomics.load(i32, H_DOORBELL) !== bell
+    if (rung) spin.sleeps++
+    if (rung && (lastYield - spinEnd) * 1000 <= spinUs) spinCur = Math.min(spinUs, spinCur ? spinCur * 2 : SPIN_BASE_US * 2)
+    else if ((spinCur /= 2) < SPIN_BASE_US) spinCur = 0
+  }
+}