<!-- task=m-inbound-queue-ordering/05_go_gateway plan=0 tag=API -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST]** 구현 후 이 파일의 구현 에이전트 소유 섹션을 실제 내용과 검증 출력으로 채우고 active 파일을 그대로 둔 채 리뷰를 요청한다. 최종화는 code-review 전용이다.

## 개요

date=2026-06-02
task=m-inbound-queue-ordering/05_go_gateway, plan=0, tag=API

## Roadmap Targets

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

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [API-1] Go gateway worker pool | [x] |

## 구현 체크리스트

- [x] Go worker gateway 타입과 내부 `seq` 포함 input/output 구조를 추가한다.
- [x] worker pool은 raw bytes decode/순수 전처리만 수행하고, pending/listener/request/write queue 상태를 소유하지 않는다.
- [x] gateway 결과를 `seq` 기준으로 reorder한 뒤 기존 `EnqueueInbound`/receive coordinator로 전달한다.
- [x] Go tests에 대량 packet decode, out-of-order worker completion, race-safe dispatch 순서 검증을 추가한다.
- [x] 중간 검증으로 `cd go && go test -count=1 ./... && go test -race ./...`를 실행하고 실제 stdout/stderr를 기록한다.
- [x] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행하고 결과 기록 파일을 남긴다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] active review/plan을 `.log`로 아카이브한다.
- [ ] PASS이면 `complete.log` 작성 후 task directory를 archive로 이동한다.
- [ ] PASS이면 runtime completion metadata를 보고하고 roadmap은 직접 수정하지 않는다.

## 계획 대비 변경 사항

- 계획의 "필요 시 Go gateway 전용 파일"을 실제로 채택해 gateway 타입과 worker pool을 새 파일 `go/inbound_gateway.go`에 분리했다. `communicator.go`에는 통합 진입점(`EnableInboundGateway`, `AttachInboundGateway`, `OnReceivedFrame`, `closeGateway`)과 필드(`gateway`, `frameSeq`)만 추가했다.
- 계획에 명시되지 않았던 디코드 실패 처리(`workerResult.err`로 seq 슬롯만 advance하고 sink로는 전달하지 않음)와 그 회귀 테스트(`TestWorkerGatewaySkipsDecodeErrors`)를 추가했다. 한 프레임의 디코드 실패가 reorder window를 영구 정지시키지 못하게 하기 위함이다.
- 테스트는 계획의 `go/test/communicator_test.go`(외부 패키지 통합 테스트)에 더해, reorder 버퍼와 out-of-order 완료를 결정론적으로 검증하기 위한 내부 패키지 테스트 `go/inbound_gateway_test.go`를 추가했다. 루트 패키지 테스트는 go 도메인 규칙상 `go/*.go`에 둘 수 있다.

## 주요 설계 결정

- **gateway = 순수 decode, coordinator = dispatch 소유.** worker는 `decodePacketBase`(PacketBase 언마샬)만 수행하고 `pendingRequests`/listeners/`writeQueue`에 접근하지 않는다. 결과는 단일 collector goroutine이 `frameReorderBuffer`로 `seq` 순서 복원 후 sink로 넘기고, sink는 기존 `OnReceivedData`(→ response면 `handleResponse`, 아니면 `EnqueueInbound`)로 라우팅한다. 따라서 stateful dispatch와 출력 순서는 기존 receive coordinator가 단독 소유한다.
- **순서 보장은 단일 collector로 직렬화.** 다수 worker가 out-of-order로 완료해도 sink를 호출하는 goroutine은 collector 하나뿐이고, `frameReorderBuffer`가 1부터 연속된 prefix만 방출하므로 sink 호출은 항상 입력 `seq` 순서다. mutex로 sink를 감싸지 않아 sink(=`EnqueueInbound` 채널)가 blocking돼도 다른 worker의 디코드를 막지 않는다.
- **backpressure는 bounded channel로.** `jobs`/`results` 채널 capacity로 자연 backpressure가 걸리며, `Submit`은 채널이 차면 block하되 `done` close 시 즉시 반환한다.
- **opt-in.** gateway 미부착 시 `OnReceivedFrame`은 호출 goroutine에서 inline 디코드하므로 기존 동작과 wire format에 영향이 없다. `seq`/`frameSeq`는 내부 정렬 전용이며 wire field가 아니다.
- **race-safety.** `gateway` 필드는 `c.mu`로 보호하고, `frameSeq`는 `atomic.Int64`, worker↔collector 통신은 채널만 사용한다. `go test -race ./...` 무경합 확인.

