Table of Contents

Interface ISagaAtomicTransitionStore

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

Optionally commits immutable state and effects in one provider-owned durable transaction.

public interface ISagaAtomicTransitionStore
Extension Methods

Remarks

Existing ISagaStore state-only semantics are unchanged. Durable orchestration must select this capability explicitly and fail closed when it is absent. Implementations commit state, timers, command/event rows, effect membership and an exact receipt together. They do not dispatch while holding the transaction. Effects retain stable identities and ordinal/sequence metadata for the existing outbox drain. This capability does not promise global FIFO, ordered completion across producers, exactly-once delivery or a new shared head/fencing protocol. Configured timers require the selected participant; absent timeout configuration requires no fabricated participant. Unsupported composition refuses before state persistence; state-only fallback is never an atomic transition.

Methods

CommitAsync(SagaPreparedTransition, CancellationToken)

Commits the same prepared batch once or resolves an existing exact receipt.

ValueTask<SagaTransitionCommitResult> CommitAsync(SagaPreparedTransition transition, CancellationToken cancellationToken)

Parameters

transition SagaPreparedTransition

The immutable prepared attempt, retained across uncertain commit outcomes.

cancellationToken CancellationToken

The operation cancellation token.

Returns

ValueTask<SagaTransitionCommitResult>

The positively known outcome, or Unknown when commit cannot be resolved.

FindCommittedDeliveryAsync(SagaDeliveryIdentity, CancellationToken)

Synchronizes with outstanding commits and looks up the original delivery before handler execution or payload preparation.

ValueTask<SagaTransitionCommitResult> FindCommittedDeliveryAsync(SagaDeliveryIdentity identity, CancellationToken cancellationToken)

Parameters

identity SagaDeliveryIdentity

The original delivery authority, independent of a new speculative transition identifier.

cancellationToken CancellationToken

The operation cancellation token.

Returns

ValueTask<SagaTransitionCommitResult>

DeliveryAlreadyCommitted and its durable version, or NotFound only after synchronized absence is established.

Remarks

A lookup error or unresolved outstanding transaction must never be converted to NotFound.

HasOwnedTimeoutIdentityAsync(SagaScopeIdentity, string, CancellationToken)

Establishes whether an identity is a retained owned timeout in the authoritative scope.

ValueTask<bool> HasOwnedTimeoutIdentityAsync(SagaScopeIdentity identity, string deliveryId, CancellationToken cancellationToken)

Parameters

identity SagaScopeIdentity

The exact current outer-authoritative saga scope.

deliveryId string

The original nonempty opaque identity being tested.

cancellationToken CancellationToken

The operation cancellation token.

Returns

ValueTask<bool>

True for any retained owned timeout identity, including cancelled or previously delivered ones.

Remarks

False means positively established synchronized absence in this scope, never a lookup error, missing schema or unsupported capability. This is not a probe of other tenants. Manual-timeout admission must refuse a known owned identity even when origin metadata was stripped. Ordinary queue acceptance retirement must retain this authority. Exact ordinal ID matching is required.

IsTimeoutDeliveryCurrentAsync(SagaTimeoutDeliveryIdentity, CancellationToken)

Synchronizes with cancellation/completion and validates an original owned timeout delivery.

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

Parameters

delivery SagaTimeoutDeliveryIdentity

The original claimed timeout authority, preserved through delivery metadata.

cancellationToken CancellationToken

The operation cancellation token.

Returns

ValueTask<bool>

True for a currently eligible owned timeout, false only for positively known obsolete authority.

Remarks

Missing/corrupt/mismatched authority or lookup failure must throw, never become a false no-op. A missing timer payload row alone is not obsolete: worker retirement can follow durable queue acceptance before the handler executes. The retained membership, scope incarnation/generation, and cancellation tombstone establish authority. Outer wrappers enforce the exact current tenant. A concurrent cancellation after this check must still defeat the eventual transition CAS.

LoadSnapshotAsync(SagaScopeIdentity, CancellationToken)

Loads a lock-synchronized scope/state snapshot without allocating a new speculative transition.

ValueTask<SagaDurableSnapshot?> LoadSnapshotAsync(SagaScopeIdentity identity, CancellationToken cancellationToken)

Parameters

identity SagaScopeIdentity

The exact tenant and saga storage scope.

cancellationToken CancellationToken

The operation cancellation token.

Returns

ValueTask<SagaDurableSnapshot>

The authoritative snapshot, or null only after synchronized absence is established.

Remarks

A mismatched type, hash collision or unsupported legacy row must refuse, never masquerade as an absent scope.

ValidateTimerParticipantAsync(SagaScopeIdentity, ISagaAtomicTimeoutParticipant, CancellationToken)

Refuses an incompatible selected timer backend/table before the handler executes.

ValueTask ValidateTimerParticipantAsync(SagaScopeIdentity identity, ISagaAtomicTimeoutParticipant participant, CancellationToken cancellationToken)

Parameters

identity SagaScopeIdentity

The current outer-authoritative tenant and saga scope.

participant ISagaAtomicTimeoutParticipant

The actual selected timeout-store participant.

cancellationToken CancellationToken

The operation cancellation token.

Returns

ValueTask

A completed operation only when the known logical writer binding agrees.

Remarks

This pure admission check uses the kernel's own frozen unopened target and exact writer table; it must not open connections, persist, commit, dispatch or infer physical alias equivalence. It does not prevent subsequent configuration changes. Commit must still compare the same digested participant binding against its ACTUAL open transaction/writer before any writes. Outer wrappers must revalidate the supplied authority and selected inner capability per call.