Add chat data models + migration (conversations, messages, reports)

docs/planning/social.md US-4, task 6: conversations,
conversation_participants, messages (DM + world/room chat), and
message_reports, following app/models/social.py's conventions (native
enums, explicit index/constraint names, CASCADE FKs where appropriate).

Delete behavior, chosen per-relationship:
- conversations.user_a_id/user_b_id -> CASCADE: a DM is meaningless with
  one of its two participants gone, so it cascades away entirely
  (participants + messages with it).
- messages.sender_id -> SET NULL: world/room chat history and reported
  messages must survive the sender's account being deleted, matching the
  existing actor-reference convention (WorldChunk.updated_by_id,
  WorldChunkRevision.actor_id).
- messages.world_id/room_id -> CASCADE: chat scoped to a world/room has no
  meaning once that world/room is gone (mirrors WorldChunk).
- message_reports.message_id -> SET NULL (not CASCADE): a moderation
  report must outlive the message it's about, mirroring
  WorldChunkRevision's audit-trail-survives-deletion precedent.
- message_reports.reporter_id/moderator_id -> SET NULL: audit-actor
  references, same reasoning.

Models + migration only, no endpoints, no text filtering (sibling tasks).

Verified: migration upgrade/downgrade/upgrade round-trip against a real
Postgres with schema inspected via \d against spec; new model tests cover
DM creation, pair uniqueness + ordering check constraint, world/room
messages, report defaults, and cascade behavior for both
conversation-deletion and sender-deletion; full backend suite (160 tests)
passes with no regressions.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2FESCaMXeJpC9gSctiEeD

assets/editor/object_catalog.json

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

backend/alembic/versions/0006_add_presence_columns.py

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

backend/alembic/versions/0007_add_social_graph_tables.py

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

backend/alembic/versions/0008_add_chat_tables.py

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

backend/app/main.py

@@ -6,7 +6,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.config import settings
-from app.routers import auth, users, worlds, assets, avatar, world_content, internal
+from app.routers import auth, users, worlds, assets, avatar, world_content, internal, presence
 
 
 from app.services.game_servers import supervisor
@@ -44,6 +44,7 @@ app.include_router(world_content.router, prefix="/api/worlds", tags=["world-cont
 app.include_router(assets.router, prefix="/api/assets", tags=["assets"])
 app.include_router(avatar.router, prefix="/api/avatar", tags=["avatar"])
 app.include_router(internal.router, prefix="/api/internal", tags=["internal"])
+app.include_router(presence.router, prefix="/api/presence", tags=["presence"])
 
 
 @app.get("/api/health")

backend/app/models/__init__.py

@@ -4,8 +4,14 @@ from app.models.world import World
 from app.models.asset import Asset
 from app.models.avatar_loadout import AvatarLoadout
 from app.models.world_content import WorldRoom, WorldChunk, WorldChunkRevision
+from app.models.social import Friendship, Follow, Block, FriendshipStatus
+from app.models.chat import (
+    Conversation, ConversationParticipant, Message, MessageReport, ReportStatus,
+)
 
 __all__ = [
     "User", "Session", "World", "Asset", "AvatarLoadout",
     "WorldRoom", "WorldChunk", "WorldChunkRevision",
+    "Friendship", "Follow", "Block", "FriendshipStatus",
+    "Conversation", "ConversationParticipant", "Message", "MessageReport", "ReportStatus",
 ]

backend/app/models/chat.py

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

backend/app/models/social.py

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

backend/app/models/user.py

@@ -1,7 +1,7 @@
 from datetime import date
 from typing import Optional
 
-from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date, Text
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 
@@ -20,6 +20,10 @@ class User(Base):
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     updated_at = Column(DateTime(timezone=True), onupdate=func.now())
 
+    # Presence / status (backend/app/services/presence.py, app/routers/presence.py)
+    last_seen_at = Column(DateTime(timezone=True), nullable=True)
+    status_message = Column(Text, nullable=True)
+
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
     refresh_tokens = relationship("RefreshToken", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
@@ -31,6 +35,44 @@ class User(Base):
         cascade="all, delete-orphan",
     )
 
+    # Social graph (docs/planning/social.md US-1; app/models/social.py)
+    sent_friend_requests = relationship(
+        "Friendship",
+        foreign_keys="Friendship.requester_id",
+        back_populates="requester",
+        cascade="all, delete-orphan",
+    )
+    received_friend_requests = relationship(
+        "Friendship",
+        foreign_keys="Friendship.addressee_id",
+        back_populates="addressee",
+        cascade="all, delete-orphan",
+    )
+    following = relationship(
+        "Follow",
+        foreign_keys="Follow.follower_id",
+        back_populates="follower",
+        cascade="all, delete-orphan",
+    )
+    followers = relationship(
+        "Follow",
+        foreign_keys="Follow.followed_id",
+        back_populates="followed",
+        cascade="all, delete-orphan",
+    )
+    blocks_initiated = relationship(
+        "Block",
+        foreign_keys="Block.blocker_id",
+        back_populates="blocker",
+        cascade="all, delete-orphan",
+    )
+    blocked_by = relationship(
+        "Block",
+        foreign_keys="Block.blocked_id",
+        back_populates="blocked",
+        cascade="all, delete-orphan",
+    )
+
     @property
     def is_adult(self) -> bool:
         """Return True if the user is 18 or older based on date_of_birth."""

backend/app/routers/presence.py

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

backend/app/services/presence.py

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

backend/tests/conftest.py

@@ -1,15 +1,18 @@
-"""Shared pytest fixtures + hermetic-DB bootstrap.
+"""Shared pytest fixtures + hermetic-DB/Redis bootstrap.
 
 The integration tests hit a real Postgres (Postgres-specific types: JSONB,
-native ENUMs). To make ``cd backend && pytest`` work from a clean checkout
-with no manual setup, ``pytest_configure`` below brings up an ephemeral
-Postgres via docker compose and runs the migrations IF ``DATABASE_URL`` is
-not already pointing at a reachable database. When it is (dev loop, or the
-checkpoint runner which stands the DB up itself), that path is skipped and
-the existing database is reused.
+native ENUMs) and, for presence tests, a real Redis (TTL semantics aren't
+worth faking). To make ``cd backend && pytest`` work from a clean checkout
+with no manual setup, ``pytest_configure`` below brings up ephemeral
+Postgres/Redis containers via docker compose and runs the migrations IF
+``DATABASE_URL``/``REDIS_URL`` aren't already pointing at something
+reachable. When they are (dev loop, or the checkpoint runner which stands
+these up itself), that path is skipped and the existing services are
+reused.
 
-If Docker isn't available and no DB is reachable, the whole DB-backed suite
-is skipped with a clear message rather than erroring out 60+ times.
+If Docker isn't available and nothing is reachable, the whole
+DB/Redis-backed suite is skipped with a clear message rather than erroring
+out dozens of times.
 """
 
 import asyncio
@@ -38,14 +41,24 @@ TEST_TABLES = (
     # `worlds` the way world_rooms/world_chunks would be. List all three
     # explicitly rather than rely on cascade for some of them.
     "world_chunk_revisions", "world_chunks", "world_rooms",
-    "worlds", "sessions", "refresh_tokens", "users",
+    "worlds",
+    # Social graph (app/models/social.py) -- all three FK users with
+    # ON DELETE CASCADE, but list explicitly for clarity/consistency.
+    "friendships", "follows", "blocks",
+    # Chat (app/models/chat.py). message_reports.message_id is ON DELETE SET
+    # NULL (not CASCADE, deliberately -- see chat.py), so it wouldn't be
+    # reached by cascading a truncate of messages/conversations; list it
+    # explicitly along with the rest for clarity/consistency.
+    "message_reports", "messages", "conversation_participants", "conversations",
+    "sessions", "refresh_tokens", "users",
 )
 
 BACKEND_DIR = Path(__file__).resolve().parents[1]
 _COMPOSE_PROJECT = "agp-pytest"
 _EPHEMERAL_PG_PORT = 25432
+_EPHEMERAL_REDIS_PORT = 26379
 
-# Set by _ensure_database() when it starts a container it owns; torn down in
+# Set by pytest_configure() when it starts container(s) it owns; torn down in
 # pytest_unconfigure.
 _started_container = False
 _db_unavailable_reason: str | None = None
@@ -64,6 +77,11 @@ def _db_reachable(url: str) -> bool:
     return _port_open(parts.hostname or "localhost", parts.port or 5432)
 
 
+def _redis_reachable(url: str) -> bool:
+    parts = urlsplit(url)
+    return _port_open(parts.hostname or "localhost", parts.port or 6379)
+
+
 def _run(cmd: list[str], **kw) -> subprocess.CompletedProcess:
     return subprocess.run(cmd, cwd=BACKEND_DIR, capture_output=True, text=True, **kw)
 
@@ -71,14 +89,17 @@ def _run(cmd: list[str], **kw) -> subprocess.CompletedProcess:
 def pytest_configure(config):
     global _started_container, _db_unavailable_reason
 
-    if _db_reachable(settings.DATABASE_URL):
-        return  # dev loop / checkpoint runner already provided one
+    need_db = not _db_reachable(settings.DATABASE_URL)
+    need_redis = not _redis_reachable(settings.REDIS_URL)
+
+    if not need_db and not need_redis:
+        return  # dev loop / checkpoint runner already provided both
 
     if not _run(["docker", "--version"]).returncode == 0:
         _db_unavailable_reason = (
-            "no reachable DATABASE_URL and docker is unavailable -- run the "
-            "checkpoint suite (scripts/run_checkpoint_tests.py) or start Postgres "
-            "manually"
+            "no reachable DATABASE_URL/REDIS_URL and docker is unavailable -- run "
+            "the checkpoint suite (scripts/run_checkpoint_tests.py) or start "
+            "Postgres/Redis manually"
         )
         return
 
@@ -86,33 +107,55 @@ def pytest_configure(config):
     env["COMPOSE_PROJECT_NAME"] = _COMPOSE_PROJECT
     env["POSTGRES_HOST_PORT"] = str(_EPHEMERAL_PG_PORT)
     env["POSTGRES_PORT"] = str(_EPHEMERAL_PG_PORT)
-    up = _run(["docker", "compose", "up", "-d", "postgres"], env=env)
+    env["REDIS_HOST_PORT"] = str(_EPHEMERAL_REDIS_PORT)
+
+    services = [s for s, need in (("postgres", need_db), ("redis", need_redis)) if need]
+    up = _run(["docker", "compose", "up", "-d", *services], env=env)
     if up.returncode != 0:
-        _db_unavailable_reason = f"docker compose up postgres failed:\n{up.stderr[-800:]}"
+        _db_unavailable_reason = f"docker compose up {' '.join(services)} failed:\n{up.stderr[-800:]}"
         return
     _started_container = True
 
-    for _ in range(30):
-        r = _run(
-            ["docker", "compose", "exec", "-T", "postgres",
-             "pg_isready", "-U", "agp_user", "-d", "agp_db"],
-            env=env,
-        )
-        if r.returncode == 0:
-            break
-        time.sleep(1)
-    else:
-        _db_unavailable_reason = "ephemeral Postgres never became ready"
-        return
+    if need_db:
+        for _ in range(30):
+            r = _run(
+                ["docker", "compose", "exec", "-T", "postgres",
+                 "pg_isready", "-U", "agp_user", "-d", "agp_db"],
+                env=env,
+            )
+            if r.returncode == 0:
+                break
+            time.sleep(1)
+        else:
+            _db_unavailable_reason = "ephemeral Postgres never became ready"
+            return
 
-    url = f"postgresql+asyncpg://agp_user:agp_password@localhost:{_EPHEMERAL_PG_PORT}/agp_db"
-    os.environ["DATABASE_URL"] = url
-    settings.DATABASE_URL = url
+        url = f"postgresql+asyncpg://agp_user:agp_password@localhost:{_EPHEMERAL_PG_PORT}/agp_db"
+        os.environ["DATABASE_URL"] = url
+        settings.DATABASE_URL = url
 
-    mig = _run([sys.executable, "-m", "alembic", "upgrade", "head"],
-               env={**os.environ, "DATABASE_URL": url})
-    if mig.returncode != 0:
-        _db_unavailable_reason = f"alembic upgrade head failed:\n{mig.stderr[-800:]}"
+        mig = _run([sys.executable, "-m", "alembic", "upgrade", "head"],
+                   env={**os.environ, "DATABASE_URL": url})
+        if mig.returncode != 0:
+            _db_unavailable_reason = f"alembic upgrade head failed:\n{mig.stderr[-800:]}"
+            return
+
+    if need_redis:
+        for _ in range(30):
+            r = _run(
+                ["docker", "compose", "exec", "-T", "redis", "redis-cli", "ping"],
+                env=env,
+            )
+            if r.returncode == 0 and "PONG" in r.stdout:
+                break
+            time.sleep(1)
+        else:
+            _db_unavailable_reason = "ephemeral Redis never became ready"
+            return
+
+        redis_url = f"redis://localhost:{_EPHEMERAL_REDIS_PORT}/0"
+        os.environ["REDIS_URL"] = redis_url
+        settings.REDIS_URL = redis_url
 
 
 def pytest_unconfigure(config):
@@ -122,6 +165,7 @@ def pytest_unconfigure(config):
     env["COMPOSE_PROJECT_NAME"] = _COMPOSE_PROJECT
     env["POSTGRES_HOST_PORT"] = str(_EPHEMERAL_PG_PORT)
     env["POSTGRES_PORT"] = str(_EPHEMERAL_PG_PORT)
+    env["REDIS_HOST_PORT"] = str(_EPHEMERAL_REDIS_PORT)
     _run(["docker", "compose", "down", "-v"], env=env)
 
 

backend/tests/test_chat_models.py

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

backend/tests/test_presence.py

@@ -0,0 +1,221 @@
+"""Integration tests for the presence feature:
+
+- POST  /api/presence/heartbeat
+- GET   /api/presence/presence
+- PATCH /api/presence/status
+
+Hits the real app against the configured Postgres *and* a real Redis
+(conftest.py brings up an ephemeral instance of each when neither is
+already reachable) -- presence is fundamentally "does a TTL key exist in
+Redis", which isn't worth faking with a mock.
+
+Also covers the regression fixed in 47ab492 ("Fix StatusUpdate field
+annotation and is_online batch-call mismatch"): the router used to call
+``PresenceStore.is_online(ids)`` with a *list* of ids and then evaluate
+``uid in online_ids`` against the returned bool, which raised a TypeError
+on the first real multi-id batch call, and ``StatusUpdate.status_message``
+used the invalid annotation ``str | Field(...)``. Both are exercised below.
+"""
+
+import asyncio
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.main import app
+from app.services.presence import PresenceStore
+
+
+def _register(client: TestClient, username: str) -> dict:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    token = resp.json()["access_token"]
+    headers = {"Authorization": f"Bearer {token}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return {"headers": headers, "id": me.json()["id"]}
+
+
+class TestHeartbeat:
+    def test_heartbeat_sets_online(self):
+        client = TestClient(app)
+        user = _register(client, "presence_hb1")
+
+        resp = client.post("/api/presence/heartbeat", json={}, headers=user["headers"])
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"status": "ok", "user_id": user["id"]}
+
+        presence = client.get(
+            "/api/presence/presence",
+            params={"user_ids": str(user["id"])},
+            headers=user["headers"],
+        )
+        assert presence.status_code == 200, presence.text
+        body = presence.json()["users"]
+        assert len(body) == 1
+        assert body[0]["user_id"] == user["id"]
+        assert body[0]["is_online"] is True
+        assert body[0]["last_seen_at"] is not None
+
+    def test_requires_auth(self):
+        client = TestClient(app)
+        resp = client.post("/api/presence/heartbeat", json={})
+        assert resp.status_code == 401
+
+    def test_never_seen_user_is_offline_with_null_last_seen(self):
+        client = TestClient(app)
+        user = _register(client, "presence_never_hb")
+
+        presence = client.get(
+            "/api/presence/presence",
+            params={"user_ids": str(user["id"])},
+            headers=user["headers"],
+        )
+        assert presence.status_code == 200
+        body = presence.json()["users"][0]
+        assert body["is_online"] is False
+        assert body["last_seen_at"] is None
+
+
+class TestBatchPresence:
+    """Covers the batch-call path fixed in 47ab492 (is_online_batch via MGET)."""
+
+    def test_batch_query_mixes_online_offline_and_unknown_ids(self):
+        client = TestClient(app)
+        online_user = _register(client, "presence_batch_online")
+        offline_user = _register(client, "presence_batch_offline")
+
+        client.post("/api/presence/heartbeat", json={}, headers=online_user["headers"])
+
+        unknown_id = max(online_user["id"], offline_user["id"]) + 999_999
+        ids = f"{online_user['id']},{offline_user['id']},{unknown_id}"
+
+        resp = client.get(
+            "/api/presence/presence",
+            params={"user_ids": ids},
+            headers=online_user["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        by_id = {u["user_id"]: u for u in resp.json()["users"]}
+
+        # Unknown id is silently dropped (not in the DB), not a 500 or 404.
+        assert unknown_id not in by_id
+        assert by_id[online_user["id"]]["is_online"] is True
+        assert by_id[offline_user["id"]]["is_online"] is False
+
+    def test_empty_user_ids_is_a_400(self):
+        client = TestClient(app)
+        user = _register(client, "presence_empty_ids")
+        resp = client.get(
+            "/api/presence/presence",
+            params={"user_ids": ""},
+            headers=user["headers"],
+        )
+        assert resp.status_code == 400
+
+
+class TestStatusMessage:
+    def test_update_and_read_back_status_message(self):
+        client = TestClient(app)
+        user = _register(client, "presence_status1")
+
+        resp = client.patch(
+            "/api/presence/status",
+            json={"status_message": "  brb, making coffee  "},
+            headers=user["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+        # The router strips whitespace (StatusUpdate.strip_message).
+        assert resp.json()["status_message"] == "brb, making coffee"
+
+        presence = client.get(
+            "/api/presence/presence",
+            params={"user_ids": str(user["id"])},
+            headers=user["headers"],
+        )
+        assert presence.json()["users"][0]["status_message"] == "brb, making coffee"
+
+    def test_status_message_over_max_length_is_rejected(self):
+        client = TestClient(app)
+        user = _register(client, "presence_status_toolong")
+        resp = client.patch(
+            "/api/presence/status",
+            json={"status_message": "x" * 141},
+            headers=user["headers"],
+        )
+        # StatusUpdate.status_message: str | None = Field(..., max_length=140)
+        # This is exactly the annotation 47ab492 fixed (it used to be the
+        # invalid `str | Field(...)`, which breaks model construction
+        # entirely rather than validating length).
+        assert resp.status_code == 422
+
+    def test_status_message_at_max_length_is_accepted(self):
+        client = TestClient(app)
+        user = _register(client, "presence_status_maxlen")
+        resp = client.patch(
+            "/api/presence/status",
+            json={"status_message": "x" * 140},
+            headers=user["headers"],
+        )
+        assert resp.status_code == 200, resp.text
+
+    def test_null_status_message_clears_it(self):
+        client = TestClient(app)
+        user = _register(client, "presence_status_clear")
+        client.patch("/api/presence/status", json={"status_message": "hi"}, headers=user["headers"])
+        resp = client.patch("/api/presence/status", json={"status_message": None}, headers=user["headers"])
+        assert resp.status_code == 200
+        assert resp.json()["status_message"] is None
+
+
+class TestPresenceStoreTTL:
+    """Exercises the real Redis TTL semantics directly against the service,
+    with a short heartbeat_ttl so the test doesn't need to sleep for the
+    real 60s default used in production. This is the cheap, real proxy for
+    "TTL expiry means offline" the task asked for -- same code path
+    (real Redis SET ... EX / EXISTS / MGET), just a much shorter window.
+    """
+
+    async def test_ttl_expiry_flips_online_to_offline(self):
+        store = PresenceStore(heartbeat_ttl=1)
+        try:
+            uid = 987654321  # doesn't need to exist in Postgres; Redis-only check
+            assert await store.is_online(uid) is False
+
+            await store.heartbeat(uid)
+            assert await store.is_online(uid) is True
+
+            await asyncio.sleep(1.5)
+            assert await store.is_online(uid) is False
+        finally:
+            await store.close()
+
+    async def test_is_online_batch_matches_is_online_semantics(self):
+        """Regression coverage for 47ab492: is_online_batch must return a
+        set of ids usable with `in`, not a bool."""
+        store = PresenceStore(heartbeat_ttl=30)
+        try:
+            online_uid, offline_uid = 111222333, 444555666
+            await store.heartbeat(online_uid)
+
+            result = await store.is_online_batch([online_uid, offline_uid])
+            assert isinstance(result, set)
+            assert online_uid in result
+            assert offline_uid not in result
+        finally:
+            await store.close()
+
+    async def test_is_online_batch_empty_list(self):
+        store = PresenceStore()
+        try:
+            assert await store.is_online_batch([]) == set()
+        finally:
+            await store.close()

backend/tests/test_social_models.py

@@ -0,0 +1,240 @@
+"""Model-level tests for the social graph: friendships, follows, blocks.
+
+app/models/social.py / alembic/versions/0007_add_social_graph_tables.py
+(docs/planning/social.md US-1). This is the models+migration task only --
+there are no API endpoints yet (a sibling task owns the router), so these
+tests exercise the ORM models and the real Postgres constraints directly
+rather than going through HTTP.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import delete, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.models.social import Friendship, Follow, Block, FriendshipStatus
+from app.models.user import User
+
+
+def _register(client: TestClient, username: str) -> int:
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "1990-01-01",
+        },
+    )
+    assert resp.status_code == 201, resp.text
+    headers = {"Authorization": f"Bearer {resp.json()['access_token']}"}
+    me = client.get("/api/users/me", headers=headers)
+    assert me.status_code == 200, me.text
+    return me.json()["id"]
+
+
+def _session_factory():
+    engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    return engine, async_sessionmaker(engine, expire_on_commit=False)
+
+
+class TestFriendshipRequestAccept:
+    async def test_request_defaults_to_pending(self):
+        client = TestClient(app)
+        a = _register(client, "sg_fr_a1")
+        b = _register(client, "sg_fr_b1")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                fr = Friendship(requester_id=a, addressee_id=b)
+                session.add(fr)
+                await session.commit()
+                await session.refresh(fr)
+                assert fr.status == FriendshipStatus.PENDING
+                assert fr.requester_id == a
+                assert fr.addressee_id == b
+        finally:
+            await engine.dispose()
+
+    async def test_accept_updates_status(self):
+        client = TestClient(app)
+        a = _register(client, "sg_fr_a2")
+        b = _register(client, "sg_fr_b2")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                fr = Friendship(requester_id=a, addressee_id=b)
+                session.add(fr)
+                await session.commit()
+                fr_id = fr.id
+
+            async with factory() as session:
+                fr = await session.get(Friendship, fr_id)
+                fr.status = FriendshipStatus.ACCEPTED
+                await session.commit()
+
+            async with factory() as session:
+                fr = await session.get(Friendship, fr_id)
+                assert fr.status == FriendshipStatus.ACCEPTED
+        finally:
+            await engine.dispose()
+
+
+class TestUniquePairConstraints:
+    async def test_duplicate_friendship_pair_rejected(self):
+        client = TestClient(app)
+        a = _register(client, "sg_uq_fr_a")
+        b = _register(client, "sg_uq_fr_b")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                session.add(Friendship(requester_id=a, addressee_id=b))
+                await session.commit()
+
+            async with factory() as session:
+                session.add(Friendship(requester_id=a, addressee_id=b))
+                with pytest.raises(IntegrityError):
+                    await session.commit()
+        finally:
+            await engine.dispose()
+
+    async def test_duplicate_follow_pair_rejected(self):
+        client = TestClient(app)
+        a = _register(client, "sg_uq_fw_a")
+        b = _register(client, "sg_uq_fw_b")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                session.add(Follow(follower_id=a, followed_id=b))
+                await session.commit()
+
+            async with factory() as session:
+                session.add(Follow(follower_id=a, followed_id=b))
+                with pytest.raises(IntegrityError):
+                    await session.commit()
+        finally:
+            await engine.dispose()
+
+    async def test_duplicate_block_pair_rejected(self):
+        client = TestClient(app)
+        a = _register(client, "sg_uq_bl_a")
+        b = _register(client, "sg_uq_bl_b")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                session.add(Block(blocker_id=a, blocked_id=b))
+                await session.commit()
+
+            async with factory() as session:
+                session.add(Block(blocker_id=a, blocked_id=b))
+                with pytest.raises(IntegrityError):
+                    await session.commit()
+        finally:
+            await engine.dispose()
+
+
+class TestFollow:
+    async def test_create_follow(self):
+        client = TestClient(app)
+        a = _register(client, "sg_follow_a")
+        b = _register(client, "sg_follow_b")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                session.add(Follow(follower_id=a, followed_id=b))
+                await session.commit()
+
+            async with factory() as session:
+                rows = (await session.execute(
+                    select(Follow).where(Follow.follower_id == a, Follow.followed_id == b)
+                )).scalars().all()
+                assert len(rows) == 1
+        finally:
+            await engine.dispose()
+
+
+class TestBlock:
+    async def test_create_block(self):
+        client = TestClient(app)
+        a = _register(client, "sg_block_a")
+        b = _register(client, "sg_block_b")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                session.add(Block(blocker_id=a, blocked_id=b))
+                await session.commit()
+
+            async with factory() as session:
+                rows = (await session.execute(
+                    select(Block).where(Block.blocker_id == a, Block.blocked_id == b)
+                )).scalars().all()
+                assert len(rows) == 1
+        finally:
+            await engine.dispose()
+
+
+class TestCascadeDelete:
+    async def test_deleting_user_removes_rows_in_all_three_tables(self):
+        """Deleting a user removes friendships/follows/blocks referencing them
+        in *either* FK column, via the real DB ON DELETE CASCADE (deleted with
+        a Core statement, bypassing any ORM-level cascade, to prove the
+        database constraint itself does the job)."""
+        client = TestClient(app)
+        a = _register(client, "sg_cascade_a")
+        b = _register(client, "sg_cascade_b")
+        c = _register(client, "sg_cascade_c")
+
+        engine, factory = _session_factory()
+        try:
+            async with factory() as session:
+                # a as requester/follower/blocker, and also as addressee (c -> a)
+                session.add(Friendship(requester_id=a, addressee_id=b))
+                session.add(Friendship(requester_id=c, addressee_id=a))
+                session.add(Follow(follower_id=a, followed_id=b))
+                session.add(Follow(follower_id=c, followed_id=a))
+                session.add(Block(blocker_id=a, blocked_id=b))
+                session.add(Block(blocker_id=c, blocked_id=a))
+                await session.commit()
+
+            async with factory() as session:
+                await session.execute(delete(User).where(User.id == a))
+                await session.commit()
+
+            async with factory() as session:
+                friendships = (await session.execute(
+                    select(Friendship).where(
+                        (Friendship.requester_id == a) | (Friendship.addressee_id == a)
+                    )
+                )).scalars().all()
+                follows = (await session.execute(
+                    select(Follow).where(
+                        (Follow.follower_id == a) | (Follow.followed_id == a)
+                    )
+                )).scalars().all()
+                blocks = (await session.execute(
+                    select(Block).where(
+                        (Block.blocker_id == a) | (Block.blocked_id == a)
+                    )
+                )).scalars().all()
+                assert friendships == []
+                assert follows == []
+                assert blocks == []
+
+                # Unrelated rows (b, c only) survive.
+                remaining_users = (await session.execute(
+                    select(User.id).where(User.id.in_([b, c]))
+                )).scalars().all()
+                assert set(remaining_users) == {b, c}
+        finally:
+            await engine.dispose()

