gamedev-the-steward/docs/FOOD_STORAGE_ARCHITECTURE.md

The Steward — Food Storage and Transactions

First complete food loop

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.

Successful extraction, deposit, withdrawal, and consumption also append structured economic facts. See the economic event stream. Active NPCs display a small food sack while their authoritative inventory contains food; this is presentation derived from state, not a second inventory.

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:

• player inventory;
• storage reservations or access capacity;
• multiple households or ownership;
• spoilage, item quality, weight, or stack definitions;
• an authored StorageNode scene beyond the current pantry marker.

Economic transfer events exist, but event retention, denial/depletion facts, witnesses, and social interpretation are deliberately deferred.

Those should extend the transaction boundary rather than mutate counters directly.