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 originally performed against main@2bda04d1443a75a71cbbc41365c4424554936a37.

Current status: main@9360d757ebf41252624e7e6f6b208b292ed643d9, released as https://github.com/lan17/DialCache/releases/tag/v0.5.0 and published as dialcache@0.5.0. Post-merge CI https://github.com/lan17/DialCache/actions/runs/29663133306 and release workflow https://github.com/lan17/DialCache/actions/runs/29663163960 passed. Twenty of 39 tracked issues are resolved, 19 implementation issues remain open, and every P0 is closed.

Confirmed behavior and architecture decisions are recorded explicitly in their implementation issues. Completed and explicitly closed-not-planned items are checked below. All remaining open decisions must still receive maintainer approval before implementation.

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.

Current grooming recommendation

No remaining issue blocks a controlled trial that uses static/default configuration or complete runtime policies. The confirmed partial-overlay contract is implemented in draft #68 and remains pending review and merge.

1. Review and merge feat: overlay runtime cache configuration on defaults #68 to complete Overlay runtime cache configuration on documented defaults #23; after that, Prevent Redis outages from amplifying latency, source load, and logs #38 is the next general production-hardening target.
2. Treat Prevent Redis outages from amplifying latency, source load, and logs #38 as the clearest subsequent outage hardening: avoid a second Redis attempt after a failed read while leaving timeout, retry, reconnect, queueing, and log policy caller-owned.
3. Resolve Align runtime support after Node 20 EOL #34 as compatibility hygiene before broad adoption by choosing the exact maintained Node 22+ floor.
4. Treat Bound and observe in-process single-flight state #41 and Characterize and guard watermark cardinality and Redis Cluster hot slots #42 as workload-gated checks: first enforce finite caller-owned Redis/fallback time budgets and measure tracked-ID rate, watermark lifetime, and hottest-ID QPS; add core machinery only if those measurements justify it.
5. Treat Recover safely from corrupt tracked watermark state #31, Validate TTL and invalidation duration arithmetic consistently #33, Add a repeatable performance and scale benchmark suite #35, Make zero local capacity consistent and evaluate byte-aware limits #40, and Establish a local-hit performance budget and remove avoidable hot-path work #43 as focused hardening or measurement work rather than initial-trial blockers.
6. Keep Add thresholded client-side compression for Redis payloads #60 at P3: compression is deliberately punted until production payload observations justify its format, CPU, and rollout complexity.
7. Candidate not-planned closures awaiting explicit maintainer approval: Design a first-class typed cache-definition handle #21, Rationalize the root export surface and scope-method vocabulary #24, Add request-boundary helpers and missing-scope diagnostics #25, Keep runtime configuration lookup cheap and bounded #39, and Design batch reads and invalidations without one Redis script per key #46.

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 (closed as not planned; string-canonical equality contract confirmed)
• Rename urnPrefix to namespace and expose cache namespace metrics #15 — rename urnPrefix to namespace and expose cache namespace metrics
• Require explicit serializers for statically non-JSON cached values #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 — document the application-owned futureBufferMs stale-publication timing contract (closed as completed; runtime/default unchanged)
• Fence in-process single-flight work across invalidation boundaries #27 — fence local single-flight across invalidation (closed as not planned; overlapping exact-key callers may share already-running work)
• Make tracked local caching consistent with the invalidation contract #28 — make tracked local caching consistent with invalidation (closed as not planned; invalidation is shared-Redis only)
• 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
• Document the immutable cached-value ownership contract #18 — immutable cached-value ownership contract (closed as not planned; the no-cloning/reference-sharing contract is already documented and tested)
• Require caller-owned Redis clients and remove the lazy factory #20 — require caller-owned Redis clients and remove the lazy factory (completed by feat: require caller-owned Redis clients #67)
• Overlay runtime cache configuration on documented defaults #23 — overlay runtime cache configuration on documented disabled defaults (draft implementation: feat: overlay runtime cache configuration on defaults #68)
• Align runtime support after Node 20 EOL #34 — align runtime support after Node 20 EOL
• Document the synchronized Redis clock assumption for tracked invalidation #32 — document the synchronized Redis clock assumption for tracked invalidation (resolved as a documented infrastructure contract; no runtime or protocol change)
• 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 (closed as not planned; exact serialized-byte observability is retained and hard ceilings remain application-owned)
• 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 (completed by the metrics-adapter and direct Redis-client simplifications)
• Recover safely from corrupt tracked watermark state #31 — document and test corrupt-watermark quarantine/recovery
• Add a repeatable performance and scale benchmark suite #35 — extend the existing benchmark into a comparable harness
• Make zero local capacity consistent and evaluate byte-aware limits #40 — make zero local capacity consistent and evaluate byte-aware limits
• 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
• Decouple core observability from Prometheus #53 — decouple core observability from Prometheus
• Add a first-party Datadog DogStatsD metrics adapter #54 — add a first-party Datadog DogStatsD adapter
• 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 (closed as not planned; the approved contract keeps serialization latency and serialized bytes without broad Redis client/write timing)
• Establish a local-hit performance budget and remove avoidable hot-path work #43 — optimize the local-hit hot path
• Add a runtime-controlled request-local cache layer #51 — runtime-controlled request-local cache layer

