# Deliberation: scope — GPT-5.3-Codex

**Date**: 2026-03-18 12:12
**Model**: GPT-5.3-Codex
**Type**: scope
**Artifact**: ## Draft: Cloud Download for DAW Export  ### Problem MixBoard can browse, stream, and add music to p

---

## Ruthless Scope Review

### Bottom line
This is **over-scoped for v1**.  
You are mixing three products into one: export reliability, local library behavior, and user-managed downloads.

Ship the smallest useful thing: **cloud tracks export successfully**.

## Cut to the 80% slice (v1)

1. **Only implement export-time download** in exporter path.
2. Download to a **temporary/export-staging folder** (or deterministic cache), then include in DAW export.
3. **Do not** add context-menu manual download in v1.
4. **Do not** add configurable download folders in v1.
5. **Do not** mutate core track semantics (`isCloud` stays as-is).
6. **Do not** add SwiftData schema fields in v1 unless absolutely required.

This gives user value immediately: exported sessions no longer drop cloud tracks.

## What is too small / risky if cut too far

If you only “try download and skip on failure,” you recreate silent failure.  
Minimum acceptable behavior:

- Export preflight lists cloud tracks and required download size if known.
- Hard fail (or explicit partial-export confirmation), never silent skip.
- Per-track error surfaced in export report.

## Hidden dependencies likely to blow estimate

- **Model semantics:** setting `track.isCloud = false` after download is a data integrity trap.
- **Filename correctness:** `{artist} - {title}.{ext}` can fail due invalid characters, missing/incorrect extension, duplicates.
- **Auth lifecycle:** bearer token expiration mid-export; retries/refresh path needed.
- **Disk space:** no preflight means export can fail late.
- **Concurrency/perf:** many cloud tracks downloaded serially can make export look hung; parallelism must be bounded.
- **State persistence:** if app closes during export, what cleanup/recovery behavior is required?
- **Future backend auth enforcement:** file server currently open; client should still send auth headers now to avoid future break.

## Recommended v1 / v2 boundary

### v1 (ship)
- Export pipeline downloads missing cloud files just-in-time.
- Bounded concurrent downloads (e.g., 2–3).
- Deterministic temp/cache path keyed by track ID + source URL hash.
- Clear progress + explicit errors; no silent skip.
- Cleanup temp files post-export (or short TTL cache).

### v2
- Manual “Download” in CloudBrowser UI.
- Configurable download folder.
- Bulk download.
- Cache management UI/limits.
- Local library integration decisions (SwiftData object creation, offline mode).

## Cheaper alternative not mentioned

Before creating a standalone `DownloadService`, implement a **narrow exporter-scoped downloader helper**.  
Reason: lower API surface, fewer architectural commitments, faster to ship. Extract to shared service only after second use-case (manual download) is approved.

---

## Hallucination detection

The following claims are not independently confirmable from provided context:

- `MixExporter.copyAudioFiles()` **[UNVERIFIED]**
- `CloudBrowserView` context menu location/details **[UNVERIFIED]**
- `ChadMusicAPIClient.streamURL(for: track.url)` exact signature **[UNVERIFIED]**
- `ChadMusicAPIClient.authHeaders` exact property name **[UNVERIFIED]**
- `track.hasLocalFile` guard exact implementation **[UNVERIFIED]**
- `UploadService` pattern parity details beyond file existence **[UNVERIFIED]**

Potentially risky factual assumption:

- “No new backend endpoints are needed” for all download use-cases **[CHECK THIS]** (true for raw GET, but may be false once auth/authorization/audit rules are enforced).

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

**Blocking findings**:  
- Ambiguous requirements: silent skip behavior vs hard-fail/partial-export policy not defined.  
- Untestable acceptance criteria: no explicit success/error criteria for export with cloud tracks.  
- Scope violation for “Small” appetite: includes UI feature + model changes + export flow in one slice.

**Advisory findings**:  
- Remove `isCloud` mutation; keep source-of-truth semantics stable.  
- Defer manual download/configurable folder/bulk/cache UI to v2.  
- Add filename sanitization, collision strategy, disk-space preflight, token-expiry handling.  
- Prefer exporter-local helper before introducing cross-app `DownloadService`.

**Decisions**:  
- Recommend v1 = export-time download only, explicit error handling, no silent skip.  
- Recommend v2 for manual and library-facing download workflows.

**Open Questions**:  
- Should export fail-fast or allow user-approved partial export?  
- Is persistent cache required, or temp-only acceptable for first release?  
- What is the retry/token-refresh policy during long exports?

**Key Entities**:  
- MixBoard, Chad Music, UploadService.swift, `MixExporter.copyAudioFiles()` [UNVERIFIED], CloudBrowserView [UNVERIFIED], `ChadMusicAPIClient.streamURL(...)` [UNVERIFIED], `ChadMusicAPIClient.authHeaders` [UNVERIFIED], `track.hasLocalFile` [UNVERIFIED], `isCloud`, `filePath`.

</details>