# 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.

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

**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).
</details>