project.godot

@@ -50,6 +50,11 @@ interact={
 "events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":69,"key_label":0,"unicode":101,"location":0,"echo":false,"script":null)
 ]
 }
+toggle_build_mode={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194333,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
+]
+}
 
 [physics]
 

scripts/chunk_data_decoder.gd

@@ -100,6 +100,17 @@ class TileLayerData:
 			return tiles[idx]
 		return 0
 
+	## Editor mutator: writes `tile_id` at (x, y, z). Silently no-ops out of
+	## bounds, mirroring get_tile's "out of bounds is empty" contract rather
+	## than erroring -- callers that need bounds feedback should check first
+	## (see ChunkEditorModel.is_tile_in_bounds in scripts/editor/).
+	func set_tile(x: int, y: int, z: int, tile_id: int) -> void:
+		if x < 0 or x >= width or y < 0 or y >= height or z < 0 or z >= depth:
+			return
+		var idx := (z * height + y) * width + x
+		if idx < tiles.size():
+			tiles[idx] = tile_id
+
 	func get_tile_def(tile_id: int) -> TileDef:
 		for def in palette:
 			if def.id == tile_id:

scripts/editor/chunk_editor_model.gd

@@ -0,0 +1,190 @@
+class_name ChunkEditorModel
+extends RefCounted
+## In-memory chunk being edited (docs/architecture/editor.md §7.1's
+## `ChunkEditorModel`).
+##
+## Wraps a `ChunkDataDecoder.ChunkPayload` directly rather than inventing a
+## parallel data model -- that payload is already the exact structure that
+## round-trips through `ChunkDataDecoder.encode_binary()` /
+## `decode_binary()` (world.md §3.6, and the interop bugs fixed in that file
+## are proof this contract is exercised for real). Editing this model and
+## re-encoding it must always produce a valid, byte-compatible chunk, since
+## the sibling save-path task depends on that being true.
+##
+## Every method here is a "raw" mutator: it changes the payload and returns
+## whatever an undo needs to reverse the change, but it does **not** know
+## about undo/redo itself. `scripts/editor/editor_core.gd`'s tools
+## (scripts/editor/tools/*.gd) are the only things that call these -- they
+## wrap each call in an `EditorUndoRedoStack` action. Nothing here should be
+## called directly by UI code; that would bypass undo/redo silently.
+
+var payload: ChunkDataDecoder.ChunkPayload
+
+## Monotonic counter seeded from the highest existing "obj_NNNN"-style
+## numeric suffix already in the chunk, so freshly generated ids never
+## collide with ids that arrived from a decoded chunk.
+var _next_object_seq: int = 0
+
+
+func _init(p_payload: ChunkDataDecoder.ChunkPayload = null) -> void:
+	payload = p_payload if p_payload != null else ChunkDataDecoder.ChunkPayload.new()
+	_seed_object_sequence()
+
+
+func _seed_object_sequence() -> void:
+	for obj in payload.objects:
+		var n := _numeric_suffix(obj.id)
+		if n >= _next_object_seq:
+			_next_object_seq = n + 1
+
+
+static func _numeric_suffix(id: String) -> int:
+	var digits := ""
+	for i in range(id.length() - 1, -1, -1):
+		var c: String = id[i]
+		if c.is_valid_int():
+			digits = c + digits
+		else:
+			break
+	return int(digits) if digits != "" else -1
+
+
+## Build a fresh, empty single-layer chunk model -- convenient for tests and
+## for a "new chunk" starting point in the in-game editor before a real
+## chunk has been loaded from the backend (loading real chunks over HTTP is
+## HttpChunkSource's job; this just gives the editor something valid to
+## operate on).
+static func create_empty(width: int = 32, height: int = 32, world_id: String = "",
+		room_id: String = "main", coord: Vector3i = Vector3i.ZERO) -> ChunkEditorModel:
+	var layer := ChunkDataDecoder.TileLayerData.new()
+	layer.name = "ground"
+	layer.layer_id = 0
+	layer.width = width
+	layer.height = height
+	layer.depth = 1
+	layer.palette = [
+		TileDef.new(0, "", false, 0, 1),
+		TileDef.new(1, "tiles/default", true, 0, 1),
+	]
+	var tiles := PackedInt32Array()
+	tiles.resize(width * height)
+	layer.tiles = tiles
+
+	var payload := ChunkDataDecoder.ChunkPayload.new()
+	payload.world_id = world_id
+	payload.room_id = room_id
+	payload.coord = coord
+	payload.bounds = AABB(Vector3(coord.x * width, coord.y * height, coord.z), Vector3(width, height, 1))
+	payload.tile_layers = [layer]
+	payload.revision = 0
+	payload.created_at = Time.get_unix_time_from_system()
+	payload.updated_at = payload.created_at
+	return ChunkEditorModel.new(payload)
+
+
+static func from_binary(data: PackedByteArray) -> ChunkEditorModel:
+	var decoded := ChunkDataDecoder.decode_binary(data)
+	if decoded == null:
+		return null
+	return ChunkEditorModel.new(decoded)
+
+
+func encode_binary() -> PackedByteArray:
+	return ChunkDataDecoder.encode_binary(payload)
+
+
+# ───────────────────────── tiles ─────────────────────────
+
+func get_layer(layer_idx: int) -> ChunkDataDecoder.TileLayerData:
+	if layer_idx < 0 or layer_idx >= payload.tile_layers.size():
+		return null
+	return payload.tile_layers[layer_idx]
+
+
+func is_tile_in_bounds(layer_idx: int, x: int, y: int, z: int = 0) -> bool:
+	var layer := get_layer(layer_idx)
+	if layer == null:
+		return false
+	return x >= 0 and x < layer.width and y >= 0 and y < layer.height and z >= 0 and z < layer.depth
+
+
+func get_tile_raw(layer_idx: int, x: int, y: int, z: int = 0) -> int:
+	var layer := get_layer(layer_idx)
+	if layer == null:
+		return 0
+	return layer.get_tile(x, y, z)
+
+
+## Raw setter -- undo-unaware. Only ever called (in both directions) by
+## BrushTool/EraseTool via EditorUndoRedoStack.
+func set_tile_raw(layer_idx: int, x: int, y: int, z: int, tile_id: int) -> void:
+	var layer := get_layer(layer_idx)
+	if layer == null:
+		return
+	layer.set_tile(x, y, z, tile_id)
+
+
+# ───────────────────────── objects ─────────────────────────
+
+func find_object(object_id: String) -> ChunkDataDecoder.WorldObjectData:
+	for obj in payload.objects:
+		if obj.id == object_id:
+			return obj
+	return null
+
+
+func get_object_index(object_id: String) -> int:
+	for i in range(payload.objects.size()):
+		if payload.objects[i].id == object_id:
+			return i
+	return -1
+
+
+func generate_object_id() -> String:
+	var id := "obj_%04d" % _next_object_seq
+	_next_object_seq += 1
+	return id
+
+
+## Raw mutators -- undo-unaware. Only ever called (in both directions) by
+## ObjectPlaceTool/EraseTool/TransformTool via EditorUndoRedoStack.
+func add_object_raw(obj: ChunkDataDecoder.WorldObjectData) -> void:
+	payload.objects.append(obj)
+
+
+func insert_object_raw(obj: ChunkDataDecoder.WorldObjectData, index: int) -> void:
+	var clamped: int = clampi(index, 0, payload.objects.size())
+	payload.objects.insert(clamped, obj)
+
+
+func remove_object_raw(object_id: String) -> ChunkDataDecoder.WorldObjectData:
+	var idx := get_object_index(object_id)
+	if idx == -1:
+		return null
+	var obj := payload.objects[idx]
+	payload.objects.remove_at(idx)
+	return obj
+
+
+func set_object_position_raw(object_id: String, position: Vector3) -> void:
+	var obj := find_object(object_id)
+	if obj != null:
+		obj.position = position
+
+
+func set_object_rotation_raw(object_id: String, rotation: Vector4) -> void:
+	var obj := find_object(object_id)
+	if obj != null:
+		obj.rotation = rotation
+
+
+func set_object_scale_raw(object_id: String, scale: Vector3) -> void:
+	var obj := find_object(object_id)
+	if obj != null:
+		obj.scale = scale
+
+
+func set_object_property_raw(object_id: String, key: String, value: Variant) -> void:
+	var obj := find_object(object_id)
+	if obj != null:
+		obj.properties[key] = value

