Feat: Add governed execution runtime (#27)

## Summary
This PR closes the first governed execution loop in
ModularityKit.Mutator.Governance and aligns the package docs with the
current runtime shape.

## Added
- governed execution contracts and runtime orchestration through
IGovernanceExecutionManager and GovernanceExecutionManager
- request execution outcome handling, guarded execution persistence, and
governance-aware mutation wrapping
- end-to-end governance execution coverage in
ModularityKit.Mutator.Governance.Tests
- runnable Examples/Governance/GovernedExecution sample
- ADR-027 for the governed execution manager

## Changed
- MutationRequest construction moved into MutationRequestFactory so the
request model stays focused on state
- governance examples and tests now use the request factory entry points
- governance package README now describes the runtime by flow and
responsibility instead of only folder layout
- governance example READMEs now point to the updated request factory
usage

## Result
Governance now owns the path from approved request to version
resolution, core mutation execution, and terminal request state. The
package documentation also reflects the current execution model instead
of describing major runtime pieces as future work.

## Testing
- dotnet build src/ModularityKit.Mutator.Governance.csproj -c Release
- dotnet build
Examples/Governance/GovernedExecution/GovernedExecution.csproj -c
Release
- dotnet test
Tests/ModularityKit.Mutator.Governance.Tests/ModularityKit.Mutator.Governance.Tests.csproj
-c Release

## Linked Issues
- Closes #16

## Checklist
- [x] Governed execution resolves requests before execution
- [x] Terminal execution outcomes are persisted through governance
runtime
- [x] Governance execution has runnable example coverage
- [x] Governance execution has test coverage
- [x] ADR and package docs reflect the new runtime shape

Author: rian-be

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.