docs: document economic event pipeline

docs/ECONOMIC_EVENTS.md

@@ -0,0 +1,53 @@
+# The Steward — Economic Event Stream
+
+## Current contract
+
+Every successful food movement creates one `EconomicEventRecord`:
+
+```text
+resource_extracted
+storage_deposited
+storage_withdrawn
+item_consumed
+```
+
+Each record contains a monotonically increasing event ID, event type,
+simulation tick, actor ID, source ID, destination ID, item ID, and transferred
+amount. Actor `-1` identifies a player-triggered extraction until persistent
+player identity is introduced.
+
+Events are immutable facts about completed transfers. They do not perform the
+transaction and are not replayed to reconstruct current state. Resource,
+inventory, and storage records remain authoritative.
+
+## Persistence and determinism
+
+`SimulationStateRecord` schema v3 stores the ordered event stream and
+`next_event_id`. Schema v1 and v2 saves migrate to an empty stream beginning at
+ID zero. Parsing rejects duplicate event IDs and a next ID that could collide
+with restored history.
+
+The food-loop regression verifies this chain:
+
+```text
+bush -> NPC inventory -> village pantry -> NPC inventory -> consumed
+```
+
+It checks event order, stable IDs, exact quantities, conservation, and
+save/restore continuity.
+
+## Presentation
+
+`npc_inventory_changed` is a transient presentation signal. The active
+`NpcVisual` shows a small food sack whenever its authoritative inventory
+contains food. A newly loaded visual derives the same state directly from the
+NPC record, so unloading presentation does not lose the fact.
+
+## Deliberate limits
+
+The stream is currently kept in full for the small simulation garden. Before
+large populations or long-running worlds, add measured retention,
+archival/summary rules, and query indexes. Denied attempts, depletion,
+witnesses, secrecy, causal links, and memories belong in later event/history
+slices; they should extend this record family without making prose
+authoritative.