Interface IMutationEngine

Orchestrates mutation execution using a fully governed, end-to-end pipeline.

Namespace: ModularityKit.Mutator.Abstractions.Engine

Assembly: ModularityKit.Mutator.dll

Syntax

public interface IMutationEngine

Remarks

IMutationEngine is the central coordination component responsible for executing mutations in a deterministic and auditable manner.

The execution pipeline includes, in order:

• Policy evaluation
• Validation
• Interception
• Execution
• Audit logging
• History persistence

Core runtime concurrency is governed by MaxConcurrentMutations. Mutations that target the same StateId are serialized by the runtime so shared-state workloads remain deterministic. This is separate from governance request storage concurrency, which protects request lifecycle writes in the governance package.

The engine acts as the primary governance boundary for all state mutations.

Methods

ExecuteAsync<TState>(IMutation<TState>, TState, CancellationToken)

Executes a single mutation using the full governance pipeline.

Declaration

Task<MutationResult<TState>> ExecuteAsync<TState>(IMutation<TState> mutation, TState state, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IMutation<TState>	mutation	The mutation to execute.
TState	state	The current state.
CancellationToken	cancellationToken	Token used to cancel execution.

Returns

Type	Description
Task<MutationResult<TState>>	A MutationResult<TState> containing the execution outcome, produced changes, and resulting state.

Type Parameters

Name	Description
TState	The type of the state being mutated.

ExecuteBatchAsync<TState>(IEnumerable<IMutation<TState>>, TState, CancellationToken)

Executes a batch of mutations as a single logical transaction.

Declaration

Task<BatchMutationResult<TState>> ExecuteBatchAsync<TState>(IEnumerable<IMutation<TState>> mutations, TState state, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IEnumerable<IMutation<TState>>	mutations	The sequence of mutations to execute.
TState	state	The initial state.
CancellationToken	cancellationToken	Token used to cancel execution.

Returns

Type	Description
Task<BatchMutationResult<TState>>	A BatchMutationResult<TState> describing the outcome of the batch execution.

Type Parameters

Name	Description
TState	The type of the state being mutated.

Remarks

Batch execution is ordered and sequential. Each batch step passes through the same core concurrency controls as a single execution, including the maximum concurrent execution limit and any state-specific serialization. Fail-fast vs best-effort behavior is controlled by MutationEngineOptions.

ExecuteBatchAsync<TState>(TState, params IMutation<TState>[])

Executes a batch of mutations as a single logical transaction.

Declaration

Task<BatchMutationResult<TState>> ExecuteBatchAsync<TState>(TState state, params IMutation<TState>[] mutations)

Parameters

Type	Name	Description
TState	state	The initial state.
IMutation<TState>[]	mutations	The mutations to execute in order.

Returns

Type	Description
Task<BatchMutationResult<TState>>	A BatchMutationResult<TState> describing the outcome of the batch execution.

Type Parameters

Name	Description
TState	The type of the state being mutated.

Remarks

This overload is optimized for call sites that want a compact mutation list without manually allocating an array.

GetHistoryAsync(string, CancellationToken)

Retrieves the mutation history for a given state identifier.

Declaration

Task<MutationHistory> GetHistoryAsync(string stateId, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	stateId	The identifier of the state.
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<MutationHistory>	A MutationHistory containing all recorded mutations for the state.

GetStatisticsAsync(CancellationToken)

Retrieves aggregated mutation execution statistics.

Declaration

Task<MutationStatistics> GetStatisticsAsync(CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Token used to cancel the operation.

Returns

Type	Description
Task<MutationStatistics>	A MutationStatistics snapshot representing engine-level metrics.

RegisterInterceptor(IMutationInterceptor)

Registers a global mutation interceptor.

Declaration

void RegisterInterceptor(IMutationInterceptor interceptor)

Parameters

Type	Name	Description
IMutationInterceptor	interceptor	The interceptor to register.

Remarks

Interceptors observe and react to mutation lifecycle events but must not directly alter mutation semantics.

RegisterPolicy<TState>(IMutationPolicy<TState>)

Registers a global mutation policy.

Declaration

void RegisterPolicy<TState>(IMutationPolicy<TState> policy)

Parameters

Type	Name	Description
IMutationPolicy<TState>	policy	The policy to register.

Type Parameters

Name	Description
TState	The state type the policy applies to.

Remarks

Global policies participate in evaluation for every compatible mutation and represent the primary governance mechanism.