문제
브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이
transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은
execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로
낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고
예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE
행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로
화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인",
WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를
기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양).
고른 방법
- 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader
거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로
바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다.
- poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는
execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다.
executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다.
- 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다.
- 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만
조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이
없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3).
위험·한계
- 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo
안 소비자는 테스트뿐이다.
- 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시
불린다. 상한은 maxAttempts·maxElapsed 그대로다.
- 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로
보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다
(before/after 테스트 그대로 통과).
검증
- 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime
단위 241건 통과.
- check:types 통과, 바꾼 파일 eslint 통과.
BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute
거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은
던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던
조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04
문제
BoundedPollOperationContract는 지운 V2 행의 어휘(contractVersion: 2,
protocol, semantics, replayPolicy, retry, transportMaxAttempts,
authRecoveryCount, maxCumulativeSleepMs, serverStream)로 된 자기 선언이다.
assertBoundedPollOperation은 리터럴만 보고 실제로 실행할 descriptor와
대조하지 않는다. 조합 코드가 execute를 V3 실행기와 기본 GET
descriptor(retryBudget 2)로 만들면 503마다 실행기가 두 번 더 보낸다.
poll 3회가 요청 9회가 되고, poll 관측에는 1건씩만 보인다(리뷰 실험 P).
고른 방법
- coordinator의 operation을 V3 descriptor(InstalledHttpContract)로 바꾼다.
실행기는 재시도 상한을 그 descriptor의 frontend.retryBudget에서 읽는다
(http-execution-v3.ts retryCeiling). 그래서 생성 때
retryBudget === 0을 요구하면 실행기 옵션 없이 poll 한 attempt가 요청
한 번이 된다. 실행기(src/adapters/http)는 고치지 않았다.
- 검사: operationId 일치, method GET·HEAD, retrySemantics SAFE·IDEMPOTENT,
retryBudget 0, responseByteLimit 1..8 MiB. execute에 넘기는
maxResponseBytes는 min(policy.maxResponseBytes, responseByteLimit)이다.
- V2 리터럴 필드는 모두 지운다. command descriptor·요청 본문은 조립
(composeContractContributions)이 GET·HEAD에서 이미 거절한다.
- 버린 대안: (a) ApiOperationRow + HttpExecutionPolicy 두 인자. 행에는
retryBudget이 없고, 실행기가 실제로 받는 것은 descriptor 하나라 같은
객체를 넘기는 쪽이 어긋날 틈이 작다. (b) 실행기에 호출별 재시도 끄기
옵션 추가. 다른 에이전트가 고치는 http 영역을 건드리고, descriptor가
재시도를 허용한다는 사실은 그대로 남는다. (c) 문서에만 적기. 검출이
없다.
위험·한계
- 공개 타입이 바뀐다. repo 안 소비자는 테스트뿐이다.
- 조합 코드가 coordinator에 넘긴 descriptor와 다른 객체를 실행기에
넘기면 막지 못한다. 타입 주석과 설계 9.2에 "같은 객체를 넘긴다"고
적었다. 조립된 행은 동결돼 있어 검사 뒤 값이 바뀌지 않는다.
- 기능의 기본 GET(retryBudget 2)은 poll에 쓸 수 없다. poll 전용
operation을 따로 등록해야 한다.
검증
- 새 테스트를 옛 코드에 돌림: 21건 실패(RED). 새 코드: 32건 통과.
- 실험 P를 테스트로 옮김: 기본 descriptor는 생성 때 TypeError,
retryBudget 0 descriptor + maxRetryAttempts 2 실행기 + 503 서버에서
poll 3회 = 요청 3회.
- 변이 5건(retryBudget·method·retrySemantics·operationId·응답 상한 검사
삭제) 모두 검출.
- check:types 통과, 바꾼 파일 eslint 통과.
BREAKING CHANGE: BoundedPollOperationContract를 지운다.
createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의
둘째 인자는 V3 descriptor(BoundedPollOperation = InstalledHttpContract)다.
조립된 행(composeContractContributions(...).httpByOperationId.get(id))을
넘기고, frontend.retryBudget을 0으로 둔 poll 전용 operation을 등록한다.
execute 안에서는 같은 descriptor를 실행기에 넘긴다.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-01
Design 14.1 connect and bounded_poll events had no place to come from, and
an exhausted budget looked the same as a terminal failure. Both coordinators
now emit a closed observation vocabulary through a best-effort sink.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- bounded-poll: an executor that throws becomes OFFLINE retryable:true,
but OFFLINE is not a poll-retryable kind, so the run ended through
pollFailure(kind) with retryable:false. OFFLINE now keeps its
retryable flag on that exit, like the lifecycle OFFLINE exits.
- sse-parser: TextDecoder(ignoreBOM: false) already strips the one
leading BOM the stream grammar allows; the parser stripped a second one.
The manual strip is removed.
- event-codec: the raw event was UTF-8 encoded twice; now once.
- fetch-sse-connection: one module TextEncoder instead of a new one per
event and per cursor check.
- websocket-protocol: the R-05 admission JSDoc sat on utf8ByteLength; it
now documents exceedsUtf8ByteLimit, and utf8ByteLength reuses one
encoder.
RED: a throwing executor returned retryable:false; a stream starting with
two BOMs before "data: x" produced an event. Both pass now; the
encode/JSDoc items are covered by the existing codec, SSE and WS suites.
Gates: architecture, types app/test, lint, adapter-inventory, test:unit,
test:component pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Realtime kept three DataSnapshot readers and about ten hand-written
abort/timeout races, and two parsers had drifted copies in other adapters.
Snapshot: reconnect-coordinator and bounded-poll now use result.ts
captureRealtimeDataSnapshot (+ `source`, variadic hasExactSnapshotKeys).
Kept the result.ts rules, the stricter ones: Object.hasOwn instead of
`"value" in` (prototype pollution), enumerable fields only, keys read from
one descriptor snapshot, frozen computed at snapshot time instead of a
later Object.isFrozen. Poll therefore now rejects non-enumerable fields;
it also accepts null-prototype records, which the other two copies
already did (pure data, no inherited accessors). Characterization test
added for both in bounded-poll-coordinator.test.ts.
Race: one raceRealtimeTask(task, signal, deadline) in result.ts, built on
kernel createAbortableOperation, replaces fetch-sse timed/cancelReader,
reconnect race/drain (the drain keeps a host timer via timerDeadline,
since the clock itself may hang), poll awaitTaskOrAbort/awaitWithinLease,
live-poll checkpoint + two quiescence races (now one), stream-coordinator
deadline/recovery-wait/close-drain, and the two WS inline races. Kept
semantics: deadline armed first and wins a tie (poll lease), task still
starts when the clock throws (reader cancel), collaborator rejections
still reach stream-coordinator callers, scheduler install failure still
fails closed as a timeout. Small change: nothing starts once the signal is
already aborted (WS apply / SSE onEvent / reader.read could run just
before being reported ABORTED). The mapping adds one microtask per race,
so the reconnect test flush() helper gets 16 turns instead of 8.
Kernel: parseRetryAfterDelay moves to platform/retry-after.ts (realtime
re-exports it; http retry-policy parseRetryAfter now delegates, so it
rejects "", " ", "1e3", "1.5", "0x10" and non-IMF dates it used to
accept). json-member-scanner moves to platform/; web-push push-codec uses
it instead of its top-level-only duplicate-key check, so nested
duplicates are rejected too. INVENTORY 136 -> 137, detail tables updated.
Tests: RED for http strict Retry-After, web-push nested duplicate, poll
snapshot rules; new direct raceRealtimeTask tests. Gates: architecture,
types app/test (+ service-worker/web-worker), lint, adapter-inventory
(abort ratchet 21/21), test:unit, test:component, realtime-boundaries,
integration/platform all pass. Realtime bundle 40346 -> 39433 gzip.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
reconnectable() in the reconnect coordinator returned false for
PROVIDER_UNAVAILABLE/RATE_LIMITED whenever serverNotBeforeMs was null, even
with retryable:true. The transports send exactly that for WS NETWORK_LOST /
RESTART (1006/1001/1012, error event) and SSE 502/504, and WS can never carry
a hint, so those streams ended instead of reconnecting. The bounded poll
coordinator had the same rule for retryAfterMs.
Both now decide on retryable + kind only; a missing hint falls back to policy
backoff. Transports that require a hint and lack one already report
retryable:false (SSE 429/503 without Retry-After, WS OVERLOADED), which stays
terminal.
Tests: the reconnect and poll tests that pinned the old behavior ("does not
reconnect/retry ... without a server hint") encoded the bug and are rewritten
to expect a policy-backoff retry. New seam tests wire the real
createWebSocketConnection / createFetchSseConnection into the reconnect
coordinator. RED before the fix: "reconnects a WebSocket NETWORK_LOST|RESTART
close that carries no server hint" (1 socket, expected 2), "reconnects SSE
HTTP 502|504 that carries no server hint" (got PROVIDER_UNAVAILABLE
retryable:true instead of the second attempt's FORBIDDEN), "retries retryable
RATE_LIMITED|PROVIDER_UNAVAILABLE without a server hint on policy backoff"
(execute called once). The WS test also closes with OVERLOADED to show
retryable:false stays terminal.
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component pass. test:unit passes except removal-fixture.test.ts, which
needs generated artifacts/release evidence absent from this fresh worktree
(unrelated).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>