83 lines
5.2 KiB
Markdown
83 lines
5.2 KiB
Markdown
# Tasks: enterprise-server-cache-memory
|
|
|
|
**Change ID**: enterprise-server-cache-memory
|
|
**Package**: `@suaveplan/cache-memory`
|
|
**Target path**: `server/data/cache-memory`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`
|
|
|
|
---
|
|
|
|
## 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` layout.
|
|
- [ ] Write `package.json` at `0.1.0`, `"sideEffects": false`, exports map for `"."`, `adapter`, and `lru`.
|
|
- [ ] Add dependencies: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/logger workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
|
|
- [ ] Add devDependencies: `vitest catalog:testing`, `@vitest/coverage-istanbul catalog:testing`, `fast-check catalog:testing`, `@suaveplan/testing workspace:^`.
|
|
- [ ] `tsconfig.json` extending `library.json`; `vitest.config.ts` using `createTestConfig()`.
|
|
- [ ] Scripts: `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`.
|
|
|
|
## 2. Types and errors
|
|
|
|
- [ ] Define `MemoryCacheOptions`, `CacheStats`, `MemoryCacheOptionsSchema` in `src/types/cache-memory.types.ts`.
|
|
- [ ] Write `cache-memory.types.md` (≥200 words, both examples, API reference).
|
|
- [ ] `src/error-codes.ts`: `MemoryCacheErrorCode`, metadata, `registerMemoryCacheErrorCodes()`, eager call.
|
|
|
|
## 3. LRU data structure
|
|
|
|
- [ ] Implement `src/lru/lru-cache/lru-cache.ts`:
|
|
- Doubly-linked list + Map, O(1) get/set/delete.
|
|
- `LruCache<V>` with `maxSize`, `get(k)`, `set(k, v)`, `delete(k)`, `has(k)`, `keys()`, `size`.
|
|
- On capacity exceeded: evict LRU (tail) entry; increment eviction counter.
|
|
- No external deps.
|
|
- [ ] Write `lru-cache.test.ts`: LRU ordering, capacity eviction, re-access promotes entry, delete middle node, size tracking.
|
|
- [ ] Write `lru-cache.md` (≥200 words).
|
|
|
|
## 4. Memory cache adapter
|
|
|
|
- [ ] Implement `MemoryCacheAdapter` in `src/adapter/memory-cache-adapter/memory-cache-adapter.ts`:
|
|
- Owns an `LruCache<{ value: Uint8Array; expiresAt?: number }>`.
|
|
- `get(key)`: check expiry using `clock.now()` (or `Date.now()` when no clock); on expiry call `delete(key)` and return `undefined`; increment hit/miss counter.
|
|
- `set(key, value, ttlMs?)`: store entry with `expiresAt = clock.now() + ttlMs` when TTL supplied; evict if `maxSize` exceeded (handled by LRU internally).
|
|
- `delete(key)`: remove entry; return `true` if existed.
|
|
- `has(key)`: get + check expiry; return bool.
|
|
- `list(prefix?)`: iterate keys, skip expired, filter by prefix.
|
|
- `clear()`: reset LRU; reset stats.
|
|
- `ttl(key)`: `expiresAt - clock.now()` or `undefined`.
|
|
- `size()`: current entry count.
|
|
- `stats()`: return `CacheStats` snapshot.
|
|
- OTel: counter `cache_memory.ops_total` (operation, hit); histogram `cache_memory.duration_ms`.
|
|
- [ ] Export `createMemoryCacheAdapter(options?)`.
|
|
- [ ] Write `memory-cache-adapter.types.ts` with internal types.
|
|
- [ ] Write `memory-cache-adapter.test.ts` (≤500 lines): all CRUD, TTL expiry with FakeClock, LRU eviction order, stats accuracy, concurrent access (synchronous — no real concurrency needed), logger invocations.
|
|
- [ ] Write `memory-cache-adapter.md` (≥200 words, simple + advanced, full API reference).
|
|
|
|
## 5. Property-based tests
|
|
|
|
- [ ] Write `tests/property.test.ts` (≤500 lines, `{ timeout: 30000 }` on each):
|
|
- **Get/set round-trip**: for arbitrary keys + values, `set` then `get` returns the same bytes.
|
|
- **Delete removes**: after `set` + `delete`, `get` returns `undefined`.
|
|
- **TTL expiry consistency**: entries with `ttlMs = 0` never returned on next `get` with advanced clock.
|
|
- **LRU ordering**: inserting N+1 entries into a size-N cache results in the oldest-accessed entry being evicted.
|
|
- **Stats accuracy**: `hits + misses === total get calls` for arbitrary call sequences.
|
|
|
|
## 6. OTel + docs
|
|
|
|
- [ ] Counter `cache_memory.ops_total`; histogram `cache_memory.duration_ms` as specified.
|
|
- [ ] All `.md` files per layout; root `README.md` with quick-start, FakeClock testing example, API table, deps table.
|
|
|
|
## 7. Verify and publish
|
|
|
|
- [ ] `bunx turbo lint --filter=@suaveplan/cache-memory` — zero errors.
|
|
- [ ] `bunx turbo typecheck --filter=@suaveplan/cache-memory` — zero errors.
|
|
- [ ] `bunx turbo test --filter=@suaveplan/cache-memory` — all tests pass.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/cache-memory` — 100%.
|
|
- [ ] Confirm `"sideEffects": false` set; no `TODO`/`any`/`.skip` in `src/`.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/cache-memory`.
|
|
- [ ] Update `CLAUDE.md`; archive to `openspec/archive/2026-04-24-enterprise-server-cache-memory/`.
|