rclone/docs/plans/001-protondrive-tier1-workspace/task-20-review.md

Task 20 review (docs) - base c1464a39a, head 7be50f9e2

Spec Compliance

• Verdict: spec compliant, with two Important wording fixes needed (below). Not a miss of any listed file: protondrive.md, protondrive.yaml, ARCHITECTURE/DECISIONS/TODO, conformance checklist all have hunks.
• Cannot verify from the diff: that the transcript matches the real binary (report says captured offline; prompts spot-checked against protondrive.go only); the yaml features were produced offline per the report, but I confirmed them against the code (below).

Strengths

• Page is free of fork-only content (no fake server, plans, ruling numbers, accounts); no claim of live testing; browser sign-in never said to be tested.
• Autogenerated block left untouched; Go Help: change limited to ignore_signature_errors and accurate.
• Rulings 18-19, 21-26, 28, both protocol limits, --dump exposure, ranged-read caveat all present. 20 and 27 reasonably omitted as not user-visible.

Claims spot-checked (page claim -> evidence)

1. Third-party notice verbatim -> protondrive.go:49 (thirdPartyNotice), used in the config prompt at :596. OK.
2. Browser sign-in default only when no password -> protondrive.go:~592 fs.ConfigConfirm("choose", !hasPassword, ...). OK.
3. CAPTCHA fails password sign-in, use reconnect -> protondrive.go:542, 633 (errCaptcha). OK.
4. Re-sign-in uses otp_secret_key else asks reconnect -> protondrive.go:492-498, 535, 541. OK.
5. 10 minute wait -> protondrive.go:54 forkPollTimeout = 10*time.Minute. OK.
6. SetModTime unsupported; precision 1 s -> protondrive.go:1130 (ErrorCantSetModTime), :891-893. OK.
7. Folder time set at creation -> protondrive.go:761 (createFolder(..., time.Now())). OK.
8. SHA1 is the uploader's recorded value, empty if absent -> nodes.go:161-166; Hashes protondrive.go:1075. OK.
9. Block hash check, 3 attempts -> download.go:54 blockAttempts = 3, :505. OK.
10. ~1 request per 80 MiB -> download.go:46 blocksPerPage = 20 x 4 MiB. OK.
11. Manifest verified before first byte on full read; whole-file range takes the same path -> download.go:83-97, protondrive.go:1173 (openWhole). OK.
12. Upload checks each block decrypts -> upload.go:652,668 (checkBlock). OK.
13. Name rules (255 UTF-16 units, empty, ., .., /, NUL, UTF-8) -> crypto.go:500-519. OK. Default encoding Slash/Zero/Dot + spaces + InvalidUtf8 -> protondrive.go:~147-151 with encoder.Base. OK.
14. Rmdir asks server, refuses non-empty; trash for Rmdir/Purge; CleanUp empties whole volume trash -> protondrive.go:867-885, 930-947, 949-951; nodes.go:1308. OK.
15. about is account-wide -> nodes.go:1318-1323 (/core/v4/users UsedSpace/MaxSpace). OK (the report itself notes the "whole account" wording is not live-checked; code supports it).
16. upload_concurrency default 4, max 5; 10 up/10 down per remote -> upload.go:44-45, nodes.go:50,187-188. OK.
17. 2^19 blocks, depth 2048 -> download.go:71, nodes.go:42. OK.
18. --dump headers exposes x-pm-uid, pm-storage-token -> session.go:248, download.go:273, upload.go:828. OK; "dump bodies" tokens rests on TODO.md:76-80 / TestNoSecretsInLogs only.
19. Only My Files -> nodes.go:322 drive/v2/shares/my-files. OK.
20. Root of trust / subtree unverified / refusals -> nodes.go:353-372, 939, 1139. OK.
21. Draft replace wording -> upload.go:291, protondrive.go:172-183 Help. OK.
22. "outcome unknown" text -> upload.go:35. OK.
23. Docs/Sheets left out with one notice -> nodes.go:845, 884. OK.
24. yaml features vs Fs: methods present About 1009, CleanUp 949, Copy 905, DirCacheFlush 1062, DirMove 1030, Disconnect 1054, ListP 802, Move 962, Purge 930, PutStream 852, Shutdown 1069; Features{} sets ReadMimeType, CanHaveEmptyDirectories (:674-677). No OpenWriterAt/ChangeNotify/Metadata/PublicLink methods exist. NoMultiThreading removal correct. Hashes sha1, precision 1e9 match. OK.
25. All 40+ SDK paths in the checklist exist in the checkout (checked each with [ -e ], none missing).

