mixboard/.orchestra/deliberations/2026-03-18-202442-Gemini-3-Pro--Preview--general.md

Deliberation: general — Gemini 3 Pro (Preview)

Date: 2026-03-18 20:24 Model: Gemini 3 Pro (Preview) Type: general Artifact: ## Offline Download — Draft Proposal ### Problem Cloud tracks can only be streamed. No way to make

---

Here is a critique of the draft proposal for the Offline Download feature.

Analysis & Critique

1. Correctness and Support

The core identification of risks is solid, particularly the conflict between OS-level cache purging and database state (Risk #2). However, the proposal misses a critical architectural flaw regarding the storage location assumption.

• Storage Location Mismatch: You identified ~/Library/Caches/ as the download location. This directly contradicts the requirement for "persistent downloads" (implied by "Offline Download" vs. "Cache"). If a user explicitly clicks "Download," they expect that file to remain until they delete it. Caches/ is for disposable data the OS can reap when disk space is low.
  • Correction: Explicit user downloads should go in ~/Library/Application Support/MixBoard/Downloads/ or ~/Music/MixBoard/Offline/, excluded from iCloud backup if necessary, but provenly persistent.

2. Errors, Gaps, and Unsupported Conclusions

• Routing Logic fragility (Risk #1): The risk is correctly identified but the analysis stops short.

  • Current: hasLocalFile = !filePath.isEmpty && !isCloud
  • Proposed: If you download a cloud track, does isCloud become false? If so, you break syncing logic. If not, how do existing consumers know to look at filePath?
  • Gap: You need a new computed property: isOfflineAvailable. The routing logic must change from if isCloud to if isCloud && !isOfflineAvailable.

• Format Compatibility (Risk #5): You mention OGG Vorbis support via stb_vorbis but question if it's in AudioEngine.

  • Gap: If StreamingPlayer uses AVPlayer (which supports HLS/HTTP streaming natively but not raw OGG usually) and AudioEngine is AVAudioEngine, switching engines based on download state is dangerous. AVAudioFile (standard input for AVAudioEngine) does not natively support OGG Vorbis without third-party codecs or custom buffers.
  • Critical Check: Does the backend transcode? If the server sends an .ogg stream, downloading it as a file and feeding it to AVAudioEngine will crash or fail silently unless your custom decoder is hooked into the file reading pipeline.

3. Additions and Challenges

• Concurrency & Queue Management: You mentioned "Concurrent downloads across multiple albums" (Risk #4) but didn't propose a mechanism.

  • Challenge: Do not permit unbounded concurrency. You need a OperationQueue or TaskGroup with a maxConcurrentOperationCount (e.g., 2 or 3). Dumping 500 tasks into URLSession simultaneously is bad practice.

• Partial State Handling: What happens if the app crashes halfway through a download?

  • Add: You need .downloading state in the model or a separate DownloadJob table. SwiftData must not record a valid filePath until the file is fully moved to its final destination and validated.

• Permissions: Since this is macOS, does the app have App Sandbox enabled? If so, writing to arbitrary locations requires entitlements, though standard Application Support/Caches are usually fine.

4. Recommendation Viability

The recommendation to extend DownloadService is logical, but the specific implementation detail of using ~/Library/Caches is fatal to the "Offline" consumer promise. It must be Application Support.

The transition from StreamingPlayer (AVPlayer) to AudioEngine (AVAudioEngine) for downloaded files is high risk for OGG/FLAC edge cases.

Hallucination Detection

• stb_vorbis: [UNVERIFIED] - This is a real C library for OGG decoding. However, claiming MixBoard uses it is unverified based on the provided text alone, though User Context implies it exists.
• ~/Library/Caches/MixBoard/CloudTracks/: [VERIFIED PLACEMENT] - This is a standard macOS path structure, not a hallucination, but mechanically incorrect for persistent downloads.
• Chad Music: [UNVERIFIED] - Likely internal project name or typo for valid service.
• Track @Model: [VERIFIED] - Confirmed in User Context.

Status: No hallucinations detected in external libraries; potential confusion on internal implementation details vs. standard macOS behaviors.

Session State

**Blocking findings**: * **Irreversibility/Safety**: Using `~/Library/Caches/` for explicit user downloads is incorrect; the OS will delete them, leading to "File Not Found" errors and user data loss. Use `Application Support`. * **Ambiguous Requirements**: Handling of partial downloads and app restarts is undefined. * **Performance/Stability**: Playback engine switching (Stream -> AudioEngine) for formats like OGG is unproven and potentially crash-prone if `AVAudioFile` is used blindly. **Advisory findings**: * Implement a download queue limiter (max 3 concurrent). * Add a specific `DownloadStatus` enum (idle, downloading, downloaded, failed) to the Track model rather than inferring from path existence. * Verify AudioEngine support for raw file playback of all server-supported formats. **Decisions**: * Reject use of `Caches` directory for offline mode. * Require architecture check for OGG file playback in `AudioEngine`. **Open Questions**: * Does the backend server provide different formats for streaming vs. download? * Does `AudioEngine` wrap `stb_vorbis` for file-reading, or is it strictly `AVAudioFile` based? **Key Entities**: `DownloadService`, `Track.filePath`, `Application Support/`, `AVAudioEngine`, `stb_vorbis`, `isOfflineAvailable` (proposed).