feat(api): Track 3.3 — GET /api/analysis-runs/{run_id}/source-audio

[slittycode]

Third of four pieces from Track 3 of the merged external-repo review. Adds a stable, round-trip-saving route for re-serving the original ingested audio for a run.

Why a new route when the bytes are already reachable?

The same bytes are reachable today via GET /api/analysis-runs/{run_id}/artifacts/{artifact_id} — source audio is stored as an artifact with kind="source_audio". So this is an ergonomic shortcut, not a net-new capability. The win is:

• Stable URL. /source-audio doesn't change per run; the artifact id does.
• One fewer round-trip. Callers (Phase 2 reruns, external consumers) don't need to fetch the snapshot first just to learn the artifact id.
• Predictable for tooling. A user can write /api/analysis-runs/{id}/source-audio directly into a Max patch, a REAPER script, or a CLI fetch — no inspection step needed.

Identical bytes, identical Content-Disposition and MIME on the wire.

Auth model

• Owner-only. Standard read pattern: _resolve_route_user_context + runtime.get_run(owner_user_id=…).
• Does NOT honor X-Admin-Key. Re-serving another user's audio has a stronger privacy posture than the cross-user delete admin bypass added in Track 3.2. Reading user content cross-tenant is more sensitive than reversibly purging it.
• Non-owner requests return RUN_NOT_FOUND (does not disclose whether the run exists), matching the existing pattern.

Error envelope

Condition	Status	Code
Success	200 audio/<original-mime>	—
Run missing or not owned	404	RUN_NOT_FOUND
Run row exists but source_artifact_id is null/dangling (defensive)	404	SOURCE_AUDIO_NOT_FOUND
Artifact row intact but file gone from disk	404	SOURCE_AUDIO_FILE_MISSING

The two "source missing" variants are distinct because the recovery paths differ — SOURCE_AUDIO_NOT_FOUND indicates server-side corruption an operator should investigate; SOURCE_AUDIO_FILE_MISSING means the metadata is intact and re-ingestion is the fix.

Files

File	Change
apps/backend/server.py	New get_run_source_audio route handler, placed next to the existing get_run_artifact handler. ~85 lines.
apps/backend/tests/test_server.py	5 new tests in GetRunSourceAudioRouteTests: happy path with Content-Disposition + MIME; non-owner → RUN_NOT_FOUND; unknown run → RUN_NOT_FOUND; missing source artifact → SOURCE_AUDIO_NOT_FOUND; missing file on disk → SOURCE_AUDIO_FILE_MISSING.
apps/backend/ARCHITECTURE.md	Route documented in the canonical list.

Verification

Route tests use the existing AnalysisRuntime + patch.object(server, "get_analysis_runtime", …) pattern. CI will exercise them. No pure-logic module to unit-test separately — the route is a thin shell over existing runtime helpers (get_source_artifact, resolve_artifact_local_path).

What this PR does NOT do

• No range-request / partial-content support. FileResponse serves the whole file; ASA's 100 MiB cap keeps that bounded. Range support could be added later if a UI playback feature needs it.
• No frontend changes. Phase 2 reruns are the intended consumer; the UI wiring is a separate follow-up.
• No admin-key bypass. Conservative read posture; see auth model above.

Track 3 sequencing

• ✅ Piece 1: URL ingestion (feat(api): Track 3.1 — URL-mode ingestion for POST /api/analysis-runs #36, merged)
• ✅ Piece 2: X-Admin-Key on DELETE (feat(api): Track 3.2 — X-Admin-Key gates cross-user DELETE on /api/analysis-runs #37, merged)
• ▶ Piece 3: this PR — GET …/source-audio re-serve
• ◯ Piece 4: Public state-machine collapse 8 → 5 at response boundary

https://claude.ai/code/session_01Uh2eNT1oqjixcox8UX3BTg

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Adds GET /api/analysis-runs/{run_id}/source-audio as an ergonomic stable-URL shortcut over the existing GET .../artifacts/{artifact_id} route. The route is a thin shell over get_source_artifact + resolve_artifact_local_path, follows the existing ownership-check pattern exactly, and comes with 5 tests covering all documented error branches. No Phase 1 data touched, no schema changes, no DSP.

The venv wasn't bootstrapped in this environment so I reviewed the tests statically; CI will catch execution failures.

Findings

Should fix:

SOURCE_AUDIO_NOT_FOUND and SOURCE_AUDIO_FILE_MISSING error bodies omit requestId, retryable, and diagnostics. CLAUDE.md states these are always required in error envelopes. The existing _run_not_found_response, ARTIFACT_NOT_FOUND, ARTIFACT_FILE_MISSING, and AUTHENTICATION_REQUIRED responses all have the same omission — so the new code is consistent with its neighbors — but that doesn't make it compliant. If the codebase is ever brought into full contract compliance on the run-management routes, these two new codes will need the same fix.

Worth considering:

get_source_artifact re-queries analysis_runs independently from get_run() (server.py:2321). In a concurrent delete + fetch race, get_source_artifact raises KeyError("Unknown run …") which the except KeyError: at server.py:2322 catches and maps to SOURCE_AUDIO_NOT_FOUND rather than RUN_NOT_FOUND. Both are 404s so this is a misclassification, not a data hazard. Practically unreachable but worth naming if the error codes are ever surfaced to operators for triage.

test_unknown_run_returns_404 doesn't patch SONIC_ANALYZER_RUNTIME_PROFILE to hosted the way the other four tests in GetRunSourceAudioRouteTests do. Functionally correct (local profile assigns user_id="local-dev" and the run genuinely doesn't exist), just inconsistent with the rest of the class setup.

Test results

5 new tests in GetRunSourceAudioRouteTests. Static analysis: all logic branches covered — happy path, non-owner, unknown run, missing artifact row, missing file on disk. No execution environment available; CI is the gate.

Phase boundary check

Clean. No Phase 1 fields read, mutated, or re-derived. No changes to analyze.py, any analyze_*.py module, Phase 2 prompts, or types.ts.

---

Generated by Claude Code