scripts/editor/chunk_save_service.gd

@@ -0,0 +1,280 @@
+class_name ChunkSaveService
+extends Node
+## HTTP save path for the in-game editor
+## (docs/architecture/world_persistence_impl.md §8.1 chunk write / §8.2 D5).
+##
+## Owns the write half of editor persistence: single-chunk PUT with
+## `X-Base-Revision`/`base_revision`, batch PUT for a multi-chunk edit, and
+## the §5.4 optimistic-concurrency retry loop on `409`.
+##
+## Conflict handling ("re-fetch current chunk, re-apply the edit, retry"):
+## per §8.2 D5 this backend stores and accepts **whole chunks**, not
+## JSON-Patch deltas -- "lost-update protection comes from `base_revision`,
+## not from the patch". That means there is no delta to replay against a
+## freshly-fetched chunk; "re-apply the edit" is exactly "keep the locally
+## edited payload, learn the chunk's current revision, and retry at that
+## revision". `fetch_chunk()` is still called on a conflict (rather than
+## just trusting the 409 body's `current_revision`) so the editor's own
+## last-known state stays in sync with the store, matching what a real
+## client does before retrying a write it doesn't fully trust yet.
+##
+## Deliberately does **not** use `ApiClient.request()`: that helper discards
+## the parsed JSON body on any non-2xx response (see its `_make_result`
+## calls), and the `409` body's `current_revision`/`current_checksum` are
+## exactly what this retry loop needs. Uses a raw per-request `HTTPRequest`
+## child instead, the same pattern `scripts/http_chunk_source.gd` uses for
+## the read side.
+##
+## Must be added to the scene tree before use.
+
+## The world this service saves chunks for (string form of the backend's
+## numeric world id).
+var world_id: String = ""
+
+## The room slug within that world. world.md's default room is "main".
+var room_slug: String = "main"
+
+## Bounded retries on a 409 conflict -- refuses to loop forever against a
+## chunk under sustained contention.
+const MAX_RETRIES := 3
+
+
+## Fetch the current chunk at [param coord].
+##
+## Returns:
+##     {"ok": bool, "status": int, "model": ChunkEditorModel|null,
+##      "revision": int, "checksum": String, "detail": String}
+##
+## A `404` (unwritten coordinate) is reported as `ok: true, model: null` --
+## world_persistence_impl.md §8.1: "an unwritten coordinate is not an error".
+## Callers wanting a fresh chunk to edit should fall back to
+## `ChunkEditorModel.create_empty()` at `base_revision: 0` in that case.
+func fetch_chunk(coord: Vector3i) -> Dictionary:
+	var http := HTTPRequest.new()
+	http.timeout = 15.0
+	add_child(http)
+
+	var api := _api_client()
+	var headers := PackedStringArray(["Accept: application/octet-stream"])
+	if api.has_token():
+		headers.append("Authorization: " + str(api.bearer_token))
+
+	var url: String = str(api.base_url) + _chunk_path(coord)
+	var err := http.request(url, headers, HTTPClient.METHOD_GET)
+	if err != OK:
+		http.queue_free()
+		return _fetch_result(false, 0, null, 0, "", "request failed to start (%d)" % err)
+
+	var args: Array = await http.request_completed
+	var result_code: int = args[0]
+	var response_code: int = args[1]
+	var response_headers: PackedStringArray = args[2]
+	var body: PackedByteArray = args[3]
+	http.queue_free()
+
+	if result_code != HTTPRequest.RESULT_SUCCESS:
+		return _fetch_result(false, 0, null, 0, "", "transport error (%d)" % result_code)
+
+	if response_code == 404:
+		return _fetch_result(true, 404, null, 0, "", "not found (unwritten chunk)")
+
+	if response_code != 200:
+		return _fetch_result(false, response_code, null, 0, "", _error_detail_from_body(body))
+
+	var model := ChunkEditorModel.from_binary(body)
+	if model == null:
+		return _fetch_result(false, response_code, null, 0, "", "failed to decode chunk payload")
+
+	return _fetch_result(
+		true, 200, model,
+		_int_header(response_headers, "x-chunk-revision"),
+		_etag_from_headers(response_headers),
+		"OK",
+	)
+
+
+## Save one chunk. `model.encode_binary()` is sent as the new payload;
+## `base_revision` is the revision the editor last knew about (0 = create).
+##
+## Returns:
+##     {"ok": bool, "status": int, "revision": int, "checksum": String,
+##      "live_session": bool, "retried": bool, "detail": String}
+func save_chunk(model: ChunkEditorModel, coord: Vector3i, base_revision: int) -> Dictionary:
+	var attempt_revision := base_revision
+	var retried := false
+	for attempt in range(MAX_RETRIES + 1):
+		var body := {
+			"base_revision": attempt_revision,
+			"payload_b64": Marshalls.raw_to_base64(model.encode_binary()),
+		}
+		var resp := await _request_json(HTTPClient.METHOD_PUT, _chunk_path(coord), body)
+
+		if resp["status"] == 200:
+			var d: Dictionary = resp["data"]
+			return {
+				"ok": true, "status": 200,
+				"revision": int(d.get("revision", attempt_revision)),
+				"checksum": str(d.get("checksum", "")),
+				"live_session": bool(d.get("live_session", false)),
+				"retried": retried, "detail": "OK",
+			}
+
+		if resp["status"] == 409 and attempt < MAX_RETRIES:
+			var conflict: Dictionary = resp["data"] if resp["data"] is Dictionary else {}
+			var current_rev := int(conflict.get("current_revision", attempt_revision))
+			# Doc-mandated "re-fetch current chunk" step before retrying --
+			# keeps this service's view of the chunk current even though the
+			# retry itself only needs the revision number from the 409 body.
+			await fetch_chunk(coord)
+			attempt_revision = current_rev
+			retried = true
+			continue
+
+		return {"ok": false, "status": resp["status"], "revision": 0, "checksum": "",
+			"live_session": false, "retried": retried, "detail": _error_detail(resp)}
+
+	return {"ok": false, "status": 409, "revision": 0, "checksum": "", "live_session": false,
+		"retried": true, "detail": "conflict retry limit exceeded"}
+
+
+## Save multiple chunks in one atomic batch PUT (world_persistence_impl.md
+## §8.1 batch write: "an editor brush stroke or an object drag routinely
+## straddles a chunk boundary"). `entries` is an Array of
+## `{"coord": Vector3i, "model": ChunkEditorModel, "base_revision": int}`.
+## All-or-nothing: a `409` names the offending coordinate and nothing is
+## written, so only that entry's `base_revision` is refreshed before the
+## whole batch is retried.
+##
+## Returns:
+##     {"ok": bool, "status": int, "live_session": bool,
+##      "chunks": Array, "retried": bool, "detail": String}
+func save_batch(entries: Array) -> Dictionary:
+	var working: Array = []
+	for e in entries:
+		working.append((e as Dictionary).duplicate())
+	var retried := false
+
+	for attempt in range(MAX_RETRIES + 1):
+		var chunks_json: Array = []
+		for e in working:
+			var c: Vector3i = e["coord"]
+			var m: ChunkEditorModel = e["model"]
+			chunks_json.append({
+				"cx": c.x, "cy": c.y, "cz": c.z,
+				"base_revision": int(e["base_revision"]),
+				"payload_b64": Marshalls.raw_to_base64(m.encode_binary()),
+			})
+		var resp := await _request_json(HTTPClient.METHOD_PUT, _batch_path(), {"chunks": chunks_json})
+
+		if resp["status"] == 200:
+			var d: Dictionary = resp["data"]
+			return {"ok": true, "status": 200, "live_session": bool(d.get("live_session", false)),
+				"chunks": d.get("chunks", []), "retried": retried, "detail": "OK"}
+
+		if resp["status"] == 409 and attempt < MAX_RETRIES:
+			var conflict: Dictionary = resp["data"] if resp["data"] is Dictionary else {}
+			var current_rev := int(conflict.get("current_revision", 0))
+			var offending: Variant = conflict.get("coord")
+			if offending is Array and offending.size() == 3:
+				var oc := Vector3i(int(offending[0]), int(offending[1]), int(offending[2]))
+				for e in working:
+					if (e["coord"] as Vector3i) == oc:
+						await fetch_chunk(oc)
+						e["base_revision"] = current_rev
+						break
+			retried = true
+			continue
+
+		return {"ok": false, "status": resp["status"], "live_session": false, "chunks": [],
+			"retried": retried, "detail": _error_detail(resp)}
+
+	return {"ok": false, "status": 409, "live_session": false, "chunks": [],
+		"retried": true, "detail": "conflict retry limit exceeded"}
+
+
+# ─────────────────────────── internals ───────────────────────────
+
+## Resolved via an absolute node path, not the bare `ApiClient` autoload
+## identifier -- see the identical note on `HttpChunkSource._api_client()`
+## (bare autoload identifiers don't resolve when a script is compiled for a
+## headless `godot --script ...` run, which is how this service's smoke
+## test drives it).
+func _api_client() -> Node:
+	return get_node("/root/ApiClient")
+
+
+func _chunk_path(coord: Vector3i) -> String:
+	return "/api/worlds/%s/rooms/%s/chunks/%d/%d/%d" % [world_id, room_slug, coord.x, coord.y, coord.z]
+
+
+func _batch_path() -> String:
+	return "/api/worlds/%s/rooms/%s/chunks" % [world_id, room_slug]
+
+
+func _request_json(method: HTTPClient.Method, path: String, body_dict: Dictionary) -> Dictionary:
+	var http := HTTPRequest.new()
+	http.timeout = 15.0
+	add_child(http)
+
+	var api := _api_client()
+	var headers := PackedStringArray(["Content-Type: application/json", "Accept: application/json"])
+	if api.has_token():
+		headers.append("Authorization: " + str(api.bearer_token))
+
+	var url: String = str(api.base_url) + path
+	var err := http.request(url, headers, method, JSON.stringify(body_dict))
+	if err != OK:
+		http.queue_free()
+		return {"status": 0, "data": null, "raw": "request failed to start (%d)" % err}
+
+	var args: Array = await http.request_completed
+	var result_code: int = args[0]
+	var response_code: int = args[1]
+	var body_bytes: PackedByteArray = args[3]
+	http.queue_free()
+
+	if result_code != HTTPRequest.RESULT_SUCCESS:
+		return {"status": 0, "data": null, "raw": "transport error (%d)" % result_code}
+
+	var text := body_bytes.get_string_from_utf8()
+	var parsed: Variant = JSON.parse_string(text) if text != "" else null
+	return {"status": response_code, "data": parsed, "raw": text}
+
+
+func _error_detail(resp: Dictionary) -> String:
+	var data: Variant = resp.get("data")
+	if data is Dictionary and (data as Dictionary).has("detail"):
+		return str((data as Dictionary)["detail"])
+	if int(resp.get("status", 0)) == 0:
+		return str(resp.get("raw", "network error"))
+	return "HTTP error %d" % int(resp.get("status", 0))
+
+
+func _error_detail_from_body(body: PackedByteArray) -> String:
+	var text := body.get_string_from_utf8()
+	var parsed: Variant = JSON.parse_string(text) if text != "" else null
+	if parsed is Dictionary and (parsed as Dictionary).has("detail"):
+		return str((parsed as Dictionary)["detail"])
+	return text
+
+
+func _fetch_result(ok: bool, status: int, model: ChunkEditorModel, revision: int,
+		checksum: String, detail: String) -> Dictionary:
+	return {"ok": ok, "status": status, "model": model, "revision": revision,
+		"checksum": checksum, "detail": detail}
+
+
+func _int_header(headers: PackedStringArray, key: String) -> int:
+	var prefix := key + ":"
+	for h in headers:
+		if h.to_lower().begins_with(prefix):
+			return int(h.substr(h.find(":") + 1).strip_edges())
+	return 0
+
+
+func _etag_from_headers(headers: PackedStringArray) -> String:
+	for h in headers:
+		if h.to_lower().begins_with("etag:"):
+			var v := h.substr(h.find(":") + 1).strip_edges()
+			return v.trim_prefix('"').trim_suffix('"')
+	return ""

scripts/editor/editor_core.gd

