📦 Inventory — System Guarantees Matrix¶
This page defines the behavioural contract of the Inventory system.
No marketing. No implication. Just guarantees — and explicit non-guarantees.
🔎 Quick Navigation¶
- Core Service
- Containers
- Mutations
- Results
- Events
- Authority
- Searching / Sorting
- Equipment
- Item Usage
- Snapshots / Persistence
- Determinism
- Public API
- Non‑Guarantees
- Final Summary
1️⃣ Core Service¶
SceneInventoryService¶
| Aspect | Guarantee |
|---|---|
| Orchestration root | ✔ Single service owns container truth |
| Container creation | ✔ Service-controlled (lazy) |
| Container mutation | ✔ Service-controlled |
| Delta computation | ✔ Internal (not user-managed) |
| Supported mutation entry point | ✔ IInventoryService |
| Runtime usage | Main thread |
| Inspector required | ❌ No |
| UI required | ❌ No |
2️⃣ Containers¶
| Aspect | Guarantee |
|---|---|
| Container ownership | ✔ Owned by GameObject |
| Container identifier | ✔ ContainerId |
| Container creation | ✔ Lazy (on demand by service) |
| Container storage | Slot-based |
| Slot count mutable | ✔ Yes (via ResizeContainer) |
| External container construction | ❌ Not supported |
3️⃣ Mutations¶
| Aspect | Guarantee |
|---|---|
| Mutations routed through service | ✔ Yes |
| Deterministic results | ✔ Yes |
| Partial operations allowed | ✔ Yes |
| Container auto-creation on mutation | ✔ Yes |
| Atomicity within single operation | ✔ Best-effort (rollback applied where supported) |
| Atomicity across containers | ❌ Not guaranteed |
| Cross-system atomicity | ❌ Not guaranteed |
Supported mutation classes:
- add
- remove
- split
- merge
- swap
- move
- transfer
- resize
4️⃣ Operation Results¶
| Aspect | Guarantee |
|---|---|
| Result returned for every mutation | ✔ Yes |
| Deterministic failure codes | ✔ Yes |
| Partial operations signaled | ✔ InvOpCode.Partial |
| Silent failure | ❌ Never |
All mutations return:
InvOpResult
5️⃣ Events¶
| Aspect | Guarantee |
|---|---|
| Container change events | ✔ Yes |
| Slot-level delta information | ✔ Yes |
| Event emission timing | ✔ After mutation completes |
| Event emitted after resize | ✔ Yes |
| Event emitted for no-op operations | ❌ No |
Primary event surface:
SceneInventoryService.OnContainerChanged
6️⃣ Authority¶
| Aspect | Guarantee |
|---|---|
| Mutation gating supported | ✔ Yes |
| Authority interface | ✔ IInventoryAuthority |
| Unauthorized mutation result | ✔ InvOpCode.NoAuthority |
| Authority evaluated before mutation | ✔ Yes |
| Read operations gated | ❌ No |
| Multiplayer replication | ❌ Not provided |
Inventory enforces authority only during mutation calls.
7️⃣ Searching / Sorting¶
| Aspect | Guarantee |
|---|---|
| Search supported | ✔ Yes |
| Sort supported | ✔ Yes |
| Strategy interfaces | ✔ Yes |
| Default implementations | ✔ Yes |
| Deterministic sort order | ✔ Stable sort |
| Operates on existing containers only | ✔ Yes |
| Implicit container creation | ❌ No |
| Cross-system deterministic ordering | ❌ Not guaranteed |
Extension seams:
IInventorySearchIInventorySorter
8️⃣ Equipment¶
| Aspect | Guarantee |
|---|---|
| One item per equipment slot | ✔ Yes |
| Equipment filters enforced | ✔ Yes |
| Equip operations transactional | ✔ Yes |
| Inventory integration | ✔ Yes |
| Equipment managed by SceneInventoryService | ❌ No |
Equipment operates through:
CharacterEquipment
9️⃣ Item Usage¶
| Aspect | Guarantee |
|---|---|
| Use effects supported | ✔ Yes |
| Effects executed sequentially | ✔ Yes |
| Item consumed after successful use | ✔ Yes |
| Use system required | ❌ No |
| External effect integration | ✔ Yes |
| Deterministic resolver ordering | ❌ Not guaranteed |
External effects integrate through:
UseEffectResolver.ExternalResolvers
🔟 Snapshots / Persistence¶
| Aspect | Guarantee |
|---|---|
| Inventory snapshot supported | ✔ Yes |
| Equipment snapshot supported | ✔ Yes |
| JSON helpers provided | ✔ Yes |
| Missing item handling policy | ✔ Yes |
| Deferred event emission on apply | ✔ Yes |
| Save slot management | ❌ Not provided |
| Automatic persistence | ❌ Not provided |
| Versioning / migration system | ❌ Not provided |
Snapshots capture:
- container contents
- equipment contents
- item stacks
11️⃣ Determinism¶
| Aspect | Guarantee |
|---|---|
| Mutation determinism | ✔ Yes |
| Event emission ordering | ✔ Deterministic per mutation |
| Cross-system determinism | ❌ Not guaranteed |
| Snapshot restore determinism | ✔ Best-effort (dependent on item database consistency) |
12️⃣ Public API¶
| Aspect | Guarantee |
|---|---|
| Stable service surface | ✔ Yes |
| Public extension interfaces | ✔ Yes |
| Internal containers exposed | ❌ No |
| Internal helpers public | ❌ No |
| DTO types exposed | ❌ No |
Public extension seams include:
IInventorySearchIInventorySorterIInventoryAuthorityIItemDatabaseIUseEffect
🚨 Non‑Guarantees¶
Inventory does not guarantee:
- multiplayer replication
- prediction / rollback
- cross-system atomic transactions
- automatic persistence
- deterministic external resolver ordering
- deterministic behaviour across external systems
🎯 Final Summary¶
| Layer | Strong Guarantee | Best Effort | Not Guaranteed |
|---|---|---|---|
| Service-controlled mutations | ✔ | ||
| Deterministic results | ✔ | ||
| Partial operations | ✔ | ||
| Snapshot restore | ✔ | ||
| Cross-system atomicity | ❌ | ||
| Multiplayer replication | ❌ |
System Philosophy¶
Inventory is:
- Service-driven
- Slot-based
- Deterministic
- Authority-aware
- Explicit about guarantees