<!-- task=m-api-centered-proto-socket-rail/01_contracts_api_registry plan=2 tag=REVIEW_API_ENV -->
# PLAN-cloud-G07: Remote Protoc Version Alignment

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

이 계획은 `user_review_0.log`에서 사용자가 결정한 "원격지 `protoc` 버전을 committed 기준인 `v5.29.3`로 올려서 진행"만 수행한다. repo의 generated output 기준선을 `protoc v3.21.12`로 낮추지 않는다. 구현이 끝나면 active `CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션에 실제 명령과 stdout/stderr를 채우고 멈춘다. finalization, log rename, `complete.log`, archive 이동은 code-review 전용이다.

## 배경

이전 루프에서 API registry/parser map 변경은 `go test ./services/api/...`로 통과했다. 남은 차단은 `bin/contracts-check`가 원격 검증 환경의 `/usr/bin/protoc v3.21.12`로 재생성하며 committed `protoc v5.29.3` generated header와 drift를 만든 점이다. 사용자는 원격지 버전을 올려 계속 진행하라고 결정했다.

## 사용자 리뷰 요청 흐름

원격 환경에서 `protoc v5.29.3` 설치 또는 PATH 우선 배치가 실패하면 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청`에 실제 stderr, `command -v protoc`, `protoc --version`, `uname -m`을 기록하고 중단한다. `bin/contracts-check`가 header-only drift가 아닌 schema/code drift로 실패하면 사용자 리뷰로 넘기지 말고 diff를 분석해 repo-owned 문제인지 좁혀 수정한다.

## 분석 결과

### 읽은 파일

- `agent-task/m-api-centered-proto-socket-rail/01_contracts_api_registry/user_review_0.log`
- `agent-task/m-api-centered-proto-socket-rail/01_contracts_api_registry/code_review_cloud_G07_1.log`
- `agent-task/m-api-centered-proto-socket-rail/01_contracts_api_registry/plan_cloud_G07_1.log`
- `bin/contracts-gen`
- `bin/contracts-check`
- `packages/contracts/gen/go/alt/v1/backtest.pb.go`
- `packages/contracts/gen/go/alt/v1/common.pb.go`
- `packages/contracts/gen/go/alt/v1/market.pb.go`

### 테스트 커버리지 공백

- 환경 PATH 정렬은 코드 테스트 대상이 아니다. 검증은 `protoc --version`, `bin/contracts-check`, `go test ./services/api/...`, generated output diff 확인으로 한다.
- 기존 `go test ./services/api/...`는 API registry/parser map 동작을 확인했고 이전 루프에서 PASS였다. 원격 환경 변경 뒤 회귀 확인으로 다시 실행한다.

### 심볼 참조

- 없음. 코드 심볼 rename/remove는 하지 않는다.

### 분할 판단

- 단일 후속 plan으로 유지한다. 작업은 같은 subtask의 검증 환경 정렬과 재검증뿐이며, source/API/call-site rollout이 없다. split하면 같은 원격 PATH 상태를 여러 task가 공유해야 해 오히려 검증 상태가 흐려진다.

### 범위 결정 근거

- 포함: 원격 세션에서 `protoc v5.29.3`를 repo 밖 임시 경로에 설치하거나 PATH 우선 배치하고 검증을 재실행한다.
- 제외: `packages/contracts/gen/**`와 `apps/client/lib/src/generated/**`를 `protoc v3.21.12` 기준으로 재생성/커밋하지 않는다.
- 제외: `bin/contracts-gen` / `bin/contracts-check` 동작 변경은 하지 않는다.

### 빌드 등급

- Build lane: `cloud-G07`
- Review lane: `cloud-G07`
- 근거: terminal-agent 성격의 toolchain/PATH 정렬, bin script 검증, stdout/stderr 판정이 성공 조건이다.

## 구현 체크리스트

### [REVIEW_API_ENV-1] 원격 `protoc v5.29.3` PATH 정렬 및 재검증

문제:
`code_review_cloud_G07_1.log`에 기록된 `bin/contracts-check` 실패는 `/usr/bin/protoc v3.21.12`가 committed generated output의 `protoc v5.29.3` 헤더와 drift를 만들기 때문이다.

해결 방법:
repo 밖 `/tmp` 아래에 `protoc 29.3` release를 준비하고, 해당 `bin`을 PATH 앞에 둔 상태로 `bin/contracts-check`와 API test를 재실행한다. `bin/contracts-gen`은 `command -v protoc` 결과를 사용하므로 PATH 우선 배치로 충분하다.

수정 파일 및 체크리스트:
- `agent-task/m-api-centered-proto-socket-rail/01_contracts_api_registry/CODE_REVIEW-cloud-G07.md`
- [ ] `uname -m`, `command -v protoc`, `protoc --version`의 초기 상태를 기록한다.
- [ ] `/tmp` 아래에 `protoc 29.3`을 준비하고 repo 내부에 tool artifact를 남기지 않는다.
- [ ] PATH 우선 배치 후 `command -v protoc`와 `protoc --version`이 `libprotoc 29.3` 또는 committed header와 동등한 `v5.29.3` 계열임을 기록한다.
- [ ] PATH 우선 배치 상태로 `bin/contracts-check`를 실행하고 실제 stdout/stderr를 기록한다.
- [ ] PATH 우선 배치 상태로 `go test ./services/api/...`를 실행하고 실제 stdout/stderr를 기록한다.
- [ ] generated output에 의도치 않은 diff가 남지 않았음을 `git diff -- packages/contracts/gen/go apps/client/lib/src/generated --exit-code`로 확인한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

테스트 작성:
- 새 테스트 작성 없음. 이 후속 작업은 source behavior 변경이 아니라 원격 codegen toolchain 정렬이다.

중간 검증:
```bash
set -euo pipefail
case "$(uname -m)" in
  aarch64|arm64) protoc_asset="protoc-29.3-linux-aarch_64.zip" ;;
  x86_64|amd64) protoc_asset="protoc-29.3-linux-x86_64.zip" ;;
  *) echo "unsupported arch: $(uname -m)" >&2; exit 2 ;;
esac
tmp_protoc="$(mktemp -d /tmp/protoc-29.3.XXXXXX)"
curl -fsSL -o "$tmp_protoc/protoc.zip" "https://github.com/protocolbuffers/protobuf/releases/download/v29.3/$protoc_asset"
unzip -q "$tmp_protoc/protoc.zip" -d "$tmp_protoc"
PATH="$tmp_protoc/bin:$PATH" protoc --version
```
기대 결과: `libprotoc 29.3` 출력.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-task/m-api-centered-proto-socket-rail/01_contracts_api_registry/CODE_REVIEW-cloud-G07.md` | REVIEW_API_ENV-1 |

## 최종 검증

아래 명령은 같은 원격 shell에서 `tmp_protoc`와 PATH를 유지한 채 실행한다. Go test cache 출력은 허용한다.

```bash
PATH="$tmp_protoc/bin:$PATH" bin/contracts-check
PATH="$tmp_protoc/bin:$PATH" go test ./services/api/...
git diff -- packages/contracts/gen/go apps/client/lib/src/generated --exit-code
```

기대 결과: 세 명령 모두 exit 0. 모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
