feat(sitecallaudit): central→site Retry/Discard relay for parked operations

src/ScadaLink.Commons/Messages/Audit/SiteCallRelayMessages.cs

@@ -0,0 +1,113 @@
+namespace ScadaLink.Commons.Messages.Audit;
+
+/// <summary>
+/// Outcome of a Site Call Audit (#22) Retry/Discard relay — distinguishes the
+/// three cases the Central UI Site Calls page must surface differently.
+/// </summary>
+/// <remarks>
+/// The "site unreachable" case is deliberately separate from
+/// <see cref="OperationFailed"/>: central is an eventually-consistent mirror,
+/// not the source of truth, so a relay that never reaches the owning site is a
+/// transient transport condition the operator can retry — not a failed
+/// operation. The UI shows "site unreachable" rather than a generic error.
+/// </remarks>
+public enum SiteCallRelayOutcome
+{
+    /// <summary>
+    /// The owning site received the relay command and applied the action to its
+    /// Store-and-Forward buffer (the parked cached call was reset to retry, or
+    /// discarded). The corrected state reaches central later via telemetry.
+    /// </summary>
+    Applied,
+
+    /// <summary>
+    /// The owning site received the relay command but found nothing to do — no
+    /// parked row matched the tracked id (already delivered/discarded, or no
+    /// longer <c>Parked</c>). A definitive answer from the site, not a failure.
+    /// </summary>
+    NotParked,
+
+    /// <summary>
+    /// The owning site could not be reached (offline / no ClusterClient route /
+    /// relay timed out). The action was NOT applied; the operator may retry once
+    /// the site is back online.
+    /// </summary>
+    SiteUnreachable,
+
+    /// <summary>
+    /// The owning site was reached but reported it could not apply the action
+    /// (its parked-message handler was unavailable or its store faulted).
+    /// </summary>
+    OperationFailed,
+}
+
+/// <summary>
+/// Central UI → Site Call Audit: relay a Retry of a parked cached call to its
+/// owning site. The owning site performs the actual retry on its
+/// Store-and-Forward buffer — central never mutates the central <c>SiteCalls</c>
+/// mirror row. Mirrors
+/// <see cref="ScadaLink.Commons.Messages.Notification.RetryNotificationRequest"/>
+/// but carries <see cref="SourceSite"/> (the relay target) and answers with a
+/// distinct site-unreachable outcome.
+/// </summary>
+/// <param name="CorrelationId">Request correlation id, echoed on the response.</param>
+/// <param name="TrackedOperationId">
+/// The cached operation to retry — the PK of the central <c>SiteCalls</c> row
+/// and the S&amp;F buffer message id at the owning site.
+/// </param>
+/// <param name="SourceSite">
+/// The owning site (<c>SiteCall.SourceSite</c>) the relay is routed to.
+/// </param>
+public sealed record RetrySiteCallRequest(
+    string CorrelationId,
+    Guid TrackedOperationId,
+    string SourceSite);
+
+/// <summary>
+/// Site Call Audit → Central UI: result of a <see cref="RetrySiteCallRequest"/>.
+/// </summary>
+/// <param name="CorrelationId">Echoed request correlation id.</param>
+/// <param name="Outcome">
+/// The relay outcome — <see cref="SiteCallRelayOutcome.Applied"/>,
+/// <see cref="SiteCallRelayOutcome.NotParked"/>,
+/// <see cref="SiteCallRelayOutcome.SiteUnreachable"/> or
+/// <see cref="SiteCallRelayOutcome.OperationFailed"/>.
+/// </param>
+/// <param name="Success">
+/// Convenience flag — <c>true</c> only for <see cref="SiteCallRelayOutcome.Applied"/>.
+/// </param>
+/// <param name="SiteReachable">
+/// <c>false</c> only for <see cref="SiteCallRelayOutcome.SiteUnreachable"/>; lets
+/// the UI distinguish "site offline" from "operation failed" without switching
+/// on the enum.
+/// </param>
+/// <param name="ErrorMessage">
+/// Human-readable detail for a non-applied outcome; <c>null</c> on success.
+/// </param>
+public sealed record RetrySiteCallResponse(
+    string CorrelationId,
+    SiteCallRelayOutcome Outcome,
+    bool Success,
+    bool SiteReachable,
+    string? ErrorMessage);
+
+/// <summary>
+/// Central UI → Site Call Audit: relay a Discard of a parked cached call to its
+/// owning site. See <see cref="RetrySiteCallRequest"/> for the source-of-truth
+/// and routing rationale.
+/// </summary>
+public sealed record DiscardSiteCallRequest(
+    string CorrelationId,
+    Guid TrackedOperationId,
+    string SourceSite);
+
+/// <summary>
+/// Site Call Audit → Central UI: result of a <see cref="DiscardSiteCallRequest"/>.
+/// Same shape as <see cref="RetrySiteCallResponse"/>.
+/// </summary>
+public sealed record DiscardSiteCallResponse(
+    string CorrelationId,
+    SiteCallRelayOutcome Outcome,
+    bool Success,
+    bool SiteReachable,
+    string? ErrorMessage);

