<!-- task=m-api-centered-proto-socket-rail/01_contracts_api_registry plan=0 tag=API -->
# PLAN-cloud-G07: Contracts and API Handler Registry Foundation

## 이 파일을 읽는 구현 에이전트에게
이 계획은 `API-Centered Proto-Socket Rail` 마일스톤 첫 번째 에픽의 큰 작업 중 `contracts`와 `api-hub`의 기반만 다룬다. 프로세스 간 연결을 바로 완성하려고 범위를 키우지 말고, API가 여러 요청 핸들러를 안정적으로 등록하고 계약 ID/파서가 빠지지 않게 만드는 기초 레일부터 깐다.

## 배경
현재 API proto-socket 서버는 `services/api/internal/socket/server.go:18`에서 만들어지고 `registerSessionHandlers`는 `HelloRequest`만 등록한다. 반면 계약에는 backtest/market 요청 메시지가 이미 있고, API parser map도 `services/api/internal/contracts/parser_map.go:11`에 여러 메시지를 등록하고 있다. 이후 작업이 API, worker, client로 나뉘므로 이 단계에서 핸들러 등록 구조와 계약 누락 확인 기준을 먼저 고정해야 한다.

## 사용자 리뷰 요청 흐름
구현 중 새 public contract를 추가해야 하는데 기존 요청/응답 의미를 바꿔야 한다면 중단하고 `CODE_REVIEW-cloud-G07.md`의 사용자 리뷰 요청 섹션을 채운다. 단순 additive proto 필드/메시지는 기존 호환성을 유지하는 범위에서 진행한다.

