# Milestone: Proto-Socket Infrastructure Communication Rail

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/workflow-core/PHASE.md`

## 목표

NomadCode 내부 런타임 간 신규 통신을 `proto-socket` 중심으로 통일하는 기반을 만든다. 모든 내부 인프라 통신 후보를 대상으로 REST/HTTP 예외를 분리하고, 첫 구현 축은 Flutter client와 Core가 같은 레일로 task 조회, 실행 요청, 상태 이벤트를 주고받을 수 있게 한다.

## 상태

[진행중]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- 내부 런타임 간 통신 표준을 `proto-socket` 기본, REST/HTTP 예외 방식으로 정리
- `apps/client`와 `services/core` 사이의 client-core 통신 레일 구현 준비
- `packages/contracts`에 proto-socket channel, message envelope, error/heartbeat/auth 후보를 정리
- 기존 core REST task API를 proto-socket channel 후보로 매핑하고 전환 경계를 기록
- Core의 proto-socket endpoint와 Flutter client connector의 최소 구현 단위 정의
- health/readiness, 외부 provider 호환 API, 운영 smoke/curl, public callback, 단순 정적 조회 같은 REST/HTTP 예외 목록 관리

## 기능

### Epic: [protocol] Internal communication contract

내부 인프라 통신을 proto-socket 중심으로 통일하기 위한 계약과 예외 경계를 정리한다.

- [x] [standard-boundary] 내부 런타임 간 신규 통신은 `proto-socket`을 기본으로 삼고 REST/HTTP 예외 조건을 contracts 또는 domain rule에서 추적한다.
- [x] [message-envelope] request, response, event, error, heartbeat, auth metadata를 포함한 최소 message envelope 후보를 정리한다.
- [x] [rest-compat-map] 현재 core REST task API와 health/readiness endpoint를 proto-socket channel 후보와 REST 예외 목록으로 매핑한다.

### Epic: [core-rail] Core proto-socket rail

Core가 내부 런타임 통신용 proto-socket endpoint와 task channel을 제공할 수 있게 한다.

- [x] [core-endpoint] `services/core`에 proto-socket endpoint 구성 위치와 lifecycle을 추가한다. 검증: Core가 기존 REST health/readiness를 유지하면서 proto-socket 연결 endpoint를 노출한다.
- [x] [task-channels] task create/list/get/enqueue와 task status event를 proto-socket channel로 제공한다. 검증: REST task API와 같은 의미의 요청/응답이 proto-socket 경로에서 동작한다.
- [x] [core-contract-tests] core proto-socket channel, auth, error, heartbeat 동작을 테스트로 고정한다.

### Epic: [client-rail] Flutter client-core rail

Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전환한다.

- [x] [client-connector] `apps/client`의 `NoopProtoSocketConnector`를 대체할 concrete connector를 추가한다. 검증: 설정된 endpoint로 연결 상태가 `connected`까지 전이된다.
- [x] [client-task-api] workspace/task 화면이 mock 데이터 대신 Core proto-socket task channel을 소비할 수 있는 client service 경계를 만든다.
- [x] [client-tests] proto-socket endpoint 설정, reconnect/failure lifecycle, client task service를 Flutter test로 검증한다.

### Epic: [ops] Observability and rollout

내부 통신 레일을 운영 가능하게 만들고 예외 프로토콜이 다시 기본값으로 새지 않게 한다.

- [ ] [diagnostics] connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인할 수 있게 한다. 검증: client diagnostics 구현은 반영되었고, 허용된 검증 환경에서 Flutter test/analyze와 code-review PASS가 필요하다.
- [x] [rollout-docs] 새 내부 통신을 추가할 때 proto-socket 우선 여부와 REST/HTTP 예외 사유를 확인하는 운영 체크를 문서화한다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- Mattermost, Plane, Jira 같은 외부 provider의 native REST API 자체를 proto-socket으로 대체하지 않는다.
- health/readiness, 운영 smoke/curl, public callback, 단순 정적 조회 REST 예외를 제거하지 않는다.
- `../nexo/packages/messaging_flutter`의 native push 처리 로직을 수정하지 않는다.
- IOP native protocol, A2A JSON-RPC, OpenAI-compatible Responses 같은 외부 실행 표면을 이 Milestone에서 재설계하지 않는다.
- 전체 프로젝트 관리 UX 완성은 후속 Project Workspace Management UX 범위로 둔다.

## 작업 컨텍스트

- 관련 경로: `services/core/internal/http/`, `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `apps/client/lib/src/integrations/proto_socket/`, `apps/client/lib/src/features/workspaces/`, `packages/contracts/`
- 표준선(선택): 내부 런타임 간 신규 통신은 `proto-socket`을 기본 표준으로 삼고, REST/HTTP는 명시된 예외 조건에서만 유지한다.
- 선행 작업: Mattermost Nexo Messaging Alignment, Client Integration Standardization, 프로젝트 룰의 proto-socket 표준 규약
- 후속 작업: Workflow Core, External Integration, Project Workspace Management UX
- 현재 지점: Core proto-socket endpoint, task channel, Flutter concrete connector, client task service boundary, workspace/task 화면 소비 경계, client diagnostics snapshot/debug surface 구현은 반영되었고, 다음 작업은 허용된 검증 환경에서 Flutter test/analyze 실행과 code-review PASS로 diagnostics 항목을 닫는 것이다.
- 반영 근거: `packages/contracts/notes/flutter-core-api-candidates.md`에 내부 통신 원칙, proto-socket semantic envelope 후보, REST compatibility map 후보를 추가했다.
- Core 반영 근거: `services/core/internal/protosocket/`, `services/core/internal/http/router.go`, `services/core/cmd/server/main.go`에 proto-socket server, task channel, task status event broadcaster, authenticated route 연결과 contract tests가 추가되었다.
- Client connector 반영 근거: `apps/client/lib/src/integrations/proto_socket/proto_socket_client.dart`, `apps/client/lib/src/app/bootstrap.dart`, `apps/client/lib/src/app/nomadcode_client_app.dart`에 `RealProtoSocketConnector`, endpoint-config 기반 connect, task service wiring이 추가되었다.
- Client task/test 반영 근거: `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart`, `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`, `apps/client/test/integrations/proto_socket_*_test.dart`, `apps/client/test/widget_test.dart`에 task channel 소비 경계와 endpoint/lifecycle/task service/widget 검증이 추가되었다.
- Client diagnostics 반영 근거: `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`에 `ProtoSocketDiagnostics` snapshot/stream과 response/event diagnostics recording을 추가했고, `apps/client/lib/src/app/nomadcode_client_app.dart`, `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`, `apps/client/test/integrations/proto_socket_lifecycle_test.dart`, `apps/client/test/widget_test.dart`에 payload/auth/raw error message 없이 connection id, protocol version, channel/action, error code, timestamp를 확인하는 debug surface와 테스트를 추가했다.
- 운영 체크 근거: `packages/contracts/notes/flutter-core-api-candidates.md`에 새 내부 통신 추가 시 proto-socket 우선 여부, REST/HTTP 예외 기록, channel/action 문서화, 검증 항목을 확인하는 운영 체크를 추가했다.
- 확인 필요: 허용된 원격/검증 환경에서 `cd apps/client && flutter test`, `cd apps/client && flutter analyze --no-fatal-infos`를 실행하고, `agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/` code-review PASS 후 `[diagnostics]` 완료 처리 여부를 반영한다.