irtt-rs/docs/clean-room/CLEANROOM_NOTES.md

Clean-Room Implementation Notes

Purpose

This document records the clean-room boundary for the IRTT reimplementation project. The goal is to ensure that the implementation is developed from a behavioral/protocol specification only, without exposure to the GPL-licensed upstream source code.

It covers three passes and a final sanitization:

• the client pass (2026-04-28), producing ../protocol/IRTT_CLIENT_PROTOCOL_SPEC.md;
• the server pass (2026-08-11), producing ../protocol/IRTT_SERVER_PROTOCOL_SPEC.md and its behavioral vectors, and applying corrections back to the client specification;
• the midpoint timestamp follow-up (2026-08-11);
• the final sanitization pass (2026-08-11), recorded at the end of this file.

How to Read This File

This is a provenance record. It states what class of material was excluded and what discipline was applied; it deliberately does not restate the excluded material. A note that says "an upstream identifier was removed" and then quotes the identifier has removed nothing. Earlier revisions of this file made exactly that mistake, and the audit sections below have been rewritten to describe categories rather than instances.

Two things that are not contamination, recorded here so they are not re-flagged:

• Parameter names. ProtocolVersion, Duration, Interval, Length, ReceivedStats, StampAt, Clock, DSCP and ServerFill appear throughout the specifications. They come from upstream's published documentation of its client's machine-readable output, not from source inspection.
• Quoted diagnostic text. Where a document quotes a message printed by the upstream client or server, that is transcribed program output observed during testing — the same thing any black-box tester sees — and is cited as evidence of observed behavior.

Clean-Room Boundary

• Contaminated side: The specification agent (this side) inspected the upstream source code, documentation, tests, CLI behavior, and release notes to understand the IRTT protocol.

• Clean side: The implementation agent will receive only the documents under docs/protocol/ and this notes file. The implementation agent MUST NOT see the upstream source code.

Source Materials Inspected

The following materials from the upstream IRTT project (heistp/irtt, GPLv2) were inspected to produce the protocol specification:

1. Published end-user documentation: the project overview and FAQ, the general and per-command manual pages, and the changelog. This material is public and may be relied on directly; it is cited in the specifications where used.

2. Source (inspected for protocol behavior only):

   • Protocol version and constants
   • Packet format, field layout, magic bytes, flags
   • Parameter serialization format (tag-value pairs, varint encoding)
   • Connection lifecycle (open, echo, close handshakes)
   • Client configuration and defaults
   • Server connection handling and parameter restriction logic
   • HMAC computation
   • Timestamp handling and clock types
   • Received stats (count and window) format
   • Round-trip data recording and measurement calculations
   • Result computation (RTT, OWD, IPDV, loss)
   • Error codes and error handling
   • Packet test vectors (serialized bytes for known inputs)
   • Network layer (IP version, DSCP, socket options)
   • Wait/drain behavior

3. Test files:

   • Packet serialization tests (used to derive test vectors only; test code itself was not copied)

Statement of Non-Copying

No upstream source code, comments, or pseudocode were copied into the specification document (IRTT_CLIENT_PROTOCOL_SPEC.md). The specification describes only externally observable protocol behavior, wire format, and interoperability requirements.

Test vectors in the specification were derived from the known inputs and expected byte sequences found in the upstream test suite. Only the input parameters and resulting byte arrays were used; no test logic or code was copied.

Post-Drafting Audit

After the initial specification was drafted, a clean-room audit was performed. The categories of problem found and corrected were:

1. Upstream private abbreviations in the terminology table. Removed and replaced with descriptive names.

2. An upstream implementation preference disclosed in the address-resolution discussion. Removed; the spec now leaves the choice to the implementer.

3. Implementation-language standard-library references in the parameter encoding section. Replaced with language-neutral descriptions (LEB128, protobuf-style zigzag).

4. An internal scheduling algorithm described in the send-scheduling section, mirroring upstream control flow. Replaced with observable behavior: packets are sent at approximately their ideal times and drift compensation is implementation-defined.

