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

Tasks: enterprise-browser-cache-browser

Change ID: enterprise-browser-cache-browser Package: @suaveplan/cache-browser Target path: browser/storage/cache-browser Prerequisite packages on Verdaccio: @suaveplan/cache, @suaveplan/events, @suaveplan/error, @suaveplan/types, @suaveplan/broadcast-channel

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal.md.
• package.json v0.0.0:
  • "sideEffects": ["./dist/register.js"] — only the register entry has side effects
  • Subpath exports: ".", "./localstorage", "./sessionstorage", "./indexeddb", "./register", "./types"
  • dependencies: @suaveplan/cache workspace:^, @suaveplan/events workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/broadcast-channel workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, fake-indexeddb catalog:testing, @playwright/test catalog:testing, @suaveplan/testing workspace:^
• tsconfig.json, vitest.config.ts (pool: forks, fileParallelism: false for browser tests).

---

2. Error codes

• CACHE_QUOTA_EXCEEDED, CACHE_SERIALIZATION_FAILED, INDEXEDDB_NOT_AVAILABLE.
• registerCacheBrowserErrorCodes() — call eagerly.

---

3. Serializer + eviction interfaces (src/utils/)

• serialization/: Serializer<T> interface, defaultSerializer, defaultDeserializer, isSerializable, safeDeserialize. Tests + md.
• quota/: quota utils. Tests + md.
• storage-events/: StorageEventHandler. Tests + md.
• src/eviction/lru-eviction/, lfu-eviction/, ttl-first-eviction/: each implements EvictionStrategy. Tests + md.

---

4. IndexedDB cache (src/indexeddb/)

Split into four sub-modules ≤300 lines each:

• store/store.ts: CRUD via IDB transactions, get/set/delete/clear/list.
• ttl/ttl.ts: expiresAt index, proactive sweep via requestIdleCallback.
• quota/quota.ts: quota check before write; CACHE_QUOTA_EXCEEDED on fail.
• events/events.ts: broadcast-channel invalidation hooks.
• indexeddb/indexeddb.ts: orchestrator composing above.
• getMetrics(): returns CacheMetrics (size, hitCount, missCount, evictionCount) — no private-property access in tests.
• Tests: CRUD, TTL expiry, quota guard, cross-tab invalidation (via broadcast-channel), batch ops. All test files ≤500 lines.
• Write .md per module.

---

5. LocalStorage cache (src/localstorage/)

Split similarly: store/, ttl/, quota/, events/, localstorage/.

• Cross-tab invalidation via StorageEventHandler + optional broadcastChannel.
• getMetrics() introspection.
• Tests ≤500 lines. Write .md per module.

---

6. SessionStorage cache (src/sessionstorage/)

Split: store/, ttl/, sessionstorage/.

• getMetrics() introspection.
• Tests ≤500 lines. Write .md per module.

---

7. Register entry (src/register.ts)

• Call CacheFactory.register('localStorage', () => new LocalStorageCache(...)) etc.
• This file is the only side-effect entry; matches sideEffects array.

---

8. OTel metrics

• Wire counters + histograms in each cache implementation's CRUD methods.

---

9. Playwright E2E (e2e/cache-browser.spec.ts)

• Three browser contexts (Chromium, WebKit, Firefox via Playwright).
• Assert: IndexedDB CRUD, LocalStorage TTL, cross-tab invalidation (two tabs, one writes, other reads updated value), quota-exceeded eviction.

---

10. Integration test (tests/integration.test.ts)

• All three caches via the same Cache interface.
• Eviction strategies (LRU, LFU, TTL-first) under simulated quota pressure.
• Serializer swap: replace JSON with a custom Serializer<User>.

---

11. Docs + verify

• Write .md per module (≥200 words, API reference, examples).
• Write README.md with subpath table, serializer guide, eviction strategy table, cross-tab section.
• bunx turbo lint typecheck test --filter=@suaveplan/cache-browser — green.
• bunx turbo test:coverage — 100%.
• No @ts-expect-error in src/ or tests.
• sideEffects declaration correctly reflects only register.ts.
• Playwright E2E green on Chromium, WebKit, Firefox.
• bun scripts/publish.ts --package @suaveplan/cache-browser.
• Archive to openspec/archive/2026-04-24-enterprise-browser-cache-browser/.