WIP checkpoint: Design world chunk data format and persistence schema

2026-08-17 16:59:48 +00:00
12 changed files with 3 additions and 1314 deletions
@@ -1,2 +0,0 @@
 # Godot 4 editor cache/import directory
 .godot/
@@ -1,462 +0,0 @@
 # Avatar Component System & glTF Attachment Spec
 > **Status:** Proposed
 > **Owner:** Platform team
 > **Related:** Server authority + client prediction, world chunk data format
 ## 1. Overview
 This document specifies the **avatar component system** for **agp-game**, a
 Godot-based multiplayer game. It defines:
 - How an avatar is decomposed into **body parts** and **attachment slots**.
 - How **cosmetic attachments** (clothing, accessories, gear) mount onto the
  base body.
 - The **glTF/GLB format requirements** that all avatar assets must satisfy so
  they can be loaded, skinned, and networked consistently.
 The goal is a **modular, data-driven avatar pipeline**: a single base body rig
 plus swappable attachments, all authored in glTF and consumed by a shared Godot
 runtime. This enables player customization, cosmetic monetization, and
 server-authoritative validation of what a player is wearing.
 ### 1.1 Design Goals
 - **Modularity:** Body parts and attachments are independent assets that can be
  combined at runtime without re-exporting.
 - **Consistency:** A single, well-defined skeleton and slot convention so any
  attachment fits any base body.
 - **Networkability:** The avatar's composition is expressed as a compact,
  serializable **loadout** that the server can validate and replicate.
 - **Performance:** Attachments are skinned to the same skeleton and share
  materials where possible to minimize draw calls and skinning cost.
 - **Tooling-friendly:** Assets are authored in standard glTF 2.0 and validated
  by a build-time checker.
 ---
 ## 2. Avatar Decomposition
 ### 2.1 The Base Body
 Every avatar is built on a **base body** — a single glTF asset containing:
 - A **skeleton** (the canonical rig, see §3).
 - A **base mesh** for the skin/body (head, torso, arms, legs).
 - **Attachment points** (empty nodes) that define where accessories mount.
 The base body is the only asset that carries the skeleton. Attachments reference
 the skeleton by **bone name** and are skinned to it; they never carry their own
 rig.
 ### 2.2 Body Parts vs. Attachments
 Two distinct concepts:
 | Concept        | Definition                                                              | Example                          |
 |----------------|-------------------------------------------------------------------------|----------------------------------|
 | **Body part**  | A mesh that replaces part of the base body's skin (e.g., a different head, a tail, wings). | Alternate head, cybernetic arm |
 | **Attachment** | A mesh that mounts *on top of* the body without replacing it (clothing, accessories). | Shirt, hat, glasses, backpack |
 The distinction matters for **slot exclusivity** and **layering**:
 - **Body parts** are *exclusive* per slot — only one head can be equipped.
 - **Attachments** are *layered* — a hat and glasses can coexist, and both sit
  above the head mesh.
 ---
 ## 3. Skeleton & Slot Convention
 ### 3.1 Canonical Skeleton
 All avatars share a **canonical skeleton** with a fixed set of bone names. This
 is the contract that lets any attachment fit any body. The skeleton follows a
 humanoid convention (Godot's `Humanoid` profile / glTF VRM-style naming).
 Required bones (subset of the full rig):
 ```
 Root
 ├── Hips
 │   ├── Spine
 │   │   ├── Chest
 │   │   │   ├── Neck
 │   │   │   │   └── Head
 │   │   │   │       ├── HeadTop          # hat / hair mount
 │   │   │   │       ├── Jaw              # face accessories
 │   │   │   │       └── LeftEye / RightEye
 │   │   │   ├── LeftShoulder
 │   │   │   │   └── LeftUpperArm
 │   │   │   │       └── LeftLowerArm
 │   │   │   │           └── LeftHand
 │   │   │   └── RightShoulder
 │   │   │       └── RightUpperArm
 │   │   │           └── RightLowerArm
 │   │   │               └── RightHand
 │   │   └── (Chest children for torso attachments)
 │   ├── LeftUpperLeg
 │   │   └── LeftLowerLeg
 │   │       └── LeftFoot
 │   └── RightUpperLeg
 │       └── RightLowerLeg
 │           └── RightFoot
 ```
 **Rules:**
 - Bone names are **case-sensitive** and must match exactly.
 - The skeleton is **T-pose** at rest for consistent skinning.
 - Attachments must be skinned to **at least** the bones they deform; static
  accessories may be parented to a single bone (e.g., a hat parented to `Head`).
 ### 3.2 Attachment Slots
 Slots are the **logical mount points** for body parts and attachments. Each slot
 maps to one or more bones and defines what can be equipped there.
 | Slot ID        | Category     | Mount bone(s)      | Exclusivity | Example assets                |
 |----------------|--------------|--------------------|-------------|-------------------------------|
 | `head`         | body part    | `Head`             | exclusive   | alternate head, face          |
 | `hair`         | attachment   | `HeadTop`          | exclusive   | hairstyles, hats              |
 | `face`         | attachment   | `Jaw`              | exclusive   | glasses, masks, beards        |
 | `torso`        | body part    | `Chest`            | exclusive   | alternate torso               |
 | `chest`        | attachment   | `Chest`            | exclusive   | shirts, armor, chest gear     |
 | `back`         | attachment   | `Chest` (back)     | exclusive   | backpacks, wings, capes       |
 | `left_arm`     | body part    | `LeftUpperArm`     | exclusive   | alternate arm                 |
 | `right_arm`    | body part    | `RightUpperArm`    | exclusive   | alternate arm                 |
 | `left_hand`    | attachment   | `LeftHand`         | exclusive   | gloves, weapons (held)        |
 | `right_hand`   | attachment   | `RightHand`        | exclusive   | gloves, weapons (held)        |
 | `legs`         | body part    | `Hips`             | exclusive   | alternate legs                |
 | `pants`        | attachment   | `Hips`             | exclusive   | pants, skirts                 |
 | `left_foot`    | attachment   | `LeftFoot`         | exclusive   | shoes                         |
 | `right_foot`   | attachment   | `RightFoot`        | exclusive   | shoes                         |
 | `accessory`    | attachment   | `Root` (free)      | multiple    | belts, jewelry, floating items|
 **Slot semantics:**
 - **`exclusive`** slots allow at most one equipped item at a time.
 - The **`accessory`** slot is *multi-slot* — multiple accessories may be equipped
  simultaneously (bounded by a configurable limit, e.g., 8).
 - **Body-part slots** (`head`, `torso`, `legs`, `left_arm`, `right_arm`) replace
  the corresponding base mesh. When a body part is equipped, the base mesh for
  that region is hidden.
 - **Attachment slots** layer on top of the base mesh and never hide it.
 ### 3.3 Slot → Bone Mapping
 Each slot declares a **primary mount bone** and an optional **secondary bone
 list** for skinning. The runtime uses this to:
 1. Parent static accessories to the mount bone.
 2. Skin skinned attachments to the union of the slot's bones.
 ---
 ## 4. glTF/GLB Format Requirements
 All avatar assets (base bodies, body parts, attachments) are distributed as
 **glTF 2.0** (`.gltf` + external buffers/textures) or **GLB** (`.glb`, binary
 container). GLB is the preferred distribution format for runtime loading.
 ### 4.1 Required Conventions
 | Concern            | Requirement                                                                 |
 |--------------------|------------------------------------------------------------------------------|
 | **Format**         | glTF 2.0 (`.gltf` or `.glb`). GLB preferred for runtime.                     |
 | **Coordinate system** | glTF standard: **+Y up, +Z forward, right-handed**. Godot converts to its own convention on import. |
 | **Units**          | Meters. Avatar height ~1.8 m at the `Root` bone.                              |
 | **Skeleton**       | Single skeleton per asset; bone names per §3.1.                              |
 | **Skinning**       | `skins` + `nodes` with `JOINTS_0` / `WEIGHTS_0` accessors.                    |
 | **Pose**           | T-pose at rest.                                                              |
 | **Materials**      | PBR metallic-roughness. Use `KHR_materials_unlit` for emissive/UI-only items. |
 | **Textures**       | Max 2048×2048; power-of-two preferred. Use `KHR_texture_basisu` (BasisU) for runtime. |
 | **Animation**      | Optional. If present, must not rename or remove canonical bones.             |
 ### 4.2 Asset Metadata (extras)
 Each asset **must** declare its slot and identity in the glTF `asset.extras`
 object. This is the machine-readable contract consumed by the build pipeline and
 runtime.
 ```json
 {
  "asset": {
    "version": "2.0",
    "extras": {
      "agp": {
        "type": "attachment",          // "base_body" | "body_part" | "attachment"
        "slot": "chest",               // slot ID from §3.2
        "id": "shirt_bandit_01",       // globally unique asset id
        "display_name": "Bandit Shirt",
        "version": "1.0.0",
        "mount_bone": "Chest",         // primary mount bone
        "skin_bones": ["Chest", "Spine", "LeftUpperArm", "RightUpperArm"],
        "exclusive": true,             // matches slot exclusivity
        "tags": ["cloth", "common"],
        "author": "platform-team"
      }
    }
  }
 }
 ```
 **Validation rules for `extras.agp`:**
 - `type` must be one of `base_body`, `body_part`, `attachment`.
 - `slot` must be a known slot ID (§3.2).
 - `mount_bone` must exist in the canonical skeleton.
 - `skin_bones` must all exist in the canonical skeleton.
 - `exclusive` must match the slot's declared exclusivity.
 - `id` must be unique across the asset catalog.
 ### 4.3 Node Naming Convention
 To make assets self-describing and mergeable, nodes follow a convention:
 - **Base body:** the mesh node is named `Body`; the skeleton root is `Root`.
 - **Body part:** the mesh node is named `<SlotID>_Mesh` (e.g., `head_Mesh`).
 - **Attachment:** the mesh node is named `<SlotID>_<AssetID>` (e.g.,
  `chest_shirt_bandit_01`).
 - **Attachment points** (empty nodes) on the base body are named
  `attach_<slot>` (e.g., `attach_head`, `attach_left_hand`).
 ### 4.4 Material & Texture Requirements
 - All materials use the **metallic-roughness** PBR model.
 - Textures are embedded in the GLB or referenced as external files; external
  references must be relative paths within the asset package.
 - **Color customization** is supported via a `baseColorFactor` tint applied at
  runtime (multiplied over the albedo). Assets should use a neutral albedo
  (white/gray) where tinting is intended.
 - **Masked/transparent** materials must set the correct alpha mode
  (`MASK` or `BLEND`) and `alphaCutoff`.
 ### 4.5 Skeleton Merging at Runtime
 When an attachment is loaded, the runtime **merges** it onto the base body:
 1. Load the base body (skeleton + base meshes).
 2. Load each equipped attachment.
 3. For each attachment, **re-target its skin** to the base body's skeleton by
   bone name (no re-export needed).
 4. Parent static accessories to their `mount_bone`.
 5. Hide base meshes for any equipped body-part slots.
 6. Apply material tints and merge into the render tree.
 The merge is **name-based** — bone names must match exactly (§3.1). This is the
 core reason for the strict naming contract.
 ---
 ## 5. Loadout Model (Network & Persistence)
 The avatar's composition is serialized as a **loadout** — a compact, ordered
 list of equipped asset IDs. This is what the server validates, persists, and
 replicates.
 ### 5.1 Loadout JSON
 ```json
 {
  "base_body": "base_human_male_01",
  "slots": {
    "head":   "head_cyber_01",
    "hair":   "hair_mohawk_01",
    "face":   null,
    "torso":  null,
    "chest":  "chest_bandit_01",
    "back":   "backpack_01",
    "left_arm":  null,
    "right_arm": null,
    "left_hand": "glove_leather_01",
    "right_hand": "glove_leather_01",
    "legs":   null,
    "pants":  "pants_cargo_01",
    "left_foot":  "shoe_boot_01",
    "right_foot": "shoe_boot_01",
    "accessory": ["belt_01", "necklace_01"]
  }
 }
 ```
 **Rules:**
 - `base_body` is required and must reference a valid `base_body` asset.
 - Each exclusive slot holds **at most one** asset id (or `null`).
 - `accessory` is an array (0..N, bounded).
 - The server validates that every id exists in the catalog and that slot
  exclusivity is respected.
 ### 5.2 Network Replication
 The loadout is replicated as part of the player's spawn/state data:
 ```
 spawn_entity:
  entity_id: uint32
  type: player
  transform: { x, y, rot }
  props:
    loadout_hash: uint32      # hash of the loadout for change detection
    loadout: { ... }          # full loadout on spawn / on change
 ```
 - The **full loadout** is sent on spawn and whenever it changes (reliable).
 - A **`loadout_hash`** lets clients skip re-resolving assets if unchanged.
 - The server is the **authority** on the loadout; clients send *requests* to
  change equipment, and the server validates and broadcasts the result.
 ### 5.3 Server-Side Validation
 The server rejects a loadout if:
 - `base_body` is missing or unknown.
 - Any slot references an unknown asset id.
 - An exclusive slot has more than one item.
 - An asset's declared `slot` does not match the slot it is placed in.
 - The accessory list exceeds the configured limit.
 - The asset is not owned/unlocked by the player (for gated cosmetics).
 ---
 ## 6. Godot Runtime Architecture
 ### 6.1 Node Structure
 ```
 Avatar (Node3D)
 ├── Skeleton3D            # canonical skeleton (from base body)
 ├── BodyMeshes            # base body meshes (skinned to Skeleton3D)
 │   ├── head_Mesh
 │   ├── torso_Mesh
 │   └── ...
 ├── Attachments           # equipped attachments
 │   ├── chest_shirt_bandit_01
 │   ├── hair_mohawk_01
 │   └── ...
 └── AttachmentPoints      # empty nodes for dynamic mounting
    ├── attach_head
    ├── attach_left_hand
    └── ...
 ```
 ### 6.2 Core Classes
 | Class                    | Responsibility                                              |
 |--------------------------|-------------------------------------------------------------|
 | `AvatarSystem`           | Loads base body + attachments, resolves loadouts, owns the avatar node. |
 | `AvatarLoader`           | glTF/GLB import, skeleton merge, skin re-targeting.          |
 | `AvatarSlotRegistry`     | Static registry of slot definitions (id, bones, exclusivity).|
 | `AvatarLoadout`          | Serializable loadout model + validation.                    |
 | `AvatarCatalog`          | Asset catalog (id → asset metadata + resource path).         |
 | `AvatarVisualizer`       | Builds the render tree from a loadout.                      |
 ### 6.3 Loading Pipeline
 ```
 loadout JSON
   │
   ▼
 AvatarCatalog.resolve(loadout)   # id → asset metadata + GLB path
   │
   ▼
 AvatarLoader.load_base_body()    # import GLB, extract skeleton + base meshes
   │
   ▼
 for each equipped slot:
   AvatarLoader.load_attachment()# import GLB, re-target skin to skeleton
   │
   ▼
 AvatarVisualizer.assemble()      # parent, hide replaced parts, apply tints
   │
   ▼
 Avatar node ready for render
 ```
 ### 6.4 Performance Considerations
 - **Shared skeleton:** All meshes skin to one `Skeleton3D`, so skinning is
  computed once per frame.
 - **Material batching:** Attachments that share a material are merged into a
  single mesh where possible (static accessories).
 - **LOD:** Optional LOD variants per asset; the runtime selects based on
  distance.
 - **Caching:** Resolved loadouts and imported GLB resources are cached by
  `AvatarCatalog` to avoid re-importing on respawn or re-join.
 ---
 ## 7. Asset Pipeline & Validation
 ### 7.1 Build-Time Validation
 A build-time checker validates every asset before it enters the catalog:
 1. **Format check:** valid glTF 2.0 / GLB.
 2. **Metadata check:** `extras.agp` present and valid (§4.2).
 3. **Skeleton check:** all `skin_bones` exist in the canonical skeleton.
 4. **Slot check:** `slot` is known and `exclusive` matches.
 5. **Mesh check:** meshes are skinned (or static accessories parented to a bone).
 6. **Texture check:** sizes, formats, and alpha modes are valid.
 7. **Uniqueness check:** `id` is unique.
 ### 7.2 Catalog Manifest
 The catalog is a JSON manifest mapping asset ids to metadata and resource paths:
 ```json
 {
  "assets": {
    "base_human_male_01": {
      "type": "base_body",
      "path": "res://assets/avatars/base_human_male_01.glb",
      "version": "1.0.0"
    },
    "chest_bandit_01": {
      "type": "attachment",
      "slot": "chest",
      "path": "res://assets/avatars/chest_bandit_01.glb",
      "version": "1.0.0"
    }
  }
 }
 ```
 ---
 ## 8. Security & Anti-Cheat
 - **Server-authoritative loadouts:** Clients only *request* equipment changes;
  the server validates against the catalog and the player's owned items.
 - **No client asset injection:** Clients cannot send arbitrary GLB data; they
  reference catalog ids only.
 - **Rate limiting:** Equipment-change requests are rate-limited per peer.
 - **Hash verification:** The `loadout_hash` lets the server detect tampered or
  stale loadout state.
 ---
 ## 9. Open Questions / Future Work
 - **Morph targets / blendshapes:** Support for facial expressions and body
  morphs (e.g., height, muscle) via glTF morph targets.
 - **Physics attachments:** Cloth simulation for capes/skirts (Godot cloth).
 - **Dynamic tinting UI:** A color-picker that writes `baseColorFactor` tints.
 - **VRM compatibility:** Consider supporting VRM (a glTF extension for
  humanoid avatars) as an import source.
 - **Attachment LOD streaming:** Streaming high-res attachments on demand.
 ---
 ## 10. Summary
 | Concern                | Decision                                              |
 |------------------------|-------------------------------------------------------|
 | Format                 | glTF 2.0 / GLB (GLB preferred for runtime)            |
 | Skeleton               | Single canonical humanoid skeleton, name-based merge  |
 | Slots                  | Fixed slot registry; exclusive body parts + layered attachments |
 | Loadout                | Compact JSON; server-authoritative and validated      |
 | Replication            | Full loadout on spawn/change + `loadout_hash`         |
 | Runtime                | Godot `Skeleton3D` + name-based skin re-targeting     |
 | Validation             | Build-time asset checker + runtime catalog validation |
@@ -1,426 +0,0 @@
 # 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.
@@ -1,286 +0,0 @@
 # 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       |
@@ -252,11 +252,6 @@ logical model serialized directly.
 }
 ```
 > **Note on the example checksum:** The value shown above is illustrative only.
 > In practice the `checksum` field is the SHA-256 of the canonical binary
 > payload body (see §3.6.3), not of the JSON text. The value here is a
 > placeholder for documentation purposes.
 ### 3.6 Binary Encoding
 The binary encoding is the **runtime and network** representation. It is compact
@@ -486,16 +481,6 @@ CREATE INDEX idx_chunk_objects_type ON chunk_objects(type);
 CREATE INDEX idx_chunk_objects_asset ON chunk_objects(asset_id);
 ```
 **Sync mechanism:** `chunk_objects` is maintained **explicitly by the write
 path** — it is not a SQL trigger. Whenever `put_chunk` (or `delete_chunk`)
 commits a chunk, the service layer performs a **delete-and-reinsert** of that
 chunk's object rows in the same transaction: it deletes all rows for
 `chunk_key`, then inserts fresh rows parsed from the new payload. This keeps the
 index transactionally consistent with the payload and avoids the complexity and
 fragility of SQL triggers over a binary BLOB. Because the index is derived, it
 can always be rebuilt from `chunks.payload` if it ever drifts (a `rebuild_index`
 utility is provided for this).
 ### 4.6 `content_flags`
 Persists the aggregated moderation flags per chunk (and optionally per object).
