@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/host/chan.js

@@ -0,0 +1,655 @@
+// P-B3: wmd.chan_* over shared-memory rings (web/docs/host-interface.md §3).
+//
+// The runner's channels are byte streams to a TCP or Unix socket (runner/src/chan.rs).
+// Here a channel is a duplex pair of byte rings in one SharedArrayBuffer (the "chan
+// block"), with a service Worker (chan-service.js) on the host side. The guest threads
+// call the imports synchronously and block in Atomics.wait; the service never blocks
+// (Atomics.waitAsync on one doorbell cell), so it can still receive messages.
+//
+// Semantics, as chan.rs:
+//   chan_open(kind, port)     -22 port not in 1..65535; -111 no service on that port (or
+//                             the service is dead); else the lowest free handle. The port
+//                             decides the service; kind is only recorded.
+//   chan_send(h, ptr, len)    all `len` bytes, blocking while the ring is full; len, or -14
+//                             bad range, -9 bad handle, -32 when the peer is gone or the
+//                             channel was shut down for writing. One message is never
+//                             interleaved with another thread's: senders hold the ring's
+//                             producer lock for the whole call (a socket does not promise
+//                             that; the guest relies on it for 9P anyway).
+//   chan_recv(h, ptr, len, t) t >= 0: wait up to t ns (rounded up to ms, as chan.rs), 0 if
+//                             nothing came; t < 0: block. Bytes read (a partial read is
+//                             normal), 0 on timeout, -1 at EOF or when the peer is gone.
+//                             Bytes already in the ring are delivered before EOF.
+//   chan_wake(h)              wake-on-stop: ends one wait in chan_recv(h) now. A latched
+//                             one-shot flag (S_WAKE): the woken recv, or the next one if none
+//                             is waiting, returns the bytes in the ring or 0 at once; wakes
+//                             before that collapse into one. 0, or -9 bad handle.
+//   chan_shutdown(h)          half-close: the host side sees EOF after the bytes in the ring.
+//   chan_close(h)             free the handle. Threads blocked on it return -1 / -32. The
+//                             slot is reused only after the service has dropped its session,
+//                             so a reply in flight can never land in a new channel.
+//
+// A peer that dies cannot hang the guest: the page (or the service itself) marks the
+// service dead (markServiceDead), which wakes every waiter, and every blocking loop also
+// re-checks the machine's exit flag at least once a second. When the machine ends, the
+// page marks the guest gone (markGuestGone), which wakes every waiter at once too.
+//
+// Layout (Int32 cells, then the ring data):
+//   header  HDR_INTS cells: doorbell, service state, guest-gone flag, port registry, counters
+//   slots   nslots x SLOT_INTS: state, kind, port, generation, then two rings' cells
+//           (guest->host and host->guest)
+//   pipe    one more ring's cells: the console's path from the service to the page
+//   stats   Float64: per slot bytes each way; the guest-side 9P round-trip histogram
+//   data    2 rings per slot + the pipe, ringBytes each (a power of two)
+
+export const CHAN_NET = 1
+export const CHAN_P9 = 2
+export const CHAN_CONTROL = 3
+export const CHAN_CONSOLE = 4
+export const KIND_NAMES = { 1: 'net', 2: '9p', 3: 'control', 4: 'console' }
+export const KIND_OF = { net: 1, '9p': 2, control: 3, console: 4 }
+
+export const EBADF = -9
+export const EFAULT = -14
+export const EINVAL = -22
+export const EMFILE = -24
+export const EPIPE = -32
+export const ECONNREFUSED = -111
+
+// Header cells.
+const H_MAGIC = 0
+const H_NSLOTS = 1
+const H_RING = 2
+export const H_DOORBELL = 3 // bumped (and notified) by anything the service must look at
+export const H_SVC = 4 // service state
+export const H_GONE = 5 // the guest machine has ended: the service stops
+const H_NPORTS = 6
+export const H_OPENS = 7
+export const H_REFUSED = 8
+export const H_CLOSES = 9
+const H_PIPE_RING = 10 // bytes of the page pipe ring
+export const H_CIN_TAKEN = 11 // console input bytes the service has put into a guest ring (or dropped), mod 2^32
+export const H_PORTS = 16 // MAX_PORTS x [port, kind]
+export const MAX_PORTS = 16
+const HDR_INTS = 64
+const MAGIC = 0x77636831 // "wch1"
+
+export const SVC_STARTING = 0
+export const SVC_RUNNING = 1
+export const SVC_DEAD = 2
+
+// Slot cells.
+export const SLOT_INTS = 32
+export const S_STATE = 0
+export const S_KIND = 1
+export const S_PORT = 2
+export const S_GEN = 3
+export const S_WAKE = 4 // chan_wake latched: the next recv that would wait returns 0
+export const G2H = 8 // guest -> host ring cells
+export const H2G = 16 // host -> guest ring cells
+
+export const ST_FREE = 0
+export const ST_OPEN = 1
+export const ST_CLOSING = 2 // chan_close called; the service frees the slot
+const ST_OPENING = 3
+
+// Ring cells (relative to the ring's base cell).
+export const R_W = 0 // bytes ever written, mod 2^32
+export const R_R = 1 // bytes ever read, mod 2^32
+export const R_DSEQ = 2 // bumped on data written / writer done / torn down: consumers wait here
+export const R_SSEQ = 3 // bumped on data read / reader gone / torn down: producers wait here
+export const R_SHUT = 4 // the writer is done: EOF once the ring is empty
+export const R_GONE = 5 // torn down: no more reads or writes
+const R_PLOCK = 6 // producer lock (held for a whole send)
+const R_CLOCK = 7 // consumer lock (held for one copy)
+
+// 9P round-trip histogram (guest side: chan_send of a T-message -> its R-message
+// delivered by chan_recv). Buckets: 0..999 us by 1 us, 1,000..9,990 us by 10 us,
+// then one bucket for 10 ms and more.
+export const RTT_BUCKETS = 1000 + 900 + 1
+export function rttBucket(us) {
+  if (us < 0) us = 0
+  if (us < 1000) return Math.floor(us)
+  if (us < 10000) return 1000 + Math.floor((us - 1000) / 10)
+  return 1900
+}
+export function bucketUs(b) {
+  if (b < 1000) return b + 0.5
+  if (b < 1900) return 1000 + (b - 1000) * 10 + 5
+  return 10000
+}
+
+/** p50/p90/p99/max (us) and count from a bucket array (Int32Array or number[]). */
+export function histSummary(buckets, extra = {}) {
+  let n = 0
+  for (let i = 0; i < buckets.length; i++) n += buckets[i]
+  const out = { n, ...extra }
+  if (!n) return out
+  const at = q => {
+    const want = Math.max(1, Math.ceil(n * q))
+    let c = 0
+    for (let i = 0; i < buckets.length; i++) {
+      c += buckets[i]
+      if (c >= want) return bucketUs(i)
+    }
+    return bucketUs(buckets.length - 1)
+  }
+  out.p50Us = at(0.5)
+  out.p90Us = at(0.9)
+  out.p99Us = at(0.99)
+  let last = 0
+  for (let i = 0; i < buckets.length; i++) if (buckets[i]) last = i
+  out.maxBucketUs = bucketUs(last)
+  return out
+}
+
+/** W51: one stage histogram (see layoutOf). Concurrent writers are fine for a diagnostic. */
+export function stageNote(st, us) {
+  if (!(us >= 0)) return
+  Atomics.add(st.hist, rttBucket(us), 1)
+  st.f64[0] += us
+  st.f64[1] += 1
+  if (us > st.f64[2]) st.f64[2] = us
+}
+const stageSummary = st => histSummary(st.hist, { meanUs: st.f64[1] ? st.f64[0] / st.f64[1] : 0, maxUs: st.f64[2] })
+
+const align = (n, a) => Math.ceil(n / a) * a
+const STAGE_BYTES = align(RTT_BUCKETS * 4, 8) + 4 * 8 // W51: one stage histogram + sum, n, max, spare
+
+function layoutOf(nslots, ringBytes, pipeBytes) {
+  const ints = HDR_INTS + (nslots + 1) * SLOT_INTS
+  const statsOff = align(ints * 4, 64)
+  const statsF64 = nslots * 4 + 4 // per slot: bytes g2h, bytes h2g, send waits, send wait ms; then rtt sum, n, max, spare
+  const rttOff = align(statsOff + statsF64 * 8, 64)
+  const tagOff = align(rttOff + RTT_BUCKETS * 4, 64) // Float64 send time per 9P tag
+  // W51: the stage split of a 9P round trip. Float64 reply-written time per tag (the
+  // service), then two histograms with their sum/n/max: request picked up by the service
+  // (send -> parse) and reply read by the guest (reply written -> chan_recv returns).
+  const replyOff = tagOff + 65536 * 8
+  const stageOff = align(replyOff + 65536 * 8, 64)
+  const dataOff = align(stageOff + 2 * STAGE_BYTES, 4096)
+  const total = dataOff + nslots * 2 * ringBytes + pipeBytes
+  return { statsOff, rttOff, tagOff, replyOff, stageOff, dataOff, total }
+}
+
+const pow2 = n => n >= 64 && n <= 1 << 30 && (n & (n - 1)) === 0
+
+/**
+ * The chan block. ports: [{port, kind}] the services listen on (kind: 1..4 or a name).
+ * ringBytes: each direction of each channel (power of two, >= 64).
+ */
+export function createChanBlock({ ports = [], nslots = 8, ringBytes = 1 << 20, pipeBytes = 1 << 23 } = {}) {
+  if (!pow2(ringBytes)) throw new Error(`channel ring size must be a power of two from 64 bytes to 1 GiB, got ${ringBytes}`)
+  if (!pow2(pipeBytes)) throw new Error(`console pipe size must be a power of two, got ${pipeBytes}`)
+  if (ports.length > MAX_PORTS) throw new Error(`at most ${MAX_PORTS} channel services`)
+  if (!(nslots >= 1 && nslots <= 64)) throw new Error('nslots must be 1..64')
+  const L = layoutOf(nslots, ringBytes, pipeBytes)
+  const sab = new SharedArrayBuffer(L.total)
+  const i32 = new Int32Array(sab)
+  i32[H_MAGIC] = MAGIC
+  i32[H_NSLOTS] = nslots
+  i32[H_RING] = ringBytes
+  i32[H_PIPE_RING] = pipeBytes
+  const seen = new Set()
+  ports.forEach((p, i) => {
+    const kind = typeof p.kind === 'string' ? KIND_OF[p.kind] : p.kind
+    if (!(p.port >= 1 && p.port <= 65535)) throw new Error(`channel port ${p.port}: must be 1..65535`)
+    if (!kind) throw new Error(`channel port ${p.port}: unknown kind ${p.kind}`)
+    if (seen.has(p.port)) throw new Error(`channel port ${p.port} given twice`)
+    seen.add(p.port)
+    i32[H_PORTS + 2 * i] = p.port
+    i32[H_PORTS + 2 * i + 1] = kind
+  })
+  i32[H_NPORTS] = ports.length
+  return sab
+}
+
+/** Views and ring handles over a chan block, for any thread (guest, service, page). */
+export function chanView(sab) {
+  const i32 = new Int32Array(sab)
+  if (i32[H_MAGIC] !== MAGIC) throw new Error('not a chan block')
+  const nslots = i32[H_NSLOTS]
+  const ringBytes = i32[H_RING]
+  const pipeBytes = i32[H_PIPE_RING]
+  const L = layoutOf(nslots, ringBytes, pipeBytes)
+  const u8 = new Uint8Array(sab)
+  const f64 = new Float64Array(sab, L.statsOff, nslots * 4 + 4)
+  const rtt = new Int32Array(sab, L.rttOff, RTT_BUCKETS)
+  const tagTimes = new Float64Array(sab, L.tagOff, 65536)
+  const replyTimes = new Float64Array(sab, L.replyOff, 65536)
+  const stage = k => ({
+    hist: new Int32Array(sab, L.stageOff + k * STAGE_BYTES, RTT_BUCKETS),
+    f64: new Float64Array(sab, L.stageOff + k * STAGE_BYTES + align(RTT_BUCKETS * 4, 8), 4),
+  })
+  const pickup = stage(0), readback = stage(1)
+  const slotBase = s => HDR_INTS + s * SLOT_INTS
+  const ring = (s, dir) => ({
+    c: slotBase(s) + dir,
+    data: L.dataOff + (2 * s + (dir === G2H ? 0 : 1)) * ringBytes,
+    size: ringBytes,
+  })
+  const pipe = { c: slotBase(nslots) + G2H, data: L.dataOff + nslots * 2 * ringBytes, size: pipeBytes }
+  return { sab, i32, u8, f64, rtt, tagTimes, replyTimes, pickup, readback, nslots, ringBytes, pipeBytes, slotBase, ring, pipe }
+}
+
+// ---- ring primitives (non-blocking; callers do the waiting) ----------------------------
+
+export const ringAvail = (v, r) => (Atomics.load(v.i32, r.c + R_W) - Atomics.load(v.i32, r.c + R_R)) >>> 0
+export const ringSpace = (v, r) => r.size - ringAvail(v, r)
+
+/** Copy up to n bytes of src[off..] into the ring. One producer at a time. Returns bytes written. */
+export function ringWrite(v, r, src, off = 0, n = src.length - off) {
+  const i32 = v.i32
+  const w = Atomics.load(i32, r.c + R_W) >>> 0
+  const rd = Atomics.load(i32, r.c + R_R) >>> 0
+  const space = r.size - ((w - rd) >>> 0)
+  n = Math.min(n, space)
+  if (n <= 0) return 0
+  const at = w & (r.size - 1)
+  const first = Math.min(n, r.size - at)
+  v.u8.set(src.subarray(off, off + first), r.data + at)
+  if (first < n) v.u8.set(src.subarray(off + first, off + n), r.data)
+  Atomics.store(i32, r.c + R_W, (w + n) | 0)
+  Atomics.add(i32, r.c + R_DSEQ, 1)
+  Atomics.notify(i32, r.c + R_DSEQ)
+  return n
+}
+
+/** Copy up to n bytes out of the ring into dst[off..]. One consumer at a time. Returns bytes read. */
+export function ringRead(v, r, dst, off = 0, n = dst.length - off) {
+  const i32 = v.i32
+  const w = Atomics.load(i32, r.c + R_W) >>> 0
+  const rd = Atomics.load(i32, r.c + R_R) >>> 0
+  n = Math.min(n, (w - rd) >>> 0)
+  if (n <= 0) return 0
+  const at = rd & (r.size - 1)
+  const first = Math.min(n, r.size - at)
+  dst.set(v.u8.subarray(r.data + at, r.data + at + first), off)
+  if (first < n) dst.set(v.u8.subarray(r.data, r.data + n - first), off + first)
+  Atomics.store(i32, r.c + R_R, (rd + n) | 0)
+  Atomics.add(i32, r.c + R_SSEQ, 1)
+  Atomics.notify(i32, r.c + R_SSEQ)
+  return n
+}
+
+/** Wake everything waiting on a ring (after a flag change). */
+export function ringKick(v, r) {
+  Atomics.add(v.i32, r.c + R_DSEQ, 1)
+  Atomics.add(v.i32, r.c + R_SSEQ, 1)
+  Atomics.notify(v.i32, r.c + R_DSEQ)
+  Atomics.notify(v.i32, r.c + R_SSEQ)
+}
+
+export function ringBell(v) {
+  Atomics.add(v.i32, H_DOORBELL, 1)
+  Atomics.notify(v.i32, H_DOORBELL)
+}
+
+/** Reset a ring for a new channel. Sequence cells keep counting, so no waiter sees an old value come back. */
+function ringReset(v, r) {
+  const i32 = v.i32
+  Atomics.store(i32, r.c + R_W, 0)
+  Atomics.store(i32, r.c + R_R, 0)
+  Atomics.store(i32, r.c + R_SHUT, 0)
+  Atomics.store(i32, r.c + R_GONE, 0)
+  Atomics.store(i32, r.c + R_PLOCK, 0)
+  Atomics.store(i32, r.c + R_CLOCK, 0)
+}
+
+/**
+ * Mark the service dead: every waiter wakes, chan_open refuses, sends fail with -32, and
+ * receives return what is left in their ring and then -1. Safe from any thread, any
+ * number of times.
+ */
+export function markServiceDead(sab) {
+  const v = chanView(sab)
+  Atomics.store(v.i32, H_SVC, SVC_DEAD)
+  for (let s = 0; s < v.nslots; s++) {
+    const g = v.ring(s, G2H)
+    const h = v.ring(s, H2G)
+    Atomics.store(v.i32, g.c + R_GONE, 1)
+    Atomics.store(v.i32, h.c + R_SHUT, 1)
+    ringKick(v, g)
+    ringKick(v, h)
+  }
+  ringKick(v, v.pipe)
+  ringBell(v)
+}
+
+/**
+ * The guest machine has ended: the service drops every session and stops, and every
+ * guest thread still blocked in chan_send / chan_recv returns now (-32 / -1) instead of
+ * at the end of its current wait slice.
+ */
+export function markGuestGone(sab) {
+  const v = chanView(sab)
+  Atomics.store(v.i32, H_GONE, 1)
+  for (let s = 0; s < v.nslots; s++) {
+    ringKick(v, v.ring(s, G2H))
+    ringKick(v, v.ring(s, H2G))
+  }
+  ringKick(v, v.pipe)
+  ringBell(v)
+}
+
+export const serviceDead = sab => Atomics.load(new Int32Array(sab), H_SVC) === SVC_DEAD
+
+// ---- guest side: the five imports -------------------------------------------------------
+
+function lock(i32, i, abort) {
+  if (Atomics.compareExchange(i32, i, 0, 1) === 0) return true
+  for (;;) {
+    if (Atomics.exchange(i32, i, 2) === 0) return true
+    if (abort()) return false
+    Atomics.wait(i32, i, 2, 100)
+  }
+}
+
+function unlock(i32, i) {
+  if (Atomics.sub(i32, i, 1) !== 1) {
+    Atomics.store(i32, i, 0)
+    Atomics.notify(i32, i, 1)
+  }
+}
+
+const WAIT_SLICE_MS = 1000 // longest single Atomics.wait: flags are re-checked at least this often
+
+/**
+ * wmd.chan_* for one guest Worker.
+ * @param {object} o
+ * @param {SharedArrayBuffer} o.sab        the chan block
+ * @param {WebAssembly.Memory} o.memory    the guest's shared memory
+ * @param {() => boolean} [o.exiting]       the machine is ending (CTL_EXIT)
+ * @param {() => number} [o.now]            ms clock comparable across Workers
+ */
+export function createChanImports({ sab, memory, exiting = () => false, now = () => performance.timeOrigin + performance.now() }) {
+  const v = chanView(sab)
+  const i32 = v.i32
+  let buf = memory.buffer
+  let mem = new Uint8Array(buf)
+  const views = () => {
+    const b = memory.buffer
+    if (b !== buf || b.byteLength !== mem.length) {
+      buf = b
+      mem = new Uint8Array(b)
+    }
+  }
+  const dead = () => Atomics.load(i32, H_SVC) === SVC_DEAD
+  const ending = () => exiting() || Atomics.load(i32, H_GONE) !== 0 // the machine is over
+  const valid = h => Number.isInteger(h) && h >= 0 && h < v.nslots && Atomics.load(i32, v.slotBase(h) + S_STATE) === ST_OPEN
+  // 9P framing state of the replies this thread receives, per handle (only the pump
+  // thread receives; this is for the round-trip histogram, it never changes the bytes).
+  const rx = new Map()
+
+  function open(kind, port) {
+    if (!(port >= 1 && port <= 65535)) return EINVAL
+    if (dead() || Atomics.load(i32, H_GONE)) {
+      Atomics.add(i32, H_REFUSED, 1)
+      return ECONNREFUSED
+    }
+    const n = Atomics.load(i32, H_NPORTS)
+    let found = false
+    for (let i = 0; i < n; i++) if (Atomics.load(i32, H_PORTS + 2 * i) === port) found = true
+    if (!found) {
+      Atomics.add(i32, H_REFUSED, 1)
+      return ECONNREFUSED
+    }
+    for (let s = 0; s < v.nslots; s++) {
+      const b = v.slotBase(s)
+      if (Atomics.compareExchange(i32, b + S_STATE, ST_FREE, ST_OPENING) !== ST_FREE) continue
+      ringReset(v, v.ring(s, G2H))
+      ringReset(v, v.ring(s, H2G))
+      v.f64.fill(0, s * 4, s * 4 + 4)
+      Atomics.store(i32, b + S_KIND, kind)
+      Atomics.store(i32, b + S_PORT, port)
+      Atomics.store(i32, b + S_WAKE, 0)
+      Atomics.add(i32, b + S_GEN, 1)
+      Atomics.store(i32, b + S_STATE, ST_OPEN)
+      Atomics.add(i32, H_OPENS, 1)
+      rx.delete(s)
+      ringBell(v)
+      return s
+    }
+    return EMFILE
+  }
+
+  function send(h, ptr, len) {
+    ptr >>>= 0
+    len >>>= 0
+    views()
+    if (ptr + len > mem.length) return EFAULT
+    if (!valid(h)) return EBADF
+    const b = v.slotBase(h)
+    const gen = Atomics.load(i32, b + S_GEN)
+    const r = v.ring(h, G2H)
+    const broken = () =>
+      dead() || Atomics.load(i32, r.c + R_GONE) !== 0 || Atomics.load(i32, r.c + R_SHUT) !== 0 ||
+      Atomics.load(i32, b + S_STATE) !== ST_OPEN || Atomics.load(i32, b + S_GEN) !== gen
+    if (broken()) return EPIPE
+    if (!lock(i32, r.c + R_PLOCK, () => broken() || ending())) return EPIPE
+    try {
+      if (Atomics.load(i32, b + S_KIND) === CHAN_P9 && len >= 7) {
+        // T-message: stamp its tag for the round-trip histogram
+        v.tagTimes[mem[ptr + 5] | (mem[ptr + 6] << 8)] = now()
+      }
+      let done = 0
+      while (done < len) {
+        if (broken()) return EPIPE
+        const seq = Atomics.load(i32, r.c + R_SSEQ)
+        views()
+        const n = ringWrite(v, r, mem, ptr + done, len - done)
+        if (n > 0) {
+          done += n
+          ringBell(v)
+          continue
+        }
+        if (ending()) return EPIPE
+        // the ring is full: the host is behind (counted, so a test can tell)
+        const tw = now()
+        Atomics.wait(i32, r.c + R_SSEQ, seq, WAIT_SLICE_MS)
+        v.f64[h * 4 + 2] += 1
+        v.f64[h * 4 + 3] += now() - tw
+      }
+      v.f64[h * 4] += len
+      return len
+    } finally {
+      unlock(i32, r.c + R_PLOCK)
+    }
+  }
+
+  function noteRx(h, kind, src, off, n) {
+    if (kind !== CHAN_P9) return
+    const gen = Atomics.load(i32, v.slotBase(h) + S_GEN)
+    let st = rx.get(h)
+    if (!st || st.gen !== gen) rx.set(h, (st = { gen, hdr: new Uint8Array(7), got: 0, left: 0, tag: 0 }))
+    let i = off
+    const end = off + n
+    while (i < end) {
+      if (st.left === 0) {
+        // in a header
+        st.hdr[st.got++] = src[i++]
+        if (st.got === 7) {
+          const size = (st.hdr[0] | (st.hdr[1] << 8) | (st.hdr[2] << 16) | (st.hdr[3] << 24)) >>> 0
+          st.tag = st.hdr[5] | (st.hdr[6] << 8)
+          st.got = 0
+          st.left = Math.max(0, size - 7)
+          if (st.left === 0) done(st.tag)
+        }
+      } else {
+        const k = Math.min(st.left, end - i)
+        i += k
+        st.left -= k
+        if (st.left === 0) done(st.tag)
+      }
+    }
+    function done(tag) {
+      const t0 = v.tagTimes[tag]
+      if (!(t0 > 0)) return
+      const t = now()
+      const tr = v.replyTimes[tag]
+      if (tr > 0) stageNote(v.readback, (t - tr) * 1000)
+      const us = (t - t0) * 1000
+      Atomics.add(v.rtt, rttBucket(us), 1)
+      const base = v.nslots * 4
+      v.f64[base] += us
+      v.f64[base + 1] += 1
+      if (us > v.f64[base + 2]) v.f64[base + 2] = us
+    }
+  }
+
+  function recv(h, ptr, len, timeoutNs) {
+    ptr >>>= 0
+    len >>>= 0
+    views()
+    if (ptr + len > mem.length) return EFAULT
+    if (!valid(h)) return EBADF
+    const b = v.slotBase(h)
+    const gen = Atomics.load(i32, b + S_GEN)
+    const kind = Atomics.load(i32, b + S_KIND)
+    const r = v.ring(h, H2G)
+    // D-419: a Number from the i64 shim (a BigInt from tests); no BigInt arithmetic per call
+    const t = Math.trunc(Number(timeoutNs) || 0)
+    const ms = t < 0 ? Infinity : Math.ceil(t / 1_000_000) // rounded up to ms, as chan.rs
+    const deadline = now() + ms
+    for (;;) {
+      const seq = Atomics.load(i32, r.c + R_DSEQ)
+      if (ringAvail(v, r) > 0) {
+        if (len === 0) return 0
+        if (!lock(i32, r.c + R_CLOCK, ending)) return -1
+        let n = 0
+        try {
+          views()
+          n = ringRead(v, r, mem, ptr, len)
+        } finally {
+          unlock(i32, r.c + R_CLOCK)
+        }
+        if (n > 0) {
+          ringBell(v) // the service may be waiting for room to write the rest of a reply
+          v.f64[h * 4 + 1] += n
+          noteRx(h, kind, mem, ptr, n)
+          return n
+        }
+        continue // another reader took it
+      }
+      if (
+        Atomics.load(i32, r.c + R_SHUT) !== 0 || Atomics.load(i32, r.c + R_GONE) !== 0 || dead() ||
+        Atomics.load(i32, b + S_STATE) !== ST_OPEN || Atomics.load(i32, b + S_GEN) !== gen || exiting() ||
+        Atomics.load(i32, H_GONE) !== 0
+      ) {
+        return -1
+      }
+      if (Atomics.exchange(i32, b + S_WAKE, 0) !== 0) return 0 // chan_wake
+      const rem = deadline - now()
+      if (rem <= 0) return 0
+      Atomics.wait(i32, r.c + R_DSEQ, seq, Math.min(rem, WAIT_SLICE_MS))
+    }
+  }
+
+  function wake(h) {
+    if (!valid(h)) return EBADF
+    Atomics.store(i32, v.slotBase(h) + S_WAKE, 1)
+    const r = v.ring(h, H2G)
+    Atomics.add(i32, r.c + R_DSEQ, 1)
+    Atomics.notify(i32, r.c + R_DSEQ)
+    return 0
+  }
+
+  function shutdown(h) {
+    if (!valid(h)) return EBADF
+    const r = v.ring(h, G2H)
+    Atomics.store(i32, r.c + R_SHUT, 1)
+    ringKick(v, r)
+    ringBell(v)
+    return 0
+  }
+
+  function close(h) {
+    if (!valid(h)) return EBADF
+    const b = v.slotBase(h)
+    if (Atomics.compareExchange(i32, b + S_STATE, ST_OPEN, ST_CLOSING) !== ST_OPEN) return EBADF
+    for (const dir of [G2H, H2G]) {
+      const r = v.ring(h, dir)
+      Atomics.store(i32, r.c + R_GONE, 1)
+      ringKick(v, r)
+    }
+    rx.delete(h)
+    Atomics.add(i32, H_CLOSES, 1)
+    ringBell(v)
+    return 0
+  }
+
+  return { open, send, recv, wake, shutdown, close }
+}
+
+/** Counters and the guest-side 9P round-trip histogram, for the page. */
+export function chanCounters(sab) {
+  const v = chanView(sab)
+  const i32 = v.i32
+  const slots = []
+  for (let s = 0; s < v.nslots; s++) {
+    const b = v.slotBase(s)
+    const state = Atomics.load(i32, b + S_STATE)
+    const gen = Atomics.load(i32, b + S_GEN)
+    if (!gen) continue
+    slots.push({
+      handle: s,
+      state: ['free', 'open', 'closing', 'opening'][state],
+      kind: KIND_NAMES[Atomics.load(i32, b + S_KIND)] || '?',
+      port: Atomics.load(i32, b + S_PORT),
+      opens: gen,
+      bytesOut: v.f64[s * 4],
+      bytesIn: v.f64[s * 4 + 1],
+      sendWaits: v.f64[s * 4 + 2], // chan_send found the ring full and waited
+      sendWaitMs: Math.round(v.f64[s * 4 + 3] * 10) / 10,
+    })
+  }
+  const base = v.nslots * 4
+  return {
+    service: ['starting', 'running', 'dead'][Atomics.load(i32, H_SVC)],
+    opens: Atomics.load(i32, H_OPENS),
+    refused: Atomics.load(i32, H_REFUSED),
+    closes: Atomics.load(i32, H_CLOSES),
+    slots,
+    p9Rtt: histSummary(v.rtt, { meanUs: v.f64[base + 1] ? v.f64[base] / v.f64[base + 1] : 0, maxUs: v.f64[base + 2] }),
+    // W51: send -> the service parses it, and reply written -> the guest's chan_recv returns
+    p9Pickup: stageSummary(v.pickup),
+    p9Readback: stageSummary(v.readback),
+  }
+}
+
+/** Ports registered in the block: [{port, kind}]. */
+export function chanPorts(sab) {
+  const i32 = new Int32Array(sab)
+  const out = []
+  for (let i = 0; i < i32[H_NPORTS]; i++) out.push({ port: i32[H_PORTS + 2 * i], kind: i32[H_PORTS + 2 * i + 1] })
+  return out
+}
+
+// ---- page side: console input with backpressure ------------------------------------------
+
+/** Console input bytes the page may have queued for the guest that it has not taken yet. */
+export const CONSOLE_IN_LIMIT = 4 << 20
+
+/**
+ * The page's side of console input (page -> guest). The page posts bytes to the service
+ * Worker; the service counts in H_CIN_TAKEN the bytes it has put into the guest's ring.
+ * Bytes posted and not yet taken (in flight, or queued in the service) never exceed
+ * `limit`: take(n) says how many of n bytes may be posted now (0 when the guest has not
+ * read what is already queued). Counters are mod 2^32, so `limit` must stay far below it.
+ */
+export function consoleInputGate(sab, limit = CONSOLE_IN_LIMIT) {
+  const i32 = new Int32Array(sab)
+  let sent = 0
+  const queued = () => ((sent >>> 0) - (Atomics.load(i32, H_CIN_TAKEN) >>> 0)) >>> 0
+  const space = () => Math.max(0, limit - queued())
+  return {
+    limit,
+    queued,
+    space,
+    take(n) {
+      const k = Math.min(n, space())
+      sent += k
+      return k
+    },
+  }
+}