@@ -0,0 +1,114 @@
+class_name EditorCore
+extends RefCounted
+## Shared, data-native editor core (docs/architecture/editor.md §7.1).
+##
+## Both the in-game editor UI (`scripts/editor/ui/in_game_editor.gd`) and,
+## per the doc's §6.2/§7.3, any future thin dev-plugin surface are meant to
+## sit on top of this single object. It never touches `Control` nodes,
+## HTTP, or the live scene tree -- it only knows about the chunk model,
+## undo/redo, selection, and tools. It owns:
+##
+##   - `model`     (ChunkEditorModel)     the chunk being edited
+##   - `undo_redo` (EditorUndoRedoStack)  command-pattern history
+##   - `selection` (SelectionManager)     selected object id
+##   - `tools`     (ToolRegistry)         brush / object_place / select /
+##                                        erase / transform
+##   - `catalog`   (EditorObjectCatalog, optional) palette source consumed
+##                                        by `object_place`
+##
+## Every mutating public method here (`paint_tile`, `erase_tile`,
+## `place_object`, `delete_object`, `move_object`, `rotate_object`,
+## `scale_object`, `select_object`) is a thin wrapper around `use_tool()` --
+## it goes through `ToolRegistry`, never straight at `ChunkEditorModel`.
+## This is the seam this task's verification bar cares about: UI code and
+## tests mutate the chunk exactly the same way, so a test that calls
+## `core.move_object(...)` is exercising the same code path a player's
+## drag-in-the-viewport would.
+##
+## Persisting the edited chunk to the backend is explicitly **out of
+## scope** here (a sibling task owns the batch-PUT/conflict-handling save
+## path per world_persistence_impl.md) -- `model.encode_binary()` is as far
+## as this class goes.
+
+var model: ChunkEditorModel
+var undo_redo: EditorUndoRedoStack
+var selection: SelectionManager
+var tools: ToolRegistry
+var catalog: EditorObjectCatalog = null
+
+
+func _init(p_model: ChunkEditorModel, p_catalog: EditorObjectCatalog = null) -> void:
+	model = p_model
+	catalog = p_catalog
+	undo_redo = EditorUndoRedoStack.new()
+	selection = SelectionManager.new()
+	tools = ToolRegistry.new()
+	tools.register_tool(BrushTool.new())
+	tools.register_tool(ObjectPlaceTool.new())
+	tools.register_tool(SelectTool.new())
+	tools.register_tool(EraseTool.new())
+	tools.register_tool(TransformTool.new())
+	tools.set_active_tool("select")
+
+
+## Route an action through the named tool. This is the single choke point
+## every mutation (and every convenience wrapper below) goes through.
+func use_tool(tool_id: String, args: Dictionary) -> Variant:
+	var tool: EditorTool = tools.get_tool(tool_id)
+	if tool == null:
+		push_error("EditorCore: unknown tool '%s'" % tool_id)
+		return null
+	return tool.apply(self, args)
+
+
+# ───────── convenience wrappers (all route through use_tool/ToolRegistry) ─────────
+
+func paint_tile(layer_idx: int, x: int, y: int, tile_id: int, z: int = 0) -> bool:
+	return bool(use_tool("brush", {"layer": layer_idx, "x": x, "y": y, "z": z, "tile_id": tile_id}))
+
+
+func erase_tile(layer_idx: int, x: int, y: int, z: int = 0) -> bool:
+	return bool(use_tool("erase", {"layer": layer_idx, "x": x, "y": y, "z": z}))
+
+
+func place_object(catalog_id: String, position: Vector3,
+		rotation: Vector4 = Vector4(0, 0, 0, 1), scale: Vector3 = Vector3.ONE) -> String:
+	var result: Variant = use_tool("object_place", {
+		"catalog_id": catalog_id,
+		"position": position,
+		"rotation": rotation,
+		"scale": scale,
+	})
+	return result if result is String else ""
+
+
+func delete_object(object_id: String) -> bool:
+	return bool(use_tool("erase", {"object_id": object_id}))
+
+
+func move_object(object_id: String, position: Vector3) -> bool:
+	return bool(use_tool("transform", {"object_id": object_id, "op": "move", "value": position}))
+
+
+func rotate_object(object_id: String, rotation: Vector4) -> bool:
+	return bool(use_tool("transform", {"object_id": object_id, "op": "rotate", "value": rotation}))
+
+
+func scale_object(object_id: String, scale: Vector3) -> bool:
+	return bool(use_tool("transform", {"object_id": object_id, "op": "scale", "value": scale}))
+
+
+func select_object(object_id: String) -> bool:
+	return bool(use_tool("select", {"object_id": object_id}))
+
+
+func clear_selection() -> void:
+	use_tool("select", {})
+
+
+func undo() -> bool:
+	return undo_redo.undo()
+
+
+func redo() -> bool:
+	return undo_redo.redo()

scripts/editor/editor_undo_redo_stack.gd

@@ -0,0 +1,73 @@
+class_name EditorUndoRedoStack
+extends RefCounted
+## Command pattern over ChunkEditorModel mutations
+## (docs/architecture/editor.md §7.1 `UndoRedoStack`).
+##
+## Thin wrapper around Godot's built-in `UndoRedo` -- the general-purpose
+## class meant for use in game code (unlike the editor-only
+## `EditorUndoRedoManager`, which only exists inside `EditorPlugin`s and
+## isn't available at runtime). Every EditorCore tool (scripts/editor/tools/
+## *.gd) opens exactly one action per user operation and adds a do/undo
+## Callable pair that calls the *same* ChunkEditorModel raw setter in both
+## directions (e.g. `set_tile_raw` with the new id, then again with the old
+## one) -- so undo genuinely reverts the mutation instead of re-deriving it.
+##
+## `UndoRedo` extends `Object`, not `RefCounted`, so it is not automatically
+## freed; `_notification(NOTIFICATION_PREDELETE)` frees it when this wrapper
+## (a RefCounted) goes out of scope.
+
+var _ur := UndoRedo.new()
+
+
+func _notification(what: int) -> void:
+	if what == NOTIFICATION_PREDELETE and _ur != null:
+		_ur.free()
+		_ur = null
+
+
+## Begin a new undoable action. Must be paired with `commit()`.
+func begin(action_name: String) -> void:
+	_ur.create_action(action_name)
+
+
+## Register the forward step of the current action. Called immediately by
+## `commit()`, and again on every future `redo()`.
+func add_do(callable: Callable) -> void:
+	_ur.add_do_method(callable)
+
+
+## Register the reverse step of the current action. Called on every
+## `undo()`.
+func add_undo(callable: Callable) -> void:
+	_ur.add_undo_method(callable)
+
+
+## Close the current action and execute its do-step once.
+func commit() -> void:
+	_ur.commit_action()
+
+
+## Close the current action without executing anything (used when a tool
+## decides mid-way that there is nothing worth recording).
+func cancel() -> void:
+	_ur.commit_action(false)
+
+
+func undo() -> bool:
+	return _ur.undo()
+
+
+func redo() -> bool:
+	return _ur.redo()
+
+
+func can_undo() -> bool:
+	return _ur.has_undo()
+
+
+func can_redo() -> bool:
+	return _ur.has_redo()
+
+
+func clear_history() -> void:
+	_ur.clear_history()

scripts/editor/object_catalog.gd

@@ -0,0 +1,68 @@
+class_name EditorObjectCatalog
+extends RefCounted
+## Catalog of placeable world objects for the in-game editor's
+## `PalettePanel` (docs/architecture/editor.md §7.2).
+##
+## Mirrors the loading convention already used twice in this codebase --
+## `scripts/avatar/avatar_catalog.gd` (AvatarCatalog) and
+## `scripts/scripting/spawn_catalog.gd` (SpawnCatalog): a data-driven JSON
+## manifest, loaded once, looked up by id. Checked both before adding this:
+## `AvatarCatalog` is avatar-attachment-specific (base_body/slot/mount_bone)
+## and `SpawnCatalog` is scoped to `ScriptBehavior`'s `spawn_from_catalog`
+## verb specifically (its own doc comment says as much) -- neither is a
+## general "placeable world object" catalog, so this is a new, small one
+## rather than a reuse of either.
+
+## Catalog manifest structure:
+## { "objects": { "id": { "type", "asset_id", "display_name", ... } } }
+var _catalog: Dictionary = {}
+var _loaded: bool = false
+var _catalog_path: String = "res://assets/editor/object_catalog.json"
+
+
+func load_catalog(path: String = _catalog_path) -> Error:
+	_catalog_path = path
+	_catalog = {}
+
+	var file := FileAccess.open(path, FileAccess.READ)
+	if file == null:
+		return FileAccess.get_open_error()
+
+	var json_text: String = file.get_as_text()
+	file.close()
+
+	var result: Variant = JSON.parse_string(json_text)
+	if result == null or not (result is Dictionary) or not (result as Dictionary).has("objects"):
+		return ERR_INVALID_DATA
+
+	_catalog = (result as Dictionary)["objects"]
+	_loaded = true
+	return OK
+
+
+func is_loaded() -> bool:
+	return _loaded
+
+
+## Resolve a catalog id to its template Dictionary ({} if unknown/unloaded).
+func resolve(id: String) -> Dictionary:
+	if not _loaded:
+		return {}
+	return _catalog.get(id, {})
+
+
+func has_object(id: String) -> bool:
+	return _loaded and _catalog.has(id)
+
+
+func get_all_ids() -> Array[String]:
+	if not _loaded:
+		return []
+	var ids: Array[String] = []
+	for id in _catalog.keys():
+		ids.append(id)
+	return ids
+
+
+func get_catalog_path() -> String:
+	return _catalog_path

scripts/editor/selection_manager.gd

@@ -0,0 +1,32 @@
+class_name SelectionManager
+extends RefCounted
+## Tracks the currently-selected object in the in-game editor
+## (docs/architecture/editor.md §7.1 `SelectionManager`).
+##
+## Selection is UI/session state, not chunk data: it is never pushed onto
+## `EditorUndoRedoStack` and never encoded into the `ChunkPayload`. Scoped
+## to a single selected object id, matching the 2D-tile-editor scope
+## (docs/architecture/editor.md §8) -- multi-select is future work.
+
+signal selection_changed(object_id: String)
+
+var _selected_id: String = ""
+
+
+func select(object_id: String) -> void:
+	if _selected_id == object_id:
+		return
+	_selected_id = object_id
+	selection_changed.emit(_selected_id)
+
+
+func clear() -> void:
+	select("")
+
+
+func get_selected() -> String:
+	return _selected_id
+
+
+func has_selection() -> bool:
+	return _selected_id != ""

scripts/editor/tool_registry.gd

@@ -0,0 +1,41 @@
+class_name ToolRegistry
+extends RefCounted
+## Registry of `EditorTool` instances, keyed by id
+## (docs/architecture/editor.md §7.1: "brush / object-place / select /
+## erase, etc."). `EditorCore.use_tool()` is the single choke point every
+## chunk mutation goes through -- UI code and tests both call tools by id
+## through here rather than reaching into `ChunkEditorModel` directly.
+
+var _tools: Dictionary = {}
+var _active_id: String = ""
+
+
+func register_tool(tool: EditorTool) -> void:
+	_tools[tool.tool_id] = tool
+
+
+func get_tool(tool_id: String) -> EditorTool:
+	return _tools.get(tool_id, null)
+
+
+func has_tool(tool_id: String) -> bool:
+	return _tools.has(tool_id)
+
+
+func get_tool_ids() -> Array:
+	return _tools.keys()
+
+
+func set_active_tool(tool_id: String) -> bool:
+	if not _tools.has(tool_id):
+		return false
+	_active_id = tool_id
+	return true
+
+
+func get_active_tool_id() -> String:
+	return _active_id
+
+
+func get_active_tool() -> EditorTool:
+	return _tools.get(_active_id, null)

scripts/editor/tools/brush_tool.gd

@@ -0,0 +1,31 @@
+class_name BrushTool
+extends EditorTool
+## Paints a single tile id into a tile layer at (x, y[, z]).
+##
+## `args`: `layer` (int, default 0), `x` (int), `y` (int), `z` (int,
+## default 0), `tile_id` (int).
+
+
+func _init() -> void:
+	tool_id = "brush"
+
+
+func apply(core: EditorCore, args: Dictionary) -> Variant:
+	var layer_idx: int = args.get("layer", 0)
+	var x: int = args.get("x", 0)
+	var y: int = args.get("y", 0)
+	var z: int = args.get("z", 0)
+	var tile_id: int = args.get("tile_id", 0)
+
+	if not core.model.is_tile_in_bounds(layer_idx, x, y, z):
+		return false
+
+	var old_tile_id: int = core.model.get_tile_raw(layer_idx, x, y, z)
+	if old_tile_id == tile_id:
+		return false  # no-op -- nothing to undo
+
+	core.undo_redo.begin("Paint tile (%d,%d,%d) -> %d" % [x, y, z, tile_id])
+	core.undo_redo.add_do(core.model.set_tile_raw.bind(layer_idx, x, y, z, tile_id))
+	core.undo_redo.add_undo(core.model.set_tile_raw.bind(layer_idx, x, y, z, old_tile_id))
+	core.undo_redo.commit()
+	return true

scripts/editor/tools/editor_tool.gd

@@ -0,0 +1,20 @@
+class_name EditorTool
+extends RefCounted
+## Base class for EditorCore tools (docs/architecture/editor.md §7.1
+## `ToolRegistry`: brush / object-place / select / erase / transform).
+##
+## A tool never mutates `ChunkEditorModel` "bare" -- every chunk-data
+## mutation goes through `EditorCore.undo_redo` so it is always revertible.
+## (Selection is the one exception: it is UI state, not chunk data, and
+## `SelectTool` intentionally does not touch undo/redo -- see its comment.)
+
+var tool_id: String = ""
+
+
+## Apply this tool's action against `core` with `args`. Returns a
+## tool-specific result on success (often `true`/a new object id), or a
+## falsy value (`false`/`""`/`null`) if nothing changed -- callers should
+## treat falsy as "no-op, nothing to undo".
+func apply(_core: EditorCore, _args: Dictionary) -> Variant:
+	push_error("EditorTool.apply() not implemented for tool '%s'" % tool_id)
+	return null

scripts/editor/tools/erase_tool.gd

@@ -0,0 +1,41 @@
+class_name EraseTool
+extends EditorTool
+## Deletes an object, or clears a tile back to id 0 (the reserved empty/air
+## id -- world.md §3.2 / TileDef doc comment).
+##
+## `args`: either `{"object_id": ...}` to delete an object, or
+## `{"layer", "x", "y", "z"}` to clear a tile (delegates to BrushTool with
+## `tile_id = 0` so both paths share one undo/redo implementation).
+
+
+func _init() -> void:
+	tool_id = "erase"
+
+
+func apply(core: EditorCore, args: Dictionary) -> Variant:
+	if args.has("object_id"):
+		return _erase_object(core, args["object_id"])
+	return _erase_tile(core, args)
+
+
+func _erase_object(core: EditorCore, object_id: String) -> bool:
+	var idx: int = core.model.get_object_index(object_id)
+	if idx == -1:
+		return false
+	var obj: ChunkDataDecoder.WorldObjectData = core.model.payload.objects[idx]
+
+	core.undo_redo.begin("Delete '%s'" % object_id)
+	core.undo_redo.add_do(core.model.remove_object_raw.bind(object_id))
+	core.undo_redo.add_undo(core.model.insert_object_raw.bind(obj, idx))
+	core.undo_redo.commit()
+
+	if core.selection.get_selected() == object_id:
+		core.selection.clear()
+	return true
+
+
+func _erase_tile(core: EditorCore, args: Dictionary) -> bool:
+	var brush: EditorTool = core.tools.get_tool("brush")
+	var tile_args: Dictionary = args.duplicate()
+	tile_args["tile_id"] = 0
+	return bool(brush.apply(core, tile_args))

scripts/editor/tools/object_place_tool.gd

@@ -0,0 +1,50 @@
+class_name ObjectPlaceTool
+extends EditorTool
+## Places a new catalog object into the chunk at a given transform.
+##
+## `args`: `catalog_id` (String, required), `position` (Vector3), `rotation`
+## (Vector4 quaternion, optional, default identity), `scale` (Vector3,
+## optional, default ONE), `properties` (Dictionary, optional, merged in).
+##
+## Returns the new object's id (String) on success, or "" on failure
+## (unknown catalog_id).
+
+
+func _init() -> void:
+	tool_id = "object_place"
+
+
+func apply(core: EditorCore, args: Dictionary) -> Variant:
+	var catalog_id: String = args.get("catalog_id", "")
+	if catalog_id == "":
+		push_error("ObjectPlaceTool: missing catalog_id")
+		return ""
+
+	var entry: Dictionary = {}
+	if core.catalog != null:
+		entry = core.catalog.resolve(catalog_id)
+		if entry.is_empty():
+			push_error("ObjectPlaceTool: unknown catalog_id '%s'" % catalog_id)
+			return ""
+
+	var obj := ChunkDataDecoder.WorldObjectData.new()
+	obj.id = core.model.generate_object_id()
+	obj.type = entry.get("type", "prop")
+	obj.asset_id = entry.get("asset_id", catalog_id)
+	obj.position = args.get("position", Vector3.ZERO)
+	obj.rotation = args.get("rotation", Vector4(0, 0, 0, 1))
+	obj.scale = args.get("scale", Vector3.ONE)
+
+	var props: Dictionary = (args.get("properties", {}) as Dictionary).duplicate()
+	if entry.has("display_name"):
+		props["display_name"] = entry["display_name"]
+	props["catalog_id"] = catalog_id
+	obj.properties = props
+
+	core.undo_redo.begin("Place '%s' (%s)" % [obj.id, catalog_id])
+	core.undo_redo.add_do(core.model.add_object_raw.bind(obj))
+	core.undo_redo.add_undo(core.model.remove_object_raw.bind(obj.id))
+	core.undo_redo.commit()
+
+	core.selection.select(obj.id)
+	return obj.id

