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

# Implementation Plan - REFACTOR

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

이 subtask는 `01_ts_gateway_single_path`의 PASS `complete.log`가 선행 조건이다. 선행 조건이 없으면 구현을 시작하지 말고 현재 상태를 보고한다. 구현 후에는 active `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션에 실제 변경/검증 출력까지 채운다.

## 배경

TypeScript gateway 병목은 현재 `worker_threads` row가 default gateway row처럼 보이는 데서 해석 비용도 생긴다. 선행 subtask가 default gateway 의미를 worker hop 없는 coordinator path로 정리하면, 이 subtask는 gateway performance profile이 `off`, default `on`, explicit `worker_threads`를 분리해 남은 overhead를 정량화하게 만든다.

## 사용자 리뷰 요청 흐름

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

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
  - `ts-worker-hop-removal`: TypeScript `worker_threads` 기반 per-frame offload를 기본 gateway 경로에서 제거하거나, 동일 단일 경로 내부 구현으로 재설계한다.
  - `gateway-overhead`: TypeScript gateway 경로의 남은 overhead를 legacy inline control row와 비교해 정량화한다.
- 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`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`

### 테스트 환경 규칙

`test_env=local`이다. `agent-test/local/proto-socket-performance-baseline.md`를 적용한다. 직접 검증은 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --lang typescript --transport tcp,ws --profile gateway`와 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick`이다. 전체 호환성은 마지막에 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`로 확인한다.

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

- 현재 `typescript/bench/stress.ts`는 gateway `off/on`만 기록하고 `on`을 `createNodeWorkerGateway`로 측정한다.
- default coordinator gateway와 explicit worker_threads gateway를 같은 record에서 분리하는 row가 없다.
- `run_performance.sh` row key는 `gateway` label을 포함하므로 label만 안정적으로 분리하면 regression 비교는 재사용 가능하다.

### 심볼 참조

public symbol rename/removal 없음. `createNodeWorkerGateway` call site는 `typescript/test/communicator.test.ts`, `typescript/test/tcp.test.ts`, `typescript/test/ws.test.ts`, `typescript/bench/stress.ts`에 있다. 선행 subtask 후 transport tests의 call site는 줄어들고, 이 subtask는 bench call site를 explicit worker row로 남겨야 한다.

### 분할 판단

이 plan은 split work의 dependent subtask다.

- shared task group: `agent-task/m-performance-hotspot-optimization`
- predecessor `01`: `01_ts_gateway_single_path`
- predecessor 상태: 작성 시점에는 active/archived `complete.log` 없음. 구현 시작 전 `agent-task/m-performance-hotspot-optimization/01_ts_gateway_single_path/complete.log` 또는 archive matching `complete.log`가 있어야 한다.

### 범위 결정 근거

이 subtask는 TypeScript gateway benchmark/profile row와 검증 기록에 한정한다. `run_performance.sh` parser는 gateway label이 이미 row key에 포함되어 있으므로 변경하지 않는다. full idle baseline 확정은 사용자/환경 확인 없이 새 기준값으로 삼지 않고, quick run은 harness sanity와 row shape 확인에 쓴다.

### 빌드 등급

`cloud-G07`. shell/benchmark output, row schema, regression 비교 해석이 중심이고 선행 subtask 결과를 신뢰해야 하므로 cloud lane으로 둔다.

## 의존 관계 및 구현 순서

이 디렉터리명 `02+01_ts_gateway_perf_rows`의 predecessor는 `01`뿐이다. 구현 시작 전에 같은 task group의 `01_ts_gateway_single_path`가 PASS되어 `complete.log`를 만든 상태여야 한다.

## 구현 체크리스트

