Skip to content

Feat: Add async policy evaluation, typed side effects, and runtime namespace refactor#43

Merged
rian-be merged 14 commits into
mainfrom
develop
Jun 30, 2026
Merged

Feat: Add async policy evaluation, typed side effects, and runtime namespace refactor#43
rian-be merged 14 commits into
mainfrom
develop

Conversation

@rian-be

@rian-be rian-be commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Add async policy evaluation support with external governance checks, introduce typed side effect contracts, and refactor the runtime execution namespace structure for better cohesion.

Added

  • IMutationPolicy<TState>.EvaluateAsync contract with default sync-to-async bridge for backwards compatibility
  • PolicyEvaluationTimeoutException for explicit timeout failure semantics during async policy evaluation
  • SideEffect<TData> typed side effect contract with explicit payload typing beyond object?
  • Runtime test coverage for typed side effect payloads and Redis serialization roundtrips
  • Runtime.Diagnostics namespace containing MutationAuditEntryFactory and StateSizeEstimator
  • Runtime.Internal.Execution subfolder grouping pipeline orchestration, concurrency, mode running, batch, and failure handling
  • Runtime.Internal.Evaluation subfolder grouping policy evaluation and policy modification application

Changed

  • MutationPolicyEvaluator now invokes EvaluateAsync with a linked CancellationTokenSource respecting PolicyEvaluationTimeout from engine options
  • Sync and async policy paths coexist without ambiguous semantics — async path is the primary evaluation contract
  • MutationEngine wired to Runtime.Diagnostics namespace and decomposed execution pipeline
  • Governance persistence, query, and Redis flows handle typed side effect payloads predictably through explicit SideEffect<TData> contracts
  • All /// <inheritdoc /> usages in MutationEngine replaced with explicit XML documentation matching IMutationEngine interface
  • XML documentation added to all runtime components: MutationBatchExecutor, PolicyModificationApplier, MutationAuditEntryFactory, StateSizeEstimator

Result

The runtime execution model is now organized by concern. Policy evaluation is fully async with explicit timeout and cancellation behavior. Side effect contracts are typed and survive persistence and downstream integration scenarios. The execution namespace structure matches the folder layout, aligning with Runtime.Audit, Runtime.Metrics, and Runtime.Policies conventions.

Testing

  • dotnet build
  • dotnet test Tests/ModularityKit.Mutator.Tests/ModularityKit.Mutator.Tests.csproj
  • dotnet test Tests/ModularityKit.Mutator.Governance.Tests/ModularityKit.Mutator.Governance.Tests.csproj
  • dotnet test Tests/ModularityKit.Mutator.Governance.Redis.Tests/ModularityKit.Mutator.Governance.Redis.Tests.csproj

Linked Issues

Checklist

  • async policy evaluation path is implemented and tested
  • sync and async policy paths coexist without ambiguous semantics
  • typed side effect contract is introduced and integrated with governance persistence
  • runtime namespace structure aligns with folder layout and existing conventions
  • XML documentation added to all affected runtime components

rian-be added 13 commits June 30, 2026 01:32
@rian-be
feat(core): add typed side effect contracts
b2d61d4
@rian-be
test(core): cover typed side effect payloads
bf96299
@rian-be
docs(examples): demonstrate typed side effect usage
394b419
@rian-be
refactor(storage): extract in-memory query materialization helpers
4250981
@rian-be
refactor(execution): delegate governed execution result handling
304d5bd
@rian-be
feat(queries): support side effect request filters
a8c444c
@rian-be
refactor(redis): align query materialization with evaluator split
90a063f
@rian-be
test(redis): cover side effect serialization and queries
0267129
@rian-be
feat(abstractions): add async mutation policy contract
97f4adc
@rian-be
feat(abstractions): add policy evaluation exceptions
1b1aa12
@rian-be
refactor(runtime): reorganize Internal into Execution and Evaluation …
e504133 
…subfolders

Split the flat Internal directory into two purpose-scoped subdirectories:
- Execution: pipeline orchestration, concurrency, mode running, batch, failure handling
- Evaluation: policy evaluation and policy modification application

Namespaces updated accordingly to match folder structure.
@rian-be
feat(runtime): extract Diagnostics into Runtime.Diagnostics namespace
82c9f66 
Move MutationAuditEntryFactory and StateSizeEstimator out of Internal
into a dedicated Runtime.Diagnostics namespace to align with the
existing Runtime.Audit, Runtime.Metrics, and Runtime.Policies pattern.

Diagnostics components are now accessible from Runtime-level consumers
without coupling to the internal execution namespace.
@rian-be
docs(runtime): replace inheritdoc with explicit XML docs in MutationE…
359e711 
…ngine

Replace all /// <inheritdoc /> usages in MutationEngine with explicit
XML documentation matching the IMutationEngine interface contract:
- ExecuteAsync
- ExecuteBatchAsync (both overloads, with remarks)
- RegisterPolicy, RegisterInterceptor (with remarks)
- GetHistoryAsync, GetStatisticsAsync

Add param/returns/exception tags to private helpers:
- ExecutePipelineAsync
- CreateConcurrencyGate (ArgumentNullException, ArgumentOutOfRangeException)
@github-actions github-actions Bot added abstractions Public abstractions and contracts runtime Runtime implementation and execution flow examples Runnable examples and sample apps tests Test coverage and test changes labels Jun 30, 2026
@rian-be rian-be merged commit bf9a94b into main Jun 30, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@rian-be rian-be

Labels

abstractions Public abstractions and contracts examples Runnable examples and sample apps runtime Runtime implementation and execution flow tests Test coverage and test changes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Task]: Add async policies and external governance checks [Task]: Add typed side effects for governance data flows

1 participant

@rian-be