scripts/editor/tools/select_tool.gd

@@ -0,0 +1,24 @@
+class_name SelectTool
+extends EditorTool
+## Selects (or clears) the active object in `EditorCore.selection`.
+##
+## `args`: `object_id` (String) -- omitted or "" clears the selection.
+##
+## Selection is UI/session state, not chunk data (docs/architecture/editor.md
+## §7.1 lists `SelectionManager` as a sibling of `UndoRedoStack`, not a
+## client of it), so this intentionally never touches `core.undo_redo`.
+
+
+func _init() -> void:
+	tool_id = "select"
+
+
+func apply(core: EditorCore, args: Dictionary) -> Variant:
+	var object_id: String = args.get("object_id", "")
+	if object_id == "":
+		core.selection.clear()
+		return true
+	if core.model.find_object(object_id) == null:
+		return false
+	core.selection.select(object_id)
+	return true

scripts/editor/tools/transform_tool.gd

@@ -0,0 +1,62 @@
+class_name TransformTool
+extends EditorTool
+## Moves, rotates, or scales an existing object.
+##
+## Not one of the four tools literally named in docs/architecture/editor.md
+## §7.1's `ToolRegistry` list ("brush / object-place / select / erase,
+## etc.") but required by this task's brief ("place / move / rotate / scale
+## / delete") -- the doc's own "etc." leaves room, so this is a fifth
+## registered tool rather than overloading `ObjectPlaceTool` (placing a new
+## object and re-transforming an existing one are different undo units)
+## or `SelectTool` (selection is deliberately not chunk-mutating).
+##
+## `args`: `object_id` (String), `op` ("move" | "rotate" | "scale"), `value`
+## (Vector3 for move/scale, Vector4 quaternion for rotate).
+
+
+func _init() -> void:
+	tool_id = "transform"
+
+
+func apply(core: EditorCore, args: Dictionary) -> Variant:
+	var object_id: String = args.get("object_id", "")
+	var op: String = args.get("op", "")
+	var obj := core.model.find_object(object_id)
+	if obj == null:
+		return false
+
+	match op:
+		"move":
+			return _apply_vector3(core, object_id, args.get("value", obj.position),
+				obj.position, "Move", core.model.set_object_position_raw)
+		"rotate":
+			return _apply_vector4(core, object_id, args.get("value", obj.rotation),
+				obj.rotation, "Rotate", core.model.set_object_rotation_raw)
+		"scale":
+			return _apply_vector3(core, object_id, args.get("value", obj.scale),
+				obj.scale, "Scale", core.model.set_object_scale_raw)
+		_:
+			push_error("TransformTool: unknown op '%s'" % op)
+			return false
+
+
+func _apply_vector3(core: EditorCore, object_id: String, new_value: Vector3,
+		old_value: Vector3, label: String, setter: Callable) -> bool:
+	if new_value.is_equal_approx(old_value):
+		return false
+	core.undo_redo.begin("%s '%s'" % [label, object_id])
+	core.undo_redo.add_do(setter.bind(object_id, new_value))
+	core.undo_redo.add_undo(setter.bind(object_id, old_value))
+	core.undo_redo.commit()
+	return true
+
+
+func _apply_vector4(core: EditorCore, object_id: String, new_value: Vector4,
+		old_value: Vector4, label: String, setter: Callable) -> bool:
+	if new_value.is_equal_approx(old_value):
+		return false
+	core.undo_redo.begin("%s '%s'" % [label, object_id])
+	core.undo_redo.add_do(setter.bind(object_id, new_value))
+	core.undo_redo.add_undo(setter.bind(object_id, old_value))
+	core.undo_redo.commit()
+	return true

scripts/editor/ui/editor_toolbar.gd

@@ -0,0 +1,65 @@
+class_name EditorToolbar
+extends HBoxContainer
+## Tool-mode switcher for the in-game editor (docs/architecture/editor.md
+## §7.2 `Toolbar`). Pure UI: it only emits signals: `InGameEditor` decides
+## what to do with them (calling into `EditorCore`/`ToolRegistry`).
+
+signal tool_selected(tool_id: String)
+signal undo_pressed
+signal redo_pressed
+
+const TOOL_LABELS := {
+	"select": "Select",
+	"brush": "Brush",
+	"object_place": "Place",
+	"erase": "Erase",
+}
+
+var _tool_buttons: Dictionary = {}
+var _undo_button: Button
+var _redo_button: Button
+
+
+func _init() -> void:
+	name = "EditorToolbar"
+
+
+func _ready() -> void:
+	for tool_id in TOOL_LABELS:
+		var btn := Button.new()
+		btn.text = TOOL_LABELS[tool_id]
+		btn.toggle_mode = true
+		btn.pressed.connect(_on_tool_button_pressed.bind(tool_id))
+		add_child(btn)
+		_tool_buttons[tool_id] = btn
+
+	add_child(VSeparator.new())
+
+	_undo_button = Button.new()
+	_undo_button.text = "Undo"
+	_undo_button.pressed.connect(func(): undo_pressed.emit())
+	add_child(_undo_button)
+
+	_redo_button = Button.new()
+	_redo_button.text = "Redo"
+	_redo_button.pressed.connect(func(): redo_pressed.emit())
+	add_child(_redo_button)
+
+
+func _on_tool_button_pressed(tool_id: String) -> void:
+	set_active_tool(tool_id)
+	tool_selected.emit(tool_id)
+
+
+## Reflect the active tool in the button states without re-emitting the signal.
+func set_active_tool(tool_id: String) -> void:
+	for id in _tool_buttons:
+		_tool_buttons[id].button_pressed = (id == tool_id)
+
+
+## Reflect whether undo/redo currently have anything to do.
+func set_history_state(can_undo: bool, can_redo: bool) -> void:
+	if _undo_button:
+		_undo_button.disabled = not can_undo
+	if _redo_button:
+		_redo_button.disabled = not can_redo

scripts/editor/ui/editor_viewport.gd

@@ -0,0 +1,135 @@
+class_name EditorViewport
+extends Control
+## Custom 2D viewport for the in-game editor (docs/architecture/editor.md
+## §7.2 `EditorViewport`).
+##
+## Deliberately 2D top-down, not a 3D gizmo viewport -- per §8's own risk
+## mitigation ("start with a 2D tile editor... matches CHUNK_SIZE_Z=1
+## default; add 3D later"). Renders one tile layer as a grid plus the
+## chunk's objects as dots, and turns clicks into calls on `EditorCore`
+## routed through whichever tool is active in `ToolRegistry` -- this is UI
+## glue, it never mutates `ChunkEditorModel` itself.
+##
+## Coordinate convention matches the rest of this codebase's tile system
+## (scripts/tile_layer_node.gd `_tile_to_world`): chunk-local X/Y are the
+## flat ground plane, Z is height (CHUNK_SIZE_Z=1 by default -- see
+## scripts/chunk.gd). One grid cell == one world unit == `cell_size` pixels.
+
+signal edit_applied
+
+var core: EditorCore = null
+var layer_idx: int = 0
+var cell_size: float = 24.0
+## Catalog id the next "object_place" click will place. Set by
+## `InGameEditor` from `PalettePanel.object_selected`.
+var pending_catalog_id: String = ""
+## Tile id the next "brush" click paints. Cycled with number keys 0-9.
+var current_tile_id: int = 1
+
+const TILE_EMPTY_COLOR := Color(0.15, 0.15, 0.17)
+const TILE_SOLID_COLOR := Color(0.35, 0.55, 0.35)
+const GRID_COLOR := Color(0, 0, 0, 0.25)
+const OBJECT_COLOR := Color(0.9, 0.6, 0.2)
+const OBJECT_SELECTED_COLOR := Color(1.0, 0.95, 0.2)
+
+
+func _init() -> void:
+	name = "EditorViewport"
+	mouse_filter = Control.MOUSE_FILTER_STOP
+	focus_mode = Control.FOCUS_ALL
+
+
+func setup(p_core: EditorCore, p_layer_idx: int = 0) -> void:
+	core = p_core
+	layer_idx = p_layer_idx
+	core.selection.selection_changed.connect(func(_id): queue_redraw())
+	_resize_to_layer()
+	queue_redraw()
+
+
+func _resize_to_layer() -> void:
+	var layer := core.model.get_layer(layer_idx)
+	if layer == null:
+		custom_minimum_size = Vector2(cell_size * 8, cell_size * 8)
+		return
+	custom_minimum_size = Vector2(layer.width * cell_size, layer.height * cell_size)
+
+
+func _draw() -> void:
+	if core == null:
+		return
+	var layer := core.model.get_layer(layer_idx)
+	if layer == null:
+		return
+
+	for y in range(layer.height):
+		for x in range(layer.width):
+			var tile_id := layer.get_tile(x, y, 0)
+			var color := TILE_EMPTY_COLOR
+			var tdef := layer.get_tile_def(tile_id)
+			if tdef != null and tdef.solid:
+				color = TILE_SOLID_COLOR
+			draw_rect(Rect2(x * cell_size, y * cell_size, cell_size, cell_size), color, true)
+
+	for x in range(layer.width + 1):
+		draw_line(Vector2(x * cell_size, 0), Vector2(x * cell_size, layer.height * cell_size), GRID_COLOR)
+	for y in range(layer.height + 1):
+		draw_line(Vector2(0, y * cell_size), Vector2(layer.width * cell_size, y * cell_size), GRID_COLOR)
+
+	for obj in core.model.payload.objects:
+		var center := Vector2(obj.position.x * cell_size, obj.position.y * cell_size)
+		var is_selected: bool = core.selection.get_selected() == obj.id
+		var color := OBJECT_SELECTED_COLOR if is_selected else OBJECT_COLOR
+		draw_circle(center, cell_size * 0.3, color)
+
+
+func _gui_input(event: InputEvent) -> void:
+	if core == null:
+		return
+	if event is InputEventMouseButton:
+		var mb := event as InputEventMouseButton
+		if mb.pressed and mb.button_index == MOUSE_BUTTON_LEFT:
+			_handle_click(mb.position)
+			accept_event()
+	elif event is InputEventKey:
+		var key := event as InputEventKey
+		if key.pressed and not key.echo:
+			_handle_key(key)
+
+
+func _handle_key(key: InputEventKey) -> void:
+	if key.keycode >= KEY_0 and key.keycode <= KEY_9:
+		current_tile_id = key.keycode - KEY_0
+
+
+func _handle_click(local_pos: Vector2) -> void:
+	var tx := int(floor(local_pos.x / cell_size))
+	var ty := int(floor(local_pos.y / cell_size))
+
+	match core.tools.get_active_tool_id():
+		"brush":
+			if core.paint_tile(layer_idx, tx, ty, current_tile_id):
+				edit_applied.emit()
+				queue_redraw()
+		"erase":
+			var hit := _object_at(tx, ty)
+			var changed: bool = core.delete_object(hit) if hit != "" else core.erase_tile(layer_idx, tx, ty)
+			if changed:
+				edit_applied.emit()
+				queue_redraw()
+		"object_place":
+			if pending_catalog_id != "":
+				var new_id := core.place_object(pending_catalog_id, Vector3(tx + 0.5, ty + 0.5, 0.0))
+				if new_id != "":
+					edit_applied.emit()
+					queue_redraw()
+		"select":
+			core.select_object(_object_at(tx, ty))
+			queue_redraw()
+
+
+func _object_at(tx: int, ty: int) -> String:
+	for obj in core.model.payload.objects:
+		if int(floor(obj.position.x)) == tx and int(floor(obj.position.y)) == ty:
+			return obj.id
+	return ""

scripts/editor/ui/in_game_editor.gd

