[BW-DL-06] Make device-wide download copy management semantics explicit #21

Open
opened 2026-09-18 08:46:16 +02:00 by alexander · 2 comments
Owner

Migrated from GitHub issue #111. Forgejo issue: #21. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Classification

Candidate implementation follow-up from #15 / GitHub PR #106, blocked on owner product decision before implementation.

Problem / opportunity

The Downloads management screen explicitly lists every physical downloaded copy on the device, including rows whose title is hidden because the active profile cannot access that book. Its comments describe the screen as answering 'what is using space on this phone'.

The actions do not currently match that device-wide meaning:

  • Remove resolves the active profile and releases only that profile's claim. A hidden copy owned only by another profile can therefore show a Delete action that cannot remove the physical copy.
  • OfflineBook.isPinned is true if any profile has pinned the shared physical copy, while setPinned(...) writes only the active profile's request. A globally-looking pin can therefore remain set because another profile owns the pin.

Product decision required

Approve or reject this split before implementation:

  1. Book/profile surfaces: Remove my download / release this profile's claim. If another profile still requests the copy, the physical files stay.
  2. Device storage management surface: Remove from device means remove the physical copy for all local profile claims, with an explicit confirmation that other profiles on this device will need to download it again.

For pinning, choose one of these before coding:

  • device-level pin owned by the physical copy; or
  • profile pins remain separate and the device screen exposes aggregate state without pretending one active-profile toggle controls all of them.

User value

The storage-management screen does what it says, while normal book/profile actions preserve the existing safe shared-copy semantics.

Scope if approved

  • Introduce explicit repository/use-case operations for profile-claim removal versus device-copy removal; do not overload the existing release(profileId) method with both meanings.
  • Make destructive scope clear in UI copy/confirmation before the action.
  • Resolve device-level pin semantics consistently with the chosen product decision.
  • Preserve title masking and profile authorization on device-wide rows.
  • Ensure removing the physical copy updates all local manifest/claim/local-availability state coherently.

Explicitly out of scope

  • No server-side deletion.
  • No progress deletion.
  • No profile permission changes.
  • No automatic cleanup behavior change except where it calls a clearly scoped existing device-copy cleanup operation.
  • No revealing hidden book titles or which other named profile owns a copy.

Dependencies

  • Owner product decision above. Do not implement until approved.
  • Parent audit #15 / GitHub PR #106.
  • BW-DL-02/#17 is recommended first for consistent presentation but not a strict data dependency.

Architecture seams affected

  • DownloadRepository claim/copy operations.
  • OfflineFiles removal semantics.
  • Downloads ViewModel/device-storage UI.
  • Local availability projection after physical deletion.
  • Pin ownership model.

Server / API assumptions

None. This is local-device storage/authorization bookkeeping only.

Storage / migration implications

Probably no Room schema change is required for an explicit 'remove all local requests + physical copy' operation because claims already exist as rows. Pin semantics may require a schema/model decision if a true device-level pin is chosen.

Any deletion operation must preserve transaction/order safety: do not remove the manifest/claims in a way that makes bytes unreachable after a partial failure, and do not delete bytes while another local claim is supposed to survive.

Privacy / security

  • The device storage screen may show a generic hidden row and its size without revealing title/author to an unauthorized active profile, as today.
  • Confirmation may say 'other profiles on this device' but should not enumerate their identities unless separately authorized/needed.
  • Physical-file presence does not grant playback/library access.

Automated-test level

If approved:

  • active profile owns sole claim -> device remove deletes bytes/manifest/claim;
  • two-profile shared copy -> profile-level remove keeps bytes;
  • device-level remove -> all local claims removed and bytes removed;
  • active profile does not own hidden copy -> device-level remove still behaves according to explicit device-management authority without leaking metadata;
  • pinned-by-other-profile cases according to the selected pin model;
  • failure/partial deletion ordering tests.

Device / platform acceptance

  • Two local profiles sharing one downloaded book.
  • Verify normal book-level Remove removes only one claim.
  • Verify device-storage Remove clearly warns and removes the physical copy for both if that product decision is approved.
  • Re-enter each profile and verify progress remains but offline availability is gone as intended.

Estimated effort

Medium.

Implementation risk

High because the action is destructive and crosses the existing shared-copy ownership model.

After BW-DL-02/03; product decision may be made earlier. Do not block non-destructive recovery improvements on this decision.

Acceptance criteria

To be finalized once the owner selects the destructive/pin semantics. No implementation work should begin from this issue while the product-decision section remains unresolved.

