redeye-breaker 0.4.0 → 0.5.0

package/README.md

@@ -104,7 +104,7 @@ Every process pointed at the same Redis instance (and using the same operation n
 
 ### Bring your own store
 
-`RedisStore` implements a `Store` interface with two required methods and four *optional* ones:
+`RedisStore` implements a `Store` interface with two required methods and seven *optional* ones:
 
 ```ts
 export interface Store {
@@ -115,19 +115,62 @@ export interface Store {
   // Optional — implement these for the reliability guarantees below.
   // Without them, redeye falls back to best-effort semantics and logs a
   // one-time warning telling you exactly what's degraded.
-  recordFailureAtomic?(key: string, opts: { ttlSeconds: number; failureThreshold: number; now: number }): Promise<CircuitBreakerState>;
-  recordOutcomeAtomic?(key: string, opts: { success: boolean; decay: number; minimumCalls: number; errorRateThreshold: number; ttlSeconds: number; now: number }): Promise<CircuitBreakerState & { openedNow: boolean }>;
+  recordFailureAtomic?(key: string, opts: { ttlSeconds: number; failureThreshold: number; now: number; operation: string }): Promise<CircuitBreakerState>;
+  recordOutcomeAtomic?(key: string, opts: { success: boolean; decay: number; minimumCalls: number; errorRateThreshold: number; ttlSeconds: number; now: number; operation: string }): Promise<CircuitBreakerState & { openedNow: boolean }>;
   claimTrial?(key: string, ttlSeconds: number): Promise<string | null>;
   releaseTrial?(key: string, token: string): Promise<void>;
+
+  // Optional — only needed for the closed-state local cache (`localCache`, see below).
+  closeAtomic?(key: string, eventsKey: string, opts: { ttlSeconds: number; operation: string }): Promise<CircuitBreakerState>;
+  reopenTrialFailureAtomic?(key: string, eventsKey: string, opts: { ttlSeconds: number; failureThreshold: number; now: number; operation: string }): Promise<CircuitBreakerState>;
+  subscribeTransitions?(eventsKey: string, handler: (event: TransitionEvent | null) => void): Promise<() => void>;
 }
 ```
 
-- `recordFailureAtomic` (`strategy: 'consecutive'`) should increment the failure count and decide `isOpen` in one atomic round trip (a Lua script in Redis, a conditional update in DynamoDB, etc.).
-- `recordOutcomeAtomic` (`strategy: 'errorRate'`) should fold one call's outcome into the EWMA rate and decide `isOpen` in one atomic round trip — called on every closed-phase call, not just failures.
+- `recordFailureAtomic` (`strategy: 'consecutive'`) should increment the failure count and decide `isOpen` in one atomic round trip (a Lua script in Redis, a conditional update in DynamoDB, etc.). Should also bump a monotonic `version` counter and publish a transition event to `eventsKey` (see below) when — and only when — this call flips `isOpen`; a plain sub-threshold increment isn't a transition and shouldn't publish one.
+- `recordOutcomeAtomic` (`strategy: 'errorRate'`) should fold one call's outcome into the EWMA rate and decide `isOpen` in one atomic round trip — called on every closed-phase call, not just failures. Same `version`/publish rule as above, keyed off an `isOpen` flip.
 - `claimTrial` should be a conditional "create if absent" write (`SET key token NX EX ttl` in Redis, with `token` a fresh unique value per call, e.g. a UUID) — it's what makes half-open recovery exclusive to one caller instead of a free-for-all. Return the token you wrote if this call won the claim, or `null` if the key was already taken.
 - `releaseTrial` should be a compare-and-delete (`if GET key == token then DEL key` in Redis, a conditional delete elsewhere), not an unconditional delete. This is what stops a trial that outran its TTL (see [item 11](#whats-still-a-fundamental-tradeoff-not-a-bug)) from deleting a *different* instance's newer claim on the same key when it finally gets around to releasing its own now-stale one. If omitted (or if a call has no confirmed ownership token to release at all — e.g. `claimTrial` itself errored), redeye logs a one-time warning and leaves the claim for its TTL to expire naturally, rather than risk an unconditional delete that could destroy a claim it never confirmed was its own.
+- `closeAtomic` should close `key`, bumping `version` and publishing a transition, **but only if there was anything to clear** (it was open, or had accumulated sub-threshold failures) — a true no-op, no write at all, when the state was already clean. This is what lets the healthy-path write-skip (see [limitation item 1](#whats-still-a-fundamental-tradeoff-not-a-bug)) happen atomically server-side instead of relying on the caller's own possibly-stale view.
+- `reopenTrialFailureAtomic` should reopen `key` after a failed half-open trial — `isOpen: true`, `openCount + 1`, `failures` raised to at least `failureThreshold`, `lastFailure: now`, `version + 1` — and always publish a transition (a failed trial is always a real transition, unlike `closeAtomic`).
+- `subscribeTransitions` should subscribe to a stream of transition events at `eventsKey` — **one shared stream per store/prefix, not one per operation** — and invoke `handler` with each decoded event, or with `null` whenever the underlying subscription drops or errors (callers must then distrust every locally cached entry until it's re-verified by a real read; implementations should retry their own subscription with backoff, not expect the caller to re-subscribe). Returns an unsubscribe function.
+
+Implement the two required methods against Memcached, DynamoDB, your own cache wrapper, etc., and you have a working (best-effort) distributed breaker. Add `recordFailureAtomic`/`recordOutcomeAtomic`/`claimTrial`/`releaseTrial` when that store supports a real atomic increment and a real conditional write, and you get the full reliability guarantees. Add `closeAtomic`/`reopenTrialFailureAtomic`/`subscribeTransitions` on top of that if you also want the [closed-state local cache](#local-caching-hybrid-mode) — every capability is independently optional, so skip any subset that doesn't fit your store.
+
+## Local caching (hybrid mode)
+
+Everything up to this point reads the store on every gate check (a genuine read every closed-path call; a cached, 0-read rejection once open — see [limitation item 1](#whats-still-a-fundamental-tradeoff-not-a-bug)). `localCache` goes one step further, opt-in, only for `RedisStore` (or any store implementing `subscribeTransitions`): it caches the **closed** state locally too, invalidated push-style instead of polling, so a healthy call can skip the store read entirely, not just the write.
+
+```ts
+const breaker = new CircuitBreaker({
+  failureThreshold: 5,
+  resetTimeout: 60_000,
+  store,
+  localCache: { staleToleranceMs: 100 }, // opt-in; default staleToleranceMs is 100 once the object is present
+});
+```
 
-Implement the two required methods against Memcached, DynamoDB, your own cache wrapper, etc., and you have a working (best-effort) distributed breaker. Add the optional methods relevant to the strategy you use when that store supports a real atomic increment and a real conditional write, and you get the full reliability guarantees.
+**What's cached, and how it's invalidated.** Per `operation`, redeye keeps `{ state, version, fetchedAt, trusted }` in memory. A gate check allows immediately, with zero store reads, when the entry is `trusted`, closed (`!state.isOpen`), and fresher than `staleToleranceMs`. Three independent mechanisms keep this from going stale silently:
+
+- **Push invalidation.** `subscribeTransitions` delivers a decoded event the instant any instance's write flips `isOpen` or clears real accumulated state (never on a plain sub-threshold counter update — those aren't transitions and don't invalidate the cache, by design, since they can't affect the *closed* fast path this cache serves). A higher `version` than what's cached overwrites the entry immediately.
+- **Fallback poll.** The existing local-mode monitor interval doubles as a missed-message safety net in distributed mode: any cached entry older than 5s gets one authoritative `get` and is reconciled by `version`. In steady state (no missed messages) this is the *only* background traffic the cache generates — one `GET` per stale operation per sweep, not per call.
+- **Your own writes are free.** The state `recordFailureAtomic`/`recordOutcomeAtomic`/`closeAtomic`/`reopenTrialFailureAtomic` hand back already updates this instance's own cache — the instance that causes a transition never has a stale window on it, regardless of stream or poll timing.
+
+**The fail-open window, as a formula, not an adjective.** This is the one place in redeye that's biased toward availability over freshness on the *closed* side (everywhere else — the open-state cache, `failOpenOnStoreError: false`, etc. — is fail-closed or symmetric by default). If the breaker trips elsewhere in the fleet, a call landing on this instance's still-fresh cached-closed entry can pass through before that instance learns about it. The bound is exactly:
+
+```
+worst-case fail-open window = staleToleranceMs + transition-delivery latency
+```
+
+— and it's a hard ceiling, not a typical case: the cache stops trusting itself once `staleToleranceMs` elapses regardless of whether the transition event ever arrives (that's what makes the fallback poll a correctness backstop and not just a nice-to-have), and delivery latency in the common case is one Redis stream round trip, not a poll cycle. Set `staleToleranceMs` to whatever window you're comfortable a downstream outage could go un-noticed on this one path — `100`ms (the default) is a reasonable starting point for most services; push it lower if even a hundred milliseconds of continued traffic against a freshly-tripped dependency is unacceptable, at the cost of the cache being useful for a shorter fraction of the healthy path.
+
+**Compare this to the open-state cache deliberately.** `openCacheRefreshMs` never risks an extra call through — staleness there can only make a rejection *late*, not wrong, because it always falls through to a real read right at the real eligibility instant (see limitation item 1). `localCache`'s closed-side cache is the opposite shape: staleness there can make an *allow* wrong for a bounded window, in exchange for the healthy path's read too. That's the real tradeoff you're opting into, not a bug to route around — the same one Envoy's outlier detection makes by default (cache state locally with a bounded TTL, accept staleness, skip the round trip), just off by default here and explicit about the bound when you turn it on.
+
+**The version/absence rule, and mixed-fleet rolling deploys.** `CircuitBreakerState.version` is a monotonic counter that increments only on a real transition — its *absence* (not `0`) means "written by a library version that predates `localCache`, provenance unknown." A cache entry built from a version-less read is marked `trusted: false` and never used for the fast path; the very next call for that operation performs a real read instead, forever, until a version-bearing write appears. This is what makes a rolling deploy safe: instances running an old version keep working exactly as before (they don't publish transitions, and their writes lack `version`), and new instances simply never trust a versionless observation rather than guessing. Nothing about this requires deploying in any particular order.
+
+**Strategy asymmetry, stated plainly.** `consecutive` is the strategy this cache is built for: combined with the healthy-path write skip, a run of successes against a warm cache is a genuine 0-store-op healthy path. `errorRate` cannot get the same benefit — `recordOutcomeAtomic` must fold *every* outcome (success or failure) into the EWMA to keep the rate meaningful, so it floors at 1 write per call no matter what's cached. `localCache` still saves the *read* for `errorRate` the same way it does for `consecutive`; it just can't save the write, structurally, not as an oversight.
+
+**Requires `subscribeTransitions`.** Without it (a custom `Store` that doesn't implement the capability), `localCache` is a no-op: one-time warning, and behavior is identical to not setting it at all. `RedisStore` implements it via a dedicated (`duplicate()`d) blocking connection running `XREAD BLOCK` against the shared `circuit_breaker:events` stream, reconnecting with backoff on its own if that connection drops — see the `Store` interface docs above for the reconnect contract.
 
 ## API
 
@@ -167,6 +210,7 @@ redeye can't stop you from doing this, but it can flag it: `execute`/`recordFail
 | `logger` | no-op | `{ warn(msg), log(msg) }` — plug in your own logger |
 | `maxOperations` | none | Logs a one-time warning once the breaker has seen more than this many distinct `operation` names — see the cardinality note above. Unset: no limit, no warning. |
 | `openCacheRefreshMs` | `2000` | Distributed mode only: while `operation` is known-open, reject locally without a store read, re-verifying against the store at most once per this many ms (to catch an early close by another instance's trial, or a manual `reset()`). Never delays trial eligibility — see [limitation item 1](#whats-still-a-fundamental-tradeoff-not-a-bug). `0` disables the cache (a store read on every call, the pre-cache behavior). |
+| `localCache` | none (disabled) | Distributed mode, opt-in, requires a store implementing `subscribeTransitions`: `{ staleToleranceMs?: number }` (default `100` once the object is present) — caches CLOSED state locally, invalidated push-style, so a healthy call can skip the store read too, not just the write. See [Local caching (hybrid mode)](#local-caching-hybrid-mode) for the fail-open window this trades for that. |
 
 ### Store unavailability: fail-open vs fail-closed
 
@@ -204,7 +248,7 @@ If your store *doesn't* implement the atomic method your chosen strategy needs (
 
 ### Split-brain: what's prevented, and what isn't
 
-There's no split-brain among your app instances in the classic sense, because instances never hold independent authoritative state to disagree over — every instance reads the store fresh before every single decision (`gateDistributed`) instead of trusting a locally cached opinion. The store is the only "brain"; instances are just readers/writers of it. Two mechanisms enforce agreement on the common path:
+There's no split-brain among your app instances in the classic sense, because instances never hold independent authoritative state *to write from* — every state-changing decision goes through the store, and the two local caches (`openCacheRefreshMs`, `localCache`) exist only to skip *reading* it before an already-known-safe decision, never to substitute for it. The store is the only "brain"; instances are just readers/writers of it, some of the time from a recent, bounded-staleness memory of what they last read instead of asking again. Two mechanisms enforce agreement on the common path:
 
 - **Atomic writes.** `recordFailureAtomic`/`recordOutcomeAtomic` run as one Lua script — GET, decode, increment, decide, SET — inside Redis's single-threaded execution, so two instances failing at the same instant can't both read the same count and both write the same increment.
 - **Exclusive trial claim.** `claimTrial` is a `SET ... NX`, which Redis resolves atomically, so exactly one instance ever runs the half-open recovery probe — never two instances simultaneously deciding they're the one testing recovery.
@@ -221,7 +265,8 @@ So the design doesn't eliminate split-brain so much as route around it: it pushe
 
 These are true of any distributed circuit breaker, rate limiter, or lock built on a shared store — not gaps specific to redeye:
 
-1. **Distributed mode costs Redis round trips per guarded call, not zero — except while the breaker is actually open, which is exactly when that matters most.** On the closed, healthy path, every `execute()` call does a gate read (`store.get`) before deciding whether to proceed; what happens after differs by strategy — `errorRate` writes (`recordOutcomeAtomic`) on every closed-phase call, success or failure, since the rate needs both to be meaningful, while `consecutive` only writes when the gate's own read observed accumulated state to clear (an open breaker, or `failures > 0`), making a run of healthy successes 1 read and 0 writes per call, not 1-and-1 (a measured claim about the steady state, not a guarantee — a dependency flapping near the failure threshold still writes on most calls). **Once the breaker is open, rejections stop costing a read at all**: the gate caches the open state locally (`lastFailure`, `openCount`, and the same jittered `expiresAt` the eligibility check itself uses) and rejects straight from that cache, re-verifying against the store only once per `openCacheRefreshMs` (default 2000ms) — to catch an early close by another instance's trial, or a manual `reset()` — and always falling through to a real read right at `expiresAt`, so the cache can delay a rejection's freshness but can never delay a trial's eligibility. Net effect: the request-volume-scaling cost this item used to describe applies to the closed, healthy path — the load *during an incident*, when the store or its host infrastructure may itself be degraded, drops instead of scaling with traffic. A resolving half-open trial still adds a round trip to claim it and another to release its claim — that path is unaffected, and unconditional, regardless of strategy. On a latency-sensitive path the closed-path round trip is still added tail latency — the opposite tradeoff from something like Envoy's outlier detection, which caches state locally with a short TTL and accepts bounded staleness instead of paying a store round trip per call. redeye chose per-call freshness over that on the closed path; it's a reasonable choice for many services, but measure it before putting this in front of your highest-QPS call. Local mode has none of this cost — see [Local mode vs. distributed mode](#local-mode-vs-distributed-mode-which-do-you-need) if you're not sure you need shared state at all.
+1. **Distributed mode's per-call store cost is opt-in-able down to a bound you choose, not fixed — but "zero" always means "zero, at a stated staleness price," never "zero, for free."** By default, every `execute()` call does a gate read (`store.get`) before deciding whether to proceed; what happens after differs by strategy — `errorRate` writes (`recordOutcomeAtomic`) on every closed-phase call, success or failure, since the rate needs both to be meaningful (this never goes away, at any cache setting — see below), while `consecutive` only writes when the gate's own read observed accumulated state to clear (an open breaker, or `failures > 0`), making a run of healthy successes 1 read and 0 writes per call by default, not 1-and-1. **Once the breaker is open, rejections stop costing a read at all**, unconditionally, no opt-in required: the gate caches the open state locally (`lastFailure`, `openCount`, and the same jittered `expiresAt` the eligibility check itself uses) and rejects straight from that cache, re-verifying against the store only once per `openCacheRefreshMs` (default 2000ms), and always falling through to a real read right at `expiresAt` — so this cache can delay a rejection's freshness but can never delay a trial's eligibility, and never risks letting an extra call through. That's the fail-*closed*-biased half of the story: staleness there can only make things more conservative.
+   The closed, healthy path is the other half, and it's where a real tradeoff lives: **`localCache` (opt-in) is redeye's answer to exactly the caching-with-bounded-staleness tradeoff Envoy's outlier detection makes by default** — cache state locally, accept a bounded staleness window, skip the round trip. Off by default (redeye chooses per-call freshness there until you say otherwise), and explicit about the bound when you turn it on: the worst case is `staleToleranceMs + transition-delivery latency`, a formula, not an adjective — see [Local caching (hybrid mode)](#local-caching-hybrid-mode) for exactly what that means and what it doesn't cover (`errorRate`'s write floor, in particular, which `localCache` cannot remove — only `consecutive` reaches a genuine 0-store-op healthy path). A resolving half-open trial always adds a round trip to claim it and another to release its claim, at any cache setting, on either strategy — that path is never cacheable, and rightly so. Local mode has none of this cost at all — see [Local mode vs. distributed mode](#local-mode-vs-distributed-mode-which-do-you-need) if you're not sure you need shared state to begin with.
 2. **Correctness depends on trusting your store.** If Redis evicts a breaker key early under memory pressure (e.g. `maxmemory-policy allkeys-lru` with `circuit_breaker:*` competing for space with everything else), the breaker can reset earlier than intended. Mitigate by giving circuit-breaker keys their own keyspace/DB with a policy that doesn't evict them, or by monitoring `onStoreError` and Redis memory pressure directly. This is not fixable in-library — it's an operational configuration matter.
 3. **Distributed timing is sensitive to clock skew.** Backoff and jitter windows are computed by comparing each instance's local `Date.now()` against a `lastFailure` timestamp written by whichever instance recorded it. With reasonably synchronized clocks (standard NTP) this is a non-issue; on a fleet with significant clock drift, instances can disagree by that drift amount about exactly when a trial becomes eligible. This affects *timing* only — the half-open claim mechanism (`claimTrial`) still guarantees exactly one trial runs regardless of skew, so skew cannot cause a thundering herd, only a slightly early or late trial attempt.
 4. **`recordFailure`/`recordSuccess`/`canExecuteAsync` don't participate in trial claiming.** Only `execute()` claims and releases the half-open trial slot. If you build your own call flow around the manual API instead of `execute()`, you lose the single-trial guarantee and get the old "everyone retries once elapsed" behavior for that flow. Prefer `execute()`.
@@ -252,6 +297,8 @@ docker compose down
 
 It connects to `REDIS_URL` (default `redis://localhost:6379`).
 
+`npm run bench` runs `bench/index.js` against a real Redis, comparing total store round trips and p50/p99 latency across three configurations: no caching, today's defaults (`openCacheRefreshMs`), and `localCache` on top. Same `REDIS_URL`; start Redis first the same way as the integration suite. See [BENCHMARK.md](BENCHMARK.md) for a full run's results and how to read them.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Changes are tracked in [CHANGELOG.md](CHANGELOG.md).

package/dist/circuit-breaker.d.ts

@@ -1,11 +1,11 @@
 import { Store } from './store';
-import { CircuitBreakerState, CircuitMetrics } from './types';
+import { CircuitBreakerState, CircuitMetrics, TransitionEvent } from './types';
 export type CircuitState = 'closed' | 'open' | 'half-open';
 export interface BreakerLogger {
     warn(message: string): void;
     log(message: string): void;
 }
-export type { CircuitBreakerState, CircuitMetrics };
+export type { CircuitBreakerState, CircuitMetrics, TransitionEvent };
 /**
  * Thrown in distributed mode when the backing store is unreachable and
  * `failOpenOnStoreError` is `false`. Distinguishable from a downstream
@@ -122,6 +122,32 @@ export interface CircuitBreakerOptions {
      * Default: 2000.
      */
     openCacheRefreshMs?: number;
+    /**
+     * Distributed mode, opt-in. Serves gate decisions for CLOSED state from a
+     * local cache while it's fresher than `staleToleranceMs`, invalidated
+     * push-style via the store's transition stream (`Store.subscribeTransitions`)
+     * instead of polling — so a healthy call can skip the store read entirely,
+     * not just the write Release 1 already skips.
+     *
+     * This only ever short-circuits an *allow*: a cache entry observed open
+     * always defers to the open-state cache (`openCacheRefreshMs`) and a real
+     * read, which remains authoritative for all rejection handling. Requires
+     * a store implementing `subscribeTransitions`; without one, this option
+     * is a no-op (one-time warning) and behavior is unchanged from not
+     * setting it at all.
+     *
+     * The worst case is a bounded fail-open window: if the breaker trips
+     * elsewhere in the fleet, a calls still landing on a cached entry can be
+     * let through for up to `staleToleranceMs` plus however long the
+     * transition event takes to arrive — never longer, since the cache entry
+     * expires against `staleToleranceMs` on its own regardless of whether the
+     * event ever arrives. See the README's local caching section for the
+     * full fail-open/fail-closed asymmetry this creates versus the
+     * (fail-closed-biased) open-state cache.
+     */
+    localCache?: {
+        staleToleranceMs?: number;
+    };
 }
 /**
  * A circuit breaker with an optional distributed mode.
@@ -159,6 +185,22 @@ export declare class CircuitBreaker {
      * an early close by another instance or a manual `reset()`.
      */
     private readonly cachedOpen;
+    /** Fixed, unprefixed key for the shared transition-event stream — one per store/prefix, not one per operation. `RedisStore` applies its own `keyPrefix` the same way it does for every other key this class hands it. */
+    private readonly eventsKey;
+    /**
+     * Distributed mode only, `localCache` opt-in: a local, push-invalidated
+     * record of the last known state for `operation`, used to serve gate
+     * decisions for CLOSED state with zero store reads while fresh and
+     * trusted. `trusted: false` means the last write we saw for this entry
+     * had no `version` (unknown provenance — an older library version wrote
+     * it) or the transition subscription itself dropped; either way, the
+     * gate must not use it and instead performs a real read next time,
+     * which re-establishes trust.
+     */
+    private readonly closedCache;
+    /** True once `subscribeTransitions` has actually succeeded; false (the closed cache is never consulted) if `localCache` wasn't set, the store lacks the capability, or the initial subscribe attempt failed. */
+    private localCacheActive;
+    private unsubscribeTransitions?;
     private readonly failures;
     private readonly lastFailureTime;
     private readonly openOperations;
@@ -169,7 +211,33 @@ export declare class CircuitBreaker {
     private readonly sampleCounts;
     private readonly monitorHandle;
     constructor(options?: CircuitBreakerOptions);
-    /** Stops the local-mode monitor interval. Call this when the breaker is no longer needed. */
+    /**
+     * Attempts to establish the closed-state cache's push invalidation via
+     * `Store.subscribeTransitions`. Best-effort and one-shot: if the store
+     * doesn't implement it, or the initial subscribe attempt itself throws,
+     * `localCache` stays disabled for this breaker's lifetime (a one-time
+     * warning either way) — reconnects *after* a successful subscription are
+     * the store implementation's own responsibility (see the interface doc).
+     */
+    private setupLocalCache;
+    /**
+     * `null` means the subscription's connection dropped or errored: every
+     * cached entry may now be missing events, so all of them are marked
+     * untrusted until their next authoritative (real-read) refresh — the
+     * fallback poll in `monitor()` is what eventually forces that refresh if
+     * no call happens to trigger one first.
+     */
+    private handleTransitionEvent;
+    /**
+     * Refreshes the closed-state cache entry for `operation` with a fresh
+     * authoritative read, whether the write came from this instance (already
+     * has the resulting state in hand) or a real gate read. A no-op if
+     * `localCache` isn't active. Never regresses a cache entry that a newer
+     * transition event has already superseded, since a real read can race a
+     * push notification and land after it.
+     */
+    private updateClosedCache;
+    /** Stops the local-mode monitor interval and any transition-event subscription. Call this when the breaker is no longer needed. */
     destroy(): void;
     execute<T>(operation: string, fn: () => Promise<T>): Promise<T>;
     /**
@@ -240,6 +308,15 @@ export declare class CircuitBreaker {
     private key;
     private trialKey;
     private stateTtlSeconds;
+    /**
+     * Same generous, non-load-bearing safety-net TTL as `stateTtlSeconds`, for
+     * the one call site (`reopenTrialFailureAtomic`) that must pick a TTL
+     * *before* knowing the resulting `openCount` the atomic script itself
+     * computes server-side. Sized off `maxResetTimeout` — the ceiling
+     * `backoffCapped` can ever reach at any `openCount` — so it's always at
+     * least as generous as the true per-`openCount` value would be.
+     */
+    private maxStateTtlSeconds;
     private trialTtlSeconds;
     private reportStoreError;
     private warnMissingCapability;
@@ -302,6 +379,7 @@ export declare class CircuitBreaker {
      * breaker open with no way to ever attempt another trial.
      */
     private monitor;
+    private reconcileClosedCache;
     private executeWithTimeout;
 }
 //# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAA8B,eAAe,EAAE,MAAM,SAAS,CAAC;AAE3G,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAErE;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAK9C;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC;IACvC,wGAAwG;IACxG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mGAAmG;IACnG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qIAAqI;IACrI,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACjE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;;;;;;;;;;;OAcG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAqCD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAuBtB;IAEF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,iCAAiC,CAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,0BAA0B,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAgF;IACpH;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyG;IAEpI,yNAAyN;IACzN,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA2G;IACvI,gNAAgN;IAChN,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,sBAAsB,CAAC,CAAa;IAG5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;gBAEnD,OAAO,GAAE,qBAA0B;IAmC/C;;;;;;;OAOG;YACW,eAAe;IAkB7B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAiBzB,mIAAmI;IACnI,OAAO,IAAI,IAAI;IAKT,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAKrE;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;;;;;;;OAQG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAiBtC;;;;;OAKG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM1D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAetC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAStC;;;;;;;;;OASG;YACW,yBAAyB;IAQjC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAYzD,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB7C,wPAAwP;IACxP,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc;IAK7C,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAM/C,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,aAAa;IAKrB;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IAe7B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,eAAe;IAUvB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,qBAAqB;YAUf,OAAO;YASP,OAAO;IAQrB,qFAAqF;YACvE,WAAW;IAQzB,4NAA4N;YAC9M,YAAY;IAQ1B;;;;;;;;;;;;;;;;OAgBG;YACW,gBAAgB;YAahB,gBAAgB;IAyB9B;;;;;OAKG;YACW,eAAe;YAsEf,kBAAkB;YAsDlB,gCAAgC;IAkD9C;;;;OAIG;YACW,wBAAwB;YAuDxB,iCAAiC;YAyCjC,YAAY;IAkC1B,gFAAgF;IAChF,OAAO,CAAC,aAAa;IAcrB,oFAAoF;IACpF,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,0BAA0B;IAclC,kIAAkI;IAClI,OAAO,CAAC,sBAAsB;IAkB9B,OAAO,CAAC,2BAA2B;IAUnC,OAAO,CAAC,UAAU;IAiBlB;;;;;;OAMG;IACH,OAAO,CAAC,OAAO;YA6BD,oBAAoB;IAOlC,OAAO,CAAC,kBAAkB;CAiB3B"}

package/dist/circuit-breaker.js

@@ -52,6 +52,21 @@ class CircuitBreaker {
          * an early close by another instance or a manual `reset()`.
          */
         this.cachedOpen = new Map();
+        /** Fixed, unprefixed key for the shared transition-event stream — one per store/prefix, not one per operation. `RedisStore` applies its own `keyPrefix` the same way it does for every other key this class hands it. */
+        this.eventsKey = 'circuit_breaker:events';
+        /**
+         * Distributed mode only, `localCache` opt-in: a local, push-invalidated
+         * record of the last known state for `operation`, used to serve gate
+         * decisions for CLOSED state with zero store reads while fresh and
+         * trusted. `trusted: false` means the last write we saw for this entry
+         * had no `version` (unknown provenance — an older library version wrote
+         * it) or the transition subscription itself dropped; either way, the
+         * gate must not use it and instead performs a real read next time,
+         * which re-establishes trust.
+         */
+        this.closedCache = new Map();
+        /** True once `subscribeTransitions` has actually succeeded; false (the closed cache is never consulted) if `localCache` wasn't set, the store lacks the capability, or the initial subscribe attempt failed. */
+        this.localCacheActive = false;
         // local mode state
         this.failures = new Map();
         this.lastFailureTime = new Map();
@@ -82,14 +97,90 @@ class CircuitBreaker {
             logger: options.logger ?? noopLogger,
             maxOperations: options.maxOperations,
             openCacheRefreshMs: options.openCacheRefreshMs ?? 2000,
+            localCache: options.localCache ? { staleToleranceMs: options.localCache.staleToleranceMs ?? 100 } : undefined,
         };
         this.distributed = !!options.store;
         this.monitorHandle = setInterval(() => this.monitor(), this.options.monitorInterval);
         this.monitorHandle.unref?.();
+        if (this.distributed && this.options.localCache) {
+            void this.setupLocalCache();
+        }
     }
-    /** Stops the local-mode monitor interval. Call this when the breaker is no longer needed. */
+    /**
+     * Attempts to establish the closed-state cache's push invalidation via
+     * `Store.subscribeTransitions`. Best-effort and one-shot: if the store
+     * doesn't implement it, or the initial subscribe attempt itself throws,
+     * `localCache` stays disabled for this breaker's lifetime (a one-time
+     * warning either way) — reconnects *after* a successful subscription are
+     * the store implementation's own responsibility (see the interface doc).
+     */
+    async setupLocalCache() {
+        const store = this.options.store;
+        if (!store.subscribeTransitions) {
+            this.options.logger.warn('localCache is set but the store does not implement subscribeTransitions(); the closed-state cache stays disabled (falling back to open-cache-only behavior). See README.');
+            return;
+        }
+        try {
+            this.unsubscribeTransitions = await store.subscribeTransitions(this.eventsKey, (event) => this.handleTransitionEvent(event));
+            this.localCacheActive = true;
+        }
+        catch (error) {
+            this.options.logger.warn(`localCache is set but subscribing to transition events failed; the closed-state cache stays disabled: ${error?.message ?? error}`);
+        }
+    }
+    /**
+     * `null` means the subscription's connection dropped or errored: every
+     * cached entry may now be missing events, so all of them are marked
+     * untrusted until their next authoritative (real-read) refresh — the
+     * fallback poll in `monitor()` is what eventually forces that refresh if
+     * no call happens to trigger one first.
+     */
+    handleTransitionEvent(event) {
+        if (event === null) {
+            for (const entry of this.closedCache.values())
+                entry.trusted = false;
+            return;
+        }
+        const existing = this.closedCache.get(event.operation);
+        if (existing && event.version <= existing.version)
+            return; // stale/duplicate delivery -- ignore
+        this.closedCache.set(event.operation, {
+            state: { ...types_1.CLOSED_STATE, isOpen: event.isOpen, lastFailure: event.lastFailure, openCount: event.openCount, version: event.version },
+            version: event.version,
+            fetchedAt: Date.now(),
+            trusted: true,
+        });
+    }
+    /**
+     * Refreshes the closed-state cache entry for `operation` with a fresh
+     * authoritative read, whether the write came from this instance (already
+     * has the resulting state in hand) or a real gate read. A no-op if
+     * `localCache` isn't active. Never regresses a cache entry that a newer
+     * transition event has already superseded, since a real read can race a
+     * push notification and land after it.
+     */
+    updateClosedCache(operation, state) {
+        if (!this.localCacheActive)
+            return;
+        // null (never written) is unambiguously clean, same as CLOSED_STATE's
+        // own version: 0 -- distrust is for a *stored* object that predates the
+        // version field, not for "nothing has ever been written here."
+        const trusted = state === null || state.version !== undefined;
+        const version = state?.version ?? 0;
+        const existing = this.closedCache.get(operation);
+        if (trusted && existing?.trusted && version < existing.version)
+            return; // don't regress past a newer stream event
+        this.closedCache.set(operation, {
+            state: state ?? { ...types_1.CLOSED_STATE },
+            version,
+            fetchedAt: Date.now(),
+            trusted,
+        });
+    }
+    /** Stops the local-mode monitor interval and any transition-event subscription. Call this when the breaker is no longer needed. */
     destroy() {
         clearInterval(this.monitorHandle);
+        this.unsubscribeTransitions?.();
     }
     async execute(operation, fn) {
         this.checkOperationName(operation);
@@ -212,6 +303,7 @@ class CircuitBreaker {
             await this.safeDelTrial(operation);
             this.cachedResetTimeouts.delete(operation);
             this.cachedOpen.delete(operation);
+            this.closedCache.delete(operation);
             if (prior?.isOpen) {
                 this.options.onStateChange?.('closed', operation);
             }
@@ -303,6 +395,17 @@ class CircuitBreaker {
         // to vary a generous cleanup TTL.
         return Math.max(1, Math.ceil((this.backoffCapped(openCount) * 3) / 1000));
     }
+    /**
+     * Same generous, non-load-bearing safety-net TTL as `stateTtlSeconds`, for
+     * the one call site (`reopenTrialFailureAtomic`) that must pick a TTL
+     * *before* knowing the resulting `openCount` the atomic script itself
+     * computes server-side. Sized off `maxResetTimeout` — the ceiling
+     * `backoffCapped` can ever reach at any `openCount` — so it's always at
+     * least as generous as the true per-`openCount` value would be.
+     */
+    maxStateTtlSeconds() {
+        return Math.max(1, Math.ceil((this.options.maxResetTimeout * 3) / 1000));
+    }
     trialTtlSeconds() {
         return Math.max(1, Math.ceil(this.options.trialTimeout / 1000));
     }
@@ -384,9 +487,29 @@ class CircuitBreaker {
         }
     }
     async closeDistributed(operation) {
+        if (this.options.store.closeAtomic) {
+            try {
+                const next = await this.options.store.closeAtomic(this.key(operation), this.eventsKey, {
+                    ttlSeconds: this.stateTtlSeconds(0),
+                    operation,
+                });
+                this.cachedResetTimeouts.delete(operation);
+                this.cachedOpen.delete(operation);
+                this.updateClosedCache(operation, next);
+                return;
+            }
+            catch (error) {
+                this.reportStoreError(error, operation);
+                // fall through to non-atomic fallback below
+            }
+        }
+        else {
+            this.warnMissingCapability('closeAtomic');
+        }
         await this.safeSet(operation, { ...types_1.CLOSED_STATE }, this.stateTtlSeconds(0));
         this.cachedResetTimeouts.delete(operation);
         this.cachedOpen.delete(operation);
+        this.updateClosedCache(operation, { ...types_1.CLOSED_STATE });
     }
     /**
      * Determines whether a call is allowed through in distributed mode.
@@ -395,6 +518,15 @@ class CircuitBreaker {
      * `canExecuteAsync`) is read-only and never claims.
      */
     async gateDistributed(operation, claim) {
+        if (this.localCacheActive) {
+            const entry = this.closedCache.get(operation);
+            if (entry && entry.trusted && !entry.state.isOpen && Date.now() - entry.fetchedAt < this.options.localCache.staleToleranceMs) {
+                return { allowed: true, isTrial: false, assumeClean: true };
+            }
+            // entry.state.isOpen, stale, untrusted, or absent -- defer entirely to
+            // the open-state cache / a real read below, which remain
+            // authoritative for all open/rejection handling.
+        }
         const cached = this.cachedOpen.get(operation);
         if (cached && this.options.openCacheRefreshMs > 0) {
             const now = Date.now();
@@ -421,6 +553,7 @@ class CircuitBreaker {
                 return { allowed: true, isTrial: false };
             throw new StoreUnavailableError(operation, error);
         }
+        this.updateClosedCache(operation, state); // every real read refreshes the closed cache too, whatever it finds
         if (!state?.isOpen) {
             this.cachedOpen.delete(operation);
             return { allowed: true, isTrial: false, observedState: state };
@@ -474,15 +607,19 @@ class CircuitBreaker {
             else {
                 // consecutive strategy, non-trial success: only write if the gate
                 // positively observed dirty state. If the read errored
-                // (observedState undefined), write anyway — we can't know.
+                // (observedState undefined), write anyway — we can't know. A
+                // closed-cache fast-pathed gate (`assumeClean`) skips the write
+                // too, accepting the same bounded staleness the 0-read cache hit
+                // itself already accepted -- this is what gets `consecutive` to a
+                // genuine 0-round-trip healthy path.
                 //
                 // Race analysis: if a concurrent failure lands between our gate
-                // read and this skipped write, not writing preserves that failure
-                // count — strictly safer than the old unconditional
+                // read (or cache hit) and this skipped write, not writing preserves
+                // that failure count — strictly safer than the old unconditional
                 // `closeDistributed`, which could erase a legitimate concurrent
                 // increment by overwriting it with CLOSED_STATE.
                 const s = gate.observedState;
-                const observedClean = s !== undefined && (s === null || (!s.isOpen && s.failures === 0));
+                const observedClean = gate.assumeClean || (s !== undefined && (s === null || (!s.isOpen && s.failures === 0)));
                 if (!observedClean) {
                     await this.closeDistributed(operation);
                 }
@@ -511,10 +648,12 @@ class CircuitBreaker {
                     ttlSeconds: this.stateTtlSeconds(0),
                     failureThreshold: this.options.failureThreshold,
                     now: Date.now(),
+                    operation,
                 });
                 this.options.logger.warn(`Recorded failure for operation: ${operation}, total failures: ${next.failures}`);
                 if (next.isOpen)
                     this.cacheOpenState(operation, next);
+                this.updateClosedCache(operation, next);
                 if (next.isOpen && next.failures === this.options.failureThreshold) {
                     this.options.logger.warn(`Circuit breaker opened for operation: ${operation}`);
                     this.options.onStateChange?.('open', operation);
@@ -546,6 +685,7 @@ class CircuitBreaker {
         await this.safeSet(operation, next, this.stateTtlSeconds(0));
         if (next.isOpen)
             this.cacheOpenState(operation, next);
+        this.updateClosedCache(operation, next);
         this.options.logger.warn(`Recorded failure for operation: ${operation}, total failures: ${next.failures}`);
         if (next.isOpen && !current.isOpen) {
             this.options.logger.warn(`Circuit breaker opened for operation: ${operation}`);
@@ -567,9 +707,11 @@ class CircuitBreaker {
                     errorRateThreshold: this.options.errorRateThreshold,
                     ttlSeconds: this.stateTtlSeconds(0),
                     now: Date.now(),
+                    operation,
                 });
                 if (next.isOpen)
                     this.cacheOpenState(operation, next);
+                this.updateClosedCache(operation, next);
                 if (next.openedNow) {
                     this.options.logger.warn(`Circuit breaker opened for operation: ${operation} (error rate ${(next.errorRate * 100).toFixed(1)}% over ${next.sampleCount} calls)`);
                     this.options.onStateChange?.('open', operation);
@@ -600,12 +742,35 @@ class CircuitBreaker {
         await this.safeSet(operation, next, this.stateTtlSeconds(0));
         if (isOpen)
             this.cacheOpenState(operation, next);
+        this.updateClosedCache(operation, next);
         if (isOpen && !current.isOpen) {
             this.options.logger.warn(`Circuit breaker opened for operation: ${operation} (error rate ${(errorRate * 100).toFixed(1)}% over ${sampleCount} calls)`);
             this.options.onStateChange?.('open', operation);
         }
     }
     async reopenAfterFailedTrialDistributed(operation) {
+        if (this.options.store.reopenTrialFailureAtomic) {
+            try {
+                const next = await this.options.store.reopenTrialFailureAtomic(this.key(operation), this.eventsKey, {
+                    ttlSeconds: this.maxStateTtlSeconds(),
+                    failureThreshold: this.options.failureThreshold,
+                    now: Date.now(),
+                    operation,
+                });
+                this.cacheOpenState(operation, next);
+                this.updateClosedCache(operation, next);
+                this.options.logger.warn(`Half-open trial failed for operation: ${operation}; backing off (attempt ${next.openCount + 1})`);
+                this.options.onStateChange?.('open', operation);
+                return;
+            }
+            catch (error) {
+                this.reportStoreError(error, operation);
+                // fall through to non-atomic fallback below
+            }
+        }
+        else {
+            this.warnMissingCapability('reopenTrialFailureAtomic');
+        }
         const current = (await this.safeGet(operation)) ?? { ...types_1.CLOSED_STATE, isOpen: true };
         const openCount = (current.openCount ?? 0) + 1;
         const next = {
@@ -618,6 +783,7 @@ class CircuitBreaker {
         };
         await this.safeSet(operation, next, this.stateTtlSeconds(openCount));
         this.cacheOpenState(operation, next); // this instance authored the open state; cache it
+        this.updateClosedCache(operation, next);
         this.options.logger.warn(`Half-open trial failed for operation: ${operation}; backing off (attempt ${openCount + 1})`);
         this.options.onStateChange?.('open', operation);
     }
@@ -760,6 +926,24 @@ class CircuitBreaker {
                 this.options.logger.warn(`Circuit breaker trial for operation: ${operation} appears stuck (wrapped function never settled); force-releasing after ${staleBound}ms. Consider configuring a timeout.`);
             }
         }
+        // Missed-message safety net for the closed-state cache: transitions are
+        // normally learned about push-style via subscribeTransitions, but a
+        // dropped stream message (or a subscription gap) would otherwise leave
+        // a cache entry stale forever. In steady state this is the only
+        // background traffic the closed-state cache generates -- one GET per
+        // stale operation per monitor tick, not per call.
+        if (this.distributed && this.localCacheActive) {
+            const pollAgeMs = 5000;
+            for (const [operation, entry] of this.closedCache.entries()) {
+                if (now - entry.fetchedAt > pollAgeMs) {
+                    void this.reconcileClosedCache(operation);
+                }
+            }
+        }
+    }
+    async reconcileClosedCache(operation) {
+        const state = await this.safeGet(operation);
+        this.updateClosedCache(operation, state);
     }
     // ---- shared -------------------------------------------------------------
     executeWithTimeout(fn) {