gamedev-the-steward/docs/decisions/0001-simulation-authority-boundary.md

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. Next: Synchronize active position and prove visual unload/reload invariance.
7. Add versioned save/load before inventories, schedules, or relationships substantially expand mutable state.

Schema v1 and its deterministic continuation contract are documented in the simulation state schema. Stable action/profession identity and immutable metadata are documented in the simulation definitions. System responsibilities and event flow are documented in the action system architecture.

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.