Documentation gaps and ambiguities found while building a JS interop client #4

@thatSFguy

Hi — thanks for putting this spec together. While building a browser-based Reticulum/LXMF client (https://github.com/thatSFguy/reticulum-lora-webclient) against stock Sideband and other peers, I cross-checked our implementation notes against SPEC.md and found a handful of places where the spec is silent, truncated, or potentially ambiguous. Filing as a single feedback issue rather than separate ones since they share a theme — happy to split if you'd prefer.

1. §11 — flag byte bit 7 interpretation

§11 describes the flag byte as bit 7-6 : header_type (0=HEADER_1, 1=HEADER_2). Because only values 0 and 1 are defined, bit 7 is always 0 on current wire, but some downstream implementers have understood bit 7 as reserved for an IFAC indicator and bit 6 as the 1-bit header_type.

Could the spec state explicitly which is normative? Specifically:

• Is bit 7 reserved for future use, or is it part of header_type?
• Will values header_type=2 or =3 ever be emitted?
• How does this relate to the IFAC_* machinery in RNS/Reticulum.py / RNS/Packet.py upstream?

Implementers without an authoritative answer will diverge silently the moment a non-zero high bit appears.

2. §9.7 — periodic re-announce interval

The spec correctly flags periodic re-announcement as non-optional (relays' identity caches expire and silently drop LRPROOFs for unknown senders), but gives no interval guidance. In our testing:

• A one-shot announce-on-connect leaves most relays unaware after a few minutes.
• Sideband appears to use ~30 min (visible in its UI defaults).
• Our client re-announces every 5 min while the radio is on.

A SHOULD-level recommended interval, or at least guidance on what constitutes "too aggressive" vs "too sparse," would help.

3. §8.3 — RNode air-frame header section appears truncated

The section header RNode air-frame header and split-packet protocol exists but the body wasn't visible in our fetch. For implementers writing KISS-side hosts (Web Bluetooth, Web Serial), it would be useful to state explicitly:

• The 1-byte proprietary header (upper nibble = sequence, lower nibble = flags incl. FLAG_SPLIT=0x01) is added/stripped by RNode firmware on the KISS boundary, so KISS hosts never see it on RX or need to add it on TX.
• Implementers driving a SX1262 directly (e.g. RadioLib-based repeaters) DO need to handle it.

Source: markqvist/RNode_Firmware (and our fork thatSFguy/reticulum-rnode) — Kiss.cpp::send_rx_packet, Radio.cpp::read_pending / transmit.

4. §10.1 — Resource activation threshold appears truncated

The visible text "When Resource runs" suggests a missing rule for when Resource framing replaces single-packet delivery. Concretely:

• What is the practical max plaintext size for opportunistic single-packet LXMF delivery (we observe ~250–300 bytes of content)?
• For Link-delivered LXMF, what is the threshold above which Resource framing is required (we observe failures around ~415 bytes)?
• Is the threshold MTU-derived or a fixed constant?

Without this, implementers end up reverse-engineering the cutoff from packet loss patterns.

5. §5.6 — canonical msgpack encoder

The stamp-stripping rule allows two paths (raw-as-received vs decode + re-encode first 4 elements). In practice, @msgpack/msgpack and umsgpack are byte-compatible most of the time but can disagree on numeric width (e.g. uint32 vs float64 for an exactly-integer timestamp).

Could the spec name a canonical encoder or specify the integer/float disambiguation rule the signer is expected to use? Receivers can fall back, but if signers diverge the fallback path becomes load-bearing.

6. §4.5 — ratchet emission, not just parsing

The spec covers receiving and signing-over-when-present cleanly. It would help to add a parallel emitter-side section:

• When SHOULD a sender include a ratchet pub vs. omit it?
• Rotation cadence — per-announce, per-N-announces, time-based?
• Backward-compat: are there peers that strict-reject ratchet-less announces, or is context_flag=0 always accepted?

We currently emit ratchet-less announces and have not seen a peer reject them, but this is anecdote, not a normative statement.

7. Not currently in spec — sender clock semantics

Embedded LoRa nodes without an RTC return seconds-since-boot as their LXMF timestamp. Receivers that sort by stored timestamp end up with these messages anchored at 1970年01月01日 + uptime. A short note recommending "receivers SHOULD prefer insertion-order or local-receive time when sender timestamp resolves to a pre-2020 wall-clock value" would prevent confused chronology in clients across the ecosystem.

---

If any of these are answered elsewhere in the repo (flows/, test-vectors/, or planned per-layer split), happy to be redirected. And if a PR adding any of this content would be welcome, let me know — I have working byte-level verifiers in tools/ of the linked repo that could be repurposed as test vectors.