<!-- task=m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync plan=1 tag=REVIEW_DOC -->

# Reconcile protocol, wire, Anthropic, and Responses documentation with source

## For the Implementing Agent

Fill the implementation-owned sections of `CODE_REVIEW-cloud-G07.md` as the mandatory final implementation step. Run every verification command, paste actual stdout/stderr, keep the active files in place, and report ready for review; finalization belongs only to the code-review skill. If blocked, record only the exact blocker, attempted commands/output, and resume condition in the implementation-owned evidence fields. Do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`.

## Background

The first closure pass added the intended contract/spec documents, but official review found that several new statements contradict the config schema, protobuf boundary, Anthropic handlers, and Responses admission source. The implementation regressions pass on an executable temporary filesystem; this follow-up is limited to accurate documentation and trustworthy deterministic closure evidence.

## Archive Evidence Snapshot

- Prior pair: `agent-task/m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync/plan_local_G06_01.log` and `agent-task/m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync/code_review_cloud_G06_01.log`.
- Verdict: FAIL with 5 Required, 0 Suggested, and 0 Nit findings.
- Required scope: correct protocol profile config/refresh ownership, distinguish Edge-local body construction from protobuf fields, correct the Anthropic HTTP/routing/metering contract, correct Responses activation semantics, and replace incomplete search/test evidence.
- Fresh reviewer evidence: focused Responses/provider-auth and Pi checks passed; full package, Edge, Node, and vet suites passed with `GOTMPDIR` under executable `/var/tmp`. The prior artifact nevertheless substituted a line count for the required raw drift search and recorded a failed package suite while claiming closure.
- Dependency evidence remains at `agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/03+02_responses_profile/complete.log` and `agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/04+02_pi_responses_regression/complete.log`.
- Roadmap carryover: `contract-sync` and `responses-regression` remain incomplete until this follow-up passes.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/multi-provider-protocol-profile-native-messages.md`
- Milestone link: [Milestone document](agent-roadmap/phase/operational-observability-provider-management/milestones/multi-provider-protocol-profile-native-messages.md)
- Task ids:
  - `contract-sync`: synchronize profile config, tunnel operation, Chat/Messages public/inner contracts, and current implementation specs
  - `responses-regression`: preserve optional Responses drivers and Pi consumption behavior
- Completion mode: check-on-pass

## Analysis

### Files Read

- `agent-roadmap/phase/operational-observability-provider-management/milestones/multi-provider-protocol-profile-native-messages.md`
- `agent-roadmap/sdd/operational-observability-provider-management/multi-provider-protocol-profile-native-messages/SDD.md`
- `agent-contract/index.md`
- `agent-contract/outer/anthropic-compatible-api.md`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-contract/inner/edge-config-runtime-refresh.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- `agent-spec/index.md`
- `agent-spec/input/openai-compatible-surface.md`
- `agent-spec/runtime/edge-node-execution.md`
- `agent-spec/runtime/provider-pool-config-refresh.md`
- `packages/go/config/edge_types.go`
- `packages/go/config/provider_types.go`
- `packages/go/config/protocol_profile.go`
- `apps/edge/internal/configrefresh/classify.go`
- `proto/iop/runtime.proto`
- `apps/edge/internal/node/mapper.go`
- `apps/edge/internal/service/provider_tunnel.go`
- `apps/edge/internal/openai/routes.go`
- `apps/edge/internal/openai/principal.go`
- `apps/edge/internal/openai/anthropic_handler.go`
- `apps/edge/internal/openai/anthropic_native.go`
- `apps/edge/internal/openai/usage_metrics.go`
- `agent-client/pi/install.sh`
- `agent-client/pi/install_test.py`
- `agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/03+02_responses_profile/complete.log`
- `agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/04+02_pi_responses_regression/complete.log`
- `agent-task/m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync/PLAN-local-G06.md`
- `agent-task/m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync/CODE_REVIEW-cloud-G06.md`

### SDD Criteria

