WIP checkpoint: US-1: Asset Import Pipeline — glTF upload endpoint with metadata extraction

backend/alembic/env.py

@@ -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, conversation, message  # noqa: F401
+from app.models import user, session, world, asset  # noqa: F401
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.

backend/alembic/versions/0002_add_date_of_birth_to_users.py

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

backend/alembic/versions/1a1983be633a_chat_data_models.py

@@ -1,228 +0,0 @@
-"""chat data models
-
-Revision ID: 1a1983be633a
-Revises: 0001_initial
-Create Date: 2026-08-18 15:06:05.948446
-"""
-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 = "1a1983be633a"
-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:
-    """Create chat tables: conversations, conversation_participants,
-    messages, message_reports."""
-
-    # ── ENUM types ──────────────────────────────────────────────────
-
-    msg_report_reason = postgresql.ENUM(
-        "spam", "inappropriate", "off_topic", "other",
-        name="message_report_reason",
-    )
-    msg_report_reason.create(op.get_bind(), checkfirst=True)
-
-    msg_report_status = postgresql.ENUM(
-        "pending", "resolved", "dismissed",
-        name="message_report_status",
-    )
-    msg_report_status.create(op.get_bind(), checkfirst=True)
-
-    # ── conversations ───────────────────────────────────────────────
-
-    op.create_table(
-        "conversations",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "latest_message_id",
-            sa.Integer(),
-            sa.ForeignKey("messages.id", ondelete="SET NULL"),
-            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(),
-            onupdate=sa.func.now(),
-        ),
-    )
-    op.create_index(op.f("ix_conversations_id"), "conversations", ["id"], unique=False)
-
-    # Unique pair constraint — populated later via participants
-    op.create_unique_constraint(
-        "uq_conversation_participants",
-        "conversations",
-        ["participant_1_id", "participant_2_id"],
-    )
-
-    # ── conversation_participants ───────────────────────────────────
-
-    op.create_table(
-        "conversation_participants",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "conversation_id",
-            sa.Integer(),
-            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column(
-            "user_id",
-            sa.Integer(),
-            sa.ForeignKey("users.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column("left_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("last_read_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-        ),
-    )
-    op.create_index(
-        op.f("ix_conversation_participants_id"),
-        "conversation_participants",
-        ["id"],
-        unique=False,
-    )
-    op.create_index(
-        op.f("ix_conversation_participants_user_id"),
-        "conversation_participants",
-        ["user_id"],
-        unique=False,
-    )
-    op.create_unique_constraint(
-        "uq_conversation_user",
-        "conversation_participants",
-        ["conversation_id", "user_id"],
-    )
-
-    # ── messages ────────────────────────────────────────────────────
-
-    op.create_table(
-        "messages",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "sender_id",
-            sa.Integer(),
-            sa.ForeignKey("users.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column(
-            "conversation_id",
-            sa.Integer(),
-            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
-            nullable=True,
-        ),
-        sa.Column(
-            "world_id",
-            sa.Integer(),
-            sa.ForeignKey("worlds.id", ondelete="CASCADE"),
-            nullable=True,
-        ),
-        sa.Column("room_id", sa.String(length=36), nullable=True),
-        sa.Column("body", sa.Text(), nullable=False),
-        sa.Column("is_filtered", sa.Boolean(), nullable=False, server_default="false"),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-        ),
-    )
-    op.create_index(op.f("ix_messages_id"), "messages", ["id"], unique=False)
-    op.create_index(
-        "ix_messages_conversation_created",
-        "messages",
-        ["conversation_id", "created_at"],
-    )
-    op.create_index(
-        "ix_messages_world_created",
-        "messages",
-        ["world_id", "created_at"],
-    )
-
-    # ── message_reports ─────────────────────────────────────────────
-
-    op.create_table(
-        "message_reports",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "message_id",
-            sa.Integer(),
-            sa.ForeignKey("messages.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column(
-            "reporter_id",
-            sa.Integer(),
-            sa.ForeignKey("users.id", ondelete="SET NULL"),
-            nullable=False,
-        ),
-        sa.Column(
-            "reason",
-            postgresql.ENUM(
-                "spam", "inappropriate", "off_topic", "other",
-                name="message_report_reason",
-                create_type=False,
-            ),
-            nullable=False,
-        ),
-        sa.Column(
-            "status",
-            postgresql.ENUM(
-                "pending", "resolved", "dismissed",
-                name="message_report_status",
-                create_type=False,
-            ),
-            nullable=False,
-            server_default="pending",
-        ),
-        sa.Column(
-            "moderator_id",
-            sa.Integer(),
-            sa.ForeignKey("users.id", ondelete="SET NULL"),
-            nullable=True,
-        ),
-        sa.Column("resolved_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            server_default=sa.func.now(),
-        ),
-    )
-    op.create_index(op.f("ix_message_reports_id"), "message_reports", ["id"], unique=False)
-
-
-def downgrade() -> None:
-    """Drop chat tables in reverse dependency order."""
-    op.drop_index(op.f("ix_message_reports_id"), table_name="message_reports")
-    op.drop_table("message_reports")
-
-    op.drop_index(op.f("ix_messages_world_created"), table_name="messages")
-    op.drop_index(op.f("ix_messages_conversation_created"), table_name="messages")
-    op.drop_index(op.f("ix_messages_id"), table_name="messages")
-    op.drop_table("messages")
-
-    op.drop_index(op.f("ix_conversation_participants_user_id"), table_name="conversation_participants")
-    op.drop_index(op.f("ix_conversation_participants_id"), table_name="conversation_participants")
-    op.drop_table("conversation_participants")
-
-    op.drop_index(op.f("ix_conversations_id"), table_name="conversations")
-    op.drop_table("conversations")
-
-    # Drop ENUM types
-    postgresql.ENUM(name="message_report_status").drop(op.get_bind(), checkfirst=True)
-    postgresql.ENUM(name="message_report_reason").drop(op.get_bind(), checkfirst=True)

backend/app/models/__init__.py

@@ -2,16 +2,5 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
-from app.models.conversation import Conversation, ConversationParticipant
-from app.models.message import Message, MessageReport
 
-__all__ = [
-    "User",
-    "Session",
-    "World",
-    "Asset",
-    "Conversation",
-    "ConversationParticipant",
-    "Message",
-    "MessageReport",
-]
+__all__ = ["User", "Session", "World", "Asset"]

backend/app/models/asset.py

@@ -3,6 +3,10 @@ from sqlalchemy.dialects.postgresql import ENUM
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 import enum
+import json
+from typing import Optional, List
+
+from pydantic import BaseModel as PydanticBaseModel
 
 from app.database import Base
 
@@ -38,3 +42,31 @@ class Asset(Base):
 
     owner = relationship("User", back_populates="assets")
     world = relationship("World", back_populates="assets")
+
+
+class GLTFMetadata(PydanticBaseModel):
+    """Pydantic schema for glTF asset metadata."""
+    mesh_count: Optional[int] = None
+    vertex_count: Optional[int] = None
+    has_animation: bool = False
+    texture_refs: Optional[List[str]] = None
+    tags: Optional[List[str]] = None
+
+    model_config = {"from_attributes": True}
+
+
+def parse_metadata_json(metadata_text: Optional[str]) -> dict:
+    """Parse the metadata_json text field into a dict, handling None gracefully."""
+    if not metadata_text:
+        return {}
+    try:
+        return json.loads(metadata_text)
+    except (json.JSONDecodeError, TypeError):
+        return {}
+
+
+def serialize_metadata(metadata: dict) -> Optional[str]:
+    """Serialize metadata dict to JSON string for storage."""
+    if not metadata:
+        return None
+    return json.dumps(metadata)

backend/app/models/conversation.py

@@ -1,94 +0,0 @@
-"""Conversation and participant models for DM chat."""
-
-from sqlalchemy import (
-    Column,
-    Integer,
-    String,
-    DateTime,
-    ForeignKey,
-    UniqueConstraint,
-    Index,
-)
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class Conversation(Base):
-    """A DM conversation between two users.
-
-    Each conversation is uniquely identified by the pair of participant
-    user IDs (regardless of order).  A conversation is soft-deletable
-    via ``left_at`` on the participant row.
-    """
-
-    __tablename__ = "conversations"
-
-    id = Column(Integer, primary_key=True, index=True)
-    # The most recent message's ID in this conversation (denormalised
-    # for fast listing; updated by triggers or app logic).
-    latest_message_id = Column(
-        Integer, ForeignKey("messages.id", ondelete="SET NULL"), nullable=True
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
-
-    # Relationships
-    latest_message = relationship(
-        "Message",
-        foreign_keys=[latest_message_id],
-        lazy="select",
-    )
-    participants = relationship(
-        "ConversationParticipant",
-        back_populates="conversation",
-        cascade="all, delete-orphan",
-        order_by="ConversationParticipant.id",
-    )
-
-    __table_args__ = (
-        # Ensure exactly one conversation per unique pair of users
-        UniqueConstraint("participant_1_id", "participant_2_id", name="uq_conversation_participants"),
-    )
-
-    def __repr__(self) -> str:
-        return f"<Conversation id={self.id}>"
-
-
-class ConversationParticipant(Base):
-    """Link table between conversations and users.
-
-    Stores per-participant metadata such as when they left the
-    conversation (for soft-delete / archival).
-    """
-
-    __tablename__ = "conversation_participants"
-
-    id = Column(Integer, primary_key=True, index=True)
-    conversation_id = Column(
-        Integer,
-        ForeignKey("conversations.id", ondelete="CASCADE"),
-        nullable=False,
-    )
-    user_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-    )
-    # When the participant left (NULL = still active).
-    left_at = Column(DateTime(timezone=True), nullable=True)
-    # Timestamp of the last message read by this participant.
-    last_read_at = Column(DateTime(timezone=True), nullable=True)
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    conversation = relationship("Conversation", back_populates="participants")
-    user = relationship("User")
-
-    __table_args__ = (
-        UniqueConstraint("conversation_id", "user_id", name="uq_conversation_user"),
-        Index("ix_conversation_participants_user_id", "user_id"),
-    )
-
-    def __repr__(self) -> str:
-        return f"<ConversationParticipant conversation_id={self.conversation_id} user_id={self.user_id}>"

backend/app/models/message.py

@@ -1,96 +0,0 @@
-"""Message models — messages, message reports."""
-
-from sqlalchemy import (
-    Column,
-    Integer,
-    String,
-    Text,
-    DateTime,
-    ForeignKey,
-    Boolean,
-    Index,
-)
-from sqlalchemy.dialects.postgresql import ENUM
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-import enum
-
-from app.database import Base
-
-
-class MessageReportStatus(str, enum.Enum):
-    PENDING = "pending"
-    RESOLVED = "resolved"
-    DISMISSED = "dismissed"
-
-
-class MessageReportReason(str, enum.Enum):
-    SPAM = "spam"
-    INAPPROPRIATE = "inappropriate"
-    OFF_TOPIC = "off_topic"
-    OTHER = "other"
-
-
-class Message(Base):
-    __tablename__ = "messages"
-
-    id = Column(Integer, primary_key=True, index=True)
-    sender_id = Column(
-        Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False
-    )
-    conversation_id = Column(
-        Integer, ForeignKey("conversations.id", ondelete="CASCADE"), nullable=True
-    )
-    world_id = Column(
-        Integer, ForeignKey("worlds.id", ondelete="CASCADE"), nullable=True
-    )
-    room_id = Column(String(36), nullable=True)
-    body = Column(Text, nullable=False)
-    is_filtered = Column(Boolean, default=False, nullable=False)
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    # Relationships
-    sender = relationship("User", back_populates="sent_messages")
-    conversation = relationship("Conversation", back_populates="messages")
-    world = relationship("World")
-    reports = relationship(
-        "MessageReport", back_populates="message", cascade="all, delete-orphan"
-    )
-
-    # Indexes for history queries
-    __table_args__ = (
-        Index("ix_messages_conversation_created", "conversation_id", "created_at"),
-        Index("ix_messages_world_created", "world_id", "created_at"),
-    )
-
-
-class MessageReport(Base):
-    __tablename__ = "message_reports"
-
-    id = Column(Integer, primary_key=True, index=True)
-    message_id = Column(
-        Integer, ForeignKey("messages.id", ondelete="CASCADE"), nullable=False
-    )
-    reporter_id = Column(
-        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=False
-    )
-    reason = Column(
-        ENUM(MessageReportReason, name="message_report_reason", create_type=False),
-        nullable=False,
-    )
-    details = Column(Text, nullable=True)
-    status = Column(
-        ENUM(MessageReportStatus, name="message_report_status", create_type=False),
-        default=MessageReportStatus.PENDING,
-        nullable=False,
-    )
-    moderator_id = Column(
-        Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True
-    )
-    resolved_at = Column(DateTime(timezone=True), nullable=True)
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    # Relationships
-    message = relationship("Message", back_populates="reports")
-    reporter = relationship("User", foreign_keys=[reporter_id])
-    moderator = relationship("User", foreign_keys=[moderator_id])

backend/app/models/user.py

@@ -1,4 +1,7 @@
-from sqlalchemy import Column, Integer, String, Boolean, DateTime
+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
 
@@ -12,6 +15,7 @@ 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())
@@ -19,14 +23,15 @@ 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")
-    sent_messages = relationship("Message", back_populates="sender")
-    reported_messages = relationship(
-        "MessageReport",
-        foreign_keys="MessageReport.reporter_id",
-        back_populates="reporter",
-    )
-    moderated_reports = relationship(
-        "MessageReport",
-        foreign_keys="MessageReport.moderator_id",
-        back_populates="moderator",
-    )
+
+    @property
+    def is_adult(self) -> bool:
+        """Return True if the user is 18 or older based on date_of_birth."""
+        if self.date_of_birth is None:
+            return False
+        today = date.today()
+        age = today.year - self.date_of_birth.year
+        # Adjust if birthday hasn't occurred yet this year
+        if (today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day):
+            age -= 1
+        return age >= 18

backend/app/routers/auth.py

@@ -1,10 +1,10 @@
 """Authentication router - login, register, token refresh."""
 
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, timedelta, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
-from pydantic import BaseModel, EmailStr
+from pydantic import BaseModel, EmailStr, field_validator
 
 from jose import jwt
 from passlib.context import CryptContext
@@ -32,12 +32,24 @@ 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
 
@@ -65,11 +77,44 @@ 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():
@@ -90,6 +135,7 @@ async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
         username=req.username,
         email=req.email,
         hashed_password=hash_password(req.password),
+        date_of_birth=dob,
     )
     db.add(user)
     await db.commit()

backend/pytest.ini

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

backend/tests/test_auth_age_gate.py

@@ -0,0 +1,94 @@
+"""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)

docs/planning/economy.md

@@ -0,0 +1,295 @@
+# 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).