<!-- task=m-iop-hot-path-one-shot-execution/15+13_chat_gate plan=1 tag=API milestone-task=terminal-control,chat-gate -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is mandatory.** Fill implementation-owned evidence and stop with active files. Review finalization is review-agent-only.

## Overview

date=2026-08-03
task=m-iop-hot-path-one-shot-execution/15+13_chat_gate, 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/wire output, archive to `code_review_cloud_G10_1.log` and `plan_cloud_G09_1.log`, then finalize by verdict. Preserve `milestone-task=terminal-control,chat-gate` on PASS.

## Implementation Item Completion

| Item | Status |
|---|---|
| API-1 Native Chat outer codec | [x] |
| API-2 Chat wire evidence | [x] |

## Implementation Checklist

- [x] [API-1] Add a caller-facing Chat outer codec and pass the already-dispatched preset result, stream mode, model, and caller output cap into the shared turn.
- [x] [API-2] Add streaming/non-streaming, mixed-provider, fragmentation, tool, cap, usage, and baseline error handler fixtures.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

- [x] Append verdict/routing signals and verify findings/dimensions.
- [x] Archive review/plan to suffix `1`; verify `.gitignore` managed block.
- [x] On PASS write `complete.log`, preserve metadata, archive child; on WARN/FAIL write directed state without completion.

## Deviations from Plan

- The existing shared outer-turn bridge lives in `hot_path_direct.go`, `hot_path_dispatch.go`, and `hot_path_light.go`. Small wiring changes were required in those files so initial, continuation, and same-HTTP multi-stage Chat responses all reuse the handler-created codec and outer turn. No provider decoder, Responses API, or unrelated endpoint behavior was added.

## Key Design Decisions

- The Chat handler creates and context-pins one codec after resolving the effective `max_tokens` or `max_completion_tokens` cap. The codec receives the already-admitted `ProviderPoolDispatchResult`; selector collection remains exactly once and never redispatches.
- Provider-specific OpenAI/Anthropic decoding remains in the common Hot Path collectors. The Chat codec consumes only normalized outer deltas and the compatibility accumulator.
- Streaming output uses one response id, one assistant role chunk, ordered content/reasoning deltas, final mapped tool order with stable zero-based indexes, aggregate usage, one finish chunk, and one `[DONE]` marker. Non-stream output uses the same public model, identity, finish mapping, and aggregate usage.
- Pre-commit collection errors retain the existing endpoint-standard JSON error. The codec exposes a single-render guard for the later exhaustive post-commit error work owned by child 17.

## Reviewer Checkpoints

- Confirm provider decoding stays common and `normalized_sse.go` only owns caller-facing Chat encoding.
- Confirm initial result is not redispatched, output cap resolves from both request fields, one response lifecycle/tool index sequence, aggregate usage, and non-stream compatibility.
- Confirm `/v1/responses` is not added to this SDD scope.

## Verification Results

### Targeted

Command: `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPathChat|TestChatStreamSession'`

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

Exit status: 0.

### Common regression

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

```text
ok  	iop/packages/go/streamgate	2.328s
ok  	iop/packages/go/config	1.786s
ok  	iop/apps/edge/internal/openai	12.481s
ok  	iop/apps/edge/internal/service	7.138s
```

Exit status: 0.

### Diff

Command: `git diff --check`

No output. Exit status: 0.

### Supplemental Edge checks

- `go test -count=1 ./apps/edge/...` - PASS with a workspace-local `TMPDIR`. The first run failed only because the default `/tmp` mount denied execution of the test-built `iop-node`; rerunning the exact failing bootstrap test and the full Edge suite from an executable workspace-local temporary directory passed.
- `go vet ./apps/edge/...` - PASS; no output.
- `gofmt -l` on the implementation-owned Go files - PASS; no output.
- Repository Edge-Node diagnostics, supplemental credentialed provider smoke, and full-cycle Pi execution were not run. This child owns deterministic handler/wire evidence; actual Pi smoke remains assigned to child 21.

## Section Ownership

Implementer owns completion status, deviations, decisions, and outputs. Reviewer alone owns review-only actions and final result.

## 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: Pass
  - Spec Conformance: Fail
- Findings:
  - Required — `apps/edge/internal/openai/normalized_sse.go:124`: the Chat codec still calls the fully buffering selector collector and only writes/flushed SSE later from `writeResponse` at `apps/edge/internal/openai/normalized_sse.go:143`. The light path likewise finishes `dispatchHotPathStage` and appends collected deltas in memory at `apps/edge/internal/openai/hot_path_light.go:810-824` before any caller write. This does not satisfy SDD S10/S12 terminal-only hold semantics or the plan's progressive caller-chunk requirement. Feed released stage deltas into the Chat writer as they become safe, preserve one outer role/identity/tool-index space, and hold only the endpoint terminal; add a blocking handler test that proves a visible delta is flushed before the provider/stage terminal is released.
  - Required — `apps/edge/internal/openai/hot_path_light.go:793`: continuation turns seed the public outer response identity with the logical `requestID`, and `apps/edge/internal/openai/normalized_sse.go:157-161` always prefers that value. The existing mixed-stage fixture codifies the leak at `apps/edge/internal/openai/hot_path_chat_gate_test.go:203-207`. The normalized selector path also assigns `RunDispatch.RunID` to `ResponseID` at `apps/edge/internal/openai/hot_path_dispatch.go:109-133`, with `apps/edge/internal/openai/hot_path_direct_test.go:480-509` expecting that internal run id on the public wire. The approved SDD and OpenAI-compatible contract require provider/public-safe response identity and keep logical request/run/stage ids internal. Bind the outer identity from the first provider-owned Chat response id, propagate an explicit public-safe identity for normalized execution or fail closed when it is unavailable, and add regressions that reject both logical request-id and run-id exposure.
- Routing Signals:
  - `review_rework_count=1`
  - `evidence_integrity_failure=false`
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with these raw findings and fresh verification evidence, then archive this pair and materialize the routed follow-up pair.
