Browser Storage and IndexedDB

Pathrule3 Rules • 2 Memories

Browser storage is durable enough to become product state but not durable enough to be a database of record: users clear it, quotas vary, private modes differ, transactions abort, tabs race, and old application versions can open the same origin data. This pattern constrains sensitive data and transaction ownership while recording schema migration, cache authority, quota, and cross-tab decisions. It complements client-state management by focusing on persistence and multi-context lifecycle; state libraries decide how UI state changes, while this pattern decides what can survive browser and application restarts.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

storage/

Keep IndexedDB transactions synchronous in ownership

Do not persist reusable secrets in script-readable storage

Schema upgrades are short structural transitions

Browser persistence is a rebuildable cache unless the product says otherwise

offline/

Give cross-tab work a lease and idempotent identity

Rules

Keep IndexedDB transactions synchronous in ownership/src/storagehighstrictCreate requests and dependent writes within the active transaction and move unrelated asynchronous work before or after it.

1	IndexedDB transactions can become inactive when control returns without a pending request. Awaiting network calls, timers, or unrelated promises inside a transaction can make later writes fail after partial application logic.
2
3	- Load remote data and perform expensive computation before opening the transaction, then revalidate local assumptions once the transaction begins.
4	- Create all reads and writes that form one invariant from the same transaction and wait for its completion event before reporting durable local success.
5	- Abort on validation or write failure and treat transaction abort as a first-class result, not an exception to suppress.
6	- Keep transaction scope to the required object stores and duration so one tab does not block upgrades or unrelated local work longer than necessary.
7
8	See /src/offline for the adjacent decision or procedure that completes this constraint.

Do not persist reusable secrets in script-readable storage/src/storagehighstrictKeep bearer credentials and private key material out of localStorage, sessionStorage, IndexedDB, and general cache entries.

1	All script-readable origin storage is available to code executing in that origin, including compromised dependencies and injected scripts. Obfuscation or a key stored beside ciphertext does not create a meaningful boundary.
2
3	- Use protected cookie or platform credential mechanisms for reusable session secrets when the architecture supports them.
4	- Persist only the minimum offline data the product contract permits, and classify personal or sensitive fields before writing them.
5	- Delete user-scoped databases, caches, queues, and cross-tab state on sign-out or account removal according to the privacy contract.
6	- Do not log stored records during migration or corruption recovery; diagnostics should use schema versions, keys, counts, and non-sensitive error codes.
7
8	See /tests/storage for the adjacent decision or procedure that completes this constraint.

Give cross-tab work a lease and idempotent identity/src/offlinehighstrictCoordinate queue ownership and mutation replay so two tabs cannot perform the same logical operation concurrently.

1	Each tab has its own JavaScript runtime but shares origin storage. Storage events or broadcast messages notify peers; they do not provide durable mutual exclusion or exactly-once execution.
2
3	- Give every queued operation a stable idempotency key that the server also understands.
4	- Acquire a time-bounded lease or use a single worker owner for replay, and renew only while the owner is alive and making progress.
5	- Recheck operation state before external submission and before final local commit because another tab may have completed it after the first read.
6	- Broadcast state changes for responsiveness but recover truth from storage after missed messages, suspended tabs, or browser restart.
7
8	See /src/storage for the adjacent decision or procedure that completes this constraint.

Memories

Schema upgrades are short structural transitions/src/storageKeep version-change handlers synchronous and bounded, then perform large data backfills as resumable application work.

1	An IndexedDB upgrade blocks other connections and can be blocked by old tabs that keep the prior version open. Long record-by-record work inside the version-change transaction creates startup stalls and fragile recovery.
2
3	- Use the version-change transaction for creating, deleting, or renaming stores and indexes and for only the bounded data changes required for structural validity.
4	- Prompt or coordinate old tabs to close when an upgrade is blocked, and provide a usable recovery path rather than waiting forever.
5	- Record a separate data-migration cursor and process large transformations in resumable batches after the database opens.
6	- Test upgrade from every supported stored version and preserve a reset or export path when corrupted legacy data cannot be migrated safely.
7
8	See /tests/storage for the rule or workflow that puts this decision into practice.

Browser persistence is a rebuildable cache unless the product says otherwise/src/storageDefine the server or user export as authority and design reset, quota, and eviction behavior before relying on local data.

1	Browsers can evict data, users can clear it, and storage availability differs across contexts. If local data is the only copy, that is a product-level durability promise requiring backup and user communication, not an implementation shortcut.
2
3	- Classify each store as cache, draft, queued command, downloaded content, or local-only user data and assign recovery behavior.
4	- Estimate usage and handle quota errors without deleting unrelated stores or looping on the same failed write.
5	- For rebuildable caches, version the cache key and allow a full reset from authoritative data.
6	- For local-only user content, provide export, backup, and explicit deletion semantics and test them before claiming offline durability.
7
8	See /src/offline for the rule or workflow that puts this decision into practice.

Why this pattern

AI agents often store secrets in local storage, perform asynchronous work that lets an IndexedDB transaction close, rewrite all data during upgrade, or let two tabs race the same queue.

Built for Frontend teams persisting offline data, drafts, caches, queues, or large client-side records.

Keeps your assistant from:

Persisting bearer secrets where injected scripts can read them
Losing writes because a transaction became inactive
Blocking application startup on an unsafe migration
Processing the same local operation from multiple tabs

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25