Docs: Rebuild governance package guides

rian-be · rian-be · commit 82549e915b68 · 2026-06-24T01:00:45.000+02:00
diff --git a/Examples/Governance/ApprovalWorkflow/README.md b/Examples/Governance/ApprovalWorkflow/README.md
@@ -1,6 +1,6 @@
 # Governance ApprovalWorkflow
 
-This example shows the governance approval workflow built on top of `MutationRequest.PendingApproval(...)` and `MutationRequestApprovalWorkflowManager`.
+This example shows the governance approval workflow built on top of `MutationRequestFactory.PendingApproval(...)` and `MutationRequestApprovalWorkflowManager`.
 
 It demonstrates:
 
diff --git a/Examples/Governance/RequestLifecycle/README.md b/Examples/Governance/RequestLifecycle/README.md
@@ -6,7 +6,7 @@ It focuses on `MutationRequest`, `IMutationRequestStore`, and `MutationRequestLi
 
 ## What it demonstrates
 
-- creating governed requests with `MutationRequest.Pending(...)` and `MutationRequest.Approved(...)`
+- creating governed requests with `MutationRequestFactory.Pending(...)` and `MutationRequestFactory.Approved(...)`
 - storing requests in `InMemoryMutationRequestStore`
 - moving requests through the lifecycle with `MutationRequestLifecycleManager`
 - listing pending requests globally and by `StateId`
diff --git a/Examples/Governance/VersionedResolution/README.md b/Examples/Governance/VersionedResolution/README.md
@@ -36,7 +36,7 @@ var resolver = new MutationRequestVersionResolver();
 var manager = new MutationRequestVersionResolutionManager(store, resolver);
 
 var request = await store.Create(
-    MutationRequest.Approved(
+    MutationRequestFactory.Approved(
         stateId: "tenant-42:roles",
         stateType: "IamRoleState",
         mutationType: "GrantRoleMutation",
diff --git a/src/Governance/README.md b/src/Governance/README.md
@@ -10,106 +10,158 @@ The core package stays responsible for direct mutation execution. Governance bui
 - **Pending Lifecycle** - represent requests that cannot execute immediately
 - **Decision History** - record approvals, rejections, cancellations, and other lifecycle transitions
 - **Approval Workflow** - model request-level approval requirements and explicit approver actions
+- **Governed Execution** - execute approved requests through resolution and the core mutation engine
 - **Request Storage Contracts** - define a persistence seam for governance-oriented stores
 - **Runtime Lifecycle Management** - move requests through pending, approval, expiration, and execution transitions
 - **In-Memory Runtime Support** - provide lightweight request runtime services for development and tests
 
-## Current Structure
+## Governance Flow
 
-### Abstractions
+The package is built around a request-driven governance loop:
 
-The package defines governance-first abstractions under:
+1. create `MutationRequest`
+2. move it through pending lifecycle states when direct execution is not allowed
+3. collect approval decisions when approval is required
+4. resolve the request against the current state version before execution
+5. execute the underlying mutation through the core engine
+6. persist the terminal governance outcome and execution metadata
 
-- `Abstractions/Requests`
-- `Abstractions/Approval`
-- `Abstractions/Lifecycle`
-- `Abstractions/Storage`
-- `Abstractions/Resolution`
-- `Abstractions/Exceptions`
+The important point is that governance owns the request lifecycle around execution. The base `ModularityKit.Mutator` package still owns the mutation engine itself.
+
+## Main Entry Points
+
+Most consumers only need a small set of types.
 
-Key types:
+### Request Model
 
 - `MutationRequest`
-- `MutationApprovalRequirement`
-- `MutationApprovalRequirementStatus`
+- `MutationRequestFactory`
 - `MutationRequestDecision`
-- `MutationRequestDecisionType`
-- `MutationRequestDecisionCategory`
-- `MutationRequestLifecycleDecisionType`
-- `MutationRequestApprovalDecisionType`
-- `MutationRequestVersionResolutionDecisionType`
 - `MutationRequestStatus`
 - `PendingMutationReason`
+
+Use these to create and inspect governed requests.
+
+### Storage
+
 - `IMutationRequestStore`
-- `IMutationRequestApprovalWorkflowManager`
+- `InMemoryMutationRequestStore`
+
+Use the store to persist requests and load them back into governance runtime services.
+
+### Lifecycle
+
 - `IMutationRequestLifecycleManager`
+- `MutationRequestLifecycleManager`
+
+Use lifecycle services to submit, pend, approve, reject, expire, supersede, cancel, and mark requests as executed.
+
+### Approval
+
+- `IMutationRequestApprovalWorkflowManager`
+- `MutationRequestApprovalWorkflowManager`
+- `MutationApprovalRequirement`
+
+Use approval workflow services when a request must be explicitly approved by one or more actors before execution.
+
+### Version Resolution
+
 - `IMutationRequestVersionResolver`
 - `IMutationRequestVersionResolutionManager`
 - `MutationRequestVersionResolution`
 - `MutationRequestVersionResolutionOutcome`
 - `VersionedRequestResolutionStrategy`
-- `MutationRequestAlreadyExistsException`
-- `MutationApprovalRequirementNotFoundException`
-- `InvalidMutationApprovalActionException`
-- `MutationRequestConcurrencyException`
-- `MutationRequestNotFoundException`
-- `InvalidMutationRequestTransitionException`
 
-`Abstractions/Requests` is further split into:
+Use resolution services to decide what happens when deferred request no longer matches the state version it was created against.
+
+### Governed Execution
+
+- `IGovernanceExecutionManager`
+- `GovernanceExecutionManager`
+- `GovernedExecutionResult<TState>`
+
+Use governed execution to close the loop from approved request to core mutation execution and terminal governance state.
+
+## Package Areas
+
+The codebase is organized by governance concern rather than by framework layer alone.
+
+### Requests
+
+`Abstractions/Requests` contains the durable request model, decision taxonomy, and request factory methods.
 
 - `Requests/Model`
 - `Requests/Decisions`
+- `Requests/Factory`
+
+### Lifecycle
+
+`Lifecycle` owns generic request movement between governance states such as pending, approved, rejected, expired, superseded, and executed.
 
-`Abstractions/Approval` is further split into:
+- `Lifecycle/Contracts`
+- `Lifecycle/Model`
+- `Runtime/Lifecycle/Execution`
+- `Runtime/Lifecycle/Validation`
+- `Runtime/Lifecycle/State`
+
+### Approval
+
+`Approval` builds request-level approval workflow on top of the generic lifecycle model.
 
 - `Approval/Contracts`
 - `Approval/Model`
 - `Approval/Mapping`
+- `Runtime/Approval/Execution`
+- `Runtime/Approval/State`
+
+### Resolution
 
-`Abstractions/Resolution` is further split into:
+`Resolution` owns version-aware request handling before governed execution.
 
 - `Resolution/Contracts`
 - `Resolution/Model`
 - `Resolution/Strategies`
+- `Runtime/Resolution/Evaluation`
+- `Runtime/Resolution/Execution`
 
-`Abstractions/Lifecycle` is further split into:
+### Execution
 
-- `Lifecycle/Contracts`
-- `Lifecycle/Model`
+`Execution` owns the bridge from governance request semantics into the core mutation engine.
 
-`Abstractions/Exceptions` is further split into:
+- `Execution/Contracts`
+- `Execution/Model`
+- `Runtime/Execution/Mutation`
+- `Runtime/Execution/Orchestration`
+- `Runtime/Execution/Outcome`
+- `Runtime/Execution/Persistence`
 
-- `Exceptions/Approval`
-- `Exceptions/Lifecycle`
-- `Exceptions/Storage`
+### Storage and Exceptions
 
-### Runtime
+`Storage` defines persistence seams. `Exceptions` contains governance-specific failures grouped by concern.
 
-The initial runtime layer currently provides:
-
-- `Runtime/Storage/InMemoryMutationRequestStore`
-- `Runtime/Approval/MutationRequestApprovalWorkflowManager`
-- `Runtime/Lifecycle/MutationRequestLifecycleManager`
-- `Runtime/Resolution/MutationRequestVersionResolver`
-- `Runtime/Resolution/MutationRequestVersionResolutionManager`
-
-`Runtime/Resolution` is further split into:
-
-- `Resolution/Evaluation`
-- `Resolution/Execution`
+- `Abstractions/Storage`
+- `Abstractions/Exceptions/Approval`
+- `Abstractions/Exceptions/Lifecycle`
+- `Abstractions/Exceptions/Storage`
 
-`Runtime/Lifecycle` is further split into:
+## What Exists Today
 
-- `Lifecycle/Execution`
-- `Lifecycle/Validation`
-- `Lifecycle/State`
+Today the package already provides:
 
-`Runtime/Approval` is further split into:
+- durable `MutationRequest` modeling
+- request-level approval requirements
+- optimistic concurrency in request storage
+- explicit lifecycle transitions
+- version-aware request resolution
+- governed execution through the core mutation engine
+- in-memory runtime support for examples and tests
 
-- `Approval/Execution`
-- `Approval/State`
+What it does not try to do yet:
 
-This keeps the first version small while leaving room for later persistence providers such as Entity Framework Core or PostgreSQL-backed governance stores.
+- persistence providers such as EF Core or PostgreSQL
+- query stores for operational governance reporting
+- compensation and retry orchestration
+- external async approval or policy integrations
 
 ## Relationship to Core
 
@@ -135,14 +187,13 @@ Responsible for:
 
 ## Direction
 
-This package is intentionally the place where broader governance behavior should grow.
+This package is the place where broader governance behavior should grow without turning the core mutation engine into a workflow framework.
 
-That includes future work such as:
+The near-term direction is:
 
-- pending mutation resolution
-- approval workflow execution
-- version aware deferred execution
-- governance persistence providers
-- governance query APIs
+- harden governed execution semantics
+- add governance persistence and query providers
+- expose governance metadata operationally
+- support richer approval and integration scenarios
 
 The goal is to keep the core runtime small and execution focused while letting governance evolve as an opt-in extension.
