refactor(auditlog): rename audit correlation field, add cross-helper tests

src/ScadaLink.SiteRuntime/Scripts/AuditingDbCommand.cs

@@ -37,10 +37,13 @@ internal sealed class AuditingDbCommand : DbCommand
     private readonly string _siteId;
     private readonly string _instanceName;
     private readonly string? _sourceScript;
-    private readonly Guid _correlationId;
+    private readonly Guid _auditCorrelationId;
     private readonly ILogger _logger;
     private DbConnection? _wrappingConnection;
 
+    // Parameter ordering: auditCorrelationId sits immediately after the ILogger,
+    // consistent with the other three audit-threaded ctors (ExternalSystemHelper,
+    // DatabaseHelper, AuditingDbConnection).
     public AuditingDbCommand(
         DbCommand inner,
         IAuditWriter auditWriter,
@@ -48,8 +51,8 @@ internal sealed class AuditingDbCommand : DbCommand
         string siteId,
         string instanceName,
         string? sourceScript,
-        Guid correlationId,
-        ILogger logger)
+        ILogger logger,
+        Guid auditCorrelationId)
     {
         _inner = inner ?? throw new ArgumentNullException(nameof(inner));
         _auditWriter = auditWriter ?? throw new ArgumentNullException(nameof(auditWriter));
@@ -57,8 +60,8 @@ internal sealed class AuditingDbCommand : DbCommand
         _siteId = siteId ?? string.Empty;
         _instanceName = instanceName ?? string.Empty;
         _sourceScript = sourceScript;
-        _correlationId = correlationId;
         _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _auditCorrelationId = auditCorrelationId;
     }
 
     // -- Forwarded surface ------------------------------------------------
@@ -429,9 +432,10 @@ internal sealed class AuditingDbCommand : DbCommand
             OccurredAtUtc = DateTime.SpecifyKind(occurredAtUtc, DateTimeKind.Utc),
             Channel = AuditChannel.DbOutbound,
             Kind = AuditKind.DbWrite,
-            // Audit Log #23: the execution-wide correlation id, so all the
-            // sync ApiCall/DbWrite rows from one script run share an id.
-            CorrelationId = _correlationId,
+            // Audit Log #23: the execution-wide correlation id, so this sync
+            // DbWrite row shares an id with the other sync trust-boundary rows
+            // from the same script run.
+            CorrelationId = _auditCorrelationId,
             SourceSiteId = string.IsNullOrEmpty(_siteId) ? null : _siteId,
             SourceInstanceId = _instanceName,
             SourceScript = _sourceScript,

src/ScadaLink.SiteRuntime/Scripts/AuditingDbConnection.cs

@@ -36,9 +36,12 @@ internal sealed class AuditingDbConnection : DbConnection
     private readonly string _siteId;
     private readonly string _instanceName;
     private readonly string? _sourceScript;
-    private readonly Guid _correlationId;
+    private readonly Guid _auditCorrelationId;
     private readonly ILogger _logger;
 
+    // Parameter ordering: auditCorrelationId sits immediately after the ILogger,
+    // consistent with the other three audit-threaded ctors (ExternalSystemHelper,
+    // DatabaseHelper, AuditingDbCommand).
     public AuditingDbConnection(
         DbConnection inner,
         IAuditWriter auditWriter,
@@ -46,8 +49,8 @@ internal sealed class AuditingDbConnection : DbConnection
         string siteId,
         string instanceName,
         string? sourceScript,
-        Guid correlationId,
-        ILogger logger)
+        ILogger logger,
+        Guid auditCorrelationId)
     {
         _inner = inner ?? throw new ArgumentNullException(nameof(inner));
         _auditWriter = auditWriter ?? throw new ArgumentNullException(nameof(auditWriter));
@@ -55,8 +58,8 @@ internal sealed class AuditingDbConnection : DbConnection
         _siteId = siteId ?? string.Empty;
         _instanceName = instanceName ?? string.Empty;
         _sourceScript = sourceScript;
-        _correlationId = correlationId;
         _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _auditCorrelationId = auditCorrelationId;
     }
 
     // ConnectionString is settable on DbConnection — forward both halves.
@@ -95,8 +98,8 @@ internal sealed class AuditingDbConnection : DbConnection
             _siteId,
             _instanceName,
             _sourceScript,
-            _correlationId,
-            _logger);
+            _logger,
+            _auditCorrelationId);
     }
 
     protected override void Dispose(bool disposing)

src/ScadaLink.SiteRuntime/Scripts/ScriptRuntimeContext.cs

@@ -111,9 +111,9 @@ public class ScriptRuntimeContext
     /// (<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;
+    private readonly Guid _auditCorrelationId;
 
-    /// <param name="correlationId">
+    /// <param name="auditCorrelationId">
     /// 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
@@ -138,7 +138,7 @@ public class ScriptRuntimeContext
         IAuditWriter? auditWriter = null,
         IOperationTrackingStore? operationTrackingStore = null,
         ICachedCallTelemetryForwarder? cachedForwarder = null,
