docs: document economic event pipeline

docs/SIMULATION_STATE_SCHEMA.md

@@ -3,7 +3,7 @@
 ## Current contract
 
 `SimulationStateRecord` is the versioned JSON boundary for the current
-simulation. Schema v1 captures:
+simulation. The current world schema is v3 and captures:
 
 - simulation seed, tick interval, tick count, clock remainder, and elapsed
   clock ticks;
@@ -13,13 +13,15 @@ simulation. Schema v1 captures:
 - controlled per-NPC wander RNG streams;
 - scene-independent resource state plus the definition facts needed while its
   ResourceNode is unloaded.
+- pantry contents, carried NPC inventory, the ordered economic event stream,
+  and its next stable event ID.
 
 The top-level identity is:
 
 ```json
 {
   "schema": "the_steward.simulation",
-  "schema_version": 1
+  "schema_version": 3
 }
 ```
 
@@ -62,6 +64,12 @@ StorageStateRecord entries; world-schema v1 migrates legacy village food into
 the stable `village_pantry` record. Parsed storage values are canonicalized so
 save/restore continuation retains byte-stable checksums.
 
+SimulationStateRecord v3 adds ordered `EconomicEventRecord` entries and
+`next_event_id`. World schemas v1 and v2 migrate explicitly to an empty event
+stream. Event records use stable source/destination/item IDs, reject invalid or
+duplicate IDs, and preserve deterministic ordering across save/restore. See
+[the economic event stream](ECONOMIC_EVENTS.md).
+
 ## Resource authority
 
 `SimulationManager` owns `ResourceStateRecord` instances independently of the
@@ -84,8 +92,8 @@ definition from a matching presentation node when one becomes available.
 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;
+- migrations older than the explicitly supported world schemas v1 and v2;
+- player inventory, relationship, schedule, or social-memory records;
 - a player-facing load flow;
 - save-slot persistence for scene-independent resource state.