- SDD: `agent-roadmap/sdd/operational-observability-provider-management/multi-provider-protocol-profile-native-messages/SDD.md`, status approved and unlocked.
- S04 maps to `contract-sync`: its Acceptance Scenario requires public/inner contracts and spec indexes to point exactly to implementation source after a drift check. Evidence Map row S04 requires the contract/spec index check and implementation-path search.
- S08 maps to `responses-regression`: its Acceptance Scenario preserves normalized/passthrough/provider-auth status, body, stream, and Pi behavior. Evidence Map row S08 requires the existing Responses regression suite.
- These rows require Items REVIEW_DOC-1 through REVIEW_DOC-3 to reconcile every documented boundary, and REVIEW_DOC-4 to capture unpiped drift output plus fresh regressions before either Roadmap target can close.

### Verification Context

- No external handoff was supplied. Repository contracts, specs, Go source, predecessor completion evidence, the failed review artifact, and fresh local commands are the evidence sources.
- Preconditions: both predecessor completion files exist; Go 1.26.2 and Python 3.12.3 are available; `/tmp` is mounted no-exec in this environment, while `/var/tmp` supports executable Go build artifacts.
- Commands were preflighted with focused Responses/provider-auth tests, Pi tests, shell syntax, all package/Edge/Node tests, all three vet suites, and `git diff --check`. Fresh Go commands use `-count=1`; cached test output is not acceptable.
- Deterministic document evidence uses `rg -n --sort path` without a counting pipeline. Every emitted path must be classified in the implementation evidence as contract authority, current spec pointer, implementation source, or test evidence; any contradictory or unexplained result fails closure.
- No live provider, remote runner, device, credential, or external execution is required. Confidence is high because the disputed behavior is explicit in local schema, protobuf, handler, and metric source.

### Test Coverage Gaps

- Config/profile schema and restart classification already have Go coverage; this follow-up changes documentation only and adds no test file.
- Protobuf mapping and tunnel request construction already compile and are covered by Edge/Node package tests; this follow-up changes documentation only and adds no test file.
- Anthropic auth, routing, native/bridge admission, and Responses/provider-auth behavior are covered by existing Edge tests; full Edge tests are mandatory because no new test owns documentation semantics.
- Pi preservation remains covered by `agent-client/pi/install_test.py` and shell parsing.
- Documentation-to-source agreement has no unit-test oracle. The required raw deterministic symbol search, targeted forbidden-drift search, and reviewer classification are the closure evidence.

### Symbol References

- No production symbol is renamed or removed.
- Documentation references must use the actual symbols `ProtocolProfiles`, `ProviderDefinition.Profile`, `ProviderDefinition.RuntimeProfile`, protobuf `ProviderTunnelRequest.operation`, Edge-local `SubmitProviderTunnelRequest.BuildBody`, and the existing driver/operation constants.

### Split Judgment

- This remains one compact documentation closure packet. Config, wire, Anthropic, and Responses wording must agree in one review because the same profile selection and provider tunnel boundary is referenced by all four surfaces; splitting would permit another contradictory intermediate contract state.
- `large_indivisible_context=false`: the packet is reducible to explicit source-backed documentation rules and deterministic local verification.
- The subtask dependencies are satisfied: index 03 by `agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/03+02_responses_profile/complete.log`, and index 04 by `agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/04+02_pi_responses_regression/complete.log`.

### Scope Rationale

- Production Go, protobuf, generated code, tests, Pi scripts, roadmap state, and SDD state are excluded. Fresh regressions and direct source inspection show a documentation/evidence defect, not a requested runtime behavior change.
- Anthropic canonical usage metering is documented as absent; implementing new metering would expand the milestone scope and requires its own runtime plan.
- Live provider qualification remains excluded by S08 and is not needed to validate local contract ownership.

### Final Routing

