<!-- task=m-inbound-queue-ordering/10+09_stress_baseline plan=0 tag=TEST -->

# Plan - TEST Stress Baseline

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

이 계획의 구현이 끝나도 작업은 완료가 아니다. 반드시 같은 디렉터리의 `CODE_REVIEW-*-G??.md`에서 구현 에이전트 소유 섹션을 실제 구현 내용, 검증 출력, 계획 대비 변경 사항으로 채운 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 최종 판정, archive, `complete.log` 작성은 code-review 전용이다. 구현 중 사용자 결정, 사용자 소유 외부 환경, scope 충돌이 필요하면 review stub의 `사용자 리뷰 요청` 섹션을 근거와 함께 채우고 멈춘다. 단순 검증 증거 공백은 후속 에이전트가 명령 재실행으로 해소할 수 있으므로 사용자 리뷰 요청이 아니다.

## 배경

Milestone의 남은 큰 작업은 빠른 roundtrip, burst inbound, sustained load, multi-client, gateway on/off 비교 기준선이다. 이 범위는 언어별 단위 테스트가 아니라 반복 실행 가능한 benchmark/stress runner와 결과 기록 계약을 요구한다. `09_verify_ordering`이 기본 correctness evidence를 만든 뒤, 이 작업은 local 환경 의존 baseline을 남기는 도구와 최소 실행 경로를 추가한다.

## 사용자 리뷰 요청 흐름

구현 중 차단은 active `CODE_REVIEW-cloud-G08.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 요청의 정당성을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/milestones/inbound-queue-ordering.md`
- Task ids:
  - `rt-bench`: 빠른 request-response 왕복 메시징 벤치마크를 추가한다.
  - `burst-stress`: burst inbound traffic 스트레스 테스트를 추가한다.
  - `sustained-load`: 지속 부하 테스트 기준선을 추가한다.
  - `parallel-clients`: 다중 connection 병렬 스트레스 테스트를 추가한다.
  - `gateway-bench`: 언어별 worker gateway 성능 기준을 검증한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/current.md`
- `agent-roadmap/ROADMAP.md`
- `agent-roadmap/milestones/inbound-queue-ordering.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-full-matrix.md`
- `agent-ops/rules/project/domain/tools/rules.md`
- `dart/pubspec.yaml`
- `go/go.mod`
- `kotlin/build.gradle.kts`
- `python/pyproject.toml`
- `typescript/package.json`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`
- `dart/test/communicator_test.dart`
- `go/test/communicator_test.go`
- `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt`
- `python/test/test_communicator.py`
- `typescript/test/communicator.test.ts`

### 테스트 환경 규칙

- `test_env=local`; `agent-test/local/rules.md` present/read.
- 적용 profile: `agent-test/local/proto-socket-full-matrix.md`.
- 기본 최종 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`.
- benchmark/stress runner는 새 결과 파일을 `agent-test/runs/` 또는 기존 local result contract와 충돌하지 않는 tracked-excluded result path에 기록해야 한다.
- `<확인 필요>` 값 없음.

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

- `rt-bench`: 기존 crosstest에는 concurrent requests가 있으나 concurrency 1/16/64/256, latency p50/p95/p99, mismatch/timeout count 기록이 없다.
- `burst-stress`: communicator tests에는 수십-수백 단위 burst가 있으나 1k/10k configurable burst와 queue/pending leak report가 없다.
- `sustained-load`: 최소 30초 configurable sustained load와 memory/peak 지표 기록이 없다.
- `parallel-clients`: crosstest concurrent request는 단일 server/client 중심이며 여러 connection 독립 FIFO/nonce 오염 방지 기준선이 없다.
- `gateway-bench`: gateway on/off 비교 결과 기록이 없다.

### 심볼 참조

- renamed/removed symbol 없음.

### 분할 판단

- split decision policy를 먼저 평가했다.
- 이 subtask는 `10+09_stress_baseline`이므로 predecessor `09`가 필요하다.
- predecessor satisfaction: `agent-task/m-inbound-queue-ordering/09_verify_ordering/complete.log` 또는 `agent-task/archive/*/*/m-inbound-queue-ordering/09_verify_ordering/complete.log`가 있어야 구현을 시작한다. 현재 생성 시점에는 active plan만 있으므로 구현 에이전트는 시작 전 complete.log를 재확인한다.
- 별도 split 이유: benchmark/stress는 terminal runner, stdout/stderr parsing, result-record contract를 포함해 `09`의 단위 테스트 보강과 risk profile이 다르다.

### 범위 결정 근거

- wire format, proto schema, package version 변경 제외.
- 모든 언어의 production API를 새로 추가하지 않는다. benchmark는 test/crosstest/helper나 script entrypoint로 둔다.
- CI/CD 연결 제외. local matrix와 local stress result만 기준으로 한다.
- 절대 성능 합격선 고정 제외. 안정성 합격선은 mismatch/timeout/FIFO violation/leak 0이다.

### 빌드 등급

- build=`cloud-G08`, review=`cloud-G08`. terminal benchmark-style task, 다중 언어 실행, concurrency/stress risk가 있어 cloud 고등급으로 둔다.

## 구현 체크리스트

- [ ] 구현 시작 전 `09_verify_ordering`의 `complete.log`가 active 또는 archive에 있는지 확인한다.
- [ ] local stress/benchmark runner entrypoint와 결과 기록 형식을 추가한다.
- [ ] roundtrip, burst, sustained, parallel-clients, gateway on/off 측정 축을 configurable하게 구현한다.
- [ ] 안정성 합격선 mismatch/timeout/FIFO violation/pending leak 0을 runner exit code에 반영한다.
- [ ] focused stress smoke와 전체 local matrix를 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

1. `09_verify_ordering` complete.log 확인.
2. Stress runner/result contract 추가.
3. 최소 한 언어 기준 smoke로 runner 계약 검증.
4. 전체 matrix로 기존 호환성 회귀 확인.

## TEST-1 Stress runner contract

### 문제

[run_matrix.sh](/config/workspace/proto-socket/agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh:694)는 matrix 결과 기록을 남기지만, benchmark/stress용 metric schema가 없다. Milestone은 latency, timeout/error count, nonce mismatch count, FIFO violation, cleanup 상태를 요구한다.

### 해결 방법

새 runner를 `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`로 추가한다. Bash는 `set -euo pipefail`과 repo root 계산 패턴을 따른다. 결과 markdown에는 command, duration/concurrency/payload/burst, p50/p95/p99, mismatch counts, pending/queue cleanup, final PASS/FAIL을 기록한다.

### 수정 파일 및 체크리스트

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh` 추가.
- [ ] 결과 기록 path와 markdown schema 추가.
- [ ] `--quick` smoke와 configurable full mode를 분리한다.

