Table of Contents

Interface ISagaTimerRecoveryStore

Namespace
Excalibur.Dispatch.Messaging
Assembly
Excalibur.Dispatch.Abstractions.dll

Applies persisted ordinary saga timer intents under retained receiver authority.

public interface ISagaTimerRecoveryStore
Extension Methods

Remarks

Optional facet discovered through selected ISagaTimeoutStore.GetService. It does not advertise atomic saga/outbox transitions. Receiver domain is exact tenant+sagaId, NEVER state type. State-type conflicts are refused within that domain, not split into cancellation islands. Existing three timer providers remain supported; no default provider refusal or mandatory lifetime quota is implied. All timer mutations and receipt/fence updates share the existing provider atomic boundary. Own-batch ordinal order is independent of external cancellation cutoffs: Schedule(T),Cancel(T) leaves no T; CancelAll,Schedule(U) retains U. State ack CAS binds stored incarnation AND version AND pending batch, and purge atomically excludes pending journals. A prior read-check is insufficient. Fence token stays stable within an incarnation; only first application of a new state incarnation rotates it. No automatic journal rebinding is part of ordinary recovery.

Methods

ApplyAsync(SagaTimerRecoveryJournal, CancellationToken)

Atomically applies the original batch with known per-intent cancellation/protection results.

ValueTask<SagaTimerRecoveryApplyResult> ApplyAsync(SagaTimerRecoveryJournal journal, CancellationToken cancellationToken)

Parameters

journal SagaTimerRecoveryJournal

Original journal persisted with state/dedup, including captured token/revision.

cancellationToken CancellationToken

Cancellation for this attempt.

Returns

ValueTask<SagaTimerRecoveryApplyResult>

Complete known receipt, positively superseded authority, revalidation, or explicit unknown.

Remarks

Verify full frame, configured limits and exact immutable receipt digest before mutation. Known duplicate means exact current incarnation/sequence/batch+digest, not an arbitrary older request. Public CancelOne records retained authority for ONLY its matching ID; other scheduled IDs remain. Public CancelAll records a scope-wide cutoff. Later cancellation versus captured Schedule produces Cancelled for that intent while other intents apply. Captured Cancel/CancelAll affect only their captured authority; newer timers are preserved and reported ProtectedNewerTimer. No blind rebase over cancellation. Cancellation/claim retirement retain authority after physical row deletion. Raw public Schedule cannot overwrite a recovery-tracked ID, even after cancellation/retirement; refuse that overwrite or require the exact current conditional authority. New untracked IDs keep normal public scheduling semantics. Public mutations must share scope lock/transaction and revision. No scalar fence change may be interpreted as successful cancel or application. RevalidationRequired cannot acknowledge the journal. Superseded must carry a known later fence and still requires current saga-state revalidation before abandoning any old local attempt. A current unresolved journal is never erased merely because a different receiver incarnation exists. Submission cancellation may be ambiguous; Unknown/throw retains original IDs/payload/journal. SQL atomic profile is unaffected.

IsTimeoutDeliveryCurrentAsync(SagaTimeoutDeliveryIdentity, CancellationToken)

Validates original queued timer authority, independent of payload-row presence.

ValueTask<bool> IsTimeoutDeliveryCurrentAsync(SagaTimeoutDeliveryIdentity delivery, CancellationToken cancellationToken)

Parameters

delivery SagaTimeoutDeliveryIdentity

The original scope/incarnation/sequence/ID carried from the claim.

cancellationToken CancellationToken

Cancellation for this read.

Returns

ValueTask<bool>

False only for positively cancelled/superseded authority; lookup/corruption must throw.

Remarks

Normal queue-acceptance retirement alone is not obsolete. New state incarnation is.

ObserveFenceAsync(SagaTimerRecoveryDomain, CancellationToken)

Observes or establishes retained receiver-local authority for the exact domain.

ValueTask<SagaTimerRecoveryFence> ObserveFenceAsync(SagaTimerRecoveryDomain domain, CancellationToken cancellationToken)

Parameters

domain SagaTimerRecoveryDomain

Exact tenant and coordinator saga ID, aligned with all public cancel paths.

cancellationToken CancellationToken

Cancellation for this attempt.

Returns

ValueTask<SagaTimerRecoveryFence>

Known opaque incarnation/batch fence and mutation revision.

Remarks

Establish an unpredictable retained token even before the first timer mutation; another receiver must not accept a foreign initial journal. Never represent lookup/storage failure as absence. Observe the actual constructor-selected receiver AFTER state load, then revalidate the same state incarnation/version/absence before handler/new journal capture. Pair again after recovery acknowledgement; never refresh a persisted journal token or its original cancellation revision. Retain authority after payload/state deletion and purge; no TTL, nonce reuse or hidden global quota. Normal provider storage pressure stays explicit.