feat(export): Track 2 — CSV export of Phase 1 time-series fields + schema ADR v1

[slittycode]

Implements Track 2 from the merged external-repo review (docs/external-repo-review-2026-05-13.md). This is the first net-new user-facing feature delivered from that planning work.

What this adds

A new HTTP endpoint that lets external tooling (REAPER scripts, Max patches, downstream pipelines) pull individual ASA time-series measurements as CSV without parsing the full JSON envelope:

GET /api/analysis-runs/{run_id}/export/csv/{field_path}

{field_path} is a simple dot-path (e.g. lufsCurve.shortTerm) — not JSONPath. Arbitrary nested-key descent isn't supported; only allowlisted fields are exportable. Adding a new exportable field is a deliberate code change in apps/backend/csv_export.py.

v1 exportable fields

Path	CSV columns
lufsCurve.shortTerm	time, duration, lufs (duration=3.0 — EBU R128 short-term window)
lufsCurve.momentary	time, duration, lufs (duration=0.4 — momentary window)
rhythmDetail.tempoCurve	time, bpm
spectralBalanceTimeSeries	time, subBass, lowBass, lowMids, mids, upperMids, highs, brilliance

Why this shape (and not Partiels' shape verbatim)

The review rejected mirroring Partiels' flat (time, duration, label/value) schema directly — that would collapse ASA's domain-named measurements into per-track Vamp-style tracks, breaking the citation chain (PURPOSE.md Quality Invariant #2). What this PR adopts instead: the tabular pattern, with ASA's domain field names preserved. The CSV columns come straight from the v1 JSON schema. Same data, lower-friction consumption.

What this PR contains

File	Role
apps/backend/csv_export.py (new, ~200 lines)	Allowlisted registry + per-field serializers + dot-path resolver. Pure stdlib; no external deps.
apps/backend/server.py (+88 lines)	New route handler. Same auth + 404 patterns as the existing artifact routes. Three distinct 404 codes (RUN_NOT_FOUND, EXPORT_FIELD_NOT_SUPPORTED, EXPORT_FIELD_NOT_AVAILABLE).
apps/backend/tests/test_csv_export.py (new, 22 tests)	Per-field unit tests covering column order, edge cases, empty arrays, missing keys, partial rows. All pass locally.
apps/backend/tests/test_server.py (+133 lines, 4 tests)	Route tests: success path with Content-Disposition; each 404 code; runs through real AnalysisRuntime + complete_measurement.
docs/adr/0001-phase1-json-schema-v1.md (new)	Ratifies the current Phase 1 shape as v1 with an additive-only compatibility policy. Pins the four exportable time-series field shapes.
apps/backend/ARCHITECTURE.md	Route list updated — also adds previously-undocumented routes (/artifacts, /spectral-enhancements, /pitch-note-translations, /interpretations).

Error model

Condition	Status	Code
Successful export	200 text/csv; charset=utf-8	—
Run doesn't exist or not owned by caller	404	RUN_NOT_FOUND
Field path not in registry	404	EXPORT_FIELD_NOT_SUPPORTED (message lists all supported paths)
Field is null/missing/empty for this run	404	EXPORT_FIELD_NOT_AVAILABLE

The "not supported" vs "not available" split lets clients distinguish "I asked for the wrong thing" from "this run doesn't have that data populated."

ADR 0001 — Phase 1 JSON Schema v1

Separately landed in this PR because the CSV endpoint's column contract depends on the schema being explicitly versioned. Key decisions:

• The schema is v1 as of today. Defined by the union of EXPECTED_TOP_LEVEL_KEYS, JSON_SCHEMA.md, and Phase1Result. No separate machine-readable schema artifact — deferred to v2 if an external consumer ever needs one.
• Additive changes are minor; renames/removals/retypes are breaking (major). Compatibility classification table in the ADR.
• No HTTP version header. When v2 lands (if ever), the canonical move is a new top-level phase1Version field rather than Accept header negotiation.

Verification

• 22 csv_export unit tests pass locally (Python stdlib only — no Essentia/FastAPI needed):

  $ python -m unittest tests.test_csv_export -v
  ...
  Ran 22 tests in 0.002s
  OK
  

• 4 route tests in CsvExportRouteTests run via the existing AnalysisRuntime + patch.object(server, "get_analysis_runtime", ...) pattern that the rest of test_server.py uses. CI will run them.

What this PR does NOT do

• No frontend UI for export. This is a backend-only addition. Adding a "Download CSV" button in the results view would be a follow-up.
• No SDIF, LAB, REAPER export. Deferred per the review.
• No beat/downbeat tabular export. The existing rhythmDetail.beatGrid / downbeats / beatPositions are sample indices, not seconds — converting requires threading the analyzer's sample rate, which is a separate decision.
• No CLI export tool. The HTTP endpoint is the v1 entry point.

https://claude.ai/code/session_01Uh2eNT1oqjixcox8UX3BTg

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Clean backend addition: a new allowlisted CSV export endpoint for Phase 1 time-series fields, plus an ADR that formally ratifies the existing schema as v1. All 22 unit tests pass locally. CI was still running at review time. No phase boundary violations, no breaking schema changes.

Findings

Worth considering (non-blocking)

1. NaN passthrough in serializers (csv_export.py:160–163, 182, 212). float(value) on a numeric field doesn't guard against NaN or Infinity. If the Phase 1 analyzer ever emits a NaN (possible from FFT edge cases on pathological input — silent audio with a DC offset, for instance), it will write the string nan to the CSV. Verified locally:

   'time,duration,lufs\n0.000000,3.0,nan\n'
   

   Most REAPER and Max CSV parsers will treat nan as a string, not a float, and silently misread the column. This is not blocking because (a) JSON doesn't have a NaN literal so the analyzer would need to deliberately emit null or skip the field — both of which are already handled — and (b) the current Phase 1 fields are normalized before emission. But it's the kind of thing that bites you once on a silent 0.0-amplitude stem.

2. test_empty_array_returns_none only exercises lufsCurve.shortTerm (test_csv_export.py:98–101). The same empty-list path through _serialize_spectral_balance_time_series and _serialize_tempo_curve is untested. Both return None correctly (verified), but the test suite doesn't assert it. Trivial to add; worth it because the empty-time-series case is the most common "measurement ran but produced nothing useful" scenario.

Test results

22 / 22 pass (tests.test_csv_export). CI (Backend + Frontend jobs) was in-progress at review time — no failures reported yet.

Phase boundary check

Clean. The route handler is read-only: it pulls snapshot["stages"]["measurement"]["result"] and serializes it. Nothing in csv_export.py or the new route modifies, re-derives, or overrides any Phase 1 value. _resolve_dot_path is a pure descent with no side effects.

ADR note

ADR 0001 correctly pins the v1 schema as the union of EXPECTED_TOP_LEVEL_KEYS, JSON_SCHEMA.md, and Phase1Result. The "no separate JSON Schema artifact" decision is sound — a drifting .schema.json would be a new failure mode with no current consumer to justify it.

---

Generated by Claude Code