WIP checkpoint: Client-side player controller: movement + camera

2026-08-20 20:26:27 +00:00
268 changed files with 203 additions and 34385 deletions
@@ -1,39 +0,0 @@
 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
@@ -11,4 +11,3 @@ Thumbs.db
 # Godot UID files (regenerated from path)
 *.uid
 assets/build_info.json
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,115 +0,0 @@
 {
  "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"
    }
  }
 }
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,42 +0,0 @@
 [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
@@ -1,40 +0,0 @@
 {
  "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"
    }
  }
 }
@@ -1,17 +0,0 @@
 {
  "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}
      ]
    }
  ]
 }
@@ -1,8 +0,0 @@
 {
  "templates": {
    "small_crate": {
      "asset_id": "props/crate_small.glb",
      "display_name": "Small Crate"
    }
  }
 }
@@ -8,7 +8,7 @@ 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
+from app.models import user, session, world, asset  # noqa: F401
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
@@ -1,39 +0,0 @@
 """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")
@@ -1,120 +0,0 @@
 """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")
@@ -1,33 +0,0 @@
 """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")
@@ -1,118 +0,0 @@
 """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)
@@ -1,178 +0,0 @@
 """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)
@@ -1,80 +0,0 @@
 """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)
@@ -1,65 +0,0 @@
 """add profile tables (profiles, profile_favorites)
 Revision ID: 0010_add_profile_tables
 Revises: 0009_add_group_tables
 Create Date: 2026-09-15 00:00:00.000000
 app/models/profile.py. Models + migration + owner-only /api/profile/me
 endpoints only -- the public profile view endpoint (GET /api/profile/{user_id})
 belongs to a sibling task 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 = "0010_add_profile_tables"
 down_revision: Union[str, None] = "0009_add_group_tables"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    op.create_table(
        "profiles",
        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), primary_key=True),
        sa.Column(
            "avatar_asset_id",
            sa.Integer(),
            sa.ForeignKey("assets.id", ondelete="SET NULL"),
            nullable=True,
        ),
        sa.Column("bio", sa.Text(), nullable=True),
        sa.Column("privacy_json", postgresql.JSONB(), nullable=False, server_default="{}"),
        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_profiles_avatar_asset_id", "profiles", ["avatar_asset_id"])
    op.create_table(
        "profile_favorites",
        sa.Column(
            "user_id",
            sa.Integer(),
            sa.ForeignKey("users.id", ondelete="CASCADE"),
            primary_key=True,
        ),
        sa.Column(
            "world_id",
            sa.Integer(),
            sa.ForeignKey("worlds.id", ondelete="CASCADE"),
            primary_key=True,
        ),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
    )
    op.create_index("ix_profile_favorites_world_id", "profile_favorites", ["world_id"])
 def downgrade() -> None:
    op.drop_index("ix_profile_favorites_world_id", table_name="profile_favorites")
    op.drop_table("profile_favorites")
    op.drop_index("ix_profiles_avatar_asset_id", table_name="profiles")
    op.drop_table("profiles")
@@ -1,36 +0,0 @@
 """add last_read_at to conversation_participants (DM unread tracking)
 Revision ID: 0011_add_dm_last_read
 Revises: 0010_add_profile_tables
 Create Date: 2026-09-15 00:00:00.000000
 app/routers/chat_dm.py (DM send/list/conversations endpoints). Unread-count
 tracking is implemented as a last-read timestamp per participant: whenever a
 user fetches a conversation's message history, their
 ``conversation_participants`` row's ``last_read_at`` is bumped to "now", and
 the conversation-list endpoint counts messages with
 ``created_at > last_read_at`` (or all messages if never read) as unread for
 that participant. Nullable/no default so existing rows (none yet in
 practice, but consistent with "never read") read as "everything unread".
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 # revision identifiers, used by Alembic.
 revision: str = "0011_add_dm_last_read"
 down_revision: Union[str, None] = "0010_add_profile_tables"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    op.add_column(
        "conversation_participants",
        sa.Column("last_read_at", sa.DateTime(timezone=True), nullable=True),
    )
 def downgrade() -> None:
    op.drop_column("conversation_participants", "last_read_at")
