feat(runtime): extract Diagnostics into Runtime.Diagnostics namespace

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.

Author: rian-be

src/Runtime/Diagnostics/MutationAuditEntryFactory.cs

@@ -0,0 +1,166 @@
+using ModularityKit.Mutator.Abstractions.Audit;
+using ModularityKit.Mutator.Abstractions.Changes;
+using ModularityKit.Mutator.Abstractions.Context;
+using ModularityKit.Mutator.Abstractions.Engine;
+using ModularityKit.Mutator.Abstractions.Effects;
+using ModularityKit.Mutator.Abstractions.History;
+using ModularityKit.Mutator.Abstractions.Policies;
+using ModularityKit.Mutator.Abstractions.Results;
+
+namespace ModularityKit.Mutator.Runtime.Diagnostics;
+
+/// <summary>
+/// Factory for creating audit and history entries for mutations.
+/// </summary>
+internal static class MutationAuditEntryFactory
+{
+    /// <summary>
+    /// Creates a successful mutation audit entry.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="mutation">The mutation that was executed.</param>
+    /// <param name="result">The result of the mutation execution.</param>
+    /// <param name="policyDecision">The policy decision applied to the mutation.</param>
+    /// <param name="executionId">The unique identifier of the execution.</param>
+    /// <param name="duration">The execution duration.</param>
+    /// <returns>A configured <see cref="MutationAuditEntry"/> representing success.</returns>
+    public static MutationAuditEntry CreateSuccess<TState>(
+        IMutation<TState> mutation,
+        MutationResult<TState> result,
+        PolicyDecision policyDecision,
+        string executionId,
+        TimeSpan duration)
+    {
+        return Create(
+            mutation,
+            executionId,
+            duration,
+            isSuccess: true,
+            changes: result.Changes,
+            policyDecisions: result.PolicyDecisions.Count > 0 ? result.PolicyDecisions : [policyDecision],
+            sideEffects: result.SideEffects,
+            sourceIpAddress: mutation.Context.SourceIpAddress,
+            userAgent: mutation.Context.UserAgent);
+    }
+
+    /// <summary>
+    /// Creates a failed mutation audit entry.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="mutation">The mutation that was executed.</param>
+    /// <param name="result">The result of the mutation execution.</param>
+    /// <param name="executionId">The unique identifier of the execution.</param>
+    /// <param name="duration">The execution duration.</param>
+    /// <returns>A configured <see cref="MutationAuditEntry"/> representing failure.</returns>
+    public static MutationAuditEntry CreateFailure<TState>(
+        IMutation<TState> mutation,
+        MutationResult<TState> result,
+        string executionId,
+        TimeSpan duration)
+    {
+        return Create(
+            mutation,
+            executionId,
+            duration,
+            isSuccess: false,
+            changes: result.Changes,
+            errorMessage: string.Join("; ", result.ValidationResult.Errors.Select(e => e.Message)),
+            policyDecisions: result.PolicyDecisions,
+            sideEffects: result.SideEffects);
+    }
+
+    /// <summary>
+    /// Creates a failed mutation audit entry due to an exception.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="mutation">The mutation that was executed.</param>
+    /// <param name="exception">The exception that occurred.</param>
+    /// <param name="executionId">The unique identifier of the execution.</param>
+    /// <param name="duration">The execution duration.</param>
+    /// <returns>A configured <see cref="MutationAuditEntry"/> representing an exception failure.</returns>
+    public static MutationAuditEntry CreateException<TState>(
+        IMutation<TState> mutation,
+        Exception exception,
+        string executionId,
+        TimeSpan duration)
+    {
+        return Create(
+            mutation,
+            executionId,
+            duration,
+            isSuccess: false,
+            errorMessage: exception.Message);
+    }
+
+    /// <summary>
+    /// Creates a mutation history entry for persistence.
+    /// </summary>
+    /// <typeparam name="TState">The state type handled by the mutation.</typeparam>
+    /// <param name="mutation">The mutation that was executed.</param>
+    /// <param name="result">The result of the mutation execution.</param>
+    /// <param name="executionId">The unique identifier of the execution.</param>
+    /// <param name="stateId">The identifier of the target state.</param>
+    /// <param name="duration">The execution duration.</param>
+    /// <returns>A configured <see cref="MutationHistoryEntry"/>.</returns>
+    public static MutationHistoryEntry CreateHistoryEntry<TState>(
+        IMutation<TState> mutation,
+        MutationResult<TState> result,
+        string executionId,
+        string stateId,
+        TimeSpan duration)
+    {
+        return new MutationHistoryEntry
+        {
+            ExecutionId = executionId,
+            StateId = stateId,
+            Intent = mutation.Intent,
+            Context = mutation.Context,
+            Changes = result.Changes,
+            SideEffects = result.SideEffects.ToList(),
+            Timestamp = mutation.Context.Timestamp,
+            ExecutionTime = duration
+        };
+    }
+
+    /// <summary>
+    /// Resolves the state identifier from the mutation context.
+    /// </summary>
+    /// <param name="context">The mutation context.</param>
+    /// <returns>The resolved state ID or correlation ID.</returns>
+    public static string? ResolveStateId(MutationContext context) =>
+        context.StateId ?? context.CorrelationId;
+
+    /// <summary>
+    /// Helper method to create a mutation audit entry.
+    /// </summary>
+    private static MutationAuditEntry Create<TState>(
+        IMutation<TState> mutation,
+        string executionId,
+        TimeSpan duration,
+        bool isSuccess,
+        ChangeSet? changes = null,
+        string? errorMessage = null,
+        IReadOnlyList<PolicyDecision>? policyDecisions = null,
+        IReadOnlyList<SideEffect>? sideEffects = null,
+        string? sourceIpAddress = null,
+        string? userAgent = null)
+    {
+        return new MutationAuditEntry
+        {
+            ExecutionId = executionId,
+            StateId = ResolveStateId(mutation.Context),
+            StateType = typeof(TState).Name,
+            MutationIntent = mutation.Intent,
+            Context = mutation.Context,
+            Changes = changes ?? ChangeSet.Empty,
+            IsSuccess = isSuccess,
+            ErrorMessage = errorMessage,
+            PolicyDecisions = policyDecisions ?? [],
+            SideEffects = sideEffects ?? [],
+            Timestamp = mutation.Context.Timestamp,
+            Duration = duration,
+            SourceIpAddress = sourceIpAddress,
+            UserAgent = userAgent
+        };
+    }
+}

