frid/PLAYBACK_PROTOCOL.md

Personal playback coordination

music_dht::playback owns the personal-device state machine, policy parameters, snapshot/command envelopes and conflict rules. It has no networking, database, clock, UI or audio dependency. The existing JSON-lines device-sync transport continues to carry snapshots and logged commands. Jam is a separate authority scope; its capability-based protocol is not a personal ownership claim.

Contract

Each logical device identity must have one coordinator and one selected output adapter. Independent live installations must not reuse a device identity or checkpoint. The web hub is a single authority for its user's browser outputs; running multiple independent hubs for that same identity requires an external actor/leader arrangement, not two copies of this in-memory adapter.

An owner is selected by an immutable Claim { counter, issuer, owner }. Claims are ordered lexicographically in that order. A locally issued claim increments the greatest counter observed so far. Persist the winning claim; never reset it because a peer disappears from an online list. Controllers gossip the winning claim as well. Concurrent startup, transfer or failover claims therefore converge to the same winner regardless of delivery order.

Only the winning output may render personal audio. A losing player stops its audio even if it was playing; it cannot reject a higher claim on that basis. This is eventual exclusivity, not a quorum lock: partitions can temporarily produce two outputs. Convergence assumes eventual delivery between trusted devices, functioning polling/event loops, and no continuing stream of explicit conflicting user transfers. A disconnected browser cannot be forcibly silenced.

Availability, actual unpaused playback, ownership and network connectivity are different inputs. Only new reports from the owner's audio endpoint renew its liveness. Duplicate snapshots and relayed claims do not. Gateway timers must not turn cached browser state into new output heartbeats. The engine reserves heartbeat sequence ranges in its checkpoint so a restart cannot roll them back and every UI tick does not require a database write.

Commands carry CommandStamp { version, claim, sequence }. A command can carry its existing claim ahead of the corresponding announcement. An explicit handoff must name that claim's owner and originate from its issuer. In a term, commands are applied in increasing sequence per sender; old, duplicate and incompatible envelopes are ignored. The command-sender map is bounded to 128 entries per term. Concurrent controllers are serialized by the selected output, whose snapshots distribute the resulting queue and transport state. This does not claim exactly-once audio effects across process crashes.

Adapter obligations

1. Authenticate the peer and trusted group using the existing transport and operation-log membership checks. Bind snapshot device_id to the actual sender. Names and snapshot wall-clock timestamps do not grant ownership.
2. Restore Checkpoint only for its matching group. Construct Engine with a stable device id, local Config and a monotonic clock. Do not restore wall clock liveness deadlines.
3. Feed real output availability and activity. Use heartbeat for a local output or output_report with an increasing source-report id for a gateway.
4. Feed announcements, tick the engine, and route explicit transfers through transfer. Ordinary controls only stamp a command in the current term.
5. Persist changed durable state before publishing decisions or executing commands. Serialize transitions with checkpoint commits and restore the previous engine if persistence fails. Recheck queued command fences before their effects reach the output.
6. Apply the resolved owner to the existing UI/audio adapter. Gossip its claim even while controlling another output. Online lists are presentation only.

Startup has a discovery grace period. If a restored/relayed owner has not yet reported, keep the startup decision pending until its heartbeat or timeout. Discovery is necessarily bounded: an entirely unknown peer across a partition cannot prevent a local startup claim. Once the peers communicate, normal claim ordering resolves the conflict.

Configuration

The complete serde Config accepts these fields (unknown fields are errors):

Field	Default	Meaning
claim_on_startup	true	One startup intent for this application instance
automatic_failover	true	Claim when the owner stops reporting
take_paused_on_startup	true	Startup may take a paused/idle output
discovery_ms	3000	Initial discovery grace
owner_timeout_ms	120000	Missing fresh output reports before failover

Config::passive() disables application-startup claims and automatic failover. Furumusic uses this for the always-on server. A real browser startup supplies a separate one-shot request_startup; explicit selection supplies a transfer. These events are not generated by server polling. Local browser selection uses the same Config::should_claim policy, with automatic cross-federation claims disabled. Browser presence expiry preserves the current owner and queue.

TUI exposes the configuration as the playback section of its existing settings file and preserves it when saving other settings. The web adapter reads optional playback_config_json on the user's furumusic__fed_device_identity row at session initialization; null selects the passive profile. Audio availability is a runtime input, not a persisted setting.

Versioning and rollout

The library-sync JSON ALPN remains furumi/sync/2; catalog, pairing and library data do not require a new transport. Device profiles advertise protocol version 3. Coordination envelopes independently carry version 1. Snapshot coordination and operation authority are additive optional JSON fields so library-sync records from older clients still deserialize. Upgraded clients ignore legacy personal playback snapshots/commands without the coordination envelope. The exclusivity guarantee applies after all audio clients have upgraded.

The shared generic Snapshot<S> and Command<S> keep state conversion in the applications while preventing divergent control message definitions. These envelopes use JSON, not a backwards-compatible promise for postcard layouts. Do not change Jam's independent authority by interpreting personal stamps there.

For local integration checks, patch the three frid crates with Cargo's external --config mechanism. Keep released dependency declarations and lockfiles in the applications; publish frid and then bump client dependencies for rollout.