/<!-- task=dart_web_e2e/02+01_multilang_matrix plan=0 tag=TEST -->

# Dart Web Multi-Language Matrix Plan

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채우는 것이 필수다. 이 subtask는 `agent-task/dart_web_e2e/01_browser_harness/complete.log`가 생긴 뒤 시작한다. 구현 후 검증 출력과 변경 사항을 기록하고, finalization은 code-review-skill에 맡긴다.

## 배경

기존 cross matrix의 Dart 열은 Dart VM/IO 클라이언트만 의미한다. Dart Web은 TCP와 서버가 불가능하고 WS 브라우저 클라이언트만 가능하므로 기존 Dart 셀과 다른 축으로 관리해야 한다. 브라우저 Origin, 서버별 WS handshake 정책, browser runner가 얽혀 있어 foundation 완료 후 별도 rollout이 적합하다.

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/dart/rules.md`
- `agent-ops/rules/project/domain/go/rules.md`
- `agent-ops/rules/project/domain/kotlin/rules.md`
- `agent-ops/rules/common/rules-roadmap.md`
- `agent-ops/roadmap/current.md`
- `agent-ops/roadmap/ROADMAP.md`
- `agent-ops/skills/common/router.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md`
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`
- `README.md`
- `dart/crosstest/dart_go.dart`
- `dart/crosstest/go_dart_client.dart`
- `go/crosstest/go_dart.go`
- `python/crosstest/python_dart.py`
- `python/proto_socket/ws_server.py`
- `kotlin/crosstest/kotlin_dart.kt`
- `kotlin/src/main/kotlin/com/tokilabs/proto_socket/WsServer.kt`
- `typescript/crosstest/typescript_dart.ts`
- `typescript/src/node_ws_server.ts`

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

- Dart.io server/client와 다른 언어 간 TCP/WS/TLS/WSS matrix: 기존 `cross_cases`로 커버됨.
- Dart.web import compile: unit matrix Dart 행에 추가됨.
- Dart.web browser client와 Dart.io/Go/Kotlin/Python/TypeScript WS 서버 간 E2E: 미커버.
- Dart.web server, TCP, TLS TCP: 플랫폼상 불가능하므로 matrix에서 `N/A`로 표현해야 한다.
- Dart.web WSS: 브라우저 인증서 신뢰 자동화가 없어 우선 `Deferred`로 둔다.

### 심볼 참조

- rename/remove 없음.
- `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`의 `cross_cases`는 [54-75](/config/workspace/proto-socket/agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh:54)에 5개 언어만 가진다.

### 분할 판단

분할 정책상 이 작업은 `01_browser_harness`에 의존한다. foundation은 브라우저 client와 Go 기준 smoke를 만들고, 이 계획은 서버 언어 확장, matrix 출력, README 문서화를 맡는다. broad rollout이지만 모두 동일한 harness를 사용하는 후속 작업이라 단일 subtask로 유지한다.

### 범위 결정 근거

새 프로토콜, proto schema, TCP browser emulation은 제외한다. Dart.web은 WS client only로 정의하고, Dart.io는 기존 Dart 행으로 유지한다. 외부 CI runner 연결은 README 정책상 deferred라 로컬 matrix까지만 반영한다.

### 빌드 등급

build=`cloud-G07`, review=`cloud-G07`. 다중언어 subprocess, browser runner, matrix 판정 로직이 포함되어 terminal/browser automation 등급이 필요하다.

## 구현 체크리스트

- [ ] [TEST-1] Dart.web client E2E를 Dart.io/Go/Kotlin/Python/TypeScript WS 서버로 확장한다.
- [ ] [TEST-2] 로컬 matrix 스크립트와 skill 문서에 Dart.io/Dart.web 축을 반영한다.
- [ ] [TEST-3] README에 Dart.io/Dart.web E2E matrix 표를 추가한다.
- [ ] [TEST-4] rollout 검증 명령을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

이 subtask는 디렉터리명 `02+01_multilang_matrix`에 따라 `agent-task/dart_web_e2e/01_browser_harness/complete.log`가 필요하다. 먼저 foundation browser harness를 재사용한 뒤 언어별 server runner와 matrix 출력을 확장한다.

### [TEST-1] Multi-Language Dart.web E2E

#### 문제

현재 matrix에서 Dart client는 [go/crosstest/go_dart.go](/config/workspace/proto-socket/go/crosstest/go_dart.go:365)처럼 `dart run crosstest/*_dart_client.dart`를 실행하는 VM/IO 클라이언트다. Dart.web 브라우저 client는 별도 축이 필요하다.

#### 해결 방법

foundation의 `dart/test/browser_ws_runtime_test.dart`를 재사용하거나 서버 식별자를 주입할 수 있게 보완한다. 서버별 runner를 추가한다.

Before:

```bash
# run_matrix.sh:55
Go|Dart|...|go run ./crosstest/go_dart.go
```

After:

```bash
Go|Dart.io|...|go run ./crosstest/go_dart.go
Go|Dart.web|...|go run ./crosstest/go_dart_web.go
```

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

