namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     Process-level supervisor contract a Tier C driver's out-of-process topology provides
///     (e.g. <c>Driver.Galaxy.Proxy/Supervisor/</c>). Concerns: restart the Host process when a
///     hard fault is detected (memory breach, wedge, scheduled recycle window).
/// </summary>
/// <remarks>
///     Per <c>docs/v2/plan.md</c> decisions #68, #73-74, and #145. Tier A/B drivers do NOT have
///     a supervisor because they run in-process — recycling would kill every OPC UA session and
///     every co-hosted driver. The Core.Stability layer only invokes this interface for Tier C
///     instances after asserting the tier via <see cref="DriverTypeMetadata.Tier"/>.
/// </remarks>
public interface IDriverSupervisor
{
    /// <summary>Driver instance this supervisor governs.</summary>
    string DriverInstanceId { get; }

    /// <summary>
    ///     Request the supervisor to recycle (terminate + restart) the Host process. Implementations
    ///     are expected to be idempotent under repeat calls during an in-flight recycle.
    /// </summary>
    /// <param name="reason">Human-readable reason — flows into the supervisor's logs.</param>
    /// <param name="cancellationToken">Cancels the recycle request; an in-flight restart is not interrupted.</param>
    Task RecycleAsync(string reason, CancellationToken cancellationToken);
}