perf: reduce result creation and materialization overhead

Author: rian-be

src/Abstractions/Audit/MutationAuditEntry.cs

@@ -7,20 +7,20 @@
 namespace ModularityKit.Mutator.Abstractions.Audit;
 
 /// <summary>
-/// Represents a single audit record for a mutation operation.
+/// Represents single audit record for a mutation operation.
 /// Captures the intent, context, changes, policy decisions, and metadata of the mutation.
 /// </summary>
 /// <remarks>
 /// Mutation audit entries are used for compliance, traceability, debugging, and monitoring.
 /// Each entry is immutable once created. Typical consumers include auditors, logging systems,
 /// or analytics pipelines.
 /// </remarks>
-public sealed class MutationAuditEntry
+public readonly record struct MutationAuditEntry
 {
     /// <summary>
     /// Unique execution identifier for this mutation.
     /// </summary>
-    public string ExecutionId { get; init; } = string.Empty;
+    public string ExecutionId { get; init; }
 
     /// <summary>
     /// Identifier of the state object that was mutated.
@@ -35,17 +35,17 @@ public sealed class MutationAuditEntry
     /// <summary>
     /// The intent describing what the mutation is trying to achieve.
     /// </summary>
-    public MutationIntent MutationIntent { get; init; } = null!;
+    public MutationIntent MutationIntent { get; init; }
 
     /// <summary>
     /// Context of the mutation (e.g., correlation data, user context).
     /// </summary>
-    public MutationContext Context { get; init; } = null!;
+    public MutationContext Context { get; init; }
 
     /// <summary>
     /// Changes applied by the mutation.
     /// </summary>
-    public ChangeSet Changes { get; init; } = ChangeSet.Empty;
+    public ChangeSet Changes { get; init; }
 
     /// <summary>
     /// Indicates whether the mutation was successful.
@@ -60,12 +60,12 @@ public sealed class MutationAuditEntry
     /// <summary>
     /// Decisions made by policies during the mutation evaluation.
     /// </summary>
-    public IReadOnlyList<PolicyDecision> PolicyDecisions { get; init; } = [];
+    public IReadOnlyList<PolicyDecision> PolicyDecisions { get; init; }
 
     /// <summary>
     /// Side effects produced during the mutation.
     /// </summary>
-    public IReadOnlyList<SideEffect> SideEffects { get; init; } = [];
+    public IReadOnlyList<SideEffect> SideEffects { get; init; }
 
     /// <summary>
     /// Timestamp when the mutation started.

src/Abstractions/Changes/ChangeSet.cs

@@ -1,11 +1,12 @@
 namespace ModularityKit.Mutator.Abstractions.Changes;
 
 /// <summary>
-/// Represents a collection of state changes introduced by a mutation.
-/// This is a **primary feature** of a mutation and not an optional addition.
+/// Represents collection of state changes introduced by a mutation.
+/// This is primary feature of mutation and not an optional addition.
 /// </summary>
 public sealed class ChangeSet
 {
+    private static readonly ChangeSet _empty = new();
     private readonly List<StateChange> _changes = [];
 
     /// <summary>
@@ -34,7 +35,7 @@ public sealed class ChangeSet
     public string? Checksum { get; init; }
 
     /// <summary>
-    /// Adds a new state change to the changeset.
+    /// Adds new state change to the changeset.
     /// </summary>
     /// <param name="change">The state change to add.</param>
     /// <exception cref="ArgumentNullException">Thrown if <paramref name="change"/> is null.</exception>
@@ -45,15 +46,15 @@ public void Add(StateChange change)
     }
 
     /// <summary>
-    /// Retrieves all changes corresponding to a specific path.
+    /// Retrieves all changes corresponding to specific path.
     /// </summary>
     /// <param name="path">The path to filter changes.</param>
     /// <returns>Enumerable of <see cref="StateChange"/> matching the path.</returns>
     public IEnumerable<StateChange> GetChanges(string path)
         => _changes.Where(c => c.Path == path);
 
     /// <summary>
-    /// Determines whether a specific path has been changed.
+    /// Determines whether specific path has been changed.
     /// </summary>
     /// <param name="path">The path to check.</param>
     /// <returns>True if the path has been changed; otherwise, false.</returns>
@@ -70,7 +71,7 @@ public IEnumerable<string> GetChangedPaths()
     /// <summary>
     /// Returns an empty changeset.
     /// </summary>
-    public static ChangeSet Empty => new();
+    public static ChangeSet Empty => _empty;
 
     /// <summary>
     /// Creates changeset containing single state change.

src/Abstractions/Effects/SideEffect.cs

@@ -1,3 +1,4 @@
+using System.Collections.Concurrent;
 using System.Text.Json.Serialization;
 
 namespace ModularityKit.Mutator.Abstractions.Effects;
@@ -189,20 +190,33 @@ private static SideEffect CreateCore(
         };
     }
 
