docs: document simulation readability layer

2026-07-05 23:50:29 +02:00
parent d883148132
commit 58d3573965
5 changed files with 27 additions and 10 deletions
@@ -23,7 +23,8 @@ SimulationManager tick
 - reads NPC and village state;
 - evaluates current utility scores;
 - consumes the NPC's deterministic decision RNG;
- returns an action ID and optional urgent-duration override;
+- returns an action ID, optional urgent-duration override, branch reason, and
+  compared utility scores;
 - does not mutate targets, navigation, or visuals.

 ### ActionExecutionSystem
@@ -60,6 +61,8 @@ SimulationManager tick
 SimulationManager remains the orchestrator and event boundary. It owns
 simulation records, invokes the focused systems, stores selected actions and
 targets, and translates presentation callbacks into simulation transitions.
+It also publishes the latest `ActionSelectionResult` for presentation; the UI
+does not recompute decisions.
 Further decomposition should follow measured pressure rather than splitting it
 into managers for their own sake.