Add the CBOR snapshot channel, expand the control model, ship MetersApp, and take the discovery port exclusively

[gotwalt]

Lands the work that had accumulated in the working tree — five themed commits, reviewable in order.

What's here

1. The CBOR state-snapshot channel — the device speaks a native CBOR control channel alongside MIDI3. This implements exactly one route on it: the state-dump snapshot reporting the current bank and rig index, which MIDI3 never volunteers. The channel's wider management grammar is documented but deliberately not implemented.

Reading it needs a second, short-lived TCP connection, which surfaced a device constraint worth encoding: it refuses to greet — or resets — a session opened too soon after a previous socket closed. CONNECTION_COOLDOWN is now a shared spec constant, so all three implementations space the CBOR fetch and the MIDI3 session identically.

2. Control model, parameter registry and state tree — three related additions:

• Rig navigation is momentary, and the release is not optional. A press alone loads the target rig, but without the matching release the device abandons the change and reloads the previous rig about two seconds later — which reads as the device spontaneously undoing the navigation. Control now renders up/down/load_slot as a press immediately followed by its release.
• Registry: volume parameters (main/monitor/headphone plus the read-only master), the bank-preview extended-string page, and effect-type categories. Type values are allocated in 16-value blocks, one per group of the device's type knob, so a UI can name a slot's family without knowing the individual type.
• State tree: tracks the device's own position reports and the bank name preview, so a client can follow rig changes made anywhere — including at the front panel.

3. MetersApp — the meters terminal example rebuilt as a native SwiftUI macOS app. The high-rate lane is deliberately not published: status events fold into a private frame that a 33 ms tick publishes once, so a 300 Hz stream doesn't drive 300 view updates a second. Every restart bumps an epoch counter that captured tasks check before writing, so a connection still unwinding can't write into its successor's state.

4. Spec 0.5.0 — wires the new surfaces into each package's public API and bumps the shared version.

5. Exclusive ownership of the discovery port — the one behavioural fix, and worth reading closely.

The discovery bug

Discovery bound UDP 5727 with SO_REUSEPORT, sharing the port with anything already listening. That's the wrong default here. The device answers a poll only on 5727 — it ignores the poll's source port — and when several sockets are bound to one UDP port the kernel delivers each datagram to exactly one of them. A second listener doesn't see a copy of the reply; it takes it.

In practice: with Kemper's Rig Manager running, discovery returned no devices while the network and the Profiler were both healthy, and the app reported "No Profiler found on the network" — sending you to debug the network instead of the other program holding the port.

The fix is to bind without SO_REUSEADDR or SO_REUSEPORT. Verified on macOS in both directions:

• Port free → the exclusive bind succeeds and every subsequent bind is refused, including SO_REUSEPORT. Replies can't be stolen mid-session.
• Port held → the bind fails EADDRINUSE, reported as a port conflict naming the likely holder rather than worked around.

Each implementation gains a DiscoveryPort handle, acquired before a session and held for its lifetime, pollable repeatedly so a long-running client can notice devices appearing and disappearing without releasing the port. discover/find_first still acquire-poll-release, so one-shot callers are unchanged.

I checked whether polling from an ephemeral source port could sidestep the clash entirely — it can't, the device replies only to 5727 (0 replies from an ephemeral port on an otherwise-idle machine, verified twice). Contention is unavoidable; exclusivity is the only real fix.

Swift needed a transport change to allow this at all. It used one NWListener plus one NWConnection per target, all co-bound to 5727 — a design that requires allowLocalEndpointReuse, which is precisely the SO_REUSEPORT causing the bug. Network.framework offers no way to decline to share, so discovery is now a single exclusively-bound BSD socket. That incidentally removes a latent mislabel: recvfrom reports the true source address, where the sender connection reported the broadcast address it was constructed with, so a reply could have been recorded as a device at 255.255.255.255.

Verification

Against a real Profiler ("Mini", 192.168.7.220):

• App in auto mode: acquired UDP 5727 exclusively → discovered 192.168.7.220 Mini → connected, rig streaming. lsof confirms it holds the port.
• App under contention: fails in 72 ms with the actionable message instead of a 3-second empty window, then recovers automatically once the port frees.
• Reliability: 8/8 clean Swift runs; Python and Rust confirmed live.
• The failure was reproduced on demand with a stand-in process holding the port (3/3 runs returned 0 replies while the stand-in logged the stolen packets).

Full CI-equivalent run is green locally: codegen drift clean, spec version consistent across all three generated modules, Rust (fmt + clippy -D warnings + 101 tests), Python (ruff check + format + 366 passed), Swift (format lint --strict + 95 tests + both products).

Notes for review

• Two formatting-only fixes were folded in (rust/src/control.rs, python/src/libkp/state.py); both predated this work and would have failed CI on arrival.
• Manual mode doesn't claim the discovery port — it connects straight over TCP and never polls, so requiring UDP 5727 there would block running alongside Rig Manager with a known IP for no benefit. Easy to make unconditional if you'd rather.
• Two copies of MetersApp can no longer run at once; the second gets the port-conflict error. Inherent to exclusivity, but worth knowing.

🤖 Generated with Claude Code

https://claude.ai/code/session_013XSn94RpApv9AYMQABGM8S