How a refreshingProvider mints, times, and protects its token. The two effectful leaves (rcMint, rcClock) and the jitter source (rcJitter) are injected so the whole policy is deterministic under test; the rest are policy knobs with sensible defaults in defaultRefreshConfig.

Sensible defaults for the policy knobs. The caller must still supply the effectful leaves — rcMint and rcClock default to a mint/clock that always fails, so a provider built without wiring them up fails loudly rather than silently serving nothing.

• refresh at 80% of lifetime (no jitter by default; rcJitter may pull it earlier);
• a 30-second floor before expiry;
• breaker trips after 5 consecutive failures, cooling down for 60 seconds.

Build a CredentialProvider that caches a token and refreshes it per the RefreshConfig policy (see the module header). Mints once eagerly to seed the cache, so a provider that cannot mint at all fails here at construction rather than on the first request; thereafter currentToken serves the cache and refreshes behind it.

As refreshingProvider, but with a hook run on the serving thread at the single-flight claim → mint-runner handoff: the interruptible window between the STM transaction committing the claim and the mint runner installing the scope that releases it. It exists only so a test can deterministically park a serving thread in that window and cancel it there; production always passes pure () via refreshingProvider.

An observer of a refresh attempt's outcome, so the composition root can record the ecluse.credential.* signals without the refresh policy depending on telemetry. A successful mint reports the freshly minted token's remaining lifetime; a failed mint reports the still-cached token's remaining lifetime (so a sustained outage shows the gauge decaying as repeated failures resample the ageing token). The seconds are Nothing for a token with no expiry. noRefreshReporter is the inert default.

The inert refresh reporter: records nothing on either outcome.

The telemetry observers a refreshing provider records through: the mint circuit breaker's state changes and each refresh attempt's outcome. Bundled so the composition root passes one value to the provider constructors; noCredentialReporters is the inert default the provider carries when telemetry is off (or before the substrate exists).

Inert observers for both signals: the provider records nothing.

A failure surfaced from the credential-refresh layer.

The runtime case is BreakerOpen: there is no valid token to serve and a fresh mint is unavailable. A still-valid token is always served instead (the refresh fails silently in the background), so this is reached only on the expired-token path. Whether reaching it can affect a client serve depends on what the credential backs: never under the default passthrough strategy (mirror-write only), but it can where a provider sits on the private-upstream read (see the module header).

The degenerate case is Unconfigured: a RefreshConfig from defaultRefreshConfig was used without supplying an effectful leaf, a wiring fault the default raises loudly rather than silently serving nothing.

The mutable state of a refreshing provider: the cached token, when its proactive refresh is due, the single-flight flag, and the breaker.

What a serve/decide decision resolves to.

The single-flight decision over the current cache state, made atomically so it holds across a concurrent cohort: serve the still-valid token, claim the flag and route to a background refresh when one is due, or — when the token has expired — either claim the flag and mint synchronously or, if a mint is already in flight, retry (block) until it lands rather than launching a second. The flag claim happens here, in the transaction, so at most one mint is ever launched; the claiming caller is responsible for releasing it (see serve / releaseSingleFlight).

Compute when a freshly minted token's proactive refresh should fire: the rcRefreshAt fraction of its lifetime, pulled earlier by a per-token jitter sample and capped at rcRefreshFloor before expiry. A token with no expiry never refreshes (Nothing).

Fold a successful mint into the cache: install the token and reset the breaker. The single-flight flag is released by releaseSingleFlight in the finally around the mint (not here), so it clears even on an async exception.

Fold a failed mint into the cache: keep the still-cached token and advance the breaker per the configured threshold and cooldown (recordFailure). The single-flight flag is released separately by releaseSingleFlight (see onMintSuccess).

The circuit-breaker admission gate, shared by the background and synchronous mint paths. Defers the decision to admit and commits the breaker state it returns: while open and cooling down it denies (fast-fail); once the cooldown elapses it moves to half-open and admits a single probe; a closed or half-open breaker always admits.

Release the single-flight flag. It is run in a finally that is installed in the same masked scope that claimed the flag — serves own finally for the synchronous mint, the background Async for a proactive refresh — so the flag is cleared on every exit: success, a synchronous mint failure, or an asynchronous exception (cancellation / timeout) at any point from the claim onward, including the handoff between the STM commit and the mint runner. Without this an orphaned flag would wedge every later expired caller on the STM retry. The flag is held for the whole operation, so no concurrent mint can re-claim it mid-flight — an unconditional release here therefore cannot clobber another operation's claim.