feat(redis): simplify tracked writes with client clocks

[lan17]

Summary

Finish the client-clock simplification on top of main:

• every tracked and untracked Redis value write is one native SET containing a complete frame-v1 value stamped once with writer Date.now();
• tracked writes never read, create, or extend watermarks;
• tracked Redis value TTLs are capped at one hour, while invalidation-owned watermarks live for at least two hours and long enough to outlive the future fence;
• tracked reads retain the primary-routed atomic MGET(value, watermark), with a missing watermark treated as zero; and
• invalidation is the only remaining Lua operation. Redis TIME is unused.

This PR contains no rollout gate. Old and new tracked protocols are gated and drained externally rather than allowed to coexist.

Why

The previous tracked write paired a placeholder SET with a Lua stamp that read Redis server time. Same-clock fencing was exact, but the write path carried two commands, per-write Lua, placeholder/nonce pairing state, and a split-pair failure mode: a sustained stamp failure (a denied command, a proxy rejecting EVALSHA) still landed every paired SET, replacing readable values with unreadable placeholders and shifting full tracked traffic to the source within one TTL horizon. This PR trades exact server-clock fencing for a documented client-clock buffer: every write is one atomic native SET that either lands servable or does not exist, and the placeholder, nonce, stamp-reply, and script-recovery machinery is deleted. The cost is stated rather than hidden — invalidation correctness now depends on the futureBufferMs sizing and watermark durability requirements below.

Architecture

Path	Result
Untracked read	Native GET; createdAtMs is informational and does not gate serving
Tracked read	Primary atomic MGET(value, watermark); serving and initial-shadow reads require createdAtMs > watermark and not future-dated
Any Redis value write	One complete-frame SET PX, stamped once by the adapter
Invalidation	Monotonic Lua with one stable invalidator timestamp reused across retries

A malformed string watermark misses. Native MGET returns nil for a wrong-type member, so a wrong-type watermark has the same read behavior as an absent one. The next explicit invalidation repairs a wrong-type watermark; other script read errors surface and cannot bypass the monotonic update.

The value envelope, timestamp field, Redis key derivation, watermark key/value encoding, and tracked primary-read routing are unchanged.

Correctness

This is a read-time invalidation fence. A write behind an active watermark may be stored, but it remains a tracked miss. A tracked invocation that reaches the Redis path does not publish its fallback directly to process-local cache; a later validated Redis hit may warm it. Local-only, remote-policy-disabled, and ramped-down paths retain their existing local-cache behavior.

Production invalidation requires:

futureBufferMs >= Dmax + S + M

• Dmax: maximum elapsed time from invalidation sampling until a stale pre-mutation SET can become visible in Redis, including source visibility, fallback, serialization, bounded client queue/reconnect delay, network transit, and Redis execution;
• S: maximum writer-clock lead over the invalidator; and
• M: operational margin.

For example: fills visible within 2 s, fleet clock skew at most 1 s, and a 1 s margin call for futureBufferMs ≈ 4000.

An unbounded offline queue or retry path makes a finite Dmax impossible. Future-dated tracked frames fail closed on serving and initial-shadow reads and emit the optional future-timestamp-offset observation. Confirmation reads observe but retain the frame for payload comparison; untracked reads do not gate serving on the informational timestamp.

Only invalidation maintains watermarks. Their TTL is:

max(existing TTL, 2 hours, watermark - invalidatedAtMs + 1 hour + 1 minute)

Persistent watermarks remain persistent. Each dispatched tracked write whose configured TTL is capped emits error="tracked_ttl_clamped" and attempts the write with the capped TTL. Losing a watermark removes its read-time fence, so production must use noeviction or an equivalent guarantee and alert on memory pressure, rejected writes, and evictions. Watermark loss also includes async-replication failover — a promoted replica may lack the newest watermark — so choose replication and failover guarantees accordingly; DialCache does not issue WAIT.

Performance and simplification

The tracked write path drops from SET + stamp Lua to one SET:

• one command/reply instead of two;
• no placeholder, nonce, stamp reply state, write batch, transaction, write-side Lua, or stamp script-cache recovery;
• payload bytes still cross the network once; and
• less fixed client, Redis, replication, and AOF work at high write rates.

The maintained live benchmark exercised 6,750 sequential writes across 100 B, 10 KiB, 100 KiB, and 1 MiB payloads. Every size produced exactly 1.0 SET/op, 0.0 script/op, and 0.0 TIME/op. Absolute latency remains environment-dependent; the benchmark validates command shape and sequential latency, not saturated throughput.

Tracked reads intentionally remain MGET(value, watermark): correctness needs an atomic primary snapshot, and invalidated misses still transfer the full payload before Node applies the fence. Standalone GLIDE retains its one-command Batch so tracked reads cannot follow a replica-read preference.

