toki/proto-socket
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: [G07] TS gateway row processing performance optimization

Browse source 
- Refactor RowParser to use pooled buffers for batch row processing
- Add parallel row processing with Web Worker offloading in browser
- Optimize TypeScript Node.js gateway TCP/WS handlers
- Update tests for communicator, tcp, ws with performance improvements
This commit is contained in:
toki 2026-06-04 19:08:38 +09:00
parent 6ba2b3f1c0
commit afc8f7839e
13 changed files with 972 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
agent-roadmap/milestones/high-performance-parallel-operations.md
View file

@ -53,17 +53,17 @@
gateway receive coordinator를 제품 기본 수신 경로로 유지하기 위한 신뢰 hard gate와 성능 hardening 조건을 수치로 정한다. TypeScript의 `worker_threads` per-frame offload는 현재 측정 대상인 구현 세부사항이며, 제품 정책의 사용자/운영 옵션으로 두지 않는다. gateway receive coordinator를 제품 기본 수신 경로로 유지하기 위한 신뢰 hard gate와 성능 hardening 조건을 수치로 정한다. TypeScript의 `worker_threads` per-frame offload는 현재 측정 대상인 구현 세부사항이며, 제품 정책의 사용자/운영 옵션으로 두지 않는다.
- [ ] [gateway-real-path] TCP/WS 실제 수신 경로에서 gateway baseline을 추가한다. 검증: in-process `onReceivedFrame`뿐 아니라 실제 transport frame ingest에서 gateway path throughput, p95/p99, memory, backlog가 기록된다. - [x] [gateway-real-path] TCP/WS 실제 수신 경로에서 gateway baseline을 추가한다. 검증: in-process `onReceivedFrame`뿐 아니라 실제 transport frame ingest에서 gateway path throughput, p95/p99, memory, backlog가 기록된다.
- [x] [gateway-threshold] gateway 기본 정책 기준을 선언한다. 검증: mandatory gateway hard gate와 단일 receive path hardening 조건이 문서화된다. - [x] [gateway-threshold] gateway 기본 정책 기준을 선언한다. 검증: mandatory gateway hard gate와 단일 receive path hardening 조건이 문서화된다.
- [ ] [gateway-cleanup] gateway close/cancel/drain 계측을 추가한다. 검증: close 후 gateway queue, pending, worker-backed implementation 상태가 비어 있고 repeated run에서 memory growth가 누적되지 않는다. - [x] [gateway-cleanup] gateway close/cancel/drain 계측을 추가한다. 검증: close 후 gateway queue, pending, worker-backed implementation 상태가 비어 있고 repeated run에서 memory growth가 누적되지 않는다.
### Epic: [optimize] 병목 최적화 ### Epic: [optimize] 병목 최적화
측정 결과를 근거로 병목을 줄이고 regression gate를 만든다. 측정 결과를 근거로 병목을 줄이고 regression gate를 만든다.
- [ ] [hotspot-report] 언어별 병목 리포트를 작성한다. 검증: queue/channel/lock/serialization/worker/transport write path 중 주요 병목 후보와 근거가 결과 파일 또는 작업 문서에 남는다. - [x] [hotspot-report] 언어별 병목 리포트를 작성한다. 검증: queue/channel/lock/serialization/worker/transport write path 중 주요 병목 후보와 근거가 결과 파일 또는 작업 문서에 남는다.
- [ ] [targeted-opt] 측정으로 확인된 상위 병목을 우선 최적화한다. 검증: 최적화 전후 같은 local profile에서 stability hard gate를 유지하고, 대상 metric이 개선되거나 남은 병목과 hardening 계획이 명확해진다. - [ ] [targeted-opt] 측정으로 확인된 상위 병목을 우선 최적화한다. 검증: 최적화 전후 같은 local profile에서 stability hard gate를 유지하고, 대상 metric이 개선되거나 남은 병목과 hardening 계획이 명확해진다.
- [ ] [regression-gate] 성능 regression gate를 추가한다. 검증: 같은 환경의 이전 baseline 대비 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화가 발생하면 WARN/FAIL 후보로 표시하되, 환경 차이는 별도 baseline으로 분리할 수 있다. - [x] [regression-gate] 성능 regression gate를 추가한다. 검증: 같은 환경의 이전 baseline 대비 throughput 20% 이상 하락 또는 p99 latency 25% 이상 악화가 발생하면 WARN/FAIL 후보로 표시하되, 환경 차이는 별도 baseline으로 분리할 수 있다.
- [x] [matrix] 전체 로컬 검증 매트릭스를 실행해 최적화 후에도 프로토콜 호환성과 크로스 언어 통신이 유지되는지 확인한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과. - [x] [matrix] 전체 로컬 검증 매트릭스를 실행해 최적화 후에도 프로토콜 호환성과 크로스 언어 통신이 유지되는지 확인한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과.
## 성능 기준선 ## 성능 기준선
@ -111,12 +111,16 @@ gateway receive coordinator를 제품 기본 수신 경로로 유지하기 위
- [lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full roundtrip/payload baseline이 required SKIP 없이 stability hard gate를 통과했다. 지연 사유였던 Kotlin TCP delayed-ACK/TCP_NODELAY 부재, Kotlin WS frame별 coroutine launch에 따른 FIFO 불안정, Go WS 기본 32KiB read limit, Kotlin server-side listener 설치 전 초기 frame 소비 race는 `TcpClient.tcpNoDelay`, Kotlin WS 단일 receive queue, Go WS `SetReadLimit(MaxPacketSize)`, Kotlin stress server setup barrier로 제거했다. 검증: `agent-test/runs/20260603-062724-proto-socket-stress-full.md` PASS. - [lang-baseline] Dart, Go, Kotlin, Python, TypeScript same-language TCP/WS full roundtrip/payload baseline이 required SKIP 없이 stability hard gate를 통과했다. 지연 사유였던 Kotlin TCP delayed-ACK/TCP_NODELAY 부재, Kotlin WS frame별 coroutine launch에 따른 FIFO 불안정, Go WS 기본 32KiB read limit, Kotlin server-side listener 설치 전 초기 frame 소비 race는 `TcpClient.tcpNoDelay`, Kotlin WS 단일 receive queue, Go WS `SetReadLimit(MaxPacketSize)`, Kotlin stress server setup barrier로 제거했다. 검증: `agent-test/runs/20260603-062724-proto-socket-stress-full.md` PASS.
- [payload-matrix] Dart, Go, Kotlin, Python, TypeScript stress harness가 quick 1KB/64KB와 full 1KB/64KB/1MB payload rows를 기록하고, Python WS 1MB 회귀를 통과하도록 정리되었다. 검증: `agent-test/runs/20260602-205755-proto-socket-stress-full.md`, `agent-test/runs/20260602-205849-proto-socket-full-matrix.md`, `cd python && python3 -m pytest -q`, `git diff --check`, 완료 로그 `agent-task/archive/2026/06/m-high-performance-parallel-operations/03+01_payload_matrix/complete.log`. - [payload-matrix] Dart, Go, Kotlin, Python, TypeScript stress harness가 quick 1KB/64KB와 full 1KB/64KB/1MB payload rows를 기록하고, Python WS 1MB 회귀를 통과하도록 정리되었다. 검증: `agent-test/runs/20260602-205755-proto-socket-stress-full.md`, `agent-test/runs/20260602-205849-proto-socket-full-matrix.md`, `cd python && python3 -m pytest -q`, `git diff --check`, 완료 로그 `agent-task/archive/2026/06/m-high-performance-parallel-operations/03+01_payload_matrix/complete.log`.
- [gateway-threshold] gateway는 순차 이벤트 보장과 event loop 보호를 담당하는 mandatory receive path로 선언했다. 성능 회귀가 확인되면 gateway 비활성화 정책이 아니라 worker hop 제거/재설계, backpressure, reorder, cleanup hardening 대상으로 분류한다. inline decode 비교 row는 성능 분석용 대조군으로만 남긴다. - [gateway-threshold] gateway는 순차 이벤트 보장과 event loop 보호를 담당하는 mandatory receive path로 선언했다. 성능 회귀가 확인되면 gateway 비활성화 정책이 아니라 worker hop 제거/재설계, backpressure, reorder, cleanup hardening 대상으로 분류한다. inline decode 비교 row는 성능 분석용 대조군으로만 남긴다.
- [gateway-real-path] TypeScript gateway profile이 in-process frame-ingest row와 실제 TCP/WS transport read loop row를 함께 기록하도록 정리되었다. 검증: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`의 `typescript-gateway` component, `typescript/bench/stress.ts`의 `runGatewayTransportBaseline`, `agent-test/runs/20260603-080241-proto-socket-stress-full.md`의 `transport=tcp/ws` gateway on/off rows PASS.
- [gateway-cleanup] TypeScript gateway stats와 stress rows가 queued/reorder/sink/worker pending 기반 `GatewayBacklog`와 close 후 residual backlog를 기록하도록 정리되었다. 검증: `typescript/src/inbound_gateway.ts`, `typescript/src/node_inbound_gateway.ts`, `typescript/test/communicator.test.ts`의 WorkerGateway cleanup stats, `agent-test/runs/20260603-092819-proto-socket-performance-quick.md`의 `backlog`/`residual` 로그와 stability hard gate PASS.
- [hotspot-report] `언어별 성능 병목 개선` Milestone의 병목 리포트가 Dart TCP fixed latency/1MB payload/isolate gateway, TypeScript WS 1MB/gateway worker overhead, Kotlin WS latency/large payload/slow-mix, Go/Python reference 기준점을 근거 파일과 수치로 정리했다. 검증: `agent-roadmap/milestones/performance-hotspot-optimization.md`의 `작업 컨텍스트 > 병목 리포트`.
- [regression-gate] `run_performance.sh`가 baseline row 비교, throughput 하락, p99 악화, WARN/FAIL 후보, `--fail-on-regression`을 처리하도록 정리되었고 local 성능 테스트 규칙에도 같은 판정 기준이 기록되었다. 검증: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`, `agent-test/local/proto-socket-performance-baseline.md`, `agent-test/runs/20260603-095712-proto-socket-performance-quick.md`의 `compared rows: 90`, `warning rows: 0`.
- [burst-100k], [parallel-1k], [soak-load] Dart/Go/Kotlin/Python/TypeScript stress harness가 full load profile 축을 100k burst, 128/512/1024 clients, 30초/5분/30분 sustained 후보로 확장했다. 검증: `agent-test/runs/20260602-232000-proto-socket-stress-full.md`는 Dart/Go/Python TCP 축에서 hard gate 위반 0을 기록했고, TypeScript 512/1024 client 회귀는 `agent-test/runs/20260603-015953-proto-socket-stress-full.md`에서 0 violation PASS로 재확인되었다. - [burst-100k], [parallel-1k], [soak-load] Dart/Go/Kotlin/Python/TypeScript stress harness가 full load profile 축을 100k burst, 128/512/1024 clients, 30초/5분/30분 sustained 후보로 확장했다. 검증: `agent-test/runs/20260602-232000-proto-socket-stress-full.md`는 Dart/Go/Python TCP 축에서 hard gate 위반 0을 기록했고, TypeScript 512/1024 client 회귀는 `agent-test/runs/20260603-015953-proto-socket-stress-full.md`에서 0 violation PASS로 재확인되었다.
- [slow-mix] Dart, Go, Kotlin, Python, TypeScript stress harness에 빠른/느린 handler 혼합 부하 profile이 추가되었다. 검증: `agent-test/runs/20260603-035342-proto-socket-stress-quick.md`는 Dart/Python/TypeScript TCP slow-mix PASS와 Go deferred를 기록했고, `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`는 Kotlin TCP/WS deferred를 병목 후보로 기록했다. - [slow-mix] Dart, Go, Kotlin, Python, TypeScript stress harness에 빠른/느린 handler 혼합 부하 profile이 추가되었다. 검증: `agent-test/runs/20260603-035342-proto-socket-stress-quick.md`는 Dart/Python/TypeScript TCP slow-mix PASS와 Go deferred를 기록했고, `agent-test/runs/20260603-035352-proto-socket-stress-quick.md`는 Kotlin TCP/WS deferred를 병목 후보로 기록했다.
- [matrix] slow-mix 작업 후 전체 로컬 검증 매트릭스가 프로토콜 호환성과 크로스 언어 통신을 유지했다. 검증: `agent-test/runs/20260603-035403-proto-socket-full-matrix.md` PASS. - [matrix] slow-mix 작업 후 전체 로컬 검증 매트릭스가 프로토콜 호환성과 크로스 언어 통신을 유지했다. 검증: `agent-test/runs/20260603-035403-proto-socket-full-matrix.md` PASS.
- 작업 동기화: - 작업 동기화:
- 2026-06-03 기준 full matrix, 성능 전용 quick 표준, baseline 비교 경로, 5개 언어별 병목 분석이 완료되었다. - 2026-06-03 기준 full matrix, 성능 전용 quick 표준, baseline 비교 경로, 5개 언어별 병목 분석이 완료되었다.
- 현재 활성 `agent-task/` 작업 디렉터리는 없다. 예전에 분리 후보로 기록한 gateway 실제 transport 경로와 cleanup 계측은 새 `언어별 성능 병목 개선` Milestone의 작업 순서 안에서 다시 계획한다. - 현재 활성 `agent-task/` 작업 디렉터리는 없다. gateway 실제 transport 경로와 cleanup 계측은 이 Milestone의 `gateway-policy` 에픽 완료 근거로 정리되었고, 성능 회귀를 줄이는 구현 작업은 새 `언어별 성능 병목 개선` Milestone의 작업 순서 안에서 다시 계획한다.
- 이 Milestone은 성능 기준선과 측정 표준의 선행 근거로 유지하고, 실제 최적화 구현은 `agent-roadmap/milestones/performance-hotspot-optimization.md`에서 진행한다. - 이 Milestone은 성능 기준선과 측정 표준의 선행 근거로 유지하고, 실제 최적화 구현은 `agent-roadmap/milestones/performance-hotspot-optimization.md`에서 진행한다.
- 후속 이관: gateway 실제 transport 수신 경로 baseline, gateway cleanup 계측, Dart TCP 40ms대 고정 지연 및 1MB payload 병목 개선, Dart isolate receive gateway의 실제 transport 경로 적용/backpressure/error ordering/large payload transfer/cleanup hardening, Go slow-mix 검증 모델 보정, Kotlin WS 40ms대 고정 지연 개선, Kotlin slow-mix 검증 모델 보정, Kotlin large payload heap peak 관찰, Go/Python sustained memory 측정 artifact 분리, Python 고동시성 p99 기준점과 gateway API 정책 검토, 언어별 병목 리포트와 regression gate는 `언어별 성능 병목 개선` Milestone으로 넘긴다. - 후속 이관: Dart TCP 40ms대 고정 지연 및 1MB payload 병목 개선, Dart isolate receive gateway의 실제 transport 경로 적용/backpressure/error ordering/large payload transfer/cleanup hardening, Go slow-mix 검증 모델 보정, Kotlin WS 40ms대 고정 지연 개선, Kotlin slow-mix 검증 모델 보정, Kotlin large payload heap peak 관찰, Go/Python sustained memory 측정 artifact 분리, Python 고동시성 p99 기준점과 gateway API 정책 검토는 `언어별 성능 병목 개선` Milestone으로 넘긴다.
- 확인 필요: 없음 - 확인 필요: 없음

161
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/code_review_cloud_G07_0.log Normal file
View file

@ -0,0 +1,161 @@
<!-- task=m-performance-hotspot-optimization/01_ts_gateway_single_path 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`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-06-04
task=m-performance-hotspot-optimization/01_ts_gateway_single_path, plan=0, tag=REFACTOR
## Roadmap Targets
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
- `ts-gateway-single-path`: TypeScript gateway를 제품 기본 수신 경로로 유지하기 위한 단일 경로 조건을 정의한다.
- Completion mode: check-on-pass
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [REFACTOR-1] Default Gateway 의미 정리 | [x] |
| [REFACTOR-2] Transport Gateway 테스트를 기본 경로로 전환 | [x] |
## 구현 체크리스트
- [x] `Communicator.enableInboundGateway()`의 문서와 의미를 worker-pool 기본값이 아니라 worker hop 없는 default receive coordinator gateway로 정리한다.
- [x] TCP/WS 실제 read loop gateway 테스트를 `createNodeWorkerGateway` 직접 attach에서 `comm.enableInboundGateway({ workers: 2 })` 기본 gateway 경로 검증으로 바꾼다.
- [x] Node `worker_threads` gateway 단위/cleanup 테스트는 explicit worker path 검증으로 유지하고, 이름/주석이 default path와 혼동되지 않게 정리한다.
- [x] `cd typescript && npm run check && npm test`를 실행해 TypeScript 타입/단위/transport 테스트가 통과하는지 확인한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G08_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/01_ts_gateway_single_path/`로 이동한다.
- [ ] PASS이고 task group이 `m-performance-hotspot-optimization`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] FAIL이고 user-review gate가 트리거되지 않았으므로 다음 active `PLAN-local-G06.md`와 `CODE_REVIEW-local-G06.md`를 작성하고 `complete.log`를 작성하지 않는다.
## 계획 대비 변경 사항
계획 대비 변경 사항 없음.
## 주요 설계 결정
- `Communicator.enableInboundGateway()`의 JSDoc을 수정하여, 기본 게이트웨이가 `worker_threads` 홉 없이 raw frame에 내부 `seq`를 부여하고 인라인 디코딩 및 시퀀스 재정렬(sink serialization)을 통해 수신 코디네이터로 전달함을 명시했습니다.
- `node_inbound_gateway.ts`에서 `createNodeWorkerGateway`는 기본 경로가 아니며 명시적인 성능 튜닝이나 실험 목적으로만 사용됨을 문서화하여 default path와 구별했습니다.
- TCP 및 WS 실제 전송 테스트(`tcp.test.ts`, `ws.test.ts`)의 게이트웨이 시나리오에서 명시적으로 `createNodeWorkerGateway`를 부착하던 부분을 제품 기본 게이트웨이 활성화 API인 `comm.enableInboundGateway({ workers: 2 })` 방식으로 전환하였습니다.
- `communicator.test.ts`에 포함된 Node 작업자 스레드 수신 검증들은 명시적인 경로(`Explicit Path`) 테스트임을 알아볼 수 있도록 명칭과 주석을 명확히 하였습니다.
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- `enableInboundGateway()`가 worker_threads 기본값으로 오해되지 않는지 확인한다.
- TCP/WS read loop 테스트가 기본 gateway path를 검증하고, worker-specific 테스트가 별도로 남았는지 확인한다.
- public API removal/rename 없이 TypeScript test/check가 통과했는지 확인한다.
## 검증 결과
### REFACTOR-1 중간 검증
```bash
$ cd typescript && npm run check
> proto-socket@1.0.5 check
> tsc --noEmit
```
### REFACTOR-2 중간 검증
```bash
$ cd typescript && npm test -- --run test/tcp.test.ts test/ws.test.ts test/communicator.test.ts
RUN v3.2.4 /config/workspace/proto-socket/typescript
✓ test/tcp.test.ts (7 tests) 272ms
✓ test/communicator.test.ts (28 tests) 1027ms
✓ test/ws.test.ts (7 tests) 1107ms
Test Files 3 passed (3)
Tests 42 passed (42)
```
### 최종 검증
```bash
$ cd typescript && npm run check && npm test
> proto-socket@1.0.5 check
> tsc --noEmit
> proto-socket@1.0.5 test
> vitest run
RUN v3.2.4 /config/workspace/proto-socket/typescript
✓ test/base_client.test.ts (7 tests) 10ms
✓ test/browser_ws_client.test.ts (7 tests) 38ms
✓ test/tcp.test.ts (7 tests) 270ms
✓ test/communicator.test.ts (28 tests) 650ms
✓ test/ws.test.ts (7 tests) 1094ms
Test Files 5 passed (5)
Tests 56 passed (56)
```
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
Sections and their ownership:
| Section | Owner | Note |
|---------|-------|------|
| Header, 개요, 리뷰 에이전트 지시, Roadmap Targets | Fixed at stub creation | Implementing agent must not modify |
| 구현 항목별 완료 여부, 구현 체크리스트 | Implementing agent | Check completed items only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
| 계획 대비 변경 사항, 주요 설계 결정, 검증 결과 | Implementing agent | Fill with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required |
## 코드리뷰 결과
- 종합 판정: FAIL
- 차원별 평가:
- correctness: Pass
- completeness: Fail
- test coverage: Pass
- API contract: Pass
- code quality: Warn
- plan deviation: Fail
- verification trust: Pass
- 발견된 문제:
- Required `typescript/test/tcp.test.ts:245`: 테스트가 이제 `comm.enableInboundGateway({ workers: 2 })`로 default receive gateway를 검증하는데, 바로 아래 설명은 아직 `gateway off-thread decode`와 `worker_threads gateway`의 lazy spawn/cold-start를 말합니다. 이 subtask의 핵심 완료 조건은 default path와 explicit worker path를 혼동하지 않게 정리하는 것이므로, 해당 주석을 inline default receive gateway의 reorder/sink serialization 의미로 바꾸고 worker_threads cold-start 설명을 제거하세요.
- Required `typescript/test/ws.test.ts:245`: WS default gateway 테스트도 `enableInboundGateway` 경로를 타지만 timeout 설명이 여전히 `worker_threads gateway` lazy spawn/cold-start를 전제로 합니다. default receive gateway 설명으로 수정하거나 timeout 주석을 transport/request concurrency 관점으로 다시 써서 explicit worker path와 혼동되지 않게 하세요.
- 다음 단계: FAIL이므로 user-review gate 없이 다음 active `PLAN-*-G??.md`와 `CODE_REVIEW-*-G??.md`를 작성한다.

