Recovered orphaned WIP before switching to a new task

WIP checkpoint: Review: Address review feedback: Implement chunk streaming system in GDScript
2026-08-18 14:07:32 +00:00 · 2026-08-18 13:57:27 +00:00
67 changed files with 42 additions and 5395 deletions
@@ -1,4 +1,4 @@
-# Godot 4 editor cache/import directory
+# Godot editor cache / generated files
 .godot/
 # Godot export artifacts
@@ -8,6 +8,3 @@ export/
 # OS
 .DS_Store
 Thumbs.db
 # Godot UID files (regenerated from path)
 *.uid
@@ -1,23 +0,0 @@
 # Database (async driver)
 DATABASE_URL=postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
 # Redis
 REDIS_URL=redis://localhost:6379/0
 # JWT / Auth
 ALGORITHM=RS256
 ACCESS_TOKEN_EXPIRE_MINUTES=60
 REFRESH_TOKEN_EXPIRE_DAYS=30
 # Directory where the RSA keypair is loaded/generated at runtime.
 # Defaults to ~/.agp/keys (outside the repo). Keys are never committed to git.
 RSA_KEY_DIR=~/.agp/keys
 # App
 APP_NAME=AGP Backend
 APP_VERSION=0.1.0
 DEBUG=true
 CORS_ORIGINS=http://localhost:8080,http://localhost:3000
 # File uploads
 UPLOAD_DIR=uploads
 MAX_UPLOAD_SIZE_MB=100
@@ -1,4 +0,0 @@
 .env
 __pycache__/
 *.pyc
 .venv/
@@ -1,42 +0,0 @@
 # Alembic configuration file.
 # Run: alembic upgrade head  (to apply migrations)
 # Run: alembic revision --autogenerate -m "description"  (to generate migration)
 [alembic]
 script_location = alembic
 prepend_sys_path = .
 sqlalchemy.url = postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
 [loggers]
 keys = root,sqlalchemy,alembic
 [handlers]
 keys = console
 [formatters]
 keys = generic
 [logger_root]
 level = WARN
 handlers = console
 qualname =
 [logger_sqlalchemy]
 level = WARN
 handlers =
 qualname = sqlalchemy.engine
 [logger_alembic]
 level = INFO
 handlers =
 qualname = alembic
 [handler_console]
 class = StreamHandler
 args = (sys.stderr,)
 level = NOTSET
 formatter = generic
 [formatter_generic]
 format = %(levelname)-5.5s [%(name)s] %(message)s
 datefmt = %H:%M:%S
@@ -1,65 +0,0 @@
 """Alembic environment configuration."""
 import asyncio
 from logging.config import fileConfig
 from alembic import context
 from sqlalchemy.ext.asyncio import create_async_engine
 from app.config import settings
 from app.database import Base
 from app.models import user, session, world, asset  # noqa: F401
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
 config = context.config
 # Interpret the config file for Python logging.
 # This line sets up loggers basically.
 if config.config_file_name is not None:
    fileConfig(config.config_file_name)
 # add your model's MetaData object here
 # for 'autogenerate' support
 target_metadata = Base.metadata
 def run_migrations_offline() -> None:
    """Run migrations in 'offline' mode."""
    url = settings.DATABASE_URL
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )
    with context.begin_transaction():
        context.run_migrations()
 def do_run_migrations(connection):
    context.configure(connection=connection, target_metadata=target_metadata)
    with context.begin_transaction():
        context.run_migrations()
 async def run_async_migrations():
    """Run migrations in 'online' mode with async engine."""
    connectable = create_async_engine(settings.DATABASE_URL, echo=False)
    async with connectable.connect() as connection:
        await connection.run_sync(do_run_migrations)
    await connectable.dispose()
 def run_migrations_online() -> None:
    """Run migrations in 'online' mode."""
    asyncio.run(run_async_migrations())
 if context.is_offline_mode():
    run_migrations_offline()
 else:
    run_migrations_online()
