# 프로토콜 진화 호환성 보강

## 목표

프로토콜 `0.1`의 단순한 wire format을 유지하면서, 장기 호환성에 취약한 `typeName`, 버전/기능 협상, 표준 오류 응답, nonce 경계, 수신 순서/역압 정책을 후속 진화 가능한 형태로 보강한다. 기존 사용 프로젝트의 영향은 낮추고, 새 프로젝트와 에이전트가 full proto name 기반으로 더 안전하게 도입할 수 있게 한다.

## 단계

프로토콜 기반

## 상태

[검토중]

## 승격 조건

- 없음

## 확정된 결정

- package 이름은 lowercase snake_case segment를 dot으로 연결한 형태로 강제한다.
- Canonical proto package 문자열은 `proto_socket`으로 둔다.
- wire `typeName`은 canonical proto package를 포함한 `<package>.<MessageName>` full proto name으로 둔다.
- common proto message의 canonical full name은 `proto_socket.PacketBase`, `proto_socket.HeartBeat`, `proto_socket.TestData` 형태다. 실제 `PacketBase.typeName` 라우팅 예시는 `proto_socket.HeartBeat`, `proto_socket.TestData`처럼 inner message full name을 사용한다.
- descriptor/native metadata에서 full name을 얻을 수 있는 언어는 해당 값을 우선 사용한다.
- TypeScript는 현재 수동 codec 구조를 유지하고, `MessageType.typeName` static metadata를 full proto name으로 정렬한다.
- 기존 simple name wire value는 송신 기본값으로 유지하지 않고, legacy receive alias로만 보존한다.
- 이 마일스톤의 구현 완료 범위는 현재 사용 가능 구현체인 Dart, Go, Kotlin, Python, TypeScript로 둔다. C#과 Swift는 이후 포팅 시 동일 규칙을 따라야 하는 승계 대상이다.

## 구현 잠금

- 상태: 해제
- SDD: 불필요 - 기존 `PacketBase` wire 구조를 유지하고 문서/테스트 보강 evidence로 완료 판단이 가능한 범위다.
- 결정 필요: 없음

## 범위

- `typeName` canonical 값을 proto full name으로 정렬한다.
- Canonical `proto/message_common.proto`에 `package proto_socket;`을 추가하고, 언어별 proto copy와 generated binding을 동기화한다.
- Go, Kotlin, Dart, Python은 가능한 경우 protobuf descriptor/native metadata에서 full name을 얻는다.
- TypeScript는 현재 수동 codec의 `MessageType.typeName` static metadata를 full name으로 정렬한다.
- 기존 simple name 기반 소비자를 위해 수신 type registry에는 full name과 legacy simple name alias를 함께 등록한다.
- alias는 parser lookup뿐 아니라 listener/request handler routing, response type matching, pending request expected type 비교까지 동일하게 적용한다.
- `PacketBase` wire field 구조는 유지하고, 필요한 확장은 새 optional message 또는 capability convention으로 설계한다.
- 표준 오류 응답, nonce overflow 경계, receive ordering/backpressure 문서와 테스트를 보강한다.

## 기능

### Epic: [identity] TypeName identity 정렬

wire message identity를 full proto name으로 정렬하고, legacy simple name 수신 호환성을 유지한다.

