feat: deploy adventure wallet progression

ADVENTURE.md

@@ -0,0 +1,49 @@
+# Battle and learning settlement
+
+`POST /player/adventure` uses the existing JWT user identity and existing
+`user_wallets` balance. It never imports the old client-local coin save.
+
+Actions:
+
+- `snapshot`: wallet, level, experience, health, enrollments and current battle.
+- `start`, `encounter`: create/resume one battle per account; response contains session ID and question without the answer.
+- `answer`, `session`, `turn`, `choice`: server grades the answer. Correct removes one of three hearts; wrong removes ten HP. Victory adds ten coins and no experience. Duplicate identical last-turn submission is idempotent.
+- `escape`, `session`: closes an active battle without a reward.
+- `rest`: restores health for free when not in battle.
+- `recover`: spends five coins for up to thirty HP, only when injured and out of battle.
+- `enroll`, `chapter`: spends twenty coins once for a published chapter.
+- `complete`, `chapter`, `answers`: validates option indexes against the server chapter catalog; grants twenty learning experience once.
+
+HP maximum is 10, 15, 20, 25, 30 for levels 1–5. Level requirements are
+40, 60, 80, 100 experience. Only chapter completion grants experience.
+
+## Deployment
+
+Run `npm run db:migrate` with the target database environment before deploying
+the new backend, then build/restart it and deploy the paired frontend. The
+migration adds a nullable JSON `adventure` column to `user_wallets` and can be
+run repeatedly. It does not change existing balances or grant old local coins.
+Do not run the new entity against a database without the migration.
+
+Database mode locks the wallet row and atomically saves progress, balance and
+transaction history. Existing spend/earn operations now lock the same wallet
+row so mall payments cannot overwrite adventure rewards. Memory mode supports
+development/tests only and is not durable across server restarts.
+
+`adventure_chapters.json` currently contains the two published chapter quizzes
+from hello-agents and happy-llm. Update it with the corresponding frontend book
+package when publishing a new chapter. Two chapters can reach level 2; levels
+3–5 need additional published learning content. Completed chapters and defeated
+encounters persist per account. No client-provided coin, damage or XP amounts
+are accepted. Encounter proximity and movement are still client-authoritative;
+this is not a server-authoritative world simulation.
+
+## Verification
+
+`npm run build`, `npm test`, and `npm run test:adventure`.
+The adventure suite covers replayed/concurrent victory and enrollment requests,
+wrong answers, insufficient funds, cross-account battle access, and chapter
+rewards. On macOS with the sibling frontend and Godot installed it also runs the
+real Godot API client against an isolated NestJS HTTP server using a test-only
+guard. Production JWT validation is unchanged. MySQL migration/locking must also
+be exercised in the target database environment before rollout.