Add ADRs for cross-tab persistence reconciliation strategy#1836
Merged
Conversation
Record the two architectural decisions governing the fix for #1820: - IndexedDB (via localForage), not localStorage, for client-side persistence — Session and Schema payloads exceed localStorage's ~5MB limit, a constraint invisible in the code. - Per-key diff-merge reconciliation at the storage layer, scoped to durability only; same-entry conflicts and live cross-tab freshness are explicitly deferred. ADRs use the date-prefixed naming convention (#1835) and reference each other by slug.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Documentation only — records the two architectural decisions that gate the fix for the cross-tab clobber bug (#1820), before any code lands. No runtime changes.
Two ADRs under a new
docs/adr/:indexeddb-not-localstorage-for-persistence— persistence stays on IndexedDB (via localForage), not localStorage. Session and Schema payloads routinely exceed localStorage's ~5MB limit, a constraint invisible in the code that rules out the otherwise-obvious localStorage-based approaches.per-key-diff-merge-cross-tab-reconciliation— concurrent-tab writes reconcile at the storage layer via a per-key, diff-the-output merge. Records the rejected alternatives (replay-the-updater, BroadcastChannel/storage-event live sync, Web Locks) and the explicit scope boundary: durability only — same-entry conflicts stay last-writer-wins and live cross-tab freshness is deferred.Supporting: a core rule in
AGENTS.mdagainst hard-wrapping Markdown prose (the ADRs follow it).Validation
pnpm checkspasses (format/lint/types). No tests — documentation only. ADRs use the repo's date-prefixed naming convention (#1835) and reference each other by slug.How to read: start with the IndexedDB ADR (the constraint), then the reconciliation ADR (the strategy built on it).
Related Issues
Check List
pnpm checkspasses with no errors.pnpm testpasses with no failures.