trail-mate/docs/protocol_runtime_budget_policy.md

Protocol Runtime Budget Policy

Trail Mate treats mesh protocols as device-terminal runtimes, not desktop routers. Protocol adapters must protect the UI, LoRa radio, serial logging, SD card, and NVS budgets before trying to ingest background network traffic.

Reticulum Runtime Model

Reticulum runs as a low-frequency terminal ingress runtime.

Reticulum All carrier policy is a Wi-Fi-preferred auto policy, not a desktop-style dual-interface router policy. When the Reticulum Wi-Fi gateway is configured and ready, normal Reticulum TX, RX, and raw LoRa packet ingestion use the Wi-Fi gateway only. LoRa is the fallback carrier only while the Wi-Fi gateway is not ready. Explicit LoRaOnly and WifiGatewayOnly policies keep their literal meanings.

The product UI must expose this as one Reticulum bearer strategy (Auto, LoRa, Wi-Fi), not as independent LoRa/Wi-Fi toggles. The legacy persisted boolean fields are only the internal projection of that strategy. Runtime code must normalize them from reticulum_interface_policy before applying a Reticulum backend.

The same strategy must also gate the shared LoRa radio receive task. In Reticulum Auto, once the Wi-Fi gateway is ready, the shared LoRa RX task must stop arming RX, reading LoRa IRQs, or queueing LoRa packets until Wi-Fi is no longer ready. In WifiGatewayOnly, shared LoRa RX stays suppressed. In LoRaOnly, shared LoRa RX stays enabled. Outbound LoRa TX may still be queued only when the active strategy has selected LoRa.

Carrier selection is a runtime fact, distinct from configured interfaces. sendPacket, sendPacketOn, packet polling, legacy LoRa polling, raw LoRa ingress, and the shared RX gate must consult the same selection owner. A path learned on a previously selected interface must not reactivate that interface; when its interface is no longer selected, routing falls back to the original header on the currently selected carrier so that path discovery can converge there.

When the screen is on, realtime processing is limited to:

• LXMF direct traffic addressed to this device.
• LXMF traffic addressed to configured Reticulum groups.
• Path, proof, link, and cache traffic that this device explicitly requested or that is required by an active local session.
• Outbound user actions such as sending text, app data, and self announces.

Ordinary public announces and public discovery traffic are not realtime while the user is interacting with the device. They may be delayed for seconds or tens of seconds and replayed during an idle or screen-off maintenance window. The exception is lightweight peer-name projection: verified LXMF delivery announces may publish one coalesced contact-store update at a low awake-screen rate so Contacts and Chat can show the sender's display name without waiting for SD or NVS persistence.

Reticulum Client Discovery Projection

Trail Mate's Reticulum UI projections follow client-facing object semantics:

• Contacts and Chat consume lxmf.delivery announces as chat peers. The peer display name is decoded from LXMF announce app data using the upstream shape: raw UTF-8 display names and msgpack arrays whose first element is the display name are both valid. Current upstream LXMF arrays may contain additional fields such as stamp cost and supported functionality; supported parsers must ignore trailing fields they do not need.
• Network consumes non-contact Reticulum announces. nomadnetwork.node announces are web/service nodes, lxmf.propagation announces are message relays, lxst.telephony and legacy call.audio announces are telephony services, and unknown announces are diagnostics. These are not Contacts rows.
• A verified lxst.telephony destination may enrich a person already joined by identity; it does not create a service-shaped contact by itself.
• lxmf.propagation, legacy call.audio, and unknown announces may be stored for routing or diagnostic use, but they are never promoted into Contacts.
• Destination and identity hashes remain address/search metadata. They must not be used as the default display name. If a Reticulum peer has no display name, the UI uses Anonymous Peer; if a Nomad node has no display name, the UI uses Anonymous Node.
• The UI must not infer display names from hash shape, old local records, destination prefixes, or other historical artefacts. If a stored record contains an incorrect name, that is stored data to fix or replace, not a runtime display-name fallback.

