<!-- task=m-inbound-queue-ordering/03+02_gateway_contract plan=0 tag=API -->

# Worker Gateway 계약 계획

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

이 계획은 구현 에이전트가 읽고 실행한다. 구현 후 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션에 실제 변경 내용, 검증 명령, stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 사용자 결정, 사용자 소유 환경, scope 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션을 채우고 중단한다. `complete.log` 작성, archive 이동, 최종 판정은 code-review 전용이다.

## 배경

Milestone은 대량 raw packet 처리와 decode/전처리를 worker gateway 후보로 분리하되, stateful dispatch는 receive coordinator가 소유해야 한다. `gateway-contract`는 실제 worker 구현 전에 gateway가 어떤 일을 할 수 없고, 어떤 순서 복원 책임을 coordinator에 남겨야 하는지 문서와 테스트 anchor로 고정한다.

## 사용자 리뷰 요청 흐름

구현 중 user-only blocker가 있으면 active `CODE_REVIEW-cloud-G06.md`의 `사용자 리뷰 요청` 섹션에 결정 필요 항목과 실행한 명령 출력을 기록한다. code-review가 정당성을 검토하고 실제 `USER_REVIEW.md` 작성 여부를 판단한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `gateway-contract`: worker gateway 계약을 문서화한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `PROTOCOL.md`
- `PORTING_GUIDE.md`
- `dart/lib/src/communicator.dart`
- `go/communicator.go`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt`
- `python/proto_socket/communicator.py`
- `typescript/src/communicator.ts`
- `typescript/test/communicator.test.ts`

### 테스트 환경 규칙

- test_env: `local`
- 적용 규칙: `agent-test/local/rules.md`, `agent-test/local/proto-socket-full-matrix.md`
- gateway 계약은 protocol/API 수준의 concurrency 경계이므로 최종 검증은 full matrix다.

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

- gateway on/off나 seq reorder 테스트는 아직 없다.
- TypeScript에는 write queue 포화 테스트가 있으나 gateway가 stateful dispatch를 소유하지 않는다는 테스트는 없다.
- 이 subtask는 gateway 구현을 만들지 않고, receive coordinator가 seq reorder와 dispatch를 소유한다는 계약 및 future-test anchor를 추가한다.

### 심볼 참조

- rename/remove 없음.
- 현재 gateway 관련 symbol 없음. 새 API를 만들지 않는 것이 기본이다.

### 분할 판단

- 이 subtask는 `02+01_receive_thread_model` 완료 뒤 수행한다. receive coordinator가 없으면 gateway 경계가 추상 문서에 머물기 때문이다.
- 실제 gateway 구현은 Milestone의 `[gateway]` Epic으로 남긴다.

### 범위 결정 근거

- Dart isolate, Go worker pool, Kotlin dispatcher, Python process pool, TypeScript worker_threads/Web Worker 구현은 하지 않는다.
- packet schema와 transport framing은 변경하지 않는다.
- 테스트는 gateway 구현을 요구하지 않는 coordinator ownership/seq ordering anchor 위주로 둔다.

### 빌드 등급

- build: `cloud-G06`, review: `cloud-G06`
- 이유: 문서와 테스트 anchor 중심이지만 향후 worker 병렬화의 concurrency 경계를 고정한다.

## 구현 체크리스트

- [ ] `PORTING_GUIDE.md`에 worker gateway 계약을 추가한다. gateway는 raw bytes/decode/순수 전처리만 수행하고 listener/request handler/pending map/write queue를 소유하지 않는다고 명시한다.
- [ ] `PROTOCOL.md` 또는 `PORTING_GUIDE.md`에 `seq` 기반 reorder와 coordinator 단독 dispatch 책임을 명시한다. wire field 추가가 아니라 내부 구현 sequence임을 분명히 한다.
- [ ] receive coordinator 테스트에 gateway 결과가 out-of-order로 도착해도 dispatch/response enqueue가 입력 seq 순서를 따른다는 future-proof hook 또는 fake gateway 테스트를 추가한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Gateway Boundary Contract

#### 문제

- `agent-roadmap/milestones/inbound-queue-ordering.md`는 gateway 후보를 상세히 적지만, public guide에는 gateway가 stateful dispatch를 소유하면 안 된다는 기준이 없다.
- 현재 communicator들은 stateful routing과 pending response matching을 직접 갖고 있다. 예: `go/communicator.go:255`, `python/proto_socket/communicator.py:198`, `typescript/src/communicator.ts:258`.

#### 해결 방법

`PORTING_GUIDE.md`에 `Worker gateway boundary` 섹션을 추가한다.

Before:

```md
PORTING_GUIDE.md:14
### 반드시 유지해야 하는 구조
```

After:

```md
### Worker gateway boundary

- Gateway input/output carries an internal `seq` assigned by the read side.
- Gateway may parse raw bytes or perform pure preprocessing only.
- The receive coordinator owns reorder-by-seq, pending response matching, listener dispatch, request handler execution, and automatic response enqueue.
```

테스트는 실제 worker 구현 없이 fake gateway/reorder helper를 통해 coordinator가 seq 순서를 보존하는 anchor를 둔다. 구현체가 아직 gateway를 지원하지 않는 언어는 gateway off fallback에서도 같은 coordinator path를 사용해야 한다.

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

- [ ] `PORTING_GUIDE.md`
- [ ] 필요 시 `PROTOCOL.md`에 internal seq가 wire format이 아니라 구현 내부 값임을 짧게 명시
- [ ] 각 언어 coordinator 테스트 파일 중 `02+01_receive_thread_model`에서 만든 fake inbound/gateway hook 위치

#### 테스트 작성

테스트를 작성한다. 언어별 receive coordinator가 fake decoded result를 `seq=2`, `seq=1` 순서로 받아도 listener/request response enqueue는 `1`, `2` 순서로 발생하는지 확인한다. gateway API가 아직 없는 언어는 private test hook 또는 helper를 사용하고 public API를 만들지 않는다.

#### 중간 검증

```bash
rg --sort path -n "gateway|seq|receive coordinator|stateful dispatch|pending response" PROTOCOL.md PORTING_GUIDE.md dart/test go/test kotlin/src/test python/test typescript/test
```

기대 결과: 문서와 테스트에 gateway 경계와 seq 순서 anchor가 검색된다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `PORTING_GUIDE.md` | API-1 |
| `PROTOCOL.md` | API-1 |
| 언어별 coordinator 테스트 파일 | API-1 |

## 최종 검증

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

기대 결과: exit code 0, matrix 결과 파일의 최종 결과값 PASS.

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