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

src/ScadaLink.AuditLog/Central/SiteAuditReconciliationOptions.cs

@@ -0,0 +1,60 @@
+namespace ScadaLink.AuditLog.Central;
+
+/// <summary>
+/// Tuning knobs for the central <see cref="SiteAuditReconciliationActor"/> singleton.
+/// Defaults mirror the M6 Bundle B brief: pull every 5 minutes per site, 256 rows per
+/// batch, declare a site "stalled" after two consecutive pull cycles return non-empty
+/// AND <c>MoreAvailable=true</c> (the backlog is not draining).
+/// </summary>
+/// <remarks>
+/// <para>
+/// Per the M6 plan the reconciliation actor is the fallback when push telemetry is
+/// lost; it is intentionally low-frequency. Lowering
+/// <see cref="ReconciliationIntervalSeconds"/> in production trades MS SQL load for
+/// fresher self-healing — keep the default unless a deployment can prove the extra
+/// load is acceptable.
+/// </para>
+/// <para>
+/// <see cref="StalledAfterNonDrainingCycles"/> = 2 because a single non-draining
+/// cycle can happen on a surge (e.g. a backed-up site replays its hot queue); the
+/// stalled signal should only fire when the backlog persists across cycles, which is
+/// the symptom the central health surface is asking us to detect.
+/// </para>
+/// </remarks>
+public sealed class SiteAuditReconciliationOptions
+{
+    /// <summary>
+    /// Period of the reconciliation tick. Each tick visits every known site once.
+    /// </summary>
+    public int ReconciliationIntervalSeconds { get; set; } = 300;
+
+    /// <summary>
+    /// Test-only override for finer control over the tick cadence than
+    /// whole-second resolution allows. When non-null, takes precedence over
+    /// <see cref="ReconciliationIntervalSeconds"/>. Not bound from config —
+    /// production config exposes <see cref="ReconciliationIntervalSeconds"/>
+    /// only.
+    /// </summary>
+    public TimeSpan? ReconciliationIntervalOverride { get; set; }
+
+    /// <summary>
+    /// Resolves the effective tick interval, honouring the test override when
+    /// set. Falls back to <see cref="ReconciliationIntervalSeconds"/>.
+    /// </summary>
+    public TimeSpan ReconciliationInterval =>
+        ReconciliationIntervalOverride ?? TimeSpan.FromSeconds(ReconciliationIntervalSeconds);
+
+    /// <summary>
+    /// Maximum number of <see cref="ScadaLink.Commons.Entities.Audit.AuditEvent"/>
+    /// rows requested in a single <c>PullAuditEvents</c> RPC call.
+    /// </summary>
+    public int BatchSize { get; set; } = 256;
+
+    /// <summary>
+    /// Number of consecutive non-draining cycles (events returned AND
+    /// <c>MoreAvailable=true</c>) that must accumulate for a site before the actor
+    /// publishes <c>SiteAuditTelemetryStalledChanged(Stalled: true)</c> on the
+    /// EventStream.
+    /// </summary>
+    public int StalledAfterNonDrainingCycles { get; set; } = 2;
+}