suaveplan/openspec/archive/2026-05-16-add-cache-storage-redis-backends/tasks.md

Tasks — add-cache-storage-redis-backends

Every checkbox MUST reflect work actually done in this change.

1. Spec authoring

• 1.1 Read openspec/specs/cache/spec.md (existing @suaveplan/cache)
• 1.2 Read openspec/specs/storage/spec.md (AbstractStorage)
• 1.3 Read CLAUDE.md, AGENTS.md, openspec/AGENTS.md
• 1.4 Read existing packages/flow/cache/src/ to confirm extension surface
• 1.5 Draft proposal.md, design.md, specs/cache-storage/spec.md, specs/cache-redis/spec.md, tasks.md
• 1.6 Spec-first inventory (INVENTORY.md)

2. Scaffolding — @suaveplan/cache-storage

• 2.1 Create packages/flow/cache-storage/
• 2.2 package.json v0.0.0, sideEffects: ["./src/registry-augment/registry-augment.ts", "./dist/registry-augment/registry-augment.js"], subpath exports for root + every feature
• 2.3 Deps: @suaveplan/cache, @suaveplan/error, @suaveplan/events, @suaveplan/storage, @suaveplan/types, tslib
• 2.4 DevDeps: @suaveplan/testing, @vitest/coverage-istanbul, typescript, vite, vite-plugin-dts, vitest
• 2.5 tsconfig.lib.json, vite.config.ts, vitest.config.ts

3. Scaffolding — @suaveplan/cache-redis

• 3.1 Create packages/flow/cache-redis/
• 3.2 package.json v0.0.0, sideEffects for the registry-augment file, engines.node >=18, no browser field
• 3.3 Deps: @suaveplan/cache, @suaveplan/cache-storage (for codecs), @suaveplan/error, @suaveplan/events, @suaveplan/types, tslib
• 3.4 DevDeps: @suaveplan/testing, vitest toolchain
• 3.5 tsconfig.lib.json, vite.config.ts, vitest.config.ts

4. Implementation — @suaveplan/cache-storage

• 4.1 src/errors/errors.ts — CACHE_STORAGE_CODES (5 codes) + StorageCacheError
• 4.2 src/types/types.ts — HeaderMeta, StorageCacheOptions
• 4.3 src/header/header.ts — HEADER_BYTES, encodeHeader, decodeHeader with bounds checks
• 4.4 src/codec/codec.ts — Codec<T> interface barrel
• 4.5 src/codec/identity.ts — IdentityCodec
• 4.6 src/codec/json.ts — JsonCodec<T> with CODEC_ERROR mapping
• 4.7 src/storage-cache/storage-cache.ts — StorageCache<T> extends AbstractCache<T>
• 4.8 src/registry-augment/registry-augment.ts — declare module + idempotent register
• 4.9 src/index.ts — explicit named re-exports + side-effect import of registry-augment

5. Implementation — @suaveplan/cache-redis

• 5.1 src/errors/errors.ts — CACHE_REDIS_CODES (5 codes) + RedisCacheError
• 5.2 src/types/types.ts — RedisCacheOptions
• 5.3 src/redis-like/redis-like.ts — RedisLike + RedisScanResult interfaces
• 5.4 src/redis-cache/redis-cache.ts — RedisCache<T> extends AbstractCache<T>
• 5.5 src/registry-augment/registry-augment.ts — declare module + idempotent register
• 5.6 src/index.ts — explicit named re-exports + side-effect import

6. Tests — @suaveplan/cache-storage

• 6.1 src/header/header.test.ts — every Verified-by test
• 6.2 src/codec/identity.test.ts — round-trip
• 6.3 src/codec/json.test.ts — round-trip + CODEC_ERROR
• 6.4 src/storage-cache/storage-cache.test.ts — every Verified-by test + lifecycle events + namespace + hitRate + tier-purity grep
• 6.5 src/registry-augment/registry-augment.test.ts — both Verified-by tests
• 6.6 src/errors/errors.test.ts — every CACHE_STORAGE_* code reachable
• 6.7 Every it(...) carries { timeout: 5000 }
• 6.8 All test imports via @suaveplan/testing/runner

7. Tests — @suaveplan/cache-redis

• 7.1 src/redis-like/redis-like.test.ts — FakeRedis conformance
• 7.2 src/redis-cache/redis-cache.test.ts — every Verified-by test + tier-purity grep
• 7.3 src/registry-augment/registry-augment.test.ts — both Verified-by tests
• 7.4 src/errors/errors.test.ts — every CACHE_REDIS_* code reachable
• 7.5 Every it(...) carries { timeout: 5000 }
• 7.6 All test imports via @suaveplan/testing/runner

8. Documentation

• 8.1 Sibling .md for every implementation .ts (≥200 words, required sections)
• 8.2 packages/flow/cache-storage/README.md
• 8.3 packages/flow/cache-redis/README.md

9. Gates

• 9.1 bunx turbo lint typecheck test --filter=@suaveplan/cache-storage
• 9.2 bunx turbo lint typecheck test --filter=@suaveplan/cache-redis
• 9.3 bunx turbo test:coverage --filter=@suaveplan/cache-storage (100/100/100/100)
• 9.4 bunx turbo test:coverage --filter=@suaveplan/cache-redis (100/100/100/100)
• 9.5 bunx turbo build --filter=@suaveplan/cache-storage
• 9.6 bunx turbo build --filter=@suaveplan/cache-redis
• 9.7 Banned-pattern scan (zero output)
• 9.8 Barrel-shape scan (zero output)
• 9.9 Runner-import scan (zero output)
• 9.10 Missing-.md scan (zero output)
• 9.11 Bare-version scan (zero output)
• 9.12 bunx turbo test --filter=...@suaveplan/cache (foundation sweep)

10. Manifest & archival

• 10.1 bun scripts/folder-reorg/generate-manifest.ts (refresh MANIFEST.md)
• 10.2 Flip rows in STATUS.md: cache-browser ✅, cache-memory ✅, cache-redis ✅
• 10.3 Update SUMMARY.md with both new packages
• 10.4 bunx markdownlint-cli2 --fix
• 10.5 Fold specs/cache-storage/spec.md → openspec/specs/cache-storage/spec.md
• 10.6 Fold specs/cache-redis/spec.md → openspec/specs/cache-redis/spec.md
• 10.7 Move change folder → openspec/archive/<yyyy-mm-dd>-add-cache-storage-redis-backends/