# Clinic Opaque Digest Reference Normalization

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "clinic-opaque-digest-ref-normalization-2026-08-18",
  "problems": [
    {
      "problemId": "clinic-refinement-reuses-opaque-digest-as-provider-filter",
      "summary": "Clinic refinement copied a compact sha256 Digest reference into slow_query.digest, causing deterministic plan rejection before otherwise valid queries could run.",
      "status": "optimized_verified",
      "applicability": "Clinic Slow Query refinement plans that reuse a 6-to-63-character hexadecimal Digest prefix from a prior handoff, plus historical plans containing the former sha256:<16hex> reference.",
      "issueKeys": ["TCID-12986"],
      "sourceRefs": ["https://tidb.atlassian.net/browse/TCID-12986#problem:clinic-opaque-digest-ref-reused-as-filter"],
      "signalTextIncludesAny": ["clinic_slow_query_digest_invalid", "sha256:75b500d8a023bb24", "opaque Digest reference"],
      "observedThrough": "2026-08-18",
      "effectiveAt": "2026-08-18T06:23:01Z",
      "verifiedAt": "2026-08-18T17:21:21.557Z",
      "attemptedAction": "Emit a bare six-character SQL Digest prefix, accept bare 6-to-63-character hexadecimal prefixes in slow_query.digest, perform a bounded prefix lookup, and use the matched full Digest internally for profile retrieval while retaining historical sha256:<16hex> inputs compatibly.",
      "evidenceUrl": "https://tidb.atlassian.net/browse/TCID-12986?focusedCommentId=23357171"
    }
  ]
}
-->

- Owner: Clinic Provider Executor
- Source: TCID-12986 read replay `38812153-6a97-4b78-9ea9-8a95b0a7e218`
- Implementation status: deployed to staging
- Effectiveness status: optimized_verified

## Bounded problem

The query-latency refinement copied `sha256:75b500d8a023bb24` from the former
compact Slow Query handoff into `slow_query.digest`. Plan parsing accepted only
a raw 64-hex SQL Digest and rejected the whole round with
`clinic_slow_query_digest_invalid` before any round-2 provider query ran, so
independent metric reads in the same batch were also lost.

## Candidate change

- Keep the full Digest outside the Agent handoff.
- Emit the first six hexadecimal characters of the raw SQL Digest without a
  label or wrapper. Accept 6-to-63-character prefixes in `slow_query.digest`;
  shorter or non-hex values remain invalid, while 64 characters mean exact
  matching.
- Resolve the six-character prefix inside the bounded Slow Query read, retain
  matching executions, and use the selected full Digest internally for profile
  retrieval.
- Continue reading historical `sha256:<16hex>` plans without failing their
  otherwise valid batch.

## Verification evidence

The full TypeScript build and 890/890 tests pass. The executor test proves a
bare six-character key becomes a bounded Digest-prefix predicate, the helper-owned
profile uses the matching raw Digest internally, and only the compact six-digit
key crosses the handoff.

A read-only direct re-execution of the exact saved TCID-12986 query-latency
round-2 context and plan completed against Clinic on 2026-08-18. The batch was
`complete`, all eight queries avoided failure, and
`candidate-normal-executions` returned 87 overlapping rows (20 retained). This
proves the previous deterministic `clinic_slow_query_digest_invalid` blocker is
removed for the historical 16-character input. The six-character prefix path
is covered locally.

Source PR [#971](https://github.com/tidbcloud/aisupport/pull/971) and
app-delivery PR [#77512](https://github.com/tidbcloud/app-delivery/pull/77512)
were merged. Staging converged to image
`f2c832c6a482e649c8d3496a94a7769b73794cf0` with one Ready replica, zero pod
restarts, and HTTP 200 from both `/healthz` and `/readyz`.

The deployed same-cutoff `mode=read` replay of TCID-12986 completed with HTTP
200 as run `3cac7aff-e189-4c71-a830-aa2d574942cc`. Query-latency round 2 used
four bare six-character prefixes: `27effe`, `f8e19b`, `bc6171`, and `0d9518`.
All four Slow Query operations executed successfully: one was empty and the
other three returned 12, 100, and 2 rows respectively. Across the replay, all
30 Provider queries succeeded, evidence acquisition and response generation
completed, and `clinic_slow_query_digest_invalid` was absent.

The later staging `mode=write` replay
`b975f4a1-22a3-4cb6-8069-87779f626a02` exercised Slow Query again, including
the six-character `a862ec` refinement, alongside typed TopSQL and independent
metrics. All 41 Clinic query events succeeded, evidence acquisition was
`complete`, and `failureCodes=[]`; no Digest validation failure recurred. The
existing Jira internal comment `23357171` was updated in place and read back as
`public=false` with no duplicate comment.

## Unresolved gaps

Historical 16-character opaque references cannot be converted back into raw
Digest prefixes and therefore retain compatibility behavior only. Fresh
handoffs use the directly resolvable six-character format.

## Next validation action

Monitor later six-to-63-character Digest refinements for ambiguous-prefix or
no-match results; those remain bounded evidence outcomes rather than plan
validation failures.