@threadedstack/wmd-web 0.1.17 → 0.1.19

package/src/host/disk-map.js

@@ -0,0 +1,330 @@
+// A thin disk in two OPFS files (docs/plans/web-buildkit-impl.md 5.9).
+//
+// vm.wasm's virtio-blk device (guest/vm/src/dev/blk.c) reads and writes a disk of a fixed size through
+// wmd.blk_rw. Firefox charges a file's whole length against the quota even where nothing was written, so
+// the disk is not one file of its size. The guest's disk is cut into 64 KiB extents; the data file holds
+// only the extents the guest wrote, packed into slots, and the map file says which slot holds which
+// extent:
+//
+//   map file   header (64 bytes): 'WMDDISK1', u32 version, u32 extent shift, f64 disk bytes, u32 crc32
+//              of bytes 0..23; then one 8-byte record per extent: u32 slot+1 (0: never written or
+//              discarded, reads as zeros), u32 crc32 of (extent index, slot+1)
+//   data file  slot s at s * 64 KiB
+//
+// Order (a disk write cache; the guest's flush is the commit): a write puts its data in the data file and
+// updates the in-memory map only; the map records of the writes and discards since the last flush are written
+// at the flush: flush the data file, write the records, flush the map file, then shrink the data file past
+// the last live slot. A crash before a flush loses the writes since the last flush, as a disk's write cache
+// does. A record whose crc does not match (torn by a crash) is dropped on open, so its extent reads as zeros.
+// Because no record names a slot before the data in it is durable, a slot freed by a discard can be taken
+// by another extent at once: a stale record can only point at bytes written for another extent that was
+// itself discarded. ENOSPC comes only when every slot is held by a live extent.
+//
+// A handle is an OPFS FileSystemSyncAccessHandle or anything with the same read/write/getSize/truncate/
+// flush (the unit tests pass a fake).
+
+export class DiskError extends Error {
+  constructor(message, reason) {
+    super(message)
+    this.name = 'DiskError'
+    this.reason = reason // 'locked' | 'quota' | 'open' | 'corrupt' | 'timeout'
+  }
+}
+
+export const EXT_SHIFT = 16
+export const EXT = 1 << EXT_SHIFT
+export const MAP_HEADER = 64
+const REC = 8
+const MAGIC = 'WMDDISK1'
+const VERSION = 1
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c >>> 0
+  }
+  return t
+})()
+
+export function crc32(bytes, crc = 0) {
+  let c = ~crc >>> 0
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8)
+  return ~c >>> 0
+}
+
+function recCrc(index, slot1) {
+  const b = new Uint8Array(8)
+  const v = new DataView(b.buffer)
+  v.setUint32(0, index, true)
+  v.setUint32(4, slot1, true)
+  return crc32(b)
+}
+
+const ENOSPC = -28
+const EIO = -5
+const EINVAL = -22
+
+/**
+ * True when createSyncAccessHandle failed because another holder has the file open: Chromium and Firefox throw
+ * NoModificationAllowedError, WebKit throws InvalidStateError.
+ */
+export function heldElsewhere(err) {
+  return err?.name === 'NoModificationAllowedError' || err?.name === 'InvalidStateError'
+}
+
+/** The errno a failed OPFS call stands for: ENOSPC when the quota ran out, else EIO. */
+export function errnoOf(err) {
+  return err?.name === 'QuotaExceededError' ? ENOSPC : EIO
+}
+
+export class DiskMap {
+  /**
+   * Opens the disk in `data` and `map`, or makes a new one of `bytes` (a multiple of 64 KiB) when the data
+   * file is empty and the map has no valid header. A bad header over a non-empty data file throws DiskError
+   * 'corrupt' (the data is not wiped). An existing disk keeps the size it was made with; `bytes` is then ignored.
+   * @returns {DiskMap} with .created and .dropped (records dropped for a bad crc or a slot claimed twice)
+   */
+  static open(data, map, bytes) {
+    const d = new DiskMap(data, map)
+    const hdr = new Uint8Array(MAP_HEADER)
+    const got = map.getSize() >= MAP_HEADER ? map.read(hdr, { at: 0 }) : 0
+    const hv = new DataView(hdr.buffer)
+    const valid =
+      got === MAP_HEADER &&
+      new TextDecoder().decode(hdr.subarray(0, 8)) === MAGIC &&
+      hv.getUint32(8, true) === VERSION &&
+      hv.getUint32(12, true) === EXT_SHIFT &&
+      hv.getUint32(24, true) === crc32(hdr.subarray(0, 24))
+    if (valid) d.#load(hv.getFloat64(16, true))
+    else if (data.getSize() > 0) throw new DiskError("the disk's map is damaged (bad header over existing data); delete the disk with deleteDisk to start over", 'corrupt')
+    else d.#create(bytes)
+    return d
+  }
+
+  constructor(data, map) {
+    this.data = data
+    this.map = map
+    this.created = false
+    this.dropped = 0
+    this.dirty = new Set() // extents whose record changed since the last flush
+  }
+
+  #create(bytes) {
+    if (!(bytes > 0) || bytes % EXT) throw new RangeError(`disk size ${bytes} is not a positive multiple of ${EXT}`)
+    this.bytes = bytes
+    this.n = bytes / EXT
+    this.slots = new Uint32Array(this.n) // extent -> slot+1
+    this.used = new Uint8Array(this.n) // slot -> 1 when a live extent holds it
+    this.lowFree = 0
+    this.top = 0 // slots in the data file
+    this.data.truncate(0)
+    this.map.truncate(0)
+    this.map.truncate(MAP_HEADER + this.n * REC) // zeros: every extent unwritten
+    const hdr = new Uint8Array(MAP_HEADER)
+    hdr.set(new TextEncoder().encode(MAGIC))
+    const hv = new DataView(hdr.buffer)
+    hv.setUint32(8, VERSION, true)
+    hv.setUint32(12, EXT_SHIFT, true)
+    hv.setFloat64(16, bytes, true)
+    hv.setUint32(24, crc32(hdr.subarray(0, 24)), true)
+    this.map.write(hdr, { at: 0 })
+    this.map.flush()
+    this.data.flush()
+    this.created = true
+  }
+
+  #load(bytes) {
+    this.bytes = bytes
+    this.n = Math.floor(bytes / EXT)
+    this.slots = new Uint32Array(this.n)
+    this.used = new Uint8Array(this.n)
+    const recs = new Uint8Array(this.n * REC)
+    const got = this.map.read(recs, { at: MAP_HEADER })
+    const rv = new DataView(recs.buffer)
+    const fix = []
+    for (let i = 0; i < this.n; i++) {
+      if ((i + 1) * REC > got) break
+      const slot1 = rv.getUint32(i * REC, true)
+      if (slot1 === 0) continue
+      const ok = rv.getUint32(i * REC + 4, true) === recCrc(i, slot1) && slot1 <= this.n && !this.used[slot1 - 1]
+      if (!ok) {
+        this.dropped++
+        fix.push(i)
+        continue
+      }
+      this.slots[i] = slot1
+      this.used[slot1 - 1] = 1
+    }
+    for (const i of fix) this.#writeRec(i, 0)
+    if (fix.length) this.map.flush()
+    this.lowFree = 0
+    this.top = 0
+    for (let s = this.n - 1; s >= 0; s--)
+      if (this.used[s]) {
+        this.top = s + 1
+        break
+      }
+    this.#shrink()
+  }
+
+  #writeRec(i, slot1) {
+    const b = new Uint8Array(REC)
+    const v = new DataView(b.buffer)
+    v.setUint32(0, slot1, true)
+    v.setUint32(4, slot1 ? recCrc(i, slot1) : 0, true)
+    if (this.map.write(b, { at: MAP_HEADER + i * REC }) !== REC) throw Object.assign(new Error('short map write'), { errno: ENOSPC })
+  }
+
+  #release(s) {
+    this.used[s] = 0
+    if (s < this.lowFree) this.lowFree = s
+    while (this.top > 0 && !this.used[this.top - 1]) this.top--
+  }
+
+  #alloc() {
+    let s = this.lowFree
+    while (s < this.n && this.used[s]) s++
+    if (s >= this.n) throw Object.assign(new Error('no free slot'), { errno: ENOSPC }) // cannot happen: n slots for n extents
+    this.used[s] = 1
+    this.lowFree = s + 1
+    if (s + 1 > this.top) this.top = s + 1
+    return s
+  }
+
+  #check(off, len) {
+    return Number.isInteger(off) && off >= 0 && len >= 0 && off + len <= this.bytes
+  }
+
+  /** The disk's [off, off+len) into buf. 0 or a negative errno. */
+  read(off, buf) {
+    if (!this.#check(off, buf.length)) return EINVAL
+    try {
+      for (let done = 0; done < buf.length; ) {
+        const pos = off + done
+        const i = Math.floor(pos / EXT)
+        const within = pos - i * EXT
+        const n = Math.min(EXT - within, buf.length - done)
+        const part = buf.subarray(done, done + n)
+        const slot1 = this.slots[i]
+        if (!slot1) part.fill(0)
+        else {
+          const got = this.data.read(part, { at: (slot1 - 1) * EXT + within })
+          if (got < n) part.fill(0, got)
+        }
+        done += n
+      }
+      return 0
+    } catch (e) {
+      return e.errno || errnoOf(e)
+    }
+  }
+
+  /** buf onto the disk at off. 0 or a negative errno. */
+  write(off, buf) {
+    if (!this.#check(off, buf.length)) return EINVAL
+    try {
+      for (let done = 0; done < buf.length; ) {
+        const pos = off + done
+        const i = Math.floor(pos / EXT)
+        const within = pos - i * EXT
+        const n = Math.min(EXT - within, buf.length - done)
+        const part = buf.subarray(done, done + n)
+        let slot1 = this.slots[i]
+        if (slot1) {
+          if (this.data.write(part, { at: (slot1 - 1) * EXT + within }) !== n) return ENOSPC
+        } else {
+          const s = this.#alloc()
+          // a new slot may hold an old extent's bytes: write the whole extent, zeros around the data
+          let whole = part
+          if (n !== EXT) {
+            whole = new Uint8Array(EXT)
+            whole.set(part, within)
+          }
+          let wrote
+          try {
+            wrote = this.data.write(whole, { at: s * EXT })
+          } catch (e) {
+            wrote = e
+          }
+          if (wrote !== EXT) {
+            this.#release(s)
+            return typeof wrote === 'number' ? ENOSPC : wrote.errno || errnoOf(wrote)
+          }
+          this.slots[i] = s + 1
+          this.dirty.add(i)
+        }
+        done += n
+      }
+      return 0
+    } catch (e) {
+      return e.errno || errnoOf(e)
+    }
+  }
+
+  /** Forgets every whole extent in [off, off+len); parts of extents are left as they are. */
+  discard(off, len) {
+    if (!this.#check(off, len)) return EINVAL
+    try {
+      const first = Math.ceil(off / EXT)
+      const end = Math.floor((off + len) / EXT)
+      for (let i = first; i < end; i++) {
+        const slot1 = this.slots[i]
+        if (!slot1) continue
+        this.slots[i] = 0
+        this.dirty.add(i)
+        this.used[slot1 - 1] = 0 // reusable at once: its record is rewritten at the flush
+        if (slot1 - 1 < this.lowFree) this.lowFree = slot1 - 1
+      }
+      return 0
+    } catch (e) {
+      return e.errno || errnoOf(e)
+    }
+  }
+
+  /** Makes every earlier write durable: the data file, then the map records, then the map file; then shrinks. */
+  flush() {
+    try {
+      this.data.flush()
+      const idx = [...this.dirty].sort((a, b) => a - b)
+      for (let k = 0; k < idx.length; ) {
+        let e = k + 1
+        while (e < idx.length && idx[e] === idx[e - 1] + 1) e++
+        this.#writeRecs(idx[k], idx.slice(k, e))
+        k = e
+      }
+      this.map.flush()
+      this.dirty.clear()
+      this.#shrink()
+      return 0
+    } catch (e) {
+      return e.errno || errnoOf(e) // the dirty set stays: the next flush retries
+    }
+  }
+
+  #writeRecs(first, list) {
+    const b = new Uint8Array(list.length * REC)
+    const v = new DataView(b.buffer)
+    list.forEach((i, k) => {
+      const slot1 = this.slots[i]
+      v.setUint32(k * REC, slot1, true)
+      v.setUint32(k * REC + 4, slot1 ? recCrc(i, slot1) : 0, true)
+    })
+    if (this.map.write(b, { at: MAP_HEADER + first * REC }) !== b.length) throw Object.assign(new Error('short map write'), { errno: ENOSPC })
+  }
+
+  #shrink() {
+    let top = this.top
+    while (top > 0 && !this.used[top - 1]) top--
+    this.top = top
+    if (this.data.getSize() > top * EXT) this.data.truncate(top * EXT)
+  }
+
+  /** Bytes the data file holds and the extents mapped. */
+  usage() {
+    let mapped = 0
+    for (let i = 0; i < this.n; i++) if (this.slots[i]) mapped++
+    return { bytes: this.bytes, fileBytes: this.data.getSize(), mapped, slots: this.top }
+  }
+}