- [ ] 선행 `01_ts_gateway_single_path`의 `complete.log` 존재를 확인하고, 없으면 구현을 시작하지 않는다.
- [ ] `typescript/bench/stress.ts` gateway profile이 `off`, default `on`, explicit `worker_threads` row를 구분해 기록하도록 바꾼다.
- [ ] gateway transport baseline의 `gateway` label과 로그가 default coordinator path와 worker_threads path를 혼동하지 않게 정리한다.
- [ ] `run_stress.sh --quick --lang typescript --transport tcp,ws --profile gateway`와 `run_performance.sh --quick` 결과에서 TypeScript gateway rows가 PASS이고 `GatewayBacklog` residual leak가 0인지 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [REFACTOR-1] Gateway Row 세분화

### 문제

[stress.ts](/config/workspace/proto-socket/typescript/bench/stress.ts:891)의 gateway profile은 `off`와 `on`만 비교하고, [stress.ts](/config/workspace/proto-socket/typescript/bench/stress.ts:942)에서 `on`을 `createNodeWorkerGateway`로 만든다. 그래서 worker_threads overhead가 default gateway overhead처럼 기록된다.

### 해결 방법

gateway mode를 내부 enum 또는 tuple로 분리한다.

- `off`: gateway 미설정 inline control
- `on`: `comm.enableInboundGateway()` default coordinator gateway
- `worker_threads`: `createNodeWorkerGateway()` explicit Node off-thread experiment row

Before:

```ts
// typescript/bench/stress.ts:914
for (const gatewayOn of [false, true]) {
  ...
  if (gatewayOn) {
    gateway = createNodeWorkerGateway({
```

After:

```ts
for (const gatewayMode of ["off", "on", "worker_threads"] as const) {
  ...
  if (gatewayMode === "on") {
    comm.enableInboundGateway({ workers: Math.max(2, Math.min(4, availableParallelism())) });
  } else if (gatewayMode === "worker_threads") {
    gateway = createNodeWorkerGateway({ ... });
    comm.attachInboundGateway(gateway);
  }
```

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

- [ ] `typescript/bench/stress.ts`: frame-ingest row를 3-mode로 분리.
- [ ] `typescript/bench/stress.ts`: transport baseline row를 3-mode로 분리.
- [ ] `typescript/bench/stress.ts`: log line에 `gateway=<mode>`와 residual/backlog를 기록.

### 테스트 작성

벤치 harness 변경이므로 별도 unit test보다 runner 결과 row를 검증한다.

### 중간 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --lang typescript --transport tcp,ws --profile gateway
```

기대 결과: exit code 0, `gateway=off`, `gateway=on`, `gateway=worker_threads` rows가 모두 PASS로 기록된다.

## [REFACTOR-2] Performance Wrapper와 결과 해석 확인

### 문제

[run_performance.sh](/config/workspace/proto-socket/agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh:249)는 `gateway` label을 row key에 포함한다. row label이 안정적이면 parser 변경 없이 비교 가능하지만, 새 mode row가 wrapper 결과에 들어오는지 확인해야 한다.

### 해결 방법

`run_performance.sh --quick`을 실행해 TypeScript gateway component가 새 3-mode rows를 aggregate record에 포함하는지 확인한다. baseline 비교는 같은 host/runtime/profile baseline이 있을 때만 수행하고, 없으면 SKIPPED를 정상 기록으로 둔다.

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

- [ ] `typescript/bench/stress.ts`: wrapper가 읽는 `ROW|...|Gateway|...` field에 안정적인 label을 출력한다.
- [ ] 필요 시 `agent-roadmap/milestones/performance-hotspot-optimization.md` 작업 컨텍스트에 새 row 해석만 보강한다. 기능 task 체크는 code-review/runtime 완료 이벤트에 맡긴다.

### 테스트 작성

새 unit test 없음. `run_performance.sh` 기록 파일이 테스트 산출물이다.

### 중간 검증

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

기대 결과: overall PASS 또는 regression SKIPPED/PASS, TypeScript gateway component PASS, 결과 기록 파일 생성.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `typescript/bench/stress.ts` | REFACTOR-1, REFACTOR-2 |
| `agent-roadmap/milestones/performance-hotspot-optimization.md` | REFACTOR-2, 필요 시 해석 보강 |

## 최종 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --lang typescript --transport tcp,ws --profile gateway
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
```

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