[Feature] : API ENDPOINTS PR 4 : Samples Endpoints

[pulk17]

[FEATURE]

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.

My familiarity with the project is as follows (check one):

• I have never used the project.
• I have used the project briefly.
• I have used the project extensively, but have not contributed previously.
• I am an active contributor to the project.

---

Overview

Fourth PR of the CI API stack (#1130 → #1141, merge bottom-up). Per-run regression test results and the sample catalog — the endpoints a dashboard would poll to render a run's result table.

Endpoints

• GET /runs/{id}/samples — per-regression-test outcomes for a run, with derived status, exit codes, runtime, categories, and per-output-file status. Filters: ?status, ?name, ?tag, ?category.
• GET /runs/{id}/samples/{regression_test_id} — single result detail
• GET /samples — catalog with ?name (LIKE wildcards escaped), ?extension, ?sha256, ?tag, ?status=active|inactive filters
• GET /samples/{id} — single sample with active regression test count
• GET /samples/{id}/history — how a sample performed across runs, with ?branch/?platform/date filters
• GET /regression-tests — definitions; ?active defaults to true and rejects anything that isn't true/false with a 400 rather than silently coercing

Design notes

• failure_signature in history distinguishes real regressions from noise: diff_mismatch:output:{id} (same signature across runs ⇒ same diff failing), exit_code_mismatch:rc:{code}, or missing_output. This is the field to use when deciding whether a failure is new.
• Status derivation is shared, not re-implemented: per-sample statuses come from the same service as /runs/{id}/summary, with expected-output rows threaded through, so a sample can't show pass here while the summary counts it as missing_output.
• Query strategy: statuses are derived (not stored), so ?status filtering happens in Python after a fixed set of batched queries. That's a deliberate trade-off — runs have at most a few hundred regression tests. What's not tolerated is per-row lazy loading: all relationship access is eager-loaded (joinedload/selectinload), and a regression test pins this down by asserting the endpoint's SQL query count is identical with 1 and 9 regression tests. If someone reintroduces an N+1, that test fails.

Testing

16 new tests; 140 total at this layer. Filter matrices, invalid-filter 400s, missing-output consistency with /summary, history signatures, and the flat-query-count guard.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud