<!-- task=m-large-payload-followup-optimization/02_typescript_tcp_tail plan=2 tag=HARNESS -->

# TypeScript TCP 1024 Harness Redesign Plan

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

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

## 배경

사용자는 `USER_REVIEW.md`의 B 방향을 선택했다. 즉 TypeScript TCP 1024-client tail을 라이브러리 결함으로 단정하지 않고, in-process 단일 Node event loop에 client/server를 함께 몰아넣는 harness/판정 조건을 재정의한다. 목표는 hard gate를 없애는 것이 아니라, full TCP 1024 parallel row를 실제 사용 모델에 가까운 client/server 분리 topology로 측정하고 그 조건에서 Timeout 0을 검증하는 것이다.

## 사용자 리뷰 요청 흐름

구현 중 사용자 결정이 필요한 경우 active `CODE_REVIEW-cloud-G07.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:
  - `typescript-tcp-1024-tail-path`: TypeScript TCP parallel clients=1024 timeout tail 재현, 측정, 수정 계획 수립
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-roadmap/current.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/code-review/SKILL.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-test/local/rules.md`
- `agent-test/local/proto-socket-performance-baseline.md`
- `agent-task/m-large-payload-followup-optimization/02_typescript_tcp_tail/user_review_0.log`
- `agent-task/m-large-payload-followup-optimization/02_typescript_tcp_tail/plan_cloud_G07_1.log`
- `agent-task/m-large-payload-followup-optimization/02_typescript_tcp_tail/code_review_cloud_G07_1.log`
- `agent-test/runs/20260614-043353-proto-socket-stress-full.md`
- `agent-test/runs/20260614-055824-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`
- `typescript/bench/stress.ts`
- `typescript/src/communicator.ts`
- `typescript/src/tcp_client.ts`
- `typescript/src/tcp_server.ts`
- `typescript/src/base_client.ts`
- `typescript/package.json`

### 테스트 환경 규칙

- `test_env=local`; `agent-test/local/rules.md`가 존재해 읽었다.
- 성능/병렬 tail 검증이므로 `agent-test/local/proto-socket-performance-baseline.md`를 적용한다.
- 필수 검증은 TypeScript check/unit, TypeScript TCP full parallel stress, quick performance다.
- B 방향은 `clients`/`perClient`/`timeoutMs` hard gate를 단순 완화하지 않는다. 1024 TCP row의 측정 topology를 client/server 분리로 재정의하고, 새 record에 topology가 명확히 남아야 한다.

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

- 기존 `typescript/test/communicator.test.ts`는 response timer/write completion semantics를 검증하지만 harness topology를 검증하지 않는다.
- child process server lifecycle, ready/cleanup, 실패 시 stderr/exit 전파는 unit test보다 focused full stress와 script-level evidence가 더 직접적이다. 구현자가 작은 helper를 분리하면 unit test를 추가하고, 분리하지 않으면 script 실행 결과를 primary verification으로 둔다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- 기존 split task `02_typescript_tcp_tail`의 사용자 결정 재개 루프다.
- 수정 범위는 TypeScript stress harness와 runner record 설명에 국한되며, communicator/transport production semantics를 더 바꾸지 않는다.
- B 방향은 단일 cohesive harness redesign이므로 새 subtask를 만들지 않고 같은 active subtask에 plan=2로 이어간다.

### 범위 결정 근거

- 제외: `Communicator.sendRequest` 추가 수정, TCP transport production API 변경, Kotlin/Dart/WS sibling task, roadmap 문서 직접 갱신.
- 금지: `clients=1024`, `perClient=500`, `timeoutMs=15000`, timeout hard gate 자체를 낮춰 PASS로 만드는 변경.
- 허용: TypeScript TCP full parallel 1024 row를 in-process single-loop에서 client/server split-process topology로 전환하거나, row axis/record에 topology를 명시해 baseline 비교가 같은 조건끼리만 되게 만드는 변경.

### 빌드 등급

- `cloud-G07`: shell runner, TypeScript benchmark harness, child process orchestration, stdout/stderr/result-record 계약이 함께 바뀌는 terminal benchmark-style 작업이다.

## 구현 체크리스트

- [ ] [HARNESS-1] TypeScript TCP full parallel `clients=1024` row를 client/server 분리 topology로 측정하도록 stress harness를 재정의하고 record에 topology를 명시한다.
- [ ] [HARNESS-2] stress/performance runner의 판정 설명과 출력 record가 새 topology를 정확히 전달하도록 정리한다.
- [ ] TypeScript check, 대상 harness 검증, TypeScript TCP full parallel stress, quick performance를 실행하고 실제 stdout/stderr와 결과 기록 파일 경로를 review stub에 남긴다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [HARNESS-1] TypeScript TCP 1024 parallel split-process topology

문제: `typescript/bench/stress.ts:554`의 full parallel profile은 `clients=[16,128,512,1024]`, `perClient=500`, `timeoutMs=15000`으로 client와 server를 같은 Node event loop 안에서 실행한다. `user_review_0.log`와 `code_review_cloud_G07_1.log`의 진단에 따르면 `clients=1024` timeout은 communicator/write 결함보다 in-process single-loop starvation 성격이 강하다.

