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 and woodpile contents and capacity.
• SimNPC.inventory owns carried item amounts.
• VillageEconomy performs deposit, withdrawal, consumption, and definition-backed completion-cost transactions.
• SimulationManager coordinates action lifecycle and exposes the transaction results to presentation.
• village.food and village.wood are synchronized aggregate views used by the existing UI, priorities, and utility scoring. They are not second mutation paths.
• StorageNode supplies the active-world interaction position and presentation for deposit, withdrawal, eating, and current player pantry interaction.

The village pantry has stable ID village_pantry; the woodpile has stable ID village_woodpile. Storage and NPC inventory are included in versioned state and deterministic checksums. Patrol and study require one wood on completion: the effect is applied only when that unit can be withdrawn, and selection does not choose those actions while the woodpile is empty.

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;
• player extraction is limited to storage capacity until player inventory exists, so overflow remains at the source;
• 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 authored 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.

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.