<!-- task=m-performance-hotspot-optimization/01_ts_gateway_single_path plan=0 tag=REFACTOR -->

# Implementation Plan - REFACTOR

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것까지가 구현이다. 검증 명령을 실행하고 실제 출력/메모를 review stub에 기록한 뒤 active 파일을 그대로 둔 채 리뷰 준비를 보고한다. 구현 중 사용자 결정, 사용자 소유 외부 환경, 범위 충돌이 없이는 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 근거를 채우고 멈춘다. 명령 재실행이나 산출물 수집으로 해결 가능한 증거 공백은 사용자 리뷰 요청이 아니다.

## 배경

`고성능 병렬 운용 기준선과 최적화`의 `optimize` 에픽에서 실제 큰 작업은 `언어별 성능 병목 개선` 마일스톤으로 이관되어 있다. TypeScript gateway 병목은 `worker_threads` per-frame hop이 실제 TCP/WS gateway row에서 큰 p99/throughput 회귀를 만든 것이 핵심이다. 첫 단계는 제품 기본 gateway 의미를 worker hop 없는 coordinator path로 고정하고, 기존 TCP/WS gateway 테스트가 worker-specific 경로가 아니라 기본 gateway 계약을 검증하게 바꾸는 것이다.

## 사용자 리뷰 요청 흐름

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

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
  - `ts-gateway-single-path`: TypeScript gateway를 제품 기본 수신 경로로 유지하기 위한 단일 경로 조건을 정의한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/milestones/high-performance-parallel-operations.md`
- `agent-roadmap/milestones/performance-hotspot-optimization.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `typescript/src/communicator.ts`
- `typescript/src/inbound_gateway.ts`
- `typescript/src/node_inbound_gateway.ts`
- `typescript/src/node_inbound_gateway_worker.ts`
- `typescript/src/tcp_client.ts`
- `typescript/src/node_ws_client.ts`
- `typescript/bench/stress.ts`
- `typescript/test/communicator.test.ts`
- `typescript/test/tcp.test.ts`
- `typescript/test/ws.test.ts`
- `typescript/package.json`
- `typescript/tsconfig.json`

### 테스트 환경 규칙

`test_env=local`이다. `agent-test/local/rules.md`를 읽었고, 성능/gateway 관련 작업이라 `agent-test/local/proto-socket-performance-baseline.md`를 적용한다. TypeScript public/protocol behavior 회귀도 걸리므로 `agent-test/local/proto-socket-full-matrix.md`의 전체 matrix 명령을 최종 보조 검증으로 둔다. 이 subtask의 직접 검증은 `cd typescript && npm run check && npm test`이고, 전체 성능/호환성은 dependent subtask와 최종 matrix에서 다룬다.

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

- TypeScript default gateway coordinator path: `typescript/test/communicator.test.ts`의 `enableInboundGateway` 테스트가 단위 수준으로 있다.
- 실제 TCP/WS read loop gateway: `typescript/test/tcp.test.ts`와 `typescript/test/ws.test.ts`가 있지만 현재 `createNodeWorkerGateway`를 직접 attach해 worker-specific 경로를 검증한다. 이 subtask에서 기본 gateway 경로로 바꿔 공백을 닫는다.
- Node `worker_threads` explicit path: `typescript/test/communicator.test.ts`의 Node worker gateway 테스트와 cleanup stats 테스트가 있으므로 유지한다.

### 심볼 참조

이 계획은 public symbol rename/removal을 요구하지 않는다. `createNodeWorkerGateway`, `enableInboundGateway`, `attachInboundGateway`, `WorkerGateway` 참조는 `rg --sort path`로 확인했고, call site는 `typescript/src/communicator.ts`, `typescript/src/node_inbound_gateway.ts`, `typescript/test/communicator.test.ts`, `typescript/test/tcp.test.ts`, `typescript/test/ws.test.ts`, `typescript/bench/stress.ts`에 있다.

### 분할 판단

split decision policy를 먼저 평가했다. source/test default path 정리와 performance row/측정 정리는 서로 검증 방식이 달라 분리한다.

- 공유 task group: `agent-task/m-performance-hotspot-optimization`
- `01_ts_gateway_single_path`: 제품 기본 gateway 의미와 TCP/WS 테스트 정리. 선행 없음.
- `02+01_ts_gateway_perf_rows`: gateway performance rows와 회귀 비교 정리. `01_ts_gateway_single_path`의 `complete.log`가 필요하다.

### 범위 결정 근거

이 subtask는 TypeScript gateway 기본 경로 정의와 테스트 정리에 한정한다. Dart/Kotlin/Go/Python, wire format, proto schema, nonce 의미, package version은 제외한다. `createNodeWorkerGateway`는 삭제하지 않고 explicit Node worker experiment path로 남긴다. 실제 성능 row 변경과 `run_performance.sh` 결과 분석은 dependent subtask로 넘긴다.

### 빌드 등급

`local-G08`. TypeScript 한 ownership boundary에 갇히지만 receive ordering/cleanup/backpressure 계약을 다루므로 높은 local 등급이 필요하다. 리뷰는 concurrency 의미와 테스트 신뢰 확인 때문에 `cloud-G07`로 둔다.

## 구현 체크리스트

