@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/host/ckpt-point.js

@@ -0,0 +1,160 @@
+// P-B9: the guest's checkpoint point, the host half that runs inside the vCPU 0 Worker.
+//
+// The guest (machine.c machine_point) stops every other vCPU at a block boundary, drains the
+// file share, stops its service threads and then calls the import wmd.point(kind, hdr, len) on
+// vCPU 0, with nothing else touching memory 0. This module is that import. While it runs the
+// machine is frozen, so it
+//   1. tells the page the point began ({t:'ckpt-point', hdr}): the page then asks the channel
+//      service Worker for its state and the JIT hub for module bytes, at this same instant;
+//   2. copies every non-zero 64 KiB page of memory 0 ({t:'ckpt-mem'}: an index of page numbers
+//      and the page bytes in chunks), the way the runner's snapshot keeps "every non-zero page";
+//   3. waits for the page's go (CTL_CK_GO), then returns 0 and the guest carries on.
+// A point that failed in the guest (a vCPU did not stop, the share did not drain: hdr.status != 0)
+// is reported as {t:'ckpt-failed'} and returns 0 at once; the guest has restarted its vCPUs.
+//
+// wmd.ctl_attach(word_addr) is called by the guest's ctl thread when it starts, and again after
+// every checkpoint when the vCPUs run again. The page writes a request kind into the word at
+// word_addr (guest memory) and notifies it; the ctl thread hands it to vCPU 0.
+
+import { CTL_CK_ATTACHES, CTL_CK_GO, CTL_CK_HOSTREQ, CTL_CK_POINTS } from './layout.js'
+
+export const PAGE = 65536
+/** struct vm_snapshot_hdr (guest/vm/include/vm/snapshot.h), 336 bytes: field offsets read here. */
+export const HDR_LEN = 336
+export const HDR_KIND = 296
+export const HDR_STATUS = 300
+export const VM_POINT_CKPT = 2
+export const POINT_STATUS = { 0: 'ok', 1: 'a vCPU did not reach a block boundary in time', 2: 'the file share did not drain in time' }
+/** The page asks the guest for a checkpoint by storing this in the word. */
+export const REQ_CKPT = VM_POINT_CKPT
+
+/** Pages per chunk of the memory section (32 MiB). */
+export const CHUNK_PAGES = 512
+
+/**
+ * Non-zero pages of memory: {index: Uint32Array of page numbers, chunks: ArrayBuffer[] (pages
+ * back to back, CHUNK_PAGES each), pages (total), nonzero, scanMs, copyMs}. Reads the memory
+ * without atomics: the machine is frozen.
+ */
+export function scanMemory(memory, { now = () => performance.now(), chunkPages = CHUNK_PAGES, limitBytes = Infinity, verifyAbove = false } = {}) {
+  const buf = memory.buffer
+  // limitBytes: pages from here up are taken to be zero and are not read. Reading an untouched page of a shared
+  // memory commits it in WebKit (W34: a full walk of a 3968 MiB memory added about 2.2 GB of footprint), so a caller
+  // that knows where the guest's heap ends should say so; the page count of the checkpoint stays the memory's.
+  const total = buf.byteLength / PAGE
+  const pages = Math.min(total, Math.ceil(limitBytes / PAGE))
+  const w = new Int32Array(buf)
+  const u8 = new Uint8Array(buf)
+  const per = PAGE / 4
+  const t0 = now()
+  let idx = new Uint32Array(Math.min(pages, 1 << 14))
+  let n = 0
+  for (let p = 0; p < pages; p++) {
+    const lo = p * per
+    const hi = lo + per
+    let nz = false
+    for (let i = lo; i < hi; i += 8) {
+      if ((w[i] | w[i + 1] | w[i + 2] | w[i + 3] | w[i + 4] | w[i + 5] | w[i + 6] | w[i + 7]) !== 0) {
+        nz = true
+        break
+      }
+    }
+    if (nz) {
+      if (n === idx.length) {
+        const g = new Uint32Array(idx.length * 2)
+        g.set(idx)
+        idx = g
+      }
+      idx[n++] = p
+    }
+  }
+  // diagnostics (verifyAbove): non-zero pages above the bound, which would be lost. Reads them (commits them in WebKit).
+  let aboveNonzero = 0
+  if (verifyAbove) {
+    for (let p = pages; p < total; p++) {
+      const lo = p * per
+      for (let i = lo; i < lo + per; i += 8) {
+        if ((w[i] | w[i + 1] | w[i + 2] | w[i + 3] | w[i + 4] | w[i + 5] | w[i + 6] | w[i + 7]) !== 0) {
+          aboveNonzero++
+          break
+        }
+      }
+    }
+  }
+  const t1 = now()
+  const chunks = []
+  for (let k = 0; k < n; k += chunkPages) {
+    const m = Math.min(chunkPages, n - k)
+    const c = new Uint8Array(m * PAGE)
+    for (let j = 0; j < m; j++) c.set(u8.subarray(idx[k + j] * PAGE, (idx[k + j] + 1) * PAGE), j * PAGE)
+    chunks.push(c.buffer)
+  }
+  return { index: idx.slice(0, n), chunks, pages: total, scannedPages: pages, aboveNonzero, nonzero: n, scanMs: t1 - t0, copyMs: now() - t1 }
+}
+
+/**
+ * The imports. memory: the machine's shared memory; ctl: the control block's Int32Array; post:
+ * message to the page; goTimeoutMs: how long vCPU 0 waits for the page (a page that is gone
+ * makes the point fail: the guest goes on, as it does for any failed point).
+ */
+export function createCkptImports({ memory, ctl, post, scanLimit = null, verifyBound = false, useHeapTop = false, heapTop = () => null, goTimeoutMs = 60_000, now = () => performance.timeOrigin + performance.now() }) {
+  return {
+    ctl_attach(wordAddr) {
+      Atomics.store(ctl, CTL_CK_HOSTREQ, wordAddr >>> 0)
+      Atomics.add(ctl, CTL_CK_ATTACHES, 1)
+      return 0
+    },
+    point(kind, hp, hl) {
+      if (kind !== VM_POINT_CKPT) return -22
+      Atomics.add(ctl, CTL_CK_POINTS, 1)
+      const at = now()
+      const len = Math.min(hl >>> 0, HDR_LEN)
+      const hdr = new Uint8Array(memory.buffer, hp >>> 0, len).slice()
+      const status = len >= HDR_STATUS + 4 ? new DataView(hdr.buffer).getUint32(HDR_STATUS, true) : 0
+      if (status !== 0) {
+        post({ t: 'ckpt-failed', status, why: POINT_STATUS[status] || `status ${status}`, hdr })
+        return 0
+      }
+      Atomics.store(ctl, CTL_CK_GO, 0)
+      post({ t: 'ckpt-point', hdr, at })
+      let cap
+      try {
+        // the bound: the caller's, else the end of memory 0 in use (vm.wasm's vm_heap_top), else all of it
+        // W58: on by default (boot.js); the heap's break only grows (sbrk refuses a negative increment), and a WebKit run with
+        // verifyBound found no non-zero page above it
+        const top = scanLimit ?? (useHeapTop ? heapTop() : null)
+        const limit = typeof top === 'number' && top > 0 ? Math.min(top, memory.buffer.byteLength) : Infinity
+        cap = scanMemory(memory, { now, limitBytes: limit, verifyAbove: verifyBound })
+        cap.limitBytes = Number.isFinite(limit) ? limit : null
+        // the live g_rsv {brk, end} of vm.wasm 50c6495e / 3aef93fc (linear address 4251160), next to what vm_heap_top() says
+        try {
+          const g = new BigUint64Array(memory.buffer, 4251160, 2)
+          cap.brkLive = Number(g[0])
+          cap.endLive = Number(g[1])
+        } catch {}
+        cap.heapTopRet = heapTop()
+      } catch (err) {
+        post({ t: 'ckpt-mem-error', message: String(err && err.message ? err.message : err) })
+        Atomics.wait(ctl, CTL_CK_GO, 0, goTimeoutMs)
+        Atomics.store(ctl, CTL_CK_GO, 0)
+        return -12
+      }
+      post({ t: 'ckpt-mem', index: cap.index, chunks: cap.chunks, pages: cap.pages, scannedPages: cap.scannedPages, aboveNonzero: cap.aboveNonzero, brkLive: cap.brkLive, endLive: cap.endLive, heapTopRet: cap.heapTopRet, limitBytes: cap.limitBytes, nonzero: cap.nonzero, scanMs: cap.scanMs, copyMs: cap.copyMs, doneAt: now() }, [cap.index.buffer, ...cap.chunks])
+      const r = Atomics.wait(ctl, CTL_CK_GO, 0, goTimeoutMs)
+      const go = Atomics.load(ctl, CTL_CK_GO)
+      Atomics.store(ctl, CTL_CK_GO, 0)
+      if (r === 'timed-out' || go !== 1) return -1
+      return 0
+    },
+  }
+}
+
+/** Asks the guest for a checkpoint: false when its ctl thread has not attached (no checkpoint support, or not booted far enough). */
+export function requestCheckpoint(memory, ctl) {
+  const addr = Atomics.load(ctl, CTL_CK_HOSTREQ)
+  if (!addr) return false
+  const w = new Int32Array(memory.buffer, addr & ~3, 1)
+  Atomics.store(w, 0, REQ_CKPT)
+  Atomics.notify(w, 0, 1)
+  return true
+}

