From 150144138fd2f4a80be6116cb2e453ed7b7f29f1 Mon Sep 17 00:00:00 2001 From: Alex Godoroja Date: Wed, 27 May 2026 21:05:13 -0700 Subject: [PATCH] docs(sdk-parity): add public parity matrix page (PILOT-42) New /docs/sdk-parity page that surfaces, on the public site, where each official SDK (Node / Python / Swift) stands today and what's planned to close the gap. Linked from the docs sidebar (between Python SDK and Messaging) and from the existing SDK pages' prev/next nav. Companion to pilotprotocol/docs/SDK_PARITY.md and the canonical Google Sheet matrix. Closes the docs deliverable for PILOT-42. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/data/docsNav.ts | 2 + src/pages/docs/messaging.astro | 2 +- src/pages/docs/python-sdk.astro | 2 +- src/pages/docs/sdk-parity.astro | 116 ++++++++++++++++++++++++++++++++ 4 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 src/pages/docs/sdk-parity.astro diff --git a/src/data/docsNav.ts b/src/data/docsNav.ts index 9332dea..e3dd120 100644 --- a/src/data/docsNav.ts +++ b/src/data/docsNav.ts @@ -20,6 +20,8 @@ export const docsNav: NavItem[] = [ icon: '' }, { label: 'Python SDK', href: '/docs/python-sdk', slug: 'python-sdk', icon: '' }, + { label: 'SDK Parity', href: '/docs/sdk-parity', slug: 'sdk-parity', + icon: '' }, // Features { section: 'Features', label: 'Messaging', href: '/docs/messaging', slug: 'messaging', icon: '' }, diff --git a/src/pages/docs/messaging.astro b/src/pages/docs/messaging.astro index de733d8..2e494f4 100644 --- a/src/pages/docs/messaging.astro +++ b/src/pages/docs/messaging.astro @@ -179,7 +179,7 @@ const bodyContent = `

Messaging

description="Send messages, transfer files, and use the inbox with Pilot Protocol." activePage="messaging" canonicalPath="/docs/messaging" - prev={{ label: "Python SDK", href: "/docs/python-sdk" }} + prev={{ label: "SDK Parity", href: "/docs/sdk-parity" }} next={{ label: "Trust & Handshakes", href: "/docs/trust" }} > diff --git a/src/pages/docs/python-sdk.astro b/src/pages/docs/python-sdk.astro index dacafd5..56b0ffd 100644 --- a/src/pages/docs/python-sdk.astro +++ b/src/pages/docs/python-sdk.astro @@ -246,7 +246,7 @@ with Driver() as d: activePage="python-sdk" canonicalPath="/docs/python-sdk" prev={{ label: "Go SDK", href: "/docs/go-sdk" }} - next={{ label: "Messaging", href: "/docs/messaging" }} + next={{ label: "SDK Parity", href: "/docs/sdk-parity" }} > diff --git a/src/pages/docs/sdk-parity.astro b/src/pages/docs/sdk-parity.astro new file mode 100644 index 0000000..a40d708 --- /dev/null +++ b/src/pages/docs/sdk-parity.astro @@ -0,0 +1,116 @@ +--- +import DocLayout from "../../layouts/DocLayout.astro"; + +const bodyContent = `

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.

+
+ +
+

On this page

+ +
+ +

Status at a glance

+ + + + + + + + + + + + + + + + + + + + + + + + +
SDKPackageCoverageNotes
Node.jspilotprotocol on npmFeature completeTypeScript types, using support, Buffer I/O. The reference surface alongside Python.
Pythonpilotprotocol on PyPIFeature completeFull type hints (py.typed), context managers, snake_case naming.
Swiftsdk-swift (SwiftPM)Core trust + datagramsEmbedded 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

+

Updated against sdk-node@d02bd00, sdk-python@93584ea, sdk-swift@0d49f87 (audited 2026-05-28).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Feature categoryNodePythonSwiftNotes
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——✅Planned for Node and Python. Currently Swift-only.
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 — score/status/rankings/cycle/reconcile✅✅—Planned for Swift.
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✅privaten/aIntentional: Swift embeds the library in an XCFramework — no loader needed.
Typed response structs (Config, StartResult, Datagram, Error)n/an/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), and Pilot.start(config) (Swift) are the same operation expressed in each language's idiom.
    • +
  • Cleanup: driver.close(), pilot.stop(), Python's with, and Node's using all resolve to the same teardown call.
    • +
  • Naming convention: Python's send_message maps to Node/Swift's sendMessage — same method, language-appropriate spelling.
    • +
  • Datagram receive: Node and Python return a dict; Swift returns a typed Datagram struct. 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 — lives in the canonical spreadsheet:

+

SDK Parity Matrix — Google Sheet

+

The matrix is generated by a deterministic script in the main protocol repo (scripts/parity-audit/). Re-running it against newer commits of the three SDKs produces an updated matrix.csv — drop it into the Sheet to refresh.

+ +

Roadmap

+

End-state target: full parity across all three SDKs, except for the three intentional rows above (FFI loader, socket-path default, 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 and Python: add waitForTrust(peerId, timeoutMs) — Swift's blocking convenience. Today, Node and Python users have to poll pendingHandshakes.
    • +
+

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.

+`; +--- + + +