scalus.cardano.infra

Point-in-time cancellation probe. Callers that only need to check "has this been cancelled?" at specific points in their code accept a CancelCheck. Compared to CancelToken, this is a strictly read-only capability — no listener registration and therefore no bookkeeping cost for either side.

API authors SHOULD accept the weakest type they actually honour. An entry guard that only does if cancel.isCancelled then ... should take CancelCheck; an operation that aborts a pending Future mid-wait via a registered listener should take CancelToken. Matching the type to the capability makes the API honest: readers know "will this be observed mid-wait?" by looking at the signature.

Every CancelToken is also a CancelCheck — pass a token where a check is expected; Scala handles the promotion automatically.

Controlling side of a cancellation. Only the owner of the source has the capability to call cancel; consumers receive the token.

Full observable cancellation signal. Extends CancelCheck with onCancel for listener registration — the mechanism implementations use to abort in-flight Futures mid-wait. Consumers receive one of these and can inspect it or register cleanup actions; they cannot trigger cancellation themselves — the CancelSource.cancel capability stays with the scope owner.

Cancellation is how a Future-returning API becomes abortable at all: Future has no cancel of its own, so the capability has to be passed in.

Handle that undoes a registration.

Thrown into Futures that were aborted via a CancelToken. The reason describes the cancel site (e.g. "pre-read", "keep-alive beat timeout").

The chain rolled back further than the provider's rollback horizon, so the events needed to reconcile the subscriber's view are no longer available. The consumer must resubscribe, and generally re-seed from a snapshot.

A bounded delta buffer overflowed. The subscriber's view of chain state is no longer trustworthy: events were produced faster than they were consumed, and dropping them silently would corrupt derived state. The subscription is terminated so the consumer resyncs.

Exceptions raised by streaming subscriptions.

Two channels, deliberately distinct:

• UnsupportedSubscriptionException is an argument error. It is thrown synchronously from subscribeXxx, at the call site that caused it, before any registration happens.
• The others are runtime failures. They surface through the stream's failure channel — a failed Future from ScalusAsyncSource.pull() — because by then the subscription exists and the caller is consuming it.