Refine governance execution runtime

Author: rian-be

src/Governance/Runtime/Execution/Mutation/GovernedMutation.cs

@@ -2,6 +2,7 @@
 using ModularityKit.Mutator.Abstractions.Engine;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Results;
+using ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Compensation;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Model;
 
 namespace ModularityKit.Mutator.Governance.Runtime.Execution.Mutation;
@@ -15,6 +16,8 @@ internal sealed class GovernedMutation<TState> : IMutation<TState>
     private const string GovernanceRequestMetadataKey = "GovernanceRequestMetadata";
     private const string GovernanceIntentMetadataKey = "GovernanceIntentMetadata";
     private const string GovernanceEstimatedBlastRadiusMetadataKey = "GovernanceEstimatedBlastRadius";
+    private const string GovernanceExecutionKindMetadataKey = "GovernanceExecutionKind";
+    private const string GovernanceCompensationMetadataKey = "GovernanceCompensation";
 
     private readonly IMutation<TState> _inner;
 
@@ -58,7 +61,8 @@ private IReadOnlyDictionary<string, object> MergeContextMetadata(MutationRequest
     {
         var metadata = new Dictionary<string, object>(_inner.Context.Metadata)
         {
-            [GovernanceRequestIdMetadataKey] = request.RequestId
+            [GovernanceRequestIdMetadataKey] = request.RequestId,
+            [GovernanceExecutionKindMetadataKey] = request.Execution.Kind.ToString()
         };
 
         if (request.Metadata.Count > 0)
@@ -70,19 +74,48 @@ private IReadOnlyDictionary<string, object> MergeContextMetadata(MutationRequest
         if (request.Intent.EstimatedBlastRadius is not null)
             metadata[GovernanceEstimatedBlastRadiusMetadataKey] = request.Intent.EstimatedBlastRadius;
 
+        if (request.Execution.Compensation is not null)
+            metadata[GovernanceCompensationMetadataKey] = CreateCompensationMetadata(request.Execution.Compensation);
+
         return metadata;
     }
 
     private IReadOnlyDictionary<string, object> MergeIntentMetadata(MutationRequest request)
     {
         var metadata = new Dictionary<string, object>(request.Intent.Metadata)
         {
-            [GovernanceRequestIdMetadataKey] = request.RequestId
+            [GovernanceRequestIdMetadataKey] = request.RequestId,
+            [GovernanceExecutionKindMetadataKey] = request.Execution.Kind.ToString()
         };
 
         if (_inner.Intent.Metadata.Count > 0)
             metadata["ExecutionIntentMetadata"] = _inner.Intent.Metadata;
 
+        if (request.Execution.Compensation is not null)
+            metadata[GovernanceCompensationMetadataKey] = CreateCompensationMetadata(request.Execution.Compensation);
+
+        return metadata;
+    }
+
+    private static IReadOnlyDictionary<string, object> CreateCompensationMetadata(
+        GovernedCompensationPlan compensation)
+    {
+        var metadata = new Dictionary<string, object>
+        {
+            ["OriginalRequestId"] = compensation.OriginalRequestId,
+            ["Kind"] = compensation.Kind.ToString(),
+            ["Trigger"] = compensation.Trigger.ToString()
+        };
+
+        if (!string.IsNullOrWhiteSpace(compensation.BatchId))
+            metadata["BatchId"] = compensation.BatchId;
+
+        if (compensation.RelatedRequestIds.Count > 0)
+            metadata["RelatedRequestIds"] = compensation.RelatedRequestIds;
+
+        if (!string.IsNullOrWhiteSpace(compensation.Reason))
+            metadata["Reason"] = compensation.Reason;
+
         return metadata;
     }
 

src/Governance/Runtime/Execution/Orchestration/GovernanceExecutionManager.cs

@@ -3,6 +3,9 @@
 using ModularityKit.Mutator.Abstractions.Results;
 using ModularityKit.Mutator.Governance.Abstractions.Execution.Contracts;
 using ModularityKit.Mutator.Governance.Abstractions.Execution.Model;
+using ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Links;
+using ModularityKit.Mutator.Governance.Abstractions.Exceptions.Storage;
+using ModularityKit.Mutator.Governance.Abstractions.Requests.Model;
 using ModularityKit.Mutator.Governance.Abstractions.Resolution.Contracts;
 using ModularityKit.Mutator.Governance.Abstractions.Resolution.Model;
 using ModularityKit.Mutator.Governance.Abstractions.Resolution.Strategies;
@@ -21,11 +24,25 @@ public sealed class GovernanceExecutionManager(
     IMutationRequestVersionResolutionManager resolutionManager,
     IMutationEngine mutationEngine) : IGovernanceExecutionManager
 {
+    private readonly IMutationRequestStore _requestStore = requestStore ?? throw new ArgumentNullException(nameof(requestStore));
     private readonly IMutationRequestVersionResolutionManager _resolutionManager = resolutionManager ?? throw new ArgumentNullException(nameof(resolutionManager));
     private readonly IMutationEngine _mutationEngine = mutationEngine ?? throw new ArgumentNullException(nameof(mutationEngine));
     private readonly GovernedExecutionOutcomeHandler _outcomeHandler =
         new(new GovernedExecutionRequestPersistence(requestStore ?? throw new ArgumentNullException(nameof(requestStore))));
 
+    /// <summary>
+    /// Executes approved governed mutation request against provided state snapshot.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the governed mutation.</typeparam>
+    /// <param name="requestId">Stable identifier of the governed mutation request.</param>
+    /// <param name="mutation">Mutation instance to execute after governance resolution succeeds.</param>
+    /// <param name="currentState">Current state snapshot used for execution.</param>
+    /// <param name="currentStateVersion">Current version or concurrency token of the state snapshot.</param>
+    /// <param name="resultingStateVersionProvider">Delegate that resolves the resulting state version from the post-mutation state.</param>
+    /// <param name="governanceContext">Context describing the governance actor or service performing execution.</param>
+    /// <param name="strategy">Version-resolution strategy applied before execution.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The governed execution result, including persisted request state and optional mutation outcome.</returns>
     public async Task<GovernedExecutionResult<TState>> ExecuteApproved<TState>(
         string requestId,
         IMutation<TState> mutation,
@@ -74,11 +91,27 @@ public async Task<GovernedExecutionResult<TState>> ExecuteApproved<TState>(
             throw;
         }
 
-        return await _outcomeHandler
+        var result = await _outcomeHandler
             .HandleMutationResult(execution, mutationResult, cancellationToken)
             .ConfigureAwait(false);
+
+        if (result.WasExecuted)
+            await LinkCompensationExecution(result.Request, governanceContext, cancellationToken).ConfigureAwait(false);
+
+        return result;
     }
 
+    /// <summary>
+    /// Executes approved governed mutation request against versioned state snapshot.
+    /// </summary>
+    /// <typeparam name="TState">The versioned state type handled by the governed mutation.</typeparam>
+    /// <param name="requestId">Stable identifier of the governed mutation request.</param>
+    /// <param name="mutation">Mutation instance to execute after governance resolution succeeds.</param>
+    /// <param name="currentState">Current versioned state snapshot used for execution.</param>
+    /// <param name="governanceContext">Context describing the governance actor or service performing execution.</param>
+    /// <param name="strategy">Version-resolution strategy applied before execution.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The governed execution result, including persisted request state and optional mutation outcome.</returns>
     public Task<GovernedExecutionResult<TState>> ExecuteApproved<TState>(
         string requestId,
         IMutation<TState> mutation,
@@ -97,6 +130,19 @@ public Task<GovernedExecutionResult<TState>> ExecuteApproved<TState>(
             strategy,
             cancellationToken);
 
+    /// <summary>
+    /// Resolves the governed request and builds execution context for the core mutation engine.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the governed mutation.</typeparam>
+    /// <param name="requestId">Stable identifier of the governed mutation request.</param>
+    /// <param name="mutation">Mutation instance to wrap for governed execution.</param>
+    /// <param name="currentState">Current state snapshot used for execution.</param>
+    /// <param name="currentStateVersion">Current version or concurrency token of the state snapshot.</param>
+    /// <param name="resultingStateVersionProvider">Delegate that resolves the resulting state version from the post-mutation state.</param>
+    /// <param name="governanceContext">Context describing the governance actor or service performing execution.</param>
+    /// <param name="strategy">Version-resolution strategy applied before execution.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Resolved execution context passed to the core mutation engine.</returns>
     private async Task<GovernedExecutionContext<TState>> ResolveExecutionContext<TState>(
         string requestId,
         IMutation<TState> mutation,
@@ -123,11 +169,80 @@ private async Task<GovernedExecutionContext<TState>> ResolveExecutionContext<TSt
             governanceContext);
     }
 
+    /// <summary>
+    /// Executes the wrapped governed mutation through the core mutation engine.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the governed mutation.</typeparam>
+    /// <param name="execution">Resolved governed execution context.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The core mutation result.</returns>
     private Task<MutationResult<TState>> ExecuteMutation<TState>(
         GovernedExecutionContext<TState> execution,
         CancellationToken cancellationToken)
         => _mutationEngine.ExecuteAsync(
             execution.Mutation,
             execution.CurrentState,
             cancellationToken);
+
+    /// <summary>
+    /// Links successful compensating execution back to the original governed request.
+    /// </summary>
+    /// <param name="executedRequest">Persisted compensating request after successful execution.</param>
+    /// <param name="governanceContext">Context describing the governance actor or service recording the compensation link.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    private async Task LinkCompensationExecution(
+        MutationRequest executedRequest,
+        MutationContext governanceContext,
+        CancellationToken cancellationToken)
+    {
+        if (executedRequest.Execution.Kind != GovernedExecutionKind.Compensation || executedRequest.Execution.Compensation is null)
+            return;
+
+        executedRequest.Execution.Compensation.EnsureValid();
+
+        var originalRequest = await _requestStore
+            .Get(executedRequest.Execution.Compensation.OriginalRequestId, cancellationToken)
+            .ConfigureAwait(false)
+                ?? throw new MutationRequestNotFoundException(executedRequest.Execution.Compensation.OriginalRequestId);
+
+        if (originalRequest.Execution.RelatedExecutions.Any(link => link.RequestId == executedRequest.RequestId &&
+        link.Type == GovernedExecutionLinkType.CompensatedBy))
+            return;
+
+        var linkedAt = executedRequest.Versioning.ExecutedAt ?? DateTimeOffset.UtcNow;
+        var decision = GovernedExecutionDecisionFactory.CreateCompensatedDecision(
+            governanceContext,
+            executedRequest.RequestId,
+            executedRequest.Execution.Compensation,
+            executedRequest.Versioning.ResultingStateVersion ?? string.Empty,
+            linkedAt);
+
+        var updatedOriginalRequest = originalRequest with
+        {
+            UpdatedAt = linkedAt,
+            Execution = originalRequest.Execution with
+            {
+                RelatedExecutions =
+                [
+                    .. originalRequest.Execution.RelatedExecutions,
+                    new GovernedExecutionLink
+                    {
+                        RequestId = executedRequest.RequestId,
+                        Type = GovernedExecutionLinkType.CompensatedBy,
+                        ExecutionKind = GovernedExecutionKind.Compensation,
+                        CompensationKind = executedRequest.Execution.Compensation.Kind,
+                        Trigger = executedRequest.Execution.Compensation.Trigger,
+                        BatchId = executedRequest.Execution.Compensation.BatchId,
+                        LinkedAt = linkedAt
+                    }
+                ]
+            },
+            Decisions = [.. originalRequest.Decisions, decision]
+        };
+
+        var persistedRequest = await _requestStore
+            .TryStore(updatedOriginalRequest, originalRequest.Revision, cancellationToken)
+            .ConfigureAwait(false)
+                ?? throw new MutationRequestConcurrencyException(originalRequest.RequestId, originalRequest.Revision);
+    }
 }