perf(chat): harden thread hydration read path for production scale

[DONGRYEOLLEE1]

배경

현재 OrchAgent는 saved thread를 열 때 보통 아래 두 개의 read endpoint를 호출합니다.

• /api/threads/{thread_id}
• /api/threads/{thread_id}/telemetry

이 구조 자체는 잘못된 것이 아니며, V1 기준으로는 합리적입니다. 다만 사용자 수, 스레드 수, 대화 길이, telemetry 계산량이 커지는 단계에서는 클릭마다 2~3회 read 자체보다도 아래 문제가 커질 가능성이 있습니다.

• 같은 thread를 다시 열 때 cache hit가 없어 read amplification이 생김
• telemetry가 요청 시점 계산이면 click path에서 불필요한 재계산이 반복됨
• hover/click prefetch가 없어 navigation이 network waterfall에 민감함
• 변경 없는 thread detail/telemetry도 payload를 매번 다시 내려받음
• 본문과 오른쪽 패널 실패가 동일한 수준으로 취급될 위험이 있음

즉, 병목의 핵심은 endpoint 개수보다 같은 데이터를 몇 번 다시 계산/다시 전송하느냐에 가깝습니다.

목표

thread hydration read path를 대규모 프로덕션 단계에 맞게 고도화합니다.

핵심 방향은 다음과 같습니다.

• click 시점 계산을 줄이고 turn-complete 시점 precompute를 늘린다
• thread detail / telemetry에 client cache를 도입한다
• sidebar interaction 기반 prefetch를 붙인다
• HTTP conditional request(ETag, Last-Modified, 304)를 검토한다
• 본문 hydrate와 오른쪽 패널 hydrate의 실패 영향을 분리한다

범위

포함:

• thread detail / telemetry read path 최적화
• telemetry precompute 저장 전략 검토
• client cache / staleTime / invalidate 정책 검토
• hover/viewport prefetch 정책 검토
• conditional request 도입 검토
• observability 지표 정의

비포함:

• 채팅 route 구조 재리팩토링
• dashboard/settings 구조 변경
• 전체 API를 단일 endpoint로 강제 통합하는 작업

우선순위 높은 개선안

1. telemetry precompute 저장

우선 reasoning_summary, suggested_queries를 click 시점 계산이 아니라 turn 완료 시점에 저장하는 방향을 검토합니다.

기대 효과:

• /telemetry read path에서 LLM 재호출 제거
• thread open latency 분산 감소
• 클릭 수 증가에도 read path가 DB lookup 중심으로 유지

2. client cache 도입

thread detail / telemetry는 query cache와 잘 맞는 데이터입니다.

초기 검토 항목:

• thread detail cache
• telemetry cache
• staleTime 30~120s
• invalidate 포인트
  • 새 message 전송
  • rename
  • pin/unpin
  • delete

3. hover / viewport prefetch

thread list에서 다음에 열릴 가능성이 높은 항목을 선별해서 prefetch합니다.

후보:

• hover된 thread
• pinned thread
• 최근 active thread 상위 N개

주의:

• thread list 전체 무차별 prefetch는 금지
• intent 기반 prefetch만 허용

4. HTTP conditional request

/api/threads/{thread_id} 및 /api/threads/{thread_id}/telemetry에 대해 아래를 검토합니다.

• ETag
• Last-Modified
• Cache-Control: private, no-cache
• 304 Not Modified

5. response shaping

detail + telemetry를 무조건 하나로 합치기보다, 아래 절충안을 검토합니다.

• /api/threads/{thread_id}
  • thread, messages
  • 가벼운 reasoning_summary
  • 가벼운 telemetry snippet
• /api/threads/{thread_id}/telemetry
  • 전체 reasoning summary
  • 전체 suggested queries
  • raw/debug payload

실패 분리 원칙

• detail 실패
  • thread open 실패
  • / fallback 또는 명확한 error state
• telemetry 실패
  • 본문은 그대로 표시
  • 오른쪽 패널만 degraded state

즉, telemetry는 본문보다 낮은 우선순위로 취급합니다.

관측/지표

최소한 아래 지표가 필요합니다.

• thread detail p50/p95
• telemetry p50/p95
• combined open-thread latency
• cache hit ratio
• 304 ratio
• prefetch hit ratio
• invalid thread fallback rate
• user당 thread open read QPS

완료 조건

• telemetry가 click path에서 재계산되는지 여부를 정리하고, precompute 저장 전환 가능성을 문서화한다
• thread detail / telemetry client cache 전략(staleTime, invalidate 기준)을 정의한다
• hover/viewport prefetch 기준을 정의한다
• conditional request(ETag, Last-Modified, 304) 적용 여부를 결정한다
• detail/telemetry failure isolation 정책을 정리한다
• observability 지표와 측정 포인트를 정의한다
• 구현 순서 기준의 후속 plan 문서로 연결 가능한 수준까지 정리한다

참고 문서

• docs/THREAD_HYDRATION_PRODUCTION_SCALING_RESEARCH.md