proto-socket/agent-roadmap/ROADMAP.md

로드맵

전체 목표

Proto Socket은 여러 언어와 플랫폼에서 일관되게 동작하는 얇고 안정적인 protocol-first 소켓 통신 라이브러리를 제공하는 것을 목표로 한다. 공유 계약은 Protocol Buffers 직렬화, TCP/WebSocket 바이너리 프레이밍, 타입 기반 라우팅, 요청-응답 상관관계, 내장 하트비트다.

코어는 작게 유지한다. 인증, 세션, 채팅, 게임 규칙, 룸 로직, 에이전트 워크플로 같은 애플리케이션 의미는 이 프로토콜 계층 위에서 다룬다.

Phase 흐름

• 프로토콜 기반: 프로토콜 버전 0.1, 와이어 포맷, 버전 정책, canonical proto 원본, 레퍼런스 구현 패턴을 정의한다.
• 검증과 호환성: 동일 언어 테스트, 크로스 언어 테스트, proto 동기화 검사, 지속 검증으로 사용 가능한 구현체들을 정렬한다.
• 안정화와 유지: 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단, 문서 정합성, 유지 기준을 정리한다.
• 남은 native platform 포팅: 사용자 요청에 따라 C# Unity/.NET 포트를 다음 진행 대상으로 두고, Swift 구현 추가는 실제 수요가 생길 때까지 보류한다.
• 릴리즈 준비: 현재 릴리즈 표준은 Git ref/tag 기반 소비로 둔다. 외부 package registry 릴리즈는 별도 수요가 생길 때 후속 작업으로 분리한다.

Milestone 목록

프로토콜 기반

• 프로토콜 기준선 - 상태: 완료; 목표: 프로토콜 0.1, canonical proto, 프레이밍, 하트비트, nonce, 버전 정책을 문서화한다.
• 프로토콜 진화 호환성 보강 - 상태: [계획]; 목표: full proto name 기반 message identity, legacy alias 수신 호환성, version/capability 후보, 표준 오류 응답, nonce 경계, receive ordering/backpressure 문서와 테스트를 보강한다.

검증과 호환성

• 사용 가능 언어 parity - 상태: 완료; 목표: Dart, Go, Kotlin, Python, TypeScript가 사용 가능 상태이며 동일 언어 및 크로스 언어 테스트 진입점을 갖춘다.
• 지속 검증 - 상태: 완료; 목표: 지원 언어, 크로스 언어 테스트, proto 동기화 검사를 저장소 로컬 검증 진입점으로 자동화한다.

안정화와 유지

• 안정화 기준선 - 상태: 완료; 목표: 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단과 유지 기준을 정리한다.
• 수신 큐와 처리 순서 보장 - 상태: 완료; 목표: 현재 5개 언어 구현에 per-connection 수신 큐와 언어별 worker gateway 후보를 도입해 수신 처리 순서, 자동 응답 출력 순서, thread-safe한 공유 상태 접근, 대량 처리 성능 개선 가능성을 보장한다.
• 고성능 병렬 운용 기준선과 최적화 - 상태: 완료; 목표: 현재 5개 언어 구현의 병렬 운용 성능을 언어별/transport별로 측정하고 gateway, queue, worker, serialization 병목을 최적화한다.
• 언어별 성능 병목 개선 - 상태: 완료; 목표: 측정 결과에서 확인된 Dart TCP fixed latency/large payload 및 isolate receive path hardening, TypeScript WS large payload, Kotlin WS latency/slow-mix 검증 모델, TypeScript gateway worker_threads overhead 병목을 안정성 hard gate와 단일 mandatory receive path 원칙을 유지하면서 개선하고, Go/Python reference 기준점을 보강한다.
• 워크스페이스 포트/환경 표준화 - 상태: 완료; 목표: proto-socket이 runtime service port를 소유하지 않는다는 점과 cross-language test runner의 fixed local port 대역을 workspace 표준 예외로 문서화한다.
• 변경 기반 테스트 라우팅 정형화 - 상태: 완료; 목표: 마지막 통과 테스트 지점과 현재 변경 내용을 분석해 기능, 속도, 안정성 테스트 중 필요한 검증 범위를 자동 선택하고, 언어별 anchor x5와 야간 장시간 측정을 분리한다.
• 야간 대용량 패킷 성능 기준선 - 상태: 완료; 목표: 64KB/1MB payload 성능 baseline과 회귀 판단을 실행 host local time 20:00 이후 야간 window에서 별도 수집해 주간 작업 부하 편차와 분리한다.
• 대용량 WS/병렬 전송 후속 최적화 - 상태: 완료; 목표: TypeScript WS 1MB, TypeScript TCP 1024 tail, Kotlin TCP parallel, Dart large-packet guard 작업 완료 이후 남은 WS fixed latency 후보까지 분리 분석했다.

남은 native platform 포팅

• C# Unity/.NET 포트 - 상태: [진행중]; 목표: 프로토콜 0.1 계약과 native-first 런타임 방향을 유지하면서 Unity 및 .NET 소비자를 지원하는 C# 구현을 추가한다.
• Swift Apple 플랫폼 포트 - 상태: [보류]; 목표: 실제 iOS/macOS 소비 수요가 생길 때까지 Swift 구현 추가를 보류한다.

릴리즈 준비

• 릴리즈 준비 - 상태: 완료; 목표: Git ref/tag 기반 릴리즈 기준과 검증 gate를 명확히 한다.

로딩 정책

• 일반 작업에서는 agent-roadmap/ROADMAP.md를 매번 읽지 않는다.
• 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 agent-roadmap/current.md를 먼저 읽는다.
• current.md는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다.
• current.md에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
• 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다.
• 활성 Milestone 밖의 작업이면 이 문서의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
• 이 문서는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다.
• 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다.
• 이 로드맵은 기존 README.md의 구현 상태, 로드맵 방향, 지속 검증 메모와 PORTING_GUIDE.md의 C#/Swift 포팅 가이드를 Milestone 문서로 분리한 것이다.
• 이전 로드맵의 순번 붙은 단계명, Milestone 이름, Milestone 파일명은 순번 없는 이름과 slug로 정리했다.