<!-- task=m-inbound-queue-ordering/03+02_gateway_contract plan=1 tag=REVIEW_API -->

# Worker Gateway 계약 보완 계획

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

이 계획은 구현 에이전트가 읽고 실행한다. 구현 후 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션에 실제 변경 내용, 검증 명령, stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 사용자 결정, 사용자 소유 환경, scope 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션을 채우고 중단한다. `complete.log` 작성, archive 이동, 최종 판정은 code-review 전용이다.

## 배경

이전 리뷰에서 `gateway-contract`가 FAIL 판정을 받았다. 문서에는 worker gateway/internal `seq` 계약이 없고, Dart/Kotlin/TypeScript에는 fake gateway reorder anchor 테스트가 없으며, review stub에 기록된 중간 검증 출력이 실제 파일 내용과 불일치했다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 결정 필요 항목과 실행한 명령 출력을 기록한다. code-review가 정당성을 검토하고 실제 `USER_REVIEW.md` 작성 여부를 판단한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `gateway-contract`: worker gateway 계약을 문서화한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-task/m-inbound-queue-ordering/03+02_gateway_contract/plan_cloud_G06_0.log`
- `agent-task/m-inbound-queue-ordering/03+02_gateway_contract/code_review_cloud_G06_0.log`
- `PROTOCOL.md`
- `PORTING_GUIDE.md`
- `dart/test/communicator_test.dart`
- `go/test/communicator_test.go`
- `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`
- `python/test/test_communicator.py`
- `typescript/test/communicator.test.ts`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`

### 실패 원인

- `PROTOCOL.md`에는 inbound queue와 receive coordinator 계약만 있고 worker gateway/internal `seq` 계약이 없다.
- `PORTING_GUIDE.md`에는 gateway가 pending response map, listener/request handler, write queue, stateful dispatch를 소유하지 않는다는 포팅 기준이 없다.
- Go/Python에는 fake gateway reorder 테스트가 있으나 Dart/Kotlin/TypeScript에는 같은 anchor가 없다.
- 이전 review stub의 검증 출력은 현재 파일 내용과 맞지 않으므로 실제 명령 재실행 결과를 다시 기록해야 한다.

### 빌드 등급

- build: `cloud-G07`, review: `cloud-G07`
- 이유: FAIL 후속이며 검증 신뢰 회복이 핵심이다. 문서/API 계약과 다언어 테스트 anchor를 동시에 확인해야 한다.

## 구현 체크리스트

- [ ] `PROTOCOL.md`에 worker gateway/internal `seq` 계약을 추가한다. `seq`는 wire format이 아니라 read side가 붙이는 내부 구현값이며 gateway는 raw bytes decode/순수 전처리만 수행한다고 명시한다.
- [ ] `PORTING_GUIDE.md`에 worker gateway boundary를 추가한다. gateway가 pending response map, listener/request handler, write queue, stateful dispatch를 소유하지 않는다고 명시한다.
- [ ] Dart/Kotlin/TypeScript receive coordinator 테스트에 fake gateway 결과가 out-of-order로 도착해도 dispatch/response enqueue가 `seq` 순서를 따른다는 anchor를 추가한다.
- [ ] 중간 검증으로 문서/테스트 검색과 Dart/Kotlin/TypeScript 단위 테스트를 실행하고 실제 stdout/stderr를 기록한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행하고 실제 stdout/stderr 및 결과 기록 파일을 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_API-1] Gateway Contract Docs

#### 문제

- `PROTOCOL.md:167` 아래에는 inbound queue/coordinator 계약만 있고 worker gateway/internal `seq` 계약이 없다.
- `PORTING_GUIDE.md:14`의 핵심 구조에는 gateway boundary가 없다.

#### 해결 방법

- `PROTOCOL.md`의 receive ordering 섹션에 `Worker Gateway and Internal seq` 하위 섹션을 추가한다.
- `PORTING_GUIDE.md`의 핵심 구조 근처에 `Worker gateway boundary` 섹션 또는 표 항목을 추가한다.
- 두 문서 모두 wire schema 변경이 아니라 내부 구현 sequence임을 명확히 쓴다.

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

- [ ] `PROTOCOL.md`
- [ ] `PORTING_GUIDE.md`

#### 테스트 작성

- 문서 변경이므로 테스트 코드는 없음. 중간 검증에서 `rg`로 gateway/internal seq/stateful dispatch 금지 문구를 확인한다.

#### 중간 검증

```bash
rg --sort path -n "Worker Gateway|Worker gateway|internal `?seq|stateful dispatch|pending response|write queue|wire format" PROTOCOL.md PORTING_GUIDE.md
```

기대 결과: `PROTOCOL.md`와 `PORTING_GUIDE.md` 모두에서 worker gateway, internal seq, stateful dispatch 금지, wire format 비변경 문구가 검색된다.

### [REVIEW_API-2] Missing Gateway Reorder Tests

#### 문제

- `dart/test/communicator_test.dart:301`, `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt:149`, `typescript/test/communicator.test.ts:294`에는 일반 FIFO 테스트만 있다.
- 계획은 fake gateway 결과가 `seq=2`, `seq=1`로 도착해도 coordinator dispatch/response enqueue가 `1`, `2` 순서를 따르는 anchor를 요구했다.

#### 해결 방법

- Go/Python 테스트의 intent를 각 언어 관례에 맞게 Dart/Kotlin/TypeScript에 추가한다.
- public gateway API를 만들지 말고 test-local fake item/helper로 `seq` 기준 정렬 후 기존 coordinator path에 주입한다.
- 가능하면 listener dispatch와 request response enqueue 중 최소 하나를 명확히 검증한다. 기존 coordinator path 한계상 둘 다 간결하게 검증할 수 있으면 둘 다 검증한다.

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

- [ ] `dart/test/communicator_test.dart`
- [ ] `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`
- [ ] `typescript/test/communicator.test.ts`

#### 테스트 작성

- Dart: `seq=2`, `seq=1` fake gateway item을 정렬해 `_FakeCommunicator.onReceivedData` 또는 공개 테스트 hook에 넣고 listener 수신 순서가 `[1, 2]`인지 확인한다.
- Kotlin: 같은 구조로 `Communicator.onReceivedData`에 넣고 listener 수신 순서가 `[1, 2]`인지 확인한다.
- TypeScript: 같은 구조로 `Communicator.onReceivedData` 또는 `enqueueInbound`에 넣고 listener 수신 순서가 `[1, 2]`인지 확인한다.

#### 중간 검증

```bash
rg --sort path -n "WorkerGateway|worker gateway|gateway reorder|seq=2|seq: 2|seq = 2" dart/test kotlin/src/test typescript/test
dart test test/communicator_test.dart
env JAVA_HOME=/config/opt/jdk/jdk-17.0.10+7 GRADLE_USER_HOME=/tmp/gradle ./gradlew test --tests com.tokilabs.proto_socket.CommunicatorTest
npm test -- communicator
```

기대 결과: 세 언어 테스트 파일에서 gateway reorder anchor가 검색되고, 각 언어의 communicator 테스트가 통과한다.

## 최종 검증

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

기대 결과: exit code 0, matrix 결과 파일의 최종 결과값 PASS.

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