# 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.

Successful extraction, deposit, withdrawal, and consumption also append
structured economic facts. See [the economic event stream](ECONOMIC_EVENTS.md).
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.