+    private static readonly ConcurrentDictionary<Type, (string? ContractType, int? ContractVersion)> _contractCache = new();
+
     private static (string? ContractType, int? ContractVersion) ResolveContract(object? data)
     {
         if (data is null)
             return (null, null);
 
         var dataType = data.GetType();
+        if (_contractCache.TryGetValue(dataType, out var cached))
+            return cached;
+
         var contract = dataType.GetCustomAttributes(typeof(SideEffectDataContractAttribute), inherit: false)
             .OfType<SideEffectDataContractAttribute>()
             .SingleOrDefault();
 
+        (string?, int?) result;
         if (contract is null)
-            return (null, null);
+        {
+            result = (null, null);
+        }
+        else
+        {
+            SideEffectDataContractRegistry.Register(dataType);
+            result = (contract.ContractType, contract.ContractVersion);
+        }
 
-        SideEffectDataContractRegistry.Register(dataType);
-        return (contract.ContractType, contract.ContractVersion);
+        _contractCache.TryAdd(dataType, result);
+        return result;
     }
 }

src/Abstractions/History/MutationHistory.cs

@@ -3,10 +3,10 @@
 namespace ModularityKit.Mutator.Abstractions.History;
 
 /// <summary>
-/// Represents the full mutation history of a specific state object.
+/// Represents the full mutation history of specific state object.
 /// </summary>
 /// <remarks>
-/// MutationHistory stores a chronological sequence of <see cref="MutationHistoryEntry"/> entries.
+/// MutationHistory stores chronological sequence of <see cref="MutationHistoryEntry"/> entries.
 /// It allows replaying state changes, querying timelines for specific paths, and computing statistics.
 /// This is typically used in combination with <see cref="IMutationHistoryStore"/> to persist and retrieve histories.
 /// </remarks>
@@ -32,13 +32,13 @@ public sealed class MutationHistory
     /// Timestamp of the first mutation in the history.
     /// </summary>
     public DateTimeOffset? FirstMutationAt
-        => Entries.FirstOrDefault()?.Timestamp;
+        => Entries.Count > 0 ? Entries[0].Timestamp : null;
 
     /// <summary>
     /// Timestamp of the last mutation in the history.
     /// </summary>
     public DateTimeOffset? LastMutationAt
-        => Entries.LastOrDefault()?.Timestamp;
+        => Entries.Count > 0 ? Entries[^1].Timestamp : null;
 
     /// <summary>
     /// Total number of mutations recorded.

src/Abstractions/History/MutationHistoryEntry.cs

@@ -11,39 +11,39 @@ namespace ModularityKit.Mutator.Abstractions.History;
 /// <remarks>
 /// Each <see cref="MutationHistoryEntry"/> captures the details of a single mutation,
 /// including its intent, context, state changes, side effects, execution timing, and integrity hashes.
-/// This class is used by <see cref="MutationHistory"/> to store a chronological sequence of mutations.
+/// This type is used by <see cref="MutationHistory"/> to store a chronological sequence of mutations.
 /// </remarks>
