<!-- task=m-iop-owned-single-request-agent-execution/06+05_stream_terminal plan=2 tag=API milestone-task=stream-terminal -->

# 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 every implementation-owned section below is filled in.
> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> Execute the plan's selected root cause, scope, files, and dependency decisions as written. Do not choose another owner, narrow/expand the write boundary, or replace a fix with another verification attempt.
> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields.
> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state.
> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.

## Overview

date=2026-08-06
task=m-iop-owned-single-request-agent-execution/06+05_stream_terminal, plan=2, tag=API

## Archive Evidence Snapshot

- Superseded pair: `plan_cloud_G09_1.log`, `code_review_cloud_G10_1.log`.
- The superseded pair contained no implementation evidence or review verdict; implementation has not started.
- Fresh-review correction: preserve the closed repair-aware projector scope, and replace the broad archive scan with the exact predecessor candidate pattern required by the split dependency protocol.

## For the Review Agent

> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section.

Compare implementation of each item against source files and verify that output in `Verification Results` matches code.
Review completion means the following steps are finished:

1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals.
2. Archive `CODE_REVIEW-cloud-G10.md` → `code_review_cloud_G10_2.log` and `PLAN-cloud-G09.md` → `plan_cloud_G09_2.log`.
3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS, preserve `milestone-task=stream-terminal` in `complete.log` and report it for runtime aggregation. Roadmap state evaluation belongs to `sync-milestone-workstate`.
5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting.

---

## Implementation Item Completion

| Item | Status |
|------|--------|
| API-1 Add a privacy-closed Anthropic stream projector | [x] |
| API-2 Pump coordinator progress and liveness on the same request | [x] |
| API-3 Synchronize SSE and compatibility contracts | [x] |

## Implementation Checklist

- [x] Implement a serialized single-request Anthropic SSE projector with one envelope, fixed plan/work/review/repair summaries, liveness ping, final text/error, and exactly-once terminal ownership.
- [x] Integrate it only with the marked coordinator stream, stop and join liveness before terminal/return, acknowledge service completion only after the one wire terminal succeeds, and prove one POST plus no private wire across fragmented multi-stage and repair events.
- [x] Preserve ordinary Anthropic/Hot Path behavior and synchronize the outer contract and current specs without expanding generic Stream Evidence Gate semantics.
- [x] Run dependency, exact-wire race, package, vet, full Edge/streamgate regression, and `git diff --check` verification.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent.
> Implementing agents must not modify or check this section.

