# Clinic TopSQL Measure Plan Contract

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "clinic-topsql-measure-plan-contract-2026-08-19",
  "problems": [
    {
      "problemId": "clinic-topsql-physical-measure-names-reject-evidence-plan",
      "summary": "The Evidence Agent contract exposed raw TopSQL column names while Provider Executor accepted only logical measure selectors, so a valid TCID-12989 replay stopped before every Clinic query with clinic_topsql_measures_invalid.",
      "status": "optimized_verified",
      "applicability": "Clinic diagnostic plans that request bounded TopSQL execution, duration, key, logical-IO, or network aggregates through the typed topsql operation.",
      "issueKeys": ["TCID-12989"],
      "sourceRefs": ["https://tidb.atlassian.net/browse/TCID-12989#problem:clinic-topsql-measure-plan-contract"],
      "signalTextIncludesAny": ["clinic_topsql_measures_invalid", "TopSQL physical measure name", "Evidence plan rejected before Clinic queries"],
      "observedThrough": "2026-08-19",
      "effectiveAt": "2026-08-19T00:57:14+08:00",
      "verifiedAt": "2026-08-19T01:18:00+08:00",
      "attemptedAction": "Expose only logical measure selectors to the Evidence Agent and normalize the exact historical Data Proxy column aliases at Provider Executor plan parsing before applying the existing closed-set and scan-count limits.",
      "evidenceUrl": "https://tidb.atlassian.net/browse/TCID-12989?focusedCommentId=23371042"
    }
  ]
}
-->

- Owner: Evidence Agent input contract for selector names; Clinic Provider
  Executor for deterministic historical-alias normalization
- Source: TCID-12989 deployed read replay
- Implementation status: deployed in image `00add7fc3ad53efc10d99e6fa9e687b1fae3197c`
- Effectiveness status: `optimized_verified`

## Bounded problem

The TopSQL operation introduced logical selectors such as `exec_count`,
`avg_latency_ms`, and `write_keys`, but its inline Evidence Agent contract also
listed the underlying `topsql_*` Data Proxy columns as the allowed measures.
The Evidence Agent followed that contradictory list. Provider Executor then
rejected the plan before executing any independent query, so unrelated Slow
Query and Prometheus evidence in all three scenarios was also lost.

## Candidate change

- Give the Evidence Agent only the closed logical selector list used by the
  typed operation.
- Normalize only the exact historical physical aliases at Provider Executor
  parsing. Duration sum and count both select the one logical
  `avg_latency_ms` aggregate and deduplicate before the four-measure limit.
- Keep unknown selectors, structural errors, and plans exceeding the bounded
  scan limit rejected.

## Verification evidence

Deployed run `7e023883-602b-47cd-a592-51eee84f6228` reproduced the mismatch:
the generated TCID-12989 plans used `topsql_stmt_exec_count`,
`topsql_stmt_duration_sum_ns`, `topsql_stmt_duration_count`, and
`topsql_write_keys`; Provider Executor stopped with
`clinic_topsql_measures_invalid` before provider execution.

Post-change read replay `b94a4804-f538-4712-9bf1-a7825f46960a` and write
replay `555872f3-6317-44f1-91d9-d786991d9899` generated accepted plans and
executed the independent Slow Query and Prometheus operations. Neither run
reported `clinic_topsql_measures_invalid`. The TopSQL source then reported the
real cluster capability result `clinic_datasource_not_configured`; that
provider outcome remained degraded without discarding the successful Slow
Query, store mapping, exact-store rate, or flow-control facts.

The write replay updated existing Jira internal comment `23371042`. Direct
readback confirmed the expected body and `public=false`; database run `150093`,
evaluation, and the Feishu dashboard write completed without publication
errors.

## Remaining capability boundary

The plan-contract mismatch is verified fixed. This cluster does not currently
have the TopSQL datasource configured, so TopSQL facts remain unavailable; the
runner now reports that bounded provider capability gap while preserving the
other valid evidence. Enabling that datasource is outside this optimization.