<!-- task=m-inbound-queue-ordering/09_verify_ordering plan=0 tag=TEST -->

# Plan - TEST Ordering Verification

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

이 계획의 구현이 끝나도 작업은 완료가 아니다. 반드시 같은 디렉터리의 `CODE_REVIEW-*-G??.md`에서 구현 에이전트 소유 섹션을 실제 구현 내용, 검증 출력, 계획 대비 변경 사항으로 채운 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종 판정, archive, `complete.log` 작성은 code-review 전용이다. 구현 중 사용자 결정, 사용자 소유 외부 환경, scope 충돌이 필요하면 review stub의 `사용자 리뷰 요청` 섹션을 근거와 함께 채우고 멈춘다. 단순 검증 증거 공백은 후속 에이전트가 명령 재실행으로 해소할 수 있으므로 사용자 리뷰 요청이 아니다.

## 배경

Milestone의 `impl`과 `gateway` Epic은 완료되었지만 `verify` Epic의 `unit-order`, `slow-handler`, `queue-close` task는 아직 Roadmap Completion 근거가 없다. 현재 5개 언어 communicator 테스트에는 관련 검증이 이미 있지만, 일부 언어는 close/drain/queue-full cleanup의 조합 검증이 약하다. 이 작업은 기존 테스트 파일 안에서 누락된 ordering/slow/close 증거를 보강하고 세 task를 PASS 시 체크할 수 있게 만든다.

## 사용자 리뷰 요청 흐름

구현 중 차단은 active `CODE_REVIEW-cloud-G08.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 요청의 정당성을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `unit-order`: 모든 지원 언어에 순서 보장 테스트를 추가한다.
  - `slow-handler`: 모든 지원 언어에 느린 request handler 테스트를 추가한다.
  - `queue-close`: 모든 지원 언어에 큐 포화와 연결 종료 테스트를 추가한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/ROADMAP.md`
- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `agent-ops/rules/project/domain/dart/rules.md`
- `agent-ops/rules/project/domain/go/rules.md`
- `agent-ops/rules/project/domain/kotlin/rules.md`
- `dart/lib/src/communicator.dart`
- `dart/test/communicator_test.dart`
- `dart/pubspec.yaml`
- `go/communicator.go`
- `go/test/communicator_test.go`
- `go/inbound_gateway_test.go`
- `go/go.mod`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt`
- `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`
- `kotlin/build.gradle.kts`
- `python/proto_socket/communicator.py`
- `python/test/test_communicator.py`
- `python/pyproject.toml`
- `typescript/src/communicator.ts`
- `typescript/test/communicator.test.ts`
- `typescript/package.json`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`

### 테스트 환경 규칙

