# 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.

## Active-position contract

NpcVisual emits active position changes after successful movement.
WorldViewManager forwards those facts through
`SimulationManager.synchronize_npc_position()`. Arrival, navigation failure,
and visual unload also perform a final synchronization.

SimNPC stores both authoritative position and the resolved travel destination.
The destination is versioned simulation state, so reloading a visual resumes
the same route request without rerolling wander, resolving another resource, or
changing a reservation.

`tests/npc_visual_lifecycle_test.gd` proves that visual unload/reload preserves
action, target ID, travel destination, resource reservation, position, and
state checksum.

Unloaded NPCs do not yet resolve abstract travel time; they remain in their
current task state until an active visual or a future simulation-LOD travel
system advances them.