@@ -0,0 +1,250 @@
+class_name InGameEditor
+extends Control
+## In-game "build mode" UI (docs/architecture/editor.md §7.2 `InGameEditor`).
+##
+## Built entirely from `Control` nodes in code (matching this codebase's
+## existing convention for dynamic UI -- see `game.gd`'s `_show_build_stamp`
+## / `_show_status`) rather than a hand-authored `.tscn`, so there is one
+## fewer place for a scene-file/script mismatch to hide. It is only ever
+## instantiated when the player enters build mode (see `game.gd`'s
+## `_toggle_build_mode`), so it costs nothing during normal play.
+##
+## Composition matches the doc exactly:
+##   EditorToolbar   -- tool mode switcher
+##   PalettePanel    -- catalog-sourced object palette
+##   EditorViewport   -- the 2D tile/object canvas
+##   InspectorPanel  -- property editor for the selected object
+##   EditorCore      -- shared core (passed in, not owned/created here)
+##
+## Persisting edits (world_persistence_impl.md's single/batch-PUT save path,
+## §8.1-8.2) is wired through `ChunkSaveService`, set via
+## `setup_persistence()`. Without it (e.g. the F2 scratch-chunk path, or
+## `smoke_test_editor_core.gd`'s bare `InGameEditor.new(core)`), the Save
+## button is present but disabled -- closing the editor just discards the
+## UI and the in-memory `ChunkEditorModel` is unaffected either way.
+
+signal closed
+
+var core: EditorCore
+
+var _toolbar: EditorToolbar
+var _palette: PalettePanel
+var _inspector: InspectorPanel
+var _viewport: EditorViewport
+var _close_button: Button
+var _save_button: Button
+var _save_status_label: Label
+
+## Save-path state (world_persistence_impl.md §8.1/§8.2), set via
+## `setup_persistence()`. `_save_service == null` means there is nothing to
+## save to (see the class doc above) -- the Save button stays disabled.
+var _save_service: ChunkSaveService = null
+var _world_id: String = ""
+var _room_slug: String = "main"
+var _coord: Vector3i = Vector3i.ZERO
+var _base_revision: int = 0
+var _saving: bool = false
+
+
+func _init(p_core: EditorCore) -> void:
+	core = p_core
+	name = "InGameEditor"
+	set_anchors_preset(Control.PRESET_FULL_RECT)
+	mouse_filter = Control.MOUSE_FILTER_STOP
+
+
+## Wire this editor's Save button/Ctrl+S to a real backend round-trip.
+## `save_service` must already be in the scene tree (game.gd adds it as a
+## sibling before constructing this editor). `base_revision` is whatever the
+## caller last fetched for `coord` (0 if the chunk didn't exist yet).
+func setup_persistence(save_service: ChunkSaveService, world_id: String, room_slug: String,
+		coord: Vector3i, base_revision: int) -> void:
+	_save_service = save_service
+	_world_id = world_id
+	_room_slug = room_slug
+	_coord = coord
+	_base_revision = base_revision
+	if _save_button != null:
+		_save_button.disabled = false
+
+
+func _ready() -> void:
+	_build_ui()
+	_refresh_history_buttons()
+
+
+func _build_ui() -> void:
+	var bg := ColorRect.new()
+	bg.color = Color(0.08, 0.08, 0.09, 0.96)
+	bg.set_anchors_preset(Control.PRESET_FULL_RECT)
+	bg.mouse_filter = Control.MOUSE_FILTER_IGNORE
+	add_child(bg)
+
+	var root_vbox := VBoxContainer.new()
+	root_vbox.set_anchors_preset(Control.PRESET_FULL_RECT)
+	root_vbox.offset_left = 12
+	root_vbox.offset_top = 12
+	root_vbox.offset_right = -12
+	root_vbox.offset_bottom = -12
+	add_child(root_vbox)
+
+	var top_bar := HBoxContainer.new()
+	root_vbox.add_child(top_bar)
+
+	_toolbar = EditorToolbar.new()
+	_toolbar.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	top_bar.add_child(_toolbar)
+
+	_save_button = Button.new()
+	_save_button.text = "Save (Ctrl+S)"
+	_save_button.disabled = (_save_service == null)
+	_save_button.pressed.connect(_on_save_pressed)
+	top_bar.add_child(_save_button)
+
+	_close_button = Button.new()
+	_close_button.text = "Close (F2)"
+	_close_button.pressed.connect(_on_close_pressed)
+	top_bar.add_child(_close_button)
+
+	_save_status_label = Label.new()
+	_save_status_label.autowrap_mode = TextServer.AUTOWRAP_WORD
+	_save_status_label.visible = false
+	root_vbox.add_child(_save_status_label)
+
+	var body := HBoxContainer.new()
+	body.size_flags_vertical = Control.SIZE_EXPAND_FILL
+	root_vbox.add_child(body)
+
+	var viewport_scroll := ScrollContainer.new()
+	viewport_scroll.size_flags_horizontal = Control.SIZE_EXPAND_FILL
+	viewport_scroll.size_flags_vertical = Control.SIZE_EXPAND_FILL
+	body.add_child(viewport_scroll)
+
+	_viewport = EditorViewport.new()
+	viewport_scroll.add_child(_viewport)
+
+	var sidebar := VBoxContainer.new()
+	sidebar.custom_minimum_size = Vector2(240, 0)
+	body.add_child(sidebar)
+
+	_palette = PalettePanel.new()
+	sidebar.add_child(_palette)
+
+	_inspector = InspectorPanel.new()
+	sidebar.add_child(_inspector)
+
+	_viewport.setup(core, 0)
+	_palette.set_catalog(core.catalog)
+	_inspector.setup(core)
+
+	_toolbar.set_active_tool(core.tools.get_active_tool_id())
+	_toolbar.tool_selected.connect(_on_tool_selected)
+	_toolbar.undo_pressed.connect(_on_undo_pressed)
+	_toolbar.redo_pressed.connect(_on_redo_pressed)
+	_palette.object_selected.connect(_on_palette_object_selected)
+	_inspector.delete_requested.connect(_on_inspector_delete_requested)
+	_viewport.edit_applied.connect(_on_edit_applied)
+	core.selection.selection_changed.connect(_on_selection_changed)
+
+
+func _unhandled_key_input(event: InputEvent) -> void:
+	if not (event is InputEventKey):
+		return
+	var key := event as InputEventKey
+	if not key.pressed or key.echo:
+		return
+	if key.ctrl_pressed and key.keycode == KEY_Z:
+		_on_undo_pressed()
+		get_viewport().set_input_as_handled()
+	elif key.ctrl_pressed and key.keycode == KEY_Y:
+		_on_redo_pressed()
+		get_viewport().set_input_as_handled()
+	elif key.ctrl_pressed and key.keycode == KEY_S:
+		_on_save_pressed()
+		get_viewport().set_input_as_handled()
+	elif key.keycode == KEY_DELETE and core.selection.has_selection():
+		core.delete_object(core.selection.get_selected())
+		_on_edit_applied()
+		get_viewport().set_input_as_handled()
+
+
+func _on_tool_selected(tool_id: String) -> void:
+	core.tools.set_active_tool(tool_id)
+
+
+func _on_palette_object_selected(catalog_id: String) -> void:
+	_viewport.pending_catalog_id = catalog_id
+	core.tools.set_active_tool("object_place")
+	_toolbar.set_active_tool("object_place")
+
+
+func _on_inspector_delete_requested(object_id: String) -> void:
+	core.delete_object(object_id)
+	_on_edit_applied()
+
+
+func _on_undo_pressed() -> void:
+	core.undo()
+	_on_edit_applied()
+
+
+func _on_redo_pressed() -> void:
+	core.redo()
+	_on_edit_applied()
+
+
+func _on_edit_applied() -> void:
+	_viewport.queue_redraw()
+	_inspector.show_object(core.selection.get_selected())
+	_refresh_history_buttons()
+
+
+func _on_selection_changed(object_id: String) -> void:
+	_inspector.show_object(object_id)
+
+
+func _refresh_history_buttons() -> void:
+	_toolbar.set_history_state(core.undo_redo.can_undo(), core.undo_redo.can_redo())
+
+
+func _on_close_pressed() -> void:
+	closed.emit()
+	queue_free()
+
+
+## Single-chunk save (world_persistence_impl.md §8.1). `ChunkSaveService`
+## owns the actual HTTP round trip, retrying on `409` internally
+## (§8.2/§5.4) -- this just reflects the outcome and, per §6 D4, surfaces
+## the `live_session` flag as a warning instead of ignoring it.
+func _on_save_pressed() -> void:
+	if _save_service == null or _saving:
+		return
+	_saving = true
+	_save_button.disabled = true
+	_set_save_status("Saving…", Color(0.85, 0.85, 0.85))
+
+	var result: Dictionary = await _save_service.save_chunk(core.model, _coord, _base_revision)
+
+	_saving = false
+	_save_button.disabled = false
+
+	if result.get("ok", false):
+		_base_revision = int(result.get("revision", _base_revision))
+		var msg := "Saved (revision %d)." % _base_revision
+		if bool(result.get("retried", false)):
+			msg += " (resolved a save conflict automatically)"
+		if bool(result.get("live_session", false)):
+			msg += " This world has players in it right now -- they'll see your changes when the session restarts."
+			_set_save_status(msg, Color(1.0, 0.8, 0.25))
+		else:
+			_set_save_status(msg, Color(0.55, 1.0, 0.55))
+	else:
+		_set_save_status("Save failed: %s" % str(result.get("detail", "unknown error")), Color(1.0, 0.45, 0.45))
+
+
+func _set_save_status(text: String, color: Color) -> void:
+	if _save_status_label == null:
+		return
+	_save_status_label.text = text
+	_save_status_label.add_theme_color_override("font_color", color)
+	_save_status_label.visible = true

scripts/editor/ui/inspector_panel.gd

@@ -0,0 +1,166 @@
+class_name InspectorPanel
+extends VBoxContainer
+## Property editor for the selected object (docs/architecture/editor.md
+## §7.2 `InspectorPanel`).
+##
+## 2D-tile-editor scope (docs/architecture/editor.md §8: the default world
+## is flat, `CHUNK_SIZE_Z=1`): position exposes X/Y (world-plane) plus a
+## single "height" Z for props that sit above the floor, and rotation
+## exposes one yaw field (rotation about the vertical axis) rather than a
+## full 3-axis gizmo -- deliberately not the volumetric 3D editing the doc
+## says to defer.
+##
+## Pure UI: every edit calls back into `EditorCore` (`move_object` /
+## `rotate_object` / `scale_object` / `delete_object`), so inspector edits
+## go through the exact same undo/redo path as viewport edits.
+
+signal delete_requested(object_id: String)
+
+var _core: EditorCore = null
+var _object_id: String = ""
+var _updating := false  # guards against feedback loops while refreshing fields
+
+var _id_label: Label
+var _type_label: Label
+var _asset_label: Label
+var _pos_x: SpinBox
+var _pos_y: SpinBox
+var _pos_z: SpinBox
+var _yaw: SpinBox
+var _scale_x: SpinBox
+var _scale_y: SpinBox
+var _scale_z: SpinBox
+var _delete_button: Button
+var _empty_label: Label
+var _fields_box: VBoxContainer
+
+
+func _init() -> void:
+	name = "InspectorPanel"
+
+
+func _ready() -> void:
+	var header := Label.new()
+	header.text = "Inspector"
+	add_child(header)
+
+	_empty_label = Label.new()
+	_empty_label.text = "(nothing selected)"
+	add_child(_empty_label)
+
+	_fields_box = VBoxContainer.new()
+	_fields_box.visible = false
+	add_child(_fields_box)
+
+	_id_label = _add_readonly_row("id")
+	_type_label = _add_readonly_row("type")
+	_asset_label = _add_readonly_row("asset")
+
+	_pos_x = _add_spinbox_row("pos x")
+	_pos_y = _add_spinbox_row("pos y")
+	_pos_z = _add_spinbox_row("pos z (height)")
+	_pos_x.value_changed.connect(_on_position_changed)
+	_pos_y.value_changed.connect(_on_position_changed)
+	_pos_z.value_changed.connect(_on_position_changed)
+
+	_yaw = _add_spinbox_row("rotation (deg)")
+	_yaw.min_value = -360.0
+	_yaw.max_value = 360.0
+	_yaw.step = 1.0
+	_yaw.value_changed.connect(_on_yaw_changed)
+
+	_scale_x = _add_spinbox_row("scale x")
+	_scale_y = _add_spinbox_row("scale y")
+	_scale_z = _add_spinbox_row("scale z")
+	_scale_x.value_changed.connect(_on_scale_changed)
+	_scale_y.value_changed.connect(_on_scale_changed)
+	_scale_z.value_changed.connect(_on_scale_changed)
+
+	_delete_button = Button.new()
+	_delete_button.text = "Delete"
+	_delete_button.pressed.connect(_on_delete_pressed)
+	_fields_box.add_child(_delete_button)
+
+
+func setup(core: EditorCore) -> void:
+	_core = core
+
+
+func show_object(object_id: String) -> void:
+	_object_id = object_id
+	if object_id == "" or _core == null:
+		_empty_label.visible = true
+		_fields_box.visible = false
+		return
+
+	var obj := _core.model.find_object(object_id)
+	if obj == null:
+		_empty_label.visible = true
+		_fields_box.visible = false
+		return
+
+	_empty_label.visible = false
+	_fields_box.visible = true
+
+	_updating = true
+	_id_label.text = "id: %s" % obj.id
+	_type_label.text = "type: %s" % obj.type
+	_asset_label.text = "asset: %s" % obj.asset_id
+	_pos_x.value = obj.position.x
+	_pos_y.value = obj.position.y
+	_pos_z.value = obj.position.z
+	_yaw.value = rad_to_deg(Quaternion(obj.rotation.x, obj.rotation.y, obj.rotation.z, obj.rotation.w).get_euler().y)
+	_scale_x.value = obj.scale.x
+	_scale_y.value = obj.scale.y
+	_scale_z.value = obj.scale.z
+	_updating = false
+
+
+func _on_position_changed(_v: float) -> void:
+	if _updating or _core == null or _object_id == "":
+		return
+	_core.move_object(_object_id, Vector3(_pos_x.value, _pos_y.value, _pos_z.value))
+
+
+func _on_yaw_changed(v: float) -> void:
+	if _updating or _core == null or _object_id == "":
+		return
+	var quat := Quaternion(Vector3.UP, deg_to_rad(v))
+	_core.rotate_object(_object_id, Vector4(quat.x, quat.y, quat.z, quat.w))
+
+
+func _on_scale_changed(_v: float) -> void:
+	if _updating or _core == null or _object_id == "":
+		return
+	_core.scale_object(_object_id, Vector3(_scale_x.value, _scale_y.value, _scale_z.value))
+
+
+func _on_delete_pressed() -> void:
+	if _object_id == "":
+		return
+	var id := _object_id
+	delete_requested.emit(id)
+
+
+func _add_readonly_row(label: String) -> Label:
+	var l := Label.new()
+	l.text = "%s: " % label
+	_fields_box.add_child(l)
+	return l
+
+
+func _add_spinbox_row(label_text: String) -> SpinBox:
+	var row := HBoxContainer.new()
+	var l := Label.new()
+	l.text = label_text
+	l.custom_minimum_size = Vector2(90, 0)
+	row.add_child(l)
+	var sb := SpinBox.new()
+	sb.min_value = -100000.0
+	sb.max_value = 100000.0
+	sb.step = 0.1
+	sb.allow_greater = true
+	sb.allow_lesser = true
+	row.add_child(sb)
+	_fields_box.add_child(row)
+	return sb

scripts/editor/ui/palette_panel.gd

@@ -0,0 +1,57 @@
+class_name PalettePanel
+extends VBoxContainer
+## Catalog-sourced object palette (docs/architecture/editor.md §7.2
+## `PalettePanel`). Lists every id in an `EditorObjectCatalog` and emits
+## which one the player picked; `InGameEditor` remembers it as the pending
+## `catalog_id` for the next `ObjectPlaceTool` placement.
+
+signal object_selected(catalog_id: String)
+
+var _list: ItemList
+var _catalog: EditorObjectCatalog = null
+var _ids: Array[String] = []
+
+
+func _init() -> void:
+	name = "PalettePanel"
+
+
+func _ready() -> void:
+	var header := Label.new()
+	header.text = "Palette"
+	add_child(header)
+
+	_list = ItemList.new()
+	_list.size_flags_vertical = Control.SIZE_EXPAND_FILL
+	_list.item_selected.connect(_on_item_selected)
+	add_child(_list)
+
+
+func set_catalog(catalog: EditorObjectCatalog) -> void:
+	_catalog = catalog
+	_refresh()
+
+
+func _refresh() -> void:
+	_list.clear()
+	_ids.clear()
+	if _catalog == null or not _catalog.is_loaded():
+		return
+	for id in _catalog.get_all_ids():
+		var entry := _catalog.resolve(id)
+		var label: String = entry.get("display_name", id)
+		_list.add_item(label)
+		_ids.append(id)
+
+
+func _on_item_selected(index: int) -> void:
+	if index < 0 or index >= _ids.size():
+		return
+	object_selected.emit(_ids[index])
+
+
+func get_selected_catalog_id() -> String:
+	var selected: PackedInt32Array = _list.get_selected_items()
+	if selected.is_empty():
+		return ""
+	return _ids[selected[0]]

scripts/game.gd

@@ -28,21 +28,148 @@ var _remotes: Dictionary = {}   # peer_id -> Node3D
 var _remote_prev: Dictionary = {}   # peer_id -> Vector3 (last snapshot position)
 var _status_label: Label = null
 
+## Build-mode UI, gated behind toggle_build_mode (F2) -- only ever
+## instantiated once the player actually enters build mode
+## (docs/architecture/editor.md §7.2: "Instantiated only when the player
+## enters 'build mode'... so the runtime footprint is negligible during
+## normal play"). Editing is in-memory only here; the save path to the
+## backend is a sibling task (world_persistence_impl.md).
+var _build_editor: InGameEditor = null
+
 
 func _ready() -> void:
 	_show_build_stamp()
-	if Session.active:
+	if Session.editing:
+		_open_editor_for_world()
+	elif Session.active:
 		_setup_networked()
 
 
 func _unhandled_input(event: InputEvent) -> void:
-	# ESC leaves the world back to the browser. Handled here (the scene root
+	if event.is_action_pressed("toggle_build_mode"):
+		# world_persistence_impl.md §6 D4: the non-joined "Edit world" entry
+		# already has its editor open from _ready() -- F2 here is the
+		# scratch/in-session build mode's own toggle and doesn't apply.
+		if not Session.editing:
+			get_viewport().set_input_as_handled()
+			_toggle_build_mode()
+		return
+
+	# ESC leaves the world back to the browser (or, while build mode is
+	# open, just closes build mode instead). Handled here (the scene root
 	# that owns the connection) rather than in player.gd so the teardown is
 	# a single ordered path -- doing it from two places raced _on_server_lost
 	# against the scene change and looked like a crash.
 	if event.is_action_pressed("ui_cancel"):
 		get_viewport().set_input_as_handled()
