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:
1 parent
2d4782819d
commit
4f7e999280
12 files changed
+563
-10
No files matched your search
+32
-1
@@ -177,13 +177,39 @@ their local output is playing. The web gateway uses a passive server profile;
|
||||
browser startup and explicit selection are separate inputs.
|
||||
|
||||
This register provides eventual exclusivity after a partition heals, not a
|
||||
quorum lock during a partition. Device-sync profiles now advertise version 3;
|
||||
quorum lock during a partition. Device-sync profiles now advertise version 4
|
||||
(version 3 introduced coordination, version 4 adds podcast queue items);
|
||||
the additive coordination envelope is independently versioned and transported
|
||||
over the existing JSON `furumi/sync/2` stream. Legacy library records remain
|
||||
readable, but legacy unfenced personal playback messages cannot control an
|
||||
upgraded output. See [PLAYBACK_PROTOCOL.md](PLAYBACK_PROTOCOL.md) for the
|
||||
contract, adapter obligations, configuration and rollout rules.
|
||||
|
||||
Podcasts are a separate content type with a pure shared contract in
|
||||
`music_dht::podcast` (normative description: [PODCASTS.md](PODCASTS.md)). It
|
||||
owns canonical feed URLs, domain-separated BLAKE3 podcast and episode ids,
|
||||
feed aliases, the no-GUID episode rule, bounded metadata DTOs, the
|
||||
self-contained `PodcastEpisodeRef` queue item, and convergent merge functions
|
||||
for subscriptions, share decisions, progress registers and listening
|
||||
sessions. The tolerant RSS/Atom parser is shared behind the `podcast-feed`
|
||||
feature because episode identity depends on it. HTTP fetching, scheduling,
|
||||
buffering and decoding remain client runtime work, and persistence lives in
|
||||
client storage that implements the same rules. Podcast audio is fetched from
|
||||
the publisher: it is never imported, content-addressed or offered for P2P
|
||||
transfer.
|
||||
|
||||
Device-sync protocol v4 carries podcast state between trusted devices only:
|
||||
four `podcast_*` operations, bounded snapshot sections (the recovery path,
|
||||
because sync vectors never re-request operations hidden from an older peer),
|
||||
and an explicit `PlaybackTrack.source`. Operation and source enums are closed,
|
||||
so senders gate on the version each peer reported itself; podcast state is
|
||||
never sent to peers below v4, handoff to them is refused, and their playback
|
||||
commands are ignored while the queue contains episodes. Jam snapshots replace
|
||||
episodes with opaque placeholders. Progress ordering uses a Lamport
|
||||
generation rather than wall-clock `hlc_ms`, so a device with a fast clock
|
||||
cannot undo an observed seek or restart. Public podcast discovery is a future
|
||||
separate overlay; the music DHT schema and `federation-net` are unchanged.
|
||||
|
||||
Music discovery identifies an owner and content; it does not force all domain
|
||||
traffic through DHT messages. `music-dht` exposes the underlying authenticated
|
||||
stream capability and defines shared wire models for Furumi catalog and device
|
||||
@@ -283,3 +309,8 @@ architectural constraint:
|
||||
- Local durable state survives ordinary peer and network failure.
|
||||
- Additional stream protocols reuse authenticated connectivity without
|
||||
coupling bulk data to the typed control channel.
|
||||
- Private personal state (podcast subscriptions, progress, history) stays in
|
||||
the trusted-device group; Jam and public overlays only see explicit public
|
||||
projections or opaque placeholders.
|
||||
- A device's protocol version is what that device reported; relays never
|
||||
substitute their own.
|
||||
Reference in new issue
Block a user