feat(audit)!: ScadaBridge C3 — swap to canonical ZB.MOM.WW.Audit.AuditEvent across seams/emitters/DTO/redactor wiring; transitional 24-col storage shim (Task 2.5)

2026-06-02 12:37:50 -04:00
parent 5aaf9e2923
commit db707bb0de
127 changed files with 2240 additions and 3886 deletions
@@ -3,6 +3,7 @@ using NSubstitute;
 using ZB.MOM.WW.ScadaBridge.AuditLog.Site.Telemetry;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 using ZB.MOM.WW.ScadaBridge.Commons.Messages.Integration;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
 using ZB.MOM.WW.ScadaBridge.Commons.Types;
 using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;

@@ -67,11 +68,11 @@ public class CachedCallLifecycleBridgeTests
            httpStatus: 503));

        var packet = Assert.Single(captured);
-        Assert.Equal(AuditKind.ApiCallCached, packet.Audit.Kind);
-        Assert.Equal(AuditStatus.Attempted, packet.Audit.Status);
-        Assert.Equal(503, packet.Audit.HttpStatus);
-        Assert.Equal("HTTP 503", packet.Audit.ErrorMessage);
-        Assert.Equal(_id.Value, packet.Audit.CorrelationId);
+        Assert.Equal(AuditKind.ApiCallCached, packet.Audit.AsRow().Kind);
+        Assert.Equal(AuditStatus.Attempted, packet.Audit.AsRow().Status);
+        Assert.Equal(503, packet.Audit.AsRow().HttpStatus);
+        Assert.Equal("HTTP 503", packet.Audit.AsRow().ErrorMessage);
+        Assert.Equal(_id.Value, packet.Audit.AsRow().CorrelationId);
        Assert.Equal("Attempted", packet.Operational.Status);
        Assert.Equal(2, packet.Operational.RetryCount);
        Assert.Null(packet.Operational.TerminalAtUtc);
@@ -90,17 +91,17 @@ public class CachedCallLifecycleBridgeTests
        Assert.Equal(2, captured.Count);

        var attempted = captured[0];
-        Assert.Equal(AuditKind.ApiCallCached, attempted.Audit.Kind);
-        Assert.Equal(AuditStatus.Attempted, attempted.Audit.Status);
+        Assert.Equal(AuditKind.ApiCallCached, attempted.Audit.AsRow().Kind);
+        Assert.Equal(AuditStatus.Attempted, attempted.Audit.AsRow().Status);
        Assert.Equal("Attempted", attempted.Operational.Status);
        Assert.Null(attempted.Operational.TerminalAtUtc);

        var resolve = captured[1];
-        Assert.Equal(AuditKind.CachedResolve, resolve.Audit.Kind);
-        Assert.Equal(AuditStatus.Delivered, resolve.Audit.Status);
+        Assert.Equal(AuditKind.CachedResolve, resolve.Audit.AsRow().Kind);
+        Assert.Equal(AuditStatus.Delivered, resolve.Audit.AsRow().Status);
        Assert.Equal("Delivered", resolve.Operational.Status);
        Assert.NotNull(resolve.Operational.TerminalAtUtc);
-        Assert.Equal(_id.Value, resolve.Audit.CorrelationId);
+        Assert.Equal(_id.Value, resolve.Audit.AsRow().CorrelationId);
    }

    [Fact]
@@ -116,9 +117,9 @@ public class CachedCallLifecycleBridgeTests
            lastError: "Permanent failure (handler returned false)"));

        Assert.Equal(2, captured.Count);
-        Assert.Equal(AuditKind.ApiCallCached, captured[0].Audit.Kind);
-        Assert.Equal(AuditKind.CachedResolve, captured[1].Audit.Kind);
-        Assert.Equal(AuditStatus.Parked, captured[1].Audit.Status);
+        Assert.Equal(AuditKind.ApiCallCached, captured[0].Audit.AsRow().Kind);
+        Assert.Equal(AuditKind.CachedResolve, captured[1].Audit.AsRow().Kind);
+        Assert.Equal(AuditStatus.Parked, captured[1].Audit.AsRow().Status);
        Assert.Equal("Parked", captured[1].Operational.Status);
    }

@@ -133,8 +134,8 @@ public class CachedCallLifecycleBridgeTests
        await sut.OnAttemptCompletedAsync(Ctx(CachedCallAttemptOutcome.ParkedMaxRetries));

        Assert.Equal(2, captured.Count);