> Migrated from [GitHub issue #111](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/111). Forgejo issue: #21. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Candidate implementation follow-up from #15 / [GitHub PR #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/106), **blocked on owner product decision before implementation**. ## Problem / opportunity The Downloads management screen explicitly lists every physical downloaded copy on the device, including rows whose title is hidden because the active profile cannot access that book. Its comments describe the screen as answering 'what is using space on this phone'. The actions do not currently match that device-wide meaning: - Remove resolves the active profile and releases only that profile's claim. A hidden copy owned only by another profile can therefore show a Delete action that cannot remove the physical copy. - `OfflineBook.isPinned` is true if any profile has pinned the shared physical copy, while `setPinned(...)` writes only the active profile's request. A globally-looking pin can therefore remain set because another profile owns the pin. ## Product decision required Approve or reject this split before implementation: 1. **Book/profile surfaces:** `Remove my download` / release this profile's claim. If another profile still requests the copy, the physical files stay. 2. **Device storage management surface:** `Remove from device` means remove the physical copy for **all local profile claims**, with an explicit confirmation that other profiles on this device will need to download it again. For pinning, choose one of these before coding: - device-level pin owned by the physical copy; or - profile pins remain separate and the device screen exposes aggregate state without pretending one active-profile toggle controls all of them. ## User value The storage-management screen does what it says, while normal book/profile actions preserve the existing safe shared-copy semantics. ## Scope if approved - Introduce explicit repository/use-case operations for profile-claim removal versus device-copy removal; do not overload the existing `release(profileId)` method with both meanings. - Make destructive scope clear in UI copy/confirmation before the action. - Resolve device-level pin semantics consistently with the chosen product decision. - Preserve title masking and profile authorization on device-wide rows. - Ensure removing the physical copy updates all local manifest/claim/local-availability state coherently. ## Explicitly out of scope - No server-side deletion. - No progress deletion. - No profile permission changes. - No automatic cleanup behavior change except where it calls a clearly scoped existing device-copy cleanup operation. - No revealing hidden book titles or which other named profile owns a copy. ## Dependencies - **Owner product decision above.** Do not implement until approved. - Parent audit #15 / [GitHub PR #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/106). - BW-DL-02/#17 is recommended first for consistent presentation but not a strict data dependency. ## Architecture seams affected - `DownloadRepository` claim/copy operations. - `OfflineFiles` removal semantics. - Downloads ViewModel/device-storage UI. - Local availability projection after physical deletion. - Pin ownership model. ## Server / API assumptions None. This is local-device storage/authorization bookkeeping only. ## Storage / migration implications Probably no Room schema change is required for an explicit 'remove all local requests + physical copy' operation because claims already exist as rows. Pin semantics may require a schema/model decision if a true device-level pin is chosen. Any deletion operation must preserve transaction/order safety: do not remove the manifest/claims in a way that makes bytes unreachable after a partial failure, and do not delete bytes while another local claim is supposed to survive. ## Privacy / security - The device storage screen may show a generic hidden row and its size without revealing title/author to an unauthorized active profile, as today. - Confirmation may say 'other profiles on this device' but should not enumerate their identities unless separately authorized/needed. - Physical-file presence does not grant playback/library access. ## Automated-test level If approved: - active profile owns sole claim -> device remove deletes bytes/manifest/claim; - two-profile shared copy -> profile-level remove keeps bytes; - device-level remove -> all local claims removed and bytes removed; - active profile does not own hidden copy -> device-level remove still behaves according to explicit device-management authority without leaking metadata; - pinned-by-other-profile cases according to the selected pin model; - failure/partial deletion ordering tests. ## Device / platform acceptance - Two local profiles sharing one downloaded book. - Verify normal book-level Remove removes only one claim. - Verify device-storage Remove clearly warns and removes the physical copy for both if that product decision is approved. - Re-enter each profile and verify progress remains but offline availability is gone as intended. ## Estimated effort Medium. ## Implementation risk High because the action is destructive and crosses the existing shared-copy ownership model. ## Recommended sequence After BW-DL-02/03; product decision may be made earlier. Do not block non-destructive recovery improvements on this decision. ## Acceptance criteria To be finalized once the owner selects the destructive/pin semantics. No implementation work should begin from this issue while the product-decision section remains unresolved. ## Links - Parent audit: #15 - Audit PR: [GitHub #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/106) - Related presentation foundation: #17
Author
Owner

Product-decision gate — refreshed against PR #94

Unified implementation PR: #94
Current Downloads branch: mcp/downloads-coherent-experience

The non-destructive Downloads work is now integrated through #19, #22, #29 and #20. #21 is the remaining product decision before destructive device-management semantics can be implemented.

Current behavior, confirmed from current branch

Book/profile removal

  • OfflineFiles.remove(profileId, serverId, bookId) releases only that profile's claim.
  • If another local profile still claims the physical copy, bytes remain.
  • If it was the last claim, bytes are deleted and the manifest is forgotten.

That is correct for a book/profile surface: Remove my download.

Downloads device-management screen

  • The screen is explicitly device-wide and may show a generic hidden row for media the active profile cannot see.
  • Its current Remove action nevertheless calls the active-profile claim removal above.
  • Therefore a hidden copy belonging only to another local profile can show a delete control that cannot actually remove the physical copy.

Pinning

  • Pin storage is currently on each profile's download_requests row.
  • OfflineBook.isPinned is an aggregate: true if any profile pinned the shared physical copy.
  • The device screen's toggle writes only the active profile's request.
  • Therefore the screen can look globally pinned while an active-profile toggle cannot clear another profile's pin.

Decision A — device-management Remove

Approve one:

A1 — Explicit device-wide removal (recommended contract for the current screen semantics)

  • Book/profile surfaces keep Remove my download and only release that profile claim.
  • Downloads/device-storage surface uses a new, separately named operation: Remove from device.
  • Confirmation explicitly says the physical copy and all local download claims will be removed and other profiles on this device will need to download it again.
  • It may operate on a hidden row without revealing title, author, owner profile names or other protected metadata.
  • Server progress/history is untouched.

A2 — Keep claim-scoped removal everywhere

  • Downloads/device-storage screen cannot truthfully mean “remove from device.”
  • Hidden rows not claimed by the active profile must not expose a misleading Delete action.
  • Device-wide physical deletion remains unavailable.

Decision B — pin ownership

Approve one:

B1 — Device-level physical pin

  • Move pin ownership to the physical downloaded-book copy.
  • One toggle in device storage controls exactly the state it displays.
  • All profiles benefit from the same “never auto-clean this physical copy” protection.
  • Requires a Room migration from profile request pin state to the physical copy, with conservative migration: physical pin becomes true if any existing profile pin is true.

B2 — Keep profile-level pins, expose aggregate device state

  • Existing per-profile pins remain.
  • Device management displays aggregate protection (“Pinned by a local profile” / equivalent) but does not pretend one active-profile toggle controls all pins.
  • Profile/book surfaces may control only their own pin.
  • Avoids a pin schema migration, but the device screen needs a different aggregate presentation/action model.

Safety requirement regardless of choice

A device-wide delete must not first erase claims/manifest and then discover filesystem deletion failed. The implementation will use an explicit device-copy operation with failure-safe ordering so failed byte deletion cannot leave an unreachable orphaned copy.

No server-side deletion, progress deletion, permission changes or identity disclosure are part of #21.

OWNER DECISION REQUIRED

Please choose A1 or A2, and B1 or B2.

## Product-decision gate — refreshed against PR #94 Unified implementation PR: #94 Current Downloads branch: `mcp/downloads-coherent-experience` The non-destructive Downloads work is now integrated through #19, #22, #29 and #20. #21 is the remaining product decision before destructive device-management semantics can be implemented. ### Current behavior, confirmed from current branch **Book/profile removal** - `OfflineFiles.remove(profileId, serverId, bookId)` releases only that profile's claim. - If another local profile still claims the physical copy, bytes remain. - If it was the last claim, bytes are deleted and the manifest is forgotten. That is correct for a book/profile surface: **Remove my download**. **Downloads device-management screen** - The screen is explicitly device-wide and may show a generic hidden row for media the active profile cannot see. - Its current Remove action nevertheless calls the active-profile claim removal above. - Therefore a hidden copy belonging only to another local profile can show a delete control that cannot actually remove the physical copy. **Pinning** - Pin storage is currently on each profile's `download_requests` row. - `OfflineBook.isPinned` is an aggregate: true if any profile pinned the shared physical copy. - The device screen's toggle writes only the active profile's request. - Therefore the screen can look globally pinned while an active-profile toggle cannot clear another profile's pin. ### Decision A — device-management Remove Approve one: **A1 — Explicit device-wide removal (recommended contract for the current screen semantics)** - Book/profile surfaces keep `Remove my download` and only release that profile claim. - Downloads/device-storage surface uses a new, separately named operation: `Remove from device`. - Confirmation explicitly says the physical copy and **all local download claims** will be removed and other profiles on this device will need to download it again. - It may operate on a hidden row without revealing title, author, owner profile names or other protected metadata. - Server progress/history is untouched. **A2 — Keep claim-scoped removal everywhere** - Downloads/device-storage screen cannot truthfully mean “remove from device.” - Hidden rows not claimed by the active profile must not expose a misleading Delete action. - Device-wide physical deletion remains unavailable. ### Decision B — pin ownership Approve one: **B1 — Device-level physical pin** - Move pin ownership to the physical downloaded-book copy. - One toggle in device storage controls exactly the state it displays. - All profiles benefit from the same “never auto-clean this physical copy” protection. - Requires a Room migration from profile request pin state to the physical copy, with conservative migration: physical pin becomes true if any existing profile pin is true. **B2 — Keep profile-level pins, expose aggregate device state** - Existing per-profile pins remain. - Device management displays aggregate protection (“Pinned by a local profile” / equivalent) but does not pretend one active-profile toggle controls all pins. - Profile/book surfaces may control only their own pin. - Avoids a pin schema migration, but the device screen needs a different aggregate presentation/action model. ### Safety requirement regardless of choice A device-wide delete must not first erase claims/manifest and then discover filesystem deletion failed. The implementation will use an explicit device-copy operation with failure-safe ordering so failed byte deletion cannot leave an unreachable orphaned copy. No server-side deletion, progress deletion, permission changes or identity disclosure are part of #21. ## OWNER DECISION REQUIRED Please choose **A1 or A2**, and **B1 or B2**.
Author
Owner

Owner decision — removal and pin semantics resolved

Owner decision recorded from the current product discussion.

Physical copy / profile claims

  • One physical downloaded copy exists per (server, item) on the device.
  • Multiple profiles may share that same physical copy through separate profile claims.
  • Removing a download from one profile removes only that profile's claim.
  • If another profile still claims the book, the physical bytes remain and that other profile keeps offline access.
  • Physical bytes are removed only when the last profile claim is removed.

Cross-profile presentation

  • If the active profile may access the book but does not currently claim it, while another local profile already has the physical copy, the UI should indicate that the book is already downloaded on the device.
  • Choosing Download in that state should attach the active profile to the existing physical copy rather than downloading a duplicate.
  • If the active profile removes its claim while another claim remains, the UI should fall back to the "downloaded on device / available from another local claim" state rather than implying the bytes disappeared.
  • Privacy rules remain unchanged: no other profile identity or unauthorized book metadata is revealed.

Pin semantics

Pin is device-level and belongs to the physical copy.

Meaning:

  • A pinned physical copy is protected from automatic cleanup.
  • Pin is not profile-specific.
  • Any profile viewing an authorized representation of the physical copy sees the same pin state.
  • Toggling Pin changes the protection state of the one shared physical copy, not a profile claim.
  • Pin does not change playback authorization, progress, profile claims, or server state.

Implementation consequence

The current schema/model stores isPinned on each profile request and aggregates OfflineBook.isPinned with "any profile pinned". The Downloads UI then writes only the active profile's pin, which is inconsistent with the decision above.

Implementation should therefore expose a true physical-copy pin operation/state and keep profile claims separate. Avoid silently treating one active-profile request row as the device pin.

With this decision, #21 is no longer blocked on owner product semantics. Acceptance criteria can now be finalized around:

  1. shared single-copy claims;
  2. claim-scoped Remove;
  3. last-claim physical deletion;
  4. device-level Pin;
  5. "already downloaded on device" presentation/instant claim attach;
  6. existing privacy/title-masking rules.
## Owner decision — removal and pin semantics resolved Owner decision recorded from the current product discussion. ### Physical copy / profile claims - One physical downloaded copy exists per `(server, item)` on the device. - Multiple profiles may share that same physical copy through separate profile claims. - Removing a download from one profile removes only that profile's claim. - If another profile still claims the book, the physical bytes remain and that other profile keeps offline access. - Physical bytes are removed only when the last profile claim is removed. ### Cross-profile presentation - If the active profile may access the book but does not currently claim it, while another local profile already has the physical copy, the UI should indicate that the book is already downloaded on the device. - Choosing Download in that state should attach the active profile to the existing physical copy rather than downloading a duplicate. - If the active profile removes its claim while another claim remains, the UI should fall back to the "downloaded on device / available from another local claim" state rather than implying the bytes disappeared. - Privacy rules remain unchanged: no other profile identity or unauthorized book metadata is revealed. ### Pin semantics **Pin is device-level and belongs to the physical copy.** Meaning: - A pinned physical copy is protected from automatic cleanup. - Pin is not profile-specific. - Any profile viewing an authorized representation of the physical copy sees the same pin state. - Toggling Pin changes the protection state of the one shared physical copy, not a profile claim. - Pin does not change playback authorization, progress, profile claims, or server state. ### Implementation consequence The current schema/model stores `isPinned` on each profile request and aggregates `OfflineBook.isPinned` with "any profile pinned". The Downloads UI then writes only the active profile's pin, which is inconsistent with the decision above. Implementation should therefore expose a true physical-copy pin operation/state and keep profile claims separate. Avoid silently treating one active-profile request row as the device pin. With this decision, #21 is no longer blocked on owner product semantics. Acceptance criteria can now be finalized around: 1. shared single-copy claims; 2. claim-scoped Remove; 3. last-claim physical deletion; 4. device-level Pin; 5. "already downloaded on device" presentation/instant claim attach; 6. existing privacy/title-masking rules.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#21
No description provided.