[BW-DL-06] Make device-wide download copy management semantics explicit #21
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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:
OfflineBook.isPinnedis true if any profile has pinned the shared physical copy, whilesetPinned(...)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:
Remove my download/ release this profile's claim. If another profile still requests the copy, the physical files stay.Remove from devicemeans 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:
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
release(profileId)method with both meanings.Explicitly out of scope
Dependencies
Architecture seams affected
DownloadRepositoryclaim/copy operations.OfflineFilesremoval semantics.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
Automated-test level
If approved:
Device / platform acceptance
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
Product-decision gate — refreshed against PR #94
Unified implementation PR: #94
Current Downloads branch:
mcp/downloads-coherent-experienceThe 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.That is correct for a book/profile surface: Remove my download.
Downloads device-management screen
Pinning
download_requestsrow.OfflineBook.isPinnedis an aggregate: true if any profile pinned the shared physical copy.Decision A — device-management Remove
Approve one:
A1 — Explicit device-wide removal (recommended contract for the current screen semantics)
Remove my downloadand only release that profile claim.Remove from device.A2 — Keep claim-scoped removal everywhere
Decision B — pin ownership
Approve one:
B1 — Device-level physical pin
B2 — Keep profile-level pins, expose aggregate device state
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.
Owner decision — removal and pin semantics resolved
Owner decision recorded from the current product discussion.
Physical copy / profile claims
(server, item)on the device.Cross-profile presentation
Pin semantics
Pin is device-level and belongs to the physical copy.
Meaning:
Implementation consequence
The current schema/model stores
isPinnedon each profile request and aggregatesOfflineBook.isPinnedwith "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: