Describe albums, the folder pickers and download progress in the designs

storage.md's trait listing stopped at get; it now has get_reporting,
what the default and the Nextcloud override do, and where develop reads
the figures. A new §5.3 says how folders are chosen — the portal or
Windows dialogue, the server browser whose New folder is create_dir,
SAF on Android — and where an album's files go: a server folder relative
to the account root, with the outbox's third .dest line, or a device
folder that never syncs.

catalog.md §8.2 said only collections merge, which had not been true
since keywords, people and capture metadata joined them, and is less
true with albums; it now lists what merges and why album_folders does
not. §2 records that the album tables, like dedup_probes, are made on
first use rather than by a migration.

outstanding.md said there was no SAF code on Android. There is now,
for album folders only, and it carries TRACES: FR-PLAT-AND-1, which
the entry says overstates a requirement about the library; FR-PLAT-AND-2
and S10's row follow from that.
This commit is contained in:
2026-09-26 14:54:46 -04:00
parent caaae11d98
commit dee509c6ef
3 changed files with 118 additions and 24 deletions
+27 -15
View File
@@ -34,6 +34,10 @@ beside re-import detection; the accessibility and localisation counts in §6 had
against the tree since 2026-08-30 and are replaced; and §4a records what the develop and keyboard
work of 0.15.0 and 0.16.0 left open.
**And again for 0.17.0.** Folders are chosen through the platform's dialogue now, so FR-PLAT-LIN-3
in §5 is rewritten around what the Flatpak has still not shown; albums brought the first SAF code,
which FR-PLAT-AND-1's entry now describes, along with why its new tag overstates it.
---
## 1. Plugins — post-v1 since 2026-09-19
@@ -234,22 +238,30 @@ models, has been measured on a tablet ([faces.md §12.1](faces.md)), and since 0
develop view zero-copy as the desktop does ([technical-debt.md TD-1](technical-debt.md), paid off).
It carries the manual and opens it in a WebView. What is missing is the platform contract around it.
**FR-PLAT-AND-1 is untagged, and what it was tagged for was intent rather than code.**
The requirement demands that library access be obtained *exclusively* through the Storage Access
Framework. There is no SAF code: no `ACTION_OPEN_DOCUMENT_TREE`, no `takePersistableUriPermission`,
no `DocumentsContract`. Its two tags rested on a `SourceRef::Document` variant constructed only
inside `#[cfg(test)]` — `LocalStorage::open` refuses it, and the test that proves so is named
`a_reference_of_the_wrong_kind_is_refused_rather_than_guessed_at` — and on
`dr_plat::imports_supported`, which *returns false on Android* and whose own documentation says it
"stops being false when a SAF implementation lands". The second tag documented the absence of the
thing it was counted as evidence for. Both have been removed; this is the "plumbing a future feature
would use" case [CONTRIBUTING.md](../../CONTRIBUTING.md) and [code-health.md CH-4](code-health.md) both
warn about. Android reaches a library through a Nextcloud account or a folder, over paths, like the
desktop.
**FR-PLAT-AND-1 — SAF is built for export folders, not for the library.** The requirement demands
that library access be obtained *exclusively* through the Storage Access Framework. Until 0.17.0
there was no SAF code at all, and the requirement's two tags rested on a `SourceRef::Document`
variant constructed only inside `#[cfg(test)]` and on `dr_plat::imports_supported`, which *returns
false on Android* and whose own documentation says it "stops being false when a SAF implementation
lands". Both were removed as intent rather than code — the "plumbing a future feature would use"
case [CONTRIBUTING.md](../../CONTRIBUTING.md) and [code-health.md CH-4](code-health.md) both warn
about.
0.17.0 brought the first real SAF code, for albums (FR-EXP-10): `FolderPicker.java` starts
`ACTION_OPEN_DOCUMENT_TREE` from a translucent activity of its own (the main activity is
`NativeActivity`, whose results are not ours) and takes a persistable grant; `Saf.java` writes each
export through `DocumentsContract`; `ui/dr-ui/src/saf.rs` is the JNI bridge. `saf.rs` and the export
path now carry `TRACES: FR-PLAT-AND-1`, and the matrix counts the requirement as covered. **That
overstates it.** The mechanism is the one the requirement names, but its subject is the library, and
Android still reaches a library through a Nextcloud account or a folder, over paths, like the
desktop. Either the tags narrow to FR-EXP-10 or the requirement is met for the library too; until
one of those, read the coverage figure with this one subtracted.
That has a consequence for the rest of the cluster: **FR-PLAT-AND-2** — detecting the loss of a
granted tree permission and marking images offline rather than deleting rows — cannot be built until
there is a permission to lose. It is listed here as unbuilt, but it is blocked, not skipped.
granted tree permission and marking images offline rather than deleting rows — is still blocked for
the library, because there is no library grant to lose. An album's folder has a grant now, and
nothing checks for its loss: an export into a folder whose grant has gone fails with whatever the
write raises, rather than the album saying beforehand that it needs a folder again.
**FR-PLAT-AND-4 — half built.** The runner is done (`core/dr-catalog/src/runner.rs`): the
queue that `jobs.rs` always had is now claimed from, completed, failed and recovered after a
@@ -501,7 +513,7 @@ requirement text that asks for it:
|---|---|---|
| S6 | FR-DSP-2, NFR-RES-2 — tiling and images larger than GPU memory | Nothing; needs a device and a large image |
| S9 | R1's tolerance threshold, and therefore R1 | Nothing; the threshold is defined *by* running it |
| S10 | Whether SAF at 10k files meets NFR-P1/P3 | §5 — there is no SAF code to measure |
| S10 | Whether SAF at 10k files meets NFR-P1/P3 | §5 — SAF reaches album folders only, never a library to enumerate |
| S11 | NFR-COMPAT-2, and whether Play makes SAF binding | Nothing |
| S13 | NFR-A11Y-2 on Android | §6 — there is almost nothing to test with |