Machine Intelligence Runtime Quickstart

using System.ComponentModel.DataAnnotations;

/// <summary>Requests creation of a governed runtime run.</summary>
public sealed record RunRequest
{
    /// <summary>Gets the externally authorized objective.</summary>
    [Display(Name = "Objective")]
    public required string Objective { get; init; }

    /// <summary>Gets the success conditions evaluated before completion.</summary>
    [Display(Name = "Success Criteria")]
    public required IReadOnlyList<string> SuccessCriteria { get; init; }

    /// <summary>Gets the latest instant at which the run may continue.</summary>
    [Display(Name = "Deadline At Utc")]
    public required DateTimeOffset DeadlineAtUtc { get; init; }
}

/// <summary>Defines the immutable controls applied to a run.</summary>
public sealed record RuntimeContract
{
    /// <summary>Gets the stable contract version.</summary>
    [Display(Name = "Contract Version")]
    public required string ContractVersion { get; init; }

    /// <summary>Gets the allowed tool keys.</summary>
    [Display(Name = "Allowed Tools")]
    public required IReadOnlySet<string> AllowedTools { get; init; }

    /// <summary>Gets the maximum orchestration steps.</summary>
    [Display(Name = "Maximum Steps")]
    public required int MaximumSteps { get; init; }
}

/// <summary>Creates and advances governed runs.</summary>
public interface IRuntimeOrchestrator
{
    /// <summary>Creates a durable run in the created state.</summary>
    /// <param name="request">The external objective and success criteria.</param>
    /// <param name="contract">The immutable runtime controls.</param>
    /// <param name="cancellationToken">Signals cancellation of the I/O operation.</param>
    /// <returns>The stable run identifier.</returns>
    Task<string> CreateRunAsync(
        RunRequest request,
        RuntimeContract contract,
        CancellationToken cancellationToken);

    /// <summary>Executes one validated lifecycle step.</summary>
    /// <param name="runId">The stable run identifier.</param>
    /// <param name="cancellationToken">Signals cancellation of the orchestration step.</param>
    /// <returns>The resulting lifecycle state.</returns>
    Task<string> ExecuteNextStepAsync(
        string runId,
        CancellationToken cancellationToken);
}

/// <summary>Represents an ordered reviewer-facing runtime event.</summary>
public sealed record EvidenceEvent
{
    /// <summary>Gets the event sequence within the run.</summary>
    [Display(Name = "Sequence")]
    public required long Sequence { get; init; }

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

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