toki/proto-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update performance-hotspot-optimization roadmap and add task archive

Browse source
This commit is contained in:
toki 2026-06-04 15:50:06 +09:00
parent 3a7e41861d
commit 6ba2b3f1c0
6 changed files with 745 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
agent-roadmap/milestones/performance-hotspot-optimization.md
View file

@ -43,7 +43,7 @@ idle 상태에서 성능 기준점을 다시 찍고, 개선 전후 비교 기준
기존 결과와 idle baseline을 비교해 언어별 병목 우선순위를 확정한다.
- [ ] [hotspot-report] Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리한다. 검증: 각 병목 후보에 근거 결과 파일, 대상 row, p99/throughput/memory 수치, 개선 전 기준값이 기록된다.
- [ ] [fast-path-ref] Go/Python 결과를 reference fast path로 정리해 다른 언어 경로와 비교한다. 검증: Go/Python concurrency 256 및 1MB payload rows가 같은 표에 포함되고, Go/Python은 최우선 런타임 최적화 대상이 아니라 기준점 보강 대상으로 분류된다.
- [x] [fast-path-ref] Go/Python 결과를 reference fast path로 정리해 다른 언어 경로와 비교한다. 검증: Go/Python concurrency 256 및 1MB payload rows가 같은 표에 포함되고, Go/Python은 최우선 런타임 최적화 대상이 아니라 기준점 보강 대상으로 분류된다.
### Epic: [go-reference] Go reference 기준점 보강
@ -164,6 +164,34 @@ Kotlin TCP는 현재 same-language 기준에서 안정적인 유지 대상이다
## 작업 컨텍스트
- 병목 리포트:
> [!WARNING]
> **Full Idle Baseline 부재**: 성능/스트레스 측정을 위한 최상위 통제 환경(Idle Host)에서의 Full Baseline(`run_performance.sh --full`) 결과가 아직 수집되지 않았습니다. 현재 기록된 개선 전 기준값들은 기존 local/remote 환경에서의 stress-full/quick 테스트 실행 결과(`agent-test/runs/*`)를 토대로 취합한 임시 기준입니다. `[idle-full]` 및 `[compare-rule]` 작업이 완료되어 전용 Baseline record가 남겨지기 전까지는 이 값들을 잠정적인 비교 기준으로 사용합니다.
### 1. 언어별 병목 후보 및 개선 목표
| 병목 후보 | 근거 파일 / 대상 Row | 개선 전 기준값 (p99 / Throughput / Memory) | 판정 및 병목 의존성 | 후속 Task ID |
|---|---|---|---|---|
| **Dart TCP**<br>(Fixed Latency, Burst, Sustained) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Sustained 30분 | - Concurrency 256 p99: **49.109ms**<br>- Burst 100k: **154.4 rps**<br>- Sustained throughput: **385.3 rps** / p99: **44.079ms** | `tcpNoDelay` 미설정 의심, per-packet `flush()`, write serialization, heartbeat timer churn, stream pause/resume 오버헤드 존재. | `dart-tcp-fixed-latency`<br>`dart-tcp-burst-sustained`<br>`dart-heartbeat-cost` |
| **Dart TCP 1MB**<br>(Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Payload 1MB | - Throughput: **9.6 rps**<br>- p99: **892.819ms** | 대형 payload 전송 시 write/read buffer copy 비용 극대화. `_socket.add` 및 sublist 비용 최적화 필요. | `dart-tcp-buffer-copy`<br>`dart-tcp-1mb` |
| **Dart Isolate Gateway**<br>(Path Hardening) | `dart/lib/src/inbound_gateway_io.dart` 및 `test/communicator_test.dart` | - 성능 Matrix 미연결 (테스트 전용) | 현재 수신 gateway가 메인 transport에 연결되어 있지 않음. `dart-app-core` 대비 동등 이상 신뢰성/라이프사이클 확보, `TransferableTypedData` 사용 및 FIFO, backpressure 구현 필요. | `dart-isolate-equal-or-better`<br>`dart-isolate-real-path`<br>`dart-isolate-backpressure`<br>`dart-isolate-error-ordering`<br>`dart-isolate-large-payload-transfer`<br>`dart-isolate-cleanup` |
| **TypeScript WS 1MB**<br>(Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Payload 1MB | - p99: **228.648ms** | 대용량 WebSocket 프레임 전송/수신 처리량 저하 및 지연 병목. | `ts-ws-1mb` |
| **TypeScript Gateway**<br>(Worker Overhead) | [stress-full (20260603-gateway)](file:///config/workspace/proto-socket/agent-test/runs/20260603-080241-proto-socket-stress-full.md)<br>- Gateway transport=ws concurrency=16<br>- Gateway transport=tcp concurrency=16 | - WS Gateway: **2499.3 rps** (vs Control: **16242.7 rps**)<br>- WS Gateway p99: **205.654ms** (vs Control: **1.887ms**)<br>- TCP Gateway p99: **193.306ms** (vs Control: **43.095ms**) | `worker_threads` 기반 frame offload hop 비용, buffer copy, reorder wait로 인해 심각한 병목 유발. worker hop 제거 또는 단일 수신 경로로 재설계 필수. | `ts-gateway-single-path`<br>`ts-worker-hop-removal`<br>`gateway-overhead` |
| **Kotlin WS**<br>(Fixed Latency, Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Concurrency 256<br>- WS Payload 1KB / 1MB | - Concurrency 256 p99: **44.877ms**<br>- Payload 1KB p99: **42.651ms**<br>- Payload 1MB p99: **133.842ms**<br>- Payload 1MB Heap Peak: **~668.3MB** | OkHttp 콜백, ByteString copy, Channel staging, inbound queue, write/send flush 지연 의심. 대용량 payload 시 JVM allocation/GC 유발 가능성. | `kotlin-ws-delay`<br>`kotlin-large-payload-memory` |
| **Kotlin slow-mix**<br>(검증 모델 보정) | [stress-quick (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-035352-proto-socket-stress-quick.md)<br>- slow-mix deferred | - 검증 결과: **Deferred** | TCP는 delayed-ACK latency-bound로 request/response concurrency 안정성 timeout 가능성이 있고, WS는 Dispatchers.IO launch-per-frame 수신 경로가 burst/mixed slow handler에서 per-connection FIFO를 깨는 deferred 사유로 기록됨. | `kotlin-slow-mix-model` |
### 2. Reference Fast Path (비교 및 감시 기준)
> [!NOTE]
> Go 및 Python은 최우선 런타임 최적화 대상이 아닙니다. 아래 reference 수치는 타 언어의 성능 개선 시 대조군 및 regression 감시 기준으로만 사용됩니다.
| 언어 및 Reference 유형 | 근거 파일 / 대상 Row | 성능 지표 (p99 / Throughput / Memory) | 비고 및 보강 Task | 후속 Task ID |
|---|---|---|---|---|
| **Go TCP / WS**<br>(Reference Fast Path) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>- WS Concurrency 256<br>- TCP Payload 1MB<br>- WS Payload 1MB<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Parallel 1024<br>- TCP Sustained 30분 | - TCP 256: **60748.4 rps** / p99 **4.432ms**<br>- WS 256: **62631.5 rps** / p99 **4.872ms**<br>- 1MB p99: **21.076ms** (TCP) / **35.880ms** (WS)<br>- Burst 100k: **201132.8 rps**<br>- Parallel 1024: **214665.2 rps** / p99 **154.621ms**<br>- Sustained throughput: **16264.9 rps** / p99 **0.646ms**<br>- Sustained Memory (30초/5분/30분): **57.1MB / 143.4MB / 794.1MB** | 30분 sustained memory 증가 원인이 leak인지 bench latency sample 누적 artifact인지 검증 필요. | `go-sustained-memory-metric`<br>`go-reference-guard` |
| **Go slow-mix**<br>(검증 모델 보정) | [stress-quick (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-035342-proto-socket-stress-quick.md)<br>- slow-mix deferred | - 검증 결과: **Deferred** | concurrent `SendRequestTyped` 완료 순서가 goroutine scheduling에 의존해 deferred 발생. 검증 helper/기준 보완. | `go-slow-mix-model` |
| **Python TCP / WS**<br>(Reference Medium Path) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>- WS Concurrency 256<br>- TCP Payload 1MB<br>- WS Payload 1MB<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Parallel (128/512/1024)<br>- Sustained Memory (30초/5분/30분) | - TCP 256: **10396.7 rps** / p99 **26.480ms**<br>- WS 256: **7790.6 rps** / p99 **29.769ms**<br>- 1MB p99: **18.856ms** (TCP) / **47.424ms** (WS)<br>- Parallel p99: **93.378ms** (128) / **501.368ms** (512) / **1288.999ms** (1024)<br>- Sustained Memory: **133.8MB / 181.1MB / 614.5MB** | 안정적인 중간 reference. 고동시성 p99 비용 정리 및 sustained memory leak/artifact 분리. gateway 관련 API 정책(사용자 옵션 배제) 정리. | `python-high-parallel-p99`<br>`python-sustained-memory-metric`<br>`python-gateway-api-policy`<br>`python-reference-guard` |
- 관련 경로: `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`, `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`
- 선행 작업: 고성능 병렬 운용 기준선과 최적화
- 후속 작업: 릴리즈 준비 또는 사용처별 성능 요구가 생길 때 package/runtime 정책 정리
@ -188,4 +216,6 @@ Kotlin TCP는 현재 same-language 기준에서 안정적인 유지 대상이다
- `agent-test/runs/20260603-080241-proto-socket-stress-full.md`는 TypeScript gateway full 결과에서 legacy inline control row가 WS throughput 약 `16242.7 rps`, p99 약 `1.887ms`였고, 현재 `worker_threads` gateway row는 throughput 약 `2499.3 rps`, p99 약 `205.654ms`로 악화되어 TypeScript worker-hop hardening 필요 근거가 되었다. TCP gateway row도 p99 약 `193.306ms`로 legacy inline control row p99 약 `43.095ms`보다 크게 나빴다. 이 수치는 gateway 비활성화 결론이 아니라, TypeScript mandatory receive path에서 `worker_threads` per-frame offload를 제거하거나 재설계해야 하는 overhead 기준이다.
- `agent-test/runs/20260603-092819-proto-socket-performance-quick.md`는 현재 HEAD `4dbeecf`에서 성능 전용 quick 표준이 same-language, cross-language, TypeScript gateway 구성요소를 모두 PASS로 aggregate 기록했다.
- `agent-test/runs/20260603-095712-proto-socket-performance-quick.md`는 baseline 비교 경로가 `compared rows: 90`, `missing baseline rows: 0`, `warning rows: 0`으로 동작함을 확인했다.
- 즉시 처리:
- [fast-path-ref] Go/Python reference fast path 분류는 `agent-test/runs/20260603-062724-proto-socket-stress-full.md`의 concurrency 256 및 1MB payload rows와 `agent-test/runs/20260602-232000-proto-socket-stress-full.md`의 burst/parallel/sustained rows를 근거로 완료 처리했다. Go는 fast path 기준점, Python은 중간 reference 기준점이며 둘 다 최우선 런타임 최적화 대상이 아니라 기준점 보강 대상으로 유지한다.
- 확인 필요: idle host에서 full baseline을 다시 측정한 뒤, 위 참고 결과 중 환경 잡음이 큰 quick 수치를 최종 개선 기준으로 쓸지 여부를 판단한다.

184
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/code_review_local_G05_0.log Normal file
View file

@ -0,0 +1,184 @@
<!-- task=m-performance-hotspot-optimization/01_hotspot_report plan=0 tag=TEST -->
# Code Review Reference - TEST
> **[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.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-06-03
task=m-performance-hotspot-optimization/01_hotspot_report, plan=0, tag=TEST
## Roadmap Targets
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
- `hotspot-report`: Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리
- Completion mode: check-on-pass
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-local-G05.md` -> `code_review_local_G05_N.log`, `PLAN-local-G05.md` -> `plan_local_G05_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/01_hotspot_report/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [TEST-1] 핫스팟 리포트 정리 | [x] |
## 구현 체크리스트
- [x] `[hotspot-report]` 근거를 마일스톤 안에 하나의 병목 리포트 섹션 또는 표로 정리한다.
- [x] Dart TCP, Dart isolate gateway, TypeScript WS 1MB, Kotlin WS/slow-mix, TypeScript gateway overhead 각각에 근거 파일, row, p99/throughput/memory, 후속 Task id를 연결한다.
- [x] Go/Python reference fast path는 병목 리포트의 비교 기준으로만 인용하고, 최우선 런타임 최적화 대상으로 쓰지 않는다.
- [x] `[idle-full]`과 `[compare-rule]`은 미완으로 유지하고, full idle baseline 부재를 명시한다.
- [x] `git diff --check`와 deterministic `rg --sort path` 검증을 실행한다.
- [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_local_G05_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G05_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리 `agent-task/m-performance-hotspot-optimization/01_hotspot_report/`를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/01_hotspot_report/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-performance-hotspot-optimization/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
- 없음. 계획대로 수행되었습니다.
## 주요 설계 결정
- 마일스톤 문서의 `## 작업 컨텍스트` 하위에 병목 리포트 및 성능 기준 표를 구성하여, 언어별 병목 후보(지연, 처리량, 메모리, 후속 Task ID)와 reference 성능 지표를 한눈에 볼 수 있도록 도표화하였습니다.
- 성능/스트레스 측정을 위한 최상위 통제 환경(Idle Host)에서의 Full Baseline(`run_performance.sh --full`) 결과가 아직 수집되지 않았음을 명시하는 경고 블록을 삽입하여 `[idle-full]`과 `[compare-rule]`이 미완성이고 임시 기준을 사용 중임을 분명히 하였습니다.
## 사용자 리뷰 요청
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- `[hotspot-report]` checkbox를 구현 중 직접 체크하지 않았는지 확인한다.
- 병목 리포트가 각 후보별 근거 파일, row, p99/throughput/memory, 후속 Task id를 포함하는지 확인한다.
- Go/Python이 최우선 최적화 대상이 아니라 reference 기준점으로만 쓰였는지 확인한다.
- `[idle-full]`과 `[compare-rule]`이 미완으로 남아 있고 full idle baseline 부재가 명시되었는지 확인한다.
## 검증 결과
### TEST-1 중간 검증
```bash
$ rg --sort path -n "병목 리포트|Dart TCP|TypeScript WS|Kotlin WS|TypeScript gateway|hotspot-report|idle-full|compare-rule" agent-roadmap/milestones/performance-hotspot-optimization.md
72:### Epic: [dart-tcp] Dart TCP 및 isolate receive path hardening
76:- [ ] [dart-tcp-fixed-latency] Dart TCP 40ms대 고정 지연 원인을 분리한다. 검증: `tcpNoDelay` 부재, per-packet `flush()`, write serialization, heartbeat timer churn, stream pause/resume 중 어느 후보가 TCP concurrency 16/64/256 및 sustained p99를 만드는지 같은 idle baseline에서 기록된다.
77:- [ ] [dart-tcp-burst-sustained] Dart TCP burst/sustained 처리량 저하를 fixed-latency 분석과 함께 분리한다. 검증: `agent-test/runs/20260602-232000-proto-socket-stress-full.md`의 Dart TCP burst 100k throughput 및 sustained 30분 throughput/p99 rows가 개선 전 기준으로 기록되고, write flush, heartbeat timer churn, receive buffering 중 원인 후보가 구분된다.
78:- [ ] [dart-tcp-buffer-copy] Dart TCP large payload의 write/read buffer copy를 줄인다. 검증: `_socket.add([...header, ...baseBytes])`, `_arrivedData.sublist`, `Uint8List.fromList`, `List<int>.from` 비용이 개선 전후로 비교되고, TCP 64KB/1MB payload row의 p99 또는 throughput이 개선되거나 남은 병목이 문서화된다.
87:### Epic: [ws-latency] Kotlin WS 지연 및 검증 모델 개선
91:- [ ] [kotlin-ws-delay] Kotlin WS roundtrip/payload 경로의 고정 지연을 분석하고 병목을 줄인다. 검증: OkHttp callback, `ByteString.toByteArray()` copy, `receiveQueue` Channel staging, communicator inbound queue, write/send flush 비용이 분리되고, Kotlin WS roundtrip concurrency 16/64/256 및 1KB/64KB/1MB payload rows가 stability hard gate를 유지한 채 p99 또는 throughput이 개선되거나 병목 원인이 명확히 문서화된다.
92:- [ ] [kotlin-slow-mix-model] Kotlin slow-mix deferred 축을 제품 결함으로 단정하지 않고, 같은 client of concurrent request completion order가 coroutine scheduling에 의존하는 검증 모델을 보정한다. 검증: 결정론적 helper, sequential same-client row, 또는 per-connection FIFO를 직접 관찰하는 별도 row 중 하나가 제안되고, `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`의 Kotlin deferred 사유가 병목 리포트에 반영된다.
96:### Epic: [gateway] TypeScript gateway 단일 수신 경로
98:이 Epic은 TypeScript gateway에 한정한다. gateway는 순차 이벤트 보장과 event loop 보호를 담당하는 mandatory receive path이며, 사용자/운영 설정으로 켜고 끄는 옵션을 두지 않는다. 현재 `worker_threads` per-frame offload 비용은 gateway를 끄는 근거가 아니라, worker hop을 기본 경로에서 제거하거나 내부 구현으로 재설계해야 하는 hardening 근거로 분류한다.
100:- [ ] [ts-gateway-single-path] TypeScript gateway를 제품 기본 수신 경로로 유지하기 위한 단일 경로 조건을 정의한다. 검증: gateway가 FIFO, nonce matching, close cleanup, bounded backlog hard gate를 유지하고, gateway/worker on-off 같은 외부 옵션 없이 같은 idle baseline 대비 p99/throughput 회귀 기준을 넘지 않는 조건이 문서화된다.
101:- [ ] [ts-worker-hop-removal] TypeScript `worker_threads` 기반 per-frame offload를 기본 gateway 경로에서 제거하거나, 동일 단일 경로 내부 구현으로 재설계한다. 검증: worker hop, buffer copy, reorder wait, sink serialization, backpressure 차이, memory 증가, p99 악화 원인이 줄어들고, 결과가 `run_performance.sh --full --baseline <baseline>` 병목 리포트에 기록된다.
102:- [ ] [gateway-overhead] TypeScript gateway 경로의 남은 overhead를 legacy inline control row와 비교해 정량화한다. 검증: 차이가 제품 정책 옵션으로 해석되지 않도록 control row는 분석용 대조군으로만 기록되고, 결론은 단일 mandatory receive path hardening 항목으로 남는다.
116: - [idle-full], [compare-rule]을 먼저 수행한다.
118: - [hotspot-report], [fast-path-ref]에서 언어별 병목과 Go/Python reference 기준점을 한 표로 정리한다.
167:- 병목 리포트:
170:> **Full Idle Baseline 부재**: 성능/스트레스 측정을 위한 최상위 통제 환경(Idle Host)에서의 Full Baseline(`run_performance.sh --full`) 결과가 아직 수집되지 않았습니다. 현재 기록된 개선 전 기준값들은 기존 local/remote 환경에서의 stress-full/quick 테스트 실행 결과(`agent-test/runs/*`)를 토대로 취합한 임시 기준입니다. `[idle-full]` 및 `[compare-rule]` 작업이 완료되어 전용 Baseline record가 남겨지기 전까지는 이 값들을 잠정적인 비교 기준으로 사용합니다.
176:| **Dart TCP**<br>(Fixed Latency, Burst, Sustained) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Sustained 30분 | - Concurrency 256 p99: **49.109ms**<br>- Burst 100k: **154.4 rps**<br>- Sustained throughput: **385.3 rps** / p99: **44.079ms** | `tcpNoDelay` 미설정 의심, per-packet `flush()`, write serialization, heartbeat timer churn, stream pause/resume 오버헤드 존재. | `dart-tcp-fixed-latency`<br>`dart-tcp-burst-sustained`<br>`dart-heartbeat-cost` |
177:| **Dart TCP 1MB**<br>(Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Payload 1MB | - Throughput: **9.6 rps**<br>- p99: **892.819ms** | 대형 payload 전송 시 write/read buffer copy 비용 극대화. `_socket.add` 및 sublist 비용 최적화 필요. | `dart-tcp-buffer-copy`<br>`dart-tcp-1mb` |
179:| **TypeScript WS 1MB**<br>(Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Payload 1MB | - p99: **228.648ms** | 대용량 WebSocket 프레임 전송/수신 처리량 저하 및 지연 병목. | `ts-ws-1mb` |
181:| **Kotlin WS**<br>(Fixed Latency, Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Concurrency 256<br>- WS Payload 1KB / 1MB | - Concurrency 256 p99: **44.877ms**<br>- Payload 1KB p99: **42.651ms**<br>- Payload 1MB p99: **133.842ms**<br>- Payload 1MB Heap Peak: **~668.3MB** | OkHttp 콜백, ByteString copy, Channel staging, inbound queue, write/send flush 지연 의심. 대용량 payload 시 JVM allocation/GC 유발 가능성. | `kotlin-ws-delay`<br>`kotlin-large-payload-memory` |
```
### 최종 검증
```bash
$ git diff --check
(아무 출력 없음, 정상적으로 0 종료)
```
```bash
$ rg --sort path -n "병목 리포트|agent-test/runs/20260603-062724-proto-socket-stress-full.md|agent-test/runs/20260602-232000-proto-socket-stress-full.md|agent-test/runs/20260603-080241-proto-socket-stress-full.md|Dart TCP|TypeScript WS|Kotlin WS|TypeScript gateway|Go|Python" agent-roadmap/milestones/performance-hotspot-optimization.md
167:- 병목 리포트:
170:> **Full Idle Baseline 부재**: 성능/스트레스 측정을 위한 최상위 통제 환경(Idle Host)에서의 Full Baseline(`run_performance.sh --full`) 결과가 아직 수집되지 않았습니다. 현재 기록된 개선 전 기준값들은 기존 local/remote 환경에서의 stress-full/quick 테스트 실행 결과(`agent-test/runs/*`)를 토대로 취합한 임시 기준입니다. `[idle-full]` 및 `[compare-rule]` 작업이 완료되어 전용 Baseline record가 남겨지기 전까지는 이 값들을 잠정적인 비교 기준으로 사용합니다.
176:| **Dart TCP**<br>(Fixed Latency, Burst, Sustained) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Sustained 30분 | - Concurrency 256 p99: **49.109ms**<br>- Burst 100k: **154.4 rps**<br>- Sustained throughput: **385.3 rps** / p99: **44.079ms** | `tcpNoDelay` 미설정 의심, per-packet `flush()`, write serialization, heartbeat timer churn, stream pause/resume 오버헤드 존재. | `dart-tcp-fixed-latency`<br>`dart-tcp-burst-sustained`<br>`dart-heartbeat-cost` |
177:| **Dart TCP 1MB**<br>(Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Payload 1MB | - Throughput: **9.6 rps**<br>- p99: **892.819ms** | 대형 payload 전송 시 write/read buffer copy 비용 극대화. `_socket.add` 및 sublist 비용 최적화 필요. | `dart-tcp-buffer-copy`<br>`dart-tcp-1mb` |
179:| **TypeScript WS 1MB**<br>(Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Payload 1MB | - p99: **228.648ms** | 대용량 WebSocket 프레임 전송/수신 처리량 저하 및 지연 병목. | `ts-ws-1mb` |
180:| **TypeScript Gateway**<br>(Worker Overhead) | [stress-full (20260603-gateway)](file:///config/workspace/proto-socket/agent-test/runs/20260603-080241-proto-socket-stress-full.md)<br>- WS Concurrency 256<br>- TCP Concurrency 256 | - WS Gateway: **2499.3 rps** (vs Control: **16242.7 rps**)<br>- WS Gateway p99: **205.654ms** (vs Control: **1.887ms**)<br>- TCP Gateway p99: **193.306ms** (vs Control: **43.095ms**) | `worker_threads` 기반 frame offload hop 비용, buffer copy, reorder wait로 인해 심각한 병목 유발. worker hop 제거 또는 단일 수신 경로로 재설계 필수. | `ts-gateway-single-path`<br>`ts-worker-hop-removal`<br>`gateway-overhead` |
181:| **Kotlin WS**<br>(Fixed Latency, Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Concurrency 256<br>- WS Payload 1KB / 1MB | - Concurrency 256 p99: **44.877ms**<br>- Payload 1KB p99: **42.651ms**<br>- Payload 1MB p99: **133.842ms**<br>- Payload 1MB Heap Peak: **~668.3MB** | OkHttp 콜백, ByteString copy, Channel staging, inbound queue, write/send flush 지연 의심. 대용량 payload 시 JVM allocation/GC 유발 가능성. | `kotlin-ws-delay`<br>`kotlin-large-payload-memory` |
187:> Go 및 Python은 최우선 런타임 최적화 대상이 아닙니다. 아래 reference 수치는 타 언어의 성능 개선 시 대조군 및 regression 감시 기준으로만 사용됩니다.
191:| **Go TCP / WS**<br>(Reference Fast Path) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>- WS Concurrency 256<br>- TCP Payload 1MB<br>- WS Payload 1MB<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Parallel 1024<br>- TCP Sustained 30분 | - TCP 256: **60748.4 rps** / p99 **4.432ms**<br>- WS 256: **62631.5 rps** / p99 **4.872ms**<br>- 1MB p99: **21.076ms** (TCP) / **35.880ms** (WS)<br>- Burst 100k: **201132.8 rps**<br>- Parallel 1024: **214665.2 rps** / p99 **154.621ms**<br>- Sustained throughput: **16264.9 rps** / p99 **0.646ms**<br>- Sustained Memory (30초/5분/30분): **57.1MB / 143.4MB / 794.1MB** | 30분 sustained memory 증가 원인이 leak인지 bench latency sample 누적 artifact인지 검증 필요. | `go-sustained-memory-metric`<br>`go-reference-guard` |
192:| **Go slow-mix**<br>(검증 모델 보정) | [stress-quick (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-035342-proto-socket-stress-quick.md)<br>- slow-mix deferred | - 검증 결과: **Deferred** | concurrent `SendRequestTyped` 완료 순서가 goroutine scheduling에 의존해 deferred 발생. 검증 helper/기준 보완. | `go-slow-mix-model` |
193:| **Python TCP / WS**<br>(Reference Medium Path) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>- WS Concurrency 256<br>- TCP Payload 1MB<br>- WS Payload 1MB<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Parallel (128/512/1024)<br>- Sustained Memory (30초/5분/30분) | - TCP 256: **10396.7 rps** / p99 **26.480ms**<br>- WS 256: **7790.6 rps** / p99 **29.769ms**<br>- 1MB p99: **18.856ms** (TCP) / **47.424ms** (WS)<br>- Parallel p99: **93.378ms** (128) / **501.368ms** (512) / **1288.999ms** (1024)<br>- Sustained Memory: **133.8MB / 181.1MB / 614.5MB** | 안정적인 중간 reference. 고동시성 p99 비용 정리 및 sustained memory leak/artifact 분리. gateway 관련 API 정책(사용자 옵션 배제) 정리. | `python-high-parallel-p99`<br>`python-sustained-memory-metric`<br>`python-gateway-api-policy`<br>`python-reference-guard` |
```
---
> **[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 review-agent-only sections unchanged.
## Ownership
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify |
| 구현 항목별 완료 여부 | Implementing agent | Check `[ ]` to `[x]` only |
| 구현 체크리스트 | Implementing agent | Check `[ ]` to `[x]` only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 | Implementing agent | Fill command output only |
| 코드리뷰 결과 | Review agent appends | Not included in stub |
## 코드리뷰 결과
- 종합 판정: FAIL
- 차원별 평가:
- correctness: Fail
- completeness: Fail
- test coverage: Pass
- API contract: Pass
- code quality: Pass
- plan deviation: Pass
- verification trust: Pass
- 발견된 문제:
- Required: `agent-roadmap/milestones/performance-hotspot-optimization.md:180`의 TypeScript Gateway 근거 row가 `WS Concurrency 256` / `TCP Concurrency 256`으로 기록되어 있지만, 인용한 `agent-test/runs/20260603-080241-proto-socket-stress-full.md:42`-`:45`의 실제 gateway transport rows는 `transport=tcp concurrency=16` 및 `transport=ws concurrency=16`입니다. 표의 대상 Row를 실제 row axis로 고쳐야 합니다.
- Required: `agent-roadmap/milestones/performance-hotspot-optimization.md:182`의 Kotlin slow-mix 판정이 "동일 클라이언트 concurrent request 완료 순서가 coroutine scheduling에 의존"한다고 되어 있지만, 인용한 `agent-test/runs/20260603-035352-proto-socket-stress-quick.md:47`-`:48`의 실제 deferred 사유는 TCP delayed-ACK latency-bound와 WS inbound launch-per-frame FIFO break입니다. 병목 리포트가 인용 run의 deferred 사유를 그대로 반영하도록 수정해야 합니다.
- 다음 단계: FAIL follow-up plan/review를 작성한다.

165
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/code_review_local_G06_1.log Normal file
View file

@ -0,0 +1,165 @@
<!-- task=m-performance-hotspot-optimization/01_hotspot_report plan=1 tag=REVIEW_TEST -->
# Code Review Reference - REVIEW_TEST
> **[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.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-06-04
task=m-performance-hotspot-optimization/01_hotspot_report, plan=1, tag=REVIEW_TEST
## Roadmap Targets
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
- `hotspot-report`: Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리
- Completion mode: check-on-pass
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-local-G06.md` -> `code_review_local_G06_N.log`, `PLAN-local-G06.md` -> `plan_local_G06_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/01_hotspot_report/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_TEST-1] TypeScript gateway row label 정정 | [x] |
| [REVIEW_TEST-2] Kotlin slow-mix deferred 사유 정정 | [x] |
## 구현 체크리스트
- [x] TypeScript Gateway row의 대상 Row label을 `agent-test/runs/20260603-080241-proto-socket-stress-full.md`의 실제 `gateway transport=tcp/ws concurrency=16` rows와 일치시킨다.
- [x] Kotlin slow-mix row의 판정 문구를 `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`의 TCP/WS deferred 사유와 일치시킨다.
- [x] `git diff --check`와 deterministic `rg --sort path` 검증을 실행한다.
- [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_local_G06_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G06_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리 `agent-task/m-performance-hotspot-optimization/01_hotspot_report/`를 `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-performance-hotspot-optimization/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
- 없음. 계획대로 수행되었습니다.
## 주요 설계 결정
- TypeScript Gateway row의 대상 Row label을 실제 인용된 결과 파일의 `gateway transport=tcp/ws concurrency=16` axis와 완벽히 일치시켰습니다.
- Kotlin slow-mix row의 판정 및 병목 의존성 항목의 설명을 실제 인용된 `stress-quick` 결과 파일에 기록된 구체적인 deferred 사유(TCP: delayed-ACK latency-bound, WS: Dispatchers.IO launch-per-frame 수신 경로에 의한 per-connection FIFO break)로 정정하여 완성도를 높였습니다.
## 사용자 리뷰 요청
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- TypeScript Gateway row의 대상 Row label이 실제 result file의 `gateway transport=tcp/ws concurrency=16` axis와 일치하는지 확인한다.
- Kotlin slow-mix row의 판정 문구가 `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`의 TCP/WS deferred 사유를 반영하는지 확인한다.
- `hotspot-report` checkbox는 구현 중 직접 체크하지 않았는지 확인한다.
## 검증 결과
### REVIEW_TEST-1 중간 검증
```bash
$ rg --sort path -n "TypeScript Gateway|Gateway transport=ws concurrency=16|Gateway transport=tcp concurrency=16|WS Concurrency 256|TCP Concurrency 256" agent-roadmap/milestones/performance-hotspot-optimization.md
176:| **Dart TCP**<br>(Fixed Latency, Burst, Sustained) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Sustained 30분 | - Concurrency 256 p99: **49.109ms**<br>- Burst 100k: **154.4 rps**<br>- Sustained throughput: **385.3 rps** / p99: **44.079ms** | `tcpNoDelay` 미설정 의심, per-packet `flush()`, write serialization, heartbeat timer churn, stream pause/resume 오버헤드 존재. | `dart-tcp-fixed-latency`<br>`dart-tcp-burst-sustained`<br>`dart-heartbeat-cost` |
180:| **TypeScript Gateway**<br>(Worker Overhead) | [stress-full (20260603-gateway)](file:///config/workspace/proto-socket/agent-test/runs/20260603-080241-proto-socket-stress-full.md)<br>- Gateway transport=ws concurrency=16<br>- Gateway transport=tcp concurrency=16 | - WS Gateway: **2499.3 rps** (vs Control: **16242.7 rps**)<br>- WS Gateway p99: **205.654ms** (vs Control: **1.887ms**)<br>- TCP Gateway p99: **193.306ms** (vs Control: **43.095ms**) | `worker_threads` 기반 frame offload hop 비용, buffer copy, reorder wait로 인해 심각한 병목 유발. worker hop 제거 또는 단일 수신 경로로 재설계 필수. | `ts-gateway-single-path`<br>`ts-worker-hop-removal`<br>`gateway-overhead` |
181:| **Kotlin WS**<br>(Fixed Latency, Large Payload) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- WS Concurrency 256<br>- WS Payload 1KB / 1MB | - Concurrency 256 p99: **44.877ms**<br>- Payload 1KB p99: **42.651ms**<br>- Payload 1MB p99: **133.842ms**<br>- Payload 1MB Heap Peak: **~668.3MB** | OkHttp 콜백, ByteString copy, Channel staging, inbound queue, write/send flush 지연 의심. 대용량 payload 시 JVM allocation/GC 유발 가능성. | `kotlin-ws-delay`<br>`kotlin-large-payload-memory` |
191:| **Go TCP / WS**<br>(Reference Fast Path) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>- WS Concurrency 256<br>- TCP Payload 1MB<br>- WS Payload 1MB<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Burst 100k<br>- TCP Parallel 1024<br>- TCP Sustained 30분 | - TCP 256: **60748.4 rps** / p99 **4.432ms**<br>- WS 256: **62631.5 rps** / p99 **4.872ms**<br>- 1MB p99: **21.076ms** (TCP) / **35.880ms** (WS)<br>- Burst 100k: **201132.8 rps**<br>- Parallel 1024: **214665.2 rps** / p99 **154.621ms**<br>- Sustained throughput: **16264.9 rps** / p99 **0.646ms**<br>- Sustained Memory (30초/5분/30분): **57.1MB / 143.4MB / 794.1MB** | 30분 sustained memory 증가 원인이 leak인지 bench latency sample 누적 artifact인지 검증 필요. | `go-sustained-memory-metric`<br>`go-reference-guard` |
193:| **Python TCP / WS**<br>(Reference Medium Path) | [stress-full (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md)<br>- TCP Concurrency 256<br>- WS Concurrency 256<br>- TCP Payload 1MB<br>- WS Payload 1MB<br>[stress-full (20260602)](file:///config/workspace/proto-socket/agent-test/runs/20260602-232000-proto-socket-stress-full.md)<br>- TCP Parallel (128/512/1024)<br>- Sustained Memory (30초/5분/30분) | - TCP 256: **10396.7 rps** / p99 **26.480ms**<br>- WS 256: **7790.6 rps** / p99 **29.769ms**<br>- 1MB p99: **18.856ms** (TCP) / **47.424ms** (WS)<br>- Parallel p99: **93.378ms** (128) / **501.368ms** (512) / **1288.999ms** (1024)<br>- Sustained Memory: **133.8MB / 181.1MB / 614.5MB** | 안정적인 중간 reference. 고동시성 p99 비용 정리 및 sustained memory leak/artifact 분리. gateway 관련 API 정책(사용자 옵션 배제) 정리. | `python-high-parallel-p99`<br>`python-sustained-memory-metric`<br>`python-gateway-api-policy`<br>`python-reference-guard` |
```
### REVIEW_TEST-2 중간 검증
```bash
$ rg --sort path -n "Kotlin slow-mix|delayed-ACK latency-bound|launch-per-frame|coroutine scheduling|코루틴 스케줄링" agent-roadmap/milestones/performance-hotspot-optimization.md
92:- [ ] [kotlin-slow-mix-model] Kotlin slow-mix deferred 축을 제품 결함으로 단정하지 않고, 같은 client의 concurrent request completion order가 coroutine scheduling에 의존하는 검증 모델을 보정한다. 검증: 결정론적 helper, sequential same-client row, 또는 per-connection FIFO를 직접 관찰하는 별도 row 중 하나가 제안되고, `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`의 Kotlin deferred 사유가 병목 리포트에 반영된다.
182:| **Kotlin slow-mix**<br>(검증 모델 보정) | [stress-quick (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-035352-proto-socket-stress-quick.md)<br>- slow-mix deferred | - 검증 결과: **Deferred** | TCP는 delayed-ACK latency-bound로 request/response concurrency 안정성 timeout 가능성이 있고, WS는 Dispatchers.IO launch-per-frame 수신 경로가 burst/mixed slow handler에서 per-connection FIFO를 깨는 deferred 사유로 기록됨. | `kotlin-slow-mix-model` |
210: - `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`는 Kotlin TCP/WS slow-mix를 deferred로 기록했다. 현재 보강 방향은 제품 결함 단정이 아니라, 같은 client의 concurrent request completion order가 coroutine scheduling에 의존하는 검증 모델을 결정론적으로 보정하는 것이다.
```
### 최종 검증
```bash
$ git diff --check
(아무 출력 없음, 정상적으로 0 종료)
```
```bash
$ rg --sort path -n "TypeScript Gateway|Gateway transport=ws concurrency=16|Gateway transport=tcp concurrency=16|Kotlin slow-mix|delayed-ACK latency-bound|launch-per-frame|agent-test/runs/20260603-080241-proto-socket-stress-full.md|agent-test/runs/20260603-035352-proto-socket-stress-quick.md" agent-roadmap/milestones/performance-hotspot-optimization.md
180:| **TypeScript Gateway**<br>(Worker Overhead) | [stress-full (20260603-gateway)](file:///config/workspace/proto-socket/agent-test/runs/20260603-080241-proto-socket-stress-full.md)<br>- Gateway transport=ws concurrency=16<br>- Gateway transport=tcp concurrency=16 | - WS Gateway: **2499.3 rps** (vs Control: **16242.7 rps**)<br>- WS Gateway p99: **205.654ms** (vs Control: **1.887ms**)<br>- TCP Gateway p99: **193.306ms** (vs Control: **43.095ms**) | `worker_threads` 기반 frame offload hop 비용, buffer copy, reorder wait로 인해 심각한 병목 유발. worker hop 제거 또는 단일 수신 경로로 재설계 필수. | `ts-gateway-single-path`<br>`ts-worker-hop-removal`<br>`gateway-overhead` |
182:| **Kotlin slow-mix**<br>(검증 모델 보정) | [stress-quick (20260603)](file:///config/workspace/proto-socket/agent-test/runs/20260603-035352-proto-socket-stress-quick.md)<br>- slow-mix deferred | - 검증 결과: **Deferred** | TCP는 delayed-ACK latency-bound로 request/response concurrency 안정성 timeout 가능성이 있고, WS는 Dispatchers.IO launch-per-frame 수신 경로가 burst/mixed slow handler에서 per-connection FIFO를 깨는 deferred 사유로 기록됨. | `kotlin-slow-mix-model` |
```
---
> **[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 review-agent-only sections unchanged.
## Ownership
| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these |
| Roadmap Targets | Fixed at stub creation from plan | Implementing agent must not modify |
| 구현 항목별 완료 여부 | Implementing agent | Check `[ ]` to `[x]` only |
| 구현 체크리스트 | Implementing agent | Check `[ ]` to `[x]` only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 | Implementing agent | Fill command output only |
| 코드리뷰 결과 | Review agent appends | Not included in stub |
## 코드리뷰 결과
- 종합 판정: PASS
- 차원별 평가:
- correctness: Pass
- completeness: Pass
- test coverage: Pass
- API contract: Pass
- code quality: Pass
- plan deviation: Pass
- verification trust: Pass
- 발견된 문제: 없음
- 다음 단계: PASS complete.log 작성 후 task directory를 archive로 이동한다.

43
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/complete.log Normal file
View file

@ -0,0 +1,43 @@
# Complete - m-performance-hotspot-optimization/01_hotspot_report
## 완료 일시
2026-06-04
## 요약
`hotspot-report` 병목 리포트 정리를 2회 리뷰 루프로 완료했고, 최종 판정은 PASS다.
## 루프 이력
| Plan | Review | Verdict | 메모 |
|------|--------|---------|------|
| `plan_local_G05_0.log` | `code_review_local_G05_0.log` | FAIL | TypeScript Gateway 대상 row label과 Kotlin slow-mix deferred 사유가 인용 결과와 달라 follow-up 작성 |
| `plan_local_G06_1.log` | `code_review_local_G06_1.log` | PASS | gateway row label과 Kotlin deferred 사유를 실제 result file 기준으로 정정하고 검증 완료 |
## 구현/정리 내용
- `agent-roadmap/milestones/performance-hotspot-optimization.md`에 언어별 병목 후보와 Go/Python reference fast path 표를 추가했다.
- full idle baseline 부재를 명시하고, 기존 stress/full 및 quick 결과를 임시 개선 전 기준값으로 분리했다.
- TypeScript Gateway row의 대상 Row label을 실제 `gateway transport=tcp/ws concurrency=16` axis와 일치시켰다.
- Kotlin slow-mix row의 판정 문구를 실제 TCP delayed-ACK 및 WS launch-per-frame FIFO deferred 사유와 일치시켰다.
## 최종 검증
- `git diff --check` - PASS; 출력 없음.
- `rg --sort path -n "TypeScript Gateway|Gateway transport=ws concurrency=16|Gateway transport=tcp concurrency=16|Kotlin slow-mix|delayed-ACK latency-bound|launch-per-frame|agent-test/runs/20260603-080241-proto-socket-stress-full.md|agent-test/runs/20260603-035352-proto-socket-stress-quick.md" agent-roadmap/milestones/performance-hotspot-optimization.md` - PASS; TypeScript Gateway row의 실제 gateway axis와 Kotlin slow-mix row의 실제 deferred 사유를 확인.
## Roadmap Completion
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Completed task ids:
- `hotspot-report`: PASS; evidence=`agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/plan_local_G06_1.log`, `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/code_review_local_G06_1.log`; verification=`git diff --check`, `rg --sort path -n "TypeScript Gateway|Gateway transport=ws concurrency=16|Gateway transport=tcp concurrency=16|Kotlin slow-mix|delayed-ACK latency-bound|launch-per-frame|agent-test/runs/20260603-080241-proto-socket-stress-full.md|agent-test/runs/20260603-035352-proto-socket-stress-quick.md" agent-roadmap/milestones/performance-hotspot-optimization.md`
- Not completed task ids: 없음
## 잔여 Nit
- 없음
## 후속 작업
- 없음

148
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/plan_local_G05_0.log Normal file
View file

@ -0,0 +1,148 @@
<!-- task=m-performance-hotspot-optimization/01_hotspot_report plan=0 tag=TEST -->
# Plan - TEST
## 이 파일을 읽는 구현 에이전트에게
`CODE_REVIEW-local-G05.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것까지가 구현입니다. 검증을 실행하고 실제 stdout/stderr를 붙여 넣은 뒤 active 파일을 그대로 두고 리뷰 준비를 보고하세요. 사용자 결정, 사용자 소유 외부 환경, 또는 계획 범위 변경 없이는 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 근거와 재개 조건을 채우고 멈추세요. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아닙니다.
## 배경
`performance-hotspot-optimization` 마일스톤의 두 번째 Epic `[hotspot]`에는 병목 리포트와 Go/Python reference 정리 두 작업이 남아 있었다. Go/Python reference 정리는 기존 측정 근거가 이미 충분해 바로 완료 처리했다. `[hotspot-report]`는 여러 결과 파일에 흩어진 Dart, TypeScript, Kotlin, gateway 근거를 하나의 검토 가능한 리포트로 정리해야 하므로 구현 루프에 태운다.
## 사용자 리뷰 요청 흐름
구현 중 차단이 있으면 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 active review stub의 `사용자 리뷰 요청` 섹션을 채운다. `USER_REVIEW.md` 작성과 차단 판단은 code-review가 담당한다.
## Roadmap Targets
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
- `hotspot-report`: Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리
- Completion mode: check-on-pass
## 분석 결과
### 읽은 파일
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/update-roadmap/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-roadmap/current.md`
- `agent-roadmap/ROADMAP.md`
- `agent-roadmap/milestones/performance-hotspot-optimization.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `agent-test/runs/20260603-062724-proto-socket-stress-full.md`
- `agent-test/runs/20260602-232000-proto-socket-stress-full.md`
- `agent-test/runs/20260603-080241-proto-socket-stress-full.md`
- `agent-test/runs/20260603-035342-proto-socket-stress-quick.md`
- `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`
- `agent-test/runs/20260603-095712-proto-socket-performance-quick.md`
- `.gitignore`
### 테스트 환경 규칙
test_env는 `local`이다. `agent-test/local/rules.md`를 읽었고, 성능/latency/payload/gateway 근거 작업이므로 `agent-test/local/proto-socket-performance-baseline.md`를 적용한다. 전체 호환성 회귀는 코드 변경이 없으므로 필수 최종 검증이 아니라 보조 검증으로만 남긴다. 이 plan의 변경은 문서/로드맵 정리라 성능 측정을 새로 실행하지 않고, 기존 결과 파일의 row 근거가 마일스톤에 정확히 연결되는지 `rg --sort path`와 `git diff --check`로 검증한다.
### 테스트 커버리지 공백
- 병목 리포트 문서화: 기존 stress/performance 기록이 증거다. 새 런타임 동작이 없으므로 unit test 추가는 하지 않는다.
- idle `run_performance.sh --full` 기준점: 아직 결과 파일이 없다. `[idle-full]`과 `[compare-rule]`은 이번 범위에서 완료 주장하지 않는다.
- 코드 성능 개선: 이번 범위가 아니다. 이후 TypeScript/Dart/Kotlin 구현 plan에서 별도 성능 검증을 지정한다.
### 심볼 참조
none. 이름 변경, 삭제, import 변경이 없다.
### 분할 판단
분할 정책을 먼저 평가했다. 공유 task group은 `agent-task/m-performance-hotspot-optimization/`이고 현재 생성하는 subtask는 `01_hotspot_report`다. 선행 subtask는 없다. `[hotspot-report]`는 로드맵/결과 근거 정리만 다루는 단일 산출물이므로 TypeScript gateway 구현, Dart TCP 구현, Kotlin WS 구현과 분리한다.
### 범위 결정 근거
수정 대상은 `agent-roadmap/milestones/performance-hotspot-optimization.md`와 active task artifact로 제한한다. `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/`는 구현 대상이 아니다. `agent-test/runs/**`는 근거로만 읽고 수정하지 않는다.
### 빌드 등급
build=`local-G05`, review=`local-G05`. 코드 변경 없는 milestone-linked 문서 작업이지만, 여러 성능 결과를 정확히 연결해야 해서 중간 난도로 둔다.
## 구현 체크리스트
- [ ] `[hotspot-report]` 근거를 마일스톤 안에 하나의 병목 리포트 섹션 또는 표로 정리한다.
- [ ] Dart TCP, Dart isolate gateway, TypeScript WS 1MB, Kotlin WS/slow-mix, TypeScript gateway overhead 각각에 근거 파일, row, p99/throughput/memory, 후속 Task id를 연결한다.
- [ ] Go/Python reference fast path는 병목 리포트의 비교 기준으로만 인용하고, 최우선 런타임 최적화 대상으로 쓰지 않는다.
- [ ] `[idle-full]`과 `[compare-rule]`은 미완으로 유지하고, full idle baseline 부재를 명시한다.
- [ ] `git diff --check`와 deterministic `rg --sort path` 검증을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
### [TEST-1] 핫스팟 리포트 정리
#### 문제
[agent-roadmap/milestones/performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:41)의 `[hotspot]` Epic은 병목 우선순위 확정을 요구하지만, [agent-roadmap/milestones/performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:171)의 참고 결과는 긴 bullet 목록이라 `[hotspot-report]` 검증 조건인 “근거 파일, 대상 row, p99/throughput/memory 수치, 개선 전 기준값”을 한눈에 검토하기 어렵다.
Before:
```markdown
45 - [ ] [hotspot-report] Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리한다. 검증: 각 병목 후보에 근거 결과 파일, 대상 row, p99/throughput/memory 수치, 개선 전 기준값이 기록된다.
171 - 참고 결과:
172 - `agent-test/runs/20260603-062724-proto-socket-stress-full.md`는 ...
```
#### 해결 방법
`작업 컨텍스트` 아래에 병목 리포트 subsection 또는 compact table을 추가한다. 각 row는 병목 후보, 근거 result file, 대상 row/axis, 핵심 수치, 판정, 후속 Task id를 포함한다. `[hotspot-report]` 체크는 이 plan의 Roadmap Targets로 처리되므로 구현 중 직접 체크하지 않는다.
After:
```markdown
## 작업 컨텍스트
- 병목 리포트:
- Dart TCP fixed latency / 1MB: ... 근거 ... 후속 Task ...
- TypeScript WS 1MB: ... 근거 ... 후속 Task ...
- Kotlin WS latency / slow-mix: ... 근거 ... 후속 Task ...
- TypeScript gateway overhead: ... 근거 ... 후속 Task ...
```
#### 수정 파일 및 체크리스트
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: 병목 리포트 subsection/table을 추가한다.
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: full idle baseline 부재와 quick/full stress 근거의 지위를 구분한다.
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: `[hotspot-report]` checkbox는 직접 변경하지 않는다.
#### 테스트 작성
테스트 파일은 추가하지 않는다. 런타임 코드 변경이 없고, 검증 대상은 기존 stress/performance 결과 파일과 마일스톤 문서의 연결성이다.
#### 중간 검증
```bash
rg --sort path -n "병목 리포트|Dart TCP|TypeScript WS|Kotlin WS|TypeScript gateway|hotspot-report|idle-full|compare-rule" agent-roadmap/milestones/performance-hotspot-optimization.md
```
기대 결과: 병목 리포트와 `[hotspot-report]`, `[idle-full]`, `[compare-rule]` 상태가 함께 출력된다.
## 수정 파일 요약
| 파일 | 항목 |
|---|---|
| `agent-roadmap/milestones/performance-hotspot-optimization.md` | TEST-1 |
| `agent-task/m-performance-hotspot-optimization/01_hotspot_report/PLAN-local-G05.md` | task artifact |
| `agent-task/m-performance-hotspot-optimization/01_hotspot_report/CODE_REVIEW-local-G05.md` | task artifact |
## 최종 검증
```bash
git diff --check
rg --sort path -n "병목 리포트|agent-test/runs/20260603-062724-proto-socket-stress-full.md|agent-test/runs/20260602-232000-proto-socket-stress-full.md|agent-test/runs/20260603-080241-proto-socket-stress-full.md|Dart TCP|TypeScript WS|Kotlin WS|TypeScript gateway|Go|Python" agent-roadmap/milestones/performance-hotspot-optimization.md
```
기대 결과: `git diff --check`는 출력 없이 0으로 종료한다. `rg`는 병목 리포트와 각 근거 파일/언어 후보를 출력한다.
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

174
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_hotspot_report/plan_local_G06_1.log Normal file
View file

@ -0,0 +1,174 @@
<!-- task=m-performance-hotspot-optimization/01_hotspot_report plan=1 tag=REVIEW_TEST -->
# Plan - REVIEW_TEST
## 이 파일을 읽는 구현 에이전트에게
`CODE_REVIEW-local-G06.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것까지가 구현입니다. 검증을 실행하고 실제 stdout/stderr를 붙여 넣은 뒤 active 파일을 그대로 두고 리뷰 준비를 보고하세요. 사용자 결정, 사용자 소유 외부 환경, 또는 계획 범위 변경 없이는 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 근거와 재개 조건을 채우고 멈추세요. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아닙니다.
## 배경
첫 리뷰에서 병목 리포트의 핵심 근거 두 곳이 인용한 결과 파일의 실제 row와 다르게 기록된 점이 확인되었습니다. TypeScript gateway 표는 실제 gateway row의 concurrency 값을 잘못 적었고, Kotlin slow-mix 표는 인용 결과 파일의 deferred 사유와 다른 원인 설명을 기록했습니다. 이번 follow-up은 마일스톤 문서의 병목 리포트 정확도만 바로잡습니다.
## 사용자 리뷰 요청 흐름
구현 중 차단이 있으면 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 active review stub의 `사용자 리뷰 요청` 섹션을 채웁니다. `USER_REVIEW.md` 작성과 차단 판단은 code-review가 담당합니다.
## Roadmap Targets
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
- `hotspot-report`: Dart TCP fixed latency/large payload/isolate gateway hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway overhead를 병목 리포트로 정리
- Completion mode: check-on-pass
## 분석 결과
### 읽은 파일
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/code-review/SKILL.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
- `agent-roadmap/current.md`
- `agent-roadmap/milestones/performance-hotspot-optimization.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-test/runs/20260603-080241-proto-socket-stress-full.md`
- `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`
- `agent-task/m-performance-hotspot-optimization/01_hotspot_report/plan_local_G05_0.log`
- `agent-task/m-performance-hotspot-optimization/01_hotspot_report/code_review_local_G05_0.log`
- `.gitignore`
### 테스트 환경 규칙
test_env는 `local`입니다. `agent-test/local/rules.md`를 읽었고, 성능 row 근거 정확도 검증이므로 `agent-test/local/proto-socket-performance-baseline.md`를 적용합니다. 런타임 코드 변경이 아니므로 새 stress/performance 측정은 실행하지 않고, 인용된 기존 result row와 마일스톤 표가 일치하는지 deterministic `rg --sort path`와 `git diff --check`로 확인합니다.
### 테스트 커버리지 공백
- 문서 row label 정확도: 기존 result file이 증거이며, 새 unit test는 필요하지 않습니다.
- Kotlin deferred 사유 정확도: 기존 result file의 SKIPPED/BLOCKED 축이 증거이며, 새 stress 실행은 필요하지 않습니다.
- 런타임 동작: 변경 대상이 아니므로 커버리지 추가 대상이 없습니다.
### 심볼 참조
none. 이름 변경, 삭제, import 변경이 없습니다.
### 분할 판단
기존 split subtask `01_hotspot_report`의 follow-up입니다. 두 Required 이슈가 같은 병목 리포트 표의 근거 정확도 문제라 하나의 plan에서 함께 고치는 것이 가장 좁고 검토 가능합니다. 다른 성능 구현, 측정 harness, 언어별 코드 수정은 이번 범위가 아닙니다.
### 범위 결정 근거
수정 대상은 `agent-roadmap/milestones/performance-hotspot-optimization.md`와 active task artifact로 제한합니다. `agent-test/runs/**`는 읽기 전용 근거이며 수정하지 않습니다. `dart/`, `go/`, `kotlin/`, `python/`, `typescript/`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/`는 구현 대상이 아닙니다.
### 빌드 등급
build=`local-G06`, review=`local-G06`. 실패 원인은 명시적이고 deterministic하게 재검증 가능하지만, 마일스톤 완료 근거의 정확도 문제라 이전보다 한 단계 높은 local review로 둡니다.
## 구현 체크리스트
- [ ] TypeScript Gateway row의 대상 Row label을 `agent-test/runs/20260603-080241-proto-socket-stress-full.md`의 실제 `gateway transport=tcp/ws concurrency=16` rows와 일치시킨다.
- [ ] Kotlin slow-mix row의 판정 문구를 `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`의 TCP/WS deferred 사유와 일치시킨다.
- [ ] `git diff --check`와 deterministic `rg --sort path` 검증을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
### [REVIEW_TEST-1] TypeScript gateway row label 정정
#### 문제
[agent-roadmap/milestones/performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:180)의 TypeScript Gateway row는 대상 Row를 `WS Concurrency 256`, `TCP Concurrency 256`으로 적었습니다. 그러나 인용한 [agent-test/runs/20260603-080241-proto-socket-stress-full.md](/config/workspace/proto-socket/agent-test/runs/20260603-080241-proto-socket-stress-full.md:42)의 실제 gateway rows는 `gateway | transport=tcp concurrency=16` 및 `gateway | transport=ws concurrency=16`입니다.
#### 해결 방법
마일스톤 표의 TypeScript Gateway 근거 파일 / 대상 Row 칸을 실제 axis와 맞춥니다. 수치 자체는 해당 `concurrency=16` row와 일치하므로, row label만 정정하면 됩니다.
Before:
```markdown
- WS Concurrency 256
- TCP Concurrency 256
```
After:
```markdown
- Gateway transport=ws concurrency=16
- Gateway transport=tcp concurrency=16
```
#### 수정 파일 및 체크리스트
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: TypeScript Gateway row의 대상 Row label을 실제 gateway axis로 바꾼다.
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: 같은 row의 p99/throughput 수치는 기존 result row와 계속 일치하는지 확인한다.
#### 테스트 작성
테스트 파일은 추가하지 않습니다. 기존 result file row와 문서 표의 연결성을 deterministic search로 검증합니다.
#### 중간 검증
```bash
rg --sort path -n "TypeScript Gateway|Gateway transport=ws concurrency=16|Gateway transport=tcp concurrency=16|WS Concurrency 256|TCP Concurrency 256" agent-roadmap/milestones/performance-hotspot-optimization.md
```
기대 결과: TypeScript Gateway row는 `Gateway transport=ws concurrency=16` 및 `Gateway transport=tcp concurrency=16`을 출력하고, 해당 row 안에는 `WS Concurrency 256` 또는 `TCP Concurrency 256`이 남지 않습니다.
### [REVIEW_TEST-2] Kotlin slow-mix deferred 사유 정정
#### 문제
[agent-roadmap/milestones/performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:182)의 Kotlin slow-mix row는 "동일 클라이언트 concurrent request 완료 순서가 코루틴 스케줄링에 의존"한다고 기록했습니다. 하지만 인용한 [agent-test/runs/20260603-035352-proto-socket-stress-quick.md](/config/workspace/proto-socket/agent-test/runs/20260603-035352-proto-socket-stress-quick.md:47)의 실제 deferred 사유는 TCP delayed-ACK latency-bound와 WS inbound launch-per-frame FIFO break입니다.
#### 해결 방법
Kotlin slow-mix row의 판정 및 병목 의존성 칸을 실제 result file의 TCP/WS 사유가 드러나도록 고칩니다. 제품 결함으로 단정하지 않는 톤은 유지하되, 현재 인용 결과에서 확인된 TCP/WS deferred 축을 그대로 반영합니다.
Before:
```markdown
동일 클라이언트의 concurrent request 완료 순서가 코루틴 스케줄링에 의존해 순서 검증 실패.
```
After:
```markdown
TCP는 delayed-ACK latency-bound로 request/response concurrency 안정성 timeout 가능성이 있고, WS는 Dispatchers.IO launch-per-frame 수신 경로가 burst/mixed slow handler에서 per-connection FIFO를 깨는 deferred 사유로 기록됨.
```
#### 수정 파일 및 체크리스트
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: Kotlin slow-mix row의 판정 문구를 실제 TCP/WS deferred 사유와 맞춘다.
- [ ] `agent-roadmap/milestones/performance-hotspot-optimization.md`: `kotlin-slow-mix-model` 후속 Task id는 유지한다.
#### 테스트 작성
테스트 파일은 추가하지 않습니다. 인용 result file의 SKIPPED/BLOCKED 축과 문서 표의 문구 일치를 search로 확인합니다.
#### 중간 검증
```bash
rg --sort path -n "Kotlin slow-mix|delayed-ACK latency-bound|launch-per-frame|coroutine scheduling|코루틴 스케줄링" agent-roadmap/milestones/performance-hotspot-optimization.md
```
기대 결과: Kotlin slow-mix row는 `delayed-ACK latency-bound`와 `launch-per-frame`을 포함하고, 해당 row의 기존 오인 문구인 `코루틴 스케줄링`은 남지 않습니다.
## 수정 파일 요약
| 파일 | 항목 |
|---|---|
| `agent-roadmap/milestones/performance-hotspot-optimization.md` | REVIEW_TEST-1, REVIEW_TEST-2 |
| `agent-task/m-performance-hotspot-optimization/01_hotspot_report/PLAN-local-G06.md` | task artifact |
| `agent-task/m-performance-hotspot-optimization/01_hotspot_report/CODE_REVIEW-local-G06.md` | task artifact |
## 최종 검증
```bash
git diff --check
rg --sort path -n "TypeScript Gateway|Gateway transport=ws concurrency=16|Gateway transport=tcp concurrency=16|Kotlin slow-mix|delayed-ACK latency-bound|launch-per-frame|agent-test/runs/20260603-080241-proto-socket-stress-full.md|agent-test/runs/20260603-035352-proto-socket-stress-quick.md" agent-roadmap/milestones/performance-hotspot-optimization.md
```
기대 결과: `git diff --check`는 출력 없이 0으로 종료합니다. `rg`는 TypeScript Gateway row의 실제 gateway axis와 Kotlin slow-mix row의 실제 deferred 사유를 출력합니다.
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.