diff --git a/Elsa.sln b/Elsa.sln index d171f43ce..a5cad563a 100644 --- a/Elsa.sln +++ b/Elsa.sln @@ -391,6 +391,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "adr", "adr", "{0A04B1FD-06C doc\adr\toc.md = doc\adr\toc.md doc\adr\graph.dot = doc\adr\graph.dot doc\adr\0003-direct-bookmark-management-in-workflowexecutioncontext.md = doc\adr\0003-direct-bookmark-management-in-workflowexecutioncontext.md + doc\adr\0004-activity-execution-snapshots.md = doc\adr\0004-activity-execution-snapshots.md EndProjectSection EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "bounty", "bounty", "{9B80A705-2E31-4012-964A-83963DCDB384}" diff --git a/doc/adr/0004-activity-execution-snapshots.md b/doc/adr/0004-activity-execution-snapshots.md new file mode 100644 index 000000000..f0ff79902 --- /dev/null +++ b/doc/adr/0004-activity-execution-snapshots.md @@ -0,0 +1,28 @@ +# 4. Activity Execution Snapshots + +**Date:** 2025-08-04 +**Status:** Accepted + +## Context + +Today the `ActivityExecutionContext` is persisted only at *commit points*. +If an activity references a workflow variable that changes after it has run—but before the next commit—the value saved is the *later* value, not the one that existed when the activity executed. +As a result, the Workflow Instance Viewer shows misleading data: users expect to see the variable values *at execution time*, not at commit time. + +## Decision + +Capture a **snapshot** of the `ActivityExecutionContext` immediately when an activity executes. +The snapshot must include: + +* All workflow variables and their values at that moment. +* Any other execution-specific metadata required for replay or inspection. + +The snapshot is created by serializing the `ActivityExecutionRecord` to JSON and storing it in the database. +The persistence layer will be updated to handle this new snapshot field, ensuring it is stored alongside the activity execution record. + +## Consequences + +* The Workflow Instance Viewer will now display the exact state that the activity saw, eliminating confusion during debugging and auditing. +* Additional storage will be consumed for each snapshot. We accept this overhead in exchange for correctness and developer experience. +* Existing persistence schemas will require a non-breaking migration to store the snapshot payload. +* Workflow instances before this change will not have snapshots, but they will still be replayable even if the variable values are not accurate at execution time. \ No newline at end of file diff --git a/doc/adr/graph.dot b/doc/adr/graph.dot index 0e66155fa..61e1e6f7c 100644 --- a/doc/adr/graph.dot +++ b/doc/adr/graph.dot @@ -1,10 +1,12 @@ digraph { - node [shape=plaintext]; - subgraph { - _1 [label="1. Record architecture decisions"; URL="0001-record-architecture-decisions.html"]; - _2 [label="2. Fault Propagation from Child to Parent Activities"; URL="0002-fault-propagation-from-child-to-parent-activities.html"]; - _1 -> _2 [style="dotted", weight=1]; - _3 [label="3. Direct Bookmark Management in WorkflowExecutionContext"; URL="0003-direct-bookmark-management-in-workflowexecutioncontext.html"]; - _2 -> _3 [style="dotted", weight=1]; - } +node [shape = plaintext]; +subgraph { +_1 [label = "1. Record architecture decisions"; URL = "0001-record-architecture-decisions.html"]; +_2 [label = "2. Fault Propagation from Child to Parent Activities"; URL ="0002-fault-propagation-from-child-to-parent-activities.html"]; +_1 -> _2 [style= "dotted", weight = 1]; +_3 [label = "3. Direct Bookmark Management in WorkflowExecutionContext"; URL = "0003-direct-bookmark-management-in-workflowexecutioncontext.html"]; +_2 -> _3 [style = "dotted", weight = 1]; +_4 [label ="4. Activity Execution Snapshots"; URL = "0004-activity-execution-snapshots.html"]; +_3 -> _4 [style = "dotted", weight = 1]; } +} \ No newline at end of file diff --git a/doc/adr/toc.md b/doc/adr/toc.md index e5c8dac8d..7eecf8af6 100644 --- a/doc/adr/toc.md +++ b/doc/adr/toc.md @@ -2,4 +2,5 @@ * [1. Record architecture decisions](0001-record-architecture-decisions.md) * [2. Fault Propagation from Child to Parent Activities](0002-fault-propagation-from-child-to-parent-activities.md) -* [3. Direct Bookmark Management in WorkflowExecutionContext](0003-direct-bookmark-management-in-workflowexecutioncontext.md) \ No newline at end of file +* [3. Direct Bookmark Management in WorkflowExecutionContext](0003-direct-bookmark-management-in-workflowexecutioncontext.md) +* [4. Activity Execution Snapshots](0004-activity-execution-snapshots.md) \ No newline at end of file