Observability and Evidence for AI Runtimes

using System.ComponentModel.DataAnnotations;

/// <summary>Represents an ordered evidence event.</summary>
public sealed record EvidenceEvent
{
    /// <summary>Gets the stable event type.</summary>
    [Display(Name = "Event Type")]
    public required string EventType { get; init; }

    /// <summary>Gets the sequence within the run.</summary>
    [Display(Name = "Sequence")]
    public required long Sequence { get; init; }

    /// <summary>Gets the event instant.</summary>
    [Display(Name = "Occurred At Utc")]
    public required DateTimeOffset OccurredAtUtc { get; init; }

    /// <summary>Gets the privacy classification.</summary>
    [Display(Name = "Privacy Classification")]
    public required string PrivacyClassification { get; init; }
}

/// <summary>Appends immutable evidence events.</summary>
public interface IEvidenceLedger
{
    /// <summary>Appends an event using optimistic sequence validation.</summary>
    /// <param name="runId">The stable run identifier.</param>
    /// <param name="evidenceEvent">The event to append.</param>
    /// <param name="cancellationToken">Signals cancellation of storage I/O.</param>
    Task AppendAsync(
        string runId,
        EvidenceEvent evidenceEvent,
        CancellationToken cancellationToken);
}