<!-- task=m-inbound-queue-ordering/04_dart_gateway plan=0 tag=API -->

# Dart Worker Gateway 구현 계획

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

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

## 배경

`dart-gateway`는 Dart IO에서 isolate 기반 worker gateway 후보를 추가하는 큰 runtime 작업이다. 현재 Dart에는 fake gateway reorder anchor만 있고 실제 상시 isolate gateway가 없다. gateway는 raw bytes decode/순수 전처리만 맡고 stateful dispatch는 기존 `Communicator` receive coordinator가 계속 소유해야 한다.

## 사용자 리뷰 요청 흐름

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

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `dart-gateway`: Dart IO 구현에서 상시 isolate gateway를 두고 순수 bytes 작업을 분리한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `agent-test/local/dart-smoke.md`
- `dart/lib/src/communicator.dart`
- `dart/test/communicator_test.dart`
- `../dart-app-core/lib/platform/isolate_manager.dart`

### 테스트 환경 규칙

- test_env: local. `agent-test/local/rules.md`, `dart-smoke.md`, `proto-socket-full-matrix.md`를 읽었다.
- 적용 명령: `cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js`.
- protocol/API 영향과 Dart.web 조건부 export/stub 영향이 있으므로 최종 검증은 전체 matrix `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`로 확장한다.

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

- 기존 `dart/test/communicator_test.dart`는 fake gateway reorder만 검증한다.
- 실제 isolate gateway on/off, out-of-order worker result reorder, close/cancel, Dart web import compile fallback 검증이 필요하다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- 세 번째 Epic은 언어별 runtime/worker 경계가 독립적이므로 split 한다.
- shared task group: `m-inbound-queue-ordering`.
- 이 plan은 `04_dart_gateway`이며 다른 gateway task와 런타임 의존성이 없다.

### 범위 결정 근거

- Dart IO gateway만 구현한다. Dart web은 worker 미지원 fallback/stub이 깨지지 않는지만 확인한다.
- user listener/request handler, pending request map, transport/write queue를 isolate로 옮기지 않는다.
- wire format, proto schema, public protocol field는 변경하지 않는다.

### 빌드 등급

- build: `cloud-G08`, review: `cloud-G08`. 이유: isolate/process boundary와 concurrency/order 보장이 포함된 runtime 작업이다.

## 구현 체크리스트

- [ ] Dart IO 전용 worker gateway 타입을 추가하고, gateway input/output에 내부 `seq`를 포함한다.
- [ ] gateway는 `PacketBase` envelope decode 또는 순수 bytes 전처리만 수행하고, 결과를 `seq`로 reorder한 뒤 기존 `Communicator.onReceivedData`/coordinator path로 전달한다.
- [ ] Dart web 조건부 export/stub 또는 fallback이 깨지지 않도록 IO 전용 import 경계를 유지한다.
- [ ] Dart 테스트에 gateway on reorder/response order/fallback compile anchor를 추가한다.
- [ ] 중간 검증으로 `cd dart && dart test test/communicator_test.dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js`를 실행하고 실제 stdout/stderr를 기록한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행하고 결과 기록 파일을 남긴다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] Dart IO worker gateway

#### 문제

- `dart/lib/src/communicator.dart`는 receive coordinator와 fake gateway anchor만 갖고 있고 실제 isolate gateway가 없다.

#### 해결 방법

- IO 전용 gateway 클래스를 추가한다.
- gateway worker는 raw frame 또는 `PacketBase` bytes를 받아 decode/전처리 결과와 `seq`를 돌려준다.
- coordinator owner는 main isolate에 유지하고 `seq` reorder 후 기존 `onReceivedData` 경로로 넣는다.

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

- [ ] `dart/lib/src/communicator.dart`
- [ ] 필요 시 IO 전용 gateway 파일
- [ ] `dart/test/communicator_test.dart`

#### 테스트 작성

- gateway result가 `seq=2`, `seq=1`로 완료되어도 listener/response order가 `[1, 2]`인지 검증한다.
- Dart web import compile이 통과해 IO 전용 isolate import가 web 빌드를 깨지 않는지 검증한다.

#### 중간 검증

```bash
cd dart && dart test test/communicator_test.dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js
```

기대 결과: communicator tests PASS, browser import compile PASS.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `dart/lib/src/communicator.dart` | API-1 |
| `dart/test/communicator_test.dart` | API-1 |
| IO 전용 gateway 파일(필요 시) | 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