5. An upstream timer-smoothing strategy named. Removed.

6. An RTT edge-case guard asserted that upstream does not in fact implement. Moved to Open Questions.

7. Received-window validity asserted normatively when it was verification-required. Softened with a reference to Open Questions.

8. An implementation-language concurrency term in the result-model section. Replaced with a neutral word.

9. Upstream test internals referenced in the test-vector section. Rewritten to describe the vector neutrally.

10. Internal constants asserted as protocol requirements — a minimum restricted interval and a maximum parameter buffer size. Moved to Open Questions with verification suggestions. Both were subsequently settled by measurement (Sections 19.9 and 19.10 of the client specification).

11. Timestamp capture order stated as MUST when it was implementation-level timing advice. Downgraded, and later rewritten again in the final sanitization pass to describe only the externally relevant relationship.

12. An internal recording structure described in the send-timing discussion. Rewritten to focus on observable behavior.

13. A self-contradictory inline correction note that revealed the drafting process. Cleaned up.

14. Field ordering stated without a verification caveat despite being source-derived at the time. Verification note added, and the ordering was subsequently confirmed by capture across six field combinations (Section 19.11).

No instance of the removed material is reproduced here. Restating a private identifier in order to record that it was removed would defeat the removal.

Clean-Room Compliance Checklist

• No upstream source code included.
• No upstream comments quoted.
• No upstream private function names included.
• No upstream private type names included.
• No upstream file/module layout described.
• No pseudocode derived from upstream implementation.
• No implementation-language API design included.
• No Go-specific language references remain.
• No upstream implementation preferences or algorithm choices disclosed.
• Protocol behavior described independently.
• Source-derived constants marked for verification.
• Ambiguous behavior marked for verification (Section 19).
• Black-box tests proposed where needed (Section 17).
• Post-drafting audit completed and documented (this section).
• Second-pass scrub completed (see below).

Second-Pass Clean-Room Scrub

A second review was performed on 2026-04-28 by an agent that had not seen the upstream source. The categories of problem found and corrected were:

1. An implementation-architecture directive in the scope section, which prescribed internal structure. Removed; the specification now constrains only observable behavior.

2. A concurrency architecture prescribed in the active-test section, implying an internal threading or task model. Rewritten to state the observable requirement — sending and receiving proceed concurrently — without prescribing how.

3. Source-derived design rationale offered for the zeroed placeholder fields in an echo request. Simplified to the observable purpose: reaching the negotiated packet length.

4. A parenthetical revealing source-exhaustive knowledge of the complete parameter set. Removed.

5. Upstream CLI option syntax mirrored in the wait-variant notation. Replaced with plain-language descriptions.

6. A named statistics algorithm recommended. Replaced with a statement that the method of computing running statistics is implementation-defined.

7. An implementation-specific error category that implied a particular allocation strategy. Generalized.

8. Implementation-language references in this notes file itself. Replaced with language-neutral phrasing.

As above, the removed instances are described by category and not reproduced.

---

Server Pass (2026-08-11)

Scope

A second contaminated-side pass characterised the upstream server and produced ../protocol/IRTT_SERVER_PROTOCOL_SPEC.md, together with ../protocol/test-vectors/SERVER_BEHAVIORAL_VECTORS.md and four new captures. Corrections and clarifications arising from it were applied to the client specification.

Upstream Material Inspected

Three upstream builds are involved in this work, and the sanitized output names whichever one it means everywhere it matters:

Build	Role
0.9.1 release	the behavioral baseline; every unqualified statement refers to it
0.9.0 release	comparison only, for the version difference in the midpoint follow-up
development tree, six upstream commits past the 0.9.1 tag	comparison only; post-release work, not part of 0.9.1, and never allowed to redefine the baseline

Provenance correction (final sanitization pass): an earlier revision described that development tree as "eight commits past the 0.9.1 tag". The count was wrong — it included two commits belonging to this clean-room project itself, which were present in the same working tree but are not upstream work. The upstream count is six, and the outgoing documents now say so consistently.

