diff --git a/README.md b/README.md index f2bdf78..142d199 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Protocol compatibility is tracked separately from language package versions. See New language implementations should start from [PORTING_GUIDE.md](PORTING_GUIDE.md) and the templates in [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/). Mark an implementation available only after its same-language tests and cross-language tests pass. -Roadmap direction: every implementation should stay as close to native platform behavior as possible outside the protobuf layer. Prefer built-in TCP/TLS/WebSocket, concurrency, timer, and binary APIs over external packages. A focused library that directly matches a protocol need is acceptable when native support is missing or impractical, but broad frameworks or runtime layers must not be introduced just to cover a narrow feature such as WebSocket transport. Runtime dependencies beyond protobuf must be explicitly justified, protocol-relevant, and kept minimal. +Detailed planning now lives in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md). Keep implementation status here as the public snapshot; roadmap direction, CI automation, and future C#/Swift work are tracked in the roadmap. --- @@ -172,7 +172,7 @@ If you want a copyable scaffold for using this module from another repository, s ## Running Tests -Local commands are documented here for development and troubleshooting. Continuous verification is expected to run in an external tool, with Jenkins planned to execute the full supported-language and cross-language test suite. +Local commands are documented here for development and troubleshooting. Continuous verification automation is tracked in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md). ```bash cd dart diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md new file mode 100644 index 0000000..f789e1c --- /dev/null +++ b/agent-ops/roadmap/ROADMAP.md @@ -0,0 +1,54 @@ +# Proto Socket Roadmap + +## Overall Goal + +Proto Socket aims to provide a thin, stable, protocol-first socket communication library that behaves consistently across languages and platforms. The shared contract is Protocol Buffers serialization, TCP/WebSocket binary framing, type-based routing, request-response correlation, and built-in heartbeat. + +The core should stay small: application semantics such as auth, sessions, chat, game rules, room logic, and agent workflow belong above this protocol layer. + +## Current Position + +- Active Phase: Phase 2 - Verification and compatibility +- Active Milestone: M03 Continuous Verification +- Active Milestone File: agent-ops/roadmap/milestones/M03-continuous-verification.md + +## Migration Notes + +This roadmap migrates the roadmap-like planning that previously lived in top-level documentation: + +- `README.md` implementation status table: summarized in the Milestone Index as available and planned language work. +- `README.md` roadmap direction paragraph: migrated into the dependency and native-platform direction in M02, M04, and M05. +- `README.md` Jenkins planning note: migrated into M03 Continuous Verification. +- `PORTING_GUIDE.md` C# and Swift guidance: linked to planned port milestones M04 and M05. + +## Phase Overview + +| Phase | Status | Goal | +|-------|--------|------| +| Phase 1 - Protocol foundation | Done | Define protocol version `0.1`, wire format, versioning policy, canonical proto source, and reference implementation patterns. | +| Phase 2 - Verification and compatibility | Active | Keep available implementations aligned through same-language tests, cross-language tests, proto sync checks, and continuous verification. | +| Phase 3 - Remaining native platform ports | Planned | Add C# and Swift implementations while preserving the protocol contract and native-first runtime direction. | +| Phase 4 - Release readiness | Planned | Prepare language packages, release documentation, and compatibility statements for external consumption. | + +## Milestone Index + +| Milestone | Phase | Status | File | Summary | +|-----------|-------|--------|------|---------| +| M01 Protocol Baseline | Phase 1 | Done | agent-ops/roadmap/milestones/M01-protocol-baseline.md | Protocol `0.1`, canonical proto, framing, heartbeat, nonce, and versioning policy are documented. | +| M02 Available Language Parity | Phase 2 | Done | agent-ops/roadmap/milestones/M02-available-language-parity.md | Dart, Go, Kotlin, Python, and TypeScript are listed as available and have same-language and cross-language test entry points. | +| M03 Continuous Verification | Phase 2 | Active | agent-ops/roadmap/milestones/M03-continuous-verification.md | Automate the supported-language and cross-language test matrix, with Jenkins currently named as the expected external runner. | +| M04 C# Unity/.NET Port | Phase 3 | Planned | agent-ops/roadmap/milestones/M04-csharp-port.md | Add a C# implementation for Unity and .NET using native runtime patterns where possible. | +| M05 Swift Apple Platform Port | Phase 3 | Planned | agent-ops/roadmap/milestones/M05-swift-port.md | Add a Swift implementation for iOS and macOS using Swift concurrency and Apple-native transport APIs where possible. | +| M06 Release Readiness | Phase 4 | Planned | agent-ops/roadmap/milestones/M06-release-readiness.md | Prepare package publication, compatibility notes, and release checks per language. | + +## Loading Policy + +- General implementation work should read `agent-ops/roadmap/current.md` and the Active Milestone file only. +- Read this full `ROADMAP.md` only for roadmap creation, roadmap updates, Phase transitions, Milestone additions, or Milestone restructuring. +- If a requested task conflicts with the Active Milestone Goal or Non-Goals, pause and confirm direction before implementing. + +## Open Questions + +- Active Milestone is inferred from the existing README note that Jenkins is planned for full supported-language and cross-language verification. +- The order between C# and Swift may change if product priorities shift. +- Release target registries and package publishing order are not yet confirmed. diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md new file mode 100644 index 0000000..8712d6a --- /dev/null +++ b/agent-ops/roadmap/current.md @@ -0,0 +1,5 @@ +# Current Roadmap Context + +- Active Phase: Phase 2 - Verification and compatibility +- Active Milestone: M03 Continuous Verification +- Active Milestone File: agent-ops/roadmap/milestones/M03-continuous-verification.md diff --git a/agent-ops/roadmap/milestones/M01-protocol-baseline.md b/agent-ops/roadmap/milestones/M01-protocol-baseline.md new file mode 100644 index 0000000..0f29702 --- /dev/null +++ b/agent-ops/roadmap/milestones/M01-protocol-baseline.md @@ -0,0 +1,45 @@ +# M01 Protocol Baseline + +## Goal + +Establish the shared Proto Socket protocol contract so every implementation can interoperate without embedding application-specific behavior into the core. + +## Phase + +Phase 1 - Protocol foundation + +## Status + +Done + +## Scope + +- Document TCP 4-byte big-endian length-prefixed framing. +- Document WebSocket/WSS binary-frame transport. +- Define `PacketBase`, `typeName`, `nonce`, `responseNonce`, and `HeartBeat` behavior. +- Define protocol/package version separation. +- Treat `proto/message_common.proto` as the canonical proto source. + +## Required Features + +- [x] Protocol version `0.1` documented in `PROTOCOL.md` and `VERSIONING.md`. +- [x] Canonical proto source documented as `proto/message_common.proto`. +- [x] TCP and WebSocket wire formats documented. +- [x] Heartbeat lifecycle and request-response correlation documented. +- [x] Breaking and non-breaking protocol change policy documented. + +## Success Criteria + +- Implementers can build a conforming language port from `PROTOCOL.md`, `VERSIONING.md`, and `PORTING_GUIDE.md`. +- Protocol-level changes have an explicit compatibility review path. +- Generated language proto copies can be checked against the canonical schema. + +## Non-Goals + +- Define application-level auth, session, chat, game, room, or agent workflow semantics. +- Publish language packages. +- Add new transport families beyond TCP/TLS and WebSocket/WSS. + +## Context for Work + +Use `PROTOCOL.md` as the wire-format source of truth and `VERSIONING.md` for compatibility policy. If proto schemas change, regenerate bindings and run `tools/check_proto_sync.sh`. diff --git a/agent-ops/roadmap/milestones/M02-available-language-parity.md b/agent-ops/roadmap/milestones/M02-available-language-parity.md new file mode 100644 index 0000000..1c0ff26 --- /dev/null +++ b/agent-ops/roadmap/milestones/M02-available-language-parity.md @@ -0,0 +1,46 @@ +# M02 Available Language Parity + +## Goal + +Bring the checked-in available implementations into a common protocol surface with same-language tests and cross-language test entry points. + +## Phase + +Phase 2 - Verification and compatibility + +## Status + +Done + +## Scope + +- Maintain the available implementation set listed in `README.md` and `PROTOCOL.md`. +- Keep Dart, Go, Kotlin, Python, and TypeScript aligned with protocol version `0.1`. +- Keep runtime dependencies native-first and narrowly scoped outside protobuf. +- Keep cross-language test runners available for the supported language matrix. + +## Required Features + +- [x] Dart implementation available under `dart/`. +- [x] Go implementation available under `go/`. +- [x] Kotlin implementation available under `kotlin/`. +- [x] Python implementation available under `python/`. +- [x] TypeScript implementation available under `typescript/`. +- [x] Cross-language test entry points exist across the available implementations. +- [x] Dependency direction documented: protobuf is the core protocol dependency; other runtime dependencies must be native-first, protocol-relevant, and minimal. + +## Success Criteria + +- A maintainer can identify available and planned implementations from top-level docs. +- New language work can start from `PORTING_GUIDE.md` and the project crosstest templates. +- Available implementations preserve the documented protocol contract. + +## Non-Goals + +- Mark C# or Swift as available before implementation, same-language tests, and cross-language tests pass. +- Introduce broad frameworks or runtime layers only to cover narrow protocol needs. +- Expand protocol semantics beyond the transport-level contract. + +## Context for Work + +When adding or changing language implementations, use `PORTING_GUIDE.md` and the project skill `agent-ops/skills/project/add-proto-socket-crosstest-language/SKILL.md`. Before changing protocol files, read the protocol domain rule. diff --git a/agent-ops/roadmap/milestones/M03-continuous-verification.md b/agent-ops/roadmap/milestones/M03-continuous-verification.md new file mode 100644 index 0000000..0695982 --- /dev/null +++ b/agent-ops/roadmap/milestones/M03-continuous-verification.md @@ -0,0 +1,49 @@ +# M03 Continuous Verification + +## Goal + +Automate confidence for all available implementations by running same-language tests, cross-language tests, and proto sync checks in an external CI runner. + +## Phase + +Phase 2 - Verification and compatibility + +## Status + +Active + +## Scope + +- Turn the README test command matrix into a repeatable CI workflow. +- Include Dart, Go, Kotlin, Python, and TypeScript same-language tests. +- Include the available cross-language test runners. +- Include proto synchronization checks when proto files change. +- Keep the workflow aligned with the existing local commands and project test-matrix skill. + +## Required Features + +- [ ] Confirm the external CI entry point. The migrated roadmap context keeps Jenkins as the current candidate until changed. +- [ ] Run Dart unit tests. +- [ ] Run Go unit tests. +- [ ] Run Kotlin unit tests. +- [ ] Run Python unit tests. +- [ ] Run TypeScript checks and unit tests. +- [ ] Run available cross-language checks across Dart, Go, Kotlin, Python, and TypeScript. +- [ ] Run `tools/check_proto_sync.sh` when proto bindings may be affected. +- [ ] Document how to inspect failures and rerun the matrix locally. + +## Success Criteria + +- A single CI job or pipeline can validate the full supported-language and cross-language matrix. +- CI failures identify the failing language pair or same-language package clearly. +- The local commands in `README.md` remain consistent with the automated workflow. + +## Non-Goals + +- Add C# or Swift implementation work in this milestone. +- Change protocol behavior or package APIs for the sake of CI convenience. +- Require every normal development task to read the full roadmap. + +## Context for Work + +Use `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md` and `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh` as the closest existing automation context. Treat Jenkins as the current documented candidate unless the user chooses another runner. diff --git a/agent-ops/roadmap/milestones/M04-csharp-port.md b/agent-ops/roadmap/milestones/M04-csharp-port.md new file mode 100644 index 0000000..4eec293 --- /dev/null +++ b/agent-ops/roadmap/milestones/M04-csharp-port.md @@ -0,0 +1,47 @@ +# M04 C# Unity/.NET Port + +## Goal + +Add a C# implementation that supports Unity and .NET consumers while preserving the protocol `0.1` contract and native-first runtime direction. + +## Phase + +Phase 3 - Remaining native platform ports + +## Status + +Planned + +## Scope + +- Implement the core transport abstraction, communicator, nonce handling, request-response correlation, heartbeat, and close-once behavior. +- Implement TCP/TLS and WebSocket/WSS support where practical for the target runtime. +- Add same-language tests and cross-language tests before marking the implementation available. +- Document any non-protobuf runtime dependency and why native APIs are insufficient. + +## Required Features + +- [ ] Choose supported .NET and Unity version targets. +- [ ] Generate or maintain C# protobuf bindings from the canonical schema. +- [ ] Implement `ITransport` and communicator core. +- [ ] Implement TCP/TLS client and server support. +- [ ] Implement WebSocket/WSS support with a focused dependency only if native support is insufficient. +- [ ] Add same-language tests. +- [ ] Add cross-language test runners. +- [ ] Update top-level implementation status only after tests pass. + +## Success Criteria + +- C# peers interoperate with at least one available implementation through the documented protocol. +- C# implementation follows `PORTING_GUIDE.md` and keeps Unity main-thread concerns outside the protocol core. +- Runtime dependency choices are documented and protocol-relevant. + +## Non-Goals + +- Add Unity-specific gameplay, room, auth, session, or chat semantics. +- Change the protocol to accommodate C#-specific APIs. +- Mark C# as available without passing same-language and cross-language checks. + +## Context for Work + +Use the C# section of `PORTING_GUIDE.md` before implementation. Reference Go for concurrency and close-once patterns, and Dart for public API shape and parser map examples. diff --git a/agent-ops/roadmap/milestones/M05-swift-port.md b/agent-ops/roadmap/milestones/M05-swift-port.md new file mode 100644 index 0000000..bc96493 --- /dev/null +++ b/agent-ops/roadmap/milestones/M05-swift-port.md @@ -0,0 +1,47 @@ +# M05 Swift Apple Platform Port + +## Goal + +Add a Swift implementation for iOS and macOS while preserving the protocol `0.1` contract and Apple-native runtime direction. + +## Phase + +Phase 3 - Remaining native platform ports + +## Status + +Planned + +## Scope + +- Implement the core transport abstraction, communicator, nonce handling, request-response correlation, heartbeat, and close-once behavior. +- Use Swift concurrency, actors, `URLSessionWebSocketTask`, and Apple platform APIs where practical. +- Add same-language tests and cross-language tests before marking the implementation available. +- Document any non-protobuf runtime dependency and why native APIs are insufficient. + +## Required Features + +- [ ] Choose supported Swift and Apple platform targets. +- [ ] Generate Swift protobuf bindings from the canonical schema. +- [ ] Implement transport and communicator core. +- [ ] Implement TCP/TLS support. +- [ ] Implement WebSocket/WSS support. +- [ ] Add same-language tests. +- [ ] Add cross-language test runners. +- [ ] Update top-level implementation status only after tests pass. + +## Success Criteria + +- Swift peers interoperate with at least one available implementation through the documented protocol. +- Swift implementation follows `PORTING_GUIDE.md` and keeps platform UI/threading concerns outside the protocol core. +- Runtime dependency choices are documented and protocol-relevant. + +## Non-Goals + +- Add app-specific auth, session, chat, game, or Apple UI abstractions. +- Change the protocol to accommodate Swift-specific APIs. +- Mark Swift as available without passing same-language and cross-language checks. + +## Context for Work + +Use the Swift section of `PORTING_GUIDE.md` before implementation. Prefer actor isolation and Swift concurrency for shared state and cancellation behavior where it fits the protocol core. diff --git a/agent-ops/roadmap/milestones/M06-release-readiness.md b/agent-ops/roadmap/milestones/M06-release-readiness.md new file mode 100644 index 0000000..712e1ca --- /dev/null +++ b/agent-ops/roadmap/milestones/M06-release-readiness.md @@ -0,0 +1,44 @@ +# M06 Release Readiness + +## Goal + +Prepare the project for repeatable external consumption with clear package versions, protocol compatibility statements, and release checks per available language. + +## Phase + +Phase 4 - Release readiness + +## Status + +Planned + +## Scope + +- Clarify package publication targets and release order per language. +- Ensure each published package states the protocol version it implements. +- Keep package versions independent from protocol compatibility versioning. +- Document release checks and compatibility notes. + +## Required Features + +- [ ] Confirm package registry targets for each available language. +- [ ] Define release checklist per language. +- [ ] Ensure package docs state protocol version support. +- [ ] Keep changelog or release notes aligned with `VERSIONING.md`. +- [ ] Verify same-language and cross-language tests before release. + +## Success Criteria + +- A maintainer can release a language package without guessing the compatibility checklist. +- Package releases communicate protocol version support separately from package version changes. +- Release documentation does not imply a protocol bump unless wire format or required behavior changes. + +## Non-Goals + +- Change protocol compatibility policy. +- Add new language implementations. +- Publish packages without the verification milestone being complete. + +## Context for Work + +Use `VERSIONING.md` as the release compatibility source of truth. README currently notes that checked-in implementations must preserve the documented protocol contract even before packages are published. diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 1821773..092bf2d 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -11,7 +11,7 @@ - Protocol Buffers 기반 직렬화 - TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍 / WebSocket 바이너리 프레임 - 타입 기반 메시지 라우팅, 요청-응답 상관관계, 내장 하트비트 -- 현재 구현 완료: Dart, Go, Kotlin / 계획: C#, Swift, Python, TypeScript +- 현재 구현 완료: Dart, Go, Kotlin, Python, TypeScript / 계획: C#, Swift ## 주요 구조 @@ -19,7 +19,10 @@ dart/ — Dart/Flutter 구현체 (lib/, test/, crosstest/) go/ — Go 구현체 (*.go, test/, crosstest/) kotlin/ — Kotlin/Android 구현체 (src/, crosstest/) +python/ — Python 구현체 (proto_socket/, test/, crosstest/) +typescript/ — TypeScript 구현체 (src/, test/, crosstest/) tools/ — proto 생성/동기화 스크립트 +agent-ops/roadmap/ — Goal / Phase / Milestone 기반 로드맵과 현재 마일스톤 포인터 PROTOCOL.md — 와이어 포맷 명세 (정식 스펙) PORTING_GUIDE.md — 새 언어 구현 가이드 VERSIONING.md — 프로토콜/패키지 버전 정책 @@ -34,6 +37,8 @@ VERSIONING.md — 프로토콜/패키지 버전 정책 | Dart | dart pub, protoc_plugin | | Go | Go modules, google.golang.org/protobuf | | Kotlin | Gradle, protobuf-kotlin | +| Python | pytest, protobuf | +| TypeScript | npm, tsx, TypeScript | | Proto 관리 | tools/generate_proto.sh, tools/check_proto_sync.sh | ## 프로젝트 특화 컨벤션 @@ -43,6 +48,12 @@ VERSIONING.md — 프로토콜/패키지 버전 정책 - 새 언어 구현은 PORTING_GUIDE.md에 따라 동일 언어 테스트 + 크로스 언어 테스트 통과 후 Available 표시 - 프로토콜 버전과 패키지 버전은 분리 관리 (VERSIONING.md 참조) +## 마일스톤 컨텍스트 로딩 + +- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다. +- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- 작업 요청이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. + ## 도메인 매핑 더 구체적인 경로가 우선한다. 여러 도메인에 걸친 변경이면 가장 구체적인 도메인 규칙을 먼저 읽고, 실제로 함께 수정하는 관련 도메인 규칙도 읽는다.