docs: document food storage transaction loop

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -95,7 +95,7 @@ Main
 │   │       ├── BerryBush instances
 │   │       └── Tree instances
 │   ├── LegacyActivityMarkers          temporary non-resource activities
-│   │   ├── FoodZone
+│   │   ├── PantryMarker
 │   │   ├── GuardZone
 │   │   ├── StudyZone
 │   │   └── RestZone

docs/FOOD_STORAGE_ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# The Steward — Food Storage and Transactions
+
+## First complete food loop
+
+```text
+ResourceStateRecord (berry bush)
+    -> gather_food extracts actual yield
+    -> SimNPC inventory carries food
+    -> deposit_food targets village_pantry
+    -> StorageStateRecord receives food
+    -> hungry NPC selects withdraw_food
+    -> pantry transfers one food into NPC inventory
+    -> eat consumes carried food and reduces hunger
+```
+
+Food is conserved across source, carried inventory, and pantry. It leaves the
+world only when consumed.
+
+## Authority
+
+- `StorageStateRecord` owns pantry contents and capacity.
+- `SimNPC.inventory` owns carried item amounts.
+- `SimulationManager` performs deposit, withdrawal, and consumption
+  transactions.
+- `village.food` is a synchronized aggregate view used by the existing UI,
+  priorities, and utility scoring. It is not a second mutation path.
+- `PantryMarker` supplies the active-world interaction position for deposit,
+  withdrawal, eating, and current player pantry interaction.
+
+The village pantry has stable ID `village_pantry`. Storage and NPC inventory
+are included in versioned state and deterministic checksums.
+
+## Failure behavior
+
+Transactions apply the amount actually available:
+
+- extraction cannot exceed the source;
+- deposit cannot exceed storage capacity;
+- withdrawal cannot exceed pantry contents;
+- eating succeeds only when the NPC carries one food.
+
+If another NPC empties the pantry first, withdrawal returns zero and the NPC
+replans on its next idle tick.
+
+## Deliberate limits
+
+This slice contains one pantry and one carried item type. It does not yet add:
+
+- visible carried props;
+- player inventory;
+- storage reservations or access capacity;
+- multiple households or ownership;
+- spoilage, item quality, weight, or stack definitions;
+- structured transaction/history events;
+- an authored StorageNode scene beyond the current pantry marker.
+
+Those should extend the transaction boundary rather than mutate counters
+directly.

docs/LEARNING_ROADMAP.md

@@ -633,14 +633,21 @@ Completed foundations:
 
 The practical next sequence is:
 
-1. Build location-based food storage, inventory, and transactions.
+Completed after the architecture gate:
-2. Emit structured economic events while making one NPC visibly gather, carry,
+
+- location-based pantry state, NPC-carried food, and explicit
+  deposit/withdraw/consume transactions;
+- a headless conservation scenario covering the complete food loop.
+
+The practical next sequence is:
+
+1. Emit structured economic events while making one NPC visibly gather, carry,
    store, retrieve, and eat food.
-3. Add save-slot persistence and explicit schema migrations before schedules
+2. Add save-slot persistence and explicit schema migrations before schedules
    or social state expand.
-4. Resume Terrain3D sculpting, runtime integration, and the simulation-garden
+3. Resume Terrain3D sculpting, runtime integration, and the simulation-garden
    beauty pass.
-5. Add stylized character and profession readability plus the reason
+4. Add stylized character and profession readability plus the reason
    inspector.
 
 This order strengthens the simulation while regularly producing visible

docs/PROJECT_CONTEXT.md

@@ -468,6 +468,7 @@ NpcVisual navigates through the active world
 │   ├── action_system_boundaries_test.gd
 │   ├── deterministic_simulation_test.gd
 │   ├── flat_map_baseline_test.gd
+│   ├── food_storage_loop_test.gd
 │   ├── jajce_world_scaffold_test.gd
 │   ├── npc_visual_lifecycle_test.gd
 │   ├── resource_node_player_parity_test.gd
