문제: 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
문서 색인
docs/의 문서를 세 묶음으로 나눈다.
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로
확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
README.md |
시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
architecture/frontend-application-foundation.md |
이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
architecture/layers.md, architecture/overview.md |
계층과 import 방향. check:architecture가 검사한다 |
architecture/starter-experience.md |
기본 라우트, 인증 모드, 기능 추가·제거 절차 |
architecture/optional-adapter-recipes.md |
선택 기능(recipe)을 넣고 빼는 절차 |
operations/ci-quality-gates.md, testing/taxonomy.md |
게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 계약 소유와 호환성:
architecture/contract-ownership.md,contracts/compatibility.md - 정적 배포와 런타임 설정:
architecture/static-delivery.md - 기능 개발자가 알아야 하는 양:
architecture/capability-consumer-experience.md - 운영·복구:
operations/,runbooks/ - 보안과 공급망:
security/browser-boundary.md,security/supply-chain.md - 디자인 토큰과 수동 접근성 검토:
styling/design-tokens.md,accessibility/manual-checklist.md - 버전별 변경:
../CHANGELOG.md
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md |
verify:documentation (FE-GATE-017) |
reviews/adapters/INVENTORY.md |
check:adapter-inventory (FE-GATE-010) |
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json |
check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json) |
2. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본:
architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md - 상태 원장:
architecture/browser-data-capability-completion-ledger.md - 전체 검토와 로드맵:
architecture/frontend-platform-capability-review.md,architecture/frontend-platform-implementation-roadmap.md - 포트·경계·데이터 흐름:
architecture/frontend-ports-adapters-and-boundaries.md,architecture/typescript-state-and-data-flow.md,architecture/routing-pages-and-patterns.md - API와 서버 상태:
architecture/api-contract-schema-mapper-and-server-state.md,architecture/backend-api-and-server-state-contract.md,architecture/protobuf-browser-transport-and-rest-gateway.md - 브라우저 데이터:
architecture/client-cache-and-storage.md,architecture/browser-file-and-origin-storage.md,architecture/presigned-transfer-and-image-cdn.md,architecture/server-file-capability-infrastructure.md - 실시간:
architecture/realtime-events-web-push-and-bounded-polling.md - 디자인 시스템과 테스트 전략:
styling/design-system-platform.md,testing/frontend-platform-testing-strategy.md - 결정 기록(ADR):
architecture/decisions/VD-*.md
3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
superpowers/ |
과거 작업 계획과 스펙 |
reviews/ |
리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다 |
../SPEC.md, ../tasks/ |
2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다 |