PPN command protocol

@@ -2,7 +2,7 @@
schema: foundry-doc-v1
title: "PPN command protocol"
slug: ppn-command-protocol
short_description: "The PPN Command Protocol is the 16-byte binary wire format os-network-admin uses to issue commands to os-infrastructure nodes over WireGuard, with no central broker."
short_description: "The PPN Command Protocol is the 16-byte binary wire format app-network-admin uses to issue commands to os-infrastructure nodes over WireGuard, with no central broker."
category: infrastructure
index_group: network-and-telemetry
type: topic
@@ -15,9 +15,9 @@ last_edited: 2026-06-23
editor: pointsav-engineering
---

**Correction (2026-08-02, verified against canonical `origin/main`):** several specific claims below don't match the real implementation. (1) UDP port — the real, functioning implementation (`app-network-admin/src/main.rs`, `MESH_LISTEN_PORT`) uses **9206**, not 8090; port 8090 belongs to a separate, more minimal `system-udp` crate that uses JSON payloads, not the binary format described here. This exact port discrepancy was already flagged to Command during Round 4's PPN cluster merge (`command-20260801-ppn-wiki-consolidation-found-2-real-engi`), still unresolved. (2) Packet layout — the real frame (`app-network-admin/src/main.rs`) is `op_code: u16` (2 bytes) + `target_node: u16` (2 bytes) + `timestamp: u32` + 8 reserved zeroed bytes; there is no "operation-specific payload" field, and only PING/ISOLATE/PONG/unknown op codes are defined. (3) Crate names — real crate is `system-udp`, not `service-udp`; the real translate→authorize→broadcast flow is implemented in `app-network-admin`, not `os-network-admin` (which is a 44-line pairing-approval CLI poller with zero mesh/crypto logic). **Flagged, not resolved.**
The PPN Command Protocol is the wire format `app-network-admin` uses to issue commands to `os-infrastructure` nodes across the PointSav Private Network. It transmits fleet commands as 16-byte binary packets broadcast over UDP port 9206 on the WireGuard mesh — with no central broker, no queue, and no third-party service in the path. Every node in the fleet receives every packet simultaneously; only the addressed node acts.

The PPN Command Protocol is the wire format used by every `os-network-admin` control plane to issue commands to `os-infrastructure` nodes across the PointSav Private Network. It transmits fleet commands as 16-byte binary packets broadcast over UDP port 8090 on the WireGuard mesh — with no central broker, no queue, and no third-party service in the path. Every node in the fleet receives every packet simultaneously; only the addressed node acts.
A separate, more minimal `system-udp` crate implements a related but distinct broadcast pattern on UDP port 8090, using JSON payloads rather than this binary format — the two are not the same protocol and should not be conflated.

## Design constraints

@@ -31,43 +31,42 @@ The protocol was shaped by three requirements that exclude conventional approach

## The packet format

Each command is exactly 16 bytes. The first two bytes constitute the operation code: one byte identifying the operation class, one byte identifying the target node. The remaining 14 bytes are available to carry operation-specific payload — node address, isolation policy, or other parameters depending on operation class.
Each command is exactly 16 bytes: a 2-byte operation code, a 2-byte target-node identifier, a 4-byte Unix timestamp, and 8 reserved zeroed bytes. There is no separate variable-length payload field — every parameter the protocol needs today fits in the fixed op-code/target/timestamp layout. Three operations are currently defined: PING, ISOLATE, and PONG; any other code is treated as unknown.

```
 0               1               2               3  ...  15
 ┌───────────────┬───────────────┬───────────────────────────┐
 │  op class (1) │  target (1)   │  payload (14 bytes)       │
 └───────────────┴───────────────┴───────────────────────────┘
 0        2        4                 8                        16
 ┌────────┬────────┬─────────────────┬────────────────────────┐
 │ op (2) │target(2)│ timestamp (4)   │  reserved, zeroed (8)   │
 └────────┴────────┴─────────────────┴────────────────────────┘
```