src/Runtime/Diagnostics/StateSizeEstimator.cs

@@ -0,0 +1,73 @@
+using System.Collections;
+using System.Text;
+
+namespace ModularityKit.Mutator.Runtime.Diagnostics;
+
+/// <summary>
+/// Provides a best-effort estimate of the in-memory size of a state object in bytes.
+/// </summary>
+internal static class StateSizeEstimator
+{
+    private static readonly IReadOnlyDictionary<Type, int> PrimitiveTypeSizes = new Dictionary<Type, int>
+    {
+        [typeof(bool)] = sizeof(bool),
+        [typeof(byte)] = sizeof(byte),
+        [typeof(sbyte)] = sizeof(sbyte),
+        [typeof(char)] = sizeof(char),
+        [typeof(short)] = sizeof(short),
+        [typeof(ushort)] = sizeof(ushort),
+        [typeof(int)] = sizeof(int),
+        [typeof(uint)] = sizeof(uint),
+        [typeof(long)] = sizeof(long),
+        [typeof(ulong)] = sizeof(ulong),
+        [typeof(float)] = sizeof(float),
+        [typeof(double)] = sizeof(double),
+        [typeof(decimal)] = sizeof(decimal),
+        [typeof(Guid)] = 16
+    };
+
+    /// <summary>
+    /// Estimates the size of the given state in bytes.
+    /// </summary>
+    /// <param name="state">The state object to estimate. Can be <see langword="null" />.</param>
+    /// <returns>
+    /// The estimated byte size: UTF-8 byte count for strings, byte length for primitive arrays,
+    /// element count for collections, or <c>0</c> for unrecognized or null values.
+    /// </returns>
+    public static long Estimate(object? state)
+    {
+        if (state is null)
+            return 0;
+
+        if (state is string text)
+            return Encoding.UTF8.GetByteCount(text);
+
+        if (TryEstimateArraySize(state, out var arraySize))
+            return arraySize;
+
+        return state is ICollection collection ? collection.Count : 0;
+    }
+
+    /// <summary>
+    /// Attempts to estimate the byte size of a primitive array.
+    /// </summary>
+    /// <param name="state">The object to inspect.</param>
+    /// <param name="sizeInBytes">When successful, contains the estimated byte size of the array.</param>
+    /// <returns><see langword="true" /> if <paramref name="state" /> is a primitive array with a known element size; otherwise <see langword="false" />.</returns>
+    private static bool TryEstimateArraySize(object state, out long sizeInBytes)
+    {
+        sizeInBytes = 0;
+        if (state is not Array array)
+            return false;
+
+        var elementType = state.GetType().GetElementType();
+        if (elementType is null)
+            return false;
+
+        if (!PrimitiveTypeSizes.TryGetValue(elementType, out var elementSize))
+            return false;
+
+        sizeInBytes = array.LongLength * elementSize;
+        return true;
+    }
+}