- [x] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`.
- [x] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match.
- [x] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G10_2.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G09_2.log`.
- [x] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`.
- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files.
- [ ] If PASS, move active task directory `agent-task/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/` to `agent-task/archive/YYYY/MM/m-iop-owned-single-request-agent-execution/06+05_stream_terminal/` and update this checklist at the final archive path.
- [ ] If PASS, preserve and report `milestone-task=stream-terminal` for runtime aggregation, without modifying roadmap or directly calling `update-roadmap`.
- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-owned-single-request-agent-execution/` or verify it was kept due to remaining siblings/files.
- [x] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`.

## Deviations from Plan

- `apps/edge/internal/openai/single_request_handler_test.go` was not listed in the planned file summary, but its predecessor fixture sent `stream:true` while asserting the deferred buffered JSON behavior. The fixture was changed to exercise the unchanged non-streaming marked path, while `single_request_anthropic_stream_test.go` now owns the required streaming POST assertion. Without this one-line compatibility-fixture correction, the new `stream:true` contract and the mandatory full package regression would conflict.
- No live Claude/provider smoke was run. The plan and SDD evidence map leave that credentialed qualification to the later `claude-smoke` packet; this packet used the required deterministic coordinator, exact-wire, race, and handler POST evidence.

## Key Design Decisions

- The projector consumes only `SingleRequestProgress.Stage` and `SingleRequestResult.Output`. It ignores arbitrary progress messages/errors/results, exposes each planning/working/reviewing/repairing summary at most once, and rejects unknown stage values without writing them.
- One projector mutex owns `message_start`, all text block indices, pings, flush calls, and the exclusive success/error terminal. Terminal ownership is claimed before terminal bytes, so partial writes cannot be retried as an alternate terminal; every later call is a wire no-op returning the established result.
- The ping source is injected at the pump boundary. Production uses a 15-second ticker; deterministic tests use a manual channel. The pump stops and joins the ping worker before final/error output, cancellation return, or handler return.
- Marked `stream=true` requests use the new projector. Marked non-streaming behavior and ordinary Anthropic/Hot Path codecs remain unchanged. The new service-to-endpoint projection does not add generic Stream Evidence Gate events, filters, release rules, recovery, or observation semantics.
- Successful coordinator completion is acknowledged only after `message_stop` returns successfully. A short/failed terminal write is negatively acknowledged, and caller disconnect cancels execution without synthesizing a terminal after handler return.

## Reviewer Checkpoints

- Packet 05 completion evidence existed before implementation; packet 03's transitive public event types were reused.
- Closed progress includes defect/repair and rejects unknown/arbitrary strings.
- One lock owns block indices, pings, flushes, and terminal selection.
- Ping worker is stopped and joined before terminal/return; post-terminal bytes never change.
- Service completion is acknowledged only after `message_stop`; write failure/disconnect cannot also complete.
- Exact wire contains no reasoning, tool/provider/route/credential/workspace/raw-command sentinels.
- Ordinary Anthropic/Hot Path and Stream Evidence Gate behavior is unchanged.

## Verification Results

### Dependency

Command: `test -f agent-task/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log || test "$(compgen -G 'agent-task/archive/*/*/m-iop-owned-single-request-agent-execution/05+03_single_ingress/complete.log' | wc -l)" -eq 1`

_Actual output/status:_

```text
dependency_exit=0
```

Exit status: `0`. The active predecessor path was absent and exactly one matching archived `complete.log` candidate satisfied the split dependency.

### Exact-wire and terminal race

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

_Actual output:_

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

### Integration and compatibility

Command: `go test ./apps/edge/internal/openai -run 'Test(AnthropicSingleRequestStreaming|AnthropicSingleRequestStream|HotPathAnthropic)' -count=1`

_Actual output:_

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

### Documentation

Command: `rg --sort path -n 'single-request|repair|event: ping|message_start|message_stop|private|tool_use' agent-contract/outer/anthropic-compatible-api.md agent-spec/input/openai-compatible-surface.md agent-spec/runtime/stream-evidence-gate.md`

_Actual output:_

Exit status: `0`. The command returned matching lines from all three documents. Representative exact stdout covering the synchronized boundary was:

```text
agent-contract/outer/anthropic-compatible-api.md:115:coordinator execution. The projector opens exactly one `message_start` envelope and
agent-contract/outer/anthropic-compatible-api.md:122:- repair: `Repairing issues found during review.`
agent-contract/outer/anthropic-compatible-api.md:125:public progress blocks. `event: ping` may occur between `message_start` and the
agent-contract/outer/anthropic-compatible-api.md:129:`stop_reason="end_turn"` followed by exactly one `message_stop`. A coordinator failure
agent-contract/outer/anthropic-compatible-api.md:139:provider reasoning, `tool_use`/tool arguments/results, route/provider/credential
agent-contract/outer/anthropic-compatible-api.md:321:#### Marked single-request SSE subset
agent-spec/input/openai-compatible-surface.md:133:| marked single-request ingress | One validated and authorized Messages POST enters the separate service coordinator capability before legacy provider/caller continuation and increments `iop_anthropic_single_request_ingress_total` once. Non-streaming returns one buffered final-only message. Streaming keeps one envelope across the coordinator lifetime, exposes only fixed plan/work/review/repair text blocks plus `event: ping`, and commits one final text/error terminal. Internal reasoning/tool wire never becomes caller `tool_use`; success is acknowledged only after the complete terminal write succeeds. |
agent-spec/input/openai-compatible-surface.md:217:- A marked single-request Messages dispatch requires the narrow service coordinator capability and never falls back to the generic provider pool. The handler copies the immutable binding and request input and counts the accepted HTTP admission once with no labels. The non-streaming path exposes only the final sanitized output. The streaming path maps the closed coordinator enum to fixed plan/work/review/repair summaries, serializes pings and monotonic text-block indices with one terminal owner, stops and joins liveness before terminal/return, and acknowledges completion only after `message_stop`. Arbitrary progress, reasoning, tool/provider/credential/workspace data, and internal stage terminals stay private. Caller disconnect cancels execution without post-disconnect output. Missing capability and runtime failures use sanitized same-request errors. Count-tokens does not enter or increment this path.
agent-spec/runtime/stream-evidence-gate.md:64:| separate marked Anthropic projection | The single-request coordinator's fixed plan/work/review/repair summaries, `event: ping`, content indices, and endpoint terminal are owned by a separate serialized service-to-endpoint projector. They do not become normalized gate events, filters, release decisions, or recovery inputs. |
agent-spec/runtime/stream-evidence-gate.md:112:- Marked single-request Anthropic progress consumes only the coordinator's closed public enum in its endpoint projector. Its pings and terminal lock do not pass through the Core registry, mutate request-start gate snapshots, or enable generic filters/recovery.
```

### Final regression

Commands:

- `go test -race ./apps/edge/internal/openai -count=1`
- `go vet ./apps/edge/...`
- `go test ./apps/edge/... ./packages/go/streamgate/... -count=1`
- `git diff --check`

_Actual output:_

```text
$ go test -race ./apps/edge/internal/openai -count=1
ok  	iop/apps/edge/internal/openai	13.435s