Issues

Critical

None.

Important

1. docs/content/protondrive.md ("Ranged reads" paragraph) understates the failure mode. It says ranged reads of files without recorded block sizes "only work from the start ... one from elsewhere may fail with an error". The code's own FIXME at backend/protondrive/download.go:143-146 says such a read "returns the wrong bytes", and the error at download.go:615-617 only fires when a second block is read after a mis-sized one (r.prevSize), so a single-block ranged read starting past block 0 can return wrong data silently. Reword to "may fail with an error, or return the wrong bytes" (or fix the code). Overclaiming safety on a data-correctness path.
2. docs/specs/001-conformance-checklist.md:9 and docs/DECISIONS.md (new entry) say "tag js/v0.23.0 (commit 05c9115)". The local checkout at 05c9115 carries only the tag cs/v0.33.0 (a Kotlin client commit, "feat(client)!: create the Kotlin client..."); js/v0.23.0 is not a git tag there. What does tie them: client/js/CHANGELOG.md in that checkout has ## js/v0.23.0 (2026-10-19) as its newest entry, and client/js/package.json says version 0.0.1. Recommended wording: "SDK: github.com/ProtonDriveApps/sdk at commit 05c9115955589d9f6ab7392a36f8f0cb39327133 (2026-11-05; its client/js/CHANGELOG.md newest entry is js/v0.23.0, 2026-10-19). Local tags on that commit: cs/v0.33.0 only." Use the commit hash as the identifier in the "Last checked" column ("05c9115 (js/v0.23.0)") and in DECISIONS.md, and say the re-check method is "diff the listed files between the two commits" rather than between tags (the file lists are JS paths; a commit diff is unambiguous).

Minor

1. docs/content/protondrive.md autogenerated block is stale against the Go Help: fields (username/password still Required: true, old app_version/replace_existing_draft text including "Need to set to true for integration tests", no upload_concurrency or ignore_signature_errors), while the hand-written text refers to the missing options. Left alone per AGENTS.md and logged in TODO.md, which is acceptable, but nothing guarantees make backenddocs is run before any upstream PR; keep it in the Task 21 / pre-upstream checklist.
2. protondrive.go:~182-190 enable_caching Help still opens with "Notice: ... please disable this feature" for VFS mounts, while the page now says to set it false only when other clients change the same files. Not wrong, slightly inconsistent; the report flagged it.
3. docs/data/backends/protondrive.yaml: the yaml was hand-edited from an offline reproduction of manage_backends.py rather than the script; the result matches the code, so no action beyond noting it in the commit/handoff.
4. "--dump bodies shows access, refresh and upload tokens" is supported only by a TODO.md note about a test, not by a code location; fine, but keep it phrased as it is (no stronger).
5. Checklist "Last checked" repeats js/v0.23.0 on every row although the review was one pass at one commit; harmless, but a single header line plus per-row blank-until-changed would age better.

Assessment

Spec: compliant (see Important items for wording corrections).

Task quality: Needs fixes (two Important wording items; both are small doc edits).

Reasoning: The page's behavioural claims match the code on all 25 spot-checks, no fork-only content, no live-testing overclaim, yaml matches Fs features. The ranged-read caveat under-describes a known wrong-bytes case, and the SDK version identifier in the checklist and DECISIONS entry should cite the commit hash.