diff --git a/agent-roadmap/milestones/protocol-evolution-compatibility.md b/agent-roadmap/milestones/protocol-evolution-compatibility.md index c1a1dde..011579b 100644 --- a/agent-roadmap/milestones/protocol-evolution-compatibility.md +++ b/agent-roadmap/milestones/protocol-evolution-compatibility.md @@ -21,7 +21,7 @@ - package 이름은 lowercase snake_case segment를 dot으로 연결한 형태로 강제한다. - Canonical proto package 문자열은 `proto_socket`으로 둔다. - wire `typeName`은 canonical proto package를 포함한 `.` full proto name으로 둔다. -- built-in/common message의 canonical wire identity는 `proto_socket.PacketBase`, `proto_socket.HeartBeat`, `proto_socket.TestData` 형태다. +- 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로만 보존한다. @@ -59,8 +59,8 @@ wire message identity를 full proto name으로 정렬하고, legacy simple name 현재 `PacketBase`의 단순성을 유지하면서, future protocol capability를 안전하게 추가할 수 있는 경계를 만든다. -- [ ] [hello-cap] `ProtoSocketHello` 또는 동등한 비차단 capability message 후보를 문서화한다. 구버전 peer가 모르면 무시할 수 있는 경로로 두고, 이 마일스톤에서 필수 handshake로 승격하지 않는다. -- [ ] [std-error] `ProtoSocketError` 또는 동등한 표준 오류 응답 convention을 문서화한다. request handler 실패가 timeout만으로 보이지 않게 하되, 구버전 peer와의 mismatch 처리를 명시하고, 이 마일스톤에서 모든 handler가 오류 응답을 강제 송신하도록 바꾸지는 않는다. +- [ ] [hello-cap] `ProtoSocketHello` 또는 동등한 비차단 version/capability message 후보를 `PROTOCOL.md`와 `VERSIONING.md`에 문서화한다. 후보 payload에는 `protocolVersion`, `capabilities`, 선택적 implementation metadata를 포함한다. 구버전 peer가 모르면 무시할 수 있는 경로로 두고, 이 마일스톤에서 필수 handshake로 승격하지 않는다. +- [ ] [std-error] `ProtoSocketError` 또는 동등한 표준 오류 응답 convention을 문서화한다. 후보 payload에는 stable error code, message, 선택적 detail/debug field를 포함한다. request handler 실패가 timeout만으로 보이지 않게 하되, 구버전 peer와의 mismatch 처리를 명시하고, 이 마일스톤에서 모든 handler가 오류 응답을 강제 송신하도록 바꾸지는 않는다. - [ ] [nonce-boundary] nonce wrap 시 pending request nonce와 충돌하지 않도록 active pending nonce skip 정책과 boundary 테스트를 보강한다. - [ ] [ordering-doc] response completion이 pending correlation 경로로 queue를 우회할 수 있음을 `Receive Ordering and Backpressure` 계약에 명확히 기록한다. listener/request handler dispatch FIFO 보장과 구분한다.