[BW-DL-02] Expose safe download failure reason and recovery presentation state #17

Closed
opened 2026-09-18 08:45:59 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #107. Forgejo issue: #17. 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

Implementation-ready follow-up from completed audit #15. Unblocked.

Problem / opportunity

BookWave already persists DownloadedBookEntity.failureSummary and DefaultDownloadRepository.markFailed(...) writes a safe AppError.summary, but DownloadMappers.toDomain drops that field and OfflineBook cannot carry it. The Downloads UI therefore knows only isFailed, not why the transfer stopped.

At the same time, durable manifest state and transient WorkManager execution state answer different questions. The UI needs a named presentation policy before later slices add Wi-Fi/backoff state.

User value

A failed or interrupted download can explain the problem in actionable language while preserving partial bytes and existing download correctness semantics.

Scope

  • Carry the already-persisted safe failure summary through the download repository/domain boundary.
  • Define a pure download recovery/presentation model that can distinguish at least Complete, Paused, Queued/Starting, Running, Retrying/Waiting (as input states even if BW-DL-04 supplies them later), and terminal/recoverable Failed.
  • Define precedence when durable manifest state and execution evidence disagree.
  • Keep safe failure wording separate from raw exceptions/URLs/responses.
  • Provide the model needed by BW-DL-03 and BW-DL-04; avoid a broad visual redesign in this slice.

Explicitly out of scope

  • No WorkManager observation implementation yet; #19 / BW-DL-04 owns that adapter.
  • No removable-storage redesign; #20 / BW-DL-05 owns it.
  • No device-wide delete/pin semantics; #21 / BW-DL-06 owns them.
  • No widget.
  • No SAF arbitrary-folder implementation.

Dependencies

None remaining. Parent audit #15 is completed. GitHub PR #106 was planning-only and closed without merge.

Architecture seams affected

  • core:model download model or an equivalent domain-facing safe failure representation.
  • data:downloads entity -> domain mapping.
  • DownloadsViewModel presentation projection.
  • A pure presentation policy that does not make Room mirror WorkManager.

Server / API assumptions

No new Audiobookshelf API. The persisted failure text must continue to derive from BookWave's sanitized AppError.summary, not raw server bodies.

Storage / migration implications

No Room migration should be required for the failure reason: failureSummary is already stored in downloaded_books.

If the implementation proposes any other durable field, justify it separately rather than expanding this slice by default.

Privacy / security

  • Never expose access tokens, credential-bearing URLs, raw server responses or private filesystem paths.
  • Title-hidden download rows remain title-hidden; an error must not reveal the book identity to a profile that cannot see it.
  • Preserve current log redaction rules.

Automated-test level

  • Mapper/repository test proving the stored safe summary reaches the domain/presentation layer.
  • Pure policy tests covering state precedence and every state listed above.
  • Regression: unknown/future durable download state fails conservatively rather than reading as Complete.
  • ViewModel test proving hidden rows remain metadata-redacted while retaining safe recovery state.

Device / platform acceptance

No special hardware is required for the core slice. A normal device smoke test should confirm a forced non-retryable failure shows the intended safe explanation without losing partial data.

Estimated effort

Small to Medium.

Implementation risk

Low. The main risk is accidentally turning a presentation need into a second durable state machine.

  1. #17 / BW-DL-02 — this issue
  2. #18 / BW-DL-03
  3. #19 / BW-DL-04

Acceptance criteria

  • A failed manifest can expose its already-stored safe reason to UI/domain code.
  • Presentation state is a pure, tested projection rather than another persisted WorkManager mirror.
  • Paused is never described as failed.
  • Retrying/waiting can be represented distinctly once #19 supplies execution evidence.
  • No partial or completed file is deleted by this slice.
  • Completed parent audit: #15
  • Follow-up action correction: #18
  • Follow-up WorkManager projection: #19
> Migrated from [GitHub issue #107](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/107). Forgejo issue: #17. 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 Implementation-ready follow-up from completed audit #15. **Unblocked.** ## Problem / opportunity BookWave already persists `DownloadedBookEntity.failureSummary` and `DefaultDownloadRepository.markFailed(...)` writes a safe `AppError.summary`, but `DownloadMappers.toDomain` drops that field and `OfflineBook` cannot carry it. The Downloads UI therefore knows only `isFailed`, not why the transfer stopped. At the same time, durable manifest state and transient WorkManager execution state answer different questions. The UI needs a named presentation policy before later slices add Wi-Fi/backoff state. ## User value A failed or interrupted download can explain the problem in actionable language while preserving partial bytes and existing download correctness semantics. ## Scope - Carry the already-persisted safe failure summary through the download repository/domain boundary. - Define a pure download recovery/presentation model that can distinguish at least Complete, Paused, Queued/Starting, Running, Retrying/Waiting (as input states even if BW-DL-04 supplies them later), and terminal/recoverable Failed. - Define precedence when durable manifest state and execution evidence disagree. - Keep safe failure wording separate from raw exceptions/URLs/responses. - Provide the model needed by BW-DL-03 and BW-DL-04; avoid a broad visual redesign in this slice. ## Explicitly out of scope - No WorkManager observation implementation yet; #19 / BW-DL-04 owns that adapter. - No removable-storage redesign; #20 / BW-DL-05 owns it. - No device-wide delete/pin semantics; #21 / BW-DL-06 owns them. - No widget. - No SAF arbitrary-folder implementation. ## Dependencies None remaining. Parent audit #15 is completed. [GitHub PR #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/106) was planning-only and closed without merge. ## Architecture seams affected - `core:model` download model or an equivalent domain-facing safe failure representation. - `data:downloads` entity -> domain mapping. - `DownloadsViewModel` presentation projection. - A pure presentation policy that does not make Room mirror WorkManager. ## Server / API assumptions No new Audiobookshelf API. The persisted failure text must continue to derive from BookWave's sanitized `AppError.summary`, not raw server bodies. ## Storage / migration implications **No Room migration should be required for the failure reason:** `failureSummary` is already stored in `downloaded_books`. If the implementation proposes any other durable field, justify it separately rather than expanding this slice by default. ## Privacy / security - Never expose access tokens, credential-bearing URLs, raw server responses or private filesystem paths. - Title-hidden download rows remain title-hidden; an error must not reveal the book identity to a profile that cannot see it. - Preserve current log redaction rules. ## Automated-test level - Mapper/repository test proving the stored safe summary reaches the domain/presentation layer. - Pure policy tests covering state precedence and every state listed above. - Regression: unknown/future durable download state fails conservatively rather than reading as Complete. - ViewModel test proving hidden rows remain metadata-redacted while retaining safe recovery state. ## Device / platform acceptance No special hardware is required for the core slice. A normal device smoke test should confirm a forced non-retryable failure shows the intended safe explanation without losing partial data. ## Estimated effort Small to Medium. ## Implementation risk Low. The main risk is accidentally turning a presentation need into a second durable state machine. ## Recommended sequence 1. **#17 / BW-DL-02 — this issue** 2. #18 / BW-DL-03 3. #19 / BW-DL-04 ## Acceptance criteria - A failed manifest can expose its already-stored safe reason to UI/domain code. - Presentation state is a pure, tested projection rather than another persisted WorkManager mirror. - Paused is never described as failed. - Retrying/waiting can be represented distinctly once #19 supplies execution evidence. - No partial or completed file is deleted by this slice. ## Links - Completed parent audit: #15 - Follow-up action correction: #18 - Follow-up WorkManager projection: #19
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#17
No description provided.