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.

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.