feat(ADM-018): completed feature

work/artifacts/F-016/documenter.md

@@ -0,0 +1,34 @@
+# 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`