@@ -1,27 +0,0 @@
 """${message}
 Revision ID: ${up_revision}
 Revises: ${down_revision | comma,n}
 Create Date: ${create_date}
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 ${imports if imports else ""}
 # revision identifiers, used by Alembic.
 revision: str = ${repr(up_revision)}
 down_revision: Union[str, None] = ${repr(down_revision)}
 branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
 depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
 def upgrade() -> None:
    """Upgrade database schema."""
    ${upgrades if upgrades else "pass"}
 def downgrade() -> None:
    """Downgrade database schema."""
    ${downgrades if downgrades else "pass"}
@@ -1,127 +0,0 @@
 """initial schema
 Revision ID: 0001_initial
 Revises:
 Create Date: 2024-01-01 00:00:00.000000
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects import postgresql
 # revision identifiers, used by Alembic.
 revision: str = "0001_initial"
 down_revision: Union[str, None] = None
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    """Upgrade database schema."""
    # Create ENUM types
    world_visibility = postgresql.ENUM(
        "public", "private", "friends_only", name="world_visibility"
    )
    world_visibility.create(op.get_bind(), checkfirst=True)
    asset_type = postgresql.ENUM(
        "image", "audio", "video", "document", "model_3d", "other", name="asset_type"
    )
    asset_type.create(op.get_bind(), checkfirst=True)
    # Create users table
    op.create_table(
        "users",
        sa.Column("id", sa.Integer(), primary_key=True),
        sa.Column("username", sa.String(length=50), nullable=False),
        sa.Column("email", sa.String(length=120), nullable=False),
        sa.Column("hashed_password", sa.String(length=255), nullable=False),
        sa.Column("is_active", sa.Boolean(), nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
    )
    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
    op.create_index(op.f("ix_users_id"), "users", ["id"], unique=False)
    op.create_index(op.f("ix_users_username"), "users", ["username"], unique=True)
    # Create sessions table
    op.create_table(
        "sessions",
        sa.Column("id", sa.String(length=36), primary_key=True),
        sa.Column("user_id", sa.Integer(), nullable=False),
        sa.Column("token", sa.String(), nullable=False),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("is_active", sa.Boolean(), nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
    )
    op.create_index(op.f("ix_sessions_token"), "sessions", ["token"], unique=True)
    # Create worlds table
    op.create_table(
        "worlds",
        sa.Column("id", sa.Integer(), primary_key=True),
        sa.Column("name", sa.String(length=255), nullable=False),
        sa.Column("description", sa.Text(), nullable=True),
        sa.Column("owner_id", sa.Integer(), nullable=False),
        sa.Column(
            "visibility",
            postgresql.ENUM(
                "public", "private", "friends_only", name="world_visibility",
                create_type=False,
            ),
            nullable=True,
        ),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
    )
    op.create_index(op.f("ix_worlds_id"), "worlds", ["id"], unique=False)
    # Create assets table
    op.create_table(
        "assets",
        sa.Column("id", sa.Integer(), primary_key=True),
        sa.Column("name", sa.String(length=255), nullable=False),
        sa.Column("description", sa.Text(), nullable=True),
        sa.Column(
            "asset_type",
            postgresql.ENUM(
                "image", "audio", "video", "document", "model_3d", "other",
                name="asset_type", create_type=False,
            ),
            nullable=False,
        ),
        sa.Column("file_path", sa.String(length=512), nullable=False),
        sa.Column("file_size", sa.Integer(), nullable=True),
        sa.Column("mime_type", sa.String(length=128), nullable=True),
        sa.Column("metadata_json", sa.Text(), nullable=True),
        sa.Column("world_id", sa.Integer(), nullable=True),
        sa.Column("owner_id", sa.Integer(), nullable=False),
        sa.Column("is_public", sa.Boolean(), nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
        sa.ForeignKeyConstraint(["world_id"], ["worlds.id"]),
    )
    op.create_index(op.f("ix_assets_id"), "assets", ["id"], unique=False)
 def downgrade() -> None:
    """Downgrade database schema."""
    op.drop_index(op.f("ix_assets_id"), table_name="assets")
    op.drop_table("assets")
    op.drop_index(op.f("ix_worlds_id"), table_name="worlds")
    op.drop_table("worlds")
    op.drop_index(op.f("ix_sessions_token"), table_name="sessions")
    op.drop_table("sessions")
    op.drop_index(op.f("ix_users_username"), table_name="users")
    op.drop_index(op.f("ix_users_id"), table_name="users")
    op.drop_index(op.f("ix_users_email"), table_name="users")
    op.drop_table("users")
    # Drop ENUM types
    postgresql.ENUM(name="asset_type").drop(op.get_bind(), checkfirst=True)
    postgresql.ENUM(name="world_visibility").drop(op.get_bind(), checkfirst=True)
@@ -1,30 +0,0 @@
 """add date_of_birth column to users table
 Revision ID: 0002_add_date_of_birth_to_users
 Revises: 0001_initial
 Create Date: 2025-01-01 00:00:00.000000
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 # revision identifiers, used by Alembic.
 revision: str = "0002_add_date_of_birth_to_users"
 down_revision: Union[str, None] = "0001_initial"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    """Add date_of_birth column to users table."""
    op.add_column(
        "users",
        sa.Column("date_of_birth", sa.Date(), nullable=True),
    )
 def downgrade() -> None:
    """Remove date_of_birth column from users table."""
    op.drop_column("users", "date_of_birth")
@@ -1,36 +0,0 @@
 """add refresh_tokens table
 Revision ID: 0003_add_refresh_tokens_table
 Revises: 0002_add_date_of_birth_to_users
 Create Date: 2025-07-25 00:00:00.000000
 """
 from typing import Sequence, Union
 from alembic import op
 import sqlalchemy as sa
 # revision identifiers, used by Alembic.
 revision: str = "0003_add_refresh_tokens_table"
 down_revision: Union[str, None] = "0002_add_date_of_birth_to_users"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    """Create the refresh_tokens table."""
    op.create_table(
        "refresh_tokens",
        sa.Column("id", sa.String(36), primary_key=True),
        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
        sa.Column("token", sa.String(512), unique=True, index=True, nullable=False),
        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
        sa.Column("is_active", sa.Boolean(), server_default=sa.text("true"), nullable=False),
        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
    )
 def downgrade() -> None:
    """Drop the refresh_tokens table."""
    op.drop_table("refresh_tokens")
@@ -1,127 +0,0 @@
 """Application configuration via pydantic-settings."""
 from functools import lru_cache
 from pathlib import Path
 from cryptography.hazmat.primitives.asymmetric.rsa import (
    RSAPrivateKey,
    RSAPublicKey,
    generate_private_key,
 )
 from cryptography.hazmat.primitives.serialization import (
    Encoding,
    NoEncryption,
    PrivateFormat,
    PublicFormat,
    load_pem_private_key,
    load_pem_public_key,
 )
 from pydantic_settings import BaseSettings, SettingsConfigDict
 def _load_or_generate_rsa_keys(key_dir: Path) -> tuple[bytes, bytes]:
    """Load existing RSA keys or generate a new pair.
    Keys are stored as PEM files in *key_dir*.  The directory is created
    if it does not exist.  Files are named ``private.pem`` and
    ``public.pem`` and are **not** committed to git.
    """
    private_path = key_dir / "private.pem"
    public_path = key_dir / "public.pem"
    if private_path.exists() and public_path.exists():
        private_pem = private_path.read_bytes()
        public_pem = public_path.read_bytes()
    else:
        # Generate a new 2048-bit RSA key pair
        private_key = generate_private_key(public_exponent=65537, key_size=2048)
        private_pem = private_key.private_bytes(
            Encoding.PEM,
            PrivateFormat.PKCS8,
            NoEncryption(),
        )
        public_pem = private_key.public_key().public_bytes(
            Encoding.PEM,
            PublicFormat.SubjectPublicKeyInfo,
        )
        key_dir.mkdir(parents=True, exist_ok=True)
        private_path.write_bytes(private_pem)
        public_path.write_bytes(public_pem)
    return private_pem, public_pem
 class Settings(BaseSettings):
    # App
    APP_NAME: str = "AGP Backend"
    APP_VERSION: str = "0.1.0"
    DEBUG: bool = True
    # Database (async)
    DATABASE_URL: str = "postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db"
    # Redis
    REDIS_URL: str = "redis://localhost:6379/0"
    # JWT / Auth
    ALGORITHM: str = "RS256"
    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
    REFRESH_TOKEN_EXPIRE_DAYS: int = 30
    # RS256 key storage.  Defaults to a directory outside the repo so the
    # generated keypair is never accidentally committed.
    RSA_KEY_DIR: str = str(Path.home() / ".agp" / "keys")
    # CORS
    CORS_ORIGINS: str = "http://localhost:8080,http://localhost:3000"
    # File uploads
    UPLOAD_DIR: str = "uploads"
    MAX_UPLOAD_SIZE_MB: int = 100
    GLTF_MAX_FILE_SIZE_MB: int = 200
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=True,
    )
    @property
    def cors_origins_list(self) -> list[str]:
        return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
    @property
    def rsa_key_dir(self) -> Path:
        return Path(self.RSA_KEY_DIR)
    @property
    def private_pem(self) -> bytes:
        """Return the private key PEM bytes (loads/generates on first call)."""
        private_pem, _ = _load_or_generate_rsa_keys(self.rsa_key_dir)
        return private_pem
    @property
    def public_pem(self) -> bytes:
        """Return the public key PEM bytes (loads/generates on first call)."""
        _, public_pem = _load_or_generate_rsa_keys(self.rsa_key_dir)
        return public_pem
    @property
    def private_key(self) -> RSAPrivateKey:
        """Return the deserialized RSA private key object."""
        return load_pem_private_key(self.private_pem, password=None)
    @property
    def public_key(self) -> RSAPublicKey:
        """Return the deserialized RSA public key object."""
        return load_pem_public_key(self.public_pem)
@lru_cache()
 def get_settings() -> Settings:
    """Return cached settings instance."""
    return Settings()
 # Convenience singleton
 settings = get_settings()
@@ -1,42 +0,0 @@
 """Async database engine and session factory."""
 from sqlalchemy.ext.asyncio import (
    AsyncSession,
    async_sessionmaker,
    create_async_engine,
 )
 from sqlalchemy.orm import DeclarativeBase
 from app.config import settings
 engine = create_async_engine(
    settings.DATABASE_URL,
    echo=settings.DEBUG,
    pool_size=10,
    max_overflow=20,
 )
 async_session_factory = async_sessionmaker(
    engine,
    class_=AsyncSession,
    expire_on_commit=False,
 )
 class Base(DeclarativeBase):
    pass
 async def get_db() -> AsyncSession:
    """Dependency that yields an async database session.
    Handlers are responsible for committing or rolling back their own
    transactions.  This avoids the double-commit problem where the
    session is committed both here and in the handler.
    """
    async with async_session_factory() as session:
        try:
            yield session
        except Exception:
            await session.rollback()
            raise
@@ -1,55 +0,0 @@
 """Shared FastAPI dependencies, including JWT-based auth."""
 from typing import Annotated
 from fastapi import Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordBearer
 from jose import JWTError, jwt
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.config import settings
 from app.database import get_db
 from app.models.user import User
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
 async def get_current_user(
    token: Annotated[str, Depends(oauth2_scheme)],
    db: Annotated[AsyncSession, Depends(get_db)],
 ) -> User:
    """Resolve the JWT bearer token to a User, or raise 401."""
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(
            token, settings.public_pem, algorithms=[settings.ALGORITHM]
        )
        user_id: str | None = payload.get("sub")
        if user_id is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception
    try:
        user_id_int = int(user_id)
    except (ValueError, TypeError):
        raise credentials_exception
    result = await db.execute(select(User).where(User.id == user_id_int))
    user = result.scalar_one_or_none()
    if user is None:
        raise credentials_exception
    if not user.is_active:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="User account is inactive",
        )
    return user
 CurrentUser = Annotated[User, Depends(get_current_user)]
@@ -1,46 +0,0 @@
 """FastAPI application entry point."""
 from contextlib import asynccontextmanager
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from app.config import settings
 from app.routers import auth, users, worlds, assets
@asynccontextmanager
 async def lifespan(app: FastAPI):
    """Application lifespan: startup and shutdown events."""
    # Startup: initialize database, connect to Redis, etc.
    yield
    # Shutdown: close connections, cleanup
 app = FastAPI(
    title=settings.APP_NAME,
    version=settings.APP_VERSION,
    description="Agentic Game Platform - Backend API",
    lifespan=lifespan,
 )
 # CORS
 app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.cors_origins_list,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
 )
 # Include routers
 app.include_router(auth.router, prefix="/api/auth", tags=["auth"])
 app.include_router(users.router, prefix="/api/users", tags=["users"])
 app.include_router(worlds.router, prefix="/api/worlds", tags=["worlds"])
 app.include_router(assets.router, prefix="/api/assets", tags=["assets"])
@app.get("/api/health")
 async def health_check():
    """Simple health check endpoint."""
    return {"status": "ok", "app": settings.APP_NAME}
@@ -1,6 +0,0 @@
 from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
 __all__ = ["User", "Session", "World", "Asset"]
@@ -1,40 +0,0 @@
 from sqlalchemy import Column, Integer, String, ForeignKey, Text, DateTime, Boolean
 from sqlalchemy.dialects.postgresql import ENUM
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 import enum
 from app.database import Base
 class AssetType(str, enum.Enum):
    IMAGE = "image"
    AUDIO = "audio"
    VIDEO = "video"
    DOCUMENT = "document"
    MODEL_3D = "model_3d"
    OTHER = "other"
 class Asset(Base):
    __tablename__ = "assets"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(255), nullable=False)
    description = Column(Text, nullable=True)
    asset_type = Column(
        ENUM(AssetType, name="asset_type", create_type=False),
        nullable=False,
    )
    file_path = Column(String(512), nullable=False)
    file_size = Column(Integer, nullable=True)
    mime_type = Column(String(128), nullable=True)
    metadata_json = Column(Text, nullable=True)
    world_id = Column(Integer, ForeignKey("worlds.id"), nullable=True)
    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    is_public = Column(Boolean, default=False, nullable=False)
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
    owner = relationship("User", back_populates="assets")
    world = relationship("World", back_populates="assets")
@@ -1,41 +0,0 @@
 import uuid
 from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Boolean
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class Session(Base):
    __tablename__ = "sessions"
    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
    token = Column(String, unique=True, index=True, nullable=False)
    expires_at = Column(DateTime(timezone=True), nullable=False)
    is_active = Column(Boolean, default=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
    user = relationship("User", back_populates="sessions")
 class RefreshToken(Base):
    __tablename__ = "refresh_tokens"
    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
    # RS256 JWTs are ~420+ chars; 512 is sufficient and matches the migration.
    token = Column(String(512), unique=True, index=True, nullable=False)
    expires_at = Column(DateTime(timezone=True), nullable=False)
    is_active = Column(Boolean, nullable=False, default=True, server_default="true")
    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
    updated_at = Column(
        DateTime(timezone=True),
        nullable=False,
        server_default=func.now(),
        onupdate=func.now(),
    )
    user = relationship("User", back_populates="refresh_tokens")
@@ -1,38 +0,0 @@
 from datetime import date
 from typing import Optional
 from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 from app.database import Base
 class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, index=True, nullable=False)
    email = Column(String(120), unique=True, index=True, nullable=False)
    hashed_password = Column(String(255), nullable=False)
    date_of_birth = Column(Date, nullable=True)
    is_active = Column(Boolean, default=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
    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")
    @property
    def is_adult(self) -> bool:
        """Return True if the user is 18 or older based on date_of_birth."""
        if self.date_of_birth is None:
            return False
        today = date.today()
        age = today.year - self.date_of_birth.year
        # Adjust if birthday hasn't occurred yet this year
        if (today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day):
            age -= 1
        return age >= 18
@@ -1,31 +0,0 @@
 from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
 from sqlalchemy.dialects.postgresql import ENUM
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 import enum
 from app.database import Base
 class WorldVisibility(enum.Enum):
    PUBLIC = "public"
    PRIVATE = "private"
    FRIENDS_ONLY = "friends_only"
 class World(Base):
    __tablename__ = "worlds"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(255), nullable=False)
    description = Column(Text, nullable=True)
    owner_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    visibility = Column(
        ENUM(WorldVisibility, name="world_visibility", create_type=False),
        default=WorldVisibility.PUBLIC,
    )
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
    owner = relationship("User", back_populates="worlds")
    assets = relationship("Asset", back_populates="world", cascade="all, delete-orphan")
@@ -1,243 +0,0 @@
 """Asset management router."""
 import json
 import os
 from pathlib import Path
 from typing import Optional
 from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Query
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.config import settings
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.asset import Asset, AssetType
 from app.models.world import World
 from app.services import gltf as gltf_service
 from pydantic import BaseModel, Field
 router = APIRouter()
 # --- Pydantic schemas ---
 class AssetCreate(BaseModel):
    """Schema for creating an asset reference."""
    name: str = Field(..., min_length=1, max_length=255)
    description: Optional[str] = None
    asset_type: AssetType
    world_id: Optional[int] = None
 class AssetResponse(BaseModel):
    """Schema for asset responses."""
    id: int
    name: str
    description: Optional[str]
    asset_type: AssetType
    file_path: str
    file_size: Optional[int]
    mime_type: Optional[str]
    world_id: Optional[int]
    owner_id: int
    is_public: bool
    created_at: str
    updated_at: str
    model_config = {"from_attributes": True}
 class AssetUpdate(BaseModel):
    """Schema for updating an asset."""
    name: Optional[str] = None
    description: Optional[str] = None
    is_public: Optional[bool] = None
 # --- Helpers ---
 def _sanitize_filename(filename: str) -> str:
    """Strip path components and unsafe characters from a filename."""
    # Remove any directory components (path traversal protection).
    base = os.path.basename(filename.replace("\\", "/"))
    # Keep only safe characters.
    safe = "".join(c for c in base if c.isalnum() or c in "._-")
    return safe or "file"
 def _detect_asset_type(filename: Optional[str], content: bytes) -> AssetType:
    """Detect the asset type from filename and content."""
    if filename and gltf_service.looks_like_gltf(content, filename):
        return AssetType.MODEL_3D
    # Fallback: let the caller decide based on mime_type or default.
    return AssetType.OTHER
 # --- Endpoints ---
@router.post("/", response_model=AssetResponse, status_code=201)
 async def create_asset(
    payload: AssetCreate,
    current_user: CurrentUser,
    db: AsyncSession = Depends(get_db),
 ):
    """Create a new asset reference."""
    # Verify world ownership if world_id is provided
    if payload.world_id is not None:
        world = await db.get(World, payload.world_id)
        if world is None:
            raise HTTPException(status_code=404, detail="World not found")
        if world.owner_id != current_user.id:
            raise HTTPException(status_code=403, detail="Not owner of this world")
    asset = Asset(
        name=payload.name,
        description=payload.description,
        asset_type=payload.asset_type,
        file_path="",  # Will be set after upload
        owner_id=current_user.id,
        world_id=payload.world_id,
        is_public=False,
    )
    db.add(asset)
    await db.commit()
    await db.refresh(asset)
    return asset
@router.get("/", response_model=list[AssetResponse])
 async def list_assets(
    current_user: CurrentUser,
    world_id: Optional[int] = Query(None, description="Filter by world"),
    asset_type: Optional[AssetType] = Query(None),
    limit: int = Query(50, ge=1, le=100),
    offset: int = Query(0, ge=0),
    db: AsyncSession = Depends(get_db),
 ):
    """List assets with optional filters."""
    stmt = select(Asset).where(Asset.owner_id == current_user.id)
    if world_id is not None:
        stmt = stmt.where(Asset.world_id == world_id)
    if asset_type is not None:
        stmt = stmt.where(Asset.asset_type == asset_type)
    stmt = stmt.order_by(Asset.created_at.desc()).limit(limit).offset(offset)
    result = await db.execute(stmt)
    assets = result.scalars().all()
    return assets
@router.get("/{asset_id}", response_model=AssetResponse)
 async def get_asset(
    asset_id: int,
    current_user: CurrentUser,
    db: AsyncSession = Depends(get_db),
 ):
    """Get a single asset by ID."""
    asset = await db.get(Asset, asset_id)
    if asset is None or asset.owner_id != current_user.id:
        raise HTTPException(status_code=404, detail="Asset not found")
    return asset
@router.patch("/{asset_id}", response_model=AssetResponse)
 async def update_asset(
    asset_id: int,
    payload: AssetUpdate,
    current_user: CurrentUser,
    db: AsyncSession = Depends(get_db),
 ):
    """Update an asset."""
    asset = await db.get(Asset, asset_id)
    if asset is None or asset.owner_id != current_user.id:
        raise HTTPException(status_code=404, detail="Asset not found")
    update_data = payload.model_dump(exclude_unset=True)
    for field, value in update_data.items():
        setattr(asset, field, value)
    await db.commit()
    await db.refresh(asset)
    return asset
@router.delete("/{asset_id}", status_code=204)
 async def delete_asset(
    asset_id: int,
    current_user: CurrentUser,
    db: AsyncSession = Depends(get_db),
 ):
    """Delete an asset."""
    asset = await db.get(Asset, asset_id)
    if asset is None or asset.owner_id != current_user.id:
        raise HTTPException(status_code=404, detail="Asset not found")
    await db.delete(asset)
    await db.commit()
@router.post("/{asset_id}/upload", response_model=AssetResponse)
 async def upload_asset_file(
    asset_id: int,
    current_user: CurrentUser,
    file: UploadFile = File(...),
    db: AsyncSession = Depends(get_db),
 ):
    """Upload a file for an existing asset."""
    asset = await db.get(Asset, asset_id)
    if asset is None or asset.owner_id != current_user.id:
        raise HTTPException(status_code=404, detail="Asset not found")
    # Sanitize filename to prevent path traversal.
    safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
    # Read the file content.
    content = await file.read()
    file_size = len(content)
    # Determine which size limit to apply.
    if gltf_service.looks_like_gltf(content, file.filename):
        max_bytes = settings.GLTF_MAX_FILE_SIZE_MB * 1024 * 1024
    else:
        max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
    if file_size > max_bytes:
        raise HTTPException(
            status_code=413,
            detail=f"File size {file_size} exceeds maximum allowed size {max_bytes} bytes",
        )
    # Write the file to the upload directory.
    upload_dir = Path(settings.UPLOAD_DIR)
    upload_dir.mkdir(parents=True, exist_ok=True)
    stored_name = f"{asset_id}_{safe_filename}"
    file_path = upload_dir / stored_name
    file_path.write_bytes(content)
    # Detect asset type from content/filename.
    detected_type = _detect_asset_type(file.filename, content)
    # Update asset record.
    asset.file_path = str(file_path)
    asset.mime_type = file.content_type
    asset.file_size = file_size
    # If this is a glTF file, extract and store metadata.
    if detected_type == AssetType.MODEL_3D:
        try:
            metadata = gltf_service.extract_gltf_metadata(content)
            asset.metadata_json = json.dumps(metadata)
            # Also set the asset type to model_3d if it was auto-detected.
            if asset.asset_type == AssetType.OTHER:
                asset.asset_type = AssetType.MODEL_3D
        except ValueError as exc:
            raise HTTPException(
                status_code=400,
                detail=f"Invalid glTF file: {exc}",
            )
    await db.commit()
    await db.refresh(asset)
    return asset
@@ -1,315 +0,0 @@
 """Authentication router - login, register, token refresh."""
 import uuid
 from datetime import date, datetime, timedelta, timezone
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
 from jose import JWTError, jwt
 from passlib.context import CryptContext
 from pydantic import BaseModel, EmailStr, field_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.config import settings
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.session import RefreshToken
 from app.models.user import User
 pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
 router = APIRouter()
 # --- Pydantic schemas ---
 class TokenResponse(BaseModel):
    access_token: str
    refresh_token: str
    token_type: str = "bearer"
    access_token_expires_minutes: int
 class RefreshRequest(BaseModel):
    refresh_token: str
 class RegisterRequest(BaseModel):
    username: str
    email: EmailStr
    password: str
    date_of_birth: str  # ISO format date string (YYYY-MM-DD)
    @field_validator("date_of_birth")
    @classmethod
    def validate_date_of_birth(cls, v: str) -> str:
        """Validate that the date string is a valid date in YYYY-MM-DD format."""
        try:
            datetime.strptime(v, "%Y-%m-%d")
        except ValueError:
            raise ValueError("date_of_birth must be in YYYY-MM-DD format")
        return v
 class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    date_of_birth: str | None = None
    is_active: bool
    created_at: datetime | None = None
    model_config = {"from_attributes": True}
 # --- Helpers ---
 def _create_access_token(data: dict) -> str:
    """Create a signed access token using RS256.
    Includes a unique ``jti`` claim so that concurrent/same-second calls
    (e.g. back-to-back /refresh requests) still produce distinct tokens —
    without it, two tokens minted for the same user within the same
    second are byte-identical since ``sub``/``exp`` are the only claims.
    """
    to_encode = data.copy()
    to_encode["jti"] = str(uuid.uuid4())
    expire = datetime.now(timezone.utc) + timedelta(
        minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
    )
    to_encode.update({"exp": expire})
    return jwt.encode(
        to_encode,
        settings.private_pem,
        algorithm=settings.ALGORITHM,
    )
 def _create_refresh_token(data: dict) -> str:
    """Create a signed refresh token using RS256.
    Includes a unique ``jti`` claim so that concurrent calls produce
    distinct tokens even when issued within the same second.
    """
    to_encode = data.copy()
    to_encode["jti"] = str(uuid.uuid4())
    expire = datetime.now(timezone.utc) + timedelta(
        days=settings.REFRESH_TOKEN_EXPIRE_DAYS
    )
    to_encode.update({"exp": expire})
    return jwt.encode(
        to_encode,
        settings.private_pem,
        algorithm=settings.ALGORITHM,
    )
 def verify_password(plain_password: str, hashed_password: str) -> bool:
    """Verify a plain password against a hash."""
    return pwd_context.verify(plain_password, hashed_password)
 def hash_password(password: str) -> str:
    """Hash a password."""
    return pwd_context.hash(password)
 def calculate_age(birth_date: date, today: date | None = None) -> int:
    """Calculate age in years from a birth date.
    Args:
        birth_date: The person's date of birth.
        today: The reference date. Defaults to today's date (UTC).
    Returns:
        Age in whole years as of the reference date.
    """
    if today is None:
        today = datetime.now(timezone.utc).date()
    age = today.year - birth_date.year
    # Adjust if birthday hasn't occurred yet this year
    if (today.month, today.day) < (birth_date.month, birth_date.day):
        age -= 1
    return age
 def _issue_refresh_token(user_id: int, db: AsyncSession) -> str:
    """Create and persist a refresh token for the given user."""
    refresh_token_value = _create_refresh_token({"sub": str(user_id)})
    refresh_token_record = RefreshToken(
        id=str(uuid.uuid4()),
        user_id=user_id,
        token=refresh_token_value,
        expires_at=datetime.now(timezone.utc)
        + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS),
    )
    db.add(refresh_token_record)
    return refresh_token_value
 # --- Endpoints ---
@router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
 async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
    """Register a new user and return access + refresh tokens.
    Requires date_of_birth and rejects users under 18.
    """
    # Parse and validate date_of_birth
    dob = datetime.strptime(req.date_of_birth, "%Y-%m-%d").date()
    age = calculate_age(dob)
    if age < 18:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=f"Must be 18 or older to register (provided date of birth: {req.date_of_birth})",
        )
    # Check if username already exists
    result = await db.execute(select(User).where(User.username == req.username))
    if result.scalar_one_or_none():
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Username already registered",
        )
    # Check if email already exists
    result = await db.execute(select(User).where(User.email == req.email))
    if result.scalar_one_or_none():
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Email already registered",
        )
    user = User(
        username=req.username,
        email=req.email,
        hashed_password=hash_password(req.password),
        date_of_birth=dob,
    )
    db.add(user)
    await db.flush()  # flush to get user.id before creating refresh token
    await db.refresh(user)
    # Create access token
    access_token = _create_access_token({"sub": str(user.id)})
    # Create and persist refresh token
    refresh_token_value = _issue_refresh_token(user.id, db)
    await db.commit()
    return TokenResponse(
        access_token=access_token,
        refresh_token=refresh_token_value,
        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
    )
@router.post("/login", response_model=TokenResponse)
 async def login(form: OAuth2PasswordRequestForm = Depends(), db: AsyncSession = Depends(get_db)):
    """Authenticate user and return access + refresh tokens.
    Accepts form-encoded credentials (username/password) as expected by
    OAuth2PasswordBearer, so the Swagger UI "Authorize" flow works correctly.
    """
    result = await db.execute(select(User).where(User.username == form.username))
    user = result.scalar_one_or_none()
    if not user or not verify_password(form.password, user.hashed_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
        )
    if not user.is_active:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="User account is inactive",
        )
    # Create access token
    access_token = _create_access_token({"sub": str(user.id)})
    # Create and persist refresh token
    refresh_token_value = _issue_refresh_token(user.id, db)
    await db.commit()
    return TokenResponse(
        access_token=access_token,
        refresh_token=refresh_token_value,
        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
    )
@router.post("/refresh", response_model=TokenResponse)
 async def refresh(req: RefreshRequest, db: AsyncSession = Depends(get_db)):
    """Exchange a valid refresh token for a new access token.
    Validates the refresh token against the database:
    - Must exist in the refresh_tokens table
    - Must not be expired (expires_at > now)
    - Must be active (is_active == true)
    On success, returns a new access token. The refresh token itself is
    NOT rotated (the client keeps using the same refresh token).
    """
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Invalid or expired refresh token",
    )
    # Step 1: Decode and validate the JWT signature/claims
    try:
        payload = jwt.decode(
            req.refresh_token,
            settings.public_pem,
            algorithms=[settings.ALGORITHM],
        )
    except JWTError:
        raise credentials_exception
    user_id_str: str | None = payload.get("sub")
    if user_id_str is None:
        raise credentials_exception
    try:
        user_id = int(user_id_str)
    except (ValueError, TypeError):
        raise credentials_exception
    # Step 2: Look up the refresh token in the database
    result = await db.execute(
        select(RefreshToken).where(
            RefreshToken.token == req.refresh_token,
            RefreshToken.user_id == user_id,
        )
    )
    stored_token = result.scalar_one_or_none()
    if stored_token is None:
        raise credentials_exception
    # Step 3: Check if the token is expired
    if datetime.now(timezone.utc) >= stored_token.expires_at:
        raise credentials_exception
    # Step 4: Check if the token is active
    if not stored_token.is_active:
        raise credentials_exception
    # Step 5: Issue a new access token
    access_token = _create_access_token({"sub": str(user_id)})
    return TokenResponse(
        access_token=access_token,
        refresh_token=req.refresh_token,  # Return the same refresh token
        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
    )
@router.get("/me", response_model=UserResponse)
 async def get_current_user(current_user: CurrentUser):
    """Get current user profile from the JWT token."""
    return current_user
@@ -1,106 +0,0 @@
 """User management router."""
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel, EmailStr
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.user import User
 router = APIRouter()
 # ─── Pydantic schemas ────────────────────────────────────────────────────────
 class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    is_active: bool
    model_config = {"from_attributes": True}
 class UserUpdate(BaseModel):
    email: EmailStr | None = None
    is_active: bool | None = None
 # ─── Endpoints ───────────────────────────────────────────────────────────────
@router.get("/me", response_model=UserResponse)
 async def get_current_user_profile(
    current_user: CurrentUser,
 ):
    """Get the currently authenticated user's profile."""
    return current_user
@router.get("/{user_id}", response_model=UserResponse)
 async def get_user(
    user_id: int,
    current_user: CurrentUser,
    db: Annotated[AsyncSession, Depends(get_db)],
 ):
    """Get a user by ID.  Only the owner can view their own profile."""
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    # Only the owner may view their own profile.
    if user.id != current_user.id:
        raise HTTPException(status_code=403, detail="Not authorized to view this user")
    return user
@router.patch("/{user_id}", response_model=UserResponse)
 async def update_user(
    user_id: int,
    user_update: UserUpdate,
    current_user: CurrentUser,
    db: Annotated[AsyncSession, Depends(get_db)],
 ):
    """Update a user.  Only the owner can update their own account."""
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    # Only the owner may update their own account.
    if user.id != current_user.id:
        raise HTTPException(status_code=403, detail="Not authorized to update this user")
    if user_update.email is not None:
        user.email = user_update.email
    if user_update.is_active is not None:
        user.is_active = user_update.is_active
    await db.commit()
    await db.refresh(user)
    return user
@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_user(
    user_id: int,
    current_user: CurrentUser,
    db: Annotated[AsyncSession, Depends(get_db)],
 ):
    """Delete a user.  Only the owner can delete their own account."""
    result = await db.execute(select(User).where(User.id == user_id))
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    # Only the owner may delete their own account.
    if user.id != current_user.id:
        raise HTTPException(status_code=403, detail="Not authorized to delete this user")
    await db.delete(user)
    await db.commit()
@@ -1,168 +0,0 @@
 """Worlds router - CRUD for game worlds."""
 from typing import Annotated
 from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel, Field
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.world import World, WorldVisibility
 router = APIRouter()
 DbDep = Annotated[AsyncSession, Depends(get_db)]
 # --- Pydantic schemas ---
 class WorldCreate(BaseModel):
    """Schema for creating a world."""
    name: str = Field(..., min_length=1, max_length=255)
    description: str | None = None
    visibility: WorldVisibility = WorldVisibility.PUBLIC
 class WorldUpdate(BaseModel):
    """Schema for updating a world."""
    name: str | None = Field(None, min_length=1, max_length=255)
    description: str | None = None
    visibility: WorldVisibility | None = None
 class WorldResponse(BaseModel):
    """Schema for world responses."""
    id: int
    name: str
    description: str | None
    visibility: WorldVisibility
    owner_id: int
    created_at: str | None = None
    model_config = {"from_attributes": True}
 # --- Endpoints ---
@router.get("/", response_model=list[WorldResponse])
 async def list_worlds(
    current_user: CurrentUser,
    db: DbDep,
    skip: int = Query(0, ge=0),
    limit: int = Query(50, ge=1, le=100),
    visibility: WorldVisibility | None = None,
 ):
    """List worlds visible to the current user.
    PUBLIC worlds are visible to everyone.
    PRIVATE/FRIENDS_ONLY worlds are visible to their owner.
    """
    query = select(World).options(selectinload(World.owner))
    # Filter by visibility if specified
    if visibility:
        query = query.where(World.visibility == visibility)
        if visibility != WorldVisibility.PUBLIC:
            # Requesting a non-public visibility explicitly must not bypass
            # ownership — otherwise any authenticated user could list every
            # PRIVATE/FRIENDS_ONLY world in the system just by passing the
            # filter, defeating the point of the check below.
            query = query.where(World.owner_id == current_user.id)
    else:
        # Show PUBLIC worlds + owner's own worlds
        query = query.where(
            (World.visibility == WorldVisibility.PUBLIC)
            | (World.owner_id == current_user.id)
        )
    query = query.offset(skip).limit(limit).order_by(World.created_at.desc())
    result = await db.execute(query)
    worlds = result.scalars().all()
    return worlds
@router.get("/{world_id}", response_model=WorldResponse)
 async def get_world(
    world_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Get a single world by ID, respecting visibility."""
    result = await db.execute(
        select(World).where(World.id == world_id).options(selectinload(World.owner))
    )
    world = result.scalar_one_or_none()
    if not world:
        raise HTTPException(status_code=404, detail="World not found")
    # Allow access if world is PUBLIC or owned by current user
    if world.visibility != WorldVisibility.PUBLIC and world.owner_id != current_user.id:
        raise HTTPException(status_code=404, detail="World not found")
    return world
@router.post("/", response_model=WorldResponse, status_code=201)
 async def create_world(
    world_data: WorldCreate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Create a new world."""
    world = World(
        name=world_data.name,
        description=world_data.description,
        owner_id=current_user.id,
        visibility=world_data.visibility,
    )
    db.add(world)
    await db.commit()
    await db.refresh(world)
    return world
@router.put("/{world_id}", response_model=WorldResponse)
 async def update_world(
    world_id: int,
    world_data: WorldUpdate,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Update an existing world."""
    result = await db.execute(select(World).where(World.id == world_id))
    world = result.scalar_one_or_none()
    if not world:
        raise HTTPException(status_code=404, detail="World not found")
    if world.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="Not owner of this world")
    update_data = world_data.model_dump(exclude_unset=True)
    for field, value in update_data.items():
        setattr(world, field, value)
    await db.commit()
    await db.refresh(world)
    return world
@router.delete("/{world_id}", status_code=204)
 async def delete_world(
    world_id: int,
    current_user: CurrentUser,
    db: DbDep,
 ):
    """Delete a world."""
    result = await db.execute(select(World).where(World.id == world_id))
    world = result.scalar_one_or_none()
    if not world:
        raise HTTPException(status_code=404, detail="World not found")
    if world.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="Not owner of this world")
    await db.delete(world)
    await db.commit()
@@ -1,197 +0,0 @@
 """Lightweight glTF / GLB metadata extraction.
 This module intentionally avoids heavyweight dependencies such as trimesh or
 pygltflib. For the metadata fields the asset upload pipeline needs (mesh and
 vertex counts, animation presence, texture references, and the bounding box)
 a small amount of glTF-specific parsing is sufficient and keeps the backend
 dependency-free.
 """
 from __future__ import annotations
 import json
 import struct
 from typing import Any, Optional
 # GLB binary header magic bytes ("glTF").
 _GLB_MAGIC = b"glTF"
 _GLB_MAGIC_INT = 0x46546C67  # b"glTF" interpreted as little-endian uint32
 _GLB_JSON_CHUNK_TYPE = 0x4E4F534A  # "JSON"
 _GLB_BIN_CHUNK_TYPE = 0x004E4942  # "BIN\0"
 # Whitespace allowed around a GLB JSON chunk. The spec pads with spaces (0x20),
 # but be lenient with null bytes and other whitespace that real exporters emit.
 _JSON_CHUNK_TRIM = b" \t\r\n\x00"
 def looks_like_gltf(content: bytes, filename: Optional[str] = None) -> bool:
    """Return True when the bytes or filename indicate a glTF/GLB asset."""
    if content.startswith(_GLB_MAGIC):
        return True
    if filename:
        lowered = filename.lower()
        if lowered.endswith(".gltf") or lowered.endswith(".glb"):
            return True
    # A bare JSON buffer (e.g. uploaded without an extension) that has the
    # glTF asset marker is also a glTF file.
    stripped = content.lstrip()
    if stripped.startswith(b"{"):
        try:
            payload = json.loads(stripped.decode("utf-8"))
        except (ValueError, UnicodeDecodeError):
            return False
        return isinstance(payload, dict) and "asset" in payload and "version" in payload.get("asset", {})
    return False
 def _parse_glb(content: bytes) -> dict[str, Any]:
    """Parse the JSON chunk of a GLB binary container."""
    if len(content) < 12:
        raise ValueError("GLB file is too short")
    magic, _version, _length = struct.unpack_from("<III", content, 0)
    if magic != _GLB_MAGIC_INT:
        raise ValueError("invalid GLB magic")
    offset = 12
    json_chunk: Optional[dict[str, Any]] = None
    while offset + 8 <= len(content):
        chunk_length, chunk_type = struct.unpack_from("<II", content, offset)
        offset += 8
        chunk_end = offset + chunk_length
        if chunk_end > len(content):
            raise ValueError("GLB chunk overruns file boundary")
        chunk_data = content[offset:chunk_end]
        if chunk_type == _GLB_JSON_CHUNK_TYPE:
            try:
                json_chunk = json.loads(chunk_data.strip(_JSON_CHUNK_TRIM).decode("utf-8"))
            except (ValueError, UnicodeDecodeError) as exc:
                raise ValueError(f"invalid GLB JSON chunk: {exc}") from exc
        offset = chunk_end
    if json_chunk is None:
        raise ValueError("GLB file does not contain a JSON chunk")
    return json_chunk
 def _parse_gltf_json(content: bytes) -> dict[str, Any]:
    """Parse a plain .gltf JSON file."""
    stripped = content.lstrip()
    try:
        payload = json.loads(stripped.decode("utf-8"))
    except (ValueError, UnicodeDecodeError) as exc:
        raise ValueError(f"invalid glTF JSON: {exc}") from exc
    if not isinstance(payload, dict):
        raise ValueError("glTF JSON root must be an object")
    return payload
 def _position_accessor_counts(gltf: dict[str, Any]) -> list[int]:
    """Return POSITION accessor counts for every mesh primitive."""
    counts: list[int] = []
    accessors = gltf.get("accessors", [])
    for mesh in gltf.get("meshes", []):
        for primitive in mesh.get("primitives", []):
            attributes = primitive.get("attributes", {})
            position_index = attributes.get("POSITION")
            if position_index is None:
                continue
            try:
                accessor = accessors[int(position_index)]
            except (IndexError, TypeError, ValueError):
                continue
            count = accessor.get("count")
            if isinstance(count, int):
                counts.append(count)
    return counts
 def _position_bounds(gltf: dict[str, Any]) -> list[list[float]]:
    """Return min/max bounds for every POSITION accessor that declares them."""
    bounds: list[list[float]] = []
    accessors = gltf.get("accessors", [])
    for mesh in gltf.get("meshes", []):
        for primitive in mesh.get("primitives", []):
            attributes = primitive.get("attributes", {})
            position_index = attributes.get("POSITION")
            if position_index is None:
                continue
            try:
                accessor = accessors[int(position_index)]
            except (IndexError, TypeError, ValueError):
                continue
            minimum = accessor.get("min")
            maximum = accessor.get("max")
            if isinstance(minimum, list) and isinstance(maximum, list):
                bounds.append([float(x) for x in minimum])
                bounds.append([float(x) for x in maximum])
    return bounds
 def _texture_refs(gltf: dict[str, Any]) -> list[str]:
    """Collect external texture source references from the image array."""
    refs: list[str] = []
    for index, image in enumerate(gltf.get("images", [])):
        uri = image.get("uri")
        if isinstance(uri, str) and not uri.startswith("data:"):
            refs.append(uri)
            continue
        name = image.get("name")
        if isinstance(name, str) and name:
            refs.append(name)
            continue
        if isinstance(uri, str):
            # Embedded data URI; keep a stable, non-huge reference.
            refs.append(f"data:{index}")
            continue
        buffer_view = image.get("bufferView")
        if buffer_view is not None:
            refs.append(f"bufferView:{buffer_view}")
            continue
        refs.append(f"image:{index}")
    return refs
 def extract_gltf_metadata(content: bytes) -> dict[str, Any]:
    """Extract upload-relevant metadata from glTF/GLB bytes.
    Raises ValueError for malformed glTF content. The returned dict contains:
        mesh_count, vertex_count, has_animation, texture_refs,
        bounding_box_min, bounding_box_max.
    """
    if content.startswith(_GLB_MAGIC):
        gltf = _parse_glb(content)
    else:
        gltf = _parse_gltf_json(content)
    position_counts = _position_accessor_counts(gltf)
    bounds = _position_bounds(gltf)
    if bounds:
        bounding_box_min = [min(axis) for axis in zip(*bounds[::2])]
        bounding_box_max = [max(axis) for axis in zip(*bounds[1::2])]
    else:
        bounding_box_min = [0.0, 0.0, 0.0]
        bounding_box_max = [0.0, 0.0, 0.0]
    return {
        "mesh_count": len(gltf.get("meshes", [])),
        "vertex_count": sum(position_counts),
        "has_animation": bool(gltf.get("animations")),
        "texture_refs": _texture_refs(gltf),
        "bounding_box_min": bounding_box_min,
        "bounding_box_max": bounding_box_max,
    }
@@ -1,34 +0,0 @@
 version: "3.9"
 services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: agp_user
      POSTGRES_PASSWORD: agp_password
      POSTGRES_DB: agp_db
    ports:
      - "${POSTGRES_HOST_PORT:-5432}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U agp_user -d agp_db"]
      interval: 5s
      timeout: 5s
      retries: 5
  redis:
    image: redis:7-alpine
    ports:
      - "${REDIS_HOST_PORT:-6379}:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5
 volumes:
  postgres_data:
  redis_data:
@@ -1,3 +0,0 @@
 [pytest]
 asyncio_mode = auto
 testpaths = tests
@@ -1,25 +0,0 @@
 fastapi==0.115.6
 uvicorn[standard]==0.34.0
 sqlalchemy==2.0.36
 alembic==1.14.0
 psycopg2-binary==2.9.10
 asyncpg==0.31.0
 redis==5.2.1
 pydantic==2.10.3
 pydantic-settings==2.7.0
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
 # passlib 1.7.4 (last release, unmaintained since ~2020) detects its bcrypt
 # backend via bcrypt.__about__.__version__, which bcrypt>=4.1 removed --
 # hashing/verifying a password then raises "password cannot be longer than
 # 72 bytes" (a misleading downstream symptom of the real AttributeError:
 # module 'bcrypt' has no attribute '__about__') on every call. Without this
 # pin, `pip install -r requirements.txt` silently grabs whatever the latest
 # bcrypt is and breaks register/login outright. Pin below 4.1 explicitly.
 bcrypt==4.0.1
 python-multipart==0.0.20
 email-validator==2.2.0
 httpx==0.28.1
 pytest==8.3.4
 pytest-asyncio==0.25.0
 pytest-cov==6.0.0
@@ -1,38 +0,0 @@
 """Shared pytest fixtures.
 The auth integration tests hit the *real* Postgres database (per
 ``DATABASE_URL``), so they persist data between runs.  Without cleanup a
 second run of the suite fails with 409 conflicts because the users it
 registered on the first run already exist.  The session-scoped fixture below
 truncates all application tables once before the first test, making the suite
 re-runnable.
 Truncation order doesn't strictly matter because ``CASCADE`` follows foreign
 keys, but the tables are listed explicitly for clarity.
 """
 import asyncio
 import pytest
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import create_async_engine
 from app.config import settings
 TEST_TABLES = ("assets", "worlds", "sessions", "refresh_tokens", "users")
@pytest.fixture(scope="session", autouse=True)
 def _reset_database():
    """Truncate all application tables once per test session."""
    async def _truncate() -> None:
        engine = create_async_engine(settings.DATABASE_URL)
        async with engine.begin() as conn:
            await conn.execute(
                text(f"TRUNCATE TABLE {', '.join(TEST_TABLES)} CASCADE")
            )
        await engine.dispose()
    asyncio.run(_truncate())
    yield
@@ -1,94 +0,0 @@
 """Tests for the 18+ age gate on user registration."""
 from datetime import date, timedelta
 import pytest
 from app.routers.auth import calculate_age
 class TestCalculateAge:
    """Unit tests for the calculate_age helper."""
    def test_exactly_18(self):
        """A person born exactly 18 years ago today is 18."""
        today = date(2025, 6, 15)
        dob = today.replace(year=today.year - 18)
        assert calculate_age(dob, today=today) == 18
    def test_just_turned_18(self):
        """A person who turned 18 yesterday is 18."""
        today = date(2025, 6, 15)
        dob = today.replace(year=today.year - 18) - timedelta(days=1)
        assert calculate_age(dob, today=today) == 18
    def test_one_day_short_of_18(self):
        """A person born one day after their 18th birthday is 17."""
        today = date(2025, 6, 15)
        dob = today.replace(year=today.year - 18) + timedelta(days=1)
        assert calculate_age(dob, today=today) == 17
    def test_17_years_old(self):
        """A person who is 17 years old today is 17."""
        today = date(2025, 6, 15)
        dob = date(2008, 6, 15)
        assert calculate_age(dob, today=today) == 17
    def test_65_years_old(self):
        """A person who is 65 is correctly calculated."""
        today = date(2025, 6, 15)
        dob = today.replace(year=today.year - 65)
        assert calculate_age(dob, today=today) == 65
    def test_newborn(self):
        """A newborn is 0."""
        today = date(2025, 6, 15)
        dob = today
        assert calculate_age(dob, today=today) == 0
    def test_birthday_not_yet_this_year(self):
        """Person born Dec 31, 2000 — on Jan 1, 2025 they are still 24."""
        dob = date(2000, 12, 31)
        assert calculate_age(dob, today=date(2025, 1, 1)) == 24
    def test_birthday_today(self):
        """Person born Dec 31, 2000 — on Dec 31, 2024 they turn 24."""
        dob = date(2000, 12, 31)
        assert calculate_age(dob, today=date(2024, 12, 31)) == 24
 class TestRegisterRequestDateValidation:
    """Tests for the RegisterRequest date_of_birth field validator."""
    @pytest.mark.parametrize(
        "dob",
        [
            "2000-01-01",
            "1990-12-31",
            "2004-02-29",  # leap day
        ],
    )
    def test_valid_dates(self, dob):
        """Valid YYYY-MM-DD dates pass validation."""
        from app.routers.auth import RegisterRequest
        req = RegisterRequest(username="u", email="u@example.com", password="p", date_of_birth=dob)
        assert req.date_of_birth == dob
    @pytest.mark.parametrize(
        "dob",
        [
            "01-01-2000",
            "2000/01/01",
            "2000-13-01",
            "2000-00-10",
            "not-a-date",
            "",
        ],
    )
    def test_invalid_dates_rejected(self, dob):
        """Invalid dates are rejected by the validator."""
        from app.routers.auth import RegisterRequest
        with pytest.raises(ValueError):
            RegisterRequest(username="u", email="u@example.com", password="p", date_of_birth=dob)
@@ -1,263 +0,0 @@
 """Integration tests for the auth endpoints (register + login).
 These tests hit the real FastAPI app against the real configured database
 (DATABASE_URL -- Postgres via Alembic migrations in CI/dev, not an isolated
 in-memory DB), so they exercise the full stack: Pydantic validation → DB →
 JWT → response. Requires migrations already applied (alembic upgrade head)
 before running.
 """
 import pytest
 from fastapi.testclient import TestClient
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlalchemy.pool import NullPool
 from app.config import settings
 from app.main import app
 from app.database import get_db
 from app.routers.auth import pwd_context
 # ---------------------------------------------------------------------------
 # Test fixtures
 # ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
 def _override_db():
    """Override get_db so the app uses a fresh session per test.
    Deliberately does NOT reuse app.database's shared engine: FastAPI's
    (sync) TestClient runs each request through anyio's blocking-portal
    machinery, which can hand different requests different event loops.
    asyncpg connections are bound to the loop they were created on, so
    reusing one from the shared engine's connection pool across requests
    raises "cannot perform operation: another operation is in progress" the
    moment a test makes more than one request (register-then-login,
    register-twice, etc.) -- confirmed this is the actual cause, not a bug
    in the endpoints themselves. NullPool sidesteps it: every checkout is a
    brand-new connection, never handed to a different loop than the one
    that opened it.
    """
    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
    async def _get_db():
        async_session = test_session_factory()
        try:
            yield async_session
            await async_session.commit()
        except Exception:
            await async_session.rollback()
            raise
        finally:
            await async_session.close()
    app.dependency_overrides[get_db] = _get_db
    yield
    app.dependency_overrides.clear()
 # ---------------------------------------------------------------------------
 # Register endpoint
 # ---------------------------------------------------------------------------
 class TestRegister:
    """Tests for POST /api/auth/register."""
    def test_register_success(self):
        """A valid registration returns 201 with a token."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/register",
            json={
                "username": "newuser",
                "email": "new@example.com",
                "password": "secret123",
                "date_of_birth": "2000-01-01",
            },
        )
        assert resp.status_code == 201
        data = resp.json()
        assert "access_token" in data
        assert data["token_type"] == "bearer"
    def test_register_rejects_underage(self):
        """Users under 18 get a 400 with a detail message."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/register",
            json={
                "username": "kid",
                "email": "kid@example.com",
                "password": "secret123",
                "date_of_birth": "2010-06-15",  # ~15 years old
            },
        )
        assert resp.status_code == 400
        assert "18 or older" in resp.json()["detail"]
    def test_register_rejects_duplicate_username(self):
        """Registering the same username twice returns 409."""
        client = TestClient(app)
        # First registration
        client.post(
            "/api/auth/register",
            json={
                "username": "duplicate",
                "email": "dup1@example.com",
                "password": "secret123",
                "date_of_birth": "2000-01-01",
            },
        )
        # Second registration with same username, different email
        resp = client.post(
            "/api/auth/register",
            json={
                "username": "duplicate",
                "email": "dup2@example.com",
                "password": "secret123",
                "date_of_birth": "2000-01-01",
            },
        )
        assert resp.status_code == 409
        assert "Username already registered" in resp.json()["detail"]
    def test_register_rejects_duplicate_email(self):
        """Registering the same email twice returns 409."""
        client = TestClient(app)
        client.post(
            "/api/auth/register",
            json={
                "username": "user1",
                "email": "same@example.com",
                "password": "secret123",
                "date_of_birth": "2000-01-01",
            },
        )
        resp = client.post(
            "/api/auth/register",
            json={
                "username": "user2",
                "email": "same@example.com",
                "password": "secret123",
                "date_of_birth": "2000-01-01",
            },
        )
        assert resp.status_code == 409
        assert "Email already registered" in resp.json()["detail"]
    def test_register_invalid_date_format(self):
        """Invalid date format returns 422 validation error."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/register",
            json={
                "username": "user",
                "email": "user@example.com",
                "password": "secret123",
                "date_of_birth": "01-01-2000",  # wrong format
            },
        )
        assert resp.status_code == 422
    def test_register_exactly_18(self):
        """A user who just turned 18 can register."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/register",
            json={
                "username": "just18",
                "email": "just18@example.com",
                "password": "secret123",
                "date_of_birth": "2007-06-15",
            },
        )
        assert resp.status_code == 201
 # ---------------------------------------------------------------------------
 # Login endpoint
 # ---------------------------------------------------------------------------
 class TestLogin:
    """Tests for POST /api/auth/login."""
    def _create_user(self, username: str, password: str, email: str = None):
        """Helper to create a user via register."""
        client = TestClient(app)
        if email is None:
            email = f"{username}@example.com"
        resp = client.post(
            "/api/auth/register",
            json={
                "username": username,
                "email": email,
                "password": password,
                "date_of_birth": "2000-01-01",
            },
        )
        assert resp.status_code == 201
        return resp.json()["access_token"]
    def test_login_success(self):
        """Correct credentials return a token."""
        self._create_user("loginuser", "correctpass")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/login",
            data={"username": "loginuser", "password": "correctpass"},
        )
        assert resp.status_code == 200
        data = resp.json()
        assert "access_token" in data
        assert data["token_type"] == "bearer"
    def test_login_wrong_password(self):
        """Wrong password returns 401."""
        # Distinct username from test_login_success -- there's no per-test
        # DB rollback/isolation here (real Postgres via the app's own
        # dependency-overridden session), so reusing "loginuser" collided
        # with the user that test already created (409 on register instead
        # of the intended 401-on-login assertion this test is actually for).
        self._create_user("loginuser_wrongpass", "correctpass")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/login",
            data={"username": "loginuser_wrongpass", "password": "wrongpass"},
        )
        assert resp.status_code == 401
        assert "Incorrect username or password" in resp.json()["detail"]
    def test_login_nonexistent_user(self):
        """Non-existent user returns 401 (not 404)."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/login",
            data={"username": "nobody", "password": "any"},
        )
        assert resp.status_code == 401
        assert "Incorrect username or password" in resp.json()["detail"]
    def test_login_accepts_form_encoded(self):
        """Login accepts application/x-www-form-urlencoded (OAuth2)."""
        self._create_user("formuser", "formpass")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/login",
            data={"username": "formuser", "password": "formpass"},
        )
        assert resp.status_code == 200
        assert "access_token" in resp.json()
    def test_login_token_is_valid_jwt(self):
        """The returned token is a valid JWT that can be decoded."""
        self._create_user("jwttoken", "jwt123")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/login",
            data={"username": "jwttoken", "password": "jwt123"},
        )
        token = resp.json()["access_token"]
        # Verify it's a 3-part JWT
        parts = token.split(".")
        assert len(parts) == 3
