docs(examples): demonstrate typed side effect usage

Author: rian-be

Examples/Core/WorkflowApprovals/Contracts/WorkflowRejectedSideEffectData.cs

@@ -0,0 +1,13 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+
+namespace WorkflowApprovals.Contracts;
+
+[SideEffectDataContract("workflow.rejected", 1)]
+internal sealed record WorkflowRejectedSideEffectData
+{
+    public required string Rejector { get; init; }
+
+    public required int StepCount { get; init; }
+
+    public required string State { get; init; }
+}

Examples/Core/WorkflowApprovals/Contracts/WorkflowStartedSideEffectData.cs

@@ -0,0 +1,13 @@
+using ModularityKit.Mutator.Abstractions.Effects;
+
+namespace WorkflowApprovals.Contracts;
+
+[SideEffectDataContract("workflow.started", 1)]
+internal sealed record WorkflowStartedSideEffectData
+{
+    public required string Initiator { get; init; }
+
+    public required int StepCount { get; init; }
+
+    public required string WorkflowId { get; init; }
+}

Examples/Core/WorkflowApprovals/Mutations/RejectWorkflowMutation.cs

@@ -4,6 +4,7 @@
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.Contracts;
 using WorkflowApprovals.State;
 
 namespace WorkflowApprovals.Mutations;
@@ -48,9 +49,9 @@ public override MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowStat
                 SideEffect.Critical(
                     type: "WorkflowRejected",
                     description: "Workflow rejection requires manual follow-up",
-                    data: new
+                    data: new WorkflowRejectedSideEffectData
                     {
-                        Rejector,
+                        Rejector = Rejector,
                         StepCount = steps.Count,
                         State = "Rejected"
                     })

Examples/Core/WorkflowApprovals/Mutations/StartApprovalMutation.cs

@@ -4,6 +4,7 @@
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Intent;
 using ModularityKit.Mutator.Abstractions.Results;
+using WorkflowApprovals.Contracts;
 using WorkflowApprovals.State;
 
 namespace WorkflowApprovals.Mutations;
@@ -54,9 +55,9 @@ public override MutationResult<ApprovalWorkflowState> Apply(ApprovalWorkflowStat
                 SideEffect.Create(
                     type: "WorkflowStarted",
                     description: "Approval workflow started and ready for first review",
-                    data: new
+                    data: new WorkflowStartedSideEffectData
                     {
-                        Initiator,
+                        Initiator = Initiator,
                         StepCount = steps.Count,
                         WorkflowId = newState.WorkflowId
                     })

Examples/Core/WorkflowApprovals/README.md

@@ -67,7 +67,7 @@ The sample is intentionally sequential. It shows how stateful process can be adv
 - creates workflow steps from names
 - initializes a new workflow ID
 - emits change entry for the created step list
-- emits a `WorkflowStarted` side effect through `SideEffect.Create(...)`
+- emits a `WorkflowStarted` side effect through `SideEffect.Create(...)` with a typed contract payload
 
 ### Approve step
 
@@ -85,7 +85,7 @@ The sample is intentionally sequential. It shows how stateful process can be adv
 - applies rejection to every step
 - records the actor who rejected the workflow
 - emits workflow level change
-- emits a critical `WorkflowRejected` side effect through `SideEffect.Critical(...)`
+- emits a critical `WorkflowRejected` side effect through `SideEffect.Critical(...)` with a typed contract payload
 
 ## Policies
 
@@ -135,7 +135,8 @@ It shows:
 
 - a standard side effect created with `SideEffect.Create(...)`
 - a critical side effect created with `SideEffect.Critical(...)`
-- how `Severity`, `RequiresAction`, and `Data` can be read from `MutationResult.SideEffects`
+- how typed payload contracts are registered through `SideEffectDataContractRegistry`
+- how `Severity`, `RequiresAction`, `DataContractType`, and typed `Data` can be read from `MutationResult.SideEffects`
 
 ## What to read first
 

Examples/Core/WorkflowApprovals/Scenarios/SideEffectsScenario.cs

@@ -1,6 +1,8 @@
 using ModularityKit.Mutator.Abstractions.Context;
 using ModularityKit.Mutator.Abstractions.Effects;
 using ModularityKit.Mutator.Abstractions.Engine;
+using System.Text.Json;
+using WorkflowApprovals.Contracts;
 using WorkflowApprovals.Mutations;
 using WorkflowApprovals.State;
 
@@ -12,6 +14,9 @@ internal static async Task Run(IMutationEngine engine)
     {
         Console.WriteLine("\n=== Side Effects Scenario ===");
 
+        SideEffectDataContractRegistry.Register<WorkflowStartedSideEffectData>();
+        SideEffectDataContractRegistry.Register<WorkflowRejectedSideEffectData>();
+
         var state = new ApprovalWorkflowState();
 
         var startContext = MutationContext.System("Start side effect demo", correlationId: "workflow-side-effects");
@@ -51,9 +56,25 @@ private static void PrintSideEffects(string operation, IReadOnlyList<SideEffect>
                 $"  {effect.Type} | severity={effect.Severity} | requiresAction={effect.RequiresAction}");
             Console.WriteLine($"    {effect.Description}");
 
-            if (effect.Data is not null)
+            var roundtrip = JsonSerializer.Deserialize<SideEffect>(JsonSerializer.Serialize(effect));
+
+            if (roundtrip?.TryGetData<WorkflowStartedSideEffectData>(out var started) == true)
+            {
+                Console.WriteLine(
+                    $"    contract={roundtrip.DataContractType}@v{roundtrip.DataContractVersion} | initiator={started!.Initiator} | workflowId={started.WorkflowId}");
+                continue;
+            }
+
+            if (roundtrip?.TryGetData<WorkflowRejectedSideEffectData>(out var rejected) == true)
+            {
+                Console.WriteLine(
+                    $"    contract={roundtrip.DataContractType}@v{roundtrip.DataContractVersion} | rejector={rejected!.Rejector} | state={rejected.State}");
+                continue;
+            }
+
+            if (roundtrip?.Data is not null)
             {
-                Console.WriteLine($"    data={effect.Data}");
+                Console.WriteLine($"    data={roundtrip.Data}");
             }
         }
     }

src/README.md

@@ -109,6 +109,37 @@ Core runtime concurrency is controlled by `MutationEngineOptions.MaxConcurrentMu
 - `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:
+
+```csharp
+[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