package/src/host/disk-worker.js

@@ -0,0 +1,125 @@
+// The disk Worker (disk.js): owns one disk's two OPFS files through sync access handles and serves the
+// vCPUs' wmd.blk_rw requests from the mailbox. After 'ready' it runs a loop with no event loop, so the page
+// talks to it only through the mailbox (control word i32[5]).
+
+import { DiskMap, errnoOf, heldElsewhere } from './disk-map.js'
+import { DATA, HEADER, OP, STATE } from './disk.js'
+
+const MiB = 2 ** 20
+
+self.onmessage = async e => {
+  if (e.data?.t !== 'open') return
+  const { mailbox, name, bytes: asked, minBytes } = e.data
+  const i32 = new Int32Array(mailbox, 0, 8)
+  const fail = (reason, message) => {
+    Atomics.store(i32, 1, STATE.GONE)
+    Atomics.notify(i32, 1)
+    self.postMessage({ t: 'fail', reason, message })
+  }
+  let data
+  let map
+  let disk
+  let est = null
+  let smaller = false
+  try {
+    const root = await navigator.storage.getDirectory()
+    est = await navigator.storage.estimate().catch(() => null)
+    const handle = async n => (await root.getFileHandle(n, { create: true })).createSyncAccessHandle()
+    try {
+      data = await handle(`${name}.disk`)
+      map = await handle(`${name}.map`)
+    } catch (err) {
+      data?.close()
+      return fail(heldElsewhere(err) ? 'locked' : 'open', `${name}: ${err?.name || ''} ${err?.message || err}`)
+    }
+    let bytes = asked
+    const fresh = map.getSize() === 0
+    if (fresh && est?.quota) {
+      // the origin's free room: its quota less its usage, plus what this disk's own files already count; a tenth kept back
+      const room = Math.floor(((est.quota - (est.usage || 0) + data.getSize() + map.getSize()) * 0.9) / MiB) * MiB
+      if (room < bytes) {
+        bytes = room
+        smaller = true
+      }
+      if (room < minBytes) {
+        data.close()
+        map.close()
+        return fail('quota', `${name}: the origin has room for ${Math.round(room / MiB)} MiB, less than ${Math.round(minBytes / MiB)} MiB`)
+      }
+    }
+    disk = DiskMap.open(data, map, bytes)
+  } catch (err) {
+    data?.close()
+    map?.close()
+    return fail(err?.reason === 'corrupt' ? 'corrupt' : errnoOf(err) === -28 ? 'quota' : 'open', `${name}: ${err?.name || ''} ${err?.message || err}`)
+  }
+  const persisted = await navigator.storage.persisted?.().catch(() => null)
+  self.postMessage({ t: 'ready', bytes: disk.bytes, created: disk.created, dropped: disk.dropped, est, persisted, smaller })
+  serve(mailbox, disk, () => {
+    data.close()
+    map.close()
+  })
+}
+
+function serve(mailbox, disk, closeFiles) {
+  const i32 = new Int32Array(mailbox, 0, 8)
+  const f64 = new Float64Array(mailbox, 0, 8)
+  const data = new Uint8Array(mailbox, HEADER, DATA)
+  const tmp = new Uint8Array(DATA) // sync access handles take no views of shared memory
+  const stats = { reads: 0, writes: 0, flushes: 0, discards: 0, readBytes: 0, writeBytes: 0, ms: 0 }
+  let quotaSaid = false
+  let ops = 0
+  const post = () => self.postMessage({ t: 'stats', stats: { ...stats, ...disk.usage() } })
+  for (;;) {
+    if (Atomics.load(i32, 5) === 1) break
+    const s = Atomics.load(i32, 1)
+    if (s === STATE.GONE) break
+    if (s !== STATE.POSTED) {
+      Atomics.wait(i32, 1, s, 250)
+      continue
+    }
+    const t = performance.now()
+    const op = Atomics.load(i32, 2)
+    const len = Atomics.load(i32, 3) >>> 0
+    const off = f64[3]
+    let r
+    if (op === OP.READ) {
+      r = disk.read(off, tmp.subarray(0, len))
+      if (r === 0) data.set(tmp.subarray(0, len))
+      stats.reads++
+      stats.readBytes += len
+    } else if (op === OP.WRITE) {
+      tmp.set(data.subarray(0, len))
+      r = disk.write(off, tmp.subarray(0, len))
+      stats.writes++
+      stats.writeBytes += len
+    } else if (op === OP.FLUSH) {
+      r = disk.flush()
+      stats.flushes++
+    } else if (op === OP.DISCARD) {
+      r = disk.discard(off, len)
+      stats.discards++
+    } else r = -22
+    if (r === -28 && !quotaSaid) {
+      quotaSaid = true
+      self.postMessage({ t: 'error', reason: 'quota', message: `the origin's storage quota ran out writing ${len} bytes at ${off}` })
+    } else if (r !== 0 && r !== -28) self.postMessage({ t: 'error', reason: 'io', message: `op ${op} at ${off} len ${len}: ${r}` })
+    stats.ms += performance.now() - t
+    Atomics.store(i32, 4, r)
+    // a vCPU that gave up marked the disk gone; leave that mark
+    if (Atomics.compareExchange(i32, 1, STATE.POSTED, STATE.DONE) === STATE.POSTED) Atomics.notify(i32, 1)
+    if (++ops % 4096 === 0 || op === OP.FLUSH) post()
+  }
+  try {
+    disk.flush()
+    post()
+  } finally {
+    try {
+      closeFiles()
+    } finally {
+      Atomics.store(i32, 1, STATE.GONE)
+      Atomics.notify(i32, 1)
+      self.postMessage({ t: 'closed' }) // the page waits for this: the handles are closed
+    }
+  }
+}

