<!-- task=m-protocol-evolution-compatibility/02+01_legacy_alias plan=1 tag=REVIEW_ALIAS -->

# Plan - REVIEW_ALIAS

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

이 plan은 `ALIAS` 1차 리뷰의 Required 이슈만 해결한다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하지 않는다. 사용자만 결정할 수 있는 blocker가 있으면 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 근거와 재개 조건을 기록하고 중단한다.

## 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

## 리뷰 근거

보관된 리뷰: `code_review_cloud_G07_0.log`

1차 리뷰 결과는 `FAIL`이다. Python process gateway가 simple alias wire type을 canonical parser class lookup에 반영하지 못해 drop되는 결함이 재현되었고, 계획이 요구한 request handler alias unit test가 5개 언어에서 빠져 있다.

재현 명령:

```bash
cd python
python3 - <<'PY'
import asyncio
from proto_socket.communicator import Communicator, type_name_of
from proto_socket.packets.message_common_pb2 import PacketBase, TestData

class FakeTransport:
    def __init__(self):
        self.packets = []
    async def write_packet(self, base: PacketBase):
        self.packets.append(base)
    async def close(self):
        pass

def parser_map():
    return {type_name_of(TestData): TestData.FromString}

async def main():
    c = Communicator()
    c.initialize(FakeTransport(), parser_map(), gateway_type="process", payload_size_threshold=1)
    loop = asyncio.get_running_loop()
    received = loop.create_future()
    c.add_listener(type_name_of(TestData), received.set_result)
    msg = TestData(index=42, message="legacy alias via process gateway")
    c.on_received_data("TestData", msg.SerializeToString(), 1, 0)
    try:
        result = await asyncio.wait_for(received, 1.0)
        print(f"PASS received index={result.index}")
    except Exception as exc:
        print(f"FAIL {type(exc).__name__}: {exc}")
    await c.close()

asyncio.run(main())
PY
```

관찰 출력:

```text
FAIL TimeoutError:
```

## 구현 체크리스트

- [ ] Python process gateway에서 parser class lookup 전에 wire type을 canonicalize하고 legacy simple-name frame이 gateway path에서도 dispatch되게 한다.
- [ ] Python process gateway legacy simple-name regression test를 추가한다.
- [ ] Dart/Go/Kotlin/Python/TypeScript focused communicator test에 full-name request handler 등록 + simple-name inbound request 케이스를 추가한다.
- [ ] focused unit tests와 전체 matrix를 실행하고 실제 stdout/stderr를 기록한다.
- [ ] CODE_REVIEW-cloud-G07.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다.

### [REVIEW_ALIAS-1] Python Process Gateway Alias Lookup

문제: `python/proto_socket/communicator.py:472`에서 process gateway decode용 parser class를 raw `type_name`으로 조회한다. `_parser_cls_map`은 canonical key로 채워지므로 incoming wire type이 `"TestData"`이면 parser class를 찾지 못한다.

해결 방법:

- process gateway 분기에서 `canonical = self._canonicalize(type_name)`로 정규화한 뒤 `_parser_cls_map.get(canonical)`을 사용한다.
- 기존 inline/asyncio gateway 경로의 `_parse()` canonical lookup 동작은 유지한다.
- `python/test/test_communicator.py`에 `gateway_type="process"`, 낮은 `payload_size_threshold`, incoming `"TestData"` frame이 listener 또는 request handler까지 도달하는 regression test를 추가한다.

중간 검증:

```bash
cd python && python3 -m pytest -q test/test_communicator.py
```

### [REVIEW_ALIAS-2] Request Handler Alias Regression Tests

문제: `plan_cloud_G07_0.log`의 ALIAS-2는 request handler가 full name으로 등록되어도 incoming simple name을 처리하는 unit test를 요구했다. 현재 alias tests는 listener routing과 pending response matching만 확인한다.

해결 방법:

- `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`에 focused request handler alias 케이스를 추가한다.
- 각 테스트는 full/canonical type helper로 request handler를 등록한 뒤, incoming `"TestData"` request frame을 넣고 handler 호출 및 response packet의 `responseNonce`/payload를 확인한다.
- 테스트 추가 중 실제 구현 결함이 드러나면 해당 언어 구현도 같은 canonical helper 규칙으로 수정한다.

중간 검증:

```bash
dart test test/communicator_test.dart
go test ./...
cd kotlin && ./gradlew test
cd python && python3 -m pytest -q
cd typescript && npm run check && npm test
```

## 수정 파일 예상

| 파일 | 항목 |
|---|---|
| `python/proto_socket/communicator.py` | REVIEW_ALIAS-1 |
| `python/test/test_communicator.py` | REVIEW_ALIAS-1, REVIEW_ALIAS-2 |
| `dart/test/communicator_test.dart` | REVIEW_ALIAS-2 |
| `go/test/communicator_test.go` | REVIEW_ALIAS-2 |
| `kotlin/src/test/kotlin/com/tokilabs/proto_socket/CommunicatorTest.kt` | REVIEW_ALIAS-2 |
| `typescript/test/communicator.test.ts` | REVIEW_ALIAS-2 |

## 최종 검증

```bash
dart test test/communicator_test.dart
go test ./...
cd kotlin && ./gradlew test
cd python && python3 -m pytest -q
cd typescript && npm run check && npm test
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
```

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 채운다.
