proto-socket/agent-roadmap/milestones/large-payload-followup-optimization.md

# 대용량 WS/병렬 전송 후속 최적화

## 목표

야간 대용량 패킷 기준선에서 병목이 유지되는 row를 근거로, 64KB/1MB WebSocket 및 병렬 전송 성능을 추가 개선한다. 기준선 수집 전에는 구현하지 않고, 후보 범위와 판정 기준을 계획 상태에서 잠금으로 유지한다.

## 단계

안정화와 유지

## 상태

[진행중]

## 승격 조건

- 사용자 요청에 따라 활성 후보 창에서 `[진행중]`으로 전환했다.
- 2026-06-10 야간 focused payload record 2회를 근거로 1차 구현 대상을 TypeScript WS 1MB로 좁혔다.
- 성공 기준은 같은 host/runtime/profile의 focused 또는 quick record에서 stability hard gate 0을 유지하면서 TypeScript WS 1MB p99/throughput의 개선 방향을 확인하는 것으로 둔다. Go/Python reference 대비 위치는 참고값으로만 본다.

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- 야간 기준선에서 재현되는 병목 row만 구현 대상으로 삼는다.
- TypeScript WS 1MB, WS 계열 fixed latency, TypeScript TCP 1024-client 병렬 tail timeout, Kotlin TCP parallel required skip 해제, Kotlin WS 1MB, Dart large-packet 회귀 방지를 우선 후보로 둔다.
- stability hard gate는 timeout, nonce mismatch, response type mismatch, FIFO violation, pending leak, queue/gateway backlog leak 0을 유지한다.
- 성능 개선은 cross-language matrix와 focused payload/stress record로 검증한다. 야간 full record 완료를 막는 same-language hard gate 실패는 focused stress로 먼저 좁힌 뒤 full record에서 재확인한다.

## 기능

### Epic: [evidence-selection] 기준선 기반 후보 선정

야간 record로 실제 구현 대상을 좁힌다.

- [x] [night-evidence-review] 야간 focused record에서 64KB/1MB TCP/WS rows를 비교해 병목이 남은 row를 분류한다. 검증: `agent-test/runs/20260610-124006-proto-socket-stress-full.md`와 `agent-test/runs/20260610-131132-proto-socket-stress-full.md`만 구현 대상 선정 근거로 사용했고, 주간 exploratory record는 구현 대상 선정 근거에서 제외했다.
- [x] [primary-target] 1차 개선 대상 row와 제외 대상을 정한다. 검증: TypeScript WS 1MB는 p99 `226.008ms -> 237.395ms`, throughput `33.5rps -> 33.3rps`, memory `193.3MB -> 179.7MB`, stability violations 0으로 반복 재현되어 1차 개선 대상으로 선택했다. TypeScript TCP 1MB, Go/Python 1MB rows는 reference로 두고, Kotlin WS 1MB와 Dart TCP/WS 1MB는 watchlist로 남긴다.
- [x] [night-full-hard-gate-review] 야간 full wrapper에서 baseline 완료를 막는 same-language hard gate 실패를 분류한다. 검증: `agent-test/runs/20260613-141506-proto-socket-stress-full.md`에서 TypeScript TCP `parallel clients=1024`가 requests `511908/512000`, timeout `92`, nonce/type/FIFO/pending/queue/gateway violations 0으로 FAIL했고, Kotlin TCP `parallel clients>=128`은 기존 required skip으로 남았다. `agent-test/runs/20260613-202101-proto-socket-stress-full-cross.md`와 `agent-test/runs/20260613-202744-proto-socket-stress-full.md`는 PASS라 cross-language/gateway 결함과 분리한다.

### Epic: [candidate-paths] 최적화 후보 경로

후보별로 구현 위험과 검증 방법을 분리한다.

