# Deliberation: scope — GPT-5.3-Codex

**Date**: 2026-03-18 12:02
**Model**: GPT-5.3-Codex
**Type**: scope
**Artifact**: ## Cloud Download Brief (Draft)  ### Problem Cloud tracks in MixBoard playlists cannot be exported t

---

## Scope/Appetite Review

### Verdict
Current brief is **slightly too big in the wrong places** and **too vague in one critical place**.

### Cut to the smallest useful ship
Ship **export-time staging only**:

- On export, for each cloud track without local file:
  - Resolve download URL
  - Download into a temp export staging folder
  - Use staged path for exporter input
- Do **not** mutate `Track` model in v1
- Do **not** add persistent cache semantics in v1
- Do **not** add standalone “Download” UI in v1

This delivers ~80% value (cloud tracks export) with less data-model risk.

---

### What to cut now
1. **Cut Track model mutation (`filePath`, `hasLocalFile`)**
   - This introduces semantic confusion (`isCloud=true` but local path exists), likely follow-up bugs in library views/filtering/sync logic.
2. **Cut persistent cache design**
   - Persistence, invalidation, and migration are separate product decisions.
3. **Cut “future-proof auth headers” unless required now**
   - `ChadMusicAPIClient.authHeaders` is **[UNVERIFIED]** in provided context.

---

### What is underspecified (blocking)
1. **Failure policy is missing** (**blocking: ambiguous requirements**)
   - If 1 of N downloads fails: fail whole export, skip failed tracks, or ask user?
   - Must define this now or estimate is unreliable.
2. **Filename/extension derivation is missing** (**blocking: untestable edge cases**)
   - Exporters often need correct extension/format.
3. **Concurrency policy is missing** (**blocking: performance/scope risk**)
   - Parallel downloads can spike memory/disk/network and complicate progress.
   - Recommend serial in v1.

---

### Hidden dependencies likely to blow estimate
- SwiftData migration if `Track` gets new persisted field (`cachedFilePath`)
- Existing logic that assumes `hasLocalFile == !isCloud`
- Disk space checks and cleanup for large playlists
- Export cancellation behavior while download in progress
- Duplicate track IDs / filename collisions in cache path
- Offline / timeout / retry behavior

---

### Simpler architecture (recommended)
- Add `ExportAssetResolver` (or small helper in exporter) that returns local URL per track:
  - local track → existing filePath
  - cloud track → download to temp staging, return staged URL
- Keep download files in export temp folder; delete on completion/failure
- Optional micro-cache later (deterministic path + existence check), but out of v1 scope

---

### Direct answers to open questions
1. Standalone download action? **No (v1).**
2. Persist cached path in SwiftData? **No (v1).**
3. Change `hasLocalFile` or add `cachedFilePath`? **Neither (v1)** if using export-time staging.

---

### Hallucination detection
- `ChadMusicAPIClient.authHeaders` — **[UNVERIFIED]** (context confirms `streamURL(for:)` only).
- “No auth on file routes” is stated in context; acceptable assumption.
- All other named components align with provided context.

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

**Blocking findings**:  
- Ambiguous failure policy for partial download/export outcomes  
- Missing testable rules for filename/format handling  
- Missing concurrency policy (serial vs parallel) creates performance/scope risk  

**Advisory findings**:  
- Scope should avoid Track model mutation in v1  
- Avoid persistent cache and standalone download UI in v1  
- Prefer export-time temp staging to reduce follow-up and migration cost  
- `ChadMusicAPIClient.authHeaders` is **[UNVERIFIED]**  

**Decisions**:  
- Recommend smallest shippable slice: export-triggered download-to-temp only  
- Keep data model unchanged for v1  

**Open Questions**:  
- Exact behavior when some cloud tracks fail to download  
- Serial-only vs limited parallel downloads in v1  
- Cleanup timing for staged files on cancel/failure  

**Key Entities**:  
- `DownloadService.swift`  
- `Track.filePath`  
- `Track.hasLocalFile`  
- `Track.isCloud`  
- `cachedFilePath`  
- `ExportSheet`  
- `MixExporter`  
- `ChadMusicAPIClient.streamURL(for:)`  
- `ChadMusicAPIClient.authHeaders` **[UNVERIFIED]**  
- `~/Library/Application Support/MixBoard/CloudCache/`  

</details>