feat(audit): M5.6 SourceNode sentinel backfill (purge-role) + CLI + runbook note (T5)

src/ZB.MOM.WW.ScadaBridge.ConfigurationDatabase/Repositories/AuditLogRepository.cs

@@ -716,6 +716,102 @@ VALUES
             .ToListAsync(ct);
     }
 
+    /// <inheritdoc />
+    public async Task<long> BackfillSourceNodeAsync(
+        string sentinel,
+        DateTime before,
+        int batchSize,
+        CancellationToken ct = default)
+    {
+        if (string.IsNullOrWhiteSpace(sentinel))
+        {
+            throw new ArgumentException("Sentinel must be a non-empty value.", nameof(sentinel));
+        }
+
+        if (batchSize <= 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(batchSize), batchSize, "Batch size must be > 0.");
+        }
+
+        var beforeUtc = DateTime.SpecifyKind(before.ToUniversalTime(), DateTimeKind.Utc);
+
+        // M5.6 (T5) SourceNode sentinel backfill. This is the ONE sanctioned UPDATE
+        // against dbo.AuditLog in the codebase. It touches ONLY rows where
+        // SourceNode IS NULL AND OccurredAtUtc < @before — rows that pre-date the
+        // M5.6 feature and whose node-of-origin is UNKNOWABLE. The sentinel (default
+        // "unknown") makes that explicit. ExecutionId/ParentExecutionId are PERSISTED
+        // COMPUTED columns derived from DetailsJson — mutating DetailsJson is forbidden
+        // under the append-only invariant, so those stay NULL on pre-feature rows.
+        //
+        // Maintenance path (NOT the writer role): runs on the same connection used for
+        // SwitchOutPartitionAsync (partition-switch DDL), which requires a role that
+        // holds UPDATE — the append-only scadabridge_audit_writer role has only
+        // INSERT + SELECT.
+        //
+        // Bounded + idempotent: UPDATE TOP (@batch) caps the log/lock footprint per
+        // statement; the loop exits when a batch updates 0 rows. Re-running after a
+        // crash simply resumes where it left off.
+        //
+        // The trailing AUDIT-PURGE-ALLOWED marker on the UPDATE line below is the
+        // single narrow exemption the append-only CI guard (AuditLogAppendOnlyGuardTests)
+        // recognises for an UPDATE; any other UPDATE targeting AuditLog still trips the guard.
+        const string updateBatchSql =
+            "UPDATE TOP (@batch) dbo.AuditLog SET SourceNode = @sentinel WHERE SourceNode IS NULL AND OccurredAtUtc < @before;"; // AUDIT-PURGE-ALLOWED: SourceNode sentinel backfill (M5.6 T5), maintenance path
+
+        long totalUpdated = 0;
+
+        var conn = _context.Database.GetDbConnection();
+        var openedHere = false;
+        if (conn.State != System.Data.ConnectionState.Open)
+        {
+            await conn.OpenAsync(ct).ConfigureAwait(false);
+            openedHere = true;
+        }
+
+        try
+        {
+            while (true)
+            {
+                ct.ThrowIfCancellationRequested();
+
+                await using var cmd = conn.CreateCommand();
+                cmd.CommandText = updateBatchSql;
+
+                var pBatch = cmd.CreateParameter();
+                pBatch.ParameterName = "@batch";
+                pBatch.Value = batchSize;
+                cmd.Parameters.Add(pBatch);
+
+                var pSentinel = cmd.CreateParameter();
+                pSentinel.ParameterName = "@sentinel";
+                pSentinel.Value = sentinel;
+                cmd.Parameters.Add(pSentinel);
+
+                var pBefore = cmd.CreateParameter();
+                pBefore.ParameterName = "@before";
+                pBefore.Value = beforeUtc;
+                cmd.Parameters.Add(pBefore);
+
+                var rows = await cmd.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
+                if (rows <= 0)
+                {
+                    break;
+                }
+
+                totalUpdated += rows;
+            }
+        }
+        finally
+        {
+            if (openedHere)
+            {
+                await conn.CloseAsync().ConfigureAwait(false);
+            }
+        }
+
+        return totalUpdated;
+    }
+
     /// <summary>
     /// Splits a <c>STRING_AGG</c> comma-joined value into a distinct, ordered
     /// list. A null/empty aggregate (a stub node with no rows) yields an empty