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

# Code Review Reference - REVIEW_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=4, tag=REVIEW_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_G05_3.log` and `agent-task/m-principal-provider-credential-slot-routing/04+03_principal_routes/code_review_cloud_G05_3.log`.
- Verdict: FAIL; Required=1, Suggested=0, Nit=0; `review_rework_count=3`, `evidence_integrity_failure=false`.
- Required finding: prove the internal group, explicit provider, and exact trusted route/credential metadata on both recorded Run and Tunnel templates for Chat, Responses, and Messages, and prove Chat rewrites a served-model response echo to the public route.
- 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: predecessor, formatting, vet, focused tests, race tests, affected packages, full `./apps/edge/...`, dormant-activation, and diff checks all pass; evidence fidelity is trusted.
- 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-G03.md` → `code_review_cloud_G03_4.log` and `PLAN-cloud-G03.md` → `plan_cloud_G03_4.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-<milestone-slug>`, 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_REVIEW_API-1 Complete the managed surface binding oracle | [x] |

## Implementation Checklist

- [x] Assert complete Run/Tunnel binding and contract-consistent caller-facing model behavior for successful managed Chat, Responses, and Messages dispatch while retaining the fixture, count-tokens, recovery, generation-swap, and 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_G03_4.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G03_4.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`.
- [x] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files.
- [x] 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.
- [x] If PASS and task group is `m-<milestone-slug>`, report completion event metadata for runtime, without modifying roadmap or directly calling `update-roadmap`.
- [x] 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.
- [ ] 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

Added local assertion helpers `assertManagedTemplate` and `assertManagedBinding` within `TestManagedSurfacesUseDistinctBinding` in `apps/edge/internal/openai/principal_routes_test.go` to assert exact internal model group, explicit provider ID, and trusted metadata (`iop_route_id`, `iop_route_revision`, `iop_credential_slot_ref`, `iop_credential_revision`) across both recorded Run and Tunnel request templates. Chat subtest also verifies that provider served-model responses are rewritten to the public route ID in caller-facing HTTP responses.

## Reviewer Checkpoints

- Confirm Chat, Responses, and Messages each submit exactly one provider-pool Tunnel request and inspect both Run and Tunnel templates.
- Require `catalog-internal`, `provider-resource`, `route-public`, revisions `4`/`9`, and `credential-slot` on every applicable recorded template.
- Give Chat a served-model provider response and assert only Chat rewrites the caller-facing model echo to `route-public`; keep Responses and Anthropic passthrough behavior unchanged.
- Retain the fixture fidelity, local/native count-tokens, adverse-order recovery, generation-swap, and no-fallback cases without production changes.
- Compare every recorded output block with its exact command; silent commands must not contain reconstructed output.

## Verification Results

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

### REVIEW_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/openai -run 'ManagedSurfacesUseDistinctBinding'`

```
ok  	iop/apps/edge/internal/openai	0.085s
```

### 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`

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

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`

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 'ManagedSurfacesUseDistinctBinding|ManagedProjectionFixture|ManagedCountTokensLocalAndNative|ManagedRecoveryReentersProviderPool|GenerationSwap|NoFallback'`

```
ok  	iop/apps/edge/internal/authprojection	0.046s [no tests to run]
ok  	iop/apps/edge/internal/openai	0.100s
```

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'`

```
ok  	iop/apps/edge/internal/authprojection	1.060s [no tests to run]
ok  	iop/apps/edge/internal/openai	1.258s
```

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`

```
ok  	iop/apps/edge/internal/authprojection	0.169s
ok  	iop/apps/edge/internal/openai	7.611s
ok  	iop/apps/edge/internal/service	5.973s
```

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

```
ok  	iop/apps/edge/cmd/edge	1.046s
ok  	iop/apps/edge/internal/authprojection	0.094s
ok  	iop/apps/edge/internal/bootstrap	8.606s
ok  	iop/apps/edge/internal/configrefresh	0.837s
ok  	iop/apps/edge/internal/controlplane	4.595s
ok  	iop/apps/edge/internal/edgecmd	0.402s
ok  	iop/apps/edge/internal/edgevalidate	0.127s
ok  	iop/apps/edge/internal/events	0.093s
ok  	iop/apps/edge/internal/input	0.174s
ok  	iop/apps/edge/internal/input/a2a	0.151s
ok  	iop/apps/edge/internal/node	0.136s
ok  	iop/apps/edge/internal/openai	7.698s
ok  	iop/apps/edge/internal/opsconsole	0.139s
ok  	iop/apps/edge/internal/service	6.002s
ok  	iop/apps/edge/internal/transport	4.857s
```

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`

9. `git diff --check`

---

> **[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: PASS
- Dimension Assessment:
  - Correctness: Pass — Chat, Responses, and Messages each record exactly one provider-pool tunnel dispatch whose Run and Tunnel templates retain the internal catalog group, explicit provider resource, and exact trusted route and credential revisions; Chat also rewrites the served-model response echo to the public route.
  - Completeness: Pass — every implementation and verification item in the active plan is complete, including the inherited fixture, count-tokens, recovery, generation-swap, and no-fallback coverage.
  - Test Coverage: Pass — the focused binding oracle, race run, affected-package suites, and full Edge suite pass freshly, and the assertions cover all three required protocol surfaces.
  - API Contract: Pass — Chat model-echo rewriting and Responses/Anthropic passthrough behavior remain consistent with the active compatible API contracts while managed projection transport stays dormant.
  - Code Quality: Pass — the change is localized to deterministic test assertions, is formatted, passes vet, and introduces no debug output, dead code, TODO, or unrelated behavioral change.
  - Implementation Deviation: Pass — the implementation matches the requested test-only recovery scope and the active review artifact accurately records the completed work.
  - Verification Trust: Pass — every prescribed command was rerun from the declared local checkout; all exited successfully and the recorded stdout/stderr is consistent with fresh reviewer output.
- Findings: None
- Finding Counts: Required=0, Suggested=0, Nit=0
- Routing Signals: `review_rework_count=3`, `evidence_integrity_failure=false`
- Next Step: Write `complete.log`, archive the active plan/review pair and task directory, and report milestone completion event metadata to the runtime without modifying the roadmap.