- `status=routed`; `evaluation_mode=isolated-reassessment`; `finalizer=finalize-task-policy.sh`; `finalizer_mode=pair`.
- Build closures: scope/context/verification/evidence/ownership/decision are all true; capability gap none.
- Build grade scores: scope_coupling=2, state_concurrency=0, blast_irreversibility=2, evidence_diagnosis=2, verification_complexity=1, producing G07.
- Build route: base `local-fit`; `large_indivisible_context=false`; matched loop risks `boundary_contract`, `structured_interpretation`, and `variant_product` (count 3); `review_rework_count=1`; `evidence_integrity_failure=true`; recovery boundary matched; final route `recovery-boundary`, cloud.
- Review closures: scope/context/verification/evidence/ownership/decision are all true; grade scores 2/0/2/2/1, producing G07; route `official-review`, cloud, Codex `gpt-5.6-sol`, xhigh.
- Canonical files: `PLAN-cloud-G07.md` and `CODE_REVIEW-cloud-G07.md`.

## Dependencies and Execution Order

1. Keep the completed index 03 and 04 predecessor evidence unchanged.
2. Correct config and wire ownership before revising the surface descriptions that reference them.
3. Reconcile Anthropic and Responses surface wording and both indexes.
4. Run deterministic drift checks before fresh regressions and record complete evidence.

## Implementation Checklist

- [ ] Correct protocol profile config paths, fields, resolution ownership, and restart-required refresh semantics in the inner contract and runtime specs.
- [ ] Correct protobuf operation, Edge-local body builder, serialized body, nested adapter profile payload, and frame wording in the wire contract and execution spec.
- [ ] Correct Anthropic auth/routes/errors, provider-pool routing, driver-specific admission, native response ownership, usage status, Responses admission, cross-links, and index descriptions.
- [ ] Record complete deterministic source-drift output and fresh focused/full regressions using executable temporary storage.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [REVIEW_DOC-1] Correct protocol profile config and refresh semantics

**Problem**

`agent-contract/inner/edge-config-runtime-refresh.md:35-36` and `agent-spec/runtime/provider-pool-config-refresh.md:154-156` describe a nonexistent `models[].providers[].protocol_profile` overlay, incorrect overlay fields, and live refresh. Source owns custom overlays at top-level `protocol_profiles`, selectors at `nodes[].providers[].profile`, resolved runtime snapshots outside YAML, and restart-required changes.

**Solution**

Replace the false schema/lifecycle statements with the exact source model:

```text
Before (edge-config-runtime-refresh.md:35):
models[].providers[].protocol_profile contains an id-bearing overlay and refreshes without restart.

After:
protocol_profiles is a top-level map keyed by profile id; nodes[].providers[].profile selects a built-in or custom profile. Resolution populates runtime-only RuntimeProfile during config normalization, and changes to either the catalog or selector are restart-required.
```

Document the complete `ProtocolProfileConf` field set (`base`, `driver`, `base_url`, operation-path map, `auth`, `capabilities`, `model_mapping`, `extensions`), distinguish `base` inheritance from legacy provider-type normalization, and keep immutable snapshot semantics separate from refresh classification.

**Modified Files and Checklist**

- [ ] Update `agent-contract/inner/edge-config-runtime-refresh.md` schema, normalization, and refresh sections.
- [ ] Update `agent-spec/runtime/provider-pool-config-refresh.md` with the same ownership and lifecycle without duplicating the full contract.

**Test Strategy**

No new test file. This is documentation correction against existing config and refresh source/tests; targeted source searches plus package/configrefresh regressions are required.

**Verification**

```bash
rg -n --sort path 'ProtocolProfiles|mapstructure:"profile"|protocol_profiles|StatusRestartRequired' packages/go/config/edge_types.go packages/go/config/provider_types.go apps/edge/internal/configrefresh/classify.go agent-contract/inner/edge-config-runtime-refresh.md agent-spec/runtime/provider-pool-config-refresh.md
```

Expected: documentation points to the same top-level catalog, provider selector, and restart-required paths as source.

### [REVIEW_DOC-2] Correct the Edge-local and protobuf tunnel boundaries

**Problem**

`agent-contract/inner/edge-node-runtime-wire.md:56-60` says protobuf `operation` adds no field, invents protobuf `build_body`, and duplicates the frame paragraph. `agent-spec/runtime/edge-node-execution.md:192` and `:226-228` repeat those false wire fields and place profile config at the wrong location.

**Solution**

Describe the actual assembly boundary:

