Track DialCache deep-review follow-up work

[lan17]

Priority

META — Tracking — umbrella only; not implementation work.

Current baseline

Reconciled on 2026-07-26 against:

• main@e06d833ba245706a499d66056fdad15dc1210b68
• GitHub release https://github.com/lan17/DialCache/releases/tag/v0.11.0
• npm dialcache@0.11.0
• passing post-release CI https://github.com/lan17/DialCache/actions/runs/30181014381
• passing release run https://github.com/lan17/DialCache/actions/runs/30181014414
• clean Node.js 22.22.0 verification: typecheck, 278 unit tests, coverage thresholds, build/declarations, packed ESM/CommonJS consumers, 73 Redis/Valkey/cluster integrations, dependency audits, and semantic benchmark assertions

Forty-eight implementation issues are tracked: 27 resolved and 21 open, plus this meta issue. Every P0 is resolved. The open implementation backlog is:

• 3 P1
• 8 P2
• 10 P3

No new P0 was found.

Changes since the v0.10.0 grooming baseline

• Clear high-severity advisories from the development dependency graph #92 shipped through chore: clear development dependency advisories #93 and is released in v0.11.0.
• Align runtime support after Node 20 EOL #34 shipped through feat: require Node.js 22 or newer #94 and is released in v0.11.0.
• The package now requires Node.js >=22.0.0.
• Seven non-duplicate findings from the v0.11 holistic review were filed as Validate cache-key shapes before canonicalization #97 through Consume rejected promises from logger and metrics adapters #103.
• Existing issues Rationalize the root export surface and scope-method vocabulary #24, Validate TTL and invalidation duration arithmetic consistently #33, Add a repeatable performance and scale benchmark suite #35, and Establish a local-hit performance budget and remove avoidable hot-path work #43 were refreshed with current source, shipped work, reproduced evidence, and narrowed acceptance criteria.
• No open design issue was closed or approved for implementation during grooming.

Recommended order

1. Reject out-of-range runtime ramps instead of activating cache layers #102 — reject invalid runtime ramp values before they can activate a cache layer.
2. Snapshot cached definition options at registration #101 — snapshot registered definitions so caller mutation cannot create cache-identity collisions.
3. Consume rejected promises from logger and metrics adapters #103 — consume rejected logger/metrics promises so observer failure cannot terminate the process.
4. Review fix: cap cache durations at one year #96, the ready and green implementation for Validate TTL and invalidation duration arithmetic consistently #33.
5. Validate cache-key shapes before canonicalization #97 — reject malformed runtime key shapes and fall back uncached.
6. Fail remote invalidation when Redis is not configured #98 — make explicit remote invalidation fail when Redis is absent.
7. Preserve payload-error identity across CommonJS package subpaths #99 — restore payload-error identity across CommonJS package subpaths.
8. Add a repeatable performance and scale benchmark suite #35 — establish comparable performance and scale measurement.
9. Characterize and guard watermark cardinality and Redis Cluster hot slots #42 — measure watermark cardinality, hot IDs, and primary limits through Add a repeatable performance and scale benchmark suite #35.
10. Rationalize the root export surface and scope-method vocabulary #24 — finish the explicit pre-v1 public-surface decisions.
11. Recover safely from corrupt tracked watermark state #31 — complete focused corrupt-watermark recovery documentation/tests.
12. Make Valkey GLIDE script-handle cleanup exception-safe #100 — make GLIDE native-handle cleanup exception-safe.
13. Establish a local-hit performance budget and remove avoidable hot-path work #43 — optimize only costs reproduced through Add a repeatable performance and scale benchmark suite #35.
14. Keep the remaining P3 design work evidence- or demand-driven.

P0 — Critical — all resolved

