<!-- task=m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration plan=1 tag=API milestone-task=terminal-control -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is mandatory.** Fill all implementation-owned sections and stop with active files in place. Final verdict, logs, `complete.log`, archive moves, and review-only checks are review-agent-only.

## Overview

date=2026-08-03
task=m-iop-hot-path-one-shot-execution/13+12_outer_turn_integration, plan=1, tag=API

## Archive Evidence Snapshot

- Plan/review 0 was superseded before implementation; it contains no implementation verdict/evidence.

## For the Review Agent

Verify source and fresh output. Archive this file to `code_review_cloud_G09_1.log` and the plan to `plan_cloud_G08_1.log`, then follow PASS/WARN/FAIL finalization. Preserve `milestone-task=terminal-control` on PASS.

## Implementation Item Completion

| Item | Status |
|---|---|
| API-1 Lifecycle integration | [x] |
| API-2 Integration evidence | [x] |

## Implementation Checklist

- [x] [API-1] Wire the already-dispatched selector result and direct/light follow-up stages through one HTTP-turn sequencer while propagating remaining output budget.
- [x] [API-2] Add compatibility, transition, response-start/terminal, and no-post-terminal regression evidence.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

- [x] Append verdict and verified routing signals; findings/dimensions agree.
- [x] Archive review/plan to suffix `1` without overwriting logs and verify `.gitignore` managed block.
- [ ] On PASS write `complete.log`, preserve milestone metadata, archive this child, and remove parent only if empty.
- [x] On WARN/FAIL write the directed next state and no `complete.log`.

## Deviations from Plan

none.

## Key Design Decisions

- Adapted the existing normalized compatibility collector to a stage-scoped Stream Evidence Gate source, so the selected attempt and each same-turn follow-up use the shared outer-turn lifecycle without changing endpoint codecs.
- Stored only the numeric caller output cap in request-local metadata. Each local/review stage derives its provider `max_tokens` from the cap minus usage reported by earlier stages in the same HTTP turn; stage options cannot overwrite that remaining limit.
- Created the outer sequencer only in the HTTP handler path. It is not retained in logical-request or tool-frontier state, so a tool terminal cannot reuse a previous writer or terminal on the next ingress.

## Reviewer Checkpoints

- Confirm one outer turn is created per inbound HTTP request and the initial dispatch result is not dispatched twice.
- Confirm local→review/repair keeps the turn, tool HTTP terminal does not retain the writer across agent roundtrip, and remaining cap reaches stage bodies.
- Confirm compatibility output and ordinary direct/light/cleanup behavior are preserved.

## Verification Results

### Targeted

Command: `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(OuterTurnIntegration|OuterTurnCompatibility|Direct|Light|Cleanup)'`

Exit status: 0

```text
ok  	iop/apps/edge/internal/openai	2.355s
```

### Common regression

Command: `go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service`

Exit status: 0

```text
ok  	iop/packages/go/streamgate	2.081s
ok  	iop/packages/go/config	1.711s
ok  	iop/apps/edge/internal/openai	11.892s
ok  	iop/apps/edge/internal/service	7.113s
```

### Diff

Command: `git diff --check`

Exit status: 0

```text
(no output)
```

### Supplemental Edge smoke

`go vet ./apps/edge/...` exited 0.

`go test -count=1 ./apps/edge/...` was blocked by an unrelated actual-node integration test before the command could complete:

```text
--- FAIL: TestActualNodeReconnectReadyPumpsQueuedWaiterExactlyOnce (7.78s)
    reconnect_readiness_integration_test.go:81: start actual iop-node: fork/exec /tmp/TestActualNodeReconnectReadyPumpsQueuedWaiterExactlyOnce302010079/001/iop-node: permission denied
FAIL	iop/apps/edge/internal/bootstrap	8.307s
```

Resume condition: allow execution of the temporary test-built `iop-node` binary, then rerun `go test -count=1 ./apps/edge/...`.

## Section Ownership

Implementation status, deviations, decisions, and command outputs belong to the implementer. Fixed text/checkpoints stay unchanged. Final result and review-only actions belong to the reviewer.

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Fail
  - Completeness: Fail
  - Test coverage: Fail
  - API contract: Fail
  - Code quality: Pass
  - Implementation deviation: Fail
  - Verification trust: Fail
  - Spec conformance: Fail
- Findings:
  - Required — `apps/edge/internal/openai/hot_path_light.go:758`: the production outer turns are created with an unlimited cap, an exhausted reported budget is converted to `1` and still dispatched at `apps/edge/internal/openai/hot_path_terminal_control.go:508`, normalized stage input omits the remaining cap at `apps/edge/internal/openai/hot_path_dispatch.go:1117`, and the compatibility renderer replaces only usage/terminal at `apps/edge/internal/openai/hot_path_terminal_control.go:516`. Consequently a provider can exceed the caller cap, normalized stages can retain stage-option limits, and local-to-review work can continue after the turn budget is exhausted. Construct each HTTP turn with the parsed caller cap, stop before acquiring/dispatching another stage when no budget remains, apply the remaining cap to both normalized and tunnel requests without stage-option override, and render the capped accumulator through the compatibility response path.
  - Required — `apps/edge/internal/openai/hot_path_terminal_control_test.go:21`: API-2's required handler-level compatibility/transition evidence is absent. The only new integration test exercises a usage helper and two body builders; no `TestHotPathOuterTurnCompatibility` exists, and there is no table proving initial dispatch reuse, direct/tool/local-pass/local-review/repair dispatch counts, response-start/terminal behavior, exhausted-cap stop, or no post-terminal provider work. Add deterministic Chat and Anthropic handler fixtures covering those rows and assert exact dispatch counts, caller-visible compatibility output, accumulated usage, decreasing/zero remaining budget, and one terminal.
- Routing Signals: `review_rework_count=1`, `evidence_integrity_failure=true`
- Next Step: Prepare and materialize a freshly routed follow-up PLAN/CODE_REVIEW pair for the two Required findings; do not write `complete.log`.
