using Akka.Actor;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Artifacts;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.DebugView;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Deployment;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Health;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.InboundApi;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Integration;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Lifecycle;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.RemoteQuery;
using ZB.MOM.WW.ScadaBridge.Communication.Actors;

namespace ZB.MOM.WW.ScadaBridge.Communication;

/// <summary>
/// Central-side service that wraps the Akka Ask pattern with per-pattern timeouts.
/// Provides a typed API for sending messages to sites and awaiting responses.
/// On connection drop, the ask times out (no central buffering per design).
/// </summary>
public class CommunicationService
{
    private readonly CommunicationOptions _options;
    private readonly ILogger<CommunicationService> _logger;
    private IActorRef? _centralCommunicationActor;
    private IActorRef? _notificationOutboxProxy;
    private IActorRef? _siteCallAuditProxy;

    /// <summary>
    /// Initializes a new instance of the CommunicationService.
    /// </summary>
    /// <param name="options">Communication service configuration options.</param>
    /// <param name="logger">Logger instance.</param>
    public CommunicationService(
        IOptions<CommunicationOptions> options,
        ILogger<CommunicationService> logger)
    {
        _options = options.Value;
        _logger = logger;
    }

    /// <summary>
    /// Sets the central communication actor reference. Called during actor system startup.
    /// </summary>
    /// <param name="centralCommunicationActor">The central communication actor reference.</param>
    public void SetCommunicationActor(IActorRef centralCommunicationActor)
    {
        _centralCommunicationActor = centralCommunicationActor;
    }

    /// <summary>
    /// Sets the notification-outbox singleton proxy reference. Called during actor
    /// system startup. The outbox actor is central-local, so outbox calls Ask this
    /// proxy directly (no SiteEnvelope routing).
    /// </summary>
    /// <param name="notificationOutboxProxy">The notification outbox proxy reference.</param>
    public void SetNotificationOutbox(IActorRef notificationOutboxProxy)
    {
        _notificationOutboxProxy = notificationOutboxProxy;
    }

    /// <summary>
    /// Sets the Site Call Audit (#22) singleton proxy reference. Called during
    /// actor system startup. The Site Call Audit actor is central-local, so Site
    /// Calls read calls Ask this proxy directly (no SiteEnvelope routing), the
    /// same pattern as <see cref="SetNotificationOutbox"/>.
    /// </summary>
    /// <param name="siteCallAuditProxy">The Site Call Audit proxy reference.</param>
    public void SetSiteCallAudit(IActorRef siteCallAuditProxy)
    {
        _siteCallAuditProxy = siteCallAuditProxy;
    }

    /// <summary>
    /// Triggers an immediate refresh of the site address cache from the database.
    /// </summary>
    public void RefreshSiteAddresses()
    {
        GetActor().Tell(new RefreshSiteAddresses());
    }

    /// <summary>
    /// Gets the central communication actor reference. Throws if not yet initialized.
    /// </summary>
    /// <returns>The <see cref="IActorRef"/> for the central communication actor.</returns>
    public IActorRef GetCommunicationActor()
    {
        return _centralCommunicationActor
            ?? throw new InvalidOperationException("CommunicationService not initialized. CentralCommunicationActor not set.");
    }

    private IActorRef GetActor() => GetCommunicationActor();

    /// <summary>
    /// Gets the notification-outbox proxy reference. Throws if not yet initialized.
    /// </summary>
    private IActorRef GetNotificationOutbox()
    {
        return _notificationOutboxProxy
            ?? throw new InvalidOperationException("CommunicationService not initialized. NotificationOutbox proxy not set.");
    }

    /// <summary>
    /// Gets the Site Call Audit proxy reference. Throws if not yet initialized.
    /// </summary>
    private IActorRef GetSiteCallAudit()
    {
        return _siteCallAuditProxy
            ?? throw new InvalidOperationException("CommunicationService not initialized. SiteCallAudit proxy not set.");
    }

    // ── Pattern 1: Instance Deployment ──

    /// <summary>
    /// Sends a deployment command for an instance to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The deployment command.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The deployment status response.</returns>
    public async Task<DeploymentStatusResponse> DeployInstanceAsync(
        string siteId, DeployInstanceCommand command, CancellationToken cancellationToken = default)
    {
        _logger.LogDebug(
            "Sending DeployInstanceCommand to site {SiteId}, instance={Instance}, correlationId={DeploymentId}",
            siteId, command.InstanceUniqueName, command.DeploymentId);

        var envelope = new SiteEnvelope(siteId, command);
        return await GetActor().Ask<DeploymentStatusResponse>(
            envelope, _options.DeploymentTimeout, cancellationToken);
    }

