docs: mark simulation state phase complete

docs/SIMULATION_STATE_SCHEMA.md

@@ -0,0 +1,70 @@
+# 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.