test commit as coder-bot

docs/architecture/content_moderation.md

@@ -0,0 +1,426 @@
+# Content Moderation & Age Verification Architecture
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Server authority + client prediction, avatar component system, backend auth (JWT)
+
+## 1. Overview
+
+This document specifies the **content moderation** and **age verification**
+architecture for **agp-game**, a Godot-based multiplayer game built by
+autonomous agents. It defines:
+
+- How **content flags** propagate through the system across the three primary
+  content types: **assets**, **rooms**, and **scripts**.
+- How flags are **evaluated, aggregated, and enforced** at load time, at
+  runtime, and at the network boundary.
+- The **age verification flow**, combining a lightweight **self-declaration**
+  with an optional **ID check hook** for higher-assurance verification.
+
+The goal is a **single, consistent moderation pipeline** that applies the same
+rules to user-generated content (UGC) regardless of whether it is a 3D asset, a
+room definition, or a script, and that gates access to mature content behind a
+verifiable age gate.
+
+### 1.1 Design Goals
+
+- **Uniformity:** One flag vocabulary and one propagation mechanism across
+  assets, rooms, and scripts.
+- **Composability:** Flags on a room aggregate the flags of the assets and
+  scripts it contains; flags on a world aggregate the flags of its rooms.
+- **Enforcement at the boundary:** The server is authoritative for what content
+  a client may load or receive, mirroring the server-authoritative networking
+  model.
+- **Privacy-preserving age checks:** Self-declaration requires no PII; the ID
+  check hook is optional, pluggable, and never stores raw identity documents.
+- **Auditability:** Every flag decision is logged with a reason, an actor, and
+  a timestamp so moderation actions are reviewable.
+
+---
+
+## 2. Content Flag Vocabulary
+
+All content carries a set of **content flags**. A flag is a typed, immutable
+label with a **severity** and a **scope**. Flags are the atomic unit of
+moderation; everything else (aggregation, enforcement, gating) operates on
+flags.
+
+### 2.1 Flag Definition
+
+A flag is a structured record:
+
+| Field      | Type      | Description                                                              |
+|------------|-----------|--------------------------------------------------------------------------|
+| `id`       | `string`  | Stable machine-readable identifier, e.g. `violence.gore`.                |
+| `label`    | `string`  | Human-readable name, e.g. "Graphic Gore".                                |
+| `category` | `enum`    | One of `violence`, `sexual`, `language`, `substance`, `gambling`, `horror`, `hate`, `custom`. |
+| `severity` | `enum`    | One of `none`, `mild`, `moderate`, `severe`.                             |
+| `scope`    | `enum`    | One of `visual`, `audio`, `text`, `behavior`, `interaction`.             |
+| `mature`   | `bool`    | Whether this flag triggers the age gate (see §5).                        |
+| `reason`   | `string`  | Free-text justification supplied by the flagger.                         |
+| `source`   | `enum`    | One of `author`, `moderator`, `automated`, `community`.                  |
+
+### 2.2 Canonical Flag Set
+
+The platform defines a **canonical registry** of flags so that different
+content types and different flaggers use the same vocabulary. Examples:
+
+| id                          | category   | severity  | scope        | mature |
+|-----------------------------|------------|-----------|--------------|--------|
+| `violence.none`             | violence   | none      | visual       | false  |
+| `violence.mild`             | violence   | mild      | visual       | false  |
+| `violence.gore`             | violence   | severe    | visual       | true   |
+| `sexual.suggestive`         | sexual     | mild      | visual       | true   |
+| `sexual.explicit`           | sexual     | severe    | visual       | true   |
+| `language.mild`             | language   | mild      | text         | false  |
+| `language.profanity`        | language   | moderate  | text         | false  |
+| `substance.references`      | substance  | mild      | text         | false  |
+| `gambling.simulated`        | gambling   | moderate  | behavior     | true   |
+| `horror.jumpscare`          | horror     | mild      | audio/visual | false  |
+| `hate.hateful`              | hate       | severe    | text         | true   |
+
+The registry is **data-driven** (a JSON/YAML manifest shipped with the server)
+so new flags can be added without code changes.
+
+---
+
+## 3. Flag Propagation Model
+
+Flags propagate through the system along the **content dependency graph**. The
+three content types form a hierarchy:
+
+```
+World
+ └── Room
+      ├── Asset  (mesh, texture, audio, animation, material)
+      └── Script (behavior, dialogue, event logic)
+```
+
+### 3.1 Propagation Rules
+
+1. **Explicit flags** are set directly on a content item by its author or a
+   moderator.
+2. **Inherited flags** flow upward: a room's effective flag set is the **union**
+   of its own explicit flags and the flags of every asset and script it
+   references.
+3. **Aggregation** uses the **maximum severity** per category across all
+   contributing items. A room containing one `violence.gore` asset and one
+   `violence.none` asset is `violence.severe`.
+4. **Maturity is monotonic:** if any contributing item is `mature`, the
+   containing room and world are `mature`.
+5. **Cycles are impossible** by construction: content references form a DAG
+   (an asset cannot contain a room; a room cannot contain itself).
+
+### 3.2 Propagation Through the Pipeline
+
+Flags are attached at **authoring time** and carried through every stage:
+
+```
+Authoring ──► Upload ──► Validation ──► Storage ──► Distribution ──► Runtime
+   │            │            │             │             │              │
+   │ flag       │ flag       │ automated   │ flag        │ flag         │ flag
+   │ declared   │ preserved  │ scan adds   │ indexed     │ re-checked   │ enforced
+   │            │            │ flags       │             │              │
+```
+
+| Stage        | Responsibility                                                          |
+|--------------|-------------------------------------------------------------------------|
+| **Authoring**| Author declares flags in the editor/upload UI.                          |
+| **Upload**   | Flags are validated against the canonical registry; unknown flags rejected. |
+| **Validation**| Automated scanner (hash-based + heuristic) adds flags for detected content. |
+| **Storage**  | Flags are stored alongside the content record and indexed for queries.  |
+| **Distribution**| Flags are re-checked against the current registry before serving.     |
+| **Runtime**  | The client enforces flags before loading content (see §4).              |
+
+### 3.3 Data Model
+
+Flags are stored as a **normalized join table** so they can be queried and
+aggregated efficiently:
+
+```
+content_item (id, type, owner_id, ...)
+content_flag  (content_id, flag_id, source, reason, created_at, actor_id)
+flag_registry (id, category, severity, scope, mature, ...)
+```
+
+Aggregation is computed by a SQL view / query that joins a content item's
+transitive dependencies. Because the graph is a DAG, this is a bounded
+recursive query (PostgreSQL `WITH RECURSIVE`).
+
+---
+
+## 4. Enforcement
+
+Enforcement happens at three layers, in order:
+
+### 4.1 Load-Time Enforcement (Server)
+
+Before a client is allowed to **request** content, the server evaluates the
+content's effective flag set against the requesting account's **content
+preferences** and **age verification status**:
+
+- If the content is `mature` and the account is **not age-verified**, the
+  request is **rejected** with a `403 MATURE_CONTENT_REQUIRES_VERIFICATION`.
+- If the content's flags exceed the account's **content filter** (a per-account
+  severity threshold per category), the request is rejected or the offending
+  content is **stripped** (e.g., audio muted, mesh hidden, script not loaded).
+
+### 4.2 Runtime Enforcement (Client)
+
+The client receives a **manifest** of allowed content from the server. It never
+loads content that is not in the manifest. This prevents a malicious or buggy
+client from bypassing the server's filter by loading content directly.
+
+- Assets not in the manifest are **not instantiated**.
+- Scripts not in the manifest are **not executed**.
+- Rooms not in the manifest are **not entered**.
+
+### 4.3 Network Boundary Enforcement
+
+The server **filters replication** based on flags:
+
+- Mature or filtered content is **not replicated** to clients that cannot
+  receive it.
+- A room's flag set is broadcast in the room metadata so clients can show a
+  warning before entry.
+
+### 4.4 Enforcement Decision Flow
+
+```
+Client requests content C for account A
+        │
+        ▼
+Compute effective flags F(C)   [union + max-severity aggregation]
+        │
+        ▼
+Is A age-verified?  ──no──►  Is F(C).mature? ──yes──► REJECT (403)
+        │ yes                     │ no
+        ▼                         ▼
+Does F(C) exceed A's filter? ──► yes ──► REJECT or STRIP
+        │ no
+        ▼
+Serve content + manifest
+```
+
+---
+
+## 5. Age Verification Flow
+
+Age verification is a **two-tier** system:
+
+- **Tier 1 — Self-declaration:** The user asserts their date of birth. This is
+  fast, requires no PII beyond a birthdate, and is sufficient for most content.
+- **Tier 2 — ID check (optional hook):** A pluggable identity-verification
+  provider confirms the user is an adult. This raises the account's assurance
+  level and unlocks the highest maturity tier.
+
+### 5.1 Verification States
+
+An account has an **age verification status**:
+
+| Status            | Meaning                                                              |
+|-------------------|----------------------------------------------------------------------|
+| `unverified`      | No declaration on file.                                              |
+| `self_declared`   | User declared a birthdate; **not** independently confirmed.          |
+| `id_verified`     | User passed the ID check hook; independently confirmed adult.        |
+| `rejected`        | ID check failed or declaration was inconsistent.                     |
+
+### 5.2 Tier 1 — Self-Declaration Flow
+
+```
+User submits { date_of_birth }
+        │
+        ▼
+Server validates format & plausibility (age 13–120, not in future)
+        │
+        ▼
+Compute age from DOB
+        │
+        ▼
+age >= 18 ──► status = self_declared (adult)
+age >= 13 ──► status = self_declared (minor, restricted)
+age <  13 ──► status = rejected (below minimum platform age)
+```
+
+- The DOB is stored **encrypted at rest** and is **never exposed** to other
+  players.
+- A user may **upgrade** from `self_declared` to `id_verified` at any time via
+  Tier 2.
+
+### 5.3 Tier 2 — ID Check Hook
+
+The ID check is an **optional, pluggable hook**. The platform defines an
+interface; concrete providers (e.g., a third-party KYC service) implement it.
+
+```
+User requests ID verification
+        │
+        ▼
+Server creates a verification session (idempotent, expiring)
+        │
+        ▼
+Server calls provider hook:  verify(identity_token) -> { adult: bool, ref: string }
+        │
+        ▼
+adult == true ──► status = id_verified, store provider ref (not raw doc)
+adult == false ─► status = rejected
+provider error ──► status unchanged, retry allowed
+```
+
+**Privacy guarantees:**
+
+- The platform **never stores** the raw identity document or image.
+- Only the provider's **opaque reference** and the boolean `adult` result are
+  persisted.
+- The hook is **asynchronous and idempotent**; a session can be retried without
+  double-charging or double-verifying.
+
+### 5.4 Hook Interface
+
+The ID check hook is defined as a backend interface (FastAPI dependency /
+abstract service):
+
+```python
+class IdentityVerificationProvider(Protocol):
+    def create_session(self, user_id: str) -> VerificationSession: ...
+    def verify(self, session_id: str, identity_token: str) -> VerificationResult: ...
+
+class VerificationResult:
+    adult: bool
+    provider_ref: str | None
+    error: str | None
+```
+
+A default **no-op provider** returns `adult=False` with a clear error, so the
+system runs without any third-party integration until one is configured.
+
+### 5.5 Age Gate Enforcement
+
+The age gate is enforced at **load time** (see §4.1):
+
+| Verification status | Can access `mature` content? |
+|---------------------|------------------------------|
+| `unverified`        | No                           |
+| `self_declared`     | Yes (adult) / No (minor)     |
+| `id_verified`       | Yes                          |
+| `rejected`          | No                           |
+
+---
+
+## 6. Moderation Workflow
+
+### 6.1 Flagging Sources
+
+Content can be flagged by:
+
+- **Author** (self-declared at upload).
+- **Automated scanner** (hash-based detection, heuristic analysis).
+- **Community** (players report content; reports become flags after review).
+- **Moderator** (manual review and override).
+
+### 6.2 Review Queue
+
+Community and automated flags enter a **review queue**. A moderator either:
+
+- **Approves** the flag (it becomes authoritative), or
+- **Rejects** the flag (it is discarded), or
+- **Escalates** to a senior moderator for severe/hate flags.
+
+### 6.3 Actions
+
+Once a flag is authoritative, a moderator can take actions:
+
+| Action          | Effect                                                        |
+|-----------------|---------------------------------------------------------------|
+| `warn`          | Notify the author; content remains.                           |
+| `restrict`      | Content hidden from users below a filter threshold.           |
+| `age_gate`      | Content marked `mature`; requires age verification.           |
+| `remove`        | Content taken down; not served.                               |
+| `ban_author`    | Author's upload privileges suspended.                         |
+
+### 6.4 Audit Log
+
+Every flag and action is written to an **audit log**:
+
+```
+audit_event (id, content_id, actor_id, action, flag_id, reason, created_at)
+```
+
+This log is append-only and used for transparency and dispute resolution.
+
+---
+
+## 7. Client-Side Integration (Godot)
+
+### 7.1 Content Manifest
+
+The server sends each client a **content manifest** — the set of content the
+client is permitted to load, derived from the account's verification status and
+filter. The Godot client:
+
+- Loads only manifest-listed assets.
+- Executes only manifest-listed scripts.
+- Shows a **maturity warning** dialog before entering a room whose effective
+  flags include `mature` content.
+
+### 7.2 Flag Metadata on Content
+
+Each content resource carries a `content_flags` metadata field (a Godot
+`Dictionary` or custom `Resource`). The client uses this for local UI decisions
+(e.g., showing a warning icon) but **never** as the authority for whether to
+load — the server manifest is authoritative.
+
+### 7.3 Age Verification UI
+
+The client exposes an **age verification screen**:
+
+- Tier 1: a date-of-birth picker.
+- Tier 2: a button that opens the ID check provider flow (deep link / webview).
+
+The client calls the backend endpoints (§8) and reflects the resulting status.
+
+---
+
+## 8. Backend API Surface
+
+| Method | Path                              | Description                                    |
+|--------|-----------------------------------|------------------------------------------------|
+| `POST` | `/v1/age/declare`                 | Submit self-declared DOB (Tier 1).             |
+| `POST` | `/v1/age/verify/session`          | Create an ID-check session (Tier 2).           |
+| `POST` | `/v1/age/verify/confirm`          | Confirm an ID-check session with a token.      |
+| `GET`  | `/v1/age/status`                  | Return the account's verification status.      |
+| `GET`  | `/v1/content/{id}/flags`          | Return a content item's effective flags.       |
+| `POST` | `/v1/content/{id}/flags`          | Add a flag (author/community).                 |
+| `POST` | `/v1/moderation/review/{flag_id}` | Moderator approve/reject/escalate.             |
+| `POST` | `/v1/moderation/action`           | Apply a moderation action.                     |
+| `GET`  | `/v1/manifest`                    | Return the client's permitted content manifest.|
+
+All endpoints require a valid **JWT** (matching the existing auth stack). The
+age endpoints additionally require the account to be in a non-`rejected` state.
+
+---
+
+## 9. Security & Privacy Considerations
+
+- **DOB encryption:** Self-declared birthdates are encrypted at rest; only the
+  derived age and verification status are used in authorization decisions.
+- **No raw identity storage:** The ID check hook persists only a provider
+  reference and a boolean result.
+- **Server authority:** The client manifest prevents bypass; the client never
+  trusts its own flag metadata for access decisions.
+- **Rate limiting:** Age-declaration and ID-check endpoints are rate-limited to
+  prevent abuse and enumeration.
+- **Auditability:** All flag and verification events are logged append-only.
+
+---
+
+## 10. Open Questions / Future Work
+
+- **Regional age thresholds:** Different jurisdictions may require different
+  minimum ages; the threshold should be configurable per region.
+- **Parental controls:** A future feature may let a parent set a content filter
+  on a minor's account.
+- **Automated scanner accuracy:** The heuristic scanner may produce false
+  positives; a confidence score should be attached to automated flags.
+- **Offline / local content:** How flags apply to locally-authored content that
+  is never uploaded remains to be defined.

