<!-- task=crosstest_coverage_gaps plan=0 tag=CROSSTEST-COVERAGE -->

# Crosstest Coverage Gaps - 작업 계획

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

이 계획은 언어별 크로스테스트 matrix에서 확인된 부족분만 보강한다.
기존 20개 cross-language TCP/WS 조합은 이미 존재하므로, 새 matrix를 다시 만들기보다
같은 언어 self-cell 시나리오 균일화와 secure transport 보강/보류 문서화에 집중한다.

완료 후 `CODE_REVIEW.md`에 실제 변경 파일, 검증 결과, 보류 사유를 채우고 체크박스를 `[x]`로 갱신한다.

## 배경

현재 crosstest 파일 기준으로 Dart, Go, Kotlin, Python, TypeScript의 서로 다른 언어 조합은
서버 언어 row / 클라이언트 언어 cell 기준 20/20이 존재한다.

일반 TCP/WS cross-language 조합은 다음 4개 시나리오를 실행한다.

| Scenario | Requirement |
|----------|-------------|
| 1 | 클라이언트 fire-and-forget `TestData` 송신, 서버 수신 검증 |
| 2 | 서버가 클라이언트로 `TestData(index=200, message=push from ... server)` push |
| 3 | 단일 `sendRequest` 응답이 `index=req.index*2`, `message=echo: req.message`인지 검증 |
| 4 | 여러 동시 `sendRequest`가 nonce/responseNonce로 올바르게 매핑되는지 검증 |

부족분은 두 종류다.

1. 같은 언어 self-cell이 위 4개 시나리오를 TCP/WS 양쪽에서 동일하게 보장한다는 근거가 언어별로 균일하지 않다.
2. secure transport(TLS+TCP, WSS)는 Dart/Go 단위 테스트에는 있으나 cross-language matrix에는 없다. Kotlin/Python/TypeScript는 현재 구현 기준 secure server/client 지원이 부분적이거나 없다.

## 현재 Matrix 요약

범례:

- `CT`: package-local crosstest 존재
- `UT-ok`: 같은 언어 테스트가 TCP/WS scenario 1-4를 충족하는 것으로 확인
- `UT-gap`: 같은 언어 테스트가 일부 scenario를 빠뜨림

| Server \ Client | Dart | Go | Kotlin | Python | TypeScript |
|-----------------|------|----|--------|--------|------------|
| Dart | UT-ok 후보 | CT | CT | CT | CT |
| Go | CT | UT-gap | CT | CT | CT |
| Kotlin | CT | CT | UT-gap | CT | CT |
| Python | CT | CT | CT | UT-gap | CT |
| TypeScript | CT | CT | CT | CT | UT-gap |

구현 전 재확인 사항:

- Dart self-cell은 `dart/test/socket_test.dart`에서 TCP/WS request 동시성까지 확인된다. scenario 1/2까지 명확히 대조한 뒤 부족하면 같은 파일에만 보강한다.
- Go/Kotlin/TypeScript self-cell은 TCP/WS send-push와 단일 request-response는 있으나 동시 request-response scenario가 별도 transport 테스트에 명확하지 않다.
- Python self-cell은 TCP send/receive와 단일 request-response만 있고, Python-only WS 테스트와 동시 request-response 테스트가 부족하다.

## 작업 범위

### [SELF-1] Self-cell coverage audit 표준화

**목표**

각 언어의 같은 언어 셀이 TCP/WS scenario 1-4 중 무엇을 기존 테스트로 만족하는지 코드와 대조한다.

**수정/기록**

- `CODE_REVIEW.md`에 언어별 self-cell 감사 표를 작성한다.
- Dart가 실제로 scenario 1-4를 모두 충족하면 소스 변경 없이 `UT-ok`로 기록한다.
- 부족한 셀만 아래 항목에서 테스트를 추가한다.

### [SELF-2] Go self-cell 동시 request-response 보강

**문제**

`go/test/tcp_test.go`, `go/test/ws_test.go`에는 단일 request-response는 있으나,
cross-language scenario 4와 같은 다중 동시 request-response 검증이 명확하지 않다.

