feat: SDK improvements for Meshtastic-Android hard cutover

[jamesarich]

Summary

Hard-cutover integration of meshtastic-sdk into Meshtastic-Android revealed SDK gaps, missing APIs, and documentation staleness. This PR addresses all findings across multiple audit rounds.

API additions (29 commits, 97 files, +13.5k lines)

Phase 1 — Core gaps:

• RadioClient.textMessages flow, RadioClient.channels StateFlow
• BleTransport(address) factory for Android
• sendRaw(ToRadio) for MQTT proxy/XModem
• Complete AdminApi — all 9 remaining operations for full proto coverage

Phase 2 — Feature APIs:

• AdminApi.forNode(dest) — remote node admin
• sendReaction() — emoji reactions
• getDeviceMetadata(), requestNodeInfo()
• editSettings {} batch support + AdminBatchScope
• SFPP protocol handling + MeshTopology graph utility
• Congestion metrics, presence timer, retry extension, Store-and-Forward impl
• AdminResult.RateLimited, AdminResult.getOrThrow()
• Config DSL builders (23 extension functions)
• Admin batch getters

Quality:

• Firmware compliance audit fixes (P0/P1 bug fixes)
• Thread-safety, timeout, flow caching, error mapping improvements
• KDoc on all public API symbols
• Stale Phase-2 labels removed from implemented features

Documentation

• api-reference.md fully synced: NodeChange.CameOnline/WentOffline, AdminResult.RateLimited, StoreForwardApi, 23 config builders, forNode(), sendReaction/sendRaw
• error-taxonomy.md, integration-guide.md, consumer guides updated
• Migration guide examples made exhaustive
• Stale sample paths fixed in ADR-003

Tests (565 total, 0 failures)

• AdminApi RPC coverage, engine integration, handshake FSM
• Config DSL, admin batch, CommandDispatcher, TelemetryApi
• StoreForward protocol, WireCodec edge cases
• RadioClient send/sendText/sendReaction

Samples

• Fixed 5 compilation errors (NodeChange + AdminResult exhaustiveness)
• All 3 sample projects build clean

---

⚠️ Merge order: This PR should merge first. CI will publish a 0.1.0-SNAPSHOT to Sonatype Central. The companion Meshtastic-Android PR depends on these changes via includeBuild (composite build) during development, or via the published snapshot artifact in CI.

[Copilot]

Pull request overview

This PR closes multiple SDK gaps discovered during a hard cutover integration into Meshtastic-Android by adding missing public APIs (notably Store-and-Forward, presence tracking, retry helpers, and various convenience builders), expanding test coverage, and syncing documentation/specs to the updated behavior and API surface.

Changes:

• Add new public APIs and utilities (StoreForwardApi, presence NodeChange events, congestion helpers, retry policy, node status/mesh-node helpers, channel helpers, shared-contact URL support).
• Expand protocol/engine behavior coverage with extensive new unit/integration tests (WireCodec, StoreForward/SFPP, presence timer, external config changes, etc.).
• Refresh docs and samples for new sealed variants, updated semantics, and new CLI conformance scenario.

Reviewed changes

