# ADR 0001: Serializable simulation state is authoritative

- **Status:** Accepted
- **Date:** 2026-07-04

## Context

The prototype correctly separates `SimNPC` from `NpcVisual`, but authority is
still split across simulation records and scene nodes:

- `ResourceNode` owns remaining amount and reservations;
- `WorldViewManager` resolves targets and writes the chosen target ID onto an
  NPC;
- `SimulationManager` combines time, orchestration, action completion, player
  commands, and event publication;
- the visual position of an active NPC can diverge from its stored simulation
  position.

This is workable for one loaded flat map. It does not support reliable
save/load, unloaded locations, deterministic replay, simulation fidelity
changes, or a large data-only population.

## Decision

Persistent mutable gameplay state will move into versioned, serializable
records owned by a `WorldState`-style simulation model.

- Definitions contain immutable action, profession, need, item, and location
  data.
- State records contain people, resources, inventories, reservations,
  locations, current actions, and later relationships and history.
- Systems are the only layer that authoritatively mutates those records.
- Godot world nodes present records and provide active-world facts such as
  interaction transforms, navigation results, collision, and animation.
- Presentation adapters may submit commands and query results, but may not
  choose actions or directly author persistent state.
- References between records use stable IDs, never `Node`, `NodePath`, or scene
  ownership.
- Active-world position must synchronize through an explicit adapter so
  unloading a visual does not erase or redefine the NPC's location.

The simulation core must be runnable headlessly with a fixed clock, controlled
random streams, and no dependency on a loaded gameplay scene.

## Staged migration

1. ✅ Add a deterministic clock, seeded random source, and scenario runner.
2. ✅ Introduce serializable village, NPC, and resource-state records.
3. ✅ Bind `ResourceNode` presentation to resource records instead of owning
   authoritative amount and reservation.
4. ✅ Move target choice and reservation coordination out of
   `WorldViewManager` into an action/target system with an active-world query
   adapter.
5. ✅ Split action selection, execution, and presentation travel.
6. ✅ Synchronize active position and prove visual unload/reload
   invariance.
7. Add save-slot persistence before schedules or relationships
   substantially expand mutable state.

Schema v1 and its deterministic continuation contract are documented in
[the simulation state schema](../SIMULATION_STATE_SCHEMA.md).
Stable action/profession identity and immutable metadata are documented in
[the simulation definitions](../SIMULATION_DEFINITIONS.md).
System responsibilities and event flow are documented in
[the action system architecture](../ACTION_SYSTEM_ARCHITECTURE.md).

## Consequences

- Some current prototype APIs are transitional and should not be generalized
  as final architecture.
- The Jajce scaffold may proceed far enough to validate terrain, navigation,
  and world-object placement, but beauty production pauses at the architecture
  gate.
- New persistent features must define their state record and save behavior.
- Headless scenarios become the preferred regression surface for simulation
  rules.

## Revisit when

Revisit this decision only if measured prototype work shows that a different
authority model materially simplifies deterministic persistence and simulation
LOD without coupling rules to loaded scenes.