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

# Bounded raw-free Hot Path observation schema

## For the Implementing Agent

구현 후 `CODE_REVIEW-cloud-G07.md`의 구현 담당 섹션에 실제 변경·검증 출력을 채우고 active 파일을 유지한다. 차단 시 정확한 blocker와 재개 조건만 기록하며 archive/`complete.log` 작성이나 상태 판정은 하지 않는다.

## Background

Hot Path lifecycle 관측을 연결하기 전에 log field와 metric label의 허용 집합을 닫아야 한다. 이 child는 기존 `Server.obsSink` Stream Gate contract를 변경하지 않고 별도 internal observer를 초기화하며, 고카디널리티 correlation은 log-only로 제한한다.

## Archive Evidence Snapshot

- 이전 active plan/review pair는 구현 전에 source reanalysis로 대체됐다. 구현 evidence와 verdict는 없다.

## 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/usage_metrics.go`
- `apps/edge/internal/openai/filter_observation_sink.go`
- `apps/edge/internal/openai/hot_path_dispatch.go`
- `agent-test/local/rules.md`

### SDD Criteria

- 승인 SDD S15: request/preset/mode/stage/attempt/route/terminal/cleanup/orphan을 상호연결하되 raw prompt/output/tool/header/credential/error와 unbounded metric label을 내보내지 않는다.

### Verification Context

- in-memory observer/collector와 seeded secret/raw sentinels로 deterministic하게 닫는다. 외부 telemetry backend는 필요 없다.

### Test Coverage Gaps

- Hot Path 전용 closed enums, log projection allowlist, metric label allowlist/cardinality budget, observer failure isolation을 검증하는 schema test가 없다.

### Symbol References

- public rename/remove 없음. 기존 `Server.obsSink` 타입/역할은 보존하고 새 field는 Hot Path internal observer만 담당한다.

### Split Judgment

- stable contract: typed lifecycle observation → bounded log/metric projection. 실제 lifecycle emit wiring은 child 19다.

### Scope Rationale

- dispatch/light/cleanup emit callsites, dashboard, backend, payload hashing/retention은 제외한다.

### Final Routing

- evaluation_mode=isolated-reassessment, finalizer=`finalize-task-policy.sh pair`.
- build scores=1/1/1/1/2, risks=`boundary_contract,variant_product`(2), local-fit → `PLAN-local-G06.md`.
- review → `CODE_REVIEW-cloud-G07.md`; `large_indivisible_context=false`, recovery=0/false.

## Implementation Checklist

- [ ] [API-1] Define a closed internal Hot Path observation contract, bounded log/metric projections, safe default observer, and failure isolation without altering Stream Gate observation ownership.
- [ ] [API-2] Add exact schema, cardinality, raw/secret rejection, and observer failure tests.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] Observation contract and projections

**Problem:** generic observation helpers do not express Hot Path stage/terminal/cleanup lifecycle or prevent accidental high-cardinality metric labels.

**Solution:** Add closed internal enums/types for event class, mode, stage, attempt bucket, route reason, disposition, cleanup/orphan outcome, and duration/usage buckets. Define separate projection functions: logs may include bounded keys plus correlation ids; metrics may include only closed enum/bucket labels and must exclude request/stage/attempt/run/provider raw ids, content, headers, error strings, and credentials. Add an internal observer interface with no-op/default bounded implementation and test injection. Store it on `Server` under a distinct field while preserving `obsSink` unchanged; observer failures never affect request results.

**Modified Files and Checklist:**

- [ ] Add `apps/edge/internal/openai/hot_path_observation.go` with closed event types, log projection, observer interface, and no-op/bounded implementation.
- [ ] Add `apps/edge/internal/openai/hot_path_metrics.go` with metric projection, fixed label sets, and bounded collectors.
- [ ] Modify `apps/edge/internal/openai/server.go` to initialize/store the distinct Hot Path observer and expose an internal test seam without changing `Server.obsSink`.

**Test Strategy:** enumerate every enum/projection and compare exact keys/labels; inject panicking/erroring observers behind safe calls.

**Verification:** targeted API-2 command exits 0.

### [API-2] Schema safety evidence

**Problem:** conventions alone cannot guarantee raw-free fields or bounded labels.

**Solution:** Add exact allowlist tests, unknown-value normalization, fixed label cardinality, log-only correlation, seeded prompt/output/tool/header/token/error exclusion, and observer failure isolation. Verify metric labels never carry high-cardinality ids.

**Modified Files and Checklist:**

- [ ] Add `apps/edge/internal/openai/hot_path_observation_test.go` with schema/projection/failure tests.
- [ ] Record actual output in `agent-task/m-iop-hot-path-one-shot-execution/18+17_observation_schema/CODE_REVIEW-cloud-G07.md`.

**Test Strategy:** inspect projected maps/labels directly and fail on any non-allowlisted key/value.

**Verification:** run Final Verification; all commands exit 0.

## Dependencies and Execution Order

1. Directory dependency `17` must produce `agent-task/m-iop-hot-path-one-shot-execution/17+14,15,16_endpoint_error_matrix/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/server.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(ObservationSchema|ObservationRejectsRawValues|MetricLabels|ObserverFailureIsolation)'
go test -race -count=1 ./packages/go/streamgate ./packages/go/config ./apps/edge/internal/openai ./apps/edge/internal/service
git diff --check
```

Expected: exit 0, exact bounded projections, correlation ids only in logs, no raw/secret/high-cardinality metric labels, observer failure isolation.

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