P3 — Low

• Characterize and improve cached() callable-shape typing #22 — characterize generic/overloaded/method callable typing before v1 or concrete demand
• 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
• Add thresholded client-side compression for Redis payloads #60 — thresholded client-side compression for large Redis payloads (demand-driven; punted for now)
• 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

• The invalidation-design cluster in 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 Document the synchronized Redis clock assumption for tracked invalidation #32 is resolved. Issue 26 documents the application-owned futureBufferMs timing contract; issue 27 accepts brief same-instance exact-key overlap with already-running work; issue 28 keeps invalidation shared-Redis-only; and issue 32 records synchronized Redis clocks as an infrastructure assumption while requiring futureBufferMs to include anticipated negative skew. No logical-generation protocol is planned; docs: document Redis clock synchronization assumption #66 merged the README and public TSDoc contract.
• The caller-owned Redis lifecycle decision in Require caller-owned Redis clients and remove the lazy factory #20 removed the lazy factory through merged feat: require caller-owned Redis clients #67. This eliminates factory retry/ownership ambiguity; Prevent Redis outages from amplifying latency, source load, and logs #38 now focuses on avoiding DialCache's second Redis attempt after a failed read while leaving timeout, retry, reconnect, queueing, and log policy at the caller-owned client/logger boundary.
• The key-equality decision in Design a versioned, type-stable cache-key encoding #14 is resolved; typed invalidation and definition-handle work must preserve its documented string-canonical identity contract.
• The serializer and schema-compatibility decisions in Require explicit serializers for statically non-JSON cached values #16 and Add application value-schema versioning to cache identity #17 are resolved; Design a first-class typed cache-definition handle #21 must preserve those contracts.
• The confirmed contract in Overlay runtime cache configuration on documented defaults #23 keeps defaultConfig optional with a disabled baseline when absent, overlays non-null runtime configuration field by field, uses explicit false/ramp-zero disabling, and removes normal missing_config outcomes in favor of documented policy defaults. Draft implementation and migration guidance are in feat: overlay runtime cache configuration on defaults #68.
• Add a repeatable performance and scale benchmark suite #35 remains an enabler for performance-sensitive P1/P2 work even though it is not itself a correctness blocker.
• The bounded-cardinality contract in Define and enforce a bounded-cardinality metrics contract #45 is complete. Broad write/client/end-to-end telemetry in Add Redis write-path and end-to-end cache outcome telemetry #44 is closed as not planned; future safety features may add only the specific bounded outcome they require.
• Prometheus decoupling in Decouple core observability from Prometheus #53 and constructor-mode cleanup in Make DialCacheConfig modes discriminated and explicit #19 are complete; any future export cleanup in Rationalize the root export surface and scope-method vocabulary #24 must preserve the backend-neutral adapter boundary.
• The prerequisite chain across Define and enforce a bounded-cardinality metrics contract #45, Decouple core observability from Prometheus #53, and Add a first-party Datadog DogStatsD metrics adapter #54 is complete.
• Add configurable serialized-payload limits with fail-open oversize behavior #36 is closed as not planned: hard payload limits remain application-owned. Compression in Add thresholded client-side compression for Redis payloads #60 is demand-driven; if implemented, it must preserve decoder safety without introducing a universal cache-value ceiling and should use evidence from Add a repeatable performance and scale benchmark suite #35.
• 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.

[lan17]

Tracking update: draft #68 implements #23 and is now the active review item. The tracker body links the PR and records #38 as the next general production-hardening target after merge.