Filed
Standards Track · draft · no sponsor yet. Three scalar fields begin on unaligned offsets, which contradicts the specification’s own zero-copy claim. Found by drawing the header as a packet grid rather than by reading it.
I
What a HEP is for
A HEP is a design document. It proposes a change, argues for it, and becomes the historical record of why the protocol is shaped the way it is — including the objections, which are recorded rather than smoothed away.
The model is MCP’s SEP process, which is itself descended from Python’s PEPs. We have taken it close to wholesale. Inventing a novel governance process would be a strange place to spend our originality, and a contributor who has written a SEP should find nothing surprising here.
Not everything needs one. Bug fixes, typos, documentation clarifications and new examples are ordinary pull requests. Write a HEP for a protocol change, a breaking change, a process change, or anything you expect to be argued about.
II
Four types
III
The nine sections
Eight are MCP’s, essentially unchanged. The seventh is ours, and it is the only place we thought the SEP format was missing something for a protocol like this one.
Preamble
Title, authors, status, type, and the pull-request number that becomes the HEP number.
Abstract
Around 200 words on the technical problem being addressed.
Motivation
Why the current specification is inadequate. A HEP without sufficient motivation is rejected without further review — this is the section that gets proposals declined.
Specification
Syntax and semantics, detailed enough for two independent implementations to interoperate.
Rationale
Designs considered and rejected, and the objections raised during discussion. Dissent is recorded, not smoothed over.
Backward compatibility
What breaks, how badly, and the migration path. Bound by the 365-day removal window.
Consent implications
oursWhat this proposal lets a counterparty learn about a person that they could not learn before, and what stops them. Required on every HEP including process ones, where the honest answer is often 'nothing' — that answer still has to be written down and reviewed. A consent protocol that does not ask this question of its own changes is not a consent protocol.
Security implications
Threats introduced or mitigated, stated including the ones the proposal does not defend against.
Reference implementation
Required before final. A prototype is required before accepted — pseudocode is not sufficient.
Why Consent implications is mandatory. A consent protocol that does not interrogate its own changes for consent impact is asking the world to hold a standard it does not hold itself. Most process HEPs will answer “nothing” — and that answer still has to be written, read, and agreed by someone other than the author. The cases we are worried about are the ones where the honest answer is short but nobody thought to ask.
IV
Statuses
| Status | Meaning |
|---|---|
draft | Has a sponsor, undergoing informal review. |
in-review | Ready for formal Core Maintainer review. |
accepted | Approved, awaiting implementation and conformance. |
final | Complete, with a reference implementation and a passing conformance scenario. |
rejected | Declined. Not permanent — address the feedback and resubmit. |
withdrawn | The author pulled it. |
superseded | Replaced by a later HEP. |
dormant | No sponsor within six months. Revivable; not a rejection. |
dormant is not rejected. A HEP that found no sponsor may still be a good idea that arrived early, and it can be revived by anyone who finds one later.
V
Two gates, and why they are strict
A prototype before acceptance. Working code, integration tests, or a reference implementation someone else can run. Pseudocode is not sufficient and neither is a convincing document. Implementation reveals what discussion cannot, and the things it reveals are cheap to fix before acceptance and expensive afterwards.
A conformance test before final.Every MUST and SHOULD in the Specification section maps to a check or to a documented exclusion. This is MCP’s requirement and it is the single most disciplined thing in their process: it converts normative prose into something a machine can disagree with. Ambiguity in a specification is usually invisible until two implementers read the same sentence differently, and a traceability file finds it while it is still a sentence.
VI
File one
Draft it as 0000-your-title.md, open a pull request against the specification repository, and rename it to the PR number. Then find a sponsor — someone who will champion it through review. If nobody responds in two weeks, ask louder; that is not rudeness, it is the process working.
If you want the fastest possible route to being useful: the specification lists four open problems we cannot solve, and the governance page names what participation looks like for a company, a startup, a lab or a regulator. A HEP that closes one of those four would be the most valuable document anyone has written about this protocol, including us.
🤫