Browser Persistence

Requirement Browser storage MUST be reached only through an Infrastructure adapter implementing an Application-declared interface.

Rationale No Domain type, component, or page touches storage, so a test substitutes an in-memory implementation of the same interface.

Requirement A storage key MUST use the form {product}.{area}.v{n} and be declared once as a constant beside its adapter.

Rationale The version segment increments when the stored shape changes incompatibly. A raw string literal elsewhere in the code is a second, unversioned declaration.

Example shop.cart.v1 names its product, its area, and its shape version.

Requirement A change to a persisted shape MUST ship a migration that reads every previously released version and produces the current one.

Rationale The migration runs at startup before the store finishes loading. Data it cannot interpret is preserved under a quarantine key and reported. Deleting unreadable user data is not a recovery.

Requirement A storage adapter MUST return a typed result covering unavailable, absent, corrupt, and present.

Rationale Storage can be full, disabled, or partitioned by the browser. The application starts and stays usable when it is unavailable, with durable writes disabled and the user told once.

Requirement A specification persisting a growing collection MUST state its bound and its eviction rule.

Rationale Browser quotas are small and shared across the origin, so unbounded append eventually fails a write the user cannot diagnose. Large generated assets are cached by the service worker rather than written to key storage.

Requirement Durable state MUST export to one versioned file that imports the same version, transforms an older version, and refuses a newer version.

Rationale The user saves the file, which is the only recovery path in a product with no server. Device-local state is excluded from the export. The file carries its own schema version. A refusal names the application version that wrote the file. A partial import of an unknown shape loses data silently.