<!-- task=01+browser_native_ws plan=2 tag=REVIEW_REVIEW_BNW -->

# Code Review Reference - REVIEW_REVIEW_BNW

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Do not modify or check the `코드리뷰 전용 체크리스트`; it is owned by the review agent only.
> Follow the ownership table at the bottom of this file for which sections you own.

## 개요

date=2026-05-20
task=01+browser_native_ws, plan=2, tag=REVIEW_REVIEW_BNW

## 이 파일을 읽는 리뷰 에이전트에게

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
Review 완료 후 반드시 아래 순서로 아카이브하세요.

1. `CODE_REVIEW-cloud-G08.md` → `code_review_cloud_G08_N.log` (N = 기존 code_review_*.log 수)
2. `PLAN-cloud-G08.md` → `plan_cloud_G08_M.log` (M = 기존 plan_*.log 수)
3. PASS인 경우 `complete.log` 작성 후 `agent-task/archive/YYYY/MM/01+browser_native_ws/`로 task 디렉터리 이동. WARN/FAIL인 경우 새 routed plan + review 스텁 작성.

어떤 판정에서도 아카이브를 건너뛰지 마세요. PASS/WARN/FAIL 모두 `코드리뷰 결과` append 후 active plan/review 파일을 먼저 아카이브하고, 그 다음 `complete.log` 또는 다음 plan/review 파일을 작성해야 합니다.
PASS에서는 `agent-ops/skills/common/code-review/templates/complete-log-template.md`의 섹션 순서와 필수 항목을 기준으로 `complete.log`를 작성하세요. 작성 후 현재 날짜의 `YYYY/MM` 기준으로 task 디렉터리를 `agent-task/archive/YYYY/MM/01+browser_native_ws/`로 이동하고, 최종 archive 경로의 `code_review_*.log`에서 `코드리뷰 전용 체크리스트`를 갱신한 다음 보고하세요.
WARN/FAIL에서는 다음 상태 파일 작성 후 현재 task 경로의 archived `code_review_*.log`에서 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 체크한 다음 보고하세요.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_REVIEW_BNW-1] `REVIEW_BNW` 후속 구현의 review 문서와 검증 출력 기록을 완성한다. | [x] |

## 구현 체크리스트

- [x] [REVIEW_REVIEW_BNW-1] `REVIEW_BNW` 후속 구현의 review 문서와 검증 출력 기록을 완성한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G08_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G08_M.log`로 아카이브한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 `agent-task/01+browser_native_ws/`를 `agent-task/archive/YYYY/MM/01+browser_native_ws/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] WARN/FAIL이면 다음 active `PLAN-cloud-G08.md`와 `CODE_REVIEW-cloud-G08.md`를 작성하고 `complete.log`를 작성하지 않는다.

## 계획 대비 변경 사항

없음. 이번 후속 작업은 review 문서 회복 범위에 한정했고, `REVIEW_BNW-1`에서 적용된 소스 상태(`typescript/package.json`, `typescript/package-lock.json`, `typescript/README.md`)가 plan 요구 조건을 이미 만족함을 검증으로 확인하여 소스 추가 변경 없이 review 문서와 검증 출력만 기록했다.

## 주요 설계 결정

- `ws`를 root `dependencies`가 아닌 optional `peerDependencies`(+ `peerDependenciesMeta.ws.optional = true`)로 선언한다. Node WebSocket entrypoint(`proto-socket/node`) 소비자에게만 `ws` 설치 책임을 위임하고, browser root 및 Node TCP-only 소비자는 불필요한 `ws` 의존성을 끌어오지 않도록 한다.
- 로컬 테스트(`test/ws.test.ts` 등) 실행을 위해 `devDependencies.ws`는 `^8.18.1`로 유지한다.
- `typescript/README.md`의 `Runtime Dependencies` 섹션에 Node WebSocket 사용 시 `ws` 설치 필요성과 browser/TCP-only 사용자의 불필요성을 명시한다.
- root/browser entrypoint(`typescript/src/index.ts`, `typescript/src/browser_ws_client.ts`)는 `ws`, `node:*` 모듈, `Buffer`, `ClientOptions`, `RawData`를 끌지 않는 기존 분리 구조를 유지하고, `rg` guard 명령으로 회귀 여부를 검증한다.

## 리뷰어를 위한 체크포인트

- active `CODE_REVIEW-cloud-G08.md`의 구현 항목별 완료 여부와 구현 체크리스트가 실제 상태에 맞게 체크됐는지 확인한다.
- `계획 대비 변경 사항`과 `주요 설계 결정`에 placeholder가 남아 있지 않은지 확인한다.
- `검증 결과`에 고정 명령의 실제 stdout/stderr가 붙어 있고 코드 상태와 일치하는지 확인한다.
- `typescript/package.json`과 `typescript/package-lock.json`이 `ws`를 optional peer dependency와 테스트용 devDependency로 반영하는지 확인한다.
- `typescript/README.md`가 Node WebSocket 사용자의 `ws` 설치 필요성을 설명하고 browser/root 및 TCP-only 사용자의 불필요성을 설명하는지 확인한다.
- root/browser entrypoint가 여전히 `ws`, `node:*`, `Buffer`를 import하지 않는지 확인한다.

