fix: .NET bug sweep — thread safety, error surfacing, caching, disposal (#252)

- AuditEmitter: surface handler exceptions via HandlerError callback
  instead of silently swallowing (#147)
- SagaOrchestrator: add per-saga lock (SyncRoot) guarding all state
  mutations during execution and compensation (#145)
- GovernanceMiddleware: cache FindMatchingRule lookups in a dictionary
  keyed by rule name, invalidated on policy count change (#148)
- GovernanceKernel: implement IDisposable to clean up Metrics (#150)
- AgentIdentity: throw InvalidOperationException instead of returning
  silent false when private key is missing for HMAC verify (#141)
- FileTrustStore: preserve corrupted file as .corrupt backup and
  surface error via loadErrorHandler callback (#152)

Closes #141, closes #145, closes #147, closes #148, closes #150, closes #152

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: imran-siddique

packages/agent-governance-dotnet/src/AgentGovernance/Audit/AuditEmitter.cs

@@ -21,6 +21,12 @@ public sealed class AuditEmitter
     /// </summary>
     private readonly ConcurrentBag<Action<GovernanceEvent>> _wildcardHandlers = new();
 
+    /// <summary>
+    /// Optional callback invoked when a handler throws an exception.
+    /// Allows callers to log or monitor handler failures without disrupting other subscribers.
+    /// </summary>
+    public Action<Exception, GovernanceEvent>? HandlerError { get; init; }
+
     /// <summary>
     /// Subscribes a handler to a specific governance event type.
     /// </summary>
@@ -116,19 +122,19 @@ public int HandlerCount(GovernanceEventType type)
     public int WildcardHandlerCount => _wildcardHandlers.Count;
 
     /// <summary>
-    /// Safely invokes a handler, catching and swallowing any exceptions
-    /// to prevent one faulty handler from disrupting other subscribers.
+    /// Safely invokes a handler, catching exceptions to prevent one faulty
+    /// handler from disrupting other subscribers. Exceptions are surfaced
+    /// through the <see cref="HandlerError"/> callback when configured.
     /// </summary>
-    private static void InvokeSafe(Action<GovernanceEvent> handler, GovernanceEvent governanceEvent)
+    private void InvokeSafe(Action<GovernanceEvent> handler, GovernanceEvent governanceEvent)
     {
         try
         {
             handler(governanceEvent);
         }
-        catch
+        catch (Exception ex)
         {
-            // Swallow handler exceptions to maintain event bus stability.
-            // In production, consider logging handler errors.
+            HandlerError?.Invoke(ex, governanceEvent);
         }
     }
 }

packages/agent-governance-dotnet/src/AgentGovernance/GovernanceKernel.cs

@@ -102,7 +102,7 @@ public sealed class GovernanceOptions
 /// }
 /// </code>
 /// </remarks>
-public sealed class GovernanceKernel
+public sealed class GovernanceKernel : IDisposable
 {
     /// <summary>
     /// The policy evaluation engine used by this kernel.
@@ -261,4 +261,14 @@ public void OnAllEvents(Action<GovernanceEvent> handler)
     {
         AuditEmitter.OnAll(handler);
     }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        if (_disposed) return;
+        _disposed = true;
+        (Metrics as IDisposable)?.Dispose();
+    }
+
+    private bool _disposed;
 }

packages/agent-governance-dotnet/src/AgentGovernance/Hypervisor/SagaOrchestrator.cs

@@ -75,6 +75,11 @@ public sealed class Saga
     public List<SagaStep> Steps { get; } = new();
     public List<string> FailedCompensations { get; } = new();
     public DateTime CreatedUtc { get; } = DateTime.UtcNow;
+
+    /// <summary>
+    /// Per-saga lock for synchronizing state mutations during execution and compensation.
+    /// </summary>
+    internal object SyncRoot { get; } = new();
 }
 
 /// <summary>
@@ -122,19 +127,19 @@ public void AddStep(Saga saga, SagaStep step)
     public async Task<bool> ExecuteAsync(Saga saga, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(saga);
-        saga.State = SagaState.Executing;
+        lock (saga.SyncRoot) { saga.State = SagaState.Executing; }
 
         foreach (var step in saga.Steps)
         {
-            var success = await ExecuteStepAsync(step, cancellationToken).ConfigureAwait(false);
+            var success = await ExecuteStepAsync(saga, step, cancellationToken).ConfigureAwait(false);
             if (!success)
             {
                 await CompensateAsync(saga, cancellationToken).ConfigureAwait(false);
                 return false;
             }
         }
 
-        saga.State = SagaState.Committed;
+        lock (saga.SyncRoot) { saga.State = SagaState.Committed; }
         return true;
     }
 
@@ -149,58 +154,58 @@ public async Task<bool> ExecuteAsync(Saga saga, CancellationToken cancellationTo
         }
     }
 
-    private async Task<bool> ExecuteStepAsync(SagaStep step, CancellationToken cancellationToken)
+    private async Task<bool> ExecuteStepAsync(Saga saga, SagaStep step, CancellationToken cancellationToken)
     {
         for (int attempt = 0; attempt < step.MaxRetries; attempt++)
         {
-            step.State = StepState.Executing;
-            step.Error = null;
+            lock (saga.SyncRoot) { step.State = StepState.Executing; step.Error = null; }
 
             try
             {
                 using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
                 cts.CancelAfter(step.Timeout);
 
-                step.Result = await step.Execute(cts.Token).ConfigureAwait(false);
-                step.State = StepState.Committed;
+                var result = await step.Execute(cts.Token).ConfigureAwait(false);
+                lock (saga.SyncRoot) { step.Result = result; step.State = StepState.Committed; }
                 return true;
             }
             catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
             {
-                step.Error = $"Step '{step.ActionId}' timed out after {step.Timeout.TotalSeconds}s.";
+                lock (saga.SyncRoot) { step.Error = $"Step '{step.ActionId}' timed out after {step.Timeout.TotalSeconds}s."; }
             }
             catch (Exception ex)
             {
-                step.Error = $"Step '{step.ActionId}' failed: {ex.Message}";
+                lock (saga.SyncRoot) { step.Error = $"Step '{step.ActionId}' failed: {ex.Message}"; }
             }
 
-            // Exponential backoff before retry.
             if (attempt + 1 < step.MaxRetries)
             {
                 var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt));
                 await Task.Delay(delay, cancellationToken).ConfigureAwait(false);
             }
         }
 
-        step.State = StepState.Failed;
+        lock (saga.SyncRoot) { step.State = StepState.Failed; }
         return false;
     }
 
     private async Task CompensateAsync(Saga saga, CancellationToken cancellationToken)
     {
-        saga.State = SagaState.Compensating;
-
-        // Compensate in reverse order of committed steps.
-        var committedSteps = saga.Steps
-            .Where(s => s.State == StepState.Committed)
-            .Reverse()
-            .ToList();
+        List<SagaStep> committedSteps;
+        lock (saga.SyncRoot)
+        {
+            saga.State = SagaState.Compensating;
+            committedSteps = saga.Steps
+                .Where(s => s.State == StepState.Committed)
+                .Reverse()
+                .ToList();
+        }
 
         foreach (var step in committedSteps)
         {
             if (step.Compensate is null)
             {
-                step.State = StepState.Compensated;
+                lock (saga.SyncRoot) { step.State = StepState.Compensated; }
                 continue;
             }
 
@@ -210,18 +215,24 @@ private async Task CompensateAsync(Saga saga, CancellationToken cancellationToke
                 cts.CancelAfter(step.Timeout);
 
                 await step.Compensate(cts.Token).ConfigureAwait(false);
-                step.State = StepState.Compensated;
+                lock (saga.SyncRoot) { step.State = StepState.Compensated; }
             }
             catch (Exception ex)
             {
-                step.State = StepState.CompensationFailed;
-                step.Error = $"Compensation for '{step.ActionId}' failed: {ex.Message}";
-                saga.FailedCompensations.Add(step.ActionId);
+                lock (saga.SyncRoot)
+                {
+                    step.State = StepState.CompensationFailed;
+                    step.Error = $"Compensation for '{step.ActionId}' failed: {ex.Message}";
+                    saga.FailedCompensations.Add(step.ActionId);
+                }
             }
         }
 
-        saga.State = saga.FailedCompensations.Count > 0
-            ? SagaState.Escalated
-            : SagaState.Aborted;
+        lock (saga.SyncRoot)
+        {
+            saga.State = saga.FailedCompensations.Count > 0
+                ? SagaState.Escalated
+                : SagaState.Aborted;
+        }
     }
 }