@@ -1,171 +0,0 @@
 """Tests for expired-token rejection across auth endpoints.
 Covers two distinct expiry paths:
 1. An *access* JWT whose ``exp`` claim is in the past must be rejected
   with 401 by ``GET /api/auth/me`` (jose's built-in ``exp`` validation).
 2. A *refresh* token whose persisted ``expires_at`` is in the past must be
   rejected with 401 by ``POST /api/auth/refresh`` even though its JWT
   signature is still valid.
 Requires migrations already applied (alembic upgrade head) before running.
 """
 import asyncio
 from datetime import datetime, timedelta, timezone
 import pytest
 from fastapi.testclient import TestClient
 from jose import jwt
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlalchemy.pool import NullPool
 from app.config import settings
 from app.main import app
 from app.database import get_db
 from app.models.session import RefreshToken
 # ---------------------------------------------------------------------------
 # Test fixtures
 # ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
 def _override_db():
    """Override get_db so the app uses a fresh session per test."""
    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
    async def _get_db():
        async_session = test_session_factory()
        try:
            yield async_session
            await async_session.commit()
        except Exception:
            await async_session.rollback()
            raise
        finally:
            await async_session.close()
    app.dependency_overrides[get_db] = _get_db
    yield
    app.dependency_overrides.clear()
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 def _mint_access_token(exp: datetime) -> str:
    """Mint an RS256 access token with an explicit ``exp`` claim."""
    return jwt.encode(
        {"sub": "1", "exp": exp},
        settings.private_pem,
        algorithm=settings.ALGORITHM,
    )
 def _expire_refresh_token_in_db(token: str) -> None:
    """Set the persisted refresh token's ``expires_at`` into the past."""
    async def _do():
        engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
        session_factory = async_sessionmaker(engine, expire_on_commit=False)
        async with session_factory() as session:
            from sqlalchemy import update
            await session.execute(
                update(RefreshToken)
                .where(RefreshToken.token == token)
                .values(expires_at=datetime.now(timezone.utc) - timedelta(hours=1))
            )
            await session.commit()
        await engine.dispose()
    asyncio.run(_do())
 def _register_user(client: TestClient, username: str) -> str:
    """Register a user and return its refresh token."""
    resp = client.post(
        "/api/auth/register",
        json={
            "username": username,
            "email": f"{username}@example.com",
            "password": "secret123",
            "date_of_birth": "2000-01-01",
        },
    )
    assert resp.status_code == 201
    return resp.json()["refresh_token"]
 # ---------------------------------------------------------------------------
 # Expired access token (GET /api/auth/me)
 # ---------------------------------------------------------------------------
 class TestExpiredAccessToken:
    def test_expired_access_token_is_rejected_by_me(self):
        """An access JWT with a past exp claim returns 401 on /me."""
        client = TestClient(app)
        expired_token = _mint_access_token(
            datetime.now(timezone.utc) - timedelta(minutes=5)
        )
        resp = client.get(
            "/api/auth/me",
            headers={"Authorization": f"Bearer {expired_token}"},
        )
        assert resp.status_code == 401
        assert "Could not validate credentials" in resp.json()["detail"]
    def test_garbage_access_token_is_rejected_by_me(self):
        """A non-JWT bearer token returns 401 on /me."""
        client = TestClient(app)
        resp = client.get(
            "/api/auth/me",
            headers={"Authorization": "Bearer not-a-real-jwt"},
        )
        assert resp.status_code == 401
    def test_missing_bearer_token_returns_401(self):
        """No Authorization header at all returns 401 on /me."""
        client = TestClient(app)
        resp = client.get("/api/auth/me")
        assert resp.status_code == 401
 # ---------------------------------------------------------------------------
 # Expired refresh token (POST /api/auth/refresh)
 # ---------------------------------------------------------------------------
 class TestExpiredRefreshToken:
    def test_expired_refresh_token_is_rejected(self):
        """A refresh token whose DB expires_at is in the past returns 401."""
        client = TestClient(app)
        refresh_token = _register_user(client, "expired_rt_user")
        # Force the persisted record to be expired while its JWT signature
        # is still valid.
        _expire_refresh_token_in_db(refresh_token)
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp.status_code == 401
        assert "Invalid or expired refresh token" in resp.json()["detail"]
    def test_expired_refresh_token_jwt_is_rejected(self):
        """A refresh JWT with a past exp claim is rejected before DB lookup."""
        client = TestClient(app)
        expired_jwt = jwt.encode(
            {"sub": "1", "exp": datetime.now(timezone.utc) - timedelta(minutes=5)},
            settings.private_pem,
            algorithm=settings.ALGORITHM,
        )
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": expired_jwt},
        )
        assert resp.status_code == 401
        assert "Invalid or expired refresh token" in resp.json()["detail"]