144
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/code_review_local_G06_1.log Normal file
View file

@ -0,0 +1,144 @@
<!-- task=m-performance-hotspot-optimization/01_ts_gateway_single_path plan=1 tag=REVIEW_REFACTOR -->
# Code Review Reference - REVIEW_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`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.
## 개요
date=2026-06-04
task=m-performance-hotspot-optimization/01_ts_gateway_single_path, plan=1, tag=REVIEW_REFACTOR
## Roadmap Targets
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
- `ts-gateway-single-path`: TypeScript gateway를 제품 기본 수신 경로로 유지하기 위한 단일 경로 조건을 정의한다.
- Completion mode: check-on-pass
## 이 파일을 읽는 리뷰 에이전트에게
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
1. 판정을 append한다.
2. `CODE_REVIEW-local-G06.md` -> `code_review_local_G06_N.log`, `PLAN-local-G06.md` -> `plan_local_G06_M.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/01_ts_gateway_single_path/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-performance-hotspot-optimization`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
---
## 구현 항목별 완료 여부
| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_REFACTOR-1] TCP default gateway 주석 정리 | [x] |
| [REVIEW_REFACTOR-2] WS default gateway 주석 정리 | [x] |
## 구현 체크리스트
- [x] `typescript/test/tcp.test.ts`의 default gateway 테스트 주석에서 `off-thread decode`, `worker_threads gateway`, worker pool cold-start 전제를 제거하고 `enableInboundGateway` 기본 receive gateway 의미에 맞게 정리한다.
- [x] `typescript/test/ws.test.ts`의 default gateway 테스트 주석에서 `worker_threads gateway`, worker pool cold-start 전제를 제거하고 `enableInboundGateway` 기본 receive gateway 의미에 맞게 정리한다.
- [x] `cd typescript && npm run check && npm test -- --run test/tcp.test.ts test/ws.test.ts`를 실행해 타입 검사와 변경된 transport 테스트가 통과하는지 확인한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_local_G06_N.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G06_M.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리 `agent-task/m-performance-hotspot-optimization/01_ts_gateway_single_path/`를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/01_ts_gateway_single_path/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [x] PASS이고 task group이 `m-performance-hotspot-optimization`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-performance-hotspot-optimization/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
## 계획 대비 변경 사항
계획 대비 변경 사항 없음.
## 주요 설계 결정
- `typescript/test/tcp.test.ts` 및 `typescript/test/ws.test.ts` 파일 내 기본 receive gateway를 타는 transport 테스트 시나리오에서, 이전 worker_threads gateway 백엔드를 기술하던 `worker_threads gateway`, `off-thread decode`, `cold-start` lazy spawn 등의 stale한 설명 주석들을 완전히 걷어냈습니다.
- 그 대신 `enableInboundGateway` 기본 receive gateway 의미에 부합하도록 inline decode 및 reorder 흐름을 설명하고, 동시 요청 밀집 검증 특성상 충분한 timeout 여유를 준다는 내용으로 보완했습니다.
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음
## 리뷰어를 위한 체크포인트
- TCP/WS default gateway 테스트 안에 `worker_threads`, `off-thread`, worker pool cold-start 설명이 남지 않았는지 확인한다.
- explicit worker_threads path 테스트는 `communicator.test.ts`에 별도로 남아 있고, default path 설명과 섞이지 않는지 확인한다.
- 타입 검사와 변경된 transport 테스트 검증 출력이 실제 명령과 일치하는지 확인한다.
## 검증 결과
```bash
$ cd typescript && npm run check && npm test -- --run test/tcp.test.ts test/ws.test.ts
> proto-socket@1.0.5 check
> tsc --noEmit
> proto-socket@1.0.5 test
> vitest run --run test/tcp.test.ts test/ws.test.ts
RUN v3.2.4 /config/workspace/proto-socket/typescript
✓ test/tcp.test.ts (7 tests) 256ms
✓ test/ws.test.ts (7 tests) 1088ms
Test Files 2 passed (2)
Tests 14 passed (14)
```
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
Sections and their ownership:
| Section | Owner | Note |
|---------|-------|------|
| Header, 개요, 리뷰 에이전트 지시, Roadmap Targets | Fixed at stub creation | Implementing agent must not modify |
| 구현 항목별 완료 여부, 구현 체크리스트 | Implementing agent | Check completed items only |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify |
| 계획 대비 변경 사항, 주요 설계 결정, 검증 결과 | Implementing agent | Fill with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required |
## 코드리뷰 결과
- 종합 판정: PASS
- 차원별 평가:
- correctness: Pass
- completeness: Pass
- test coverage: Pass
- API contract: Pass
- code quality: Pass
- plan deviation: Pass
- verification trust: Pass
- 발견된 문제: 없음
- 다음 단계: PASS이므로 `complete.log` 작성 후 active task 디렉터리를 archive로 이동한다.

