Experimental Runtime Control Roadmap

using System;
using System.ComponentModel.DataAnnotations;

namespace LmRuntime.RoadmapSample;

/// <summary>Defines host-owned limits for one bounded runtime trial.</summary>
public sealed class AdaptiveRuntimeBudget
{
    /// <summary>Gets the maximum number of generated tokens.</summary>
    [Display(Name = "Maximum Generated Tokens")]
    public int MaximumGeneratedTokens { get; init; } = 256;

    /// <summary>Gets the maximum elapsed time for the trial.</summary>
    [Display(Name = "Maximum Elapsed")]
    public TimeSpan MaximumElapsed { get; init; } = TimeSpan.FromSeconds(30);

    /// <summary>Gets the maximum number of recovery cycles.</summary>
    [Display(Name = "Maximum Recovery Cycles")]
    public int MaximumRecoveryCycles { get; init; } = 1;
}

/// <summary>Describes evidence observed by the host after a bounded step.</summary>
public sealed class AdaptiveRuntimeObservation
{
    /// <summary>Gets the UTC time at which the observation was captured.</summary>
    [Display(Name = "Observed At UTC")]
    public required DateTimeOffset ObservedAtUtc { get; init; }

    /// <summary>Gets the elapsed duration of the current trial.</summary>
    [Display(Name = "Elapsed")]
    public required TimeSpan Elapsed { get; init; }

    /// <summary>Gets the number of tokens generated by the current trial.</summary>
    [Display(Name = "Generated Tokens")]
    public int GeneratedTokens { get; init; }

    /// <summary>Gets the number of recovery cycles already consumed.</summary>
    [Display(Name = "Recovery Cycles")]
    public int RecoveryCycles { get; init; }

    /// <summary>Gets a value indicating whether operator cancellation was requested.</summary>
    [Display(Name = "Cancellation Requested")]
    public bool CancellationRequested { get; init; }

    /// <summary>Gets a value indicating whether all required evidence fields are present.</summary>
    [Display(Name = "Evidence Complete")]
    public bool EvidenceComplete { get; init; }

    /// <summary>Gets a value indicating whether the required backend is available.</summary>
    [Display(Name = "Required Backend Available")]
    public bool RequiredBackendAvailable { get; init; }

    /// <summary>Gets a value indicating whether recovery was requested.</summary>
    [Display(Name = "Recovery Requested")]
    public bool RecoveryRequested { get; init; }

    /// <summary>Gets a value indicating whether the saved state matches the model and configuration fingerprints.</summary>
    [Display(Name = "Checkpoint Compatible")]
    public bool CheckpointCompatible { get; init; }
}

/// <summary>Lists the only actions the experimental host policy may select.</summary>
public enum AdaptiveRuntimeAction
{
    /// <summary>Continues without changing runtime configuration.</summary>
    NoOpContinue,

    /// <summary>Signals cooperative cancellation.</summary>
    Cancel,

    /// <summary>Restores a previously validated compatible state.</summary>
    RestoreCompatibleState,

    /// <summary>Stops because a required condition is unavailable.</summary>
    FailClosed,

    /// <summary>Ends the trial at a declared resource boundary.</summary>
    Terminate
}

/// <summary>Represents a typed policy decision and its reviewable reason.</summary>
public sealed class AdaptiveRuntimeDecision
{
    /// <summary>Gets the selected host action.</summary>
    [Display(Name = "Action")]
    public required AdaptiveRuntimeAction Action { get; init; }

    /// <summary>Gets the deterministic reason for the decision.</summary>
    [Display(Name = "Reason")]
    public required string Reason { get; init; }
}

/// <summary>Evaluates observations without granting authority to model output.</summary>
public static class EvidenceGatedRuntimePolicy
{
    /// <summary>Chooses one host action from the closed experimental allowlist.</summary>
    /// <param name="observation">The typed evidence captured after a bounded runtime step.</param>
    /// <param name="budget">The immutable host-owned limits for the current trial.</param>
    /// <returns>A deterministic action and reason for the evidence ledger.</returns>
    public static AdaptiveRuntimeDecision Evaluate(
        AdaptiveRuntimeObservation observation,
        AdaptiveRuntimeBudget budget)
    {
        ArgumentNullException.ThrowIfNull(observation);
        ArgumentNullException.ThrowIfNull(budget);

        if (observation.CancellationRequested)
        {
            return Decide(AdaptiveRuntimeAction.Cancel, "Operator cancellation requested.");
        }

        if (!observation.EvidenceComplete || !observation.RequiredBackendAvailable)
        {
            return Decide(AdaptiveRuntimeAction.FailClosed, "A required evidence or backend condition is unavailable.");
        }

        if (observation.Elapsed >= budget.MaximumElapsed)
        {
            return Decide(AdaptiveRuntimeAction.Cancel, "The elapsed-time budget was reached.");
        }

        if (observation.GeneratedTokens >= budget.MaximumGeneratedTokens)
        {
            return Decide(AdaptiveRuntimeAction.Terminate, "The generated-token budget was reached.");
        }

        if (observation.RecoveryRequested)
        {
            if (!observation.CheckpointCompatible || observation.RecoveryCycles >= budget.MaximumRecoveryCycles)
            {
                return Decide(AdaptiveRuntimeAction.FailClosed, "Recovery is incompatible or its budget is exhausted.");
            }

            return Decide(AdaptiveRuntimeAction.RestoreCompatibleState, "A compatible checkpoint was approved for bounded recovery.");
        }

        return Decide(AdaptiveRuntimeAction.NoOpContinue, "The run remains valid; no change is justified.");
    }

    /// <summary>Creates a typed decision record.</summary>
    /// <param name="action">The selected allowlisted host action.</param>
    /// <param name="reason">The deterministic reason retained as evidence.</param>
    /// <returns>A new decision record.</returns>
    private static AdaptiveRuntimeDecision Decide(AdaptiveRuntimeAction action, string reason) =>
        new() { Action = action, Reason = reason };
}