Networking Stack Design Spike: Statline / Toneline / Gridline

Depends on: docs/software/runtime/platform-link.md (GWP-254, PR #174) — the platform_link_* HAL is the foundation. Do not redesign it here. Device specs read: docs/kn90s-statline.md, docs/kn90t-toneline.md, docs/kn92-gridline.md Related: ADR-0017 (Pico 2 coprocessor), kn86-emulator/src/platform_link.h

1. Device-by-Device Networking Needs

KN-86 Deckline. Point-to-point peer link over USB-C cable — one matched pair, the current HAL shape. WiFi and Bluetooth hardware exist on the Pi Zero 2 W but are not activated; the fiction positions the deck as deliberately off-grid. The worldbook’s AetherNet (mesh, stealth, store-and-forward) is in-universe fiction for contract delivery, not a real stack we implement. Networking role: peer (cable, one other deck). Nothing more is needed for the KN-86 itself.

KN-90S Statline. The device spec names a “phone modem port (RJ-11 jack) for league data synchronization between commissioners via direct dial-up.” In the modern reconstruction, dial-up is not the transport, but the role is precise: one deck is the commissioner host, others are league participants that submit stat entries and pull updated standings. Synchronization is batch (between sessions), not real-time. Networking role: host or client in a small named group, batch sync.

KN-90T Toneline. The spec names a LINK port enabling “two Tonelines to sync and play together over a serial cable — a portable 1988 jam session.” Multi-deck LINK synchronization was in development when the project was suspended. The modern reconstruction requires a beat-clock protocol: one deck is conductor (emits tempo), others are performers (slave their sequences to the beat). Latency tolerance is low — tens of milliseconds acceptable; beyond that, the jam breaks audibly. Networking role: beacon emitter (conductor) or subscriber (performer), real-time sync.

KN-92 Gridline. Two distinct networking surfaces. Primary: hardwired RJ-45 Ethernet to external market data feeds and broker APIs — TCP/IP, standard Linux networking, not platform_link_* territory. Secondary: the LINK key enables “deck-to-deck sync for shared watchlists” between multiple Gridlines operated by the same person. Networking role: client to external infrastructure (primary); peer in small named group for deck sync (secondary).

2. Topology Models In Scope

The current HAL models exactly one topology: a matched pair. The three future devices require a wider vocabulary.

Topology	Devices	v1 Recommendation
Point-to-point	All	In scope — current HAL shape
Hub-and-spoke (1 host, N clients)	KN-90S (commissioner + league), KN-92 (multi-terminal)	In scope — host calls `platform_link_open` N times, routes by context pointer
Beacon / broadcast (1 emitter, N subscribers)	KN-90T (beat clock)	In scope — conductor calls `platform_link_send` on N contexts without expecting responses
Mesh / multi-deck	Speculative	Deferred — requires relay protocol extension beyond current HAL

Hub-and-spoke and beacon are compositions of the existing API, not new primitives. This is important: the HAL does not need to change for v1 topologies.

3. Transport Layer Recommendations

Point-to-point, cable → USB CDC ACM. Each deck presents as a serial device over the USB hub IC (ADR-0018 / ADR-0019). Initiator listens on /dev/ttyACM0; joiner dials. No network stack, no configuration, no infrastructure. Lowest latency. This is platform_link_usb.c and is the right first physical transport for all point-to-point use including Toneline cable sessions. Hardware-gated on assembled prototype decks.

Hub-and-spoke, WiFi → UDP with mDNS discovery. The Pi Zero 2 W has integrated 802.11n. Host deck runs a UDP listener; clients discover via mDNS (_decklink._udp.local) and dial. UDP is appropriate because sync messages are idempotent versioned records; application-layer retry handles drops without a TCP retransmit stall. This handles Statline league sync and Gridline deck-to-deck watchlist sync from a single platform_link_wifi.c implementation.

Beacon, WiFi → UDP broadcast. Conductor sends beat-clock ticks to the subnet broadcast address; subscribers receive and align. No handshake per tick. WiFi latency (~2–10 ms on a local network) is acceptable at 120 BPM (500 ms per beat) but marginal for tight 16th-note sync at high tempo. Fallback: USB-C cable between adjacent Tonelines. Both paths use the same HAL surface.

Gridline external services → standard Linux networking (not platform_link_*). The RJ-45 Ethernet jack connects to broker APIs and market data feeds over TCP/IP. This is curl, WebSocket, whatever the broker requires. Keep this cleanly separated from the deck-to-deck HAL.

Bluetooth: not recommended for v1. Pairing UX is worse than WiFi, throughput is lower, and power cost is non-trivial on the battery budget.

4. Wire Protocol Layer

The HAL transports opaque framed bytes (256-byte maximum per frame). Above it, the devices need a shared meaning layer — sketched here, not fully specified.

Message envelope. Type (1 byte), sequence number (2 bytes), payload length (2 bytes), payload, CRC-16/CCITT (2 bytes). Total overhead: 7 bytes. Consistent with ADR-0017’s Pico UART protocol — same CRC variant, same pattern.

Capability negotiation. On link establishment: both sides exchange a HELLO frame containing device type (KN-86, KN-90S, KN-90T, KN-92), nOSh runtime version, protocol version (major.minor), and session role. Receiver sends HELLO_ACK or a rejection with a reason string rendered on Row 24. A KN-86 connecting to a KN-92 is a clean rejection, not a crash.

Versioning. Same major version required; minor version differences tolerate with degraded capability (lower-versioned side ignores unknown message types). Major version mismatch is a hard reject. This is the same versioning pattern as the Pi-to-Pico handshake in ADR-0017 — consistent across the platform.

Discovery / pairing. USB-C: no discovery problem (cable is the signal). WiFi: mDNS service advertisement with device type in TXT record. Persistent pairing tables are a v2 addition.

Key open question: PLATFORM_LINK_MSG_MAX is 256 bytes. A Statline full-season batch sync (30 teams, full rosters, statistical records) does not fit in 256 bytes. Fragmentation/reassembly is required at the envelope layer, or the HAL frame size needs to increase. Fragmentation is the recommended default — keep the HAL small, handle segmentation above it.

5. Gameplay Implications

The Statline’s league sync maps cleanly onto the list-processing grammar: a league is a list of teams, a trade is a CONS pairing two players, NIL drops a player, EVAL confirms a transaction. Cart authors write the data model; nOSh handles sync. The operator experience is passing the commissioner deck around a table.

The Toneline’s two-deck jam is the most experientially distinctive networking mode. What cart authors author is the phrase vocabulary and the sync-binding that attaches local sequences to the conductor’s beat clock. The multi-deck experience is playing in a band where the instrument is a terminal.

The Gridline’s deck-to-deck sync is a quality-of-life feature for an operator running multiple terminals. Shared watchlists and synchronized alert lambdas mean both screens show the same state. Cart authors express what to sync; the networking layer makes it happen.

Diegesis. The worldbook establishes AetherNet as the always-on background inter-deck protocol. Direct LINK connections are described separately in the Toneline spec as an explicit peer contract. The clearest reading: LINK connections are diegetically peer arrangements, executed over whatever transport is available. Operators see the LINK key and the other deck’s handle, not the transport underneath.

6. Security and Identity

Deck provenance (GWP-255 / PR #173) is the right foundation. At HELLO, the initiator presents its handle and provenance signature; the joiner verifies. Unverifiable provenance is rejected before the session opens. Operators cannot impersonate other handles.

Full link encryption is a v2 concern. The KEC fiction is 1988–1991 vintage; the period-appropriate precedent is plaintext. For v1, operators trust their local network — acceptable for Statline league sync and Toneline jam sessions. The Gridline’s broker API connections use the broker’s own TLS, outside platform_link_* scope.

Edge case: two operators with the same handle connecting to the same Statline commissioner must produce a clean rejection (“handle already connected”), not a silent drop.

7. Implementation Roadmap (Sketched)

Phase 1 — Real USB-C transport (platform_link_usb.c): Hardware-gated on two assembled KN-86 prototypes. HAL is ready; the transport implementation is the gap. Deliverable: two decks connected by USB-C cable, loopback smoke test equivalent to --link-stub. No application-layer protocol needed at this phase.

Phase 2 — WiFi UDP transport + envelope protocol (platform_link_wifi.c): Enables Statline hub-and-spoke and Toneline beacon. Both devices share one transport implementation. Includes mDNS discovery, HELLO/HELLO_ACK handshake, handle + provenance verification, fragmentation for payloads exceeding 256 bytes. Hardware-gated on at least one Statline or Toneline prototype, which is not yet sprint-scoped.

Phase 3 — Application layer per device: Statline league sync protocol, Toneline beat-clock broadcast, Gridline watchlist sync. Each is a separate domain protocol built on the Phase 2 envelope. Gated on Phase 2 stability and device hardware.

8. Open Questions for Josh

WiFi activation on the KN-86. The current device config disables WiFi (off-grid fiction). A “dev mode” flag that enables WiFi in developer builds but ships disabled in production is the recommended default. Flipping it (WiFi on in shipped hardware) changes the KEC off-grid positioning.
Statline and Toneline as modern products vs. fiction-only. If these are real hardware SKUs we intend to build, Phase 2 needs hardware roadmap entries and sprint scoping. If they are fiction-world devices whose networking design informs KN-86 platform architecture only, Phase 2 is a paper exercise until a separate product decision is made.
Protocol location: nOSh core vs. cart layer. Recommended default: nOSh core owns the envelope and HELLO handshake; cart layer defines domain-specific message types. Flipping it (pure cart layer) maximizes flexibility but requires every cart author to re-implement the same handshake boilerplate.
Payload size ceiling. Recommended default: fragmentation at the envelope layer, HAL frame stays at 256 bytes. Flipping it (larger HAL frame) simplifies the protocol but increases memory pressure in the static pool and requires a HAL API rev.
Gridline broker API integration scope. Is the Gridline a product we intend to ship with real broker connectivity (regulatory surface area, data licensing costs, account security requirements), or is the financial domain fictional in the same way the KN-86’s network-intrusion missions are fictional? The answer gates whether Phase 3 includes real API integration work.