**해결 방법**

- `go/test/tcp_test.go`에 TCP concurrent `SendRequestTyped` 테스트 추가
- `go/test/ws_test.go`에 WS concurrent `SendRequestTyped` 테스트 추가
- 기존 request listener 패턴을 재사용하고, 응답 index/message를 각 요청별로 검증

**수정 파일**

- [x] `go/test/tcp_test.go`
- [x] `go/test/ws_test.go`

### [SELF-3] Kotlin self-cell 동시 request-response 보강

**문제**

`kotlin/src/test/kotlin/com/tokilabs/toki_socket/TcpTest.kt`,
`kotlin/src/test/kotlin/com/tokilabs/toki_socket/WsTest.kt`에는 단일 request-response는 있으나,
transport 레벨의 동시 request-response 검증이 명확하지 않다.

**해결 방법**

- TCP/WS 각각에 `async` 또는 `awaitAll` 기반 concurrent `sendRequestTyped` 테스트 추가
- 기존 `testParserMap()`, `freePort()`, request listener 패턴 재사용

**수정 파일**

- [x] `kotlin/src/test/kotlin/com/tokilabs/toki_socket/TcpTest.kt`
- [x] `kotlin/src/test/kotlin/com/tokilabs/toki_socket/WsTest.kt`

### [SELF-4] Python self-cell TCP/WS scenario 보강

**문제**

Python에는 `python/test/test_tcp.py`와 communicator 단위 테스트가 있으나,
Python-only WS 테스트가 없고 TCP/WS concurrent request-response 검증도 부족하다.

**해결 방법**

- `python/test/test_tcp.py`에 TCP concurrent `send_request` 테스트 추가
- Python WS 테스트 파일을 추가해 WS send-push, 단일 request-response, concurrent request-response를 검증
- 새 파일은 기존 구조상 `python/test/test_ws.py`가 가장 자연스럽다. 새 파일 생성 사유를 `CODE_REVIEW.md`에 기록한다.

**수정 파일**

- [x] `python/test/test_tcp.py`
- [x] `python/test/test_ws.py`

### [SELF-5] TypeScript self-cell 동시 request-response 보강

**문제**

`typescript/test/tcp.test.ts`, `typescript/test/ws.test.ts`에는 send-push와 단일 request-response는 있으나,
transport 레벨의 동시 request-response 검증이 명확하지 않다.

**해결 방법**

- TCP/WS 각각에 `Promise.all` 기반 concurrent `sendRequestTyped` 테스트 추가
- 기존 `parserMap()`, `TcpServer`, `WsServer`, cleanup 패턴 재사용

**수정 파일**

- [x] `typescript/test/tcp.test.ts`
- [x] `typescript/test/ws.test.ts`

### [SECURE-1] Dart <-> Go secure crosstest 추가

**문제**

Dart와 Go는 TLS+TCP 및 WSS API와 단위 테스트가 있으나 cross-language secure transport 검증이 없다.

**해결 방법**

기존 Dart/Go pairwise crosstest를 확장한다.

- Dart server -> Go client:
  - `dart/crosstest/dart_go.dart`에 TLS+TCP, WSS phases 추가
  - `go/crosstest/dart_go_client/main.go`에 `tls`/`wss` mode 추가
- Go server -> Dart client:
  - `go/crosstest/go_dart.go`에 TLS+TCP, WSS phases 추가
  - `dart/crosstest/go_dart_client.dart`에 `tls`/`wss` mode 추가
- secure phase는 최소한 `TestData` exchange와 request-response를 검증한다.
- 가능하면 일반 crosstest와 같은 scenario 1-4를 유지한다. 구현 난도가 커지면 scenario 1/3만 먼저 추가하지 말고 계획을 갱신한다.
- 인증서는 test fixture 또는 실행 중 임시 생성 방식을 사용하고, machine-global trust store는 사용하지 않는다.

**수정 파일 후보**

