The README's crate table says what each layer is, but not what to read first. The layering (transport → wire protocol → zero-copy semantics → async adapter → demos) only lands in one direction, and a newcomer opening hord-stream/src/stream.rs first — the biggest file — gets the worst possible entry point.
A short "Where to start" section would help. Suggested order, with the reason each step earns its place:
SPEC.md §4–§6 — the wire protocol before any code: envelope, handshake, credits. The tree carries 260 inline § annotations, so these clause numbers are the vocabulary every comment assumes you already have.hord-stream/src/handshake.rs — 246 lines, self-contained, with round-trip unit tests that need no device. The smallest complete piece of the protocol.HordStream::handle_completion in hord-stream/src/stream.rs — the heart of the transport: one flat dispatcher over completion types, each branch naming its spec clause. Worth reading before the API surface around it.serve_one in hord-demo/src/bin/server.rs — a whole request/response cycle, sync, no tokio in the way.hord-zerocopy/src/lib.rs with the rdma feature off — the X-HORD-RDMA-Write codec with no RDMA anywhere near it; builds and tests on a laptop.acceptor_loop in hord-async/src/listener.rs — deliberately last. The subtlest error handling in the tree, and it only makes sense once the layers beneath it do.
The new "Spec coverage map" in PROTOTYPE.md is the companion piece — it maps each spec section to the crate and file implementing it, so step 1 has somewhere to go next.
The README's crate table says what each layer is, but not what to read first. The layering (transport → wire protocol → zero-copy semantics → async adapter → demos) only lands in one direction, and a newcomer opening
hord-stream/src/stream.rsfirst — the biggest file — gets the worst possible entry point.A short "Where to start" section would help. Suggested order, with the reason each step earns its place:
SPEC.md§4–§6 — the wire protocol before any code: envelope, handshake, credits. The tree carries 260 inline§annotations, so these clause numbers are the vocabulary every comment assumes you already have.hord-stream/src/handshake.rs— 246 lines, self-contained, with round-trip unit tests that need no device. The smallest complete piece of the protocol.HordStream::handle_completioninhord-stream/src/stream.rs— the heart of the transport: one flat dispatcher over completion types, each branch naming its spec clause. Worth reading before the API surface around it.serve_oneinhord-demo/src/bin/server.rs— a whole request/response cycle, sync, no tokio in the way.hord-zerocopy/src/lib.rswith therdmafeature off — theX-HORD-RDMA-Writecodec with no RDMA anywhere near it; builds and tests on a laptop.acceptor_loopinhord-async/src/listener.rs— deliberately last. The subtlest error handling in the tree, and it only makes sense once the layers beneath it do.The new "Spec coverage map" in
PROTOTYPE.mdis the companion piece — it maps each spec section to the crate and file implementing it, so step 1 has somewhere to go next.