FrogNet / Specification
Specification

FrogNet Protocol Specification

Draft 0.9, revision 2026-08-31. Key words are as defined in §1.2 [RFC2119] [RFC8174].

Prerequisites

Technical prerequisites

This specification assumes the reader has an advanced working knowledge of the architecture and use of the following technologies:

FrogNet deliberately uses standard APIs, protocols, operating-system facilities, and tools wherever practical. As a result, its dependencies and relationships cross multiple engineering layers and are dispersed throughout the system.

Required

  • Linux
  • HTTPS proxies
  • Distributed systems
  • Shared memory
  • Semantic compression
  • Custom wire protocols
  • Python

Recommended

  • Conventional networking and routing
  • TCP/IP
  • DNS and DHCP
  • WireGuard
  • REST and HTTP
  • Relational databases and SQL
  • systemd
  • Shell scripting
  • Radio networking
  • FFmpeg
  • Real-time audio/video systems

It is strongly suggested that you load the FrogNet codebase into an AI capable of repository-wide analysis. This makes it considerably easier to trace those dependencies and relationships across the complete system.

FrogNet Specification — Draft 0.9, revision 2026-08-31. Cite a conformance claim against this revision, not against a section number alone.

Read in order or by section. Sections §4a and §11a are numbered on the half convention: they specify components that had no section of their own, and no existing section number changes because of them.

Documents20
Normative statements476 MUST, 208 MUST NOT
ProvenanceEvery requirement checked against the reference implementation; each constant cited with its source file
UnfinishedFour source-verification gaps remain, each marked PENDING SOURCE at the point it applies: discovery cadence and withdrawal in §6, the reassignment-callback registration API in §10, the template disuse interval in §11, and association retry policy in §13. None is filled with a plausible figure. Allocator exhaustion, previously listed here, is closed: the behaviour is stated in §17.4 from the broker source.
StatusDraft 0.9, revision 2026-08-31. Experimental; no registry assignment is claimed.
LicenceThe implementation is open source under GPLv2. The specification is published so an implementation can be written against the contract rather than against the code.
§1
Scope and TerminologyWhat this specification covers, how conformance is claimed, the normative terminology, and the model the rest of it assumes.
§2
Architectural InvariantsFive statements that hold across every other section: one authoritative copy, one serialization point, no replication or merge, topology derived rather than distributed, and independent producer and consumer lifetimes.
§3
Node Model, Identity, Installation and BootstrapWhat a node is, its two unrelated identities, the GUID lifecycle, gateway and child roles, and the requirements an installer must meet.
§4
Discovery and MembershipThe bounded walk, per-path deduplication, the negative cache and what may never mark it, the liveness gate, and what a walk outputs. Depends on §11a: discovery runs over HTTP carried by the proxy and daemon, and opens that link with its own first probe.
§4a
Triggering and the Merge ControllerWhat causes a merge to run: link and lease events, the single controller, re-entrancy, the converge loop, and how the mesh announces to itself.
§5
Addressing and RoutingObservations as evidence, metric roles, pure planning, fallback routes, commit and mutation flagging, and why tunnel existence is not tunnel usage.
§6
Pond Formation, Merge, Split and HealingFormation and splitting as one mechanism, local detection, re-establishment by re-assertion, and the definition of convergence.
§7
Internet Extension and Broker BehaviourWhat the broker is and is not, enrolment, channel-list authority, the teardown guard, transit advertisement, allocation and trust.
§8
Service Discovery and ElectionTwo hosts and only one elected, capability publication, the candidate pool, static scoring, and why nothing that moves with load may select a role.
§9
FrogNet MemoryThe store: addressing, write and read semantics, who decides freshness, coherence and the database-host election, partition behaviour, and non-goals.
§10
UnREST — the Programming ModelThe exchange before and after, the three operations, coupling and lifetime, what the application no longer writes, ownership rules, handlers and concurrency.
§11
FNWP-1 and BLDC-1Frame format and opcodes, template learning, the three reference states, how SAME is proven, sequencing, duplicate-work collapse and gossip bounds.
§11a
The Proxy and the DaemonInterception, socket sets and the cost of overlay, the daemon execution gate, worker pool sizing, and the two caches with their different standing. Prerequisite of §4: discovery runs over HTTP carried by this layer, and opens the :9009 link with its first probe (§4.1b).
§12
Security Architecture and Trust BoundariesNo cryptography of its own, the absent surface, the reference-only wire and its honest boundary, encryption as a bearer choice, and remaining exposure.
§13
Failure Semantics and RecoveryFailure classes and required responses, what does not expire, writes during a partition, and what is not provided.
§14
Performance and AdaptationSemantic versus media adaptation, the nine-rung ladder, pure rate derivation, why a failed rate is not a candidate, and what may be claimed for a figure.
§15
Reference ApplicationsThe Communicator as the reference application, the Monitor as the consumer half of §10, governed shared state in the games, and what a reference application is not.
§16
Simulator and Conformance TestingSubstitution points, the tier ladder, coverage proven from output, isolation requirements, hardware correspondence, and what is not modelled.
§17
Known Limits and Unresolved IssuesEvery known limit with its mechanism, consequence and status — structural limits distinguished from open work.
§18
Implementation and Security ConsiderationsReference platform, interchangeable bearers, registries and protocol naming, regulatory posture, falsification challenges, doctrine tags and deployment cautions.

Clarifications

Nothing is copied. A connected pond holds one authoritative copy of each value at one place. There are no replicas, no deltas, no anti-entropy, and no merge procedure — on reunion after a partition nothing is merged and no value travels (§2, §6, §13).

Gossip carries topology, never memory. A change notification propagates between directly attached neighbours; a tuple value never does, because there is only one copy of it. (§4a, §11).

Companion material

Internals gives mechanism notes alongside the normative text. UnREST by example is worked code. The simulator and the demonstrations carry the evidence. Magnum Croakus is the build manual and the derivation for every section here.

This specification is normative. The reference implementation is one implementation expected to conform to it (§18.8). Where the two disagree, either this document has a defect — corrected by erratum and revision — or the implementation departs from what this document requires. Source is the arbiter of what the reference implementation does; it is not the arbiter of what a conforming implementation must do.