- [x] `dart/crosstest/dart_go.dart`
- [x] `go/crosstest/dart_go_client/main.go`
- [x] `go/crosstest/go_dart.go`
- [x] `dart/crosstest/go_dart_client.dart`
- [x] `dart/test/certs/server.crt` / `dart/test/certs/server.key` 재사용 가능 여부 확인 → SAN에 IP:127.0.0.1, DNS:localhost 포함. 재사용 가능.

### [SECURE-2] Kotlin/Python/TypeScript secure matrix 보류 사유 문서화

**문제**

secure transport matrix를 모든 언어에 적용하려면 언어별 API 지원이 필요하다. 현재 코드 기준:

- Kotlin: WSS client API는 있으나 secure WS server와 TLS+TCP API가 없다.
- Python: TCP/WS client/server에 SSL context 경로가 없다.
- TypeScript: TCP는 `net`, WS는 plain `ws://`만 사용하며 TLS/WSS wrapper가 없다.

**해결 방법**

- `CODE_REVIEW.md`에 secure matrix 보류 표를 작성한다.
- README나 언어별 README가 TLS/WSS 지원을 과하게 주장하는 경우에만 문서를 정정한다.
- secure API 구현 자체는 이 계획의 범위를 넘긴다.

**수정 파일 후보**

- [x] `CODE_REVIEW.md`
- [x] `README.md` 또는 언어별 README는 과한 지원 표기가 있을 때만 수정 → 과잉 주장 없음. 수정 불필요.

## 최종 목표 Matrix

일반 TCP/WS:

| Server \ Client | Dart | Go | Kotlin | Python | TypeScript |
|-----------------|------|----|--------|--------|------------|
| Dart | UT-ok | CT | CT | CT | CT |
| Go | CT | UT-ok | CT | CT | CT |
| Kotlin | CT | CT | UT-ok | CT | CT |
| Python | CT | CT | CT | UT-ok | CT |
| TypeScript | CT | CT | CT | CT | UT-ok |

Secure transport:

| Server \ Client | Dart | Go | Kotlin | Python | TypeScript |
|-----------------|------|----|--------|--------|------------|
| Dart | 기존 단위 테스트 | CT-secure | deferred | deferred | deferred |
| Go | CT-secure | 기존 단위 테스트 | deferred | deferred | deferred |
| Kotlin | deferred | deferred | deferred | deferred | deferred |
| Python | deferred | deferred | deferred | deferred | deferred |
| TypeScript | deferred | deferred | deferred | deferred | deferred |

## 검증 명령

Self-cell 보강 검증:

```bash
cd dart && dart test
cd go && go test ./...
cd kotlin && ./gradlew test
cd python && python3 -m pytest test/ -v
cd typescript && npm test
cd typescript && npm run check
```

Dart/Go secure crosstest 보강 검증:

```bash
cd dart && dart run crosstest/dart_go.dart
cd go && go run ./crosstest/go_dart.go
```

회귀 확인:

```bash
cd go && go run ./crosstest/go_kotlin.go
cd go && go run ./crosstest/go_python.go
cd go && go run ./crosstest/go_typescript.go
cd dart && dart run crosstest/dart_kotlin.dart
cd dart && dart run crosstest/dart_python.dart
cd dart && dart run crosstest/dart_typescript.dart
cd kotlin && ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinGoKt
cd kotlin && ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinPythonKt
cd kotlin && ./gradlew run -PmainClass=com.tokilabs.toki_socket.crosstest.KotlinTypescriptKt
cd python && python3 -m crosstest.python_dart
cd python && python3 -m crosstest.python_go
cd python && python3 -m crosstest.python_kotlin
cd python && python3 -m crosstest.python_typescript
cd typescript && node --import tsx crosstest/typescript_dart.ts
cd typescript && node --import tsx crosstest/typescript_go.ts
cd typescript && node --import tsx crosstest/typescript_kotlin.ts
cd typescript && node --import tsx crosstest/typescript_python.ts
```

정리 검증:

```bash
git diff --check
```

## 범위 밖

- Kotlin/Python/TypeScript secure transport API 신규 구현
- 새 언어 추가
- proto/schema 변경
- 기존 plain TCP/WS cross-language matrix 재작성