<!-- task=m-iop-hot-path-one-shot-execution/18+17_observation_schema plan=1 tag=API milestone-task=route-observability -->

# Raw-free Hot Path observation schema

## For the Implementing Agent

구현 후 `CODE_REVIEW-cloud-G07.md`의 구현 담당 섹션에 실제 notes/output을 채우고 active 파일을 유지한다. 차단 시 정확한 blocker/시도/출력/재개 조건만 기록하며 사용자 질문, archive, `complete.log` 작성은 하지 않는다.

## Background

Hot Path lifecycle에는 request-correlated log와 low-cardinality metric을 위한 닫힌 schema가 없다. 이 child는 lifecycle wiring에 앞서 raw/secret을 받을 수 없는 typed event, enum, log projection, metric label surface를 정의한다.

## Analysis

### Files Read

- `agent-roadmap/sdd/knowledge-tool-optimization-extension/iop-hot-path-one-shot-execution/SDD.md`
- `apps/edge/internal/openai/server.go`
- `apps/edge/internal/openai/filter_observation_sink.go`
- `apps/edge/internal/openai/usage_metrics.go`
- `packages/go/streamgate/filter_observation.go`
- `agent-spec/runtime/stream-evidence-gate.md`
- `agent-test/local/rules.md`

### SDD Criteria

- 승인 SDD, `milestone-task=route-observability`, S15.
- exact log field allowlist, bounded metric labels, enum normalization, raw/secret absence가 이 child의 oracle이다.

### Verification Context

- zap observer와 isolated Prometheus collector를 사용하는 deterministic tests로 닫는다.

### Test Coverage Gaps

- Hot Path typed observation schema와 metric label allowlist 자체를 검증하는 tests가 없다.

### Symbol References

- existing `Server.obsSink`/`streamgate.FilterObservation` contract is not changed.

### Split Judgment

- stable contract: closed Hot Path observation event → log/metric allowlist projections.
- stage lifecycle wiring and correlation are child 19.
- endpoint terminal outcomes must be fixed by predecessor 17.

### Scope Rationale

- dispatch/light/cleanup emission points, backend/dashboard/alert, durable store, raw hashing are excluded.

### Final Routing

- evaluation_mode=isolated-reassessment, finalizer=`finalize-task-policy.sh pair`.
- build closures 모두 true, scores=1/1/1/1/2, G06, local-fit → `PLAN-local-G06.md`.
- review closures 모두 true, scores=1/1/1/2/2, G07, official-review → `CODE_REVIEW-cloud-G07.md`.
- risks=`boundary_contract,variant_product`(2), `large_indivisible_context=false`, recovery=0/false, capability gap 없음.

## Implementation Checklist

- [ ] [API-1] Add closed Hot Path observation enums and separate raw-free log/low-cardinality metric projections without arbitrary payload maps or strings.
- [ ] [API-2] Add exact log-field and metric-label allowlist plus redaction guard tests and run the child verification commands.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] Closed observation and metric schema

**Problem:** ad-hoc logging can leak payloads and metrics can accidentally acquire high-cardinality identifiers.

**Solution:** Add `hotPathObservation` with closed enum fields for preset/mode/endpoint/stage/route/outcome/cleanup responsibility plus explicit log-only correlation identifiers. Add typed log projection and dedicated counter/histogram collectors whose bounded labels exclude request/stage/attempt/provider/run ids. Reject arbitrary maps and raw prompt/output/tool/header/credential/error strings.

**Modified Files and Checklist:**

- [ ] Add `apps/edge/internal/openai/hot_path_observation.go` with closed event/enum types and log projection.
- [ ] Add `apps/edge/internal/openai/hot_path_metrics.go` with bounded-label counters/histograms.

**Test Strategy:** API-2 compares exact sorted field/label sets and sentinel absence.

**Verification:** `go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(ObservationFieldAllowlist|MetricLabelAllowlist|ObservationRejectsRawValues)'` exits 0.

### [API-2] Schema allowlist evidence

**Problem:** S15 needs positive allowlist and negative raw-data evidence before lifecycle emission is wired.

**Solution:** Capture projected zap fields and Prometheus descriptors. Assert exact key/label names, log-only high-cardinality ids, enum normalization, and absence of seeded prompt/output/tool/header/credential/error sentinel values.

**Modified Files and Checklist:**

- [ ] Add `apps/edge/internal/openai/hot_path_observation_test.go` with field allowlist, metric label allowlist, and raw-value rejection tests.
- [ ] Fill `agent-task/m-iop-hot-path-one-shot-execution/18+17_observation_schema/CODE_REVIEW-cloud-G07.md`.

**Test Strategy:** use isolated observers/collectors; no external metrics backend.

**Verification:** run Final Verification; all exact allowlist assertions pass.

## Dependencies and Execution Order

1. `17+14,15,16_endpoint_error_matrix` must produce its active `complete.log`.
2. Implement API-1, then API-2.

## Modified Files Summary

| File | Item |
|---|---|
| `apps/edge/internal/openai/hot_path_observation.go` | API-1 |
| `apps/edge/internal/openai/hot_path_metrics.go` | API-1 |
| `apps/edge/internal/openai/hot_path_observation_test.go` | API-2 |
| `agent-task/m-iop-hot-path-one-shot-execution/18+17_observation_schema/CODE_REVIEW-cloud-G07.md` | API-2 |

## Final Verification

```bash
go test -race -count=1 ./apps/edge/internal/openai -run 'TestHotPath(ObservationFieldAllowlist|MetricLabelAllowlist|ObservationRejectsRawValues)'
go test -race -count=1 ./apps/edge/internal/openai
git diff --check
```

Expected: exit 0, exact allowlists, no high-cardinality metric labels or raw/secret sentinels, empty diff check. Cached output is not acceptable.

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
