<!-- task=m-inbound-queue-ordering/06_kotlin_gateway plan=0 tag=API -->

# Kotlin Worker Gateway 구현 계획

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

구현 후 `CODE_REVIEW-cloud-G08.md`의 구현 에이전트 소유 섹션에 실제 변경 내용과 검증 stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 최종 판정과 archive는 code-review 전용이다.

## 배경

`kotlin-gateway`는 coroutine worker pool 또는 제한된 dispatcher 기반 gateway 후보를 추가하는 작업이다. 현재 Kotlin은 inbound `Channel`과 receive coroutine은 있지만 실제 gateway worker pool은 없다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active review stub의 `사용자 리뷰 요청` 섹션을 채운다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `kotlin-gateway`: Kotlin coroutine worker gateway 후보를 적용한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-test/local/rules.md`
- `agent-test/local/kotlin-smoke.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt`
- `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`

### 테스트 환경 규칙

- Kotlin 변경 필수 검증: `cd kotlin && ./gradlew test`.
- 최종 검증: 전체 matrix.

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

- fake gateway reorder는 있지만 coroutine worker pool out-of-order completion, actor/coordinator ownership, close/cancel 검증이 없다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- `06_kotlin_gateway`는 독립 언어 task이며 dependency 없음.

### 범위 결정 근거

- Kotlin communicator/gateway와 tests만 수정한다. OkHttp WS staging 정책, proto schema, app-level handler pool은 제외한다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: coroutine worker/actor ownership과 ordering risk가 있다.

## 구현 체크리스트

- [ ] Kotlin gateway input/output에 내부 `seq`를 포함하고 coroutine worker pool 또는 제한 dispatcher를 추가한다.
- [ ] gateway는 decode/전처리만 수행하고 pending/listener/request/write queue 상태를 소유하지 않는다.
- [ ] 결과 collector가 `seq` 순서로 receive coordinator에 전달한다.
- [ ] Kotlin tests에 out-of-order worker completion, 대량 packet 순서, close/cancel anchor를 추가한다.
- [ ] 중간 검증으로 `cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle ./gradlew test --tests com.tokilabs.proto_socket.CommunicatorTest --rerun-tasks`를 실행한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Kotlin coroutine gateway

#### 문제

- `Communicator.kt`는 receive coroutine만 있고 gateway worker candidate가 없다.

#### 해결 방법

- coroutine worker pool/collector를 두고 collector만 coordinator path에 결과를 넣는다.

#### 수정 파일 및 체크리스트

- [ ] `kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt`
- [ ] `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`

#### 테스트 작성

- `seq=2`가 먼저 완료되어도 dispatch order는 `[1,2]`인지 확인한다.

#### 중간 검증

```bash
cd kotlin && env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle ./gradlew test --tests com.tokilabs.proto_socket.CommunicatorTest --rerun-tasks
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt` | API-1 |
| `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt` | API-1 |

## 최종 검증

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

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