using ZB.MOM.WW.OtOpcUa.Commons.Messages.Deploy;

namespace ZB.MOM.WW.OtOpcUa.Runtime.Communication;

/// <summary>
///     Posts this node's deployment acknowledgment to central over the <c>mesh_transport.v1</c>
///     command plane (mesh gRPC command plane, Phase 1B). The seam
///     <see cref="NodeCommunicationActor"/> uses under <c>MeshTransport:Mode = Grpc</c>, in place of
///     the node-local DistributedPubSub publish it uses under <c>Dps</c>.
/// </summary>
/// <remarks>
///     <para>
///         <b>One ack per node per dispatch.</b> Whatever the implementation does about redundancy, it
///         posts to <i>one</i> central endpoint at a time rather than fanning out — the semantic of the
///         one-ack-per-node-per-dispatch semantic the deploy coordinator counts on.
///         This is <b>defence in depth, not a correctness dependency</b>: the coordinator counts acks
///         in a <c>NodeId</c>-keyed dictionary behind an expected-set membership guard
///         (<c>ConfigPublishCoordinator.HandleAck</c>), so a duplicate from one node overwrites its own
///         entry and cannot inflate the count or seal a deployment early. What fan-out would actually
///         cost is duplicated work at central, doubled deploy-ack rows written, and a transport whose
///         delivery count nobody can reason about — none of which is worth having.
///     </para>
///     <para>
///         <b>Fire-and-forget, and it never throws.</b> The caller is an actor that discards the
///         returned task, so an exception escaping here would become an unobserved task fault — the
///         silent drop this migration exists to remove. An implementation reports failure by logging
///         and returning, never by faulting the task.
///     </para>
/// </remarks>
public interface IApplyAckSender
{
    /// <summary>Posts <paramref name="ack"/> to central, or logs why it could not be.</summary>
    /// <param name="ack">The per-node apply acknowledgment.</param>
    /// <param name="cancellationToken">Cancels the in-flight call.</param>
    /// <returns>
    ///     A task that completes when the attempt finishes, successfully or not. It never faults —
    ///     see the remarks.
    /// </returns>
    Task SendAsync(ApplyAck ack, CancellationToken cancellationToken = default);
}