Inventory Item Module

Status: Designed — runtime build pending. The rules of physical inventory custody described here have been designed and checked; a live inventory capability exists but is being rebuilt to these rules.

Purpose

An inventory item is a discrete, homogeneous, located, owned quantity of goods — a specific chunk of physical stock — classified by a catalog Item. The catalog item describes what a thing is; an inventory item is some actual stock of it, sitting in a place, in a condition, at a quantity. This module makes the rules of holding, moving, splitting, consuming, and counting that stock precise.

The central distinction is identity versus state: an inventory item’s identity is permanent, while everything about its current condition is state that changes only through explicit, recorded operations.

Main entities

• Identity (permanent). Which item it is, its license plate (its handling-unit identity, like a pallet’s label), an optional serial number, and a reorder threshold. None of these change for the life of the holding.
• State (changes only through operations). Its fill (Sealed = asserted as-intended, Open = in use, Empty = nothing left), its quantity (and any degraded, unavailable portion), its location, its lot provenance, an optional expiration, and whether it is locked (held / quarantined). The system can answer what the state was at any moment in the past.
• Inventory pool. All the holdings of a single item, grouped together — the way the system refers to “all the stock of this item.” A pool tracks which holdings belong to it (add and remove); it does not store a count of its own. See Inventory pools and counts for how counts over a pool are computed.

Operations

Action	What it does	Notes
Create	Mints a new holding (with a license plate).	Born Open.
Replenish / consume	Adds or removes quantity.	Over-consuming is refused; consuming to zero leaves an empty, revivable holding.
Adjust quantity	Sets the counted quantity to an observed value.
Move	Relocates the holding.	Refused while locked.
Split / merge	Divides one holding into two, or combines two into one.	Quantity is conserved.
Repack	Re-expresses the same goods in a different unit of measure.	Does not change the real quantity.
Inspect	Marks a degraded (unusable) portion.	The single driver of condition.
Seal / unseal	Asserts, or releases, the as-intended condition.
Lock / unlock	Places or releases an administrative hold.
Delete / write off	Retires the holding.	Terminal.

Guarantees

• Identity is permanent and separate from state. The item it classifies, its license plate, and its serial number never change.
• License plates are never reused — once retired, a handling-unit identity does not come back.
• Depleting is not retiring. Consuming a holding to zero leaves it empty but alive, ready to receive new stock; only a delete or write-off retires it, and retirement is final.
• Split and merge conserve quantity — nothing is created or lost when a holding is divided or combined.
• Over-consuming is refused, specifically. Trying to remove more than is on hand is rejected with a precise reason, not silently clamped.
• Every state is well-formed, and the full history is queryable — you can ask what any holding’s quantity, location, or condition was as of any moment.

Inventory pools and counts

An inventory pool is a set of holdings of a single item — the way the system talks about “all the stock of this item, here.” Counts are computed, never stored: the total, degraded, and usable quantities of an item at a location are derived from the live holdings as of the moment you ask, so a count is always a true reading rather than a figure that can drift.

How it relates to its neighbors

• Item — every holding is classified by exactly one catalog item.
• Kanban Cards — a loaded card carries inventory holdings across part of its lap.
• Demand — a production request accumulates produced materials in a holding pool.

Linear

• Initiative: Product / Resources / Inventory Items