Inspection covered, at a high level:

1. Published documentation: the server manual page, the changelog, and the project overview's security, FAQ and roadmap sections.
2. Source (for behavior only): request admission and validation, session creation and lookup, parameter restriction, echo handling, reception statistics, timestamp selection, payload filling, close handling, session expiry, and server configuration defaults.
3. Release history: tags and commits between 0.9.1 and the checked-out development head, to classify version differences.

Source inspection was used only to decide what to test. Every normative statement in the sanitized output rests on an observed experiment, a capture, or published end-user documentation — not on the source.

Method, and What Each Part of It Establishes

The distinction below is load-bearing and is preserved in the outgoing documents.

• Black-box observation — a raw UDP harness. It drove a real upstream server directly, so that requests no conforming client would emit could be tested (out-of-order sequence numbers, truncated packets, invalid flag combinations, foreign-endpoint packets, corrupted authentication, and so on). It shares no code with any implementation. Its measurements are stated as observed wire behavior.
• Black-box observation — the real upstream client. Driving the unmodified upstream client and observing what it recorded, reported and exited with is an observation of a genuinely independent second implementation.
• Measurement, not constant-reading. Timing boundaries (idle-expiry grace, maximum-duration grace, interval caps) were established by measuring the server's responses, not by reading values out of the source.
• Contaminated-side consistency validation — a server written on this side. A server was built from the behavioral model and driven by the real upstream client across eleven configurations. Because it was written on the contaminated side it is not an independent implementation, and nothing in the outgoing documents rests on it. What it establishes is that the specification as written is sufficient to build something the upstream client accepts; the client's acceptance is the black-box part. Earlier revisions called this an "independent server"; that description was inaccurate and has been corrected throughout.
• All research scripts, logs, probe sources and notes were kept outside docs/ and are not part of the outgoing material.

Statement of Non-Copying (Server Pass)

No upstream source code, comments, pseudocode, tests, or file/module names were copied into any document under docs/. The sanitized output describes externally observable behavior only.

Where upstream behavior differs from what a naive reading of the wire format would suggest — the received-window reset on reordering, the unenforced protocol version, the midpoint dual-field emission — that difference is documented as an observation, with the input that produces it and the output it yields. No explanation of why the implementation behaves that way appears in the sanitized output, because any such explanation would necessarily be source-derived.

Amended 2026-08-11: this remains true of the received-window and protocol-version items. For the dual-field midpoint emission, one narrowly scoped source-assisted historical conclusion was admitted and labelled — a judgement that the measured 0.9.0-to-0.9.1 difference was unintended. See "Midpoint Timestamp Follow-Up" below.

Two upstream robustness defects are recorded in the server specification (../protocol/IRTT_SERVER_PROTOCOL_SPEC.md Section 22) because both are reachable from ordinary client traffic and a clean implementation has to decide what to do instead. They are stated as observed outcomes plus robustness recommendations for the clean implementation — explicitly not as interoperability requirements, since no conforming client can observe which choice a server made — with no description of the internal cause.

Server-Pass Sanitization Audit

The following were checked for and are absent from all files under docs/:

1. Upstream private function, type, field and variable names.
2. Upstream source file names, module names and package names.
3. Implementation-language identifiers, standard-library references and concurrency vocabulary.
4. Copied or paraphrased upstream comments.
5. Source-shaped pseudocode and control-flow transcription.
6. Internal constants that are not externally observable. Timing values that are observable (the idle-expiry grace, the maximum-duration grace, the interval cap ratio) are stated with the measurement that establishes them and are labelled as server policy, not protocol law.
7. Internal data-structure descriptions. Session lookup is described purely in terms of which packets are accepted and which are dropped.
8. Token generation strategy. The specification states only the uniqueness requirement and explicitly leaves generation to the implementer.

The following items were considered and deliberately excluded from the sanitized output as implementation-internal:

