Repository navigation
Description
Summary
BrowserDb in IndexedDB mode (BrowserDb.open(name)) can store an inconsistent page set after an IndexedDB flush fails: a later successful flush can write a meta page that references pages that never reached IndexedDB. Split out of #441 (comment of 2026-10-07), with further findings from the planning of #441. Branch: v3 (read at 108b993). It is independent of the OPFS mode.
What happens
Each write is a synchronous save() into the in-memory page buffer, followed by an asynchronous IndexedDB transaction with the pages the save dirtied and the keys of the pages it freed.
- Dirty pages are lost on failure.
take_dirty_pages(src/browser/mod.rs:817) drains the buffer's dirty set before the pages are sent. Ifwrite_pagesrejects (quota exceeded, transaction aborted), the set is not restored, and the in-memory state has already activated the new meta. The next successful flush sends only its own dirty pages. - Page deletes are lost too.
take_flush(:853) releases the freed pages' bytes and builds the delete list before the write.BrowserBufferBackend::release(src/browser/buffer.rs:68) reports a page once, so a retry produces no delete for it. This matters most for animportGraph()of a smaller database. - Every write path is affected:
execute(apply_write,:478),BrowserWriteTransaction.commit()(:552),checkpoint()(:231),importGraph()(:325; it swaps the live store before the flush is awaited) and the migration flush inopen(:121). - Overlapping calls. The
RefCellborrow is released before each IndexedDB await, andcommit()clearstx_openbefore the flush. A later operation can compute its page delta before an earlier flush has failed, so restoring dirty ids after the error is not enough: the later flush can already be queued and succeed. - Some failures may never settle.
transaction_to_promise(src/browser/indexeddb.rs:38) listens forcompleteanderrorbut notabort. An abort need not fire a requesterrorevent (IndexedDB "abort a transaction"), so a commit-time abort can leave the promise pending.write_pages(:168) can also return early from a failedput/deletecall without aborting the transaction it has already queued requests on.
src/browser/tx_tests.rs:272 pins today's contract for a failed flush: the call rejects, the facts stay visible in memory, and a reopen shows the previous stored state. That test does not cover a later successful flush.
Expected
- After a failed flush, a later successful write or
checkpoint()stores the complete state it acknowledges: every page the stored meta references is in IndexedDB, and every freed page's key is deleted. A reopen matches that state. - A stale retry never overwrites a newer page or deletes a page id that has been reused.
- Overlapping calls are ordered or rejected; none resolves over missing predecessor pages.
- An aborted transaction rejects; a failed request cannot leave a partly committed flush.
- Whether a rejected write stays visible in memory is unchanged unless decided otherwise.
Tests wanted
Failed flush then success for execute, commit(), checkpoint() and a smaller-file importGraph(); repeated failures; page-id reuse between the failure and the retry; an overlapping call behind a failing flush; an abort-only failure settling. A recoverable abort is needed as well as the closed-connection case the existing test uses.
Notes
- The browser: BrowserDb.open() does not write migrated pages back to IndexedDB #411/BrowserDb: bound page growth via v8 free-list reuse; avoid v7→v8 migration bloat #440 design (
docs/superpowers/specs/2026-10-07-browser-page-reuse-design.md) deferred failed-flush recovery; the Expose explicit write transactions across all supported language bindings #824 design inherited the behaviour. - Does v2.x have it too? To be checked during triage (the v2.x browser path also drains the dirty set before the write).
Activity
adityamukho commentedon Nov 17, 2026
Confirmed end-to-end on v2.x by #896 (report, harness on branch
spike/896-idb-flush-repro).Affected (tested): v2.0.11 source, current main (
19fd080a6), and the published@minigraf/browser@2.0.11. By source only: the flush pattern (drain the dirty set, then awaitwrite_pages, with no restore on failure) has been inBrowserDbsince it was added in #149 (first released in v0.20.0). Releases before v2.0.11 were not run.QuotaExceededErrorcommit abort leaves the write's promise pending forever. A later write is acknowledged, and the database then fails to open with[INT-052] Page 6 not found. A rejected multi-page write followed by a successful write has the same effect.checkpoint()succeeds without retrying a failed flush; a rejected write or import stays visible in memory; a synchronousputthrow commits the puts already queued (synthetic); andClosure::onceon the transaction'sonerrorthrowsFnOnce called more than onceon every request-abort.Labelled
known-issueand added to #421. v3 behaviour still needs its own pinned-build run here.Merge pull request #903 from project-minigraf/fix/894-idb-flush-recovery
fix(browser): fail the IndexedDB handle after a failed flush and sett…
release: v2.0.12 (#907)
adityamukho commentedon Nov 18, 2026
Fixed in v2.0.12 (released 2026-11-18): backport PR #904, v3.0.0 fix PR #903. Release: https://github.com/project-minigraf/minigraf/releases/tag/v2.0.12. The entry moved to "Fixed in v2.0.12" in #421.