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

# Code Review Reference - REFACTOR

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.

## 개요

date=2026-06-04
task=m-performance-hotspot-optimization/02+01_ts_gateway_perf_rows, plan=0, tag=REFACTOR

## 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

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.

선행 `01_ts_gateway_single_path` PASS 여부와 이 subtask의 row schema/검증 출력이 일치하는지 확인하세요.

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REFACTOR-1] Gateway Row 세분화 | [x] |
| [REFACTOR-2] Performance Wrapper와 결과 해석 확인 | [x] |

## 구현 체크리스트

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

## 코드리뷰 전용 체크리스트

> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
- [x] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/02+01_ts_gateway_perf_rows/`로 이동한다.
- [x] PASS이고 task group이 `m-performance-hotspot-optimization`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.

## 계획 대비 변경 사항

- 계획 "After" 스케치는 `on` mode를 `comm.enableInboundGateway({...})`로 켜라고 제시했으나, 실제로는 `comm.attachInboundGateway(new WorkerGateway({...}))`로 구현했다. `enableInboundGateway`는 내부에서 gateway를 생성·attach하며 참조를 노출하지 않아 `on` row의 peak/residual `GatewayBacklog`를 계측할 수 없다. `WorkerGateway`를 직접 만들면 `enableInboundGateway`가 내부에서 만드는 것과 동일한 inline-decode default coordinator gateway(worker_threads hop 없음)를 얻으면서 backlog 참조를 확보한다. 동작은 동등하다.
- `on`/`worker_threads`의 `onError`는 `frameErrorHandler` 대신 bench의 `stability.typeMismatch` 카운터로 보낸다. 기존 worker_threads row가 쓰던 decode-error 회계 방식을 그대로 유지해 세 mode의 안정성 판정 기준을 동일하게 둔다.
- 계획이 sink 타입을 명시하지 않았다. 공통 헬퍼 sink를 `DecodedFrame`(seq 포함)이 아니라 상위 타입 `DecodedEnvelope`(seq 제외)로 타이핑했다. `WorkerGateway`(sink param `DecodedFrame`은 `DecodedEnvelope`를 확장)와 `createNodeWorkerGateway`(sink param이 seq 없는 envelope 형태) 양쪽에 모두 대입 가능해야 하기 때문이다(`tsc --noEmit` 통과 조건).

## 주요 설계 결정

- 3-mode gateway 생성을 `createGatewayForMode(mode, sink, onError)` 헬퍼 하나로 집중해 frame-ingest row와 transport-baseline row가 같은 sink/onError/workers 구성과 같은 backlog 계측을 쓰게 했다. `off`는 gateway 없이 inline decode이므로 `null`을 반환하고, 호출부는 `gw !== null`로 attach 여부와 sampler 생성 여부, residual leak 판정을 일관되게 분기한다.
- row의 `gateway` label을 mode 문자열(`off`/`on`/`worker_threads`) 그대로 출력한다. `run_performance.sh`의 row key는 이미 gateway label을 자유 필드로 포함하므로 parser/aggregator를 바꾸지 않고도 세 mode가 안정적으로 분리된다(REFACTOR-2 범위 결정과 일치).
- 로그 라인을 `on=<bool>`에서 `mode=<off|on|worker_threads>`로 바꿔 default coordinator path와 worker_threads path가 stderr 진행 로그에서도 혼동되지 않게 했다.
- quick run은 harness sanity와 row shape 확인 용도로만 썼다. baseline 미지정이라 regression은 `SKIPPED`이며, full idle baseline을 새 기준값으로 확정했다고 주장하지 않는다(범위 결정 근거 준수).

## 사용자 리뷰 요청

_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- dependent subtask가 선행 `complete.log` 없이 구현되지 않았는지 확인한다.
- gateway rows가 `off`, default `on`, `worker_threads`를 안정적인 label로 구분하는지 확인한다.
- `run_performance.sh` aggregate record가 TypeScript gateway component PASS와 row labels를 포함하는지 확인한다.
- full idle baseline을 새 기준값으로 확정했다고 주장하지 않는지 확인한다.

## 검증 결과

### 타입 체크 (수정 파일: typescript/bench/stress.ts)
```bash
$ npm run check    # tsc --noEmit
# exit 0, 출력 없음 (오류 0)
```

### REFACTOR-1 중간 검증
```bash
$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --lang typescript --transport tcp,ws --profile gateway
[gateway] mode=quick frames=500
[gateway] mode=off dispatched=500 backlog=0 residual=0 violations=0
[gateway] mode=on dispatched=500 backlog=0 residual=0 violations=0
[gateway] mode=worker_threads dispatched=500 backlog=500 residual=0 violations=0
[gateway] transport=tcp mode=off requests=64 backlog=0 residual=0 violations=0
[gateway] transport=tcp mode=on requests=64 backlog=0 residual=0 violations=0
[gateway] transport=tcp mode=worker_threads requests=64 backlog=16 residual=0 violations=0
[gateway] transport=ws mode=off requests=64 backlog=0 residual=0 violations=0
[gateway] transport=ws mode=on requests=64 backlog=0 residual=0 violations=0
[gateway] transport=ws mode=worker_threads requests=64 backlog=16 residual=0 violations=0
DONE typescript: PASS (rows=9 skips=0 required_skips=0 violations=0)
전체 결과값: PASS
결과 기록 파일: agent-test/runs/20260604-102223-proto-socket-stress-quick.md
```
- 기대 결과 충족: `gateway=off`, `gateway=on`, `gateway=worker_threads` rows가 frame-ingest/tcp/ws 각각에서 분리되어 모두 PASS. 모든 row residual backlog=0 (cleanup leak 없음).
- 해석: `worker_threads`만 peak backlog가 비어있지 않고(off-thread pending) `on`(default coordinator)은 inline drain되어 peak backlog 0. 세 mode overhead가 한 record에서 분리됨.

### REFACTOR-2 중간 검증
```bash
$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
=== performance 측정 결과 ===
| 구성 | 결과 | exit code | 결과 기록 |
| same-language       | PASS | 0 | agent-test/runs/20260604-102233-proto-socket-stress-quick.md |
| cross-language      | PASS | 0 | agent-test/runs/20260604-102327-proto-socket-stress-quick-cross.md |
| typescript-gateway  | PASS | 0 | agent-test/runs/20260604-103828-proto-socket-stress-quick.md |
전체 결과값: PASS
Regression 결과값: SKIPPED
결과 기록 파일: agent-test/runs/20260604-102233-proto-socket-performance-quick.md
```
- 기대 결과 충족: same-language, cross-language, TypeScript gateway 구성요소 모두 PASS로 aggregate record에 포함. typescript-gateway 구성요소가 새 3-mode rows(off/on/worker_threads × frame-ingest/tcp/ws)를 포함.
- baseline 미지정이라 regression `SKIPPED`(정상). 새 idle baseline 확정 주장 없음.

### 최종 검증
```bash
$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --lang typescript --transport tcp,ws --profile gateway
# PASS (rows=9, violations=0) — 위 REFACTOR-1과 동일 결과 재현

