irtt-rs/docs/protocol/IRTT_SERVER_PROTOCOL_SPEC.md

IRTT-Compatible Server Protocol Specification

Version: 1.1-verified Date: 2026-08-11 Compatibility baseline: IRTT 0.9.1, protocol version 1 Verification platform: macOS Darwin 25.5.0 arm64

---

1. Status

This document describes the externally observable behavior required for an independent server implementation that interoperates with existing IRTT (Isochronous Round-Trip Tester) clients speaking protocol version 1.

It is the server-side counterpart to IRTT_CLIENT_PROTOCOL_SPEC.md. The two documents share a wire format; this one adds only what a server must do that a client does not. Where a rule is already stated in the client specification (magic bytes, flag bits, field ordering, parameter encoding, HMAC computation), this document references it rather than restating it, and states only the server-specific reading of it.

This document does not describe upstream source structure, internal algorithms, module layout, or implementation organization. It is intended for a clean-room implementation that has never seen the upstream source code.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as interoperability requirements, consistent with RFC 2119.

Five distinct levels of statement are used throughout, and they are not interchangeable. Nothing in one level implies anything at another.

Marker	Meaning
Protocol requirement	Required for interoperability with existing clients. Stated with MUST / MUST NOT / SHOULD. Every one rests on observed behavior.
Upstream 0.9.1 behavior	What the reference server was observed to do on the wire. A compatible implementation is not obliged to reproduce it unless a separate protocol requirement says so.
Server policy	A configurable or arbitrary choice of the reference server, including its defaults. A compatible implementation may choose differently, and in several cases should.
Robustness recommendation	Advice for the clean implementation's own resilience or safety. It is not an interoperability requirement and no existing client can observe whether it was followed.
Source-assisted historical conclusion	A judgement about upstream's release history reached with contaminated-side access to upstream material. Never load-bearing: no requirement in this document depends on one. Used once, in Section 11.3.1.

Where the reference server's own behavior would be a poor choice for a new implementation — an unbounded resource policy, a fatal reaction to a single failed send — this document records the observation and the recommendation separately, and does not turn either into a protocol rule.

---

2. Scope and Compatibility Baseline

• Server-only. Client behavior appears only where a server's obligations depend on it.
• Protocol version 1, as implemented by IRTT 0.9.0 and 0.9.1.
• The baseline for every unqualified statement is the upstream 0.9.1 release.
• Two other upstream builds were exercised, and each is named explicitly wherever its results are used:
  • the 0.9.0 release, for the version comparison in Sections 11.3.1 and 21.1;
  • a build of the upstream development tree as it stood six commits past the 0.9.1 tag, covered separately in Section 21.2. Those six commits are not part of the 0.9.1 release, and no result measured against them redefines the 0.9.1 baseline.
• Development-era (0.1.x) protocol variants are out of scope and are not interoperable.
• CLI design, logging, output formats, configuration file syntax, and process supervision are out of scope.

Implementations are not required to use any specific internal architecture, data structure, naming convention, concurrency model, threading or task model, socket ownership arrangement, or source organization. This document deliberately prescribes none of those: they are decisions for the implementing project, not protocol facts. Only externally observable behavior is normative.

---

3. Clean-Room Provenance

This specification was produced on the contaminated side of the clean-room boundary described in ../clean-room/CLEANROOM_NOTES.md. It records only externally observable behavior:

• packet bytes on the wire, in both directions;
• accept / drop / reply decisions;
• session state transitions inferred from subsequent packet exchanges;
• negotiated parameter values returned to the client;
• timing boundaries measured by observation;
• documented command-line policy knobs and their observable effects.

Every normative statement in this document is supported by a black-box experiment against a running reference server, by a packet capture in captures/, or by published end-user documentation. Statements that could only be derived from internal structure have been excluded.

One labelled exception. Section 11.3.1 carries a single sentence of historical judgement — that a particular measured difference between 0.9.0 and 0.9.1 is an unintended regression rather than a designed feature — which was reached with contaminated-side access to upstream material. It is labelled where it appears, it is not normative, and no requirement anywhere in this document depends on it. The measured 0.9.0-versus-0.9.1 wire difference is stated separately and stands on its own. The contaminated-side evidence behind the judgement was retained on the contaminated side and deliberately not carried into this document; see ../clean-room/CLEANROOM_NOTES.md.

Naming. The parameter names used throughout (ProtocolVersion, Duration, Interval, Length, ReceivedStats, StampAt, Clock, DSCP, ServerFill) are taken from upstream's published documentation of its client's machine-readable output, not from source inspection. No other upstream identifier appears in this document.

---

4. Roles and Directionality

A server:

1. listens on one or more UDP endpoints;
2. accepts session-open requests and assigns session tokens;
3. echoes test packets, annotating them with reception statistics and timestamps as negotiated;
4. releases session state on client request, on policy limits, or on idle expiry.

Every packet a server emits MUST have the Reply flag (0x02) set. Every packet a server accepts MUST have the Reply flag clear.

Protocol requirement. A reply without the Reply flag is not merely ignored by existing clients — upstream 0.9.1 clients abort the run and terminate abnormally when a reply arrives with the flag clear. This was confirmed by driving an upstream client against a deliberately non-conforming server.

---

5. Transport and Packet Envelope

5.1 Transport

UDP only. There is no TCP fallback, no connection setup at the transport layer, and no fragmentation logic in the protocol itself.

