@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/host/ckpt-file.js

@@ -0,0 +1,395 @@
+// P-B9: the checkpoint file (browser form of research/10 appendix B's WMDCKPT, which the desktop
+// writes; the two are not interchangeable: the desktop's carries hash vectors and artifact keys of
+// its JIT cache, this one carries what the browser host needs, so it has its own magic).
+//
+//   [0, 64 KiB)   header block: magic "WMDWCKP1" (written LAST: a file that never got that far
+//                 reads as "incomplete"), u32 version, u32 json length, the header JSON, then the SHA-256 of that
+//                 JSON (a flipped byte in the section table or in a count of the header is refused as corrupt)
+//   then, in the order of header.sections, each section's chunks back to back, 8-byte aligned
+//
+// header JSON: {format, createdAt, label, vmKey, bootKey, memPages, pageSize, guestHdr (base64),
+//   ports, sections: [{name, off, chunks: [{len, sha256}]}], fileLen, ...whatever the caller adds}
+//
+// Every chunk has its SHA-256 in the header; a reader that verifies compares all of them, so a
+// flipped byte anywhere is refused and the message names the section and the chunk.
+//
+// "handle" is a FileSystemSyncAccessHandle or anything with read(buf,{at}), write(buf,{at}),
+// getSize(), truncate(n), flush(), close() (the unit tests use a memory file).
+
+export const MAGIC = 'WMDWCKP1'
+export const FORMAT_VERSION = 2
+export const HEADER_SPACE = 64 * 1024
+const ALIGN = 8
+
+export class CheckpointError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.code = code // 'incomplete' | 'foreign' | 'version' | 'truncated' | 'corrupt' | 'malformed' | 'quota' | ...
+    // W24: a storage failure is told by its name, as the browser's own (DOMException QuotaExceededError)
+    if (code === 'quota') this.name = 'QuotaExceededError'
+  }
+}
+
+export async function sha256Hex(u8) {
+  const d = new Uint8Array(await crypto.subtle.digest('SHA-256', u8))
+  let s = ''
+  for (const b of d) s += b.toString(16).padStart(2, '0')
+  return s
+}
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const pad = n => (ALIGN - (n % ALIGN)) % ALIGN
+
+function writeAll(h, u8, at) {
+  let done = 0
+  while (done < u8.length) {
+    let n
+    try {
+      n = h.write(done ? u8.subarray(done) : u8, { at: at + done })
+    } catch (e) {
+      if (e && e.name === 'QuotaExceededError') throw e
+      // say how far it got: a browser's limit on one file or on its storage shows in the offset
+      throw new CheckpointError('io', `writing the checkpoint failed at byte ${at + done} (${e && e.name}: ${e && e.message})`)
+    }
+    if (!(n > 0)) throw new CheckpointError('truncated', `checkpoint write stopped at ${at + done} (storage full?)`)
+    done += n
+  }
+}
+
+function readExact(h, off, len) {
+  const out = new Uint8Array(len)
+  let got = 0
+  while (got < len) {
+    const n = h.read(got ? out.subarray(got) : out, { at: off + got })
+    if (!(n > 0)) break
+    got += n
+  }
+  if (got !== len) throw new CheckpointError('truncated', `checkpoint is cut short: wanted ${len} bytes at ${off}, the file has ${got}`)
+  return out
+}
+
+/**
+ * Writes sections ({name, chunks: Uint8Array[]}) and the header. Returns {bytes, headerJson, ms, sha}.
+ * `header` is the caller's fields; format, sections and fileLen are added here.
+ */
+export async function writeCheckpoint(h, header, sections, { now = () => performance.now() } = {}) {
+  const t0 = now()
+  h.truncate(0)
+  writeAll(h, new Uint8Array(HEADER_SPACE), 0) // zeros: no magic yet
+  let off = HEADER_SPACE
+  const table = []
+  let shaMs = 0
+  for (const s of sections) {
+    const entry = { name: s.name, off, chunks: [] }
+    for (const chunk of s.chunks) {
+      // a chunk is bytes, or a function (with .length set to its size) that returns them when asked: a save streams
+      // 32 MiB at a time instead of holding a copy of the whole checkpoint
+      const c = typeof chunk === 'function' ? await chunk() : chunk
+      const t1 = now()
+      const sha = await sha256Hex(c)
+      shaMs += now() - t1
+      writeAll(h, c, off)
+      entry.chunks.push({ len: c.length, sha256: sha })
+      off += c.length
+      const p = pad(off)
+      if (p) {
+        writeAll(h, new Uint8Array(p), off)
+        off += p
+      }
+    }
+    table.push(entry)
+  }
+  const full = { ...header, format: FORMAT_VERSION, sections: table, fileLen: off }
+  const hb = headerBlock(full)
+  writeAll(h, hb.subarray(8), 8) // version, length, json, its sha-256
+  h.flush()
+  writeAll(h, enc.encode(MAGIC), 0) // the commit
+  h.flush()
+  return { bytes: off, header: full, ms: now() - t0, shaMs }
+}
+
+const K256 = Uint32Array.from(
+  '428a2f98 71374491 b5c0fbcf e9b5dba5 3956c25b 59f111f1 923f82a4 ab1c5ed5 d807aa98 12835b01 243185be 550c7dc3 72be5d74 80deb1fe 9bdc06a7 c19bf174 e49b69c1 efbe4786 0fc19dc6 240ca1cc 2de92c6f 4a7484aa 5cb0a9dc 76f988da 983e5152 a831c66d b00327c8 bf597fc7 c6e00bf3 d5a79147 06ca6351 14292967 27b70a85 2e1b2138 4d2c6dfc 53380d13 650a7354 766a0abb 81c2c92e 92722c85 a2bfe8a1 a81a664b c24b8b70 c76c51a3 d192e819 d6990624 f40e3585 106aa070 19a4c116 1e376c08 2748774c 34b0bcb5 391c0cb3 4ed8aa4a 5b9cca4f 682e6ff3 748f82ee 78a5636f 84c87814 8cc70208 90befffa a4506ceb bef9a3f7 c67178f2'
+    .split(' ')
+    .map(x => parseInt(x, 16)),
+)
+
+/** SHA-256 of a small buffer, synchronously (the header is under 64 KiB; the chunks use SubtleCrypto). */
+export function sha256Sync(data) {
+  const H = Uint32Array.of(0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19)
+  const bits = data.length * 8
+  const padded = new Uint8Array(((data.length + 9 + 63) >> 6) << 6)
+  padded.set(data)
+  padded[data.length] = 0x80
+  const dv = new DataView(padded.buffer)
+  dv.setUint32(padded.length - 8, Math.floor(bits / 2 ** 32))
+  dv.setUint32(padded.length - 4, bits >>> 0)
+  const w = new Uint32Array(64)
+  const rotr = (x, n) => (x >>> n) | (x << (32 - n))
+  for (let o = 0; o < padded.length; o += 64) {
+    for (let i = 0; i < 16; i++) w[i] = dv.getUint32(o + i * 4)
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3)
+      const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10)
+      w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0
+    }
+    let [a, b, c, d, e, f, g, h] = H
+    for (let i = 0; i < 64; i++) {
+      const t1 = (h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K256[i] + w[i]) | 0
+      const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) | 0
+      h = g
+      g = f
+      f = e
+      e = (d + t1) | 0
+      d = c
+      c = b
+      b = a
+      a = (t1 + t2) | 0
+    }
+    H[0] += a
+    H[1] += b
+    H[2] += c
+    H[3] += d
+    H[4] += e
+    H[5] += f
+    H[6] += g
+    H[7] += h
+  }
+  const out = new Uint8Array(32)
+  const odv = new DataView(out.buffer)
+  H.forEach((x, i) => odv.setUint32(i * 4, x))
+  return out
+}
+
+/** The header block's bytes after the magic's place: [8) version, [12) json length, [16) json, then its SHA-256 (32 bytes). */
+export function headerBlock(full) {
+  const json = enc.encode(JSON.stringify(full))
+  if (json.length + 32 > HEADER_SPACE - 16) throw new CheckpointError('malformed', `checkpoint header is ${json.length} bytes; the limit is ${HEADER_SPACE - 48}`)
+  const sha = sha256Sync(json)
+  const hb = new Uint8Array(16 + json.length + 32)
+  new DataView(hb.buffer).setUint32(8, FORMAT_VERSION, true)
+  new DataView(hb.buffer).setUint32(12, json.length, true)
+  hb.set(json, 16)
+  hb.set(sha, 16 + json.length)
+  return hb
+}
+
+/** The validated header of a checkpoint file. */
+export function readHeader(h) {
+  const size = h.getSize()
+  if (size < 16) throw new CheckpointError('incomplete', `not a checkpoint: the file is ${size} bytes`)
+  const top = readExact(h, 0, 16)
+  const magic = dec.decode(top.subarray(0, 8))
+  if (magic !== MAGIC) {
+    if (top.subarray(0, 8).every(b => b === 0)) throw new CheckpointError('incomplete', 'the checkpoint was never finished (its write did not complete: the page closed or the storage filled while it was written)')
+    throw new CheckpointError('foreign', `not a wmd-web checkpoint (magic ${JSON.stringify(magic.replace(/[^\x20-\x7e]/g, '?'))})`)
+  }
+  const dv = new DataView(top.buffer)
+  const version = dv.getUint32(8, true)
+  if (version !== FORMAT_VERSION) throw new CheckpointError('version', `checkpoint format ${version}; this build reads format ${FORMAT_VERSION}`)
+  const n = dv.getUint32(12, true)
+  if (n > HEADER_SPACE - 16) throw new CheckpointError('malformed', `checkpoint header length ${n} is not possible`)
+  let header
+  try {
+    const jsonBytes = readExact(h, 16, n)
+    const want = readExact(h, 16 + n, 32)
+    const got = sha256Sync(jsonBytes)
+    if (want.some((b, i) => b !== got[i])) throw new CheckpointError('corrupt', 'the checkpoint header does not match its SHA-256 (the section table or a count in it is damaged)')
+    header = JSON.parse(dec.decode(jsonBytes))
+  } catch (e) {
+    if (e instanceof CheckpointError) throw e
+    throw new CheckpointError('malformed', `checkpoint header is not JSON: ${e.message}`)
+  }
+  if (header.format !== FORMAT_VERSION || !Array.isArray(header.sections) || typeof header.fileLen !== 'number') {
+    throw new CheckpointError('malformed', 'checkpoint header is missing its section table')
+  }
+  if (size < header.fileLen) throw new CheckpointError('truncated', `checkpoint is cut short: ${size} bytes of ${header.fileLen}`)
+  for (const s of header.sections) {
+    let end = s.off
+    for (const c of s.chunks) end += c.len
+    if (s.off < HEADER_SPACE || end > header.fileLen) throw new CheckpointError('malformed', `section ${s.name} lies outside the file`)
+  }
+  return header
+}
+
+/** One section's chunks as Uint8Arrays (each its own buffer), verified against their digests unless verify is false. */
+export async function readSection(h, header, name, { verify = true } = {}) {
+  const s = header.sections.find(x => x.name === name)
+  if (!s) throw new CheckpointError('malformed', `checkpoint has no section ${name}`)
+  const out = []
+  let off = s.off
+  for (let i = 0; i < s.chunks.length; i++) {
+    const c = s.chunks[i]
+    const b = readExact(h, off, c.len)
+    if (verify) {
+      const got = await sha256Hex(b)
+      if (got !== c.sha256) throw new CheckpointError('corrupt', `checkpoint section ${name}, chunk ${i} (bytes ${off}..${off + c.len}) does not match its SHA-256: the file is damaged`)
+    }
+    out.push(b)
+    off += c.len + pad(off + c.len)
+  }
+  return out
+}
+
+export const sectionBytes = (header, name) => header.sections.find(s => s.name === name)?.chunks.reduce((n, c) => n + c.len, 0) ?? 0
+
+/** Concatenates chunks (for small sections). */
+export function concat(chunks) {
+  if (chunks.length === 1) return chunks[0]
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0))
+  let p = 0
+  for (const c of chunks) {
+    out.set(c, p)
+    p += c.length
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Versioned files: a save never touches the checkpoint it replaces
+// ---------------------------------------------------------------------------
+//
+// <name>~<n>.ckpt, n counting up (a file named <name>.ckpt, from an earlier build, is version 0). A save writes version
+// max+1 and removes the older ones only once the new file is complete; if the write fails (storage quota, a closed page
+// leaves a file with no magic) the partial file is removed and the previous version is still the one a load finds. This
+// needs no rename, which the browsers do not all offer for OPFS files in a Worker.
+// "dir" is {names(): Promise<string[]>, open(file, create): Promise<handle>, remove(file): Promise, free?(): Promise<number|null>}.
+
+const FILE_RE = /^(.+?)(?:~(\d+))?\.ckpt$/
+export const versionsOf = (names, name) =>
+  names
+    .map(n => FILE_RE.exec(n))
+    .filter(m => m && m[1] === name)
+    .map(m => Number(m[2] ?? 0))
+    .sort((a, b) => a - b)
+export const fileOf = (name, v) => (v ? `${name}~${v}.ckpt` : `${name}.ckpt`)
+export const baseNames = names => [...new Set(names.map(n => FILE_RE.exec(n)).filter(Boolean).map(m => m[1]))]
+
+const isQuota = e => e && (e.name === 'QuotaExceededError' || e.code === 22 || /quota/i.test(String(e.message)))
+
+const saveChains = new Map() // dir.key (or the dir object) -> the save in progress: saves to one directory run one at a time
+
+/** An OPFS handle a tab or operation holds exclusively (createSyncAccessHandle, removeEntry) is "in use". */
+const isBusy = e => e && e.name === 'NoModificationAllowedError'
+const busyError = (what, e) => new CheckpointError('busy', `${what} is in use by another tab or operation (${e.name}); try again when it is done. (Coordination between tabs is not done: a second tab saving the same name fails this way.)`)
+
+/**
+ * Writes `name` as a new version; resolves with writeCheckpoint's result plus {version, removed, leftover}. Saves to one
+ * directory (one `dir.key`, or one dir object) run one after the other, in this module (two at once would both pick the next
+ * version number); across callers it is the Worker's `saving` guard (ckpt-save.js) that refuses a second save. `leftover` lists older versions that
+ * could not be removed (in use by a reader): the next save removes them.
+ */
+export function saveVersioned(dir, name, header, sections, o = {}) {
+  const key = dir.key ?? dir // opfsDir() makes a new object per call: it names its directory in `key`
+  const prev = saveChains.get(key) || Promise.resolve()
+  const run = prev.catch(() => {}).then(() => saveVersionedNow(dir, name, header, sections, o))
+  const tail = run.catch(() => {})
+  saveChains.set(key, tail)
+  tail.then(() => saveChains.get(key) === tail && saveChains.delete(key))
+  return run
+}
+
+async function saveVersionedNow(dir, name, header, sections, o) {
+  const versions = versionsOf(await dir.names(), name)
+  const next = (versions.at(-1) ?? 0) + 1
+  const file = fileOf(name, next)
+  const need = HEADER_SPACE + sections.reduce((n, s) => n + s.chunks.reduce((m, c) => m + (typeof c === 'function' ? c.size : c.length) + ALIGN, 0), 0)
+  const mb = n => `${Math.round(n / 1048576)} MB`
+  const keep = versions.length ? `; the previous checkpoint ${JSON.stringify(name)} is unchanged and still usable` : ''
+  const free = dir.free ? await dir.free() : null
+  if (free !== null && free !== undefined && need > free) {
+    throw new CheckpointError('quota', `not enough browser storage for this checkpoint: it needs ${mb(need)} and ${mb(Math.max(0, free))} is free${keep}. Delete a checkpoint or free space, and try again`)
+  }
+  let h = null
+  try {
+    h = await dir.open(file, true)
+    const r = await writeCheckpoint(h, header, sections, o)
+    h.close()
+    h = null
+    const leftover = []
+    for (const v of versions) {
+      try {
+        await dir.remove(fileOf(name, v))
+      } catch (e) {
+        leftover.push(fileOf(name, v)) // a reader has it open: not lost, removed by the next save
+      }
+    }
+    return { ...r, version: next, removed: versions.length - leftover.length, leftover }
+  } catch (e) {
+    try {
+      h?.close()
+    } catch {}
+    await dir.remove(file).catch(() => {}) // no half-written checkpoint is left behind
+    if (isBusy(e)) throw busyError(`the checkpoint file ${file}`, e)
+    if (isQuota(e) || (e instanceof CheckpointError && e.code === 'truncated' && /storage full/.test(e.message))) {
+      throw new CheckpointError('quota', `the browser ran out of storage writing this checkpoint (${mb(need)} needed): the partial file was removed${keep}`)
+    }
+    throw e
+  }
+}
+
+/**
+ * Calls fn(handle, version, note) on the newest version of `name` whose header is valid, closing the handle after.
+ * note: {skipped: [{version, code, message}]} - newer versions passed over (never finished, cut short) and why; the
+ * caller reports it, so a load that used an older checkpoint than the newest file says so.
+ */
+export async function withNewest(dir, name, fn) {
+  const versions = versionsOf(await dir.names(), name)
+  if (!versions.length) throw new CheckpointError('missing', `no checkpoint named ${JSON.stringify(name)} in this browser's storage`)
+  const skipped = []
+  for (const v of versions.reverse()) {
+    let h
+    try {
+      h = await dir.open(fileOf(name, v), false)
+    } catch (e) {
+      if (isBusy(e)) throw busyError(`the checkpoint file ${fileOf(name, v)}`, e)
+      throw e
+    }
+    try {
+      readHeader(h) // a newer file that never finished (the page closed mid-write) is skipped for the one before it
+      return await fn(h, v, { skipped })
+    } catch (e) {
+      if (!(e instanceof CheckpointError) || !['incomplete', 'truncated'].includes(e.code)) throw e
+      skipped.push({ version: v, code: e.code, message: e.message })
+    } finally {
+      h.close()
+    }
+  }
+  throw new CheckpointError(skipped.at(-1).code, `${skipped.at(-1).message} (every version of ${JSON.stringify(name)} was tried: ${skipped.map(x => `~${x.version} ${x.code}`).join(', ')})`)
+}
+
+/** A file in memory with the sync handle's shape (tests, and a store without OPFS). */
+export function memoryFile(initial = new Uint8Array(0)) {
+  let buf = initial
+  let size = initial.length
+  return {
+    getSize: () => size,
+    truncate(n) {
+      if (n > buf.length) {
+        const nb = new Uint8Array(Math.max(n, buf.length * 2))
+        nb.set(buf.subarray(0, size))
+        buf = nb
+      } else buf.fill(0, n, size)
+      size = n
+    },
+    write(src, { at }) {
+      if (at + src.length > buf.length) {
+        const nb = new Uint8Array(Math.max(at + src.length, buf.length * 2))
+        nb.set(buf.subarray(0, size))
+        buf = nb
+      }
+      buf.set(src, at)
+      size = Math.max(size, at + src.length)
+      return src.length
+    },
+    read(dst, { at }) {
+      const n = Math.max(0, Math.min(dst.length, size - at))
+      dst.set(buf.subarray(at, at + n))
+      return n
+    },
+    flush() {},
+    close() {},
+    bytes: () => buf.subarray(0, size),
+  }
+}

package/src/host/ckpt-io.js

@@ -0,0 +1,207 @@
+// P-B9: the checkpoint store's Worker: OPFS files through FileSystemSyncAccessHandle (the one
+// OPFS API that all three browsers give a Worker). One file per checkpoint in the directory
+// `wmd-ckpt` of the origin's private file system: <id>.ckpt.
+//
+// in:  {id, op:'save', name, header, sections:[{name, lens:[n]}]}   -> {ok, bytes, ms, shaMs, version, leftover}
+//        The bytes are pulled, one chunk at a time: when the save is ready for chunk (si, ci) the Worker posts
+//        {need:true, saveId:id, si, ci}; the page answers {op:'chunk', saveId, si, ci, buf}. At most one chunk (32 MiB)
+//        waits here, and a chunk is dropped as soon as it is written. One save at a time (a second is refused: busy).
+//      {id, op:'info', name}                       -> {ok, header}            (header only: fast, no digests)
+//      {id, op:'load', name, sections:[names] | null (all), verify}  -> {ok, header, sections:{name:[ArrayBuffer]}, ms}
+//      {id, op:'verify', name}                     -> {ok, header, ms}        (every digest)
+//      {id, op:'list'}                             -> {ok, items:[{name, size, modified}]}
+//      {id, op:'delete', name}                     -> {ok}
+//      {id, op:'usage'}                            -> {ok, usage, quota}
+//      {id, op:'poke', name, at, xor} / {id, op:'cut', name, size}   test hooks: damage a file
+// out: {id, ok:false, code, error} on failure (code: CheckpointError.code, or 'io').
+import { createSaver } from './ckpt-save.js'
+import { CheckpointError, baseNames, fileOf, readHeader, readSection, saveVersioned, versionsOf, withNewest } from './ckpt-file.js'
+
+const DIR = 'wmd-ckpt'
+const now = () => performance.now()
+
+async function dir() {
+  const root = await navigator.storage.getDirectory()
+  return root.getDirectoryHandle(DIR, { create: true })
+}
+
+const checkName = name => {
+  if (!/^[A-Za-z0-9._-]{1,80}$/.test(name) || name.startsWith('.')) throw new CheckpointError('malformed', `checkpoint name ${JSON.stringify(name)}: use letters, digits, . _ - (at most 80)`)
+  return name
+}
+
+/** The directory the versioned save works on (ckpt-file.js saveVersioned), over OPFS. */
+async function opfsDir() {
+  const d = await dir()
+  return {
+    key: `opfs:${DIR}`, // saveVersioned serializes saves per key (a fresh object per call would defeat a per-object chain)
+    async names() {
+      const out = []
+      for await (const [n] of d.entries()) out.push(n)
+      return out
+    },
+    async open(file, create) {
+      try {
+        return await (await d.getFileHandle(file, { create })).createSyncAccessHandle()
+      } catch (e) {
+        if (e.name === 'NotFoundError') throw new CheckpointError('missing', `no such checkpoint file ${file}`)
+        throw e
+      }
+    },
+    remove: file => d.removeEntry(file),
+    async free() {
+      const e = await navigator.storage.estimate()
+      return typeof e.quota === 'number' && typeof e.usage === 'number' ? e.quota - e.usage : null
+    },
+  }
+}
+
+/** The newest version's file without validating it (the test hooks damage and repair files). */
+async function rawNewest(name, fn) {
+  const d = await opfsDir()
+  const v = versionsOf(await d.names(), checkName(name)).at(-1)
+  if (v === undefined) throw new CheckpointError('missing', `no checkpoint named ${JSON.stringify(name)} in this browser's storage`)
+  const h = await d.open(fileOf(name, v), false)
+  try {
+    return await fn(h)
+  } finally {
+    h.close()
+  }
+}
+
+const withHandle = async (name, fn) => withNewest(await opfsDir(), checkName(name), fn)
+
+async function handle(m) {
+  switch (m.op) {
+    case 'save': {
+      // the chunks are pulled one at a time (startSave): the save asks for each when it is ready for it
+      try {
+        const r = await saveVersioned(await opfsDir(), checkName(m.name), m.header, m._sections, {})
+        return { bytes: r.bytes, ms: r.ms, shaMs: r.shaMs, version: r.version, leftover: r.leftover }
+      } finally {
+        saver.done() // success or failure, so the next save can start
+      }
+    }
+    case 'info':
+      return withHandle(m.name, async (h, version, note) => ({ header: readHeader(h), size: h.getSize(), version, skipped: note.skipped }))
+    case 'load':
+      return withHandle(m.name, async (h, version, note) => {
+        const t0 = now()
+        const header = readHeader(h)
+        const out = {}
+        const transfer = []
+        for (const name of m.sections || header.sections.map(x => x.name)) {
+          out[name] = (await readSection(h, header, name, { verify: m.verify !== false })).map(u => u.buffer)
+          for (const b of out[name]) transfer.push(b)
+        }
+        return { header, sections: out, ms: now() - t0, transfer, version, skipped: note.skipped }
+      })
+    case 'verify':
+      return withHandle(m.name, async h => {
+        const t0 = now()
+        const header = readHeader(h)
+        for (const s of header.sections) await readSection(h, header, s.name, { verify: true })
+        return { header, ms: now() - t0 }
+      })
+    case 'list': {
+      const d = await dir()
+      const names = []
+      const files = new Map()
+      for await (const [n, fh] of d.entries()) {
+        names.push(n)
+        files.set(n, fh)
+      }
+      const items = []
+      for (const base of baseNames(names)) {
+        const v = versionsOf(names, base).at(-1)
+        const f = await files.get(fileOf(base, v)).getFile()
+        items.push({ name: base, size: f.size, modified: f.lastModified })
+      }
+      return { items }
+    }
+    case 'delete': {
+      const d = await dir()
+      const names = []
+      for await (const [n] of d.entries()) names.push(n)
+      const vs = versionsOf(names, checkName(m.name))
+      if (!vs.length) throw new CheckpointError('missing', `no checkpoint named ${JSON.stringify(m.name)} in this browser's storage`)
+      for (const v of vs) await d.removeEntry(fileOf(m.name, v))
+      return {}
+    }
+    case 'poke': // test hook: XOR one byte of a checkpoint file (damage it)
+      return rawNewest(m.name, async h => {
+        const b = new Uint8Array(1)
+        h.read(b, { at: m.at })
+        b[0] ^= m.xor || 0xff
+        h.write(b, { at: m.at })
+        h.flush()
+        return {}
+      })
+    case 'cut': // test hook: truncate a checkpoint file to `size` bytes
+      return rawNewest(m.name, async h => {
+        h.truncate(m.size)
+        h.flush()
+        return {}
+      })
+    case 'probe': {
+      // test hook: how much one OPFS file takes in this browser, in 16 MiB writes, until it refuses (at most m.maxMB);
+      // an error says at which step (getDirectory, getFileHandle, createSyncAccessHandle, write)
+      let step = 'getDirectory'
+      let h = null
+      let d = null
+      let written = 0
+      let err = null
+      try {
+        d = await dir()
+        step = 'getFileHandle'
+        const fh = await d.getFileHandle('probe.tmp', { create: true })
+        step = 'createSyncAccessHandle'
+        h = await fh.createSyncAccessHandle()
+        step = 'write'
+        const block = new Uint8Array(16 << 20).fill(7)
+        while (written < (m.maxMB || 1024) * (1 << 20)) {
+          const n = h.write(block, { at: written })
+          if (!(n > 0)) {
+            err = `write returned ${n}`
+            break
+          }
+          written += n
+        }
+        step = 'flush'
+        h.flush()
+      } catch (e) {
+        err = `${e && e.name}: ${e && e.message}`
+      }
+      try {
+        h?.close()
+        await d?.removeEntry('probe.tmp')
+      } catch {}
+      return { writtenMB: Math.round(written / (1 << 20)), error: err && `${err} (at ${step})` }
+    }
+    case 'usage': {
+      const e = await navigator.storage.estimate()
+      return { usage: e.usage, quota: e.quota }
+    }
+    default:
+      throw new Error(`ckpt-io: unknown op ${m.op}`)
+  }
+}
+
+const saver = createSaver(msg => self.postMessage(msg))
+
+self.onmessage = async e => {
+  const m = e.data
+  if (m.op === 'chunk') {
+    saver.chunk(m)
+    return
+  }
+  try {
+    if (m.op === 'save') m._sections = saver.start(m) // before anything is awaited: the page answers the first request at once
+    const r = await handle(m)
+    const transfer = r.transfer || []
+    delete r.transfer
+    self.postMessage({ id: m.id, ok: true, ...r }, transfer)
+  } catch (err) {
+    self.postMessage({ id: m.id, ok: false, code: err instanceof CheckpointError ? err.code : 'io', error: err && err.message ? `${err.name}: ${err.message}` : String(err) })
+  }
+}