<!-- task=m-inbound-queue-ordering/01_contract_docs plan=0 tag=API -->

# 수신 큐 계약 문서화 계획

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

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

## 배경

현재 `PROTOCOL.md`는 wire format, nonce, request-response를 정의하지만 수신 처리 순서, 자동 응답 순서, inbound queue capacity, close/drain/cancel 정책은 비어 있다. 첫 Epic의 `recv-contract`는 이후 언어별 구현이 같은 기준으로 움직이도록 관찰 가능한 수신 계약을 먼저 고정해야 한다.

## 사용자 리뷰 요청 흐름

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

## Roadmap Targets

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

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/private/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-roadmap/current.md`
- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/rules/project/domain/protocol/rules.md`
- `agent-ops/rules/project/domain/tools/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `PROTOCOL.md`
- `PORTING_GUIDE.md`
- `README.md`

### 테스트 환경 규칙

- test_env: `local`
- 적용 규칙: `agent-test/local/rules.md`, `agent-test/local/proto-socket-full-matrix.md`
- 최종 검증은 protocol/API 계약 문서 변경이므로 full-cycle 명령 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 사용한다.
- 확인: `/bin/bash`와 matrix script가 존재한다. Dart, Go, Python, npm, Java runtime 경로도 확인했다.

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

- 수신 순서 계약 문서화: 기존 테스트는 일부 순서만 확인한다. Dart TCP 일반 수신 순서 테스트는 있지만 문서 계약 자체를 검증하지 않는다.
- inbound queue capacity와 close/drain/cancel 정책: 송신 write queue 테스트는 일부 있으나 inbound queue 계약 테스트는 없다. 이 계획은 문서 계약만 완료하고 구현/테스트 보강은 뒤 subtask에서 처리한다.

### 심볼 참조

- rename/remove 없음.

### 분할 판단

- 첫 Epic 전체는 문서, 다섯 언어 수신 처리, gateway 경계가 섞여 있어 split 대상이다.
- 이 subtask는 `recv-contract` 문서 계약만 다룬다.
- 같은 task group의 sibling:
  - `01_contract_docs`: 선행 문서 계약, 의존 없음.
  - `02+01_receive_thread_model`: 01 완료 뒤 언어별 수신 coordinator와 thread model 반영.
  - `03+02_gateway_contract`: 02 완료 뒤 worker gateway 경계 문서와 테스트 anchor 반영.

### 범위 결정 근거

- proto schema, generated packet binding, wire framing bytes는 변경하지 않는다.
- 실제 inbound queue 구현과 언어별 테스트 추가는 `02+01_receive_thread_model`에서 처리한다.
- gateway worker 구현은 범위 제외다.

### 빌드 등급

- build: `cloud-G05`, review: `cloud-G05`
- 이유: 문서 중심이지만 protocol/API 계약 문서이며 이후 concurrency 구현의 기준이 된다.

## 구현 체크리스트

- [ ] `PROTOCOL.md`에 per-connection inbound queue ordering, automatic response ordering, capacity/backpressure, close/drain/cancel 계약을 추가한다.
- [ ] `PORTING_GUIDE.md`의 공통 구조에 inbound queue/coordinator 항목을 추가하고 새 언어 구현 기준을 맞춘다.
- [ ] `README.md`의 설계 원칙 또는 프로토콜 안내가 새 계약 위치를 가리키도록 최소 문구를 보강한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Inbound Queue Contract Docs

#### 문제

- `PROTOCOL.md:140`의 request-response 규칙은 응답 상관관계만 설명하고, 같은 connection에서 수신된 일반 메시지와 request가 어떤 순서로 dispatch되는지 정의하지 않는다.
- `PORTING_GUIDE.md:14`의 핵심 구조 표에는 write queue는 암시되어 있지만 inbound queue와 receive coordinator가 없다.
- `README.md:25`의 설계 원칙은 프로토콜 표준화 범위를 설명하지만 수신 처리 계약 문서 위치를 안내하지 않는다.

#### 해결 방법

`PROTOCOL.md`의 request-response 섹션 뒤에 `Receive Ordering and Backpressure` 섹션을 추가한다.

Before:

```md
PROTOCOL.md:158
**Rules:**
- `responseNonce == 0`: regular message or outgoing request → routed to `addListener` or `addRequestListener`
```

After:

```md
## Receive Ordering and Backpressure

- Each connection owns one bounded FIFO inbound queue between frame parsing and stateful dispatch.
- The read loop parses complete frames and enqueues packet envelopes in arrival order.
- A single receive coordinator matches pending responses, invokes listeners, runs request handlers, and enqueues automatic responses through the existing write queue.
```

`PORTING_GUIDE.md`의 공통 핵심 구조 표에는 inbound queue, receive coordinator, close/drain/cancel 정책을 추가한다. `README.md`에는 상세 계약은 `PROTOCOL.md`와 `PORTING_GUIDE.md`를 보라는 한 문장을 추가한다.

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

- [ ] `PROTOCOL.md`: 수신 FIFO, 자동 응답 순서, capacity/backpressure, close/drain/cancel 정의.
- [ ] `PORTING_GUIDE.md`: 새 언어 구현이 따라야 하는 inbound queue/coordinator 구조 추가.
- [ ] `README.md`: 공개 snapshot에서 수신 처리 계약 문서 위치 안내.

#### 테스트 작성

문서 계약 subtask이므로 새 테스트는 작성하지 않는다. 실제 inbound queue 동작 테스트는 `02+01_receive_thread_model`에서 추가한다.

#### 중간 검증

```bash
rg --sort path -n "Receive Ordering|inbound queue|receive coordinator|backpressure|drain|cancel" PROTOCOL.md PORTING_GUIDE.md README.md
```

기대 결과: 세 문서에서 새 계약 문구가 검색된다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `PROTOCOL.md` | API-1 |
| `PORTING_GUIDE.md` | API-1 |
| `README.md` | 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
