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

# TypeScript TCP 1024 Tail Follow-up Plan

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

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

## 배경

첫 리뷰에서 `cd typescript && npm run check`와 대상 unit/TCP 테스트는 통과했지만, 필수 hard gate인 TypeScript TCP full parallel stress가 현재 작업트리에서 재현 실패했다. 같은 명령의 새 결과 기록 `agent-test/runs/20260614-033946-proto-socket-stress-full.md`는 `clients=1024` row에서 Timeout 130을 기록한다. 이 후속 작업은 남은 1024-client tail timeout을 실제로 제거하고, 같은 full stress 명령의 새 PASS 증거를 남기는 데 한정한다.

## 사용자 리뷰 요청 흐름

구현 중 사용자 결정이 필요한 경우 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-ops/skills/common/_templates/implementation-user-review-request-section.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/plan_cloud_G07_0.log`
- `agent-task/m-large-payload-followup-optimization/02_typescript_tcp_tail/code_review_cloud_G07_0.log`
- `agent-test/runs/20260614-033946-proto-socket-stress-full.md`
- `typescript/src/communicator.ts`
- `typescript/src/tcp_client.ts`
- `typescript/src/tcp_server.ts`
- `typescript/src/base_client.ts`
- `typescript/src/node_ws_client.ts`
- `typescript/src/browser_ws_client.ts`
- `typescript/bench/stress.ts`
- `typescript/test/communicator.test.ts`
- `typescript/test/tcp.test.ts`
- `typescript/package.json`

### 테스트 환경 규칙

- `test_env=local`; `agent-test/local/rules.md`가 존재해 읽었다.
- 성능/병렬 tail 검증이므로 `agent-test/local/proto-socket-performance-baseline.md`를 적용한다.
- 리뷰 중 재실행한 명령:
  - `cd typescript && npm run check` → exit 0.
  - `cd typescript && npm test -- test/communicator.test.ts test/tcp.test.ts` → exit 0, 37 tests PASS.
  - `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --lang typescript --transport tcp --profile parallel` → exit 1, 결과 기록 `agent-test/runs/20260614-033946-proto-socket-stress-full.md`, `clients=1024 Timeout 130`.

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

- `typescript/test/communicator.test.ts`는 write blocked 중 response timeout이 시작되지 않는 단위 회귀와 write 완료 후 response timeout을 검증한다.
- 현재 실패는 1024 TCP client full stress tail에서만 재현된다. 단위 테스트는 유지하되, 완료 판정은 full stress `clients=1024 Timeout 0` hard gate로 닫아야 한다.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- 기존 split task `02_typescript_tcp_tail`의 같은 후속 루프다.
- sibling `03_kotlin_tcp_parallel`, `04_ws_fixed_latency`, `05_dart_large_packet_guard`는 수정하지 않는다.
- Required 이슈가 하나이며 TypeScript TCP communicator/send/write tail에 국한되므로 새 split을 만들지 않고 같은 active subtask에 단일 follow-up plan으로 이어간다.

### 범위 결정 근거

- stress matrix의 `clients`, `perClient`, `timeoutMs`를 완화해 PASS로 만드는 변경은 금지한다.
- Kotlin quick performance 실패, WebSocket 1MB, Dart payload guard, roadmap 문서 변경은 본 후속 범위가 아니다.
- 필요하면 TypeScript TCP tail 원인 파악을 위한 최소 계측을 추가할 수 있으나, 최종 변경은 production 코드 또는 테스트에 남길 가치가 있는 내용으로 정리한다. 임시 로그/디버그 출력은 제거한다.

### 빌드 등급

- `cloud-G07`: terminal benchmark-style full stress 재현 실패와 concurrency/timeout semantics를 함께 판단해야 하며, 검증 신뢰 회복이 핵심이다.

## 구현 체크리스트

- [ ] [REVIEW_PERF-1] 현재 작업트리의 TypeScript TCP full parallel `clients=1024 Timeout 130`을 재현/분석하고, 남은 send/write/response tail 원인을 수정해 같은 hard gate에서 Timeout 0을 확보한다.
- [ ] TypeScript check, 대상 unit/TCP 테스트, TypeScript TCP full parallel stress, quick performance를 실행하고 실제 stdout/stderr와 결과 기록 파일 경로를 review stub에 남긴다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_PERF-1] full parallel 1024 timeout hard gate 복구

문제: `agent-test/runs/20260614-033946-proto-socket-stress-full.md:43`에서 TypeScript TCP `parallel / clients=1024` row가 `Timeout 130`, 결과 `FAIL`이다. 현재 `typescript/src/communicator.ts:387-417`의 response timer 시작 시점 조정만으로는 `PERF-2` hard gate가 닫히지 않는다.

해결 방법:

```ts
// current: typescript/src/communicator.ts:387
return new Promise<TRes>((resolve, reject) => {
  this.pendingRequests.set(requestNonce, {
    expectedTypeName: resType.typeName,
    timer: null,
    resolve: (msg) => resolve(msg as TRes),
    reject,
  });
  void this.queuePacket(...).then(() => {
    const pending = this.pendingRequests.get(requestNonce);
    if (pending === undefined) return;
    pending.timer = setTimeout(...);
  }, ...);
});
```

- 같은 full stress 명령을 먼저 재현해 현재 실패가 `clients=1024 Timeout > 0`인지 확인한다.
- queue wait, `transport.writePacket` wait, pending timer start, response receive 간 시간을 분리해 남은 tail 위치를 좁힌다. 임시 계측은 최종 전 제거하거나, 유지할 경우 deterministic하고 일반 사용자 출력에 noise를 만들지 않게 한다.
- `Communicator.sendRequest`, `queuePacket`, `runWriteQueue`, TCP transport write 완료 의미 중 실제 원인에 해당하는 경로만 수정한다.
- `clients`, `perClient`, `timeoutMs`, required hard gate, timeout 분류 로직을 완화하지 않는다.
- write 실패/close/shutdown cleanup, 빠른 response-before-write-resolve race, pending leak 0 계약을 유지한다.

수정 파일 및 체크리스트:

- [ ] `typescript/src/communicator.ts`: 남은 tail 원인에 맞게 send/write/timeout semantics를 수정한다.
- [ ] `typescript/test/communicator.test.ts`: 새 semantics 또는 edge race가 생기면 회귀 테스트를 추가/수정한다.
- [ ] `typescript/bench/stress.ts`: matrix 완화 없이 필요한 결과/계측만 최소 보강한다. 보강이 불필요하면 수정하지 않는다.

테스트 작성: bug fix이므로 regression test 필요. 기존 blocked-write tests가 충분하지 않으면 `typescript/test/communicator.test.ts`에 queue/write/response tail을 더 직접 검증하는 테스트를 추가한다. 1024-client tail 자체는 full stress harness로 검증한다.

중간 검증:

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

예상 결과: exit 0, 기존 37 tests와 신규/수정 regression PASS.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `typescript/src/communicator.ts` | REVIEW_PERF-1 |
| `typescript/test/communicator.test.ts` | REVIEW_PERF-1 |
| `typescript/bench/stress.ts` | REVIEW_PERF-1, 필요한 경우만 |

## 최종 검증

```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 `parallel / clients=1024` 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
