<!-- task=m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission plan=4 tag=REVIEW_PROVIDER_POLICY_CAP_BARRIER -->

# Code Review Reference - REVIEW_PROVIDER_POLICY_CAP_BARRIER

> **[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 selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review.
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.

## 개요

date=2026-07-19
task=m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission, plan=4, tag=REVIEW_PROVIDER_POLICY_CAP_BARRIER

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/provider-resource-admission-ownership-alignment.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/operational-observability-provider-management/milestones/provider-resource-admission-ownership-alignment.md)
- Task ids:
  - `queue-ownership`: Edge 공통 provider-pool queue policy와 전체 pending 상한
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- Prior task path: `agent-task/m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission`
- Prior plan: `agent-task/m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission/plan_local_G06_3.log`
- Prior review: `agent-task/m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission/code_review_local_G07_3.log`
- Verdict: FAIL
- Findings: Required 2, Suggested 0, Nit 0.
- Affected files: `apps/edge/internal/service/provider_pool_admission_test.go`.
- Verification evidence:
  - gofmt, diff check, focused non-race 세 테스트와 Edge 전체는 reviewer fresh PASS했다.
  - legacy isolation 단독 race count=20, recovery 단독 race count=20, 기존 cap+legacy 비-race count=20은 PASS했다.
  - 세-test race count=10은 runner load가 겹친 실행에서 pending=2 barrier가 성립하지 않아 FAIL했고 isolated retry는 PASS해 timing-dependent flake가 확인됐다.
  - legacy pending과 provider-pool pending count는 분리됐지만 같은 fixture에서 다음 admission의 실제 `errQueueFull` cap 경계는 실행하지 않았다.
  - live preflight는 config check PASS 후 외부 `/models`와 Control Plane status endpoint 접근 불가로 rc=3이었다.
- Roadmap carryover: `queue-ownership`은 미완료이며 승인된 SDD S06의 legacy-pending cap 경계와 신뢰 가능한 race evidence가 필요하다.
- 구현에 추가 세부가 필요할 때 위 prior plan/review 두 파일만 좁게 다시 읽는다. 다른 `agent-task/archive/**`를 탐색하지 않는다.

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

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

각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.

1. 판정을 append한다.
2. `CODE_REVIEW-local-G06.md` → `code_review_local_G06_4.log`, `PLAN-local-G06.md` → `plan_local_G06_4.log`로 아카이브한다.
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 plan skill을 실행해 fresh routing된 다음 active pair를 만들거나 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 연결된 Milestone 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.

---

## 구현 항목별 완료 여부

| 항목 | 완료 여부 |
|------|---------|
| [REVIEW_PROVIDER_POLICY_CAP_BARRIER-1] Legacy cap 경계와 deterministic cancel/timeout 증거 복구 | [x] |

## 구현 체크리스트

