namespace MS.Microservice.Tasks; public enum JobState { Queued, Running, Succeeded, Failed, Cancelled, Interrupted } public sealed record JobSnapshot(Guid JobId, string Scope, string HandlerName, int HandlerVersion, string PayloadJson, string Queue, int MaximumAttempts, JobState State, int AttemptCount, int Progress, string? ProgressMessage, bool CancellationRequested, DateTimeOffset CreatedAtUtc, DateTimeOffset UpdatedAtUtc, DateTimeOffset NextRunAtUtc, DateTimeOffset? FinishedAtUtc, string? ErrorCode, string? ResultReference); /// Identifies one execution; retain this token for progress and final-state updates. public readonly record struct JobAttemptToken(string Scope, Guid JobId, Guid Token); public sealed record JobExecution(JobSnapshot Job, JobAttemptToken Attempt); public sealed record JobAttemptSnapshot(int Number, JobState State, int Progress, string? ProgressMessage, DateTimeOffset StartedAtUtc, DateTimeOffset? FinishedAtUtc, string? ErrorCode, string? ResultReference); public enum JobUpdateResult { Applied, NotFound, Rejected } public enum JobExecutionStatus { Running, CancellationRequested, Ended } /// The same scope and identity cannot represent different job requests. public sealed class JobSubmissionConflictException(Guid jobId) : InvalidOperationException($"Job {jobId} was already submitted with different parameters."); /// Durable submission and lifecycle storage; no method executes the registered job handler. public interface IJobStore { /// Commits a job independently, using a fresh context and no caller-owned transaction. Task SubmitAsync(JobSubmission submission, CancellationToken cancellationToken = default); /// Tracks a job in the caller's active transaction; the caller must save and commit it. Task StageAsync(JobSubmission submission, CancellationToken cancellationToken = default); Task GetAsync(string scope, Guid jobId, CancellationToken cancellationToken = default); Task> ListAsync(string scope, JobState? state = null, int take = 50, CancellationToken cancellationToken = default); Task> GetAttemptsAsync(string scope, Guid jobId, CancellationToken cancellationToken = default); /// Reads due candidates across scopes for a trusted worker; candidates still require TryStartAsync. Task> GetDueAsync(string queue = "default", int take = 100, CancellationToken cancellationToken = default); /// Reads active execution tokens across scopes for single-instance startup recovery. Task> GetRunningExecutionsAsync(int take = 100, CancellationToken cancellationToken = default); /// Reads control state for the current execution without loading its payload. Task GetExecutionStatusAsync(JobAttemptToken attempt, CancellationToken cancellationToken = default); /// Atomically claims a due queued job and appends a new attempt, or returns null. Task TryStartAsync(string scope, Guid jobId, CancellationToken cancellationToken = default); /// Persists monotonic progress for the current running attempt; stale tokens return false. Task ReportProgressAsync(JobAttemptToken attempt, int progress, string? message = null, CancellationToken cancellationToken = default); /// Completes the current attempt; an earlier committed cancellation request takes precedence. Task CompleteAsync(JobAttemptToken attempt, string? resultReference = null, CancellationToken cancellationToken = default); Task FailAsync(JobAttemptToken attempt, string errorCode, CancellationToken cancellationToken = default); Task InterruptAsync(JobAttemptToken attempt, CancellationToken cancellationToken = default); /// Atomically interrupts an abandoned attempt and optionally requeues it within its attempt budget. Task RecoverAsync(JobAttemptToken attempt, bool allowRetry, CancellationToken cancellationToken = default); /// Cancels a queued job, or records a cooperative cancellation request for its running attempt. Task CancelAsync(string scope, Guid jobId, CancellationToken cancellationToken = default); /// Requeues a failed, interrupted or cancelled job while retaining its identity and attempt history. Task RetryAsync(string scope, Guid jobId, DateTimeOffset? notBeforeUtc = null, CancellationToken cancellationToken = default); }