Feat: Add governed execution abstraction models

Author: rian-be

src/Governance/Abstractions/Execution/Model/Compensation/GovernedCompensationKind.cs

@@ -0,0 +1,17 @@
+namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Compensation;
+
+/// <summary>
+/// Distinguishes rollback-style restoration from forward corrective compensation.
+/// </summary>
+public enum GovernedCompensationKind
+{
+    /// <summary>
+    /// Attempts to restore the prior state or its equivalent.
+    /// </summary>
+    Rollback = 0,
+
+    /// <summary>
+    /// Applies a forward corrective action instead of restoring prior state.
+    /// </summary>
+    ForwardCorrection = 1
+}

src/Governance/Abstractions/Execution/Model/Compensation/GovernedCompensationPlan.cs

@@ -0,0 +1,43 @@
+namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Compensation;
+
+/// <summary>
+/// Describes how a governed request compensates for a prior execution.
+/// </summary>
+public sealed record GovernedCompensationPlan
+{
+    /// <summary>
+    /// Request identifier of the original execution being compensated.
+    /// </summary>
+    public string OriginalRequestId { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Compensation style to apply.
+    /// </summary>
+    public GovernedCompensationKind Kind { get; init; } = GovernedCompensationKind.Rollback;
+
+    /// <summary>
+    /// Trigger that initiated the compensation.
+    /// </summary>
+    public GovernedCompensationTrigger Trigger { get; init; } = GovernedCompensationTrigger.OperatorRollback;
+
+    /// <summary>
+    /// Optional batch identifier for batch-oriented compensation plans.
+    /// </summary>
+    public string? BatchId { get; init; }
+
+    /// <summary>
+    /// Optional identifiers of related requests in the same compensation plan.
+    /// </summary>
+    public IReadOnlyList<string> RelatedRequestIds { get; init; } = [];
+
+    /// <summary>
+    /// Optional human-readable rationale for the compensation.
+    /// </summary>
+    public string? Reason { get; init; }
+
+    internal void EnsureValid()
+    {
+        if (string.IsNullOrWhiteSpace(OriginalRequestId))
+            throw new InvalidOperationException("Compensation requests require an original request identifier.");
+    }
+}

src/Governance/Abstractions/Execution/Model/Compensation/GovernedCompensationTrigger.cs

@@ -0,0 +1,22 @@
+namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Compensation;
+
+/// <summary>
+/// Describes what initiated a governed compensation plan.
+/// </summary>
+public enum GovernedCompensationTrigger
+{
+    /// <summary>
+    /// A human operator explicitly initiated rollback or correction.
+    /// </summary>
+    OperatorRollback = 0,
+
+    /// <summary>
+    /// A batch workflow initiated compensation after one or more failures.
+    /// </summary>
+    BatchFailure = 1,
+
+    /// <summary>
+    /// A failed execution path initiated a compensating follow-up action.
+    /// </summary>
+    FailedExecution = 2
+}

src/Governance/Abstractions/Execution/Model/GovernedExecutionKind.cs

@@ -0,0 +1,17 @@
+namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model;
+
+/// <summary>
+/// Classifies governed execution as a primary mutation or compensating execution.
+/// </summary>
+public enum GovernedExecutionKind
+{
+    /// <summary>
+    /// Standard governed execution for the originally requested mutation.
+    /// </summary>
+    Standard = 0,
+
+    /// <summary>
+    /// Governed execution intended to compensate for a prior execution.
+    /// </summary>
+    Compensation = 1
+}

src/Governance/Abstractions/Execution/Model/GovernedExecutionResult.cs

@@ -1,11 +1,12 @@
 using ModularityKit.Mutator.Abstractions.Results;
+using ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Compensation;
 using ModularityKit.Mutator.Governance.Abstractions.Requests.Model;
 using ModularityKit.Mutator.Governance.Abstractions.Resolution.Model;
 
 namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model;
 
 /// <summary>
-/// Captures the outcome of executing a governed mutation request.
+/// Captures the outcome of executing governed mutation request.
 /// </summary>
 public sealed record GovernedExecutionResult<TState>
 {
@@ -29,6 +30,16 @@ public sealed record GovernedExecutionResult<TState>
     /// </summary>
     public bool WasExecuted { get; init; }
 
+    /// <summary>
+    /// Classifies the execution path represented by this result.
+    /// </summary>
+    public GovernedExecutionKind ExecutionKind { get; init; } = GovernedExecutionKind.Standard;
+
+    /// <summary>
+    /// Compensation plan attached to the execution when the request is compensating.
+    /// </summary>
+    public GovernedCompensationPlan? Compensation { get; init; }
+
     /// <summary>
     /// Resulting state version recorded after a successful execution.
     /// </summary>

src/Governance/Abstractions/Execution/Model/Links/GovernedExecutionLink.cs

@@ -0,0 +1,44 @@
+using ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Compensation;
+
+namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Links;
+
+/// <summary>
+/// Represents an explicit relation between governed execution records.
+/// </summary>
+public sealed record GovernedExecutionLink
+{
+    /// <summary>
+    /// Linked request identifier.
+    /// </summary>
+    public string RequestId { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Relationship to the linked request.
+    /// </summary>
+    public GovernedExecutionLinkType Type { get; init; }
+
+    /// <summary>
+    /// Execution kind of the linked request.
+    /// </summary>
+    public GovernedExecutionKind ExecutionKind { get; init; } = GovernedExecutionKind.Standard;
+
+    /// <summary>
+    /// Compensation style associated with the link when applicable.
+    /// </summary>
+    public GovernedCompensationKind? CompensationKind { get; init; }
+
+    /// <summary>
+    /// Trigger that led to the compensating execution when applicable.
+    /// </summary>
+    public GovernedCompensationTrigger? Trigger { get; init; }
+
+    /// <summary>
+    /// Optional batch identifier associated with the compensation plan.
+    /// </summary>
+    public string? BatchId { get; init; }
+
+    /// <summary>
+    /// Time when the relation was recorded.
+    /// </summary>
+    public DateTimeOffset LinkedAt { get; init; } = DateTimeOffset.UtcNow;
+}

src/Governance/Abstractions/Execution/Model/Links/GovernedExecutionLinkType.cs

@@ -0,0 +1,17 @@
+namespace ModularityKit.Mutator.Governance.Abstractions.Execution.Model.Links;
+
+/// <summary>
+/// Describes how one governed request relates to another.
+/// </summary>
+public enum GovernedExecutionLinkType
+{
+    /// <summary>
+    /// The current request compensates for the linked request.
+    /// </summary>
+    Compensates = 0,
+
+    /// <summary>
+    /// The current request was compensated by the linked request.
+    /// </summary>
+    CompensatedBy = 1
+}