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 릴리즈는 별도 수요가 생길 때 후속 작업으로 분리한다.

2026-06-18 잠정 완료 판단

현재 사용 가능 구현은 Dart, Go, Kotlin, Python, TypeScript 5개 언어다. 2026-06-18 기준 전체 기능 매트릭스와 성능/안정성 quick 재검증이 통과했고, 기존 full baseline 근거도 유지된다. 따라서 현재 범위는 잠정 완료로 두고, 이후 작업은 유지보수 모드에서 bug fix, 문서 정정, 테스트 보강, 호환성을 유지하는 작은 구현 수정만 수행한다.

C# Unity/.NET 포트와 Swift Apple 플랫폼 포트는 실제 소비 수요 또는 명시적 재개 요청이 있을 때 별도 언어 확장 작업으로 다시 연다. 재개 시에는 각 언어의 target runtime, SDD 필요 여부, 동일 언어 테스트, 크로스 언어 테스트, 전체 검증 매트릭스 통과 조건을 다시 확인한다.

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 포트 - 상태: [보류]; 목표: 실제 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로 정리했다.