src/ScadaLink.Commons/Messages/RemoteQuery/ParkedOperationRelayMessages.cs

@@ -0,0 +1,75 @@
+using ScadaLink.Commons.Types;
+
+namespace ScadaLink.Commons.Messages.RemoteQuery;
+
+/// <summary>
+/// Central → site relay command: retry a parked cached operation
+/// (<c>ExternalSystem.CachedCall</c> / <c>Database.CachedWrite</c>) on the
+/// owning site's Store-and-Forward buffer. Sent over the command/control
+/// channel by <c>SiteCallAuditActor</c> when an operator clicks Retry on a
+/// <c>Parked</c> Site Call row in the Central UI.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The site is the source of truth for cached-call status — central never
+/// mutates the central <c>SiteCalls</c> mirror row directly. This command asks
+/// the site to reset its own parked row back to <c>Pending</c> so the S&amp;F
+/// retry sweep attempts delivery again; the corrected state then flows back to
+/// central via the normal cached-call telemetry path.
+/// </para>
+/// <para>
+/// The cached call's S&amp;F buffer message id is the
+/// <see cref="TrackedOperationId"/> itself (the tracked id is supplied as the
+/// buffered row's id at enqueue time), so the site can resolve the parked row
+/// directly from <see cref="TrackedOperationId"/>. A retry on a row that is not
+/// actually <c>Parked</c> is a safe no-op at the site — the ack reports
+/// <c>Applied=false</c> rather than corrupting a non-parked row.
+/// </para>
+/// <para>
+/// This is a plain record carrying only ids, so it lives in Commons (no
+/// <c>IActorRef</c> field). It mirrors <see cref="ParkedMessageRetryRequest"/>
+/// but keys on <see cref="TrackedOperationId"/> rather than the opaque S&amp;F
+/// message-id string.
+/// </para>
+/// </remarks>
+public sealed record RetryParkedOperation(
+    string CorrelationId,
+    TrackedOperationId TrackedOperationId);
+
+/// <summary>
+/// Central → site relay command: discard a parked cached operation on the
+/// owning site's Store-and-Forward buffer. Sent over the command/control
+/// channel by <c>SiteCallAuditActor</c> when an operator clicks Discard on a
+/// <c>Parked</c> Site Call row in the Central UI. See
+/// <see cref="RetryParkedOperation"/> for the source-of-truth and message-id
+/// rationale; Discard marks the operation terminally <c>Discarded</c> at the
+/// site by removing the parked S&amp;F buffer row.
+/// </summary>
+public sealed record DiscardParkedOperation(
+    string CorrelationId,
+    TrackedOperationId TrackedOperationId);
+
+/// <summary>
+/// Site → central ack for a <see cref="RetryParkedOperation"/> /
+/// <see cref="DiscardParkedOperation"/> relay command. The site replies this
+/// after applying (or safely no-op-ing) the action against its own
+/// Store-and-Forward buffer.
+/// </summary>
+/// <param name="CorrelationId">Correlation id of the originating relay command.</param>
+/// <param name="Applied">
+/// <c>true</c> when the parked operation was found and the action was applied;
+/// <c>false</c> when no parked row matched the <see cref="RetryParkedOperation.TrackedOperationId"/>
+/// (already delivered, discarded, never cached, or not in a <c>Parked</c>
+/// state). A <c>false</c> ack is a definitive "nothing to do" answer from the
+/// site — it is NOT a transport failure, so the relay must distinguish it from
+/// a site-unreachable timeout.
+/// </param>
+/// <param name="ErrorMessage">
+/// Populated only when the site could not apply the action (e.g. the parked
+/// message handler is not available, or the S&amp;F store faulted); <c>null</c>
+/// on a clean <c>Applied=true</c>/<c>Applied=false</c> outcome.
+/// </param>
+public sealed record ParkedOperationActionAck(
+    string CorrelationId,
+    bool Applied,
+    string? ErrorMessage = null);