Turn Documentation

ClickHouse Alert Context Hydration

Alert detail drawers now load persisted evidence context from ClickHouse by alert trace id, then hydrate linked flow packets and option prints into the existing pinned evidence maps.

Validation complete

Summary

Alert detail hydration no longer depends only on live cache residency. When a user selects an alert, the terminal now requests a persisted context bundle and resolves linked evidence from ClickHouse.

Changes Made

  • Added storage lookup for alert context by trace_id with explicit missing_refs diagnostics.
  • Added API endpoint GET /flow/alerts/:trace_id/context for detail-time evidence hydration.
  • Updated terminal selection flow so hydrated packets and prints merge into pinned evidence maps shared by drawers and support paths.
  • Updated drawer copy from live-cache miss language to persisted-context language.
  • Preserved dense drawer structure while surfacing execution context fields such as NBBO side, bid/ask/mid/spread, quote age, and underlying spot/bid/ask/mid.

Context

Existing list feeds remain unchanged, including /flow/alerts, /history/alerts, /replay/alerts, and live websocket rows. This keeps burst-time payloads lean while moving heavy evidence lookup to detail interactions.

Important Implementation Details

Context endpoint payload:

{
  alert: AlertEvent | null,
  flow_packets: FlowPacket[],
  option_prints: OptionPrint[],
  missing_refs: string[]
}

Evidence refs are resolved without failing the whole response when some refs are stale or absent. Unresolved refs are surfaced to UI as diagnostics.

Expected Impact for End-Users

Alert investigation should remain reliable after live cache churn. Users can open an alert and still inspect preserved evidence context needed for decision-making, even when original live rows rotated out.

Validation

  • bun test packages/storage/tests passed
  • bun test services/api/tests passed
  • bun test apps/web/app/terminal.test.ts passed
  • bun --cwd=apps/web run build passed

Issues, Limitations, and Mitigations

  • Detail-time hydration adds a request on selection; this intentionally avoids inflating live alert table payloads.
  • Malformed trace ids are rejected safely at the route layer.
  • Missing evidence refs are reported as missing_refs instead of causing hard failure.

Follow-up Work

No mandatory follow-up remains for baseline delivery. Further UI refinement could add richer missing-ref drilldown and stronger loading placeholders if desired.