Dual-backend 1/3 — RNS core + protocol seam

[torlando-tech]

Part 1 of 3 of a path-scoped split of feat/dual-backend-arch, sliced to stay under the 100-file Greptile review limit. The whole feature is the Python-RNS migration + the RnsBackend protocol seam (embedded-Python and native-Swift backends) + a runtime engine toggle. Net diff vs main is 190 files; this slice is 44.

This slice — RNS core + protocol seam

RNSAPI (seam + Compat), RNSBackendPy / RNSBackendSwift, PythonBridge, the app/*.py Python RNS sources, Columba.xcodeproj, build / support scripts, CI + docs.

Stacked series (merge in order)

1. this PR → main
2. app services + BLE bridge → base pr1-rns-core (67 files)
3. UI screens + tests → base pr2-app-services (79 files)

The three slices' union is byte-identical to feat/dual-backend-arch. They are chunks of one feature, not independent units: merge 1 → 2 → 3, and an individual slice is not independently buildable (fine for static review; not for per-PR CI).

Deferred (carried here, intentionally not applied)

• The LXMF-swift 0.4.0 / reticulum-swift 0.3.0 bump is not applied — the current pins are kept (the native Swift backend is verified against them); do the bump separately with a Swift-backend rebuild.
• main's newer interop test files are present on disk but not yet wired into the ColumbaAppTests target.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR introduces the RNS protocol seam — the RnsBackend protocol and its two concrete implementations (PythonRNSBackend wrapping embedded CPython, SwiftRNSBackend wrapping reticulum-swift/LXMF-swift) — plus the full Python rns_bridge.py module, PythonBridge C-API embedding, build/CI scripts, and the RNSAPI Compat/DTO layer. It is the first of three stacked slices and is not independently buildable.

• RnsBackend protocol seam with neutral DTOs (BackendEvent, PropagationSyncResult, StartParams) replaces all Python-namespaced types in the host; both backends conform identically from AppServices's perspective.
• PythonRNSBackend / PythonBridge add blockingQueue separation for long-poll calls (propagationSync, fetchNomadNetPage) and explicit drain-loop restart in start() — addressing previously-flagged drain starvation and drain-loop-death issues.
• SwiftRNSBackend adds linkLock protecting nextLinkId/links/linkStateTasks, explicit task cancellation in stop()/linkTeardown(), and a racing withThrowingTaskGroup in propagationSync to bound the wait.

Confidence Score: 3/5

The CI workflow clones sibling packages without branch/commit pinning, meaning it can silently test against different library versions than Package.resolved specifies — including the wrong branch for LXST-swift.

The CI clone step for LXST-swift omits -b feat/transport-agnostic, so xcodebuild on CI resolves a different branch than what Package.resolved pins. Prior review rounds surfaced a cluster of concurrency bugs many of which the current code addresses; remaining open items are the primary obstacle to production-readiness.

.github/workflows/tests.yml (clone pinning), Sources/RNSBackendSwift/SwiftRNSBackend.swift and Sources/PythonBridge/PythonBridge.swift (open items from prior rounds), app/rns_bridge.py (same).

Important Files Changed

Filename	Overview
.github/workflows/tests.yml	Adds Python framework/wheel-fetch step before xcodebuild (fixing the previously-missing step), but the Clone sibling packages step clones all three repos without branch or commit pinning — LXST-swift should use -b feat/transport-agnostic and all three should be pinned to match Package.resolved.
Sources/RNSBackendSwift/SwiftRNSBackend.swift	New native Swift backend conforming to RnsBackend. linkLock, explicit linkStateTasks cancellation, and a racing task group in propagationSync address the data-race and unbounded-block issues from prior review rounds.
Sources/RNSBackendPy/PythonRNSBackend.swift	Python-backed RnsBackend adapter. The drain-loop restart fix is present. Clean mapping layer between PythonBridge enums and RNSAPI neutrals.
Sources/PythonBridge/PythonBridge.swift	CPython embedding bridge. fetchNomadNetPage and propagationSync now run on blockingQueue avoiding drain starvation. Some C-API allocations (PyFloat_FromDouble, PyLong_FromLongLong) are still passed directly to PyTuple_SetItem without NULL guards.
app/rns_bridge.py	Core Python RNS/LXMF bridge. alloc_link_id race, link callback ordering, deadlock on teardown, and reset_identity cleanup are all addressed in the current code. _propagation_state_name rebuilds its mapping dict on every poll call.
Sources/RNSAPI/Protocols/RnsBackend.swift	Clean protocol seam definition; BackendEvent, PropagationSyncResult, and the composed RnsBackend protocol mirror the Android :rns-api layout. No issues found.
support/fetch-wheels.sh	Wheel-fetch script with explicit env-var overrides for all three Python dependencies. ble-reticulum is now pinned to a specific commit hash via BLE_RETICULUM_REF.

Sequence Diagram

sequenceDiagram
    participant UI as SwiftUI / AppServices
    participant B as RnsBackend (protocol)
    participant Py as PythonRNSBackend
    participant Br as PythonBridge (queue / blockingQueue)
    participant Py2 as rns_bridge.py (CPython)
    participant Sw as SwiftRNSBackend
    participant RS as reticulum-swift / LXMFSwift

    UI->>B: start(params)
    B->>Py: start(params)
    Py->>Br: bridge.start(...) [serial queue]
    Br->>Py2: PyObject_CallObject(start)
    Py2-->>Br: identity_hash, destination_hash
    Br-->>Py: LocalInfo
    Py-->>UI: LocalInfo

    loop Drain loop 200ms
        Py->>Br: bridge.drainEvents() [serial queue]
        Br->>Py2: drain_events()
        Py2-->>Br: event dicts
        Br-->>Py: PythonBridge.Event list
        Py->>UI: eventContinuation.yield(BackendEvent)
    end

    UI->>B: propagationSync(timeout)
    B->>Py: propagationSync
    Py->>Br: bridge.propagationSync [blockingQueue]
    Br->>Py2: propagation_sync() blocks up to timeout
    Py2-->>Br: PropagationSyncResult dict
    Br-->>Py: PropagationSyncResult
    Py-->>UI: PropagationSyncResult

    Note over Sw,RS: Swift backend path
    UI->>B: start(params)
    B->>Sw: start(params)
    Sw->>RS: ReticulumTransport + LXMRouter init
    RS-->>Sw: transport / router
    Sw->>Sw: startAnnouncePolling()
    Sw-->>UI: LocalInfo

    RS->>Sw: RouterDelegate.didReceiveMessage
    Sw->>UI: eventContinuation.yield(.inbound)

Loading

Comments Outside Diff (1)

1. .github/workflows/tests.yml, line 21-23 (link)

   Sibling-package clones use wrong branch and no commit pin

   git clone without -b <branch> clones the repository's default branch. Package.resolved pins lxst-swift to branch feat/transport-agnostic at commit b192964e14, but the clone here picks up the default branch instead. If the Xcode project uses these sibling directories as local path dependencies (which the clone step implies), then CI builds against the wrong lxst-swift branch. The same applies to reticulum-swift (pinned at 0.2.3 / b8ae6491) and lxmf-swift (pinned at 0.3.4 / b31a14a8): unless the default branch happens to be at exactly those commits, the local clone diverges from the Package.resolved pins. At minimum the LXST-swift clone should add -b feat/transport-agnostic; all three should be pinned with --branch <tag-or-commit> or cloned at the specific SHAs from Package.resolved.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: .github/workflows/tests.yml
   Line: 21-23
   
   Comment:
   **Sibling-package clones use wrong branch and no commit pin**
   
   `git clone` without `-b <branch>` clones the repository's default branch. `Package.resolved` pins `lxst-swift` to branch `feat/transport-agnostic` at commit `b192964e14`, but the clone here picks up the default branch instead. If the Xcode project uses these sibling directories as local path dependencies (which the clone step implies), then CI builds against the wrong `lxst-swift` branch. The same applies to `reticulum-swift` (pinned at 0.2.3 / `b8ae6491`) and `lxmf-swift` (pinned at 0.3.4 / `b31a14a8`): unless the default branch happens to be at exactly those commits, the local clone diverges from the `Package.resolved` pins. At minimum the LXST-swift clone should add `-b feat/transport-agnostic`; all three should be pinned with `--branch <tag-or-commit>` or cloned at the specific SHAs from `Package.resolved`.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
.github/workflows/tests.yml:21-23
**Sibling-package clones use wrong branch and no commit pin**

`git clone` without `-b <branch>` clones the repository's default branch. `Package.resolved` pins `lxst-swift` to branch `feat/transport-agnostic` at commit `b192964e14`, but the clone here picks up the default branch instead. If the Xcode project uses these sibling directories as local path dependencies (which the clone step implies), then CI builds against the wrong `lxst-swift` branch. The same applies to `reticulum-swift` (pinned at 0.2.3 / `b8ae6491`) and `lxmf-swift` (pinned at 0.3.4 / `b31a14a8`): unless the default branch happens to be at exactly those commits, the local clone diverges from the `Package.resolved` pins. At minimum the LXST-swift clone should add `-b feat/transport-agnostic`; all three should be pinned with `--branch <tag-or-commit>` or cloned at the specific SHAs from `Package.resolved`.

### Issue 2 of 2
app/rns_bridge.py:523-540
`_propagation_state_name` builds its lookup dict on every call. The `mapping.get(val, f"state_{val}")` fallback returns a non-canonical string like `"state_-1"` that `PropagationSyncResult.State(rawValue:)` cannot decode — it falls to `.unknown` and `ok == (state_name == "complete")` returns `false` even after a successful sync if any `PR_*` attribute is missing. Caching the mapping at module level avoids the repeated `getattr` cost and makes the fallback behaviour explicit.

```suggestion
_PROPAGATION_STATE_MAP: dict = {}

def _build_propagation_state_map() -> dict:
    return {
        getattr(LXMF.LXMRouter, "PR_IDLE", -1): "idle",
        getattr(LXMF.LXMRouter, "PR_PATH_REQUESTED", -2): "path_requested",
        getattr(LXMF.LXMRouter, "PR_LINK_ESTABLISHING", -3): "link_establishing",
        getattr(LXMF.LXMRouter, "PR_LINK_ESTABLISHED", -4): "link_established",
        getattr(LXMF.LXMRouter, "PR_REQUEST_SENT", -5): "request_sent",
        getattr(LXMF.LXMRouter, "PR_RECEIVING", -6): "receiving",
        getattr(LXMF.LXMRouter, "PR_RESPONSE_RECEIVED", -7): "response_received",
        getattr(LXMF.LXMRouter, "PR_COMPLETE", -8): "complete",
        getattr(LXMF.LXMRouter, "PR_NO_PATH", -9): "no_path",
        getattr(LXMF.LXMRouter, "PR_TRANSFER_FAILED", -10): "transfer_failed",
    }

def _propagation_state_name(val: Any) -> str:
    if val is None:
        return "idle"
    if not _PROPAGATION_STATE_MAP:
        _PROPAGATION_STATE_MAP.update(_build_propagation_state_map())
    return _PROPAGATION_STATE_MAP.get(val, f"state_{val}")
```

_{Reviews (22): Last reviewed commit: "fix: guard interfaceIds with linkLock + ..." | Re-trigger Greptile}

[torlando-tech]

@greptile review

[torlando-tech]

@greptile review

[torlando-tech]

@greptile review

[torlando-tech]

@greptile review

[torlando-tech]

@greptile review

[torlando-tech]

@greptile review

[torlando-tech]

On the flagged SwiftRNSBackend telephony inbound-link gap: inbound voice links are already wired by CallManager.initialize, which calls transport.registerDestinationLinkCallback(for: telephonyDestHash) → handleIncomingLink (CallManager.swift) against the same lxst.telephony destination hash. Adding a second link-established callback on SwiftRNSBackend.telephonyDestination for that hash would register a competing handler for the same hash and risks breaking the working ring path. Whether the network-layer gap greptile describes is real depends on the legacy-transport/double-stack wiring (AppServices' transport vs the backend's), which can only be settled with an actual inbound device voice call — deferring rather than blind-fixing to avoid a regression. Tracked for device-voice verification.

[torlando-tech]

@greptile review

[torlando-tech]

@greptile review