<!-- task=m-large-payload-followup-optimization/05_dart_large_packet_guard plan=0 tag=PERF -->

# Dart 1MB Payload Guard Plan

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

이 plan의 구현 완료 조건에는 대응 `CODE_REVIEW-local-G05.md`의 구현 에이전트 소유 섹션 작성이 포함된다. 구현 후 검증 명령을 실행하고 실제 출력, 계획 대비 변경, 주요 설계 결정을 채운 뒤 active 파일을 그대로 둔 채 리뷰 준비를 보고한다. 사용자만 결정할 수 있는 범위 변경, 외부 환경/secret/서비스 준비, 또는 구현을 안전하게 계속할 수 없는 충돌이 있으면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거를 기록하고 중단한다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 재실행으로 닫을 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다.

## 배경

현 마일스톤의 `[dart-large-packet-guard]`는 Dart TCP/WS 1MB payload 경로가 안정적으로 유지되는지 보호선을 만드는 작업이다. 최근 full 결과에서 Dart TCP/WS 1MB stability는 PASS지만 WS 1MB throughput은 20260610의 66.6 rps에서 20260613의 52.5 rps로 약 21% 하락했고 p99는 112.137ms에서 146.489ms로 약 31% 악화됐다. 이미 `run_performance.sh`에는 baseline 대비 throughput 20%, p99 25% WARN 비교가 있으므로 guard는 이 경로를 명시적으로 사용하고 WS 1MB correctness test 공백을 메우는 데 둔다.

## 사용자 리뷰 요청 흐름

구현 중 사용자 결정이 필요한 경우 active `CODE_REVIEW-local-G05.md`의 `사용자 리뷰 요청` 섹션에 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 기록한다. 구현 에이전트는 직접 사용자 프롬프트를 만들지 않으며, code-review가 해당 요청을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 판단한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/large-payload-followup-optimization.md`
- Task ids:
  - `dart-large-packet-guard`: Dart TCP/WS 1MB guard
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/dart/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-roadmap/current.md`
- `agent-roadmap/milestones/large-payload-followup-optimization.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-test/runs/20260613-141506-proto-socket-performance-full.md`
- `agent-test/runs/20260613-141506-proto-socket-stress-full.md`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`
- `dart/lib/src/protobuf_client.dart`
- `dart/lib/src/ws_protobuf_client_io.dart`
- `dart/lib/src/ws_protobuf_server.dart`
- `dart/lib/src/communicator.dart`
- `dart/lib/src/inbound_gateway_io.dart`
- `dart/bench/stress.dart`
- `dart/test/socket_test.dart`
- `dart/pubspec.yaml`

### 테스트 환경 규칙

- `test_env=local`; performance baseline profile을 읽었다.
- `run_stress.sh`의 stability hard gate와 `run_performance.sh`의 baseline regression WARN(`throughput-drop-pct=20`, `p99-worse-pct=25`)을 guard 검증으로 사용한다.
- layout 확인: `dart`, `bash`, `run_stress.sh`, `run_performance.sh`, `dart/pubspec.yaml` 존재 확인.

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

- `dart/test/socket_test.dart:991-1012`에는 TCP 1MB payload send test가 있지만 WS 1MB request/response test가 없다.
- `dart/bench/stress.dart:650-750`은 full payload 1MB row를 기록하지만 baseline이 없으면 regression 판정은 SKIPPED다. guard 완료에는 baseline 비교 명령을 명시해야 한다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- shared task group: `agent-task/m-large-payload-followup-optimization/`.
- sibling split은 `01_typescript_ws_1mb`, `02_typescript_tcp_tail`, `03_kotlin_tcp_parallel`, `04_ws_fixed_latency`, `05_dart_large_packet_guard`이며 모두 독립이다.
- 본 작업은 Dart guard/test와 performance comparison usage로 한정된다.

### 범위 결정 근거

- Dart runtime 최적화 자체는 제외한다. 이번 작업은 regression guard와 evidence path를 고정한다.
- TypeScript/Kotlin 성능 문제와 cross-language adapter는 제외한다.

### 빌드 등급

- `local-G05`: 단일 Dart test/bench guard이며 기존 performance script가 비교 로직을 제공한다. 다만 1MB WS regression 증거가 있어 중간 등급으로 둔다.

## 구현 체크리스트

- [ ] [PERF-1] Dart WS 1MB request/response correctness test를 추가해 TCP-only 1MB 테스트 공백을 닫는다.
- [ ] [PERF-2] Dart TCP/WS 1MB payload guard 검증 명령을 baseline comparison 경로로 고정하고 필요하면 stress output 식별성을 보강한다.
- [ ] Dart test와 Dart payload full stress, baseline regression comparison을 실행해 stability PASS 및 regression WARN/FAIL 여부를 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [PERF-1] WS 1MB correctness test 추가

문제: `dart/test/socket_test.dart:937-1013`의 large payload group은 TCP fragmentation과 TCP 1MB만 다룬다. `dart/lib/src/ws_protobuf_client_io.dart:62-88`의 WS drain queue와 `dart/lib/src/ws_protobuf_client_io.dart:105-107`의 write path가 1MB request/response를 유지하는지 unit 회귀가 없다.

해결 방법:

```dart
// before: dart/test/socket_test.dart:991
test('TCP 1MB payload roundtrip', () async {
  ...
});
```

```dart
// after: shape
test('WS 1MB payload roundtrip', () async {
  final server = _TestWsReqServer();
  ...
  final response = await client.sendRequest<TestData, TestData>(large).timeout(...);
  expect(response.message.length, equals(1024 * 1024));
});
```

- fixed port 충돌을 피하기 위해 기존 WS test server lifecycle pattern을 따른다.
- message length와 echo content prefix/suffix를 검증해 truncation을 잡는다.

수정 파일 및 체크리스트:

- [ ] `dart/test/socket_test.dart`: WS 1MB request/response test 추가.

테스트 작성: 필수. test name은 `WS 1MB payload roundtrip`로 두고 timeout은 기존 1MB payload보다 여유 있게 잡는다.

중간 검증:

```bash
cd dart && dart test test/socket_test.dart
```

예상 결과: exit 0, TCP/WS socket tests PASS.

### [PERF-2] baseline comparison guard 고정

문제: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh:317-339`는 baseline이 있을 때만 regression 비교를 수행한다. baseline 없이 payload stress만 실행하면 20260613 Dart WS 1MB처럼 20%대 회귀 후보가 PASS row로만 남는다.

