docs: document food storage transaction loop

2026-07-05 17:57:33 +02:00
parent 6dbb395bd6
commit ebf70a711a
8 changed files with 92 additions and 14 deletions
@@ -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.