Docs/ac 0001 v0 governance

.github/copilot-instructions.md

@@ -86,7 +86,7 @@ This repository uses stable Constitution IDs for traceability:
 - Prefer `cargo clippy` with `-D warnings`
 - Tests should reference Constitution IDs in comments when verifying invariants
 
-### Simulation Plane
+### Simulation Core
 - **Determinism is non-negotiable** — see `INV-0001`, `INV-0002`
 - Fixed timestep; no frame-rate-dependent logic
 - Authoritative state transitions only in `crates/sim`

README.md

@@ -14,7 +14,7 @@ Foundation phase. Initial workspace + simulation scaffolding is in place. No gam
 ## What we’re optimizing for
 
 - Deterministic simulation and replay verification
-- Clean authority boundaries (simulation vs client vs control plane)
+- Clean authority boundaries (Simulation Core isolated from Server Edge and Game Client)
 - Transport-independent protocol semantics
 - Testability as a first-class feature
 - Human + agent collaboration within explicit constraints

docs/adr/0001-authoritative-multiplayer-architecture.md

@@ -0,0 +1,90 @@
+# ADR 0001: Authoritative Multiplayer Architecture
+
+## Status
+Accepted
+
+## Type
+Technical
+
+## Context
+Flowstate is a competitive multiplayer game that prioritizes correctness, testability, and long-term preservability. To achieve these goals, the system must separate concerns cleanly: game logic must be isolated from networking/session management and from presentation (rendering, input, UI). Without this separation, the simulation becomes entangled with I/O, making determinism impossible to guarantee and testing prohibitively expensive.
+
+The architecture must support multiple client types (native, web browser) and enable replay verification, which requires the simulation to be pure and side-effect-free.
+
+## Decision
+Flowstate adopts an **Authoritative Multiplayer Architecture** with strict separation of concerns and clear authority boundaries:
+
+### Runtime Components
+
+**1. Game Client** — The player runtime.
+- Owns: rendering, input capture, UI, interpolation, and (future) prediction/reconciliation.
+- MUST NOT authoritatively decide game-outcome-affecting state.
+
+**2. Matchmaker** — The sole system a Game Client contacts to create/find/join a match.
+- Owns: matchmaking, lobbies/queues (if any), match creation, and assignment of players to a specific Game Server Instance.
+- Returns connection information/credentials for a Game Server Instance.
+- Optional for LAN/dev scenarios; may not exist in local play.
+
+**3. Game Server Instance** — One running authoritative match runtime (process/container).
+- Owns the authoritative game simulation for exactly one match lifecycle.
+- Contains exactly two named subcomponents:
+
+  **3a. Server Edge** — The networking and session boundary.
+  - Owns: all networking, transports, session lifecycle, input validation.
+  - Performs all I/O.
+  - Exchanges explicit, typed, tick-indexed messages with the Simulation Core.
+
+  **3b. Simulation Core** — The deterministic game logic.
+  - Deterministic, fixed-timestep, replayable game rules: physics, movement, abilities, combat resolution.
+  - Performs NO I/O, networking, rendering, engine calls, or OS/system calls.
+  - Replayable purely from recorded inputs.
+
+### Hard Boundaries
+
+- The Simulation Core MUST NOT perform I/O, networking, rendering, or system calls.
+- The Simulation Core MUST be deterministic and replayable from recorded inputs.
+- The Game Client MUST NOT authoritatively decide game-outcome-affecting state.
+- Communication across boundaries is via explicit, typed, tick-indexed message passing only.
+
+## Rationale
+This architecture enables:
+- **Determinism:** Simulation Core has no hidden state from I/O or timing.
+- **Testability:** Simulation Core can be tested without graphics, network, or OS dependencies.
+- **Replayability:** Record inputs, replay simulation, verify identical outcomes.
+- **Multiple clients:** Native, web, headless bots all consume the same simulation.
+- **Preservability:** Core game logic remains runnable decades from now (no platform lock-in).
+- **Clear authority:** Each component has explicit ownership; no ambiguity about who decides what.
+
+**Tradeoffs:**
+- Higher upfront design cost (explicit boundaries require discipline).
+- Cannot use "engine-native" patterns that blur simulation/presentation (e.g., Godot signals from physics to rendering).
+- Requires careful message protocol design between Server Edge and Simulation Core.
+
+## Constraints & References (no prose duplication)
+- Constitution IDs:
+  - INV-0001 (Deterministic Simulation)
+  - INV-0002 (Fixed Timestep)
+  - INV-0004 (Simulation Core Isolation)
+- Canonical Constitution docs:
+  - [docs/constitution.md](../constitution.md) — Product Thesis
+  - [docs/constitution/invariants.md](../constitution/invariants.md)
+- Related ADRs:
+  - ADR-0002 (Deterministic Simulation) — defines properties of Simulation Core
+  - ADR-0003 (Fixed Timestep) — defines stepping model of Simulation Core
+  - ADR-0004 (Server-Authoritative) — defines authority model
+
+## Alternatives Considered
+- **Monolithic engine-integrated architecture** — Use Godot's scene tree and signals for all logic. Rejected: Makes determinism and replay impossible; locks simulation to Godot's lifecycle.
+- **Merge orchestration into server** — Combine matchmaking and simulation into one component. Rejected: Loses separation between orchestration and simulation; makes headless testing harder.
+- **Four-layer (separate Data layer)** — Add explicit persistence layer. Deferred: Can be added later; v0 doesn't require it.
+
+## Implications
+- **Enables:** Deterministic testing, replay verification, multiple client types, long-term preservability.
+- **Constrains:** Simulation Core code cannot directly call Godot APIs, network libraries, or OS functions.
+- **Migration costs:** None (greenfield project).
+- **Contributor impact:** Developers must understand component boundaries and message-passing contracts.
+
+## Follow-ups
+- Define Simulation Core I/O interface (message types for inputs/outputs)
+- Establish testing patterns for Simulation Core-only tests
+- Document component boundaries in repository map and handbook

