suaveplan/openspec/archive/2026-05-12-storage-browser-localstorage/proposal.md

Migrate storage-browser-localstorage into genesis

Package: @suaveplan/storage-browser-localstorage Status: PROPOSED Type: new-package (migration from suaveplan)

Why

The upstream @suaveplan/storage-browser package combines two distinct browser-tier storage backends (IndexedDB and the synchronous localStorage API) behind a single barrel and a shared sideEffects-coupled registry. Genesis is splitting the package into two focused, tree-shake-clean siblings — @suaveplan/storage-browser-indexeddb and @suaveplan/storage-browser-localstorage — that each register explicitly against the @suaveplan/storage factory. This change ships the LocalStorage half. Splitting reduces bundle size for consumers that only need one backend, removes the import-time side-effect smell flagged by the upstream enterprise audit, and produces a typed LOCAL_STORAGE.* error registry aligned with the OPFS sibling that landed today.

What changes

• ADDED: LocalStorageStorage class extending AbstractStorage from @suaveplan/storage/abstract. Synchronous Storage API presented through the AbstractStorage async surface.
• ADDED: createLocalStorageStorage(options?) factory.
• ADDED: LocalStorageStorageOptions + LocalStorageStorageOptionsSchema Zod boundary.
• ADDED: StorageLike structural interface mirroring the DOM Storage shape (getItem/setItem/removeItem/clear/length/key(i)) — injectable adapter.
• ADDED: defaultLocalStorage() adapter wrapping globalThis.localStorage, plus isLocalStorageAvailable() feature detector with sentinel-write probe.
• ADDED: createInMemoryLocalStorage() real-implementation Storage adapter for testing (no mocks).
• ADDED: LOCAL_STORAGE_CODES registry (NOT_FOUND, PERMISSION_DENIED, QUOTA_EXCEEDED, UNAVAILABLE, INVALID_KEY, KEY_TOO_LONG, INVALID_OPTIONS, ABORTED, IO_FAILED, CORRUPT_PAYLOAD) + LocalStorageError extends SuaveplanError<LocalStorageErrorCode>.
• ADDED: sanitizeKey(key) boundary (rejects empty/non-string/control-char/absolute/../null-byte; caps at 256 chars).
• ADDED: encodeEnvelope / decodeEnvelope — base64 payload + JSON metadata wire format with expiresAt TTL.
• ADDED: registerLocalStorageProvider() explicit-call factory registration under slot "localstorage".
• ADDED: Full OTel surface — storage_browser_localstorage.{reads,writes,deletes,errors}_total, op_duration_ms, io_bytes instruments with setStorageBrowserLocalStorageMeterProvider override + resetInstruments.

Out of scope

• IndexedDB backend — separate parallel migration storage-browser-indexeddb.
• Compression / encryption wrappers — deferred; out of scope for the base adapter migration.
• BroadcastChannel cross-tab sync — deferred; future feature, separate change.
• Proactive TTL sweep timer — deferred; this migration ships lazy-on-read expiry only.
• React hooks layer — separate storage-browser-react consumer, future package.

Source mapping

This change derives from ../suaveplan/enterprise/storage-browser.md.

Requirement	Source lines	Notes
AbstractStorage extension with async API over Uint8Array	L12	Upstream describes both adapters extending AbstractStorage; preserved verbatim for LocalStorage.
Base64 + JSON envelope wire format	L12, L24	Reworded — kept Base64-of-Uint8Array payload, JSON envelope { v, payload, meta, expiresAt? }.
Namespace prefix + TTL expiry on read	L24	Verbatim contract — ${namespace}:${key} keyspace, lazy delete on get.
Prefix-based listing with pagination	L12	Verbatim — list({ prefix, limit, offset }) iterates localStorage.key(i).
Metadata: size, mimeType, createdAt, updatedAt, custom	L12	Verbatim.
StorageQuotaError quota wrapping	L12	Extended — genesis uses typed LOCAL_STORAGE.QUOTA_EXCEEDED covering code 22 and code 1014 (Firefox) in addition to QuotaExceededError.
Explicit registerLocalStorageProvider() factory registration (no module-load side effects)	L48, L84	Extended — upstream had import-time side effects; the audit's "Fix sideEffects vs. registry modules" recommendation is implemented as an explicit-call function so sideEffects: false holds.
Sub-path exports ./localstorage, ./registry	L49, L102	Extended — every feature module gets its own subpath per genesis §6.
Co-located .md docs for every implementation file	L50, L86, L100	Verbatim — required gate.

Requirements with no source line

Requirement	Justification
AbortSignal threading on every public method	Genesis baseline added to every storage adapter since OPFS; pre-aborted signals throw LOCAL_STORAGE.ABORTED before any localStorage call.
Injectable Storage adapter (StorageLike interface)	Required by the genesis "no mocks" rule (CLAUDE.md §10.2) — tests must run against a real in-memory implementation rather than vi.stubGlobal.
Injectable Clock from @suaveplan/types	Genesis cross-package contract — every TTL/timestamp surface accepts a Clock for deterministic tests.
Zod boundary schemas on options	Genesis @suaveplan/validation-aligned baseline.
Typed LOCAL_STORAGE_CODES registry via defineCodes	Genesis baseline (every package owns a frozen registry); upstream used a single StorageQuotaError.
Sentinel-write availability probe with UNAVAILABLE error	Old Safari private mode throws on setItem; without a probe, callers hit a generic Error from the first write.
Full OTel surface (instruments + counters + histograms)	Genesis baseline; upstream had no observability.
CORRUPT_PAYLOAD error code	Genesis hardening — malformed base64 / JSON envelope returns a typed boundary error instead of silently swallowing as null.

Verification approach

• src/local-storage/local-storage.test.ts — CRUD, list/pagination, metadata, TTL expiry, namespace isolation, AbortSignal pre-abort, key boundary, corrupt-payload graceful degrade.
• src/local-storage/local-storage.spec-conformance.test.ts — AbstractStorage instance, capabilities matrix, every LOCAL_STORAGE_CODES.* thrown by a production path, OTel instruments emitted through a real in-memory MeterProvider.
• src/key-sanitizer/key-sanitizer.test.ts — every boundary rule.
• src/envelope/envelope.test.ts — round-trip, corrupt detection.
• src/in-memory-storage/in-memory-storage.test.ts — fixture self-test (length, key(i), getItem/setItem/removeItem, clear, quota).
• src/local-storage-adapter/local-storage-adapter.test.ts — defaultLocalStorage() + isLocalStorageAvailable() probe.
• src/otel/otel.test.ts — recorder semantics, per-op counter routing.
• src/registry/registry.test.ts — registerLocalStorageProvider() idempotency + createStorage({ type: "localstorage", ... }) roundtrip.

Migration impact

None — additive only. New package; no existing genesis consumers. Downstream genesis packages that need browser localStorage may import this package once available.

Impact

Affected dependents

bunx turbo ls --filter=...@suaveplan/storage-browser-localstorage — no dependents (package is brand new on the genesis branch). No work needed in any other package.