<!-- task=m-inbound-queue-ordering/07_python_gateway plan=0 tag=API -->

# Python Worker Gateway 구현 계획

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

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

## 배경

`python-gateway`는 Python에서 CPU-bound decode는 process worker 후보로, 경량 전처리는 asyncio worker 후보로 분리하는 작업이다. 현재 Python은 `asyncio.Queue` receive task와 fake gateway reorder test만 있고 실제 gateway on/off 후보가 없다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active review stub의 `사용자 리뷰 요청` 섹션을 채운다.

## 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-roadmap/current.md`
- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-test/local/rules.md`
- `agent-test/local/python-smoke.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `python/proto_socket/communicator.py`
- `python/test/test_communicator.py`

### 테스트 환경 규칙

- Python 변경 필수 검증: `cd python && python3 -m pytest -q`.
- 최종 검증: 전체 matrix.

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

- 실제 gateway on/off, out-of-order worker completion, close/cancel, small packet fallback 검증이 없다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- `07_python_gateway`는 독립 언어 task이며 dependency 없음.

### 범위 결정 근거

- Python communicator/gateway와 tests만 수정한다. 외부 dependency 추가는 피하고 standard library `asyncio`/`concurrent.futures`를 우선한다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: process/async worker와 close/cancel/order 경계가 있다.

## 구현 체크리스트

- [ ] Python gateway input/output에 내부 `seq`를 포함하고 asyncio worker 또는 process worker 후보를 추가한다.
- [ ] gateway는 decode/전처리만 수행하고 pending/listener/request/write queue 상태를 소유하지 않는다.
- [ ] 작은 packet에서는 gateway off fallback이 기존 receive coordinator path를 사용하도록 한다.
- [ ] Python tests에 out-of-order worker completion, fallback, close/cancel 순서 검증을 추가한다.
- [ ] 중간 검증으로 `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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Python gateway worker candidate

#### 문제

- `python/proto_socket/communicator.py`에는 실제 gateway 후보가 없다.

#### 해결 방법

- asyncio worker path와 CPU-bound process worker 후보를 표준 라이브러리로 구성한다.
- 결과 collector가 `seq` 순서로 기존 `enqueue_inbound`/coordinator path에 넘긴다.

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

- [ ] `python/proto_socket/communicator.py`
- [ ] `python/test/test_communicator.py`

#### 테스트 작성

- out-of-order worker result가 `[1,2]`로 dispatch되는지 검증한다.
- gateway off fallback이 기존 테스트와 동일 path를 사용하는지 검증한다.

#### 중간 검증

```bash
cd python && python3 -m pytest -q test/test_communicator.py
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `python/proto_socket/communicator.py` | API-1 |
| `python/test/test_communicator.py` | API-1 |

## 최종 검증

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

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