Module adaptive 

Adaptive effect handlers (§10.8).

This module provides the Rust-level infrastructure for runtime strategy selection on effect failure. The surface follows the spec’s RecoveryStrategy[E, T] trait, its RecoveryContext record, and the five built-in combinators (retry, use_cached, degrade, circuit_break, escalate).

Runtime plumbing (full Cancel ambient effect, interpreter wiring of handling (... with adaptive(...)) blocks) is deferred to Phase 5/6 per the 2026-04-22 changelog. What lands here in Phase D:

• RecoveryContext matching §10.8 exactly.
• A RecoveryStrategy trait whose attempt returns StrategyOutcome<T, E> — the Rust spelling of Result[T, E] | Cancelled — and a default-no-op on_cancel.
• Five built-in combinators with cancel-awareness at their internal await points.
• AdaptiveHandler: the Effect.adaptive() combinator. Given a list of strategies and a provider, it selects via AiProvider::select in development/sketch, or looks up a pin in the runtime decision manifest in production.
• AdaptivePinKey: the (error_signature, operation) pair that Q6 of the 2026-04-20 amendment specifies for pin granularity.

The module is not yet connected to the interpreter’s handling block — that wiring happens in Phase 5/6 when the effect handler runtime is extended to support the adaptive path. What this module delivers is the stable API surface Phase 5/6 will wire up, with unit-level coverage that exercises it end to end.

Structs

AdaptiveHandler

Handler constructed by Effect.adaptive(strategies, context_aware).

AdaptiveHandlerBuilder

Builder for AdaptiveHandler. Returned by adaptive / [Effect::adaptive]-style callers.

AdaptivePinKey

Pin key = (error_signature, operation) per Q6 of the 2026-04-20 spec amendment.

Annotations

Snapshot of @context, @performance, @domain, @security annotations reaching the recovery site.

CancelCheckpoint

Cooperative cancellation flag used by built-in combinators at their internal await points.

Cancelled

Phase D stub for the Cancelled value that will cross the adaptive boundary in Phase 5/6 when the full Cancel ambient effect lands.

CircuitBreakerStrategy

circuit_break(threshold, reset_after) combinator.

DegradeStrategy

degrade(fallback) combinator. Immediately returns a fallback value of the operation’s type.

ErrorOccurrence

A prior error observed by this handler. Bounded to 10 most recent entries in RecoveryContext.

EscalateStrategy

escalate() combinator. Propagates the error without recovery.

RecoveryContext

Shape defined in §10.8 (Q5 of the 2026-04-20 amendment).

RecoveryResult

Outcome of an adaptive recovery call. Wraps StrategyOutcome with the SelectionRecord that was consulted so callers can inspect what happened.

RetryStrategy

retry(max, backoff) combinator. Re-invokes the operation up to max additional times, waiting backoff.delay(attempt) between attempts. Checks cancellation before each retry.

SelectionRecord

Description of the selection that the handler applied. Useful for tests and the manifest layer.

SimpleError

A simple owned error value suitable for tests and library callers that don’t yet have a first-class error representation.

UseCachedStrategy

use_cached(ttl) combinator. Returns the cached value if present and within TTL; otherwise forwards the original error.

Enums

AdaptiveError

Error type produced by AdaptiveHandler::recover when the handler cannot make a selection (e.g., unknown pattern in production mode).

Backoff

Backoff function between retry attempts.

SelectionSource

Explains why the handler picked a strategy.

StrategyOutcome

The Rust spelling of the spec’s Result[T, E] | Cancelled sum.

Traits

ErrorValue

Minimal view of a Bock error that the adaptive handler needs.

RecoveryStrategy

Bock spec:

Functions

adaptive

Effect.adaptive(...) factory. Creates an AdaptiveHandlerBuilder with the developer-preferred default (context_aware = true, development strictness, no provider, no manifest).

adaptive_scope

Convenience: register the runtime scope for a decision so callers building a manifest entry by hand don’t have to duplicate the check.

circuit_break

Constructs a CircuitBreakerStrategy.

degrade

Constructs a DegradeStrategy returning fallback on the first invocation.

escalate

Constructs an EscalateStrategy.

retry

Constructs a RetryStrategy. See spec §10.8.

use_cached

Constructs a UseCachedStrategy wired to lookup. ttl is recorded in the description but enforcement is the lookup’s responsibility.

Type Aliases

BoxedStrategy

Heap-allocated strategy pointer used everywhere the adaptive handler stores strategies.

CacheLookup

A cached lookup function. Used by use_cached.

PinTable

Thread-safe lookup table for pinned selections. In production strictness the handler consults this before anything else.

RecoveryOperation

The operation the adaptive handler will re-run on each attempt.