lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/Runtime/IGalaxyDataWriter.cs

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

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

/// <summary>
///     Driver-side seam for batched writes. Production implementation routes by
///     <see cref="SecurityClassification"/>: SecuredWrite / VerifiedWrite go through
///     <c>MxCommandKind.WriteSecured</c>, everything else through
///     <c>MxGatewaySession.WriteAsync</c>. Tests substitute a fake to record routing
///     decisions without touching real gw infrastructure.
/// </summary>
public interface IGalaxyDataWriter
{
    /// <summary>
    ///     Write each <paramref name="writes"/> entry; return one
    ///     <see cref="WriteResult"/> per request entry, in input order. Implementations
    ///     MUST return the same length as the input — partial-tag failures are encoded
    ///     as Bad-status results, not omitted.
    /// </summary>
    /// <param name="writes">Pairs of full reference + value to write.</param>
    /// <param name="securityResolver">
    ///     Maps a full reference to its discovered <see cref="SecurityClassification"/>
    ///     so the writer can route SecuredWrite / VerifiedWrite tags through the
    ///     <c>WriteSecured</c> command instead of <c>Write</c>. Returns
    ///     <see cref="SecurityClassification.FreeAccess"/> when the tag isn't tracked
    ///     (the safest default — non-secured Write).
    /// </param>
    /// <param name="cancellationToken">Aborts the in-flight batch.</param>
    /// <returns>One <see cref="WriteResult"/> per request entry, in input order.</returns>
    Task<IReadOnlyList<WriteResult>> WriteAsync(
        IReadOnlyList<WriteRequest> writes,
        Func<string, SecurityClassification> securityResolver,
        CancellationToken cancellationToken);

    /// <summary>Drop cached gateway item handles + supervisory-advise state. Call after a session
    /// reconnect — the prior handles are dead, so the next write must re-AddItem + re-AdviseSupervisory.</summary>
    void InvalidateHandleCaches();
}