@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/host/errno.js

@@ -0,0 +1,18 @@
+// WASI preview1 errno values (wasi_snapshot_preview1 `errno` enum).
+export const E = Object.freeze({
+  SUCCESS: 0,
+  AGAIN: 6,
+  BADF: 8,
+  FAULT: 21,
+  INVAL: 28,
+  IO: 29,
+  ISDIR: 31,
+  NFILE: 41,
+  NOENT: 44,
+  NOSYS: 52,
+  NOTDIR: 54,
+  NOTSUP: 58,
+  ROFS: 69,
+  SPIPE: 70,
+  NOTCAPABLE: 76,
+})

package/src/host/fs.js

@@ -0,0 +1,167 @@
+// A read-only, in-memory filesystem behind one WASI preopen, shared by all Workers.
+//
+// The file bytes live in SharedArrayBuffers (one per file) so every Worker reads the
+// same memory without copies. The fd table is process-wide like the runner's
+// (runner/src/wasi.rs FileTable behind a Mutex): it lives in the control buffer, so a
+// file opened on one thread can be read on another. fds 0-2 are stdio, fd 3 is the
+// preopen, files get 4.. (the runner hands out the next free number the same way).
+
+import { CTL_FD_LOCK, FD_FILE, FD_KIND, FD_MAX, FD_POS_HI, FD_POS_LO, fdIndex } from './layout.js'
+import { E } from './errno.js'
+
+export const FILETYPE_CHARACTER_DEVICE = 2
+export const FILETYPE_DIRECTORY = 3
+export const FILETYPE_REGULAR_FILE = 4
+
+export const PREOPEN_FD = 3
+const FIRST_FILE_FD = 4
+
+// Normalise a path relative to the preopen. Returns null when it climbs out.
+export function normalizePath(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('/')
+}
+
+/**
+ * @param {object} o
+ * @param {SharedArrayBuffer} o.ctlSab control buffer (holds the fd table)
+ * @param {string} o.preopen guest name of the preopened directory, e.g. "/g"
+ * @param {{path:string, buffer:SharedArrayBuffer|ArrayBuffer}[]} o.files
+ */
+export function createFs({ ctlSab, preopen, files }) {
+  const ctl = new Int32Array(ctlSab)
+  const list = files.map(f => ({ path: normalizePath(f.path), bytes: new Uint8Array(f.buffer) }))
+  const byPath = new Map(list.map((f, i) => [f.path, i]))
+  const dirs = new Set([''])
+  for (const f of list) {
+    const parts = f.path.split('/')
+    for (let i = 1; i < parts.length; i++) dirs.add(parts.slice(0, i).join('/'))
+  }
+
+  function lock() {
+    while (Atomics.compareExchange(ctl, CTL_FD_LOCK, 0, 1) !== 0) {
+      /* spin: held for a few loads/stores only */
+    }
+  }
+  const unlock = () => Atomics.store(ctl, CTL_FD_LOCK, 0)
+
+  const slot = fd => fd - FIRST_FILE_FD
+  const isFile = fd =>
+    fd >= FIRST_FILE_FD &&
+    slot(fd) < FD_MAX &&
+    Atomics.load(ctl, fdIndex(slot(fd), FD_KIND)) === 1
+  const getPos = s =>
+    (Atomics.load(ctl, fdIndex(s, FD_POS_HI)) >>> 0) * 2 ** 32 +
+    (Atomics.load(ctl, fdIndex(s, FD_POS_LO)) >>> 0)
+  const setPos = (s, pos) => {
+    Atomics.store(ctl, fdIndex(s, FD_POS_LO), pos % 2 ** 32 | 0)
+    Atomics.store(ctl, fdIndex(s, FD_POS_HI), Math.floor(pos / 2 ** 32) | 0)
+  }
+  const fileOf = fd => list[Atomics.load(ctl, fdIndex(slot(fd), FD_FILE))]
+
+  /** WASI filetype of an fd, or -1 when it is not open. */
+  function fdType(fd) {
+    if (fd >= 0 && fd <= 2) return FILETYPE_CHARACTER_DEVICE
+    if (fd === PREOPEN_FD) return FILETYPE_DIRECTORY
+    if (isFile(fd)) return FILETYPE_REGULAR_FILE
+    return -1
+  }
+
+  function prestatName(fd) {
+    return fd === PREOPEN_FD ? preopen : null
+  }
+
+  /** @returns {{errno:number, fd?:number}} */
+  function open(dirfd, path, oflags) {
+    if (dirfd !== PREOPEN_FD) return { errno: isFile(dirfd) || dirfd <= 2 ? E.NOTDIR : E.BADF }
+    const rel = normalizePath(path)
+    if (rel === null) return { errno: E.NOTCAPABLE }
+    const idx = byPath.get(rel)
+    if (idx === undefined) return { errno: dirs.has(rel) ? E.ISDIR : E.NOENT }
+    // Same as the runner: O_DIRECTORY (oflags bit 1) on a regular file is ENOTDIR.
+    if (oflags & 0x2) return { errno: E.NOTDIR }
+    // O_TRUNC / O_CREAT|O_EXCL on a read-only fs.
+    if (oflags & 0x8 || (oflags & 0x5) === 0x5) return { errno: E.ROFS }
+    lock()
+    try {
+      for (let s = 0; s < FD_MAX; s++) {
+        if (Atomics.load(ctl, fdIndex(s, FD_KIND)) !== 0) continue
+        Atomics.store(ctl, fdIndex(s, FD_FILE), idx)
+        setPos(s, 0)
+        Atomics.store(ctl, fdIndex(s, FD_KIND), 1)
+        return { errno: E.SUCCESS, fd: s + FIRST_FILE_FD }
+      }
+      return { errno: E.NFILE }
+    } finally {
+      unlock()
+    }
+  }
+
+  function close(fd) {
+    if (fd >= 0 && fd <= PREOPEN_FD) return E.SUCCESS
+    if (!isFile(fd)) return E.BADF
+    Atomics.store(ctl, fdIndex(slot(fd), FD_KIND), 0)
+    return E.SUCCESS
+  }
+
+  /**
+   * Copy up to dest.length bytes from the fd's position into dest.
+   * @returns {number} bytes copied, or -errno
+   */
+  function read(fd, dest) {
+    if (fd === 0) return 0 // stdin: always EOF
+    if (!isFile(fd)) return -E.BADF
+    const s = slot(fd)
+    const f = fileOf(fd)
+    lock()
+    try {
+      const pos = getPos(s)
+      const n = Math.max(0, Math.min(dest.length, f.bytes.length - pos))
+      if (n) dest.set(f.bytes.subarray(pos, pos + n))
+      setPos(s, pos + n)
+      return n
+    } finally {
+      unlock()
+    }
+  }
+
+  /** @returns {{errno:number, pos?:number}} */
+  function seek(fd, offset, whence) {
+    if (fd >= 0 && fd <= PREOPEN_FD) return { errno: E.SPIPE }
+    if (!isFile(fd)) return { errno: E.BADF }
+    const s = slot(fd)
+    const size = fileOf(fd).bytes.length
+    lock()
+    try {
+      let base
+      if (whence === 0) base = 0
+      else if (whence === 1) base = getPos(s)
+      else if (whence === 2) base = size
+      else return { errno: E.INVAL }
+      const pos = base + Number(offset)
+      if (pos < 0 || !Number.isSafeInteger(pos)) return { errno: E.INVAL }
+      setPos(s, pos)
+      return { errno: E.SUCCESS, pos }
+    } finally {
+      unlock()
+    }
+  }
+
+  /** @returns {{type:number,size:number}|null} */
+  function stat(fd) {
+    const type = fdType(fd)
+    if (type < 0) return null
+    return { type, size: type === FILETYPE_REGULAR_FILE ? fileOf(fd).bytes.length : 0 }
+  }
+
+  return { fdType, prestatName, open, close, read, seek, stat }
+}

