suaveplan/openspec/changes/enterprise-browser-cache-browser/proposal.md

# OpenSpec Change: enterprise-browser-cache-browser

- **Change ID**: enterprise-browser-cache-browser
- **Package**: `@suaveplan/cache-browser`
- **Category**: browser
- **Target path**: `browser/storage/cache-browser`
- **Status**: IN PROGRESS
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/cache-browser.md`

---

## Summary

Deliver `@suaveplan/cache-browser` on the genesis branch at enterprise quality. The package provides browser-side cache implementations (`LocalStorageCache`, `SessionStorageCache`, `IndexedDBCache`) plugging into `@suaveplan/cache`, plus quota utilities, pluggable serializers, cross-tab invalidation via `@suaveplan/broadcast-channel`, pluggable eviction strategies, and OTel metrics. Auto-registration contract and `sideEffects` declaration are aligned.

---

## Current-state audit (genesis)

Fresh build — does not exist on genesis yet.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/cache` (`workspace:^`) | `Cache` interface, `CacheFactory` |
| `@suaveplan/events` (`workspace:^`) | Storage-event multiplexer |
| `@suaveplan/error` (`workspace:^`) | Typed cache errors |
| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
| `@suaveplan/broadcast-channel` (`workspace:^`) | Cross-tab invalidation |
| `@suaveplan/crypto` (`workspace:^`) | Optional AES-GCM encryption transform |
| `@suaveplan/schema-registry` (`workspace:^`) | Register cache config schemas |
| `zod` (`catalog:forms`) | Config schemas |
| `@opentelemetry/api` (`catalog:observability`) | Cache hit/miss/eviction metrics |
| `tslib` (`catalog:build`) | Runtime helpers |

Dev: `vitest`, `@vitest/coverage-istanbul`, `fake-indexeddb` (`catalog:testing`), `@playwright/test`, `@suaveplan/testing`.

---

## Preserved public API surface

```ts
// Three cache implementations
class LocalStorageCache implements Cache { constructor(config: LocalStorageCacheConfig) }
class SessionStorageCache implements Cache { constructor(config: SessionStorageCacheConfig) }
class IndexedDBCache implements Cache { constructor(config: IndexedDBCacheConfig) }

// Subpath exports
// @suaveplan/cache-browser/localstorage
// @suaveplan/cache-browser/sessionstorage
// @suaveplan/cache-browser/indexeddb
// @suaveplan/cache-browser/register  (explicit auto-registration)

// Quota utilities
function getStorageQuota(): Promise<StorageQuota>
function isStorageNearQuota(threshold?: number): Promise<boolean>
function estimateStorageSize(): Promise<number>
function handleQuotaExceeded(cache: Cache, strategy: EvictionStrategy): Promise<void>
function isStorageAvailable(type: 'localStorage' | 'sessionStorage'): boolean

// Serialization
function defaultSerializer<T>(value: T): string
function defaultDeserializer<T>(raw: string): T
function isSerializable(value: unknown): boolean
function safeDeserialize<T>(raw: string): T | undefined

// Storage events
class StorageEventHandler { ... }
const globalStorageEventHandler: StorageEventHandler

// Config types
interface LocalStorageCacheConfig { namespace: string; ttl?: number; serializer?: Serializer<unknown> }
interface SessionStorageCacheConfig { namespace: string; ttl?: number; serializer?: Serializer<unknown> }
interface IndexedDBCacheConfig { dbName: string; storeName: string; ttl?: number; schemaVersion?: number; serializer?: Serializer<unknown> }
```

---

## New additions for genesis

### 1. `sideEffects` contract

Auto-registration moves to explicit `@suaveplan/cache-browser/register` subpath; `"sideEffects": false` is then accurate for all other entry points. The `register` subpath is a `sideEffects: ["./dist/register.js"]` entry.

### 2. Pluggable `Serializer<T>` interface

```ts
interface Serializer<T> { serialize(value: T): string; deserialize(raw: string): T }
```

Default: JSON. Alternatives: `CborSerializer` (via `@msgpack/msgpack`), `StructuredCloneSerializer`.

### 3. `EvictionStrategy` interface

```ts
interface EvictionStrategy { selectForEviction(entries: CacheEntry[]): CacheEntry[] }
class LRUEviction implements EvictionStrategy { ... }
class LFUEviction implements EvictionStrategy { ... }
class TTLFirstEviction implements EvictionStrategy { ... }
```

### 4. Cross-tab invalidation

`LocalStorageCache` and `IndexedDBCache` accept an optional `broadcastChannel?: TypedBroadcastChannel` — on write/delete/clear, publishes invalidation events so other tabs update their in-memory views.

### 5. Split oversized files

Each implementation splits into: `store.ts` (core CRUD), `ttl.ts` (expiry logic), `quota.ts` (quota guard), `events.ts` (storage-event wiring). All ≤300 lines.

### 6. Public introspection surface

`cache.getMetrics(): CacheMetrics` replaces private-property reach-through in tests.

### 7. Error codes

`CACHE_QUOTA_EXCEEDED`, `CACHE_SERIALIZATION_FAILED`, `INDEXEDDB_NOT_AVAILABLE`.

### 8. OTel metrics

Counter `cache.hits_total{backend}`, counter `cache.misses_total{backend}`, counter `cache.evictions_total{strategy}`, histograms `cache.read_ms`, `cache.write_ms`.

---

## File layout

```text
browser/storage/cache-browser/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    register.ts              (explicit CacheFactory.register calls; sideEffects entry)
    error-codes.ts
    indexeddb/
      store/        (store.ts, store.test.ts, store.md)
      ttl/          (ttl.ts, ttl.test.ts, ttl.md)
      quota/        (quota.ts, quota.test.ts, quota.md)
      events/       (events.ts, events.test.ts, events.md)
      indexeddb/    (indexeddb.ts — orchestrator, indexeddb.test.ts, indexeddb.md, indexeddb.types.ts)
    localstorage/
      store/
      ttl/
      quota/
      events/
      localstorage/ (localstorage.ts, localstorage.test.ts, localstorage.md, localstorage.types.ts)
    sessionstorage/
      store/
      ttl/
      sessionstorage/ (sessionstorage.ts, sessionstorage.test.ts, sessionstorage.md, sessionstorage.types.ts)
    utils/
      quota/         (getStorageQuota, isStorageNearQuota, estimateStorageSize, handleQuotaExceeded, isStorageAvailable)
      serialization/ (defaultSerializer/Deserializer, isSerializable, safeDeserialize, Serializer interface)
      storage-events/(StorageEventHandler, globalStorageEventHandler)
    eviction/
      lru-eviction/
      lfu-eviction/
      ttl-first-eviction/
    types/
      types/         (all shared types)
  tests/
    integration.test.ts
  e2e/
    cache-browser.spec.ts   (Playwright: Chromium/WebKit/Firefox real storage)
```

---

## Impact

**Downstream**: `@suaveplan/analytics-browser`, `@suaveplan/pwa`, `@suaveplan/network-discovery-*`, any package using browser caching.

**Prerequisites**: `@suaveplan/cache`, `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/broadcast-channel` on Verdaccio.