# The Steward — Simulation State Schema

## Current contract

`SimulationStateRecord` is the versioned JSON boundary for the current
simulation. Schema v1 captures:

- simulation seed, tick interval, tick count, clock remainder, and elapsed
  clock ticks;
- every NPC's identity, needs, attributes, task lifecycle, target, position,
  starvation state, and decision RNG stream;
- village resource counters;
- controlled per-NPC wander RNG streams;
- loaded ResourceNode amount, reservation, and enabled state.

The top-level identity is:

```json
{
  "schema": "the_steward.simulation",
  "schema_version": 1
}
```

Unknown schema versions and structurally incomplete records are rejected. Add
an explicit migration function before accepting a future version; never
silently reinterpret old data as the newest layout.

## Deterministic continuation

RNG seeds and internal states are encoded as decimal strings. They are signed
64-bit values and cannot safely pass through every JSON number implementation
without precision loss. Converting them to ordinary JSON numbers caused a
restored simulation to retain the same visible state while silently changing
its future random sequence.

`tests/simulation_state_serialization_test.gd` protects this contract by:

1. running a fixed-seed scenario for 48 ticks without interruption;
2. running the same scenario for 24 ticks;
3. serializing and restoring into a fresh manager;
4. running the remaining 24 ticks;
5. requiring the complete final-state checksums to match.

It also verifies clock remainder, ResourceNode amount/reservation/enabled
round-tripping, and rejection of unsupported schemas.

## Transitional resource boundary

Schema v1 can capture and restore loaded `ResourceNode` state, but the scene
node still owns the live amount and reservation. That is transitional support,
not the final authority model.

The next architecture-gate phase moves those values into scene-independent
resource records. ResourceNode will then bind to a record by stable ID and act
as presentation plus an active-world interaction surface. An unloaded resource
must remain simulated and serializable.

## Deliberately out of scope

This phase does not yet provide:

- save-slot files, metadata, thumbnails, or atomic disk writes;
- backward migrations beyond schema v1;
- inventory, relationship, schedule, or history records;
- a player-facing load flow;
- scene-independent resource authority.

Those features should build on this boundary rather than inventing parallel
serialization paths.