• how session state is stored, indexed, or reclaimed;
• how packet buffers are managed or reused;
• the mechanism by which expired sessions are noticed;
• any description of why the received-window behavior takes the form it does.

Clean-Room Compliance Checklist (Server Pass)

• No upstream source code included.
• No upstream comments quoted.
• No upstream private function or type names included.
• No upstream file/module layout described.
• No implementation-language references remain.
• No pseudocode derived from upstream implementation.
• No internal data structures or algorithms described.
• Observable behavior separated from server policy throughout.
• Every normative statement backed by an experiment, capture, or public documentation.
• Version differences classified explicitly, with each build named (server specification Section 21).
• Unresolved questions recorded rather than inferred (server specification Section 23).
• Contaminated-side consistency validation performed against the real upstream client, and labelled as such rather than as independent verification.
• Contaminated research notes, scripts and probe sources kept outside docs/.

---

Midpoint Timestamp Follow-Up (2026-08-11)

Scope

A focused contaminated-side investigation of one behavior: the timestamp layout upstream 0.9.1 emits for StampAt = Midpoint. It produced changes to the server specification (Sections 9.2, 11.3.1, 21.1, 21.2, 23.4, 24), the client specification (Sections 8.5, 19.14), the verification report (Part III, Finding S-18, plus a caveat on Section 19.2) and the behavioral vectors (Section 5.2 and its new subsections).

A Different Provenance Mix From the Earlier Passes

The earlier passes used source inspection only to decide what to test. This pass went further: contaminated-side analysis was used to form expectations, which were then tested. The sanitized output therefore contains one class of statement the earlier passes did not, and it is labelled wherever it appears. What crosses the boundary falls into four kinds:

• Black-box observed — the wire order (wall field then monotonic field), the affected StampAt/Clock combinations, the dependence of the reply length on the negotiated length, the value an ordinary positional decoder reads in the monotonic-only case, and the 0.9.0 / 0.9.1 / tested-post-0.9.1 comparison. All measured with a raw UDP harness against three separate server builds, and cross-checked at the application layer with the real upstream client.
• Source-assisted historical conclusion — one judgement only: that the measured difference between 0.9.0 and 0.9.1 is an unintended regression rather than a designed feature. It is labelled where it appears, it is not normative, and the measured version difference is stated separately and stands on its own.
• Interoperability requirement — narrowly, what a clean client must tolerate for this one verified case.
• Robustness / implementation recommendation — what a clean server should emit.

The specification wording keeps these four apart explicitly, so a clean-side reader can tell which statements they may rely on as observed fact.

Note in particular what is not in the list. An earlier revision also carried a characterisation of how upstream conceptually represents a midpoint value. That was an internal model, it was source-derived, and the useful wire behavior is fully established without it, so it was removed from all implementation-facing documentation in the final sanitization pass.

What Was Deliberately Not Transferred

Detailed upstream implementation structure, internal representation, control flow, change-level source evidence, and the source-derived reasoning supporting the regression diagnosis were retained only on the contaminated side.

That sentence is the whole of the disclosure, and deliberately so. An earlier revision of this file enumerated the withheld findings in enough detail that reading the list conveyed much of what the list claimed to be withholding. Naming the categories is what a provenance record needs; restating the contents defeats the exclusion it is recording.

What crossed the boundary from that body of work is one sentence of conclusion — labelled source-assisted, non-normative, and separable from every requirement in the outgoing documents.

Method

• A raw UDP harness performed the open negotiation, sent a single echo request, and reported the exact reply datagram length and the bytes at each timestamp offset. It shares no code with any implementation.
• Three server builds were exercised, each named wherever its results are used: the 0.9.1 release, the 0.9.0 release, and a build of the upstream development tree six upstream commits past the 0.9.1 tag. Builds and harness live outside this tree.
• The real upstream client was used as a second, genuinely independent observer for the application-layer effects.

Clean-Room Compliance Checklist (Midpoint Follow-Up)

