# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.