process TODO.md step 9

2026-03-28 14:26:40 +08:00
parent 101694a3b0
commit 1b1598dbb7
15 changed files with 396 additions and 13 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-28
@@ -0,0 +1,55 @@
+## Context
+
+The shared networking layer already separates reliable messaging from sync-heavy traffic conceptually, but the runtime integration path still tends to compose a single transport dependency and leaves lane selection to host-specific setup. This makes the dual-transport design incomplete: shared services can express sync intent, yet composition can still collapse both lanes into one implicit path. The repository also requires preserving the existing client single-session flow and avoiding Unity-specific dependencies in shared networking code.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Allow integration-layer composition to pass both reliable and sync transports into shared networking services.
+- Keep the single-transport path valid by falling back to the reliable transport when no dedicated sync transport is configured.
+- Centralize lane selection inside shared networking/session code so client and server hosts follow the same wiring rules.
+- Add regression coverage for both client single-session and server multi-session composition paths.
+
+**Non-Goals:**
+- Redesign transport implementations or message schemas.
+- Introduce Unity-only adapters into `Assets/Scripts/Network/`.
+- Change message delivery policy beyond what is required to connect existing sync traffic to the proper transport.
+
+## Decisions
+
+### Decision: Treat sync transport as an optional secondary dependency
+The integration layer will accept a primary reliable transport and an optional sync transport. Shared services will retain a deterministic fallback to the primary transport when the secondary dependency is absent.
+
+This preserves existing callers and lets the change land without forcing all hosts to upgrade in one step.
+
+Alternative considered: require dual transports everywhere. Rejected because it would break the current single-session client setup and create unnecessary migration pressure.
+
+### Decision: Keep transport ownership at session/runtime composition boundaries
+Session managers, message managers, or equivalent composition roots should receive both transport references during construction so downstream routing logic can stay host-agnostic.
+
+This keeps transport selection in shared code and prevents Unity or host bootstrapping layers from re-implementing routing rules.
+
+Alternative considered: inject a host-side selector callback. Rejected because it spreads transport policy across hosts and makes regression coverage weaker.
+
+### Decision: Encode fallback behavior in requirements and tests
+The change will specify that sync-routed traffic uses the sync transport when available and otherwise uses the primary reliable transport. Tests should cover both client single-session and server multi-session variants.
+
+Alternative considered: rely on implementation comments only. Rejected because the fallback contract is easy to regress during future refactors.
+
+## Risks / Trade-offs
+
+- [Risk] Integration constructors may grow more complex with optional transport parameters. → Mitigation: keep the extra dependency scoped to composition roots and default the sync transport explicitly.
+- [Risk] Hosts may accidentally provide mismatched transport instances across session types. → Mitigation: express wiring requirements in specs and add regression tests for composition paths.
+- [Risk] Existing tests may only cover single-session client behavior. → Mitigation: add server multi-session coverage as part of the task list.
+
+## Migration Plan
+
+1. Extend composition APIs to accept the optional sync transport without breaking existing call sites.
+2. Update shared routing/session initialization to store and use both dependencies.
+3. Add or adjust edit-mode tests for fallback and dedicated sync-lane behavior.
+4. Rollback, if needed, by removing the optional sync transport wiring while retaining the original single-transport constructor path.
+
+## Open Questions
+
+- Which concrete integration types currently own transport composition for client and server entry points?
+- Are there any message categories besides sync traffic that should explicitly target the secondary transport at composition time?
@@ -0,0 +1,26 @@
+## Why
+
+The networking stack already distinguishes between reliable gameplay messaging and high-frequency sync traffic, but the integration layer still assumes a single transport path in its runtime wiring. Step 9 is needed now to expose the dual-transport design at composition time so hosts can route each lane consistently without breaking the existing single-session client path.
+
+## What Changes
+
+- Wire the integration layer so session/runtime composition can accept both a primary reliable transport and a sync transport.
+- Preserve backward-compatible behavior when only the primary transport is provided by continuing to use the reliable path for all traffic that lacks a dedicated sync lane.
+- Update message/session integration contracts so transport selection is resolved in shared networking code rather than by host-specific call sites.
+- Add regression coverage for client single-session and server multi-session integration paths that depend on dual-transport wiring.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `shared-network-foundation`: Extend the shared composition contract so network managers and related services can be constructed with dual transports while preserving the existing single-transport fallback.
+- `network-session-lifecycle`: Update runtime/session wiring requirements so sessions initialize and retain both reliable and sync transport dependencies where available.
+- `network-sync-strategy`: Require integration-layer routing to connect sync traffic to the dedicated sync transport instead of relying on host-side manual wiring.
+
+## Impact
+
+- Affected code under `Assets/Scripts/Network/` for integration/composition, session initialization, and transport-aware message dispatch.
+- Edit-mode regression tests under `Assets/Tests/EditMode/Network/`.
+- No Unity-specific dependency changes; Unity adapters should remain outside shared networking code.
@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Sessions retain dual transport wiring
+Session lifecycle components SHALL initialize session-scoped networking services with both the primary reliable transport and the optional sync transport supplied by the integration layer.
+
+#### Scenario: Client single-session initialization with dual transports
+- **WHEN** the client integration path creates a single session and a sync transport is configured
+- **THEN** the session-scoped services SHALL retain both transport references for subsequent message routing
+
+#### Scenario: Server multi-session initialization with fallback transport
+- **WHEN** the server integration path creates session-scoped services without a dedicated sync transport
+- **THEN** each session SHALL continue to initialize successfully and SHALL use the primary reliable transport as the fallback lane
@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Integration wiring enforces sync lane selection
+The networking stack SHALL route sync-designated traffic through the sync transport when the integration layer provides one, and SHALL fall back to the primary reliable transport when it does not.
+
+#### Scenario: Dedicated sync transport available
+- **WHEN** sync-designated traffic is sent from a session whose integration wiring includes a sync transport
+- **THEN** the traffic SHALL be dispatched on the sync transport instead of the primary reliable transport
+
+#### Scenario: Dedicated sync transport unavailable
+- **WHEN** sync-designated traffic is sent from a session whose integration wiring does not include a sync transport
+- **THEN** the traffic SHALL be dispatched on the primary reliable transport without failing session operation
@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Shared network composition accepts dual transports
+The shared networking composition layer SHALL allow construction of network managers and related shared services with a primary reliable transport and an optional sync transport.
+
+#### Scenario: Integration receives both transports
+- **WHEN** a host composes the shared networking stack with both a reliable transport and a sync transport
+- **THEN** the shared composition path SHALL retain both dependencies for downstream routing and session services
+
+#### Scenario: Integration receives only one transport
+- **WHEN** a host composes the shared networking stack with only the reliable transport
+- **THEN** the shared composition path SHALL remain valid and SHALL treat the reliable transport as the fallback lane for traffic without a dedicated secondary transport
@@ -0,0 +1,17 @@
+## 1. Extend Integration Composition
+
+- [x] 1.1 Identify the shared integration/composition entry points that currently construct networking services with a single transport.
+- [x] 1.2 Update the relevant constructors or factory methods to accept an optional sync transport alongside the primary reliable transport.
+- [x] 1.3 Preserve backward-compatible call paths so existing single-transport composition still builds and defaults correctly.
+
+## 2. Wire Dual Transports Through Session Services
+
+- [x] 2.1 Update session-scoped networking services to retain both transport references provided by the integration layer.
+- [x] 2.2 Route sync-designated traffic to the sync transport when present and fall back to the reliable transport otherwise.
+- [x] 2.3 Ensure the shared wiring keeps host-specific transport policy out of Unity-only or integration call sites.
+
+## 3. Verify Regression Coverage
+
+- [x] 3.1 Add or update edit-mode tests for client single-session composition with both reliable and sync transports.
+- [x] 3.2 Add or update edit-mode tests for server multi-session composition when no dedicated sync transport is provided.
+- [x] 3.3 Run `dotnet build Network.EditMode.Tests.csproj -v minimal` and `dotnet test Network.EditMode.Tests.csproj --no-build -v minimal` after implementation.