Feat: Add governed execution runtime

Docs/Decision/Adr/ADR_027_Governed_Execution_Manager.md

@@ -0,0 +1,99 @@
+# ADR-027: Governed Execution Manager
+
+## Tag
+#adr_027
+
+## Status
+Accepted
+
+## Date
+2026-06-24
+
+## Scope
+ModularityKit.Mutator.Governance
+
+## Context
+
+The governance package already models:
+
+- durable mutation requests
+- pending request lifecycle
+- approval workflow
+- version-aware request resolution
+
+What remained open was the final governed execution loop:
+
+- load an approved request
+- resolve it against the current state version
+- execute the underlying core mutation only when resolution permits it
+- persist the terminal governance outcome
+- record the resulting state version for future audit and replay
+
+Without an explicit runtime service for that flow, callers would have to manually compose:
+
+- request loading
+- resolution
+- mutation engine invocation
+- request status persistence
+- execution decision history
+
+That would make governed execution easy to implement inconsistently across applications.
+
+## Decision
+
+The governance package introduces a dedicated governed execution runtime centered on `IGovernanceExecutionManager`.
+
+The governed execution flow is:
+
+1. load and resolve an approved request through governance version resolution
+2. stop early when resolution yields a non-executable outcome such as:
+   - `RejectedAsStale`
+   - `RequiresRenewedApproval`
+3. execute the wrapped core mutation through `IMutationEngine` only when resolution allows execution
+4. persist the terminal governance request outcome:
+   - `Executed` on successful mutation execution
+   - `Rejected` on failed execution or execution exception
+5. record governance metadata such as:
+   - resulting state version
+   - executed timestamp
+   - request correlation metadata flowing into core audit/history
+
+The runtime is intentionally split by responsibility:
+
+- `GovernanceExecutionManager` orchestrates the end-to-end flow
+- `GovernedMutation` carries governance request identifiers into core execution metadata
+- `GovernedExecutionOutcomeHandler` maps execution outcomes into terminal request state
+- `GovernedExecutionDecisionFactory` creates execution-related governance decisions
+- `GovernedExecutionRequestPersistence` performs guarded request persistence with optimistic concurrency
+
+## Design Rationale
+
+- Governed execution is governance concern, not responsibility of the base mutation engine.
+- Version resolution must always happen before governed execution proceeds.
+- Terminal request persistence must be handled consistently and with optimistic concurrency checks.
+- The execution runtime should remain decomposed so orchestration, persistence, and decision mapping can evolve independently.
+
+## Consequences
+
+### Positive
+
+- Governance now closes the loop from approved request to terminal execution outcome.
+- Version drift handling is enforced before core execution starts.
+- Core audit/history can be correlated with governance request identifiers.
+- Execution state is recorded explicitly through `ExecutedAt` and `ResultingStateVersion`.
+
+### Negative
+
+- Governance runtime now owns a larger orchestration surface.
+- Execution failures currently collapse into terminal rejection and may require richer taxonomy later.
+- Future work is still needed for:
+  - governed execution retries
+  - compensation semantics
+  - persistent queryable execution history across providers
+
+## Related ADRs
+
+- ADR-020: Governance MutationRequest Model
+- ADR-023: Governance Versioned Request Resolution
+- ADR-024: Governance Runtime Pending Request Handling
+- ADR-025: Governance Approval Workflow

Docs/Decision/listadr.md

@@ -42,5 +42,6 @@ These ADRs describe the `ModularityKit.Mutator.Governance` extension layer and i
 | ADR-024 | Governance Runtime Pending Request Handling          | [ADR-024](Adr/ADR_024_Governance_Runtime_Pending_Request_Handling.md)          |
 | ADR-025 | Governance Approval Workflow                         | [ADR-025](Adr/ADR_025_Governance_Approval_Workflow.md)                         |
 | ADR-026 | Governance Request Query API                         | [ADR-026](Adr/ADR_026_Governance_Request_Query_API.md)                         |
+| ADR-027 | Governed Execution Manager                           | [ADR-027](Adr/ADR_027_Governed_Execution_Manager.md)                           |
 
 > See individual ADRs for detailed context, decision rationale, and consequences.

Docs/ExecutionModel.md

