Initial Commit

openspec/archive/2026-04-24-enterprise-cache/proposal.md

@@ -0,0 +1,282 @@
+# OpenSpec Change: enterprise-cache
+
+- **Change ID**: enterprise-cache
+- **Package**: `@suaveplan/cache`
+- **Category**: universal
+- **Target path**: `universal/database/cache`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/cache.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/cache` on the genesis branch from scratch at enterprise quality. The package provides a type-safe caching abstraction: an `AbstractCache` base class, a built-in LRU `MemoryCache`, a `CacheFactory` with module-augmentation-based provider registry, namespaced caches, TTL support, stale-while-revalidate, multi-get/set, lifecycle hooks via `@suaveplan/events`, and cache statistics. Genesis adds structured errors via `@suaveplan/error`, Zod schemas for all option types, OTel instrumentation, injectable clock and RNG (no `Date.now()` at module scope), `AbortSignal` on async operations, property-based tests (fast-check), and a mitata benchmark suite.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | Base class for `CacheError`; `defineCodes` for `CACHE.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock` (injectable for TTL expiry, `Date.now` replacement), `EventBusLike`, `LoggerLike` |
+| `@suaveplan/events` (`workspace:^`) | `EventBus` for lifecycle hooks (hit, miss, set, evict, expire) |
+| `zod` (`catalog:forms`) | Zod schemas for all public option types |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters on every public cache operation |
+| `tslib` (`catalog:build`) | Runtime helpers |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`), `@suaveplan/testing` (`workspace:^`).
+
+---
+
+## Preserved public API surface (from main branch)
+
+### Abstract
+
+```ts
+abstract class AbstractCache<T = unknown> {
+  abstract get(key: string): Promise<T | undefined>
+  abstract set(key: string, value: T, options?: CacheSetOptions): Promise<void>
+  abstract delete(key: string): Promise<boolean>
+  abstract clear(): Promise<void>
+  abstract has(key: string): Promise<boolean>
+  abstract getStats(): CacheStats
+  abstract getMultiple(keys: string[]): Promise<CacheMultiGetResult<T>>
+  abstract setMultiple(entries: CacheMultiSetEntry<T>[]): Promise<void>
+  wrap(key: string, fn: () => Promise<T>, options?: CacheWrapOptions<T>): Promise<T>
+}
+
+class NamespacedCache<T = unknown> extends AbstractCache<T>
+```
+
+### Memory cache
+
+```ts
+class MemoryCache<T = unknown> extends AbstractCache<T> {
+  constructor(options?: CacheOptions)
+  get(key: string): Promise<T | undefined>
+  set(key: string, value: T, options?: CacheSetOptions): Promise<void>
+  delete(key: string): Promise<boolean>
+  clear(): Promise<void>
+  has(key: string): Promise<boolean>
+  getStats(): CacheStats
+  getMultiple(keys: string[]): Promise<CacheMultiGetResult<T>>
+  setMultiple(entries: CacheMultiSetEntry<T>[]): Promise<void>
+}
+```
+
+### Factory
+
+```ts
+class CacheFactory {
+  static create<T>(type: CacheProviderType, config?: CacheProviderConfig): AbstractCache<T>
+  static register(type: string, impl: CacheProviderImplementation): void
+  static unregister(type: string): void
+  static has(type: string): boolean
+  static providers(): string[]
+}
+
+function createCache<T>(type: CacheProviderType, config?: CacheProviderConfig): AbstractCache<T>
+function createCacheWithConfig<T>(config: CacheFactoryConfig): AbstractCache<T>
+function registerCacheProvider(type: string, impl: CacheProviderImplementation): void
+function unregisterCacheProvider(type: string): void
+function hasCacheProvider(type: string): boolean
+function getCacheProviders(): string[]
+function clearCacheProviders(): void
+```
+
+### Types
+
+```ts
+interface CacheEntry<T = unknown> {
+  value: T
+  expiresAt: number
+  createdAt: number
+  lastAccessedAt: number
+  hitCount: number
+}
+
+interface CacheStats { hits: number; misses: number; size: number; hitRate: number; memoryUsage?: number }
+type CacheEvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl'
+
+interface CacheOptions {
+  maxSize?: number
+  defaultTTL?: number
+  evictionPolicy?: CacheEvictionPolicy
+  enableStats?: boolean
+  checkExpirationInterval?: number
+}
+
+interface CacheSetOptions { ttl?: number; staleWhileRevalidate?: boolean; staleThreshold?: number }
+
+interface CacheWrapOptions<T> {
+  ttl?: number
+  staleWhileRevalidate?: boolean
+  staleThreshold?: number
+  forceRefresh?: boolean
+  shouldCache?: (value: T) => boolean
+}
+
+interface CacheTransformHook<T = unknown> { name: string; transform: (key: string, value: T) => Promise<T> | T; priority?: number }
+interface CacheMultiGetResult<T = unknown> { found: Map<string, T>; missing: string[] }
+interface CacheMultiSetEntry<T = unknown> { key: string; value: T; options?: CacheSetOptions }
+type CacheProviderType = keyof CacheProviderRegistry
+interface CacheProviderConfig extends CacheOptions { [key: string]: unknown }
+type CacheProviderConfigFor<K extends keyof CacheProviderRegistry> = CacheProviderRegistry[K] extends new (opts: infer O) => unknown ? O : CacheProviderConfig
+interface CacheProviderImplementation { new(options?: CacheProviderConfig): AbstractCache }
+interface CacheFactoryConfig { type: CacheProviderType; options?: CacheProviderConfig }
+interface CacheProviderRegistry { memory: typeof MemoryCache }
+
+interface CacheEvents {
+  hit: { key: string }
+  miss: { key: string }
+  set: { key: string; ttl?: number }
+  delete: { key: string }
+  clear: {}
+  evict: { key: string; reason: 'ttl' | 'lru' | 'lfu' | 'manual' }
+  expire: { key: string }
+}
+```
+
+### Error codes
+
+```ts
+type CacheErrorCode =
+  | 'CACHE_KEY_INVALID'
+  | 'CACHE_CAPACITY_EXCEEDED'
+  | 'CACHE_PROVIDER_NOT_FOUND'
+  | 'CACHE_SET_FAILED'
+  | 'CACHE_GET_FAILED'
+  | 'CACHE_SERIALIZATION_FAILED'
+```
+
+---
+
+## New additions for genesis
+
+### 1. Structured `CacheError`
+
+`CacheError` extends `SuaveplanError` from `@suaveplan/error` carrying a `CacheErrorCode` discriminant. All internal throw sites use named factory helpers.
+
+### 2. Zod option schemas
+
+- `CacheOptionsSchema`
+- `CacheSetOptionsSchema`
+- `CacheWrapOptionsSchema`
+- `CacheFactoryConfigSchema`
+- `CacheTransformHookSchema`
+
+### 3. Injectable clock
+
+`CacheOptions` gains an optional `clock?: Clock` field (from `@suaveplan/types`). `MemoryCache` uses `clock.now()` for all TTL calculations instead of bare `Date.now()`. Defaults to `{ now: () => Date.now() }`.
+
+### 4. Event bus integration
+
+`CacheOptions` gains an optional `events?: EventBusLike` field. When provided, `MemoryCache` emits typed `CacheEvents` on every hit/miss/set/delete/evict/expire. Uses `@suaveplan/events` `EventBus` shape — no external event emitter library.
+
+### 5. AbortSignal on `wrap`
+
+`CacheWrapOptions` gains an optional `signal?: AbortSignal`. The background refresh in stale-while-revalidate is aborted when the signal fires.
+
+### 6. OTel instrumentation
+
+| Operation | Signal |
+|---|---|
+| `get` | counter `cache.get_total`, attribute `cache.hit` (bool), attribute `cache.namespace` |
+| `set` | counter `cache.set_total`, attribute `cache.ttl_set` (bool) |
+| `delete` | counter `cache.delete_total` |
+| `clear` | counter `cache.clear_total` |
+| `wrap` | span `cache.wrap`, histogram `cache.wrap_duration_ms` |
+| `getStats` | gauge `cache.size`, gauge `cache.hit_rate` |
+
+### 7. LFU eviction policy
+
+The `lfu` eviction policy is fully implemented (main branch had the type but the implementation may have been a stub). `MemoryCache` uses a frequency map + linked-list for O(1) LFU eviction when `evictionPolicy: 'lfu'` is set.
+
+### 8. Property-based tests (fast-check)
+
+- **LRU eviction invariant**: after filling a cache of capacity N and setting N+1 items, assert the least-recently-used item is no longer present.
+- **TTL expiry**: for items set with TTL T, after advancing the injectable clock by T+1 ms, assert `has()` returns false and `get()` returns `undefined`.
+- **`getMultiple` completeness**: for M items set in cache and K random keys queried (K ≥ M), assert `found.size + missing.length === K` always.
+- **Stats accuracy**: for N random get/set/miss sequences, assert `hits + misses === total get calls` and `hitRate ≈ hits / (hits + misses)`.
+
+### 9. Benchmark suite
+
+- `get_hot_1k`: 1000 `get()` calls, all hits, LRU cache of 500 items.
+- `set_1k`: 1000 `set()` calls with TTL.
+- `wrap_cold`: 100 `wrap()` calls where all miss (async factory call each time).
+- `lru_eviction_pressure`: fill cache to 2x capacity, measure eviction throughput.
+
+---
+
+## File layout
+
+```text
+universal/database/cache/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts                          # Public barrel
+    error-codes.ts                    # CACHE.* codes + registerCacheErrorCodes
+    constants/
+      index.ts                        # DEFAULT_MAX_SIZE, DEFAULT_TTL, DEFAULT_EVICTION_POLICY
+    types/
+      common.ts                       # All public TS interfaces and type aliases
+      common.md
+      schemas.ts                      # Zod schemas
+      schemas.md
+    abstract/
+      abstract-cache/
+        abstract-cache.ts             # AbstractCache base class
+        abstract-cache.md
+        abstract-cache.types.ts
+        abstract-cache.test.ts
+        index.ts
+      namespaced-cache/
+        namespaced-cache.ts
+        namespaced-cache.md
+        namespaced-cache.test.ts
+        index.ts
+    memory/
+      memory-cache/
+        memory-cache.ts               # LRU/LFU/FIFO/TTL MemoryCache
+        memory-cache.md
+        memory-cache.types.ts
+        memory-cache.test.ts
+        index.ts
+    factory/
+      cache-factory/
+        cache-factory.ts              # CacheFactory class + free functions
+        cache-factory.md
+        cache-factory.types.ts
+        cache-factory.test.ts
+        index.ts
+      registry/
+        registry.ts                   # Built-in memory provider registration
+        registry.md
+        index.ts
+    __benchmarks__/
+      cache.bench.ts
+  tests/
+    integration.test.ts               # Cross-cutting: namespaced + factory + wrap round-trip
+    property.test.ts                  # fast-check property tests
+```
+
+---
+
+## Impact
+
+**Downstream packages**: `@suaveplan/idempotency` and any server-side package that needs caching will depend on `@suaveplan/cache`. No existing genesis package currently requires it.
+
+**Breaking changes from main-branch API**: none. New optional fields (`clock`, `events`, `signal`) are additive.
+
+**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events` must be published to Verdaccio before this package can be built or tested.