Status: R0.9 contract, stated before any mechanism exists. Nothing in this file is implemented. It is written first on purpose: the review pattern this project has settled into is state the contract, then let a control decide it — never mint a finding from a reading. Every clause below is paired with what would refute it, because a contract clause with no falsifier is a preference.
This file is canonical for what discovery may be asked and what it may say. It sits beside docs/identity-layers.md, which is canonical for the four things routinely confused with "the address of that node", and does not restate it.
A discovery answer is a HINT ABOUT WHERE TO SEND BYTES. It is not a statement about who anyone is, what they hold, or what they may do.
The hint has exactly one legitimate consumer: the code that chooses a destination address for a packet. Every other consumer is a defect.
A hint is not evidence. It does not become evidence by being fresh, by being signed, by being repeated, or by being agreed with.
WireGuard has no discovery at all, deliberately, and states its whole position in one sentence: a peer's endpoint is updated only from the outer source address of a packet that already authenticated — authentication produces the address; the address never produces authentication.
This system needs one more clause than WireGuard does, because it has a lifecycle layer WireGuard does not:
DISCOVERY CHOOSES WHERE WE TRY. AUTHENTICATION DECIDES WHOM WE REACHED. ONLY THE LINEAGE DECIDES WHAT THEY MAY DO.
Three clauses, three planes, and the arrows only ever point rightward. That sentence is what R0.9 must earn, and every clause below is an attempt to say precisely what would falsify one of its three parts.
The discovery plane is an untrusted hint source, assumed adversary- controlled. This is not pessimism; it is the honest reading of a third party whose whole job is to speak on behalf of others. Concretely it may:
answer with any endpoint, for any identity, including ones that do not exist;
omit answers, permanently or selectively;
answer staleness forever;
return many answers, or different answers to different askers;
replay, reorder and correlate;
lie about its own freshness, its own age, and its own sources;
be all of a caller's answers at once (eclipse).
Falsifier. If any of the above changes any authority state, the model is wrong and the round has found its defect.
An earlier draft of this file said the adversary's total power is three verbs. That was false on its own terms: §2 grants the plane the ability to observe, correlate, replay and reorder, and none of those is delay, misdirect or deny. Overstating a claim in the direction of strength is the same defect as understating it, and it would have been quoted.
So the claim is split into three envelopes, and only the third is the theorem.
1 — REACHABILITY EFFECTS. This is the complete envelope of what an adversarial discovery plane can do to a connection attempt:
DELAY make reaching the current embodiment slower
MISDIRECT make a caller send bytes somewhere useless
DENY make the current embodiment unfindable2 — PRIVACY / METADATA RESIDUAL. Real, unclaimed, and stated rather than argued away:
OBSERVE who asks after whom, and when
CORRELATE link askers, targets and timing across queries
REPLAY / REORDER metadata, to the extent the plane carries anySyncthing is the honest precedent: its global discovery operator can map device IDs to addresses and infer which devices connect, while the connection itself still authenticates the configured device identity. The metadata is genuinely exposed; the identity is genuinely not. Say both.
3 — AUTHORITY EFFECTS. This is the theorem. A purely discovery-plane action produces none of:
mint · bind · widen · restore · transfer · closeFalsifier. A run in which a purely discovery-plane action produces any of the six. Each of the six gets its own control; a single "nothing bad happened" assertion is not acceptable, because it can pass by measuring nothing.
Do not paraphrase envelope 1 as "the adversary can only do three things". It can only do three things to reachability. What it cannot do is envelope 3.
A discovery miss is a reachability fact. Reachability facts close nothing.
A caller that cannot find anybody must fail-stop. It must not conclude vacancy, loss, succession, or that a generation may be closed. It must not downgrade to a weaker path that happens to be reachable.
This is not new doctrine; it is docs/failure-model.md reached by a longer road. LossBasis has no reachability variant, so partitions close nothing, and cd-core has no sensor and must not be given one — a liveness signal accepted as a lifecycle input is a reachability fact promoted to authority. A directory answer is a liveness signal wearing better clothes: it arrives structured, punctual and plural, and it is still a reachability fact.
Falsifier. A run in which total discovery failure produces a finalization, a succession, a vacancy, or a fallback to a lower-assurance path. Also its inverse, which is the one that is usually forgotten: a run in which discovery succeeds for a carrier that is already finalized, and something treats the answer as evidence the finalization did not happen.
The first mechanism is KNOWN-IDENTITY RENDEZVOUS / LOCATION RESOLUTION, and calling it that rather than "discovery" is load-bearing. The caller already knows whom it intends to reach; it does not know where. So the question is not who is out there but:
I already know WHO I intend to reach.
Give me addresses I may TRY.The caller holds a PeerExpectation — an expected NodeId and an expected transport credential — established outside this plane and before it. R0.9 does not establish either, and may not mint a NodeId, a transport credential, or the binding between them.
MAY be asked about: an already-expected layer-1 semantic identity (a NodeId), used as a lookup key and nothing more. MAY answer with: layer-4 locations (underlay endpoints) to try.
Unknown-peer sampling, DHT bootstrapping and any path by which a caller learns of an identity it did not already expect are a different trust contract and are out of scope until this one is frozen. A plane that can introduce you to a stranger is not the plane described here.
MAY NOT name, in a question or an answer: a Locus, a Worker, a Carrier, a generation, a fencing epoch, an admission, a custody, a revision, a canonical head, or any anchor state.
The reason is written in docs/identity-layers.md and is the specific hazard of this round. That file deliberately leaves open which of Locus / Worker / Carrier a persistent NodeId belongs to, "rather than being settled silently by a convenient equality". A discovery plane that can be asked where is Locus L? settles it silently, by convenience, in the direction of
answered for L ⟶ is L's current Carrier ⟶ may act for Lwhich is the entire defect this round exists to prevent.
Falsifier. A message type, wire field, log line, metric label or receipt key in the discovery plane that carries any of the forbidden names. This one is checkable statically and should be a guard, not an experiment.
Every clause so far says refuse X. This one says treat every road the same, and it is the clause a system is most likely to satisfy on paper and violate in code.
An earlier draft stated it as validation parity: an identity learned from the directory must traverse byte-identical validation to one learned from a handshake. That is true but concedes too much, because under §5 the directory never teaches you an identity at all. The stronger and cleaner rule:
ENDPOINT PROVENANCE IS ERASED BEFORE AUTHENTICATION. A connection attempted through static configuration, through a cache, through discovery, or through a rendezvous must enter the SAME peer-validation path, which cannot see which of those it came from.
The shape:
Lookup(expected NodeId) ──────────► EndpointHint[]
│
static config ──┐ │
cache ──────────┼────────────────┤
rendezvous ─────┘ │
▼
┌────────────────────────────────┐
│ ONE strict connector │
│ exact-datagram parsing │
│ transport credential auth │
│ expected NodeId comparison │
└────────────────────────────────┘
│
▼
a validated session
│
and STILL no authority
│
▼
R0.8 lineage decides what may be doneOnly the connector may produce a validated peer. A discovery result cannot produce a validated identity, and a validated transport identity cannot produce lifecycle authority. Those are the second and third clauses of the rule in §1.
ZeroTier's root-server hijack is the defect shape this prevents: the path that validated identities on HELLO was not the path that accepted them from a directory lookup, and any packet could force a victim into that lookup. Nothing was permitted that should have been refused — a check was skipped on one of two roads to the same state.
Falsifier. Reach the same peer by a statically configured endpoint and by a discovered one, and compare the validation performed. A difference is the finding. Equality of outcome on honest input is not evidence of equality of validation — the control must compare the path, not the result.
1 NodeId semantic identity
2 ObservedRoute application-visible route
3 transport credential authentication material
4 underlay endpoint current network location
5 lifecycle authority who may currently mutate a LocusDiscovery operates between 1 and 4 only. It does not read 5 and cannot write it. Nothing derives any layer from any other; in particular:
holding 3 does not establish 1 — falsifier: a legitimate credential holder
presenting a different NodeId must be refused;
holding 1 does not establish 3 — falsifier: the correct NodeId with the
wrong credential must be refused;
being at 4 establishes nothing about 1, 3 or 5;
any equality gate between layers is written over decoded bytes. R0.6's
version compared 64 hex characters to 44 base64 characters and could therefore never fire. An equality falsifier over encoded forms is worth nothing.
Not in the first mechanism. Known-identity location resolution introduces no relay, so a relay control would be measuring a surface that does not exist — and the round has been burned before by controls whose subject was absent. The clause is kept here because the surface will arrive, and it should arrive to a contract rather than the reverse.
A relay is a wire. Its powers are exactly: delay, drop, reorder, observe.
Falsifier. A run in which a relay's own position, credential, or reachability counts as the relayed party's — the confused-deputy shape that made TURN servers into request-forgery pivots. And: a response larger than its request before the path has been validated, which makes the plane an amplifier; measure the ratio and refuse an unbounded one.
An address change is a location fact. It grants nothing the old address did not have, and bytes do not flow to a claimed new address until that address has answered a challenge sent to it.
Falsifier. An off-path party claiming a peer's move and being believed without a round trip to the claimed address.
Trust on first use is a real residual and is stated rather than argued away. The round must say precisely what a caller loses when its first answer is the adversary's — and prove the loss is confined to reachability, by showing that the same caller still refuses to accept an identity or an authority it did not already have grounds for.
Falsifier. Any first-contact path in which the first answer establishes more than later answers do.
§5's list — Locus, Worker, Carrier, generation, epoch, admission, custody, revision, head, anchor — is a rule about discovery-owned surfaces: its protocol types, its state types, its logs and its metrics. It is a structural firewall around a plane while a narrow theorem is being proved, not a ban on two words appearing in one system.
A higher layer may perfectly well say "Locus X could not reach its configured peer", because that sentence is a correlation made above discovery by something that can already see both. What must never happen is the reverse arrow: discovery consuming or emitting one of those names as a semantic input of its own.
Falsifier. Any discovery-owned type, field, log line or metric label carrying one of the names; and separately, any path by which such a name flows back down into a discovery decision.
It does not specify a protocol, a message format, a directory, a DHT, a rendezvous service, or a relay. Choosing any of those is mechanism, and mechanism comes after the controls in receipts/R0.9-OPEN.md §5 exist and have been shown to fail against a tree that lacks the property they test.