fix(sitecallaudit): push StuckOnly filter into SQL; doc accuracy fixes

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

@@ -18,6 +18,10 @@ namespace ScadaLink.Commons.Messages.Audit;
 /// exact-match target filter, consistent with the repository's
 /// <see cref="SiteCallQueryFilter.Target"/> predicate.
 /// </remarks>
+/// <param name="PageSize">
+/// Requested page size. The actor clamps this to the <c>[1, 200]</c> range, so
+/// the effective ceiling is 200 rows per page regardless of the value sent.
+/// </param>
 public sealed record SiteCallQueryRequest(
     string CorrelationId,
     string? StatusFilter,
@@ -39,6 +43,12 @@ public sealed record SiteCallQueryRequest(
 /// <see cref="ScadaLink.Commons.Messages.Notification.NotificationSummary"/>
 /// none are surfaced here.
 /// </summary>
+/// <remarks>
+/// <see cref="HttpStatus"/> is not called out in the Site Call Audit plan, but
+/// it is a real (nullable) <see cref="ScadaLink.Commons.Entities.Audit.SiteCall"/>
+/// column — the last HTTP status code observed for the call — so it is surfaced
+/// here for the grid; <c>null</c> for non-HTTP channels or before a first attempt.
+/// </remarks>
 public sealed record SiteCallSummary(
     Guid TrackedOperationId,
     string SourceSite,

src/ScadaLink.Commons/Types/Audit/SiteCallKpiSnapshot.cs

@@ -8,7 +8,7 @@ namespace ScadaLink.Commons.Types.Audit;
 /// Notification Outbox tile layout.
 /// </summary>
 /// <param name="BufferedCount">
-/// Count of non-terminal rows (<c>Pending</c> + <c>Retrying</c>) — calls
+/// Count of non-terminal rows (<c>TerminalAtUtc IS NULL</c>) — calls
 /// buffered at sites awaiting retry.
 /// </param>
 /// <param name="ParkedCount">Count of rows in the <c>Parked</c> status.</param>
@@ -25,7 +25,7 @@ namespace ScadaLink.Commons.Types.Audit;
 /// <c>null</c> when there are no non-terminal rows.
 /// </param>
 /// <param name="StuckCount">
-/// Count of non-terminal rows (<c>Pending</c>/<c>Retrying</c>) whose
+/// Count of non-terminal rows (<c>TerminalAtUtc IS NULL</c>) whose
 /// <see cref="ScadaLink.Commons.Entities.Audit.SiteCall.CreatedAtUtc"/> is older
 /// than the supplied stuck cutoff. Display-only — no escalation.
 /// </param>

src/ScadaLink.Commons/Types/Audit/SiteCallQueryFilter.cs

@@ -12,10 +12,25 @@ namespace ScadaLink.Commons.Types.Audit;
 /// underlying columns are bounded ASCII (varchar) and the Central UI Site Calls
 /// page exposes them as drop-down filters, not free-text search.
 /// </remarks>
+/// <param name="Channel">Restrict to a single channel (exact match).</param>
+/// <param name="SourceSite">Restrict to a single source site (exact match).</param>
+/// <param name="Status">Restrict to a single status (exact match).</param>
+/// <param name="Target">Restrict to a single target (exact match).</param>
+/// <param name="FromUtc">Inclusive lower bound on <c>CreatedAtUtc</c>.</param>
+/// <param name="ToUtc">Inclusive upper bound on <c>CreatedAtUtc</c>.</param>
+/// <param name="StuckCutoffUtc">
+/// When set, restrict to stuck rows: <c>TerminalAtUtc IS NULL AND CreatedAtUtc &lt;
+/// StuckCutoffUtc</c>. Both columns are plain (no value converter) and compose
+/// directly with the keyset cursor. Mirrors
+/// <see cref="ScadaLink.Commons.Types.Notifications.NotificationOutboxFilter.StuckCutoff"/>;
+/// keeps the "StuckOnly" filter honest so paging never returns under-filled
+/// pages with a non-null next cursor.
+/// </param>
 public sealed record SiteCallQueryFilter(
     string? Channel = null,
     string? SourceSite = null,
     string? Status = null,
     string? Target = null,
     DateTime? FromUtc = null,
-    DateTime? ToUtc = null);
+    DateTime? ToUtc = null,
+    DateTime? StuckCutoffUtc = null);

src/ScadaLink.Commons/Types/Audit/SiteCallSiteKpiSnapshot.cs

@@ -7,7 +7,7 @@ namespace ScadaLink.Commons.Types.Audit;
 /// <see cref="ScadaLink.Commons.Types.Notifications.SiteNotificationKpiSnapshot"/>.
 /// </summary>
 /// <param name="SourceSite">The site identifier these metrics are scoped to.</param>
-/// <param name="BufferedCount">Count of this site's non-terminal rows (<c>Pending</c> + <c>Retrying</c>).</param>
+/// <param name="BufferedCount">Count of this site's non-terminal rows (<c>TerminalAtUtc IS NULL</c>).</param>
 /// <param name="ParkedCount">Count of this site's rows in the <c>Parked</c> status.</param>
 /// <param name="FailedLastInterval">
 /// Count of this site's <c>Failed</c> rows whose <c>TerminalAtUtc</c> is at or