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

tests/ScadaLink.SiteCallAudit.Tests/SiteCallAuditActorTests.cs

@@ -293,6 +293,65 @@ public class SiteCallAuditActorTests : TestKit, IClassFixture<MsSqlMigrationFixt
         Assert.True(response.SiteCalls[0].IsStuck);
     }
 
+    [SkippableFact]
+    public async Task SiteCallQueryRequest_StuckOnly_PagesAreFull_NoEmptyPagesWithCursor()
+    {
+        Skip.IfNot(_fixture.Available, _fixture.SkipReason);
+
+        var siteId = NewSiteId();
+        await using var context = CreateContext();
+        var repo = new SiteCallAuditRepository(context);
+        var actor = CreateActor(repo, new SiteCallAuditOptions { StuckAgeThreshold = TimeSpan.FromMinutes(10) });
+
+        var now = DateTime.UtcNow;
+        // Three stuck rows interleaved (by CreatedAtUtc) with three non-stuck
+        // rows: recent non-terminal and old-but-terminal. With the StuckOnly
+        // filter pushed into SQL, a page-size-2 query must return exactly the
+        // stuck rows two-per-page — never an under-filled page with a non-null
+        // next cursor caused by post-filtering.
+        for (var i = 0; i < 3; i++)
+        {
+            await repo.UpsertAsync(NewRow(
+                TrackedOperationId.New(), siteId, status: "Attempted",
+                createdAtUtc: now.AddMinutes(-30 - i)));
+            await repo.UpsertAsync(NewRow(
+                TrackedOperationId.New(), siteId, status: "Attempted",
+                createdAtUtc: now.AddMinutes(-2 - i)));
+            await repo.UpsertAsync(NewRow(
+                TrackedOperationId.New(), siteId, status: "Delivered",
+                createdAtUtc: now.AddMinutes(-40 - i), terminal: true));
+        }
+
+        actor.Tell(
+            new SiteCallQueryRequest(
+                "corr-stuck-p1", null, siteId, null, null, StuckOnly: true,
+                null, null, null, null, PageSize: 2),
+            TestActor);
+        var page1 = ExpectMsg<SiteCallQueryResponse>(TimeSpan.FromSeconds(10));
+        Assert.True(page1.Success);
+        // Page is full — two stuck rows, both honestly stuck.
+        Assert.Equal(2, page1.SiteCalls.Count);
+        Assert.All(page1.SiteCalls, s => Assert.True(s.IsStuck));
+        Assert.NotNull(page1.NextAfterCreatedAtUtc);
+
+        actor.Tell(
+            new SiteCallQueryRequest(
+                "corr-stuck-p2", null, siteId, null, null, StuckOnly: true,
+                null, null, page1.NextAfterCreatedAtUtc, page1.NextAfterId,
+                PageSize: 2),
+            TestActor);
+        var page2 = ExpectMsg<SiteCallQueryResponse>(TimeSpan.FromSeconds(10));
+        Assert.True(page2.Success);
+        // Final page — the third stuck row, the only remaining match.
+        Assert.Single(page2.SiteCalls);
+        Assert.All(page2.SiteCalls, s => Assert.True(s.IsStuck));
+
+        // No overlap, exactly the three stuck rows across both pages.
+        var allIds = page1.SiteCalls.Concat(page2.SiteCalls)
+            .Select(s => s.TrackedOperationId).ToHashSet();
+        Assert.Equal(3, allIds.Count);
+    }
+
     [SkippableFact]
     public async Task SiteCallDetailRequest_KnownId_ReturnsFullDetail()
     {