# Metrics 422 and Activities Limit Contract Fix

## Summary

- Preserve upstream HTTP 422 for all Clinic Data Service Metrics proxy routes and return a safe, actionable, non-retryable error contract.
- Classify VictoriaMetrics `search.maxSamplesPerQuery` failures without exposing vmstorage hosts, private IPs, internal URLs, raw response bodies, PromQL, or customer data.
- Align the public and Clinic Internal Activities `limit` maximum with ActivityHub's actual maximum of 100.
- Do not split or retry deterministic Metrics queries, increase VictoriaMetrics limits, paginate Activities automatically, or change app-delivery configuration.

## Metrics Contract

- Apply the contract to cluster Metrics canonical, TiDB Cloud public alias, legacy, and serverless-parent instant, range, and series routes.
- A structured upstream 422 caused by `cannot select more than -search.maxSamplesPerQuery=<number> samples` returns HTTP 422 with code `MAX_SAMPLES_PER_QUERY`, a sanitized actionable message, upstream status/type details, and `retryable:false`.
- Other structured 422 responses return `METRICS_UPSTREAM_UNPROCESSABLE`; malformed responses use a fixed safe message.
- Legacy routes stop returning raw upstream bodies. Existing 429, timeout, transport, 5xx, and success behavior remains unchanged.
- Logs contain only trace ID, upstream status, classified code/type, body length, and sanitization state.

## Activities Contract

- Change the maximum `limit` from 1000 to 100 in Clinic Data Service and Clinic Internal validation and OpenAPI documentation.
- Values from 20 through 100 retain existing behavior; values above 100 return `400 InvalidArgument` before ActivityHub is called.
- Preserve the default limit, cursor, partial response, filters, and handling of unrelated ActivityHub 400 responses.
- Use context-aware logging in Clinic Internal so the propagated trace ID is included with safe ActivityHub status and request identifiers.

## Tests and Verification

- Cover Metrics max-samples, generic structured 422, malformed 422, sanitization, handler status/body contracts, and unchanged non-422 behavior for cluster and serverless-parent routes.
- Cover Activities limit 100 success, values above 100 rejected without an upstream call, unchanged defaults/cursor/filters, and trace-aware safe logging.
- Regenerate and validate Swagger/OpenAPI, run focused tests from both Go module roots, and run `git diff --check`.
- In staging, replay the historical Metrics request and Activities limit boundary requests, verify safe responses and trace-correlated logs, then repeat in prod-cloud only after explicit release authorization.

## Deployment Impact and Boundaries

- Affected images: `clinic/data-service` from `clinic_data_service/cmd/api`, and `internal_api` from `cmd/internal_server`.
- Required Clinic CD components: `clinic-data-service` and `internal-api`.
- Required app-delivery applications/workloads: `clinic-data-service` / `Deployment/clinic-data-service`, and `clinic-api` / `Deployment/clinic-internal-api`, first staging and then prod-cloud.
- `clinic`, `task-manager`, Kong, NGM, and cloud-server do not require deployment.
- No app-delivery configuration change, automatic PR merge, or production release is included.