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

## 목표

야간 대용량 패킷 기준선에서 병목이 유지되는 row를 근거로, 64KB/1MB WebSocket 및 병렬 전송 성능을 추가 개선한다. TypeScript WS 1MB, TypeScript TCP 1024-client tail, Kotlin TCP parallel required skip 해제, Dart large-packet guard, WS fixed latency 경로 분리까지 완료 근거를 반영했다.

## 단계

안정화와 유지

## 상태

[완료]

## 승격 조건

- 사용자 요청에 따라 활성 후보 창에서 `[진행중]`으로 전환했다.
- 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, TypeScript TCP 1024-client 병렬 tail timeout, Kotlin TCP parallel required skip 해제는 완료 반영된 후보로 둔다.
- WS 계열 fixed latency는 Kotlin WS same-language 수신 plateau와 TypeScript gateway worker_threads tail의 별도 경로로 분리 분석 완료했다.
- Kotlin WS 1MB는 야간 record에서 안정성 유지가 확인되어 이번 후보 창에서는 별도 구현 대상으로 승격하지 않는다.
- 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`.
- [x] [ws-fixed-latency-path] WS 계열 fixed latency가 야간에도 유지되면 transport별 공통 지연 경로와 언어별 worker/gateway path를 분리해 분석한다. 완료 근거: `agent-task/archive/2026/06/m-large-payload-followup-optimization/04_ws_fixed_latency_1/complete.log`; 검증: `agent-test/runs/20260614-224355-proto-socket-stress-quick.md`, `agent-test/runs/20260614-224424-proto-socket-stress-quick.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 없이 유지되어 이번 후보 창에서는 별도 구현 대상으로 승격하지 않는다.
- [x] [dart-large-packet-guard] Dart TCP/WS 1MB는 기존 개선이 유지되는지 감시하고, 회귀가 보이면 guard 또는 path hardening 대상으로 승격한다. 검증: `agent-test/runs/20260614-123328-proto-socket-performance-full.md`에서 Dart TCP 1MB p99 `140.565ms`, throughput `56.4rps`, Dart WS 1MB p99 `149.095ms`, throughput `52.4rps`, timeout/nonce/type/FIFO/pending/queue/gateway violations 0으로 PASS라 별도 guard/hardening 구현 대상으로 승격하지 않는다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-15
- 완료 근거:
  - TypeScript WS 1MB, TypeScript TCP 1024 tail, Kotlin TCP parallel, Dart large-packet guard 완료 근거가 모두 반영됐다.
  - WS fixed latency는 `agent-task/archive/2026/06/m-large-payload-followup-optimization/04_ws_fixed_latency_1/complete.log`에서 Kotlin WS same-language 수신 plateau와 TypeScript gateway worker_threads tail로 분리 완료됐다.
  - 모든 기능 Task와 Task 내부 검증 근거가 `[x]` 상태로 정리됐다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-15 사용자 요청으로 현재 마일스톤 완료 및 다음 마일스톤 지정.

## 범위 제외

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

## 작업 컨텍스트

- 관련 경로: `agent-roadmap/archive/phase/stability-maintenance/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`
- 선행 작업: `야간 대용량 패킷 성능 기준선` 완료.
- 완료된 구현 대상: TypeScript WS 1MB, TypeScript TCP 1024-client 병렬 timeout tail, Kotlin TCP parallel clients>=128 required skip 해제, Dart TCP/WS 1MB large-packet guard, WS fixed latency 경로 분리.
- 남은 후보: 없음. WS fixed latency 분석에서 후속 구현 후보로 Kotlin WS same-language 수신 staging plateau와 TypeScript gateway worker_threads dispatch tail을 별도 후보로 분리했다.
- 제외/감시: Kotlin WS 1MB는 야간 record에서 안정성 유지가 확인되어 이번 후보 창에서는 별도 구현 대상으로 승격하지 않는다. Dart TCP/WS 1MB는 2026-06-14/15 야간 full record에서 stability PASS가 확인되어 별도 구현 대상으로 승격하지 않는다. 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로 작성했다. 이 Milestone은 완료되었으며, 추가 구현은 사용자 확인 후 새 Milestone 또는 별도 follow-up 작업으로 분리한다.