Initial Commit

openspec/archive/2026-05-05-network-plugin-session/proposal.md

@@ -0,0 +1,100 @@
+# OpenSpec Change: network-plugin-session
+
+- **Change ID**: network-plugin-session
+- **Package**: `@suaveplan/network-plugin-session` (new)
+- **Status**: PROPOSED
+- **Type**: new-package
+- **Date**: 2026-04-29
+
+## Why
+
+The tiered mesh network provides peer-to-peer connectivity, but it has no concept of **logical player groupings** — sessions. A session is a scope within which peers see each other, exchange state, and interact. Sessions can be nested: a parent session (free-roam open world) contains child sessions (missions, heists, races), which may contain further nested sessions (mission phases, instanced interiors). This is the pattern used by GTA V Online, Destiny, The Division, and many other multiplayer games.
+
+Without session management, every peer in the mesh receives every message from every other peer. Sessions provide:
+
+- **Visibility isolation** — peers only receive state from peers in their session branch
+- **Nested hierarchies** — missions inside free-roam, phases inside missions
+- **Session-scoped host nomination** — each session elects its own host for state authority
+- **Capacity enforcement** — hard caps per session type (free-roam: 30, mission: 4, race: 8)
+- **Graceful transitions** — joining/leaving sessions without dropping mesh connection
+- **Parent state inheritance** — sub-sessions can optionally receive read-only state from parent (weather, time, world events)
+
+## What changes
+
+- **ADDED**: `SessionPlugin` class implementing `NetworkPlugin`.
+- **ADDED**: `SessionManager` — maintains the session tree, handles create/destroy/join/leave/move operations.
+- **ADDED**: `Session` — represents one session node in the tree: `id`, `parentId`, `hostId`, `peers[]`, `capacity`, `rules`, `state`.
+- **ADDED**: `SessionRouter` — intercepts outgoing messages and filters delivery to peers in the target session scope only.
+- **ADDED**: `SessionHostElection` — per-session host nomination, independent of mesh Tier 0 host. A peer can be host of multiple sessions.
+- **ADDED**: `SessionTransitionManager` — handles join/leave/move with state snapshot transfer and forwarding tunnel.
+- **ADDED**: `ParentStateBridge` — optionally replicates read-only parent state into child sessions (e.g., world time, weather).
+- **ADDED**: `SessionCapacityEnforcer` — rejects joins when capacity exceeded; can trigger session split.
+- **ADDED**: `SessionRegistry` — tracks all known sessions in the mesh, their hosts, and their peer counts.
+- **ADDED**: `NETWORK_SESSION_CODES` — frozen error registry.
+
+## Session hierarchy model
+
+```text
+Mesh (all connected peers)
+└── Session: "freeroam-01" (capacity: 30, host: Peer-A)
+    ├── Peer-A (host)
+    ├── Peer-B
+    ├── Peer-C
+    ├── Peer-D
+    └── Session: "mission-heist-01" (capacity: 4, host: Peer-B)
+        ├── Peer-B (host)
+        ├── Peer-C
+        ├── Peer-D
+        └── Session: "phase-drill" (capacity: 2, host: Peer-C)
+            ├── Peer-C (host)
+            └── Peer-D
+```
+
+**Rules**:
+
+- A peer can be in **exactly one leaf session** at a time.
+- A peer implicitly belongs to all ancestor sessions (for parent state bridge).
+- Messages sent within a session are delivered **only to peers in that session or its descendants**.
+- Messages sent "upward" (to parent) are delivered to the parent session host only.
+- Each session has its own host, elected independently via the same governance scoring.
+
+## Out of scope
+
+- Game-specific state replication (entities, physics, AI) → gaming packages (`gaming-ecs`, `gaming-r3f-networking`).
+- Matchmaking (finding which session to join) → `gaming-lobby`, `gaming-matchmaking`.
+- Party system (persistent friend group) → `gaming-party`.
+- Persistence (saving session state to disk) → future `network-plugin-session-persistence`.
+
+## Source mapping
+
+This change derives from the session concepts in `../suaveplan/enterprise/game-server.md` (§sessions) and `../suaveplan/enterprise/lobby.md`, but is a **new design** — suaveplan has no equivalent network-layer session plugin.
+
+| Requirement | Source lines | Notes |
+|---|---|---|
+| Session management | `game-server/README.md` §Sessions | reworded; suaveplan had session stubs in game-server, not network layer |
+| Session host | `game-server/README.md` §Sessions | reworded; host per session, not per mesh |
+| Capacity limits | `lobby/README.md` §Capacity | reworded; per-session, not per-lobby |
+
+### Requirements with no source line
+
+| Requirement | Justification |
+|---|---|
+| Session-scoped message routing | Defensive — prevents free-roam state flooding mission peers |
+| Nested session hierarchies | Required for GTA V-style missions-within-free-roam |
+| Parent state bridge | Required so mission players still see world time/weather |
+| Per-session host election | Required so mission host can be closest to mission peers, not free-roam host |
+| Session transition with snapshot | Required for seamless join/leave without mesh disconnect |
+
+## Verification approach
+
+- `src/session/session.spec-conformance.test.ts` — pins create, destroy, join, leave, move.
+- `src/router/router.spec-conformance.test.ts` — pins message delivery scope, upward routing, parent bridge.
+- `src/election/election.spec-conformance.test.ts` — pins per-session host election, independent of mesh host.
+- `src/transition/transition.spec-conformance.test.ts` — pins join/leave/move with state snapshot.
+- `src/capacity/capacity.spec-conformance.test.ts` — pins capacity enforcement, rejection, split trigger.
+- `src/registry/session-registry.spec-conformance.test.ts` — pins session tree tracking, peer counts.
+- `tests/dep-graph.test.ts` — pins no direct import of webrtc or gaming packages.
+
+## Migration impact
+
+None — additive only.