<!-- task=m-performance-hotspot-optimization/15+14_kotlin_ws_reference_guard plan=0 tag=TEST -->

# Plan - TEST

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

14번 subtask의 archive `complete.log`를 선행 근거로 확인한 뒤 구현을 시작하세요. 이 작업은 Kotlin WS hardening 이후 증거 수집과 guard 판정이 목적입니다. 코드 변경이 없더라도 `CODE_REVIEW-local-G06.md`의 구현 에이전트 소유 섹션에 실제 명령 출력과 결과 파일을 채워야 완료입니다. 사용자 소유 idle host 조건이 필요해 자동으로 진행할 수 없으면 리뷰 stub의 `사용자 리뷰 요청`에 근거를 기록하고 멈추세요.

## 배경

`kotlin-large-payload-memory`와 `kotlin-tcp-reference-guard`는 WS 개선 이후의 결과로 닫아야 한다. 기존 full stress는 Kotlin TCP 1MB memory 약 500.3MB, WS 1MB memory 약 668.3MB, TCP concurrency 256 p99 약 21.173ms를 기록했다. 14번 hardening이 WS 지연을 줄였더라도 TCP reference를 악화시키면 안 된다.

## 사용자 리뷰 요청 흐름

구현 중 차단은 active review stub의 `사용자 리뷰 요청` 섹션에 기록합니다. 직접 사용자 프롬프트는 금지이며, code-review가 요청 타당성을 검증하고 실제 `USER_REVIEW.md` 작성을 소유합니다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
  - `kotlin-large-payload-memory`: Kotlin large payload heap peak를 WS 지연 개선과 함께 관찰한다.
  - `kotlin-tcp-reference-guard`: Kotlin TCP는 idle full baseline에서 현재 기준선이 유지되는지 확인한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `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/local/kotlin-smoke.md`