• No upstream source code, comments or pseudocode included.
• No upstream private function, type or field names included.
• No upstream control flow described.
• No upstream file or module layout described.
• No internal conceptual model of upstream's timestamp representation included.
• The single source-assisted statement labelled as such, confined to a historical judgement, and never presented as black-box verified.
• Black-box observation, source-assisted conclusion, interoperability requirement and robustness recommendation kept distinct.
• Excluded contaminated-side material described by category only, without restating its content.
• Earlier over-general claim ("always 8 bytes longer") corrected rather than left standing.

---

Final Sanitization Pass (2026-08-11)

A last audit of the entire outgoing docs/ tree before it crosses the airlock. No new protocol research was performed; this pass only corrected, reclassified and removed.

Provenance

• Every statement now names the build it came from. The 0.9.1 release is the baseline; the 0.9.0 release and the development tree six upstream commits past the 0.9.1 tag appear only where explicitly labelled, and neither is allowed to stand in for 0.9.1.
• The "eight commits past the 0.9.1 tag" figure was corrected to six. The earlier count wrongly included two commits belonging to this clean-room project itself.
• The server written on this side is now described everywhere as contaminated- side consistency validation, never as an independent implementation. Only the raw UDP harness and the real upstream client are treated as black-box observers.

Statement classification

The outgoing documents now separate five kinds of statement and never conflate them: interoperability requirement; black-box observed upstream behavior; upstream policy or default; robustness recommendation for the clean implementation; and source-assisted historical conclusion.

Specific reclassifications made in this pass:

• Surviving a failed reply send is a robustness recommendation, not a protocol MUST. No conforming client can observe which choice a server made.
• Upstream's absence of session and per-peer bounds is observed policy, and the documents now say explicitly that it is not something a compatible server should reproduce. The clean server is expected to be bounded; the shape of that policy is left to the clean project.
• The fill-validation, DSCP-clamping and length-clamping items in the hazards section were likewise moved from "requirement" to robustness recommendation.
• The server specification's conformance summary is split: interoperability MUST / MUST NOT lists, and a separate list of robustness recommendations.

Architecture neutrality

The outgoing documents prescribe no runtime or architecture for the clean server — no blocking-versus-async choice, no runtime-free API, no core-type shape, no socket ownership arrangement. Those are clean-project decisions and belong in the clean repository after the airlock, not in protocol documentation. The architecture-neutrality statement in the server specification's scope section was extended to say so directly.

Wording removed or rewritten

• Source-derived timestamp placement. Statements locating a timestamp immediately before or after a particular system call were replaced with the externally relevant property: the pair must bracket the server's handling of the request, receive never later than send. Where an implementation takes its readings is not observable and is no longer described.
• Validation-order narrative. The packet-admission section was rewritten from a numbered processing sequence into a table of discard conditions plus the two ordering relationships that were actually verified externally (Open-versus-Close and Open-versus-echo-shaped-body interpretation precedence for an otherwise admissible datagram, which overrides no independent rejection condition; and the indistinguishability of an authentication failure from an unknown token). Behavioral wording replaced control-flow wording throughout.
• Internal midpoint model. The characterisation of upstream's internal representation of a midpoint timestamp was removed from all implementation-facing documentation. What remains is the wire fact: a dual-field midpoint representation, wall field followed by monotonic field.
• DSCP. The wire parameter is now stated plainly as the raw IP TOS / Traffic-Class byte, range 0–255, with Expedited Forwarding at 0xb8 / 184. The future user-facing notation for the clean project is marked out of scope rather than baked into the protocol documents.

Corrected claims