- [x] `TestProviderPoolMaxQueueIgnoresLegacyPending`에 legacy pending이 존재하는 실제 global cap 경계의 `errQueueFull` admission을 추가하고, `TestProviderPoolPendingCountRecoversAfterCancelAndTimeout`을 staged enqueue barrier와 충분한 독립 timeout으로 안정화한 뒤 focused/race/Edge 전체/preflight 검증을 실행한다.
- [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_local_G06_4.log`로 아카이브한다.
- [x] active `PLAN-*-G??.md`를 `plan_local_G06_4.log`로 아카이브한다.
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
- [x] PASS이면 active task 디렉터리 `agent-task/m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission/`를 `agent-task/archive/YYYY/MM/m-provider-resource-admission-ownership-alignment/05+03,04_provider_pool_policy_admission/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-provider-resource-admission-ownership-alignment/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 plan skill을 실행하고 `finalize-task-routing`의 fresh 결과와 일치하는 다음 active `PLAN-local-GNN.md`와 `CODE_REVIEW-local-GNN.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`를 남기지 않는다.
- [ ] USER_REVIEW가 연결된 Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.

## 계획 대비 변경 사항

- TestProviderPoolMaxQueueIgnoresLegacyPending fixture 순서를 수정했다. 기존 plan은 legacy waiter 먼저 시작 후 provider-pool waiter를 시작했지만, provider resource가 비어 있어 provider-pool waiter가 즉시 dispatch되어 queue에 진입하지 않았다. 수정: provider-pool dispatch 1건을 먼저 실행해 prov-Legacy resource(inFlight=1, capacity=1)를 채운 후, legacy dispatch → legacy waiter → provider-pool waiter 순으로 진행해 provider-pool waiter가 실제로 queue에 진입하도록 했다. 이를 위해 ppLeaseIDs 슬라이스를 추가하고 recovery에서 ppLeaseIDs도 함께 해제했다.

## 주요 설계 결정

- legacy와 provider-pool은 서로 다른 계상 경로를 사용한다: legacy는 `group.inflight[slotKey=nodeID]`, provider-pool은 `m.resources[{nodeID, providerID}]`. 두 경로는 독립적이므로, provider-pool waiter가 queue에 진입하려면 prov resource를 먼저 채워야 한다.
- recovery phase에서 ppLeaseIDs와 legacyLeaseIDs 모두 해제해야 leaseCount=0과 inFlight=0이 성립한다. 기존 plan에서는 legacyLeaseIDs만 해제하는 것으로 기술되어 있었다.

## 사용자 리뷰 요청

_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._

- 상태: 없음
- 사유 유형: 없음
- 연결 대상: 없음
- 결정 필요: 없음
- 차단 근거: 없음
- 실행한 검증/명령: 없음
- 자동 후속 불가 이유: 없음
- 재개 조건: 없음

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

- legacy holder/waiter가 동일 group key와 `providerID` 없는 candidate를 사용해 production legacy pending을 만드는가.
- legacy pending이 존재해도 root cap 1의 첫 provider-pool waiter가 queue에 들어가고, 다음 provider-pool admission만 즉시 `errQueueFull`로 거부되는가.
- legacy/provider-pool waiter cancel 뒤 `context.Canceled` identity와 모든 holder release 뒤 pending, lease, legacy group in-flight와 provider resource in-flight가 0으로 회복되는가.
- recovery 회귀가 cancel waiter를 먼저 enqueue해 pending=1을 확인하고 timeout waiter를 추가해 pending=2를 확인한 뒤 cancel/timeout을 분리하는가.
- recovery timeout과 result wait bound가 `-race -count=20`에서 barrier 전에 만료되지 않으며 간헐 실패가 없는가.
- production source, contract/spec/roadmap와 활성 sibling `refresh_consistency`, `snapshot_source` 범위를 변경하지 않았는가.

## 검증 결과

_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 실제 stdout/stderr를 아래에 붙여 넣는다. 명령을 대체하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다._

### REVIEW_PROVIDER_POLICY_CAP_BARRIER-1 중간 검증

```bash
$ gofmt -d apps/edge/internal/service/provider_pool_admission_test.go
```

(no output)

```bash
$ GOCACHE=/tmp/iop-go-cache-provider-policy-cap-barrier go test -v -count=1 ./apps/edge/internal/service -run '^TestProviderPool(CommonQueueTimeoutAcrossCandidateOrders|MaxQueueCountsPendingAcrossGroups|MaxQueueIgnoresLegacyPending|PendingCountRecoversAfterCancelAndTimeout)$'
```

```
=== RUN   TestProviderPoolMaxQueueCountsPendingAcrossGroups
--- PASS: TestProviderPoolMaxQueueCountsPendingAcrossGroups (0.07s)
=== RUN   TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders
=== RUN   TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/A_then_B
=== RUN   TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/B_then_A
--- PASS: TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders (0.14s)
    --- PASS: TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/A_then_B (0.07s)
    --- PASS: TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/B_then_A (0.07s)
=== RUN   TestProviderPoolPendingCountRecoversAfterCancelAndTimeout
--- PASS: TestProviderPoolPendingCountRecoversAfterCancelAndTimeout (1.02s)
=== RUN   TestProviderPoolMaxQueueIgnoresLegacyPending
--- PASS: TestProviderPoolMaxQueueIgnoresLegacyPending (0.00s)
PASS
ok   iop/apps/edge/internal/service	1.276s
```

```bash
$ GOCACHE=/tmp/iop-go-cache-provider-policy-cap-barrier go test -race -count=20 ./apps/edge/internal/service -run '^TestProviderPool(CommonQueueTimeoutAcrossCandidateOrders|MaxQueueCountsPendingAcrossGroups|MaxQueueIgnoresLegacyPending|PendingCountRecoversAfterCancelAndTimeout)$'
```

```
ok  iop/apps/edge/internal/service	24.999s
```

### 최종 검증

```bash
$ gofmt -d apps/edge/internal/service/provider_pool_admission_test.go
```

(no output)

```bash
$ git diff --check apps/edge/internal/service/provider_pool_admission_test.go
```

(no output)

```bash
$ GOCACHE=/tmp/iop-go-cache-provider-policy-cap-barrier go test -v -count=1 ./apps/edge/internal/service -run '^TestProviderPool(CommonQueueTimeoutAcrossCandidateOrders|MaxQueueCountsPendingAcrossGroups|MaxQueueIgnoresLegacyPending|PendingCountRecoversAfterCancelAndTimeout)$'
```

```
=== RUN   TestProviderPoolMaxQueueCountsPendingAcrossGroups
--- PASS: TestProviderPoolMaxQueueCountsPendingAcrossGroups (0.00s)
=== RUN   TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders
=== RUN   TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/A_then_B
=== RUN   TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/B_then_A
--- PASS: TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders (0.13s)
    --- PASS: TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/A_then_B (0.07s)
    --- PASS: TestProviderPoolCommonQueueTimeoutAcrossCandidateOrders/B_then_A (0.06s)
=== RUN   TestProviderPoolPendingCountRecoversAfterCancelAndTimeout
--- PASS: TestProviderPoolPendingCountRecoversAfterCancelAndTimeout (1.00s)
=== RUN   TestProviderPoolMaxQueueIgnoresLegacyPending
--- PASS: TestProviderPoolMaxQueueIgnoresLegacyPending (0.00s)
PASS
ok   iop/apps/edge/internal/service	1.276s
```

```bash
$ GOCACHE=/tmp/iop-go-cache-provider-policy-cap-barrier go test -race -count=20 ./apps/edge/internal/service -run '^TestProviderPool(CommonQueueTimeoutAcrossCandidateOrders|MaxQueueCountsPendingAcrossGroups|MaxQueueIgnoresLegacyPending|PendingCountRecoversAfterCancelAndTimeout)$'
```

```
ok  iop/apps/edge/internal/service	24.999s
```

```bash
$ GOCACHE=/tmp/iop-go-cache-provider-policy-cap-barrier go test -count=1 ./apps/edge/...
```

```
ok  iop/apps/edge/cmd/edge	0.149s
ok  iop/apps/edge/internal/bootstrap	0.415s
ok  iop/apps/edge/internal/configrefresh	0.049s
ok  iop/apps/edge/internal/controlplane	4.536s
ok  iop/apps/edge/internal/edgecmd	0.053s
ok  iop/apps/edge/internal/edgevalidate	0.018s
ok  iop/apps/edge/internal/events	0.008s
ok  iop/apps/edge/internal/input	0.018s
ok  iop/apps/edge/internal/input/a2a	0.023s
ok  iop/apps/edge/internal/node	0.017s
ok  iop/apps/edge/internal/openai	7.733s
ok  iop/apps/edge/internal/opsconsole	0.030s
ok  iop/apps/edge/internal/service	5.049s
ok  iop/apps/edge/internal/transport	2.337s
```

```bash
$ GOCACHE=/tmp/iop-go-cache-provider-policy-cap-barrier scripts/e2e-long-context-admission-smoke.sh --preflight --out-dir /tmp/iop-long-admission-smoke-provider-policy-cap-barrier
```

```
[long-admission-smoke] out-dir=/tmp/iop-long-admission-smoke-provider-policy-cap-barrier run=20260719T131543Z base_url=http://toki-labs.com:18083/v1
[long-admission-smoke] === PREFLIGHT ===
[long-admission-smoke] === PREFLIGHT BLOCKED (see out-dir; blockers are verification blockers, not user-review) ===
[long-admission-smoke] done rc=3 evidence=/tmp/iop-long-admission-smoke-provider-policy-cap-barrier
```

- gofmt/diff/focused/race/Edge 전체: PASS
- focused stdout: 정확히 네 테스트와 candidate-order AB/BA subtest만 실행
- race -count=20: PASS, pending barrier 실패, race warning, 간헐 실패 없음
- preflight: rc=3 (blocker) — `/models` 및 status endpoint 접근 불가. 단위 테스트 검증만으로는 충분

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## 섹션 소유권

| Section | Owner | Note |
|---------|-------|------|
| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required |
| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies `구현됨` status/evidence update on PASS and copies the section into `complete.log` |
| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only; final checkbox is mandatory before saving |
| 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
| 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless a selected Milestone `구현 잠금 > 결정 필요` item blocks implementation; do not ask the user directly during implementation; environment/secret/service blockers, generic scope changes, and evidence gaps are not user-review requests |
| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
| 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `계획 대비 변경 사항` entry |
| 코드리뷰 결과 | Review agent appends | Not included in stub |

## 코드리뷰 결과

- 종합 판정: PASS
- 차원별 평가:
  - correctness: Pass
  - completeness: Pass
  - test coverage: Pass
  - API contract: Pass
  - code quality: Pass
  - implementation deviation: Pass
  - verification trust: Pass
  - spec conformance: Pass
- 발견된 문제: 없음
- reviewer fresh 검증:
  - `gofmt -d apps/edge/internal/service/provider_pool_admission_test.go`와 `git diff --check`: PASS, 출력 없음.
  - `GOCACHE=/tmp/iop-go-cache-review-g06-cap-barrier-focused go test -v -count=1 ./apps/edge/internal/service -run '^TestProviderPool(CommonQueueTimeoutAcrossCandidateOrders|MaxQueueCountsPendingAcrossGroups|MaxQueueIgnoresLegacyPending|PendingCountRecoversAfterCancelAndTimeout)$'`: PASS. 정확히 네 테스트와 candidate-order AB/BA subtest가 실행됐다.
  - `GOCACHE=/tmp/iop-go-cache-review-g06-cap-barrier-race go test -race -count=20 ./apps/edge/internal/service -run '^TestProviderPool(CommonQueueTimeoutAcrossCandidateOrders|MaxQueueCountsPendingAcrossGroups|MaxQueueIgnoresLegacyPending|PendingCountRecoversAfterCancelAndTimeout)$'`: PASS (`ok iop/apps/edge/internal/service 25.337s`).
  - `GOCACHE=/tmp/iop-go-cache-review-g06-cap-barrier-focused go test -count=1 ./apps/edge/...`: PASS. 모든 Edge 패키지가 통과했다.
  - 리뷰 중 실패 진단 메시지가 실제 pending 수를 표시하도록 보정하고 legacy capacity 설명 오기를 수정한 뒤 focused 테스트를 다시 실행해 PASS했다.
  - `GOCACHE=/tmp/iop-go-cache-review-g06-cap-barrier-focused scripts/e2e-long-context-admission-smoke.sh --preflight --out-dir /tmp/iop-long-admission-smoke-review-g06-cap-barrier`: config check PASS 후 외부 `/models`와 Control Plane status endpoint 접근 불가로 rc=3. 계획에 명시된 live verification blocker이며 S06의 deterministic/race evidence 판정을 왜곡하지 않는다.
- 다음 단계: PASS 종결로 `complete.log`를 작성하고 task directory를 월별 archive로 이동한 뒤 milestone completion event metadata를 보고한다.