- [x] [typescript-ws-1mb-path] TypeScript WS 1MB 병목이 야간에도 유지되면 mask/protobuf/parse queue 경로를 우선 분석한다. 완료 근거: `agent-task/archive/2026/06/m-large-payload-followup-optimization/01_typescript_ws_1mb/complete.log`; 검증: `npm run check`, `npm test -- test/ws.test.ts test/communicator.test.ts`, `run_stress.sh --full --lang typescript --transport ws --profile payload`, `agent-test/runs/20260613-220314-proto-socket-stress-full.md`.
- [x] [typescript-tcp-1024-tail-path] TypeScript TCP `parallel clients=1024` timeout tail을 focused stress로 재현하고, write queue 대기, socket write/drain, read parse queue, request timeout 시작점 중 어느 경로가 15초 hard gate를 넘기는지 계측한 뒤 transport/communicator 수정 계획을 작성한다. 완료 근거: `agent-task/archive/2026/06/m-large-payload-followup-optimization/02_typescript_tcp_tail/complete.log`; 검증: `agent-test/runs/20260614-072352-proto-socket-stress-full.md`, `agent-test/runs/20260614-072436-proto-socket-performance-quick.md`.
- [x] [kotlin-tcp-parallel-unskip-path] Kotlin TCP `parallel clients>=128` required skip을 해제하기 위해 blocking read thread-per-connection 병목과 bounded read timeout 부재를 분리 분석하고, 128 -> 512 -> 1024 순서로 측정 가능하게 만드는 수정 계획을 작성한다. 완료 근거: `agent-task/archive/2026/06/m-large-payload-followup-optimization/03_kotlin_tcp_parallel/complete.log`; 검증: `cd kotlin && ./gradlew --offline test`, `run_stress.sh --full --lang kotlin --transport tcp --profile parallel`, `agent-test/runs/20260614-082714-proto-socket-stress-full.md`.
- [ ] [ws-fixed-latency-path] WS 계열 fixed latency가 야간에도 유지되면 transport별 공통 지연 경로와 언어별 worker/gateway path를 분리해 분석한다. 구현 계획: `agent-task/m-large-payload-followup-optimization/04_ws_fixed_latency/PLAN-cloud-G07.md`
- [x] [kotlin-ws-guard] Kotlin WS 1MB는 야간 record에서 개선 유지 여부를 확인하고, 회귀가 보이면 별도 구현 대상으로 승격한다. 검증: `agent-test/runs/20260610-124006-proto-socket-stress-full.md`, `agent-test/runs/20260610-131132-proto-socket-stress-full.md`, `agent-test/runs/20260613-141506-proto-socket-stress-full.md`의 Kotlin WS 1MB rows가 모두 stability PASS이고 queue/backlog leak 없이 유지되어 이번 후보 창에서는 별도 구현 대상으로 승격하지 않는다.
- [ ] [dart-large-packet-guard] Dart TCP/WS 1MB는 기존 개선이 유지되는지 감시하고, 회귀가 보이면 guard 또는 path hardening 대상으로 승격한다. 구현 계획: `agent-task/m-large-payload-followup-optimization/05_dart_large_packet_guard/PLAN-local-G05.md`

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- 야간 기준선 없이 코드 최적화에 들어가지 않는다.
- C#/Swift 포팅, package registry release, 외부 CI/CD runner 연결은 포함하지 않는다.
- Go/Python reference path를 불필요하게 변경하지 않는다.

## 작업 컨텍스트

- 관련 경로: `agent-roadmap/milestones/nightly-large-payload-baseline.md`, `agent-test/local/proto-socket-performance-baseline.md`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`
- 선행 작업: `야간 대용량 패킷 성능 기준선`
- 1차 구현 대상: TypeScript WS 1MB.
- 추가 hard gate 후보: TypeScript TCP 1024-client 병렬 timeout tail, Kotlin TCP parallel clients>=128 required skip 해제.
- 1차 제외/감시: Kotlin WS 1MB와 Dart TCP/WS 1MB는 watchlist, Go/Python 1MB와 TypeScript TCP 1MB payload rows는 reference/비교 대상으로 둔다.
- 성공 기준: stability hard gate 0을 유지하고, 같은 host/runtime/profile의 focused 또는 quick record에서 대상 row의 p99/throughput이 개선 방향을 보이는지 기록한다. 절대값 고정 합격선은 두지 않는다.
- 구현 계획 작성 기준: `candidate-paths`의 큰 작업은 `agent-task/m-large-payload-followup-optimization/` 아래 split task로 작성한다. TypeScript TCP 1024 tail, Kotlin TCP parallel unskip, WS fixed latency, Dart guard는 원인과 위험이 달라 독립 plan으로 유지한다.