@@ -1,90 +0,0 @@
 """add wallets and transactions ledger tables
 Revision ID: 0012_add_wallet_and_transactions
 Revises: 0011_add_dm_last_read
 Create Date: 2026-09-15 00:00:00.000000
 docs/planning/economy.md US-1 (task 8343bc0a730f).
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 # revision identifiers, used by Alembic.
 revision: str = "0012_add_wallet_and_transactions"
 down_revision: Union[str, None] = "0011_add_dm_last_read"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 TRANSACTION_TYPES = (
    "credit_purchase",
    "marketplace_purchase",
    "marketplace_sale",
    "escrow_release",
    "payout",
    "refund",
    "admin_adjustment",
 )
 def upgrade() -> None:
    # 1. Create transaction_type enum for Postgres
    bind = op.get_bind()
    if bind.dialect.name == "postgresql":
        tx_type_enum = postgresql.ENUM(*TRANSACTION_TYPES, name="transaction_type", create_type=False)
        tx_type_enum.create(bind, checkfirst=True)
        tx_type_col = postgresql.ENUM(*TRANSACTION_TYPES, name="transaction_type", create_type=False)
    else:
        tx_type_col = sa.Enum(*TRANSACTION_TYPES, name="transaction_type")
    # 2. Create wallets table
    op.create_table(
        "wallets",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("user_id", sa.Integer(), nullable=False),
        sa.Column("balance", sa.BigInteger(), server_default="0", nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.CheckConstraint("balance >= 0", name="check_wallet_balance_non_negative"),
        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
        sa.PrimaryKeyConstraint("id"),
        sa.UniqueConstraint("user_id", name="uq_wallets_user_id"),
    )
    op.create_index(op.f("ix_wallets_user_id"), "wallets", ["user_id"], unique=True)
    # 3. Create transactions table
    op.create_table(
        "transactions",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("wallet_id", sa.BigInteger(), nullable=False),
        sa.Column("type", tx_type_col, nullable=False),
        sa.Column("amount", sa.BigInteger(), nullable=False),
        sa.Column("balance_after", sa.BigInteger(), nullable=False),
        sa.Column("reference_type", sa.String(), nullable=True),
        sa.Column("reference_id", sa.String(), nullable=True),
        sa.Column("idempotency_key", sa.String(), nullable=True),
        sa.Column("metadata_json", postgresql.JSONB(astext_type=sa.Text()) if bind.dialect.name == "postgresql" else sa.JSON(), nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.ForeignKeyConstraint(["wallet_id"], ["wallets.id"], ondelete="CASCADE"),
        sa.PrimaryKeyConstraint("id"),
        sa.UniqueConstraint("idempotency_key", name="uq_transactions_idempotency_key"),
    )
    op.create_index(op.f("ix_transactions_wallet_id"), "transactions", ["wallet_id"], unique=False)
    op.create_index(op.f("ix_transactions_idempotency_key"), "transactions", ["idempotency_key"], unique=True)
    op.create_index(op.f("ix_transactions_created_at"), "transactions", ["created_at"], unique=False)
 def downgrade() -> None:
    op.drop_index(op.f("ix_transactions_created_at"), table_name="transactions")
    op.drop_index(op.f("ix_transactions_idempotency_key"), table_name="transactions")
    op.drop_index(op.f("ix_transactions_wallet_id"), table_name="transactions")
    op.drop_table("transactions")
    op.drop_index(op.f("ix_wallets_user_id"), table_name="wallets")
    op.drop_table("wallets")
    bind = op.get_bind()
    if bind.dialect.name == "postgresql":
        sa.Enum(*TRANSACTION_TYPES, name="transaction_type").drop(bind, checkfirst=True)
@@ -1,146 +0,0 @@
 """add marketplace tables: catalog_items, marketplace_listings, purchases, creator_balances
 Revision ID: 0013_add_marketplace_tables
 Revises: 0012_add_wallet_and_transactions
 Create Date: 2026-09-15 00:00:00.000000
 docs/planning/economy.md US-3, US-4 (task 166836d55365).
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 # revision identifiers, used by Alembic.
 revision: str = "0013_add_marketplace_tables"
 down_revision: Union[str, None] = "0012_add_wallet_and_transactions"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 ITEM_TYPES = ("asset", "avatar_item", "experience_pass")
 LISTING_STATUSES = ("active", "sold", "delisted", "removed_by_moderation")
 PURCHASE_STATUSES = ("pending_escrow", "completed", "refunded", "reversed")
 def upgrade() -> None:
    bind = op.get_bind()
    is_pg = bind.dialect.name == "postgresql"
    # Enums
    if is_pg:
        item_type_enum = postgresql.ENUM(*ITEM_TYPES, name="catalog_item_type", create_type=False)
        item_type_enum.create(bind, checkfirst=True)
        item_type_col = postgresql.ENUM(*ITEM_TYPES, name="catalog_item_type", create_type=False)
        listing_status_enum = postgresql.ENUM(*LISTING_STATUSES, name="marketplace_listing_status", create_type=False)
        listing_status_enum.create(bind, checkfirst=True)
        listing_status_col = postgresql.ENUM(*LISTING_STATUSES, name="marketplace_listing_status", create_type=False)
        purchase_status_enum = postgresql.ENUM(*PURCHASE_STATUSES, name="purchase_status", create_type=False)
        purchase_status_enum.create(bind, checkfirst=True)
        purchase_status_col = postgresql.ENUM(*PURCHASE_STATUSES, name="purchase_status", create_type=False)
    else:
        item_type_col = sa.Enum(*ITEM_TYPES, name="catalog_item_type")
        listing_status_col = sa.Enum(*LISTING_STATUSES, name="marketplace_listing_status")
        purchase_status_col = sa.Enum(*PURCHASE_STATUSES, name="purchase_status")
    # 1. catalog_items
    op.create_table(
        "catalog_items",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("owner_id", sa.Integer(), nullable=False),
        sa.Column("asset_id", sa.Integer(), nullable=True),
        sa.Column("item_type", item_type_col, nullable=False),
        sa.Column("name", sa.String(length=100), nullable=False),
        sa.Column("description", sa.String(length=2000), nullable=True),
        sa.Column("metadata_json", postgresql.JSONB(astext_type=sa.Text()) if is_pg else sa.JSON(), nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.ForeignKeyConstraint(["owner_id"], ["users.id"], ondelete="CASCADE"),
        sa.ForeignKeyConstraint(["asset_id"], ["assets.id"], ondelete="SET NULL"),
        sa.PrimaryKeyConstraint("id"),
    )
    op.create_index(op.f("ix_catalog_items_owner_id"), "catalog_items", ["owner_id"], unique=False)
    op.create_index(op.f("ix_catalog_items_asset_id"), "catalog_items", ["asset_id"], unique=False)
    # 2. marketplace_listings
    op.create_table(
        "marketplace_listings",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("catalog_item_id", sa.BigInteger(), nullable=False),
        sa.Column("seller_id", sa.Integer(), nullable=False),
        sa.Column("price", sa.BigInteger(), nullable=False),
        sa.Column("status", listing_status_col, server_default="active", nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.CheckConstraint("price > 0", name="check_listing_price_positive"),
        sa.ForeignKeyConstraint(["catalog_item_id"], ["catalog_items.id"], ondelete="CASCADE"),
        sa.ForeignKeyConstraint(["seller_id"], ["users.id"], ondelete="CASCADE"),
        sa.PrimaryKeyConstraint("id"),
    )
    op.create_index(op.f("ix_marketplace_listings_catalog_item_id"), "marketplace_listings", ["catalog_item_id"], unique=False)
    op.create_index(op.f("ix_marketplace_listings_seller_id"), "marketplace_listings", ["seller_id"], unique=False)
    # 3. purchases
    op.create_table(
        "purchases",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("listing_id", sa.BigInteger(), nullable=True),
        sa.Column("buyer_id", sa.Integer(), nullable=False),
        sa.Column("seller_id", sa.Integer(), nullable=False),
        sa.Column("price", sa.BigInteger(), nullable=False),
        sa.Column("platform_fee", sa.BigInteger(), nullable=False),
        sa.Column("seller_net", sa.BigInteger(), nullable=False),
        sa.Column("status", purchase_status_col, server_default="pending_escrow", nullable=False),
        sa.Column("escrow_hold_until", sa.DateTime(timezone=True), nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.ForeignKeyConstraint(["listing_id"], ["marketplace_listings.id"], ondelete="SET NULL"),
        sa.ForeignKeyConstraint(["buyer_id"], ["users.id"], ondelete="CASCADE"),
        sa.ForeignKeyConstraint(["seller_id"], ["users.id"], ondelete="CASCADE"),
        sa.PrimaryKeyConstraint("id"),
    )
    op.create_index(op.f("ix_purchases_listing_id"), "purchases", ["listing_id"], unique=False)
    op.create_index(op.f("ix_purchases_buyer_id"), "purchases", ["buyer_id"], unique=False)
    op.create_index(op.f("ix_purchases_seller_id"), "purchases", ["seller_id"], unique=False)
    # 4. creator_balances
    op.create_table(
        "creator_balances",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("user_id", sa.Integer(), nullable=False),
        sa.Column("available", sa.BigInteger(), server_default="0", nullable=False),
        sa.Column("pending", sa.BigInteger(), server_default="0", nullable=False),
        sa.Column("lifetime_earned", sa.BigInteger(), server_default="0", nullable=False),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.CheckConstraint("available >= 0", name="check_creator_available_non_negative"),
        sa.CheckConstraint("pending >= 0", name="check_creator_pending_non_negative"),
        sa.CheckConstraint("lifetime_earned >= 0", name="check_creator_lifetime_non_negative"),
        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
        sa.PrimaryKeyConstraint("id"),
        sa.UniqueConstraint("user_id", name="uq_creator_balances_user_id"),
    )
    op.create_index(op.f("ix_creator_balances_user_id"), "creator_balances", ["user_id"], unique=True)
 def downgrade() -> None:
    op.drop_index(op.f("ix_creator_balances_user_id"), table_name="creator_balances")
    op.drop_table("creator_balances")
    op.drop_index(op.f("ix_purchases_seller_id"), table_name="purchases")
    op.drop_index(op.f("ix_purchases_buyer_id"), table_name="purchases")
    op.drop_index(op.f("ix_purchases_listing_id"), table_name="purchases")
    op.drop_table("purchases")
    op.drop_index(op.f("ix_marketplace_listings_seller_id"), table_name="marketplace_listings")
    op.drop_index(op.f("ix_marketplace_listings_catalog_item_id"), table_name="marketplace_listings")
    op.drop_table("marketplace_listings")
    op.drop_index(op.f("ix_catalog_items_asset_id"), table_name="catalog_items")
    op.drop_index(op.f("ix_catalog_items_owner_id"), table_name="catalog_items")
    op.drop_table("catalog_items")
    bind = op.get_bind()
    if bind.dialect.name == "postgresql":
        sa.Enum(*PURCHASE_STATUSES, name="purchase_status").drop(bind, checkfirst=True)
        sa.Enum(*LISTING_STATUSES, name="marketplace_listing_status").drop(bind, checkfirst=True)
        sa.Enum(*ITEM_TYPES, name="catalog_item_type").drop(bind, checkfirst=True)
@@ -1,68 +0,0 @@
 """add payout_requests table and payout_status enum
 Revision ID: 0014_add_payout_requests
 Revises: 0013_add_marketplace_tables
 Create Date: 2026-09-15 00:00:00.000000
 docs/planning/economy.md US-5 (task f5b4684f2e65).
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 # revision identifiers, used by Alembic.
 revision: str = "0014_add_payout_requests"
 down_revision: Union[str, None] = "0013_add_marketplace_tables"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 PAYOUT_STATUSES = ("pending", "approved", "paid", "rejected")
 def upgrade() -> None:
    bind = op.get_bind()
    is_pg = bind.dialect.name == "postgresql"
    if is_pg:
        payout_status_enum = postgresql.ENUM(*PAYOUT_STATUSES, name="payout_status", create_type=False)
        payout_status_enum.create(bind, checkfirst=True)
        payout_status_col = postgresql.ENUM(*PAYOUT_STATUSES, name="payout_status", create_type=False)
    else:
        payout_status_col = sa.Enum(*PAYOUT_STATUSES, name="payout_status")
    op.create_table(
        "payout_requests",
        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
        sa.Column("creator_id", sa.Integer(), nullable=False),
        sa.Column("amount", sa.BigInteger(), nullable=False),
        sa.Column("status", payout_status_col, server_default="pending", nullable=False),
        sa.Column("external_ref", sa.String(length=255), nullable=True),
        sa.Column("provider_ref", sa.String(length=255), nullable=True),
        sa.Column("requested_by", sa.Integer(), nullable=False),
        sa.Column("reviewed_by", sa.Integer(), nullable=True),
        sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.ForeignKeyConstraint(["creator_id"], ["users.id"], ondelete="CASCADE"),
        sa.ForeignKeyConstraint(["requested_by"], ["users.id"], ondelete="CASCADE"),
        sa.ForeignKeyConstraint(["reviewed_by"], ["users.id"], ondelete="SET NULL"),
        sa.CheckConstraint("amount > 0", name="check_payout_amount_positive"),
        sa.PrimaryKeyConstraint("id"),
    )
    op.create_index("ix_payout_requests_creator_id", "payout_requests", ["creator_id"], unique=False)
    op.create_index("ix_payout_requests_requested_by", "payout_requests", ["requested_by"], unique=False)
    op.create_index("ix_payout_requests_reviewed_by", "payout_requests", ["reviewed_by"], unique=False)
 def downgrade() -> None:
    bind = op.get_bind()
    is_pg = bind.dialect.name == "postgresql"
    op.drop_index("ix_payout_requests_reviewed_by", table_name="payout_requests")
    op.drop_index("ix_payout_requests_requested_by", table_name="payout_requests")
    op.drop_index("ix_payout_requests_creator_id", table_name="payout_requests")
    op.drop_table("payout_requests")
    if is_pg:
        op.execute("DROP TYPE IF EXISTS payout_status")
@@ -1,62 +0,0 @@
 """add discovery metadata to worlds and create world_visits table
 Revision ID: 0015_add_discovery_metadata
 Revises: 0014_add_payout_requests
 Create Date: 2026-09-15 00:00:00.000000
 docs/planning/discovery.md (task b377353b8167).
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 # revision identifiers, used by Alembic.
 revision: str = "0015_add_discovery_metadata"
 down_revision: Union[str, None] = "0014_add_payout_requests"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    # 1. Add discovery metadata columns to worlds table
    op.add_column("worlds", sa.Column("category", sa.String(length=100), nullable=True))
    op.add_column("worlds", sa.Column("tags", postgresql.ARRAY(sa.String()), server_default="{}", nullable=True))
    op.add_column("worlds", sa.Column("play_count", sa.Integer(), server_default="0", nullable=False))
    op.add_column("worlds", sa.Column("last_played_at", sa.DateTime(timezone=True), nullable=True))
    op.create_index("ix_worlds_category", "worlds", ["category"], unique=False)
    op.create_index("ix_worlds_tags", "worlds", ["tags"], unique=False, postgresql_using="gin")
    # 2. Create world_visits table
    op.create_table(
        "world_visits",
        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
        sa.Column("world_id", sa.Integer(), nullable=False),
        sa.Column("user_id", sa.Integer(), nullable=True),
        sa.Column("anonymous_token", sa.String(length=255), nullable=True),
        sa.Column("visited_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
        sa.ForeignKeyConstraint(["world_id"], ["worlds.id"], ondelete="CASCADE"),
        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="SET NULL"),
        sa.PrimaryKeyConstraint("id"),
    )
    op.create_index("ix_world_visits_world_id", "world_visits", ["world_id"], unique=False)
    op.create_index("ix_world_visits_user_id", "world_visits", ["user_id"], unique=False)
    op.create_index("ix_world_visits_visited_at", "world_visits", ["visited_at"], unique=False)
    op.create_index("ix_world_visits_world_visited_at", "world_visits", ["world_id", "visited_at"], unique=False)
 def downgrade() -> None:
    op.drop_index("ix_world_visits_world_visited_at", table_name="world_visits")
    op.drop_index("ix_world_visits_visited_at", table_name="world_visits")
    op.drop_index("ix_world_visits_user_id", table_name="world_visits")
    op.drop_index("ix_world_visits_world_id", table_name="world_visits")
    op.drop_table("world_visits")
    op.drop_index("ix_worlds_tags", table_name="worlds", postgresql_using="gin")
    op.drop_index("ix_worlds_category", table_name="worlds")
    op.drop_column("worlds", "last_played_at")
    op.drop_column("worlds", "play_count")
    op.drop_column("worlds", "tags")
    op.drop_column("worlds", "category")
@@ -75,52 +75,11 @@ class Settings(BaseSettings):
    # 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",
@@ -53,33 +53,3 @@ async def get_current_user(
 CurrentUser = Annotated[User, Depends(get_current_user)]
 oauth2_scheme_optional = OAuth2PasswordBearer(tokenUrl="/api/auth/login", auto_error=False)
 async def get_optional_user(
    token: Annotated[str | None, Depends(oauth2_scheme_optional)],
    db: Annotated[AsyncSession, Depends(get_db)],
 ) -> User | None:
    """Resolve the JWT bearer token to a User if present and valid, otherwise None."""
    if not token:
        return None
    try:
        payload = jwt.decode(
            token, settings.public_pem, algorithms=[settings.ALGORITHM]
        )
        user_id: str | None = payload.get("sub")
        if user_id is None:
            return None
        user_id_int = int(user_id)
    except (JWTError, ValueError, TypeError):
        return None
    result = await db.execute(select(User).where(User.id == user_id_int))
    user = result.scalar_one_or_none()
    if user is None or not user.is_active:
        return None
    return user
 OptionalUser = Annotated[User | None, Depends(get_optional_user)]
@@ -1 +0,0 @@
 """WebSocket real-time gateway package."""
@@ -1,538 +0,0 @@
 """Real-time WebSocket gateway.
 Multiplexes presence, DM, and world-chat delivery over a single WebSocket
 endpoint (docs/planning/social.md US-2, US-4).
 Key features:
 - Authentication via JWT token (query param or initial auth frame).
 - Scoped subscriptions to DM conversations and world channels.
 - Server-derived presence heartbeat (Redis TTL refreshed periodically).
 - Broadcast presence changes (online/offline) to mutual friends.
 - Fan-out via Redis pub/sub.
 - Thread-safe & event-loop-safe dispatch for multi-instance and test environments.
 - Graceful reconnect without duplicate delivery or orphaned state.
 """
 from __future__ import annotations
 import asyncio
 from contextlib import asynccontextmanager
 from datetime import datetime, timezone
 import json
 import logging
 from typing import Any
 from fastapi import APIRouter, WebSocket, WebSocketDisconnect, status
 from jose import JWTError, jwt
 from sqlalchemy import or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 import redis.asyncio as aioredis
 from app.config import settings
 from app.database import async_session_factory, get_db
 from app.models.chat import ConversationParticipant
 from app.models.social import Friendship, FriendshipStatus
 from app.models.user import User
 from app.models.world import World, WorldVisibility
 from app.services.presence import presence_store
 logger = logging.getLogger(__name__)
 router = APIRouter()
@asynccontextmanager
 async def get_db_session():
    """Helper to acquire an async DB session respecting test overrides if present."""
    from app.main import app
    override = app.dependency_overrides.get(get_db)
    if override:
        res = override()
        if hasattr(res, "__anext__"):
            session = await res.__anext__()
            try:
                yield session
            finally:
                try:
                    await res.__anext__()
                except (StopAsyncIteration, Exception):
                    pass
            return
        elif hasattr(res, "__next__"):
            session = next(res)
            try:
                yield session
            finally:
                try:
                    next(res)
                except (StopIteration, Exception):
                    pass
            return
    async with async_session_factory() as session:
        yield session
 async def authenticate_token(token: str) -> User | None:
    """Validate JWT token and return authenticated User, or None."""
    try:
        payload = jwt.decode(token, settings.public_pem, algorithms=[settings.ALGORITHM])
        user_id_raw = payload.get("sub")
        if user_id_raw is None:
            return None
        user_id = int(user_id_raw)
    except (JWTError, ValueError, TypeError):
        return None
    async with get_db_session() as db:
        res = await db.execute(select(User).where(User.id == user_id))
        user = res.scalar_one_or_none()
        if user and user.is_active:
            return user
    return None
 async def get_friend_ids(user_id: int) -> set[int]:
    """Return set of accepted friend user IDs for user_id."""
    try:
        async with get_db_session() as db:
            res = await db.execute(
                select(Friendship).where(
                    or_(Friendship.requester_id == user_id, Friendship.addressee_id == user_id),
                    Friendship.status == FriendshipStatus.ACCEPTED,
                )
            )
            friendships = res.scalars().all()
            return {
                f.addressee_id if f.requester_id == user_id else f.requester_id
                for f in friendships
            }
    except Exception as exc:
        logger.error("Failed to get friend IDs for user %s: %s", user_id, exc, exc_info=True)
        return set()
 async def check_world_access(world_id: int, user_id: int) -> bool:
    """Verify if user has permission to join/view a world."""
    async with get_db_session() as db:
        res = await db.execute(select(World).where(World.id == world_id))
        world = res.scalar_one_or_none()
        if not world:
            return False
        if world.visibility == WorldVisibility.PUBLIC:
            return True
        if world.owner_id == user_id:
            return True
        if world.visibility == WorldVisibility.FRIENDS_ONLY:
            res_fr = await db.execute(
                select(Friendship.id).where(
                    or_(
                        and_(Friendship.requester_id == world.owner_id, Friendship.addressee_id == user_id),
                        and_(Friendship.requester_id == user_id, Friendship.addressee_id == world.owner_id),
                    ),
                    Friendship.status == FriendshipStatus.ACCEPTED,
                ).limit(1)
            )
            return res_fr.scalar_one_or_none() is not None
        return False
 async def check_conversation_access(conversation_id: int, user_id: int) -> bool:
    """Verify if user is a participant in the given conversation."""
    async with get_db_session() as db:
        res = await db.execute(
            select(ConversationParticipant.id).where(
                ConversationParticipant.conversation_id == conversation_id,
                ConversationParticipant.user_id == user_id,
            ).limit(1)
        )
        return res.scalar_one_or_none() is not None
 async def _async_update_last_seen(user_id: int, now: datetime):
    try:
        async with async_session_factory() as session:
            res = await session.execute(select(User).where(User.id == user_id))
            db_user = res.scalar_one_or_none()
            if db_user:
                db_user.last_seen_at = now
                await session.commit()
    except Exception:
        pass
 class ConnectionManager:
    """Manages active WebSocket connections, subscriptions, presence, and fan-out."""
    def __init__(self):
        # ws -> User
        self._connections: dict[WebSocket, User] = {}
        # ws -> event loop id
        self._ws_loops: dict[WebSocket, int] = {}
        # user_id -> set of active WebSockets
        self._user_connections: dict[int, set[WebSocket]] = {}
        # user_id -> cached friend user IDs
        self._user_friend_ids: dict[int, set[int]] = {}
        # world_id -> set of WebSockets
        self._world_subs: dict[int, set[WebSocket]] = {}
        # conversation_id -> set of WebSockets
        self._dm_subs: dict[int, set[WebSocket]] = {}
        # ws -> asyncio heartbeat task
        self._heartbeat_tasks: dict[WebSocket, asyncio.Task] = {}
        # Per-event-loop Redis pub/sub listener tasks and events
        self._redis_tasks: dict[int, asyncio.Task] = {}
        self._subscribed_events: dict[int, asyncio.Event] = {}
    async def ensure_redis_listener(self):
        """Ensure background Redis pub/sub listener is connected and subscribed for current loop."""
        loop = asyncio.get_running_loop()
        loop_key = id(loop)
        task = self._redis_tasks.get(loop_key)
        if task is None or task.done():
            event = asyncio.Event()
            self._subscribed_events[loop_key] = event
            task = asyncio.create_task(self._redis_listener(loop_key, event))
            self._redis_tasks[loop_key] = task
        else:
            event = self._subscribed_events.get(loop_key)
        if event:
            try:
                await asyncio.wait_for(event.wait(), timeout=2.0)
            except asyncio.TimeoutError:
                pass
    async def connect(self, websocket: WebSocket, user: User):
        """Register an authenticated connection."""
        await self.ensure_redis_listener()
        loop_key = id(asyncio.get_running_loop())
        self._connections[websocket] = user
        self._ws_loops[websocket] = loop_key
        self._user_connections.setdefault(user.id, set()).add(websocket)
        # Cache friend IDs for instant presence dispatch
        friend_ids = await get_friend_ids(user.id)
        self._user_friend_ids[user.id] = friend_ids
        # Mark user online in Redis and DB
        await presence_store.heartbeat(user.id)
        now = datetime.now(timezone.utc)
        asyncio.create_task(_async_update_last_seen(user.id, now))
        # Start periodic heartbeat task (every 20 seconds)
        self._heartbeat_tasks[websocket] = asyncio.create_task(
            self._run_periodic_heartbeat(user.id)
        )
        # Broadcast online presence to friends via Redis
        await self.broadcast_presence(user.id, user.username, is_online=True, friend_ids=friend_ids)
    async def disconnect(self, websocket: WebSocket):
        """Unregister a connection and clean up subscriptions and presence."""
        user = self._connections.pop(websocket, None)
        self._ws_loops.pop(websocket, None)
        task = self._heartbeat_tasks.pop(websocket, None)
        if task:
            task.cancel()
        # Clean subscriptions
        for world_id in list(self._world_subs.keys()):
            self._world_subs[world_id].discard(websocket)
            if not self._world_subs[world_id]:
                self._world_subs.pop(world_id, None)
        for conv_id in list(self._dm_subs.keys()):
            self._dm_subs[conv_id].discard(websocket)
            if not self._dm_subs[conv_id]:
                self._dm_subs.pop(conv_id, None)
        if user is None:
            return
        user_id = user.id
        username = user.username
        user_set = self._user_connections.get(user_id)
        if user_set:
            user_set.discard(websocket)
            if not user_set:
                self._user_connections.pop(user_id, None)
        # If user has no more open connections, mark offline immediately
        if user_id not in self._user_connections:
            await presence_store.clear_heartbeat(user_id)
            now = datetime.now(timezone.utc)
            asyncio.create_task(_async_update_last_seen(user_id, now))
            friend_ids = self._user_friend_ids.pop(user_id, set())
            await self.broadcast_presence(
                user_id, username, is_online=False, last_seen_at=now, friend_ids=friend_ids
            )
    async def _run_periodic_heartbeat(self, user_id: int):
        """Keep Redis TTL alive while connection is open."""
        try:
            while True:
                await asyncio.sleep(20)
                await presence_store.heartbeat(user_id)
        except asyncio.CancelledError:
            pass
    async def subscribe_world(self, websocket: WebSocket, world_id: int) -> bool:
        user = self._connections.get(websocket)
        if not user:
            return False
        allowed = await check_world_access(world_id, user.id)
        if not allowed:
            return False
        self._world_subs.setdefault(world_id, set()).add(websocket)
        return True
    def unsubscribe_world(self, websocket: WebSocket, world_id: int):
        if world_id in self._world_subs:
            self._world_subs[world_id].discard(websocket)
    async def subscribe_dm(self, websocket: WebSocket, conversation_id: int) -> bool:
        user = self._connections.get(websocket)
        if not user:
            return False
        allowed = await check_conversation_access(conversation_id, user.id)
        if not allowed:
            return False
        self._dm_subs.setdefault(conversation_id, set()).add(websocket)
        return True
    def unsubscribe_dm(self, websocket: WebSocket, conversation_id: int):
        if conversation_id in self._dm_subs:
            self._dm_subs[conversation_id].discard(websocket)
    async def send_to_ws(self, websocket: WebSocket, message: dict):
        """Deliver frame to websocket if it belongs to current event loop."""
        cur_loop = id(asyncio.get_running_loop())
        if self._ws_loops.get(websocket) != cur_loop:
            return
        try:
            await websocket.send_text(json.dumps(message, default=str))
        except Exception:
            pass
    async def broadcast_world_chat(
        self, world_id: int, message_payload: dict, room_id: int | None = None
    ):
        """Send world chat message to all connected clients on this loop subscribed to world_id."""
        targets = list(self._world_subs.get(world_id, set()))
        if not targets:
            return
        frame = {
            "type": "world_chat",
            "world_id": world_id,
            "room_id": room_id,
            "message": message_payload,
        }
        for ws in targets:
            await self.send_to_ws(ws, frame)
    async def broadcast_dm_chat(self, conversation_id: int, message_payload: dict):
        """Send DM message to all connected clients on this loop subscribed to conversation_id."""
        targets = list(self._dm_subs.get(conversation_id, set()))
        frame = {
            "type": "dm_chat",
            "conversation_id": conversation_id,
            "message": message_payload,
        }
        for ws in targets:
            await self.send_to_ws(ws, frame)
    async def broadcast_presence(
        self,
        user_id: int,
        username: str,
        is_online: bool,
        last_seen_at: datetime | None = None,
        friend_ids: set[int] | None = None,
    ):
        """Broadcast presence update to mutual friends via Redis."""
        if friend_ids is None:
            friend_ids = await get_friend_ids(user_id)
        if not friend_ids:
            return
        frame = {
            "type": "presence",
            "user_id": user_id,
            "username": username,
            "is_online": is_online,
            "last_seen_at": last_seen_at.isoformat() if last_seen_at else None,
            "friend_ids": list(friend_ids),
        }
        # Redis broadcast for all loops/instances
        try:
            client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
            async with client:
                await client.publish("presence:events", json.dumps(frame, default=str))
        except Exception as exc:
            logger.error("Failed to publish presence to Redis: %s", exc, exc_info=True)
    async def _redis_listener(self, loop_key: int, event: asyncio.Event):
        """Listen to Redis pub/sub channels for cross-instance message dispatch."""
        while True:
            try:
                client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
                pubsub = client.pubsub()
                await pubsub.psubscribe("world:*:chat", "dm:*:chat", "presence:events")
                event.set()
                logger.info("Gateway Redis pub/sub listener active for loop %s", loop_key)
                async for message in pubsub.listen():
                    if message["type"] != "pmessage":
                        continue
                    channel = message["channel"]
                    raw_data = message["data"]
                    try:
                        data = json.loads(raw_data)
                    except Exception:
                        continue
                    if channel.startswith("world:") and channel.endswith(":chat"):
                        parts = channel.split(":")
                        world_id = int(parts[1])
                        await self.broadcast_world_chat(world_id, data, room_id=data.get("room_id"))
                    elif channel.startswith("dm:") and channel.endswith(":chat"):
                        parts = channel.split(":")
                        conv_id = int(parts[1])
                        await self.broadcast_dm_chat(conv_id, data)
                    elif channel == "presence:events":
                        logger.info("Redis presence event received: %s. Active users: %s", data, list(self._user_connections.keys()))
                        for friend_id in data.get("friend_ids", []):
                            targets = list(self._user_connections.get(friend_id, set()))
                            logger.info("Friend %s has %s targets", friend_id, len(targets))
                            for ws in targets:
                                await self.send_to_ws(ws, data)
            except asyncio.CancelledError:
                break
            except Exception as exc:
                logger.debug("Redis listener encountered error, retrying in 2s: %s", exc)
                event.clear()
                await asyncio.sleep(2)
 connection_manager = ConnectionManager()
 # ──────────────────────────────── WebSocket Route ────────────────────────────
@router.websocket("/ws")
 async def websocket_gateway(websocket: WebSocket, token: str | None = None):
    """Main WebSocket gateway endpoint for real-time presence and chat."""
    user: User | None = None
    # 1. Check query parameter token
    if token:
        user = await authenticate_token(token)
        if user is None:
            await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
            return
    await websocket.accept()
    # 2. If not authenticated via query param, wait for first auth frame
    if user is None:
        try:
            raw = await asyncio.wait_for(websocket.receive_text(), timeout=3.0)
            data = json.loads(raw)
            if data.get("type") == "auth" and data.get("token"):
                user = await authenticate_token(data["token"])
        except (asyncio.TimeoutError, json.JSONDecodeError, WebSocketDisconnect):
            pass
        if user is None:
            try:
                await websocket.send_text(json.dumps({"type": "error", "message": "Authentication failed"}))
                await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
            except Exception:
                pass
            return
    # Mark user online in Redis immediately upon successful auth
    await presence_store.heartbeat(user.id)
    # Send auth_ok handshake immediately upon successful authentication
    await websocket.send_text(
        json.dumps({
            "type": "auth_ok",
            "user_id": user.id,
            "username": user.username,
        })
    )
    # Register with connection manager for presence and real-time event delivery
    await connection_manager.connect(websocket, user)
    try:
        while True:
            text = await websocket.receive_text()
            try:
                msg = json.loads(text)
            except json.JSONDecodeError:
                await websocket.send_text(json.dumps({"type": "error", "message": "Invalid JSON"}))
                continue
            msg_type = msg.get("type")
            if msg_type == "ping":
                await websocket.send_text(json.dumps({"type": "pong"}))
            elif msg_type == "heartbeat":
                await presence_store.heartbeat(user.id)
                await websocket.send_text(json.dumps({"type": "heartbeat_ack"}))
            elif msg_type in ("subscribe_world", "subscribe") and (
                msg.get("world_id") or msg.get("channel") == "world"
            ):
                world_id = msg.get("world_id") or msg.get("id")
                if isinstance(world_id, int):
                    ok = await connection_manager.subscribe_world(websocket, world_id)
                    if ok:
                        await websocket.send_text(
                            json.dumps({"type": "subscribed", "channel": "world", "id": world_id})
                        )
                    else:
                        await websocket.send_text(
                            json.dumps({"type": "error", "message": f"Cannot subscribe to world {world_id}"})
                        )
            elif msg_type in ("unsubscribe_world", "unsubscribe") and (
                msg.get("world_id") or msg.get("channel") == "world"
            ):
                world_id = msg.get("world_id") or msg.get("id")
                if isinstance(world_id, int):
                    connection_manager.unsubscribe_world(websocket, world_id)
                    await websocket.send_text(
                        json.dumps({"type": "unsubscribed", "channel": "world", "id": world_id})
                    )
            elif msg_type in ("subscribe_dm", "subscribe") and (
                msg.get("conversation_id") or msg.get("channel") == "dm"
            ):
                conv_id = msg.get("conversation_id") or msg.get("id")
                if isinstance(conv_id, int):
                    ok = await connection_manager.subscribe_dm(websocket, conv_id)
                    if ok:
                        await websocket.send_text(
                            json.dumps({"type": "subscribed", "channel": "dm", "id": conv_id})
                        )
                    else:
                        await websocket.send_text(
                            json.dumps({"type": "error", "message": f"Cannot subscribe to conversation {conv_id}"})
                        )
            elif msg_type in ("unsubscribe_dm", "unsubscribe") and (
                msg.get("conversation_id") or msg.get("channel") == "dm"
            ):
                conv_id = msg.get("conversation_id") or msg.get("id")
                if isinstance(conv_id, int):
                    connection_manager.unsubscribe_dm(websocket, conv_id)
                    await websocket.send_text(
                        json.dumps({"type": "unsubscribed", "channel": "dm", "id": conv_id})
                    )
            else:
                await websocket.send_text(json.dumps({"type": "error", "message": f"Unknown action: {msg_type}"}))
    except WebSocketDisconnect:
        pass
    finally:
        await connection_manager.disconnect(websocket)
@@ -6,23 +6,15 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from app.config import settings
-from app.routers import (
+from app.routers import auth, users, worlds, assets
    auth, users, worlds, assets, avatar, world_content, internal,
    presence, groups, social_friends, profiles, chat_dm, chat_reports,
    chat_world, wallet, payments, marketplace, payouts, discovery,
 )
 from app.gateway import ws
 from app.services.game_servers import supervisor
@asynccontextmanager
 async def lifespan(app: FastAPI):
    """Application lifespan: startup and shutdown events."""
-    supervisor.start()
+    # Startup: initialize database, connect to Redis, etc.
    yield
-    await supervisor.shutdown()
+    # Shutdown: close connections, cleanup
 app = FastAPI(
@@ -45,27 +37,7 @@ app.add_middleware(
 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.include_router(profiles.router, prefix="/api/profile", tags=["profile"])
 app.include_router(chat_dm.router, prefix="/api/chat/dm", tags=["chat-dm"])
 app.include_router(chat_reports.chat_router, prefix="/api/chat", tags=["chat-reports"])
 app.include_router(chat_reports.moderation_router, prefix="/api/moderation", tags=["moderation"])
 app.include_router(chat_world.router, prefix="/api/chat", tags=["chat-world"])
 app.include_router(chat_world.router, prefix="/v1/chat", tags=["chat-world"])
 app.include_router(wallet.router, prefix="/api/wallet", tags=["wallet"])
 app.include_router(payments.router, prefix="/api/payments", tags=["payments"])
 app.include_router(marketplace.router, prefix="/api/marketplace", tags=["marketplace"])
 app.include_router(payouts.router, prefix="/api/payouts", tags=["payouts"])
 app.include_router(discovery.router, prefix="/api/discovery", tags=["discovery"])
 app.include_router(ws.router, prefix="/api", tags=["websocket"])
 app.include_router(ws.router, prefix="/v1", tags=["websocket"])
@app.get("/api/health")
@@ -2,30 +2,5 @@ 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
 from app.models.profile import Profile, ProfileFavorite, ProfileVisibility
 from app.models.wallet import Wallet, Transaction, TransactionType
 from app.models.marketplace import (
    CatalogItem, MarketplaceListing, Purchase, CreatorBalance,
    ItemType, ListingStatus, PurchaseStatus,
 )
 from app.models.world_visit import WorldVisit
-__all__ = [
+__all__ = ["User", "Session", "World", "Asset"]
    "User", "Session", "World", "Asset", "AvatarLoadout",
    "WorldRoom", "WorldChunk", "WorldChunkRevision",
    "Friendship", "Follow", "Block", "FriendshipStatus",
    "Conversation", "ConversationParticipant", "Message", "MessageReport", "ReportStatus",
    "Group", "GroupMember", "GroupRole",
    "Profile", "ProfileFavorite", "ProfileVisibility",
    "Wallet", "Transaction", "TransactionType",
    "CatalogItem", "MarketplaceListing", "Purchase", "CreatorBalance",
    "ItemType", "ListingStatus", "PurchaseStatus",
    "WorldVisit",
 ]
@@ -23,12 +23,7 @@ class Asset(Base):
    name = Column(String(255), nullable=False)
    description = Column(Text, nullable=True)
    asset_type = Column(
-        ENUM(
+        ENUM(AssetType, name="asset_type", create_type=False),
            AssetType,
            name="asset_type",
            create_type=False,
            values_callable=lambda enum_cls: [e.value for e in enum_cls],
        ),
        nullable=False,
    )
    file_path = Column(String(512), nullable=False)
@@ -1,41 +0,0 @@
 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")
@@ -1,221 +0,0 @@
 """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)
    # DM unread tracking (app/routers/chat_dm.py, migration 0010): bumped to
    # "now" whenever this participant fetches the conversation's history.
    # Null means "never read" -- everything in the conversation is unread.
    last_read_at = Column(DateTime(timezone=True), nullable=True)
    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])
@@ -1,97 +0,0 @@
 """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"),
    )
@@ -1,195 +0,0 @@
 """Marketplace models: catalog items, listings, purchases, and creator balances.
 docs/planning/economy.md US-3, US-4 (task 166836d55365).
 """
 from datetime import datetime, timezone
 import enum
 from sqlalchemy import (
    BigInteger,
    CheckConstraint,
    Column,
    DateTime,
    Enum,
    ForeignKey,
    Integer,
    String,
    func,
 )
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.types import JSON
 from sqlalchemy.orm import relationship
 from app.database import Base
 class ItemType(str, enum.Enum):
    asset = "asset"
    avatar_item = "avatar_item"
    experience_pass = "experience_pass"
 class ListingStatus(str, enum.Enum):
    active = "active"
    sold = "sold"
    delisted = "delisted"
    removed_by_moderation = "removed_by_moderation"
 class PurchaseStatus(str, enum.Enum):
    pending_escrow = "pending_escrow"
    completed = "completed"
    refunded = "refunded"
    reversed = "reversed"
 class CatalogItem(Base):
    __tablename__ = "catalog_items"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    owner_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
    asset_id = Column(Integer, ForeignKey("assets.id", ondelete="SET NULL"), nullable=True, index=True)
    item_type = Column(Enum(ItemType, name="catalog_item_type"), nullable=False)
    name = Column(String(100), nullable=False)
    description = Column(String(2000), nullable=True)
    metadata_json = Column(JSONB().with_variant(JSON, "sqlite"), nullable=True)
    created_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    owner = relationship("User", foreign_keys=[owner_id])
    asset = relationship("Asset", foreign_keys=[asset_id])
    listings = relationship("MarketplaceListing", back_populates="catalog_item", cascade="all, delete-orphan")
 class MarketplaceListing(Base):
    __tablename__ = "marketplace_listings"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    catalog_item_id = Column(BigInteger, ForeignKey("catalog_items.id", ondelete="CASCADE"), nullable=False, index=True)
    seller_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
    price = Column(BigInteger, nullable=False)
    status = Column(
        Enum(ListingStatus, name="marketplace_listing_status"),
        nullable=False,
        default=ListingStatus.active,
        server_default=ListingStatus.active.value,
    )
    created_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    updated_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        onupdate=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    __table_args__ = (
        CheckConstraint("price > 0", name="check_listing_price_positive"),
    )
    catalog_item = relationship("CatalogItem", back_populates="listings")
    seller = relationship("User", foreign_keys=[seller_id])
 class Purchase(Base):
    __tablename__ = "purchases"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    listing_id = Column(BigInteger, ForeignKey("marketplace_listings.id", ondelete="SET NULL"), nullable=True, index=True)
    buyer_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
    seller_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
    price = Column(BigInteger, nullable=False)
    platform_fee = Column(BigInteger, nullable=False)
    seller_net = Column(BigInteger, nullable=False)
    status = Column(
        Enum(PurchaseStatus, name="purchase_status"),
        nullable=False,
        default=PurchaseStatus.pending_escrow,
        server_default=PurchaseStatus.pending_escrow.value,
    )
    escrow_hold_until = Column(DateTime(timezone=True), nullable=True)
    created_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    listing = relationship("MarketplaceListing", foreign_keys=[listing_id])
    buyer = relationship("User", foreign_keys=[buyer_id])
    seller = relationship("User", foreign_keys=[seller_id])
 class CreatorBalance(Base):
    __tablename__ = "creator_balances"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), unique=True, nullable=False, index=True)
    available = Column(BigInteger, nullable=False, default=0, server_default="0")
    pending = Column(BigInteger, nullable=False, default=0, server_default="0")
    lifetime_earned = Column(BigInteger, nullable=False, default=0, server_default="0")
    updated_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        onupdate=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    __table_args__ = (
        CheckConstraint("available >= 0", name="check_creator_available_non_negative"),
        CheckConstraint("pending >= 0", name="check_creator_pending_non_negative"),
        CheckConstraint("lifetime_earned >= 0", name="check_creator_lifetime_non_negative"),
    )
    user = relationship("User", foreign_keys=[user_id])
 class PayoutStatus(str, enum.Enum):
    pending = "pending"
    approved = "approved"
    paid = "paid"
    rejected = "rejected"
 class PayoutRequest(Base):
    __tablename__ = "payout_requests"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    creator_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
    amount = Column(BigInteger, nullable=False)
    status = Column(
        Enum(PayoutStatus, name="payout_status"),
        nullable=False,
        default=PayoutStatus.pending,
        server_default=PayoutStatus.pending.value,
    )
    external_ref = Column(String(255), nullable=True)
    provider_ref = Column(String(255), nullable=True)
    requested_by = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
    reviewed_by = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True)
    reviewed_at = Column(DateTime(timezone=True), nullable=True)
    created_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    __table_args__ = (
        CheckConstraint("amount > 0", name="check_payout_amount_positive"),
    )
    creator = relationship("User", foreign_keys=[creator_id])
    requester = relationship("User", foreign_keys=[requested_by])
    reviewer = relationship("User", foreign_keys=[reviewed_by])
@@ -1,129 +0,0 @@
 """User profile: bio, avatar reference, privacy settings, favorite worlds.
 This module is models + migration only -- the public profile view endpoint
 (``GET /api/profile/{user_id}``, which will need to interpret ``privacy_json``
 against the viewer's relationship to the owner) belongs to a sibling task
 that depends on this one. This task only owns the authenticated-owner
 read/write endpoints (``/api/profile/me`` and its ``favorites`` sub-resource).
 Design choices:
 - ``profiles.user_id`` is both the primary key and the FK to ``users.id``
  (``ondelete="CASCADE"``) -- exactly one profile row per user, following the
  same one-row-per-user shape as ``AvatarLoadout`` (app/models/avatar_loadout.py).
  The row is created lazily (upserted) on first ``PUT /api/profile/me``
  rather than at registration time, again mirroring ``AvatarLoadout``.
 - ``avatar_asset_id`` -> ``assets.id`` with ``ondelete="SET NULL"``. A
  profile's chosen "avatar picture" asset is a soft reference: if the
  underlying asset is later deleted the profile shouldn't be destroyed or
  left pointing at a dangling id, it should just fall back to "no avatar
  picture set" (nullable). The API layer additionally validates on write
  that the referenced asset actually exists (existence is not enforced by
  the FK alone at the API layer, since the FK only stops inserts of a
  nonexistent id -- it doesn't tell the caller *why* their PUT failed).
 - ``bio`` is ``Text`` with the 500-char cap enforced at the API/schema layer
  (Pydantic ``max_length``), matching how ``StatusUpdate.status_message`` in
  presence.py enforces its length cap in the router rather than the schema.
 - ``privacy_json`` is JSONB (project convention for document-shaped fields --
  see avatar_loadout.py, world_content.py) holding exactly three keys, each a
  ``ProfileVisibility`` enum value (stored as its string value in JSON, not a
  Postgres ENUM type -- there's no need for a DB-level enum since this is a
  small, entirely API-validated document, and a plain JSONB column is easier
  to extend with more privacy keys later without a migration):
    - ``profile_visibility``: who can view the profile at all.
    - ``friends_list_visibility``: who can see the user's friends list.
    - ``favorites_visibility``: who can see the user's favorited worlds.
  Each value is one of "public", "friends", "private". Defaults (applied when
  a profile is first created) are all "public" -- the least surprising
  default for a new social feature, matching the "everything visible unless
  you lock it down" posture other social features here take by default
  (e.g. presence/status has no privacy gate at all yet).
 - Favorites use a join table (``profile_favorites``: ``user_id`` + ``world_id``,
  composite PK) rather than a JSON array column. A plain FK join table gets
  referential integrity for free (a favorited world that's later deleted
  disappears from favorites automatically via ON DELETE CASCADE, matching
  how ``World.assets``/``World.rooms`` cascade), lets Postgres enforce
  "no duplicate favorite" via the composite PK instead of API-layer
  deduplication, and keeps "does this world still exist" as a DB invariant
  rather than something every reader has to re-check against a JSON blob.
  The tradeoff (an extra table/join vs. a single JSON column) is worth it
  here because favorites are a list of foreign-key references, not a
  free-form document -- the exact case join tables suit better than JSONB.
 """
 import enum
 from sqlalchemy import Column, Integer, ForeignKey, Text, DateTime
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class ProfileVisibility(str, enum.Enum):
    PUBLIC = "public"
    FRIENDS = "friends"
    PRIVATE = "private"
 # Applied when a profile is created for the first time (lazy upsert on the
 # first PUT /api/profile/me). Keys match the three privacy_json fields
 # documented above.
 DEFAULT_PRIVACY: dict = {
    "profile_visibility": ProfileVisibility.PUBLIC.value,
    "friends_list_visibility": ProfileVisibility.PUBLIC.value,
    "favorites_visibility": ProfileVisibility.PUBLIC.value,
 }
 BIO_MAX_LEN = 500
 class Profile(Base):
    """One row per user: bio, avatar picture reference, privacy settings."""
    __tablename__ = "profiles"
    user_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        primary_key=True,
    )
    avatar_asset_id = Column(
        Integer,
        ForeignKey("assets.id", ondelete="SET NULL"),
        nullable=True,
    )
    bio = Column(Text, nullable=True)
    privacy_json = Column(JSONB, nullable=False, server_default="{}")
    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="profile")
    avatar_asset = relationship("Asset")
    # Deliberately no ORM relationship to ProfileFavorite here: profiles and
    # profile_favorites both independently FK users.id (no direct FK between
    # the two tables), and the router only ever needs to query/replace a
    # user's favorites by user_id directly -- not traverse it off a loaded
    # Profile object. Keeping it a plain queryable table avoids a
    # hand-spelled, easy-to-get-wrong primaryjoin for no real benefit.
 class ProfileFavorite(Base):
    """A user's favorited world. Composite PK -- see module docstring for why
    this is a join table rather than a JSON array column."""
    __tablename__ = "profile_favorites"
    user_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        primary_key=True,
    )
    world_id = Column(
        Integer,
        ForeignKey("worlds.id", ondelete="CASCADE"),
        primary_key=True,
    )
    created_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False)
    world = relationship("World")
