inxilpro · January 20, 2026 18:12 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026
diff --git a/chronicle-demo.md b/chronicle-demo.md
@@ -17,7 +17,7 @@ The current approach to state reconstitution in Verbs is brittle—it relies on
 
 ## Next Steps
 
-- [x] Investigate the codebase to document all places where replay/reconstitution behavior needs refactoring
+- [ ] Investigate the codebase to document all places where replay/reconstitution behavior needs refactoring
 - [ ] Design the interface for a base `Replay` class
 - [ ] Create scaffolding for the Replay class
 - [ ] Revisit the interdependent state sync problem once the extraction is complete

diff --git a/chronicle-demo.md b/chronicle-demo.md
@@ -17,7 +17,7 @@ The current approach to state reconstitution in Verbs is brittle—it relies on
 
 ## Next Steps
 
-- [ ] Investigate the codebase to document all places where replay/reconstitution behavior needs refactoring
+- [x] Investigate the codebase to document all places where replay/reconstitution behavior needs refactoring
 - [ ] Design the interface for a base `Replay` class
 - [ ] Create scaffolding for the Replay class
 - [ ] Revisit the interdependent state sync problem once the extraction is complete

diff --git a/chronicle-demo.md b/chronicle-demo.md
@@ -0,0 +1,27 @@
+# Extract a Replay Class to Encapsulate Event Reconstitution
+
+The current approach to state reconstitution in Verbs is brittle—it relies on the StateManager tracking whether it's in a "replaying" state, then branching behavior accordingly. This creates coupling issues and edge cases when states trigger loading of other states during reconstitution. We need a cleaner abstraction that encapsulates replay operations.
+
+## Overview
+
+- **Core problem**: StateManager's singleton state handling doesn't cleanly separate normal operation from replay/reconstitution, leading to scattered `is_replaying` checks and potential sync issues
+- **Key file**: `src/Lifecycle/StateManager.php` — particularly around line 192 where `if (! $this->is_replaying)` gates behavior
+- **Edge case to address**: When reconstituting state A triggers loading of state B, state B also reconstitutes and can get out of sync in memory if the two states are interdependent
+- **Branch**: `generics`
+
+## Decisions
+
+- The solution is a new `Replay` class that encapsulates the operation of replaying events—whether for reconstitution or explicit replay
+- This will eliminate the need for `is_replaying` checks scattered through StateManager
+- The interdependent state sync issue is acknowledged but not yet solved; extracting the Replay class is the prerequisite first step
+
+## Next Steps
+
+- [ ] Investigate the codebase to document all places where replay/reconstitution behavior needs refactoring
+- [ ] Design the interface for a base `Replay` class
+- [ ] Create scaffolding for the Replay class
+- [ ] Revisit the interdependent state sync problem once the extraction is complete
+
+## Notes
+
+The state sync issue (states getting out of sync during cascading reconstitution) only manifests with unusual state patterns, but should still be accounted for in the final design.
No results found