Copilot reviewed 103 out of 105 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
transport-ble/src/androidMain/kotlin/org/meshtastic/sdk/transport/ble/BleTransport.android.kt	Adds Android factory for creating BleTransport from persisted MAC address.
testing/src/commonMain/kotlin/org/meshtastic/sdk/testing/FakeRadioTransport.kt	Adds test injection helpers for arbitrary packets and Store-and-Forward responses.
testing/api/testing.klib.api	Updates KLIB ABI surface for FakeRadioTransport injections.
testing/api/jvm/testing.api	Updates JVM ABI surface for FakeRadioTransport injections.
samples/parity-app/src/commonMain/kotlin/org/meshtastic/sample/MeshSampleController.kt	Updates sample to handle new NodeChange presence events.
samples/cli/src/main/kotlin/org/meshtastic/cli/conformance/Scenarios.kt	Refines cs2 semantics and adds cs7 unicast-DM conformance scenario.
samples/cli/src/main/kotlin/org/meshtastic/cli/cmd/TuiCmd.kt	Updates TUI node event logging for presence events.
samples/cli/src/main/kotlin/org/meshtastic/cli/cmd/ConnectCmds.kt	Updates CLI JSON/human node events output for presence events.
samples/cli/src/main/kotlin/org/meshtastic/cli/cmd/ConformanceCmd.kt	Exposes cs7 filtering and execution wiring.
gradle/libs.versions.toml	Bumps Android Gradle Plugin version.
docs/SPEC.md	Syncs AdminApi spec (nodeDbReset signature change).
docs/protocol.md	Updates protocol notes (admin channel indexing, session-passkey timing, reconnect wake bytes, managed mode, heartbeat nonce behavior, BLE commit disconnect note).
docs/integration-guide.md	Adds Admin/config builder usage section and renumbers subsequent sections.
docs/error-taxonomy.md	Documents AdminResult.RateLimited and routing error interception mapping.
docs/decisions/003-tooling.md	Updates sample app paths in tooling ADR.
docs/consumer-guides/reactive-lifecycle-management.md	Updates guide examples for NodeChange presence events.
docs/architecture/meshtastic-android-migration.md	Updates migration guide for presence events and new AdminResult variant handling.
docs/api-reference.md	Expands API reference for StoreForwardApi, presence NodeChange events, new send APIs, AdminResult.RateLimited, config builders, forNode().
core/src/jvmTest/kotlin/org/meshtastic/sdk/MeshTopologyTest.kt	Adds tests for MeshTopology graph operations.
core/src/jvmTest/kotlin/org/meshtastic/sdk/internal/StoreForwardApiImplSfppTest.kt	Adds SFPP StoreForward event behavior tests.
core/src/commonTest/kotlin/org/meshtastic/sdk/WireCodecTest.kt	Adds additional framing/boundary/resync test coverage.
core/src/commonTest/kotlin/org/meshtastic/sdk/P2RoutingRpcTest.kt	Resolves NeighborInfo type ambiguity by aliasing proto type in tests.
core/src/commonTest/kotlin/org/meshtastic/sdk/P0ReliabilityTest.kt	Updates broadcast ACK expectations and adds want_ack broadcast timeout test.
core/src/commonTest/kotlin/org/meshtastic/sdk/NodeStatusTest.kt	Adds tests for online/connection/signal quality helpers on NodeInfo.
core/src/commonTest/kotlin/org/meshtastic/sdk/MeshNodeTest.kt	Adds tests for MeshNode convenience wrapper/accessors.
core/src/commonTest/kotlin/org/meshtastic/sdk/internal/NodeDiffTest.kt	Adds tests for diffNodeFields field categorization.
core/src/commonTest/kotlin/org/meshtastic/sdk/internal/ConfigMergeTest.kt	Adds tests for config/module-config merge helpers.
core/src/commonTest/kotlin/org/meshtastic/sdk/HandshakeFsmTest.kt	Renames/retitles audit section header.
core/src/commonTest/kotlin/org/meshtastic/sdk/ExternalConfigChangeTest.kt	Adds tests for unsolicited admin updates applying to local state + event emission.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/StoreForwardImplTest.kt	Adds StoreForward API integration tests using FakeRadioTransport.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/StoreForwardApiTest.kt	Adds basic StoreForwardStats and StoreForwardEvent sealed-shape tests.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/SharedContactUrlTest.kt	Adds tests for shared-contact URL encode/parse behavior.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/SfppHashTest.kt	Adds tests for SFPP hash properties (size/determinism).
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/RouteDiscoveryResultTest.kt	Adds tests for RouteDiscoveryResult assembly and formatting.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/RetryPolicyTest.kt	Adds tests for retry delay computation.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/PresenceTimerTest.kt	Adds tests for presence timeout/offline-online transitions.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/PositionUtilsTest.kt	Adds tests for position conversions/validation/distance/bearing.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/PayloadAccessorsTest.kt	Adds tests for packets/textMessages flow and new payload accessors.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/NodeIdsTest.kt	Adds tests for default-id formatting/parsing.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/NodeChangePresenceTest.kt	Adds tests ensuring presence changes are pattern-matchable NodeChange variants.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/NeighborInfoTest.kt	Adds tests for parsed NeighborInfo model.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/MqttEventsTest.kt	Adds tests for MQTT MeshEvent variants.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/MessageHandleRetryTest.kt	Adds tests for MessageHandle.retryWith behavior using a fake handle.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/DeviceCapabilitiesTest.kt	Adds tests for firmware version parsing and capability gating.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/ConnectionStateTest.kt	Adds tests for new ConnectionState convenience extensions.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/CongestionTest.kt	Adds tests for congestion level derivation and backoff suggestions.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/CongestionEmissionTest.kt	Adds tests for congestion warning emission behavior.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/ChannelUrlsTest.kt	Adds test for DJB2 channel-name hash.
core/src/commonTest/kotlin/org/meshtastic/sdk/ext/ChannelHelpersTest.kt	Adds tests for channel validation and empty-slot selection.
core/src/commonTest/kotlin/org/meshtastic/sdk/EngineTest.kt	Adjusts engine tests to use unicast packets where broadcasts now auto-resolve.
core/src/commonTest/kotlin/org/meshtastic/sdk/EngineAuditFixesTest.kt	Updates audit test to assert DeviceUIConfig is captured in ConfigBundle.
core/src/commonTest/kotlin/org/meshtastic/sdk/AdminResultExtensionsTest.kt	Adds tests for AdminResult extension helpers and getOrThrow exceptions.
core/src/commonMain/kotlin/org/meshtastic/sdk/TelemetryApi.kt	Adds telemetry RPCs for health/host/traffic-management metrics.
core/src/commonMain/kotlin/org/meshtastic/sdk/StoreForwardApi.kt	Introduces StoreForwardApi, StoreForwardStats, and StoreForwardEvent public types.
core/src/commonMain/kotlin/org/meshtastic/sdk/Storage.kt	Extends ConfigBundle to optionally include DeviceUIConfig.
core/src/commonMain/kotlin/org/meshtastic/sdk/SharedContactUrl.kt	Adds shared-contact URL encoding/parsing helpers and extension.
core/src/commonMain/kotlin/org/meshtastic/sdk/SfppHash.kt	Adds SFPP deduplication hash computation utility.
core/src/commonMain/kotlin/org/meshtastic/sdk/RoutingApi.kt	Disambiguates proto NeighborInfo type via alias in public API.
core/src/commonMain/kotlin/org/meshtastic/sdk/RouteDiscoveryResult.kt	Adds parsed traceroute result model + formatting helper.
core/src/commonMain/kotlin/org/meshtastic/sdk/RetryPolicy.kt	Introduces retry policy types and delay computation.
core/src/commonMain/kotlin/org/meshtastic/sdk/Result.kt	Adds ConnectionState helpers and AdminResult.RateLimited + AdminResult extensions/exceptions.
core/src/commonMain/kotlin/org/meshtastic/sdk/PositionUtils.kt	Adds reusable geographic computations (validation, haversine distance, bearing).
core/src/commonMain/kotlin/org/meshtastic/sdk/PayloadAccessors.kt	Adds RadioClient.textMessages flow and new payload decoding helpers.
core/src/commonMain/kotlin/org/meshtastic/sdk/NodeStatus.kt	Adds online/connection/signal quality helpers for NodeInfo.
core/src/commonMain/kotlin/org/meshtastic/sdk/NodeIds.kt	Adds default-id formatting/parsing helpers.
core/src/commonMain/kotlin/org/meshtastic/sdk/Node.kt	Adds presence NodeChange variants + new MeshEvent variants and external-config change kinds.
core/src/commonMain/kotlin/org/meshtastic/sdk/NeighborInfo.kt	Introduces parsed NeighborInfo model distinct from proto type.
core/src/commonMain/kotlin/org/meshtastic/sdk/MessageHandleRetry.kt	Adds MessageHandle.retryWith and retryability classification.
core/src/commonMain/kotlin/org/meshtastic/sdk/MeshTopology.kt	Introduces a topology graph utility built from NeighborInfo reports.
core/src/commonMain/kotlin/org/meshtastic/sdk/MeshNode.kt	Adds MeshNode consumer-friendly wrapper with flattened accessors.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/TelemetryApiImpl.kt	Implements new telemetry RPC variants and propagates RateLimited.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/RoutingApiImpl.kt	Updates neighbor-info RPC to use proto alias consistently.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/NodeDiff.kt	Adds internal node-diff helper used for changed-field reporting.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/EngineMessage.kt	Adds presence tick message and removes stale “Phase 2” wording.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/ConfigMerge.kt	Adds internal config merge utilities for section-based replacement.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/CommandDispatcher.kt	Extends RPC response decoding (Admin/UI/status/etc.) and StoreForward decode paths; maps RateLimited.
core/src/commonMain/kotlin/org/meshtastic/sdk/internal/Base64Url.kt	Centralizes base64url encode/decode for URL-based sharing features.
core/src/commonMain/kotlin/org/meshtastic/sdk/DeviceCapabilities.kt	Adds firmware version parsing and capability flags.
core/src/commonMain/kotlin/org/meshtastic/sdk/Connect.kt	Adds @since tag to connectAndAwaitReady documentation.
core/src/commonMain/kotlin/org/meshtastic/sdk/CongestionLevel.kt	Adds congestion metrics model and derived levels/backoff guidance.
core/src/commonMain/kotlin/org/meshtastic/sdk/ConfigBuilders.kt	Adds AdminApi config builder extensions for common writes and batching.
core/src/commonMain/kotlin/org/meshtastic/sdk/ChannelUrls.kt	Reuses centralized base64url helpers and adds DJB2 channel-name hashing.
core/src/commonMain/kotlin/org/meshtastic/sdk/ChannelHelpers.kt	Adds channel validation and slot selection helpers.
core/src/commonMain/kotlin/org/meshtastic/sdk/BatteryStatus.kt	Improves KDoc and adds @since tags for battery status helpers.
core/src/commonMain/kotlin/org/meshtastic/sdk/AutoReconnectConfig.kt	Minor KDoc wording update.
build.gradle.kts	Applies axion-release conditionally for composite-build compatibility and sets a composite fallback version.