<!-- task=m-inbound-queue-ordering/08_typescript_gateway plan=0 tag=API -->

# TypeScript Worker Gateway 구현 계획

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

구현 후 `CODE_REVIEW-cloud-G08.md`의 구현 에이전트 소유 섹션에 실제 변경 내용과 검증 stdout/stderr를 채운 뒤 active 파일을 그대로 두고 리뷰를 요청한다. 최종화는 code-review 전용이다.

## 배경

`typescript-gateway`는 Node `worker_threads`와 browser Web Worker/fallback 후보를 추가하는 runtime 작업이다. 현재 TypeScript는 inbound queue/async worker와 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:
  - `typescript-gateway`: Node/browser 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/typescript-smoke.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `typescript/src/communicator.ts`
- `typescript/test/communicator.test.ts`

### 테스트 환경 규칙

- TypeScript 변경 필수 검증: `cd typescript && npm run check && npm test`.
- 최종 검증: 전체 matrix.

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

- 실제 Node worker_threads gateway, browser worker/fallback, transferable ArrayBuffer, out-of-order completion 검증이 없다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- `08_typescript_gateway`는 독립 언어 task이며 dependency 없음.

### 범위 결정 근거

- TypeScript communicator/gateway와 tests만 수정한다. 패킷 wire schema와 app-level handler pool은 제외한다.

### 빌드 등급

- build/review: `cloud-G08`. 이유: Node/browser runtime split과 worker/fallback 경계가 있다.

## 구현 체크리스트

- [ ] TypeScript gateway input/output에 내부 `seq`를 포함하고 Node worker_threads 후보를 추가한다.
- [ ] browser target은 Web Worker 또는 safe fallback을 사용하며 unsupported 환경에서 기존 coordinator path를 유지한다.
- [ ] transferable `ArrayBuffer` 사용 여부를 검토하고 복사 비용을 줄인다.
- [ ] worker result를 `seq` 기준으로 reorder한 뒤 기존 `enqueueInbound`/coordinator path로 전달한다.
- [ ] TypeScript tests에 Node gateway on, fallback, out-of-order completion 검증을 추가한다.
- [ ] 중간 검증으로 `cd typescript && npm run check && npm test -- communicator`를 실행한다.
- [ ] 최종 검증으로 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] TypeScript worker gateway

#### 문제

- `typescript/src/communicator.ts`에는 실제 worker gateway 후보가 없다.

#### 해결 방법

- Node worker_threads gateway와 browser fallback 경계를 분리한다.
- worker result collector가 `seq` 순서로 coordinator path에 넣는다.

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

- [ ] `typescript/src/communicator.ts`
- [ ] 필요 시 gateway 전용 파일
- [ ] `typescript/test/communicator.test.ts`

#### 테스트 작성

- worker result가 out-of-order로 완료되어도 dispatch order가 `[1,2]`인지 검증한다.
- fallback 모드가 기존 coordinator path를 사용하는지 검증한다.

#### 중간 검증

```bash
cd typescript && npm run check && npm test -- communicator
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `typescript/src/communicator.ts` | API-1 |
| `typescript/test/communicator.test.ts` | API-1 |
| gateway 전용 파일(필요 시) | API-1 |

## 최종 검증

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

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