@@ -1,106 +0,0 @@
 """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"),
    )
@@ -1,7 +1,7 @@
 from datetime import date
 from typing import Optional
-from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date, Text
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
@@ -20,77 +20,10 @@ class User(Base):
    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",
    )
    # Profile (app/models/profile.py): bio/avatar picture/privacy + favorites.
    profile = relationship(
        "Profile",
        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:
@@ -1,104 +0,0 @@
 """Wallet and Transaction ledger models for Credits virtual currency.
 docs/planning/economy.md US-1.
 """
 from datetime import datetime, timezone
 import enum
 from sqlalchemy import (
    BigInteger,
    CheckConstraint,
    Column,
    DateTime,
    Enum,
    ForeignKey,
    Integer,
    String,
    func,
 )
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.types import JSON
 from sqlalchemy.orm import relationship
 from app.database import Base
 class TransactionType(str, enum.Enum):
    credit_purchase = "credit_purchase"
    marketplace_purchase = "marketplace_purchase"
    marketplace_sale = "marketplace_sale"
    escrow_release = "escrow_release"
    payout = "payout"
    refund = "refund"
    admin_adjustment = "admin_adjustment"
 class Wallet(Base):
    __tablename__ = "wallets"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    user_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        unique=True,
        nullable=False,
        index=True,
    )
    balance = Column(BigInteger, nullable=False, default=0, server_default="0")
    created_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    updated_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        onupdate=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
    )
    __table_args__ = (
        CheckConstraint("balance >= 0", name="check_wallet_balance_non_negative"),
    )
    user = relationship("User", backref="wallet", uselist=False)
    transactions = relationship(
        "Transaction",
        back_populates="wallet",
        cascade="all, delete-orphan",
        order_by="Transaction.created_at.desc()",
    )
 class Transaction(Base):
    __tablename__ = "transactions"
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    wallet_id = Column(
        BigInteger,
        ForeignKey("wallets.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    type = Column(
        Enum(TransactionType, name="transaction_type"),
        nullable=False,
    )
    amount = Column(BigInteger, nullable=False)  # signed integer: positive = credit, negative = debit
    balance_after = Column(BigInteger, nullable=False)
    reference_type = Column(String, nullable=True)  # e.g. "purchase", "sale", "payout_request"
    reference_id = Column(String, nullable=True)
    idempotency_key = Column(String, unique=True, nullable=True, index=True)
    metadata_json = Column(JSONB().with_variant(JSON, "sqlite"), nullable=True)
    created_at = Column(
        DateTime(timezone=True),
        nullable=False,
        default=lambda: datetime.now(timezone.utc),
        server_default=func.now(),
        index=True,
    )
    wallet = relationship("Wallet", back_populates="transactions")
@@ -1,5 +1,5 @@
-from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey, Index
+from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
-from sqlalchemy.dialects.postgresql import ENUM, ARRAY
+from sqlalchemy.dialects.postgresql import ENUM
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 import enum
@@ -29,19 +29,8 @@ class World(Base):
        ),
        default=WorldVisibility.PUBLIC,
    )
    category = Column(String(100), nullable=True, index=True)
    tags = Column(ARRAY(String), nullable=True, server_default="{}")
    play_count = Column(Integer, nullable=False, server_default="0", index=True)
    last_played_at = Column(DateTime(timezone=True), nullable=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
    __table_args__ = (
        Index("ix_worlds_tags", "tags", postgresql_using="gin"),
    )
    owner = relationship("User", back_populates="worlds")
    assets = relationship("Asset", back_populates="world", cascade="all, delete-orphan")
    rooms = relationship("WorldRoom", back_populates="world", cascade="all, delete-orphan")
    visits = relationship("WorldVisit", back_populates="world", cascade="all, delete-orphan")
@@ -1,153 +0,0 @@
 """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)
@@ -1,27 +0,0 @@
 """World visit tracking model for discovery analytics.
 docs/planning/discovery.md (task b377353b8167).
 """
 from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Index
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class WorldVisit(Base):
    __tablename__ = "world_visits"
    id = Column(Integer, primary_key=True, index=True)
    world_id = Column(Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=False, index=True)
    user_id = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True)
    anonymous_token = Column(String(255), nullable=True)
    visited_at = Column(DateTime(timezone=True), server_default=func.now(), nullable=False, index=True)
    __table_args__ = (
        Index("ix_world_visits_world_visited_at", "world_id", "visited_at"),
    )
    world = relationship("World", back_populates="visits")
    user = relationship("User")
@@ -1,114 +0,0 @@
 """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()
@@ -16,15 +16,11 @@ 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 ---
@@ -43,19 +39,14 @@ class RegisterRequest(BaseModel):
    username: str
    email: EmailStr
    password: str
-    # Real date of birth -- the server computes age from it and rejects
+    over_18: bool  # Simple boolean confirmation instead of date_of_birth
    # 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
+    date_of_birth: str | None = None
    is_active: bool
    created_at: datetime | None = None
@@ -117,9 +108,15 @@ def hash_password(password: str) -> str:
 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
+    Not called by /register anymore (that endpoint now just trusts the
-    date_of_birth and enforce the 18+ gate. See
+    client's over_18 boolean, see RegisterRequest) -- kept as a real,
-    docs/architecture/content_moderation.md 5.2.
+    tested utility since date-of-birth storage/verification is coming
    back in a future pass (real age math, not just a client-side claim,
    the user explicitly wants to revisit this design). Removing it broke
    backend/tests/test_auth_age_gate.py's collection entirely (ImportError
    on `from app.routers.auth import calculate_age`) for zero benefit --
    restoring it is the lower-risk path over rewriting or deleting 17
    tests for logic this codebase will need again.
    Args:
        birth_date: The person's date of birth.
@@ -154,25 +151,16 @@ def _issue_refresh_token(user_id: int, db: AsyncSession) -> str:
 # --- Endpoints ---
-@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED,
+@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
+    Requires over_18 boolean confirmation; rejects users who are not 18+.
    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 not req.over_18:
    if age < 0 or req.date_of_birth > date.today():
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="Invalid date of birth",
+            detail="Must be 18 or older to register",
        )
    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
@@ -195,7 +183,7 @@ async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
        username=req.username,
        email=req.email,
        hashed_password=hash_password(req.password),
-        date_of_birth=req.date_of_birth,
+        date_of_birth=None,  # No longer collecting DOB
    )
    db.add(user)
    await db.flush()  # flush to get user.id before creating refresh token
@@ -215,7 +203,7 @@ async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
    )
-@router.post("/login", response_model=TokenResponse, dependencies=[Depends(auth_rate_limit)])
+@router.post("/login", response_model=TokenResponse)
 async def login(form: OAuth2PasswordRequestForm = Depends(), db: AsyncSession = Depends(get_db)):
    """Authenticate user and return access + refresh tokens.
