step 5.1: 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:** 4.5 (hunt UI — zones endpoint, combat-log endpoint, zone cards, hunt button, result panel, combat log replay)
+- **Last completed step:** 5.1 (inventory migration verified — already existed from step 4.4 review, applies clean)
-- **Next step:** 5.1 — inventory migration (`004_inventory.sql`)
+- **Next step:** 5.2 — inventory/equipment services + routes (list, equip, unequip, slots)
 - **Updated:** 2026-10-20
 - **Was the last session cut off mid-task?** No
 
@@ -27,13 +27,14 @@
 - `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.
 - `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).
+- No inventory/equipment system yet (Phase 5 steps 5.2–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`.
@@ -50,11 +51,12 @@
 - 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.
 
-## 7. Next-step briefing (5.1)
+## 7. Next-step briefing (5.2)
-- **Goal:** Create `004_inventory.sql` migration (inventory table + starting items for new heroes).
+- **Goal:** Services + routes for inventory management: list inventory, equip, unequip. Slots: weapon, armor, trinket. Equipment modifies derived stats via `calcDerived()`.
-- **Docs:** DATABASE.md, GAME_DESIGN.md §Items.
+- **Docs:** DATABASE.md (§004_inventory), GAME_DESIGN.md §Items, BALANCE.md.
-- **Files:** `src/db/migrations/004_inventory.sql`.
+- **Files to create:** `src/services/inventoryService.js`, `src/routes/inventory.js`.
-- **Schema:** `inventory` table (`id, character_id, item_id, quantity, equipped_slot NULL, acquired_at`), FK constraints. Starting items: class-appropriate common weapon (auto-equipped) + 2 Minor Healing Potions on character creation.
+- **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.
 
 ## 8. Open Known Issues
 STATUS.md issues 1–6 (balance, dangling `seed` script, restart test, equipment-in-combat, HP regen, zone min_level balance).

STATUS.md

@@ -8,7 +8,7 @@
 
 ## Current Focus
 - **Phase:** 5
-- **Step:** 5.1
+- **Step:** 5.2
 - **Blocked?** No
 - **Last verified working command:** `npm test` — 98/98 passing (74 unit + 29 integration), 2026-10-20 step 4.5
 
@@ -71,7 +71,8 @@
   *Verified:* `GET /api/zones` + `GET /api/combat-log` endpoints; zone cards with locked/unlocked states; Hunt button with energy cost display; result panel showing victory/defeat, XP, gold, loot, level-up; combat log replay; energy re-sync after hunt. 98/98 tests pass (5 new integration tests).
 
 ## Phase 5 — Inventory & Equipment  (docs: GAME_DESIGN §Items, DATABASE)
-- [ ] **5.1** Migration `004_inventory.sql`.
+- [x] **5.1** Migration `004_inventory.sql`.
+  *Acceptance:* migration creates inventory table with FK constraints and indexes.
 - [ ] **5.2** Services + routes: list inventory, equip, unequip (slots: weapon, armor, trinket). Equipment modifies derived stats.
 - [ ] **5.3** Stackable consumables: `POST /api/inventory/use` (health potion heals; energy tonic restores energy, capped).
 - [ ] **5.4** UI: inventory grid, equipment panel, tooltips with stats.
@@ -144,6 +145,7 @@ Severity: `blocker` / `major` / `minor` / `cosmetic`. Status: `open` / `fixing`
 
 ## Session Log
 _Format:_ `YYYY-MM-DD | step | what changed | result`
+- 2026-10-20 | 5.1 | Verified 004_inventory.sql migration (inventory table, FK constraints, indexes) applies clean; all tests pass | 98/98 tests pass
 - 2026-10-20 | 4.5 | Added `GET /api/zones` (zoneService + zones route), `GET /api/combat-log` (combatLogService + combatLog route); extended game.html with zone list/combat log/result panels; rewrote game.js with hunt UI (zone cards, hunt button, result display, combat log replay, toast notifications); added CSS for zone cards/combat log/toasts; 5 new integration tests | 98/98 tests pass
 - 2026-10-20 | review | Fixed `npm test` (ran 62 of 79 tests; auth/combat/health were skipped by an unquoted glob). Rewrote combat (slower side never attacked; mage bonus dead; hpRemaining wrong on loss). Rewrote huntService (XP not deducted on level-up, unspent points overwritten, deaths never counted, min_level ignored, stackable loot duplicated, duplicate stat formulas). Fixed nextTickInSec (was time-to-full). Added utils/time.js, WeakMap stmt cache, session store unref, ok:false error envelope, removed connect-sqlite3 | 93/93 tests pass; smoke test OK
 - 2026-10-20 | 4.4 | Created 004_inventory.sql + 006_logs.sql migrations; fixed huntService transaction (db.transaction() returns wrapper, must call separately); added huntService to helpers.js cache invalidation; session middleware uses memory store in tests | 62/62 tests pass, hunt endpoint working