@bymax-one/nest-cache 1.0.6 → 1.2.0

package/CHANGELOG.md

@@ -4,7 +4,119 @@ All notable changes to this project are documented in this file. The format is
 based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.2.0] - 2026-08-21
+
+### Security
+
+- **`validateOptions` now rejects a namespace containing a Redis glob metacharacter
+  (`*`, `?`, `[`, `\`).** The namespace is this library's isolation boundary and it was
+  composed unvalidated into `flushNamespace`'s destructive match pattern
+  (`{namespace}{separator}*`), so a metacharacter changed which keys `UNLINK` reached.
+  Measured against Redis 8.10.0, each one broke isolation differently: `*` and `?` **widen**
+  the pattern (namespace `ten*ant` matches every other tenant's keys, turning a scoped flush
+  into a cross-tenant delete); `\` **escapes** the next character (namespace `ten\ant`
+  matches `tenant:*` — a different keyspace — while sparing its own keys); and `[` opens a
+  character class that never closes, so the pattern matches **nothing** and `flushNamespace`
+  removes none of the namespace's keys while returning `0`, which reads as a successful flush.
+  Triggering it required a misconfigured namespace, so no default configuration was exposed;
+  the case to worry about is a namespace derived from input, such as multi-tenant wiring using
+  a tenant slug. `]` is deliberately still accepted — measured to be a literal that neither
+  widens nor silences the pattern.
+- An **empty `keySeparator`** now fails with its own message. It was already rejected, but by
+  coincidence: the next guard is `namespace.includes(separator)` and `'anything'.includes('')`
+  is `true` for every string, so it reported _"namespace contains key separator"_ — something
+  the consumer had not done.
+
+### Added
+
+- **New subpath `@bymax-one/nest-cache/admin`** — a privileged, read-only administration
+  surface: health, parsed `INFO` statistics, resolved configuration, keyspace listing, key
+  inspection and value reveal. Kept out of the main entry deliberately: importing it is a
+  greppable, reviewable act; a consumer who never wires it cannot resolve a reveal service
+  from DI by accident and does not pay for it in the main bundle.
+- `BymaxCacheAdminModule.forRoot()` / `.forRootAsync()`, `CacheStatusService`,
+  `CacheAdminService`, and the scope model (`CacheScope`, `validateScopes`, `findScope`,
+  `isKeyInScope`).
+- New error codes: `cache.invalid_scope`, `cache.scope_not_found`, `cache.scope_not_readable`,
+  `cache.key_not_in_scope`.
+- `ResolvedOptions` and `DEFAULT_REDIS_PORT` are now exported from the main entry. The former
+  is the shape stored under the already-exported `BYMAX_CACHE_OPTIONS` token, which previously
+  had no public type.
+- `pnpm check:admin-readonly` — a build gate that fails if the admin subpath declares a method
+  named after a mutating Redis command, sends a non-allowlisted command through the `call`
+  escape hatch, or imports `ioredis` as a value. Wired into `prepublishOnly`.
+
+### Administration surface — shapes chosen deliberately
+
+- **The application declares which keyspaces exist; the library validates and serves them.**
+  A cache library cannot know that another library writes at Redis root through
+  `getClient()`, and must not depend on that library to learn it.
+- **`isReadable: false` withholds the value only.** Listing, types, TTLs and sizes stay
+  available. A surface that renders an unreadable keyspace as empty tells an operator the
+  region holds nothing when it is full — the same defect as a blank log page during an outage.
+- **Scope patterns are restricted to a literal prefix with at most one trailing `*`.** A
+  caller names a key, so the library must decide whether that key belongs to the named scope.
+  Deciding that for arbitrary globs means reimplementing Redis's `stringmatchlen`, and a
+  matcher even slightly _more_ permissive than the server's is a silent cross-scope leak that
+  no happy-path test would show. With this shape, membership is exact by construction — and it
+  is checked differentially against a real server in the E2E suite.
+- **Health is three states and `latencyMs` cannot exist without a measurement.** The type is
+  a union, so a handler that caught a throwing ping and returned a confident status does not
+  compile. `mode` and `isScanSupported` sit outside the union: a cluster deployment that is
+  down should still report that scanning was never going to work.
+- **Every reading that would carry two meanings under one `null` is a union.**
+  `maxmemory` is `unbounded | limited | unreported` (Redis spells "no ceiling" as
+  `maxmemory:0`, which read literally draws a full saturation bar on the least constrained
+  server there is); `TTL` is `expiring | persistent | missing` (`-1` and `-2` are different
+  facts, and the key that expired mid-listing is the one an operator is watching);
+  `aofEnabled` is nullable, because `false` for an absent field is a durability claim made
+  without evidence.
+- **`connection.url` is never on the wire.** The config payload carries host, port and a TLS
+  flag; the URL and its password are never read into this subpath at all.
+- **Sampled figures are named `sampledCount` / `sampledBytes`.** They are sums over a capped
+  `SCAN`, not measurements of the keyspace. `isComplete` is the fact; the names are the guard,
+  because a caller reaching for one does not necessarily read the other.
+- **Pipeline batches are bounded in commands, not keys.** Redis is single-threaded, so a
+  pipeline converts a network cost into a server-blocking one — describing N keys is two or
+  three commands each, and one flush blocks every other client for the whole burst, on a
+  server someone is inspecting precisely because it is unwell. Sizing is opt-in for the same
+  reason.
+
+### Internal
+
+- Bundle-size budgets recalibrated: server `14.50` → `15.00` kB, admin added at `7.25` kB
+  against a measured `6.60` kB. The admin entry marks `@bymax-one/nest-cache` **external** —
+  bundling the server modules would give it its own copies of `CacheService` and the DI
+  tokens, so `@Inject(CacheService)` in an admin provider would name a different class object
+  than the one `BymaxCacheModule` registered and DI would fail at a consumer's runtime.
+- E2E coverage for the admin subpath against a real Redis, asserting all twenty-four `INFO`
+  field names the parser reads, real `MEMORY USAGE` sizing, and the differential scope-membership
+  check. `ioredis-mock` supports none of those three (measured), so a unit suite alone could not
+  have verified them.
+
+## [1.1.0] - 2026-08-11
+
+### Changed
+
+- **BREAKING: peer dependency `ioredis` migrated `^5` → `^6`.** A consumer must move to
+  ioredis 6, which aligns this package with `@bymax-one/nest-queue` so a single ioredis copy
+  resolves across a workspace that uses both. ioredis 6 negotiates **RESP3** on the wire by
+  default — the protocol changes at runtime — but its `'legacy'` reply mapping preserves every
+  reply shape this cache relies on (GET/SET/TTL, EVALSHA, Pub/Sub message events, cluster and
+  sentinel commands), so observable behaviour is unchanged; the only source change is the
+  compile-time typing narrowing below. ioredis 6 requires Node.js ≥ 20, already covered by
+  this package's `engines` (Node ≥ 24).
+
+### Internal
+
+- `ConnectionManager` narrows the options handed to the `Redis` and `Cluster` constructors
+  to a local shape (`OwnedRedisOptions` / `OwnedClusterOptions`). ioredis 6's constructor
+  overloads intersect `replyMapping` with a non-`undefined` variant to infer the
+  reply-mapping generic, which makes a plain `RedisOptions`/`ClusterOptions` value
+  unassignable under `exactOptionalPropertyTypes`. The narrowing drops only that `undefined`;
+  the runtime object is untouched.
+- Mutation gate tightened: Stryker `break`/`high`/`low` raised to **100** (the run is at
+  100%, 0 survivors).
 
 ## [1.0.6] - 2026-08-06
 
@@ -168,6 +280,8 @@ type or export moved.
 - Published with npm OIDC provenance — no long-lived tokens
 - Zero direct runtime dependencies (`dependencies: {}`) — `ioredis` and NestJS via peer deps
 
+[1.2.0]: https://github.com/bymaxone/nest-cache/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/bymaxone/nest-cache/compare/v1.0.6...v1.1.0
 [1.0.6]: https://github.com/bymaxone/nest-cache/compare/v1.0.5...v1.0.6
 [1.0.5]: https://github.com/bymaxone/nest-cache/compare/v1.0.4...v1.0.5
 [1.0.4]: https://github.com/bymaxone/nest-cache/compare/v1.0.3...v1.0.4

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Typed Redis cache for NestJS</strong><br />
-  <sub>ioredis 5 · Namespacing · Pub/Sub · Lua Scripts · Multi-Tenant · Zero Runtime Dependencies</sub>
+  <sub>ioredis 6 · Namespacing · Pub/Sub · Lua Scripts · Multi-Tenant · Zero Runtime Dependencies</sub>
 </p>
 
 <p align="center">
@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-cache"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-cache?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-cache/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-cache/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-cache/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-cache/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.78%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-cache/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-cache"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-cache/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-cache/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-cache?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -97,19 +97,22 @@ pnpm add @bymax-one/nest-cache ioredis
 
 ## 📦 Subpath Exports
 
-One package, two entry points — import only what your app needs:
+One package, three entry points — import only what your app needs:
 
 | Subpath    | Import                         | Purpose                                                                                                  |              Dependencies              |
 | ---------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- | :------------------------------------: |
-| **Server** | `@bymax-one/nest-cache`        | `BymaxCacheModule`, `CacheService`, `PubSubService`, `ScriptManagerService`, DI tokens, `CacheException` | NestJS 11, ioredis 5, reflect-metadata |
+| **Server** | `@bymax-one/nest-cache`        | `BymaxCacheModule`, `CacheService`, `PubSubService`, `ScriptManagerService`, DI tokens, `CacheException` | NestJS 11, ioredis 6, reflect-metadata |
+| **Admin**  | `@bymax-one/nest-cache/admin`  | Read-only administration — health, `INFO` statistics, keyspace listing, key inspection, value reveal     | NestJS 11, ioredis 6, the server entry |
 | **Shared** | `@bymax-one/nest-cache/shared` | Types + constants — `CACHE_ERROR_CODES`, `CacheEventName`, config types                                  |                  None                  |
 
 ```
 shared (zero deps)
      ↑
-  server
+  server  ←  admin
 ```
 
+`/admin` is a **privileged** surface and is kept out of the main entry on purpose: importing it is a greppable, reviewable act, a consumer who never wires it cannot resolve a reveal service from DI by accident, and it never lands in the main bundle.
+
 The `/shared` subpath is safe to import in isomorphic code, test helpers, CLI scripts, or shared packages that must not pull in NestJS or ioredis.
 
 ---
@@ -386,6 +389,104 @@ export class HealthController {
 
 ---
 
+## 🔎 Administration surface (`/admin`)
+
+A read-only surface for an operator-facing console: is the cache answering, what is it doing, what is in it.
+
+```ts
+import { BymaxCacheModule } from '@bymax-one/nest-cache'
+import { BymaxCacheAdminModule } from '@bymax-one/nest-cache/admin'
+
+// `config` is a ConfigService reachable where the module is declared; see
+// Scenario 4 above for the forRootAsync form that injects it properly.
+@Module({
+  imports: [
+    BymaxCacheModule.forRoot({
+      connection: { url: config.getOrThrow<string>('REDIS_URL') },
+      namespace: 'my-app'
+    }),
+    BymaxCacheAdminModule.forRoot({
+      scopes: [
+        {
+          id: 'cache',
+          label: 'Application cache',
+          pattern: 'my-app:*',
+          isReadable: true,
+          origin: "the application's own namespace, written through the typed API"
+        },
+        {
+          id: 'auth',
+          label: 'Authentication',
+          pattern: 'auth:*',
+          isReadable: false,
+          origin:
+            'written by another library through the un-namespaced client, so it sits at Redis ' +
+            'root. Values are refused: this keyspace holds session records.'
+        }
+      ]
+    })
+  ]
+})
+export class AppModule {}
+```
+
+```ts
+constructor(
+  @Inject(CacheStatusService) private readonly status: CacheStatusService,
+  @Inject(CacheAdminService) private readonly admin: CacheAdminService
+) {}
+
+await this.status.health()   // { status: 'up', latencyMs: 3, mode, isScanSupported, degradedAboveMs }
+await this.status.stats()    // parsed INFO
+this.status.config()         // resolved wiring, connection URL withheld
+this.admin.listScopes()      // never touches the connection
+await this.admin.listKeys('cache', { includeSize: true })
+await this.admin.revealValue('auth', 'auth:sess:1')  // { status: 'withheld', origin }
+```
+
+### What the library owns, and what you own
+
+The library owns the **mechanism**: validating the allowlist, scanning against it, describing keys, withholding values. The application owns **which keyspaces exist**, the `origin` prose that explains them, the routes, and the guards. A cache library cannot know that another library writes at Redis root through `getClient()`, and making it depend on that library to find out would invert two packages to save an application from stating one thing about itself.
+
+### `isReadable: false` withholds the value — and nothing else
+
+Listing, types, TTLs and sizes stay available on an unreadable scope. Only the value is refused, and the refusal is returned _before_ the value is read.
+
+This is the easy thing to get wrong, because "unreadable" reads like "return nothing" — and the unreadable scope is typically the one that holds the most interesting keys. A surface that renders it as empty tells an operator the region holds nothing while it is full, which is the same defect as a blank log page during an outage: a reading meaning _"I may not tell you"_ drawn identically to one meaning _"there is nothing here"_.
+
+### Scope patterns: a literal prefix, optionally ending in `*`
+
+`auth:*`, `my-app:*` and exact keys are accepted. `app:*:v1`, `*`, `a?b` and `a[bc]` are refused at wiring.
+
+The restriction exists because a caller names a **key**, so the library must decide whether that key belongs to the named scope — otherwise a caller names the readable scope and passes a key from the credential-bearing one. Deciding that for arbitrary globs means reimplementing Redis's `stringmatchlen` — greedy `*` with backtracking, `[a-z]` classes, `^` negation, escapes, and the unterminated-class case where `ten[ant` matches nothing at all — and **a matcher even slightly more permissive than the server's is a silent cross-scope leak that no happy-path test would show.** With this shape, membership is exact by construction, and the E2E suite checks it differentially against a real server's own `KEYS`.
+
+Do not relax this to be helpful. Widening it later is compatible; a leak is not un-shippable.
+
+### Readings that would carry two meanings are unions, not nullables
+
+| Reading      | Type                                                      | Why                                                                                                                                                                                            |
+| ------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxmemory`  | `unbounded \| limited \| unreported`                      | Redis spells "no ceiling" as `maxmemory:0`; read as a literal ceiling it draws a full saturation bar on the least constrained server there is — and "unbounded" is not "the server didn't say" |
+| `TTL`        | `expiring \| persistent \| missing`                       | `-1` and `-2` are different facts, and the key that expired between the scan and the read is the one an operator is watching                                                                   |
+| `aofEnabled` | `boolean \| null`                                         | `false` for an absent field is a durability claim made without evidence                                                                                                                        |
+| health       | `{ up \| degraded, latencyMs } \| { down, reason, code }` | A latency exists if and only if the ping answered — expressed as `latencyMs: number \| null` that is a convention a future `catch` can break; as a union it does not compile                   |
+
+`mode`, `isScanSupported` and `degradedAboveMs` sit **outside** the health union: a cluster deployment that is down should still report that scanning was never going to work.
+
+### Costs the surface does not hide
+
+- **`sampledCount` / `sampledBytes`** are sums over a capped `SCAN`, not measurements of the keyspace. `isComplete` is the fact; the names are the guard.
+- **A page may carry slightly more than `scanLimit` entries.** `SCAN` returns whole batches and the cursor has already moved past them, so the limit stops the loop rather than trimming the result — trimming would drop keys no later page could reach.
+- **Sizing is opt-in** (`includeSize`), and every pipeline batch is bounded in **commands**, not keys. Redis is single-threaded, so a pipeline converts a network cost into a server-blocking one: one flush of N keys × 3 commands blocks every other client for the whole burst, on a server someone is inspecting precisely because it is unwell.
+- **`connection.url` is never on the wire.** The config payload carries host, port and a TLS flag; the URL is never read into the admin subpath at all.
+- **`mem_fragmentation_ratio` is reported raw.** On an instance holding very little, allocator and copy-on-write overhead dominate and the figure reads far above 1 without indicating a problem — 9.07 was measured on an instance holding 1.1 MiB. Turning it into a verdict is deployment policy.
+
+### Cluster
+
+Every scan-based operation throws `UNSUPPORTED_IN_CLUSTER`, inherited from `CacheService.getClient()` rather than restated. `isScanSupported` travels on the health payload so a console never has to re-derive that rule from `mode`.
+
+---
+
 ## 🏗️ Architecture
 
 The package runs **inside** your NestJS application as a dynamic module — not as a separate service:
@@ -467,6 +568,10 @@ Error `details` are built to be safe to log:
 
 Scripts are declared up front — through `options.scripts` or `ScriptManagerService.register(name, lua)` — and executed **by name**. A call site passes `eval(scriptName, keys, args)`; it has no way to pass a script body. Keys are namespaced before execution and arguments arrive as Redis `ARGV[]`, which Lua treats as data, so request input cannot become script source. Standalone and Sentinel use `EVALSHA` with a `NOSCRIPT` reload-and-retry; Cluster sends the full body via `EVAL`, because `EVALSHA` routes by key slot and a keyless reload would not reach the node that reported `NOSCRIPT`.
 
+### The namespace cannot widen a destructive pattern
+
+`validateOptions` rejects a namespace containing a Redis glob metacharacter (`*`, `?`, `[`, `\`). The namespace is composed into `flushNamespace()`'s match pattern, so a metacharacter there is not cosmetic — measured against Redis 8.10.0, `*` and `?` **widen** the pattern into other keyspaces, `\` **escapes** into a different one while sparing its own keys, and `[` opens a character class that never closes so the pattern matches **nothing** and the flush reports success having removed no keys. `]` is accepted: measured to be a literal that neither widens nor silences. This matters most when the namespace is derived from input — multi-tenant wiring using a tenant slug reads like isolation and would otherwise be one unsanitised character from a cross-tenant delete.
+
 ### Cluster mode refuses commands it cannot honor safely
 
 `scan()`, `flushNamespace()`, and `getClient()` throw `UNSUPPORTED_IN_CLUSTER` under `mode: 'cluster'` rather than silently operating on one node. A partial flush that reports success is worse than an error.
@@ -483,6 +588,8 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 - Values that must not be readable by whoever can read Redis are encrypted by the application (or a custom `ISerializer`) before they are cached — the library stores what you hand it
 - Cached entries carry a TTL sized to your data-retention policy; namespacing bounds who can read an entry, not how long it exists
 - Custom `ISerializer` implementations throw on malformed input rather than returning a fallback value
+- If `/admin` is wired, its routes are behind the application's own authorization — the library validates scopes and withholds values, it does not authenticate anyone
+- Any admin scope whose keyspace holds credentials is declared `isReadable: false`, and the deployment understands that this withholds the **value only** — listing, types, TTLs and sizes stay visible by design
 
 ---
 
@@ -491,7 +598,9 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 | Layer                 | Implementation                                                                                                              |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 | Tenant Isolation      | Every key and channel composed by `KeyBuilder` as `{namespace}{sep}{prefix}{sep}{id}` — no bare-key path in the API         |
-| Namespace Validation  | Empty or separator-containing namespace rejected at bootstrap (`INVALID_NAMESPACE`)                                         |
+| Namespace Validation  | Empty, separator-containing, or glob-metacharacter namespace rejected at bootstrap (`INVALID_NAMESPACE`)                    |
+| Admin Scope Allowlist | Scopes declared at wiring, validated and frozen; a caller names a scope by id and can never supply a match pattern          |
+| Admin Read-Only       | The `/admin` subpath issues no mutating command — enforced by the `check:admin-readonly` build gate, not by convention      |
 | Key Validation        | Empty `prefix` / `id` rejected before the command is issued (`INVALID_KEY`)                                                 |
 | Deserialization       | Fails closed — `DESERIALIZATION_FAILED`; never a partial or wrongly-typed value                                             |
 | Serialization         | Top-level `undefined` / function / symbol rejected; the value is never echoed into `details`                                |
@@ -511,7 +620,7 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 ## 🧱 Tech Stack
 
 [![NestJS](https://img.shields.io/badge/NestJS-11-E0234E?style=flat-square&logo=nestjs&logoColor=white)](https://nestjs.com)
-[![ioredis](https://img.shields.io/badge/ioredis-5-DC382D?style=flat-square&logo=redis&logoColor=white)](https://github.com/redis/ioredis)
+[![ioredis](https://img.shields.io/badge/ioredis-6-DC382D?style=flat-square&logo=redis&logoColor=white)](https://github.com/redis/ioredis)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![Node.js](https://img.shields.io/badge/Node.js-24-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![Jest](https://img.shields.io/badge/Jest-30-C21325?style=flat-square&logo=jest)](https://jestjs.io)
@@ -526,8 +635,8 @@ When integrating `@bymax-one/nest-cache` in production, verify each of the follo
 A cache is consulted on the hot path of every request that touches it, so the suite is held to a bar beyond "it runs" — every behavior is pinned so that a regression **fails a test**.
 
 - ✅ **100% line coverage** — statements, branches, functions, and lines, enforced by `jest.coverage.config.ts` as a pre-publish gate, not a target
-- ✅ **99.78% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at `break: 95` and `ignoreStatic: false`; the single survivor is `configurable: false` on the withheld connection accessor, equivalent here because the resolved options are frozen on the way out, and [documented as such](./docs/mutation_testing_results.md)
-- ✅ **Zero suppressions** — the production source carries no coverage or mutation directives; the one would-be equivalent mutant was refactored away rather than silenced, so the score is an accounting rather than a number
+- ✅ **100% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at `break: 100` and `ignoreStatic: false`; 441 killed, 6 timed out, **0 survived**, and [documented in full](./docs/mutation_testing_results.md)
+- ✅ **One documented equivalent** — the production source carries a single `// Stryker disable` directive, on `configurable: false` of the withheld connection accessor, genuinely equivalent because the resolved options are frozen on the way out (freezing already makes every property non-configurable); `check:mutants` proves it parses and carries its reason, so the score is an accounting rather than a number
 - ✅ **No real Redis in unit tests** — `ioredis-mock` throughout; e2e tests exercise the wired module through `@nestjs/testing` and Testcontainers against a real Redis for connection lifecycle, Pub/Sub, and Lua scripts
 - ✅ **Published-package smoke test** — `scripts/dogfood-smoke-test.mjs` validates exports, tarball shape, and a consumer install before tagging