Run Lifecycle State Machine

using System.ComponentModel.DataAnnotations;

/// <summary>Defines the durable lifecycle states for a run.</summary>
public enum RunLifecycleState
{
    Created,
    Provisioning,
    Running,
    AwaitingApproval,
    Recovering,
    Completed,
    Failed,
    Terminated
}

/// <summary>Represents one requested state transition.</summary>
public sealed record RunTransition
{
    /// <summary>Gets the source state.</summary>
    [Display(Name = "From State")]
    public required RunLifecycleState FromState { get; init; }

    /// <summary>Gets the destination state.</summary>
    [Display(Name = "To State")]
    public required RunLifecycleState ToState { get; init; }

    /// <summary>Gets the event that requested the transition.</summary>
    [Display(Name = "Event Type")]
    public required string EventType { get; init; }

    /// <summary>Gets the expected optimistic concurrency token.</summary>
    [Display(Name = "Concurrency Token")]
    public required string ConcurrencyToken { get; init; }
}

/// <summary>Validates and persists run transitions.</summary>
public interface IRunStateMachine
{
    /// <summary>Attempts one state transition atomically.</summary>
    /// <param name="runId">The stable run identifier.</param>
    /// <param name="transition">The requested transition and expected token.</param>
    /// <param name="cancellationToken">Signals cancellation of the storage operation.</param>
    /// <returns>True when the transition was applied; otherwise false.</returns>
    Task<bool> TryTransitionAsync(
        string runId,
        RunTransition transition,
        CancellationToken cancellationToken);
}