step 10.12: 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:** 10.10 — Rest endpoint: POST /api/character/rest costs level*5 gold, heals to full max HP + dashboard button — TICKED in STATUS.md
-- **Next step:** Phase 10.11 — Natural HP regeneration: +1% max HP/min, lazy computation, new migration adds hp_updated_at
+- **Last completed step:** 10.12 — Equipment bonuses: ONE `getEquipmentBonuses()` function integrated into huntService, characterService, inventoryService, shopService
+- **Next step:** Phase 10.13 — Starter kit: createCharacter grants class-appropriate weapon + 2 Minor Healing Potions
 - **Updated:** 2026-10-23
 - **Was the last session cut off mid-task?** No
 
@@ -13,31 +13,28 @@
 | Command | Expected |
 |---|---|
 | `npm install` | succeeds |
-| `npm run migrate` | applies 001–006 / "nothing to do" |
-| `npm test` | **227 passing, 0 failing** (85 unit + 142 integration incl. 5 rest endpoint tests) |
+| `npm run migrate` | applies 001–007 / "nothing to do" |
+| `npm test` | **249 passing, 0 failing** (97 unit + 152 integration incl. 4 equipment bonus tests) |
 | `npm run seed:dev` | creates demo user "demo"/"demo123", hero "Aldric" (warrior), starter gear |
 | `npm start` + `curl localhost:3000/` | 200 HTML landing page |
 | Open `/game.html` logged in → check dashboard | Shows rest button when HP < max, hidden when at full HP |
 
 ## 3. What exists now (files that matter)
-- `src/services/characterService.js` — Added `rest()` function: costs level*5 gold, heals to full max HP, errors NOTHING_TO_HEAL/INSUFFICIENT_GOLD
-- `src/routes/character.js` — Added `handleRest` handler, exported `postRest`
-- `src/app.js` — Mounted `POST /api/character/rest` route
-- `public/game.html` — Added `#rest-section` div with `#rest-btn` button (hidden by default)
-- `public/css/main.css` — Added `.btn-rest` styles
-- `public/js/game.js` — Added `initRestUI()`, `handleRest()`, calls `initRestUI` from `loadCharacter`, attaches click handler
-- `tests/integration/step-10.10.test.js` — 5 tests (happy heal, full HP rejection, insufficient gold, cross-user isolation, level scaling)
+- `src/game/equipment.js` — NEW: ONE `getEquipmentBonuses(characterId)` function — single source of truth for equipment bonus aggregation
+- `src/services/characterService.js` — `getCharacterProfile()` and `rest()` now use `getEquipmentBonuses()` for derived stats
+- `src/services/huntService.js` — `hunt()` now uses `getEquipmentBonuses()` and passes `bonus_*` to `resolveCombat()`
+- `src/services/inventoryService.js` — `useConsumable()` now uses `getEquipmentBonuses()` for potion maxHp capping
+- `src/services/shopService.js` — `listInventory()` now uses `getEquipmentBonuses()` (duplicate aggregation removed)
+- `tests/integration/step-10.12.test.js` — NEW: 4 integration tests (derived stats include bonuses, vit raises maxHp, potion caps at equipment-inclusive maxHp, unequip removes bonuses)
 
 ## 4. Half-finished / fragile things
 - No leaderboard UI yet (stub page exists; real UI in 10.17).
-- HP never regenerates naturally; only level-up/rest restores it. (10.11 next)
 - 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).
-- Starter gear documented but not auto-created on character creation.
-- `GET /api/zones` documented in API.md but not implemented (Issue #2).
+- Starter gear not auto-created on character creation (10.13 next).
+- `GET /api/zones` documented in API.md but not implemented.
+- Material sell prices use hero-level formula; BALANCE.md says item-level formula (10.14).
 - Mobile nav uses emoji icons (⚔️ 🏕️ 🎒) — verify they render acceptably on all platforms.
-- **10.11 next:** Natural HP regeneration — +1% max HP/min, lazy computation like energy, migration adds hp_updated_at
 
 ## 5. Decisions & deviations from the docs
 - D-004..D-007 in `docs/DECISIONS.md` (combat rounds, equipment counted once, session store, clock).
@@ -73,6 +70,7 @@
 - Character profile GET returns `{ ok: true, data: { character, derived, energy } }` — fields nested under `character`, `derived`, `energy`.
 - Register returns 201 (Created), not 200.
 - Character creation returns 201 (Created), not 200.
+- Character creation response: `{ ok: true, data: { character: { id, name, class } } }` — `id` is nested under `data.character`, NOT `data.id`.
 - Expedition start uses `defId` in request body (not `expeditionId`).
 - Expedition claim uses `expeditionId` in request body.
 - Expedition start response returns `data.expedition.id` — capture this for claim.
@@ -97,10 +95,10 @@
 - **10.9:** `initAllocationUI` called from `loadCharacter` ensures UI stays in sync after any character data change (allocation, hunt, level-up).
 - **10.10:** `setupHero` helper must use `.then()` chain (not `return async () => { ... }`) — the latter returns a function that doesn't execute when awaited.
 - **10.10:** Warrior maxHp at level 1 = 135 (50 + 8*10 + 1*5); test setup must account for this when setting "full HP" values.
+- **10.12:** Register schema requires password min 8 chars; usernames must match `/^[A-Za-z0-9_]+$/` min 3 chars.
+- **10.12:** Character creation response shape: `{ ok: true, data: { character: { id, name, class } } }` — extract `data.character.id`, NOT `data.id`.
 
 ## 7. Next-step briefing
-- **Next step: 10.11** — Natural HP regeneration: +1% max HP/min, computed lazily like energy.
-- New migration (next unused number, likely 007) adds `hp_updated_at INTEGER` column to characters table; backfill existing rows with `energy_updated_at`.
-- Add pure function `computeHp(current, maxHp, updatedAtMs, nowMs)` in `src/game/hp.js` with unit tests (partial minute, cap at max, clock backwards, large gap).
-- Apply computeHp before HP checks in: hunting, `getCharacterProfile`, potion use, and rest.
-- Heals/damage must set `hp_updated_at = now`.
+- **Next step: 10.13** — Starter kit: `createCharacter` in `characterService.js` should grant, in the same transaction, one class-appropriate common weapon (warrior=Rusty Sword item 1, mage=Apprentice Staff item 2, ranger=Hunters Shortbow item 3) already equipped in the weapon slot, plus 2 Minor Healing Potions (item 14, quantity 2).
+- Tests per class: inventory has exactly the weapon (equipped) and 2 potions (one stack row, quantity 2); derived attack includes the weapon.
+- Need to modify `createCharacter` function and add integration tests.