@@ -505,7 +490,7 @@ payloads.
 ```sql
 CREATE TABLE content_flags (
    chunk_key   TEXT NOT NULL REFERENCES chunks(key) ON DELETE CASCADE,
-    object_id   TEXT NOT NULL DEFAULT '',  -- '' = chunk-level flag (sentinel)
+    object_id   TEXT,                      -- NULL = chunk-level flag
    violence    INTEGER NOT NULL DEFAULT 0,
    sexual      INTEGER NOT NULL DEFAULT 0,
    language    INTEGER NOT NULL DEFAULT 0,
@@ -523,16 +508,6 @@ CREATE INDEX idx_content_flags_mature ON content_flags(mature);
 Severity is stored as `0=none, 1=mild, 2=moderate, 3=severe`.
 **Chunk-level vs. object-level flags:** Chunk-level flags use the **sentinel
 value `''` (empty string)** in `object_id` rather than `NULL`. This is
 deliberate: in SQLite, `NULL` values in a composite primary key are **not**
 unique-constrained, so two rows with the same `chunk_key` and `object_id = NULL`
 could be inserted accidentally. Using `''` as the sentinel means the composite
 `PRIMARY KEY (chunk_key, object_id)` enforces that there is **exactly one**
 chunk-level flag row per chunk. Object-level flags use the object's actual `id`
 (which is never empty). The application layer treats `object_id = ''` as
 "chunk-level" and any non-empty value as "object-level".
 ### 4.7 `revisions`
 An append-only audit log of chunk writes. Enables rollback, auditing, and
@@ -541,31 +516,16 @@ replication of changes.
 ```sql
 CREATE TABLE revisions (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    chunk_key   TEXT NOT NULL,             -- NOT a FK: survives chunk deletion
+    chunk_key   TEXT NOT NULL REFERENCES chunks(key) ON DELETE CASCADE,
    revision    INTEGER NOT NULL,
    actor       TEXT NOT NULL,             -- user / agent id
    action      TEXT NOT NULL,             -- 'create' | 'update' | 'delete'
-    checksum    TEXT NOT NULL,             -- SHA-256 of payload
+    checksum    TEXT NOT NULL,
    payload     BLOB,                      -- full binary payload at this revision
    created_at  TEXT NOT NULL
 );
 CREATE INDEX idx_revisions_chunk ON revisions(chunk_key);
 ```
 **Rollback support:** The `payload` BLOB stores the **full binary chunk payload**
 at each revision. This is what makes rollback possible: to restore a chunk to a
 previous revision, the server reads the `payload` of the target revision and
 writes it back to `chunks.payload` (incrementing `revision` and appending a new
 `revisions` row). Without the payload, only the checksum would be available,
 which is insufficient to reconstruct the chunk.
 **Audit trail preservation:** `chunk_key` is **not** a foreign key to `chunks`.
 This means deleting a chunk does **not** cascade-delete its revision history —
 the audit trail is preserved even after a chunk is removed. (The `chunk_key`
 string is still stored so the history can be correlated to a chunk that existed
 at that time.) If a chunk is later recreated with the same key, its history is
 still intact.
 ### 4.8 Schema Versioning & Migrations
 The database carries a schema version in a `meta` table:
@@ -606,8 +566,6 @@ class WorldStore:
                    bounds: Bounds | None = None) -> list[str]: ...
    def get_chunk_flags(self, key: str) -> ContentFlags: ...
    def flush_dirty(self) -> int: ...
    def rollback_chunk(self, key: str, revision: int, actor: str) -> Chunk: ...
    def rebuild_index(self, chunk_key: str | None = None) -> int: ...
    def migrate(self) -> None: ...
 ```
