<!-- task=m-operator-runtime-refactor/02+01_api_lifecycle_capabilities plan=1 tag=REVIEW_API -->

# PLAN - REVIEW_API

## 이 파일을 읽는 구현 에이전트에게

`code_review_cloud_G07_0.log`의 Required findings만 해결한다. 새 구조 리팩토링이나 API semantics 변경은 이 follow-up 범위가 아니다. 구현 후 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 반드시 채우고, 원격 ALT checkout root에서 실행한 검증 명령의 실제 stdout/stderr를 붙인다.

## 배경

1차 구현은 API worker dependency injection과 handler request-path `Connect` 호출을 추가했고, 원격 `go test -count=1 ./services/api/...`는 통과했다. 다만 계획의 API-2 필수 회귀 테스트와 API/worker capability naming alignment 검증이 빠져 있어 `api-worker-lifecycle`과 `capabilities` roadmap target을 PASS로 닫을 수 없다.

## 사용자 리뷰 요청 흐름

구현 중 차단 사유는 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 정당성을 확인한 뒤에만 `USER_REVIEW.md`를 작성한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operator-surface/milestones/operator-runtime-refactor.md`
- Task ids:
  - `api-worker-lifecycle`: `services/api`의 worker client 전역 상태와 one-shot connect 흐름을 주입 가능한 lifecycle로 정리하고, connect failure, timeout, disconnect behavior를 테스트한다.
  - `capabilities`: API/worker `HelloResponse.capabilities`와 handler coverage test가 market/backtest/worker availability를 실제 등록 surface와 일치하게 검증한다.
- Completion mode: check-on-pass

## 분석 결과

### 근거 로그

- `agent-task/m-operator-runtime-refactor/02+01_api_lifecycle_capabilities/code_review_cloud_G07_0.log`

### Required findings

- `services/api/internal/socket/backtest_test.go:34`의 fake worker가 connect 호출/forward 여부를 관측하지 못해 API-2 필수 테스트가 빠져 있다.
- `services/api/internal/socket/handlers.go:80`의 API capability 목록이 `services/worker/internal/socket/handlers.go:80`의 `worker-execution` naming과 정렬되지 않았고, `services/api/internal/socket/server_test.go:242`의 registration coverage도 handler surface와 capability sync를 보장하지 않는다.

### 범위 결정 근거

- 기존 DI 구조, handler signatures, workerclient public interface는 유지한다.
- Protobuf schema/generated output은 변경하지 않는다.
- API가 worker execution/storage를 직접 소유하지 않는다.
- 이 follow-up은 테스트 보강과 capability naming alignment에 한정한다.

### 빌드 등급

- build lane: `cloud-G07`; review lane: `cloud-G07`.
- 기존 task가 lifecycle/capability contract 변경이고, verification trust 회복을 위해 원격 명령 stdout/stderr를 다시 수집해야 하므로 같은 route를 유지한다.

## 구현 체크리스트

- [ ] [REVIEW_API-1] API-2 connect failure 및 reconnect behavior를 handler/lifecycle tests로 고정한다.
- [ ] [REVIEW_API-2] API capability names를 worker capability naming과 정렬하고, registered handler surface와 capability helper가 함께 검증되도록 테스트한다.
- [ ] 원격 ALT checkout root에서 `go test -count=1 ./services/api/internal/socket`를 실행하고 실제 stdout/stderr를 review stub에 기록한다.
- [ ] 원격 ALT checkout root에서 `go test -count=1 ./services/api/...`를 실행하고 실제 stdout/stderr를 review stub에 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

### [REVIEW_API-1] API-2 Regression Tests

#### 문제

`handleStartBacktest`, market handlers, and backtest query handlers now call `worker.Connect(ctx)` before forwarding. The implementation has no test proving a connect failure returns a typed unavailable response without forwarding the request, and no test proving a disconnected fake worker reconnect path is attempted before a valid request is forwarded.

#### 해결 방법

Extend `fakeWorkerClient` with observability for connect calls. A minimal shape is:

```go
connectCount int
```

Then add focused tests:

- connect failure: set `connectErr=workerclient.ErrUnavailable`, call `handleStartBacktest(fake, validStart())`, require `backtestErrorUnavailable`, require `fake.startReq == nil`, and require `connectCount == 1`.
- reconnect behavior: start with `isConnected=false`, call a valid representative handler, require `connectCount == 1`, require request forwarding happened, and require `isConnected == true`.
- apply the same idea to one market handler if existing market tests do not already cover the shared forwarding path.

Do not use sleeps or goroutine timing for these tests; assert fake worker state directly.

#### 수정 파일 및 체크리스트

- [ ] `services/api/internal/socket/backtest_test.go`: add connect call observability and backtest connect failure/reconnect tests.
- [ ] `services/api/internal/socket/market_test.go`: add representative market connect failure or reconnect coverage if backtest-only coverage is not enough for both handler families.

#### 테스트 작성

Required tests:

- connect failure returns typed unavailable without forwarding request.
- reconnect/disconnected state calls `Connect` before forwarding.
- existing timeout mapping tests continue to pass.

#### 중간 검증

Run from the remote ALT checkout root:

```bash
go test -count=1 ./services/api/internal/socket
```

Expected: exit code 0.

### [REVIEW_API-2] Capability Alignment And Sync Test

#### 문제

Worker hello currently advertises `backtest-start` and `worker-execution` when the starter dependency exists. API hello advertises `backtest-start` but not `worker-execution`, and the API registration test only requires `HelloRequest`, so handler/capability drift would not fail tests.

#### 해결 방법

Choose the narrowest contract-preserving alignment:

- If API should expose the worker execution capability to clients, add `worker-execution` to the available API capability set when worker execution is reachable, and keep `worker-available` / `worker-unavailable` as the API-side availability signal.
- If API intentionally should not expose `worker-execution`, document the reason in code/test naming and make the tests assert the deliberate API-vs-worker difference. Do not leave it as an accidental omission.

Add a unit test that ties registered request surface to capabilities. The test can map request types to expected capability names, for example:

```go
registered request types include ListInstruments/ListBars -> market-read
registered request types include backtest query requests -> backtest-read
registered request types include StartBacktestRequest -> backtest-start and, if adopted, worker-execution
```

#### 수정 파일 및 체크리스트

- [ ] `services/api/internal/socket/handlers.go`: align or explicitly justify capability names.
- [ ] `services/api/internal/socket/server_test.go`: add capability/helper sync test that fails if registered market/backtest handlers and advertised capability names drift apart.

#### 테스트 작성

Required tests:

- unavailable worker exact capability set.
- available worker exact capability set.
- capability names and registered handler surface stay in sync.

#### 중간 검증

Run from the remote ALT checkout root:

```bash
go test -count=1 ./services/api/internal/socket
```

Expected: exit code 0.

## 최종 검증

Run from the remote ALT checkout root:

```bash
go test -count=1 ./services/api/...
```

Expected: exit code 0. Go test cache output is not acceptable.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
