Track DialCache deep-review follow-up work

[lan17]

Priority

META — Tracking — umbrella only; not implementation work.

Current baseline

Reconciled on 2026-08-01 against:

• main@34bd022f656ae0057f68390fcbea64f5ab9b08c5
• GitHub release https://github.com/lan17/DialCache/releases/tag/v0.14.0
• npm dialcache@0.14.0 as the latest published package
• passing current-main CI https://github.com/lan17/DialCache/actions/runs/30669912007
• green current CodeQL, Scorecard, and release workflows

Fifty-two implementation issues are tracked: 37 resolved and 15 open, plus this meta issue. Every P0 is resolved. After promoting #98 for invalidation safety, the open implementation backlog is:

• 3 P1
• 7 P2
• 5 P3

No open implementation issue is already shipped on main.

Shipped since the v0.11.0 grooming baseline

• Validate TTL and invalidation duration arithmetic consistently #33 shipped through fix: cap cache durations at one year #96 and was released in v0.12.0.
• Add sampled shadow validation for tracked Redis cache hits #104 shipped through feat: add sampled Redis shadow validation #105 and was released in v0.12.0.
• Reject out-of-range runtime ramps instead of activating cache layers #102, Consume rejected promises from logger and metrics adapters #103, and Bootstrap and validate Redis through detached shadow mode #110 shipped through feat: bootstrap Redis through detached shadow mode #111 and were released in v0.13.0.
• feat: group shadow config and log mismatch JSON #113 added grouped shadow configuration and opt-in JSON mismatch logging in v0.14.0.

Recommended order

1. Snapshot cached definition options at registration #101 — snapshot cached definitions; highest-priority correctness and cache-identity fix.
2. Fail remote invalidation when Redis is not configured #98 — reject explicit remote invalidation when Redis is absent; cover batch invalidation too if PR feat: add cluster-aware batch invalidation #114 lands first.
3. Review feat: add cluster-aware batch invalidation #114; it is the ready current-main implementation for Add batched remote invalidation with cluster-aware adapter routing #46.
4. Keep Add opt-in Redis Pub/Sub coherence for tracked process-local caching #106 and feat: coordinate process-local invalidation #107 open for now; before implementation resumes, rebase and reconcile the design with current main.
5. Validate cache-key shapes before canonicalization #97 and Preserve payload-error identity across CommonJS package subpaths #99 — runtime key validation and CommonJS error identity.
6. Rationalize the root export surface and scope-method vocabulary #24 — make the explicit pre-v1 public-surface decisions; reconcile or close stale draft PR docs: focus README on safe cache rollouts #89.
7. Add a repeatable performance and scale benchmark suite #35, then Characterize and guard watermark cardinality and Redis Cluster hot slots #42 — comparable measurement before scale controls.
8. Make Valkey GLIDE script-handle cleanup exception-safe #100 after PR feat: add cluster-aware batch invalidation #114 is merged or rejected.
9. Establish a local-hit performance budget and remove avoidable hot-path work #43 only after current profiling through Add a repeatable performance and scale benchmark suite #35.
10. Keep the remaining design work 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 observer isolation, later completed for returned promises in Consume rejected promises from logger and metrics adapters #103

P1 — High — 3 open

• Snapshot cached definition options at registration #101 — snapshot cached definitions at registration
• Fail remote invalidation when Redis is not configured #98 — fail explicit remote invalidation without Redis
• Add opt-in Redis Pub/Sub coherence for tracked process-local caching #106 — optional Pub/Sub coherence for tracked process-local caching; strategy decision pending

Recently resolved P1: #102 and #103.

P2 — Medium — 7 open

• Rationalize the root export surface and scope-method vocabulary #24 — pre-v1 root exports and scope vocabulary
• 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 — watermark cardinality and Redis Cluster hot slots
• Validate cache-key shapes before canonicalization #97 — validate runtime cache-key shapes
• Preserve payload-error identity across CommonJS package subpaths #99 — preserve CommonJS payload-error identity
• Add opt-in stale-on-error recovery from retained Redis values #117 — opt-in stale-on-error design; implementation decisions still pending

Recently resolved P2: #33, #104, and #110.

P3 — Low / demand-driven — 5 open

