Document podcast contract and bump crate versions

Add PODCASTS.md as the normative podcast contract: identity and URL
canonicalization, the no-GUID rule, synced versus local versus public
data, operation kinds and merge rules with examples, snapshot recovery,
version gating for peers below v4, Jam privacy and the reserved
playback_rate. Update PLAYBACK_PROTOCOL.md, ARCHITECTURE.md, the crate
READMEs and CHANGELOG.md.

Bump music-dht to 0.6.0 and furumi-library to 0.3.0: new public enum
variants and struct fields are breaking changes for 0.x, and
furumi-library re-exposes music-dht types.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 15:40:55 +02:00
1 parent 2d4782819d
commit 4f7e999280
12 files changed
+563 -10

No files matched your search

+44 -2
View File
@@ -97,8 +97,9 @@ 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
data do not require a new transport. Device profiles advertised protocol
version 3 when coordination was introduced (version 4 adds podcast queue items,
see below). 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.
@@ -109,6 +110,47 @@ 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.
## Protocol v4: podcast queue items
Device profiles advertise protocol version 4. The JSON ALPN stays
`furumi/sync/2` and the coordination envelope stays version 1. Version 4 adds
to the portable queue DTO:
- `PlaybackTrack.source`: `music`, `podcast_episode` with a self-contained
`PodcastEpisodeRef`, or `private` (Jam placeholder). It is omitted for
music, so music-only state serializes exactly as in v3. Podcast episodes are
never encoded as negative ids or URLs in `file_path`.
- `PlaybackStateWire.playback_rate`: reserved, omitted when unset. Treat a
missing or unsupported value as 1.0.
`PlaybackSource` is a closed enum: a v3 client fails to parse any message
with a podcast item. Adapters therefore apply the shared helpers from
`music_dht::device_sync`:
1. Send a playback snapshot to a peer only when
`playback_allowed_for_peer(state, peer_version)` holds; otherwise send
`None`.
2. Refuse an explicit transfer to a device below v4 while the queue contains
podcast items and show that the target needs an update. The decision uses
the version that device reported itself (`profile_protocol_version`),
never the local constant. Do not strip episodes from the queue.
3. Ignore `SetState`/`ActiveChanged` from peers below v4 while the local
queue contains podcast items (`playback_command_allowed_from_peer`).
4. A stamped `playback_command` operation with podcast items is itself gated
by `op_allowed_for_peer`.
A handoff of a podcast episode records the position and the play/pause intent
first, transfers the queue with its sources, and lets the receiver open the
publisher's HTTP source and seek. Ownership still changes only through the
claim, so a late response cannot make the previous owner resume audio. The
durable episode progress is a separate register; see `PODCASTS.md`.
Jam hosts send `music_dht::jam::redact_jam_snapshot`, which replaces podcast
items with opaque `private` placeholders and drops the personal coordination
envelope. They reject participant commands with real episodes
(`jam_command_allowed`) and map placeholders back with
`restore_jam_private_items` before applying a participant's state.
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.