Track DialCache deep-review follow-up work

[lan17]

Priority

META — Tracking — umbrella only; not implementation work.

Current baseline

This tracker began with the deep API, performance, scalability, and correctness review of main@2bda04d1443a75a71cbbc41365c4424554936a37.

It is now reconciled against:

• main@34a45facfc4cb11ca7c08d5506e74b3dbcef4dd2
• GitHub release https://github.com/lan17/DialCache/releases/tag/v0.6.0
• npm dialcache@0.6.0
• passing post-merge CI https://github.com/lan17/DialCache/actions/runs/29709940733
• passing release run https://github.com/lan17/DialCache/actions/runs/29709966868

Forty implementation issues are tracked: 21 resolved and 19 open. Every P0 is resolved. The open backlog contains 4 P1, 8 P2, and 7 P3 issues after downgrading the speculative definition-handle work in #21 from P2 to P3.

Confirmed behavior and architecture decisions are recorded in their individual issues. Open decisions still require maintainer approval before implementation.

Recommended order

1. Resolve the remaining public-API question in https://github.com/lan17/DialCache/pull/68—whether to remove or retain deprecated MissingKeyConfigError—then finish Overlay runtime cache configuration on documented defaults #23. The PR is otherwise ready for review at 4c5d516fc71e529723bbde9cdbd84786b3b4fc8d, with passing CI https://github.com/lan17/DialCache/actions/runs/29710409148.
2. Approve and implement the narrow outage fix in Prevent Redis outages from amplifying latency, source load, and logs #38: after a Redis read exception, run fallback but skip the second Redis write.
3. Resolve Align runtime support after Node 20 EOL #34 by selecting the maintained Node runtime floor. The current recommendation is Node 22+.
4. Measure the workload gates in Characterize and guard watermark cardinality and Redis Cluster hot slots #42: distinct tracked-ID rate, watermark lifetime, and hottest-ID QPS.
5. Confirm the narrow correctness contracts in Recover safely from corrupt tracked watermark state #31 and Validate TTL and invalidation duration arithmetic consistently #33.
6. Build the comparable harness in Add a repeatable performance and scale benchmark suite #35 before the measured hot-path work in Establish a local-hit performance budget and remove avoidable hot-path work #43.
7. Resolve zero-capacity semantics in Make zero local capacity consistent and evaluate byte-aware limits #40.
8. Implement the approved additive getOrLoad() API in Add an ergonomic getOrLoad() API for inline cache blocks #71 when API ergonomics becomes the focus.
9. Keep P3 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 — shipped one explicit namespace across keys and metrics
• Require explicit serializers for statically non-JSON cached values #16 — shipped the 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 — shipped the 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 is shared-Redis-only
• Make logger failures unable to change cache behavior #29 — shipped non-throwing logger isolation

P1 — High

• Document the immutable cached-value ownership contract #18 — closed not planned; immutable/reference-sharing ownership is documented
• Require caller-owned Redis clients and remove the lazy factory #20 — caller-owned Redis clients shipped through feat: require caller-owned Redis clients #67
• Validate exact Lua reply domains in bundled Redis adapters #30 — exact Lua reply-domain validation shipped
• Document the synchronized Redis clock assumption for tracked invalidation #32 — synchronized Redis clock infrastructure contract shipped
• Add configurable serialized-payload limits with fail-open oversize behavior #36 — closed not planned; hard payload ceilings remain application-owned
• Require finite single-flight lifetimes and expose observability #41 — fallback deadlines and coalescing state shipped through feat: add fallback deadlines and coalescing state #69
• Bound metrics error labels with a backend-neutral taxonomy #45 — bounded backend-neutral error taxonomy shipped
• Overlay runtime cache configuration on documented defaults #23 — sparse runtime-config overlay; implementation open in feat: overlay runtime cache configuration on defaults #68
• Align runtime support after Node 20 EOL #34 — align the maintained Node runtime floor
• Prevent Redis outages from amplifying latency, source load, and logs #38 — avoid a second Redis operation after a failed read
• Characterize and guard watermark cardinality and Redis Cluster hot slots #42 — characterize watermark cardinality and cluster hot IDs

P2 — Medium

