# E3.M3 — ItemizationAndInventorySchema

## Summary

| Field | Value |
|--------|--------|
| **Module ID** | E3.M3 |
| **Epic** | [Epic 3 — Crafting Economy](../epics/epic_03_crafting_economy.md) |
| **Stage target** | Prototype |
| **Status** | In Progress — Slice 1 backlog [NEO-50](https://linear.app/neon-sprawl/issue/NEO-50)–[NEO-56](https://linear.app/neon-sprawl/issue/NEO-56) ([E3M3-prototype-backlog](../../plans/E3M3-prototype-backlog.md); see [dependency register](module_dependency_register.md)) |

## Purpose

Item definitions, rarity/quality, stackability, and equipment metadata plus `InventorySlot` representation. Foundation for craft outputs, quest rewards, combat loot, and trade.

## Responsibilities

- Version `ItemDef` / `ItemInstance` schema; enforce stack and slot rules server-side.

## Key contracts

| Contract | Role |
|----------|------|
| `ItemDef` | Static template data. |
| `ItemInstance` | Per-item state (stack, durability hook, binds). |
| `InventorySlot` | Container model for players and exchanges. |

## Module dependencies

- **None**

## Dependents (by design)

- **E3.M2**, **E3.M4**, **E5.M3**, **E7.M2**, **E8.M3**, and any system moving items.

## Designer note: stack, slot, and v1 scope

Each **`ItemDef`** row under `content/items/*.json` declares:

- **`stackMax`** — maximum units per inventory slot for that def (inventory engine in E3M3-05+ enforces this on add).
- **`inventorySlotKind`** — **`bag`** (general inventory) vs **`equipment`** (equip-stub slot only in prototype; full loadout rules are later).
- **`prototypeRole`** — Slice 1 archetype for CI coverage (`material` → `equip_stub`); not a player-facing bucket label (see [items.md](../../game-design/items.md) design lenses).

**Prototype v1:** optional schema fields **`rarity`**, **`bindPolicy`**, **`durabilityMax`** exist for forward compatibility but are **omitted** on all six shipped rows. **No durability mutation** or repair sinks in Slice 1—those belong to [E3.M4](E3_M4_SinkAndDurabilityLifecycle.md).

## Prototype Slice 1 freeze (NEO-50)

The **first shipped six-item spine** under `content/items/*.json` is **frozen** for downstream references (gather yields, recipes, inventory grants) until a deliberate migration or follow-up issue expands the roster.

| `ItemDef.id` | `prototypeRole` | `inventorySlotKind` | `stackMax` |
|--------------|-----------------|---------------------|------------|
| **`scrap_metal_bulk`** | `material` | `bag` | 999 |
| **`refined_plate_stock`** | `intermediate` | `bag` | 999 |
| **`field_stim_mk0`** | `consumable` | `bag` | 20 |
| **`survey_drone_kit`** | `utility` | `bag` | 1 |
| **`contract_handoff_token`** | `quest_token` | `bag` | 1 |
| **`prototype_armor_shell`** | `equip_stub` | `equipment` | 1 |

**Rules:** Do **not** rename these `id` values—change **`displayName`** only, or add a new `id` in a follow-up issue. CI ([`scripts/validate_content.py`](../../../scripts/validate_content.py)) enforces **exactly** these six ids, **one row per `prototypeRole`**, and duplicate-`id` rejection across all item JSON files. Relaxing or changing that gate belongs in a new Linear issue once the catalog intentionally grows.

## Related implementation slices

Epic 3 **Slice 1** — MVP inventory; `item_created`, transfer failures.

**Linear backlog (decomposed):** [E3M3-prototype-backlog.md](../../plans/E3M3-prototype-backlog.md) — **E3M3-01** [NEO-50](https://linear.app/neon-sprawl/issue/NEO-50) (content + CI) through **E3M3-07** [NEO-56](https://linear.app/neon-sprawl/issue/NEO-56) (telemetry hooks).

## Source anchors

- Master plan: [`neon_sprawl_vision.plan.md`](../../../neon_sprawl_vision.plan.md) — Epic 3.
- [Module dependency register](module_dependency_register.md)