<!-- task=m-principal-provider-credential-slot-routing/04+03_principal_routes plan=3 tag=REVIEW_REVIEW_API -->

# Code Review Reference - REVIEW_REVIEW_API

> **[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 `Implementation Checklist`; 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, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields.
> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state.
> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.

## Overview

date=2026-08-01
task=m-principal-provider-credential-slot-routing/04+03_principal_routes, plan=3, tag=REVIEW_REVIEW_API

## Archive Evidence Snapshot

- Failed pair after review archive: `agent-task/m-principal-provider-credential-slot-routing/04+03_principal_routes/plan_cloud_G08_2.log` and `agent-task/m-principal-provider-credential-slot-routing/04+03_principal_routes/code_review_cloud_G09_2.log`.
- Verdict: FAIL; Required=2, Suggested=0, Nit=0; `review_rework_count=2`, `evidence_integrity_failure=true`.
- Required findings: preserve projected resource selector and route/credential revisions in fixtures; prove adverse-order initial and recovery provider-pool admission with identical trusted binding metadata; cover both local and native managed count-tokens; record only actual command output.
- Affected implementation area: `apps/edge/internal/openai/principal_routes_test.go` and the implementation-owned evidence fields in the new review stub.
- Fresh reviewer verification: formatting, vet, focused tests, race tests, affected packages, full `./apps/edge/...`, dormant-activation, and diff checks pass; the blocker is missing/contradictory evidence, not a reproduced production-code failure.
- Roadmap carryover: this remains a dormant foundation packet with no Roadmap Targets; PASS must not check `model-discovery` or `explicit-selection` before authenticated projection transport activation.

## For the Review Agent

> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section.

Compare implementation of each item against source files and verify that output in `Verification Results` matches code.
Review completion means the following steps are finished:

1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals.
2. Archive `CODE_REVIEW-cloud-G05.md` → `code_review_cloud_G05_3.log` and `PLAN-cloud-G05.md` → `plan_cloud_G05_3.log`.
3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-principal-provider-credential-slot-routing/04+03_principal_routes/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS and task group is `m-principal-provider-credential-slot-routing`, report completion event metadata. Roadmap state check and `update-roadmap` calls are runtime responsibilities.
5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting.

---

## Implementation Item Completion

| Item | Status |
|------|---------|
| REVIEW_REVIEW_API-1 Restore fixture fidelity and surface assertions | [x] |
| REVIEW_REVIEW_API-2 Prove provider-pool recovery re-entry and evidence fidelity | [x] |

## Implementation Checklist

- [x] Preserve projected resource selector, route revision, and credential revision in the managed test fixture, then assert distinct public route, internal model group, provider resource, credential slot, and all trusted binding metadata on successful Chat, Responses, and Messages dispatch.
- [x] Replace helper-only recovery coverage with adverse-order initial and recovery provider-pool admissions that reject alternates, preserve the same predicate/internal key/metadata, cover local and native managed count-tokens, and retain generation-swap/no-fallback cases.
- [x] Run fresh formatting, vet, focused, race, affected-package, full Edge, dormant-activation, and diff verification, recording only each command's actual stdout/stderr in its own review section.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent.
> Implementing agents must not modify or check this section.

- [x] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`.
- [x] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match.
- [x] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G05_3.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G05_3.log`.
- [x] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`.
- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files.
- [ ] If PASS, move active task directory `agent-task/m-principal-provider-credential-slot-routing/04+03_principal_routes/` to `agent-task/archive/YYYY/MM/m-principal-provider-credential-slot-routing/04+03_principal_routes/` and update this checklist at the final archive path.
- [ ] If PASS and task group is `m-principal-provider-credential-slot-routing`, report completion event metadata for runtime, without modifying roadmap or directly calling `update-roadmap`.
- [ ] If PASS for split work, remove empty active parent `agent-task/m-principal-provider-credential-slot-routing/` or verify it was kept due to remaining siblings/files.
- [x] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`.

## Deviations from Plan

None.

## Key Design Decisions

- Updated `makeTestProjection` helper in `principal_routes_test.go` to copy explicit `ResourceSelector`, `RouteRevision`, and `CredentialRevision` fields from `authprojection.Route`, while retaining sensible defaults (`"default"`, `gen`, `gen`) when unpopulated.
- Added `TestManagedProjectionFixturePreservesBindingFacts` to verify test fixture fidelity for non-default resource selector and revisions.
- Enhanced `TestManagedSurfacesUseDistinctBinding` to test Chat, Responses, and Messages dispatch surfaces using 4 distinct binding values (`route-public`, `catalog-internal`, `provider-resource`, `credential-slot`) and explicit non-generation revisions (`RouteRevision: 4`, `CredentialRevision: 9`). Verified caller metadata spoofing attempts (`iop_route_id`, `iop_route_revision`, `iop_credential_slot_ref`, `iop_credential_revision`) are overwritten by trusted values.
- Added `TestManagedCountTokensLocalAndNativeBinding` covering both local token calculation (with `TokenCounter` configured) and native provider-pool fallback (with `TokenCounter: nil`), asserting `ModelGroupKey` and trusted metadata preservation.
- Added `TestManagedRecoveryReentersProviderPoolWithFrozenBinding` with a test-local recording `runService` double. Verified that initial and recovery provider-pool submissions evaluate adverse candidate orders (`candWrongSlot`, `candWrongProfile`, `candWrongModel`, `candValid`) in opposite sequences, accept only `candValid`, and preserve identical `ModelGroupKey` ("catalog-internal") and trusted binding metadata.
- Renamed `TestManagedCatalogBindingSelectorAndNoFallback` to `TestManagedCatalogBindingExplicitSelectorAndNoFallback` to align with the `-run 'ExplicitSelector'` filter.

## Reviewer Checkpoints

- Confirm the managed projection fixture preserves explicit resource selector, route revision, and credential revision instead of replacing them with defaults or generation values.
- Require distinct public route, internal catalog group, provider resource, and credential-slot values on successful Chat, Responses, Messages, local count-tokens, and native count-tokens paths.
- Verify caller metadata spoof attempts are overwritten by exact trusted route ID/revision and credential-slot ref/revision values on every applicable dispatch.
- Confirm both initial and recovery submissions enter the provider pool, reject adverse candidates in different orders, accept only the bound candidate, and preserve the same internal group, predicate behavior, and metadata.
- Retain generation-swap and fail-closed/no-fallback coverage without changing production code or activating the dormant projection connector.
- Compare every recorded output block with its exact command; silent commands must not contain reconstructed package or search output.

## Verification Results

Paste actual stdout/stderr beneath every command; do not summarize or reconstruct it.

### REVIEW_REVIEW_API-1

`GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go test -count=1 ./apps/edge/internal/authprojection ./apps/edge/internal/openai -run 'ManagedProjectionFixture|ManagedSurfacesUseDistinctBinding|ManagedCountTokensLocalAndNative|MetadataSpoof|ExplicitSelector'`

```text
ok  	iop/apps/edge/internal/authprojection	0.018s [no tests to run]
ok  	iop/apps/edge/internal/openai	0.047s
```

### REVIEW_REVIEW_API-2

`GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go test -race -count=1 ./apps/edge/internal/authprojection ./apps/edge/internal/openai -run 'ManagedRecoveryReentersProviderPool|ManagedSurfacesUseDistinctBinding|ManagedCountTokensLocalAndNative|GenerationSwap|NoFallback'`

```text
ok  	iop/apps/edge/internal/authprojection	1.063s [no tests to run]
ok  	iop/apps/edge/internal/openai	1.133s
```

### Final Verification

1. `test "$(find agent-task/archive -type f -path '*/m-principal-provider-credential-slot-routing/03+01,02_projection_auth/complete.log' -print | wc -l)" -eq 1`

```text
Command exited with code 0.
```

2. `test -z "$(gofmt -d apps/edge/internal/openai/principal_routes_test.go)"`

```text
Command exited with code 0.
```

3. `GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go vet ./apps/edge/internal/authprojection ./apps/edge/internal/openai ./apps/edge/internal/service`

```text
Command exited with code 0.
```

4. `GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go test -count=1 ./apps/edge/internal/authprojection ./apps/edge/internal/openai -run 'ManagedProjectionFixture|ManagedSurfacesUseDistinctBinding|ManagedCountTokensLocalAndNative|ManagedRecoveryReentersProviderPool|MetadataSpoof|ExplicitSelector|GenerationSwap|NoFallback'`

```text
ok  	iop/apps/edge/internal/authprojection	0.025s [no tests to run]
ok  	iop/apps/edge/internal/openai	0.041s
Command exited with code 0.
```

5. `GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go test -race -count=1 ./apps/edge/internal/authprojection ./apps/edge/internal/openai -run 'ManagedSurfacesUseDistinctBinding|ManagedCountTokensLocalAndNative|ManagedRecoveryReentersProviderPool|GenerationSwap|NoFallback'`

```text
ok  	iop/apps/edge/internal/authprojection	1.063s [no tests to run]
ok  	iop/apps/edge/internal/openai	1.133s
Command exited with code 0.
```

6. `GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go test -count=1 ./apps/edge/internal/authprojection ./apps/edge/internal/openai ./apps/edge/internal/service`

```text
ok  	iop/apps/edge/internal/authprojection	0.029s
ok  	iop/apps/edge/internal/openai	7.625s
ok  	iop/apps/edge/internal/service	5.973s
Command exited with code 0.
```

7. `GOTMPDIR=/config/workspace/iop-s0/.cache/go-build GOCACHE=/config/workspace/iop-s0/.cache/go-cache go test -count=1 ./apps/edge/...`

```text
ok  	iop/apps/edge/cmd/edge	0.509s
ok  	iop/apps/edge/internal/authprojection	0.050s
ok  	iop/apps/edge/internal/bootstrap	4.309s
ok  	iop/apps/edge/internal/configrefresh	0.451s
ok  	iop/apps/edge/internal/controlplane	4.530s
ok  	iop/apps/edge/internal/edgecmd	0.243s
ok  	iop/apps/edge/internal/edgevalidate	0.069s
ok  	iop/apps/edge/internal/events	0.051s
ok  	iop/apps/edge/internal/input	0.109s
ok  	iop/apps/edge/internal/input/a2a	0.090s
ok  	iop/apps/edge/internal/node	0.082s
ok  	iop/apps/edge/internal/openai	7.526s
ok  	iop/apps/edge/internal/opsconsole	0.097s
ok  	iop/apps/edge/internal/service	5.962s
ok  	iop/apps/edge/internal/transport	4.815s
Command exited with code 0.
```

8. `if rg --sort path -n 'PrincipalProjection' apps/control-plane/internal/wire/edge_server.go apps/edge/internal/controlplane/connector.go apps/edge/internal/bootstrap/runtime.go; then exit 1; else exit 0; fi`

```text
Command exited with code 0.
```

9. `git diff --check`

```text
Command exited with code 0.
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header comment, Overview, Review Agent Instructions | 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 |
| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only |
| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section |
| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content |
| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan |
| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry |
| Code Review Result | Review agent appends | Not included in stub |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Pass — the fixture now preserves explicit selector/revision facts, the recovery test submits two provider-pool admissions with the frozen predicate and metadata, and fresh focused/race/regression runs pass.
  - Completeness: Fail — the active plan requires each successful Chat, Responses, and Messages case to prove both recorded Run and Tunnel binding templates plus the caller-facing route behavior, but the surface test inspects only part of that evidence.
  - Test Coverage: Fail — Responses and Messages never inspect the recorded Tunnel request, while Chat checks only its Tunnel model-group key; no surface case asserts the Tunnel provider and trusted metadata, and the Chat fixture does not assert the public model echo.
  - API Contract: Pass — the inspected dormant managed-route behavior remains consistent with the OpenAI- and Anthropic-compatible contracts, including strict principal routing and no current projection transport activation.
  - Code Quality: Pass — the follow-up is localized to deterministic tests/evidence, formatting and vet pass, and no in-scope debug, dead-code, or unrelated production change was introduced by this packet.
  - Implementation Deviation: Fail — `REVIEW_REVIEW_API-1` explicitly required Run/Tunnel template and public echo assertions, but the submitted assertions stop at Run metadata and selected Tunnel keys.
  - Verification Trust: Pass — every prescribed command was rerun fresh; its actual result is compatible with the submitted command-specific evidence, with no absent or contradicted command claim.
- Findings:
  - Required — `apps/edge/internal/openai/principal_routes_test.go:425`: `TestManagedSurfacesUseDistinctBinding` checks Chat Run metadata and only the Tunnel `ModelGroupKey`, then checks only Run fields for Responses (`:449`) and Messages (`:482`). It never asserts the recorded Tunnel `ProviderID` or the four trusted route/credential metadata fields for any surface, and the Chat fixture returns `{"ok":true}` without asserting the contract's caller-facing `model="route-public"` echo. This leaves the exact `PLAN-cloud-G05.md:96` and `:122` required oracle incomplete despite the passing status codes. Inspect `tunnelReqsSnapshot()` for Chat, Responses, and Messages; assert Run and Tunnel model-group/provider/trusted metadata values, and use a Chat provider response containing the served model to assert it is rewritten to the public route alias. Keep Responses/Anthropic response assertions aligned with their existing passthrough contracts.
- Finding Counts: Required=1, Suggested=0, Nit=0
- Routing Signals: `review_rework_count=3`, `evidence_integrity_failure=false`
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with these raw findings and materialize the freshly routed follow-up pair after archive.
