Wire calibration controls into create/update/read endpoints (inline JSON + controls_file CSV) #753

Summary

Extend the calibration create, update, and read router endpoints to accept and return calibration controls — both as inline JSON in the request body and as an optional controls_file CSV upload.

Background

With the DB schema, view models, and validation in place, this issue wires everything together at the API layer. Controls should be manageable both inline (as part of the JSON payload) and via CSV upload, consistent with the existing classes_file pattern for class-based calibrations.

Proposed Behavior

Create (POST /api/v1/score-calibrations)

• Accept optional controls array in the ScoreCalibrationCreate JSON payload
• Accept optional controls_file (UploadFile, CSV) alongside calibration_json
• CSV format: two columns — variant (MaveDB URN or HGVS) and clinical_status (pathogenic | benign, case-insensitive)
• If both JSON controls and controls_file are provided, return 422
• Run scope validation before persisting

Update (PATCH /api/v1/score-calibrations/{urn})

• Same as create: accept controls array and/or controls_file
• Replace semantics: submitted controls list replaces all existing controls for that calibration (consistent with how functional_classifications are handled)

Read (GET /api/v1/score-calibrations/{urn})

• Return controls list in the response (subject to existing private flag)
• Return disease and controls_not_phi fields

CSV format for controls_file

• Columns: variant (URN or HGVS nt/pro), clinical_status
• Validation follows the same pattern as validate_and_standardize_calibration_classes_dataframe in lib/validation/dataframe/calibration.py

Acceptance Criteria

• POST and PATCH endpoints accept controls in JSON payload
• POST and PATCH endpoints accept controls_file CSV upload
• Providing both JSON controls and controls_file in the same request returns 422
• GET returns controls, disease, and controls_not_phi for authorized users
• Controls are not visible in GET responses when the calibration is private and the requesting user lacks read access
• CSV parsing validates columns, status values, and variant existence
• Replace semantics: updating with a new controls list replaces the old one atomically
• Empty controls array clears all existing controls on update

Implementation Notes

• Follow the classes_file pattern in routers/score_calibrations.py for multipart upload handling
• controls_file should be optional: omitting it on update means "no change to existing controls"; sending an empty JSON controls: [] means "clear all controls"
• Add controls_file to the OpenAPI schema override dict alongside classes_file in the existing endpoint schemas
• Wrap control persistence in a transaction so a validation failure mid-way leaves no partial state

Additional Considerations

List endpoint performance

The full controls list should be omitted from collection/list responses (e.g., GET /score-calibrations/me). Only the detail endpoint (GET /score-calibrations/{urn}) should include the full controls list. Consider returning a controlsCount: int in list responses to avoid large payloads.

Authorization

Controls must respect the calibration's existing permission model: write access is required to create or modify controls; read access is required to retrieve them. Apply the existing assert_permission / has_permission guards to control mutations the same way they are applied to calibration mutations. No new permission types are needed.

controls_not_phi reset on controls change

See the PHI gate issue (#752): when controls are replaced via an update, reset controls_not_phi to null so the submitter must re-acknowledge before republishing.