# Deliberation: challenge — Gemini 3 Pro (Preview)

**Date**: 2026-03-18 12:13
**Model**: Gemini 3 Pro (Preview)
**Type**: challenge
**Artifact**: ## Draft: Cloud Download for DAW Export  ### Problem MixBoard can browse, stream, and add music to p

---

No hallucinations detected.

Here is the critique of the **Cloud Download for DAW Export** proposal.

### 1. Challenge the "On-Demand" Export Assumption

**The Proposal:** `MixExporter.copyAudioFiles()` downloads cloud tracks *during* the export process.

**The Counter-Argument (Devil's Advocate):** This couples an inherently synchronous, file-system-bound operation (Export) with an inherently unstable, network-bound operation (Download).

*   **Risk:** What happens when a user exports a 50-track playlist where 25 are cloud tracks? The export, which usually takes seconds, now hangs for minutes or fails entirely if the network drops on track 14.
*   **Alternative Framing:** Keep Export purely local. Do not allow the Exporter to trigger downloads.
    *   **Better UX:** The Exporter should perform a "Preflight Check." If cloud tracks exist, the UI should block the export button and show a "Download All Required Files" button instead.
    *   **Separation of Concerns:** The Exporter shouldn't know about `URLSession` or networking delegates. It should only know about file paths. This makes unit testing the Exporter infinitely easier (no mocking network calls).

### 2. Challenge the `track.filePath` Mutation Strategy

**The Proposal:** "After download, set `track.filePath` to local path."

**The Counter-Argument:**
*   **The "Split Brain" Problem:** Is the track now a "Local Track" or still a "Cloud Track"? If you set `track.filePath`, you are effectively converting the entity.
*   **Sync Issues:** If the user deletes the local file to save space, does the app crash when it tries to play `track.filePath`? Or does it gracefully fall back to `cloudStreamPath`?
*   **Proposal:** Do not mutate `filePath`. Keep `cloudStreamPath` as the primary identity. Add a strictly non-persisted or cache-managed helper: `MixCacheManager.localPath(for: track)`. The Exporter queries the Cache Manager, not the Track model directly.

### 3. File Naming is More Dangerous Than You Think

**The Proposal:** `file naming: {artist} - {title}.{ext}`

**The Counter-Argument:**
*   **Filesystem Constraints:** "AC/DC", "N.W.A.", or tracks with slashes, colons, or emojis in their metadata will cause file creation failures on macOS.
*   **Collision Hell:** Two tracks named "Intro" by the same artist (on different albums) or even just "Untitled" will overwrite each other, causing data loss or incorrect audio in the export.
*   **Requirement:** Any download logic **must** include rigorous sanitization (stripping illegal chars) *and* a collision strategy (e.g., append `_1`, `_2` or include a unique ID in the filename: `{id}_{artist}_{title}.{ext}`).

### 4. The "Simplest Thing That Could Work" Failure Mode

**The Proposal:** Uses `URLSession` and saves to `~/Library/...`.

**The Counter-Argument:**
*   **Orphaned Files:** What is the garbage collection strategy? If a user exports 5GB of WAV files for a specific project, those files sit in `~/Library` forever, eating disk space hidden from the user.
*   **Alternative:** Since this is for *Export*, download the files directly into a temporary staging folder *inside* the destination DAW project folder (or a system temp folder that the OS cleans up automatically), rather than a permanent internal library path.

### 5. Architectural Correctness [CHECK THIS]

**Critique on Context:** You mention `ChadMusicAPIClient.streamURL` returns a raw file URL.
**Assumption Check:** Are you absolutely certain the server headers (Content-Disposition, Content-Type) are correct for a raw download?
*   **Risk:** If Nginx serves these with `Transfer-Encoding: chunked` or without a known content length, your progress bar in the UI will stay at 0% or spin indefinitely because `countOfBytesExpectedToReceive` will be unknown.
*   **Risk:** If the URL relies on specific cookies rather than just the Bearer token (common in some streamed setups), a distinct `URLSession` download task might fail where `AVPlayer` succeeds.

---

<details>
<summary>Session State</summary>

**Blocking findings**:
- **Design Flaw**: Coupling Network IO (Download) directly inside the Export Loop (`MixExporter`). This creates poor UX (hanging exports) and complicates testing.
- **Data Integrity**: File naming strategy lacks sanitization and collision handling.
- **Resource Management**: No strategy for cleaning up downloaded "export-only" files (disk leak).

**Advisory findings**:
- Separation of Concerns: Move the "Check for required downloads" logic *before* the export starts (Preflight check).
- Model Integrity: Avoid mutating the persistence layer (`track.filePath`) for transient export files. Use a Cache Manager lookup instead.

**Decisions**:
- **None made yet**. Architect strongly recommends refactoring to a "Pre-export Download" step rather than "On-demand Download."

**Open Questions**:
- Does the Nginx server provide `Content-Length` headers for the stream URLs? (Required for progress bars).
- Is persistent offline playback a goal, or is this *only* for DAW export? (Determines cache strategy).

**Key Entities**:
- `MixExporter.copyAudioFiles()` (needs refactoring)
- `DownloadService` (new)
- `ChadMusicAPIClient`
- `Track` (SwiftData)
</details>