<!-- task=m-inbound-queue-ordering/07_python_gateway plan=1 tag=REVIEW_API -->

# Python Worker Gateway 후속 수정 계획

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

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

## 배경

첫 리뷰에서 gateway 후보 자체는 추가되었지만, process parse 실패가 빈 메시지로 dispatch되고, close가 gateway in-flight 결과를 놓치며, full queue에서 background `put` task가 backpressure/FIFO 계약을 약하게 만드는 문제가 확인되었다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active review stub의 `사용자 리뷰 요청` 섹션을 채운다. 검증 증거 공백이나 repo 내부에서 고칠 수 있는 lifecycle 문제는 사용자 리뷰 요청 대상이 아니다.

## Roadmap Targets

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

## 분석 결과

### 읽은 파일

- `agent-task/m-inbound-queue-ordering/07_python_gateway/plan_cloud_G08_0.log`
- `agent-task/m-inbound-queue-ordering/07_python_gateway/code_review_cloud_G08_0.log`
- `python/proto_socket/communicator.py`
- `python/test/test_communicator.py`
- `agent-test/local/rules.md`
- `agent-test/local/python-smoke.md`
- `agent-test/local/proto-socket-full-matrix.md`

### 범위 결정 근거

- Python communicator gateway lifecycle과 그 테스트만 수정한다.
- wire format, public parser contract, 다른 언어 구현, roadmap 문서는 수정하지 않는다.
- `gateway_type` 옵션은 유지하되, worker 결과와 coordinator enqueue 경계가 기존 parse 실패/close/backpressure 의미를 깨지 않게 한다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: process/async worker, close/cancel, queue backpressure, stdout/stderr 검증이 함께 걸린 후속 수정이다.

## 구현 체크리스트

- [ ] process gateway parse 실패가 listener/request handler에 빈 protobuf 메시지로 전달되지 않도록 worker result에 실패 상태를 보존하고 기존 parse 실패처럼 drop한다.
- [ ] gateway in-flight 작업과 queue put 작업을 추적하거나 직렬 dispatcher로 묶어 close/shutdown 시 consumer 없는 inbound queue에 결과가 남지 않게 한다.
- [ ] inbound queue full 경로에서 seq 순서와 bounded backpressure가 유지되도록 `_dispatch_gateway_result`의 background `put` 우회를 제거하거나 동일한 순서 보장 경계 안으로 이동한다.
- [ ] Python tests에 process parse 실패 drop, close 중 gateway in-flight 처리, full queue/backpressure 순서 회귀 검증을 추가한다.
- [ ] 중간 검증으로 `cd python && python3 -m pytest -q test/test_communicator.py`를 실행한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_API-1] process parse failure state

#### 문제

`_process_decode`가 parse 실패를 `None` message로만 표현하고, caller가 이를 성공으로 취급해 빈 bytes 재parse로 이어진다.

#### 해결 방법

- process worker result에 success/failure 또는 exception marker를 포함한다.
- process parse 실패는 `_InboundItem.parse_exception` 또는 동등한 실패 상태로 coordinator에 전달한다.
- 실패한 packet은 기존 `_parse` 예외 경로와 같이 listener/request handler에 전달하지 않는다.

#### 테스트 작성

- process gateway에서 invalid bytes를 수신했을 때 listener가 호출되지 않는 테스트를 추가한다.

### [REVIEW_API-2] gateway close lifecycle

#### 문제

close가 `_inbound_queue.join()`만 기다려 gateway task가 아직 결과를 enqueue하지 않은 상태를 닫힌 것으로 판단한다.

#### 해결 방법

- gateway worker task와 pending queue put task를 추적한다.
- close/shutdown 시 새 gateway 결과 enqueue를 막거나, in-flight 결과가 coordinator에서 처리/폐기될 때까지 일관되게 정리한다.
- 닫힌 후 inbound queue에 처리 불가능한 item이 남지 않게 한다.

#### 테스트 작성

- async gateway 수신 직후 close해도 close 후 inbound queue에 item이 남지 않고 task leak 없이 종료되는 테스트를 추가한다.

### [REVIEW_API-3] queue full ordering/backpressure

#### 문제

full queue에서 background `put`을 만들고 seq를 전진시키면 bounded backpressure와 FIFO enqueue 순서가 task scheduling에 맡겨진다.

#### 해결 방법

- full queue에서는 await 가능한 단일 enqueue 경계에서 순서를 보존한다.
- `_dispatch_gateway_result`가 sync 함수로 남기 어렵다면 async dispatcher/collector 구조로 바꾸어 result reorder와 inbound put을 한 흐름에서 처리한다.

#### 테스트 작성

- queue가 full인 상태에서도 후속 seq가 선행 seq를 추월하지 않고, enqueue 작업이 close 시 정리되는 테스트를 추가한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `python/proto_socket/communicator.py` | REVIEW_API-1, REVIEW_API-2, REVIEW_API-3 |
| `python/test/test_communicator.py` | REVIEW_API-1, REVIEW_API-2, REVIEW_API-3 |

## 최종 검증

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

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