문제: stream coordinator는 effect 마감 초과를 IDLE_TIMEOUT/APPLY로,
recovery 마감 초과를 IDLE_TIMEOUT/RECOVER로, close drain 초과를
IDLE_TIMEOUT/CLOSE로 보고한다. 설계 13.1에서 IDLE_TIMEOUT은 전송
idle(heartbeat/byte deadline -> close + bounded reconnect)이다. reconnect
관측(RUN_ENDED failureKind)에는 operation이 없어서 운영에서 "서버가
조용해짐"과 "우리 effect가 멈춤"을 failureKind로 나눌 수 없다.
5b3f5b0은 13.1에 두 뜻을 적기만 했다(리뷰의 (b)).
고른 방법: 리뷰의 (a). kind만 바꾸고 retryable:false, DRAINING 유지,
resume token 폐기는 그대로 둔다.
- effect 마감: APPLY_FAILED/APPLY. 13.1의 "feature effect 실패"이고,
WebSocket 연결도 자기 apply 마감을 APPLY_FAILED로 보고한다.
- recovery 마감: PROVIDER_UNAVAILABLE/RECOVER. recovery source가 제때
답하지 않은 것이다. recovery가 throw한 경우와 같은 kind다.
- close drain 마감: PROVIDER_UNAVAILABLE/CLOSE. reconnect coordinator가
drain 상한 초과를 PROVIDER_UNAVAILABLE로 보고하는 것과 맞춘다.
- 관측 reason도 같은 kind로 바꾼다.
- 13.1 표는 IDLE_TIMEOUT 행에서 stream coordinator 설명을 빼고,
APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 마감 경우를 적는다.
VD-28의 같은 설명도 고친다.
이 템플릿으로 운영 중인 제품이 아직 없어서 관측 값을 바꾸는 비용이
지금 가장 작다.
버린 대안: (b) 문서만 고친다. 5b3f5b0이 한 것이고, 관측에서는 여전히
구분되지 않는다. close 마감에 CLOSED를 쓰는 것도 버렸다. 아직
DRAINING인데 "닫힘"으로 읽힌다.
위험·한계:
- 공개로 관측되는 값이 바뀐다. stream coordinator 결과의 kind와
RealtimeObservation.reason에서 IDLE_TIMEOUT을 보던 조합 코드는
APPLY_FAILED/PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 그런
소비자는 없다.
- live-poll handoff coordinator의 quiescence·checkpoint·close 마감은
여전히 IDLE_TIMEOUT이다. 결정 범위(stream coordinator)를 지켰다.
13.1 IDLE_TIMEOUT 행에 handoff 마감만 남겨 적었다.
- realtime 레시피 번들 gzip이 40,897 B에서 40,902 B로 늘어 예산
40,900 B를 2 B 넘는다. "PROVIDER_UNAVAILABLE"이 "IDLE_TIMEOUT"보다
8자 길어 3곳에서 원본이 24 B 늘었다. 예산은 올리지 않았다.
check-optional-recipes가 REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED로
실패한다.
검증:
- RED: 기대값을 먼저 바꾸고 stream-coordinator.test.ts 실행 ->
7 failed | 31 passed. 예: expected kind APPLY_FAILED, received
IDLE_TIMEOUT.
- GREEN: tests/unit/realtime 14 files, 230 passed.
- tsc (tsconfig.app.json, tsconfig.test.json) 통과. 바꾼 두 파일 eslint
통과. verify-documentation-readiness PASS_SCOPED.
- check-optional-recipes: realtime 40902 > 40900 실패(위험 참고).
Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02
A full dedupe window (2,048 IDs / 4 MiB) used to trigger a full
DEDUPE_OVERFLOW recovery on every event past capacity, so a steady
3.4 events/s stream re-fetched snapshots and reconnected every window.
The coordinator now drops the oldest entry (Map insertion order equals
apply order) and keeps applying; a replay pushed out of the window still
drops as STALE_EVENT through the sequence check. The design doc row and
the maxDedupeBytes contract comment now say eviction instead of recovery.
The semantic fingerprint is now a 16-char 64-bit FNV-1a hash of the
canonical envelope instead of the canonical text itself (up to 64 KiB
each). The canonical-size EVENT_TOO_LARGE check only bounded that stored
text, so it goes too; the wire-size check stays. pruneDedupe stops at the
first unexpired entry instead of scanning every entry.
The old "recovers instead of evicting" coordinator test encoded the bug
and is replaced by an eviction test. RED: the eviction test (got
RECOVERED/DEDUPE_OVERFLOW) and a fixed-size fingerprint codec test (got
3326 vs 333 bytes) failed before the change. Added a TTL prune
characterization test (passes before and after). Gates: architecture,
types app/test, lint, adapter-inventory, test:unit, test:component pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
runRecovery() checked lifecycle === "DRAINING" only on entry. After
`await quiescence` it re-checked closed/abort/scope but not DRAINING, so an
effect that timed out while the recovery waited left the stream DRAINING and
the recovery still called the authority, committed a new resume state and
cleared recoveryRequired while the abandoned effect kept running (the
RT-RR-01/02 case).
The post-quiescence check now also fails with CLOSED/RECOVER when the stream
is DRAINING, without calling the authority.
Test: "fails a recovery whose effect quiescence ends in DRAINING" in
stream-coordinator.test.ts. RED before the fix: the recovery resolved
{ ok: true } (authority called and committed). After: CLOSED, authority not
called, no resume state; once the late effect settles the stream is OPEN and
STALE.
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>
A server stream's registration was pruned on any settled close receipt.
`waitClosed()` rejecting, throwing synchronously, or not returning a
promise at all was absorbed into a fulfilled `undefined`, so the runtime
opened a second physical stream for the same operation while the first was
still running against the server. Only a fulfilled, contract-shaped
receipt confirms closure now; every negative receipt keeps the operation
DRAINING.
Cleanup also read foreign state outside the result boundary. A throwing
iterator `return` accessor replaced the already selected timeout with a
native `TypeError` and skipped the rest of the teardown, and the exported
lease decoder threw on a hostile `Symbol.asyncIterator`. Both reads move
inside their own boundaries, and the positive-close subscription is
installed before any fallible cleanup.
Composition validated the caller's registries before snapshotting them, so
a hostile accessor ran twice during validation, and rows hiding fields
behind a prototype or a non-enumerable key installed. Transport results
were checked for allowed own keys only, so own `{ok,message,encodedBytes}`
plus a prototype `injected` was a success and a missing `message` reached
a permissive schema as `undefined`.
In Realtime the tracked task was registered after the collaborator
returned. An authority that re-entered `close()` from inside its own
invocation saw an empty registry and got `{ok:true}` while its effect was
pending. The task is now registered first and the collaborator is invoked
a microtask later. A `scheduleTimeout` that threw was worse: the caller's
own catch treated it as an apply failure and started a recovery beside the
still-running effect, and `close()` rejected with a native `TypeError`. An
uninstallable deadline now fails closed as an expired one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
RT-RR-01. An effect or recovery task was registered as retained only after its
public wait expired, so a close() that arrived first saw an empty set and
reported quiescence while the raw task was still running against the authority.
Tasks are now registered when they are created and removed when they settle;
DRAINING keeps its narrower meaning through a separate timed-out set.
RT-RR-02. Admission happened when an event was queued; execution is a second
decision. A queue entry admitted before the stream entered DRAINING no longer
starts running inside it. And an abandoned task may have applied part of its
effect, so the resume token it was based on is discarded and recovery is
required explicitly — the next ordinary event can no longer skip authoritative
recovery on the strength of state a timed-out effect may have invalidated.
RT-RR-03. close() cached the first timeout forever, so a writer that later
settled could never be proved quiescent and the retained registry could never be
pruned. Only an in-flight close is shared now, every writer a close fences is
retained until its tail actually settles, and the tail prunes itself. A second
close therefore converges to success once the writer finishes.
RT-RR-04. Checkpoint work joins writer tails in the physical-task registry from
invocation to settlement and is drained on the same terms.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
R-02: add an OPEN/DRAINING/CLOSED lifecycle orthogonal to freshness. Effect and
recovery authorities are now awaited under a deadline: on expiry the commit
capability is revoked and the work aborted, the caller gets a bounded
non-retryable IDLE_TIMEOUT, and the underlying task is retained rather than
dropped. A draining stream refuses new events and recovery, and close() returns
a Promise that succeeds only once every retained task actually settled,
reporting IDLE_TIMEOUT otherwise.
R-03: a handoff fail-close moves active, probe, quiescing and transition leases
into a retired-writer set before clearing their references, and close() waits on
current and retired writers together, so an abandoned non-cooperative writer can
no longer make teardown report a false success.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>