fix(realtime): live-poll handoff 마감 실패를 13.1의 kind로 보고한다 (04-02)

문제: 1196b86은 stream coordinator의 마감 실패만 13.1 어휘로 바꿨다.
live↔Poll handoff coordinator는 아직 네 마감을 모두 `IDLE_TIMEOUT`으로
보고한다. 설계 13.1에서 `IDLE_TIMEOUT`은 전송 idle(heartbeat/byte
deadline → close + bounded reconnect)이다. 그래서 관측에서 "서버가
조용함"과 "우리 effect·checkpoint가 멈춤"을 kind로 나눌 수 없다.
- switchToPoll quiescence 마감: IDLE_TIMEOUT/RECOVER
- activateProbe quiescence 마감: IDLE_TIMEOUT/RECOVER
- checkpoint 마감: IDLE_TIMEOUT/RECOVER
- close drain 마감: IDLE_TIMEOUT/CLOSE

고른 방법: 결정 (a)를 1196b86과 같은 방식으로 적용한다. kind만 바꾸고
operation, retryable(전과 같이 true), fail-close 동작은 그대로 둔다.
- quiescence 마감 → APPLY_FAILED/RECOVER. 기다리는 것은 이전 writer의
  apply effect tail이다. stream coordinator의 effect 마감과 같은 kind다.
  APPLY_FAILED의 기본 retryable은 false라 true를 명시했다. 두 곳의 같은
  분기를 `quiescenceFailure` 하나로 합쳤다.
- checkpoint 마감 → PROVIDER_UNAVAILABLE/RECOVER. checkpoint authority가
  throw할 때와 같은 kind다.
- close drain 마감 → PROVIDER_UNAVAILABLE/CLOSE. stream·reconnect
  coordinator의 drain 상한과 같다. 이전부터 timer 실패도 같은 값이라 두
  분기를 하나로 합쳤다.
- 13.1 표: IDLE_TIMEOUT 행에서 handoff를 빼고 "내부 task 마감에는 쓰지
  않는다"로 적었다. APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 handoff 마감과
  retryable 값, 뒤 동작을 적었다. 남은 IDLE_TIMEOUT 생성 지점은 SSE·WS의
  RECEIVE·SUBSCRIBE(전송 idle)뿐이다.

버린 대안:
- retryable도 kind 기본값으로(quiescence가 false가 됨): 결정 범위는
  어휘다. 재시도 판단 변경은 따로 정한다.
- close 마감에 CLOSED: 1196b86과 같은 이유로 버렸다. 아직 writer가
  settle하지 않았는데 "닫힘"으로 읽힌다.

위험·한계:
- 배럴로 공개된 handoff coordinator 결과의 kind가 바뀐다. IDLE_TIMEOUT을
  보던 조합 코드는 APPLY_FAILED·PROVIDER_UNAVAILABLE을 봐야 한다. repo
  안에 소비자는 없다(AVAILABLE_NOT_COMPOSED).
- handoff에는 observer가 없어 관측 reason은 바뀌는 것이 없다.
- 같은 APPLY_FAILED라도 stream coordinator는 retryable:false, handoff는
  true다. 13.1 표에 둘 다 적었다.
- realtime 레시피 gzip 40,902 → 40,878 B(한도 42,200).

