Feat: add governance query APIs and read side examples

rian-be · Jun 26, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
commit df0a0d32313e48630ed4a05566a0197e0ce0c9fa
diff --git a/Examples/Governance/Queries/Program.cs b/Examples/Governance/Queries/Program.cs
@@ -0,0 +1,3 @@
+using Queries.Scenarios;
+
+await GovernanceQueriesScenario.Run();
diff --git a/Examples/Governance/Queries/Queries.csproj b/Examples/Governance/Queries/Queries.csproj
@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <OutputType>Exe</OutputType>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <ProjectReference Include="..\..\..\src\ModularityKit.Mutator.Governance.csproj" />
+    </ItemGroup>
+
+</Project>
diff --git a/Examples/Governance/Queries/README.md b/Examples/Governance/Queries/README.md
@@ -0,0 +1,49 @@
+# Governance Queries
+
+This example shows the query-oriented read side of `ModularityKit.Mutator.Governance`.
+
+It focuses on listing governed requests, approval work, and decision history without reconstructing those views manually from raw stored records.
+
+## What it demonstrates
+
+- querying governed requests with `MutationRequestQuery`
+- listing the pending approval queue through `IMutationRequestQueryStore`
+- listing pending requests by `PendingMutationReason`
+- querying requests by `StateId` and request category
+- listing recent approval-driven requests
+- projecting pending approval work with `MutationApprovalQuery`
+- projecting recent decision history with `MutationRequestDecisionQuery`
+- projecting recent execution outcomes separately from version resolution history
+- using the in-memory governance store as both write-side storage and query-side read model
+
+## Key files
+
+- [`Program.cs`](Program.cs)
+- [`Scenarios/GovernanceQueriesScenario.cs`](Scenarios/GovernanceQueriesScenario.cs)
+- [`Scenarios/GovernanceQueriesSampleData.cs`](Scenarios/GovernanceQueriesSampleData.cs)
+- [`Scenarios/RequestQueryScenario.cs`](Scenarios/RequestQueryScenario.cs)
+- [`Scenarios/ApprovalQueryScenario.cs`](Scenarios/ApprovalQueryScenario.cs)
+- [`Scenarios/DecisionQueryScenario.cs`](Scenarios/DecisionQueryScenario.cs)
+- [`src/Governance/Abstractions/Queries/Contracts/IMutationRequestQueryStore.cs`](../../../src/Governance/Abstractions/Queries/Contracts/IMutationRequestQueryStore.cs)
+- [`src/Governance/Abstractions/Queries/Model/MutationRequestQuery.cs`](../../../src/Governance/Abstractions/Queries/Model/MutationRequestQuery.cs)
+- [`src/Governance/Abstractions/Queries/Model/MutationApprovalQuery.cs`](../../../src/Governance/Abstractions/Queries/Model/MutationApprovalQuery.cs)
+- [`src/Governance/Abstractions/Queries/Model/MutationRequestDecisionQuery.cs`](../../../src/Governance/Abstractions/Queries/Model/MutationRequestDecisionQuery.cs)
+
+## Run
+
+```bash
+dotnet run --project Examples/Governance/Queries/Queries.csproj
+```
+
+## Expected output
+
+The sample prints:
+
+- pending approval requests
+- pending external-check requests
+- requests filtered by request category
+- requests filtered by state
+- recent approval-driven requests
+- approval views filtered by approver
+- recent version-resolution decisions
+- recent execution outcomes
diff --git a/Examples/Governance/Queries/Scenarios/ApprovalQueryScenario.cs b/Examples/Governance/Queries/Scenarios/ApprovalQueryScenario.cs
@@ -0,0 +1,16 @@
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Contracts;
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Model;
+
+namespace Queries.Scenarios;
+
+internal static class ApprovalQueryScenario
+{
+    public static async Task Run(IMutationRequestQueryStore queryStore)
+    {
+        GovernanceQueriesSampleData.PrintSection("Pending Approvals For security-lead");
+        GovernanceQueriesSampleData.PrintApprovals(await queryStore.GetPendingApprovalsAsync(new MutationApprovalQuery
+        {
+            ApproverIds = new HashSet<string> { "security-lead" }
+        }));
+    }
+}
diff --git a/Examples/Governance/Queries/Scenarios/DecisionQueryScenario.cs b/Examples/Governance/Queries/Scenarios/DecisionQueryScenario.cs
@@ -0,0 +1,20 @@
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Contracts;
+using ModularityKit.Mutator.Governance.Abstractions.Queries.Model;
+
+namespace Queries.Scenarios;
+
+internal static class DecisionQueryScenario
+{
+    public static async Task Run(IMutationRequestQueryStore queryStore)
+    {
+        GovernanceQueriesSampleData.PrintSection("Recent Version Resolution Decisions");
+        GovernanceQueriesSampleData.PrintDecisions(await queryStore.GetRecentDecisionsAsync(
+            MutationRequestDecisionQuery.RecentVersionResolutions(),
+            take: 5));
+
+        GovernanceQueriesSampleData.PrintSection("Recent Execution Outcomes");
+        GovernanceQueriesSampleData.PrintDecisions(await queryStore.GetRecentDecisionsAsync(
+            MutationRequestDecisionQuery.RecentExecutionOutcomes(),
+            take: 5));
+    }
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		using Queries.Scenarios;

		await GovernanceQueriesScenario.Run();