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.SiteRuntime/Persistence/SiteStorageInitializer.cs

@@ -23,6 +23,7 @@ public class SiteStorageInitializer : IHostedService
     /// Initializes the SQLite schema before the actor system starts.
     /// </summary>
     /// <param name="cancellationToken">Cancellation token for the startup operation.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task StartAsync(CancellationToken cancellationToken)
     {
         await _storage.InitializeAsync();
@@ -32,5 +33,6 @@ public class SiteStorageInitializer : IHostedService
     /// No-op stop; schema initialization does not require cleanup.
     /// </summary>
     /// <param name="cancellationToken">Unused cancellation token.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
 }

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Persistence/SiteStorageService.cs

@@ -30,12 +30,14 @@ public class SiteStorageService
     /// reaching into private state via reflection (SiteRuntime-006). The caller owns
     /// the connection and is responsible for opening and disposing it.
     /// </summary>
+    /// <returns>A new, unopened <see cref="SqliteConnection"/> against the site database.</returns>
     public SqliteConnection CreateConnection() => new(_connectionString);
 
     /// <summary>
     /// Creates the SQLite tables if they do not exist.
     /// Called once on site startup.
     /// </summary>
+    /// <returns>A task that completes when all tables have been created or verified.</returns>
     public async Task InitializeAsync()
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -157,6 +159,7 @@ public class SiteStorageService
     /// <summary>
     /// Returns all deployed instance configurations from SQLite.
     /// </summary>
+    /// <returns>A task that resolves to the list of all deployed instance configurations.</returns>
     public async Task<List<DeployedInstance>> GetAllDeployedConfigsAsync()
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -193,6 +196,7 @@ public class SiteStorageService
     /// <param name="deploymentId">The unique deployment identifier.</param>
     /// <param name="revisionHash">The configuration revision hash for staleness detection.</param>
     /// <param name="isEnabled">Whether the instance is enabled.</param>
