Track DialCache deep-review follow-up work

[lan17]

Priority

META — Tracking — umbrella only; not implementation work.

Context

This tracks follow-up from the deep API, performance, scalability, and correctness review of main@2bda04d1443a75a71cbbc41365c4424554936a37.

The reviewed tree passed strict TypeScript, 5 release-version tests, 106 unit tests with coverage thresholds, ESM/CJS/declaration build, packed-consumer checks, 48 Redis/Valkey/Redis Cluster integration tests, and production dependency audit on Node 22. dialcache@0.1.1 is now published, so P0 means work that should be completed before the next release presented as production-ready.

Only one new behavior decision is confirmed: remove flushAll() entirely. Every other design issue records evidence, decision points, and acceptance criteria but intentionally leaves architecture open for maintainer approval.

Priority rubric

• P0 — Critical: resolve before the next release presented as production-ready.
• P1 — High: resolve before broad production adoption or large-scale use.
• P2 — Medium: important hardening or API work after the safety foundations.
• P3 — Low: later or demand-driven enhancement.

P0 — Critical

• Remove flushAll from DialCache and Redis adapter contracts #13 — remove flushAll() (confirmed decision)
• Design a versioned, type-stable cache-key encoding #14 — type-stable, versioned key encoding
• Require an explicit Redis Cluster-safe cache namespace #15 — explicit cluster-safe namespace
• Make the default JSON serializer contract honest and enforceable #16 — honest default JSON serializer contract
• Add application value-schema versioning to cache identity #17 — application value-schema versioning
• Prevent stale pre-invalidation fallbacks from repopulating tracked caches #26 — prevent stale pre-invalidation fallback publication
• Fence in-process single-flight work across invalidation boundaries #27 — fence local single-flight across invalidation
• Make tracked local caching consistent with the invalidation contract #28 — make tracked local caching consistent with invalidation
• Make logger failures unable to change cache behavior #29 — isolate throwing loggers

P1 — High

• Validate exact Lua reply domains in bundled Redis adapters #30 — validate exact Lua reply domains
• Define local-cache value ownership and mutation semantics #18 — define local value ownership/mutation semantics
• Define ownership and shutdown semantics for factory-created Redis clients #20 — define Redis client ownership and shutdown
• Harden cached() callable typing for methods, generics, and overloads #22 — correct method/generic/overload typing
• Test and align the minimum declared Node 20 runtime #34 — align and prove the Node 20 minimum
• Recover safely from corrupt tracked watermark state #31 — recover safely from corrupt watermark state
• Remove or explicitly bound Redis wall-clock dependence in invalidation ordering #32 — bound or remove wall-clock invalidation ordering
• Add a repeatable performance and scale benchmark suite #35 — add repeatable performance/scale benchmarks
• Prevent Redis outages from amplifying latency, source load, and logs #38 — bound Redis outage latency, load, retries, and logs
• Add configurable serialized-payload limits with fail-open oversize behavior #36 — enforce serialized-payload ceilings
• Add byte-aware and per-use-case local-cache capacity controls #40 — add byte-aware/per-use-case local capacity
• Bound and observe in-process single-flight state #41 — bound and observe in-process single-flight state
• Characterize and guard watermark cardinality and Redis Cluster hot slots #42 — guard watermark cardinality and cluster hot slots
• Define and enforce a bounded-cardinality metrics contract #45 — enforce bounded metrics cardinality

P2 — Medium

• Make DialCacheConfig modes discriminated and explicit #19 — discriminated constructor modes
• Simplify per-layer policy declaration and validate static policy early #23 — coherent per-layer policy API
• Design a first-class typed cache-definition handle #21 — typed cache-definition handles
• Rationalize the root export surface and scope-method vocabulary #24 — rationalize exports and scope vocabulary
• Validate TTL and invalidation duration arithmetic consistently #33 — validate extreme duration arithmetic
• Keep runtime configuration lookup cheap and bounded #39 — bound runtime configuration lookup
• Add Redis write-path and end-to-end cache outcome telemetry #44 — add write-path/end-to-end outcome telemetry
• Establish a local-hit performance budget and remove avoidable hot-path work #43 — optimize the local-hit hot path

P3 — Low

• Add request-boundary helpers and missing-scope diagnostics #25 — request-boundary helpers and diagnostics
• Benchmark lower-copy Redis protocol alternatives for large payloads #37 — lower-copy Redis protocol research
• Design optional cross-process cache stampede protection #7 — optional cross-process stampede protection and TTL jitter research
• Design batch reads and invalidations without one Redis script per key #46 — batch reads and invalidations

Dependency notes

• Treat Prevent stale pre-invalidation fallbacks from repopulating tracked caches #26, Fence in-process single-flight work across invalidation boundaries #27, Make tracked local caching consistent with the invalidation contract #28, and Remove or explicitly bound Redis wall-clock dependence in invalidation ordering #32 as one invalidation-design cluster; logical generations may change or partially subsume multiple fixes.
• Complete Design a versioned, type-stable cache-key encoding #14 before typed invalidation/definition-handle work.
• Decide Make the default JSON serializer contract honest and enforceable #16 and Add application value-schema versioning to cache identity #17 before finalizing Design a first-class typed cache-definition handle #21.
• Start Add a repeatable performance and scale benchmark suite #35 in parallel with P0 work; it is an enabler even though it is not itself a correctness blocker.
• Complete Define and enforce a bounded-cardinality metrics contract #45 before expanding telemetry in Add Redis write-path and end-to-end cache outcome telemetry #44.
• Do not delay the payload ceiling in Add configurable serialized-payload limits with fail-open oversize behavior #36 for protocol research in Benchmark lower-copy Redis protocol alternatives for large payloads #37.
• Address outage controls in Prevent Redis outages from amplifying latency, source load, and logs #38 before optional Redis lease coordination in Design optional cross-process cache stampede protection #7.
• Coordinate the batch API in Design batch reads and invalidations without one Redis script per key #46 with definition handles in Design a first-class typed cache-definition handle #21.

Completion standard

• Every implementation issue includes focused unit/integration/type tests for its failure mode.
• Breaking changes include migration and mixed-version/rollback notes.
• Performance work reports reproducible before/after results.
• No design issue is implemented until its open decisions are explicitly approved.