<!-- task=m-performance-hotspot-optimization/12+10,11_dart_isolate_large_payload plan=0 tag=REFACTOR -->

# Code Review Reference - REFACTOR

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> Do not implement until predecessors `10` and `11` have `complete.log`.

## 개요

date=2026-06-06
task=m-performance-hotspot-optimization/12+10,11_dart_isolate_large_payload, plan=0, tag=REFACTOR

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/performance-hotspot-optimization.md`
- Task ids:
  - `dart-isolate-large-payload-transfer`: isolate gateway large payload 전달 비용 축소
- Completion mode: check-on-pass

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

> **[REVIEW AGENT ONLY]** 종결 절차는 코드리뷰 에이전트 전용이다.

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REFACTOR-1] Transferable IO frame handoff | [x] |
| [REFACTOR-2] Web fallback and cleanup preservation | [x] |
| [REFACTOR-3] 1MB payload performance evidence | [x] |

## 구현 체크리스트

- [x] predecessor `10`과 `11` complete.log 존재를 확인한다.
- [x] IO gateway에서 large frame submit에 `TransferableTypedData` 또는 동등한 최소-copy 방식을 적용한다.
- [x] web fallback은 `dart:isolate` import 없이 기존 sync path를 유지한다.
- [x] 1MB frame decode correctness와 close cleanup tests를 추가/갱신한다.
- [x] `run_stress.sh --full --lang dart --transport tcp,ws --profile payload` 결과에서 TCP/WS 1MB p99/throughput/memory/stability를 기록한다.
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

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

- [x] 판정을 append한다.
- [x] PASS이면 complete/archive 절차와 런타임 완료 이벤트를 처리한다.

## 계획 대비 변경 사항

계획과 동일하게 `TransferableTypedData`를 활용하여 low-copy 프레임 전달 및 디코드 결과 전달 구조를 설계하고 구현을 마쳤습니다.

## 주요 설계 결정

1. **임계값 기반 TransferableTypedData 전환**:
   - `IsolateInboundGateway.transferableThreshold`를 `32768` (32KB)로 정의하여, 32KB 이상의 대용량 프레임에 대해서만 `TransferableTypedData`를 생성하도록 최적화했습니다. 임계값보다 작은 프레임은 기존과 같이 일반 복사 패스로 전달되어 소형 프레임 전달의 오버헤드를 막습니다.
2. **양방향 복사 오버헤드 최소화**:
   - Main isolate에서 Worker isolate로 프레임을 전달할 때뿐만 아니라, Worker isolate에서 디코딩한 `PacketBase.data` 페이로드를 다시 Main isolate로 반환할 때도 크기가 임계값 이상이면 `TransferableTypedData`로 전달하도록 최적화하여 1MB 대형 페이로드 전송 효율을 극대화했습니다.
3. **Web Fallback 안정성 유지**:
   - `TransferableTypedData` 및 `dart:isolate` 의존성은 오직 IO 전용 소스인 `inbound_gateway_io.dart` 내부에만 한정되도록 분리하여, Web fallback인 `inbound_gateway_web.dart` 및 웹 컴파일 경로(`browser_ws_import_compile.dart`)가 깨지지 않고 안전하게 `SyncInboundGateway`를 참조하도록 유지했습니다.

## 사용자 리뷰 요청

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

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

- `TransferableTypedData`가 IO-only 파일에 갇혀 web compile을 깨지 않는지 확인한다.
- 1MB correctness test와 full payload row가 모두 있는지 확인한다.
- 다른 host baseline과 절대 비교를 단정하지 않았는지 확인한다.

## 검증 결과

### REFACTOR-1 중간 검증
```text
$ cd dart && dart test test/communicator_test.dart -r expanded
00:00 +0: loading test/communicator_test.dart
...
00:00 +25: Communicator protocol guards IsolateInboundGateway: 1MB large payload가 TransferableTypedData를 거쳐 올바르게 디코드된다
00:00 +26: Communicator protocol guards IsolateInboundGateway: 1MB large payload (List<int>)가 TransferableTypedData를 거쳐 올바르게 디코드된다
...
00:00 +28: All tests passed!
```

### REFACTOR-3 중간 검증
```text
$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang dart --transport tcp,ws --profile payload
RUN stress lang=dart mode=full transports=tcp,ws profiles=payload
[payload] transport=tcp size=1KB bytes=1029 peakMemMb=215.9 violations=0
[payload] transport=tcp size=64KB bytes=65542 peakMemMb=258.8 violations=0
[payload] transport=tcp size=1MB bytes=1048582 peakMemMb=305.9 violations=0
[payload] transport=ws size=1KB bytes=1029 peakMemMb=308.7 violations=0
[payload] transport=ws size=64KB bytes=65542 peakMemMb=308.9 violations=0
[payload] transport=ws size=1MB bytes=1048582 peakMemMb=306.9 violations=0
DONE dart: PASS (rows=6 skips=0 required_skips=0 violations=0)
결과 기록 파일: `agent-test/runs/20260606-050440-proto-socket-stress-full.md`

