feat: add knowledge-gated pantry opportunities

docs/SIMULATION_STATE_SCHEMA.md

@@ -3,7 +3,7 @@
 ## Current contract
 
 `SimulationStateRecord` is the versioned JSON boundary for the current
-simulation. The current world schema is v7 and captures:
+simulation. The current world schema is v8 and captures:
 
 - simulation seed, tick interval, tick count, clock remainder, and elapsed
   clock ticks;
@@ -19,14 +19,16 @@ simulation. The current world schema is v7 and captures:
   ID that last changed trust;
 - per-NPC known-event records that reference objective event history without
   copying it, including first-acquisition method, acquisition tick, and
-  historical communicator provenance.
+  historical communicator provenance;
+- opportunity records with stable type/status, interested NPC, trigger event,
+  target storage/resource/amount, and exact later resolution event identity.
 
 The top-level identity is:
 
 ```json
 {
   "schema": "the_steward.simulation",
-  "schema_version": 7
+  "schema_version": 8
 }
 ```
 
@@ -59,6 +61,8 @@ It also verifies clock remainder, resource amount/reservation/enabled
 round-tripping, presentation unload/rebind, directed relationship/cause
 round-tripping, divergent known-event state, communicated provenance, and
 deterministic retention boundaries, and rejection of unsupported schemas.
+Active and resolved opportunity round-tripping, contradictory target state,
+invalid resource sources, and cross-record event references are covered too.
 
 NPCStateRecord v2 adds the resolved travel destination and whether it is
 active. Nested v1 NPC records migrate explicitly with no invented active
@@ -147,6 +151,30 @@ facts, and recent facts at least one simulated day old are removed at the next
 deterministic daily-sized review. The objective event stream is never pruned by
 this rule.
 
+SimulationStateRecord v8 adds the top-level `opportunities` array and
+`simulation.next_opportunity_id`. The first nested `OpportunityStateRecord`
+schema stores `opportunity_id`, `opportunity_type`, `status`, `created_tick`,
+`trigger_event_id`, `interested_npc_id`, `target_id`, `resource_id`,
+`target_amount`, `resolution_event_id`, and `resolved_tick`. World schemas
+v1–v7 migrate explicitly to an empty opportunity list with next ID zero.
+
+The bounded `restock_empty_pantry` contract accepts at most one open record.
+Opportunity, trigger-event, and resolution-event IDs are unique and the next
+ID must remain above restored history. The interested NPC, pantry, food
+resource, and referenced events must exist. Its trigger is a positive NPC food
+withdrawal from `village_pantry` to that actor's matching inventory; an open
+record additionally requires the pantry to remain below its one-food target
+and the interested NPC to have acquired that fact no later than creation.
+Resolution references an exact later NPC inventory-to-pantry food deposit or a
+player `resource_extracted` event from an existing player-usable food resource
+into the pantry, with a matching resolved tick. Resolved history does not
+require the pantry still to contain food because later consumption is valid.
+
+While the need is open, its interested villager's trigger evidence is treated
+as lasting during deterministic memory maintenance. Resolution releases that
+fact back to the normal bounded-retention rules; it does not delete objective
+event or opportunity history.
+
 ## Resource authority
 
 `SimulationManager` owns `ResourceStateRecord` instances independently of the
@@ -183,11 +211,13 @@ This phase does not yet provide:
 
 - a save-slot menu, metadata, thumbnails, autosaves, or multiple profiles;
 - migrations from any historical world schema other than the explicitly
-  supported v1–v6 layouts;
+  supported v1–v7 layouts;
 - player inventory or player relationship records;
 - broader relationship dimensions, line-of-sight/hearing evidence,
   continuous or personalized memory decay, reinforcement, false beliefs, or
   multi-hop rumours;
+- generalized opportunity/quest definitions, acceptance, rewards, assignment,
+  dialogue, or player-facing quest-log state;
 - persistence for the player transform or presentation-only scene state.
 
 Those features should build on this boundary rather than inventing parallel