swactor/specs/mvp_system/driver_pumps_contract.md

Driver And Pump Contract

This document defines the behavioral contract for the iroh driver, edge demux, and send/recv pumps. The driver owns tokio, connections, streams, demux, and byte-pump tasks.

Driver Authority

• The driver owns one iroh endpoint.
• The driver owns connection caching.
• The driver owns edge ALPN.
• The driver owns edge-id stream demux.
• The driver owns send and recv pump tasks.
• Actors do not poll stream futures directly in the MVP.

Connection And Stream Shape

• Each edge uses one persistent uni-stream.
• The stream starts with an edge_id preamble.
• After the preamble, the stream carries object records as bytes.
• The stream is not opened per object.
• Connections may be cached per (peer_node_id, ALPN).

Receive Rendezvous

• EstablishRecv may arrive before the stream.
• The stream may arrive before EstablishRecv.
• The driver stores whichever half arrives first.
• The recv pump starts only after both receive spec and stream exist.
• A pending stream is not read before the receive spec exists.

Recv Pump

• The recv pump is byte-blind after edge demux.
• It does not parse ObjectHeader.
• It copies QUIC bytes into free ingress ring spans.
• It advances commit after bytes are in the ring.
• It emits or coalesces RingReadable.
• If no ring space exists, it stops reading and waits for RingWritable.

Send Pump

• The send pump opens one uni-stream for the edge.
• It writes the edge_id preamble once.
• It writes committed egress ring bytes to QUIC.
• It advances consume only after write_all accepts bytes.
• It emits or coalesces RingWritable.
• If network or QUIC flow control stalls, it keeps ownership of unread ring bytes until the write completes.

Fault And Stop

• Read error emits StreamFault.
• Write error emits StreamFault.
• Protocol edge failure emits StreamFault.
• StopEdge stops the corresponding pump.
• Stopped pumps emit PumpStopped.

Test Direction

Tests should use mock streams and rings to drive driver messages and pump wake events. Successful tests should assert rendezvous in both arrival orders, preamble once, byte-blind copying, cursor advancement after I/O acceptance, and backpressure. Fault tests should inject read/write errors and stop races.