SDK Parity
Where each Pilot Protocol SDK stands today and what's planned to close the gap.
Three official SDKs ship under one brand: Python, Node.js, and Swift (iOS/macOS). They all speak the same wire protocol — but they don't yet expose the same public API surface. This page tracks where they line up and where they don't.
Status at a glance
| SDK | Package | Coverage | Notes |
|---|---|---|---|
| Node.js | pilotprotocol on npm | Feature complete | TypeScript types, using support, Buffer I/O. The reference surface alongside Python. |
| Python | pilotprotocol on PyPI | Feature complete | Full type hints (py.typed), context managers, snake_case naming. |
| Swift | sdk-swift (SwiftPM) | Core trust + datagrams | Embedded daemon (XCFramework, no separate process). Streams, networks, managed networks, policy, member tags, high-level services, and most registry admin are not yet exposed. |
Summary by feature category
| Feature category | Node | Python | Swift | Notes |
|---|---|---|---|---|
| Lifecycle (construct, dispose) | ✅ | ✅ | ✅ | Each SDK uses its native idiom (using, with, deinit). |
Daemon admin — info, health | ✅ | ✅ | ✅ | |
Daemon admin — rotateKey | ✅ | ✅ | — | Planned for Swift. |
| Trust — initiate handshake, list trusted peers | ✅ | ✅ | ✅ | |
| Trust admin — approve/reject/pending/revoke | ✅ | ✅ | — | Planned for Swift. |
Trust convenience — waitForTrust | — | ✅ | ✅ | Shipped in Swift and Python (wait_for_trust). Planned for Node. |
Datagrams — sendTo, recvFrom | ✅ | ✅ | ✅ | Swift uses send(to:port:data:) and returns a typed Datagram. |
Datagrams — broadcast | ✅ | ✅ | — | Planned for Swift. |
Streams — dial, listen, Conn, Listener | ✅ | ✅ | — | Planned for Swift. |
| Registry admin — hostname / visibility / deregister / tags / webhook | ✅ | ✅ | — | Planned for Swift. |
| Networks — list/join/leave/members/invite/respond | ✅ | ✅ | — | Planned for Swift. |
| Managed networks — status/forceCycle/reconcile | ✅ | ✅ | — | Planned for Swift. |
| Managed networks — score/rankings | — | — | — | Removed in v1.10 — the symbols are no longer present in shipped libpilot builds. |
| Policy — get/set | ✅ | ✅ | — | Planned for Swift. |
| Member tags — get/set | ✅ | ✅ | — | Planned for Swift. |
High-level services — sendMessage, sendFile, publishEvent, subscribeEvent | ✅ | ✅ | — | Planned for Swift. |
FFI loader — findLibrary / loadLibrary | ✅ | private | n/a | Intentional: Swift embeds the library in an XCFramework — no loader needed. |
Typed response structs (Config, StartResult, Datagram, Error) | n/a | n/a | ✅ | Swift idiom. Node/Python return untyped Record<string, unknown> / dict[str, Any] from the same RPCs. |
What counts as a gap
Naming differences across languages are not gaps. The matrix collapses idiomatic equivalents into a single canonical row:
- Constructors:
new Driver()(Node),Driver()(Python), andPilot.start(config)(Swift) are the same operation expressed in each language's idiom. - Cleanup:
driver.close(),pilot.stop(), Python'swith, and Node'susingall resolve to the same teardown call. - Naming convention: Python's
send_messagemaps to Node'ssendMessage— same method, language-appropriate spelling. (Swift does not yet expose the high-level service methods; see the matrix.) - Datagram receive: Node and Python return a
dict; Swift returns a typedDatagramstruct. Both surface the same underlying RPC.
A real gap is an operation that one SDK does not expose at all. Those are the rows in the matrix marked unintentional — every one of them has a follow-up ticket to close it.
Full method matrix
The complete row-per-method matrix — including exact signatures and rationale for each gap — is generated by a deterministic script in the main protocol repo (scripts/parity-audit/). Re-running it against newer commits of the three SDKs regenerates the matrix locally (the script writes to ./inventory/).
Roadmap
End-state target: full parity across all three SDKs, except for the two intentional rows above (the FFI loader and Swift's typed response structs).
- Swift: the gap-fill work is tracked as a single follow-up ticket covering streams, networks, managed networks, policy, member tags, registry admin, trust admin, and high-level services. Wire protocol support already exists — what's missing is the Swift surface that exposes it.
- Node: add
waitForTrust(peerId, timeoutMs)— the blocking convenience Swift ships and Python now exposes aswait_for_trust. Today, Node users have to pollpendingHandshakes.
Cross-SDK versioning is documented in the GOVERNANCE file in the main protocol repo: all three SDKs share the same MAJOR.MINOR line, with coordinated releases when the wire protocol changes.