Required Boundaries

• pollIncomingText() and pollIncomingData() may only return already materialised Trail Mate business messages. They must not parse Reticulum packets, verify announces, write SD files, persist peer caches, or send announces.
• Reticulum packet ingestion must run from a periodic runtime pump with an explicit budget. On ESP Arduino this is currently carried by the adapter processSendQueue() hook because it already runs outside the LVGL loop.
• LoRa and Wi-Fi Reticulum ingress must share the same public-discovery budget rules. Wi-Fi-only discovery throttles are not sufficient.
• Public discovery persistence must be deferred and coalesced. record_announce() and record_lxmf_address() on ESP Arduino are queueing APIs for runtime RX callers; they must not perform TSV upserts or other SD file I/O on the RX caller task.
• Explicit user address-book actions are the exception to RX-path deferral. Adding or removing a Reticulum contact may synchronously update lxmf_addresses.tsv because the user is already waiting for that action to complete. These paths must stay bounded, must not run from packet RX, and should use a blocking UI affordance if real hardware shows visible SD delay.
• Peer-name projection is not persistence. It may run while the screen is on, but it must be queue-backed and rate-limited; it must not trigger SD, TSV, or NVS writes.
• Peer cache persistence is dirty/coalesced. Code must not force maybePersistPeers(true) from RX paths, and non-forced peer dirty marking must not flush NVS from mesh_task.
• RX hot-path logging must be summary-first. Detailed logs are acceptable for local/realtime traffic and diagnostics, but public discovery should normally be represented by periodic counters.
• Shared LoRa RX task logging must also be summary-first. Normal IRQ/RX_DONE packets must not emit per-packet serial lines on ESP devices, because short packet bursts can stall UI-visible work even before packets reach Reticulum. If the mesh queue is full, the radio task must drop and count the packet instead of blocking on queue send.
• Reticulum runtime code executed by mesh_task must not allocate MTU-sized packet buffers or queued packet records as automatic locals. Carrier packet scratch storage belongs in adapter/interface members, and mesh_task needs enough stack headroom for Reticulum parsing and crypto call frames.

Maintenance Windows

A maintenance window is available only after the screen runtime has reported that the device is sleeping and the saver is not active for a stable grace period. A single instantaneous sleep-state check is not sufficient for SD persistence, because wake/saver/app transitions can otherwise let background Reticulum writes overlap foreground Contacts or Map SD reads. During stable maintenance windows the Reticulum runtime may:

• Replay deferred discovery packets under the discovery sample budget.
• Let the Reticulum directory worker persist one coalesced announce or LXMF address record to SD per slice.
• Publish deferred peer projections to the contact store at the faster maintenance-window rate.

The maintenance window still has finite budgets. It must not drain unbounded network queues in one cycle.

Reticulum directory persistence is a cancellable maintenance transaction on ESP-class devices. The directory worker must re-check the maintenance gate before heavy SD operations such as TSV scans, temp-file writes, remove, and rename. If the gate closes, it must stop the transaction, leave the original directory file intact, requeue the coalesced record, and wait for the next stable maintenance window. Foreground user actions such as manually adding a contact may still perform bounded synchronous address-book writes, but runtime announce/address discovery must not write or remove /trailmate/reticulum/announces.tsv or /trailmate/reticulum/lxmf_addresses.tsv while Contacts, Network, Map, Chat, or other normal UI pages are foregrounded.

UI Projection Budget

Contacts and Network are projections of Reticulum discovery state. They must not mount every known announce as a live LVGL object on small ESP targets. Long Contacts lists should render a visible window with spacer rows and preserve scroll position across timer refreshes. Data snapshots may contain more records than the visible UI window, preferably in PSRAM-backed storage when available. Reticulum Contacts search may stream over the SD address book, but the UI must still cap the number of projected rows.

LoRa TX Scheduler Budget

