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,55 @@
+## Context
+
+`TODO.md` step 2 focuses narrowly on how the shared runtime chooses a delivery lane after the gameplay protocol split. The current code already centralizes that decision in `DefaultMessageDeliveryPolicyResolver`, which is consulted by `MessageManager` before selecting either the reliable transport or the optional sync transport.
+
+This change does not introduce a new transport abstraction or alter the envelope contract. Its purpose is to lock down the default mapping contract so later MVP work on stale filtering, prediction, and dual-transport wiring can assume a stable policy table: latest-wins movement/state traffic uses the sync lane, while shooting and combat-result traffic continue to use reliable ordered delivery.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Define the default message-type to delivery-policy mapping used by the shared runtime.
+- Keep the mapping small and explicit so `MoveInput` and `PlayerState` are the only gameplay messages promoted to `HighFrequencySync`.
+- Preserve reliable ordered fallback for `ShootInput`, `CombatEvent`, and existing control-plane messages.
+- Require regression tests that exercise `MessageManager` lane selection through the resolver contract.
+
+**Non-Goals:**
+- Wiring two concrete transport instances through all integration entry points.
+- Changing stale-sequence filtering, prediction replay, or protobuf field definitions beyond what this mapping step depends on.
+- Replacing the resolver with a configurable registry or runtime policy editor.
+
+## Decisions
+
+### Keep the default mapping in a static resolver table
+The default runtime contract will remain a small static mapping owned by `DefaultMessageDeliveryPolicyResolver`. `MoveInput` and `PlayerState` are explicitly listed as `HighFrequencySync`, and unresolved message types fall back to `ReliableOrdered`.
+
+Alternative considered: list every message type explicitly in the resolver.
+Rejected because the TODO step only needs a narrow exception set. A reliable fallback keeps control traffic and future message types safe unless they are intentionally promoted to the sync lane.
+
+### Make lane selection observable through `MessageManager` regression tests
+The design relies on send-path tests rather than resolver-only unit tests. `MessageManager` is the behavior boundary that chooses which transport instance sends the envelope, so routing tests verify the mapping contract and the integration between resolver and transport selection at the same time.
+
+Alternative considered: test only `DefaultMessageDeliveryPolicyResolver.Resolve`.
+Rejected because that would not prove the runtime actually routes through the expected transport lane.
+
+### Treat reliable ordered delivery as the default for discrete gameplay events
+`ShootInput` and `CombatEvent` remain on the reliable ordered path by omission from the sync mapping table. This avoids expanding latest-wins semantics to discrete gameplay events where silent dropping or unordered handling would be incorrect.
+
+Alternative considered: map all gameplay messages to the sync lane after the protocol split.
+Rejected because delivery semantics differ by message intent, and event-style gameplay traffic must preserve reliable ordered behavior.
+
+## Risks / Trade-offs
+
+- [A default fallback can hide newly added message types on the reliable lane] -> Mitigation: keep the spec explicit that only `MoveInput` and `PlayerState` use `HighFrequencySync`, and add routing tests for every split MVP gameplay message.
+- [Future transport wiring could drift from the resolver contract] -> Mitigation: keep `MessageManager` tests asserting which transport instance is selected for sync versus reliable policies.
+- [This change can look redundant because the current code already implements it] -> Mitigation: use the change to align TODO step 2, specs, and regression coverage so later work has a stable contract to build on.
+
+## Migration Plan
+
+1. Update the `network-sync-strategy` delta spec to define the default resolver mapping for split gameplay messages.
+2. Verify `DefaultMessageDeliveryPolicyResolver` maps `MoveInput` and `PlayerState` to `HighFrequencySync` and leaves `ShootInput`/`CombatEvent` on the reliable ordered fallback.
+3. Keep or add `MessageManager` routing tests that prove sync-lane and reliable-lane selection for the split MVP gameplay messages.
+4. Use this locked mapping as the baseline for later dual-transport integration work.
+
+## Open Questions
+
+- None for this planning slice. The TODO step already defines the target mapping and the current runtime shape is sufficient to implement it.
@@ -0,0 +1,26 @@
+## Why
+
+The MVP TODO requires a stable default mapping between gameplay message types and delivery lanes so split movement, state, shooting, and combat-result messages do not regress back onto one transport policy. This needs to be formalized now because the routing resolver is the contract that keeps the sync lane limited to latest-wins traffic while preserving reliable delivery for gameplay events.
+
+## What Changes
+
+- Define the default delivery-policy mapping for shared gameplay message routing in the networking runtime.
+- Require `MoveInput` and `PlayerState` to resolve to `HighFrequencySync` in the default resolver used by `MessageManager`.
+- Require `ShootInput` and `CombatEvent` to continue resolving through the reliable ordered default path instead of the sync lane.
+- Add regression coverage that proves movement/state traffic uses the sync lane while shooting/combat-result traffic remains on the reliable lane.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `network-sync-strategy`: Clarify the default resolver mapping that sends `MoveInput` and `PlayerState` through the high-frequency sync lane while `ShootInput` and `CombatEvent` remain on the reliable ordered lane.
+
+## Impact
+
+- Affected code: `Assets/Scripts/Network/NetworkApplication/DefaultMessageDeliveryPolicyResolver.cs` and the `MessageManager` send path that consults the resolver.
+- Affected behavior: the runtime keeps latest-wins movement/state traffic off the reliable lane by default, while shooting requests and combat results keep reliable ordered delivery semantics.
+- Affected tests: edit-mode message-routing tests need explicit assertions for sync-lane and reliable-lane selection for the split MVP gameplay message types.
@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: Hosts assign delivery policies to synchronization message types
+The shared networking core SHALL allow hosts to map business message types to delivery policies. The default shared resolver used by `MessageManager` MUST map `MoveInput` and `PlayerState` to `HighFrequencySync`, while `ShootInput`, `CombatEvent`, and control-plane messages MUST resolve to `ReliableOrdered` unless a host intentionally supplies a different resolver.
+
+#### Scenario: Default resolver sends movement and state traffic to the sync lane
+- **WHEN** the runtime uses `DefaultMessageDeliveryPolicyResolver` to send `MoveInput` or `PlayerState`
+- **THEN** the resolver returns `HighFrequencySync`
+- **THEN** `MessageManager` sends that envelope through the sync transport lane when one is configured
+
+#### Scenario: Default resolver keeps shooting and combat events on the reliable lane
+- **WHEN** the runtime uses `DefaultMessageDeliveryPolicyResolver` to send `ShootInput` or `CombatEvent`
+- **THEN** the resolver returns `ReliableOrdered`
+- **THEN** `MessageManager` sends that envelope through the reliable transport lane
+
+#### Scenario: Default resolver preserves reliable control traffic
+- **WHEN** the runtime uses `DefaultMessageDeliveryPolicyResolver` to send login, logout, heartbeat, or other session-management messages
+- **THEN** the resolver returns `ReliableOrdered`
+- **THEN** those messages continue to use the reliable transport path
@@ -0,0 +1,17 @@
+## 1. Lock The Default Delivery Mapping
+
+- [x] 1.1 Verify `Assets/Scripts/Network/NetworkApplication/DefaultMessageDeliveryPolicyResolver.cs` explicitly maps `MessageType.MoveInput` and `MessageType.PlayerState` to `DeliveryPolicy.HighFrequencySync`.
+- [x] 1.2 Verify the default resolver leaves `MessageType.ShootInput`, `MessageType.CombatEvent`, and control-plane messages on the `DeliveryPolicy.ReliableOrdered` fallback path.
+- [x] 1.3 Confirm `MessageManager` continues consulting the resolver before selecting the reliable or sync transport lane.
+
+## 2. Protect Lane Selection With Regression Tests
+
+- [x] 2.1 Keep or add edit-mode routing tests proving `MoveInput` uses the sync lane and does not send through the reliable transport.
+- [x] 2.2 Keep or add edit-mode routing tests proving `ShootInput` and `CombatEvent` use the reliable lane and do not send through the sync transport.
+- [x] 2.3 Keep or add coverage that control-plane traffic still defaults to the reliable ordered lane when the default resolver is used.
+
+## 3. Validate The Step-2 Contract
+
+- [x] 3.1 Build `Network.EditMode.Tests.csproj -v minimal` to verify the delivery-mapping change does not break the shared networking assemblies.
+- [x] 3.2 Run `dotnet test Network.EditMode.Tests.csproj --no-build -v minimal` to confirm the routing regression suite passes.
+- [x] 3.3 Update `TODO.md` or related implementation notes only if verification shows the step-2 completion markers need correction.