- [ ] `dart/test/browser_ws_runtime_test.dart` 서버 라벨 또는 expected message 주입 지원
- [ ] `dart/crosstest/dart_web.dart` 추가, Dart.io WS server -> Dart.web client
- [ ] `kotlin/crosstest/kotlin_dart_web.kt` 추가
- [ ] `python/crosstest/python_dart_web.py` 추가
- [ ] `typescript/crosstest/typescript_dart_web.ts` 추가
- [ ] 기존 Go foundation runner를 matrix용 명령으로 확정

#### 테스트 작성

작성한다. 각 runner는 send-push와 request-response 최소 2개 scenario를 PASS/FAIL 라인으로 출력한다.

#### 중간 검증

```bash
cd dart && dart run crosstest/dart_web.dart
cd go && go run ./crosstest/go_dart_web.go
cd kotlin && ./gradlew run -PmainClass=com.tokilabs.proto_socket.crosstest.KotlinDartWebKt
cd python && python3 crosstest/python_dart_web.py
cd typescript && ./node_modules/.bin/tsx crosstest/typescript_dart_web.ts
```

기대 결과: 각 명령이 Dart.web 관련 PASS 라인을 출력하고 종료 코드 0.

### [TEST-2] Matrix Script And Skill Docs

#### 문제

[run_matrix.sh](/config/workspace/proto-socket/agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh:28)는 `Dart` 단일 열만 가진다. Dart.io와 Dart.web의 가능 범위가 다르므로 단일 셀은 의미가 모호하다.

#### 해결 방법

기존 `languages` 표는 호환성 회귀를 위해 유지하고, 별도 `web_cases`와 `print_dart_web_table`을 추가한다. `--all`과 `--cross`에서 Dart.web 표를 출력한다. skill 문서의 fallback 명령과 출력 형식도 같이 업데이트한다.

Before:

```bash
# run_matrix.sh:28
languages=("Dart" "Go" "Kotlin" "Python" "TypeScript")
```

After:

```bash
server_languages=("Dart.io" "Go" "Kotlin" "Python" "TypeScript")
web_cases=(...)
```

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

- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`에 Dart.web cases 추가
- [ ] PASS/FAIL line count 기준을 Dart.web scenario 수에 맞게 분리
- [ ] 실패 출력에 Dart.web 재현 명령 포함
- [ ] `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md` fallback과 출력 예시 업데이트

#### 테스트 작성

스크립트 자체는 shell이다. 별도 unit test 대신 실제 `--cross`와 `--unit` 실행으로 검증한다.

#### 중간 검증

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

기대 결과: 기존 cross table과 Dart.web table이 모두 출력되고 실패 시 재현 명령이 표시된다.

### [TEST-3] README Matrix Table

#### 문제

README의 구현 상태는 Dart를 하나의 구현으로 표시한다. Dart.io와 Dart.web의 지원 transport가 다르다는 사실이 드러나지 않는다.

#### 해결 방법

README Running Tests 또는 Implementations 아래에 Dart client variant 표를 추가한다.

| Server | Dart.io TCP | Dart.io WS | Dart.web WS | Dart.web WSS |
|---|---|---|---|---|
| Dart.io | Covered | Covered | Planned | Deferred |
| Go | Covered | Covered | Planned | Deferred |
| Kotlin | Covered | Covered | Planned | Deferred |
| Python | Covered | Covered | Planned | Deferred |
| TypeScript | Covered | Covered | Planned | Deferred |

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

- [ ] `README.md`에 Dart.io/Dart.web E2E matrix 표 추가
- [ ] `Dart.web`은 browser WS client only라고 명시
- [ ] WSS deferred 사유를 자체 서명 인증서 신뢰 자동화 부재로 명시

#### 테스트 작성

문서 변경이다. 별도 테스트는 작성하지 않고 matrix script 실행으로 명령 정합성을 검증한다.

#### 중간 검증

```bash
rg --sort path "Dart.web|Dart.io|browser WS" README.md
```

기대 결과: 새 표와 설명이 검색된다.

### [TEST-4] Rollout Verification

#### 문제

브라우저 E2E는 local machine의 Chrome availability, ports, server origin 정책에 민감하다. 최종 검증이 실제 entrypoint를 통과해야 한다.

#### 해결 방법

`--unit`은 Dart web compile을 계속 포함하고, `--cross`는 Dart.web runtime table을 포함한다.

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

- [ ] `bash ... --unit` PASS
- [ ] `bash ... --cross` PASS
- [ ] 실패 시 로그 디렉터리와 재현 명령 확인

#### 테스트 작성

별도 테스트 없음. matrix entrypoint 자체가 acceptance test다.

#### 중간 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --unit
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --cross
```

기대 결과: 두 명령 모두 PASS. Go test cache 여부와 무관하게 browser subprocess는 실제 실행된다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `dart/test/browser_ws_runtime_test.dart` | TEST-1 |
| `dart/crosstest/dart_web.dart` | TEST-1 |
| `go/crosstest/go_dart_web.go` | TEST-1 |
| `kotlin/crosstest/kotlin_dart_web.kt` | TEST-1 |
| `python/crosstest/python_dart_web.py` | TEST-1 |
| `typescript/crosstest/typescript_dart_web.ts` | TEST-1 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh` | TEST-2 |
| `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md` | TEST-2 |
| `README.md` | TEST-3 |

## 최종 검증

```bash
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --unit
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --cross
```

Go test cache는 `--cross` 판정에 사용하지 않는다. browser subprocess와 언어별 server runner가 실제 실행되어야 한다.

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