### 테스트 작성

- 작성: script smoke command. shell parser는 deterministic stdout을 내야 한다.

### 중간 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick
```

기대: 결과 기록 파일 생성, final PASS.

## TEST-2 Roundtrip/burst/sustained/multi-client axes

### 문제

기존 communicator tests는 [typescript/test/communicator.test.ts](/config/workspace/proto-socket/typescript/test/communicator.test.ts:325) 같은 단위 FIFO와 crosstest concurrent request를 제공하지만, Milestone이 요구하는 1/16/64/256 concurrency, 1k/10k burst, 30초 sustained, multi-client 독립성 축을 한 runner에서 기록하지 않는다.

### 해결 방법

가장 유지보수 쉬운 기준 언어를 선택해 local server/client harness를 작성하고, 언어별 확장은 config table로 둔다. 빠른 smoke는 작은 duration/count로 실행하고, full mode는 Milestone 기준값을 사용한다. mismatch와 FIFO violation은 counters로 집계하고 0이 아니면 non-zero exit한다.

### 수정 파일 및 체크리스트

- [ ] request-response roundtrip 측정: concurrency 1/16/64/256 config.
- [ ] burst inbound 측정: quick에서는 작은 count, full에서는 1k/10k 이상.
- [ ] sustained load: quick duration과 full 30초 이상 config.
- [ ] parallel clients: connection별 counters와 nonce namespace 분리 확인.

### 테스트 작성

- 작성: runner quick mode가 deterministic PASS/FAIL을 산출하는 smoke.

### 중간 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --profile roundtrip,burst,sustained,parallel
```

기대: all selected profiles PASS.

## TEST-3 Gateway on/off baseline

### 문제

Gateway 구현은 완료되었지만 on/off 비교 결과를 같은 형식으로 기록하는 baseline이 없다. Milestone은 큰 payload 또는 burst traffic에서 gateway on/off 비교와 fallback 판단을 요구한다.

### 해결 방법

runner에 gateway mode axis를 추가한다. 지원 언어별 gateway option이 다르므로 구현 에이전트는 각 언어의 현재 opt-in 방식을 사용하고, 미지원/이득 불명확 환경은 fallback 기본값과 이유를 결과에 기록한다. PASS 기준은 순서/nonce/timeout 안정성 0 위반이다.

### 수정 파일 및 체크리스트

- [ ] gateway off baseline 기록.
- [ ] gateway on baseline 기록.
- [ ] payload size 또는 burst count를 config로 둔다.
- [ ] 이득이 불명확하면 성능 PASS가 아니라 safety fallback PASS로 기록한다.

### 테스트 작성

- 작성: quick gateway on/off smoke.

### 중간 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick --profile gateway
```

기대: gateway on/off 모두 안정성 counters 0.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh` | TEST-1, TEST-2, TEST-3 |
| `agent-test/runs/<generated-stress-result>.md` | TEST-1, TEST-2, TEST-3 |
| language-specific benchmark helpers under `dart/`, `go/`, `kotlin/`, `python/`, or `typescript/` as chosen | TEST-2, TEST-3 |

## 최종 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --quick
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
git diff --check
```

기대: stress quick PASS, matrix 전체 PASS, whitespace error 없음. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
