process TODO.md

2026-03-28 11:35:00 +08:00
parent 371ab30eea
commit fc8675f081
15 changed files with 323 additions and 26 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-28
@@ -0,0 +1,41 @@
+## Context
+
+`SharedNetworkRuntime` and `ServerNetworkHost` already expose an MVP-friendly constructor shape with one reliable `ITransport` and an optional sync `ITransport`. That behavior is important because the message-routing layer now distinguishes reliable gameplay/control traffic from high-frequency sync traffic, but the current spec only says sync traffic is composable in principle. TODO step 5 is about preserving the current dual-transport runtime boundary before the Unity integration layer is updated in a later step.
+
+The main constraint is to keep the shared networking core host-agnostic. We need explicit runtime and host requirements for dual-lane startup, shutdown, and receive composition without introducing Unity types or widening `ITransport` into a multi-lane abstraction too early.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Preserve a shared-runtime contract where client and server hosts can provide distinct reliable and sync transport instances.
+- Make startup, shutdown, and inbound handling expectations explicit for both `SharedNetworkRuntime` and `ServerNetworkHost`.
+- Keep lane selection in `MessageManager` and delivery-policy abstractions rather than redesigning `ITransport`.
+- Drive minimal implementation work, ideally verification plus any missing regression tests.
+
+**Non-Goals:**
+- Updating `NetworkManager` or the server bootstrap integration layer to instantiate two transports.
+- Redesigning `ITransport`, introducing a transport multiplexer abstraction, or changing the envelope protocol.
+- Expanding the sync strategy beyond the message-lane split already captured in `network-sync-strategy`.
+
+## Decisions
+
+### Preserve constructor-based dual-transport composition
+The shared runtime contract will continue to accept one primary reliable transport plus an optional sync transport. This matches the existing code, keeps host wiring simple, and avoids forcing every transport implementation to understand multiple delivery lanes.
+
+Alternative considered: extend `ITransport` with multiple send lanes or channel APIs. Rejected for MVP because it would ripple through every transport implementation and blur the boundary between transport concerns and message-routing policy.
+
+### Specify dual-lane lifecycle behavior at the host/runtime level
+The spec will explicitly require `SharedNetworkRuntime` and `ServerNetworkHost` to start and stop both transport instances when distinct transports are supplied, and to observe inbound activity from both lanes on the server side. That turns the current code shape into a protected contract instead of an incidental implementation detail.
+
+Alternative considered: leave lifecycle behavior implicit and only test lane selection in `MessageManager`. Rejected because lane selection is not sufficient if host/runtime wiring later collapses back to one started transport.
+
+### Keep message and delivery policy contracts unchanged
+The updated requirement will keep the existing shared envelope format and `MessageManager` delivery-policy resolution, with dual-lane composition remaining outside `ITransport`. This isolates TODO step 5 from later integration changes while still making `MoveInput`/`PlayerState` vs. `ShootInput`/`CombatEvent` lane expectations usable at runtime.
+
+Alternative considered: introduce a new capability just for dual transport wiring. Rejected because this is a refinement of the existing shared foundation contract, not a separate product capability.
+
+## Risks / Trade-offs
+
+- [Risk] Shared specs may become too implementation-shaped by naming concrete runtime classes. → Mitigation: keep the requirement centered on host-visible behavior while using `SharedNetworkRuntime` and `ServerNetworkHost` only where the current shared entry points are the contract.
+- [Risk] Future transport redesign could invalidate the constructor shape. → Mitigation: scope this explicitly to the MVP and note that broader `ITransport` changes remain out of scope.
+- [Risk] Existing tests may not cover startup or shutdown of both lanes. → Mitigation: include regression tasks for dual-transport lifecycle behavior, not only message routing.
@@ -0,0 +1,21 @@
+## Why
+
+The shared runtime already has an MVP-oriented dual-transport shape, but TODO step 5 is still undocumented at the spec level. We need to lock that contract before changing integration wiring so client and server hosts keep a clear, host-agnostic way to run reliable control traffic and high-frequency sync traffic on separate transport instances without prematurely redesigning `ITransport`.
+
+## What Changes
+
+- Document that `SharedNetworkRuntime` preserves separate reliable and sync transport inputs for the MVP and starts or stops both lanes when distinct instances are supplied.
+- Document that `ServerNetworkHost` preserves the same dual-transport constructor shape and attaches receive handling for both lanes without forking message contracts.
+- Require the shared runtime foundation to keep delivery-lane composition outside `ITransport` so hosts can use two transport instances instead of expanding the transport abstraction early.
+- Add implementation tasks to verify or tighten regression coverage around dual-transport startup and message-lane usage in the shared runtime and server host.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `shared-network-foundation`: Narrow the shared runtime contract so MVP hosts explicitly preserve dual-transport composition through `SharedNetworkRuntime` and `ServerNetworkHost` without widening `ITransport`.
+
+## Impact
+
+Affected code is expected in `Assets/Scripts/Network/NetworkApplication/SharedNetworkRuntime.cs`, `Assets/Scripts/Network/NetworkHost/ServerNetworkHost.cs`, and related edit-mode regression tests. This change should not introduce new transport interfaces or Unity-specific dependencies into shared networking code.
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Shared core preserves current transport and message contracts
+The shared client/server foundation SHALL preserve the envelope-based business-message contract across client and server hosts while allowing delivery-policy selection behind the shared message-routing layer. Reliable control traffic MUST continue to use the existing `ITransport` contract, and high-frequency sync traffic MUST remain composable by supplying a second host-agnostic sync transport instance to `SharedNetworkRuntime` or `ServerNetworkHost` rather than by expanding `ITransport` for MVP-specific lane semantics. The shared message-type contract MUST allow hosts to distinguish `MoveInput`, `ShootInput`, `CombatEvent`, and `PlayerState` as separate business messages across both delivery lanes.
+
+#### Scenario: Shared runtime starts distinct reliable and sync transports
+- **WHEN** a client host constructs `SharedNetworkRuntime` with one reliable transport and a different sync transport instance
+- **THEN** starting the runtime starts both transport instances
+- **THEN** stopping the runtime stops both transport instances while keeping the same shared message-routing contract
+
+#### Scenario: Server host composes both transport lanes without protocol forks
+- **WHEN** a server host constructs `ServerNetworkHost` with one reliable transport and a different sync transport instance
+- **THEN** it observes inbound activity from both transport lanes through shared host logic
+- **THEN** it routes messages with the same envelope and message-type contract instead of defining a lane-specific protocol fork
+
+#### Scenario: Shared hosts exchange the same envelope format across delivery lanes
+- **WHEN** a client host sends a business message through either the reliable control path or the high-frequency sync path
+- **THEN** the payload is encoded with the same shared envelope and message-type contract
+- **THEN** the server host decodes and routes it through shared networking logic without a host-specific protocol fork
+
+#### Scenario: Hosts preserve dual-transport composition outside ITransport
+- **WHEN** a host needs separate reliable and sync lanes for MVP gameplay traffic
+- **THEN** it provides separate transport instances plus delivery-policy configuration to shared runtime or host entry points
+- **THEN** the shared networking core does not require `ITransport` itself to grow MVP-specific multi-lane APIs
@@ -0,0 +1,14 @@
+## 1. Verify shared dual-transport runtime boundaries
+
+- [x] 1.1 Verify `SharedNetworkRuntime` still preserves the MVP constructor shape with a primary reliable `ITransport`, an optional sync `ITransport`, and no new multi-lane transport API.
+- [x] 1.2 Verify `ServerNetworkHost` still preserves the same dual-transport constructor shape, starts both lanes when distinct transports are supplied, and attaches inbound handling for both transports.
+
+## 2. Add regression coverage for dual-lane lifecycle behavior
+
+- [x] 2.1 Add or extend edit-mode tests to prove `SharedNetworkRuntime` starts and stops two distinct transport instances while continuing to route sync-lane messages through the configured sync transport.
+- [x] 2.2 Add or extend edit-mode tests to prove `ServerNetworkHost` starts two distinct transport instances and records inbound activity from the sync transport without cross-lane protocol changes.
+
+## 3. Validate the MVP shared-network contract
+
+- [x] 3.1 Run `dotnet build Network.EditMode.Tests.csproj -v minimal`.
+- [x] 3.2 Run `dotnet test Network.EditMode.Tests.csproj --no-build -v minimal`.