<!-- task=m-usage-token-log-ops-mvp/01_identity_alias_auth plan=1 tag=REVIEW_USAGE_ID -->

# Plan - REVIEW_USAGE_ID

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 마지막 단계다. 구현 후 active 파일을 유지하고 리뷰 준비 상태로 보고한다. 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막을 때만 review stub의 `사용자 리뷰 요청` 섹션에 기록하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다. 직접 사용자에게 질문하거나 `USER_REVIEW.md`, `complete.log`, archive log를 만들지 않는다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md)
- Task ids:
  - `identity-scope`: OpenAI-compatible 호출 주체는 IOP bearer token 운영 매핑으로 판별한다.
  - `token-alias`: `token_ref -> principal_ref/internal_alias` 매핑을 raw token 없이 관리한다.
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- Archived plan: `agent-task/m-usage-token-log-ops-mvp/01_identity_alias_auth/plan_cloud_G05_0.log`
- Archived review: `agent-task/m-usage-token-log-ops-mvp/01_identity_alias_auth/code_review_cloud_G05_0.log`
- Verdict: FAIL
- Required summary:
  - `agent-contract/outer/openai-compatible-api.md` Auth 계약이 `openai.principal_tokens` hash mapping auth와 legacy fallback을 설명하지 않는다.
  - `agent-contract/inner/edge-config-runtime-refresh.md` config 계약이 `openai.principal_tokens[]` schema/validation/restart-required classification을 설명하지 않는다.
  - `agent-spec/input/openai-compatible-surface.md` living spec이 현재 principal token auth와 `metadata.user` 비사용/`iop_principal_*` overwrite 정책을 설명하지 않는다.
- Affected files for this follow-up:
  - `agent-contract/outer/openai-compatible-api.md`
  - `agent-contract/inner/edge-config-runtime-refresh.md`
  - `agent-spec/input/openai-compatible-surface.md`
- Prior verification evidence:
  - `GOCACHE=/config/workspace/iop/.cache/go-build go test -count=1 ./packages/go/config ./apps/edge/internal/openai`: PASS in review rerun.
  - `GOCACHE=/config/workspace/iop/.cache/go-build go test -count=1 ./apps/edge/...`: PASS in review rerun.
  - `git diff --check`: PASS.
  - Running the same Go tests without a workspace `GOCACHE` failed in this shell because `/config/.cache/go-build` was not writable; this is local environment cache setup, not a code failure.
- Allowed archive reread:
  - Read only the two archived files listed above if prior implementation details are needed. Do not search `agent-task/archive/**`.

## 배경

이전 구현은 `openai.principal_tokens[]` config schema, hash 기반 bearer auth, principal metadata propagation, `metadata.user` 비사용 테스트를 추가했고 대상 Go tests는 통과했다. 남은 실패 원인은 코드가 아니라 source-of-truth 계약과 현재 구현 스펙이 새 auth/config 경계를 설명하지 않아 외부 동작과 문서가 모순되는 점이다.

## 범위 결정 근거

- 포함: 외부 OpenAI-compatible auth 계약, Edge config/runtime refresh 계약, OpenAI-compatible 입력 표면 living spec 동기화.
- 제외: Go 코드 변경, config validation 변경, metric emit 구현, Grafana 문서, 사용자별 제한, request ledger. 새 동작이 필요한 문제가 아니라 문서/source-of-truth drift 보정이다.
- 코드 변경이 필요하다고 판단되면 이 plan 범위를 벗어난 것이므로 `계획 대비 변경 사항`에 이유를 쓰고 대상 Go tests를 추가 실행한다.

## 구현 체크리스트

- [ ] `agent-contract/outer/openai-compatible-api.md` Auth 계약에 `openai.principal_tokens` hash mapping auth, resolved principal metadata, `metadata.user` 비사용, legacy `openai.bearer_token` fallback을 반영한다.
- [ ] `agent-contract/inner/edge-config-runtime-refresh.md` config 계약에 `openai.principal_tokens[]` schema, raw token 미저장, validation, `openai` restart-required classification을 반영한다.
- [ ] `agent-spec/input/openai-compatible-surface.md` current implementation spec에 principal token auth, legacy fallback, `metadata.user` 비사용, `iop_principal_*` overwrite metadata를 반영한다.
- [ ] `rg` 기반 계약/spec 동기화 확인과 `git diff --check`를 실행한다. 문서/spec 외 코드 변경이 발생한 경우 대상 Go test도 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_USAGE_ID-1] Contract And Spec Sync

문제: 구현은 `openai.principal_tokens[]`를 새 auth/config 경계로 추가했지만, 계약과 living spec은 여전히 legacy `openai.bearer_token` 단일 auth로 설명한다. 이 상태에서는 SDD S01/S02 완료 evidence가 source-of-truth 문서와 충돌한다.

해결 방법:
- `agent-contract/outer/openai-compatible-api.md`의 Auth 섹션을 갱신한다.
  - `openai.principal_tokens[]`가 설정되면 caller는 기존과 같은 `Authorization: Bearer <token>`을 보내며, Edge가 raw token의 SHA-256 hash를 `token_hash_sha256`과 매칭한다.
  - 매칭 성공 시 내부 dispatch metadata 후보로 `iop_principal_ref`, `iop_principal_alias`, `iop_token_ref`, `iop_principal_source`가 채워진다.
  - caller-provided `metadata.user`는 identity source가 아니며, caller가 `metadata.iop_principal_*`를 보내도 authenticated context 값이 overwrite한다.
  - legacy `openai.bearer_token`은 unmapped fallback으로 유지된다.
- `agent-contract/inner/edge-config-runtime-refresh.md`의 핵심 규칙과 refresh 분류 기준을 갱신한다.
  - `openai.principal_tokens[]` fields: `token_ref`, `token_hash_sha256`, `principal_ref`, optional `principal_alias`.
  - tracked config에는 raw token을 저장하지 않고 hash/reference만 둔다.
  - validation: non-empty unique `token_ref`, 64-char hex `token_hash_sha256`, duplicate hash rejection, non-empty `principal_ref`.
  - 기존 classifier가 `openai` deep diff를 restart-required로 분류한다는 점을 기록한다.
- `agent-spec/input/openai-compatible-surface.md`의 기능 목록/설정/한계와 주의사항을 현재 코드 기준으로 갱신한다.

테스트 결정:
- 문서/spec-only 변경이면 Go tests는 재실행하지 않아도 된다. 이전 구현 테스트 PASS는 archive snapshot에 남아 있다.
- 코드 변경이 발생하면 최소 `GOCACHE=/config/workspace/iop/.cache/go-build go test -count=1 ./packages/go/config ./apps/edge/internal/openai`를 실행한다.

중간 검증:

```bash
rg -n "principal_tokens|token_hash_sha256|iop_principal|metadata\\.user|legacy.*bearer|restart_required" agent-contract/outer/openai-compatible-api.md agent-contract/inner/edge-config-runtime-refresh.md agent-spec/input/openai-compatible-surface.md
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `agent-contract/outer/openai-compatible-api.md` | REVIEW_USAGE_ID-1 |
| `agent-contract/inner/edge-config-runtime-refresh.md` | REVIEW_USAGE_ID-1 |
| `agent-spec/input/openai-compatible-surface.md` | REVIEW_USAGE_ID-1 |

## 최종 검증

```bash
rg -n "principal_tokens|token_hash_sha256|iop_principal|metadata\\.user|legacy.*bearer|restart_required" agent-contract/outer/openai-compatible-api.md agent-contract/inner/edge-config-runtime-refresh.md agent-spec/input/openai-compatible-surface.md
git diff --check
```

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