Document podcast register ordering, versions and snapshot limits
CI / check (pull_request) Successful in 2m13s

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 16:10:33 +02:00
1 parent 085bff6191
commit 65d6ca2f14
5 files changed
+243 -94

No files matched your search

+17 -6
View File
@@ -119,31 +119,42 @@ 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`.
never encoded as negative ids or URLs in `file_path`. Queue items carry
`PodcastEpisodeRef.progress_generation`, the greatest progress generation
the sender has seen for the episode.
- `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`:
A v3 client does not know `source` and ignores it: it would treat an episode
as a broken music item (id 0, no content id) and forward the queue that way,
losing the episode for every device. `PlaybackSource` is also a closed enum
for v4 clients, so a future variant needs a new protocol version. 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`),
the version that device reported itself (`profile_protocol_version`;
profiles relayed by other devices only raise it, `relayed_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`.
5. A `PairRequest` is sent before the invite consumer hears from the inviter:
gate its playback snapshot by `InviteWire::inviter_protocol_version()`
(version 1 for invites without one).
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`.
durable episode progress is a separate register; see `PODCASTS.md`. Only the
receiver writes the handoff's explicit progress action, with
`ProgressRecord::explicit_generation(max(local, progress_generation))`; the
sender writes a final checkpoint at its session generation.
Jam hosts send `music_dht::jam::redact_jam_snapshot`, which replaces podcast
items with opaque `private` placeholders and drops the personal coordination