• Make DialCacheConfig modes discriminated and explicit #19 — constructor modes simplified by metrics/client ownership work
• Add Redis write-path and end-to-end cache outcome telemetry #44 — closed not planned; broad Redis write/client telemetry is not planned
• Add a runtime-controlled request-local cache layer #51 — runtime-controlled request-local cache shipped
• Decouple core observability from Prometheus #53 — Prometheus decoupling shipped
• Add a first-party Datadog DogStatsD metrics adapter #54 — first-party Datadog adapter shipped
• Rationalize the root export surface and scope-method vocabulary #24 — finish root exports and scope-method vocabulary before v1
• Recover safely from corrupt tracked watermark state #31 — document/test corrupt-watermark recovery
• Validate TTL and invalidation duration arithmetic consistently #33 — define safe duration arithmetic
• Add a repeatable performance and scale benchmark suite #35 — comparable performance/scale harness
• Keep runtime configuration lookup cheap and bounded #39 — internal no-custom-provider fast path
• Make zero local capacity consistent and evaluate byte-aware limits #40 — resolve zero-capacity semantics; defer byte weighting
• Establish a local-hit performance budget and remove avoidable hot-path work #43 — establish and optimize against a local-hit budget
• Add an ergonomic getOrLoad() API for inline cache blocks #71 — approved additive getOrLoad() API

P3 — Low / demand-driven

• Design optional cross-process cache stampede protection #7 — optional cross-process stampede mitigation
• Design a first-class typed cache-definition handle #21 — reconsider a typed definition handle only with concrete demand
• 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 or framework integration
• Benchmark lower-copy Redis protocol alternatives for large payloads #37 — lower-copy Redis protocol research
• Design batch reads and invalidations without one Redis script per key #46 — batch API/protocol design
• Add thresholded client-side compression for Redis payloads #60 — thresholded client-side compression, deliberately punted

Open decisions to batch-confirm

• Overlay runtime cache configuration on documented defaults #23 — remove MissingKeyConfigError now, or retain its deprecated export?
• Recover safely from corrupt tracked watermark state #31 — use explicit invalidateRemote() as the sole corrupt-watermark repair path, with no automatic repair subsystem or dedicated API/metric?
• Validate TTL and invalidation duration arithmetic consistently #33 — exact maximum TTL/buffer values and registration-versus-runtime rejection timing.
• Align runtime support after Node 20 EOL #34 — Node 22+ or deliberate EOL Node 20 support.
• Prevent Redis outages from amplifying latency, source load, and logs #38 — approve skipping the second Redis operation after a read exception.
• Keep runtime configuration lookup cheap and bounded #39 — approve only the internal static-provider fast path; keep dynamic-provider memoization/deadlines application-owned.
• Make zero local capacity consistent and evaluate byte-aware limits #40 — does localMaxSize: 0 disable storage only, or make the process-local layer absent for policy/metrics/coalescing?
• Design a first-class typed cache-definition handle #21 — revisit the previously rejected handle API, or eventually close not planned?
• Add request-boundary helpers and missing-scope diagnostics #25 — are docs plus bounded context metrics sufficient?
• Design batch reads and invalidations without one Redis script per key #46 — is there a real batch workload worth retaining this design task for?

Dependency notes

• Require finite single-flight lifetimes and expose observability #41 is complete. Fallback execution is bounded by default, but Redis and other injected async-boundary deadlines remain application-owned under Prevent Redis outages from amplifying latency, source load, and logs #38.
• feat: overlay runtime cache configuration on defaults #68 implements Overlay runtime cache configuration on documented defaults #23 and partially improves Validate TTL and invalidation duration arithmetic consistently #33 through registration-time static validation. It intentionally preserves one provider resolution per enabled invocation, so Keep runtime configuration lookup cheap and bounded #39 remains separate.
• 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 work on Add thresholded client-side compression for Redis payloads #60.
• Add an ergonomic getOrLoad() API for inline cache blocks #71 is a one-shot inline operation and is separate from the speculative definition handle in Design a first-class typed cache-definition handle #21.
• Bound metrics error labels with a backend-neutral taxonomy #45's bounded error taxonomy is complete; future telemetry must preserve that contract.
• Add thresholded client-side compression for Redis payloads #60 remains punted. If resumed, compression must keep Redis opaque and preserve Require finite single-flight lifetimes and expose observability #41's finite serializer-settlement boundary.
• Add an ergonomic getOrLoad() API for inline cache blocks #70 is a closed duplicate of canonical Add an ergonomic getOrLoad() API for inline cache blocks #71 and is not counted.

Completion standard

• Focused unit/integration/type coverage for the actual failure mode.
• Breaking changes include migration and mixed-version/rollback notes.
• Performance work reports reproducible before/after evidence.
• No open design is implemented until its decision is 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.