refactor(notification-outbox): align outbox repository with cancellationToken convention

src/ScadaLink.Commons/Interfaces/Repositories/INotificationOutboxRepository.cs

@@ -8,14 +8,21 @@ namespace ScadaLink.Commons.Interfaces.Repositories;
 /// rows the outbox actor drains, retries, and audits. Distinct from
 /// <see cref="INotificationRepository"/>, which manages notification list configuration.
 /// </summary>
+/// <remarks>
+/// Persistence model: <see cref="InsertIfNotExistsAsync"/> and <see cref="UpdateAsync"/> commit
+/// internally, so each call is its own transaction — suited to the outbox actor committing one
+/// row's status transition at a time. The standalone <see cref="SaveChangesAsync"/> is available
+/// for callers that stage multiple changes and want to flush them together.
+/// </remarks>
 public interface INotificationOutboxRepository
 {
     /// <summary>
     /// Inserts <paramref name="n"/> only if no row with the same
     /// <see cref="Notification.NotificationId"/> exists. Returns <c>true</c> when a new
     /// row was inserted, <c>false</c> when an existing row was left untouched.
+    /// Commits internally — this call is its own transaction.
     /// </summary>
-    Task<bool> InsertIfNotExistsAsync(Notification n, CancellationToken ct = default);
+    Task<bool> InsertIfNotExistsAsync(Notification n, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Returns notifications ready for a delivery attempt: <c>Pending</c> rows, plus
@@ -23,26 +30,29 @@ public interface INotificationOutboxRepository
     /// Terminal rows are excluded. Ordered by <c>CreatedAt</c> ascending, capped at
     /// <paramref name="batchSize"/>.
     /// </summary>
-    Task<IReadOnlyList<Notification>> GetDueAsync(DateTimeOffset now, int batchSize, CancellationToken ct = default);
+    Task<IReadOnlyList<Notification>> GetDueAsync(DateTimeOffset now, int batchSize, CancellationToken cancellationToken = default);
 
     /// <summary>Returns the notification with the given id, or <c>null</c>.</summary>
-    Task<Notification?> GetByIdAsync(string notificationId, CancellationToken ct = default);
+    Task<Notification?> GetByIdAsync(string notificationId, CancellationToken cancellationToken = default);
 
-    /// <summary>Marks <paramref name="n"/> modified and persists it (status transitions).</summary>
-    Task UpdateAsync(Notification n, CancellationToken ct = default);
+    /// <summary>
+    /// Marks <paramref name="n"/> modified and persists it (status transitions).
+    /// Commits internally — this call is its own transaction.
+    /// </summary>
+    Task UpdateAsync(Notification n, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Returns a page of notifications matching <paramref name="filter"/>, ordered by
     /// <c>CreatedAt</c> descending, together with the total matching count.
     /// </summary>
     Task<(IReadOnlyList<Notification> Rows, int TotalCount)> QueryAsync(
-        NotificationOutboxFilter filter, int pageNumber, int pageSize, CancellationToken ct = default);
+        NotificationOutboxFilter filter, int pageNumber, int pageSize, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Bulk-deletes terminal rows (Delivered/Parked/Discarded) whose <c>CreatedAt</c> is
     /// older than <paramref name="cutoff"/>. Returns the number of rows deleted.
     /// </summary>
-    Task<int> DeleteTerminalOlderThanAsync(DateTimeOffset cutoff, CancellationToken ct = default);
+    Task<int> DeleteTerminalOlderThanAsync(DateTimeOffset cutoff, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Computes a point-in-time <see cref="NotificationKpiSnapshot"/>. The stuck and
@@ -50,8 +60,12 @@ public interface INotificationOutboxRepository
     /// <c>OldestPendingAge</c> is captured inside the method.
     /// </summary>
     Task<NotificationKpiSnapshot> ComputeKpisAsync(
-        DateTimeOffset stuckCutoff, DateTimeOffset deliveredSince, CancellationToken ct = default);
+        DateTimeOffset stuckCutoff, DateTimeOffset deliveredSince, CancellationToken cancellationToken = default);
 
-    /// <summary>Persists pending changes tracked on the underlying context.</summary>
-    Task<int> SaveChangesAsync(CancellationToken ct = default);
+    /// <summary>
+    /// Persists pending changes tracked on the underlying context. Use this when staging
+    /// multiple changes for a single commit; the individual mutating methods on this
+    /// interface already commit on their own.
+    /// </summary>
+    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
 }