$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
# 전체 PASS, Regression SKIPPED, 3개 구성요소 PASS — 위 REFACTOR-2와 동일

$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
# 1차: overall_result FAIL — agent-test/runs/20260604-103911-proto-socket-full-matrix.md
#   실패 셀: Kotlin 서버 -> Dart.web / Dart.web(WSS) 2건만 FAIL (브라우저 클라이언트 request-response 30s TimeoutException).
#   나머지 전부 PASS: Proto sync, 5개 동일언어(TypeScript 포함 npm run check && npm test PASS), 그 외 모든 cross-lang 방향.
# 2차(재실행): overall_result PASS — agent-test/runs/20260604-104812-proto-socket-full-matrix.md
#   Kotlin -> Dart.web / Dart.web(WSS) 포함 전체 셀 PASS.
```
- 최종 매트릭스 PASS. 1차 FAIL은 원격 브라우저 host(`toki@toki-labs.com`) WSS request-response의 transient 30s timeout이며 재실행에서 해소됨.
- 이 subtask 변경은 `typescript/bench/stress.ts`(성능 bench 하네스) 단일 파일이고 crosstest 경로에 포함되지 않으므로 1차 실패와 인과관계가 없다. 1차 record의 `git status 요약`도 변경 파일을 `M typescript/bench/stress.ts` 하나로 보고했다.

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - correctness: Pass
  - completeness: Pass
  - test coverage: Pass
  - API contract: Pass
  - code quality: Pass
  - plan deviation: Pass
  - verification trust: Pass
- 발견된 문제: 없음
- 다음 단계: PASS이므로 `complete.log` 작성 후 task archive로 이동한다.

리뷰 메모:
- 선행 작업 완료 로그는 `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/complete.log`에서 확인했다.
- `typescript/bench/stress.ts`는 gateway row를 `off`, `on`, `worker_threads`로 분리하고, `run_performance.sh`의 row key가 이미 `gateway` label을 포함해 parser 변경 없이 비교 가능한 구조임을 확인했다.
- `agent-test/runs/20260604-103828-proto-socket-stress-quick.md`와 `agent-test/runs/20260604-102233-proto-socket-performance-quick.md`에서 TypeScript gateway 9개 row가 모두 PASS이고 residual leak가 0임을 확인했다.
- `agent-test/runs/20260604-104812-proto-socket-full-matrix.md`에서 최종 full matrix PASS를 확인했다.
- 리뷰 중 `cd typescript && npm run check`를 재실행해 `tsc --noEmit` 통과를 확인했다.