- `agent-test/runs/20260603-062724-proto-socket-stress-full.md`
- `agent-test/runs/20260605-115943-proto-socket-performance-full.md`
- `agent-ops/rules/project/domain/kotlin/rules.md`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/WsClient.kt`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/WsServer.kt`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/TcpClient.kt`
- `kotlin/crosstest/stress.kt`

### 테스트 환경 규칙

`test_env=local`을 사용한다. 성능 기준선/latency/memory 판단이므로 `agent-test/local/proto-socket-performance-baseline.md`를 적용한다. Kotlin 변경 후 guard이므로 `agent-test/local/kotlin-smoke.md`의 `cd kotlin && ./gradlew test`도 확인한다. full baseline은 idle host에서만 기준값으로 쓴다는 마일스톤 작업 순서를 따른다.

### 테스트 커버리지 공백

unit tests는 TCP/WS 기능 회귀만 확인한다. memory peak, p99, throughput, TCP reference 보존은 `run_stress.sh`/`run_performance.sh` 결과 파일로만 판정한다. full run이 idle host가 아니면 기준값으로 단정하지 않고 user-review 또는 WARN evidence로 남긴다.

### 심볼 참조

renamed/removed symbol 없음.

### 분할 판단

이 subtask는 `15+14_kotlin_ws_reference_guard`이며 predecessor `14_kotlin_ws_transport_hardening` complete.log가 필요하다. 선행 조건은 archive path `agent-task/archive/2026/06/m-performance-hotspot-optimization/14+13_kotlin_ws_transport_hardening/complete.log`로 충족됐다.

### 범위 결정 근거

새 최적화 구현을 추가하지 않는다. Kotlin WS/TCP stress 결과를 수집하고 code review evidence로 정리한다. 전체 release compatibility matrix는 `verify` Epic의 별도 `compat-matrix` Task에 남긴다.

### 빌드 등급

`local-G06`: 코드 변경은 없거나 작지만, 장시간/성능 결과 해석과 idle-host 조건 판단이 필요하다.

## 구현 체크리스트

- [ ] 14번 complete.log와 최종 검증 결과를 읽고 Kotlin WS 변경 범위를 확인한다.
- [ ] Kotlin unit test를 실행해 기능 회귀가 없는지 확인한다.
- [ ] Kotlin focused full stress로 TCP/WS roundtrip,payload rows를 기록한다.
- [ ] Kotlin TCP concurrency 256 및 TCP 1MB payload row가 기존 기준선 대비 악화되지 않았는지 기록한다.
- [ ] Kotlin WS 1MB payload memory, p99, throughput과 13번 diagnostics 값을 함께 기록해 JVM allocation/GC 후보와 queue/backlog 잔여 상태를 분리한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

이 plan은 directory name의 `+14`에 따라 14번 subtask 완료가 필요하다. 선행 조건은 `agent-task/archive/2026/06/m-performance-hotspot-optimization/14+13_kotlin_ws_transport_hardening/complete.log`로 충족됐다.

### [TEST-1] Kotlin Focused Full Stress Evidence

문제: 기존 기준은 [agent-test/runs/20260603-062724-proto-socket-stress-full.md](/config/workspace/proto-socket/agent-test/runs/20260603-062724-proto-socket-stress-full.md:69)에 Kotlin TCP/WS roundtrip,payload rows를 기록했지만, 14번 변경 이후의 Kotlin rows가 없다.

해결 방법: Kotlin만 대상으로 full `roundtrip,payload` stress를 실행하고 결과 파일 경로를 review에 붙인다. row에서 TCP concurrency 256, TCP 1MB, WS 1KB, WS 64KB, WS 1MB를 발췌한다.

수정 파일 및 체크리스트:

- [ ] 소스 수정 없음.
- [ ] `CODE_REVIEW-local-G06.md`: 결과 파일 경로와 Kotlin rows를 기록.

테스트 작성: 작성하지 않는다. 이 작업은 검증 실행과 evidence 정리다.

중간 검증:

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

### [TEST-2] Kotlin TCP Reference And WS Memory Guard

문제: [performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:93)는 Kotlin 1MB memory를 WS 지연 개선과 함께 관찰해야 하고, [performance-hotspot-optimization.md](/config/workspace/proto-socket/agent-roadmap/milestones/performance-hotspot-optimization.md:94)는 TCP reference 보존을 요구한다.

해결 방법: focused full stress와 필요 시 performance quick/full 결과를 비교해 TCP reference와 WS memory를 정리한다. idle host가 아니면 full baseline 판단을 확정하지 말고, 결과는 guard 후보로만 기록한다. idle host에서 가능하면 같은 host/runtime/profile baseline과 `run_performance.sh --full --baseline agent-test/runs/20260605-025842-proto-socket-performance-full.md`를 실행한다.

수정 파일 및 체크리스트:

- [ ] 소스 수정 없음.
- [ ] `CODE_REVIEW-local-G06.md`: TCP reference row, WS memory row, regression WARN 여부, idle-host 여부 기록.

테스트 작성: 작성하지 않는다. 성능 결과 파일이 검증 산출물이다.

중간 검증:

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

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| 소스 수정 없음 | TEST-1, TEST-2 |
| `agent-test/runs/YYYYMMDD-HHMMSS-proto-socket-stress-full.md` | TEST-1 |
| `agent-test/runs/YYYYMMDD-HHMMSS-proto-socket-performance-quick.md` | TEST-2 |

## 최종 검증

```bash
cd kotlin && ./gradlew test
```

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

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

idle host에서 full regression 판단이 가능한 경우 추가 실행:

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --full --baseline agent-test/runs/20260605-025842-proto-socket-performance-full.md
```

기대 결과: Kotlin tests PASS, focused full stress stability counters 0, Kotlin TCP concurrency 256/TCP 1MB reference row가 악화되지 않음, Kotlin WS 1MB memory/p99/throughput 및 queue/backlog 상태가 기록됨.

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