ModularityKit.Mutator 0.1.3

ModularityKit.Mutators

A deterministic, async safe mutation engine with built in policy enforcement, audit logging, and execution context.

Features

• Deterministic State Mutations – Apply and simulate state changes safely
• Policy Enforcement – Declarative, composable mutation policies
• Async Safe Execution – Works across async/await boundaries
• Immutable State Models – Encourages safe, concurrent operations
• Audit & Change Tracking – ChangeSet captures granular modifications
• High Performance – Minimal overhead per mutation execution

Quick Start (Example)

using Microsoft.Extensions.DependencyInjection;
using ModularityKit.Mutators.Abstractions;
using ModularityKit.Mutators.Abstractions.Engine;
using ModularityKit.Mutators.Runtime;
using ModularityKit.Mutators.Runtime.Loggers;
using Mutators.Examples.BillingQuotas.Policies;
using Mutators.Examples.IamRoles.Policies;
using Mutators.Examples.WorkflowApprovals.Policies;
using IamTwoManApprovalPolicy = Mutators.Examples.IamRoles.Policies.RequireTwoManApprovalPolicy;
using FeatureFlagsTwoManApprovalPolicy = Mutators.Examples.FeatureFlags.Policies.RequireTwoManApprovalPolicy;

var services = new ServiceCollection();

// 1. Register Mutators engine with options
services.AddMutators(MutationEngineOptions.Strict, addDefaultLoggingInterceptor: true);

// 2. Build DI provider
var provider = services.BuildServiceProvider();
var engine = provider.GetRequiredService<IMutationEngine>();

// 3. Register policies
engine.RegisterPolicy(new MaxQuotaPolicy());
engine.RegisterPolicy(new PreventNegativeQuotaPolicy());
engine.RegisterPolicy(new IamTwoManApprovalPolicy());
engine.RegisterPolicy(new PreventLastAdminRemovalPolicy());
engine.RegisterPolicy(new FeatureFlagsTwoManApprovalPolicy());
engine.RegisterPolicy(new EnforceOrderPolicy());
engine.RegisterPolicy(new RequireManagerApprovalPolicy());

// 4. Execute example scenarios
await Examples.FeatureFlags.Scenarios.EnableNewCheckoutScenario.Run(engine);
await Examples.BillingQuotas.Scenarios.EmergencyIncreaseScenario.Run(engine);
await Examples.IamRoles.Scenarios.GrantAdminScenario.Run(engine);

// 5. Inspect history
var history = await engine.GetHistoryAsync(stateId: "EnableNewCheckout");
MutationHistoryLogger.LogHistory(history);

// 6. Metrics & statistics
var stats = await engine.GetStatisticsAsync();
Console.WriteLine($"Total executed: {stats.TotalExecuted}");
Console.WriteLine($"Average execution time: {stats.AverageExecutionTime.TotalMilliseconds:F2} ms");

Core Concepts

Mutation

Represents single atomic change to specific state.

• Implement IMutation<TState>
• Define intent (MutationIntent)
• Implement Validate(TState)
• Implement Apply(TState) and optionally Simulate(TState)

State

Immutable representation of domain data.

• use record types.
• Concurrent safe
• Represents the source of truth for mutations

Policy

Controls which mutations are allowed.

• Implement IMutationPolicy<TState>
• Evaluate mutations before application
• Return PolicyDecision.Allow() or PolicyDecision.Deny(reason)

Best Practices

1. Immutable State – Always use record types or read-only properties.
2. Explicit Context – Pass MutationContext per mutation.
3. Validate Before Apply – Call Validate() before applying a mutation.
4. Enforce Policies – Never skip policy evaluation.
5. Scoped Execution – Execute mutations inside a controlled engine.
6. Do Not Share Mutable State – Each logical operation gets its own state snapshot.
7. Use Clear IDs for Tracking – Helps with audit logs and debugging.
8. Centralized Registration – Register all policies at engine startup.

API Reference

Core Interfaces

• IMutation<TState> – Base interface for mutations
• IMutationPolicy<TState> – Policy controlling allowed mutations
• IMutationEngine – Engine for applying mutations
• MutationContext – Context carrying metadata about execution
• MutationResult<TState> – Wraps the new state and change set
• ChangeSet – Captures state modifications

Package Layout

• ModularityKit.Mutator - core mutation runtime, policies, audit, history, and side effects
• ModularityKit.Mutator.Governance - governed mutation request lifecycle, pending execution, and approval-oriented contracts

Metrics & Logging

The engine supports:

• Mutation execution history (GetHistoryAsync)
• Execution statistics (GetStatisticsAsync)
• Logging via MutationHistoryLogger
• Optional interceptors for audit and diagnostics

Architecture Decision Records (ADR)

Key architectural decisions for ModularityKit.Mutators are tracked as ADRs. They document engine design, policy evaluation, context handling, change tracking, and DI registration.

See full ADR documentation in Docs/Decision/Adr for details on each architectural decision.

Roadmap

The planned evolution of the engine is documented in Docs/Roadmap.md.