@@ -1,220 +0,0 @@
 """Tests for the lightweight glTF metadata extraction service."""
 import json
 import struct
 import pytest
 from app.services.gltf import (
    extract_gltf_metadata,
    looks_like_gltf,
    _parse_glb,
    _parse_gltf_json,
 )
 # ---------------------------------------------------------------------------
 # Test data helpers
 # ---------------------------------------------------------------------------
 def _make_gltf_json(
    meshes: int = 1,
    vertices_per_mesh: int = 24,
    has_animations: bool = False,
    images: list[dict] | None = None,
 ) -> dict:
    """Build a minimal glTF JSON structure."""
    accessors = []
    meshes_data = []
    for i in range(meshes):
        acc_index = len(accessors)
        accessors.append({
            "bufferView": 0,
            "componentType": 5126,  # FLOAT
            "count": vertices_per_mesh,
            "type": "VEC3",
            "max": [1.0, 1.0, 1.0],
            "min": [-1.0, -1.0, -1.0],
        })
        meshes_data.append({
            "primitives": [{
                "attributes": {"POSITION": acc_index},
            }],
        })
    gltf = {
        "asset": {"version": "2.0"},
        "accessors": accessors,
        "meshes": meshes_data,
    }
    if has_animations:
        gltf["animations"] = [{"name": "anim1", "channels": [], "samplers": []}]
    if images:
        gltf["images"] = images
    return gltf
 def _make_glb(gltf_json: dict) -> bytes:
    """Wrap *gltf_json* in a minimal GLB binary container."""
    json_bytes = json.dumps(gltf_json).encode("utf-8")
    json_length = len(json_bytes)
    # Pad JSON chunk to 4-byte boundary.
    json_padding = (4 - json_length % 4) % 4
    json_chunk = json_bytes + b"\x00" * json_padding
    json_chunk_type = 0x4E4F534A  # "JSON"
    # No BIN chunk.
    bin_length = 0
    bin_chunk_type = 0x004E4942
    total_length = 12 + 8 + len(json_chunk) + 8 + bin_length
    header = struct.pack("<III", 0x46546C67, 2, total_length)  # magic, version, length
    json_header = struct.pack("<II", len(json_chunk), json_chunk_type)
    if bin_length > 0:
        bin_header = struct.pack("<II", bin_length, bin_chunk_type)
    else:
        bin_header = b""
    return header + json_header + json_chunk + bin_header
 # ---------------------------------------------------------------------------
 # looks_like_gltf
 # ---------------------------------------------------------------------------
 class TestLooksLikeGltf:
    def test_glb_magic(self):
        assert looks_like_gltf(b"glTF\x00\x00\x00\x00") is True
    def test_gltf_extension(self):
        assert looks_like_gltf(b'{"asset":{"version":"2.0"}}', "model.gltf") is True
    def test_glb_extension(self):
        assert looks_like_gltf(b"some binary", "model.glb") is True
    def test_json_with_asset_version(self):
        payload = json.dumps({"asset": {"version": "2.0"}}).encode()
        assert looks_like_gltf(payload) is True
    def test_plain_json_no_asset(self):
        payload = json.dumps({"foo": "bar"}).encode()
        assert looks_like_gltf(payload) is False
    def test_non_json_bytes(self):
        assert looks_like_gltf(b"\x89PNG\r\n\x1a\n") is False
 # ---------------------------------------------------------------------------
 # _parse_glb
 # ---------------------------------------------------------------------------
 class TestParseGlb:
    def test_parses_valid_glb(self):
        gltf_json = _make_gltf_json()
        glb = _make_glb(gltf_json)
        result = _parse_glb(glb)
        assert result["asset"]["version"] == "2.0"
        assert len(result["meshes"]) == 1
    def test_rejects_too_short(self):
        with pytest.raises(ValueError, match="too short"):
            _parse_glb(b"glTF\x00\x00")
    def test_rejects_invalid_magic(self):
        with pytest.raises(ValueError, match="invalid GLB magic"):
            _parse_glb(b"NOTglTF\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00")
 # ---------------------------------------------------------------------------
 # _parse_gltf_json
 # ---------------------------------------------------------------------------
 class TestParseGltfJson:
    def test_parses_valid_gltf(self):
        gltf_json = _make_gltf_json()
        result = _parse_gltf_json(json.dumps(gltf_json).encode())
        assert result["asset"]["version"] == "2.0"
    def test_rejects_non_object(self):
        with pytest.raises(ValueError, match="root must be an object"):
            _parse_gltf_json(b"[1, 2, 3]")
 # ---------------------------------------------------------------------------
 # extract_gltf_metadata  (GLB path)
 # ---------------------------------------------------------------------------
 class TestExtractGltfMetadataGlb:
    def test_basic_glb(self):
        gltf_json = _make_gltf_json(meshes=1, vertices_per_mesh=24)
        glb = _make_glb(gltf_json)
        meta = extract_gltf_metadata(glb)
        assert meta["mesh_count"] == 1
        assert meta["vertex_count"] == 24
        assert meta["has_animation"] is False
        assert meta["bounding_box_min"] == [-1.0, -1.0, -1.0]
        assert meta["bounding_box_max"] == [1.0, 1.0, 1.0]
        assert meta["texture_refs"] == []
    def test_multiple_meshes(self):
        gltf_json = _make_gltf_json(meshes=3, vertices_per_mesh=12)
        glb = _make_glb(gltf_json)
        meta = extract_gltf_metadata(glb)
        assert meta["mesh_count"] == 3
        assert meta["vertex_count"] == 36
    def test_with_animation(self):
        gltf_json = _make_gltf_json(has_animations=True)
        glb = _make_glb(gltf_json)
        meta = extract_gltf_metadata(glb)
        assert meta["has_animation"] is True
    def test_with_external_texture(self):
        gltf_json = _make_gltf_json(images=[{"uri": "textures/rock.png"}])
        glb = _make_glb(gltf_json)
        meta = extract_gltf_metadata(glb)
        assert meta["texture_refs"] == ["textures/rock.png"]
    def test_with_named_texture(self):
        gltf_json = _make_gltf_json(images=[{"name": "my_texture"}])
        glb = _make_glb(gltf_json)
        meta = extract_gltf_metadata(glb)
        assert meta["texture_refs"] == ["my_texture"]
    def test_empty_meshes(self):
        gltf_json = _make_gltf_json(meshes=0)
        glb = _make_glb(gltf_json)
        meta = extract_gltf_metadata(glb)
        assert meta["mesh_count"] == 0
        assert meta["vertex_count"] == 0
        assert meta["bounding_box_min"] == [0.0, 0.0, 0.0]
        assert meta["bounding_box_max"] == [0.0, 0.0, 0.0]
 # ---------------------------------------------------------------------------
 # extract_gltf_metadata  (plain .gltf JSON path)
 # ---------------------------------------------------------------------------
 class TestExtractGltfMetadataGltfJson:
    def test_plain_gltf(self):
        gltf_json = _make_gltf_json(meshes=2, vertices_per_mesh=8)
        raw = json.dumps(gltf_json).encode()
        meta = extract_gltf_metadata(raw)
        assert meta["mesh_count"] == 2
        assert meta["vertex_count"] == 16
        assert meta["has_animation"] is False
    def test_plain_gltf_with_animation(self):
        gltf_json = _make_gltf_json(has_animations=True)
        raw = json.dumps(gltf_json).encode()
        meta = extract_gltf_metadata(raw)
        assert meta["has_animation"] is True
 # ---------------------------------------------------------------------------
 # Error handling
 # ---------------------------------------------------------------------------
 class TestExtractGltfMetadataErrors:
    def test_invalid_glb(self):
        with pytest.raises(ValueError):
            extract_gltf_metadata(b"not a glb")
    def test_invalid_gltf_json(self):
        with pytest.raises(ValueError):
            _parse_gltf_json(b"[1, 2, 3]")
@@ -1,201 +0,0 @@
 """Tests for the POST /api/auth/refresh endpoint.
 These tests exercise the full stack: register → get refresh token →
 refresh → new access token.  Requires migrations already applied
 (alembic upgrade head) before running.
 """
 import pytest
 from fastapi.testclient import TestClient
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
 from sqlalchemy.pool import NullPool
 from app.config import settings
 from app.main import app
 from app.database import get_db
 # ---------------------------------------------------------------------------
 # Test fixtures
 # ---------------------------------------------------------------------------
@pytest.fixture(autouse=True)
 def _override_db():
    """Override get_db so the app uses a fresh session per test."""
    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
    async def _get_db():
        async_session = test_session_factory()
        try:
            yield async_session
            await async_session.commit()
        except Exception:
            await async_session.rollback()
            raise
        finally:
            await async_session.close()
    app.dependency_overrides[get_db] = _get_db
    yield
    app.dependency_overrides.clear()
 # ---------------------------------------------------------------------------
 # Refresh endpoint tests
 # ---------------------------------------------------------------------------
 class TestRefresh:
    """Tests for POST /api/auth/refresh."""
    def _register_user(self, username: str, password: str, email: str = None):
        """Helper to register a user and return the refresh token."""
        client = TestClient(app)
        if email is None:
            email = f"{username}@example.com"
        resp = client.post(
            "/api/auth/register",
            json={
                "username": username,
                "email": email,
                "password": password,
                "date_of_birth": "2000-01-01",
            },
        )
        assert resp.status_code == 201
        return resp.json()["refresh_token"]
    def test_refresh_success(self):
        """A valid refresh token returns a new access token."""
        refresh_token = self._register_user("refep_refreshuser", "secret123")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp.status_code == 200
        data = resp.json()
        assert "access_token" in data
        assert data["token_type"] == "bearer"
        # The refresh token in the response is the same one we sent
        assert data["refresh_token"] == refresh_token
    def test_refresh_returns_different_access_token(self):
        """Refreshing produces a new access token (different from any previous)."""
        refresh_token = self._register_user("refep_refreshtoken", "secret123")
        client = TestClient(app)
        # First refresh
        resp1 = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp1.status_code == 200
        access_token_1 = resp1.json()["access_token"]
        # Second refresh
        resp2 = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp2.status_code == 200
        access_token_2 = resp2.json()["access_token"]
        # Each refresh should produce a new access token
        assert access_token_1 != access_token_2
    def test_refresh_invalid_token(self):
        """An invalid (garbage) refresh token returns 401."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": "not.a.jwt.token"},
        )
        assert resp.status_code == 401
        assert "Invalid or expired refresh token" in resp.json()["detail"]
    def test_refresh_empty_body(self):
        """Missing refresh_token field returns 422 validation error."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/refresh",
            json={},
        )
        assert resp.status_code == 422
    def test_refresh_missing_field(self):
        """No body at all returns 422."""
        client = TestClient(app)
        resp = client.post(
            "/api/auth/refresh",
            content="{}",
            headers={"Content-Type": "application/json"},
        )
        assert resp.status_code == 422
    def test_refresh_with_login_token(self):
        """A refresh token obtained from login also works for /refresh."""
        client = TestClient(app)
        # Register first
        client.post(
            "/api/auth/register",
            json={
                "username": "refep_loginrefuser",
                "email": "loginref@example.com",
                "password": "secret123",
                "date_of_birth": "2000-01-01",
            },
        )
        # Login to get a refresh token
        login_resp = client.post(
            "/api/auth/login",
            data={"username": "refep_loginrefuser", "password": "secret123"},
        )
        assert login_resp.status_code == 200
        refresh_token = login_resp.json()["refresh_token"]
        # Use it to refresh
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp.status_code == 200
        assert "access_token" in resp.json()
    def test_refresh_access_token_is_valid_jwt(self):
        """The access token returned by /refresh is a valid JWT."""
        from jose import jwt
        refresh_token = self._register_user("refep_jwttoken", "secret123")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp.status_code == 200
        access_token = resp.json()["access_token"]
        # Verify it's a 3-part JWT
        parts = access_token.split(".")
        assert len(parts) == 3
        # Verify it decodes with the public key
        payload = jwt.decode(
            access_token,
            settings.public_pem,
            algorithms=[settings.ALGORITHM],
        )
        assert "sub" in payload
        assert "exp" in payload
    def test_refresh_expires_minutes_in_response(self):
        """The response includes access_token_expires_minutes."""
        refresh_token = self._register_user("refep_expiretest", "secret123")
        client = TestClient(app)
        resp = client.post(
            "/api/auth/refresh",
            json={"refresh_token": refresh_token},
        )
        assert resp.status_code == 200
        assert "access_token_expires_minutes" in resp.json()
        assert resp.json()["access_token_expires_minutes"] == settings.ACCESS_TOKEN_EXPIRE_MINUTES
@@ -1,79 +0,0 @@
 """Tests for refresh token uniqueness (jti claim) and model column length."""
 import uuid
 from datetime import datetime, timedelta, timezone
 import pytest
 from jose import jwt
 from app.config import settings
 from app.routers.auth import _create_refresh_token
 from app.models.session import RefreshToken
 class TestRefreshTokenJtiUniqueness:
    """Verify that _create_refresh_token produces unique tokens even when
    called with identical data in rapid succession (issue #1 from review)."""
    def test_two_calls_produce_different_tokens(self):
        """Two calls with the same sub produce different JWTs because of jti."""
        token_a = _create_refresh_token({"sub": "42"})
        token_b = _create_refresh_token({"sub": "42"})
        assert token_a != token_b
    def test_jti_is_valid_uuid(self):
        """The jti claim inside the refresh token is a valid UUID."""
        token = _create_refresh_token({"sub": "1"})
        payload = jwt.decode(
            token,
            settings.public_pem,
            algorithms=[settings.ALGORITHM],
        )
        assert "jti" in payload
        # Verify it parses as a UUID (raises ValueError if not)
        uuid.UUID(payload["jti"])
    def test_each_token_has_unique_jti(self):
        """Generate 100 tokens for the same user — all jtis must differ."""
        jtis = set()
        for _ in range(100):
            token = _create_refresh_token({"sub": "999"})
            payload = jwt.decode(
                token,
                settings.public_pem,
                algorithms=[settings.ALGORITHM],
            )
            jtis.add(payload["jti"])
        assert len(jtis) == 100
    def test_jti_survives_decode(self):
        """The jti claim is present and correct after decode."""
        token = _create_refresh_token({"sub": "7"})
        payload = jwt.decode(
            token,
            settings.public_pem,
            algorithms=[settings.ALGORITHM],
        )
        assert payload["sub"] == "7"
        assert "jti" in payload
        assert "exp" in payload
 class TestRefreshTokenModelColumnLength:
    """Verify the model's token column length matches the migration (issue #2)."""
    def test_token_column_has_length_512(self):
        """RefreshToken.token column should be String(512), not unbounded."""
        from sqlalchemy import inspect
        # Get the column definition from the model's table
        column = RefreshToken.__table__.columns["token"]
        # The type should be String with length 512
        assert column.type.length == 512
    def test_token_column_type_is_string(self):
        """The token column should be a String type."""
        from sqlalchemy import String as SAString
        column = RefreshToken.__table__.columns["token"]
        assert isinstance(column.type, SAString)
@@ -1,369 +0,0 @@
 # Editor Architecture: Godot Editor Plugin vs. In-Game Editor
 > **Status:** Proposed
 > **Owner:** Platform team
 > **Related:** World chunk data format & persistence, server authority + client
 > prediction, content moderation & age verification, avatar component system
 > **Godot version:** 4.6.2 stable
 ## 1. Overview
 This document evaluates the two primary ways to build the **world/level
 authoring tool** for **agp-game**:
 - **(a) Godot editor plugin** — extend the Godot editor itself with custom
  panels, dock widgets, and tools that operate on the project's scenes and
  resources.
 - **(b) In-game editor** — a fully custom editor built as game UI (Godot
  `Control` nodes) that runs inside the running game, editing the game's own
  world data.
 The goal is to pick the approach that best fits the platform's constraints:
 a **server-authoritative** multiplayer game where the **world is stored as
 versioned chunks** (see `world.md`), content is **moderation-flagged** (see
 `content_moderation.md`), and the client is a **shipped binary** that players
 run (not a dev tool).
 This document is a **decision record**: it lays out the trade-offs, gives a
 clear recommendation, and defines the resulting architecture boundaries.
 ---
 ## 2. Context & Constraints
 Before comparing the two approaches, we must fix the constraints that drive the
 decision. These come from the existing architecture docs.
 ### 2.1 The World Is Data, Not Scenes
 `world.md` defines the world as **chunk data** (JSON for authoring, binary for
 runtime/network), persisted in SQLite on the server. A chunk is the atomic unit
 of load, save, and stream. The **server is the only writer** to the store;
 clients submit **deltas** against a `base_revision` and the server validates and
 applies them.
 **Implication:** The editor's output is **chunk payloads**, not `.tscn` scene
 files. Whatever editor we build must serialize to the chunk contract, not to
 Godot scene resources.
 ### 2.2 Server-Authoritative & Moderation-Aware
 - The server validates every edit (schema, bounds, moderation) before
  persisting (`world.md` §5.4).
 - Content carries **content flags** aggregated from referenced assets/scripts
  (`content_moderation.md` §3). Mature content is gated behind age verification.
 - The client receives a **content manifest** and never loads content not in it.
 **Implication:** An editor that runs on a **player's machine** cannot be the
 authority on what gets published. Editing must go through the server's
 validation pipeline, and the editor must surface moderation flags.
 ### 2.3 The Client Is a Shipped Binary
 The game is a multiplayer product. Players run a **release build**. The Godot
 editor is a **development tool** that players do not have.
 **Implication:** If authoring is a first-class *player* feature (user-generated
 content), the editor must ship inside the game binary. If authoring is a
 *developer/platform* feature, it can live in the editor.
 ### 2.4 Two Distinct Audiences
 The evaluation must separate two audiences, because they have opposite needs:
 | Audience | Who | Where they run | What they build |
 |----------|-----|----------------|-----------------|
 | **Platform/dev** | The team building the game | Godot editor (dev machines) | Base worlds, rooms, templates, test levels |
 | **Players (UGC)** | End users | The shipped game | Their own rooms/worlds, published to the server |
 The two approaches map cleanly onto these audiences, and the right answer is
 likely **both** — but with a clear primary recommendation.
 ---
 ## 3. Approach (a): Godot Editor Plugin
 ### 3.1 What It Is
 A Godot editor plugin is a set of scripts (and optionally scenes) that extend
 the editor via the `EditorPlugin` API. It can add:
 - **Dock panels** (`add_control_to_dock`) — e.g., a chunk/tile palette panel.
 - **Toolbar buttons** (`add_control_to_container`).
 - **Inspector plugins** (`EditorInspectorPlugin`) — custom property editors.
 - **Import plugins** (`EditorImportPlugin`) — custom asset importers.
 - **Scene/Node plugins** (`EditorNode3DGizmoPlugin`) — custom gizmos.
 - **Menu entries** (`add_tool_menu_item`).
 Plugins are enabled per-project via `project.godot` (`[editor_plugins]`).
 ### 3.2 Pros
 - **Full editor power for free:** You get the scene tree, inspector, viewport
  navigation, undo/redo, gizmos, and asset pipeline — all battle-tested.
 - **Native Godot editing:** Editing `.tscn` scenes, materials, and nodes is
  exactly what the editor is built for. Great for authoring **base content**
  (rooms, templates, avatar base bodies).
 - **Fast iteration for devs:** The platform team can build and test levels
  directly in the tool they already use.
 - **Undo/redo, selection, snapping** come from the editor's `EditorUndoRedoManager`.
 - **No runtime footprint:** Editor-only code is stripped from export builds
  (`@tool` scripts and editor plugins are not shipped to players).
 ### 3.3 Cons
 - **Not available to players.** Players don't run the Godot editor. Any
  player-facing UGC authoring cannot use this approach.
 - **Tied to the editor's UX.** You inherit the editor's look and interaction
  model; deep customization is limited by what the editor API exposes.
 - **Editor API churn.** `EditorPlugin` APIs change between Godot versions;
  plugins are more brittle across upgrades than game code.
 - **Scene-centric, not data-centric.** The editor is optimized for scenes and
  resources. Our world is **chunk data** (`world.md`). We'd have to build a
  translation layer (scene ↔ chunk) and keep it in sync — a real source of
  drift.
 - **Single-user, local.** The editor edits local files. It does not natively
  talk to our server-authoritative chunk store or the moderation pipeline.
 - **Headless/CI friction.** Validating plugin behavior in CI requires running
  the editor headless, which is heavier than testing game code.
 ### 3.4 Fit for Our Constraints
 - **Platform/dev authoring:** Excellent. This is the natural home for building
  base worlds, rooms, and templates.
 - **Player UGC:** Not applicable. Players cannot run the editor.
 - **Server-authoritative chunk store:** Poor fit natively. The editor edits
  local scenes; we'd bolt on a chunk export/import and a server sync layer.
 ---
 ## 4. Approach (b): In-Game Editor
 ### 4.1 What It Is
 A fully custom editor built as **game UI** — Godot `Control` nodes (panels,
 buttons, toolbars) that run inside the running game. It edits the game's own
 world data model (chunks) and submits edits through the normal server pipeline.
 ### 4.2 Pros
 - **Ships to players.** The editor is part of the game binary, so **player UGC
  authoring is possible** — the core requirement for a user-generated-content
  platform.
 - **Data-native.** The editor operates directly on the **chunk model**
  (`world.md`), so there is no scene↔chunk translation layer and no drift.
 - **Server-authoritative by construction.** Edits go through the same
  `request_chunk_edit` RPCs as gameplay, so validation, revisioning, and
  moderation apply uniformly. The editor cannot bypass the server.
 - **Moderation-aware.** Because edits flow through the server, content flags are
  computed and enforced at the boundary (`content_moderation.md` §4). The editor
  can surface flags and gate mature content.
 - **One codebase, one UX.** The editor uses the same UI toolkit and art style as
  the game; no separate editor theme to maintain.
 - **Testable in CI.** The editor is ordinary game code; it can be exercised
  headlessly and unit-tested like any other system.
 ### 4.3 Cons
 - **We build everything.** No free scene tree, inspector, gizmos, or undo/redo.
  We must implement selection, snapping, undo/redo, viewport navigation, and
  property editing ourselves.
 - **Runtime footprint.** Editor UI ships in the binary (though it can be gated
  behind a feature flag / separate scene that is only instantiated on demand).
 - **More upfront work.** A usable in-game editor is a large feature; it needs
  its own architecture (tool modes, gizmos, palette, inspector).
 - **Not ideal for deep asset authoring.** Modeling a mesh or authoring a
  material is better done in the Godot editor / DCC tools. The in-game editor
  should focus on **world composition** (placing tiles and objects), not asset
  creation.
 ### 4.4 Fit for Our Constraints
 - **Platform/dev authoring:** Workable but not ideal for deep asset work.
 - **Player UGC:** The **only** viable approach. Players can only author through
  the shipped game.
 - **Server-authoritative chunk store:** Excellent fit. The editor is a client
  that submits validated deltas.
 ---
 ## 5. Comparison Matrix
 | Criterion | (a) Editor plugin | (b) In-game editor |
 |-----------|-------------------|--------------------|
 | Ships to players | ❌ No | ✅ Yes |
 | Player UGC authoring | ❌ Impossible | ✅ Core capability |
 | World data model fit | ⚠️ Scene-centric; needs translation layer | ✅ Chunk-native |
 | Server-authoritative edits | ⚠️ Bolted on | ✅ Native (same RPCs) |
 | Moderation enforcement | ⚠️ Manual | ✅ At the boundary |
 | Free editor features (undo, gizmos, inspector) | ✅ Rich | ❌ Build ourselves |
 | Runtime footprint | ✅ None (stripped from export) | ⚠️ Ships in binary (gated) |
 | Dev iteration speed | ✅ Fast | ⚠️ Slower to build |
 | Deep asset authoring (mesh/material) | ✅ Native | ❌ Out of scope |
 | CI testability | ⚠️ Heavier (headless editor) | ✅ Ordinary game code |
 | Editor API churn risk | ⚠️ Higher | ✅ None (game code) |
 ---
 ## 6. Recommendation
 **Primary recommendation: build the in-game editor (b) as the platform's
 authoring surface, and use a lightweight Godot editor plugin (a) only as an
 internal dev convenience.**
 ### 6.1 Rationale
 1. **Player UGC is the deciding factor.** The platform's value proposition is
   user-generated content (rooms, worlds, avatars). Players cannot run the Godot
   editor, so **only an in-game editor can deliver player authoring**. This is a
   hard requirement that the editor-plugin approach cannot meet.
 2. **The world is data, and the in-game editor is data-native.** `world.md`
   defines chunks as the atomic unit. An in-game editor edits chunks directly
   and submits them through the server pipeline. An editor plugin would force a
   scene↔chunk translation layer that is a constant source of drift and bugs.
 3. **Server authority and moderation fall out naturally.** Because in-game
   edits use the same `request_chunk_edit` RPCs as gameplay, validation,
   revisioning, optimistic concurrency, and content-flag enforcement
   (`content_moderation.md`) apply uniformly. The editor cannot bypass the
   server — which is exactly what a moderation-aware UGC platform needs.
 4. **The editor-plugin's strengths are not what we need.** Its free features
   (scene tree, inspector, gizmos) are for editing Godot scenes and resources.
   Our authoring is world composition against a chunk contract, not scene
   editing. The plugin's main win — deep asset authoring — is better served by
   DCC tools and the Godot editor for the *platform team*, not by a plugin we
   must maintain.
 ### 6.2 The Role of the Editor Plugin (Dev Convenience Only)
 We still recommend a **small, optional** editor plugin for the **platform team**
 to author **base content** (base rooms, templates, avatar base bodies, test
 levels) directly in the Godot editor. This is a dev-time convenience, not a
 product feature:
 - It can export a scene/resource as a **chunk** (reusing the same encoder as the
  in-game editor) so dev-authored content flows into the same pipeline.
 - It is **not shipped** to players and is **not** the authoring surface for UGC.
 - It should be kept thin to minimize editor-API churn risk.
 ### 6.3 Scope Boundary
 To keep the in-game editor tractable, define its scope clearly:
 - **In scope (world composition):** placing tiles, placing static/dynamic
  objects, setting transforms, editing object properties, saving/loading chunks,
  submitting edits to the server, showing moderation flags.
 - **Out of scope (asset creation):** modeling meshes, authoring materials,
  rigging avatars. These are done in DCC tools / the Godot editor and imported
  as catalog assets (see `avatar.md` §7). The in-game editor **references**
  catalog assets by id; it does not create them.
 ---
 ## 7. Resulting Architecture
 ### 7.1 Shared Editor Core
 Both the in-game editor and the (optional) dev plugin should share a single
 **editor core** that operates on the chunk model. This avoids two divergent
 implementations.
 ```
 EditorCore (shared, data-native)
 ├── ChunkEditorModel      # in-memory chunk being edited (tiles, objects, flags)
 ├── ChunkEncoder          # JSON/binary encode/decode (world.md §3)
 ├── EditSession           # base_revision tracking, delta generation
 ├── EditSubmitter         # request_chunk_edit RPC wrapper + conflict handling
 ├── UndoRedoStack         # command pattern over chunk mutations
 ├── SelectionManager      # selected tiles/objects
 ├── ToolRegistry          # brush, object-place, select, erase, etc.
 └── ModerationView        # surfaces content flags; gates mature content
 ```
 ### 7.2 In-Game Editor (Primary)
 ```
 InGameEditor (Control-based UI, shipped in binary, gated by feature flag)
 ├── EditorViewport        # custom 2D/3D viewport with camera navigation
 ├── Toolbar               # tool mode switcher
 ├── PalettePanel          # tile/object palette (from catalog)
 ├── InspectorPanel        # property editor for selected object
 ├── ChunkBrowser          # load/save chunks, list rooms
 └── EditorCore            # shared core (above)
 ```
 - Instantiated only when the player enters "build mode" (a separate scene /
  feature flag), so the runtime footprint is negligible during normal play.
 - Submits edits via `request_chunk_edit`; handles `chunk_edit_result` conflicts
  by re-fetching and re-applying (`world.md` §5.4).
 ### 7.3 Dev Editor Plugin (Optional, Thin)
 ```
 DevChunkPlugin (EditorPlugin, dev-only, not shipped)
 ├── Dock panel: "Chunk Export"
 ├── Reads the current scene / selected nodes
 ├── Maps scene content → chunk model (via EditorCore.ChunkEncoder)
 └── Exports a .chunk.json / submits to a dev server
 ```
 Kept thin to minimize editor-API churn. Its only job is to let the platform team
 author base content in the editor and push it into the same chunk pipeline.
 ### 7.4 Data Flow
 ```
 [In-game editor]  --request_chunk_edit(delta, base_revision)-->  [Server]
        ^                                                          | validate
        |                                                          | apply
        +--chunk_edit_result(ok/new_revision | conflict)-----------| persist
                                                                   v
                                                              SQLite (world.db)
 [Dev plugin]  --export chunk JSON-->  [EditorCore.ChunkEncoder]  -->  [Server]
 ```
 Both paths converge on the **same server validation pipeline**, so moderation
 and revisioning are uniform regardless of authoring surface.
 ---
 ## 8. Risks & Mitigations
 | Risk | Mitigation |
 |------|------------|
 | In-game editor is a large build | Scope it to world composition (§6.3); reuse EditorCore; ship behind a feature flag |
 | Custom viewport/gizmos are hard | Start with a 2D tile editor (matches `CHUNK_SIZE_Z=1` default); add 3D later |
 | Undo/redo complexity | Use a command pattern over chunk mutations; test headlessly |
 | Editor-plugin API churn | Keep the plugin thin; treat it as dev-only convenience, not a product surface |
 | Drift between dev plugin and in-game editor | Both use the same `EditorCore`/`ChunkEncoder` |
 | Players bypass moderation | Impossible by construction: edits go through server validation |
 ---
 ## 9. Open Questions / Future Work
 - **3D editing:** The default world is flat (`CHUNK_SIZE_Z=1`). A 3D in-game
  editor (volumetric chunks) is future work (`world.md` §8).
 - **Collaborative editing:** Multiple players editing the same chunk concurrently
  — the optimistic-concurrency model already supports it, but the UX (live
  cursors, conflict resolution) is unspecified.
 - **Template library:** A curated set of room templates players can start from.
 - **Publish/review flow:** How a player's authored room enters the moderation
  review queue (`content_moderation.md` §6) and becomes publicly joinable.
 ---
 ## 10. Summary
 | Concern | Decision |
 |---------|----------|
 | Primary authoring surface | **In-game editor** (ships to players, enables UGC) |
 | Dev authoring convenience | Thin, optional **editor plugin** (not shipped) |
 | World data model | Both operate on the **chunk model** via a shared `EditorCore` |
 | Server authority | Edits go through `request_chunk_edit`; server validates |
 | Moderation | Enforced at the server boundary for both paths |
 | In-game editor scope | World composition only; asset creation is out of scope |
 | Runtime footprint | Editor gated behind a feature flag / separate scene |
