📦 Crafting — Inventory Abstractions¶

📦 Folder Overview¶

This folder defines the inventory integration seam for the Crafting system.

Crafting does not depend on a concrete inventory implementation. All inventory interaction flows through these interfaces.

🧩 What Lives Here¶

ICraftingInventoryAdapter — primary inventory integration contract
CraftingInventoryContext — adapter + container handle wrapper
Reservation interfaces for optional escrow workflows

🎯 Purpose¶

These abstractions provide a way to:

resolve and operate on inventory containers
query item counts and available space
consume inputs and add outputs
support optional reservation-based workflows

They allow Crafting to remain inventory-agnostic while supporting different backend implementations.

🧠 Usage Guidance¶

ICraftingInventoryAdapter¶

The required inventory adapter used for:

resolving containers
counting items
checking space
consuming inputs
adding outputs
deferring or batching inventory events (if supported)

Every Crafting setup requires an implementation of this interface in order to interact with an inventory system.

Implementations define what constitutes a valid container handle and how inventory semantics behave.

CraftingInventoryContext¶

A lightweight value wrapper combining:

an inventory adapter
an opaque container handle

This is the supported way Crafting code interacts with containers. It hides adapter-specific handle types.

Contexts are considered valid only when both the adapter and handle are non-null. When invalid, mutation methods fail safely and count queries return zero.

Contexts are produced by the Crafting service through its inventory adapter. Consumers should not construct them directly.

Reservation interfaces (optional)¶

ICraftingInventoryReservationAdapter
ICraftingInputReservation
ICraftingOutputReservation

These interfaces enable reservation-based workflows by allowing:

inputs to be reserved
output capacity to be reserved
commits to be performed with adapter-defined semantics

Correctness guarantees (such as atomicity or idempotency) depend on the adapter implementation. The Crafting service relies on these guarantees but does not enforce them.

These interfaces are optional and are only required for advanced escrow-style workflows.

⚠️ Important Notes¶

Inventory behaviour depends on the adapter implementation
Container handle types are adapter-defined and opaque to Crafting
Missing reservation support limits escrow-style workflows

Crafting Core (inventory usage during preflight and execution)
Integrations (inventory adapter implementations)