-		_leave_world()
+		if Session.editing:
+			# Non-joined editing has no play session to fall back into --
+			# closing it means leaving, same as the Close button.
+			_exit_editor_to_browser()
+		elif _build_editor != null and is_instance_valid(_build_editor):
+			_close_build_mode()
+		else:
+			_leave_world()
+
+
+## Entry point into the in-game editor (docs/architecture/editor.md §7.2).
+## Freezes the player and opens a fresh, empty in-memory chunk to edit --
+## loading a *real* chunk from the backend for editing is the sibling
+## save-path task's territory (it owns the HTTP round-trip); this task's
+## contract stops at "a correctly-editable in-memory ChunkEditorModel".
+func _toggle_build_mode() -> void:
+	if _build_editor != null and is_instance_valid(_build_editor):
+		_close_build_mode()
+	else:
+		_open_build_mode()
+
+
+func _open_build_mode() -> void:
+	var model := ChunkEditorModel.create_empty(32, 32, str(Session.world_id), "main")
+	var catalog := EditorObjectCatalog.new()
+	var err := catalog.load_catalog()
+	if err != OK:
+		push_error("game.gd: failed to load editor object catalog (%d)" % err)
+	var core := EditorCore.new(model, catalog)
+
+	_build_editor = InGameEditor.new(core)
+	_build_editor.closed.connect(_close_build_mode)
+	add_child(_build_editor)
+
+	Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+	_player.set_physics_process(false)
+	_player.set_process_unhandled_input(false)
+
+
+## Shared teardown for both close paths (F2 again, or the editor's own
+## Close button/`closed` signal) -- safe to call twice: `queue_free()` on an
+## already-freeing node and restoring already-restored player state are
+## both no-ops.
+func _close_build_mode() -> void:
+	if _build_editor != null and is_instance_valid(_build_editor):
+		_build_editor.queue_free()
+	_build_editor = null
+	_player.set_physics_process(true)
+	_player.set_process_unhandled_input(true)
+	_player._refresh_mouse_mode()
+
+
+## "Edit world" entry point from the world browser
+## (world_persistence_impl.md §6 D4 / §9 "Client/editor task"). Reached only
+## via Session.editing (set by world_list.gd's "Edit World" button, which
+## never calls /join) -- non-joined, no ENet connection, no dedicated
+## server. Loads the real chunk at (0,0,0) in the "main" room over HTTP so
+## there is something real to edit and save, falling back to a fresh empty
+## chunk at base_revision 0 for an unwritten coordinate (§8.1: "an unwritten
+## coordinate is not an error").
+func _open_editor_for_world() -> void:
+	Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+	_player.set_physics_process(false)
+	_player.set_process_unhandled_input(false)
+
+	var world_id_str := str(Session.world_id)
+	var room_slug := "main"
+	var coord := Vector3i.ZERO
+
+	var save_service := ChunkSaveService.new()
+	save_service.world_id = world_id_str
+	save_service.room_slug = room_slug
+	add_child(save_service)
+
+	var fetch_result: Dictionary = await save_service.fetch_chunk(coord)
+
+	var model: ChunkEditorModel
+	var base_revision := 0
+	if fetch_result.get("ok", false) and fetch_result.get("model") != null:
+		model = fetch_result["model"]
+		base_revision = int(fetch_result.get("revision", 0))
+	else:
+		if not fetch_result.get("ok", false):
+			push_error("game.gd: chunk fetch failed opening editor (%s) -- starting from a fresh empty chunk" % str(fetch_result.get("detail", "")))
+		model = ChunkEditorModel.create_empty(32, 32, world_id_str, room_slug, coord)
+		base_revision = 0
+
+	var catalog := EditorObjectCatalog.new()
+	var err := catalog.load_catalog()
+	if err != OK:
+		push_error("game.gd: failed to load editor object catalog (%d)" % err)
+	var core := EditorCore.new(model, catalog)
+
+	_build_editor = InGameEditor.new(core)
+	_build_editor.setup_persistence(save_service, world_id_str, room_slug, coord, base_revision)
+	_build_editor.closed.connect(_exit_editor_to_browser)
+	add_child(_build_editor)
+
+
+## Close path for the non-joined editor (ESC, or the editor's own Close
+## button/`closed` signal) -- there is no play session underneath to fall
+## back into, so this always returns to the world browser.
+func _exit_editor_to_browser() -> void:
+	if _build_editor != null and is_instance_valid(_build_editor):
+		_build_editor.queue_free()
+	_build_editor = null
+	Session.clear()
+	get_tree().change_scene_to_file("res://scenes/world_list.tscn")
 
 
 func _leave_world() -> void:

scripts/session.gd

@@ -6,11 +6,19 @@ extends Node
 ## POST /api/worlds/{id}/join; game.gd reads it in _ready() to decide whether
 ## to run networked or fall back to local single-player (e.g. game.tscn opened
 ## directly, or the backend has no orchestration).
+##
+## world_list.gd also calls begin_edit() for the "Edit world" entry point
+## (docs/architecture/world_persistence_impl.md §6 D4): editing is
+## deliberately **non-joined** -- it never calls POST /join, so `active`
+## stays false and game.gd never opens an ENet connection for it. `editing`
+## is the separate signal game.gd checks to open the in-game editor against
+## a real, HTTP-fetched chunk instead of running gameplay.
 
 var world_id: int = 0
 var host: String = ""
 var port: int = 0
 var active: bool = false
+var editing: bool = false
 
 
 func begin(p_world_id: int, p_host: String, p_port: int) -> void:
@@ -18,6 +26,18 @@ func begin(p_world_id: int, p_host: String, p_port: int) -> void:
 	host = p_host
 	port = p_port
 	active = true
+	editing = false
+
+
+## Enter "Edit world" (world_persistence_impl.md §6 D4): non-joined, no
+## ENet connection, no dedicated server. game.gd loads/saves chunks over
+## HTTP instead.
+func begin_edit(p_world_id: int) -> void:
+	world_id = p_world_id
+	host = ""
+	port = 0
+	active = false
+	editing = true
 
 
 func clear() -> void:
@@ -25,3 +45,4 @@ func clear() -> void:
 	host = ""
 	port = 0
 	active = false
+	editing = false

scripts/smoke_test_editor_core.gd

@@ -0,0 +1,260 @@
+extends SceneTree
+## Real exercise of the in-game editor's data-native core
+## (docs/architecture/editor.md §7.1/§7.2, scoped to 2D per §8).
+##
+## Loads a real chunk (the backend's golden fixture
+## backend/tests/fixtures/chunks/simple_tile_chunk.bin -- the same file
+## scripts/smoke_test_chunk_codec_interop.gd proves decodes correctly),
+## wraps it in a ChunkEditorModel, and drives every operation
+## (place/move/rotate/scale/delete an object, paint/erase a tile) through
+## the actual EditorCore.use_tool()/ToolRegistry path -- never by calling
+## ChunkEditorModel's raw setters directly, which would bypass the tool
+## layer this task was scoped to build. Then it undoes every single one of
+## those operations and checks the chunk is back to exactly its starting
+## state, redoes them all back, and finally round-trips the result through
+## encode_binary()/decode_binary() to prove the model stays a valid,
+## byte-compatible ChunkPayload throughout -- the contract the sibling
+## save-path task depends on.
+##
+## Run with:
+##     ~/godot/godot --headless --path . --script res://scripts/smoke_test_editor_core.gd
+
+const FIXTURE_PATH := "res://backend/tests/fixtures/chunks/simple_tile_chunk.bin"
+
+var passed := 0
+var failed := 0
+
+
+func _check(label: String, cond: bool) -> void:
+	if cond:
+		passed += 1
+		print("  PASS: ", label)
+	else:
+		failed += 1
+		printerr("  FAIL: ", label)
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	await _test_full_editing_loop()
+	_test_catalog_rejects_unknown_id()
+	_test_selection_is_not_undoable()
+
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	quit(0 if failed == 0 else 1)
+
+
+func _read_fixture() -> PackedByteArray:
+	var f := FileAccess.open(FIXTURE_PATH, FileAccess.READ)
+	if f == null:
+		push_error("Could not open fixture: " + FIXTURE_PATH)
+		return PackedByteArray()
+	return f.get_buffer(f.get_length())
+
+
+func _test_full_editing_loop() -> void:
+	print("--- EditorCore/ToolRegistry over a real decoded chunk (simple_tile_chunk.bin) ---")
+
+	var original_bytes := _read_fixture()
+	_check("fixture file read (non-empty)", original_bytes.size() > 0)
+	if original_bytes.is_empty():
+		return
+
+	var model := ChunkEditorModel.from_binary(original_bytes)
+	_check("ChunkEditorModel.from_binary decoded the fixture", model != null)
+	if model == null:
+		return
+
+	# Baseline sanity on the loaded real chunk before touching anything.
+	_check("loaded chunk has 1 tile layer", model.payload.tile_layers.size() == 1)
+	_check("loaded chunk is 4x4", model.get_layer(0).width == 4 and model.get_layer(0).height == 4)
+	var baseline_tiles := (model.get_layer(0).tiles as PackedInt32Array).duplicate()
+	var baseline_object_count := model.payload.objects.size()
+
+	var catalog := EditorObjectCatalog.new()
+	var cat_err := catalog.load_catalog()
+	_check("object catalog loaded", cat_err == OK)
+
+	var core := EditorCore.new(model, catalog)
+	_check("EditorCore registers all 5 tools", core.tools.get_tool_ids().size() == 5)
+	for expected_tool in ["brush", "object_place", "select", "erase", "transform"]:
+		_check("ToolRegistry has tool '%s'" % expected_tool, core.tools.has_tool(expected_tool))
+
+	# ── 1. Paint a tile via the brush tool (through EditorCore/ToolRegistry) ──
+	_check("tile (0,0) starts as 0 in the fixture", model.get_tile_raw(0, 0, 0) == 0)
+	var painted := core.paint_tile(0, 0, 0, 1)
+	_check("core.paint_tile (brush tool) applied", painted)
+	_check("tile (0,0) is now 1 after paint", model.get_tile_raw(0, 0, 0) == 1)
+
+	# ── 2. Place a catalog object (through EditorCore/ToolRegistry) ──
+	var obj_id := core.place_object("crate_small", Vector3(1.5, 1.5, 0.0))
+	_check("core.place_object (object_place tool) returned a real id", obj_id != "")
+	_check("placed object exists in the model", model.find_object(obj_id) != null)
+	_check("placed object got the catalog's asset_id", model.find_object(obj_id).asset_id == "props/crate_small.glb")
+	_check("placing auto-selected the new object", core.selection.get_selected() == obj_id)
+
+	# ── 3. Select it explicitly via the select tool ──
+	_check("core.select_object (select tool)", core.select_object(obj_id))
+	_check("selection reflects it", core.selection.get_selected() == obj_id)
+
+	# ── 4. Move / rotate / scale via the transform tool ──
+	var moved := core.move_object(obj_id, Vector3(5.0, 6.0, 0.0))
+	_check("core.move_object (transform tool) applied", moved)
+	_check("object position updated", model.find_object(obj_id).position.is_equal_approx(Vector3(5.0, 6.0, 0.0)))
+
+	var new_rot := Vector4(0.0, 0.7071068, 0.0, 0.7071068)  # 90 deg yaw
+	var rotated := core.rotate_object(obj_id, new_rot)
+	_check("core.rotate_object (transform tool) applied", rotated)
+	_check("object rotation updated", model.find_object(obj_id).rotation.is_equal_approx(new_rot))
+
+	var scaled := core.scale_object(obj_id, Vector3(2.0, 2.0, 2.0))
+	_check("core.scale_object (transform tool) applied", scaled)
+	_check("object scale updated", model.find_object(obj_id).scale.is_equal_approx(Vector3(2.0, 2.0, 2.0)))
+
+	# ── 5. Erase a different tile (the fixture already has a nonzero tile at
+	# (1,0) -- world_id 12's palette makes it a real, non-empty tile id, so
+	# erase has something genuine to clear without needing a manual seed). ──
+	var original_tile_1_0 := model.get_tile_raw(0, 1, 0)
+	_check("tile (1,0) is nonzero in the fixture (something real to erase)", original_tile_1_0 != 0)
+	var erased_tile := core.erase_tile(0, 1, 0)
+	_check("core.erase_tile (erase tool) applied", erased_tile)
+	_check("tile (1,0) is 0 after erase", model.get_tile_raw(0, 1, 0) == 0)
+
+	# ── 6. Delete the object via the erase tool ──
+	var deleted := core.delete_object(obj_id)
+	_check("core.delete_object (erase tool) applied", deleted)
+	_check("object is gone from the model", model.find_object(obj_id) == null)
+	_check("deleting the selected object cleared the selection", not core.selection.has_selection())
+
+	# ── 7. Undo every operation (6 ops) and verify each actually reverts ──
+	print("--- undo/redo actually revert each step ---")
+	_check("undo #1 (re-adds deleted object)", core.undo())
+	_check("object exists again after undo", model.find_object(obj_id) != null)
+
+	_check("undo #2 (un-erases tile)", core.undo())
+	_check("tile (1,0) is back to its original value after undo",
+		model.get_tile_raw(0, 1, 0) == original_tile_1_0)
+
+	_check("undo #3 (un-scales)", core.undo())
+	_check("scale reverted", model.find_object(obj_id).scale.is_equal_approx(Vector3.ONE))
+
+	_check("undo #4 (un-rotates)", core.undo())
+	_check("rotation reverted", model.find_object(obj_id).rotation.is_equal_approx(Vector4(0, 0, 0, 1)))
+
+	_check("undo #5 (un-moves)", core.undo())
+	_check("position reverted", model.find_object(obj_id).position.is_equal_approx(Vector3(1.5, 1.5, 0.0)))
+
+	_check("undo #6 (un-places, object removed)", core.undo())
+	_check("placed object is gone after undo", model.find_object(obj_id) == null)
+
+	_check("undo #7 (un-paints tile)", core.undo())
+	_check("tile (0,0) is back to 0 after undo", model.get_tile_raw(0, 0, 0) == 0)
+
+	_check("no more undo history", not core.undo_redo.can_undo())
+	_check("tiles exactly match the original fixture after full undo",
+		model.get_layer(0).tiles == baseline_tiles)
+	_check("object count matches the original fixture after full undo",
+		model.payload.objects.size() == baseline_object_count)
+
+	# ── 8. Redo everything back ──
+	print("--- redo replays every step forward again ---")
+	var redo_count := 0
+	while core.redo():
+		redo_count += 1
+	_check("redo replayed all 7 recorded actions", redo_count == 7)
+	_check("tile (0,0) painted again after full redo", model.get_tile_raw(0, 0, 0) == 1)
+	_check("object gone again after full redo (last op was delete)", model.find_object(obj_id) == null)
+
+	# ── 9. Round-trip the final state through encode/decode ──
+	print("--- encode_binary()/decode_binary() round-trip after editing ---")
+	var re_encoded := model.encode_binary()
+	_check("re-encoded chunk is non-empty", re_encoded.size() > 0)
+	var re_decoded := ChunkDataDecoder.decode_binary(re_encoded)
+	_check("re-decoded without error", re_decoded != null)
+	if re_decoded != null:
+		_check("re-decoded tile layer matches edited model",
+			re_decoded.tile_layers[0].tiles == model.get_layer(0).tiles)
+		_check("re-decoded world_id preserved", re_decoded.world_id == model.payload.world_id)
+		_check("re-decoded coord preserved", re_decoded.coord == model.payload.coord)
+		_check("re-decoded bounds preserved",
+			re_decoded.bounds.position.is_equal_approx(model.payload.bounds.position)
+			and re_decoded.bounds.size.is_equal_approx(model.payload.bounds.size))
+		_check("re-decoded object count matches", re_decoded.objects.size() == model.payload.objects.size())
+
+	# ── 10. Also prove a fresh in-memory chunk (no fixture) works end to end,
+	# including that the InGameEditor UI wires up against a real EditorCore
+	# without crashing headlessly. ──
+	await _test_ui_smoke()
+
+
+func _test_ui_smoke() -> void:
+	print("--- InGameEditor UI wires up against a real EditorCore (headless, no crash) ---")
+	var model := ChunkEditorModel.create_empty(8, 8, "1", "main", Vector3i.ZERO)
+	var catalog := EditorObjectCatalog.new()
+	catalog.load_catalog()
+	var core := EditorCore.new(model, catalog)
+
+	var editor := InGameEditor.new(core)
+	root.add_child(editor)
+	await process_frame  # let _ready() run so the UI is actually built
+	_check("InGameEditor instantiated and added to the tree without error", is_instance_valid(editor))
+
+	# Drive a real placement through the viewport's own click handler (not a
+	# bare model mutation) to prove the UI layer -> EditorCore wiring works.
+	# EditorViewport is nested a few levels down (ScrollContainer, etc.).
+	var viewport: EditorViewport = _find_viewport(editor)
+	_check("EditorViewport exists in the built UI", viewport != null)
+	if viewport != null:
+		viewport.pending_catalog_id = "rock_01"
+		core.tools.set_active_tool("object_place")
+		viewport._handle_click(Vector2(20, 20))  # inside tile (0,0) at cell_size 24
+		_check("clicking with object_place active through the viewport placed an object",
+			model.payload.objects.size() == 1)
+
+	editor.queue_free()
+
+
+func _find_viewport(node: Node) -> EditorViewport:
+	if node is EditorViewport:
+		return node
+	for child in node.get_children():
+		var found := _find_viewport(child)
+		if found != null:
+			return found
+	return null
+
+
+func _test_catalog_rejects_unknown_id() -> void:
+	print("--- object_place tool rejects an unknown catalog id ---")
+	var model := ChunkEditorModel.create_empty()
+	var catalog := EditorObjectCatalog.new()
+	catalog.load_catalog()
+	var core := EditorCore.new(model, catalog)
+
+	var result := core.place_object("does_not_exist", Vector3.ZERO)
+	_check("unknown catalog_id is rejected (empty id returned)", result == "")
+	_check("nothing was added to the model", model.payload.objects.is_empty())
+	_check("nothing was pushed onto the undo stack", not core.undo_redo.can_undo())
+
+
+func _test_selection_is_not_undoable() -> void:
+	print("--- selection is UI state, not chunk data (not on the undo stack) ---")
+	var model := ChunkEditorModel.create_empty()
+	var catalog := EditorObjectCatalog.new()
+	catalog.load_catalog()
+	var core := EditorCore.new(model, catalog)
+
+	var obj_id := core.place_object("chest_01", Vector3(2, 2, 0))
+	_check("setup: object placed", obj_id != "")
+	core.select_object(obj_id)
+	_check("object selected", core.selection.get_selected() == obj_id)
+
+	# Only one undoable action should exist (the placement) -- selecting it
+	# must not have added a second one.
+	core.undo()
+	_check("a single undo removes the placed object (selection wasn't a 2nd undo step)",
+		model.find_object(obj_id) == null)
+	_check("no further undo history from selection", not core.undo_redo.can_undo())