The operation code is produced by `service-slm` running locally on the `os-network-admin` node — the natural-language sentence the administrator types never reaches the wire.

## The dispatch sequence

1. The administrator types plain-language intent at the F8 terminal — for example, instructing the fleet to isolate a specific edge node.
2. `service-slm` running locally on the `os-network-admin` node parses the sentence and produces the two-byte operation code identifying the operation class and target.
3. `service-udp` constructs the full 16-byte packet and broadcasts it across the WireGuard mesh on UDP port 8090.
4. Every node in the fleet receives the packet simultaneously. Only the node whose address matches the target byte acts; all others discard.
2. `service-slm`, running locally, parses the sentence and produces the operation code and target-node identifier.
3. `app-network-admin` constructs the full 16-byte packet and broadcasts it across the WireGuard mesh on UDP port 9206.
4. Every node in the fleet receives the packet simultaneously. Only the node whose address matches the target field acts; all others discard.

The translation layer is invisible at the protocol boundary — the mesh sees only the binary command, not the natural-language sentence. There is no audit record of the original text at the protocol layer; that record lives in the F8 terminal log on `os-network-admin`, not in the mesh.
The translation layer is invisible at the protocol boundary — the mesh sees only the binary command, not the natural-language sentence. `os-network-admin` itself is a separate, minimal pairing-approval poller: it watches for pending node-join requests and lets an operator approve them, and carries no mesh-broadcast or cryptographic logic of its own. The translate-authorize-broadcast flow described above lives entirely in `app-network-admin`.

## Why simultaneous broadcast

The broadcast model is deliberate. A unicast model would require the control plane to maintain a routing table with individual addresses for each node, and would require per-node TCP sessions or acknowledgements. Both introduce state that can drift out of sync.

Broadcast over a WireGuard mesh eliminates both problems. Every peer receives every packet. The addressed node acts; the others discard at the first byte comparison. The control plane has no routing state to maintain beyond the mesh peer list, which is managed by `os-network-admin`'s mesh routing policy function.
Broadcast over a WireGuard mesh eliminates both problems. Every peer receives every packet. The addressed node acts; the others discard at the first byte comparison. The control plane has no routing state to maintain beyond the mesh peer list, which `app-network-admin` manages.

The security constraint is satisfied by the mesh itself: non-members cannot receive mesh packets because they do not hold a valid WireGuard handshake with the hub.

## Relationship to the Diode Standard

The PPN Command Protocol is the wire implementation of the [[diode-standard|Diode Standard]]'s downstream control category. It flows from authority (`os-network-admin`) to subject (`os-infrastructure`) and never the reverse. There is no upstream command path in the protocol: the packet format contains no reply-to address, no acknowledgement field, and no mechanism for a Subject node to initiate a packet toward the Authority.
The PPN Command Protocol is the wire implementation of the [[diode-standard|Diode Standard]]'s downstream control category. It flows from authority (`app-network-admin`) to subject (`os-infrastructure`) and never the reverse. There is no upstream command path in the protocol: the packet format contains no reply-to address, no acknowledgement field, and no mechanism for a Subject node to initiate a packet toward the Authority.

Upstream telemetry — logs, heartbeats, status — travels over a separate, strictly sanitised channel. The command protocol and the telemetry channel are intentionally decoupled so that a failure in one does not affect the other.

## See also

- [[os-network-admin]] — the control plane that produces and broadcasts command packets
- `app-network-admin` — the control-plane crate that produces and broadcasts command packets
- [[os-network-admin]] — the separate node-join pairing-approval poller; not the mesh-broadcast component
- [[os-infrastructure-ppn-node]] — the compute substrate nodes that receive and execute commands
- [[diode-standard]] — the authority hierarchy and traffic rules the protocol implements
- [[sovereign-mesh]] — the WireGuard overlay the protocol runs over