Compatibility and rollout

Wire formats remain compatible, but old tracked state is not safe to carry across the protocol transition because old watermark lifetimes were derived for the old writer.

Before enabling this release for a namespace:

1. Stop and drain every old writer and invalidator, including fallbacks, shadow work, Redis client queues, and other in-flight operations that can still write tracked state.
2. Purge every tracked value, complete or placeholder, and every watermark in the affected namespace. A full namespace flush is simplest when Redis is dedicated; untracked complete values may remain.
3. Enable the new release only after the purge completes.

Waiting for natural expiry is safe only with all traffic disabled, bounded remaining TTLs for both tracked values and watermarks, no persistent watermark, and a wait covering the old value and future-buffer-derived watermark lifetimes.

Source compatibility changes:

• DialCacheRedisClient.write() returns void, and RedisWriteRequest no longer accepts watermarkKey;
• placeholder/stamp protocol exports and DialCacheRedisPlaceholderLostError are removed;
• dialcacheRedisScripts and DialCacheNodeRedisScripts are removed; ordinary node-redis clients require no DialCache script registration;
• ValkeyGlideRuntime no longer requires ClusterBatch;
• fill_blocked is removed from ShadowValidationOutcome;
• tracked_ttl_clamped is added to MetricErrorKind, so exhaustive switches and Record<MetricErrorKind, ...> values must add it; and
• the Prometheus future-timestamp histogram uses a new skew-oriented bucket schema, which is incompatible with a same-name collector registered with the former default buckets.

Validation

• corepack pnpm check: typecheck, 529 unit tests with coverage, ESM/CJS build, and packed-consumer tests
• corepack pnpm test:integration: 125 passed, 0 skipped, across Redis 6.2 and Valkey 8 with node-redis and GLIDE, including the GLIDE Cluster suite
• live Redis write benchmark: 6,750 writes, one SET and zero Lua/TIME calls per operation through 1 MiB
• independent multi-pass adversarial review (10 finder angles, verification, gap sweep) produced 15 findings — 2 corruption-class correctness, 1 shadow-telemetry, 2 doc-contract, plus operability and cleanup items; 14 applied in 8068f46, 1 simplification declined (timestamp assert kept as defense in depth)
• refreshed origin/main: branch remains based directly on main

Closes #139

BREAKING CHANGE: DialCacheRedisClient.write() now returns void and RedisWriteRequest no longer accepts watermarkKey. The placeholder/stamp protocol and related exports, dialcacheRedisScripts/DialCacheNodeRedisScripts registration facade, ValkeyGlideRuntime.ClusterBatch requirement, and fill_blocked outcome are removed; MetricErrorKind adds tracked_ttl_clamped; and the Prometheus future-timestamp histogram bucket schema changes. Node-redis clients should be created without DialCache script registration.

[lan17]

Deep review of the client-clock protocol (10 finder angles + adversarial verification + gap sweep; tsc and the 519-test unit suite pass locally). The core protocol verified sound: invalidation math, fence coverage on every read path, adapter dispatch against real node-redis/GLIDE semantics, cluster routing, retry idempotency, migration steps, and benchmark claims. Inline comments below; the corrupt-watermark hardening items (wrong-type key, >2^53 numeric parse) are tracked separately.

[lan17]

Follow-up to the review discussion: concrete fix suggestions for the corrupt-watermark hardening items (strict shared integer grammar with a MAX_SAFE cap, and WRONGTYPE self-heal). All three are small and independent; together they make every corruption class route to the script's existing repair path.

[lan17]

Two follow-ups from a coverage pass over the final head (97.6% statements / 95% branches; unit 528 + integration 125/125 green locally): inline below. One process question rather than a code comment: does test:integration gate PRs in CI, or is it a manual step? The wrong-type-watermark and persistent-watermark behaviors are covered only there — FakeRedis structurally cannot represent either state — so the unit tier is blind to regressions in those two safety paths if integration is manual-only. The remaining uncovered lines are pre-existing convenience paths (local-cache.ts get/put-without-config, RedisCache.getResult's disabled-layer return) and constructor validation branches — reviewed, fine to leave.

[lan17]

On the integration-gating question: yes. The PR-triggered CI workflow runs pnpm test:integration inside the test job, and the active protect-main ruleset requires that test status with strict/up-to-date enforcement. The preceding head ran all 125 integration tests with zero CI skips across Redis 6.2/Valkey 8 and node-redis/GLIDE. Keeping WRONGTYPE and persistent-watermark behavior in real integration coverage rather than expanding FakeRedis is therefore merge-gated; the new head is running the same required job now.