docs/adr/0002-deterministic-simulation.md

@@ -9,7 +9,7 @@ Technical
 ## Context
 Competitive multiplayer games require verifiable correctness. Players expect consistent outcomes: the same inputs should produce the same results every time. Without determinism, replay verification is impossible, testing becomes unreliable, and subtle bugs can manifest as desync or inconsistent match outcomes across clients.
 
-The Simulation Plane (ADR-0001) is the authoritative source of truth for game state. If the simulation is non-deterministic, there is no "truth"—only probabilistic approximations.
+The Simulation Core (DM-0014, defined in ADR-0001) is the authoritative source of truth for game state. If the simulation is non-deterministic, there is no "truth"—only probabilistic approximations.
 
 ## Decision
 The authoritative simulation MUST be **deterministic**: identical initial state, input sequence, seed, and tuning parameters MUST produce identical outcomes across all runs, platforms, and compiler configurations.
@@ -55,7 +55,7 @@ The authoritative simulation MUST be **deterministic**: identical initial state,
 - Canonical Constitution docs:
   - [docs/constitution/invariants.md](../constitution/invariants.md)
 - Related ADRs:
-  - ADR-0001 (Three-Plane Architecture) — defines Simulation Plane where determinism applies
+  - ADR-0001 (Authoritative Multiplayer Architecture) — defines Simulation Core where determinism applies
   - ADR-0003 (Fixed Timestep) — fixed timestep is a prerequisite for determinism
 
 ## Alternatives Considered

docs/adr/0003-fixed-timestep-simulation.md

@@ -12,7 +12,7 @@ Variable delta time (frame-rate-dependent simulation) causes non-determinism: th
 To achieve determinism (ADR-0002), the simulation must advance in predictable, fixed-size increments independent of frame rate or wall-clock time.
 
 ## Decision
-The Simulation Plane (ADR-0001) MUST advance in **fixed discrete ticks**. Each tick represents a fixed duration of simulated time.
+The Simulation Core (DM-0014, defined in ADR-0001) MUST advance in **fixed discrete ticks**. Each tick represents a fixed duration of simulated time.
 
 **Requirements:**
 - Simulation stepping function: `advance(state, inputs, dt_seconds)` where `dt_seconds` is constant for a match