- [ ] `Communicator.enableInboundGateway()`의 문서와 의미를 worker-pool 기본값이 아니라 worker hop 없는 default receive coordinator gateway로 정리한다.
- [ ] TCP/WS 실제 read loop gateway 테스트를 `createNodeWorkerGateway` 직접 attach에서 `comm.enableInboundGateway({ workers: 2 })` 기본 gateway 경로 검증으로 바꾼다.
- [ ] Node `worker_threads` gateway 단위/cleanup 테스트는 explicit worker path 검증으로 유지하고, 이름/주석이 default path와 혼동되지 않게 정리한다.
- [ ] `cd typescript && npm run check && npm test`를 실행해 TypeScript 타입/단위/transport 테스트가 통과하는지 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [REFACTOR-1] Default Gateway 의미 정리

### 문제

[communicator.ts](/config/workspace/proto-socket/typescript/src/communicator.ts:164)는 `enableInboundGateway()`를 “default worker-pool gateway”라고 설명하지만, 실제 기본 구현은 `WorkerGateway`의 inline `decodePacketBaseEnvelope` path다. 반면 [node_inbound_gateway.ts](/config/workspace/proto-socket/typescript/src/node_inbound_gateway.ts:144)는 explicit `worker_threads` gateway를 별도 factory로 제공한다. 이 표현이 product default와 worker experiment를 섞어 `worker_threads` 회귀를 gateway 정책 자체의 문제처럼 보이게 한다.

### 해결 방법

`Communicator.enableInboundGateway()` JSDoc을 “default receive coordinator gateway”로 바꾸고, 기본값은 inline decode + seq/reorder/sink serialization임을 명확히 한다. `node_inbound_gateway.ts`는 explicit Node off-thread backend이며 default receive path가 아니라는 주석을 추가한다.

Before:

```ts
// typescript/src/communicator.ts:164
/**
 * receive coordinator 앞단에 default worker-pool gateway를 attach한다. {@link onReceivedFrame}으로 제출된
 * raw frame은 pool이 decode하고 내부 `seq`로 reorder해 coordinator의 {@link enqueueInbound}로 전달하므로
```

After:

```ts
/**
 * receive coordinator 앞단에 default receive gateway를 attach한다. 기본 gateway는 worker_threads hop 없이
 * raw frame에 내부 `seq`를 부여하고 inline decode 결과를 reorder/sink serialization으로 coordinator에 전달한다.
```

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

- [ ] `typescript/src/communicator.ts`: `enableInboundGateway` JSDoc과 `attachInboundGateway` JSDoc 정리.
- [ ] `typescript/src/node_inbound_gateway.ts`: `createNodeWorkerGateway`가 explicit Node worker backend임을 주석으로 분리.

### 테스트 작성

테스트 추가 없음. 문서/의미 정리이며 behavior는 기존 테스트가 검증한다.

### 중간 검증

```bash
cd typescript && npm run check
```

기대 결과: exit code 0.

## [REFACTOR-2] Transport Gateway 테스트를 기본 경로로 전환

### 문제

[tcp.test.ts](/config/workspace/proto-socket/typescript/test/tcp.test.ts:216)와 [ws.test.ts](/config/workspace/proto-socket/typescript/test/ws.test.ts:216)는 “read loop drives server inbound gateway” 테스트에서 `createNodeWorkerGateway`를 attach한다. 이 테스트는 실제 TCP/WS read loop와 FIFO/nonce를 검증하지만 default gateway 계약이 아니라 worker-specific hop을 검증한다.

### 해결 방법

두 transport 테스트는 `comm.enableInboundGateway({ workers: 2 })`를 사용하게 바꾼다. Node worker path는 [communicator.test.ts](/config/workspace/proto-socket/typescript/test/communicator.test.ts:608)의 explicit worker_threads 테스트와 cleanup stats 테스트에 남긴다.

Before:

```ts
// typescript/test/tcp.test.ts:229
comm.attachInboundGateway(
  createNodeWorkerGateway({
    sink: (frame) =>
      comm.enqueueInbound(frame.typeName, frame.data, frame.incomingNonce, frame.responseNonce),
    workers: 2,
  }),
);
```

After:

```ts
comm.enableInboundGateway({ workers: 2 });
```

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

- [ ] `typescript/test/tcp.test.ts`: import 정리, 테스트 이름/주석/attach 코드 갱신.
- [ ] `typescript/test/ws.test.ts`: import 정리, 테스트 이름/주석/attach 코드 갱신.
- [ ] `typescript/test/communicator.test.ts`: worker_threads explicit path 테스트 이름/주석 유지 또는 명확화.

### 테스트 작성

기존 transport 테스트를 수정한다. 새 파일은 만들지 않는다.

### 중간 검증

```bash
cd typescript && npm test -- --run test/tcp.test.ts test/ws.test.ts test/communicator.test.ts
```

기대 결과: exit code 0.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `typescript/src/communicator.ts` | REFACTOR-1 |
| `typescript/src/node_inbound_gateway.ts` | REFACTOR-1 |
| `typescript/test/tcp.test.ts` | REFACTOR-2 |
| `typescript/test/ws.test.ts` | REFACTOR-2 |
| `typescript/test/communicator.test.ts` | REFACTOR-2 |

## 최종 검증

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

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