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

# Plan - REFACTOR

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

이 plan은 `10_dart_isolate_gateway_contract`와 `11+10_dart_isolate_transport_path` 완료 후 구현한다. 두 predecessor complete.log가 없으면 구현하지 말고 review stub에 blocker를 기록한다. 구현 완료는 review stub 작성까지다.

## 배경

isolate gateway가 실제 TCP/WS 수신 경로에 붙으면 1MB frame에서 isolate message copy가 새로운 병목이 될 수 있다. Milestone은 `TransferableTypedData` 또는 동등한 최소-copy 방식을 확인하고 TCP/WS 1MB p99/throughput/memory row를 남기라고 요구한다.

## 사용자 리뷰 요청 흐름

선행 complete.log 부재, unavailable runtime, 범위 충돌만 `사용자 리뷰 요청`에 기록한다. 측정 증거 부족은 follow-up 검증으로 처리한다.

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

## 분석 결과

### 읽은 파일

- 공통/로드맵/plan/test 규칙 파일 일체
- `agent-roadmap/milestones/performance-hotspot-optimization.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-test/local/dart-smoke.md`
- `dart/lib/src/inbound_gateway.dart`
- `dart/lib/src/inbound_gateway_io.dart`
- `dart/lib/src/inbound_gateway_web.dart`
- `dart/lib/src/communicator.dart`
- `dart/lib/src/protobuf_client.dart`
- `dart/lib/src/ws_protobuf_client_io.dart`
- `dart/lib/src/ws_protobuf_client_web.dart`
- `dart/bench/stress.dart`
- `dart/test/communicator_test.dart`
- `dart/test/socket_test.dart`

### 테스트 환경 규칙

`test_env=local`. Dart smoke는 필수다. 성능 task라 `run_performance.sh --quick`을 실행하고, 1MB 확인은 `run_stress.sh --full --lang dart --transport tcp,ws --profile payload`로 좁혀 실행한다.

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

- `TransferableTypedData` path는 현재 없음.
- web fallback은 `dart:isolate`/Transferable unavailable이므로 compile-only와 sync fallback tests가 필요하다.
- 1MB memory/throughput row는 기존 `dart-tcp-1mb` full record가 있지만 isolate path 적용 후 새 record가 필요하다.

### 심볼 참조

변경 후보: `InboundFrame.bytes`(`dart/lib/src/inbound_gateway.dart:11-15`), `IsolateInboundGateway.submit`(`dart/lib/src/inbound_gateway_io.dart:65-69`), `_gatewayEntry` bytes materialization(`:96-99`), `SyncInboundGateway.submit`(`dart/lib/src/inbound_gateway.dart:104-118`).

### 분할 판단

subtask dir `12+10,11_dart_isolate_large_payload`는 predecessor `10`과 `11`에 의존한다. 현재 두 predecessor complete.log가 없으므로 의존성은 미충족이다. 이 plan은 large payload transfer와 1MB evidence만 다룬다.

### 범위 결정 근거

TCP buffer-copy task는 이미 완료 처리됐다. 이 plan은 isolate hop copy만 다루며, `_TcpFrameBuffer`, heartbeat, fixed latency, TypeScript/Kotlin 작업은 제외한다.

### 빌드 등급

`cloud-G07`. large payload memory/performance evidence와 IO/web conditional behavior가 필요하지만 선행 contract/path 완료 후 범위는 좁다.

## 의존 관계 및 구현 순서

1. `10_dart_isolate_gateway_contract` complete.log 확인.
2. `11+10_dart_isolate_transport_path` complete.log 확인.
3. IO isolate transfer path 구현.
4. web sync fallback compile/test 확인.
5. TCP/WS full payload rows 기록.

## 구현 체크리스트

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

### [REFACTOR-1] Transferable IO frame handoff

문제: IO gateway submit은 `[frame.seq, frame.bytes]` list를 isolate mailbox로 보낸다(`dart/lib/src/inbound_gateway_io.dart:65-69`). 1MB frame에서는 isolate message copy가 p99/memory 병목이 될 수 있다.

해결 방법:

```dart
// Before
_toWorker?.send([frame.seq, frame.bytes]);
```

```dart
// After sketch
final payload = frame.bytes is Uint8List && frame.bytes.length >= threshold
    ? TransferableTypedData.fromList([frame.bytes as Uint8List])
    : frame.bytes;
_toWorker.send([frame.seq, payload]);
```

worker는 `TransferableTypedData.materialize().asUint8List()`와 List path를 모두 처리한다.

수정 파일 및 체크리스트:
- [ ] `dart/lib/src/inbound_gateway_io.dart`
- [ ] `dart/lib/src/inbound_gateway.dart` 필요 시 bytes type 유지/정리

테스트 작성: 1MB raw frame을 gateway로 보내 decoded `TestData.message.length`가 보존되는 test를 추가한다.

중간 검증:

```bash
cd dart && dart test test/communicator_test.dart -r expanded
```

### [REFACTOR-2] Web fallback and cleanup preservation

문제: shared contract가 Transferable-specific type을 노출하면 `dart.library.html` compile이 깨질 수 있다. web fallback은 `SyncInboundGateway`를 유지해야 한다.

해결 방법: `TransferableTypedData` import와 materialize는 `inbound_gateway_io.dart` 내부에만 둔다. shared `InboundFrame`은 `List<int>`를 유지하거나 platform-neutral abstraction만 둔다.

수정 파일 및 체크리스트:
- [ ] `dart/lib/src/inbound_gateway.dart`
- [ ] `dart/lib/src/inbound_gateway_web.dart`
- [ ] `dart/test/communicator_test.dart`

테스트 작성: existing SyncInboundGateway tests 유지. compile js를 최종 검증으로 둔다.

중간 검증:

```bash
cd dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js
```

### [REFACTOR-3] 1MB payload performance evidence

문제: large payload transfer task 완료에는 TCP/WS 1MB p99/throughput/memory row가 필요하다.

해결 방법: focused full payload stress를 실행하고, 이전 Dart TCP 1MB record(`agent-test/runs/20260605-225539-proto-socket-stress-full.md`)와 같은 host/runtime/profile인지 구분해 기록한다. 다른 host면 절대 비교하지 말고 새 기준 row로 문서화한다.

수정 파일 및 체크리스트:
- [ ] 코드 변경 없음. 검증 산출물 수집.

테스트 작성: skip.

중간 검증:

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang dart --transport tcp,ws --profile payload
```

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `dart/lib/src/inbound_gateway_io.dart` | REFACTOR-1 |
| `dart/lib/src/inbound_gateway.dart` | REFACTOR-1, REFACTOR-2 |
| `dart/lib/src/inbound_gateway_web.dart` | REFACTOR-2 |
| `dart/test/communicator_test.dart` | REFACTOR-1, REFACTOR-2 |

## 최종 검증

```bash
cd dart && dart test test/communicator_test.dart test/socket_test.dart -r expanded
cd dart && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang dart --transport tcp,ws --profile payload
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
```

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