-        Assert.Equal(AuditKind.CachedResolve, captured[1].Audit.Kind);
-        Assert.Equal(AuditStatus.Parked, captured[1].Audit.Status);
+        Assert.Equal(AuditKind.CachedResolve, captured[1].Audit.AsRow().Kind);
+        Assert.Equal(AuditStatus.Parked, captured[1].Audit.AsRow().Status);
    }

    [Fact]
@@ -149,11 +150,11 @@ public class CachedCallLifecycleBridgeTests
            CachedCallAttemptOutcome.Delivered, channel: "DbOutbound"));

        Assert.Equal(2, captured.Count);
-        Assert.Equal(AuditKind.DbWriteCached, captured[0].Audit.Kind);
-        Assert.Equal(AuditChannel.DbOutbound, captured[0].Audit.Channel);
+        Assert.Equal(AuditKind.DbWriteCached, captured[0].Audit.AsRow().Kind);
+        Assert.Equal(AuditChannel.DbOutbound, captured[0].Audit.AsRow().Channel);
        Assert.Equal("DbOutbound", captured[0].Operational.Channel);
-        Assert.Equal(AuditKind.CachedResolve, captured[1].Audit.Kind);
-        Assert.Equal(AuditChannel.DbOutbound, captured[1].Audit.Channel);
+        Assert.Equal(AuditKind.CachedResolve, captured[1].Audit.AsRow().Kind);
+        Assert.Equal(AuditChannel.DbOutbound, captured[1].Audit.AsRow().Channel);
    }

    [Fact]
@@ -184,11 +185,11 @@ public class CachedCallLifecycleBridgeTests
            httpStatus: 500));

        Assert.NotNull(captured);
-        Assert.Equal("site-77", captured!.Audit.SourceSiteId);
-        Assert.Equal("Plant.Pump42", captured.Audit.SourceInstanceId);
-        Assert.Equal("ERP.GetOrder", captured.Audit.Target);
-        Assert.Equal(42, captured.Audit.DurationMs);
-        Assert.Equal(_id.Value, captured.Audit.CorrelationId);
+        Assert.Equal("site-77", captured!.Audit.AsRow().SourceSiteId);
+        Assert.Equal("Plant.Pump42", captured.Audit.AsRow().SourceInstanceId);
+        Assert.Equal("ERP.GetOrder", captured.Audit.AsRow().Target);
+        Assert.Equal(42, captured.Audit.AsRow().DurationMs);
+        Assert.Equal(_id.Value, captured.Audit.AsRow().CorrelationId);
    }

    // ── Audit Log #23 (ExecutionId Task 4): ExecutionId / SourceScript ──
@@ -212,9 +213,9 @@ public class CachedCallLifecycleBridgeTests
            sourceScript: "Plant.Pump42/OnTick"));

        var packet = Assert.Single(captured);
-        Assert.Equal(AuditKind.ApiCallCached, packet.Audit.Kind);
-        Assert.Equal(executionId, packet.Audit.ExecutionId);
-        Assert.Equal("Plant.Pump42/OnTick", packet.Audit.SourceScript);
+        Assert.Equal(AuditKind.ApiCallCached, packet.Audit.AsRow().Kind);
+        Assert.Equal(executionId, packet.Audit.AsRow().ExecutionId);
+        Assert.Equal("Plant.Pump42/OnTick", packet.Audit.AsRow().SourceScript);
    }

    [Fact]
@@ -235,13 +236,13 @@ public class CachedCallLifecycleBridgeTests
            sourceScript: "Plant.Tank/OnAlarm"));

        Assert.Equal(2, captured.Count);
-        var resolve = Assert.Single(captured, p => p.Audit.Kind == AuditKind.CachedResolve);
-        Assert.Equal(executionId, resolve.Audit.ExecutionId);
-        Assert.Equal("Plant.Tank/OnAlarm", resolve.Audit.SourceScript);
+        var resolve = Assert.Single(captured, p => p.Audit.AsRow().Kind == AuditKind.CachedResolve);
+        Assert.Equal(executionId, resolve.Audit.AsRow().ExecutionId);
+        Assert.Equal("Plant.Tank/OnAlarm", resolve.Audit.AsRow().SourceScript);

-        var attempted = Assert.Single(captured, p => p.Audit.Kind == AuditKind.DbWriteCached);
-        Assert.Equal(executionId, attempted.Audit.ExecutionId);
-        Assert.Equal("Plant.Tank/OnAlarm", attempted.Audit.SourceScript);
+        var attempted = Assert.Single(captured, p => p.Audit.AsRow().Kind == AuditKind.DbWriteCached);
+        Assert.Equal(executionId, attempted.Audit.AsRow().ExecutionId);
+        Assert.Equal("Plant.Tank/OnAlarm", attempted.Audit.AsRow().SourceScript);
    }

    [Fact]
