From 7d818cfa6a0d53388e7949018165cf2569c89cf6 Mon Sep 17 00:00:00 2001 From: dirtydishes Date: Sun, 17 May 2026 21:31:12 -0400 Subject: [PATCH] polish clickhouse alert context turn document layout --- .../2026-05-17-clickhouse-alert-context.html | 374 +++++++++++++++++- 1 file changed, 363 insertions(+), 11 deletions(-) diff --git a/docs/turns/2026-05-17-clickhouse-alert-context.html b/docs/turns/2026-05-17-clickhouse-alert-context.html index 6ea6daf..604bb63 100644 --- a/docs/turns/2026-05-17-clickhouse-alert-context.html +++ b/docs/turns/2026-05-17-clickhouse-alert-context.html @@ -1,12 +1,364 @@ -2026-05-17 clickhouse alert context -

ClickHouse Alert Context Hydration

-

Summary

Implemented persisted alert-context hydration so alert drawers resolve evidence from ClickHouse context instead of only live cache state.

-

Changes Made

-

Context

Alert rows remain delivered by existing list feeds and websocket channels; this change only affects detail-time hydration for investigative context.

-

Important Implementation Details

The storage bundle resolves evidence refs by type: flowpacket:* refs map to flow packet IDs, remaining refs map to option print trace IDs, and unresolved refs are returned as missing_refs.

-

Expected Impact for End-Users

Selecting alerts now resolves more complete persisted evidence context, reducing empty evidence states caused by live-cache eviction windows.

-

Validation

-

Issues, Limitations, and Mitigations

Front-end loading indicator and explicit missing-ref surfacing in drawer UI are partially addressed; the endpoint and hydration path are in place for further UX polish.

-

Follow-up Work

None required for baseline endpoint + hydration path. If needed, create a follow-up Beads item for richer drawer loading skeleton and explicit missing-ref diagnostics display.

- + + + + + Turn Doc | ClickHouse Alert Context Hydration + + + +
+
+
+

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. +

+
+
+
+
+
+ +