@@ -1,159 +0,0 @@
 # GDScript Sandboxing for User-Written Scripts
 > **Status:** Proposed
 > **Owner:** Platform team
 > **Related:** Content moderation & age verification (scripts are one of the
 > three moderated content types), avatar component system
 ## 1. Overview
 This document evaluates how to safely run **user-written scripts** as part of
 UGC (user-generated content) in **agp-game**, and recommends an approach.
 **Bottom line: Godot 4 has no built-in security sandbox for GDScript, and
 none of the three options named in the original task hold up under testing.**
 A script running anywhere inside the Godot process — however it's loaded,
 parented, or wrapped — runs with full engine privileges: arbitrary process
 execution, full filesystem read/write, and raw network access. Sandboxing
 has to happen *outside* the scripting language, not through an in-engine
 restriction mechanism, because no such mechanism exists.
 This was verified directly against Godot 4.6.2 (`godot --headless`, evidence
 in `sandbox_probe/` on this branch) rather than assumed from documentation,
 some of which (see §2.1) describes APIs that don't actually exist in this
 version.
 ## 2. Options Evaluated
 ### 2.1 Godot's built-in "ScriptServer" restrictions — does not exist
 There is no `ScriptServer` class in Godot 4.6.2:
 ```
 ClassDB.class_exists("ScriptServer")  →  false
 ```
 There's also no project setting to disable engine subsystems for scripts —
 none of `application/run/disable_os`, `disable_file_access`, or
 `disable_network` exist as settings, and `ProjectSettings.get_property_list()`
 returns nothing matching "sandbox", "restrict", or "security". Any plan that
 assumes a flag like this exists needs to be dropped; it was likely conflated
 with sandboxing features from a different engine/scripting ecosystem, or
 with **export template stripping** (which controls what ships in a build,
 not what a script can call at runtime).
 Directly probed capabilities of an ordinary GDScript running as a normal
 node script, no special setup:
 | Capability | Available to any script? |
 |---|---|
 | `OS.execute(...)` — run arbitrary processes | ✅ Yes |
 | `FileAccess.open(...)` — read/write any path the OS user can reach | ✅ Yes (read `/etc/hostname`, write `/tmp/...` both succeeded) |
 | `TCPServer` / `HTTPClient` / `HTTPRequest` / `PacketPeerUDP` / `WebSocketPeer` | ✅ All instantiate and work |
 | `ClassDB.instantiate(...)` — construct any engine class by name | ✅ Yes |
 | Loading and running a second script from source text at runtime (`GDScript.new()` + `.reload()`) | ✅ Yes |
 **Verdict: rejected.** There is nothing to configure here — the restriction
 surface this option assumed doesn't exist in the engine.
 ### 2.2 Isolated SubViewport with a limited API — doesn't isolate scripts
 `SubViewport` is a **rendering and input isolation** primitive (it gives a
 scene subtree its own render target and can gate input propagation) — it is
 not a security or scripting boundary. A script attached to any node inside a
 `SubViewport` still runs in the same process, on the same GDScript VM, with
 the exact same access to `OS`, `FileAccess`, networking classes, and
 `ClassDB` as a script anywhere else in the tree. Nothing about being
 "inside" a SubViewport changes what API calls are reachable from a script.
 **Verdict: rejected.** This solves a rendering/UI-composition problem, not
 the security problem the task is asking about. Worth keeping in mind for
 other purposes (e.g. isolated preview rendering of user avatars), but it
 provides zero script sandboxing.
 ### 2.3 Custom GDScript interpreter with an allowlist — right idea, wrong layer for "custom interpreter"
 Two ways to read this option, tested separately:
 **(a) Write/embed a separate GDScript parser+interpreter.** Not
 practical — this means re-implementing (and then indefinitely maintaining,
 in lockstep with every Godot release) a full language interpreter outside
 the engine. Far more engineering than the problem justifies.
 **(b) Use Godot's built-in `Expression` class as a restricted subset.**
 `Expression` *looks* like a natural allowlist mechanism — it only evaluates
 a single expression, no control flow, no arbitrary statements. But it isn't
 safe by default: it can still reach through to unsafe engine methods if you
 aren't careful about what object you hand it as a base instance:
 ```gdscript
 var expr = Expression.new()
 expr.parse("get_environment('HOME')", ["OS"])
 expr.execute([], OS)   # → "/home/daddy"  (successfully called OS.get_environment)
 ```
 So `Expression` is a viable building block only if the host **never passes
 a base instance (or arguments) that exposes anything sensitive** — i.e. the
 allowlisting work still has to happen at the call site, `Expression` itself
 enforces none of it.
 **Static text pattern-matching (blocklisting dangerous substrings like
 `"OS.execute"` before parsing) was also probed and is not a real
 defense** — it's trivially defeated by string concatenation, `call()`,
 `Callable`, or any other indirection, and produces false confidence.
 **Verdict: partially viable, but only as a foundation, not a solution on
 its own.** A hand-built, narrow, data-driven DSL (not full GDScript, not
 raw `Expression`) with an explicit allowlist of safe operations and *no
 ability to reference engine singletons or arbitrary objects* is the only
 version of "custom interpreter" that's actually safe. This is real
 engineering effort, not a config flag.
 ## 3. Recommendation
 **Don't run untrusted GDScript in-process at all.** Given none of the three
 in-engine options provide a real boundary, the two approaches actually worth
 building are, in order of recommended priority:
 1. **Primary: a narrow, non-Turing-complete content DSL**, not general
   scripting. Most UGC scripting needs in a game like this (custom
   interactions, simple triggers, item behaviors) don't need a general
   programming language — they need a small set of declarative
   verbs/conditions (e.g. `on_interact: give_item("torch")`,
   `on_enter: play_sound("chime")`). Expressed as data (JSON/Resource, not
   code) and interpreted by trusted, hand-written GDScript on the engine
   side. This has *zero* attack surface by construction — there's no
   interpreter to escape because there's no general execution, just a
   fixed, reviewed set of verbs. This is almost certainly sufficient for
   the actual UGC use cases in this game and should be scoped against real
   feature requirements before assuming more is needed.
 2. **If genuinely general scripting becomes a hard requirement**, isolate it
   at the OS level, not the engine level: run untrusted scripts in a
   **separate process** (a stripped-down Godot instance or a dedicated
   interpreter) under OS sandboxing (a restricted user account, a
   container, or `firejail`/`bwrap`/seccomp), communicating with the main
   game over a narrow IPC/RPC boundary that only exposes intentionally-safe
   operations. This is the only approach that provides a real security
   boundary for arbitrary code, because it doesn't depend on the scripting
   language cooperating — the OS enforces it. Substantially more
   infrastructure than option 1; only worth it if option 1's DSL genuinely
   can't express what's needed.
 **Do not** attempt in-process GDScript sandboxing via SubViewport,
 ScriptServer, or ad hoc blocklisting — all three were directly tested and
 none provide a real boundary (§2).
 ## 4. Open Questions
 - What do actual planned UGC scripts need to *do*? (Trigger conditions,
  simple item/state effects, dialogue branching?) This determines whether
  the DSL in §3.1 is sufficient or whether §3.2's process isolation is
  needed. Needs a concrete feature list before implementation starts.
 - If §3.2 is needed later, does it run per-user-session or shared/pooled?
  Affects resource cost and isolation guarantees.
 - Interaction with the content moderation pipeline (`content_moderation.md`):
  scripts as a moderated content type still need a moderation flag path
  regardless of which execution model is chosen — a DSL makes static
  analysis of *what a script can possibly do* far easier than it would be
  for general code, which is an additional point in its favor.
@@ -1,41 +0,0 @@
 # MVP Vertical Slice: Client-Server Wiring — Plan
 ## Goal
 Prove the real Godot client and the real backend can talk: **a user can register/log in
 and see a list of worlds from the game client**. Nothing more. Gameplay, join-a-world,
 chat, avatar, Discovery search/tags/trending, Social/Economy/Trust & Safety are all
 explicitly out of scope.
 ## Verified backend contract (as of this writing)
 - `POST /api/auth/register` — JSON body `{username, email, password, date_of_birth}`.
  `date_of_birth` is a `YYYY-MM-DD` string. Returns `201 {access_token, token_type}`.
  Rejects under-18 with `400`.
 - `POST /api/auth/login` — OAuth2 **form-encoded** (`application/x-www-form-urlencoded`)
  `username` + `password` (this is NOT a JSON endpoint). Returns `{access_token, token_type}`.
 - `GET /api/worlds` — **requires auth** (`CurrentUser`), returns a JSON array of
  `{id, name, description, visibility, owner_id, created_at}`. There is no unauthenticated
  public-worlds path, so the worlds list screen can only be shown after login/register.
 - `GET /api/health` — unauthenticated, `{status, app}`.
 - Base URL: uvicorn default `http://127.0.0.1:8000` (must be configurable in the client).
 - CORS is irrelevant to the native Godot `HTTPRequest` client (no browser origin).
 ## Task breakdown
 | # | Type | Task | Depends on |
 |---|------|------|-----------|
 | 1 | architecture | `ApiClient` autoload: HTTP + JWT storage + error contract | — |
 | 2 | implementation | Main-menu **login + register** UI built & wired (form-encoded + JSON/age gate) | 1 |
 | 3 | implementation | **World list** screen consuming `GET /api/worlds` | 1 |
 | 4 | testing | End-to-end headless smoke test + manual verify | 1,2,3 |
 ## Design decisions captured (resolved in task 1)
 - Token storage: in-memory singleton property for the MVP; a `save_to_disk` seam is left
  open but not required yet (no re-login on restart in this slice).
 - Error contract: every call returns a discriminated result (`ok`/`error`) so callers
  never crash on network failure; non-2xx surfaces `{status, detail}` from the backend.
 - Base URL: read from a ProjectSetting, defaulting to `http://127.0.0.1:8000`.
 - Login is form-encoded; register is JSON — the client helper must support both content types.
 ## Notes
 - The main-menu auth UI does **not** exist yet (main_menu.gd currently has only Play/Quit
  stubs). Task 2 must **build** the login/register UI, not merely wire an existing one.
 - The world-list screen also needs to be **built** (a new scene), not just wired.