- [x] [pkg-rule] Proto package naming rule을 `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`에 문서화한다. package는 lowercase snake_case segment를 dot으로 연결한 형태만 허용하고, 언어별 namespace/package option은 wire identity와 분리한다. common proto의 package는 `proto_socket`으로 둔다.
- [x] [proto-package-sync] Canonical `proto/message_common.proto`에 `package proto_socket;`을 추가하고 언어별 proto copy와 generated binding을 동기화한다. 검증: `tools/check_proto_sync.sh`
- [x] [fullname-type] 각 사용 가능 언어의 `typeNameOf()` 또는 message metadata를 full proto name 기준으로 정렬한다. descriptor/native metadata를 우선 사용하되, Python은 `DESCRIPTOR.full_name`, TypeScript는 static metadata를 사용한다. common proto의 기대값은 `proto_socket.<MessageName>`이다.
- [x] [legacy-alias] 수신 type registry에 full name과 simple name alias를 함께 등록하되, parser lookup, listener/request handler routing, response type matching, pending expected type 비교가 같은 alias 규칙을 사용하게 한다. simple alias 충돌 시 초기화 실패로 처리한다.
- [x] [fullname-tests] full name 송수신, simple name legacy 수신, request/response alias 호환, alias 충돌 감지에 대한 동일 언어 및 크로스 언어 테스트를 추가한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all`

### Epic: [evolution] 진화 안전장치

현재 `PacketBase`의 단순성을 유지하면서, future protocol capability를 안전하게 추가할 수 있는 경계를 만든다.

- [x] [hello-cap] `ProtoSocketHello` 또는 동등한 비차단 version/capability message 후보를 `PROTOCOL.md`와 `VERSIONING.md`에 문서화한다. 후보 payload에는 `protocolVersion`, `capabilities`, 선택적 implementation metadata를 포함한다. 구버전 peer가 모르면 무시할 수 있는 경로로 두고, 이 마일스톤에서 필수 handshake로 승격하지 않는다.
- [x] [std-error] `ProtoSocketError` 또는 동등한 표준 오류 응답 convention을 문서화한다. 후보 payload에는 stable error code, message, 선택적 detail/debug field를 포함한다. request handler 실패가 timeout만으로 보이지 않게 하되, 구버전 peer와의 mismatch 처리를 명시하고, 이 마일스톤에서 모든 handler가 오류 응답을 강제 송신하도록 바꾸지는 않는다.
- [x] [nonce-boundary] nonce wrap 시 pending request nonce와 충돌하지 않도록 active pending nonce skip 정책과 boundary 테스트를 보강한다.
- [x] [ordering-doc] response completion이 pending correlation 경로로 queue를 우회할 수 있음을 `Receive Ordering and Backpressure` 계약에 명확히 기록한다. listener/request handler dispatch FIFO 보장과 구분한다.

## 완료 리뷰

- 상태: 요청됨
- 요청일: 2026-06-17
- 완료 근거:
  - `01_proto_fullname_foundation`, `02+01_legacy_alias`, `03+01,02_fullname_tests`가 PASS 완료되어 TypeName identity 정렬 범위를 충족했다.
  - `04+03_nonce_contract`, `05+04_nonce_dart_go`, `06+04,05_nonce_kotlin_python_ts`가 PASS 완료되어 nonce 계약, Dart/Go 구현, Kotlin/Python/TypeScript 구현과 boundary regression test를 충족했다.
  - `agent-task/archive/2026/06/m-protocol-evolution-compatibility/06+04,05_nonce_kotlin_python_ts/complete.log`의 `Roadmap Completion`이 `nonce-boundary: PASS`와 전체 테스트 매트릭스 PASS를 기록했다.
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 모든 기능 Task가 evidence 기준 완료되어 사용자 최종 확인과 archive 승인만 남았다.

## 범위 제외

- 인증, 세션, 채팅, 게임 규칙, 룸, 에이전트 워크플로 의미를 protocol core에 넣지 않는다.
- 기존 `PacketBase` 필드를 제거하거나 번호를 바꾸지 않는다.
- full name 송신 기본값 전환 전에 legacy simple name 수신 호환성을 제거하지 않는다.
- TypeScript에 full protobuf reflection runtime을 강제 도입하지 않는다.
- C#과 Swift 포트를 이 Milestone의 완료 조건으로 삼지 않는다.
- package registry 릴리즈 정책을 이 Milestone에서 확정하지 않는다.

## 작업 컨텍스트

- 관련 경로: `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`, `proto/message_common.proto`, `dart/lib/src/communicator.dart`, `go/communicator.go`, `kotlin/src/main/kotlin/com/tokilabs/proto_socket/Communicator.kt`, `python/proto_socket/communicator.py`, `typescript/src/communicator.ts`, `typescript/src/packets/message_common_pb.ts`, `tools/`
- 표준선(선택): native descriptor/full name 추출을 우선하고, descriptor가 없는 런타임만 static metadata fallback을 쓴다. 기존 simple name wire value는 legacy receive alias로 유지한다.
- 선행 작업: 프로토콜 기준선
- 후속 작업: 필요 시 protocol `0.2` 또는 `1.0` compatibility release planning
- 확인 필요: 없음
- 작업 현황 동기화(2026-06-17): `01_proto_fullname_foundation`, `02+01_legacy_alias`, `03+01,02_fullname_tests`, `04+03_nonce_contract`, `05+04_nonce_dart_go`, `06+04,05_nonce_kotlin_python_ts`가 모두 PASS 완료되어 기능 Task 전체를 반영했다. 근거는 각 split의 `agent-task/archive/2026/06/m-protocol-evolution-compatibility/<split>/complete.log`다.
- `nonce-boundary`는 `06+04,05_nonce_kotlin_python_ts/complete.log`의 `Roadmap Completion`에서 PASS로 확인했으며, 검증은 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` PASS다.
- 모든 기능 Task가 완료되어 상태를 `[검토중]`으로 전환했다. 남은 항목은 사용자 완료 결과 확인과 archive 이동 승인이다.