feat: add knowledge-gated pantry opportunities

docs/ECONOMIC_EVENTS.md

@@ -37,22 +37,25 @@ transfer occurred.
 
 ## Persistence and determinism
 
-`SimulationStateRecord` schema v7 stores the ordered event stream,
+`SimulationStateRecord` schema v8 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.
+per-NPC known-event references with first-acquisition provenance, plus
+opportunity records that reference exact trigger/resolution events. Schema v1
+and v2 saves migrate to an empty stream beginning at ID zero; world schemas
+v1–v7 migrate to an empty opportunity list. Parsing rejects duplicate event
+IDs, invalid or duplicate knowledge/opportunity references, impossible
+communicator sources, relationship causes the observer does not know, and next
+IDs 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.
+Positive food deposits and positive NPC food withdrawals from
+`village_pantry` into that actor's matching inventory are currently knowable.
+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. A successful food deposit
+can raise a hungry familiar witness's directed trust; the relationship stores
+that same deposit event ID rather than copied prose, so the inspector can
+resolve and display the real completed fact. This is evidence-gated use 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
@@ -72,6 +75,21 @@ evidence. Conversations prefer lasting direct facts, then the most recently
 acquired direct fact. Communicated provenance snapshots how the speaker knew
 the event, so a listener's memory stays valid after the speaker forgets.
 
+`FoodShortageOpportunitySystem` is another read-only consumer of immutable
+facts. A known positive NPC pantry withdrawal, combined with the pantry
+currently being empty and a living critically hungry knower, can open one
+`restock_empty_pantry` record. The opportunity does not perform a transaction,
+assign an NPC, or append a quest-only event. It resolves only after the pantry
+actually reaches its target through either:
+
+- a later positive `storage_deposited` event from a real NPC inventory; or
+- a later player `resource_extracted` event from an existing player-usable food
+  ResourceNode directly into `village_pantry`.
+
+The exact trigger and resolution IDs remain in opportunity history. The active
+trigger memory is protected until resolution, then returns to normal bounded
+retention.
+
 The food-loop regression verifies this chain:
 
 ```text
@@ -92,6 +110,9 @@ acquisition provenance, separately from three objective events the NPC
 personally performed. A real trust-changing consequence emits one transient
 amber blossom above its observer. The cue is presentation-only, remains visible
 in cinematic mode, and is neither saved nor replayed after visual rebuild.
+The village summary also shows one compact active need with its real food
+progress and interested villager; only that villager's inspector retains its
+open/resolved detail and names the exact supplier.
 
 ## Deliberate limits
 
@@ -104,3 +125,5 @@ hearing, personalized reinforcement/decay, multi-hop rumours, secrecy, false
 beliefs, and multi-event causal graphs belong in later event/history slices.
 They should extend this record family without making prose authoritative or
 recomputing old evidence from current positions.
+The current opportunity is likewise a single bounded projection, not a generic
+quest, reward, acceptance, dialogue, or capable-helper framework.