Rijad Zuzo
93 lines
4.3 KiB
Markdown
93 lines
4.3 KiB
Markdown
# The Steward — Economic Event Stream
|
|
|
|
## Current contract
|
|
|
|
Every successful food or wood movement creates an `EconomicEventRecord` using
|
|
the applicable event type:
|
|
|
|
```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, plus the authoritative world position captured when the fact is
|
|
recorded. NPC events preserve their authoritative interaction target (or NPC
|
|
position when no target applies); player extraction/depletion events preserve
|
|
the ResourceNode interaction position. 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.
|
|
|
|
`SimulationEventLog` owns ordered event identity, append/restore behavior, and
|
|
history/rate queries, including exact lookup through `get_by_id()`.
|
|
`VillageEconomy` performs transactions and requests event records only after
|
|
state changes succeed; `SimulationManager` remains the public signal boundary
|
|
used by presentation.
|
|
|
|
An action whose definition-backed completion cost becomes unavailable records
|
|
a zero-amount `task_blocked` narrative fact with the action and shortfall
|
|
reason. This makes late contention inspectable without pretending that a
|
|
transfer occurred.
|
|
|
|
## Persistence and determinism
|
|
|
|
`SimulationStateRecord` schema v6 stores the ordered event stream,
|
|
`next_event_id`, directed relationships that may reference an exact event, and
|
|
per-NPC known-event references with first-acquisition provenance. Schema v1 and
|
|
v2 saves migrate to an empty stream beginning at ID zero. Parsing rejects
|
|
duplicate event IDs, invalid or duplicate knowledge references, impossible
|
|
communicator sources, relationship causes the observer does not know, and a
|
|
next ID that could collide with restored history.
|
|
|
|
A successful food deposit can currently raise a hungry familiar NPC's directed
|
|
trust in its contributor only when that NPC knows the event. The actor and
|
|
living NPCs within the bounded witness radius receive a `KnownEventStateRecord`
|
|
at record time. Witness distance uses the event's captured position, never the
|
|
actor's later location. The relationship stores the same deposit event ID
|
|
rather than copied prose, so the inspector can resolve and display the real
|
|
completed fact. This is a first evidence-gated causal consumer of the event
|
|
stream, not general event sourcing.
|
|
|
|
Knowledge now records whether an NPC performed, witnessed, heard, or inherited
|
|
a fact from a legacy save. When an NPC arrives beside an already-working NPC at
|
|
the same non-storage activity site, the worker may communicate one newest
|
|
direct fact within 2.5 metres. The listener references the same immutable event
|
|
and retains the speaker ID; no transaction or event is replayed. Only
|
|
performed/witnessed facts can cross this one social hop, so this is not yet a
|
|
rumour cascade. Relationship appraisal uses the listener's state when the fact
|
|
is acquired, not a reconstruction of their needs when the old event occurred.
|
|
|
|
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. Proximity is the only current direct
|
|
witness rule, and communication is intentionally one-hop and tied to shared
|
|
activity arrival. Line of sight, hearing, acquisition timestamps, multi-hop
|
|
rumours, secrecy, false beliefs, multi-event causal graphs, and memory
|
|
retention belong in later event/history slices. They should extend this record
|
|
family without making prose authoritative or recomputing old evidence from
|
|
current positions.
|