@@ -511,7 +512,8 @@ These are expected prototype constraints, not necessarily isolated bugs:
   continuation checks, player-parity/resource-contention, flat-map, and Jajce
   scaffold scenarios; broader gameplay coverage is still missing.
 - Resources are global floating-point counters rather than items in locations
-  and inventories.
+  and inventories, except food, which now moves through sources, NPC inventory,
+  and the village pantry.
 - NPCs do not have homes, schedules, possessions, memories, relationships,
   goals, or social knowledge.
 - NPC reasoning is logged but not presented through an in-game inspector.
@@ -735,10 +737,11 @@ architecture gate are complete:
 - authoritative active position and persisted travel destinations;
 - checksum-invariant NPC visual unload/reload with reservation preservation.
 
-The next systems milestone is a complete location-based food loop: storage,
+The location-based food loop is now complete at simulation level: gathering
-inventory, carrying, depositing, withdrawing, and eating through transactions.
+creates carried food, depositing fills the pantry, withdrawal retrieves one
-Bounded Terrain3D look-development can resume, but runtime terrain integration
+unit, and eating consumes it. The next systems milestone is structured
-should remain coordinated with that visible systems slice.
+transaction events and visible carrying/readability. Bounded Terrain3D
+look-development can resume alongside that presentation work.
 
 The coherent visual slice can then aim for:
 

docs/README.md

@@ -16,6 +16,7 @@ sources of truth.
    migration plan. Phases 1–4 are complete; its Phase 5 hands world placement to
    the visual-slice plan.
 5. [`ACTION_SYSTEM_ARCHITECTURE.md`](ACTION_SYSTEM_ARCHITECTURE.md),
+   [`FOOD_STORAGE_ARCHITECTURE.md`](FOOD_STORAGE_ARCHITECTURE.md),
    [`SIMULATION_DEFINITIONS.md`](SIMULATION_DEFINITIONS.md), and
    [`SIMULATION_STATE_SCHEMA.md`](SIMULATION_STATE_SCHEMA.md) document the
    current data contracts.

docs/RESOURCE_NODE_MIGRATION.md

@@ -527,6 +527,10 @@ nodes have been deleted from `main.tscn`. The surviving nodes live under
 mapping still exists for eating, rest, study, and patrol, so this phase is not
 complete.
 
+The former `FoodZone` is now `PantryMarker` backed by simulation-owned
+`StorageStateRecord` state and explicit deposit/withdraw transactions. A
+dedicated authored StorageNode presentation is still pending.
+
 **Exit:** temporary activity markers and task-to-marker mapping are deleted,
 not merely unused.
 

docs/SIMULATION_DEFINITIONS.md

@@ -22,9 +22,9 @@ Each executable action definition contains:
 - target type: resource, activity, or free movement;
 - resource action ID when the action targets a ResourceNode.
 
-The current actions are gather food, gather wood, patrol, study, eat, rest, and
+The current actions are gather food, gather wood, deposit food, withdraw food,
-wander. Idle and dead are stable state sentinels, not executable action
+patrol, study, eat, rest, and wander. Idle and dead are stable state sentinels,
-definitions.
+not executable action definitions.
 
 SimNPC reads default duration and preferred-profession metadata from these
 definitions. WorldViewManager reads target type and resource-action metadata

docs/SIMULATION_STATE_SCHEMA.md

@@ -57,6 +57,11 @@ active. Nested v1 NPC records migrate explicitly with no invented active
 destination. This allows a reloaded visual to resume travel without changing
 target selection or deterministic RNG state.
 
+NPCStateRecord v3 adds carried inventory. SimulationStateRecord v2 adds
+StorageStateRecord entries; world-schema v1 migrates legacy village food into
+the stable `village_pantry` record. Parsed storage values are canonicalized so
+save/restore continuation retains byte-stable checksums.
+
 ## Resource authority
 
 `SimulationManager` owns `ResourceStateRecord` instances independently of the