From 438e84bac2298ce327b3ad4e140d7c2e69c39b30 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 15 Jun 2026 15:44:44 +0900 Subject: [PATCH] add protocol-evolution-compatibility milestone and update roadmap --- README.md | 6 +- agent-roadmap/ROADMAP.md | 1 + .../protocol-evolution-compatibility.md | 86 +++++++++++++++++++ 3 files changed, 90 insertions(+), 3 deletions(-) create mode 100644 agent-roadmap/milestones/protocol-evolution-compatibility.md diff --git a/README.md b/README.md index 1393c22..60e6cff 100644 --- a/README.md +++ b/README.md @@ -20,12 +20,12 @@ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh ### 검증 스냅샷 -다른 프로젝트나 에이전트가 도입 여부를 빠르게 판단할 때는 아래 값을 현재 공개 snapshot으로 본다. 절대 throughput/latency는 local host와 runtime 상태에 의존하므로, 회귀 판단은 같은 host/runtime/profile에서 생성한 결과끼리 비교한다. +다른 프로젝트나 에이전트가 도입 여부를 빠르게 판단할 때는 아래 표 자체를 현재 공개 snapshot으로 본다. 원본 실행 기록은 `agent-test/runs/` 아래의 로컬 산출물이라 저장소에는 포함하지 않는다. 절대 throughput/latency는 local host와 runtime 상태에 의존하므로, 회귀 판단은 같은 host/runtime/profile에서 생성한 결과끼리 비교한다. | 항목 | 최신 근거 | 결과 | 해석 | |------|-----------|------|------| -| 기능 호환성 | [20260615-020431-proto-socket-full-matrix.md](agent-test/runs/20260615-020431-proto-socket-full-matrix.md), ref `3bc131c` | PASS | proto sync, 동일 언어 테스트, 20개 native cross-language 방향, Dart.web/Dart.web(WSS) client coverage가 모두 통과했다. | -| 성능/안정성 baseline 후보 | [20260614-123328-proto-socket-performance-full.md](agent-test/runs/20260614-123328-proto-socket-performance-full.md), ref `29ea189` | PASS | same-language, cross-language, TypeScript gateway 성능/안정성 측정이 모두 통과했다. baseline 비교가 없어 regression 판정은 `SKIPPED`다. | +| 기능 호환성 | 로컬 기록 `20260615-020431-proto-socket-full-matrix.md`, ref `3bc131c` | PASS | proto sync, 동일 언어 테스트, 20개 native cross-language 방향, Dart.web/Dart.web(WSS) client coverage가 모두 통과했다. | +| 성능/안정성 baseline 후보 | 로컬 기록 `20260614-123328-proto-socket-performance-full.md`, ref `29ea189` | PASS | same-language, cross-language, TypeScript gateway 성능/안정성 측정이 모두 통과했다. baseline 비교가 없어 regression 판정은 `SKIPPED`다. | | 안정성 hard gate | performance full 378 rows | PASS | timeout, nonce mismatch, response type mismatch, FIFO violation, pending leak가 모두 0이다. | 성능 full 기록의 대표 수치는 다음과 같다. diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index c4b6b5e..f6e2305 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -19,6 +19,7 @@ Proto Socket은 여러 언어와 플랫폼에서 일관되게 동작하는 얇 ### 프로토콜 기반 - [프로토콜 기준선](milestones/protocol-baseline.md) - 상태: 완료; 목표: 프로토콜 `0.1`, canonical proto, 프레이밍, 하트비트, nonce, 버전 정책을 문서화한다. +- [프로토콜 진화 호환성 보강](milestones/protocol-evolution-compatibility.md) - 상태: [계획]; 목표: full proto name 기반 message identity, legacy alias 수신 호환성, version/capability 후보, 표준 오류 응답, nonce 경계, receive ordering/backpressure 문서와 테스트를 보강한다. ### 검증과 호환성 diff --git a/agent-roadmap/milestones/protocol-evolution-compatibility.md b/agent-roadmap/milestones/protocol-evolution-compatibility.md new file mode 100644 index 0000000..9b0778c --- /dev/null +++ b/agent-roadmap/milestones/protocol-evolution-compatibility.md @@ -0,0 +1,86 @@ +# 프로토콜 진화 호환성 보강 + +## 목표 + +프로토콜 `0.1`의 단순한 wire format을 유지하면서, 장기 호환성에 취약한 `typeName`, 버전/기능 협상, 표준 오류 응답, nonce 경계, 수신 순서/역압 정책을 후속 진화 가능한 형태로 보강한다. 기존 사용 프로젝트의 영향은 낮추고, 새 프로젝트와 에이전트가 full proto name 기반으로 더 안전하게 도입할 수 있게 한다. + +## 단계 + +프로토콜 기반 + +## 상태 + +[계획] + +## 승격 조건 + +- 없음 + +## 확정된 결정 + +- package 이름은 dot-separated lowercase로 강제한다. +- wire `typeName`은 canonical proto package를 포함한 `.` full proto name으로 둔다. +- descriptor/native metadata에서 full name을 얻을 수 있는 언어는 해당 값을 우선 사용한다. +- TypeScript는 현재 수동 codec 구조를 유지하고, `MessageType.typeName` static metadata를 full proto name으로 정렬한다. +- 기존 simple name wire value는 송신 기본값으로 유지하지 않고, legacy receive alias로만 보존한다. + +## 구현 잠금 + +- 상태: 잠금 +- 결정 필요: + - [ ] Canonical proto package의 정확한 문자열을 확정한다. 현재 canonical `proto/message_common.proto`에는 `package` 선언이 없으므로, 예: `proto_socket` 또는 `tokilabs.proto_socket` 중 어느 값을 wire identity 기준으로 삼을지 결정한다. + +## 범위 + +- `typeName` canonical 값을 proto full name으로 정렬한다. +- Go, Kotlin, Dart, Python, C#, Swift는 가능한 경우 protobuf descriptor/native metadata에서 full name을 얻는다. +- TypeScript는 현재 수동 codec의 `MessageType.typeName` static metadata를 full name으로 정렬한다. +- 기존 simple name 기반 소비자를 위해 수신 parser map에는 full name과 legacy simple name alias를 함께 등록한다. +- `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 수신 호환성을 유지한다. + +- [ ] [pkg-rule] Proto package naming rule을 문서화한다. package는 dot-separated lowercase만 허용하고, 언어별 namespace/package option은 wire identity와 분리한다. +- [ ] [fullname-type] 각 언어의 `typeNameOf()` 또는 message metadata를 full proto name 기준으로 정렬한다. descriptor/native metadata를 우선 사용하고, TypeScript는 static metadata를 사용한다. +- [ ] [legacy-alias] 수신 parser map에 full name과 simple name alias를 함께 등록하되, simple alias 충돌 시 초기화 실패로 처리한다. +- [ ] [fullname-tests] full name 송수신, simple name legacy 수신, alias 충돌 감지에 대한 동일 언어 및 크로스 언어 테스트를 추가한다. 검증: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` + +### Epic: [evolution] 진화 안전장치 + +현재 `PacketBase`의 단순성을 유지하면서, future protocol capability를 안전하게 추가할 수 있는 경계를 만든다. + +- [ ] [hello-cap] `ProtoSocketHello` 또는 동등한 비차단 capability message 후보를 설계한다. 구버전 peer가 모르면 무시할 수 있는 경로로 둔다. +- [ ] [std-error] `ProtoSocketError` 또는 동등한 표준 오류 응답 convention을 설계한다. request handler 실패가 timeout만으로 보이지 않게 하되, 구버전 peer와의 mismatch 처리를 문서화한다. +- [ ] [nonce-boundary] nonce wrap 시 pending request nonce와 충돌하지 않도록 경계 정책과 테스트를 보강한다. +- [ ] [ordering-doc] response completion이 pending correlation 경로로 queue를 우회할 수 있음을 `Receive Ordering and Backpressure` 계약에 명확히 기록한다. listener/request handler dispatch FIFO 보장과 구분한다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 없음 +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 인증, 세션, 채팅, 게임 규칙, 룸, 에이전트 워크플로 의미를 protocol core에 넣지 않는다. +- 기존 `PacketBase` 필드를 제거하거나 번호를 바꾸지 않는다. +- full name 송신 기본값 전환 전에 legacy simple name 수신 호환성을 제거하지 않는다. +- TypeScript에 full protobuf reflection runtime을 강제 도입하지 않는다. +- 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/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 +- 확인 필요: Canonical proto package 문자열