WIP checkpoint: Wallet & ledger models + Alembic migration (wallets, transactions)

2026-08-18 16:34:12 +00:00 · 2026-08-18 16:01:28 +00:00
18 changed files with 94 additions and 990 deletions
@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import create_async_engine
 from app.config import settings
 from app.database import Base
-from app.models import user, session, world, asset  # noqa: F401
+from app.models import user, session, world, asset, wallet  # noqa: F401
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
@@ -69,8 +69,7 @@ def upgrade() -> None:
        sa.Column(
            "visibility",
            postgresql.ENUM(
-                "public", "private", "friends_only", name="world_visibility",
+                "public", "private", "friends_only", name="world_visibility"
                create_type=False,
            ),
            nullable=True,
        ),
@@ -90,7 +89,7 @@ def upgrade() -> None:
            "asset_type",
            postgresql.ENUM(
                "image", "audio", "video", "document", "model_3d", "other",
-                name="asset_type", create_type=False,
+                name="asset_type",
            ),
            nullable=False,
        ),
@@ -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")
@@ -30,7 +30,6 @@ class Settings(BaseSettings):
    # 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",
@@ -2,5 +2,14 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
 from app.models.wallet import Transaction, TransactionType, Wallet
-__all__ = ["User", "Session", "World", "Asset"]
+__all__ = [
    "User",
    "Session",
    "World",
    "Asset",
    "Wallet",
    "Transaction",
    "TransactionType",
 ]
@@ -1,7 +1,4 @@
-from datetime import date
+from sqlalchemy import Column, Integer, String, Boolean, DateTime
 from typing import Optional
 from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
@@ -15,7 +12,6 @@ class User(Base):
    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())
@@ -23,15 +19,3 @@ class User(Base):
    sessions = relationship("Session", 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
@@ -0,0 +1,73 @@
 """Wallet and transaction ledger models."""
 import enum
 from sqlalchemy import (
    BigInteger,
    CheckConstraint,
    Column,
    DateTime,
    ForeignKey,
    Integer,
    Text,
 )
 from sqlalchemy.dialects.postgresql import ENUM, JSONB
 from sqlalchemy.sql import func
 from app.database import Base
 class TransactionType(str, enum.Enum):
    CREDIT_PURCHASE = "credit_purchase"
    MARKETPLACE_PURCHASE = "marketplace_purchase"
    MARKETPLACE_SALE = "marketplace_sale"
    ESCROW_RELEASE = "escrow_release"
    PAYOUT = "payout"
    REFUND = "refund"
    ADMIN_ADJUSTMENT = "admin_adjustment"
 class Wallet(Base):
    __tablename__ = "wallets"
    __table_args__ = (
        CheckConstraint("balance >= 0", name="ck_wallets_balance_nonnegative"),
    )
    id = Column(BigInteger, primary_key=True, index=True)
    user_id = Column(
        Integer,
        ForeignKey("users.id", ondelete="CASCADE"),
        unique=True,
        index=True,
        nullable=False,
    )
    balance = Column(BigInteger, nullable=False, default=0, server_default="0")
    created_at = Column(DateTime(timezone=True), server_default=func.now())
    updated_at = Column(
        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
    )
 class Transaction(Base):
    __tablename__ = "transactions"
    id = Column(BigInteger, primary_key=True, index=True)
    wallet_id = Column(
        BigInteger, ForeignKey("wallets.id"), nullable=False
    )
    type = Column(
        ENUM(
            TransactionType,
            name="transaction_type",
            create_type=False,
            values_callable=lambda enum_cls: [member.value for member in enum_cls],
        ),
        nullable=False,
    )
    amount = Column(BigInteger, nullable=False)
    balance_after = Column(BigInteger, nullable=False)
    reference_type = Column(Text, nullable=True)
    reference_id = Column(Text, nullable=True)
    idempotency_key = Column(Text, unique=True, index=True, nullable=True)
    metadata_json = Column(JSONB, nullable=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())
@@ -1,6 +1,5 @@
 """Asset management router."""
 import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -14,7 +13,6 @@ 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()
@@ -66,14 +64,6 @@ def _sanitize_filename(filename: str) -> str:
    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)
@@ -193,16 +183,10 @@ async def upload_asset_file(
    # Sanitize filename to prevent path traversal.
    safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
-    # Read the file content.
+    # Validate file size against configured maximum.
    max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
    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,
@@ -216,28 +200,10 @@ async def upload_asset_file(
    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,10 +1,10 @@
 """Authentication router - login, register, token refresh."""
-from datetime import date, datetime, timedelta, timezone
+from datetime import datetime, timedelta, timezone
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
-from pydantic import BaseModel, EmailStr, field_validator
+from pydantic import BaseModel, EmailStr
 from jose import jwt
 from passlib.context import CryptContext
@@ -32,24 +32,12 @@ 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
@@ -77,44 +65,11 @@ def hash_password(password: str) -> str:
    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
 # --- 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 an access token.
+    """Register a new user and return an access token."""
    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():
@@ -135,7 +90,6 @@ async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
        username=req.username,
        email=req.email,
        hashed_password=hash_password(req.password),
        date_of_birth=dob,
    )
    db.add(user)
    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,
    }
@@ -8,7 +8,7 @@ services:
      POSTGRES_PASSWORD: agp_password
      POSTGRES_DB: agp_db
    ports:
-      - "${POSTGRES_HOST_PORT:-5432}:5432"
+      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
@@ -20,7 +20,7 @@ services:
  redis:
    image: redis:7-alpine
    ports:
-      - "${REDIS_HOST_PORT:-6379}:6379"
+      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
@@ -1,3 +0,0 @@
 [pytest]
 asyncio_mode = auto
 testpaths = tests
@@ -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,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,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).
Author	SHA1	Message	Date
architect-bot	34fe164347	WIP checkpoint: Wallet & ledger models + Alembic migration (wallets, transactions)	2026-08-18 16:34:12 +00:00
architect-bot	cef6968766	WIP checkpoint: Wallet & ledger models + Alembic migration (wallets, transactions)	2026-08-18 16:01:28 +00:00