feat(comms): site-side PullAuditEvents handler (#23 M6)

src/ScadaLink.AuditLog/Site/SqliteAuditWriter.cs

@@ -2,7 +2,6 @@ using System.Threading.Channels;
 using Microsoft.Data.Sqlite;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
-using ScadaLink.AuditLog.Site.Telemetry;
 using ScadaLink.Commons.Entities.Audit;
 using ScadaLink.Commons.Interfaces.Services;
 using ScadaLink.Commons.Types.Enums;
@@ -390,6 +389,106 @@ public class SqliteAuditWriter : IAuditWriter, ISiteAuditQueue, IAsyncDisposable
         }
     }
 
+    /// <summary>
+    /// M6 reconciliation-pull read: returns up to <paramref name="batchSize"/> rows
+    /// whose <c>OccurredAtUtc &gt;= sinceUtc</c> and whose <see cref="AuditForwardState"/>
+    /// is still <see cref="AuditForwardState.Pending"/> or
+    /// <see cref="AuditForwardState.Forwarded"/>. Forwarded rows are included so the
+    /// brief race window between a site-Forwarded ack and central ingest cannot
+    /// silently drop rows; central dedups on <see cref="AuditEvent.EventId"/>.
+    /// Ordered oldest <see cref="AuditEvent.OccurredAtUtc"/> first, EventId tiebreaker.
+    /// </summary>
+    public Task<IReadOnlyList<AuditEvent>> ReadPendingSinceAsync(
+        DateTime sinceUtc, int batchSize, CancellationToken ct = default)
+    {
+        if (batchSize <= 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(batchSize), "batchSize must be > 0.");
+        }
+
+        // Mirror ReadPendingAsync: the write lock guards the single connection.
+        lock (_writeLock)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+
+            using var cmd = _connection.CreateCommand();
+            cmd.CommandText = """
+                SELECT EventId, OccurredAtUtc, Channel, Kind, CorrelationId,
+                       SourceSiteId, SourceInstanceId, SourceScript, Actor, Target,
+                       Status, HttpStatus, DurationMs, ErrorMessage, ErrorDetail,
+                       RequestSummary, ResponseSummary, PayloadTruncated, Extra, ForwardState
+                FROM   AuditLog
+                WHERE  ForwardState IN ($pending, $forwarded)
+                  AND  OccurredAtUtc >= $since
+                ORDER  BY OccurredAtUtc ASC, EventId ASC
+                LIMIT  $limit;
+                """;
+            cmd.Parameters.AddWithValue("$pending", AuditForwardState.Pending.ToString());
+            cmd.Parameters.AddWithValue("$forwarded", AuditForwardState.Forwarded.ToString());
+            // Normalise to UTC ISO-8601 round-trip format to match how OccurredAtUtc
+            // is stored on insert ("o" format) — string comparison is monotonic for
+            // that encoding so we can index-scan against it.
+            cmd.Parameters.AddWithValue("$since", EnsureUtc(sinceUtc).ToString(
+                "o", System.Globalization.CultureInfo.InvariantCulture));
+            cmd.Parameters.AddWithValue("$limit", batchSize);
+
+            var rows = new List<AuditEvent>(Math.Min(batchSize, 256));
+            using var reader = cmd.ExecuteReader();
+            while (reader.Read())
+            {
+                rows.Add(MapRow(reader));
+            }
+
+            return Task.FromResult<IReadOnlyList<AuditEvent>>(rows);
+        }
+    }
+
+    /// <summary>
+    /// M6 reconciliation-pull commit: flips the supplied EventIds to
+    /// <see cref="AuditForwardState.Reconciled"/>, but ONLY for rows currently in
+    /// <see cref="AuditForwardState.Pending"/> or <see cref="AuditForwardState.Forwarded"/>.
+    /// Rows already in <see cref="AuditForwardState.Reconciled"/> are left untouched
+    /// (idempotent re-call). Non-existent ids are silent no-ops.
+    /// </summary>
+    public Task MarkReconciledAsync(IReadOnlyList<Guid> eventIds, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(eventIds);
+        if (eventIds.Count == 0)
+        {
+            return Task.CompletedTask;
+        }
+
+        lock (_writeLock)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+
+            using var cmd = _connection.CreateCommand();
+            var sb = new System.Text.StringBuilder();
+            sb.Append("UPDATE AuditLog SET ForwardState = $reconciled ")
+              .Append("WHERE ForwardState IN ($pending, $forwarded) AND EventId IN (");
+            for (int i = 0; i < eventIds.Count; i++)
+            {
+                if (i > 0) sb.Append(',');
+                var p = $"$id{i}";
+                sb.Append(p);
+                cmd.Parameters.AddWithValue(p, eventIds[i].ToString());
+            }
+            sb.Append(");");
+            cmd.CommandText = sb.ToString();
+            cmd.Parameters.AddWithValue("$reconciled", AuditForwardState.Reconciled.ToString());
+            cmd.Parameters.AddWithValue("$pending", AuditForwardState.Pending.ToString());
+            cmd.Parameters.AddWithValue("$forwarded", AuditForwardState.Forwarded.ToString());
+
+            cmd.ExecuteNonQuery();
+            return Task.CompletedTask;
+        }
+    }
+
+    private static DateTime EnsureUtc(DateTime value) =>
+        value.Kind == DateTimeKind.Utc
+            ? value
+            : DateTime.SpecifyKind(value.ToUniversalTime(), DateTimeKind.Utc);
+
     private static AuditEvent MapRow(SqliteDataReader reader)
     {
         return new AuditEvent

src/ScadaLink.AuditLog/Site/Telemetry/ISiteAuditQueue.cs

@@ -1,34 +0,0 @@
-using ScadaLink.Commons.Entities.Audit;
-
-namespace ScadaLink.AuditLog.Site.Telemetry;
-
-/// <summary>
-/// Site-local audit-log queue surface consumed by <see cref="SiteAuditTelemetryActor"/>.
-/// Extracted from <see cref="SqliteAuditWriter"/> so the telemetry actor can be
-/// unit-tested against a stub without touching SQLite. <see cref="SqliteAuditWriter"/>
-/// implements this interface; production wiring injects the same instance.
-/// </summary>
-/// <remarks>
-/// Only the two methods the drain loop needs are exposed — the hot-path
-/// <c>WriteAsync</c> stays on <see cref="Commons.Interfaces.Services.IAuditWriter"/>
-/// (script-thread surface), separated by concern from the
-/// telemetry-actor surface so each side can be mocked independently.
-/// </remarks>
-public interface ISiteAuditQueue
-{
-    /// <summary>
-    /// Returns up to <paramref name="limit"/> rows currently in
-    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Pending"/>,
-    /// oldest first. Idempotent — repeated calls before
-    /// <see cref="MarkForwardedAsync"/> will yield the same rows again.
-    /// </summary>
-    Task<IReadOnlyList<AuditEvent>> ReadPendingAsync(int limit, CancellationToken ct = default);
-
-    /// <summary>
-    /// Flips the supplied EventIds from
-    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Pending"/> to
-    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Forwarded"/>.
-    /// Non-existent or already-forwarded ids are silent no-ops.
-    /// </summary>
-    Task MarkForwardedAsync(IReadOnlyList<Guid> eventIds, CancellationToken ct = default);
-}

src/ScadaLink.AuditLog/Site/Telemetry/SiteAuditTelemetryActor.cs

@@ -3,6 +3,7 @@ using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using ScadaLink.AuditLog.Telemetry;
 using ScadaLink.Commons.Entities.Audit;
+using ScadaLink.Commons.Interfaces.Services;
 using ScadaLink.Communication.Grpc;
 
 namespace ScadaLink.AuditLog.Site.Telemetry;