@@ -670,18 +628,6 @@ memory and flushes them to SQLite in batches:
 This keeps the hot path (in-memory chunk access) fast while guaranteeing
 durability at shutdown and on a configurable interval.
 **Recovery after unclean shutdown:** The `dirty` column in the `chunks` table
 exists specifically to support recovery if the process crashes before a flush
 completes. On startup, the server scans for rows where `dirty = 1` and treats
 them as **unflushed in-memory state that was lost** — it re-reads the last
 persisted payload from `chunks.payload` (the last durable state) and clears the
 `dirty` flag. In other words, `dirty = 1` at startup means "the last write was
 not durable; discard the in-memory delta and fall back to the persisted
 payload." This guarantees that the on-disk state is always a consistent,
 previously-committed snapshot, never a partially-written chunk. (The in-memory
 dirty set is authoritative during normal operation; the `dirty` column is only a
 recovery marker.)
 ### 5.6 Streaming & Caching
 - The server streams only the chunks a client needs (those within the client's
@@ -1,24 +0,0 @@
 ; Engine configuration file.
 ; It's best edited using the editor UI and not directly,
 ; but it can also be edited by hand.
 config_version=5
 [application]
 config/name="AGP-Game"
 run/main_scene="res://scenes/main_menu.tscn"
 config/features=PackedStringArray("4.6.2")
 [autoload]
 [display]
 window/size/viewport_width=1920
 window/size/viewport_height=1080
 window/stretch/mode="canvas_items"
 [rendering]
 renderer/rendering_method="gl_compatibility"
 renderer/rendering_method.mobile="gl_compatibility"
@@ -1,43 +0,0 @@
 [gd_scene load_steps=2 format=3]
 [ext_resource type="Script" path="res://scripts/main_menu.gd" id="1_main"]
 [node name="MainMenu" type="Control"]
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
 grow_horizontal = 2
 grow_vertical = 2
 script = ExtResource("1_main")
 [node name="CenterContainer" type="CenterContainer" parent="."]
 layout_mode = 3
 anchors_preset = 15
 anchor_right = 1.0
 anchor_bottom = 1.0
 grow_horizontal = 2
 grow_vertical = 2
 [node name="VBoxContainer" type="VBoxContainer" parent="CenterContainer"]
 layout_mode = 1
 theme_override_constants/separation = 16
 size_flags_horizontal = 4
 [node name="TitleLabel" type="Label" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "AGP Game"
 horizontal_alignment = 1
 theme_override_font_sizes/font_size = 72
 [node name="PlayButton" type="Button" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "Play"
 size_flags_horizontal = 4
 [node name="QuitButton" type="Button" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "Quit"
 size_flags_horizontal = 4
 [connection signal="pressed" from="CenterContainer/VBoxContainer/PlayButton" to="." method="_on_play_button_pressed"]
 [connection signal="pressed" from="CenterContainer/VBoxContainer/QuitButton" to="." method="_on_quit_button_pressed"]
@@ -1,14 +0,0 @@
 extends Control
 func _ready():
 	pass
 func _on_play_button_pressed():
 	# No gameplay scene exists yet — wire this to the real scene once one lands.
 	print("Play pressed — no gameplay scene yet")
 func _on_quit_button_pressed():
 	get_tree().quit()
		`@@ -1,2 +0,0 @@`
			`# Godot 4 editor cache/import directory`
			`.godot/`