    /// <summary>
    /// DeploymentManager-006: queries a site for the currently-applied deployment
    /// identity of a single instance. Used by the Deployment Manager before a
    /// re-deploy to reconcile against the site's actual state. Sent over the
    /// existing ClusterClient command/control transport; the Ask times out (no
    /// central buffering) if the site is unreachable, and the caller falls
    /// through to a normal deploy.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The deployment state query request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The deployment state query response.</returns>
    public async Task<DeploymentStateQueryResponse> QueryDeploymentStateAsync(
        string siteId, DeploymentStateQueryRequest request, CancellationToken cancellationToken = default)
    {
        _logger.LogDebug(
            "Sending DeploymentStateQueryRequest to site {SiteId}, instance={Instance}, correlationId={CorrelationId}",
            siteId, request.InstanceUniqueName, request.CorrelationId);

        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<DeploymentStateQueryResponse>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    // ── Pattern 2: Lifecycle ──

    /// <summary>
    /// Sends a disable command for an instance to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The disable command.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The instance lifecycle response.</returns>
    public async Task<InstanceLifecycleResponse> DisableInstanceAsync(
        string siteId, DisableInstanceCommand command, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, command);
        return await GetActor().Ask<InstanceLifecycleResponse>(
            envelope, _options.LifecycleTimeout, cancellationToken);
    }

