문제: bounded poll은 생성 때 descriptor의 `retryBudget`이 0인지 본다
(1103/04-01). 그런데 `execute` 입력에는 descriptor가 없다. 조합 코드는
실행기에 넘길 descriptor를 스스로 골라야 하고, 같은 경로의 기본 GET
(`retryBudget: 2`)을 넘겨도 막는 것이 없다. 리뷰 04-R1 P5에서 poll 3회가
요청 9회, 실행기 대기 6번이었다. 타입 주석과 설계 9.2가 "같은 객체를
넘긴다"고 적을 뿐이다.
고른 방법: coordinator가 생성 때 검사한 그 객체를 모든 `execute` 호출에
`input.operation`으로 넘긴다. 생성 때 한 번 잡아 두므로 나중에
dependencies 객체가 바뀌어도 검사한 객체가 간다. 조합 코드는 클로저의
descriptor 대신 이것을 실행기에 넘기면 된다. 테스트의 V3 조합도 그렇게
바꿨다. 타입 주석(`bounded-polling.ts`, `bounded-poll-coordinator.ts`)과
설계 9.2를 고쳤다.
버린 대안: coordinator가 실행기를 직접 받아 부르기. 실행기 타입은
`adapters/http`에 있어 realtime 어댑터가 import할 수 없다(adapter 사이
import 금지, kernel 예외 아님). 구조 타입을 새로 두면 결과 매핑까지
coordinator가 정해야 해서 공개 모양이 크게 바뀐다.
위험·한계: 일부만 닫는다. 조합 코드가 `input.operation`을 무시하고 다른
descriptor를 실행기에 넘기면 여전히 attempt마다 요청이 최대 3번이다.
설계 9.2가 이 남은 틈을 적는다. 입력 칸을 더한 것이라 기존 `execute`는
그대로 돈다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "hands every execute call the descriptor it checked at creation"
(받은 값이 undefined), "sends one request per poll attempt with a poll
descriptor"(실행기에 undefined가 가서 요청 0개, PROTOCOL_MISMATCH)가
옛 코드에서 실패한다.
Refs: 1103/04-01
문제: bounded poll은 `execute`의 throw를 PROVIDER_UNAVAILABLE/retryable로
바꿔 lease 안에서 다시 부른다(af00067). 설계 9.2가 권하는 조합은
`execute` 안에서 V3 실행기를 부르는 것이고, 실행기는 fetch 거절을 던지지
않고 NETWORK_FAILURE 결과로 돌려준다. 그래서 그 조합에서 throw는 결과
매핑·디코딩 같은 조합 코드 결함이다. 지금은 그 결함이 maxAttempts번의
요청과 ATTEMPT_FINISHED: PROVIDER_UNAVAILABLE, 끝으로
POLL_BUDGET_EXHAUSTED가 되어 서버 장애로 보인다. 원인 예외는 남지 않는다.
고른 방법: 리뷰 04-02의 선택지 (b). throw를 모양이 틀린 결과와 같은
계약 위반으로 본다. coordinator는 이미 `parseAttemptResult`가 거절한
결과를 재시도 없이 PROTOCOL_MISMATCH로 끝낸다. throw도 그 길로 보낸다.
lease 자신의 abort로 생긴 throw는 지금처럼 abort의 이유(ABORTED,
OFFLINE, 예산 소진 등)로 끝난다. `execute` 타입 주석, 설계 9.2와 13.1의
PROVIDER_UNAVAILABLE·PROTOCOL_MISMATCH 행을 같이 고쳤다.
버린 대안:
- (c) 주석과 13.1에만 "throw는 서버 장애로 재시도된다"를 적기. 완료
기준은 "결과를 보고 조합 결함과 서버 장애를 구분한다"인데, (c)는 읽는
사람만 알고 결과는 그대로라 구분할 수 없다.
- 관측에 throw 표시 칸을 더하기. 닫힌 관측 어휘를 넓히고, 결과 kind는
여전히 서버 장애다.
위험·한계:
- 배럴로 공개된 bounded poll의 결과가 바뀐다. repo 안 소비자는 테스트뿐이다.
- `fetch`를 직접 부르는 조합은 네트워크 실패를 결과로 바꾸지 않으면 첫
거절에서 lease가 끝난다. 설계가 권하지 않는 조합이고, 타입 주석과
9.2가 "실패도 결과로 돌려준다"를 적는다.
- reconnect coordinator는 던지는 `attempt`를 계속 PROVIDER_UNAVAILABLE로
재시도한다. 그쪽 attempt는 브라우저 연결 API를 감싸는 자리라 이번
범위 밖이다.
- CHANGELOG.md 미출시 [계약] 행의 "poll은 던지는 execute도 lease 안에서
다시 시도한다"는 이 커밋과 맞지 않는다. CHANGELOG는 오케스트레이터가
고친다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/realtime/
- RED: "ends the lease with PROTOCOL_MISMATCH for an async execute that
rejects"·"... throws before returning"가 옛 코드에서 execute 3회,
POLL_BUDGET_EXHAUSTED로 실패한다. "keeps ABORTED ..."는 양쪽에서 통과한다
(보존 조건).
BREAKING CHANGE: createBoundedPollCoordinator의 `execute`가 던지면(abort로
생긴 것 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable: false)로 lease가
끝난다. 전에는 PROVIDER_UNAVAILABLE로 maxAttempts까지 재시도했다.
네트워크 실패를 throw로 내던 `execute`는 그것을 retryable
PROVIDER_UNAVAILABLE 결과로 바꿔 돌려준다.
Refs: 1105/04-02
문제
브라우저는 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>