docs(realtime): VD-28과 설계 3절의 poll 규칙을 V3 descriptor로 고친다

문제: VD-28은 poll 규칙을 지운 V2 실행 예산으로 적는다. "operation은
registered terminal·replay-safe REST `QUERY`", "Poll-bound VD-23 budget은
`maxAttempts=1`, `authRecoveryCount=0`, `maxCumulativeSleepMs=0`"이다.
설계 3절도 "REST `QUERY` operation"과 "REST operation registry"라고 적는다.
V2 실행 경로는 2026-11-03에 지웠고(VD-23 상태 줄), 지금 규칙은 V3
descriptor의 `frontend.retryBudget: 0`이다(설계 9.2, 1103/04-01).
a65df74가 9.2만 고쳤다.

고른 방법: VD-28 1절 끝 문장과 11절 목록, 설계 3절 두 항목을 지금
규칙으로 바꾼다. GET·HEAD, SAFE·IDEMPOTENT인 V3 descriptor, `retryBudget`
0이 아니면 생성 때 거절, 실행기가 그 칸에서 재시도 상한을 읽어 한
attempt가 요청 하나라는 것이다. 상세는 9.2를 가리킨다.

설계 3절의 "REST operation registry의 credential, conditional request, ...
재사용"은 주어를 V3 실행기로 바꾸면서 conditional request를 뺐다. V3
실행기에는 ETag 처리가 없고(`http-execution-v3.ts`에 If-None-Match 없음),
VD-23 상태 줄이 conditional execution을 `DESIGNED_NOT_IMPLEMENTED`로 적는다.

위험·한계: 문서만 바꿨다. VD-28 11절의 "ETag/`If-None-Match` 또는 server
cursor 사용" 목표 줄은 결정 내용이라 그대로 두었다.

검증: 문서 전용이라 RED 없음. desktop batch에서 확인.
- pnpm verify:documentation
- `git grep -n "authRecoveryCount\|maxCumulativeSleepMs" --
  docs/architecture/decisions/VD-28*` 0건(로컬 확인)

Refs: 1105/04-03
This commit is contained in:
DongHyeonka
2026-11-05 22:06:38 +09:00
parent 27e3dec5dd
commit 05880d12fa
2 changed files with 17 additions and 13 deletions
@@ -114,9 +114,10 @@ protocol-specific terminal proof와 protobuf decode/schema/mapper를 끝낸
runtime-wide notification branch에서만 공통
scope/gap/resync coordinator를 재사용한다. frame/media/trailer, reconnect와
operation deadline owner를 SSE/WebSocket adapter로 합치거나 protobuf message를
`REALTIME_EVENT_V1` JSON으로 다시 감싸지 않는다. Polling의 개별 attempt는 VD-23의
terminal·replay-safe REST `QUERY` execution contract를 재사용하되 transport/Query
retry는 끄고, 이 결정은 attempt 사이 bounded lease만 소유한다.
`REALTIME_EVENT_V1` JSON으로 다시 감싸지 않는다. Polling의 개별 attempt는 V3
contract executor가 실행하는 V3 REST descriptor 하나다(GET·HEAD, SAFE·IDEMPOTENT,
`frontend.retryBudget: 0`, 상세 설계 9.2). transport/Query retry는 끄고, 이 결정은
attempt 사이 bounded lease만 소유한다.
### 2. source of truth는 서버다
@@ -438,10 +439,11 @@ Service Worker를 선택해도 offline fetch, PWA shell cache나 background sync
각 lease는 operation owner, minimum/success/max interval, max attempts,
max elapsed, response byte cap, visible-only policy와 terminal states를 가진다.
- operation은 registered terminal·replay-safe REST `QUERY`여야 함
- Poll `maxAttempts`는 physical request 하나인 logical completion을 셈
- Poll-bound VD-23 budget은 `maxAttempts=1`, `authRecoveryCount=0`,
`maxCumulativeSleepMs=0`; TanStack Query retry도 끔
- operation은 설치된 V3 REST descriptor(`InstalledHttpContract`)로, method가
GET·HEAD이고 `retrySemantics`가 SAFE·IDEMPOTENT여야 함
- descriptor의 `frontend.retryBudget`은 0이어야 함. 아니면 poll coordinator 생성이
거절한다(상세 설계 9.2, 1103/04-01). V3 실행기는 재시도 상한을 이 칸에서 읽으므로
Poll `maxAttempts`의 한 attempt가 physical request 하나다. TanStack Query retry도 끔
- completion-chained timeout으로 single-flight
- hidden/offline/pagehide/unmount/scope change/user cancel에서 stop
- ETag/`If-None-Match` 또는 server cursor 사용
@@ -362,12 +362,14 @@ Connect/gRPC-Web server stream과 향후 GraphQL subscription은 이 문서의 S
VD-29/VD-27 규칙을 우선한다.
- API operation registry의 현재 `SERVER_STREAM`은
`CONNECT_HTTP | GRPC_WEB + rpcKind=SERVER_STREAM`만 허용한다. SSE, WebSocket과 Web Push는
realtime registry가 소유하고, bounded polling은 terminal·replay-safe REST
`QUERY` operation에 적용하는 scheduling policy다.
- bounded polling의 한 logical attempt는 REST operation registry의 credential,
conditional request, schema/mapper와 deadline을 재사용한다. Poll 전용
operation은 transport retry를 끄며 이 문서는 완료된 attempt 사이 cadence와
failure backoff만 소유한다.
realtime registry가 소유하고, bounded polling은 V3 REST descriptor 중
GET·HEAD이고 SAFE·IDEMPOTENT인 읽기 operation에 적용하는 scheduling policy다.
- bounded polling의 한 logical attempt는 V3 contract executor가 실행하고, 그
실행기의 credential, schema/mapper와 deadline을 재사용한다. conditional
request(ETag)는 V3 실행기에 아직 없다(VD-23 conditional execution
`DESIGNED_NOT_IMPLEMENTED`). Poll 전용
operation은 `frontend.retryBudget: 0`으로 transport retry를 끈다(9.2). 이 문서는
완료된 attempt 사이 cadence와 failure backoff만 소유한다.
같은 stream을 Connect/gRPC-Web과 SSE로 자동 failover하지 않는다. wire와 resume 의미가
같다는 backend contract와 별도 rollout evidence가 있을 때만 명시된 fallback으로