package/src/host/disk.js

@@ -0,0 +1,219 @@
+// A disk for the guest, kept in the origin private file system (docs/plans/web-buildkit-impl.md 5.9).
+//
+// vm.wasm's virtio-blk device (guest/vm/src/dev/blk.c) calls wmd.blk_rw(op, off, ptr, len) on the vCPU
+// that kicked the queue, with ptr in memory 0 (RAM outside memory 0 is bounced through memory 0). An OPFS
+// sync access handle belongs to one Worker, so one disk Worker (disk-worker.js) owns the disk's files
+// (disk-map.js) and the vCPU Workers reach it through a mailbox in a SharedArrayBuffer:
+//
+//   i32[0] lock     0 free, 1 held. vm.wasm already serialises requests (notify_lock, virtio.c); this guards
+//   i32[1] state    0 idle, 1 request posted, 2 done, 3 the disk is gone (every request: EIO)
+//   i32[2] op       0 read, 1 write, 2 flush, 3 discard (blk.c's BLK_OP_*)
+//   i32[3] len      bytes (u32)
+//   i32[4] result   0 or a negative errno
+//   i32[5] control  1: the page asks the Worker to flush and close
+//   f64[3] off      byte offset (bytes 24..31)
+//   data from byte 64, DATA bytes; longer reads and writes go in pieces
+//
+// A vCPU that waits WAIT_MS for an answer marks the disk gone and returns EIO, so a Worker that died or
+// hangs gives the guest an I/O error, never a stuck vCPU.
+
+import { DiskError } from './disk-map.js'
+
+export const HEADER = 64
+export const DATA = 4 << 20
+export const WAIT_MS = 30_000
+export const OP = { READ: 0, WRITE: 1, FLUSH: 2, DISCARD: 3 }
+export const STATE = { IDLE: 0, POSTED: 1, DONE: 2, GONE: 3 }
+const EIO = -5
+
+export function createDiskMailbox() {
+  return new SharedArrayBuffer(HEADER + DATA)
+}
+
+/** The vCPU side: wmd.blk_rw over the mailbox. `now` is for tests. */
+export function createDiskImports({ memory, mailbox, waitMs = WAIT_MS, now = () => performance.now() }) {
+  const i32 = new Int32Array(mailbox, 0, 8)
+  const f64 = new Float64Array(mailbox, 0, 8)
+  const data = new Uint8Array(mailbox, HEADER, DATA)
+  const gone = () => Atomics.load(i32, 1) === STATE.GONE
+  const lock = () => {
+    const end = now() + waitMs
+    while (Atomics.compareExchange(i32, 0, 0, 1) !== 0) {
+      if (gone()) return false
+      if (now() > end) {
+        Atomics.store(i32, 1, STATE.GONE)
+        return false
+      }
+      Atomics.wait(i32, 0, 1, 50)
+    }
+    return true
+  }
+  const unlock = () => {
+    Atomics.store(i32, 0, 0)
+    Atomics.notify(i32, 0, 1)
+  }
+  const one = (op, off, len, mem) => {
+    if (op === OP.WRITE) data.set(mem)
+    Atomics.store(i32, 2, op)
+    Atomics.store(i32, 3, len)
+    f64[3] = off
+    if (Atomics.compareExchange(i32, 1, STATE.IDLE, STATE.POSTED) !== STATE.IDLE) return EIO
+    Atomics.notify(i32, 1, 1)
+    const end = now() + waitMs
+    for (;;) {
+      const s = Atomics.load(i32, 1)
+      if (s === STATE.DONE) break
+      if (s === STATE.GONE) return EIO
+      if (now() > end) {
+        // the Worker never answered: the disk is gone for good, so a late answer cannot be mistaken for the next one's;
+        // but an answer that landed just before the deadline counts (the swap says which came first)
+        if (Atomics.compareExchange(i32, 1, STATE.POSTED, STATE.GONE) === STATE.DONE) break
+        Atomics.notify(i32, 1)
+        return EIO
+      }
+      Atomics.wait(i32, 1, STATE.POSTED, 1000)
+    }
+    const r = Atomics.load(i32, 4)
+    if (op === OP.READ && r === 0) mem.set(data.subarray(0, len))
+    Atomics.compareExchange(i32, 1, STATE.DONE, STATE.IDLE)
+    return r
+  }
+  return {
+    blk_rw(op, off, ptr, len) {
+      ptr >>>= 0 // an i32 from wasm; memory 0 can pass 2 GiB
+      len >>>= 0
+      const base = Number(off)
+      if ((op === OP.READ || op === OP.WRITE) && ptr + len > memory.buffer.byteLength) return -14 // EFAULT, never a throw into wasm
+      if (gone() || !lock()) return EIO
+      try {
+        if (op === OP.FLUSH || op === OP.DISCARD) return one(op, base, len, null)
+        if (op !== OP.READ && op !== OP.WRITE) return -22
+        for (let done = 0; done < len; ) {
+          const n = Math.min(DATA, len - done)
+          const r = one(op, base + done, n, new Uint8Array(memory.buffer, ptr + done, n))
+          if (r !== 0) return r
+          done += n
+        }
+        return 0
+      } finally {
+        unlock()
+      }
+    },
+  }
+}
+
+export { DiskError }
+
+/** A valid disk name: letters, digits, '-', '_' and '.', at most 128, not starting with '.'. */
+export function checkDiskName(name) {
+  if (typeof name !== 'string' || !/^[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}$/.test(name)) throw new TypeError(`bad disk name: ${JSON.stringify(name)}`)
+  return name
+}
+
+/**
+ * Opens (or makes) the disk `name` in OPFS: files `<name>.disk` and `<name>.map`. A new disk gets `mib`
+ * MiB, made smaller when the origin's quota has no room for it; an existing one keeps its size.
+ * @returns {Promise<{mailbox, name, bytes, mib, created, dropped, est, persisted, events: object[],
+ *   onEvent: Function|null, stats: object|null, close(): Promise<void>}>}
+ * Rejects with DiskError: reason 'locked' when another tab has it open, 'quota' when there is no room
+ * for even `minMib`, 'corrupt' when the map is damaged, 'timeout' when the worker never answers, 'open' otherwise.
+ */
+export async function openDisk({ name, mib, minMib = 1024, onEvent = null, openTimeoutMs = 30_000, workerUrl = new URL('./disk-worker.js', import.meta.url) }) {
+  checkDiskName(name)
+  const mailbox = createDiskMailbox()
+  const w = new Worker(workerUrl, { type: 'module', name: `wmd-disk-${name}` })
+  const disk = { mailbox, name, events: [], onEvent, stats: null, worker: w, closed: null }
+  const emit = ev => {
+    disk.events.push(ev)
+    if (disk.events.length > 200) disk.events.shift()
+    try {
+      disk.onEvent?.(ev)
+    } catch {}
+  }
+  let closedRes
+  disk.closed = new Promise(r => (closedRes = r))
+  await new Promise((res, rej) => {
+    const timer = setTimeout(() => {
+      Atomics.store(new Int32Array(mailbox, 0, 8), 1, STATE.GONE)
+      w.terminate()
+      rej(new DiskError(`${name}: the disk worker did not answer in ${Math.round(openTimeoutMs / 1000)} s`, 'timeout'))
+    }, openTimeoutMs)
+    const rej0 = rej
+    const res0 = res
+    rej = e => (clearTimeout(timer), rej0(e))
+    res = () => (clearTimeout(timer), res0())
+    w.onmessage = e => {
+      const m = e.data
+      if (m.t === 'ready') {
+        Object.assign(disk, { bytes: m.bytes, mib: m.bytes / 2 ** 20, created: m.created, dropped: m.dropped, est: m.est, persisted: m.persisted })
+        if (m.smaller) emit({ t: 'disk', reason: 'quota', mib: disk.mib, asked: mib })
+        res()
+      } else if (m.t === 'fail') {
+        w.terminate()
+        rej(new DiskError(m.message, m.reason))
+      } else if (m.t === 'stats') disk.stats = m.stats
+      else if (m.t === 'error') emit({ t: 'disk', reason: m.reason || 'error', message: m.message })
+      else if (m.t === 'closed') closedRes()
+    }
+    w.onerror = e => {
+      Atomics.store(new Int32Array(mailbox, 0, 8), 1, STATE.GONE)
+      rej(new DiskError(`disk worker: ${e.message}`, 'open'))
+      emit({ t: 'disk', reason: 'error', message: `disk worker: ${e.message}` })
+    }
+    w.postMessage({ t: 'open', mailbox, name, bytes: Math.floor(mib) * 2 ** 20, minBytes: minMib * 2 ** 20 })
+  })
+  disk.close = async ({ timeoutMs = 5_000 } = {}) => {
+    const i32 = new Int32Array(mailbox, 0, 8)
+    Atomics.store(i32, 5, 1)
+    Atomics.notify(i32, 1)
+    await Promise.race([disk.closed, new Promise(r => setTimeout(r, timeoutMs))])
+    Atomics.store(i32, 1, STATE.GONE)
+    w.terminate()
+  }
+  return disk
+}
+
+/** Deletes the disk `name` (both files). False when it is open somewhere (locked) or absent. */
+export async function deleteDisk(name, { root } = {}) {
+  checkDiskName(name)
+  root ||= await navigator.storage.getDirectory()
+  // Lock both files first (a writable stream is refused while a worker holds the file's sync access handle,
+  // and works on the page's thread), release, then remove: if either is held, remove neither.
+  const files = []
+  const locks = []
+  try {
+    for (const f of [`${name}.disk`, `${name}.map`]) {
+      let fh
+      try {
+        fh = await root.getFileHandle(f)
+      } catch (e) {
+        if (e?.name === 'NotFoundError') continue // a lone file left behind is still removable
+        throw e
+      }
+      locks.push(await fh.createWritable())
+      files.push(f)
+    }
+  } catch {
+    files.length = 0
+  }
+  for (const l of locks) await l.abort().catch(() => {})
+  if (!files.length) return false
+  let ok = true
+  for (const f of files)
+    try {
+      await root.removeEntry(f)
+    } catch {
+      ok = false
+    }
+  return ok
+}
+
+/** Deletes every disk whose name starts with `prefix` and that no tab holds open. Returns the names deleted. */
+export async function sweepDisks(prefix, { root } = {}) {
+  root ||= await navigator.storage.getDirectory()
+  const names = new Set()
+  for await (const [n] of root.entries()) if (n.startsWith(prefix) && /\.(disk|map)$/.test(n)) names.add(n.replace(/\.(disk|map)$/, ''))
+  const gone = []
+  for (const n of names) if (await deleteDisk(n, { root })) gone.push(n)
+  return gone
+}