@@ -258,8 +259,8 @@ public class CachedCallLifecycleBridgeTests
        await sut.OnAttemptCompletedAsync(Ctx(CachedCallAttemptOutcome.TransientFailure));

        Assert.NotNull(captured);
-        Assert.Null(captured!.Audit.ExecutionId);
-        Assert.Null(captured.Audit.SourceScript);
+        Assert.Null(captured!.Audit.AsRow().ExecutionId);
+        Assert.Null(captured.Audit.AsRow().SourceScript);
    }

    // ── Audit Log #23 (ParentExecutionId Task 6): ParentExecutionId ──
@@ -282,8 +283,8 @@ public class CachedCallLifecycleBridgeTests
            parentExecutionId: parentExecutionId));

        var packet = Assert.Single(captured);
-        Assert.Equal(AuditKind.ApiCallCached, packet.Audit.Kind);
-        Assert.Equal(parentExecutionId, packet.Audit.ParentExecutionId);
+        Assert.Equal(AuditKind.ApiCallCached, packet.Audit.AsRow().Kind);
+        Assert.Equal(parentExecutionId, packet.Audit.AsRow().ParentExecutionId);
    }

    [Fact]
@@ -304,11 +305,11 @@ public class CachedCallLifecycleBridgeTests
            parentExecutionId: parentExecutionId));

        Assert.Equal(2, captured.Count);
-        var resolve = Assert.Single(captured, p => p.Audit.Kind == AuditKind.CachedResolve);
-        Assert.Equal(parentExecutionId, resolve.Audit.ParentExecutionId);
+        var resolve = Assert.Single(captured, p => p.Audit.AsRow().Kind == AuditKind.CachedResolve);
+        Assert.Equal(parentExecutionId, resolve.Audit.AsRow().ParentExecutionId);

-        var attempted = Assert.Single(captured, p => p.Audit.Kind == AuditKind.DbWriteCached);
-        Assert.Equal(parentExecutionId, attempted.Audit.ParentExecutionId);
+        var attempted = Assert.Single(captured, p => p.Audit.AsRow().Kind == AuditKind.DbWriteCached);
+        Assert.Equal(parentExecutionId, attempted.Audit.AsRow().ParentExecutionId);
    }

    [Fact]
@@ -325,7 +326,7 @@ public class CachedCallLifecycleBridgeTests
        await sut.OnAttemptCompletedAsync(Ctx(CachedCallAttemptOutcome.TransientFailure));

        Assert.NotNull(captured);
-        Assert.Null(captured!.Audit.ParentExecutionId);
+        Assert.Null(captured!.Audit.AsRow().ParentExecutionId);
    }

    // ── SourceNode-stamping (Task 14) ──
@@ -2,7 +2,9 @@ using Microsoft.Extensions.Logging.Abstractions;
 using NSubstitute;
 using NSubstitute.ExceptionExtensions;
 using ZB.MOM.WW.ScadaBridge.AuditLog.Site.Telemetry;
