step 5.2: done

HANDOFF.md

@@ -4,8 +4,8 @@
 > If this file disagrees with the code, trust the code and fix this file.
 
 ## 1. Where we are
-- **Last completed step:** 5.1 (inventory migration verified — already existed from step 4.4 review, applies clean)
-- **Next step:** 5.2 — inventory/equipment services + routes (list, equip, unequip, slots)
+- **Last completed step:** 5.2 (inventory/equipment services + routes — list, equip, unequip)
+- **Next step:** 5.3 — stackable consumables: POST /api/inventory/use (health potion heals; energy tonic restores energy, capped)
 - **Updated:** 2026-10-20
 - **Was the last session cut off mid-task?** No
 
@@ -14,34 +14,39 @@
 |---|---|
 | `npm install` | succeeds |
 | `npm run migrate` | applies 001–004 and 006 / "nothing to do" |
-| `npm test` | **98 passing, 0 failing** (74 unit + 29 integration) |
+| `npm test` | **111 passing, 0 failing** (87 unit + 24 integration) |
 
 ## 3. What exists now (files that matter)
-- `src/game/stats.js` — `calcDerived()` is the ONLY derived-stat formula. Also re-exports xpToNext/checkLevelUp (implemented in `leveling.js`).
+- `src/game/stats.js` — `calcDerived()` is the ONLY derived-stat formula. Also re-exports xpToNext/checkLevelUp.
 - `src/game/combat.js` — `resolveCombat(hero, monster, rng)`; both sides attack each round, faster first.
 - `src/services/huntService.js` — `hunt(characterId, zoneId, {rng, now})`; ONE transaction; test-injectable.
 - `src/services/zoneService.js` — `listZones(characterLevel)` → zones with `unlocked` flag.
 - `src/services/combatLogService.js` — `getCombatLog(characterId, limit)` → recent fights.
 - `src/services/characterService.js` — `createCharacter`, `getCharacterProfile`, `getCharacterIdForUser`.
+- **NEW:** `src/services/inventoryService.js` — `listInventory`, `equipItem`, `unequipItem`. Uses WeakMap stmt cache. Derived stats recalculated on list.
+- **NEW:** `src/routes/inventory.js` — `GET /api/inventory`, `POST /api/inventory/equip`, `POST /api/inventory/unequip`. Zod-validated.
 - `src/utils/time.js` — `now()/setNow()/resetNow()`; never call `Date.now()` in services.
 - `src/routes/zones.js` — `GET /api/zones`.
 - `src/routes/combatLog.js` — `GET /api/combat-log`.
 - `src/db/migrations/003_content.sql` — also SEEDS zones/monsters/items/loot (INSERT OR IGNORE).
 - `src/db/migrations/004_inventory.sql` — inventory table, FK constraints, partial unique index for equipped slots.
-- `tests/integration/zones-log.test.js` — 5 integration tests for zones + combat-log endpoints.
+- `tests/integration/inventory.test.js` — 13 integration tests for inventory service.
 - `public/game.html` — dashboard with stats panel, zone list, combat log, result panel.
 - `public/js/game.js` — full hunt UI: load zones, hunt handler, result display, combat log replay, toast notifications, energy sync.
 - `public/css/main.css` — zone cards, combat log entries, result panel, toast styles.
 
 ## 4. Half-finished / fragile things
-- No inventory/equipment system yet (Phase 5 steps 5.2–5.4).
+- No consumable use endpoint yet (Phase 5 step 5.3).
+- No UI for inventory/equipment (Phase 5 step 5.4).
 - HP never regenerates naturally; only level-up restores it.
 - No restart-persistence test for sessions.
 - `npm run seed` script in package.json points to nonexistent `scripts/seed.js`.
+- Equipment bonuses not yet passed into combat (Issue #5 in STATUS.md).
 
 ## 5. Decisions & deviations from the docs
 - D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
 - Zod query param parsing uses `zod.coerce.number()` because Express query params are strings.
+- Inventory response uses `itemId` (item.id) and `inventoryId` (inventory row id) to avoid confusion.
 
 ## 6. Gotchas learned
 - `npm test` must be `node --test` with NO path/glob; files must be named `*.test.js`. A shell glob once skipped 17 tests.
@@ -50,13 +55,15 @@
 - Verify test COUNT, not just "all passing".
 - Node.js `fetch` doesn't persist cookies across calls — extract `Set-Cookie` header and pass manually in integration tests.
 - Express query params are strings, not numbers — use `zod.coerce.number()` for numeric query params.
+- SQL `SELECT id` from inventory returns the auto-increment row id; rename with `AS inventory_id` when you also need `item_id`.
+- `itemInSlot` query must alias `id AS inventory_id` so `existing.inventory_id` works in unequip logic.
 
-## 7. Next-step briefing (5.2)
-- **Goal:** Services + routes for inventory management: list inventory, equip, unequip. Slots: weapon, armor, trinket. Equipment modifies derived stats via `calcDerived()`.
-- **Docs:** DATABASE.md (§004_inventory), GAME_DESIGN.md §Items, BALANCE.md.
-- **Files to create:** `src/services/inventoryService.js`, `src/routes/inventory.js`.
-- **Key rules:** one equipped item per slot (enforced by partial unique index in DB); equipping an item moves the previous one in that slot to unequipped; stackable items merge (quantity); non-stackable get one row per drop.
-- **Tests:** at least one happy-path + one failure-path test.
+## 7. Next-step briefing (5.3)
+- **Goal:** Stackable consumables: `POST /api/inventory/use` — health potion heals HP (capped at maxHp); energy tonic restores energy (capped at ENERGY_MAX). Only consumable type items can be used. Consumable is consumed (quantity -1, removed when 0).
+- **Docs:** DATABASE.md (§004_inventory), GAME_DESIGN.md §Items, BALANCE.md (effect format: 'heal:50', 'energy:25').
+- **Files to create/modify:** extend `inventoryService.js` with `useConsumable(characterId, itemId)`, extend `inventory.js` route.
+- **Key rules:** parse `effect` field from items table ('heal:N' or 'energy:N'); validate character has the item in inventory (quantity >= 1); apply effect; decrement quantity; remove row when quantity reaches 0; return updated inventory listing.
+- **Tests:** happy-path heal, happy-path energy, use on non-consumable rejected, insufficient quantity, effect capped at maxHp/energyMax.
 
 ## 8. Open Known Issues
 STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).