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

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);