scripts/smoke_test_editor_save.gd

@@ -0,0 +1,200 @@
+extends SceneTree
+## Real integration test for ChunkSaveService against a live backend.
+##
+## Covers docs/architecture/world_persistence_impl.md §8.1/§8.2 (this task's
+## §9 "Client/editor task" items 2-3):
+##   1. single-chunk PUT with X-Base-Revision (via the JSON base_revision
+##      field, exercised through the same route the client hits)
+##   2. a real 409 -> re-fetch -> retry cycle
+##   3. batch PUT of multiple chunks in one atomic call
+##   4. the live_session response flag actually reaching the caller
+##   5. persistence survives a real reload (save, then re-fetch, confirm)
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_editor_save.gd
+##
+## Requires the backend to be running (AGP_API_BASE_URL, default
+## http://127.0.0.1:8000).
+
+var passed := 0
+var failed := 0
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	await process_frame
+
+	var api := root.get_node("ApiClient")
+
+	randomize()
+	var unique_id: int = int(Time.get_unix_time_from_system() * 1000) + randi() % 100000
+	var username := "editorsave_%d" % unique_id
+	var email := "editorsave_%d@test.example.com" % unique_id
+	var reg: Dictionary = await api.register(username, email, "SmokeTest123!", "1990-01-01")
+	if not _check("setup: register succeeded", reg.ok):
+		print("  detail: ", reg.detail)
+		_finish()
+		return
+
+	var world_body := JSON.stringify({
+		"name": "EditorSave Smoke World %d" % unique_id,
+		"visibility": "public",
+	})
+	var world_result: Dictionary = await api.request(
+		HTTPClient.METHOD_POST, "/api/worlds/", world_body, "application/json", true
+	)
+	if not _check("setup: world created", world_result.ok):
+		print("  detail: ", world_result.detail)
+		_finish()
+		return
+	var world_id: int = (world_result.data as Dictionary)["id"]
+
+	var save_service := ChunkSaveService.new()
+	save_service.world_id = str(world_id)
+	save_service.room_slug = "main"
+	root.add_child(save_service)
+
+	await _test_single_save_and_reload(save_service, world_id)
+	await _test_409_retry(save_service)
+	await _test_batch_save(save_service)
+	await _test_live_session_flag(save_service, world_id, api)
+
+	_finish()
+
+
+## 1 + 5. Single-chunk save at (0,0,0), then a fresh fetch (simulating a
+## reload) confirms the edit actually persisted server-side.
+func _test_single_save_and_reload(save_service: ChunkSaveService, world_id: int) -> void:
+	print("--- single-chunk save, then reload ---")
+	var coord := Vector3i(0, 0, 0)
+	var model := ChunkEditorModel.create_empty(32, 32, str(world_id), "main", coord)
+	model.set_tile_raw(0, 3, 4, 0, 1)
+
+	var save_result: Dictionary = await save_service.save_chunk(model, coord, 0)
+	if not _check("save_chunk: single PUT (base_revision 0, create) succeeded", save_result.get("ok", false)):
+		print("  detail: ", save_result.get("detail", ""))
+		return
+	_check("save_chunk: server returned revision 1 for a fresh chunk", int(save_result.get("revision", -1)) == 1)
+	_check("save_chunk: live_session present and false (no dedicated server running)",
+		save_result.get("live_session", true) == false)
+
+	# Simulate a reload: a brand new fetch, independent of the model we just
+	# edited in memory.
+	var reload := ChunkSaveService.new()
+	reload.world_id = str(world_id)
+	reload.room_slug = "main"
+	save_service.get_parent().add_child(reload)
+	var fetch_result: Dictionary = await reload.fetch_chunk(coord)
+	if not _check("reload: fetch after save succeeded", fetch_result.get("ok", false) and fetch_result.get("model") != null):
+		print("  detail: ", fetch_result.get("detail", ""))
+		reload.queue_free()
+		return
+	var reloaded_model: ChunkEditorModel = fetch_result["model"]
+	_check("reload: revision matches what save reported", int(fetch_result.get("revision", -1)) == int(save_result.get("revision", -2)))
+	_check("reload: painted tile (3,4) survived the round trip", reloaded_model.get_tile_raw(0, 3, 4) == 1)
+	reload.queue_free()
+
+
+## 2. A real 409: two independent saves race against the same base_revision;
+## the loser's save_chunk() must transparently re-fetch + retry and still
+## succeed (this is exactly the class doc's "no delta to replay, only the
+## base to refresh" case -- the retry keeps the loser's own edit).
+func _test_409_retry(save_service: ChunkSaveService) -> void:
+	print("--- real 409 conflict -> re-fetch -> retry ---")
+	var coord := Vector3i(1, 0, 0)
+	var world_id_str := save_service.world_id
+
+	var model_a := ChunkEditorModel.create_empty(32, 32, world_id_str, "main", coord)
+	model_a.set_tile_raw(0, 0, 0, 0, 1)
+	var first: Dictionary = await save_service.save_chunk(model_a, coord, 0)
+	if not _check("setup: first save at (1,0,0) succeeded", first.get("ok", false)):
+		print("  detail: ", first.get("detail", ""))
+		return
+	var stale_revision: int = int(first.get("revision", 1))
+
+	# Advance the server past what "model_b" below still thinks is current,
+	# by saving again from the correct revision.
+	var model_advance := ChunkEditorModel.create_empty(32, 32, world_id_str, "main", coord)
+	model_advance.set_tile_raw(0, 1, 1, 0, 1)
+	var second: Dictionary = await save_service.save_chunk(model_advance, coord, stale_revision)
+	if not _check("setup: advancing save succeeded", second.get("ok", false)):
+		print("  detail: ", second.get("detail", ""))
+		return
+
+	# model_b still has the now-stale revision as its base -- this must 409
+	# internally and ChunkSaveService must resolve it on its own.
+	var model_b := ChunkEditorModel.create_empty(32, 32, world_id_str, "main", coord)
+	model_b.set_tile_raw(0, 2, 2, 0, 1)
+	var conflicted: Dictionary = await save_service.save_chunk(model_b, coord, stale_revision)
+	if not _check("save_chunk: stale base_revision still ends in success (409 handled internally)", conflicted.get("ok", false)):
+		print("  detail: ", conflicted.get("detail", ""))
+		return
+	_check("save_chunk: reports that a retry actually happened", conflicted.get("retried", false) == true)
+	_check("save_chunk: revision advanced past the stale one", int(conflicted.get("revision", -1)) > stale_revision)
+
+	# Confirm the loser's edit (not the advancing one) is what's actually
+	# stored -- proves "re-apply the edit" really means "the retry keeps our
+	# own locally edited payload".
+	var check_fetch: Dictionary = await save_service.fetch_chunk(coord)
+	_check("post-conflict fetch: the retried edit (not the earlier advance) is what's stored",
+		check_fetch.get("ok", false) and (check_fetch["model"] as ChunkEditorModel).get_tile_raw(0, 2, 2) == 1)
+
+
+## 3. Batch PUT: two chunks written atomically in one call.
+func _test_batch_save(save_service: ChunkSaveService) -> void:
+	print("--- batch PUT (multi-chunk edit) ---")
+	var world_id_str := save_service.world_id
+	var coord_a := Vector3i(5, 0, 0)
+	var coord_b := Vector3i(5, 1, 0)
+
+	var model_a := ChunkEditorModel.create_empty(32, 32, world_id_str, "main", coord_a)
+	model_a.set_tile_raw(0, 7, 7, 0, 1)
+	var model_b := ChunkEditorModel.create_empty(32, 32, world_id_str, "main", coord_b)
+	model_b.set_tile_raw(0, 8, 8, 0, 1)
+
+	var batch_result: Dictionary = await save_service.save_batch([
+		{"coord": coord_a, "model": model_a, "base_revision": 0},
+		{"coord": coord_b, "model": model_b, "base_revision": 0},
+	])
+	if not _check("save_batch: atomic 2-chunk PUT succeeded", batch_result.get("ok", false)):
+		print("  detail: ", batch_result.get("detail", ""))
+		return
+	_check("save_batch: response lists both chunks", (batch_result.get("chunks", []) as Array).size() == 2)
+
+	var fetch_a: Dictionary = await save_service.fetch_chunk(coord_a)
+	var fetch_b: Dictionary = await save_service.fetch_chunk(coord_b)
+	_check("save_batch: chunk A actually persisted", fetch_a.get("ok", false) and (fetch_a["model"] as ChunkEditorModel).get_tile_raw(0, 7, 7) == 1)
+	_check("save_batch: chunk B actually persisted", fetch_b.get("ok", false) and (fetch_b["model"] as ChunkEditorModel).get_tile_raw(0, 8, 8) == 1)
+
+
+## 4. live_session: with a fake dedicated-server registration for this
+## world, a save must come back with live_session == true instead of the
+## flag being silently dropped.
+func _test_live_session_flag(save_service: ChunkSaveService, world_id: int, api: Object) -> void:
+	print("--- live_session flag surfaced on a write ---")
+	# There's no public API to fake a live game-server registration for this
+	# world from the client side (that's internal/game_servers.py state) --
+	# so this asserts the flag is at least always present and well-typed on
+	# a normal save, which is what the editor UI's warning path branches on.
+	var coord := Vector3i(9, 9, 0)
+	var model := ChunkEditorModel.create_empty(32, 32, str(world_id), "main", coord)
+	var result: Dictionary = await save_service.save_chunk(model, coord, 0)
+	_check("save_chunk: result always carries a boolean live_session field", result.has("live_session") and typeof(result["live_session"]) == TYPE_BOOL)
+
+
+func _check(description: String, condition: bool) -> bool:
+	if condition:
+		print("  PASS: ", description)
+		passed += 1
+	else:
+		printerr("  FAIL: ", description)
+		failed += 1
+	return condition
+
+
+func _finish() -> void:
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	quit(0 if failed == 0 else 1)

scripts/smoke_test_world_list.gd

@@ -48,6 +48,11 @@ func _run() -> void:
 
 	var api := root.get_node("ApiClient")
 	assert(api != null, "ApiClient autoload not found")
+	# Bare autoload identifiers (e.g. `Session`) don't resolve when a script
+	# is compiled for a headless `godot --script ...` run -- same note as
+	# HttpChunkSource._api_client() / ChunkSaveService._api_client().
+	var session := root.get_node("Session")
+	assert(session != null, "Session autoload not found")
 
 	var passed: int = 0
 	var failed: int = 0
@@ -150,6 +155,32 @@ func _run() -> void:
 			else:
 				failed += 1
 
+		# --- Test 3: "Edit World" entry point (world_persistence_impl.md
+		# §6 D4) -- shown for the seeded world's owner (this test's own
+		# user), and, critically, wired to Session.begin_edit() rather than
+		# ApiClient.join_world() -- pressing it must never call /join.
+		print("\n=== Test 3: Edit World entry point (owner-gated, non-joined) ===")
+		var owned_buttons := _find_buttons_in_first_card(world_list_node)
+		var edit_button: Button = null
+		for b in owned_buttons:
+			if b.text == "Edit World":
+				edit_button = b
+		if _check("owner's card shows an Edit World button", edit_button != null):
+			passed += 1
+		else:
+			failed += 1
+
+		if edit_button != null:
+			session.clear()
+			edit_button.pressed.emit()
+			var editing_set: bool = session.editing and not session.active and session.world_id == int((create_result.data as Dictionary)["id"])
+			if _check("pressing Edit World sets Session.editing (non-joined) for the right world, not Session.active", editing_set):
+				passed += 1
+			else:
+				failed += 1
+				print("  Session: editing=%s active=%s world_id=%s" % [session.editing, session.active, session.world_id])
+			session.clear()
+
 	# --- Summary ---
 	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
 	if failed > 0:
@@ -159,6 +190,22 @@ func _run() -> void:
 		quit(0)
 
 
+## Depth-first collect every Button under the first rendered world card.
+func _find_buttons_in_first_card(world_list_node: VBoxContainer) -> Array:
+	var out: Array = []
+	if world_list_node.get_child_count() == 0:
+		return out
+	_collect_buttons(world_list_node.get_child(0), out)
+	return out
+
+
+func _collect_buttons(node: Node, out: Array) -> void:
+	if node is Button:
+		out.append(node)
+	for c in node.get_children():
+		_collect_buttons(c, out)
+
+
 func _check(description: String, condition: bool) -> bool:
 	if condition:
 		print("  PASS: ", description)

scripts/world_list.gd

@@ -14,6 +14,13 @@ extends Control
 @onready var back_button: Button = $VBoxContainer/HeaderHBox/BackButton
 @onready var empty_label: Label = $VBoxContainer/EmptyLabel
 
+## Cached so each world card can decide whether to show "Edit World"
+## (docs/architecture/world_persistence_impl.md §5.3: chunk writes require
+## `world.owner_id == caller`, same as `update_world`) without an extra
+## round trip per card. -1 until resolved / on failure, in which case no
+## card shows the edit entry point.
+var _current_user_id: int = -1
+
 
 func _ready() -> void:
 	refresh_button.disabled = false
@@ -22,6 +29,11 @@ func _ready() -> void:
 	error_label.visible = false
 	empty_label.visible = false
 	world_list.visible = false
+
+	var me_result: Dictionary = await ApiClient.get_me()
+	if me_result.ok and me_result.data is Dictionary:
+		_current_user_id = int((me_result.data as Dictionary).get("id", -1))
+
 	_refresh_worlds()
 
 
@@ -146,10 +158,26 @@ func _create_world_card(world_dict: Dictionary) -> Control:
 	enter_button.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
 	enter_button.pressed.connect(_on_enter_world_pressed.bind(world_id, enter_button))
 
+	var buttons_row := HBoxContainer.new()
+	buttons_row.add_child(enter_button)
+
+	# "Edit World" (world_persistence_impl.md §6 D4): a non-joined entry
+	# point into the in-game editor -- it does NOT call POST /join. Only
+	# shown for the world's owner, matching the write-side authorization the
+	# save path itself enforces (§5.3), so a non-owner never sees a button
+	# that would just 403 on the first save.
+	var owner_id := int(world_dict.get("owner_id", -1))
+	if _current_user_id != -1 and owner_id == _current_user_id:
+		var edit_button := Button.new()
+		edit_button.text = "Edit World"
+		edit_button.size_flags_horizontal = Control.SIZE_SHRINK_BEGIN
+		edit_button.pressed.connect(_on_edit_world_pressed.bind(world_id))
+		buttons_row.add_child(edit_button)
+
 	card.add_child(name_label)
 	card.add_child(desc_label)
 	card.add_child(meta_label)
-	card.add_child(enter_button)
+	card.add_child(buttons_row)
 
 	return panel
 
@@ -176,3 +204,11 @@ func _on_enter_world_pressed(world_id: int, button: Button) -> void:
 	button.text = "Enter World"
 	error_label.text = "Couldn't join: %s" % result.detail
 	error_label.visible = true
+
+
+## Enter build mode for this world without joining it
+## (world_persistence_impl.md §6 D4). No /join call, no ENet connection, no
+## dedicated server -- game.gd loads/saves the world's chunks over HTTP.
+func _on_edit_world_pressed(world_id: int) -> void:
+	Session.begin_edit(world_id)
+	get_tree().change_scene_to_file("res://scenes/game.tscn")