Durable Execution and Recovery for MIR

using System.ComponentModel.DataAnnotations;

/// <summary>Contains a durable checkpoint reference.</summary>
public sealed record CheckpointRecord
{
    /// <summary>Gets the checkpoint identifier.</summary>
    [Display(Name = "Checkpoint")]
    public required string CheckpointId { get; init; }

    /// <summary>Gets the content hash of checkpoint state.</summary>
    [Display(Name = "State Hash")]
    public required string StateHash { get; init; }

    /// <summary>Gets when the checkpoint was created.</summary>
    [Display(Name = "Created At Utc")]
    public required DateTimeOffset CreatedAtUtc { get; init; }
}

/// <summary>Stores and retrieves durable checkpoints.</summary>
public interface ICheckpointStore
{
    /// <summary>Creates a checkpoint before a material effect.</summary>
    /// <param name="runId">The stable run identifier.</param>
    /// <param name="cancellationToken">Signals cancellation of checkpoint I/O.</param>
    /// <returns>The created checkpoint record.</returns>
    Task<CheckpointRecord> CreateAsync(string runId, CancellationToken cancellationToken);
}

/// <summary>Describes an authorized recovery plan.</summary>
public sealed record RecoveryPlan
{
    /// <summary>Gets the recovery strategy.</summary>
    [Display(Name = "Strategy")]
    public required string Strategy { get; init; }

    /// <summary>Gets the checkpoint to restore when required.</summary>
    [Display(Name = "Checkpoint")]
    public string? CheckpointId { get; init; }
}

/// <summary>Coordinates validated recovery.</summary>
public interface IRecoveryCoordinator
{
    /// <summary>Builds a bounded recovery plan.</summary>
    /// <param name="runId">The stable run identifier.</param>
    /// <param name="cancellationToken">Signals cancellation of diagnosis I/O.</param>
    /// <returns>The proposed recovery plan.</returns>
    Task<RecoveryPlan> PlanAsync(string runId, CancellationToken cancellationToken);
}

/// <summary>Stores command and effect identities for deduplication.</summary>
public interface IIdempotencyStore
{
    /// <summary>Attempts to reserve an idempotency key.</summary>
    /// <param name="key">The stable command key.</param>
    /// <param name="cancellationToken">Signals cancellation of storage I/O.</param>
    /// <returns>True when the key was reserved by this caller.</returns>
    Task<bool> TryReserveAsync(string key, CancellationToken cancellationToken);
}