<!-- task=m-iop-hot-path-one-shot-execution/10+07,09_light_flow plan=0 tag=API milestone-task=light-flow -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> Fill item statuses, deviations, decisions, and actual output, then stop with active files and report ready. Record blockers only in implementation evidence. Do not ask the user, create control state, classify, archive, or write `complete.log`; review owns finalization.

## Overview

date=2026-08-02
task=m-iop-hot-path-one-shot-execution/10+07,09_light_flow, plan=0, tag=API

## For the Review Agent

> **[REVIEW AGENT ONLY]** Implementers must not execute this section.

Compare source/evidence, append verdict/signals, archive the pair, and on PASS write `complete.log`, preserve metadata, archive the directory, and update the final `.log` checklist. WARN/FAIL must create the exact next state.
## Implementation Item Completion

| Item | Status |
|------|---------|
| API-1 Run the isolated local worker stage | [x] |
| API-2 Run one review write/resolution and optional repair | [x] |

## Implementation Checklist

- [x] Transition exact Plan/Review pair success into an immutable local stage with visible content/tool loops and terminal correlation.
- [x] Run one fixed cloud review stage through write, read-resolution, pass or defect repair, then stop at cleanup_pending without Edge file reads or a second review.
- [x] Run scripted flow, isolation, common race, vet, and diff verification exactly as written.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** Implementers must not modify or check this section.

- [x] Append one PASS/WARN/FAIL verdict with verified `review_rework_count` and `evidence_integrity_failure`.
- [x] Verify verdict, Dimension Assessment, and Required/Suggested/Nit classifications match.
- [x] Archive the active review to `code_review_cloud_G10_0.log`.
- [x] Archive the active plan to `plan_cloud_G10_0.log`.
- [x] Verify the Agent-Ops `.gitignore` block.
- [ ] On PASS write `complete.log` from `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md`.
- [ ] On PASS archive to `agent-task/archive/YYYY/MM/m-iop-hot-path-one-shot-execution/10+07,09_light_flow/` and update this checklist there.
- [ ] On PASS preserve/report `milestone-task=light-flow` without direct roadmap mutation.
- [ ] On PASS remove the active parent only if no siblings/files remain.
- [x] On WARN/FAIL create the mandatory next state without `complete.log`.

## Deviations from Plan

- The two dependency checks at their active paths exited 1 because the dispatcher had already archived both completed predecessor packets. The corresponding same-task-group archived `complete.log` files exist and both record PASS; no active dependency artifacts were recreated.
- Integration also required scoped edits to the existing coordinator, ingress, endpoint handlers, server wiring, artifact-pair handoff, and predecessor test fixtures so exact pair success can enter and resume the new local/review state machine. There was no behavioral scope expansion.

## Key Design Decisions

- Pin a request-local immutable snapshot of the caller task, tool contract, workspace mapping, execution preset, route bindings, and selector identity. Local and review inputs cross stage boundaries with only that task, the two issued paths, and committed provider correlations.
- Revalidate every managed local/review route and credential revision before dispatch, retain one local stage ID across its tool frontiers, and atomically replace it with one fixed review stage ID after a correlated local completion.
- Keep provider-native stage transcripts separate from public responses. Tool frontier lineage hashes are calculated from the exact public assistant response, while provider call IDs and result bodies are retained only in the same-stage transcript used for the next provider call.
- Drive review state from normalized structure only: one exact review write, one exact same-stage review read, then either completion or ordinary repair tools. Edge never reads a workspace file or parses verdict prose, reserved review re-entry is rejected during repair, and cleanup pending can be committed once.

## Reviewer Checkpoints

- Local/review inputs contain immutable task/correlation/paths, not file contents or credentials.
- Pair success starts one local stage and its committed terminal starts one fixed reviewer.
- Review write/read-resolution/repair stays one stage; only completion-versus-repair-tool structure decides the path, prose verdict words have no effect, and cleanup pending is reached once.

## Verification Results

Paste actual stdout/stderr below.

### API-1 item verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(LightLocal|StageInput)'
```

_Actual stdout/stderr:_

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

### API-2 item verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Review|Light)'
```

_Actual stdout/stderr:_

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

### Dependencies and focused race

```bash
test -f agent-task/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/complete.log
test -f agent-task/m-iop-hot-path-one-shot-execution/09+06,08_artifact_pair/complete.log
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Light|Review|StageInput)'
```

_Actual stdout/stderr:_

```text
$ test -f agent-task/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/complete.log
exit status 1
$ test -f agent-task/m-iop-hot-path-one-shot-execution/09+06,08_artifact_pair/complete.log
exit status 1

The dispatcher had already moved both completed packets to the archive. The
following same-task-group evidence checks exited 0 with no stdout, and both
completion logs record PASS:

$ test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/07+02,04,06_route_selector_direct/complete.log
$ test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/09+06,08_artifact_pair/complete.log

$ go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Light|Review|StageInput)'
ok  	iop/apps/edge/internal/openai	1.433s
```

### Common race tests

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

