Add Friends & follow API router: requests, accept/decline, follow, block

Implements docs/planning/social.md US-1's API layer on top of the
merged Friendship/Follow/Block models (app/models/social.py):

- POST/GET /api/friends/requests, POST .../accept, POST .../decline
- DELETE /api/friends/{user_id} (unfriend)
- POST/DELETE /api/friends/{user_id}/follow, GET /api/friends/following
- POST/DELETE /api/friends/{user_id}/block, GET /api/friends/blocked
- GET /api/friends (mutual friends list)

All endpoints require JWT auth. Requests are scoped to caller (no
cross-account enumeration); duplicate/self requests are rejected
idempotently; block clears mutual friendship and follow in both directions.

Independently re-verified: 19/19 new unit/integration tests pass,
239/239 full backend test suite passes with zero regressions.

.gitea/workflows/checkpoint.yml

@@ -0,0 +1,39 @@
+name: checkpoint
+
+# Runs the full checkpoint suite (migrations, backend pytest, Godot smoke
+# tests, multiplayer, fresh-clone boot) on every push and PR.
+#
+# Runs on a `host`-label act_runner on the AGP box: Docker, ~/godot/godot,
+# and Python 3 are already there. Deliberately uses no JavaScript actions
+# (actions/checkout etc.) so the host needs no Node install -- checkout is a
+# plain git clone from the local Gitea. See docs/ci.md.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checkpoint:
+    runs-on: host
+    steps:
+      - name: Checkout
+        run: |
+          set -eu
+          rm -rf repo && mkdir repo && cd repo
+          git init -q
+          git remote add origin "http://x:${{ github.token }}@localhost:3000/${{ github.repository }}.git"
+          git fetch -q --depth 1 origin "${{ github.sha }}"
+          git checkout -q FETCH_HEAD
+
+      - name: Python env
+        working-directory: repo
+        run: |
+          set -eu
+          python3 -m venv .venv
+          .venv/bin/pip install --quiet --upgrade pip
+          .venv/bin/pip install --quiet -r backend/requirements.txt
+
+      - name: Checkpoint suite
+        working-directory: repo
+        run: .venv/bin/python scripts/run_checkpoint_tests.py --postgres-port 25690 --backend-port 18690

.gitignore

@@ -1,4 +1,4 @@
-# Godot editor cache / generated files
+# Godot 4 editor cache/import directory
 .godot/
 
 # Godot export artifacts
@@ -8,3 +8,7 @@ export/
 # OS
 .DS_Store
 Thumbs.db
+
+# Godot UID files (regenerated from path)
+*.uid
+assets/build_info.json

