Table of Contents

Interface IScheduleExecutionFailureStore

Namespace
Excalibur.Dispatch.Delivery
Assembly
Excalibur.Dispatch.Abstractions.dll

Same-authority admission policy, bounded failure retention and explicit quarantine recovery. Budget capture/grant/count, failure/disable, and recovery/receipt/history each share one atomic boundary. Query tenant IDs are exact partitions supplied by an authorized caller, not authorization credentials.

public interface IScheduleExecutionFailureStore : IScheduleExecutionStore, IScheduleStore
Inherited Members
Extension Methods

Remarks

The first budgeted admission atomically captures the positive requested limit with grant/count before dispatch. Later requests, even with a different positive limit, return UsedExisting and the stored limit; neither inherited admission nor progress may erase captured policy/history for an unsettled occurrence. Consumed unbudgeted legacy history refuses upgrade with an actionable exception. Failure/disable and recovery/history/receipt mutations share the existing authority transaction. Recovery compares the exact token, creates a fresh generation with count zero and the SAME captured budget, and retains original provenance. The next ordinary acquisition creates execution ownership. Same command/token returns its original receipt after later progress and restart; conflicting command or token cannot grant another reset. Ordinary administration cannot erase unresolved provenance: replacement refuses any captured unsettled/recovery epoch, even before a failure write succeeds. Complete atomically retains such an occurrence as administrative quarantine, clearing execution ownership and disabling without losing the generation, original payload, count or captured budget. Already quarantined completion is idempotent. Normal uncaptured administration keeps its prior contract. Cancellation observed before mutation leaves state unchanged. In-flight cancellation/unknown reply does not establish rollback; reconcile exact durable state before claiming failure or success. Query cursors use ordinal Guid.ToString("N") order, exclusive and weakly consistent during inserts; they are bounded observations, not a transaction-snapshot pagination guarantee.

Methods

GetOccurrenceFailureAsync(Guid, Guid, DateTimeOffset, string?, CancellationToken)

Reads exact retained provenance in one tenant partition, including resolved quarantine history.

Task<ScheduleOccurrenceFailureSnapshot?> GetOccurrenceFailureAsync(Guid scheduleId, Guid generation, DateTimeOffset occurrenceUtc, string? tenantId, CancellationToken cancellationToken)

Parameters

scheduleId Guid

Schedule identifier.

generation Guid

Original failure generation.

occurrenceUtc DateTimeOffset

Original occurrence.

tenantId string

Exact tenant partition, including null.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ScheduleOccurrenceFailureSnapshot>

Detached matching provenance or null.

GetQuarantinesAsync(string?, Guid?, int, CancellationToken)

Reads a bounded stable quarantine page for one exact tenant partition; resolved history is retained.

Task<IReadOnlyList<ScheduleOccurrenceFailureSnapshot>> GetQuarantinesAsync(string? tenantId, Guid? afterQuarantineId, int maximumCount, CancellationToken cancellationToken)

Parameters

tenantId string

Exact tenant partition, including null.

afterQuarantineId Guid?

Exclusive stable GUID cursor, or null for the first page.

maximumCount int

Page size from1 through256.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<ScheduleOccurrenceFailureSnapshot>>

Detached provenance ordered by the ordinal Guid.ToString("N") ordering.

TryAcquireExecutionAsync(Guid, Guid, DateTimeOffset, int, CancellationToken)

Captures policy on the first authoritative grant, or returns existing policy without widening it.

Task<ScheduleFailureExecutionAdmission?> TryAcquireExecutionAsync(Guid scheduleId, Guid generation, DateTimeOffset occurrenceUtc, int requestedMaxAdmissionAttempts, CancellationToken cancellationToken)

Parameters

scheduleId Guid

Schedule identifier.

generation Guid

Observed administrative generation.

occurrenceUtc DateTimeOffset

Exact due occurrence.

requestedMaxAdmissionAttempts int

Positive proposed automatic budget.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ScheduleFailureExecutionAdmission>

Admission and explicit captured-policy observation; null for ordinary authority contention.

Exceptions

InvalidOperationException

Consumed legacy admission history has no captured budget; explicit repair is required.

TryCompleteExecutionAsync(ScheduleExecutionLease, ScheduleExecutionResult, ScheduleExecutionCompletionDisposition, CancellationToken)

Conditionally retires a fulfilled occurrence or explicitly policy-skipped first-grant work.

Task<bool> TryCompleteExecutionAsync(ScheduleExecutionLease lease, ScheduleExecutionResult result, ScheduleExecutionCompletionDisposition disposition, CancellationToken cancellationToken)

Parameters

lease ScheduleExecutionLease

Exact current unexpired authority.

result ScheduleExecutionResult

Bounded progress.

disposition ScheduleExecutionCompletionDisposition

Actual successful dispatch or an intentional catchup policy disposition.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

True only on first confirmed atomic completion; false grants no reset or progress.

Remarks

Fulfilled is the caller assertion of actual successful dispatch, not provider proof. PolicySkipped and PolicyDisabled require provider-stored count one, no failure or recovered-work lineage and unchanged LastExecutionUtc. PolicyDisabled requires Disable; enabled completion requires a next occurrence strictly after the admitted occurrence. Inherited progress refuses captured-policy work. The provider rechecks these facts; caller-supplied AdmissionAttempt/policy observations are not authority.

TryRecordFailureAsync(ScheduleExecutionLease, ScheduleOccurrenceFailure, CancellationToken)

Conditionally records failure without resetting budget/count or advancing the occurrence; quarantine also disables it.

Task<bool> TryRecordFailureAsync(ScheduleExecutionLease lease, ScheduleOccurrenceFailure failure, CancellationToken cancellationToken)

Parameters

lease ScheduleExecutionLease

Exact current unexpired authority.

failure ScheduleOccurrenceFailure

Bounded reason and requested disposition.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

True only after confirmed atomic mutation. False never authorizes ordinary progress.

TryResumeQuarantinedOccurrenceAsync(ScheduleQuarantineToken, Guid, CancellationToken)

Resumes one unresolved quarantine under exact expected state and an idempotent command.

Task<ScheduleQuarantineRecoveryReceipt?> TryResumeQuarantinedOccurrenceAsync(ScheduleQuarantineToken expectedQuarantineToken, Guid recoveryCommandId, CancellationToken cancellationToken)

Parameters

expectedQuarantineToken ScheduleQuarantineToken

Exact provider-owned quarantine identity/version.

recoveryCommandId Guid

Nonempty durable command identifier.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<ScheduleQuarantineRecoveryReceipt>

The same durable receipt on identical command replay; null on conflicting expected state/command.