<!-- task=m-performance-hotspot-optimization/08_ts_ws_1mb_payload plan=1 tag=REVIEW_PERF_TS_PAYLOAD -->

# TypeScript WS 1MB Payload Follow-up Plan

## 이 파일을 읽는 구현 에이전트에게

이 작업은 이전 code review의 Required 이슈만 좁게 해결한다. 구현 후 active `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 변경 내용과 검증 출력으로 채워야 완료된다. 검증 명령을 실행하고 실제 stdout/stderr 또는 저장된 결과 파일 경로를 기록한 뒤 active 파일을 유지한 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review 스킬 전용이다.

구현 중 사용자만 결정할 수 있는 제품 선택, 사용자 소유 외부 환경, secret, 범위 충돌이 필요하면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 결정, 증거, 실행한 명령/출력, 자동 후속 불가 이유, 재개 조건을 적고 중단한다. 구현 에이전트는 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
  - `ts-ws-1mb`: TypeScript WS 1MB payload 경로를 분석하고 p99 latency 또는 throughput을 개선한다.
- Completion mode: check-on-pass

## 이전 리뷰 요약

- Archived plan: `agent-task/m-performance-hotspot-optimization/08_ts_ws_1mb_payload/plan_cloud_G07_0.log`
- Archived review: `agent-task/m-performance-hotspot-optimization/08_ts_ws_1mb_payload/code_review_cloud_G07_0.log`
- Verdict: FAIL
- Required 이슈:
  - `ReadBuffer.take(0)`가 zero-length control frame에서 빈 버퍼를 처리하지 못한다.
  - receive path 마지막 `new Uint8Array(payload)` copy가 남아 계획된 no-copy 수신 최적화가 완료되지 않았다.
  - TypeScript WS `payload=1MB` p99/throughput 개선이 확인되지 않았고 남은 병목 문서화도 부족하다.

## 구현 체크리스트

- [ ] `ReadBuffer.take(0)`를 안전하게 처리하고, 빈 WS control frame이 연결을 깨지 않는 regression test를 추가한다.
- [ ] TypeScript Node WS receive path의 `new Uint8Array(payload)` full-copy를 제거하고, 1MB WS roundtrip 계약을 유지한다.
- [ ] TypeScript WS `payload=1MB` full row의 p99/throughput 증거를 재기록하고, 개선 또는 남은 병목 원인을 명확히 문서화하며 trailing whitespace를 정리한다.
- [ ] `cd typescript && npm run check && npm test`를 실행한다.
- [ ] `git diff --check -- typescript/src/node_ws_client.ts typescript/test/ws.test.ts`를 실행한다.
- [ ] `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang typescript --transport ws --profile payload`를 실행하고 TypeScript WS `payload=1MB` row의 stability 0 및 p99/throughput 변화를 기록한다.
- [ ] `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick`를 실행해 project performance quick smoke가 회귀 없이 기록되는지 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_PERF_TS_PAYLOAD-1] Zero-length control frame 처리

#### 문제

[typescript/src/node_ws_client.ts](/config/workspace/proto-socket/typescript/src/node_ws_client.ts:108)의 `ReadBuffer.take(len)`는 `len === 0`일 때도 `this.chunks[0]!`를 읽는다. [typescript/src/node_ws_client.ts](/config/workspace/proto-socket/typescript/src/node_ws_client.ts:309)는 모든 frame에서 `take(payloadLength)`를 호출하므로, 정상적인 빈 close/ping frame 수신이 error/terminate로 이어질 수 있다.

#### 해결 방법

- `ReadBuffer.take(0)`가 즉시 `Buffer.alloc(0)` 또는 동등한 empty Buffer를 반환하게 한다.
- 빈 masked ping 또는 close frame 수신 후 연결이 정상적으로 유지/종료되는 테스트를 추가한다.
- 가능하면 raw `net.Socket` handshake test에서 빈 masked ping을 보낸 뒤 pong 수신 또는 후속 binary message 처리를 확인한다.

#### 중간 검증

```bash
cd typescript && npm run check && npm test
```

### [REVIEW_PERF_TS_PAYLOAD-2] receive payload 마지막 copy 제거

#### 문제

[typescript/src/node_ws_client.ts](/config/workspace/proto-socket/typescript/src/node_ws_client.ts:374)는 `Buffer` payload를 `new Uint8Array(payload)`로 다시 감싼다. 이 생성자는 full copy를 만들기 때문에, 이전 plan에서 제거하려던 1MB receive path copy가 남는다.

#### 해결 방법

- `Buffer`는 `Uint8Array`이므로 message event에 payload view를 그대로 넘긴다.
- downstream `NodeWsClient.onMessage`와 `Communicator.onReceivedFrame` 계약이 `Uint8Array` 입력을 그대로 받을 수 있는지 확인한다.
- 기존 1MB WS roundtrip test가 계속 통과해야 한다. 필요한 경우 no-copy 의도가 드러나도록 테스트 이름 또는 검증 주석을 보강한다.

#### 중간 검증

```bash
cd typescript && npm run check && npm test
```

### [REVIEW_PERF_TS_PAYLOAD-3] 1MB 성능 증거와 문서화 정합성

#### 문제

이전 구현 결과 `agent-test/runs/20260605-230744-proto-socket-stress-full.md`의 TypeScript WS `payload=1MB` row는 `32.7 rps / p99 236.456ms`였고, 리뷰 재실행 `agent-test/runs/20260605-232403-proto-socket-stress-full.md`도 `33.1 rps / p99 239.361ms`였다. 이전 full 기준 `agent-test/runs/20260605-115943-proto-socket-performance-full.md`의 `35.8 rps / p99 217.890ms` 대비 p99 또는 throughput 개선이 확인되지 않았다. 또한 `typescript/test/ws.test.ts`에는 trailing whitespace가 남아 `git diff --check`가 실패한다.

#### 해결 방법

- source/test trailing whitespace를 정리한다.
- 위 두 코드 이슈 수정 후 targeted full payload 측정을 다시 실행한다.
- 새 결과 파일에서 TypeScript WS `payload=1MB` row의 throughput/p99/stability 값을 review stub에 기록한다.
- p99 또는 throughput이 같은 host/runtime/profile 기준으로 개선되면 그 수치를 명시한다.
- 개선되지 않으면 남은 병목 후보를 구체적으로 적는다. 예: Node stream write scheduling, masking copy, protobuf encode/decode, communicator queue, benchmark workload 특성 중 실제 코드와 결과로 뒷받침되는 후보만 적는다.

#### 중간 검증

```bash
git diff --check -- typescript/src/node_ws_client.ts typescript/test/ws.test.ts
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang typescript --transport ws --profile payload
```

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `typescript/src/node_ws_client.ts` | REVIEW_PERF_TS_PAYLOAD-1, REVIEW_PERF_TS_PAYLOAD-2 |
| `typescript/test/ws.test.ts` | REVIEW_PERF_TS_PAYLOAD-1, REVIEW_PERF_TS_PAYLOAD-2, REVIEW_PERF_TS_PAYLOAD-3 |
| `agent-task/m-performance-hotspot-optimization/08_ts_ws_1mb_payload/CODE_REVIEW-cloud-G07.md` | REVIEW_PERF_TS_PAYLOAD-3 검증 결과 기록 |

## 최종 검증

```bash
cd typescript && npm run check && npm test
```

기대 결과: 종료 코드 0, TypeScript typecheck PASS, Vitest PASS.

```bash
git diff --check -- typescript/src/node_ws_client.ts typescript/test/ws.test.ts
```

기대 결과: 종료 코드 0.

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang typescript --transport ws --profile payload
```

기대 결과: 결과 기록 파일 생성, TypeScript WS payload rows PASS, `payload=1MB` row stability counters all 0, p99 또는 throughput 개선 여부와 남은 병목 문서화.

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
```

기대 결과: performance quick 결과 기록 파일 생성, same-language/cross-language/typescript-gateway 구성요소가 실행 범위에 포함되고 새 TypeScript 변경으로 인한 stability FAIL 없음.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
