ModularityKit.Mutator

What it provides

Quick start

using Microsoft.Extensions.DependencyInjection;
using ModularityKit.Mutator.Abstractions;
using ModularityKit.Mutator.Abstractions.Changes;
using ModularityKit.Mutator.Abstractions.Context;
using ModularityKit.Mutator.Abstractions.Engine;
using ModularityKit.Mutator.Abstractions.Intent;
using ModularityKit.Mutator.Abstractions.Policies;
using ModularityKit.Mutator.Abstractions.Results;
using ModularityKit.Mutator.Runtime;

var services = new ServiceCollection();
services.AddMutators(MutationEngineOptions.Strict);

var provider = services.BuildServiceProvider();
var engine = provider.GetRequiredService<IMutationEngine>();

engine.RegisterPolicy(new PreventNegativeQuotaPolicy());

var state = new QuotaState("tenant-42", 10);
var mutation = new IncreaseQuotaMutation("tenant-42", 5);

var result = await engine.ExecuteAsync(mutation, state);
Console.WriteLine(result.NewState!.Quota);

public sealed record QuotaState(string StateId, int Quota);

public sealed class IncreaseQuotaMutation : MutationBase<QuotaState>
{
    public IncreaseQuotaMutation(string stateId, int amount)
        : base(
            CreateIntent(
                operationName: "IncreaseQuota",
                category: "Quota",
                description: "Increase tenant quota"),
            MutationContext.System("Initial quota setup") with { StateId = stateId })
    {
        Amount = amount;
    }

    public int Amount { get; }

    public MutationResult<QuotaState> Apply(QuotaState state)
        => MutationResult<QuotaState>.Success(
            state with { Quota = state.Quota + Amount },
            ChangeSet.Single(StateChange.Modified("Quota", state.Quota, state.Quota + Amount)));

    public ValidationResult Validate(QuotaState state)
        => Amount > 0
            ? ValidationResult.Success()
            : ValidationResult.WithError("Amount", "Amount must be positive.");
}

public sealed class PreventNegativeQuotaPolicy : IMutationPolicy<QuotaState>
{
    public string Name => "PreventNegativeQuota";
    public int Priority => 100;
    public string? Description => "Rejects quota changes that would go negative.";

    public PolicyDecision Evaluate(IMutation<QuotaState> mutation, QuotaState state)
        => PolicyDecision.Allow();
}

Execution model

IMutationEngine runs a consistent pipeline around every mutation:

  1. evaluate registered policies
  2. validate the mutation against current state
  3. run interceptors
  4. apply the mutation
  5. record audit/history data
  6. update runtime metrics

Core runtime concurrency is controlled by MutationEngineOptions.MaxConcurrentMutations.

  • mutations targeting the same MutationContext.StateId are serialized
  • batch execution remains ordered and sequential
  • this is separate from request-storage concurrency in ModularityKit.Mutator.Governance

Primary APIs

Engine

  • IMutation<TState>
  • MutationBase<TState>
  • IMutationEngine
  • IMutationExecutor
  • MutationEngineOptions

Policies

  • IMutationPolicy<TState>
  • IPolicyRegistry
  • PolicyDecision
  • PolicyRequirement

Async policies and external checks

IMutationPolicy<TState> supports both synchronous and asynchronous evaluation.

  • implement Evaluate(...) for lightweight in-process rules
  • implement EvaluateAsync(..., CancellationToken) for external identity, ticketing, quota, or compliance checks
  • the runtime evaluates policies in descending Priority order
  • sync and async policies can be registered together; they participate in the same priority-ordered pipeline
  • when MutationEngineOptions.PolicyEvaluationTimeout is set, the timeout is applied per policy evaluation
  • caller cancellation still flows through unchanged
  • policy failures are surfaced as PolicyEvaluationException
  • policy timeouts are surfaced as PolicyEvaluationTimeoutException

Typical integration cases include:

  • external approval evidence checks
  • actor/identity resolution against IAM or directory systems
  • ticket status validation before execution
  • quota lookups in remote control planes
  • compliance or risk verification before commit
public sealed class RequireApprovedTicketPolicy : IMutationPolicy<QuotaState>
{
    private readonly ITicketGateway _tickets;

    public RequireApprovedTicketPolicy(ITicketGateway tickets)
    {
        _tickets = tickets;
    }

    public string Name => "RequireApprovedTicket";
    public int Priority => 200;
    public string? Description => "Checks ticket approval status before quota changes execute.";

    public async Task<PolicyDecision> EvaluateAsync(
        IMutation<QuotaState> mutation,
        QuotaState state,
        CancellationToken cancellationToken = default)
    {
        var ticketId = mutation.Context.CorrelationId;
        var approved = await _tickets.IsApprovedAsync(ticketId!, cancellationToken);

        return approved
            ? PolicyDecision.Allow(Name, "External ticket is approved.")
            : PolicyDecision.Deny("External ticket is not approved.", Name);
    }
}

Results and changes

  • MutationResult<TState>
  • BatchMutationResult<TState>
  • ValidationResult
  • ChangeSet
  • StateChange
  • SideEffect
  • SideEffectDataContractAttribute
  • SideEffectDataContractRegistry

Typed side effects

Use typed side effect payloads when the emitted data is meant to survive serialization, audit, or downstream integration:

[SideEffectDataContract("workflow.started", 1)]
public sealed record WorkflowStartedSideEffectData
{
    public required string Initiator { get; init; }
    public required int StepCount { get; init; }
    public required string WorkflowId { get; init; }
}

SideEffectDataContractRegistry.Register<WorkflowStartedSideEffectData>();

var effect = SideEffect.Create(
    type: "WorkflowStarted",
    description: "Approval workflow started",
    data: new WorkflowStartedSideEffectData
    {
        Initiator = "alice",
        StepCount = 2,
        WorkflowId = "wf-42"
    });

The side effect keeps DataContractType and DataContractVersion alongside Data, so persistence and integration layers do not have to guess the payload shape.

Context and intent

  • MutationContext
  • MutationIntent
  • BlastRadius

Runtime observability

  • IMutationAuditor
  • IMutationHistoryStore
  • MutationHistory
  • IMetricsCollector
  • MutationStatistics
  • IMutationInterceptor

Examples

Runnable examples for the core engine live under Examples/Core:

Relationship to governance

ModularityKit.Mutator is the direct execution runtime.

If your workflow needs deferred execution, request approval, pending states, or stale-version resolution before the mutation can run, use ModularityKit.Mutator.Governance on top of the core package.

Current scope

Included today:

  • direct mutation execution
  • batch execution
  • policy evaluation
  • validation and failure modeling
  • audit/history capture
  • metrics and interception
  • in-memory runtime components for local and test scenarios

Not included in the core package:

  • request lifecycle management
  • approval workflow orchestration
  • versioned request resolution
  • governed request persistence contracts