The FrogNet Specification

FrogNet Specification — Draft 0.9, revision 2026-08-29. 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.

Documents	20
Normative statements	437 MUST, 187 MUST NOT
Provenance	Every requirement checked against the reference implementation; each constant cited with its source file
Unfinished	Four values could not be located in source. Each is marked `PENDING SOURCE` in place rather than filled with a plausible figure.
Status	Draft 0.9, revision 2026-08-29. Experimental; no registry assignment is claimed.
Licence	The implementation is open source under GPLv3. The specification is published so an implementation can be written against the contract rather than against the code.

README — technical prerequisites, and using AI with FrogNet

Technical prerequisites

The FrogNet architecture spans multiple computer science specialties that are often considered unrelated or, at best, loosely related. To make the best use of these documents requires working expertise across the following areas.

Application and protocol architecture

The reader must be able to reason through taking ownership of a conventional application interface, intercepting its traffic, replacing the communication mechanism beneath it with a different protocol, and reconstructing the behavior expected by the application. Expertise with JSON, SQL/MySQL, Apache, Flask/WSGI services, socket APIs, and custom application and wire-protocol implementation is assumed. Topics covered include, but are not limited to, HTTP/1.1 and REST semantics; request and response processing; persistent connections; protocol interception and interposition; transparent proxying; port ownership and redirection; protocol translation; framing; binary encoding; serialization; hashing and HMAC; compression; and compatibility boundaries.

Systems programming and Linux internals

The reader must be able to reason about processes, services, threads, concurrency, resource ownership, kernel interaction, and failure behavior in a live Linux system. Expertise with socket creation and manipulation, socket attributes and options, binding and port ownership, listen/accept/connect behavior, persistent sockets, blocking and non-blocking I/O, timeouts, multiplexing, connection teardown, and socket failure semantics is assumed. Expertise with Linux/Debian, systemd, /proc, /etc, dnsmasq, iproute2, network namespaces, Python, Bash, and PHP is assumed. Topics covered include, but are not limited to, processes; threads; concurrency; synchronization; worker pools; timers; signals; caching; daemon architecture; service lifecycle; filesystem state; kernel interfaces; resource ownership; and failure recovery.

Computer networking

The reader must be able to reconstruct, manipulate, and diagnose a network from interface state, routing tables, policy rules, socket state, packet captures, tunnel state, kernel state, and observed packet paths, including explaining why a packet took a particular path and what happens when that path changes underneath a running application. Topics covered include, but are not limited to, IPv4 addressing and subnetting; interfaces; forwarding; routing tables; route selection and metrics; gateways; multihoming; DNS; tunnels; WireGuard; NAT and firewall interaction; MTU; reachability; topology discovery; failure detection; network partitioning; convergence; and dynamic route changes.

Security engineering

The reader must be able to determine where plaintext exists, where cryptographic protection begins and ends, which principal possesses which keys, what compromise of each component permits, and which security property follows from which mechanism. Expertise with WireGuard, TLS, PKI, certificate management, authentication mechanisms, cryptographic identity, key management, and practical network-security analysis is assumed. Topics covered include, but are not limited to, authentication; authorization; confidentiality; integrity; HMACs; certificates; key ownership; trust establishment; trust boundaries; privilege boundaries; attack surfaces; transport security; failure modes; and threat modeling.

Distributed systems

The reader must be able to reason about what state is authoritative at a particular instant, who can change it, what another participant can observe, what happens when connectivity disappears, and what happens when independently operating regions become connected again. Expertise with consensus, replication, CRDTs, tuple spaces, distributed shared memory, caching, serialization, consistency models, partition behavior, and distributed failure modes is assumed, including the ability to recognize where FrogNet resembles, uses, or deliberately does not use those mechanisms. Topics covered include, but are not limited to, authoritative state; serialization; consistency; freshness; ordering; deterministic election; partition and split/heal behavior; convergence; failure domains; distributed observation; state ownership; materialization; caching; replication; and migration of authority.

Adaptive and feedback systems

The reader must be able to reason about system behavior over time, including the interaction of independently operating adaptive mechanisms and the effects of delayed or incomplete observations. Topics covered include, but are not limited to, measurement; sampling; feedback; control loops; hysteresis; stability; oscillation; saturation; feedback delay; asymmetric transitions; rate selection; recovery; and adaptation under changing network conditions.

Verification, simulation, and conformance

