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

/// <summary>
///     Fetches the deployed-configuration artifact bytes from central over gRPC (per-cluster mesh
///     Phase 3, <c>FetchAndCache</c> mode). The node-side counterpart of central's
///     <c>DeploymentArtifactService</c>.
/// </summary>
public interface IDeploymentArtifactFetcher
{
    /// <summary>
    ///     Fetches and reassembles the artifact for <paramref name="deploymentId"/> from the first
    ///     configured central endpoint that answers, verifying that
    ///     <c>SHA-256(reassembled bytes)</c> (lowercase hex) equals
    ///     <paramref name="expectedRevisionHash"/> — the hash already carried in the dispatch.
    /// </summary>
    /// <param name="deploymentId">The deployment id to fetch.</param>
    /// <param name="expectedRevisionHash">
    ///     The lowercase-hex SHA-256 the reassembled bytes must match (<c>Deployment.RevisionHash</c>).
    /// </param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>
    ///     The verified artifact bytes, or <see langword="null"/> on ANY failure — every configured
    ///     endpoint unreachable/NotFound, a zero-length stream, or a SHA-256 mismatch. A
    ///     <see langword="null"/> is "no answer," NEVER an empty configuration: the caller treats it as
    ///     an apply failure and keeps last-known-good (the #485 contract).
    /// </returns>
    Task<byte[]?> FetchAsync(string deploymentId, string expectedRevisionHash, CancellationToken ct);
}
