RUDPClient/openspec/changes/archive/2026-03-26-main-thread-network-dispatch/specs/network-main-thread-dispatch/spec.md

ADDED Requirements

Requirement: Transport callbacks enqueue network message dispatch work

The network application layer SHALL place a thread-safe queue between ITransport.OnReceive callbacks and message handler execution. When a transport callback produces a valid application envelope, the callback path MUST enqueue dispatch work and return without invoking registered business handlers inline.

Scenario: Valid payload is deferred instead of dispatched inline

• WHEN a transport implementation raises OnReceive with a valid encoded application message
• THEN the message layer enqueues one dispatch work item for that message
• THEN the registered handler is not executed during the transport callback itself

Scenario: Invalid payload does not block later queued messages

• WHEN the transport callback receives malformed bytes followed by a valid application message
• THEN the malformed payload is handled as an error without enqueuing executable work
• THEN the later valid message can still be enqueued and processed normally

Requirement: Main-thread drain executes queued handlers in receive order

The runtime SHALL provide an explicit main-thread drain step that executes queued network dispatch work in FIFO order. Message handlers, gameplay state mutation, and UI-facing reactions triggered by received messages MUST run only through this main-thread drain path.

Scenario: Drain executes queued work on demand

• WHEN one or more network messages have been enqueued from transport callbacks
• THEN no registered handler runs until the main-thread dispatcher performs a drain step
• THEN each queued handler executes during that drain step on the Unity main thread path

Scenario: Messages preserve receive order through the dispatcher

• WHEN multiple valid messages are enqueued in sequence for the same runtime
• THEN the main-thread dispatcher invokes their handlers in the same order they were enqueued

Requirement: Runtime network host pumps the dispatcher each frame

The Unity-side runtime network host SHALL integrate the dispatcher into its frame loop so queued network work is drained regularly while the network stack is running. The transport background thread responsibilities MUST remain limited to socket receive, KCP input/update, and transport-level error handling.

Scenario: Network host drains queued messages during runtime

• WHEN the client runtime has started networking and a message is queued from the transport layer
• THEN the runtime network host performs dispatcher draining during its Unity update loop
• THEN the queued handler runs without the transport layer directly touching Unity objects

Scenario: Transport layer remains free of Unity object mutation

• WHEN developers inspect the responsibilities of the transport receive path after stage four
• THEN they find socket receive, KCP processing, and enqueue/error handling only
• THEN Unity object mutation and UI updates are performed outside the transport callback path