@@ -1,295 +0,0 @@
 # Economy — Currency, Marketplace & Creator Payouts — Plan
 > **Status:** Planned
 > **Owner:** Platform team
 > **Feature ID:** `economy`
 > **Godot version:** 4.6.2 stable
 > **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
 ## 1. Overview
 This document breaks the **Economy** feature into user stories and right-sized
 implementation tasks. The feature delivers:
 - **Virtual currency ("Credits")** — a single, server-authoritative currency
  with an immutable, append-only transaction ledger.
 - **Premium purchase** — buying Credits with real money through a pluggable
  payment-provider hook.
 - **Marketplace** — user-generated content (UGC) listings where creators sell
  items (assets, avatar items, experience passes) to players for Credits.
 - **Creator payouts** — accumulating creator earnings and paying them out to
  external accounts through a pluggable payout-provider hook.
 - **Godot client** — wallet/transaction history, marketplace browse/buy/sell,
  and creator payout screens.
 The economy is the monetization backbone of the platform. Because it moves
 virtual value between real people, correctness (no double-spend, no lost funds,
 no balance drift) and safety (fraud prevention, moderation, audit) are treated
 as **blocking requirements**, not add-ons.
 ## 2. Why correctness is the differentiator
 The platform is a creator economy (players buy UGC from other players). The
 economy is the highest-risk surface after chat: a single arithmetic or
 concurrency bug can mint or destroy value and irreversibly erode trust.
 Correctness is therefore designed in from the start:
 - **One currency, integer units.** Credits are whole-number integers. There are
  no floats, no rounding, and no client-computed totals.
 - **Append-only ledger.** Every balance change is a row in a `transactions`
  table with a signed amount, a `balance_after` snapshot, a reference to the
  event that caused it, and an **idempotency key** so retries cannot double
  credit or double debit.
 - **Atomic, locked mutations.** Balance changes run in a single database
  transaction with row locking (`SELECT ... FOR UPDATE`) so concurrent
  purchases/payouts cannot race.
 - **Escrow hold.** Marketplace proceeds are held in `pending_escrow` for a
  configurable window before becoming available to the seller, so fraudulent
  or moderated sales can be reversed without clawing back paid-out funds.
 - **Server-authoritative fees.** The platform commission is computed
  server-side from a configured rate; the client never supplies the fee or the
  seller's net.
 ## 3. Existing constraints (do not re-build)
 - **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
  `app/dependencies.py`. All economy endpoints reuse this.
 - **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
  Existing tables: `users`, `sessions`, `worlds`, `assets`.
 - **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
  idempotency short-caching and rate limiting.
 - **Models:** `User` (owner_id), `Asset` (owner_id, is_public, asset_type).
  Marketplace items reference existing `assets` rows and/or avatar items.
 - **Content moderation:** `docs/architecture/content_moderation.md` defines
  flag vocabulary, age gate, and moderation actions. Marketplace items and
  listings must inherit and enforce these rules (see §7).
 - **Client:** Godot 4.6.2, minimal `main_menu.gd`; no economy UI yet.
 ## 4. Key design decisions
 | Concern | Decision |
 |---|---|
 | Currency model | Single virtual currency **"Credits" (CR)**, integer units. One wallet row per user; no fractional amounts. |
 | Ledger | Append-only `transactions` table: signed `amount`, `balance_after`, `reference_type`/`reference_id`, unique `idempotency_key`. |
 | Concurrency | `SELECT ... FOR UPDATE` on the wallet row inside the mutation transaction; never read-modify-write from stale data. |
 | Payments | Pluggable `PaymentProvider` interface with a **no-op default** that simulates a confirmed payment for dev/testing (clearly flagged). Stripe/PayPal later. |
 | Marketplace items | `catalog_items` (what is sold) + `marketplace_listings` (a seller's offer with a price/status). One item can have multiple listings over time. |
 | Purchase flow | Atomic transaction: debit buyer → hold funds in escrow (`pending_escrow`) → grant item. Platform fee computed server-side. |
 | Escrow | Configurable hold window (default 72h) before `pending_escrow` becomes available seller earnings. Refunds during the window reverse the sale. |
 | Fees | Single configurable `MARKETPLACE_FEE_RATE` (default `0.30`). `seller_net = floor(price * (1 - fee_rate))`. |
 | Creator balance | `creator_balances` table: `available` (earned, payable), `pending` (inside an open payout request), `lifetime_earned`. Updated in the same transaction as the sale completion. |
 | Payouts | Pluggable `PayoutProvider.pay()` with a no-op default (simulated external ref). Minimum payout threshold, admin review for large payouts. |
 | Idempotency | Every money-moving request carries a client-generated `Idempotency-Key`; duplicate keys return the original result. |
 | Rate limiting | Redis token-bucket dependency reused from the social feature for purchase/listing/payout endpoints. |
 | Moderation | Listings enforce content flags + age gate; moderators can `delist`/`remove`; fraud/chargeback reversal is an audited admin action. |
 ## 5. User stories
 ### US-1 Currency & wallet
 As a player, I can see my Credit balance and transaction history, and the system
 credits/debits my wallet only through server-authoritative events.
 **Acceptance criteria**
 - Exactly one wallet per user, created lazily on first use.
 - Balance is always a non-negative integer; no operation can make it negative.
 - Every mutation appends an immutable ledger row with amount, resulting balance,
  reference, and idempotency key.
 - Retrying a request with the same idempotency key does not double-apply.
 - `GET` endpoints expose current balance and paged transaction history.
 ### US-2 Premium purchase (buy Credits)
 As a player, I can purchase Credits with real money and have them credited only
 after the payment is confirmed.
 **Acceptance criteria**
 - A purchase session is created through the payment provider (or the no-op
  default) and is idempotent.
 - Credits are granted exactly once, only after a verified provider confirmation
  (webhook/confirm endpoint), never on client claim.
 - Purchase amounts are bounded and server-defined; clients cannot pick arbitrary
  prices.
 - Confirmation is idempotent and audited (provider reference recorded).
 ### US-3 Marketplace listing (sell)
 As a creator, I can list a catalog item for sale at a Credit price and
 manage/remove my listings.
 **Acceptance criteria**
 - A listing references a valid `catalog_item` owned by the seller (or an
  authorized seller).
 - Price is bounded (min/max) and set server-side; status transitions are
  explicit (`active`, `sold`, `delisted`, `removed_by_moderation`).
 - Only the seller (or a moderator) can update/remove a listing.
 - Listings are searchable/filterable (item type, price range, owner).
 ### US-4 Marketplace purchase (buy)
 As a player, I can buy a listed item. The purchase is atomic, holds funds in
 escrow, grants the item, and splits the payment between platform and seller.
 **Acceptance criteria**
 - A single transaction debits the buyer, holds funds in escrow, and grants the
  item — no partial states on failure.
 - Platform fee and seller net are computed server-side from the configured rate.
 - After the escrow hold window, funds move from escrow to the seller's
  available balance.
 - Refunds during the hold window reverse the sale and return funds to the buyer.
 - Concurrent purchases of a one-of-a-kind listing cannot both succeed.
 ### US-5 Creator payouts
 As a creator, I can view my earned balance, request a payout, and track its
 status; admins can review and approve/reject payouts.
 **Acceptance criteria**
 - Available balance is derived only from completed (escrow-released) sales and
  completed payouts; it never goes negative.
 - Payout requests are bounded (min threshold, max per period) and rate-limited.
 - Large payouts require admin review; all payout requests carry an audit trail
  (requested by, reviewed by, provider reference, status).
 - The payout provider is called exactly once; idempotent on retry.
 ### US-6 Godot client
 As a player, I can manage Credits, browse/buy/sell marketplace items, and manage
 payouts from the game UI.
 **Acceptance criteria**
 - An API client handles JWT auth, HTTP, and idempotency keys for all economy
  calls.
 - Dedicated screens: wallet + transaction history, marketplace browse/buy,
  sell-listing, and creator payout.
 - The client never computes balances, fees, or seller nets — it only displays
  server responses.
 ## 6. Task breakdown
 Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
 are sequential for dependency chaining.
 | # | Task | Story | Depends on |
 |---|------|-------|-----------|
 | 1 | Wallet & ledger models + Alembic migration (`wallets`, `transactions`) | US-1 | — |
 | 2 | Wallet service (atomic credit/debit, idempotency, locking) + wallet/transactions API | US-1 | 1 |
 | 3 | Premium purchase: `PaymentProvider` interface + purchase/confirm endpoints | US-2 | 1 |
 | 4 | Catalog item & listing models + migration (`catalog_items`, `marketplace_listings`, `creator_balances`) | US-3 | 1 |
 | 5 | Marketplace listing API (create/list/search/update/remove) | US-3 | 4 |
 | 6 | Marketplace purchase service + API (atomic escrow, fee split, item grant) | US-4 | 2, 4, 5 |
 | 7 | Creator payout request models + API (`payout_requests`) | US-5 | 2, 6 |
 | 8 | Payout admin review + `PayoutProvider` + audit | US-5 | 7 |
 | 9 | Marketplace moderation + content-flag/age-gate enforcement | cross-cutting | 5, 6 |
 | 10 | Godot economy API client (auth + HTTP + idempotency) | US-6 | 2 |
 | 11 | Godot wallet & transaction history UI | US-6 | 10 |
 | 12 | Godot marketplace browse/buy UI | US-6 | 6, 10 |
 | 13 | Godot selling & payout UI | US-6 | 5, 7, 10 |
 ## 7. Phasing
 - **Phase 1 (currency + payments):** tasks 1–3. The foundation — ledger and
  money movement must be rock-solid before anything spends Credits.
 - **Phase 2 (marketplace):** tasks 4–6. Listing and atomic purchase with escrow.
 - **Phase 3 (payouts):** tasks 7–8. Turn released escrow into creator payouts.
 - **Phase 4 (moderation):** task 9. Lock down the marketplace against mature
  content and abuse.
 - **Phase 5 (client):** tasks 10–13, each landing after its backend dependency.
 ## 8. Data model sketch
 ```text
 wallets
  id                bigint PK
  user_id           int UNIQUE FK -> users.id
  balance           bigint NOT NULL DEFAULT 0  CHECK (balance >= 0)
  created_at        timestamptz
  updated_at        timestamptz
 transactions        (append-only ledger)
  id                bigint PK
  wallet_id         bigint FK -> wallets.id
  type              enum(credit_purchase, marketplace_purchase,
                        marketplace_sale, escrow_release, payout,
                        refund, admin_adjustment)
  amount            bigint NOT NULL            (signed)
  balance_after     bigint NOT NULL
  reference_type    text                        (e.g. "purchase", "sale", "payout_request")
  reference_id      text
  idempotency_key   text UNIQUE
  metadata_json     jsonb
  created_at        timestamptz
 catalog_items
  id                bigint PK
  owner_id          int FK -> users.id
  asset_id          int FK -> assets.id (nullable; null for non-asset virtual items)
  item_type         enum(asset, avatar_item, experience_pass)
  name              text
  description       text
  metadata_json     jsonb
  created_at        timestamptz
 marketplace_listings
  id                bigint PK
  catalog_item_id   bigint FK -> catalog_items.id
  seller_id         int FK -> users.id
  price             bigint NOT NULL CHECK (price > 0)
  status            enum(active, sold, delisted, removed_by_moderation)
  created_at        timestamptz
  updated_at        timestamptz
 purchases
  id                bigint PK
  listing_id        bigint FK -> marketplace_listings.id
  buyer_id          int FK -> users.id
  seller_id         int FK -> users.id
  price             bigint NOT NULL
  platform_fee      bigint NOT NULL
  seller_net        bigint NOT NULL
  status            enum(pending_escrow, completed, refunded, reversed)
  escrow_hold_until timestamptz
  created_at        timestamptz
 creator_balances
  id                bigint PK
  user_id           int UNIQUE FK -> users.id
  available         bigint NOT NULL DEFAULT 0
  pending           bigint NOT NULL DEFAULT 0
  lifetime_earned   bigint NOT NULL DEFAULT 0
  updated_at        timestamptz
 payout_requests
  id                bigint PK
  creator_id        int FK -> users.id
  amount            bigint NOT NULL CHECK (amount > 0)
  status            enum(pending, approved, paid, rejected)
  external_ref      text
  provider_ref      text
  requested_by      int FK -> users.id
  reviewed_by       int FK -> users.id (nullable)
  reviewed_at       timestamptz
  created_at        timestamptz
 ```
 ## 9. Security, anti-fraud & audit
 - **Server-authoritative balances/fees:** clients never compute totals; amounts
  are validated server-side against bounds and the current listing.
 - **Row locking:** wallet and creator-balance mutations use `SELECT ... FOR
  UPDATE` within one transaction.
 - **Idempotency:** every money-moving endpoint requires an `Idempotency-Key`;
  duplicate keys return the stored original outcome.
 - **Rate limiting:** purchase, listing, and payout endpoints are token-bucket
  rate-limited per user.
 - **Escrow & reversibility:** funds are not payable until the hold window
  elapses; chargebacks/refunds reverse before release.
 - **Moderation:** listings carry the item's effective content flags; mature
  items require age verification (per `content_moderation.md`); moderators can
  `delist`/`remove` and trigger audited reversals.
 - **Audit:** the ledger plus `payout_requests` review fields form an append-only
  audit trail for every movement of value.
 ## 10. Out of scope for this feature
 - Real Stripe/PayPal/KYC integrations (provider interfaces leave the hooks; the
  defaults are deterministic no-ops).
 - Subscriptions, recurring billing, or premium memberships.
 - Gift cards, promotional codes, or user-to-user Credit transfers.
 - Partial refunds, chargeback disputes, and seller tax/VAT handling.
 - In-world vending machines / scripted economy triggers (future, built on this
  ledger via the scripting sandbox).
@@ -1,170 +0,0 @@
 # Social — Friends, Chat & Groups — Plan
 > **Status:** Planned
 > **Owner:** Platform team
 > **Feature ID:** `social`
 > **Godot version:** 4.6.2 stable
 > **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
 ## 1. Overview
 This document breaks the **Social** feature into user stories and right-sized
 implementation tasks. The feature delivers:
 - **Friends & following** — a friend request/accept model plus a one-way follow
  relationship, with block lists.
 - **Presence & status** — online/offline, custom status message, last-seen.
 - **Chat** — direct messages (DM) and in-experience (world/room) chat with
  **first-class safety**: server-side text filtering, report-message, and rate
  limiting.
 - **Groups** — named groups with roles (owner/admin/member) and a simple group
  page.
 - **Public profiles** — avatar, bio, favorite experiences, and a friends list
  that respects privacy settings.
 ## 2. Why chat safety is the differentiator
 The platform is explicitly meant to pull adults away from a youth-oriented
 competitor. Chat is the highest-risk surface: it is real-time, user-generated,
 and where abuse happens fastest. Safety is therefore treated as a **blocking
 requirement**, not an add-on:
 - Every message passes a **server-side text filter** before it is stored or
  delivered. The client filter is cosmetic only; the server is authoritative.
 - Every message can be **reported**; reports flow into a moderation queue with
  actor + reason + audit trail (mirroring `content_moderation.md`).
 - Sending is **rate limited** per user (Redis token bucket) to stop flooding and
  harassment-by-volume.
 - Report and block are always reachable from a message context in the UI.
 ## 3. Existing constraints (do not re-build)
 - **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
  `app/dependencies.py`. All social endpoints reuse this.
 - **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
 - **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
  presence and rate limiting.
 - **Models:** `User`, `World` (owner_id), `Asset` (owner_id, is_public). Avatars
  and favorite-experience references point at existing rows.
 - **Client:** Godot 4.6.2, minimal `main_menu.gd`; no social UI yet.
 ## 4. Key design decisions
 | Concern | Decision |
 |---|---|
 | Message transport | REST for send/history; **WebSocket** gateway for real-time delivery + presence (matches `networking.md`'s "WebSocket as secondary transport" for chat) |
 | Presence store | Redis (TTL heartbeat) + persisted `last_seen_at` on the user record |
 | Text filtering | Pluggable `TextFilter` interface with a deterministic default (profanity list + normalization) so it runs without external services; third-party hook later |
 | Rate limiting | Redis token-bucket dependency, reusable across all social endpoints |
 | Reports | `message_reports` table + moderation endpoints (list/review/resolve) with audit fields |
 | Friends vs. follow | Friends = mutual (request→accept). Follow = one-way (no approval). Block = hard deny that also hides content and prevents DMs |
 | Privacy | Per-user settings JSON (`profile_visibility`, `friends_list_visibility`, `favorites_visibility`) enforced server-side on every read |
 | Groups | `groups` + `group_members` (role: owner/admin/member) + group page aggregate endpoint |
 | Real-time | One WebSocket endpoint multiplexing presence, DM, and world-chat messages via Redis pub/sub |
 ## 5. User stories
 ### US-1 Friends & following
 As a player, I can send a friend request, accept/decline incoming requests,
 unfriend, follow/unfollow other players, and block users so they can't interact
 with me.
 **Acceptance criteria**
 - Friend requests are one-directional until accepted; accepted friendships are mutual.
 - Follow is one-way and requires no approval.
 - Block prevents DMs, hides the blocked user's profile/friends interactions, and
  removes any existing friendship/follow between the two.
 - Duplicate/self requests are rejected idempotently.
 ### US-2 Presence & status
 As a player, I can see whether my friends are online, their custom status, and
 when they were last seen.
 **Acceptance criteria**
 - Online/offline is derived from a server-side heartbeat (Redis TTL), not client claims.
 - `last_seen_at` persists and is visible (subject to privacy settings).
 - Custom status text is optional and length-limited.
 ### US-3 Public profiles
 As a player, I can view a public profile page showing avatar, bio, favorite
 experiences, and a friends list that respects the owner's privacy settings.
 **Acceptance criteria**
 - Avatar and bio are editable by the owner only.
 - Favorite experiences reference existing `World` rows.
 - A viewer sees only the sections the owner's privacy settings allow; blocked
  users see a restricted view.
 ### US-4 Chat (DM + in-experience) with safety
 As a player, I can send direct messages and chat inside a world/room. Messages
 are filtered, rate limited, and reportable.
 **Acceptance criteria**
 - Server filters message text before storing/delivering; filtered content is either
  rejected (blocking) or redacted (configurable per filter policy).
 - Send rate is limited per user (token bucket); excess sends get `429`.
 - Every message has a stable id, author, timestamp, and conversation/world scope.
 - Any message can be reported with a reason; reports are stored and reviewable.
 - Real-time delivery over WebSocket with REST fallback for history.
 ### US-5 Groups
 As a player, I can create a group, join/leave groups, and (as owner/admin)
 manage roles and view a simple group page.
 **Acceptance criteria**
 - Each group has exactly one owner and any number of admins/members.
 - Role transitions are authorized (only owner can transfer ownership or promote/demote admins).
 - Group page lists name, description, member list with roles, and member count.
 ### US-6 Godot client
 As a player, I can access friends, presence, chat, profiles, and groups from the
 game UI.
 **Acceptance criteria**
 - An API client handles JWT auth, HTTP, and WebSocket for all social calls.
 - Dedicated screens/panels: friends+presence, DM & world chat (with report),
  profile page, group page.
 - Client-side filtering is cosmetic; server responses remain authoritative.
 ## 6. Task breakdown
 Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
 are sequential for dependency chaining.
 | # | Task | Story | Depends on |
 |---|------|-------|-----------|
 | 1 | Friends/follow/block models + Alembic migration | US-1 | — |
 | 2 | Friends & follow API router | US-1 | 1 |
 | 3 | Presence & status model + endpoints (Redis heartbeat) | US-2 | — |
 | 4 | Profile model + migration + own-profile endpoints | US-3 | 1 |
 | 5 | Public profile view + favorites + privacy enforcement | US-3 | 2, 4 |
 | 6 | Chat data models + migration (conversations, messages, reports) | US-4 | — |
 | 7 | Text filtering service + profanity config | US-4 | — |
 | 8 | Redis rate-limiting dependency | US-4 | — |
 | 9 | DM chat send/list endpoints (filter + rate limit) | US-4 | 6, 7, 8 |
 | 10 | Report-message endpoint + moderation queue | US-4 | 6, 9 |
 | 11 | In-experience (world/room) chat endpoints | US-4 | 9 |
 | 12 | Real-time WebSocket gateway (presence + DM + world chat) | US-4 | 3, 9, 11 |
 | 13 | Group + membership models + migration | US-5 | — |
 | 14 | Groups API (CRUD, join/leave, roles, group page) | US-5 | 13 |
 | 15 | Godot API client (auth + HTTP + WebSocket) | US-6 | 2 |
 | 16 | Godot friends & presence UI | US-6 | 3, 15 |
 | 17 | Godot chat UI (DM + world chat + report) | US-6 | 12, 15 |
 | 18 | Godot profile page UI | US-6 | 5, 15 |
 | 19 | Godot groups UI + group page | US-6 | 14, 15 |
 ## 7. Phasing
 - **Phase 1 (data + core APIs):** tasks 1–5 (friends, presence, profiles).
 - **Phase 2 (chat safety — the differentiator):** tasks 6–12 (chat + safety +
  realtime). This is the critical path and highest priority.
 - **Phase 3 (groups):** tasks 13–14.
 - **Phase 4 (client):** tasks 15–19, each landing after its backend dependency.
 ## 8. Out of scope for this feature
 - Age verification / maturity gating (covered by `content_moderation.md`).
 - Voice chat, media/image messages, message editing/deletion history.
 - Third-party profanity/toxicity vendors (the `TextFilter` interface leaves a
  hook, but the default is deterministic and dependency-free).
 - Mobile push notifications.
@@ -1,50 +0,0 @@
 # Testing at Package Checkpoints
 A Package Checkpoint (PC1, PC2, ...) is a periodic review point — every few
 real milestones, the client and server builds get packaged together and
 independently reviewed before anyone calls anything actually done. See
 `project_agp` in Claude's memory, or ask, for the full definition; this
 doc is just the mechanical "how do I run the tests" part of that review.
 ## Running the suite
 ```
 python scripts/run_checkpoint_tests.py
 ```
 Brings up a throwaway Postgres, runs Alembic migrations against it, runs the
 backend pytest suite, starts the backend server, and runs every Godot
 headless smoke test (`scripts/smoke_test_*.gd`) against it. Tears the
 Postgres container down afterward (`--keep-postgres` to skip that if you
 want to poke at the DB after a failure).
 If port 5432 is already taken on the machine, pass `--postgres-port` with
 something else.
 Exit code is 0 only if everything that actually ran passed — suites with
 nothing to run yet (no Godot binary found, no smoke test scripts yet) are
 reported SKIPPED, not treated as a failure.
 ## What this does and doesn't prove
 Passing this script means: migrations apply cleanly to a genuinely empty
 database, the backend's unit-level logic is correct, and whatever Godot
 smoke tests exist actually round-trip against a live backend. It does
 **not** mean full endpoint/integration coverage exists — see
 `test_inventory.md` for the current, honest list of what's tested and what
 isn't. A checkpoint review should still involve reading the actual diffs
 for anything this script's current coverage doesn't reach, not just running
 green and calling it done.
 ## Growing this over time
 As real integration tests get added (endpoint tests hitting the FastAPI app,
 more Godot smoke coverage beyond `health_check`), they should land under
 `backend/tests/` / `scripts/smoke_test_*.gd` respectively — this script
 picks up new files automatically, nothing to register by hand. Update
 `test_inventory.md`'s tables when you do, so the inventory stays a source
 of truth instead of quietly going stale.
 Eventual goal (not implemented yet): gate merges to `main` on this script
 passing, the same way a real CI pipeline would. For now it's a manual step
 run at checkpoint review time.
@@ -1,78 +0,0 @@
 # Test Inventory
 What automated coverage actually exists, what it actually verifies, and what
 doesn't have coverage yet. Keep this current as tests are added — it's the
 thing a Package Checkpoint review (see `docs/testing/README.md`) reads first
 to know what "run the tests" actually checked.
 Run everything below in one shot with `scripts/run_checkpoint_tests.py`.
 Last verified against `main`: 2026-08-19 (commit `1c75367`).
 ## Backend — `backend/tests/` (pytest)
 Run: `cd backend && python -m pytest -v` (needs `DATABASE_URL` pointed at a
 reachable Postgres — see the runner script; most of these tests don't
 actually touch the DB, but the app's import chain requires a valid URL to
 construct).
 **Current total: 38 tests, all passing on a clean `main` checkout.**
 | File | Tests | What it covers |
 |---|---|---|
 | `test_auth_age_gate.py` | 10 | `calculate_age()` date-math correctness (exact boundary, leap years, birthday-not-yet-this-year) + `RegisterRequest` date-of-birth validation (parametrized valid/invalid date rejection). Backs the 18+ registration gate (PR #23). |
 | `test_gltf_metadata.py` | 21 | glTF/GLB binary + JSON parsing: magic-byte detection, chunk-padding handling, mesh/animation/texture-reference metadata extraction, malformed-input rejection. Backs the asset-import pipeline (PR #27). |
 **What these are, honestly:** pure unit tests of standalone functions
 (`calculate_age`, the glTF parser, Pydantic validators). None of them spin
 up the FastAPI app or hit a real endpoint — they run in ~1s and don't
 actually need Postgres reachable at all (the import chain just needs a
 syntactically valid `DATABASE_URL`, nothing connects during collection).
 **Known coverage gaps** (real gaps, not placeholders — nothing enforces filling
 these yet):
 - No integration/endpoint tests at all — `/register`, `/login`, `/refresh`,
  `/worlds`, `/assets/*` have zero tests that actually call them through
  the FastAPI app (e.g. via `httpx.AsyncClient` + `ASGITransport`) against a
  real (or test) database. Everything currently shipped works because it
  was manually verified at merge time (checkpoint review), not because a
  test asserts it.
 - No tests for the RS256 auth upgrade (key generation, refresh-token
  issuance/persistence) — PR #30, pending review as of this writing,
  manually verified (correct key usage, all 38 existing tests still pass)
  but not covered by an automated test of its own yet.
 - No tests for the moderation schema/migration (in progress as of this
  writing) beyond "the migration runs."
 ## Godot client — `scripts/smoke_test_*.gd`
 **Nothing merged into `main` yet as of this writing** — `sandbox_probe/test_script.gd`
 is the only Godot script on `main` right now, and it's **not a real
 test** (a leftover manual probe, returns a hardcoded string, asserts
 nothing). Don't count it toward coverage; delete or repurpose it if anyone
 actually needs a sandbox probe again.
 `scripts/smoke_test_api.gd` (PC1, PR #29, pending review as of this writing)
 will be the first real one once merged — `ApiClient` autoload's
 `health_check()` against a **live backend** (set `AGP_API_BASE_URL` to point
 at one), verified by hand end-to-end before opening the PR: exercises the
 real HTTP request path (`HTTPRequest` node lifecycle, JSON parse, the
 result-dictionary contract), not just that the script compiles. Exits 1 on
 failure, so it's CI/script-friendly.
 Run (once merged): `godot --headless --path . --import` once (builds the
 class cache — skip this and every `class_name`-declared class falsely
 errors as undeclared), then for each `scripts/smoke_test_*.gd`:
 `godot --headless --path . --script res://scripts/<name>.gd`
 **Known gap once it lands:** only `health_check()` is exercised end-to-end.
 `login`, `register`, `get_worlds`, `get_me` are implemented (see
 `scripts/api_client.gd`) but have no smoke coverage yet — each would need a
 real user/world fixture in the target backend to test against meaningfully.
 ## What "full coverage" should eventually mean here
 Not defined precisely yet — the honest target as of 2026-08-19 is just
 "more than pure-function unit tests." As real integration/endpoint tests get
 added, update the tables above rather than letting this doc drift stale;
 a wrong inventory is worse than no inventory.
@@ -1,74 +0,0 @@
 [preset.0]
 name="Linux"
 platform="Linux/X11"
 runnable=true
 advanced_options=false
 dedicated_server=false
 custom_features=""
 export_filter="all_resources"
 include_filter=""
 exclude_filter=""
 export_path="export/linux/agp-game.x86_64"
 encryption_include_filters=""
 encryption_exclude_filters=""
 encrypt_pck=false
 encrypt_directory=false
 script_export_mode=2
 [preset.0.options]
 custom_template/debug=""
 custom_template/release=""
 debug/export_console_wrapper=1
 binary_format/embed_pck=false
 texture_format/bptc=true
 texture_format/s3tc=true
 texture_format/etc=false
 texture_format/etc2=false
 binary_format/architecture="x86_64"
 ssh_remote_deploy/enabled=false
 [preset.1]
 name="Windows Desktop"
 platform="Windows Desktop"
 runnable=true
 advanced_options=false
 dedicated_server=false
 custom_features=""
 export_filter="all_resources"
 include_filter=""
 exclude_filter=""
 export_path="export/windows/agp-game.exe"
 encryption_include_filters=""
 encryption_exclude_filters=""
 encrypt_pck=false
 encrypt_directory=false
 script_export_mode=2
 [preset.1.options]
 custom_template/debug=""
 custom_template/release=""
 debug/export_console_wrapper=1
 binary_format/embed_pck=false
 texture_format/bptc=true
 texture_format/s3tc=true
 texture_format/etc=false
 texture_format/etc2=false
 binary_format/architecture="x86_64"
 codesign/enable=false
 application/icon=""
 application/console_wrapper_icon=""
 application/icon_interpolation=4
 application/file_version=""
 application/product_version=""
 application/company_name=""
 application/product_name=""
 application/file_description=""
 application/copyright=""
 application/trademarks=""
 application/export_angle=0
 application/export_d3d12=0
 d3d12/agility_sdk_multizip=0
@@ -6,22 +6,11 @@ config_version=5
 [application]
-config/name="AGP-Game"
+config/name="AGP Game"
-run/main_scene="res://scenes/main_menu.tscn"
+run/main_scene="res://scenes/main.tscn"
 config/features=PackedStringArray("4.6.2")
 agp/api_base_url="http://127.0.0.1:8000"
 [autoload]
 ApiClient="*res://scripts/api_client.gd"
 [display]
-window/size/viewport_width=1920
+window/size/viewport_width=1280
-window/size/viewport_height=1080
+window/size/viewport_height=720
 window/stretch/mode="canvas_items"
 [rendering]
 renderer/rendering_method="gl_compatibility"
 renderer/rendering_method.mobile="gl_compatibility"
@@ -1 +0,0 @@
@@ -1,174 +0,0 @@
 extends Node
 func _ready():
 	print("=== SANDBOX PROBE 6: Corrected Evidence Gathering (Godot 4.6.2) ===")
 	probe_script_loading()
 	probe_os_apis()
 	probe_file_access()
 	probe_network()
 	probe_classdb()
 	probe_expression_engine()
 	probe_engine_singletons()
 	probe_worker_threads()
 	probe_project_settings()
 	probe_allowlist()
 	print("=== SANDBOX PROBE 6 END ===")
 	get_tree().quit()
 func probe_script_loading():
 	print("--- Script loading ---")
 	var gd = GDScript.new()
 	gd.source_code = "extends RefCounted\nfunc hello():\n\treturn 42\n"
 	var err = gd.reload()
 	print("GDScript.reload() from source_code err=", err)
 	if err == OK:
 		var inst = gd.new()
 		print("  instantiated, hello()=", inst.call("hello"))
 	var res = load("res://test_script.gd")
 	print("load('res://test_script.gd') = ", res)
 	if res:
 		print("  get_source_code() available: ", res.has_method("get_source_code"))
 	print("  GDScript instance has 'get_ast': ", gd.has_method("get_ast"))
 	print("  GDScript instance has 'get_parser': ", gd.has_method("get_parser"))
 	print("  GDScript instance has 'get_script_method_list': ", gd.has_method("get_script_method_list"))
 	print("  GDScript instance has 'get_script_property_list': ", gd.has_method("get_script_property_list"))
 func probe_os_apis():
 	print("--- OS APIs ---")
 	var out = []
 	var exit_code = OS.execute("echo", ["hello"], out)
 	print("OS.execute('echo') exit=", exit_code, " out=", out)
 	print("OS.get_environment('HOME') = ", OS.get_environment("HOME"))
 	print("OS has 'create_process': ", OS.has_method("create_process"))
 	print("OS.get_cmdline_args() = ", OS.get_cmdline_args())
 	print("OS.get_user_data_dir() = ", OS.get_user_data_dir())
 	print("OS.get_executable_path() = ", OS.get_executable_path())
 func probe_file_access():
 	print("--- File access ---")
 	var f = FileAccess.open("/etc/hostname", FileAccess.READ)
 	print("FileAccess.open('/etc/hostname') = ", f)
 	if f:
 		print("  content: ", f.get_as_text())
 		f.close()
 	var w = FileAccess.open("/tmp/godot_probe_write.txt", FileAccess.WRITE)
 	print("FileAccess.open('/tmp/...', WRITE) = ", w)
 	if w:
 		w.store_string("probe")
 		w.close()
 		print("  wrote to /tmp OK")
 	var dir = DirAccess.open("/")
 	print("DirAccess.open('/') = ", dir)
 	if dir:
 		var names = dir.get_files()
 		print("  root files count: ", names.size())
 	var res_dir = DirAccess.open("res://")
 	print("DirAccess.open('res://') = ", res_dir)
 	var user_dir = DirAccess.open("user://")
 	print("DirAccess.open('user://') = ", user_dir)
 func probe_network():
 	print("--- Network ---")
 	var tcp = TCPServer.new()
 	var bind_err = tcp.listen(0)
 	print("TCPServer.listen(0) err=", bind_err)
 	var http = HTTPClient.new()
 	print("HTTPClient instantiated: ", http != null)
 	var http_req = HTTPRequest.new()
 	print("HTTPRequest instantiated: ", http_req != null)
 	var udp = PacketPeerUDP.new()
 	print("PacketPeerUDP instantiated: ", udp != null)
 	var ws = WebSocketPeer.new()
 	print("WebSocketPeer instantiated: ", ws != null)
 func probe_classdb():
 	print("--- ClassDB ---")
 	print("ClassDB.class_exists('OS'): ", ClassDB.class_exists("OS"))
 	print("ClassDB.class_exists('FileAccess'): ", ClassDB.class_exists("FileAccess"))
 	print("ClassDB.class_exists('TCPServer'): ", ClassDB.class_exists("TCPServer"))
 	print("ClassDB.class_exists('HTTPClient'): ", ClassDB.class_exists("HTTPClient"))
 	var class_list = ClassDB.get_class_list()
 	print("ClassDB.get_class_list() count: ", class_list.size())
 	var os_methods = ClassDB.class_get_method_list("OS")
 	print("OS method count: ", os_methods.size())
 	var inst = ClassDB.instantiate("Node")
 	print("ClassDB.instantiate('Node') = ", inst)
 	print("ClassDB has 'class_get_singleton': ", ClassDB.has_method("class_get_singleton"))
 func probe_expression_engine():
 	print("--- Expression engine ---")
 	var expr = Expression.new()
 	var err = expr.parse("1 + 2")
 	print("Expression.parse('1 + 2') err=", err)
 	if err == OK:
 		var result = expr.execute()
 		print("  Expression.execute() = ", result)
 	var expr2 = Expression.new()
 	err = expr2.parse("OS.get_environment('HOME')")
 	print("Expression.parse('OS.get_environment') err=", err)
 	if err == OK:
 		var result2 = expr2.execute()
 		print("  Expression.execute() = ", result2)
 	var expr3 = Expression.new()
 	err = expr3.parse("get_environment('HOME')", ["OS"])
 	print("Expression.parse with base_instance err=", err)
 	if err == OK:
 		var result3 = expr3.execute([], OS)
 		print("  Expression.execute with OS base = ", result3)
 	var expr4 = Expression.new()
 	err = expr4.parse("FileAccess.open('/etc/hostname', 1)")
 	print("Expression.parse('FileAccess.open') err=", err)
 	if err == OK:
 		var result4 = expr4.execute()
 		print("  Expression.execute() = ", result4)
 	var expr5 = Expression.new()
 	err = expr5.parse("get_tree().quit()")
 	print("Expression.parse('get_tree().quit()') err=", err)
 	if err == OK:
 		var result5 = expr5.execute()
 		print("  Expression.execute() = ", result5)
 func probe_engine_singletons():
 	print("--- Engine singletons ---")
 	print("Engine has 'remove_singleton': ", Engine.has_method("remove_singleton"))
 	print("Engine has 'add_singleton': ", Engine.has_method("add_singleton"))
 	print("Engine.get_main_loop() = ", Engine.get_main_loop())
 func probe_worker_threads():
 	print("--- Worker threads ---")
 	var thread = Thread.new()
 	print("  Thread.new() = ", thread)
 	print("  WorkerThreadPool has 'add_task': ", WorkerThreadPool.has_method("add_task"))
 func probe_project_settings():
 	print("--- Project settings ---")
 	var settings = ProjectSettings.get_property_list()
 	var relevant = []
 	for s in settings:
 		var name = String(s.name)
 		if "sandbox" in name.to_lower() or "restrict" in name.to_lower() or "security" in name.to_lower():
 			relevant.append(name)
 	print("  Sandbox/security project settings: ", relevant)
 	print("  ProjectSettings has 'application/run/disable_os': ", ProjectSettings.has_setting("application/run/disable_os"))
 	print("  ProjectSettings has 'application/run/disable_file_access': ", ProjectSettings.has_setting("application/run/disable_file_access"))
 	print("  ProjectSettings has 'application/run/disable_network': ", ProjectSettings.has_setting("application/run/disable_network"))
 	print("  ProjectSettings has 'set_setting': ", ProjectSettings.has_method("set_setting"))
 	print("  ProjectSettings has 'save': ", ProjectSettings.has_method("save"))
 func probe_allowlist():
 	print("--- Allowlist / static analysis ---")
 	var dangerous_patterns = [
 		"OS.execute", "OS.create_process", "OS.get_environment",
 		"FileAccess.open", "DirAccess.open", "TCPServer", "HTTPClient",
 		"load(", "preload(", "ClassDB", "Engine.get_main_loop",
 		"get_tree().quit", "ProjectSettings"
 	]
 	var test_script = """extends Node
 func _ready():
 	var f = FileAccess.open("/etc/passwd", FileAccess.READ)
 	OS.execute("rm", ["-rf", "/"])
 """
 	print("  Test script contains dangerous patterns:")
 	for p in dangerous_patterns:
 		if p in test_script:
 			print("    DETECTED: ", p)
@@ -1,6 +0,0 @@
 [gd_scene load_steps=2 format=3]
 [ext_resource type="Script" path="res://probe6.gd" id="1"]
 [node name="Probe6" type="Node"]
 script = ExtResource("1")
@@ -1,8 +0,0 @@
 ; Engine configuration file.
 config_version=5
 [application]
 config/name="sandbox_probe"
 run/main_scene="res://probe6.tscn"
 config/features=PackedStringArray("4.6")
@@ -1,4 +0,0 @@
 extends RefCounted
 func hello():
 	return "from test_script.gd"
@@ -1,114 +0,0 @@
 [gd_scene load_steps=2 format=3 uid="uid://main_menu_scene"]
 [ext_resource type="Script" path="res://scripts/main_menu.gd" id="1_main"]
 [node name="MainMenu" type="Control"]
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
 grow_horizontal = 2
 grow_vertical = 2
 script = ExtResource("1_main")
 [node name="CenterContainer" type="CenterContainer" parent="."]
 layout_mode = 3
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
 grow_horizontal = 2
 grow_vertical = 2
 [node name="VBoxContainer" type="VBoxContainer" parent="CenterContainer"]
 layout_mode = 1
 theme_override_constants/separation = 16
 size_flags_horizontal = 4
 [node name="TitleLabel" type="Label" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "AGP Game"
 horizontal_alignment = 1
 theme_override_font_sizes/font_size = 72
 [node name="AuthPanel" type="PanelContainer" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 visible = false
 [node name="MarginContainer" type="MarginContainer" parent="CenterContainer/VBoxContainer/AuthPanel"]
 layout_mode = 1
 theme_override_constants/margin_left = 24
 theme_override_constants/margin_top = 24
 theme_override_constants/margin_right = 24
 theme_override_constants/margin_bottom = 24
 [node name="AuthVBox" type="VBoxContainer" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer"]
 layout_mode = 1
 theme_override_constants/separation = 8
 size_flags_horizontal = 3
 [node name="AuthModeLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 text = "Login"
 horizontal_alignment = 1
 theme_override_font_sizes/font_size = 24
 [node name="UsernameEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 placeholder_text = "Username"
 size_flags_horizontal = 3
 [node name="PasswordEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 placeholder_text = "Password"
 size_flags_horizontal = 3
 echo_password = true
 [node name="EmailEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 visible = false
 placeholder_text = "Email"
 size_flags_horizontal = 3
 [node name="DOBEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 visible = false
 placeholder_text = "Date of Birth (YYYY-MM-DD)"
 size_flags_horizontal = 3
 [node name="ModeToggle" type="CheckButton" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 text = "Register"
 [node name="AuthButton" type="Button" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 text = "Login"
 size_flags_horizontal = 3
 [node name="AuthStatusLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 text = ""
 horizontal_alignment = 1
 autowrap_mode = 2
 visible = false
 [node name="WelcomeLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
 layout_mode = 1
 visible = false
 text = ""
 horizontal_alignment = 1
 [node name="PlayButton" type="Button" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "Play"
 size_flags_horizontal = 4
 [node name="QuitButton" type="Button" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "Quit"
 size_flags_horizontal = 4
 [connection signal="pressed" from="CenterContainer/VBoxContainer/PlayButton" to="." method="_on_play_button_pressed"]
 [connection signal="pressed" from="CenterContainer/VBoxContainer/QuitButton" to="." method="_on_quit_button_pressed"]
 [connection signal="toggled" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/ModeToggle" to="." method="_on_mode_toggle_toggled"]
 [connection signal="pressed" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton" to="." method="_on_auth_button_pressed"]
 [connection signal="text_submitted" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit" to="." method="_on_auth_button_pressed"]
 [connection signal="text_submitted" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit" to="." method="_on_auth_button_pressed"]
@@ -1,292 +0,0 @@
 extends Node
 ## Central HTTP client singleton (autoload name: "ApiClient").
 ##
 ## Every network call in the game flows through this class. Callers use the
 ## high-level helpers ([method login], [method register], [method get_worlds],
 ## [method health_check], [method get_me]) or the generic [method request]
 ## primitive. All results conform to the result-dictionary contract below.
 ##
 ## [b]Result Dictionary Contract[/b]
 ## Every public method returns (after `await`) a Dictionary with this shape:
 ##
 ##     {
 ##         "ok":     bool,     # true for HTTP 2xx, false otherwise
 ##         "status": int,      # HTTP status code (0 on network failure)
 ##         "data":   Variant,  # parsed JSON body on success (null otherwise)
 ##         "detail": String,   # human-readable message
 ##     }
 ##
 ## Network failures (timeout / DNS / refused connection) return `status == 0`
 ## with a `detail` describing the transport failure. Non-2xx responses return
 ## the real HTTP status and the backend's `detail` field from the JSON error
 ## body when present. No caller can crash on a failed request.
 ##
 ## [b]Token storage[/b]
 ## JWTs are kept in memory. [method set_token] is the single seam for future
 ## disk persistence (override it to save to `user://`).
 ##
 ## [b]Usage[/b]
 ##     var result: Dictionary = await ApiClient.login("alice", "secret")
 ##     if result.ok:
 ##         print("Logged in!")
 ##     else:
 ##         print("Error: ", result.detail)
 # ---------------------------------------------------------------------------
 # Token storage
 # ---------------------------------------------------------------------------
 var _access_token: String = ""
 var _token_type: String = "Bearer"
 ## Full Authorization header value, e.g. "Bearer eyJ...". Empty if no token.
 var bearer_token: String:
 	get:
 		return _token_type + " " + _access_token if _access_token != "" else ""
 ## Whether an access token is currently stored.
 func has_token() -> bool:
 	return _access_token != ""
 ## Set the access token (called after login / register / token refresh).
 ## This is the persistence seam: override to also write to disk.
 func set_token(access_token: String, token_type: String = "Bearer") -> void:
 	_access_token = access_token
 	_token_type = token_type
 ## Clear stored tokens.
 func clear_token() -> void:
 	_access_token = ""
 	_token_type = "Bearer"
 # ---------------------------------------------------------------------------
 # Configuration
 # ---------------------------------------------------------------------------
 var _base_url: String = "http://127.0.0.1:8000"
 ## Request timeout in seconds. 0 disables the timeout.
 var timeout_seconds: float = 10.0
 func _ready() -> void:
 	# Environment variable override (e.g. for headless smoke tests against a
 	# backend on a non-default port). Falls back to the ProjectSetting, then
 	# to the documented default.
 	var env_url := OS.get_environment("AGP_API_BASE_URL")
 	if env_url != "":
 		_base_url = env_url.rstrip("/")
 	else:
 		_base_url = str(ProjectSettings.get_setting(
 			"application/agp/api_base_url",
 			"http://127.0.0.1:8000"
 		)).rstrip("/")
 # ---------------------------------------------------------------------------
 # Core request primitive
 # ---------------------------------------------------------------------------
 ## Generic request primitive. Awaitable via `await`.
 ##
 ## Uses a dedicated HTTPRequest node per call so concurrent requests can never
 ## cross-talk, and so the result maps 1:1 to the awaiting caller.
 ##
 ## @param method       HTTPClient.Method enum value (GET/POST/PUT/PATCH/DELETE).
 ## @param path         URL path, e.g. "/api/health".
 ## @param body         Request body string (JSON or form-encoded).
 ## @param content_type "application/json" or "application/x-www-form-urlencoded".
 ## @param require_auth If true, attach the stored bearer token when present.
 ## @return Result dictionary conforming to the contract.
 func request(
 	method: HTTPClient.Method,
 	path: String,
 	body: String = "",
 	content_type: String = "application/json",
 	require_auth: bool = false
 ) -> Dictionary:
 	var http := HTTPRequest.new()
 	http.timeout = timeout_seconds
 	http.max_redirects = 8
 	http.accept_gzip = true
 	add_child(http)
 	var headers := PackedStringArray()
 	headers.append("Accept: application/json")
 	if content_type != "":
 		headers.append("Content-Type: " + content_type)
 	if require_auth and has_token():
 		headers.append("Authorization: " + bearer_token)
 	var url := _base_url + path
 	var err := http.request(url, headers, method, body)
 	if err != OK:
 		http.queue_free()
 		return _make_result(false, 0, null, "Failed to start request: " + _error_string(err))
 	# request_completed emits (result, response_code, headers, body).
 	var args: Array = await http.request_completed
 	var result_code: int = args[0]
 	var response_code: int = args[1]
 	var response_body: PackedByteArray = args[3]
 	http.queue_free()
 	# Transport-level failure (timeout / DNS / refused / TLS, etc.).
 	if result_code != HTTPRequest.RESULT_SUCCESS:
 		return _make_result(false, 0, null, _transport_error_detail(result_code))
 	# Server accepted the connection but returned no HTTP status line.
 	if response_code == 0:
 		return _make_result(false, 0, null, "No response received from server.")
 	var json_string := response_body.get_string_from_utf8()
 	var ok := response_code >= 200 and response_code < 300
 	if ok:
 		var data: Variant = _parse_json(json_string)
 		return _make_result(true, response_code, data, "OK")
 	# Non-2xx: surface the backend's "detail" message when available.
 	var detail := "HTTP error %d" % response_code
 	var parsed: Variant = _parse_json(json_string)
 	if parsed is Dictionary and (parsed as Dictionary).has("detail"):
 		detail = str((parsed as Dictionary)["detail"])
 	return _make_result(false, response_code, null, detail)
 # ---------------------------------------------------------------------------
 # High-level helpers
 # ---------------------------------------------------------------------------
 ## Log in with username/password (OAuth2PasswordRequestForm).
 ## On success stores the returned access token.
 func login(username: String, password: String) -> Dictionary:
 	var form := "username=" + username.uri_encode() + "&password=" + password.uri_encode()
 	var result := await request(
 		HTTPClient.METHOD_POST,
 		"/api/auth/login",
 		form,
 		"application/x-www-form-urlencoded",
 		false
 	)
 	_store_token_from_result(result)
 	return result
 ## Register a new user. On success stores the returned access token.
 ## @param date_of_birth ISO date string "YYYY-MM-DD".
 func register(
 	username: String,
 	email: String,
 	password: String,
 	date_of_birth: String
 ) -> Dictionary:
 	var payload := {
 		"username": username,
 		"email": email,
 		"password": password,
 		"date_of_birth": date_of_birth,
 	}
 	var result := await request(
 		HTTPClient.METHOD_POST,
 		"/api/auth/register",
 		JSON.stringify(payload),
 		"application/json",
 		false
 	)
 	_store_token_from_result(result)
 	return result
 ## List worlds visible to the current user (requires auth).
 ## @param visibility Optional filter: "public", "private", "friends_only".
 func get_worlds(skip: int = 0, limit: int = 50, visibility: String = "") -> Dictionary:
 	var path := "/api/worlds/?skip=%d&limit=%d" % [skip, limit]
 	if visibility != "":
 		path += "&visibility=" + visibility.uri_encode()
 	return await request(HTTPClient.METHOD_GET, path, "", "application/json", true)
 ## Ping the backend health endpoint (no auth).
 func health_check() -> Dictionary:
 	return await request(HTTPClient.METHOD_GET, "/api/health", "", "application/json", false)
 ## Fetch the current user's profile from the stored JWT (requires auth).
 func get_me() -> Dictionary:
 	return await request(HTTPClient.METHOD_GET, "/api/users/me", "", "application/json", true)
 # ---------------------------------------------------------------------------
 # Internals
 # ---------------------------------------------------------------------------
 func _store_token_from_result(result: Dictionary) -> void:
 	if result.ok and result.data is Dictionary:
 		var token: String = str((result.data as Dictionary).get("access_token", ""))
 		if token != "":
 			set_token(token)
 func _parse_json(text: String) -> Variant:
 	if text == "":
 		return null
 	var parsed: Variant = JSON.parse_string(text)
 	if parsed == null:
 		# null is ambiguous (valid JSON "null" vs parse failure). Fall back to
 		# the raw string so callers never lose the body entirely.
 		return text if text != "null" else null
 	return parsed
 func _make_result(ok: bool, status: int, data: Variant, detail: String) -> Dictionary:
 	return {
 		"ok": ok,
 		"status": status,
 		"data": data,
 		"detail": detail,
 	}
 func _transport_error_detail(result_code: int) -> String:
 	match result_code:
 		HTTPRequest.RESULT_CANT_CONNECT:
 			return "Could not connect to server. Is it running?"
 		HTTPRequest.RESULT_CANT_RESOLVE:
 			return "Could not resolve server hostname."
 		HTTPRequest.RESULT_CONNECTION_ERROR:
 			return "Connection error."
 		HTTPRequest.RESULT_TLS_HANDSHAKE_ERROR:
 			return "TLS handshake failed."
 		HTTPRequest.RESULT_NO_RESPONSE:
 			return "No response from server."
 		HTTPRequest.RESULT_BODY_SIZE_LIMIT_EXCEEDED:
 			return "Response body too large."
 		HTTPRequest.RESULT_BODY_DECOMPRESS_FAILED:
 			return "Failed to decompress response body."
 		HTTPRequest.RESULT_REQUEST_FAILED:
 			return "Request failed."
 		HTTPRequest.RESULT_TIMEOUT:
 			return "Request timed out."
 		_:
 			return "Network error (code %d)." % result_code
 func _error_string(err_code: int) -> String:
 	match err_code:
 		OK:
 			return "OK"
 		ERR_UNCONFIGURED:
 			return "HTTPRequest not configured (not in tree)."
 		ERR_BUSY:
 			return "HTTPRequest is busy with a previous request."
 		ERR_INVALID_PARAMETER:
 			return "Invalid URL format."
 		ERR_CANT_CONNECT:
 			return "Cannot connect to host."
 		_:
 			return "Unknown error (%d)." % err_code
@@ -1 +0,0 @@
 uid://cjd0uhll7iylj
@@ -1,42 +0,0 @@
 #!/usr/bin/env bash
 # Headless CI export for Linux and Windows.
 #
 # Requires:
 #   - Godot 4.6.2 (the exact version this project + export_presets.cfg were
 #     built against; a different Godot minor version's export templates are
 #     not guaranteed compatible)
 #   - The matching export templates installed at
 #     ~/.local/share/godot/export_templates/4.6.2.stable/
 #     (download: https://godotengine.org/download/archive/4.6.2-stable/,
 #     "Export templates" -- NOT the same as the editor download)
 #   - godot on PATH (or set GODOT_BIN below)
 #
 # Usage: scripts/build.sh
 # Output: export/linux/agp-game.x86_64, export/windows/agp-game.exe
 set -euo pipefail
 cd "$(dirname "$0")/.."
 GODOT_BIN="${GODOT_BIN:-godot}"
 if ! command -v "$GODOT_BIN" >/dev/null 2>&1; then
    if [ -x "$HOME/godot/godot" ]; then
        GODOT_BIN="$HOME/godot/godot"
    else
        echo "godot binary not found (checked PATH and ~/godot/godot)." >&2
        exit 1
    fi
 fi
 echo "Godot version: $("$GODOT_BIN" --version)"
 mkdir -p export/linux export/windows
 echo "=== Exporting Linux/X11 ==="
 "$GODOT_BIN" --headless --path . --export-release "Linux" export/linux/agp-game.x86_64
 echo "=== Exporting Windows Desktop ==="
 "$GODOT_BIN" --headless --path . --export-release "Windows Desktop" export/windows/agp-game.exe
 echo ""
 echo "Build artifacts:"
 ls -la export/linux export/windows
@@ -1,211 +0,0 @@
 extends Control
 ## Main menu with login/register UI wired to the backend auth API.
 ##
 ## The AuthPanel is hidden by default. When the user clicks "Login" or "Register"
 ## (the existing Play/Quit buttons), the auth panel slides in. The ModeToggle
 ## switches between Login and Register modes, showing/hiding the email and DOB
 ## fields accordingly.
 ##
 ## On successful auth the token is stored via ApiClient, the welcome label
 ## shows the username, and the Play button becomes enabled.
 # ── UI references ────────────────────────────────────────────────────────────
 var _auth_panel: PanelContainer
 var _auth_mode_label: Label
 var _username_edit: LineEdit
 var _password_edit: LineEdit
 var _email_edit: LineEdit
 var _dob_edit: LineEdit
 var _mode_toggle: CheckButton
 var _auth_button: Button
 var _status_label: Label
 var _welcome_label: Label
 var _play_button: Button
 var _quit_button: Button
 var _is_register_mode: bool = false
 var _is_authenticating: bool = false
 # ── Lifecycle ────────────────────────────────────────────────────────────────
 func _ready() -> void:
 	# Cache node references.
 	_auth_panel = $CenterContainer/VBoxContainer/AuthPanel
 	_auth_mode_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthModeLabel
 	_username_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit
 	_password_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit
 	_email_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/EmailEdit
 	_dob_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/DOBEdit
 	_mode_toggle = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/ModeToggle
 	_auth_button = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton
 	_status_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthStatusLabel
 	_welcome_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/WelcomeLabel
 	_play_button = $CenterContainer/VBoxContainer/PlayButton
 	_quit_button = $CenterContainer/VBoxContainer/QuitButton
 	# Initial state.
 	_auth_panel.visible = false
 	_status_label.visible = false
 	_welcome_label.visible = false
 	_email_edit.visible = false
 	_dob_edit.visible = false
 	_play_button.disabled = true  # Gate play behind successful auth.
 	_update_auth_mode_ui()
 # ── Play / Quit ──────────────────────────────────────────────────────────────
 func _on_play_button_pressed() -> void:
 	if _play_button.disabled:
 		return
 	# TODO: transition to the worlds / gameplay scene once it exists.
 	print("Play pressed — transitioning to game")
 func _on_quit_button_pressed() -> void:
 	get_tree().quit()
 # ── Auth panel toggle ────────────────────────────────────────────────────────
 func _on_login_button_pressed() -> void:
 	"""Show the auth panel (called from a future Login button on the main menu)."""
 	_auth_panel.visible = true
 	_auth_panel.grab_focus()
 func _on_register_button_pressed() -> void:
 	"""Show the auth panel in register mode."""
 	_auth_panel.visible = true
 	_is_register_mode = true
 	_mode_toggle.button_pressed = true
 	_update_auth_mode_ui()
 	_clear_status()
 # ── Mode toggle (Login / Register) ───────────────────────────────────────────
 func _on_mode_toggle_toggled(button_pressed: bool) -> void:
 	_is_register_mode = button_pressed
 	_update_auth_mode_ui()
 	_clear_status()
 func _update_auth_mode_ui() -> void:
 	"""Update labels and field visibility based on login vs register mode."""
 	if _is_register_mode:
 		_auth_mode_label.text = "Register"
 		_auth_button.text = "Register"
 		_email_edit.visible = true
 		_dob_edit.visible = true
 	else:
 		_auth_mode_label.text = "Login"
 		_auth_button.text = "Login"
 		_email_edit.visible = false
 		_dob_edit.visible = false
 # ── Auth submission ──────────────────────────────────────────────────────────
 func _on_auth_button_pressed() -> void:
 	"""Handle login or register button press."""
 	if _is_authenticating:
 		return
 	# Validate inputs.
 	var username := _username_edit.text.strip_edges()
 	var password := _password_edit.text
 	if username == "":
 		_show_status("Username is required.")
 		return
 	if password == "":
 		_show_status("Password is required.")
 		return
 	if _is_register_mode:
 		var email := _email_edit.text.strip_edges()
 		var dob := _dob_edit.text.strip_edges()
 		if email == "":
 			_show_status("Email is required.")
 			return
 		if dob == "":
 			_show_status("Date of birth is required.")
 			return
 		# Basic YYYY-MM-DD format check.
 		if not _is_valid_date(dob):
 			_show_status("Date of birth must be in YYYY-MM-DD format.")
 			return
 		_auth_button.disabled = true
 		_auth_button.text = "Registering..."
 		_is_authenticating = true
 		_clear_status()
 		var result := await ApiClient.register(username, email, password, dob)
 		_on_auth_complete(result)
 	else:
 		_auth_button.disabled = true
 		_auth_button.text = "Logging in..."
 		_is_authenticating = true
 		_clear_status()
 		var result := await ApiClient.login(username, password)
 		_on_auth_complete(result)
 func _on_auth_complete(result: Dictionary) -> void:
 	"""Handle the result of a login or register call."""
 	_auth_button.disabled = false
 	_auth_button.text = "Register" if _is_register_mode else "Login"
 	_is_authenticating = false
 	if result.ok:
 		# Success — show welcome, enable Play.
 		_welcome_label.text = "Welcome, %s!" % _username_edit.text.strip_edges()
 		_welcome_label.visible = true
 		_status_label.visible = false
 		_play_button.disabled = false
 		print("Auth successful. Token stored.")
 	else:
 		# Failure — show backend error detail.
 		_show_status(result.detail)
 # ── Status helpers ───────────────────────────────────────────────────────────
 func _show_status(message: String) -> void:
 	_status_label.text = message
 	_status_label.visible = true
 func _clear_status() -> void:
 	_status_label.text = ""
 	_status_label.visible = false
 # ── Validation ───────────────────────────────────────────────────────────────
 func _is_valid_date(date_str: String) -> bool:
 	"""Check if a string looks like a valid YYYY-MM-DD date."""
 	if date_str.length() != 10:
 		return false
 	var parts := date_str.split("-")
 	if parts.size() != 3:
 		return false
 	var year := parts[0].to_int()
 	var month := parts[1].to_int()
 	var day := parts[2].to_int()
 	if month < 1 or month > 12:
 		return false
 	if day < 1 or day > 31:
 		return false
 	# Rough month-day validation.
 	var days_in_month := [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
 	if day > days_in_month[month]:
 		return false
 	return true
@@ -1 +0,0 @@
 uid://bgnc3iamfgf6k
@@ -1,170 +0,0 @@
 #!/usr/bin/env python3
 """Run the full automated test inventory for a Package Checkpoint review.
 See docs/testing/test_inventory.md for what each suite actually covers (and
 doesn't) -- keep that doc in sync as tests are added, this script just runs
 whatever's there.
 Usage:
    python scripts/run_checkpoint_tests.py [--keep-postgres] [--postgres-port PORT]
 Exits 0 if everything that ran passed, 1 otherwise. Suites with nothing to
 run (e.g. no scripts/smoke_test_*.gd yet, or no Godot binary found) are
 reported as SKIPPED, not counted as a failure.
 """
 import argparse
 import glob
 import os
 import shutil
 import subprocess
 import sys
 import time
 from pathlib import Path
 ROOT = Path(__file__).resolve().parent.parent
 BACKEND = ROOT / "backend"
 def run(cmd, cwd=None, env=None, capture=False):
    print(f"$ {' '.join(cmd)}" + (f"  (cwd={cwd})" if cwd else ""))
    return subprocess.run(cmd, cwd=cwd, env=env, capture_output=capture, text=True)
 def find_godot():
    for candidate in ("godot", str(Path.home() / "godot" / "godot")):
        if shutil.which(candidate) or Path(candidate).is_file():
            return candidate
    return None
 def wait_for_http(url: str, timeout_s: int = 20) -> bool:
    import urllib.request
    import urllib.error
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        try:
            with urllib.request.urlopen(url, timeout=2) as resp:
                if resp.status == 200:
                    return True
        except (urllib.error.URLError, ConnectionError, OSError):
            pass
        time.sleep(1)
    return False
 def main():
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--keep-postgres", action="store_true",
                         help="Don't tear down the checkpoint Postgres container afterward")
    parser.add_argument("--postgres-port", default=os.environ.get("CHECKPOINT_POSTGRES_PORT", "5432"),
                         help="Host port for the checkpoint's own Postgres container (default 5432 -- "
                              "override if that's already in use on this machine)")
    parser.add_argument("--backend-port", default=os.environ.get("CHECKPOINT_BACKEND_PORT", "18080"),
                         help="Port to run the backend server on for the Godot smoke tests")
    args = parser.parse_args()
    results = {}
    # --- Backend: bring up Postgres ---
    compose_env = os.environ.copy()
    compose_env["COMPOSE_PROJECT_NAME"] = "agp-checkpoint"
    compose_env["POSTGRES_HOST_PORT"] = args.postgres_port
    compose_env["POSTGRES_PORT"] = args.postgres_port  # some branches use this name instead, see tools/definitions.py
    print("=== Backend: bringing up Postgres ===")
    run(["docker", "compose", "up", "-d", "postgres"], cwd=BACKEND, env=compose_env)
    print("Waiting for Postgres to be ready...")
    pg_ready = False
    for _ in range(20):
        r = run(["docker", "compose", "exec", "-T", "postgres", "pg_isready", "-U", "agp_user", "-d", "agp_db"],
                cwd=BACKEND, env=compose_env, capture=True)
        if r.returncode == 0:
            pg_ready = True
            break
        time.sleep(1)
    if not pg_ready:
        print("Postgres never became ready -- aborting.")
        sys.exit(1)
    db_url = f"postgresql+asyncpg://agp_user:agp_password@localhost:{args.postgres_port}/agp_db"
    backend_env = os.environ.copy()
    backend_env["DATABASE_URL"] = db_url
    print("\n=== Backend: alembic upgrade head ===")
    r = run([sys.executable, "-m", "alembic", "upgrade", "head"], cwd=BACKEND, env=backend_env)
    results["migrations (fresh DB)"] = r.returncode == 0
    print("\n=== Backend: pytest ===")
    r = run([sys.executable, "-m", "pytest", "-v"], cwd=BACKEND, env=backend_env)
    results["backend pytest"] = r.returncode == 0
    # --- Godot: headless smoke tests (need a live backend server) ---
    godot_bin = find_godot()
    smoke_tests = sorted(glob.glob(str(ROOT / "scripts" / "smoke_test_*.gd")))
    if not godot_bin:
        print("\n=== Godot: binary not found (checked PATH and ~/godot/godot), skipping smoke tests ===")
        results["godot smoke tests"] = None
    elif not smoke_tests:
        print("\n=== Godot: no scripts/smoke_test_*.gd found yet, nothing to run ===")
        results["godot smoke tests"] = None
    else:
        print(f"\n=== Backend: starting server on :{args.backend_port} for Godot smoke tests ===")
        server_proc = subprocess.Popen(
            [sys.executable, "-m", "uvicorn", "app.main:app", "--host", "127.0.0.1", "--port", args.backend_port],
            cwd=BACKEND, env=backend_env,
            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
        )
        try:
            base_url = f"http://127.0.0.1:{args.backend_port}"
            if not wait_for_http(f"{base_url}/api/health"):
                print("Backend server never became healthy -- skipping Godot smoke tests.")
                results["godot smoke tests"] = False
            else:
                godot_env = os.environ.copy()
                godot_env["AGP_API_BASE_URL"] = base_url
                print("=== Godot: import pass (builds the class cache) ===")
                run([godot_bin, "--headless", "--path", str(ROOT), "--import"], env=godot_env)
                run([godot_bin, "--headless", "--path", str(ROOT), "--quit"], env=godot_env)
                godot_ok = True
                for test in smoke_tests:
                    rel = os.path.relpath(test, ROOT)
                    print(f"\n--- {rel} ---")
                    r = run([godot_bin, "--headless", "--path", str(ROOT), "--script", f"res://{rel}"], env=godot_env)
                    if r.returncode != 0:
                        godot_ok = False
                results["godot smoke tests"] = godot_ok
        finally:
            server_proc.terminate()
            try:
                server_proc.wait(timeout=10)
            except subprocess.TimeoutExpired:
                server_proc.kill()
    if not args.keep_postgres:
        print("\n=== Backend: tearing down checkpoint Postgres ===")
        run(["docker", "compose", "down", "-v", "postgres"], cwd=BACKEND, env=compose_env)
    # --- Summary ---
    print("\n" + "=" * 50)
    print("SUMMARY")
    print("=" * 50)
    overall_ok = True
    for name, ok in results.items():
        if ok is None:
            print(f"  {name}: SKIPPED")
        elif ok:
            print(f"  {name}: PASS")
        else:
            print(f"  {name}: FAIL")
            overall_ok = False
    print("\nSee docs/testing/test_inventory.md for what each suite actually covers (and doesn't).")
    sys.exit(0 if overall_ok else 1)
 if __name__ == "__main__":
    main()
@@ -1,46 +0,0 @@
 extends SceneTree
 ## Headless smoke test for the ApiClient autoload.
 ##
 ## Run with:
 ##     godot --headless --path . --script res://scripts/smoke_test_api.gd
 ##
 ## Requires the backend to be running (default base URL
 ## `application/agp/api_base_url` -> http://127.0.0.1:8000).
 ##
 ## Calls the real autoload's `health_check()` (which exercises the generic
 ## `request()` primitive) and exits 0 on a `status == "ok"` response, 1
 ## otherwise. This script is intentionally NOT wired into any game scene.
 func _initialize() -> void:
 	_run()
 func _run() -> void:
 	# _initialize() fires before the SceneTree has processed its first frame,
 	# so a freshly add_child()'d HTTPRequest node isn't reliably considered
 	# "inside tree" yet (request_raw fails with !is_inside_tree()). One frame
 	# of delay is enough; this only matters for --script mode, not a real
 	# running game.
 	await process_frame
 	# Godot's --script/SceneTree runner doesn't resolve autoload singletons
 	# as bare global identifiers at compile time (the node exists at
 	# runtime -- root.has_node("ApiClient") is true -- but referencing it as
 	# a plain identifier fails with "Identifier not found: ApiClient" during
 	# script compilation). get_node sidesteps compile-time resolution
 	# entirely. This only affects --script mode; a real game scene resolves
 	# the bare autoload name normally.
 	var api_client := root.get_node("ApiClient")
 	print("SMOKE: calling ApiClient.health_check() ...")
 	var result: Dictionary = await api_client.health_check()
 	print("SMOKE: result = ", result)
 	if result.ok \
 			and result.data is Dictionary \
 			and str((result.data as Dictionary).get("status", "")) == "ok":
 		print("SMOKE RESULT: PASS (status=ok)")
 		quit(0)
 	else:
 		printerr("SMOKE RESULT: FAIL")
 		quit(1)
@@ -1,133 +0,0 @@
 extends SceneTree
 ## Headless smoke test for the AuthPanel login/register flow.
 ##
 ## Run with:
 ##     godot --headless --path . --script res://scripts/smoke_test_auth.gd
 ##
 ## Requires the backend to be running (default base URL
 ## `application/agp/api_base_url` -> http://127.0.0.1:8000).
 ##
 ## Tests:
 ##   1. Register a unique user → 201 + token stored.
 ##   2. Register the same user again → 409 "Username already registered".
 ##   3. Register an under-18 user → 400 "Must be 18 or older".
 ##   4. Login with correct credentials → 200 + token stored.
 ##   5. Login with wrong password → 401 "Incorrect username or password".
 ##   6. Login with non-existent user → 401 "Incorrect username or password".
 ##
 ## Exits 0 on full pass, 1 on any failure.
 const API_BASE := "http://127.0.0.1:8000"
 const TEST_USERNAME := "smoke_test_user_%d"
 const TEST_EMAIL := "smoke_%d@test.example.com"
 const TEST_PASSWORD := "SmokeTest123!"
 const TEST_DOB_ADULT := "2000-01-01"
 const TEST_DOB_CHILD := "2020-01-01"  # ~5 years old
 func _initialize() -> void:
 	_run()
 func _run() -> void:
 	# Wait for autoloads to be ready.
 	await process_frame
 	var api := root.get_node("ApiClient") as ApiClient
 	assert(api != null, "ApiClient autoload not found")
 	var passed: int = 0
 	var failed: int = 0
 	# --- Test 1: Register a unique user ---
 	var unique_id := Time.get_ticks_msec()
 	var username := "smoke_%d" % unique_id
 	var email := "smoke_%d@test.example.com" % unique_id
 	print("\n=== Test 1: Register unique user ===")
 	var result := await api.register(username, email, TEST_PASSWORD, TEST_DOB_ADULT)
 	if _check("register returns ok", result.ok) \
 			and _check("register status is 201", result.status == 201) \
 			and _check("register stores token", api.has_token()):
 		passed += 1
 	else:
 		failed += 1
 		print("  detail: ", result.detail)
 	# --- Test 2: Register same user again (duplicate) ---
 	print("\n=== Test 2: Duplicate username ===")
 	result = await api.register(username, email, TEST_PASSWORD, TEST_DOB_ADULT)
 	if _check("duplicate register not ok", not result.ok) \
 			and _check("duplicate status is 409", result.status == 409) \
 			and _check("duplicate detail mentions username",
 					"username" in result.detail.to_lower()):
 		passed += 1
 	else:
 		failed += 1
 		print("  detail: ", result.detail)
 	# --- Test 3: Register under-18 user ---
 	print("\n=== Test 3: Under-18 registration ===")
 	var child_username := "child_%d" % unique_id
 	var child_email := "child_%d@test.example.com" % unique_id
 	result = await api.register(child_username, child_email, TEST_PASSWORD, TEST_DOB_CHILD)
 	if _check("under-18 register not ok", not result.ok) \
 			and _check("under-18 status is 400", result.status == 400) \
 			and _check("under-18 detail mentions age",
 					"18" in result.detail):
 		passed += 1
 	else:
 		failed += 1
 		print("  detail: ", result.detail)
 	# --- Test 4: Login with correct credentials ---
 	print("\n=== Test 4: Correct login ===")
 	result = await api.login(username, TEST_PASSWORD)
 	if _check("login returns ok", result.ok) \
 			and _check("login status is 200", result.status == 200) \
 			and _check("login stores token", api.has_token()):
 		passed += 1
 	else:
 		failed += 1
 		print("  detail: ", result.detail)
 	# --- Test 5: Login with wrong password ---
 	print("\n=== Test 5: Wrong password ===")
 	result = await api.login(username, "WrongPassword!")
 	if _check("wrong pwd login not ok", not result.ok) \
 			and _check("wrong pwd status is 401", result.status == 401) \
 			and _check("wrong pwd detail",
 					"Incorrect" in result.detail or "incorrect" in result.detail):
 		passed += 1
 	else:
 		failed += 1
 		print("  detail: ", result.detail)
 	# --- Test 6: Login with non-existent user ---
 	print("\n=== Test 6: Non-existent user ===")
 	result = await api.login("nonexistent_user_xyz", TEST_PASSWORD)
 	if _check("missing user login not ok", not result.ok) \
 			and _check("missing user status is 401", result.status == 401) \
 			and _check("missing user detail",
 					"Incorrect" in result.detail or "incorrect" in result.detail):
 		passed += 1
 	else:
 		failed += 1
 		print("  detail: ", result.detail)
 	# --- Summary ---
 	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
 	if failed > 0:
 		quit(1)
 	else:
 		print("SMOKE RESULT: ALL PASS")
 		quit(0)
 func _check(description: String, condition: bool) -> bool:
 	if condition:
 		print("  PASS: ", description)
 		return true
 	else:
 		printerr("  FAIL: ", description)
 		return false
@@ -0,0 +1,15 @@
 Godot Engine v4.6.2.stable.official.71f334935 - https://godotengine.org
 roundtrip bounds.position = (0.0, 0.0, 0.0)  (expected (0.5, 1.5, 2.5))
 roundtrip coord = (0, 0, 0)  (expected (1, 2, 3))
 format_version present? -> <null>
 version field -> 1
 SCRIPT ERROR: Invalid assignment of property or key 'properties' with value of type 'bool' on a base object of type 'RefCounted (WorldObjectData)'.
          at: _parse_object_section (res://scripts/chunk_data_decoder.gd:407)
          GDScript backtrace (most recent call first):
              [0] _parse_object_section (res://scripts/chunk_data_decoder.gd:407)
              [1] _init (res://test_review.gd:25)
 SCRIPT ERROR: Out of bounds get index '0' (on base: 'Array[WorldObjectData]')
          at: _init (res://test_review.gd:26)
          GDScript backtrace (most recent call first):
              [0] _init (res://test_review.gd:26)
@@ -0,0 +1,22 @@
 extends SceneTree
 func _init() -> void:
 	# 1. float32 encode/decode
 	var b: PackedByteArray = ChunkDataDecoder._write_float32(0.5)
 	print("float32(0.5) bytes = ", b, " (expected 00 00 00 3f)")
 	var decoded_f: float = ChunkDataDecoder._read_float32(PackedByteArray([0x00, 0x00, 0x00, 0x3f]), 0)
 	print("read_float32 of 0x3f000000 = ", decoded_f, " (expected 0.5)")
 	# 2. metadata section wrapping: inspect first bytes of encoded payload
 	var payload: ChunkDataDecoder.ChunkPayload = ChunkDataDecoder.ChunkPayload.new()
 	payload.world_id = "w"
 	payload.room_id = "r"
 	payload.coord = Vector3i(1, 2, 3)
 	var meta: PackedByteArray = ChunkDataDecoder._build_metadata_section(payload)
 	print("metadata section first 12 bytes = ", meta.slice(0, 12))
 	# 3. properties parse with empty-ish string
 	var props_str := "{}"
 	var val = JSON.parse_string(props_str) or {}
 	print("'JSON.parse_string(props_str) or {{}}' type = ", typeof(val), " value = ", val)
 	quit()
Author	SHA1	Message	Date
reviewer-bot	cea0835244	Recovered orphaned WIP before switching to a new task	2026-08-18 14:07:32 +00:00
reviewer-bot	a5834a0e85	WIP checkpoint: Review: Address review feedback: Implement chunk streaming system in GDScript	2026-08-18 13:57:27 +00:00