Inventory owns possession, not every item meaning

669. Lesson identity

Module

2.5 — Inventory, equipment, and crafting

Lesson

1

Academic type

Systems

Estimated time

30–40 minutes, including practice

Core capability

Model a small inventory contract

670. Learning objective

After this lesson, you can define a small inventory contract that stores fungible quantities by item-definition ID, enforces an explicit per-definition possession cap, validates mutations, reports their results, and separates possession from item interpretation.

671. Why this matters

Equipment, crafting, rewards, shops, and save data may all depend on inventory state. If each system changes that state according to different assumptions, quantities can become negative, caps can be exceeded, and callers may report success when possession did not change.

A narrow inventory authority provides one answer to what the player possesses and one path for changing it. It does not make the inventory responsible for equipment effects, recipes, prices, progression, or narrative meaning.

672. Identity: definition IDs and instance IDs

This lesson distinguishes two forms of identity:

• An item-definition ID identifies a reusable item type, such as bandage or scrap_metal. Multiple interchangeable units can share this ID.
• An item-instance ID identifies one particular object when it has individual state, such as durability, generated properties, ownership history, or another per-instance value.

The small contract in this lesson supports only fungible quantities keyed by item-definition ID:

quantityByDefinitionId[definitionId] = quantity

It does not store item-instance IDs, stack records, or slot placement. Therefore, it cannot represent two separate stacks of the same definition or two individually different copies. A game that needs those distinctions requires a different or extended storage model.

673. Inventory authority and boundaries

The inventory is authoritative for:

• whether a positive quantity of an item-definition ID is possessed;
• the stored quantity for that definition ID;
• whether an addition or removal satisfies the inventory contract;
• applying or rejecting the mutation;
• reporting a caller-visible result.

Other systems remain authoritative for:

• whether an item can be equipped and what effect it has;
• whether an item is a valid crafting ingredient;
• shop prices and economic interpretation;
• progression or unlock decisions;
• narrative meaning;
• item-definition data such as display information and the configured possession cap.

Other systems may read possession and request a mutation, but they should not rewrite the quantity map directly.

674. Supported storage and capacity model

For this lesson, each item definition has one aggregate quantity and an optional per-definition possession cap:

stored state: definition ID → aggregate quantity
valid quantity: 0 through possessionCap, inclusive

The cap limits the total quantity held under that definition ID. It is not a stack limit, slot limit, weight limit, or total inventory limit.

Examples:

bandage      quantity: 3   possession cap: 5
scrap_metal  quantity: 4   possession cap: 10
key_fold     quantity: 1   possession cap: 1

The item-definition data owns the configured cap. The inventory reads that value when validating possession changes. A quantity of zero may be omitted from storage, provided the contract states that a missing entry means zero.

675. Mutation contract

Use this sequence:

REQUEST → VALIDATE → MUTATE OR REJECT → REPORT RESULT

A minimal request identifies:

• the operation: add or remove;
• the item-definition ID;
• a positive requested quantity.

Validation rules for this model:

1. The definition ID must resolve to a known definition.
2. The requested quantity must be greater than zero.
3. Addition is valid only when current + requested <= possessionCap.
4. Removal is valid only when current >= requested.
5. Rejection leaves stored state unchanged.

A caller-visible result should include at least:

accepted: true or false
reason: accepted, unknown_definition, invalid_quantity, cap_exceeded, or insufficient_quantity
resultingQuantity: authoritative quantity after the request

Reporting the authoritative resulting quantity prevents the caller from guessing whether state changed.

676. Concrete example

Initial state and definitions:

bandage      quantity: 3   possession cap: 5
scrap_metal  quantity: 4   possession cap: 10
key_fold     quantity: 1   possession cap: 1

The rejected bandage addition is not split into multiple stacks because this model has no stack records. Supporting separate stacks would require stack identity and an appropriate container structure.

677. Responsibility table

The inventory can supply possession evidence without becoming the authority for those interpretations.

678. Common mistakes

Calling an aggregate cap a stack limit

A stack limit applies to a stack record. This lesson stores no stack records, so its rule is a per-definition possession cap.

Treating a definition ID as an instance ID

bandage identifies a type shared by interchangeable units. It does not distinguish one bandage from another. Individual durability or generated properties require instance records.

Leaving capacity unspecified

The word “capacity” is ambiguous unless the contract identifies whether it means slots, weight, stacks, total items, or a per-definition quantity. This contract supports only the last of those.

Allowing direct writes

Callers that edit the quantity map can bypass validation. Additions and removals should use explicit operations.

679. Guided practice

Create a contract and decision table for these definitions:

ration         possession cap: 4
copper_wire    possession cap: 10
access_token   possession cap: 1

Use this template:

Supported identity model:
Stored state:
Meaning of a missing entry:
Cap ownership and meaning:
Add validation:
Remove validation:
Rejected-request behavior:
Caller-visible result:
Unsupported storage features:
Responsibilities outside inventory:

Resolve these cases:

1. Add 4 ration to quantity 0.
2. Add 1 more ration after case 1.
3. Remove 2 access_token when quantity is 1.
4. Decide whether copper_wire is a valid crafting ingredient.
5. Explain what must change in the storage model if two ration units need different durability values.

For each mutation, record the accepted flag, reason, resulting quantity, and whether stored state changed.

680. Validation and evidence

Submit the contract and result table through the attached practical assessment. Check that:

• definition IDs and optional instance IDs are explicitly distinguished;
• the supported model is limited to fungible aggregate quantities;
• the cap is defined as a per-definition possession cap;
• no answer relies on stack splitting, slots, or weight;
• additions and removals validate before mutation;
• rejected requests leave state unchanged;
• caller-visible results include acceptance, reason, and resulting quantity;
• crafting or another interpretation is assigned outside inventory;
• the need for instance records is recognized when units have individual state.

681. Key takeaways

• This inventory stores aggregate fungible quantities keyed by item-definition ID.
• An item-definition ID identifies a type; an item-instance ID would identify one particular object.
• This model uses a per-definition possession cap, not stacks, slots, or weight.
• Inventory owns possession and validated possession changes, not every interpretation of an item.
• Every mutation must validate first and return an explicit result.

682. Next lesson

2.5 L2 — Equipment changes capability through a contract keeps inventory authoritative for possession while equipment owns equipped state and effect interpretation.

683. Knowledge check