• Midpoint reply length. Every "negotiated length + 8" and "normal packet length + 8" claim was removed. The documents now state the model uniformly: upstream_header is normal_header plus one 8-byte timestamp field; compatible_reply_len = max(negotiated_length, normal_header); upstream_0_9_1_reply_len = max(negotiated_length, upstream_header); and the observable excess is +8, then +7…+1, then 0 as the negotiated length rises. The measured sweeps demonstrating this were preserved.
• Overlong replies. The blanket requirement that a client tolerate any reply longer than the negotiated length was narrowed to the one verified case: single-clock midpoint at exactly upstream_0_9_1_reply_len. That is one additional accepted length per negotiation, not a +1..+8 window — where upstream_0_9_1_reply_len > compatible_reply_len the two values differ by between 1 and 8 bytes, but a length strictly between them is rejected like any other unexpected length. The documents say explicitly that this does not generalise to arbitrary overlong echo replies and that strict validation of other malformed or oversized packets is retained.
• Normal minimum reply size. Reply-length validation is stated against compatible_reply_len, the normal compatible reply length, rather than against the negotiated Length value alone; the two differ whenever the negotiated Length is below the mandatory field block.
• Monotonic-only midpoint. The suggestion that a client may simply read the second 8-byte region as the monotonic value was replaced with a conservative rule. In the equal-length regime the conforming and upstream forms are indistinguishable, so the second region may be ordinary payload; a correction is permitted only where the dual-field form is otherwise identifiable, the ambiguity is recorded rather than resolved by heuristic, and the packet must be accepted either way.
• 0.9.0 → 0.9.1. Any claim of no protocol-visible change between the two was corrected. Published release-note content and measured wire behavior are now stated separately, and they disagree on this point.
• Protocol version. Stale text using "protocol version mismatch" as an example of a normal server rejection was removed. Upstream 0.9.1 accepts version 0, 2, negative and absent, and returns 1; enforcement is client-side.
• Received window. The documents now state that 0x1 means no useful prior received-history is represented, not that the previous 63 packets were lost. Downstream/upstream loss classification is flagged as a separate question scheduled for its own clean-side audit.
• Close semantics. No production standalone close-reply codec is specified. Such a datagram was observed to be tolerated by upstream clients but has no demonstrated purpose in protocol version 1, and the documents say so.
• Parameter payload size. The "believed to be 128 bytes" limit was replaced with the measured result: no protocol limit on a received payload; 128 bytes is a local allocation choice.

Contamination scan

The whole outgoing docs/ tree was scanned against a private-token list derived on the contaminated side from the upstream tree. That list is not reproduced here, and neither is any token from it.

Scanned for and now absent: upstream private function, type, field and variable identifiers; implementation-language identifiers and standard-library references; upstream source filenames, module and package names; source-derived commit identifiers; local filesystem paths; scratchpad paths; and temporary build paths.

The residual hits found and fixed in this pass were all in the audit prose of this file, which had been quoting the identifiers it claimed to have removed, and one tooling-environment block in the verification report that carried a local installation path and an implementation-language version string.

Retained deliberately, and not contamination: the public upstream project identity (heistp/irtt) where provenance requires it; the parameter names, which come from upstream's published documentation; and quoted upstream program output, which is observed black-box evidence.

Captures

Every .pcapng intended to cross was metadata-reviewed. Four had already been container-normalized during the server pass; the remaining ten still carried capture-machine hardware and operating-system identification, the local capture interface name and description, and the capture filter string. All ten were regenerated to strip that metadata.

No capture contained a hostname, a username, a filesystem path, a command string or any reference to an upstream checkout.

Packet bytes were not altered. For each regenerated file the full frame hexdump and the per-frame epoch timestamps were compared before and after and were identical. No capture had to be excluded from the outgoing set.

Outgoing tree hygiene

The outgoing docs/ tree contains only specifications, the verification report, behavioral and packet vectors, and captures. No research scripts, probe sources, upstream source archives, build outputs, temporary logs, dirty source notes or private-identifier lists are present, and the contaminated-side material for the midpoint work was left where it already lives, outside docs/.

One incidental local file sits inside docs/ and is not outgoing material: a local tool-permissions file under a dotted directory. It is ignored by version control, it is not tracked, and it may not be copied across the airlock. The macOS Finder metadata file previously listed here is no longer present; the exclusion still stands, since Finder can recreate one at any time. Re-verified 2026-08-11: the dotted directory is the only ignored entry under docs/, and no Finder metadata file exists anywhere in the outgoing tree.