<!-- task=m-large-payload-followup-optimization plan=1 tag=REVIEW_PERF -->

# Plan - REVIEW_PERF

## 개요

date=2026-06-11
task=m-large-payload-followup-optimization, plan=1, tag=REVIEW_PERF

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/large-payload-followup-optimization.md`
- Task ids:
  - `typescript-ws-1mb-path`: TypeScript WS 1MB 병목이 야간에도 유지되면 mask/protobuf/parse queue 경로를 우선 분석한다.
- Completion mode: check-on-pass

## 구현 에이전트 지시

이 plan은 이전 리뷰의 Required 이슈 하나만 해결한다. 사용자에게 직접 질문하지 말고, 사용자 결정이 필요한 경우 `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청`에 기록한다.

## 이전 리뷰 요약

- Archived plan: `agent-task/m-large-payload-followup-optimization/plan_local_G06_0.log`
- Archived review: `agent-task/m-large-payload-followup-optimization/code_review_cloud_G06_0.log`
- Verdict: FAIL
- Required issue: TypeScript WS 1MB 최적화 작업인데 검증 출력은 quick payload의 1KB/64KB row만 포함했다. `run_stress.sh` 계약상 1MB는 full payload에서만 실행되므로 1MB hot path 검증 증거가 없다.

## 범위 결정 근거

- 포함: 기존 `typescript/src/node_ws_client.ts` 변경에 대해 TypeScript/ws `payload=1MB` row가 포함되는 검증 증거를 복구한다.
- 제외: 별도 성능 목표값 확정, 다른 언어 최적화, browser WebSocket 변경, 로드맵 상태 갱신.
- 소스 변경은 기본적으로 하지 않는다. 다만 full payload 실행에서 현재 변경이 직접 유발한 correctness/stability 실패가 재현되면, 그 실패를 고치는 최소 TypeScript 변경은 허용한다.

## 구현 체크리스트

- [ ] `npm --prefix typescript run check`를 실행해 현재 TypeScript 타입 계약을 확인한다.
- [ ] `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 violations, throughput, p99, peak memory, 결과 record 경로를 기록한다.
- [ ] full payload 명령이 실패하거나 1MB row를 생성하지 못하면 quick 결과로 대체하지 말고, 실제 stdout/stderr와 실패 사유를 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 검증 출력과 판단으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [REVIEW_PERF-1] TypeScript WS 1MB 검증 증거 복구

### 문제

이전 리뷰 파일은 `run_stress.sh --quick --lang typescript --transport ws --profile payload` 결과를 TypeScript WS payload 검증으로 기록했다. 그러나 해당 출력은 `sizes=1KB,64KB`와 `rows=2`만 포함한다. 이번 작업의 핵심 판단 대상은 1MB receive unmask hot path이므로 1MB row 없이 PASS 처리할 수 없다.

### 해결 방법

1MB row가 포함되는 full payload 명령을 실행하고, 결과 record에서 TypeScript/ws `payload=1MB` row를 확인한다.

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

기대 결과:

- 전체 결과값 PASS.
- TypeScript/ws `payload=1MB` row 존재.
- timeout, nonce mismatch, response type mismatch, FIFO violation, pending leak, queue/gateway backlog leak가 모두 0.
- throughput, p99, peak memory가 결과 record에 남는다.

### 수정 파일 및 체크리스트

- [ ] `CODE_REVIEW-local-G07.md`: 실제 full payload stdout/stderr와 결과 record 경로를 기록한다.
- [ ] `typescript/src/node_ws_client.ts`: full payload에서 현재 변경이 직접 유발한 correctness/stability 실패가 확인될 때만 최소 수정한다.

### 테스트 작성

- 새 단위 테스트는 기본값으로 작성하지 않는다. 기존 `typescript/test/ws.test.ts`에는 1MB WS roundtrip과 fragmented large binary frame 회귀 테스트가 이미 있다.
- full payload에서 mask correctness나 fragmentation 문제가 드러난 경우에만 focused unit test를 추가한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `CODE_REVIEW-local-G07.md` | REVIEW_PERF-1 |
| `typescript/src/node_ws_client.ts` | REVIEW_PERF-1, 필요 시 |

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

- 검증 출력이 quick이 아니라 full payload이며, TypeScript/ws `payload=1MB` row를 실제로 포함하는지 확인한다.
- 1MB row의 stability hard gate가 모두 0인지 확인한다.
- 소스 변경이 추가됐다면 기존 in-place unmask 안전성, Buffer aliasing, fragmentation 처리가 유지되는지 확인한다.
- quick 결과나 이전 야간 record를 새 full payload 실행의 대체 근거로 쓰지 않았는지 확인한다.

## 최종 검증

```bash
npm --prefix typescript run check
```

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

기대 결과: 두 명령 모두 exit code 0. full payload 결과 record에 TypeScript/ws `payload=1MB` row가 있으며 stability violations 0이다.
