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

/// <summary>
///     Driver capability for on-demand writes. Optional — read-only drivers (a hypothetical
///     historian-only adapter, for example) can omit this.
/// </summary>
/// <remarks>
///     Per <c>docs/v2/plan.md</c> decisions #44 + #45 — <b>writes are NOT auto-retried by default</b>.
///     A timeout may fire after the device already accepted the command; replaying non-idempotent
///     field actions (pulses, alarm acks, recipe steps, counter increments) can cause duplicate
///     operations. Per-tag opt-in via <c>Tag.WriteIdempotent = true</c> in the central config DB
///     enables retry; otherwise the OPC UA client decides whether to re-issue.
/// </remarks>
public interface IWritable
{
    /// <summary>
    ///     Write a batch of values to the driver. Returns one status per requested write,
    ///     in the same order.
    /// </summary>
    /// <param name="writes">Pairs of full reference + value to write.</param>
    /// <param name="cancellationToken">Cancellation token; the driver should abort the batch if cancelled.</param>
    Task<IReadOnlyList<WriteResult>> WriteAsync(
        IReadOnlyList<WriteRequest> writes,
        CancellationToken cancellationToken);
}

/// <summary>One write request in a batch.</summary>
/// <param name="FullReference">Driver-side full reference (matches <see cref="DriverAttributeInfo.FullName"/>).</param>
/// <param name="Value">Value to write; type must be compatible with the attribute's <see cref="DriverDataType"/>.</param>
public sealed record WriteRequest(string FullReference, object? Value);

/// <summary>Result of one write in a batch.</summary>
/// <param name="StatusCode">OPC UA status code (numeric value matches the OPC UA spec).</param>
public sealed record WriteResult(uint StatusCode);