<!-- task=m-iop-hot-path-one-shot-execution/05+02,04_request_coordinator plan=1 tag=API milestone-task=request-identity -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is not complete until item statuses, Deviations, Key Design Decisions, and actual verification output are filled. Then stop with active files and report ready. Blockers belong only in those evidence fields. Do not ask the user, create control state, classify next state, archive, or write `complete.log`; review owns finalization.

## Overview

date=2026-08-02
task=m-iop-hot-path-one-shot-execution/05+02,04_request_coordinator, plan=1, tag=API

## For the Review Agent

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

Compare source and Verification Results, append verdict/signals, archive the pair, and on PASS write `complete.log`, preserve metadata, archive the task directory, and update the final `.log` checklist. WARN/FAIL must create the exact next state.

## Implementation Item Completion

| Item | Status |
|------|---------|
| API-1 Build the bounded logical-request store and lineage fence | [x] |

## Implementation Checklist

- [x] Implement opaque request/call/stage identity, owner affinity, immutable lineage/toolset fingerprints, and bounded state.
- [x] Enforce one active transition and exactly-once expected-frontier consumption under races.
- [x] Run dependency, deterministic concurrency, race, vet, and diff verification exactly as written.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual notes and 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_G08_1.log`.
- [x] Archive the active plan to `plan_cloud_G07_1.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/05+02,04_request_coordinator/` and update this checklist there.
- [ ] On PASS preserve/report `milestone-task=request-identity` without direct roadmap mutation.
- [ ] On PASS remove the active parent only if no siblings/files remain.
- [x] On WARN/FAIL write the mandatory next state and no `complete.log`.

## Deviations from Plan

The reviewed predecessor tasks have already been finalized and moved from their active task directories to `agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/`. Therefore, the two plan-prescribed active-path dependency checks now exit 1 with no output. The exact archived predecessor `complete.log` files both exist and were read before implementation. A minimal `Server` field/accessor was added so the new coordinator is Edge-local and server-owned; endpoint handler integration remains deferred as planned.

## Key Design Decisions

The server owns one HTTP-handler-independent coordinator. It owns only payload-free Edge-local transient state, while a later handler task supplies endpoint-specific immutable prefixes and result frontiers. IDs use 144-bit URL-safe random material by default and injected ID/time sources in tests. The mutex covers validation and frontier consumption together, so an invalid or losing concurrent continuation cannot mutate the record. Lineage fingerprints are endpoint-tagged SHA-256 digests over canonical JSON; request history and tool schemas are stored only as digests.

## Reviewer Checkpoints

- IDs are server-generated, path-safe, collision-resistant, and never authorization secrets.
- Lineage/toolset/principal mutation and missing state change nothing.
- Exactly one concurrent resume consumes a frontier.

## Verification Results

### API-1 item verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestLogicalRequest'
```

_Actual stdout/stderr:_

```text
$ go test -race -count=1 ./apps/edge/internal/openai -run 'TestLogicalRequest'
ok   iop/apps/edge/internal/openai  1.075s
```

### Dependencies and common race

```bash
test -f agent-task/m-iop-hot-path-one-shot-execution/02+01_preset_generation/complete.log
test -f agent-task/m-iop-hot-path-one-shot-execution/04+02,03_preset_model_authorization/complete.log
go test -race -count=1 ./packages/go/streamgate ./apps/edge/internal/openai ./apps/edge/internal/service
```

_Actual stdout/stderr:_

```text
$ test -f agent-task/m-iop-hot-path-one-shot-execution/02+01_preset_generation/complete.log
exit 1 (no stdout/stderr; predecessor was finalized and archived)

$ test -f agent-task/m-iop-hot-path-one-shot-execution/04+02,03_preset_model_authorization/complete.log
exit 1 (no stdout/stderr; predecessor was finalized and archived)

$ test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/02+01_preset_generation/complete.log && test -f agent-task/archive/2026/08/m-iop-hot-path-one-shot-execution/04+02,03_preset_model_authorization/complete.log
exit 0

$ go test -race -count=1 ./packages/go/streamgate ./apps/edge/internal/openai ./apps/edge/internal/service
ok   iop/packages/go/streamgate              1.984s
ok   iop/apps/edge/internal/openai           8.824s
ok   iop/apps/edge/internal/service          6.990s
```

### Vet and diff

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

_Actual stdout/stderr:_

```text
$ go vet ./apps/edge/internal/openai
exit 0 (no output)

$ git diff --check
exit 0 (no output)
```

---

> **[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
- Dimension Assessment:
  - Correctness: Fail
  - Completeness: Fail
  - Test Coverage: Fail
  - API Contract: Fail
  - Code Quality: Fail
  - Implementation Deviation: Fail
  - Verification Trust: Fail
  - Spec Conformance: Fail
- Findings:
  - Required — `apps/edge/internal/openai/request_lineage.go:29`: Chat lineage is computed after lossy typed decoding. A fresh reviewer test showed that JSON Schema constraints `9007199254740992` and `9007199254740993` produce the same `ToolsetDigest`, because `Tools []any` has already converted both values through `float64`; the same typed path also discards non-text content blocks. Build the Chat lineage from bounded raw/canonical JSON decoded with `UseNumber` before lossy DTO conversion, isolate the committed immutable prefix from the new result frontier, and add Chat plus Anthropic canonicalization/mutation regression tests.
  - Required — `apps/edge/internal/openai/request_coordinator.go:227`: frontier validation checks duplicate public IDs but not duplicate provider IDs staged in the same batch, so two public IDs can map to one provider ID. The retained maps also allow a consumed public/provider pair to become a later expected frontier again. Reject batch-local provider duplicates and all previously consumed public/provider IDs before mutating the record, with tests for both same-frontier collisions and cross-frontier replay.
  - Required — `apps/edge/internal/openai/request_coordinator.go:214`: `Capacity` bounds only the number of request records; `expected`, `publicToProvider`, and `providerToPublic` remain unbounded per request, and `awaitToolResults` accepts an arbitrarily large frontier. Add explicit per-frontier and per-request mapping limits, reject over-limit input without mutation, and cover boundary/TTL capacity behavior with deterministic tests.
  - Required — `apps/edge/internal/openai/request_coordinator.go:384`: admission accepts an empty `PresetGeneration`, so the coordinator can create a request without the immutable preset-generation pin required by the plan and SDD. Require a non-empty generation and add positive/negative admission tests.
- Routing Signals:
  - `review_rework_count=2`
  - `evidence_integrity_failure=true`
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with these raw findings and the fresh reviewer evidence, then archive this pair and materialize the newly routed follow-up pair.
