Files
clean-architecture-frontend…/docs/architecture
DongHyeonka 5b3f5b0eb3 docs(realtime): 13.1에 내부 task 마감의 IDLE_TIMEOUT 뜻을 적는다 (04-02)
문제: 설계 13.1은 IDLE_TIMEOUT을 "heartbeat/byte deadline 초과 ->
close + bounded reconnect" 한 뜻으로만 적는다. 코드는 같은 kind를
내부 task 마감에도 쓴다. stream coordinator는 effect·recovery·close
drain 마감을 IDLE_TIMEOUT/APPLY·RECOVER·CLOSE(retryable false)로,
handoff coordinator는 quiescence·checkpoint·close 마감을
IDLE_TIMEOUT/RECOVER·CLOSE(기본값 retryable)로 보고한다. 13.1만 보고
조합 코드를 쓰면 내부 마감도 재연결 대상으로 읽는다.

RED(문서-코드 대조): 13.1 행은 transport 뜻 하나. 코드에서
IDLE_TIMEOUT을 만드는 곳은 transport 3곳(SSE RECEIVE, WS RECEIVE·
SUBSCRIBE)과 내부 task 7곳(stream-coordinator.ts 3곳,
live-poll-handoff-coordinator.ts 4곳). stream coordinator close()
주석은 "IDLE_TIMEOUT이면 아직 DRAINING"을 공개 계약으로 적는다.

고른 방법: 리뷰의 (b). 13.1 IDLE_TIMEOUT 행을 코드에 맞춰 두 뜻,
operation으로 구분하는 법, 각 경우의 recovery, 관측에서 구분되지
않는다는 한계를 적는다. 코드는 바꾸지 않는다.

버린 대안: (a) stream coordinator의 마감을 APPLY_FAILED·
PROVIDER_UNAVAILABLE로 바꾸기. 리뷰는 코드 3곳으로 봤지만 같은 관례가
handoff coordinator 4곳에도 있고, stream coordinator close()의
IDLE_TIMEOUT은 주석에 적힌 공개 계약이다. 바꾸려면 두 coordinator의
마감 어휘를 함께 정해야 하므로 별도 결정으로 남긴다.

위험·한계:
- 리뷰 완료 기준 중 "effect 마감과 전송 idle을 관측에서 구분"은
  충족하지 못했다. reconnect 관측(RUN_ENDED)에 operation이 없다.
  (a) 또는 관측에 operation 추가가 필요하다.
- handoff 마감 결과가 retryable true(kind 기본값)이고 stream
  coordinator는 false인 차이는 문서에 적기만 했다.

검증:
- `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED.
- 코드 변경 없음. 테스트 미실행(해당 없음).

Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02, 6.3절
2026-11-01 22:49:38 +09:00
..