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

/// <summary>
///     One numeric sample the continuous-historization recorder drains to the historian's SQL
///     live-value write path. Carries the minimal payload that path can ingest: an optional UTC
///     timestamp, the coerced numeric value, and an OPC-DA quality byte.
/// </summary>
/// <param name="TimestampUtc">
///     UTC source timestamp of the sample, or <c>null</c> to defer to the historian's server-stamped
///     current-time path (the SQL writer uses <c>SYSDATETIME()</c> when the timestamp is absent).
/// </param>
/// <param name="Value">The coerced numeric value (the SQL analog write path is numeric-only).</param>
/// <param name="Quality">OPC-DA-derived quality code carried to the historian (192 = Good).</param>
public readonly record struct HistorizationValue(DateTime? TimestampUtc, double Value, ushort Quality);

/// <summary>
///     Seam over the historian's live-value write path used by the continuous-historization recorder.
///     Lives in the abstraction layer so the Runtime recorder depends on it without taking a hard
///     reference on the gRPC gateway driver; the gateway driver supplies the concrete adapter
///     (<c>GatewayHistorianValueWriter</c>).
/// </summary>
public interface IHistorianValueWriter
{
    /// <summary>
    ///     Writes a batch of live values for a single tag through the historian's SQL live-write path.
    ///     Implementations are expected to be non-throwing: a transport/gateway error is surfaced as a
    ///     <c>false</c> result so the recorder retains the entries and retries, rather than as an
    ///     exception.
    /// </summary>
    /// <param name="tag">Fully-qualified historian tag the values are recorded against.</param>
    /// <param name="values">The numeric samples to write, in append order.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns><c>true</c> on a successful (or durably-queued) gateway ack; <c>false</c> on a retryable failure.</returns>
    Task<bool> WriteLiveValuesAsync(string tag, IReadOnlyList<HistorizationValue> values, CancellationToken ct);
}
