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

# Go Worker Gateway 구현 계획

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

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

## 배경

`go-gateway`는 Go에서 goroutine worker pool과 bounded channel 기반 gateway 후보를 추가하는 concurrency 작업이다. 현재 Go는 inbound queue/receive loop와 fake gateway reorder test는 있지만 실제 gateway worker pool은 없다. gateway는 decode/순수 전처리만 수행하고 coordinator가 `seq` 순서 복원과 dispatch를 소유해야 한다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active `CODE_REVIEW-cloud-G08.md`의 `사용자 리뷰 요청` 섹션에 결정 필요 항목과 실행한 명령 출력을 기록한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `go-gateway`: Go goroutine worker pool 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/go-smoke.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `go/communicator.go`
- `go/test/communicator_test.go`

### 테스트 환경 규칙

- test_env: local. Go 변경 필수 검증은 `cd go && go test ./...`.
- concurrency 공유 상태 검증이므로 중간 검증에 `go test -race ./...`를 포함한다.
- 최종 검증은 전체 matrix `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`.

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

- fake gateway reorder test만 있고 실제 worker pool out-of-order completion, bounded queue, race detector 검증이 없다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- 언어별 gateway는 독립 작업이다. 이 plan은 `05_go_gateway`이며 dependency 없음.

### 범위 결정 근거

- Go communicator/gateway와 Go tests만 다룬다. proto schema, public wire field, app-level ordering key는 제외한다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: goroutine, bounded channel, race-free state ownership이 핵심이다.

## 구현 체크리스트

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

### [API-1] Go gateway worker pool

#### 문제

- `go/communicator.go`는 `inboundQueue`와 `receiveLoop`만 있고 gateway worker pool이 없다.

#### 해결 방법

- 내부 gateway input/output 타입에 `seq`, `typeName`, raw bytes를 둔다.
- worker pool 결과를 collector가 `seq` 순서로 정렬/버퍼링한 뒤 coordinator에 넘긴다.

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

- [ ] `go/communicator.go`
- [ ] 필요 시 Go gateway 전용 파일
- [ ] `go/test/communicator_test.go`

#### 테스트 작성

- worker 결과가 `seq=2` 먼저, `seq=1` 나중에 도착해도 dispatch는 `[1,2]`인지 확인한다.
- `go test -race ./...`로 공유 상태 경합이 없는지 확인한다.

#### 중간 검증

```bash
cd go && go test -count=1 ./... && go test -race ./...
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `go/communicator.go` | API-1 |
| `go/test/communicator_test.go` | API-1 |

## 최종 검증

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

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