```text
Before (edge-node-runtime-wire.md:56-57):
operation and build_body are append-only ProviderTunnelRequest fields that add no protobuf field.

After:
operation is protobuf field 13. BuildBody belongs only to Edge-local SubmitProviderTunnelRequest; Edge invokes it with the selected served target and serializes the returned bytes into protobuf body. The resolved profile travels in the nested OpenAI-compatible adapter config, not in each tunnel request.
```

Keep `path` as the mixed-version fallback, state that `body` is final serialized provider request bytes, and retain one authoritative frame-invariant paragraph.

**Modified Files and Checklist**

- [ ] Update `agent-contract/inner/edge-node-runtime-wire.md` and remove the duplicate frame entry.
- [ ] Update `agent-spec/runtime/edge-node-execution.md` sequence and data ownership wording.

**Test Strategy**

No new test file. Protobuf compilation, Edge mapper/tunnel tests, and full Edge/Node suites cover the unchanged implementation.

**Verification**

```bash
rg -n --sort path 'operation|BuildBody|ProtocolProfile|body' proto/iop/runtime.proto apps/edge/internal/service/provider_tunnel.go apps/edge/internal/node/mapper.go agent-contract/inner/edge-node-runtime-wire.md agent-spec/runtime/edge-node-execution.md
```

Expected: every documented field is assigned to the correct Edge-local struct, protobuf message, or nested adapter payload.

### [REVIEW_DOC-3] Correct Anthropic and Responses surface contracts

**Problem**

`agent-contract/outer/anthropic-compatible-api.md:30-44`, `:81-87`, `:239-271` omits supported `X-Api-Key` auth, contradicts the models GET route, permits unsupported legacy fallback routing, applies native admission to the Chat bridge, and claims nonexistent Anthropic metering. `agent-spec/input/openai-compatible-surface.md:129-132` repeats the metering claim and makes `openai_responses` the exclusive Responses driver even though the built-in `openai_chat` profile declares Responses.

**Solution**

Align the outer contract and living spec with current handlers:

```text
Before (anthropic-compatible-api.md:255, 269-271):
Native and bridge both require messages/messages, and Anthropic emits the canonical usage series with endpoint=messages.

After:
Native requires messages/messages; the Chat bridge requires chat/chat_completions. Anthropic handlers currently do not record the OpenAI usage metric series, and native USAGE frames are ignored.
```

Document bearer or `X-Api-Key` caller auth and equality when both are present; both Anthropic route aliases plus `/v1/models` selected by `anthropic-version`; actual 405 `invalid_request_error`; provider-pool-only Messages/count_tokens dispatch; native raw response ownership versus bridge conversion; driver-specific capability admission; and Responses admission by declared operation/capability rather than one exclusive driver. Remove false shared-usage text from `openai-compatible-api.md`, both indexes, and the surface spec.

**Modified Files and Checklist**

- [ ] Update `agent-contract/outer/anthropic-compatible-api.md`.
- [ ] Update `agent-contract/outer/openai-compatible-api.md` cross-links.
- [ ] Update `agent-contract/index.md` Anthropic description.
- [ ] Update `agent-spec/input/openai-compatible-surface.md`.
- [ ] Update `agent-spec/index.md` route/source description.

**Test Strategy**

No new test file. Existing Anthropic, Responses, provider-auth, and Pi regressions cover unchanged behavior; focused and full fresh runs are mandatory.

**Verification**

```bash
rg -n --sort path 'X-Api-Key|anthropic-version|ProviderPool|OperationMessages|OperationChatCompletions|usageEndpoint|OperationResponses' apps/edge/internal/openai packages/go/config/protocol_profile.go agent-contract/outer/anthropic-compatible-api.md agent-contract/outer/openai-compatible-api.md agent-contract/index.md agent-spec/input/openai-compatible-surface.md agent-spec/index.md
```

Expected: contract/spec statements match route, auth, provider-pool, capability, usage, and Responses source ownership.

### [REVIEW_DOC-4] Restore trustworthy closure evidence

**Problem**

The prior review artifact at `code_review_cloud_G06_01.log:216-242` replaced the planned raw source search with `wc -l` and asserted full classification without evidence. Its lines 295-329 record a failed package suite while the implementation checklist claims all fresh checks passed.