해결 방법:

```bash
# before: ad hoc full stress only
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang dart --transport tcp,ws --profile payload
```

```bash
# after: guard evidence includes baseline comparison
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick --no-cross --baseline agent-test/runs/<baseline>.md --fail-on-regression
```

- repository에 고정 baseline file을 추가하지 않는다. 기존 `agent-test/runs/**`는 local artifact라 plan 검증에서 경로를 명시해 실행자가 선택한다.
- 구현 시 사용할 baseline 후보가 없으면 사용자 리뷰 요청이 아니라 review stub에 `command -v`/파일 확인 결과와 함께 fallback으로 full payload stress를 기록한다.
- 필요하면 `dart/bench/stress.dart` stderr에 payload label과 transport를 더 명확히 남긴다. ROW schema는 유지한다.

수정 파일 및 체크리스트:

- [ ] `dart/bench/stress.dart`: 필요 시 payload full row 식별 로그만 보강한다.
- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`: 비교 로직 변경은 원칙적으로 하지 않는다. 변경이 필요하면 이 plan 범위 초과로 review stub에 기록한다.

테스트 작성: 별도 unit test 없음. performance script의 baseline comparison이 guard다.

중간 검증:

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

예상 결과: exit 0, Dart TCP/WS payload=1MB rows PASS, stability counter 0.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `dart/test/socket_test.dart` | PERF-1 |
| `dart/bench/stress.dart` | PERF-2 |

## 최종 검증

```bash
cd dart && dart test test/socket_test.dart
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 --no-cross --baseline agent-test/runs/20260613-141506-proto-socket-performance-full.md --fail-on-regression
```

예상 결과: Dart tests exit 0. full payload stress는 Dart TCP/WS 1MB rows PASS, stability counter 0. baseline comparison은 regression warning이 있으면 non-zero가 맞으며, 그 경우 구현 에이전트는 WARN row를 review stub에 붙이고 guard가 회귀 후보를 잡았음을 기록한다.

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