package/src/host/ckpt-save.js

@@ -0,0 +1,64 @@
+// P-B9: the two halves of the OPFS save's pull protocol, apart from the Worker and the page so tests can drive them.
+//
+//   worker side  createSaver(post): start(m) maps the save's section sizes into lazy chunks; each lazy chunk asks the page for
+//                its bytes ({need:true, saveId, si, ci}) when the writer reaches it and is dropped once written.
+//                chunk(m) delivers the page's answer: bytes, or {error} (the page could not copy the chunk: out of memory).
+//   page side    answerNeed(ck, need, send): copies exactly the chunk asked for and sends {op:'chunk', saveId, si, ci, buf},
+//                or {op:'chunk', ..., error} when the copy failed, so the save fails instead of waiting for ever.
+//
+// One save at a time: `saving` is what refuses a second ("busy"); done() clears it, so a failed save does not block the next.
+import { CheckpointError } from './ckpt-file.js'
+
+export function createSaver(post) {
+  let saving = null // {id, waits: Map key -> {resolve, reject}}
+  return {
+    get busy() {
+      return !!saving
+    },
+    /** Maps m.sections ({name, lens}) into lazy chunks. `saving` is set only after the sections were validated and mapped. */
+    start(m) {
+      if (saving) throw new CheckpointError('busy', 'a checkpoint save is already running in this browser (saves are one at a time)')
+      if (!Array.isArray(m.sections) || !m.sections.every(s => s && typeof s.name === 'string' && Array.isArray(s.lens) && s.lens.every(n => Number.isInteger(n) && n >= 0))) {
+        throw new CheckpointError('malformed', 'the save request has no valid section list')
+      }
+      const waits = new Map()
+      const sections = m.sections.map((s, si) => ({
+        name: s.name,
+        chunks: s.lens.map((len, ci) => {
+          const f = () =>
+            new Promise((resolve, reject) => {
+              waits.set(`${si}:${ci}`, { resolve, reject })
+              post({ need: true, saveId: m.id, si, ci })
+            })
+          f.size = len
+          Object.defineProperty(f, 'length', { value: len })
+          return f
+        }),
+      }))
+      saving = { id: m.id, waits }
+      return sections
+    },
+    /** The page's answer to a need. */
+    chunk(m) {
+      const w = saving && saving.id === m.saveId ? saving.waits.get(`${m.si}:${m.ci}`) : null
+      if (!w) return false
+      saving.waits.delete(`${m.si}:${m.ci}`)
+      if (m.error) w.reject(new CheckpointError('io', `the page could not copy checkpoint chunk ${m.si}:${m.ci} (${m.error})`))
+      else w.resolve(new Uint8Array(m.buf))
+      return true
+    },
+    /** The save ended, however it ended. */
+    done() {
+      saving = null
+    },
+  }
+}
+
+export function answerNeed(ck, need, send) {
+  try {
+    const buf = ck.sections[need.si].chunks[need.ci].slice().buffer
+    send({ op: 'chunk', saveId: need.saveId, si: need.si, ci: need.ci, buf }, [buf])
+  } catch (e) {
+    send({ op: 'chunk', saveId: need.saveId, si: need.si, ci: need.ci, error: String((e && e.message) || e) })
+  }
+}

