proto-socket/agent-task/m-protocol-evolution-compatibility/02+01_legacy_alias/CODE_REVIEW-cloud-G07.md

Code Review Reference - ALIAS

[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation. The task is NOT complete until every implementation-owned section below is filled in. Complete the 구현 체크리스트; the final checklist item is mandatory before saving. Fill implementation-owned sections, then stop with active files in place and report ready for review. If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill 사용자 리뷰 요청 with evidence and stop with active files in place; code-review decides whether to write USER_REVIEW.md. Do not ask the user directly, present choices in chat, or call request_user_input during implementation. Finalization is review-agent-only.

개요

date=2026-06-15 task=m-protocol-evolution-compatibility/02+01_legacy_alias, plan=0, tag=ALIAS

Roadmap Targets

• Milestone: agent-roadmap/milestones/protocol-evolution-compatibility.md
• Task ids:
  • legacy-alias: parser lookup, listener/request handler routing, response type matching, pending expected type 비교에 동일 alias 규칙 적용
• Completion mode: check-on-pass

이 파일을 읽는 리뷰 에이전트에게

리뷰 완료는 plan 스킬의 종결 순서를 따른다. 이 dependent split은 predecessor complete.log 확인 여부를 특히 검토한다.

구현 항목별 완료 여부

항목	완료 여부
[ALIAS-1] Alias Registry Helpers	[x]
[ALIAS-2] Routing And Pending Matching	[x]
[ALIAS-3] HeartBeat Alias Consistency	[x]

구현 체크리스트

• 구현 시작 전 01_proto_fullname_foundation complete.log로 predecessor 완료를 확인한다.
• 각 언어에 canonical full name과 legacy simple name을 같은 identity group으로 다루는 helper를 추가한다.
• parser map 등록 시 full/simple alias를 모두 등록하고, simple alias가 서로 다른 full name으로 충돌하면 initialize 단계에서 실패시킨다.
• listener/request handler 등록과 상호 배타 검사, inbound dispatch, pending response expected type 비교가 같은 alias 규칙을 사용하게 한다.
• 각 언어 focused unit test로 simple legacy receive와 alias collision을 검증한다.
• CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

코드리뷰 전용 체크리스트

• 코드리뷰 결과에 PASS, WARN, FAIL 중 하나의 판정을 append한다.
• active files를 .log로 아카이브하고 PASS이면 complete.log를 작성한다.
• PASS이면 active task directory를 archive로 이동한다.
• PASS split 작업이면 dependency와 parent directory 상태를 확인한다.
• roadmap 수정이나 update-roadmap 직접 호출을 하지 않는다.

계획 대비 변경 사항

• 없음. 계획된 모든 설계 요구사항에 맞춰 5개 언어 구현체에 동일한 Alias 처리 로직을 적용 완료함.

주요 설계 결정

• Centralized Canonical Name Map: 각 언어의 Communicator 내부에 canonicalNameMap을 캐시하여, full name(패키지명 포함)과 simple name(alias)을 단일 identity group으로 묶어 O(1)로 lookup하도록 일관되게 구조화했습니다.
• Strict Collision Verification: 초기화(initialize) 단계에서 parserMap을 병렬 순회하며 simple alias가 서로 다른 두 full name에 매핑되어 충돌하는 경우 IllegalArgumentException/ValueError/panic 등으로 즉시 실패하도록 예외 제약을 추가했습니다.

사용자 리뷰 요청

• 상태: 없음
• 사유 유형: 없음
• 결정 필요: 없음
• 차단 근거: 없음
• 실행한 검증/명령: 없음
• 자동 후속 불가 이유: 없음
• 재개 조건: 없음

리뷰어를 위한 체크포인트

• Parser alias와 handler/listener alias가 서로 다른 helper를 쓰지 않는지 확인한다.
• Pending response expected type 비교가 simple/full 양쪽을 같은 identity로 보는지 확인한다.
• Simple alias collision이 초기화 단계에서 실패하는지 확인한다.
• HeartBeat 자동 등록이 alias helper를 통과하는지 확인한다.

검증 결과

ALIAS-1 중간 검증

$ go test ./...
ok  	git.toki-labs.com/toki/proto-socket/go	0.043s
ok  	git.toki-labs.com/toki/proto-socket/go/test	8.312s

$ cd kotlin && ./gradlew test
BUILD SUCCESSFUL in 15s

$ cd python && python3 -m pytest -q
.............................................                            [100%]
45 passed in 1.56s

$ cd typescript && npm run check && npm test
✓ test/base_client.test.ts (7 tests) 10ms
✓ test/browser_ws_client.test.ts (7 tests) 40ms
✓ test/tcp.test.ts (7 tests) 271ms
✓ test/communicator.test.ts (32 tests) 601ms
✓ test/ws.test.ts (12 tests) 1460ms
Test Files  5 passed (5)
     Tests  65 passed (65)

$ dart test test/communicator_test.dart
00:00 +30: All tests passed!

최종 검증

$ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
**Proto 동기화**
| 검사 | 명령 | 결과 |
|---|---|---|
| schema sync | `tools/check_proto_sync.sh` | PASS |

**동일언어**
| 언어 | 명령 | 결과 |
|---|---|---|
| Dart | `dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | PASS |
| Go | `go test ./...` | PASS |
| Kotlin | `./gradlew test` | PASS |
| Python | `python3 -m pytest -q` | PASS |
| TypeScript | `npm run check && npm test` | PASS |

**언어 PASS 매트릭스**
| 서버 \ 클라이언트 | Dart.io | Dart.web | Dart.web(WSS) | Go | Kotlin | Python | TypeScript |
|---|---|---|---|---|---|---|---|
| Dart.io | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| Go | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| Kotlin | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| Python | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| TypeScript | PASS | PASS | PASS | PASS | PASS | PASS | PASS |

---

[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section? Yes, all implementation-owned sections have been fully completed with verification outputs and architecture explanations.