- `test_env=local`; `agent-test/local/rules.md` present/read.
- 적용 profile: `agent-test/local/proto-socket-full-matrix.md`.
- 기본 최종 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`.
- 범위 축소 중간 검증: Dart `dart test test/communicator_test.dart`, Go `go test -count=1 ./...`, Kotlin `./gradlew test --tests com.tokilabs.proto_socket.CommunicatorTest --rerun-tasks`, Python `python3 -m pytest -q test/test_communicator.py`, TypeScript `npm test -- communicator`.
- `<확인 필요>` 값 없음. fallback 없음.

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

- `unit-order`: Dart lines 317-340, Go lines 127-168, Kotlin `testInboundQueueFifoOrder`, Python lines 164-187, TypeScript lines 325-348에 기본 FIFO가 있다. 누락: queue-full과 close cleanup까지 묶은 cross-language evidence는 Python에만 강하다.
- `slow-handler`: Dart lines 392-426, Go lines 170-209, Kotlin `testSlowRequestHandlerResponseFifo`, Python lines 191-218, TypeScript lines 350-380에 기본 응답 순서가 있다. 누락: close/drain과 slow handler의 조합은 Dart/Go에서 약하다.
- `queue-close`: Dart lines 342-390, 428-450; Go lines 211-245; Kotlin `testInboundBackpressureOnHeavyLoad`, `testGracefulCloseDrainsInFlight`; Python lines 221-319, 561-596; TypeScript lines 382-479에 관련 검증이 있다. 누락: Go inbound queue full block/resume와 Dart/Go graceful close drain 검증을 명시적으로 보강해야 한다.

### 심볼 참조

- renamed/removed symbol 없음.

### 분할 판단

- split decision policy를 먼저 평가했다.
- shared task group: `agent-task/m-inbound-queue-ordering`.
- sibling `09_verify_ordering`: 언어별 communicator test 보강. predecessor 없음.
- sibling `10+09_stress_baseline`: benchmark/stress 기준선. predecessor `09` 완료 후 진행.
- 분할 이유: 단위 검증 보강은 기존 테스트 파일 중심이고, stress baseline은 별도 runner/measurement/output contract라 risk와 검증 방식이 다르다.

### 범위 결정 근거

- proto schema, wire format, public API rename은 제외한다.
- gateway 구현 변경은 regression이 드러날 때만 최소 수정한다. 기본 목표는 tests/evidence 보강이다.
- crosstest matrix script는 최종 검증으로만 사용하고 이 task에서는 benchmark runner를 추가하지 않는다.

### 빌드 등급

- build=`cloud-G08`, review=`cloud-G08`. 다중 언어, concurrency/ordering 검증, close semantics 리스크가 있어 cloud 고등급으로 둔다.

## 구현 체크리스트

- [ ] Dart/Go의 close-drain 및 queue-full cleanup 누락을 기존 communicator test 안에 보강한다.
- [ ] 5개 언어의 ordering/slow-handler/queue-close 검증 이름과 assertion이 Roadmap task 의미와 직접 대응되는지 정리한다.
- [ ] 언어별 focused test와 전체 local matrix를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## TEST-1 Dart close/drain ordering 보강

### 문제

[communicator.dart](/config/workspace/proto-socket/dart/lib/src/communicator.dart:314)는 `close()`에서 `_inboundDispatch`를 기다린 뒤 pending을 취소한다. [communicator_test.dart](/config/workspace/proto-socket/dart/test/communicator_test.dart:342)는 queue full block/resume, [communicator_test.dart](/config/workspace/proto-socket/dart/test/communicator_test.dart:428)는 pending cancellation만 확인해 slow handler in-flight drain과 자동 응답 보존을 직접 묶지 않는다.

### 해결 방법

`dart/test/communicator_test.dart`에 `graceful close drains in-flight request handler` 성격의 테스트를 추가한다. 기존 `_FakeCommunicator`, `_FakeTransport`를 재사용하고 첫 request handler를 지연시킨 뒤 `close()`가 handler 완료와 response packet enqueue를 기다리는지 확인한다.

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

- [ ] `dart/test/communicator_test.dart`: close 중 handlerStarted/handlerFinished, responseNonce, `isAlive=false` assertion 추가.
- [ ] `dart/test/communicator_test.dart`: 기존 FIFO/slow/queue-full 테스트 이름은 유지한다.

### 테스트 작성

- 작성: `graceful close 시 in-flight request handler가 완료되고 자동 응답 순서가 유지된다`.
- assertion: handler 완료, responseNonce가 입력 nonce와 일치, close 후 communicator inactive.

### 중간 검증

```bash
cd dart && dart test test/communicator_test.dart
```

기대: communicator tests PASS.

## TEST-2 Go queue/full close cleanup 보강

### 문제

[communicator.go](/config/workspace/proto-socket/go/communicator.go:395)는 bounded inbound channel로 backpressure를 적용하고 [communicator.go](/config/workspace/proto-socket/go/communicator.go:411)는 close 시 drain 여부를 분기한다. [communicator_test.go](/config/workspace/proto-socket/go/test/communicator_test.go:170)는 slow response FIFO, [communicator_test.go](/config/workspace/proto-socket/go/test/communicator_test.go:211)는 pending cancellation을 확인하지만 channel full block/resume와 graceful close drain 조합이 직접 없다.

### 해결 방법

`go/test/communicator_test.go`에 두 테스트를 추가한다. 하나는 blocking request handler로 inbound channel을 채운 뒤 추가 enqueue goroutine이 block되고 handler release 후 resume되는지 본다. 다른 하나는 in-flight handler 중 `Close()`가 drain하고 자동 응답이 기록되는지 본다.

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

- [ ] `go/test/communicator_test.go`: `TestInboundBackpressureBlocksAndResumes` 추가.
- [ ] `go/test/communicator_test.go`: `TestGracefulCloseDrainsInFlightRequestHandler` 추가.
- [ ] timeout은 1-3초 bounded로 둔다.

### 테스트 작성

- 작성: Go regression tests 2개.
- assertion: blocked goroutine이 release 전 완료되지 않음, release 후 완료됨, close drain 후 responseNonce 보존.

### 중간 검증

```bash
cd go && go test -count=1 ./...
```

기대: PASS. Go test cache는 허용하지 않는다.

## TEST-3 5개 언어 verify evidence 정렬

### 문제

Milestone task `unit-order`, `slow-handler`, `queue-close`는 “모든 지원 언어” 기준이다. 현재 Kotlin/Python/TypeScript에는 강한 검증이 있지만 task 완료 근거가 흩어져 있다.

### 해결 방법

필요한 경우 Kotlin/Python/TypeScript 테스트 이름이나 assertion message만 최소 보강한다. 기능 동작 변경 없이 검증 의도를 명시하고, CODE_REVIEW에 각 언어별 test name을 evidence로 기록한다.

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

- [ ] `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`: 기존 order/slow/queue-close test evidence 확인, 필요 시 assertion message 보강.
- [ ] `python/test/test_communicator.py`: 기존 `test_queue_full_ordering_and_close_cleanup` evidence 확인, 필요 시 name/comment 보강.
- [ ] `typescript/test/communicator.test.ts`: 기존 FIFO/slow/backpressure/graceful close evidence 확인, 필요 시 assertion message 보강.

### 테스트 작성

- 조건부 작성: 누락된 assertion이 발견될 때만 추가한다. 이미 충분하면 skip 사유를 CODE_REVIEW에 남긴다.

### 중간 검증

```bash
cd kotlin && ./gradlew test --tests com.tokilabs.proto_socket.CommunicatorTest --rerun-tasks
cd python && python3 -m pytest -q test/test_communicator.py
cd typescript && npm test -- communicator
```

기대: 모두 PASS.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `dart/test/communicator_test.dart` | TEST-1 |
| `go/test/communicator_test.go` | TEST-2 |
| `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt` | TEST-3 |
| `python/test/test_communicator.py` | TEST-3 |
| `typescript/test/communicator.test.ts` | TEST-3 |

## 최종 검증

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

기대: matrix 전체 PASS, whitespace error 없음. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
