docs: fold shipped specs into the architecture docs and delete them
A spec was a promise; sixteen of them had become descriptions of code that already shipped, sitting beside four that describe work still outstanding, with nothing in the file telling the two apart. Half the statuses were also wrong — audio-equalizer read "Accepted" with the EQ live on both platforms, the native video spec said the flag stays off after the default was flipped on. The shipped designs move into docs/architecture, which is the maintained description of the build, and the spec files go. Git history keeps the originals; what a future change still needs is carried across: - 01-rust-backend: favourites rewritten (the old section named a file that no longer exists and called shipped buttons "planned"), domain vocabulary owned by Rust (SearchScope, exclusions, the bitrate ladder), background workers - 02-svelte-frontend: app shell and chrome, library mosaic, series/episode navigation, downloaded browse, safe-area insets, native-video store, logging - 03-data-flow: locally-indexed search - 05-platform-backends: audio settings on ExoPlayer, the equalizer's band vocabulary, native video compositing, the background-audio handoff - 06-downloads-and-offline: one storage model, offline catalog visibility - 09-security: path confinement and input binding docs/specs/README.md now says what the directory is for and where each shipped design went. Deferred work the specs recorded is kept beside the code it concerns rather than lost: season-bounded autoplay, the two dead search commands, why indexing is a full crawl. requirements.md had fourteen stale statuses — Android audio parity still read "Linux only", DR-150 still said the native-video default was off, DR-190 was Proposed after DR-196 implemented it, and five tooling requirements were Proposed after landing. Three unbuilt specs suggested requirement ids that have since been allocated to other work; each now carries a warning.
This commit is contained in:
@@ -139,9 +139,56 @@ flowchart TB
|
||||
CheckStorage -->|"OK"| Download["Queue Download"]
|
||||
```
|
||||
|
||||
## One Storage Model: Cache Entries Are Downloads
|
||||
|
||||
**TRACES**: UR-071 | DR-126, DR-127
|
||||
|
||||
A cache entry **is** a download with a shorter life: the same `downloads` row and
|
||||
the same file handling, distinguished by `download_source` plus an expiry. There
|
||||
is one storage model rather than a cache and a download library that can
|
||||
disagree about what is on disk.
|
||||
|
||||
| `download_source` | Life | Reclaimed by |
|
||||
|-------------------|------|--------------|
|
||||
| `'auto'` (temporary) | Expiry, or eviction under space pressure | Both |
|
||||
| `'user'` (permanent) | No expiry | Neither |
|
||||
|
||||
**Eviction only reclaims the temporary tier.** `evict_lru_async` originally
|
||||
selected every completed download ordered by `completed_at ASC` with no source
|
||||
filter, so hitting the storage limit deleted the *oldest* download — typically a
|
||||
film saved deliberately for offline — to make room for a newly precached track.
|
||||
It now evicts only `COALESCE(download_source, 'user') = 'auto'` rows.
|
||||
`COALESCE` rather than a bare equality is load-bearing: rows predating the
|
||||
migration can be NULL, and **unknown provenance must be treated as the user's,
|
||||
never as disposable**. Freeing less than requested is the correct outcome when
|
||||
only user downloads remain — the caller reports "unable to free enough".
|
||||
|
||||
A temporary row can be **promoted** to permanent when the user chooses to keep
|
||||
it. That only clears the expiry and flips the source; the bytes never move.
|
||||
|
||||
## Offline Catalog Visibility
|
||||
|
||||
**TRACES**: UR-052 | DR-078, DR-079, DR-080
|
||||
|
||||
Offline, a library page shows **only media on the device**. A "Show all server
|
||||
media" toggle additionally reveals the cached server catalog, greyed out and
|
||||
queueable for download on reconnect.
|
||||
|
||||
The gate is a process-global `INCLUDE_CATALOG_BROWSE` in
|
||||
`repository/offline.rs`, written by the `set_show_server_catalog` command. It
|
||||
gates the synced-catalog leg of `get_items`; without it the toggle rendered but
|
||||
every server item still appeared, which is the defect the spec was written for.
|
||||
`isConnected` derives from backend-reported reachability alone (DR-079) — see
|
||||
[07-connectivity.md](07-connectivity.md).
|
||||
|
||||
Per-item disk usage comes from `repository_get_download_disk_usage`
|
||||
(`DownloadDiskUsage`), aggregated from `downloads.file_size` — used by the
|
||||
Downloaded browse cards, detail pages, the device total and the remove
|
||||
confirmation (DR-085).
|
||||
|
||||
## Download Commands
|
||||
|
||||
**Location**: `src-tauri/src/commands/download.rs`
|
||||
**Location**: `src-tauri/src/commands/download/` — `mod.rs` (the commands below), `pinning.rs`, `smart_cache.rs`
|
||||
|
||||
| Command | Parameters | Description |
|
||||
|---------|------------|-------------|
|
||||
@@ -152,6 +199,11 @@ flowchart TB
|
||||
| `resume_download` | `download_id` | Resume paused download |
|
||||
| `cancel_download` | `download_id` | Cancel and delete partial |
|
||||
| `delete_download` | `download_id` | Delete completed download |
|
||||
| `download_video` / `download_series` / `download_season` | item ids | Queue video content |
|
||||
| `get_download_storage_stats` | `user_id` | Device totals for the downloads screen |
|
||||
| `delete_album_downloads` / `delete_downloads_under` / `delete_all_downloads` | container id | Bulk removal |
|
||||
| `pin_item` / `unpin_item` / `is_item_pinned` | `item_id` | Protect metadata from a cache clear |
|
||||
| `set_max_concurrent_downloads` | `max` | Worker concurrency (3 by default) |
|
||||
|
||||
## Offline Commands
|
||||
|
||||
|
||||
Reference in New Issue
Block a user