feat(core): add typed side effect contracts

rian-be · rian-be · commit b2d61d4d16a4 · 2026-06-30T01:32:02.000+02:00
diff --git a/src/Abstractions/Effects/SideEffect.cs b/src/Abstractions/Effects/SideEffect.cs
@@ -1,9 +1,12 @@
+using System.Text.Json.Serialization;
+
 namespace ModularityKit.Mutator.Abstractions.Effects;
 
 /// <summary>
 /// Represents a side effect produced by a mutation.
 /// Side effects capture additional consequences that are not part of the primary state change.
 /// </summary>
+[JsonConverter(typeof(SideEffectJsonConverter))]
 public sealed class SideEffect
 {
     /// <summary>
@@ -28,6 +31,16 @@ public sealed class SideEffect
     /// </summary>
     public object? Data { get; init; }
 
+    /// <summary>
+    /// Stable contract identifier for typed side effect payloads.
+    /// </summary>
+    public string? DataContractType { get; init; }
+
+    /// <summary>
+    /// Version number for typed side effect payloads.
+    /// </summary>
+    public int? DataContractVersion { get; init; }
+
     /// <summary>
     /// Timestamp when the side effect occurred.
     /// </summary>
@@ -43,7 +56,10 @@ public sealed class SideEffect
     /// </summary>
     /// <param name="type">The type of the side effect.</param>
     /// <param name="description">Human-readable description.</param>
-    /// <param name="data">Optional associated data.</param>
+    /// <param name="data">
+    /// Optional associated data. When the payload type declares <see cref="SideEffectDataContractAttribute"/>,
+    /// the side effect contract metadata is populated automatically.
+    /// </param>
     /// <param name="severity">Severity level.</param>
     /// <param name="requiresAction">
     /// Indicates whether the side effect requires explicit follow-up. Critical severity always implies action.
@@ -56,22 +72,47 @@ public static SideEffect Create(
         SideEffectSeverity severity = SideEffectSeverity.Info,
         bool requiresAction = false,
         DateTimeOffset? timestamp = null)
-        => new()
-        {
-            Type = type,
-            Description = description,
-            Data = data,
-            Severity = severity,
-            RequiresAction = requiresAction || severity == SideEffectSeverity.Critical,
-            Timestamp = timestamp ?? DateTimeOffset.UtcNow
-        };
+        => CreateCore(
+            type,
+            description,
+            data,
+            severity,
+            requiresAction,
+            timestamp);
+
+    /// <summary>
+    /// Creates a new <see cref="SideEffect"/> with a typed payload contract.
+    /// </summary>
+    /// <typeparam name="TData">The payload type.</typeparam>
+    /// <param name="type">The type of the side effect.</param>
+    /// <param name="description">Human-readable description.</param>
+    /// <param name="data">Typed associated payload.</param>
+    /// <param name="severity">Severity level.</param>
+    /// <param name="requiresAction">
+    /// Indicates whether the side effect requires explicit follow-up. Critical severity always implies action.
+    /// </param>
+    /// <param name="timestamp">Optional timestamp override. Defaults to current UTC time.</param>
+    public static SideEffect Create<TData>(
+        string type,
+        string description,
+        TData data,
+        SideEffectSeverity severity = SideEffectSeverity.Info,
+        bool requiresAction = false,
+        DateTimeOffset? timestamp = null)
+    {
+        ArgumentNullException.ThrowIfNull(data);
+        return CreateCore(type, description, data, severity, requiresAction, timestamp);
+    }
 
     /// <summary>
     /// Creates a new critical <see cref="SideEffect"/> instance.
     /// </summary>
     /// <param name="type">The type of the side effect.</param>
     /// <param name="description">Human-readable description.</param>
-    /// <param name="data">Optional associated data.</param>
+    /// <param name="data">
+    /// Optional associated data. When the payload type declares <see cref="SideEffectDataContractAttribute"/>,
+    /// the side effect contract metadata is populated automatically.
+    /// </param>
     /// <param name="timestamp">Optional timestamp override. Defaults to current UTC time.</param>
     public static SideEffect Critical(
         string type,
@@ -85,4 +126,83 @@ public static SideEffect Critical(
             SideEffectSeverity.Critical,
             requiresAction: true,
             timestamp: timestamp);
+
+    /// <summary>
+    /// Creates a new critical <see cref="SideEffect"/> instance with a typed payload contract.
+    /// </summary>
+    /// <typeparam name="TData">The payload type.</typeparam>
+    /// <param name="type">The type of the side effect.</param>
+    /// <param name="description">Human-readable description.</param>
+    /// <param name="data">Typed associated payload.</param>
+    /// <param name="timestamp">Optional timestamp override. Defaults to current UTC time.</param>
+    public static SideEffect Critical<TData>(
+        string type,
+        string description,
+        TData data,
+        DateTimeOffset? timestamp = null)
+        => Create(
+            type,
+            description,
+            data,
+            SideEffectSeverity.Critical,
+            requiresAction: true,
+            timestamp: timestamp);
+
+    /// <summary>
+    /// Attempts to read the side effect payload as a typed contract.
+    /// </summary>
+    /// <typeparam name="TData">The expected payload type.</typeparam>
+    /// <param name="data">The typed payload when available.</param>
+    /// <returns><see langword="true"/> when the payload is available as <typeparamref name="TData"/>.</returns>
+    public bool TryGetData<TData>(out TData? data)
+    {
+        if (Data is TData typed)
+        {
+            data = typed;
+            return true;
+        }
+
+        data = default;
+        return false;
+    }
+
+    private static SideEffect CreateCore(
+        string type,
+        string description,
+        object? data,
+        SideEffectSeverity severity,
+        bool requiresAction,
+        DateTimeOffset? timestamp)
+    {
+        var (contractType, contractVersion) = ResolveContract(data);
+
+        return new SideEffect
+        {
+            Type = type,
+            Description = description,
+            Data = data,
+            Severity = severity,
+            RequiresAction = requiresAction || severity == SideEffectSeverity.Critical,
+            Timestamp = timestamp ?? DateTimeOffset.UtcNow,
+            DataContractType = contractType,
+            DataContractVersion = contractVersion
+        };
+    }
+
+    private static (string? ContractType, int? ContractVersion) ResolveContract(object? data)
+    {
+        if (data is null)
+            return (null, null);
+
+        var dataType = data.GetType();
+        var contract = dataType.GetCustomAttributes(typeof(SideEffectDataContractAttribute), inherit: false)
+            .OfType<SideEffectDataContractAttribute>()
+            .SingleOrDefault();
+
+        if (contract is null)
+            return (null, null);
+
+        SideEffectDataContractRegistry.Register(dataType);
+        return (contract.ContractType, contract.ContractVersion);
+    }
 }
diff --git a/src/Abstractions/Effects/SideEffectDataContractAttribute.cs b/src/Abstractions/Effects/SideEffectDataContractAttribute.cs
@@ -0,0 +1,22 @@
+namespace ModularityKit.Mutator.Abstractions.Effects;
+
+/// <summary>
+/// Declares stable contract identifier for typed side effect payloads.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, Inherited = false)]
+public sealed class SideEffectDataContractAttribute(string contractType, int contractVersion = 1) : Attribute
+{
+    /// <summary>
+    /// Stable contract identifier for the payload.
+    /// </summary>
+    public string ContractType { get; } = string.IsNullOrWhiteSpace(contractType)
+        ? throw new ArgumentException("Contract type is required.", nameof(contractType))
+        : contractType;
+
+    /// <summary>
+    /// Version number for the payload contract.
+    /// </summary>
+    public int ContractVersion { get; } = contractVersion > 0
+        ? contractVersion
+        : throw new ArgumentOutOfRangeException(nameof(contractVersion), "Contract version must be greater than zero.");
+}
diff --git a/src/Abstractions/Effects/SideEffectDataContractRegistry.cs b/src/Abstractions/Effects/SideEffectDataContractRegistry.cs
@@ -0,0 +1,74 @@
+using System.Collections.Concurrent;
+
+namespace ModularityKit.Mutator.Abstractions.Effects;
+
+/// <summary>
+/// Stores registrations that map side effect payload contracts to CLR types.
+/// Registered types allow serializers and integration layers to rehydrate typed payloads
+/// from stable contract identifiers instead of inferring payload shape at runtime.
+/// </summary>
+public static class SideEffectDataContractRegistry
+{
+    private static readonly ConcurrentDictionary<(string ContractType, int ContractVersion), Type> TypesByContract = new();
+
+    /// <summary>
+    /// Registers typed side effect payload contract.
+    /// </summary>
+    /// <typeparam name="TData">The payload type to register.</typeparam>
+    public static void Register<TData>()
+        => Register(typeof(TData));
+
+    /// <summary>
+    /// Registers typed side effect payload contract.
+    /// </summary>
+    /// <param name="dataType">The payload type to register.</param>
+    public static void Register(Type dataType)
+    {
+        ArgumentNullException.ThrowIfNull(dataType);
+
+        var contract = GetRequiredContract(dataType);
+        TypesByContract[(contract.ContractType, contract.ContractVersion)] = dataType;
+    }
+
+    /// <summary>
+    /// Attempts to resolve payload CLR type from side effect data contract.
+    /// </summary>
+    /// <param name="contractType">The stable contract identifier.</param>
+    /// <param name="contractVersion">The contract version.</param>
+    /// <param name="dataType">The resolved CLR type when present.</param>
+    /// <returns><see langword="true"/> when the contract is registered; otherwise <see langword="false"/>.</returns>
+    public static bool TryResolve(string contractType, int contractVersion, out Type? dataType)
+    {
+        if (string.IsNullOrWhiteSpace(contractType) || contractVersion <= 0)
+        {
+            dataType = null;
+            return false;
+        }
+
+        return TypesByContract.TryGetValue((contractType, contractVersion), out dataType);
+    }
+
+    /// <summary>
+    /// Reads the declared side effect data contract for CLR type.
+    /// </summary>
+    /// <typeparam name="TData">The payload type.</typeparam>
+    /// <returns>The declared side effect data contract.</returns>
+    public static SideEffectDataContractAttribute GetRequiredContract<TData>()
+        => GetRequiredContract(typeof(TData));
+
+    /// <summary>
+    /// Reads the declared side effect data contract for CLR type.
+    /// </summary>
+    /// <param name="dataType">The payload type.</param>
+    /// <returns>The declared side effect data contract.</returns>
+    public static SideEffectDataContractAttribute GetRequiredContract(Type dataType)
+    {
+        ArgumentNullException.ThrowIfNull(dataType);
+
+        return dataType.GetCustomAttributes(typeof(SideEffectDataContractAttribute), inherit: false)
+            .OfType<SideEffectDataContractAttribute>()
+            .SingleOrDefault()
+            ?? throw new InvalidOperationException(
+                $"Typed side effect payload '{dataType.FullName}' must declare {nameof(SideEffectDataContractAttribute)}.");
+    }
+}
diff --git a/src/Abstractions/Effects/SideEffectJsonConverter.cs b/src/Abstractions/Effects/SideEffectJsonConverter.cs
