# Documenter — F-016 Inventory module

## Summary
Documented F-016 behavior in this evidence artifact. No project README update was applied because the repository guard allows product/project file edits only during build; the document stage is limited to artifacts/docs outside `project/` in the active guard policy.

## Public API notes

Inventory owns sellability state for product variants. Catalog treats inventory as a separate module: variant ids are opaque UUID references, and catalog must not import inventory internals or query `inventory_*` tables directly.

| Route                                             | Access     | Result                                            |
| ------------------------------------------------- | ---------- | ------------------------------------------------- |
| GET /inventory/:variantId/availability?quantity=1 | public     | `200` + `{ available, availableQuantity }`        |
| PUT /inventory/:variantId/stock                   | admin only | `200` stock item with updated available quantity  |
| POST /inventory/:variantId/reservations           | admin only | `201` reserved stock, `409` if unavailable        |
| POST /inventory/:variantId/reservations/release   | admin only | `200` released stock, `409` if reserved too small |
| POST /inventory/:variantId/reservations/confirm   | admin only | `200` sold stock, `409` if reserved too small     |

## Error codes
- `INSUFFICIENT_STOCK` — HTTP 409
- `INSUFFICIENT_RESERVED_STOCK` — HTTP 409
- `INVALID_STOCK_QUANTITY` — HTTP 422

## Operational notes
- Stock counters are `available`, `reserved`, `sold`, and `incoming`; every counter is constrained non-negative in PostgreSQL.
- Reserve, release, and confirm are atomic predicate `UPDATE` statements, not application-level read-before-write checks.
- `InventoryService` is exported as the public contract for future checkout integration.
- Inventory mutations write `inventory_movements` audit rows.

## Evidence
- `work/artifacts/F-016/architect.md`
- `work/artifacts/F-016/implementer.md`
- `work/artifacts/F-016/reviewer.json`
- `work/artifacts/F-016/security.json`
- `work/artifacts/F-016/qa.json`