feat(audit): M5.5 per-channel retention overrides via purge-role bounded delete (T3)

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Repositories/IAuditLogRepository.cs

@@ -87,6 +87,42 @@ public interface IAuditLogRepository
     /// <returns>A task that resolves to the approximate number of rows discarded by the partition switch.</returns>
     Task<long> SwitchOutPartitionAsync(DateTime monthBoundary, CancellationToken ct = default);
 
+    /// <summary>
+    /// M5.5 (T3) per-channel retention override purge. Deletes <c>AuditLog</c> rows for a
+    /// single <paramref name="channel"/> (matched against the canonical
+    /// <c>Category</c> column — the bare channel name, e.g. <c>ApiOutbound</c>) whose
+    /// <c>OccurredAtUtc</c> is strictly older than <paramref name="threshold"/>, in
+    /// bounded batches of <paramref name="batchSize"/> rows, looping until no further
+    /// rows match. Returns the total number of rows deleted across all batches.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <b>Maintenance path — NOT the writer role.</b> The append-only invariant binds
+    /// the <c>scadabridge_audit_writer</c> ingest role (INSERT + SELECT only). This row
+    /// DELETE runs on the purge/maintenance connection, the same path that performs the
+    /// global partition switch-out (also a destructive operation forbidden to the writer
+    /// role). Per-channel overrides can only ever expire rows EARLIER than the global
+    /// month-partition switch-out would — never later — so this is a strict tightening
+    /// of the retention window, applied AFTER the global purge on the same tick.
+    /// </para>
+    /// <para>
+    /// <b>Bounded + idempotent.</b> Each batch is a <c>DELETE TOP (@batch)</c> so the
+    /// transaction log and lock footprint stay bounded regardless of backlog. Re-running
+    /// the purge is a no-op once every eligible row is gone (the loop exits when a batch
+    /// deletes zero rows), so a crash mid-loop is recoverable by simply running again.
+    /// </para>
+    /// </remarks>
+    /// <param name="channel">Canonical channel name (the <c>Category</c> column value, e.g. <c>ApiOutbound</c>).</param>
+    /// <param name="threshold">Rows with <c>OccurredAtUtc</c> strictly older than this UTC datetime are deleted.</param>
+    /// <param name="batchSize">Maximum rows deleted per batch; must be &gt; 0.</param>
+    /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to the total number of rows deleted across all batches.</returns>
+    Task<long> PurgeChannelOlderThanAsync(
+        string channel,
+        DateTime threshold,
+        int batchSize,
+        CancellationToken ct = default);
+
     /// <summary>
     /// Returns the set of <c>pf_AuditLog_Month</c> partition lower-bound
     /// boundaries whose partitions contain only rows with