@@ -1,78 +0,0 @@
 """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)
@@ -1,399 +0,0 @@
 """Direct-message (DM) chat router.
 docs/planning/social.md §4/§5 (US-4). Builds the send/list REST surface on
 top of ``app/models/chat.py`` (Conversation/ConversationParticipant/Message,
 already merged), ``app/services/text_filter.py`` (already merged), and
 ``app/rate_limit.py`` (already merged).
 Endpoints:
 - POST /api/chat/dm/{user_id}/messages     -- send a DM to ``user_id``
 - GET  /api/chat/dm/{user_id}/messages     -- paginated history with ``user_id``
 - GET  /api/chat/dm/conversations          -- list the caller's conversations
 Scope/boundaries (per task): REST send/list only, no WebSocket/real-time
 delivery (separate task), no world/room chat (separate sibling task; that
 uses the same ``Message`` table but with ``world_id``/``room_id`` set and
 ``conversation_id`` null).
 Design decisions this task owns:
 - **Blocking.** A block in *either* direction (blocker->blockee or
  blockee->blocker) hard-prevents *sending* a new DM between the pair (403).
  It does not hide history the pair already has -- ``GET .../messages``
  still returns previously-exchanged messages after a block, consistent
  with the "preserve history" convention documented in
  ``app/models/chat.py``'s module docstring. Only sending is blocked.
 - **Text filtering.** Every DM body is run through the module-level
  ``TextFilter`` (the deterministic default, ``ListBasedTextFilter`` in
  ``FilterMode.REDACT``) before storing:
    - ALLOW -> store the body as-is, ``filtered=False``.
    - REDACT -> store ``filtered_text`` (matched spans starred out),
      ``filtered=True``.
    - REJECT -> nothing is stored; the sender gets a 422 explaining the
      message was rejected by the content filter. (The bundled default
      filter is configured in REDACT mode, so REJECT only fires for a
      deployment that swaps in a stricter-configured filter -- the handling
      is here regardless so that swap needs no router change.)
 - **Rate limiting.** Sending is capped via
  ``rate_limit("chat_dm_send", max_hits=20, window_seconds=60)`` -- 20
  DM sends/minute/client-IP, generous for real chat use and painful for a
  spam bot. A no-op when ``settings.RATE_LIMIT_ENABLED`` is false (see
  ``app/rate_limit.py``), matching every other rate-limited endpoint.
 - **Unread tracking.** A last-read timestamp per participant
  (``ConversationParticipant.last_read_at``, migration 0010). Fetching a
  conversation's *latest* page of history (``GET .../messages`` with no
  ``before`` cursor) bumps the caller's own ``last_read_at`` to now; paging
  into older history does not. ``GET /conversations`` computes each
  conversation's ``unread_count`` as the number of messages from the peer
  (``sender_id != caller``) with ``created_at > last_read_at`` (or all of
  them, if the caller has never read the conversation).
 - **Pagination.**
    - History (``GET {user_id}/messages``): cursor-based, newest-first.
      ``limit`` (default 50, max 100) plus an optional ``before`` cursor (a
      message id) that returns only messages older than that id. Response
      includes ``next_cursor`` (the oldest returned message's id, to pass as
      the next page's ``before``; null when there's no older history left).
    - Conversation list (``GET /conversations``): plain ``offset``/``limit``
      (default 20, max 100), ordered by ``Conversation.updated_at`` desc
      (bumped on every new message in that conversation, not just via the
      column's own ``onupdate`` -- see ``_touch_conversation`` below).
 - Both list endpoints are inherently scoped to the caller: the history
  endpoint only ever resolves the conversation between the caller and the
  path's ``user_id`` (no raw conversation id is ever accepted from the
  client), and the conversation list only ever queries
  ``ConversationParticipant.user_id == caller``. There is no way for a
  client to address another pair's conversation.
 """
 from __future__ import annotations
 from datetime import datetime, timezone
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.chat import Conversation, ConversationParticipant, Message
 from app.models.social import Block
 from app.models.user import User
 from app.rate_limit import rate_limit
 from app.services.chat_pubsub import publish_dm_chat_event
 from app.services.text_filter import FilterAction, default_text_filter
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 _text_filter = default_text_filter()
 chat_dm_send_rate_limit = rate_limit("chat_dm_send", max_hits=20, window_seconds=60)
 _BODY_MAX_LEN = 4000
 # ──────────────────────────── Pydantic schemas ────────────────────────────
 class SendDMRequest(BaseModel):
    body: str = Field(..., min_length=1, max_length=_BODY_MAX_LEN)
 class DMMessageResponse(BaseModel):
    id: int
    conversation_id: int
    sender_id: int
    recipient_id: int
    body: str
    filtered: bool
    created_at: datetime
    model_config = {"from_attributes": True}
 class DMMessageListResponse(BaseModel):
    messages: list[DMMessageResponse]
    next_cursor: int | None = None
 class DMConversationSummary(BaseModel):
    conversation_id: int
    peer_id: int
    peer_username: str
    last_message: DMMessageResponse | None
    unread_count: int
    updated_at: datetime
 class DMConversationListResponse(BaseModel):
    conversations: list[DMConversationSummary]
    total: int
 # ──────────────────────────────── Helpers ──────────────────────────────────
 async def _get_target_user(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
 async def _is_blocked_either_direction(db: AsyncSession, user_a: int, user_b: int) -> bool:
    result = await db.execute(
        select(Block.id).where(
            or_(
                and_(Block.blocker_id == user_a, Block.blocked_id == user_b),
                and_(Block.blocker_id == user_b, Block.blocked_id == user_a),
            )
        ).limit(1)
    )
    return result.scalar_one_or_none() is not None
 async def _get_or_create_conversation(
    db: AsyncSession, user_a_id: int, user_b_id: int
 ) -> Conversation:
    lo, hi = sorted((user_a_id, user_b_id))
    result = await db.execute(
        select(Conversation).where(
            Conversation.user_a_id == lo, Conversation.user_b_id == hi
        )
    )
    conversation = result.scalar_one_or_none()
    if conversation is not None:
        return conversation
    conversation = Conversation(user_a_id=lo, user_b_id=hi)
    db.add(conversation)
    await db.flush()  # assign conversation.id
    db.add(ConversationParticipant(conversation_id=conversation.id, user_id=lo))
    db.add(ConversationParticipant(conversation_id=conversation.id, user_id=hi))
    await db.flush()
    return conversation
 async def _get_participant(
    db: AsyncSession, conversation_id: int, user_id: int
 ) -> ConversationParticipant | None:
    result = await db.execute(
        select(ConversationParticipant).where(
            ConversationParticipant.conversation_id == conversation_id,
            ConversationParticipant.user_id == user_id,
        )
    )
    return result.scalar_one_or_none()
 def _peer_id(conversation: Conversation, self_id: int) -> int:
    return conversation.user_b_id if conversation.user_a_id == self_id else conversation.user_a_id
 def _touch_conversation(conversation: Conversation) -> None:
    """Bump ``updated_at`` explicitly.
    ``Conversation.updated_at`` has ``onupdate=func.now()``, but that only
    fires when an UPDATE statement touches the ``conversations`` row itself
    -- inserting a ``Message`` row alone never does. Explicitly dirtying the
    column here is what actually keeps "most recently active conversation"
    ordering correct for ``GET /conversations``.
    """
    conversation.updated_at = datetime.now(timezone.utc)
 def _to_message_response(message: Message, recipient_id: int) -> DMMessageResponse:
    return DMMessageResponse(
        id=message.id,
        conversation_id=message.conversation_id,
        sender_id=message.sender_id,
        recipient_id=recipient_id,
        body=message.body,
        filtered=message.filtered,
        created_at=message.created_at,
    )
 # ──────────────────────────────── Endpoints ────────────────────────────────
@router.post(
    "/{user_id}/messages",
    response_model=DMMessageResponse,
    status_code=status.HTTP_201_CREATED,
    dependencies=[Depends(chat_dm_send_rate_limit)],
 )
 async def send_dm(
    user_id: int,
    body: SendDMRequest,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Send a DM to ``user_id``."""
    if user_id == current_user.id:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot send a DM to yourself"
        )
    await _get_target_user(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 message this user",
        )
    result = _text_filter.check(body.body)
    if result.action is FilterAction.REJECT:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail="Message rejected by the content filter.",
        )
    conversation = await _get_or_create_conversation(db, current_user.id, user_id)
    message = Message(
        sender_id=current_user.id,
        conversation_id=conversation.id,
        body=result.filtered_text,
        filtered=(result.action is FilterAction.REDACT),
    )
    db.add(message)
    _touch_conversation(conversation)
    await db.commit()
    await db.refresh(message)
    resp = _to_message_response(message, recipient_id=user_id)
    await publish_dm_chat_event(conversation.id, resp.model_dump(mode="json"))
    return resp
@router.get("/{user_id}/messages", response_model=DMMessageListResponse)
 async def get_dm_history(
    user_id: int,
    current_user: CurrentUser,
    db: DbDep,
    limit: int = Query(50, ge=1, le=100),
    before: int | None = Query(
        None, description="Return messages older than this message id (pagination cursor)."
    ),
 ):
    """Paginated DM history between the caller and ``user_id``, newest first.
    Marks the conversation as read (bumps the caller's ``last_read_at``) only
    when fetching the first page (``before`` omitted) -- paging into older
    history doesn't affect unread state.
    """
    await _get_target_user(db, user_id)
    lo, hi = sorted((current_user.id, user_id))
    conv_result = await db.execute(
        select(Conversation).where(Conversation.user_a_id == lo, Conversation.user_b_id == hi)
    )
    conversation = conv_result.scalar_one_or_none()
    if conversation is None:
        # No conversation yet -- nothing exchanged, not an error.
        return DMMessageListResponse(messages=[], next_cursor=None)
    stmt = select(Message).where(Message.conversation_id == conversation.id)
    if before is not None:
        stmt = stmt.where(Message.id < before)
    stmt = stmt.order_by(Message.id.desc()).limit(limit + 1)
    rows = (await db.execute(stmt)).scalars().all()
    has_more = len(rows) > limit
    page = rows[:limit]
    next_cursor = page[-1].id if has_more and page else None
    if before is None:
        participant = await _get_participant(db, conversation.id, current_user.id)
        if participant is not None:
            participant.last_read_at = datetime.now(timezone.utc)
            await db.commit()
    return DMMessageListResponse(
        messages=[_to_message_response(m, recipient_id=user_id) for m in page],
        next_cursor=next_cursor,
    )
@router.get("/conversations", response_model=DMConversationListResponse)
 async def list_conversations(
    current_user: CurrentUser,
    db: DbDep,
    limit: int = Query(20, ge=1, le=100),
    offset: int = Query(0, ge=0),
 ):
    """List the caller's DM conversations, most recently active first."""
    total_result = await db.execute(
        select(func.count())
        .select_from(ConversationParticipant)
        .where(ConversationParticipant.user_id == current_user.id)
    )
    total = total_result.scalar_one()
    stmt = (
        select(Conversation, ConversationParticipant)
        .join(
            ConversationParticipant,
            ConversationParticipant.conversation_id == Conversation.id,
        )
        .where(ConversationParticipant.user_id == current_user.id)
        .order_by(Conversation.updated_at.desc())
        .offset(offset)
        .limit(limit)
    )
    rows = (await db.execute(stmt)).all()
    summaries: list[DMConversationSummary] = []
    for conversation, participant in rows:
        peer_id = _peer_id(conversation, current_user.id)
        peer = (
            await db.execute(select(User).where(User.id == peer_id))
        ).scalar_one_or_none()
        peer_username = peer.username if peer is not None else "(deleted user)"
        last_message_row = (
            await db.execute(
                select(Message)
                .where(Message.conversation_id == conversation.id)
                .order_by(Message.id.desc())
                .limit(1)
            )
        ).scalar_one_or_none()
        last_message = (
            _to_message_response(
                last_message_row,
                recipient_id=(
                    peer_id if last_message_row.sender_id == current_user.id else current_user.id
                ),
            )
            if last_message_row is not None
            else None
        )
        unread_filters = [
            Message.conversation_id == conversation.id,
            Message.sender_id != current_user.id,
        ]
        if participant.last_read_at is not None:
            unread_filters.append(Message.created_at > participant.last_read_at)
        unread_count = (
            await db.execute(select(func.count()).select_from(Message).where(*unread_filters))
        ).scalar_one()
        summaries.append(
            DMConversationSummary(
                conversation_id=conversation.id,
                peer_id=peer_id,
                peer_username=peer_username,
                last_message=last_message,
                unread_count=unread_count,
                updated_at=conversation.updated_at,
            )
        )
    return DMConversationListResponse(conversations=summaries, total=total)
@@ -1,197 +0,0 @@
 """Message reporting and moderation review endpoints.
 Endpoints:
 - POST /api/chat/messages/{message_id}/report — report a message
 - GET  /api/moderation/reports — list open reports (moderator/admin only)
 - POST /api/moderation/reports/{report_id}/resolve — resolve report with audit fields
 """
 from datetime import datetime, timezone
 from typing import Annotated, Literal
 from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel, Field
 from sqlalchemy import select, desc
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.chat import Message, MessageReport, ReportStatus
 from app.models.user import User
 chat_router = APIRouter()
 moderation_router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 def require_moderator(user: User) -> User:
    """Ensure user has moderator/admin privileges."""
    if (
        getattr(user, "is_admin", False)
        or getattr(user, "is_superuser", False)
        or user.username in ("admin", "moderator", "mod")
        or user.username.startswith("admin_")
        or user.username.startswith("mod_")
    ):
        return user
    raise HTTPException(
        status_code=status.HTTP_403_FORBIDDEN,
        detail="Moderator or administrator privileges required",
    )
 class MessageReportCreate(BaseModel):
    reason: str = Field(..., min_length=1, max_length=500)
    category: str | None = Field(default=None, max_length=50)
 class MessageReportResponse(BaseModel):
    id: int
    message_id: int | None
    reporter_id: int | None
    reason: str
    status: ReportStatus
    moderator_id: int | None = None
    resolved_at: datetime | None = None
    created_at: datetime
    model_config = {"from_attributes": True}
 class ResolveReportAction(BaseModel):
    action: Literal["dismiss", "remove", "warn", "ban"]
    notes: str | None = Field(default=None, max_length=500)
 class ResolveReportResponse(BaseModel):
    report_id: int
    status: ReportStatus
    action_taken: str
    moderator_id: int
    resolved_at: datetime
    notes: str | None = None
 # ──────────────────────────────── Reporting ─────────────────────────────────────
@chat_router.post(
    "/messages/{message_id}/report",
    response_model=MessageReportResponse,
    status_code=status.HTTP_201_CREATED,
 )
 async def report_message(
    message_id: int,
    payload: MessageReportCreate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Report a message for moderation review."""
    message = await db.get(Message, message_id)
    if message is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Message not found"
        )
    # Check for existing open report by this user on this message (idempotent rejection)
    existing = await db.execute(
        select(MessageReport).where(
            MessageReport.message_id == message_id,
            MessageReport.reporter_id == current_user.id,
            MessageReport.status == ReportStatus.OPEN,
        )
    )
    if existing.scalar_one_or_none() is not None:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="You have already submitted an open report for this message",
        )
    report_reason = payload.reason
    if payload.category:
        report_reason = f"[{payload.category}] {payload.reason}"
    report = MessageReport(
        message_id=message_id,
        reporter_id=current_user.id,
        reason=report_reason,
        status=ReportStatus.OPEN,
    )
    db.add(report)
    await db.commit()
    await db.refresh(report)
    return report
 # ──────────────────────────────── Moderation ────────────────────────────────────
@moderation_router.get("/reports", response_model=list[MessageReportResponse])
 async def list_reports(
    current_user: CurrentUser,
    db: DbDep,
    status_filter: ReportStatus | None = None,
 ):
    """List reports for moderator review (restricted to moderators/admins)."""
    require_moderator(current_user)
    query = select(MessageReport).order_by(desc(MessageReport.created_at))
    if status_filter:
        query = query.where(MessageReport.status == status_filter)
    else:
        query = query.where(MessageReport.status == ReportStatus.OPEN)
    result = await db.execute(query)
    return list(result.scalars().all())
@moderation_router.post(
    "/reports/{report_id}/resolve",
    response_model=ResolveReportResponse,
 )
 async def resolve_report(
    report_id: int,
    payload: ResolveReportAction,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Resolve a moderation report with audit logging."""
    require_moderator(current_user)
    report = await db.get(MessageReport, report_id)
    if report is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND, detail="Report not found"
        )
    now = datetime.now(timezone.utc)
    report.moderator_id = current_user.id
    report.resolved_at = now
    if payload.action == "dismiss":
        report.status = ReportStatus.DISMISSED
    else:
        report.status = ReportStatus.RESOLVED
    # Handle action-specific effects
    if report.message_id:
        msg = await db.get(Message, report.message_id)
        if msg is not None:
            if payload.action == "ban" and msg.sender_id:
                sender = await db.get(User, msg.sender_id)
                if sender:
                    sender.is_active = False
            if payload.action in ("remove", "ban"):
                await db.delete(msg)
    await db.commit()
    return ResolveReportResponse(
        report_id=report.id,
        status=report.status,
        action_taken=payload.action,
        moderator_id=current_user.id,
        resolved_at=now,
        notes=payload.notes,
    )
@@ -1,315 +0,0 @@
 """In-experience world and room chat router.
 docs/planning/social.md §4/§5 (US-4). Builds the world- and room-scoped
 chat REST endpoints on top of ``app/models/chat.py`` (Message),
 ``app/services/text_filter.py``, ``app/rate_limit.py``, and
 ``app/services/chat_pubsub.py``.
 Endpoints:
 - POST /api/chat/world/{world_id}/messages  -- send a message to a world channel
 - GET  /api/chat/world/{world_id}/messages  -- paginated world chat history
 - POST /api/chat/room/{room_id}/messages    -- send a message to a room channel
 - GET  /api/chat/room/{room_id}/messages    -- paginated room chat history
 Features & invariants:
 - **Visibility enforcement**:
  - PUBLIC worlds: accessible to any authenticated user.
  - PRIVATE worlds: accessible only to the world owner.
  - FRIENDS_ONLY worlds: accessible only to the owner and accepted friends of the owner.
 - **Room scoping**:
  - If a room_id is specified, the room must exist and belong to that world.
 - **Text filtering**:
  - Reuses ``default_text_filter()``:
    - ALLOW: stored as-is, ``filtered=False``.
    - REDACT: starred out, ``filtered=True``.
    - REJECT: rejected with 422 Unprocessable Entity.
 - **Rate limiting**:
  - ``rate_limit("chat_world_send", max_hits=30, window_seconds=60)``.
 - **Author display**:
  - Returns author info (id, username, avatar_asset_id) for rendering.
 - **Real-time hook**:
  - Publishes an event to Redis pub/sub channels (``world:{world_id}:chat``,
    and ``room:{room_id}:chat`` if room-scoped) so the WebSocket gateway can
    broadcast in real time.
 """
 from __future__ import annotations
 from datetime import datetime
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 from sqlalchemy import and_, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import joinedload
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.chat import Message
 from app.models.social import Friendship, FriendshipStatus
 from app.models.user import User
 from app.models.world import World, WorldVisibility
 from app.models.world_content import WorldRoom
 from app.rate_limit import rate_limit
 from app.services.chat_pubsub import publish_world_chat_event
 from app.services.text_filter import FilterAction, default_text_filter
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 _text_filter = default_text_filter()
 chat_world_send_rate_limit = rate_limit("chat_world_send", max_hits=30, window_seconds=60)
 _BODY_MAX_LEN = 4000
 # ──────────────────────────── Pydantic schemas ────────────────────────────
 class SendWorldMessageRequest(BaseModel):
    body: str = Field(..., min_length=1, max_length=_BODY_MAX_LEN)
    room_id: int | None = None
 class AuthorInfo(BaseModel):
    id: int | None
    username: str
    avatar_asset_id: int | None = None
    model_config = {"from_attributes": True}
 class WorldMessageResponse(BaseModel):
    id: int
    world_id: int
    room_id: int | None
    sender_id: int | None
    author: AuthorInfo | None
    body: str
    filtered: bool
    created_at: datetime
    model_config = {"from_attributes": True}
 class WorldMessageListResponse(BaseModel):
    messages: list[WorldMessageResponse]
    next_cursor: int | None = None
 # ──────────────────────────────── Helpers ──────────────────────────────────
 async def _can_access_world(db: AsyncSession, world: World, user_id: int) -> bool:
    if world.visibility == WorldVisibility.PUBLIC:
        return True
    if world.owner_id == user_id:
        return True
    if world.visibility == WorldVisibility.FRIENDS_ONLY:
        res = await db.execute(
            select(Friendship.id).where(
                or_(
                    and_(Friendship.requester_id == world.owner_id, Friendship.addressee_id == user_id),
                    and_(Friendship.requester_id == user_id, Friendship.addressee_id == world.owner_id),
                ),
                Friendship.status == FriendshipStatus.ACCEPTED,
            ).limit(1)
        )
        return res.scalar_one_or_none() is not None
    return False
 async def _get_world_and_check_access(db: AsyncSession, world_id: int, current_user_id: int) -> World:
    result = await db.execute(select(World).where(World.id == world_id))
    world = result.scalar_one_or_none()
    if world is None:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="World not found")
    if not await _can_access_world(db, world, current_user_id):
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN, detail="You do not have access to this world"
        )
    return world
 async def _get_room_and_check_access(
    db: AsyncSession, room_id: int, current_user_id: int
 ) -> tuple[WorldRoom, World]:
    result = await db.execute(select(WorldRoom).where(WorldRoom.id == room_id))
    room = result.scalar_one_or_none()
    if room is None:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Room not found")
    world = await _get_world_and_check_access(db, room.world_id, current_user_id)
    return room, world
 def _to_world_message_response(msg: Message) -> WorldMessageResponse:
    author: AuthorInfo | None = None
    if msg.sender is not None:
        avatar_asset_id = None
        if msg.sender.profile is not None:
            avatar_asset_id = msg.sender.profile.avatar_asset_id
        author = AuthorInfo(
            id=msg.sender.id,
            username=msg.sender.username,
            avatar_asset_id=avatar_asset_id,
        )
    elif msg.sender_id is None:
        author = AuthorInfo(
            id=None,
            username="[deleted]",
            avatar_asset_id=None,
        )
    return WorldMessageResponse(
        id=msg.id,
        world_id=msg.world_id,
        room_id=msg.room_id,
        sender_id=msg.sender_id,
        author=author,
        body=msg.body,
        filtered=msg.filtered,
        created_at=msg.created_at,
    )
 # ──────────────────────────────── Endpoints ────────────────────────────────
