docs(spec,security,adr): specify the gateway contract

[bahdotsh]

Workstream D1.2 (spec half), D1.4 and D1.6 from the gateway design record. Documents plus one test guard, independent of #375 and #376, mergeable in any order.

Why

Layer 2 of the program architecture existed only as a concept. "Gateway" and "backbone" appeared in this repo solely as Reticulum integration prose, and docs/reticulum.md documented a daemon TCP protocol as though a counterpart shipped — it never has, in this or any companion repository, and rnsd's actual IPC is a different protocol entirely (which the same document describes three sections earlier, contradicting itself).

What is specified

docs/spec/gateway-contract.md — four invariants, five verbs, the daemon wire protocol, the backbone.

The key move is that this is a reframing, not an invention: the internet relay already implements all five verbs. So the SDK's existing machinery around relay answers (parking, escalating probes, mesh offers, presence-driven flush) turns out to be gateway-verdict machinery that predates the name, and a Reticulum gateway plugs into it rather than needing its own path. Likewise the daemon protocol promotes the one both mobile bridges already speak, rather than designing a third — the client side is implemented twice already, and since no daemon exists, extending it breaks nobody.

Verdict is the load-bearing verb, and the spec is explicit that verdicts are unauthenticated claims: they MAY open a path, MUST NOT close one, and settle nothing. That single rule is the entire answer to a hostile gateway, and it is why the rest of the contract can be as permissive as it is.

New signing domain offline-gateway-addr-v1, registered in the spec's signing-domain table as reserved (specified, not yet emitted). It is registered in advance because mutual non-prefixing is a property of the whole set, so a domain cannot be chosen in isolation — and it must stay distinct from offline-relay-addr-v1 so a proof harvested by one gateway cannot be replayed against the other.

Decisions recorded

• ADR 0016 — gateways are provisioned, never emergent. Self-promotion is the obvious design and this codebase already does something that looks like it (role-blind forwarding with a capability bias). That shape does not transfer: it works in-zone because every device can forward and suppression makes redundancy cheap. Most devices structurally cannot bridge, and no in-zone redundancy covers a bridge that leaves, so an emergent gateway produces a silent partition — from inside the zone, an absent gateway and one that decided it wasn't needed look identical.
• ADR 0017 — Nostr is a carrier, never a gateway. A broadcast relay reports no per-recipient delivery, so there is no verdict to be had. Recorded as permanent so it stops being rediscovered as a bug, and specifically so nobody "fixes" it by inferring verdicts from a relay OK rejection or a send timeout — both are evidence about the relay, and inferring recipient state from them yields confident wrong claims, which is worse than honest silence.

Threat model

Adversary A7 (hostile gateway) and residual R10: blackholing, verdicts lying in both directions, zone-membership exposure to the operator, backbone exhaustion — each with why it is bounded to latency rather than loss, and an honest "nothing closes the lying-gateway case, because the lie is about someone else's state."

Corrections (D1.4)

• docs/reticulum.md: the phantom daemon section now points at the contract and says plainly that no counterpart exists; "fourth transport" predated Nostr; the reconnection table presented inert Rust ReticulumConfig fields as live behaviour when reconnection is entirely owned by the native managers (1s doubling to 30s, not configurable); RETICULUM_MAX_PAYLOAD_SIZE is documented as a limit but has no reader anywhere.
• docs/transport-architecture.md aligned.

Review round 1

Five gaps found in review, all fixed in the follow-up commits on this branch:

• Contract v1 specified no inbound delivery. Both shipped Reticulum managers handle MessageReceived and it is the transport's whole inbound path, but the contract, which now calls itself the document to implement against, never mentioned it: a daemon built to the five verbs alone would attach devices, accept their frames, answer their verdicts and deliver nothing to any of them. Added as Deliver, deliberately not as a sixth verb (delivery is what any carrier does, not what makes one a gateway), with sender marked as a gateway claim rather than authentication.
• Attach had verification obligations on one side only. Every MUST pointed at the device. The gateway is now required to verify the signature, that address is the address derived from public_key, and that the challenge is its own and single-use. Without those a conforming daemon attaches any device under anybody's address, which draws a victim's inbound traffic to a hostile device and poisons the presence answers about them.
• R10 listed unimplemented mechanisms as "in place": gateway token buckets, attach under a domain that is reserved and unemitted, and the recipient-aware decay that lives in feat(protocol): make transport choice ask where the recipient is #376. Split into what holds today and what is only specified.
• The reserved signing domain was prose only. offline-gateway-addr-v1 now sits in the non-prefixing and distinctness guards in protocol::types::signing_domain_tests, since non-prefixing is a property of the whole set and a guard watching only live domains would accept a future live domain that prefixes this one. Negative-controlled: pointing the constant at a prefixing value fails the guard.
• The MDU contradicted itself across docs/reticulum.md (464) and the new spec (465). 465 is correct (MTU 500 minus 35 header).

Also recorded, because it is a silence rather than a message and a daemon author will otherwise miss it: today's bridges confirm a send on the socket write and ignore MessageSent and DeliveryError entirely, so a daemon that answers contract v1 correctly gets no verdict handling until the transport work lands.

Rebased onto main after #375 and #376 merged, resolving one CHANGELOG.md conflict (both sides opened an [Unreleased] section; the gateway entries now sit inside the existing ### Documentation subsection, per the house ordering that puts it last).

The rebase invalidated one of the fixes above, which is worth stating rather than quietly correcting: R10's "specified but not yet implemented" list named the recipient-aware decay, and #376 is the branch that shipped it. The decay is now in the tree (ten-minute TTL for a verdict, five for a presence answer) and has moved into the mitigations that hold today. The Presence section's claim that presence answers "decay the same way" as verdicts is likewise now checkable and was not quite right; they decay on a shorter TTL, and the spec says so with the reason.

Verified locally on the rebased tree: cargo fmt --all --check, CI-parity cargo clippy --workspace -D warnings, cargo test --workspace --lib (2,226 pass), RUSTDOCFLAGS=-D warnings cargo doc, and a scripted relative-link and anchor check across every touched document (0 broken).

Verification

All relative links resolve (scripted check across every touched file). No em dashes in the new documents, per house style.