docs: complete XML doc coverage (returns, summaries, inheritdoc)

Resolve all 622 issues flagged by the enhanced CommentChecker: add missing
<returns> tags (incl. the standard phrasing on non-generic Task methods),
add missing <summary> tags, and replace misused/redundant <inheritdoc/> on
members that override or implement nothing with real documentation.
Documentation-only — no behavior change; solution builds clean.

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IAuditService.cs

@@ -12,5 +12,6 @@ public interface IAuditService
     /// <param name="entityName">The display name of the affected entity.</param>
     /// <param name="afterState">The entity state after the action; may be null for deletes.</param>
     /// <param name="cancellationToken">Cancellation token for the log write.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task LogAsync(string user, string action, string entityType, string entityId, string entityName, object? afterState, CancellationToken cancellationToken = default);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IAuditWriter.cs

@@ -21,5 +21,6 @@ public interface IAuditWriter
     /// </summary>
     /// <param name="evt">The audit event to persist.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task representing the asynchronous write operation.</returns>
     Task WriteAsync(AuditEvent evt, CancellationToken ct = default);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/ICachedCallLifecycleObserver.cs

@@ -36,6 +36,7 @@ public interface ICachedCallLifecycleObserver
     /// </summary>
     /// <param name="context">Per-attempt context including the tracking id, outcome, and audit provenance fields.</param>
     /// <param name="ct">Cancellation token for the observation operation.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task OnAttemptCompletedAsync(CachedCallAttemptContext context, CancellationToken ct = default);
 }
 

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/ICachedCallTelemetryForwarder.cs

@@ -32,5 +32,6 @@ public interface ICachedCallTelemetryForwarder
     /// </summary>
     /// <param name="telemetry">The combined-telemetry packet to fan out.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task ForwardAsync(CachedCallTelemetry telemetry, CancellationToken ct = default);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/ICentralAuditWriter.cs

@@ -14,5 +14,6 @@ public interface ICentralAuditWriter
     /// </summary>
     /// <param name="evt">The audit event to persist.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task WriteAsync(AuditEvent evt, CancellationToken ct = default);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IDatabaseGateway.cs

@@ -16,6 +16,7 @@ public interface IDatabaseGateway
     /// </summary>
     /// <param name="connectionName">Name of the configured database connection to open.</param>
     /// <param name="cancellationToken">Cancellation token for the async open operation.</param>
+    /// <returns>A task that resolves to an open <see cref="DbConnection"/>; the caller is responsible for disposing it.</returns>
     Task<DbConnection> GetConnectionAsync(
         string connectionName,
         CancellationToken cancellationToken = default);
@@ -55,6 +56,7 @@ public interface IDatabaseGateway
     /// <param name="parameters">Optional SQL parameters for the statement.</param>
     /// <param name="originInstanceName">Optional name of the instance that originated the write.</param>
     /// <param name="cancellationToken">Cancellation token for the buffering operation.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task CachedWriteAsync(
         string connectionName,
         string sql,

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IInstanceLocator.cs

@@ -12,6 +12,7 @@ public interface IInstanceLocator
     /// </summary>
     /// <param name="instanceUniqueName">System-wide unique name of the instance to look up.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that resolves to the site identifier for the instance, or <c>null</c> if the instance is not found.</returns>
     Task<string?> GetSiteIdForInstanceAsync(
         string instanceUniqueName,
         CancellationToken cancellationToken = default);

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IOperationTrackingStore.cs

@@ -47,6 +47,7 @@ public interface IOperationTrackingStore
     /// <param name="sourceScript">Optional name of the source script.</param>
     /// <param name="sourceNode">Optional source node identifier.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task RecordEnqueueAsync(
         TrackedOperationId id,
         string kind,
@@ -68,6 +69,7 @@ public interface IOperationTrackingStore
     /// <param name="lastError">Optional error message from the last attempt.</param>
     /// <param name="httpStatus">Optional HTTP status code from the last attempt.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task RecordAttemptAsync(
         TrackedOperationId id,
         string status,