package/src/host/gcnudge.js

@@ -0,0 +1,83 @@
+// D-419: make WebKit collect the garbage of a thread that holds the guest's shared memory.
+//
+// JavaScriptCore sizes how much a heap may allocate before its next collection from the heap's
+// size, and that size counts the shared WebAssembly.Memory the thread holds (gigabytes for
+// vm.wasm). Small objects then never reach it: a Worker making 26,000 short-lived arrays a
+// second grew the content process 0.95 MiB/s for ten minutes with no collection, whether the
+// big Memory was the instance's or only kept alive beside it, and whether or not the Worker
+// returned to its event loop; with 16 pages of memory it was flat. Every host call that
+// allocates (a console write, a JIT compile, the page's own work) added to it for good.
+//
+// An ArrayBuffer's size counts toward the next collection the moment it is made. One of 2 GiB
+// every 5 s, released at once (transfer(0)) and never written, so it costs no memory and about
+// 0.02 ms, makes the collection happen: the same Worker stayed flat at vm.wasm's 3.9 GiB.
+// Only JavaScriptCore needs it. Chromium's V8 collects such garbage on its own (per-Worker heaps
+// stayed at 1-6 MiB) and refuses a 2 GiB ArrayBuffer.
+
+export const NUDGE_BYTES = 2 ** 31
+export const NUDGE_MS = 5000
+
+/**
+ * Whether this engine is JavaScriptCore: WebKit's own user agent (Safari, and every browser
+ * on iOS). Blink keeps AppleWebKit/537.36 in its user agent; Gecko has no AppleWebKit.
+ */
+export function needsGcNudge(ua = globalThis.navigator?.userAgent || '') {
+  return /AppleWebKit\//.test(ua) && !/AppleWebKit\/537\.36/.test(ua)
+}
+
+/** One nudge. A refused allocation (no address space left) only skips this one. */
+export function gcNudge() {
+  try {
+    const b = new ArrayBuffer(NUDGE_BYTES)
+    b.transfer?.(0) // release the reservation now, not at the collection
+  } catch {}
+}
+
+/**
+ * For a thread that runs vm.wasm (it seldom returns to its event loop): a function to call on every host call,
+ * which nudges once NUDGE_MS has passed. Returns null where no nudge is needed.
+ * @param {{on?: boolean, now?: () => number, nudge?: () => void}} [o]
+ */
+export function gcNudger({ on = needsGcNudge(), now = () => performance.now(), nudge = gcNudge } = {}) {
+  if (!on) return null
+  let n = 0
+  let next = now() + NUDGE_MS
+  return () => {
+    if ((++n & 15) !== 0) return // a clock read every 16 calls is plenty: idle vCPUs call thousands of times a second
+    const t = now()
+    if (t < next) return
+    next = t + NUDGE_MS
+    nudge()
+  }
+}
+
+/** For a thread with an event loop: nudge every NUDGE_MS. Returns a stop function. */
+export function gcNudgeEvery({ on = needsGcNudge(), nudge = gcNudge } = {}) {
+  if (!on) return () => {}
+  const id = setInterval(nudge, NUDGE_MS)
+  return () => clearInterval(id)
+}
+
+/**
+ * W32: the wmd.jit_yield import for a thread that runs vm.wasm under JSPI (JIT sharing: its
+ * entry points are promising; wrap the result in WebAssembly.Suspending). JavaScriptCore gives a
+ * dead Instance's code back only once this thread's heap is swept, and the sweep runs from the
+ * thread's event loop, which a vCPU or service thread inside vm.wasm never reaches: in WebKit,
+ * 83 MB of released JIT code stayed pinned while three idle vCPUs sat in wasm, nudged or not; a
+ * 0 ms yield once per second or once per 5 s gave it back (93 -> 2 MB, test/features/w32,
+ * docs/plans/w32-holder-results.md). vm.wasm calls it only where no JIT block is on its stack: a
+ * JSPI suspension under a block chain traps in WebKit ("JSPI stack scan failed: unrecognized type
+ * of Wasm frame: RestoreFrameMode"). Once per `every` ms a call nudges the collector and returns a
+ * Promise settled from a 0 ms timer, so the event loop runs once; every other call returns at once.
+ * @param {{every?: number, now?: () => number, nudge?: () => void, delay?: (fn: () => void) => void}} [o]
+ */
+export function jitYielder({ every = 2000, now = () => performance.now(), nudge = gcNudge, delay = fn => setTimeout(fn, 0) } = {}) {
+  let next = now() + every
+  return () => {
+    const t = now()
+    if (t < next) return
+    next = t + every
+    nudge()
+    return new Promise(r => delay(r))
+  }
+}