+    /// <returns>A task that completes when the configuration has been stored or updated.</returns>
     public async Task StoreDeployedConfigAsync(
         string instanceName,
         string configJson,
@@ -229,6 +233,7 @@ public class SiteStorageService
     /// Removes a deployed instance configuration and its static overrides.
     /// </summary>
     /// <param name="instanceName">The unique name of the instance to remove.</param>
+    /// <returns>A task that completes when the configuration and its overrides have been removed.</returns>
     public async Task RemoveDeployedConfigAsync(string instanceName)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -269,6 +274,7 @@ public class SiteStorageService
     /// </summary>
     /// <param name="instanceName">The unique name of the instance.</param>
     /// <param name="isEnabled">Whether the instance should be enabled.</param>
+    /// <returns>A task that completes when the enabled flag has been updated.</returns>
     public async Task SetInstanceEnabledAsync(string instanceName, bool isEnabled)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -296,6 +302,7 @@ public class SiteStorageService
     /// Returns all static attribute overrides for an instance.
     /// </summary>
     /// <param name="instanceName">The unique name of the instance.</param>
+    /// <returns>A task that resolves to a dictionary mapping attribute names to their override values.</returns>
     public async Task<Dictionary<string, string>> GetStaticOverridesAsync(string instanceName)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -324,6 +331,7 @@ public class SiteStorageService
     /// <param name="instanceName">The unique name of the instance.</param>
     /// <param name="attributeName">The name of the attribute to override.</param>
     /// <param name="value">The override value for the attribute.</param>
+    /// <returns>A task that completes when the override has been saved.</returns>
     public async Task SetStaticOverrideAsync(string instanceName, string attributeName, string value)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -350,6 +358,7 @@ public class SiteStorageService
     /// Called on redeployment to reset overrides.
     /// </summary>
     /// <param name="instanceName">The unique name of the instance.</param>
+    /// <returns>A task that completes when all overrides for the instance have been deleted.</returns>
     public async Task ClearStaticOverridesAsync(string instanceName)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -369,6 +378,12 @@ public class SiteStorageService
     /// Inserts or updates a single mirrored native alarm condition, keyed by
     /// (instance, source canonical name, source reference). Newer transitions overwrite older ones.
     /// </summary>
+    /// <param name="instanceName">Unique name of the instance owning the alarm.</param>
+    /// <param name="sourceCanonicalName">Canonical name of the source binding (connection/alarm source).</param>
+    /// <param name="sourceReference">Source-system reference key identifying the specific alarm condition.</param>
+    /// <param name="conditionJson">Serialized <see cref="AlarmConditionState"/> JSON snapshot.</param>
+    /// <param name="lastTransitionAt">Timestamp of the most recent condition transition.</param>
+    /// <returns>A task that completes when the alarm condition has been inserted or updated.</returns>
     public async Task UpsertNativeAlarmAsync(
         string instanceName, string sourceCanonicalName, string sourceReference,
         string conditionJson, DateTimeOffset lastTransitionAt)
@@ -397,6 +412,10 @@ public class SiteStorageService
     /// <summary>
     /// Removes a single mirrored native alarm condition (e.g. a return-to-normal that drops out of retention).
     /// </summary>
+    /// <param name="instanceName">Unique name of the instance owning the alarm.</param>
+    /// <param name="sourceCanonicalName">Canonical name of the source binding.</param>
+    /// <param name="sourceReference">Source-system reference key identifying the alarm condition to remove.</param>
+    /// <returns>A task that completes when the alarm condition row has been deleted.</returns>
     public async Task DeleteNativeAlarmAsync(string instanceName, string sourceCanonicalName, string sourceReference)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -419,6 +438,9 @@ public class SiteStorageService
     /// Returns all mirrored native alarm conditions for an instance's source binding,
     /// used to rehydrate a NativeAlarmActor on (re)start.
     /// </summary>
+    /// <param name="instanceName">Unique name of the instance to query.</param>
+    /// <param name="sourceCanonicalName">Canonical name of the source binding to query.</param>
+    /// <returns>A task that resolves to the list of stored native alarm condition rows for the binding.</returns>
     public async Task<IReadOnlyList<NativeAlarmRow>> GetNativeAlarmsAsync(string instanceName, string sourceCanonicalName)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -448,6 +470,8 @@ public class SiteStorageService
     /// <summary>
     /// Clears all mirrored native alarm conditions for an instance. Called on redeployment / stop.
     /// </summary>
+    /// <param name="instanceName">Unique name of the instance whose native alarm state should be cleared.</param>
+    /// <returns>A task that completes when all native alarm rows for the instance have been deleted.</returns>
     public async Task ClearNativeAlarmsForInstanceAsync(string instanceName)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -470,6 +494,7 @@ public class SiteStorageService
     /// <param name="code">The script code.</param>
     /// <param name="parameterDefs">JSON representation of parameter definitions, if any.</param>
     /// <param name="returnDef">JSON representation of the return type definition, if any.</param>
+    /// <returns>A task that completes when the shared script has been stored or updated.</returns>
     public async Task StoreSharedScriptAsync(string name, string code, string? parameterDefs, string? returnDef)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -498,6 +523,7 @@ public class SiteStorageService
     /// <summary>
     /// Returns all stored shared scripts.
     /// </summary>
+    /// <returns>A task that resolves to the list of all stored shared scripts.</returns>
     public async Task<List<StoredSharedScript>> GetAllSharedScriptsAsync()
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -532,6 +558,7 @@ public class SiteStorageService
     /// <param name="authType">The authentication type (e.g., 'ApiKey', 'BasicAuth').</param>
     /// <param name="authConfig">Authentication configuration JSON, if applicable.</param>
     /// <param name="methodDefs">JSON representation of available method definitions, if any.</param>
+    /// <returns>A task that completes when the external system definition has been stored or updated.</returns>
     public async Task StoreExternalSystemAsync(
         string name, string endpointUrl, string authType, string? authConfig, string? methodDefs)
     {
@@ -568,6 +595,7 @@ public class SiteStorageService
     /// <param name="connectionString">The database connection string.</param>
     /// <param name="maxRetries">Maximum number of retry attempts.</param>
     /// <param name="retryDelay">Delay between retry attempts.</param>
+    /// <returns>A task that completes when the database connection definition has been stored or updated.</returns>
     public async Task StoreDatabaseConnectionAsync(
         string name, string connectionString, int maxRetries, TimeSpan retryDelay)
     {
@@ -600,6 +628,7 @@ public class SiteStorageService
     /// </summary>
     /// <param name="name">The name of the notification list.</param>
     /// <param name="recipientEmails">List of recipient email addresses.</param>
+    /// <returns>A task that completes when the notification list has been stored or updated.</returns>
     public async Task StoreNotificationListAsync(string name, IReadOnlyList<string> recipientEmails)
     {
         await using var connection = new SqliteConnection(_connectionString);
@@ -633,6 +662,7 @@ public class SiteStorageService
     /// <param name="username">Username for authentication, if applicable.</param>
     /// <param name="password">Password for authentication, if applicable.</param>
     /// <param name="oauthConfig">OAuth2 configuration JSON, if applicable.</param>
+    /// <returns>A task that completes when the SMTP configuration has been stored or updated.</returns>
     public async Task StoreSmtpConfigurationAsync(
         string name, string server, int port, string authMode, string fromAddress,
         string? username, string? password, string? oauthConfig)
@@ -677,6 +707,7 @@ public class SiteStorageService
     /// <param name="configJson">Primary configuration as JSON.</param>
     /// <param name="backupConfigJson">Backup configuration as JSON, if applicable.</param>
     /// <param name="failoverRetryCount">Number of retries for failover attempts.</param>
+    /// <returns>A task that completes when the data connection definition has been stored or updated.</returns>
     public async Task StoreDataConnectionDefinitionAsync(
         string name, string protocol, string? configJson, string? backupConfigJson = null, int failoverRetryCount = 3)
     {
@@ -708,6 +739,7 @@ public class SiteStorageService
     /// <summary>
     /// Returns all stored data connection definitions.
     /// </summary>
+    /// <returns>A task that resolves to the list of all stored data connection definitions.</returns>
     public async Task<List<StoredDataConnectionDefinition>> GetAllDataConnectionDefinitionsAsync()
     {
         await using var connection = new SqliteConnection(_connectionString);

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Repositories/SyntheticId.cs

@@ -21,6 +21,7 @@ internal static class SyntheticId
     /// given name using the FNV-1a hash over its UTF-8 bytes.
     /// </summary>
     /// <param name="name">The string to hash into a synthetic integer ID.</param>
+    /// <returns>A deterministic positive 31-bit integer derived from the FNV-1a hash of the name.</returns>
     public static int From(string name)
     {
         var hash = FnvOffsetBasis;

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/ScopeAccessors.cs

@@ -39,6 +39,7 @@ public class AttributeAccessor
     /// Resolves a key to its full canonical name by applying the scope prefix.
     /// </summary>
     /// <param name="key">The attribute key to resolve.</param>
+    /// <returns>The fully qualified canonical name (e.g. "TempSensor.X" or "X" for the root scope).</returns>
     public string Resolve(string key) =>
         ScopePrefix.Length == 0 ? key : ScopePrefix + "." + key;
 
@@ -59,6 +60,7 @@ public class AttributeAccessor
     /// Gets an attribute value asynchronously.
     /// </summary>
     /// <param name="key">The attribute key.</param>
+    /// <returns>A task that resolves to the attribute value, or null if not set.</returns>
     public Task<object?> GetAsync(string key) => _ctx.GetAttribute(Resolve(key));
 
     /// <summary>
@@ -66,6 +68,7 @@ public class AttributeAccessor
     /// </summary>
     /// <param name="key">The attribute key.</param>
     /// <param name="value">The value to set.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public Task SetAsync(string key, object? value)
         => _ctx.SetAttribute(Resolve(key), value?.ToString() ?? string.Empty);
 }
@@ -102,6 +105,7 @@ public class CompositionAccessor
     /// Resolves a script name to its full canonical name by applying the composition path.
     /// </summary>
     /// <param name="scriptName">The script name to resolve.</param>
+    /// <returns>The fully qualified canonical script name (e.g. "Module.MyScript" or "MyScript" at root).</returns>
     public string ResolveScript(string scriptName) =>
         Path.Length == 0 ? scriptName : Path + "." + scriptName;
 
@@ -110,6 +114,7 @@ public class CompositionAccessor
     /// </summary>
     /// <param name="scriptName">The name of the script to call.</param>
     /// <param name="parameters">Optional parameters to pass to the script.</param>
+    /// <returns>A task that resolves to the script's return value, or null if none.</returns>
     public Task<object?> CallScript(string scriptName, object? parameters = null)
         => _ctx.CallScript(ResolveScript(scriptName), parameters);
 }
@@ -157,6 +162,7 @@ internal static class ScopeAccessorFactory
     /// </summary>
     /// <param name="ctx">The script runtime context.</param>
     /// <param name="selfPath">The canonical-name path.</param>
+    /// <returns>A new <see cref="AttributeAccessor"/> rooted at <paramref name="selfPath"/>.</returns>
     public static AttributeAccessor AttributesFor(ScriptRuntimeContext ctx, string selfPath)
         => new(ctx, selfPath);
 
@@ -165,6 +171,7 @@ internal static class ScopeAccessorFactory
     /// </summary>
     /// <param name="ctx">The script runtime context.</param>
     /// <param name="selfPath">The canonical-name path.</param>
+    /// <returns>A new <see cref="ChildrenAccessor"/> rooted at <paramref name="selfPath"/>.</returns>
     public static ChildrenAccessor ChildrenFor(ScriptRuntimeContext ctx, string selfPath)
         => new(ctx, selfPath);
 
@@ -173,6 +180,7 @@ internal static class ScopeAccessorFactory
     /// </summary>
     /// <param name="ctx">The script runtime context.</param>
     /// <param name="parentPath">The parent path, or null if no parent.</param>
+    /// <returns>A <see cref="CompositionAccessor"/> for the parent, or null when <paramref name="parentPath"/> is null.</returns>
     public static CompositionAccessor? ParentFor(ScriptRuntimeContext ctx, string? parentPath)
         => parentPath == null ? null : new CompositionAccessor(ctx, parentPath);
 }

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/ScriptCompilationService.cs

@@ -69,6 +69,7 @@ public class ScriptCompilationService
     /// Returns a list of violation messages, empty if clean.
     /// </summary>
     /// <param name="code">The script code to validate.</param>
+    /// <returns>A list of trust-model violation messages; empty if the script is clean.</returns>
     public IReadOnlyList<string> ValidateTrustModel(string code)
     {
         var tree = CSharpSyntaxTree.ParseText(
@@ -243,6 +244,7 @@ public class ScriptCompilationService
     /// </summary>
     /// <param name="scriptName">The name of the script.</param>
     /// <param name="code">The script code to compile.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> containing the compiled script on success, or error messages on failure.</returns>
     public ScriptCompilationResult Compile(string scriptName, string code)
         => CompileCore(scriptName, code, typeof(ScriptGlobals));
 
@@ -255,6 +257,7 @@ public class ScriptCompilationService
     /// </summary>
     /// <param name="name">The name of the trigger expression.</param>
     /// <param name="expression">The trigger expression to compile.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> containing the compiled expression on success, or error messages on failure.</returns>
     public ScriptCompilationResult CompileTriggerExpression(string name, string expression)
         => CompileCore(name, expression, typeof(TriggerExpressionGlobals));
 
@@ -327,11 +330,13 @@ public class ScriptCompilationResult
 
     /// <summary>Creates a successful compilation result.</summary>
     /// <param name="script">The compiled script.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> with <see cref="IsSuccess"/> set to <c>true</c> and the compiled script attached.</returns>
     public static ScriptCompilationResult Succeeded(Script<object?> script) =>
         new(true, script, []);
 
     /// <summary>Creates a failed compilation result.</summary>
     /// <param name="errors">List of error messages.</param>
+    /// <returns>A <see cref="ScriptCompilationResult"/> with <see cref="IsSuccess"/> set to <c>false</c> and the provided error messages.</returns>
     public static ScriptCompilationResult Failed(IReadOnlyList<string> errors) =>
         new(false, null, errors);
 }

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/ScriptExecutionScheduler.cs

@@ -31,6 +31,7 @@ public sealed class ScriptExecutionScheduler : TaskScheduler, IDisposable
     /// first caller wins, subsequent calls reuse the existing instance.
     /// </summary>
     /// <param name="options">Site runtime options supplying the thread count for the scheduler.</param>
+    /// <returns>The process-wide <see cref="ScriptExecutionScheduler"/> instance, creating it on first call.</returns>
     public static ScriptExecutionScheduler Shared(SiteRuntimeOptions options)
     {
         if (_shared != null)

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/ScriptRuntimeContext.cs

@@ -266,6 +266,7 @@ public class ScriptRuntimeContext
     /// </summary>
     /// <param name="attributeName">Name of the attribute to set.</param>
     /// <param name="value">String value to set for the attribute.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public async Task SetAttribute(string attributeName, string value)
     {
         var correlationId = Guid.NewGuid().ToString();

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/SharedScriptLibrary.cs

@@ -36,6 +36,7 @@ public class SharedScriptLibrary
     /// </summary>
     /// <param name="name">Unique name for the shared script.</param>
     /// <param name="code">C# source code of the shared script.</param>
+    /// <returns><c>true</c> if compilation succeeded and the script was registered; <c>false</c> if compilation failed.</returns>
     public bool CompileAndRegister(string name, string code)
     {
         var result = _compilationService.Compile(name, code);
@@ -60,6 +61,7 @@ public class SharedScriptLibrary
     /// Removes a shared script from the library.
     /// </summary>
     /// <param name="name">Name of the shared script to remove.</param>
+    /// <returns><c>true</c> if the script was found and removed; <c>false</c> if no script with that name was registered.</returns>
     public bool Remove(string name)
     {
         lock (_lock)
@@ -76,6 +78,7 @@ public class SharedScriptLibrary
     /// <param name="context">Runtime context providing instance state and services to the script globals.</param>
     /// <param name="parameters">Optional input parameters passed to the script.</param>
     /// <param name="cancellationToken">Cancellation token for the execution.</param>
+    /// <returns>A task that resolves to the script's return value, or <c>null</c> if the script returns nothing.</returns>
     public async Task<object?> ExecuteAsync(
         string scriptName,
         ScriptRuntimeContext context,
@@ -106,6 +109,7 @@ public class SharedScriptLibrary
     /// <summary>
     /// Returns the names of all currently registered shared scripts.
     /// </summary>
+    /// <returns>A snapshot list of all registered script names at the time of the call.</returns>
     public IReadOnlyList<string> GetRegisteredScriptNames()
     {
         lock (_lock)
@@ -118,6 +122,7 @@ public class SharedScriptLibrary
     /// Returns whether a script with the given name is registered.
     /// </summary>
     /// <param name="name">Name of the shared script to look up.</param>
+    /// <returns><c>true</c> if a script with the given name is registered; otherwise <c>false</c>.</returns>
     public bool Contains(string name)
     {
         lock (_lock)

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Scripts/TriggerExpressionGlobals.cs

@@ -20,6 +20,7 @@ public sealed class TriggerExpressionGlobals
     /// and AlarmActor.
     /// </summary>
     /// <param name="triggerConfigJson">JSON string of the trigger configuration, or null.</param>
+    /// <returns>The expression string, or <c>null</c> if the config is missing, blank, or malformed.</returns>
     public static string? ExtractExpression(string? triggerConfigJson)
     {
         if (string.IsNullOrEmpty(triggerConfigJson)) return null;

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/ServiceCollectionExtensions.cs

@@ -18,6 +18,7 @@ public static class ServiceCollectionExtensions
     /// overload with an explicit connection string.
     /// </summary>
     /// <param name="services">The DI service collection to register services into.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> to allow chaining.</returns>
     public static IServiceCollection AddSiteRuntime(this IServiceCollection services)
     {
         // SiteStorageService is registered by the Host using AddSiteRuntime(connectionString)
@@ -30,6 +31,7 @@ public static class ServiceCollectionExtensions
     /// </summary>
     /// <param name="services">The DI service collection to register services into.</param>
     /// <param name="siteDbConnectionString">The SQLite connection string for the site local storage database.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> to allow chaining.</returns>
     public static IServiceCollection AddSiteRuntime(this IServiceCollection services, string siteDbConnectionString)
     {
         services.AddSingleton(sp =>
@@ -66,6 +68,7 @@ public static class ServiceCollectionExtensions
 
     /// <summary>Registers any additional DI services needed by the Site Runtime Akka actors.</summary>
     /// <param name="services">The DI service collection to register services into.</param>
+    /// <returns>The same <see cref="IServiceCollection"/> to allow chaining.</returns>
     public static IServiceCollection AddSiteRuntimeActors(this IServiceCollection services)
     {
         // Actor registration is handled by AkkaHostedService.RegisterSiteActors()

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Tracking/OperationTrackingStore.cs

@@ -400,6 +400,7 @@ public class OperationTrackingStore : IOperationTrackingStore, IAsyncDisposable,
     /// connection, so a write currently executing a SqliteCommand completes
     /// before the connection is freed.
     /// </summary>
+    /// <returns>A <see cref="ValueTask"/> that completes when all resources have been released.</returns>
     public async ValueTask DisposeAsync()
     {
         if (Interlocked.Exchange(ref _disposeState, 1) != 0)