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

/// <summary>
///     Optional driver capability — drivers whose backend has a native change signal
///     (Galaxy <c>time_of_last_deploy</c>, OPC UA server change notifications, TwinCAT
///     symbol-version-changed) implement this to tell Core when to re-run discovery.
/// </summary>
/// <remarks>
///     Per <c>docs/v2/plan.md</c> decision #54 — static drivers (Modbus, S7, etc. whose tags
///     only change via a published config generation) don't implement <c>IRediscoverable</c>.
///     The Core just sees absence of the interface and skips change-detection wiring for that driver.
/// </remarks>
public interface IRediscoverable
{
    /// <summary>
    ///     Fired when the driver's backend signals that the address space may have changed.
    ///     The Core's response is to re-run <see cref="ITagDiscovery.DiscoverAsync"/> and
    ///     diff the result against the current address space.
    /// </summary>
    event EventHandler<RediscoveryEventArgs>? OnRediscoveryNeeded;
}

/// <summary>Event payload for <see cref="IRediscoverable.OnRediscoveryNeeded"/>.</summary>
/// <param name="Reason">Driver-supplied reason string for the diagnostic log (e.g. "Galaxy time_of_last_deploy advanced", "TwinCAT symbol-version-changed 0x0702").</param>
/// <param name="ScopeHint">
///     Optional hint about which subtree changed. Null means "the whole address space may have changed".
///     A non-null value (e.g. a folder path) lets the Core scope the rebuild surgically.
/// </param>
public sealed record RediscoveryEventArgs(string Reason, string? ScopeHint);