fix(studio): Add solid floor collision, live 3D gizmo dragging, inspector property sync, and nudge shortcuts

- Creator Studio: Visual behavior & property inspector, GLB model importer, binary persistence
- Trust & Safety: 18+ TOS confirmation (DOB removed), creator guidelines & briefing card on join, in-game reporting HUD
- Test Harness: Add --filter, --skip-backend, --skip-godot to run_checkpoint_tests.py

.gitignore

@@ -12,3 +12,7 @@ Thumbs.db
 # Godot UID files (regenerated from path)
 *.uid
 assets/build_info.json
+
+# Dynamic uploads
+uploads/
+backend/uploads/

AGENTS.md

@@ -0,0 +1,40 @@
+# ModBison (Project & Agent Guidelines)
+
+> **CRITICAL REBRANDING NOTICE**
+> - **Game Name**: **ModBison** (formerly `agp-game`).
+>   - "ModBison" represents a play on game modification and the 1960s British "mod" subculture, adhering to the user's "bison" project naming convention (e.g. host machine `cloudbison`, Windows client machine `pinkbison`, social platform `WiseBison`).
+> - **In-Game Currency**: **Buffalo Chips** (formerly `Credits` / `CR`).
+>   - Named playfully after bison poop. Displayed throughout all UI menus, wallet, marketplace, and creator payout screens as "Buffalo Chips".
+> - **Git Repository**:
+>   - Local clone path: `/home/daddy/modbison` (symlinked as `/home/daddy/agp-game-dev` for backwards compatibility).
+>   - Gitea repository name: `modbison`
+>   - Clone URL: `http://localhost:3000/daddy/modbison.git`
+>   - Web UI: `https://git.cloudbison.duckdns.org/daddy/modbison`
+> - **Binaries & Exports**:
+>   - Windows: `modbison.exe` (legacy alias `agp-game.exe` maintained for backwards compatibility)
+>   - Linux: `modbison.x86_64`
+
+---
+
+## Architecture Overview
+
+1. **Client**: Godot 4.6.2 (GDScript).
+   - Headless engine binary located at `~/godot/godot`.
+   - Export presets defined in `export_presets.cfg`.
+   - Main scenes in `res://scenes/` (`main_menu.tscn`, `world_3d.tscn`, `wallet_ui.tscn`, `marketplace_ui.tscn`, `selling_payout_ui.tscn`, etc.).
+   - Scripts in `res://scripts/`.
+
+2. **Backend**: FastAPI + SQLAlchemy (asyncpg) + Alembic in `backend/`.
+   - Python environment: `/home/daddy/agp/venv` (or project `.venv`).
+   - Runtime game server supervisor allocates headless Godot instances per active world session under `/tmp/modbison-game-servers`.
+
+3. **Orchestration & Playtesting (`/home/daddy/agp`)**:
+   - PM Dashboard: `http://localhost:7070` (`agp-dashboard.service`).
+   - Checkpoint system: `pm/checkpoint_ops.py` controls playtest instances (`PC1` through `PC5`).
+   - Current active checkpoint: **PC5** (backend on `http://192.168.58.138:28005`, postgres on `25545`).
+   - Building Windows package: `PYTHONPATH=. /home/daddy/agp/venv/bin/python3 -c "import pm.checkpoint_ops as ops; ops.build_exe('PC5')"`
+
+4. **Testing Protocols**:
+   - Headless smoke tests: `AGP_API_BASE_URL=http://127.0.0.1:28005 ~/godot/godot --headless --path . --script res://scripts/smoke_test_<name>.gd`
+   - Fast checkpoint tests: `PYTHONPATH=. /home/daddy/agp/venv/bin/python3 scripts/run_checkpoint_tests.py --skip-backend --filter <keyword>`
+   - Backend pytest: `PYTHONPATH=. /home/daddy/agp/venv/bin/pytest backend/tests`

CLAUDE.md

@@ -0,0 +1,18 @@
+# ModBison Guidelines for Claude Code
+
+See [AGENTS.md](AGENTS.md) for full project conventions.
+
+### Quick Reference:
+- **Game Name**: ModBison (formerly agp-game)
+- **Currency**: Buffalo Chips (formerly Credits / CR)
+- **Repo URL**: `http://localhost:3000/daddy/modbison.git` (`https://git.cloudbison.duckdns.org/daddy/modbison`)
+- **Working Tree**: `/home/daddy/modbison` (or `/home/daddy/agp-game-dev`)
+- **Windows Executable**: `modbison.exe`
+- **Linux Executable**: `modbison.x86_64`
+
+### Commands:
+- **Run tests**:
+  - Backend: `PYTHONPATH=. /home/daddy/agp/venv/bin/pytest backend/tests`
+  - Godot UI smoke tests: `AGP_API_BASE_URL=http://127.0.0.1:28004 ~/godot/godot --headless --path . --script res://scripts/smoke_test_<name>.gd`
+- **Rebuild PC4 Windows package**:
+  - `PYTHONPATH=. /home/daddy/agp/venv/bin/python3 -c "import pm.checkpoint_ops as ops; ops.build_exe('PC4')"`

README.md

@@ -1,3 +1,129 @@
-# agp-game
+# ModBison
 