assets/avatars/accessory_belt_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://bm01jsuomi50i"
+path="res://.godot/imported/accessory_belt_01.glb-a2b6be72b4422067d290c84868489d2d.scn"
+
+[deps]
+
+source_file="res://assets/avatars/accessory_belt_01.glb"
+dest_files=["res://.godot/imported/accessory_belt_01.glb-a2b6be72b4422067d290c84868489d2d.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/accessory_necklace_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://dvou487niwnjt"
+path="res://.godot/imported/accessory_necklace_01.glb-75d713dbb1ff9579d6f0bf8b7ddde1e2.scn"
+
+[deps]
+
+source_file="res://assets/avatars/accessory_necklace_01.glb"
+dest_files=["res://.godot/imported/accessory_necklace_01.glb-75d713dbb1ff9579d6f0bf8b7ddde1e2.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/back_backpack_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://dknbtq33pssf4"
+path="res://.godot/imported/back_backpack_01.glb-d0ccc39aed8e86403d649c8d07008591.scn"
+
+[deps]
+
+source_file="res://assets/avatars/back_backpack_01.glb"
+dest_files=["res://.godot/imported/back_backpack_01.glb-d0ccc39aed8e86403d649c8d07008591.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/base_human_male_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://brfp6g6pcbbw7"
+path="res://.godot/imported/base_human_male_01.glb-c917b85c8f8ab5d1974812a6891f052f.scn"
+
+[deps]
+
+source_file="res://assets/avatars/base_human_male_01.glb"
+dest_files=["res://.godot/imported/base_human_male_01.glb-c917b85c8f8ab5d1974812a6891f052f.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/catalog.json

@@ -0,0 +1,115 @@
+{
+  "assets": {
+    "base_human_male_01": {
+      "type": "base_body",
+      "slot": "base_body",
+      "path": "res://assets/avatars/base_human_male_01.glb",
+      "version": "1.0.0",
+      "display_name": "Human Male Base"
+    },
+    "head_cyber_01": {
+      "type": "attachment",
+      "slot": "head",
+      "path": "res://assets/avatars/head_cyber_01.glb",
+      "version": "1.0.0",
+      "display_name": "Cyber Head",
+      "mount_bone": "Head"
+    },
+    "hair_mohawk_01": {
+      "type": "attachment",
+      "slot": "hair",
+      "path": "res://assets/avatars/hair_mohawk_01.glb",
+      "version": "1.0.0",
+      "display_name": "Mohawk",
+      "mount_bone": "HeadTop"
+    },
+    "hair_ponytail_01": {
+      "type": "attachment",
+      "slot": "hair",
+      "path": "res://assets/avatars/hair_ponytail_01.glb",
+      "version": "1.0.0",
+      "display_name": "Ponytail",
+      "mount_bone": "HeadTop"
+    },
+    "face_glasses_01": {
+      "type": "attachment",
+      "slot": "face",
+      "path": "res://assets/avatars/face_glasses_01.glb",
+      "version": "1.0.0",
+      "display_name": "Glasses",
+      "mount_bone": "Jaw"
+    },
+    "chest_bandit_01": {
+      "type": "attachment",
+      "slot": "chest",
+      "path": "res://assets/avatars/chest_bandit_01.glb",
+      "version": "1.0.0",
+      "display_name": "Bandit Shirt",
+      "mount_bone": "Chest"
+    },
+    "back_backpack_01": {
+      "type": "attachment",
+      "slot": "back",
+      "path": "res://assets/avatars/back_backpack_01.glb",
+      "version": "1.0.0",
+      "display_name": "Backpack",
+      "mount_bone": "Chest"
+    },
+    "pants_cargo_01": {
+      "type": "attachment",
+      "slot": "pants",
+      "path": "res://assets/avatars/pants_cargo_01.glb",
+      "version": "1.0.0",
+      "display_name": "Cargo Pants",
+      "mount_bone": "Hips"
+    },
+    "left_hand_glove_01": {
+      "type": "attachment",
+      "slot": "left_hand",
+      "path": "res://assets/avatars/left_hand_glove_01.glb",
+      "version": "1.0.0",
+      "display_name": "Left Glove",
+      "mount_bone": "LeftHand"
+    },
+    "right_hand_glove_01": {
+      "type": "attachment",
+      "slot": "right_hand",
+      "path": "res://assets/avatars/right_hand_glove_01.glb",
+      "version": "1.0.0",
+      "display_name": "Right Glove",
+      "mount_bone": "RightHand"
+    },
+    "left_foot_boot_01": {
+      "type": "attachment",
+      "slot": "left_foot",
+      "path": "res://assets/avatars/left_foot_boot_01.glb",
+      "version": "1.0.0",
+      "display_name": "Left Boot",
+      "mount_bone": "LeftFoot"
+    },
+    "right_foot_boot_01": {
+      "type": "attachment",
+      "slot": "right_foot",
+      "path": "res://assets/avatars/right_foot_boot_01.glb",
+      "version": "1.0.0",
+      "display_name": "Right Boot",
+      "mount_bone": "RightFoot"
+    },
+    "accessory_belt_01": {
+      "type": "attachment",
+      "slot": "accessory",
+      "path": "res://assets/avatars/accessory_belt_01.glb",
+      "version": "1.0.0",
+      "display_name": "Belt",
+      "mount_bone": "Root"
+    },
+    "accessory_necklace_01": {
+      "type": "attachment",
+      "slot": "accessory",
+      "path": "res://assets/avatars/accessory_necklace_01.glb",
+      "version": "1.0.0",
+      "display_name": "Necklace",
+      "mount_bone": "Root"
+    }
+  }
+}

assets/avatars/chest_bandit_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://bva2etlpa8act"
+path="res://.godot/imported/chest_bandit_01.glb-90867999feb79e02c469ef45d970f0e1.scn"
+
+[deps]
+
+source_file="res://assets/avatars/chest_bandit_01.glb"
+dest_files=["res://.godot/imported/chest_bandit_01.glb-90867999feb79e02c469ef45d970f0e1.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/face_glasses_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://ctwcxf552y325"
+path="res://.godot/imported/face_glasses_01.glb-fe06ebb12e6caf265dce06de37a74fc5.scn"
+
+[deps]
+
+source_file="res://assets/avatars/face_glasses_01.glb"
+dest_files=["res://.godot/imported/face_glasses_01.glb-fe06ebb12e6caf265dce06de37a74fc5.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/hair_mohawk_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://j4dc6l3l0j6f"
+path="res://.godot/imported/hair_mohawk_01.glb-f2a6883730b5d02facb56d1dbb0e371e.scn"
+
+[deps]
+
+source_file="res://assets/avatars/hair_mohawk_01.glb"
+dest_files=["res://.godot/imported/hair_mohawk_01.glb-f2a6883730b5d02facb56d1dbb0e371e.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/hair_ponytail_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://dp4vqp2trrank"
+path="res://.godot/imported/hair_ponytail_01.glb-cdf5913fc63278b1dd362cb640c2ecb4.scn"
+
+[deps]
+
+source_file="res://assets/avatars/hair_ponytail_01.glb"
+dest_files=["res://.godot/imported/hair_ponytail_01.glb-cdf5913fc63278b1dd362cb640c2ecb4.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/head_cyber_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://bkp35fnns36xb"
+path="res://.godot/imported/head_cyber_01.glb-8081a99d6b31c121d208dd2f9629df5c.scn"
+
+[deps]
+
+source_file="res://assets/avatars/head_cyber_01.glb"
+dest_files=["res://.godot/imported/head_cyber_01.glb-8081a99d6b31c121d208dd2f9629df5c.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_boot_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://bgfjpdu8kg0aj"
+path="res://.godot/imported/left_foot_boot_01.glb-cab36c9e44befe0a3ff50ee651f2ff67.scn"
+
+[deps]
+
+source_file="res://assets/avatars/left_foot_boot_01.glb"
+dest_files=["res://.godot/imported/left_foot_boot_01.glb-cab36c9e44befe0a3ff50ee651f2ff67.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_glove_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://dtq7tgio1iymd"
+path="res://.godot/imported/left_hand_glove_01.glb-4b237bea3299c6604547afa353a7b602.scn"
+
+[deps]
+
+source_file="res://assets/avatars/left_hand_glove_01.glb"
+dest_files=["res://.godot/imported/left_hand_glove_01.glb-4b237bea3299c6604547afa353a7b602.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/pants_cargo_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://yo204q1m6hs3"
+path="res://.godot/imported/pants_cargo_01.glb-00f3e3b72fd692344cbb8bfd2b8449f9.scn"
+
+[deps]
+
+source_file="res://assets/avatars/pants_cargo_01.glb"
+dest_files=["res://.godot/imported/pants_cargo_01.glb-00f3e3b72fd692344cbb8bfd2b8449f9.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_boot_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://30ij0eapm6ti"
+path="res://.godot/imported/right_foot_boot_01.glb-ffff27e561e5632596b7ba89fee5b5ea.scn"
+
+[deps]
+
+source_file="res://assets/avatars/right_foot_boot_01.glb"
+dest_files=["res://.godot/imported/right_foot_boot_01.glb-ffff27e561e5632596b7ba89fee5b5ea.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_glove_01.glb.import

@@ -0,0 +1,42 @@
+[remap]
+
+importer="scene"
+importer_version=1
+type="PackedScene"
+uid="uid://bcrtxtp47dv8h"
+path="res://.godot/imported/right_hand_glove_01.glb-a59875b630ac413350c3bdf6acc84bdf.scn"
+
+[deps]
+
+source_file="res://assets/avatars/right_hand_glove_01.glb"
+dest_files=["res://.godot/imported/right_hand_glove_01.glb-a59875b630ac413350c3bdf6acc84bdf.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

@@ -0,0 +1,40 @@
+{
+  "objects": {
+    "crate_small": {
+      "asset_id": "props/crate_small.glb",
+      "type": "prop",
+      "display_name": "Small Crate",
+      "category": "props"
+    },
+    "rock_01": {
+      "asset_id": "props/rock_01.glb",
+      "type": "prop",
+      "display_name": "Rock",
+      "category": "nature"
+    },
+    "tree_pine_01": {
+      "asset_id": "props/tree_pine_01.glb",
+      "type": "prop",
+      "display_name": "Pine Tree",
+      "category": "nature"
+    },
+    "lamp_post_01": {
+      "asset_id": "props/lamp_post_01.glb",
+      "type": "prop",
+      "display_name": "Lamp Post",
+      "category": "props"
+    },
+    "chest_01": {
+      "asset_id": "props/chest.glb",
+      "type": "interactable",
+      "display_name": "Treasure Chest",
+      "category": "interactables"
+    },
+    "spawn_point": {
+      "asset_id": "",
+      "type": "spawn_point",
+      "display_name": "Spawn Point",
+      "category": "gameplay"
+    }
+  }
+}

assets/scripting/behaviors/demo_chest.json

@@ -0,0 +1,17 @@
+{
+  "content_flags": {
+    "violence": "none",
+    "mature": false
+  },
+  "rules": [
+    {
+      "trigger": {"type": "on_interact"},
+      "conditions": [],
+      "actions": [
+        {"verb": "give_item", "item_id": "gold_coin", "count": 3},
+        {"verb": "play_sound", "sound_id": "chest_open"},
+        {"verb": "rotate", "target": "self", "degrees": 90, "axis": "y", "duration": 0.4}
+      ]
+    }
+  ]
+}

assets/scripting/spawn_catalog.json

@@ -0,0 +1,8 @@
+{
+  "templates": {
+    "small_crate": {
+      "asset_id": "props/crate_small.glb",
+      "display_name": "Small Crate"
+    }
+  }
+}

backend/.env.example

@@ -0,0 +1,23 @@
+# Database (async driver)
+DATABASE_URL=postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
+
+# Redis
+REDIS_URL=redis://localhost:6379/0
+
+# JWT / Auth
+ALGORITHM=RS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+REFRESH_TOKEN_EXPIRE_DAYS=30
+# Directory where the RSA keypair is loaded/generated at runtime.
+# Defaults to ~/.agp/keys (outside the repo). Keys are never committed to git.
+RSA_KEY_DIR=~/.agp/keys
+
+# App
+APP_NAME=AGP Backend
+APP_VERSION=0.1.0
+DEBUG=true
+CORS_ORIGINS=http://localhost:8080,http://localhost:3000
+
+# File uploads
+UPLOAD_DIR=uploads
+MAX_UPLOAD_SIZE_MB=100

backend/.gitignore

@@ -0,0 +1,4 @@
+.env
+__pycache__/
+*.pyc
+.venv/

backend/alembic.ini

@@ -0,0 +1,42 @@
+# Alembic configuration file.
+# Run: alembic upgrade head  (to apply migrations)
+# Run: alembic revision --autogenerate -m "description"  (to generate migration)
+
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+sqlalchemy.url = postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/alembic/env.py

@@ -0,0 +1,65 @@
+"""Alembic environment configuration."""
+
+import asyncio
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.config import settings
+from app.database import Base
+from app.models import user, session, world, asset, avatar_loadout, world_content  # noqa: F401
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here
+# for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = settings.DATABASE_URL
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations():
+    """Run migrations in 'online' mode with async engine."""
+    connectable = create_async_engine(settings.DATABASE_URL, echo=False)
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade database schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade database schema."""
+    ${downgrades if downgrades else "pass"}

backend/alembic/versions/0001_initial.py

@@ -0,0 +1,127 @@
+"""initial schema
+
+Revision ID: 0001_initial
+Revises:
+Create Date: 2024-01-01 00:00:00.000000
+"""
+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 = "0001_initial"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade database schema."""
+    # Create ENUM types
+    world_visibility = postgresql.ENUM(
+        "public", "private", "friends_only", name="world_visibility"
+    )
+    world_visibility.create(op.get_bind(), checkfirst=True)
+
+    asset_type = postgresql.ENUM(
+        "image", "audio", "video", "document", "model_3d", "other", name="asset_type"
+    )
+    asset_type.create(op.get_bind(), checkfirst=True)
+
+    # Create users table
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("username", sa.String(length=50), nullable=False),
+        sa.Column("email", sa.String(length=120), nullable=False),
+        sa.Column("hashed_password", sa.String(length=255), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
+    op.create_index(op.f("ix_users_id"), "users", ["id"], unique=False)
+    op.create_index(op.f("ix_users_username"), "users", ["username"], unique=True)
+
+    # Create sessions table
+    op.create_table(
+        "sessions",
+        sa.Column("id", sa.String(length=36), primary_key=True),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("token", sa.String(), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("is_active", sa.Boolean(), 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()),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+    )
+    op.create_index(op.f("ix_sessions_token"), "sessions", ["token"], unique=True)
+
+    # Create worlds table
+    op.create_table(
+        "worlds",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("owner_id", sa.Integer(), nullable=False),
+        sa.Column(
+            "visibility",
+            postgresql.ENUM(
+                "public", "private", "friends_only", name="world_visibility",
+                create_type=False,
+            ),
+            nullable=True,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
+    )
+    op.create_index(op.f("ix_worlds_id"), "worlds", ["id"], unique=False)
+
+    # Create assets table
+    op.create_table(
+        "assets",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "asset_type",
+            postgresql.ENUM(
+                "image", "audio", "video", "document", "model_3d", "other",
+                name="asset_type", create_type=False,
+            ),
+            nullable=False,
+        ),
+        sa.Column("file_path", sa.String(length=512), nullable=False),
+        sa.Column("file_size", sa.Integer(), nullable=True),
+        sa.Column("mime_type", sa.String(length=128), nullable=True),
+        sa.Column("metadata_json", sa.Text(), nullable=True),
+        sa.Column("world_id", sa.Integer(), nullable=True),
+        sa.Column("owner_id", sa.Integer(), nullable=False),
+        sa.Column("is_public", sa.Boolean(), nullable=False),
+        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()),
+        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
+        sa.ForeignKeyConstraint(["world_id"], ["worlds.id"]),
+    )
+    op.create_index(op.f("ix_assets_id"), "assets", ["id"], unique=False)
+
+
+def downgrade() -> None:
+    """Downgrade database schema."""
+    op.drop_index(op.f("ix_assets_id"), table_name="assets")
+    op.drop_table("assets")
+    op.drop_index(op.f("ix_worlds_id"), table_name="worlds")
+    op.drop_table("worlds")
+    op.drop_index(op.f("ix_sessions_token"), table_name="sessions")
+    op.drop_table("sessions")
+    op.drop_index(op.f("ix_users_username"), table_name="users")
+    op.drop_index(op.f("ix_users_id"), table_name="users")
+    op.drop_index(op.f("ix_users_email"), table_name="users")
+    op.drop_table("users")
+
+    # Drop ENUM types
+    postgresql.ENUM(name="asset_type").drop(op.get_bind(), checkfirst=True)
+    postgresql.ENUM(name="world_visibility").drop(op.get_bind(), checkfirst=True)

backend/alembic/versions/0002_add_date_of_birth_to_users.py

@@ -0,0 +1,30 @@
+"""add date_of_birth column to users table
+
+Revision ID: 0002_add_date_of_birth_to_users
+Revises: 0001_initial
+Create Date: 2025-01-01 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0002_add_date_of_birth_to_users"
+down_revision: Union[str, None] = "0001_initial"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add date_of_birth column to users table."""
+    op.add_column(
+        "users",
+        sa.Column("date_of_birth", sa.Date(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    """Remove date_of_birth column from users table."""
+    op.drop_column("users", "date_of_birth")

backend/alembic/versions/0003_add_refresh_tokens_table.py

@@ -0,0 +1,36 @@
+"""add refresh_tokens table
+
+Revision ID: 0003_add_refresh_tokens_table
+Revises: 0002_add_date_of_birth_to_users
+Create Date: 2025-07-25 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0003_add_refresh_tokens_table"
+down_revision: Union[str, None] = "0002_add_date_of_birth_to_users"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create the refresh_tokens table."""
+    op.create_table(
+        "refresh_tokens",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("token", sa.String(512), unique=True, index=True, nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.text("true"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    """Drop the refresh_tokens table."""
+    op.drop_table("refresh_tokens")

backend/alembic/versions/0004_add_avatar_loadouts_table.py

@@ -0,0 +1,39 @@
+"""add avatar_loadouts table
+
+Revision ID: 0004_add_avatar_loadouts_table
+Revises: 0003_add_refresh_tokens_table
+Create Date: 2026-09-05 00:00:00.000000
+
+"""
+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 = "0004_add_avatar_loadouts_table"
+down_revision: Union[str, None] = "0003_add_refresh_tokens_table"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create the avatar_loadouts table (one row per user)."""
+    op.create_table(
+        "avatar_loadouts",
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column("data", postgresql.JSONB(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    """Drop the avatar_loadouts table."""
+    op.drop_table("avatar_loadouts")

backend/alembic/versions/0005_add_world_content_tables.py

@@ -0,0 +1,120 @@
+"""add world_rooms, world_chunks, world_chunk_revisions tables
+
+Revision ID: 0005_add_world_content_tables
+Revises: 0004_add_avatar_loadouts_table
+Create Date: 2026-09-14 00:00:00.000000
+
+See docs/architecture/world_persistence_impl.md §4. Chunk content
+(rooms, chunk payloads, chunk revisions) lives in Postgres, purely
+additive to the existing ``worlds`` table.
+"""
+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 = "0005_add_world_content_tables"
+down_revision: Union[str, None] = "0004_add_avatar_loadouts_table"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "world_rooms",
+        sa.Column("id", sa.Integer(), primary_key=True, index=True),
+        sa.Column(
+            "world_id", sa.Integer(),
+            sa.ForeignKey("worlds.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("slug", sa.String(64), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column(
+            "grid", postgresql.JSONB(), nullable=False,
+            server_default='{"size": [32, 32, 1], "origin": [0, 0, 0]}',
+        ),
+        sa.Column("bounds", postgresql.JSONB(), nullable=True),
+        sa.Column("spawn", postgresql.JSONB(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True),
+            server_default=sa.func.now(), nullable=False,
+        ),
+        sa.UniqueConstraint("world_id", "slug", name="uq_world_rooms_world_slug"),
+    )
+    op.create_index("ix_world_rooms_world_id", "world_rooms", ["world_id"])
+
+    op.create_table(
+        "world_chunks",
+        sa.Column("id", sa.Integer(), primary_key=True, index=True),
+        sa.Column(
+            "world_id", sa.Integer(),
+            sa.ForeignKey("worlds.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "room_id", sa.Integer(),
+            sa.ForeignKey("world_rooms.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("chunk_key", sa.String(160), nullable=False, unique=True),
+        sa.Column("cx", sa.Integer(), nullable=False),
+        sa.Column("cy", sa.Integer(), nullable=False),
+        sa.Column("cz", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("format_version", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("payload", sa.LargeBinary(), nullable=False),
+        sa.Column("payload_len", sa.Integer(), nullable=False),
+        sa.Column("checksum", sa.String(64), nullable=False),
+        sa.Column("revision", sa.Integer(), nullable=False, server_default="1"),
+        sa.Column("content_flags", postgresql.JSONB(), nullable=False, server_default="{}"),
+        sa.Column("is_mature", sa.Boolean(), nullable=False, server_default="false"),
+        sa.Column(
+            "updated_by_id", sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True),
+            server_default=sa.func.now(), nullable=False,
+        ),
+        sa.UniqueConstraint("room_id", "cx", "cy", "cz", name="uq_world_chunks_coord"),
+    )
+    op.create_index("ix_world_chunks_world_id", "world_chunks", ["world_id"])
+    op.create_index("ix_world_chunks_room_id", "world_chunks", ["room_id"])
+    op.create_index(
+        "ix_world_chunks_room_coord", "world_chunks", ["room_id", "cx", "cy", "cz"],
+    )
+    op.create_index(
+        "ix_world_chunks_mature", "world_chunks", ["world_id"],
+        postgresql_where=sa.text("is_mature"),
+    )
+
+    op.create_table(
+        "world_chunk_revisions",
+        sa.Column("id", sa.Integer(), primary_key=True, index=True),
+        sa.Column("chunk_key", sa.String(160), nullable=False),
+        sa.Column("world_id", sa.Integer(), nullable=False),
+        sa.Column("revision", sa.Integer(), nullable=False),
+        sa.Column("action", sa.String(16), nullable=False),
+        sa.Column(
+            "actor_id", sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("checksum", sa.String(64), nullable=False),
+        sa.Column("payload", sa.LargeBinary(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_world_chunk_revisions_chunk_key", "world_chunk_revisions", ["chunk_key"])
+    op.create_index("ix_world_chunk_revisions_world_id", "world_chunk_revisions", ["world_id"])
+    op.create_index("ix_world_chunk_revisions_created_at", "world_chunk_revisions", ["created_at"])
+
+
+def downgrade() -> None:
+    op.drop_table("world_chunk_revisions")
+    op.drop_table("world_chunks")
+    op.drop_table("world_rooms")

backend/alembic/versions/0006_add_presence_columns.py

@@ -0,0 +1,33 @@
+"""add presence columns to users
+
+Revision ID: 0006_add_presence_columns
+Revises: 0005_add_world_content_tables
+Create Date: 2026-09-14 00:00:00.000000
+
+Ported forward from the orphaned agent/dd2a126b57a1 branch (originally
+2a9b9873244a_add_presence_columns.py, down_revision 0001_initial) and
+rebased onto the current migration head. See app/services/presence.py /
+app/routers/presence.py.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0006_add_presence_columns"
+down_revision: Union[str, None] = "0005_add_world_content_tables"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add last_seen_at and status_message columns to users table."""
+    op.add_column("users", sa.Column("last_seen_at", sa.DateTime(timezone=True), nullable=True))
+    op.add_column("users", sa.Column("status_message", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    """Remove presence columns from users table."""
+    op.drop_column("users", "status_message")
+    op.drop_column("users", "last_seen_at")

backend/alembic/versions/0007_add_social_graph_tables.py

@@ -0,0 +1,118 @@
+"""add social graph tables (friendships, follows, blocks)
+
+Revision ID: 0007_add_social_graph_tables
+Revises: 0006_add_presence_columns
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/social.md US-1 / app/models/social.py. Models + migration
+only -- the request/accept/block business logic lives in the sibling
+"Friends & follow API router" task.
+"""
+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 = "0007_add_social_graph_tables"
+down_revision: Union[str, None] = "0006_add_presence_columns"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    friendship_status = postgresql.ENUM(
+        "pending", "accepted", name="friendship_status"
+    )
+    friendship_status.create(op.get_bind(), checkfirst=True)
+
+    op.create_table(
+        "friendships",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "requester_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "addressee_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "status",
+            postgresql.ENUM(
+                "pending", "accepted", name="friendship_status", create_type=False
+            ),
+            nullable=False,
+            server_default="pending",
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint("requester_id", "addressee_id", name="uq_friendships_pair"),
+    )
+    op.create_index("ix_friendships_requester_id", "friendships", ["requester_id"])
+    op.create_index("ix_friendships_addressee_id", "friendships", ["addressee_id"])
+
+    op.create_table(
+        "follows",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "follower_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "followed_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint("follower_id", "followed_id", name="uq_follows_pair"),
+    )
+    op.create_index("ix_follows_follower_id", "follows", ["follower_id"])
+    op.create_index("ix_follows_followed_id", "follows", ["followed_id"])
+
+    op.create_table(
+        "blocks",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "blocker_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "blocked_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint("blocker_id", "blocked_id", name="uq_blocks_pair"),
+    )
+    op.create_index("ix_blocks_blocker_id", "blocks", ["blocker_id"])
+    op.create_index("ix_blocks_blocked_id", "blocks", ["blocked_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_blocks_blocked_id", table_name="blocks")
+    op.drop_index("ix_blocks_blocker_id", table_name="blocks")
+    op.drop_table("blocks")
+
+    op.drop_index("ix_follows_followed_id", table_name="follows")
+    op.drop_index("ix_follows_follower_id", table_name="follows")
+    op.drop_table("follows")
+
+    op.drop_index("ix_friendships_addressee_id", table_name="friendships")
+    op.drop_index("ix_friendships_requester_id", table_name="friendships")
+    op.drop_table("friendships")
+
+    postgresql.ENUM(name="friendship_status").drop(op.get_bind(), checkfirst=True)

backend/alembic/versions/0008_add_chat_tables.py

@@ -0,0 +1,178 @@
+"""add chat tables (conversations, messages, message_reports)
+
+Revision ID: 0008_add_chat_tables
+Revises: 0007_add_social_graph_tables
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/social.md US-4 / app/models/chat.py. Models + migration only
+-- text filtering, rate limiting, and send/report/moderation endpoints live
+in sibling tasks that depend on this one.
+"""
+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 = "0008_add_chat_tables"
+down_revision: Union[str, None] = "0007_add_social_graph_tables"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    message_report_status = postgresql.ENUM(
+        "open", "resolved", "dismissed", name="message_report_status"
+    )
+    message_report_status.create(op.get_bind(), checkfirst=True)
+
+    op.create_table(
+        "conversations",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_a_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_b_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint("user_a_id", "user_b_id", name="uq_conversations_pair"),
+        sa.CheckConstraint("user_a_id < user_b_id", name="ck_conversations_ordered_pair"),
+    )
+    op.create_index("ix_conversations_user_a_id", "conversations", ["user_a_id"])
+    op.create_index("ix_conversations_user_b_id", "conversations", ["user_b_id"])
+
+    op.create_table(
+        "conversation_participants",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "conversation_id",
+            sa.Integer(),
+            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint(
+            "conversation_id", "user_id", name="uq_conversation_participants_pair"
+        ),
+    )
+    op.create_index(
+        "ix_conversation_participants_conversation_id",
+        "conversation_participants",
+        ["conversation_id"],
+    )
+    op.create_index(
+        "ix_conversation_participants_user_id", "conversation_participants", ["user_id"]
+    )
+
+    op.create_table(
+        "messages",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "sender_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column(
+            "conversation_id",
+            sa.Integer(),
+            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+        sa.Column(
+            "world_id",
+            sa.Integer(),
+            sa.ForeignKey("worlds.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+        sa.Column(
+            "room_id",
+            sa.Integer(),
+            sa.ForeignKey("world_rooms.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+        sa.Column("body", sa.Text(), nullable=False),
+        sa.Column("filtered", sa.Boolean(), nullable=False, server_default="false"),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_messages_sender_id", "messages", ["sender_id"])
+    op.create_index(
+        "ix_messages_conversation_created", "messages", ["conversation_id", "created_at"]
+    )
+    op.create_index("ix_messages_world_created", "messages", ["world_id", "created_at"])
+
+    op.create_table(
+        "message_reports",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "message_id",
+            sa.Integer(),
+            sa.ForeignKey("messages.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column(
+            "reporter_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("reason", sa.Text(), nullable=False),
+        sa.Column(
+            "status",
+            postgresql.ENUM(
+                "open", "resolved", "dismissed", name="message_report_status", create_type=False
+            ),
+            nullable=False,
+            server_default="open",
+        ),
+        sa.Column(
+            "moderator_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_message_reports_message_id", "message_reports", ["message_id"])
+    op.create_index("ix_message_reports_reporter_id", "message_reports", ["reporter_id"])
+    op.create_index("ix_message_reports_moderator_id", "message_reports", ["moderator_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_message_reports_moderator_id", table_name="message_reports")
+    op.drop_index("ix_message_reports_reporter_id", table_name="message_reports")
+    op.drop_index("ix_message_reports_message_id", table_name="message_reports")
+    op.drop_table("message_reports")
+
+    op.drop_index("ix_messages_world_created", table_name="messages")
+    op.drop_index("ix_messages_conversation_created", table_name="messages")
+    op.drop_index("ix_messages_sender_id", table_name="messages")
+    op.drop_table("messages")
+
+    op.drop_index("ix_conversation_participants_user_id", table_name="conversation_participants")
+    op.drop_index(
+        "ix_conversation_participants_conversation_id", table_name="conversation_participants"
+    )
+    op.drop_table("conversation_participants")
+
+    op.drop_index("ix_conversations_user_b_id", table_name="conversations")
+    op.drop_index("ix_conversations_user_a_id", table_name="conversations")
+    op.drop_table("conversations")
+
+    postgresql.ENUM(name="message_report_status").drop(op.get_bind(), checkfirst=True)

backend/alembic/versions/0009_add_group_tables.py

@@ -0,0 +1,80 @@
+"""add group tables (groups, group_members)
+
+Revision ID: 0009_add_group_tables
+Revises: 0008_add_chat_tables
+Create Date: 2026-09-15 00:00:00.000000
+
+docs/planning/social.md US-5 / app/models/groups.py. Models + migration only
+-- create/join/leave, role authorization, and the group page endpoint live
+in a sibling task ("Groups API") that depends on this one.
+"""
+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 = "0009_add_group_tables"
+down_revision: Union[str, None] = "0008_add_chat_tables"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    group_role = postgresql.ENUM("owner", "admin", "member", name="group_role")
+    group_role.create(op.get_bind(), checkfirst=True)
+
+    op.create_table(
+        "groups",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(length=100), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "owner_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_groups_owner_id", "groups", ["owner_id"])
+
+    op.create_table(
+        "group_members",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "group_id",
+            sa.Integer(),
+            sa.ForeignKey("groups.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "role",
+            postgresql.ENUM("owner", "admin", "member", name="group_role", create_type=False),
+            nullable=False,
+            server_default="member",
+        ),
+        sa.Column("joined_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.UniqueConstraint("group_id", "user_id", name="uq_group_members_pair"),
+    )
+    op.create_index("ix_group_members_group_id", "group_members", ["group_id"])
+    op.create_index("ix_group_members_user_id", "group_members", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_group_members_user_id", table_name="group_members")
+    op.drop_index("ix_group_members_group_id", table_name="group_members")
+    op.drop_table("group_members")
+
+    op.drop_index("ix_groups_owner_id", table_name="groups")
+    op.drop_table("groups")
+
+    postgresql.ENUM(name="group_role").drop(op.get_bind(), checkfirst=True)

backend/app/config.py

@@ -0,0 +1,168 @@
+"""Application configuration via pydantic-settings."""
+
+from functools import lru_cache
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.rsa import (
+    RSAPrivateKey,
+    RSAPublicKey,
+    generate_private_key,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_pem_private_key,
+    load_pem_public_key,
+)
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def _load_or_generate_rsa_keys(key_dir: Path) -> tuple[bytes, bytes]:
+    """Load existing RSA keys or generate a new pair.
+
+    Keys are stored as PEM files in *key_dir*.  The directory is created
+    if it does not exist.  Files are named ``private.pem`` and
+    ``public.pem`` and are **not** committed to git.
+    """
+    private_path = key_dir / "private.pem"
+    public_path = key_dir / "public.pem"
+
+    if private_path.exists() and public_path.exists():
+        private_pem = private_path.read_bytes()
+        public_pem = public_path.read_bytes()
+    else:
+        # Generate a new 2048-bit RSA key pair
+        private_key = generate_private_key(public_exponent=65537, key_size=2048)
+        private_pem = private_key.private_bytes(
+            Encoding.PEM,
+            PrivateFormat.PKCS8,
+            NoEncryption(),
+        )
+        public_pem = private_key.public_key().public_bytes(
+            Encoding.PEM,
+            PublicFormat.SubjectPublicKeyInfo,
+        )
+        key_dir.mkdir(parents=True, exist_ok=True)
+        private_path.write_bytes(private_pem)
+        public_path.write_bytes(public_pem)
+
+    return private_pem, public_pem
+
+
+class Settings(BaseSettings):
+    # App
+    APP_NAME: str = "AGP Backend"
+    APP_VERSION: str = "0.1.0"
+    DEBUG: bool = True
+
+    # Database (async)
+    DATABASE_URL: str = "postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db"
+
+    # Redis
+    REDIS_URL: str = "redis://localhost:6379/0"
+
+    # JWT / Auth
+    ALGORITHM: str = "RS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 30
+
+    # RS256 key storage.  Defaults to a directory outside the repo so the
+    # generated keypair is never accidentally committed.
+    RSA_KEY_DIR: str = str(Path.home() / ".agp" / "keys")
+
+    # CORS
+    CORS_ORIGINS: str = "http://localhost:8080,http://localhost:3000"
+
+    # Per-IP auth rate limiting (app/rate_limit.py). Disabled by the
+    # checkpoint smoke suite, which runs every test from one client IP.
+    RATE_LIMIT_ENABLED: bool = True
+
+    # File uploads
+    UPLOAD_DIR: str = "uploads"
+    MAX_UPLOAD_SIZE_MB: int = 100
+    GLTF_MAX_FILE_SIZE_MB: int = 200
+
+    # ── Game-server orchestration ──────────────────────────────────────────
+    # The join flow (POST /api/worlds/{id}/join) ensures a headless Godot
+    # dedicated-server process exists for a world and returns its address.
+    # Disabled by default so nothing tries to spawn Godot in environments
+    # that don't have it (plain pytest, CI without the engine); the
+    # checkpoint/playtest launcher turns it on.
+    GAME_SERVERS_ENABLED: bool = False
+    # Path to the Godot 4 binary. "godot" resolves via PATH.
+    GODOT_BIN: str = str(Path.home() / "godot" / "godot")
+    # Godot project directory (the game repo root -- backend/ is a subdir).
+    GAME_PROJECT_DIR: str = str(Path(__file__).resolve().parents[2])
+    # The host clients should connect to for ENet. Defaults to the LAN IP the
+    # launcher bakes into the exe; overridable for local testing.
+    GAME_SERVER_HOST: str = "127.0.0.1"
+    # Port range for per-world dedicated servers.
+    GAME_SERVER_PORT_MIN: int = 27000
+    GAME_SERVER_PORT_MAX: int = 27099
+    # Kill a world's server this long after its last join with no active
+    # players reported.
+    GAME_SERVER_IDLE_TIMEOUT_SECONDS: int = 300
+    # How long ensure_server() waits for a spawned server to report
+    # "ready": true in its status file before giving up (503 to the
+    # joining client). See world_persistence_impl.md §7.4 -- content
+    # loading makes a slow start more likely than the old bare-port-bind
+    # wait, so this is a separate, longer-by-default budget.
+    GAME_SERVER_READY_TIMEOUT_SECONDS: float = 20.0
+    # The base URL the dedicated Godot server should call back into this
+    # backend on, for the read-only /api/internal content routes
+    # (world_persistence_impl.md §4.4 / §7).
+    GAME_SERVER_INTERNAL_API_URL: str = "http://127.0.0.1:8000"
+
+    # ── World content persistence (world_persistence_impl.md §4.4) ─────────
+    WORLD_CHUNK_MAX_PAYLOAD_BYTES: int = 1_048_576  # 1 MiB
+    WORLD_CHUNK_MAX_OBJECTS: int = 512
+    WORLD_CHUNK_MAX_BATCH: int = 64
+    WORLD_CHUNK_REVISION_KEEP: int = 20
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+    )
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
+
+    @property
+    def rsa_key_dir(self) -> Path:
+        return Path(self.RSA_KEY_DIR)
+
+    @property
+    def private_pem(self) -> bytes:
+        """Return the private key PEM bytes (loads/generates on first call)."""
+        private_pem, _ = _load_or_generate_rsa_keys(self.rsa_key_dir)
+        return private_pem
+
+    @property
+    def public_pem(self) -> bytes:
+        """Return the public key PEM bytes (loads/generates on first call)."""
+        _, public_pem = _load_or_generate_rsa_keys(self.rsa_key_dir)
+        return public_pem
+
+    @property
+    def private_key(self) -> RSAPrivateKey:
+        """Return the deserialized RSA private key object."""
+        return load_pem_private_key(self.private_pem, password=None)
+
+    @property
+    def public_key(self) -> RSAPublicKey:
+        """Return the deserialized RSA public key object."""
+        return load_pem_public_key(self.public_pem)
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Return cached settings instance."""
+    return Settings()
+
+
+# Convenience singleton
+settings = get_settings()

backend/app/database.py

@@ -0,0 +1,42 @@
+"""Async database engine and session factory."""
+
+from sqlalchemy.ext.asyncio import (
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+from app.config import settings
+
+engine = create_async_engine(
+    settings.DATABASE_URL,
+    echo=settings.DEBUG,
+    pool_size=10,
+    max_overflow=20,
+)
+
+async_session_factory = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+async def get_db() -> AsyncSession:
+    """Dependency that yields an async database session.
+
+    Handlers are responsible for committing or rolling back their own
+    transactions.  This avoids the double-commit problem where the
+    session is committed both here and in the handler.
+    """
+    async with async_session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise

backend/app/dependencies.py

@@ -0,0 +1,55 @@
+"""Shared FastAPI dependencies, including JWT-based auth."""
+
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import get_db
+from app.models.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> User:
+    """Resolve the JWT bearer token to a User, or raise 401."""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(
+            token, settings.public_pem, algorithms=[settings.ALGORITHM]
+        )
+        user_id: str | None = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    try:
+        user_id_int = int(user_id)
+    except (ValueError, TypeError):
+        raise credentials_exception
+
+    result = await db.execute(select(User).where(User.id == user_id_int))
+    user = result.scalar_one_or_none()
+    if user is None:
+        raise credentials_exception
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is inactive",
+        )
+    return user
+
+
+CurrentUser = Annotated[User, Depends(get_current_user)]

backend/app/main.py

@@ -0,0 +1,55 @@
+"""FastAPI application entry point."""
+
+from contextlib import asynccontextmanager
+
+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
+
+
+from app.services.game_servers import supervisor
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan: startup and shutdown events."""
+    supervisor.start()
+    yield
+    await supervisor.shutdown()
+
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    version=settings.APP_VERSION,
+    description="Agentic Game Platform - Backend API",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include routers
+app.include_router(auth.router, prefix="/api/auth", tags=["auth"])
+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(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"])
+app.include_router(groups.router, prefix="/api/groups", tags=["groups"])
+app.include_router(social_friends.router, prefix="/api/friends", tags=["friends"])
+
+
+@app.get("/api/health")
+async def health_check():
+    """Simple health check endpoint."""
+    return {"status": "ok", "app": settings.APP_NAME}

backend/app/models/__init__.py

@@ -0,0 +1,19 @@
+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.avatar_loadout import AvatarLoadout
+from app.models.world_content import WorldRoom, WorldChunk, WorldChunkRevision
+from app.models.social import Friendship, Follow, Block, FriendshipStatus
+from app.models.chat import (
+    Conversation, ConversationParticipant, Message, MessageReport, ReportStatus,
+)
+from app.models.groups import Group, GroupMember, GroupRole
+
+__all__ = [
+    "User", "Session", "World", "Asset", "AvatarLoadout",
+    "WorldRoom", "WorldChunk", "WorldChunkRevision",
+    "Friendship", "Follow", "Block", "FriendshipStatus",
+    "Conversation", "ConversationParticipant", "Message", "MessageReport", "ReportStatus",
+    "Group", "GroupMember", "GroupRole",
+]

backend/app/models/asset.py

@@ -0,0 +1,40 @@
+from sqlalchemy import Column, Integer, String, ForeignKey, Text, DateTime, Boolean
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class AssetType(str, enum.Enum):
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    MODEL_3D = "model_3d"
+    OTHER = "other"
+
+
+class Asset(Base):
+    __tablename__ = "assets"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    asset_type = Column(
+        ENUM(AssetType, name="asset_type", create_type=False),
+        nullable=False,
+    )
+    file_path = Column(String(512), nullable=False)
+    file_size = Column(Integer, nullable=True)
+    mime_type = Column(String(128), nullable=True)
+    metadata_json = Column(Text, nullable=True)
+    world_id = Column(Integer, ForeignKey("worlds.id"), nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    is_public = Column(Boolean, default=False, nullable=False)
+    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="assets")
+    world = relationship("World", back_populates="assets")

backend/app/models/avatar_loadout.py

@@ -0,0 +1,41 @@
+from sqlalchemy import Column, Integer, ForeignKey, DateTime
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+# The default a brand-new account gets before they touch the customization
+# screen. Kept in sync with assets/avatars/catalog.json (the base_body id) and
+# with the client's AvatarLoadout.to_json() shape.
+DEFAULT_LOADOUT: dict = {
+    "base_body": "base_human_male_01",
+    "slots": {},
+}
+
+
+class AvatarLoadout(Base):
+    """A user's equipped avatar composition.
+
+    One row per user. The whole loadout is stored as a single JSON document
+    matching the client's ``AvatarLoadout.to_json()`` shape
+    (``{"base_body": str, "slots": {...}, "skin_tone"?: {...}}``) rather than
+    exploded into columns -- the server has no copy of the asset catalog, so
+    deep validation (does this asset exist, is it valid for this slot) stays
+    on the client. The server only enforces the envelope: valid JSON object
+    with a non-empty ``base_body``.
+    """
+
+    __tablename__ = "avatar_loadouts"
+
+    user_id = Column(
+        Integer,
+        ForeignKey("users.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    data = Column(JSONB, nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    user = relationship("User", back_populates="avatar_loadout")

backend/app/models/chat.py

@@ -0,0 +1,217 @@
+"""Chat: DM conversations and world/room chat, plus message reports.
+
+docs/planning/social.md §4/§5 (US-4). This module is models + schema only --
+text filtering, rate limiting, and the send/list/report/moderation endpoints
+belong to sibling tasks that depend on this one.
+
+Delete-behavior choices (mirrors ``app/models/world_content.py``'s
+established convention of preserving audit/history data over cascading it
+away):
+
+- ``conversations.user_a_id`` / ``user_b_id`` -> CASCADE. A DM conversation
+  is meaningless with one of its two (and only) participants gone, so
+  deleting either user removes the conversation outright, which in turn
+  cascades to its ``conversation_participants`` rows and its ``messages``.
+- ``conversation_participants.user_id`` -> CASCADE, ``.conversation_id`` ->
+  CASCADE. Pure join-table rows; they only make sense alongside both sides.
+- ``messages.conversation_id`` -> CASCADE. Deleting a conversation deletes
+  its message history with it.
+- ``messages.sender_id`` -> SET NULL (nullable). Unlike a DM conversation
+  (which dies with its participants above), world/room chat history and any
+  message under moderation review should survive the sender's account being
+  deleted -- the row just becomes attributed to no one, matching how
+  ``WorldChunk.updated_by_id`` / ``WorldChunkRevision.actor_id`` treat
+  actor references as SET NULL rather than cascading away history.
+- ``messages.world_id`` / ``room_id`` -> CASCADE. World/room chat has no
+  meaning once the world or room it was said in is gone; consistent with
+  ``WorldChunk``'s own CASCADE from both.
+- ``message_reports.message_id`` -> SET NULL (nullable). Same audit-trail
+  reasoning as ``WorldChunkRevision`` (world_content.py): a moderation
+  report is a record that something *was* said and reported, which must
+  outlive the underlying message being removed (e.g. as the moderation
+  action taken in response to the report itself).
+- ``message_reports.reporter_id`` / ``moderator_id`` -> SET NULL (nullable).
+  Actor references for an audit record; the report itself must survive
+  either account being deleted later, matching the actor-reference
+  convention above.
+"""
+import enum
+
+from sqlalchemy import (
+    Boolean,
+    CheckConstraint,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class ReportStatus(str, enum.Enum):
+    OPEN = "open"
+    RESOLVED = "resolved"
+    DISMISSED = "dismissed"
+
+
+class Conversation(Base):
+    """A DM conversation between exactly two users.
+
+    ``conversation_participants`` is the real roster (modeled as a join
+    table so a future group-DM schema change can widen it beyond two rows
+    without touching this table's shape), but a 2-party DM also needs a
+    cheap, DB-enforced "only one conversation per pair" guarantee, which a
+    plain join table can't express as a simple unique constraint. So the
+    pair is additionally denormalized here as ``user_a_id``/``user_b_id``,
+    always stored with the lower user id first (enforced by the check
+    constraint below); the API layer is responsible for normalizing the
+    pair before insert/lookup.
+    """
+
+    __tablename__ = "conversations"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_a_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    user_b_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    participants = relationship(
+        "ConversationParticipant", back_populates="conversation", cascade="all, delete-orphan"
+    )
+    messages = relationship(
+        "Message", back_populates="conversation", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (
+        UniqueConstraint("user_a_id", "user_b_id", name="uq_conversations_pair"),
+        CheckConstraint("user_a_id < user_b_id", name="ck_conversations_ordered_pair"),
+    )
+
+
+class ConversationParticipant(Base):
+    """Join table of a conversation's members.
+
+    DMs are strictly 2-party today (enforced by ``Conversation``'s pair
+    columns above), but this is modeled as a real join table -- not folded
+    into ``Conversation`` -- so a later group-conversation feature can add
+    rows here without a schema change to this table.
+    """
+
+    __tablename__ = "conversation_participants"
+
+    id = Column(Integer, primary_key=True, index=True)
+    conversation_id = Column(
+        Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    user_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    conversation = relationship("Conversation", back_populates="participants")
+    user = relationship("User")
+
+    __table_args__ = (
+        UniqueConstraint(
+            "conversation_id", "user_id", name="uq_conversation_participants_pair"
+        ),
+    )
+
+
+class Message(Base):
+    """A chat message: either a DM (``conversation_id`` set) or a
+    world/room chat message (``conversation_id`` null, ``world_id`` set and
+    optionally ``room_id``).
+
+    ``world_id`` is denormalized onto every world/room message (mirroring
+    ``WorldChunk.world_id``) so world-scoped history queries don't need a
+    join through rooms; ``room_id`` narrows further to a specific room when
+    the world subdivides chat by room, and is null for world-wide chat.
+    """
+
+    __tablename__ = "messages"
+
+    id = Column(Integer, primary_key=True, index=True)
+    sender_id = Column(
+        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    conversation_id = Column(
+        Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=True
+    )
+    world_id = Column(
+        Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=True
+    )
+    room_id = Column(
+        Integer, ForeignKey("world_rooms.id", ondelete="CASCADE"), nullable=True
+    )
+    body = Column(Text, nullable=False)
+    filtered = Column(Boolean, nullable=False, default=False, server_default="false")
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    sender = relationship("User")
+    conversation = relationship("Conversation", back_populates="messages")
+    world = relationship("World")
+    room = relationship("WorldRoom")
+    reports = relationship(
+        "MessageReport", back_populates="message", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (
+        Index("ix_messages_conversation_created", "conversation_id", "created_at"),
+        Index("ix_messages_world_created", "world_id", "created_at"),
+    )
+
+
+class MessageReport(Base):
+    """A moderation report filed against a message.
+
+    ``message_id`` is nullable with ``ON DELETE SET NULL`` (rather than
+    CASCADE) so the report -- the audit record that something was said and
+    flagged -- outlives the message row, including when the message's own
+    removal is the moderation action taken in response to this report.
+    """
+
+    __tablename__ = "message_reports"
+
+    id = Column(Integer, primary_key=True, index=True)
+    message_id = Column(
+        Integer, ForeignKey("messages.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    reporter_id = Column(
+        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    reason = Column(Text, nullable=False)
+    status = Column(
+        ENUM(
+            ReportStatus,
+            name="message_report_status",
+            create_type=False,
+            values_callable=lambda enum_cls: [e.value for e in enum_cls],
+        ),
+        nullable=False,
+        default=ReportStatus.OPEN,
+        server_default=ReportStatus.OPEN.value,
+    )
+    moderator_id = Column(
+        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    resolved_at = Column(DateTime(timezone=True), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    message = relationship("Message", back_populates="reports")
+    reporter = relationship("User", foreign_keys=[reporter_id])
+    moderator = relationship("User", foreign_keys=[moderator_id])

backend/app/models/groups.py

@@ -0,0 +1,97 @@
+"""Groups: named groups with owner/admin/member roles.
+
+docs/planning/social.md §4/§5 (US-5). This module is models + schema only --
+create/join/leave, role authorization (only the owner may transfer ownership
+or promote/demote admins), and the group page aggregate endpoint belong to
+the API router task ("Groups API") that depends on this one.
+
+Delete-behavior choices:
+
+- ``groups.owner_id`` -> ``SET NULL`` (nullable). A group is a durable,
+  multi-member community, not content solely attributable to one person like
+  a ``World``/``Asset``. Cascading the group away (or hard-blocking the
+  owner's account deletion) would punish every other member for the owner's
+  choice to leave the platform. Instead the group and its full membership
+  list survive with ``owner_id`` nulled out; the sibling API task is
+  responsible for surfacing an ownerless group (e.g. prompting an admin to
+  claim ownership) the same way ``Message.sender_id`` / ``WorldChunk``'s
+  actor columns already treat "the actor is gone" as a survivable state
+  elsewhere in this schema.
+- ``group_members.group_id`` -> ``CASCADE``. A membership row is meaningless
+  without the group it belongs to; deleting a group deletes its roster,
+  mirroring ``ConversationParticipant.conversation_id`` in chat.py.
+- ``group_members.user_id`` -> ``CASCADE``. Deleting a user removes their own
+  membership rows wherever they appear, matching the join-table convention
+  used by ``ConversationParticipant.user_id`` and the social-graph tables
+  (``Friendship``/``Follow``/``Block``) for plain per-user references.
+"""
+import enum
+
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text, UniqueConstraint
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class GroupRole(str, enum.Enum):
+    OWNER = "owner"
+    ADMIN = "admin"
+    MEMBER = "member"
+
+
+class Group(Base):
+    """A named group. ``owner_id`` is nullable -- see module docstring for
+    why the group survives its owner's account deletion."""
+
+    __tablename__ = "groups"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(100), nullable=False)
+    description = Column(Text, nullable=True)
+    owner_id = Column(
+        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    owner = relationship("User", back_populates="owned_groups")
+    members = relationship(
+        "GroupMember", back_populates="group", cascade="all, delete-orphan"
+    )
+
+
+class GroupMember(Base):
+    """A group's roster: one row per (group, user) with a role."""
+
+    __tablename__ = "group_members"
+
+    id = Column(Integer, primary_key=True, index=True)
+    group_id = Column(
+        Integer, ForeignKey("groups.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    user_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    role = Column(
+        ENUM(
+            GroupRole,
+            name="group_role",
+            create_type=False,
+            values_callable=lambda enum_cls: [e.value for e in enum_cls],
+        ),
+        nullable=False,
+        default=GroupRole.MEMBER,
+        server_default=GroupRole.MEMBER.value,
+    )
+    joined_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+
+    group = relationship("Group", back_populates="members")
+    user = relationship("User", back_populates="group_memberships")
+
+    __table_args__ = (
+        UniqueConstraint("group_id", "user_id", name="uq_group_members_pair"),
+    )

backend/app/models/session.py

@@ -0,0 +1,41 @@
+import uuid
+
+from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Boolean
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class Session(Base):
+    __tablename__ = "sessions"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    token = Column(String, unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    user = relationship("User", back_populates="sessions")
+
+
+class RefreshToken(Base):
+    __tablename__ = "refresh_tokens"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    # RS256 JWTs are ~420+ chars; 512 is sufficient and matches the migration.
+    token = Column(String(512), unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, nullable=False, default=True, server_default="true")
+    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    user = relationship("User", back_populates="refresh_tokens")

backend/app/models/social.py

@@ -0,0 +1,106 @@
+"""Social graph: friendships, follows, blocks.
+
+docs/planning/social.md §4/§5 (US-1). Friends = mutual (request -> accept),
+Follow = one-way (no approval), Block = hard deny. This module is models +
+schema only -- the request/accept/block business logic (idempotent
+duplicate/self handling, removing an existing friendship/follow on block,
+etc.) belongs to the API router task that depends on this one.
+"""
+import enum
+
+from sqlalchemy import Column, Integer, ForeignKey, DateTime, UniqueConstraint
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class FriendshipStatus(str, enum.Enum):
+    PENDING = "pending"
+    ACCEPTED = "accepted"
+
+
+class Friendship(Base):
+    """A friend request, directional until accepted.
+
+    ``requester_id`` sent the request to ``addressee_id``. Once accepted the
+    friendship is mutual, but the row stays directional (who asked whom) for
+    audit purposes; the API layer treats it as symmetric once accepted.
+    """
+
+    __tablename__ = "friendships"
+
+    id = Column(Integer, primary_key=True, index=True)
+    requester_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    addressee_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    status = Column(
+        ENUM(
+            FriendshipStatus,
+            name="friendship_status",
+            create_type=False,
+            values_callable=lambda enum_cls: [e.value for e in enum_cls],
+        ),
+        nullable=False,
+        default=FriendshipStatus.PENDING,
+        server_default=FriendshipStatus.PENDING.value,
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    requester = relationship("User", foreign_keys=[requester_id], back_populates="sent_friend_requests")
+    addressee = relationship("User", foreign_keys=[addressee_id], back_populates="received_friend_requests")
+
+    __table_args__ = (
+        UniqueConstraint("requester_id", "addressee_id", name="uq_friendships_pair"),
+    )
+
+
+class Follow(Base):
+    """A one-way follow relationship: ``follower_id`` follows ``followed_id``."""
+
+    __tablename__ = "follows"
+
+    id = Column(Integer, primary_key=True, index=True)
+    follower_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    followed_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    follower = relationship("User", foreign_keys=[follower_id], back_populates="following")
+    followed = relationship("User", foreign_keys=[followed_id], back_populates="followers")
+
+    __table_args__ = (
+        UniqueConstraint("follower_id", "followed_id", name="uq_follows_pair"),
+    )
+
+
+class Block(Base):
+    """A hard deny: ``blocker_id`` has blocked ``blocked_id``."""
+
+    __tablename__ = "blocks"
+
+    id = Column(Integer, primary_key=True, index=True)
+    blocker_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    blocked_id = Column(
+        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False)
+
+    blocker = relationship("User", foreign_keys=[blocker_id], back_populates="blocks_initiated")
+    blocked = relationship("User", foreign_keys=[blocked_id], back_populates="blocked_by")
+
+    __table_args__ = (
+        UniqueConstraint("blocker_id", "blocked_id", name="uq_blocks_pair"),
+    )

backend/app/models/user.py

@@ -0,0 +1,97 @@
+from datetime import date
+from typing import Optional
+
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date, Text
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String(50), unique=True, index=True, nullable=False)
+    email = Column(String(120), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    date_of_birth = Column(Date, nullable=True)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    # Presence / status (backend/app/services/presence.py, app/routers/presence.py)
+    last_seen_at = Column(DateTime(timezone=True), nullable=True)
+    status_message = Column(Text, nullable=True)
+
+    sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
+    refresh_tokens = relationship("RefreshToken", back_populates="user", cascade="all, delete-orphan")
+    worlds = relationship("World", back_populates="owner")
+    assets = relationship("Asset", back_populates="owner")
+    avatar_loadout = relationship(
+        "AvatarLoadout",
+        back_populates="user",
+        uselist=False,
+        cascade="all, delete-orphan",
+    )
+
+    # Social graph (docs/planning/social.md US-1; app/models/social.py)
+    sent_friend_requests = relationship(
+        "Friendship",
+        foreign_keys="Friendship.requester_id",
+        back_populates="requester",
+        cascade="all, delete-orphan",
+    )
+    received_friend_requests = relationship(
+        "Friendship",
+        foreign_keys="Friendship.addressee_id",
+        back_populates="addressee",
+        cascade="all, delete-orphan",
+    )
+    following = relationship(
+        "Follow",
+        foreign_keys="Follow.follower_id",
+        back_populates="follower",
+        cascade="all, delete-orphan",
+    )
+    followers = relationship(
+        "Follow",
+        foreign_keys="Follow.followed_id",
+        back_populates="followed",
+        cascade="all, delete-orphan",
+    )
+    blocks_initiated = relationship(
+        "Block",
+        foreign_keys="Block.blocker_id",
+        back_populates="blocker",
+        cascade="all, delete-orphan",
+    )
+    blocked_by = relationship(
+        "Block",
+        foreign_keys="Block.blocked_id",
+        back_populates="blocked",
+        cascade="all, delete-orphan",
+    )
+
+    # Groups (docs/planning/social.md US-5; app/models/groups.py)
+    owned_groups = relationship(
+        "Group",
+        back_populates="owner",
+    )
+    group_memberships = relationship(
+        "GroupMember",
+        back_populates="user",
+        cascade="all, delete-orphan",
+    )
+
+    @property
+    def is_adult(self) -> bool:
+        """Return True if the user is 18 or older based on date_of_birth."""
+        if self.date_of_birth is None:
+            return False
+        today = date.today()
+        age = today.year - self.date_of_birth.year
+        # Adjust if birthday hasn't occurred yet this year
+        if (today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day):
+            age -= 1
+        return age >= 18

backend/app/models/world.py

@@ -0,0 +1,39 @@
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
+from sqlalchemy.dialects.postgresql import ENUM
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+import enum
+
+from app.database import Base
+
+
+class WorldVisibility(enum.Enum):
+    PUBLIC = "public"
+    PRIVATE = "private"
+    FRIENDS_ONLY = "friends_only"
+
+
+class World(Base):
+    __tablename__ = "worlds"
+
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    visibility = Column(
+        ENUM(
+            WorldVisibility,
+            name="world_visibility",
+            create_type=False,
+            values_callable=lambda enum_cls: [e.value for e in enum_cls],
+        ),
+        default=WorldVisibility.PUBLIC,
+    )
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
+
+    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")

backend/app/models/world_content.py

@@ -0,0 +1,153 @@
+"""World content persistence models.
+
+Implements the schema decided in ``docs/architecture/world_persistence_impl.md``
+§4: chunk content (rooms, chunk payloads, chunk revisions) lives in Postgres,
+alongside ``worlds``, rather than in a per-world SQLite file
+(``docs/architecture/world.md`` §4, superseded).
+
+The chunk *payload* format itself (the 48-byte header + sectioned binary
+body) is unchanged from ``world.md`` §3.6 and is decoded/encoded by
+``app.services.chunk_codec``, not by these models -- these just store the
+opaque ``BYTEA``.
+
+Conventions follow the existing models (``app/models/world.py``,
+``app/models/avatar_loadout.py``): declarative ``Column(...)`` style,
+``Integer`` surrogate PKs, ``DateTime(timezone=True)`` with
+``server_default=func.now()``, JSONB for document-shaped fields.
+"""
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    LargeBinary,
+    String,
+    UniqueConstraint,
+    text,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from app.database import Base
+
+# Default chunk grid, matching Chunk.CHUNK_SIZE_* in scripts/chunk.gd (the
+# client's source of truth for the same constants) and world.md §2.2.
+DEFAULT_ROOM_GRID: dict = {"size": [32, 32, 1], "origin": [0, 0, 0]}
+
+# The room every world gets automatically (world_persistence_impl.md §4.1).
+MAIN_ROOM_SLUG = "main"
+MAIN_ROOM_NAME = "Main"
+
+
+class WorldRoom(Base):
+    """A bounded region within a world -- a level, building, or zone
+    (world.md §2.1). Holds the chunk grid config so a world can later hold
+    rooms with different grids without touching the ``worlds`` table.
+    """
+
+    __tablename__ = "world_rooms"
+
+    id = Column(Integer, primary_key=True, index=True)
+    world_id = Column(
+        Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    slug = Column(String(64), nullable=False)  # url-safe; "main" by default
+    name = Column(String(255), nullable=False)
+    # {"size": [x, y, z], "origin": [x, y, z]}
+    grid = Column(
+        JSONB, nullable=False,
+        server_default='{"size": [32, 32, 1], "origin": [0, 0, 0]}',
+    )
+    bounds = Column(JSONB, nullable=True)  # {"min":[x,y,z], "max":[x,y,z]}; null = unbounded
+    spawn = Column(JSONB, nullable=True)  # {"pos":[x,y,z], "yaw": 0.0}
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint("world_id", "slug", name="uq_world_rooms_world_slug"),
+    )
+
+    world = relationship("World", back_populates="rooms")
+    chunks = relationship("WorldChunk", back_populates="room", cascade="all, delete-orphan")
+
+
+class WorldChunk(Base):
+    """One chunk's persisted content -- the atomic load/save/stream unit
+    (world.md §2.1). ``payload`` is the world.md §3.6 binary blob, stored
+    verbatim as BYTEA.
+
+    Deltas from world.md §4.4 (SQLite design): a surrogate integer PK +
+    unique coordinate constraint (rather than ``chunk_key`` as the PK), no
+    ``dirty`` column (write-behind doesn't apply over Postgres -- see
+    world_persistence_impl.md §3.3/§5), and content flags folded into this
+    row as JSONB + an indexed ``is_mature`` boolean rather than a separate
+    ``content_flags`` table (world.md §4.6).
+    """
+
+    __tablename__ = "world_chunks"
+
+    id = Column(Integer, primary_key=True, index=True)
+    world_id = Column(
+        Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=False, index=True
+    )  # denormalized: world-scoped queries without a join through rooms
+    room_id = Column(
+        Integer, ForeignKey("world_rooms.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    chunk_key = Column(String(160), nullable=False, unique=True)  # world.md §2.3 / §4.5
+    cx = Column(Integer, nullable=False)
+    cy = Column(Integer, nullable=False)
+    cz = Column(Integer, nullable=False, server_default="0")
+
+    format_version = Column(Integer, nullable=False, server_default="1")
+    payload = Column(LargeBinary, nullable=False)  # world.md §3.6 bytes
+    payload_len = Column(Integer, nullable=False)
+    checksum = Column(String(64), nullable=False)  # SHA-256 hex of payload body
+    revision = Column(Integer, nullable=False, server_default="1")
+
+    content_flags = Column(JSONB, nullable=False, server_default="{}")  # world.md §3.4
+    is_mature = Column(Boolean, nullable=False, server_default="false")
+
+    updated_by_id = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at = Column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    __table_args__ = (
+        UniqueConstraint("room_id", "cx", "cy", "cz", name="uq_world_chunks_coord"),
+        Index("ix_world_chunks_room_coord", "room_id", "cx", "cy", "cz"),
+        Index("ix_world_chunks_mature", "world_id", postgresql_where=text("is_mature")),
+    )
+
+    room = relationship("WorldRoom", back_populates="chunks")
+
+
+class WorldChunkRevision(Base):
+    """Audit trail of chunk writes (world.md §4.7). ``chunk_key``/``world_id``
+    are deliberately **not** foreign keys, so deleting a chunk or a world
+    preserves the audit trail.
+
+    Retention (world_persistence_impl.md §4.3, required): only the newest
+    ``settings.WORLD_CHUNK_REVISION_KEEP`` rows per ``chunk_key`` keep a
+    non-null ``payload``; older rows are pruned (payload nulled, metadata
+    row kept) by ``WorldStore`` in the same transaction as the write that
+    triggers it.
+    """
+
+    __tablename__ = "world_chunk_revisions"
+
+    id = Column(Integer, primary_key=True, index=True)
+    chunk_key = Column(String(160), nullable=False, index=True)
+    world_id = Column(Integer, nullable=False, index=True)
+    revision = Column(Integer, nullable=False)
+    action = Column(String(16), nullable=False)  # 'create' | 'update' | 'delete'
+    actor_id = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True)
+    checksum = Column(String(64), nullable=False)
+    payload = Column(LargeBinary, nullable=True)  # full payload at this revision; nulled by retention
+    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False, index=True)

backend/app/rate_limit.py

@@ -0,0 +1,114 @@
+"""Lightweight in-process rate limiting.
+
+The backend runs single-worker (required by the game-server supervisor), so a
+process-local sliding-window counter is sufficient and needs no Redis. Keyed
+by client IP. Used to blunt credential brute-force on the auth endpoints.
+
+If the backend is ever scaled to multiple workers/hosts this must move to a
+shared store (Redis) -- flagged here rather than silently under-enforcing.
+"""
+from __future__ import annotations
+
+import time
+from collections import defaultdict, deque
+
+from fastapi import HTTPException, Request, status
+
+from app.config import settings
+
+
+class SlidingWindowLimiter:
+    def __init__(self, max_hits: int, window_seconds: float) -> None:
+        self.max_hits = max_hits
+        self.window = window_seconds
+        self._hits: dict[str, deque[float]] = defaultdict(deque)
+
+    def check(self, key: str) -> None:
+        now = time.monotonic()
+        q = self._hits[key]
+        cutoff = now - self.window
+        while q and q[0] < cutoff:
+            q.popleft()
+        if len(q) >= self.max_hits:
+            retry = max(1, int(q[0] + self.window - now))
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Too many attempts. Try again shortly.",
+                headers={"Retry-After": str(retry)},
+            )
+        q.append(now)
+
+    def reset(self) -> None:
+        self._hits.clear()
+
+
+def _client_key(request: Request) -> str:
+    # X-Forwarded-For first hop when behind the reverse proxy, else the socket.
+    fwd = request.headers.get("x-forwarded-for", "")
+    if fwd:
+        return fwd.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+# 10 auth attempts / minute / IP -- generous for a human, painful for a
+# brute-forcer.
+_auth_limiter = SlidingWindowLimiter(max_hits=10, window_seconds=60)
+
+# Every limiter in the process -- named limits built via `rate_limit()`
+# below register themselves here too, so `reset_all()` (the test hook) and
+# any future process-wide accounting stay correct without each caller
+# having to remember to wire it up.
+_registered_limiters: list[SlidingWindowLimiter] = [_auth_limiter]
+
+
+async def auth_rate_limit(request: Request) -> None:
+    """FastAPI dependency: rate-limit auth attempts per client IP.
+
+    A no-op when ``RATE_LIMIT_ENABLED`` is false -- the checkpoint smoke
+    suite runs every test against one backend from one client IP, so the
+    per-IP cap would trip mid-suite. The dedicated ``test_rate_limit``
+    module exercises the real behaviour regardless of this flag.
+    """
+    if not settings.RATE_LIMIT_ENABLED:
+        return
+    _auth_limiter.check(f"auth:{_client_key(request)}")
+
+
+def rate_limit(name: str, *, max_hits: int, window_seconds: float):
+    """Build a named, per-client-IP FastAPI rate-limit dependency.
+
+    Generalizes the ``auth_rate_limit`` pattern above for other endpoints
+    (e.g. chat send, message report) that want their own independent cap:
+
+        report_rate_limit = rate_limit("message_report", max_hits=5, window_seconds=60)
+
+        @router.post("/report", dependencies=[Depends(report_rate_limit)])
+        ...
+
+    Each call gets its own ``SlidingWindowLimiter`` -- counters for one
+    named limit never bleed into another, even for the same client IP --
+    and reuses ``SlidingWindowLimiter.check`` for the actual sliding-window
+    accounting and the 429 + ``Retry-After`` response. Like
+    ``auth_rate_limit``, the returned dependency is a no-op when
+    ``settings.RATE_LIMIT_ENABLED`` is false, so the checkpoint smoke suite
+    (one client IP for the whole run) doesn't trip on it.
+
+    ``name`` only needs to be unique within the process; it namespaces the
+    per-IP key so it doesn't collide with ``auth_rate_limit`` or any other
+    named limit.
+    """
+    limiter = SlidingWindowLimiter(max_hits=max_hits, window_seconds=window_seconds)
+    _registered_limiters.append(limiter)
+
+    async def _dependency(request: Request) -> None:
+        if not settings.RATE_LIMIT_ENABLED:
+            return
+        limiter.check(f"{name}:{_client_key(request)}")
+
+    return _dependency
+
+
+def reset_all() -> None:
+    """Test hook."""
+    for limiter in _registered_limiters:
+        limiter.reset()

backend/app/routers/assets.py

@@ -0,0 +1,243 @@
+"""Asset management router."""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+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.world import World
+from app.services import gltf as gltf_service
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+# --- Pydantic schemas ---
+
+class AssetCreate(BaseModel):
+    """Schema for creating an asset reference."""
+    name: str = Field(..., min_length=1, max_length=255)
+    description: Optional[str] = None
+    asset_type: AssetType
+    world_id: Optional[int] = None
+
+
+class AssetResponse(BaseModel):
+    """Schema for asset responses."""
+    id: int
+    name: str
+    description: Optional[str]
+    asset_type: AssetType
+    file_path: str
+    file_size: Optional[int]
+    mime_type: Optional[str]
+    world_id: Optional[int]
+    owner_id: int
+    is_public: bool
+    created_at: str
+    updated_at: str
+
+    model_config = {"from_attributes": True}
+
+
+class AssetUpdate(BaseModel):
+    """Schema for updating an asset."""
+    name: Optional[str] = None
+    description: Optional[str] = None
+    is_public: Optional[bool] = None
+
+
+# --- Helpers ---
+
+def _sanitize_filename(filename: str) -> str:
+    """Strip path components and unsafe characters from a filename."""
+    # Remove any directory components (path traversal protection).
+    base = os.path.basename(filename.replace("\\", "/"))
+    # Keep only safe characters.
+    safe = "".join(c for c in base if c.isalnum() or c in "._-")
+    return safe or "file"
+
+
+def _detect_asset_type(filename: Optional[str], content: bytes) -> AssetType:
+    """Detect the asset type from filename and content."""
+    if filename and gltf_service.looks_like_gltf(content, filename):
+        return AssetType.MODEL_3D
+    # Fallback: let the caller decide based on mime_type or default.
+    return AssetType.OTHER
+
+
+# --- Endpoints ---
+
+@router.post("/", response_model=AssetResponse, status_code=201)
+async def create_asset(
+    payload: AssetCreate,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Create a new asset reference."""
+    # Verify world ownership if world_id is provided
+    if payload.world_id is not None:
+        world = await db.get(World, payload.world_id)
+        if world is None:
+            raise HTTPException(status_code=404, detail="World not found")
+        if world.owner_id != current_user.id:
+            raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    asset = Asset(
+        name=payload.name,
+        description=payload.description,
+        asset_type=payload.asset_type,
+        file_path="",  # Will be set after upload
+        owner_id=current_user.id,
+        world_id=payload.world_id,
+        is_public=False,
+    )
+    db.add(asset)
+    await db.commit()
+    await db.refresh(asset)
+    return asset
+
+
+@router.get("/", response_model=list[AssetResponse])
+async def list_assets(
+    current_user: CurrentUser,
+    world_id: Optional[int] = Query(None, description="Filter by world"),
+    asset_type: Optional[AssetType] = Query(None),
+    limit: int = Query(50, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    db: AsyncSession = Depends(get_db),
+):
+    """List assets with optional filters."""
+    stmt = select(Asset).where(Asset.owner_id == current_user.id)
+
+    if world_id is not None:
+        stmt = stmt.where(Asset.world_id == world_id)
+    if asset_type is not None:
+        stmt = stmt.where(Asset.asset_type == asset_type)
+
+    stmt = stmt.order_by(Asset.created_at.desc()).limit(limit).offset(offset)
+    result = await db.execute(stmt)
+    assets = result.scalars().all()
+    return assets
+
+
+@router.get("/{asset_id}", response_model=AssetResponse)
+async def get_asset(
+    asset_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Get a single asset by ID."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+    return asset
+
+
+@router.patch("/{asset_id}", response_model=AssetResponse)
+async def update_asset(
+    asset_id: int,
+    payload: AssetUpdate,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Update an asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    update_data = payload.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(asset, field, value)
+
+    await db.commit()
+    await db.refresh(asset)
+    return asset
+
+
+@router.delete("/{asset_id}", status_code=204)
+async def delete_asset(
+    asset_id: int,
+    current_user: CurrentUser,
+    db: AsyncSession = Depends(get_db),
+):
+    """Delete an asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    await db.delete(asset)
+    await db.commit()
+
+
+@router.post("/{asset_id}/upload", response_model=AssetResponse)
+async def upload_asset_file(
+    asset_id: int,
+    current_user: CurrentUser,
+    file: UploadFile = File(...),
+    db: AsyncSession = Depends(get_db),
+):
+    """Upload a file for an existing asset."""
+    asset = await db.get(Asset, asset_id)
+    if asset is None or asset.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="Asset not found")
+
+    # Sanitize filename to prevent path traversal.
+    safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
+
+    # Read the file content.
+    content = await file.read()
+    file_size = len(content)
+
+    # Determine which size limit to apply.
+    if gltf_service.looks_like_gltf(content, file.filename):
+        max_bytes = settings.GLTF_MAX_FILE_SIZE_MB * 1024 * 1024
+    else:
+        max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
+
+    if file_size > max_bytes:
+        raise HTTPException(
+            status_code=413,
+            detail=f"File size {file_size} exceeds maximum allowed size {max_bytes} bytes",
+        )
+
+    # Write the file to the upload directory.
+    upload_dir = Path(settings.UPLOAD_DIR)
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    stored_name = f"{asset_id}_{safe_filename}"
+    file_path = upload_dir / stored_name
+    file_path.write_bytes(content)
+
+    # Detect asset type from content/filename.
+    detected_type = _detect_asset_type(file.filename, content)
+
+    # Update asset record.
+    asset.file_path = str(file_path)
+    asset.mime_type = file.content_type
+    asset.file_size = file_size
+
+    # If this is a glTF file, extract and store metadata.
+    if detected_type == AssetType.MODEL_3D:
+        try:
+            metadata = gltf_service.extract_gltf_metadata(content)
+            asset.metadata_json = json.dumps(metadata)
+            # Also set the asset type to model_3d if it was auto-detected.
+            if asset.asset_type == AssetType.OTHER:
+                asset.asset_type = AssetType.MODEL_3D
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid glTF file: {exc}",
+            )
+
+    await db.commit()
+    await db.refresh(asset)
+    return asset

backend/app/routers/auth.py

@@ -0,0 +1,323 @@
+"""Authentication router - login, register, token refresh."""
+
+import uuid
+from datetime import date, datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.session import RefreshToken
+from app.models.user import User
+from app.rate_limit import auth_rate_limit
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+router = APIRouter()
+
+## Minimum age to register. This platform is adults-only.
+MIN_AGE = 18
+
+
+# --- Pydantic schemas ---
+
+class TokenResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    access_token_expires_minutes: int
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+
+
+class RegisterRequest(BaseModel):
+    username: str
+    email: EmailStr
+    password: str
+    # Real date of birth -- the server computes age from it and rejects
+    # anyone under MIN_AGE. Still self-attested (no document check yet), but
+    # a concrete, stored, legally-meaningful data point rather than a
+    # throwaway checkbox, and the seam for a future hard ID-verification
+    # pass. See docs/architecture/content_moderation.md 5.2.
+    date_of_birth: date
+
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    date_of_birth: date | None = None
+    is_active: bool
+    created_at: datetime | None = None
+
+    model_config = {"from_attributes": True}
+
+
+# --- Helpers ---
+
+def _create_access_token(data: dict) -> str:
+    """Create a signed access token using RS256.
+
+    Includes a unique ``jti`` claim so that concurrent/same-second calls
+    (e.g. back-to-back /refresh requests) still produce distinct tokens —
+    without it, two tokens minted for the same user within the same
+    second are byte-identical since ``sub``/``exp`` are the only claims.
+    """
+    to_encode = data.copy()
+    to_encode["jti"] = str(uuid.uuid4())
+    expire = datetime.now(timezone.utc) + timedelta(
+        minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+    )
+    to_encode.update({"exp": expire})
+    return jwt.encode(
+        to_encode,
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def _create_refresh_token(data: dict) -> str:
+    """Create a signed refresh token using RS256.
+
+    Includes a unique ``jti`` claim so that concurrent calls produce
+    distinct tokens even when issued within the same second.
+    """
+    to_encode = data.copy()
+    to_encode["jti"] = str(uuid.uuid4())
+    expire = datetime.now(timezone.utc) + timedelta(
+        days=settings.REFRESH_TOKEN_EXPIRE_DAYS
+    )
+    to_encode.update({"exp": expire})
+    return jwt.encode(
+        to_encode,
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a plain password against a hash."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def hash_password(password: str) -> str:
+    """Hash a password."""
+    return pwd_context.hash(password)
+
+
+def calculate_age(birth_date: date, today: date | None = None) -> int:
+    """Calculate age in years from a birth date.
+
+    Used by /register (PC3 Phase 3) to compute age from the submitted
+    date_of_birth and enforce the 18+ gate. See
+    docs/architecture/content_moderation.md 5.2.
+
+    Args:
+        birth_date: The person's date of birth.
+        today: The reference date. Defaults to today's date (UTC).
+
+    Returns:
+        Age in whole years as of the reference date.
+    """
+    if today is None:
+        today = datetime.now(timezone.utc).date()
+
+    age = today.year - birth_date.year
+    # Adjust if birthday hasn't occurred yet this year
+    if (today.month, today.day) < (birth_date.month, birth_date.day):
+        age -= 1
+    return age
+
+
+def _issue_refresh_token(user_id: int, db: AsyncSession) -> str:
+    """Create and persist a refresh token for the given user."""
+    refresh_token_value = _create_refresh_token({"sub": str(user_id)})
+    refresh_token_record = RefreshToken(
+        id=str(uuid.uuid4()),
+        user_id=user_id,
+        token=refresh_token_value,
+        expires_at=datetime.now(timezone.utc)
+        + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS),
+    )
+    db.add(refresh_token_record)
+    return refresh_token_value
+
+
+# --- Endpoints ---
+
+@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED,
+             dependencies=[Depends(auth_rate_limit)])
+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
+    under MIN_AGE (18). See docs/architecture/content_moderation.md for the
+    verification design and its self-attestation limitation.
+    """
+    age = calculate_age(req.date_of_birth)
+    if age < 0 or req.date_of_birth > date.today():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid date of birth",
+        )
+    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",
+        )
+
+    # Check if username already exists
+    result = await db.execute(select(User).where(User.username == req.username))
+    if result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Username already registered",
+        )
+
+    # Check if email already exists
+    result = await db.execute(select(User).where(User.email == req.email))
+    if result.scalar_one_or_none():
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Email already registered",
+        )
+
+    user = User(
+        username=req.username,
+        email=req.email,
+        hashed_password=hash_password(req.password),
+        date_of_birth=req.date_of_birth,
+    )
+    db.add(user)
+    await db.flush()  # flush to get user.id before creating refresh token
+    await db.refresh(user)
+
+    # Create access token
+    access_token = _create_access_token({"sub": str(user.id)})
+
+    # Create and persist refresh token
+    refresh_token_value = _issue_refresh_token(user.id, db)
+    await db.commit()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token_value,
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.post("/login", response_model=TokenResponse, dependencies=[Depends(auth_rate_limit)])
+async def login(form: OAuth2PasswordRequestForm = Depends(), db: AsyncSession = Depends(get_db)):
+    """Authenticate user and return access + refresh tokens.
+
+    Accepts form-encoded credentials (username/password) as expected by
+    OAuth2PasswordBearer, so the Swagger UI "Authorize" flow works correctly.
+    """
+    result = await db.execute(select(User).where(User.username == form.username))
+    user = result.scalar_one_or_none()
+
+    if not user or not verify_password(form.password, user.hashed_password):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+        )
+
+    if not user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is inactive",
+        )
+
+    # Create access token
+    access_token = _create_access_token({"sub": str(user.id)})
+
+    # Create and persist refresh token
+    refresh_token_value = _issue_refresh_token(user.id, db)
+    await db.commit()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token_value,
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(req: RefreshRequest, db: AsyncSession = Depends(get_db)):
+    """Exchange a valid refresh token for a new access token.
+
+    Validates the refresh token against the database:
+    - Must exist in the refresh_tokens table
+    - Must not be expired (expires_at > now)
+    - Must be active (is_active == true)
+
+    On success, returns a new access token. The refresh token itself is
+    NOT rotated (the client keeps using the same refresh token).
+    """
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or expired refresh token",
+    )
+
+    # Step 1: Decode and validate the JWT signature/claims
+    try:
+        payload = jwt.decode(
+            req.refresh_token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+    except JWTError:
+        raise credentials_exception
+
+    user_id_str: str | None = payload.get("sub")
+    if user_id_str is None:
+        raise credentials_exception
+
+    try:
+        user_id = int(user_id_str)
+    except (ValueError, TypeError):
+        raise credentials_exception
+
+    # Step 2: Look up the refresh token in the database
+    result = await db.execute(
+        select(RefreshToken).where(
+            RefreshToken.token == req.refresh_token,
+            RefreshToken.user_id == user_id,
+        )
+    )
+    stored_token = result.scalar_one_or_none()
+
+    if stored_token is None:
+        raise credentials_exception
+
+    # Step 3: Check if the token is expired
+    if datetime.now(timezone.utc) >= stored_token.expires_at:
+        raise credentials_exception
+
+    # Step 4: Check if the token is active
+    if not stored_token.is_active:
+        raise credentials_exception
+
+    # Step 5: Issue a new access token
+    access_token = _create_access_token({"sub": str(user_id)})
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=req.refresh_token,  # Return the same refresh token
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user(current_user: CurrentUser):
+    """Get current user profile from the JWT token."""
+    return current_user

backend/app/routers/avatar.py

@@ -0,0 +1,78 @@
+"""Avatar router - the current user's persisted avatar loadout.
+
+The loadout is a single JSON document matching the client's
+``AvatarLoadout.to_json()`` shape. The server has no copy of the asset
+catalog, so it only validates the envelope (JSON object, non-empty
+``base_body``); which assets are valid for which slot is the client's job.
+"""
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException
+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.avatar_loadout import AvatarLoadout, DEFAULT_LOADOUT
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+# A loadout document is small; reject anything absurd outright.
+MAX_LOADOUT_BYTES = 16 * 1024
+
+
+class LoadoutResponse(BaseModel):
+    data: dict[str, Any]
+    is_default: bool = Field(
+        description="True when the user has never saved a loadout and this is "
+        "the server default."
+    )
+
+
+class LoadoutUpdate(BaseModel):
+    data: dict[str, Any]
+
+
+def _validate_envelope(data: dict[str, Any]) -> None:
+    base_body = data.get("base_body")
+    if not isinstance(base_body, str) or not base_body.strip():
+        raise HTTPException(
+            status_code=422,
+            detail="loadout.data must have a non-empty string 'base_body'",
+        )
+    slots = data.get("slots", {})
+    if not isinstance(slots, dict):
+        raise HTTPException(status_code=422, detail="loadout.data.slots must be an object")
+    if len(str(data)) > MAX_LOADOUT_BYTES:
+        raise HTTPException(status_code=413, detail="loadout document too large")
+
+
+@router.get("/loadout", response_model=LoadoutResponse)
+async def get_loadout(current_user: CurrentUser, db: DbDep):
+    """Return the current user's saved loadout, or the server default if they
+    have never saved one."""
+    row = await db.get(AvatarLoadout, current_user.id)
+    if row is None:
+        return LoadoutResponse(data=dict(DEFAULT_LOADOUT), is_default=True)
+    return LoadoutResponse(data=row.data, is_default=False)
+
+
+@router.put("/loadout", response_model=LoadoutResponse)
+async def put_loadout(payload: LoadoutUpdate, current_user: CurrentUser, db: DbDep):
+    """Replace the current user's loadout."""
+    _validate_envelope(payload.data)
+
+    row = await db.get(AvatarLoadout, current_user.id)
+    if row is None:
+        row = AvatarLoadout(user_id=current_user.id, data=payload.data)
+        db.add(row)
+    else:
+        row.data = payload.data
+
+    await db.commit()
+    await db.refresh(row)
+    return LoadoutResponse(data=row.data, is_default=False)

backend/app/routers/groups.py

@@ -0,0 +1,465 @@
+"""Groups API router.
+
+Endpoints:
+- POST   /api/groups                              -- create (creator becomes owner)
+- GET    /api/groups                               -- list groups (paginated), optional mine=true
+- GET    /api/groups/{id}                          -- group page (name/description/members)
+- PATCH  /api/groups/{id}                          -- update name/description (owner/admin)
+- DELETE /api/groups/{id}                          -- delete (owner only)
+- POST   /api/groups/{id}/join                     -- join (idempotent)
+- POST   /api/groups/{id}/leave                    -- leave (owner must transfer first)
+- POST   /api/groups/{id}/members/{user_id}/role   -- set role admin/member (owner only)
+- POST   /api/groups/{id}/transfer                 -- transfer ownership (owner only)
+
+See app/models/groups.py for the schema and delete-behavior rationale
+(docs/planning/social.md US-5). This module owns create/join/leave, role
+authorization, and the group page aggregate.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.groups import Group, GroupMember, GroupRole
+from app.models.user import User
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+_NAME_MAX_LEN = 100
+_DESCRIPTION_MAX_LEN = 2000
+
+
+# ──────────────────────────── Pydantic schemas ────────────────────────────────
+
+
+class GroupCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=_NAME_MAX_LEN)
+    description: str | None = Field(default=None, max_length=_DESCRIPTION_MAX_LEN)
+
+    @field_validator("name")
+    @classmethod
+    def strip_name(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("name must not be blank")
+        return v
+
+    @field_validator("description")
+    @classmethod
+    def strip_description(cls, v: str | None) -> str | None:
+        if v is not None:
+            v = v.strip() or None
+        return v
+
+
+class GroupUpdate(BaseModel):
+    name: str | None = Field(default=None, min_length=1, max_length=_NAME_MAX_LEN)
+    description: str | None = Field(default=None, max_length=_DESCRIPTION_MAX_LEN)
+
+    @field_validator("name")
+    @classmethod
+    def strip_name(cls, v: str | None) -> str | None:
+        if v is not None:
+            v = v.strip()
+            if not v:
+                raise ValueError("name must not be blank")
+        return v
+
+    @field_validator("description")
+    @classmethod
+    def strip_description(cls, v: str | None) -> str | None:
+        if v is not None:
+            v = v.strip() or None
+        return v
+
+
+class GroupSummary(BaseModel):
+    id: int
+    name: str
+    description: str | None
+    owner_id: int | None
+    member_count: int
+    created_at: datetime
+
+
+class GroupListResponse(BaseModel):
+    groups: list[GroupSummary]
+    total: int
+
+
+class GroupMemberOut(BaseModel):
+    """Public-safe member entry -- no email or other private User fields."""
+
+    user_id: int
+    username: str
+    role: GroupRole
+    joined_at: datetime
+
+
+class GroupDetail(BaseModel):
+    id: int
+    name: str
+    description: str | None
+    owner_id: int | None
+    member_count: int
+    members: list[GroupMemberOut]
+    created_at: datetime
+
+
+class RoleUpdateRequest(BaseModel):
+    role: GroupRole
+
+    @field_validator("role")
+    @classmethod
+    def only_admin_or_member(cls, v: GroupRole) -> GroupRole:
+        if v == GroupRole.OWNER:
+            raise ValueError(
+                "cannot set role to owner directly -- use POST /transfer"
+            )
+        return v
+
+
+class TransferRequest(BaseModel):
+    new_owner_id: int
+
+
+class MembershipOut(BaseModel):
+    group_id: int
+    user_id: int
+    role: GroupRole
+    joined_at: datetime
+
+
+# ──────────────────────────────── Helpers ─────────────────────────────────────
+
+
+async def _get_group_or_404(db: AsyncSession, group_id: int) -> Group:
+    group = await db.get(Group, group_id)
+    if group is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Group not found")
+    return group
+
+
+async def _get_membership(db: AsyncSession, group_id: int, user_id: int) -> GroupMember | None:
+    result = await db.execute(
+        select(GroupMember).where(
+            GroupMember.group_id == group_id, GroupMember.user_id == user_id
+        )
+    )
+    return result.scalar_one_or_none()
+
+
+async def _member_count(db: AsyncSession, group_id: int) -> int:
+    result = await db.execute(
+        select(func.count()).select_from(GroupMember).where(GroupMember.group_id == group_id)
+    )
+    return int(result.scalar_one())
+
+
+def _require_role(membership: GroupMember | None, *allowed: GroupRole) -> None:
+    if membership is None or membership.role not in allowed:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You do not have permission to perform this action",
+        )
+
+
+# ──────────────────────────────── Endpoints ───────────────────────────────────
+
+
+@router.post("", response_model=GroupDetail, status_code=status.HTTP_201_CREATED)
+@router.post("/", response_model=GroupDetail, status_code=status.HTTP_201_CREATED, include_in_schema=False)
+async def create_group(
+    body: GroupCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Create a group. The creator becomes its owner."""
+    group = Group(name=body.name, description=body.description, owner_id=current_user.id)
+    db.add(group)
+    await db.flush()
+
+    db.add(GroupMember(group_id=group.id, user_id=current_user.id, role=GroupRole.OWNER))
+    await db.commit()
+    await db.refresh(group)
+
+    return GroupDetail(
+        id=group.id,
+        name=group.name,
+        description=group.description,
+        owner_id=group.owner_id,
+        member_count=1,
+        members=[
+            GroupMemberOut(
+                user_id=current_user.id,
+                username=current_user.username,
+                role=GroupRole.OWNER,
+                joined_at=group.created_at,
+            )
+        ],
+        created_at=group.created_at,
+    )
+
+
+@router.get("", response_model=GroupListResponse)
+@router.get("/", response_model=GroupListResponse, include_in_schema=False)
+async def list_groups(
+    current_user: CurrentUser,
+    db: DbDep,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=100),
+    mine: bool = Query(False, description="If true, only groups the caller is a member of"),
+):
+    """List groups, paginated. With ``mine=true``, restrict to the caller's own groups."""
+    base_query = select(Group)
+    count_query = select(func.count()).select_from(Group)
+
+    if mine:
+        base_query = base_query.join(
+            GroupMember, GroupMember.group_id == Group.id
+        ).where(GroupMember.user_id == current_user.id)
+        count_query = count_query.join(
+            GroupMember, GroupMember.group_id == Group.id
+        ).where(GroupMember.user_id == current_user.id)
+
+    total = (await db.execute(count_query)).scalar_one()
+
+    result = await db.execute(
+        base_query.order_by(Group.created_at.desc()).offset(skip).limit(limit)
+    )
+    groups = result.scalars().all()
+
+    summaries = []
+    for group in groups:
+        summaries.append(
+            GroupSummary(
+                id=group.id,
+                name=group.name,
+                description=group.description,
+                owner_id=group.owner_id,
+                member_count=await _member_count(db, group.id),
+                created_at=group.created_at,
+            )
+        )
+
+    return GroupListResponse(groups=summaries, total=total)
+
+
+@router.get("/{group_id}", response_model=GroupDetail)
+async def get_group(
+    group_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Group page: name, description, member count, and member list with roles."""
+    group = await _get_group_or_404(db, group_id)
+
+    result = await db.execute(
+        select(GroupMember, User.username)
+        .join(User, User.id == GroupMember.user_id)
+        .where(GroupMember.group_id == group_id)
+        .order_by(GroupMember.joined_at.asc())
+    )
+    rows = result.all()
+
+    members = [
+        GroupMemberOut(
+            user_id=gm.user_id,
+            username=username,
+            role=gm.role,
+            joined_at=gm.joined_at,
+        )
+        for gm, username in rows
+    ]
+
+    return GroupDetail(
+        id=group.id,
+        name=group.name,
+        description=group.description,
+        owner_id=group.owner_id,
+        member_count=len(members),
+        members=members,
+        created_at=group.created_at,
+    )
+
+
+@router.patch("/{group_id}", response_model=GroupDetail)
+async def update_group(
+    group_id: int,
+    body: GroupUpdate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Update name/description. Owner/admin only."""
+    group = await _get_group_or_404(db, group_id)
+    membership = await _get_membership(db, group_id, current_user.id)
+    _require_role(membership, GroupRole.OWNER, GroupRole.ADMIN)
+
+    if body.name is not None:
+        group.name = body.name
+    if body.description is not None:
+        group.description = body.description if body.description else None
+
+    await db.commit()
+    await db.refresh(group)
+
+    return await get_group(group_id, current_user, db)
+
+
+@router.delete("/{group_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_group(
+    group_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Delete a group. Owner only."""
+    group = await _get_group_or_404(db, group_id)
+    if group.owner_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Only the owner can delete this group",
+        )
+
+    await db.delete(group)
+    await db.commit()
+    return None
+
+
+@router.post("/{group_id}/join", response_model=MembershipOut)
+async def join_group(
+    group_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Join a group. Idempotent -- joining an already-joined group is a no-op."""
+    await _get_group_or_404(db, group_id)
+
+    existing = await _get_membership(db, group_id, current_user.id)
+    if existing is not None:
+        return MembershipOut(
+            group_id=group_id,
+            user_id=current_user.id,
+            role=existing.role,
+            joined_at=existing.joined_at,
+        )
+
+    membership = GroupMember(group_id=group_id, user_id=current_user.id, role=GroupRole.MEMBER)
+    db.add(membership)
+    await db.commit()
+    await db.refresh(membership)
+
+    return MembershipOut(
+        group_id=group_id,
+        user_id=current_user.id,
+        role=membership.role,
+        joined_at=membership.joined_at,
+    )
+
+
+@router.post("/{group_id}/leave", response_model=dict)
+async def leave_group(
+    group_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Leave a group. The owner cannot leave without transferring ownership first."""
+    await _get_group_or_404(db, group_id)
+    membership = await _get_membership(db, group_id, current_user.id)
+    if membership is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="You are not a member of this group",
+        )
+
+    if membership.role == GroupRole.OWNER:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Transfer ownership before leaving this group",
+        )
+
+    await db.delete(membership)
+    await db.commit()
+    return {"status": "ok"}
+
+
+@router.post("/{group_id}/members/{user_id}/role", response_model=MembershipOut)
+async def set_member_role(
+    group_id: int,
+    user_id: int,
+    body: RoleUpdateRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Set a member's role (admin/member). Owner only."""
+    group = await _get_group_or_404(db, group_id)
+    if group.owner_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Only the owner can change member roles",
+        )
+
+    target = await _get_membership(db, group_id, user_id)
+    if target is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Member not found")
+
+    if target.role == GroupRole.OWNER:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Use POST /transfer to change ownership",
+        )
+
+    target.role = body.role
+    await db.commit()
+    await db.refresh(target)
+
+    return MembershipOut(
+        group_id=group_id, user_id=user_id, role=target.role, joined_at=target.joined_at
+    )
+
+
+@router.post("/{group_id}/transfer", response_model=GroupDetail)
+async def transfer_ownership(
+    group_id: int,
+    body: TransferRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Transfer group ownership to another existing member. Owner only."""
+    group = await _get_group_or_404(db, group_id)
+    if group.owner_id != current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Only the owner can transfer ownership",
+        )
+
+    if body.new_owner_id == current_user.id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="You already own this group",
+        )
+
+    new_owner_membership = await _get_membership(db, group_id, body.new_owner_id)
+    if new_owner_membership is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="New owner must already be a member of this group",
+        )
+
+    current_owner_membership = await _get_membership(db, group_id, current_user.id)
+
+    new_owner_membership.role = GroupRole.OWNER
+    if current_owner_membership is not None:
+        current_owner_membership.role = GroupRole.ADMIN
+    group.owner_id = body.new_owner_id
+
+    await db.commit()
+
+    return await get_group(group_id, current_user, db)

backend/app/routers/internal.py

@@ -0,0 +1,146 @@
+"""Internal, dedicated-server-only content API.
+
+Implements `docs/architecture/world_persistence_impl.md` §7 + §8.3. This is
+how a spawned Godot dedicated server (`scripts/server.gd`, spawned by
+`app.services.game_servers`) pulls its world's content read-only over HTTP
+before binding its ENet port. Mounted at ``/api/internal`` -- a prefix that
+can also be blocked at the reverse proxy, per the doc's rejected-alternative
+note in §7.3.
+
+Gated by ``require_game_server`` (§7.3): a bearer token minted per spawn by
+``GameServerSupervisor._spawn`` and checked against
+``supervisor.validate_token(world_id, token)``. There is no user identity
+here at all -- these routes skip the per-user visibility check public
+routes apply, and apply no mature-content gating (gating is a client/user
+concern; the dedicated server still needs the geometry for collision).
+
+Read-only by construction: there is no write route here, and adding one
+would violate world_persistence_impl.md D2 (the FastAPI backend is the
+only writer).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Response
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.models.world import World
+from app.models.world_content import MAIN_ROOM_SLUG
+from app.services import chunk_codec
+from app.services.game_servers import supervisor
+from app.services.world_store import Bounds, WorldStore
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+async def require_game_server(
+    world_id: int,
+    authorization: Annotated[str | None, Header()] = None,
+) -> None:
+    """world_persistence_impl.md §7.3. A path whose ``world_id`` differs
+    from the token's world is 403 -- ``validate_token`` enforces that by
+    construction (it looks the token up *by* ``world_id``)."""
+    if not authorization or not authorization.lower().startswith("bearer "):
+        raise HTTPException(status_code=401, detail="missing bearer token")
+    token = authorization.split(" ", 1)[1].strip()
+    if not token or not supervisor.validate_token(world_id, token):
+        raise HTTPException(status_code=403, detail="invalid or expired server token")
+
+
+async def _get_world_or_404(world_id: int, db: AsyncSession) -> 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=404, detail="World not found")
+    return world
+
+
+async def _resolve_room(store: WorldStore, db: AsyncSession, world_id: int, slug: str):
+    room = await store.get_room(world_id, slug)
+    if room is None and slug == MAIN_ROOM_SLUG:
+        room = await store.get_or_create_main_room(world_id)
+        await db.commit()
+    return room
+
+
+@router.get("/worlds/{world_id}/manifest", dependencies=[Depends(require_game_server)])
+async def manifest(world_id: int, db: DbDep):
+    await _get_world_or_404(world_id, db)
+    store = WorldStore(db)
+    rooms = await store.list_rooms(world_id)
+    if not rooms:
+        rooms = [await store.get_or_create_main_room(world_id)]
+        await db.commit()
+
+    room_payloads = []
+    for r in rooms:
+        room_payloads.append({
+            "slug": r.slug, "name": r.name, "grid": r.grid, "bounds": r.bounds,
+            "spawn": r.spawn, "chunk_count": await store.count_chunks(r.id),
+        })
+
+    return {
+        "world_id": world_id,
+        "content_revision": await store.content_revision(world_id),
+        "rooms": room_payloads,
+    }
+
+
+@router.get("/worlds/{world_id}/rooms/{slug}/chunks", dependencies=[Depends(require_game_server)])
+async def internal_list_chunks(
+    world_id: int, slug: str, db: DbDep,
+    cx_min: int | None = None, cx_max: int | None = None,
+    cy_min: int | None = None, cy_max: int | None = None,
+    cz: int | None = None,
+):
+    await _get_world_or_404(world_id, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    bounds = Bounds(cx_min=cx_min, cx_max=cx_max, cy_min=cy_min, cy_max=cy_max, cz=cz)
+    chunks = await store.list_chunks(world_id, room.id, bounds)
+    return {
+        "room": room.slug,
+        "content_revision": await store.content_revision(world_id),
+        "chunks": [
+            {
+                "key": c.chunk_key, "cx": c.cx, "cy": c.cy, "cz": c.cz,
+                "revision": c.revision, "checksum": c.checksum, "payload_len": c.payload_len,
+                "is_mature": c.is_mature,
+                "updated_at": c.updated_at.isoformat() if c.updated_at else None,
+            }
+            for c in chunks
+        ],
+    }
+
+
+@router.get(
+    "/worlds/{world_id}/rooms/{slug}/chunks/{cx}/{cy}/{cz}",
+    dependencies=[Depends(require_game_server)],
+)
+async def internal_get_chunk(world_id: int, slug: str, cx: int, cy: int, cz: int, db: DbDep):
+    await _get_world_or_404(world_id, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    key = chunk_codec.build_key(world_id, slug, cx, cy, cz)
+    chunk = await store.get_chunk(key)
+    if chunk is None:
+        raise HTTPException(status_code=404, detail="chunk not found")
+
+    return Response(
+        content=chunk.payload, media_type="application/octet-stream",
+        headers={
+            "ETag": f'"{chunk.checksum}"', "X-Chunk-Revision": str(chunk.revision), "X-Chunk-Key": key,
+        },
+    )

backend/app/routers/presence.py

@@ -0,0 +1,146 @@
+"""Presence & status router.
+
+Endpoints:
+- POST  /api/presence/heartbeat  -- record a heartbeat (sets Redis TTL key)
+- GET   /api/presence/presence   -- query presence for a list of user ids
+- PATCH /api/presence/status     -- update the authenticated user's status message
+"""
+
+from datetime import datetime, timezone
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, status, Depends
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.user import User
+from app.services.presence import presence_store
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+# ──────────────────────────── Pydantic schemas ────────────────────────────────
+
+_STATUS_MAX_LEN = 140
+
+
+class HeartbeatRequest(BaseModel):
+    """Empty body -- the caller's identity comes from the JWT."""
+
+
+class PresenceUser(BaseModel):
+    user_id: int
+    is_online: bool
+    last_seen_at: datetime | None
+    status_message: str | None
+
+
+class PresenceResponse(BaseModel):
+    users: list[PresenceUser]
+
+
+class StatusUpdate(BaseModel):
+    status_message: str | None = Field(default=None, max_length=_STATUS_MAX_LEN)
+
+    @field_validator("status_message")
+    @classmethod
+    def strip_message(cls, v: str | None) -> str | None:
+        if v is not None:
+            v = v.strip()
+        return v
+
+
+# ──────────────────────────────── Endpoints ───────────────────────────────────
+
+
+@router.post("/heartbeat", response_model=dict)
+async def heartbeat(
+    _req: HeartbeatRequest,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Record a heartbeat for the authenticated user.
+
+    Sets a Redis key with a TTL so the server can derive online/offline
+    status without trusting client claims. Also persists last_seen_at to
+    the database.
+    """
+    # Update Redis TTL (presence heartbeat)
+    await presence_store.heartbeat(current_user.id)
+
+    # Persist last_seen_at to the database
+    now = datetime.now(timezone.utc)
+    result = await db.execute(select(User).where(User.id == current_user.id))
+    user = result.scalar_one_or_none()
+    if user:
+        user.last_seen_at = now
+        await db.commit()
+
+    return {"status": "ok", "user_id": current_user.id}
+
+
+@router.get("/presence", response_model=PresenceResponse)
+async def get_presence(
+    user_ids: str,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Return presence info for a comma-separated list of user ids.
+
+    Online/offline is derived from the Redis heartbeat TTL.
+    last_seen_at and status_message come from the database.
+    """
+    ids = [int(uid.strip()) for uid in user_ids.split(",") if uid.strip()]
+    if not ids:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="user_ids must contain at least one integer",
+        )
+
+    # Check Redis for online status (single round trip via MGET).
+    online_ids = await presence_store.is_online_batch(ids)
+
+    # Fetch DB records for last_seen_at and status_message
+    result = await db.execute(select(User).where(User.id.in_(ids)))
+    users = {u.id: u for u in result.scalars().all()}
+
+    presence_users = []
+    for uid in ids:
+        user = users.get(uid)
+        if user is None:
+            continue
+        presence_users.append(
+            PresenceUser(
+                user_id=uid,
+                is_online=uid in online_ids,
+                last_seen_at=user.last_seen_at,
+                status_message=user.status_message,
+            )
+        )
+
+    return PresenceResponse(users=presence_users)
+
+
+@router.patch("/status", response_model=dict)
+async def update_status(
+    body: StatusUpdate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Update the authenticated user's status message (length-limited)."""
+    result = await db.execute(select(User).where(User.id == current_user.id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+
+    user.status_message = body.status_message
+    await db.commit()
+
+    return {"status": "ok", "status_message": body.status_message}

backend/app/routers/social_friends.py

@@ -0,0 +1,362 @@
+"""Friends/follow/block router.
+
+docs/planning/social.md §4/§5 (US-1). Builds the request/accept/block
+business logic on top of the models in app/models/social.py (already
+merged): friend requests are directional (requester -> addressee) until
+accepted, at which point the relationship is treated as mutual; follow is
+one-way with no approval step; block is a hard deny that clears any
+existing friendship/follow between the two users and is queryable so a
+later layer (e.g. chat) can check it -- enforcing the block anywhere but
+here is out of scope for this router.
+
+Endpoints:
+- POST   /api/friends/requests                -- send a friend request
+- GET    /api/friends/requests                -- list incoming (pending) requests
+- POST   /api/friends/requests/{id}/accept    -- accept an incoming request
+- POST   /api/friends/requests/{id}/decline   -- decline an incoming request
+- DELETE /api/friends/{user_id}                -- unfriend
+- POST   /api/friends/{user_id}/follow         -- follow a user
+- DELETE /api/friends/{user_id}/follow         -- unfollow a user
+- POST   /api/friends/{user_id}/block          -- block a user
+- DELETE /api/friends/{user_id}/block          -- unblock a user
+- GET    /api/friends                          -- list friends
+- GET    /api/friends/following                -- list users followed
+- GET    /api/friends/blocked                  -- list blocked users
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, HTTPException, status, Depends
+from pydantic import BaseModel
+from sqlalchemy import select, delete, or_, and_
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.social import Friendship, Follow, Block, FriendshipStatus
+from app.models.user import User
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+# ──────────────────────────── Pydantic schemas ────────────────────────────────
+
+
+class FriendRequestCreate(BaseModel):
+    user_id: int
+
+
+class FriendRequestResponse(BaseModel):
+    id: int
+    requester_id: int
+    addressee_id: int
+    status: FriendshipStatus
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class UserSummary(BaseModel):
+    id: int
+    username: str
+
+    model_config = {"from_attributes": True}
+
+
+class FriendRequestListResponse(BaseModel):
+    requests: list[FriendRequestResponse]
+
+
+class FriendListResponse(BaseModel):
+    friends: list[UserSummary]
+
+
+class FollowListResponse(BaseModel):
+    following: list[UserSummary]
+
+
+class BlockedListResponse(BaseModel):
+    blocked: list[UserSummary]
+
+
+class ActionResponse(BaseModel):
+    status: str
+
+
+# ──────────────────────────────── Helpers ──────────────────────────────────────
+
+
+def _friendship_pair(a: int, b: int):
+    """SQLAlchemy predicate matching a Friendship row between a and b,
+    regardless of which one is the requester/addressee."""
+    return or_(
+        and_(Friendship.requester_id == a, Friendship.addressee_id == b),
+        and_(Friendship.requester_id == b, Friendship.addressee_id == a),
+    )
+
+
+def _follow_pair(a: int, b: int):
+    """Predicate matching a Follow row in either direction between a and b."""
+    return or_(
+        and_(Follow.follower_id == a, Follow.followed_id == b),
+        and_(Follow.follower_id == b, Follow.followed_id == a),
+    )
+
+
+async def _is_blocked_either_direction(db: AsyncSession, a: int, b: int) -> bool:
+    result = await db.execute(
+        select(Block.id).where(
+            or_(
+                and_(Block.blocker_id == a, Block.blocked_id == b),
+                and_(Block.blocker_id == b, Block.blocked_id == a),
+            )
+        )
+    )
+    return result.scalar_one_or_none() is not None
+
+
+async def _get_user_or_404(db: AsyncSession, user_id: int) -> User:
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    return user
+
+
+# ──────────────────────────────── Requests ─────────────────────────────────────
+
+
+@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
+    if target_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot send a friend request to yourself")
+
+    await _get_user_or_404(db, target_id)
+
+    if await _is_blocked_either_direction(db, current_user.id, target_id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Cannot send a friend request to this user")
+
+    existing = await db.execute(select(Friendship).where(_friendship_pair(current_user.id, target_id)))
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Friend request or friendship already exists")
+
+    fr = Friendship(requester_id=current_user.id, addressee_id=target_id)
+    db.add(fr)
+    try:
+        await db.commit()
+    except IntegrityError:
+        await db.rollback()
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Friend request or friendship already exists")
+    await db.refresh(fr)
+    return fr
+
+
+@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(
+            Friendship.addressee_id == current_user.id,
+            Friendship.status == FriendshipStatus.PENDING,
+        )
+    )
+    return FriendRequestListResponse(requests=list(result.scalars().all()))
+
+
+@router.post("/requests/{request_id}/accept", response_model=FriendRequestResponse)
+async def accept_friend_request(request_id: int, current_user: CurrentUser, db: DbDep):
+    """Accept an incoming friend request, making the friendship mutual."""
+    result = await db.execute(select(Friendship).where(Friendship.id == request_id))
+    fr = result.scalar_one_or_none()
+    # 404 (not a 403) both when the row doesn't exist and when it isn't
+    # addressed to the caller, so ids can't be enumerated to probe other
+    # accounts' pending requests.
+    if fr is None or fr.addressee_id != current_user.id or fr.status != FriendshipStatus.PENDING:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Friend request not found")
+
+    fr.status = FriendshipStatus.ACCEPTED
+    await db.commit()
+    await db.refresh(fr)
+    return fr
+
+
+@router.post("/requests/{request_id}/decline", response_model=ActionResponse)
+async def decline_friend_request(request_id: int, current_user: CurrentUser, db: DbDep):
+    """Decline (and remove) an incoming friend request."""
+    result = await db.execute(select(Friendship).where(Friendship.id == request_id))
+    fr = result.scalar_one_or_none()
+    if fr is None or fr.addressee_id != current_user.id or fr.status != FriendshipStatus.PENDING:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Friend request not found")
+
+    await db.delete(fr)
+    await db.commit()
+    return ActionResponse(status="declined")
+
+
+# ──────────────────────────────── Friends ──────────────────────────────────────
+
+
+@router.get("", response_model=FriendListResponse)
+async def list_friends(current_user: CurrentUser, db: DbDep):
+    """List the authenticated user's accepted friends."""
+    result = await db.execute(
+        select(Friendship).where(
+            or_(Friendship.requester_id == current_user.id, Friendship.addressee_id == current_user.id),
+            Friendship.status == FriendshipStatus.ACCEPTED,
+        )
+    )
+    friendships = result.scalars().all()
+    other_ids = [
+        fr.addressee_id if fr.requester_id == current_user.id else fr.requester_id
+        for fr in friendships
+    ]
+    if not other_ids:
+        return FriendListResponse(friends=[])
+
+    users_result = await db.execute(select(User).where(User.id.in_(other_ids)))
+    return FriendListResponse(friends=list(users_result.scalars().all()))
+
+
+@router.delete("/{user_id}", response_model=ActionResponse)
+async def unfriend(user_id: int, current_user: CurrentUser, db: DbDep):
+    """Remove an existing (accepted) friendship."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot unfriend yourself")
+
+    result = await db.execute(
+        select(Friendship).where(
+            _friendship_pair(current_user.id, user_id),
+            Friendship.status == FriendshipStatus.ACCEPTED,
+        )
+    )
+    fr = result.scalar_one_or_none()
+    if fr is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not friends with this user")
+
+    await db.delete(fr)
+    await db.commit()
+    return ActionResponse(status="unfriended")
+
+
+# ──────────────────────────────── Follow ───────────────────────────────────────
+
+
+@router.post("/{user_id}/follow", response_model=ActionResponse, status_code=status.HTTP_201_CREATED)
+async def follow_user(user_id: int, current_user: CurrentUser, db: DbDep):
+    """Follow another user (one-way, no approval)."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot follow yourself")
+
+    await _get_user_or_404(db, user_id)
+
+    if await _is_blocked_either_direction(db, current_user.id, user_id):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Cannot follow this user")
+
+    existing = await db.execute(
+        select(Follow).where(Follow.follower_id == current_user.id, Follow.followed_id == user_id)
+    )
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Already following this user")
+
+    db.add(Follow(follower_id=current_user.id, followed_id=user_id))
+    try:
+        await db.commit()
+    except IntegrityError:
+        await db.rollback()
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Already following this user")
+    return ActionResponse(status="followed")
+
+
+@router.delete("/{user_id}/follow", response_model=ActionResponse)
+async def unfollow_user(user_id: int, current_user: CurrentUser, db: DbDep):
+    """Unfollow a user."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot unfollow yourself")
+
+    result = await db.execute(
+        select(Follow).where(Follow.follower_id == current_user.id, Follow.followed_id == user_id)
+    )
+    follow = result.scalar_one_or_none()
+    if follow is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not following this user")
+
+    await db.delete(follow)
+    await db.commit()
+    return ActionResponse(status="unfollowed")
+
+
+@router.get("/following", response_model=FollowListResponse)
+async def list_following(current_user: CurrentUser, db: DbDep):
+    """List users the authenticated user follows."""
+    result = await db.execute(select(Follow).where(Follow.follower_id == current_user.id))
+    followed_ids = [f.followed_id for f in result.scalars().all()]
+    if not followed_ids:
+        return FollowListResponse(following=[])
+
+    users_result = await db.execute(select(User).where(User.id.in_(followed_ids)))
+    return FollowListResponse(following=list(users_result.scalars().all()))
+
+
+# ──────────────────────────────── Block ────────────────────────────────────────
+
+
+@router.post("/{user_id}/block", response_model=ActionResponse, status_code=status.HTTP_201_CREATED)
+async def block_user(user_id: int, current_user: CurrentUser, db: DbDep):
+    """Block a user: hard deny that also clears any existing friendship/follow
+    between the two users in either direction."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot block yourself")
+
+    await _get_user_or_404(db, user_id)
+
+    existing = await db.execute(
+        select(Block).where(Block.blocker_id == current_user.id, Block.blocked_id == user_id)
+    )
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="User already blocked")
+
+    db.add(Block(blocker_id=current_user.id, blocked_id=user_id))
+    await db.execute(delete(Friendship).where(_friendship_pair(current_user.id, user_id)))
+    await db.execute(delete(Follow).where(_follow_pair(current_user.id, user_id)))
+
+    try:
+        await db.commit()
+    except IntegrityError:
+        await db.rollback()
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="User already blocked")
+    return ActionResponse(status="blocked")
+
+
+@router.delete("/{user_id}/block", response_model=ActionResponse)
+async def unblock_user(user_id: int, current_user: CurrentUser, db: DbDep):
+    """Remove a block."""
+    if user_id == current_user.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot unblock yourself")
+
+    result = await db.execute(
+        select(Block).where(Block.blocker_id == current_user.id, Block.blocked_id == user_id)
+    )
+    block = result.scalar_one_or_none()
+    if block is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User is not blocked")
+
+    await db.delete(block)
+    await db.commit()
+    return ActionResponse(status="unblocked")
+
+
+@router.get("/blocked", response_model=BlockedListResponse)
+async def list_blocked(current_user: CurrentUser, db: DbDep):
+    """List users the authenticated user has blocked."""
+    result = await db.execute(select(Block).where(Block.blocker_id == current_user.id))
+    blocked_ids = [b.blocked_id for b in result.scalars().all()]
+    if not blocked_ids:
+        return BlockedListResponse(blocked=[])
+
+    users_result = await db.execute(select(User).where(User.id.in_(blocked_ids)))
+    return BlockedListResponse(blocked=list(users_result.scalars().all()))

backend/app/routers/users.py

@@ -0,0 +1,106 @@
+"""User management router."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, EmailStr
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.user import User
+
+router = APIRouter()
+
+
+# ─── Pydantic schemas ────────────────────────────────────────────────────────
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    is_active: bool
+
+    model_config = {"from_attributes": True}
+
+
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    is_active: bool | None = None
+
+
+# ─── Endpoints ───────────────────────────────────────────────────────────────
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user_profile(
+    current_user: CurrentUser,
+):
+    """Get the currently authenticated user's profile."""
+    return current_user
+
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(
+    user_id: int,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Get a user by ID.  Only the owner can view their own profile."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Only the owner may view their own profile.
+    if user.id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to view this user")
+
+    return user
+
+
+@router.patch("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    user_update: UserUpdate,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Update a user.  Only the owner can update their own account."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Only the owner may update their own account.
+    if user.id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to update this user")
+
+    if user_update.email is not None:
+        user.email = user_update.email
+    if user_update.is_active is not None:
+        user.is_active = user_update.is_active
+
+    await db.commit()
+    await db.refresh(user)
+    return user
+
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_user(
+    user_id: int,
+    current_user: CurrentUser,
+    db: Annotated[AsyncSession, Depends(get_db)],
+):
+    """Delete a user.  Only the owner can delete their own account."""
+    result = await db.execute(select(User).where(User.id == user_id))
+    user = result.scalar_one_or_none()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    # Only the owner may delete their own account.
+    if user.id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not authorized to delete this user")
+
+    await db.delete(user)
+    await db.commit()

backend/app/routers/world_content.py

@@ -0,0 +1,451 @@
+"""World content router -- rooms + chunks, for the editor and player client.
+
+Implements `docs/architecture/world_persistence_impl.md` §8.1. JWT-authenticated
+(``CurrentUser``, same as ``app/routers/worlds.py``). All chunk content
+reads/writes go through ``WorldStore``; this module is HTTP plumbing +
+authorization only.
+
+Authorization (doc §5.3):
+ - **Read** (world visibility, room listing, chunk fetch/index/revisions):
+   same rule as ``GET /api/worlds/{id}`` -- 404 (not 403) if the world is
+   neither PUBLIC nor owned by the caller. See ``_get_world_readable``.
+ - **Write** (room create, chunk PUT/DELETE/rollback): caller must be
+   ``world.owner_id``, matching ``update_world`` -- 403 otherwise, with
+   *no* visibility gate (this deliberately mirrors ``update_world``, which
+   also has no visibility check; see ``_get_world_writable``).
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.user import User
+from app.models.world import World, WorldVisibility
+from app.models.world_content import MAIN_ROOM_SLUG, WorldRoom
+from app.services import chunk_codec
+from app.services.game_servers import supervisor
+from app.services.world_store import Bounds, RevisionConflict, RevisionNotAvailable, WorldStore
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+# world_persistence_impl.md §8.1: "Bounds are capped (default 32x32 chunks
+# per query) and return 422 beyond that."
+MAX_BOUNDS_SPAN = 32
+# §8.1 batch write cap, beyond WORLD_CHUNK_MAX_BATCH chunks: "Capped at ...
+# 8 MB."
+MAX_BATCH_TOTAL_BYTES = 8 * 1024 * 1024
+
+
+# ─────────────────────────── auth helpers ───────────────────────────
+
+async def _get_world_readable(world_id: int, current_user: User, db: AsyncSession) -> 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=404, detail="World not found")
+    if world.visibility != WorldVisibility.PUBLIC and world.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="World not found")
+    return world
+
+
+async def _get_world_writable(world_id: int, current_user: User, db: AsyncSession) -> 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=404, detail="World not found")
+    if world.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not owner of this world")
+    return world
+
+
+async def _resolve_room(store: WorldStore, db: AsyncSession, world_id: int, slug: str) -> WorldRoom | None:
+    """world_persistence_impl.md §4.1: lazily create the main room for
+    worlds that predate this feature, on first read/write."""
+    room = await store.get_room(world_id, slug)
+    if room is None and slug == MAIN_ROOM_SLUG:
+        room = await store.get_or_create_main_room(world_id)
+        await db.commit()
+    return room
+
+
+def _is_live(world_id: int) -> bool:
+    return any(s["world_id"] == str(world_id) for s in supervisor.debug_state())
+
+
+def _validation_error_body(exc: chunk_codec.ChunkValidationError) -> dict:
+    return {"detail": "chunk validation failed", "reason": exc.reason}
+
+
+def _conflict_body(exc: RevisionConflict) -> dict:
+    body: dict = {
+        "detail": "revision conflict",
+        "current_revision": exc.current_revision,
+        "current_checksum": exc.current_checksum,
+    }
+    if exc.coord is not None:
+        body["coord"] = list(exc.coord)
+    return body
+
+
+# ─────────────────────────── schemas ───────────────────────────
+
+class RoomResponse(BaseModel):
+    id: int
+    slug: str
+    name: str
+    grid: dict
+    bounds: dict | None
+    spawn: dict | None
+    chunk_count: int
+
+
+class RoomCreate(BaseModel):
+    slug: str = Field(..., min_length=1, max_length=64, pattern=r"^[a-z0-9_-]+$")
+    name: str = Field(..., min_length=1, max_length=255)
+    grid: dict | None = None
+    bounds: dict | None = None
+    spawn: dict | None = None
+
+
+# ─────────────────────────── rooms ───────────────────────────
+
+@router.get("/{world_id}/rooms", response_model=list[RoomResponse])
+async def list_rooms(world_id: int, current_user: CurrentUser, db: DbDep):
+    await _get_world_readable(world_id, current_user, db)
+    store = WorldStore(db)
+    rooms = await store.list_rooms(world_id)
+    if not rooms:
+        rooms = [await store.get_or_create_main_room(world_id)]
+        await db.commit()
+    return [
+        RoomResponse(
+            id=r.id, slug=r.slug, name=r.name, grid=r.grid, bounds=r.bounds, spawn=r.spawn,
+            chunk_count=await store.count_chunks(r.id),
+        )
+        for r in rooms
+    ]
+
+
+@router.post("/{world_id}/rooms", response_model=RoomResponse, status_code=201)
+async def create_room(world_id: int, body: RoomCreate, current_user: CurrentUser, db: DbDep):
+    await _get_world_writable(world_id, current_user, db)
+    store = WorldStore(db)
+    if await store.get_room(world_id, body.slug) is not None:
+        raise HTTPException(status_code=409, detail="a room with this slug already exists")
+    room = await store.create_room(
+        world_id, body.slug, body.name, grid=body.grid, bounds=body.bounds, spawn=body.spawn
+    )
+    await db.commit()
+    await db.refresh(room)
+    return RoomResponse(
+        id=room.id, slug=room.slug, name=room.name, grid=room.grid,
+        bounds=room.bounds, spawn=room.spawn, chunk_count=0,
+    )
+
+
+# ─────────────────────────── chunk index ───────────────────────────
+
+@router.get("/{world_id}/rooms/{slug}/chunks")
+async def list_chunks(
+    world_id: int, slug: str, current_user: CurrentUser, db: DbDep,
+    cx_min: int | None = None, cx_max: int | None = None,
+    cy_min: int | None = None, cy_max: int | None = None,
+    cz: int | None = None,
+):
+    await _get_world_readable(world_id, current_user, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    if cx_min is not None and cx_max is not None and (cx_max - cx_min + 1) > MAX_BOUNDS_SPAN:
+        raise HTTPException(status_code=422, detail=f"cx bounds span exceeds {MAX_BOUNDS_SPAN}")
+    if cy_min is not None and cy_max is not None and (cy_max - cy_min + 1) > MAX_BOUNDS_SPAN:
+        raise HTTPException(status_code=422, detail=f"cy bounds span exceeds {MAX_BOUNDS_SPAN}")
+
+    bounds = Bounds(cx_min=cx_min, cx_max=cx_max, cy_min=cy_min, cy_max=cy_max, cz=cz)
+    chunks = await store.list_chunks(world_id, room.id, bounds)
+    content_revision = await store.content_revision(world_id)
+    return {
+        "room": room.slug,
+        "content_revision": content_revision,
+        "chunks": [
+            {
+                "key": c.chunk_key, "cx": c.cx, "cy": c.cy, "cz": c.cz,
+                "revision": c.revision, "checksum": c.checksum, "payload_len": c.payload_len,
+                "is_mature": c.is_mature,
+                "updated_at": c.updated_at.isoformat() if c.updated_at else None,
+            }
+            for c in chunks
+        ],
+    }
+
+
+# ─────────────────────────── chunk fetch ───────────────────────────
+
+@router.get("/{world_id}/rooms/{slug}/chunks/{cx}/{cy}/{cz}")
+async def get_chunk(
+    world_id: int, slug: str, cx: int, cy: int, cz: int,
+    current_user: CurrentUser, db: DbDep,
+    accept: Annotated[str | None, Header()] = None,
+    if_none_match: Annotated[str | None, Header(alias="If-None-Match")] = None,
+):
+    await _get_world_readable(world_id, current_user, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    key = chunk_codec.build_key(world_id, slug, cx, cy, cz)
+    chunk = await store.get_chunk(key)
+    if chunk is None:
+        raise HTTPException(status_code=404, detail="chunk not found")
+
+    etag = f'"{chunk.checksum}"'
+    headers = {"ETag": etag, "X-Chunk-Revision": str(chunk.revision), "X-Chunk-Key": key}
+
+    if if_none_match is not None and if_none_match.strip('"') == chunk.checksum:
+        return Response(status_code=304, headers=headers)
+
+    wants_json = (
+        accept is not None
+        and "application/json" in accept
+        and "application/octet-stream" not in accept
+    )
+    if wants_json:
+        decoded = chunk_codec.decode_binary(chunk.payload)
+        body = chunk_codec.to_json_dict(decoded, key=key, chunk_checksum=chunk.checksum)
+        return JSONResponse(content=body, headers=headers)
+
+    return Response(content=chunk.payload, media_type="application/octet-stream", headers=headers)
+
+
+# ─────────────────────────── chunk write ───────────────────────────
+
+async def _read_write_payload(request: Request, x_base_revision: int | None) -> tuple[bytes, int]:
+    content_type = request.headers.get("content-type", "")
+    if "application/json" in content_type:
+        body = await request.json()
+        try:
+            payload_bytes = base64.b64decode(body["payload_b64"], validate=True)
+        except (KeyError, binascii.Error, ValueError) as exc:
+            raise HTTPException(status_code=422, detail=f"invalid payload_b64: {exc}")
+        base_revision = int(body.get("base_revision", 0))
+        return payload_bytes, base_revision
+    payload_bytes = await request.body()
+    return payload_bytes, (x_base_revision if x_base_revision is not None else 0)
+
+
+@router.put("/{world_id}/rooms/{slug}/chunks/{cx}/{cy}/{cz}")
+async def put_chunk(
+    world_id: int, slug: str, cx: int, cy: int, cz: int,
+    request: Request, current_user: CurrentUser, db: DbDep,
+    x_base_revision: Annotated[int | None, Header(alias="X-Base-Revision")] = None,
+):
+    await _get_world_writable(world_id, current_user, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    payload_bytes, base_revision = await _read_write_payload(request, x_base_revision)
+    if len(payload_bytes) > settings.WORLD_CHUNK_MAX_PAYLOAD_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"payload exceeds WORLD_CHUNK_MAX_PAYLOAD_BYTES ({settings.WORLD_CHUNK_MAX_PAYLOAD_BYTES})",
+        )
+
+    try:
+        chunk = await store.put_chunk(
+            room=room, cx=cx, cy=cy, cz=cz, payload_bytes=payload_bytes,
+            base_revision=base_revision, actor_id=current_user.id,
+        )
+    except chunk_codec.ChunkCodecError as exc:
+        await db.rollback()
+        return JSONResponse(status_code=422, content={"detail": "chunk decode failed", "reason": "malformed", "message": str(exc)})
+    except chunk_codec.ChunkValidationError as exc:
+        await db.rollback()
+        return JSONResponse(status_code=422, content=_validation_error_body(exc))
+    except RevisionConflict as exc:
+        # Nothing must stick from a failed write. Returning a JSONResponse
+        # here (rather than raising) means no exception propagates through
+        # `get_db`, so this rollback has to be explicit -- see the note on
+        # the batch endpoint below, where this is load-bearing for
+        # all-or-nothing semantics.
+        await db.rollback()
+        return JSONResponse(status_code=409, content=_conflict_body(exc))
+
+    await db.commit()
+    await db.refresh(chunk)
+
+    return {
+        "key": chunk.chunk_key, "revision": chunk.revision, "checksum": chunk.checksum,
+        "payload_len": chunk.payload_len,
+        "updated_at": chunk.updated_at.isoformat() if chunk.updated_at else None,
+        "is_mature": chunk.is_mature, "live_session": _is_live(world_id),
+    }
+
+
+# ─────────────────────────── batch write ───────────────────────────
+
+class BatchChunkItem(BaseModel):
+    cx: int
+    cy: int
+    cz: int
+    base_revision: int
+    payload_b64: str
+
+
+class BatchPutRequest(BaseModel):
+    chunks: list[BatchChunkItem]
+
+
+@router.put("/{world_id}/rooms/{slug}/chunks")
+async def put_chunks_batch(
+    world_id: int, slug: str, body: BatchPutRequest, current_user: CurrentUser, db: DbDep,
+):
+    await _get_world_writable(world_id, current_user, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    if len(body.chunks) > settings.WORLD_CHUNK_MAX_BATCH:
+        raise HTTPException(
+            status_code=422,
+            detail=f"batch of {len(body.chunks)} exceeds WORLD_CHUNK_MAX_BATCH ({settings.WORLD_CHUNK_MAX_BATCH})",
+        )
+
+    items = []
+    total_bytes = 0
+    for item in body.chunks:
+        try:
+            payload_bytes = base64.b64decode(item.payload_b64, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise HTTPException(status_code=422, detail=f"invalid payload_b64 for ({item.cx},{item.cy},{item.cz}): {exc}")
+        total_bytes += len(payload_bytes)
+        items.append({
+            "cx": item.cx, "cy": item.cy, "cz": item.cz,
+            "base_revision": item.base_revision, "payload_bytes": payload_bytes,
+        })
+
+    if total_bytes > MAX_BATCH_TOTAL_BYTES:
+        raise HTTPException(status_code=413, detail=f"batch exceeds {MAX_BATCH_TOTAL_BYTES} bytes")
+
+    try:
+        rows = await store.put_chunks_batch(room=room, items=items, actor_id=current_user.id)
+    except chunk_codec.ChunkCodecError as exc:
+        # All-or-nothing (world_persistence_impl.md §8.1): earlier items in
+        # this batch may already be flushed (but never committed) to this
+        # transaction. Rolling back here is what actually makes the batch
+        # atomic -- without it, returning a JSONResponse instead of raising
+        # means no exception reaches `get_db`, and its own transaction
+        # handling would otherwise commit those earlier writes anyway.
+        await db.rollback()
+        return JSONResponse(status_code=422, content={"detail": "chunk decode failed", "reason": "malformed", "message": str(exc)})
+    except chunk_codec.ChunkValidationError as exc:
+        await db.rollback()
+        return JSONResponse(status_code=422, content=_validation_error_body(exc))
+    except RevisionConflict as exc:
+        await db.rollback()
+        return JSONResponse(status_code=409, content=_conflict_body(exc))
+
+    await db.commit()
+    for row in rows:
+        await db.refresh(row)
+
+    return {
+        "live_session": _is_live(world_id),
+        "chunks": [
+            {
+                "key": r.chunk_key, "revision": r.revision, "checksum": r.checksum,
+                "payload_len": r.payload_len,
+                "updated_at": r.updated_at.isoformat() if r.updated_at else None,
+                "is_mature": r.is_mature,
+            }
+            for r in rows
+        ],
+    }
+
+
+# ─────────────────────────── delete ───────────────────────────
+
+@router.delete("/{world_id}/rooms/{slug}/chunks/{cx}/{cy}/{cz}", status_code=204)
+async def delete_chunk(
+    world_id: int, slug: str, cx: int, cy: int, cz: int, current_user: CurrentUser, db: DbDep,
+):
+    await _get_world_writable(world_id, current_user, db)
+    store = WorldStore(db)
+    room = await _resolve_room(store, db, world_id, slug)
+    if room is None:
+        raise HTTPException(status_code=404, detail="room not found")
+
+    key = chunk_codec.build_key(world_id, slug, cx, cy, cz)
+    await store.delete_chunk(key, current_user.id)
+    await db.commit()
+    return Response(status_code=204)
+
+
+# ─────────────────────────── revisions + rollback ───────────────────────────
+
+@router.get("/{world_id}/rooms/{slug}/chunks/{cx}/{cy}/{cz}/revisions")
+async def chunk_revisions(
+    world_id: int, slug: str, cx: int, cy: int, cz: int, current_user: CurrentUser, db: DbDep,
+):
+    # doc: "(owner)" -- same gate as writes.
+    await _get_world_writable(world_id, current_user, db)
+    store = WorldStore(db)
+    key = chunk_codec.build_key(world_id, slug, cx, cy, cz)
+    revisions = await store.list_revisions(key)
+    return [
+        {
+            "revision": r.revision, "action": r.action, "actor_id": r.actor_id,
+            "checksum": r.checksum, "payload_available": r.payload is not None,
+            "created_at": r.created_at.isoformat() if r.created_at else None,
+        }
+        for r in revisions
+    ]
+
+
+class RollbackRequest(BaseModel):
+    revision: int
+
+
+@router.post("/{world_id}/rooms/{slug}/chunks/{cx}/{cy}/{cz}/rollback")
+async def rollback_chunk(
+    world_id: int, slug: str, cx: int, cy: int, cz: int,
+    body: RollbackRequest, current_user: CurrentUser, db: DbDep,
+):
+    await _get_world_writable(world_id, current_user, db)
+    store = WorldStore(db)
+    key = chunk_codec.build_key(world_id, slug, cx, cy, cz)
+    try:
+        chunk = await store.rollback_chunk(key, body.revision, current_user.id)
+    except RevisionNotAvailable as exc:
+        await db.rollback()
+        return JSONResponse(status_code=404, content={"detail": str(exc)})
+    except chunk_codec.ChunkValidationError as exc:
+        await db.rollback()
+        return JSONResponse(status_code=422, content=_validation_error_body(exc))
+
+    await db.commit()
+    await db.refresh(chunk)
+    return {
+        "key": chunk.chunk_key, "revision": chunk.revision, "checksum": chunk.checksum,
+        "payload_len": chunk.payload_len,
+        "updated_at": chunk.updated_at.isoformat() if chunk.updated_at else None,
+        "is_mature": chunk.is_mature, "live_session": _is_live(world_id),
+    }

backend/app/routers/worlds.py

@@ -0,0 +1,212 @@
+"""Worlds router - CRUD for game worlds."""
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.database import get_db
+from app.dependencies import CurrentUser
+from app.models.world import World, WorldVisibility
+from app.services.game_servers import supervisor
+from app.services.world_store import WorldStore
+
+router = APIRouter()
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+
+
+# --- Pydantic schemas ---
+
+class WorldCreate(BaseModel):
+    """Schema for creating a world."""
+    name: str = Field(..., min_length=1, max_length=255)
+    description: str | None = None
+    visibility: WorldVisibility = WorldVisibility.PUBLIC
+
+
+class WorldUpdate(BaseModel):
+    """Schema for updating a world."""
+    name: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = None
+    visibility: WorldVisibility | None = None
+
+
+class WorldResponse(BaseModel):
+    """Schema for world responses."""
+    id: int
+    name: str
+    description: str | None
+    visibility: WorldVisibility
+    owner_id: int
+    created_at: datetime | None = None
+
+    model_config = {"from_attributes": True}
+
+
+# --- Endpoints ---
+
+@router.get("/", response_model=list[WorldResponse])
+async def list_worlds(
+    current_user: CurrentUser,
+    db: DbDep,
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=100),
+    visibility: WorldVisibility | None = None,
+):
+    """List worlds visible to the current user.
+
+    PUBLIC worlds are visible to everyone.
+    PRIVATE/FRIENDS_ONLY worlds are visible to their owner.
+    """
+    query = select(World).options(selectinload(World.owner))
+
+    # Filter by visibility if specified
+    if visibility:
+        query = query.where(World.visibility == visibility)
+        if visibility != WorldVisibility.PUBLIC:
+            # Requesting a non-public visibility explicitly must not bypass
+            # ownership — otherwise any authenticated user could list every
+            # PRIVATE/FRIENDS_ONLY world in the system just by passing the
+            # filter, defeating the point of the check below.
+            query = query.where(World.owner_id == current_user.id)
+    else:
+        # Show PUBLIC worlds + owner's own worlds
+        query = query.where(
+            (World.visibility == WorldVisibility.PUBLIC)
+            | (World.owner_id == current_user.id)
+        )
+
+    query = query.offset(skip).limit(limit).order_by(World.created_at.desc())
+    result = await db.execute(query)
+    worlds = result.scalars().all()
+    return worlds
+
+
+@router.get("/{world_id}", response_model=WorldResponse)
+async def get_world(
+    world_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Get a single world by ID, respecting visibility."""
+    result = await db.execute(
+        select(World).where(World.id == world_id).options(selectinload(World.owner))
+    )
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    # Allow access if world is PUBLIC or owned by current user
+    if world.visibility != WorldVisibility.PUBLIC and world.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    return world
+
+
+class JoinResponse(BaseModel):
+    """Address of the dedicated server hosting this world."""
+    world_id: int
+    host: str
+    port: int
+
+
+@router.post("/{world_id}/join", response_model=JoinResponse)
+async def join_world(
+    world_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Ensure a dedicated game server is running for this world and return its
+    ENet address for the client to connect to.
+
+    503 if game-server orchestration isn't enabled on this backend (e.g. a
+    plain dev/test instance with no Godot binary).
+    """
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+    if world.visibility != WorldVisibility.PUBLIC and world.owner_id != current_user.id:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    try:
+        info = await supervisor.ensure_server(str(world_id))
+    except RuntimeError as exc:
+        raise HTTPException(status_code=503, detail=str(exc))
+
+    return JoinResponse(world_id=world_id, host=info["host"], port=info["port"])
+
+
+@router.post("/", response_model=WorldResponse, status_code=201)
+async def create_world(
+    world_data: WorldCreate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Create a new world.
+
+    Also creates the world's "main" room (world_persistence_impl.md §4.1) --
+    every world gets one so chunk content has somewhere to live from the
+    start.
+    """
+    world = World(
+        name=world_data.name,
+        description=world_data.description,
+        owner_id=current_user.id,
+        visibility=world_data.visibility,
+    )
+    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)
+    await db.commit()
+    await db.refresh(world)
+    return world
+
+
+@router.put("/{world_id}", response_model=WorldResponse)
+async def update_world(
+    world_id: int,
+    world_data: WorldUpdate,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Update an existing world."""
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    if world.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    update_data = world_data.model_dump(exclude_unset=True)
+    for field, value in update_data.items():
+        setattr(world, field, value)
+
+    await db.commit()
+    await db.refresh(world)
+    return world
+
+
+@router.delete("/{world_id}", status_code=204)
+async def delete_world(
+    world_id: int,
+    current_user: CurrentUser,
+    db: DbDep,
+):
+    """Delete a world."""
+    result = await db.execute(select(World).where(World.id == world_id))
+    world = result.scalar_one_or_none()
+    if not world:
+        raise HTTPException(status_code=404, detail="World not found")
+
+    if world.owner_id != current_user.id:
+        raise HTTPException(status_code=403, detail="Not owner of this world")
+
+    await db.delete(world)
+    await db.commit()

backend/app/services/chunk_codec.py

@@ -0,0 +1,676 @@
+"""Python port of the chunk binary/JSON codec, `docs/architecture/world.md` §3.
+
+This is the server-side half of the "single shared format, two
+implementations" contract world.md §5.2 and
+`world_persistence_impl.md` §5.5/§9 call for. The Godot-side implementation
+is `scripts/chunk_data_decoder.gd`; this module must decode anything it
+produces and produce bytes it can decode.
+
+IMPORTANT DEVIATION (see the "Known cross-codec divergence" note at the
+bottom of this file): the current `scripts/chunk_data_decoder.gd` does not
+actually implement IEEE-754 float32 for the `pos`/`rot`/`scale`/`bounds`
+fields -- it performs a lossy numeric `int`/`float` cast instead of a bit
+reinterpretation, which both truncates fractional values and does not
+write IEEE-754 bits at all. This module implements the format as
+*specified* (real `<f` IEEE-754 float32, matching every other field in the
+spec and matching what any conformant decoder would assume). See the note
+for what this means for cross-codec byte parity today.
+
+Nothing here talks to a database or the FastAPI app; it is a pure,
+side-effect-free codec so it can be golden-file tested in isolation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import struct
+from dataclasses import dataclass, field
+
+MAGIC = b"AGPC"
+HEADER_SIZE = 48
+CURRENT_VERSION = 1
+
+SECTION_META = 0x01
+SECTION_TILE = 0x02
+SECTION_OBJECT = 0x03
+SECTION_FLAGS = 0x04
+SECTION_REVISION_META = 0x05
+
+CATEGORY_FIELDS = (
+    "violence", "sexual", "language", "substance",
+    "gambling", "horror", "hate", "custom",
+)
+
+
+class ChunkCodecError(Exception):
+    """Malformed bytes -- the payload isn't shaped like a chunk at all."""
+
+
+class ChunkValidationError(Exception):
+    """A structurally-valid chunk failed a content/business-rule check.
+
+    ``reason`` is the machine-readable code the API surface (world_persistence_impl.md
+    §8.1) puts in the 422 response body's ``reason`` field, e.g.
+    ``"checksum_mismatch"``, ``"layer_dims"``, ``"object_out_of_bounds"``.
+    """
+
+    def __init__(self, reason: str, message: str | None = None) -> None:
+        self.reason = reason
+        super().__init__(message or reason)
+
+
+# ───────────────────────── Logical model ─────────────────────────
+
+@dataclass
+class TileDef:
+    id: int
+    asset_id: str = ""
+    solid: bool = False
+    flags: int = 0
+    variants: int = 1
+
+
+@dataclass
+class TileLayer:
+    name: str
+    layer_id: int = 0
+    width: int = 0
+    height: int = 0
+    depth: int = 1
+    palette: list[TileDef] = field(default_factory=list)
+    tiles: list[int] = field(default_factory=list)  # flattened, row-major
+
+
+@dataclass
+class ContentFlags:
+    violence: int = 0
+    sexual: int = 0
+    language: int = 0
+    substance: int = 0
+    gambling: int = 0
+    horror: int = 0
+    hate: int = 0
+    custom: int = 0
+    mature: bool = False
+    sources: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "categories": {name: getattr(self, name) for name in CATEGORY_FIELDS},
+            "mature": self.mature,
+            "sources": list(self.sources),
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ContentFlags":
+        cats = d.get("categories", {})
+        return cls(
+            **{name: int(cats.get(name, 0)) for name in CATEGORY_FIELDS},
+            mature=bool(d.get("mature", False)),
+            sources=list(d.get("sources", [])),
+        )
+
+
+@dataclass
+class WorldObject:
+    id: str
+    type: str
+    asset_id: str
+    pos: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    rot: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 1.0)
+    scale: tuple[float, float, float] = (1.0, 1.0, 1.0)
+    dynamic: bool = False
+    properties: dict = field(default_factory=dict)
+    flags: ContentFlags = field(default_factory=ContentFlags)
+
+
+@dataclass
+class ChunkBounds:
+    """Stored here as min-corner + size (matching the Godot client's AABB
+    type) for convenience, but the §3.6 BINARY wire format is min + max
+    (world.md §3.1, and the client's actual ChunkDataDecoder) -- fixed
+    2026-09-14 after a real client/server interop test caught this class's
+    original binary codec writing min+size on the wire, which the client
+    decoder (unaware of the "size" convention) read as a second min/max
+    pair, corrupting every chunk's bounds. The two representations are
+    fully recoverable from each other; `max` below is computed for exactly
+    this reason."""
+
+    min: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    size: tuple[float, float, float] = (0.0, 0.0, 0.0)
+
+    @property
+    def max(self) -> tuple[float, float, float]:
+        return tuple(a + b for a, b in zip(self.min, self.size))
+
+
+@dataclass
+class ChunkPayload:
+    version: int = CURRENT_VERSION
+    world_id: str = ""
+    room_id: str = ""
+    coord: tuple[int, int, int] = (0, 0, 0)
+    bounds: ChunkBounds = field(default_factory=ChunkBounds)
+    tile_layers: list[TileLayer] = field(default_factory=list)
+    objects: list[WorldObject] = field(default_factory=list)
+    flags: ContentFlags = field(default_factory=ContentFlags)
+    created_at: int = 0
+    updated_at: int = 0
+    revision: int = 0
+    author: str = ""
+
+
+def build_key(world_id: str | int, room_slug: str, cx: int, cy: int, cz: int) -> str:
+    """world_persistence_impl.md §4.5: ``"{world.id}:{room.slug}:{cx}:{cy}:{cz}"``."""
+    return f"{world_id}:{room_slug}:{cx}:{cy}:{cz}"
+
+
+# ───────────────────────── Binary primitives ─────────────────────────
+# All integers little-endian, matching world.md §3.6.3. Floats are packed
+# as real IEEE-754 float32 -- see the module docstring's deviation note.
+
+def _read_u16(data: bytes, off: int) -> int:
+    return struct.unpack_from("<H", data, off)[0]
+
+
+def _read_u32(data: bytes, off: int) -> int:
+    return struct.unpack_from("<I", data, off)[0]
+
+
+def _read_i32(data: bytes, off: int) -> int:
+    return struct.unpack_from("<i", data, off)[0]
+
+
+def _read_i64(data: bytes, off: int) -> int:
+    return struct.unpack_from("<q", data, off)[0]
+
+
+def _read_f32(data: bytes, off: int) -> float:
+    return struct.unpack_from("<f", data, off)[0]
+
+
+def _w_u16(v: int) -> bytes:
+    return struct.pack("<H", v & 0xFFFF)
+
+
+def _w_u32(v: int) -> bytes:
+    return struct.pack("<I", v & 0xFFFFFFFF)
+
+
+def _w_i32(v: int) -> bytes:
+    return struct.pack("<i", v)
+
+
+def _w_i64(v: int) -> bytes:
+    return struct.pack("<q", v)
+
+
+def _w_f32(v: float) -> bytes:
+    return struct.pack("<f", v)
+
+
+def _read_str(data: bytes, off: int) -> tuple[str, int]:
+    """Length-prefixed UTF-8 string. Returns (value, next_offset)."""
+    n = _read_u16(data, off)
+    off += 2
+    s = data[off:off + n].decode("utf-8")
+    return s, off + n
+
+
+def _w_str(s: str) -> bytes:
+    b = s.encode("utf-8")
+    if len(b) > 0xFFFF:
+        raise ChunkCodecError(f"string field too long to encode ({len(b)} bytes)")
+    return _w_u16(len(b)) + b
+
+
+def checksum(payload_body: bytes) -> str:
+    """SHA-256 hex digest of the payload body (world.md §3.6.3)."""
+    return hashlib.sha256(payload_body).hexdigest()
+
+
+# ───────────────────────── Section codecs ─────────────────────────
+
+def _encode_metadata(payload: ChunkPayload) -> bytes:
+    out = bytearray()
+    out += _w_str(payload.world_id)
+    out += _w_str(payload.room_id)
+    out += _w_i32(payload.coord[0])
+    out += _w_i32(payload.coord[1])
+    out += _w_i32(payload.coord[2])
+    out += _w_f32(payload.bounds.min[0])
+    out += _w_f32(payload.bounds.min[1])
+    out += _w_f32(payload.bounds.min[2])
+    out += _w_f32(payload.bounds.max[0])
+    out += _w_f32(payload.bounds.max[1])
+    out += _w_f32(payload.bounds.max[2])
+    return bytes(out)
+
+
+def _decode_metadata(data: bytes, result: ChunkPayload) -> None:
+    off = 0
+    result.world_id, off = _read_str(data, off)
+    result.room_id, off = _read_str(data, off)
+    coord = (_read_i32(data, off), _read_i32(data, off + 4), _read_i32(data, off + 8))
+    off += 12
+    min_pos = (_read_f32(data, off), _read_f32(data, off + 4), _read_f32(data, off + 8))
+    max_pos = (_read_f32(data, off + 12), _read_f32(data, off + 16), _read_f32(data, off + 20))
+    size = tuple(a - b for a, b in zip(max_pos, min_pos))
+    result.coord = coord
+    result.bounds = ChunkBounds(min=min_pos, size=size)
+
+
+def _encode_tile_layer(layer: TileLayer) -> bytes:
+    out = bytearray()
+    out += _w_str(layer.name)
+    out += _w_u16(layer.layer_id)
+    out += _w_u16(layer.width)
+    out += _w_u16(layer.height)
+    out += _w_u16(layer.depth)
+    out += _w_u16(len(layer.palette))
+    for td in layer.palette:
+        out += _w_u16(td.id)
+        out += _w_str(td.asset_id)
+        out += bytes([1 if td.solid else 0])
+        out += _w_u32(td.flags)
+        out += bytes([td.variants & 0xFF])
+    out += _w_u32(len(layer.tiles))
+    for tile_id in layer.tiles:
+        out += _w_u16(tile_id)
+    return bytes(out)
+
+
+def _decode_tile_layer(data: bytes) -> TileLayer:
+    off = 0
+    name, off = _read_str(data, off)
+    layer_id = _read_u16(data, off); off += 2
+    width = _read_u16(data, off); off += 2
+    height = _read_u16(data, off); off += 2
+    depth = _read_u16(data, off); off += 2
+    palette_count = _read_u16(data, off); off += 2
+    palette: list[TileDef] = []
+    for _ in range(palette_count):
+        tid = _read_u16(data, off); off += 2
+        asset_id, off = _read_str(data, off)
+        solid = data[off] != 0; off += 1
+        flags = _read_u32(data, off); off += 4
+        variants = data[off]; off += 1
+        palette.append(TileDef(id=tid, asset_id=asset_id, solid=solid, flags=flags, variants=variants))
+    tile_count = _read_u32(data, off); off += 4
+    tiles: list[int] = []
+    for _ in range(tile_count):
+        tiles.append(_read_u16(data, off))
+        off += 2
+    return TileLayer(name=name, layer_id=layer_id, width=width, height=height,
+                      depth=depth, palette=palette, tiles=tiles)
+
+
+def _encode_flags(flags: ContentFlags) -> bytes:
+    out = bytearray()
+    for name in CATEGORY_FIELDS:
+        out.append(getattr(flags, name) & 0xFF)
+    out.append(1 if flags.mature else 0)
+    out += _w_u16(len(flags.sources))
+    for src in flags.sources:
+        out += _w_str(src)
+    return bytes(out)
+
+
+def _decode_flags(data: bytes) -> ContentFlags:
+    off = 0
+    values = {}
+    for name in CATEGORY_FIELDS:
+        values[name] = data[off]
+        off += 1
+    mature = data[off] != 0
+    off += 1
+    source_count = _read_u16(data, off)
+    off += 2
+    sources = []
+    for _ in range(source_count):
+        s, off = _read_str(data, off)
+        sources.append(s)
+    return ContentFlags(**values, mature=mature, sources=sources)
+
+
+def _encode_object(obj: WorldObject) -> bytes:
+    out = bytearray()
+    out += _w_str(obj.id)
+    out += _w_str(obj.type)
+    out += _w_str(obj.asset_id)
+    for v in obj.pos:
+        out += _w_f32(v)
+    for v in obj.rot:
+        out += _w_f32(v)
+    for v in obj.scale:
+        out += _w_f32(v)
+    out.append(1 if obj.dynamic else 0)
+    # Canonical JSON: keys sorted lexicographically (world.md §3.6.3).
+    props_json = json.dumps(obj.properties, sort_keys=True, separators=(",", ":"))
+    out += _w_str(props_json)
+    out += _encode_flags(obj.flags)
+    return bytes(out)
+
+
+def _decode_object(data: bytes) -> WorldObject:
+    off = 0
+    oid, off = _read_str(data, off)
+    otype, off = _read_str(data, off)
+    asset_id, off = _read_str(data, off)
+    pos = (_read_f32(data, off), _read_f32(data, off + 4), _read_f32(data, off + 8))
+    off += 12
+    rot = (
+        _read_f32(data, off), _read_f32(data, off + 4),
+        _read_f32(data, off + 8), _read_f32(data, off + 12),
+    )
+    off += 16
+    scale = (_read_f32(data, off), _read_f32(data, off + 4), _read_f32(data, off + 8))
+    off += 12
+    dynamic = data[off] != 0
+    off += 1
+    props_str, off = _read_str(data, off)
+    try:
+        properties = json.loads(props_str) if props_str else {}
+    except json.JSONDecodeError as exc:
+        raise ChunkCodecError(f"object {oid!r}: invalid properties JSON") from exc
+    obj_flags = _decode_flags(data[off:])
+    return WorldObject(id=oid, type=otype, asset_id=asset_id, pos=pos, rot=rot,
+                        scale=scale, dynamic=dynamic, properties=properties, flags=obj_flags)
+
+
+def _encode_revision_meta(payload: ChunkPayload) -> bytes:
+    out = bytearray()
+    out += _w_i64(payload.created_at)
+    out += _w_i64(payload.updated_at)
+    out += _w_u32(payload.revision)
+    out += _w_str(payload.author)
+    return bytes(out)
+
+
+def _decode_revision_meta(data: bytes, result: ChunkPayload) -> None:
+    off = 0
+    result.created_at = _read_i64(data, off); off += 8
+    result.updated_at = _read_i64(data, off); off += 8
+    result.revision = _read_u32(data, off); off += 4
+    result.author, off = _read_str(data, off)
+
+
+def _wrap_section(section_id: int, data: bytes) -> bytes:
+    return bytes([section_id]) + _w_u32(len(data)) + data
+
+
+# ───────────────────────── Top-level encode/decode ─────────────────────────
+
+def encode_binary(payload: ChunkPayload) -> bytes:
+    """Encode a ChunkPayload to the world.md §3.6 wire format."""
+    sections = bytearray()
+    sections += _wrap_section(SECTION_META, _encode_metadata(payload))
+    for layer in payload.tile_layers:
+        sections += _wrap_section(SECTION_TILE, _encode_tile_layer(layer))
+    for obj in payload.objects:
+        sections += _wrap_section(SECTION_OBJECT, _encode_object(obj))
+    sections += _wrap_section(SECTION_FLAGS, _encode_flags(payload.flags))
+    sections += _wrap_section(SECTION_REVISION_META, _encode_revision_meta(payload))
+
+    payload_body = bytes(sections)
+    digest = hashlib.sha256(payload_body).digest()  # 32 raw bytes
+
+    header = bytearray()
+    header += MAGIC
+    header += _w_u16(CURRENT_VERSION)
+    header += _w_u16(HEADER_SIZE - 8)  # header_len: bytes of header after this field (spec-correct)
+    header += _w_u32(0)  # flags (reserved)
+    header += _w_u32(len(payload_body))
+    header += digest
+
+    return bytes(header) + payload_body
+
+
+def decode_binary(data: bytes) -> ChunkPayload:
+    """Decode a world.md §3.6 binary chunk. Raises ChunkCodecError on
+    structurally malformed input (short buffer, bad magic, unsupported
+    version, truncated payload)."""
+    if len(data) < HEADER_SIZE:
+        raise ChunkCodecError(f"data too short for header ({len(data)} bytes)")
+
+    if data[0:4] != MAGIC:
+        raise ChunkCodecError("bad magic bytes")
+
+    version = _read_u16(data, 4)
+    if version < 1 or version > CURRENT_VERSION:
+        raise ChunkCodecError(f"unsupported chunk format version {version}")
+
+    # header_len (offset 6) is intentionally not used for offset math --
+    # both this decoder and the Godot one always slice at the fixed
+    # HEADER_SIZE, matching the reference implementation's actual (if
+    # spec-inconsistent) behaviour.
+    payload_len = _read_u32(data, 12)
+    # bytes 16:48 are the header's advisory checksum -- decode_and_validate
+    # re-reads it directly and recomputes against the parsed payload body.
+
+    if len(data) - HEADER_SIZE != payload_len:
+        raise ChunkCodecError(
+            f"declared payload_len ({payload_len}) does not match actual "
+            f"remaining bytes ({len(data) - HEADER_SIZE})"
+        )
+
+    payload_body = data[HEADER_SIZE:HEADER_SIZE + payload_len]
+
+    result = ChunkPayload(version=version)
+
+    offset = 0
+    while offset < len(payload_body):
+        if offset + 5 > len(payload_body):
+            raise ChunkCodecError("truncated section header")
+        section_id = payload_body[offset]
+        section_len = _read_u32(payload_body, offset + 1)
+        data_start = offset + 5
+        data_end = data_start + section_len
+        if data_end > len(payload_body):
+            raise ChunkCodecError("truncated section body")
+        section_data = payload_body[data_start:data_end]
+
+        if section_id == SECTION_META:
+            _decode_metadata(section_data, result)
+        elif section_id == SECTION_TILE:
+            result.tile_layers.append(_decode_tile_layer(section_data))
+        elif section_id == SECTION_OBJECT:
+            result.objects.append(_decode_object(section_data))
+        elif section_id == SECTION_FLAGS:
+            result.flags = _decode_flags(section_data)
+        elif section_id == SECTION_REVISION_META:
+            _decode_revision_meta(section_data, result)
+        # Unknown section ids are skipped (forward-compat), matching the
+        # Godot decoder's match-with-no-default behaviour.
+
+        offset = data_end
+
+    return result
+
+
+# ───────────────────────── JSON encoding (world.md §3.5) ─────────────────────────
+# Derived, never stored (world_persistence_impl.md §8.1) -- produced here
+# from a decoded ChunkPayload for the ``Accept: application/json`` path.
+
+def to_json_dict(payload: ChunkPayload, *, key: str, chunk_checksum: str) -> dict:
+    return {
+        "version": payload.version,
+        "key": key,
+        "world_id": payload.world_id,
+        "room_id": payload.room_id,
+        "coord": {"cx": payload.coord[0], "cy": payload.coord[1], "cz": payload.coord[2]},
+        "bounds": {
+            "min_x": payload.bounds.min[0], "min_y": payload.bounds.min[1], "min_z": payload.bounds.min[2],
+            "max_x": payload.bounds.max[0], "max_y": payload.bounds.max[1], "max_z": payload.bounds.max[2],
+        },
+        "tiles": [
+            {
+                "name": layer.name,
+                "layer_id": layer.layer_id,
+                "width": layer.width,
+                "height": layer.height,
+                "depth": layer.depth,
+                "palette": [
+                    {"id": td.id, "asset_id": td.asset_id, "solid": td.solid,
+                     "flags": td.flags, "variants": td.variants}
+                    for td in layer.palette
+                ],
+                "tiles": list(layer.tiles),
+            }
+            for layer in payload.tile_layers
+        ],
+        "objects": [
+            {
+                "id": obj.id, "type": obj.type, "asset_id": obj.asset_id,
+                "transform": {
+                    "pos": list(obj.pos), "rot": list(obj.rot), "scale": list(obj.scale),
+                },
+                "properties": obj.properties,
+                "dynamic": obj.dynamic,
+                "flags": obj.flags.to_dict(),
+            }
+            for obj in payload.objects
+        ],
+        "flags": payload.flags.to_dict(),
+        "meta": {
+            "created_at": payload.created_at, "updated_at": payload.updated_at,
+            "revision": payload.revision, "author": payload.author,
+        },
+        "checksum": chunk_checksum,
+    }
+
+
+# ───────────────────────── Validation (world_persistence_impl.md §5.5) ─────────────────────────
+
+# Not precisely quantified by the design doc beyond "length limits" --
+# these are this implementation's conservative defaults (world.md §7).
+MAX_STRING_FIELD_LEN = 256
+MAX_PROPERTIES_JSON_LEN = 16_384
+MAX_SOURCES_PER_FLAGSET = 32
+
+
+def _check_string_lengths(obj: WorldObject) -> None:
+    for field_name, value in (("id", obj.id), ("type", obj.type), ("asset_id", obj.asset_id)):
+        if len(value) > MAX_STRING_FIELD_LEN:
+            raise ChunkValidationError(
+                "string_field_too_long", f"object.{field_name} exceeds {MAX_STRING_FIELD_LEN} chars"
+            )
+    props_json = json.dumps(obj.properties)
+    if len(props_json) > MAX_PROPERTIES_JSON_LEN:
+        raise ChunkValidationError(
+            "string_field_too_long", f"object {obj.id!r} properties exceed {MAX_PROPERTIES_JSON_LEN} bytes"
+        )
+    if len(obj.flags.sources) > MAX_SOURCES_PER_FLAGSET:
+        raise ChunkValidationError("string_field_too_long", f"object {obj.id!r} has too many flag sources")
+
+
+def decode_and_validate(
+    data: bytes,
+    *,
+    expected_key: str,
+    grid_size: tuple[int, int, int],
+    max_objects: int,
+) -> ChunkPayload:
+    """Decode + fully validate a client-submitted chunk payload.
+
+    This is the boundary world_persistence_impl.md §5.5 requires: "the
+    backend must not trust the client". Raises ``ChunkCodecError`` for
+    structurally malformed bytes (mapped to a 422 by the router with a
+    generic reason) or ``ChunkValidationError`` with a specific ``reason``
+    code for a well-formed-but-invalid payload.
+    """
+    payload = decode_binary(data)  # raises ChunkCodecError for structural problems first
+
+    # Checksum is advisory in the header (world.md §7); the value that
+    # matters is recomputed from the actual payload body we just parsed.
+    payload_body = data[HEADER_SIZE:]
+    recomputed = checksum(payload_body)
+    header_checksum_hex = data[16:48].hex()
+    if header_checksum_hex != recomputed:
+        raise ChunkValidationError(
+            "checksum_mismatch",
+            "header checksum does not match the recomputed SHA-256 of the payload body",
+        )
+
+    actual_key = build_key(payload.world_id, payload.room_id, *payload.coord)
+    if actual_key != expected_key:
+        raise ChunkValidationError(
+            "chunk_key_mismatch",
+            f"payload key {actual_key!r} does not match URL {expected_key!r}",
+        )
+
+    for layer in payload.tile_layers:
+        if (layer.width, layer.height, layer.depth) != tuple(grid_size):
+            raise ChunkValidationError(
+                "layer_dims",
+                f"tile layer {layer.name!r} dims {(layer.width, layer.height, layer.depth)} "
+                f"!= room grid {tuple(grid_size)}",
+            )
+        valid_ids = {0} | {td.id for td in layer.palette}
+        for tile_id in layer.tiles:
+            if tile_id not in valid_ids:
+                raise ChunkValidationError(
+                    "tile_out_of_palette",
+                    f"tile layer {layer.name!r} references palette id {tile_id} not in its palette",
+                )
+        if len(layer.tiles) != layer.width * layer.height * layer.depth:
+            raise ChunkValidationError(
+                "layer_dims",
+                f"tile layer {layer.name!r} has {len(layer.tiles)} cells, expected "
+                f"{layer.width * layer.height * layer.depth}",
+            )
+
+    if len(payload.objects) > max_objects:
+        raise ChunkValidationError(
+            "too_many_objects", f"{len(payload.objects)} objects exceeds max {max_objects}"
+        )
+
+    bmin, bmax = payload.bounds.min, payload.bounds.max
+    for obj in payload.objects:
+        _check_string_lengths(obj)
+        if not all(bmin[i] <= obj.pos[i] <= bmax[i] for i in range(3)):
+            raise ChunkValidationError(
+                "object_out_of_bounds",
+                f"object {obj.id!r} position {obj.pos} outside chunk bounds "
+                f"[{bmin}, {bmax}]",
+            )
+
+    if len(payload.author) > MAX_STRING_FIELD_LEN:
+        raise ChunkValidationError("string_field_too_long", "meta.author too long")
+
+    return payload
+
+
+# ───────────────────────── Known cross-codec divergence ─────────────────────────
+#
+# `scripts/chunk_data_decoder.gd`'s `_read_float32`/`_write_float32` do:
+#
+#     static func _write_float32(val: float) -> PackedByteArray:
+#         var bits := val as int
+#         return _write_uint32(bits)
+#
+#     static func _read_float32(data: PackedByteArray, offset: int) -> float:
+#         var bits := _read_uint32(data, offset)
+#         return bits as float
+#
+# `as` between int and float in GDScript is a numeric conversion, not a bit
+# reinterpretation (verified empirically against Godot 4.6.2 headless:
+# `1.5 as int` -> `1`, `1 as float` -> `1.0`; the IEEE-754 bit pattern of
+# 1.5f is 0x3FC00000 = 1069547520, not 1). So the shipped client codec
+# truncates every float32 field (bounds, object pos/rot/scale) to its
+# integer part and stores that integer as a raw int32 -- not as float32
+# bits at all. This is a real bug in already-merged, client-side code
+# (scripts/ is out of scope for this task) that breaks the "byte-stable
+# across two implementations" guarantee world.md §3.6.3 states.
+#
+# This module implements the *specified* format (real IEEE-754 float32)
+# rather than replicating that bug, because world.md §3.6 is normative and
+# says "float32" for these fields, and mirroring the bug would mean the
+# backend also corrupts every non-integer transform/bounds value it
+# stores. Practical effect until the client-side bug is fixed: payloads
+# with integer-only floats will decode identically on both sides; any
+# payload with a fractional position/rotation/scale/bounds value will not
+# be byte-identical (or numerically identical) between this module and the
+# current `scripts/chunk_data_decoder.gd`. This is flagged for the
+# client/editor follow-on task, not fixed here.

backend/app/services/game_servers.py

@@ -0,0 +1,239 @@
+"""Game-server orchestration.
+
+On ``POST /api/worlds/{id}/join`` the backend ensures a headless Godot
+dedicated-server process is running for that world and returns its address.
+One process per world, keyed by ``world_id``. A background reaper kills a
+world's server once its status file reports zero players for
+``GAME_SERVER_IDLE_TIMEOUT_SECONDS``.
+
+This lives in-process (a module-level singleton) rather than as a separate
+service, so the backend MUST run single-worker -- which it does
+(``uvicorn app.main:app`` with no ``--workers``). The Godot binary and
+project are on the host (see ``settings.GODOT_BIN`` / ``GAME_PROJECT_DIR``);
+the backend spawns them as subprocesses.
+
+Design notes / limits (PC3):
+ - Port allocation is a linear scan of the configured range.
+ - No crash-restart: if a server process dies, the next join respawns it.
+   With world content now durable in Postgres (world_persistence_impl.md
+   D2), this is genuinely safe rather than merely tolerated: the sim
+   process holds no unsaved world content, so a reap/crash/kill can never
+   lose world data.
+
+Per-spawn auth token (world_persistence_impl.md §7.3): each spawned server
+gets a random ``secrets.token_urlsafe(32)`` on its command line, which it
+uses as a Bearer token against ``/api/internal`` to pull its world's
+content read-only before binding its ENet port. The token grants access to
+exactly one world and dies with its process (the reaper's
+``del self._servers[wid]`` invalidates it; see ``validate_token``).
+"""
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import secrets
+import socket
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from app.config import settings
+
+
+@dataclass
+class _WorldServer:
+    world_id: str
+    port: int
+    proc: subprocess.Popen
+    status_path: Path
+    token: str
+    started_at: float = field(default_factory=time.time)
+    last_join: float = field(default_factory=time.time)
+
+    def status(self) -> dict:
+        try:
+            return json.loads(self.status_path.read_text())
+        except (OSError, ValueError):
+            return {}
+
+    def player_count(self) -> int:
+        return int(self.status().get("players", 0))
+
+    def is_ready(self) -> bool:
+        return self.status().get("ready") is True
+
+    def alive(self) -> bool:
+        return self.proc.poll() is None
+
+    def stop(self) -> None:
+        if self.alive():
+            self.proc.terminate()
+            try:
+                self.proc.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self.proc.kill()
+        self.status_path.unlink(missing_ok=True)
+
+
+class GameServerSupervisor:
+    def __init__(self) -> None:
+        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.mkdir(parents=True, exist_ok=True)
+
+    # ── lifecycle ────────────────────────────────────────────────────────
+    def start(self) -> None:
+        if not settings.GAME_SERVERS_ENABLED:
+            return
+        if self._reaper is None or self._reaper.done():
+            self._reaper = asyncio.create_task(self._reap_loop())
+
+    async def shutdown(self) -> None:
+        if self._reaper:
+            self._reaper.cancel()
+        async with self._lock:
+            for srv in list(self._servers.values()):
+                srv.stop()
+            self._servers.clear()
+
+    # ── join ─────────────────────────────────────────────────────────────
+    async def ensure_server(self, world_id: str) -> dict:
+        """Return ``{"host", "port", "world_id"}`` for the world's dedicated
+        server, spawning it if needed. Raises RuntimeError if orchestration
+        is disabled or no port/engine is available."""
+        if not settings.GAME_SERVERS_ENABLED:
+            raise RuntimeError("game servers are not enabled on this backend")
+
+        async with self._lock:
+            srv = self._servers.get(world_id)
+            if srv is not None and not srv.alive():
+                srv.stop()
+                srv = None
+                del self._servers[world_id]
+
+            if srv is None:
+                srv = self._spawn(world_id)
+                self._servers[world_id] = srv
+                try:
+                    await self._await_ready(srv)
+                except TimeoutError:
+                    # Real failure now, not a silent "hope it's fine" --
+                    # see _await_ready's docstring. Don't leave a possibly
+                    # half-started process registered.
+                    srv.stop()
+                    del self._servers[world_id]
+                    raise RuntimeError(
+                        f"dedicated server for world {world_id} did not become ready in time"
+                    )
+
+            srv.last_join = time.time()
+            return {"host": settings.GAME_SERVER_HOST, "port": srv.port, "world_id": world_id}
+
+    def validate_token(self, world_id: str, token: str) -> bool:
+        """`require_game_server` dependency support (world_persistence_impl.md
+        §7.3): true iff *token* is the live token for *world_id*'s server.
+        A dict lookup, as the doc specifies, plus a constant-time compare
+        since it's a bearer credential."""
+        srv = self._servers.get(str(world_id))
+        if srv is None or not srv.alive():
+            return False
+        return hmac.compare_digest(srv.token, token)
+
+    # ── internals ────────────────────────────────────────────────────────
+    def _spawn(self, world_id: str) -> _WorldServer:
+        port = self._free_port()
+        token = secrets.token_urlsafe(32)
+        status_path = self._runtime_dir / f"world_{world_id}_{port}.json"
+        status_path.unlink(missing_ok=True)
+        cmd = [
+            settings.GODOT_BIN, "--headless",
+            "--path", settings.GAME_PROJECT_DIR,
+            "res://scenes/server.tscn", "--",
+            "--port", str(port),
+            "--world", str(world_id),
+            "--status-file", str(status_path),
+            "--api-url", settings.GAME_SERVER_INTERNAL_API_URL,
+            "--server-token", token,
+        ]
+        proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        return _WorldServer(
+            world_id=world_id, port=port, proc=proc, status_path=status_path, token=token
+        )
+
+    def _free_port(self) -> int:
+        used = {s.port for s in self._servers.values()}
+        for p in range(settings.GAME_SERVER_PORT_MIN, settings.GAME_SERVER_PORT_MAX + 1):
+            if p in used:
+                continue
+            with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+                try:
+                    s.bind(("0.0.0.0", p))
+                    return p
+                except OSError:
+                    continue
+        raise RuntimeError("no free game-server port in the configured range")
+
+    async def _await_ready(self, srv: _WorldServer) -> None:
+        """Wait for a ``"ready": true`` field in the status file
+        (world_persistence_impl.md §7.4).
+
+        This replaces the old ``_await_port``, which had two real bugs:
+        it treated a bound UDP port as "ready", but with content loading
+        the port binds *before* the server has fetched its world's rooms
+        and chunks (world_persistence_impl.md §7.2 step 4) -- so a client
+        could get handed an address for a server still mid-fetch. And it
+        *failed open*: past its 8s deadline it simply returned, with no
+        error, so ``ensure_server`` reported success for a server that may
+        never have started at all. This raises ``TimeoutError`` instead,
+        which ``ensure_server`` turns into a real 503 for the joining
+        client, and also bails out early (same exception) if the process
+        has already exited.
+        """
+        deadline = time.time() + settings.GAME_SERVER_READY_TIMEOUT_SECONDS
+        while time.time() < deadline:
+            if srv.is_ready():
+                return
+            if not srv.alive():
+                raise TimeoutError(
+                    f"server process for world {srv.world_id} exited before becoming ready"
+                )
+            await asyncio.sleep(0.25)
+        raise TimeoutError(
+            f"server for world {srv.world_id} did not report ready within "
+            f"{settings.GAME_SERVER_READY_TIMEOUT_SECONDS}s"
+        )
+
+    async def _reap_loop(self) -> None:
+        try:
+            while True:
+                await asyncio.sleep(30)
+                async with self._lock:
+                    now = time.time()
+                    for wid, srv in list(self._servers.items()):
+                        if not srv.alive():
+                            srv.stop()
+                            del self._servers[wid]
+                            continue
+                        idle_for = now - srv.last_join
+                        if idle_for > settings.GAME_SERVER_IDLE_TIMEOUT_SECONDS and srv.player_count() == 0:
+                            srv.stop()
+                            del self._servers[wid]
+        except asyncio.CancelledError:
+            pass
+
+    def debug_state(self) -> list[dict]:
+        return [
+            {
+                "world_id": s.world_id, "port": s.port, "alive": s.alive(),
+                "players": s.player_count(), "uptime_s": round(time.time() - s.started_at),
+            }
+            for s in self._servers.values()
+        ]
+
+
+supervisor = GameServerSupervisor()

backend/app/services/gltf.py

@@ -0,0 +1,197 @@
+"""Lightweight glTF / GLB metadata extraction.
+
+This module intentionally avoids heavyweight dependencies such as trimesh or
+pygltflib. For the metadata fields the asset upload pipeline needs (mesh and
+vertex counts, animation presence, texture references, and the bounding box)
+a small amount of glTF-specific parsing is sufficient and keeps the backend
+dependency-free.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any, Optional
+
+# GLB binary header magic bytes ("glTF").
+_GLB_MAGIC = b"glTF"
+_GLB_MAGIC_INT = 0x46546C67  # b"glTF" interpreted as little-endian uint32
+_GLB_JSON_CHUNK_TYPE = 0x4E4F534A  # "JSON"
+_GLB_BIN_CHUNK_TYPE = 0x004E4942  # "BIN\0"
+
+# Whitespace allowed around a GLB JSON chunk. The spec pads with spaces (0x20),
+# but be lenient with null bytes and other whitespace that real exporters emit.
+_JSON_CHUNK_TRIM = b" \t\r\n\x00"
+
+
+def looks_like_gltf(content: bytes, filename: Optional[str] = None) -> bool:
+    """Return True when the bytes or filename indicate a glTF/GLB asset."""
+    if content.startswith(_GLB_MAGIC):
+        return True
+
+    if filename:
+        lowered = filename.lower()
+        if lowered.endswith(".gltf") or lowered.endswith(".glb"):
+            return True
+
+    # A bare JSON buffer (e.g. uploaded without an extension) that has the
+    # glTF asset marker is also a glTF file.
+    stripped = content.lstrip()
+    if stripped.startswith(b"{"):
+        try:
+            payload = json.loads(stripped.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return False
+        return isinstance(payload, dict) and "asset" in payload and "version" in payload.get("asset", {})
+
+    return False
+
+
+def _parse_glb(content: bytes) -> dict[str, Any]:
+    """Parse the JSON chunk of a GLB binary container."""
+    if len(content) < 12:
+        raise ValueError("GLB file is too short")
+
+    magic, _version, _length = struct.unpack_from("<III", content, 0)
+    if magic != _GLB_MAGIC_INT:
+        raise ValueError("invalid GLB magic")
+
+    offset = 12
+    json_chunk: Optional[dict[str, Any]] = None
+
+    while offset + 8 <= len(content):
+        chunk_length, chunk_type = struct.unpack_from("<II", content, offset)
+        offset += 8
+        chunk_end = offset + chunk_length
+        if chunk_end > len(content):
+            raise ValueError("GLB chunk overruns file boundary")
+
+        chunk_data = content[offset:chunk_end]
+        if chunk_type == _GLB_JSON_CHUNK_TYPE:
+            try:
+                json_chunk = json.loads(chunk_data.strip(_JSON_CHUNK_TRIM).decode("utf-8"))
+            except (ValueError, UnicodeDecodeError) as exc:
+                raise ValueError(f"invalid GLB JSON chunk: {exc}") from exc
+
+        offset = chunk_end
+
+    if json_chunk is None:
+        raise ValueError("GLB file does not contain a JSON chunk")
+
+    return json_chunk
+
+
+def _parse_gltf_json(content: bytes) -> dict[str, Any]:
+    """Parse a plain .gltf JSON file."""
+    stripped = content.lstrip()
+    try:
+        payload = json.loads(stripped.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ValueError(f"invalid glTF JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("glTF JSON root must be an object")
+    return payload
+
+
+def _position_accessor_counts(gltf: dict[str, Any]) -> list[int]:
+    """Return POSITION accessor counts for every mesh primitive."""
+    counts: list[int] = []
+    accessors = gltf.get("accessors", [])
+    for mesh in gltf.get("meshes", []):
+        for primitive in mesh.get("primitives", []):
+            attributes = primitive.get("attributes", {})
+            position_index = attributes.get("POSITION")
+            if position_index is None:
+                continue
+            try:
+                accessor = accessors[int(position_index)]
+            except (IndexError, TypeError, ValueError):
+                continue
+            count = accessor.get("count")
+            if isinstance(count, int):
+                counts.append(count)
+    return counts
+
+
+def _position_bounds(gltf: dict[str, Any]) -> list[list[float]]:
+    """Return min/max bounds for every POSITION accessor that declares them."""
+    bounds: list[list[float]] = []
+    accessors = gltf.get("accessors", [])
+    for mesh in gltf.get("meshes", []):
+        for primitive in mesh.get("primitives", []):
+            attributes = primitive.get("attributes", {})
+            position_index = attributes.get("POSITION")
+            if position_index is None:
+                continue
+            try:
+                accessor = accessors[int(position_index)]
+            except (IndexError, TypeError, ValueError):
+                continue
+            minimum = accessor.get("min")
+            maximum = accessor.get("max")
+            if isinstance(minimum, list) and isinstance(maximum, list):
+                bounds.append([float(x) for x in minimum])
+                bounds.append([float(x) for x in maximum])
+    return bounds
+
+
+def _texture_refs(gltf: dict[str, Any]) -> list[str]:
+    """Collect external texture source references from the image array."""
+    refs: list[str] = []
+    for index, image in enumerate(gltf.get("images", [])):
+        uri = image.get("uri")
+        if isinstance(uri, str) and not uri.startswith("data:"):
+            refs.append(uri)
+            continue
+
+        name = image.get("name")
+        if isinstance(name, str) and name:
+            refs.append(name)
+            continue
+
+        if isinstance(uri, str):
+            # Embedded data URI; keep a stable, non-huge reference.
+            refs.append(f"data:{index}")
+            continue
+
+        buffer_view = image.get("bufferView")
+        if buffer_view is not None:
+            refs.append(f"bufferView:{buffer_view}")
+            continue
+
+        refs.append(f"image:{index}")
+
+    return refs
+
+
+def extract_gltf_metadata(content: bytes) -> dict[str, Any]:
+    """Extract upload-relevant metadata from glTF/GLB bytes.
+
+    Raises ValueError for malformed glTF content. The returned dict contains:
+        mesh_count, vertex_count, has_animation, texture_refs,
+        bounding_box_min, bounding_box_max.
+    """
+    if content.startswith(_GLB_MAGIC):
+        gltf = _parse_glb(content)
+    else:
+        gltf = _parse_gltf_json(content)
+
+    position_counts = _position_accessor_counts(gltf)
+    bounds = _position_bounds(gltf)
+
+    if bounds:
+        bounding_box_min = [min(axis) for axis in zip(*bounds[::2])]
+        bounding_box_max = [max(axis) for axis in zip(*bounds[1::2])]
+    else:
+        bounding_box_min = [0.0, 0.0, 0.0]
+        bounding_box_max = [0.0, 0.0, 0.0]
+
+    return {
+        "mesh_count": len(gltf.get("meshes", [])),
+        "vertex_count": sum(position_counts),
+        "has_animation": bool(gltf.get("animations")),
+        "texture_refs": _texture_refs(gltf),
+        "bounding_box_min": bounding_box_min,
+        "bounding_box_max": bounding_box_max,
+    }

backend/app/services/presence.py

@@ -0,0 +1,145 @@
+"""Redis-backed presence store.
+
+Presence is determined by a heartbeat TTL key in Redis:
+- heartbeat(user_id) sets a TTL key per user (default 60 s).
+- is_online(user_id) / is_online_batch(user_ids) check whether the key(s)
+  exist.
+
+status_message and last_seen_at are persisted in the ``users`` table by the
+router (app/routers/presence.py); this store only owns the Redis side.
+
+The Redis client is created lazily, on first actual use, rather than
+requiring an explicit ``connect()`` call during app startup. This matters
+because FastAPI's lifespan handler does not run under the plain
+``TestClient(app)`` instantiation this codebase's tests use (no
+``with`` block), so anything that only connected during lifespan startup
+would never connect in tests. Lazy connection means the store works
+identically whether the app was started for real or is being driven by
+pytest.
+
+The client is also cached per-*event loop* rather than globally: the same
+plain ``TestClient(app)`` pattern can dispatch different requests onto
+different event loops (see the NullPool comment on ``_override_db`` in
+tests/conftest.py for the analogous asyncpg problem), and an
+``aioredis.Redis`` connection, like an asyncpg connection, breaks with
+"Event loop is closed" if reused across loops. In the real running server
+there is exactly one event loop for the process lifetime, so this
+degrades to a single cached, pooled connection there.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import redis.asyncio as aioredis
+
+from app.config import settings
+
+logger = logging.getLogger(__name__)
+
+# Key prefix for heartbeat entries.
+_PRESENCE_KEY_PREFIX = "presence:heartbeat:"
+
+# Default heartbeat TTL in seconds (1 minute).
+# Clients should heartbeat at least once per interval.
+_DEFAULT_HEARTBEAT_TTL = 60
+
+
+class PresenceStore:
+    """Redis-backed presence store with async, lazily-connected operations."""
+
+    def __init__(self, redis_url: str | None = None, heartbeat_ttl: int = _DEFAULT_HEARTBEAT_TTL):
+        # redis_url is resolved from settings at first use (not at
+        # construction time) so tests that override settings.REDIS_URL
+        # before the first call still take effect -- this module is
+        # imported (and the module-level singleton below constructed)
+        # well before any such override runs.
+        self._redis_url = redis_url
+        self._heartbeat_ttl = heartbeat_ttl
+        # Keyed by id(running loop) -- see the module docstring.
+        self._clients: dict[int, aioredis.Redis] = {}
+        self._connect_lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def _ensure_client(self) -> aioredis.Redis:
+        """Return a connected client for the current event loop, connecting
+        on first use per loop."""
+        loop_key = id(asyncio.get_running_loop())
+        client = self._clients.get(loop_key)
+        if client is None:
+            async with self._connect_lock:
+                client = self._clients.get(loop_key)
+                if client is None:
+                    url = self._redis_url or settings.REDIS_URL
+                    client = aioredis.from_url(
+                        url,
+                        encoding="utf-8",
+                        decode_responses=True,
+                    )
+                    try:
+                        await client.ping()
+                    except Exception:
+                        logger.warning("Redis ping failed for %s", url)
+                        raise
+                    self._clients[loop_key] = client
+        return client
+
+    async def close(self) -> None:
+        """Close the Redis connection for the current event loop, if one was
+        opened."""
+        loop_key = id(asyncio.get_running_loop())
+        client = self._clients.pop(loop_key, None)
+        if client is not None:
+            await client.aclose()
+
+    # ------------------------------------------------------------------
+    # Heartbeat
+    # ------------------------------------------------------------------
+
+    async def heartbeat(self, user_id: int) -> None:
+        """Record a heartbeat for *user_id*.
+
+        Sets a TTL key so that the user is considered online as long as
+        heartbeats arrive at least once per heartbeat_ttl seconds.
+        """
+        client = await self._ensure_client()
+        await client.set(self._heartbeat_key(user_id), "1", ex=self._heartbeat_ttl)
+
+    # ------------------------------------------------------------------
+    # Online checks
+    # ------------------------------------------------------------------
+
+    async def is_online(self, user_id: int) -> bool:
+        """Return True if the user has a valid heartbeat key."""
+        client = await self._ensure_client()
+        exists = await client.exists(self._heartbeat_key(user_id))
+        return bool(exists)
+
+    async def is_online_batch(self, user_ids: list[int]) -> set[int]:
+        """Return the subset of user_ids that currently have a valid
+        heartbeat key. Uses MGET (one round trip) rather than one EXISTS
+        per user.
+        """
+        if not user_ids:
+            return set()
+        client = await self._ensure_client()
+        keys = [self._heartbeat_key(uid) for uid in user_ids]
+        values = await client.mget(keys)
+        return {uid for uid, v in zip(user_ids, values) if v is not None}
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _heartbeat_key(user_id: int) -> str:
+        return f"{_PRESENCE_KEY_PREFIX}{user_id}"
+
+
+# Singleton instance shared by the router, so all requests share the same
+# connection pool.
+presence_store = PresenceStore()

backend/app/services/text_filter.py

@@ -0,0 +1,304 @@
+"""Pluggable server-side text filtering, `docs/planning/social.md` §4/§5 (US-4).
+
+social.md §4 calls for a "Pluggable `TextFilter` interface with a
+deterministic default (profanity list + normalization) so it runs without
+external services; third-party hook later". This module is that interface
+plus the default implementation:
+
+- `TextFilter` is a `Protocol` -- the extension point. A future third-party
+  moderation provider (a paid API, an ML classifier, etc.) just needs to
+  implement `check(text) -> FilterResult`; nothing else in this module
+  needs to change, and callers depend on the protocol, not a concrete
+  class.
+- `ListBasedTextFilter` is the deterministic default: a configurable
+  term list (JSON file, see `text_filter_terms.json` next to this module)
+  matched against a normalized form of the input text so that trivial
+  evasion (case changes, leetspeak substitutions, and punctuation/spacing
+  inserted between letters) doesn't slip through.
+
+Nothing here talks to a database, an HTTP client, or the FastAPI app -- it
+is a pure, side-effect-free (aside from reading the term list file once, at
+construction) service so it can be unit tested in isolation. It is NOT
+wired into any router/endpoint by this task; that's for the chat feature
+tasks that depend on it (social.md §6) to do.
+
+Normalization approach
+-----------------------
+Matching naively against raw text misses "sh1t", "@ss", or "s.h.i.t". To
+catch these without a real tokenizer, every character of the input is
+independently normalized to at most one lowercase ASCII alphanumeric
+character (case-folded, then run through a small leetspeak substitution
+table); characters that don't reduce to `[a-z0-9]` (punctuation, spacing,
+symbols, non-ASCII) are dropped entirely rather than kept as separators.
+This collapses "s.h.i.t", "s h i t", and "SHIT" to the same normalized
+string ("shit") that a plain lowercase term list entry matches, while a
+side table (`index_map`) remembers which original character produced each
+surviving normalized character -- so a match found in the normalized
+string can still be translated back into a span of the *original* text for
+redaction.
+
+This is a deliberate precision/recall tradeoff common to list-based
+filters: stripping separators and folding leetspeak increases recall
+against evasion at the cost of occasionally matching a term inside an
+unrelated longer word (e.g. a 3-letter term inside a longer benign word).
+That tradeoff is exactly why this is pluggable -- a deployment that needs
+tighter precision can swap in a smarter `TextFilter` implementation behind
+the same protocol.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Iterable, Protocol, runtime_checkable
+
+# ---------------------------------------------------------------------------
+# Public result / protocol
+# ---------------------------------------------------------------------------
+
+
+class FilterAction(str, Enum):
+    """What the caller should do with a checked message."""
+
+    ALLOW = "allow"
+    REDACT = "redact"
+    REJECT = "reject"
+
+
+@dataclass(frozen=True)
+class FilterResult:
+    """Outcome of running a piece of text through a `TextFilter`.
+
+    - `action`: ALLOW (no matches), REDACT (matches replaced in
+      `filtered_text`), or REJECT (matches found; the message should be
+      blocked -- callers should not persist/deliver it even though
+      `filtered_text` is populated for logging/audit purposes).
+    - `filtered_text`: the text to actually store/deliver. Equal to the
+      input for ALLOW and REJECT; has matched spans replaced for REDACT.
+    - `matched_terms`: the distinct matched terms (original, un-normalized
+      list entries), in first-occurrence order. Empty for ALLOW.
+    """
+
+    action: FilterAction
+    filtered_text: str
+    matched_terms: tuple[str, ...] = ()
+
+
+@runtime_checkable
+class TextFilter(Protocol):
+    """Extension point for text filtering/moderation providers.
+
+    Any implementation -- the deterministic default below, or a future
+    third-party service call -- just needs this one method.
+    """
+
+    def check(self, text: str) -> FilterResult:
+        """Check `text` and return the action to take plus filtered text."""
+        ...
+
+
+class FilterMode(str, Enum):
+    """Configures what `ListBasedTextFilter` does when it finds a match."""
+
+    REDACT = "redact"
+    REJECT = "reject"
+
+
+# ---------------------------------------------------------------------------
+# Normalization
+# ---------------------------------------------------------------------------
+
+# Common leetspeak / lookalike substitutions, applied after case-folding.
+# Keys are already-lowercased single characters.
+_LEET_MAP: dict[str, str] = {
+    "0": "o",
+    "1": "i",
+    "!": "i",
+    "3": "e",
+    "4": "a",
+    "@": "a",
+    "5": "s",
+    "$": "s",
+    "7": "t",
+    "+": "t",
+    "8": "b",
+    "|": "l",
+}
+
+_ALNUM_RE = re.compile(r"[a-z0-9]")
+
+
+def _normalize(text: str) -> tuple[str, list[int]]:
+    """Fold `text` to a lowercase-alnum-only string plus an index map.
+
+    Returns `(normalized, index_map)` where `index_map[i]` is the index
+    into the *original* `text` that produced `normalized[i]`. Characters
+    that don't reduce to a single `[a-z0-9]` character (punctuation,
+    whitespace, symbols, most non-ASCII) are dropped from both outputs.
+    """
+    normalized_chars: list[str] = []
+    index_map: list[int] = []
+    for i, ch in enumerate(text):
+        folded = ch.casefold()
+        # case-fold can expand to multiple characters for some unicode
+        # (e.g. German "ß" -> "ss"); such characters are not part of the
+        # leetspeak table and are not plain ascii alnum, so just skip them
+        # like any other non-matching character rather than guessing.
+        if len(folded) != 1:
+            continue
+        folded = _LEET_MAP.get(folded, folded)
+        if _ALNUM_RE.fullmatch(folded):
+            normalized_chars.append(folded)
+            index_map.append(i)
+    return "".join(normalized_chars), index_map
+
+
+def _normalize_term(term: str) -> str:
+    normalized, _ = _normalize(term)
+    return normalized
+
+
+# ---------------------------------------------------------------------------
+# Default term list loading
+# ---------------------------------------------------------------------------
+
+DEFAULT_TERMS_PATH = Path(__file__).with_name("text_filter_terms.json")
+
+
+def load_terms(path: Path | str | None = None) -> list[str]:
+    """Load a term list from a JSON file shaped `{"terms": [...]}`.
+
+    Any other top-level keys (e.g. `_readme`) are ignored. Defaults to the
+    bundled `text_filter_terms.json` next to this module.
+    """
+    resolved = Path(path) if path is not None else DEFAULT_TERMS_PATH
+    with resolved.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    terms = data.get("terms", [])
+    if not isinstance(terms, list):
+        raise ValueError(f"{resolved}: 'terms' must be a list")
+    return [str(t) for t in terms]
+
+
+# ---------------------------------------------------------------------------
+# Span merging / redaction helpers
+# ---------------------------------------------------------------------------
+
+
+def _merge_spans(spans: list[tuple[int, int, str]]) -> list[tuple[int, int]]:
+    """Merge overlapping/adjacent (start, end) spans, sorted by start."""
+    if not spans:
+        return []
+    ordered = sorted((s, e) for s, e, _ in spans)
+    merged: list[tuple[int, int]] = [ordered[0]]
+    for start, end in ordered[1:]:
+        last_start, last_end = merged[-1]
+        if start <= last_end:
+            merged[-1] = (last_start, max(last_end, end))
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def _apply_redactions(text: str, merged_spans: list[tuple[int, int]], redaction_char: str) -> str:
+    if not merged_spans:
+        return text
+    pieces: list[str] = []
+    cursor = 0
+    for start, end in merged_spans:
+        pieces.append(text[cursor:start])
+        pieces.append(redaction_char * (end - start))
+        cursor = end
+    pieces.append(text[cursor:])
+    return "".join(pieces)
+
+
+# ---------------------------------------------------------------------------
+# Default implementation
+# ---------------------------------------------------------------------------
+
+
+class ListBasedTextFilter:
+    """Deterministic `TextFilter`: normalized substring match against a term list.
+
+    `mode` controls what happens on a match:
+    - `FilterMode.REDACT` (default): matched spans in the *original* text
+      are replaced with `redaction_char` repeated to the matched span's
+      original length; `action` is REDACT if anything matched, else ALLOW.
+    - `FilterMode.REJECT`: `filtered_text` is returned unchanged but
+      `action` is REJECT if anything matched (callers should treat this as
+      "do not store/deliver"), else ALLOW.
+
+    An empty or whitespace-only string always returns ALLOW with no
+    matches -- there is nothing to filter.
+    """
+
+    def __init__(
+        self,
+        terms: Iterable[str] | None = None,
+        *,
+        mode: FilterMode = FilterMode.REDACT,
+        terms_path: Path | str | None = None,
+        redaction_char: str = "*",
+    ) -> None:
+        if terms is None:
+            terms = load_terms(terms_path)
+        # De-dupe while preserving order; drop blanks.
+        seen: dict[str, None] = {}
+        for t in terms:
+            t = t.strip()
+            if t:
+                seen.setdefault(t, None)
+        self._terms: tuple[str, ...] = tuple(seen)
+        # Pre-normalize once at construction; skip terms that normalize to
+        # nothing (e.g. a term that's pure punctuation).
+        self._normalized_terms: list[tuple[str, str]] = [
+            (normalized, original)
+            for original in self._terms
+            if (normalized := _normalize_term(original))
+        ]
+        self.mode = mode
+        self.redaction_char = redaction_char
+
+    def check(self, text: str) -> FilterResult:
+        if not text or not text.strip():
+            return FilterResult(action=FilterAction.ALLOW, filtered_text=text, matched_terms=())
+
+        normalized, index_map = _normalize(text)
+        if not normalized:
+            return FilterResult(action=FilterAction.ALLOW, filtered_text=text, matched_terms=())
+
+        spans: list[tuple[int, int, str]] = []
+        for normalized_term, original_term in self._normalized_terms:
+            start = 0
+            term_len = len(normalized_term)
+            while True:
+                idx = normalized.find(normalized_term, start)
+                if idx == -1:
+                    break
+                end = idx + term_len
+                orig_start = index_map[idx]
+                orig_end = index_map[end - 1] + 1
+                spans.append((orig_start, orig_end, original_term))
+                start = end  # non-overlapping: resume after this match
+
+        if not spans:
+            return FilterResult(action=FilterAction.ALLOW, filtered_text=text, matched_terms=())
+
+        spans.sort(key=lambda s: s[0])
+        matched_terms = tuple(dict.fromkeys(term for _, _, term in spans))
+
+        if self.mode is FilterMode.REJECT:
+            return FilterResult(action=FilterAction.REJECT, filtered_text=text, matched_terms=matched_terms)
+
+        merged = _merge_spans(spans)
+        filtered_text = _apply_redactions(text, merged, self.redaction_char)
+        return FilterResult(action=FilterAction.REDACT, filtered_text=filtered_text, matched_terms=matched_terms)
+
+
+def default_text_filter(mode: FilterMode = FilterMode.REDACT) -> ListBasedTextFilter:
+    """Convenience factory for the bundled default term list."""
+    return ListBasedTextFilter(mode=mode)

backend/app/services/text_filter_terms.json

@@ -0,0 +1,20 @@
+{
+  "_readme": "Default deterministic term list for app.services.text_filter.ListBasedTextFilter. This is a minimal, illustrative starter list (common mild-to-strong English profanity, no slurs) meant to be replaced/extended per-deployment -- swap this file, or pass an explicit `terms`/`terms_path` to the filter, rather than editing this list in place for production moderation policy.",
+  "terms": [
+    "fuck",
+    "shit",
+    "ass",
+    "asshole",
+    "bitch",
+    "bastard",
+    "damn",
+    "crap",
+    "dick",
+    "piss",
+    "slut",
+    "whore",
+    "cunt",
+    "douche",
+    "bullshit"
+  ]
+}

backend/app/services/world_store.py

@@ -0,0 +1,431 @@
+"""World content storage service.
+
+Implements the `world.md` §5.1 service interface over Postgres, per
+`world_persistence_impl.md` §9 -- **minus** ``flush_dirty`` and
+``rebuild_index``, which don't apply once there is no write-behind dirty
+set and no derived index to rebuild (see that doc's §3.3 and §4.2).
+
+This is the *only* place chunk content is written (world_persistence_impl.md
+D2 / §5). Callers (the routers) own transaction boundaries: methods here
+``flush()`` so later statements in the same request see earlier ones and so
+integrity errors surface before a caller commits, but they never
+``commit()`` -- that mirrors the existing convention in
+``app/routers/worlds.py`` (``get_db`` docs: "Handlers are responsible for
+committing or rolling back their own transactions").
+
+Known gap this module had to resolve on its own (flagged, not silently
+decided): `world_persistence_impl.md` §6/§7.2/§8.1 all reference a world's
+monotonic ``content_revision`` ("bumped on every chunk write"), but no
+column for it is defined anywhere in §4's schema. Rather than add an
+undocumented column, ``content_revision()`` below derives it as
+``MAX(id)`` over ``world_chunk_revisions`` scoped to the world: that table
+is append-only (retention only nulls ``payload``, it never deletes rows),
+so the value is genuinely monotonic and increments on every
+create/update/delete/rollback.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy import func, select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import load_only
+
+from app.config import settings
+from app.models.world_content import (
+    MAIN_ROOM_NAME,
+    MAIN_ROOM_SLUG,
+    WorldChunk,
+    WorldChunkRevision,
+    WorldRoom,
+)
+from app.services import chunk_codec
+
+
+class RevisionConflict(Exception):
+    """Optimistic-concurrency conflict (world.md §5.4). ``current_revision``
+    is 0 and ``current_checksum`` is None when the caller's ``base_revision``
+    assumed a chunk exists but it doesn't."""
+
+    def __init__(
+        self,
+        current_revision: int,
+        current_checksum: str | None,
+        coord: tuple[int, int, int] | None = None,
+    ) -> None:
+        self.current_revision = current_revision
+        self.current_checksum = current_checksum
+        self.coord = coord
+        super().__init__(f"revision conflict: current_revision={current_revision}")
+
+
+class RevisionNotAvailable(Exception):
+    """Raised by ``rollback_chunk`` when the requested revision doesn't
+    exist, or exists but its payload was pruned by the retention policy
+    (world_persistence_impl.md §4.3)."""
+
+
+@dataclass
+class Bounds:
+    cx_min: int | None = None
+    cx_max: int | None = None
+    cy_min: int | None = None
+    cy_max: int | None = None
+    cz: int | None = None
+
+
+class WorldStore:
+    """Owns chunk/room read/write operations over the async session
+    handed to it. One instance per request is the expected usage
+    (``WorldStore(db)`` where ``db`` is the ``DbDep`` session)."""
+
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    # ── rooms ────────────────────────────────────────────────────────────
+
+    async def get_room(self, world_id: int, slug: str) -> WorldRoom | None:
+        result = await self.db.execute(
+            select(WorldRoom).where(WorldRoom.world_id == world_id, WorldRoom.slug == slug)
+        )
+        return result.scalar_one_or_none()
+
+    async def list_rooms(self, world_id: int) -> list[WorldRoom]:
+        result = await self.db.execute(
+            select(WorldRoom).where(WorldRoom.world_id == world_id).order_by(WorldRoom.id)
+        )
+        return list(result.scalars().all())
+
+    async def create_room(
+        self,
+        world_id: int,
+        slug: str,
+        name: str,
+        *,
+        grid: dict | None = None,
+        bounds: dict | None = None,
+        spawn: dict | None = None,
+    ) -> WorldRoom:
+        room = WorldRoom(world_id=world_id, slug=slug, name=name)
+        if grid is not None:
+            room.grid = grid
+        if bounds is not None:
+            room.bounds = bounds
+        if spawn is not None:
+            room.spawn = spawn
+        self.db.add(room)
+        await self.db.flush()
+        await self.db.refresh(room)
+        return room
+
+    async def get_or_create_main_room(self, world_id: int) -> WorldRoom:
+        """world_persistence_impl.md §4.1: every world gets a ``main`` room.
+        Called from ``create_world`` for new worlds, and lazily here for
+        worlds that predate this migration."""
+        room = await self.get_room(world_id, MAIN_ROOM_SLUG)
+        if room is not None:
+            return room
+        try:
+            return await self.create_room(world_id, MAIN_ROOM_SLUG, MAIN_ROOM_NAME)
+        except IntegrityError:
+            # Lost a race with a concurrent creator; the row now exists.
+            await self.db.rollback()
+            room = await self.get_room(world_id, MAIN_ROOM_SLUG)
+            if room is None:
+                raise
+            return room
+
+    async def count_chunks(self, room_id: int) -> int:
+        result = await self.db.execute(
+            select(func.count()).select_from(WorldChunk).where(WorldChunk.room_id == room_id)
+        )
+        return int(result.scalar_one())
+
+    async def content_revision(self, world_id: int) -> int:
+        """See module docstring for why this is derived rather than stored."""
+        result = await self.db.execute(
+            select(func.max(WorldChunkRevision.id)).where(WorldChunkRevision.world_id == world_id)
+        )
+        return int(result.scalar() or 0)
+
+    # ── chunk reads ──────────────────────────────────────────────────────
+
+    async def get_chunk(self, key: str) -> WorldChunk | None:
+        result = await self.db.execute(select(WorldChunk).where(WorldChunk.chunk_key == key))
+        return result.scalar_one_or_none()
+
+    async def get_chunk_by_coord(self, room_id: int, cx: int, cy: int, cz: int) -> WorldChunk | None:
+        result = await self.db.execute(
+            select(WorldChunk).where(
+                WorldChunk.room_id == room_id, WorldChunk.cx == cx,
+                WorldChunk.cy == cy, WorldChunk.cz == cz,
+            )
+        )
+        return result.scalar_one_or_none()
+
+    async def get_chunk_binary(self, key: str) -> bytes | None:
+        chunk = await self.get_chunk(key)
+        return chunk.payload if chunk is not None else None
+
+    async def get_chunk_flags(self, key: str) -> dict | None:
+        chunk = await self.get_chunk(key)
+        return chunk.content_flags if chunk is not None else None
+
+    async def list_chunks(
+        self,
+        world_id: int,
+        room_id: int | None = None,
+        bounds: Bounds | None = None,
+    ) -> list[WorldChunk]:
+        """Index query -- world.md §5.1's ``list_chunks``. Payload bytes are
+        deliberately not loaded (world_persistence_impl.md §8.1: "Payloads
+        are not included")."""
+        query = select(WorldChunk).options(
+            load_only(
+                WorldChunk.id, WorldChunk.world_id, WorldChunk.room_id, WorldChunk.chunk_key,
+                WorldChunk.cx, WorldChunk.cy, WorldChunk.cz, WorldChunk.revision,
+                WorldChunk.checksum, WorldChunk.payload_len, WorldChunk.is_mature,
+                WorldChunk.updated_at,
+            )
+        ).where(WorldChunk.world_id == world_id)
+        if room_id is not None:
+            query = query.where(WorldChunk.room_id == room_id)
+        if bounds is not None:
+            if bounds.cx_min is not None:
+                query = query.where(WorldChunk.cx >= bounds.cx_min)
+            if bounds.cx_max is not None:
+                query = query.where(WorldChunk.cx <= bounds.cx_max)
+            if bounds.cy_min is not None:
+                query = query.where(WorldChunk.cy >= bounds.cy_min)
+            if bounds.cy_max is not None:
+                query = query.where(WorldChunk.cy <= bounds.cy_max)
+            if bounds.cz is not None:
+                query = query.where(WorldChunk.cz == bounds.cz)
+        query = query.order_by(WorldChunk.cx, WorldChunk.cy, WorldChunk.cz)
+        result = await self.db.execute(query)
+        return list(result.scalars().all())
+
+    # ── chunk writes ─────────────────────────────────────────────────────
+
+    async def put_chunk(
+        self,
+        *,
+        room: WorldRoom,
+        cx: int,
+        cy: int,
+        cz: int,
+        payload_bytes: bytes,
+        base_revision: int,
+        actor_id: int | None,
+    ) -> WorldChunk:
+        """Full-chunk write with optimistic concurrency (world.md §5.4,
+        world_persistence_impl.md §5.4/§8.2). Validates the payload
+        server-side (§5.5) before ever touching a row. ``base_revision=0``
+        means "create; 409 if it already exists"."""
+        key = chunk_codec.build_key(room.world_id, room.slug, cx, cy, cz)
+        grid_size = tuple(room.grid.get("size", [32, 32, 1]))
+
+        # Raises ChunkCodecError / ChunkValidationError -- the router maps
+        # those to 422. Nothing below trusts the request body's own claims
+        # about content_flags/is_mature; both come from `decoded`.
+        decoded = chunk_codec.decode_and_validate(
+            payload_bytes,
+            expected_key=key,
+            grid_size=grid_size,
+            max_objects=settings.WORLD_CHUNK_MAX_OBJECTS,
+        )
+        body_checksum = chunk_codec.checksum(payload_bytes[chunk_codec.HEADER_SIZE:])
+
+        result = await self.db.execute(
+            select(WorldChunk)
+            .where(
+                WorldChunk.room_id == room.id, WorldChunk.cx == cx,
+                WorldChunk.cy == cy, WorldChunk.cz == cz,
+            )
+            .with_for_update()
+        )
+        row = result.scalar_one_or_none()
+
+        if base_revision == 0:
+            if row is not None:
+                raise RevisionConflict(row.revision, row.checksum, (cx, cy, cz))
+            row = WorldChunk(
+                world_id=room.world_id, room_id=room.id, chunk_key=key,
+                cx=cx, cy=cy, cz=cz, revision=1,
+            )
+            self.db.add(row)
+            action = "create"
+        else:
+            if row is None or row.revision != base_revision:
+                raise RevisionConflict(
+                    row.revision if row else 0, row.checksum if row else None, (cx, cy, cz)
+                )
+            row.revision = row.revision + 1
+            action = "update"
+
+        row.format_version = decoded.version
+        row.payload = payload_bytes
+        row.payload_len = len(payload_bytes)
+        row.checksum = body_checksum
+        row.content_flags = decoded.flags.to_dict()
+        row.is_mature = decoded.flags.mature
+        row.updated_by_id = actor_id
+
+        try:
+            await self.db.flush()
+        except IntegrityError:
+            # Lost a create race to a concurrent writer between our SELECT
+            # and this flush. Roll back and report the real current state.
+            await self.db.rollback()
+            existing = await self.get_chunk_by_coord(room.id, cx, cy, cz)
+            raise RevisionConflict(
+                existing.revision if existing else 0,
+                existing.checksum if existing else None,
+                (cx, cy, cz),
+            )
+
+        await self._record_revision(key, room.world_id, row.revision, action, actor_id, body_checksum, payload_bytes)
+        await self.db.refresh(row)
+        return row
+
+    async def put_chunks_batch(
+        self,
+        *,
+        room: WorldRoom,
+        items: list[dict],
+        actor_id: int | None,
+    ) -> list[WorldChunk]:
+        """Batch write (world_persistence_impl.md §8.1). One transaction,
+        all-or-nothing: none of this ``commit()``s, so a ``RevisionConflict``
+        raised partway leaves nothing persisted once the caller's request
+        handler lets the exception (or the HTTPException it becomes)
+        propagate through ``get_db``, which rolls back on any exception."""
+        rows: list[WorldChunk] = []
+        for item in items:
+            row = await self.put_chunk(
+                room=room, cx=item["cx"], cy=item["cy"], cz=item["cz"],
+                payload_bytes=item["payload_bytes"], base_revision=item["base_revision"],
+                actor_id=actor_id,
+            )
+            rows.append(row)
+        return rows
+
+    async def delete_chunk(self, key: str, actor_id: int | None) -> None:
+        row = await self.get_chunk(key)
+        if row is None:
+            return
+        await self._record_revision(key, row.world_id, row.revision, "delete", actor_id, row.checksum, None)
+        await self.db.delete(row)
+        await self.db.flush()
+
+    async def rollback_chunk(self, key: str, revision: int, actor_id: int | None) -> WorldChunk:
+        """Restore a chunk to a previously-recorded revision's payload
+        (world.md §5.1). Raises ``RevisionNotAvailable`` if that revision
+        was never recorded, its payload was pruned by retention, or the
+        chunk has since been deleted outright (nothing to update in place)."""
+        rev_result = await self.db.execute(
+            select(WorldChunkRevision)
+            .where(WorldChunkRevision.chunk_key == key, WorldChunkRevision.revision == revision)
+            .order_by(WorldChunkRevision.id.desc())
+            .limit(1)
+        )
+        rev_row = rev_result.scalar_one_or_none()
+        if rev_row is None:
+            raise RevisionNotAvailable(f"no revision {revision} recorded for {key!r}")
+        if rev_row.payload is None:
+            raise RevisionNotAvailable(f"revision {revision} of {key!r} was pruned; payload unavailable")
+
+        chunk = await self.get_chunk(key)
+        if chunk is None:
+            raise RevisionNotAvailable(f"chunk {key!r} no longer exists; cannot roll back in place")
+
+        room_result = await self.db.execute(select(WorldRoom).where(WorldRoom.id == chunk.room_id))
+        room = room_result.scalar_one()
+        grid_size = tuple(room.grid.get("size", [32, 32, 1]))
+        decoded = chunk_codec.decode_and_validate(
+            rev_row.payload, expected_key=key, grid_size=grid_size,
+            max_objects=settings.WORLD_CHUNK_MAX_OBJECTS,
+        )
+        body_checksum = chunk_codec.checksum(rev_row.payload[chunk_codec.HEADER_SIZE:])
+
+        chunk.revision = chunk.revision + 1
+        chunk.payload = rev_row.payload
+        chunk.payload_len = len(rev_row.payload)
+        chunk.checksum = body_checksum
+        chunk.format_version = decoded.version
+        chunk.content_flags = decoded.flags.to_dict()
+        chunk.is_mature = decoded.flags.mature
+        chunk.updated_by_id = actor_id
+
+        await self.db.flush()
+        # Tagged "update" (not a fourth action value) to keep the
+        # documented 'create'|'update'|'delete' action enum intact.
+        await self._record_revision(
+            key, chunk.world_id, chunk.revision, "update", actor_id, body_checksum, rev_row.payload
+        )
+        await self.db.refresh(chunk)
+        return chunk
+
+    async def list_revisions(self, chunk_key: str, limit: int = 50) -> list[WorldChunkRevision]:
+        """Not in world.md §5.1's interface by name, but required to
+        implement the revision-history endpoint world_persistence_impl.md
+        §8.1 lists (``GET .../revisions``)."""
+        result = await self.db.execute(
+            select(WorldChunkRevision)
+            .where(WorldChunkRevision.chunk_key == chunk_key)
+            .order_by(WorldChunkRevision.revision.desc(), WorldChunkRevision.id.desc())
+            .limit(limit)
+        )
+        return list(result.scalars().all())
+
+    async def migrate(self) -> None:
+        """No-op. `world.md` §4.8's hand-rolled SQLite migration runner is
+        superseded by Alembic (`backend/alembic/`) now that content lives
+        in Postgres (world_persistence_impl.md §3.3). Kept only so this
+        class's shape still matches the §5.1 interface it's implementing
+        a subset of."""
+        return None
+
+    # ── internals ────────────────────────────────────────────────────────
+
+    async def _record_revision(
+        self,
+        chunk_key: str,
+        world_id: int,
+        revision: int,
+        action: str,
+        actor_id: int | None,
+        checksum_hex: str,
+        payload_bytes: bytes | None,
+    ) -> None:
+        """Append an audit row and enforce the retention policy
+        (world_persistence_impl.md §4.3, required): keep the newest
+        ``WORLD_CHUNK_REVISION_KEEP`` payloads per ``chunk_key``, null out
+        ``payload`` on older rows, in the same transaction as the write."""
+        rev = WorldChunkRevision(
+            chunk_key=chunk_key, world_id=world_id, revision=revision, action=action,
+            actor_id=actor_id, checksum=checksum_hex, payload=payload_bytes,
+        )
+        self.db.add(rev)
+        await self.db.flush()
+
+        keep = settings.WORLD_CHUNK_REVISION_KEEP
+        keep_ids_result = await self.db.execute(
+            select(WorldChunkRevision.id)
+            .where(WorldChunkRevision.chunk_key == chunk_key)
+            .order_by(WorldChunkRevision.id.desc())
+            .limit(keep)
+        )
+        keep_ids = [row[0] for row in keep_ids_result.all()]
+        if keep_ids:
+            await self.db.execute(
+                update(WorldChunkRevision)
+                .where(
+                    WorldChunkRevision.chunk_key == chunk_key,
+                    WorldChunkRevision.id.notin_(keep_ids),
+                    WorldChunkRevision.payload.isnot(None),
+                )
+                .values(payload=None)
+            )

backend/docker-compose.yml

@@ -0,0 +1,34 @@
+version: "3.9"
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: agp_user
+      POSTGRES_PASSWORD: agp_password
+      POSTGRES_DB: agp_db
+    ports:
+      - "${POSTGRES_HOST_PORT:-5432}:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U agp_user -d agp_db"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "${REDIS_HOST_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+  redis_data:

backend/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests

backend/requirements.txt

@@ -0,0 +1,25 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+sqlalchemy==2.0.36
+alembic==1.14.0
+psycopg2-binary==2.9.10
+asyncpg==0.31.0
+redis==5.2.1
+pydantic==2.10.3
+pydantic-settings==2.7.0
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+# passlib 1.7.4 (last release, unmaintained since ~2020) detects its bcrypt
+# backend via bcrypt.__about__.__version__, which bcrypt>=4.1 removed --
+# hashing/verifying a password then raises "password cannot be longer than
+# 72 bytes" (a misleading downstream symptom of the real AttributeError:
+# module 'bcrypt' has no attribute '__about__') on every call. Without this
+# pin, `pip install -r requirements.txt` silently grabs whatever the latest
+# bcrypt is and breaks register/login outright. Pin below 4.1 explicitly.
+bcrypt==4.0.1
+python-multipart==0.0.20
+email-validator==2.2.0
+httpx==0.28.1
+pytest==8.3.4
+pytest-asyncio==0.25.0
+pytest-cov==6.0.0

backend/tests/conftest.py

@@ -0,0 +1,246 @@
+"""Shared pytest fixtures + hermetic-DB/Redis bootstrap.
+
+The integration tests hit a real Postgres (Postgres-specific types: JSONB,
+native ENUMs) and, for presence tests, a real Redis (TTL semantics aren't
+worth faking). To make ``cd backend && pytest`` work from a clean checkout
+with no manual setup, ``pytest_configure`` below brings up ephemeral
+Postgres/Redis containers via docker compose and runs the migrations IF
+``DATABASE_URL``/``REDIS_URL`` aren't already pointing at something
+reachable. When they are (dev loop, or the checkpoint runner which stands
+these up itself), that path is skipped and the existing services are
+reused.
+
+If Docker isn't available and nothing is reachable, the whole
+DB/Redis-backed suite is skipped with a clear message rather than erroring
+out dozens of times.
+"""
+
+import asyncio
+import hashlib
+import os
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import pytest
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.database import get_db
+from app.main import app
+
+TEST_TABLES = (
+    "avatar_loadouts", "assets",
+    # world_chunk_revisions has no FK to worlds/world_chunks (world.md §4.7 /
+    # world_persistence_impl.md §4.3, deliberate -- deleting a chunk or world
+    # must not lose the audit trail), so it won't be cascade-truncated via
+    # `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",
+    "worlds",
+    # Social graph (app/models/social.py) -- all three FK users with
+    # ON DELETE CASCADE, but list explicitly for clarity/consistency.
+    "friendships", "follows", "blocks",
+    # Chat (app/models/chat.py). message_reports.message_id is ON DELETE SET
+    # NULL (not CASCADE, deliberately -- see chat.py), so it wouldn't be
+    # reached by cascading a truncate of messages/conversations; list it
+    # explicitly along with the rest for clarity/consistency.
+    "message_reports", "messages", "conversation_participants", "conversations",
+    # Groups (app/models/groups.py). groups.owner_id is ON DELETE SET NULL
+    # (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",
+    "sessions", "refresh_tokens", "users",
+)
+
+BACKEND_DIR = Path(__file__).resolve().parents[1]
+
+# A hardcoded project name/port here would mean every concurrent checkout
+# running `pytest` (e.g. several Claude Agent-tool subagents, each in their
+# own ~/agp/workspace/task_<id> clone) fights over the exact same Docker
+# Compose project and host ports -- one run's pytest_unconfigure teardown
+# can yank the ephemeral Postgres out from under a completely unrelated
+# concurrent run, surfacing as "connection was closed in the middle of
+# operation" with no obvious cause. Confirmed live 2026-09-15 running 3
+# parallel subagents. Same root cause and fix pattern as the agent_core
+# workspace/Docker-Compose collision documented in project_agp memory --
+# derive both the project name and the port from a hash of the checkout
+# directory, so different concurrent checkouts land on different projects/
+# ports while the same checkout is stable across repeated runs.
+_WORKSPACE_HASH = hashlib.sha256(str(BACKEND_DIR.parent).encode()).hexdigest()[:10]
+_COMPOSE_PROJECT = f"agp-pytest-{_WORKSPACE_HASH}"
+_EPHEMERAL_PG_PORT = 25400 + (int(_WORKSPACE_HASH, 16) % 100)
+_EPHEMERAL_REDIS_PORT = 26300 + (int(_WORKSPACE_HASH, 16) % 100)
+
+# Set by pytest_configure() when it starts container(s) it owns; torn down in
+# pytest_unconfigure.
+_started_container = False
+_db_unavailable_reason: str | None = None
+
+
+def _port_open(host: str, port: int, timeout: float = 1.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def _db_reachable(url: str) -> bool:
+    parts = urlsplit(url)
+    return _port_open(parts.hostname or "localhost", parts.port or 5432)
+
+
+def _redis_reachable(url: str) -> bool:
+    parts = urlsplit(url)
+    return _port_open(parts.hostname or "localhost", parts.port or 6379)
+
+
+def _run(cmd: list[str], **kw) -> subprocess.CompletedProcess:
+    return subprocess.run(cmd, cwd=BACKEND_DIR, capture_output=True, text=True, **kw)
+
+
+def pytest_configure(config):
+    global _started_container, _db_unavailable_reason
+
+    need_db = not _db_reachable(settings.DATABASE_URL)
+    need_redis = not _redis_reachable(settings.REDIS_URL)
+
+    if not need_db and not need_redis:
+        return  # dev loop / checkpoint runner already provided both
+
+    if not _run(["docker", "--version"]).returncode == 0:
+        _db_unavailable_reason = (
+            "no reachable DATABASE_URL/REDIS_URL and docker is unavailable -- run "
+            "the checkpoint suite (scripts/run_checkpoint_tests.py) or start "
+            "Postgres/Redis manually"
+        )
+        return
+
+    env = os.environ.copy()
+    env["COMPOSE_PROJECT_NAME"] = _COMPOSE_PROJECT
+    env["POSTGRES_HOST_PORT"] = str(_EPHEMERAL_PG_PORT)
+    env["POSTGRES_PORT"] = str(_EPHEMERAL_PG_PORT)
+    env["REDIS_HOST_PORT"] = str(_EPHEMERAL_REDIS_PORT)
+
+    services = [s for s, need in (("postgres", need_db), ("redis", need_redis)) if need]
+    up = _run(["docker", "compose", "up", "-d", *services], env=env)
+    if up.returncode != 0:
+        _db_unavailable_reason = f"docker compose up {' '.join(services)} failed:\n{up.stderr[-800:]}"
+        return
+    _started_container = True
+
+    if need_db:
+        for _ in range(30):
+            r = _run(
+                ["docker", "compose", "exec", "-T", "postgres",
+                 "pg_isready", "-U", "agp_user", "-d", "agp_db"],
+                env=env,
+            )
+            if r.returncode == 0:
+                break
+            time.sleep(1)
+        else:
+            _db_unavailable_reason = "ephemeral Postgres never became ready"
+            return
+
+        url = f"postgresql+asyncpg://agp_user:agp_password@localhost:{_EPHEMERAL_PG_PORT}/agp_db"
+        os.environ["DATABASE_URL"] = url
+        settings.DATABASE_URL = url
+
+        mig = _run([sys.executable, "-m", "alembic", "upgrade", "head"],
+                   env={**os.environ, "DATABASE_URL": url})
+        if mig.returncode != 0:
+            _db_unavailable_reason = f"alembic upgrade head failed:\n{mig.stderr[-800:]}"
+            return
+
+    if need_redis:
+        for _ in range(30):
+            r = _run(
+                ["docker", "compose", "exec", "-T", "redis", "redis-cli", "ping"],
+                env=env,
+            )
+            if r.returncode == 0 and "PONG" in r.stdout:
+                break
+            time.sleep(1)
+        else:
+            _db_unavailable_reason = "ephemeral Redis never became ready"
+            return
+
+        redis_url = f"redis://localhost:{_EPHEMERAL_REDIS_PORT}/0"
+        os.environ["REDIS_URL"] = redis_url
+        settings.REDIS_URL = redis_url
+
+
+def pytest_unconfigure(config):
+    if not _started_container:
+        return
+    env = os.environ.copy()
+    env["COMPOSE_PROJECT_NAME"] = _COMPOSE_PROJECT
+    env["POSTGRES_HOST_PORT"] = str(_EPHEMERAL_PG_PORT)
+    env["POSTGRES_PORT"] = str(_EPHEMERAL_PG_PORT)
+    env["REDIS_HOST_PORT"] = str(_EPHEMERAL_REDIS_PORT)
+    _run(["docker", "compose", "down", "-v"], env=env)
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _reset_database():
+    """Truncate all application tables once per test session."""
+    if _db_unavailable_reason:
+        pytest.skip(_db_unavailable_reason, allow_module_level=True)
+
+    async def _truncate() -> None:
+        engine = create_async_engine(settings.DATABASE_URL)
+        async with engine.begin() as conn:
+            await conn.execute(text(f"TRUNCATE TABLE {', '.join(TEST_TABLES)} CASCADE"))
+        await engine.dispose()
+
+    asyncio.run(_truncate())
+    yield
+
+
+@pytest.fixture(autouse=True)
+def _reset_rate_limiter():
+    """Every TestClient request looks like the same client IP, so the
+    per-IP auth limiter would trip mid-suite. Clear it between tests; the
+    dedicated rate-limit test disables this to exercise the real behaviour.
+    """
+    from app import rate_limit
+    rate_limit.reset_all()
+    yield
+
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test.
+
+    Deliberately does NOT reuse app.database's shared engine: FastAPI's
+    (sync) TestClient runs each request through anyio's blocking-portal
+    machinery, which can hand different requests different event loops.
+    asyncpg connections are bound to the loop they were created on, so
+    reusing one from the shared pool across requests raises "attached to a
+    different loop" the moment a test makes more than one request. NullPool
+    sidesteps it: every checkout is a brand-new connection.
+    """
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()

backend/tests/fixtures/chunks/generate_fixtures.py

@@ -0,0 +1,105 @@
+"""Generates the golden-file chunk fixtures in this directory.
+
+These pin the world.md §3.6 binary format so the Python codec
+(app/services/chunk_codec.py) and any future Godot-side test fixture can be
+checked for drift (world_persistence_impl.md §5.5's "drift control"
+requirement). No Godot-side golden fixture existed at the time this was
+written (searched scripts/ and tests/ for AGPC / binary-format test
+vectors -- none found), so these are authored here, from this
+implementation, as the first golden files for the format. The client/editor
+follow-on task should decode these same files with
+`ChunkDataDecoder.decode_binary()` and assert the same logical values
+(see the note in chunk_codec.py about a confirmed float32 handling bug in
+that decoder that will need fixing for full byte parity on non-integer
+transforms).
+
+Run with: `python tests/fixtures/chunks/generate_fixtures.py` from `backend/`.
+Fixtures are checked in; this script is for regenerating them if the format
+or these examples change, not run as part of the test suite.
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))  # backend/
+
+from app.services import chunk_codec as cc
+
+FIXTURES_DIR = Path(__file__).resolve().parent
+
+
+def _empty_chunk() -> cc.ChunkPayload:
+    return cc.ChunkPayload(
+        world_id="7", room_id="main", coord=(0, 0, 0),
+        bounds=cc.ChunkBounds(min=(0.0, 0.0, 0.0), size=(32.0, 32.0, 1.0)),
+        tile_layers=[], objects=[],
+        flags=cc.ContentFlags(),
+        created_at=1_700_000_000, updated_at=1_700_000_000, revision=1, author="fixture-gen",
+    )
+
+
+def _simple_tile_chunk() -> cc.ChunkPayload:
+    layer = cc.TileLayer(
+        name="ground", layer_id=0, width=4, height=4, depth=1,
+        palette=[
+            cc.TileDef(id=0, asset_id="", solid=False, flags=0, variants=1),
+            cc.TileDef(id=1, asset_id="tiles/grass", solid=False, flags=1, variants=4),
+            cc.TileDef(id=2, asset_id="tiles/stone", solid=True, flags=2, variants=2),
+        ],
+        tiles=[0, 1, 1, 0, 1, 2, 2, 1, 1, 2, 2, 1, 0, 1, 1, 0],
+    )
+    return cc.ChunkPayload(
+        world_id="12", room_id="main", coord=(3, -1, 0),
+        bounds=cc.ChunkBounds(min=(96.0, -32.0, 0.0), size=(32.0, 32.0, 1.0)),
+        tile_layers=[layer], objects=[],
+        flags=cc.ContentFlags(violence=0, mature=False, sources=[]),
+        created_at=1_700_000_000, updated_at=1_700_000_500, revision=2, author="fixture-gen",
+    )
+
+
+def _chunk_with_objects() -> cc.ChunkPayload:
+    layer = cc.TileLayer(
+        name="ground", layer_id=0, width=2, height=2, depth=1,
+        palette=[cc.TileDef(id=0, asset_id="", solid=False, flags=0, variants=1)],
+        tiles=[0, 0, 0, 0],
+    )
+    obj1 = cc.WorldObject(
+        id="obj_0001", type="interactable", asset_id="props/chest",
+        pos=(101.5, -110.25, 0.5), rot=(0.0, 0.0, 0.0, 1.0), scale=(1.0, 1.0, 1.0),
+        dynamic=False,
+        properties={"locked": False, "loot_table": "chest_basic"},
+        flags=cc.ContentFlags(violence=0, mature=False, sources=[]),
+    )
+    obj2 = cc.WorldObject(
+        id="obj_0002", type="spawn_point", asset_id="",
+        pos=(96.0, -128.0, 1.0), rot=(0.0, 0.7071, 0.0, 0.7071), scale=(1.0, 1.0, 1.0),
+        dynamic=True,
+        properties={},
+        flags=cc.ContentFlags(violence=1, mature=False, sources=["asset:props/chest"]),
+    )
+    return cc.ChunkPayload(
+        world_id="12", room_id="main", coord=(3, -4, 0),
+        bounds=cc.ChunkBounds(min=(96.0, -128.0, 0.0), size=(32.0, 32.0, 1.0)),
+        tile_layers=[layer], objects=[obj1, obj2],
+        flags=cc.ContentFlags(violence=1, mature=False, sources=["asset:props/chest"]),
+        created_at=1_700_000_000, updated_at=1_700_001_000, revision=5, author="agent-bot",
+    )
+
+
+FIXTURES = {
+    "empty_chunk.bin": _empty_chunk,
+    "simple_tile_chunk.bin": _simple_tile_chunk,
+    "chunk_with_objects.bin": _chunk_with_objects,
+}
+
+
+def main() -> None:
+    for filename, builder in FIXTURES.items():
+        payload = builder()
+        data = cc.encode_binary(payload)
+        (FIXTURES_DIR / filename).write_bytes(data)
+        print(f"wrote {filename} ({len(data)} bytes)")
+
+
+if __name__ == "__main__":
+    main()

backend/tests/test_auth_age_gate.py

@@ -0,0 +1,104 @@
+"""Tests for the 18+ age gate on user registration."""
+
+from datetime import date, timedelta
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.routers.auth import calculate_age, MIN_AGE, RegisterRequest
+
+
+class TestCalculateAge:
+    """Unit tests for the calculate_age helper."""
+
+    def test_exactly_18(self):
+        today = date(2026, 6, 15)
+        dob = today.replace(year=today.year - 18)
+        assert calculate_age(dob, today=today) == 18
+
+    def test_just_turned_18(self):
+        today = date(2026, 6, 15)
+        dob = today.replace(year=today.year - 18) - timedelta(days=1)
+        assert calculate_age(dob, today=today) == 18
+
+    def test_one_day_short_of_18(self):
+        today = date(2026, 6, 15)
+        dob = today.replace(year=today.year - 18) + timedelta(days=1)
+        assert calculate_age(dob, today=today) == 17
+
+    def test_leap_day_birthday_before(self):
+        assert calculate_age(date(2000, 2, 29), today=date(2024, 2, 28)) == 23
+
+    def test_leap_day_birthday_after(self):
+        assert calculate_age(date(2000, 2, 29), today=date(2024, 3, 1)) == 24
+
+
+class TestRegisterRequestDob:
+    def test_dob_parsed_from_iso_string(self):
+        req = RegisterRequest(username="u", email="u@example.com", password="p",
+                              date_of_birth="1990-01-01")
+        assert req.date_of_birth == date(1990, 1, 1)
+
+    def test_dob_required(self):
+        with pytest.raises(Exception):
+            RegisterRequest(username="u", email="u@example.com", password="p")
+
+    def test_bad_dob_string_rejected(self):
+        with pytest.raises(Exception):
+            RegisterRequest(username="u", email="u@example.com", password="p",
+                            date_of_birth="not-a-date")
+
+
+class TestRegisterAgeGate:
+    """End-to-end: the /register endpoint computes age from the DOB."""
+
+    def _dob_for_age(self, years: int) -> str:
+        return (date.today().replace(year=date.today().year - years)).isoformat()
+
+    def test_adult_accepted(self):
+        client = TestClient(app)
+        r = client.post("/api/auth/register", json={
+            "username": "gate_adult", "email": "gate_adult@e.com",
+            "password": "secret123", "date_of_birth": self._dob_for_age(25),
+        })
+        assert r.status_code == 201, r.text
+
+    def test_minor_rejected(self):
+        client = TestClient(app)
+        r = client.post("/api/auth/register", json={
+            "username": "gate_minor", "email": "gate_minor@e.com",
+            "password": "secret123", "date_of_birth": self._dob_for_age(15),
+        })
+        assert r.status_code == 403
+        assert str(MIN_AGE) in r.json()["detail"]
+
+    def test_exactly_18_accepted(self):
+        client = TestClient(app)
+        r = client.post("/api/auth/register", json={
+            "username": "gate_18", "email": "gate_18@e.com",
+            "password": "secret123",
+            "date_of_birth": (date.today().replace(year=date.today().year - 18) - timedelta(days=1)).isoformat(),
+        })
+        assert r.status_code == 201, r.text
+
+    def test_future_dob_rejected(self):
+        client = TestClient(app)
+        r = client.post("/api/auth/register", json={
+            "username": "gate_future", "email": "gate_future@e.com",
+            "password": "secret123", "date_of_birth": "2999-01-01",
+        })
+        assert r.status_code == 400
+
+    def test_dob_is_stored(self):
+        client = TestClient(app)
+        dob = self._dob_for_age(30)
+        reg = client.post("/api/auth/register", json={
+            "username": "gate_stored", "email": "gate_stored@e.com",
+            "password": "secret123", "date_of_birth": dob,
+        })
+        assert reg.status_code == 201
+        me = client.get("/api/auth/me", headers={
+            "Authorization": f"Bearer {reg.json()['access_token']}"
+        })
+        assert me.json()["date_of_birth"] == dob

backend/tests/test_auth_endpoints.py

@@ -0,0 +1,251 @@
+"""Integration tests for the auth endpoints (register + login).
+
+These tests hit the real FastAPI app against the real configured database
+(DATABASE_URL -- Postgres via Alembic migrations in CI/dev, not an isolated
+in-memory DB), so they exercise the full stack: Pydantic validation → DB →
+JWT → response. Requires migrations already applied (alembic upgrade head)
+before running.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+from app.routers.auth import pwd_context
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test.
+
+    Deliberately does NOT reuse app.database's shared engine: FastAPI's
+    (sync) TestClient runs each request through anyio's blocking-portal
+    machinery, which can hand different requests different event loops.
+    asyncpg connections are bound to the loop they were created on, so
+    reusing one from the shared engine's connection pool across requests
+    raises "cannot perform operation: another operation is in progress" the
+    moment a test makes more than one request (register-then-login,
+    register-twice, etc.) -- confirmed this is the actual cause, not a bug
+    in the endpoints themselves. NullPool sidesteps it: every checkout is a
+    brand-new connection, never handed to a different loop than the one
+    that opened it.
+    """
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Register endpoint
+# ---------------------------------------------------------------------------
+
+class TestRegister:
+    """Tests for POST /api/auth/register."""
+
+    def test_register_success(self):
+        """A valid registration returns 201 with a token."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "newuser",
+                "email": "new@example.com",
+                "password": "secret123",
+                "date_of_birth": "1990-01-01",
+            },
+        )
+        assert resp.status_code == 201
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+
+    def test_register_rejects_under_18(self):
+        """A DOB that computes to under 18 gets a 403 (see test_auth_age_gate
+        for the age-math coverage)."""
+        from datetime import date
+        client = TestClient(app)
+        minor_dob = date.today().replace(year=date.today().year - 14).isoformat()
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "kid",
+                "email": "kid@example.com",
+                "password": "secret123",
+                "date_of_birth": minor_dob,
+            },
+        )
+        assert resp.status_code == 403
+        assert "at least 18" in resp.json()["detail"]
+
+    def test_register_rejects_duplicate_username(self):
+        """Registering the same username twice returns 409."""
+        client = TestClient(app)
+        # First registration
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "duplicate",
+                "email": "dup1@example.com",
+                "password": "secret123",
+                "date_of_birth": "1990-01-01",
+            },
+        )
+        # Second registration with same username, different email
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "duplicate",
+                "email": "dup2@example.com",
+                "password": "secret123",
+                "date_of_birth": "1990-01-01",
+            },
+        )
+        assert resp.status_code == 409
+        assert "Username already registered" in resp.json()["detail"]
+
+    def test_register_rejects_duplicate_email(self):
+        """Registering the same email twice returns 409."""
+        client = TestClient(app)
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "user1",
+                "email": "same@example.com",
+                "password": "secret123",
+                "date_of_birth": "1990-01-01",
+            },
+        )
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "user2",
+                "email": "same@example.com",
+                "password": "secret123",
+                "date_of_birth": "1990-01-01",
+            },
+        )
+        assert resp.status_code == 409
+        assert "Email already registered" in resp.json()["detail"]
+
+    def test_register_missing_dob(self):
+        """Missing the required date_of_birth field returns 422."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "user",
+                "email": "user@example.com",
+                "password": "secret123",
+            },
+        )
+        assert resp.status_code == 422
+
+
+# ---------------------------------------------------------------------------
+# Login endpoint
+# ---------------------------------------------------------------------------
+
+class TestLogin:
+    """Tests for POST /api/auth/login."""
+
+    def _create_user(self, username: str, password: str, email: str = None):
+        """Helper to create a user via register."""
+        client = TestClient(app)
+        if email is None:
+            email = f"{username}@example.com"
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": username,
+                "email": email,
+                "password": password,
+                "date_of_birth": "1990-01-01",
+            },
+        )
+        assert resp.status_code == 201
+        return resp.json()["access_token"]
+
+    def test_login_success(self):
+        """Correct credentials return a token."""
+        self._create_user("loginuser", "correctpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "loginuser", "password": "correctpass"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+
+    def test_login_wrong_password(self):
+        """Wrong password returns 401."""
+        # Distinct username from test_login_success -- there's no per-test
+        # DB rollback/isolation here (real Postgres via the app's own
+        # dependency-overridden session), so reusing "loginuser" collided
+        # with the user that test already created (409 on register instead
+        # of the intended 401-on-login assertion this test is actually for).
+        self._create_user("loginuser_wrongpass", "correctpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "loginuser_wrongpass", "password": "wrongpass"},
+        )
+        assert resp.status_code == 401
+        assert "Incorrect username or password" in resp.json()["detail"]
+
+    def test_login_nonexistent_user(self):
+        """Non-existent user returns 401 (not 404)."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "nobody", "password": "any"},
+        )
+        assert resp.status_code == 401
+        assert "Incorrect username or password" in resp.json()["detail"]
+
+    def test_login_accepts_form_encoded(self):
+        """Login accepts application/x-www-form-urlencoded (OAuth2)."""
+        self._create_user("formuser", "formpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "formuser", "password": "formpass"},
+        )
+        assert resp.status_code == 200
+        assert "access_token" in resp.json()
+
+    def test_login_token_is_valid_jwt(self):
+        """The returned token is a valid JWT that can be decoded."""
+        self._create_user("jwttoken", "jwt123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "jwttoken", "password": "jwt123"},
+        )
+        token = resp.json()["access_token"]
+        # Verify it's a 3-part JWT
+        parts = token.split(".")
+        assert len(parts) == 3

backend/tests/test_auth_expired_token.py

@@ -0,0 +1,171 @@
+"""Tests for expired-token rejection across auth endpoints.
+
+Covers two distinct expiry paths:
+
+1. An *access* JWT whose ``exp`` claim is in the past must be rejected
+   with 401 by ``GET /api/auth/me`` (jose's built-in ``exp`` validation).
+2. A *refresh* token whose persisted ``expires_at`` is in the past must be
+   rejected with 401 by ``POST /api/auth/refresh`` even though its JWT
+   signature is still valid.
+
+Requires migrations already applied (alembic upgrade head) before running.
+"""
+
+import asyncio
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from fastapi.testclient import TestClient
+from jose import jwt
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+from app.models.session import RefreshToken
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test."""
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _mint_access_token(exp: datetime) -> str:
+    """Mint an RS256 access token with an explicit ``exp`` claim."""
+    return jwt.encode(
+        {"sub": "1", "exp": exp},
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def _expire_refresh_token_in_db(token: str) -> None:
+    """Set the persisted refresh token's ``expires_at`` into the past."""
+
+    async def _do():
+        engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        async with session_factory() as session:
+            from sqlalchemy import update
+
+            await session.execute(
+                update(RefreshToken)
+                .where(RefreshToken.token == token)
+                .values(expires_at=datetime.now(timezone.utc) - timedelta(hours=1))
+            )
+            await session.commit()
+        await engine.dispose()
+
+    asyncio.run(_do())
+
+
+def _register_user(client: TestClient, username: str) -> str:
+    """Register a user and return its refresh token."""
+    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
+    return resp.json()["refresh_token"]
+
+
+# ---------------------------------------------------------------------------
+# Expired access token (GET /api/auth/me)
+# ---------------------------------------------------------------------------
+
+class TestExpiredAccessToken:
+    def test_expired_access_token_is_rejected_by_me(self):
+        """An access JWT with a past exp claim returns 401 on /me."""
+        client = TestClient(app)
+        expired_token = _mint_access_token(
+            datetime.now(timezone.utc) - timedelta(minutes=5)
+        )
+        resp = client.get(
+            "/api/auth/me",
+            headers={"Authorization": f"Bearer {expired_token}"},
+        )
+        assert resp.status_code == 401
+        assert "Could not validate credentials" in resp.json()["detail"]
+
+    def test_garbage_access_token_is_rejected_by_me(self):
+        """A non-JWT bearer token returns 401 on /me."""
+        client = TestClient(app)
+        resp = client.get(
+            "/api/auth/me",
+            headers={"Authorization": "Bearer not-a-real-jwt"},
+        )
+        assert resp.status_code == 401
+
+    def test_missing_bearer_token_returns_401(self):
+        """No Authorization header at all returns 401 on /me."""
+        client = TestClient(app)
+        resp = client.get("/api/auth/me")
+        assert resp.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# Expired refresh token (POST /api/auth/refresh)
+# ---------------------------------------------------------------------------
+
+class TestExpiredRefreshToken:
+    def test_expired_refresh_token_is_rejected(self):
+        """A refresh token whose DB expires_at is in the past returns 401."""
+        client = TestClient(app)
+        refresh_token = _register_user(client, "expired_rt_user")
+
+        # Force the persisted record to be expired while its JWT signature
+        # is still valid.
+        _expire_refresh_token_in_db(refresh_token)
+
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]
+
+    def test_expired_refresh_token_jwt_is_rejected(self):
+        """A refresh JWT with a past exp claim is rejected before DB lookup."""
+        client = TestClient(app)
+        expired_jwt = jwt.encode(
+            {"sub": "1", "exp": datetime.now(timezone.utc) - timedelta(minutes=5)},
+            settings.private_pem,
+            algorithm=settings.ALGORITHM,
+        )
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": expired_jwt},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]

backend/tests/test_avatar_loadout.py

@@ -0,0 +1,91 @@
+"""Integration tests for GET/PUT /api/avatar/loadout.
+
+Hits the real app against the configured Postgres (same contract as the
+other integration tests -- migrations applied first).
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.models.avatar_loadout import DEFAULT_LOADOUT
+
+
+def _auth_headers(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
+    return {"Authorization": f"Bearer {resp.json()['access_token']}"}
+
+
+class TestGetLoadout:
+    def test_new_user_gets_the_default(self):
+        client = TestClient(app)
+        headers = _auth_headers(client, "av_default")
+        resp = client.get("/api/avatar/loadout", headers=headers)
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["is_default"] is True
+        assert body["data"] == DEFAULT_LOADOUT
+
+    def test_requires_auth(self):
+        client = TestClient(app)
+        assert client.get("/api/avatar/loadout").status_code == 401
+
+
+class TestPutLoadout:
+    def test_save_then_read_back(self):
+        client = TestClient(app)
+        headers = _auth_headers(client, "av_save")
+        loadout = {
+            "base_body": "base_human_male_01",
+            "slots": {"hair": "hair_mohawk_01", "accessory": ["accessory_belt_01"]},
+            "skin_tone": {"r": 0.8, "g": 0.6, "b": 0.5, "a": 1.0},
+        }
+        put = client.put("/api/avatar/loadout", headers=headers, json={"data": loadout})
+        assert put.status_code == 200, put.text
+        assert put.json()["is_default"] is False
+
+        got = client.get("/api/avatar/loadout", headers=headers)
+        assert got.status_code == 200
+        assert got.json()["is_default"] is False
+        assert got.json()["data"] == loadout
+
+    def test_put_is_idempotent_replace(self):
+        client = TestClient(app)
+        headers = _auth_headers(client, "av_replace")
+        client.put(
+            "/api/avatar/loadout", headers=headers,
+            json={"data": {"base_body": "base_human_male_01", "slots": {"hair": "hair_mohawk_01"}}},
+        )
+        second = {"base_body": "base_human_male_01", "slots": {"chest": "chest_bandit_01"}}
+        client.put("/api/avatar/loadout", headers=headers, json={"data": second})
+        got = client.get("/api/avatar/loadout", headers=headers)
+        assert got.json()["data"] == second
+
+    def test_rejects_missing_base_body(self):
+        client = TestClient(app)
+        headers = _auth_headers(client, "av_nobase")
+        resp = client.put("/api/avatar/loadout", headers=headers, json={"data": {"slots": {}}})
+        assert resp.status_code == 422
+
+    def test_rejects_non_object_slots(self):
+        client = TestClient(app)
+        headers = _auth_headers(client, "av_badslots")
+        resp = client.put(
+            "/api/avatar/loadout", headers=headers,
+            json={"data": {"base_body": "base_human_male_01", "slots": "nope"}},
+        )
+        assert resp.status_code == 422
+
+    def test_requires_auth(self):
+        client = TestClient(app)
+        resp = client.put("/api/avatar/loadout", json={"data": {"base_body": "x", "slots": {}}})
+        assert resp.status_code == 401

backend/tests/test_chat_models.py

@@ -0,0 +1,344 @@
+"""Model-level tests for chat: conversations, messages, message reports.
+
+app/models/chat.py / alembic/versions/0008_add_chat_tables.py
+(docs/planning/social.md US-4). This is the models+migration task only --
+there are no API endpoints yet (sibling tasks own filtering, rate limiting,
+and the routers), so these tests exercise the ORM models and the real
+Postgres constraints directly rather than going through HTTP.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import delete, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.models.chat import (
+    Conversation,
+    ConversationParticipant,
+    Message,
+    MessageReport,
+    ReportStatus,
+)
+from app.models.user import User
+from app.models.world import World
+
+
+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)
+
+
+class TestConversationCreation:
+    async def test_create_conversation_with_participants_and_messages(self):
+        client = TestClient(app)
+        a = _register(client, "chat_conv_a")
+        b = _register(client, "chat_conv_b")
+
+        engine, factory = _session_factory()
+        try:
+            lo, hi = sorted((a, b))
+            async with factory() as session:
+                convo = Conversation(user_a_id=lo, user_b_id=hi)
+                session.add(convo)
+                await session.flush()
+                session.add_all(
+                    [
+                        ConversationParticipant(conversation_id=convo.id, user_id=a),
+                        ConversationParticipant(conversation_id=convo.id, user_id=b),
+                    ]
+                )
+                session.add(
+                    Message(sender_id=a, conversation_id=convo.id, body="hi there")
+                )
+                await session.commit()
+                convo_id = convo.id
+
+            async with factory() as session:
+                participants = (
+                    await session.execute(
+                        select(ConversationParticipant).where(
+                            ConversationParticipant.conversation_id == convo_id
+                        )
+                    )
+                ).scalars().all()
+                messages = (
+                    await session.execute(
+                        select(Message).where(Message.conversation_id == convo_id)
+                    )
+                ).scalars().all()
+                assert len(participants) == 2
+                assert len(messages) == 1
+                assert messages[0].sender_id == a
+                assert messages[0].filtered is False
+        finally:
+            await engine.dispose()
+
+    async def test_duplicate_pair_rejected(self):
+        client = TestClient(app)
+        a = _register(client, "chat_uq_a")
+        b = _register(client, "chat_uq_b")
+        lo, hi = sorted((a, b))
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                session.add(Conversation(user_a_id=lo, user_b_id=hi))
+                await session.commit()
+
+            async with factory() as session:
+                session.add(Conversation(user_a_id=lo, user_b_id=hi))
+                with pytest.raises(IntegrityError):
+                    await session.commit()
+        finally:
+            await engine.dispose()
+
+    async def test_unordered_pair_rejected_by_check_constraint(self):
+        client = TestClient(app)
+        a = _register(client, "chat_ck_a")
+        b = _register(client, "chat_ck_b")
+        lo, hi = sorted((a, b))
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                # Reversed order violates ck_conversations_ordered_pair.
+                session.add(Conversation(user_a_id=hi, user_b_id=lo))
+                with pytest.raises(IntegrityError):
+                    await session.commit()
+        finally:
+            await engine.dispose()
+
+
+class TestWorldRoomChat:
+    async def test_world_message_has_null_conversation(self):
+        client = TestClient(app)
+        owner = _register(client, "chat_world_owner")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                world = World(name="Chat Test World", owner_id=owner)
+                session.add(world)
+                await session.flush()
+                msg = Message(sender_id=owner, world_id=world.id, body="hello world")
+                session.add(msg)
+                await session.commit()
+                world_id = world.id
+
+            async with factory() as session:
+                rows = (
+                    await session.execute(
+                        select(Message).where(Message.world_id == world_id)
+                    )
+                ).scalars().all()
+                assert len(rows) == 1
+                assert rows[0].conversation_id is None
+                assert rows[0].room_id is None
+        finally:
+            await engine.dispose()
+
+
+class TestMessageReports:
+    async def test_create_report_defaults_to_open(self):
+        client = TestClient(app)
+        sender = _register(client, "chat_rpt_sender")
+        reporter = _register(client, "chat_rpt_reporter")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                world = World(name="Report World", owner_id=sender)
+                session.add(world)
+                await session.flush()
+                msg = Message(sender_id=sender, world_id=world.id, body="bad words")
+                session.add(msg)
+                await session.flush()
+                report = MessageReport(
+                    message_id=msg.id, reporter_id=reporter, reason="spam"
+                )
+                session.add(report)
+                await session.commit()
+                report_id = report.id
+
+            async with factory() as session:
+                report = await session.get(MessageReport, report_id)
+                assert report.status == ReportStatus.OPEN
+                assert report.moderator_id is None
+                assert report.resolved_at is None
+        finally:
+            await engine.dispose()
+
+
+class TestCascadeDelete:
+    async def test_deleting_conversation_deletes_participants_and_messages(self):
+        client = TestClient(app)
+        a = _register(client, "chat_cd_conv_a")
+        b = _register(client, "chat_cd_conv_b")
+        lo, hi = sorted((a, b))
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                convo = Conversation(user_a_id=lo, user_b_id=hi)
+                session.add(convo)
+                await session.flush()
+                session.add_all(
+                    [
+                        ConversationParticipant(conversation_id=convo.id, user_id=a),
+                        ConversationParticipant(conversation_id=convo.id, user_id=b),
+                    ]
+                )
+                session.add(Message(sender_id=a, conversation_id=convo.id, body="bye"))
+                await session.commit()
+                convo_id = convo.id
+
+            async with factory() as session:
+                # Core delete against the conversations table directly, so
+                # the real ON DELETE CASCADE does the work (not the ORM).
+                await session.execute(
+                    delete(Conversation).where(Conversation.id == convo_id)
+                )
+                await session.commit()
+
+            async with factory() as session:
+                participants = (
+                    await session.execute(
+                        select(ConversationParticipant).where(
+                            ConversationParticipant.conversation_id == convo_id
+                        )
+                    )
+                ).scalars().all()
+                messages = (
+                    await session.execute(
+                        select(Message).where(Message.conversation_id == convo_id)
+                    )
+                ).scalars().all()
+                assert participants == []
+                assert messages == []
+        finally:
+            await engine.dispose()
+
+    async def test_deleting_user_removes_conversation_but_keeps_report_and_message_id_null(self):
+        """Deleting a conversation participant cascades away the whole DM
+        (conversation + participants + messages -- there's no third party
+        left to care about the history). Deleting the sender of a
+        world-chat message, by contrast, must NOT delete the message or its
+        report -- sender_id is SET NULL and message_reports.message_id
+        follows the message (also SET NULL, never CASCADE) so the audit
+        trail survives account deletion."""
+        client = TestClient(app)
+        a = _register(client, "chat_cd_user_a")
+        b = _register(client, "chat_cd_user_b")
+        reporter = _register(client, "chat_cd_user_reporter")
+        lo, hi = sorted((a, b))
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                convo = Conversation(user_a_id=lo, user_b_id=hi)
+                session.add(convo)
+                await session.flush()
+                session.add_all(
+                    [
+                        ConversationParticipant(conversation_id=convo.id, user_id=a),
+                        ConversationParticipant(conversation_id=convo.id, user_id=b),
+                    ]
+                )
+                session.add(Message(sender_id=a, conversation_id=convo.id, body="dm"))
+
+                world = World(name="Sender Delete World", owner_id=b)
+                session.add(world)
+                await session.flush()
+                world_msg = Message(sender_id=a, world_id=world.id, body="world chat")
+                session.add(world_msg)
+                await session.flush()
+                report = MessageReport(
+                    message_id=world_msg.id, reporter_id=reporter, reason="rude"
+                )
+                session.add(report)
+                await session.commit()
+                convo_id = convo.id
+                world_msg_id = world_msg.id
+                report_id = report.id
+
+            async with factory() as session:
+                # Delete `a`: participant in the DM (cascades the whole
+                # conversation) and sender of the world message (SET NULL).
+                await session.execute(delete(User).where(User.id == a))
+                await session.commit()
+
+            async with factory() as session:
+                convo_row = await session.get(Conversation, convo_id)
+                dm_messages = (
+                    await session.execute(
+                        select(Message).where(Message.conversation_id == convo_id)
+                    )
+                ).scalars().all()
+                world_msg = await session.get(Message, world_msg_id)
+                report = await session.get(MessageReport, report_id)
+
+                assert convo_row is None
+                assert dm_messages == []
+                # World message survives with sender_id nulled out.
+                assert world_msg is not None
+                assert world_msg.sender_id is None
+                assert world_msg.body == "world chat"
+                # Report still points at the surviving message.
+                assert report is not None
+                assert report.message_id == world_msg_id
+        finally:
+            await engine.dispose()
+
+    async def test_deleting_message_nulls_report_message_id(self):
+        client = TestClient(app)
+        sender = _register(client, "chat_cd_msg_sender")
+        reporter = _register(client, "chat_cd_msg_reporter")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                world = World(name="Msg Delete World", owner_id=sender)
+                session.add(world)
+                await session.flush()
+                msg = Message(sender_id=sender, world_id=world.id, body="to be removed")
+                session.add(msg)
+                await session.flush()
+                report = MessageReport(
+                    message_id=msg.id, reporter_id=reporter, reason="spam"
+                )
+                session.add(report)
+                await session.commit()
+                msg_id = msg.id
+                report_id = report.id
+
+            async with factory() as session:
+                await session.execute(delete(Message).where(Message.id == msg_id))
+                await session.commit()
+
+            async with factory() as session:
+                report = await session.get(MessageReport, report_id)
+                assert report is not None
+                assert report.message_id is None
+        finally:
+            await engine.dispose()