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

/// <summary>
///     Required capability for every driver instance. Owns lifecycle, metadata, health.
///     Other capabilities (<see cref="ITagDiscovery"/>, <see cref="IReadable"/>,
///     <see cref="IWritable"/>, <see cref="ISubscribable"/>, <see cref="IAlarmSource"/>,
///     <see cref="IHistoryProvider"/>, <see cref="IRediscoverable"/>,
///     <see cref="IHostConnectivityProbe"/>) are composable — a driver implements only what its
///     backend actually supports.
/// </summary>
/// <remarks>
///     Per <c>docs/v2/plan.md</c> decisions #4 (composable capability interfaces) and #53
///     (capability discovery via <c>is</c> checks — no redundant flag enum).
/// </remarks>
public interface IDriver
{
    /// <summary>Stable logical ID of this driver instance, sourced from the central config DB.</summary>
    string DriverInstanceId { get; }

    /// <summary>Driver type name (e.g. "Galaxy", "ModbusTcp", "AbCip"). Matches <c>DriverInstance.DriverType</c>.</summary>
    string DriverType { get; }

    /// <summary>Initialize the driver from its <c>DriverConfig</c> JSON; open connections; prepare for first use.</summary>
    Task InitializeAsync(string driverConfigJson, CancellationToken cancellationToken);

    /// <summary>
    ///     Apply a config change in place without tearing down the driver process.
    ///     Used by <c>IGenerationApplier</c> when only this driver's config changed in the new generation.
    /// </summary>
    /// <remarks>
    ///     Per <c>docs/v2/driver-stability.md</c> §"In-process only (Tier A/B)" — Reinitialize is the
    ///     only Core-initiated recovery path for in-process drivers; if it fails, the driver instance
    ///     is marked Faulted and its nodes go Bad quality, but the server process keeps running.
    /// </remarks>
    Task ReinitializeAsync(string driverConfigJson, CancellationToken cancellationToken);

    /// <summary>Stop the driver, close connections, release resources. Called on shutdown or driver removal.</summary>
    Task ShutdownAsync(CancellationToken cancellationToken);

    /// <summary>Current health snapshot, polled by Core for the status dashboard and ServiceLevel.</summary>
    DriverHealth GetHealth();

    /// <summary>
    ///     Approximate driver-attributable footprint in bytes (caches, queues, symbol tables).
    ///     Polled every 30s by Core; on cache-budget breach, Core asks the driver to flush via
    ///     <see cref="FlushOptionalCachesAsync"/>.
    /// </summary>
    /// <remarks>
    ///     Per <c>docs/v2/driver-stability.md</c> §"In-process only (Tier A/B) — driver-instance
    ///     allocation tracking". Tier C drivers (process-isolated) report through the same
    ///     interface but the cache-flush is internal to their host.
    /// </remarks>
    long GetMemoryFootprint();

    /// <summary>
    ///     Drop optional caches (symbol cache, browse cache, etc.) to bring footprint back below budget.
    ///     Required-for-correctness state must NOT be flushed.
    /// </summary>
    Task FlushOptionalCachesAsync(CancellationToken cancellationToken);
}