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.

Animal care extends the same ownership chain without a parallel counter:

village_pantry
    -> feed_animal pickup moves one food into exact caretaker inventory
    -> existing carried-food prop derives from that inventory
    -> delivery consumes caretaker inventory into exact named animal

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, including exact all-or-nothing animal-care pickup and inventory removal.
• 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. NPC animal care therefore uses the same visible prop between pantry pickup and the claimed goat.

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;
• animal-care pickup succeeds only when the complete missing cost is available;
• eating succeeds only when the NPC carries one food.

If another caretaker empties the pantry first, animal-care pickup records the definition-backed shortfall, transfers nothing, releases only the losing caretaker's exact animal claim, and replans. A caretaker that already carries the unit never consults pantry stock again before delivery.

Deliberate limits

The current bounded economy has one authored pantry and one woodpile with simple food/wood stacks. It does not yet add:

• player inventory;
• storage reservations or access capacity;
• multiple households or ownership;
• spoilage, item quality, weight, or stack definitions.

Objective event history, depletion and blocked-task facts, bounded per-NPC knowledge, proximity witnesses, and the first social consequences now exist. Long-run event archival, generalized denial facts, wider witness models, and broader social interpretation remain deferred.

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