검증:
- RED: 기대값을 먼저 바꾸고 activateProbe quiescence 마감 테스트를 새로
  넣은 뒤 live-poll-handoff-coordinator.test.ts 실행 → 7 failed | 9
  passed. 7건 모두 received kind IDLE_TIMEOUT(close 4건, switchToPoll
  quiescence, activateProbe quiescence, checkpoint).
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime` 14 files,
  231 passed.
- tsc app·test·recipes 통과, 바꾼 두 파일 eslint 통과,
  `check-optional-recipes`(source) PASS, `verify-documentation-readiness`
  PASS_SCOPED, `check-adapter-inventory` PASS.
- 미실행: `check:architecture`(pnpm 필요).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.1 04-02, 14.4
This commit is contained in:
DongHyeonka
2026-11-03 20:22:49 +09:00
parent e5b7b3e857
commit 17fa8d1f65
3 changed files with 65 additions and 30 deletions
@@ -1895,11 +1895,11 @@ credential을 보호할 수 있다고 주장하지 않는다.
| `UNSUPPORTED` | browser capability 없음 | declared fallback |
| `OFFLINE` | network hint/attempt failure | online hint 뒤 bounded check |
| `CONNECT_TIMEOUT` | open deadline 초과 | bounded reconnect |
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). handoff coordinator의 quiescence·checkpoint·close deadline 초과(operation `RECOVER`·`CLOSE`) | transport: close + bounded reconnect. handoff 마감은 재연결로 풀리지 않는다: 그 전환을 fail-close한다(결과는 kind 기본값대로 retryable). 두 뜻은 `operation`으로 구분한다 |
| `IDLE_TIMEOUT` | transport: heartbeat/byte/unsubscribe deadline 초과(operation `RECEIVE`·`SUBSCRIBE`). 내부 task 마감에는 쓰지 않는다 | close + bounded reconnect |
| `AUTH_REQUIRED` | session expired/recovery 실패 | sign-in UX |
| `FORBIDDEN` | stream/resource 거절 | retry 없음 |
| `RATE_LIMITED` | connection/request/provider limit | bounded server hint |
| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다 |
| `PROVIDER_UNAVAILABLE` | backend/push/hosting unavailable. stream coordinator의 recovery deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: false`). live↔Poll handoff coordinator의 checkpoint deadline 초과(operation `RECOVER`)와 close drain deadline 초과(operation `CLOSE`)도 이 kind다(`retryable: true`) | bounded retry 또는 degraded. stream coordinator 마감은 재연결로 풀리지 않는다: task가 settle할 때까지 `DRAINING`을 유지한다. settle 뒤 recovery 마감은 다음 event가 recovery부터 하고, close 마감은 `CLOSED`가 된다. handoff checkpoint 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다. handoff close 마감 뒤에는 writer·checkpoint task가 settle하면 다시 부른 `close()`가 성공한다 |
| `PROTOCOL_MISMATCH` | version/subprotocol/content type | terminal/rollout rollback |
| `MALFORMED_EVENT` | state-bearing syntax/schema/exact-key 실패 | cursor 미진행, freshness `UNKNOWN`, close + registered recovery |
| `MAPPING_CONTRACT_VIOLATION` | validated DTO의 registered mapper 실패 | effect/cache/cursor write 0, close + registered recovery |
@@ -1910,7 +1910,7 @@ credential을 보호할 수 있다고 주장하지 않는다.
| `SEQUENCE_GAP` | missing event | snapshot resync |
| `CURSOR_EXPIRED` | replay retention 밖 | snapshot reset |
| `QUEUE_OVERFLOW` | backpressure ceiling | close + registered snapshot/session rebuild |
| `APPLY_FAILED` | feature effect 실패. stream coordinator의 effect deadline 초과(operation `APPLY`, `retryable: false`)도 이 kind다 | cursor 미commit, bounded registered recovery. deadline 초과는 recovery를 바로 하지 않는다: task가 settle할 때까지 `DRAINING`을 유지하고, settle 뒤 다음 event가 recovery부터 한다 |
| `APPLY_FAILED` | feature effect 실패. stream coordinator의 effect deadline 초과(operation `APPLY`, `retryable: false`)도 이 kind다. live↔Poll handoff coordinator에서 이전 writer의 effect가 quiescence deadline 안에 끝나지 않은 것(operation `RECOVER`, `retryable: true`)도 이 kind다 | cursor 미commit, bounded registered recovery. deadline 초과는 recovery를 바로 하지 않는다: task가 settle할 때까지 `DRAINING`을 유지하고, settle 뒤 다음 event가 recovery부터 한다. handoff quiescence 마감은 그 전환을 fail-close하므로 새 handoff만 돌 수 있다 |
| `POLL_BUDGET_EXHAUSTED` | lease 한도 도달 | stale/manual retry |
| `PUSH_PERMISSION_DENIED` | 사용자 거절 | foreground fallback |
| `PUSH_SUBSCRIPTION_STALE` | rotation/expiry/provider gone | bounded re-registration |