## 사용자 리뷰 요청

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- gateway가 stateful dispatcher 책임을 갖지 않는지 확인한다.
- `go test -race ./...` 결과가 실제 출력인지 확인한다.

## 검증 결과

### API-1 중간 검증
```
$ cd go && go test -count=1 ./...
ok  	git.toki-labs.com/toki/proto-socket/go	0.042s
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/dart_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/kotlin_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/python_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/typescript_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/examples/tcp_echo	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/examples/ws_echo	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/packets	[no test files]
ok  	git.toki-labs.com/toki/proto-socket/go/test	8.189s

$ cd go && go test -race ./...
ok  	git.toki-labs.com/toki/proto-socket/go	1.052s
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/dart_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/kotlin_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/python_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/crosstest/typescript_go_client	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/examples/tcp_echo	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/examples/ws_echo	[no test files]
?   	git.toki-labs.com/toki/proto-socket/go/packets	[no test files]
ok  	git.toki-labs.com/toki/proto-socket/go/test	9.234s
```

추가된 테스트: `TestFrameReorderBufferReleasesInOrder`, `TestWorkerGatewayReordersOutOfOrderCompletion`, `TestWorkerGatewaySkipsDecodeErrors`(go/inbound_gateway_test.go), `TestInboundGatewayPreservesDispatchOrder`(go/test/communicator_test.go).

### 최종 검증
```
$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
```

- 결과: 전 항목 PASS. Proto 동기화 PASS, 동일언어 5/5 PASS, 언어 PASS 매트릭스 5x7 전부 PASS, 크로스테스트 30방향 전부 expected 일치 PASS.
- 결과 기록 파일: `agent-test/runs/20260602-015124-proto-socket-full-matrix.md`

## 코드리뷰 결과

- 종합 판정: FAIL
- 차원별 평가:
  - correctness: Fail
  - completeness: Fail
  - test coverage: Fail
  - API contract: Warn
  - code quality: Pass
  - plan deviation: Fail
  - verification trust: Pass
- 발견된 문제:
  - Required: `go/tcp_client.go:83`와 `go/ws_client.go:98`의 실제 transport read loop가 여전히 raw frame을 직접 `proto.Unmarshal`한 뒤 `OnReceivedData`로 전달한다. 따라서 `EnableInboundGateway`/`AttachInboundGateway`를 호출해도 TCP/WS 실연결 수신 경로는 gateway를 전혀 통과하지 않아, 계획의 worker gateway 적용 및 `seq` reorder 후 coordinator 전달 조건이 충족되지 않는다. read loop가 gateway 부착 여부를 반영하는 raw-frame 진입점을 사용하도록 연결하고, 기존 parse 실패 disconnect semantics도 유지해야 한다.
  - Required: `go/test/communicator_test.go:333`의 신규 통합 테스트는 `Communicator.OnReceivedFrame`을 직접 호출해서 새 helper만 검증한다. 실제 `TcpClient.readLoop`/`WsClient.readLoop`가 gateway를 사용하는지 검증하지 못하므로 위 누락을 잡지 못한다. TCP 또는 WS 실제 read path에서 gateway가 부착된 경우 raw frame이 gateway sink를 거쳐 dispatch되는 테스트와 parse error 동작 테스트를 추가해야 한다.
- 다음 단계: WARN/FAIL follow-up으로 다음 active `PLAN-cloud-G08.md`와 `CODE_REVIEW-cloud-G08.md`를 작성한다.