The conventional server port is 2112 (server policy: the reference server's default bind is all addresses on port 2112).

5.2 Address Families

A server MUST support IPv4. IPv6 support is RECOMMENDED and is provided by the reference server.

Upstream 0.9.1 behavior. Binding to an unspecified address creates two independent listeners, one per address family, on the same port. Tokens are scoped to the listener that issued them: a token issued by the IPv4 listener is not recognized by the IPv6 listener on the same port, and a request bearing it is dropped as an unknown token. See captures/server-session-identity.pcapng and the vectors file for the equivalent same-family case.

Protocol requirement. Session tokens need only be unique within the scope in which they are looked up. A compatible implementation MAY use one global table or one per listener; clients never observe the difference except through the drop behavior above.

5.3 Reply Addressing

Protocol requirement. A reply MUST be sent to the exact source address and port of the request, and MUST be sent from the address and port to which the request was addressed. Clients use connected UDP sockets and silently discard datagrams whose source does not match the address they sent to.

Server policy. On a multi-homed host with a listener bound to an unspecified address, choosing the reply source address by routing table rather than by the request's destination address will break clients on the non-preferred address. The reference server offers an opt-in policy to pin the reply source address to the request's destination address, and its documentation recommends binding to explicit addresses instead. On single-homed and loopback configurations both modes were observed to produce correct source addresses.

5.4 Packet Admission

This section states which datagrams a server answers and which it discards. It describes outcomes, not an internal processing pipeline: any implementation that produces these accept/discard decisions is conformant, whatever order it evaluates them in.

Discard conditions. Each of the following was independently observed to cause the datagram to be silently discarded, with no reply of any kind and no change to the state of any live session:

Condition	Notes
Datagram too short to carry magic + flags	With an HMAC key configured, the authentication field is part of the floor, so the floor rises by 16 bytes
First three bytes are not the protocol magic
Any flag bit above the four defined bits is set (flags > 0x0F)
The Reply flag is set	A server never answers a datagram carrying it
Authentication mismatch of any kind	Section 14; includes the flag/key mismatch in either direction
A non-open datagram too short to carry the token
A non-open datagram whose token matches no live session	Section 8
A non-open datagram whose token matches a session bound to a different source endpoint	Section 8; the session itself is unaffected
An echo datagram too short to carry the sequence number
An echo datagram exceeding a configured maximum packet length	Section 9.4, server policy
An echo datagram arriving with no rate allowance left	Section 9.3, server policy
An open datagram whose parameter payload is malformed or out of range	Section 7.2

Protocol requirement. Every rejection is a silent discard. The protocol defines no error reply, no reset, and no NACK. A client distinguishes "rejected" from "lost" only by timing out. A compatible server MUST NOT answer any of the conditions above.

Observable precedence. Only two ordering relationships are externally visible, and both were verified directly. Both describe how an admissible datagram is interpreted; neither weakens any discard condition in the table above.

1. For an otherwise admissible datagram with Open set, Open interpretation takes precedence over Close interpretation and over an echo-shaped body. A datagram with both Open and Close set is a no-test open (Section 16), not a close; and an echo-shaped datagram that also carries the Open flag is answered as an open, with the bytes that would have been the token and sequence number parsed as Open parameter data rather than as those fields. This precedence is about interpretation only. It does not override the independent rejection conditions above: a datagram carrying the Open flag is still silently discarded if the Reply flag is also set, if any undefined flag bit is set, if authentication fails, or if its Open parameter payload is malformed or out of range. A compatible server SHOULD behave the same way, so that a client's retransmitted open is never mistaken for an echo.
2. An authentication failure is indistinguishable from an unknown token. A datagram carrying a valid token with a bad MAC produces exactly the same silence as one carrying a token that was never issued (Section 14.2). A compatible server MUST preserve this: no reply behavior may reveal whether a token exists, for a datagram that failed authentication.

Request bytes beyond the sequence number carry no meaning to a server. The midpoint/receive-send exclusivity and clock-consistency rules that govern timestamp fields apply to replies; they have no effect on inbound traffic. An echo request carrying arbitrary bytes in the region a reply would use for timestamps is accepted and answered normally.

5.5 Minimum and Maximum Datagram Sizes

Observed minimum accepted request sizes (no authentication):

Request kind	Minimum accepted datagram
Open (with empty parameter payload)	4 bytes
Close	12 bytes
Echo	16 bytes

With authentication enabled, add 16 bytes to each figure.

Upstream 0.9.1 behavior. Trailing bytes beyond the fields a request kind requires are ignored:

• an echo request longer than the negotiated length is accepted and answered with a reply of the negotiated length, not the request length;
• a close request with trailing bytes is accepted and closes the session.

The only length ceiling applied to requests is the configured maximum packet length (Section 19).

---

6. Server Lifecycle

6.1 Startup

Server policy. The reference server resolves its bind specifications, creates one listener per resolved address/family, and serves until interrupted. A failure on any single listener causes the whole server to stop.

6.2 Shutdown

Upstream 0.9.1 behavior. Termination is abrupt from the client's perspective. No close, reset, or notification packet of any kind is emitted for live sessions when the server shuts down; subsequent client packets simply go unanswered. Verified by signalling a running server mid-session and observing that nothing arrived at the client before the socket went silent.

Protocol requirement. None. Clients MUST already tolerate an unresponsive server. A compatible implementation MAY emit close replies to live sessions on shutdown; upstream clients ignore unsolicited close replies harmlessly (Section 15.1).

6.3 Reply Send Failures

Upstream 0.9.1 behavior. If sending a reply fails with a non-transient socket error, the listener terminates and the whole server process exits. This is reachable in ordinary use: a client may negotiate a packet length larger than the host's maximum outbound datagram size, and the first echo reply then ends the server. See Section 22.

Protocol requirement: none. A reply that is never sent is indistinguishable, to the client, from a reply that was lost in the network. No client can observe how the server reacted internally.

Robustness recommendation (clean implementation). Because the outcome above is reachable from ordinary client traffic and takes every other session down with it, a clean server should treat a per-packet send failure as a per-packet event: drop that reply, keep the listener and the process running, and continue serving other sessions. This is a resilience choice for the implementing project, not something compatibility requires.

---

7. OPEN Negotiation

7.1 Open Request

Direction: client → server.

Flags: Open (0x01) set, Reply (0x02) clear, HMAC (0x08) set iff the client is authenticating, Close (0x04) set iff the client requests no-test (Section 16).

Layout: magic (3) + flags (1) + [authentication (16)] + parameter payload.

Protocol requirement. There is no token field in an open request. The parameter payload begins immediately after the fixed header (and the authentication field, when present).

The parameter payload uses the tag/value encoding defined in the client specification, Section 8.6. A server MUST decode it with the same rules.

7.2 Parameter Acceptance and Rejection

A server parses the whole parameter payload. Observed acceptance rules:

Condition	Observed result
Empty parameter payload	Accepted; all parameters default to zero, then restriction applies
Unknown tag with a well-formed value	Silently ignored; the rest of the payload is still parsed
Truncated tag or truncated value varint	Dropped, no reply
Varint overflow	Dropped, no reply
Duration present and ≤ 0	Dropped, no reply
Interval present and ≤ 0	Dropped, no reply
Duration or Interval absent (implicitly 0)	Accepted
ReceivedStats outside 0–3	Dropped, no reply
StampAt outside 0–4	Dropped, no reply
Clock outside 1–3	Dropped, no reply
Length any value, including negative	Accepted (see Section 7.3)
DSCP any value, including negative or > 255	Accepted (see Section 7.3)
ServerFill string longer than 32 bytes	Dropped, no reply
ServerFill declared length exceeding the remaining payload	Dropped, no reply
Parameter payload far larger than any real request (200+ bytes of unknown tags tested)	Accepted

Protocol requirement. Unknown tags MUST be silently ignored. A malformed parameter payload MUST NOT produce a reply — a rejection reply would let an unauthenticated peer distinguish a live server from a firewall drop, which is contrary to the design of the authenticated mode.

Clarification. Upstream servers impose no 128-byte ceiling on incoming parameter payloads. A payload of over 200 bytes composed of unknown tags was accepted and answered normally. Any such limit in an implementation is a local buffer-sizing choice, not a protocol rule.

7.3 Server Restriction of Parameters

A server MAY reduce or replace requested parameters. The restricted values are what it returns in the open reply and what it enforces thereafter.

Observed restriction rules of upstream 0.9.1 (each is server policy, gated on the corresponding configuration knob):

Parameter	Restriction applied
ProtocolVersion	Always rewritten to 1 (see Section 7.5)
Duration	Clamped down to the configured maximum test duration, when one is set
Interval	Raised to the configured minimum interval, when one is set
Interval	Then clamped down to (idle timeout ÷ 4), when an idle timeout is set
Length	Clamped down to the configured maximum packet length, when one is set
StampAt	Reduced per the configured timestamp allowance (Section 11.4)
DSCP	Forced to 0 when DSCP is disallowed or unsupported on the socket
ServerFill	Replaced with the server's own default fill descriptor when the requested fill does not match the allow-list

Measured confirmations of the interval cap: idle timeout 4 s → maximum interval 1 s; 8 s → 2 s; 20 s → 5 s; 40 s → 10 s; 60 s → 15 s.

Interoperability note. The interval cap can reduce an interval below what the client asked for. Upstream clients enforce a hard floor of 1 second on a server-reduced interval and abort the session — in both strict and loose mode — when the returned interval is below it. A reduction to exactly 1 s is accepted in loose mode. A server whose idle timeout is below 4 s will therefore be unable to serve clients requesting a 1 s interval. Measured: idle timeout 2 s reduces 1 s → 500 ms and the client aborts; idle timeout 3 s reduces to 750 ms and the client aborts; idle timeout 4 s produces no reduction at all for a 1 s request.

Server-policy hazard. If the configured minimum interval is larger than (idle timeout ÷ 4), the negotiated interval is the smaller of the two while the enforced minimum remains the larger. A fully conforming client then sends at the negotiated interval and is rate-limited (Section 9.3). Observed with a 5 s minimum interval and an 8 s idle timeout: negotiated interval 2 s, but only the first request in each 5 s window was answered.

7.4 Open Reply

Direction: server → client.

Flags: Open (0x01) set, Reply (0x02) set, HMAC (0x08) set iff the server is authenticating, Close (0x04) set iff the request had it set (no-test) — see Section 7.5 for the one case where upstream does not set it.

Layout: magic (3) + flags (1) + [authentication (16)] + token (8) + restricted parameter payload.

Protocol requirement.

• The token field MUST be present in an open reply.
• For a session-creating open, the token MUST be non-zero. Clients treat a zero token without the Close flag as an error.
• The parameter payload MUST contain the restricted values — the values the server will actually enforce. Clients compare them field-by-field against what they requested and, by default, abort on any difference.
• Parameters whose restricted value is zero are omitted from the payload entirely; the client reconstructs them as zero.
• The open reply is not padded to the negotiated length. Its size is header + token + parameter payload.

Upstream 0.9.1 behavior. The open reply preserves whatever flags the request carried, adding Reply. There is no separate "reject" reply shape.

7.5 Protocol Version — Important Deviation

Upstream 0.9.1 behavior. The server does not reject a mismatched protocol version. Any value in the ProtocolVersion parameter — 0, 2, −1, or the tag omitted entirely — is silently rewritten to 1, a normal session is created, and the open reply carries ProtocolVersion = 1 with the Close flag clear. Verified by black-box test: requests with ProtocolVersion 0, 2 and −1 each produced a session-creating open reply.

Consequence: version mismatch is detected client-side only, by the client comparing the returned version against its own. A client speaking a future version would send its own version, receive 1, and abort locally.

Protocol requirement. A compatible server MUST return ProtocolVersion = 1 in the open reply so that version-1 clients accept the session. A compatible server MAY additionally reject unknown versions by replying with the Close flag set and a zero token; existing clients treat such a reply as a rejection and abort. Both behaviors are interoperable with version-1 clients; only the second is interoperable with a hypothetical future client that relies on server-side detection.

Do not assume that an upstream server will tell you your version is wrong.

7.6 Repeated and Retransmitted Opens

Upstream 0.9.1 behavior. Every open request creates a new, independent session with a fresh token. There is no deduplication of retransmitted opens and no per-endpoint session limit:

• two opens from the same source port yield two distinct tokens, and both remain usable simultaneously;
• an open request sent twice (as a client retransmission would) yields two distinct tokens; the client keeps only the token from the reply it processes, and the other session is orphaned;
• 1000 sequential opens from a single source endpoint all succeeded, all tokens were distinct, and the first, middle and last were all still usable afterwards.

Resource consequence (upstream policy). An orphaned session created by a retransmitted open never carries an echo request, and — under upstream's idle policy — a session that has never carried an echo request never expires (Section 18.2). On a lossy path, open retransmissions therefore accumulate permanent state.

Protocol requirement: none. Clients cannot observe orphaned sessions, and nothing about the behavior above is required for interoperability.

Robustness recommendation (clean implementation). Bound the lifetime of sessions that have never carried an echo request, so that open retransmissions cannot accumulate. See Section 18.3.

---

8. Session Identity and Tokens

8.1 What Identifies a Session

Protocol requirement. A post-open request is bound to a session by the token, and the server MUST additionally verify that it arrived from the same source endpoint the session was opened from.

Observed identity components, all of which must match:

Component	Must match
Token (64-bit, little-endian)	Yes
Source IP address	Yes
Source UDP port	Yes
IPv6 zone/scope, when present	Yes
Address family / listener	Yes — tokens are not shared between the IPv4 and IPv6 listeners of the same port

Observed outcomes:

Case	Result
Correct token, original endpoint	Served normally
Correct token, different source port, same IP	Dropped, no reply. Session left intact and still usable from the original port
Correct token, different address family	Dropped, no reply (different listener, unknown token there)
Unknown token	Dropped, no reply
Zero token	Dropped, no reply (treated as any other unknown token)
Token of a session already closed	Dropped, no reply
Close request bearing a valid token from a foreign source port	Dropped; the session is not closed

The last row matters: endpoint binding protects the close path as well as the echo path. A capture of these cases is in captures/server-session-identity.pcapng.

Practical consequence. Any NAT rebinding, source-port change, or address change during a session terminates it from the client's point of view — all subsequent packets go unanswered until the idle timeout reclaims the state. There is no rebinding or migration mechanism in protocol version 1.

8.2 Token Semantics

Property	Value
Width	64 bits
Encoding	Little-endian in the token field
Assigned by	Server, during open
Zero token	Reserved in practice: clients reject a zero token in a session-creating open reply, and a zero token is used in no-test replies (Section 16)
Uniqueness	MUST be unique among the server's live sessions in the scope where lookups occur
Lifetime	From open until close, policy limit, or idle expiry
Reuse	A token that has been released MAY be issued again later; no client-visible barrier exists

Protocol requirement. The server MUST echo the session token back in every reply it sends for that session.

Upstream 0.9.1 client behavior (informative). Upstream clients do not validate the token in echo replies — a reply carrying a wrong token was accepted and recorded. Do not rely on this: other implementations may validate, and matching the token is required by this specification.

Token generation is deliberately unspecified. A compatible implementation MAY choose any generation strategy that satisfies the uniqueness requirement. Because the token is the only thing standing between an off-path attacker and a usable session on a non-authenticated server, generating tokens from a cryptographically strong source is RECOMMENDED.

---

9. ECHO Processing

9.1 Echo Request

Direction: client → server.

Flags: Open clear, Reply clear, Close clear, HMAC set iff authenticating.

Layout: magic (3) + flags (1) + [authentication (16)] + token (8) + sequence number (4) + client padding to the negotiated length.

Protocol requirement. A server MUST read only the token and the 32-bit little-endian sequence number from a request. Everything after the sequence number is opaque to the server: clients place zeroed placeholders there so the request reaches the negotiated length, and a server MUST NOT interpret them.

Upstream 0.9.1 behavior. The datagram length of a request is not compared against the negotiated length. A 16-byte request on a session that negotiated 64 bytes is accepted and answered with a 64-byte reply. A request longer than the negotiated length is likewise accepted, and the reply is still the negotiated length.

9.2 Echo Reply

Direction: server → client.

Flags: Reply (0x02) set; HMAC (0x08) set iff authenticating; Close (0x04) set only in the server-initiated close case (Section 15.2). Open MUST be clear — upstream clients abort if an echo reply has the Open flag set.

Layout (fields in the order defined in the client specification, Section 8.1.3):

magic (3) | flags (1) | [auth (16)] | token (8) | sequence (4)
          | [received count (4)]      -- iff negotiated stats include "count"
          | [received window (8)]     -- iff negotiated stats include "window"
          | [timestamp fields]        -- per negotiated StampAt and Clock
          | payload padding to the negotiated length

Protocol requirement.

• The sequence number MUST be copied from the request unchanged.
• The token MUST be copied from the request unchanged.
• The reply length MUST be at least the length of the fields it contains, and SHOULD be exactly the negotiated length when that is larger.
• When the negotiated length is smaller than the field block (including the common case of a negotiated length of 0), the reply is the field block's length. Measured: a session negotiating length 0 or 20 with full statistics and dual timestamps on both clocks produced 60-byte replies.

Writing normal_header for the block of fields the negotiated parameters imply:

compatible_reply_len = max(negotiated_length, normal_header)

For StampAt = Midpoint with a single negotiated clock, upstream 0.9.1 emits one 8-byte timestamp field more than the negotiated parameters imply, which changes the reply length in exactly the cases where the field block wins. See Section 11.3.1.

Upstream 0.9.1 behavior — reply length is capped by the local interface MTU. The negotiated length is echoed back to the client unchanged, but the actual reply datagram is truncated to the detected MTU of the listener's interface. Measured on a 1500-byte-MTU interface: negotiated 1501, 2000, 3000 and 8000 all produced 1500-byte replies, while the open reply still reported the requested value. Upstream clients treat a reply shorter than the negotiated length as a fatal error, so this configuration fails on the first echo. See Section 22.

9.3 Rate Limiting

Server policy. The reference server enforces the negotiated minimum send interval with a token-bucket allowance:

• a burst allowance of N requests is available immediately (default N = 5);
• allowance is replenished at one request per configured minimum interval and is capped at N;
• a request arriving with no allowance is dropped without a reply.

Measured with a 100 ms minimum interval and a burst of 5: a blast of 12 requests produced exactly 5 replies; after a 600 ms pause, the next 3 spaced requests were all answered. With a burst of 1, a blast of 4 produced 1 reply.

Protocol requirement. A rate-limited request MUST NOT be answered and MUST NOT affect the reception statistics (Section 10). Measured: the received count advanced 1, 2, 3, 4, 5 across the accepted burst and continued 6, 7, 8 for the later requests — dropped requests were not counted.

9.4 Maximum Request Length

Server policy. When a maximum packet length is configured, a request whose datagram length exceeds it is dropped without a reply. Measured with a maximum of 64: 16-, 32- and 64-byte requests were answered with 64-byte replies; 65- and 100-byte requests were dropped.

The maximum applies to echo requests only. An open request larger than the maximum was still accepted and answered.

If the configured maximum is below the minimum echo field block, every echo request is dropped while opens still succeed. Measured with a maximum of 10: the session opened, negotiated a length of 10, and every 16-byte echo request was dropped.

---

10. Sequence Handling and Received Statistics

This section is the most behaviorally distinctive part of the server and is specified strictly as input → observed output. The reference implementation's observable semantics differ from a naive reading of "a 64-packet reception bitmap", and clients depend on the observed behavior.

10.1 Received Count

Property	Value
Field width	32 bits, little-endian
Present when	Negotiated ReceivedStats includes "count" (values 1 or 3)
Initial value	0 at session creation; the first accepted request is answered with 1
Scope	Per session. A new session starts at 0 again
Counts	Every echo request that reaches the reply stage
Does not count	Requests dropped for bad magic, bad flags, bad authentication, unknown token, endpoint mismatch, oversize, or rate limiting
Duplicates	Counted. A repeated sequence number increments the count
Reordered / late requests	Counted
Close and open requests	Not counted

Protocol requirement. The count reported in a reply MUST include the request being answered.

Wraparound. The field is 32 bits. Behavior at 2^32 requests in one session was not observed and is listed in Section 23.

10.2 Received Window

Property	Value
Field width	64 bits, little-endian
Present when	Negotiated ReceivedStats includes "window" (values 2 or 3)
Bit 0 (LSB)	The request being answered
Bit k	The request with sequence number (current − k), for 1 ≤ k ≤ 63
Set bit	That sequence number was received by the server in this session
Initial value	0 at session creation

Observed upstream 0.9.1 semantics. The table below is a summary of the measured input → output vectors in test-vectors/SERVER_BEHAVIORAL_VECTORS.md Section 1, expressed as a relation between two values a client can see on the wire: the window in the previous reply and the window in the next one. It is a description of observed output, not a prescription of how to compute it — any method producing these values is conformant.

Let S be the sequence number of the incoming request, L the sequence number carried by the previous accepted request of the session, W the window value carried by the previous reply (W = 0 before the session's first request), and

Δ = (S − L) mod 2^32          -- unsigned 32-bit difference

Three cases account for every observed vector:

Condition	Resulting window
Δ = 0	W | 1
1 ≤ Δ ≤ 63	(W << Δ) | 1
Δ ≥ 64	0x1

Read through the cases a client actually encounters:

Situation	Δ	Resulting window
First request of a session	any	0x1 (because W is 0)
In order, no gap	1	(W << 1) | 1
Duplicate of the most recent sequence number	0	W, unchanged
Gap ahead, within range	2 … 63	(W << Δ) | 1
Gap ahead of 64 or more	≥ 64	0x1
Out of order / late arrival	large, because the unsigned difference wraps	0x1

The last two rows are the critical ones. Because the difference is unsigned, a sequence number lower than the previous one produces a very large Δ and therefore falls into the third case. A late or reordered request does not set a historical bit; it resets the window to 0x1. The information that earlier packets were received is lost, and it is not recovered by later packets — the window rebuilds from scratch.

Protocol requirement. Bit 0 is always set in a window a server emits. A compatible server MUST set bit 0. Consequently a window value of 0 is never produced by upstream 0.9.1 when the window field is negotiated at all; clients MAY continue to treat 0 defensively as "no information".

Client-facing consequence, and why this must be stated. A window of 0x1 is a valid window that carries no information about earlier packets. It does not mean the previous 63 sequence numbers were lost; it means no useful prior received-history is represented in the window after the transition that produced it. A client that reads 0x1 literally will classify up to 63 earlier packets as lost upstream after a single reordering event or after any gap of 64 or more. Implementations of either side SHOULD treat 0x1 on a non-first packet as "no historical information available" rather than "nothing earlier was received".

This is a statement about what the window represents. How a client turns window bits into an upstream/downstream loss classification is a separate question, out of scope here, and is scheduled for its own audit on the clean side; nothing in this section should be read as settling it.

Sequence wraparound. The comparison is modular over 32 bits, so a session that crosses the u32 boundary continues normally. Measured with sequence numbers 4294967293, 4294967294, 4294967295, 0, 1: windows advanced 0x1, 0x3, 0x7, 0xf, 0x1f with counts 1…5, exactly as for a non-wrapping run.

Sequence numbers need not start at 0. A session whose first request carries sequence 100 behaves identically to one starting at 0: window 0x1, then 0x3, then 0x7.

10.3 Behavioral Vectors

See test-vectors/SERVER_BEHAVIORAL_VECTORS.md for the full input → output tables, and captures/server-recv-window.pcapng for a capture of the gap / duplicate / reorder / far-gap sequence.

---

11. Timestamp Semantics

11.1 What Each Field Means

Negotiated StampAt	Fields emitted	Instant represented
None (0)	none	—
Send (1)	send wall and/or send monotonic	The server's departure instant for this reply
Receive (2)	receive wall and/or receive monotonic	The server's arrival instant for this request
Both (3)	receive and send fields	Both of the above
Midpoint (4)	midpoint fields	The arithmetic mean of the receive and send instants

The externally relevant property is the relationship between the two instants, not where in a server's internals they are taken. The pair must bracket the server's own handling of the request as tightly as the implementation can manage, so that the difference between them is a usable estimate of server processing time and the client's round-trip correction is not systematically wrong. How closely a given implementation can bracket that interval is not externally observable; see Section 23.7.

Protocol requirement. The receive instant MUST NOT be later than the send instant for the same reply. Measured server-side processing durations on loopback were on the order of a few microseconds.

11.2 Clock Encodings

Clock	Field	Encoding
Wall	wall fields	Signed 64-bit little-endian, nanoseconds since the Unix epoch
Monotonic	monotonic fields	Signed 64-bit little-endian, nanoseconds since an arbitrary server-chosen origin

Observed monotonic origin. The origin is fixed for the life of the server process and is shared by every session and every listener of that process. Two sessions opened seconds apart on different address families reported monotonic values differing by exactly the elapsed wall time between them, and values tracked the server process's uptime. A client therefore MUST NOT assume the origin is per-session, and MUST NOT compare monotonic values against its own clock — only differences between two server monotonic values from the same server are meaningful.

Protocol requirement. A compatible server MAY choose any monotonic origin, provided it is stable for as long as any session it reports into may live.

11.3 Absent Fields

A timestamp field that is not negotiated is simply not present in the reply; it is not zero-filled. Field presence is positional — receivers derive offsets from the negotiated parameters, not from the packet.

11.3.1 Upstream 0.9.1 — Dual-Field Midpoint Wire Representation

Black-box observed. For StampAt = Midpoint, upstream 0.9.1 emits the midpoint as two 8-byte timestamp fields — the midpoint wall field followed by the midpoint monotonic field, in that order — even when the negotiated Clock selects only one clock. The midpoint occupies that fixed two-field, 16-byte region whenever it is present at all, so a single-clock midpoint reply carries one 8-byte field more than the negotiated parameters imply.

This is a statement about bytes on the wire. It says nothing about how upstream represents a midpoint internally, and nothing in this section depends on any such model.

Which negotiations are affected.

StampAt	Clock	Midpoint region on the wire
Midpoint (4)	Wall (1)	wall + monotonic — one field more than negotiated
Midpoint (4)	Monotonic (2)	wall + monotonic — one field more than negotiated
Midpoint (4)	Both (3)	wall + monotonic — matches the negotiated layout

Receive-only, send-only and both-timestamp modes are not affected: each of those emits exactly the fields the negotiated Clock implies, for all three Clock values. Measured for all 15 StampAt × Clock combinations; only the two single-clock midpoint rows deviate.

A client can reach this configuration without asking for midpoint timestamps: a server restricted to a single timestamp answers a request for both receive and send with Midpoint (Section 11.4), so a Wall-only client that requested StampAt = Both also receives the dual-field form.

Effect on reply length. The extra field enlarges the minimum reply length; it does not add 8 bytes to every reply. Reply length follows the ordinary rule of Section 9.2 — the larger of the negotiated length and the field block — applied to a field block one timestamp field larger. Writing normal_header for the block of fields the negotiated parameters imply:

normal_header   = negotiated field block
upstream_header = normal_header + one 8-byte timestamp field

compatible_reply_len    = max(negotiated_length, normal_header)
upstream_0_9_1_reply_len = max(negotiated_length, upstream_header)

The observable excess is therefore upstream_0_9_1_reply_len − compatible_reply_len, which takes one of three forms depending on the negotiated length:

Negotiated length	Upstream 0.9.1 reply	Excess over a compatible server
≤ normal_header	upstream_header	+8
between normal_header and upstream_header	upstream_header	+7 … +1, shrinking as the negotiated length rises
≥ upstream_header	exactly the negotiated length	0 — the extra field displaces 8 bytes of payload

Read the excess column across rows, not within one session: for any single set of negotiated Params the upstream reply has exactly one length, upstream_0_9_1_reply_len. The +8, +7…+1 and 0 values are what that one length works out to under different negotiations. No negotiation admits a range of lengths.

Measured with ReceivedStats = Both, StampAt = Midpoint, Clock = Wall (normal_header 36, upstream_header 44):

Negotiated length	0	16	32	36	37	40	43	44	45	64	1024	4096
Reply datagram	44	44	44	44	44	44	44	44	45	64	1024	4096
Excess	+8	+8	+8	+8	+7	+4	+1	0	0	0	0	0

The same pattern was measured for ReceivedStats = None, Count and Window, with the two minima shifting accordingly (24/32, 28/36 and 32/40 respectively). At a negotiated length of 4096 the midpoint region still contains both fields, followed by fill — so the dual-field emission is unconditional, and only its effect on the total datagram length depends on the negotiated length.

Correction to earlier material. Any statement that an upstream reply is "the negotiated length plus 8 bytes", or "the normal packet length plus 8", is wrong as a general claim. It holds only in the first regime above. For sufficiently large negotiated packets the datagram length is exactly the negotiated length, and the excess field is visible only as displaced payload.

Effect on the values a positional decoder reads. Field offsets are derived from the negotiated parameters, and the extra field is the last field before the payload. The two forms compare as follows:

Clock = Wall
  conforming single-clock form:   [midpoint_wall][payload...]
  upstream 0.9.1 form:            [midpoint_wall][midpoint_mono][payload...]

Clock = Monotonic
  conforming single-clock form:   [midpoint_mono][payload...]
  upstream 0.9.1 form:            [midpoint_wall][midpoint_mono][payload...]

• Clock = Wall: the negotiated field comes first in both forms, so an ordinary positional decoder reads the correct value.
• Clock = Monotonic: an ordinary positional decoder reads the first 8-byte region — which upstream fills with the wall-domain value — as the negotiated monotonic timestamp. Black-box verified with the upstream client: a 0.9.1 client requesting monotonic-only midpoint reported server monotonic timestamps of approximately 1.79 × 10¹⁸ ns — a nanoseconds-since-epoch magnitude, not a process-relative one — and completed the test without error.

The two forms are not generally distinguishable. Once the negotiated length reaches upstream_header, the equality

upstream_0_9_1_reply_len == compatible_reply_len

holds, and the conforming and upstream forms produce datagrams of identical length:

conforming:   [mono][payload...]
upstream:     [wall][mono][payload...]

In that regime nothing in the datagram identifies which form was used. The eight bytes following the first midpoint region are a monotonic timestamp under the upstream form and ordinary payload under a conforming one. This ambiguity is recorded here as a limitation, not resolved: no heuristic for telling the two apart in the equal-length regime has been established, and this document does not invent one.

Version behavior. Black-box measured: upstream 0.9.0 emits only the negotiated midpoint field for a single clock (a monotonic-only midpoint reply carries a process-relative value at the negotiated length). The dual-field form appears in 0.9.1 and is unchanged in the tested post-0.9.1 development tree (Section 21).

Source-assisted historical conclusion (non-normative). Contaminated-side investigation of upstream's release history indicates that the difference between 0.9.0 and 0.9.1 recorded above is an unintended regression rather than a designed protocol feature. This is a judgement reached with access to upstream material on the contaminated side; it is not an independent observation, and the measured 0.9.0-versus-0.9.1 difference stated above does not by itself establish intent. Nothing in upstream's published release notes or documentation refers to the behavior. No requirement below depends on this paragraph, and a reader who discards it entirely loses nothing normative.

Protocol requirement.

• A compatible server SHOULD emit exactly the fields implied by the negotiated StampAt and Clock, including for midpoint. Emitting the conforming form is known to interoperate: a contaminated-side server built to emit only the negotiated midpoint field was driven by the upstream 0.9.1 client for Wall-only, Monotonic-only and dual-clock midpoint configurations, and the client — an independent implementation — completed every run cleanly.
• A compatible client MUST tolerate the verified upstream single-clock midpoint dual-field form. Specifically, when the negotiated parameters are StampAt = Midpoint with a single Clock, it MUST accept a reply whose length is exactly upstream_0_9_1_reply_len. It MUST NOT require the extra field to be present, and it MUST NOT treat its presence as an error.
• That tolerance is a single additional accepted length, not a range. For any one set of negotiated Params, compatible_reply_len and upstream_0_9_1_reply_len are two fixed numbers, and those are the only two lengths an echo reply may have. When upstream_0_9_1_reply_len > compatible_reply_len the upstream form is identifiable by length alone, and the difference between the two values is between 1 and 8 bytes. The +8, +7…+1 and 0 figures in the excess table earlier in this section are differences across different negotiations; they are not a range of acceptable lengths within one negotiation. A client MUST NOT apply a rule of the form "accept anything up to 8 bytes over", and MUST reject a length strictly between compatible_reply_len and upstream_0_9_1_reply_len exactly as it rejects any other unexpected length.
• The tolerance is otherwise narrow and specific. It is not a general rule that replies longer than expected are valid, and it does not license accepting arbitrary overlong echo replies. A compatible client MUST continue to reject replies shorter than compatible_reply_len — the normal compatible reply length, which is the larger of the negotiated Length and the mandatory field block, not the negotiated Length on its own — and MUST continue to apply its ordinary strict validation to every other malformed or unexpectedly sized datagram.
• A client that negotiates monotonic-only midpoint MAY read its monotonic value from the second 8-byte region of the midpoint area only when the dual-field form is otherwise identifiable — that is, when upstream_0_9_1_reply_len > compatible_reply_len for the negotiated Params and the datagram length is exactly upstream_0_9_1_reply_len, which happens only while the negotiated length is below upstream_header. A client MUST NOT apply that correction unconditionally whenever midpoint and monotonic are negotiated: in the equal-length regime it would interpret ordinary payload bytes from a conforming server as a timestamp.
• In the equal-length regime a client SHOULD record the value as ambiguous rather than guess. Whatever it decides, it MUST still accept the packet: a reply is not to be rejected merely because upstream might have produced the ambiguous form, and a client that applies no correction MUST NOT fail on the resulting implausible value.
• All of the above constrains a client. None of it is a licence, or a requirement, for a clean implementation's server to emit the extra field.

Accepted echo reply lengths, in full. For a given set of negotiated Params, compute compatible_reply_len and upstream_0_9_1_reply_len once. A conforming client then accepts exactly these lengths and no others:

Received packet_len	Condition	Outcome
== compatible_reply_len	always	accepted — the normal exact form
== upstream_0_9_1_reply_len	single-clock Midpoint and upstream_0_9_1_reply_len > compatible_reply_len	accepted — the identifiable upstream midpoint compatibility form
any other value	—	rejected

When upstream_0_9_1_reply_len == compatible_reply_len the two rows collapse: the packet is accepted at the normal exact length, the wire form is ambiguous between [mono][payload…] and [wall][mono][payload…], and no generic monotonic correction is applied. This is behavioral wording; it prescribes no particular decoder structure.

11.4 Timestamp Allowance (Server Policy)

The reference server can restrict which timestamp modes it will provide. The observed mapping from requested StampAt to negotiated StampAt:

Requested	Allowance = dual	Allowance = single	Allowance = none
None (0)	0	0	0
Send (1)	1	1	0
Receive (2)	2	2	0
Both (3)	3	4 (midpoint)	0
Midpoint (4)	4	4	0

Note the substitution: under a single-timestamp allowance, a request for both receive and send is answered with midpoint, not with one of the two. Clients comparing negotiated against requested parameters will see this as a server restriction.

---

12. Server Timing Relationships

A server's timestamps exist so a client can separate server processing time from network time. The relationships a compatible server MUST make derivable:

server_processing = server_send − server_receive          (both from the same clock)
adjusted_rtt      = raw_client_rtt − server_processing
send_delay        = server_best_receive_wall − client_send_wall
receive_delay     = client_receive_wall − server_best_send_wall

where best receive is the receive timestamp when present, otherwise the send timestamp, and symmetrically for best send. For midpoint timestamps both resolve to the midpoint value, which makes server_processing identically zero — measured: an upstream client using midpoint timestamps reports a server processing time of 0 s in all four statistics.

Protocol requirement.

• When both receive and send timestamps are negotiated, they MUST be taken from the same clock domain, and MUST bracket the server's own handling of that request.
• One-way delays are only meaningful with externally synchronized wall clocks; a server has no obligation beyond reporting its own wall clock honestly.
• A server MUST NOT rewrite or smooth timestamps between packets.

Client-side statistics (IPDV, loss classification, aggregate reporting) are out of scope here; see the client specification, Section 12.

---

13. Server Fill and Payload

13.1 What the Payload Is

Everything after the last present field in a reply, up to the reply's length, is payload. Its content carries no protocol meaning; it exists to reach the negotiated packet length.

13.2 Fill Negotiation

The ServerFill parameter (tag 9) is a length-prefixed UTF-8 string, maximum 32 bytes. Observed descriptor forms:

Descriptor	Meaning
absent / empty	Client expresses no preference; the server uses its own configured fill
none	Do not fill; see Section 13.4
rand	Fill with random bytes
pattern:HH…	Fill with the repeating byte pattern given as hex

Server policy. The reference server matches the requested descriptor against an allow-list of glob patterns (default: rand only). A descriptor that does not match is replaced with the server's default fill descriptor, which is returned to the client in the open reply.

Measured on a default-configuration server:

Requested	Negotiated value returned	Actual reply payload
rand	rand	random bytes
none	pattern:69727474	repeating 69 72 74 74
pattern:aabb	pattern:69727474	repeating 69 72 74 74
bogus	pattern:69727474	repeating 69 72 74 74
32-byte string	pattern:69727474	repeating 69 72 74 74
33-byte string	—	open dropped, no reply

Note. The descriptor returned on refusal is the server's default fill descriptor and does not necessarily describe the bytes the server will actually send — a server configured with a different fill still returns the default descriptor while filling with its configured fill. Clients MUST NOT rely on the returned descriptor to predict payload bytes.

With a permissive allow-list, requested descriptors are honored and returned verbatim: pattern:aabb produced aa bb aa bb …, pattern:00 produced zeros, pattern:ff00 produced ff 00 ff 00 …. An unparseable hex body (pattern:zz) falls back to the server default and returns pattern:69727474.

13.3 Default Fill Bytes and Pattern Phase

Upstream 0.9.1 behavior. The default fill is the repeating four-byte pattern 69 72 74 74. The pattern's phase is not reset per packet or per session; it advances continuously as bytes are consumed. Observed across four consecutive replies with a 7-byte payload on one session:

seq 0 payload: 72 74 74 69 72 74 74
seq 1 payload: 69 72 74 74 69 72 74
seq 2 payload: 74 69 72 74 74 69 72
seq 3 payload: 74 74 69 72 74 74 69

and across separate sessions on the same listener, the phase carried over.

Protocol requirement. A client MUST NOT assume a reply payload begins at the start of the fill pattern, and MUST NOT use payload bytes for any protocol purpose. A compatible server MAY reset the phase per packet.

13.4 No Fill

Upstream 0.9.1 behavior. When the effective fill is none, no bytes are written into the payload region. The bytes that appear there are unspecified residual buffer content. In practice:

• when the request was at least as long as the reply, the client's own request payload is returned;
• when the request was shorter, the trailing bytes are residue from earlier traffic on that listener — observed to include fragments of a previous packet's parameter payload.

The reference server's own documentation describes none as insecure on public servers, and its default allow-list excludes it.

Protocol requirement. A compatible server that supports a no-fill mode MUST NOT emit residual bytes from other clients' traffic. Zero-filling or echoing only the bytes actually supplied by the requester are both acceptable.

13.5 Interaction with Length and Authentication

• The payload region is what remains after all present fields. Enabling authentication consumes 16 bytes of the packet, reducing the payload for the same negotiated length.
• If the negotiated length is smaller than the field block, there is no payload.
• The fill is applied after all fields are written, so it never overwrites protocol data.

---

14. Authentication (HMAC)

14.1 Mechanism

When a server is configured with a key, an authentication field of 16 bytes immediately follows the flags byte in every packet in both directions, and the HMAC flag (0x08) is set.

The MAC is HMAC-MD5 over the entire datagram with the 16-byte authentication field zeroed, exactly as specified in the client specification, Section 13.4. A server computes and verifies it identically.

Protocol requirement. A server that is authenticating MUST set the HMAC flag and write a valid MAC in every reply it sends, including echo replies. This was verified the hard way: a server that authenticated open replies correctly but omitted the HMAC flag from echo replies caused every echo reply to be discarded by the upstream client, which then terminated abnormally with no packets received.

14.2 Observed Behavior on Authentication Failure

Every case below results in a silent drop: no reply of any kind, and no change to any session's state.

Condition (server has a key)	Result
Request has no HMAC flag and no field	Dropped
Request has the HMAC flag, MAC computed with a different key	Dropped
Request has the HMAC flag, one bit flipped in the MAC	Dropped
Request has the HMAC flag, MAC field all zeros	Dropped
Request too short to contain the MAC field (< 20 bytes)	Dropped
MAC field truncated (field shortened, rest shifted)	Dropped
MAC computed correctly but the HMAC flag cleared	Dropped
Valid open, valid echo, valid close	Served normally

Condition (server has no key)	Result
Request has the HMAC flag set	Dropped

Protocol requirement. Authentication failure MUST NOT produce a reply. A server MUST reject a packet whose HMAC flag disagrees with its own configuration, in both directions of mismatch. MAC comparison SHOULD be constant-time.

Applies to all three request kinds: open, echo, and close. An unauthenticated close request cannot tear down an authenticated session.

Indistinguishability. An authentication failure is externally indistinguishable from every other drop: a packet bearing a valid token with a bad MAC produces exactly the same silence as one bearing an unknown token.

Protocol requirement. A compatible server MUST NOT allow the result of a session lookup to leak through its reply behavior for a packet that failed authentication. Otherwise an unauthenticated peer could probe for live tokens.

14.3 Session Effect

An authentication failure leaves the session completely untouched. Measured: a sequence of eight malformed or wrongly-keyed packets against a live session was followed by a correctly authenticated echo that was served normally, with the received count advancing only for the accepted packets.

---

15. CLOSE Lifecycle

15.1 Client-Initiated Close

Request. Direction client → server.

Flags: Close (0x04) set, Reply clear, Open clear, HMAC set iff authenticating.

Layout: magic (3) + flags (1) + [authentication (16)] + token (8). Total 12 bytes unauthenticated, 28 bytes authenticated. There is no sequence number and no payload.

Observed server behavior:

Event	Result
Valid close from the session's endpoint	Session removed. No reply of any kind is sent.
Trailing bytes after the token	Accepted; session removed
Repeated close with the same token	Dropped as an unknown token; no reply
Echo after close	Dropped as an unknown token; no reply
Close from a foreign source port	Dropped; session not removed
Close bearing an unknown or zero token	Dropped; no reply

Protocol requirement. A server MUST accept the close request and release the session. It MUST NOT be expected to reply, and a compatible server that sends nothing is fully conformant.

• Upstream 0.9.1 sends no reply at all to a normal client close. Verified in captures/server-close-lifecycle.pcapng, where the close request is the last packet in the exchange.
• Once the session is gone, a repeated close or a post-close echo is handled the same way as any unknown or stale token: silently discarded, no reply.
• A standalone Reply|Close datagram is tolerated by upstream clients but has no demonstrated purpose in protocol version 1. As a one-off experiment, an upstream client was driven against a server that answered close with magic + flags(Reply|Close) + [auth] + token; the run completed normally with correct results and nothing in the client's output changed, showing no sign the reply had been used. That establishes only that such a datagram is harmless.

No production standalone close-reply codec is specified here. Because no version-1 client has been shown to do anything with such a datagram, this document does not define one as required — or even as recommended — behavior. An implementation that wants to emit one is not prohibited from doing so, but it gains nothing observable and should not treat the shape above as a normative encoding.

The exact point at which the session becomes unavailable is the moment the close request is processed. The client has no acknowledgement and therefore no way to distinguish "close delivered" from "close lost"; a lost close leaves the session to be reclaimed by idle expiry (Section 18).

15.2 Server-Initiated Close

When it happens. A server signals close by setting the Close flag (0x04) on an otherwise ordinary echo reply. There is no standalone server-initiated close packet in protocol version 1.

Upstream 0.9.1 behavior. The single observed trigger is the maximum test duration hard limit:

• when a maximum test duration is configured, the server clamps the negotiated duration to it during negotiation;
• it additionally enforces a hard deadline of maximum duration + 2 seconds, measured from the first echo request of the session;
• the first echo request arriving after that deadline is answered with a normal, complete echo reply — correct sequence number, token, statistics and timestamps — with the Close flag additionally set;
• the session is removed at the same time, so every later request is dropped as an unknown token.

Measured: maximum duration 1 s → close flag on the reply at 3.01 s after the first echo; maximum duration 2 s → close flag at 4.06 s and again at 4.1 s in a separate run. Captured in captures/server-close.pcapng (frame 36 carries flags 0x06).

A conforming client never reaches this deadline, because it stops sending at the negotiated duration. The mechanism exists to bound sessions from clients that ignore the negotiated duration.

Observed client reaction. An upstream 0.9.1 client that receives an echo reply with the Close flag set:

1. does not record that reply's measurement;
2. terminates the run immediately, reporting a "server closed connection" condition;
3. prints the partial results gathered up to that point and exits with a success status;
4. sends its own close request for the session.

Protocol requirement.

• A server that terminates a session mid-test MUST do so by setting the Close flag on an echo reply; there is no other in-band mechanism.
• The close-flagged reply MUST otherwise be a well-formed echo reply for the request that triggered it — clients parse it before noticing the flag.
• A server MUST NOT expect an acknowledgement. The client's subsequent close request will be dropped as an unknown token, which is normal and harmless.
• The close-flagged reply MUST be authenticated when the session is authenticated.
• The session token MUST be released at the same time; it MUST NOT remain usable after a close-flagged reply.

---

16. No-Test Mode

A client may open and immediately close a session without running a test, in order to validate parameters against a server.

Request: an open request with both Open (0x01) and Close (0x04) set.

Reply: Open | Reply | Close (0x07, or 0x0F with authentication), a zero token, and the fully restricted parameter payload.

Observed properties:

Property	Result
Session state created	None. No token is issued and nothing is retained
Token in the reply	All zeros
Parameters in the reply	The same restricted values a real open would return
Subsequent echo with the zero token	Dropped, no reply
Subsequent close with the zero token	Dropped, no reply
With authentication	Reply is authenticated normally; flags 0x0F
Cleanup required	None

Protocol requirement. A server MUST NOT create a usable session for a no-test open, and MUST return a zero token. The Close flag in the reply here means "acknowledged and finished", not "rejected"; the distinction is made by the client from whether it set Close in the request. See the client specification, Sections 6.2 and 8.3.

---

17. Malformed, Unexpected and Adversarial Packets

Compact reference table. "Session effect: none" means the referenced session (if any) is left fully usable.

Request condition	Session state	Auth state	Server response	Session effect
Datagram shorter than the fixed header	any	any	drop	none
Bad magic	any	any	drop	none
Any reserved flag bit set (flags > 0x0F)	any	any	drop	none
Reply flag set	any	any	drop	none
HMAC flag set, server has no key	any	n/a	drop	none
No HMAC flag, server has a key	any	fail	drop	none
Wrong / corrupted / zeroed / truncated MAC	any	fail	drop	none
Open, truncated parameter varint	n/a	ok	drop	none
Open, duration ≤ 0 or interval ≤ 0	n/a	ok	drop	none
Open, out-of-range stats / stamp-at / clock enum	n/a	ok	drop	none
Open, server-fill string > 32 bytes or short buffer	n/a	ok	drop	none
Open, unknown parameter tags	n/a	ok	open reply, tags ignored	new session
Open, empty parameter payload	n/a	ok	open reply	new session
Open, protocol version ≠ 1	n/a	ok	open reply with version 1	new session
Open with Close flag (no-test)	n/a	ok	reply, zero token	none created
Non-open, too short for the token	any	ok	drop	none
Non-open, unknown token	—	ok	drop	none
Non-open, zero token	—	ok	drop	none
Echo, correct token, foreign source port	live	ok	drop	none
Close, correct token, foreign source port	live	ok	drop	none — stays open
Echo, too short for the sequence number	live	ok	drop	none
Echo exceeding the configured maximum length	live	ok	drop	none
Echo arriving faster than the rate allowance	live	ok	drop	none
Echo with trailing bytes past the negotiated length	live	ok	reply at negotiated length	normal
Echo shorter than the negotiated length	live	ok	reply at negotiated length	normal
Echo with a duplicate sequence number	live	ok	reply	count +1, window unchanged
Echo with a lower sequence number than the last	live	ok	reply	count +1, window reset to 0x1
Echo after the maximum-duration deadline	live	ok	reply with Close flag	session removed
Echo after idle expiry deadline	expired	ok	reply (served once)	session removed
Any request on a closed / expired session	gone	ok	drop	none
Close with trailing bytes	live	ok	accepted; no reply, as for any close	session removed
Echo-shaped datagram with the Open flag set, otherwise admissible	—	ok	treated as an open; the token bytes are parsed as parameters	new session if those bytes parse
Open flag set together with the Reply flag, or with an undefined flag bit	any	any	drop	none

The last row restates the observable precedence of Section 5.4 in its narrow form: for an otherwise admissible datagram, Open interpretation wins over Close interpretation and over an echo-shaped body, so an echo-shaped datagram with the Open flag set produces an open reply rather than an echo reply. That precedence does not override the drop rows above — a datagram carrying the Open flag is still dropped when the Reply flag is set, when an undefined flag bit is set, on an authentication failure, or when its Open parameter payload is malformed or out of range. A compatible server SHOULD behave the same way, so that a client's retransmitted open is never mistaken for an echo.

---

18. Session Lifetime and Resource Policy

18.1 Lifetime Events

Event	Effect
Open (non-no-test)	Session created, token issued
Open with Close (no-test)	No session created
Client close from the bound endpoint	Session removed immediately, no reply
Maximum test duration exceeded	Close-flagged echo reply, session removed (Section 15.2)
Idle expiry	Session removed (Section 18.2)
Server shutdown	All sessions gone, no notification
Client disappears	Nothing until idle expiry

18.2 Idle Expiry — Observed Semantics

Server policy. The reference server has a configurable idle timeout, default 1 minute, with 0 meaning "never expire".

Observed behavior, measured with a 2-second idle timeout:

Gap since the previous accepted echo	First request after the gap	The request after that
5.0 s	answered	answered
6.5 s	answered	answered
6.9 s	answered	answered
7.1 s	answered	dropped
7.5 s	answered	dropped
9.0 s	answered	dropped

Two things follow, and both are externally observable:

1. The effective expiry deadline is the configured idle timeout plus a 5-second grace period. Measured boundary between 6.9 s and 7.1 s for a 2-second timeout.
2. The first request that arrives after the deadline is still answered, and the session is torn down as part of handling it. Only the next request is dropped. A compatible implementation MAY drop the first post-deadline request instead; clients cannot depend on either behavior, because from their side the deadline coincides with an unresponsive server.

Upstream 0.9.1 behavior — a session that has never carried an echo request never expires. The idle clock starts at the first echo request, not at open. Measured with a 2-second idle timeout: a session opened and left idle for 9 seconds with no echo request was still served afterwards. See Section 7.6 for why this matters (open retransmissions).

Protocol requirement. Expiry itself is entirely server policy, and a compatible server MAY choose any deadline or none. The one interoperability constraint is negative: a server MUST NOT signal expiry to the client — the client observes it only as silence.

Robustness recommendation (clean implementation). Apply an expiry deadline to sessions that have never carried an echo request as well, rather than leaving them resident indefinitely as upstream does.

Requests dropped for rate limiting still refresh the idle clock, so a client sending faster than the allowance keeps its session alive without receiving replies.

18.3 Resource Limits

Observed upstream 0.9.1 policy. The table below records what the reference server was seen to do with its default configuration. Every row is an observation about upstream's policy, not a protocol rule, and none of it is behavior a compatible server is expected to reproduce.

Limit	Observed
Maximum concurrent sessions	None observed. 1000 sessions from one source endpoint all succeeded and all remained usable
Per-peer session limit	None
Per-peer or global request rate limit	None beyond the per-session minimum-interval allowance
Maximum request length	Only if configured; unlimited by default
Maximum test duration	Only if configured; unlimited by default
Server-fill descriptor length	32 bytes (hard)

Protocol requirement. None. Nothing here is observable to a conforming client, and a compatible server MAY impose session caps, per-peer caps and admission limits freely. Because the protocol has no rejection reply, the only way to refuse is to drop — a client hitting a cap sees an open timeout, which it already has to tolerate.

Explicitly not an interoperability requirement. Upstream's absence of session and per-peer bounds is an observed policy choice. It is not something a compatible irtt-rs server should reproduce, and reproducing it would not improve interoperability by any measure.

Robustness recommendation (clean implementation). A session is created by a single unauthenticated datagram, opens are never deduplicated, and upstream never expires a session that has not carried an echo request. The clean irtt-rs server is therefore expected to operate under a bounded resource policy: bounded total session state, and an expiry deadline that also covers never-used sessions. The specific limits, the eviction strategy and the shape of that policy are a clean-project design decision and are deliberately not prescribed here.

---

19. Protocol-Visible Limits and Defaults

Values marked (protocol) are fixed by the wire format. Values marked (policy) are the reference server's defaults and are freely changeable by a compatible implementation.

Item	Value	Kind
Magic	0x14 0xA7 0x5B	protocol
Flag bits defined	0x01 Open, 0x02 Reply, 0x04 Close, 0x08 HMAC	protocol
Reserved flag bits	0x10–0x80, must be zero	protocol
Token width	64 bits, little-endian	protocol
Sequence width	32 bits, little-endian, wraps modularly	protocol
Received count width	32 bits, little-endian	protocol
Received window width	64 bits, little-endian, bit 0 = current	protocol
Timestamp width	64 bits signed, little-endian, nanoseconds	protocol
Authentication field	16 bytes, HMAC-MD5, packet-wide with the field zeroed	protocol
Server-fill descriptor maximum	32 bytes	protocol
Protocol version	1	protocol
Default port	2112	policy
Default minimum send interval	10 ms	policy
Default burst allowance	5 requests	policy
Default idle timeout	1 minute	policy
Idle-expiry grace beyond the timeout	5 seconds (measured)	policy
Maximum negotiable interval	idle timeout ÷ 4 (measured)	policy
Maximum-duration grace	2 seconds (measured)	policy
Default maximum test duration	unlimited	policy
Default maximum packet length	unlimited	policy
Default fill pattern	repeating 69 72 74 74	policy
Default fill allow-list	random fills only	policy
Default timestamp allowance	dual	policy
DSCP allowed by default	yes	policy

Client-side floor worth knowing. Upstream clients reject any server-reduced interval below 1 second, in strict and loose mode alike. A server policy that would produce a smaller interval makes the server unusable by those clients.

---

20. DSCP

Protocol requirement — what the wire parameter is. The DSCP parameter (tag 8) carries the raw IP TOS / Traffic Class byte, with a useful range of 0–255. It is not a 6-bit codepoint. A server applies the negotiated value directly as the TOS / Traffic Class byte of its echo replies, and a compatible implementation MUST encode and interpret it the same way. The common Expedited Forwarding marking is therefore 0xb8 (184) on the wire, not 46. Verified by capture; see BLACKBOX_VERIFICATION_REPORT.md Finding B and captures/dscp-session.pcapng.

Out of scope: user-facing DSCP notation. Whether an implementation's command line or configuration accepts a 6-bit codepoint (0–63) and shifts it left by two to produce the wire byte, or accepts the raw byte directly, is a presentation decision for that project. The clean irtt-rs project will decide and implement its own convention separately. Nothing about that choice is upstream wire behavior, and it does not belong in this specification.

Server policy. When DSCP is permitted and supported on the socket, the server applies the negotiated value to its echo replies. When DSCP is disallowed, the negotiated value is forced to 0 and returned as absent from the parameter payload.

Observed range handling. The negotiated value is not range-checked during negotiation. Values 0–255 are applied normally. A value above 255 is accepted and echoed back in the open reply, but then every echo reply for that session fails to send and is dropped — the client sees a session that opens and then answers nothing.

Robustness recommendation (clean implementation). Reject or clamp DSCP values outside 0–255 during negotiation rather than accepting a value that cannot be applied, so that the value returned in the open reply is one the server will honour.

DSCP is applied to echo replies only; open and close packets are unmarked (see the client specification, Section 10.8).

---

21. Version Differences

21.1 0.9.0 → 0.9.1

Two independent things are recorded here and must not be conflated.

What upstream's published release notes say. They cover platform time precision, server logging transport, a probe integration, build changes and bug fixes. None of it is presented as a protocol change, and the protocol version remained 1. Taken alone, the release notes would suggest no wire-visible difference.

What was measured on the wire. One wire-visible difference exists that the release notes do not mention: the single-clock midpoint layout. A 0.9.0 server emits only the negotiated midpoint field; a 0.9.1 server emits both midpoint fields. Measured side by side with identical scripted sessions:

Server	StampAt = 4, Clock = Wall	StampAt = 4, Clock = Monotonic	StampAt = 4, Clock = Both
0.9.0	36 bytes, one field	36 bytes, one field, process-relative value	44 bytes, two fields
0.9.1	44 bytes, two fields	44 bytes, two fields	44 bytes, two fields

(Received stats = both, negotiated length 0.) See Section 11.3.1.

Correction to earlier material. Any earlier statement that there were no protocol-visible changes between 0.9.0 and 0.9.1 is wrong. That claim followed the release notes rather than measurement; the measured difference above stands.

Classification: one wire-visible difference in 0.9.1, alongside changes that are not wire-visible. Section 11.3.1 additionally records a source-assisted, non-normative judgement that the wire-visible difference is unintended. That judgement is separate from, and not required by, the measurement above.

21.2 0.9.1 → the tested post-0.9.1 development tree

Provenance. The development tree exercised for this study is the 0.9.1 release plus six subsequent upstream commits on the development branch: an ECN change and its merge, a roadmap note, a documentation correction, and a dependency update. Only one of them is a functional change. These six commits are not part of the 0.9.1 release; everything in this subsection was measured against a build of that development tree, and nothing here describes 0.9.1.

Change: an opt-in server ECN option.

• Adds a server command-line option that, per its documentation, ships ECN bits for the client to log, and states that it is IPv6-only, that it forces the source-IP-pinning option, and that it "disables UDP replies from server".
• Observed behavior contradicts the documentation on the last point. With the option enabled, sessions completed normally over both IPv4 and IPv6: packets sent/received 4/4, no loss, ordinary results. Replies are not disabled.
• Enabling it forces the source-IP-pinning behavior described in Section 5.3.
• ECN observation is a receive-side property read from the IP header; it does not change the IRTT payload in either direction.

Timestamp layout is unchanged. The full StampAt × Clock matrix and the midpoint length sweep of Section 11.3.1 were re-measured against a build of this development tree and produced results identical to 0.9.1, byte-position for byte-position. The tested post-0.9.1 tree therefore behaves like 0.9.1 in this respect, and none of the six commits changes the dual-field midpoint emission.

Wire comparison. A side-by-side run of the 0.9.1 release build and the post-0.9.1 build, using an identical scripted request sequence (open with full statistics and dual timestamps on both clocks; echo sequence 0, 1, 4, 3; close), produced byte-identical structure: same open-reply layout, same reply lengths (60 bytes), same flags, same counts (1, 2, 3, 4) and the same windows (0x1, 0x3, 0x19, 0x1), and no close reply in either case.

Classification: CLI / server-policy difference. Not wire-visible.

Nothing in this document changes for the tested post-0.9.1 tree.

21.3 0.1.x

Incompatible predecessor protocol. Out of scope.

---

22. Implementation Hazards Observed Upstream

These are behaviors a clean implementation should deliberately not reproduce. They are listed because each is reachable from ordinary client traffic, so a clean server has to decide what to do instead.

Everything in this section is an observation plus a robustness recommendation. None of it is an interoperability requirement: no conforming client can tell which choice a server made, because in every case the visible effect is either silence or an ordinary reply.

22.1 Oversized Reply Terminates the Server

If the negotiated packet length exceeds the host's maximum outbound UDP datagram size, the first echo reply fails to send with a non-transient error, and upstream 0.9.1 treats that as fatal: the listener stops and the server process exits. Observed on a host whose maximum outbound datagram size was 9216 bytes: a session negotiating 15000 bytes killed the server on its first echo reply, and all subsequent clients received nothing.

The default configuration places no upper bound on the negotiated length, so this is reachable without any malformed packet.

Robustness recommendation (restated from Section 6.3). Treat a per-packet send failure as a per-packet event rather than a fatal one, and refuse to negotiate a length the server cannot transmit.

22.2 Zero-Length Fill Pattern Terminates the Server

A server-fill descriptor of the form pattern: with an empty hex body terminates upstream 0.9.1 during open handling, when the fill allow-list permits pattern fills. The default allow-list does not, so a default-configured server is not exposed; a server configured with a permissive allow-list is.

Robustness recommendation. Validate a fill descriptor before using it and reject a zero-length pattern. Falling back to the server default — the behavior already observed for an unparseable hex body such as pattern:zz — is the natural response, and is what upstream already does for that neighbouring case.

22.3 Negotiated Length Not Bounded by Path or Interface

The negotiated length reported to the client is not clamped to the interface MTU, but the reply is (Section 9.2). Clients treat a short reply as fatal, so this produces a session that opens successfully and then fails immediately.

Robustness recommendation. Clamp the negotiated length to what the server can actually emit, so that the value returned in the open reply is honest. (The resulting reply length is then covered by the ordinary rule of Section 9.2, which is an interoperability requirement — a reply shorter than the negotiated length is fatal to upstream clients.)

22.4 Residual Payload Disclosure Under No-Fill

See Section 13.4. A no-fill mode that emits uninitialized buffer content can leak bytes from other clients' traffic. The requirement not to emit another peer's data is stated in Section 13.4; it is a security property of the implementation rather than a wire-compatibility rule.

---

23. Remaining Unknowns

Each entry records the question, why compatibility might depend on it, what was inspected, what was attempted, and what evidence would settle it.

23.1 Received-count wraparound

• Question: What does the 32-bit received count do at 2^32 requests in a single session — wrap, saturate, or something else?
• Why it matters: A client computing upstream loss from the count would see a large negative or nonsensical delta at the wrap point. Only reachable in extremely long, high-rate sessions.
• Evidence inspected: Field width and encoding confirmed from captures; counter observed to advance by exactly one per accepted request.
• Attempted: Not attempted. Reaching 2^32 requests is not feasible in a targeted experiment.
• Would resolve it: A server-side test harness able to preload a session counter, or a very long-running instrumented session.

23.2 Behavior under genuine resource exhaustion

• Question: What does a server do when session state or buffers can no longer be allocated?
• Why it matters: Determines whether a client sees an open timeout, a partial session, or a dead server.
• Evidence inspected: 1000 concurrent sessions from one endpoint were created with no refusals and no degradation; no admission control was observed.
• Attempted: Scaling to exhaustion was deliberately not attempted — it is a resource-starvation test, not a protocol test.
• Would resolve it: A memory-capped container running the reference server while a controlled harness opens sessions until allocation fails.

23.3 IPv6 zone / link-local session identity

• Question: Is the IPv6 zone index part of session identity in practice, and how are scoped addresses compared?
• Why it matters: A server bound to a link-local address on multiple interfaces could confuse two peers with the same address in different zones.
• Evidence inspected: IPv6 sessions over loopback work identically to IPv4; the IPv4 and IPv6 listeners of one port were confirmed to have separate token scopes.
• Attempted: Link-local multi-interface testing was not possible on the single-host test platform.
• Would resolve it: Two interfaces with the same link-local address in different zones, with clients on each.

23.4 Midpoint dual-field emission and non-upstream clients

• Question: Do client implementations other than upstream 0.9.1 tolerate the extra midpoint field, and do any require it?
• Why it matters: Section 11.3.1 recommends emitting only the negotiated fields; a client that computes an exact expected reply length and rejects longer replies would break against upstream servers, not against a compatible one.
• Evidence inspected: All 60 combinations of ReceivedStats × StampAt × Clock measured against the reference server; a negotiated-length sweep across the two minima for four received-stats settings; upstream client verified to accept both forms. The 0.9.0 build and the tested post-0.9.1 build were measured for comparison.
• Note: the question is narrower than it was. Because the length difference disappears once the negotiated length reaches upstream_header, a third-party client is only exposed to the length discrepancy at small negotiated lengths; at larger ones it is exposed only to the field contents in the monotonic-only case — which is also the regime in which the two forms cannot be told apart (Section 11.3.1).
• Attempted: Only upstream 0.9.1 was available as a second implementation.
• Would resolve it: Testing against a third-party client, or a survey of other implementations.

23.5 Reply-length capping on other platforms

• Question: Is the reply-length cap always the listener interface's MTU, or does it vary with how the platform reports interface MTUs?
• Why it matters: It determines the largest length a server can honestly negotiate.
• Evidence inspected: Measured on one host: replies capped at exactly the bind interface's MTU (1500 on an Ethernet interface); loopback with a 16384-byte MTU was masked by a smaller maximum outbound datagram size.
• Attempted: Two interfaces with different MTUs on one host.
• Would resolve it: The same measurement on Linux and Windows hosts with jumbo-frame and tunnel interfaces.

23.6 Whether any trigger other than the duration limit sets Close on a reply

• Question: Are there conditions besides the maximum-duration hard limit that cause upstream to set the Close flag on an echo reply?
• Why it matters: A client must handle the flag whenever it appears; a server implementer needs to know which conditions warrant it.
• Evidence inspected: The duration limit was reproduced and captured. Idle expiry, shutdown, rate limiting, oversize requests and authentication failure were each exercised and none of them produced a close-flagged reply.
• Attempted: All the above, plus repeated close and foreign-endpoint close.
• Would resolve it: Exhaustive exercise of every server policy knob against a rogue client that keeps sending regardless.

23.7 How tightly server timestamps bracket the request

• Question: How much of a server's own send and receive path falls outside the interval its two timestamps describe?
• Why it matters: It bounds the accuracy of the client's server-processing correction.
• Evidence inspected: Receive-to-send deltas of a few microseconds on loopback; ordering (receive ≤ send) always held.
• Attempted: Cannot be separated from scheduling noise externally.
• Would resolve it: Hardware timestamping on both endpoints. Nothing about where an implementation takes its timestamps is externally observable, so this is likely to remain permanently open, and no requirement in this document depends on it. Section 11.1 states the relationship a compatible server should aim to make derivable.

---

24. Conformance Summary

The two lists below are interoperability requirements only: each is observable by a conforming client, and each rests on a black-box experiment. Robustness recommendations for the clean implementation are collected separately in Section 24.3 and are deliberately not mixed in.

24.1 A conforming server MUST:

1. Speak UDP, validate magic and flag bits, and reject any packet with the Reply flag set.
2. Set the Reply flag on every packet it emits, and never the Open flag on an echo reply.
3. Silently drop every rejected packet — no error replies, ever.
4. Accept open requests without a token field, decode the parameter payload per the shared encoding rules, and return the restricted parameters together with a non-zero token.
5. Return ProtocolVersion = 1 in the open reply.
6. Return a zero token and the Close flag for a no-test open, and create no session for it.
7. Bind each session to its token and its source endpoint, and drop packets that fail either check without disturbing the session.
8. Echo the token and sequence number unchanged in every echo reply.
9. Emit the negotiated fields in the specified order, and pad to the negotiated length. For StampAt = Midpoint this means the fields the negotiated Clock implies and no others — a conforming server does not reproduce the upstream dual-field emission of Section 11.3.1.
10. Report a received count that includes the current request and excludes every dropped one.
11. Report a received window with bit 0 set, bit k meaning "sequence (current − k) was received".
12. Emit receive and send timestamps from a consistent clock domain, such that the pair brackets the server's own handling of that request and the receive instant is never later than the send instant.
13. Release the session on a valid close request. Sending nothing in response is correct and is what upstream does; no close-reply datagram is required, and none is specified here (Section 15.1).
14. Signal a server-initiated close only by setting the Close flag on an otherwise complete echo reply, and release the token at that point.
15. When authenticating: set the HMAC flag and a valid MAC on every reply, and drop silently on any authentication failure, with no reply behavior that could distinguish a known token from an unknown one.

24.2 A conforming server MUST NOT:

1. Reply to any malformed, unauthenticated, unknown-token or foreign-endpoint packet.
2. Interpret any request bytes beyond the token and sequence number.
3. Emit another peer's data, or uninitialized memory, as payload.
4. Return a negotiated packet length in the open reply that it will not actually emit.

24.3 Robustness recommendations for the clean implementation

Not interoperability requirements. No conforming client can observe whether these were followed; they are here because each addresses a behavior observed upstream that a new implementation should not copy.

1. Treat a per-packet send failure as a per-packet event, not a fatal one (Sections 6.3, 22.1).
2. Operate under a bounded session-resource policy, and expire sessions that have never carried an echo request (Sections 7.6, 18.2, 18.3). The specific limits and eviction policy are a clean-project decision.
3. Validate a fill descriptor before use, and reject a zero-length pattern (Section 22.2).
4. Reject or clamp DSCP values the socket cannot carry, during negotiation (Section 20).
5. Clamp the negotiated length to what the server can actually transmit (Sections 22.1, 22.3).

---

25. Related Documents

• IRTT_CLIENT_PROTOCOL_SPEC.md — wire format, parameter encoding, HMAC computation, client-side measurement semantics.
• BLACKBOX_VERIFICATION_REPORT.md — verification evidence, including the server-side section.
• test-vectors/SERVER_BEHAVIORAL_VECTORS.md — input → output vectors for this document.
• test-vectors/README.md — packet-level test vectors.
• captures/ — packet captures referenced throughout.
• ../clean-room/CLEANROOM_NOTES.md — clean-room boundary and audit record.