mixboard/.orchestra/deliberations/2026-03-18-121303-Gemini-3-Pro--Preview--challenge.md

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.

---

Session State

**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)