The reader must be able to use the FrogNet Simulator as an engineering instrument, not merely understand its output. This includes constructing and modifying topologies, selecting appropriate simulation tiers and backends, introducing controlled failures and environmental changes, exercising production FrogNet code against modeled conditions, interpreting registered evidence and instrumentation, tracing unexpected behavior through the mechanisms that produced it, and comparing simulated behavior with hardware-derived baselines and live-system observations. The ability to reproduce a result, devise a test that could falsify it, and distinguish implementation behavior from simulator behavior is assumed. Topics covered include, but are not limited to, invariants; preconditions and postconditions; test oracles; deterministic simulation; topology construction; fault injection; state-space exploration; instrumentation; observability; reproducibility; hardware correspondence; implementation-versus-model boundaries; Linux network namespaces; automated integration and system testing; packet traces; controlled failure injection; and externally observable conformance.

Cross-layer software and systems architecture

The reader must be able to follow a consequence across application semantics, shared state, protocol encoding, process behavior, sockets, kernel networking, routing, tunnels, and physical transport, including cases in which individually correct mechanisms interact to produce unexpected system behavior. Topics covered include, but are not limited to, abstraction boundaries; encapsulation; ownership; coupling; interfaces; state versus communication; mechanism versus policy; control plane versus data plane; composition; emergent behavior; and failure propagation.

Expertise in any one of these areas is not sufficient to understand FrogNet as a whole. FrogNet deliberately crosses the boundaries between them, and important behavior frequently emerges from their interaction.

These documents assume working mastery of their prerequisites. They define FrogNet. They do not teach the underlying disciplines.

Using AI with FrogNet

It is clear and obvious to the author of FrogNet that artificial intelligence has advanced sufficiently to assist in the development and deployment of large, complex systems such as FrogNet. It has not advanced sufficiently, nor does it possess the capacity for imagination and independent architectural judgment, to operate independently. It is strongly recommended that AI assistance be treated as a working engineering partnership between an architect and a junior- to mid-level programmer.

FrogNet is delivered with a complex, real-world simulator that exercises the live code across various topologies and under varying conditions. There are specific AI assistance files for the simulator that enable the generation of additional scenarios. We strongly recommend familiarity with the simulator and its capabilities, and that you incorporate it into both your manual and automated workflows.

The documentation set contains AI primers, architectural summaries, definitions, cross-references, and other embedded material specifically intended to give an AI assistant the context necessary to reason about FrogNet accurately.

When using an AI assistant with FrogNet, provide it access to the FrogNet documentation rather than relying on its general knowledge. FrogNet differs from conventional architectures in several areas, and an assistant without the supplied context may substitute conventional models that do not describe FrogNet.

§1Scope and TerminologyWhat this specification covers, how conformance is claimed, the normative terminology, and the model the rest of it assumes. §2Architectural 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. §3Node 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. §4Discovery and MembershipThe bounded walk, per-path deduplication, the negative cache and what may never mark it, the liveness gate, and what a walk outputs. §4aTriggering 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. §5Addressing and RoutingObservations as evidence, metric roles, pure planning, fallback routes, commit and mutation flagging, and why tunnel existence is not tunnel usage. §6Pond Formation, Merge, Split and HealingFormation and splitting as one mechanism, local detection, re-establishment by re-assertion, and the definition of convergence. §7Internet Extension and Broker BehaviourWhat the broker is and is not, enrolment, channel-list authority, the teardown guard, transit advertisement, allocation and trust. §8Service 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. §9FrogNet MemoryThe store: addressing, write and read semantics, who decides freshness, coherence and the database-host election, partition behaviour, and non-goals. §10UnREST — the Programming ModelThe exchange before and after, the two operations, coupling and lifetime, what the application no longer writes, ownership rules, handlers and concurrency. §11FNWP-1 and BLDC-1Frame format and opcodes, template learning, the three reference states, how SAME is proven, sequencing, duplicate-work collapse and gossip bounds. §11aThe 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. §12Security 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. §13Failure Semantics and RecoveryFailure classes and required responses, what does not expire, writes during a partition, and what is not provided. §14Performance 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. §15Reference 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. §16Simulator and Conformance TestingSubstitution points, the tier ladder, coverage proven from output, isolation requirements, hardware correspondence, and what is not modelled. §17Known Limits and Unresolved IssuesEvery known limit with its mechanism, consequence and status — structural limits distinguished from open work. §18Implementation 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.

FrogNet Protocol Specification