packages/agent-governance-dotnet/src/AgentGovernance/Integration/GovernanceMiddleware.cs

@@ -58,6 +58,8 @@ public sealed class GovernanceMiddleware
 {
     private readonly PolicyEngine _policyEngine;
     private readonly AuditEmitter _auditEmitter;
+    private Dictionary<string, PolicyRule>? _ruleLookupCache;
+    private int _cachedPolicyCount = -1;
     private readonly RateLimiter? _rateLimiter;
     private readonly GovernanceMetrics? _metrics;
     private readonly RingEnforcer? _ringEnforcer;
@@ -296,18 +298,28 @@ private static Dictionary<string, object> BuildContext(
     }
 
     /// <summary>
-    /// Searches loaded policies for a rule by name.
+    /// Searches loaded policies for a rule by name using a cached lookup.
+    /// Cache is invalidated when the policy count changes.
     /// </summary>
     private PolicyRule? FindMatchingRule(string ruleName)
     {
-        foreach (var policy in _policyEngine.ListPolicies())
+        var policies = _policyEngine.ListPolicies();
+        var currentCount = policies.Count;
+
+        if (_ruleLookupCache is null || _cachedPolicyCount != currentCount)
         {
-            foreach (var rule in policy.Rules)
+            var cache = new Dictionary<string, PolicyRule>(StringComparer.Ordinal);
+            foreach (var policy in policies)
             {
-                if (string.Equals(rule.Name, ruleName, StringComparison.Ordinal))
-                    return rule;
+                foreach (var rule in policy.Rules)
+                {
+                    cache.TryAdd(rule.Name, rule);
+                }
             }
+            _ruleLookupCache = cache;
+            _cachedPolicyCount = currentCount;
         }
-        return null;
+
+        return _ruleLookupCache.TryGetValue(ruleName, out var cached) ? cached : null;
     }
 }

