RUDPClient/openspec/specs/multi-session-lifecycle/spec.md

multi-session-lifecycle Specification

Purpose

Define the shared orchestration model for hosts that manage multiple concurrent network sessions while preserving the existing per-session lifecycle vocabulary.

Requirements

Requirement: Multi-session hosts manage per-peer lifecycle state

The shared networking core SHALL provide a multi-session lifecycle coordinator for hosts that manage multiple concurrent remote peers. The coordinator MUST maintain distinct per-session lifecycle state keyed by remote identity rather than collapsing all peers into one runtime-level state.

Scenario: Server tracks two peers independently

• WHEN a server host accepts transport activity from two different remote peers
• THEN the multi-session coordinator creates or resolves two distinct managed sessions
• THEN lifecycle changes for one peer do not overwrite or hide the state of the other peer

Requirement: Multi-session hosts can observe and evaluate each managed session

The multi-session lifecycle coordinator SHALL expose per-session lookup or enumeration and MUST evaluate timeout, heartbeat, login, reconnect, authoritative movement tick rules, and authoritative combat input rules for each managed session independently using the shared session lifecycle vocabulary. Server-side stale-input acceptance, shoot validation, and authoritative gameplay tracking MUST remain scoped to the peer that produced the traffic.

Scenario: Timeout affects only one managed session

• WHEN one managed session stops receiving liveness updates while another session continues receiving heartbeat or message activity
• THEN the timed-out session transitions through timeout or reconnect states according to policy
• THEN the active session remains in its current healthy state

Scenario: Host can inspect current managed sessions

• WHEN server-side code needs to inspect the current connection state of connected peers
• THEN it can look up or enumerate managed sessions through the multi-session coordinator
• THEN each entry exposes the shared session lifecycle state for that specific peer

Scenario: Movement tick filtering remains peer-scoped

• WHEN two managed peers send MoveInput traffic with different tick progress or ordering
• THEN stale-input acceptance is evaluated independently for each managed peer
• THEN one peer's late or advanced movement input does not overwrite or suppress the other's authoritative movement state

Scenario: Shoot validation remains peer-scoped

• WHEN two managed peers send ShootInput traffic with different tick progress, target choices, or validation failures
• THEN acceptance and rejection are evaluated independently for each sending peer
• THEN one peer's stale or invalid shoot request does not overwrite or suppress the other's authoritative combat state

Requirement: Session removal is explicit and does not corrupt remaining peers

The multi-session lifecycle coordinator SHALL support explicit removal or disconnection handling for one managed session without resetting unrelated sessions that remain active.

Scenario: Disconnect removes one session only

• WHEN one remote peer disconnects or is evicted by the host
• THEN the coordinator updates or removes that peer's managed session
• THEN other managed sessions remain queryable and keep their own lifecycle state

Requirement: Multi-session server lifecycle can be owned by a runtime entry point

The multi-session lifecycle model SHALL support being created, owned, and torn down through a concrete server runtime entry point. Starting the entry point MUST provide access to the MultiSessionManager through the hosted ServerNetworkHost, and stopping the entry point MUST clear managed sessions without requiring callers to remove peers individually.

Scenario: Entry point startup exposes multi-session lifecycle ownership

• WHEN a server runtime entry point starts successfully
• THEN the hosted ServerNetworkHost exposes its MultiSessionManager for per-peer lifecycle observation
• THEN callers do not need to manually construct or inject a separate multi-session coordinator

Scenario: Entry point shutdown clears all managed peers

• WHEN the server runtime entry point is stopped while one or more managed sessions exist
• THEN the hosted ServerNetworkHost removes all managed sessions as part of shutdown
• THEN no unrelated external cleanup step is required to reset multi-session lifecycle state