docs: mark action separation phase complete

2026-07-05 14:17:57 +02:00
parent 4673f0698d
commit 4f9dc842fd
8 changed files with 127 additions and 40 deletions
@@ -0,0 +1,78 @@
+# The Steward — Action System Architecture
+
+## Current flow
+
+```text
+SimulationManager tick
+    -> ActionExecutionSystem advances needs and working progress
+    -> ActionSelectionSystem chooses an action when the NPC is idle
+    -> SimulationManager stores the selected action
+    -> npc_target_requested
+    -> WorldViewManager supplies the active visual's current position
+    -> ActionTargetResolver consumes simulation state + ActiveWorldAdapter facts
+    -> SimulationManager stores/reserves the target
+    -> npc_travel_requested
+    -> WorldViewManager commands NpcVisual travel
+    -> arrival/navigation failure returns to SimulationManager
+```
+
+## Responsibilities
+
+### ActionSelectionSystem
+
+- 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;
+- does not mutate targets, navigation, or visuals.
+
+### ActionExecutionSystem
+
+- advances hunger, energy, starvation, death, and working progress;
+- marks an action complete when its duration elapses;
+- does not select the next action or resolve a target.
+
+### ActionTargetResolver
+
+- reads target metadata from ActionDefinition;
+- consumes active-world facts through ActiveWorldAdapter;
+- checks simulation-owned ResourceStateRecord availability;
+- reserves and returns stable resource target IDs;
+- returns activity or wander positions without owning presentation.
+
+### ActiveWorldAdapter
+
+- exposes loaded resource interaction positions;
+- maps current temporary activity markers to action IDs;
+- contains active-world query facts, not persistent mutable authority;
+- does not choose actions or reserve resources.
+
+### WorldViewManager
+
+- spawns and tracks NpcVisual instances;
+- supplies a visual's current position when resolution is requested;
+- applies travel commands;
+- reports arrival, navigation failure, and visual death state;
+- does not map actions, select targets, write target IDs, or mutate resources.
+
+### SimulationManager
+
+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.
+Further decomposition should follow measured pressure rather than splitting it
+into managers for their own sake.
+
+## Remaining architecture-gate gap
+
+The resolver currently asks WorldViewManager for a visual's position at target
+request time. SimNPC also stores a position, but active movement is not yet
+synchronized back through an explicit authority contract.
+
+The next phase must:
+
+- define when active position is written to simulation state;
+- preserve the last authoritative position when a visual unloads;
+- spawn a reloaded visual from that position;
+- prove visual unload/reload does not change action, target, reservation, or
+  position state.