feat(auditlog): per-script-execution correlation id on sync audit rows

src/ScadaLink.SiteRuntime/Scripts/ScriptRuntimeContext.cs

@@ -105,6 +105,21 @@ public class ScriptRuntimeContext
     /// </summary>
     private readonly ICachedCallTelemetryForwarder? _cachedForwarder;
 
+    /// <summary>
+    /// Audit Log #23: the execution-wide audit correlation id. Every sync
+    /// trust-boundary audit row emitted by this script execution
+    /// (<c>ApiCall</c>, <c>DbWrite</c>) is stamped with this id so all the
+    /// rows from one script run can be correlated together.
+    /// </summary>
+    private readonly Guid _correlationId;
+
+    /// <param name="correlationId">
+    /// Audit Log #23: the execution-wide audit correlation id. When omitted
+    /// (tag-change / timer-triggered executions) a fresh id is generated; an
+    /// inbound caller may supply one to tie the execution to an upstream
+    /// request. Stamped on the sync <c>ApiCall</c>/<c>DbWrite</c> audit rows
+    /// this execution emits.
+    /// </param>
     public ScriptRuntimeContext(
         IActorRef instanceActor,
         IActorRef self,
@@ -122,7 +137,8 @@ public class ScriptRuntimeContext
         string? sourceScript = null,
         IAuditWriter? auditWriter = null,
         IOperationTrackingStore? operationTrackingStore = null,
-        ICachedCallTelemetryForwarder? cachedForwarder = null)
+        ICachedCallTelemetryForwarder? cachedForwarder = null,
+        Guid? correlationId = null)
     {
         _instanceActor = instanceActor;
         _self = self;
@@ -141,6 +157,7 @@ public class ScriptRuntimeContext
         _auditWriter = auditWriter;
         _operationTrackingStore = operationTrackingStore;
         _cachedForwarder = cachedForwarder;
+        _correlationId = correlationId ?? Guid.NewGuid();
     }
 
     /// <summary>
@@ -241,7 +258,7 @@ public class ScriptRuntimeContext
     /// ExternalSystem.CachedCall("systemName", "methodName", params)
     /// </summary>
     public ExternalSystemHelper ExternalSystem => new(
-        _externalSystemClient, _instanceName, _logger, _auditWriter, _siteId, _sourceScript,
+        _externalSystemClient, _instanceName, _logger, _correlationId, _auditWriter, _siteId, _sourceScript,
         // Audit Log #23 (M3 Bundle E — Task E3): emit CachedSubmit telemetry
         // on every ExternalSystem.CachedCall enqueue.
         _cachedForwarder);
@@ -255,6 +272,7 @@ public class ScriptRuntimeContext
         _databaseGateway,
         _instanceName,
         _logger,
+        _correlationId,
         // Audit Log #23 (M4 Bundle A): wire the IAuditWriter so
         // Database.Connection(name) returns an auditing decorator that
         // emits one DbOutbound/DbWrite row per script-initiated
@@ -362,6 +380,7 @@ public class ScriptRuntimeContext
         private readonly IExternalSystemClient? _client;
         private readonly string _instanceName;
         private readonly ILogger _logger;
+        private readonly Guid _correlationId;
         private readonly IAuditWriter? _auditWriter;
         private readonly string _siteId;
         private readonly string? _sourceScript;
@@ -374,6 +393,7 @@ public class ScriptRuntimeContext
             IExternalSystemClient? client,
             string instanceName,
             ILogger logger,
+            Guid correlationId,
             IAuditWriter? auditWriter = null,
             string siteId = "",
             string? sourceScript = null,
@@ -382,6 +402,7 @@ public class ScriptRuntimeContext
             _client = client;
             _instanceName = instanceName;
             _logger = logger;
+            _correlationId = correlationId;
             _auditWriter = auditWriter;
             _siteId = siteId;
             _sourceScript = sourceScript;
@@ -882,7 +903,9 @@ public class ScriptRuntimeContext
                 OccurredAtUtc = DateTime.SpecifyKind(occurredAtUtc, DateTimeKind.Utc),
                 Channel = AuditChannel.ApiOutbound,
                 Kind = AuditKind.ApiCall,
-                CorrelationId = null,
+                // Audit Log #23: the execution-wide correlation id, so all the
+                // sync ApiCall/DbWrite rows from one script run share an id.
+                CorrelationId = _correlationId,
                 SourceSiteId = string.IsNullOrEmpty(_siteId) ? null : _siteId,
                 SourceInstanceId = _instanceName,
                 SourceScript = _sourceScript,
@@ -949,6 +972,7 @@ public class ScriptRuntimeContext
         private readonly IDatabaseGateway? _gateway;
         private readonly string _instanceName;
         private readonly ILogger _logger;
+        private readonly Guid _correlationId;
         private readonly string _siteId;
         private readonly string? _sourceScript;
         private readonly ICachedCallTelemetryForwarder? _cachedForwarder;
@@ -969,6 +993,7 @@ public class ScriptRuntimeContext
             IDatabaseGateway? gateway,
             string instanceName,
             ILogger logger,
+            Guid correlationId,
             IAuditWriter? auditWriter = null,
             string siteId = "",
             string? sourceScript = null,
@@ -977,6 +1002,7 @@ public class ScriptRuntimeContext
             _gateway = gateway;
             _instanceName = instanceName;
             _logger = logger;
+            _correlationId = correlationId;
             _auditWriter = auditWriter;
             _siteId = siteId;
             _sourceScript = sourceScript;
@@ -1011,6 +1037,7 @@ public class ScriptRuntimeContext
                 siteId: _siteId,
                 instanceName: _instanceName,
                 sourceScript: _sourceScript,
+                correlationId: _correlationId,
                 logger: _logger);
         }