• Remove flushAll from DialCache and Redis adapter contracts #13 — removed flushAll() through feat: remove flushAll from public API #48
• Design a versioned, type-stable cache-key encoding #14 — closed not planned; string-canonical scalar equality confirmed
• Rename urnPrefix to namespace and expose cache namespace metrics #15 — one explicit namespace across keys and metrics
• Require explicit serializers for statically non-JSON cached values #16 — honest default-JSON type contract
• Add application value-schema versioning to cache identity #17 — closed not planned; schema compatibility uses validating serializers or a new useCase
• Prevent stale pre-invalidation fallbacks from repopulating tracked caches #26 — application-owned invalidation-buffer contract
• Fence in-process single-flight work across invalidation boundaries #27 — closed not planned; accepted overlapping exact-key in-flight work
• Make tracked local caching consistent with the invalidation contract #28 — closed not planned; targeted invalidation remains shared-Redis-only
• Make logger failures unable to change cache behavior #29 — non-throwing synchronous logger isolation

P1 — High — 3 open

Resolved:

• Document the immutable cached-value ownership contract #18 — immutable/reference-sharing ownership documented
• Require caller-owned Redis clients and remove the lazy factory #20 — caller-owned Redis clients
• Overlay runtime cache configuration on documented defaults #23 — sparse runtime-config overlays
• Validate exact Lua reply domains in bundled Redis adapters #30 — exact Lua reply validation
• Document the synchronized Redis clock assumption for tracked invalidation #32 — synchronized Redis clock infrastructure contract
• Align runtime support after Node 20 EOL #34 — maintained Node.js 22+ runtime floor
• Add configurable serialized-payload limits with fail-open oversize behavior #36 — application-owned payload ceilings
• Enforce runtime-configurable remote read deadlines and fail open without a second Redis operation #38 — finite remote-read deadlines and no second Redis operation after read failure
• Require finite single-flight lifetimes and expose observability #41 — fallback deadlines and coalescing state
• Bound metrics error labels with a backend-neutral taxonomy #45 — bounded backend-neutral error taxonomy
• Clear high-severity advisories from the development dependency graph #92 — development dependency security remediation

Open:

• Reject out-of-range runtime ramps instead of activating cache layers #102 — reject out-of-range runtime ramps
• Snapshot cached definition options at registration #101 — snapshot cached definitions at registration
• Consume rejected promises from logger and metrics adapters #103 — consume rejected logger/metrics promises

P2 — Medium — 8 open

Resolved:

• Make DialCacheConfig modes discriminated and explicit #19 — constructor modes simplified
• Keep runtime configuration lookup cheap and bounded #39 — consolidated into Establish a local-hit performance budget and remove avoidable hot-path work #43
• Add Redis write-path and end-to-end cache outcome telemetry #44 — broad Redis write/client telemetry closed not planned
• Add a runtime-controlled request-local cache layer #51 — runtime-controlled request-local cache
• Decouple core observability from Prometheus #53 — Prometheus decoupling
• Add a first-party Datadog DogStatsD metrics adapter #54 — first-party Datadog adapter
• Add an ergonomic getOrLoad() API for inline cache blocks #71 — inline getOrLoad() API

Open:

• Rationalize the root export surface and scope-method vocabulary #24 — pre-v1 root exports and scope vocabulary
• Validate TTL and invalidation duration arithmetic consistently #33 — safe duration arithmetic; ready implementation in fix: cap cache durations at one year #96
• Add a repeatable performance and scale benchmark suite #35 — comparable performance/scale harness
• Make zero local capacity consistent and evaluate byte-aware limits #40 — zero-capacity semantics and deferred weighting decision
• Characterize and guard watermark cardinality and Redis Cluster hot slots #42 — derived watermark cardinality and hot-ID scale
• Validate cache-key shapes before canonicalization #97 — validate runtime cache-key shapes
• Fail remote invalidation when Redis is not configured #98 — fail explicit remote invalidation without Redis
• Preserve payload-error identity across CommonJS package subpaths #99 — preserve CommonJS payload-error identity

