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

namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Runtime;

/// <summary>
///     Driver-side seam for one-shot reads. Production implementation (PR 4.4) wraps
///     <c>MxGatewaySession</c>'s SubscribeBulk + StreamEvents path to obtain values; tests
///     substitute a fake returning canned snapshots.
/// </summary>
/// <remarks>
///     The interface is deliberately minimal — no per-tag overload, no continuation
///     points. The driver-side <c>IReadable.ReadAsync</c> contract guarantees a value per
///     requested tag in input order, with status codes carrying the per-tag failure mode
///     (e.g. BadInternalError for transport failure on a single tag, BadOutOfService for
///     a tag the gateway didn't recognise).
/// </remarks>
public interface IGalaxyDataReader
{
    /// <summary>
    ///     Read each <paramref name="fullReferences"/> entry once and return one
    ///     <see cref="DataValueSnapshot"/> per request entry, in input order.
    ///     Implementations MUST return the same length as the input — partial-tag
    ///     failures are encoded as Bad-quality snapshots, not omitted.
    /// </summary>
    /// <param name="fullReferences">The list of fully-qualified tag references to read.</param>
    /// <param name="cancellationToken">Cancellation token for the read operation.</param>
    /// <returns>A list of data value snapshots, one per input reference in the same order.</returns>
    Task<IReadOnlyList<DataValueSnapshot>> ReadAsync(
        IReadOnlyList<string> fullReferences, CancellationToken cancellationToken);
}