-        Guid? correlationId = null)
+        Guid? auditCorrelationId = null)
     {
         _instanceActor = instanceActor;
         _self = self;
@@ -157,7 +157,7 @@ public class ScriptRuntimeContext
         _auditWriter = auditWriter;
         _operationTrackingStore = operationTrackingStore;
         _cachedForwarder = cachedForwarder;
-        _correlationId = correlationId ?? Guid.NewGuid();
+        _auditCorrelationId = auditCorrelationId ?? Guid.NewGuid();
     }
 
     /// <summary>
@@ -258,7 +258,7 @@ public class ScriptRuntimeContext
     /// ExternalSystem.CachedCall("systemName", "methodName", params)
     /// </summary>
     public ExternalSystemHelper ExternalSystem => new(
-        _externalSystemClient, _instanceName, _logger, _correlationId, _auditWriter, _siteId, _sourceScript,
+        _externalSystemClient, _instanceName, _logger, _auditCorrelationId, _auditWriter, _siteId, _sourceScript,
         // Audit Log #23 (M3 Bundle E — Task E3): emit CachedSubmit telemetry
         // on every ExternalSystem.CachedCall enqueue.
         _cachedForwarder);
@@ -272,7 +272,7 @@ public class ScriptRuntimeContext
         _databaseGateway,
         _instanceName,
         _logger,
-        _correlationId,
+        _auditCorrelationId,
         // 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
@@ -380,7 +380,7 @@ public class ScriptRuntimeContext
         private readonly IExternalSystemClient? _client;
         private readonly string _instanceName;
         private readonly ILogger _logger;
-        private readonly Guid _correlationId;
+        private readonly Guid _auditCorrelationId;
         private readonly IAuditWriter? _auditWriter;
         private readonly string _siteId;
         private readonly string? _sourceScript;
@@ -389,11 +389,18 @@ public class ScriptRuntimeContext
         // Internal constructor for tests living in ScadaLink.SiteRuntime.Tests
         // (via InternalsVisibleTo). Production sites resolve the helper through
         // ScriptRuntimeContext.ExternalSystem.
+        //
+        // Parameter ordering: auditCorrelationId sits immediately after the
+        // ILogger across all four audit-threaded ctors (ExternalSystemHelper,
+        // DatabaseHelper, AuditingDbConnection, AuditingDbCommand) — a required
+        // Guid cannot follow the optional provenance params without a
+        // required-after-optional compile error, so the post-logger slot is the
+        // one consistent position that compiles cleanly everywhere.
         internal ExternalSystemHelper(
             IExternalSystemClient? client,
             string instanceName,
             ILogger logger,
-            Guid correlationId,
+            Guid auditCorrelationId,
             IAuditWriter? auditWriter = null,
             string siteId = "",
             string? sourceScript = null,
@@ -402,7 +409,7 @@ public class ScriptRuntimeContext
             _client = client;
             _instanceName = instanceName;
             _logger = logger;
-            _correlationId = correlationId;
+            _auditCorrelationId = auditCorrelationId;
             _auditWriter = auditWriter;
             _siteId = siteId;
             _sourceScript = sourceScript;
@@ -905,7 +912,7 @@ public class ScriptRuntimeContext
                 Kind = AuditKind.ApiCall,
                 // Audit Log #23: the execution-wide correlation id, so all the
                 // sync ApiCall/DbWrite rows from one script run share an id.
-                CorrelationId = _correlationId,
+                CorrelationId = _auditCorrelationId,
                 SourceSiteId = string.IsNullOrEmpty(_siteId) ? null : _siteId,
                 SourceInstanceId = _instanceName,
                 SourceScript = _sourceScript,
@@ -972,7 +979,7 @@ public class ScriptRuntimeContext
         private readonly IDatabaseGateway? _gateway;
         private readonly string _instanceName;
         private readonly ILogger _logger;
-        private readonly Guid _correlationId;
+        private readonly Guid _auditCorrelationId;
         private readonly string _siteId;
         private readonly string? _sourceScript;
         private readonly ICachedCallTelemetryForwarder? _cachedForwarder;
@@ -989,11 +996,15 @@ public class ScriptRuntimeContext
         /// </summary>
         private readonly IAuditWriter? _auditWriter;
 
+        // Parameter ordering: auditCorrelationId sits immediately after the
+        // ILogger — see the note on ExternalSystemHelper's ctor for why the
+        // post-logger slot is the one consistent position across all four
+        // audit-threaded ctors.
         internal DatabaseHelper(
             IDatabaseGateway? gateway,
             string instanceName,
             ILogger logger,
-            Guid correlationId,
+            Guid auditCorrelationId,
             IAuditWriter? auditWriter = null,
             string siteId = "",
             string? sourceScript = null,
@@ -1002,7 +1013,7 @@ public class ScriptRuntimeContext
             _gateway = gateway;
             _instanceName = instanceName;
             _logger = logger;
-            _correlationId = correlationId;
+            _auditCorrelationId = auditCorrelationId;
             _auditWriter = auditWriter;
             _siteId = siteId;
             _sourceScript = sourceScript;
@@ -1037,8 +1048,8 @@ public class ScriptRuntimeContext
                 siteId: _siteId,
                 instanceName: _instanceName,
                 sourceScript: _sourceScript,
-                correlationId: _correlationId,
-                logger: _logger);
+                logger: _logger,
+                auditCorrelationId: _auditCorrelationId);
         }
 
         /// <summary>