阶段 5

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

@@ -0,0 +1,34 @@
+# 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, and reconnect rules for each managed session independently using the shared session lifecycle vocabulary.
+
+#### 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
+
+### 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

openspec/specs/network-session-lifecycle/spec.md

@@ -0,0 +1,44 @@
+# network-session-lifecycle Specification
+
+## Purpose
+Define the shared session lifecycle model that separates transport connectivity, login state, heartbeat liveness, timeout detection, and reconnect scheduling for client and server hosts.
+
+## Requirements
+### Requirement: Session lifecycle distinguishes transport and login state
+The shared networking core SHALL expose an explicit session lifecycle model that distinguishes transport connectivity from login/authentication success. Hosts MUST be able to observe at least disconnected, transport-connected, login-pending, logged-in, login-failed, timed-out, and reconnecting lifecycle states for each managed session without inferring them from unrelated message handlers.
+
+#### Scenario: Transport connect does not imply login success
+- **WHEN** the transport establishes a usable remote session but no login success message has been accepted yet
+- **THEN** the shared lifecycle reports a transport-connected or login-pending state for that managed session
+- **THEN** it does not report the session as logged in
+
+#### Scenario: Login success advances lifecycle independently
+- **WHEN** the client or server session manager receives a successful login/authentication result for an active transport session
+- **THEN** the shared lifecycle transitions that managed session into the logged-in state
+- **THEN** hosts can react to that state change without conflating it with transport establishment
+
+### Requirement: Heartbeat is limited to liveness, RTT, and time sync
+The shared session lifecycle SHALL treat heartbeat traffic as infrastructure input for liveness detection, round-trip-time measurement, and clock synchronization only. Heartbeat processing MUST NOT itself own login success, login failure, or reconnect policy decisions.
+
+#### Scenario: Heartbeat updates liveness and RTT only
+- **WHEN** a heartbeat response is received for an active session
+- **THEN** the session manager updates last-seen or timeout bookkeeping and RTT or clock-sync data
+- **THEN** it does not mark the session logged in solely because the heartbeat succeeded
+
+#### Scenario: Missing heartbeat triggers timeout state
+- **WHEN** the configured heartbeat timeout elapses without a required heartbeat or other liveness signal
+- **THEN** the session lifecycle transitions the session into a timed-out state
+- **THEN** reconnect handling is delegated to the lifecycle reconnect policy rather than hidden inside the heartbeat handler itself
+
+### Requirement: Timeout and reconnect are session-manager responsibilities
+The shared networking core SHALL manage timeout detection, disconnect transitions, and reconnect scheduling through session-manager components rather than implementing those decisions inside business message handlers. Hosts that manage multiple concurrent peers MUST apply these rules independently per managed session rather than collapsing timeout or reconnect state to the entire runtime.
+
+#### Scenario: Timeout produces an observable reconnect transition
+- **WHEN** a reconnect-capable host has a session that times out
+- **THEN** the session manager emits a timeout-related lifecycle transition for that managed session
+- **THEN** it can subsequently move the session into a reconnecting or reconnect-pending state according to configured policy
+
+#### Scenario: Login failure is distinct from transport disconnect
+- **WHEN** authentication or login fails while the transport session is still active
+- **THEN** the shared lifecycle reports a login-failed state for that managed session
+- **THEN** hosts can handle that failure separately from a transport disconnect or heartbeat timeout

openspec/specs/shared-network-foundation/spec.md

@@ -1,7 +1,7 @@
 # shared-network-foundation Specification
 
 ## Purpose
-Define the shared transport and message-routing foundation that both client and server hosts use without depending on Unity-specific runtime host classes.
+Define the shared transport, session-lifecycle, and message-routing foundation that both client and server hosts use without depending on Unity-specific runtime host classes.
 
 ## Requirements
 ### Requirement: Shared network core is host-agnostic
@@ -37,3 +37,16 @@ The shared client/server foundation SHALL preserve the existing `ITransport` sen
 - **WHEN** a client host sends a business message through the shared core to a server host using the shared core
 - **THEN** the message is encoded using the same envelope contract on the client side
 - **THEN** the server host decodes and routes it through the shared message-routing layer without a host-specific protocol fork
+
+### Requirement: Shared runtime owns host-agnostic session lifecycle orchestration
+The shared network foundation SHALL include host-agnostic session lifecycle orchestration alongside transport startup and message routing. Client and server hosts MUST be able to compose the shared foundation with session orchestration that consumes transport events, login results, and heartbeat signals without depending on Unity-specific runtime types, while supporting both single-session client composition and multi-session server composition.
+
+#### Scenario: Client host composes runtime with single-session lifecycle manager
+- **WHEN** the Unity client constructs its shared networking runtime
+- **THEN** that runtime includes shared session lifecycle management for its single remote session in addition to transport and message routing
+- **THEN** Unity-specific code remains responsible only for reacting to lifecycle state changes and driving host behavior
+
+#### Scenario: Server host composes shared foundation with multi-session orchestration
+- **WHEN** a non-Unity server host constructs the runtime networking stack for multiple remote peers
+- **THEN** it uses the shared transport and message-routing foundation together with shared multi-session lifecycle orchestration
+- **THEN** server-specific cleanup, admission, and gameplay reactions stay in the server host adapter rather than forking the shared lifecycle contract