package/src/host/i64shim.js

@@ -0,0 +1,81 @@
+// D-419: vm.wasm's imports with i64 parameters, called through a small wasm module that hands
+// JS each i64 as an f64 (f64.convert_i64_s), so no call makes a BigInt.
+//
+// The engine makes a BigInt for every i64 argument of a wasm-to-JS call, and WebKit collects
+// garbage late in a thread holding a large shared memory (gigabytes, as vm.wasm's; gcnudge.js):
+// 26,000 calls a second of an import with an i64 parameter grew the content process 0.62 MiB/s,
+// with 64 KiB of shared memory or an i32-only import 0.0. An idle guest calls clock_time_get
+// thousands of times a second. A wasm-to-wasm call makes nothing, and the f64 reaches JS as a
+// Number.
+//
+// Every value these parameters carry is exact as an f64: clock precision (ignored), seek
+// offsets (fs.seek wants a safe integer anyway), rights masks (under 2^30) and timeouts in ns
+// (-1 or less than 2^53). Signed conversion: -1 stays -1.
+
+/** name -> [module, params, results], the signatures vm.wasm imports (i = i32, I = i64). */
+export const I64_IMPORTS = {
+  clock_time_get: ['wasi_snapshot_preview1', 'iIi', 'i'],
+  fd_seek: ['wasi_snapshot_preview1', 'iIii', 'i'],
+  path_open: ['wasi_snapshot_preview1', 'iiiiiIIii', 'i'],
+  chan_recv: ['wmd', 'iiiI', 'i'],
+}
+
+const leb = n => {
+  const o = []
+  do {
+    let b = n & 0x7f
+    n >>>= 7
+    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 TY = { i: 0x7f, I: 0x7e, F: 0x7c }
+
+/** The shim's bytes for these names: imports j.<name> (i64 as f64), exports <name> (as vm.wasm imports it). */
+export function i64ShimBytes(names) {
+  const types = []
+  const imports = []
+  const funcs = []
+  const exports = []
+  const codes = []
+  names.forEach((name, k) => {
+    const [, params, results] = I64_IMPORTS[name]
+    const ft = (ps, rs) => [0x60, ...vec([...ps].map(c => [TY[c]])), ...vec([...rs].map(c => [TY[c]]))]
+    types.push(ft(params.replaceAll('I', 'F'), results), ft(params, results))
+    imports.push([...str('j'), ...str(name), 0x00, ...leb(2 * k)])
+    funcs.push(leb(2 * k + 1))
+    exports.push([...str(name), 0x00, ...leb(names.length + k)])
+    const body = [0] // no locals
+    ;[...params].forEach((c, i) => body.push(0x20, ...leb(i), ...(c === 'I' ? [0xb9] : []))) // local.get; f64.convert_i64_s
+    body.push(0x10, ...leb(k), 0x0b) // call j.<name>; end
+    codes.push([...leb(body.length), ...body])
+  })
+  return new Uint8Array([
+    0, 0x61, 0x73, 0x6d, 1, 0, 0, 0,
+    ...sec(1, vec(types)), ...sec(2, vec(imports)), ...sec(3, vec(funcs)), ...sec(7, vec(exports)), ...sec(10, vec(codes)),
+  ])
+}
+
+/**
+ * The import objects with each I64_IMPORTS function replaced by the shim's export, which calls
+ * the given JS function with Numbers. Modules and names not given are left as they are.
+ * @param {{[module: string]: {[name: string]: Function}}} imports
+ */
+export function shimI64Imports(imports) {
+  // a WebAssembly.Suspending import (W32: clock_time_get under JSPI) goes through the shim too
+  const isImport = f => typeof f === 'function' || (typeof WebAssembly.Suspending === 'function' && f instanceof WebAssembly.Suspending)
+  const names = Object.keys(I64_IMPORTS).filter(n => isImport(imports[I64_IMPORTS[n][0]]?.[n]))
+  if (!names.length) return imports
+  const j = Object.fromEntries(names.map(n => [n, imports[I64_IMPORTS[n][0]][n]]))
+  const { exports } = new WebAssembly.Instance(new WebAssembly.Module(i64ShimBytes(names)), { j })
+  const out = { ...imports }
+  for (const n of names) {
+    const m = I64_IMPORTS[n][0]
+    out[m] = { ...out[m], [n]: exports[n] }
+  }
+  return out
+}

package/src/host/jit-cache.js

@@ -0,0 +1,341 @@
+// W77: the JIT's module bytes kept across visits, in a store the page supplies
+// (bootWmd jit.cache: {get(key) -> Promise<Uint8Array|null>, put(key, bytes)}).
+//
+// The runner keeps the same thing on disk (D-295, runner/src/jit.rs known/note): vm.wasm
+// asks wmd.jit_known(key) for every block it decodes and, on a hit, takes the function an
+// earlier run compiled for that key instead of interpreting the block jit_threshold times
+// and translating it again; wmd.jit_note tells the host which function each newly
+// compiled block got. A block key (32 bytes, struct vm_known_rec) is the hash of the
+// block's guest bytes, its pc, stage, mode, length and a hash of the emitter's settings;
+// vm.wasm checks the span hash it gets back (ir_adopt), so a stale entry is only a miss.
+//
+// A compiled WebAssembly.Module cannot be stored (IndexedDB refuses it in Chromium,
+// Firefox and WebKit: DataCloneError), so the store holds bytes, under two kinds of key,
+// both under the vm.wasm build's sha256 (code from another build is never used):
+//
+//   jit1/<vm sha256>/idx                  the index: every block key noted so far, with
+//                                         its module, function and span (encodeIndex)
+//   jit1/<vm sha256>/m/<hash64>-<len>     one module's bytes, as jit_load/jit_compile got them
+//
+// jit_known runs for every decoded block (53,000 times in a boot) inside vm.wasm's cache
+// lock, so a miss must answer at once: the page reads the index before the guest starts
+// and hands every Worker a read-only table of it in a SharedArrayBuffer (buildKnown,
+// knownLookup). Only a hit waits (JSPI, as jit_sync does for the hub): the Worker asks
+// the page for that module's bytes once, and appends them as jit_load would; every later
+// hit on the module in the same flush generation uses the record the first one made
+// (a cell per module in the table, shared by the Workers).
+//
+// A module is put when a note first names one of its functions (jit_load modules that no
+// block key names are not kept); the index is put a few seconds after new notes and when
+// the machine ends (bootWmd waits for that last put, up to SAVE_WAIT_MS).
+
+import { hash64 } from './jit.js'
+
+export const CACHE_PREFIX = 'jit1'
+export const INDEX_MAGIC = 0x3143_4a57 // "WJC1"
+export const KEY_BYTES = 32 // struct vm_known_rec's key: hash, pc (u64), stage, mode, len, fp (u32)
+export const NOTE_BYTES = 56 // a jit_note record: key, rlo, rlen, span (u64), tidx, pad
+export const ENT_INTS = 6 // mod, func, rlo, rlen, spanLo, spanHi
+export const MOD_INTS = 5 // hl, hh, len, loaded record + 1, its generation
+export const M_LOADED = 3
+export const M_GEN = 4
+export const MAX_ENTRIES = 1 << 20 // index entries kept (past it new notes are dropped)
+export const SAVE_DELAY_MS = 5000 // index put this long after the last new note
+export const SAVE_WAIT_MS = 10_000 // bootWmd waits this long for the last puts when the machine ends
+
+const hex8 = v => (v >>> 0).toString(16).padStart(8, '0')
+export const indexKey = tag => `${CACHE_PREFIX}/${tag}/idx`
+export const moduleKey = (tag, hl, hh, len) => `${CACHE_PREFIX}/${tag}/m/${hex8(hh)}${hex8(hl)}-${len >>> 0}`
+const modId = (hl, hh, len) => `${hl >>> 0}:${hh >>> 0}:${len >>> 0}`
+const keyHex = k => {
+  let s = ''
+  for (let i = 0; i < KEY_BYTES; i++) s += k[i].toString(16).padStart(2, '0')
+  return s
+}
+
+/**
+ * The index blob: u32 magic, u32 module count M, u32 entry count N, M x (i32 hl, hh, len),
+ * N x (32-byte key, i32 mod, func, rlo, rlen, spanLo, spanHi). Little endian.
+ * @param {{mods:number[][], ents:{key:Uint8Array, v:number[]}[]}} ix
+ */
+export function encodeIndex(ix) {
+  const M = ix.mods.length
+  const N = ix.ents.length
+  const out = new Uint8Array(12 + M * 12 + N * (KEY_BYTES + ENT_INTS * 4))
+  const dv = new DataView(out.buffer)
+  dv.setUint32(0, INDEX_MAGIC, true)
+  dv.setUint32(4, M, true)
+  dv.setUint32(8, N, true)
+  let o = 12
+  for (const m of ix.mods) {
+    for (let i = 0; i < 3; i++) dv.setInt32(o + i * 4, m[i] | 0, true)
+    o += 12
+  }
+  for (const e of ix.ents) {
+    out.set(e.key, o)
+    o += KEY_BYTES
+    for (let i = 0; i < ENT_INTS; i++) dv.setInt32(o + i * 4, e.v[i] | 0, true)
+    o += ENT_INTS * 4
+  }
+  return out
+}
+
+/** The inverse of encodeIndex; throws on a blob that is not one (the caller starts empty). */
+export function decodeIndex(bytes) {
+  const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  const dv = new DataView(b.buffer, b.byteOffset, b.byteLength)
+  if (b.byteLength < 12 || dv.getUint32(0, true) !== INDEX_MAGIC) throw new Error('not a JIT cache index')
+  const M = dv.getUint32(4, true)
+  const N = dv.getUint32(8, true)
+  if (b.byteLength !== 12 + M * 12 + N * (KEY_BYTES + ENT_INTS * 4)) throw new Error('JIT cache index: bad length')
+  const mods = []
+  let o = 12
+  for (let j = 0; j < M; j++, o += 12) mods.push([dv.getInt32(o, true), dv.getInt32(o + 4, true), dv.getInt32(o + 8, true)])
+  const ents = []
+  for (let j = 0; j < N; j++) {
+    const key = b.slice(o, o + KEY_BYTES)
+    o += KEY_BYTES
+    const v = []
+    for (let i = 0; i < ENT_INTS; i++, o += 4) v.push(dv.getInt32(o, true))
+    if (v[0] < 0 || v[0] >= M) throw new Error('JIT cache index: bad module number')
+    ents.push({ key, v })
+  }
+  return { mods, ents }
+}
+
+const slotOf = (k, i, mask) => {
+  // the key starts with the 64-bit hash of the block's bytes: its words are spread enough
+  const h = Math.imul(k[i] ^ k[i + 2], 0x9e3779b1) ^ k[i + 1] ^ k[i + 3]
+  return (h >>> 0) & mask
+}
+
+/**
+ * The Workers' read-only table of an index: one SharedArrayBuffer with a header
+ * (capacity, entries, modules), the keys, the entries, the open-addressing slots
+ * (entry + 1) and one cell per module (MOD_INTS: hl, hh, len, and the record the first
+ * hit of this boot loaded it as, + 1, with that record's flush generation).
+ */
+export function buildKnown(ix) {
+  const N = ix.ents.length
+  const M = ix.mods.length
+  let cap = 16
+  while (cap < N * 2) cap *= 2
+  const ints = 4 + N * (KEY_BYTES / 4) + N * ENT_INTS + cap + M * MOD_INTS
+  const sab = new SharedArrayBuffer(ints * 4)
+  const I = new Int32Array(sab)
+  I[0] = cap
+  I[1] = N
+  I[2] = M
+  const kOff = 4
+  const eOff = kOff + N * (KEY_BYTES / 4)
+  const sOff = eOff + N * ENT_INTS
+  const mOff = sOff + cap
+  const K = new Int32Array(KEY_BYTES / 4)
+  const K8 = new Uint8Array(K.buffer)
+  for (let j = 0; j < N; j++) {
+    const e = ix.ents[j]
+    K8.set(e.key)
+    I.set(K, kOff + j * (KEY_BYTES / 4))
+    I.set(e.v, eOff + j * ENT_INTS)
+    let s = slotOf(K, 0, cap - 1)
+    while (I[sOff + s]) s = (s + 1) & (cap - 1)
+    I[sOff + s] = j + 1
+  }
+  for (let j = 0; j < M; j++) I.set(ix.mods[j], mOff + j * MOD_INTS)
+  return sab
+}
+
+/** A Worker's view of buildKnown's table. find(key Int32Array(8)) -> entry or -1. */
+export function knownLookup(sab) {
+  const I = new Int32Array(sab)
+  const cap = I[0]
+  const N = I[1]
+  const M = I[2]
+  const kOff = 4
+  const eOff = kOff + N * (KEY_BYTES / 4)
+  const sOff = eOff + N * ENT_INTS
+  const mOff = sOff + cap
+  return {
+    entries: N,
+    modules: M,
+    find(K) {
+      if (!N) return -1
+      for (let s = slotOf(K, 0, cap - 1); ; s = (s + 1) & (cap - 1)) {
+        const j = I[sOff + s] - 1
+        if (j < 0) return -1
+        const b = kOff + j * (KEY_BYTES / 4)
+        let same = true
+        for (let i = 0; i < KEY_BYTES / 4; i++) {
+          if (I[b + i] !== K[i]) {
+            same = false
+            break
+          }
+        }
+        if (same) return j
+      }
+    },
+    /** [mod, func, rlo, rlen, spanLo, spanHi] */
+    entry: j => I.subarray(eOff + j * ENT_INTS, eOff + (j + 1) * ENT_INTS),
+    mod: m => I.subarray(mOff + m * MOD_INTS, mOff + m * MOD_INTS + 3),
+    /** the record + 1 and generation a hit of this boot loaded module m as (0 when none) */
+    loaded: m => [Atomics.load(I, mOff + m * MOD_INTS + M_LOADED), Atomics.load(I, mOff + m * MOD_INTS + M_GEN)],
+    setLoaded(m, rec, gen) {
+      Atomics.store(I, mOff + m * MOD_INTS + M_GEN, gen)
+      Atomics.store(I, mOff + m * MOD_INTS + M_LOADED, rec + 1)
+    },
+  }
+}
+
+/** Checks the bytes a store returned for module m of the index before a Worker loads them. */
+export function moduleBytesFit(bytes, hl, hh, len) {
+  if (!(bytes instanceof Uint8Array) || bytes.length !== len >>> 0) return false
+  const [a, b] = hash64(bytes)
+  return a === hl && b === hh
+}
+
+/**
+ * The page's side: reads the index before the guest starts, answers the Workers' module
+ * reads, takes their notes and puts the modules they name and the index.
+ * @param {{cache:{get:Function, put:Function}, tag:string, log?:(s:string)=>void, saveDelayMs?:number}} o
+ */
+export function createJitCacheHost({ cache, tag, log = () => {}, saveDelayMs = SAVE_DELAY_MS }) {
+  if (!cache || typeof cache.get !== 'function' || typeof cache.put !== 'function') throw new Error('jit.cache needs get(key) and put(key, bytes)')
+  const ix = { mods: [], ents: [] }
+  const modIds = new Map() // modId -> number in ix.mods
+  const entIds = new Map() // keyHex -> number in ix.ents
+  const stored = new Set() // modIds the store has (from the index, or put by this boot)
+  const stats = { indexEntries: 0, indexModules: 0, indexBytes: 0, indexLoadMs: 0, gets: 0, getMisses: 0, getBytes: 0, puts: 0, putBytes: 0, notes: 0, newEntries: 0, indexPuts: 0, dropped: 0, errors: 0 }
+  let dirty = false
+  let timer = null
+  let chain = Promise.resolve() // puts in order: a module before the index that names it
+  let errLogged = false
+  const fail = (what, err) => {
+    stats.errors++
+    if (!errLogged) {
+      errLogged = true
+      log(`wmd-web: jit cache: ${what}: ${err && err.message ? err.message : err}`)
+    }
+  }
+  const queue = f => (chain = chain.then(f).catch(err => fail('put', err)))
+
+  function addMod(hl, hh, len) {
+    const id = modId(hl, hh, len)
+    let m = modIds.get(id)
+    if (m === undefined) {
+      m = ix.mods.length
+      ix.mods.push([hl | 0, hh | 0, len | 0])
+      modIds.set(id, m)
+    }
+    return m
+  }
+
+  function saveSoon() {
+    dirty = true
+    if (timer || !saveDelayMs) return
+    timer = setTimeout(() => {
+      timer = null
+      saveIndex()
+    }, saveDelayMs)
+  }
+  function saveIndex() {
+    if (!dirty) return chain
+    dirty = false
+    const bytes = encodeIndex(ix)
+    return queue(async () => {
+      await cache.put(indexKey(tag), bytes)
+      stats.indexPuts++
+      stats.putBytes += bytes.length
+    })
+  }
+
+  return {
+    stats,
+    /** Read the index; a missing or unreadable one is an empty cache. The table for the Workers. */
+    async load() {
+      const t = performance.now()
+      try {
+        const b = await cache.get(indexKey(tag))
+        if (b) {
+          const got = decodeIndex(b)
+          stats.indexBytes = b.byteLength
+          for (const m of got.mods) {
+            addMod(m[0], m[1], m[2])
+            stored.add(modId(m[0], m[1], m[2]))
+          }
+          for (const e of got.ents) {
+            entIds.set(keyHex(e.key), ix.ents.length)
+            ix.ents.push(e)
+          }
+        }
+      } catch (err) {
+        fail('index', err)
+      }
+      stats.indexEntries = ix.ents.length
+      stats.indexModules = ix.mods.length
+      stats.indexLoadMs = Math.round(performance.now() - t)
+      return buildKnown(ix)
+    },
+    /** A Worker's read of module m's bytes (null: the store has none). */
+    async get(hl, hh, len) {
+      stats.gets++
+      try {
+        const b = await cache.get(moduleKey(tag, hl, hh, len))
+        if (!b) {
+          stats.getMisses++
+          return null
+        }
+        const copy = new Uint8Array(b) // the store's buffer is not ours to transfer
+        stats.getBytes += copy.length
+        return copy
+      } catch (err) {
+        fail('get', err)
+        return null
+      }
+    },
+    /**
+     * A Worker's notes: {mods:[{hl,hh,len,bytes?}], ents:[{key, mod (number in mods), func, rlo, rlen, spanLo, spanHi}]}.
+     * A module's bytes come with the first note that names it from that Worker.
+     */
+    note({ mods, ents }) {
+      stats.notes += ents.length
+      const ids = mods.map(m => {
+        const id = modId(m.hl, m.hh, m.len)
+        if (m.bytes && !stored.has(id)) {
+          stored.add(id)
+          const bytes = m.bytes
+          queue(async () => {
+            await cache.put(moduleKey(tag, m.hl, m.hh, m.len), bytes)
+            stats.puts++
+            stats.putBytes += bytes.length
+          })
+        }
+        return stored.has(id) ? addMod(m.hl, m.hh, m.len) : -1
+      })
+      for (const e of ents) {
+        const m = ids[e.mod]
+        if (m === undefined || m < 0) continue // its bytes never reached the store
+        const k = keyHex(e.key)
+        const v = [m, e.func, e.rlo, e.rlen, e.spanLo, e.spanHi]
+        const j = entIds.get(k)
+        if (j !== undefined) {
+          ix.ents[j].v = v // a block compiled again (after a stale hit): the newest function
+        } else if (ix.ents.length >= MAX_ENTRIES) {
+          stats.dropped++
+          continue
+        } else {
+          entIds.set(k, ix.ents.length)
+          ix.ents.push({ key: e.key, v })
+          stats.newEntries++
+        }
+        saveSoon()
+      }
+    },
+    /** The machine ended: put the index (if it changed); resolves when every put is done or after waitMs. */
+    save(waitMs = SAVE_WAIT_MS) {
+      clearTimeout(timer)
+      timer = null
+      const done = saveIndex()
+      return Promise.race([done, new Promise(r => setTimeout(r, waitMs))])
+    },
+  }
+}