## 검증 결과

_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._

필수 규칙:
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.

### REVIEW_REVIEW_BNW-1 중간 검증
```
$ cd typescript && node -e "const fs=require('fs'); const p=JSON.parse(fs.readFileSync('package.json','utf8')); if (p.dependencies?.ws) throw new Error('ws must not be a root dependency'); if (p.devDependencies?.ws !== '^8.18.1') throw new Error('ws devDependency missing'); if (p.peerDependencies?.ws !== '^8.18.1') throw new Error('ws peerDependency missing'); if (p.peerDependenciesMeta?.ws?.optional !== true) throw new Error('ws peerDependency must be optional');"
(no output; exit code 0)
```

### 최종 검증
```
$ cd typescript && npm run check

> proto-socket@1.0.5 check
> tsc --noEmit

(exit code 0)
```

```
$ cd typescript && npm test

> proto-socket@1.0.5 test
> vitest run


 RUN  v3.2.4 /config/workspace/proto-socket/typescript

 ✓ test/base_client.test.ts (7 tests) 8ms
 ✓ test/communicator.test.ts (10 tests) 19ms
 ✓ test/browser_ws_client.test.ts (6 tests) 17ms
 ✓ test/tcp.test.ts (5 tests) 49ms
 ✓ test/ws.test.ts (5 tests) 56ms

 Test Files  5 passed (5)
      Tests  33 passed (33)
   Start at  06:10:16
   Duration  540ms (transform 355ms, setup 0ms, collect 964ms, tests 149ms, environment 0ms, prepare 503ms)

(exit code 0)
```

```
$ cd go && go run ./crosstest/go_typescript.go
INFO typeName go=TestData
INFO typeName ts=TestData
SERVER_RECEIVED index=101 message=fire from typescript client
PASS scenario=1 detail=fire-and-forget sent
PASS scenario=2 detail=received push from go server
INFO typeName ts=TestData
PASS scenario=3 detail=single request response matched
PASS scenario=4 detail=concurrent request responses matched
INFO typeName ts=TestData
SERVER_RECEIVED index=101 message=fire from typescript client
PASS scenario=1 detail=fire-and-forget sent
PASS scenario=2 detail=received push from go server
INFO typeName ts=TestData
PASS scenario=3 detail=single request response matched
PASS scenario=4 detail=concurrent request responses matched
INFO typeName ts=TestData
SERVER_RECEIVED index=101 message=fire from typescript client
PASS scenario=1 detail=fire-and-forget sent
PASS scenario=2 detail=received push from go server
INFO typeName ts=TestData
PASS scenario=3 detail=single request response matched
PASS scenario=4 detail=concurrent request responses matched
INFO typeName ts=TestData
SERVER_RECEIVED index=101 message=fire from typescript client
PASS scenario=1 detail=fire-and-forget sent
PASS scenario=2 detail=received push from go server
INFO typeName ts=TestData
PASS scenario=3 detail=single request response matched
PASS scenario=4 detail=concurrent request responses matched
PASS all go-server/typescript-client crosstests passed
(exit code 0)
```

```
$ rg --sort path -n 'from "ws"|node:|\bBuffer\b|ClientOptions|RawData' typescript/src/index.ts typescript/src/browser_ws_client.ts
(no output; exit code 1)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave the review-agent-only checklist unchanged.

## 코드리뷰 결과

### 2026-05-20 cloud-G08

- 종합 판정: PASS

#### 차원별 평가

| 차원 | 평가 | 근거 |
|------|------|------|
| Correctness | Pass | 후속 범위인 review 문서 회복이 완료됐고, `ws` runtime 계약은 optional peer + devDependency + README 안내로 실제 소스와 일치한다. |
| Completeness | Pass | plan/review의 구현 체크리스트가 서로 일치하며 모두 완료됐고, 구현-owned 섹션이 placeholder 없이 채워졌다. |
| Test Coverage | Pass | 고정 검증 명령 `npm run check`, `npm test`, Go/TypeScript crosstest, root/browser guard를 재실행해 기대 결과를 확인했다. |
| API Contract | Pass | `typescript/package.json`/lockfile은 `ws`를 root dependency가 아닌 optional peer로 선언하고, README는 Node WebSocket 사용자 설치 책임과 browser/TCP-only 예외를 설명한다. |
| Code Quality | Pass | 후속 작업은 task 문서 기록 회복으로 좁게 수행됐고, 추가 소스 변경 없이 기존 구현 상태를 검증했다. |
| Plan Deviation | Pass | 계획된 문서 회복과 검증 출력 기록 범위를 벗어난 변경이 없다. |
| Verification Trust | Pass | active review 파일의 기록과 재실행한 명령 출력이 일치한다. |

#### 발견된 문제

- 없음

#### 다음 단계

- PASS: active plan/review를 아카이브하고 complete.log 작성 후 task 디렉터리를 archive로 이동한다.