@@ -56,7 +56,7 @@ The Simulation Plane (ADR-0001) MUST advance in **fixed discrete ticks**. Each t
   - [docs/constitution/invariants.md](../constitution/invariants.md)
   - [docs/constitution/domain-model.md](../constitution/domain-model.md)
 - Related ADRs:
-  - ADR-0001 (Three-Plane Architecture) — defines Simulation Plane where fixed timestep applies
+  - ADR-0001 (Authoritative Multiplayer Architecture) — defines Simulation Core where fixed timestep applies
   - ADR-0002 (Deterministic Simulation) — fixed timestep enables determinism
 
 ## Alternatives Considered

docs/adr/0004-server-authoritative-architecture.md

@@ -9,31 +9,31 @@ Technical
 ## Context
 Competitive multiplayer games require a trusted arbiter to prevent cheating and ensure consistent outcomes. If clients authoritatively decide game-affecting state (e.g., "I hit the target", "I have 1000 resources"), players can modify their clients to cheat, and different clients may disagree on match outcomes.
 
-The Simulation Plane (ADR-0001) is deterministic (ADR-0002), but determinism alone does not prevent cheating—clients could run modified simulations. A single authoritative instance must enforce the rules.
+The Simulation Core (DM-0014, defined in ADR-0001) is deterministic (ADR-0002), but determinism alone does not prevent cheating—clients could run modified simulations. A single authoritative instance must enforce the rules.
 
 ## Decision
 The **server is the single source of truth** for all game-outcome-affecting state. Clients are presentation-only and never authoritatively decide hits, damage, resource changes, or state transitions.
 
 **Server responsibilities:**
-- Run the authoritative Simulation Plane (ADR-0001)
+- Run the authoritative Simulation Core (DM-0014, defined in ADR-0001)
 - Receive client inputs (movement intent, aim direction, action requests)
 - Advance simulation via deterministic stepping (ADR-0002, ADR-0003)
-- Broadcast authoritative state snapshots to clients
+- Broadcast authoritative state snapshots to Game Clients
 - Validate inputs (rate limiting, bounds checking, action legality)
 - Enforce match rules and win conditions
 
-**Client responsibilities:**
+**Game Client responsibilities:**
 - Capture player inputs and send to server
 - Receive authoritative snapshots from server
 - Render game state (interpolate/predict for responsiveness)
 - Provide immediate feedback (cosmetic effects, predicted movement)
 - MUST NOT authoritatively decide: hits, damage, status effects, spawns, despawns, resource changes
 
 **Future ADR: Client Prediction & Reconciliation:**
-- Clients MAY predict local player movement for responsiveness
-- Clients MUST reconcile predicted state when authoritative snapshot arrives
+- Game Clients MAY predict local player movement for responsiveness
+- Game Clients MUST reconcile predicted state when authoritative snapshot arrives
 - Cosmetic effects (muzzle flash, VFX) are allowed but never commit game state
-- (Deferred to post-v0; v0 clients render authoritative snapshots only)
+- (Deferred to post-v0; v0 Game Clients render authoritative snapshots only)
 
 ## Rationale
 **Why server-authoritative:**
@@ -65,7 +65,7 @@ The **server is the single source of truth** for all game-outcome-affecting stat
   - [docs/constitution.md](../constitution.md) — "server-authoritative" is explicit in-scope goal
   - [docs/constitution/scope-non-goals.md](../constitution/scope-non-goals.md)
 - Related ADRs:
-  - ADR-0001 (Three-Plane Architecture) — server runs Simulation Plane, clients run Client Plane
+  - ADR-0001 (Authoritative Multiplayer Architecture) — server runs Simulation Core, Game Clients present state
   - ADR-0002 (Deterministic Simulation) — server simulation is deterministic and replayable
   - ADR-0003 (Fixed Timestep) — server simulation advances in fixed ticks
 