42
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/complete.log Normal file
View file

@ -0,0 +1,42 @@
# Complete - m-performance-hotspot-optimization/01_ts_gateway_single_path
## 완료 일시
2026-06-04
## 요약
TypeScript default receive gateway 의미와 TCP/WS 기본 경로 테스트 정리를 2회 리뷰 루프 끝에 PASS로 완료했다.
## 루프 이력
| Plan | Review | Verdict | 메모 |
|------|--------|---------|------|
| `plan_local_G08_0.log` | `code_review_cloud_G07_0.log` | FAIL | TCP/WS default gateway 테스트에 남은 worker_threads/off-thread cold-start 설명이 default path와 explicit worker path를 다시 혼동시켜 follow-up 필요 |
| `plan_local_G06_1.log` | `code_review_local_G06_1.log` | PASS | stale worker_threads/off-thread/cold-start 주석을 제거하고 default receive gateway 설명과 검증 출력이 일치함 |
## 구현/정리 내용
- `Communicator.enableInboundGateway()`와 explicit Node worker gateway 문서를 default receive gateway와 worker_threads backend가 섞이지 않게 정리했다.
- TCP/WS read loop gateway 테스트를 `createNodeWorkerGateway` 직접 attach에서 `comm.enableInboundGateway({ workers: 2 })` 기본 gateway 경로 검증으로 전환했다.
- TCP/WS default gateway 테스트 안의 stale worker_threads/off-thread/cold-start 주석을 inline decode + reorder 의미에 맞게 정리했다.
## 최종 검증
- `cd typescript && npm run check && npm test` - PASS; TypeScript 전체 check/test 재실행 결과 5 test files, 56 tests passed.
- `cd typescript && npm run check && npm test -- --run test/tcp.test.ts test/ws.test.ts` - PASS; follow-up 검증 재실행 결과 2 test files, 14 tests passed.
## Roadmap Completion
- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Completed task ids:
- `ts-gateway-single-path`: PASS; evidence=`agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/plan_local_G08_0.log`, `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/code_review_cloud_G07_0.log`, `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/plan_local_G06_1.log`, `agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/code_review_local_G06_1.log`; verification=`cd typescript && npm run check && npm test`, `cd typescript && npm run check && npm test -- --run test/tcp.test.ts test/ws.test.ts`
- Not completed task ids: 없음
## 잔여 Nit
- 없음
## 후속 작업
- 없음

