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

/// <summary>
///     Optional control-plane capability — drivers whose backend exposes a way to refresh
///     the symbol table on-demand (without tearing the driver down) implement this so the
///     Admin UI / CLI can trigger a re-walk in response to an operator action.
/// </summary>
/// <remarks>
///     Distinct from <see cref="IRediscoverable"/>: that interface is the driver telling Core
///     a refresh is needed; this one is Core asking the driver to refresh now. For drivers that
///     implement both, the typical wiring is "operator clicks Rebrowse → Core calls
///     <see cref="RebrowseAsync"/> → driver re-walks → driver fires
///     <c>OnRediscoveryNeeded</c> so the address space is rebuilt".
///
///     For AB CIP this is the "force re-walk of @tags" hook — useful after a controller
///     program download added new tags but the static config still drives the address space.
/// </remarks>
public interface IDriverControl
{
    /// <summary>
    ///     Re-run the driver's discovery pass against live backend state and stream the
    ///     resulting nodes through the supplied builder. Implementations must be safe to call
    ///     concurrently with reads / writes; they typically serialize internally so a second
    ///     concurrent rebrowse waits for the first to complete rather than racing it.
    /// </summary>
    Task RebrowseAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken);
}