feat(metrics)!: classify cache misses by reason

[lan17]

Summary

Implements #145 and replaces the closed, stale attempt at #130.

• Adds one required bounded reason to the existing miss event: value_absent, watermark_fenced, or unclassified.
• Preserves read cause independently from a valid observed watermark, so an absent value may still fence a refill without being mislabeled as watermark_fenced.
• Updates Node Redis, Valkey GLIDE, Prometheus, Datadog, custom-adapter guidance, and packed package consumers without adding Redis commands or a second miss metric.

Design

Bundled decoders return classified semantic misses. A genuine tracked frame-versus-watermark rejection is watermark_fenced; Redis nil is value_absent; malformed metadata, client-side future/invalid timestamps, serializer-load failure, and legacy custom null reads are unclassified. Core validates custom typed results so watermark_fenced requires a valid tracked observed watermark.

Prometheus keeps dialcache_miss_counter and adds its fifth reason label. Datadog keeps dialcache.miss.count and adds the same reason tag. Migration notes cover same-registry incompatibility, mixed-fleet PromQL aggregation, Datadog cardinality, and custom metric adapters.

Dependency

This is deliberately stacked on #143, which introduces the observed-refill-fence result model this change classifies. After that PR merges, retarget or rebase this PR onto main before merge.

Breaking change

BREAKING CHANGE: DialCacheMetricsAdapter.miss now receives MissMetricLabels, and first-party miss metrics require the reason label or tag. Under the pre-1.0 release policy, this is a minor release.

Validation

• corepack pnpm check
• corepack pnpm test:integration
• Fresh semantic review of source/API boundaries and custom-adapter normalization