-using ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit;
+using ZB.MOM.WW.Audit;
+using IAuditWriter = ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services.IAuditWriter;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 using ZB.MOM.WW.ScadaBridge.Commons.Messages.Integration;
@@ -32,20 +34,17 @@ public class CachedCallTelemetryForwarderTests

    private CachedCallTelemetry SubmitPacket() =>
        new(
-            Audit: new AuditEvent
-            {
-                EventId = Guid.NewGuid(),
-                OccurredAtUtc = _now,
-                Channel = AuditChannel.ApiOutbound,
-                Kind = AuditKind.CachedSubmit,
-                CorrelationId = _id.Value,
-                SourceSiteId = "site-1",
-                SourceInstanceId = "inst-1",
-                SourceScript = "ScriptActor:doStuff",
-                Target = "ERP.GetOrder",
-                Status = AuditStatus.Submitted,
-                ForwardState = AuditForwardState.Pending,
-            },
+            Audit: ScadaBridgeAuditEventFactory.Create(
+                eventId: Guid.NewGuid(),
+                occurredAtUtc: _now,
+                channel: AuditChannel.ApiOutbound,
+                kind: AuditKind.CachedSubmit,
+                correlationId: _id.Value,
+                sourceSiteId: "site-1",
+                sourceInstanceId: "inst-1",
+                sourceScript: "ScriptActor:doStuff",
+                target: "ERP.GetOrder",
+                status: AuditStatus.Submitted),
            Operational: new SiteCallOperational(
                TrackedOperationId: _id,
                Channel: "ApiOutbound",
@@ -62,20 +61,17 @@ public class CachedCallTelemetryForwarderTests

    private CachedCallTelemetry AttemptedPacket(int retryCount = 1, string? lastError = "HTTP 500", int? httpStatus = 500) =>
        new(
-            Audit: new AuditEvent
-            {
-                EventId = Guid.NewGuid(),
-                OccurredAtUtc = _now,
-                Channel = AuditChannel.ApiOutbound,
-                Kind = AuditKind.ApiCallCached,
-                CorrelationId = _id.Value,
-                SourceSiteId = "site-1",
-                Target = "ERP.GetOrder",
-                Status = AuditStatus.Attempted,
-                HttpStatus = httpStatus,
-                ErrorMessage = lastError,
-                ForwardState = AuditForwardState.Pending,
-            },
+            Audit: ScadaBridgeAuditEventFactory.Create(
+                eventId: Guid.NewGuid(),
+                occurredAtUtc: _now,
+                channel: AuditChannel.ApiOutbound,
+                kind: AuditKind.ApiCallCached,
+                correlationId: _id.Value,
+                sourceSiteId: "site-1",
+                target: "ERP.GetOrder",
+                status: AuditStatus.Attempted,
+                httpStatus: httpStatus,
+                errorMessage: lastError),
            Operational: new SiteCallOperational(
                TrackedOperationId: _id,
                Channel: "ApiOutbound",
@@ -92,18 +88,15 @@ public class CachedCallTelemetryForwarderTests

    private CachedCallTelemetry ResolvePacket(string status = "Delivered") =>
        new(
-            Audit: new AuditEvent
-            {
-                EventId = Guid.NewGuid(),
-                OccurredAtUtc = _now,
-                Channel = AuditChannel.ApiOutbound,
-                Kind = AuditKind.CachedResolve,
-                CorrelationId = _id.Value,
-                SourceSiteId = "site-1",
-                Target = "ERP.GetOrder",
-                Status = Enum.Parse<AuditStatus>(status),
-                ForwardState = AuditForwardState.Pending,
-            },
+            Audit: ScadaBridgeAuditEventFactory.Create(
+                eventId: Guid.NewGuid(),
+                occurredAtUtc: _now,
+                channel: AuditChannel.ApiOutbound,
+                kind: AuditKind.CachedResolve,
+                correlationId: _id.Value,
+                sourceSiteId: "site-1",
+                target: "ERP.GetOrder",
+                status: Enum.Parse<AuditStatus>(status)),
            Operational: new SiteCallOperational(
                TrackedOperationId: _id,
                Channel: "ApiOutbound",
@@ -130,8 +123,8 @@ public class CachedCallTelemetryForwarderTests
        await _writer.Received(1).WriteAsync(
            Arg.Is<AuditEvent>(e =>
                e.EventId == packet.Audit.EventId
-                && e.Kind == AuditKind.CachedSubmit
-                && e.Status == AuditStatus.Submitted),
+                && e.AsRow().Kind == AuditKind.CachedSubmit
+                && e.AsRow().Status == AuditStatus.Submitted),
            Arg.Any<CancellationToken>());

        // Tracking row: insert-if-not-exists with kind discriminator.
@@ -165,8 +158,8 @@ public class CachedCallTelemetryForwarderTests
        await _writer.Received(1).WriteAsync(
            Arg.Is<AuditEvent>(e =>
                e.EventId == packet.Audit.EventId
-                && e.Kind == AuditKind.ApiCallCached
-                && e.Status == AuditStatus.Attempted),
+                && e.AsRow().Kind == AuditKind.ApiCallCached
+                && e.AsRow().Status == AuditStatus.Attempted),
            Arg.Any<CancellationToken>());

        await _tracking.Received(1).RecordAttemptAsync(
@@ -188,8 +181,8 @@ public class CachedCallTelemetryForwarderTests
        await _writer.Received(1).WriteAsync(
            Arg.Is<AuditEvent>(e =>
                e.EventId == packet.Audit.EventId
-                && e.Kind == AuditKind.CachedResolve
-                && e.Status == AuditStatus.Delivered),
+                && e.AsRow().Kind == AuditKind.CachedResolve
+                && e.AsRow().Status == AuditStatus.Delivered),
            Arg.Any<CancellationToken>());

        await _tracking.Received(1).RecordTerminalAsync(
@@ -2,7 +2,8 @@ using Akka.Actor;
 using Akka.TestKit.Xunit2;
 using Google.Protobuf.WellKnownTypes;
 using ZB.MOM.WW.ScadaBridge.AuditLog.Site.Telemetry;
-using ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
 using ZB.MOM.WW.ScadaBridge.Commons.Messages.Audit;
 using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
 using ZB.MOM.WW.ScadaBridge.Communication.Grpc;
@@ -29,16 +30,13 @@ public class ClusterClientSiteAuditClientTests : TestKit
    /// <summary>Short Ask timeout so the timeout test completes quickly.</summary>
    private static readonly TimeSpan AskTimeout = TimeSpan.FromMilliseconds(500);

-    private static AuditEvent NewEvent(Guid? id = null) => new()
-    {
-        EventId = id ?? Guid.NewGuid(),
-        OccurredAtUtc = new DateTime(2026, 5, 20, 10, 0, 0, DateTimeKind.Utc),
-        Channel = AuditChannel.ApiOutbound,
-        Kind = AuditKind.ApiCall,
-        Status = AuditStatus.Delivered,
-        SourceSiteId = "site-1",
-        ForwardState = AuditForwardState.Pending,
-    };
+    private static AuditEvent NewEvent(Guid? id = null) => ScadaBridgeAuditEventFactory.Create(
+        eventId: id ?? Guid.NewGuid(),
+        occurredAtUtc: new DateTime(2026, 5, 20, 10, 0, 0, DateTimeKind.Utc),
+        channel: AuditChannel.ApiOutbound,
+        kind: AuditKind.ApiCall,
+        status: AuditStatus.Delivered,
+        sourceSiteId: "site-1");

    private static AuditEventBatch BatchOf(IEnumerable<AuditEvent> events)
    {
@@ -6,7 +6,8 @@ using Microsoft.Extensions.Options;
 using NSubstitute;
 using NSubstitute.ExceptionExtensions;
 using ZB.MOM.WW.ScadaBridge.AuditLog.Site.Telemetry;
-using ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
 using ZB.MOM.WW.ScadaBridge.Commons.Types;
@@ -66,16 +67,13 @@ public class SiteAuditTelemetryActorTests : TestKit
            NullLogger<SiteAuditTelemetryActor>.Instance,
            (IOperationTrackingStore?)_trackingStore)));

-    private static AuditEvent NewEvent(Guid? id = null) => new()
-    {
-        EventId = id ?? Guid.NewGuid(),
-        OccurredAtUtc = new DateTime(2026, 5, 20, 10, 0, 0, DateTimeKind.Utc),
-        Channel = AuditChannel.ApiOutbound,
-        Kind = AuditKind.ApiCall,
-        Status = AuditStatus.Delivered,
-        SourceSiteId = "site-1",
-        ForwardState = AuditForwardState.Pending,
-    };
+    private static AuditEvent NewEvent(Guid? id = null) => ScadaBridgeAuditEventFactory.Create(
+        eventId: id ?? Guid.NewGuid(),
+        occurredAtUtc: new DateTime(2026, 5, 20, 10, 0, 0, DateTimeKind.Utc),
+        channel: AuditChannel.ApiOutbound,
+        kind: AuditKind.ApiCall,
+        status: AuditStatus.Delivered,
+        sourceSiteId: "site-1");

    private static IngestAck AckAll(IReadOnlyList<AuditEvent> events)
    {
@@ -265,18 +263,18 @@ public class SiteAuditTelemetryActorTests : TestKit
        AuditKind kind = AuditKind.CachedSubmit,
        Guid? eventId = null,
        Guid? correlationId = null,
-        string sourceSiteId = "site-1") => new()
-    {
-        EventId = eventId ?? Guid.NewGuid(),
-        OccurredAtUtc = new DateTime(2026, 5, 20, 10, 0, 0, DateTimeKind.Utc),
-        Channel = AuditChannel.ApiOutbound,
-        Kind = kind,
-        Status = AuditStatus.Submitted,
-        SourceSiteId = sourceSiteId,
-        Target = "ERP.GetOrder",
-        CorrelationId = correlationId ?? Guid.NewGuid(),
-        ForwardState = AuditForwardState.Pending,
-    };
+        string sourceSiteId = "site-1") =>
+        // C3 (Task 2.5): canonical record via the shared factory; ForwardState is
+        // no longer a record field (the SQLite shim defaults it on INSERT).
+        ScadaBridgeAuditEventFactory.Create(
+            channel: AuditChannel.ApiOutbound,
+            kind: kind,
+            status: AuditStatus.Submitted,
+            eventId: eventId ?? Guid.NewGuid(),
+            occurredAtUtc: new DateTime(2026, 5, 20, 10, 0, 0, DateTimeKind.Utc),
+            target: "ERP.GetOrder",
+            sourceSiteId: sourceSiteId,
+            correlationId: correlationId ?? Guid.NewGuid());

    private static TrackingStatusSnapshot NewSnapshot(
        TrackedOperationId id,