package/src/host/ckpt.js

@@ -0,0 +1,434 @@
+// P-B9: checkpoints, the page's side: what a checkpoint is made of, the keys that say which
+// machine it belongs to, and the store (OPFS, through ckpt-io.js, or memory).
+//
+// A checkpoint is {header, sections}. The header is JSON (ckpt-file.js adds the section table when
+// it is written); sections are named lists of byte chunks:
+//   mem-index  Uint32 page numbers of the non-zero 64 KiB pages of memory 0
+//   mem        those pages' bytes, back to back (32 MiB chunks)
+//   jit-recs   the JIT door's slot records (jit-snap.js), jit-log: the modules' bytes
+//   svc-<port> the 9P service's state for that port (fs/svc-snapshot.js)
+//   ctl        the control block's WASI fd table (Int32 cells)
+// Taken by vm.checkpoint() (boot.js), restored by bootWmd({restore}).
+import { FORMAT_VERSION, CheckpointError, concat, memoryFile, readHeader, readSection, sectionBytes, sha256Hex, writeCheckpoint } from './ckpt-file.js'
+import { answerNeed } from './ckpt-save.js'
+import { PAGE } from './ckpt-point.js'
+import { validateSnap, widenRecs } from './jit-snap.js'
+import { FD_BASE, FD_FILE, FD_INTS, FD_KIND, FD_MAX } from './layout.js'
+
+export { CheckpointError, FORMAT_VERSION, sha256Hex }
+
+const b64 = u8 => {
+  let s = ''
+  for (let i = 0; i < u8.length; i += 8192) s += String.fromCharCode.apply(null, u8.subarray(i, i + 8192))
+  return btoa(s)
+}
+export const fromB64 = s => Uint8Array.from(atob(s), c => c.charCodeAt(0))
+
+/** A fresh (non-shared) copy: SubtleCrypto refuses views of shared memory. */
+const plain = u8 => (u8.buffer instanceof SharedArrayBuffer ? u8.slice() : u8)
+
+/** SHA-256 of a pack or file that may be large: its size, and (when large) only its first 64 KiB and last 4 MiB. */
+export async function sampleKey(u8, { head = 64 << 10, tail = 4 << 20 } = {}) {
+  if (u8.length <= head + tail) return `${u8.length}:${await sha256Hex(plain(u8))}`
+  const a = await sha256Hex(plain(u8.subarray(0, head)))
+  const b = await sha256Hex(plain(u8.subarray(u8.length - tail)))
+  return `${u8.length}:${a}:${b}`
+}
+
+/** Full digest of a pack: its size and the SHA-256 of the SHA-256s of its 8 MiB pieces (pieces are copied out of shared memory one at a time). */
+export async function treeKey(u8, piece = 8 << 20) {
+  const parts = []
+  for (let o = 0; o < u8.length; o += piece) parts.push(await sha256Hex(plain(u8.subarray(o, Math.min(u8.length, o + piece)))))
+  return `${u8.length}:${await sha256Hex(new TextEncoder().encode(parts.join('')))}`
+}
+
+/** [[treeKey of each layer] per service], from the fetched layers (ArrayBuffers) as boot.js holds them. */
+export async function packDigestsOf(chanLayers) {
+  return Promise.all(chanLayers.map(ls => Promise.all(ls.map(l => treeKey(new Uint8Array(l))))))
+}
+
+/** A snapshot's pack digests must equal this boot's: the boot key only samples each pack, this covers every byte. */
+export function checkPacksFit(theirs, mine) {
+  if (!mine) return
+  if (!Array.isArray(theirs)) throw new CheckpointError('stale', 'this snapshot does not record the full digests of its image layers (taken by an older build): it cannot be checked against the packs this page loaded; take a new one')
+  for (let i = 0; i < Math.max(theirs.length, mine.length); i++) {
+    const a = theirs[i] || []
+    const b = mine[i] || []
+    for (let j = 0; j < Math.max(a.length, b.length); j++) {
+      if (a[j] !== b[j]) throw new CheckpointError('stale', `this snapshot was taken over a different image layer: service ${i} layer ${j} is ${String(a[j]).slice(0, 30)} there and ${String(b[j]).slice(0, 30)} here (same boot key, other bytes: a rebuilt pack?)`)
+    }
+  }
+}
+
+/**
+ * The key of a boot: which vm.wasm, which kernel and initramfs, which command line and
+ * environment, which packs and bundle files. A checkpoint restores only into a boot with the
+ * same key (research/10 R11).
+ */
+export async function bootKeyOf({ vmKey, argv, env, preopen, files, services, maxPages }) {
+  const fileKeys = {}
+  for (const f of files) fileKeys[f.path] = await sampleKey(new Uint8Array(f.buffer), { head: 1 << 30, tail: 1 << 30 }) // the kernel and initramfs in full (a few MB: cheap)
+  const svc = []
+  for (const s of services) {
+    const layers = []
+    for (const l of s.layers || []) layers.push(await sampleKey(new Uint8Array(l)))
+    const bundle = {}
+    for (const [p, f] of Object.entries(s.files || {})) {
+      const d = f && typeof f === 'object' && 'data' in f ? f.data : f
+      const u8 = typeof d === 'string' ? new TextEncoder().encode(d) : new Uint8Array(d)
+      bundle[p] = await sampleKey(u8)
+    }
+    // W56: a guest on an in-page switch has a network, and its address is in its memory (a restore must give it the same one)
+    const sw = s.switch ? { ip: s.switch.address(s.name, s.ip) } : {}
+    svc.push({ port: s.port, kind: s.kind, at: s.at || '', yamux: !!s.yamux, net: !!(s.relay || s.switch), ...sw, layers, bundle })
+  }
+  const desc = { vmKey, argv, env, preopen, files: fileKeys, services: svc, maxPages }
+  return { key: await sha256Hex(new TextEncoder().encode(JSON.stringify(desc))), desc }
+}
+
+/** The ports a resume writes for the guest (vm_resume_args), from the command line. */
+export function resumePorts(args) {
+  const get = name => {
+    const i = args.indexOf(name)
+    return i >= 0 && /^[0-9]+$/.test(args[i + 1] ?? '') ? Number(args[i + 1]) : 0
+  }
+  return { net: get('--net'), p9: get('--p9'), console: get('--console'), control: get('--control'), stats: args.includes('--stats') }
+}
+
+/** Parts packed into chunks of at most `limit` bytes; a single part over the limit is split too (a 74 MB JIT log is three chunks). */
+export const concatChunks = (parts, limit) => {
+  const out = []
+  let cur = []
+  let n = 0
+  const flush = () => {
+    if (cur.length) out.push(concat(cur))
+    cur = []
+    n = 0
+  }
+  for (const p of parts) {
+    if (p.length > limit) {
+      flush()
+      for (let o = 0; o < p.length; o += limit) out.push(p.subarray(o, Math.min(p.length, o + limit)))
+      continue
+    }
+    if (cur.length && n + p.length > limit) flush()
+    cur.push(p)
+    n += p.length
+  }
+  flush()
+  return out.length ? out : [new Uint8Array(0)]
+}
+
+/** The control block's fd table cells as bytes. */
+export function fdTableBytes(ctl) {
+  const cells = new Int32Array(FD_MAX * FD_INTS)
+  for (let i = 0; i < cells.length; i++) cells[i] = Atomics.load(ctl, FD_BASE + i)
+  return new Uint8Array(cells.buffer)
+}
+
+/** Writes the saved fd table into a new control block. */
+export function validateFdTable(bytes, nfiles = Infinity) {
+  if (bytes.byteLength % 4) throw new CheckpointError('malformed', `the checkpoint's fd table is ${bytes.byteLength} bytes, not a whole number of cells`)
+  const cells = new Int32Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength)) // aligned copy
+  if (cells.length !== FD_MAX * FD_INTS) throw new CheckpointError('malformed', `the checkpoint's fd table has ${cells.length} cells; this build has ${FD_MAX * FD_INTS}`)
+  for (let fd = 0; fd < FD_MAX; fd++) {
+    const kind = cells[fd * FD_INTS + FD_KIND]
+    if (kind !== 0 && kind !== 1) throw new CheckpointError('malformed', `fd ${fd + 4} has kind ${kind} in the checkpoint (0 or 1 only)`)
+    if (kind === 1 && !(cells[fd * FD_INTS + FD_FILE] >= 0 && cells[fd * FD_INTS + FD_FILE] < nfiles)) throw new CheckpointError('malformed', `fd ${fd + 4} refers to boot file ${cells[fd * FD_INTS + FD_FILE]} and this boot has ${nfiles}`)
+  }
+  return cells
+}
+
+export function restoreFdTable(ctl, bytes, nfiles = Infinity) {
+  const cells = validateFdTable(bytes, nfiles)
+  for (let i = 0; i < cells.length; i++) Atomics.store(ctl, FD_BASE + i, cells[i])
+}
+
+/**
+ * Assembles a checkpoint from what the capture collected.
+ * @param {object} p {meta, hdr (Uint8Array, the guest's 336 bytes), mem: {index, chunks (ArrayBuffer[]), pages, nonzero},
+ *   jit: {snap (jit-snap capture)}|null, svc: {port: {segments}}, ctl (bytes), names?: [[name, ip]] (W59: the network's
+ *   placeholder map, an optional section `net-names`; FORMAT_VERSION is unchanged and images without it still load)}
+ */
+export function assembleCheckpoint(p) {
+  const sections = []
+  sections.push({ name: 'mem-index', chunks: [new Uint8Array(p.mem.index.buffer, p.mem.index.byteOffset, p.mem.index.byteLength)] })
+  sections.push({ name: 'mem', chunks: p.mem.chunks.map(c => new Uint8Array(c)) })
+  const header = {
+    ...p.meta,
+    format: FORMAT_VERSION,
+    createdAt: new Date().toISOString(),
+    memPages: p.mem.pages,
+    memNonzero: p.mem.nonzero,
+    pageSize: PAGE,
+    guestHdr: b64(p.hdr),
+    svcPorts: Object.keys(p.svc).map(Number),
+  }
+  if (p.jit) {
+    sections.push({ name: 'jit-recs', chunks: [new Uint8Array(p.jit.snap.recs.buffer, p.jit.snap.recs.byteOffset, p.jit.snap.recs.byteLength)] })
+    sections.push({ name: 'jit-log', chunks: concatChunks([p.jit.snap.log], 32 << 20) })
+    header.jit = { gen: p.jit.snap.gen, nslots: p.jit.snap.nslots, slot0: p.jit.snap.slot0, nrec: p.jit.snap.nrec }
+  }
+  for (const [port, d] of Object.entries(p.svc)) sections.push({ name: `svc-${port}`, chunks: concatChunks(d.segments, 16 << 20) })
+  sections.push({ name: 'ctl', chunks: [p.ctl] })
+  if (p.names?.length) sections.push({ name: 'net-names', chunks: [new TextEncoder().encode(JSON.stringify(p.names))] })
+  header.sizes = Object.fromEntries(sections.map(s => [s.name, s.chunks.reduce((n, c) => n + c.length, 0)]))
+  header.bytes = Object.values(header.sizes).reduce((a, b) => a + b, 0)
+  return { header, sections }
+}
+
+/** The typed pieces boot.js restores from. Throws CheckpointError for a checkpoint that cannot be used. */
+export function parseCheckpoint(ck) {
+  const h = ck.header
+  const get = name => {
+    const s = ck.sections.find(x => x.name === name)
+    if (!s) throw new CheckpointError('malformed', `checkpoint has no section ${name}`)
+    return s.chunks
+  }
+  const idxBytes = concat(get('mem-index'))
+  if (idxBytes.length % 4) throw new CheckpointError('malformed', 'mem-index is not a list of 32-bit page numbers')
+  const index = new Uint32Array(idxBytes.buffer.slice(idxBytes.byteOffset, idxBytes.byteOffset + idxBytes.length))
+  const memChunks = get('mem')
+  const have = memChunks.reduce((n, c) => n + c.length, 0)
+  if (have !== index.length * PAGE) throw new CheckpointError('malformed', `memory section holds ${have} bytes for ${index.length} pages`)
+  memChunks.forEach((c, i) => {
+    if (c.length % PAGE) throw new CheckpointError('malformed', `memory chunk ${i} is ${c.length} bytes, not a whole number of ${PAGE}-byte pages`)
+  })
+  for (let i = 0; i < index.length; i++) {
+    if (index[i] >= h.memPages) throw new CheckpointError('malformed', `page ${index[i]} is past the ${h.memPages} pages of memory`)
+    if (i && index[i] <= index[i - 1]) throw new CheckpointError('malformed', `the page list is not strictly increasing at entry ${i} (page ${index[i]} after ${index[i - 1]}): a duplicate or unordered page`)
+  }
+  let jit = null
+  if (h.jit) {
+    const recs = concat(get('jit-recs'))
+    const log = concat(get('jit-log'))
+    if (recs.length % 4) throw new CheckpointError('malformed', 'the JIT record section is not whole 32-bit cells')
+    jit = { gen: h.jit.gen, nslots: h.jit.nslots, slot0: h.jit.slot0, nrec: h.jit.nrec, recs: widenRecs(new Int32Array(recs.buffer.slice(recs.byteOffset, recs.byteOffset + recs.length)), h.jit.nrec), log }
+    try {
+      validateSnap(jit)
+    } catch (e) {
+      throw new CheckpointError('malformed', e.message)
+    }
+  }
+  const svc = {}
+  for (const port of h.svcPorts || []) svc[port] = concat(get(`svc-${port}`))
+  const ctlBytes = concat(get('ctl'))
+  return { header: h, index, memChunks, jit, svc, ctl: new Uint8Array(ctlBytes), names: parseNames(ck) }
+}
+
+// no leading zeros: "198.18.07.1" and "198.18.7.1" are one address, and the map keeps each address once
+const PLACEHOLDER = /^198\.1[89]\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]\d|\d)$/
+
+/** W59: the optional `net-names` section: [[name, ip]] with ip in 198.18.0.0/15, each name and ip once. */
+function parseNames(ck) {
+  const s = ck.sections.find(x => x.name === 'net-names')
+  if (!s) return []
+  let v
+  try {
+    v = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(concat(s.chunks)))
+  } catch (e) {
+    throw new CheckpointError('malformed', `the net-names section is not JSON: ${e.message}`)
+  }
+  if (!Array.isArray(v) || v.length > 65536) throw new CheckpointError('malformed', 'the net-names section is not a list of at most 65536 names')
+  const names = new Set()
+  const ips = new Set()
+  for (const e of v) {
+    if (!Array.isArray(e) || e.length !== 2 || typeof e[0] !== 'string' || !e[0] || e[0].length > 253 || typeof e[1] !== 'string' || !PLACEHOLDER.test(e[1])) {
+      throw new CheckpointError('malformed', `the net-names section has a bad entry: ${JSON.stringify(e)?.slice(0, 80)}`)
+    }
+    if (names.has(e[0]) || ips.has(e[1])) throw new CheckpointError('malformed', `the net-names section lists ${e[0]} or ${e[1]} twice`)
+    names.add(e[0])
+    ips.add(e[1])
+  }
+  return v
+}
+
+/** Throws a CheckpointError naming what differs, if `h` does not belong to this boot. */
+/** What differs between two boot descriptions (bootKeyOf's desc), for the message of a refused restore. */
+export function bootDescDiff(a, b) {
+  if (!a || !b) return ''
+  const out = []
+  const walk = (x, y, path) => {
+    if (JSON.stringify(x) === JSON.stringify(y)) return
+    if (x && y && typeof x === 'object' && typeof y === 'object') {
+      for (const k of new Set([...Object.keys(x), ...Object.keys(y)])) walk(x[k], y[k], `${path}.${k}`)
+    } else out.push(`${path}: ${JSON.stringify(x)?.slice(0, 60)} -> ${JSON.stringify(y)?.slice(0, 60)}`)
+  }
+  walk(a, b, 'boot')
+  return out.slice(0, 6).join('; ')
+}
+
+/** The part of the fit check that needs only vm.wasm's key: a snapshot from another vm.wasm is refused before anything else is read of it. */
+export function checkVmKeyFits(h, vmKey) {
+  if (h.format !== FORMAT_VERSION) throw new CheckpointError('version', `checkpoint format ${h.format}; this build restores format ${FORMAT_VERSION}`)
+  if (h.vmKey !== vmKey) {
+    throw new CheckpointError('stale', `this checkpoint was taken with a different vm.wasm (${String(h.vmKey).slice(0, 12)}, this boot has ${String(vmKey).slice(0, 12)}): its memory image is the old emulator's and cannot be restored; take a new one`)
+  }
+}
+
+export function checkCheckpointFits(h, { vmKey, bootKey, bootDesc, maxPages, hasJit, fmaFused = true }) {
+  if (h.format !== FORMAT_VERSION) throw new CheckpointError('version', `checkpoint format ${h.format}; this build restores format ${FORMAT_VERSION}`)
+  if (h.vmKey !== vmKey) {
+    throw new CheckpointError('stale', `this checkpoint was taken with a different vm.wasm (${String(h.vmKey).slice(0, 12)}, this boot has ${String(vmKey).slice(0, 12)}): its memory image is the old emulator's and cannot be restored; take a new one`)
+  }
+  if (h.bootKey !== bootKey) {
+    const diff = bootDescDiff(h.bootDesc, bootDesc)
+    throw new CheckpointError('stale', `this checkpoint was taken by a boot with a different kernel, initramfs, command line, environment, image layers or bundle files than this one; restore it only into the same configuration${diff ? ` (differs: ${diff})` : ''}`)
+  }
+  if (h.memPages > maxPages) throw new CheckpointError('stale', `this checkpoint's memory is ${h.memPages} pages and this boot's maximum is ${maxPages}`)
+  if (h.jit && !hasJit) throw new CheckpointError('stale', 'this checkpoint carries JIT state and this boot has the JIT door off (jit: false)')
+  if (!h.jit && hasJit) throw new CheckpointError('stale', 'this checkpoint was taken without the JIT door and this boot has it on')
+  // D-539: its JIT blocks may use relaxed_madd, which this engine does not fuse or parse
+  if (h.fmaFused && h.jit && !fmaFused) throw new CheckpointError('stale', "this checkpoint was taken in a browser whose wasm engine fuses relaxed_madd, and its compiled code uses it; this browser's engine does not (Safari): restore it in Chromium or Firefox, or take a new one here")
+}
+
+// ---------------------------------------------------------------------------
+// The stores
+// ---------------------------------------------------------------------------
+
+/** OPFS, through the I/O Worker. Methods return promises. */
+export function opfsStore({ workerUrl } = {}) {
+  let w = null
+  let next = 1
+  const pending = new Map()
+  let saveQueue = Promise.resolve() // saves run one at a time (the Worker refuses a second, and two would pick one version number)
+  const activeSaves = new Map() // save id -> checkpoint being streamed
+  const call = (msg, transfer = [], id = next++) => {
+    if (!w) {
+      // a literal URL when no workerUrl is given, so bundlers bundle the Worker (2.15)
+      w = workerUrl
+        ? new Worker(workerUrl, { type: 'module', name: 'wmd-ckpt-io' })
+        : new Worker(new URL('./ckpt-io.js', import.meta.url), { type: 'module', name: 'wmd-ckpt-io' })
+      w.onmessage = e => {
+        if (e.data.need) {
+          // the save is ready for a chunk: copy exactly that one (the in-memory checkpoint stays usable) and send it
+          const ck = activeSaves.get(e.data.saveId)
+          if (ck) answerNeed(ck, e.data, (m, t) => w.postMessage(m, t || [])) // a failed copy (out of memory) answers with an error, so the save fails
+          return
+        }
+        const p = pending.get(e.data.id)
+        if (!p) return
+        pending.delete(e.data.id)
+        if (e.data.ok) p.resolve(e.data)
+        else p.reject(new CheckpointError(e.data.code || 'io', e.data.error))
+      }
+      w.onerror = err => {
+        for (const p of pending.values()) p.reject(new CheckpointError('io', `the checkpoint I/O Worker failed: ${err.message || err}`))
+        pending.clear()
+      }
+    }
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject })
+      w.postMessage({ ...msg, id }, transfer)
+    })
+  }
+  return {
+    kind: 'opfs',
+    /**
+     * Writes a checkpoint. The Worker pulls it one chunk (at most 32 MiB) at a time, each copied on request so the
+     * in-memory checkpoint stays usable: the page never holds a second copy of the whole file, and the Worker holds at
+     * most one chunk. Saves are queued, one at a time. Resolves {bytes, ms, shaMs, version, leftover}.
+     */
+    save(name, ck) {
+      const run = saveQueue.catch(() => {}).then(async () => {
+        const id = next++
+        activeSaves.set(id, ck)
+        try {
+          const sections = ck.sections.map(s => ({ name: s.name, lens: s.chunks.map(c => c.length) }))
+          const r = await call({ op: 'save', name, header: ck.header, sections }, [], id)
+          return { bytes: r.bytes, ms: r.ms, shaMs: r.shaMs, version: r.version, leftover: r.leftover }
+        } finally {
+          activeSaves.delete(id)
+        }
+      })
+      saveQueue = run
+      return run
+    },
+    async info(name) {
+      const r = await call({ op: 'info', name })
+      return { header: r.header, size: r.size, version: r.version, skipped: r.skipped }
+    },
+    /** Reads and verifies a checkpoint into memory: {header, sections, ms}. */
+    async load(name, { verify = true } = {}) {
+      // one op: a save that lands between an info and a load could make them name different versions
+      const r = await call({ op: 'load', name, sections: null, verify })
+      return { header: r.header, sections: r.header.sections.map(s => ({ name: s.name, chunks: r.sections[s.name].map(b => new Uint8Array(b)) })), ms: r.ms, version: r.version, skipped: r.skipped }
+    },
+    async verify(name) {
+      return call({ op: 'verify', name })
+    },
+    async list() {
+      return (await call({ op: 'list' })).items
+    },
+    async delete(name) {
+      await call({ op: 'delete', name })
+    },
+    async usage() {
+      const r = await call({ op: 'usage' })
+      return { usage: r.usage, quota: r.quota }
+    },
+    /** Test hook: how many MB one OPFS file can take here before the browser refuses. */
+    async probe(maxMB = 1024) {
+      const r = await call({ op: 'probe', maxMB })
+      return { writtenMB: r.writtenMB, error: r.error }
+    },
+    /** Test hooks: damage a stored checkpoint (flip a byte; cut the file short). */
+    async poke(name, at, xor = 0xff) {
+      await call({ op: 'poke', name, at, xor })
+    },
+    async cut(name, size) {
+      await call({ op: 'cut', name, size })
+    },
+    close() {
+      w?.terminate()
+      w = null
+      // nothing will answer the calls still waiting for the Worker, or the save that was pulling chunks from it
+      for (const p of pending.values()) p.reject(new CheckpointError('io', 'the checkpoint store was closed'))
+      pending.clear()
+      activeSaves.clear()
+    },
+  }
+}
+
+/** The same interface over memory files (tests; a page without OPFS). */
+export function memoryStore() {
+  const files = new Map()
+  return {
+    kind: 'memory',
+    files,
+    async save(name, ck) {
+      const f = memoryFile()
+      const r = await writeCheckpoint(f, ck.header, ck.sections)
+      files.set(name, f)
+      return { bytes: r.bytes, ms: r.ms, shaMs: r.shaMs }
+    },
+    async info(name) {
+      const f = files.get(name)
+      if (!f) throw new CheckpointError('missing', `no checkpoint named ${JSON.stringify(name)}`)
+      return { header: readHeader(f), size: f.getSize() }
+    },
+    async load(name, { verify = true } = {}) {
+      const f = files.get(name)
+      if (!f) throw new CheckpointError('missing', `no checkpoint named ${JSON.stringify(name)}`)
+      const header = readHeader(f)
+      const sections = []
+      for (const s of header.sections) sections.push({ name: s.name, chunks: await readSection(f, header, s.name, { verify }) })
+      return { header, sections, ms: 0 }
+    },
+    async verify(name) {
+      await this.load(name, { verify: true })
+    },
+    async list() {
+      return [...files].map(([name, f]) => ({ name, size: f.getSize(), modified: 0 }))
+    },
+    async delete(name) {
+      if (!files.delete(name)) throw new CheckpointError('missing', `no checkpoint named ${JSON.stringify(name)}`)
+    },
+    async usage() {
+      return { usage: [...files.values()].reduce((n, f) => n + f.getSize(), 0), quota: Infinity }
+    },
+    close() {},
+  }
+}
+
+export { sectionBytes }