Document prompt revocation and moved-feed subscriptions

README, ARCHITECTURE, CHANGELOG and AGENTS describe the immediate
revocation and quit-time wait, decision-bound confirmations, the card
URL filter, devices that left the group, the separate bounded podcast
search, and which direction of a moved feed the search mark covers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 15:13:07 +02:00
1 parent 17ed8bfcd4
commit 3ddf7995e8
4 files changed
+76 -29

No files matched your search

+4 -1
View File
@@ -69,7 +69,10 @@ update it only when dependencies change.
`podcasts::publication` (`PodcastDht::sync_shares` over the merged
registers): never publish a podcast directly, never log feed URLs or ids of
podcasts that are not shared, never put progress, history, counters or
device names into a card. Public cards found by search are publisher claims:
device names into a card. A local share-off or unsubscribe asks for an
immediate pass (`Reconciler::revoke_now`), which quitting waits for, and
privacy confirmations change only through `publication::set_shared` /
`ShareConfirmations` (bound to the share decision, never synced). Public cards found by search are publisher claims:
subscribe and preview only through `podcasts::discovery`, which uses the
card's origin URL (`PodcastSearchHit::feed_url`), never a claimed URL, and
never stores card metadata. Queue items are identified by `state::track_key`
+26 -11
View File
@@ -406,8 +406,9 @@ The TUI owns what the contract leaves to clients:
`podcast_dht` in its own manifest only while the overlay runs. A cache
that cannot be opened is logged and only turns discovery off. What this
device publishes is decided by `podcasts::publication`: after local share
and unsubscribe actions, received podcast operations, feed refreshes,
every overlay (re)start and every 5 minutes it builds one
and unsubscribe actions (at once: `Reconciler::revoke_now`), received
podcast operations and feed refreshes (debounced 1 s), every overlay
(re)start and every 5 minutes it builds one
`PodcastShareState` per subscription (merged registers, a card from the
catalog for shared podcasts only, the local privacy confirmation) and
calls the declarative `PodcastDht::sync_shares`, which publishes what is
@@ -417,14 +418,24 @@ The TUI owns what the contract leaves to clients:
republish. Publication runs from each device's own identity. Privacy
confirmations of feed URLs that look private are device-local
(`podcast-share-confirmations.json`, mode 0600) and bound to the exact
URLs. Without a readable podcast store this device revokes all its own
cards. Logs carry counts only.
- **Finding and subscribing.** `Federation::search` runs
`PodcastDht::search` next to the music DHT search and takes the podcast
entries of `merge_search_results` (exact titles first) as
`podcasts::discovery::PodcastHit`s; the music sections keep their own
aggregation and ranking, so music results are unchanged. Off the UI
thread each hit's origin URL is resolved with
URLs and to the share decision (the share register's operation): a newer
decision on any device drops them. Cards leave out artwork and web links
that look private, and both for a private-looking feed. Without a
readable podcast store this device revokes all its own cards. The report
of each pass lists the private podcasts whose own card is still live
(`unrevoked`: pending, failed or federation off) for the side panel; the
overlay peer count is refreshed every 10 s between passes. Before the
node stops on quit, `Reconciler::flush` waits up to 4 s for a revocation
requested just before. Logs carry counts only.
- **Finding and subscribing.** `Federation::search_podcasts`
(`podcasts::discovery::search`) runs `PodcastDht::search` as its own task,
bounded at 15 s including the overlay's bootstrap, apart from the music
search (`Federation::search`, unchanged), and delivers
`AppEvent::FedPodcastsLoaded` for the same search sequence, so music
results never wait for the overlay. The hits keep the podcast entries of
`merge_search_results` (exact titles first) as
`podcasts::discovery::PodcastHit`s. Off the UI thread each hit's origin
URL is resolved with
`PodcastStore::resolve_podcast_id`, and the "subscribed" mark compares
that id and the card's id with the subscribed podcasts, so a feed alias
counts. A card is a publisher's claim: only `PodcastSearchHit::feed_url`
@@ -433,7 +444,11 @@ The TUI owns what the contract leaves to clients:
«Подписаться» (`discovery::subscribe_from_hit` → `refresh::subscribe_url`),
which refuses a hit whose id does not match its URL and stores only what
the feed says. Claimed moved-feed URLs are displayed, never fetched or
recorded as aliases. The new subscription is private.
recorded as aliases. The new subscription is private. Subscribing to an
address whose feed announces (`itunes:new-feed-url`) a newer one this
device already follows reports that subscription instead of adding a
second one, and the preview (`discovery::preview_for`) resolves the
address the feed moved to, so the card reads «Уже подписан» then.
- **Progress.** `podcasts::progress` runs one writer thread so every
progress write of this device is ordered. The app tick follows the
position and actual listening time and sends: an explicit start (or
+13 -3
View File
@@ -19,18 +19,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
published only after a confirmation on that device. The list and side
panel show whether a podcast is shared and whether this device publishes
it.
- Turning sharing off or unsubscribing revokes this device's card at once,
and quitting waits up to 4 s for that; the side panel says when a
private podcast's card is not revoked yet (pending, failed or federation
off). A privacy confirmation covers one share decision: turning sharing
off (or on again after that) on any trusted device asks again. Cards
leave out artwork and web links that look like they carry an access key,
and both for a feed whose URL looks private.
- Search (`/`, with the federation running) also finds public podcast cards.
They are listed after the music results under "Podcasts · public cards" with
a `[podcast]` marker, the number of publishing devices, and "✓ subscribed"
when this device is subscribed (also through a feed alias). Local-only
search is unchanged.
when this device is subscribed (also through a feed alias). The podcast
search runs apart from the federated music search (bounded at 15 s), so
music results never wait for it; local-only search is unchanged.
- Enter on a podcast hit opens its card: title, author, categories,
description, episode count, newest episode, publishing devices, feed URL
and unverified moved-feed claims. `e` reads the seasons and episodes from
the feed without subscribing. «Подписаться» (Enter) subscribes privately
with the card's origin feed URL, so the podcast id is the card's, and
reads everything from the feed itself; «Уже подписан» opens the podcast
in the Podcasts tab instead.
in the Podcasts tab instead, also when this device follows the feed under
the newer address it moved to (known once the feed was read), and
subscribing to such an older address adds no second subscription.
### Changed
+33 -14
View File
@@ -292,22 +292,34 @@ Sharing a podcast (public discovery):
podcast under its own device key: the feed URL, title, author,
description, artwork and web links, the number of episodes and the date of
the newest one. The card never contains your progress, history, play
counts, device names or anything from podcasts you did not share.
counts, device names or anything from podcasts you did not share. Artwork
and web links that look like they carry an access key are left out, and
so are both for a feed whose own URL looks private.
- If the feed URL looks private (a token, key or signature in its query, a
member-feed host such as Patreon, a long random-looking part), Furumi asks
first and lists why (in Russian). Anyone who finds the card can read the
feed at that URL. The confirmation is stored only on this device
(`podcast-share-confirmations.json` next to `podcasts.sqlite3`) and covers
exactly the URLs shown: another device of yours asks again before it
publishes, and so does this one if the feed moves. Until then the side
panel says the publication is held back; press `Shift+F` there to
confirm (or `x` in the dialog to stop sharing).
exactly the URLs shown and this one decision to share: another device of
yours asks again before it publishes, and so does this one if the feed
moves or if sharing is turned off (or turned on again after that) on any
of your devices. Until then the side panel says the publication is held
back; press `Shift+F` there to confirm (or `x` in the dialog to stop
sharing).
- `Shift+F` on a shared podcast, or unsubscribing, makes it private again on
every device: each device replaces its card with a signed removal record.
Removal spreads with the usual delay of the network: a copy that missed
it can still be found until it expires (at most 12 hours). Removing your
card never touches other people's subscriptions. An older device that
comes back with the earlier "share" decision does not publish it again.
every device in your group: each device replaces its card with a signed
removal record. This device sends its removal right away, and quitting
waits for it (up to 4 seconds). While the removal is not sent yet (or
could not be sent, or the federation is off), the side panel says the
public card is not revoked yet instead of just "private". With the
federation off, the removal is sent the next time it runs; until then,
and for a copy that missed the removal, the card can still be found until
it expires (at most 12 hours). Removing your card never touches other
people's subscriptions. An older device that comes back with the earlier
"share" decision does not publish it again.
- A device that left your device group, or was removed from it, no longer
receives your share decisions: it keeps publishing the podcasts it shares
until you turn sharing off (or unsubscribe) on that device itself.
- The card is signed with this device's federation key, which is also the
key of its public music library, so a shared podcast can be linked to
that library and to the device's network address.
@@ -322,9 +334,14 @@ Finding public podcasts:
with the number of devices that publish the card (devices, not
subscribers; anyone can create devices, so it is not a sign of trust) or
"✓ subscribed" when this device already follows the podcast, also when
you subscribed under an older or newer address of the same feed. Your
query words go to the discovery peers, as they do for music search. With
the federation off, search stays local and shows no podcasts.
you subscribed under an older address of the same feed that moved to the
card's address. When you follow the feed under a newer address than the
card's, the list cannot tell yet; the card can once its episodes are read
(`e`), and «Подписаться» never adds a second subscription for it. Your
query words go to the discovery peers, as they do for music search. The
podcast search runs apart from the music search (music results never wait
for it) and gives up after 15 seconds. With the federation off, search
stays local and shows no podcasts.
- Enter opens the card (in Russian): what its publishers claim (title,
author, categories, description, number of episodes and date of the
newest one), the feed URL, and addresses some publishers claim the feed
@@ -338,7 +355,9 @@ Finding public podcasts:
online, and nothing from the card is kept. The new subscription is
private like any other: it is not shared until you press `Shift+F`, and
your progress is your own. «Уже подписан» means this device is already
subscribed; Enter then opens the podcast in the Podcasts tab.
subscribed (under the card's address, an older one, or — once the feed
was read — the newer address the feed moved to); Enter then opens the
podcast in the Podcasts tab.
Podcast data lives in `podcasts.sqlite3` in the platform data directory (the
same file the earlier podcast test build used; it is upgraded in place). If