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절
This commit is contained in:
DongHyeonka
2026-11-01 22:49:38 +09:00
parent 3fe28dec2e
commit 5b3f5b0eb3
@@ -1890,7 +1890,7 @@ credential을 보호할 수 있다고 주장하지 않는다.
| `UNSUPPORTED` | browser capability 없음 | declared fallback |
| `OFFLINE` | network hint/attempt failure | online hint 뒤 bounded check |
| `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect |
| `IDLE_TIMEOUT` | heartbeat/byte deadline 초과 | close + bounded reconnect |
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task: stream·handoff coordinator의 effect·recovery·quiescence·close deadline 초과(operation `APPLY`·`RECOVER`·`CLOSE`) | transport: close + bounded reconnect. 내부 task는 재연결로 풀리지 않는다: stream coordinator는 `retryable: false`로 보고하고 task가 settle할 때까지 `DRAINING`을 유지하며, handoff는 그 전환을 fail-close한다(결과는 kind 기본값대로 retryable). 두 뜻은 kind가 아니라 `operation`으로 구분한다. reconnect 관측(`RUN_ENDED failureKind`)에는 `operation`이 없어 구분되지 않는다 |
| `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX |
| `FORBIDDEN` | stream/resource 거절 | retry 없음 |
| `RATE_LIMITED` | connection/request/provider limit | bounded server hint |