feat: enforce runtime-configurable remote read deadlines

[lan17]

Summary

• add a finite 50 ms core default for every active remote Redis read
• support an optional instance default through RedisConfig.readTimeoutMs and per-use-case static/runtime policy through DialCacheKeyConfig.remoteReadTimeoutMs
• resolve timeout precedence per invocation: runtime provider → operation defaultConfig → instance Redis config → 50 ms
• enforce one monotonic deadline per shared Redis-read leader, consume late settlement, and provide adapters an optional cooperative AbortSignal
• fail open to the source after read errors/timeouts without attempting a second Redis operation
• preserve safe process-local publication for untracked keys while suppressing it for tracked keys when watermark safety was not established
• report timeouts through the existing error metric as cache_read_timeout; other read failures remain cache_read
• apply the same contract to cached() and getOrLoad()

Public API

new DialCache({
  redis: {
    client,
    readTimeoutMs: 100, // optional instance default; omission uses 50 ms
  },
  cacheConfigProvider: (key) =>
    key.useCase === "GetUser"
      ? new DialCacheKeyConfig({ remoteReadTimeoutMs: 25 })
      : null,
});

• RedisConfig.readTimeoutMs?: number
• DialCacheKeyConfig.remoteReadTimeoutMs?: number
• RedisReadContext { timeoutMs, signal } as the optional second argument to DialCacheRedisClient.read()
• exported RedisReadTimeoutError
• MetricErrorKind adds "cache_read_timeout"

There is no new option on CachedOptions; per-use-case policy stays in the existing runtime-config abstraction. Existing one-argument custom Redis clients remain structurally compatible.

Semantics

The deadline bounds caller wait and cache publication, not guaranteed server-side cancellation. Same-key followers share the active leader’s remaining budget. fallbackTimeoutMs starts separately only when the source loader begins. Writes, invalidations, serializers, config providers, and underlying client resource lifetime remain application-owned.

Explicit timeout values must be positive safe integers no greater than 2,147,483,647. An invalid runtime value is a config-resolution failure: the invocation runs the source uncached without attempting Redis.

Review loop

A three-reviewer discovery round covered correctness/concurrency, API/observability, and tests/package/performance. It found one P2: a custom client that synchronously exceeded the deadline and then threw was classified as cache_read instead of cache_read_timeout. Follow-up commit d32847b normalizes invocation through the monotonic promise path and adds paired over-deadline synchronous return/throw regressions.

The branch was also rebased onto main after PR #88 merged. A brand-new confirmation reviewer then inspected the complete rebased tree and returned no P0–P3 findings, explicitly verifying that the derived watermark-TTL behavior remains intact.

Validation

• corepack pnpm check — typecheck, 278 unit tests with 96.77% statement / 92.94% branch coverage, ESM/CJS build and declarations, packed-consumer checks
• corepack pnpm test:integration — 73 Redis 6.2, Valkey 8, and Redis Cluster cases
• corepack pnpm benchmark:request-local — six-scenario default matrix; 1,000 coalesced callers asserted one semantic Redis read and one deadline timer
• corepack pnpm audit --prod --audit-level high — no known production vulnerabilities
• git diff --check
• current main (615c31fef702ec141396413a6f16b4d6c78fa06a) is an ancestor of this head

Closes #38