feat(storage): support pause and resume for downloads

[grdsdev]

Summary

• Adds DownloadEngine — an actor-based state machine (idle → starting → downloading → paused → completed/failed/cancelled) that owns the URLSessionDownloadTask lifecycle
• pause() calls cancel(byProducingResumeData:) and awaits the callback so resume data is captured synchronously before returning; resume() uses downloadTask(withResumeData:) when available, otherwise restarts from byte 0
• DownloadSessionDelegate refactored from continuation-holding to callback-based routing (DownloadTaskCallbacks); temp-file move now happens synchronously inside the delegate method before URLSession reclaims the file
• StorageTransferTask.pause() / resume() docs updated to describe download behaviour alongside TUS uploads

Design notes

Why pause() is async: cancel(byProducingResumeData:) delivers resume data via a callback. Making pause() async lets us await withCheckedContinuation so the data is stored on the actor before the method returns — no extra Task {} or intermediate state needed.

Temp-file safety: URLSession deletes the temp file passed to didFinishDownloadingTo when that delegate method returns. The old design moved the file inside a continuation yield (safe). The new callback design moves it synchronously inside the delegate method before invoking onFinished(Result<URL, StorageError>), so the engine only ever sees the already-moved URL.

didCompleteWithError filtering: A URLError.cancelled arriving while state is .paused or .starting is intentional (from cancel(byProducingResumeData:) or a stale cancel after resume()) and is silently dropped. Only .downloading state treats an unexpected .cancelled as a real failure.

Test plan

• DownloadEngineTests.downloadCompletesSuccessfully — basic happy path
• DownloadEngineTests.pauseAndResumeCompletesDownload — pause a hanging download, resume, verify completion
• DownloadEngineTests.cancelYieldsCancelledError — cancel mid-download, verify .failed(.cancelled) event
• DownloadEngineTests.cancelThrowsFromValue — cancel mid-download, verify task.value throws StorageError.cancelled
• DownloadEngineTests.networkErrorYieldsFailedEvent — network error surfaces as .failed
• Existing DownloadSessionDelegateTests — delegate routing still correct after refactor
• Existing StorageDownloadTaskTests — end-to-end download API unchanged

🤖 Generated with Claude Code

[grdsdev]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}