ADR 0004: Memory-first VFS with write-behind OPFS persistence

  • Status: accepted (2026-10-21), based on phase2-probes.md
  • Context: An OPFS operation costs 145–375 µs, while an in-memory syscall costs about 10 µs. npm install and module loading issue tens of thousands of syscalls, so OPFS on the syscall path would make the runtime 10–30× slower.
  • Decision: Syscalls always hit the in-memory MemoryVfs. Persistent instances (fs.persist: true) write behind to the instance origin’s OPFS:
    • Layout: content-addressed blobs (blobs/<sha256>) plus one checkpoint (the inode table, referencing blobs by hash) plus HEAD.
    • Flush: debounced 250 ms after the first change. It writes new blobs, then the checkpoint, then HEAD, then garbage-collects. A crash at any point leaves HEAD on a complete generation (unit-tested by crashing at every write).
    • Hashes are cached per buffer, so a flush hashes and writes only data that changed.
    • Checkpoints are encoded in parts, and the flush yields to the event loop between them, so syscalls keep being serviced.
    • Boot loads the checkpoint and all blobs eagerly.
    • A Web Lock gives one tab exclusive ownership of an instance’s store.
  • Measured (5,000 files, ~15 MB):
    • Full flush: ~780 ms. Restore boot: ~270 ms.
    • During a flush, NOOP syscalls stay at p50 11.5 µs and p99 159 µs (batch means), with a worst single call of ~1.9 ms.
    • A dedicated persistence worker is therefore not justified yet.
  • Consequences:
    • Writes after the last flush can be lost on crash or tab close. Instance.flush() and destroy() are the durability points; pagehide triggers a best-effort flush.
    • Memory use equals the instance’s filesystem size, bounded by quotaBytes.
    • A journal (incremental checkpoints) and lazy blob loading are possible later optimizations. They would cut flush cost for very large trees.

Edit this page on GitHub ↗Markdown