## 분석 결과
### 읽은 파일
- `agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md`
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/api/rules.md`
- `services/api/internal/socket/server.go`
- `services/api/internal/socket/server_test.go`
- `services/api/internal/contracts/parser_map.go`
- `services/api/internal/contracts/parser_map_test.go`
- `packages/contracts/proto/alt/v1/common.proto`
- `packages/contracts/proto/alt/v1/market.proto`
- `packages/contracts/proto/alt/v1/backtest.proto`
- `packages/contracts/README.md`
- `../proto-socket/go/communicator.go`

### 테스트 커버리지 공백
- API socket server 테스트는 hello handler 중심이라 다중 핸들러 등록 실패, 중복 등록, parser 누락을 직접 잡지 못한다.
- 계약 parser map 테스트는 메시지 파싱을 확인하지만 API handler coverage와 연결되어 있지 않다.
- 로컬 테스트 실행은 `agent-test/local/rules.md`에 따라 금지되어 있으므로 원격 검증 환경에서만 실행한다.

### 심볼 참조
- `NewServer`: `services/api/internal/socket/server.go:18`
- `registerSessionHandlers`: `services/api/internal/socket/server.go:32`
- `NewParserMap`: `services/api/internal/contracts/parser_map.go:11`
- `StartBacktestRequest`: `packages/contracts/proto/alt/v1/backtest.proto:35`
- `ListBacktestRunsRequest`: `packages/contracts/proto/alt/v1/backtest.proto:95`
- `ListInstrumentsRequest`: `packages/contracts/proto/alt/v1/market.proto:39`
- `ListBarsRequest`: `packages/contracts/proto/alt/v1/market.proto:48`
- `AddRequestListenerTyped`: `../proto-socket/go/communicator.go`

### 분할 판단
이 작업은 API 내부 등록 구조와 계약 누락 점검까지만 맡는다. 실제 worker socket server/client 구현은 `02+01_worker_socket_rail`, backtest/market 비즈니스 연결은 `04+02_backtest_rail`, `05+02_market_rail`에서 처리한다.

### 범위 결정 근거
- 지금 바로 필요한 것은 API가 hello 외 요청을 받을 수 있는 구조적 자리다.
- worker process 연결 없이 API 핸들러 인터페이스와 parser/contract 점검을 먼저 끝내면 후속 구현 충돌이 줄어든다.
- 새 프로토콜 도입은 금지하고, 기존 proto-socket과 `packages/contracts/proto`만 사용한다.

### 빌드 등급
- Build lane: `cloud-G07`
- Review lane: `cloud-G07`
- 근거: API runtime protocol surface와 contracts registry를 건드리며, 로컬 검증이 금지되어 원격 테스트가 필요하다.

## 구현 체크리스트
### [API-1] API socket handler registry 분리
문제:
`registerSessionHandlers`가 hello만 직접 등록하는 구조라 후속 요청을 추가할 때 socket server가 계속 비대해진다.

해결 방법:
API socket 패키지 안에 handler registration 단위를 분리한다. 예시는 `type HandlerRegistrar interface`나 `RegisterHandlers(ctx, session)` 형태 중 기존 proto-socket 사용 방식에 맞는 최소 구조를 선택한다. hello handler도 새 등록 흐름을 통해 붙여 기존 동작을 유지한다.

수정 파일 및 체크리스트:
- `services/api/internal/socket/server.go`
- 필요 시 `services/api/internal/socket/handlers.go`
- `services/api/internal/socket/server_test.go`
- [ ] hello handler가 새 registry 경유로 등록된다.
- [ ] 중복/누락 등록이 테스트에서 드러난다.
- [ ] public API 함수 시그니처 변경은 최소화한다.

테스트 작성:
- hello request/response 기존 테스트 유지.
- registry에 복수 handler를 등록하는 테스트 추가.
- handler 등록 실패 또는 nil handler 방어 테스트를 추가할지 판단한다.

중간 검증:
- 원격 검증 환경에서만 `go test ./services/api/...` 실행.

### [API-2] Contracts/parser 누락 점검 고정
문제:
API parser map은 market/backtest 메시지를 등록하지만, 실제 handler registry와 연결된 coverage가 약하다.

해결 방법:
현재 milestone에서 API가 받을 요청 메시지 목록을 명시하고 parser map 테스트가 그 목록을 검증하게 한다. 기존 메시지로 부족한 경우에만 proto에 additive schema를 추가한다.

수정 파일 및 체크리스트:
- `services/api/internal/contracts/parser_map.go`
- `services/api/internal/contracts/parser_map_test.go`
- 필요 시 `packages/contracts/proto/alt/v1/*.proto`
- 필요 시 generated contract files
- [ ] backtest start/list/detail/result/compare 요청/응답 parser가 모두 확인된다.
- [ ] market instruments/bars/status에 필요한 요청/응답 parser가 확인된다.
- [ ] schema 추가 시 Go/Dart generated artifacts 갱신 계획과 함께 처리한다.

테스트 작성:
- parser map의 필수 message ID 목록 테스트.
- missing parser가 실패로 드러나는 table test.

중간 검증:
- 원격 검증 환경에서만 `bin/contracts-check` 실행.
- 원격 검증 환경에서만 `go test ./services/api/...` 실행.

### [API-3] 마일스톤 문서와 rule 간 용어 정렬
문제:
API가 core/control plane 역할을 맡는다는 결정이 룰에는 반영됐지만 구현 계획의 용어도 같은 단어를 써야 후속 작업이 흔들리지 않는다.

해결 방법:
구현 중 파일/패키지/테스트 이름에서 `core server`를 새 프로세스로 만들지 않는다. 필요한 naming은 `api hub`, `control plane`, `worker client`로 통일한다.

수정 파일 및 체크리스트:
- 필요 시 `agent-roadmap/phase/operator-surface/milestones/api-centered-proto-socket-rail.md`
- 필요 시 domain rule 문서
- [ ] 별도 core service 생성 없음.
- [ ] API 기준 runtime topology 유지.

테스트 작성:
- 문서만 바꾸는 경우 테스트 없음.
- 코드 naming 변경 시 관련 API tests만 원격에서 실행.

중간 검증:
- 원격 검증 환경에서만 관련 smoke 명령을 실행한다.

## 수정 파일 요약
- 예상 코드: `services/api/internal/socket/**`, `services/api/internal/contracts/**`
- 조건부 코드: `packages/contracts/proto/alt/v1/**`, generated contracts
- 예상 문서: 필요 시 milestone/rule 문구 정렬

## 최종 검증
- 원격 검증 환경에서만 `go test ./services/api/...`
- 원격 검증 환경에서만 `bin/contracts-check`
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