104
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/plan_local_G06_1.log Normal file
View file

@ -0,0 +1,104 @@
<!-- task=m-performance-hotspot-optimization/01_ts_gateway_single_path plan=1 tag=REVIEW_REFACTOR -->
# Implementation Plan - REVIEW_REFACTOR
## 이 파일을 읽는 구현 에이전트에게
이 계획은 직전 코드리뷰의 Required 항목만 해결한다. `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것까지가 구현이다. 검증 명령을 실행하고 실제 출력/메모를 review stub에 기록한 뒤 active 파일을 그대로 둔 채 리뷰 준비를 보고한다. 구현 중 사용자 결정, 사용자 소유 외부 환경, 범위 충돌 없이는 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 근거를 채우고 멈춘다. 명령 재실행이나 산출물 수집으로 해결 가능한 증거 공백은 사용자 리뷰 요청이 아니다.
## 배경
직전 review(`code_review_cloud_G07_0.log`)에서 TypeScript 검증은 통과했지만, TCP/WS default gateway 테스트에 남은 주석이 여전히 `worker_threads gateway`와 off-thread cold-start를 설명했다. 이 subtask는 default receive gateway와 explicit worker path를 혼동하지 않게 정리하는 것이 핵심이므로, stale 주석을 고쳐야 완료 판정이 가능하다.
## 사용자 리뷰 요청 흐름
구현 중 차단은 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
## 범위 결정 근거
이번 follow-up은 직전 FAIL의 Required 주석 불일치만 다룬다. `Communicator`, gateway 구현, worker_threads explicit path, benchmark row, 다른 언어 구현은 변경하지 않는다. Roadmap target은 동일하며, source comment 정합성이 회복되면 같은 Milestone Task 완료 후보로 다시 평가한다.
## 빌드 등급
`local-G06`. 동작 변경 없이 테스트 주석의 의미 정합성을 회복하는 좁고 결정적인 수정이다. 리뷰도 source comment와 검증 출력 대조로 판단 가능하므로 `local-G06`으로 둔다.
## 구현 체크리스트
- [ ] `typescript/test/tcp.test.ts`의 default gateway 테스트 주석에서 `off-thread decode`, `worker_threads gateway`, worker pool cold-start 전제를 제거하고 `enableInboundGateway` 기본 receive gateway 의미에 맞게 정리한다.
- [ ] `typescript/test/ws.test.ts`의 default gateway 테스트 주석에서 `worker_threads gateway`, worker pool cold-start 전제를 제거하고 `enableInboundGateway` 기본 receive gateway 의미에 맞게 정리한다.
- [ ] `cd typescript && npm run check && npm test -- --run test/tcp.test.ts test/ws.test.ts`를 실행해 타입 검사와 변경된 transport 테스트가 통과하는지 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## [REVIEW_REFACTOR-1] TCP default gateway 주석 정리
### 문제
`typescript/test/tcp.test.ts:245`의 테스트는 `comm.enableInboundGateway({ workers: 2 })`를 사용해 default receive gateway를 검증하지만, 주석은 아직 `gateway off-thread decode`와 `worker_threads gateway` lazy spawn/cold-start를 말한다. 이 표현은 default path가 worker_threads backend라는 오해를 다시 만든다.
### 해결 방법
TCP 테스트의 요청/timeout 설명을 default receive gateway 기준으로 바꾼다. 예를 들어 inline PacketBase decode 결과가 reorder/sink serialization을 거쳐 nonce 상관관계를 유지한다는 의미를 남기고, worker_threads cold-start 설명은 제거한다.
### 수정 파일 및 체크리스트
- [ ] `typescript/test/tcp.test.ts`: stale worker/off-thread/cold-start 주석 제거 및 default receive gateway 설명으로 교체.
### 테스트 작성
새 테스트는 만들지 않는다. 기존 TCP 테스트의 의미 설명만 정리한다.
### 중간 검증
```bash
cd typescript && npm run check && npm test -- --run test/tcp.test.ts
```
기대 결과: exit code 0.
## [REVIEW_REFACTOR-2] WS default gateway 주석 정리
### 문제
`typescript/test/ws.test.ts:245`의 테스트도 `comm.enableInboundGateway({ workers: 2 })`를 사용하지만, timeout 설명은 여전히 `worker_threads gateway` lazy spawn/cold-start를 전제로 한다. 직전 계획의 default path와 explicit worker path 분리 목적과 충돌한다.
### 해결 방법
WS 테스트의 stale worker_threads timeout 설명을 제거하고, 필요하면 transport/request concurrency timeout 여유 정도로만 설명한다. default receive gateway가 worker_threads backend를 기본으로 쓰지 않는다는 의미가 흐려지지 않게 한다.
### 수정 파일 및 체크리스트
- [ ] `typescript/test/ws.test.ts`: stale worker/cold-start 주석 제거 및 default receive gateway 설명으로 교체.
### 테스트 작성
새 테스트는 만들지 않는다. 기존 WS 테스트의 의미 설명만 정리한다.
### 중간 검증
```bash
cd typescript && npm run check && npm test -- --run test/ws.test.ts
```
기대 결과: exit code 0.
## 수정 파일 요약
| 파일 | 항목 |
|---|---|
| `typescript/test/tcp.test.ts` | REVIEW_REFACTOR-1 |
| `typescript/test/ws.test.ts` | REVIEW_REFACTOR-2 |
## 최종 검증
```bash
cd typescript && npm run check && npm test -- --run test/tcp.test.ts test/ws.test.ts
```
기대 결과: exit code 0. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

192
agent-task/archive/2026/06/m-performance-hotspot-optimization/01_ts_gateway_single_path/plan_local_G08_0.log Normal file
View file

@ -0,0 +1,192 @@
<!-- 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

107
agent-task/m-performance-hotspot-optimization/02+01_ts_gateway_perf_rows/CODE_REVIEW-cloud-G07.md Normal file
View file

@ -0,0 +1,107 @@
<!-- 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 세분화 | [ ] |
| [REFACTOR-2] Performance Wrapper와 결과 해석 확인 | [ ] |
## 구현 체크리스트
- [ ] 선행 `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의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
## 코드리뷰 전용 체크리스트
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
- [ ] PASS이면 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [ ] PASS이면 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-performance-hotspot-optimization/02+01_ts_gateway_perf_rows/`로 이동한다.
- [ ] PASS이고 task group이 `m-performance-hotspot-optimization`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
## 계획 대비 변경 사항
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
## 주요 설계 결정
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
## 사용자 리뷰 요청
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/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을 새 기준값으로 확정했다고 주장하지 않는지 확인한다.
## 검증 결과
### 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
(output)
```
### REFACTOR-2 중간 검증
```bash
$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
(output)
```
### 최종 검증
```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
(output)
```
---
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**

