[Feature]: Third-party hosts driving nvpair-ui-broker: is the JSON-RPC surface a supported contract, is the app-data layout versioned, and can the proxy expose the serving node?

Area

nvpair-ui-broker (JSON-RPC surface, --ipc mode), nvpair-cluster-manager (app-data / cluster dir layout), ollama-proxy (response headers)

User problem

We are integrating PAIR as the LAN inference layer behind our own desktop application (Magieva Desktop, an Electron app; we are an NVIDIA Inception member). Our host process supervises nvpair-ui-broker itself — spawned with piped stdio, or over --ipc — instead of the shipped PAIR UI, and relies on:

• discovery:get-nodes / discovery:subscribe → discovery:nodes-changed for the roster (members, addresses, modelsByEngine, loadedByEngine, trusted / clustered);
• workloads:subscribe → workloads:upsert with workloadInfo.scheduledOn / originatedFrom to record which node actually served each request (we write it to our usage ledger);
• cluster:invite-node / cluster:respond-to-invite / cluster:invite-status and engine:remote-install / engine:remote-pull-model to drive pairing and model placement from our own UI;
• the per-user app-data directory (~/Library/Application Support/Nvidia Corporation/Personal AI Router on macOS) and the cluster dir (identity.json, node.crt, node.key, trusted/) so an existing NVIDIA-created node keeps its identity when our host takes over supervision.

Measured on v0.1.1 (13b6811, built from source with Go 1.25, macOS 26 / Apple M4 Max): all of the above works today when the broker is driven from a plain shell over newline-delimited JSON-RPC 2.0 — app:ready in ~3 s, the roster is pushed, a real Ollama turn through the proxy yields workloads:upsert with scheduledOn set, and the invite / engine methods are routed. What we cannot determine from the repo:

1. Is the broker's JSON-RPC method + notification surface a supported integration contract, with a compatibility policy across releases (additive changes only? deprecation window?), or is it considered internal to the shipped UI?
2. Is the on-disk format of the app-data and cluster directories versioned? node-id.json and cluster/identity.json carry only node_uuid and created_at; services/VERSIONING.md versions binaries, not the data layout. A third-party host cannot tell whether a directory written by a newer or older PAIR is safe to attach to, or refuse it cleanly.
3. Will the proxies expose the serving node on the HTTP response (e.g. an X-PAIR-Served-On: <hostUuid> header)? Today it is available only through the broker event stream (proxy:proxy/request.node_id, workloads:upsert.scheduledOn), which is fine for a host that also owns the broker, but not for an Ollama-compatible client that only sees the proxy.

Desired outcome

• A short statement in the broker README (or a docs/integration.mdx) of which methods/notifications are stable for third-party hosts and how breaking changes are announced.
• A format_version (or equivalent) field in node-id.json / cluster/identity.json, plus a documented rule for what a host should do when it does not match.
• Optionally, a X-PAIR-Served-On response header on ollama-proxy / lmstudio-proxy responses.

Alternatives considered

• Pinning to a vendored v0.1.1 build and treating every upgrade as a full re-validation of the JSON-RPC surface (what we will do if the surface is declared internal).
• Reading the serving node only from the broker events (works for us; leaves plain Ollama clients unable to attribute a response).
• Inferring the data-dir version from file shape (fragile; the reason for question 2).

Compatibility and security implications

Additive only: a version field and a response header change no existing behaviour. A published compatibility policy lets hosts fail closed on a surface they do not recognise instead of guessing. No change to pairing, mTLS or data handling is requested.

Validation approach

• Drive the broker from a shell exactly as we did: ./nvpair-ui-broker --cluster-dir <dir> from a directory holding the sibling binaries, send {"jsonrpc":"2.0","id":1,"method":"discovery:subscribe"} and workloads:subscribe, run one POST /api/chat through the proxy, observe workloads:upsert with scheduledOn.
• For the version field: create a node, read node-id.json, confirm the field; start a host against a directory carrying a higher version and confirm it refuses with a clear error.
• For the header: curl -i a successful POST /api/chat through the proxy and read the header.

Confirmations

• I searched existing issues for duplicates (#1, #4, #48, #49, #58 are adjacent — mDNS reflectors, enrichment refresh, test data dir, Linux service, headless manual nodes — none asks about contract stability, data-dir versioning or a served-on header).
• I agree to follow the Code of Conduct.

Commencez par le point d’entrée JSON-RPC de nvpair-ui-broker et README ou docs/integration.mdx, puis examinez services/VERSIONING.md, node-id.json et cluster/identity.json. Reproduisez les commandes documentées du broker et du proxy, notamment discovery:subscribe, workloads:subscribe et curl, afin d’établir le comportement actuel. La tâche est terminée lorsque le contrat pris en charge, la gestion des formats de données et toutes les métadonnées de réponse du proxy sont documentés ou implémentés avec la validation indiquée.