LoRa TX is an air-time budgeted runtime resource. It is not safe for UI, event-bus, BLE/phone facade, MQTT RX, key-verification RX, or application action paths to synchronously push arbitrary packets to the radio.

Required scheduler model:

• Public adapter APIs such as sendText() and sendAppData() enqueue work and return whether the work was accepted by the scheduler.
• Runtime protocol effects, key verification replies, routing replies, ACK retry, and MQTT downlink relay enqueue into bounded queues.
• One periodic adapter tick owns the air-time budget. The tick drains protocol actions, ACK retry, ordinary sends, and MQTT downlink under the same kLoRaAirTxBudgetPerTick.
• min_tx_interval_ms_ is global across those TX owners. A recent TX from one owner defers every other owner.
• MQTT downlink relay must keep official gateway behavior, but must deduplicate by from + id + channel, bound queue depth, bound per-tick drain, and report full/deferred/drop reasons.
• UI projections may show queued/deferred/failed states, but UI must not block waiting for the radio task or retry loop.

Forbidden scheduler shapes:

• injectMqttEnvelope() or MQTT RX hot path calling transmitWirePacket().
• sendAppData() directly calling transmitWirePacket() as the normal public path.
• Key verification RX handlers synchronously transmitting replies.
• Separate local drain counters that allow protocol actions, app sends, ACK retry, and MQTT downlink each to consume a full TX slot in the same tick.

Device I/O deferral is not successful airtime. The radio task retains the front TX packet and retries it with bounded exponential backoff when the radio device service reports Deferred. IRQ polling remains bounded and must never block a frame-critical display operation. Queue buffers and RX scratch use PSRAM on PSRAM-capable targets.

Protocol Switch Lifecycle

Changing MT/MC/RT is a runtime lifecycle transition, not a reboot contract. Before a backend is configured or installed, the radio and mesh tasks must cooperatively reach quiescent points outside board SPI calls and adapter work. Only then may the owner discard old-protocol TX/RX queues, configure the radio, install the backend, and switch Chat/Contacts active protocol projections.

If quiescing or installation fails, the old protocol remains active and its configuration is reapplied. A task must never be force-suspended while it may be inside a radio device transaction. Settings reports success/failure from this transition; it must not issue an unconditional software reset that makes a successful switch look like a crash.

Reticulum Runtime Owner Budget

The embedded Reticulum adapter is allowed to coordinate owners, but it must not re-own runtime state that already has a policy owner:

• RuntimeBudget owns phase-to-budget decisions.
• AnnounceScheduler owns announce pending/retry/rebroadcast cadence.
• DeferredDiscoveryQueue owns bounded public discovery deferral.
• RawRxTelemetry owns RX summary and suppression counters.
• AdapterScratchBuffers owns long-lived MTU packet scratch.
• PeerDirectoryService owns Reticulum peer hot-load and projection queueing.

This keeps UI responsiveness and packet fairness reviewable: budget decisions, queue pressure, telemetry counters, and projection backpressure can each be tested without reading the whole adapter.

Notification / Audio Budget

Notification is a product policy runtime. Chat, Contacts, Settings, and Team events may request feedback, but they must not directly own the speaker or vibrator.

Required model:

• Message notifications, contact/person notifications, and Settings tone preview call Notification runtime.
• Notification runtime reads user policy and emits tone/vibration intent.
• Platform audio adapter owns the ES8311/I2S speaker and microphone session.
• Call ring and call media have realtime priority. Non-call notification audio must not steal an active call audio session.
• If an audio owner cannot play, it must expose a failure/deferred result or log from the owner boundary.

Regression Checks

scripts/check_reticulum_runtime_budget_policy.py enforces the highest-risk boundaries:

• Reticulum polling APIs must not call the packet ingestion pump.
• Reticulum RX paths must not force peer persistence.
• Discovery budget names and helpers must not regress to Wi-Fi-only concepts.
• The Reticulum product adapter must forward the periodic runtime pump.
• Announce RX/TX hot paths must not allocate Reticulum packet buffers on the mesh_task stack.