feat(commons): add audit telemetry + pull message DTOs (#23)

src/ScadaLink.Commons/Messages/Integration/AuditTelemetryEnvelope.cs

@@ -0,0 +1,13 @@
+using ScadaLink.Commons.Entities.Audit;
+
+namespace ScadaLink.Commons.Messages.Integration;
+
+/// <summary>
+/// Audit Log (#23) telemetry envelope sent from a site to central over gRPC.
+/// At-least-once delivery; central is idempotent on <see cref="AuditEvent.EventId"/>.
+/// See Component-AuditLog.md "Ingestion" for the handoff contract.
+/// </summary>
+public sealed record AuditTelemetryEnvelope(
+    Guid EnvelopeId,
+    string SourceSiteId,
+    IReadOnlyList<AuditEvent> Events);

src/ScadaLink.Commons/Messages/Integration/PullAuditEventsRequest.cs

@@ -0,0 +1,11 @@
+namespace ScadaLink.Commons.Messages.Integration;
+
+/// <summary>
+/// Audit Log (#23) periodic reconciliation pull request: central asks a site for
+/// audit events since the given UTC watermark, up to <paramref name="BatchSize"/>.
+/// Acts as the fallback when streaming telemetry is lost. See Component-AuditLog.md "Ingestion".
+/// </summary>
+public sealed record PullAuditEventsRequest(
+    string SourceSiteId,
+    DateTime SinceUtc,
+    int BatchSize);

src/ScadaLink.Commons/Messages/Integration/PullAuditEventsResponse.cs

@@ -0,0 +1,12 @@
+using ScadaLink.Commons.Entities.Audit;
+
+namespace ScadaLink.Commons.Messages.Integration;
+
+/// <summary>
+/// Audit Log (#23) periodic reconciliation pull response: the next batch of site
+/// audit events plus a <paramref name="MoreAvailable"/> flag signalling the caller
+/// to advance the watermark and pull again. See Component-AuditLog.md "Ingestion".
+/// </summary>
+public sealed record PullAuditEventsResponse(
+    IReadOnlyList<AuditEvent> Events,
+    bool MoreAvailable);

tests/ScadaLink.Commons.Tests/Messages/Integration/AuditTelemetryMessagesTests.cs

@@ -0,0 +1,105 @@
+using ScadaLink.Commons.Entities.Audit;
+using ScadaLink.Commons.Messages.Integration;
+using ScadaLink.Commons.Types.Enums;
+
+namespace ScadaLink.Commons.Tests.Messages.Integration;
+
+/// <summary>
+/// Audit Log (#23) telemetry handoff: envelope + pull request/response DTOs.
+/// At-least-once from sites; idempotent at central on <see cref="AuditEvent.EventId"/>.
+/// </summary>
+public class AuditTelemetryMessagesTests
+{
+    private static AuditEvent MakeEvent(Guid? id = null) => new()
+    {
+        EventId = id ?? Guid.NewGuid(),
+        OccurredAtUtc = DateTime.UtcNow,
+        Channel = AuditChannel.ApiOutbound,
+        Kind = AuditKind.ApiCall,
+        Status = AuditStatus.Delivered,
+        PayloadTruncated = false
+    };
+
+    [Fact]
+    public void AuditTelemetryEnvelope_ConstructsWithThreeEvents_AndIsEnumerable()
+    {
+        var envelopeId = Guid.NewGuid();
+        var events = new List<AuditEvent> { MakeEvent(), MakeEvent(), MakeEvent() };
+
+        var envelope = new AuditTelemetryEnvelope(envelopeId, "site-01", events);
+
+        Assert.Equal(envelopeId, envelope.EnvelopeId);
+        Assert.Equal("site-01", envelope.SourceSiteId);
+        Assert.Equal(3, envelope.Events.Count);
+
+        // Enumerable round-trip
+        var collected = new List<AuditEvent>();
+        foreach (var e in envelope.Events)
+        {
+            collected.Add(e);
+        }
+        Assert.Equal(3, collected.Count);
+    }
+
+    [Fact]
+    public void AuditTelemetryEnvelope_IsImmutable_RecordEqualityOnReferenceIdentityOfList()
+    {
+        // The record's value equality compares the IReadOnlyList reference; two envelopes
+        // built with the same list instance + same fields must be equal, but using a
+        // different list instance (even with equal content) must NOT be equal.
+        var events = new List<AuditEvent> { MakeEvent() } as IReadOnlyList<AuditEvent>;
+        var envelopeId = Guid.NewGuid();
+        var a = new AuditTelemetryEnvelope(envelopeId, "site-01", events);
+        var b = new AuditTelemetryEnvelope(envelopeId, "site-01", events);
+
+        Assert.Equal(a, b);
+        Assert.Equal(a.GetHashCode(), b.GetHashCode());
+
+        var withDifferentSite = a with { SourceSiteId = "site-02" };
+        Assert.NotEqual(a, withDifferentSite);
+        Assert.Equal("site-02", withDifferentSite.SourceSiteId);
+        Assert.Equal("site-01", a.SourceSiteId);
+    }
+
+    [Fact]
+    public void PullAuditEventsRequest_ConstructsAndIsImmutable()
+    {
+        var since = new DateTime(2026, 5, 20, 0, 0, 0, DateTimeKind.Utc);
+        var request = new PullAuditEventsRequest("site-01", since, 100);
+
+        Assert.Equal("site-01", request.SourceSiteId);
+        Assert.Equal(since, request.SinceUtc);
+        Assert.Equal(100, request.BatchSize);
+
+        var bigger = request with { BatchSize = 500 };
+        Assert.Equal(100, request.BatchSize);
+        Assert.Equal(500, bigger.BatchSize);
+    }
+
+    [Fact]
+    public void PullAuditEventsResponse_ConstructsWithMoreAvailableTrue_AndIsEnumerable()
+    {
+        var events = new List<AuditEvent> { MakeEvent(), MakeEvent() };
+        var response = new PullAuditEventsResponse(events, MoreAvailable: true);
+
+        Assert.True(response.MoreAvailable);
+        Assert.Equal(2, response.Events.Count);
+
+        var collected = new List<AuditEvent>();
+        foreach (var e in response.Events)
+        {
+            collected.Add(e);
+        }
+        Assert.Equal(2, collected.Count);
+    }
+
+    [Fact]
+    public void PullAuditEventsResponse_WithExpression_ChangesSingleField()
+    {
+        var response = new PullAuditEventsResponse(new List<AuditEvent>(), MoreAvailable: false);
+        var updated = response with { MoreAvailable = true };
+
+        Assert.False(response.MoreAvailable);
+        Assert.True(updated.MoreAvailable);
+    }
+}