# Clinic Topology Handoff Facts

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "clinic-topology-handoff-facts-2026-08-20",
  "problems": [
    {
      "problemId": "clinic-topology-capacity-dropped-before-scenario-diagnosis",
      "summary": "Clinic components queries persisted TiKV node count, CPU, and memory capacity in the compact report but omitted those facts from the child handoff, so the Scenario Diagnostic Agent could receive per-instance RSS extrema without the node capacity needed to interpret the alert.",
      "status": "optimized_unverified",
      "applicability": "Clinic evidence-assisted resource and capacity diagnosis that combines component topology with entity-labelled metrics.",
      "issueKeys": ["ST-2865"],
      "sourceRefs": ["https://tidb.atlassian.net/browse/ST-2865#problem:clinic-topology-capacity-dropped-before-scenario-diagnosis"],
      "signalTextIncludesAny": ["per-instance values unavailable", "topology capacity missing from handoff", "generic memory checklist"],
      "observedThrough": "2026-08-20",
      "effectiveAt": "2026-08-20T08:00:05Z",
      "verifiedAt": null,
      "attemptedAction": "Materialize bounded component type, node count, CPU, and memory capacity facts from the existing Clinic compact topology result into the Provider Executor child handoff, and prove with an ST-2865-style offline fixture that those facts and RSS extrema reach the Scenario Diagnostic Agent input.",
      "evidenceUrl": "https://github.com/tidbcloud/aisupport/blob/main/auto-oncall-services/docs/opts/2026-08-20-clinic-topology-handoff-facts.md"
    }
  ]
}
-->

- Owner: Clinic Provider Executor compact-fact materialization
- Source: `ST-2865` evidence-chain review
- Implementation status: deployed to staging in image `0e1599be39bc440874be2875053671281b0c4980`
- Effectiveness status: `optimized_unverified`

## Bounded problem

The Clinic components operation already compacts each component's type, node
count, CPU, and memory capacity. The next deterministic materialization step
did not include the `components` array in its factual handoff statement. A
Scenario Diagnostic Agent could therefore see a high TiKV RSS extrema while
missing the 128 GiB per-node capacity needed to interpret the alert boundary.

This is a Provider Executor handoff problem. It does not change query planning,
Provider access, diagnosis ownership, mitigation, severity, or response wording.

## Candidate change

- Preserve the existing bounded component fields `componentType`, `nodeCount`,
  `cpu`, and `memoryGi` in the Clinic factual handoff.
- Keep the canonical compact report as the complete source and retain at most
  twenty already-sanitized component summaries.
- Add an offline `ST-2865`-style fixture that combines 36-node/128-GiB topology
  with a 94.22-GiB per-instance RSS extrema and asserts both reach the Scenario
  Diagnostic Agent finalization input.

## Verification evidence

The offline `ST-2865`-style fixture passed on 2026-08-20. It materialized a
36-node TiKV topology with 128 GiB per node and one compacted per-instance RSS
extrema of 94.22 GiB, then proved that the topology capacity, RSS extrema, and
affected instance all appear in the Scenario Diagnostic Agent finalization
input. The focused Clinic evidence and optimization-record run passed 53/53
tests, and the complete TypeScript suite passed 927/927 tests.

This simulation did not query Clinic and therefore does not prove the current
live cluster state or the final model conclusion.

A deployed `mode=read` replay of `ST-2865` then completed on 2026-08-20 with
run `c40690bc-9710-448d-a1dd-ea69afe96d74`. The Scenario Diagnostic Agent
received the real component topology as 30 TiKV nodes with 128 GiB per node,
alongside instance-labelled memory evidence. The final answer used the aligned
container denominator and reported db-tikv-9 at about 83.5%, peak 83.87%, with
about 20.56 GB headroom; it did not use process RSS divided by advertised node
memory to negate the alert.

## Unresolved gaps

- The offline fixture proves fact delivery, not that the Scenario Diagnostic
  Agent and Scenario Router choose the correct causal strength in every run.
- The deployed replay ran in `mode=read`; the applicable existing Jira internal
  comment was not refreshed, so this diagnostic optimization remains
  `optimized_unverified` under the case-refresh contract.

## Next validation action

Refresh the existing `ST-2865` Jira internal comment through the authorized
write replay and verify the same comment ID before promoting this problem to
`optimized_verified`.