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

# 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.