The ioredis-mock inertness declaration expires if either dependency range moves, and nothing defends it — pin the version pair it names

[os-warren]

What needs defending

PR #15985 (card #15467) resolves the ioredis-mock@8 (peer ioredis@^5) versus ioredis@^6 mismatch by measuring it and declaring it inert — comments only, no code, dependency or CI change. The measurement is good and the route was the one triage named for that outcome.

⚠️ But the whole deliverable is a claim in a comment, and the claim has an expiry condition it states itself: it holds for the pair ioredis 5.11.1 / 6.0.0 and stops holding if either range moves. Nothing checks that. ⇒ A dependency bump six months from now silently invalidates a header that will still read as authoritative.

Why this is worth a card rather than trust

This repository keeps rediscovering the same defect class, three separate times today alone:

• a header promising RUN_REAL_REDIS=1 + REDIS_URL and "conditional describe.skipIf blocks at the bottom" — no such blocks existed, and neither name occurred anywhere else in the package (removed by that same PR);
• eval-user.zod.ts documenting createEvalUser as "the single factory every surface uses (server buildScope, the customSession bridge, …)" — measured, there is no customSession bridge, and that non-existent producer is exactly the gap card action.visible 的 current_user.positions 装的是 auth 角色而非安全层岗位,按岗位收敛的按钮对所有人静默消失(17.2.0) #15136 fell through;
• resolve-authz-context.ts:1125-1129's ⛔ "never positions.includes(...)" — a comment, not a gate, which did not stop a privilege escalation from being written twice (fix(plugin-auth)!: session payload positions[] is the security axis, not the better-auth role scalar #15948 round 1, and the four pre-existing readers in Four server-side readers derive platform authority from the NAME in ExecutionContext.positions — same species as #15948's blocked escalation, and already reachable on main #15981).

⭐ In every one, the prose was correct when written and rotted without a signal. That is the shape here.

Suggested shape, ⛔ not prescribed

A pin asserting the two dependency ranges still match the pair the new header names — so the declaration reddens when it stops being true, instead of being quietly wrong.

⚠️ This is a policy call, which is why it is filed rather than folded in. It reddens on every bump of either dependency, and whether that is a feature or a nuisance is a judgement:

• For: the bump is exactly the moment the claim needs re-measuring, and a red pin puts the header in front of whoever is bumping — the only person positioned to re-check it.
• Against: it is new verification surface nobody asked for, and a pin that fires on routine maintenance trains people to edit the pin rather than re-do the measurement, which would be worse than no pin.

⇒ A middle option worth considering: pin the conclusion rather than the versions — re-derive the overload intersection in CI — which does not fire on a bump that changes nothing. ⚠️ More expensive, and it needs both packages' type declarations resolvable in that environment.

What a taker should NOT do

⛔ Do not "fix" this by adopting @types/ioredis-mock and dropping the @ts-expect-error. That was measured and deliberately rejected on #15467: those types declare the mock constructor as returning a real ioredis Redis, so they assert conformance instead of verifying it — trading a visible any for an unearned certainty TypeScript would then vouch for. ⭐ That is the same failure mode this whole family is about, one layer up.

⛔ Do not re-litigate the inertness measurement itself; it is on PR #15985 with its controls, and the ablation there shows the suppression has not rotted (removing it yields TS7016 … implicitly has an any type).

Related

• service-cluster-redis's contract test runs ioredis-mock@8 (peer ioredis@^5) against a package that depends on ioredis@^6, with the import seam suppressed by @ts-expect-error #15467 / PR docs(service-cluster-redis): record the measured ioredis 5-vs-6 gap in the contract test header, and drop a live-Redis path that never existed #15985 — the measurement and the declaration this card would defend.
• [finding] service-cluster-redis's KV contract suite never exercises the WATCH/MULTI abort-retry path nor the versioned-delete MULTI branch — measured by instrumenting the shipped test #15983 — from the same instrumentation run: RedisKV.delete's versioned branch is unexercised, so the optimistic-concurrency claim in its header has zero assertions behind it. Same package, same species — a claim with nothing checking it.

[os-warren]

Scope widened before anyone takes it — a range-only pin would not catch the move that matters most

From the Clause-② review of PR #15985, which measured this while checking the declaration this card exists to defend:

⚠️ The claim can expire without any range moving. The header's expiry clause is written in terms of the dependency ranges, but the resolved version can move under an unchanged range — a lockfile-only bump. ⇒ A pin that asserts "the two ranges still read ^6.0.0 and ^8.13.1" would stay green through exactly the change that invalidates the measurement.

So whatever shape this lands in has to key on the resolved pair (ioredis 5.11.1 / 6.0.0 as measured), not on the declared ranges — or on the derived conclusion, which is the middle option this card already carries.

⭐ That makes the "pin the conclusion rather than the versions" option better than it looked when I filed this. Re-deriving the overload intersection in CI is immune to how the version moved — range, lockfile, or transitive — because it measures the thing the claim is actually about. The cost stated on this card still applies (more expensive, needs both packages' type declarations resolvable in that environment), but the cheap alternative just got cheaper-looking and less correct.

One more fact for whoever takes it

The review established that @types/ioredis-mock is present in the store but sits on no @types directory tsc walks. ⇒ The rejected option B was never as close to free as it appeared — adopting it would have needed a typeRoots or types change too, which is a wider edit than "add a devDependency". ⛔ Still not a reason to revisit B; recorded so nobody re-derives it and reaches a different conclusion about its cost.

---

Generated by Claude Code