feat(auditlog): SiteAuditReconciliationActor central singleton (#23 M6)

src/ScadaLink.AuditLog/Central/IPullAuditEventsClient.cs

@@ -0,0 +1,45 @@
+using ScadaLink.Commons.Messages.Integration;
+
+namespace ScadaLink.AuditLog.Central;
+
+/// <summary>
+/// Mockable abstraction over the central-side <c>PullAuditEvents</c> gRPC
+/// client surface that <see cref="SiteAuditReconciliationActor"/> uses to
+/// fetch the next reconciliation batch from a specific site. Extracted so the
+/// actor can be unit-tested against an in-memory stub without standing up a
+/// real <c>GrpcChannel</c> per site.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The production implementation (host wiring task) wraps the auto-generated
+/// <c>SiteStreamService.SiteStreamServiceClient</c>, multiplexing one
+/// <c>GrpcChannel</c> per site keyed on
+/// <see cref="SiteEntry.GrpcEndpoint"/>. Until that wiring lands the DI
+/// composition root binds a NoOp default that returns an empty response — the
+/// reconciliation tick is still scheduled and the cursor logic still runs, so
+/// regressions in the actor itself are caught even before the real client
+/// arrives.
+/// </para>
+/// <para>
+/// Implementations MUST NOT throw on transport faults that the actor can
+/// tolerate (connection refused, deadline exceeded). The actor's contract is
+/// "one site's failure doesn't sink the rest of the tick"; an exception still
+/// won't crash the actor (the per-site try/catch catches it), but returning
+/// an empty response on a known-recoverable error keeps the logs cleaner.
+/// </para>
+/// </remarks>
+public interface IPullAuditEventsClient
+{
+    /// <summary>
+    /// Issues a <c>PullAuditEvents</c> RPC against the site whose endpoint
+    /// is registered against <paramref name="siteId"/>. Returns the next
+    /// batch of <see cref="ScadaLink.Commons.Entities.Audit.AuditEvent"/>
+    /// rows ordered oldest-first AND a <c>MoreAvailable</c> flag the actor
+    /// uses to decide whether to fire another pull immediately.
+    /// </summary>
+    Task<PullAuditEventsResponse> PullAsync(
+        string siteId,
+        DateTime sinceUtc,
+        int batchSize,
+        CancellationToken ct);
+}