@@ -76,12 +76,12 @@ The **server is the single source of truth** for all game-outcome-affecting stat
 
 ## Implications
 - **Enables:** Cheat resistance, consistent match outcomes, replay verification from server perspective, competitive integrity
-- **Constrains:** Requires server hosting infrastructure, clients cannot play offline (for competitive modes), latency must be masked via prediction
+- **Constrains:** Requires server hosting infrastructure, Game Clients cannot play offline (for competitive modes), latency must be masked via prediction
 - **Migration costs:** None (greenfield project)
-- **Contributor impact:** All simulation changes must consider server authority; clients cannot "decide" outcomes locally
+- **Contributor impact:** All Simulation Core changes must consider server authority; Game Clients cannot "decide" outcomes locally
 
 ## Follow-ups
-- Define client-server message protocol (inputs client→server, snapshots server→client)
+- Define client-server message protocol (inputs Game Client→server, snapshots server→Game Client)
 - Implement input validation at simulation boundary (rate limiting, bounds checking)
-- Document prediction/reconciliation strategy for clients (Future ADR: Client Prediction & Reconciliation)
+- Document prediction/reconciliation strategy for Game Clients (Future ADR: Client Prediction & Reconciliation)
 - Establish server hosting requirements (headless mode, tick rate targets, scalability)

docs/adr/0005-v0-networking-architecture.md

@@ -13,7 +13,7 @@ Flowstate requires client-server networked multiplayer. The goal for v0 is to de
 Key constraints:
 - The simulation MUST be deterministic (INV-0001) and advance in fixed Ticks (INV-0002)
 - The server is authoritative (INV-0003); client inputs are intent, not commands
-- The Simulation Plane MUST NOT perform I/O or networking (INV-0004)
+- The Simulation Core MUST NOT perform I/O or networking (INV-0004)
 - All inputs and outputs MUST carry explicit Tick identifiers (INV-0005)
 - Replay artifacts MUST reproduce authoritative outcomes on the same build/platform (INV-0006)
 
@@ -30,7 +30,7 @@ We adopt a **two-layer networking architecture**:
 
 ### A. Semantic Contract (Transport-Agnostic)
 
-The I/O Boundary (DM-0011) mediates communication between the Control Plane and Simulation Plane via **tick-indexed messages** on **logical Channels** (DM-0009) with defined semantics:
+The Server Edge (DM-0011) mediates communication between Game Clients (DM-0015) and the Simulation Core (DM-0014) via **tick-indexed messages** on **logical Channels** (DM-0009) with defined semantics:
 
 - **Realtime Channel:** Unreliable + sequenced (discard older packets)
   - Uses: Snapshots (DM-0007), InputCmds (DM-0006)
@@ -83,12 +83,12 @@ v0 guarantees determinism **within the same build and platform**. Cross-platform
 ## Constraints & References
 
 - Constitution IDs:
-  - INV-0001 (Deterministic Simulation), INV-0002 (Fixed Timestep), INV-0003 (Authoritative Simulation), INV-0004 (Simulation Plane Isolation), INV-0005 (Tick-Indexed I/O Contract), INV-0006 (Replay Verifiability)
+  - INV-0001 (Deterministic Simulation), INV-0002 (Fixed Timestep), INV-0003 (Authoritative Simulation), INV-0004 (Simulation Core Isolation), INV-0005 (Tick-Indexed I/O Contract), INV-0006 (Replay Verifiability)
   - DM-0001 (Tick), DM-0006 (InputCmd), DM-0007 (Snapshot), DM-0008 (Session), DM-0009 (Channel), DM-0010 (Match)
   - AC-0001 (v0 Two-Client Multiplayer Slice)
   - KC-0001 (Plane Boundary Violation), KC-0002 (Replay Verification Blocker)
 - Related ADRs:
-  - ADR-0001 (Three-Plane Architecture)
+  - ADR-0001 (Authoritative Multiplayer Architecture)
   - ADR-0002 (Deterministic Simulation)
   - ADR-0003 (Fixed Timestep Simulation)
   - ADR-0004 (Server Authoritative Architecture)