# NERVE Code Map
A concise, file-by-file overview of the `nerve-ipc` crate. Use this as a quick reference when navigating the codebase. See `docs/protocol.md` for the full wire specification.
## src/
### lib.rs
Crate root. Declares public modules and re-exports the primary API surface (`encode`, `decode`, `FrameReader`, `Frame`, `FrameHeader`, `ProtocolError`, `FrameFlags`, `MessageType`, `RequestId`, `RequestTable`).
### main.rs
Binary entrypoint (example/CLI placeholder). Currently prints a greeting; intended to evolve into demos/tools that exercise the protocol.
### constants.rs
Protocol constants:
- `MAGIC` (`u32`): ASCII "NERV" (`0x4E455256`)
- `VERSION` (`u16`): protocol version (`1`)
- `HEADER_SIZE` (`usize`): fixed header size (`20` bytes)
- `MAX_PAYLOAD_SIZE` (`usize`): per-frame payload limit (`1 MiB`)
- `MAX_INFLIGHT_REQUESTS` (`usize`): max concurrent requests per connection (`1024`)
### types.rs
Shared protocol types:
- `MessageType` (`repr(u8)`): enumerates supported message kinds
- `FrameFlags` (`bitflags`): `STREAM`, `FINAL`
- `RequestId` (`repr(transparent)`): request identifier (`u64`)
- `ProtocolErrorKind`: local error classification used by `ProtocolError`
Includes `TryFrom<u8>` for `MessageType`.
### frame.rs
Wire-level structures:
- `FrameHeader` (fixed 20 bytes, little-endian): matches on-wire layout
- `Frame<'a>`: borrowed view combining header and payload slice
### codec.rs
Binary codec:
- `encode(msg_type, flags, request_id, payload) -> Vec<u8>`
- Single allocation; validates header invariants and `MAX_PAYLOAD_SIZE`
- `decode(buffer) -> Frame<'_>`
- Parses header and payload; checks magic/version/type; returns borrowed `Frame`
### io.rs
Buffered I/O helpers:
- `FrameReader`
- Accumulates bytes from any `std::io::Read`
- Produces parsed `Frame`s incrementally
- Drains consumed bytes from the internal buffer
### request.rs
Request lifecycle per connection:
- `RequestState`: `Init`, `Running`, `Streaming`, `Completed`, `Cancelled`, `Error`
- `RequestTable`
- `start(id)`, `mark_streaming(id)`, `complete(id)`, `cancel(id)`, `is_cancelled(id)`, `cleanup(id)`
- Backed by `HashMap<RequestId, RequestState>` (may be optimized to slab/array later)
### message.rs
V1 message-level schema. Provides strongly-typed, serde-serializable Rust structs for each NERVE message type, plus `encode_message` / `decode_message` codec helpers and `decode_search_query` (decode + validate combined).
Types: `SearchQuery`, `SearchContext`, `SearchOptions`, `SearchResult`, `SearchResultItem`, `AiToken`, `MessageError`.
Constants: `MESSAGE_VERSION`, `MAX_RESULTS`.
Cancel carries no struct — its `request_id` is in the frame header and its payload is empty.
## benches/
### ping.rs
Benchmark(s) for ping/latency and codec performance. Used to validate target p99 RTT and allocation characteristics.
## tests/
### frame_roundtrip.rs
Round-trip encode/decode tests for `FrameHeader` and payload invariants.
### malformed.rs
Malformed input handling; validates error paths (e.g., invalid magic/version). Connection should be closed on violations.
### io.rs
Tests for `FrameReader` incremental parsing behavior with partial reads and buffer boundaries.
## docs/
### protocol.md
Formal protocol specification covering frame layout, message types, limits, and error semantics.
---
## Quick Links
- Public API: see `src/lib.rs` and re-exports
- Wire layout: see `src/frame.rs` and `docs/protocol.md`
- Codec: see `src/codec.rs`
- I/O: see `src/io.rs`
- Requests: see `src/request.rs`