feat: add knowledge-gated pantry opportunities

docs/ARCHITECTURE_OVERVIEW.md

@@ -17,6 +17,7 @@ SimulationClock
         -> SimulationEventLog records completed facts
         -> EventKnowledgeSystem records, ranks, transfers, and retains bounded knowledge
         -> RelationshipSystem applies evidence-gated social consequences
+        -> FoodShortageOpportunitySystem projects one known unresolved need
     -> WorldViewManager presents travel and NPC state
         -> ActiveWorldAdapter supplies loaded-world positions/capacity
         -> NpcVisual performs local navigation, animation, and transient reactions
@@ -38,6 +39,10 @@ would otherwise obscure that lifecycle:
   retention/importance ranking;
 - `simulation/relationships/RelationshipSystem.gd` owns directed relationship
   queries, event-driven trust changes, and deterministic social tie-breaking;
+- `simulation/opportunities/FoodShortageOpportunitySystem.gd` observes
+  immutable event references plus current pantry/NPC state, then owns the
+  bounded open/resolved pantry-restock lifecycle without changing resources or
+  assigning tasks;
 - `simulation/persistence/` owns save-slot file safety;
 - `simulation/state/` owns versioned serialized record contracts;
 - `simulation/definitions/` owns stable IDs and immutable action/profession
@@ -58,6 +63,7 @@ hard to read.
 | `simulation/events/` | Immutable event history and derived event queries |
 | `simulation/knowledge/` | Per-NPC knowledge of objective event IDs |
 | `simulation/relationships/` | Directed social consequences and relationship queries |
+| `simulation/opportunities/` | Knowledge-gated unresolved-condition projections |
 | `simulation/state/` | Versioned, serializable mutable records |
 | `simulation/definitions/` | Stable IDs and immutable gameplay definitions |
 | `simulation/persistence/` | Validated local save-file storage |
@@ -80,15 +86,19 @@ improving ownership.
   ownership.
 - Presentation may report facts and submit commands; it does not choose NPC
   actions or own resource, storage, inventory, event, knowledge, relationship,
-  or reservation state.
+  opportunity, or reservation state.
 - Inspector history is a read-only façade query over objective events and
-  retained knowledge. Relationship cues consume state-change signals and are
-  intentionally absent from saves and checksums.
+  retained knowledge. Opportunity presentation is likewise query-only.
+  Relationship cues consume state-change signals and are intentionally absent
+  from saves and checksums.
 - Resource changes go through `ResourceStateRecord`, NPC inventory, and
   `VillageEconomy`; `village.food` and `village.wood` are synchronized views.
 - New mutable features define serialization and deterministic continuation at
   the same time as their first gameplay use. Cross-record causes use stable
   event IDs rather than object references or prose.
+- Opportunity records reference stable NPC, storage, resource, trigger-event,
+  and resolution-event IDs. Their generator may observe authoritative state
+  and history, but it does not mutate the economy or command NPC behavior.
 - Prefer one tested vertical behavior over a generic framework with no proven
   consumers.