[BW-DL-07] Add explicit discard-partial recovery action #22

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

Migrated from GitHub issue #112. Forgejo issue: #22. 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 follow-up from #15 / GitHub PR #106.

Problem / opportunity

BookWave deliberately preserves .part files after ordinary download failures and pauses so Retry/Resume can continue instead of starting over. That is correct. But a listener may eventually decide a stuck/abandoned partial is not worth keeping and want to reclaim the space.

The underlying capability already exists as OfflineFiles.discardPartials(...); it is not currently a first-class recovery decision in the Downloads UI.

User value

A listener can reclaim resumable partial-download space deliberately without deleting already-committed files or the whole download record, while normal Retry continues to preserve work already done.

Scope

  • Expose Discard partial download only as a secondary/destructive recovery action for applicable Paused/Failed states.
  • Make Retry/Resume the primary action and preserve partial data by default.
  • Show the amount of resumable data that will be discarded where it can be computed truthfully.
  • Require confirmation before destroying .part data.
  • After discard, keep the manifest/profile claim in a clean recoverable state so a later Retry starts from zero only for the discarded non-complete files.
  • Preserve committed files.

Explicitly out of scope

  • Do not call this action Repair; verification and discarding solve different problems.
  • No automatic partial cleanup while a live manifest/claim still wants the download.
  • No deletion of committed audio files.
  • No entire-book/device-copy removal semantics; BW-DL-06 owns that.
  • No storage-volume redesign.

Dependencies

  • BW-DL-03 / #18 — correct recovery action hierarchy must already exist so destructive discard cannot become the primary failure action.
  • Parent audit #15 / GitHub PR #106.

Architecture seams affected

  • Existing OfflineFiles.discardPartials domain capability.
  • Downloads ViewModel recovery actions.
  • Downloads UI confirmation/copy.

Server / API assumptions

None. A later Retry uses the existing download path/server media endpoints as usual.

Storage / migration implications

None expected. The existing capability deletes .part files and resets their recorded downloaded byte count while retaining the manifest/claim.

The implementation must confirm the current state transition after discard is unambiguous; if the manifest remains Failed/Paused, the UI should still offer the correct next action rather than implying bytes remain.

Privacy / security

No media identity should leak through title-hidden rows. The confirmation may show reclaimed byte count but not hidden title/author information.

Automated-test level

  • Existing/expanded storage tests: only .part files are deleted.
  • Committed files remain untouched.
  • Manifest/claim survive.
  • Downloaded byte counts for discarded non-complete files reset appropriately.
  • Retry after discard starts those files from zero and does not refetch already-complete files.
  • UI requires confirmation and exposes the action only for applicable states.

Device / platform acceptance

  • Pause/fail a sizeable download after partial progress.
  • Confirm displayed reclaimable amount is sensible.
  • Discard partials and verify device storage decreases.
  • Retry and confirm completed files are reused while discarded partial file restarts.
  • Process restart between discard and Retry remains consistent.

Estimated effort

Small to Medium.

Implementation risk

Medium because it intentionally destroys resumable user data, even though it does not delete committed media.

After #18. It does not need to block BW-DL-04 or BW-DL-05.

Acceptance criteria

  • Retry/Resume always preserves partials by default.
  • Discard is explicit, secondary and confirmed.
  • Only .part data is removed; committed media stays.
  • The amount reclaimed is reported truthfully where available.
  • A later Retry remains valid and starts only discarded portions from zero.
> Migrated from [GitHub issue #112](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/112). Forgejo issue: #22. 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 follow-up from #15 / [GitHub PR #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/106). ## Problem / opportunity BookWave deliberately preserves `.part` files after ordinary download failures and pauses so Retry/Resume can continue instead of starting over. That is correct. But a listener may eventually decide a stuck/abandoned partial is not worth keeping and want to reclaim the space. The underlying capability already exists as `OfflineFiles.discardPartials(...)`; it is not currently a first-class recovery decision in the Downloads UI. ## User value A listener can reclaim resumable partial-download space deliberately without deleting already-committed files or the whole download record, while normal Retry continues to preserve work already done. ## Scope - Expose **Discard partial download** only as a secondary/destructive recovery action for applicable Paused/Failed states. - Make Retry/Resume the primary action and preserve partial data by default. - Show the amount of resumable data that will be discarded where it can be computed truthfully. - Require confirmation before destroying `.part` data. - After discard, keep the manifest/profile claim in a clean recoverable state so a later Retry starts from zero only for the discarded non-complete files. - Preserve committed files. ## Explicitly out of scope - Do not call this action Repair; verification and discarding solve different problems. - No automatic partial cleanup while a live manifest/claim still wants the download. - No deletion of committed audio files. - No entire-book/device-copy removal semantics; BW-DL-06 owns that. - No storage-volume redesign. ## Dependencies - **BW-DL-03 / #18** — correct recovery action hierarchy must already exist so destructive discard cannot become the primary failure action. - Parent audit #15 / [GitHub PR #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/106). ## Architecture seams affected - Existing `OfflineFiles.discardPartials` domain capability. - Downloads ViewModel recovery actions. - Downloads UI confirmation/copy. ## Server / API assumptions None. A later Retry uses the existing download path/server media endpoints as usual. ## Storage / migration implications None expected. The existing capability deletes `.part` files and resets their recorded downloaded byte count while retaining the manifest/claim. The implementation must confirm the current state transition after discard is unambiguous; if the manifest remains Failed/Paused, the UI should still offer the correct next action rather than implying bytes remain. ## Privacy / security No media identity should leak through title-hidden rows. The confirmation may show reclaimed byte count but not hidden title/author information. ## Automated-test level - Existing/expanded storage tests: only `.part` files are deleted. - Committed files remain untouched. - Manifest/claim survive. - Downloaded byte counts for discarded non-complete files reset appropriately. - Retry after discard starts those files from zero and does not refetch already-complete files. - UI requires confirmation and exposes the action only for applicable states. ## Device / platform acceptance - Pause/fail a sizeable download after partial progress. - Confirm displayed reclaimable amount is sensible. - Discard partials and verify device storage decreases. - Retry and confirm completed files are reused while discarded partial file restarts. - Process restart between discard and Retry remains consistent. ## Estimated effort Small to Medium. ## Implementation risk Medium because it intentionally destroys resumable user data, even though it does not delete committed media. ## Recommended sequence After #18. It does not need to block BW-DL-04 or BW-DL-05. ## Acceptance criteria - Retry/Resume always preserves partials by default. - Discard is explicit, secondary and confirmed. - Only `.part` data is removed; committed media stays. - The amount reclaimed is reported truthfully where available. - A later Retry remains valid and starts only discarded portions from zero. ## Links - Parent audit: #15 - Audit PR: [GitHub #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/106) - Depends on: #18
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#22
No description provided.