test: cross-boundary Phase 1 contract gate — kill the silent-field-drop bug class

[slittycode]

Why

The Phase 1 contract lives in three hand-maintained reconstructions — analyze.py output, _build_phase1 in server_phase1.py, and parsePhase1Result in backendPhase1Client.ts — plus two declarative mirrors (JSON_SCHEMA.md, types/measurement.ts), and nothing executable defended the boundary. The 2026-05-30 full review named this the structural root cause of the dropped reverbDetail.perBandRt60/preDelayMs and vocalDetail.stemEnergyRatio/stemOtherCorrelation citation fields ("no generated source of truth and no cross-app test"); CLAUDE.md tripwires #3/#4 exist because this keeps biting. This PR makes the bug class fail loudly in CI instead of relying on the tripwire being remembered.

What

Backend — golden snapshot becomes the generated cross-app source of truth (apps/backend/tests/test_phase1_golden.py):

• build_golden now records a recursive, structure-only keyTree: dicts recurse, lists of objects record the union of element keys, scalars reduce to type categories. Comparison tolerates the known runner-noise axes (nested null↔scalar flips, empty↔populated lists) and bites on every container-shape change (key added/removed, dict↔scalar, objects↔scalars). KEYTREE_PRUNE_PATHS (seeded empty) is the documented one-line loosening path if a flaky subtree ever surfaces.
• New test_phase1_keytree_matches_golden gate; goldens predating keyTree skip visibly until the next UPDATE_PHASE1_GOLDEN=1 re-baseline arms it. The golden here is regenerated, so the gate ships armed (+426 purely additive lines).
• New BuildPhase1KeySupersetTests: pins that _build_phase1 forwards every golden top-level key — the third reconstruction layer, previously unguarded (a key missed there never reaches the frontend at all).
• 14 KeyTreeMetaTests prove the comparator bites and doesn't over-bite.

Frontend — the parity gate (apps/ui):

• tests/fixtures/phase1FullPayload.ts: the inline validPayload promoted to a shared, envelope-shaped fixture, enriched to cover all 66 golden top-level keys (9 were missing: phase1Version, lufsCurve, spectralBalanceTimeSeries, saturationDetail, snareDetail, hihatDetail, transientDensityDetail, pitchDetail, stemAnalysis) with realistic nested values.
• tests/services/phase1ContractParity.test.ts — five gates driven by the committed backend golden:
  • A1: every golden top-level key exists (non-null) in the fixture.
  • A2 (reverse): every fixture key is a golden key or a declared envelope addition — catches fixture rot when the backend deletes a field.
  • A3: every nested keyTree path exists in the fixture. Auto-arms off the golden; active in this PR.
  • B: the fixture survives the real parsePhase1Result with every non-null input path intact — the silent-drop check itself.
  • C: the canonical run path strips exactly transcriptionDetail and nothing else.
  • Server-side transforms (stereo hoist, spectral *Mean renames, staged-path strip) are a small declared map with server_phase1.py/analysis_runtime.py citations — an undeclared future transform fails the gate rather than passing silently.

Two real catches before merge (the gate proving itself):

1. parsePhase1Result silently dropped phase1Version — emitted by the server, declared in the type, never forwarded. Fixed (one line).
2. Arming Gate A3 surfaced stale segmentLoudness/segmentSpectral fixture shapes ({start, value} vs the real {segmentIndex, start, end, lufs, lra} contract) — corrected.

Docs: tripwires #3/#4, JSON_SCHEMA.md, and apps/ui/AGENTS.md now point at the executable gates.

Verification

• apps/ui: npm run verify green — lint, 756 unit tests (all six new gates active, zero skips), build, 49 smoke tests.
• apps/backend (fresh py3.11 venv): tests.test_phase1_golden 27 tests OK with the keytree gate active; tests.test_analyze + tests.test_server 374 tests OK.
• Mutation checks observed red→green: parser-side drop (reverbDetail.preDelayMs forwarding removed → Gate B names exactly that path), fixture-side gap (vocalDetail removed → Gates A1+A2 name it), and the live phase1Version drop (Gate B red on first run, green after the fix).

https://claude.ai/code/session_014eU638tNAHuV3bXDZStuNU

---

Generated by Claude Code