# Deliberation: general — GPT-5.3-Codex

**Date**: 2026-03-18 20:24
**Model**: GPT-5.3-Codex
**Type**: general
**Artifact**: ## Offline Download — Draft Proposal  ### Problem Cloud tracks can only be streamed. No way to make 

---

## Review

### What is solid
- Problem framing is clear and aligned with the stated gap (no offline playback for cloud tracks).
- Reuse of `DownloadService` and bounded concurrency is a good low-risk direction.
- Calling out cache purge behavior and stale `filePath` handling is necessary.

### Critical issues to fix

1. **Routing logic appears inconsistent**  
   The artifact says: “`PlayerViewModel` already routes by `hasLocalFile`.”  
   Context says routing is by `isCloud` (`isCloud -> StreamingPlayer`, `!isCloud -> AudioEngine`).  
   **[CHECK THIS]** This is a core correctness issue. If routing is still `isCloud`-based, downloaded cloud tracks will still stream unless routing is changed.

2. **“Persistent offline” vs `~/Library/Caches` is a mismatch**  
   Storing user-expected offline downloads in Caches is risky because macOS may purge it.  
   **[CHECK THIS]** If the product promise is “downloaded for offline,” Caches is the wrong default. Use Application Support (or make cache semantics explicit in UX).

3. **Model semantics are overloaded and fragile**  
   Using `isCloud=true + filePath set` as “downloaded” introduces ambiguous state and increases regression risk around `hasLocalFile`.  
   Add explicit state, e.g. `downloadState` (`none/downloading/downloaded/failed`) + `localFilePath?`.  
   This avoids boolean coupling and makes UI/test logic deterministic.

4. **Recommendation to switch downloaded cloud tracks to AudioEngine in v1 is high-risk**  
   This couples offline delivery with playback pipeline migration.  
   Keep v1 focused on offline availability; defer EQ-path migration (Phase 2/3) unless required now.

---

### Scope recommendation (minimum v1)

- **Phase 1 (v1):**
  - Track-level download only (no album/playlist bulk yet).
  - Explicit `downloadState` + `localFilePath`.
  - Playback selection: if cloud track has valid local file, play local (can still use existing player path first to reduce risk).
  - Remove download + stale file recovery.
  - Basic retry/error UI.

- **Phase 2:**
  - Album/playlist batch download orchestration.
  - Queue management, cancellation, prioritization.

- **Phase 3:**
  - Route downloaded cloud tracks through AudioEngine for EQ parity.

This sequencing reduces irreversibility and isolates regressions.

---

### Hallucination check on specific claims

- “`PlayerViewModel` already routes by `hasLocalFile`” → **[CHECK THIS]** (conflicts with provided context).
- “Persistent downloads to `~/Library/Caches/MixBoard/CloudTracks/`” → **[CHECK THIS]** (technically possible, but conflicts with persistence expectation).
- “Per designer: inline arrow.down.circle... four states...” → **[UNVERIFIED]** (cannot independently confirm design directive).
- “`{cloudTrackId}.{ext}` naming” → **[UNVERIFIED]** (extension/source format mapping not demonstrated).
- “Downloaded cloud track becomes playable via AudioEngine” → **[UNVERIFIED]** (depends on routing and decoder compatibility not evidenced).

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

**Blocking findings**: Routing logic inconsistency (**untestable until clarified**); storage location conflicts with persistence promise (**scope/requirement ambiguity**); coupling v1 with playback-engine migration (**scope/performance/regression risk**).  
**Advisory findings**: Add explicit `downloadState`; avoid deriving state from `isCloud` + `filePath`; phase album/playlist after track-level stabilizes; define stale-file and retry behavior in acceptance criteria.  
**Decisions**: Recommend phased rollout (track-only v1, batch later, AudioEngine migration later).  
**Open Questions**: Is “offline” best-effort cache or durable user-managed download? Must v1 include EQ for downloaded cloud tracks? What is authoritative routing condition in `PlayerViewModel` today?  
**Key Entities**: `DownloadService`, `Track @Model`, `hasLocalFile`, `PlayerViewModel`, `StreamingPlayer`, `AudioEngine`, `isCloud`, `cloudTrackId`, `filePath`, `~/Library/Caches/MixBoard/CloudTracks/`.
</details>