[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.

Bắt đầu với điểm vào JSON-RPC của nvpair-ui-broker và README hoặc docs/integration.mdx, sau đó kiểm tra services/VERSIONING.md, node-id.json và cluster/identity.json. Chạy lại các lệnh broker và proxy đã được ghi trong tài liệu, bao gồm discovery:subscribe, workloads:subscribe và curl, để xác định hành vi hiện tại. Công việc được coi là hoàn tất khi contract được hỗ trợ, việc xử lý định dạng dữ liệu và mọi metadata phản hồi của proxy được ghi lại hoặc triển khai kèm validation đã nêu.