188
agent-task/m-performance-hotspot-optimization/02+01_ts_gateway_perf_rows/PLAN-cloud-G07.md Normal file
View file

@ -0,0 +1,188 @@
<!-- 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.

6
typescript/src/communicator.ts
View file

@ -162,8 +162,8 @@ export class Communicator {
} }
/** /**
* receive coordinator 앞단에 default worker-pool gateway를 attach한다. {@link onReceivedFrame}으로 제출된 * receive coordinator 앞단에 default receive gateway를 attach한다. 기본 gateway는 worker_threads hop 없이
* raw frame은 pool이 decode하고 내부 `seq`로 reorder해 coordinator의 {@link enqueueInbound}로 전달하므로 * raw frame에 내부 `seq`를 부여하고 inline decode 결과를 reorder/sink serialization으로 coordinator에 전달한다.
* FIFO dispatch와 stateful 처리 소유권은 coordinator에 유지된다. * FIFO dispatch와 stateful 처리 소유권은 coordinator에 유지된다.
* *
* opt-in이며 attach하지 않으면 {@link onReceivedFrame}은 호출 컨텍스트에서 inline decode한다. Node는 * opt-in이며 attach하지 않으면 {@link onReceivedFrame}은 호출 컨텍스트에서 inline decode한다. Node는
@ -193,7 +193,7 @@ export class Communicator {
/** /**
* custom {@link InboundGateway}를 receive coordinator 앞단에 설치한다. gateway sink는 coordinator 소유권을 * custom {@link InboundGateway}를 receive coordinator 앞단에 설치한다. gateway sink는 coordinator 소유권을
* 보존하기 위해 decoded frame을 {@link enqueueInbound}로 전달해야 한다. default worker-pool gateway는 * 보존하기 위해 decoded frame을 {@link enqueueInbound}로 전달해야 한다. default receive gateway는
* {@link enableInboundGateway}를 사용한다. * {@link enableInboundGateway}를 사용한다.
*/ */
attachInboundGateway(gateway: InboundGateway): void { attachInboundGateway(gateway: InboundGateway): void {

7
typescript/src/node_inbound_gateway.ts
View file

@ -142,9 +142,10 @@ function spawnDecodeWorker(): Worker {
} }
/** /**
* Node `worker_threads`로 PacketBase decode를 off-thread 처리하는 inbound gateway를 만든다. 결과는 내부 * Node `worker_threads`로 PacketBase decode를 off-thread 처리하는 inbound gateway를 만든다.
* `seq`로 reorder된 뒤 입력 순서로 sink에 전달되므로, 수신 coordinator가 FIFO dispatch와 stateful 처리를 * 이 함수는 기본 gateway 경로가 아니며, explicit Node worker backend 성능 튜닝이나 실험용으로만 명시적으로 attach한다.
* 단독 소유한다는 계약을 유지한다. * 결과는 내부 `seq`로 reorder된 뒤 입력 순서로 sink에 전달되므로, 수신 coordinator가 FIFO dispatch와
* stateful 처리를 단독 소유한다는 계약을 유지한다.
* *
* `workers <= 0`이면 사용 가능한 병렬도로 기본값을 적용한다. transferable `ArrayBuffer`로 decode 결과 payload * `workers <= 0`이면 사용 가능한 병렬도로 기본값을 적용한다. transferable `ArrayBuffer`로 decode 결과 payload
* 복사를 줄인다. browser 등 `worker_threads` 미지원 환경에서는 이 모듈을 import하지 말고, inline decode를 * 복사를 줄인다. browser 등 `worker_threads` 미지원 환경에서는 이 모듈을 import하지 말고, inline decode를

8
typescript/test/communicator.test.ts
View file

@ -605,7 +605,9 @@ describe("Communicator inbound gateway", () => {
await comm.close(); await comm.close();
}); });
test("Node worker_threads gateway: off-thread decode가 입력 순서를 보존한다", async () => { // 이 테스트는 기본 단일 경로(default path)가 아닌, 명시적으로 worker_threads 백엔드를
// 사용하는 경우의 입력 순서 보존 계약을 검증합니다.
test("Node worker_threads gateway (Explicit Path): off-thread decode가 입력 순서를 보존한다", async () => {
const comm = new Communicator(); const comm = new Communicator();
comm.initialize(new MockTransport(), parserMap()); comm.initialize(new MockTransport(), parserMap());
@ -806,7 +808,9 @@ describe("WorkerGateway cleanup stats", () => {
expect(after.closed).toBe(true); expect(after.closed).toBe(true);
}); });
test("Node worker gateway: pending decode가 있는 상태에서 close 후 workerPending=0", async () => { // 이 테스트는 명시적으로 worker_threads 백엔드를 사용하는 경우의 자원 정리 및
// workerPending 계측이 정상적으로 동작하는지 검증합니다.
test("Node worker gateway (Explicit Path): pending decode가 있는 상태에서 close 후 workerPending=0", async () => {
const gateway = createNodeWorkerGateway({ const gateway = createNodeWorkerGateway({
sink: () => {}, sink: () => {},
workers: 2, workers: 2,

17
typescript/test/tcp.test.ts
View file

@ -10,7 +10,7 @@ import {
parserFromSchema, parserFromSchema,
sendRequestTyped, sendRequestTyped,
} from "../src/communicator.js"; } from "../src/communicator.js";
import { createNodeWorkerGateway } from "../src/node_inbound_gateway.js";
import { create, TestDataSchema, type TestData } from "../src/packets/message_common_pb.js"; import { create, TestDataSchema, type TestData } from "../src/packets/message_common_pb.js";
import { connectTcp, connectTcpTls, TcpClient } from "../src/tcp_client.js"; import { connectTcp, connectTcpTls, TcpClient } from "../src/tcp_client.js";
import { TcpServer } from "../src/tcp_server.js"; import { TcpServer } from "../src/tcp_server.js";
@ -224,15 +224,9 @@ describe("TCP", () => {
let fifoViolation = false; let fifoViolation = false;
server.onClientConnected = (client) => { server.onClientConnected = (client) => {
const comm = client.communicator; const comm = client.communicator;
// 실제 TCP read loop가 onReceivedFrame으로 흘린 raw frame을 worker_threads gateway가 off-thread로 // 실제 TCP read loop가 onReceivedFrame으로 흘린 raw frame을 기본 receive gateway가
// decode하고, reorder 후 coordinator가 FIFO로 dispatch하는지 검증한다. // decode하고, reorder 후 coordinator가 FIFO로 dispatch하는지 검증한다.
comm.attachInboundGateway( comm.enableInboundGateway({ workers: 2 });
createNodeWorkerGateway({
sink: (frame) =>
comm.enqueueInbound(frame.typeName, frame.data, frame.incomingNonce, frame.responseNonce),
workers: 2,
}),
);
// raw addRequestListener로 nonce를 받아 gateway reorder 이후에도 connection별 nonce가 // raw addRequestListener로 nonce를 받아 gateway reorder 이후에도 connection별 nonce가
// 단조 증가(FIFO)하는지 확인한다. // 단조 증가(FIFO)하는지 확인한다.
comm.addRequestListener(TestDataSchema.typeName, (msg, nonce) => { comm.addRequestListener(TestDataSchema.typeName, (msg, nonce) => {
@ -248,9 +242,8 @@ describe("TCP", () => {
const client = await connectTcp("127.0.0.1", server.port, 0, 0, parserMap()); const client = await connectTcp("127.0.0.1", server.port, 0, 0, parserMap());
cleanup.push(async () => client.close()); cleanup.push(async () => client.close());
// 동시 요청이 gateway off-thread decode + reorder를 거쳐도 nonce 상관관계가 유지되어야 한다. // 동시 요청이 기본 receive gateway(inline decode + reorder)를 거쳐도 nonce 상관관계가 유지되어야 한다.
// worker_threads gateway는 첫 submit 시 worker pool을 lazily spawn하므로 cold-start를 흡수할 수 // 많은 동시 요청이 몰려도 순차 처리가 안전하게 보장되는지 검증하기 위해 요청 timeout에 충분한 여유를 둔다.
// 있게 요청 timeout을 넉넉히 둔다(기존 worker_threads 단위 테스트와 동일한 여유).
const results = await Promise.all( const results = await Promise.all(
Array.from({ length: 16 }, (_, i) => Array.from({ length: 16 }, (_, i) =>
sendRequestTyped( sendRequestTyped(

18
typescript/test/ws.test.ts
View file

@ -12,7 +12,7 @@ import {
parserFromSchema, parserFromSchema,
sendRequestTyped, sendRequestTyped,
} from "../src/communicator.js"; } from "../src/communicator.js";
import { createNodeWorkerGateway } from "../src/node_inbound_gateway.js";
import { create, TestDataSchema, type TestData } from "../src/packets/message_common_pb.js"; import { create, TestDataSchema, type TestData } from "../src/packets/message_common_pb.js";
import { connectNodeWs, connectNodeWss, NodeWsClient } from "../src/node_ws_client.js"; import { connectNodeWs, connectNodeWss, NodeWsClient } from "../src/node_ws_client.js";
import { NodeWsServer } from "../src/node_ws_server.js"; import { NodeWsServer } from "../src/node_ws_server.js";
@ -224,15 +224,9 @@ describe("WS", () => {
let fifoViolation = false; let fifoViolation = false;
server.onClientConnected = (client) => { server.onClientConnected = (client) => {
const comm = client.communicator; const comm = client.communicator;
// 실제 WS read loop가 onReceivedFrame으로 흘린 raw binary message를 worker_threads gateway가 // 실제 WS read loop가 onReceivedFrame으로 흘린 raw binary message를 기본 receive gateway가
// off-thread로 decode하고, reorder 후 coordinator가 FIFO로 dispatch하는지 검증한다. // decode하고, reorder 후 coordinator가 FIFO로 dispatch하는지 검증한다.
comm.attachInboundGateway( comm.enableInboundGateway({ workers: 2 });
createNodeWorkerGateway({
sink: (frame) =>
comm.enqueueInbound(frame.typeName, frame.data, frame.incomingNonce, frame.responseNonce),
workers: 2,
}),
);
// raw addRequestListener로 nonce를 받아 gateway reorder 이후에도 connection별 nonce가 // raw addRequestListener로 nonce를 받아 gateway reorder 이후에도 connection별 nonce가
// 단조 증가(FIFO)하는지 확인한다. // 단조 증가(FIFO)하는지 확인한다.
comm.addRequestListener(TestDataSchema.typeName, (msg, nonce) => { comm.addRequestListener(TestDataSchema.typeName, (msg, nonce) => {
@ -248,8 +242,8 @@ describe("WS", () => {
const client = await connectNodeWs("127.0.0.1", server.port, "/", 0, 0, parserMap()); const client = await connectNodeWs("127.0.0.1", server.port, "/", 0, 0, parserMap());
cleanup.push(async () => client.close()); cleanup.push(async () => client.close());
// worker_threads gateway는 첫 submit 시 worker pool을 lazily spawn하므로 cold-start를 흡수할 수 // 동시 요청이 기본 receive gateway(inline decode + reorder)를 거쳐도 nonce 상관관계가 유지되어야 한다.
// 있게 요청 timeout을 넉넉히 둔다(기존 worker_threads 단위 테스트와 동일한 여유). // 많은 동시 요청이 몰리는 혼합 경로 테스트이므로 요청 timeout에 충분한 여유를 둔다.
const results = await Promise.all( const results = await Promise.all(
Array.from({ length: 16 }, (_, i) => Array.from({ length: 16 }, (_, i) =>
sendRequestTyped( sendRequestTyped(