Skip to content

feat(browser): OPFS-backed BrowserDb mode and close() (#441) - #899

Merged
adityamukho merged 22 commits into
v3from
feat/441-browser-opfs
Nov 17, 2026
Merged

adityamukho merged 22 commits into
v3from
feat/441-browser-opfs

Conversation

@adityamukho

@adityamukho adityamukho commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Adds BrowserDb.openOpfs(name), a second persistent browser mode. The database is one <name>.graph file in the Origin Private File System, read and written in place through a FileSystemSyncAccessHandle in a dedicated worker. Memory holds only the 256-page cache, and there is no WAL. Refs #441.

What changes

  • OPFS backend (src/browser/opfs.rs, backend.rs):
    • Exact page offsets; a short read or write is an error, never a partial page.
    • Browser failures surface as STG-048 with the operation and the exception name.
    • The handle is the lock: a second open is STG-026 until close() or the worker ends.
  • Recovery without a WAL (PersistentFactStorage::open_wal_less): an OPFS file with exactly one valid meta slot opens at that slot, so a tab killed mid-commit reopens instead of refusing. Native opens are unchanged and still return STG-033 for the same bytes.
  • Exports (write_image): free pages and the inactive meta slot are zeroed, so an export always opens natively with no WAL beside it.
  • Crash-atomic import:
    • The image is checked in memory first (meta, length, verify(); v7 is migrated).
    • It is staged in <name>.graph-import with its meta written last; that meta is the publication point. It is then copied into the database file, meta last.
    • The staged image gets an odd generation above every old meta, so a finished copy is never redone over later commits.
    • An interruption at any point reopens as the whole old or the whole new database. Cursors and prepared queries from before the import fail with API-018.
  • close() in every mode: synchronous and idempotent; saves nothing. Afterwards every method of the database and its dependents is API-018, except disposal. It is refused with API-027 while an import runs, or when called from a user function during a query.
  • IndexedDB mode now works in workers.
  • New error codes: API-026 (OPFS not available here), API-027 (database busy), STG-048 (browser storage operation failed).
  • Tests and CI: the lib's browser tests also build for a dedicated worker (--cfg minigraf_browser_worker). There, the mode-independent tests run against OPFS. wasm.yml adds Firefox and Chrome worker jobs.
  • Docs: CHANGELOG, README, ROADMAP (BrowserDb: OPFS-backed persistent mode (sync access handle, no in-memory buffer) #441 moves to v3.0.0), PHILOSOPHY, DURABILITY, ERROR_REFERENCE, TEST_COVERAGE, CLAUDE.md. The approved design is in docs/superpowers/specs/2026-11-14-441-browser-opfs-design.md; the measurements are in docs/benchmarks/441-opfs/.

No format change and no new crate; only web-sys features are added. A wasm build with atomics fails to compile, because the JS handle is not Send/Sync there.

Verification

  • cargo test: 2,149 passed, 0 failed, 23 ignored.
  • fmt, --all-targets clippy, and the browser and WASI clippies pass.
  • Firefox, local:
    • Main thread: 81 passed.
    • Dedicated worker: 114 passed.
  • Packaged consumer tests (minigraf-wasm), Chromium and Firefox: 54 checks pass. They cover worker termination during a stream of commits (a gap-free prefix that includes every acknowledged commit), the lock across workers, and import interruption.
  • Memory: opening a 42 MB database uses the same wasm memory high-water as opening a 4 MB one, 1,245,184 B on both Chromium and Firefox. IndexedDB mode uses 43 MB.
  • Package .wasm: 1,754,394 B → 1,822,855 B (+68,461, +3.9%), built with Rust 1.94, release, wasm-opt off.
  • Native dist binary: 1,269,568 B on Rust 1.99.1, within the 1,250 KiB gate.

CI: Chrome, Firefox and Safari (macOS, via safaridriver) run the core suites on the main thread (81) and in a dedicated worker (114); the minigraf-wasm package test runs on Chromium, Firefox and macOS WebKit. Safari reports a held handle as InvalidStateError, mapped to STG-026 alongside NoModificationAllowedError. Safari private-window OPFS is not tested (WebDriver cannot open one); WebKit documents OPFS as unavailable there. Companion PRs: minigraf-wasm (pins this branch's head) and minigraf-docs. Merge this one first.

🤖 Generated with Claude Code

https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9

adityamukho and others added 14 commits November 14, 2026 14:12
BrowserDb.openOpfs(name) keeps the database as one <name>.graph file in
the Origin Private File System, read and written in place through a
FileSystemSyncAccessHandle in a dedicated worker: a 256-page cache, no
in-memory copy of the pages, no WAL. An OPFS database with exactly one
valid meta slot opens at it (native opens keep STG-033), since there is
no WAL to tell an interrupted commit from rot and no repair tool in the
browser. Imports stage the new image in <name>.graph-import and publish
it by its meta page, so an interruption leaves the old or the new
database whole. close() exists in every mode; IndexedDB mode opens in
workers. New codes API-026, API-027, STG-048.

Refs #441

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9
…ively (#441)

The lib's browser tests also build for a dedicated worker
(--cfg minigraf_browser_worker), where the mode-independent ones run
against OPFS and the OPFS tests cover the lock, close(), failed commits,
open outcomes, imports interrupted at every write and flush, and the
read and cache bounds. Native fault-injection tests check that a
WAL-less open after a crash at any point of a commit gives the previous
state or the new one, and that its export opens with Minigraf::open.
Portability fixtures tie a native v8 file and an OPFS export to one set
of answers.

Refs #441

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9
Document the OPFS error codes alongside the registry and retain main-thread browser coverage.

Refs #441

Co-Authored-By: GPT-6 <noreply@openai.com>
Add reproducible bounded-memory probes and distinguish outstanding browser measurements from completed native and WASI checks.

Refs #441

Co-Authored-By: GPT-6 <noreply@openai.com>
Publish matching-profile wasm sizes, the native size gate, coverage results and a bounded-memory harness with a validated worker route.

Refs #441

Co-Authored-By: GPT-6 <noreply@openai.com>
Record successful packaged consumer runs on Chromium and Firefox, bounded-memory results for 4 MiB and 40 MiB databases, and observed private browsing behavior. Identify the missing WebKit engine and Chrome driver mismatch explicitly.

Refs #441

Co-Authored-By: GPT-6 <noreply@openai.com>
… exports (#441)

Reject nonempty images without a selectable meta before open-time recovery can initialize them. Enforce the supplied page count before migration or image emission, and fill only absent meta slots during export. Include native creation-interruption regressions and a full v7 portability fixture.

Refs #441

Co-Authored-By: Codex (GPT-6.1-sol) <noreply@openai.com>
Exercise rejected import admission, creation exports, all close outcomes, real API errors, v7 portability and staging failures in Firefox workers. Sweep repeated recovery-copy interruptions and retain browser lock and dependent assertions at each outcome. Allow the worker job time for the complete boundary matrix.

Refs #441

Co-Authored-By: Codex (GPT-6.1-sol) <noreply@openai.com>
Use a checked first-page view during import admission so the browser strict lint gate also verifies the new validation path.

Refs #441

Co-Authored-By: Codex (GPT-6.1-sol) <noreply@openai.com>
Document the exact database and staging entry mapping, strict nonempty import admission and complete recovered exports. Record the expanded lifecycle and fault coverage, current native and browser counts, unchanged healthy-read memory measurement and the remaining WebKit limitation.

Refs #441

Co-Authored-By: Codex (GPT-6.1-sol) <noreply@openai.com>
Start every recovery-copy interruption case from an actual published import whose main-file copy failed. Keep its earlier cursor and prepared query alive and assert their closed outcomes, lock exclusion and successful staging cleanup across the retry.

Refs #441

Co-Authored-By: Codex (GPT-6.1-sol) <noreply@openai.com>
Distinguish the 4322 Clippy diagnostics from 23 unchanged compiler diagnostics in the complete base comparison. Neither category adds a diagnostic on the feature branch.

Refs #441

Co-Authored-By: Codex (GPT-6.1-sol) <noreply@openai.com>
…441)

Keep shared storage error classification for foreign imports while refusing nonempty initial images that open would repair. Cover error parity and preserved destination state, clarify supported import images, and restrict OPFS test helpers to their worker build.

Refs #441

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 94.27793% with 21 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/storage/persistent_facts.rs 94.23% 19 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

adityamukho and others added 8 commits November 17, 2026 15:17
Playwright's Linux WebKit has no OPFS in workers, so WebKit OPFS had no
automated run. Add main-thread and worker lanes in real Safari via
safaridriver, and record that Safari private browsing is not tested.

Refs #441

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9
Refs #441

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9
The test runner's own launch timed out on the hosted runner.

Refs #441

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9
Safari throws InvalidStateError, not NoModificationAllowedError, when a sync
access handle is already open on the file, so a second open was STG-048
instead of STG-026.

Refs #441

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2a7QjCHpikfsg5qwAV1p9
@adityamukho
adityamukho merged commit df7e817 into v3 Nov 17, 2026
28 checks passed
@adityamukho
adityamukho deleted the feat/441-browser-opfs branch November 17, 2026 13:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant