Feat: Clarify governance revalidation semantics

Author: rian-be

Examples/Governance/VersionedResolution/README.md

@@ -12,6 +12,7 @@ It is the direct runnable example for the semantics introduced around `ExpectedS
 - resolving stale requests with `RevalidateOnLatestState`
 - persisting a resolved outcome through `MutationRequestVersionResolutionManager`
 - inspecting the resulting lifecycle state and appended decision history
+- observing that revalidation is represented as `Pending` with `PendingMutationReason.Revalidation`
 
 ## Key files
 
@@ -67,6 +68,7 @@ The sample prints one block per resolution strategy and one persisted-resolution
 - selected outcome
 - whether the request was stale
 - resulting request status
+- the revalidation pending reason when the latest-state branch is selected
 - updated expected version
 - last decision recorded during resolution
 - persisted request revision for the runtime path

Tests/ModularityKit.Mutator.Governance.Tests/Execution/GovernanceExecutionManagerTests.cs

@@ -143,6 +143,48 @@ public async Task ExecuteApproved_requires_renewed_approval_before_execution_whe
         Assert.Equal(MutationRequestVersionResolutionOutcome.RequiresRenewedApproval, result.Resolution.Outcome);
     }
 
+    [Fact]
+    public async Task ExecuteApproved_revalidates_and_executes_against_latest_state_when_strategy_demands_it()
+    {
+        var services = new ServiceCollection();
+        services.AddMutators(MutationEngineOptions.Strict);
+        await using var provider = services.BuildServiceProvider();
+
+        var engine = provider.GetRequiredService<IMutationEngine>();
+        var requestStore = new InMemoryMutationRequestStore();
+        var resolutionManager = new MutationRequestVersionResolutionManager(requestStore, new MutationRequestVersionResolver());
+        var executionManager = new GovernanceExecutionManager(requestStore, resolutionManager, engine);
+
+        var request = await requestStore.Create(MutationRequestTestFactory.CreateApprovedSecurityRequest("v10"));
+        var mutation = new PromoteRoleMutation(
+            MutationContext.User("operator-1", "Operator One", "Execute approved role promotion"),
+            nextVersion: "v16");
+        var state = RoleState.Create("tenant-42:roles", role: "Reader", version: "v15");
+
+        var result = await executionManager.ExecuteApproved(
+            request.RequestId,
+            mutation,
+            state,
+            currentStateVersion: state.Version,
+            resultingStateVersionProvider: updated => updated.Version,
+            governanceContext: MutationContext.Service("governance-runtime", "Revalidate and execute"),
+            strategy: VersionedRequestResolutionStrategy.RevalidateOnLatestState);
+
+        Assert.True(result.WasExecuted);
+        Assert.NotNull(result.MutationResult);
+        Assert.Equal(MutationRequestVersionResolutionOutcome.RevalidateOnLatestState, result.Resolution.Outcome);
+        Assert.Equal(MutationRequestStatus.Executed, result.Request.Status);
+        Assert.Equal("v16", result.ResultingStateVersion);
+        Assert.Equal("v16", result.Request.ResultingStateVersion);
+        Assert.Equal("v16", result.Request.ExpectedStateVersion);
+        Assert.Equal(
+            MutationRequestDecisionType.Lifecycle(MutationRequestLifecycleDecisionType.Executed),
+            result.Request.Decisions[^1].Type);
+        Assert.Contains(
+            result.Request.Decisions,
+            decision => decision.Type == MutationRequestDecisionType.VersionResolution(MutationRequestVersionResolutionDecisionType.RevalidationRequired));
+    }
+
     private sealed record RoleState(string StateId, string Role, string Version)
     {
         public static RoleState Create(string stateId, string role, string version) => new(stateId, role, version);

Tests/ModularityKit.Mutator.Governance.Tests/Resolution/MutationRequestVersionResolutionPersistenceTests.cs

@@ -3,6 +3,7 @@
 using ModularityKit.Mutator.Governance.Abstractions.Lifecycle.Model;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Decisions;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Model;
+using ModularityKit.Mutator.Governance.Abstractions.Resolution.Model;
 using ModularityKit.Mutator.Governance.Abstractions.Resolution.Strategies;
 using ModularityKit.Mutator.Governance.Runtime.Resolution.Execution;
 using ModularityKit.Mutator.Governance.Runtime.Storage;
@@ -63,6 +64,35 @@ public async Task ResolveAndStore_persists_decision_history_and_state()
         Assert.Equal(loaded, resolution.Request);
     }
 
+    [Fact]
+    public async Task ResolveAndStore_revalidation_marks_request_pending_for_revalidation()
+    {
+        var store = new InMemoryMutationRequestStore();
+        var resolver = new MutationRequestVersionResolver();
+        var manager = new MutationRequestVersionResolutionManager(store, resolver);
+        var request = await store.Create(MutationRequestTestFactory.CreateApprovedSecurityRequest("v10"));
+
+        var resolution = await manager.ResolveAndStore(
+            request.RequestId,
+            currentStateVersion: "v15",
+            resolutionContext: MutationContext.User("approver", "Approver", "Revalidate request"),
+            strategy: VersionedRequestResolutionStrategy.RevalidateOnLatestState);
+
+        var loaded = await store.Get(request.RequestId);
+
+        Assert.NotNull(loaded);
+        Assert.Equal(3, loaded.Decisions.Count);
+        Assert.Equal(
+            MutationRequestDecisionType.VersionResolution(MutationRequestVersionResolutionDecisionType.RevalidationRequired),
+            loaded.Decisions[^1].Type);
+        Assert.Equal(MutationRequestStatus.Pending, loaded.Status);
+        Assert.Equal(PendingMutationReason.Revalidation, loaded.PendingReason);
+        Assert.Equal("v15", loaded.ExpectedStateVersion);
+        Assert.Equal(1, loaded.Revision);
+        Assert.Equal(MutationRequestVersionResolutionOutcome.RevalidateOnLatestState, resolution.Outcome);
+        Assert.Equal(loaded, resolution.Request);
+    }
+
     [Fact]
     public async Task ResolveAndStore_throws_not_found_for_missing_request()
     {

src/Governance/Abstractions/Lifecycle/Model/PendingMutationReason.cs

@@ -5,10 +5,34 @@ namespace ModularityKit.Mutator.Governance.Abstractions.Lifecycle.Model;
 /// </summary>
 public enum PendingMutationReason
 {
+    /// <summary>
+    /// The request is waiting for approval.
+    /// </summary>
     Approval = 0,
+
+    /// <summary>
+    /// The request is waiting for an external check or integration response.
+    /// </summary>
     ExternalCheck = 1,
+
+    /// <summary>
+    /// The request is waiting for a scheduled execution window.
+    /// </summary>
     Schedule = 2,
+
+    /// <summary>
+    /// The request is waiting for a dependency to become ready.
+    /// </summary>
     Dependency = 3,
+
+    /// <summary>
+    /// The request is waiting because of quota constraints.
+    /// </summary>
     Quota = 4,
-    ManualReview = 5
+
+    /// <summary>
+    /// The request is waiting for manual review.
+    /// </summary>
+    ManualReview = 5,
+    Revalidation = 6
 }

src/Governance/Runtime/Resolution/Execution/MutationRequestVersionResolutionState.cs

@@ -71,8 +71,8 @@ public static MutationRequest ApplyRevalidationRequired(
         return AppendDecision(
             request with
             {
-                Status = MutationRequestStatus.Approved,
-                PendingReason = null,
+                Status = MutationRequestStatus.Pending,
+                PendingReason = PendingMutationReason.Revalidation,
                 ExpectedStateVersion = currentStateVersion,
                 UpdatedAt = decision.Timestamp
             },