chronicle-demo.md

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.