    /// <summary>
    /// Sends an enable command for an instance to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The enable command.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The instance lifecycle response.</returns>
    public async Task<InstanceLifecycleResponse> EnableInstanceAsync(
        string siteId, EnableInstanceCommand command, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, command);
        return await GetActor().Ask<InstanceLifecycleResponse>(
            envelope, _options.LifecycleTimeout, cancellationToken);
    }

    /// <summary>
    /// Sends a delete command for an instance to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The delete command.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The instance lifecycle response.</returns>
    public async Task<InstanceLifecycleResponse> DeleteInstanceAsync(
        string siteId, DeleteInstanceCommand command, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, command);
        return await GetActor().Ask<InstanceLifecycleResponse>(
            envelope, _options.LifecycleTimeout, cancellationToken);
    }

    // ── Pattern 3: Artifact Deployment ──

    /// <summary>
    /// Sends a system-wide artifact deployment command to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The artifact deployment command.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The artifact deployment response.</returns>
    public async Task<ArtifactDeploymentResponse> DeployArtifactsAsync(
        string siteId, DeployArtifactsCommand command, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, command);
        return await GetActor().Ask<ArtifactDeploymentResponse>(
            envelope, _options.ArtifactDeploymentTimeout, cancellationToken);
    }

    // ── Pattern 4: Integration Routing ──

    /// <summary>
    /// Routes an integration call to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The integration call request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The integration call response.</returns>
    public async Task<IntegrationCallResponse> RouteIntegrationCallAsync(
        string siteId, IntegrationCallRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<IntegrationCallResponse>(
            envelope, _options.IntegrationTimeout, cancellationToken);
    }

    // ── Pattern 5: Debug View ──

    /// <summary>
    /// Subscribes to debug view events from a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The debug view subscription request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A snapshot of the debug view.</returns>
    public async Task<DebugViewSnapshot> SubscribeDebugViewAsync(
        string siteId, SubscribeDebugViewRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<DebugViewSnapshot>(
            envelope, _options.DebugViewTimeout, cancellationToken);
    }

    /// <summary>
    /// Unsubscribes from debug view events for a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The debug view unsubscription request.</param>
    public void UnsubscribeDebugView(string siteId, UnsubscribeDebugViewRequest request)
    {
        // Tell (fire-and-forget) — no response expected
        GetActor().Tell(new SiteEnvelope(siteId, request));
    }

    // ── Pattern 6a: Debug Snapshot (one-shot, request/response) ──

    /// <summary>
    /// Requests a snapshot of the debug view from a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The debug snapshot request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A snapshot of the debug view.</returns>
    public async Task<DebugViewSnapshot> RequestDebugSnapshotAsync(
        string siteId, DebugSnapshotRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<DebugViewSnapshot>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    // ── Pattern 6b: Health Reporting (site→central, Tell) ──
    // Health reports are received by central, not sent. No method needed here.

    // ── Pattern 7: Remote Queries ──

    /// <summary>
    /// Queries event logs from a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The event log query request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The event log query response.</returns>
    public async Task<EventLogQueryResponse> QueryEventLogsAsync(
        string siteId, EventLogQueryRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<EventLogQueryResponse>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Queries parked messages from a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The parked message query request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The parked message query response.</returns>
    public async Task<ParkedMessageQueryResponse> QueryParkedMessagesAsync(
        string siteId, ParkedMessageQueryRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<ParkedMessageQueryResponse>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Retries a parked message at a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The parked message retry request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The parked message retry response.</returns>
    public async Task<ParkedMessageRetryResponse> RetryParkedMessageAsync(
        string siteId, ParkedMessageRetryRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<ParkedMessageRetryResponse>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Discards a parked message at a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The parked message discard request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The parked message discard response.</returns>
    public async Task<ParkedMessageDiscardResponse> DiscardParkedMessageAsync(
        string siteId, ParkedMessageDiscardRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<ParkedMessageDiscardResponse>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    // ── OPC UA Tag Browser (interactive design-time query) ──

    /// <summary>
    /// Asks a site to enumerate the immediate children of an OPC UA node on the
    /// live server backing the given data connection. Used by the CentralUI OPC UA
    /// Tag Browser dialog. The Ask is bounded by <see cref="CommunicationOptions.QueryTimeout"/>
    /// — interactive browse expansions are short, one-shot queries that share the
    /// same latency budget as other remote queries (event logs, parked messages).
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The OPC UA browse command.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The browse result (children + truncation flag + structured failure).</returns>
    public Task<BrowseNodeResult> BrowseNodeAsync(
        string siteId,
        BrowseNodeCommand command,
        CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, command);
        return GetActor().Ask<BrowseNodeResult>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    // ── Test Bindings (one-shot live read of bound tags) ──

    /// <summary>
    /// Asks a site to read the current value of one or more tags on the live
    /// server backing the given data connection. Used by the CentralUI "Test
    /// Bindings" dialog on the Configure Instance page. The Ask is bounded by
    /// <see cref="CommunicationOptions.QueryTimeout"/> — same latency budget
    /// as <see cref="BrowseNodeAsync"/> (both are interactive one-shot
    /// design-time queries).
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="command">The read-tag-values command (connection name + tag paths).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The read result — per-tag outcomes plus an optional connection-level failure.</returns>
    public Task<ReadTagValuesResult> ReadTagValuesAsync(
        string siteId,
        ReadTagValuesCommand command,
        CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, command);
        return GetActor().Ask<ReadTagValuesResult>(
            envelope, _options.QueryTimeout, cancellationToken);
    }

    // ── Pattern 8: Heartbeat (site→central, Tell) ──
    // Heartbeats are received by central, not sent. No method needed here.

    // ── Inbound API Cross-Site Routing (WP-4) ──

    /// <summary>
    /// Routes an inbound API call to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The call route request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The call route response.</returns>
    public async Task<RouteToCallResponse> RouteToCallAsync(
        string siteId, RouteToCallRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<RouteToCallResponse>(
            envelope, _options.IntegrationTimeout, cancellationToken);
    }

    /// <summary>
    /// Routes an inbound API get-attributes request to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The get-attributes route request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The get-attributes route response.</returns>
    public async Task<RouteToGetAttributesResponse> RouteToGetAttributesAsync(
        string siteId, RouteToGetAttributesRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<RouteToGetAttributesResponse>(
            envelope, _options.IntegrationTimeout, cancellationToken);
    }

    /// <summary>
    /// Routes an inbound API set-attributes request to a site.
    /// </summary>
    /// <param name="siteId">The target site identifier.</param>
    /// <param name="request">The set-attributes route request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The set-attributes route response.</returns>
    public async Task<RouteToSetAttributesResponse> RouteToSetAttributesAsync(
        string siteId, RouteToSetAttributesRequest request, CancellationToken cancellationToken = default)
    {
        var envelope = new SiteEnvelope(siteId, request);
        return await GetActor().Ask<RouteToSetAttributesResponse>(
            envelope, _options.IntegrationTimeout, cancellationToken);
    }

    // ── Notification Outbox (central-local actor — Asked directly, no SiteEnvelope) ──

    /// <summary>
    /// Queries the notification outbox.
    /// </summary>
    /// <param name="request">The notification outbox query request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The notification outbox query response.</returns>
    public async Task<NotificationOutboxQueryResponse> QueryNotificationOutboxAsync(
        NotificationOutboxQueryRequest request, CancellationToken cancellationToken = default)
    {
        return await GetNotificationOutbox().Ask<NotificationOutboxQueryResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Retries a notification from the outbox.
    /// </summary>
    /// <param name="request">The retry notification request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The retry notification response.</returns>
    public async Task<RetryNotificationResponse> RetryNotificationAsync(
        RetryNotificationRequest request, CancellationToken cancellationToken = default)
    {
        return await GetNotificationOutbox().Ask<RetryNotificationResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Discards a notification from the outbox.
    /// </summary>
    /// <param name="request">The discard notification request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The discard notification response.</returns>
    public async Task<DiscardNotificationResponse> DiscardNotificationAsync(
        DiscardNotificationRequest request, CancellationToken cancellationToken = default)
    {
        return await GetNotificationOutbox().Ask<DiscardNotificationResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Gets details about a specific notification.
    /// </summary>
    /// <param name="request">The notification detail request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The notification detail response.</returns>
    public async Task<NotificationDetailResponse> GetNotificationDetailAsync(
        NotificationDetailRequest request, CancellationToken cancellationToken = default)
    {
        return await GetNotificationOutbox().Ask<NotificationDetailResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Gets KPI metrics for the notification outbox.
    /// </summary>
    /// <param name="request">The notification KPI request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The notification KPI response.</returns>
    public async Task<NotificationKpiResponse> GetNotificationKpisAsync(
        NotificationKpiRequest request, CancellationToken cancellationToken = default)
    {
        return await GetNotificationOutbox().Ask<NotificationKpiResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Gets per-site KPI metrics for the notification outbox.
    /// </summary>
    /// <param name="request">The per-site notification KPI request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The per-site notification KPI response.</returns>
    public async Task<PerSiteNotificationKpiResponse> GetPerSiteNotificationKpisAsync(
        PerSiteNotificationKpiRequest request, CancellationToken cancellationToken = default)
    {
        return await GetNotificationOutbox().Ask<PerSiteNotificationKpiResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    // ── Site Call Audit (central-local actor — Asked directly, no SiteEnvelope) ──

    /// <summary>
    /// Queries site call audit records.
    /// </summary>
    /// <param name="request">The site call query request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The site call query response.</returns>
    public async Task<SiteCallQueryResponse> QuerySiteCallsAsync(
        SiteCallQueryRequest request, CancellationToken cancellationToken = default)
    {
        return await GetSiteCallAudit().Ask<SiteCallQueryResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Gets details about a specific site call.
    /// </summary>
    /// <param name="request">The site call detail request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The site call detail response.</returns>
    public async Task<SiteCallDetailResponse> GetSiteCallDetailAsync(
        SiteCallDetailRequest request, CancellationToken cancellationToken = default)
    {
        return await GetSiteCallAudit().Ask<SiteCallDetailResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Gets KPI metrics for site calls.
    /// </summary>
    /// <param name="request">The site call KPI request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The site call KPI response.</returns>
    public async Task<SiteCallKpiResponse> GetSiteCallKpisAsync(
        SiteCallKpiRequest request, CancellationToken cancellationToken = default)
    {
        return await GetSiteCallAudit().Ask<SiteCallKpiResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Gets per-site KPI metrics for site calls.
    /// </summary>
    /// <param name="request">The per-site site call KPI request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The per-site site call KPI response.</returns>
    public async Task<PerSiteSiteCallKpiResponse> GetPerSiteSiteCallKpisAsync(
        PerSiteSiteCallKpiRequest request, CancellationToken cancellationToken = default)
    {
        return await GetSiteCallAudit().Ask<PerSiteSiteCallKpiResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Task 5 (#22): relays an operator Retry of a parked cached call to its
    /// owning site. The <c>SiteCallAuditActor</c> is Asked directly (it is
    /// central-local); it in turn relays a <c>RetryParkedOperation</c> to the
    /// owning site and replies a <see cref="RetrySiteCallResponse"/> carrying a
    /// distinct site-unreachable outcome. Central never mutates the central
    /// <c>SiteCalls</c> mirror row.
    /// <para>
    /// This outer Ask uses <see cref="CommunicationOptions.QueryTimeout"/>
    /// (default 30s), which must outlive the inner site relay Ask the
    /// <c>SiteCallAuditActor</c> issues with <c>SiteCallAuditOptions.RelayTimeout</c>
    /// (default 10s). The inner relay must time out first so its distinct
    /// <c>SiteUnreachable</c> outcome reaches us; were this outer Ask to expire
    /// first, that outcome would be lost to a generic Ask-timeout exception.
    /// </para>
    /// </summary>
    /// <param name="request">The retry site call request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The retry site call response.</returns>
    public async Task<RetrySiteCallResponse> RetrySiteCallAsync(
        RetrySiteCallRequest request, CancellationToken cancellationToken = default)
    {
        return await GetSiteCallAudit().Ask<RetrySiteCallResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }

    /// <summary>
    /// Task 5 (#22): relays an operator Discard of a parked cached call to its
    /// owning site. See <see cref="RetrySiteCallAsync"/> for the routing and
    /// source-of-truth rationale.
    /// </summary>
    /// <param name="request">The discard site call request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The discard site call response.</returns>
    public async Task<DiscardSiteCallResponse> DiscardSiteCallAsync(
        DiscardSiteCallRequest request, CancellationToken cancellationToken = default)
    {
        return await GetSiteCallAudit().Ask<DiscardSiteCallResponse>(
            request, _options.QueryTimeout, cancellationToken);
    }
}

/// <summary>
/// Envelope that wraps any message with a target site ID for routing.
/// Used by CentralCommunicationActor to resolve the site actor path.
/// </summary>
public record SiteEnvelope(string SiteId, object Message);