packages/agent-governance-dotnet/src/AgentGovernance/Trust/AgentIdentity.cs

@@ -121,44 +121,48 @@ public byte[] Sign(string message)
     }
 
     /// <summary>
-    /// Verifies a signature against data using this identity's public key.
+    /// Verifies a signature against data using this identity's key material.
     /// </summary>
     /// <param name="data">The data that was signed.</param>
     /// <param name="signature">The signature to verify.</param>
     /// <returns><c>true</c> if the signature is valid; otherwise <c>false</c>.</returns>
-    /// <remarks>
-    /// In the HMAC-SHA256 fallback, verification requires the private key to
-    /// recompute the HMAC. This is a known limitation; with Ed25519, verification
-    /// uses only the public key.
-    /// </remarks>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when this identity does not have a private key. HMAC-SHA256
+    /// verification requires the signing key. For public-key verification,
+    /// migrate to Ed25519 on .NET 9+.
+    /// </exception>
     public bool Verify(byte[] data, byte[] signature)
     {
         ArgumentNullException.ThrowIfNull(data);
         ArgumentNullException.ThrowIfNull(signature);
 
         if (PrivateKey is null)
         {
-            // Without Ed25519, we cannot verify with only the public key.
-            // In production with .NET 9+, use Ed25519 public-key verification.
-            return false;
+            throw new InvalidOperationException(
+                "Cannot verify signature: HMAC-SHA256 requires the private key. " +
+                "For cross-agent verification with only a public key, migrate to Ed25519 (.NET 9+).");
         }
 
         var expected = Sign(data);
         return CryptographicOperations.FixedTimeEquals(expected, signature);
     }
 
     /// <summary>