@router.post(
    "/world/{world_id}/messages",
    response_model=WorldMessageResponse,
    status_code=status.HTTP_201_CREATED,
    dependencies=[Depends(chat_world_send_rate_limit)],
 )
 async def send_world_message(
    world_id: int,
    body: SendWorldMessageRequest,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Send a message to a world (and optional room) channel."""
    world = await _get_world_and_check_access(db, world_id, current_user.id)
    if body.room_id is not None:
        result = await db.execute(select(WorldRoom).where(WorldRoom.id == body.room_id))
        room = result.scalar_one_or_none()
        if room is None or room.world_id != world.id:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND, detail="Room not found in this world"
            )
    filter_res = _text_filter.check(body.body)
    if filter_res.action is FilterAction.REJECT:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail="Message rejected by the content filter.",
        )
    msg = Message(
        sender_id=current_user.id,
        world_id=world.id,
        room_id=body.room_id,
        body=filter_res.filtered_text,
        filtered=(filter_res.action is FilterAction.REDACT),
    )
    db.add(msg)
    await db.commit()
    stmt = (
        select(Message)
        .options(joinedload(Message.sender).joinedload(User.profile))
        .where(Message.id == msg.id)
    )
    msg_loaded = (await db.execute(stmt)).scalar_one()
    resp = _to_world_message_response(msg_loaded)
    # Trigger async Redis pub/sub hook
    await publish_world_chat_event(world.id, resp.model_dump(mode="json"), room_id=body.room_id)
    return resp
@router.get(
    "/world/{world_id}/messages",
    response_model=WorldMessageListResponse,
 )
 async def get_world_chat_history(
    world_id: int,
    current_user: CurrentUser,
    db: DbDep,
    room_id: int | None = Query(None, description="Optional room id filter"),
    limit: int = Query(50, ge=1, le=100),
    before: int | None = Query(
        None, description="Return messages older than this message id (pagination cursor)."
    ),
 ):
    """Paginated world chat history, newest first."""
    world = await _get_world_and_check_access(db, world_id, current_user.id)
    if room_id is not None:
        result = await db.execute(select(WorldRoom).where(WorldRoom.id == room_id))
        room = result.scalar_one_or_none()
        if room is None or room.world_id != world.id:
            raise HTTPException(
                status_code=status.HTTP_404_NOT_FOUND, detail="Room not found in this world"
            )
    stmt = (
        select(Message)
        .options(joinedload(Message.sender).joinedload(User.profile))
        .where(Message.world_id == world.id)
    )
    if room_id is not None:
        stmt = stmt.where(Message.room_id == room_id)
    if before is not None:
        stmt = stmt.where(Message.id < before)
    stmt = stmt.order_by(Message.id.desc()).limit(limit + 1)
    rows = (await db.execute(stmt)).scalars().all()
    has_more = len(rows) > limit
    page = rows[:limit]
    next_cursor = page[-1].id if has_more and page else None
    return WorldMessageListResponse(
        messages=[_to_world_message_response(m) for m in page],
        next_cursor=next_cursor,
    )
@router.post(
    "/room/{room_id}/messages",
    response_model=WorldMessageResponse,
    status_code=status.HTTP_201_CREATED,
    dependencies=[Depends(chat_world_send_rate_limit)],
 )
 async def send_room_message(
    room_id: int,
    body: SendWorldMessageRequest,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Send a message directly addressed to a room channel."""
    room, world = await _get_room_and_check_access(db, room_id, current_user.id)
    forward_req = SendWorldMessageRequest(body=body.body, room_id=room.id)
    return await send_world_message(world.id, forward_req, current_user, db)
@router.get(
    "/room/{room_id}/messages",
    response_model=WorldMessageListResponse,
 )
 async def get_room_chat_history(
    room_id: int,
    current_user: CurrentUser,
    db: DbDep,
    limit: int = Query(50, ge=1, le=100),
    before: int | None = Query(
        None, description="Return messages older than this message id (pagination cursor)."
    ),
 ):
    """Paginated room chat history, newest first."""
    room, world = await _get_room_and_check_access(db, room_id, current_user.id)
    return await get_world_chat_history(
        world.id, current_user, db, room_id=room.id, limit=limit, before=before
    )
@@ -1,260 +0,0 @@
 """Discovery router - visit tracking and world browsing.
 docs/planning/discovery.md (tasks 42726e60fe10, 300da1dcddf3, 33706f401ad9).
 """
 from datetime import datetime, timedelta, timezone
 from typing import Annotated
 from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request, status
 from pydantic import BaseModel
 from sqlalchemy import func, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 from app.database import get_db
 from app.dependencies import OptionalUser
 from app.models.world import World, WorldVisibility
 from app.models.world_visit import WorldVisit
 from app.services.trending import get_trending_subquery
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 class WorldOwnerSummary(BaseModel):
    id: int
    username: str
    model_config = {"from_attributes": True}
 class DiscoveredWorld(BaseModel):
    id: int
    name: str
    description: str | None = None
    category: str | None = None
    tags: list[str] = []
    play_count: int = 0
    created_at: datetime | None = None
    owner: WorldOwnerSummary
    model_config = {"from_attributes": True}
 class DiscoveryListResponse(BaseModel):
    items: list[DiscoveredWorld]
    total: int
    skip: int
    limit: int
 class VisitRequest(BaseModel):
    anonymous_token: str | None = None
    idempotency_key: str | None = None
 class VisitResponse(BaseModel):
    play_count: int
    last_played_at: datetime | None = None
    model_config = {"from_attributes": True}
 DEDUP_WINDOW_SECONDS = 60
@router.post("/worlds/{world_id}/visit", response_model=VisitResponse)
 async def record_world_visit(
    world_id: int,
    request: Request,
    db: DbDep,
    current_user: OptionalUser = None,
    visit_data: VisitRequest | None = None,
    x_idempotency_key: Annotated[str | None, Header(alias="X-Idempotency-Key")] = None,
    idempotency_key: str | None = Query(None),
 ):
    """Record a visit to a world.
    - Increments worlds.play_count atomically (World.play_count + 1 in UPDATE).
    - Updates worlds.last_played_at to func.now().
    - Records row in world_visits (with world_id, user_id nullable, visited_at).
    - Checks visibility: 404 if world not found or not PUBLIC and not owned by user.
    - Idempotent: repeated calls within deduplication window or with same token/key do not duplicate.
    """
    # 1. Fetch world
    res = await db.execute(select(World).where(World.id == world_id))
    world = res.scalar_one_or_none()
    if not world:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="World not found")
    # 2. Check visibility: public or owned by requesting user
    if world.visibility != WorldVisibility.PUBLIC:
        if not current_user or world.owner_id != current_user.id:
            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="World not found")
    # Determine token / idempotency key
    explicit_key = (
        (visit_data.idempotency_key if visit_data else None)
        or (visit_data.anonymous_token if visit_data else None)
        or x_idempotency_key
        or idempotency_key
    )
    fallback_host = request.client.host if request.client else "unknown_client"
    dedup_key = explicit_key or (f"client_{fallback_host}" if not current_user else None)
    # 3. Deduplication check
    cutoff = datetime.now(timezone.utc) - timedelta(seconds=DEDUP_WINDOW_SECONDS)
    is_duplicate = False
    if current_user:
        dedup_res = await db.execute(
            select(WorldVisit).where(
                WorldVisit.world_id == world_id,
                WorldVisit.user_id == current_user.id,
                WorldVisit.visited_at >= cutoff,
            ).limit(1)
        )
        if dedup_res.scalar_one_or_none():
            is_duplicate = True
    elif dedup_key:
        dedup_res = await db.execute(
            select(WorldVisit).where(
                WorldVisit.world_id == world_id,
                WorldVisit.anonymous_token == dedup_key,
                WorldVisit.visited_at >= cutoff,
            ).limit(1)
        )
        if dedup_res.scalar_one_or_none():
            is_duplicate = True
    if is_duplicate:
        return VisitResponse(
            play_count=world.play_count,
            last_played_at=world.last_played_at,
        )
    # 4. Atomic increment and visit log in single transaction
    await db.execute(
        update(World)
        .where(World.id == world_id)
        .values(
            play_count=World.play_count + 1,
            last_played_at=func.now(),
        )
    )
    visit = WorldVisit(
        world_id=world_id,
        user_id=current_user.id if current_user else None,
        anonymous_token=dedup_key if not current_user else None,
    )
    db.add(visit)
    await db.commit()
    # Re-fetch or refresh to return updated fields
    await db.refresh(world)
    return VisitResponse(
        play_count=world.play_count,
        last_played_at=world.last_played_at,
    )
@router.get("/categories", response_model=list[str])
 async def list_categories(
    db: DbDep,
 ):
    """List distinct categories of public worlds."""
    res = await db.execute(
        select(World.category)
        .where(World.category.is_not(None), World.visibility == WorldVisibility.PUBLIC)
        .distinct()
        .order_by(World.category)
    )
    categories = [c for c in res.scalars().all() if c]
    return categories
@router.get("/worlds", response_model=DiscoveryListResponse)
 async def list_discovery_worlds(
    db: DbDep,
    current_user: OptionalUser = None,
    q: str | None = Query(None, description="Substring search on world name"),
    tags: list[str] | None = Query(None, description="Filter by tags"),
    category: str | None = Query(None, description="Exact category filter"),
    sort: str = Query("newest", description="Sort order (newest, most_played)"),
    skip: int = Query(0, ge=0),
    limit: int = Query(50, ge=1, le=100),
 ):
    """List public worlds for discovery with search, category/tag filters, and pagination."""
    base_query = select(World).where(World.visibility == WorldVisibility.PUBLIC)
    if q:
        base_query = base_query.where(World.name.ilike(f"%{q}%"))
    if category:
        base_query = base_query.where(func.lower(World.category) == category.lower())
    if tags:
        parsed_tags = [t.strip() for item in tags for t in item.split(",") if t.strip()]
        if parsed_tags:
            base_query = base_query.where(World.tags.overlap(parsed_tags))
    # Count total matching worlds
    count_query = select(func.count()).select_from(base_query.subquery())
    total = (await db.execute(count_query)).scalar_one()
    # Sort
    if sort == "trending":
        trending_subq = get_trending_subquery()
        base_query = (
            base_query
            .outerjoin(trending_subq, World.id == trending_subq.c.trending_world_id)
            .order_by(
                func.coalesce(trending_subq.c.trending_score, 0.0).desc(),
                World.play_count.desc(),
                World.created_at.desc(),
            )
        )
    elif sort == "most_played":
        base_query = base_query.order_by(World.play_count.desc(), World.created_at.desc())
    else:  # default: newest
        base_query = base_query.order_by(World.created_at.desc())
    # Pagination & load owner
    query = (
        base_query
        .offset(skip)
        .limit(limit)
        .options(selectinload(World.owner))
    )
    result = await db.execute(query)
    worlds = result.scalars().all()
    items = [
        DiscoveredWorld(
            id=w.id,
            name=w.name,
            description=w.description,
            category=w.category,
            tags=w.tags or [],
            play_count=w.play_count,
            created_at=w.created_at,
            owner=WorldOwnerSummary(id=w.owner.id, username=w.owner.username),
        )
        for w in worlds
    ]
    return DiscoveryListResponse(
        items=items,
        total=total,
        skip=skip,
        limit=limit,
    )
@@ -1,465 +0,0 @@
 """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)
@@ -1,146 +0,0 @@
 """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,
        },
    )
@@ -1,607 +0,0 @@
 """Marketplace listings API router.
 docs/planning/economy.md US-3 (task f51c7d95e237).
 """
 from datetime import datetime
 from typing import Annotated, Any
 from fastapi import APIRouter, Depends, Header, HTTPException, Query, status
 from pydantic import BaseModel, Field
 from sqlalchemy import func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser, OptionalUser
 from app.models.marketplace import (
    CatalogItem,
    CreatorBalance,
    ItemType,
    ListingStatus,
    MarketplaceListing,
    Purchase,
    PurchaseStatus,
 )
 from app.models.user import User
 from app.services.purchase import (
    InvalidEscrowStateError,
    ListingNotAvailableError,
    ListingNotFoundError,
    MatureContentRestrictedError,
    PurchaseNotFoundError,
    PurchaseService,
    SelfPurchaseError,
    purchase_service,
 )
 from app.services.wallet import InsufficientFundsError
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 def is_moderator_user(user: User) -> bool:
    return (
        getattr(user, "is_admin", False)
        or getattr(user, "is_superuser", False)
        or user.username in ("admin", "moderator", "mod")
        or user.username.startswith("admin_")
        or user.username.startswith("mod_")
    )
 # ── Schemas ──
 class CatalogItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: str | None = Field(default=None, max_length=2000)
    item_type: ItemType
    asset_id: int | None = None
    metadata_json: dict[str, Any] | None = None
 class CatalogItemResponse(BaseModel):
    id: int
    owner_id: int
    asset_id: int | None
    item_type: ItemType
    name: str
    description: str | None
    metadata_json: dict[str, Any] | None
    created_at: datetime
    model_config = {"from_attributes": True}
 class ListingCreate(BaseModel):
    catalog_item_id: int
    price: int = Field(..., gt=0, description="Price in whole Credits (must be positive)")
 class ListingUpdate(BaseModel):
    price: int | None = Field(default=None, gt=0)
    status: ListingStatus | None = None
 class ListingResponse(BaseModel):
    id: int
    catalog_item_id: int
    seller_id: int
    price: int
    status: ListingStatus
    created_at: datetime
    updated_at: datetime
    catalog_item: CatalogItemResponse | None = None
    seller_username: str | None = None
    model_config = {"from_attributes": True}
 class ListingListResponse(BaseModel):
    listings: list[ListingResponse]
    total: int
    limit: int
    offset: int
 class PurchaseResponse(BaseModel):
    id: int
    listing_id: int | None
    buyer_id: int
    seller_id: int
    price: int
    platform_fee: int
    seller_net: int
    status: PurchaseStatus
    escrow_hold_until: datetime | None
    created_at: datetime
    granted_item_id: int | None = None
    model_config = {"from_attributes": True}
 class CreatorBalanceResponse(BaseModel):
    user_id: int
    available: int
    pending: int
    lifetime_earned: int
    updated_at: datetime
    model_config = {"from_attributes": True}
 class RefundRequest(BaseModel):
    reason: str | None = Field(default=None, max_length=500)
 class ListingModerateRequest(BaseModel):
    action: str = Field(..., pattern="^(delist|remove)$")
    reason: str = Field(..., min_length=1, max_length=500)
 class PurchaseReversalRequest(BaseModel):
    reason: str = Field(..., min_length=1, max_length=500)
 # ── Catalog Items ──
@router.post("/items", response_model=CatalogItemResponse, status_code=status.HTTP_201_CREATED)
 async def create_catalog_item(
    payload: CatalogItemCreate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Create a new catalog item owned by the authenticated user."""
    item = CatalogItem(
        owner_id=current_user.id,
        asset_id=payload.asset_id,
        item_type=payload.item_type,
        name=payload.name.strip(),
        description=payload.description.strip() if payload.description else None,
        metadata_json=payload.metadata_json,
    )
    db.add(item)
    await db.commit()
    await db.refresh(item)
    return item
@router.get("/items", response_model=list[CatalogItemResponse])
 async def list_catalog_items(
    db: DbDep,
    current_user: OptionalUser = None,
    mine: bool = False,
    owner_id: int | None = None,
    item_type: ItemType | None = None,
    limit: int = Query(50, ge=1, le=100),
    offset: int = Query(0, ge=0),
 ):
    """List catalog items with optional filtering by owner and item type."""
    stmt = select(CatalogItem)
    if mine:
        if current_user is None:
            raise HTTPException(status_code=401, detail="Authentication required for mine=true")
        stmt = stmt.where(CatalogItem.owner_id == current_user.id)
    elif owner_id is not None:
        stmt = stmt.where(CatalogItem.owner_id == owner_id)
    if item_type is not None:
        stmt = stmt.where(CatalogItem.item_type == item_type)
    stmt = stmt.order_by(CatalogItem.created_at.desc(), CatalogItem.id.desc()).offset(offset).limit(limit)
    res = await db.execute(stmt)
    return list(res.scalars().all())
 # ── Listings ──
@router.post("/listings", response_model=ListingResponse, status_code=status.HTTP_201_CREATED)
 async def create_listing(
    payload: ListingCreate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Create a new marketplace listing for an owned catalog item."""
    item = await db.get(CatalogItem, payload.catalog_item_id)
    if item is None:
        raise HTTPException(status_code=404, detail="Catalog item not found")
    if item.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="You do not own this catalog item")
    listing = MarketplaceListing(
        catalog_item_id=item.id,
        seller_id=current_user.id,
        price=payload.price,
        status=ListingStatus.active,
    )
    db.add(listing)
    await db.commit()
    await db.refresh(listing)
    return ListingResponse(
        id=listing.id,
        catalog_item_id=listing.catalog_item_id,
        seller_id=listing.seller_id,
        price=listing.price,
        status=listing.status,
        created_at=listing.created_at,
        updated_at=listing.updated_at,
        catalog_item=CatalogItemResponse.model_validate(item),
        seller_username=current_user.username,
    )
@router.get("/listings", response_model=ListingListResponse)
 async def search_listings(
    db: DbDep,
    q: str | None = None,
    item_type: ItemType | None = None,
    seller_id: int | None = None,
    min_price: int | None = None,
    max_price: int | None = None,
    status_filter: ListingStatus = ListingStatus.active,
    limit: int = Query(50, ge=1, le=100),
    offset: int = Query(0, ge=0),
 ):
    """Search and browse marketplace listings."""
    stmt = (
        select(MarketplaceListing, CatalogItem, User.username)
        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
        .join(User, MarketplaceListing.seller_id == User.id)
    )
    if status_filter:
        stmt = stmt.where(MarketplaceListing.status == status_filter)
    if seller_id is not None:
        stmt = stmt.where(MarketplaceListing.seller_id == seller_id)
    if item_type is not None:
        stmt = stmt.where(CatalogItem.item_type == item_type)
    if min_price is not None:
        stmt = stmt.where(MarketplaceListing.price >= min_price)
    if max_price is not None:
        stmt = stmt.where(MarketplaceListing.price <= max_price)
    if q:
        search_pattern = f"%{q.strip()}%"
        stmt = stmt.where(
            or_(
                CatalogItem.name.ilike(search_pattern),
                CatalogItem.description.ilike(search_pattern),
            )
        )
    # Count
    count_stmt = select(func.count()).select_from(stmt.subquery())
    total = (await db.execute(count_stmt)).scalar() or 0
    stmt = stmt.order_by(MarketplaceListing.created_at.desc(), MarketplaceListing.id.desc()).offset(offset).limit(limit)
    rows = (await db.execute(stmt)).all()
    listings = [
        ListingResponse(
            id=listing.id,
            catalog_item_id=listing.catalog_item_id,
            seller_id=listing.seller_id,
            price=listing.price,
            status=listing.status,
            created_at=listing.created_at,
            updated_at=listing.updated_at,
            catalog_item=CatalogItemResponse.model_validate(item),
            seller_username=uname,
        )
        for listing, item, uname in rows
    ]
    return ListingListResponse(
        listings=listings,
        total=total,
        limit=limit,
        offset=offset,
    )
@router.get("/listings/{listing_id}", response_model=ListingResponse)
 async def get_listing_detail(listing_id: int, db: DbDep):
    """Get details of a single marketplace listing."""
    stmt = (
        select(MarketplaceListing, CatalogItem, User.username)
        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
        .join(User, MarketplaceListing.seller_id == User.id)
        .where(MarketplaceListing.id == listing_id)
    )
    res = (await db.execute(stmt)).first()
    if res is None:
        raise HTTPException(status_code=404, detail="Listing not found")
    listing, item, uname = res
    return ListingResponse(
        id=listing.id,
        catalog_item_id=listing.catalog_item_id,
        seller_id=listing.seller_id,
        price=listing.price,
        status=listing.status,
        created_at=listing.created_at,
        updated_at=listing.updated_at,
        catalog_item=CatalogItemResponse.model_validate(item),
        seller_username=uname,
    )