-public sealed class MutationHistoryEntry
+public readonly record struct MutationHistoryEntry
 {
     /// <summary>
     /// Unique identifier for the execution of this mutation.
     /// </summary>
-    public string ExecutionId { get; init; } = string.Empty;
+    public string ExecutionId { get; init; }
 
     /// <summary>
     /// Identifier of the state this mutation was applied to.
     /// </summary>
-    public string StateId { get; init; } = string.Empty;
+    public string StateId { get; init; }
 
     /// <summary>
     /// The intent behind the mutation.
     /// </summary>
-    public MutationIntent Intent { get; init; } = null!;
+    public MutationIntent Intent { get; init; }
 
     /// <summary>
     /// Contextual information about the mutation execution.
     /// </summary>
-    public MutationContext Context { get; init; } = null!;
+    public MutationContext Context { get; init; }
 
     /// <summary>
     /// Set of changes applied by this mutation.
     /// </summary>
-    public ChangeSet Changes { get; init; } = ChangeSet.Empty;
+    public ChangeSet Changes { get; init; }
 
     /// <summary>
     /// Side effects produced by this mutation.
     /// </summary>
-    public IReadOnlyList<SideEffect> SideEffects { get; init; } = [];
+    public IReadOnlyList<SideEffect> SideEffects { get; init; }
 
     /// <summary>
     /// Timestamp indicating when the mutation occurred.

src/Abstractions/Metrics/MutationMetrics.cs

@@ -12,6 +12,7 @@ namespace ModularityKit.Mutator.Abstractions.Metrics;
 /// <para>
 /// Key considerations:
 /// <list type="bullet">
+/// <item><see cref="RecordedAt"/> timestamp of the mutation recording.</item>
 /// <item><see cref="ExecutionTime"/> measures the total duration of the mutation.</item>
 /// <item><see cref="ValidationTime"/> measures time spent validating the mutation.</item>
 /// <item><see cref="PolicyEvaluationTime"/> measures time spent evaluating policies.</item>
@@ -25,6 +26,11 @@ namespace ModularityKit.Mutator.Abstractions.Metrics;
 /// </remarks>
 public sealed record MutationMetrics
 {
+    private static readonly IReadOnlyDictionary<string, object> _emptyAdditionalMetrics
+        = new Dictionary<string, object>();
+
+    internal static readonly MutationMetrics Empty = new();
+
     /// <summary>
     /// Timestamp when the mutation was recorded.
     /// </summary>
@@ -46,12 +52,12 @@ public sealed record MutationMetrics
     public TimeSpan PolicyEvaluationTime { get; init; }
 
     /// <summary>
-    /// Number of rules validated during the mutation.
+    /// Number of validated rules.
     /// </summary>
     public int ValidatedRules { get; init; }
 
     /// <summary>
-    /// Number of policies evaluated during the mutation.
+    /// Number of evaluated policies.
     /// </summary>
     public int EvaluatedPolicies { get; init; }
 
@@ -61,23 +67,23 @@ public sealed record MutationMetrics
     public int ChangesCount { get; init; }
 
     /// <summary>
-    /// Size of the state before the mutation (in bytes, if applicable).
+    /// Size of the state object in bytes, if available.
     /// </summary>
     public long? StateSize { get; init; }
 
     /// <summary>
-    /// Memory used during mutation execution (in bytes).
+    /// Memory used during mutation execution in bytes, if available.
     /// </summary>
     public long? MemoryUsed { get; init; }
 
     /// <summary>
-    /// Indicates whether a cache was used.
+    /// Indicates whether caching was used during the mutation.
     /// </summary>
     public bool UsedCache { get; init; }
 
     /// <summary>
-    /// Additional custom metrics.
+    /// Additional metrics for extensibility.
     /// </summary>
     public IReadOnlyDictionary<string, object> AdditionalMetrics { get; init; }
-        = new Dictionary<string, object>();
+        = _emptyAdditionalMetrics;
 }