해결 방법:

```ts
// current: typescript/bench/stress.ts:554
async function profileParallel(transport: WireTransport, mode: Mode): Promise<void> {
  const clientCounts = mode === "quick" ? [4] : [16, 128, 512, 1_024];
  ...
  await withRequestServer(transport, stability, async (port) => {
    const clients = await Promise.all(
      Array.from({ length: clientCount }, () => connectClient(transport, port)),
    );
    ...
  });
}
```

- `transport === "tcp" && mode === "full" && clientCount >= 1024`에서 server를 별도 Node process로 띄우는 helper를 추가한다.
- child process는 hidden mode(예: `--server-child --transport=tcp`)로 request echo server만 실행하고, ready line으로 port를 부모에게 전달한다. child stdout은 protocol line만 쓰고, child stderr는 parent stderr에 prefix해 전달한다.
- parent는 기존 client load를 그대로 실행하되 server process lifecycle을 반드시 정리한다. 실패/timeout/interrupt에서도 child process가 남지 않아야 한다.
- row axis 또는 별도 field가 없으면 axis에 `clients=1024,topology=split-process`처럼 topology를 포함한다. 16/128/512 기존 rows는 `clients=N,topology=in-process` 또는 기존 axis를 유지하되, 1024 row만 topology를 명시한다. baseline 비교 key 변화가 의도된 조건 변경임을 record에서 볼 수 있어야 한다.
- 기존 hard gate는 유지한다: Timeout/NonceMis/TypeMis/FIFOViol/PendLeak는 모두 0이어야 PASS.

수정 파일 및 체크리스트:

- [ ] `typescript/bench/stress.ts`: split-process server child mode, parent orchestration, topology axis/record를 구현한다.
- [ ] `typescript/bench/stress.ts`: child process cleanup과 error propagation을 구현한다.
- [ ] `typescript/test/communicator.test.ts`: production communicator semantics가 변하지 않으면 수정하지 않는다.

테스트 작성: helper를 순수 함수로 분리하면 unit test를 추가한다. child process orchestration 자체는 `run_stress.sh --full --lang typescript --transport tcp --profile parallel`의 record로 검증한다.

중간 검증:

```bash
cd typescript && npm run check
cd typescript && npm test -- test/communicator.test.ts test/tcp.test.ts
```

예상 결과: exit 0.

### [HARNESS-2] runner/record 판정 설명 정리

문제: `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh:31`와 생성 record의 안정성 설명은 topology 조건을 설명하지 않는다. B 방향 이후에는 TypeScript TCP 1024 full row가 split-process topology임을 사람이 record만 보고도 알아야 한다.

해결 방법:

```bash
# current: run_stress.sh usage/stability text
Stability pass criteria (hard fail): timeout / nonce mismatch / response type mismatch /
per-connection FIFO violation / pending-queue leak all 0.
```

- runner usage 또는 record `안정성 합격선`에 TypeScript TCP full `parallel clients=1024`는 single-loop artifact를 피하기 위해 split-process topology로 측정한다는 설명을 추가한다.
- 필요하면 `run_performance.sh` 성능 판정 기준에도 same-language component가 harness topology를 record axis로 구분한다는 설명을 추가한다.
- 출력 계약(`ROW|...|status`)은 깨지지 않아야 한다. 기존 parser가 axis 문자열을 opaque field로 다루므로 axis에 topology를 넣는 방식이 가장 작다.

수정 파일 및 체크리스트:

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh`: usage/record 설명을 갱신한다.
- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh`: 필요하면 performance record 설명을 갱신한다.

테스트 작성: shell script unit test는 없다. `run_stress.sh`와 `run_performance.sh --quick` 실제 실행 record로 검증한다.

중간 검증:

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang typescript --transport tcp --profile parallel
```

예상 결과: exit 0, TypeScript TCP 1024 split-process row Timeout 0, 전체 결과값 PASS, 결과 기록 파일에 topology 조건이 보인다.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `typescript/bench/stress.ts` | HARNESS-1 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh` | HARNESS-2 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh` | HARNESS-2, 필요한 경우만 |

## 최종 검증

```bash
cd typescript && npm run check
cd typescript && npm test -- test/communicator.test.ts test/tcp.test.ts
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang typescript --transport tcp --profile parallel
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
```

예상 결과: TypeScript check/unit 명령 exit 0. full parallel stress는 TypeScript TCP 1024 split-process row `Timeout 0`, NonceMis 0, TypeMis 0, FIFOViol 0, PendLeak 0, 전체 결과값 PASS여야 한다. quick performance가 Kotlin sibling 범위 문제로 전체 FAIL이면 TypeScript same-language/cross-language/gateway PASS 여부와 실패 원인을 분리해 실제 stdout/stderr 및 결과 기록 파일로 남긴다.

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