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

/// <summary>How aggressively the host re-runs post-connect discovery for this driver.</summary>
public enum DiscoveryRediscoverPolicy
{
    /// <summary>Retry every interval up to the cap or until the captured set is non-empty and stable
    /// (for drivers whose discovered shape fills in asynchronously after connect, e.g. the FOCAS FixedTree).</summary>
    UntilStable,
    /// <summary>Run exactly one discovery pass on connect (drivers that discover synchronously in DiscoverAsync).</summary>
    Once,
    /// <summary>Never run post-connect discovery.</summary>
    Never,
}

/// <summary>
///     Driver capability for discovering tags and hierarchy from the backend.
///     Streams discovered nodes into <see cref="IAddressSpaceBuilder"/> rather than
///     buffering the entire tree (supports incremental / large address spaces).
/// </summary>
public interface ITagDiscovery
{
    /// <summary>
    ///     Discover the driver's tag set and stream nodes to the builder.
    ///     The driver decides ordering (root → leaf typically) and may yield as many calls as needed.
    /// </summary>
    /// <param name="builder">The address space builder to stream discovered nodes into.</param>
    /// <param name="cancellationToken">A cancellation token for the discovery operation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task DiscoverAsync(IAddressSpaceBuilder builder, CancellationToken cancellationToken);

    /// <summary>Post-connect re-discovery policy. Default preserves the original retry-until-stable behavior.</summary>
    DiscoveryRediscoverPolicy RediscoverPolicy => DiscoveryRediscoverPolicy.UntilStable;

    /// <summary>
    ///     True when <see cref="DiscoverAsync"/> enumerates the tag set from the live backend
    ///     (browsable by the universal discovery browser), rather than replaying
    ///     pre-declared/authored tags. Default false — flat-address drivers stay manual-entry.
    ///     See docs/plans/2026-07-15-universal-discovery-browser-design.md §5.
    /// </summary>
    bool SupportsOnlineDiscovery => false;
}
