# 로드맵

## 전체 목표

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-19 완료 판단

현재 사용 가능 구현은 Dart, Go, Kotlin, Python, TypeScript 5개 언어다. 2026-06-18 실행 기록 기준 전체 기능 매트릭스가 통과했고, same-language/cross-language/TypeScript gateway full 안정성 hard gate도 통과했다. 기존 full baseline 근거도 유지된다. 최신 full 성능 회귀 비교에는 local host/runtime 상태에 민감한 `WARN` row가 있으나, timeout, nonce mismatch, response type mismatch, FIFO violation, pending leak 같은 correctness/stability 위반은 0이다. 따라서 현재 범위는 완료로 두고, 이후 작업은 유지보수 모드에서 bug fix, 문서 정정, 테스트 보강, 호환성을 유지하는 작은 구현 수정만 수행한다.

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

## Milestone 목록

### 프로토콜 기반

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

### 검증과 호환성

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

### 안정화와 유지

- [안정화 기준선](milestones/stability-baseline.md) - 상태: 완료; 목표: 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단과 유지 기준을 정리한다.
- [수신 큐와 처리 순서 보장](archive/phase/stability-maintenance/milestones/inbound-queue-ordering.md) - 상태: 완료; 목표: 현재 5개 언어 구현에 per-connection 수신 큐와 언어별 worker gateway 후보를 도입해 수신 처리 순서, 자동 응답 출력 순서, thread-safe한 공유 상태 접근, 대량 처리 성능 개선 가능성을 보장한다.
- [고성능 병렬 운용 기준선과 최적화](archive/phase/stability-maintenance/milestones/high-performance-parallel-operations.md) - 상태: 완료; 목표: 현재 5개 언어 구현의 병렬 운용 성능을 언어별/transport별로 측정하고 gateway, queue, worker, serialization 병목을 최적화한다.
- [언어별 성능 병목 개선](archive/phase/stability-maintenance/milestones/performance-hotspot-optimization.md) - 상태: 완료; 목표: 측정 결과에서 확인된 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 기준점을 보강한다.
- [워크스페이스 포트/환경 표준화](archive/phase/stability-maintenance/milestones/workspace-port-env-standardization.md) - 상태: 완료; 목표: proto-socket이 runtime service port를 소유하지 않는다는 점과 cross-language test runner의 fixed local port 대역을 workspace 표준 예외로 문서화한다.
- [변경 기반 테스트 라우팅 정형화](archive/phase/stability-maintenance/milestones/change-aware-test-routing.md) - 상태: 완료; 목표: 마지막 통과 테스트 지점과 현재 변경 내용을 분석해 기능, 속도, 안정성 테스트 중 필요한 검증 범위를 자동 선택하고, 언어별 anchor x5와 야간 장시간 측정을 분리한다.
- [야간 대용량 패킷 성능 기준선](archive/phase/stability-maintenance/milestones/nightly-large-payload-baseline.md) - 상태: 완료; 목표: 64KB/1MB payload 성능 baseline과 회귀 판단을 실행 host local time 20:00 이후 야간 window에서 별도 수집해 주간 작업 부하 편차와 분리한다.
- [대용량 WS/병렬 전송 후속 최적화](archive/phase/stability-maintenance/milestones/large-payload-followup-optimization.md) - 상태: 완료; 목표: TypeScript WS 1MB, TypeScript TCP 1024 tail, Kotlin TCP parallel, Dart large-packet guard 작업 완료 이후 남은 WS fixed latency 후보까지 분리 분석했다.

### 남은 native platform 포팅

- [C# Unity/.NET 포트](milestones/csharp-port.md) - 상태: [보류]; 목표: 실제 Unity/.NET 소비 수요 또는 명시적 재개 요청이 생길 때까지 C# 구현 추가를 보류한다.
- [Swift Apple 플랫폼 포트](milestones/swift-port.md) - 상태: [보류]; 목표: 실제 iOS/macOS 소비 수요가 생길 때까지 Swift 구현 추가를 보류한다.

### 릴리즈 준비

- [릴리즈 준비](milestones/release-readiness.md) - 상태: 완료; 목표: 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로 정리했다.
