docs(service-cluster-redis): record the measured ioredis 5-vs-6 gap in the contract test header, and drop a promised live-Redis path that never existed

The contract test runs `ioredis-mock@8.13.1` (peer `ioredis: ^5`) against a
package depending on `ioredis@^6`, with the untyped import suppressed by
`@ts-expect-error`. This commit changes no code and no dependency: it writes
down the measurement that was missing, so the next reader starts where this
one finished.

Measured against ioredis 5.11.1 (newest release satisfying the mock's `^5`
peer) and 6.0.0 (the version resolved in this workspace):

  - all 14 Redis commands this package issues carry every v5 overload verbatim
    into v6's RedisCommander.d.ts; `set` is a strict superset there (v6 adds
    IFEQ/IFNE/IFDEQ/IFDNE), and nothing used here was removed or re-shaped
  - v6's RESP3 reply mapping is opt-in: the class defaults its ReplyMapping
    parameter to "legacy", ChainableCommander defaults to "resp2", and
    duplicate() with no override inherits the caller's mapping. This package
    never passes replyMapping, so every reply shape it sees is the v5 one
  - the three RedisOptions keys client.ts sets (lazyConnect,
    maxRetriesPerRequest, enableAutoPipelining) are declared identically

The peer mismatch is therefore real but inert on the surface these suites
drive. The header now says so, names the version pair the claim rests on, and
states that the claim expires if either range in package.json moves.

Also recorded: these suites reach the mock only through the injected client
and the pub/sub duplicate, never through createRedisClient(), so
`new Redis(url, options)` — this package's only contact with ioredis's
constructor and connection surface, and the area v6 changed most — is
exercised by nothing in this file. That is why the gap is inert here, and it
is not a reason to trust the double.

The header additionally promised `RUN_REAL_REDIS=1` + `REDIS_URL` and
"conditional describe.skipIf blocks at the bottom". No such blocks exist, and
both names occurred nowhere in the package outside that one sentence. The
false promise is removed rather than left standing as an escape hatch nobody
can take.

The `@ts-expect-error` stays. Removing it fails typecheck with TS7016 —
ioredis-mock ships no `types` field and no .d.ts of its own — so the
suppression has not rotted. Its comment now also records what it costs: with
the module untyped the client is `any` and satisfies ioredis's Redis type
without being checked against it, which is the second reason a v5-vs-v6
divergence could not surface here. `@types/ioredis-mock` would type the seam
but only asserts `new(): ioredis.Redis` rather than describing the mock, so
adopting it would trade an honest `any` for an unearned certainty; that trade
is left to a maintainer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Author: claude

packages/services/service-cluster-redis/src/redis.contract.test.ts

@@ -3,12 +3,67 @@
 /**
  * Driver contract tests for the Redis cluster driver, run against
  * `ioredis-mock` so they execute without a real Redis instance in CI.
+ * There is no live-Redis path in this file: every suite below runs on the
+ * mock. (An earlier version of this header promised `RUN_REAL_REDIS=1` +
+ * `REDIS_URL` and "conditional `describe.skipIf` blocks at the bottom" —
+ * no such blocks were ever here, and the two names appeared nowhere in
+ * this package outside that sentence.)
  *
- * The same suites can be invoked against a live Redis by setting
- * `RUN_REAL_REDIS=1` and providing `REDIS_URL` — see the conditional
- * `describe.skipIf` blocks at the bottom.
+ * ## The double is one major version behind the client it doubles
+ *
+ * This package depends on `ioredis@^6`, while `ioredis-mock@8.13.1`
+ * declares `peerDependencies: { ioredis: "^5" }` — so `pnpm install`
+ * prints an unmet-peer warning for it. That gap is real, and it is
+ * declared here rather than closed, because it was measured to be inert
+ * on the surface these suites actually drive. Measured against ioredis
+ * 5.11.1 (newest release satisfying the mock's `^5` peer) and 6.0.0 (the
+ * version resolved in this workspace):
+ *
+ *   - Every Redis command issued by this package's `src/*.ts` — get, set,
+ *     del, incr, incrby, pttl, watch, unwatch, multi, exec, publish,
+ *     subscribe, unsubscribe, quit, eval — carries all of its v5
+ *     overloads verbatim into v6's `RedisCommander.d.ts`. `set` is a
+ *     strict superset there (v6 adds the IFEQ/IFNE/IFDEQ/IFDNE tokens);
+ *     nothing used here was removed or re-shaped.
+ *   - v6's one substantive change reachable from this package is RESP3
+ *     reply mapping, and it is opt-in: the class is declared with a
+ *     `ReplyMapping` parameter defaulting to "legacy", `ChainableCommander`
+ *     defaults to "resp2", and `duplicate()` with no override inherits the
+ *     caller's mapping. This package never passes `replyMapping`, so every
+ *     reply shape it sees is still the v5 one.
+ *   - The three `RedisOptions` keys client.ts sets — lazyConnect,
+ *     maxRetriesPerRequest, enableAutoPipelining — are declared
+ *     identically in both versions.
+ *
+ * That named set is the whole basis for the claim; it is not a statement
+ * about ioredis 5 vs 6 in general. If the `ioredis` or `ioredis-mock`
+ * range in package.json moves, this paragraph expires and the diff has to
+ * be re-taken.
+ *
+ * ## What these suites therefore do NOT certify
+ *
+ * They reach the mock only through the injected `client` and the
+ * `client.duplicate()` the pub/sub adapter makes. They never call
+ * `createRedisClient()`, so `new Redis(url, options)` — this package's
+ * only contact with ioredis's constructor and connection surface, and the
+ * area v6 changed most — is exercised by nothing in this file. That is
+ * why the version gap is inert here, and it is not a reason to trust the
+ * double: the mock is simply never asked to stand in for the surface on
+ * which the two majors differ.
  */
 
+// `ioredis-mock` publishes no type declarations of its own — no `types`
+// field in its manifest and no `.d.ts` in the tarball — so this import
+// raises TS7016 ("could not find a declaration file ... implicitly has an
+// 'any' type") and the directive below is what silences it. Note the
+// second cost, beyond the missing types: with the module untyped
+// `RedisMock` is `any`, so every `client:` argument constructed from it
+// satisfies ioredis's `Redis` type without ever being checked against it.
+// That is the other reason a v5-vs-v6 divergence could not surface here.
+// `@types/ioredis-mock` exists and would type this seam, but it only
+// *asserts* `new(): ioredis.Redis` rather than describing the mock, so
+// adopting it would trade an honest `any` for an unearned certainty —
+// that trade has not been made, deliberately.
 // @ts-expect-error — ioredis-mock has no published types
 import RedisMock from 'ioredis-mock';
 import { describe, expect, it, vi } from 'vitest';