$ go vet ./apps/edge/...
(no stdout/stderr; exit 0)

$ go test ./apps/edge/... ./packages/go/streamgate/... -count=1
ok  	iop/apps/edge/cmd/edge	0.162s
ok  	iop/apps/edge/internal/authprojection	0.042s
ok  	iop/apps/edge/internal/bootstrap	0.463s
ok  	iop/apps/edge/internal/configrefresh	0.094s
ok  	iop/apps/edge/internal/controlplane	6.622s
ok  	iop/apps/edge/internal/edgecmd	0.107s
ok  	iop/apps/edge/internal/edgevalidate	0.068s
ok  	iop/apps/edge/internal/events	0.049s
ok  	iop/apps/edge/internal/input	0.103s
ok  	iop/apps/edge/internal/input/a2a	0.067s
ok  	iop/apps/edge/internal/node	0.072s
ok  	iop/apps/edge/internal/openai	7.978s
ok  	iop/apps/edge/internal/opsconsole	0.041s
ok  	iop/apps/edge/internal/service	5.981s
ok  	iop/apps/edge/internal/transport	4.794s
ok  	iop/packages/go/streamgate	0.882s

$ git diff --check
(no stdout/stderr; exit 0)
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required |
| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only |
| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section |
| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content |
| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan |
| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry |
| Code Review Result | Review agent appends | Not included in stub |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Fail — the projector treats an undelivered terminal flush as a successful wire terminal and acknowledges coordinator completion.
  - Completeness: Fail — API-2's terminal-success ownership is incomplete for flush failures.
  - Test Coverage: Fail — terminal write failure coverage exercises `Write` failure only and does not exercise the supported `FlushError` path.
  - API Contract: Fail — the marked SSE contract requires negative acknowledgement when the complete terminal cannot be committed.
  - Code Quality: Pass — the implementation is otherwise isolated, serialized, and free of unrelated debug/dead-code changes in this packet.
  - Implementation Deviation: Fail — reusing the generic `writeDirectAnthropicEvent` helper also reused its error-blind `http.Flusher.Flush()` behavior, contrary to the plan's stronger terminal-commit invariant.
  - Verification Trust: Pass — all claimed commands were rerun successfully and their reported outputs are credible; the defect is a missing case rather than fabricated evidence.
  - Spec Conformance: Fail — SDD S03 and the terminal state invariant require one successfully committed final terminal before `completed`.
- Findings:
  - Required R1 — `apps/edge/internal/openai/single_request_anthropic_stream.go:196`: every projector event is flushed through `writeDirectAnthropicEvent`, whose `http.Flusher.Flush()` cannot return an error. Consequently `Final` returns nil and `pumpSingleRequestAnthropicStream` calls `AcknowledgeTerminal(true)` even when the writer exposes `FlushError() == io.ErrClosedPipe`; a focused reviewer reproducer failed with `pump error=<nil>, want flush failure`. Add a projector-owned error-reporting flush path (for example `http.NewResponseController(w).Flush()` or an equivalent injectable abstraction), propagate flush failures from all event writes, preserve terminal ownership after a partial/failed flush, and add a deterministic terminal-flush-failure test that proves the execution ends `failed` rather than `completed`.
- Routing Signals:
  - review_rework_count=1
  - evidence_integrity_failure=false
- Next Step: Prepare and execute the smallest routed follow-up plan that resolves Required R1, then rerun the focused flush-failure, race, package, vet, regression, and diff checks.
