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>
///     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>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task RecycleAsync(string reason, CancellationToken cancellationToken);
}