• Characterize and improve cached() callable-shape typing #22 — callable-shape typing characterization
• Recover safely from corrupt tracked watermark state #31 — corrupt-watermark operational docs and edge-case tests
• Establish a local-hit performance budget and remove avoidable hot-path work #43 — measured local-hit optimization
• Add batched remote invalidation with cluster-aware adapter routing #46 — batch remote invalidation; ready implementation in PR feat: add cluster-aware batch invalidation #114
• Make Valkey GLIDE script-handle cleanup exception-safe #100 — exception-safe GLIDE script-handle cleanup

Closed as not planned on 2026-08-01: #7, #21, #25, #37, and #60.

Grooming decisions recorded on 2026-08-01

Closed as not planned; reopen on concrete demand/evidence:

• Design optional cross-process cache stampede protection #7 — no measured production stampede pressure justified distributed coordination complexity.
• Design a first-class typed cache-definition handle #21 — no concrete consumer requires a second typed definition-handle vocabulary.
• Add request-boundary helpers and missing-scope diagnostics #25 — the concrete request-boundary gap is already covered; only speculative diagnostics/integrations remained.
• Benchmark lower-copy Redis protocol alternatives for large payloads #37 — generic protocol research lacked a workload trigger and overlapped Add opt-in stale-on-error recovery from retained Redis values #117's concrete header-first work.
• Add thresholded client-side compression for Redis payloads #60 — custom serializers already provide application-owned compression without first-party API or dependency growth.

Kept open:

• Add opt-in Redis Pub/Sub coherence for tracked process-local caching #106 and feat: coordinate process-local invalidation #107 remain open for now. This preserves the option; it does not approve the conflicting pre-v0.14.0 implementation. Any resumed work requires rebase, design reconciliation, and fresh correctness review.
• Recover safely from corrupt tracked watermark state #31 — retain the small safety runbook and edge-case test scope.
• Make zero local capacity consistent and evaluate byte-aware limits #40 — retain the zero-capacity inconsistency; byte-aware weighting remains evidence-gated.
• Characterize and improve cached() callable-shape typing #22 — retain as pre-v1 type characterization.
• Add opt-in stale-on-error recovery from retained Redis values #117 — retain as a decision-gated availability design, not an approved implementation.

Close after merge:

• Add batched remote invalidation with cluster-aware adapter routing #46 should close when feat: add cluster-aware batch invalidation #114 merges; do not close it while the implementation remains unmerged.

Live pull-request state

#114

• Implements Add batched remote invalidation with cluster-aware adapter routing #46.
• Head c8869e464a6b7accc8575e46f1d18eb3a0eb02ba is based on current v0.14.0 main.
• Open, non-draft, mergeable, and green; blocked only on required review/protection.
• It does not fix Fail remote invalidation when Redis is not configured #98 or Make Valkey GLIDE script-handle cleanup exception-safe #100.

#107

• Implements Add opt-in Redis Pub/Sub coherence for tracked process-local caching #106.
• Head ff1b70c predates v0.14.0.
• Open draft and conflicting; old green checks are not current validation.
• The at-most-once Pub/Sub design cannot guarantee peer coherence after undetected event loss.

#89

• Documentation-only README/reference-guide rewrite related to Rationalize the root export surface and scope-method vocabulary #24.
• Head 8bb7309 is open draft and conflicting with v0.14.0.
• It remains useful material but must be reconciled with current shadow configuration/logging; it does not resolve Rationalize the root export surface and scope-method vocabulary #24.

Dependencies and boundaries

• Snapshot cached definition options at registration #101 is internal correctness work and must not wait for speculative definition-handle Design a first-class typed cache-definition handle #21.
• Fail remote invalidation when Redis is not configured #98 should cover both scalar invalidation and PR feat: add cluster-aware batch invalidation #114's batch method if that method lands first.
• 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.
• Make Valkey GLIDE script-handle cleanup exception-safe #100 should follow the final adapter shape after PR feat: add cluster-aware batch invalidation #114.
• Add opt-in stale-on-error recovery from retained Redis values #117 increases Redis CPU, read traffic during source failures, and value/watermark residency; its final protocol must be benchmarked through Add a repeatable performance and scale benchmark suite #35.
• 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.

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.
• Cache plumbing fails open to the source of truth; explicit maintenance operations fail loudly.
• 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.