-Agentic Game Platform - Godot game built by autonomous agents
+> **Godot 4 Multiplayer Sandbox Platform**  
+> Customizable 3D avatars, real-time multiplayer worlds, in-game building tools, social community hubs, and a creator economy powered by **Buffalo Chips**.
+
+---
+
+## 🦬 About ModBison
+
+**ModBison** (formerly `agp-game`) is a collaborative sandbox game and platform built in Godot 4 and Python FastAPI. 
+
+* **The Name**: "ModBison" is a double play on game modification and the 1960s British "mod" youth subculture, aligning with the host and infrastructure naming convention (`cloudbison`, `pinkbison`, `WiseBison`).
+* **The Currency**: **Buffalo Chips** — the in-game virtual currency used for marketplace trading, creator selling, and cash payouts (a playful reference to bison poop).
+
+---
+
+## 🏛️ Architecture Overview
+
+The platform consists of two integrated environments:
+
+1. **Client & Game Server (`modbison`)**:
+   - Built with **Godot 4.6.2** (GDScript).
+   - Headless Godot dedicated server (`scenes/server.tscn`) spawned per active world session via high ENet ports.
+   - Dual-platform export configuration: Windows Desktop (`modbison.exe`) and Linux (`modbison.x86_64`).
+   - Binary chunk streaming and client-side interpolation.
+
+2. **Backend & Orchestration Platform (`agp`)**:
+   - **FastAPI** (Python 3.12) REST API with **PostgreSQL** (asyncpg) and **Alembic** migrations.
+   - **Redis** for real-time presence heartbeats and pub/sub messaging.
+   - **Game Server Supervisor**: Dynamic headless Godot instance orchestrator allocating runtime servers in `/tmp/modbison-game-servers`.
+   - **PM Dashboard & Checkpoints**: Live orchestration dashboard running at `http://localhost:7070` managing Package Checkpoints (**PC1** through **PC4**).
+
+---
+
+## ✨ What Has Been Built (Feature Summary)
+
+### 1. 👤 3D Avatar & Customization Engine
+* **Canonical Rig**: 24-bone skeleton supporting attachment sockets for Head, Hair, Face, Chest, Pants, Left/Right Hand, Left/Right Foot, and Accessories.
+* **Customization Studio** (`scenes/avatar_customization.tscn`): Full 3D turntable preview, orbit camera controls, slot-based equipment, RGB tint pickers, and backend persistence (`/api/avatar/loadout`).
+* **Multiplayer Replication**: Remote players receive complete avatar loadout dictionaries via RPC upon joining, dynamically assembling meshes and materials in real time.
+* **Solid Double-Sided Rendering**: Fixed polygon winding order and material setups to ensure characters render fully solid from all camera angles.
+
+### 2. 🌍 Multiplayer World & Chunk Streaming
+* **Dedicated Server Architecture**: Server-authoritative player movement, client prediction, reconciliation, and collision boundaries.
+* **Chunk Streaming**: Binary stream encoding/decoding (`chunk_codec.py` / `chunk_data_decoder.gd`) enabling real-time streaming of world geometry, collision boxes, and dynamic props as players explore.
+* **Stable Spawn System**: Server-authoritative solid ground anchoring ensuring players never fall into the void upon connection.
+
+### 3. 🛠️ In-Game World Editor & Sandboxed Scripting
+* **Runtime World Editor** (`scripts/editor/`): In-game tool registry, block/prop palette, selection manager, raycast placement/deletion, and undo/redo action stacks.
+* **Chunk Persistence** (`chunk_save_service.gd`): Saves player modifications and created structures back to the world backend.
+* **Rule-Based Scripting** (`scripts/scripting/`): Sandboxed behavior interpreter (`script_interpreter.gd`, `script_rule.gd`) allowing props to trigger gameplay actions, inventory changes, and spawn events.
+* **In-Game HUD Bar**: Hotkey-driven overlay bar giving players instant access to build tools and menus while inside a live world.
+
+### 4. 👥 Social, Chat & Clans
+* **Friends & Presence** (`scenes/friends_presence_ui.tscn`): Friend requests, accept/decline flows, and live online/in-world presence heartbeats via Redis.
+* **Multi-Channel Chat** (`scenes/chat_ui.tscn`): Direct messaging (DM), group chat, and spatial in-world chat with automated text filtering (`text_filter.py`).
+* **Groups & Clans** (`scenes/groups_ui.tscn`): Group creation, member roles, descriptions, and membership rosters.
+
+### 5. 💰 Virtual Economy & Creator Payouts
+* **In-Game Currency**: **Buffalo Chips** displayed across all menus, wallets, listings, and payout screens.
+* **Wallet UI** (`scenes/wallet_ui.tscn`): Live balance display, quick-purchase packs (+100, +500, +1,000, +5,000 Buffalo Chips), and transaction history ledger.
+* **Marketplace UI** (`scenes/marketplace_ui.tscn`): Browse items for sale, filter by price in Buffalo Chips, search catalog, and instant purchase with inventory delivery.
+* **Creator Selling & Payouts** (`scenes/selling_payout_ui.tscn`): Catalog item listing, price configuration, escrow tracking (Available, In Escrow, Lifetime Earned), and cash payout requests (minimum 100 Buffalo Chips).
+
+### 6. 🌐 Discovery & Catalog
+* **World Discovery UI** (`scenes/discovery_ui.tscn`): Public world browser with search by title, tags, or category.
+* **Trending Algorithm**: Decay-weighted play counts ranking popular worlds on the discovery front page.
+
+---
+
+## 🎮 In-Game Controls & Hotkeys
+
+| Key | Action |
+| :--- | :--- |
+| **`W` `A` `S` `D`** | Move character |
+| **`Space`** | Jump |
+| **`Mouse`** | Look / Camera rotation |
+| **`T`** or **`Enter`** | Open Chat |
+| **`Tab`** or **`F1`** | Open Friends & Social Panel |
+| **`F2`** | Toggle In-Game World Editor |
+| **`ESC`** | Close current modal / Toggle In-Game HUD Menu |
+
+---
+
+## 🚀 Development, Testing & Builds
+
+### Automated Smoke Tests (Headless Godot)
+All UI panels and client subsystems have headless GDScript smoke tests:
+```bash
+# Set target backend (e.g. PC4 playtest instance)
+export AGP_API_BASE_URL=http://127.0.0.1:28004
+
+# Run individual UI & subsystem smoke tests
+~/godot/godot --headless --path . --script res://scripts/smoke_test_main_menu_full_flow.gd
+~/godot/godot --headless --path . --script res://scripts/smoke_test_marketplace_ui.gd
+~/godot/godot --headless --path . --script res://scripts/smoke_test_wallet_ui.gd
+~/godot/godot --headless --path . --script res://scripts/smoke_test_selling_payout_ui.gd
+~/godot/godot --headless --path . --script res://scripts/smoke_test_avatar_in_world.gd
+```
+
+### Backend Test Suite
+```bash
+# Run 335+ FastAPI & SQLAlchemy test suite
+PYTHONPATH=. /home/daddy/agp/venv/bin/pytest backend/tests
+```
+
+### Building Release Binaries
+```bash
+# Export Linux and Windows binaries
+scripts/build.sh
+
+# Or build pre-configured Windows package for current checkpoint (PC4):
+PYTHONPATH=. /home/daddy/agp/venv/bin/python3 -c "import pm.checkpoint_ops as ops; ops.build_exe('PC4')"
+```
+Output artifacts:
+- Windows: `export/windows/modbison.exe` (or `agp/playtest/PC4/build/windows/modbison.exe`)
+- Linux: `export/linux/modbison.x86_64`
+
+---
+
+## 📦 Project Links & Configuration
+
+* **Gitea Repository**: `http://localhost:3000/daddy/modbison.git`
+* **Web Interface**: [https://git.cloudbison.duckdns.org/daddy/modbison](https://git.cloudbison.duckdns.org/daddy/modbison)
+* **Active Playtest Instance**: **PC4**
+  - Backend URL: `http://192.168.58.138:28004`
+  - Database: PostgreSQL on port `25544`
+* **PM Dashboard**: `http://localhost:7070`
+* **Working Directory**: `/home/daddy/modbison` (symlinked as `/home/daddy/agp-game-dev`)

assets/audio/bell.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://dvln67rbfmcnt"
+path="res://.godot/imported/bell.wav-c9e8b15c72938ff0cc4247d900f73a2f.sample"
+
+[deps]
+
+source_file="res://assets/audio/bell.wav"
+dest_files=["res://.godot/imported/bell.wav-c9e8b15c72938ff0cc4247d900f73a2f.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

assets/audio/chime.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://uvtdcjsrs4oc"
+path="res://.godot/imported/chime.wav-cbf50c3ed007f7bda834f64e66ec1ffa.sample"
+
+[deps]
+
+source_file="res://assets/audio/chime.wav"
+dest_files=["res://.godot/imported/chime.wav-cbf50c3ed007f7bda834f64e66ec1ffa.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

assets/audio/click.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://cxiiaesukt1ci"
+path="res://.godot/imported/click.wav-726094e36c7052fadb6392aaf7409595.sample"
+
+[deps]
+
+source_file="res://assets/audio/click.wav"
+dest_files=["res://.godot/imported/click.wav-726094e36c7052fadb6392aaf7409595.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

assets/audio/coin.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://cssl2kgkc53is"
+path="res://.godot/imported/coin.wav-e1bec9e9502a5df388e6fd33d4bb5689.sample"
+
+[deps]
+
+source_file="res://assets/audio/coin.wav"
+dest_files=["res://.godot/imported/coin.wav-e1bec9e9502a5df388e6fd33d4bb5689.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

assets/audio/door_open.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://c10qifwxnhin6"
+path="res://.godot/imported/door_open.wav-d530c3547ac0143568ab23d68285c71c.sample"
+
+[deps]
+
+source_file="res://assets/audio/door_open.wav"
+dest_files=["res://.godot/imported/door_open.wav-d530c3547ac0143568ab23d68285c71c.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

assets/audio/fanfare.wav.import

@@ -0,0 +1,24 @@
+[remap]
+
+importer="wav"
+type="AudioStreamWAV"
+uid="uid://bl6jimdmb1d3u"
+path="res://.godot/imported/fanfare.wav-e0524ad6f859b26eee9ccfabfec4f302.sample"
+
+[deps]
+
+source_file="res://assets/audio/fanfare.wav"
+dest_files=["res://.godot/imported/fanfare.wav-e0524ad6f859b26eee9ccfabfec4f302.sample"]
+
+[params]
+
+force/8_bit=false
+force/mono=false
+force/max_rate=false
+force/max_rate_hz=44100
+edit/trim=false
+edit/normalize=false
+edit/loop_mode=0
+edit/loop_begin=0
+edit/loop_end=-1
+compress/mode=2

assets/avatars/catalog.json

@@ -31,6 +31,14 @@
       "display_name": "Ponytail",
       "mount_bone": "HeadTop"
     },
+    "hair_waterbuffalo_01": {
+      "type": "attachment",
+      "slot": "hair",
+      "path": "res://assets/avatars/hair_waterbuffalo_01.glb",
+      "version": "1.0.0",
+      "display_name": "Water Buffalo Lodge Hat",
+      "mount_bone": "HeadTop"
+    },
     "face_glasses_01": {
       "type": "attachment",
       "slot": "face",
@@ -71,6 +79,14 @@
       "display_name": "Left Glove",
       "mount_bone": "LeftHand"
     },
+    "left_hand_wristband_01": {
+      "type": "attachment",
+      "slot": "left_hand",
+      "path": "res://assets/avatars/left_hand_wristband_01.glb",
+      "version": "1.0.0",
+      "display_name": "Left Gold Band",
+      "mount_bone": "LeftHand"
+    },
     "right_hand_glove_01": {
       "type": "attachment",
       "slot": "right_hand",
@@ -79,6 +95,14 @@
       "display_name": "Right Glove",
       "mount_bone": "RightHand"
     },
+    "right_hand_wristband_01": {
+      "type": "attachment",
+      "slot": "right_hand",
+      "path": "res://assets/avatars/right_hand_wristband_01.glb",
+      "version": "1.0.0",
+      "display_name": "Right Gold Band",
+      "mount_bone": "RightHand"
+    },
     "left_foot_boot_01": {
       "type": "attachment",
       "slot": "left_foot",
@@ -87,6 +111,14 @@
       "display_name": "Left Boot",
       "mount_bone": "LeftFoot"
     },
+    "left_foot_sneaker_01": {
+      "type": "attachment",
+      "slot": "left_foot",
+      "path": "res://assets/avatars/left_foot_sneaker_01.glb",
+      "version": "1.0.0",
+      "display_name": "Left Sneaker",
+      "mount_bone": "LeftFoot"
+    },
     "right_foot_boot_01": {
       "type": "attachment",
       "slot": "right_foot",
@@ -95,6 +127,14 @@
       "display_name": "Right Boot",
       "mount_bone": "RightFoot"
     },
+    "right_foot_sneaker_01": {
+      "type": "attachment",
+      "slot": "right_foot",
+      "path": "res://assets/avatars/right_foot_sneaker_01.glb",
+      "version": "1.0.0",
+      "display_name": "Right Sneaker",
+      "mount_bone": "RightFoot"
+    },
     "accessory_belt_01": {
       "type": "attachment",
       "slot": "accessory",

assets/avatars/hair_waterbuffalo_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://dbpg1j858253k"
+path="res://.godot/imported/hair_waterbuffalo_01.glb-c029a4cc5c7f4da664b2a6ff40a4d5a5.scn"
+
+[deps]
+
+source_file="res://assets/avatars/hair_waterbuffalo_01.glb"
+dest_files=["res://.godot/imported/hair_waterbuffalo_01.glb-c029a4cc5c7f4da664b2a6ff40a4d5a5.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/avatars/left_foot_sneaker_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://cdu5ncc6txi2a"
+path="res://.godot/imported/left_foot_sneaker_01.glb-58178eceb7610b00fcdd19ec562d32ee.scn"
+
+[deps]
+
+source_file="res://assets/avatars/left_foot_sneaker_01.glb"
+dest_files=["res://.godot/imported/left_foot_sneaker_01.glb-58178eceb7610b00fcdd19ec562d32ee.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/avatars/left_hand_wristband_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://bd2pj86s3jgw6"
+path="res://.godot/imported/left_hand_wristband_01.glb-bbb8beaefb98cfa41b275a9c621f1f25.scn"
+
+[deps]
+
+source_file="res://assets/avatars/left_hand_wristband_01.glb"
+dest_files=["res://.godot/imported/left_hand_wristband_01.glb-bbb8beaefb98cfa41b275a9c621f1f25.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/avatars/right_foot_sneaker_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://da2jib466th8w"
+path="res://.godot/imported/right_foot_sneaker_01.glb-54204fa9ac3cba3033c3591ef48c54c7.scn"
+
+[deps]
+
+source_file="res://assets/avatars/right_foot_sneaker_01.glb"
+dest_files=["res://.godot/imported/right_foot_sneaker_01.glb-54204fa9ac3cba3033c3591ef48c54c7.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/avatars/right_hand_wristband_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://b64ejiiluvql4"
+path="res://.godot/imported/right_hand_wristband_01.glb-65f50dbbe9aaf5f2de1555fec5ca3385.scn"
+
+[deps]
+
+source_file="res://assets/avatars/right_hand_wristband_01.glb"
+dest_files=["res://.godot/imported/right_hand_wristband_01.glb-65f50dbbe9aaf5f2de1555fec5ca3385.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/editor/object_catalog.json

@@ -30,6 +30,18 @@
       "display_name": "Treasure Chest",
       "category": "interactables"
     },
+    "buffalo_chip_coin": {
+      "asset_id": "props/buffalo_chip_coin.glb",
+      "type": "prop",
+      "display_name": "Buffalo Chip Coin",
+      "category": "props"
+    },
+    "bison": {
+      "asset_id": "props/bison.glb",
+      "type": "prop",
+      "display_name": "Bison",
+      "category": "nature"
+    },
     "spawn_point": {
       "asset_id": "",
       "type": "spawn_point",

assets/props/bison.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://wa7kf5fvrdh1"
+path="res://.godot/imported/bison.glb-caef5252d8e08046747c7628b6609f07.scn"
+
+[deps]
+
+source_file="res://assets/props/bison.glb"
+dest_files=["res://.godot/imported/bison.glb-caef5252d8e08046747c7628b6609f07.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/props/bison_04bizontexture.jpg.import

@@ -0,0 +1,43 @@
+[remap]
+
+importer="texture"
+type="CompressedTexture2D"
+uid="uid://oemjaiyc1jor"
+path="res://.godot/imported/bison_04bizontexture.jpg-ee62bcbf71190dd9c3260c488d0f5226.ctex"
+metadata={
+"vram_texture": false
+}
+generator_parameters={
+"md5": "62ac14285e2f49777af903582f16d021"
+}
+
+[deps]
+
+source_file="res://assets/props/bison_04bizontexture.jpg"
+dest_files=["res://.godot/imported/bison_04bizontexture.jpg-ee62bcbf71190dd9c3260c488d0f5226.ctex"]
+
+[params]
+
+compress/mode=0
+compress/high_quality=false
+compress/lossy_quality=0.7
+compress/uastc_level=0
+compress/rdo_quality_loss=0.0
+compress/hdr_compression=1
+compress/normal_map=0
+compress/channel_pack=0
+mipmaps/generate=true
+mipmaps/limit=-1
+roughness/mode=0
+roughness/src_normal=""
+process/channel_remap/red=0
+process/channel_remap/green=1
+process/channel_remap/blue=2
+process/channel_remap/alpha=3
+process/fix_alpha_border=true
+process/premult_alpha=false
+process/normal_map_invert_y=false
+process/hdr_as_srgb=false
+process/hdr_clamp_exposure=false
+process/size_limit=0
+detect_3d/compress_to=1

assets/props/buffalo_chip_coin.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://dxjew7eex2jh4"
+path="res://.godot/imported/buffalo_chip_coin.glb-ccee212ee6fb7ddcc2555bc23ea60f4b.scn"
+
+[deps]
+
+source_file="res://assets/props/buffalo_chip_coin.glb"
+dest_files=["res://.godot/imported/buffalo_chip_coin.glb-ccee212ee6fb7ddcc2555bc23ea60f4b.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/props/chest.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://kik8lcd3jp7x"
+path="res://.godot/imported/chest.glb-22b4964b33afcd001921fbaa02f82b8a.scn"
+
+[deps]
+
+source_file="res://assets/props/chest.glb"
+dest_files=["res://.godot/imported/chest.glb-22b4964b33afcd001921fbaa02f82b8a.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/props/crate_small.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://n18xbm0q3jai"
+path="res://.godot/imported/crate_small.glb-e6fdaf315193cd20d4514609adaa68f2.scn"
+
+[deps]
+
+source_file="res://assets/props/crate_small.glb"
+dest_files=["res://.godot/imported/crate_small.glb-e6fdaf315193cd20d4514609adaa68f2.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/props/lamp_post_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://b3nfmxbm87pl3"
+path="res://.godot/imported/lamp_post_01.glb-eea7873c5c7bafcb4d19a09b9d97e53c.scn"
+
+[deps]
+
+source_file="res://assets/props/lamp_post_01.glb"
+dest_files=["res://.godot/imported/lamp_post_01.glb-eea7873c5c7bafcb4d19a09b9d97e53c.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/props/rock_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://boi3fsj4ehqvb"
+path="res://.godot/imported/rock_01.glb-b0b73bccccfa933f3863bdc2afcb3246.scn"
+
+[deps]
+
+source_file="res://assets/props/rock_01.glb"
+dest_files=["res://.godot/imported/rock_01.glb-b0b73bccccfa933f3863bdc2afcb3246.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

assets/props/tree_pine_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://b84vjc1c3d650"
+path="res://.godot/imported/tree_pine_01.glb-519f726dc86fdb9eefd0928153fa0181.scn"
+
+[deps]
+
+source_file="res://assets/props/tree_pine_01.glb"
+dest_files=["res://.godot/imported/tree_pine_01.glb-519f726dc86fdb9eefd0928153fa0181.scn"]
+
+[params]
+
+nodes/root_type=""
+nodes/root_name=""
+nodes/root_script=null
+nodes/apply_root_scale=true
+nodes/root_scale=1.0
+nodes/import_as_skeleton_bones=false
+nodes/use_name_suffixes=true
+nodes/use_node_type_suffixes=true
+meshes/ensure_tangents=true
+meshes/generate_lods=true
+meshes/create_shadow_meshes=true
+meshes/light_baking=1
+meshes/lightmap_texel_size=0.2
+meshes/force_disable_compression=false
+skins/use_named_skins=true
+animation/import=true
+animation/fps=30
+animation/trimming=false
+animation/remove_immutable_tracks=true
+animation/import_rest_as_RESET=false
+import_script/path=""
+materials/extract=0
+materials/extract_format=0
+materials/extract_path=""
+_subresources={}
+gltf/naming_version=2
+gltf/embedded_image_handling=1

backend/alembic/versions/0012_add_wallet_and_transactions.py

@@ -0,0 +1,90 @@
+"""add wallets and transactions ledger tables
+
+Revision ID: 0012_add_wallet_and_transactions
+Revises: 0011_add_dm_last_read
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/economy.md US-1 (task 8343bc0a730f).
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0012_add_wallet_and_transactions"
+down_revision: Union[str, None] = "0011_add_dm_last_read"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+TRANSACTION_TYPES = (
+    "credit_purchase",
+    "marketplace_purchase",
+    "marketplace_sale",
+    "escrow_release",
+    "payout",
+    "refund",
+    "admin_adjustment",
+)
+
+
+def upgrade() -> None:
+    # 1. Create transaction_type enum for Postgres
+    bind = op.get_bind()
+    if bind.dialect.name == "postgresql":
+        tx_type_enum = postgresql.ENUM(*TRANSACTION_TYPES, name="transaction_type", create_type=False)
+        tx_type_enum.create(bind, checkfirst=True)
+        tx_type_col = postgresql.ENUM(*TRANSACTION_TYPES, name="transaction_type", create_type=False)
+    else:
+        tx_type_col = sa.Enum(*TRANSACTION_TYPES, name="transaction_type")
+
+    # 2. Create wallets table
+    op.create_table(
+        "wallets",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("balance", sa.BigInteger(), server_default="0", nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.CheckConstraint("balance >= 0", name="check_wallet_balance_non_negative"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("user_id", name="uq_wallets_user_id"),
+    )
+    op.create_index(op.f("ix_wallets_user_id"), "wallets", ["user_id"], unique=True)
+
+    # 3. Create transactions table
+    op.create_table(
+        "transactions",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("wallet_id", sa.BigInteger(), nullable=False),
+        sa.Column("type", tx_type_col, nullable=False),
+        sa.Column("amount", sa.BigInteger(), nullable=False),
+        sa.Column("balance_after", sa.BigInteger(), nullable=False),
+        sa.Column("reference_type", sa.String(), nullable=True),
+        sa.Column("reference_id", sa.String(), nullable=True),
+        sa.Column("idempotency_key", sa.String(), nullable=True),
+        sa.Column("metadata_json", postgresql.JSONB(astext_type=sa.Text()) if bind.dialect.name == "postgresql" else sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(["wallet_id"], ["wallets.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("idempotency_key", name="uq_transactions_idempotency_key"),
+    )
+    op.create_index(op.f("ix_transactions_wallet_id"), "transactions", ["wallet_id"], unique=False)
+    op.create_index(op.f("ix_transactions_idempotency_key"), "transactions", ["idempotency_key"], unique=True)
+    op.create_index(op.f("ix_transactions_created_at"), "transactions", ["created_at"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_transactions_created_at"), table_name="transactions")
+    op.drop_index(op.f("ix_transactions_idempotency_key"), table_name="transactions")
+    op.drop_index(op.f("ix_transactions_wallet_id"), table_name="transactions")
+    op.drop_table("transactions")
+
+    op.drop_index(op.f("ix_wallets_user_id"), table_name="wallets")
+    op.drop_table("wallets")
+
+    bind = op.get_bind()
+    if bind.dialect.name == "postgresql":
+        sa.Enum(*TRANSACTION_TYPES, name="transaction_type").drop(bind, checkfirst=True)

backend/alembic/versions/0013_add_marketplace_tables.py

@@ -0,0 +1,146 @@
+"""add marketplace tables: catalog_items, marketplace_listings, purchases, creator_balances
+
+Revision ID: 0013_add_marketplace_tables
+Revises: 0012_add_wallet_and_transactions
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/economy.md US-3, US-4 (task 166836d55365).
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0013_add_marketplace_tables"
+down_revision: Union[str, None] = "0012_add_wallet_and_transactions"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+ITEM_TYPES = ("asset", "avatar_item", "experience_pass")
+LISTING_STATUSES = ("active", "sold", "delisted", "removed_by_moderation")
+PURCHASE_STATUSES = ("pending_escrow", "completed", "refunded", "reversed")
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    is_pg = bind.dialect.name == "postgresql"
+
+    # Enums
+    if is_pg:
+        item_type_enum = postgresql.ENUM(*ITEM_TYPES, name="catalog_item_type", create_type=False)
+        item_type_enum.create(bind, checkfirst=True)
+        item_type_col = postgresql.ENUM(*ITEM_TYPES, name="catalog_item_type", create_type=False)
+
+        listing_status_enum = postgresql.ENUM(*LISTING_STATUSES, name="marketplace_listing_status", create_type=False)
+        listing_status_enum.create(bind, checkfirst=True)
+        listing_status_col = postgresql.ENUM(*LISTING_STATUSES, name="marketplace_listing_status", create_type=False)
+
+        purchase_status_enum = postgresql.ENUM(*PURCHASE_STATUSES, name="purchase_status", create_type=False)
+        purchase_status_enum.create(bind, checkfirst=True)
+        purchase_status_col = postgresql.ENUM(*PURCHASE_STATUSES, name="purchase_status", create_type=False)
+    else:
+        item_type_col = sa.Enum(*ITEM_TYPES, name="catalog_item_type")
+        listing_status_col = sa.Enum(*LISTING_STATUSES, name="marketplace_listing_status")
+        purchase_status_col = sa.Enum(*PURCHASE_STATUSES, name="purchase_status")
+
+    # 1. catalog_items
+    op.create_table(
+        "catalog_items",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("owner_id", sa.Integer(), nullable=False),
+        sa.Column("asset_id", sa.Integer(), nullable=True),
+        sa.Column("item_type", item_type_col, nullable=False),
+        sa.Column("name", sa.String(length=100), nullable=False),
+        sa.Column("description", sa.String(length=2000), nullable=True),
+        sa.Column("metadata_json", postgresql.JSONB(astext_type=sa.Text()) if is_pg else sa.JSON(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(["owner_id"], ["users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["asset_id"], ["assets.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_catalog_items_owner_id"), "catalog_items", ["owner_id"], unique=False)
+    op.create_index(op.f("ix_catalog_items_asset_id"), "catalog_items", ["asset_id"], unique=False)
+
+    # 2. marketplace_listings
+    op.create_table(
+        "marketplace_listings",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("catalog_item_id", sa.BigInteger(), nullable=False),
+        sa.Column("seller_id", sa.Integer(), nullable=False),
+        sa.Column("price", sa.BigInteger(), nullable=False),
+        sa.Column("status", listing_status_col, server_default="active", nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.CheckConstraint("price > 0", name="check_listing_price_positive"),
+        sa.ForeignKeyConstraint(["catalog_item_id"], ["catalog_items.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["seller_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_marketplace_listings_catalog_item_id"), "marketplace_listings", ["catalog_item_id"], unique=False)
+    op.create_index(op.f("ix_marketplace_listings_seller_id"), "marketplace_listings", ["seller_id"], unique=False)
+
+    # 3. purchases
+    op.create_table(
+        "purchases",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("listing_id", sa.BigInteger(), nullable=True),
+        sa.Column("buyer_id", sa.Integer(), nullable=False),
+        sa.Column("seller_id", sa.Integer(), nullable=False),
+        sa.Column("price", sa.BigInteger(), nullable=False),
+        sa.Column("platform_fee", sa.BigInteger(), nullable=False),
+        sa.Column("seller_net", sa.BigInteger(), nullable=False),
+        sa.Column("status", purchase_status_col, server_default="pending_escrow", nullable=False),
+        sa.Column("escrow_hold_until", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(["listing_id"], ["marketplace_listings.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["buyer_id"], ["users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["seller_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_purchases_listing_id"), "purchases", ["listing_id"], unique=False)
+    op.create_index(op.f("ix_purchases_buyer_id"), "purchases", ["buyer_id"], unique=False)
+    op.create_index(op.f("ix_purchases_seller_id"), "purchases", ["seller_id"], unique=False)
+
+    # 4. creator_balances
+    op.create_table(
+        "creator_balances",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("available", sa.BigInteger(), server_default="0", nullable=False),
+        sa.Column("pending", sa.BigInteger(), server_default="0", nullable=False),
+        sa.Column("lifetime_earned", sa.BigInteger(), server_default="0", nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.CheckConstraint("available >= 0", name="check_creator_available_non_negative"),
+        sa.CheckConstraint("pending >= 0", name="check_creator_pending_non_negative"),
+        sa.CheckConstraint("lifetime_earned >= 0", name="check_creator_lifetime_non_negative"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("user_id", name="uq_creator_balances_user_id"),
+    )
+    op.create_index(op.f("ix_creator_balances_user_id"), "creator_balances", ["user_id"], unique=True)
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_creator_balances_user_id"), table_name="creator_balances")
+    op.drop_table("creator_balances")
+
+    op.drop_index(op.f("ix_purchases_seller_id"), table_name="purchases")
+    op.drop_index(op.f("ix_purchases_buyer_id"), table_name="purchases")
+    op.drop_index(op.f("ix_purchases_listing_id"), table_name="purchases")
+    op.drop_table("purchases")
+
+    op.drop_index(op.f("ix_marketplace_listings_seller_id"), table_name="marketplace_listings")
+    op.drop_index(op.f("ix_marketplace_listings_catalog_item_id"), table_name="marketplace_listings")
+    op.drop_table("marketplace_listings")
+
+    op.drop_index(op.f("ix_catalog_items_asset_id"), table_name="catalog_items")
+    op.drop_index(op.f("ix_catalog_items_owner_id"), table_name="catalog_items")
+    op.drop_table("catalog_items")
+
+    bind = op.get_bind()
+    if bind.dialect.name == "postgresql":
+        sa.Enum(*PURCHASE_STATUSES, name="purchase_status").drop(bind, checkfirst=True)
+        sa.Enum(*LISTING_STATUSES, name="marketplace_listing_status").drop(bind, checkfirst=True)
+        sa.Enum(*ITEM_TYPES, name="catalog_item_type").drop(bind, checkfirst=True)

backend/alembic/versions/0014_add_payout_requests.py

@@ -0,0 +1,68 @@
+"""add payout_requests table and payout_status enum
+
+Revision ID: 0014_add_payout_requests
+Revises: 0013_add_marketplace_tables
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/economy.md US-5 (task f5b4684f2e65).
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0014_add_payout_requests"
+down_revision: Union[str, None] = "0013_add_marketplace_tables"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+PAYOUT_STATUSES = ("pending", "approved", "paid", "rejected")
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    is_pg = bind.dialect.name == "postgresql"
+
+    if is_pg:
+        payout_status_enum = postgresql.ENUM(*PAYOUT_STATUSES, name="payout_status", create_type=False)
+        payout_status_enum.create(bind, checkfirst=True)
+        payout_status_col = postgresql.ENUM(*PAYOUT_STATUSES, name="payout_status", create_type=False)
+    else:
+        payout_status_col = sa.Enum(*PAYOUT_STATUSES, name="payout_status")
+
+    op.create_table(
+        "payout_requests",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("creator_id", sa.Integer(), nullable=False),
+        sa.Column("amount", sa.BigInteger(), nullable=False),
+        sa.Column("status", payout_status_col, server_default="pending", nullable=False),
+        sa.Column("external_ref", sa.String(length=255), nullable=True),
+        sa.Column("provider_ref", sa.String(length=255), nullable=True),
+        sa.Column("requested_by", sa.Integer(), nullable=False),
+        sa.Column("reviewed_by", sa.Integer(), nullable=True),
+        sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(["creator_id"], ["users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["requested_by"], ["users.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["reviewed_by"], ["users.id"], ondelete="SET NULL"),
+        sa.CheckConstraint("amount > 0", name="check_payout_amount_positive"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_payout_requests_creator_id", "payout_requests", ["creator_id"], unique=False)
+    op.create_index("ix_payout_requests_requested_by", "payout_requests", ["requested_by"], unique=False)
+    op.create_index("ix_payout_requests_reviewed_by", "payout_requests", ["reviewed_by"], unique=False)
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    is_pg = bind.dialect.name == "postgresql"
+
+    op.drop_index("ix_payout_requests_reviewed_by", table_name="payout_requests")
+    op.drop_index("ix_payout_requests_requested_by", table_name="payout_requests")
+    op.drop_index("ix_payout_requests_creator_id", table_name="payout_requests")
+    op.drop_table("payout_requests")
+
+    if is_pg:
+        op.execute("DROP TYPE IF EXISTS payout_status")

backend/alembic/versions/0015_add_discovery_metadata.py

@@ -0,0 +1,62 @@
+"""add discovery metadata to worlds and create world_visits table
+
+Revision ID: 0015_add_discovery_metadata
+Revises: 0014_add_payout_requests
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/discovery.md (task b377353b8167).
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0015_add_discovery_metadata"
+down_revision: Union[str, None] = "0014_add_payout_requests"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1. Add discovery metadata columns to worlds table
+    op.add_column("worlds", sa.Column("category", sa.String(length=100), nullable=True))
+    op.add_column("worlds", sa.Column("tags", postgresql.ARRAY(sa.String()), server_default="{}", nullable=True))
+    op.add_column("worlds", sa.Column("play_count", sa.Integer(), server_default="0", nullable=False))
+    op.add_column("worlds", sa.Column("last_played_at", sa.DateTime(timezone=True), nullable=True))
+
+    op.create_index("ix_worlds_category", "worlds", ["category"], unique=False)
+    op.create_index("ix_worlds_tags", "worlds", ["tags"], unique=False, postgresql_using="gin")
+
+    # 2. Create world_visits table
+    op.create_table(
+        "world_visits",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("world_id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        sa.Column("anonymous_token", sa.String(length=255), nullable=True),
+        sa.Column("visited_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(["world_id"], ["worlds.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_world_visits_world_id", "world_visits", ["world_id"], unique=False)
+    op.create_index("ix_world_visits_user_id", "world_visits", ["user_id"], unique=False)
+    op.create_index("ix_world_visits_visited_at", "world_visits", ["visited_at"], unique=False)
+    op.create_index("ix_world_visits_world_visited_at", "world_visits", ["world_id", "visited_at"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_world_visits_world_visited_at", table_name="world_visits")
+    op.drop_index("ix_world_visits_visited_at", table_name="world_visits")
+    op.drop_index("ix_world_visits_user_id", table_name="world_visits")
+    op.drop_index("ix_world_visits_world_id", table_name="world_visits")
+    op.drop_table("world_visits")
+
+    op.drop_index("ix_worlds_tags", table_name="worlds", postgresql_using="gin")
+    op.drop_index("ix_worlds_category", table_name="worlds")
+    op.drop_column("worlds", "last_played_at")
+    op.drop_column("worlds", "play_count")
+    op.drop_column("worlds", "tags")
+    op.drop_column("worlds", "category")

backend/alembic/versions/0016_content_guidelines.py

@@ -0,0 +1,30 @@
+"""add content_guidelines column to worlds table
+
+Revision ID: 0016_content_guidelines
+Revises: 0015_add_discovery_metadata
+Create Date: 2026-09-17 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0016_content_guidelines"
+down_revision: Union[str, None] = "0015_add_discovery_metadata"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Check if column already exists (in case partial run added column before version update failed)
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    cols = [c["name"] for c in insp.get_columns("worlds")]
+    if "content_guidelines" not in cols:
+        op.add_column("worlds", sa.Column("content_guidelines", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("worlds", "content_guidelines")

backend/alembic/versions/0017_add_asset_collections.py

@@ -0,0 +1,53 @@
+"""add asset_collections and collection_assets tables
+
+Revision ID: 0017_add_asset_collections
+Revises: 0016_content_guidelines
+Create Date: 2026-09-22 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0017_add_asset_collections"
+down_revision: Union[str, None] = "0016_content_guidelines"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    tables = insp.get_table_names()
+
+    if "asset_collections" not in tables:
+        op.create_table(
+            "asset_collections",
+            sa.Column("id", sa.Integer(), primary_key=True, index=True),
+            sa.Column("title", sa.String(length=255), nullable=False, index=True),
+            sa.Column("description", sa.Text(), nullable=True),
+            sa.Column("theme", sa.String(length=64), nullable=False, server_default="general", index=True),
+            sa.Column("thumbnail_url", sa.String(length=512), nullable=True),
+            sa.Column("owner_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+            sa.Column("is_public", sa.Boolean(), nullable=False, server_default=sa.text("true"), index=True),
+            sa.Column("tags", sa.String(length=512), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        )
+
+    if "collection_assets" not in tables:
+        op.create_table(
+            "collection_assets",
+            sa.Column("id", sa.Integer(), primary_key=True, index=True),
+            sa.Column("collection_id", sa.Integer(), sa.ForeignKey("asset_collections.id", ondelete="CASCADE"), nullable=False, index=True),
+            sa.Column("asset_id", sa.Integer(), sa.ForeignKey("assets.id", ondelete="CASCADE"), nullable=False, index=True),
+            sa.Column("sort_order", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        )
+
+
+def downgrade() -> None:
+    op.drop_table("collection_assets")
+    op.drop_table("asset_collections")

backend/app/dependencies.py

@@ -53,3 +53,33 @@ async def get_current_user(
 
 
 CurrentUser = Annotated[User, Depends(get_current_user)]
+
+oauth2_scheme_optional = OAuth2PasswordBearer(tokenUrl="/api/auth/login", auto_error=False)
+
+
+async def get_optional_user(
+    token: Annotated[str | None, Depends(oauth2_scheme_optional)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> User | None:
+    """Resolve the JWT bearer token to a User if present and valid, otherwise None."""
+    if not token:
+        return None
+    try:
+        payload = jwt.decode(
+            token, settings.public_pem, algorithms=[settings.ALGORITHM]
+        )
+        user_id: str | None = payload.get("sub")
+        if user_id is None:
+            return None
+        user_id_int = int(user_id)
+    except (JWTError, ValueError, TypeError):
+        return None
+
+    result = await db.execute(select(User).where(User.id == user_id_int))
+    user = result.scalar_one_or_none()
+    if user is None or not user.is_active:
+        return None
+    return user
+
+
+OptionalUser = Annotated[User | None, Depends(get_optional_user)]

backend/app/gateway/__init__.py

@@ -0,0 +1 @@
+"""WebSocket real-time gateway package."""

backend/app/gateway/ws.py

@@ -0,0 +1,538 @@
+"""Real-time WebSocket gateway.
+
+Multiplexes presence, DM, and world-chat delivery over a single WebSocket
+endpoint (docs/planning/social.md US-2, US-4).
+
+Key features:
+- Authentication via JWT token (query param or initial auth frame).
+- Scoped subscriptions to DM conversations and world channels.
+- Server-derived presence heartbeat (Redis TTL refreshed periodically).
+- Broadcast presence changes (online/offline) to mutual friends.
+- Fan-out via Redis pub/sub.
+- Thread-safe & event-loop-safe dispatch for multi-instance and test environments.
+- Graceful reconnect without duplicate delivery or orphaned state.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+import json
+import logging
+from typing import Any
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, status
+from jose import JWTError, jwt
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+import redis.asyncio as aioredis
+
+from app.config import settings
+from app.database import async_session_factory, get_db
+from app.models.chat import ConversationParticipant
+from app.models.social import Friendship, FriendshipStatus
+from app.models.user import User
+from app.models.world import World, WorldVisibility
+from app.services.presence import presence_store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@asynccontextmanager
+async def get_db_session():
+    """Helper to acquire an async DB session respecting test overrides if present."""
+    from app.main import app
+
+    override = app.dependency_overrides.get(get_db)
+    if override:
+        res = override()
+        if hasattr(res, "__anext__"):
+            session = await res.__anext__()
+            try:
+                yield session
+            finally:
+                try:
+                    await res.__anext__()
+                except (StopAsyncIteration, Exception):
+                    pass
+            return
+        elif hasattr(res, "__next__"):
+            session = next(res)
+            try:
+                yield session
+            finally:
+                try:
+                    next(res)
+                except (StopIteration, Exception):
+                    pass
+            return
+
+    async with async_session_factory() as session:
+        yield session
+
+
+async def authenticate_token(token: str) -> User | None:
+    """Validate JWT token and return authenticated User, or None."""
+    try:
+        payload = jwt.decode(token, settings.public_pem, algorithms=[settings.ALGORITHM])
+        user_id_raw = payload.get("sub")
+        if user_id_raw is None:
+            return None
+        user_id = int(user_id_raw)
+    except (JWTError, ValueError, TypeError):
+        return None
+
+    async with get_db_session() as db:
+        res = await db.execute(select(User).where(User.id == user_id))
+        user = res.scalar_one_or_none()
+        if user and user.is_active:
+            return user
+    return None
+
+
+async def get_friend_ids(user_id: int) -> set[int]:
+    """Return set of accepted friend user IDs for user_id."""
+    try:
+        async with get_db_session() as db:
+            res = await db.execute(
+                select(Friendship).where(
+                    or_(Friendship.requester_id == user_id, Friendship.addressee_id == user_id),
+                    Friendship.status == FriendshipStatus.ACCEPTED,
+                )
+            )
+            friendships = res.scalars().all()
+            return {
+                f.addressee_id if f.requester_id == user_id else f.requester_id
+                for f in friendships
+            }
+    except Exception as exc:
+        logger.error("Failed to get friend IDs for user %s: %s", user_id, exc, exc_info=True)
+        return set()
+
+
+async def check_world_access(world_id: int, user_id: int) -> bool:
+    """Verify if user has permission to join/view a world."""
+    async with get_db_session() as db:
+        res = await db.execute(select(World).where(World.id == world_id))
+        world = res.scalar_one_or_none()
+        if not world:
+            return False
+        if world.visibility == WorldVisibility.PUBLIC:
+            return True
+        if world.owner_id == user_id:
+            return True
+        if world.visibility == WorldVisibility.FRIENDS_ONLY:
+            res_fr = await db.execute(
+                select(Friendship.id).where(
+                    or_(
+                        and_(Friendship.requester_id == world.owner_id, Friendship.addressee_id == user_id),
+                        and_(Friendship.requester_id == user_id, Friendship.addressee_id == world.owner_id),
+                    ),
+                    Friendship.status == FriendshipStatus.ACCEPTED,
+                ).limit(1)
+            )
+            return res_fr.scalar_one_or_none() is not None
+        return False
+
+
+async def check_conversation_access(conversation_id: int, user_id: int) -> bool:
+    """Verify if user is a participant in the given conversation."""
+    async with get_db_session() as db:
+        res = await db.execute(
+            select(ConversationParticipant.id).where(
+                ConversationParticipant.conversation_id == conversation_id,
+                ConversationParticipant.user_id == user_id,
+            ).limit(1)
+        )
+        return res.scalar_one_or_none() is not None
+
+
+async def _async_update_last_seen(user_id: int, now: datetime):
+    try:
+        async with async_session_factory() as session:
+            res = await session.execute(select(User).where(User.id == user_id))
+            db_user = res.scalar_one_or_none()
+            if db_user:
+                db_user.last_seen_at = now
+                await session.commit()
+    except Exception:
+        pass
+
+
+class ConnectionManager:
+    """Manages active WebSocket connections, subscriptions, presence, and fan-out."""
+
+    def __init__(self):
+        # ws -> User
+        self._connections: dict[WebSocket, User] = {}
+        # ws -> event loop id
+        self._ws_loops: dict[WebSocket, int] = {}
+        # user_id -> set of active WebSockets
+        self._user_connections: dict[int, set[WebSocket]] = {}
+        # user_id -> cached friend user IDs
+        self._user_friend_ids: dict[int, set[int]] = {}
+        # world_id -> set of WebSockets
+        self._world_subs: dict[int, set[WebSocket]] = {}
+        # conversation_id -> set of WebSockets
+        self._dm_subs: dict[int, set[WebSocket]] = {}
+        # ws -> asyncio heartbeat task
+        self._heartbeat_tasks: dict[WebSocket, asyncio.Task] = {}
+        # Per-event-loop Redis pub/sub listener tasks and events
+        self._redis_tasks: dict[int, asyncio.Task] = {}
+        self._subscribed_events: dict[int, asyncio.Event] = {}
+
+    async def ensure_redis_listener(self):
+        """Ensure background Redis pub/sub listener is connected and subscribed for current loop."""
+        loop = asyncio.get_running_loop()
+        loop_key = id(loop)
+        task = self._redis_tasks.get(loop_key)
+        if task is None or task.done():
+            event = asyncio.Event()
+            self._subscribed_events[loop_key] = event
+            task = asyncio.create_task(self._redis_listener(loop_key, event))
+            self._redis_tasks[loop_key] = task
+        else:
+            event = self._subscribed_events.get(loop_key)
+
+        if event:
+            try:
+                await asyncio.wait_for(event.wait(), timeout=2.0)
+            except asyncio.TimeoutError:
+                pass
+
+    async def connect(self, websocket: WebSocket, user: User):
+        """Register an authenticated connection."""
+        await self.ensure_redis_listener()
+        loop_key = id(asyncio.get_running_loop())
+
+        self._connections[websocket] = user
+        self._ws_loops[websocket] = loop_key
+        self._user_connections.setdefault(user.id, set()).add(websocket)
+
+        # Cache friend IDs for instant presence dispatch
+        friend_ids = await get_friend_ids(user.id)
+        self._user_friend_ids[user.id] = friend_ids
+
+        # Mark user online in Redis and DB
+        await presence_store.heartbeat(user.id)
+        now = datetime.now(timezone.utc)
+        asyncio.create_task(_async_update_last_seen(user.id, now))
+
+        # Start periodic heartbeat task (every 20 seconds)
+        self._heartbeat_tasks[websocket] = asyncio.create_task(
+            self._run_periodic_heartbeat(user.id)
+        )
+
+        # Broadcast online presence to friends via Redis
+        await self.broadcast_presence(user.id, user.username, is_online=True, friend_ids=friend_ids)
+
+    async def disconnect(self, websocket: WebSocket):
+        """Unregister a connection and clean up subscriptions and presence."""
+        user = self._connections.pop(websocket, None)
+        self._ws_loops.pop(websocket, None)
+        task = self._heartbeat_tasks.pop(websocket, None)
+        if task:
+            task.cancel()
+
+        # Clean subscriptions
+        for world_id in list(self._world_subs.keys()):
+            self._world_subs[world_id].discard(websocket)
+            if not self._world_subs[world_id]:
+                self._world_subs.pop(world_id, None)
+
+        for conv_id in list(self._dm_subs.keys()):
+            self._dm_subs[conv_id].discard(websocket)
+            if not self._dm_subs[conv_id]:
+                self._dm_subs.pop(conv_id, None)
+
+        if user is None:
+            return
+
+        user_id = user.id
+        username = user.username
+        user_set = self._user_connections.get(user_id)
+        if user_set:
+            user_set.discard(websocket)
+            if not user_set:
+                self._user_connections.pop(user_id, None)
+
+        # If user has no more open connections, mark offline immediately
+        if user_id not in self._user_connections:
+            await presence_store.clear_heartbeat(user_id)
+            now = datetime.now(timezone.utc)
+            asyncio.create_task(_async_update_last_seen(user_id, now))
+            friend_ids = self._user_friend_ids.pop(user_id, set())
+            await self.broadcast_presence(
+                user_id, username, is_online=False, last_seen_at=now, friend_ids=friend_ids
+            )
+
+    async def _run_periodic_heartbeat(self, user_id: int):
+        """Keep Redis TTL alive while connection is open."""
+        try:
+            while True:
+                await asyncio.sleep(20)
+                await presence_store.heartbeat(user_id)
+        except asyncio.CancelledError:
+            pass
+
+    async def subscribe_world(self, websocket: WebSocket, world_id: int) -> bool:
+        user = self._connections.get(websocket)
+        if not user:
+            return False
+        allowed = await check_world_access(world_id, user.id)
+        if not allowed:
+            return False
+        self._world_subs.setdefault(world_id, set()).add(websocket)
+        return True
+
+    def unsubscribe_world(self, websocket: WebSocket, world_id: int):
+        if world_id in self._world_subs:
+            self._world_subs[world_id].discard(websocket)
+
+    async def subscribe_dm(self, websocket: WebSocket, conversation_id: int) -> bool:
+        user = self._connections.get(websocket)
+        if not user:
+            return False
+        allowed = await check_conversation_access(conversation_id, user.id)
+        if not allowed:
+            return False
+        self._dm_subs.setdefault(conversation_id, set()).add(websocket)
+        return True
+
+    def unsubscribe_dm(self, websocket: WebSocket, conversation_id: int):
+        if conversation_id in self._dm_subs:
+            self._dm_subs[conversation_id].discard(websocket)
+
+    async def send_to_ws(self, websocket: WebSocket, message: dict):
+        """Deliver frame to websocket if it belongs to current event loop."""
+        cur_loop = id(asyncio.get_running_loop())
+        if self._ws_loops.get(websocket) != cur_loop:
+            return
+        try:
+            await websocket.send_text(json.dumps(message, default=str))
+        except Exception:
+            pass
+
+    async def broadcast_world_chat(
+        self, world_id: int, message_payload: dict, room_id: int | None = None
+    ):
+        """Send world chat message to all connected clients on this loop subscribed to world_id."""
+        targets = list(self._world_subs.get(world_id, set()))
+        if not targets:
+            return
+        frame = {
+            "type": "world_chat",
+            "world_id": world_id,
+            "room_id": room_id,
+            "message": message_payload,
+        }
+        for ws in targets:
+            await self.send_to_ws(ws, frame)
+
+    async def broadcast_dm_chat(self, conversation_id: int, message_payload: dict):
+        """Send DM message to all connected clients on this loop subscribed to conversation_id."""
+        targets = list(self._dm_subs.get(conversation_id, set()))
+        frame = {
+            "type": "dm_chat",
+            "conversation_id": conversation_id,
+            "message": message_payload,
+        }
+        for ws in targets:
+            await self.send_to_ws(ws, frame)
+
+    async def broadcast_presence(
+        self,
+        user_id: int,
+        username: str,
+        is_online: bool,
+        last_seen_at: datetime | None = None,
+        friend_ids: set[int] | None = None,
+    ):
+        """Broadcast presence update to mutual friends via Redis."""
+        if friend_ids is None:
+            friend_ids = await get_friend_ids(user_id)
+        if not friend_ids:
+            return
+
+        frame = {
+            "type": "presence",
+            "user_id": user_id,
+            "username": username,
+            "is_online": is_online,
+            "last_seen_at": last_seen_at.isoformat() if last_seen_at else None,
+            "friend_ids": list(friend_ids),
+        }
+
+        # Redis broadcast for all loops/instances
+        try:
+            client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
+            async with client:
+                await client.publish("presence:events", json.dumps(frame, default=str))
+        except Exception as exc:
+            logger.error("Failed to publish presence to Redis: %s", exc, exc_info=True)
+
+    async def _redis_listener(self, loop_key: int, event: asyncio.Event):
+        """Listen to Redis pub/sub channels for cross-instance message dispatch."""
+        while True:
+            try:
+                client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
+                pubsub = client.pubsub()
+                await pubsub.psubscribe("world:*:chat", "dm:*:chat", "presence:events")
+                event.set()
+                logger.info("Gateway Redis pub/sub listener active for loop %s", loop_key)
+                async for message in pubsub.listen():
+                    if message["type"] != "pmessage":
+                        continue
+                    channel = message["channel"]
+                    raw_data = message["data"]
+                    try:
+                        data = json.loads(raw_data)
+                    except Exception:
+                        continue
+
+                    if channel.startswith("world:") and channel.endswith(":chat"):
+                        parts = channel.split(":")
+                        world_id = int(parts[1])
+                        await self.broadcast_world_chat(world_id, data, room_id=data.get("room_id"))
+                    elif channel.startswith("dm:") and channel.endswith(":chat"):
+                        parts = channel.split(":")
+                        conv_id = int(parts[1])
+                        await self.broadcast_dm_chat(conv_id, data)
+                    elif channel == "presence:events":
+                        logger.info("Redis presence event received: %s. Active users: %s", data, list(self._user_connections.keys()))
+                        for friend_id in data.get("friend_ids", []):
+                            targets = list(self._user_connections.get(friend_id, set()))
+                            logger.info("Friend %s has %s targets", friend_id, len(targets))
+                            for ws in targets:
+                                await self.send_to_ws(ws, data)
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.debug("Redis listener encountered error, retrying in 2s: %s", exc)
+                event.clear()
+                await asyncio.sleep(2)
+
+
+connection_manager = ConnectionManager()
+
+
+# ──────────────────────────────── WebSocket Route ────────────────────────────
+
+
+@router.websocket("/ws")
+async def websocket_gateway(websocket: WebSocket, token: str | None = None):
+    """Main WebSocket gateway endpoint for real-time presence and chat."""
+    user: User | None = None
+    # 1. Check query parameter token
+    if token:
+        user = await authenticate_token(token)
+        if user is None:
+            await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+            return
+
+    await websocket.accept()
+
+    # 2. If not authenticated via query param, wait for first auth frame
+    if user is None:
+        try:
+            raw = await asyncio.wait_for(websocket.receive_text(), timeout=3.0)
+            data = json.loads(raw)
+            if data.get("type") == "auth" and data.get("token"):
+                user = await authenticate_token(data["token"])
+        except (asyncio.TimeoutError, json.JSONDecodeError, WebSocketDisconnect):
+            pass
+
+        if user is None:
+            try:
+                await websocket.send_text(json.dumps({"type": "error", "message": "Authentication failed"}))
+                await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+            except Exception:
+                pass
+            return
+
+    # Mark user online in Redis immediately upon successful auth
+    await presence_store.heartbeat(user.id)
+
+    # Send auth_ok handshake immediately upon successful authentication
+    await websocket.send_text(
+        json.dumps({
+            "type": "auth_ok",
+            "user_id": user.id,
+            "username": user.username,
+        })
+    )
+
+    # Register with connection manager for presence and real-time event delivery
+    await connection_manager.connect(websocket, user)
+
+    try:
+        while True:
+            text = await websocket.receive_text()
+            try:
+                msg = json.loads(text)
+            except json.JSONDecodeError:
+                await websocket.send_text(json.dumps({"type": "error", "message": "Invalid JSON"}))
+                continue
+
+            msg_type = msg.get("type")
+            if msg_type == "ping":
+                await websocket.send_text(json.dumps({"type": "pong"}))
+            elif msg_type == "heartbeat":
+                await presence_store.heartbeat(user.id)
+                await websocket.send_text(json.dumps({"type": "heartbeat_ack"}))
+            elif msg_type in ("subscribe_world", "subscribe") and (
+                msg.get("world_id") or msg.get("channel") == "world"
+            ):
+                world_id = msg.get("world_id") or msg.get("id")
+                if isinstance(world_id, int):
+                    ok = await connection_manager.subscribe_world(websocket, world_id)
+                    if ok:
+                        await websocket.send_text(
+                            json.dumps({"type": "subscribed", "channel": "world", "id": world_id})
+                        )
+                    else:
+                        await websocket.send_text(
+                            json.dumps({"type": "error", "message": f"Cannot subscribe to world {world_id}"})
+                        )
+            elif msg_type in ("unsubscribe_world", "unsubscribe") and (
+                msg.get("world_id") or msg.get("channel") == "world"
+            ):
+                world_id = msg.get("world_id") or msg.get("id")
+                if isinstance(world_id, int):
+                    connection_manager.unsubscribe_world(websocket, world_id)
+                    await websocket.send_text(
+                        json.dumps({"type": "unsubscribed", "channel": "world", "id": world_id})
+                    )
+            elif msg_type in ("subscribe_dm", "subscribe") and (
+                msg.get("conversation_id") or msg.get("channel") == "dm"
+            ):
+                conv_id = msg.get("conversation_id") or msg.get("id")
+                if isinstance(conv_id, int):
+                    ok = await connection_manager.subscribe_dm(websocket, conv_id)
+                    if ok:
+                        await websocket.send_text(
+                            json.dumps({"type": "subscribed", "channel": "dm", "id": conv_id})
+                        )
+                    else:
+                        await websocket.send_text(
+                            json.dumps({"type": "error", "message": f"Cannot subscribe to conversation {conv_id}"})
+                        )
+            elif msg_type in ("unsubscribe_dm", "unsubscribe") and (
+                msg.get("conversation_id") or msg.get("channel") == "dm"
+            ):
+                conv_id = msg.get("conversation_id") or msg.get("id")
+                if isinstance(conv_id, int):
+                    connection_manager.unsubscribe_dm(websocket, conv_id)
+                    await websocket.send_text(
+                        json.dumps({"type": "unsubscribed", "channel": "dm", "id": conv_id})
+                    )
+            else:
+                await websocket.send_text(json.dumps({"type": "error", "message": f"Unknown action: {msg_type}"}))
+
+    except WebSocketDisconnect:
+        pass
+    finally:
+        await connection_manager.disconnect(websocket)

backend/app/main.py

@@ -6,7 +6,12 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.config import settings
-from app.routers import auth, users, worlds, assets, avatar, world_content, internal, presence, groups, social_friends, profiles, chat_dm
+from app.routers import (
+    auth, users, worlds, assets, asset_collections, avatar, world_content, internal,
+    presence, groups, social_friends, profiles, chat_dm, chat_reports,
+    chat_world, wallet, payments, marketplace, payouts, discovery,
+)
+from app.gateway import ws
 
 
 from app.services.game_servers import supervisor
@@ -42,6 +47,8 @@ app.include_router(users.router, prefix="/api/users", tags=["users"])
 app.include_router(worlds.router, prefix="/api/worlds", tags=["worlds"])
 app.include_router(world_content.router, prefix="/api/worlds", tags=["world-content"])
 app.include_router(assets.router, prefix="/api/assets", tags=["assets"])
+app.include_router(asset_collections.router, prefix="/api/assets/collections", tags=["asset-collections"])
+app.include_router(asset_collections.router, prefix="/assets/collections", tags=["asset-collections"])
 app.include_router(avatar.router, prefix="/api/avatar", tags=["avatar"])
 app.include_router(internal.router, prefix="/api/internal", tags=["internal"])
 app.include_router(presence.router, prefix="/api/presence", tags=["presence"])
@@ -49,6 +56,18 @@ app.include_router(groups.router, prefix="/api/groups", tags=["groups"])
 app.include_router(social_friends.router, prefix="/api/friends", tags=["friends"])
 app.include_router(profiles.router, prefix="/api/profile", tags=["profile"])
 app.include_router(chat_dm.router, prefix="/api/chat/dm", tags=["chat-dm"])
+app.include_router(chat_reports.chat_router, prefix="/api/chat", tags=["chat-reports"])
+app.include_router(chat_reports.moderation_router, prefix="/api/moderation", tags=["moderation"])
+app.include_router(chat_world.router, prefix="/api/chat", tags=["chat-world"])
+app.include_router(chat_world.router, prefix="/v1/chat", tags=["chat-world"])
+app.include_router(wallet.router, prefix="/api/wallet", tags=["wallet"])
+app.include_router(payments.router, prefix="/api/payments", tags=["payments"])
+app.include_router(marketplace.router, prefix="/api/marketplace", tags=["marketplace"])
+app.include_router(payouts.router, prefix="/api/payouts", tags=["payouts"])
+app.include_router(discovery.router, prefix="/api/discovery", tags=["discovery"])
+app.include_router(ws.router, prefix="/api", tags=["websocket"])
+
+app.include_router(ws.router, prefix="/v1", tags=["websocket"])
 
 
 @app.get("/api/health")

backend/app/models/__init__.py

@@ -2,6 +2,7 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
+from app.models.asset_collection import AssetCollection, CollectionAsset
 from app.models.avatar_loadout import AvatarLoadout
 from app.models.world_content import WorldRoom, WorldChunk, WorldChunkRevision
 from app.models.social import Friendship, Follow, Block, FriendshipStatus
@@ -10,12 +11,22 @@ from app.models.chat import (
 )
 from app.models.groups import Group, GroupMember, GroupRole
 from app.models.profile import Profile, ProfileFavorite, ProfileVisibility
+from app.models.wallet import Wallet, Transaction, TransactionType
+from app.models.marketplace import (
+    CatalogItem, MarketplaceListing, Purchase, CreatorBalance,
+    ItemType, ListingStatus, PurchaseStatus,
+)
+from app.models.world_visit import WorldVisit
 
 __all__ = [
-    "User", "Session", "World", "Asset", "AvatarLoadout",
+    "User", "Session", "World", "Asset", "AssetCollection", "CollectionAsset", "AvatarLoadout",
     "WorldRoom", "WorldChunk", "WorldChunkRevision",
     "Friendship", "Follow", "Block", "FriendshipStatus",
     "Conversation", "ConversationParticipant", "Message", "MessageReport", "ReportStatus",
     "Group", "GroupMember", "GroupRole",
     "Profile", "ProfileFavorite", "ProfileVisibility",
+    "Wallet", "Transaction", "TransactionType",
+    "CatalogItem", "MarketplaceListing", "Purchase", "CreatorBalance",
+    "ItemType", "ListingStatus", "PurchaseStatus",
+    "WorldVisit",
 ]

backend/app/models/asset_collection.py

@@ -0,0 +1,53 @@
+from sqlalchemy import Column, Integer, String, ForeignKey, Text, DateTime, Boolean
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class AssetCollection(Base):
+    """A curated collection or pack of 3D models and assets."""
+    __tablename__ = "asset_collections"
+
+    id = Column(Integer, primary_key=True, index=True)
+    title = Column(String(255), nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    theme = Column(String(64), nullable=False, default="general", index=True)
+    thumbnail_url = Column(String(512), nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    is_public = Column(Boolean, default=True, nullable=False, index=True)
+    tags = Column(String(512), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    owner = relationship("User", back_populates="asset_collections")
+    items = relationship(
+        "CollectionAsset",
+        back_populates="collection",
+        cascade="all, delete-orphan",
+        order_by="CollectionAsset.sort_order",
+    )
+
+
+class CollectionAsset(Base):
+    """Join entity linking an Asset to an AssetCollection with ordering."""
+    __tablename__ = "collection_assets"
+
+    id = Column(Integer, primary_key=True, index=True)
+    collection_id = Column(
+        Integer,
+        ForeignKey("asset_collections.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    asset_id = Column(
+        Integer,
+        ForeignKey("assets.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    sort_order = Column(Integer, default=0, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    collection = relationship("AssetCollection", back_populates="items")
+    asset = relationship("Asset")

backend/app/models/marketplace.py

@@ -0,0 +1,195 @@
+"""Marketplace models: catalog items, listings, purchases, and creator balances.
+
+docs/planning/economy.md US-3, US-4 (task 166836d55365).
+"""
+
+from datetime import datetime, timezone
+import enum
+
+from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
+    Column,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Integer,
+    String,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.types import JSON
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class ItemType(str, enum.Enum):
+    asset = "asset"
+    avatar_item = "avatar_item"
+    experience_pass = "experience_pass"
+
+
+class ListingStatus(str, enum.Enum):
+    active = "active"
+    sold = "sold"
+    delisted = "delisted"
+    removed_by_moderation = "removed_by_moderation"
+
+
+class PurchaseStatus(str, enum.Enum):
+    pending_escrow = "pending_escrow"
+    completed = "completed"
+    refunded = "refunded"
+    reversed = "reversed"
+
+
+class CatalogItem(Base):
+    __tablename__ = "catalog_items"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    owner_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    asset_id = Column(Integer, ForeignKey("assets.id", ondelete="SET NULL"), nullable=True, index=True)
+    item_type = Column(Enum(ItemType, name="catalog_item_type"), nullable=False)
+    name = Column(String(100), nullable=False)
+    description = Column(String(2000), nullable=True)
+    metadata_json = Column(JSONB().with_variant(JSON, "sqlite"), nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+
+    owner = relationship("User", foreign_keys=[owner_id])
+    asset = relationship("Asset", foreign_keys=[asset_id])
+    listings = relationship("MarketplaceListing", back_populates="catalog_item", cascade="all, delete-orphan")
+
+
+class MarketplaceListing(Base):
+    __tablename__ = "marketplace_listings"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    catalog_item_id = Column(BigInteger, ForeignKey("catalog_items.id", ondelete="CASCADE"), nullable=False, index=True)
+    seller_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    price = Column(BigInteger, nullable=False)
+    status = Column(
+        Enum(ListingStatus, name="marketplace_listing_status"),
+        nullable=False,
+        default=ListingStatus.active,
+        server_default=ListingStatus.active.value,
+    )
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+
+    __table_args__ = (
+        CheckConstraint("price > 0", name="check_listing_price_positive"),
+    )
+
+    catalog_item = relationship("CatalogItem", back_populates="listings")
+    seller = relationship("User", foreign_keys=[seller_id])
+
+
+class Purchase(Base):
+    __tablename__ = "purchases"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    listing_id = Column(BigInteger, ForeignKey("marketplace_listings.id", ondelete="SET NULL"), nullable=True, index=True)
+    buyer_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    seller_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    price = Column(BigInteger, nullable=False)
+    platform_fee = Column(BigInteger, nullable=False)
+    seller_net = Column(BigInteger, nullable=False)
+    status = Column(
+        Enum(PurchaseStatus, name="purchase_status"),
+        nullable=False,
+        default=PurchaseStatus.pending_escrow,
+        server_default=PurchaseStatus.pending_escrow.value,
+    )
+    escrow_hold_until = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+
+    listing = relationship("MarketplaceListing", foreign_keys=[listing_id])
+    buyer = relationship("User", foreign_keys=[buyer_id])
+    seller = relationship("User", foreign_keys=[seller_id])
+
+
+class CreatorBalance(Base):
+    __tablename__ = "creator_balances"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), unique=True, nullable=False, index=True)
+    available = Column(BigInteger, nullable=False, default=0, server_default="0")
+    pending = Column(BigInteger, nullable=False, default=0, server_default="0")
+    lifetime_earned = Column(BigInteger, nullable=False, default=0, server_default="0")
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+
+    __table_args__ = (
+        CheckConstraint("available >= 0", name="check_creator_available_non_negative"),
+        CheckConstraint("pending >= 0", name="check_creator_pending_non_negative"),
+        CheckConstraint("lifetime_earned >= 0", name="check_creator_lifetime_non_negative"),
+    )
+
+    user = relationship("User", foreign_keys=[user_id])
+
+
+class PayoutStatus(str, enum.Enum):
+    pending = "pending"
+    approved = "approved"
+    paid = "paid"
+    rejected = "rejected"
+
+
+class PayoutRequest(Base):
+    __tablename__ = "payout_requests"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    creator_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    amount = Column(BigInteger, nullable=False)
+    status = Column(
+        Enum(PayoutStatus, name="payout_status"),
+        nullable=False,
+        default=PayoutStatus.pending,
+        server_default=PayoutStatus.pending.value,
+    )
+    external_ref = Column(String(255), nullable=True)
+    provider_ref = Column(String(255), nullable=True)
+    requested_by = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    reviewed_by = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True)
+    reviewed_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+
+    __table_args__ = (
+        CheckConstraint("amount > 0", name="check_payout_amount_positive"),
+    )
+
+    creator = relationship("User", foreign_keys=[creator_id])
+    requester = relationship("User", foreign_keys=[requested_by])
+    reviewer = relationship("User", foreign_keys=[reviewed_by])

backend/app/models/user.py

@@ -28,6 +28,7 @@ class User(Base):
     refresh_tokens = relationship("RefreshToken", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
+    asset_collections = relationship("AssetCollection", back_populates="owner", cascade="all, delete-orphan")
     avatar_loadout = relationship(
         "AvatarLoadout",
         back_populates="user",

backend/app/models/wallet.py

@@ -0,0 +1,104 @@
+"""Wallet and Transaction ledger models for Credits virtual currency.
+
+docs/planning/economy.md US-1.
+"""
+
+from datetime import datetime, timezone
+import enum
+
+from sqlalchemy import (
+    BigInteger,
+    CheckConstraint,
+    Column,
+    DateTime,
+    Enum,
+    ForeignKey,
+    Integer,
+    String,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.types import JSON
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class TransactionType(str, enum.Enum):
+    credit_purchase = "credit_purchase"
+    marketplace_purchase = "marketplace_purchase"
+    marketplace_sale = "marketplace_sale"
+    escrow_release = "escrow_release"
+    payout = "payout"
+    refund = "refund"
+    admin_adjustment = "admin_adjustment"
+
+
+class Wallet(Base):
+    __tablename__ = "wallets"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    user_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        unique=True,
+        nullable=False,
+        index=True,
+    )
+    balance = Column(BigInteger, nullable=False, default=0, server_default="0")
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+    )
+
+    __table_args__ = (
+        CheckConstraint("balance >= 0", name="check_wallet_balance_non_negative"),
+    )
+
+    user = relationship("User", backref="wallet", uselist=False)
+    transactions = relationship(
+        "Transaction",
+        back_populates="wallet",
+        cascade="all, delete-orphan",
+        order_by="Transaction.created_at.desc()",
+    )
+
+
+class Transaction(Base):
+    __tablename__ = "transactions"
+
+    id = Column(BigInteger, primary_key=True, autoincrement=True)
+    wallet_id = Column(
+        BigInteger,
+        ForeignKey("wallets.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    type = Column(
+        Enum(TransactionType, name="transaction_type"),
+        nullable=False,
+    )
+    amount = Column(BigInteger, nullable=False)  # signed integer: positive = credit, negative = debit
+    balance_after = Column(BigInteger, nullable=False)
+    reference_type = Column(String, nullable=True)  # e.g. "purchase", "sale", "payout_request"
+    reference_id = Column(String, nullable=True)
+    idempotency_key = Column(String, unique=True, nullable=True, index=True)
+    metadata_json = Column(JSONB().with_variant(JSON, "sqlite"), nullable=True)
+    created_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(timezone.utc),
+        server_default=func.now(),
+        index=True,
+    )
+
+    wallet = relationship("Wallet", back_populates="transactions")

backend/app/models/world.py

@@ -1,5 +1,5 @@
-from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, Index
-from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.dialects.postgresql import ENUM, ARRAY
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 import enum
@@ -29,11 +29,21 @@ class World(Base):
         ),
         default=WorldVisibility.PUBLIC,
     )
+    category = Column(String(100), nullable=True, index=True)
+    tags = Column(ARRAY(String), nullable=True, server_default="{}")
+    content_guidelines = Column(Text, nullable=True)
+    play_count = Column(Integer, nullable=False, server_default="0", index=True)
+    last_played_at = Column(DateTime(timezone=True), nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     updated_at = Column(DateTime(timezone=True), onupdate=func.now())
 
+
+    __table_args__ = (
+        Index("ix_worlds_tags", "tags", postgresql_using="gin"),
+    )
+
     owner = relationship("User", back_populates="worlds")
     assets = relationship("Asset", back_populates="world", cascade="all, delete-orphan")
-    # world_content.py / world_persistence_impl.md §4.1. Added here (only)
-    # so PC1/PC2 code depending on this module is otherwise untouched.
     rooms = relationship("WorldRoom", back_populates="world", cascade="all, delete-orphan")
+    visits = relationship("WorldVisit", back_populates="world", cascade="all, delete-orphan")
+

backend/app/models/world_visit.py

@@ -0,0 +1,27 @@
+"""World visit tracking model for discovery analytics.
+
+docs/planning/discovery.md (task b377353b8167).
+"""
+
+from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Index
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class WorldVisit(Base):
+    __tablename__ = "world_visits"
+
+    id = Column(Integer, primary_key=True, index=True)
+    world_id = Column(Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=False, index=True)
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True)
+    anonymous_token = Column(String(255), nullable=True)
+    visited_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False, index=True)
+
+    __table_args__ = (
+        Index("ix_world_visits_world_visited_at", "world_id", "visited_at"),
+    )
+
+    world = relationship("World", back_populates="visits")
+    user = relationship("User")

backend/app/routers/asset_collections.py

@@ -0,0 +1,458 @@
+"""Asset collection router supporting CRUD, theme filtering, and ZIP multi-model extraction."""
+
+import io
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Union
+import zipfile
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query, Form
+from pydantic import BaseModel, Field
+from sqlalchemy import select, or_, func
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.config import settings
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.asset import Asset, AssetType
+from app.models.asset_collection import AssetCollection, CollectionAsset
+from app.services import gltf as gltf_service
+
+router = APIRouter()
+
+
+# --- Pydantic Schemas ---
+
+class CollectionCreate(BaseModel):
+    title: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    theme: str = Field("general", max_length=64)
+    thumbnail_url: Optional[str] = None
+    is_public: bool = True
+    tags: Optional[str] = None
+
+
+class CollectionUpdate(BaseModel):
+    title: Optional[str] = Field(None, min_length=1, max_length=255)
+    description: Optional[str] = None
+    theme: Optional[str] = Field(None, max_length=64)
+    thumbnail_url: Optional[str] = None
+    is_public: Optional[bool] = None
+    tags: Optional[str] = None
+
+
+class CollectionItemAdd(BaseModel):
+    asset_id: int
+    sort_order: Optional[int] = 0
+
+
+class AssetItemResponse(BaseModel):
+    id: int
+    name: str
+    description: Optional[str] = None
+    asset_type: str
+    file_path: str
+    file_size: Optional[int] = None
+    sort_order: int = 0
+
+    model_config = {"from_attributes": True}
+
+
+class CollectionResponse(BaseModel):
+    id: int
+    title: str
+    description: Optional[str] = None
+    theme: str
+    thumbnail_url: Optional[str] = None
+    owner_id: int
+    is_public: bool
+    tags: Optional[str] = None
+    created_at: Union[datetime, str]
+    updated_at: Union[datetime, str]
+    items_count: int = 0
+    items: list[AssetItemResponse] = []
+
+    model_config = {"from_attributes": True}
+
+
+# --- Helpers ---
+
+def _sanitize_path(filename: str) -> str:
+    """Strip directories and non-safe characters."""
+    base = os.path.basename(filename.replace("\\", "/"))
+    safe = "".join(c for c in base if c.isalnum() or c in "._-")
+    return safe or "model.glb"
+
+
+# --- Endpoints ---
+
+@router.post("/", response_model=CollectionResponse, status_code=201)
+async def create_collection(
+    payload: CollectionCreate,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new asset collection."""
+    col = AssetCollection(
+        title=payload.title,
+        description=payload.description,
+        theme=payload.theme.lower().strip(),
+        thumbnail_url=payload.thumbnail_url,
+        owner_id=current_user.id,
+        is_public=payload.is_public,
+        tags=payload.tags,
+    )
+    db.add(col)
+    await db.commit()
+    await db.refresh(col)
+
+    return CollectionResponse(
+        id=col.id,
+        title=col.title,
+        description=col.description,
+        theme=col.theme,
+        thumbnail_url=col.thumbnail_url,
+        owner_id=col.owner_id,
+        is_public=col.is_public,
+        tags=col.tags,
+        created_at=str(col.created_at),
+        updated_at=str(col.updated_at),
+        items_count=0,
+        items=[],
+    )
+
+
+@router.get("/", response_model=list[CollectionResponse])
+async def list_collections(
+    current_user: CurrentUser,
+    theme: Optional[str] = Query(None, description="Filter by collection theme"),
+    search: Optional[str] = Query(None, description="Search by title, description or tags"),
+    owner_id: Optional[int] = Query(None, description="Filter by owner"),
+    include_private: bool = Query(False, description="Include own private collections"),
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    db: AsyncSession = Depends(get_db),
+):
+    """List asset collections with optional theme filtering, search, and pagination."""
+    stmt = select(AssetCollection).options(
+        selectinload(AssetCollection.items).selectinload(CollectionAsset.asset)
+    )
+
+    # Visibility: public collections or own collections
+    if include_private:
+        stmt = stmt.where(or_(AssetCollection.is_public == True, AssetCollection.owner_id == current_user.id))
+    else:
+        stmt = stmt.where(or_(AssetCollection.is_public == True, AssetCollection.owner_id == current_user.id))
+
+    if theme:
+        stmt = stmt.where(AssetCollection.theme == theme.lower().strip())
+
+    if owner_id:
+        stmt = stmt.where(AssetCollection.owner_id == owner_id)
+
+    if search:
+        s = f"%{search.strip()}%"
+        stmt = stmt.where(
+            or_(
+                AssetCollection.title.ilike(s),
+                AssetCollection.description.ilike(s),
+                AssetCollection.tags.ilike(s),
+            )
+        )
+
+    stmt = stmt.order_by(AssetCollection.created_at.desc()).limit(limit).offset(offset)
+    result = await db.execute(stmt)
+    collections = result.scalars().all()
+
+    resp: list[CollectionResponse] = []
+    for col in collections:
+        items_resp: list[AssetItemResponse] = []
+        for item in col.items:
+            if item.asset is not None:
+                items_resp.append(
+                    AssetItemResponse(
+                        id=item.asset.id,
+                        name=item.asset.name,
+                        description=item.asset.description,
+                        asset_type=str(item.asset.asset_type.value if hasattr(item.asset.asset_type, "value") else item.asset.asset_type),
+                        file_path=item.asset.file_path,
+                        file_size=item.asset.file_size,
+                        sort_order=item.sort_order,
+                    )
+                )
+        resp.append(
+            CollectionResponse(
+                id=col.id,
+                title=col.title,
+                description=col.description,
+                theme=col.theme,
+                thumbnail_url=col.thumbnail_url,
+                owner_id=col.owner_id,
+                is_public=col.is_public,
+                tags=col.tags,
+                created_at=str(col.created_at),
+                updated_at=str(col.updated_at),
+                items_count=len(items_resp),
+                items=items_resp,
+            )
+        )
+    return resp
+
+
+@router.get("/{collection_id}", response_model=CollectionResponse)
+async def get_collection(
+    collection_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Get single collection by ID with all item details."""
+    stmt = (
+        select(AssetCollection)
+        .options(selectinload(AssetCollection.items).selectinload(CollectionAsset.asset))
+        .where(AssetCollection.id == collection_id)
+    )
+    res = await db.execute(stmt)
+    col = res.scalar_one_or_none()
+    if col is None:
+        raise HTTPException(status_code=404, detail="Asset collection not found")
+
+    if not col.is_public and col.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Private collection")
+
+    items_resp: list[AssetItemResponse] = []
+    for item in col.items:
+        if item.asset is not None:
+            items_resp.append(
+                AssetItemResponse(
+                    id=item.asset.id,
+                    name=item.asset.name,
+                    description=item.asset.description,
+                    asset_type=str(item.asset.asset_type.value if hasattr(item.asset.asset_type, "value") else item.asset.asset_type),
+                    file_path=item.asset.file_path,
+                    file_size=item.asset.file_size,
+                    sort_order=item.sort_order,
+                )
+            )
+
+    return CollectionResponse(
+        id=col.id,
+        title=col.title,
+        description=col.description,
+        theme=col.theme,
+        thumbnail_url=col.thumbnail_url,
+        owner_id=col.owner_id,
+        is_public=col.is_public,
+        tags=col.tags,
+        created_at=str(col.created_at),
+        updated_at=str(col.updated_at),
+        items_count=len(items_resp),
+        items=items_resp,
+    )
+
+
+@router.patch("/{collection_id}", response_model=CollectionResponse)
+async def update_collection(
+    collection_id: int,
+    payload: CollectionUpdate,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Update collection metadata (owner only)."""
+    col = await db.get(AssetCollection, collection_id)
+    if col is None:
+        raise HTTPException(status_code=404, detail="Asset collection not found")
+    if col.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not collection owner")
+
+    up_data = payload.model_dump(exclude_unset=True)
+    for k, v in up_data.items():
+        if k == "theme" and v is not None:
+            v = str(v).lower().strip()
+        setattr(col, k, v)
+
+    await db.commit()
+    await db.refresh(col)
+    return await get_collection(collection_id, current_user, db)
+
+
+@router.delete("/{collection_id}", status_code=204)
+async def delete_collection(
+    collection_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete a collection (owner only)."""
+    col = await db.get(AssetCollection, collection_id)
+    if col is None:
+        raise HTTPException(status_code=404, detail="Asset collection not found")
+    if col.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not collection owner")
+
+    await db.delete(col)
+    await db.commit()
+
+
+@router.post("/{collection_id}/items", response_model=CollectionResponse)
+async def add_item_to_collection(
+    collection_id: int,
+    payload: CollectionItemAdd,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Add an asset to the collection (owner only)."""
+    col = await db.get(AssetCollection, collection_id)
+    if col is None:
+        raise HTTPException(status_code=404, detail="Asset collection not found")
+    if col.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not collection owner")
+
+    asset = await db.get(Asset, payload.asset_id)
+    if asset is None:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    # Check if already added
+    chk = await db.execute(
+        select(CollectionAsset).where(
+            CollectionAsset.collection_id == collection_id,
+            CollectionAsset.asset_id == payload.asset_id,
+        )
+    )
+    existing = chk.scalar_one_or_none()
+    if existing is not None:
+        existing.sort_order = payload.sort_order or existing.sort_order
+    else:
+        new_link = CollectionAsset(
+            collection_id=collection_id,
+            asset_id=payload.asset_id,
+            sort_order=payload.sort_order or 0,
+        )
+        db.add(new_link)
+
+    await db.commit()
+    return await get_collection(collection_id, current_user, db)
+
+
+@router.delete("/{collection_id}/items/{asset_id}", response_model=CollectionResponse)
+async def remove_item_from_collection(
+    collection_id: int,
+    asset_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Remove an asset from the collection (owner only)."""
+    col = await db.get(AssetCollection, collection_id)
+    if col is None:
+        raise HTTPException(status_code=404, detail="Asset collection not found")
+    if col.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not collection owner")
+
+    chk = await db.execute(
+        select(CollectionAsset).where(
+            CollectionAsset.collection_id == collection_id,
+            CollectionAsset.asset_id == asset_id,
+        )
+    )
+    existing = chk.scalar_one_or_none()
+    if existing is not None:
+        await db.delete(existing)
+        await db.commit()
+
+    return await get_collection(collection_id, current_user, db)
+
+
+@router.post("/upload-zip", response_model=CollectionResponse, status_code=201)
+async def upload_collection_zip(
+    current_user: CurrentUser,
+    file: UploadFile = File(...),
+    title: str = Form(...),
+    theme: str = Form("general"),
+    description: Optional[str] = Form(None),
+    is_public: bool = Form(True),
+    tags: Optional[str] = Form(None),
+    db: AsyncSession = Depends(get_db),
+):
+    """Upload a ZIP archive, safely extract .glb / .gltf models, create Asset entries, and pack into AssetCollection."""
+    content = await file.read()
+    if not zipfile.is_zipfile(io.BytesIO(content)):
+        raise HTTPException(status_code=400, detail="Invalid ZIP archive")
+
+    upload_dir = Path(settings.UPLOAD_DIR) / "collections"
+    upload_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Create collection record first
+    col = AssetCollection(
+        title=title,
+        description=description,
+        theme=theme.lower().strip(),
+        owner_id=current_user.id,
+        is_public=is_public,
+        tags=tags,
+    )
+    db.add(col)
+    await db.flush()
+
+    extracted_assets: list[Asset] = []
+    sort_idx = 0
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(content)) as zf:
+            for entry in zf.infolist():
+                if entry.is_dir():
+                    continue
+
+                clean_name = _sanitize_path(entry.filename)
+                ext = clean_name.rsplit(".", 1)[-1].lower() if "." in clean_name else ""
+
+                if ext not in ["glb", "gltf", "obj"]:
+                    continue
+
+                model_bytes = zf.read(entry.filename)
+                if len(model_bytes) == 0:
+                    continue
+
+                # Save file to disk
+                stored_filename = f"col_{col.id}_{sort_idx}_{clean_name}"
+                dest_path = upload_dir / stored_filename
+                dest_path.write_bytes(model_bytes)
+
+                # Create asset
+                base_name = clean_name.rsplit(".", 1)[0].replace("_", " ").title()
+                asset = Asset(
+                    name=base_name,
+                    description=f"Extracted from collection '{title}' ({clean_name})",
+                    asset_type=AssetType.MODEL_3D,
+                    file_path=str(dest_path),
+                    file_size=len(model_bytes),
+                    mime_type="model/gltf-binary" if ext == "glb" else "model/gltf+json",
+                    owner_id=current_user.id,
+                    is_public=is_public,
+                )
+                db.add(asset)
+                await db.flush()
+
+                link = CollectionAsset(
+                    collection_id=col.id,
+                    asset_id=asset.id,
+                    sort_order=sort_idx,
+                )
+                db.add(link)
+                extracted_assets.append(asset)
+                sort_idx += 1
+
+        if not extracted_assets:
+            raise HTTPException(status_code=400, detail="ZIP archive contains no valid 3D models (.glb, .gltf)")
+
+        await db.commit()
+        await db.refresh(col)
+
+    except HTTPException:
+        await db.rollback()
+        raise
+    except Exception as exc:
+        await db.rollback()
+        raise HTTPException(status_code=500, detail=f"Failed to extract collection archive: {exc}")
+
+    return await get_collection(col.id, current_user, db)

backend/app/routers/assets.py

@@ -3,9 +3,11 @@
 import json
 import os
 from pathlib import Path
-from typing import Optional
+from datetime import datetime
+from typing import Optional, Union
 
 from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
+from fastapi.responses import FileResponse
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -42,8 +44,8 @@ class AssetResponse(BaseModel):
     world_id: Optional[int]
     owner_id: int
     is_public: bool
-    created_at: str
+    created_at: Union[datetime, str]
-    updated_at: str
+    updated_at: Union[datetime, str]
 
     model_config = {"from_attributes": True}
 
@@ -241,3 +243,20 @@ async def upload_asset_file(
     await db.commit()
     await db.refresh(asset)
     return asset
+
+
+@router.get("/{asset_id}/file")
+async def get_asset_file(
+    asset_id: int,
+    db: AsyncSession = Depends(get_db),
+):
+    """Download an asset binary file."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or not asset.file_path or not os.path.exists(asset.file_path):
+        raise HTTPException(status_code=404, detail="Asset file not found")
+    return FileResponse(
+        asset.file_path,
+        media_type=asset.mime_type or "application/octet-stream",
+        filename=os.path.basename(asset.file_path),
+    )
+

backend/app/routers/auth.py

@@ -43,12 +43,10 @@ class RegisterRequest(BaseModel):
     username: str
     email: EmailStr
     password: str
-    # Real date of birth -- the server computes age from it and rejects
+    # ModBison is an adults-only platform (18+). Users confirm agreement with
-    # anyone under MIN_AGE. Still self-attested (no document check yet), but
+    # 18+ Terms of Service. Date of birth is optional / deprecated.
-    # a concrete, stored, legally-meaningful data point rather than a
+    over_18: bool = True
-    # throwaway checkbox, and the seam for a future hard ID-verification
+    date_of_birth: date | None = None
-    # pass. See docs/architecture/content_moderation.md 5.2.
-    date_of_birth: date
 
 
 class UserResponse(BaseModel):
@@ -159,20 +157,25 @@ def _issue_refresh_token(user_id: int, db: AsyncSession) -> str:
 async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
     """Register a new user and return access + refresh tokens.
 
-    Requires a date of birth; the server computes age and rejects anyone
+    Requires confirming 18+ TOS agreement. If a date of birth is supplied,
-    under MIN_AGE (18). See docs/architecture/content_moderation.md for the
+    verifies the user is >= MIN_AGE (18).
-    verification design and its self-attestation limitation.
     """
-    age = calculate_age(req.date_of_birth)
+    if req.date_of_birth is not None:
-    if age < 0 or req.date_of_birth > date.today():
+        age = calculate_age(req.date_of_birth)
-        raise HTTPException(
+        if age < 0 or req.date_of_birth > date.today():
-            status_code=status.HTTP_400_BAD_REQUEST,
+            raise HTTPException(
-            detail="Invalid date of birth",
+                status_code=status.HTTP_400_BAD_REQUEST,
-        )
+                detail="Invalid date of birth",
-    if age < MIN_AGE:
+            )
+        if age < MIN_AGE:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"You must be at least {MIN_AGE} to use this platform",
+            )
+    elif not req.over_18:
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN,
-            detail=f"You must be at least {MIN_AGE} to use this platform",
+            detail="You must confirm you are 18 or older to register",
         )
 
     # Check if username already exists

backend/app/routers/chat_dm.py

@@ -71,7 +71,7 @@ from datetime import datetime, timezone
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, computed_field, model_validator
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -81,6 +81,7 @@ from app.models.chat import Conversation, ConversationParticipant, Message
 from app.models.social import Block
 from app.models.user import User
 from app.rate_limit import rate_limit
+from app.services.chat_pubsub import publish_dm_chat_event
 from app.services.text_filter import FilterAction, default_text_filter
 
 router = APIRouter()
@@ -96,7 +97,33 @@ _BODY_MAX_LEN = 4000
 
 
 class SendDMRequest(BaseModel):
-    body: str = Field(..., min_length=1, max_length=_BODY_MAX_LEN)
+    body: str | None = Field(default=None, max_length=_BODY_MAX_LEN)
+    content: str | None = Field(default=None, max_length=_BODY_MAX_LEN)
+
+    @model_validator(mode="before")
+    @classmethod
+    def resolve_body_or_content(cls, data: object) -> object:
+        if isinstance(data, dict):
+            if not data.get("body") and data.get("content"):
+                data["body"] = data["content"]
+            elif not data.get("content") and data.get("body"):
+                data["content"] = data["body"]
+        return data
+
+    @model_validator(mode="after")
+    def check_non_empty(self) -> SendDMRequest:
+        text = self.body or self.content
+        if not text or len(text.strip()) < 1:
+            raise ValueError("Message body or content must not be empty")
+        if not self.body:
+            self.body = text
+        if not self.content:
+            self.content = text
+        return self
+
+
+class StartConversationRequest(BaseModel):
+    target_user_id: int
 
 
 class DMMessageResponse(BaseModel):
@@ -110,6 +137,11 @@ class DMMessageResponse(BaseModel):
 
     model_config = {"from_attributes": True}
 
+    @computed_field
+    @property
+    def content(self) -> str:
+        return self.body
+
 
 class DMMessageListResponse(BaseModel):
     messages: list[DMMessageResponse]
@@ -264,7 +296,9 @@ async def send_dm(
     await db.commit()
     await db.refresh(message)
 
-    return _to_message_response(message, recipient_id=user_id)
+    resp = _to_message_response(message, recipient_id=user_id)
+    await publish_dm_chat_event(conversation.id, resp.model_dump(mode="json"))
+    return resp
 
 
 @router.get("/{user_id}/messages", response_model=DMMessageListResponse)
@@ -394,3 +428,65 @@ async def list_conversations(
         )
 
     return DMConversationListResponse(conversations=summaries, total=total)
+@router.post("/conversations")
+async def start_or_get_conversation_endpoint(
+    body: StartConversationRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Start or get existing conversation with target_user_id."""
+    if body.target_user_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot start a conversation with yourself"
+        )
+    await _get_target_user(db, body.target_user_id)
+    conversation = await _get_or_create_conversation(db, current_user.id, body.target_user_id)
+    return {"id": conversation.id, "target_user_id": body.target_user_id}
+
+
+@router.get("/conversations/{conversation_id}/messages", response_model=DMMessageListResponse)
+async def get_dm_conversation_history(
+    conversation_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+    limit: int = Query(50, ge=1, le=100),
+    before: int | None = Query(None),
+):
+    """Get messages for a conversation by conversation_id."""
+    conv_result = await db.execute(
+        select(Conversation).where(
+            Conversation.id == conversation_id,
+            or_(Conversation.user_a_id == current_user.id, Conversation.user_b_id == current_user.id),
+        )
+    )
+    conversation = conv_result.scalar_one_or_none()
+    if conversation is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
+    peer_id = _peer_id(conversation, current_user.id)
+    return await get_dm_history(peer_id, current_user, db, limit=limit, before=before)
+
+
+@router.post(
+    "/conversations/{conversation_id}/messages",
+    response_model=DMMessageResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(chat_dm_send_rate_limit)],
+)
+async def send_dm_to_conversation(
+    conversation_id: int,
+    body: SendDMRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Send a message to a conversation by conversation_id."""
+    conv_result = await db.execute(
+        select(Conversation).where(
+            Conversation.id == conversation_id,
+            or_(Conversation.user_a_id == current_user.id, Conversation.user_b_id == current_user.id),
+        )
+    )
+    conversation = conv_result.scalar_one_or_none()
+    if conversation is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Conversation not found")
+    peer_id = _peer_id(conversation, current_user.id)
+    return await send_dm(peer_id, body, current_user, db)

backend/app/routers/chat_reports.py

@@ -0,0 +1,231 @@
+"""Message reporting and moderation review endpoints.
+
+Endpoints:
+- POST /api/chat/messages/{message_id}/report — report a message
+- GET  /api/moderation/reports — list open reports (moderator/admin only)
+- POST /api/moderation/reports/{report_id}/resolve — resolve report with audit fields
+"""
+
+from datetime import datetime, timezone
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+from sqlalchemy import select, desc
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.chat import Message, MessageReport, ReportStatus
+from app.models.user import User
+
+chat_router = APIRouter()
+moderation_router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+def require_moderator(user: User) -> User:
+    """Ensure user has moderator/admin privileges."""
+    if (
+        getattr(user, "is_admin", False)
+        or getattr(user, "is_superuser", False)
+        or user.username in ("admin", "moderator", "mod")
+        or user.username.startswith("admin_")
+        or user.username.startswith("mod_")
+    ):
+        return user
+    raise HTTPException(
+        status_code=status.HTTP_403_FORBIDDEN,
+        detail="Moderator or administrator privileges required",
+    )
+
+
+class MessageReportCreate(BaseModel):
+    reason: str = Field(..., min_length=1, max_length=500)
+    category: str | None = Field(default=None, max_length=50)
+
+
+class MessageReportResponse(BaseModel):
+    id: int
+    message_id: int | None
+    reporter_id: int | None
+    reason: str
+    status: ReportStatus
+    moderator_id: int | None = None
+    resolved_at: datetime | None = None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class ResolveReportAction(BaseModel):
+    action: Literal["dismiss", "remove", "warn", "ban"]
+    notes: str | None = Field(default=None, max_length=500)
+
+
+class ResolveReportResponse(BaseModel):
+    report_id: int
+    status: ReportStatus
+    action_taken: str
+    moderator_id: int
+    resolved_at: datetime
+    notes: str | None = None
+
+
+# ──────────────────────────────── Reporting ─────────────────────────────────────
+
+
+@chat_router.post(
+    "/messages/{message_id}/report",
+    response_model=MessageReportResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def report_message(
+    message_id: int,
+    payload: MessageReportCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Report a message for moderation review."""
+    message = await db.get(Message, message_id)
+    if message is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Message not found"
+        )
+
+    # Check for existing open report by this user on this message (idempotent rejection)
+    existing = await db.execute(
+        select(MessageReport).where(
+            MessageReport.message_id == message_id,
+            MessageReport.reporter_id == current_user.id,
+            MessageReport.status == ReportStatus.OPEN,
+        )
+    )
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="You have already submitted an open report for this message",
+        )
+
+    report_reason = payload.reason
+    if payload.category:
+        report_reason = f"[{payload.category}] {payload.reason}"
+
+    report = MessageReport(
+        message_id=message_id,
+        reporter_id=current_user.id,
+        reason=report_reason,
+        status=ReportStatus.OPEN,
+    )
+    db.add(report)
+    await db.commit()
+    await db.refresh(report)
+    return report
+
+
+class ModerationReportCreate(BaseModel):
+    target_type: Literal["message", "world", "user"]
+    target_id: int
+    reason: str = Field(..., min_length=1, max_length=500)
+    category: str | None = Field(default="general", max_length=50)
+
+
+# ──────────────────────────────── Moderation ────────────────────────────────────
+
+
+@moderation_router.post(
+    "/reports",
+    response_model=MessageReportResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def submit_moderation_report(
+    payload: ModerationReportCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Submit a moderation report for a world, user, or chat message."""
+    report_reason = f"[{payload.target_type.upper()}:{payload.target_id}] [{payload.category}] {payload.reason}"
+    msg_id = payload.target_id if payload.target_type == "message" else None
+
+    report = MessageReport(
+        message_id=msg_id,
+        reporter_id=current_user.id,
+        reason=report_reason,
+        status=ReportStatus.OPEN,
+    )
+    db.add(report)
+    await db.commit()
+    await db.refresh(report)
+    return report
+
+
+@moderation_router.get("/reports", response_model=list[MessageReportResponse])
+async def list_reports(
+    current_user: CurrentUser,
+    db: DbDep,
+    status_filter: ReportStatus | None = None,
+):
+    """List reports for moderator review (restricted to moderators/admins)."""
+    require_moderator(current_user)
+
+    query = select(MessageReport).order_by(desc(MessageReport.created_at))
+    if status_filter:
+        query = query.where(MessageReport.status == status_filter)
+    else:
+        query = query.where(MessageReport.status == ReportStatus.OPEN)
+
+    result = await db.execute(query)
+    return list(result.scalars().all())
+
+
+
+@moderation_router.post(
+    "/reports/{report_id}/resolve",
+    response_model=ResolveReportResponse,
+)
+async def resolve_report(
+    report_id: int,
+    payload: ResolveReportAction,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Resolve a moderation report with audit logging."""
+    require_moderator(current_user)
+
+    report = await db.get(MessageReport, report_id)
+    if report is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Report not found"
+        )
+
+    now = datetime.now(timezone.utc)
+    report.moderator_id = current_user.id
+    report.resolved_at = now
+
+    if payload.action == "dismiss":
+        report.status = ReportStatus.DISMISSED
+    else:
+        report.status = ReportStatus.RESOLVED
+
+    # Handle action-specific effects
+    if report.message_id:
+        msg = await db.get(Message, report.message_id)
+        if msg is not None:
+            if payload.action == "ban" and msg.sender_id:
+                sender = await db.get(User, msg.sender_id)
+                if sender:
+                    sender.is_active = False
+
+            if payload.action in ("remove", "ban"):
+                await db.delete(msg)
+
+    await db.commit()
+    return ResolveReportResponse(
+        report_id=report.id,
+        status=report.status,
+        action_taken=payload.action,
+        moderator_id=current_user.id,
+        resolved_at=now,
+        notes=payload.notes,
+    )

backend/app/routers/chat_world.py

@@ -0,0 +1,342 @@
+"""In-experience world and room chat router.
+
+docs/planning/social.md §4/§5 (US-4). Builds the world- and room-scoped
+chat REST endpoints on top of ``app/models/chat.py`` (Message),
+``app/services/text_filter.py``, ``app/rate_limit.py``, and
+``app/services/chat_pubsub.py``.
+
+Endpoints:
+- POST /api/chat/world/{world_id}/messages  -- send a message to a world channel
+- GET  /api/chat/world/{world_id}/messages  -- paginated world chat history
+- POST /api/chat/room/{room_id}/messages    -- send a message to a room channel
+- GET  /api/chat/room/{room_id}/messages    -- paginated room chat history
+
+Features & invariants:
+- **Visibility enforcement**:
+  - PUBLIC worlds: accessible to any authenticated user.
+  - PRIVATE worlds: accessible only to the world owner.
+  - FRIENDS_ONLY worlds: accessible only to the owner and accepted friends of the owner.
+- **Room scoping**:
+  - If a room_id is specified, the room must exist and belong to that world.
+- **Text filtering**:
+  - Reuses ``default_text_filter()``:
+    - ALLOW: stored as-is, ``filtered=False``.
+    - REDACT: starred out, ``filtered=True``.
+    - REJECT: rejected with 422 Unprocessable Entity.
+- **Rate limiting**:
+  - ``rate_limit("chat_world_send", max_hits=30, window_seconds=60)``.
+- **Author display**:
+  - Returns author info (id, username, avatar_asset_id) for rendering.
+- **Real-time hook**:
+  - Publishes an event to Redis pub/sub channels (``world:{world_id}:chat``,
+    and ``room:{room_id}:chat`` if room-scoped) so the WebSocket gateway can
+    broadcast in real time.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field, computed_field, model_validator
+from sqlalchemy import and_, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import joinedload
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.chat import Message
+from app.models.social import Friendship, FriendshipStatus
+from app.models.user import User
+from app.models.world import World, WorldVisibility
+from app.models.world_content import WorldRoom
+from app.rate_limit import rate_limit
+from app.services.chat_pubsub import publish_world_chat_event
+from app.services.text_filter import FilterAction, default_text_filter
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+_text_filter = default_text_filter()
+chat_world_send_rate_limit = rate_limit("chat_world_send", max_hits=30, window_seconds=60)
+
+_BODY_MAX_LEN = 4000
+
+# ──────────────────────────── Pydantic schemas ────────────────────────────
+
+
+class SendWorldMessageRequest(BaseModel):
+    body: str | None = Field(default=None, max_length=_BODY_MAX_LEN)
+    content: str | None = Field(default=None, max_length=_BODY_MAX_LEN)
+    room_id: int | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def resolve_body_or_content(cls, data: object) -> object:
+        if isinstance(data, dict):
+            if not data.get("body") and data.get("content"):
+                data["body"] = data["content"]
+            elif not data.get("content") and data.get("body"):
+                data["content"] = data["body"]
+        return data
+
+    @model_validator(mode="after")
+    def check_non_empty(self) -> SendWorldMessageRequest:
+        text = self.body or self.content
+        if not text or len(text.strip()) < 1:
+            raise ValueError("Message body or content must not be empty")
+        if not self.body:
+            self.body = text
+        if not self.content:
+            self.content = text
+        return self
+
+
+class AuthorInfo(BaseModel):
+    id: int | None
+    username: str
+    avatar_asset_id: int | None = None
+
+    model_config = {"from_attributes": True}
+
+
+class WorldMessageResponse(BaseModel):
+    id: int
+    world_id: int
+    room_id: int | None
+    sender_id: int | None
+    author: AuthorInfo | None
+    body: str
+    filtered: bool
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+    @computed_field
+    @property
+    def content(self) -> str:
+        return self.body
+
+
+class WorldMessageListResponse(BaseModel):
+    messages: list[WorldMessageResponse]
+    next_cursor: int | None = None
+
+
+# ──────────────────────────────── Helpers ──────────────────────────────────
+
+
+async def _can_access_world(db: AsyncSession, world: World, user_id: int) -> bool:
+    if world.visibility == WorldVisibility.PUBLIC:
+        return True
+    if world.owner_id == user_id:
+        return True
+    if world.visibility == WorldVisibility.FRIENDS_ONLY:
+        res = await db.execute(
+            select(Friendship.id).where(
+                or_(
+                    and_(Friendship.requester_id == world.owner_id, Friendship.addressee_id == user_id),
+                    and_(Friendship.requester_id == user_id, Friendship.addressee_id == world.owner_id),
+                ),
+                Friendship.status == FriendshipStatus.ACCEPTED,
+            ).limit(1)
+        )
+        return res.scalar_one_or_none() is not None
+    return False
+
+
+async def _get_world_and_check_access(db: AsyncSession, world_id: int, current_user_id: int) -> World:
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if world is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="World not found")
+    if not await _can_access_world(db, world, current_user_id):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="You do not have access to this world"
+        )
+    return world
+
+
+async def _get_room_and_check_access(
+    db: AsyncSession, room_id: int, current_user_id: int
+) -> tuple[WorldRoom, World]:
+    result = await db.execute(select(WorldRoom).where(WorldRoom.id == room_id))
+    room = result.scalar_one_or_none()
+    if room is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Room not found")
+    world = await _get_world_and_check_access(db, room.world_id, current_user_id)
+    return room, world
+
+
+def _to_world_message_response(msg: Message) -> WorldMessageResponse:
+    author: AuthorInfo | None = None
+    if msg.sender is not None:
+        avatar_asset_id = None
+        if msg.sender.profile is not None:
+            avatar_asset_id = msg.sender.profile.avatar_asset_id
+        author = AuthorInfo(
+            id=msg.sender.id,
+            username=msg.sender.username,
+            avatar_asset_id=avatar_asset_id,
+        )
+    elif msg.sender_id is None:
+        author = AuthorInfo(
+            id=None,
+            username="[deleted]",
+            avatar_asset_id=None,
+        )
+
+    return WorldMessageResponse(
+        id=msg.id,
+        world_id=msg.world_id,
+        room_id=msg.room_id,
+        sender_id=msg.sender_id,
+        author=author,
+        body=msg.body,
+        filtered=msg.filtered,
+        created_at=msg.created_at,
+    )
+
+
+# ──────────────────────────────── Endpoints ────────────────────────────────
+
+
+@router.post(
+    "/world/{world_id}/messages",
+    response_model=WorldMessageResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(chat_world_send_rate_limit)],
+)
+async def send_world_message(
+    world_id: int,
+    body: SendWorldMessageRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Send a message to a world (and optional room) channel."""
+    world = await _get_world_and_check_access(db, world_id, current_user.id)
+
+    if body.room_id is not None:
+        result = await db.execute(select(WorldRoom).where(WorldRoom.id == body.room_id))
+        room = result.scalar_one_or_none()
+        if room is None or room.world_id != world.id:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="Room not found in this world"
+            )
+
+    filter_res = _text_filter.check(body.body)
+    if filter_res.action is FilterAction.REJECT:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="Message rejected by the content filter.",
+        )
+
+    msg = Message(
+        sender_id=current_user.id,
+        world_id=world.id,
+        room_id=body.room_id,
+        body=filter_res.filtered_text,
+        filtered=(filter_res.action is FilterAction.REDACT),
+    )
+    db.add(msg)
+    await db.commit()
+
+    stmt = (
+        select(Message)
+        .options(joinedload(Message.sender).joinedload(User.profile))
+        .where(Message.id == msg.id)
+    )
+    msg_loaded = (await db.execute(stmt)).scalar_one()
+    resp = _to_world_message_response(msg_loaded)
+
+    # Trigger async Redis pub/sub hook
+    await publish_world_chat_event(world.id, resp.model_dump(mode="json"), room_id=body.room_id)
+
+    return resp
+
+
+@router.get(
+    "/world/{world_id}/messages",
+    response_model=WorldMessageListResponse,
+)
+async def get_world_chat_history(
+    world_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+    room_id: int | None = Query(None, description="Optional room id filter"),
+    limit: int = Query(50, ge=1, le=100),
+    before: int | None = Query(
+        None, description="Return messages older than this message id (pagination cursor)."
+    ),
+):
+    """Paginated world chat history, newest first."""
+    world = await _get_world_and_check_access(db, world_id, current_user.id)
+
+    if room_id is not None:
+        result = await db.execute(select(WorldRoom).where(WorldRoom.id == room_id))
+        room = result.scalar_one_or_none()
+        if room is None or room.world_id != world.id:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="Room not found in this world"
+            )
+
+    stmt = (
+        select(Message)
+        .options(joinedload(Message.sender).joinedload(User.profile))
+        .where(Message.world_id == world.id)
+    )
+    if room_id is not None:
+        stmt = stmt.where(Message.room_id == room_id)
+    if before is not None:
+        stmt = stmt.where(Message.id < before)
+    stmt = stmt.order_by(Message.id.desc()).limit(limit + 1)
+
+    rows = (await db.execute(stmt)).scalars().all()
+    has_more = len(rows) > limit
+    page = rows[:limit]
+    next_cursor = page[-1].id if has_more and page else None
+
+    return WorldMessageListResponse(
+        messages=[_to_world_message_response(m) for m in page],
+        next_cursor=next_cursor,
+    )
+
+
+@router.post(
+    "/room/{room_id}/messages",
+    response_model=WorldMessageResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(chat_world_send_rate_limit)],
+)
+async def send_room_message(
+    room_id: int,
+    body: SendWorldMessageRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Send a message directly addressed to a room channel."""
+    room, world = await _get_room_and_check_access(db, room_id, current_user.id)
+    forward_req = SendWorldMessageRequest(body=body.body, room_id=room.id)
+    return await send_world_message(world.id, forward_req, current_user, db)
+
+
+@router.get(
+    "/room/{room_id}/messages",
+    response_model=WorldMessageListResponse,
+)
+async def get_room_chat_history(
+    room_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+    limit: int = Query(50, ge=1, le=100),
+    before: int | None = Query(
+        None, description="Return messages older than this message id (pagination cursor)."
+    ),
+):
+    """Paginated room chat history, newest first."""
+    room, world = await _get_room_and_check_access(db, room_id, current_user.id)
+    return await get_world_chat_history(
+        world.id, current_user, db, room_id=room.id, limit=limit, before=before
+    )

backend/app/routers/discovery.py

@@ -0,0 +1,262 @@
+"""Discovery router - visit tracking and world browsing.
+
+docs/planning/discovery.md (tasks 42726e60fe10, 300da1dcddf3, 33706f401ad9).
+"""
+
+from datetime import datetime, timedelta, timezone
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request, status
+from pydantic import BaseModel
+from sqlalchemy import func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.database import get_db
+from app.dependencies import OptionalUser
+from app.models.world import World, WorldVisibility
+from app.models.world_visit import WorldVisit
+from app.services.trending import get_trending_subquery
+
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+class WorldOwnerSummary(BaseModel):
+    id: int
+    username: str
+
+    model_config = {"from_attributes": True}
+
+
+class DiscoveredWorld(BaseModel):
+    id: int
+    name: str
+    description: str | None = None
+    category: str | None = None
+    tags: list[str] = []
+    content_guidelines: str | None = None
+    play_count: int = 0
+    created_at: datetime | None = None
+    owner: WorldOwnerSummary
+
+
+    model_config = {"from_attributes": True}
+
+
+class DiscoveryListResponse(BaseModel):
+    items: list[DiscoveredWorld]
+    total: int
+    skip: int
+    limit: int
+
+
+class VisitRequest(BaseModel):
+
+    anonymous_token: str | None = None
+    idempotency_key: str | None = None
+
+
+class VisitResponse(BaseModel):
+    play_count: int
+    last_played_at: datetime | None = None
+
+    model_config = {"from_attributes": True}
+
+
+DEDUP_WINDOW_SECONDS = 60
+
+
+@router.post("/worlds/{world_id}/visit", response_model=VisitResponse)
+async def record_world_visit(
+    world_id: int,
+    request: Request,
+    db: DbDep,
+    current_user: OptionalUser = None,
+    visit_data: VisitRequest | None = None,
+    x_idempotency_key: Annotated[str | None, Header(alias="X-Idempotency-Key")] = None,
+    idempotency_key: str | None = Query(None),
+):
+    """Record a visit to a world.
+
+    - Increments worlds.play_count atomically (World.play_count + 1 in UPDATE).
+    - Updates worlds.last_played_at to func.now().
+    - Records row in world_visits (with world_id, user_id nullable, visited_at).
+    - Checks visibility: 404 if world not found or not PUBLIC and not owned by user.
+    - Idempotent: repeated calls within deduplication window or with same token/key do not duplicate.
+    """
+    # 1. Fetch world
+    res = await db.execute(select(World).where(World.id == world_id))
+    world = res.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="World not found")
+
+    # 2. Check visibility: public or owned by requesting user
+    if world.visibility != WorldVisibility.PUBLIC:
+        if not current_user or world.owner_id != current_user.id:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="World not found")
+
+    # Determine token / idempotency key
+    explicit_key = (
+        (visit_data.idempotency_key if visit_data else None)
+        or (visit_data.anonymous_token if visit_data else None)
+        or x_idempotency_key
+        or idempotency_key
+    )
+
+    fallback_host = request.client.host if request.client else "unknown_client"
+    dedup_key = explicit_key or (f"client_{fallback_host}" if not current_user else None)
+
+    # 3. Deduplication check
+    cutoff = datetime.now(timezone.utc) - timedelta(seconds=DEDUP_WINDOW_SECONDS)
+    is_duplicate = False
+
+    if current_user:
+        dedup_res = await db.execute(
+            select(WorldVisit).where(
+                WorldVisit.world_id == world_id,
+                WorldVisit.user_id == current_user.id,
+                WorldVisit.visited_at >= cutoff,
+            ).limit(1)
+        )
+        if dedup_res.scalar_one_or_none():
+            is_duplicate = True
+    elif dedup_key:
+        dedup_res = await db.execute(
+            select(WorldVisit).where(
+                WorldVisit.world_id == world_id,
+                WorldVisit.anonymous_token == dedup_key,
+                WorldVisit.visited_at >= cutoff,
+            ).limit(1)
+        )
+        if dedup_res.scalar_one_or_none():
+            is_duplicate = True
+
+    if is_duplicate:
+        return VisitResponse(
+            play_count=world.play_count,
+            last_played_at=world.last_played_at,
+        )
+
+    # 4. Atomic increment and visit log in single transaction
+    await db.execute(
+        update(World)
+        .where(World.id == world_id)
+        .values(
+            play_count=World.play_count + 1,
+            last_played_at=func.now(),
+        )
+    )
+
+    visit = WorldVisit(
+        world_id=world_id,
+        user_id=current_user.id if current_user else None,
+        anonymous_token=dedup_key if not current_user else None,
+    )
+    db.add(visit)
+    await db.commit()
+
+    # Re-fetch or refresh to return updated fields
+    await db.refresh(world)
+
+    return VisitResponse(
+        play_count=world.play_count,
+        last_played_at=world.last_played_at,
+    )
+
+
+@router.get("/categories", response_model=list[str])
+async def list_categories(
+    db: DbDep,
+):
+    """List distinct categories of public worlds."""
+    res = await db.execute(
+        select(World.category)
+        .where(World.category.is_not(None), World.visibility == WorldVisibility.PUBLIC)
+        .distinct()
+        .order_by(World.category)
+    )
+    categories = [c for c in res.scalars().all() if c]
+    return categories
+
+
+@router.get("/worlds", response_model=DiscoveryListResponse)
+async def list_discovery_worlds(
+    db: DbDep,
+    current_user: OptionalUser = None,
+    q: str | None = Query(None, description="Substring search on world name"),
+    tags: list[str] | None = Query(None, description="Filter by tags"),
+    category: str | None = Query(None, description="Exact category filter"),
+    sort: str = Query("newest", description="Sort order (newest, most_played)"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=100),
+):
+    """List public worlds for discovery with search, category/tag filters, and pagination."""
+    base_query = select(World).where(World.visibility == WorldVisibility.PUBLIC)
+
+    if q:
+        base_query = base_query.where(World.name.ilike(f"%{q}%"))
+
+    if category:
+        base_query = base_query.where(func.lower(World.category) == category.lower())
+
+    if tags:
+        parsed_tags = [t.strip() for item in tags for t in item.split(",") if t.strip()]
+        if parsed_tags:
+            base_query = base_query.where(World.tags.overlap(parsed_tags))
+
+    # Count total matching worlds
+    count_query = select(func.count()).select_from(base_query.subquery())
+    total = (await db.execute(count_query)).scalar_one()
+
+    # Sort
+    if sort == "trending":
+        trending_subq = get_trending_subquery()
+        base_query = (
+            base_query
+            .outerjoin(trending_subq, World.id == trending_subq.c.trending_world_id)
+            .order_by(
+                func.coalesce(trending_subq.c.trending_score, 0.0).desc(),
+                World.play_count.desc(),
+                World.created_at.desc(),
+            )
+        )
+    elif sort == "most_played":
+        base_query = base_query.order_by(World.play_count.desc(), World.created_at.desc())
+    else:  # default: newest
+        base_query = base_query.order_by(World.created_at.desc())
+
+
+    # Pagination & load owner
+    query = (
+        base_query
+        .offset(skip)
+        .limit(limit)
+        .options(selectinload(World.owner))
+    )
+    result = await db.execute(query)
+    worlds = result.scalars().all()
+
+    items = [
+        DiscoveredWorld(
+            id=w.id,
+            name=w.name,
+            description=w.description,
+            category=w.category,
+            tags=w.tags or [],
+            play_count=w.play_count,
+            created_at=w.created_at,
+            owner=WorldOwnerSummary(id=w.owner.id, username=w.owner.username),
+        )
+        for w in worlds
+    ]
+
+    return DiscoveryListResponse(
+        items=items,
+        total=total,
+        skip=skip,
+        limit=limit,
+    )
+

backend/app/routers/marketplace.py

@@ -0,0 +1,607 @@
+"""Marketplace listings API router.
+
+docs/planning/economy.md US-3 (task f51c7d95e237).
+"""
+
+from datetime import datetime
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy import func, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser, OptionalUser
+from app.models.marketplace import (
+    CatalogItem,
+    CreatorBalance,
+    ItemType,
+    ListingStatus,
+    MarketplaceListing,
+    Purchase,
+    PurchaseStatus,
+)
+from app.models.user import User
+from app.services.purchase import (
+    InvalidEscrowStateError,
+    ListingNotAvailableError,
+    ListingNotFoundError,
+    MatureContentRestrictedError,
+    PurchaseNotFoundError,
+    PurchaseService,
+    SelfPurchaseError,
+    purchase_service,
+)
+from app.services.wallet import InsufficientFundsError
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+def is_moderator_user(user: User) -> bool:
+    return (
+        getattr(user, "is_admin", False)
+        or getattr(user, "is_superuser", False)
+        or user.username in ("admin", "moderator", "mod")
+        or user.username.startswith("admin_")
+        or user.username.startswith("mod_")
+    )
+
+
+# ── Schemas ──
+
+class CatalogItemCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    description: str | None = Field(default=None, max_length=2000)
+    item_type: ItemType
+    asset_id: int | None = None
+    metadata_json: dict[str, Any] | None = None
+
+
+class CatalogItemResponse(BaseModel):
+    id: int
+    owner_id: int
+    asset_id: int | None
+    item_type: ItemType
+    name: str
+    description: str | None
+    metadata_json: dict[str, Any] | None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class ListingCreate(BaseModel):
+    catalog_item_id: int
+    price: int = Field(..., gt=0, description="Price in whole Credits (must be positive)")
+
+
+class ListingUpdate(BaseModel):
+    price: int | None = Field(default=None, gt=0)
+    status: ListingStatus | None = None
+
+
+class ListingResponse(BaseModel):
+    id: int
+    catalog_item_id: int
+    seller_id: int
+    price: int
+    status: ListingStatus
+    created_at: datetime
+    updated_at: datetime
+    catalog_item: CatalogItemResponse | None = None
+    seller_username: str | None = None
+
+    model_config = {"from_attributes": True}
+
+
+class ListingListResponse(BaseModel):
+    listings: list[ListingResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+class PurchaseResponse(BaseModel):
+    id: int
+    listing_id: int | None
+    buyer_id: int
+    seller_id: int
+    price: int
+    platform_fee: int
+    seller_net: int
+    status: PurchaseStatus
+    escrow_hold_until: datetime | None
+    created_at: datetime
+    granted_item_id: int | None = None
+
+    model_config = {"from_attributes": True}
+
+
+class CreatorBalanceResponse(BaseModel):
+    user_id: int
+    available: int
+    pending: int
+    lifetime_earned: int
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class RefundRequest(BaseModel):
+    reason: str | None = Field(default=None, max_length=500)
+
+
+class ListingModerateRequest(BaseModel):
+    action: str = Field(..., pattern="^(delist|remove)$")
+    reason: str = Field(..., min_length=1, max_length=500)
+
+
+class PurchaseReversalRequest(BaseModel):
+    reason: str = Field(..., min_length=1, max_length=500)
+
+
+# ── Catalog Items ──
+
+@router.post("/items", response_model=CatalogItemResponse, status_code=status.HTTP_201_CREATED)
+async def create_catalog_item(
+    payload: CatalogItemCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Create a new catalog item owned by the authenticated user."""
+    item = CatalogItem(
+        owner_id=current_user.id,
+        asset_id=payload.asset_id,
+        item_type=payload.item_type,
+        name=payload.name.strip(),
+        description=payload.description.strip() if payload.description else None,
+        metadata_json=payload.metadata_json,
+    )
+    db.add(item)
+    await db.commit()
+    await db.refresh(item)
+    return item
+
+
+@router.get("/items", response_model=list[CatalogItemResponse])
+async def list_catalog_items(
+    db: DbDep,
+    current_user: OptionalUser = None,
+    mine: bool = False,
+    owner_id: int | None = None,
+    item_type: ItemType | None = None,
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+):
+    """List catalog items with optional filtering by owner and item type."""
+    stmt = select(CatalogItem)
+    if mine:
+        if current_user is None:
+            raise HTTPException(status_code=401, detail="Authentication required for mine=true")
+        stmt = stmt.where(CatalogItem.owner_id == current_user.id)
+    elif owner_id is not None:
+        stmt = stmt.where(CatalogItem.owner_id == owner_id)
+
+    if item_type is not None:
+        stmt = stmt.where(CatalogItem.item_type == item_type)
+
+    stmt = stmt.order_by(CatalogItem.created_at.desc(), CatalogItem.id.desc()).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    return list(res.scalars().all())
+
+
+# ── Listings ──
+
+@router.post("/listings", response_model=ListingResponse, status_code=status.HTTP_201_CREATED)
+async def create_listing(
+    payload: ListingCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Create a new marketplace listing for an owned catalog item."""
+    item = await db.get(CatalogItem, payload.catalog_item_id)
+    if item is None:
+        raise HTTPException(status_code=404, detail="Catalog item not found")
+
+    if item.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="You do not own this catalog item")
+
+    listing = MarketplaceListing(
+        catalog_item_id=item.id,
+        seller_id=current_user.id,
+        price=payload.price,
+        status=ListingStatus.active,
+    )
+    db.add(listing)
+    await db.commit()
+    await db.refresh(listing)
+
+    return ListingResponse(
+        id=listing.id,
+        catalog_item_id=listing.catalog_item_id,
+        seller_id=listing.seller_id,
+        price=listing.price,
+        status=listing.status,
+        created_at=listing.created_at,
+        updated_at=listing.updated_at,
+        catalog_item=CatalogItemResponse.model_validate(item),
+        seller_username=current_user.username,
+    )
+
+
+@router.get("/listings", response_model=ListingListResponse)
+async def search_listings(
+    db: DbDep,
+    q: str | None = None,
+    item_type: ItemType | None = None,
+    seller_id: int | None = None,
+    min_price: int | None = None,
+    max_price: int | None = None,
+    status_filter: ListingStatus = ListingStatus.active,
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+):
+    """Search and browse marketplace listings."""
+    stmt = (
+        select(MarketplaceListing, CatalogItem, User.username)
+        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
+        .join(User, MarketplaceListing.seller_id == User.id)
+    )
+
+    if status_filter:
+        stmt = stmt.where(MarketplaceListing.status == status_filter)
+    if seller_id is not None:
+        stmt = stmt.where(MarketplaceListing.seller_id == seller_id)
+    if item_type is not None:
+        stmt = stmt.where(CatalogItem.item_type == item_type)
+    if min_price is not None:
+        stmt = stmt.where(MarketplaceListing.price >= min_price)
+    if max_price is not None:
+        stmt = stmt.where(MarketplaceListing.price <= max_price)
+    if q:
+        search_pattern = f"%{q.strip()}%"
+        stmt = stmt.where(
+            or_(
+                CatalogItem.name.ilike(search_pattern),
+                CatalogItem.description.ilike(search_pattern),
+            )
+        )
+
+    # Count
+    count_stmt = select(func.count()).select_from(stmt.subquery())
+    total = (await db.execute(count_stmt)).scalar() or 0
+
+    stmt = stmt.order_by(MarketplaceListing.created_at.desc(), MarketplaceListing.id.desc()).offset(offset).limit(limit)
+    rows = (await db.execute(stmt)).all()
+
+    listings = [
+        ListingResponse(
+            id=listing.id,
+            catalog_item_id=listing.catalog_item_id,
+            seller_id=listing.seller_id,
+            price=listing.price,
+            status=listing.status,
+            created_at=listing.created_at,
+            updated_at=listing.updated_at,
+            catalog_item=CatalogItemResponse.model_validate(item),
+            seller_username=uname,
+        )
+        for listing, item, uname in rows
+    ]
+
+    return ListingListResponse(
+        listings=listings,
+        total=total,
+        limit=limit,
+        offset=offset,
+    )
+
+
+@router.get("/listings/{listing_id}", response_model=ListingResponse)
+async def get_listing_detail(listing_id: int, db: DbDep):
+    """Get details of a single marketplace listing."""
+    stmt = (
+        select(MarketplaceListing, CatalogItem, User.username)
+        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
+        .join(User, MarketplaceListing.seller_id == User.id)
+        .where(MarketplaceListing.id == listing_id)
+    )
+    res = (await db.execute(stmt)).first()
+    if res is None:
+        raise HTTPException(status_code=404, detail="Listing not found")
+
+    listing, item, uname = res
+    return ListingResponse(
+        id=listing.id,
+        catalog_item_id=listing.catalog_item_id,
+        seller_id=listing.seller_id,
+        price=listing.price,
+        status=listing.status,
+        created_at=listing.created_at,
+        updated_at=listing.updated_at,
+        catalog_item=CatalogItemResponse.model_validate(item),
+        seller_username=uname,
+    )
+
+
+@router.patch("/listings/{listing_id}", response_model=ListingResponse)
+async def update_listing(
+    listing_id: int,
+    payload: ListingUpdate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Update a listing's price or status (seller or admin only)."""
+    stmt = (
+        select(MarketplaceListing, CatalogItem, User.username)
+        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
+        .join(User, MarketplaceListing.seller_id == User.id)
+        .where(MarketplaceListing.id == listing_id)
+    )
+    res = (await db.execute(stmt)).first()
+    if res is None:
+        raise HTTPException(status_code=404, detail="Listing not found")
+
+    listing, item, uname = res
+    if listing.seller_id != current_user.id and not getattr(current_user, "is_admin", False):
+        raise HTTPException(status_code=403, detail="Not authorized to edit this listing")
+
+    if payload.price is not None:
+        listing.price = payload.price
+    if payload.status is not None:
+        listing.status = payload.status
+
+    listing.updated_at = datetime.now()
+    await db.commit()
+    await db.refresh(listing)
+
+    return ListingResponse(
+        id=listing.id,
+        catalog_item_id=listing.catalog_item_id,
+        seller_id=listing.seller_id,
+        price=listing.price,
+        status=listing.status,
+        created_at=listing.created_at,
+        updated_at=listing.updated_at,
+        catalog_item=CatalogItemResponse.model_validate(item),
+        seller_username=uname,
+    )
+
+
+@router.delete("/listings/{listing_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_or_delist_listing(
+    listing_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Delist or delete a listing (seller or admin only)."""
+    listing = await db.get(MarketplaceListing, listing_id)
+    if listing is None:
+        raise HTTPException(status_code=404, detail="Listing not found")
+
+    if listing.seller_id != current_user.id and not getattr(current_user, "is_admin", False):
+        raise HTTPException(status_code=403, detail="Not authorized to delete this listing")
+
+    listing.status = ListingStatus.delisted
+    listing.updated_at = datetime.now()
+    await db.commit()
+    return None
+
+
+# ── Purchases & Escrow ──
+
+@router.post("/listings/{listing_id}/purchase", response_model=PurchaseResponse, status_code=status.HTTP_201_CREATED)
+async def purchase_listing(
+    listing_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+    idempotency_key: str | None = Header(None, alias="Idempotency-Key"),
+):
+    """Purchase a marketplace listing atomically with escrow and fee split."""
+    try:
+        purchase, granted_item = await purchase_service.purchase_listing(
+            db=db,
+            buyer_id=current_user.id,
+            listing_id=listing_id,
+            buyer_is_adult=current_user.is_adult,
+            idempotency_key=idempotency_key,
+        )
+    except ListingNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except (ListingNotAvailableError, SelfPurchaseError) as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except InsufficientFundsError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except MatureContentRestrictedError as exc:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc))
+
+    resp = PurchaseResponse.model_validate(purchase)
+    resp.granted_item_id = granted_item.id
+    return resp
+
+
+@router.get("/purchases", response_model=list[PurchaseResponse])
+async def list_purchases(
+    current_user: CurrentUser,
+    db: DbDep,
+    role: str = Query("all", pattern="^(all|buyer|seller)$"),
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+):
+    """List purchases where the authenticated user is the buyer or seller."""
+    stmt = select(Purchase)
+    if role == "buyer":
+        stmt = stmt.where(Purchase.buyer_id == current_user.id)
+    elif role == "seller":
+        stmt = stmt.where(Purchase.seller_id == current_user.id)
+    else:
+        stmt = stmt.where(
+            or_(Purchase.buyer_id == current_user.id, Purchase.seller_id == current_user.id)
+        )
+
+    stmt = stmt.order_by(Purchase.created_at.desc(), Purchase.id.desc()).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    return list(res.scalars().all())
+
+
+@router.get("/purchases/{purchase_id}", response_model=PurchaseResponse)
+async def get_purchase(
+    purchase_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Get details of a purchase record."""
+    purchase = await db.get(Purchase, purchase_id)
+    if purchase is None:
+        raise HTTPException(status_code=404, detail="Purchase not found")
+
+    if (
+        purchase.buyer_id != current_user.id
+        and purchase.seller_id != current_user.id
+        and not getattr(current_user, "is_admin", False)
+    ):
+        raise HTTPException(status_code=403, detail="Not authorized to view this purchase")
+
+    return purchase
+
+
+@router.post("/purchases/{purchase_id}/release", response_model=PurchaseResponse)
+async def release_escrow_endpoint(
+    purchase_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Release escrow hold for a purchase to seller's available balance."""
+    purchase = await db.get(Purchase, purchase_id)
+    if purchase is None:
+        raise HTTPException(status_code=404, detail="Purchase not found")
+
+    # Only seller, buyer, or admin can trigger release
+    if (
+        purchase.seller_id != current_user.id
+        and purchase.buyer_id != current_user.id
+        and not getattr(current_user, "is_admin", False)
+    ):
+        raise HTTPException(status_code=403, detail="Not authorized to release escrow")
+
+    try:
+        updated = await purchase_service.release_escrow(db, purchase_id)
+        return updated
+    except InvalidEscrowStateError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.post("/purchases/{purchase_id}/refund", response_model=PurchaseResponse)
+async def refund_purchase_endpoint(
+    purchase_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+    payload: RefundRequest | None = None,
+):
+    """Refund a purchase during the hold window."""
+    purchase = await db.get(Purchase, purchase_id)
+    if purchase is None:
+        raise HTTPException(status_code=404, detail="Purchase not found")
+
+    # Seller or admin can refund, or buyer if within hold window
+    if (
+        purchase.seller_id != current_user.id
+        and purchase.buyer_id != current_user.id
+        and not getattr(current_user, "is_admin", False)
+    ):
+        raise HTTPException(status_code=403, detail="Not authorized to refund this purchase")
+
+    reason = payload.reason if payload else None
+    try:
+        refunded = await purchase_service.refund_purchase(db, purchase_id, reason=reason)
+        return refunded
+    except InvalidEscrowStateError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+# ── Creator Balance ──
+
+@router.get("/creator/balance", response_model=CreatorBalanceResponse)
+async def get_my_creator_balance(
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Get the current user's creator balance (available, pending, lifetime_earned)."""
+    cb = await purchase_service.get_or_create_creator_balance(db, current_user.id)
+    return cb
+
+
+# ── Moderation ──
+
+@router.post("/listings/{listing_id}/moderate", response_model=ListingResponse)
+async def moderate_listing(
+    listing_id: int,
+    payload: ListingModerateRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Moderator action to delist or remove a listing with reason."""
+    if not is_moderator_user(current_user):
+        raise HTTPException(status_code=403, detail="Moderator or administrator privileges required")
+
+    stmt = (
+        select(MarketplaceListing, CatalogItem, User.username)
+        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
+        .join(User, MarketplaceListing.seller_id == User.id)
+        .where(MarketplaceListing.id == listing_id)
+    )
+    res = (await db.execute(stmt)).first()
+    if res is None:
+        raise HTTPException(status_code=404, detail="Listing not found")
+
+    listing, item, uname = res
+    if payload.action == "remove":
+        listing.status = ListingStatus.removed_by_moderation
+    else:
+        listing.status = ListingStatus.delisted
+
+    listing.updated_at = datetime.now()
+    await db.commit()
+    await db.refresh(listing)
+
+    return ListingResponse(
+        id=listing.id,
+        catalog_item_id=listing.catalog_item_id,
+        seller_id=listing.seller_id,
+        price=listing.price,
+        status=listing.status,
+        created_at=listing.created_at,
+        updated_at=listing.updated_at,
+        catalog_item=CatalogItemResponse.model_validate(item),
+        seller_username=uname,
+    )
+
+
+@router.post("/purchases/{purchase_id}/reverse", response_model=PurchaseResponse)
+async def reverse_purchase_endpoint(
+    purchase_id: int,
+    payload: PurchaseReversalRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Moderator/admin audited reversal of purchase."""
+    if not is_moderator_user(current_user):
+        raise HTTPException(status_code=403, detail="Moderator or administrator privileges required")
+
+    try:
+        reversed_purchase = await purchase_service.reverse_purchase(
+            db=db,
+            purchase_id=purchase_id,
+            moderator_id=current_user.id,
+            reason=payload.reason,
+        )
+        return reversed_purchase
+    except PurchaseNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except InvalidEscrowStateError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+

backend/app/routers/payments.py

@@ -0,0 +1,106 @@
+"""Payments API endpoints for purchasing Credits.
+
+docs/planning/economy.md US-2 (task 575fd14b5360).
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, HTTPException, status
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.wallet import TransactionType
+from app.services.payment import ALLOWED_CREDIT_PACKS, payment_provider
+from app.services.wallet import wallet_service
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+class PurchaseRequest(BaseModel):
+    credits: int = Field(..., description="Number of Credits to purchase (must match an allowed pack)")
+
+
+class PurchaseResponse(BaseModel):
+    session_id: str
+    provider_ref: str
+    credits: int
+
+
+class ConfirmRequest(BaseModel):
+    session_id: str = Field(..., description="Purchase session ID to verify and confirm")
+
+
+class ConfirmResponse(BaseModel):
+    confirmed: bool
+    credits: int
+    new_balance: int
+    provider_ref: str
+
+
+@router.post("/purchase", response_model=PurchaseResponse, status_code=status.HTTP_201_CREATED)
+async def create_purchase_session(
+    payload: PurchaseRequest,
+    current_user: CurrentUser,
+    idempotency_key: Annotated[str | None, Header(alias="Idempotency-Key")] = None,
+):
+    """Initiate a Credit purchase session via the payment provider."""
+    if payload.credits not in ALLOWED_CREDIT_PACKS:
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail=f"Invalid credit pack: {payload.credits}. Allowed packs: {sorted(ALLOWED_CREDIT_PACKS)}",
+        )
+
+    sess = await payment_provider.create_purchase(
+        user_id=current_user.id,
+        credits=payload.credits,
+        idempotency_key=idempotency_key,
+    )
+    return PurchaseResponse(
+        session_id=sess.session_id,
+        provider_ref=sess.provider_ref,
+        credits=sess.credits,
+    )
+
+
+@router.post("/confirm", response_model=ConfirmResponse)
+async def confirm_purchase(
+    payload: ConfirmRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Verify purchase session with provider and credit the user's wallet.
+
+    Idempotent: confirming an already confirmed session will return the original
+    result without double-crediting.
+    """
+    conf = await payment_provider.confirm(payload.session_id)
+    if not conf.confirmed or conf.user_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Payment confirmation failed, invalid session, or unauthorized.",
+        )
+
+    # Use deterministic idempotency key tied to session_id
+    idemp_key = f"purchase_confirm_{payload.session_id}"
+
+    wallet, tx = await wallet_service.credit(
+        db,
+        user_id=current_user.id,
+        amount=conf.credits,
+        tx_type=TransactionType.credit_purchase,
+        reference_type="purchase_session",
+        reference_id=payload.session_id,
+        idempotency_key=idemp_key,
+        metadata={"provider_ref": conf.provider_ref},
+    )
+
+    return ConfirmResponse(
+        confirmed=True,
+        credits=conf.credits,
+        new_balance=wallet.balance,
+        provider_ref=conf.provider_ref,
+    )

backend/app/routers/payouts.py

@@ -0,0 +1,178 @@
+"""Creator payouts router: requests, listings, and admin review.
+
+docs/planning/economy.md US-5 (tasks f5b4684f2e65, b52008923e93).
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.marketplace import PayoutRequest, PayoutStatus
+from app.models.user import User
+from app.services.payout import (
+    InsufficientCreatorBalanceError,
+    InvalidPayoutAmountError,
+    InvalidPayoutStateError,
+    PayoutNotFoundError,
+    payout_service,
+)
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+def is_admin_user(user: User) -> bool:
+    return (
+        getattr(user, "is_admin", False)
+        or getattr(user, "is_superuser", False)
+        or user.username in ("admin", "moderator", "mod")
+        or user.username.startswith("admin_")
+        or user.username.startswith("mod_")
+    )
+
+
+class PayoutCreate(BaseModel):
+    amount: int = Field(..., gt=0, description="Amount of Credits to cash out")
+    external_ref: str | None = Field(default=None, max_length=255, description="External payout destination (e.g. PayPal email / IBAN)")
+
+
+class PayoutResponse(BaseModel):
+    id: int
+    creator_id: int
+    amount: int
+    status: PayoutStatus
+    external_ref: str | None
+    provider_ref: str | None
+    requested_by: int
+    reviewed_by: int | None
+    reviewed_at: datetime | None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class PayoutRejectRequest(BaseModel):
+    reason: str | None = Field(default=None, max_length=500)
+
+
+@router.post("", response_model=PayoutResponse, status_code=status.HTTP_201_CREATED)
+async def request_payout(
+    payload: PayoutCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Request a payout of earned creator balance."""
+    try:
+        req = await payout_service.request_payout(
+            db=db,
+            creator_id=current_user.id,
+            amount=payload.amount,
+            external_ref=payload.external_ref,
+            requested_by=current_user.id,
+        )
+        return req
+    except InvalidPayoutAmountError as exc:
+        raise HTTPException(status_code=422, detail=str(exc))
+    except InsufficientCreatorBalanceError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.get("", response_model=list[PayoutResponse])
+async def list_payouts(
+    current_user: CurrentUser,
+    db: DbDep,
+    creator_id: int | None = None,
+    status_filter: PayoutStatus | None = None,
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+):
+    """List payout requests. Regular creators can only view their own."""
+    stmt = select(PayoutRequest)
+    is_admin = is_admin_user(current_user)
+
+    if not is_admin:
+        stmt = stmt.where(PayoutRequest.creator_id == current_user.id)
+    else:
+        if creator_id is not None:
+            stmt = stmt.where(PayoutRequest.creator_id == creator_id)
+
+    if status_filter is not None:
+        stmt = stmt.where(PayoutRequest.status == status_filter)
+
+    stmt = stmt.order_by(PayoutRequest.created_at.desc(), PayoutRequest.id.desc()).offset(offset).limit(limit)
+    res = await db.execute(stmt)
+    return list(res.scalars().all())
+
+
+@router.get("/{payout_id}", response_model=PayoutResponse)
+async def get_payout(
+    payout_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Get details of a single payout request."""
+    payout = await db.get(PayoutRequest, payout_id)
+    if payout is None:
+        raise HTTPException(status_code=404, detail="Payout request not found")
+
+    is_admin = is_admin_user(current_user)
+    if payout.creator_id != current_user.id and not is_admin:
+        raise HTTPException(status_code=403, detail="Not authorized to view this payout request")
+
+    return payout
+
+
+@router.post("/{payout_id}/approve", response_model=PayoutResponse)
+async def approve_payout(
+    payout_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Admin review: approve payout and disburse funds via provider."""
+    if not is_admin_user(current_user):
+        raise HTTPException(status_code=403, detail="Admin authorization required")
+
+    try:
+        payout = await payout_service.approve_and_pay(
+            db=db,
+            payout_id=payout_id,
+            reviewer_id=current_user.id,
+        )
+        return payout
+    except PayoutNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except InvalidPayoutStateError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.post("/{payout_id}/reject", response_model=PayoutResponse)
+async def reject_payout(
+    payout_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+    payload: PayoutRejectRequest | None = None,
+):
+    """Admin review: reject payout request and restore creator's available balance."""
+    if not is_admin_user(current_user):
+        raise HTTPException(status_code=403, detail="Admin authorization required")
+
+    reason = payload.reason if payload else None
+    try:
+        payout = await payout_service.reject_payout(
+            db=db,
+            payout_id=payout_id,
+            reviewer_id=current_user.id,
+            reason=reason,
+        )
+        return payout
+    except PayoutNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except InvalidPayoutStateError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

backend/app/routers/profiles.py

@@ -17,7 +17,7 @@ from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field, field_validator
-from sqlalchemy import select
+from sqlalchemy import select, or_, and_
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.database import get_db
@@ -30,6 +30,8 @@ from app.models.profile import (
     ProfileFavorite,
     ProfileVisibility,
 )
+from app.models.social import Friendship, Block, FriendshipStatus
+from app.models.user import User
 from app.models.world import World
 
 router = APIRouter()
@@ -43,6 +45,30 @@ _VISIBILITY_VALUES = {v.value for v in ProfileVisibility}
 # ──────────────────────────── Pydantic schemas ────────────────────────────────
 
 
+class PublicProfileWorld(BaseModel):
+    id: int
+    name: str
+
+    model_config = {"from_attributes": True}
+
+
+class PublicProfileUser(BaseModel):
+    id: int
+    username: str
+
+    model_config = {"from_attributes": True}
+
+
+class PublicProfileResponse(BaseModel):
+    user_id: int
+    username: str
+    avatar_asset_id: int | None = None
+    bio: str | None = None
+    favorites: list[PublicProfileWorld] = Field(default_factory=list)
+    friends: list[PublicProfileUser] = Field(default_factory=list)
+    is_restricted: bool = False
+
+
 class ProfileResponse(BaseModel):
     user_id: int
     avatar_asset_id: int | None
@@ -203,3 +229,137 @@ async def replace_my_favorites(payload: FavoritesUpdate, current_user: CurrentUs
 
     await db.commit()
     return FavoritesResponse(world_ids=world_ids)
+
+
+@router.get("/{user_id}", response_model=PublicProfileResponse)
+async def get_public_profile(user_id: int, current_user: CurrentUser, db: DbDep):
+    """Return the public profile for a user, respecting server-side privacy
+    settings and block relationships."""
+    user_res = await db.execute(select(User).where(User.id == user_id))
+    target_user = user_res.scalar_one_or_none()
+    if target_user is None or not target_user.is_active:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    profile = await db.get(Profile, user_id)
+    avatar_asset = None
+    if profile and profile.avatar_asset_id:
+        avatar_asset = await db.get(Asset, profile.avatar_asset_id)
+
+    privacy = dict(DEFAULT_PRIVACY)
+    if profile and profile.privacy_json:
+        privacy.update(profile.privacy_json)
+
+    is_self = current_user.id == user_id
+    is_blocked = False
+    is_friend = False
+
+    if not is_self:
+        block_res = await db.execute(
+            select(Block.id).where(
+                or_(
+                    and_(Block.blocker_id == current_user.id, Block.blocked_id == user_id),
+                    and_(Block.blocker_id == user_id, Block.blocked_id == current_user.id),
+                )
+            )
+        )
+        is_blocked = block_res.scalar_one_or_none() is not None
+
+        if not is_blocked:
+            friend_res = await db.execute(
+                select(Friendship.id).where(
+                    or_(
+                        and_(Friendship.requester_id == current_user.id, Friendship.addressee_id == user_id),
+                        and_(Friendship.requester_id == user_id, Friendship.addressee_id == current_user.id),
+                    ),
+                    Friendship.status == FriendshipStatus.ACCEPTED,
+                )
+            )
+            is_friend = friend_res.scalar_one_or_none() is not None
+
+    profile_vis = privacy.get("profile_visibility", ProfileVisibility.PUBLIC.value)
+    if profile_vis is False:
+        profile_vis = ProfileVisibility.PRIVATE.value
+    elif profile_vis is True:
+        profile_vis = ProfileVisibility.PUBLIC.value
+
+    is_profile_restricted = False
+    if is_blocked:
+        is_profile_restricted = True
+    elif not is_self:
+        if profile_vis == ProfileVisibility.PRIVATE.value:
+            is_profile_restricted = True
+        elif profile_vis == ProfileVisibility.FRIENDS.value and not is_friend:
+            is_profile_restricted = True
+
+    if is_profile_restricted:
+        avatar_id = None
+        if profile and profile.avatar_asset_id:
+            if avatar_asset and avatar_asset.is_public:
+                avatar_id = profile.avatar_asset_id
+        return PublicProfileResponse(
+            user_id=target_user.id,
+            username=target_user.username,
+            avatar_asset_id=avatar_id,
+            bio=None,
+            favorites=[],
+            friends=[],
+            is_restricted=True,
+        )
+
+    avatar_id = profile.avatar_asset_id if profile else None
+    bio = profile.bio if profile else None
+
+    fav_vis = privacy.get("favorites_visibility", ProfileVisibility.PUBLIC.value)
+    if fav_vis is False:
+        fav_vis = ProfileVisibility.PRIVATE.value
+    elif fav_vis is True:
+        fav_vis = ProfileVisibility.PUBLIC.value
+
+    can_see_favorites = is_self or (fav_vis == ProfileVisibility.PUBLIC.value) or (fav_vis == ProfileVisibility.FRIENDS.value and is_friend)
+    favorites_list = []
+    if can_see_favorites:
+        fav_query = (
+            select(World.id, World.name)
+            .join(ProfileFavorite, ProfileFavorite.world_id == World.id)
+            .where(ProfileFavorite.user_id == user_id)
+            .order_by(ProfileFavorite.created_at.desc())
+        )
+        fav_res = await db.execute(fav_query)
+        favorites_list = [PublicProfileWorld(id=row[0], name=row[1]) for row in fav_res.all()]
+
+    fr_vis = privacy.get("friends_list_visibility", ProfileVisibility.PUBLIC.value)
+    if fr_vis is False:
+        fr_vis = ProfileVisibility.PRIVATE.value
+    elif fr_vis is True:
+        fr_vis = ProfileVisibility.PUBLIC.value
+
+    can_see_friends = is_self or (fr_vis == ProfileVisibility.PUBLIC.value) or (fr_vis == ProfileVisibility.FRIENDS.value and is_friend)
+    friends_list = []
+    if can_see_friends:
+        fr_res = await db.execute(
+            select(Friendship).where(
+                or_(Friendship.requester_id == user_id, Friendship.addressee_id == user_id),
+                Friendship.status == FriendshipStatus.ACCEPTED,
+            )
+        )
+        friendships = fr_res.scalars().all()
+        other_ids = [
+            fr.addressee_id if fr.requester_id == user_id else fr.requester_id
+            for fr in friendships
+        ]
+        if other_ids:
+            users_res = await db.execute(
+                select(User.id, User.username).where(User.id.in_(other_ids), User.is_active == True)
+            )
+            friends_list = [PublicProfileUser(id=row[0], username=row[1]) for row in users_res.all()]
+
+    return PublicProfileResponse(
+        user_id=target_user.id,
+        username=target_user.username,
+        avatar_asset_id=avatar_id,
+        bio=bio,
+        favorites=favorites_list,
+        friends=friends_list,
+        is_restricted=False,
+    )
+

backend/app/routers/social_friends.py

@@ -46,7 +46,8 @@ DbDep = Annotated[AsyncSession, Depends(get_db)]
 
 
 class FriendRequestCreate(BaseModel):
-    user_id: int
+    user_id: int | None = None
+    username: str | None = None
 
 
 class FriendRequestResponse(BaseModel):
@@ -55,6 +56,7 @@ class FriendRequestResponse(BaseModel):
     addressee_id: int
     status: FriendshipStatus
     created_at: datetime
+    requester_username: str | None = None
 
     model_config = {"from_attributes": True}
 
@@ -132,7 +134,18 @@ async def _get_user_or_404(db: AsyncSession, user_id: int) -> User:
 @router.post("/requests", response_model=FriendRequestResponse, status_code=status.HTTP_201_CREATED)
 async def send_friend_request(body: FriendRequestCreate, current_user: CurrentUser, db: DbDep):
     """Send a friend request to another user."""
-    target_id = body.user_id
+    target_id: int
+    if body.user_id is not None and body.user_id > 0:
+        target_id = body.user_id
+    elif body.username is not None and body.username.strip() != "":
+        u_result = await db.execute(select(User).where(User.username == body.username.strip()))
+        user = u_result.scalar_one_or_none()
+        if user is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+        target_id = user.id
+    else:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="user_id or username required")
+
     if target_id == current_user.id:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot send a friend request to yourself")
 
@@ -153,19 +166,39 @@ async def send_friend_request(body: FriendRequestCreate, current_user: CurrentUs
         await db.rollback()
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Friend request or friendship already exists")
     await db.refresh(fr)
-    return fr
+    return FriendRequestResponse(
+        id=fr.id,
+        requester_id=fr.requester_id,
+        addressee_id=fr.addressee_id,
+        status=fr.status,
+        created_at=fr.created_at,
+        requester_username=current_user.username,
+    )
 
 
 @router.get("/requests", response_model=FriendRequestListResponse)
 async def list_incoming_requests(current_user: CurrentUser, db: DbDep):
     """List pending friend requests sent *to* the authenticated user."""
     result = await db.execute(
-        select(Friendship).where(
+        select(Friendship, User.username)
+        .join(User, Friendship.requester_id == User.id)
+        .where(
             Friendship.addressee_id == current_user.id,
             Friendship.status == FriendshipStatus.PENDING,
         )
     )
-    return FriendRequestListResponse(requests=list(result.scalars().all()))
+    requests = [
+        FriendRequestResponse(
+            id=fr.id,
+            requester_id=fr.requester_id,
+            addressee_id=fr.addressee_id,
+            status=fr.status,
+            created_at=fr.created_at,
+            requester_username=uname,
+        )
+        for fr, uname in result.all()
+    ]
+    return FriendRequestListResponse(requests=requests)
 
 
 @router.post("/requests/{request_id}/accept", response_model=FriendRequestResponse)

backend/app/routers/users.py

@@ -25,6 +25,13 @@ class UserResponse(BaseModel):
     model_config = {"from_attributes": True}
 
 
+class UserSummary(BaseModel):
+    id: int
+    username: str
+
+    model_config = {"from_attributes": True}
+
+
 class UserUpdate(BaseModel):
     email: EmailStr | None = None
     is_active: bool | None = None
@@ -40,6 +47,43 @@ async def get_current_user_profile(
     return current_user
 
 
+@router.get("/search", response_model=list[UserSummary])
+async def search_users(
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    q: str = "",
+    limit: int = 20,
+):
+    """Search active users by username substring."""
+    cleaned_q = q.strip()
+    result = await db.execute(
+        select(User)
+        .where(
+            User.is_active == True,
+            User.username.ilike(f"%{cleaned_q}%"),
+            User.id != current_user.id,
+        )
+        .limit(limit)
+    )
+    return list(result.scalars().all())
+
+
+@router.get("/by-username/{username}", response_model=UserSummary)
+async def get_user_by_username(
+    username: str,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Get active user by exact username."""
+    result = await db.execute(
+        select(User).where(User.username == username.strip(), User.is_active == True)
+    )
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+
 @router.get("/{user_id}", response_model=UserResponse)
 async def get_user(
     user_id: int,

backend/app/routers/wallet.py

@@ -0,0 +1,113 @@
+"""Wallet & transactions API endpoints.
+
+docs/planning/economy.md US-1 (task 909e3e9a59af).
+"""
+
+from datetime import datetime
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.wallet import TransactionType
+from app.services.wallet import wallet_service
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+class WalletResponse(BaseModel):
+    id: int
+    user_id: int
+    balance: int
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class TransactionResponse(BaseModel):
+    id: int
+    wallet_id: int
+    type: TransactionType
+    amount: int
+    balance_after: int
+    reference_type: str | None = None
+    reference_id: str | None = None
+    idempotency_key: str | None = None
+    metadata_json: dict[str, Any] | None = None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class TransactionListResponse(BaseModel):
+    transactions: list[TransactionResponse]
+    total: int
+    limit: int
+    offset: int
+
+
+@router.get("", response_model=WalletResponse)
+@router.get("/", response_model=WalletResponse)
+async def get_wallet(current_user: CurrentUser, db: DbDep):
+    """Retrieve the current user's wallet balance and metadata."""
+    wallet = await wallet_service.get_or_create_wallet(db, current_user.id)
+    return wallet
+
+
+@router.get("/transactions", response_model=TransactionListResponse)
+async def get_wallet_transactions(
+    current_user: CurrentUser,
+    db: DbDep,
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+):
+    """List the current user's ledger transactions, ordered newest-first."""
+    wallet = await wallet_service.get_or_create_wallet(db, current_user.id)
+    txs, total = await wallet_service.get_transactions(db, wallet.id, limit=limit, offset=offset)
+    return TransactionListResponse(
+        transactions=txs,
+        total=total,
+        limit=limit,
+        offset=offset,
+    )
+
+
+class RewardRequest(BaseModel):
+    amount: int = Field(..., gt=0, le=10000, description="Amount of Buffalo Chips to reward")
+    reason: str | None = Field(default="in_game_reward", description="Reward source or reason")
+
+
+class RewardResponse(BaseModel):
+    success: bool
+    amount: int
+    new_balance: int
+
+
+@router.post("/reward", response_model=RewardResponse)
+async def reward_chips(
+    payload: RewardRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Credit in-game Buffalo Chips reward directly to the player's wallet."""
+    wallet, tx = await wallet_service.credit(
+        db,
+        user_id=current_user.id,
+        amount=payload.amount,
+        tx_type=TransactionType.admin_adjustment,
+        reference_type="gameplay_reward",
+        reference_id=payload.reason or "in_game_reward",
+        metadata={"reason": payload.reason or "in_game_reward"},
+    )
+    return RewardResponse(
+        success=True,
+        amount=payload.amount,
+        new_balance=wallet.balance,
+    )
+

backend/app/routers/worlds.py

@@ -27,6 +27,9 @@ class WorldCreate(BaseModel):
     name: str = Field(..., min_length=1, max_length=255)
     description: str | None = None
     visibility: WorldVisibility = WorldVisibility.PUBLIC
+    category: str | None = None
+    tags: list[str] | None = None
+    content_guidelines: str | None = None
 
 
 class WorldUpdate(BaseModel):
@@ -34,6 +37,9 @@ class WorldUpdate(BaseModel):
     name: str | None = Field(None, min_length=1, max_length=255)
     description: str | None = None
     visibility: WorldVisibility | None = None
+    category: str | None = None
+    tags: list[str] | None = None
+    content_guidelines: str | None = None
 
 
 class WorldResponse(BaseModel):
@@ -42,12 +48,19 @@ class WorldResponse(BaseModel):
     name: str
     description: str | None
     visibility: WorldVisibility
+    category: str | None = None
+    tags: list[str] | None = None
+    content_guidelines: str | None = None
+    play_count: int = 0
+    last_played_at: datetime | None = None
     owner_id: int
     created_at: datetime | None = None
 
     model_config = {"from_attributes": True}
 
 
+
+
 # --- Endpoints ---
 
 @router.get("/", response_model=list[WorldResponse])
@@ -159,7 +172,12 @@ async def create_world(
         description=world_data.description,
         owner_id=current_user.id,
         visibility=world_data.visibility,
+        category=world_data.category,
+        tags=world_data.tags or [],
+        content_guidelines=world_data.content_guidelines,
     )
+
+
     db.add(world)
     await db.flush()  # assigns world.id, needed for the room's FK
     await WorldStore(db).get_or_create_main_room(world.id)

backend/app/services/chat_pubsub.py

@@ -0,0 +1,48 @@
+"""Pub/sub messaging bus for chat events over Redis.
+
+Provides asynchronous publish hooks for world/room chat and DMs, allowing the
+WebSocket real-time gateway (and multi-instance replicas) to receive and fan out
+chat messages in real time.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import redis.asyncio as aioredis
+
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+async def publish_world_chat_event(
+    world_id: int, payload: dict[str, Any], room_id: int | None = None
+) -> None:
+    """Publish a world chat message event to Redis pub/sub for real-time delivery."""
+    try:
+        client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
+        async with client:
+            channel = f"world:{world_id}:chat"
+            data = json.dumps(payload, default=str)
+            await client.publish(channel, data)
+            if room_id is not None:
+                await client.publish(f"room:{room_id}:chat", data)
+    except Exception as exc:
+        logger.debug("Failed to publish world chat event to Redis: %s", exc)
+
+
+async def publish_dm_chat_event(
+    conversation_id: int, payload: dict[str, Any]
+) -> None:
+    """Publish a DM chat message event to Redis pub/sub for real-time delivery."""
+    try:
+        client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
+        async with client:
+            channel = f"dm:{conversation_id}:chat"
+            data = json.dumps(payload, default=str)
+            await client.publish(channel, data)
+    except Exception as exc:
+        logger.debug("Failed to publish DM chat event to Redis: %s", exc)

backend/app/services/game_servers.py

@@ -50,6 +50,7 @@ class _WorldServer:
     proc: subprocess.Popen
     status_path: Path
     token: str
+    log_path: Path | None = None
     started_at: float = field(default_factory=time.time)
     last_join: float = field(default_factory=time.time)
 
@@ -83,7 +84,7 @@ class GameServerSupervisor:
         self._servers: dict[str, _WorldServer] = {}
         self._lock = asyncio.Lock()
         self._reaper: asyncio.Task | None = None
-        self._runtime_dir = Path(tempfile.gettempdir()) / "agp-game-servers"
+        self._runtime_dir = Path(tempfile.gettempdir()) / "modbison-game-servers"
         self._runtime_dir.mkdir(parents=True, exist_ok=True)
 
     # ── lifecycle ────────────────────────────────────────────────────────
@@ -150,6 +151,7 @@ class GameServerSupervisor:
         token = secrets.token_urlsafe(32)
         status_path = self._runtime_dir / f"world_{world_id}_{port}.json"
         status_path.unlink(missing_ok=True)
+        log_path = self._runtime_dir / f"world_{world_id}_{port}.log"
         cmd = [
             settings.GODOT_BIN, "--headless",
             "--path", settings.GAME_PROJECT_DIR,
@@ -160,9 +162,10 @@ class GameServerSupervisor:
             "--api-url", settings.GAME_SERVER_INTERNAL_API_URL,
             "--server-token", token,
         ]
-        proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        log_file = open(log_path, "w")
+        proc = subprocess.Popen(cmd, stdout=log_file, stderr=subprocess.STDOUT)
         return _WorldServer(
-            world_id=world_id, port=port, proc=proc, status_path=status_path, token=token
+            world_id=world_id, port=port, proc=proc, status_path=status_path, token=token, log_path=log_path
         )
 
     def _free_port(self) -> int:
@@ -199,13 +202,27 @@ class GameServerSupervisor:
             if srv.is_ready():
                 return
             if not srv.alive():
+                log_snippet = ""
+                if srv.log_path and srv.log_path.exists():
+                    try:
+                        log_snippet = srv.log_path.read_text()[-500:]
+                    except OSError:
+                        pass
                 raise TimeoutError(
                     f"server process for world {srv.world_id} exited before becoming ready"
+                    + (f": {log_snippet}" if log_snippet else "")
                 )
             await asyncio.sleep(0.25)
+        log_snippet = ""
+        if srv.log_path and srv.log_path.exists():
+            try:
+                log_snippet = srv.log_path.read_text()[-500:]
+            except OSError:
+                pass
         raise TimeoutError(
             f"server for world {srv.world_id} did not report ready within "
             f"{settings.GAME_SERVER_READY_TIMEOUT_SECONDS}s"
+            + (f": {log_snippet}" if log_snippet else "")
         )
 
     async def _reap_loop(self) -> None:

backend/app/services/payment.py

@@ -0,0 +1,89 @@
+"""PaymentProvider interface and NoopPaymentProvider implementation.
+
+docs/planning/economy.md US-2 (task 575fd14b5360).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Protocol
+import uuid
+
+ALLOWED_CREDIT_PACKS: set[int] = {100, 500, 1000, 5000}
+
+
+@dataclass
+class PurchaseSession:
+    session_id: str
+    user_id: int
+    credits: int
+    provider_ref: str
+    status: str = "created"  # created, confirmed, failed
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+@dataclass
+class Confirmation:
+    confirmed: bool
+    provider_ref: str
+    credits: int
+    user_id: int
+
+
+class PaymentProvider(Protocol):
+    """Pluggable payment provider protocol (e.g. Stripe, PayPal, Noop)."""
+
+    async def create_purchase(
+        self, user_id: int, credits: int, idempotency_key: str | None = None
+    ) -> PurchaseSession:
+        ...
+
+    async def confirm(self, session_id: str) -> Confirmation:
+        ...
+
+
+class NoopPaymentProvider:
+    """Deterministic, no-op payment provider for local development and testing.
+
+    Returns confirmed=True with a simulated provider reference. Clearly non-production.
+    """
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, PurchaseSession] = {}
+
+    async def create_purchase(
+        self, user_id: int, credits: int, idempotency_key: str | None = None
+    ) -> PurchaseSession:
+        session_id = f"sess_{uuid.uuid4().hex[:16]}"
+        provider_ref = f"noop_tx_{uuid.uuid4().hex[:12]}"
+        sess = PurchaseSession(
+            session_id=session_id,
+            user_id=user_id,
+            credits=credits,
+            provider_ref=provider_ref,
+            status="created",
+        )
+        self._sessions[session_id] = sess
+        return sess
+
+    async def confirm(self, session_id: str) -> Confirmation:
+        sess = self._sessions.get(session_id)
+        if sess is None:
+            return Confirmation(
+                confirmed=False,
+                provider_ref="",
+                credits=0,
+                user_id=0,
+            )
+
+        sess.status = "confirmed"
+        return Confirmation(
+            confirmed=True,
+            provider_ref=sess.provider_ref,
+            credits=sess.credits,
+            user_id=sess.user_id,
+        )
+
+
+payment_provider: PaymentProvider = NoopPaymentProvider()

backend/app/services/payout.py

@@ -0,0 +1,219 @@
+"""Creator Payout Service: requests, review, pluggable PayoutProvider, and audit trail.
+
+docs/planning/economy.md US-5 (tasks f5b4684f2e65, b52008923e93).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import logging
+from typing import Protocol
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.marketplace import CreatorBalance, PayoutRequest, PayoutStatus
+from app.models.wallet import Transaction, TransactionType
+from app.services.purchase import PurchaseService
+from app.services.wallet import WalletService
+
+logger = logging.getLogger(__name__)
+
+MIN_PAYOUT_AMOUNT = 100
+MAX_PAYOUT_AMOUNT = 100_000
+LARGE_PAYOUT_THRESHOLD = 5000
+
+
+class InsufficientCreatorBalanceError(Exception):
+    """Raised when creator available balance is less than requested payout amount."""
+    pass
+
+
+class InvalidPayoutAmountError(ValueError):
+    """Raised when requested payout amount is out of valid bounds."""
+    pass
+
+
+class PayoutNotFoundError(Exception):
+    """Raised when payout request is not found."""
+    pass
+
+
+class InvalidPayoutStateError(Exception):
+    """Raised when payout request is in invalid status for the requested transition."""
+    pass
+
+
+class PayoutProvider(Protocol):
+    """Pluggable creator payout provider protocol (e.g. Stripe Connect, PayPal, Noop)."""
+
+    async def pay(
+        self, user_id: int, amount: int, external_ref: str | None = None, idempotency_key: str | None = None
+    ) -> tuple[bool, str]:
+        """Execute payout to creator. Returns (success, provider_ref)."""
+        ...
+
+
+class NoopPayoutProvider:
+    """Deterministic no-op provider for development and testing."""
+
+    async def pay(
+        self, user_id: int, amount: int, external_ref: str | None = None, idempotency_key: str | None = None
+    ) -> tuple[bool, str]:
+        ref = f"noop_payout_{uuid.uuid4().hex[:12]}"
+        logger.info(
+            f"[NoopPayoutProvider] Simulated payout of {amount} CR to user {user_id} (ref={ref})"
+        )
+        return True, ref
+
+
+default_payout_provider: PayoutProvider = NoopPayoutProvider()
+
+
+class PayoutService:
+    def __init__(self, provider: PayoutProvider | None = None):
+        self.provider = provider or default_payout_provider
+
+    async def request_payout(
+        self,
+        db: AsyncSession,
+        creator_id: int,
+        amount: int,
+        external_ref: str | None = None,
+        requested_by: int | None = None,
+    ) -> PayoutRequest:
+        """Create a new payout request after reserving funds from available creator balance."""
+        if amount < MIN_PAYOUT_AMOUNT:
+            raise InvalidPayoutAmountError(
+                f"Minimum payout amount is {MIN_PAYOUT_AMOUNT} Buffalo Chips"
+            )
+        if amount > MAX_PAYOUT_AMOUNT:
+            raise InvalidPayoutAmountError(
+                f"Maximum payout amount is {MAX_PAYOUT_AMOUNT} Buffalo Chips"
+            )
+
+        requester = requested_by if requested_by is not None else creator_id
+
+        # Lock creator balance row
+        cb = await PurchaseService.get_or_create_creator_balance(db, creator_id, for_update=True)
+        if cb.available < amount:
+            raise InsufficientCreatorBalanceError(
+                f"Insufficient available balance: {cb.available} Buffalo Chips available, {amount} Buffalo Chips requested"
+            )
+
+        # Reserve funds: move from available to pending
+        cb.available -= amount
+        cb.pending += amount
+        cb.updated_at = datetime.now(timezone.utc)
+
+        payout = PayoutRequest(
+            creator_id=creator_id,
+            amount=amount,
+            status=PayoutStatus.pending,
+            external_ref=external_ref,
+            requested_by=requester,
+        )
+        db.add(payout)
+        await db.commit()
+        await db.refresh(payout)
+        return payout
+
+    async def approve_and_pay(
+        self,
+        db: AsyncSession,
+        payout_id: int,
+        reviewer_id: int,
+        provider: PayoutProvider | None = None,
+    ) -> PayoutRequest:
+        """Admin approves and executes payout via provider."""
+        stmt = select(PayoutRequest).where(PayoutRequest.id == payout_id).with_for_update()
+        res = await db.execute(stmt)
+        payout = res.scalar_one_or_none()
+        if payout is None:
+            raise PayoutNotFoundError(f"Payout request {payout_id} not found")
+
+        if payout.status != PayoutStatus.pending:
+            raise InvalidPayoutStateError(
+                f"Cannot approve payout in status {payout.status.value}"
+            )
+
+        active_provider = provider or self.provider
+        success, provider_ref = await active_provider.pay(
+            user_id=payout.creator_id,
+            amount=payout.amount,
+            external_ref=payout.external_ref,
+            idempotency_key=f"payout-{payout.id}",
+        )
+
+        if not success:
+            raise RuntimeError("Payout provider rejected transaction")
+
+        now = datetime.now(timezone.utc)
+        cb = await PurchaseService.get_or_create_creator_balance(db, payout.creator_id, for_update=True)
+        cb.pending = max(0, cb.pending - payout.amount)
+        cb.updated_at = now
+
+        payout.status = PayoutStatus.paid
+        payout.provider_ref = provider_ref
+        payout.reviewed_by = reviewer_id
+        payout.reviewed_at = now
+
+        # Record immutable ledger audit row
+        wallet = await WalletService.get_or_create_wallet(db, payout.creator_id, for_update=True)
+        tx = Transaction(
+            wallet_id=wallet.id,
+            type=TransactionType.payout,
+            amount=-payout.amount,
+            balance_after=wallet.balance,
+            reference_type="payout_request",
+            reference_id=str(payout.id),
+            idempotency_key=f"payout-audit-{payout.id}",
+            metadata_json={
+                "provider_ref": provider_ref,
+                "reviewed_by": reviewer_id,
+                "external_ref": payout.external_ref,
+            },
+        )
+        db.add(tx)
+
+        await db.commit()
+        await db.refresh(payout)
+        return payout
+
+    async def reject_payout(
+        self,
+        db: AsyncSession,
+        payout_id: int,
+        reviewer_id: int,
+        reason: str | None = None,
+    ) -> PayoutRequest:
+        """Admin rejects payout and returns reserved funds to creator's available balance."""
+        stmt = select(PayoutRequest).where(PayoutRequest.id == payout_id).with_for_update()
+        res = await db.execute(stmt)
+        payout = res.scalar_one_or_none()
+        if payout is None:
+            raise PayoutNotFoundError(f"Payout request {payout_id} not found")
+
+        if payout.status != PayoutStatus.pending:
+            raise InvalidPayoutStateError(
+                f"Cannot reject payout in status {payout.status.value}"
+            )
+
+        now = datetime.now(timezone.utc)
+        cb = await PurchaseService.get_or_create_creator_balance(db, payout.creator_id, for_update=True)
+        cb.pending = max(0, cb.pending - payout.amount)
+        cb.available += payout.amount
+        cb.updated_at = now
+
+        payout.status = PayoutStatus.rejected
+        payout.reviewed_by = reviewer_id
+        payout.reviewed_at = now
+
+        await db.commit()
+        await db.refresh(payout)
+        return payout
+
+
+payout_service = PayoutService()

backend/app/services/presence.py

@@ -109,6 +109,11 @@ class PresenceStore:
         client = await self._ensure_client()
         await client.set(self._heartbeat_key(user_id), "1", ex=self._heartbeat_ttl)
 
+    async def clear_heartbeat(self, user_id: int) -> None:
+        """Clear heartbeat for *user_id* to mark them offline immediately."""
+        client = await self._ensure_client()
+        await client.delete(self._heartbeat_key(user_id))
+
     # ------------------------------------------------------------------
     # Online checks
     # ------------------------------------------------------------------

backend/app/services/purchase.py

@@ -0,0 +1,323 @@
+"""Marketplace purchase service: atomic escrow, fee split, item granting, refunds.
+
+docs/planning/economy.md US-4 (task bc90d3f481b4).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+import math
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.marketplace import (
+    CatalogItem,
+    CreatorBalance,
+    ListingStatus,
+    MarketplaceListing,
+    Purchase,
+    PurchaseStatus,
+)
+from app.models.wallet import TransactionType
+from app.services.wallet import InsufficientFundsError, WalletService
+
+
+MARKETPLACE_FEE_RATE = 0.30  # 30% platform fee
+DEFAULT_ESCROW_HOLD_HOURS = 72
+
+
+class ListingNotFoundError(Exception):
+    """Raised when the specified listing does not exist."""
+    pass
+
+
+class ListingNotAvailableError(Exception):
+    """Raised when the listing is not in active status."""
+    pass
+
+
+class SelfPurchaseError(Exception):
+    """Raised when a seller attempts to buy their own listing."""
+    pass
+
+
+class PurchaseNotFoundError(Exception):
+    """Raised when the specified purchase does not exist."""
+    pass
+
+
+class InvalidEscrowStateError(Exception):
+    """Raised when an operation cannot be performed on the current escrow state."""
+    pass
+
+
+class MatureContentRestrictedError(Exception):
+    """Raised when an unverified minor attempts to purchase mature content."""
+    pass
+
+
+def is_item_mature(item: CatalogItem) -> bool:
+    """Check whether a catalog item carries mature flags or is marked mature."""
+    if not item.metadata_json or not isinstance(item.metadata_json, dict):
+        return False
+    if item.metadata_json.get("is_mature") or item.metadata_json.get("mature"):
+        return True
+    flags = item.metadata_json.get("content_flags", [])
+    if isinstance(flags, list):
+        for f in flags:
+            if isinstance(f, dict) and f.get("mature"):
+                return True
+            if isinstance(f, str) and any(
+                m in f for m in ("gore", "sexual", "gambling", "hate", "explicit")
+            ):
+                return True
+    return False
+
+
+class PurchaseService:
+    @staticmethod
+    def compute_fee_split(price: int, fee_rate: float = MARKETPLACE_FEE_RATE) -> tuple[int, int]:
+        """Compute platform fee and seller net amount.
+
+        Returns (platform_fee, seller_net).
+        """
+        platform_fee = math.floor(price * fee_rate)
+        seller_net = price - platform_fee
+        return platform_fee, seller_net
+
+    @classmethod
+    async def get_or_create_creator_balance(
+        cls, db: AsyncSession, user_id: int, for_update: bool = False
+    ) -> CreatorBalance:
+        """Fetch or lazily create a creator balance row for user_id."""
+        stmt = select(CreatorBalance).where(CreatorBalance.user_id == user_id)
+        if for_update:
+            stmt = stmt.with_for_update()
+        result = await db.execute(stmt)
+        cb = result.scalar_one_or_none()
+        if cb is not None:
+            return cb
+
+        new_cb = CreatorBalance(
+            user_id=user_id,
+            available=0,
+            pending=0,
+            lifetime_earned=0,
+        )
+        db.add(new_cb)
+        await db.flush()
+        return new_cb
+
+    @classmethod
+    async def purchase_listing(
+        cls,
+        db: AsyncSession,
+        buyer_id: int,
+        listing_id: int,
+        buyer_is_adult: bool = True,
+        idempotency_key: str | None = None,
+        escrow_hours: int = DEFAULT_ESCROW_HOLD_HOURS,
+    ) -> tuple[Purchase, CatalogItem]:
+        """Perform atomic purchase of a marketplace listing.
+
+        Debits buyer, holds escrow, grants item to buyer, records purchase,
+        and updates creator pending balance.
+        """
+        # 1. Lock and validate listing
+        stmt_listing = (
+            select(MarketplaceListing)
+            .where(MarketplaceListing.id == listing_id)
+            .with_for_update()
+        )
+        res_listing = await db.execute(stmt_listing)
+        listing = res_listing.scalar_one_or_none()
+        if listing is None:
+            raise ListingNotFoundError(f"Listing {listing_id} not found")
+
+        if listing.status != ListingStatus.active:
+            raise ListingNotAvailableError(f"Listing {listing_id} is not active ({listing.status.value})")
+
+        if listing.seller_id == buyer_id:
+            raise SelfPurchaseError("Cannot purchase your own listing")
+
+        # 2. Fetch catalog item
+        catalog_item = await db.get(CatalogItem, listing.catalog_item_id)
+        if catalog_item is None:
+            raise ListingNotFoundError("Catalog item referenced by listing does not exist")
+
+        if is_item_mature(catalog_item) and not buyer_is_adult:
+            raise MatureContentRestrictedError(
+                "MATURE_CONTENT_REQUIRES_VERIFICATION: Buyer must be 18+ to purchase mature items"
+            )
+
+        # 3. Calculate fee split
+        price = listing.price
+        platform_fee, seller_net = cls.compute_fee_split(price)
+
+        # 4. Debit buyer wallet atomically (commit=False)
+        tx_idemp = f"mkt-purchase-{idempotency_key}" if idempotency_key else None
+        await WalletService.debit(
+            db=db,
+            user_id=buyer_id,
+            amount=price,
+            tx_type=TransactionType.marketplace_purchase,
+            reference_type="marketplace_listing",
+            reference_id=str(listing.id),
+            idempotency_key=tx_idemp,
+            commit=False,
+        )
+
+        # 5. Grant catalog item to buyer
+        granted_item = CatalogItem(
+            owner_id=buyer_id,
+            asset_id=catalog_item.asset_id,
+            item_type=catalog_item.item_type,
+            name=catalog_item.name,
+            description=catalog_item.description,
+            metadata_json=catalog_item.metadata_json,
+        )
+        db.add(granted_item)
+
+        # 6. Mark listing as sold
+        now = datetime.now(timezone.utc)
+        listing.status = ListingStatus.sold
+        listing.updated_at = now
+
+        # 7. Create purchase record
+        hold_until = now + timedelta(hours=escrow_hours)
+        purchase = Purchase(
+            listing_id=listing.id,
+            buyer_id=buyer_id,
+            seller_id=listing.seller_id,
+            price=price,
+            platform_fee=platform_fee,
+            seller_net=seller_net,
+            status=PurchaseStatus.pending_escrow,
+            escrow_hold_until=hold_until,
+        )
+        db.add(purchase)
+
+        # 8. Update seller's CreatorBalance (pending escrow)
+        creator_balance = await cls.get_or_create_creator_balance(
+            db, listing.seller_id, for_update=True
+        )
+        creator_balance.pending += seller_net
+        creator_balance.updated_at = now
+
+        # Commit everything atomically
+        await db.commit()
+        await db.refresh(purchase)
+        await db.refresh(granted_item)
+
+        return purchase, granted_item
+
+    @classmethod
+    async def release_escrow(cls, db: AsyncSession, purchase_id: int) -> Purchase:
+        """Release funds from escrow to seller's available creator balance."""
+        stmt = select(Purchase).where(Purchase.id == purchase_id).with_for_update()
+        res = await db.execute(stmt)
+        purchase = res.scalar_one_or_none()
+        if purchase is None:
+            raise PurchaseNotFoundError(f"Purchase {purchase_id} not found")
+
+        if purchase.status != PurchaseStatus.pending_escrow:
+            raise InvalidEscrowStateError(
+                f"Cannot release escrow in status {purchase.status.value}"
+            )
+
+        cb = await cls.get_or_create_creator_balance(db, purchase.seller_id, for_update=True)
+        cb.pending = max(0, cb.pending - purchase.seller_net)
+        cb.available += purchase.seller_net
+        cb.lifetime_earned += purchase.seller_net
+        cb.updated_at = datetime.now(timezone.utc)
+
+        purchase.status = PurchaseStatus.completed
+        await db.commit()
+        await db.refresh(purchase)
+        return purchase
+
+    @classmethod
+    async def refund_purchase(
+        cls, db: AsyncSession, purchase_id: int, reason: str | None = None
+    ) -> Purchase:
+        """Refund a purchase during the escrow hold window."""
+        stmt = select(Purchase).where(Purchase.id == purchase_id).with_for_update()
+        res = await db.execute(stmt)
+        purchase = res.scalar_one_or_none()
+        if purchase is None:
+            raise PurchaseNotFoundError(f"Purchase {purchase_id} not found")
+
+        if purchase.status != PurchaseStatus.pending_escrow:
+            raise InvalidEscrowStateError(
+                f"Cannot refund purchase in status {purchase.status.value}"
+            )
+
+        # Reverse seller's pending creator balance
+        cb = await cls.get_or_create_creator_balance(db, purchase.seller_id, for_update=True)
+        cb.pending = max(0, cb.pending - purchase.seller_net)
+        cb.updated_at = datetime.now(timezone.utc)
+
+        # Credit buyer wallet
+        await WalletService.credit(
+            db=db,
+            user_id=purchase.buyer_id,
+            amount=purchase.price,
+            tx_type=TransactionType.refund,
+            reference_type="purchase_refund",
+            reference_id=str(purchase.id),
+            metadata={"reason": reason} if reason else None,
+            commit=False,
+        )
+
+        purchase.status = PurchaseStatus.refunded
+        await db.commit()
+        await db.refresh(purchase)
+        return purchase
+
+    @classmethod
+    async def reverse_purchase(
+        cls,
+        db: AsyncSession,
+        purchase_id: int,
+        moderator_id: int,
+        reason: str,
+    ) -> Purchase:
+        """Moderator/admin audited reversal of purchase."""
+        stmt = select(Purchase).where(Purchase.id == purchase_id).with_for_update()
+        res = await db.execute(stmt)
+        purchase = res.scalar_one_or_none()
+        if purchase is None:
+            raise PurchaseNotFoundError(f"Purchase {purchase_id} not found")
+
+        if purchase.status in (PurchaseStatus.reversed, PurchaseStatus.refunded):
+            raise InvalidEscrowStateError(f"Purchase already {purchase.status.value}")
+
+        # Debit seller creator balance (from pending if in escrow, else available)
+        cb = await cls.get_or_create_creator_balance(db, purchase.seller_id, for_update=True)
+        if purchase.status == PurchaseStatus.pending_escrow:
+            cb.pending = max(0, cb.pending - purchase.seller_net)
+        else:
+            cb.available = max(0, cb.available - purchase.seller_net)
+        cb.updated_at = datetime.now(timezone.utc)
+
+        # Refund buyer wallet
+        await WalletService.credit(
+            db=db,
+            user_id=purchase.buyer_id,
+            amount=purchase.price,
+            tx_type=TransactionType.refund,
+            reference_type="purchase_reversal",
+            reference_id=str(purchase.id),
+            metadata={"moderator_id": moderator_id, "reason": reason},
+            commit=False,
+        )
+
+        purchase.status = PurchaseStatus.reversed
+        await db.commit()
+        await db.refresh(purchase)
+        return purchase
+
+
+purchase_service = PurchaseService()

backend/app/services/trending.py

@@ -0,0 +1,34 @@
+"""Trending recommendation heuristic service.
+
+docs/planning/discovery.md (task 33706f401ad9).
+"""
+
+from sqlalchemy import case, func, select, text
+from app.models.world_visit import WorldVisit
+
+
+def get_trending_subquery(days: int = 7):
+    """Build a subquery that computes a decay-weighted trending score per world_id.
+
+    Decay weights:
+    - Visited within 24 hours: weight 3.0
+    - Visited within 3 days: weight 2.0
+    - Visited within 7 days: weight 1.0
+    """
+    trending_weight = case(
+        (WorldVisit.visited_at >= func.now() - text("interval '1 day'"), 3.0),
+        (WorldVisit.visited_at >= func.now() - text("interval '3 days'"), 2.0),
+        else_=1.0,
+    )
+
+    interval_str = f"interval '{days} days'"
+    subq = (
+        select(
+            WorldVisit.world_id.label("trending_world_id"),
+            func.coalesce(func.sum(trending_weight), 0.0).label("trending_score"),
+        )
+        .where(WorldVisit.visited_at >= func.now() - text(interval_str))
+        .group_by(WorldVisit.world_id)
+        .subquery("trending_scores")
+    )
+    return subq

backend/app/services/wallet.py

@@ -0,0 +1,208 @@
+"""Wallet service: atomic credit/debit, row locking, and idempotency.
+
+docs/planning/economy.md US-1 (task 909e3e9a59af).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.wallet import Transaction, TransactionType, Wallet
+
+logger = logging.getLogger(__name__)
+
+
+class InsufficientFundsError(Exception):
+    """Raised when a debit would cause wallet balance to drop below zero."""
+    pass
+
+
+class InvalidAmountError(ValueError):
+    """Raised when an invalid (non-positive) amount is supplied."""
+    pass
+
+
+class WalletService:
+    @staticmethod
+    async def get_or_create_wallet(
+        db: AsyncSession, user_id: int, for_update: bool = False
+    ) -> Wallet:
+        """Fetch existing wallet or lazily create one for user_id.
+
+        If for_update is True, locks the row with SELECT ... FOR UPDATE.
+        """
+        stmt = select(Wallet).where(Wallet.user_id == user_id)
+        if for_update:
+            stmt = stmt.with_for_update()
+
+        result = await db.execute(stmt)
+        wallet = result.scalar_one_or_none()
+        if wallet is not None:
+            return wallet
+
+        # If not found and not in update mode, create lazily
+        try:
+            new_wallet = Wallet(user_id=user_id, balance=0)
+            db.add(new_wallet)
+            await db.commit()
+            await db.refresh(new_wallet)
+
+            if for_update:
+                stmt_locked = select(Wallet).where(Wallet.id == new_wallet.id).with_for_update()
+                res = await db.execute(stmt_locked)
+                return res.scalar_one()
+
+            return new_wallet
+        except IntegrityError:
+            # Concurrent insert collision -- rollback and fetch the existing one
+            await db.rollback()
+            stmt = select(Wallet).where(Wallet.user_id == user_id)
+            if for_update:
+                stmt = stmt.with_for_update()
+            result = await db.execute(stmt)
+            return result.scalar_one()
+
+    @classmethod
+    async def credit(
+        cls,
+        db: AsyncSession,
+        user_id: int,
+        amount: int,
+        tx_type: TransactionType | str,
+        reference_type: str | None = None,
+        reference_id: str | None = None,
+        idempotency_key: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        commit: bool = True,
+    ) -> tuple[Wallet, Transaction]:
+        """Credit a user's wallet atomically with row locking.
+
+        If an idempotency_key is provided and already exists, returns the original
+        outcome without double-crediting.
+        """
+        if amount <= 0:
+            raise InvalidAmountError("Credit amount must be strictly positive")
+
+        if isinstance(tx_type, str):
+            tx_type = TransactionType(tx_type)
+
+        # Check idempotency first
+        if idempotency_key:
+            stmt = select(Transaction).where(Transaction.idempotency_key == idempotency_key)
+            existing_tx = (await db.execute(stmt)).scalar_one_or_none()
+            if existing_tx is not None:
+                wallet = await cls.get_or_create_wallet(db, user_id, for_update=False)
+                return wallet, existing_tx
+
+        # Lock wallet row
+        wallet = await cls.get_or_create_wallet(db, user_id, for_update=True)
+        wallet.balance += amount
+
+        tx = Transaction(
+            wallet_id=wallet.id,
+            type=tx_type,
+            amount=amount,
+            balance_after=wallet.balance,
+            reference_type=reference_type,
+            reference_id=reference_id,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata,
+        )
+        db.add(tx)
+        if commit:
+            await db.commit()
+            await db.refresh(wallet)
+            await db.refresh(tx)
+        else:
+            await db.flush()
+        return wallet, tx
+
+    @classmethod
+    async def debit(
+        cls,
+        db: AsyncSession,
+        user_id: int,
+        amount: int,
+        tx_type: TransactionType | str,
+        reference_type: str | None = None,
+        reference_id: str | None = None,
+        idempotency_key: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        commit: bool = True,
+    ) -> tuple[Wallet, Transaction]:
+        """Debit a user's wallet atomically with row locking and balance check.
+
+        Raises InsufficientFundsError if wallet balance < amount.
+        If idempotency_key is provided and already exists, returns the original
+        outcome without double-debiting.
+        """
+        if amount <= 0:
+            raise InvalidAmountError("Debit amount must be strictly positive")
+
+        if isinstance(tx_type, str):
+            tx_type = TransactionType(tx_type)
+
+        # Check idempotency first
+        if idempotency_key:
+            stmt = select(Transaction).where(Transaction.idempotency_key == idempotency_key)
+            existing_tx = (await db.execute(stmt)).scalar_one_or_none()
+            if existing_tx is not None:
+                wallet = await cls.get_or_create_wallet(db, user_id, for_update=False)
+                return wallet, existing_tx
+
+        # Lock wallet row
+        wallet = await cls.get_or_create_wallet(db, user_id, for_update=True)
+        cur_balance = wallet.balance
+        if cur_balance < amount:
+            if commit:
+                await db.rollback()
+            raise InsufficientFundsError(
+                f"Insufficient funds: available {cur_balance}, required {amount}"
+            )
+
+        wallet.balance -= amount
+
+        tx = Transaction(
+            wallet_id=wallet.id,
+            type=tx_type,
+            amount=-amount,
+            balance_after=wallet.balance,
+            reference_type=reference_type,
+            reference_id=reference_id,
+            idempotency_key=idempotency_key,
+            metadata_json=metadata,
+        )
+        db.add(tx)
+        if commit:
+            await db.commit()
+            await db.refresh(wallet)
+            await db.refresh(tx)
+        else:
+            await db.flush()
+        return wallet, tx
+
+    @staticmethod
+    async def get_transactions(
+        db: AsyncSession, wallet_id: int, limit: int = 50, offset: int = 0
+    ) -> tuple[list[Transaction], int]:
+        """Fetch paged transactions for a wallet ordered newest-first, plus total count."""
+        count_stmt = select(func.count()).select_from(Transaction).where(Transaction.wallet_id == wallet_id)
+        total = (await db.execute(count_stmt)).scalar() or 0
+
+        stmt = (
+            select(Transaction)
+            .where(Transaction.wallet_id == wallet_id)
+            .order_by(Transaction.created_at.desc(), Transaction.id.desc())
+            .offset(offset)
+            .limit(limit)
+        )
+        res = await db.execute(stmt)
+        return list(res.scalars().all()), total
+
+
+wallet_service = WalletService()

backend/tests/conftest.py

@@ -45,6 +45,8 @@ TEST_TABLES = (
     # `worlds` the way world_rooms/world_chunks would be. List all three
     # explicitly rather than rely on cascade for some of them.
     "world_chunk_revisions", "world_chunks", "world_rooms",
+    # Discovery (app/models/world_visit.py) -- FK worlds.id with ON DELETE CASCADE
+    "world_visits",
     "worlds",
     # Social graph (app/models/social.py) -- all three FK users with
     # ON DELETE CASCADE, but list explicitly for clarity/consistency.
@@ -58,6 +60,9 @@ TEST_TABLES = (
     # (not CASCADE, deliberately -- see groups.py), so it wouldn't be reached
     # by cascading a truncate of users; list it explicitly for clarity too.
     "group_members", "groups",
+    # Economy (app/models/wallet.py, app/models/marketplace.py)
+    "payout_requests", "purchases", "marketplace_listings", "catalog_items", "creator_balances",
+    "transactions", "wallets",
     "sessions", "refresh_tokens", "users",
 )
 

backend/tests/test_asset_collections.py

@@ -0,0 +1,235 @@
+"""Integration tests for Poly Model Asset Collections and ZIP batch extraction.
+
+Covers tasks dfe19da5a448 and 840bb736d098.
+"""
+
+import io
+import zipfile
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+def _register(client: TestClient, username: str) -> tuple[int, dict[str, str]]:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["access_token"]
+    headers = {"Authorization": f"Bearer {token}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return me.json()["id"], headers
+
+
+def test_collection_crud_and_permissions():
+    client = TestClient(app)
+    uid1, h1 = _register(client, "col_user_1")
+    uid2, h2 = _register(client, "col_user_2")
+
+    # 1. Create collection as user 1
+    resp = client.post(
+        "/api/assets/collections/",
+        headers=h1,
+        json={
+            "title": "Low Poly Fantasy Props",
+            "description": "Swords, shields, and potions",
+            "theme": "fantasy",
+            "is_public": True,
+            "tags": "fantasy,lowpoly,weapons",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    col_data = resp.json()
+    assert col_data["title"] == "Low Poly Fantasy Props"
+    assert col_data["theme"] == "fantasy"
+    assert col_data["owner_id"] == uid1
+    col_id = col_data["id"]
+
+    # 2. List collections with theme filter
+    resp = client.get("/api/assets/collections/", headers=h2, params={"theme": "fantasy"})
+    assert resp.status_code == 200
+    cols = resp.json()
+    assert any(c["id"] == col_id for c in cols)
+
+    # 3. List with non-matching theme filter
+    resp = client.get("/api/assets/collections/", headers=h2, params={"theme": "scifi"})
+    assert resp.status_code == 200
+    cols = resp.json()
+    assert not any(c["id"] == col_id for c in cols)
+
+    # 4. Search filter
+    resp = client.get("/api/assets/collections/", headers=h2, params={"search": "shields"})
+    assert resp.status_code == 200
+    assert any(c["id"] == col_id for c in resp.json())
+
+    # 5. User 2 views public collection
+    resp = client.get(f"/api/assets/collections/{col_id}", headers=h2)
+    assert resp.status_code == 200
+    assert resp.json()["id"] == col_id
+
+    # 6. User 2 cannot modify User 1's collection
+    resp = client.patch(
+        f"/api/assets/collections/{col_id}",
+        headers=h2,
+        json={"title": "Hacked Title"},
+    )
+    assert resp.status_code == 403
+
+    # 7. User 2 cannot delete User 1's collection
+    resp = client.delete(f"/api/assets/collections/{col_id}", headers=h2)
+    assert resp.status_code == 403
+
+    # 8. User 1 updates collection to private
+    resp = client.patch(
+        f"/api/assets/collections/{col_id}",
+        headers=h1,
+        json={"is_public": False, "theme": "medieval"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["is_public"] is False
+    assert resp.json()["theme"] == "medieval"
+
+    # 9. User 2 can no longer view private collection
+    resp = client.get(f"/api/assets/collections/{col_id}", headers=h2)
+    assert resp.status_code == 403
+
+    # 10. User 1 deletes collection
+    resp = client.delete(f"/api/assets/collections/{col_id}", headers=h1)
+    assert resp.status_code == 204
+
+    # 11. Verify gone
+    resp = client.get(f"/api/assets/collections/{col_id}", headers=h1)
+    assert resp.status_code == 404
+
+
+def test_collection_item_association_and_ordering():
+    client = TestClient(app)
+    uid, h = _register(client, "col_items_user")
+
+    # Create 2 assets
+    a1_resp = client.post(
+        "/api/assets/",
+        headers=h,
+        json={"name": "Wooden Crate", "asset_type": "model_3d"},
+    )
+    assert a1_resp.status_code == 201, a1_resp.text
+    asset1_id = a1_resp.json()["id"]
+
+    a2_resp = client.post(
+        "/api/assets/",
+        headers=h,
+        json={"name": "Iron Barrel", "asset_type": "model_3d"},
+    )
+    assert a2_resp.status_code == 201, a2_resp.text
+    asset2_id = a2_resp.json()["id"]
+
+    # Create collection
+    col_resp = client.post(
+        "/api/assets/collections/",
+        headers=h,
+        json={"title": "Industrial Pack", "theme": "industrial"},
+    )
+    assert col_resp.status_code == 201
+    col_id = col_resp.json()["id"]
+
+    # Add items with explicit ordering
+    add1 = client.post(
+        f"/api/assets/collections/{col_id}/items",
+        headers=h,
+        json={"asset_id": asset1_id, "sort_order": 0},
+    )
+    assert add1.status_code == 200
+    assert add1.json()["items_count"] == 1
+    assert add1.json()["items"][0]["id"] == asset1_id
+
+    add2 = client.post(
+        f"/api/assets/collections/{col_id}/items",
+        headers=h,
+        json={"asset_id": asset2_id, "sort_order": 1},
+    )
+    assert add2.status_code == 200
+    assert add2.json()["items_count"] == 2
+    assert add2.json()["items"][1]["id"] == asset2_id
+
+    # Remove item 1
+    rem = client.delete(
+        f"/api/assets/collections/{col_id}/items/{asset1_id}",
+        headers=h,
+    )
+    assert rem.status_code == 200
+    assert rem.json()["items_count"] == 1
+    assert rem.json()["items"][0]["id"] == asset2_id
+
+
+def test_collection_zip_upload_and_extraction():
+    client = TestClient(app)
+    uid, h = _register(client, "col_zip_user")
+
+    # 1. Build a valid in-memory zip file with mock GLB content
+    zip_buf = io.BytesIO()
+    with zipfile.ZipFile(zip_buf, "w") as zf:
+        zf.writestr("stone_pillar.glb", b"glTFmockheader_binary_stone_pillar")
+        zf.writestr("wooden_arch.glb", b"glTFmockheader_binary_wooden_arch")
+        zf.writestr("temple_roof.gltf", b'{"asset": {"version": "2.0"}}')
+        zf.writestr("readme.txt", b"Instructions for this pack")
+    zip_bytes = zip_buf.getvalue()
+
+    # Upload zip pack
+    resp = client.post(
+        "/api/assets/collections/upload-zip",
+        headers=h,
+        data={
+            "title": "Ancient Ruins Pack",
+            "theme": "historical",
+            "description": "Set of stone pillars and wooden arches",
+            "is_public": "true",
+            "tags": "ruins,ancient,stone",
+        },
+        files={"file": ("ruins_pack.zip", zip_bytes, "application/zip")},
+    )
+    assert resp.status_code == 201, resp.text
+    data = resp.json()
+    assert data["title"] == "Ancient Ruins Pack"
+    assert data["theme"] == "historical"
+    assert data["items_count"] == 3
+    names = [i["name"] for i in data["items"]]
+    assert "Stone Pillar" in names
+    assert "Wooden Arch" in names
+    assert "Temple Roof" in names
+
+
+def test_collection_zip_error_handling():
+    client = TestClient(app)
+    uid, h = _register(client, "col_badzip_user")
+
+    # 1. Invalid zip payload
+    resp = client.post(
+        "/api/assets/collections/upload-zip",
+        headers=h,
+        data={"title": "Corrupt Pack", "theme": "general"},
+        files={"file": ("bad.zip", b"not-a-valid-zip-file", "application/zip")},
+    )
+    assert resp.status_code == 400
+    assert "Invalid ZIP archive" in resp.json()["detail"]
+
+    # 2. Valid zip but no 3D models
+    zip_buf = io.BytesIO()
+    with zipfile.ZipFile(zip_buf, "w") as zf:
+        zf.writestr("notes.txt", b"Hello world")
+        zf.writestr("image.png", b"fake image bytes")
+    resp = client.post(
+        "/api/assets/collections/upload-zip",
+        headers=h,
+        data={"title": "No Models Pack", "theme": "general"},
+        files={"file": ("empty.zip", zip_buf.getvalue(), "application/zip")},
+    )
+    assert resp.status_code == 400
+    assert "no valid 3D models" in resp.json()["detail"]

backend/tests/test_auth_age_gate.py

@@ -40,9 +40,10 @@ class TestRegisterRequestDob:
                               date_of_birth="1990-01-01")
         assert req.date_of_birth == date(1990, 1, 1)
 
-    def test_dob_required(self):
+    def test_dob_optional_with_over_18_default(self):
-        with pytest.raises(Exception):
+        req = RegisterRequest(username="u", email="u@example.com", password="p")
-            RegisterRequest(username="u", email="u@example.com", password="p")
+        assert req.date_of_birth is None
+        assert req.over_18 is True
 
     def test_bad_dob_string_rejected(self):
         with pytest.raises(Exception):
@@ -50,6 +51,7 @@ class TestRegisterRequestDob:
                             date_of_birth="not-a-date")
 
 
+
 class TestRegisterAgeGate:
     """End-to-end: the /register endpoint computes age from the DOB."""
 

backend/tests/test_auth_endpoints.py

@@ -149,18 +149,34 @@ class TestRegister:
         assert resp.status_code == 409
         assert "Email already registered" in resp.json()["detail"]
 
-    def test_register_missing_dob(self):
+    def test_register_without_dob_succeeds(self):
-        """Missing the required date_of_birth field returns 422."""
+        """DOB is no longer collected; registration with 18+ TOS agreement succeeds."""
         client = TestClient(app)
         resp = client.post(
             "/api/auth/register",
             json={
-                "username": "user",
+                "username": "adult_user_nodob",
-                "email": "user@example.com",
+                "email": "adult_user_nodob@example.com",
                 "password": "secret123",
+                "over_18": True,
             },
         )
-        assert resp.status_code == 422
+        assert resp.status_code == 201
+
+    def test_register_not_over_18_rejected(self):
+        """Declining 18+ confirmation returns 403."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "underage_declined",
+                "email": "underage_declined@example.com",
+                "password": "secret123",
+                "over_18": False,
+            },
+        )
+        assert resp.status_code == 403
+
 
 
 # ---------------------------------------------------------------------------

backend/tests/test_chat_reports.py

@@ -0,0 +1,243 @@
+"""Integration tests for message reporting and moderation queue:
+- POST /api/chat/messages/{message_id}/report
+- GET  /api/moderation/reports
+- POST /api/moderation/reports/{id}/resolve
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+def _register(client: TestClient, username: str) -> dict:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["access_token"]
+    headers = {"Authorization": f"Bearer {token}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return {"headers": headers, "id": me.json()["id"], "username": username}
+
+
+def _send_dm(client: TestClient, sender: dict, recipient: dict, text: str = "hello") -> int:
+    resp = client.post(
+        f"/api/chat/dm/{recipient['id']}/messages",
+        headers=sender["headers"],
+        json={"body": text},
+    )
+    assert resp.status_code == 201, resp.text
+    return resp.json()["id"]
+
+
+class TestReportMessage:
+    def test_report_message_success(self):
+        client = TestClient(app)
+        alice = _register(client, "rep_alice1")
+        bob = _register(client, "rep_bob1")
+
+        msg_id = _send_dm(client, alice, bob, "spam message")
+
+        resp = client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=bob["headers"],
+            json={"reason": "Contains spam", "category": "spam"},
+        )
+        assert resp.status_code == 201, resp.text
+        data = resp.json()
+        assert data["message_id"] == msg_id
+        assert data["reporter_id"] == bob["id"]
+        assert data["status"] == "open"
+        assert "[spam] Contains spam" in data["reason"]
+
+    def test_duplicate_report_rejected(self):
+        client = TestClient(app)
+        alice = _register(client, "rep_alice2")
+        bob = _register(client, "rep_bob2")
+
+        msg_id = _send_dm(client, alice, bob, "bad message")
+
+        resp1 = client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=bob["headers"],
+            json={"reason": "offensive"},
+        )
+        assert resp1.status_code == 201
+
+        resp2 = client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=bob["headers"],
+            json={"reason": "offensive again"},
+        )
+        assert resp2.status_code == 409
+
+    def test_report_nonexistent_message_404(self):
+        client = TestClient(app)
+        bob = _register(client, "rep_bob3")
+
+        resp = client.post(
+            "/api/chat/messages/999999/report",
+            headers=bob["headers"],
+            json={"reason": "ghost"},
+        )
+        assert resp.status_code == 404
+
+    def test_report_requires_auth(self):
+        client = TestClient(app)
+        resp = client.post("/api/chat/messages/1/report", json={"reason": "no auth"})
+        assert resp.status_code == 401
+
+
+class TestModerationQueue:
+    def test_non_moderator_cannot_access_queue(self):
+        client = TestClient(app)
+        regular_user = _register(client, "rep_regular1")
+
+        resp = client.get("/api/moderation/reports", headers=regular_user["headers"])
+        assert resp.status_code == 403
+
+    def test_moderator_can_list_reports(self):
+        client = TestClient(app)
+        alice = _register(client, "rep_alice4")
+        bob = _register(client, "rep_bob4")
+        admin = _register(client, "admin_list")
+
+        msg_id = _send_dm(client, alice, bob, "something to report")
+        client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=bob["headers"],
+            json={"reason": "needs review"},
+        )
+
+        resp = client.get("/api/moderation/reports", headers=admin["headers"])
+        assert resp.status_code == 200, resp.text
+        reports = resp.json()
+        assert len(reports) >= 1
+        assert any(r["message_id"] == msg_id for r in reports)
+
+    def test_moderator_resolve_dismiss(self):
+        client = TestClient(app)
+        alice = _register(client, "rep_alice5")
+        bob = _register(client, "rep_bob5")
+        admin = _register(client, "admin_dismiss")
+
+        msg_id = _send_dm(client, alice, bob, "benign message")
+        rep_resp = client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=bob["headers"],
+            json={"reason": "false alarm"},
+        )
+        report_id = rep_resp.json()["id"]
+
+        resolve_resp = client.post(
+            f"/api/moderation/reports/{report_id}/resolve",
+            headers=admin["headers"],
+            json={"action": "dismiss", "notes": "No violation found"},
+        )
+        assert resolve_resp.status_code == 200, resolve_resp.text
+        data = resolve_resp.json()
+        assert data["report_id"] == report_id
+        assert data["status"] == "dismissed"
+        assert data["action_taken"] == "dismiss"
+        assert data["moderator_id"] == admin["id"]
+
+    def test_moderator_resolve_remove(self):
+        client = TestClient(app)
+        alice = _register(client, "rep_alice6")
+        bob = _register(client, "rep_bob6")
+        admin = _register(client, "admin_remove")
+
+        msg_id = _send_dm(client, alice, bob, "offensive content")
+        rep_resp = client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=bob["headers"],
+            json={"reason": "hate speech"},
+        )
+        report_id = rep_resp.json()["id"]
+
+        resolve_resp = client.post(
+            f"/api/moderation/reports/{report_id}/resolve",
+            headers=admin["headers"],
+            json={"action": "remove", "notes": "Content removed"},
+        )
+        assert resolve_resp.status_code == 200
+        assert resolve_resp.json()["status"] == "resolved"
+
+        # The message is removed from conversation history
+        hist = client.get(f"/api/chat/dm/{bob['id']}/messages", headers=alice["headers"])
+        assert all(m["id"] != msg_id for m in hist.json()["messages"])
+
+    def test_moderator_resolve_ban(self):
+        client = TestClient(app)
+        bad_user = _register(client, "bad_actor")
+        victim = _register(client, "rep_victim")
+        admin_auth = _register(client, "admin_ban")
+
+        msg_id = _send_dm(client, bad_user, victim, "terrible violation")
+        rep_resp = client.post(
+            f"/api/chat/messages/{msg_id}/report",
+            headers=victim["headers"],
+            json={"reason": "malicious user"},
+        )
+        report_id = rep_resp.json()["id"]
+
+        resolve_resp = client.post(
+            f"/api/moderation/reports/{report_id}/resolve",
+            headers=admin_auth["headers"],
+            json={"action": "ban", "notes": "Banned malicious user"},
+        )
+        assert resolve_resp.status_code == 200
+
+        # Attempting to use bad_user's token fails with 403 inactive account
+        bad_me = client.get("/api/users/me", headers=bad_user["headers"])
+        assert bad_me.status_code == 403
+
+    def test_submit_world_and_user_moderation_report(self):
+        """Test submitting general moderation reports for worlds and users."""
+        client = TestClient(app)
+        reporter = _register(client, "gen_reporter")
+        admin = _register(client, "admin_gen_mod")
+
+        # Report a world
+        world_rep = client.post(
+            "/api/moderation/reports",
+            headers=reporter["headers"],
+            json={
+                "target_type": "world",
+                "target_id": 42,
+                "reason": "Violates world guidelines",
+                "category": "world_rules",
+            },
+        )
+        assert world_rep.status_code == 201, world_rep.text
+        assert "[WORLD:42]" in world_rep.json()["reason"]
+
+        # Report a user
+        user_rep = client.post(
+            "/api/moderation/reports",
+            headers=reporter["headers"],
+            json={
+                "target_type": "user",
+                "target_id": 99,
+                "reason": "Harassment in world",
+                "category": "harassment",
+            },
+        )
+        assert user_rep.status_code == 201, user_rep.text
+        assert "[USER:99]" in user_rep.json()["reason"]
+
+        # Admin lists open reports and sees both
+        rep_list = client.get("/api/moderation/reports", headers=admin["headers"])
+        assert rep_list.status_code == 200
+        reasons = [r["reason"] for r in rep_list.json()]
+        assert any("[WORLD:42]" in r for r in reasons)
+        assert any("[USER:99]" in r for r in reasons)
+

backend/tests/test_chat_world.py

@@ -0,0 +1,246 @@
+"""Integration tests for in-experience world/room chat:
+- POST /api/chat/world/{world_id}/messages
+- GET  /api/chat/world/{world_id}/messages
+- POST /api/chat/room/{room_id}/messages
+- GET  /api/chat/room/{room_id}/messages
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+def _register(client: TestClient, username: str) -> dict:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["access_token"]
+    headers = {"Authorization": f"Bearer {token}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return {"headers": headers, "id": me.json()["id"], "username": username}
+
+
+def _make_world(client: TestClient, headers: dict, visibility: str = "public") -> int:
+    r = client.post("/api/worlds/", headers=headers, json={"name": "TestWorld", "visibility": visibility})
+    assert r.status_code == 201, r.text
+    return r.json()["id"]
+
+
+def _make_friends(client: TestClient, user_a: dict, user_b: dict) -> None:
+    req = client.post("/api/friends/requests", json={"user_id": user_b["id"]}, headers=user_a["headers"])
+    assert req.status_code == 201, req.text
+    req_id = req.json()["id"]
+    acc = client.post(f"/api/friends/requests/{req_id}/accept", headers=user_b["headers"])
+    assert acc.status_code == 200, acc.text
+
+
+class TestWorldChat:
+    def test_send_and_get_world_message(self):
+        client = TestClient(app)
+        alice = _register(client, "wch_alice1")
+        bob = _register(client, "wch_bob1")
+
+        world_id = _make_world(client, alice["headers"], visibility="public")
+
+        # Bob posts to Alice's public world
+        post_resp = client.post(
+            f"/api/chat/world/{world_id}/messages",
+            headers=bob["headers"],
+            json={"body": "Hello world from Bob!"},
+        )
+        assert post_resp.status_code == 201, post_resp.text
+        msg_data = post_resp.json()
+        assert msg_data["world_id"] == world_id
+        assert msg_data["room_id"] is None
+        assert msg_data["sender_id"] == bob["id"]
+        assert msg_data["body"] == "Hello world from Bob!"
+        assert msg_data["filtered"] is False
+        assert msg_data["author"]["username"] == "wch_bob1"
+        assert msg_data["author"]["id"] == bob["id"]
+
+        # Alice gets world chat history
+        get_resp = client.get(
+            f"/api/chat/world/{world_id}/messages",
+            headers=alice["headers"],
+        )
+        assert get_resp.status_code == 200, get_resp.text
+        history = get_resp.json()
+        assert len(history["messages"]) == 1
+        assert history["messages"][0]["id"] == msg_data["id"]
+        assert history["messages"][0]["author"]["username"] == "wch_bob1"
+
+    def test_room_scoped_messages(self):
+        client = TestClient(app)
+        alice = _register(client, "wch_alice2")
+        world_id = _make_world(client, alice["headers"])
+
+        # Fetch auto-created main room
+        rooms_resp = client.get(f"/api/worlds/{world_id}/rooms", headers=alice["headers"])
+        assert rooms_resp.status_code == 200, rooms_resp.text
+        rooms = rooms_resp.json()
+        assert len(rooms) >= 1
+        room_id = rooms[0]["id"]
+
+        # Post directly via room endpoint
+        post_room = client.post(
+            f"/api/chat/room/{room_id}/messages",
+            headers=alice["headers"],
+            json={"body": "Message in room"},
+        )
+        assert post_room.status_code == 201, post_room.text
+        msg_data = post_room.json()
+        assert msg_data["world_id"] == world_id
+        assert msg_data["room_id"] == room_id
+        assert msg_data["body"] == "Message in room"
+
+        # Get room history
+        get_room = client.get(
+            f"/api/chat/room/{room_id}/messages",
+            headers=alice["headers"],
+        )
+        assert get_room.status_code == 200, get_room.text
+        messages = get_room.json()["messages"]
+        assert len(messages) == 1
+        assert messages[0]["id"] == msg_data["id"]
+
+        # Also visible when querying world history with room_id filter
+        get_world_room = client.get(
+            f"/api/chat/world/{world_id}/messages?room_id={room_id}",
+            headers=alice["headers"],
+        )
+        assert get_world_room.status_code == 200, get_world_room.text
+        assert len(get_world_room.json()["messages"]) == 1
+
+    def test_visibility_access_control(self):
+        client = TestClient(app)
+        alice = _register(client, "wch_alice3")
+        bob = _register(client, "wch_bob3")
+        charlie = _register(client, "wch_charlie3")
+
+        # Private world: only Alice
+        priv_world_id = _make_world(client, alice["headers"], visibility="private")
+
+        # Bob cannot send or read
+        bob_send = client.post(
+            f"/api/chat/world/{priv_world_id}/messages",
+            headers=bob["headers"],
+            json={"body": "Trying to trespass"},
+        )
+        assert bob_send.status_code == 403, bob_send.text
+
+        bob_read = client.get(
+            f"/api/chat/world/{priv_world_id}/messages",
+            headers=bob["headers"],
+        )
+        assert bob_read.status_code == 403, bob_read.text
+
+        # Alice (owner) can send and read
+        alice_send = client.post(
+            f"/api/chat/world/{priv_world_id}/messages",
+            headers=alice["headers"],
+            json={"body": "My private sanctum"},
+        )
+        assert alice_send.status_code == 201, alice_send.text
+
+        # Friends-only world
+        fr_world_id = _make_world(client, alice["headers"], visibility="friends_only")
+        _make_friends(client, alice, bob)
+
+        # Bob (friend) can post
+        bob_fr_send = client.post(
+            f"/api/chat/world/{fr_world_id}/messages",
+            headers=bob["headers"],
+            json={"body": "Hello friend!"},
+        )
+        assert bob_fr_send.status_code == 201, bob_fr_send.text
+
+        # Charlie (not friend) cannot post or read
+        charlie_send = client.post(
+            f"/api/chat/world/{fr_world_id}/messages",
+            headers=charlie["headers"],
+            json={"body": "Can I join?"},
+        )
+        assert charlie_send.status_code == 403, charlie_send.text
+
+        charlie_read = client.get(
+            f"/api/chat/world/{fr_world_id}/messages",
+            headers=charlie["headers"],
+        )
+        assert charlie_read.status_code == 403, charlie_read.text
+
+    def test_not_found_validation(self):
+        client = TestClient(app)
+        alice = _register(client, "wch_alice4")
+
+        # Non-existent world
+        res = client.post(
+            "/api/chat/world/999999/messages",
+            headers=alice["headers"],
+            json={"body": "Ghost world"},
+        )
+        assert res.status_code == 404, res.text
+
+        # Non-existent room
+        world_id = _make_world(client, alice["headers"])
+        res2 = client.post(
+            f"/api/chat/world/{world_id}/messages",
+            headers=alice["headers"],
+            json={"body": "Ghost room", "room_id": 999999},
+        )
+        assert res2.status_code == 404, res2.text
+
+    def test_text_filtering_in_world_chat(self):
+        client = TestClient(app)
+        alice = _register(client, "wch_alice5")
+        world_id = _make_world(client, alice["headers"])
+
+        # Default filter redacts forbidden words
+        res = client.post(
+            f"/api/chat/world/{world_id}/messages",
+            headers=alice["headers"],
+            json={"body": "you are a bastard"},
+        )
+        assert res.status_code == 201, res.text
+        data = res.json()
+        assert data["filtered"] is True
+        assert "bastard" not in data["body"]
+        assert "*" in data["body"]
+
+    def test_pagination_and_next_cursor(self):
+        client = TestClient(app)
+        alice = _register(client, "wch_alice6")
+        world_id = _make_world(client, alice["headers"])
+
+        for i in range(5):
+            r = client.post(
+                f"/api/chat/world/{world_id}/messages",
+                headers=alice["headers"],
+                json={"body": f"Msg {i}"},
+            )
+            assert r.status_code == 201
+
+        page1 = client.get(
+            f"/api/chat/world/{world_id}/messages?limit=2",
+            headers=alice["headers"],
+        ).json()
+        assert len(page1["messages"]) == 2
+        assert page1["next_cursor"] is not None
+        assert page1["messages"][0]["body"] == "Msg 4"
+        assert page1["messages"][1]["body"] == "Msg 3"
+
+        page2 = client.get(
+            f"/api/chat/world/{world_id}/messages?limit=2&before={page1['next_cursor']}",
+            headers=alice["headers"],
+        ).json()
+        assert len(page2["messages"]) == 2
+        assert page2["messages"][0]["body"] == "Msg 2"
+        assert page2["messages"][1]["body"] == "Msg 1"

backend/tests/test_discovery_browse_api.py

@@ -0,0 +1,188 @@
+"""API tests for discovery browse & search endpoints.
+
+docs/planning/discovery.md (task 300da1dcddf3).
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+
+def _register(client: TestClient, username: str) -> tuple[int, dict[str, str]]:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["access_token"]
+    headers = {"Authorization": f"Bearer {token}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return me.json()["id"], headers
+
+
+@pytest.mark.asyncio
+async def test_discovery_public_worlds_only_and_fields():
+    client = TestClient(app)
+    uid, headers = _register(client, "creator_browse_1")
+
+    # Create public world
+    pub_resp = client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={
+            "name": "Fantasy Kingdom",
+            "description": "A magical realm",
+            "visibility": "public",
+            "category": "RPG",
+            "tags": ["magic", "dragons"],
+        },
+    )
+    assert pub_resp.status_code == 201, pub_resp.text
+    pub_id = pub_resp.json()["id"]
+
+    # Create private world
+    priv_resp = client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={
+            "name": "Secret Base",
+            "description": "Classified",
+            "visibility": "private",
+            "category": "RPG",
+            "tags": ["secret"],
+        },
+    )
+    assert priv_resp.status_code == 201, priv_resp.text
+
+    # 1. Anonymous listing: only public world is returned
+    anon_resp = client.get("/api/discovery/worlds")
+    assert anon_resp.status_code == 200, anon_resp.text
+    data = anon_resp.json()
+    assert data["total"] >= 1
+    items = data["items"]
+    ids = [w["id"] for w in items]
+    assert pub_id in ids
+    assert priv_resp.json()["id"] not in ids
+
+    # Check fields of returned item
+    pub_item = next(w for w in items if w["id"] == pub_id)
+    assert pub_item["name"] == "Fantasy Kingdom"
+    assert pub_item["description"] == "A magical realm"
+    assert pub_item["category"] == "RPG"
+    assert "magic" in pub_item["tags"]
+    assert pub_item["play_count"] == 0
+    assert pub_item["owner"]["id"] == uid
+    assert pub_item["owner"]["username"] == "creator_browse_1"
+
+    # 2. Authenticated caller also does NOT see private worlds in discovery
+    auth_resp = client.get("/api/discovery/worlds", headers=headers)
+    assert auth_resp.status_code == 200
+    auth_ids = [w["id"] for w in auth_resp.json()["items"]]
+    assert priv_resp.json()["id"] not in auth_ids
+
+
+@pytest.mark.asyncio
+async def test_discovery_filtering_and_categories():
+    client = TestClient(app)
+    uid, headers = _register(client, "creator_filter_2")
+
+    # Create distinct worlds
+    client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={"name": "Cyber Arena", "visibility": "public", "category": "Action", "tags": ["pvp", "fps"]},
+    )
+    client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={"name": "Peaceful Meadow", "visibility": "public", "category": "Social", "tags": ["relax", "hangout"]},
+    )
+    client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={"name": "Cyber Hangout", "visibility": "public", "category": "Social", "tags": ["cyberpunk", "chat"]},
+    )
+
+    # Search by q
+    res_q = client.get("/api/discovery/worlds?q=cyber")
+    assert res_q.status_code == 200
+    names = [w["name"] for w in res_q.json()["items"]]
+    assert "Cyber Arena" in names
+    assert "Cyber Hangout" in names
+    assert "Peaceful Meadow" not in names
+
+    # Filter by category (case-insensitive)
+    res_cat = client.get("/api/discovery/worlds?category=action")
+    assert res_cat.status_code == 200
+    names = [w["name"] for w in res_cat.json()["items"]]
+    assert "Cyber Arena" in names
+    assert "Peaceful Meadow" not in names
+
+    # Filter by tags (overlap)
+    res_tags = client.get("/api/discovery/worlds?tags=relax,pvp")
+    assert res_tags.status_code == 200
+    names = [w["name"] for w in res_tags.json()["items"]]
+    assert "Peaceful Meadow" in names
+    assert "Cyber Arena" in names
+    assert "Cyber Hangout" not in names
+
+    # Get distinct categories
+    res_cats = client.get("/api/discovery/categories")
+    assert res_cats.status_code == 200
+    cats = res_cats.json()
+    assert "Action" in cats
+    assert "Social" in cats
+
+
+@pytest.mark.asyncio
+async def test_discovery_sorting_and_pagination():
+    client = TestClient(app)
+    uid, headers = _register(client, "creator_sort_3")
+
+    w1 = client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={"name": "Sort World 1", "visibility": "public"},
+    ).json()
+    w2 = client.post(
+        "/api/worlds/",
+        headers=headers,
+        json={"name": "Sort World 2", "visibility": "public"},
+    ).json()
+
+    # Record visits on w1 so play_count = 1
+    v_res = client.post(f"/api/discovery/worlds/{w1['id']}/visit")
+    assert v_res.status_code == 200
+
+    # Sort by most_played
+    res_mp = client.get("/api/discovery/worlds?sort=most_played")
+    assert res_mp.status_code == 200
+    items = res_mp.json()["items"]
+    # w1 should come before w2
+    idx_w1 = next(i for i, w in enumerate(items) if w["id"] == w1["id"])
+    idx_w2 = next(i for i, w in enumerate(items) if w["id"] == w2["id"])
+    assert idx_w1 < idx_w2
+
+    # Sort by newest (default)
+    res_new = client.get("/api/discovery/worlds?sort=newest")
+    assert res_new.status_code == 200
+    items_new = res_new.json()["items"]
+    idx_w1_n = next(i for i, w in enumerate(items_new) if w["id"] == w1["id"])
+    idx_w2_n = next(i for i, w in enumerate(items_new) if w["id"] == w2["id"])
+    # w2 was created after w1, so w2 is newer
+    assert idx_w2_n < idx_w1_n
+
+    # Pagination: limit 1, skip 0
+    p1 = client.get("/api/discovery/worlds?limit=1&skip=0")
+    assert p1.status_code == 200
+    assert len(p1.json()["items"]) == 1
+    assert p1.json()["total"] >= 2
+    assert p1.json()["skip"] == 0
+    assert p1.json()["limit"] == 1

backend/tests/test_discovery_models.py

@@ -0,0 +1,149 @@
+"""Model-level integration tests for Discovery metadata and WorldVisit.
+
+docs/planning/discovery.md (task b377353b8167).
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.orm import selectinload
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.models.user import User
+from app.models.world import World, WorldVisibility
+from app.models.world_visit import WorldVisit
+
+
+def _register(client: TestClient, username: str) -> int:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    headers = {"Authorization": f"Bearer {resp.json()['access_token']}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return me.json()["id"]
+
+
+def _session_factory():
+    engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    return engine, async_sessionmaker(engine, expire_on_commit=False)
+
+
+@pytest.mark.asyncio
+async def test_world_discovery_metadata_and_visits():
+    client = TestClient(app)
+    user_id = _register(client, "discoverer_1")
+    visitor_id = _register(client, "visitor_1")
+
+    engine, sf = _session_factory()
+    try:
+        async with sf() as session:
+            # 1. Create a world with discovery metadata
+            world = World(
+                name="Cyber Adventure",
+                description="An epic adventure world",
+                owner_id=user_id,
+                visibility=WorldVisibility.PUBLIC,
+                category="Adventure",
+                tags=["cyberpunk", "rpg", "quest"],
+            )
+            session.add(world)
+            await session.commit()
+            await session.refresh(world)
+
+            assert world.id is not None
+            assert world.category == "Adventure"
+            assert world.tags == ["cyberpunk", "rpg", "quest"]
+            assert world.play_count == 0
+            assert world.last_played_at is None
+
+            # 2. Add authenticated visit
+            visit1 = WorldVisit(
+                world_id=world.id,
+                user_id=visitor_id,
+            )
+            # 3. Add anonymous visit
+            visit2 = WorldVisit(
+                world_id=world.id,
+                user_id=None,
+                anonymous_token="anon_token_12345",
+            )
+            session.add_all([visit1, visit2])
+            await session.commit()
+
+            # Query world with visits
+            res = await session.execute(
+                select(World).where(World.id == world.id).options(selectinload(World.visits))
+            )
+            w = res.scalar_one()
+            assert len(w.visits) == 2
+            v_user = next(v for v in w.visits if v.user_id == visitor_id)
+            assert v_user.visited_at is not None
+            v_anon = next(v for v in w.visits if v.user_id is None)
+            assert v_anon.anonymous_token == "anon_token_12345"
+
+        # 4. Verify cascade delete on world
+        async with sf() as session:
+            res = await session.execute(select(World).where(World.id == world.id))
+            w = res.scalar_one()
+            await session.delete(w)
+            await session.commit()
+
+            # Visits should be gone
+            res_v = await session.execute(select(WorldVisit).where(WorldVisit.world_id == world.id))
+            assert len(res_v.scalars().all()) == 0
+
+    finally:
+        await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_user_delete_sets_null_on_world_visits():
+    client = TestClient(app)
+    owner_id = _register(client, "world_owner_2")
+    visitor_id = _register(client, "temp_visitor_2")
+
+    engine, sf = _session_factory()
+    try:
+        async with sf() as session:
+            world = World(
+                name="Chill Lobby",
+                owner_id=owner_id,
+                visibility=WorldVisibility.PUBLIC,
+                category="Social",
+                tags=["hangout"],
+            )
+            session.add(world)
+            await session.commit()
+            await session.refresh(world)
+
+            visit = WorldVisit(world_id=world.id, user_id=visitor_id)
+            session.add(visit)
+            await session.commit()
+            await session.refresh(visit)
+            visit_id = visit.id
+
+            # Delete visitor user
+            visitor_user = await session.get(User, visitor_id)
+            await session.delete(visitor_user)
+            await session.commit()
+
+            # In a new session, query from database to see ON DELETE SET NULL effect
+            async with sf() as session:
+                v = await session.get(WorldVisit, visit_id)
+                assert v is not None
+                assert v.user_id is None
+                assert v.world_id == world.id
+
+    finally:
+        await engine.dispose()