docs/architecture/networking.md

@@ -0,0 +1,286 @@
+# Multiplayer Networking Architecture
+
+> **Status:** Proposed
+> **Owner:** Platform team
+> **Related:** Server authority + client prediction
+
+## 1. Overview
+
+This document specifies the multiplayer networking architecture for **agp-game**,
+a Godot-based game built by autonomous agents. The architecture follows a
+**server-authoritative model with client-side prediction and reconciliation**,
+which is the industry standard for fast-paced, competitive multiplayer games.
+
+The goals of this architecture are:
+
+- **Fairness & anti-cheat:** The server is the single source of truth for all
+  gameplay state. Clients never directly mutate world state.
+- **Responsiveness:** Client-side prediction hides network latency so local input
+  feels immediate.
+- **Determinism:** The server runs a fixed-timestep simulation so that state is
+  reproducible and testable.
+- **Scalability:** A clear separation between transport, simulation, and
+  replication layers allows the server to be tuned independently.
+
+---
+
+## 2. Transport Choice: ENet over WebSocket
+
+### 2.1 Decision
+
+We choose **ENet** as the primary transport for gameplay traffic.
+
+### 2.2 Justification
+
+| Criterion            | ENet                                   | WebSocket (TCP)                     |
+|----------------------|----------------------------------------|-------------------------------------|
+| **Reliability model**| Reliable + unreliable channels         | Reliable only (TCP)                 |
+| **Latency**          | Low; unreliable packets skip retransmit| Head-of-line blocking on loss       |
+| **Packet ordering**  | Per-channel ordering                   | Global strict ordering              |
+| **Congestion control**| Lightweight, game-oriented            | TCP-style (slow start, backoff)     |
+| **Godot support**    | First-class (`ENetConnection`, `MultiplayerPeerENet`) | Supported but TCP-based |
+| **Use case fit**     | Real-time action game                  | Chat, lobby, HTTP-style messaging   |
+
+**Rationale:**
+
+- **Movement & state replication** are latency-sensitive and tolerate occasional
+  packet loss. ENet's *unreliable* channel lets us send position snapshots at high
+  frequency without head-of-line blocking.
+- **RPCs that must be delivered** (e.g., interactions, spawns) use ENet's
+  *reliable* channel, giving us exactly the semantics we need without TCP's
+  retransmission stalls.
+- Godot's `MultiplayerPeerENet` is mature and integrates directly with the
+  high-level multiplayer API (`MultiplayerAPI`, `rpc()`).
+
+### 2.3 WebSocket as a Secondary Transport
+
+WebSocket remains available as a **secondary transport** for:
+
+- **Lobby / matchmaking** messaging (low-frequency, must-be-reliable).
+- **Browser builds** where raw UDP/ENet is unavailable.
+- **Admin / telemetry** channels.
+
+The transport layer is abstracted behind an interface so gameplay code does not
+depend on the underlying protocol.
+
+---
+
+## 3. Server-Side Game Loop
+
+### 3.1 Tick Rate
+
+- **Simulation tick rate:** **30 Hz** (33.33 ms per tick).
+- **Replication / snapshot rate:** **30 Hz**, aligned with the simulation tick.
+
+**Justification:**
+
+- 30 Hz is sufficient for smooth movement and interaction in a top-down / 2D
+  action game while keeping CPU and bandwidth costs predictable.
+- A fixed timestep (rather than delta-time) makes the simulation deterministic
+  and testable.
+- The tick rate is a **configuration constant** so it can be raised (e.g., to
+  60 Hz) for competitive modes without architectural changes.
+
+### 3.2 Authority Model
+
+- **Server is authoritative** for:
+  - Player position, velocity, and physics state.
+  - Health, damage, and death.
+  - Item pickups, inventory, and world-object state.
+  - Spawning and despawning of entities.
+  - Game rules, scoring, and win/lose conditions.
+- **Client is authoritative** for:
+  - Its own *input* (which keys/buttons are pressed).
+  - Local camera and UI.
+  - Cosmetic / non-gameplay presentation.
+
+### 3.3 Server Loop Pseudocode
+
+```
+while server_running:
+    process_network_inbound()      # read client inputs & RPCs
+    for _ in range(ticks_to_advance):
+        simulate_tick()            # fixed 30 Hz step
+    broadcast_snapshots()          # replicate authoritative state
+    process_network_outbound()     # flush reliable/unreliable channels
+```
+
+The server accumulates real elapsed time and advances the simulation in fixed
+`TICK_DURATION` increments, decoupling simulation from frame rate.
+
+---
+
+## 4. RPC Call Patterns
+
+RPCs are grouped by direction and reliability. All gameplay RPCs are routed
+through the high-level `MultiplayerAPI` with explicit `rpc_id` targeting.
+
+### 4.1 Client → Server (Input & Requests)
+
+| RPC                          | Channel   | Payload                                   | Notes |
+|------------------------------|-----------|-------------------------------------------|-------|
+| `request_move_input`         | unreliable| `{ seq, input_state, timestamp }`         | Batched per tick; drives prediction |
+| `request_interact`           | reliable  | `{ target_id }`                           | Open door, pick up item, use object |
+| `request_attack`             | reliable  | `{ target_id, aim_dir }`                  | Combat action |
+| `request_join`               | reliable  | `{ player_name, profile }`                | Session setup |
+| `request_respawn`            | reliable  | `{}`                                      | After death |
+
+**Design notes:**
+
+- **Input is batched** per client tick and sent with a monotonically increasing
+  `seq` so the server can detect gaps and the client can reconcile.
+- **Interactions are reliable** because they are discrete, must-happen events
+  (opening a door, picking up an item). Losing them would corrupt world state.
+
+### 4.2 Server → Client (State & Events)
+
+| RPC                          | Channel   | Payload                                   | Notes |
+|------------------------------|-----------|-------------------------------------------|-------|
+| `snapshot_state`             | unreliable| `{ tick, entities[], player_states[] }`   | Periodic authoritative state |
+| `spawn_entity`               | reliable  | `{ entity_id, type, transform, props }`   | New entity enters world |
+| `despawn_entity`             | reliable  | `{ entity_id, reason }`                   | Entity removed |
+| `interact_result`            | reliable  | `{ request_seq, success, result }`        | Acknowledges interaction |
+| `damage_event`               | reliable  | `{ target_id, amount, source_id }`        | Combat feedback |
+| `game_event`                 | reliable  | `{ type, payload }`                       | Score, win, round start/end |
+
+### 4.3 Broadcast vs. Targeted
+
+- **Broadcast (all clients):** `snapshot_state`, `spawn_entity`,
+  `despawn_entity`, `game_event`.
+- **Targeted (single client):** `interact_result`, `damage_event` (to affected
+  players), and any player-private data.
+
+---
+
+## 5. Client-Side Prediction & Reconciliation
+
+### 5.1 Prediction
+
+- The client runs a **local copy of the movement simulation** using the same
+  physics constants as the server.
+- When the player provides input, the client:
+  1. Applies the input to its local player immediately.
+  2. Renders the predicted position.
+  3. Sends the input to the server (batched, with `seq`).
+
+### 5.2 Reconciliation
+
+- The server sends authoritative `snapshot_state` at 30 Hz containing the
+  server's tick number and authoritative player positions.
+- The client keeps a **ring buffer of predicted states** keyed by input `seq`.
+- On receiving a snapshot:
+  1. Find the last predicted state that matches the server's tick.
+  2. Compute the **error** between predicted and authoritative position.
+  3. If error exceeds a threshold, **snap or smoothly interpolate** the local
+     player to the authoritative position (error correction).
+  4. Re-simulate any inputs that occurred after the server's tick (rollback).
+
+### 5.3 Interpolation of Remote Entities
+
+- **Local player:** predicted + reconciled (see above).
+- **Remote players / entities:** rendered with **interpolation delay** of
+  `2 × TICK_DURATION` (≈ 66 ms) to smooth out snapshot jitter.
+- The client buffers the last N snapshots and interpolates between them.
+
+### 5.4 Prediction Buffer Sizing
+
+- Buffer size is adaptive based on measured RTT.
+- Default: hold up to `ceil(RTT / TICK_DURATION) + 2` predicted states.
+
+---
+
+## 6. Entity & World State Replication
+
+### 6.1 Entity Model
+
+Every networked entity has:
+
+- A globally unique `entity_id` (server-assigned).
+- An `EntityType` (player, enemy, item, projectile, door, ...).
+- A `Transform` (position, rotation).
+- A typed `props` dictionary of gameplay state (health, state machine, etc.).
+
+### 6.2 Snapshot Format
+
+```
+snapshot_state:
+  tick: uint32
+  entities:
+    - entity_id: uint32
+      type: uint8
+      transform: { x, y, rot }
+      props: { ... }        # delta-encoded where possible
+  player_states:
+    - peer_id: int
+      entity_id: uint32
+      health: int
+      state: uint8
+```
+
+### 6.3 Delta Compression
+
+- Only **changed** entity fields are sent per snapshot (dirty-flag per entity).
+- Static or unchanged entities are omitted from the snapshot.
+- This keeps bandwidth proportional to *activity*, not world size.
+
+---
+
+## 7. Connection & Session Lifecycle
+
+1. **Connect:** Client opens an ENet connection to the server.
+2. **Authenticate / Join:** Client sends `request_join`; server validates and
+   assigns a `peer_id` and spawns the player entity.
+3. **Spawn:** Server broadcasts `spawn_entity` for the new player to all clients.
+4. **Play:** Input → prediction → server simulation → snapshot → reconciliation.
+5. **Disconnect:** Server removes the player entity, broadcasts `despawn_entity`,
+   and cleans up session state.
+
+---
+
+## 8. Security & Anti-Cheat
+
+- **No client-authoritative gameplay values.** Clients only send *inputs* and
+  *requests*; the server computes all outcomes.
+- **Input validation:** Server clamps movement speed, rejects out-of-bounds
+  positions, and validates interaction targets.
+- **Rate limiting:** Per-peer input and RPC rate limits prevent flooding.
+- **Sequence validation:** Gaps or replays in input `seq` are detected and
+  rejected.
+
+---
+
+## 9. Testing & Determinism
+
+- The simulation is a **pure function of (state, inputs, tick)** so it can be
+  unit-tested headlessly.
+- A **replay system** records inputs and can re-simulate to verify server and
+  client produce identical results.
+- Network code is tested with a **mock transport** that can inject latency,
+  jitter, and packet loss.
+
+---
+
+## 10. Open Questions / Future Work
+
+- **Interest management / spatial partitioning:** For large worlds, restrict
+  snapshots to entities near each client (AOI culling).
+- **Server-side physics:** Decide whether to use Godot's physics server on the
+  host or a custom deterministic physics step.
+- **Dedicated server vs. listen server:** The architecture supports both; a
+  dedicated headless server is the target for production.
+- **WebSocket fallback:** Implement the transport abstraction for browser builds.
+
+---
+
+## 11. Summary
+
+| Concern                | Decision                                        |
+|------------------------|-------------------------------------------------|
+| Transport              | ENet (primary), WebSocket (secondary)           |
+| Tick rate              | 30 Hz fixed timestep                            |
+| Authority              | Server-authoritative; client sends input only   |
+| Prediction             | Client-side prediction + reconciliation         |
+| Remote interpolation   | 2-tick interpolation delay                      |
+| Replication            | Delta-compressed snapshots at 30 Hz             |
+| Interaction RPCs       | Reliable channel                                |
+| Movement input         | Unreliable channel, batched with sequence       |

identity_check.txt

@@ -0,0 +1 @@
+testing coder-bot identity