_Actual stdout/stderr:_

```text
ok  	iop/packages/go/streamgate	2.170s
ok  	iop/packages/go/config	1.583s
ok  	iop/apps/edge/internal/openai	9.889s
ok  	iop/apps/edge/internal/service	7.094s
```

### Vet and diff

```bash
go vet ./apps/edge/internal/openai
git diff --check
```

_Actual stdout/stderr:_

```text
$ go vet ./apps/edge/internal/openai
(no output; exit 0)
$ git diff --check
(no output; exit 0)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?** Leave review-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Fixed structure, item names/checklist/checkpoints/commands | Fixed | Do not rewrite |
| Item status, deviations, decisions, actual output | Implementer | Must complete |
| Review checklist and verdict/finalization | Review agent | Implementer must not modify |

## Code Review Result

### Overall Verdict

FAIL

The local/review state machine, fixed reviewer identity, structural review resolution, and deterministic verification all work as exercised. However, the committed selector/local correlations required at the cross-stage input boundary are validated only inside Edge state and are omitted from every provider-visible stage request. This is a required S08 input-contract gap.

### Dimension Assessment

| Dimension | Result | Assessment |
|---|---|---|
| Correctness | FAIL | Local and review providers receive the task and artifact paths but not the committed predecessor-stage correlations required to establish the stage transition context. |
| Completeness | FAIL | The stage-input structs carry the correlations, but the final prompt/request serialization drops them. |
| Test coverage | FAIL | The isolation test checks task/path presence and secret absence, while the scripted request assertions check stage identity only; neither proves selector/local correlations reach the outbound provider request. |
| API/contract | FAIL | The S08 input boundary and this review's checkpoint require immutable task, committed correlations, and issued paths at local/review input. The actual provider-visible input lacks the correlation component. |
| Code quality | PASS | The phase transitions and provider/public transcript separation are explicit and readable. |
| Implementation deviation | PASS | The reported coordinator, ingress, handler, wiring, and predecessor-fixture edits are necessary integration work and remain within the light-flow scope. |
| Verification trust | PASS | All claimed focused/race/vet/diff checks were reproduced successfully, both exact archived predecessor completion logs record PASS, and the supplemental full Edge suite passed after moving `TMPDIR` off the host's non-executable `/tmp`. |
| Spec conformance | FAIL | The implementation does not satisfy the SDD S08 requirement that local/review stage input include the committed predecessor-stage success/output correlation. |

### Findings

#### Required

1. Committed selector/local correlations never reach the local/review model input.
   - Evidence: `apps/edge/internal/openai/hot_path_stage_input.go:25` stores `SelectorCommit` and `LocalCommit`, and `validate` requires them, but `prompt` at `apps/edge/internal/openai/hot_path_stage_input.go:74` serializes only the immutable task, issued paths, and phase instruction. `submitHotPathStage` at `apps/edge/internal/openai/hot_path_dispatch.go:840` then builds the provider prompt, messages, input, and metadata from that reduced value; its metadata contains only the current logical request/stage identity, and `hotPathStageRunInput` at `apps/edge/internal/openai/hot_path_dispatch.go:1087` adds no predecessor correlation. Consequently, neither normalized nor tunnel dispatch exposes the selector commit to local, or the selector and local commits to review.
   - Impact: The actual stage boundary does not satisfy API-1, the reviewer checkpoint, or SDD S08. A local/review provider cannot correlate its work with the committed predecessor success/output that authorized the transition.
   - Fix: Serialize a safe, immutable correlation block into every provider-visible local/review request (selector commit for local; selector and local commits for review) across normalized and tunnel paths, without adding credentials, provider targets, file contents, or prior prompts. Extend `TestHotPathStageInputIsolation` and the scripted request assertions to inspect actual captured provider requests for the exact selector/local stage and response correlations, while continuing to assert forbidden data is absent.

#### Suggested

None.

#### Nit

None.

### Verification Performed

- `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(LightLocal|StageInput)'` - PASS (`1.412s`).
- `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Review|Light)'` - PASS (`1.585s`).
- `go test -count=1 ./apps/edge/internal/openai -run 'TestHotPath(Light|Review)'` - PASS (`0.186s`).
- `go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service` - PASS for all four packages.
- `go vet ./apps/edge/internal/openai` - PASS with no output.
- `gofmt -d` over the planned and reported integration files - PASS with no output.
- `git diff --check` - PASS with no output.
- `go test -count=1 ./apps/edge/...` - first attempt failed only because the host `/tmp` is non-executable; rerun with an isolated workspace-local `TMPDIR` passed every Edge package.
- Live provider/agent smoke - not run; the task explicitly scopes S08 verification to deterministic fake services and leaves live smoke to S16.

### Routing Signals

```text
review_rework_count=1
evidence_integrity_failure=false
```

### Next Step

Prepare and validate the mandatory follow-up plan that fixes the provider-visible correlation serialization and its outbound-request coverage, then archive this plan/review pair and materialize the next active pair. Do not write `complete.log`.