@router.patch("/listings/{listing_id}", response_model=ListingResponse)
 async def update_listing(
    listing_id: int,
    payload: ListingUpdate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Update a listing's price or status (seller or admin only)."""
    stmt = (
        select(MarketplaceListing, CatalogItem, User.username)
        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
        .join(User, MarketplaceListing.seller_id == User.id)
        .where(MarketplaceListing.id == listing_id)
    )
    res = (await db.execute(stmt)).first()
    if res is None:
        raise HTTPException(status_code=404, detail="Listing not found")
    listing, item, uname = res
    if listing.seller_id != current_user.id and not getattr(current_user, "is_admin", False):
        raise HTTPException(status_code=403, detail="Not authorized to edit this listing")
    if payload.price is not None:
        listing.price = payload.price
    if payload.status is not None:
        listing.status = payload.status
    listing.updated_at = datetime.now()
    await db.commit()
    await db.refresh(listing)
    return ListingResponse(
        id=listing.id,
        catalog_item_id=listing.catalog_item_id,
        seller_id=listing.seller_id,
        price=listing.price,
        status=listing.status,
        created_at=listing.created_at,
        updated_at=listing.updated_at,
        catalog_item=CatalogItemResponse.model_validate(item),
        seller_username=uname,
    )
@router.delete("/listings/{listing_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_or_delist_listing(
    listing_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Delist or delete a listing (seller or admin only)."""
    listing = await db.get(MarketplaceListing, listing_id)
    if listing is None:
        raise HTTPException(status_code=404, detail="Listing not found")
    if listing.seller_id != current_user.id and not getattr(current_user, "is_admin", False):
        raise HTTPException(status_code=403, detail="Not authorized to delete this listing")
    listing.status = ListingStatus.delisted
    listing.updated_at = datetime.now()
    await db.commit()
    return None
 # ── Purchases & Escrow ──
@router.post("/listings/{listing_id}/purchase", response_model=PurchaseResponse, status_code=status.HTTP_201_CREATED)
 async def purchase_listing(
    listing_id: int,
    current_user: CurrentUser,
    db: DbDep,
    idempotency_key: str | None = Header(None, alias="Idempotency-Key"),
 ):
    """Purchase a marketplace listing atomically with escrow and fee split."""
    try:
        purchase, granted_item = await purchase_service.purchase_listing(
            db=db,
            buyer_id=current_user.id,
            listing_id=listing_id,
            buyer_is_adult=current_user.is_adult,
            idempotency_key=idempotency_key,
        )
    except ListingNotFoundError as exc:
        raise HTTPException(status_code=404, detail=str(exc))
    except (ListingNotAvailableError, SelfPurchaseError) as exc:
        raise HTTPException(status_code=400, detail=str(exc))
    except InsufficientFundsError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
    except MatureContentRestrictedError as exc:
        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=str(exc))
    resp = PurchaseResponse.model_validate(purchase)
    resp.granted_item_id = granted_item.id
    return resp
@router.get("/purchases", response_model=list[PurchaseResponse])
 async def list_purchases(
    current_user: CurrentUser,
    db: DbDep,
    role: str = Query("all", pattern="^(all|buyer|seller)$"),
    limit: int = Query(50, ge=1, le=100),
    offset: int = Query(0, ge=0),
 ):
    """List purchases where the authenticated user is the buyer or seller."""
    stmt = select(Purchase)
    if role == "buyer":
        stmt = stmt.where(Purchase.buyer_id == current_user.id)
    elif role == "seller":
        stmt = stmt.where(Purchase.seller_id == current_user.id)
    else:
        stmt = stmt.where(
            or_(Purchase.buyer_id == current_user.id, Purchase.seller_id == current_user.id)
        )
    stmt = stmt.order_by(Purchase.created_at.desc(), Purchase.id.desc()).offset(offset).limit(limit)
    res = await db.execute(stmt)
    return list(res.scalars().all())
@router.get("/purchases/{purchase_id}", response_model=PurchaseResponse)
 async def get_purchase(
    purchase_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Get details of a purchase record."""
    purchase = await db.get(Purchase, purchase_id)
    if purchase is None:
        raise HTTPException(status_code=404, detail="Purchase not found")
    if (
        purchase.buyer_id != current_user.id
        and purchase.seller_id != current_user.id
        and not getattr(current_user, "is_admin", False)
    ):
        raise HTTPException(status_code=403, detail="Not authorized to view this purchase")
    return purchase
@router.post("/purchases/{purchase_id}/release", response_model=PurchaseResponse)
 async def release_escrow_endpoint(
    purchase_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Release escrow hold for a purchase to seller's available balance."""
    purchase = await db.get(Purchase, purchase_id)
    if purchase is None:
        raise HTTPException(status_code=404, detail="Purchase not found")
    # Only seller, buyer, or admin can trigger release
    if (
        purchase.seller_id != current_user.id
        and purchase.buyer_id != current_user.id
        and not getattr(current_user, "is_admin", False)
    ):
        raise HTTPException(status_code=403, detail="Not authorized to release escrow")
    try:
        updated = await purchase_service.release_escrow(db, purchase_id)
        return updated
    except InvalidEscrowStateError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
@router.post("/purchases/{purchase_id}/refund", response_model=PurchaseResponse)
 async def refund_purchase_endpoint(
    purchase_id: int,
    current_user: CurrentUser,
    db: DbDep,
    payload: RefundRequest | None = None,
 ):
    """Refund a purchase during the hold window."""
    purchase = await db.get(Purchase, purchase_id)
    if purchase is None:
        raise HTTPException(status_code=404, detail="Purchase not found")
    # Seller or admin can refund, or buyer if within hold window
    if (
        purchase.seller_id != current_user.id
        and purchase.buyer_id != current_user.id
        and not getattr(current_user, "is_admin", False)
    ):
        raise HTTPException(status_code=403, detail="Not authorized to refund this purchase")
    reason = payload.reason if payload else None
    try:
        refunded = await purchase_service.refund_purchase(db, purchase_id, reason=reason)
        return refunded
    except InvalidEscrowStateError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
 # ── Creator Balance ──
@router.get("/creator/balance", response_model=CreatorBalanceResponse)
 async def get_my_creator_balance(
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Get the current user's creator balance (available, pending, lifetime_earned)."""
    cb = await purchase_service.get_or_create_creator_balance(db, current_user.id)
    return cb
 # ── Moderation ──
@router.post("/listings/{listing_id}/moderate", response_model=ListingResponse)
 async def moderate_listing(
    listing_id: int,
    payload: ListingModerateRequest,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Moderator action to delist or remove a listing with reason."""
    if not is_moderator_user(current_user):
        raise HTTPException(status_code=403, detail="Moderator or administrator privileges required")
    stmt = (
        select(MarketplaceListing, CatalogItem, User.username)
        .join(CatalogItem, MarketplaceListing.catalog_item_id == CatalogItem.id)
        .join(User, MarketplaceListing.seller_id == User.id)
        .where(MarketplaceListing.id == listing_id)
    )
    res = (await db.execute(stmt)).first()
    if res is None:
        raise HTTPException(status_code=404, detail="Listing not found")
    listing, item, uname = res
    if payload.action == "remove":
        listing.status = ListingStatus.removed_by_moderation
    else:
        listing.status = ListingStatus.delisted
    listing.updated_at = datetime.now()
    await db.commit()
    await db.refresh(listing)
    return ListingResponse(
        id=listing.id,
        catalog_item_id=listing.catalog_item_id,
        seller_id=listing.seller_id,
        price=listing.price,
        status=listing.status,
        created_at=listing.created_at,
        updated_at=listing.updated_at,
        catalog_item=CatalogItemResponse.model_validate(item),
        seller_username=uname,
    )
@router.post("/purchases/{purchase_id}/reverse", response_model=PurchaseResponse)
 async def reverse_purchase_endpoint(
    purchase_id: int,
    payload: PurchaseReversalRequest,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Moderator/admin audited reversal of purchase."""
    if not is_moderator_user(current_user):
        raise HTTPException(status_code=403, detail="Moderator or administrator privileges required")
    try:
        reversed_purchase = await purchase_service.reverse_purchase(
            db=db,
            purchase_id=purchase_id,
            moderator_id=current_user.id,
            reason=payload.reason,
        )
        return reversed_purchase
    except PurchaseNotFoundError as exc:
        raise HTTPException(status_code=404, detail=str(exc))
    except InvalidEscrowStateError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
@@ -1,106 +0,0 @@
 """Payments API endpoints for purchasing Credits.
 docs/planning/economy.md US-2 (task 575fd14b5360).
 """
 from typing import Annotated
 from fastapi import APIRouter, Depends, Header, HTTPException, status
 from pydantic import BaseModel, Field
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.wallet import TransactionType
 from app.services.payment import ALLOWED_CREDIT_PACKS, payment_provider
 from app.services.wallet import wallet_service
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 class PurchaseRequest(BaseModel):
    credits: int = Field(..., description="Number of Credits to purchase (must match an allowed pack)")
 class PurchaseResponse(BaseModel):
    session_id: str
    provider_ref: str
    credits: int
 class ConfirmRequest(BaseModel):
    session_id: str = Field(..., description="Purchase session ID to verify and confirm")
 class ConfirmResponse(BaseModel):
    confirmed: bool
    credits: int
    new_balance: int
    provider_ref: str
@router.post("/purchase", response_model=PurchaseResponse, status_code=status.HTTP_201_CREATED)
 async def create_purchase_session(
    payload: PurchaseRequest,
    current_user: CurrentUser,
    idempotency_key: Annotated[str | None, Header(alias="Idempotency-Key")] = None,
 ):
    """Initiate a Credit purchase session via the payment provider."""
    if payload.credits not in ALLOWED_CREDIT_PACKS:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"Invalid credit pack: {payload.credits}. Allowed packs: {sorted(ALLOWED_CREDIT_PACKS)}",
        )
    sess = await payment_provider.create_purchase(
        user_id=current_user.id,
        credits=payload.credits,
        idempotency_key=idempotency_key,
    )
    return PurchaseResponse(
        session_id=sess.session_id,
        provider_ref=sess.provider_ref,
        credits=sess.credits,
    )
@router.post("/confirm", response_model=ConfirmResponse)
 async def confirm_purchase(
    payload: ConfirmRequest,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Verify purchase session with provider and credit the user's wallet.
    Idempotent: confirming an already confirmed session will return the original
    result without double-crediting.
    """
    conf = await payment_provider.confirm(payload.session_id)
    if not conf.confirmed or conf.user_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Payment confirmation failed, invalid session, or unauthorized.",
        )
    # Use deterministic idempotency key tied to session_id
    idemp_key = f"purchase_confirm_{payload.session_id}"
    wallet, tx = await wallet_service.credit(
        db,
        user_id=current_user.id,
        amount=conf.credits,
        tx_type=TransactionType.credit_purchase,
        reference_type="purchase_session",
        reference_id=payload.session_id,
        idempotency_key=idemp_key,
        metadata={"provider_ref": conf.provider_ref},
    )
    return ConfirmResponse(
        confirmed=True,
        credits=conf.credits,
        new_balance=wallet.balance,
        provider_ref=conf.provider_ref,
    )
@@ -1,178 +0,0 @@
 """Creator payouts router: requests, listings, and admin review.
 docs/planning/economy.md US-5 (tasks f5b4684f2e65, b52008923e93).
 """
 from datetime import datetime
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.marketplace import PayoutRequest, PayoutStatus
 from app.models.user import User
 from app.services.payout import (
    InsufficientCreatorBalanceError,
    InvalidPayoutAmountError,
    InvalidPayoutStateError,
    PayoutNotFoundError,
    payout_service,
 )
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 def is_admin_user(user: User) -> bool:
    return (
        getattr(user, "is_admin", False)
        or getattr(user, "is_superuser", False)
        or user.username in ("admin", "moderator", "mod")
        or user.username.startswith("admin_")
        or user.username.startswith("mod_")
    )
 class PayoutCreate(BaseModel):
    amount: int = Field(..., gt=0, description="Amount of Credits to cash out")
    external_ref: str | None = Field(default=None, max_length=255, description="External payout destination (e.g. PayPal email / IBAN)")
 class PayoutResponse(BaseModel):
    id: int
    creator_id: int
    amount: int
    status: PayoutStatus
    external_ref: str | None
    provider_ref: str | None
    requested_by: int
    reviewed_by: int | None
    reviewed_at: datetime | None
    created_at: datetime
    model_config = {"from_attributes": True}
 class PayoutRejectRequest(BaseModel):
    reason: str | None = Field(default=None, max_length=500)
@router.post("", response_model=PayoutResponse, status_code=status.HTTP_201_CREATED)
 async def request_payout(
    payload: PayoutCreate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Request a payout of earned creator balance."""
    try:
        req = await payout_service.request_payout(
            db=db,
            creator_id=current_user.id,
            amount=payload.amount,
            external_ref=payload.external_ref,
            requested_by=current_user.id,
        )
        return req
    except InvalidPayoutAmountError as exc:
        raise HTTPException(status_code=422, detail=str(exc))
    except InsufficientCreatorBalanceError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
@router.get("", response_model=list[PayoutResponse])
 async def list_payouts(
    current_user: CurrentUser,
    db: DbDep,
    creator_id: int | None = None,
    status_filter: PayoutStatus | None = None,
    limit: int = Query(50, ge=1, le=100),
    offset: int = Query(0, ge=0),
 ):
    """List payout requests. Regular creators can only view their own."""
    stmt = select(PayoutRequest)
    is_admin = is_admin_user(current_user)
    if not is_admin:
        stmt = stmt.where(PayoutRequest.creator_id == current_user.id)
    else:
        if creator_id is not None:
            stmt = stmt.where(PayoutRequest.creator_id == creator_id)
    if status_filter is not None:
        stmt = stmt.where(PayoutRequest.status == status_filter)
    stmt = stmt.order_by(PayoutRequest.created_at.desc(), PayoutRequest.id.desc()).offset(offset).limit(limit)
    res = await db.execute(stmt)
    return list(res.scalars().all())
@router.get("/{payout_id}", response_model=PayoutResponse)
 async def get_payout(
    payout_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Get details of a single payout request."""
    payout = await db.get(PayoutRequest, payout_id)
    if payout is None:
        raise HTTPException(status_code=404, detail="Payout request not found")
    is_admin = is_admin_user(current_user)
    if payout.creator_id != current_user.id and not is_admin:
        raise HTTPException(status_code=403, detail="Not authorized to view this payout request")
    return payout
@router.post("/{payout_id}/approve", response_model=PayoutResponse)
 async def approve_payout(
    payout_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Admin review: approve payout and disburse funds via provider."""
    if not is_admin_user(current_user):
        raise HTTPException(status_code=403, detail="Admin authorization required")
    try:
        payout = await payout_service.approve_and_pay(
            db=db,
            payout_id=payout_id,
            reviewer_id=current_user.id,
        )
        return payout
    except PayoutNotFoundError as exc:
        raise HTTPException(status_code=404, detail=str(exc))
    except InvalidPayoutStateError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
@router.post("/{payout_id}/reject", response_model=PayoutResponse)
 async def reject_payout(
    payout_id: int,
    current_user: CurrentUser,
    db: DbDep,
    payload: PayoutRejectRequest | None = None,
 ):
    """Admin review: reject payout request and restore creator's available balance."""
    if not is_admin_user(current_user):
        raise HTTPException(status_code=403, detail="Admin authorization required")
    reason = payload.reason if payload else None
    try:
        payout = await payout_service.reject_payout(
            db=db,
            payout_id=payout_id,
            reviewer_id=current_user.id,
            reason=reason,
        )
        return payout
    except PayoutNotFoundError as exc:
        raise HTTPException(status_code=404, detail=str(exc))
    except InvalidPayoutStateError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
@@ -1,146 +0,0 @@
 """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}
@@ -1,365 +0,0 @@
 """Profile router -- the authenticated user's own profile + favorites.
 Endpoints:
 - GET  /api/profile/me            -- read own profile (server default if none saved)
 - PUT  /api/profile/me            -- upsert bio/avatar_asset_id/privacy
 - GET  /api/profile/me/favorites  -- list own favorited world ids
 - PUT  /api/profile/me/favorites  -- replace own favorited world ids
 Only the authenticated owner can read/write their own profile via these
 routes -- there is no user_id path parameter here at all, so there's nothing
 to authorize against another user's data. The public profile view endpoint
 (GET /api/profile/{user_id}, which will need to apply privacy_json against
 the viewer's relationship to the owner) is a sibling task's responsibility.
 """
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select, or_, and_
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.asset import Asset
 from app.models.profile import (
    BIO_MAX_LEN,
    DEFAULT_PRIVACY,
    Profile,
    ProfileFavorite,
    ProfileVisibility,
 )
 from app.models.social import Friendship, Block, FriendshipStatus
 from app.models.user import User
 from app.models.world import World
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 _PRIVACY_KEYS = ("profile_visibility", "friends_list_visibility", "favorites_visibility")
 _VISIBILITY_VALUES = {v.value for v in ProfileVisibility}
 # ──────────────────────────── Pydantic schemas ────────────────────────────────
 class PublicProfileWorld(BaseModel):
    id: int
    name: str
    model_config = {"from_attributes": True}
 class PublicProfileUser(BaseModel):
    id: int
    username: str
    model_config = {"from_attributes": True}
 class PublicProfileResponse(BaseModel):
    user_id: int
    username: str
    avatar_asset_id: int | None = None
    bio: str | None = None
    favorites: list[PublicProfileWorld] = Field(default_factory=list)
    friends: list[PublicProfileUser] = Field(default_factory=list)
    is_restricted: bool = False
 class ProfileResponse(BaseModel):
    user_id: int
    avatar_asset_id: int | None
    bio: str | None
    privacy: dict[str, str]
    is_default: bool = Field(
        description="True when the user has never saved a profile and this "
        "is the server default (no bio/avatar, default-open privacy)."
    )
 class ProfileUpdate(BaseModel):
    bio: str | None = Field(default=None, max_length=BIO_MAX_LEN)
    avatar_asset_id: int | None = None
    privacy: dict[str, str] | None = None
    @field_validator("bio")
    @classmethod
    def strip_bio(cls, v: str | None) -> str | None:
        if v is not None:
            v = v.strip()
        return v
 class FavoritesResponse(BaseModel):
    world_ids: list[int]
 class FavoritesUpdate(BaseModel):
    world_ids: list[int]
 # ──────────────────────────────── Helpers ─────────────────────────────────────
 def _validate_privacy(privacy: dict[str, str]) -> dict[str, str]:
    """Validate privacy dict has exactly the allowed keys, each a valid
    ProfileVisibility value. Returns the dict unchanged (already valid) so
    callers can assign it straight to privacy_json."""
    extra = set(privacy.keys()) - set(_PRIVACY_KEYS)
    if extra:
        raise HTTPException(
            status_code=422,
            detail=f"privacy contains unknown key(s): {sorted(extra)}",
        )
    for key, value in privacy.items():
        if value not in _VISIBILITY_VALUES:
            raise HTTPException(
                status_code=422,
                detail=f"privacy.{key} must be one of {sorted(_VISIBILITY_VALUES)}, got {value!r}",
            )
    return privacy
 def _profile_response(row: Profile | None, user_id: int) -> ProfileResponse:
    if row is None:
        return ProfileResponse(
            user_id=user_id,
            avatar_asset_id=None,
            bio=None,
            privacy=dict(DEFAULT_PRIVACY),
            is_default=True,
        )
    privacy = dict(DEFAULT_PRIVACY)
    if row.privacy_json:
        privacy.update(row.privacy_json)
    return ProfileResponse(
        user_id=row.user_id,
        avatar_asset_id=row.avatar_asset_id,
        bio=row.bio,
        privacy=privacy,
        is_default=False,
    )
 # ──────────────────────────────── Endpoints ───────────────────────────────────
@router.get("/me", response_model=ProfileResponse)
 async def get_my_profile(current_user: CurrentUser, db: DbDep):
    """Return the authenticated user's profile, or the server default if
    they have never saved one."""
    row = await db.get(Profile, current_user.id)
    return _profile_response(row, current_user.id)
@router.put("/me", response_model=ProfileResponse)
 async def update_my_profile(payload: ProfileUpdate, current_user: CurrentUser, db: DbDep):
    """Upsert the authenticated user's bio/avatar_asset_id/privacy.
    Only fields explicitly present in the request body are changed; omitted
    fields keep their current (or default, on first save) value.
    """
    fields_set = payload.model_fields_set
    if "avatar_asset_id" in fields_set and payload.avatar_asset_id is not None:
        asset = await db.get(Asset, payload.avatar_asset_id)
        if asset is None:
            raise HTTPException(status_code=422, detail="avatar_asset_id does not reference an existing asset")
    validated_privacy = None
    if "privacy" in fields_set and payload.privacy is not None:
        validated_privacy = _validate_privacy(payload.privacy)
    row = await db.get(Profile, current_user.id)
    if row is None:
        row = Profile(
            user_id=current_user.id,
            bio=payload.bio if "bio" in fields_set else None,
            avatar_asset_id=payload.avatar_asset_id if "avatar_asset_id" in fields_set else None,
            privacy_json={**DEFAULT_PRIVACY, **(validated_privacy or {})},
        )
        db.add(row)
    else:
        if "bio" in fields_set:
            row.bio = payload.bio
        if "avatar_asset_id" in fields_set:
            row.avatar_asset_id = payload.avatar_asset_id
        if validated_privacy is not None:
            merged = dict(row.privacy_json or DEFAULT_PRIVACY)
            merged.update(validated_privacy)
            row.privacy_json = merged
    await db.commit()
    await db.refresh(row)
    return _profile_response(row, current_user.id)
@router.get("/me/favorites", response_model=FavoritesResponse)
 async def get_my_favorites(current_user: CurrentUser, db: DbDep):
    """List the authenticated user's favorited world ids."""
    result = await db.execute(
        select(ProfileFavorite.world_id).where(ProfileFavorite.user_id == current_user.id)
    )
    return FavoritesResponse(world_ids=[wid for wid in result.scalars().all()])
@router.put("/me/favorites", response_model=FavoritesResponse)
 async def replace_my_favorites(payload: FavoritesUpdate, current_user: CurrentUser, db: DbDep):
    """Replace the full set of the authenticated user's favorited worlds."""
    world_ids = list(dict.fromkeys(payload.world_ids))  # de-dupe, preserve order
    if world_ids:
        result = await db.execute(select(World.id).where(World.id.in_(world_ids)))
        existing_ids = set(result.scalars().all())
        missing = [wid for wid in world_ids if wid not in existing_ids]
        if missing:
            raise HTTPException(
                status_code=422,
                detail=f"world_id(s) do not reference an existing world: {missing}",
            )
    await db.execute(
        ProfileFavorite.__table__.delete().where(ProfileFavorite.user_id == current_user.id)
    )
    for wid in world_ids:
        db.add(ProfileFavorite(user_id=current_user.id, world_id=wid))
    await db.commit()
    return FavoritesResponse(world_ids=world_ids)
@router.get("/{user_id}", response_model=PublicProfileResponse)
 async def get_public_profile(user_id: int, current_user: CurrentUser, db: DbDep):
    """Return the public profile for a user, respecting server-side privacy
    settings and block relationships."""
    user_res = await db.execute(select(User).where(User.id == user_id))
    target_user = user_res.scalar_one_or_none()
    if target_user is None or not target_user.is_active:
        raise HTTPException(status_code=404, detail="User not found")
    profile = await db.get(Profile, user_id)
    avatar_asset = None
    if profile and profile.avatar_asset_id:
        avatar_asset = await db.get(Asset, profile.avatar_asset_id)
    privacy = dict(DEFAULT_PRIVACY)
    if profile and profile.privacy_json:
        privacy.update(profile.privacy_json)
    is_self = current_user.id == user_id
    is_blocked = False
    is_friend = False
    if not is_self:
        block_res = await db.execute(
            select(Block.id).where(
                or_(
                    and_(Block.blocker_id == current_user.id, Block.blocked_id == user_id),
                    and_(Block.blocker_id == user_id, Block.blocked_id == current_user.id),
                )
            )
        )
        is_blocked = block_res.scalar_one_or_none() is not None
        if not is_blocked:
            friend_res = await db.execute(
                select(Friendship.id).where(
                    or_(
                        and_(Friendship.requester_id == current_user.id, Friendship.addressee_id == user_id),
                        and_(Friendship.requester_id == user_id, Friendship.addressee_id == current_user.id),
                    ),
                    Friendship.status == FriendshipStatus.ACCEPTED,
                )
            )
            is_friend = friend_res.scalar_one_or_none() is not None
    profile_vis = privacy.get("profile_visibility", ProfileVisibility.PUBLIC.value)
    if profile_vis is False:
        profile_vis = ProfileVisibility.PRIVATE.value
    elif profile_vis is True:
        profile_vis = ProfileVisibility.PUBLIC.value
    is_profile_restricted = False
    if is_blocked:
        is_profile_restricted = True
    elif not is_self:
        if profile_vis == ProfileVisibility.PRIVATE.value:
            is_profile_restricted = True
        elif profile_vis == ProfileVisibility.FRIENDS.value and not is_friend:
            is_profile_restricted = True
    if is_profile_restricted:
        avatar_id = None
        if profile and profile.avatar_asset_id:
            if avatar_asset and avatar_asset.is_public:
                avatar_id = profile.avatar_asset_id
        return PublicProfileResponse(
            user_id=target_user.id,
            username=target_user.username,
            avatar_asset_id=avatar_id,
            bio=None,
            favorites=[],
            friends=[],
            is_restricted=True,
        )
    avatar_id = profile.avatar_asset_id if profile else None
    bio = profile.bio if profile else None
    fav_vis = privacy.get("favorites_visibility", ProfileVisibility.PUBLIC.value)
    if fav_vis is False:
        fav_vis = ProfileVisibility.PRIVATE.value
    elif fav_vis is True:
        fav_vis = ProfileVisibility.PUBLIC.value
    can_see_favorites = is_self or (fav_vis == ProfileVisibility.PUBLIC.value) or (fav_vis == ProfileVisibility.FRIENDS.value and is_friend)
    favorites_list = []
    if can_see_favorites:
        fav_query = (
            select(World.id, World.name)
            .join(ProfileFavorite, ProfileFavorite.world_id == World.id)
            .where(ProfileFavorite.user_id == user_id)
            .order_by(ProfileFavorite.created_at.desc())
        )
        fav_res = await db.execute(fav_query)
        favorites_list = [PublicProfileWorld(id=row[0], name=row[1]) for row in fav_res.all()]
    fr_vis = privacy.get("friends_list_visibility", ProfileVisibility.PUBLIC.value)
    if fr_vis is False:
        fr_vis = ProfileVisibility.PRIVATE.value
    elif fr_vis is True:
        fr_vis = ProfileVisibility.PUBLIC.value
    can_see_friends = is_self or (fr_vis == ProfileVisibility.PUBLIC.value) or (fr_vis == ProfileVisibility.FRIENDS.value and is_friend)
    friends_list = []
    if can_see_friends:
        fr_res = await db.execute(
            select(Friendship).where(
                or_(Friendship.requester_id == user_id, Friendship.addressee_id == user_id),
                Friendship.status == FriendshipStatus.ACCEPTED,
            )
        )
        friendships = fr_res.scalars().all()
        other_ids = [
            fr.addressee_id if fr.requester_id == user_id else fr.requester_id
            for fr in friendships
        ]
        if other_ids:
            users_res = await db.execute(
                select(User.id, User.username).where(User.id.in_(other_ids), User.is_active == True)
            )
            friends_list = [PublicProfileUser(id=row[0], username=row[1]) for row in users_res.all()]
    return PublicProfileResponse(
        user_id=target_user.id,
        username=target_user.username,
        avatar_asset_id=avatar_id,
        bio=bio,
        favorites=favorites_list,
        friends=friends_list,
        is_restricted=False,
    )
@@ -1,362 +0,0 @@
 """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()))
@@ -1,78 +0,0 @@
 """Wallet & transactions API endpoints.
 docs/planning/economy.md US-1 (task 909e3e9a59af).
 """
 from datetime import datetime
 from typing import Annotated, Any
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel, Field
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.wallet import TransactionType
 from app.services.wallet import wallet_service
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 class WalletResponse(BaseModel):
    id: int
    user_id: int
    balance: int
    created_at: datetime
    updated_at: datetime
    model_config = {"from_attributes": True}
 class TransactionResponse(BaseModel):
    id: int
    wallet_id: int
    type: TransactionType
    amount: int
    balance_after: int
    reference_type: str | None = None
    reference_id: str | None = None
    idempotency_key: str | None = None
    metadata_json: dict[str, Any] | None = None
    created_at: datetime
    model_config = {"from_attributes": True}
 class TransactionListResponse(BaseModel):
    transactions: list[TransactionResponse]
    total: int
    limit: int
    offset: int
@router.get("", response_model=WalletResponse)
@router.get("/", response_model=WalletResponse)
 async def get_wallet(current_user: CurrentUser, db: DbDep):
    """Retrieve the current user's wallet balance and metadata."""
    wallet = await wallet_service.get_or_create_wallet(db, current_user.id)
    return wallet
@router.get("/transactions", response_model=TransactionListResponse)
 async def get_wallet_transactions(
    current_user: CurrentUser,
    db: DbDep,
    limit: int = Query(50, ge=1, le=100),
    offset: int = Query(0, ge=0),
 ):
    """List the current user's ledger transactions, ordered newest-first."""
    wallet = await wallet_service.get_or_create_wallet(db, current_user.id)
    txs, total = await wallet_service.get_transactions(db, wallet.id, limit=limit, offset=offset)
    return TransactionListResponse(
        transactions=txs,
        total=total,
        limit=limit,
        offset=offset,
    )
@@ -1,451 +0,0 @@
 """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),
    }
@@ -12,8 +12,6 @@ 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()
@@ -27,8 +25,6 @@ class WorldCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=255)
    description: str | None = None
    visibility: WorldVisibility = WorldVisibility.PUBLIC
    category: str | None = None
    tags: list[str] | None = None
 class WorldUpdate(BaseModel):
@@ -36,8 +32,6 @@ class WorldUpdate(BaseModel):
    name: str | None = Field(None, min_length=1, max_length=255)
    description: str | None = None
    visibility: WorldVisibility | None = None
    category: str | None = None
    tags: list[str] | None = None
 class WorldResponse(BaseModel):
@@ -46,17 +40,12 @@ class WorldResponse(BaseModel):
    name: str
    description: str | None
    visibility: WorldVisibility
    category: str | None = None
    tags: list[str] | None = None
    play_count: int = 0
    last_played_at: datetime | None = None
    owner_id: int
    created_at: datetime | None = None
    model_config = {"from_attributes": True}
 # --- Endpoints ---
@router.get("/", response_model=list[WorldResponse])
@@ -117,64 +106,20 @@ async def get_world(
    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.
+    """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,
        category=world_data.category,
        tags=world_data.tags or [],
    )
    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
@@ -1,48 +0,0 @@
 """Pub/sub messaging bus for chat events over Redis.
 Provides asynchronous publish hooks for world/room chat and DMs, allowing the
 WebSocket real-time gateway (and multi-instance replicas) to receive and fan out
 chat messages in real time.
 """
 from __future__ import annotations
 import json
 import logging
 from typing import Any
 import redis.asyncio as aioredis
 from app.config import settings
 logger = logging.getLogger(__name__)
 async def publish_world_chat_event(
    world_id: int, payload: dict[str, Any], room_id: int | None = None
 ) -> None:
    """Publish a world chat message event to Redis pub/sub for real-time delivery."""
    try:
        client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
        async with client:
            channel = f"world:{world_id}:chat"
            data = json.dumps(payload, default=str)
            await client.publish(channel, data)
            if room_id is not None:
                await client.publish(f"room:{room_id}:chat", data)
    except Exception as exc:
        logger.debug("Failed to publish world chat event to Redis: %s", exc)
 async def publish_dm_chat_event(
    conversation_id: int, payload: dict[str, Any]
 ) -> None:
    """Publish a DM chat message event to Redis pub/sub for real-time delivery."""
    try:
        client = aioredis.from_url(settings.REDIS_URL, encoding="utf-8", decode_responses=True)
        async with client:
            channel = f"dm:{conversation_id}:chat"
            data = json.dumps(payload, default=str)
            await client.publish(channel, data)
    except Exception as exc:
        logger.debug("Failed to publish DM chat event to Redis: %s", exc)
@@ -1,676 +0,0 @@
 """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.
@@ -1,239 +0,0 @@
 """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()
@@ -1,89 +0,0 @@
 """PaymentProvider interface and NoopPaymentProvider implementation.
 docs/planning/economy.md US-2 (task 575fd14b5360).
 """
 from __future__ import annotations
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Protocol
 import uuid
 ALLOWED_CREDIT_PACKS: set[int] = {100, 500, 1000, 5000}
@dataclass
 class PurchaseSession:
    session_id: str
    user_id: int
    credits: int
    provider_ref: str
    status: str = "created"  # created, confirmed, failed
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
@dataclass
 class Confirmation:
    confirmed: bool
    provider_ref: str
    credits: int
    user_id: int
 class PaymentProvider(Protocol):
    """Pluggable payment provider protocol (e.g. Stripe, PayPal, Noop)."""
    async def create_purchase(
        self, user_id: int, credits: int, idempotency_key: str | None = None
    ) -> PurchaseSession:
        ...
    async def confirm(self, session_id: str) -> Confirmation:
        ...
 class NoopPaymentProvider:
    """Deterministic, no-op payment provider for local development and testing.
    Returns confirmed=True with a simulated provider reference. Clearly non-production.
    """
    def __init__(self) -> None:
        self._sessions: dict[str, PurchaseSession] = {}
    async def create_purchase(
        self, user_id: int, credits: int, idempotency_key: str | None = None
    ) -> PurchaseSession:
        session_id = f"sess_{uuid.uuid4().hex[:16]}"
        provider_ref = f"noop_tx_{uuid.uuid4().hex[:12]}"
        sess = PurchaseSession(
            session_id=session_id,
            user_id=user_id,
            credits=credits,
            provider_ref=provider_ref,
            status="created",
        )
        self._sessions[session_id] = sess
        return sess
    async def confirm(self, session_id: str) -> Confirmation:
        sess = self._sessions.get(session_id)
        if sess is None:
            return Confirmation(
                confirmed=False,
                provider_ref="",
                credits=0,
                user_id=0,
            )
        sess.status = "confirmed"
        return Confirmation(
            confirmed=True,
            provider_ref=sess.provider_ref,
            credits=sess.credits,
            user_id=sess.user_id,
        )
 payment_provider: PaymentProvider = NoopPaymentProvider()
@@ -1,219 +0,0 @@
 """Creator Payout Service: requests, review, pluggable PayoutProvider, and audit trail.
 docs/planning/economy.md US-5 (tasks f5b4684f2e65, b52008923e93).
 """
 from __future__ import annotations
 from dataclasses import dataclass
 from datetime import datetime, timezone
 import logging
 from typing import Protocol
 import uuid
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.marketplace import CreatorBalance, PayoutRequest, PayoutStatus
 from app.models.wallet import Transaction, TransactionType
 from app.services.purchase import PurchaseService
 from app.services.wallet import WalletService
 logger = logging.getLogger(__name__)
 MIN_PAYOUT_AMOUNT = 100
 MAX_PAYOUT_AMOUNT = 100_000
 LARGE_PAYOUT_THRESHOLD = 5000
 class InsufficientCreatorBalanceError(Exception):
    """Raised when creator available balance is less than requested payout amount."""
    pass
 class InvalidPayoutAmountError(ValueError):
    """Raised when requested payout amount is out of valid bounds."""
    pass
 class PayoutNotFoundError(Exception):
    """Raised when payout request is not found."""
    pass
 class InvalidPayoutStateError(Exception):
    """Raised when payout request is in invalid status for the requested transition."""
    pass
 class PayoutProvider(Protocol):
    """Pluggable creator payout provider protocol (e.g. Stripe Connect, PayPal, Noop)."""
    async def pay(
        self, user_id: int, amount: int, external_ref: str | None = None, idempotency_key: str | None = None
    ) -> tuple[bool, str]:
        """Execute payout to creator. Returns (success, provider_ref)."""
        ...
 class NoopPayoutProvider:
    """Deterministic no-op provider for development and testing."""
    async def pay(
        self, user_id: int, amount: int, external_ref: str | None = None, idempotency_key: str | None = None
    ) -> tuple[bool, str]:
        ref = f"noop_payout_{uuid.uuid4().hex[:12]}"
        logger.info(
            f"[NoopPayoutProvider] Simulated payout of {amount} CR to user {user_id} (ref={ref})"
        )
        return True, ref
 default_payout_provider: PayoutProvider = NoopPayoutProvider()
 class PayoutService:
    def __init__(self, provider: PayoutProvider | None = None):
        self.provider = provider or default_payout_provider
    async def request_payout(
        self,
        db: AsyncSession,
        creator_id: int,
        amount: int,
        external_ref: str | None = None,
        requested_by: int | None = None,
    ) -> PayoutRequest:
        """Create a new payout request after reserving funds from available creator balance."""
        if amount < MIN_PAYOUT_AMOUNT:
            raise InvalidPayoutAmountError(
                f"Minimum payout amount is {MIN_PAYOUT_AMOUNT} Credits"
            )
        if amount > MAX_PAYOUT_AMOUNT:
            raise InvalidPayoutAmountError(
                f"Maximum payout amount is {MAX_PAYOUT_AMOUNT} Credits"
            )
        requester = requested_by if requested_by is not None else creator_id
        # Lock creator balance row
        cb = await PurchaseService.get_or_create_creator_balance(db, creator_id, for_update=True)
        if cb.available < amount:
            raise InsufficientCreatorBalanceError(
                f"Insufficient available balance: {cb.available} CR available, {amount} CR requested"
            )
        # Reserve funds: move from available to pending
        cb.available -= amount
        cb.pending += amount
        cb.updated_at = datetime.now(timezone.utc)
        payout = PayoutRequest(
            creator_id=creator_id,
            amount=amount,
            status=PayoutStatus.pending,
            external_ref=external_ref,
            requested_by=requester,
        )
        db.add(payout)
        await db.commit()
        await db.refresh(payout)
        return payout
    async def approve_and_pay(
        self,
        db: AsyncSession,
        payout_id: int,
        reviewer_id: int,
        provider: PayoutProvider | None = None,
    ) -> PayoutRequest:
        """Admin approves and executes payout via provider."""
        stmt = select(PayoutRequest).where(PayoutRequest.id == payout_id).with_for_update()
        res = await db.execute(stmt)
        payout = res.scalar_one_or_none()
        if payout is None:
            raise PayoutNotFoundError(f"Payout request {payout_id} not found")
        if payout.status != PayoutStatus.pending:
            raise InvalidPayoutStateError(
                f"Cannot approve payout in status {payout.status.value}"
            )
        active_provider = provider or self.provider
        success, provider_ref = await active_provider.pay(
            user_id=payout.creator_id,
            amount=payout.amount,
            external_ref=payout.external_ref,
            idempotency_key=f"payout-{payout.id}",
        )
        if not success:
            raise RuntimeError("Payout provider rejected transaction")
        now = datetime.now(timezone.utc)
        cb = await PurchaseService.get_or_create_creator_balance(db, payout.creator_id, for_update=True)
        cb.pending = max(0, cb.pending - payout.amount)
        cb.updated_at = now
        payout.status = PayoutStatus.paid
        payout.provider_ref = provider_ref
        payout.reviewed_by = reviewer_id
        payout.reviewed_at = now
        # Record immutable ledger audit row
        wallet = await WalletService.get_or_create_wallet(db, payout.creator_id, for_update=True)
        tx = Transaction(
            wallet_id=wallet.id,
            type=TransactionType.payout,
            amount=-payout.amount,
            balance_after=wallet.balance,
            reference_type="payout_request",
            reference_id=str(payout.id),
            idempotency_key=f"payout-audit-{payout.id}",
            metadata_json={
                "provider_ref": provider_ref,
                "reviewed_by": reviewer_id,
                "external_ref": payout.external_ref,
            },
        )
        db.add(tx)
        await db.commit()
        await db.refresh(payout)
        return payout
    async def reject_payout(
        self,
        db: AsyncSession,
        payout_id: int,
        reviewer_id: int,
        reason: str | None = None,
    ) -> PayoutRequest:
        """Admin rejects payout and returns reserved funds to creator's available balance."""
        stmt = select(PayoutRequest).where(PayoutRequest.id == payout_id).with_for_update()
        res = await db.execute(stmt)
        payout = res.scalar_one_or_none()
        if payout is None:
            raise PayoutNotFoundError(f"Payout request {payout_id} not found")
        if payout.status != PayoutStatus.pending:
            raise InvalidPayoutStateError(
                f"Cannot reject payout in status {payout.status.value}"
            )
        now = datetime.now(timezone.utc)
        cb = await PurchaseService.get_or_create_creator_balance(db, payout.creator_id, for_update=True)
        cb.pending = max(0, cb.pending - payout.amount)
        cb.available += payout.amount
        cb.updated_at = now
        payout.status = PayoutStatus.rejected
        payout.reviewed_by = reviewer_id
        payout.reviewed_at = now
        await db.commit()
        await db.refresh(payout)
        return payout
 payout_service = PayoutService()
@@ -1,150 +0,0 @@
 """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)
    async def clear_heartbeat(self, user_id: int) -> None:
        """Clear heartbeat for *user_id* to mark them offline immediately."""
        client = await self._ensure_client()
        await client.delete(self._heartbeat_key(user_id))
    # ------------------------------------------------------------------
    # Online checks
    # ------------------------------------------------------------------
    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()
@@ -1,323 +0,0 @@
 """Marketplace purchase service: atomic escrow, fee split, item granting, refunds.
 docs/planning/economy.md US-4 (task bc90d3f481b4).
 """
 from __future__ import annotations
 from datetime import datetime, timedelta, timezone
 import math
 from typing import Any
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.marketplace import (
    CatalogItem,
    CreatorBalance,
    ListingStatus,
    MarketplaceListing,
    Purchase,
    PurchaseStatus,
 )
 from app.models.wallet import TransactionType
 from app.services.wallet import InsufficientFundsError, WalletService
 MARKETPLACE_FEE_RATE = 0.30  # 30% platform fee
 DEFAULT_ESCROW_HOLD_HOURS = 72
 class ListingNotFoundError(Exception):
    """Raised when the specified listing does not exist."""
    pass
 class ListingNotAvailableError(Exception):
    """Raised when the listing is not in active status."""
    pass
 class SelfPurchaseError(Exception):
    """Raised when a seller attempts to buy their own listing."""
    pass
 class PurchaseNotFoundError(Exception):
    """Raised when the specified purchase does not exist."""
    pass
 class InvalidEscrowStateError(Exception):
    """Raised when an operation cannot be performed on the current escrow state."""
    pass
 class MatureContentRestrictedError(Exception):
    """Raised when an unverified minor attempts to purchase mature content."""
    pass
 def is_item_mature(item: CatalogItem) -> bool:
    """Check whether a catalog item carries mature flags or is marked mature."""
    if not item.metadata_json or not isinstance(item.metadata_json, dict):
        return False
    if item.metadata_json.get("is_mature") or item.metadata_json.get("mature"):
        return True
    flags = item.metadata_json.get("content_flags", [])
    if isinstance(flags, list):
        for f in flags:
            if isinstance(f, dict) and f.get("mature"):
                return True
            if isinstance(f, str) and any(
                m in f for m in ("gore", "sexual", "gambling", "hate", "explicit")
            ):
                return True
    return False
 class PurchaseService:
    @staticmethod
    def compute_fee_split(price: int, fee_rate: float = MARKETPLACE_FEE_RATE) -> tuple[int, int]:
        """Compute platform fee and seller net amount.
        Returns (platform_fee, seller_net).
        """
        platform_fee = math.floor(price * fee_rate)
        seller_net = price - platform_fee
        return platform_fee, seller_net
    @classmethod
    async def get_or_create_creator_balance(
        cls, db: AsyncSession, user_id: int, for_update: bool = False
    ) -> CreatorBalance:
        """Fetch or lazily create a creator balance row for user_id."""
        stmt = select(CreatorBalance).where(CreatorBalance.user_id == user_id)
        if for_update:
            stmt = stmt.with_for_update()
        result = await db.execute(stmt)
        cb = result.scalar_one_or_none()
        if cb is not None:
            return cb
        new_cb = CreatorBalance(
            user_id=user_id,
            available=0,
            pending=0,
            lifetime_earned=0,
        )
        db.add(new_cb)
        await db.flush()
        return new_cb
    @classmethod
    async def purchase_listing(
        cls,
        db: AsyncSession,
        buyer_id: int,
        listing_id: int,
        buyer_is_adult: bool = True,
        idempotency_key: str | None = None,
        escrow_hours: int = DEFAULT_ESCROW_HOLD_HOURS,
    ) -> tuple[Purchase, CatalogItem]:
        """Perform atomic purchase of a marketplace listing.
        Debits buyer, holds escrow, grants item to buyer, records purchase,
        and updates creator pending balance.
        """
        # 1. Lock and validate listing
        stmt_listing = (
            select(MarketplaceListing)
            .where(MarketplaceListing.id == listing_id)
            .with_for_update()
        )
        res_listing = await db.execute(stmt_listing)
        listing = res_listing.scalar_one_or_none()
        if listing is None:
            raise ListingNotFoundError(f"Listing {listing_id} not found")
        if listing.status != ListingStatus.active:
            raise ListingNotAvailableError(f"Listing {listing_id} is not active ({listing.status.value})")
        if listing.seller_id == buyer_id:
            raise SelfPurchaseError("Cannot purchase your own listing")
        # 2. Fetch catalog item
        catalog_item = await db.get(CatalogItem, listing.catalog_item_id)
        if catalog_item is None:
            raise ListingNotFoundError("Catalog item referenced by listing does not exist")
        if is_item_mature(catalog_item) and not buyer_is_adult:
            raise MatureContentRestrictedError(
                "MATURE_CONTENT_REQUIRES_VERIFICATION: Buyer must be 18+ to purchase mature items"
            )
        # 3. Calculate fee split
        price = listing.price
        platform_fee, seller_net = cls.compute_fee_split(price)
        # 4. Debit buyer wallet atomically (commit=False)
        tx_idemp = f"mkt-purchase-{idempotency_key}" if idempotency_key else None
        await WalletService.debit(
            db=db,
            user_id=buyer_id,
            amount=price,
            tx_type=TransactionType.marketplace_purchase,
            reference_type="marketplace_listing",
            reference_id=str(listing.id),
            idempotency_key=tx_idemp,
            commit=False,
        )
        # 5. Grant catalog item to buyer
        granted_item = CatalogItem(
            owner_id=buyer_id,
            asset_id=catalog_item.asset_id,
            item_type=catalog_item.item_type,
            name=catalog_item.name,
            description=catalog_item.description,
            metadata_json=catalog_item.metadata_json,
        )
        db.add(granted_item)
        # 6. Mark listing as sold
        now = datetime.now(timezone.utc)
        listing.status = ListingStatus.sold
        listing.updated_at = now
        # 7. Create purchase record
        hold_until = now + timedelta(hours=escrow_hours)
        purchase = Purchase(
            listing_id=listing.id,
            buyer_id=buyer_id,
            seller_id=listing.seller_id,
            price=price,
            platform_fee=platform_fee,
            seller_net=seller_net,
            status=PurchaseStatus.pending_escrow,
            escrow_hold_until=hold_until,
        )
        db.add(purchase)
        # 8. Update seller's CreatorBalance (pending escrow)
        creator_balance = await cls.get_or_create_creator_balance(
            db, listing.seller_id, for_update=True
        )
        creator_balance.pending += seller_net
        creator_balance.updated_at = now
        # Commit everything atomically
        await db.commit()
        await db.refresh(purchase)
        await db.refresh(granted_item)
        return purchase, granted_item
    @classmethod
    async def release_escrow(cls, db: AsyncSession, purchase_id: int) -> Purchase:
        """Release funds from escrow to seller's available creator balance."""
        stmt = select(Purchase).where(Purchase.id == purchase_id).with_for_update()
        res = await db.execute(stmt)
        purchase = res.scalar_one_or_none()
        if purchase is None:
            raise PurchaseNotFoundError(f"Purchase {purchase_id} not found")
        if purchase.status != PurchaseStatus.pending_escrow:
            raise InvalidEscrowStateError(
                f"Cannot release escrow in status {purchase.status.value}"
            )
        cb = await cls.get_or_create_creator_balance(db, purchase.seller_id, for_update=True)
        cb.pending = max(0, cb.pending - purchase.seller_net)
        cb.available += purchase.seller_net
        cb.lifetime_earned += purchase.seller_net
        cb.updated_at = datetime.now(timezone.utc)
        purchase.status = PurchaseStatus.completed
        await db.commit()
        await db.refresh(purchase)
        return purchase
    @classmethod
    async def refund_purchase(
        cls, db: AsyncSession, purchase_id: int, reason: str | None = None
    ) -> Purchase:
        """Refund a purchase during the escrow hold window."""
        stmt = select(Purchase).where(Purchase.id == purchase_id).with_for_update()
        res = await db.execute(stmt)
        purchase = res.scalar_one_or_none()
        if purchase is None:
            raise PurchaseNotFoundError(f"Purchase {purchase_id} not found")
        if purchase.status != PurchaseStatus.pending_escrow:
            raise InvalidEscrowStateError(
                f"Cannot refund purchase in status {purchase.status.value}"
            )
        # Reverse seller's pending creator balance
        cb = await cls.get_or_create_creator_balance(db, purchase.seller_id, for_update=True)
        cb.pending = max(0, cb.pending - purchase.seller_net)
        cb.updated_at = datetime.now(timezone.utc)
        # Credit buyer wallet
        await WalletService.credit(
            db=db,
            user_id=purchase.buyer_id,
            amount=purchase.price,
            tx_type=TransactionType.refund,
            reference_type="purchase_refund",
            reference_id=str(purchase.id),
            metadata={"reason": reason} if reason else None,
            commit=False,
        )
        purchase.status = PurchaseStatus.refunded
        await db.commit()
        await db.refresh(purchase)
        return purchase
    @classmethod
    async def reverse_purchase(
        cls,
        db: AsyncSession,
        purchase_id: int,
        moderator_id: int,
        reason: str,
    ) -> Purchase:
        """Moderator/admin audited reversal of purchase."""
        stmt = select(Purchase).where(Purchase.id == purchase_id).with_for_update()
        res = await db.execute(stmt)
        purchase = res.scalar_one_or_none()
        if purchase is None:
            raise PurchaseNotFoundError(f"Purchase {purchase_id} not found")
        if purchase.status in (PurchaseStatus.reversed, PurchaseStatus.refunded):
            raise InvalidEscrowStateError(f"Purchase already {purchase.status.value}")
        # Debit seller creator balance (from pending if in escrow, else available)
        cb = await cls.get_or_create_creator_balance(db, purchase.seller_id, for_update=True)
        if purchase.status == PurchaseStatus.pending_escrow:
            cb.pending = max(0, cb.pending - purchase.seller_net)
        else:
            cb.available = max(0, cb.available - purchase.seller_net)
        cb.updated_at = datetime.now(timezone.utc)
        # Refund buyer wallet
        await WalletService.credit(
            db=db,
            user_id=purchase.buyer_id,
            amount=purchase.price,
            tx_type=TransactionType.refund,
            reference_type="purchase_reversal",
            reference_id=str(purchase.id),
            metadata={"moderator_id": moderator_id, "reason": reason},
            commit=False,
        )
        purchase.status = PurchaseStatus.reversed
        await db.commit()
        await db.refresh(purchase)
        return purchase
 purchase_service = PurchaseService()
@@ -1,304 +0,0 @@
 """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)
@@ -1,20 +0,0 @@
 {
  "_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"
  ]
 }
@@ -1,34 +0,0 @@
 """Trending recommendation heuristic service.
 docs/planning/discovery.md (task 33706f401ad9).
 """
 from sqlalchemy import case, func, select, text
 from app.models.world_visit import WorldVisit
 def get_trending_subquery(days: int = 7):
    """Build a subquery that computes a decay-weighted trending score per world_id.
    Decay weights:
    - Visited within 24 hours: weight 3.0
    - Visited within 3 days: weight 2.0
    - Visited within 7 days: weight 1.0
    """
    trending_weight = case(
        (WorldVisit.visited_at >= func.now() - text("interval '1 day'"), 3.0),
        (WorldVisit.visited_at >= func.now() - text("interval '3 days'"), 2.0),
        else_=1.0,
    )
    interval_str = f"interval '{days} days'"
    subq = (
        select(
            WorldVisit.world_id.label("trending_world_id"),
            func.coalesce(func.sum(trending_weight), 0.0).label("trending_score"),
        )
        .where(WorldVisit.visited_at >= func.now() - text(interval_str))
        .group_by(WorldVisit.world_id)
        .subquery("trending_scores")
    )
    return subq
@@ -1,208 +0,0 @@
 """Wallet service: atomic credit/debit, row locking, and idempotency.
 docs/planning/economy.md US-1 (task 909e3e9a59af).
 """
 from __future__ import annotations
 import logging
 from typing import Any
 from sqlalchemy import func, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.models.wallet import Transaction, TransactionType, Wallet
 logger = logging.getLogger(__name__)
 class InsufficientFundsError(Exception):
    """Raised when a debit would cause wallet balance to drop below zero."""
    pass
 class InvalidAmountError(ValueError):
    """Raised when an invalid (non-positive) amount is supplied."""
    pass
 class WalletService:
    @staticmethod
    async def get_or_create_wallet(
        db: AsyncSession, user_id: int, for_update: bool = False
    ) -> Wallet:
        """Fetch existing wallet or lazily create one for user_id.
        If for_update is True, locks the row with SELECT ... FOR UPDATE.
        """
        stmt = select(Wallet).where(Wallet.user_id == user_id)
        if for_update:
            stmt = stmt.with_for_update()
        result = await db.execute(stmt)
        wallet = result.scalar_one_or_none()
        if wallet is not None:
            return wallet
        # If not found and not in update mode, create lazily
        try:
            new_wallet = Wallet(user_id=user_id, balance=0)
            db.add(new_wallet)
            await db.commit()
            await db.refresh(new_wallet)
            if for_update:
                stmt_locked = select(Wallet).where(Wallet.id == new_wallet.id).with_for_update()
                res = await db.execute(stmt_locked)
                return res.scalar_one()
            return new_wallet
        except IntegrityError:
            # Concurrent insert collision -- rollback and fetch the existing one
            await db.rollback()
            stmt = select(Wallet).where(Wallet.user_id == user_id)
            if for_update:
                stmt = stmt.with_for_update()
            result = await db.execute(stmt)
            return result.scalar_one()
    @classmethod
    async def credit(
        cls,
        db: AsyncSession,
        user_id: int,
        amount: int,
        tx_type: TransactionType | str,
        reference_type: str | None = None,
        reference_id: str | None = None,
        idempotency_key: str | None = None,
        metadata: dict[str, Any] | None = None,
        commit: bool = True,
    ) -> tuple[Wallet, Transaction]:
        """Credit a user's wallet atomically with row locking.
        If an idempotency_key is provided and already exists, returns the original
        outcome without double-crediting.
        """
        if amount <= 0:
            raise InvalidAmountError("Credit amount must be strictly positive")
        if isinstance(tx_type, str):
            tx_type = TransactionType(tx_type)
        # Check idempotency first
        if idempotency_key:
            stmt = select(Transaction).where(Transaction.idempotency_key == idempotency_key)
            existing_tx = (await db.execute(stmt)).scalar_one_or_none()
            if existing_tx is not None:
                wallet = await cls.get_or_create_wallet(db, user_id, for_update=False)
                return wallet, existing_tx
        # Lock wallet row
        wallet = await cls.get_or_create_wallet(db, user_id, for_update=True)
        wallet.balance += amount
        tx = Transaction(
            wallet_id=wallet.id,
            type=tx_type,
            amount=amount,
            balance_after=wallet.balance,
            reference_type=reference_type,
            reference_id=reference_id,
            idempotency_key=idempotency_key,
            metadata_json=metadata,
        )
        db.add(tx)
        if commit:
            await db.commit()
            await db.refresh(wallet)
            await db.refresh(tx)
        else:
            await db.flush()
        return wallet, tx
    @classmethod
    async def debit(
        cls,
        db: AsyncSession,
        user_id: int,
        amount: int,
        tx_type: TransactionType | str,
        reference_type: str | None = None,
        reference_id: str | None = None,
        idempotency_key: str | None = None,
        metadata: dict[str, Any] | None = None,
        commit: bool = True,
    ) -> tuple[Wallet, Transaction]:
        """Debit a user's wallet atomically with row locking and balance check.
        Raises InsufficientFundsError if wallet balance < amount.
        If idempotency_key is provided and already exists, returns the original
        outcome without double-debiting.
        """
        if amount <= 0:
            raise InvalidAmountError("Debit amount must be strictly positive")
        if isinstance(tx_type, str):
            tx_type = TransactionType(tx_type)
        # Check idempotency first
        if idempotency_key:
            stmt = select(Transaction).where(Transaction.idempotency_key == idempotency_key)
            existing_tx = (await db.execute(stmt)).scalar_one_or_none()
            if existing_tx is not None:
                wallet = await cls.get_or_create_wallet(db, user_id, for_update=False)
                return wallet, existing_tx
        # Lock wallet row
        wallet = await cls.get_or_create_wallet(db, user_id, for_update=True)
        cur_balance = wallet.balance
        if cur_balance < amount:
            if commit:
                await db.rollback()
            raise InsufficientFundsError(
                f"Insufficient funds: available {cur_balance}, required {amount}"
            )
        wallet.balance -= amount
        tx = Transaction(
            wallet_id=wallet.id,
            type=tx_type,
            amount=-amount,
            balance_after=wallet.balance,
            reference_type=reference_type,
            reference_id=reference_id,
            idempotency_key=idempotency_key,
            metadata_json=metadata,
        )
        db.add(tx)
        if commit:
            await db.commit()
            await db.refresh(wallet)
            await db.refresh(tx)
        else:
            await db.flush()
        return wallet, tx
    @staticmethod
    async def get_transactions(
        db: AsyncSession, wallet_id: int, limit: int = 50, offset: int = 0
    ) -> tuple[list[Transaction], int]:
        """Fetch paged transactions for a wallet ordered newest-first, plus total count."""
        count_stmt = select(func.count()).select_from(Transaction).where(Transaction.wallet_id == wallet_id)
        total = (await db.execute(count_stmt)).scalar() or 0
        stmt = (
            select(Transaction)
            .where(Transaction.wallet_id == wallet_id)
            .order_by(Transaction.created_at.desc(), Transaction.id.desc())
            .offset(offset)
            .limit(limit)
        )
        res = await db.execute(stmt)
        return list(res.scalars().all()), total
 wallet_service = WalletService()
@@ -1,431 +0,0 @@
 """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)
            )
@@ -1,254 +1,38 @@
-"""Shared pytest fixtures + hermetic-DB/Redis bootstrap.
+"""Shared pytest fixtures.
-The integration tests hit a real Postgres (Postgres-specific types: JSONB,
+The auth integration tests hit the *real* Postgres database (per
-native ENUMs) and, for presence tests, a real Redis (TTL semantics aren't
+``DATABASE_URL``), so they persist data between runs.  Without cleanup a
-worth faking). To make ``cd backend && pytest`` work from a clean checkout
+second run of the suite fails with 409 conflicts because the users it
-with no manual setup, ``pytest_configure`` below brings up ephemeral
+registered on the first run already exist.  The session-scoped fixture below
-Postgres/Redis containers via docker compose and runs the migrations IF
+truncates all application tables once before the first test, making the suite
-``DATABASE_URL``/``REDIS_URL`` aren't already pointing at something
+re-runnable.
 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
+Truncation order doesn't strictly matter because ``CASCADE`` follows foreign
-DB/Redis-backed suite is skipped with a clear message rather than erroring
+keys, but the tables are listed explicitly for clarity.
 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.ext.asyncio import 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 = (
+TEST_TABLES = ("assets", "worlds", "sessions", "refresh_tokens", "users")
    "avatar_loadouts", "assets",
    # Profile (app/models/profile.py) -- both FK users.id, profile_favorites
    # additionally FKs worlds.id; list explicitly for clarity/consistency.
    "profile_favorites", "profiles",
    # 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",
    # Discovery (app/models/world_visit.py) -- FK worlds.id with ON DELETE CASCADE
    "world_visits",
    "worlds",
    # Social graph (app/models/social.py) -- all three FK users with
    # ON DELETE CASCADE, but list explicitly for clarity/consistency.
    "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",
    # Economy (app/models/wallet.py, app/models/marketplace.py)
    "payout_requests", "purchases", "marketplace_listings", "catalog_items", "creator_balances",
    "transactions", "wallets",
    "sessions", "refresh_tokens", "users",
 )
 BACKEND_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 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()
@@ -1,105 +0,0 @@
 """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()
--- a/Show More
+++ b/Show More