-    /// Verifies a signature using a standalone public key and private key pair.
+    /// Verifies a signature using a standalone key pair.
     /// This static overload is provided for cross-agent verification scenarios.
     /// </summary>
-    /// <param name="publicKey">The public key of the signer.</param>
+    /// <param name="publicKey">The public key of the signer (unused in HMAC mode; reserved for Ed25519).</param>
     /// <param name="data">The signed data.</param>
     /// <param name="signature">The signature to verify.</param>
     /// <param name="privateKey">
-    /// The private key for HMAC recomputation (required for HMAC-SHA256 fallback;
-    /// not needed with Ed25519 on .NET 9+).
+    /// The private key for HMAC recomputation. Required for HMAC-SHA256;
+    /// will not be needed with Ed25519 on .NET 9+.
     /// </param>
     /// <returns><c>true</c> if the signature is valid; otherwise <c>false</c>.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when <paramref name="privateKey"/> is <c>null</c> because HMAC-SHA256
+    /// cannot verify without the signing key.
+    /// </exception>
     public static bool VerifySignature(byte[] publicKey, byte[] data, byte[] signature, byte[]? privateKey = null)
     {
         ArgumentNullException.ThrowIfNull(publicKey);
@@ -167,9 +171,9 @@ public static bool VerifySignature(byte[] publicKey, byte[] data, byte[] signatu
 
         if (privateKey is null)
         {
-            // Cannot verify without private key in HMAC-SHA256 mode.
-            // With Ed25519 (.NET 9+), this would use the public key directly.
-            return false;
+            throw new InvalidOperationException(
+                "Cannot verify signature: HMAC-SHA256 requires the private key. " +
+                "For public-key-only verification, migrate to Ed25519 (.NET 9+).");
         }
 
         using var hmac = new HMACSHA256(privateKey);

packages/agent-governance-dotnet/src/AgentGovernance/Trust/FileTrustStore.cs

@@ -16,6 +16,7 @@ public sealed class FileTrustStore : IDisposable
     private readonly object _ioLock = new();
     private readonly double _defaultScore;
     private readonly double _decayRate;
+    private readonly Action<Exception, string>? _loadErrorHandler;
     private bool _disposed;
 
     private static readonly JsonSerializerOptions JsonOptions = new()
@@ -34,12 +35,17 @@ public sealed class FileTrustStore : IDisposable
     /// Trust decay rate per hour of inactivity (0–1000). Defaults to 10.
     /// Agents that have not had positive signals lose trust over time.
     /// </param>
-    public FileTrustStore(string filePath, double defaultScore = 500.0, double decayRate = 10.0)
+    /// <param name="loadErrorHandler">
+    /// Optional callback invoked when the trust store file is corrupted.
+    /// Receives the exception and file path. When null, corruption is handled silently.
+    /// </param>
+    public FileTrustStore(string filePath, double defaultScore = 500.0, double decayRate = 10.0, Action<Exception, string>? loadErrorHandler = null)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(filePath);
         _filePath = filePath;
         _defaultScore = Math.Clamp(defaultScore, 0, 1000);
         _decayRate = Math.Max(0, decayRate);
+        _loadErrorHandler = loadErrorHandler;
 
         Load();
     }
@@ -179,9 +185,20 @@ private void Load()
                     }
                 }
             }
-            catch (JsonException)
+            catch (JsonException ex)
             {
-                // Corrupted file — start fresh.
+                // Preserve corrupted file for forensics.
+                try
+                {
+                    var corruptPath = _filePath + ".corrupt";
+                    File.Copy(_filePath, corruptPath, overwrite: true);
+                }
+                catch
+                {
+                    // Best-effort backup; ignore if it fails.
+                }
+
+                _loadErrorHandler?.Invoke(ex, _filePath);
             }
         }
     }