**Solution**

Run every final command exactly. Paste the unpiped sorted search output or record a deterministic external temporary output path and the exact producing command, then classify every result in `CODE_REVIEW-cloud-G07.md`. Use a unique executable `/var/tmp` directory for Go build artifacts, preserve actual exit status, and report no all-pass conclusion if any command fails.

**Modified Files and Checklist**

- [ ] Fill `agent-task/m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync/CODE_REVIEW-cloud-G07.md` with exact outputs, per-result classification, deviations, and decisions.

**Test Strategy**

No new test file. This item restores deterministic evidence from existing focused and full suites.

**Verification**

Run the complete `Final Verification` block below; every command must exit zero, except the guarded no-match `rg`, whose successful shell result is zero only when no forbidden drift is found.

## Modified Files Summary

| File | Item |
|------|------|
| `agent-contract/inner/edge-config-runtime-refresh.md` | REVIEW_DOC-1 |
| `agent-spec/runtime/provider-pool-config-refresh.md` | REVIEW_DOC-1 |
| `agent-contract/inner/edge-node-runtime-wire.md` | REVIEW_DOC-2 |
| `agent-spec/runtime/edge-node-execution.md` | REVIEW_DOC-2 |
| `agent-contract/outer/anthropic-compatible-api.md` | REVIEW_DOC-3 |
| `agent-contract/outer/openai-compatible-api.md` | REVIEW_DOC-3 |
| `agent-contract/index.md` | REVIEW_DOC-3 |
| `agent-spec/input/openai-compatible-surface.md` | REVIEW_DOC-3 |
| `agent-spec/index.md` | REVIEW_DOC-3 |
| `agent-task/m-multi-provider-protocol-profile-native-messages/05+03,04_contract_spec_sync/CODE_REVIEW-cloud-G07.md` | REVIEW_DOC-4 |

## Final Verification

```bash
set -e
test -f agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/03+02_responses_profile/complete.log
test -f agent-task/archive/2026/08/m-multi-provider-protocol-profile-native-messages/04+02_pi_responses_regression/complete.log
command -v go && go version && go env GOROOT
command -v python3 && python3 --version
test -f agent-contract/outer/anthropic-compatible-api.md
rg -n --sort path 'anthropic-compatible-api|openai-compatible-api|edge-node-runtime-wire|edge-config-runtime-refresh' agent-contract/index.md agent-spec/index.md
rg -n --sort path 'ConcreteProtocolProfile|ProtocolOperation|/v1/messages|/v1/responses' agent-contract agent-spec apps/edge/internal/openai proto/iop/runtime.proto packages/go/config
if rg -n --sort path 'models\[\]\.providers\[\]\.protocol_profile|ProviderTunnelRequest\.build_body|openai_responses.{0,40}active|OpenAI/Anthropic usage metering|endpoint.*messages.*record' agent-contract agent-spec; then echo 'forbidden contract/spec drift remains' >&2; exit 1; fi
if rg -n --sort path 'agent-client/claude/iop-claude-gateway.py' agent-contract agent-spec; then echo 'migration-only gateway leaked into current contract/spec' >&2; exit 1; fi
python3 agent-client/pi/install_test.py
bash -n agent-client/pi/install.sh
followup_tmp=$(mktemp -d /var/tmp/iop-contract-spec-followup.XXXXXX)
trap 'find "$followup_tmp" -depth -delete' EXIT
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go test -count=1 ./apps/edge/internal/openai -run 'TestAnthropic|TestResponses|Test.*ProviderAuth'
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go vet ./packages/go/...
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go vet ./apps/edge/...
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go vet ./apps/node/...
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go test -count=1 ./packages/go/...
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go test -count=1 ./apps/edge/...
env GOCACHE=/config/.cache/iop-contract-spec-followup GOTMPDIR="$followup_tmp" go test -count=1 ./apps/node/...
git diff --check
```

Expected: dependencies and tools exist; indexes resolve; the complete unpiped source search is classified with no forbidden drift; the gateway remains migration-only; Pi and shell checks pass; all fresh focused, vet, package, Edge, and Node checks pass; and the diff is clean.

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
