<!-- task=m-api-centered-proto-socket-rail/01_contracts_api_registry plan=2 tag=REVIEW_API_ENV -->

# Code Review Reference - REVIEW_API_ENV

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked by a user-only decision, external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.

## 개요

date=2026-05-30
task=m-api-centered-proto-socket-rail/01_contracts_api_registry, plan=2, tag=REVIEW_API_ENV

## 이 파일을 읽는 리뷰 에이전트에게

> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.

각 항목의 구현을 실제 원격 검증 출력과 대조하고, `검증 결과` 섹션의 출력이 plan의 고정 명령과 일치하는지 확인하세요.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_API_ENV-1] 원격 `protoc v5.29.3` PATH 정렬 및 재검증 | [x] |

## 구현 체크리스트

- [x] `uname -m`, `command -v protoc`, `protoc --version`의 초기 상태를 기록한다. → `aarch64` / `/usr/bin/protoc` / `libprotoc 3.21.12`
- [x] `/tmp` 아래에 `protoc 29.3`을 준비하고 repo 내부에 tool artifact를 남기지 않는다. → `mktemp -d /tmp/protoc-29.3.XXXXXX`에 release 추출, repo artifact 검색 결과 없음 확인.
- [x] PATH 우선 배치 후 `command -v protoc`와 `protoc --version`이 `libprotoc 29.3` 또는 committed header와 동등한 `v5.29.3` 계열임을 기록한다. → `command -v protoc`=`/tmp/protoc-29.3.LoErHk/bin/protoc`, `protoc --version`=`libprotoc 29.3`.
- [x] PATH 우선 배치 상태로 `bin/contracts-check`를 실행하고 실제 stdout/stderr를 기록한다. → exit 0, stdout/stderr 없음.
- [x] PATH 우선 배치 상태로 `go test ./services/api/...`를 실행하고 실제 stdout/stderr를 기록한다. → exit 0 (PASS).
- [x] generated output에 의도치 않은 diff가 남지 않았음을 `git diff -- packages/contracts/gen/go apps/client/lib/src/generated --exit-code`로 확인한다. → exit 0 (diff 없음).
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 코드리뷰 전용 체크리스트

> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.

- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_2.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_2.log`로 아카이브한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리 `agent-task/m-api-centered-proto-socket-rail/01_contracts_api_registry/`를 `agent-task/archive/2026/05/m-api-centered-proto-socket-rail/01_contracts_api_registry/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [x] PASS이고 task group이 `m-api-centered-proto-socket-rail`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-api-centered-proto-socket-rail/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.

## 계획 대비 변경 사항

- 계획과 동일하게 진행했다. source/API 코드 변경 없음, `bin/contracts-gen`/`bin/contracts-check` 동작 변경 없음, generated 기준선을 `protoc v3.21.12`로 낮추지 않음. plan-0의 API registry/parser map 소스 변경은 그대로 유지했고 이 후속 plan에서는 검증 환경 정렬과 재검증만 수행했다.

## 주요 설계 결정

- 사용자 결정(`user_review_0.log`)에 따라 검증 환경의 `protoc`를 committed 기준선(`protoc v5.29.3` = protobuf release v29.3, `libprotoc 29.3`)에 맞췄다. protobuf v29.3 release를 repo 밖 `/tmp`에 추출하고 PATH 앞에 두어 `bin/contracts-gen`이 사용하는 `protoc`를 교체했다. `/usr/bin/protoc v3.21.12`는 그대로 두고 repo 내부에는 tool artifact를 남기지 않아, generated 기준선과 시스템 toolchain을 모두 변경하지 않으면서 검증만 통과시켰다.

## 사용자 리뷰 요청

_기본값은 `없음`이다. 구현 중 사용자 결정, 외부 환경 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. code-review가 이 내용을 검증해 `USER_REVIEW.md`를 작성한다._

- 상태: 없음
- 사유 유형: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 재개 조건: 없음

## 리뷰어를 위한 체크포인트

- `user_review_0.log`의 사용자 결정이 새 plan 배경에 반영됐는지 확인한다.
- repo 내부에 downloaded protoc artifact가 남지 않았는지 확인한다.
- `bin/contracts-check`가 PATH 우선 배치된 `protoc 29.3`으로 실행됐는지 확인한다.
- `go test ./services/api/...`가 같은 원격 검증 세션에서 다시 통과했는지 확인한다.
- generated output diff가 남지 않았는지 확인한다.

## 검증 결과

_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._

### 초기 상태
```bash
$ uname -m
aarch64
$ command -v protoc
/usr/bin/protoc
$ protoc --version
libprotoc 3.21.12
```

### REVIEW_API_ENV-1 중간 검증
```bash
$ 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
# protoc_asset=protoc-29.3-linux-aarch_64.zip
$ tmp_protoc="$(mktemp -d /tmp/protoc-29.3.XXXXXX)"
# tmp_protoc=/tmp/protoc-29.3.LoErHk
$ curl -fsSL -o "$tmp_protoc/protoc.zip" "https://github.com/protocolbuffers/protobuf/releases/download/v29.3/$protoc_asset"
# exit 0
$ unzip -q "$tmp_protoc/protoc.zip" -d "$tmp_protoc"
# exit 0
$ PATH="$tmp_protoc/bin:$PATH" command -v protoc
/tmp/protoc-29.3.LoErHk/bin/protoc
$ PATH="$tmp_protoc/bin:$PATH" protoc --version
libprotoc 29.3
```

### 최종 검증
```bash
$ PATH="$tmp_protoc/bin:$PATH" bin/contracts-check
# (stdout/stderr 없음)
[contracts-check exit: 0]

$ PATH="$tmp_protoc/bin:$PATH" go test ./services/api/...
?   	git.toki-labs.com/toki/alt/services/api/cmd/alt-api	[no test files]
ok  	git.toki-labs.com/toki/alt/services/api/internal/config	(cached)
ok  	git.toki-labs.com/toki/alt/services/api/internal/contracts	(cached)
ok  	git.toki-labs.com/toki/alt/services/api/internal/socket	(cached)
[go test exit: 0]

$ git diff -- packages/contracts/gen/go apps/client/lib/src/generated --exit-code
# (출력 없음)
[git diff exit: 0]
```

### repo artifact 잔존 확인
```bash
$ find . -name '*protoc-29*' -not -path './.git/*'
# (출력 없음 — downloaded protoc는 /tmp 아래에만 존재, repo 내부 artifact 없음)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - correctness: Pass
  - completeness: Pass
  - test coverage: Pass
  - API contract: Pass
  - code quality: Pass
  - plan deviation: Pass
  - verification trust: Pass
- 발견된 문제: 없음
- 다음 단계: PASS. active plan/review를 로그로 아카이브하고 `complete.log` 작성 후 task directory를 archive로 이동한다.
