<!-- task=m-inbound-queue-ordering/05_go_gateway plan=2 tag=REVIEW_REVIEW_API -->

# Go Gateway Parse Error Follow-up 계획

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

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

## 배경

두 번째 루프에서 TCP/WS read loop는 gateway raw-frame 경로로 연결되었다. 하지만 gateway 부착 시 malformed raw frame은 worker decode error로 처리된 뒤 조용히 drop되어, 기존 TCP/WS parse-error disconnect semantics가 사라진다. follow-up은 이 semantics 보존과 테스트 보강만 다룬다.

## 사용자 리뷰 요청 흐름

구현 중 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-task/m-inbound-queue-ordering/05_go_gateway/code_review_cloud_G08_1.log`
- `go/communicator.go`
- `go/inbound_gateway.go`
- `go/tcp_client.go`
- `go/ws_client.go`
- `go/test/communicator_test.go`

### 테스트 환경 규칙

- Go 변경 필수 검증은 `cd go && go test -count=1 ./...`.
- concurrency/gateway error 경계 보완이므로 `cd go && go test -race ./...`를 포함한다.
- 최종 검증은 전체 matrix `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`.

### 범위 결정 근거

- gateway decode error propagation과 TCP/WS parse-error disconnect tests만 다룬다.
- worker pool reorder, raw frame wiring, proto schema, wire format, listener/request dispatch 정책은 바꾸지 않는다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: gateway worker goroutine의 error propagation과 transport close semantics가 포함된다.

## 구현 체크리스트

- [ ] gateway 부착 read path에서 raw frame decode 실패가 기존 TCP/WS parse-error disconnect semantics로 이어지도록 error propagation 경계를 보완한다.
- [ ] gateway worker는 stateful dispatch를 소유하지 않고, decode error 전달도 transport/communicator teardown 책임 경계를 침범하지 않게 구성한다.
- [ ] TCP gateway 부착 read path에서 malformed frame이 `DisconnectReasonTCPPacketParse`로 disconnect되는 테스트를 추가한다.
- [ ] WS gateway 부착 read path의 malformed frame semantics를 테스트하거나, WS를 생략한다면 TCP와 같은 `OnReceivedFrame` error path를 공유한다는 근거를 구현 기록에 남긴다.
- [ ] 기존 gateway 순서 보존, worker decode error reorder advance, read loop wiring 테스트가 계속 통과하는지 확인한다.
- [ ] 중간 검증으로 `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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_REVIEW_API-1] gateway decode error semantics 보존

#### 문제

- gateway 부착 시 `OnReceivedFrame`은 nil을 반환하고 worker가 malformed frame을 drop하므로 TCP/WS parse-error disconnect가 발생하지 않는다.
- 현재 parse-error 테스트는 gateway 미부착 경로만 다뤄 이 회귀를 잡지 못한다.

#### 해결 방법

- `WorkerGateway`가 decode error를 sink/error callback으로 전달하거나, `Communicator`가 gateway decode error를 받아 transport별 parse-error handler를 실행할 수 있게 작은 error propagation 경계를 추가한다.
- 또는 gateway submit 전에 raw frame validation을 수행하되, 성공 경로의 worker decode/reorder 이점을 과도하게 훼손하지 않는 이유를 구현 기록에 남긴다.
- 어떤 방식을 선택하든 gateway는 listener/request/pending/write queue 상태를 소유하지 않는다.

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

- [ ] `go/communicator.go`
- [ ] `go/inbound_gateway.go`
- [ ] `go/tcp_client.go`
- [ ] `go/ws_client.go`
- [ ] `go/test/communicator_test.go`
- [ ] 필요 시 `go/inbound_gateway_test.go`

#### 테스트 작성

- gateway 부착 TCP read loop에 malformed PacketBase bytes를 넣고 `DisconnectReasonTCPPacketParse`가 기록되는지 확인한다.
- 기존 `TestWorkerGatewaySkipsDecodeErrors`의 의도(한 frame decode 실패가 reorder window를 막지 않음)를 새 error propagation 모델에 맞게 유지 또는 갱신한다.
- WS도 직접 테스트할 수 있으면 malformed binary frame + gateway 부착에서 `DisconnectReasonWSPacketParse`를 확인한다.

#### 중간 검증

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

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `go/communicator.go` | REVIEW_REVIEW_API-1 |
| `go/inbound_gateway.go` | REVIEW_REVIEW_API-1 |
| `go/tcp_client.go` | REVIEW_REVIEW_API-1 |
| `go/ws_client.go` | REVIEW_REVIEW_API-1 |
| `go/test/communicator_test.go` | REVIEW_REVIEW_API-1 |
| `go/inbound_gateway_test.go` | REVIEW_REVIEW_API-1 |

## 최종 검증

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

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