P3 — Low / demand-driven — 10 open

• Design optional cross-process cache stampede protection #7 — optional cross-process stampede mitigation
• Design a first-class typed cache-definition handle #21 — typed cache-definition handle design
• Characterize and improve cached() callable-shape typing #22 — callable-shape typing characterization
• Add request-boundary helpers and missing-scope diagnostics #25 — optional missing-scope diagnostic/framework integration
• Recover safely from corrupt tracked watermark state #31 — corrupt-watermark operational docs and edge-case tests
• Benchmark lower-copy Redis protocol alternatives for large payloads #37 — lower-copy Redis protocol research
• Establish a local-hit performance budget and remove avoidable hot-path work #43 — measured local-hit optimization
• Design batch reads and invalidations without one Redis script per key #46 — batch API design
• Add thresholded client-side compression for Redis payloads #60 — thresholded client-side compression
• Make Valkey GLIDE script-handle cleanup exception-safe #100 — exception-safe GLIDE script-handle cleanup

Dependencies and boundaries

• Snapshot cached definition options at registration #101 is correctness work independent of speculative definition-handle design in Design a first-class typed cache-definition handle #21.
• Reject out-of-range runtime ramps instead of activating cache layers #102 builds on sparse overlays from Overlay runtime cache configuration on documented defaults #23 and deterministic internal ramping from refactor: internalize deterministic ramp sampling #86.
• Consume rejected promises from logger and metrics adapters #103 closes the promise-return gap left after synchronous logger isolation in Make logger failures unable to change cache behavior #29.
• Duration arithmetic remains in Validate TTL and invalidation duration arithmetic consistently #33 and fix: cap cache durations at one year #96; do not combine it with runtime-ramp validation.
• Add a repeatable performance and scale benchmark suite #35 is the measurement prerequisite for Characterize and guard watermark cardinality and Redis Cluster hot slots #42, Establish a local-hit performance budget and remove avoidable hot-path work #43, and any resumed performance-sensitive work in Make zero local capacity consistent and evaluate byte-aware limits #40 or Add thresholded client-side compression for Redis payloads #60.
• Establish a local-hit performance budget and remove avoidable hot-path work #43 owns the no-custom-provider fast path, redundant tracked-prefix construction, clock elision, and any justified internal cache-layer simplification.
• Dynamic-provider memoization, refresh, and settlement deadlines remain application-owned.
• No open design issue is approved for implementation or closure merely by appearing in this tracker. Keep design issues open until the behavior/API decision is explicitly confirmed.

Live pull-request state

#96

• Implements Validate TTL and invalidation duration arithmetic consistently #33 with the agreed fixed 365-day maximum.
• Base e06d833ba245706a499d66056fdad15dc1210b68; head 8ff528a9aef980828f358ea7dbb32749c73f80b6.
• Open, non-draft, mergeable, green, and review-required.
• It is not merged or shipped. If it later merges and closes Validate TTL and invalidation duration arithmetic consistently #33, the tracker becomes 28 resolved / 20 open, with 3 P1, 7 P2, and 10 P3 open.

#89

• Documentation-only README/reference-guide rewrite based on current v0.11.0 main.
• Base e06d833ba245706a499d66056fdad15dc1210b68; head b44c9de34fae1344b063a9e5a6d0e3b8fdfadfc1.
• Open draft, mergeable, green, and review-required.
• It does not resolve Rationalize the root export surface and scope-method vocabulary #24 or change implementation counts.
• It needs a separate ready-for-review and merge decision.

Completion standard

• Focused unit/integration/type coverage for the demonstrated failure mode.
• Public type/package-topology fixes include packed ESM and CommonJS proof.
• Breaking behavior or API changes include migration and mixed-version/rollback notes.
• Performance work includes reproducible before/after evidence.
• No new public API, configuration path, state machine, or operational subsystem without concrete need and explicit approval.

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