@@ -2,7 +2,7 @@
 
 This document describes the execution model that `ModularityKit.Mutator` is moving toward as governance features become first-class runtime capabilities.
 
-It complements the roadmap by explaining the lifecycle of a mutation once the engine supports pending execution, approvals, versioning, and compensation.
+It complements the roadmap by explaining the lifecycle of a mutation now that governance already has request lifecycle, approval workflow, and version-resolution primitives, but still needs a fully closed governed execution loop.
 
 ## Current Model
 
@@ -18,7 +18,7 @@ Today, the engine is centered around direct mutation execution:
 This model is strong for immediate execution flows, but it is intentionally narrow:
 
 - blocked mutations are terminal outcomes
-- approval requirements are modeled but not yet lifecycle-driven
+- direct mutation execution is still the dominant runtime path
 - concurrency is not yet part of a first-class execution contract
 - compensation and re-execution are not yet modeled as governed transitions
 
@@ -32,11 +32,12 @@ The target shape is:
 2. Evaluate policies and requirements
 3. Enter pending state when execution is deferred
 4. Resolve requirements through approvals or external checks
-5. Re-validate against the current state version
-6. Execute or reject
+5. Resolve against the current state version
+6. Execute through a governed execution manager
 7. Emit side effects
 8. Audit and persist history
-9. Optionally compensate or reverse
+9. Record executed or terminal governance decision
+10. Optionally compensate or reverse
 
 This is the key conceptual shift in the project:
 
@@ -69,7 +70,7 @@ Possible pending reasons:
 - `PendingDependency`
 - `PendingQuota`
 
-Pending state should be treated as a first-class runtime state, not just a flag in `MutationResult`.
+Pending state is already a first-class governance state. The remaining work is to ensure every pending path has a clear re-entry route into governed execution.
 
 ### Resolution
 
@@ -83,6 +84,8 @@ Possible outcomes:
 - expired
 - superseded by a newer request or state version
 
+Resolution is already modeled in the governance runtime. The remaining gap is making it part of one mandatory execution path rather than a helper that callers compose manually.
+
 ### Versioned Execution
 
 Approval and deferred execution require explicit version handling.
@@ -95,6 +98,23 @@ When a request is approved against a later state than the one originally evaluat
 
 This behavior must be explicit and consistent across all pending mutation types.
 
+The main hardening point is no longer whether version resolution exists, but whether approved requests always pass through it before execution and whether revalidation has its own explicit runtime semantics.
+
+### Governed Execution Manager
+
+Once approvals and version resolution exist, the runtime needs one orchestrator that closes the loop.
+
+Expected responsibilities:
+
+- load an approved request
+- perform mandatory version resolution
+- choose execute / reject / re-approve / revalidate paths
+- invoke the core mutation engine when execution is still valid
+- record resulting state version and execution outcome
+- persist terminal governance decisions such as `Executed`
+
+Without this step, governance remains a set of useful runtime pieces rather than one coherent execution contract.
+
 ### Compensation
 
 Once the engine supports governed execution over time, compensation becomes part of the execution model rather than a simple utility.
@@ -123,18 +143,20 @@ Without an explicit execution model, these features risk being implemented as is
 
 ## Design Pressure Points
 
-These are the architectural questions that should stay visible as implementation starts:
+These are the architectural questions that should stay visible as implementation continues:
 
 - Is the primary unit of governance a mutation or a mutation request?
 - What state version contract is required for deferred execution?
 - When does a pending mutation become stale?
 - Can approvals survive state drift, or must they be renewed?
+- What is the exact contract of revalidation before execution?
 - Are side effects emitted on request creation, on execution, or both?
 - How are compensation flows represented in audit and history?
+- Where does core mutation execution concurrency end and governance request concurrency begin?
 
 ## Relationship to the Roadmap
 
-- `v1.1 Governance Runtime` introduces pending mutation lifecycle, approval workflow, versioned execution, and concurrency control.
+- `v1.1 Governance Runtime Hardening` closes the governed execution loop and hardens approval, version-resolution, and core concurrency semantics.
 - `v1.2 Governance Data` adds persistence, queryability, metadata handling, and typed side effects around that runtime model.
 - `v1.3 Integration` expands the model to async policy evaluation and external governance dependencies.
 - `v2.0 Governance Platform` extends the lifecycle with compensation and richer policy composition.