Leviculum

Leviculum is a Rust implementation of the Reticulum network stack. It is wire-compatible with the Python reference implementation and runs on Linux, macOS, and embedded devices.

What is Reticulum?

Reticulum is a networking stack for building resilient, encrypted mesh networks over any transport medium. It works over LoRa radios, TCP, UDP, serial links, or anything that can carry bytes. Every node gets a cryptographic identity. Every connection is end-to-end encrypted. No servers, no accounts, no infrastructure required.

What does leviculum do?

Leviculum provides the same functionality as Python Reticulum but compiled to native code. The lnsd daemon is a drop-in replacement for rnsd. The lncp file transfer tool replaces rncp. Python CLI tools like rnstatus, rnpath, and rnprobe work against a running lnsd without modification.

The protocol core (leviculum-core) compiles as no_std with only alloc, so it runs on microcontrollers. The same code powers the Linux daemon, a future Android app, and embedded firmware.

Who this manual is for

• Daemon users running lnsd alongside or instead of rnsd: start with the lnsd quickstart and the man pages.
• Developers embedding or extending the stack: read the Concepts part — the Architecture overview plus Interface Isolation, Python-RNS Compatibility, Identity and Forward Secrecy, and Storage and Embedding.
• Firmware flashers putting Leviculum on nRF52 boards: see the firmware section and the RNode protocol reference.

The Concepts part explains the non-obvious design ideas; the appendix carries the authoritative Reticulum and LXMF specifications.

Tools

Leviculum ships four binaries:

• lnsd -- the Reticulum network daemon
• lnstest -- test and diagnostics tool: integration self-test, diagnostic bundles, identity management, and interactive sessions
• lncp -- standalone file transfer utility (compatible with Python rncp)
• lnstatus -- network status tool (compatible with Python rnstatus)

Architecture Overview

This is the entry point to the Concepts part of the manual. It covers the sans-IO core, the crate split, the driver event loop, and the platform-abstraction traits — the mechanics that the four concept pages build on:

• Interface Isolation — why only the interface knows its medium's quirks.
• Python-RNS Compatibility — wire/semantic compatibility and the drop-in daemon, vs. internal parity (not a goal).
• Identity and Forward Secrecy — dual keypairs, derived destinations, ratchets.
• Storage and Embedding — the Clock/Storage/Interface traits that let one core run on a host or a microcontroller.

The crate split

The protocol logic lives in one no_std crate; everything platform- specific wraps around it:

The application boundary is NodeCore: feed it bytes via handle_packet / handle_timeout and drain a TickOutput { actions, events }. The core decides what to send; the driver decides how and when to put it on the wire. See Storage and Embedding for the injected Clock/Storage/Interface traits that make this portable.

Sans-I/O Core

                     ┌─────────────────────────────────┐
                     │         leviculum-core          │
                     │                                 │
  handle_packet() ──►│  NodeCore<R, C, S>              │──► TickOutput {
  (iface_id, data)   │    ├── Transport (routing)      │      actions: Vec<Action>,
                     │    ├── Links + Channels         │      events: Vec<NodeEvent>,
  handle_timeout() ─►│    └── Destinations             │    }
                     │                                 │
  next_deadline() ──►│  Returns: Option<u64>           │
                     └─────────────────────────────────┘

  Action::SendPacket { iface, data, peer }  — send to one interface,
                                             optionally naming the peer
                                             behind it the bytes are for
  Action::Broadcast { data, exclude }       — send to all interfaces (except one)

Driver Event Loop

The leviculum-std driver has 6 select! branches:

#![allow(unused)]
fn main() {
loop {
    select! {
        // 1. Packet from any interface
        (iface_id, data) = registry.recv_any() => {
            output = core.handle_packet(iface_id, &data);
            post_dispatch(output);
        }
        // 2. External action (connect, send, announce)
        output = action_dispatch_rx.recv() => { post_dispatch(output); }
        // 3. Timer fires
        _ = sleep_until(next_poll) => {
            output = core.handle_timeout();
            post_dispatch(output);
        }
        // 4. Shutdown
        _ = shutdown.changed() => break
        // 5. New interface (TCP accept, local client connect)
        handle = new_interface_rx.recv() => {
            registry.register(handle);
            output = core.handle_interface_up(iface_idx);
            post_dispatch(output);
        }
        // 6. Periodic storage flush (crash protection, hourly)
        _ = sleep_until(next_flush) => { core.storage_mut().flush(); }
    }
}
}

Post-dispatch (after every core call)

1. dispatch_actions(&mut ifaces, &output.actions) — routes Actions to interfaces (protocol logic in core)
2. React to errors — BufferFull: log. Disconnected: call handle_interface_down()
3. Forward output.events to the application
4. Schedule handle_timeout() from output.next_deadline_ms

Interface Trait

#![allow(unused)]
fn main() {
pub trait Interface {
    fn id(&self) -> InterfaceId;
    fn name(&self) -> &str;
    fn mtu(&self) -> usize;
    fn is_online(&self) -> bool;
    fn try_send(&mut self, data: &[u8]) -> Result<(), InterfaceError>;
}
}

Send-only. Receive is driver-specific (tokio: mpsc::poll_recv, Embassy: interrupt DMA, bare-metal: poll FIFO). try_send is fire-and-forget: Reticulum is best-effort, higher layers retransmit.

dispatch_actions() lives in core (not the driver) because action routing (broadcast exclusion, interface selection) is protocol knowledge.

In leviculum-std, InterfaceHandle wraps tokio::sync::mpsc::Sender behind the trait. An embedded driver implements it directly on a radio struct.

Core processes packets with zero delay. Collision avoidance (jitter, CSMA) is the interface's responsibility — fast interfaces (TCP) transmit immediately, slow interfaces (LoRa) apply send-side jitter. This is the interface-isolation rule in code.

Writing a Driver

1. Create interface objects

Implement Interface on your outbound channel. Register with your own bookkeeping. Core references interfaces by InterfaceId only.

2. Run the event loop

Minimum 3 branches: receive, timer, shutdown. Feed everything through the post-dispatch sequence above.

3. Handle the receive path

Driver-specific. On complete packet: core.handle_packet(iface_id, &data) → post-dispatch. On disconnect: core.handle_interface_down(iface_id).

Packet Flow

Incoming

Interface → deframe → mpsc → recv_any() → handle_packet()
  → Transport::process_incoming() → TickOutput
  → dispatch_actions() → interfaces → wire
  → events → application

Outgoing

Application → connect/send/announce → TickOutput (via action_dispatch)
  → dispatch_actions() → interfaces → wire

Local Client (Shared Instance)

lnstest/lncp → Unix socket → LocalInterface (HDLC)
  → handle_packet() with is_local_client=true
  → local_client_known_dests updated (6h TTL)

RPC (rnstatus, rnpath, rnprobe)

Python CLI → Unix socket → RPC server (multiprocessing.connection, pickle)
  → handlers query NodeCore state or trigger probe
  → pickle response → CLI

The shared-instance socket and this RPC channel are what make lnsd a drop-in for rnsd; see Python-RNS Compatibility.

IPC platform support

The shared-instance data channel and the RPC control channel use abstract Unix sockets on Linux, filesystem Unix sockets on macOS/BSD, and TCP loopback on Windows (mirroring Python-RNS's AF_INET fallback). Linux is the tested path and is the one exercised by our CI; macOS/Windows IPC is community-supported and not exercised by our CI.

Storage Trait

For the conceptual rationale (one core, host or embedded backend) see Storage and Embedding; for the per-method deep dive see Storage Trait Split Analysis.

Type-safe methods organized by collection:

Shared types in storage_types.rs: PathEntry, ReverseEntry, LinkEntry, AnnounceEntry, PacketReceipt.

Implementations: NoStorage (no-op), MemoryStorage (BTreeMap, host/tests), EmbeddedStorage (heapless FnvIndexMap, fixed capacity, used by leviculum-nrf), FileStorage (wraps MemoryStorage + disk).

FileStorage Persistence

Non-persistent collections (paths, reverses, links, announces, receipts) are RAM-only and rebuilt from network on restart.

Logging

Sentence-style messages with inline context. Good:

Destination <81b22f60> is now 4 hops away via <ecc35451> on iface 1
Answering path request for <4c0c6c7f> on iface 1, path is known

Bad:

path updated dest=81b22f60 hops=4

Use HexShort for hashes. Always explain drop reasons ("rate limited", "duplicate packet", "no path known").

Interface Isolation

The single most important architectural rule in Leviculum:

Only the interface knows the quirks of its carrier medium. The core, the transport, and the daemon are media-agnostic.

A packet is a packet. At the boundary where the core hands bytes to an interface, there is no distinction between an announce, a link request, a data packet, or a resource chunk. They are all just bytes.

What "media-agnostic core" means

leviculum-core decides what to send, to which interface, and — on an interface that carries several peers — for which peer (the peer hint on Action::SendPacket, Codeberg #376: an identity, never a link, a handle or an address, so the interface still owns the map from peer to link). It never decides when to put a frame on the wire, never spaces transmissions, and never reasons about contention. The core processes every packet with zero delay and emits an Action::SendPacket or Action::Broadcast immediately (see Architecture).

Because the core is the same code on a Linux daemon, an Android app, and an nRF52 firmware image, it cannot afford to know whether the medium underneath is a fibre-fast TCP socket or a half-duplex LoRa radio whose airtime budget is measured in minutes. Medium awareness lives entirely on the far side of the Interface trait.

What an interface is allowed to know

A LoRa interface knows it cannot transmit and receive at the same time. It knows its RadioSettings (bandwidth, spreading factor, coding rate) and therefore the airtime cost of any given frame. It holds packets back, applies its own randomised pre-TX jitter on top of the RNode firmware's CSMA, and refuses new frames when its airtime budget is exhausted. Concretely:

• Send-side jitter — packets are queued, not sent immediately; a frame that acquires an idle channel first serves a randomised wait, DIFS plus a contention window sized from the radio parameters, so two nodes do not re-collide (leviculum-std/src/interfaces/rnode.rs:2742-2773, where the TX loop arms it; the ceiling it reports is compute_jitter_max_ms, leviculum-std/src/interfaces/rnode.rs:293-303).
• CSMA — radio-level carrier sensing is handled by the RNode firmware on top; the interface hands the modem one frame at a time so that CSMA runs for every frame, and none of this reaches the core (leviculum-std/src/interfaces/rnode.rs:2264-2273).
• Airtime backpressure — a per-interface credit bucket charges every send by its airtime cost and signals BufferFull rather than flooding the serial queue (leviculum-std/src/interfaces/airtime.rs:1). This explicitly "never leaks into leviculum-core, so the no_std core stays free of host-side backpressure concerns" (same file).

A TCP interface has none of this. It just writes bytes (leviculum-std/src/interfaces/tcp.rs).

Why the rule is hard, not advisory

The rule binds anyone writing a fix. If a proposed fix for a collision, contention, or duplex problem introduces an awareness flag or counter in transport.rs, the node/ modules, or the daemon ("is a link in flight?", "am I forwarding a link request?"), it is at the wrong layer. Such a fix must be redirected into the interface.

Interface implementations are therefore free to diverge from Python-Reticulum's thin serial-writer style — that divergence is exactly where medium-specific intelligence belongs, and it satisfies the project's deviation rule as long as wire and semantic compatibility are preserved.

Consequences

• The same routing logic runs unchanged over LoRa, TCP, UDP, serial, and the in-process local socket. That includes relaying a packet back out of the interface it arrived on — the same-interface relay decision is taken in the media-agnostic core; the interface is not involved.
• New media are added by implementing one trait, not by threading medium-specific cases through the protocol core.
• Collision-avoidance bugs are debugged in one place — the interface — instead of being smeared across six stack layers.

The one place the medium is named

InterfaceKind (leviculum-core/src/traits.rs) names the carrier — Tcp, Rnode, Serial, and so on — and that looks like an exception to the rule. It is not: the kind is reported, never acted on. It exists so rnstatus can print the Python-RNS interface class name and so a status consumer can group interfaces by transport instead of by their peer label.

A match on it outside traits.rs may produce a string, a number or a status field, and nothing else. As of 2026-07-30 there are exactly two consumers: transport.rs's sparse-map bookkeeping (where Unknown means "no entry") and rpc/handlers.rs::interface_type. A third that decides what the stack does — a longer timeout for LoRa, a skipped step on serial — is the wrong-layer fix this page describes; widen the Interface trait so the interface answers the question itself.

This rule is deliberately not machine-checked. A guard could only see a syntactic comparison against a variant, which is not the shape the violation takes: an exhaustive match kind returning a timeout reads identically to one returning a label. Both existing consumers would need an exemption, so on today's three call sites the exemption list would be longer than the finding, and it would grow with every legitimate status field. The rule is stated here and on the enum instead.

See also: Storage and Embedding for the parallel isolation of persistence and time, and the RNode protocol page for the LoRa carrier details an interface must handle.

An interface that holds several peers

A TCP listener, an AutoInterface, a BLE radio and an I2P endpoint all have the same shape: one configured section, many peers behind it. Each one has to answer the same question, and the answer decides how much the rest of the stack has to know about the carrier:

When the transport wants these bytes to reach one of the peers behind this interface, how does it say which one?

This page records the answers we run today, the answer the references run, what one more interface actually costs measured on the firmware, and which model we take forward. It is a design document, not a status page: what is open belongs on the tracker.

The rule it has to live under is Interface isolation — only the interface knows its medium. Nothing below weakens that; the whole argument is about where the peer-to-link map lives, and in every option it lives on the interface's side of the boundary.

What we do today, and it is not one thing

TCP server: a child interface per connection

The listener binds and accepts; every accepted connection becomes its own InterfaceHandle with its own id, drawn from the shared counter (spawn_tcp_server, leviculum-std/src/interfaces/tcp.rs:365). The child is built from the already-connected stream (spawn_tcp_interface_from_stream, leviculum-std/src/interfaces/tcp.rs:432), inherits IFAC, mode and ingress control from the listener, and is handed to the event loop, which registers it in the routing map like any other interface (registry, leviculum-std/src/driver/mod.rs:4917).

The listener itself is deliberately not in that map. It carries no packets, so it would be a send target that cannot send; it is recorded in the reporting inventory instead, where the child registers its display identity and its parent link (add_spawned, leviculum-std/src/interfaces/tcp.rs:419; listener_id, leviculum-std/src/interfaces/tcp.rs:427). The split between the routing map and the reporting inventory is the point of that module (interface_names, leviculum-std/src/interfaces/inventory.rs:7).

Teardown runs through the ordinary disconnect path: the event loop notices the channel closed, calls handle_interface_down (leviculum-std/src/driver/mod.rs:4571) to cull the routing entries, and the child's byte counters are folded into its parent's departed totals so the listener's reported traffic does not shrink when a client leaves (remove_spawned, leviculum-std/src/driver/mod.rs:4086).

AutoInterface, I2P, shared instance: the same shape

• Every discovered AutoInterface peer becomes a separate handle (spawn_auto_interface, leviculum-std/src/interfaces/auto_interface/orchestrator.rs:168; the per-peer handle at InterfaceHandle, leviculum-std/src/interfaces/auto_interface/orchestrator.rs:805).
• Every accepted I2P stream becomes a handle (new_interface_tx, leviculum-std/src/interfaces/i2p/mod.rs:495).
• Every accepted shared-instance IPC client becomes a handle (add_spawned, leviculum-std/src/interfaces/local.rs:319).

Four multi-peer carriers, one model: a child interface per peer.

BLE: one interface, many links, a peer hint

The fifth is different. One configured BLEInterface section is one Reticulum interface and one broadcast domain (BLEInterface, leviculum-std/src/interfaces/ble/mod.rs:5). Every outbound packet goes through one planner that decides which links get a copy (plan_tx_to, leviculum-std/src/interfaces/ble/links.rs:898, driven from send_packet, leviculum-std/src/interfaces/ble/mod.rs:1029). Since Codeberg #376 the core supplies the addressee: a path entry carries the identity it was learned from (via_peer, leviculum-core/src/storage_types.rs:48) and that identity rides out with the packet. With a hint the planner picks one link; without one (an announce, a path request) it floods, which is what a broadcast domain owes its peers.

Since Codeberg #422 there is a third statement, and it is the one that makes a board a relay between two of its own links: a broadcast the core is re-sending carries the peer it ARRIVED from (exclude_peer, leviculum-core/src/transport.rs:524), and the interface serves every link but that one (try_send_excluding_peer, leviculum-core/src/traits.rs:347). The default implementation sends nothing, which is exactly what excluding the whole interface did, so every single-link carrier is unchanged and so is lnsd's BLE interface, whose peripheral role notifies its subscribed centrals as one group and cannot address a subset of them. The firmware implements it (try_send_excluding_peer, leviculum-nrf/src/ble/mod.rs:698), where the decision is a pure function of the registry (TxAim, leviculum-nrf/ble-tx/src/registry.rs:828). Without it a path request from the phone died at the board: one InterfaceId covered both links, so excluding the arrival interface silenced the neighbour board that was the only node able to answer.

The firmware runs the same shape with fixed ids: serial 0, LoRa 1, BLE 2, set once at startup (set_interface_name, leviculum-nrf/src/bin/t114.rs:286) and hardcoded in the interface itself (BleInterface, leviculum-nrf/src/ble/mod.rs:630), with the announce gate naming the same constant (BLE_IFACE, leviculum-nrf/src/announce.rs:85). The fan-out is a task that maps the hint onto a per-link queue (tx_fanout_task, leviculum-nrf/src/ble/mod.rs:489; LINK_OUT, leviculum-nrf/src/ble/mod.rs:453).

The receive side is already peer-aware on both stacks. The board reports which peer a packet came from and when a peer appears or disappears (handle_packet_from_peer, leviculum-nrf/src/bin/t114.rs:1153; handle_interface_peer_lost, leviculum-nrf/src/bin/t114.rs:1181; handle_interface_peer_up, leviculum-nrf/src/bin/t114.rs:1193; the same three in handle_packet_from_peer, leviculum-nrf/src/bin/rak4631.rs:1150), the core stamps the peer onto the path entry it installs, and a peer loss culls exactly the paths through it (drop_paths_via_peer, leviculum-core/src/transport.rs:5434). So the identity-shaped addressing already exists end to end; the only open question is whether the send side spends an interface object on it.

How far the two stacks already drift under one model

Both stacks run the peer-hint model for BLE today, so what follows is not the cost of two models — it is the baseline drift between two implementations of one model, which is the floor any split model would build on top of. lnsd's central task always reports CentralGone when it ends, including when the dial never connected at all (CentralGone, leviculum-std/src/interfaces/ble/bluez.rs:400), and the orchestrator restarts the strict scan phase on that event (CentralGone, leviculum-std/src/interfaces/ble/mod.rs:827, into note_reset, leviculum-std/src/interfaces/ble/links.rs:1470). The firmware restarts its strict phase only when a new neighbour links or the strict rule finds a target (note_phase_event, leviculum-nrf/src/ble/columba.rs:1685, under the reset rule PhaseEvent::resets_strict in leviculum-nrf/ble-tx/src/admission.rs, narrowed by #504 so a known peer's reconnect and a teardown no longer reset it); a dial that timed out records at most a dead end and leaves the clock running (note_dead_end, leviculum-nrf/src/ble/columba.rs:1760).

Same protocol, same shared constant, different behaviour after a failed dial: lnsd owes another full 30 s strict bound, the board does not. Neither is obviously wrong. The point is that nobody decided it — it fell out of the two stacks having different event vocabularies (CentralGone fires for a dial that never connected; conn_link_down cannot). That happens under one shared model. Option B below would give the two stacks different structures as well, and the drift rate is what it would multiply.

The reference, as a source of ideas

Python-RNS spawns a child interface per connection in five places: spawned_interfaces (TCPInterface.py:632), spawned_interfaces (AutoInterface.py:590), spawned_interfaces (I2PInterface.py:998), spawned_interfaces (BackboneInterface.py:129) and spawned_interfaces (WeaveInterface.py:990). The child is appended to RNS.Transport.interfaces and is from then on an ordinary send target.

What that buys:

• The transport addresses an interface. There is no hint, no second addressing concept, no interface that means different things depending on an extra argument.
• Per-peer statistics fall out: each child has its own rxb/txb, and rnstatus shows a row per peer.
• Teardown is one code path — detach the child, and everything keyed on its id goes with it.

What it costs: an interface object, its state, and its registration per connection. Python has no BLE interface at all, so on the carrier this page is actually about, the reference offers no precedent.

The nearest thing that does is the ble-reticulum package Columba uses, which is our wire counterpart. It spawns one child per peer (BLEPeerInterface, ble-reticulum/src/ble_reticulum/BLEInterface.py:2380; at commit 07d9413, 2026-01-18, in the sibling checkout). Two things about that child are worth more than the precedent itself:

1. The child is a shim, not an interface. Its process_outgoing (ble-reticulum/src/ble_reticulum/BLEInterface.py:2437) fetches the fragmenter from its parent, fragments, and hands each fragment back to the parent's shared driver keyed by address (ble-reticulum/src/ble_reticulum/BLEInterface.py:2474). Every piece of per-medium machinery stays on the parent. The child holds an address and two counters.
2. On the peripheral side the addressing is not real. The GATT server's send_notification (ble-reticulum/src/ble_reticulum/BLEGATTServer.py:537) takes a central_address, and then writes the value to the one TX characteristic (set_value, ble-reticulum/src/ble_reticulum/BLEGATTServer.py:575), which notifies every subscribed central. The address argument only selects which counter to increment.

So the reference implementation of a per-peer interface, on this exact carrier, does not actually address one peer where the carrier cannot. That is not a criticism of it — the Columba wire spec has one notify characteristic, and no software layer can conjure a second one. It is the reason "the reference spawns children, so we should" is not an argument here. Our own planner is explicit about the same limit (plan_tx_to, leviculum-std/src/interfaces/ble/links.rs:898).

The firmware is the exception, and it cuts the other way: the SoftDevice's notification takes a connection handle, so a board can address one peripheral-role link. lnsd, on BlueZ, cannot.

The numbers

Per-interface state in Transport and NodeCore

NodeCore holds no interface-keyed collection of its own; every per-interface field lives in Transport, and there are 24 of them (interface_announce_caps, leviculum-core/src/transport.rs:2761 through own_tunnel_ids, leviculum-core/src/transport.rs:3099 — the BTreeMap<usize, _> and BTreeSet<usize> fields in that block).

Method, and why not size_of. Summing size_of over those 24 value types would be the wrong number by a wide margin in both directions: a BTreeMap allocates in nodes of up to 11 entries, so the first interface pays for a whole node in every map and the next ten pay nothing, and several of the values are themselves growable (interface_held_announces, leviculum-core/src/transport.rs:2982, is a map of maps). What the 96 KiB firmware pool actually sees is allocator traffic, so that is what was measured: a counting GlobalAlloc around System — the harness already in the tree as CountingAlloc (leviculum-core/tests/heap_leak.rs:56) — reporting net live bytes (allocated minus freed), sampled around building one Transport with N interfaces registered through the setter sequence the firmware bins run, then driving 40 rounds of announce RX across all of them.

Positive control in every run: the transport must hold 3 of 3 peer paths at the end, or the measurement is discarded as vacuous. That control earned itself immediately — the first version of this harness reported a flat 0 B for every N, because it drove NodeCore with NoStorage and no announce was ever accepted.

The harness itself is deliberately not committed. It would have to live in leviculum-core/tests/, and fast runs cargo test --workspace --lib, so nothing would ever execute it — a test that runs nowhere is the exact Guarantee-B failure Checks that are actually checks is about. It is ~180 lines and the recipe above is enough to rebuild it: the allocator from heap_leak.rs, Transport::new with enable_transport: true and a long path_expiry_secs, the seven setters, and clear_packet_hashes per round so the dedup cache does not mask the per-interface growth.

Run on i686-unknown-linux-musl, not the host default: the board is a 32-bit-pointer target and every one of those maps is pointer-heavy, so x86-64 overstates it. How much depends on what is being counted — a third on the pointer-dominated first registration (1 363 B vs 891 B), about 5 % on the warm 3 → 4 step (1 411 B vs 1 347 B), 10 % on an 11-interface transport (22 228 B vs 20 136 B). The 32-bit column is the one quoted below.

Registration is nearly free; the cost appears when the interface carries traffic and the lazily-created maps get their entry. Take 1 347 B for the first extra interface and ~600 B for each one after. Reproduced identically across two runs, with the one exception of a single 6 → 7 step where a node split landed differently (939 B) — which is the BTreeMap node granularity showing, not noise in the method.

What the firmware can afford

Three measured budgets, all from the T114 on the rig, all post-#372:

Three BLE children cost 1 347 + 2 × 579 = 2 505 B of heap, 4 041 B if every step happens to split a node. Against 33 260 B free at the worst watermark ever observed that is 7-12 %, and against the ~42 000 B free at the typical watermark it is 6-10 %. The heap affords it.

The 928 B SoftDevice margin does not bound this, and it is worth being explicit because the number is small enough to look alarming. That margin sizes the SoftDevice's own RAM requirement, which scales with conn_count: 15 272 B at two connections, 23 968 B at four (leviculum-nrf/memory.x:166), and #372 paid for that by moving the app RAM floor up 8 576 B. A Reticulum interface object is application heap; it does not appear in sd_ble_enable's requirement at all. Spawning three children over the same four BLE connections costs the SoftDevice nothing. A fifth BLE connection would cost about another 4 300 B (the measured two-to-four slope) and blow the 928 B margin — but that is equally true today with one interface, and the boot assert catches it either way.

Stack is likewise not per-interface: the send loop iterates, it does not recurse. What does scale with the interface count is the broadcast fan-out — an announce emits one action per entry in the routing map (interface_names, leviculum-core/src/transport.rs:12342), each carrying a cloned packet. With three BLE children an announce would allocate three ~500 B action buffers where today it allocates one that tx_fanout_task clones per link (leviculum-nrf/src/ble/mod.rs:489). Same peak, moved one layer up.

Which machinery is per medium, and which is per link

This is what decides whether a child can stand on its own or needs a parent to lean on. Measured against the tree, not assumed:

Six of the ten rows are per medium, and the four that are not are the small ones. That is the finding: on a shared-carrier medium almost everything that makes an interface an interface is per medium. A child would own an MTU, a pacer, two timers and two counters, and would have to reach the parent for everything else — which is precisely the shape ble-reticulum's child ended up in.

The options

A — children everywhere. BLE spawns an interface per link on both stacks, matching TCP, AutoInterface, I2P and the shared instance.

B — children on lnsd, peer hint on the board. The daemon can afford interface objects; the firmware keeps three compile-time ids.

C — peer hint everywhere. One interface per medium; the transport passes "for this peer"; the interface maps peer to link. This is what Codeberg #365 and #376 built, and what runs today.

D — peer hint everywhere, per-peer rows in the reporting inventory. C, plus the one thing A gives away for free: the inventory already models a parent with spawned children and merges a departed child's bytes into its parent (add_spawned, leviculum-std/src/interfaces/inventory.rs:184; remove_spawned, leviculum-std/src/interfaces/inventory.rs:190), and it is driver-owned and deliberately outside the routing map. A BLE peer appearing and disappearing already crosses the driver boundary as a peer event, so it can create and retire an inventory row without ever becoming a send target.

A peer reachable on two links at once. Under A there are two child interfaces and therefore two path entries with different interface indices; the transport picks by hop count and the loser is a live standby, and losing one link culls only its own paths. That is the cleanest behaviour of the four, and it is a real scenario: a rotated- address reconnect holds two links to one identity for a moment. Under C and D there is one interface and one path entry; the planner takes the first link it finds for that identity (plan_tx_to, leviculum-std/src/interfaces/ble/links.rs:898), and a peer loss is reported only when the last link for that identity dies (knows_identity, leviculum-std/src/interfaces/ble/links.rs:503). The observable difference is which of two equally good links carries the next packet — the transport cannot express a preference it has no information to form. Under B, whichever of the two the stack in question runs.

What an address rotation looks like, from each side. The observed trigger is a Columba phone rotating its resolvable private address about every ~90 s (review notes columba-befunde.md §5; the 2026-09-12 field capture on #360 shows the same ~90 s cycle). The phone abandons its old connection when it rotates — from our side that link simply goes silent mid-keepalive-interval — and reappears under an address no table can associate with it, because an advertisement carries no identity. The two sides of the same event:

• Seen from the board or lnsd: the old link's inbound frames stop; seconds later the same 16-byte identity handshakes on a NEW connection — either because the phone dialled us, or because our own scanner dialled the unrecognizable new address. Which link survives is judge_duplicate (leviculum-nrf/ble-tx/src/registry.rs, shared by lnsd): an old link its peer has stopped keepaliving for LINK_ABANDONED_MS (30 s) loses to the newcomer (BLE_LINK_REPLACED … rule=abandoned); otherwise the decision is the PEER's own, preferred_ble_role — a port of Columba's preferredBleRole — and we keep whichever connection it keeps. The losing link is disconnected by us at the decision, in either role.
• Seen from the phone: it runs the same function on the same four inputs, which is the whole point: a rule both ends compute identically is the only one that cannot leave the pair linkless. The brief two-links-one-peer window above is the hand-over moment.

Before #360 round 1 the board refused every outgoing-origin duplicate, which kept the abandoned link and left the rotating phone linkless for the 45 s expiry of every ~90 s cycle. Round 1 then read the old link's PAYLOAD recency, which displaced links the phone was still keepaliving and produced the mirror-image hole on 2026-09-12 21:41 — each side closing the link the other had kept. Round 2 removed our own opinion from the general case and copies the peer's instead; see Bluetooth interfaces for the branches.

The recommendation

D: keep the peer hint on both stacks, and recover per-peer visibility in the reporting inventory rather than in the routing map. The deciding argument is not the RAM — 2.5 KiB of a 33 KiB worst-case margin is affordable, so option A is not blocked by the firmware and we should stop saying it is. It is that a child interface on a shared carrier is not an interface: six of the ten mechanisms above are per medium, so every child would delegate straight back to a parent, and the reference implementation of exactly this idea on exactly this carrier ended up as a shim holding an address and two counters, with a peripheral-side central_address that only picks a counter. We would pay an object, a registration, a teardown path and a second addressing concept to buy an addressing capability the carrier does not have. The hint costs one Option<[u8; 16]> on an action we already emit, works identically on both stacks, and is honest about the peripheral-side limit instead of papering over it. What A genuinely buys — a row per peer in rnstatus — is a reporting concern, and the inventory is already the place where reporting rows live without being send targets. Option B is rejected outright. The two stacks already drift under one shared model — the failed-dial scan phase above is this month's example — and giving them different structures as well buys nothing the numbers ask for: the firmware is not the constrained party here, which was B's whole premise.

What would change this, and what to measure again

The recommendation is a reading of today's mechanisms, not a permanent verdict. Three triggers, each with the measurement that settles it:

1. A carrier arrives where per-link addressing is real on both roles and per-link policy is genuine — per-link airtime, per-link congestion control, per-link IFAC. Then a child owns something and A wins on its merits. Measure: how many of the ten rows above move from "medium" to "link" for that carrier.
2. The transport gains a reason to prefer one of two links to the same peer — a per-link quality or cost signal. Today it has none, which is why C's "first link found" is not a shortcoming. Measure: whether a per-link metric changes the chosen route on the rig at all.
3. rnstatus parity against rnsd needs per-peer BLE rows. That is D's second half, and it is an inventory change, not an architecture change. Measure: the interface_stats row set from both daemons on the same topology, which the drop-in property makes a single-driver comparison.

What would not change it is a future firmware with more RAM. The argument above is about where the mechanisms live, and that is the same on a board with 96 KiB of heap and on a server with 96 GB.

One correction this page owes

Bluetooth interfaces records an earlier "Stage B" plan to model ble-reticulum as "one ordinary byte only interface per connected peer (the Columba BLEPeerInterface shape)". That is option A, written before #365 and #376 built the peer hint and before anyone read what the Columba child actually does on the peripheral side. This page supersedes that paragraph; the surrounding argument there — that the broadcast plane and the link plane are two interfaces and not one clever hybrid — is unaffected and still holds.

The Core Lock Budget

The async driver owns exactly one NodeCore behind one mutex (leviculum-std/src/driver/mod.rs:1321). Every packet the node decrypts, routes, forwards or emits passes through it. It is the narrowest point in the stack, and the rule that follows from that is:

No caller holds the core lock across CPU-heavy work. Work that scales with payload size runs off the lock, between a cheap capture and a cheap commit.

This is not a style preference. It was measured.

The measurement that set the rule

NodeCore::send_resource used to run its whole build — bz2 compress, bulk token encrypt, full/map hashing — inside the mutex. For a 1 MiB incompressible payload with compression on, that was a 141 ms hold in release. On a 20-link inbound flood it cost a 32 % inbound throughput stall while round-sized sends ran; ~0 % after the fix (Codeberg #152).

The fix is the three-phase shape, and it is the house idiom for anything with the same profile:

Commit re-validates what could have changed while the build ran unlocked: link gone, a transfer raced in, or the link re-keyed (#66) — the last returns the retryable ResourceError::LinkStateChanged and the caller rebuilds once. The std driver calls the three phases itself (leviculum-std/src/driver/mod.rs:3602).

NodeCore::send_resource still exists as the composed single call (leviculum-core/src/node/mod.rs:1543) because no_std and FFI callers have no lock to hold and no second thread to starve. It is the composed form that is dangerous behind the driver, not the code it composes.

The numbers, restated for callers

Measured with leviculum-core/compression on (as leviculum-std builds it), comparing the composed call against the locked portion of the phased path.

The conditions, because a timing without them is an anecdote: profile release, target x86_64-unknown-linux-musl, an AMD Ryzen 9 7950X. Each cell is the median of five timed runs after one discarded warm-up, and each run builds a freshly linked pair — a second Resource to the same link cannot build at all (ResourceError::TransferInProgress), so re-using one would not repeat the measurement. Both harnesses are #[ignore]d and print every number below: measure_send_lock_costs (leviculum-lxmf/src/node.rs:2607) for the send tables, measure_deferred_tick_costs (leviculum-lxmf/tests/direct_delivery_attempts.rs:1560) for the tick table.

Every column names the bytes it was given, because the cost being reported is a compressor's and a compressor's cost is a property of its input. The three classes are generated by incompressible (leviculum-lxmf/tests/common/payloads.rs:32), compressible (leviculum-lxmf/tests/common/payloads.rs:79) and degenerate (leviculum-lxmf/tests/common/payloads.rs:104), and both harnesses below take them from the same array so neither can drift onto different bytes under the same name:

The first three columns are the composed call under the lock; the last is the locked half of the phased path, which does not vary with the payload because no payload passes through it.

Incompressible data is the worse case, not compressible data. An earlier revision of this page said the opposite — "bz2 does more work when it succeeds" — and the measurement above refuses it at every size: compressible text costs 0.54x to 0.75x of incompressible bytes of the same length. The mechanism is that the Burrows-Wheeler sort is paid in full either way, and a run that succeeds then has less output left to code, not more. Plan for the incompressible number: it is both the larger one and the one an attachment actually hits, since anything already compressed looks incompressible to bz2.

Without the compression feature — the embedded default — the 1 MiB build drops to 6.4 ms, which is why the same code is tolerable on an nRF52 and intolerable behind the driver. That figure is from the #152 pass and was not re-measured here.

The segment boundary sits under the 1 MiB row

RESOURCE_MAX_EFFICIENT_SIZE is 1 048 575 bytes (leviculum-core/src/resource/mod.rs:69) and the split is decided on the packed, uncompressed length (leviculum-core/src/resource/outgoing.rs:106), so a 1 MiB body is above it in every payload class — the compression ratio does not move the boundary. The 1 MiB row therefore measures segment 1 of a two-segment transfer, not a whole one. Segments 2..N are built on the receive path, under the caller's lock, and the phased path does not cover them.

That also bounds who can reach the row at all. Python LXMF refuses an incoming delivery Resource larger than DELIVERY_LIMIT × 1000, which is 1 000 000 bytes (delivery_resource_advertised, reference/LXMF/LXMF/LXMRouter.py:1977) — below the segment boundary. So no LXMF transfer that a Python peer would accept is ever a two-segment one, and the segment path is reached only by a Rust-to-Rust transfer or a non-LXMF core Resource user.

What the payload class was worth, as a number

This matters beyond bookkeeping, because a table measured on degenerate was once proposed as a correction to this page. On the same machine and profile, degenerate reads 8.5x below incompressible at 1 MiB and 12x below it at 16 KiB: bz2's run-length front end collapses a single repeated byte before the Burrows-Wheeler transform ever runs, so the number that comes out is the cost of compressing almost nothing.

Two other candidate explanations for a table reading low were tested and do not hold.

A missing warm-up is not one. The harness prints the run it discards next to the median it keeps, so this is checkable rather than assumed: every cell above 1 ms has its cold run within 2 % of its median, and the largest gap anywhere is 11 % — on degenerate at 16 KiB, the cheapest cell in the table at 154 µs cold against 139 µs. An n=1 harness on this path is imprecise; it is not biased low.

A build-profile difference is not one either. This run reproduces the figures the page carried before it — 1.7, 16.4 and 65.2 ms — to within 4 % on the incompressible column, so those were release-profile numbers taken on comparable hardware, and the column they belong to is incompressible.

Costs that do not justify phasing, measured the same way: packing a 1 MiB LXMF message is 0.8 ms, and unpacking one with signature verification is 3.2 ms. Inbound verification cannot be phased away — the bytes are already in hand — and at that magnitude it does not need to be.

The adapter-side number: LxmfRouter::tick

Measured during the #196 design pass, on the same machine and profile: one LxmfRouter::tick with 8 due 256 KiB messages holds 126.6 ms in a single uninterrupted borrow. It is the composed-send_resource cost of the table above, multiplied by a queue depth an adapter reaches routinely — the router builds each due message in turn, and nothing between them yields.

That figure is consistent with the table above: eight times the incompressible 256 KiB build is 127 ms.

LxmfRouter can hand the build out instead, under RouterConfig::defer_resource_builds (leviculum-lxmf/src/router.rs:124). What the tick then costs, for one due message, measured the same way:

The deferred column is flat across all three payload classes — 13.6 to 14.6 µs at 16 KiB, 282 to 300 µs at 256 KiB — which is the mechanism showing through: a deferring tick copies bytes and does not compress them, so the class it was handed cannot matter. What is left in it is the Message clone, and that is why the deferred column still grows with size at all.

One due message rather than the eight above, because a second Resource to the same link is refused before it builds, so an eight-message comparison would not be comparing like with like. The composed column carries the router's own tick work on top of the build, which is why it reads a little above the send table at the same size; the gap is under 3 % at every row.

It is recorded here rather than in the issue because this page is where a caller looks for it, and because a number that lives only in a tracker cannot be cited from the tree: PROCESSOR_TICK_BUDGET (leviculum-std/src/driver/processor.rs:181) is set against this measurement, and until it was written down the only number behind a public constant could not be traced at all.

What this binds

Any protocol adapter layered on the core. leviculum-lxmf is the current instance and leviculum-lxst will be the next. An adapter that offers only a monolithic submit call forces its host either to hold the lock for the build or to fork the driver. Adapters that are expected to run behind the async driver expose the phase split; the composed form stays for the embedded caller.

Anything the driver runs inside its event loop. The loop's dispatch_output (leviculum-std/src/driver/mod.rs:5247) routes actions to interfaces and forwards events. Work done there blocks not just the lock but interface I/O dispatch — strictly worse than the mutex case. The in-loop /status responder (leviculum-std/src/driver/remote_mgmt.rs:82) is the reference for how much is acceptable there: take the lock, build a small bundle, hand back a TickOutput, return.

Two things the loop's callees may never do. They may not .await, and they may not call back into the driver's public async API: those methods end in action_dispatch_tx.send(output).await on a bounded channel that the same loop drains, so a full channel deadlocks the node.

Those are one rule, not two, and knowing which way round matters when you have to enforce it. The second is a consequence of the first: an async fn called and not awaited builds a future and drops it, sends nothing and blocks nothing. The deadlock needs the bounded-channel send to complete, and only .await can complete it. So a callee expressed as a synchronous fn has both prohibitions closed at once, which is what the in-driver core processor (#196) is built on — see leviculum-std/src/driver/processor.rs. It follows that a runtime guard on the async API would be the wrong shape: there is nothing to guard until an .await that cannot be written.

The residue is re-entrancy, not the async API

Both prohibitions above are special cases of a plainer one, and stating them first got the emphasis wrong for two commits. The loop calls its callees with the core mutex held, and that mutex is a non-reentrant std::sync::Mutex. Any path from a callee back to it hangs the node immediately — first call, no load required.

The async route is one such path and not the instructive one. Consider the block_on case the previous wording named as the whole residue: a callee that smuggles a PacketSender and blocks on send does not reach the bounded channel at all, because PacketSender::send (leviculum-std/src/driver/sender.rs:92-107) takes the core lock in a block and releases it before its .await. It deadlocks one line earlier, on the mutex.

And no block_on is needed. The number is 58, and it is a number rather than a phrase on purpose: scripts/check-core-lock-census.py rebuilds the list of public methods that lock the core out of the sources on every just fast and pins it, name by name, in a checked-in file (TOTAL, scripts/core-lock-census.txt:30). Two earlier revisions of this page estimated the size of this set in words and were low by nearly half — which is what an estimate nothing can check is worth.

53 of them are on ReticulumNode — plain synchronous pub fns that open by locking the core, of which has_path (leviculum-std/src/driver/mod.rs:3085) is self.inner.lock_recover().has_path(dest_hash) and entirely typical. The other five are on PacketSender and LinkHandle, which matters more than the count suggests: those are the two handles a callee is most likely to have been handed in the first place.

A callee holding an Arc<ReticulumNode> deadlocks the node on its first invocation, in ordinary safe synchronous code, with no .await, no channel, and nothing a compile-fail fixture can catch.

So the rule for anything the loop calls is: hold no handle to the node you run inside. The &mut StdNodeCore the seam hands out locks nothing and is the whole intended surface. Everything else belongs on the far side of a channel.

What holds this up is not the type system. It is that registration happens on the builder, before the node exists, so a callee cannot be constructed holding a node handle — injecting one afterwards takes a deliberate OnceLock or Weak and a reference cycle. That is a construction-order barrier, and it is why the hazard stays theoretical in practice. It is not a guarantee, and this page should not be read as offering one.

The one call the seam hands out that this page forbids

NodeCore::send_resource is pub (leviculum-core/src/node/mod.rs:1747) and therefore reachable on the &mut StdNodeCore a processor hook holds. It is the 141 ms composed call this page opens with — one line, in consumer code, behind the driver and under the lock. PROCESSOR_TICK_BUDGET reports it 141 ms after the fact and cannot prevent it, and no fixture can refuse it: it compiles, because for the no_std and FFI callers it is the correct API.

A hook that has to send a resource uses the three-phase form the driver itself uses — resource_send_params, prepare_resource_send off the lock, commit_resource_send — or hands the send to the application side of a channel. This is named again in leviculum-std/src/driver/processor.rs where a consumer will meet it.

Work that is already off the core by construction

Proof-of-work stamp generation borrows only its executor, never the router and never the core (leviculum-lxmf/src/router/stamp_runtime.rs:26). The router emits a pending-stamp event, the application computes the stamp on whatever schedule it likes, and hands the result back. This matters because a peer chooses the stamp cost: an announced cost of 254 is legal and effectively unfinishable (#185). If that search could ever run under the core lock, any peer could stop the node by announcing a number. It cannot, and no seam added later may make it possible.

That pattern — emit a request, compute detached, submit the result — is the general answer whenever the cost of a step is not ours to bound.

One correction to the paragraph above, because its phrasing is wider than what holds. It is exactly true of the peer-priced search, which is the one that matters: generate_with is an async fn, so no synchronous callee of the event loop can drive it to completion at all. It is not true that the tree contains no synchronous proof-of-work. leviculum-core::discovery::stamp::generate_stamp (leviculum-core/src/discovery/stamp.rs:176) is a public synchronous brute-force loop taking a caller-supplied cost, and nothing stops a loop callee from calling it. It is not a DoS vector today because no peer picks its number: the only caller is the discovery announcer, which runs it once per discoverable interface during ReticulumNode::start() — off the loop — at the locally fixed DEFAULT_STAMP_VALUE. The invariant to keep is therefore "no peer-chosen cost is ever ground synchronously", and the async signature is what enforces it.

That fixed cost is not static across RNS versions: #328 raised it from 14 to 16 to stay visible to RNS 1.5.0 listeners, and each extra bit doubles the search. Measured on the coder host (release build, x86-64), one mint went from 39 ms mean / 198 ms max to 191 ms mean / 737 ms max over 24 samples. It is paid once per discoverable interface at wiring time and the result is reused for every re-announce, so this is startup latency, not a per-announce or per-loop cost. The budget argument is unchanged; the number it is measured against is four to five times larger.

A diagnostic write is inside the budget too (#418)

The budget above is about CPU: work whose cost scales with a payload. The miauhaus soak found the other half, and it is worse, because nothing about the call site looks expensive.

Over 49 days and 397 023 881 events, the node's 10 s PATH_TABLE liveness heartbeat missed at least one beat 2 928 times out of 421 605 intervals, with a tail to 37.0 s. During each of those the daemon emitted nothing at all — no packet, no announce, not the heartbeat — on a node that otherwise logs 30 to 150 events a second. Both long stalls pulled out of the raw log have the same shape: the hole sits between the ANN_RX of one announce and the PATH_ADD of that same destination, a span in which nothing can take seconds.

The emission can. Until #418 the event-log layer wrote each line with a blocking write(2), flushed, under a process-global mutex, on the thread that emitted it — and the event loop emits while it holds the core mutex (apply_inbound, leviculum-std/src/driver/mod.rs:4456). A write(2) to a USB disk under writeback throttling blocks for seconds, so the loop stopped, and everything that wanted the core queued behind it. That is why the symptom was total silence rather than a missing log line.

The rule that follows is the CPU rule's sibling:

No caller holds the core lock across an I/O call whose latency belongs to a device. A diagnostic that can stop the transport is a worse bug than the missing diagnostic.

The event log now inverts the trade (FileSink, leviculum-std/src/event_log.rs:1332): the emitting thread does a bounded enqueue and returns, one writer thread owns the file, and an overrun drops lines and says so with EVENT_LOG_DROPPED rather than blocking the mesh. LEVICULUM_EVENT_LOG_SYNC=1 restores the old behaviour for anyone who would rather block than lose a line, and it is what the mvr's positive-control arm runs.

What measures this

Three events, all threshold-gated so a healthy node emits none of them, and deliberately at different altitudes so they disagree informatively:

CORE_STALL without ANN_SLOW means the loop was stopped by something other than announce handling; EVENT_LOG_WRITE_SLOW alongside it names the disk. The watchdog measures the wait for the core mutex, never the hold, which is exactly "how long the loop spent not polling" without an Instant in a dozen select! arms.

A durable store append is inside the budget too (#384)

The #418 rule above is about a diagnostic, and a diagnostic can be dropped. The propagation node found the same shape in work that cannot be: storing a message somebody sent us.

lnpnd ran for 32 minutes in the public mesh on miauhaus (2026-09-21) and emitted 73 CORE_PROCESSOR_OVER_BUDGET warnings out of 324 log lines, 54 of them under hook="on_event" and 19 under hook="on_tick", with nine over 100 ms. lnsd on the same host, same uptime, same traffic: none. The worst one names its own cause in the line above it:

10:25:12 lnpnd: sync in peer 535d9c5db65bfcd4 transferred 105 (30240 B): ok
10:25:12 CORE_PROCESSOR_OVER_BUDGET hook="on_tick" elapsed_us=239016 budget_us=5000 events=0

A quarter of a second of core lock, having processed events=0. The time was not in event work; it was in the store. FilePropagationStore::append is a write, an fsync, a rename and a second fsync (leviculum-std/src/file_propagation_store.rs, "Power-cut safety, and why this store fsyncs"), and the engine stored the whole inbound batch inside the one hook that classified it.

The attribution is a measurement, not a reading of the code. 105 appends of 288-byte bodies cost 124 µs into a memory store and 127-189 ms into the file store on the coder host's ext4, over six runs — 1.1 to 1.5 ms each, worst single append 6.4 ms. Three orders of magnitude, on the same verb with the same bytes: the cost is the device, not the book-keeping. append_cost (leviculum-std/src/file_propagation_store.rs) prints both lines on whatever filesystem it is pointed at, and pointing it at a tmpfs — where fsync never reaches a device — reads 60x cheaper and proves nothing.

Two things follow, and only one of them is a fix.

The store cannot be the layer that fixes it. The fsyncs are what makes "persist before you prove" true (docs/src/concepts/propagation-node-on-a-board.md §3): dropping them trades a message for a millisecond. The cost is the device's, and the device's cost is not negotiable from this side.

The hook is. lnpnd's engine now queues validated payloads and stores PERSIST_PER_HOOK of them per hook (lnpnd/src/engine.rs), asking the driver to come straight back for the rest; a peer's batch is resumable across hooks (PeeringRuntime::advance_sync_resource, lnpnd/src/peering.rs) and still reports itself as one round. The batch still costs what it costs in wall-clock — the disk did not get faster — but the core lock is released between messages, so the node keeps answering while it absorbs a sync.

A cost that cannot be made cheap and cannot be dropped is still a cost that may not be paid all at once under the lock. Bound the work per hook and come back.

What this does not buy: one append can exceed the budget on its own — 6.4 ms measured, against a 5 ms budget — so CORE_PROCESSOR_OVER_BUDGET can still fire on a slow disk. What is gone is the multiplier, which is the part that scaled with someone else's batch size.

A diagnostic's volume is a cost too, and the cadence is the wrong lever

The same log gave the other half of the lesson. Of those 397 023 881 events, 214 594 631 — 54 % — are PATH_TABLE_ENTRY, the per-path snapshot of the path table; in the last megabyte of the live tail it is 77 %. The file is 61 GiB and grows ~2.6 GB a day.

That share is what remains after a fix. The dump used to fire every 10 s; 5ab938a4 (2026-07-13) moved it to every five minutes and cut its volume thirtyfold. It did not settle the problem, because a cadence is the wrong lever for this cost:

One snapshot costs one line per path. The miauhaus path table is 22 362 entries — the number is in the heartbeat itself, PATH_TABLE node=miauhaus size=22362. Five minutes apart, that is still ~6.4 million lines a day, and it grows with the mesh, not with anything the code chose.

Against that cost, nothing consumes the lines. The soak's analyze.py puts them on a count-only fast path and never reads dst, hops, iface, next_hop or expires_in_ms; periculum does not reference the event at all. And the one number counting them yields — how many paths there are — is already emitted every 10 s as PATH_TABLE size=.

So the dump is now off by default (TransportConfig::path_entries_dump, config key path_entries_dump under [reticulum]), reachable for a debugging session that wants the per-path fields. Nothing else moved: the 10 s PATH_TABLE heartbeat still carries liveness and the count, and PATH_ADD still records every insertion, so the path table's history survives the silence.

The rule, sibling to the one above:

A diagnostic whose volume scales with mesh state, not with a rate the code picks, is not a diagnostic you can leave on. Gate it, and keep the cheap scalar that answers the question people actually ask of it.

The Self-Deadlock Tripwire

A deadlock is the worst failure this daemon produces. A panic leaves a stack and an exit code; a dropped packet leaves a counter; a wrong answer leaves a log line somebody can grep. A self-deadlock leaves nothing at all. The node stops, keeps its listening socket open, and reads as healthy to every supervisor watching it.

This page records what detects one, what it costs, which decisions were made against project precedent, and what it does not reach.

The hazard

93ba351 shipped [CoreProcessor], a seam that runs consumer code inside the driver's tick. Both entry points — run_event_tap and the timer branch's run_tick — call the consumer's hook with the core std::sync::Mutex guard live, because handing the hook &mut StdNodeCore is the entire point of the seam.

std::sync::Mutex is not reentrant. So any handle the consumer smuggled in that re-locks the core parks the driver's event loop on a lock only that same loop can release. ReticulumNode::has_path (leviculum-std/src/driver/mod.rs:3084-3086) does it in one line, and it is one of roughly forty synchronous pub fns on ReticulumNode shaped exactly like it. No .await, no unsafe, no channel — nothing a compiler or a compile-fail fixture can see.

The seam's own defence is a construction-order barrier, not a guarantee: a processor is registered on the builder, before the node exists, so it cannot be built holding a handle to the node it will run inside. Getting one takes a deliberate OnceLock/Weak cycle. That is why the hazard is theoretical rather than routine — and it is exactly what a future set_core_processor on a live node would give up.

Two things that were tried on paper and are not the answer

try_lock that reports instead of blocking is strictly worse. From the same thread try_lock returns WouldBlock, so has_path would answer false for a destination that has a path. A loud deadlock becomes a silent wrong answer inside routing, which is the worse failure for Priority 1. It would also mean turning roughly forty public accessors fallible, a breaking change for every consumer, to defend against a hazard reachable only from inside the seam.

Type-system prevention does not exist. The processor is Box<dyn CoreProcessor> and its struct is opaque by construction. Every bound available ('static, Send) is already applied and none can express "holds no Arc<ReticulumNode>".

Detection is the remaining avenue.

The mechanism

MutexRecover::lock_recover (leviculum-std/src/sync_ext.rs) is the single choke point: every std::sync::Mutex acquisition in leviculum-std goes through it, 149 call sites against one implementation.

Before it blocks, it records the mutex's address in a thread-local set. An address already present means this thread is about to wait for a lock only this thread can release, which never wakes. The guard it returns (TrackedGuard) removes the address on Drop.

Three properties are worth naming because each is a defect if it is wrong:

• Removal is by address, not by position. Guards are values and nothing forces them to drop in acquisition order. Popping the top would evict the wrong entry and leave a stale address behind — a false positive on the next acquisition of a mutex that was released long ago.
• The set is per thread. Another thread holding the mutex is an ordinary wait, not a self-deadlock. TrackedGuard is !Send for the same reason a MutexGuard is, which is also what makes the thread-local sound: a registration can never be read from a thread other than the one that made it.
• An unwind must clean up. A hook that panics for an unrelated reason unwinds through the guard, and if the address survived that, the next acquisition on that thread would report a re-entry that is not one. The tripwire's worst failure mode is a false positive in production, so this has its own test.

Depth is capped at 32 held mutexes per thread — the crate's deepest measured nesting is 4 — and exceeding it is reported as LOCK_DEPTH_OVERFLOW rather than absorbed. Past that point a negative answer means nothing, and a check that has quietly stopped checking is the failure mode Checks That Are Actually Checks exists to remove.

The measurement that chose the shape

Two shapes were on the table. The narrow one — a static CORE_LOCK_OWNER: AtomicU64 written by the tap and the timer branch, read in lock_recover under #[cfg(debug_assertions)] — is scoped to the one lock and the two callers we currently suspect, and does nothing in release, which is where the deadlock actually bites. The broad one is the thread-local address set above, which covers every mutex and every caller and needs nobody to have guessed right.

The question that settles it is what the broad shape costs on a real workload.

Per acquisition (release, opt-level=3, uncontended mutex, 20 M iterations, best of 5, four-core host):

In an unoptimised build the same three are 24.6 / 26.5 / 67.1 ns, because nothing inlines; that is a test-run cost, not a shipped one.

Acquisition rate on a real workload. The TCP-hub load test (leviculum-std/tests/rnsd_interop/loadtest_tcp_hub_tests.rs) driving the real lnsd binary at 128 steady connections, one packet per connection every 15 ms for 40 s, 377,572 packets forwarded at 100 % delivery: 2,061,220 acquisitions in 42.56 s = 48,428/s, or 5.46 acquisitions per forwarded packet.

So the prediction is 2,061,220 × 0.458 ns = 0.94 ms of CPU across the whole 42.6 s run — 0.0055 % of the hub's 17.1 s of CPU time, and 2.5 ns against the 45.4 µs of CPU the hub spends per forwarded packet, about one part in eighteen thousand.

And the end-to-end A/B agrees, which is the point of doing both. Two release lnsd binaries differing only in the tripwire, alternated over the same load:

Delta −0.04 %, against a run-to-run spread of ±6 % on the same binary. Delivery was 100.0000 % on every run of both. A null A/B on its own would only say the effect is below the noise floor; paired with the prediction it says why — the effect is three orders of magnitude below it, and no amount of extra runs would resolve it.

It is noise. The broad shape wins, on the criterion set before the numbers were taken.

Panic, not log-and-hang — and in release too

Both decisions follow from the same observation, and neither inherits from the poison precedent above it in sync_ext.rs.

Why not log-and-hang. Project policy prefers a degraded daemon to a crashing one, and MutexRecover's poison recovery argues exactly that. But that argument does not transfer, because there the daemon really is degraded and still serving: the panicking task has unwound, every other task still runs, and the node keeps forwarding. Here the thread about to block is normally the driver's event loop, and once it stops the node forwards nothing, answers no path request and maintains no link — while holding its listening socket open. That is not degraded operation. It is a stopped node wearing a healthy face, and Priority 1 is packet delivery, of which this delivers zero.

Panicking is also, for the hazard this exists for, the cheapest possible recovery — because the seam already catches it. run_event_tap and run_tick wrap every hook in catch_unwind. The unwind releases the outer core guard (poisoned, which lock_recover then recovers), the driver logs CORE_PROCESSOR_PANICKED, detaches the offending processor permanently, emits NodeEvent::CoreProcessorPanicked on the application's control plane, and carries on serving the mesh without it. That is precisely the graceful degradation the policy asks for, and log-and-hang forfeits it. Away from the seam, a report here means an ordinary lock-order bug in our own code on a path some test exercises, and failing at the defect beats hanging at it.

Why release carries it. Debug-only was the cheap answer and it does nothing where the deadlock actually bites: a #[cfg(debug_assertions)] check is absent from every binary an operator runs. The only argument for compiling it out is cost, and cost is 0.0055 % of a busy hub's CPU. There is nothing to trade.

The standing canaries

Per Checks That Are Actually Checks: a tripwire that has silently stopped tripping satisfies "no deadlock detected" forever, so the demonstration is permanent rather than one-time. Both halves live in leviculum-std/src/sync_ext.rs and run in just fast (cargo test --workspace --lib):

• canary_re_entering_one_mutex_trips — a re-entry the detector is meant to see, asserting the report names both the failure and the mutex.
• canary_distinct_mutexes_nest_without_tripping — legitimately nested different mutexes, which must not fire. Without it the positive canary is satisfied by a tripwire that reports everything, which would take the daemon down on its first tick.

The acceptance test is leviculum-std/tests/mvr/core_lock_reentrancy.rs: a registered CoreProcessor calling has_path on the node it runs inside, plus a negative control that is the same node with a processor that does not re-enter. That test hung forever before this landed, which is why it carries two independent bounds — a tokio::time::timeout on a runtime the node does not own, and Drop for ReticulumNode, which polls for at most 400 ms and then calls Runtime::shutdown_background. Verified by disabling the tripwire by hand: the test fails in 15 s with a message naming the deadlock, and the binary exits normally.

What this does not reach

• Deadlocks between two threads and two mutexes. A holds M1 wanting M2 while B holds M2 wanting M1 is a lock-order inversion, and neither thread's own set contains what it is waiting for. Detecting that needs a wait-for graph across threads, which is a different mechanism and a different cost.
• Mutexes not taken through lock_recover. tokio::sync::Mutex, any RwLock, any .lock().unwrap() that skipped the trait, and every mutex outside leviculum-std. The choke point is what makes this cheap and it is also its boundary.
• Blocking that is not a mutex. A hook that blocks on a channel, a socket or a block_on stalls the loop just as completely and is invisible here. The core lock budget is the surface for that, and it reports after the fact rather than preventing.
• Depth beyond 32 on one thread, which is reported and then untracked.

See also

• The core lock budget — what a hook may cost while it holds the lock, as opposed to whether it may re-take it.
• Checks That Are Actually Checks — the standing-canary rule this page applies.

Bluetooth interfaces

Reticulum uses Bluetooth in three distinct ways. They are not variants of one interface, they are three separate carrier protocols with different connection models, different peers, and different scaling behaviour. This chapter names them, maps them to what Python-RNS and the Columba app call the same things, and records the design decisions behind them.

The actionable status and open work for each lives on Codeberg, not here. This chapter is the durable concept; the tracker is the source of truth for what is done.

The three protocols at a glance

Naming and lineage

Two of these already exist in the wider ecosystem, so we adopt their names to keep wire compatibility obvious. The third is our own invention.

ble-leviculum is a BLE 5 connectionless broadcast carrier for Reticulum packets. It is leviculum originated and is not an upstream RNS standard. We chose a name in our own namespace, not ble5-reticulum, on purpose: this protocol interoperates with nobody yet, and the *-reticulum namespace is not ours to reserve. The name itself marks it as ours, which sets it apart from the two protocols above whose names we adopted because we must match their wire.

The no_std layering

Every Bluetooth interface splits into two layers, and the split follows the interface isolation rule (see Interface isolation).

• Carrier logic, no_std. Framing, fragmentation and reassembly, the protocol state machine. This belongs in leviculum-core, which is no_std and already builds for thumbv6m. BLE framing already lives in leviculum-core/src/framing/ble.rs. Keeping the carrier logic no_std means the same code runs on the nRF firmware and on the host.
• Platform binding. The radio and OS specific glue. On nRF this is the SoftDevice glue in leviculum-nrf (no_std). On lnsd this is a Linux BLE stack, candidate bluer over BlueZ via DBus (necessarily std). On a phone it is the OS BLE API.

The goal is no_std carrier logic wherever possible so it runs on embedded devices. One known exception: the RNode over BLE byte channel seam currently lives in leviculum-std with tokio traits, so it is std only. A no_std variant over embedded-io-async would be needed for on device use, tracked separately.

RNode over BLE

BLE is used purely as a cable. The far end is an RNode radio that speaks the RNode KISS protocol; leviculum still drives detection, configuration and the radio lifecycle. The peer is not a Reticulum node.

The enabling work is a generic byte channel seam: drive the RNode lifecycle over any duplex byte channel instead of a serial port path, so a process that never sees a serial device (Android USB host, BLE GATT, iOS BLE) can still run an RNode. Compatibility is unaffected, the serial path is unchanged and the wire format does not change.

ble-reticulum (BLE 4 link mesh)

Each nearby device is a full Reticulum node. A node opens one connection oriented GATT link per peer, acting as both peripheral (GATT server) and central (scan and connect). Columba implements this as the ble-reticulum Python package with a BLEInterface for protocol handling and one BLEPeerInterface per connected peer.

To interoperate with Columba we must match its wire spec, "Protocol v2.2": a fixed service UUID 37145b00-442d-4a94-917f-8f42c5da28e3, RX and TX and Identity characteristics, and the connection handshake. The Identity characteristic carries a stable Reticulum transport identity hash so peers can be tracked across the BLE MAC address rotation that phones perform for privacy.

The hard limit of this protocol is the number of simultaneous links. Columba caps at MAX_CONNECTIONS = 7 and Android allows about 8 BLE connections total across all apps; in practice 3 to 4 links are reliable. This protocol therefore does not scale to a dense mesh, which is the motivation for ble-leviculum.

Incoming link slots and the slot-contention policy

An LNode accepts three incoming (peripheral-role) links and initiates one outgoing (central-role) link (#372), and since #432 lnsd has the same shape: max_connections (default 4) still means the total, and inside it one slot is this node's own dial and max_connections - 1 are incoming. Before #432 the budget was undivided, and a node that filled it in either direction both stopped advertising and stopped dialling. That is how the rig's regression/ble_room_10 --seed 2 room ended ABSORBING: nine boards formed eighteen links among themselves, all nine went dark, and the tenth — holding the room's lowest address, so the sort said it must dial everyone and nobody may dial it — arrived 4 s late to a room with nothing on the air. No link ever died to free a slot, and the #375 fallback verdict each of the nine held on its advertisement died on their own full-table gate. The split makes the two questions independent: may-dial reads the OUTGOING slot (an lnsd with three incoming links still dials), on-air reads the INCOMING slots (an lnsd that has spent its dial still advertises and still accepts). Those same nine boards then land eight dials instead of eighteen and every one of them is still advertising when the tenth arrives. Admission does not widen for it: admit refuses a surplus link by role, so nothing on the air is over-promised. Three incoming slots dissolve the single-slot field failure where two boards beside a phone paired with each other first and the phone could only reach the board whose one slot was still free: with slots to spare, a neighbour board and a phone link to the same relay simultaneously.

The SoftDevice RAM cost of this configuration (conn_count = 4, periph 3, central 1) is measured, not extrapolated: the S140 wants an app RAM base of 0x20005DA0 (23 968 B), 928 B under the linked ceiling in leviculum-nrf/memory.x (rig T114 SD_RAM_FLOOR, 2026-09-08). The margin is deliberately small — the requirement is a fixed, deterministic property of this exact configuration and the boot-time SD_RAM_FLOOR assert refuses any config that outgrows it.

There is deliberately NO preference of a phone over a board for the last free slot. With more slots than nearby peers the policy would decide nothing, and deciding it well needs information a connect-time policy does not have (which peer carries traffic the mesh needs). It becomes worth revisiting when a deployment has more adjacent boards than a relay has slots — the boards can then occupy every slot before a phone arrives, which is the single-slot failure again, one layer up. The firmware keeps advertising while any slot is free and goes silent when full, so a scanner not seeing the relay is the honest signal of that state.

Initiation direction, the fallback, cycles and duplicate links

Who initiates is the v2.2 address sort: the lower BLE address dials, the higher one advertises and waits (with the v0.3.0 capability override for peripheral-only peers). The sort alone does not reliably connect a room of boards (#375): a full board stops advertising, so the highest addresses can run out of permitted targets and sit scanning forever while the sort forbids them to dial anyone lower. A Monte Carlo of random arrival orders puts ten boards at a 21 % chance of a disconnected BLE graph under the pure sort.

The fallback closes the stranded-board gap: a central task that has scanned for SCAN_FALLBACK_AFTER_MS (30 s) without a single initiate verdict, and without a connection event in either role, accepts any advertising Reticulum peer (BLE_SCAN_FALLBACK marks the switch, once per strict phase, and the verdict logs as rule=initiate_fallback in BLE_SCAN_DECISION). Full boards do not advertise, so a fallback dial only ever lands on a free slot. The rule stays pure and host tested in leviculum-nrf/ble-tx (should_initiate with a ScanMode input); the firmware measures the time and hands the mode in.

The clock is eager: it runs whenever the outgoing slot is free, live links notwithstanding, so a board that holds links but keeps losing the sort can still dial a third party and merge two components. Two guards make that safe. A live connection's address is excluded before it can leave the scanner (the registry's addr_linked): the Core Spec permits one connection per address pair (Vol 6 Part B §4.5), so such a dial could only time out — the rig once showed exactly that, a doomed 5 s dial at an already-linked peer every ~20 s, forever. And a fallback target that does not even connect goes into a dead-end table for two minutes (BLE_DIAL_DEAD_END, sized to the RPA rotation timescale), so a vanished advertiser is not re-dialled every backoff. The interim alternative — suspending the clock while any link is live — was shipped briefly and measurably cost merges: 28 and 78 all-linked splits per 1000 arrival orders at 10 and 20 boards, against eager's zero, because a component whose boards all hold some link can never initiate a cross-component dial.

Which eligible advertiser gets dialled is not first-heard-wins: the scanner collects one bounded window (BLE_SCAN_WINDOW) and dials the best eligible candidate, via a CandidateTable shared by the firmware, lnsd and the simulation. Best is, in order: strict verdicts before fallback verdicts, then the peer with the MOST free incoming slots, then the lowest address. First-heard-wins is what produced the saturated-cycle lock — fallback dials closing cycles inside their own component until nobody scans — measured at 48 of 1000 arrival orders for twenty boards; the window's choice removes it entirely.

The free-slot count is the middle term, and boards put it on the air themselves: capability bits 1-2 of the v0.3.0 record carry how many of the three incoming slots are still free, bit 3 says the count is present at all (leviculum-nrf/ble-tx/src/adv.rs). Without it a searching board picks blind between a peer with three free slots and one with its last one free, so several searchers elect the same board and all but one are refused. In the arrival-order simulation the preference leaves connectivity untouched (0 of 1000 orders disconnected at both sizes, as before) and halves the boards that end saturated: 976 to 498 at ten boards, 2538 to 914 at twenty.

Three properties keep it honest:

• It is a hint, never a permission. Nothing in the duplicate or refusal path reads it. A board that advertised a free slot and has none by the time the connection lands refuses exactly as before.
• It can understate, never overstate. The advertisement is rebuilt at each advertising start, and an incoming link can only land on the board that is currently advertising — which then stops and lets the next free task advertise the new, lower count. A slot freed while another task is mid-advertisement stays unannounced until that advertisement resolves, so the air can lag behind a board that got emptier, never behind one that got fuller. No running advertisement is stopped to rewrite it, so no advertising interval is dropped.
• Silence is not zero. A peer that advertises no count — an older board, a phone, another implementation — is ranked as if all its slots were free, the same "assume full capability" the v0.3.0 §3.2 rule applies to the capability flags, so it keeps exactly its pre-#375 standing. Bit 3 exists precisely so that an older record with only bit 0 set cannot be read as "zero slots free".

lnsd publishes the count too, since #432. Until the asymmetric cap it did not, and the reason was not modesty: its capacity was one budget shared by both roles, so a number in the boards' units would have been a different quantity wearing the same bits. With one outgoing slot and max_connections - 1 incoming, lnsd's free-incoming count IS a board's free-incoming count, and it goes on the air from one shared builder (links.rs's capability_record against the firmware's, the same two calls) — so a peer can tell an lnsd record from a board's by the count in it and by nothing else. BlueZ cannot edit a live record, so a changed count is a deregister and a register; the published value is remembered beside the handle and compared, so that pair is paid when a link goes up or comes down and at no other moment. lnsd understates the same way a board does, for the same reason: the link is admitted before the record naming its slot leaves the air. And it now skips a peer advertising zero — a peer whose last incoming slot is gone cannot accept our dial, so the dial could only end in a refusal or, since a full node goes dark and a dark node cannot even refuse, in the 20 s setup timeout. That is the one place the count gates instead of ranking, it gates only our own spending of a dial, and silence is still not zero.

Two consequences of dialling against the sort are deliberate:

• Cycles in the BLE graph are harmless. Reticulum treats every interface as a lossy broadcast domain and deduplicates packets at the transport, so a packet arriving over two paths costs one discarded duplicate, not a loop; announce rebroadcast is suppressed the same way. Connectivity is what the graph owes the mesh, minimal edge count is not.

• A second link to an already linked identity is decided by the rule the PEER runs. It adds no reachability, burns one of three incoming slots and the airtime of a connect, so both roles resolve the identity at connect — read from the Identity characteristic as central, presented in the handshake as peripheral — and then apply one rule, judge_duplicate in leviculum-nrf/ble-tx/src/registry.rs, which lnsd calls too. Three branches, and the rule= token on every duplicate line says which one fired:

  1. rule=abandoned — the old link has delivered NOTHING, payload and keepalives alike, for LINK_ABANDONED_MS (30 s, two keepalive intervals). Its peer has walked away from it; the newcomer wins (BLE_LINK_REPLACED). This is the one case the peer's own arbitration never sees, so nothing it decides can contradict us.
  2. rule=same_role — both connections carry the same role, which a rotated address makes possible in either direction (the pre-dial exclusion is address-keyed, this rule identity-keyed). The peer then holds both in one role and has no central-vs-peripheral choice to make, so we decide alone: our own second dial is refused (it reaches nothing the live link does not), the peer's second dial wins (a node that dials again is done with the connection it has).
  3. rule=columba_mtu / rule=columba_identity — the general case: preferred_ble_role, a port of Columba's own preferredBleRole(centralMtu, peripheralMtu, localIdentity, peerIdentity), evaluated from the PEER's perspective. It keeps the role with the larger usable MTU and breaks a tie on identity order (localIdentity < peerIdentity keeps central), and we keep whichever connection it keeps. "Usable MTU" is the peer's own conversion, bounds included: usableValueLength(rawAttMtu) = (rawAttMtu - 3).coerceIn(20, 512) (columba/rns-host/src/main/kotlin/network/columba/app/rns/host/ble/model/BleConstants.kt:87-88). The ceiling is not cosmetic — at the top of the range ATT 517 and ATT 515 both read 512, so a pair holding those two connections is a TIE the identity order decides; reading the 517 as 514 would decide it by MTU instead, and the two sides would keep different links.

  Whichever branch fires, the LOSING link is disconnected by us at the decision, in either role — never left to the expiry.

  Why the peer's function and not a rule of our own (#360 round 2): the only duplicate rule that never leaves the pair linkless is one both sides compute identically from the same inputs. On 2026-09-12 at 21:41 the field T114 and a Pixel running Columba 2.2.4-beta each deduplicated in the OPPOSITE direction within one second. The board kept the newer connection because the old one's last payload was 15 185 ms old; the phone kept its own central because its ledger still read the new connection's MTU at the floor (centralPeerMtus[address] ?: BleConstants.MIN_USABLE_MTU, so MTU=20 although the ATT exchange had long settled at 517). Each side then closed the link the other had kept, and the phone's cancel did not even drop the ACL: our outgoing link stayed up for 45 s collecting Rejecting pre-identity write refusals until our own expiry. 45 s of dead air per rotation cycle — the same hole round 1 closed from the other direction.

  What that capture showed at the floor was a FRESH connection, one the phone had not bookkept yet, and the rule is built on it being transient: our own dial enters the peer's comparison at MIN_USABLE_MTU and is refused pre-handshake, while every other number in the comparison is the ATT MTU we negotiated, assumed to be the number the peer holds too. #377 puts that assumption in doubt from the peripheral end: on the desk 2026-09-09 a Columba peer listed a link the BOARD had dialled at "MTU 20 bytes" long after the exchange had settled, i.e. a peripheral-role ledger stuck at the floor for the life of the link. If its arbitration reads that number, a pair whose two connections negotiated the same MTU is a tie to us — settled by identity order, keeping the link we dialled — and an MTU decision to the peer, keeping the link it dialled, and the pair ends up linkless again in the identity order where those differ. Unconfirmed on the device: #377 waits for the capture #376 is taking, and whether our rule should model a peer's bookkeeping bug is that issue's decision, not a silent change of input here. The arithmetic of the divergence is asserted in a_peer_reading_its_peripheral_link_at_the_floor_decides_the_pair_the_other_way (leviculum-nrf/ble-tx/src/registry.rs), so a confirmation has one place to land.

  Why the liveness test is any-frame and not payload: Columba sends a 1-byte keepalive every 15 s on every connection it holds, so "any traffic within two intervals" is what distinguishes a link its peer still holds from one it has abandoned. Payload silence is what an IDLE phone looks like — it is not evidence of anything, and round 1 reading it is precisely what displaced a link the phone was actively keepaliving. old_data_silence_ms is still measured and logged, so a round-1-vs-round-2 capture stays greppable, and consulted by nothing.

  A link that has really stopped answering is removed by the expiry, not by a replacement: last_heard_ms counts every inbound frame including the peer's keepalive, and a link that delivers neither payload nor keepalive for LINK_TIMEOUT_MS (45 s, three missed keepalives) is torn down by lnsd's LinkTable::expire and by the firmware session's link_silent arm — whether or not anybody dials the identity (BLE_LINK_EXPIRE role=<r> slot=<n> conn=<h> silence_ms=<n>). The replacement handles only the case the expiry is too slow for: the peer is here, on a new connection, asking to be reachable now. A REFUSED address goes into the dead-end table for its TTL so the scanner does not immediately re-offer it; a replaced link's queued packets move to the new link first.

  Every duplicate line carries rule=, origin= (the role map the arbitration is computed over), old_mtu=/new_mtu= (the usable MTUs as compared, in the peer's ledger), old_silence_ms= (the any-frame measurement the abandonment test reads) and old_data_silence_ms= — round 1's input, reported for comparison, never for a link that carried none.

  What the expiry bound itself replaced is a measurement (#382). Over 14.1 h beside a Columba phone (ble-accept-rns/lnsd.log, 2026-08-30) the gaps between received non-keepalive packets from a peer that was demonstrably present throughout ran to a median of 51 s, a 90th percentile of 182 s and a maximum of 5590 s; 502 links outlived 45 s with no payload at all. Payload silence is what an idle phone looks like, which is why round 2 removed it from the rule entirely. The decisions are pinned by a_live_old_links_own_dial_is_refused_before_the_handshake, an_abandoned_rotated_link_is_displaced_by_our_dial, payload_recency_no_longer_flips_the_verdict, keepalives_keep_a_link_out_of_the_abandoned_branch, a_same_role_pair_is_decided_without_the_peers_arbitration and preferred_ble_role_is_kotlinblebridge_44 in the registry, by the two-sided registry::duel scenarios that assert the pair is never linkless for longer than 2 s, and by an_idle_link_is_alive_and_our_redundant_dial_is_refused, payload_recency_no_longer_flips_admission_in_either_role, our_dial_against_the_peers_live_central_link_is_refused and the_peers_second_dial_displaces_its_own_first_link in leviculum-std/src/interfaces/ble/links.rs.

The simulation that motivated the fallback is a host test: leviculum-nrf/ble-tx/tests/graph_formation.rs replays random arrival orders through the real rule with the real slot limits. It reproduces the issue's strict-rule disconnection rates exactly, asserts that no fallback configuration ever leaves a board linkless, pins the quiet suspension's measured cost as the record, and holds the shipped configuration — eager clock, lowest-eligible window — to zero disconnected orders at both sizes.

Three implementations exist in tree: the shared carrier logic (leviculum-core/src/framing/ble.rs, plus the advertisement/decision logic in leviculum-nrf/ble-tx), the firmware's dual-role implementation (leviculum-nrf/src/ble/), and lnsd's dual-role BlueZ interface (leviculum-std/src/interfaces/ble/, type = BLEInterface, via bluer). The lnsd interface treats all live BLE links as one broadcast domain behind one Reticulum interface — which is also the only shape BlueZ supports on the peripheral side, where a GATT notification reaches every subscribed central at once.

lnsd as peripheral: one ordered socket per central

When a peer dials lnsd, lnsd is the GATT server and every frame the peer sends is a write to the RX characteristic. lnsd takes those writes over BlueZ's AcquireWrite, not WriteValue (#436): the characteristic declares write-without-response with bluer's CharacteristicWriteMethod::Io, BlueZ asks for a socket on the first write of each connection, and one reader task per central (bluez::periph_reader) reads that SEQPACKET socket and hands each value to the interface's event loop in the order the kernel received it. Through WriteValue every write was its own D-Bus call, and bluer runs each on its own tokio task, so two fragments a board wrote back to back could reach the defragmenter END before START; the 2026-10-06 ble_lxmf_delivery red lost ten whole packets that way with every fragment delivered.

Which writes take the socket is BlueZ's routing, not ours. The GattCharacteristic API document (bluez 5.82, doc/org.bluez.GattCharacteristic.rst, AcquireWrite) says that once the fd is acquired WriteValue is locked, and the server side of bluetoothd implements exactly that per connection: in src/gatt-database.c chrc_write_cb looks up the connection's acquired socket first and sends any write it finds one for down it, a Write Request with response included, and acknowledges the ATT request itself. Only a Prepare Write request is answered before the socket is consulted, and only a failed AcquireWrite falls back to WriteValue, which bluer refuses under Io. So the identity handshake, which the boards and lnsd's own central write WITH response, also arrives on the socket: it is the write that triggers the AcquireWrite, and bluetoothd forwards it once the socket exists. The socket's end is the central's disconnect (client_io_new registers a disconnect callback on the ATT channel that closes it); the reader reports it as PeriphGone and the peripheral link is released there, as a central-role link is when its session ends, instead of waiting for the expiry sweep.

The park-and-replay of an inverted fragment pair (#434, Link::oo_tail in links.rs) stays behind this as the last line of defence: free on an ordered stream, and a counted loss rather than a silent one should a carrier ever reorder again.

Notifications are flow controlled, not fired and forgotten

The GATT server sends a packet as a sequence of notifications, one per fragment. The SoftDevice queues those per connection, and the queue is one entry deep by default (BLE_GATTS_HVN_TX_QUEUE_SIZE_DEFAULT = 1 on S140). The second sd_ble_gatts_hvx of a packet is therefore refused with NRF_ERROR_RESOURCES until the first one has actually gone out over the air.

A loop that pushes every fragment back to back and ignores the return value consequently delivers fragment 0 and drops the rest, silently, on both sides: the peer sits on an assembly that never completes and the node believes it transmitted. That is what the interface did until Codeberg #264, and it is why only single-fragment traffic — anything below one fragment payload, 177 bytes at the default MTU — ever arrived. An announce did not.

The rule that replaces it: a fragment is offered again after the queue drains, and a fragment that cannot be sent is reported, never discarded.

• The wait is on the SoftDevice's own BLE_GATTS_EVT_HVN_TX_COMPLETE, not on a guessed interval. nrf-softdevice surfaces it as gatt_server::Server::on_notify_tx_complete, whose default implementation throws the event away and which the #[gatt_server] macro does not generate — so the server type implements Server by hand.
• The wait is bounded, so a peer that stops listening cannot wedge the outbound task. On expiry the packet is abandoned like any other failure.
• Every abandonment emits BLE_TX_DROP (see Structured event logs) and bumps a counter. A dropped fragment is never again indistinguishable from a sent one.

The decision itself — retry, abort, report, and the exactly-once ordering — is pure and lives in leviculum-nrf/ble-tx, unit-tested on the host against a scripted notification sink; the firmware only performs the actions. This is the same split as the GNSS and telemetry policies, for the same reason: the interesting states are queue-full-then-drains, queue-full-then-times-out and hard-error-mid-packet, and none of them are reachable on demand with a real phone in the loop.

Pacing on a link

Two packets whose fragments leave back to back on one connection can cost the receiver the first packet: the 2026-09-09 desk measurement (#376) showed a Columba phone one hop from two boards losing exactly the first of two fragmented packets arriving back to back, on both boards' links, reproducibly — and receiving both once the sender left 100 ms between the packets.

Every pump therefore serves a per-link inter-packet gap, measured from the last fragment of one packet to the first fragment of the next on the same connection: the compiled default is 100 ms (leviculum-ble-tx's DEFAULT_TX_GAP_MS). The number is the measured value, not a derived one — one to two connection intervals (30 to 50 ms) may suffice but was not measured. The knob stays for measurement: lnflash --set-ble-tx-gap <ms> overrides the default on a running board (0 disables the gap entirely), is never persisted, and a reset restores the default. The first packet of a connection is never deferred, an idle link pays nothing, and keepalives are neither paced nor slide the window. Every actual wait logs BLE_TX_GAP conn=<h> waited_ms=<n>. lnsd's Columba interface serves the same default on its notify pipe and each central link — it is the phone stand-in on the rig and must behave like a board toward a real phone.

Related, from the same desk session: the peripheral pump drains nothing before the peer can receive. The first notify on a fresh connection, sent before the central had written the TX CCCD, fails inside the SoftDevice (sd_error code=13313, BLE_ERROR_GATTS_SYS_ATTR_MISSING) and the packet dies. The pump now holds the drain until both the CCCD subscription and the identity handshake have happened — packets queued before that wait, they are not dropped — and logs BLE_TX_HELD conn=<h> reason=not-subscribed once per connection when it actually held one. Policy host-tested in leviculum-ble-tx's hold module.

ble-leviculum (BLE 5 broadcast mesh)

Reticulum broadcasts are sent as real BLE 5 connectionless extended advertisements, so any number of devices in range form a mesh without per peer links. This sidesteps the 3 to 4 link ceiling entirely.

To the core this is just another lossy broadcast medium, the same model LoRa already uses, so the existing robustness logic applies. A BLE 5 broadcast interface is a normal lossy broadcast Interface; the connectionless and size limited nature is a carrier quirk handled inside the interface.

Feasibility was confirmed by a read only spike (see docs/ble5-broadcast-protocol3-spike.md in the repository). Key results, valid for nrf-softdevice rev 5949a5b and SoftDevice S140 v7.0.0:

• Connectionless extended advertising is supported, including the pure broadcast type EXTENDED_NONCONNECTABLE_NONSCANNABLE_UNDIRECTED.
• One advertisement carries at most 255 bytes, about 245 usable after framing.
• The receive side (extended advertising scan) is supported but gated behind the ble-central feature, currently off.
• Periodic advertising is absent in S140 7.0.0. It is optional; repeated extended advertising suffices for a broadcast mesh.

The consequence is fragmentation. Small packets such as announces fit in one advertisement. A full 500 byte Reticulum packet (the MTU) does not and must be fragmented across two advertisements and reassembled. Because broadcast is lossy, a fragmented large packet only arrives if both fragments do; reliable large transfers use links over a connection oriented path, not broadcast, so this is acceptable.

Coded PHY: automatic range extension, first-class

Coded PHY (S=2/S=8) is a first-class part of the ble-leviculum design, not an optional add-on. The reason is the range and rate frontier: room scale BLE at 1M on one end, km scale LoRa at kbit/s on the other, and nothing in between. Coded PHY at S=8 trades 1/8 rate for roughly 4x range and fills exactly that empty middle, about 200 to 800 m at a ~100 kbit/s class rate.

The architecture keeps it automatic. 1M extended advertising is the universal floor: every device transmits and scans it. Controllers that support LE Coded (runtime feature detection: the LE Coded feature bit; on Android isLeCodedPhySupported()) additionally dual advertise the same payload on a coded primary advertising chain and scan both PHYs (scan_phys = 1M | Coded, the controller time shares the scan windows). No user configuration, and no parallel meshes: coded capable nodes bridge by construction because 1M always stays on. Double reception of the same payload is absorbed by the normal Reticulum packet hash dedup.

Costs to tune, stated here and not solved here. Coded TX is about 8x airtime at S=8, so coded repeats are rate limited, for example one coded transmission per N 1M intervals. Splitting the scan budget across two PHYs lengthens discovery latency. Android background scan limits apply.

Capability is unevenly distributed, and the design accounts for that honestly. Recent Android flagships largely support Coded PHY, often both scan and advertise; midrange devices are mixed, sometimes scan only; iOS exposes no Coded PHY at all; cheap BT5 USB dongles often omit it. The nRF52840 on our boards and test dongles supports it fully. This asymmetry is why the design makes coded an automatic bonus above the 1M floor, never a requirement.

Combining the protocols

The broadcast and connection oriented protocols are not mutually exclusive. The useful combination is broadcast for reach (announces, discovery, small packets to everyone, no connection limit) and a connection for reliable directed bulk. This maps onto Reticulum's own layering: announces are best effort broadcast, links and resources are reliable and directed.

The constraint on how to combine them comes from the interface boundary. An Interface is sent only bytes: try_send(&[u8]) (leviculum-core/src/traits.rs:280, plus a prioritized variant that adds a priority hint) takes a packet buffer, no destination and no next hop. The next hop and the choice of interface live one layer up in the transport. So an interface cannot decide "open a connection because this packet is for node X" without reading the destination out of the packet bytes, which is the link awareness the interface isolation rule forbids. The Columba maintainer raised the same objection on the original proposal (see the discussion linked below).

The clean way to combine them is therefore to keep the broadcast versus connection decision in the transport, which is allowed to be path aware, and to run two dumb interfaces rather than one clever one. Two staged options:

• Stage A, broadcast only. Run ble-leviculum alone. Reliability for large or important traffic comes from Reticulum's existing link and resource layers riding on top of the lossy broadcast, exactly as they already do over LoRa. The interface stays a pure try_send(bytes) broadcast pipe, fully isolated, unbounded in scale, with a minimal failure surface. Build this first and measure throughput.
• Stage B, broadcast plus per peer connections. If Stage A throughput is not enough, run ble-leviculum and ble-reticulum together. Model ble-reticulum as one ordinary byte only interface per connected peer (the Columba BLEPeerInterface shape): each GATT link is a normal interface that sends the bytes it is given over its one connection, and the transport routes over the set of interfaces normally. Which peers to connect is a neighbour and discovery policy with an idle timeout to free connection slots, not a per packet trigger. The hybrid benefit then emerges from running both planes at once and letting the transport choose, with no clever single interface and no change to the byte only interface boundary.

Power shapes the deployment. Continuous advertising and scanning is costly on phones, so powered nodes (lnsd, stationary RTNodes) run the broadcast plane, while phones connect sparingly over ble-reticulum to a nearby powered relay.

True on demand, opening a connection because a packet needs to reach node X, belongs in the transport, which knows the next hop, via a control path beyond try_send. That changes the media agnostic interface boundary and is deferred until measurement shows Stage A and Stage B are not enough.

This analysis follows a proposal and debate in the Columba project, discussion 880, a hybrid broadcast and on demand connection model. The points above record why a single hybrid interface is not the chosen path here.

Capability matrix

Decisions

• Broadcast instead of more BLE 4 links. The connection oriented model caps at 3 to 4 reliable links, which does not scale to a dense mesh. BLE 5 connectionless advertising removes the ceiling, hence ble-leviculum.
• Fragmentation for full size packets. One extended advertisement holds 255 bytes on S140 7.0.0, the Reticulum MTU is 500, so the ble-leviculum interface fragments and reassembles. This is carrier logic, it lives in the interface, the core stays unaware.
• Name in our own namespace. ble-leviculum, not ble5-reticulum, because the protocol is our unilateral invention, interoperates with nobody yet, and the *-reticulum namespace is controlled upstream.
• no_std carrier logic. So the same protocol code runs on embedded nRF and on the host. Only the radio and OS binding is platform specific.
• Combine by two interfaces plus transport, not one hybrid interface. The interface boundary is bytes only, so a single interface that opened connections per destination would need link awareness, which the isolation rule forbids. Keep the broadcast versus connection choice in the transport.
• Stage broadcast first, then measure. Build ble-leviculum alone, let Reticulum's link and resource layers provide reliability over it, and only add per peer connections if measured throughput requires it.
• Coded PHY is first class and automatic. It fills the empty middle of the range and rate frontier between 1M BLE and LoRa. 1M stays the universal floor; coded capable nodes dual advertise and dual scan on top of it, so the mesh never partitions and no user configures anything.
• Idle timeout governs connection management, not packet routing. Closing idle connections to free slots is fine. Triggering a connection open from a per packet destination is not.

See also

• Interface isolation
• docs/ble5-broadcast-protocol3-spike.md, the ble-leviculum feasibility spike
• Columba discussion 880, the hybrid broadcast and connection proposal: https://github.com/torlando-tech/columba/discussions/880

Media profiles

An LNode meshes over LoRa and BLE at once, by default, from the moment it boots. That is the right behaviour for a field node and the wrong one for a measurement: a packet delivered over the other medium masks a loss on the medium under test, so every single-medium number a dual-carrier node produces is falsifiable. "LoRa PDR was 94 %" is not a statement about LoRa if BLE was carrying the same mesh.

A media profile is the node's declaration of which carriers it meshes over. It is declared (a host says so), applied (the firmware honours it at boot and at runtime), and proven (the board says out loud, every boot, what it is on). All three are needed: a declaration nothing applies is a comment, and an application nothing proves is a hope.

The default is both carriers on

Absence of a profile changes nothing. A board with no record on its flash page, a board whose record is corrupt, a board whose record names a carrier this firmware does not know — all of them come up on both carriers, which is what every fielded board is already doing. There is no firmware update on this path that can take a board off the mesh.

That is why the record has a magic and a checksum rather than being a bare flag byte: a zeroed page read as flags would say "both carriers off", which is a silent way to lose a node.

Setting one

$ lnflash --set-media lora=on,ble=off
/dev/ttyACM0: media profile set — running lora=on ble=off, configured lora=on ble=off.
  It survives resets; the board's own [MEDIA] line on if00 says the same.

lora= and/or ble=, comma or space separated, on/off (true/false, yes/no, 1/0 also accepted), keys and values case-insensitive. A carrier not named keeps the board's own setting — lnflash reads the board back first and applies the spec on top, the same read-modify-write contract --set-tx-power holds for the radio, and for the same reason: a host that substitutes its own default for the field it did not mean to touch changes what it claimed not to change.

--set-media with no value only reads:

$ lnflash --set-media
/dev/ttyACM0: running lora=on ble=off, configured lora=on ble=off.

What "off" means on the board

At boot, a carrier that is off is never started. The LoRa task that resets, configures and keys the SX1262 is not spawned, so the chip is never brought up; the Columba tasks are not spawned, so there is no advertisement, no scan, no GATT service and no connection. Nothing is transmitted and nothing is received.

The SoftDevice is still enabled with ble=off, deliberately. It is not only the BLE stack: sd_flash_write is the one legal way to write internal flash once it is enabled, and both persistence store tasks ride on it. A board that could not persist its own profile could not be put back on BLE — the one state this feature must never be able to reach.

At runtime, switching a carrier off stops it carrying Reticulum traffic in both directions immediately: the interface drops what the core hands it and the binary's receive arm drops what the medium hands up.

For BLE the runtime off also takes the carrier off the air: the Columba tasks disconnect every live link, central and peripheral role — a connected phone sees the board go, exactly as if it had left range — and stop advertising and scanning. Each dropped link unwinds through the same per-link teardown as range loss, so the core receives the same peer-lost report and culls its paths identically.

For LoRa it does not: the LoRa task keeps listening (nothing is transmitted, and what it hears is dropped before the core sees it). LoRa radio silence needs the boot path, which is why the acceptance for LoRa silence is set-then-reset and not a runtime set.

What "on" means, and when it needs a reset

Switching a carrier back on is immediate if it came up at boot — its tasks are still there, gated, and for BLE they resume advertising and scanning at once. A carrier that did not come up has no task to un-gate, and an embassy task cannot be spawned from nothing after the fact, so it cannot start before the next reset.

The board says which case it is in rather than acking either way. Both media frames are answered with a report carrying two profiles:

• running — what the board is carrying traffic on right now.
• configured — what a reset would come up with.

They differ exactly when a carrier is waiting for a reset, and lnflash renders that difference as a sentence naming the carrier. An ack would have said "done" to a request the board cannot honour yet, and a measurement run reading that ack would believe it had a BLE link that does not exist.

Because "configured on, not running" is a terminal statement — the host prints "Reset the board" for it — the board must not be able to say it while it is merely still booting. USB comes up before the carriers by design, so the serial task answers frames during a window in which nothing has been spawned yet; in that window the board reports the declared profile as running, and narrows it to what really started as soon as both spawn decisions are made. Without that, a set-then-reset script that connects the moment the tty appears reads "did not come up" off a board that came up perfectly (seen on the rig, #255).

The proof line

Every boot, on the debug CDC, before anything can have moved:

[MEDIA] lora=on ble=off src=flash t=1183

The two carrier fields are what the board is running; src= is flash for a profile read off the page and default for the both-on fallback. It is re-emitted with the [FW_BUILD] banner every five seconds, so a capture attached after the boot window still reads the carriers off the board rather than off an operator's memory, and a runtime change shows up within five seconds.

The shape is an interface. Assertions read it; it is frozen in docs/src/structured-event-logs.md and must not drift.

Where the pieces live

What this is not

It is not a power-saving feature and not a way to run a node on one carrier in the field — a node with a carrier off is a node that cannot be reached over it, which for a mesh is a fault, not a setting. It exists so that a measurement can say which medium it measured. Deployments run both carriers; that is the default and it stays the default.

How far one firmware build reaches

Every board we support costs a build, a bundle entry, a row in the test matrix and a place in everyone's head. The policy that keeps that cost from growing with the hardware catalogue:

A firmware build serves a whole family of boards. A build for one hardware configuration is only justified where universality is unreachable, and the burden of proof lies with the specialised build.

This is not an aspiration. It is already how the builds we have behave, and it was decided twice before it was written down.

Why a family and not a board

Boards differ in dozens of ways and almost none of them matter. What decides whether firmware runs at all is the SX1262 wiring: seven pins, plus the TCXO voltage and whether DIO2 owns the antenna switch. Every other difference is peripheral in the literal sense.

Those seven pins are usually not a property of the product. They are a property of whatever part carries the radio. When the radio ships together with the MCU as one module, every carrier board built around that module inherits identical wiring, and a product family of a dozen devices collapses to a single set of pins. The RAK4630 is the clean case: twelve different carriers in Meshtastic's tree, from the Pocket V2 to a solar repeater to an Ethernet gateway, all repeat the same seven numbers because the RAK4630 datasheet fixes them.

The unit of support is therefore the pinout family, and the concrete membership lists live in Supported boards.

What universality requires of the firmware

A single image only serves a family if everything a carrier adds either announces itself or costs nothing when absent. That is a design constraint on peripheral handling, not a hope:

• Probe where the bus allows it. The RAK baseboard display is found by an I2C address probe (ack_probe, leviculum-nrf/src/display.rs:55); when nothing answers, the task logs and exits (DetectedKind::None, leviculum-nrf/src/display.rs:161-167).
• Fail into the harmless state. The user button is configured Pull::Up (leviculum-nrf/src/button.rs:37), so an absent button reads as not pressed rather than as noise.
• Park rather than spin. The GNSS task awaits a UART that simply stays silent when no receiver is fitted.
• Publish nowhere. The battery task samples a pin that floats on a bare module, but its only subscriber is the display task that is not running, so no wrong reading escapes.

Measured on this tree, carrying all of that costs 47.6 KiB of flash and 2.5 KiB of RAM over the stripped build. The RAM figure is affordable by construction rather than by luck: the same image already runs on a populated carrier with the same chip and the same memory, and a carrier board adds peripherals, never RAM.

Where a bus cannot be probed, writing blind is acceptable only for a known board. The T114 drives its ST7789 panel blind because MISO is not connected and detection is physically impossible, which is safe because we know what else is on those pins. The same reasoning does not transfer to an unfamiliar board, where the identical pins may carry something that must not be driven.

Runtime detection is therefore the lever, and a build-time feature is the fallback. Every peripheral moved from a feature flag to a probe removes a reason for a second build. Codeberg #240 does this for GNSS presence.

When a specialised build is justified

Three conditions, any one of which is sufficient:

1. The radio wiring differs. No amount of runtime detection recovers from pins that are simply elsewhere. The third build, solarnode (Codeberg #233), is this case and nothing more interesting: the Wio-SX1262 puts all seven pins elsewhere and adds an eighth, a host RX-enable the other two families do not have.
2. A radio parameter is board-specific rather than family-specific and is compiled in. The Elecrow ThinkNode M1 matches all seven T114 pins but runs its TCXO at 3.3 V against the family's 1.8 V. Either the value becomes data, or the board needs its own build.
3. A peripheral is dangerous when mishandled. A board with an external power amplifier needs its enable line driven correctly. Silence is not a safe default there, unlike a missing display.

Convenience, code tidiness, and "it would be cleaner to separate them" are not on this list.

A frequency region is not on it either. The compiled default is the eu868 community profile, but the radio configuration is data, chosen at flash time: lnflash ends every flash with a preset menu — eu868, us915, au915, or a custom five-number entry — and stores the choice on the board (see Flashing an LNode, "The radio configuration belongs to the flash"). The presets are the settings each regional Reticulum community has converged on; a default, not legal advice.

Two device classes, one policy

Everything above was written about nRF52840 boards, because for a long time those were the only boards we had firmware for. leviculum-esp adds a second class — ESP32 and ESP32-S3 — and the policy does not change: one build per pinout family still holds, and a board file still describes a wiring rather than a product.

What the second class does add is a layer the first one never had to name out loud, because with one SoC family there was nothing to separate it from. The split is:

The third row is the one that earns the split. The sequences that decide what goes on the air are not per class and not per board; they were lifted into leviculum-core precisely so a host test could run them, and a second device class must not become a second copy of them. What a class crate implements is the two traits leviculum_core::sx126x reaches the hardware through — CommandBus and RegisterBus — and nothing above them.

Adding the second board of a class is therefore: one boards/<name>.rs with its pins and its BoardConfig, one src/bin/<name>.rs that hands those pins to the shared init, one [[bin]] stanza, one Justfile recipe. No new idiom, and nothing in lib.rs moves. If adding a board does require moving something in lib.rs, that is the signal that the thing being moved was a board fact sitting in the class layer.

Where the classes differ, and why that is not a policy exception. An ESP32-S3 board has no UF2 bootloader and no mass-storage volume, so nothing in the ESP class corresponds to the Board-ID discussion below; identification there happens over the serial protocol the ROM speaks, and the same question — is the identifier bound to the same unit as the wiring — has to be asked again on its own terms. The class boundary is about where code lives. It is not a second policy.

The axis the policy does not have: the transceiver family

Everything above varies two things, the class and the pinout family, and holds a third fixed without ever saying so: every board in this book carries an SX1262. The unit of support is a set of seven pins because seven pins is all that differs once the part itself is settled. A board with a different transceiver does not sit anywhere on that scale, and the Seeed SenseCAP Card Tracker T1000-E (Codeberg #406) is the first one we own: the nRF52840 we already build for, a bootloader and a USB path we already flash through, and a Semtech LR1110 where every board above has an SX1262.

The class table above puts every opcode sequence in one row. That row is where the cost lands, and it is not spread evenly across the code that looks radio-shaped. Measured on this tree, 2026-09-25:

The two pure crates are the cheaper half, and that is worth stating because their prose names the chip on nearly every page and reads like the expensive half. Both were lifted out of the driver so a host test could drive them, and being liftable is the same property as being portable:

• rx-arming reaches a radio only through two traits, RxPort (leviculum-nrf/rx-arming/src/lib.rs:167) and RxWindowProbe (leviculum-nrf/rx-arming/src/lib.rs:706). The driver implements both, RxPort (leviculum-nrf/src/sx1262.rs:1450) and RxWindowProbe (leviculum-nrf/src/sx1262.rs:1480), and a test fake implements RxPort (leviculum-nrf/rx-arming/src/lib.rs:1838) beside it. A second family writes a third implementation; it does not fork the crate.
• channel-access touches no radio at all. The caller reports what its own channel-activity detection said — cad_clear (leviculum-nrf/channel-access/src/lib.rs:323), cad_busy (leviculum-nrf/channel-access/src/lib.rs:333), cad_error (leviculum-nrf/channel-access/src/lib.rs:350) — and the jitter slot is derived from bandwidth, spreading factor and coding rate (jitter_slot_ms, leviculum-nrf/channel-access/src/lib.rs:116), which are properties of the modulation rather than of the part. Only the module's own text names the SX1262 (leviculum-nrf/channel-access/src/lib.rs:17).

Where the seam would have to open, if it opens. RxLatch (leviculum-nrf/rx-arming/src/lib.rs:367) is three named LoRa interrupt bits — preamble, header, RxDone — read back without being cleared, and the two bounds computed from them are forwarded to leviculum_core::sx126x::tx_defer_ms and leviculum_core::sx126x::false_preamble_ms. A part that latches those three the same way slots in behind the existing traits. A part that does not forces the traits themselves open, and choosing between widening them and carrying a second implementation is a design decision, not a port. That decision is not taken here, and nothing in this tree has measured an LR11xx part against these traits. Until one has, the honest estimate is the driver in full and the two crates untouched.

The limit that bites

Universality reaches exactly as far as the identification does. A build may serve twelve carriers, but something has to decide that the board in front of it is one of those twelve, and that decision is made from the bootloader (see Flashing an LNode). Where the bootloader identifier is bound to the same unit as the wiring, the two line up and the family is safe end to end. Where a vendor shares one identifier across models with different wiring, a correct universal build can still be written onto a board it does not fit.

So the reach of a build and the precision of its identification have to be argued together. A family is only as wide as the narrowest of the two.

The firmware's host-test seam

A decision lives in a host-testable crate. The nRF binary calls it.

leviculum-nrf builds for thumbv7em-none-eabihf, sits outside the root workspace with its own .cargo config, and runs no test of its own. Any statement about firmware behaviour that is written inside it is therefore provable only by flashing a board. This page says where the line between the two sides runs, why it is not a matter of taste, and which decisions are still on the wrong side of it.

Why the rule is about the bench

The rig is one bench. It is shared between the conformance corpus, the land gates and every manual measurement, and a hardware run costs hours — so anything provable only there competes with everything else provable there. A host assertion costs a second and runs on every push.

The pattern was found under time pressure rather than designed. Codeberg #402 stayed open for days over a board's announce cap registration that had in fact been correct since 594dd3f8, because nothing could show it. What closed it was moving the step that carried the meaning (AnnounceCapBitrate::sync_phy) into leviculum-core, where a host test makes the same call the firmware makes. That is the pattern; this page is it stated as policy instead of as one lucky fix.

What counts as a decision

A decision is anything whose wrongness is a behaviour, not a wiring fault: a cadence, a threshold, an ordering, a predicate, an arithmetic budget, a byte-exact line other tools grep. If a sentence about the code can be written as "under X it does Y", it is a decision, and that sentence belongs in a test.

The far side — what legitimately stays in leviculum-nrf/src — is everything whose argument is a pin, a register, a SoftDevice syscall or an embassy_time::Instant: peripheral access, task spawning, the boot order, the I/O half of a driver.

The seam between them is a value type. The crate holds the decision and the vocabulary it is expressed in; the firmware supplies the I/O and the clock and does what it is told. leviculum-rx-arming is the sharpest example already in the tree — it holds the order in which the receive path re-arms and hands a frame up, and src/sx1262.rs supplies a chip to drive (stand_down_for_rx, leviculum-nrf/src/sx1262.rs:965).

Where the seam runs today

The leviculum-nrf workspace has 32 members besides the firmware crate, every one of them pure and host-testable: screen, sd-policy, gnss-time, gnss-presence, gnss-init, telemetry-policy, ble-tx, announce-policy, queue-budget, log-line, tx-spacing, rx-arming, persist-ack, boot-trace, boot-count, channel-access, media-state, record-log, pn-store, store-spike, qspi-bitbang, battery-scale, settle-budget, drop-budget, heap-budget, node-name, sync-batch, upload-proof, mute-lease, qspi-selftest, qspi-boot, usb-policy (members, leviculum-nrf/Cargo.toml:14). Before heap-budget and node-name joined them they carried 806 host assertions across 61 test targets — measured 2026-09-25 by the host-triple lines of lint-nrf (Justfile:75). mute-lease is the newest and the rule's own case twice over: the deadline on a host's transmit mute (Codeberg #410) is a decision that would have been unassertable inside src/lora.rs, and the LORA_MUTE_EXPIRED line that announces it went into log-line beside the two mute lines it closes out, rather than being spelled at its one call site.

leviculum-core is the other half of the seam and counts the same way: a decision that is not board-specific belongs there, where lnsd runs the identical code. leviculum-announce-policy is deliberately shared with the daemon for exactly that reason, so the cadence the desk measures on a board is the cadence the daemon runs.

That number — how many firmware decisions can be asserted without a board — is the measure this page is judged by. It goes up when a decision moves, and it is the only thing that does.

The far side is not a choice

Whether leviculum-nrf should gain a host test target of its own is settled by the compiler, not by preference. Both BSP features route through the softdevice aggregator, lib.rs refuses a build with no BSP selected, and the SoftDevice bindings do not compile for a host triple:

$ cd leviculum-nrf
$ cargo check -p leviculum-nrf --features bsp-t114 \
      --target x86_64-unknown-linux-gnu
error: invalid register `r0`: unknown register
...
error: could not compile `nrf-softdevice-s140` (lib) due to 548 previous errors

(measured 2026-09-25). There is no feature combination that both links and builds for the host, so #[test] inside leviculum-nrf has nowhere to run. Consistently, leviculum-nrf/src contains zero #[test] and no tests/ directory today.

So: "cannot move" is the definition of hardware-only. A decision that has not been moved is not hardware-only, it is untested. The question to ask of any firmware behaviour is never "can the firmware crate test this?" — it cannot test anything — but "what is the value type that carries this decision, and what is left over once it is gone?"

How the rule is gated

lint-nrf runs clippy and the tests of every workspace member except the firmware crate, on the host triple, as --workspace --exclude leviculum-nrf. It is spelled that way rather than as a list of -p flags so that adding a seam crate to members is the whole act of gating it. The list it replaced lived in three places, and its prose copy had already lost leviculum-upload-proof within a day of that crate landing. A positive control confirmed the failure mode is silent: a member carrying a deliberately red test failed the workspace form with exit 101 and passed the -p list with exit 0, because the list did not name it.

New code follows the rule. Old code moves when it is touched anyway — a bug fix in a stranded decision is the moment to move it, not a reason to defer.

Still stranded

The four areas that prompted this page are already seamed, and so is most of what the list below used to name; it is worth saying which, because the list below is what is actually left:

The answer windows moved as constants, not as functions of the modulation. What the modulation moves is the delay they must cover, one maximum-size frame's airtime (728 ms at the SF8/125 kHz default, 4756 ms at SF10/62.5 kHz); the windows answer to the hosts' fixed waits (lnsd's 2 s per attempt), so a slow profile is answered busy and acked on the retry rather than waited out. The crate asserts both halves, and the envelope-inside-lnsd relation is a build-time assert the firmware build inherits.

What has no host assertion, in the order it is cheap to move:

1. The [TRANSPORT] ticker. The re-arm deliberately drops missed periods so a busy loop does not then emit a burst of catch-up lines (poll, leviculum-nrf/src/transport_stats.rs:106), and the line is byte-exact because capture consumers grep it (log, leviculum-nrf/src/transport_stats.rs:114). leviculum-log-line already exists for the second half.

See also: Checks that are actually checks for why a stated rule without a gate does not hold, and Evidence and honesty in testing.

Flashing an LNode

Every board we flash is an nRF52840 carrying a factory UF2 bootloader. That bootloader, not the firmware on top of it, is the part that decides what a flashing tool can do. The rule that follows:

The application is not the board's identity. The bootloader is. Anything a tool needs to know before writing, it learns from the bootloader, never from the firmware currently running.

A T114 may arrive carrying Meshtastic, Meshcore, microReticulum, RNode firmware or our own. Each picks its own USB identity, and a crashed one picks none. The bootloader underneath is the same in all five cases, answers on a fixed USB ID, and publishes what it is in a text file.

The three states a board can be in

Application. Our firmware enumerates 1209:0001 (T114) or 1209:0002 (RAK4631), from usb_vid/usb_pid in leviculum-nrf/src/boards/t114.rs:172-173 and leviculum-nrf/src/boards/rak4631.rs:187. Two CDC ports: interface 00 is the debug log, interface 02 the Reticulum transport. Both IDs are squatted pid.codes test IDs, flagged as a TODO at leviculum-nrf/src/usb.rs:119. Heltec stock firmware uses 239a:8071. Meshtastic on the SenseCAP Solar Node uses 2886:0059, and calls itself "XIAO-BOOT" while doing so. Nothing stops an application from naming itself after a bootloader, which is the sharpest available argument for the rule above: the product string is application data, not evidence.

Bootloader (UF2/DFU). A different USB ID entirely, which is why an application-ID match can never be true while a board sits in DFU (leviculum-nrf/tools/uf2-runner.sh:279). Measured on the rig:

The last row is the Solar Node, measured 2026-08-17. Note that its bootloader is the one row whose product string does not contain the word BOOT, while its application's does.

Dark. Crashed firmware never enumerates at all. No touch reaches it; only a physical double-tap does.

Getting into the bootloader

Two mechanisms, and only one of them is ours to control.

1200-baud touch. The host opens a CDC port at exactly 1200 baud. Our firmware answers the resulting SET_LINE_CODING in leviculum-nrf/src/usb.rs:188, writes DFU_MAGIC_UF2_RESET (0x57) to GPREGRET at 0x4000_051C and resets. The bootloader reads that retained register on the next boot and stays in mass-storage mode. Measured latency from stty ... 1200 to the bootloader appearing on USB: 5 s on the T114, 3 s on the RAK.

Double-tap RESET. The bootloader's own mechanism, independent of any firmware: it sets a RAM flag at startup and stays in DFU if a second reset arrives while the flag is still live.

The touch only exists if the running firmware implements it. Ours does. Stock Meshtastic does not, which is why a first flash away from Meshtastic needs the manual double-tap (Justfile:1719); for that case Meshtastic offers its own admin command, wrapped as just dfu-rak4631. For Meshcore, microReticulum and RNode firmware on nRF we have not measured it.

This is the load-bearing limit for any "fully automatic" tool. There is no universal software trigger. The double-tap is the only mechanism that works regardless of what is running, and it needs a human. A tool can be fully automatic for boards already carrying our firmware, which is every re-flash, and must fall back to one clearly announced key press otherwise.

And what that key press is differs per board. The WisMesh Pocket V2 has no externally accessible RESET at all: the contact is reachable only through a hidden pinhole beside the USB socket, double-tapped with a needle (Recovery, "the hidden-pinhole caveat"). Telling its owner to press RESET twice sends them looking for a button that does not exist, which is a worse failure than saying nothing — they conclude the board is dead. So the wording is a board fact like any other and lives in lnflash/catalogue.toml ([board.<name>.flashing.double_tap]), not in a branch around the prompt; a board that says nothing there gets the ordinary wording. just flash-rak4631 carries the same line into the developer runner's prompt through LEVICULUM_DOUBLE_TAP_HINT (Codeberg #261).

RNode firmware on the T114 lands a board in exactly that state

Mark's official RNode build for the Heltec T114 (rnode_firmware_heltec_t114.zip, v1.85/1.86) is an app-only Nordic DFU package. Its application vector table reads SP 0x20040000 and reset vector 0x00051819, so the image is linked for a flash base around 0x51000. This board's factory bootloader with S140 7.3.0 runs applications at 0x27000, which is the base our own image is linked for as well (leviculum-nrf/memory.x:16). rnodeconf pushes the app-only package through the factory bootloader (adafruit-nrfutil dfu serial --package … -t 1200), so it lands at 0x27000; the bootloader jumps there, reads a reset vector pointing into unprogrammed flash, and hard-faults before USB comes up. The same dark board as the SoftDevice mismatch below, from a different cause. rnodeconf itself calls the T114 target experimental and AS-IS.

The operational consequence is the one this page keeps arriving at: nothing is running to answer the 1200-baud touch, and a board that never enumerates is not even a candidate for a tool to find, so it takes a double-tap. After that nothing further is special — lnflash writes our application at 0x27000 over whatever was resident and it boots. Where the previous firmware was linked does not affect where the next one is written. Measured on 2026-08-10 on serial 183004F712B4A7FE: rnodeconf v1.86 reported "Device programmed" and then could not reopen the port, the board did not re-enumerate, a double-tap brought the HT-n5262 bootloader back, and CURRENT.UF2 showed the RNode vector table with reset 0x51819 sitting at 0x27000. lnflash then flashed over it and the board came up as 1209:0001 "leviculum T114".

What the bootloader tells you

Mounting the mass-storage drive gives three files: INFO_UF2.TXT, INDEX.HTM and CURRENT.UF2. The first is the entire basis for deciding whether a board can be flashed. Read from the rig, verbatim (CRLF line endings):

UF2 Bootloader 0.9.0-2-g836c8dc-dirty lib/nrfx (v2.0.0) lib/tinyusb (0.12.0-145-g9775e7691) lib/uf2 (remotes/origin/configupdate-9-gadbb8c7)
Model: HT-n5262
Board-ID: HT-n5262
Date: Jul  9 2024
SoftDevice: S140 7.3.0

UF2 Bootloader 0.4.3
Model: WisBlock RAK4631 Board
Board-ID: WisBlock-RAK4631-Board
Date: May 20 2023
Ver: 0.4.3
SoftDevice: S140 7.3.0

The SoftDevice: line is generated at runtime by the bootloader from the SoftDevice actually installed, so it answers the version question directly rather than by inference. The T114's Board-ID is exactly HT-n5262, not a substring of something longer, which retroactively justifies the substring match at leviculum-nrf/tools/uf2-volumes.sh:258.

Note the T114 bootloader build date matches Heltec's published HT-n5262-bootloader-20240709.hex, so that board still carries its factory bootloader.

What a UF2 is allowed to write

The bootloader validates every block's target address before writing. From src/usb/uf2/uf2cfg.h upstream:

#define USER_FLASH_START   MBR_SIZE   // skip MBR included in SD hex
#define USER_FLASH_END     (BOOTLOADER_REGION_START - DFU_APP_DATA_RESERVED)

in_app_space() accepts USER_FLASH_START <= addr < USER_FLASH_END; blocks below the window are skipped silently while still reporting success, and blocks at or above it are rejected outright.

Both bounds are measurable without reading a single constant, because the bootloader generates CURRENT.UF2 from exactly that window. On both rig boards it covers 0x1000 to 0x000EA000. So USER_FLASH_START is 0x1000, one MBR page, and USER_FLASH_END is 0xEA000. Nordic's own nrf_mbr.h agrees: #define MBR_SIZE (0x1000), carried through into the nrf-softdevice-s140 bindings as 4096.

The consequence is the important part: the writable window opens directly above the MBR and includes the whole SoftDevice region. An image converted from a SoftDevice hex has its MBR blocks declined and the rest installed, which is precisely what the skip MBR included in SD hex comment describes. A SoftDevice can therefore be replaced through the ordinary mass-storage path, without touching the bootloader.

leviculum-nrf/memory.x used to contradict this, computing safe application space as 0xEC000 - 0x27000 (788 KiB) — 8 KiB the bootloader would have refused to write. It now links the application against the bootloader's own window minus the record store's region and the boot-record page, 0xD9000 - 0x27000 = 0xB2000 (712 KiB); the image is ~660 KiB, so the change costs nothing today and the gate prints the remaining gap on every push (scripts/check-nrf-store-gap.sh).

Everything at or above 0xEA000 survives every UF2 flash, because the bootloader declines those blocks. All three persistence pages live there: identity at 0xEC000, the radio configuration at 0xEB000 and the telemetry target / fixed position / media profile at 0xEA000 (leviculum-nrf/src/boards/t114.rs, radio_store.rs, telemetry.rs). A user's chosen frequency therefore survives a firmware update as well as a reset.

The record store (#384, 0xDA000–0xEA000, 16 pages) survives one too, but for a different reason, and the difference matters because it is the weaker guarantee of the two. The store sits inside the writable window, so USER_FLASH_END does not protect it. What protects it is that the bootloader erases only the pages it writes: flash_nrf5x_write buffers one page and flash_nrf5x_flush (upstream src/flash_nrf5x.c) erases and programs exactly that page, and only when its content differs. Our .uf2 carries blocks from 0x27000 to the end of the image and none above it, so no page of the store is ever a target and no erase reaches one. That holds as long as the image stops below the store, which memory.x's ASSERTs make a link error and the gate above reports as a number.

The boot record (#380, 0xD9000, one page) is the same case one page further down, and it is where the image now stops: it counts the boots a field board made while nobody was watching (boot_count.rs), so it has to outlive both a power loss and a firmware update. It is protected by the same argument as the store and by no other — our .uf2 carries no block for it — and it is deliberately the thing directly above the image, so the linker's "will not fit in region FLASH" is the first thing an over-grown image hits. A foreign image, or a tool that writes blocks up here, erases the page; the record's magic is what makes the bytes it leaves read as foreign rather than as a count.

Family IDs seen in practice:

Only the last one touches the bootloader itself. A flashing tool must never emit it. With the bootloader intact, an interrupted flash is recoverable: the board comes back into DFU and can be rewritten. Replace the bootloader and a failure needs SWD to undo. There is a precedent for the general risk: a bad application build once left the RAK4631 in a HardFault boot loop that required opening the case to reach the internal reset button (commit 43d25830).

The SoftDevice

Our firmware links against S140 v7.x and places its application at 0x27000 (FLASH ORIGIN, leviculum-nrf/memory.x:84). A board carrying S140 6.1.1 puts the boundary at 0x26000 instead, so the version is not cosmetic.

The bindings we compile against are generated from S140 7.0.1 (SD_VERSION = 7000001, which decodes as major 7, minor 0, bugfix 1 — not 7.0.0 as docs/ble5-broadcast-protocol3-spike.md:39 states). The boards run 7.3.0. That works because Nordic keeps the ABI stable within a major version, which is what makes >=7.0.1, <8.0.0 the honest version constraint rather than a guess.

Reading the version without trusting the bootloader

INFO_UF2.TXT is the convenient source, but it depends on the bootloader choosing to emit the line. The SoftDevice states its own version in flash, independently: nrf_sdm.h puts the info struct at offset 0x2000 above the MBR, with the version word 0x14 into it, so the absolute address is 0x3014. The encoding is major * 1000000 + minor * 1000 + bugfix.

That address sits inside the range CURRENT.UF2 dumps, so it can be read without writing anything. Verified 2026-08-09 on both rig boards: the word reads 7003000, decoding to S140 7.3.0 and agreeing exactly with what each board's INFO_UF2.TXT claims. A tool that cross-checks the two is immune to a bootloader too old to report the line at all.

The image is not part of this repo's source. The crate dependency (leviculum-nrf/Cargo.toml:254) supplies Rust bindings, not the blob. The authoritative copy is Nordic's own distribution, downloaded 2026-08-10 to ~/coding/s140_nrf52_730/, containing s140_nrf52_7.3.0_softdevice.hex (md5 29013ba2d0507c25f62dffa96b6c67af), the API headers, release notes and s140_nrf52_7.3.0_license-agreement.txt. Parsed, the hex covers 0x0-0xB00 (MBR) and 0x1000-0x26498 (the SoftDevice itself, 149 KiB), which lands exactly below our 0x27000 origin once page-aligned.

For a while the only copy on our machines was inside a Meshtastic checkout. That copy is authentic — byte-identical after stripping CR, both files 9726 lines — but it had been converted to LF, whereas Nordic ships CRLF. Two consequences: an Intel-HEX parser must handle both, and the vendored image should be Nordic's original so that no build path leads through somebody else's repository.

Nordic's headers also settle two constants this page derived by other means. nrf_mbr.h defines MBR_SIZE (0x1000), and nrf_sdm.h gives SD_MAJOR_VERSION 7, SD_MINOR_VERSION 3, SD_BUGFIX_VERSION 0 — encoding to exactly the 7003000 both rig boards report from 0x3014.

The mismatch is a soft brick, not a dead board

Flashing our application onto a board still carrying 6.1.1 produces a device that goes dark: the old SoftDevice forwards to 0x26000, finds no vector table there because our image starts a page higher, and crashes before USB initialises. No CDC ports, no bootloader drive, nothing on the bus. It looks hardware-dead and is not. The bootloader region at 0xF4000 is never touched by an application flash, so a physical double-tap always brings the UF2 drive back. The 1200-baud touch is useless here, because the application never runs far enough to answer it.

Confirmed on 2026-08-08 on the T114 with serial 183004F712B4A7FE, which had been written off as bricked for weeks. Its INFO_UF2.TXT read SoftDevice: S140 6.1.1. That board was never part of the 2026-05 spike, which names only DEC9947DAD9D2869, so it is direct evidence for the factory state: factory T114 boards ship S140 6.1.1, as leviculum-nrf/memory.x:5 claims.

The SoftDevice carve-out: the RAK4631 states the constraint and ships no remedy

The version constraint is the same on both boards, >=7.0.1, <8.0.0, and for the same reason: our image is based at 0x27000 and cannot start on a 6.1.1 boundary. What differs is what the bundle can do about a violation.

For the T114 the remedy is measured end to end — a genuine 6.1.1 board was repaired unattended on 2026-08-10, recorded under "Verified on hardware" below. For the RAK4631 (Codeberg #261) it is unmeasured. Our only RAK, serial DEC9947DAD9D2869, has carried 7.3.0 since we first flashed it, so we have never seen the failing state on that board and cannot say what a factory Pocket V2 ships. memory.x:5 claims both boards leave the factory on 6.1.1, but that line predates the T114 measurement that confirmed it for the T114 alone.

So the bundle carries no SoftDevice for the RAK4631, deliberately. A precondition without a remedy is allowed by construction — Requires and Remedy are separate tables, and flow::resolve answers an unmet constraint with no remedy by refusing:

rak4631 needs SoftDevice >=7.0.1, <8.0.0 and the board has 6.1.1
(bootloader and flash agree), but this bundle carries no remedy for
that. Nothing was written.

That is the honest outcome for a case nobody has seen: "I cannot fix this, here is why" beats writing anyway, and it beats shipping a repair path whose only evidence is that the same blob works on a different board. The opposite arrangement is what the loader refuses outright — a remedy with no precondition to trigger it will not load.

What would close this. One factory or Meshtastic-stock Pocket V2 read through lnflash --dry-run under sudo, which prints the SoftDevice: line off INFO_UF2.TXT without writing anything. If it reads 6.1.1, the same vendored S140 7.3.0 hex serves this board too — it is an nRF52840 blob, not a board-specific one — and the carve-out becomes one line in scripts/lnflash-bundle.sh's board list plus the payload pair beside it. Until somebody reads one, the gap stays visible here rather than assumed closed.

Installing the SoftDevice

adafruit-nrfutil's serial DFU protocol does not work against the Heltec bootloader; the 2026-05 spike got "Timed out waiting for acknowledgement" (f517a172). Do not retry it. The mass-storage path works, and needs no SWD probe:

python3 ~/coding/meshtastic/bin/uf2conv.py -f 0xADA52840 -c \
  -o s140_7.3.0.uf2 \
  ~/coding/meshtastic/bin/s140_nrf52_7.3.0_softdevice.hex

Copy the result onto the mounted bootloader drive and sync. The application flashed earlier boots immediately afterwards; it was intact all along, only the SoftDevice beneath it was wrong.

The conversion is deterministic, so its output can be checked before anything is written. Reproduced 2026-08-09:

The last row is the one that matters: the update cannot reach the application, which is why the app survives it.

Eleven of those 608 blocks are never written. They carry the MBR below 0x1000 and the bootloader declines them, silently and with a success return. The block counter still sees all 608 arrive and reboots on the last one, so nothing about the transfer looks unusual. This is harmless, since the MBR is already present and identical, but it means an application-family UF2 can never replace an MBR, and a report that counts copied blocks is not evidence that all of them landed.

Why we cannot simply ship it

The SoftDevice is under Nordic's five-clause BSD variant, and two of those clauses decide the architecture of any flashing tool we build. This is a reading of the licence text, not legal advice.

Clause 2 permits redistribution in binary form, provided the copyright notice, the conditions and the disclaimer travel with the distribution. Clause 4 restricts use to Nordic silicon, which our case satisfies. Clause 3 is trivially satisfiable. So handing the blob to a user is allowed, as long as the licence goes with it.

The obstacle is the combination with our own licence. Clause 4 limits what the software may be used for, and clause 5 forbids modification, decompilation and disassembly outright. AGPL-3.0 grants every recipient the right to use and modify the whole work for any purpose, and permits no additional restrictions of that kind. A blob carrying clauses 4 and 5 therefore cannot become part of one combined work with AGPL code.

The practical consequence: the SoftDevice must not be linked into an lnflash binary via include_bytes!. That would make it part of the executable and put the two licences in direct conflict. Shipping it alongside as a separate file, with Nordic's own licence file next to it, is ordinary aggregation and does not have that problem.

Decided (2026-08-09): we ship it, as a separate file with its licence beside it, sourced from Nordic's own distribution rather than a third-party checkout. Our own firmware images travel the same way, even though being ours they could be embedded. One payload layout beats a split where some images live inside the binary and others outside, and it is what makes the bundle below the extension point for new boards. The binary stays a single static executable; it just is not the only file.

Ship Nordic's own licence file, not a copy of the text. The distribution includes s140_nrf52_7.3.0_license-agreement.txt, and it differs from the widely circulated LICENSE-NORDIC in exactly one line: its notice reads Copyright (c) 2007 - 2020, Nordic Semiconductor ASA where the other says only Copyright (c) Nordic Semiconductor ASA. Clause 2 obliges us to reproduce the above copyright notice, so the file that travels with the blob is the one Nordic shipped alongside it. It also names its own product and version, which the circulated variant does not. That is what lnflash/payload/t114/ vendors, next to Nordic's CRLF original of the hex.

Note also that Meshtastic vendors the blob under GPL-3 without any accompanying Nordic notice, so their practice is not the precedent it was taken for; it fails clause 2 on its face. The nrf-softdevice project is the counter-example worth copying: it is MIT/Apache licensed and places a LICENSE-NORDIC in every crate that carries Nordic material. That project has no copyleft conflict to solve, so it demonstrates correct attribution, not that the AGPL question goes away.

One further detail. Converting the hex to UF2 does not alter a byte, only the container, so it is hard to read as the "modification" clause 5 prohibits; still, distributing the untouched hex and converting at runtime avoids the question entirely.

CURRENT.UF2 as a backup

The bootloader exposes the installed flash as CURRENT.UF2, 1.9 MB covering 0x1000-0xEA000 under the board-specific family ID. Filtering it to blocks at or above 0x27000 and renumbering blockNo/numBlocks yields a restorable application image. Verified on both rig boards on 2026-08-09: read, filtered to 3120 of 3728 blocks, written back, and each board returned with its original serial and firmware ([FW_BUILD] git_sha=bb7c4f64 on the T114), PANIC_COUNT total=0.

That makes a flash reversible for the user who wants their previous firmware back, at the cost of one file copy before writing. The SoftDevice portion of the dump is not needed for restore and is filtered out; keeping it would only re-write identical bytes.

It also identifies what is installed, without running it. The dump is the application region, so the strings in it are the application's. Read off the Solar Node on 2026-08-17 it gave Meshtastic 2.7.15, build 567b8ea, build target seeed_solar_node, and an occupancy of 92.4 per cent that distinguishes a programmed board from a blank one. Two uses follow. A tool can name what it is about to overwrite instead of reporting that it found "a board", and where the Board-ID is ambiguous the foreign firmware's own build target often names the carrier that the bootloader does not. The second use is inference from a third party's build strings and belongs in a prompt to the user, never in a silent decision to write.

Practical details that bite

The USB serial number may change between modes, and whether it does is board-specific. The T114 reports 183004F712B4A7FE as an application and 12B4A7FE183004F7 in the bootloader: the two 32-bit words are swapped. The Solar Node reports 40E37463CA8A59DF in both, unchanged (measured 2026-08-17). Anything correlating a device across app to bootloader to app must therefore accept both forms rather than assume either. That is what same_serial (lnflash/src/usb.rs:140) does: it tests equality first and the swap only as an alternative, so a board that keeps its serial is matched as readily as one that swaps it. The older runner is unaffected because it only compares serials in application mode (leviculum-nrf/tools/uf2-runner.sh:287).

Writing needs root. The mass-storage device appears as /dev/sdX owned root:disk. Automounting assumes a desktop stack that a headless host does not have. A single self-contained binary can read USB identity from sysfs and issue the touch through termios without any external tool, but it cannot write the drive unprivileged.

A successful write ends in a kernel error. The bootloader reboots the moment the final UF2 block lands, while the filesystem still wants to flush metadata, producing device offline error ... lost async page write. This is the normal completion path, not a failure (leviculum-nrf/tools/uf2-runner.sh:234).

A copy returning 0 does not mean the flash took. Verify that the application re-enumerated and that the bootloader drive is gone (leviculum-nrf/tools/uf2-runner.sh:308). Stronger still, read the periodic [FW_BUILD] banner off the debug port and compare the git SHA, as scripts/flash-lnodes-from-head.sh:113 does.

More than one board can be in its bootloader at once, and the wrong one is usually first. The volumes are anonymous mass storage; only Board-ID distinguishes them. A tool that takes the first UF2 volume it finds and stops looking will be handed the same wrong volume on every retry, refuse it every time, and never examine the board it was asked to flash. find_uf2_drive therefore enumerates every candidate and poll_matching_drive selects across the whole set (leviculum-nrf/tools/uf2-volumes.sh).

A mount you make is a mount you owe back. Mounting a volume to read its Board-ID and then leaving it behind because it was the wrong board is worse than not looking: the leaked mount shadows every later board in the search path and survives until somebody unmounts by hand. Volumes this tooling mounts go under /run/leviculum-uf2/<device> — one mount point per device, never the single shared /mnt, so a foreign volume cannot occupy the only slot — and are released on every exit path.

A give-up message must report, not assert. The runner used to end every failure with "app never re-enumerated" even when no volume for the board had ever been found, naming a symptom that had not been reached. It now names the volumes it saw and their Board-IDs.

Structuring a flashing tool

Everything above is mechanism. What follows is the shape a tool takes if it has to survive more boards than the two we support today.

Start with how wide the field actually is. The Meshtastic tree carries 162 variants, and they collapse onto very few flashing mechanisms:

Two transports cover 155 of the 160 flashable variants, and we already own both: the UF2 path in leviculum-nrf/tools/uf2-runner.sh and the ESP path behind Justfile:774, which drives esptool. The work is not building 162 things. It is separating two mechanisms cleanly and turning everything else into data.

Four axes, not one "board"

Treating a board as one indivisible unit is the design mistake to avoid. A board is four independent answers, and a new device rarely changes all four:

Identify — what is attached? For UF2 boards the truth is the Board-ID in INFO_UF2.TXT; for ESP32 it is the chip identity the ROM bootloader reports. Never the USB ID of the running application, which belongs to whatever firmware happens to be installed.

That truth is authoritative but not always sufficient, and the condition under which it is sufficient can be stated exactly:

A Board-ID carries a write decision only where it is bound to the same physical unit as the radio wiring. Where the two are bound to different units, a match is a hint.

Three real bindings, all measured in 2026-08:

• Coupled. On the RAK4630 the SX1262 wiring and the bootloader both belong to the module. Twelve different carriers report WisBlock-RAK4631-Board and share seven identical pin numbers. The key is exact, and one image serves all of them.
• Decoupled by the vendor. Heltec records the same bootloader product string HT-n5262 for the Mesh Node T114, for MeshSolar and for the Mesh Pocket. The first two share our wiring; the Mesh Pocket puts CS on P0.26 and BUSY on P0.15. The identifier belongs to a bootloader shared across models while the wiring belongs to the model.
• Decoupled by construction. The Seeed XIAO is an MCU module with the radio outside it, so a SenseCAP Solar Node and a DIY XIAO with different radio wiring both report nRF52840-SeeedXiao-v1.

In both decoupled cases a manifest entry keyed on info_uf2_board_id alone is not a decision. Such a board needs a second discriminator or an explicit question naming the model, and the honest failure is to stop and ask rather than to write the more likely of two images. The cost of getting this wrong is not a failed flash but a board driving the wrong pins, which on hardware carrying a power amplifier is a repair rather than a retry.

The cheaper answer, where it is available, is to make the ambiguity stop mattering. The RAK4631 looks like the same problem, since the bare module and the Pocket V2 share a Board-ID and have separate builds, but the baseboard build degrades cleanly on a bare module: the display is found by an I2C probe and its task exits when nothing answers (leviculum-nrf/src/display.rs:161-167), the button pin is pulled up so it never reads as pressed (leviculum-nrf/src/button.rs:37), the GNSS task waits on a UART that stays silent, and the battery task publishes into a watch channel whose only subscriber is the display that is not running. One image therefore covers both, at 47.6 KiB of flash and 2.5 KiB of RAM that the bare module does not use, and the RAM cost is already proven affordable because the same image runs on a Pocket V2 with the same chip and the same memory. Prefer that over asking a question, and reserve the discriminator for boards whose peripherals genuinely cannot be probed.

Enter — how does it reach a programmable state? 1200-baud touch, physical double-tap, a DTR/RTS sequence on ESP32, BOOTSEL on RP2040.

Transport — how do the bytes get in? The two above.

Verify — did it take? Re-enumeration plus the [FW_BUILD] banner with a matching git SHA.

Crossing all four sit preconditions. The SoftDevice version is the only one today; a bootloader minimum version would be the next. A precondition must be data that names its own remedy, never a special case in code.

Separated this way, a new nRF or RP2040 board is data entry, and a new chip family costs exactly one new transport.

The bundle is the extension point

Since third-party blobs cannot be linked in anyway, the payload lives beside the binary and the manifest describes it:

lnflash                     # board-agnostic binary
firmware/
  manifest.toml             # index, checksums, licences
  t114/
    leviculum-t114-0.8.0.uf2
    s140_nrf52_7.3.0_softdevice.hex
    s140_nrf52_7.3.0_license-agreement.txt
  rak4631/
    leviculum-rak4631-0.8.0.uf2

The second board arrived in Codeberg #261 and cost exactly what this structure promised: a catalogue entry, an image, and a line in the board list scripts/lnflash-bundle.sh walks. No Rust changed except the per-board wording of the one prompt a human has to act on — see "Getting into the bootloader" below.

Note what the RAK directory does not contain. The SoftDevice remedy is per board and this bundle carries none for that one; see "The SoftDevice carve-out" below for why, and what a board that needs it is told.

The data is split in two by what it describes. Board facts — USB IDs, Board-ID, flash geometry, the SoftDevice constraint — are properties of the hardware and do not change when a release is cut, so they live in lnflash/catalogue.toml, compiled into the binary:

[board.t114]
family        = "nrf52840"
candidate_usb = ["1209:0001", "239a:8071"]

[board.t114.flashing]
transport = "uf2-msc"
entry     = ["touch-1200", "double-tap"]
identify  = { info_uf2_board_id = "HT-n5262", bootloader_usb = ["239a:0071"] }
requires.softdevice = ">=7.0.1, <8.0.0"

The entry is itself split, along the same seam (Codeberg #233). The top level is what talking to a running board needs, and it is one field: the USB IDs its firmware answers on. Everything a write needs sits under flashing, and that table is optional. A board with none is control-only — --watch, --announce, --set-time and the --radio-* flags reach it exactly as they reach any other board, while no bundle may carry an image for it, --board <name> is refused before the bus is read, and a flash session that meets it on the bus says so and does not even reboot it.

That is not a lesser kind of support; it is the honest kind for a board whose Board-ID is not an identity. The two halves rest on different evidence: a control frame reaches a board that is up and identifying itself, while a write rests on what a bootloader publishes. The Solar Node is the first such entry, and the reason is data rather than a comment — a control-only board must state not_flashable, which is the sentence the user is refused with, and stating both halves or neither fails to load. The refusal is therefore impossible to lose to an edit that widens the entry by accident.

Release facts — which images this tarball carries, what they hash to, and which compiler produced them — are the bundle's:

[bundle]
version = "0.8.0"
rustc   = "rustc 1.97.1 (8bab26f4f 2026-07-14)"

[board.t114.app]
file    = "t114/leviculum-t114-0.8.0.uf2"
sha256  = "..."

[board.t114.remedy.softdevice]
file    = "t114/s140_nrf52_7.3.0_softdevice.hex"
license = "t114/s140_nrf52_7.3.0_license-agreement.txt"
convert = "hex-to-uf2"

The split is Codeberg #342. Before it, both halves were in the bundle manifest, and run() loaded it before dispatching — so --set-time and --set-telemetry, which read nothing but the USB IDs, refused to start without a firmware bundle on disk. Activation is configuration, not firmware (#236/#238); somebody pointing a node they already own at an LXMF address was being sent to hunt for an image they had no use for. The configure-only sessions now take the catalogue and never locate a bundle at all; the flashing paths locate one and still fail with no bundle found, naming every place they looked.

A bundle built before the split still loads: its board-fact sections are ignored, and the catalogue in the binary reading them is the more trustworthy of the two copies anyway, since binary and bundle ship together. A bundle built before rustc was recorded loads too, and lnflash says the compiler is unrecorded rather than refusing an image it can still verify against its checksum.

rustc is the compiler that produced both the images and the flasher beside them, and it is rustc --version as the bundle build ran it rather than the channel rust-toolchain.toml names (Codeberg #305). Whichever image a board is running, the first question behind "these two boards behave differently" is which compiler built each of them: this is embedded code with a measured 3264-byte stack-frame margin, and codegen differences between compiler versions move frame sizes. scripts/lnflash-bundle.sh asks both workspaces and refuses to write a manifest claiming one compiler for a bundle built by two.

A new board still needs no new binary in the sense that matters — it is data entry, in the catalogue plus one image. The license field is not bureaucracy: it makes shipping a third-party blob without its licence impossible by construction, which is exactly the mistake described above. Board names stay identical to the firmware-side ones in leviculum-nrf/src/boards/mod.rs:39, so that two namespaces never diverge.

Identify in two stages, write only after

Before entering the bootloader we know only "some USB device". The reliable identity exists only afterwards. The order is therefore: find candidates, enter, confirm identity there, check preconditions, check the checksum, and only then write. No write may rest on a guessed identity. Commit 362c1c2d records why: a T114 image once landed on a RAK4631 during bring-up. Several devices on the bus must each be resolved individually rather than assuming "the one UF2 drive".

Confirm by reading back, do not infer

The stage above resolves identity before the write. Afterwards there is a second, separate question — which board actually received it — and a UF2 mass-storage volume gives no help with it at all: the volume carries no board serial, so a runner that finds one has no way from the volume alone to say whose it is.

uf2-runner.sh used to answer by pairing the volume with a candidate from its own USB enumeration, which yields a board of the right type and not the board that owns the volume. With two T114s attached, one in DFU and one running, it wrote to the one in DFU and reported the other. Measured twice on the rig, 2026-08-23 and 2026-08-24, naming the opposite board each night — the answer follows enumeration order, which is neither stable nor related to which board was in the bootloader (Codeberg #343). The same gap made flash CONFIRMED mean "a board of this type re-enumerated" rather than "the named board runs the named image".

The fix is a read-back, and it turns attribution into a measurement:

• The firmware carries leviculum_nrf::FW_BUILD_STAMP, one contiguous literal git_sha=<sha> dirty=<bool>, and prints it after [FW_BUILD] at boot and every five seconds thereafter.
• The runner greps that same literal out of the flat image it is about to write (tools/fw-readback.sh, fw_image_stamp). Not out of git rev-parse: that describes the working tree at the moment of the question rather than the bytes going to the board, and it cannot express a dirty tree at all, so two different images built from one commit would both answer with that commit.
• After the copy it opens the candidate's debug port and requires the stamp to match. If the named board is carrying something else, the other attached candidates are asked, and the one that answers with the image is the one the summary names.

Three outcomes, kept apart on purpose, because they need different things done to them:

A board can legitimately fail to answer — crashed firmware, a port that never appears — and silence must never be reported as wrong firmware, nor as right firmware. When the write cannot be bound to any board at all, the runner says exactly that (flash UNATTRIBUTED — … the runner does not know which board it wrote) and exits non-zero. A guess in that position is what produced the ticket.

Two constraints the read-back has to respect, both long established on the rig: the debug CDC transmits only with DTR and RTS asserted, so a port opened without them is silent for reasons that have nothing to do with its firmware; and the by-id symlinks are the stable handle (-if00 debug, -if02 transport), because a /dev/ttyACM* number is a position and moves between enumerations — trusting a position for an identity is the defect itself.

tools/test-fw-readback.sh (just nrf-fw-readback) drives all of this against stubbed boards, so it runs with no hardware.

The line has to be one the board said after the reset

Reading a window and keeping the last [FW_BUILD] in it is not the same question as "what is running now". The port's input queue was filled before the question was asked, and a line in it is an answer to a question nobody asked — on 2026-09-09 that made lnflash report

1 of 2 board(s) confirmed running the firmware in this bundle.
  1-1 (rak4631): not confirmed — Some(WrongBuild { saw: "ead0bce", expected: "daa8b8e" })

about a board whose own debug port said git_sha=daa8b8e seconds later. ead0bce was the build that had been running before the flash. A completely successful flash exited non-zero, which stops any script that chains on it (Codeberg #378).

The confirmation therefore establishes a boundary the tool itself creates, and only accepts what comes after it (lnflash/src/verify.rs, fresh_banner):

• The board must have left the bus. If the bootloader is still there when the wait times out, the board never rebooted into what was written, and nothing a port says next is about the new image. That is Absent, not a build claim.
• The port's input queue is flushed on open — one tcflush, the same one every control transaction does — so no line from the previous session can be read as an answer.
• The debug port is resolved to its by-id path and the open is proved against the board's bus identity before a byte is read (entry::wait_for_interface_tty, flow::open_debug). A bare /dev/ttyACM number is a position, and on a multi-board run the board it moves to is the one still carrying the firmware this flash replaced.
• Only a complete line counts. A half-read git_sha=daa8b8e parses as daa8 and would be reported as a different build — a failure manufactured out of a partial read.
• A line the firmware is quoting is not a line the firmware claims. At boot our images re-emit the last ~2 KiB of the previous boot's log out of retained RAM, each line wrapped in [PERSISTENT_LOG] (leviculum-nrf/src/bin/t114.rs, the persistent_log block). That replay includes the previous firmware's own [FW_BUILD] banner, so a board that has just booted into a new image says the old image's sha within milliseconds of the port opening — after the reset, after the flush, and still not about itself. The wrapper is what disqualifies such a line; its arrival time is not consulted.
• A banner that is not the one we wrote does not end the read. The read is told which sha it is waiting for: a matching banner is an answer and stops it, anything else is kept as evidence while the read goes on. The board repeats its banner every five seconds, so the expected build gets another chance for as long as the budget lasts, and a stale line — from the replay or from anywhere else — gets exactly one. Only the last non-matching line, once the budget is gone, is reported as "the write did not take". A genuinely failed flash therefore costs the whole 15 s budget; the alternative is believing the first line on the port, which is what #372 did.
• The budget is three banner periods, 15 s. The firmware emits one every 5 s, so a healthy board answers inside the first; the margin covers a board whose banner task ticks just before the port opens and a line the flush cut in half. A board still silent after that is silent, and silence is unknown.

This is the second false negative of the same shape and the reason the rules above are structural rather than temporal. On 2026-09-27 the rig flashed a T114 and a RAK from one bundle (/home/lew/rig-run/boot-proof-flash.log, section === flash 01eb398b 2026-09-27T20:37:14):

3-2.3.4.4: back as leviculum T114 [1209:0001]
3-2.3.4.4: the board reports git_sha=abaea121f, not 01eb398b7, read as a
     [FW_BUILD] banner line on …_T114_183004F712B4A7FE-if00
     (/dev/ttyACM0), 0.0 s after that port was flushed.
     The write did not take.
lnflash rc=1, 1 of 2 board(s) confirmed

The board's own capture has [FW_BUILD] git_sha=01eb398b7 … t=7448 92 seconds later: the write had taken. What lnflash read was the new firmware quoting the old one (Codeberg #372).

The exit code carries the same three-way split, because "not confirmed" and "failed" need different things done about them:

Naming the old sha as if it were current is the defect. A confirmation that cannot decide says unknown and never names a sha it did not read.

Every build claim names where it was read

The rules above are what the confirmation does; they are not, by themselves, evidence that it did it. On 2026-09-11 the same report came back on a two-board run under a capture reader holding if00 on both boards:

1-1: back as leviculum RAK4631 [1209:0002]
1-1: the board reports git_sha=b9b4a9c3, not de6e74ed. The write did not take.
1-2: running git_sha=de6e74ed. Done.

That line names a sha and nothing else, so the first question it raises — was that line read on this board's own port at all? — needed two capture files and a hand correlation, and ended undecided. A claim the operator cannot check is not much better than no claim.

So every build claim carries its provenance (verify::Source), and the verdict prints it:

1-1: running git_sha=de6e74ed, read as a [FW_BUILD] banner line on
     /dev/serial/by-id/usb-leviculum_RAK4631_DEC9947DAD9D2869-if00
     (/dev/ttyACM3), 4.2 s after that port was flushed, the line
     stamped t=7448 ms of board uptime. Done.

Four facts, each answering a question the bare sha left open: which mechanism decided it (the banner read after the reset — the control envelope carries no build query, so there is only one), which path was opened and which node the fd was proved against, how long after the flush the line arrived, and the t=<ms> the line stamped itself with. The delay is the load-bearing number: a banner from a board that has just booted arrives seconds in, so a sha delivered in the first milliseconds was already in flight and the claim deserves that doubt. The uptime stamp is what separates the two ways that can happen — a fresh boot stamps its first periodic banner near 5000 ms, while a line quoted out of retained RAM carries the stamp of a session that had been up for hours (#372). Both are reported, neither is judged: a rule that refused a line for its stamp would be guessing at how fast a board boots.

just nrf-shellcheck (Codeberg #345) is the static half of the same coverage: shellcheck -x over leviculum-nrf/tools/*.sh and scripts/flash-lnodes-from-head.sh, which sources them. The scripts carried # shellcheck directives long before anything ran them, and an SC2034 and an SC2015 sat in the runner until #341 and #343 happened to remove them. It runs from the repo root because the source= directives name repo-relative paths.

The radio configuration belongs to the flash

A board that has just been written runs the compiled eu_medium profile, and until the firmware learned to remember a configuration (radio_store.rs) there was nowhere else for one to live: every host that bound the board had to send the frequency again, and a standalone LNode with no host had no way to be on anything else.

With the flash page in place the honest moment to choose is the flash itself, once. lnflash therefore ends its sequence with a fifth step: after the [FW_BUILD] banner confirms the write, it asks "Flash default radio settings? [Y/n]". Enter takes the eu868 preset; "n" opens a preset menu — eu868, us915, au915, custom — where custom is the five-number field-by-field path. The choice goes to the board's transport CDC; since #238 lnflash opens with a capability probe and sends the configuration inside the control envelope (docs/src/firmware/usb-control-envelope.md), falling back to the legacy magic-prefixed frame lnsd still uses (leviculum_core::rnode::build_radio_config_frame, HDLC-framed, answered by RADIO_CONFIG_ACK) when the probe goes unanswered. Non-interactively, --radio-preset <eu868|us915|au915> names a preset outright; it cannot be combined with the --radio-* value flags (two ways to state one configuration).

The presets are community profiles, not conformance claims

The names look like regulatory bands, which is why the menu spells out what they actually are: the settings each regional Reticulum community has converged on (the Reticulum wiki's "Popular RNode Settings"), with the regulatory situation documented next to them rather than implied by the name.

eu868 is the ReticulumNet consensus channel and the compiled firmware default. The channel sits in the band ERC 70-03 Annex 1 designates as h1.7 (869.4-869.65 MHz, 500 mW e.r.p.), so 22 dBm conducted stays lawful up to roughly 7 dBi of antenna gain, and the derived long-term airtime lock arms the ETSI 10 % duty cycle.

us915 follows the US community, and the tool prints a note when it is chosen because power conformance is not the whole story: FCC 15.247(a)(2) requires at least 500 kHz of occupied bandwidth for non-hopping digital systems, which a fixed-frequency 125 kHz node does not meet. The preset ships the profile the entire known US Reticulum scene runs; whether that is lawful for a given deployment is the operator's call, and the note says so at selection time, not in a footnote.

au915 matches the Western Sydney and Brisbane communities. Under the ACMA LIPD class licence (915-928 MHz, digital modulation, 1 W EIRP, no minimum bandwidth) 22 dBm plus a typical antenna sits far under the limit — sourced from two agreeing secondary references, as the primary ACMA text could not be retrieved.

eu433 is decided but deferred: ERC 70-03 allows 10 mW e.r.p. at 433.05-434.79 MHz, i.e. 10 dBm, and the SX1262 driver's lowest PA profile is 14 dBm. Offering the preset today would transmit 4 dB over the limit, so asking for it is refused with that reason until the driver can produce 10 dBm.

Three details are not obvious:

The step cannot fail the flash. It runs after the firmware is on the board and confirmed. A board that does not answer is a board running the compiled default, which is a warning and a re-run, not a failed flash.

Two of the seven wire fields are not the user's to state. The preamble is derived from the PHY the way the RNode firmware derives it (derive_preamble_symbols); a preamble belonging to a different SF mis-prices airtime on both sides. The long-term airtime lock is sent at the value the firmware would have derived for the chosen frequency, because the frame's own presence (lt_alock_present) switches that derivation off — sending zero would persist "no duty-cycle limit" onto a board whose operator only picked a frequency.

Validation happens before the board is touched. --radio-sf 3 and a bandwidth the SX1262 has no register code for are refused at the command line. Left to the board, an unparseable frame is silently dropped and looks exactly like a dead port.

An unavailable preset refuses the same way: --radio-preset eu433 stops the run with the 10 dBm reason before any board is enumerated, rather than shipping a board 4 dB over the limit.

The real bottleneck is not the tool

A manifest invites the belief that the whole palette is a matter of configuration lines. It is not. Our firmware supports exactly two boards today, bsp-t114 and bsp-rak4631. A manifest entry without a matching firmware build is an empty promise, and a LoRa board needs more than an entry: pin mapping, TCXO voltage, SPI frequency and maximum transmit power all live in BoardConfig and have to be right per device and measured.

The structure should therefore follow the firmware side's growth rather than anticipate it. The value appears immediately and independently of it: a tool that identifies a board reliably, checks the SoftDevice precondition, and says "I do not know this board" instead of writing to it is what is missing today.

Deliberately not

No plugin system with shared libraries; it contradicts the statically linked binary. No scripting language in the manifest — such fields become a programming language within a year; when declarative data is not enough, the answer is a new transport in Rust. And no fetching firmware from the network: it contradicts "no infrastructure" and adds an attack surface to a tool that overwrites other people's devices with root privileges.

The structure proves itself on the second board, not the first. Building the UF2 transport for the T114 alone, but already split along the four axes and driven by the manifest, is only a claim until the RAK4631 — same transport, different board ID, different bootloader — runs through without a code change.

Verified on hardware

The factory path was exercised end to end on 2026-08-10, on the T114 with serial 183004F712B4A7FE, using the tarball rather than the repo build.

A genuine factory state was reconstructed rather than waited for: the 6.1.1 SoftDevice was extracted from Meshtastic's combined hex and trimmed to the window 0x1000-0x27000, which drops 11 MBR blocks and 135 blocks that would have written bootloader, bootloader settings and UICR. Without that trim the bootloader rejects those blocks and the whole copy fails; had it accepted them, it would have been the brick path. The board then went dark exactly as predicted, and did not stay in DFU — a physical double-tap was required, confirming the 2026-08-08 observation.

From there the tool ran unattended: it read SoftDevice 6.1.1 with bootloader and flash agreeing, found >=7.0.1, <8.0.0 violated, installed the SoftDevice (608 blocks, 11 declined), and then — the part worth naming — the board rebooted into the old application, which now booted because its base finally matched the installed SoftDevice. The tool touched it back into the bootloader, re-read the version as 7.3.0, and wrote the current application. That re-entry is the step a naive implementation gets wrong by answering "wait for the bootloader" with the pre-reboot sysfs entry.

That the application runs at all is the independent proof that the SoftDevice is 7.3.0: an image based at 0x27000 cannot start on 6.1.1. The board was confirmed afterwards over the debug port at git_sha=d82ccfc with LoRa cycling normally.

Also confirmed in the same session: a board already sitting in its bootloader is handled without a redundant touch, several devices on one bus are resolved individually, and a RAK4631 on the same hub is neither offered nor written to, because it had no catalogue entry.

That last clause is now history rather than behaviour. Codeberg #261 gave the RAK4631 its entry, so a Pocket V2 on the same hub is found, hinted at its own board, brought into its own bootloader and written its own image — and a bundle that carries no image for it says so in those words rather than falling silent. The property the 2026-08-10 session actually demonstrated is the one that survives: each device is resolved individually, and no write rests on an identity the bootloader did not publish. The structure's own claim — "the second board proves it" — is what #261 collected on: the RAK reached hardware readiness through a catalogue entry, an image, and one board-list line, with no change to the transport, the identify step or the write path.

Open questions

• Does the touch handler exist in Meshcore, microReticulum or RNode firmware on nRF? Unmeasured; assume no, and fall back to the double-tap prompt.
• Nothing further on the SoftDevice. Provenance, version constraint and the two independent ways to read the installed version are settled above.
• Whether boards leaving the factory today still carry 6.1.1 is unknown; the measured board is one unit from one batch. A tool must read INFO_UF2.TXT and decide, never assume a version.

OTA stage 1: entering BLE DFU on a command from the mesh

Status: concept, not scheduled.

Every firmware update this project has ever shipped ended with a hand on the board: a cable, or a needle in a pinhole (Flashing an LNode). That is fine for a board on a desk and wrong for the one on the roof, in the hedge, or two valleys away. Stage 1 splits the problem along the seam where it is cheapest to split it:

The decision travels the mesh. The bytes do not.

A command over Reticulum — any carrier, any hop count — puts the board into the bootloader's BLE DFU mode. Somebody then walks up to within Bluetooth range with a phone and pushes the image. Nothing about the image itself crosses the radio. OTA stage 2 is the document for when nobody can walk up at all, and it costs orders of magnitude more.

What the bootloader already does for us

All three board types carry a factory Adafruit nRF52 bootloader, and that bootloader — not our firmware — owns DFU. Besides the UF2 mass-storage mode the flash runner uses, it has an over-the-air mode speaking Nordic legacy DFU over BLE. Both modes are selected the same way: a magic value in GPREGRET, the retained register that survives a soft reset, read by the bootloader on the next boot.

We already drive one of them. The 1200-baud touch writes DFU_MAGIC_UF2_RESET (leviculum-nrf/src/usb.rs:226) and resets, and the bootloader comes up as a mass-storage volume. The OTA mode is a different constant written to the same register at the same point by the same code path.

The tree already knows the OTA mode exists, from a direction that had nothing to do with flashing: memory.x reasons about it because in OTA mode the bootloader enables the SoftDevice itself, whose RAM then reaches up over the retained band (the RETAINED comment, leviculum-nrf/memory.x:142, and Recovery, step 2).

Open, and it must be closed by reading rather than remembering: the exact magic byte. INFO_UF2.TXT names the bootloader build each board carries (0.9.0 on the T114, 0.4.3 on the RAK — see Flashing an LNode, "What the bootloader tells you"), and the constant belongs to that build's source, not to anybody's memory of the Adafruit tree. Writing a wrong magic is harmless — the bootloader ignores what it does not recognise and the board boots normally — which makes this cheap to settle on the bench and unacceptable to guess in the document.

The control frame, and why it cannot be the one we have

We already have a control plane to the firmware: the #238 envelope, one framing for every host command, with TYPE_RESET among them (leviculum-core/src/envelope.rs:79). It is unauthenticated, and deliberately so — read its header (leviculum-core/src/envelope.rs, "Framed control envelope for the LNode USB channel"): every argument in it is about framing and about not colliding with Reticulum packets, and none is about who is allowed to send this, because the answer was "whoever holds the cable". A frame that arrives over the mesh has no cable behind it, so the envelope's trust model does not travel with its wire format.

The pattern that does travel is already in this tree, on the propagation node's control destination: the request runs over a Link, the remote's identity hash is taken from that link, and it is checked against an allow list before any verb is answered — with a typed refusal, not silence, when it is absent or unlisted (answer_control, lnpnd/src/engine.rs:988; the check itself at lnpnd/src/engine.rs:1001). The list is operator configuration (control_allowed, lnpnd/src/config.rs:532) and the node's own identity is always on it. Codeberg #384 part 4 built that because the reference has it; stage 1 needs exactly the same shape for a different verb.

What a board needs on top of the daemon's version:

• The list has to survive a reset, so it is a flash record, and it belongs in the band the bootloader declines to overwrite — the same band the telemetry target, the radio config and the identity live in (leviculum-nrf/memory.x, the 0xEA000–0xEC000 pages). The telemetry target is the closest existing model for the record shape: magic, version, checksum, and a blank page decoding to "nobody" rather than to a garbage identity (leviculum-core/src/telemetry_target_store.rs). A board whose allow list decodes to "nobody" accepts no remote DFU command at all, which is the correct default for a board that was never configured.
• A replay of a captured frame must not work. A Link is not a replayable object — it is established, identified on, and forward secret (Cryptographic identity and forward secrecy) — so requiring the command to arrive on an identified link already carries most of this. What it does not carry is the operator's own mistake: the same command sent twice. That is harmless here (a board already in DFU is not made worse by being told again) and it is worth stating rather than discovering.
• Nothing about the carrier. Whether the command arrived over LoRa, BLE or TCP, and over how many hops, is not the board's business (Interface isolation). A command that only works at one hop is a command that does not solve this page's problem.

What the board does on the command

Validate, acknowledge, write the magic, reset. In that order, and the order is the whole of it.

The acknowledgement has to leave before the reset, because in this scenario there is no second channel: on the cable the operator sees the port disappear and the volume appear, and over the mesh the ack is the only evidence the command was ever received. A board that resets first and acks never is indistinguishable, from the far end, from a board that never heard anything.

The write itself has a hot-path constraint that the UF2 path already pays and that a mesh path pays in full: between the GPREGRET write and sys_reset() there must be no await, no allocation and no logging, and under a live SoftDevice the write must go through the SoC syscalls rather than the register, or it records a bogus MWU panic per attempt (leviculum-nrf/src/usb.rs:226-254, Codeberg #249). A mesh-borne command always arrives with the SoftDevice enabled, so only the syscall branch of that code is ever exercised — the branch the cable case takes least often.

What the bootloader advertises, and what disappears

While the bootloader is in OTA mode, our firmware is not running. Our BLE identity is gone, the Columba service is gone (leviculum-nrf/src/ble/columba.rs:122), the LoRa interface is gone, the board is off the mesh. To a phone it is a different device with a different name, and to the mesh it has vanished. That is not a side-effect to be engineered away; it is what DFU is, and it is the reason the timeout question below is the important one on this page.

What it advertises — the service UUID, the device name, whether the address is resolvable — is a measurement, not a recollection, and this project has a sniffer and the tooling to take it (Bluetooth interfaces); nRF Connect on a phone answers it in one scan without any of that. Nothing downstream should be designed against a remembered UUID.

The open question: does DFU mode ever come back on its own

Open. It has two possible answers and they differ in how dangerous stage 1 is:

• It times out and boots the application again. Then a command sent to a board nobody reaches costs one reboot and one gap in the mesh, and the boot counter records it (BOOT_COUNT n=… reset_reason=…, Codeberg #380). Stage 1 is safe to use on any board, including one that cannot be reached physically.
• It waits indefinitely for a connection. Then a command sent by mistake — or one whose operator's plan changed — takes the board off the mesh until somebody physically resets it. On the roof that is a ladder; in the hedge it is a walk; two valleys away it is the end of that node until spring.

How to settle it, and it is one afternoon on the bench: put one board into OTA mode, connect nothing, and watch the debug port. If the application comes back, BOOT_TRACE and BOOT_COUNT say so on the next boot and the elapsed time is the timeout (leviculum-nrf/src/boot_count.rs:122, Codeberg #380). Hold it for at least an hour before concluding there is no timeout; a short watch that sees nothing has measured nothing. The bootloader's own source for the build on the board is the second reading, and the two together are the answer.

Until that measurement exists, the honest scope of stage 1 is boards somebody can still reach on foot — which is most of them, and already worth having, because reaching a board on foot with a phone is much cheaper than reaching it with a laptop and a cable.

Failure modes, and why an interrupted transfer is survivable

The fourth row is the one that makes stage 1 worth doing at all. A DFU that dies halfway leaves the bootloader intact, because nothing in this path ever writes the bootloader region: it sits above the bootloader's own USER_FLASH_END and every mechanism here declines writes there (Flashing an LNode, "What a UF2 is allowed to write"). An interrupted transfer therefore produces a board sitting in DFU waiting to be told again — not a dark board. A bad UF2 write, by contrast, produces a board that boots into nothing and enumerates nothing, which is the state that costs a pinhole and a needle.

What stays physical, unchanged. A board whose application has crashed answers no command, over any carrier, because nothing is running to answer it. The double tap remains the only trigger that works regardless of what is on the board, it needs a human, and on a Pocket V2 it needs a needle (Recovery, the hidden-pinhole caveat). Stage 1 does not shrink that set; it shrinks the set of routine updates that fall into it.

lnflash, and the phone that needs nothing from us

A phone running nRF Connect speaks Nordic legacy DFU today. It needs one .zip package from us and no code at all, which means stage 1's useful half — the control frame — is the only thing that has to be built before the first remote update is possible.

Teaching lnflash the same trick is a separate and much larger decision. It would need a BLE central stack (BlueZ through bluer or btleplug), the legacy DFU control-point and packet characteristics, the init packet and the package format — and, more expensively, a live D-Bus and a running bluetoothd underneath. lnflash today is a single static binary that shells out to nothing and calls syscalls rather than programs, and that is a stated property of the bundle, not an accident (lnflash/Cargo.toml, the libc dependency's comment; Flashing an LNode). Adding a BLE central spends that property. It may still be the right trade one day — for a fleet, a phone in the loop is the bottleneck — but it is not free and must not be smuggled in as an implementation detail of this page.

What stage 1 does not solve

Somebody has to stand within Bluetooth range of the board. Where that is impossible, the image itself has to travel the mesh, and OTA stage 2 measures what that costs — in hours of channel time, in hardware two of our three boards do not have, and in the one piece of code in this system whose bug is an unrecoverable board.

OTA stage 2: the image itself over the mesh

Status: concept, not scheduled. Conditional on hardware two of our three boards do not have.

OTA stage 1 moves the decision over the mesh and leaves the bytes to somebody standing within Bluetooth range. This page is for the board where nobody can stand: the image travels the mesh too, as a signed Reticulum Resource to the board's control destination, is staged on external flash, and is written into the application window by a copier that runs from RAM. A golden image and the boot counter undo it when the new image does not come back.

Two numbers decide almost everything below, and neither is negotiable: the application window is smaller than two images, and a 620 KB transfer costs hours of a channel everybody else is also using.

Why internal flash cannot do it

The nRF52840 has 1 MB of internal flash and it is already spoken for. The SoftDevice sits at the bottom, the bootloader at the top, and what is left is the application window: origin 0x27000, length 0xB2000 — 729 088 B, 712 KiB (FLASH, leviculum-nrf/memory.x:84). Above it the boot record takes a page (BOOT, leviculum-nrf/memory.x:108, Codeberg #380) and the record store sixteen more (STORE, leviculum-nrf/memory.x:91, Codeberg #384), then the three persistence pages.

The image that lnflash wrote to a T114 on 2026-09-24 was 2 419 UF2 blocks of 256 payload bytes: 619 264 B, 605 KiB. A staged second copy beside the running one needs 1 238 528 B, 1 210 KiB. That does not fit in 712 KiB, and it does not fit even if the boot record and the record store are given up and the whole writable window above the SoftDevice is claimed: 0x27000 to 0xEA000 is 798 720 B, 780 KiB (Flashing an LNode, "What a UF2 is allowed to write") — still 440 KB short of two banks.

So there is no A/B bank internally, and the alternative — erase the running image and write the new one from a transfer held in RAM — is not an alternative at all. It fails on two counts: the board has 96 KiB of heap (HEAP_SIZE, leviculum-nrf/heap-budget/src/lib.rs:54) against a 605 KiB image, and a power cut during the write leaves a board with no image and no copy of one. Staging on flash the copier does not erase is not an optimisation; it is the property that makes the operation survivable.

Which boards are in, and on what evidence

T114 and RAK4631: out. Neither carries QSPI flash. That is measured, not read off a header — three units answered nothing to 05h, 9Fh, 90h or the datasheet reset while every pin followed our drive, and both board files state qspi_part: None (leviculum-nrf/src/boards/t114.rs:184, leviculum-nrf/src/boards/rak4631.rs:199). The EXTERNAL_FLASH_DEVICES lines in the vendor variant headers that once suggested otherwise sit under comments denying the part — RAK's own reads "No onboard flash" (leviculum-nrf/src/boards/rak4631.rs:152-153) — and leviculum-nrf/src/qspi.rs carries the whole account. For these two boards stage 1 is the entire answer, and that is why the two stages are separate documents rather than two halves of one.

SolarNode: conditional, and the condition is a boot line. The XIAO nRF52840 module's CONFIG.qspi_part is Some(&crate::qspi::P25Q16H) (leviculum-nrf/src/boards/solarnode.rs:402), 2 MB (P25Q16H, leviculum-nrf/src/qspi.rs:435). But that part number comes from Seeed's variant headers and the wiring from Seeed's schematic, and the schematic for the plain XIAO v1.1 draws the same footprint marked DNP — do not populate. So the firmware does not assert the part, it asks: identify_at_boot (leviculum-nrf/src/qspi.rs:463) reads the JEDEC id once at boot and prints [QSPI] JEDEC … state=ok or does not.

Our SolarNode prints that line, and the part has been driven. On 2026-09-24 the unit answered [QSPI] JEDEC id=85:60:15 … match=1 state=ok (/home/lew/rig-run/solarnode-dfu/dfu-test.log). On 2026-10-02 the destructive self-test (qspi-selftest, single-line bus at 32 MHz) ran over the whole 2 MB of the PUYA P25Q16H (/home/lew/rig-run/solarnode-qspi/qspi-selftest-20261002T134004Z.log): all 512 sectors erased clean in 8.8 s per pass, slowest sector 17 ms; 2 MB programmed in 13.4 s, 152 KiB/s with single-line page program; 2 MB read back in 0.55 s. The read-back is red: 11 445 mismatching bytes against the first pattern and 7 012 against the second (RESULT pass=0 reason=mismatch), while every erase verified all-0xFF.

The error is the 32 MHz read, not the part and not the program (Codeberg #435). On 2026-10-04 the self-test wrote each pattern at one clock and read it five times at each (/home/lew/rig-run/solarnode-qspi/qspi-selftest-20261004T211914Z.log): written at 32 MHz and read at 8 MHz, and written and read at 8 MHz, not one byte was wrong; read at 32 MHz the same data came back wrong in 1 644 555 and 1 743 635 of 2 097 152 bytes, 99.8 % of them different from one read to the next, on all eight bit positions, with 0-to-1 flips 130 to 170 times more frequent than 1-to-0. Data the reads cannot agree on is not data the cells hold, and the 2026-10-02 red was the same artefact. The part allows the clock: the P25Q16H datasheet gives 104 MHz for FAST_READ (0Bh), the opcode the firmware uses. What does not hold is the nRF52840's input sampling delay as embassy-nrf sets it, IFTIMING.RXDELAY = 2: 31.25 ns after the SCK edge.

The read sweep of 2026-10-05 measured the eye (/home/lew/rig-run/solarnode-qspi/qspi-selftest-20261004T230630Z.log, build 8c52c797). Pattern B, programmed at 8 MHz, read five times per chunk at the 8 MHz control and at 16 and 32 MHz under every RXDELAY; wrong bytes of 2 097 152:

"One bit late" is lost1 = gained1 = 20 979 770: the whole image shifted by one bit. RXDELAY 7 at 32 MHz is not in the capture, which closed after point 15. At 16 MHz the clean eye is three RXDELAY steps wide (0 to 31 ns), at 32 MHz one step (15.6 ns), and the default delay sits on the falling edge of the 32 MHz one: that is the whole of #435. The firmware therefore reads the part at 16 MHz, RXDELAY 1, the middle of the only clean run at least three steps wide, one constant (P25Q16H_BUS, leviculum-nrf/src/qspi.rs). 32 MHz at RXDELAY 1 is faster and has no margin on either side, and temperature and supply move a 15 ns eye by more than that. The self-test's SWEEPBEST line applies the same rule (MIN_CLEAN_RUN, leviculum-nrf/qspi-selftest/src/lib.rs) and names a faster clock with only a narrower eye as margin=too-narrow. At 16 MHz a full 2 MB read takes about 1.05 s instead of 0.55 s; for a 605 KiB staged image that is 0.3 s per verifying read.

The self-test's RESULT line judges the part, not the bus (Codeberg #413): it is green iff both 8 MHz read sets match the pattern, every erase verified all-0xFF, and SWEEPBEST found a wide window, and names the failing one as reason=program, not-erased or no-wide-window. The 32 MHz read sets stay in the plan, since they measure the default timing's eye, and their bytes are reported as read_side_mismatches=. The second sweep run of 2026-10-05 (/home/lew/rig-run/solarnode-qspi/qspi-selftest-20261005T005318Z.log) printed RESULT pass=0 reason=mismatch mismatches=3523349 on a part that held both patterns; under this rule it reads RESULT pass=1 reason=ok mismatches=0 read_side_mismatches=3523349 not_ff=0.

What this means for stage 2: staging plus golden fits the part with room to spare (below), and programming is not the constraint, since a 605 KiB image takes about 4 s to write and about 2.6 s to erase its 152 sectors. The constraint is the transfer, about 4.9 h per image per hop at our default PHY under the 10 % duty cycle (below). And no image is trusted from this flash until its read-back is green, and the read-back is green only at a bus timing the self-test has shown clean: a part that hands back other bytes than it was given turns every signature check over the staged copy into a coin toss, and a golden image read back wrong is a rollback to something nobody built.

The budget on a 2 MB part, and the other claimant

Staging plus golden is 1 238 528 B of 2 097 152 — 59 % of the part — leaving about 838 KiB. That is enough, and it is not so much that the region layout can be left implicit, because the same part is already wanted by something else: the record log, the message store of Codeberg #384, mounts over the whole part today (log_store, leviculum-nrf/src/qspi.rs:1054, read-only and formatting nothing, precisely because that decision had not been taken). Two claimants and one part means one region map, decided once, in one place — not two mounts that each believe they own sector 0. Whichever batch first writes to that part owns the map, and stage 2 must not be that batch by accident.

Erase granularity is 4 KiB (ERASE_SIZE, leviculum-nrf/src/qspi.rs), so staging an image is 152 sector erases. Against the part's rated endurance that is free; it is the pattern that matters, not the count — a staging region rewritten in place from sector 0 every time wears one end of the part and nothing else, which is the same argument the record log already makes for itself (An LXMF propagation node on a board).

The image arrives as a Resource and is never held

The image is a Reticulum Resource on a Link to the board's control destination — stock Reticulum, the same mechanism rncp and lncp use. The board writes each part to the staging region as it arrives and holds none of the image in RAM.

That is not a preference. The board has 96 KiB of heap and the cost of holding a copy of anything is measured: a 5 427 B propagation response held 51 662 B live before Codeberg #384 B1 and 29 842 B after it, and before either, a board died on a 5 446 B allocation between serving a request and answering it — PN_GET … bytes=5376 as the last line of one boot and PANIC_PMRT … "memory allocation of 5446 bytes failed" on the next (leviculum-nrf/heap-budget/src/lib.rs:177-202, pinned by leviculum-std/tests/mvr/pn_serve_peak_outgrows_the_board_heap.rs). A path that holds one whole copy of 5 KB killed a board; 605 KB is not a question of tuning.

Two consequences follow and both are design constraints, not details:

• The transfer must be resumable across a reboot. Five hours of channel time (below) is far longer than the interval at which a field board reboots for its own reasons. The staged region and its header are the resume state; a transfer that starts from zero after every reset never completes on a board that reboots at all.
• The staging region is untrusted until the whole image verifies. Partial contents are exactly what an interrupted transfer leaves, and they must be indistinguishable from garbage to everything downstream.

Header and signature: refuse before the first erase

Ahead of the staged copy sits a header, and it is checked in full before the copier touches the application window:

ed25519_dalek is already a dependency of the core and builds for the firmware target (leviculum-core/src/identity.rs:63-65), so verification costs a public key compiled into the image and one pass over the staged bytes. That pass is cheap against the five hours the transfer took.

Why a signature, when stage 1's allow list already says who may command. The allow list authenticates a peer on a live link. The staged image outlives that link, the reboot, and possibly the operator's key: what the copier reads at 3 a.m. after a power cut has no link behind it and no peer to ask. The allow list says who may command; the signature says what may run. Neither substitutes for the other.

And the order is load-bearing. A signature checked after the erase is not a check — by then the board has nothing to fall back to but the golden image, which turns a refusable mistake into a rollback. Verify, then erase.

The copier, and what it must never depend on

One routine, running from RAM with the SoftDevice disabled: erase 0x27000 for the image's length, write from the staging region, verify, mark done, reset.

It must not depend on:

• the image it is erasing — no call into it, no vector table in it, no panic handler in it, no string in it;
• the SoftDevice, which owns flash timing while it is enabled and which the boot record already steps around by writing before Softdevice::enable (leviculum-nrf/src/boot_count.rs);
• the heap, USB, BLE, the radio, the log path — anything that might route through a region being erased or an allocator that might fail;
• interrupts it did not itself arm;
• the transfer that produced the staged copy, which finished hours or reboots ago.

It must be idempotent under a power cut, because that is the failure it exists to survive: a cut halfway through leaves a partly written application window, and the only correct behaviour on the next boot is to copy again from the same source. That means "a copy is in progress" is itself a flash record, written before the first erase, in a page the copier never erases — the boot record's neighbourhood (BOOT, leviculum-nrf/memory.x:108) is the shape, for the same reason the boot record chose it: it must survive a power loss, which is the case it exists for.

This is the one piece of code in the system whose bug is an unrecoverable board in a place nobody can reach. It should be the smallest, dullest, most heavily host-tested thing we own — the same disposition leviculum_boot_count took, where a host test can cut the power at every word boundary (leviculum-nrf/src/boot_count.rs).

Golden image and the rollback trigger

The golden image is the last one that came back healthy, kept on the same part. The trigger for restoring it is the boot counter that landed on 2026-09-24 (record_at_boot, leviculum-nrf/src/boot_count.rs:122, Codeberg #380): one 16-byte record per boot with the raw RESETREAS and whether retained RAM survived, appended to the BOOT page, one erase per 256 boots. It exists because a Pocket V2 restarted twice on a field walk and every boot read reset_reason=0x00000000 with prev_magic=absent — a power loss takes retained RAM with it, and a rollback trigger that lives in RAM is a rollback trigger that a sagging battery switches off.

The rule's shape: the copier marks the new image unproven; the application clears the mark once it reaches a defined healthy point; N consecutive boots with the mark still set restores the golden image.

Two parts of that are decisions this page deliberately does not take, and naming them is more useful than guessing them:

• What "healthy" means. It must be later than "reached main" — a board that boots and cannot bring up its radio is precisely the failure that needs rolling back, and it reaches main every time. It must not be "heard a peer", or a quiet mesh looks like a broken image and the board rolls back a perfectly good update because nobody was talking.
• What N is. Too small and one unlucky brown-out undoes a good update; too large and a boot-looping board spends a day looping before it heals.

The counter is also the only evidence anybody will ever get from a board in a hedge: BOOT_COUNT n=… reset_reason=… retained=… since_erase=…, read on the next visit or over the mesh, says what the board did while nobody was watching.

What it costs the channel, in hours

Measured on 2026-09-24, lora_lncp_push_to_python_50kb on the rig: five 50 KiB pushes at 869.525 MHz, SF7, BW 62.5 kHz, CR 4:5, 212–333 s of wall clock each with the airtime lock deliberately switched off for the cell, and about 165 s of transmitter airtime each — 109 parts of 491 B at roughly 1.50 s of airtime apiece.

Scaling to the 619 264 B image is a factor of 12.1:

869.463 MHz — our default carrier — sits in the 869.4–869.65 MHz sub-band, whose lawful duty cycle is 10 % (etsi_eu868_duty_cycle, leviculum-core/src/rnode.rs:1525; Regulatory airtime). Ten percent of an hour is 360 s of airtime, so 1 750–2 000 s of airtime is five hours of wall clock however fast the modem is. The PHY does not change the answer; the regulation does.

And it is worse than "five hours", because that budget is not spare capacity:

• The sending node spends its entire lawful hour on the image, for five hours. It forwards nobody's traffic while it does. A transport node updating a neighbour stops being a transport node for an afternoon.
• Every relay on the path pays it again, once per hop, and pays it serially. A two-hop image is ten hours of two nodes' budgets.
• Everyone else on the channel pays too. The band is occupied ten percent of the time, continuously, for hours; every other node's pre-transmit window finds a busy channel more often and backs off (The randomised pre-transmit window).

Compression halves it at best. The measurement above is deliberately incompressible — /dev/urandom, so that 50 KiB of payload is 50 KiB on the air and the durations compare — while a real ARM firmware image does compress, though less than a halving: xz -9e takes the built image from 619 124 B to 379 608 B, 61 %, so about 4.9 h per hop becomes about 3 h. That is also not small enough for an internal A/B on the boards without external flash. It changes the scheduling of the operation and not its nature.

The arithmetic forces the conclusion, and the conclusion is the point of the page: stage 2 is for the board nobody can reach at all. An update over the mesh is an event the mesh is told about in advance, planned around, and done once. A fleet update over LoRa is not a thing that happens. Wherever somebody can get within Bluetooth range, stage 1 does the same job for the cost of one control frame.

Python-RNS compatibility: untouched

Nothing here is on the wire between stacks. The transfer is a Resource on a Link to a destination resolved the ordinary way, which is stock Reticulum in both directions — a Python peer could be the sender without knowing what it is sending. The header, the signature, the staging layout, the copier and the rollback rule are all behind our own control destination, visible to nothing but us, in the same sense the propagation node's control destination is (Python-RNS compatibility). No new packet type, no announce semantics, no change to any field a Python node reads.

Python-RNS Compatibility

Leviculum is built to live in the same mesh as Python Reticulum (rnsd) and to be a drop-in replacement for the daemon and its tooling. Compatibility is pursued at two distinct levels, and one thing that is not pursued at all.

Level 1: wire and semantic compatibility

The protocol the two stacks speak must be identical on the air. The exact bytes of identities, destinations, announces, packets, and links are fixed by the Reticulum specification; the message format layered on top is fixed by the LXMF specification. Leviculum implements those formats so that a Python peer cannot tell a Leviculum neighbour from another Python node.

Semantic compatibility goes beyond byte layout: behaviours a Python peer expects from a neighbour — answering path requests, rebroadcast decisions, link lifecycle, ratchet handling — must still be delivered. Where the precise expected behaviour matters and is subtle, it is captured as a source-of-truth reference; the broadcast path is documented in Broadcast: Python-RNS parity reference, which records what Python does for every broadcast mechanism so the Rust core can match it.

Semantic compatibility is decided field by field: what a peer decides from a value we generate is part of the contract, even when the byte layout is right. The audit method and testing rule for that are in Wire Field Semantics.

It cuts both ways. The reference's accept set is as much of the contract as its output set, and it is wider — Python's decoder takes forms Python's encoder never emits. A mesh has more than two implementations in it (reticulum-kt, microReticulum, hand-rolled senders), and any of them may pick a legal encoding Python happens not to use. Testing only against rnsd cannot see this: it never produces the form we refuse. Being stricter than the reference on the read path is a compatibility defect of the same standing as emitting a wrong value, and it fails silently — see Wire Field Semantics.

Level 2: drop-in daemon and tooling

lnsd shares two interfaces with Python's rnsd:

• The shared-instance IPC socket. A running daemon exposes a local control/data channel that client tools connect to. Leviculum speaks the same protocol, so Python's rnstatus, rnpath, rnprobe, and rncp drive a running lnsd without modification, and the Leviculum tools lnstest and lncp drive a running rnsd just the same. The RPC control channel that backs rnstatus/rnpath/ rnprobe is implemented in leviculum-std/src/rpc/ (it speaks Python's multiprocessing.connection framing with pickle payloads, see rpc/connection.rs and rpc/pickle.rs). A client on that socket — lxmf-node, lnmsg, lnomad, every ln* tool — keeps its own known-destination table rather than delegating it, so a peer it has used stays recallable for KNOWN_DEST_USED_LINGER_MS (leviculum-core/src/constants.rs:176) after the daemon stops offering a path to it, instead of being forgotten on the next sweep (Codeberg #389).
• The config-file format. lnsd parses the same INI-style config that rnsd uses (leviculum-std/src/config.rs, leviculum-std/src/ini_config.rs). Even keys Leviculum does not act on are parsed for compatibility — for example shared_instance_type and shared_instance_socket are read and honoured per RNS 1.3.x semantics so an existing rnsd config works unchanged (leviculum-std/src/config.rs:76-82).

This drop-in property is a deliberate design goal, not an accident. It is also what makes honest A/B testing possible: the test harness points the same client binary (e.g. lnstest selftest) at either daemon, never a parallel per-stack driver. A parallel driver would smuggle configuration differences into what claims to be a stack comparison.

What is explicitly not a goal: internal parity

Compatibility is not the same as parity.

• Compatibility — our stacks interoperate at the wire and semantic level.
• Parity — our internals mirror Python's (same algorithms, same retry timings, same state-machine structure).

Leviculum needs the first, not the second. The historical parity documents under docs/src/architecture-*-python-parity.md are reference material for getting behaviour right, not commitments to maintain identical internals.

The deviation rule

A deviation from Python-RNS's implementation is acceptable if and only if all three of the following hold:

1. Wire-format compatibility is preserved.
2. Semantic compatibility is preserved (behaviours Python peers expect from a neighbour are still delivered).
3. The deviation measurably improves robustness or mesh delivery.

"Because Python does it differently" is not, on its own, an objection; only "this breaks wire or semantic compatibility" is. The interface-isolation design — interfaces applying their own jitter, CSMA, and airtime budgeting — is a deliberate deviation that satisfies this rule.

A deviation that is not written down is indistinguishable from a bug. Each one is pinned here with the reference line it departs from, so the next reader can check the claim instead of re-deriving it.

Pinned deviation: a pathless never-used destination does not linger

The reference's known-destination sweep spares a pathless entry on three grounds: an application pinned it, it was used within DESTINATION_TIMEOUT * 1.25, or it was never used but announced within UNUSED_DESTINATION_LINGER — 6 minutes (reference/Reticulum/RNS/Identity.py:349-352, the two timeouts at Transport.py:91-92). We implement the first two and not the third (leviculum-core/src/memory_storage.rs:1226): our announce cache stores the raw announce, not the moment we heard it, so there is no age to compare against. The third arm only ever protects a destination nothing has asked about, so dropping it a few minutes early costs a path request rather than a fact, and clause 3 of the rule is satisfied by the smaller resident set. EmbeddedStorage goes one further and implements only the first (leviculum-core/src/embedded_storage.rs:1103), because a board tracks no use-state at all.

Pinned deviation: ingress-control default on dial-out links

The reference gives every interface ingress_control = True (Interface.py:112), overridable per interface by the config key of the same name (Reticulum.py:768-769, applied at Reticulum.py:910). Leviculum defaults it off on dial-out point-to-point links — TCPClientInterface, BackboneClientInterface, UDPInterface, and an I2PInterface without connectable — and leaves it on everywhere else, including every listener (ingress_control_default_for_type, leviculum-std/src/config.rs:947).

Against the rule: the flag decides only whether we hold incoming announces, so no wire byte and no behaviour a peer observes changes (1 and 2). It gains us the announces the limiter would otherwise hold silently on a link carrying one known peer's startup burst — the mechanism behind the Codeberg #44 flake, on our receive side (3). An operator who wants the reference behaviour writes ingress_control = yes on the interface.

The default is a role distinction, not a medium one: an interface that accepts connections from arbitrary unknown peers is exactly the announce-storm surface the limiter exists for, so a listener keeps the reference default. What a listener resolves is inherited by every connection it accepts, as in the reference (TCPInterface.py:582, I2PInterface.py:951, BackboneInterface.py:409). Shared-instance IPC clients are never ingress-limited on either stack — the reference hard-wires should_ingress_limit to False for them (LocalInterface.py:137-138) — so that is not a deviation.

Pinned deviation: an absent txpower is the board maximum

The reference resolves an omitted txpower key to 0 dBm (RNodeInterface.py:153: int(c["txpower"]) if "txpower" in c else 0). Leviculum resolves it to the board maximum, capped by the lawful e.r.p. limit for the configured frequency: 22 dBm — the ceiling of the SX1262 high-power PA and the highest value an RNode-firmware board takes before clamping — or the sub-band's limit from ERC 70-03, whichever is lower (rnode::resolve_tx_power and DEFAULT_TX_POWER_DBM, leviculum-core/src/rnode.rs:742, capped by lawful_erp_dbm, applied in both interface builders and in the SerialInterface LNode path). The standalone LNode firmware's compiled profile carries the uncapped board maximum (RadioConfig::eu_medium, leviculum-nrf/src/lora.rs:414-460), which is the capped resolution's own result at that profile's 869.463 MHz.

Against the rule: TX power is a local modem setting. It is never on the wire, and no peer — Python or otherwise — learns or expects anything about a neighbour's transmit power, so (1) and (2) are untouched. What it gains (3) is the whole failure mode: 0 dBm is 1 mW, and a 1 mW node has no symptom at the node. It boots, configures, transmits, logs nothing unusual, and is simply not heard. 22 dBm is 158 mW. An operator who wants 0 dBm writes txpower = 0 and gets 0 — the resolution keeps None and Some(0) distinct, the same way an explicit airtime_limit_long = 0 beats the derived lawful default.

Because the request is not preceded by a capability probe, a board whose maximum is lower answers by clamping and echoing the clamped value (RNode_Firmware/RNode_Firmware.ino:861-879 — 17 dBm on an SX127x, PA_MAX_OUTPUT on an SX1262 with an external PA). Confirmation is otherwise an exact match on both stacks (ours at leviculum-std/src/interfaces/rnode.rs:1874, the reference at RNodeInterface.py:677), so the derived default — and only the derived default — accepts a confirmation below what it asked for, logs the board's ceiling, and runs. An explicitly configured power keeps the strict check: a board that cannot deliver a value the operator chose must say so. A confirmation above the request is a mismatch either way.

Regulatory note (EU 863-870 MHz). 27 dBm e.r.p. is permitted only in 869.4-869.65 MHz (ERC Recommendation 70-03, Annex 1, sub-band h1.7); every other listed European sub-band allows at most 25 mW e.r.p. = 14 dBm. That is why the derived default is capped by frequency (rnode::lawful_erp_dbm): a node on a community frequency like 867.2 MHz (Rotterdam/Duffel), 867.5 (UK), 868.0 (Bern) or 868.2 (Madrid) resolves an absent txpower to 14 dBm, not 22. An explicit txpower wins even above the cap — the operator may hold a licence or sit in another jurisdiction — and the excess is logged. Inside 869.4-869.65 MHz, 22 dBm conducted stays under the 500 mW limit up to roughly 7 dBi of antenna gain (22 + 7 - 2.15 dBd ≈ 26.9 dBm e.r.p.); above that the operator has to set txpower down explicitly, and that residual is documentation, not a runtime warning: the stack does not know what antenna is attached, and a warning it cannot condition on anything is a warning operators learn to ignore. A carrier overlapping one of the narrowband alarm bands between the wideband sub-bands is named in a warning at interface build (rnode::erp_band_gap) and then transmitted: a 125 kHz signal cannot meet their ≤ 25 kHz channel spacing on any power, but the judgement is the operator's, not ours — see No radio configuration is refused.

Not a deviation: a class constant is not the value on the wire

An interface's HW_MTU in the reference is a class attribute that looks like the answer and is not it. TCPInterface.HW_MTU = 262144 (TCPInterface.py:42) is only what the interface carries into interface_post_init (Reticulum.py:879), which immediately runs optimise_mtu (Interface.py:198) over the interface bitrate for every interface with AUTOCONFIGURE_MTU set — TCP among them. With TCPServerInterface.BITRATE_GUESS = 10 Mbps (TCPInterface.py:453) the derivation lands on 8192 up to and including Reticulum 1.5.0, and on 16384 from 1.5.2 on, where the thresholds became >=. The class value never reaches the wire on either.

We read the class constant instead of the derivation until Codeberg #355. The measurement that closed it drove the same two Python clients, attached to the shared instances of two relays, over one TCP hop between the relays, swapping only which daemon the relays were:

So the constant acted on the wire: a Python client on our shared instance negotiated a link MTU 32x larger than the same client gets from rnsd, and the frames actually crossed the TCP hop at that size. A Python peer on the path clamps a too-large signalled MTU down to its own on the hop it carries — the mixed rows of the same measurement settle on 8192 — so nothing broke as long as one was there to do it. That conditional is the semantic-compatibility risk: a Reticulum 1.5.x peer's receive path rejects a frame longer than its own HW_MTU, so any route change onto such a peer silently drops the traffic. Speed is Priority 2 and does not buy that.

The lesson generalises past MTU: before adopting a reference class attribute as a value we signal, check whether the reference derives it at interface post-init, and whether it signals it at all. UDPInterface was the sibling case, closed by Codeberg #357. It sets self.HW_MTU = 1064 (UDPInterface.py:74) and leaves the base class's AUTOCONFIGURE_MTU = False and FIXED_MTU = False (Interface.py:93-94) alone, and every gate that puts an MTU on the wire reads those flags rather than the value:

• the initiator asks Transport.next_hop_interface_hw_mtu, which returns None for such an interface (Transport.py:2682-2683), so it signals RNS.Reticulum.MTU (Link.py:310-314);
• a relay forwarding onto such a next hop truncates the link request by LINK_MTU_SIZE (Transport.py:1599-1602);
• a receiver clamps against RNS.Reticulum.MTU rather than HW_MTU (Transport.py:2101-2104).

All three land on 500. 1064 is what the interface's own read path accepts off the wire, never what it negotiates. We signalled it until #357, which is why our own interop suite carried two UDP numbers: 500 for every link with a Python end on it and 1064 between two Rust ends. HW_MTU in InterfaceInfo now means the value the interface signals, so a UDP interface carries None there and reports nothing under the mtu stats key — a key that postdates our pinned 1.3.5 reference, where Reticulum 1.5.x reports 1064.

The reference gates several more interfaces off the same way — PipeInterface, KISSInterface, AX25KISSInterface, SerialInterface, I2PInterface, RNodeInterface and RNodeMultiInterface all set an instance HW_MTU without either flag — and we still signal ours on each. Those are not #357: LoRa in particular has a Priority-1 argument for keeping the link inside one 508-byte frame that the UDP case has no counterpart to, so each wants its own measurement.

Same-interface relay on shared media

Path-directed transport forwarding transmits on the next-hop interface even when it equals the receiving interface. Same-interface relay is NOT suppressed — it is how multi-hop works on one shared medium. In the fundamental single-channel LoRa topology A-B-C (A↔B and B↔C in range, A↮C), B's only route to A is back out of the very interface C's packet arrived on; a relay that declines that hop kills every data flow the announce flood just made possible.

The reference behaves this way on every forwarding path:

• Path-table data and link requests: the outbound interface IS the receiving-side path interface — outbound_interface (Transport.py:1583) — and Transport.transmit (Transport.py:1635) sends there with no receiving-interface guard.
• Link-table data: when next-hop and receiving interface are equal, "direction doesn't matter, and we simply repeat the packet" (Transport.py:1651).
• Proofs: an LRPROOF goes back out of the interface the link request arrived on (Transport.py:2197), a data proof out of the reverse table's receiving interface (Transport.py:2263) — on one shared channel, each is the interface the proof itself arrived on.

Loop-freedom never came from interface suppression. It comes from transport_id addressing (only the addressed relay processes a Type2 transport packet), the hop-count limit, and packet-hash dedup — has_packet_hash (leviculum-core/src/transport.rs:3956) drops a repeated copy, add_packet_hash (leviculum-core/src/transport.rs:4010) records it.

The forwarding decision lives in the media-agnostic core (forward_on_interface_from, leviculum-core/src/transport.rs:8677). Whether the relayed echo needs TX spacing on a half-duplex channel is the interface's business — see Interface Isolation.

Pinned by test_pkt_journey_same_interface_relay_forward (one relay, one interface, forward asserted with iface_out == iface_in) and the three-node test_shared_medium_multihop_data_forward (announce flood A→C via B, then data C→A delivered through B's single shared interface), both in leviculum-core/src/transport.rs.

Client Tools

Leviculum ships command-line tools next to the daemon, and every tool we will ever ship is governed by the same small set of rules. This page records them for whoever adds the next tool: the counterpart rule, the drop-in contract, the explicit permission to exceed the reference, the case where a tool with no Python equivalent is the right deliverable, the one situation in which our own tool must not be used, and the marking rule for tools that can forge traffic.

The daemon-level half of this story — shared-instance IPC and config compatibility, and why drop-in is a design goal rather than an accident — is in Python-RNS Compatibility. This page extends the same property from the daemon to the clients.

A counterpart for every reference tool

The reference stack ships a family of utilities under reference/Reticulum/RNS/Utilities/. The rule is one ln* counterpart per reference tool. The honest current state, as of 2026-09:

The vendored 1.3.5 tree also carries rngit as a utility subpackage; the counterpart rule covers it the same way, and it is likewise missing and unfiled. "Not yet filed" rows are gaps in the issue tracker, not decisions to skip the tool — file the issue when work on one begins.

Alongside the counterparts we ship tools with no reference equivalent: lnstest (test and diagnostics driver, see below), lnomad (NomadNet browser; its reference counterpart is the NomadNet application rather than an RNS utility), and lblogd (blog daemon). The counterpart rule does not restrict these; the drop-in rule below does not apply to them because there is no reference surface to be compatible with.

Drop-in first

With the reference tool's arguments, our tool behaves like the reference tool. Same flags mean the same thing, same exit codes, and the output is something a script written for the Python tool can still parse. This is the daemon-level drop-in property extended to the clients, and it is what lets a comparison harness point one driver at either stack.

The worked example is lnstatus: the renderer consumes the same interface_stats dict a Python rnsd exposes, and feeding an identical stats dict into lnstatus and rnstatus yields byte-identical output (lnstatus_render.rs:1-15, pinned by the 2×2 parity matrix, which drives both clients against both daemons after byte-identical controlled traffic, status_parity_tests.rs:1-30). lnstatus mirrors the reference flag surface — -a, -A, -P, -l, -j/--json, -m/--monitor, -s/--sort, the name filter — with the reference meanings, because those flags and formats are the compatible surface a user's muscle memory and a user's scripts depend on.

Drop-in is judged against the vendored reference (reference/Reticulum), which is the same source of truth the protocol work measures against. When the reference tool's own output changes between versions, the bridge parsers in Periculum absorb it — compatibility of meaning, not a frozen byte format, per Wire Field Semantics.

Drop-in is about the answer, not just the query

A client tool asks a daemon a question. Drop-in means the answer describes the same world, not merely that the query succeeded — and an answer about a different world is the hardest kind of difference to notice, because nothing fails.

Codeberg #177 was exactly that. rnstatus against rnsd listed three interfaces; against lnsd it listed none, and the query returned cleanly both times. The cause was structural: our interface_stats was assembled from Transport's routing map — the interfaces the core can send packets on — while a Python rnsd reports RNS.Transport.interfaces, everything Reticulum runs (Reticulum.py:1334). Listeners carry no packets, so they were in no collection at all on our side, and their absence was the symptom. The reporting inventory now lives in the driver (leviculum-std/src/interfaces/inventory.rs) and interface_stats reports the union: transport's routable interfaces plus the listeners the daemon runs. Transport stays free of listener rows, which it would otherwise try to send on.

Codeberg #190 was the same shape one field down. A radio row's bitrate answered with the per-medium BITRATE_GUESS — 10 Mbit/s, TCP's — because the key was filled only from a configured bitrate, and a radio configures none. Python fills it from the interface itself, which for an RNode is the on-air rate derived from the radio settings (RNodeInterface.updateBitrate, RNodeInterface.py:693-696). The precedence is now Python's, in Python's order: a configured bitrate first (if configured_bitrate: interface.bitrate = configured_bitrate, Reticulum.py:887), else the interface's own rate for its medium, else the guess. Nothing failed while it was wrong; a client asking how fast the air is simply got an answer about a different medium.

What appears, and under what name

The name is the interface's identity to a script, so each row reproduces the reference __str__ exactly:

<section> is the config section name ([[My TCP Server]]), which is Python's interface.name; it is carried on InterfaceConfig::name because flattening the parsed config used to drop it. A spawned row also carries parent_interface_name / parent_interface_hash pointing at its listener (Reticulum.py:1342-1344), and hash is the full 32-byte Identity.full_hash(str(interface)) on both stacks, so a script may key interfaces by hash across daemons. A listener reports clients (its live spawned count) and its children's byte totals, including those of children that have since disconnected — the reference gets the latter for free by incrementing the parent counter alongside the child's (TCPInterface.py:306-308).

Pinned deviations

Each is a decision, not an accident, and each has a test that fails if it drifts:

• A listener's frequency fields are the sum of its live children's, where the reference keeps a deque on the listener itself (TCPInterface.py:634-644). Identical at rest (both read exactly 0, which is what the frozen comparisons assert) and equal in aggregate under load; they can differ while a child that contributed samples has already disconnected.
• Interfaces other than the four rows above still report our internal name (tcp_client_0, rnode_0, auto/eth0/…) rather than the reference's TCPInterface[<section>/<host>:<port>] family. A script that keys on those names still sees an unfamiliar identity; the drop-in gap is narrowed, not closed.
• Config interfaces are ordered by section name, not config-file order: the parsed config is a map keyed by section name, so file order is not recoverable. Deterministic run to run, which HashMap iteration was not.
• Extra and missing keys: ours adds announce_queue and peers, the reference adds autoconnect_source. Pinned exactly by assert_daemon_stats_parity.
• tx_jitter_max (Codeberg #190): the ceiling, in seconds, of the randomised pre-TX delay an interface draws against before a frame goes on the air. The reference has no equivalent — Python's RNodeInterface leaves medium access to the RNode firmware's CSMA and holds no such attribute, so nothing in get_interface_stats (Reticulum.py:1326-1470) reports it. Purely additive: rnstatus reads every field by name (ifstat["name"], rnstatus.py:391; if "<key>" in ifstat for the optional ones) and never enumerates an interface dict, so an unknown key is not read. Emitted only where the concept applies, the way Python gates airtime_short and friends on hasattr, which is why it does not appear in the TCP-only rows the parity matrix compares.
• An IPC client's short_name index mirrors the reference's live-client count at accept time (LocalInterface.py:441/355), so the labels of two daemons agree only when their clients connected and left in the same order.

Exceeding is allowed and wanted

Additive flags and richer output are welcome. The constraint is only that the reference-compatible surface stays reference-compatible: an extra flag must not change what an existing flag does, and extra output must not break what a Python-tool script would parse.

Current examples: lnstatus --instance_name (leviculum-cli/src/lnstatus.rs) selects a shared instance by name where the reference tool only reads it from the config file, and lnstatus --tables (the second half of Codeberg #174) exposes internal tables rnstatus cannot show at all. Both are additive: run lnstatus with exactly rnstatus's arguments and you get rnstatus's behaviour.

The shape an additive dump takes

--tables is the worked example, and four of its decisions generalise to the next one.

Additive key, not an envelope. The tables go into the -j object under one new key rather than wrapping it, so the stats dict stays the top-level object. Everything that parses lnstatus -j today — Periculum's parse_status scans for the line whose object carries interfaces — keeps working untouched, and -j without the flag is what it always was. Wrapping would have been tidier and would have broken every existing reader.

Reference names where the reference has one, its own vocabulary where it does not. Python serves exactly one of these tables over RPC (get_path_table, Reticulum.py:1516-1538), so those six keys and their units are taken verbatim and our one addition sits beside them. The other tables Python holds but never exposes; it names their fields only by list index (IDX_RT_*, IDX_LT_*, IDX_AT_*, IDX_TT_*, Transport.py:3556-3586), so the string keys are ours, spelled after those constants. The additive keys are safe against a Python reader for the same reason tx_jitter_max is: every Python consumer of an RPC response reads it by name and none enumerates it.

Naming collides once, and it is worth knowing about: link_table in the dump is Transport.link_table, the links this node relays. The pre-existing link_table RPC (lnstest diag) is the links this node terminates, and appears in the dump as local_links. The reference name won the contested word because the reference has a table by that name; the inventory the reference has no table for at all took the qualified one.

Absent is not empty. A daemon that implements the query answers with the key present and its tables possibly empty. A daemon that does not — a Python rnsd, or an lnsd from before the flag — makes the client omit the key, print why on stderr, and exit 0. Presence therefore distinguishes "cannot answer" from "nothing there". Nulling the key, or defaulting it to empty lists, would have made every assertion about an empty table pass silently against a daemon that cannot answer it — the read-side tolerance question of Codeberg #183, one layer up. Python's rpc_loop matches no arm for an unknown command and falls through to conn.close() (Reticulum.py:1213-1260), so the absence surfaces as a fast transport error rather than a hang; that is pinned against a real rnsd in reverse_rpc_interop_tests.

The expensive half is opt-in, and absence covers it too. Sizes and rows are different questions with costs three orders of magnitude apart: a size is a len(), a row makes the daemon build a dictionary with a string key per field, and a field node holds 43 000 of them in one table. The dump therefore always answers the cheap question and answers the expensive one only when a request names the table (--table-rows, Codeberg #028) — so the common poll, "how full is it", stops moving the daemon's resident set by tens of megabytes. This is where the rule above earns its second use: a table whose rows were not asked for is absent, because the one thing it must not be is present and empty, which already means something else. The response says in rows_for which tables it carries rows for, so the reader never has to infer it from which keys turned up.

One honesty note, because it is easy to get wrong in the other direction: -j/--json, -m/--monitor and the announce/path-request/ link statistics flags are not exceedances — the reference rnstatus has all of them (rnstatus.py:685-706), and ours mirror them under the drop-in rule. Claiming reference-mirrored features as our extensions would misstate where the compatible surface ends; check the reference before calling a flag additive.

New tools where testing gains from them

lnstest exists because Periculum needed a driver the Python tool set does not offer — deterministic selftest phases (delivery, ratchet, link) with machine-parseable summary lines (leviculum-cli/src/lnstest.rs:1-4). That is the precedent: when a test cannot be written because no tool can express it, the tool is the deliverable.

The currently open examples — not a closed list — are:

• Codeberg #175: wire-level tools, a packet injector and a decoder with no Python equivalent.
• Codeberg #176: a structured event tap, so Periculum can assert on events instead of scraping container logs.

A new tool of this kind has no reference surface, so the drop-in rule does not bind it; the evidence rules do. In particular a test tool's output is a diagnostic indicator: it must measure the production path and be observed in both states before its green is believed.

The rule a comparison must not break

A stack comparison drives the same client against both daemons. That is the whole point of the drop-in property, and it cuts both ways: our own client may not replace the reference tool in the very tests that measure against the reference. Substituting "our better tool" on one side smuggles config, cadence and timeout differences into a result that claims to be about the stacks — the parallel-driver failure described in Evidence and Honesty.

So: lnstest selftest pointed at either daemon is a valid A/B. lnstatus against lnsd compared with rnstatus against rnsd is not a stack comparison — it varies two things at once. The 2×2 parity matrix (status_parity_tests.rs:5-30) is the shape that untangles this: each client against each daemon, so client-render parity and daemon-stats parity are separated instead of conflated. This is the one place where "use our better tool" is wrong.

A tool that can forge is marked as such

Anything that emits crafted frames — the planned packet injector of Codeberg #175 first among them — refuses to run without an explicit flag acknowledging that it forges traffic, and names itself in its output so a capture containing forged frames is attributable. A crafted frame in a mesh is indistinguishable from a real one by design; the honesty has to live in the tool. No shipped tool forges today; this rule binds the first one that does.

Adding the next tool: the checklist

1. Name and scope. ln* counterpart of one reference tool, or a new testing tool per the precedent above. Check the tracker first (#173 covers probe and path query).
2. Drop-in surface. Implement the reference tool's flags with the reference tool's meanings and exit codes. Divergence from the reference's internals is fine under the deviation rule; divergence of the compatible surface is not.
3. Parity evidence. Pin the drop-in claim with a test that could fail — the 2×2 matrix of status_parity_tests.rs is the model.
4. Periculum wiring. Add a client manifest (periculum/periculum/adapters/clients/*.toml) and an output parser in the bridge (periculum/periculum/src/bridge.rs), so scenarios can drive the tool and assert on its output.
5. Docs. Guide page, man page, and both in docs/src/SUMMARY.md.
6. Forgery marking, if the tool can emit crafted frames.

See also

• Python-RNS Compatibility — the daemon-level drop-in property this page extends, and the deviation rule.
• Evidence and Honesty in Testing — the A/B discipline the comparison rule enforces.
• Wire Field Semantics — compatibility as meaning, not bytes.

Cryptographic Identity and Forward Secrecy

Every node and every endpoint in a Reticulum network is identified by cryptography, not by an address handed out by infrastructure. This page explains the conceptual model. For the exact byte layouts, defer to the Reticulum specification (its Identity, Destination, and Announce sections).

Identities are dual keypairs

A Reticulum identity holds two keypairs, used for two different jobs (leviculum-core/src/identity.rs:55):

• X25519 — for key agreement (ECDH). This is how two parties derive a shared secret to encrypt traffic to each other.
• Ed25519 — for digital signatures. This is how a node proves an announce or a packet genuinely came from the holder of the identity.

An identity may be full (it holds the private halves and can decrypt and sign) or public-only (it holds just the public keys, learned from someone else's announce, and can only encrypt and verify). In the source this is the difference between the Option-wrapped private fields and the always-present public fields (leviculum-core/src/identity.rs:58).

Destinations are derived addresses

You do not pick a Reticulum address; you derive one. A Destination is an addressable endpoint whose 16-byte hash is computed from an application name, a set of aspects, and (for most types) an identity (leviculum-core/src/destination.rs:1). Because the address is a hash of stable inputs, it is reproducible and self-authenticating: anyone who knows the inputs computes the same address, and the identity bound into it proves ownership.

A destination also carries a type (SINGLE, GROUP, PLAIN, LINK) that selects its encryption behaviour, and a direction (IN, OUT) that selects whether it can receive or send (leviculum-core/src/destination.rs:6-7).

Announces carry the public keys

A node makes itself reachable by broadcasting an announce: a signed notification that carries the destination's public keys out into the mesh. Peers that receive it learn the destination's address and the keys needed to encrypt to it, and Transport learns a path back. The exact announce wire format is specified in the Reticulum spec.

Ratchets: forward secrecy without a link

End-to-end encryption protects traffic in flight, but if a long-lived identity key is ever compromised, an attacker who recorded past ciphertext could decrypt it. Ratchets close that window for packets sent to SINGLE destinations without first establishing a Link (leviculum-core/src/ratchet.rs:1).

The mechanism, conceptually:

1. A destination enables ratchets and generates an initial X25519 keypair.
2. It includes the current ratchet public key in its announces.
3. Senders encrypt to the ratchet public key, not the long-term identity key.
4. The destination rotates its ratchet keypair periodically (default ~30 minutes).
5. Old ratchets are retained for a while so late-arriving packets still decrypt (default 512 retained), then discarded.

Because the rotating key is short-lived and the private half is thrown away after rotation, compromising the long-term identity does not expose traffic encrypted to expired ratchets. That is forward secrecy.

Persisting ratchet keys across restarts is the job of the Storage trait (the ratchets/ and ratchetkeys/ collections, see Architecture). Links — the other path to forward secrecy, via an ephemeral session handshake — are a separate mechanism; see the Reticulum specification.

Where to read the exact bytes

This page stays conceptual on purpose. The authoritative definitions of identity serialisation, destination hashing, announce structure, and ratchet encoding are in the Reticulum specification. The Rust types above (identity.rs, destination.rs, ratchet.rs) implement that specification.

Storage and Embedding

leviculum-core is #![no_std] with only alloc (leviculum-core/src/lib.rs:59-70). It contains no I/O, no clock, no filesystem, and no async runtime. That is what lets the exact same protocol code run on a Linux daemon, a future Android app, and a bare-metal nRF52 firmware image. The bridge to the outside world is a small set of traits the core depends on but does not implement.

Three injected dependencies

The core declares its platform needs as traits in leviculum-core/src/traits.rs and takes implementations from the driver:

• Clock (traits.rs:419) — supplies the monotonic now_ms() and, only where the platform has a real wall clock, wall_unix_secs() (default None). The core never calls a system clock; time is handed in. now_ms() is a timer, not a calendar — on the host it counts milliseconds since process start (leviculum-std/src/clock.rs:45), on the nRF52 it is the Embassy timer (leviculum-nrf/src/clock.rs:8). Which wire fields need calendar time instead, and where a clockless node gets it, is the subject of Time and Clocks.
• Storage (traits.rs:500) — supplies persistence and lookup for every collection the protocol maintains. flush() defaults to a no-op (traits.rs:856) so a RAM-only backend needs to implement nothing extra.
• Interface (traits.rs:242) — supplies framing and the wire (see Interface Isolation and the Interface trait).

Randomness is injected the same way, as an explicit rng: &mut impl CryptoRngCore parameter rather than a global (leviculum-core/src/lib.rs, "Platform Dependencies").

The Storage trait

Rather than a generic key/value blob store, Storage exposes type-safe methods grouped by collection — packet-dedup hashes, the path table, the reverse table, link/announce tables, receipts, and ratchets — with typed entries from storage_types.rs. The full method inventory is tabulated in Architecture.

This shape was a deliberate decision. The deep analysis of every method — who calls it, how often, and whether it matters on an embedded target — is in Storage Trait Split Analysis. Read that page before changing the trait surface.

Three backends, one core

The same NodeCore is parameterised over its Storage implementation, so embedding is a matter of choosing a backend (leviculum-core/src/node/mod.rs:409, NodeCore<R: CryptoRngCore, C: Clock, S: Storage>):

FileStorage persists only what must survive a restart — known destinations, the packet dedup hashlist, and ratchet keys — and keeps the rest (paths, reverses, links, announces, receipts) in RAM, rebuilt from the network on restart. The file formats and flush strategy are in Architecture.

What the split buys you

• Host vs. embedded from one source tree. leviculum-std builds a tokio driver around the core; leviculum-nrf builds an Embassy driver around the same core (leviculum-nrf/src/bin/t114.rs, leviculum-nrf/src/bin/rak4631.rs, both #![no_std] and both constructing the core via NodeCoreBuilder).
• Testability. Because time and storage are injected, the core is driven deterministically in tests — feed bytes and a fixed clock, drain the TickOutput, assert. This is the basis of the minimal-reproducer tests under leviculum-std/tests/mvr/.
• No host concerns in the core. Backpressure, airtime budgeting, and serial queueing live host-side in leviculum-std and never leak into the no_std core (leviculum-std/src/interfaces/airtime.rs:1).

See Architecture for the sans-IO core diagram and the driver event loop that pumps these traits.

Time and Clocks

How a node keeps calendar time, why it must always be able to, and how a wrong calendar heals. This applies to every firmware and every platform port, present and future. Issues come and go; this concept stays.

This page is the binding spec of the anchor model. It replaces the earlier doctrine "no verified clock, no authorship": the rule is now that every instance always authors, stamped with its best honest estimate and never ahead of that estimate — and that foreign garbage timestamps must never break an instance. "Never ahead" is exactly what the mechanisms deliver, no more: every fallback anchor lies in the past, so an uncertain calendar errs backwards by construction. It is not a claim to detect a wrong source: an anchor that is wrong but inside the sanity window — including a plausible forward-wrong one — is adopted and stamped as-is, a named residual, time-bounded by the healing loop. The sections below define the estimate, the anchor's provenance rank, the one filter every time source passes, and the loop that heals a wrong calendar. Testing the model closes the page: the rule-by-tier matrix that binds every one of these rules to a named test cell, Periculum included.

The two poisons

Calendar failures hurt in exactly two directions, and they are not symmetric.

Too old, self-consistently. A Reticulum peer orders same-destination paths by the announce emission timestamp. Python-RNS stamps int(time.time()) — epoch seconds — into the announce random hash (reference/Reticulum/RNS/Destination.py:282) and replaces a stored path only when a new announce carries a newer emission than the stored one (announce_emitted > path_timebase, reference/Reticulum/RNS/Transport.py:1772; the worse-hop branch runs the same newer-wins comparison against a separately computed field, announce_emitted > path_announce_emitted, Transport.py:1809). The value we stamp is therefore compared on other machines, across our reboots, against values our earlier selves emitted. A clock that is merely self-consistent — process uptime — restarts from zero on every reboot and loses that comparison forever: the node keeps announcing, and no peer ever updates its path entry again (Codeberg #155). Obtaining usable time is a protocol obligation, not a platform convenience. #155 is one instance of a general failure class — a generated field that is self-consistent between our writer and our reader and means something else to a peer; the class and the audit method for it are in Wire Field Semantics.

Too far in the future. The reverse error is worse, because it poisons others, silently and permanently. Receivers advance monotonic cursors over the stamps they ingest — the worked case is the telemetry collector cursor (Telemetry), which one future-stamped row raises past every honest later reading, forever, with no refusal logged anywhere. A past-stamped message, by contrast, sorts too far back where it is displayed directly: visible, attributable, self-limiting. One reader must be priced honestly rather than folded into that: a collector serves only rows above a requester's cursor, so a past-stamped row below an already-synced cursor is not "sorted backwards" — it is invisible to that requester, indistinguishable from loss, until the sender's calendar heals (see the one honest cost).

These two poisons shape the whole model. A node must always be able to author — an instance that falls silent for lack of a clock fails the switch-on-and-it-works requirement exactly when it is needed — and when its calendar is uncertain, the error must land in the benign direction: backwards, never forwards.

Two clocks, strictly separated

A node runs two clocks with disjoint jobs, and no time correction ever crosses from one to the other.

The stopwatch is the monotonic tick counter, Clock::now_ms (leviculum-core/src/traits.rs:369). All timeout and deadline arithmetic stays on it — retries, link timeouts, announce cadences. No anchor change, GNSS fix, or healing step ever stretches or shrinks a protocol timer.

The calendar clock is an estimate, not a measurement: an anchor (unix seconds, obtained from some source) plus the stopwatch time elapsed since that anchor was seated. Two properties follow by construction:

• It never stands still. Between anchors it advances with the stopwatch, so repeated identical stamps — the #217 class of same-timestamp ID collisions — cannot come back.
• It moves in jumps only when a better anchor re-seats it. An anchor change is an explicit, recordable event with a source, not a drift.

The clockless arm of the implementation already has this shape: a learned floor advanced by the monotonic clock, inside Transport::emission_secs (leviculum-core/src/transport.rs:5014). On std platforms the same estimate answers from the OS: the SystemClock implementation of wall_unix_secs (leviculum-std/src/clock.rs:49) reads SystemTime, with the anchor-keeping delegated to the OS and its NTP discipline.

One value, one producer

Transport::emission_secs (leviculum-core/src/transport.rs:5014) is the single point that turns the calendar estimate into the unix-seconds value for wire fields that peers compare across our process lifetimes: announce emission timestamps, built by generate_random_hash (leviculum-core/src/announce.rs:156), and request timestamps (leviculum-core/src/node/mod.rs:1477, :1154, Codeberg #164). Any new wire field with cross-lifetime semantics draws from it too — never from the monotonic Clock::now_ms, which is a timer, not a calendar.

Crates layered on NodeCore reach the same producer, they do not take a parameter. NodeCore::emission_secs exposes it; LXMF's three cross-lifetime fields — the message timestamp, the ticket expiry and the propagation upload timestamp — resolve through it inside the router (leviculum-lxmf/src/router.rs, Codeberg #182). They used to arrive as a now_unix: f64 argument on enqueue, tick, handle_event and issue_ticket_field, which is the #155 shape with the defect moved into the caller: nothing about the signature stops a clockless node from passing uptime seconds. An API that cannot be called wrongly beats a doc comment warning about it. Pinned at leviculum-lxmf/tests/wall_clock_producer.rs, structurally (no public router entry point takes an f64) as well as by value.

One producer, two resolutions

The field decides the resolution, not the clock. emission_secs returns whole seconds for fields that are whole seconds on the wire — the 5-byte announce emission timestamp above all. emission_micros returns the same instant in microseconds, and NodeCore::emission_secs_f64 divides it back into fractional unix seconds for fields that are floats. They are the same producer with the same source ranking: emission_micros(now) / 1_000_000 == emission_secs(now) on every arm.

The float resolution exists because LXMF hashes the message timestamp into the message ID. At whole seconds, two identical messages created inside one second are one ID, and the second is refused as a duplicate of the first — a message the reference, writing time.time() (reference/LXMF/LXMF/LXMessage.py:357), would have sent (Codeberg #217).

Microseconds, not milliseconds. The collision is between two calls in one code path, not two user actions. Two consecutive LxmfRouter::create_message calls measure ~115 µs apart — each signs an Ed25519 message — so a millisecond value collides on every such pair; that was measured at 20 pairs out of 20 before this unit was chosen. Microseconds is also what the reference effectively produces: time.time() is an f64 of unix seconds, resolving to ~0.24 µs at present-day timestamps.

On the clockless arm the sub-second part comes from our own monotonic clock, and Clock::now_ms is the only monotonic source there. So emission_micros returns floor_secs * 1_000_000 plus the milliseconds elapsed since the floor was set, scaled up: monotonic, separating two instants one millisecond apart, and honest about the resolution the platform actually has. It is not a claim to know the wall-clock microsecond, and nothing reads it as one. Platforms whose Clock implements only wall_unix_secs get the trait default — secs * 1_000_000 — and keep working unchanged, with no precision to gain and none invented.

An age is not a timestamp, and the producer steps

Everything above is about instants a peer compares. A second kind of consumer measures ages against the same value — how long ago did we see this ID, how long ago did this peer announce its stamp cost — and for that consumer the calendar clock has a property the instant consumers do not care about: it moves in jumps.

A clockless node stamps from uptime seconds until its first re-anchor, so the step at that moment is the full distance from a few seconds to present-day unix time — about 1.7e9 seconds, at once. Any window aged by subtracting a stored calendar value from the current one expires in that single step, however short the window's real age. Nothing grew old; the ruler changed.

The rule, therefore: age on the stopwatch, stamp on the calendar. A cache that must survive process restarts has to persist calendar values — the stopwatch epoch does not outlive the process — so it stores the calendar stamp and absorbs the step instead. The LXMF router does exactly that: it keeps the (emission_secs, now_ms) pair of the last tick and, when the calendar advances by more than the stopwatch says it should have, shifts every stored stamp by the difference (LxmfRouter::anchor_wall_clock, leviculum-lxmf/src/router.rs:1927, Codeberg #186). The ages the cache encodes are then preserved exactly across the re-anchor, and real elapsed time still expires entries.

Two things are deliberately NOT absorbed. A stamp is never moved past the current calendar value, so a checkpoint restored from a life with a real clock onto a node still on uptime seconds cannot become unexpirable. And expiries a peer wrote from its own clock — an LXMF ticket's expires_unix — are absolute instants, not ages measured here: a node whose calendar has just become real should start honouring them, not carry them along.

The one refusal left: a field the peer discards in silence

Authorship is never refused — that is the headline rule of this page. One narrow refusal survives it, and it blocks no message.

The LXMF ticket expiry is compared on the peer's clock: a peer keeps a ticket only while time.time() < expires on its own machine (reference/LXMF/LXMF/LXMRouter.py:1854) and says nothing when it does not. A backwards-biased expiry from an unhealed calendar is therefore already expired on arrival — issuing it is emitting a field the peer silently discards. LxmfRouter::issue_ticket_field (leviculum-lxmf/src/router.rs:669) returns RouterError::NoWallClock while the calendar is not a plausible wall clock, rather than issue one: a named error is a diagnosis; a discarded ticket is a mystery that surfaces months later as "replies from this peer are slow".

"Plausible" here is a question about the anchor's provenance rank, not about its value: a birth-anchored (rank 5) calendar holds a value that passes the sanity window and is refused anyway, because its estimate is recognisably behind real time and every expiry it computes is already in the past on every healed peer. The gate is NodeCore::has_plausible_wall_clock (leviculum-core/src/node/mod.rs:3608), and since Codeberg #247 it asks the rank: anchor_rank() < BIRTH_ANCHOR_RANK.

Fields the peer decides nothing on are always emitted. The LXMF message timestamp (displayed and sorted, LXMessage.py:357 unvalidated) and the propagation upload timestamp (bound and dropped, LXMRouter.py:2238-2240) both flow regardless of clock state — a backwards-biased stamp mis-sorts, and mis-sorting is the accepted cost, not a failure. Withholding a message because our clock is uncertain would be the far worse failure.

The refusal is always on writing, never on reading: a peer's ticket is remembered and used regardless of the state of our own clock.

The sanity window

Every candidate anchor, from every source — RTC, GNSS, host injection, network-learned time — passes one filter. No source gets a special case, and no source bypasses it.

• Lower bound: the build timestamp. The firmware or binary build time is compiled in: free, always present, and incorruptible by any runtime input. Real time is always after it, so any source claiming a moment before it — a 1999 RTC with a dead backup cell — is deterministically garbage, not merely suspicious.
• Upper bound: a generous margin above the best known anchor, on the order of decades above the build floor. It only has to separate values a real clock could hold from values none can; its exact size is a tunable practice parameter (see Practice parameters), not dogma.

A source that fails the window is refused as an anchor — never "corrected" — and the calendar keeps running on the best anchor it has. GNSS gets no bypass: it is simply the highest-ranked source inside the same filter, trusted by default and rejected when implausible. A receiver subtly shifted within the window (a spoofed or faulty fix that still looks plausible) is an accepted residual risk, time-bounded by the healing loop.

The window answers exactly one question: may this value seat an anchor at all. Every other predicate in the model — is first adoption still unbounded, may a ticket be issued, does the calendar count as a plausible wall clock — keys on the anchor's provenance rank, not on its value clearing the window. The next section is that rule; skipping it re-introduces two regressions by accident.

Implementation status. The lower bound is the build timestamp (Codeberg #247): leviculum-core/build.rs embeds it, BUILD_UNIX_SECS (constants.rs:621) carries it, and EMISSION_SANITY_FLOOR_SECS (constants.rs:654) is the bound the filter applies — the build stamp, floored by the old fixed date EMISSION_PLAUSIBLE_MIN_SECS (constants.rs:628, 2020) so a bogus SOURCE_DATE_EPOCH cannot lower it. The upper bound is still the fixed date EMISSION_LEARN_CEILING_SECS (constants.rs:611, 2200-01-01). One filter enforces both on learning, on host injection and on GNSS. The stamp is precise enough by construction: real time is always after the moment the binary was built, and a stale stamp only widens the window.

Anchor provenance is first-class state

An anchor is a pair: the value it seated and the rank of the source that seated it (the arms of the next section). The calendar keeps both, and the model's predicates split cleanly over the two:

• The sanity window bounds anchor admission — a question about the value, asked once, on the way in.
• Adoption, healing and ticket predicates key on the anchor's rank — never on whether its value happens to clear the plausibility floor.

The distinction is load-bearing, because the build floor (arm 5) sits at the plausibility floor by construction: every firmware is built after 2020, so a birth anchor passes every value test from the moment arm 5 is plumbed. Two predicates in the tree then misfire if they stay keyed on the value:

• Unbounded first adoption. learn_emission_timebase (leviculum-core/src/transport.rs:5201) selected the unbounded branch by current < EMISSION_PLAUSIBLE_MIN_SECS until #247. A birth-anchored cold node clears that test, so its first credible announce would have fallen into the bounded branch and the node would have crawled to real time at one day per announce — the exact #161 §1 regression this page forbids — instead of healing in one step. It now asks anchor_rank() == BIRTH_ANCHOR_RANK.
• The ticket refusal. NodeCore::has_plausible_wall_clock (leviculum-core/src/node/mod.rs:3608) became vacuously true at the build floor: the refusal would never fire again, and a birth-anchored node would issue tickets whose expiry is already in the past on every healed peer — the silently-discarded field the refusal exists to prevent. It asks the rank too.

The binding rule: while the calendar is anchored at rank 5 (birth), first adoption is unbounded, tickets are refused, and the calendar does not count as a plausible wall clock — regardless of the anchor's value. Stated the other way round: a build-floor anchor passes the sanity window for stamping — the node authors, per the stamping rule below — but it is never "plausible" for tickets or for capping adoption.

Both switches landed in the same change as the build floor (#247), which is what that requirement meant: a port that plumbs the stamp without moving the predicates ships both regressions at once. The rank is TimeSource::rank (leviculum-core/src/transport.rs:1579) and BIRTH_ANCHOR_RANK (leviculum-core/src/transport.rs:1651) is the constant every predicate compares against.

The source ranking

The calendar takes its anchor from the best source available, and a higher-ranked source re-seats an anchor from a lower-ranked one — the arms 1 to 4 of the old chain survive here as ranks. The order is by how hard the source is to fool, not by precision: a GNSS fix is a live measurement, a host injection is an explicit claim by an operator, an RTC is whatever it was last set to, and network-learned time is arbitrary input from anyone in radio range. Every arm passes the same sanity window. For each: what it costs, when it is unavailable, what it guarantees.

Rustdoc debt, paid in #247. Two doc comments in the tree stated a different order and were corrected by the issue that implemented this ranking: the rustdoc of set_wall_time_unix_secs (leviculum-core/src/node/mod.rs:936, and on the transport at transport.rs:4038) said a platform wall clock always takes precedence over an injection — the reverse of arms 2 and 3 — and its NodeCore::emission_secs (leviculum-core/src/node/mod.rs:3593) rustdoc listed the chain as "platform wall clock, learned announce timebase, host injection, uptime". This page is the spec; both now say so, and both name the one place the implementation still deviates from the order — it consults the platform clock first, which no platform can currently observe because none offers a second arm alongside it.

Arm 1: GNSS

Where the board has a receiver — today the WisMesh Pocket V2's u-blox ZOE-M8Q (leviculum-nrf/src/gnss.rs). The NMEA RMC sentence carries UTC date and time in every fix.

• Cost: receiver power, a sky view, and cold-start acquisition time (seconds to minutes).
• Unavailable: indoors or shadowed — a node without sky view never gets a fix, so GNSS seeds the calendar, it never replaces the ranking below it.
• Guarantees: UTC to well under a second, far beyond the one-second wire granularity. Trusted by default; a fix outside the sanity window is refused like any other source.
• Status: the firmware parses RMC but consumes only position and validity (GnssFix, leviculum-nrf/src/baseboard.rs:26, has no time field yet). Seeding the calendar from RMC is tracked as a firmware implementation issue, not here. See GNSS specifics below.

Arm 2: Host injection

Node::set_wall_time_unix_secs (leviculum-core/src/node/mod.rs:934 → leviculum-core/src/transport.rs:5125), for deployments where a clockless node has a host that does know wall time — e.g. a control frame on the LNode serial channel (the radio-config envelope of leviculum-core/src/rnode.rs).

• Cost: one control-channel frame; requires a host that itself has a trustworthy clock.
• Unavailable: standalone nodes with no host attached.
• Guarantees: host-clock quality, sanity-gated: values outside [EMISSION_PLAUSIBLE_MIN_SECS, EMISSION_LEARN_CEILING_SECS] are refused (leviculum-core/src/transport.rs:5133), because an injection claims to know wall time, so a value no real clock can hold is self-refuting. Pinned at test_implausibly_low_wall_time_injection_is_refused (transport.rs:23649) and test_absurd_wall_time_injection_is_refused (transport.rs:24112).
• Status: wired (#238): the control envelope's wall-time frame (docs/src/firmware/usb-control-envelope.md) carries a u64 of unix seconds from the host to the seam; the seam's bool picks the enveloped ack or the named value refused answer, an accepted seed logs [TIME_SEED] source=host, and lnflash --set-time is the speaker.

Arm 3: Platform clock passing sanity

Clock::wall_unix_secs (leviculum-core/src/traits.rs:440). On std platforms SystemClock answers from SystemTime (leviculum-std/src/clock.rs:50) — effectively the OS's NTP-managed clock. On a board it is a battery-backed RTC, which under this model also carries anchors back: see the healing loop for the write-back.

• Cost: none.
• Unavailable: on MCUs without an RTC. The LNode's EmbassyClock (leviculum-nrf/src/clock.rs) keeps the trait default of None — that is correct, not a gap: returning uptime-derived values from wall_unix_secs would be lying to the transport.
• Guarantees: whatever the platform clock guarantees — NTP quality on a host, last-set-plus-drift on an RTC. An RTC counts only when its value passes the sanity window; below the build floor it is a dead cell, not a time source. Note the trait contract: this is not a timer source; all timeout and deadline arithmetic stays on the monotonic now_ms (traits.rs:369).
• Status: the implementation consults this arm first when it answers (emission_secs, leviculum-core/src/transport.rs:5014). No current platform offers both a platform clock and GNSS or injection, so the difference in order has no behavioural effect today; a port that has both follows this ranking. The arm reports itself as TimeSource::PlatformClock only while its value passes the window (time_source, leviculum-core/src/transport.rs:5135); below the build floor it is a dead cell and the calendar stays birth-anchored, which is what refuses tickets on a node with a dead RTC.

Arm 4: Network-learned

The sourceless fallback: learn_emission_timebase (transport.rs:5201) adopts the highest emission timestamp seen in any signature-valid announce as the calendar anchor, then advances it with the monotonic clock (transport.rs:4494). This includes the node's own pre-restart announce echoing back from a neighbour — learning deliberately runs before the own-destination echo drop, so a rebooted node re-seeds past exactly the value its next announce must exceed — pinned at test_own_announce_echo_reseeds_timebase_before_echo_drop (transport.rs:23353).

• Cost: nothing — no hardware, no host.
• Unavailable: on a mesh where no participant has a clock, or before the first plausible traffic arrives.
• Guarantees: only as good as radio-range neighbours, and validate() proves only that the announce signs itself — the field is arbitrary input from anyone in range. Hence every hardening rule below and the re-anchor rules of the healing loop. A calendar seated by this arm is anchored from traffic, unconfirmed: the evidence may itself be another unhealed node's birth clock (see the one honest cost). The learned anchor is in-memory only on RTC-less boards: after a reboot the node starts from the build floor again until live traffic re-seeds it. Adoption records the transition: the source becomes TimeSource::Overheard, rank 4, and a higher-ranked anchor that is merely being advanced keeps its own rank.

Arm 5: The build floor

The birth state of every instance with no better source: the calendar anchors at the build timestamp, advanced by uptime. This replaces raw uptime seconds as the bottom of the ranking, and it is a valid state, not a defect: the stamp is recognisably old, but unique, monotonic, and non-toxic — it can never poison a peer's cursor, because it errs backwards. Nobody stays silent, nobody poisons; the cost is confined to the one honest cost below. The rank is the part that matters beyond the value: a rank-5 anchor stamps, but it never counts as a plausible wall clock, never issues tickets, and never caps adoption (provenance rank).

• Cost: none; the build timestamp is compiled in.
• Unavailable: never — that is the point.
• Guarantees: uniqueness and monotonicity within the boot, a value that is always in the past, and a floor the sanity window can trust.
• Status: implemented in the core (#247). An instance with no source anchors at BUILD_UNIX_SECS (leviculum-core/src/constants.rs:621) advanced by uptime, which retires the raw-uptime state every cross-restart comparison lost (#155). A port inherits it with the core and adds nothing; what a port still owes is the arms above it.

Stamping: always author, never ahead of the estimate

Every instance always stamps outgoing fields with its best honest estimate of now — the calendar clock, whatever its anchor. The directional guarantee is stated at its real strength: we never stamp ahead of our own estimate, and every fallback anchor lies in the past, so an uncertain calendar errs backwards by construction. That is where the safety comes from: the poison was never wrong time but future time (the cursor mechanism in the two poisons is why — permanent, silent, hurts others), while past time hurts only presentation. What the mechanisms do not deliver is detection of a wrong source: an anchor that is wrong but inside the sanity window — a plausible forward-shifted GNSS fix, a mis-set host clock — is adopted and stamped as-is. That residual is named here rather than implied away, and it is time-bounded by the healing loop. A source-less instance anchors at build-time plus uptime and authors anyway.

The old rule — no verified clock, no LXMF authorship — is withdrawn. It bought cursor safety by silencing exactly the instances a mesh is for, and the same safety is now had cheaper: backwards-biased stamping at the writer, ingress clamping at the reader.

The one honest cost

Between cold start and healing, outgoing messages carry recognisably old stamps, and the cost is priced per path. Where a stamp is displayed directly, it sorts backwards — a Sideband conversation shows messages out of order until the calendar heals: visible, attributable. On the collector path the same stamp costs more, and the real price is stated rather than rounded down: a collector serves only rows above a requester's cursor, so a birth-stamped row sits below every already-synced requester's cursor — not sorted backwards but invisible to that requester, indistinguishable from loss, until the tracker heals and stamps climb past the cursor (Telemetry).

How the cost ends is graded by what healed the calendar:

• Contact with arms-1–3-quality time — a GNSS fix, a host injection, a plausible platform clock — ends it outright.
• Traffic healing (arm 4) ends it provisionally. A foreign stamp that passes our sanity window may itself be another unhealed node's birth clock: a build-floor stamp from a node built after us (or comparably) clears our own floor. The calendar is then anchored from traffic, unconfirmed — better than birth, not yet known-good — and stays in that state until arms-1–3-quality contact confirms or corrects it. Two clockless nodes healing from each other are an echo chamber, and nothing on the wire can fully prevent it: the stamps are signature-valid and in-window. A named residual, not a solved problem.

We state the cost rather than hide it, because the alternatives are the two poisons: silence or invented time.

Ingress: clamp for semantics, keep for display

The mirror image of backwards-biased stamping protects us from everyone else. An incoming stamp beyond the local plausible-now is clamped to receive time for ordering and cursor semantics: indexing and above all cursor advancement — in our collector (#239) and in any future propagation node. The original stamp is kept alongside as local display information, so nothing is destroyed and a viewer on this node can still show what the sender claimed.

Local plausible-now, defined. The basis is the local calendar estimate at receive time — Transport::emission_secs (leviculum-core/src/transport.rs:5014) — plus a bounded forward tolerance for honest clock skew between sender and receiver. A stamp at or below basis-plus-tolerance passes as-is; above it, it is clamped to receive time. The tolerance is a practice parameter (see Practice parameters): its job is to keep two honestly-synced clocks from clamping each other, not to admit the future.

Three boundaries keep the clamp from doing damage of its own:

• Dedup keys are not clamped. Deduplication runs on content or transient ID, never on the timestamp, so clamping can neither make two distinct readings collide nor let a replay through. The clamp covers ordering and cursor semantics only.
• What is served is the clamped value. A telemetry stream row has exactly one timestamp slot (the row form in Telemetry), and a collector serves what it indexed. Keep-for-display is local-only — and the limit of the defence is stated with it: the row's packed_telemetry payload still carries the sender's raw claim in its own SID_TIME, so a downstream reader that parses the payload sees the claim. Cursors — ours and every requester's — advance over the clamped value regardless.
• The clamp is armed only by a healed calendar. Clamping "to receive time" presumes the receiver knows what time it is. An unhealed collector — birth-anchored, or below arms-1–3 quality with no traffic re-anchor yet — would clamp every honest current stamp down to its own ancient notion of now and blackhole the mesh's telemetry into a years-old index. While unhealed, it takes in-window sender stamps as-is; those same stamps are simultaneously its healing evidence (arm 4). Rows ingested before healing keep their index stamps — there is no re-index — and that cost is part of the honest cold-start story above.

The reason for the clamp is the cursor mechanism: a cursor that advances over a raw foreign stamp hands every sender a lever to starve it. Clamped, the worst a garbage stamp can do is index as "arrived now" — wrong by presentation, harmless by mechanism. Foreign garbage can no longer break us, which is the other half of the always-author rule: authorship without ingress protection would just move the poison one hop.

Scope: this clamp lives at the application layer — what we index, serve, and advance cursors over. It does not touch announce path ordering, which stays raw for reference parity; see the non-behaviours below.

Rules that hold regardless of source

The wire field is 40 bits; every producer saturates

The announce timestamp field holds 8 * RANDOM_HASH_TIMESTAMP_SIZE = 40 bits. A larger value would silently drop its high bits on the wire and sort below every stored path entry — the node instantly loses path replacement everywhere. EMISSION_TIMESTAMP_MAX_SECS (leviculum-core/src/constants.rs:602) caps it, enforced at the point of resolution (transport.rs:4504) and again at the wire producer (announce.rs:167), so truncation is unrepresentable regardless of which source produced the value. Incident: Codeberg #160. Pinned at test_emission_secs_saturates_at_wire_field_max (transport.rs:24136).

The timebase never moves backwards, and adoption is windowed

Within arm 4, an older emission never regresses the anchor (emitted_secs <= current, leviculum-core/src/transport.rs:5223), and adoption is bounded by the sanity window: values above EMISSION_LEARN_CEILING_SECS (constants.rs:611, 2200-01-01) cannot come from a real clock and are refused outright (leviculum-core/src/transport.rs:5208); the lower bound is the build floor EMISSION_SANITY_FLOOR_SECS (leviculum-core/src/constants.rs:654), which real time is always after, so a peer's uptime seconds and a dead RTC's 1999 are refused as anchors by the same filter (#247). Incidents: #160, #161. Pinned at test_clockless_node_learns_emission_timebase_from_announce (transport.rs:23249) and test_timebase_floor_cannot_pass_learn_ceiling (transport.rs:24051). The per-announce no-backwards guard is not contradicted by the healing loop: a backwards re-anchor is a deliberate event that requires arms-1–2 evidence and respects the emitted high-water mark (see the healing loop) — never one announce dragging the anchor down.

The FIRST adoption is unbounded while anchored at rank 5

While the calendar is still on its birth anchor — rank 5 — adoption is deliberately unbounded (learn_emission_timebase, leviculum-core/src/transport.rs:5201): a node starting at the build floor must climb to real unix time in one step. First-plausible-wins is correct here, and only here: a birth anchor has nothing worth defending, and instant recovery beats attack resistance for it. The predicate is the anchor's rank, not its value: a birth anchor's value clears the plausibility floor now that the build floor is plumbed, and a value test would route a cold node into the bounded branch below (provenance rank). The negative that catches exactly that misfire is test_birth_anchor_value_clears_the_window_but_not_the_rank (leviculum-core/src/transport.rs:23747). Capping this was a real regression (#161 §1): with the bounded advance applied to an implausibly low anchor, recovery crawled at one day per announce — about 20 602 announces, ~429 days at a 30-minute LoRa cadence — where a single credible announce used to recover the node instantly. Do not re-introduce that cap. The no-backwards guard above keeps the unbounded branch from being abused downwards. Pinned at test_clockless_first_timebase_adoption_is_unbounded (transport.rs:23445) and test_clockless_timebase_advance_is_bounded_after_first_adoption (transport.rs:23394).

Advance past rank 5 is bounded — per announce, not per peer

Once the calendar is no longer birth-anchored, one announce may advance it by at most EMISSION_LEARN_MAX_ADVANCE_SECS (constants.rs:693, one day), so a peer whose clock is decades wrong cannot capture the calendar in one announce. State the protection level honestly: learning runs before the per-destination announce rate limit and the rebroadcast dedup, so N announces advance the floor by N × cap regardless of how many identities or destinations they came from. The real cap on the walk rate is announces-per-second on the air — nothing identity-shaped. This measured reality is pinned at test_timebase_walk_is_capped_per_announce_not_per_identity (transport.rs:23977); the walk terminates at the learn ceiling, pinned at test_timebase_floor_cannot_pass_learn_ceiling (transport.rs:24051). No durable defence is claimed from the healing loop's median: a median over free identities resists a broken peer, not an attacker. What actually bounds a hostile forward walk is the ceiling and the airtime it costs; what undoes one afterwards is arms-1–2 evidence, because the healing loop deliberately refuses to move a calendar backwards on traffic alone.

We do not validate our own clock, or incoming timestamps

Two deliberate non-behaviours, both reference parity. The anchor model does not soften them — it validates anchors on the way into the calendar, never emissions on the way out or announces on the way into the path table:

• Our own calendar estimate is emitted verbatim. Python fills the field from time.time() unvalidated (Destination.py:282); bounding, substituting, or withholding our value at emission time would desynchronise us from a network that does not validate. Under the anchor model an "implausible own clock" collapses to "no anchor better than the build floor" — and that state emits too, per the stamping rule. The once-per-process operator warning in Transport::announce_emission_secs (transport.rs:5089) remains the only reaction to an implausible value — never an altered emission. Pinned at test_own_wall_clock_is_not_plausibility_bounded_on_emission (transport.rs:24297) and test_implausible_own_wall_clock_warns_once_and_leaves_emission_unchanged (transport.rs:24345).
• Incoming emission timestamps are not plausibility-checked on path acceptance. Ordering is per-destination comparison only, exactly announce_emitted > path_timebase (Transport.py:1772; the worse-hop branch compares against its own stored field at Transport.py:1809). A clockless peer's uptime-seconds announce must enter the path table (that is how a #155 node is reachable at all), and an absurdly high emission must win the newer-emission comparison. Python peers accept both; filtering would only desynchronise our path tables from every other node's view of the same announces. Pinned at test_incoming_emission_not_plausibility_checked_on_acceptance (transport.rs:24416). The ingress clamp operates strictly above this layer — on what we index and serve, never on what we route.

The sanity window exists for anchor adoption — learning, host injection, GNSS, RTC — never for emission or path acceptance.

The healing loop

The protocol self-heals wherever the evidence for healing exists; where it does not, this section names the residual instead of claiming one. The loop, binding as spec:

1. Collect. Plausible foreign times are gathered from live traffic the node already receives — LXMF message stamps, propagation announces. Plausible means: passes the sanity window.
2. Re-anchor — by rank and by direction.
   • While anchored at rank 5, a single plausible source re-anchors the calendar. This is the unbounded first adoption above, restated as the healing rule: a birth anchor has nothing worth defending. Unless the source was arms 1–3, the result is anchored from traffic, unconfirmed.
   • A calendar already anchored to real time is never re-anchored by a single sender. A forward correction requires gross deviation from the median of several distinct senders; cohort size and deviation threshold are practice parameters.
   • A gross backwards correction additionally requires arms-1–2 evidence — a GNSS fix or a host injection — never traffic alone. Announce identities are free (this page already concedes that for the walk cap), so a traffic median in the past is exactly what an attacker can fabricate; a backwards path open to traffic would be a remote lever for dragging any healed calendar down and silencing its announces. Closing it costs a residual, named under "sparse meshes" below.
   • The emitted high-water rule, binding on every re-anchor: the calendar is never re-anchored below the highest value this identity has ever emitted — not even by arms-1–2 evidence; the correction floors at the high-water mark. Peers order our announces by emission timestamp (announce_emitted > path_timebase, reference/Reticulum/RNS/Transport.py:1772), so dropping below our own emitted high-water silences our announces mesh-wide until the calendar climbs past it again — and re-stamping a range we already stamped would revive the #217 same-stamp class this page claims cannot come back. Where storage exists, the high-water mark is persisted across boots. An RTC-less, storage-less node cannot persist it, and that cost is named: such a node re-enters the same build-plus-uptime stamp range on every boot until re-seeded. The practical mitigation is already in the model — arm 4 hears the node's own pre-restart announces echo back and re-seeds past them, pinned at test_own_announce_echo_reseeds_timebase_before_echo_drop (transport.rs:23353).
3. Write back to the RTC. Every better anchor is also written into a present RTC, so the hardware clock itself heals and the next boot starts from the healed value instead of the build floor. The write-back is what turns arm 3 from "whatever it was last set to" into "whatever we last verified".

What the median is, honestly. A median over distinct senders resists a broken peer: one wrong clock in an honest cohort cannot move it. It does not resist an attacker — identities are free, and a cohort of them is one attacker with a loop. The attack-facing guarantees come from the other rules: the ceiling and the advance cap bound a forward walk, the arms-1–2 requirement closes the backwards lever, and the high-water rule caps what any accepted correction may do to our own emissions.

Sparse meshes, honestly. With one neighbour no cohort exists, so a calendar that is grossly forward — and no longer at rank 5 — does not heal from traffic at all: the median that would justify a correction cannot form, and traffic alone may never pull backwards anyway. The residual is stated rather than papered over: such a node heals through a GNSS fix, a host injection, or a reflash — not from listening. Until then it keeps authoring, and the learn ceiling keeps it from walking further.

The cold-start story then reads: a device with nothing stamps from its birth anchor; the first plausible contact re-anchors it — to known-good time when the contact was arms 1–3, to traffic-unconfirmed when it was a foreign stamp, which may itself be another unhealed node's birth clock (the echo-chamber residual of the one honest cost); the RTC (where present) keeps it across power cycles; and a calendar later walked wrong is corrected forward by its cohort's median, backwards only on arms-1–2 evidence. No operator action at any step — switch on and it works, with the residuals stated.

Implementation status. Arm 4's single-announce learning (learn_emission_timebase, transport.rs:5201) implements the rank-5 re-anchor today. The median re-anchor, the collection of LXMF-stamp evidence, the high-water persistence, and the RTC write-back are spec, tracked as implementation issues per platform.

GNSS specifics for a board bring-up

• Use NMEA UTC, never raw GPS time. GPS system time does not observe leap seconds and is currently 18 s ahead of UTC. The receiver applies the broadcast UTC offset before it builds the RMC sentence, so RMC date + time is UTC — take it from there. Getting this wrong is silent: an 18-second skew breaks nothing visibly and is indistinguishable from clock drift in the field.
• Acquire, seed, let the receiver sleep. One fix seeds the calendar; the monotonic clock carries it forward. Crystal drift (tens of ppm — under half an hour per year of isolation) is irrelevant at one-second wire granularity. Keeping the receiver powered buys nothing for time.
• Seed through the sanity window. Route the fix through the same filter as every other source so a garbage fix cannot wedge the calendar; a valid RMC should pass it trivially. A subtly shifted fix inside the window is the accepted residual risk named above, time-bounded by the healing loop.
• GNSS never replaces the ranking. A node without sky view never gets a fix. Arms 2–5 must behave exactly as if no receiver were fitted.

Record the source

A node should be able to state, at any moment, where its notion of time came from: GNSS, host injection, platform clock, learned from traffic (whose, and when, and whether still unconfirmed), a median re-anchor (over which cohort), or the build floor. This is more than a breadcrumb: the anchor's rank is live state the model's predicates key on (provenance rank), so a node that cannot answer it cannot even decide whether it may issue a ticket. Diagnosis of a path-ordering problem starts with "what did this node think the time was, and who told it" — without provenance, a wrong timestamp in a peer's path table cannot be attributed to a dead RTC, a lying neighbour, or a boot-order race. The healing loop raises the stakes: a re-anchor is a calendar jump, and an unattributed jump is indistinguishable from a bug. The core answers the first half: Transport::time_source (leviculum-core/src/transport.rs:5135) names the arm — including the platform clock, which answers for itself — and NodeCore::anchor_rank (leviculum-core/src/node/mod.rs:3625) is the number the predicates use. The rest — which neighbour, when, and the cohort behind a median re-anchor — is still only the once-per-process implausible-own-clock warning (announce_emission_secs, leviculum-core/src/transport.rs:5089); exposing the origin (status RPC, control-channel query) is part of implementing this concept on each platform.

Practice parameters, not dogma

The model fixes mechanisms; these values tune them. Each is a practice parameter: chosen to work, changed by measurement and a reasoned commit, never load-bearing for the model itself.

• The upper sanity margin above the best known anchor — order of decades; today the fixed date in EMISSION_LEARN_CEILING_SECS (constants.rs:611).
• The lower bound is the build timestamp and not a practice parameter at all; EMISSION_PLAUSIBLE_MIN_SECS (constants.rs:628) survives only as the guard under it, for a build stamp no firmware was ever built at.
• The per-announce advance cap EMISSION_LEARN_MAX_ADVANCE_SECS (constants.rs:693).
• The healing cohort: how many distinct senders form a median, and how large a deviation counts as gross.
• The local plausible-now tolerance: the bounded forward skew allowance added to the local calendar estimate at the ingress clamp — basis is Transport::emission_secs at receive time; the tolerance absorbs honest sender/receiver skew, nothing more.

Testing the model

Every binding rule on this page maps to a named test cell in a named tier, and this section is that map. It is a concept-level test contract: each implementing issue lands with its cells from this matrix, in the same change, never as a follow-up, and a reviewer ticks the touched rules off against this section before merge. Cells that pin behaviour already implemented are cited; cells for spec-only mechanisms are named here and land with the issue that implements them — for those, named-but-not-landed is the intended state until the issue lands, not accumulated debt. This page names cells; it writes no scenario files and no test code — the implementing issues fill the names in.

The tiers

Four tiers, in the order a failure should be caught:

• unit / mvr. Deterministic, one to two nodes, under five seconds, structured event logs from all sides — the mvr constraints of the project's protocol-debugging discipline. Canonical mvr home: leviculum-std/tests/mvr/; unit pins live beside the code they pin. Everything decidable on one node's state machine is decided here.
• workspace integration. The workspace test suite: multi-crate seams, restart persistence, structural API pins.
• periculum conformance. Docker, against real Python-RNS, under the drop-in discipline: the SAME driver (lns selftest, rnstatus, the same client binary) pointed at lnsd and rnsd — never parallel per-stack drivers, which smuggle config differences into what claims to be a stack comparison. The project's interop rule applies in full: every cross-stack rule gets a positive AND a negative cell against real Python.
• periculum hardware. The rig, and only where the radio or a real peripheral — a GNSS receiver, an RTC — is itself the subject. Time logic decidable without hardware is decided in a lower tier; this tier verifies the peripheral wiring, not the model.

The matrix

A dash means the rule has no cell in that tier by design, not that one is missing. Names not yet in the tree are the binding intent; the implementing issue may adjust a file name, but it updates this matrix in the same commit.

The cells, rule by rule

1. Stopwatch/calendar separation (Two clocks). mvr calendar_jump_timer_isolation: a wall-time injection lands in the middle of a live link, in both directions — a decades-forward jump and a backwards re-seat — and no relative timer moves. Retry cadence, keepalive interval and path expiry are observed unchanged across the jump on the structured event timeline; the test fails if any timer stretches or shrinks. This is the separation rule's negative cell and its only cell: the rule forbids exactly one thing, and this watches for it.

2. Sanity window, per source (The sanity window). One unit trio per source arm: a below-build-floor value is refused (the 1999-RTC dead-cell shape), an above-margin value is refused (a 2500-RTC), an in-window value is accepted. Arm 1 is test_refused_gnss_seed_reports_false_and_keeps_source (leviculum-core/src/transport.rs:23706), which carries the no-bypass assertion: it drives the same seam the host-injection cells drive, so a GNSS special case would have to be written into the shared filter to pass it. Arm 2 is test_implausibly_low_wall_time_injection_is_refused (transport.rs:23649) and test_absurd_wall_time_injection_is_refused (transport.rs:24112). Arm 3 is test_platform_clock_outside_the_window_is_not_a_time_source (leviculum-core/src/transport.rs:23826). Arm 4's floor is test_implausibly_low_floor_recovers_in_one_adoption (leviculum-core/src/transport.rs:23494) and its ceiling test_timebase_floor_cannot_pass_learn_ceiling (transport.rs:24051).

3. Anchor rank predicates (provenance rank). Unit, landed with the build-floor plumbing (#247): at rank 5 the unbounded first adoption fires (test_birth_anchor_adoption_is_unbounded_despite_a_plausible_value, leviculum-core/src/transport.rs:23783) AND tickets are refused (clockless_node_refuses_to_issue_a_ticket_a_peer_would_discard, leviculum-lxmf/tests/wall_clock_producer.rs:237, which asserts the rank and that the birth value clears the old floor); after an anchor from a better source the per-announce cap binds AND tickets are issued (same two cells' second halves, plus test_clockless_timebase_advance_is_bounded_after_first_adoption, transport.rs:23394); and the negative that catches the value-test misfire is test_birth_anchor_value_clears_the_window_but_not_the_rank (leviculum-core/src/transport.rs:23747) — the build-floor value alone never satisfies the plausibility predicate, even though it clears the sanity window. The older test_clockless_first_timebase_adoption_is_unbounded (transport.rs:23445) keeps its assertions and now asserts the rank alongside them. Integration: leviculum-lxmf/tests/wall_clock_producer.rs remains the structural pin that no router entry point takes a caller-supplied wall clock.

4. Stamping asymmetry (Stamping). Unit, landed with #247: test_stamps_never_run_ahead_of_the_estimate_across_anchor_changes (leviculum-core/src/transport.rs:23878) walks a sequence of anchor changes — birth, uptime advance, traffic adoption, a host re-anchor, saturation — and asserts after every step that the stamp is the estimate rather than ahead of it, that the microsecond producer describes the same instant, and that the value never repeats; the birth step asserts the clockless stamp is exactly build floor plus uptime. Wire saturation is also pinned at test_emission_secs_saturates_at_wire_field_max (transport.rs:24136).

5. Emitted high-water (healing loop). Unit: no re-anchor — including an arms-1–2-quality backwards correction — takes the calendar below the highest value this identity has emitted; the correction floors at the high-water mark (the below-floor attempt is the negative cell). Integration: persistence of the mark across a restart where storage exists; the RTC-less mitigation is pinned at test_own_announce_echo_reseeds_timebase_before_echo_drop (transport.rs:23353). The announce-timebase consequence — a peer keeps the newest path — is shown against a Python-shaped peer: conformance time_high_water_path_retention, where a re-anchored lnsd keeps its announces ordered above its own high-water and the Python peer's path entry keeps updating.

6. Healing loop (healing loop). mvr, one cell per branch of the re-anchor rule: a median over a cohort of distinct senders re-anchors a grossly-forward calendar; a single sender does NOT re-anchor a calendar past rank 5 (negative; the rank-5 single-source adoption is rule 3's cell); a gross backwards correction via traffic alone is refused, including a fabricated traffic median (negative). The Sybil-style bound — N identities from one neighbour advance the calendar no further than the documented N × cap — is pinned at test_timebase_walk_is_capped_per_announce_not_per_identity (transport.rs:23977) and stays a negative cell: the assertion is the bound, not a defence the model does not claim. RTC write-back on re-anchor is a unit cell against a mock RTC; the real peripheral is rule 10.

7. Echo chamber (the one honest cost). Conformance time_echo_chamber_third_peer: two cold, build-floor nodes adopt each other's birth clocks without harm — traffic flows, nothing poisons — and BOTH converge once a third peer with real time appears. The provenance transitions (birth → anchored from traffic, unconfirmed → healed) are observable in the structured event log of both nodes; a run that converges without showing the intermediate state fails the cell.

8. Ingress clamp + collector (Ingress, Telemetry, Codeberg #239). Unit: a future-stamped row is clamped for cursor and index and served with the clamped value; dedup still catches a twice-delivered row despite clamping (dedup keys are not clamped); an UNHEALED collector does not clamp (the arming rule's negative). Conformance time_collector_clamp_cursor: the cursor of a synced requester is never poisoned by a future-stamped row — the cell reproduces the pre-fix starvation shape and asserts it gone. Conformance time_collector_unhealed_heals: an unhealed collector takes in-window stamps as-is and heals from the very traffic it is collecting.

9. End-to-end authorship interop. Conformance against real Python, drop-in discipline both ways. time_cold_authorship_python_receiver: a cold-start lnsd authors LXMF to a Python receiver; the message is accepted and readable — it sorts old, so the cell asserts delivery, never sort order — and after healing, stamps are current. The reverse cell, time_python_future_stamps: Python sends future-stamped traffic at our stack; nothing breaks and nothing poisons — cursors are asserted not to advance past local plausible-now, and path tables stay intact.

10. Hardware tier — only where the subject is real. time_gnss_seed_rig: GNSS time seeding on the rig boards, lands with the GNSS issues (#69/#70). time_rtc_writeback_rig: RTC write-back on a board with an RTC, lands with the write-back implementation. Both are marked "lands with the implementing issue", not pre-existing debt: the rows exist precisely so those issues cannot land without their cells.

Meta-rules

• Every implementing issue carries its cells from this matrix. The issue is not done until its cells are green in the tier named here, in the same change.
• A rule without a named cell is a spec hole. The fix is a new cell in this matrix — added to it, and to the port checklist where the rule touches a port duty — before the rule is implemented, not after.
• Negative cells are mandatory wherever a rule refuses something. A refusal without a red-path test is a refusal nobody has seen fire; every "refused", "never" and "does not" in this page has its negative cell above.

Checklist for a new firmware port

1. Inventory the arms. Which of the five can this platform offer? (GNSS receiver? an attached host? OS/RTC clock?)
2. Implement Clock::wall_unix_secs only if the platform has a real wall clock. Returning None is correct and engages the ranking. Never return an uptime-derived value from it.
3. Inherit the build floor; do not reinvent it. The build timestamp is the sanity floor and the birth anchor, and the core carries both (BUILD_UNIX_SECS, leviculum-core/src/constants.rs:621, from leviculum-core/build.rs), together with the rank-keyed adoption and ticket predicates that must move with it (provenance rank). A port that substitutes its own value test for either one regresses cold-start healing and ticket refusal in one step. A packager that wants a reproducible stamp sets SOURCE_DATE_EPOCH.
4. Wire every available better source. GNSS: seed from RMC UTC through the sanity window. Attached host: implement the control-channel frame that calls set_wall_time_unix_secs.
5. Write healed anchors back to the RTC, where one exists.
6. Do not touch announce learning. It comes with the core for free. Do not disable it, and do not "improve" it with local filtering of incoming timestamps — that is a semantic deviation from the reference (see the non-behaviours above).
7. Never stamp cross-lifetime wire fields from now_ms. New fields go through Transport::emission_secs.
8. Expose the time source for diagnosis (see Record the source).
9. Leave the pins green. The tests cited throughout this document are the contract; a correct port never needs to change them. The full rule-by-tier map is Testing the model — a port's own issues land with their cells from it.

Wire Field Semantics

Every field we write into a wire structure carries a meaning that some peer acts on. This page records the failure mode where the meaning is wrong while all our own tests stay green, the audit method that finds it, and the testing rule that keeps it found. It applies to every field we will ever add to any protocol we implement — Reticulum, LXMF, or our own.

The failure mode: self-consistent and wrong

The dangerous defect is not a malformed field. It is a field whose value is self-consistent between our writer and our reader, and means something else to a peer. Our writer produces it, our reader consumes it, both apply the same rule — the same wrong rule — and every test that exercises both halves of the misunderstanding passes. Interop tests pass too, as long as they assert that exchanges succeed rather than that generated values mean what the reference takes them to mean.

Codeberg #155 is the worked example. The 5-byte announce emission timestamp is defined by the reference as unix seconds, and a peer orders same-destination paths by it. We stamped process uptime. Our own reader applied the ordering rule correctly to our own wrong values, so a pure leviculum mesh was blind to the defect; 318 interop tests against real Python missed it, because the exchanges all succeeded. The damage lived only in foreign path tables: entries that could never win the newer-emission comparison again, worsening with every restart because every reboot restarted the value from zero. A live rnsd was found carrying 660 of 10 983 path entries with non-timestamp values. The full story of where wall time comes from is in Time and Clocks; this page is about the class, not the instance.

The audit method: four questions per generated field

For every field we generate (not fields we merely echo back), answer four questions, each with a citation:

1. What does a peer DECIDE from it? Ordering, acceptance, expiry, deduplication, routing — the rule the value feeds, not the byte layout it sits in. Ask this one first: it partitions the surface. A field no peer decides anything from needs only a shape check, and the answer tells you which adverse conditions in question 4 are worth constructing.
2. What does the reference put there? File and line into reference/Reticulum (and reference/LXMF where applicable).
3. What does the reference DECLINE to put there, and why? Some guards live only in the writer, and their absence produces a well-formed field that harms the reader.
4. Does our value satisfy that rule under adverse conditions? Process restart, absence of a clock, long uptime, the field at its representable limit, a peer that has been up much longer or much shorter than we have.

Question 1 is the one our old tests never asked. A field whose encoding round-trips perfectly can still fail the decision rule — the #155 timestamp round-tripped for months.

Question 3: the refusal is part of the contract

Codeberg #181 is the worked example, and it is a different shape from #155: not a wrong value, but a missing refusal to send a value. Questions 1 and 2 both pass on it. What a peer decides is clear (mine a stamp at the announced cost) and what the reference puts there is the configured cost — we wrote the same field, with the same meaning, from the same source. Only question 3 finds it.

LXMRouter.get_announce_app_data (LXMRouter.py:1033-1052) starts from stamp_cost = None and overwrites it only when 0 < cost < 255. The reader applies no bound of its own: the announced cost is stored unvalidated (update_stamp_cost, LXMRouter.py:1027-1032) and passed straight to LXStamper.generate_stamp (LXMessage.py:320), whose search loop (LXStamper.py:199) runs until a digest meets 1 << 256-cost. At 255 that never happens. We announced whatever u8 the caller passed, so one announce from us could wedge every Python peer's outbound queue for our destination — with nothing in their logs naming us.

Two rules generalise from it:

• A guard in the writer implies no guard in the reader. When the reference validates on write, look for the matching check on read. If it is not there, the write-side guard is load-bearing, and omitting it is not a cosmetic deviation.
• The same refusal usually appears twice. #181's window sits both at the emit boundary and one layer earlier in set_inbound_stamp_cost (LXMRouter.py:378-393), where the refusal is visible in the return value. Mirroring both is what lets a caller learn, without weakening the boundary that actually protects peers.

Symmetry is worth asking about but is not automatic: our read side now drops an announced 255 (leviculum-lxmf/src/router.rs:1181-1227) although the reference does not, because that deviation is invisible on the wire and to any conforming peer, and removes an unbounded loop reachable from the network.

The frame is a field: how often we send it

The four questions are asked of a value inside a frame, but they apply unchanged to the emission itself — whether a frame goes out at all, and how many times. A peer decides from that too: a second copy of an announce it already holds is absorbed by its packet hashlist and costs it only airtime, which on a shared medium is airtime nobody else can use, and which no counter on either side reports.

Codeberg #192 is the worked example. Answering a path request, we inserted the response into the announce table with retries = 0 — the value the reference uses for a received announce, which it means to rebroadcast twice (Transport.py:1867). The reference inserts a path response with retries = PATHFINDER_R (Transport.py:2970) and completes the entry at retries > PATHFINDER_R (Transport.py:585-587): one transmission, not two. Every field in both frames was correct; the second frame should not have existed. It was found by decoding what each daemon transmitted under one byte-identical traffic script and comparing the two multisets frame by frame (status_parity_tests.rs, TX frame census), not by comparing byte totals — a percentage says something diverged, a census says what.

The mirror question: what do we refuse to read?

The four questions above are asked of fields we generate. They cannot find the mirror defect, which is being stricter than the reference on the read path: refusing a value the reference accepts. Nothing in a generated-field audit reaches it, and interop testing against Python does not either, because Python only ever produces the form we already accept. The defect surfaces only against a third implementation — reticulum-kt, microReticulum, a hand-rolled encoder — and it surfaces as silence: the message is dropped, and the sender sees a peer that never answers.

Codeberg #183 is the worked example. LXMF writes time.time(), so payload[0] from a Python peer is always msgpack float64, and our decoder demanded the 0xcb marker. The reference performs no type check at all — timestamp = unpacked_payload[0] (LXMessage.py:766) — so an integer second delivers on Python and was refused by us. The same audit found the second half: the reference hashes the payload bytes it received when there is no stamp (packed_payload, :753, :762), while we re-encoded canonically before hashing, so even a timestamp we decoded correctly would have failed its own signature.

Two rules generalise:

• The read side has a contract too, and it is the reference's accept set, not its output set. What Python's writer emits is a subset of what Python's reader takes. Auditing only against the writer measures the wrong boundary. Read the reference's decoder and enumerate what it lets through.
• Where the reference's reader keeps received bytes, keep them. Re-deriving a value that a signature or hash covers substitutes our encoder's opinion for the sender's bytes. It is invisible while every peer encodes as we do, and silent when one does not.

Refuse on write, accept on read

The two sides are not symmetric, and treating them as one rule is what produces an inconsistent codebase. Refusing to emit a value costs no peer anything: nothing conforming expects it, so the refusal is wire-invisible. Refusing to accept one costs the sender its message. So:

• A value we cannot bound the effect of goes in the writer's refusal set. Codeberg #184 put the non-finite message timestamps there: a NaN compares False against everything, so it orders arbitrarily at any peer that sorts by it, and we cannot cite what a client does with it because the decision rule lives outside the reference.
• The same value is still accepted on read, because a peer that sent it has already made its choice and dropping the message adds nothing.
• The exception is a value that becomes a bound on our own behaviour — a ticket expiry we store, a snapshot field we restore. There the reader refuses too, because accepting it hands an unbounded quantity to a comparison that governs our resource use (Ticket::from_field_value, leviculum-lxmf/src/ticket.rs).

Working the method

• Grep the reference for the field's read sites before writing the test. The decision rule is in the reader, not the writer, and it is routinely in a different file from the one that emits the field.
• Extend gen_vectors.py rather than hand-writing expected bytes. Expected values then come from the reference's own emitter and its own decoder. Hand-written bytes encode the auditor's belief about the reference, which is the thing under test.
• Check the reference submodule's actual HEAD before auditing against it. Auditing against a remembered version produces confident findings about code that is not what we ship. The pinned commits are asserted by leviculum-lxmf/tests/reference_lock.rs.

The testing rule: pin the meaning, recomposed independently

A field is verified only when a test pins its meaning, not its encoding — and the test must recompose the expected value independently, never by calling the same helper the writer uses. A test that shares the writer's helper does not test the writer; it tests that the helper equals itself, and stays green when writer and reader drift together.

The worked example of getting this right is the announce-signature pin from the #159 audit, announce_signature_covers_reference_byte_order_on_the_wire (leviculum-core/src/destination.rs:2250). It takes the raw wire bytes of a packed announce, rebuilds the signed data in the exact order the reference composes it (Destination.py:297-298: hash + public_key + name_hash + random_hash + ratchet [+ app_data]), and verifies with raw Ed25519 against the key half at payload bytes 32..64 — then proves the pin bites by showing that dropping the destination hash from the front makes verification fail. The signature tests that existed before it could not have caught a drift: they called verify_signature, which shares build_signed_data (leviculum-core/src/announce.rs:108) with the writer, so a writer and reader that both composed the wrong bytes would have verified each other forever — exactly the #155 class, one layer up.

Where a reference value is computable offline, pin it as a known- answer test with the reference's own output (the name-hash and destination-hash KATs in the same audit tranche, destination.rs:1902).

The standing instrument: lndecode

Recomposing independently once per test is the rule; lndecode is that rule built once and reusable. It parses a raw frame into JSON from offsets re-derived out of reference/Reticulum alone, and its library links no leviculum-* crate at all — the independence is in the dependency list (lndecode/Cargo.toml), not in a promise, so a future edit cannot quietly route it back through the writer's helpers. On an announce it recomputes the identity hash, the destination hash and the Ed25519 signature from the wire bytes, which is the #159 pin's method applied to any frame instead of one fixture.

Two properties matter for the audit. It reports rather than refuses: a hop count above PATHFINDER_M, an emission timestamp holding uptime seconds (the #155 shape), a link request signalling an MTU of 3 all decode completely and land in a warnings array — a decoder that rejected adversarial frames would be useless on exactly the traffic worth reading. And it answers the signature question twice, because the permissive Ed25519 verifier the mesh applies accepts an all-zero key and an all-zero signature for some messages: signature_valid is what a peer decides, signature_strict_valid is whether that decision means anything.

Its own agreement with the writer is asserted in lndecode/tests/agrees_with_the_writer.rs, on packets leviculum-core produced rather than on hand-built bytes — an oracle nobody calibrates is just a second opinion.

Deliberate non-behaviours get pins too

When we intentionally do not do something — usually because the reference does not and doing it would desynchronise us — that non-behaviour is itself a semantic contract, and it gets a pinned test with the reference citation in the test's doc comment. A later "improvement" then breaks a test whose comment explains why the missing behaviour is deliberate, instead of silently shipping a semantic deviation. The worked examples are the two time non-behaviours — we emit our own wall clock verbatim and we do not plausibility-check incoming emission timestamps — pinned with their Destination.py/Transport.py citations; see Time and Clocks.

Where the audit stands

The systematic sweep over every generated field is Codeberg #159 — the issue, not this page, is the source of truth for its state. As of 2026-08-03 all four tranches are done: the announce layer (tranche 1, pins in leviculum-core/src/destination.rs and transport.rs), the link and resource layers (tranche 2, pins in leviculum-core/src/node/mvr_generated_field_pins.rs and the resource modules), the transport layer (tranche 3, pins in the same two files), and LXMF (tranche 4, pins in leviculum-lxmf/tests/generated_field_pins.rs and leviculum-lxmf/tests/wall_clock_producer.rs).

Tranche 2 found two fields that failed the audit and were fixed red-first: the request timestamp carried process uptime (#164) and the resource advertisement sent a content hash where the reference sends the salted per-transfer hash (#165). Tranche 3 found four routing defects (#168, #169, #170, #172). Tranche 4 found that the announced LXMF stamp cost was not clamped to the reference's 0 < cost < 255 window (#181, fixed red-first, and the origin of question 3 above), and that the LXMF crate resolved none of its wall-clock wire fields through Transport::emission_secs — it took them from a caller parameter instead (#182, fixed: the router now resolves them from the NodeCore it holds, and refuses to issue a ticket whose expiry it knows a peer will discard).

Working tranche 4 also turned the method around and asked the mirror question above, which produced two more: we refused every payload[0] that was not float64 and re-hashed the payload instead of keeping the received bytes (#183, fixed red-first, and the origin of that section), and Message::create signed NaN and ±Inf timestamps while a dozen other sites in the same crate refused them (#184, resolved by refusing on write and continuing to accept on read). Pins for both are in leviculum-lxmf/tests/foreign_payload_encodings.rs and generated_field_pins.rs, backed by VEC-MSG-FOREIGN-* vectors that record the reference decoder's own verdict.

The recurring lesson across all four: the offenders were timestamps and identifier-derivation order, never framing. Nothing that round-trips was ever wrong; everything that a peer compared against a value from another machine was worth checking — and, from #181, everything the reference deliberately declines to send, and from #183, everything the reference declines to require.

See also

• Time and Clocks — the #155 instance in full: where wall time comes from and the hardening around it.
• Python-RNS Compatibility — why the reference's decision rules, not its internals, are the contract.

Regulatory Airtime

Unlicensed LoRa bands are shared under duty-cycle rules. This page records where the limit is enforced, what a node does when nobody configured one, why no radio setting is ever refused for a regulatory reason, what it takes to switch the limit off, and one measurement pitfall. It is a durable rule for every radio firmware we write, present and future.

Enforcement belongs in the firmware, not the host

The firmware is the only place that knows what actually went on the air: retransmissions, preambles, frames queued by a host that has since crashed — none of that is visible from above. A host-side budget can shape traffic, but only the modem firmware can enforce a duty cycle, because only it stands between the queue and the antenna.

The RNode firmware is the model: it accounts every transmitted frame's airtime into rolling bins, raises airtime_lock when the short- or long-term limit is exceeded (reference/RNode_Firmware/RNode_Firmware.ino:1673-1675), and gates the transmit queue on it — if (!airtime_lock && queue_height > 0) (RNode_Firmware.ino:1624). The limits arrive from the host as CMD_ST_ALOCK / CMD_LT_ALOCK (Framing.h:36-37), but the enforcement never leaves the device.

Our LNode firmware enforces the same way: AirtimeTracker (leviculum-core/src/rnode.rs:1832) mirrors the RNode ledger, and the nRF TX path holds a queued frame instead of keying the radio while the tracker is locked (is_locked, leviculum-nrf/src/lora.rs:1902-1989), continuing to listen so RX is not starved — until the frame has waited so long that keying it would be pointless, which is the age rule below.

The host-side airtime credit bucket (leviculum-std/src/interfaces/airtime.rs, see Interface Isolation) is backpressure, not regulation: it keeps the serial queue from absorbing minutes of backlog. It is a comfort for the stack, not a legal control, and nothing may treat it as one.

Lawful by default

A node that is not told otherwise obeys the band it is on. When no airtime_limit_long is configured, the host derives the lawful long-term limit from the TX frequency (resolve_lt_alock, leviculum-std/src/driver/mod.rs:513-547) and sends it to the modem; a standalone LNode whose host never sent one derives it in the firmware from its own frequency (firmware_default_lt_alock, leviculum-core/src/rnode.rs:1638). Both read the same table, etsi_eu868_duty_cycle (leviculum-core/src/rnode.rs:1524), which carries the EU 863-870 MHz sub-bands with their 0.1 % / 1 % / 10 % duty cycles and the 433.05-434.79 MHz band at 10 %. An explicit configured value always wins — including an explicit 0, which the firmware reads as unlimited.

A cap that cannot be read back is not a cap anyone can check. The firmware states the settings it applied and the limits it loaded into the tracker on the boot-critical log path — the one that bypasses the debug port's runtime drain gate (airtime_limits, leviculum-nrf/log-line/src/facts.rs:421) — and states them again on every runtime reconfiguration. Until 2026-08 both were ordinary runtime lines: a board that came up before a reader attached dropped them with everything else, so the two facts a compliance question is actually about were the two that could never be obtained from a running board. Neither is recoverable any other way — the settings live in the radio's registers and the cap in the airtime tracker, and nothing reads either back out.

The limits line is unconditional, and it names an origin per limit. It used to be emitted only when the firmware had derived the cap itself, which left the more dangerous case silent: a host that sent an explicit 0 switched the cap off and produced no line at all, so the cap in force had to be inferred from an absence, and a board legitimately unlimited on a shielded bench read exactly like one unlimited in the field. It now carries both limits with the raw u16 and a human rendering (lt_cap=unlimited versus lt_cap=0.10% — the one confusion on this line with a legal consequence), whether each came from the host or was derived, and the lawful cap the frequency alone would give, so a host's choice can be weighed against the band without looking a sub-band up in this page. grep AIRTIME on a fresh boot answers "under what cap is this board transmitting, and who chose it".

Every row of the table has been verified against the standard text: ERC Recommendation 70-03, Annex 1, sub-bands h1.3-h1.9 for 863-870 MHz and the 433.05-434.79 MHz entry of the same annex. The duty cycle is also the only compliance route open to a fixed-frequency LNode: every sub-band's requirement reads "≤ x % duty cycle or LBT+AFA", and AFA — adaptive frequency agility, changing channel — is impossible here by construction.

One honesty note, deliberate: the table covers only the bands above. Other bands (US 902-928, AU/NZ, ...) have no citable source in this tree, so they get no auto-limit and a warning that says so — a limit invented from memory would read as authoritative to exactly the operator who most needs it not to be. Supply the citation and the table grows.

TX power follows the same lawful-by-default shape (resolve_tx_power capped by lawful_erp_dbm, leviculum-core/src/rnode.rs:1570): an absent txpower asks for the board maximum, capped by the sub-band's e.r.p. limit — 25 mW everywhere in the European SRD spectrum except 500 mW in 869.4-869.65 MHz and 10 mW in 433.05-434.79 MHz. An explicit txpower wins even above the cap (the operator may hold a licence or know the jurisdiction); the excess is logged. The narrowband bands between the wideband sub-bands (868.6-868.7 MHz and its four siblings, alarms, ≤ 25 kHz channel spacing) fit no LoRa bandwidth this stack configures, so a carrier that overlaps one is warned about by name at interface build (erp_band_gap, leviculum-core/src/rnode.rs:1513) — falling through to "no known limit, board maximum" without a word would be the most permissive outcome exactly where the operator most needs to be told. The carrier is then honoured; see No radio configuration is refused below.

Python-Reticulum does not do lawful-by-default; the cap only shapes local TX and is invisible to receivers, so this is a Priority-1 enhancement under the deviation rule.

No radio configuration is refused

Every radio setting this stack is given is honoured. A setting that looks unlawful for a region is warned about, loudly, by name — and then applied. That is project policy, decided 2026-08-16, and it supersedes the hard band-gap error this page used to describe.

Two reasons, and the second is the stronger one:

1. The jurisdiction is not knowable from here. The same carrier is lawful under a licence, in another region, on an amateur allocation, or in a shielded chamber with dummy loads. A check that reads a frequency cannot tell those apart from an unlawful deployment, so it would refuse the lawful cases too.
2. The operator is the responsible party. In the EU it is the operator, not the software author, who answers for compliant operation. Software that refuses a setting takes on a responsibility it does not hold, and hands the operator a daemon that will not start instead of the information they need. Our job is to make the consequence impossible to miss, not to make the choice.

The warning is emitted at WARN, never at debug: a decision narrated below the default log level is the silent substitution this policy exists to prevent.

What stays a refusal is anything with no regulatory content in it — the SX1262's 150-960 MHz tuning range, the ten bandwidths the modem has a register code for, the 0..=37 dBm field of the RNode wire protocol, the SF and CR ranges shared with Python-RNS, and the SoftDevice version guard that keeps a flash from bricking a board. Those are arithmetic and device protection, not paternalism: they describe what the hardware can be asked for at all, and honouring them is not a judgement about anybody's licence.

Prose alone has drifted twice here — the code once, this page once — so both halves are mechanical now. The code is pinned behaviourally by no_radio_configuration_is_refused_for_a_regulatory_reason (leviculum-std/src/driver/interface_build/mod.rs:690), which drives the known regulatory edge cases through the config-building entry point and asserts each one builds and warns at WARN, with a second half pinning the capability refusals so the first cannot be satisfied by deleting every check. This page is pinned by the_book_describes_the_band_gap_as_a_warning_never_a_refusal (leviculum-std/tests/doc_radio_policy.rs:198).

Disabling is an operator act, not a test convenience

Switching the limit off is sometimes legitimate — a shielded bench with dummy loads, a throughput scenario that cannot measure what it exists to measure at 1 % duty. But it is an operator decision with a paper trail, never a default and never a convenience:

• It requires a written justification. Periculum's [disable_airtime_lock] section refuses to parse without one (periculum/src/topology.rs:258, DisableAirtimeLockDef).
• Every run that had the limit off must say so — in its terminal output (the airtime banner prints the rendered limit per frequency, whichever route produced it) and in its result document (the measurement cell records the policy, the rendered limit, and the lawful limit for that frequency, AirtimeContext in periculum/src/bench.rs, with the source — scenario or rig — recorded in the results).

Of the three possible outcomes, a silent green under a lifted limit is the worst:

1. Red under the lawful limit is honest: the design exceeds the band's budget, and the result says exactly that.
2. Green with a declared lifted limit is honest: it measures the stack, not the law, and every reader can see which.
3. Silent green under a lifted limit is a lie with a green checkmark: it reads as evidence that the system works lawfully when it never once ran under the law. It also poisons comparisons — a figure taken with the lock off next to one taken with it on is a comparison of the lock, not of the stack — and it ships that lie forward into every document that cites the run.

Where the bench-level switch lives, and why

The blanket switch for a whole bench lives in the Periculum rig profile (rig.toml, periculum/src/rig.rs) — site data, not scenario data. Containment is a property of the site: whether the bench is shielded and on dummy loads is true of THIS rig, not of a scenario file that travels between benches and operators. A scenario that must not run unlimited even on such a bench can carry [require_airtime_lock], which wins. The mechanics are Periculum's to document; the durable rule here is only the split: scenario files describe the experiment, the rig profile describes the site, and the airtime carve-out belongs to the site.

The measurement pitfall: reading the meter restarts it

The duty-cycle history lives in RAM, and on ESP32 targets the RNode firmware's startRadio() zeroes it: it calls init_channel_stats() (RNode_Firmware.ino:523), which clears the airtime bins and both utilisation figures (reference/RNode_Firmware/Utilities.h:1858). So a diagnostic that starts (or restarts) the radio in order to read the airtime counters measures nothing — the act of taking the reading destroyed the reading. We hit this in practice.

The general lesson is not radio-specific: a diagnostic must not disturb what it measures, and a diagnostic that can must be checked for it before its numbers are believed. See Evidence and Honesty in Testing.

A hold ages traffic; it does not thin it

The gate above holds the frame at the head of the queue and re-checks. That is FIFO under a hold, and the consequence is worth stating plainly for anyone reading a LoRa capture: a duty-cycle hold does not thin traffic, it ages it. Each dip of the ledger below the cap admits exactly one frame, which re-pins the lock, so under sustained load the queue drains at the cap's rate with its order intact and the frames that reach the air are as old as the standing backlog. Nothing is lost and the airtime stays lawful — but what the lawful airtime carries is history.

Measured on the WisMesh Pocket V2 during the field test of 2026-09-27 (docs/measurements/2026-09-27-field-test-lora-chain-columba.md, outside the book because it is a measurement record, not a rule): pinned at a 10 % long-term cap, one frame left every 10–15 s and the three relayed link requests in the window were keyed 145.6 s, 137.7 s and 144.0 s after the stack handed them over. A forwarded link request is routable only until the relay's link-table entry expires, (hops + path_hops + 2) × 6 s — 30 s in that topology — so every proof came back to an entry that had died about 115 s earlier.

So the interface drops what it has held too long, at the point where it waited (Codeberg #433):

• The rule. At dequeue, while AirtimeTracker::is_locked is true, a frame whose age since the interface accepted it exceeds leviculum_queue_budget::HOLD_MAX_AGE_MS (18 s) is thrown away instead of keyed. The 18 s is derived, and the derivation is in that constant's own doc comment: it is the shortest entry any relay grants, (1 + 0 + 2) × 6 s for a one-hop request to a destination the relay reaches directly, so a frame older than that is dead on arrival in every topology; it sits above the 15 s short-term airtime window, so a lock that engaged on short-term airtime alone never loses a frame it was about to release, and below the measured field topology's 30 s entry deadline minus the measured 1.0 s return leg.
• Both stacks. lnsd driving an RNode cannot read the modem's lock, so its send queue applies the same constant against what it can see: the CMD_READY gate held shut, with frames waiting, for longer than a full frame's airtime plus one re-query interval explains (DutyHolds, in the same crate). A frame past the cap whose wait overlapped such a hold is dropped at dequeue with LORA_TX_STALE iface=<name> age_ms=<n> len=<n> held_ms=<n> and counted as tx_stale_drops (also inside tx_queue_drops), which lnstatus shows as TX stale. Frames the modem already holds age inside it, out of the host's reach.
• Only under the lock. A frame that waited for CSMA, for an acquisition-jitter draw or behind a burst gap is not stale in this sense, whatever its age: those waits are the interface's own and end by themselves. Only the regulatory lock holds a frame for minutes.
• Type-blind. The interface reads the age and never the packet, so a link request, an announce and a resource chunk of the same age get the same verdict (Interface Isolation). What makes the drop acceptable is not a judgement about the packet but the cadences above it: a link request is reissued every 6 s per hop, an announce on its own cadence, LXMF at its own layer — a frame older than 18 s behind a lock has been superseded or written off by its sender already.
• Counted, never silent. Every drop raises LORA_QUEUE_DROP reason=stale age_ms=<n> bytes=<n> total=<n> under the [LORA] prefix, rate-limited like the core's [DROP] lines with a LORA_QUEUE_DROP suppressed=<n> window_ms=<n> line for what a clipped window held back, and the running total is the lora_stale= field on the periodic [TRANSPORT] line. The counter is how the fix is read on the air: lrproof_no_link on a relay should fall toward zero for through-traffic as lora_stale rises.

What this does not do is create airtime. The cap spends the same milliseconds it spent before; the change is that they carry current traffic instead of fossils. A board that is permanently over its cap is still a board with too much to say, and the honest reading of a climbing lora_stale= is a load problem, not a solved one.

A relay in duty hold advertises no route — and the hold provably lifts

The same arithmetic binds the control plane (leviculum#493, decided on #433). A relay whose interface is in duty hold cannot carry a link setup under any stack's clocks — initiator 20 s, forwarding entry 24 s ours and 12 s Python's, against two held frames of up to 36 s — so an announce it relays there advertises a service it cannot render, and every initiator behind it spends 20 s per attempt learning that. The rule has two halves, and the second is the guard on the first:

• While the hold is in force, the interface advertises nothing. The interface reports its hold to the core as a boolean (duty_hold, mirrored like the online flag — the core computes nothing), and the core's announce admission refuses rebroadcasts and path responses alike on a held interface, logged as ANN_TX_SUPPRESSED … closed=duty_hold. The refusal is final, not queued: the destination re-announces on its own cadence, and a queue released at lift time would key routes exactly as old as the hold. The node's own announces are exempt — the #402 announce cap governs them, priced against the duty budget by #401 rule 5. Python is the precedent for the half that refuses: an interface over its announce_cap relays no announce through Transport.outbound() at that moment (Transport.py:1252-1294) — though Python queues what we refuse, which is the one place we deviate, per the stale-route argument above.
• The hold ends when the rolling window frees budget, visibly. The firmware states the edge once — [LORA] hold lifted lt_ms=<n> held_for_ms=<n> dropped_stale=<n> beside the per-turn [LORA_AIRTIME_LOCK] … holding line — and lnsd emits DUTY_HOLD iface=<name> state=held|lifted lt_ms=<n> on the same two edges. The lift is pinned by host tests on the real ledger: flat at the cap at t0 it holds, nothing inside the rolling hour frees it, and the first bin that leaves the hour drops the long-term sum below the cap and reads duty_hold false again, also when the loop was parked in a receive window across that edge (leviculum-nrf/queue-budget/src/tests.rs, and the end-to-end mvr in leviculum-std/tests/mvr/). That holds because the ledger retires every bin a call skipped, not only the bin after the current one as the reference does (RNode_Firmware.ino:688, :698): a bin no call landed on would otherwise keep an hour-old charge and hold the lock on air spent in the previous hour (leviculum#495). The wire sees none of this.

Three topologies set that boolean, and each from the layer that owns the carrier:

1. The board as a node. The firmware's own core reads the lock gate's flag (LORA_DUTY_HOLD) on every main-loop wake and mirrors it onto its LoRa interface.
2. lnsd driving an RNode. lnsd's RNode interface watches the modem's CMD_READY flow control, and a gate closure that qualifies as a hold (DutyHolds::holding) raises the flag.
3. lnsd driving an LNode over its serial protocol (leviculum#501). The board's lock gate holds, but the host's interface is a plain serial port with no flow control, so the board tells it: a DUTY_HOLD frame on the USB control envelope on each edge, and the current state behind every media report, which lnsd asks for each time the port attaches. lnsd's serial interface sets the flag from it, logs the same DUTY_HOLD line as the RNode path, and clears it when the port goes down. Before this, a relay whose modem was locked for 261 s of a 310 s run measured duty_hold=never ann_suppressed=0 on the host (497): the board knew, and the protocol between board and host had no word for it. The frame is USB protocol between our board and our host (docs/src/firmware/usb-control-envelope.md), never on the air.

A propagation node leaves half its budget to forwarding

The hold above is the end state; the second half of the same decision (leviculum#494, Lew 2026-10-07) keeps a propagation node from walking into it on its own traffic. The field relay of 2026-09-27 was a propagation node: its own sync rounds filled the lawful budget, the hold followed, and the link setups of everyone behind it died there (#433). So a board running the propagation role originates nothing once the rolling hour has spent half its long-term cap (OWN_TRAFFIC_SHARE_PERMILLE, 500, in leviculum-nrf/queue-budget/src/lib.rs). The split is by origin, and it is decided where the traffic is originated, not where it is keyed: the LoRa queue still treats every frame alike, and what the node forwards as a transport node never meets the share, so forwarding always has the other half.

The engine asks before it starts a sync round, before it identifies and offers on the round's link, before it sends the transfer the peer asked for, before an active delivery, and before it accepts an inbound offer, which past the share is answered with the reference's own postponement, ERROR_THROTTLED, on which a stock peer waits and offers again. Answers to clients (/get, upload proofs) are not its own initiative and are not gated; its announces are priced against the budget by #401 rule 5. A refusal is stated once, on its edge, as PN_YIELD reason=duty_share lt_ms=<n> cap_ms=<n> share=<permille> site=<first site>, and every site retries on its own cadence. The used figure is the LoRa task's ledger, published once per loop turn.

The firmware ledger is not a cross-session account

The same fact has a second consequence, and it is the one that decides where an hour-scale budget lives. Because a radio start clears the bins, the firmware's long-term figure covers airtime since the last radio start, not the rolling hour. It is a lower bound, and the bound is zero exactly when the question is worth asking: a harness that reboots a board to give a test a defined starting state (Periculum does, before every scenario that binds one) has zeroed it, and the daemon under test zeroes it again when it brings the radio up. An offline radio's history survives in RAM and cannot be read out-of-band at all — the only way to make the firmware emit it is the call that clears it first.

So: enforcement belongs to the firmware, but the hour-scale account belongs to whoever drives the radio. The board is the only thing that can refuse to transmit, and the only thing that cannot tell you what it transmitted an hour ago. Anything that needs to know — a test harness spacing its runs, a scheduler shaping traffic — keeps its own ledger and states plainly that the figure is modelled, not measured, and a floor rather than a total. A reset makes the board forget what it radiated; it does not make the airtime unspent.

See also

• Interface Isolation — why airtime backpressure is host-side and per-interface while airtime enforcement is firmware-side.
• Python-RNS Compatibility — the deviation rule that lawful-by-default satisfies.
• Evidence and Honesty in Testing — the wider discipline behind "say so in the output".

lnmsg: a terminal LXMF messenger

Status: design record. All ten open questions are decided.

This began as a draft for argument in which nothing was decided. Every significant decision was presented as options with trade-offs and a stated preference, and the preference was an opening position rather than a conclusion. Between 2026-08-08 and 2026-08-10 all ten questions were settled, so the document graduates from discussion to record and the remaining work is issues and batches.

The rejected alternatives are kept throughout, on all five pages. They are the why: a decision recorded without the options it beat is an assertion, and the next person to ask "why not SQLite / why not modal keys / why not a daemon" has to re-derive the argument from nothing.

• Architecture — the library it stands on, the driver seam that nearly forces the shape, process architecture, the TEA split, scriptability, and the library gaps.
• The user interface — the input model, and what honesty about delivery looks like.
• Conversation storage — SQLite, the schema, retention.
• The mailbox and who you talk to — propagation-node policy, trust, contacts and names.

1. What the program is

A terminal client for reading and sending LXMF messages over Reticulum, connected to a running lnsd or rnsd shared instance, the same way lnomad connects.

It must talk to a propagation node. A propagation node is the mailbox that holds messages addressed to a client that was not reachable. Without it, a laptop that is closed for eight hours simply does not receive mail, and the program is a toy. With it, the program is usable on hardware that is off most of the time, which is the actual deployment.

Scope explicitly excluded: hosting a propagation node. The library side of hosting has since been written: leviculum-lxmf carries both ends of the client to node exchange and the node role that stores uploads and answers /get (leviculum-lxmf/src/lib.rs:16-21, leviculum#384 part 1), and the node to node direction, peer sync and the /offer path, in its peering module (leviculum-lxmf/src/lib.rs:23-34, leviculum#384 part 2). The crate still performs no I/O, so a host owns links, resources and stamp-validation scheduling, and the two client modules lnmsg is built on keep hosting out in their own headers (leviculum-lxmf/src/router/propagation_runtime.rs:3-5, leviculum-lxmf/src/propagation_client.rs:5-8). Hosting is a separate program and a separate argument — and it now exists: the channel design record (Public channels over LXMF) reopens hosting, because the channel retrieval side only works on nodes we run.

The name

The house convention is one ln* counterpart per reference tool (Client tools, "A counterpart for every reference tool"), and the existing family is lnsd, lnstatus, lncp, lnomad. There is no single reference tool to be a counterpart of: LXMF messaging in the reference world lives inside NomadNet and Sideband, not in a standalone utility.

Decided 2026-08-10: lnmsg. Rejected: lnmail promises mail while the UI is chat (the input-model decision); lnchat promises chat while the protocol delivers mailbox behaviour on slow paths. "Message" is the only word the protocol can always honour, and lnmsg send in a cron job explains itself.

2. The ten decisions

3. Scale and honesty about hardware

This runs on machines from a Raspberry Pi upward, which sets a few hard numbers.

Memory. The whole model plus the visible window, not the whole history. lnomad's eager full-page layout (lnomad/src/tui.rs:910-934) is acceptable for a page and not for a conversation. Attachments in a byte-budgeted cache, not a count-budgeted one (lnomad/src/image_cache.rs:11-14).

Disk. SD cards die from writes. This argues against NomadNet's file-per-message plus a full .index rewrite on every change, and for a store that appends. It also argues for batching persist() rather than calling it on every PersistenceRequested, at the cost of a bounded window of loss.

CPU. Proof-of-work is the one unbounded computation in the system. On a Pi it must run off the core lock and at low priority, and the UI must be able to say "this will take a while" with a number that was measured on that class of hardware.

The core lock is the real budget. 5 ms per hook call (PROCESSOR_TICK_BUDGET, leviculum-std/src/driver/processor.rs:181), against 3.2 ms to verify a 1 MiB message's signature per The core lock budget. A messenger doing anything expensive inside the hook stalls the node's inbound path for every other client of the shared instance. Everything that is not the router's own state machine belongs on the far side of a queue.

Airtime is the scarcest resource of all. Every design choice on these pages that trades bytes for clarity — a sync poll, an announce, a read receipt we are not going to invent — is spending the one thing that cannot be bought back.

4. Compatibility constraints

Non-negotiable, per the project's first priority.

• No wire-format changes. Everything on these pages is expressible in LXMF as it is. The delivery ledger, the collision warning, the cost estimate and the mailbox screen are all local views over data the protocol already carries.
• No new fields. If threading or replies are wanted, they use FIELD_THREAD (0x08), FIELD_REPLY_TO (0x30) and FIELD_REPLY_QUOTE (0x31) with the reference's semantics (reference/LXMF/LXMF/LXMF.py:15, :23-24), not a private encoding.
• Unknown fields round-trip, as the library already guarantees (leviculum-lxmf/src/message.rs:5-8). A reply composed by us to a message from a newer client must not silently drop what we did not understand.
• Names on the wire are bytes, and we sanitise for display without altering what we forward.
• Interoperability is tested, not assumed. Per the project's test discipline, this program needs interop tests against real Python LXMF peers and a real propagation node, positive and negative, before it is called finished. leviculum-lxmf-node exists precisely to make such A/B comparisons possible with one driver (leviculum-lxmf-node/src/lib.rs:12-18), and the same trick applies here.

5. Provenance

Prior art, condensed

Two programs were read end to end before any of this was decided, and most of the arguments on the other four pages are arguments with one of them.

NomadNet. Storage is one directory per conversation named by the peer hash and one file per message named by the LXM hash, with unread and failed side-car counters and a msgpack .index that caches timestamp, state, title and the full content of every message (NomadNet's Conversation.py, lines 62-71, 120, 236, 93-109 and 944-960). Attachments are stripped out into storage/attachments/<hash>/ with a manifest and sanitised names, which is good. Everything else about the storage is not: scan_storage() does a full listdir and constructs a ConversationMessage for every file on every call, and update_message_widgets() rebuilds every widget and replaces the whole listbox on every change (Conversations.py, lines 2254-2291). NomadNet commit 7bc6911 exists specifically because calling the conversation list on every announce caused file-descriptor starvation during announce storms. There is no pruning, no paging and no search anywhere.

Its chat pane is a two-column layout with the editor in the frame footer and initial focus on it. Composition is an inline MessageEdit with a readline mixin; there is no $EDITOR integration, and send is Ctrl-D. Every command is Ctrl-modified, so plain typing always reaches the edit box, at the cost of an exhausted and context-overloaded Ctrl namespace: Ctrl-X is "delete conversation" in the list and "clear history" in the body, Ctrl-U is "ingest URI" and "purge failed", Ctrl-P is "my QR" and "paper message". Delivery state is glyph and colour only: the distinction between SENT, DELIVERED and propagated-SENT genuinely exists and gets three different styles, but it is never stated in words, and propagated shares a style with paper messages. Two honest touches: signature failure is rendered in plain English ("Unknown Origin", "Invalid Signature"), and on load a message stuck mid-flight that is no longer in the router's pending set is forced to FAILED.

Identity handling is where NomadNet is genuinely ahead of everything else: four trust levels with real UI consequences, and, uniquely, duplicate display names raise WARNING. Notification is a terminal bell, literally sys.stdout.write("\a").

columba. A Room database, fifteen entities, and two schema decisions worth taking. Every row is scoped by identityHash with composite primary and foreign keys, so multiple local identities coexist with cascading isolation. And receivedAt (local clock) is stored separately from timestamp (sender clock), with sorting on COALESCE(receivedAt, timestamp) and an explicit comment that this is immune to sender clock skew. NomadNet has the same problem and solves it worse, as a user-toggled sort mode on Ctrl-O. Paging3 with a DESC query and a reversed layout is the right answer to NomadNet's rebuild-everything problem.

Its propagation handling adds three things NomadNet lacks: a user-configurable sync interval, real failover to an alternative relay when one dies, and a structured SyncResult / SyncProgress sum type where manual syncs report loudly and periodic ones stay silent. The relay is modelled as a contact with an isMyRelay flag, which is a nice way to make the relationship visible. Contact status is a persisted enum — ACTIVE, PENDING_IDENTITY, UNRESOLVED — rather than a live key lookup, and name resolution has a documented precedence: in-memory cache, then the user's own nickname, then the announced name, then the stored conversation name. User nickname beating announced name is exactly right.

What columba gets wrong: it has no trust model at all. A search for trustLevel / isTrusted across its app, domain and data modules returns nothing outside tests, there is no duplicate-name detection, and consequently no trust gate on relay auto-selection. It will happily adopt the nearest stranger's relay. Its delivery display also collapses sent and propagated into the same single check mark, which is precisely the distinction that matters most on a delay-tolerant network. Its per-message detail screen, showing delivery method with a one-sentence explanation plus hop count, interface, RSSI and SNR, is the best idea in either program and is trivial to do in a terminal.

Neither program prunes history.

The citation convention on these pages

Claims about existing code carry file:line. Where something could not be verified, it says so.

In-tree citations were re-pinned against this tree when the concept was promoted (2026-08-10); the draft had been written days earlier and the leviculum-lxmf crate had moved substantially under it. The citation guard (leviculum-std/tests/doc_citations.rs) resolves every one of them.

Claims about the vendored references use the same form under reference/, for example reference/LXMF/LXMF/LXMRouter.py:38, which is what every other page in this book does.

NomadNet and columba are not vendored here and are not in this repo, so the guard cannot resolve a citation into either and would report one as a file that had been deleted or renamed. Their line references are therefore written with the file name backticked and the lines outside it — NomadNet's Conversation.py, lines 62-71 — which says exactly as much and does not claim a path this tree holds. Every such reference names NomadNet or columba in the same sentence, so a reader always knows which tree to open.

lnmsg: architecture

Part of the lnmsg design record. This page carries the ground truth the design stands on — lnomad and leviculum-lxmf — the driver seam that nearly forces the architecture, the process and event-loop decisions, scriptability, and the triage of what the library does not yet expose.

1. lnomad, and one correction to the premise

lnomad is described as supporting "Emacs keybindings, vi keybindings, Firefox keybindings and Firefox mouse behaviour, all at the same time". That is the observable behaviour, but it is not implemented as four schemes. It is one keymap with three resolution mechanisms, and only one of them is table-driven.

What is table-driven. SCROLL_KEYS (lnomad/src/tui.rs:3159-3291) is a static table of ScrollKey { keys, desc, chords } where each ScrollChord { code, mods, cmd } carries a modifier class (ScrollMods::{Any, Plain, Ctrl, Alt}, lnomad/src/tui.rs:3128-3135). One row carries the vi and the emacs and the arrow spelling of the same motion side by side:

#![allow(unused)]
fn main() {
keys: "j / k   ↓ / ↑   Ctrl-n / Ctrl-p",   // lnomad/src/tui.rs:3161
desc: "scroll a line",
}

Resolution is a linear scan, first match wins (key_to_scroll, lnomad/src/tui.rs:3293-3311). The table is read by both the key handler and the help overlay (lnomad/src/tui.rs:4669-4680), and the doc comment says that is deliberate: "the SINGLE source of truth read by BOTH" (lnomad/src/tui.rs:3147-3151).

What is not. Everything else is a hand-written if-chain in update_browse_key (lnomad/src/tui.rs:1810-1957): roughly twenty sequential if key.code == ... { return ...; } statements. There is no binding map, no user-configurable keymap, no keybinding config file. The help overlay's non-scroll groups are a second, unlinked static list (lnomad/src/tui.rs:4687-4788) that can silently drift from the handler.

How the conflicts are actually resolved. Three layers, in this order.

1. Global escapes, before any mode dispatch (update_key, lnomad/src/tui.rs:1566-1606): any key dismisses the toast; Ctrl-C quits from anywhere; an open help overlay swallows everything; an open places panel takes over.
2. Mode gating. Mode::{Browse, Address, Hint, Search, Field} (lnomad/src/tui.rs:292-311), each with its own handler. Text modes forward unclaimed keys to a tui_input::Input editor. Mode::Field uses a whitelist rather than a catch-all so that "field editing never leaks into browse hotkeys" (lnomad/src/tui.rs:1614, whitelist at :1643-1652).
3. Modifier discrimination. Nearly every single-letter binding is guarded && !ctrl && !alt, which is what lets f (hint mode) and Ctrl-f (page down), d (places) and Ctrl-d (half page), n (next match) and Ctrl-n (line down), g (top) and Ctrl-g (cancel) all coexist.

The ordering is load-bearing. In browse mode key_to_scroll is consulted last (lnomad/src/tui.rs:1951-1954), so single-letter commands claim their keys first and j/k/Space reach the scroll table only because nothing above claims them. In the places panel the order is inverted (lnomad/src/tui.rs:2145) with a comment explaining why: there Ctrl-d must be a half-page motion, not the d that closes the panel.

There is one further principle worth carrying over verbatim. Bare r is deliberately left unbound, because "a mesh reload is expensive and single letters are reserved for cheap local actions" (lnomad/src/tui.rs:1930-1933); reload requires R, Ctrl-R or F5. That is a cost-aware keymap, and a messenger sends over the same radios.

Architecture. Elm-style with an explicit effect list, all in lnomad/src/tui.rs: Model at :680-838 (#[derive(Clone, Debug, Default)] at :679), AppEvent at :1197-1264, Effect at :592-646, update(&mut Model, AppEvent) -> Vec<Effect> at :1271-1381, view(&Model, &ImageStore, &mut Frame) at :3532-3571, and a single effect interpreter run_effects at :5783-5889. update mutates rather than returning a new model, and effects are plain data, not closures. That combination is what makes the 245 in-file unit tests possible: build a Model, feed a synthetic AppEvent::Key, assert on the model and on the returned Vec<Effect>, with no IO anywhere (lnomad/src/tui.rs:6228 onwards; helpers at :6238-6251). The view is tested against ratatui::backend::TestBackend (:6232, :7055), and the --print path has byte-identical golden files (lnomad/tests/render_golden.rs:18-37).

Unsolicited inbound events already exist. This matters more than anything else for a messenger, and the answer is yes. AppEvent::NodeDiscovered (lnomad/src/tui.rs:1264) arrives from announces with no user action. The chain is: an announce sink installed before the session is shared so nothing is missed at startup (set_announce_sink, lnomad/src/fetch.rs:225-227, wiring comment at lnomad/src/tui.rs:5995-5998), a non-blocking unbounded send on every recorded announce (note_announce, lnomad/src/fetch.rs:369-389), a dedicated background task parked on the shared session in 250 ms lock slices (spawn_discovery, lnomad/src/tui.rs:5721-5762), and a tokio::select! arm that folds the result into the model (lnomad/src/tui.rs:6154-6156). The main loop has five arms (lnomad/src/tui.rs:6058-6161), and the timer arm is conditionally enabled (, if animate at :6157, driven by needs_tick() at :1018-1021) so an idle browser does not wake eight times a second.

Persistence. Three small files under ${XDG_CONFIG_HOME:-~/.config}/lnomad/: bookmarks.toml, identify.toml, and a binary identity. Everything else is RAM. The write path is fs::write with no atomic rename, no fsync, and errors deliberately ignored (lnomad/src/bookmarks.rs:124-130, effect handler at lnomad/src/tui.rs:5879-5885), and load treats corrupt exactly like missing (lnomad/src/bookmarks.rs:116-121). For bookmarks that is a defensible trade. For a message store it is data loss.

load_or_create (lnomad/src/identity.rs:39-53) silently mints a fresh identity when the stored one fails to decode. For a browser, whose identity is disposable, that is right. For a messenger, whose identity is the user's address, silently replacing it breaks every contact's address book with no warning. That default must be inverted.

Two caches worth copying. The page cache stores the parsed document rather than the laid-out page, because layout depends on width and theme (lnomad/src/page_cache.rs:10-13). The image cache is bounded by bytes rather than count, and the reasoning generalises directly to attachments: "a cache of 'the last fifty pictures' says nothing about how much memory a browser is holding, and pictures differ in size by three orders of magnitude" (lnomad/src/image_cache.rs:11-14).

Rendering. One layout core, two sinks. layout_blocks (lnomad/src/render.rs:192-217) produces Vec<RLine> where RLine is a vector of StyledChar { ch, st, link, field } (lnomad/src/render.rs:340-361): already wrapped, aligned and indented, one RLine per output row, every cell carrying its resolved style and its owning link index. That IR feeds either to_ratatui_text (lnomad/src/tui.rs:5143-5162) for the TUI or emit_ansi (lnomad/src/render.rs:224-231) for --print. Scrolling is a slice, not a widget scroll, because the page is pre-wrapped (lnomad/src/tui.rs:3782-3789), and there is one scroll rule shared by every scrollable window (scrolled, lnomad/src/tui.rs:274-289).

Two rendering caveats. Wrapping compares cur.len() > width, i.e. character count rather than display width (wrap, lnomad/src/render.rs:848-875), which will overflow on CJK and emoji. No test covering that was found, so whether it is a known limitation or an oversight is unclear. And the whole page is laid out eagerly on every relayout (lnomad/src/tui.rs:910-934), including on every keystroke in a form field (:1657-1660).

Scriptability, and the absence of settings. --print fetches, renders and prints once (print_once, lnomad/src/browser.rs:133-141). Output is raw ANSI page text and nothing else: no link markers, no legend, and with --no-color links are indistinguishable from body text (lnomad/src/render.rs:143-146). There is no JSON output anywhere in the crate: serde_json is not a dependency. Non-interactive detection is automatic: interactive = !args.print && stdin().is_terminal() && stdout().is_terminal() (lnomad/src/main.rs:167-168), so piping never blocks on the UI. Exit codes: 0 success, 1 operational failure, 2 argument or URL error (lnomad/src/main.rs:174, :188, :222, :238).

lnomad has no settings file at all. --config points at the Reticulum config directory; the lnomad/ directory holds only data. The theme is auto-detected via OSC 11 before raw mode is entered (lnomad/src/tui.rs:5956-5963) and toggled at runtime with t; theme colours are hard-coded (lnomad/src/theme.rs:112-193).

The handoff that already exists. lnomad recognises lxmf@<hash> links, and because it has no composer it copies the address to the clipboard and says so in a toast (follow_link, lnomad/src/tui.rs:2768-2777). The messenger is the natural target of that handoff, and wiring the two together is an explicit goal.

2. leviculum-lxmf: what it gives and what it does not

Three layers, all sans-IO: NodeCore (Reticulum transport, owned by the app), LxmfNode (leviculum-lxmf/src/node.rs:375, the lxmf.delivery destination adapter), and LxmfRouter (leviculum-lxmf/src/router.rs:461, the queue, retry scheduler, stamp and ticket policy, dedup caches and propagation client). The application builds on LxmfRouter and owns both it and the core; the router never owns the core, every method takes it as a parameter.

Note that LxmfRouter, RouterEvent, RouterOutput, RouterConfig and MessageState are not re-exported at the crate root — the crate root exports only BuiltResource, DeliveryStampRequest, InboundStampRequest, PendingResourceBuild and PropagationStampRequest from that module (leviculum-lxmf/src/lib.rs:97-100) — so they are reachable as leviculum_lxmf::router::* only.

Events are return values, not a channel

#![allow(unused)]
fn main() {
#[must_use]
pub struct RouterOutput {          // leviculum-lxmf/src/router.rs:300-303
    pub core: TickOutput,
    pub events: Vec<RouterEvent>,
}
}

Every router method that can produce work returns this. There is no callback and no channel. The library never drops an event, but it never retains one either: if the application drops a RouterOutput, those events are gone. #[must_use] on both RouterOutput and TickOutput (leviculum-core/src/transport.rs:534) is the only safety net, and TickOutput's own doc says dropping it "silently loses outbound packets and application events" (leviculum-core/src/transport.rs:498-500).

There is a re-entrancy obligation that is easy to miss and fatal to get wrong: RouterOutput.core.events contains NodeEvents that must be fed back into router.handle_event(), recursively, until the worklist drains. This is exactly Codeberg #204's subject. leviculum-lxmf-node implements it with a bounded worklist and says why the bound is the consumer's choice (MAX_ABSORB_ROUNDS, leviculum-lxmf-node/src/processor.rs:82-92, absorb at :392-394). A client that forgets this will silently never see incoming messages.

RouterEvent

Fifteen variants (leviculum-lxmf/src/router.rs:294-342): MessageQueued, MessageState { message_id, state }, MessageReceived, InboundRejected, DirectLinkEstablished, Duplicate, InvalidSignature, InvalidStamp, ResourceBuildPending, StampPending, InboundStampPending, PropagationStampPending, PropagationSyncState, PropagationSyncComplete, PersistenceRequested.

What is missing is as informative as what is there. There is no announce event: LxmfNodeEvent::PeerAnnounced carries the destination hash only, with app data discarded (leviculum-lxmf/src/node.rs:133-135, :746-754), and handle_node_event does not forward it at all — it falls into _ => {} (leviculum-lxmf/src/router.rs:1369). The router does decode the delivery announce but keeps only stamp_cost and compression_supported, discarding the display name (leviculum-lxmf/src/router.rs:1209-1219). Display-name learning is entirely the client's job, from raw NodeEvent::AnnounceReceived.

Sending does arrive, on the event every verdict travels on: RouterEvent::MessageState, from all three sites that enter the state — the composed send (leviculum-lxmf/src/router.rs:1832-1837), the built-transfer commit (leviculum-lxmf/src/router.rs:1033-1038) and the upload the transport reports through UploadSubmitted (leviculum-lxmf/src/router/propagation_runtime.rs:354-366) — and on the transition only: a submission onto an entry already in that state reports nothing. For a direct delivery it is the only thing between being accepted and being answered. For a propagated one it names the message on a link PropagationSyncState was already narrating, which narrates the link and cannot say what is on it. An opportunistic message reports it and then goes quiet until the verdict: the router moves it on to Sent in the same tick, and that transition is reported nowhere.

There is still no event for Outbound and none for progress: the router folds LxmfNodeEvent::Progress into OutboundEntry::progress without emitting anything (leviculum-lxmf/src/router.rs:1421-1433), so progress must be polled through outbound() (leviculum-lxmf/src/router.rs:701).

MessageState and what it honestly means

#![allow(unused)]
fn main() {
pub enum MessageState {          // leviculum-lxmf/src/router.rs:62-71
    Generating = 0x00, Outbound = 0x01, Sending = 0x02, Sent = 0x04,
    Delivered = 0x08, Rejected = 0xfd, Cancelled = 0xfe, Failed = 0xff,
}
}

Discriminants are the Python LXMessage constants. Four traps:

1. Generating is dead. It is only ever produced by snapshot decoding (leviculum-lxmf/src/router.rs:2356); nothing assigns it.
2. Sent means two different things and never applies to direct delivery. For opportunistic messages it means the packet was handed to Reticulum unproven, and the message is still queued and still retryable (leviculum-lxmf/src/router.rs:1327-1341). For propagated messages it means the propagation node accepted the upload, and the entry is deleted (leviculum-lxmf/src/router/propagation_runtime.rs:386-393). Direct delivery goes Outbound -> Sending -> Delivered | Rejected | Failed and never passes through Sent, because the Submitted handler matches only DeliveryMethod::Opportunistic (leviculum-lxmf/src/router.rs:1403-1407).
3. Delivered is a Reticulum transport proof, not an application receipt. It comes from PacketDeliveryConfirmed / LinkDeliveryConfirmed (leviculum-lxmf/src/node.rs:1282-1304) or from ResourceCompleted { is_sender: true } (leviculum-lxmf/src/node.rs:1098-1109). It proves the bytes arrived at the destination identity. It does not prove an LXMF client parsed them and it certainly does not prove a human read them. There is no read-receipt field in LXMF at all (leviculum-lxmf/src/constants.rs:52-78).
4. Rejected is ambiguous. It means either "the receiver cancelled the Resource transfer" (leviculum-lxmf/src/router.rs:1285-1298) or "the propagation node refused the upload for an insufficient stamp" (leviculum-lxmf/src/router/propagation_runtime.rs:418-430), and the event alone cannot distinguish them.

And one omission that shapes the whole UI: there is no "propagated but not yet collected" state. A propagated message reaches Sent, its queue entry is removed, and from then on it is indistinguishable from a message that vanished.

Terminal states remove the entry from the outbound map (remove_outbound, leviculum-lxmf/src/router.rs:873-876; call sites at :888, :1334, :1369 and five in the propagation runtime, among them leviculum-lxmf/src/router/propagation_runtime.rs:895). If the client does not capture the Message at enqueue time it cannot render its own sent message afterwards, and it cannot offer a retry button. MAX_DELIVERY_ATTEMPTS is 5 (leviculum-lxmf/src/router.rs:47).

Propagation: what the router does, and what it refuses to do

Setup requires the client to mint a second lxmf.propagation destination via PropagationTransport::destination (leviculum-lxmf/src/propagation_client.rs:282-292), register it, and hand it to enable_propagation_client (leviculum-lxmf/src/router.rs:603); the transport identity must equal the router's or you get RouterError::IdentityMismatch (leviculum-lxmf/src/router.rs:608-610).

Node discovery is automatic from announces (remember_announce, leviculum-lxmf/src/propagation_client.rs:384-400, driven from the announce arm at :733-742), and the decoded announce carries enabled, transfer_limit_kb, sync_limit_kb, stamp_cost, peering_cost and metadata (PropagationNodeAnnounce, leviculum-lxmf/src/propagation.rs:513-525), all of which are directly displayable. select_outbound_propagation_node with None auto-ranks by route, hops, peering cost and stamp cost (leviculum-lxmf/src/router/propagation_runtime.rs:1161-1196).

Once a sync starts, everything is automatic: path request, link, identify, list request, want/have partitioning, download, acknowledge and purge (begin_list_request, leviculum-lxmf/src/router/propagation_runtime.rs:459-551). The observable state machine is PropagationClientState (leviculum-lxmf/src/router/propagation_runtime.rs:60-75), wire-compatible with Python's PR_* constants: Idle, PathRequested, LinkEstablishing, LinkEstablished, RequestSent, Receiving, ResponseReceived, Complete, NoPath, LinkFailed, TransferFailed, NoIdentity, NoAccess, Failed. ResponseReceived is never assigned in practice. There is automatic failover to another reachable node when the selected one loses its route (leviculum-lxmf/src/router/propagation_runtime.rs:825-846).

What the router will not do:

• It never schedules a sync. request_messages_from_propagation_node (leviculum-lxmf/src/router/propagation_runtime.rs:1365) must be called by the application every time. PropagationClientConfig has three fields and none of them is an interval (leviculum-lxmf/src/router/propagation_runtime.rs:35-45), and next_deadline() returns None in every state except PathRequested (leviculum-lxmf/src/router/propagation_runtime.rs:1142-1148).
• It does not persist known propagation nodes. They live in an in-memory map (known_nodes, leviculum-lxmf/src/propagation_client.rs:267) and are absent from the router snapshot (snapshot, leviculum-lxmf/src/router.rs:2069-2086). The client must persist and replay them via restore_known_propagation_node (leviculum-lxmf/src/router/propagation_runtime.rs:1317). The selected node is not snapshotted either.
• It does not clamp the transfer limit against the node's advertised one. The download request carries the local delivery_transfer_limit_kb (default 1000) regardless of what the node announced (leviculum-lxmf/src/router/propagation_runtime.rs:533-538).

Default retain_synced_on_node is false (leviculum-lxmf/src/router/propagation_runtime.rs:50), meaning the client tells the node to purge what it has collected. That is a user-visible policy decision disguised as a config default, and the mailbox page argues it should be surfaced.

The reference holds messages for MESSAGE_EXPIRY = 30*24*60*60, i.e. thirty days (reference/LXMF/LXMF/LXMRouter.py:38).

Storage is a bare key/value trait

#![allow(unused)]
fn main() {
pub trait LxmfStorage {          // leviculum-lxmf/src/storage.rs:18-26
    fn load(&self, key: &[u8]) -> Result<Option<Vec<u8>>, StorageError>;
    fn store(&mut self, key: &[u8], value: &[u8]) -> Result<(), StorageError>;
    fn remove(&mut self, key: &[u8]) -> Result<(), StorageError>;
    fn keys(&self, prefix: &[u8]) -> Result<Vec<Vec<u8>>, StorageError>;
    fn flush(&mut self) -> Result<(), StorageError> { Ok(()) }
}
}

There is no conversation, thread, contact or history concept in it. Two implementations exist, both in that file: MemoryLxmfStorage (leviculum-lxmf/src/storage.rs:42) and NoLxmfStorage (leviculum-lxmf/src/storage.rs:116). The file-backed one is FileLxmfStorage (leviculum-std/src/file_lxmf_store.rs:27), in the std crate because the LXMF crate is no_std.

The router writes exactly one key, b"lxmf/router-state" (ROUTER_STATE_KEY, leviculum-lxmf/src/router.rs:64), holding the outbound queue, delivered and processed ID windows, stamp costs, tickets and the ignore set (leviculum-lxmf/src/router.rs:2069-2086). A client should stay off the lxmf/ prefix and is otherwise free.

Restore resets every queued message to Outbound with next_attempt_ms = 0 and progress = 0.01 (leviculum-lxmf/src/router.rs:2054-2057), because in-flight correlation is expressed in a process-local monotonic clock that does not survive a restart. A UI therefore cannot show a stable "sending" progress across restarts, and must not pretend to.

Features a UI could surface

• Attachments (leviculum-lxmf/src/attachments.rs): files, one image, one audio clip, as MessageAttachments::into_fields() (leviculum-lxmf/src/attachments.rs:57) / from_fields() (leviculum-lxmf/src/attachments.rs:86). Attachments are inline bytes in the message, so anything with a real attachment exceeds the packet MDU and forces link or Resource delivery (representation, leviculum-lxmf/src/node.rs:577-605).
• Paper messages (leviculum-lxmf/src/paper.rs): a message encrypted to a destination and rendered as an lxm:// base64 URI (to_uri, leviculum-lxmf/src/paper.rs:172), capped at PAPER_MDU = 2210 bytes (leviculum-lxmf/src/constants.rs:38). Ingest via router.ingest_paper(uri) (ingest_paper, leviculum-lxmf/src/router/paper_runtime.rs:17). No QR generation exists; that is the client's job.
• Tickets (leviculum-lxmf/src/ticket.rs): a 16-byte secret you issue to a contact so their future messages skip proof-of-work. Mostly invisible and automatic: received tickets are remembered from any signature-valid inbound message — remember_verified_ticket (leviculum-lxmf/src/router.rs:1512) — and applied when a message is enqueued (leviculum-lxmf/src/router.rs:820). Expiry 21 days, renew at 14, minimum one day between issuances to the same peer (leviculum-lxmf/src/constants.rs:40-43). issue_ticket_field refuses with RouterError::NoWallClock when the node's clock is implausible (leviculum-lxmf/src/router.rs:681-682), and can also legitimately return Ok((None, _)) when rate-limited (leviculum-lxmf/src/router.rs:699). A UI has to distinguish "granted", "not yet, try tomorrow" and "cannot, no clock".
• Stamps (leviculum-lxmf/src/stamp.rs): proof-of-work over the message ID, cost being required leading zero bits, so expected work is 2^cost hashes plus a workblock expansion of 3000 rounds (WORKBLOCK_EXPAND_ROUNDS, leviculum-lxmf/src/constants.rs:45). Costs above about 40 bits are described in-tree as "already unreachable in practice" (leviculum-lxmf/src/router.rs:1145-1146). No wall-clock benchmark exists in the crate and none was run for this document, so any UI estimate of mining time must be measured first, not guessed. There is no cancellation and no deadline: generate loops until it succeeds (leviculum-lxmf/src/stamp.rs:356-367), and StampError::Cancelled exists but is never constructed (leviculum-lxmf/src/stamp.rs:25).

Fields with constants but no codec

leviculum-lxmf/src/constants.rs:52-78 declares the full LXMF field set including FIELD_THREAD (0x08), FIELD_RENDERER (0x0F), FIELD_REPLY_TO (0x30), FIELD_REPLY_QUOTE (0x31), FIELD_REACTION (0x40) and FIELD_COMMENT (0x41), but only files, image and audio have typed codecs. Unknown fields round-trip byte-for-byte (leviculum-lxmf/src/message.rs:5-8), so nothing is lost, but a client wanting replies, threads, reactions or renderer-aware display must hand-roll the msgpack via the exported msgpack module.

RENDERER_MICRON = 0x01 (reference/LXMF/LXMF/LXMF.py:100) is interesting here: leviculum-micron already parses micron into a document model (leviculum-micron/src/lib.rs:25-27) and lnomad already renders that model. A messenger in this workspace can honour FIELD_RENDERER almost for free, which no other terminal LXMF client does.

3. The driver seam, which nearly forces the architecture

An LXMF client cannot be fed from leviculum-std's public event stream. The reason is documented at the seam itself: the tap sits on output.events inside dispatch_output, before the event sink classifies, and seven of the event types LXMF needs, including PacketReceived and LinkDataReceived, are EventClass::Data and therefore droppable under load. A processor fed from take_event_receiver "would silently lose inbound messages with nothing underneath to retransmit them" (leviculum-std/src/driver/processor.rs:191-199, "Where the events come from").

So the messenger must register a CoreProcessor (leviculum-std/src/driver/processor.rs:274-302) on the builder, and the LXMF router lives inside the driver's tick, under the core mutex. That carries hard obligations:

• Both hooks run with a non-reentrant mutex held. The processor may not own a handle to the node it runs inside; roughly forty synchronous pub fns on ReticulumNode open with a lock and one of them in a hook body deadlocks the node in ordinary safe code.
• Every side effect must be a non-blocking queue push. leviculum-lxmf-node does exactly this: stdout lines, stderr lines, proof-of-work jobs and shutdown are all channel sends (leviculum-lxmf-node/src/processor.rs:15-30).
• PROCESSOR_TICK_BUDGET is 5 ms per hook call (leviculum-std/src/driver/processor.rs:181), reported rather than enforced. Message packing costs about 0.8 ms and unpacking with signature verification about 3.2 ms for 1 MiB, per The core lock budget. NodeCore::send_resource (leviculum-core/src/node/mod.rs:1747) must not be called from a hook: 141 ms under the lock for 1 MiB.
• The processor needs its own periodic slot to drain its command queue, because an event tap can never initiate anything. leviculum-lxmf-node uses 200 ms (POLL_INTERVAL_MS, leviculum-lxmf-node/src/processor.rs:80).

This is a strong constraint and a gift at the same time: it means the "model" that talks to the network is a synchronous state machine with a queue on either side, which is exactly the shape that tests well.

4. Decision: process architecture

Options

A. One process. TUI plus an in-driver CoreProcessor. The binary builds a ReticulumNode as a shared-instance client with core_processor(...) installed, exactly as leviculum-lxmf-node does (leviculum-lxmf-node/src/main.rs:384-390). The processor owns the LxmfRouter; the TUI owns the model. They talk over two unbounded channels.

For: one binary, one config, no IPC to design, matches lnomad's deployment shape. Against: mail is only received while the TUI is running. Closing the terminal stops collecting.

B. Two processes. A headless daemon plus a thin TUI client. A lnmsgd holds the router and the store and exposes a local socket; the TUI is a view onto it. For: mail arrives while the UI is closed, several front ends can attach, and the store has one writer. Against: an entire IPC protocol, a second daemon on a system that already runs lnsd, and a second thing to package and supervise.

C. One binary, two modes. lnmsg with a --daemon flag, and the TUI attaching to a running daemon if there is one and otherwise running the router itself. For: option A's simplicity on day one, option B's availability when the user asks for it. Against: two code paths for every operation, and the temptation to test only one.

Decision (2026-08-08)

C, built as A first. Start with a single process, but put the router and the store behind an interface from the beginning so that the daemon mode is a wiring change rather than a rewrite. Whether the daemon mode is ever built is decided empirically: if syncing with a propagation node on start plus every N minutes proves sufficient in the mesh we care about, A alone stays. The reference retention default of thirty days (reference/LXMF/LXMF/LXMRouter.py:38) suggests it might. This aligns with the standing decision that propagation nodes, not client uptime, are the answer to offline delivery.

The lnsd-resident variant — daemon mode as a CoreProcessor registered inside lnsd — is rejected, twice over: it would put LXMF knowledge into the transport daemon, which the Codeberg #196 seam was explicitly designed to avoid, and it contradicts the standing rule that client programs do not merge into lnsd (there will be more clients than this one).

Requirement: the core must not know it has a terminal

Decided 2026-08-08, and binding for lnomad too: the messenger will grow other frontends on other platforms later — a GUI is expected — and that must be a frontend swap, not a rework.

Concretely, the crate splits into two layers with a hard boundary:

• lnmsg-core (or a module boundary with the same discipline until a crate split is warranted): the model, update, effects, the store, the router glue, sync scheduling, trust, delivery bookkeeping. This layer never imports crossterm, ratatui, or any terminal type. Everything in it is driven by AppEvent in and Effect out, and is testable headless.
• The TUI frontend: rendering, key mapping, terminal lifecycle. It translates terminal events into AppEvents and draws the model. A GUI frontend later is a second translator and a second renderer over the same core — no change to the core's types.

The TEA split below is what makes this cheap: the discipline is not a new architecture, it is refusing to let the existing one leak. The test for the boundary is mechanical and should exist from day one: the core compiles without the TUI dependency tree (feature gate or crate split), and the headless test suite drives complete user stories through AppEvents alone.

For lnomad the same requirement holds as a future refactor: its TEA split already keeps the model headless-testable, but model, update and view live in one 11,873-line file with crossterm types reachable throughout. When lnomad next gets substantial work, the same core/frontend boundary is carved there. Tracked as its own issue, not as part of this program.

5. Decision: the event loop and the TEA split

lnomad's split survives contact with a messenger with one change.

The shape that follows from the driver seam is three layers, not two:

  crossterm events ──┐
  router events    ──┼──> AppEvent ──> update(&mut Model) ──> Vec<Effect>
  timer            ──┘                                              │
                                                                    v
                                                            run_effects
                                                                    │
                                          Command queue ────────────┘
                                                    │
                                                    v
                              CoreProcessor::on_tick / on_event
                                (LxmfRouter, under the core lock)
                                                    │
                                          RouterEvent queue
                                                    │
                                                    └──> AppEvent

The processor is not part of the TEA model. It is a second, synchronous state machine on the far side of two queues, and it is testable on its own terms without a terminal, exactly as leviculum-lxmf-node is.

Three specific things lnomad does that must change:

1. Bottom-anchored scrolling with a pinned flag. lnomad's scroll is the index of the top visible line (lnomad/src/tui.rs:274-289). A message list wants a "pinned to bottom" boolean so an inbound message appends without yanking the viewport out from under a user who has scrolled up. NomadNet gets this wrong: it resets to the bottom on every refresh (NomadNet's Conversations.py, line 2287).
2. Windowed layout. lnomad re-lays out the whole page on every relayout (lnomad/src/tui.rs:910-934). A ten-thousand-message conversation must not do that, and a compose buffer must not trigger it per keystroke. Lay out the visible window plus a margin, and cache per message keyed by (message_id, width, theme).
3. The timer must run. lnomad disables its tick when idle (lnomad/src/tui.rs:6157). A messenger has relative timestamps, a sync schedule and retry deadlines. A one-second tick when there is anything pending, and a slower one otherwise, driven by next_deadline() (leviculum-lxmf/src/router.rs:2000).

Things to carry over unchanged: the generation counter for stale-result rejection (spawn_fetch, lnomad/src/tui.rs:5305-5346), the tick-counted toast whose expiry is a pure function and therefore unit-testable without real time passing (Toast, lnomad/src/tui.rs:661-676, test at :7271), the TerminalGuard RAII plus panic hook that restores the terminal before the backtrace prints (lnomad/src/tui.rs:5229-5273), and OSC 52 for the clipboard so copy works over SSH with no X11 dependency (osc52, lnomad/src/tui.rs:2519-2551).

One thing to fix from day one: lnomad is 11,873 lines in src/tui.rs. A messenger has strictly more state. Split model.rs / event.rs / update/ / view/ / shell.rs before the first thousand lines, not after the tenth.

6. Decision: scriptability

lnomad's --print prints rendered ANSI and nothing machine-readable (lnomad/src/render.rs:143-146); there is no JSON anywhere in the crate. For a browser that is defensible. For a messenger it is a missed opportunity: "send me a message when the backup finishes" is a real use and needs no UI at all.

Non-interactive subcommands from the start, following lnomad's automatic non-tty detection (lnomad/src/main.rs:167-168) and its exit-code convention (0, 1, 2):

lnmsg send <address> [--title T] [--from NAME] [--attach F] [--via direct|propagated] [-]
lnmsg read [--conversation A] [--since T] [--unread] [--json]
lnmsg sync [--json]
lnmsg contacts [--json]
lnmsg paper <address> -           # emit an lxm:// URI
lnmsg ingest <lxm://...>

with --json producing one object per line so jq works, and the exit code distinguishing "sent" from "queued but not confirmed", which a script genuinely needs to know.

Decision (2026-08-10): send returns immediately with the message ID on stdout; exit 0 means "queued cleanly" and claims nothing more, so it never lies. lnmsg status <id> answers at any time (state, ledger, --json). --wait opts into blocking until the delivery proof, with a configurable timeout, and its exit codes distinguish delivered / still-pending-at-timeout / terminally-failed — a timeout is not reported as a failure, because the message may still arrive. Rationale: the common case is a script that must not hang, and enqueueing is the only operation whose success is knowable immediately; everything after it is a history, not a result.

Amended (2026-08-21): the message ID comes off stdout. A successful lnmsg send now prints nothing at all and exits 0; errors keep going to stderr. The ID is not interesting to the person running the command, and saying nothing on success is the ordinary Unix contract — a cron job that mails its output should mail nothing when the send worked. The rest of this decision is untouched: exit 0 still means "queued cleanly" and claims nothing about delivery, and that is now the entire success signal, which is why the exit code is what the tests assert. The ID does not become unobtainable, because lnmsg status <id> needs it: LNMSG_ENQUEUED … id=… carries it into the structured event log, which LEVICULUM_EVENT_LOG=<path> turns on and which is written by an unfiltered layer, so the line arrives even at the warn default (leviculum-std/src/event_log.rs:644-651). No --print-id flag was added: nothing consumes the ID today, and an option added against a hypothetical user is an option nobody tests.

Decision (2026-08-21): the sender's name. The delivery announce carried the literal lnmsg, which names the tool rather than the person, so every recipient saw the same sender for every operator on every host. The default is now the account name, resolved in this order: getpwuid(getuid()) first, then $USER, then $LOGNAME, then lnmsg as a last resort. The password database comes first deliberately — the first real consumer is a health monitor started from cron, whose environment has no $USER at all, and a name that is right interactively and wrong from cron would be discovered late and by a machine. Resolution never fails: a status line that does not go out is worse than one from an oddly-named sender.

--from NAME, and LNMSG_DISPLAY_NAME for the cron case, override it, with the flag winning. They exist because a bare account name is ambiguous when the same user runs the monitor on several machines — but what goes in them is the operator's choice, not a policy of ours: no automatic hostname suffix and no templating. An empty or whitespace-only override is exit 2, not a silent fall back to the default, since it was set on purpose. lnmsg/src/display_name.rs holds the order; LNMSG_SENDER from=… source=… records which step answered, which is what separates a cron run that fell through to the last resort from an interactive one that read $USER.

7. Structured event log

Structured event logs and the project's debugging discipline call for EVENT_NAME key=val t=<ms> lines. A messenger that can be started with a log file, and whose every protocol transition appears in it, is debuggable in the field in a way that no terminal-scrollback client is. lnomad has no tracing dependency at all. This one is cheap and is not treated as speculative.

8. What the library does not expose

Naming these is useful because each is a candidate issue.

Decision (2026-08-10) on sequencing: triage, not either extreme. Gaps 1, 2, 3 and 8 are closed in one library wave before lnmsg starts, because the decided design cannot be built honestly without them: gap 2 blocks the mailbox glyph and the truthful delivery display outright, gap 1 blocks the naming-based trust model, gap 3 is shared infrastructure every client rewrites, and gap 8 is small and stops two clients wording the same errors differently. The remaining eight are filed as issues and met in build order — the Codeberg #196 precedent (the library's biggest gap was found by building a real consumer) argues for letting lnmsg discover the gaps nobody has named yet, but waiting to "discover" a gap that is already understood is delay, not empiricism. Gaps 10 and 11 are already covered by the queued #204/#202/#203 batch; gap 7 shares its core-side prerequisite with the S2 test-infrastructure question from the #212 work.

Closed 2026-08-11. The four are done: RouterEvent::PeerAnnounced (1), MessageState::AwaitingCollection (2), FileLxmfStorage in leviculum-std (3), and Display plus core::error::Error on the error types (8). The entries below are left as written — they are the record of what was missing, not a list of open work.

1. No display name reaches the application. LxmfNodeEvent::PeerAnnounced carries the destination hash only (leviculum-lxmf/src/node.rs:133-135), the router drops the name after reading the stamp cost (leviculum-lxmf/src/router.rs:1209-1219), and RouterEvent has no announce variant. Every client will re-implement announce filtering and DeliveryAnnounce::decode. A RouterEvent::PeerAnnounced { destination, announce } would remove that duplication.
2. No "propagated, awaiting collection" state. A propagated message reaches Sent and its queue entry is deleted (leviculum-lxmf/src/router/propagation_runtime.rs:386-393), so the client cannot distinguish "in a mailbox" from "gone" without keeping its own shadow record. This is the single biggest obstacle to an honest delivery display.
3. No file-backed LxmfStorage. Two implementations exist, both in-memory or null (leviculum-lxmf/src/storage.rs:42, leviculum-lxmf/src/storage.rs:116). Every host application writes the same one.
4. No periodic sync scheduler and no interval config. PropagationClientConfig has three fields (leviculum-lxmf/src/router/propagation_runtime.rs:35-45). Arguably correct for a sans-IO crate, but it means every client invents its own policy.
5. Known propagation nodes and the selection are not in the snapshot (leviculum-lxmf/src/router.rs:2069-2086), so every client writes its own persistence and replay.
6. No stamp cancellation or deadline. generate loops until success (leviculum-lxmf/src/stamp.rs:356-367) and StampError::Cancelled is declared but never constructed (leviculum-lxmf/src/stamp.rs:25). A user who starts a message to a high-cost peer and changes their mind has no way out.
7. No inbound Resource cancellation, stated as deliberate pending core support (leviculum-lxmf/src/node.rs:518-519). A user receiving a large attachment they do not want can only watch.
8. Most error types are Debug only. RouterError (leviculum-lxmf/src/router.rs:359), LxmfNodeError (leviculum-lxmf/src/node.rs:257), PropagationTransportError (leviculum-lxmf/src/propagation_client.rs:144), MessageError (leviculum-lxmf/src/message.rs:40) and StorageError have no Display. Every user-facing string is the client's to write, and two clients will word them differently.
9. No typed codecs for reply, thread, reaction or renderer fields (leviculum-lxmf/src/constants.rs:60-78), so each client hand-rolls msgpack for the same wire structures. This is a compatibility risk more than an ergonomics one.
10. Codeberg #203 (StampExecutor::generate returns a !Send future) applies to us as it applied to leviculum-lxmf-node, which worked around it with a dedicated thread running a current-thread runtime (leviculum-lxmf-node/src/main.rs:430-481). We will make the same workaround.
11. Codeberg #204 (a hook owns the events its own core calls return) is a documentation gap we will hit on day one. The bounded re-feed loop is not optional.
12. Codeberg #186 (LXMF caches age on wall-clock time and are wiped by a timebase jump) matters more for a laptop that suspends than for a daemon that runs continuously, and should be checked against the suspend-resume path before it is dismissed.

lnmsg: the user interface

Part of the lnmsg design record. Two decisions live here: how keys are dispatched, and what an honest delivery display looks like. They share one discipline — a single table read by everything that renders from it — and that discipline is the reason both are on one page.

1. Decision: the input model

This is the hard one, and the browser's answer does not transfer. In a browser, plain letters are free because there is nothing to type into most of the time. In a chat client, the single most common action is typing prose.

Options

A. Modal, vi-style. Normal mode for commands, insert mode for composing, i to enter, Esc to leave. For: every key stays available for commands; scales to any number of bindings; vi users are instantly at home; it is the only option where j/k mean what they mean in lnomad. Against: it is the single biggest complaint non-vi users have about terminal software. A user who types a message, presses Esc out of habit, and then types "quit" has issued four commands. Mode errors in a messenger are worse than in an editor because the consequence can be sending something.

B. Always-insert, everything Ctrl-modified. NomadNet's answer (NomadNet's Conversations.py, lines 68-80). Focus starts in the compose box, plain typing always composes, every command is Ctrl-something. For: zero mode errors; a user who has never read the manual can still type and send. Against: the Ctrl namespace is about twenty-six slots wide and readline already claims a dozen of them. NomadNet ran out and started overloading by focus, so Ctrl-X means two different things depending on invisible state.

C. Focus-follows-pane. The conversation list and the message list are command panes with lnomad-style bindings; the compose box is a text pane where plain keys type. Tab moves focus. For: no modes to learn, because the mode is visible as which pane has the cursor; single-letter commands survive in the panes where they make sense; it matches how tmux, mutt and every mail client behave. Against: the same key does different things in different panes, which is a mode by another name, just one you can see. And Tab becomes precious.

D. Prefix key. Everything types; a prefix (Ctrl-Space, Ctrl-A, or ,) introduces a command. For: unlimited namespace, no modes, tmux and screen users know it. Against: two keystrokes for everything, including scrolling, which is the operation you do most.

Decision (2026-08-08)

C, with a command palette (D) layered on it, and no modes.

Concretely:

• Three panes: conversations (left), messages (right, upper), compose (right, lower). Tab and Shift-Tab cycle; a click focuses.
• In the conversation and message panes, lnomad's keymap applies unchanged: the SCROLL_KEYS table verbatim (lnomad/src/tui.rs:3159-3291), so j/k, Ctrl-n/Ctrl-p, arrows, Ctrl-f/Ctrl-b, Ctrl-v/Alt-v, Ctrl-d/Ctrl-u, g/G, Home/End and the wheel all work, in all four idioms, for free.
• In the compose pane, plain keys type. Only Ctrl- and Alt- chords are commands, plus the scroll table's Ctrl and Alt rows, which do not collide with readline because they are page motions and readline's are line motions. Enter sends: LXMF is email on the wire but chat in every deployed client — Sideband, NomadNet, MeshChat and columba all render conversations, nobody uses the title field — so users arrive with chat expectations, and Enter-to-send is the universal chat convention. Newline is Alt-Enter everywhere and additionally Shift-Enter where the terminal speaks the keyboard enhancement protocol (legacy terminals cannot distinguish Shift-Enter or Ctrl-Enter from Enter — same byte — which is also why Ctrl-Enter-to-send was dropped; crossterm's PushKeyboardEnhancementFlags enables the modern protocol where available). Enter on an empty buffer does nothing. The keymap table carries a send_on_enter switch; off flips to email style (Enter newline, Ctrl-D send) for long-form writers. Ctrl-D on an empty buffer must not send and must not quit.
• A command palette on : in a command pane and Ctrl-P in the compose pane, with fuzzy matching over named commands. This is what makes the scheme learnable: every command has a name, the palette lists them all, and each entry shows its key if it has one. NomadNet's static shortcut bar is the failure mode to avoid.
• f hint mode from lnomad (hints, lnomad/src/tui.rs:1155-1195), extended to conversations. Its best property is that it matches either the hint label or a substring of the target's text (hint_matches, lnomad/src/tui.rs:1182-1195), so f then typing part of a contact's name jumps to that conversation. That is a better contact switcher than anything in either prior-art program.

What must not be copied: lnomad quits on Ctrl-C from any mode, before the mode dispatch (lnomad/src/tui.rs:1575-1578). In a messenger that is a half-written message thrown away by a reflex. Ctrl-C in the compose pane clears the buffer to a recoverable draft; quitting needs Ctrl-Q or the palette.

The keymap must be one table. lnomad applied single-source-of-truth discipline to scrolling and nowhere else, and its help overlay's other groups are hand-typed strings that can drift (lnomad/src/tui.rs:4687-4788). Every binding here is one table read by the key handler, the help overlay, the palette and the footer hints. That table is also the natural place to hang user configuration later, which lnomad has none of.

What would change this: if the compose box turns out to be where users spend nearly all their time, B (always-insert, Ctrl for everything) is simpler and has no invisible state at all, at the cost of losing single-letter commands entirely. The way to find out is to build C and count how often focus is in the compose pane.

The quiet keyboard, with its one exception (decided 2026-08-08). The lnomad rule that single letters are reserved for cheap local actions (lnomad/src/tui.rs:1930-1933) generalises here to: no single keystroke may put bytes on the air — except Enter in the compose pane. The exception is principled, not a leak: the deliberate act was typing the message into a deliberately focused pane, and Enter completes that act. Everywhere else the rule is absolute: no key in a command pane transmits, syncing needs a chord or the palette, announcing needs a chord or the palette. Everything free is free.

2. Decision: what honesty about delivery looks like

Most chat UIs lie by simplification: one check for sent, two for delivered, and everything ambiguous rounded to the friendlier reading. LXMF has real states and the library reports them, so there is no excuse.

The states as they actually are, from the library survey:

What a truthful UI shows

Different marks for different truths, and words in the detail view. The three that must never be collapsed:

• handed to the network, unproven (opportunistic Sent),
• left in a mailbox for later (propagated Sent),
• arrived at the destination (Delivered).

columba collapses the first two into one check mark; NomadNet gives them different colours but never words. Three visually distinct marks, and, crucially, a per-message detail view (columba's best idea) showing delivery method with a one-sentence explanation, attempt count, hop count, and the error string when there is one. In a terminal that is a key press on a focused message.

Never claim a read receipt. LXMF has no such field (leviculum-lxmf/src/constants.rs:52-78). Any UI element that suggests one is a lie in the protocol's own terms.

Say what Delivered means, once. It means the bytes reached the destination identity, not that a human saw them. The detail view is where that sentence lives.

Distinguish the two Rejecteds by correlating with the message's method before the entry disappears. "Your mailbox refused this message" and "the recipient's client refused this message" are different problems with different fixes.

Handle the restart discontinuity honestly. restore resets every queued message to Outbound (leviculum-lxmf/src/router.rs:2054-2057). So after a restart, a message that was "sending" is "queued" again, and the UI must show that rather than a frozen progress bar. NomadNet's equivalent, forcing a stale mid-flight message to FAILED on load (NomadNet's Conversation.py, lines 455-467), is at least honest, though our library gives us the better option of an honest retry.

Never let a late failure demote a success. columba added exactly this guard after a real bug. Delivered must be terminal in the UI even if something arrives afterwards claiming otherwise.

Decision (2026-08-10): the ledger and the glyph

The ledger is one keypress away, inside the per-message detail view — part of the normal program, not a debug flag, but costing no space in the conversation. It is also where the airtime number lives. The ledger rows are stored beside the message in SQLite (a handful of roughly 50-byte rows per message) and share the message's retention (storage).

Decided with it: one coloured glyph per message in the conversation view, occupying a single cell, carrying the delivery state at a glance. The glyph is the compact face of the same state machine the detail view explains; both render from one shared state-mapping table (the keymap discipline above, applied again — the glyph, the detail view and the ledger can never disagree).

The glyph language, chosen so the colours carry the meaning even before the shapes are learned:

The rules the table encodes: green and a check mark appear only on proof — the mailbox state is a blue house, deliberately not a second check, because "in a mailbox the recipient may never open" must not read as progress toward delivered; amber ◇ (hollow) against green ✓ (solid) mirrors unproven-versus-proven; animation means "the machine is working right now" and nothing else, driven by the event-loop tick so it freezes honestly if the program hangs. An ASCII fallback set (. * o ^ v x) ships behind the same table for terminals that mangle the glyphs.

The timeline itself:

14:02:11  queued
14:02:11  no route known, asked the network
14:02:19  route found, 3 hops
14:02:20  link established
14:02:21  sent, 412 bytes
14:02:26  delivery proof received

This is close to free, since the library already emits every one of those transitions, and it turns "why is this taking so long" from a support question into something the user can read.

3. Proposals, not requirements

Everything in this section is a proposal rather than a decision, and several of these will not survive contact with a real user.

Cost before commitment

Show what a message will cost before it is sent, next to the send action:

412 bytes   ~7 s airtime at the slowest hop   no stamp required

The pieces exist. leviculum_core::rnode::airtime_ms (leviculum-core/src/rnode.rs:1061) and packet_airtime_ms (leviculum-core/src/rnode.rs:1655) are public, interfaces report a bitrate (leviculum-std/src/interfaces/mod.rs:598-600) computed from spreading factor, coding rate and bandwidth (compute_bitrate, leviculum-std/src/interfaces/rnode.rs:3185), and fetch_remote_status (leviculum-std/src/remote_status.rs:192) retrieves the interface list from the daemon, which is how lnstatus works. Note two honesty constraints: fetch_remote_status needs the management authkey, and the status surface reports bitrate but not the raw radio parameters, so an estimate from bytes * 8 / bitrate is the best available and must be labelled as an estimate.

When the peer advertises a stamp cost, the estimate must include the proof-of-work, and that number has to be measured first: the crate contains no benchmarks, and the cost model (2^cost hashes plus a 3000-round workblock, leviculum-lxmf/src/constants.rs:45, leviculum-lxmf/src/stamp.rs:458-466) predicts scaling but not milliseconds on a Pi.

Offline as a state, not a failure

An offline-first client should look deliberate rather than broken. Two concrete moves:

• A single posture line that says what the program can do right now: "3 peers reachable directly, mailbox 4m ago, 2 messages waiting to send". Not a red error banner; a statement of fact.
• Queued messages shown in the conversation, in place, greyed, with their reason ("waiting for a route", "computing proof-of-work, about a minute"). A message the user wrote should never vanish into a queue they cannot see. The library gives progress and next-attempt time per entry (OutboundEntry, leviculum-lxmf/src/router/outbound.rs:58-72).

The mouse as a first-class citizen

lnomad enables mouse capture unconditionally with no toggle (lnomad/src/tui.rs:5215-5218) and handles neither drag nor selection (lnomad/src/tui.rs:1374). In a browser that costs you the terminal's own copy-paste; in a messenger, where copying message text is a constant, it is worse.

Proposal: handle drag selection ourselves over the message IR, so selecting text across wrapped lines and across message boundaries works and copies via OSC 52 (lnomad/src/tui.rs:2519-2551, which works over SSH). Plus a --no-mouse flag and a runtime toggle for people who want the terminal's own selection back. The StyledChar IR already carries per-cell ownership (lnomad/src/render.rs:340-354), so the hit-testing is a small extension of visible_links rather than new machinery.

Terminal QR for paper messages and for your own address

PaperMessage::to_uri() produces an lxm:// URI (leviculum-lxmf/src/paper.rs:172) and the crate stops there. A QR code rendered in Unicode half blocks is a well-trodden trick, and lnomad already has the half-block ladder for images. That gives an air-gapped send path: compose, render, photograph, and the recipient scans it. Also useful for showing your own address to someone sitting next to you, which NomadNet does (Ctrl-P in the conversation list).

Constraint: PAPER_MDU is 2210 bytes (leviculum-lxmf/src/constants.rs:38), which is near the practical limit of what a QR code can hold and certainly beyond what a phone camera reads off a terminal at normal font sizes. The UI must say when a message is too big to be a QR and offer the URI as text instead.

A "what changed while I was away" view

On start, after the first sync, one screen summarising what arrived, grouped by conversation, with the option to mark all read or step through them. Every mail client has this; no Reticulum client does. It fits the usage pattern exactly, because the whole point of the propagation node is that the user was away.

Micron in messages

If FIELD_RENDERER says micron (reference/LXMF/LXMF/LXMF.py:100), render it with leviculum-micron (leviculum-micron/src/lib.rs:25-27) and lnomad's renderer. If it says markdown, we already depend on pulldown-cmark at workspace level (Cargo.toml:82). This is a capability the workspace has and nobody has spent, and it costs a match statement.

Sending micron is the more interesting half: a compose box with a preview toggle, in a client whose sister program is a micron browser.

lnmsg: conversation storage

Part of the lnmsg design record.

The library stores one key (ROUTER_STATE_KEY, b"lxmf/router-state", leviculum-lxmf/src/router.rs:64) and hands each received message to the application exactly once. All history is the client's problem.

Options

A. NomadNet's shape: a directory per conversation, a file per message. For: trivially crash-safe per message if each write is temp-plus-rename; human-inspectable; deleting a conversation is rm -rf; no dependency. Against: one inode per message forever; listing a conversation is O(n) listdir; no search without reading everything; NomadNet needed a .index sidecar that duplicates every message body on disk (NomadNet's Conversation.py, lines 944-960) and still starves file descriptors under announce storms (NomadNet commit 7bc6911). On a Raspberry Pi with an SD card this is the worst option.

B. An append-only log per conversation plus a separate index. Messages appended as length-prefixed msgpack; an index mapping message ID to offset; compaction on deletion. For: appends are one write and one fsync; sequential reads are fast; the format is simple enough to recover by hand. Against: you are writing a small database, including the index, the compaction and the crash-consistency argument between them.

C. SQLite. One file, one messages table with the columns columba already proved out. For: paging, search (FTS5), indices, transactions and crash safety all solved by someone else; a 2 GB history is unremarkable; sqlite3 on the command line is the debugging tool. Against: rusqlite with bundled compiles SQLite's C into the binary. lnomad treats a C library in the path of the musl-static .deb as disqualifying (lnomad/Cargo.toml, the ratatui-image comment), though that was about a pkg-config probe for a shared library rather than a vendored static one. Checked empirically 2026-08-08: rusqlite with bundled compiles clean against x86_64-unknown-linux-musl on the project toolchain — statically linked binary, SQLite 3.46 embedded, FTS5 verified working by query, 2.6 MB total, 25 s build. The lnomad disqualifier was a pkg-config probe for a shared library and does not apply to the vendored static build.

D. A pure-Rust embedded store (redb, sled, fjall). For: no C toolchain, ACID, ordered keys, so range scans give paging for free. Against: no query language and no full-text search, so search is hand-rolled; another dependency to trust with the user's mail.

Decision (2026-08-10)

C — SQLite, via rusqlite with the bundled feature. The packaging question was answered by the build probe above, so the fallback to D is retired. The schema below, with its three commitments (identity-scoped rows, two timestamps sorted on COALESCE(received_at, timestamp), raw msgpack fields), is the starting point; attachments live out of line as content-addressed files. Retention is settled further down.

The schema to start from, taking columba's two good decisions:

messages(
  id BLOB, identity BLOB, conversation BLOB,
  direction INT, state INT, method INT, verification INT,
  timestamp REAL,        -- the sender's clock, from the wire
  received_at REAL,      -- our clock, when we saw it
  title BLOB, content BLOB, fields BLOB,   -- fields as raw msgpack
  error TEXT,
  PRIMARY KEY (id, identity))

with an index on (conversation, identity, COALESCE(received_at, timestamp)) and one on (conversation, identity, direction, read).

Three reasons for the shape:

1. Every row scoped by local identity. A user may hold several addresses; columba's composite keys make that free, and retrofitting it later means a migration.
2. Two timestamps, sort on COALESCE(received_at, timestamp). The wire timestamp is the sender's clock, and nothing makes another node's clock trustworthy. Sorting on it puts a peer with a wrong clock at the top or bottom of your history forever. NomadNet exposes this as a user-facing sort toggle, which is not a fix. (Sub-second precision is not the problem it once was on our side: the emission timestamp carries it, as the reference's time.time() does, because at whole-second granularity two identical messages created inside one second collapse to one ID — leviculum-lxmf/src/router.rs:531-535, Codeberg #217. Precision and skew are different failures, and only the second one is a sorting question.)
3. fields stored as raw msgpack, not exploded into columns. Unknown fields round-trip byte-for-byte in the library (leviculum-lxmf/src/message.rs:5-8) and must round-trip here too, or a reply to a message from a newer client loses information.

Attachments out of line, as NomadNet does (its Conversation.py, lines 752-812): content-addressed files under an attachments/ directory, with the row carrying names and hashes. Blobs in the database make the database the size of the blobs, and a 2 MB voice message has no business in a row you page through.

Retention, decided 2026-08-10

Neither prior-art program prunes, and both will therefore eventually fail on small hardware. The decision:

• Message text is kept forever. A million messages are a few hundred megabytes, SQLite territory, and the searchable archive is precisely the value the FTS decision bought.
• Attachments live under a total-bytes budget (default about 500 MB, configurable, numbers stated in the manual), evicting oldest first — the same pattern as lnomad's byte-budgeted image cache (lnomad/src/image_cache.rs:11-14).
• Evicting an attachment never touches the message row. The message keeps the attachment's name, hash and size and renders "attachment (2.1 MB), evicted under the storage budget on ". The history does not lie, it just gets lighter.
• Ledger rows (the delivery ledger) share the message's retention, so for text they live forever; no extra rule.
• A per-conversation opt-in age cap remains open as a possible later addition and was deliberately not built now.

On the 2 GB Raspberry Pi question specifically

With option C, a 2 GB history is roughly ten million short messages, and the operations that matter are "open the last screenful of a conversation" and "search". Both are index lookups and neither touches the bulk. With option A, opening a conversation reads every file in it. That asymmetry is the whole argument.

Durability rule, from lnomad's counter-example

Nothing in this program may use fs::write on a file it cannot afford to lose, and nothing may treat a corrupt load as an empty load (lnomad/src/bookmarks.rs:116-130). Bookmarks can be silently forgotten. Mail cannot.

lnmsg: the mailbox, and who you talk to

Part of the lnmsg design record. Two decisions live here: when and how the client talks to a propagation node, and how it names and trusts the people on the other end. They belong together because the trust model is what gates the mailbox choice.

1. Decision: propagation node interaction

This is where a naive design produces a client that silently loses mail, and the library has arranged things so that the naive design is the default: nothing syncs unless the application asks (request_messages_from_propagation_node, leviculum-lxmf/src/router/propagation_runtime.rs:1365, and next_deadline() returns None outside PathRequested, leviculum-lxmf/src/router/propagation_runtime.rs:1142-1148).

When to sync

Options: on demand only; on a timer; on start plus timer; on announce of the selected node; adaptive.

NomadNet uses a six-hour timer with a limit of eight messages and no sync on start (NomadNet's NomadNetworkApp.py, lines 148-150 and 456-471). Six hours is a very long time for something calling itself a messenger. columba makes the interval configurable.

Decision (2026-08-10): sync on start, on resume from suspend, on a manual key, opportunistically when the selected node announces (free evidence that it is reachable right now), and on a timer with asymmetric adaptivity:

• The configured interval — default fifteen minutes — is a hard upper bound that is never exceeded. That is the promise the user can rely on: mail is at worst one interval old, always.
• After activity (a sync that returned something, or an outbound send), the client syncs more often for a while — on the order of every two minutes — decaying back to the bound. This is the chat-feel half of adaptivity (the input-model decision), applied to the mailbox.
• The dangerous half — silently lengthening the interval when syncs come back empty — does not exist. Full adaptivity was rejected because an interval that quietly stretches is exactly the "why didn't I get that message for two hours" machine, and unpredictability in a messenger is a breach of trust.

Never sync while a direct link to the peer is up and working, because that spends airtime to learn nothing.

The bound is configurable, its cost is stated in the manual in airtime rather than in seconds (on LoRa a fifteen-minute poll is not cheap), and the status line always shows when the next sync is due — the current cadence is visible, never inferred.

What the user sees

The library hands over a fourteen-state machine (PropagationClientState, leviculum-lxmf/src/router/propagation_runtime.rs:60-75), progress as an f32, transfer size, and a result of { received, duplicates } (PropagationSyncResult, leviculum-lxmf/src/router/propagation_runtime.rs:78-83). That is more than enough to be honest.

A permanent one-line status, taking NomadNet's best idea (its Conversations.py, lines 517-548) and refusing its modal dialog. Something like:

mailbox  a1b2c3d4 Node-Name   3 hops   last sync 4m ago, 2 new   next in 11m

and during a sync the same line becomes the progress display, naming the state in words: "asking the network where the node is", "connecting", "asking what it has", "downloading 4 of 7". columba's plain-English state descriptions are better than NomadNet's terse ones and both are better than a bare progress bar.

When there is no reachable node, the line must say which of the several different failures happened, because they need different fixes:

A single "sync failed" for all six is the lie this section exists to prevent.

The non-interactive slice's selection order (decided 2026-09-12)

The shipped lnmsg send/lnmsg fetch have no picker to offer, so the CLI resolves the node in a fixed order: the --pn flag, then the propagation_node key in ${LNMSG_HOME}/config (the persisted default), then the most recently announced node heard while attached. Recency rather than the library's route/cost ranking, because for a short-lived CLI the node that just announced is the one whose reachability is evidence rather than cache; the reference LXMRouter ships no autoselection at all — its clients pick, each with their own rule (NomadNet by hops among trusted, columba by hops). Nothing is auto-adopted silently in the TUI sense: a cron job's operator wrote --pn or the config key, and the announced fallback is for the interactive shell where the operator reads the LNMSG_PN line. What is persisted where: the identity at ${LNMSG_HOME}/identity, the node default in ${LNMSG_HOME}/config, the cross-run seen-message ids in ${LNMSG_HOME}/seen; the selection itself is per-run and never written back.

Which node, and the trust question

NomadNet auto-selects the fewest-hops node whose trust level is TRUSTED (its NomadNetworkApp.py, lines 607-631). columba auto-selects the fewest-hops node, full stop. The library's own auto-selection ranks by route, hops, peering cost and stamp cost (select_outbound_propagation_node, leviculum-lxmf/src/router/propagation_runtime.rs:1161-1196) with no trust input at all, because it has no notion of trust.

Your mailbox sees the envelope of every message sent to you: who sent it and when, even though it cannot read the content. Handing that to whoever happens to be nearest is a real privacy decision, and neither prior-art program presents it as one.

Never auto-adopt silently. On first run, and whenever the selected node becomes unreachable, present a picker with the candidates, their hop counts, their advertised limits and costs (PropagationNodeAnnounce, leviculum-lxmf/src/propagation.rs:513-525), and require one keystroke to accept. Automatic failover between nodes the user has already approved is fine and the library already does it (leviculum-lxmf/src/router/propagation_runtime.rs:825-846); automatic adoption of a stranger is not.

Note that NomadNet's trust propagation makes this worse: trusting a person auto-trusts their node (its Directory.py, lines 198-202), which makes it eligible as your mailbox. Do not inherit that.

The purge default

retain_synced_on_node defaults to false (leviculum-lxmf/src/router/propagation_runtime.rs:50), so by default the client tells the node to delete what it has collected. That is the right default for privacy and for the node operator's disk, and it is the wrong default for a user who runs two clients on the same identity, because the first one to sync takes the mail. This must be a visible setting with the consequence spelled out, not a config-file default nobody reads.

What the client must implement itself

• The sync schedule (there is none in the library).
• Persistence of known propagation nodes and of the selection, since neither is in the router snapshot (snapshot, leviculum-lxmf/src/router.rs:2069-2086); replay via restore_known_propagation_node (leviculum-lxmf/src/router/propagation_runtime.rs:1317).
• Re-selection after restart.
• Proof-of-work for PropagationStampPending, off the core lock.
• Calling persist() on PersistenceRequested.

The mailbox as a visible relationship (proposal)

The propagation node is currently magic in every client: something chosen for you, syncing on a schedule you did not set, holding mail you cannot see. Make it a first-class object in the UI, with its own screen: who it is, how many hops away, what it advertises, when you last spoke to it, what it is holding for you if it will say, and whether it is purging what you collect. columba's trick of modelling the relay as a contact with an isMyRelay flag is a cheap way to get there.

The honest version of this includes telling the user what the mailbox learns about them: the envelope of every message they receive. No prior program says this out loud.

2. Decision: identity, contacts, and names

The address is the identity. A 16-byte destination hash, rendered as 32 hex characters, is the only thing that is true about a peer.

The delivery announce carries a display name as arbitrary bytes (DeliveryAnnounce, leviculum-lxmf/src/announce.rs:39-44), and display_name() strips NUL and trims but does nothing else (leviculum-lxmf/src/announce.rs:164-168). The announce is signed: the Reticulum announce signature covers the app data (leviculum-core/src/announce.rs:104, :213: "the signature covers destination_hash + public_key + name_hash + random_hash + [ratchet] + app_data"). So a verified announce proves that the holder of that key chose that name. It proves nothing about uniqueness, and there is no naming authority in Reticulum. Two identities can both announce "Lew", and one of them can be doing it on purpose.

Two further facts a UI must not paper over. Message::verification can be Unverified when the source identity has never been announced to us (leviculum-lxmf/src/message.rs:229-231), and such messages are delivered to the application anyway (leviculum-lxmf/src/router.rs:1474-1477). And the router discards the display name from announces entirely, so the client must maintain its own hash-to-name map from raw NodeEvent::AnnounceReceived.

Options for naming

A. Announced name only. What most chat UIs do. Simple, and impersonation is trivial.

B. Local petname only. Nothing is displayed until the user names the contact; strangers show as a hash prefix. Maximally safe, maximally tedious, and hostile to the case where someone new writes to you.

C. Petname wins, announced name shown as provenance. columba's precedence chain (nickname, then announced, then stored), with the announced name still visible somewhere.

Decision

C, plus NomadNet's collision check, plus a hash that never fully disappears.

1. Display: petname if set, otherwise the announced name, and in both cases a short hash suffix. NomadNet suppresses the hash for trusted peers (its Directory.py, lines 277-297); we shorten it rather than suppress it, because a four-character hash costs nothing and makes "wait, that is not the Lew I know" possible at a glance.
2. Collision warning, the one genuinely novel thing in the prior art: if an announced name is already claimed by a different address, mark it (NomadNet's Directory.py, lines 306-320). Extend it to a name-change warning: if an address you have talked to announces a different name than last time, say so once in the conversation. That is cheap, and it is the actual impersonation vector.
3. Sanitise names. They are arbitrary bytes off the wire. Strip control characters, normalise, cap the display width, and refuse to let a name contain something that renders as a checkmark or as another contact's name. NomadNet does this because micron markup in a name would otherwise render (its util.py, strip_modifiers).
4. Unverified messages must look different. NomadNet's "Unknown Origin" / "Invalid Signature" plain-English rendering (its Conversation.py, lines 620-630) is right; a coloured glyph alone is not.
5. Refuse to compose to an address whose key is unknown, with the reason and a "ask the network" action, as NomadNet does (its Conversations.py, lines 2186-2204). The library will tell you: our own helper checks core.storage().get_identity(&peer) before composing and reports which call was skipped rather than timing out later (leviculum-lxmf-node/src/processor.rs:1160-1169).
6. Contact status as persisted state, columba's ACTIVE / PENDING_IDENTITY / UNRESOLVED, rather than a live lookup, so the list can be rendered without touching the network.

Trust levels: how many?

NomadNet has four — WARNING, UNTRUSTED, UNKNOWN, TRUSTED (its Directory.py, lines 410-413); columba has none. Four levels with a radio group is more ceremony than most users will perform.

Decision (2026-08-10): exactly three states that a user reaches by accident and understands: known (I named this contact), unknown (I have not), and blocked. Trust is not a thing to configure but a thing that follows from having named someone, which is an action people take anyway.

A derived fourth state ("suspicious", computed from name collisions and name changes) was considered and rejected: on a mesh, two identities sharing a display name and a contact renaming themselves are normal occurrences, not indicators of attack, and a state that cries wolf on normal behaviour trains the user to ignore it. The signals themselves are not discarded — they are a rendering matter, not a trust matter: when two contacts share a display name the list must disambiguate them (short hash suffix), and identity, not name, is always what messages are keyed by. The columba defect this section opened with was the missing trust anchor for relay auto-selection, and three states cover that: only known contacts qualify.

The identity file itself must not behave like lnomad's (load_or_create, lnomad/src/identity.rs:39-53, silently regenerating on a decode failure). A corrupt identity is a refusal to start with a clear message, because minting a new one silently changes the user's address.

Public channels over LXMF

Status: design record. Not yet implemented.

Meshtastic and MeshCore both have public channels, and they are the reason a lot of people pick those stacks. You flash a board, type a channel name, and you are talking to whoever is in range. LXMF has nothing equivalent. It has mailboxes, and a mailbox is a conversation with one person.

This document describes how to add channels without changing anything in the existing Reticulum or LXMF infrastructure, why that is possible at all, and where the sharp edges are.

Two crates are involved, neither of which exists yet: a propagation node server, and channel support in lnmsg. The lnmsg design record currently states that hosting a propagation node is out of scope. That changes here: the channel feature only works if we host nodes, because the retrieval side is ours.

1. Why the obvious approach does not work

Reticulum has a broadcast packet form and a symmetric group destination type, and neither carries a channel.

Destination.announce() refuses anything that is not a SINGLE destination (Destination.py:251-252), so a GROUP or PLAIN destination can never be announced, and without an announce there is no path table entry. Transport.outbound skips the path lookup for both types outright (Transport.py:1121), and any receiving node drops such a packet once hops > 1 (Transport.py:1354-1373, mirrored in leviculum-core/src/transport.rs:3233-3265). The reach of a Reticulum broadcast is exactly one hop plus locally attached clients.

For PLAIN the manual gives the reason: "To be transportable over multiple hops in Reticulum, information must be encrypted, since Reticulum uses the per-packet encryption to verify routing paths and keep them alive" (docs/source/understanding.rst:112-114). For GROUP the same manual says only that packets are "not currently" carried over multiple hops, "although a planned upgrade to Reticulum will allow globally reachable group destinations" (understanding.rst:118-120). That sentence has stood unchanged since 2022-04-28.

The other flooding primitive, the announce, is capped at two percent of interface bandwidth by ANNOUNCE_CAP (Reticulum.py:114), with rate penalties on top. It is not a carrier for chat.

2. The carrier that does exist

Propagation nodes flood among themselves over the full multi-hop transport, because peer-to-peer sync runs over ordinary links between SINGLE destinations. An earlier draft of this document called that flooding "blind", and overstated it: a node never looks inside what it stores, but it does not accept unconditionally. Three properties make the carrier usable, and two toll gates stand in front of it.

A node does not inspect what it stores. lxmf_propagation (LXMRouter.py:2487-2518) requires only that the data is at least LXMF_OVERHEAD bytes long (LXMessage.py:63) and that its transient ID, the SHA-256 of the bytes, is new. It then takes the first 16 bytes as the destination hash, writes the message to disk and queues it for distribution. There is no signature check, no decryption, and no check that the destination has ever been announced or exists.

Distribution is unfiltered. flush_peer_distribution_queue (LXMRouter.py:2472-2485) offers every new message to every peer except the one it came from, with no criterion whatsoever.

Peering is automatic — within three limits. A node peers with any node whose announce it hears, as long as autopeer is set and the hop distance is within autopeer_maxdepth (Handlers.py:81-83, and again on inbound sync at LXMRouter.py:2365). Three gates bound it. A peer whose announced peering cost exceeds the local max_peering_cost is refused (LXMRouter.py:2005-2010; default maximum 26, LXMRouter.py:50-51). A node that already holds MAX_PEERS peers — twenty by default (LXMRouter.py:43) — refuses further ones (LXMRouter.py:2032). And an inbound sync offer must present a peering key: a proof of work over the two node identities at the announced peering cost, 18 bits by default, checked by validate_peering_key (LXMRouter.py:2300-2312). An offer without a valid key is rejected with ERROR_INVALID_KEY, and a party without one may deliver at most one message per transfer (LXMRouter.py:2382-2385).

Every stored message has paid for admission. Both ingest paths — the link-packet path and the resource path — run validate_pn_stamps (LXMRouter.py:2242-2243, again at LXMRouter.py:2401-2402) before lxmf_propagation ever sees a byte. A propagation stamp is a proof of work over the message, carried as 32 trailing bytes. The minimum accepted cost is the node's propagation_stamp_cost minus its flexibility — 16 minus 3 with the defaults (LXMRouter.py:52-54), and the cost knob is clamped so it can never be configured below PROPAGATION_COST_MIN = 13 (LXMRouter.py:137). An unstamped or understamped message is dropped; a transfer containing one tears the link down and throttles the sender for PN_STAMP_THROTTLE = 180 seconds (LXMRouter.py:63, applied at LXMRouter.py:2449-2452).

So a channel message injected anywhere reaches every propagation node in the connected network — provided it carries a stamp the ingest node accepts, which with default configurations means minting 16 bits of work per post, and never less than 13. Existing Python nodes are the transport; our nodes are the access points. Nothing upstream has to change for the distribution half to work, but a node of ours that wants to distribute has to implement all of the above: the announce format position by position, peering-key minting and validation, stamp minting and validation, transfer and sync limits, and the throttle behaviour. A node built without the peering key gets ERROR_INVALID_KEY on every sync offer it makes and is limited to one message per transfer; a node that skips stamp validation accepts what its peers will not. Either way the distribution half collapses.

Writing does not even require one of our nodes. A client with no presented identity may deliver one stamped message per transfer to any node, and that message is flooded normally. Only reading requires us.

3. What we must not build

The retrieval endpoint has to work without an identity check, or channels do not work at all: many people read the same address, and none of them owns it. The naive form is "client asks for a destination hash, node returns what it holds".

That must not be built. Through peer sync our node also stores every foreign mailbox message in the network. An endpoint that answers for an arbitrary destination hash becomes a traffic-analysis oracle over the whole mesh: ask about any address and learn how many messages are pending, how large they are, and when they arrived. The contents stay encrypted, and it still destroys exactly the property Reticulum exists to provide.

The rule: a channel endpoint may only ever serve entries the node has positively classified as channel entries. Mailbox entries are reachable solely through the identity-bound /get path, unchanged from Python: message_get_request (LXMRouter.py:1482-1484) refuses a client that presents no identity, and serves only entries addressed to the destination derived from that identity. Section 5 is what makes the classification sound rather than a matter of trust.

What the rule does not give: any operator of any propagation node — Python or ours — sees the destination hash of every stored entry in plaintext, and can watch per-address volume and timing locally. The rule closes the remote oracle, the one that answers strangers about addresses they merely name. It cannot close the local view, because carrying traffic means seeing it. Section 4 states what that costs each channel type.

4. Addressing

Both channel types are ordinary 16-byte destination hashes, derived with the standard Reticulum construction, Destination.hash (Destination.py:116-130), so that stock tooling can compute them unmodified.

Open channels derive from the name alone:

name_hash = SHA-256("lxmf.channel." + name)[:10]
dest_hash = SHA-256(name_hash)[:16]

which is Destination.hash(None, "lxmf", "channel", name). Anyone who knows the name can compute the address, which is the point.

A key-stretching alternative was considered and rejected: derive the address through an expensive KDF over the name instead of one cheap hash, so that an observer holding a stored entry's address cannot cheaply dictionary-test candidate names against it. It buys nothing here. Every open-channel message carries its name in cleartext (section 5), because the node must recompute the address from the name to classify the entry at all — so the name is public the moment the first post exists, and hardening the derivation only slows down legitimate clients on weak hardware. For closed groups the question does not arise, because their addresses do not derive from names.

Closed groups. This section replaces an earlier design that review killed, and the replacement is a proposal, not a settled decision — it changes the shape of the group secret and needs its own review before anything is built.

The earlier draft derived the group address from a symmetric group key and authenticated readers by an HMAC under a second symmetric key. One sentence on why that was unsound, so the scar stays visible: the node never holds any group's key, so it could verify neither the HMAC nor the claimed binding between address and key — the "authentication" reduced to knowledge of a 16-byte address, which is exactly the oracle section 3 forbids.

The proposal: a group is an ordinary Reticulum identity — an asymmetric keypair — whose full key material is shared among the members as the group secret, alongside a symmetric content key for the payloads. The address derives from the group identity with the standard construction and a fixed aspect set:

dest_hash = Destination.hash(group_identity, "lxmf", "group")

Destination.hash accepts an identity (Destination.py:122-124) or 16 bytes of raw hash material (Destination.py:125-126); the proposal uses the identity form. No name enters the derivation, so a node holding the group's public key can recompute the address — and verify that key and address belong together — without ever learning a name or a secret. That recomputation is what makes closed-group authentication and classification verifiable (sections 5 and 7) where the HMAC design was not.

What a closed group hides, stated honestly rather than generously: the name and the contents. Not the existence, and not the traffic. The address stands in plaintext as the first 16 bytes of every stored entry on every node that syncs it, and the envelope that makes classification possible (section 5) marks the entry as closed-group traffic and carries the group's public key. After the first post, any node operator in the network can observe that this group exists, how much it posts and when. Without the group secret the address cannot be derived in advance and the group cannot be found by name — but "unguessable and undiscoverable", as the earlier draft had it, overstated the property. Members who need their group's existence hidden from node operators need a different tool.

Both channel namespaces are disjoint from lxmf.delivery by the name hash that enters the construction, so a channel or group hash can never collide with a mailbox hash short of a SHA-256 collision.

5. Message format, and how a node recognises a channel message

A channel message is an ordinary LXMF message whose destination hash is the channel address. The packed form is destination(16) || source(16) || signature(64) || payload, where the payload is a msgpack array (LXMessage.py:382-386). The signature covers destination, source, payload and the message hash (LXMessage.py:364-368 builds the hashed part, LXMessage.py:375-378 signs it).

For propagation, Python encrypts everything after the destination hash and appends the propagation stamp: destination || encrypt(rest) || stamp (LXMessage.py:430-435). An open channel message differs in exactly one step: the rest is not encrypted, so the stored body is readable. A receiving Python node cannot tell the difference, because it never decrypts either one. On disk, a propagation node stores the entry with the validated stamp re-appended (LXMRouter.py:2512-2515) and strips it again when serving (LXMRouter.py:1549); the stamp is 32 bytes (STAMP_SIZE, LXStamper.py:15).

Three reserved custom fields carry the channel data (LXMF.py:44-46):

• FIELD_CUSTOM_TYPE (0xFB): the discriminator and format version.
• FIELD_CUSTOM_META (0xFD): the channel name, and the sender's public key.
• FIELD_CUSTOM_DATA (0xFC): reserved for later use.

Classification of open-channel entries. The classifier takes a stored entry, strips the trailing 32-byte stamp, and parses the region after byte 96 — after destination, source and signature, not after the destination alone — as msgpack. An earlier draft parsed at the wrong offset and claimed that encrypted mailbox traffic "fails this immediately, being ciphertext". Both halves were wrong: a literal implementation would have failed on every legitimate entry, and ciphertext does not reliably fail a msgpack parse — any byte in 0x00-0x7f is a complete, valid positive-fixint document, and larger accidental structures parse too. Parsing is a cheap prefilter, nothing more. The checks, in order:

1. The entry is at least LXMF_OVERHEAD plus stamp bytes long.
2. The region after byte 96 parses as a msgpack array of four or five elements that consumes the region exactly — trailing garbage fails.
3. The first element is a plausible timestamp, the fourth is a field map carrying our FIELD_CUSTOM_TYPE discriminator and a FIELD_CUSTOM_META with a name and a sender key.
4. The authoritative test: recompute the address from the name in FIELD_CUSTOM_META (section 4) and require it to equal the destination hash the entry is stored under.

Steps 1-3 can, with residual probability, be satisfied by ciphertext. Step 4 cannot be satisfied by accident: the entry must contain a name that hashes to its own address. For a mailbox entry to be misclassified, its ciphertext would have to embed a name whose channel-namespace hash equals the mailbox's identity-derived hash — a second preimage across disjoint namespaces. The realistic false-positive is an entry deliberately constructed to pass, and that is not a false positive at all: an entry addressed to hash(name) that names itself correctly is a channel post, possibly with garbage content, which an open channel admits by definition. Misclassification can waste channel storage; it cannot expose mailbox entries.

Classification of closed-group entries cannot work that way — the payload is ciphertext and carries no name, and no amount of parsing classifies ciphertext positively. The proposal (with section 4's caveat) is an explicit envelope outside the ciphertext:

destination(16) || tag+version || group_pubkey || group_signature
               || ciphertext

The node classifies by recomputing the address from the embedded public key — fixed aspects, no name needed — and requiring equality with the entry's destination, then verifying the group signature over destination and ciphertext against that key. Both checks need no secret. The signature additionally means non-members cannot inject entries into a closed group, which open channels by design cannot promise. The price is the metadata stated in section 4: the envelope is what makes the entry observably closed-group traffic, linkable by its public key. That trade — classifiable but visible, versus hidden but unservable under section 3's rule — is the crux Lew should weigh when reviewing this proposal.

What the signature proves. Every post carries a signature, and the sender's public key travels in FIELD_CUSTOM_META because unpack_from_bytes (LXMessage.py:747) resolves the sender through RNS.Identity.recall (LXMessage.py:776) and leaves the signature unverified when that returns nothing (LXMessage.py:809-816), which in a public channel is the common case. Verifying the in-message key against the source hash makes a channel self-supporting rather than dependent on whether an announce happened to arrive. But this must not be oversold, as an earlier draft did with "cryptographically attributable": the key is attacker-chosen material that travels in the message, and the source hash derives from it. Verification therefore proves key continuity — two posts verified against the same key were made by the same key holder — and nothing about who that holder is. An impersonator mints a fresh keypair, copies a display name, and every one of their posts verifies. The remedy is the same as for look-alike channel names: the client displays a short hash prefix of the author identity beside the display name, so two authors who read alike are visibly distinct. Key continuity plus visible key prefixes is the honest offer; it is more than nothing, and less than identity.

The key costs 64 bytes; on narrow links a client may send it only for the first message per author per time window.

6. The directory, and creating a channel

A node cannot invert a hash, so it cannot enumerate channels from stored entries alone. It does not have to: for open channels the name travels inside the message and is verified on arrival, so every node learns of a channel the moment its first message passes through. The directory builds itself out of traffic, network-wide, with no registry, no gossip protocol and no configuration.

Closed groups never appear in any directory. Precisely: the node knows a classified group's address, its public key and its traffic volume — it can enumerate that a group exists — but it never learns a name, and the directory lists names.

Creating a channel is therefore not an operation. A client picks a name and posts. The channel exists, and it appears in the directory of every node that sees the message. There is nothing to register and no one to ask.

The cost is that names are unowned, so squatting and homoglyph confusion ("general" against "genera1") are possible. An earlier draft called this "the same trade Meshtastic makes", and that equivalence is false: a Meshtastic channel name collides only within RF range, while this namespace is worldwide — there is exactly one "general" for the entire connected network, and whoever posts to it first shapes it for everyone. The global namespace makes squatting strictly worse than in the systems this feature borrows from, and two mitigations follow. Directory entries must be ranked and bounded by activity, not merely accumulated, or the listing becomes a spam surface. And the client must display a short hash prefix beside the name, so two channels that read alike are still visibly distinct.

7. The retrieval protocol

Three request handlers are registered on the lxmf.propagation destination alongside the existing /offer and /get. Python nodes do not know them and will fail the request, which doubles as the fallback when discovery is stale.

/channel/list returns the directory: name, hash prefix, an activity figure and the timestamp of the most recent post. Open channels only, paged and bounded.

/channel/get takes a channel name, not a hash, plus an optional cursor. The node derives the hash itself and serves only entries classified per section 5. Passing the name rather than the address is what keeps section 3's rule enforceable for open channels: there is no name that produces a mailbox address, so the endpoint cannot be aimed at one.

/channel/auth admits a closed-group reader, under section 4's proposal, by proof of key possession. The client presents the group public key; the node recomputes the address from it and, if it holds classified entries for that address, issues a random nonce; the client returns a signature over the nonce and the link ID under the group key; the node verifies against the presented key and serves that one address for the lifetime of the link. At no point does a group secret reach the node, and knowledge of an address alone gets nothing: the address must be derived from a key the client demonstrably holds, which is the verifiable binding the earlier HMAC design lacked (section 4). Since closed-group entries are also positively classified by their envelope, section 3's rule holds on this path with or without the auth step; what auth adds is that non-members cannot remotely harvest a group's ciphertext and traffic pattern through our own endpoint. The local view of a node operator is out of scope for auth, as section 3 states.

Retrieval never deletes. Python's /get treats the client's "have" list as a purge instruction (LXMRouter.py:1509-1514), which is right for a mailbox and fatal for a channel, since the first reader would empty it for everyone. Channel entries on our nodes expire on their own TTL and a per-channel ring buffer instead.

8. Discovery

Position 6 of the propagation node announce is a metadata dict, and pn_announce_data_is_valid checks only that it is a dict (LXMF.py:224-244). Unknown keys pass validation untouched; the receiving router stores the dict on the peer object (LXMRouter.py:2018) and otherwise ignores what it does not know. LXMF reserves PN_META_CUSTOM = 0xFF (LXMF.py:138) for exactly this.

Our node advertises channel support under a namespaced key there: protocol version, which channel types it serves, directory size, and the minimum stamp cost it requires for channel posts. Because propagation node announces travel over the ordinary announce mechanism, every client in the mesh sees them. lnmsg collects them, filters on the capability key, and selects by hops_to. That is the automatic discovery the feature needs, and it costs nothing upstream.

One caveat, from the LXMF source itself: the metadata fields "may be highly unstable in allocation and availability until the version 1.0.0 release, so use at your own risk until then, and expect changes!" (LXMF.py:128-131). The mechanism is sound, the field numbering is not guaranteed. Our entry therefore carries its own version field and the client must tolerate absence and garbage.

9. Storage, cost and fairness

Two directions of cost, and both need a deliberate answer.

Inbound. A node participating in the peer network receives everything, not only channels. Ours will store and forward the entire LXMF propagation traffic of the reachable network. That figure should be measured on a real node before the server is built, since it decides the hardware floor.

Outbound. Our channel messages come to rest on every Python node in the network, for up to the thirty-day MESSAGE_EXPIRY (LXMRouter.py:38, applied from receive time in clean_message_store, LXMRouter.py:1144-1163), and nobody ever collects a channel post, so until expiry only storage pressure removes them. Under pressure the eviction pass weighs every entry by get_weight (LXMRouter.py:1056-1067) — priority weight times age times size — and evicts the heaviest first (LXMRouter.py:1188-1196). The stamp value is stored with each entry and eviction never consults it. An earlier draft claimed the opposite, citing this very code, and built its politeness story on posts carrying deliberately low stamps so channels would be "first evicted". That claim is withdrawn: no such lever exists. What the weighting actually does is evict big-and-old first and spare operator-prioritised destinations, so an active channel competes with other people's mail on exactly those terms — it does displace mail on foreign nodes under pressure. The honest levers are the remaining ones: keep posts small (size is a linear factor in the weight), keep volume moderate, and keep the footprint visible and measured, which is section 10's bargain rather than a technical trick.

Stamps are admission control, not eviction control. Every post must carry the proof of work section 2 describes — at least 13 bits against any conforming node, 16 to clear every default configuration — and our clients mint to the announced cost of the node they post through. That is a mandatory floor the network enforces, not a knob of ours. Above that floor, a channel may declare its own minimum stamp cost as a spam barrier, and here the earlier draft's contradiction has to be resolved rather than papered over: one stamp value cannot be pulled low for eviction politeness and high for spam defence at once. The resolution is that the politeness direction never existed (see above), so the stamp is pulled in one direction only — upward, as a cost on posting. Its enforcement is also honestly narrower than "the network": our nodes refuse to serve entries below the channel's declared minimum and our clients refuse to display them, but a Python node stores and floods anything at or above its own floor regardless. A per-channel stamp floor filters what readers see through us; it does not keep spam off the carrier.

Channel entries on our own nodes live in a separate quota from mailbox entries, so that a busy channel can never crowd out the mailbox function we also promise to provide.

The flood is global and the use case is local. This is a real mismatch and it gets recorded as a weighed decision, not smuggled past. The mechanism puts every post of every channel onto every propagation node in the connected network for up to thirty days, while the motivating use case — "type a name, talk to whoever is around" — is local chat. Alternatives were considered. Carrying channels only on our own nodes avoids imposing on foreign operators but gives up the free transport that is this design's entire reason to exist, and is kept as the degraded mode in section 10 rather than the default. Regionally scoped names ("hb.general") reduce reader collision but change nothing about propagation — the carrier does not read names, every post still floods globally. A sender-chosen TTL shorter than thirty days does not exist in the protocol: expiry is the storing node's constant, counted from receive time, and nothing in the message can lower it. So the trade is accepted for v1 with open eyes: global flood is the price of zero-infrastructure distribution, it is bounded by the stamp floor and the smallness of chat messages, and the inbound measurement above doubles as the check on whether the price is as low as this paragraph assumes. If the measured numbers say otherwise, the decision gets revisited, not defended.

10. The compatibility bargain

Everything above rests on Python nodes accepting without inspection and flooding without filtering, gated only by stamps and peering keys. That is a factual property of the current implementation, not a promise anyone made us. A single upstream commit restricting storage to destinations that have been announced would end the free-transport half, and from a node operator's perspective that would be an entirely reasonable change.

This cannot be secured technically, only socially. We say plainly what we are doing, we make it identifiable in the announce metadata, and we keep our footprint on foreign nodes visibly small. Doing it quietly and being found out later closes the route permanently.

The degradation plan, decided now rather than improvised later. If upstream starts classifying or rejecting channel entries — requiring announced destinations, parsing payloads, or filtering our discriminator — the design degrades to an overlay instead of breaking. Our nodes are full propagation nodes that peer with each other statically, not only by autopeer, so channel distribution continues over our own peerings with the same sync protocol; clients already post and read through our nodes, so nothing changes for them. What is lost is exactly the free transport: reach shrinks from every propagation node to the connected set of our nodes plus whatever Python nodes still carry unclassified traffic. The mailbox function is untouched either way, because our nodes are conforming propagation nodes first. To notice the change when it happens rather than months later, a canary: periodically post a test channel message through a Python node and confirm arrival at one of ours over a Python-only path; when that stops, the assumption behind sections 2 and 9 has expired and the overlay mode becomes the documented default.

The conformance obligation is the ordinary one: our node has to be a correct propagation node first and a channel node second. Stamp validation, peering keys, sync limits, throttling and announce format all have to match Python exactly, or autopeering will not happen and none of this runs. Channels are an addition to a compatible node, never a deviation from one.

11. Open questions

• The inbound storage and bandwidth figure for full peer participation (section 9) is unmeasured. It should be measured before the server is designed, not after — it decides both the hardware floor and whether section 9's global-flood trade is as cheap as assumed.
• The closed-group proposal in sections 4, 5 and 7 needs its own review: whether the shared-keypair group secret is acceptable, and whether the envelope's metadata cost (visible group existence, linkable public key) is a price the use case can pay.
• Whether closed groups need key rotation, and what happens to the address when a member leaves, given that the address is derived from the group keypair.
• Directory ranking: what activity measure, over what window, and how large a listing before it needs paging or filtering.
• Whether channel messages should carry a FIELD_THREAD equivalent, so replies can be shown threaded rather than flat.

Telemetry

How a node reports where it is and how it is doing, and why almost none of that format is ours to decide. This applies to every firmware and every platform port, present and future.

The goal

A node — a tracker in a rucksack, a solar relay on a roof, a handheld with a display — produces readings that belong somewhere else: a position, a battery charge, a link quality. Telemetry is the path from that reading to a map pin or a database row, over the same mesh the node already speaks.

The receiving end is not ours. Sideband and Columba display telemetry today, from any peer, without knowing what produced it. A node that emits the format they already read is useful on the day it ships; a node that emits its own format is useful when someone writes a viewer for it. So the format is adopted first and the node conforms to it, not the reverse.

Where the format comes from, and how far it is settled

Telemetry rides inside a normal LXMF message, in the fields dictionary of the encrypted payload — not in a destination of its own, not in a side protocol. It therefore inherits everything LXMF already provides: end-to-end encryption, the three delivery methods, propagation nodes, and receipts. A peer that does not know the field sees a message with no text, which is the correct failure — subject to the empty-content rule below.

The field numbers are LXMF's (leviculum-lxmf/src/constants.rs:52-78). Three matter here: FIELD_TELEMETRY (0x02) carries one node's readings, FIELD_TELEMETRY_STREAM (0x03) carries many nodes' readings collected by a third party, and FIELD_COMMANDS (0x09) carries the request that asks for the second one.

The content of FIELD_TELEMETRY is Sideband's, defined by its Telemeter class in sense.py: a msgpack map from sensor ID to that sensor's packed value. Sideband is the origin of this format and, for most of it, the only implementation. Columba reimplements two sensor IDs of the twenty-four — time and location — in TelemeterCodec.kt, naming sense.py as its own reference. That is corroboration for those two, not a second independent implementation of the format. For every other sensor we encode, we are the second implementation, and the accept-set rule of Python-RNS compatibility applies with full force: we must read what the origin emits, not only what we would have written.

How settled the format is differs by part, and the difference decides how much freedom a reader has:

Why citations to Sideband and Columba carry no line numbers. This is a new rule, stated here rather than inherited: those repositories are not in this tree and not pinned by it, so a path:line citation into them cannot be checked by the citation guard and cannot be trusted to still point at what it claims. They are cited by symbol, which survives the edit that moves a line, plus the upstream commit the reading was taken from — Sideband 2000d81, Columba 0930293 — so a reader can reconstruct the line. Checks that are actually checks argues the converse case for in-tree references and does not cover out-of-tree ones; this is the gap being filled, not an application of that page.

Which viewer wins a disagreement

Columba is the app this project targets: it is the one whose users we serve first and the one we can realistically patch. That ordering decides what we build for. It does not decide what is correct on the wire, and the two questions are answered in this order:

1. Does one form break the other implementation? Then that form is a bug, not a tie, however confidently it is implemented. Emit the form both accept and report the bug to whoever emits the other.
2. Are both forms legitimate readings of the format? Then prefer the one Columba displays.
3. Would our output only be understood by a build carrying our own patch? Then it is not permitted, whatever step 2 said.

Step 3 is the operative test, and it is the one that can be checked before the change lands rather than after: run the output against an unpatched build of both viewers. Three concrete temptations it rules out, each of which would work and each of which would leave our node broken against every implementation but the patched one — a receiver taught to accept an unverifiable signature so a node can skip announcing its delivery destination; a receiver taught to ignore timestamps entirely so a node can skip keeping a calendar at all; a receiver taught to reinterpret a placeholder coordinate so a node can transmit without a fix.

Rules that hold regardless of platform

Telemetry always stamps — never ahead of the calendar estimate

SID_TIME and the location sensor's last_update are real UTC seconds, and they are load-bearing at the receiver in three separate places:

• Storage keys on them. Sideband dedups on exact (source, ts) equality and otherwise inserts, so a wrong timestamp is stored rather than rejected — a node emitting a wrong time appears in the viewer, wrongly dated.
• Collection filters on them. A collector serves only rows strictly newer than the requester's stored cursor.
• The cursor advances over every row seen, saved or not. So one row timestamped in the future raises a requester's cursor past it permanently: every honest later reading from that collector is "not newer" forever, and nothing anywhere logs a refusal.

That third mechanism is why stamping is directional. A future stamp is poison — permanent, silent, and it hurts every subscriber of a collector, not the sender. A past stamp merely sorts too far back: visible, attributable, harmless. An earlier version of this page drew the conclusion that a node without a verified clock must not report at all ("arms 1–3 or silence"); that rule is withdrawn. It silenced exactly the switch-on-and-it-works trackers this feature exists for, and it defended the cursor at the wrong end.

The binding rule comes from the anchor model of Time and clocks: a telemetry node always stamps with its best honest calendar estimate, and never ahead of it — every fallback anchor lies in the past, so an uncertain calendar errs backwards by construction; a source that is wrong but plausible is stamped as-is, the residual the anchor model names. A node whose calendar is still at the build floor reports recognisably old readings, and the cost is priced per path. Where the reading is displayed directly, it sorts to the back of the viewer: visible, attributable. Where it travels through a collector, the real price is higher: a collector serves only rows above a requester's cursor, so a birth-stamped row sits below every already-synced requester's cursor — not sorted backwards but invisible to that requester, indistinguishable from loss, until the tracker heals. The cost ends at the node's first plausible contact — outright at arms-1–3-quality time, provisionally when healed from traffic (the one honest cost).

The cursor is defended at the reader instead: our collector (#239) clamps inbound stamps beyond its local plausible-now to receive time for indexing and cursor advancement, keeping the original stamp as local display information (ingress clamping). The clamp is armed only while the collector's own calendar is healed: an unhealed collector clamping "to receive time" would drag every honest current stamp down to its own ancient notion of now and blackhole them below every synced cursor. Until it heals, it takes in-window sender stamps as-is — the same stamps double as its healing evidence — and rows ingested before healing keep their index stamps; there is no re-index. Dedup keys are never clamped: dedup runs on content and transient ID, the clamp covers ordering and cursor semantics only. And what a collector serves is the clamped value — a stream row has one timestamp slot — while keep-for-display stays local; note the stated limit that the row's packed_telemetry still carries the sender's raw SID_TIME claim to any downstream parser. Foreign future stamps then cannot starve anyone's cursor through us.

A node still has to know which arm anchored its calendar — the provenance requirement of Time and clocks — not as a gate on reporting but as the diagnosis surface: "why does this tracker report from 2026-01-01" must be answerable from the node itself.

No fix, no position — and absence has one encoding

A sensor with no reading is absent from the map. It is never present with a placeholder: no zero coordinates, no last-known value restamped as current, no accuracy invented to fill the field. A viewer cannot distinguish a placeholder from a measurement, and 0°/0° is a real place in the Gulf of Guinea.

The format does not decide how absence is spelled, so we do. Sideband packs every active sensor, and a sensor with no data packs as its SID mapped to None — key present, value empty. That is two encodings of absence in one format, and the choice is ours to fix:

• We emit the omission. A sensor without a reading contributes no key. Telemeter.from_packed instantiates only the sensors present in the map, so an omitted key round-trips cleanly.
• We accept both on read. A SID mapped to None is a sensor without a reading, not a malformed message. This is the accept-set half of Python-RNS compatibility: the origin emits a form we would not write, and refusing it would be our defect.

The encoder is multi-sensor from the first line

The unit is a Telemeter with n sensors, not a position packet with extras bolted on later. Position, battery, temperature and link quality are the same code path with different sensor IDs, and every board that measures anything gets to report it without a second design.

The justification is the format's own extension mechanism, not our future plans: a viewer ignores a sensor ID it does not know, so emitting a reading no current viewer displays costs one map entry and breaks nothing. A sensor left out of the encoder, by contrast, needs a new design to add later.

Followed through on the boards: a node reports everything it can measure, so both LNode builds carry the nRF52's die temperature as a Temperature reading (SID 0x07) whether or not a baseboard is fitted. The die thermometer belongs to the SoftDevice, so it is read through sd_temp_get and never off the TEMP registers; its 0.25 °C step is already exact at the two decimals Sideband rounds to, so the value goes on the wire unrounded. Battery charge stays feature-gated — it needs a baseboard that has a gauge — and an absent sensor contributes no key.

The same rule adds the physical link (SID 0x05), which is the one sensor that describes the mesh rather than the box. It is the last frame the radio received, not a mean over a window and not the best of one: a mean on a mesh averages over whichever neighbours happened to transmit, so it falls when a distant node joins and reads on a viewer as the near link degrading. The last frame is also what the references report under this name — RNS.Link.rssi/.snr keep the last received packet's figures (RNS/Link.py), and RNodeInterface's r_stat_rssi belong to the frame the stat bytes arrived with — so our rssi and a Python-RNS peer's rssi are the same quantity. q is Reticulum's own SNR-to-quality map (RNodeInterface.Q_SNR_*, whose floor drops 2 dB per spreading factor), not a scale of ours; where the PHY has none defined the slot goes out nil and the two measurements beside it still go.

A board that has heard nothing for longer than the fastest reporting cadence sends no physical-link sensor at all, which is the general absence rule applied to a reading that would otherwise never expire: a stale rssi is the one number in the set that says the opposite of the truth. The rule and its bound live in leviculum-nrf/telemetry-policy/src/link.rs, where a host test can reach them.

Two sensors of the type stay empty on every board we build, and for a reason worth writing down rather than a gap. charging inside the battery sensor is None because a voltage divider cannot tell charging from discharging and no board brings a charger status line to the MCU — upstream's own answer on the RAK4631 (NRF_APM) reads the nRF52's USB VBUS state, which is "USB is plugged in", not "the pack is gaining". power_production is empty for the same kind of reason: not one carrier exposes a panel current, and on the Solar Node in particular every XIAO pad is accounted for in boards/solarnode.rs with nothing left over (Codeberg #233).

A reporting message carries no text

A telemetry message sets content and title to empty. This is a hard wire requirement, not tidiness: Sideband suppresses the notification for a telemetry-bearing message only when both are empty, so a reporting node that fills in either one notifies its recipient once per reporting interval, forever, and the feature is indistinguishable from spam.

Delivery is opportunistic unless a port shows otherwise

Of LXMF's three methods, a reporting node uses the opportunistic single packet by default. A direct delivery pays a link setup — three round trips before any payload — for a payload of roughly fifty bytes, and a propagated delivery pays a node round trip and adds a delay that makes a position stale. A port that needs delivery confirmation, or that reports to a target it can only reach through a propagation node, may choose differently, and states why.

Cadence is policy; airtime is the interface's business

A telemetry producer states when it wants to report: a minimum interval, a minimum distance moved, a maximum interval as a heartbeat so that "stationary" stays distinguishable from "dead", an accuracy threshold, and a settle time so a cold start does not spend the channel on a drifting first fix.

It does not state when the radio may transmit, and it holds no airtime figure of its own. Duty cycle, spacing and back-off belong to the interface — see Interface isolation and Regulatory airtime, which also settles how any such figure is to be described: modelled, and a floor rather than a total, because the board's own meter clears when it is read.

The configuration surface itself is settled in #236: setting a target is the on-switch, and the tracker and station profiles bundle the cadence defaults.

Activation is configuration, not firmware

Setting or changing the telemetry configuration never requires rewriting firmware. lnflash gains a config-only session — the same post-flash serial configuration channel, entered without a UF2 write — and the #238 control envelope and #235 remote management make the same configuration changeable at runtime later. The reason is operational: a node already running in the field must be adoptable into telemetry, and retirable from it, where it hangs.

One input, and it is the address. Most users configure nothing beyond the target, so the target is the only thing configuration may require: profiles bundle the cadence and one of them is the default (station — a node that does not move is the common case, and a tracker misconfigured as a station still proves it is alive on the heartbeat, where the converse merely costs airtime). Everything else is an expert flag underneath a preset, in the same shape as the radio menu.

Sending the position is the switch for sending everything

Reports go out iff both a target is configured and a position source is — a fixed position set, or a GNSS receiver built into the firmware and not switched off (Lew, 2026-08-30). The reading is intent, not possession: a receiver that has never seen sky still counts, because the four use cases behind this feature — tracker, sensor node, mobile transport node, quasi-modem — are all nodes whose operator meant to say where they are, and a tracker that goes silent in a garage is indistinguishable from a dead one. Such a node keeps reporting on the heartbeat with the position absent and its other sensors fresh, which is the designed behaviour and not a degraded mode. GNSS is optional throughout; a fixed position is settable on any board, with or without a receiver.

What the rule refuses is the unconfigured node: a target and no answer of any kind to "where am I". It sends nothing — not a heartbeat, not a battery reading — and says why, state=no-position-source on the same surface and the same cadence rule as awaiting-key. Position-less telemetry is deliberately not a mode: a node that reports readings a collector cannot place is a row on a map with nowhere to put it, and the operator who wanted one had only to set a position. Setting one, or flashing a build that has a receiver, leaves the state at once — it is a runtime path, like applying a target, and needs no reboot.

The destination hash alone is enough

A user knows the LXMF address. Requiring the public key alongside it would make the common case the hard one, so the key is optional wherever a target is set: hash-only is expected, and the node resolves the key itself over the air — a path request is answered with the destination's announce, and the announce carries the identity.

This creates a state that did not exist when a target implied a key: the node holds a perfectly valid target it cannot yet encrypt to. That state is stated, not waited out silently. A reporting node says which of four it is in — off, no-position-source, awaiting-key, ready — on the same surface as its clock provenance, and a target that never resolves is then a visible condition rather than an absence of packets. no-position-source outranks awaiting-key in that line: a node that will not report anyway must not spend airtime chasing a key it has no use for.

The consequence for the previous rule is that the immediate report fires on key arrival, which for a hash-only target is later than the moment the target was set. A frame that carries a key skips that wait, which is the whole benefit of carrying one.

Setting a target emits one immediate report

When a telemetry target becomes usable — set or changed with a key, or set by hash and then resolved — the node sends one report at once, regardless of the configured cadence. Success must be observable within seconds: a station profile on an hourly heartbeat would otherwise leave the operator without any confirmation for up to an hour. The immediate report follows every other rule in this document — no fix, no position; empty content and title.

The report is owed until it is actually sent, not until it was first due: a node that has the key but no path yet retries rather than counting an attempt it could not make. And a report that a target cannot receive is a report nobody can verify, so the node announces its own delivery destination before sending — the announce is what puts our public key in the receiver's hands.

A request from the target triggers one report

Sideband lets a peer ask for telemetry on demand: an LXMF message whose FIELD_COMMANDS field (reference/LXMF/LXMF/LXMF.py:16) carries the TELEMETRY_REQUEST command with a timebase. A reporting node answers one such request with an immediate report — the same report a target write arms, subject to the same rules (owed until sent, announce first, attempt floor). That gives the operator a position on demand instead of at the profile's cadence, and gives a field test a way to force the whole chain — path request, answer, data — at a known moment.

The gate is authentication, not reachability: the request must name the configured target as its source and carry a signature that verifies against the target's identity. The target is the only allowed sender for now; a general allow list is a later step and will follow the collector rule above — explicit, empty by default, set only off-radio. A request from anyone else is answered with nothing but a debug line, because an unauthenticated trigger for a radio transmission is a remote airtime primitive.

Requests are rate-limited to one accepted request per min_interval_ms of the active profile; a request inside the window is logged and dropped, not queued. The request's timebase is read but does not change the answer: a node keeps no history, so the current reading is the answer to every timebase.

Sideband's own source is not vendored under reference/, so the command id (0x01) and the value shape (a list of command maps, [{0x01: <timebase>}]) are a documented assumption — recorded at COMMAND_TELEMETRY_REQUEST (leviculum-lxmf/src/telemetry.rs:678) — to be verified against a captured Columba/Sideband request and then pinned as a fixture.

On the host side, lnsd neither registers an lxmf.delivery destination nor runs a telemetry policy today, so there is nothing for a request to trigger there; the screen in leviculum-lxmf is the seam a host-side consumer will reuse when that changes.

Fan-out is the expensive shape; collection is the cheaper one

Telemetry to n recipients is n individually addressed and individually encrypted messages. Mutual reporting in a group of n is therefore n(n−1) messages per interval — thirty a minute for six people at a one-minute cadence.

Routing the same group through a collector is n reports plus, for those who want to see the others, n request/response pairs: eighteen rather than thirty for the same six. The saving is real but it is roughly a third, not fivefold, and it is not free in kind — a stream response carrying several sources will exceed one packet and become a link plus a resource transfer, where a report is a single packet. Both figures belong in a port's own arithmetic; neither is a licence to skip it.

There is no third shape. Reticulum has no multi-hop broadcast at all — see Public channels over LXMF, which settles this at the protocol level rather than by what two apps happen to implement. LXMF's FIELD_GROUP is conversation metadata and not a delivery mechanism; it would not produce a broadcast even if every viewer read it.

Relaying someone else's readings needs permission

A collector redistributes positions of people who are not asking for that redistribution. It therefore answers requests only from an explicit allow-list, empty by default, set only through a path that is not the radio: on a host that is the config file, as remote_management_allowed is (leviculum-std/src/config.rs:119, empty by default at leviculum-std/src/config.rs:375); on a firmware with no filesystem it is the local control channel, which is the same requirement in a different envelope.

The same applies to precision. Where a deployment wants a node's position blurred, the blurring happens at the producer, before the reading is packed — a receiver's promise to round a coordinate is not privacy.

A port may ship send-only

Emitting telemetry needs an encoder, a target and a cadence. Consuming it needs the inbound LXMF path, a peer table and something to show. A port may implement the first without the second, and nothing in this document may be read as requiring both: a tracker that cannot receive is a complete node for its purpose.

The collector exchange

Two implementations exist and they disagree, so this table is normative for us rather than descriptive of them.