@@ -86,6 +88,7 @@ public interface IOperationTrackingStore
     /// <param name="lastError">Optional final error message.</param>
     /// <param name="httpStatus">Optional final HTTP status code.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task RecordTerminalAsync(
         TrackedOperationId id,
         string status,
@@ -111,6 +114,7 @@ public interface IOperationTrackingStore
     /// </summary>
     /// <param name="olderThanUtc">Cutoff timestamp; rows terminal before this are deleted.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task PurgeTerminalAsync(
         DateTime olderThanUtc,
         CancellationToken ct = default);

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/IPartitionMaintenance.cs

@@ -44,6 +44,7 @@ public interface IPartitionMaintenance
     /// </summary>
     /// <param name="lookaheadMonths">Number of future monthly boundaries to ensure exist.</param>
     /// <param name="ct">Cancellation token for the SQL operation.</param>
+    /// <returns>A task that resolves to the list of boundary values actually added, in chronological order.</returns>
     Task<IReadOnlyList<DateTime>> EnsureLookaheadAsync(int lookaheadMonths, CancellationToken ct = default);
 
     /// <summary>
@@ -53,5 +54,6 @@ public interface IPartitionMaintenance
     /// has no boundaries.
     /// </summary>
     /// <param name="ct">Cancellation token for the SQL operation.</param>
+    /// <returns>A task that resolves to the highest boundary value, or <c>null</c> when the partition function has no boundaries.</returns>
     Task<DateTime?> GetMaxBoundaryAsync(CancellationToken ct = default);
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Services/ISiteAuditQueue.cs

@@ -47,6 +47,7 @@ public interface ISiteAuditQueue
     /// </remarks>
     /// <param name="limit">Maximum number of rows to return.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to the oldest pending non-cached audit events, up to <paramref name="limit"/>.</returns>
     Task<IReadOnlyList<AuditEvent>> ReadPendingAsync(int limit, CancellationToken ct = default);
 
     /// <summary>
@@ -77,6 +78,7 @@ public interface ISiteAuditQueue
     /// </remarks>
     /// <param name="limit">Maximum number of rows to return.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to the oldest pending cached-lifecycle audit events, up to <paramref name="limit"/>.</returns>
     Task<IReadOnlyList<AuditEvent>> ReadPendingCachedTelemetryAsync(int limit, CancellationToken ct = default);
 
     /// <summary>
@@ -87,6 +89,7 @@ public interface ISiteAuditQueue
     /// </summary>
     /// <param name="eventIds">Event IDs to mark as forwarded.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task MarkForwardedAsync(IReadOnlyList<Guid> eventIds, CancellationToken ct = default);
 
     /// <summary>
@@ -107,6 +110,7 @@ public interface ISiteAuditQueue
     /// <param name="sinceUtc">Lower bound timestamp (UTC).</param>
     /// <param name="batchSize">Maximum number of rows to return.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to audit events at or after <paramref name="sinceUtc"/> in pending or forwarded state, up to <paramref name="batchSize"/>.</returns>
     Task<IReadOnlyList<AuditEvent>> ReadPendingSinceAsync(
         DateTime sinceUtc, int batchSize, CancellationToken ct = default);
 
@@ -121,6 +125,7 @@ public interface ISiteAuditQueue
     /// </summary>
     /// <param name="eventIds">Event IDs to mark as reconciled.</param>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     Task MarkReconciledAsync(IReadOnlyList<Guid> eventIds, CancellationToken ct = default);
 
     /// <summary>
@@ -135,5 +140,6 @@ public interface ISiteAuditQueue
     /// the hot-path INSERT batch and the drain queries.
     /// </summary>
     /// <param name="ct">Cancellation token.</param>
+    /// <returns>A task that resolves to a point-in-time snapshot of the site audit queue's pending count, oldest timestamp, and on-disk file size.</returns>
     Task<SiteAuditBacklogSnapshot> GetBacklogStatsAsync(CancellationToken ct = default);
 }