| Profile | Axis | Language | Transport | Payload(bytes) | Clients | Throughput(rps) | p99(ms) | Mem(MB) | 결과 |
|---|---|---|---|---:|---:|---:|---:|---|---|
| payload | payload=1KB | Dart | tcp | 1029 | 1 | 2067.3 | 22.163 | 215.9 | PASS |
| payload | payload=64KB | Dart | tcp | 65542 | 1 | 997.4 | 9.659 | 258.8 | PASS |
| payload | payload=1MB | Dart | tcp | 1048582 | 1 | 51.9 | 171.040 | 305.9 | PASS |
| payload | payload=1KB | Dart | ws | 1029 | 1 | 3111.8 | 10.209 | 308.7 | PASS |
| payload | payload=64KB | Dart | ws | 65542 | 1 | 894.9 | 13.213 | 308.9 | PASS |
| payload | payload=1MB | Dart | ws | 1048582 | 1 | 56.0 | 146.195 | 306.9 | PASS |
```

### 최종 검증
```text
$ cd dart && dart test test/communicator_test.dart test/socket_test.dart -r expanded
00:17 +67: All tests passed!

$ cd dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js
Compiled 10,874,863 input bytes (5,876,091 characters source) to 11,692 characters JavaScript in 0.49 seconds

$ 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/20260606-050449-proto-socket-stress-quick.md | /tmp/proto-socket-performance.Up1owj/same-language.log |
| cross-language | PASS | 0 | agent-test/runs/20260606-050518-proto-socket-stress-quick-cross.md | /tmp/proto-socket-performance.Up1owj/cross-language.log |
| typescript-gateway | PASS | 0 | agent-test/runs/20260606-051152-proto-socket-stress-quick.md | /tmp/proto-socket-performance.Up1owj/typescript-gateway.log |
```

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - correctness: Pass
  - completeness: Pass
  - test coverage: Pass
  - API contract: Pass
  - code quality: Pass
  - plan deviation: Pass
  - verification trust: Pass
- 발견된 문제:
  - Nit: `dart/test/communicator_test.dart:719`, `dart/test/communicator_test.dart:727`, `dart/test/communicator_test.dart:762`, `dart/test/communicator_test.dart:770`에 trailing whitespace가 남아 있다. 기능/검증을 막지는 않지만 후속 정리 시 `dart format dart/lib/src/inbound_gateway_io.dart dart/test/communicator_test.dart` 또는 공백 제거로 정리한다.
- 리뷰어 추가 검증:
  - `dart test test/communicator_test.dart -r expanded` - PASS, 28 tests passed.
  - `dart analyze lib/src/inbound_gateway_io.dart test/communicator_test.dart` - PASS, No issues found.
  - `dart test test/socket_test.dart -r expanded` - PASS, 41 tests passed.
  - `dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile_review.js` - PASS.
  - `git diff --check` - Nit 발견, trailing whitespace 4건.
- 다음 단계: PASS이므로 `complete.log` 작성 후 active task directory를 archive로 이동한다.
