Memory, Context, and Lineage for MIR

using System.ComponentModel.DataAnnotations;

/// <summary>Contains the sealed context delivered to a model adapter.</summary>
public sealed record ContextPackage
{
    /// <summary>Gets the package version.</summary>
    [Display(Name = "Package Version")]
    public required string PackageVersion { get; init; }

    /// <summary>Gets the selected source records.</summary>
    [Display(Name = "Sources")]
    public required IReadOnlyList<ContextSourceRecord> Sources { get; init; }

    /// <summary>Gets when the package was sealed.</summary>
    [Display(Name = "Sealed At Utc")]
    public required DateTimeOffset SealedAtUtc { get; init; }
}

/// <summary>Describes one attributable context source.</summary>
public sealed record ContextSourceRecord
{
    /// <summary>Gets the stable source identifier.</summary>
    [Display(Name = "Source")]
    public required string SourceId { get; init; }

    /// <summary>Gets the content hash.</summary>
    [Display(Name = "Content Hash")]
    public required string ContentHash { get; init; }

    /// <summary>Gets why the source was selected.</summary>
    [Display(Name = "Selection Reason")]
    public required string SelectionReason { get; init; }
}

/// <summary>Assembles authorized context for a run step.</summary>
public interface IContextAssembler
{
    /// <summary>Builds and seals a context package.</summary>
    /// <param name="runId">The stable run identifier.</param>
    /// <param name="cancellationToken">Signals cancellation of retrieval and validation.</param>
    /// <returns>The sealed context package.</returns>
    Task<ContextPackage> AssembleAsync(string runId, CancellationToken cancellationToken);
}

/// <summary>Represents a governed durable memory projection.</summary>
public sealed record MemoryRecord
{
    /// <summary>Gets the memory scope.</summary>
    [Display(Name = "Scope")]
    public required string Scope { get; init; }

    /// <summary>Gets when the record expires, when configured.</summary>
    [Display(Name = "Expires At Utc")]
    public DateTimeOffset? ExpiresAtUtc { get; init; }
}

/// <summary>Stores governed memory projections.</summary>
public interface IMemoryProjectionStore
{
    /// <summary>Upserts one authorized memory record.</summary>
    /// <param name="record">The governed memory projection.</param>
    /// <param name="cancellationToken">Signals cancellation of storage I/O.</param>
    Task UpsertAsync(MemoryRecord record, CancellationToken cancellationToken);
}