Implementation Plan: Command-Dispatch Architecture

J. Rogers, SE Ohio

Objective: Evolve the current input-to-action dispatch into a robust Command Pipeline. This will enable Undo/Redo, automated testing, and network synchronization by treating all application state changes as serializable data.

---

Phase 1: Command Formalization

Target: Convert loose action dictionaries into immutable Command objects.

1. Define the Command Class: Create codex_engine/core/command.py.

   • Fields: id (UUID), timestamp, action (str), data (dict), inverse_data (dict/optional).

2. Controller Update: Update all _handle_action methods to return or accept Command objects.

3. Refactor 

   • Change from simple dictionary lookup to a pipeline:

     • Pre-process: Inject metadata (timestamp, user_id).

     • Validation: Check if action is valid for self.state.

     • Execution: Invoke handler.

     • Post-process: Push to CommandHistory and UndoStack.

Phase 2: Undo/Redo Stack

Target: Enable non-destructive state manipulation.

1. UndoStack Implementation:

   • Add self.undo_stack = [] and self.redo_stack = [] to CampaignManager.

2. Inversion Strategy:

   • Update controllers to provide an "inverse" for state-mutating actions (e.g., move_marker inverse is move_marker to original (x, y)).

   • When a Command is executed, package the current state as inverse_data.

3. Global Key Binding:

   • Map Ctrl+Z to CampaignManager.undo() and Ctrl+Y to CampaignManager.redo().

   • undo() pops the stack, executes the inverse command, and pushes the original to redo_stack.

Phase 3: Serialization & Replay Harness

Target: Enable automated testing and persistent event logs.

1. Serialization Layer:

   • Implement Command.to_json() and Command.from_json().

2. Headless Test Harness:

   • Create tests/harness.py:

     • Initialize CodexApp with pygame in headless mode (no window).

     • Add a MockInputProvider that reads a JSON file of Command objects.

     • Inject commands into CampaignManager._handle_action.

3. State Validation:

   • Add assert_state(node_id, property_key, expected_value) to the harness to verify controller outputs after specific command sequences.

Phase 4: Network Synchronization (Async Actions)

Target: Enable remote collaboration.

1. Queue-to-Network Bridge:

   • In main.py, create a CommandBridge that sits between the multiprocessing.Queue and the FastAPI server.

2. Broadcast Protocol:

   • When CampaignManager executes a local Command, emit it to the CommandBridge.

   • Bridge broadcasts the JSON-serialized Command via WebSockets to all connected clients.

3. Remote Execution:

   • Remote instances listen for the packet and call _handle_action(Command.from_json(packet)).

   • Constraint: Ensure all generation IDs are synchronized; use the DBManager as the source of truth for all node references.

---

Implementation Roadmap

Priority	Feature	Complexity	Dependency
High	Command Class & Dispatch Pipeline	Medium	None
High	HistoryStack (Audit Log)	Low	Pipeline
Medium	Undo/Redo Logic in Controllers	High	HistoryStack
Medium	CLI Test Harness	Medium	Serialization
Low	Network Sync (Broadcast)	High	HistoryStack

Success Metrics

• Decoupling: TacticalController and GeoController should have zero knowledge of how an action is stored or undone; they only provide the "how-to-execute" logic.

• Determinism: Running the same sequence of commands in the test harness must result in an identical codex.db state every time.

• Performance: UI interactions must remain frame-locked; dispatching a command must remain an 

  $O(1)$

   operation to ensure no input lag.