---
spec_doc_type: spec
spec_id: runtime/stream-evidence-gate
status: 구현됨
source_evidence:
  - type: contract
    path: agent-contract/outer/openai-compatible-api.md
    notes: OpenAI-compatible ingress, stream commit와 terminal 오류 계약
  - type: contract
    path: agent-contract/inner/edge-config-runtime-refresh.md
    notes: Stream Evidence Gate 설정과 restart-required 분류 계약
  - type: code
    path: packages/go/streamgate/runtime.go
    notes: request-local event, evaluation, release와 recovery lifecycle
  - type: code
    path: packages/go/streamgate/recovery_coordinator.go
    notes: abort, optional prepare, rebuild, budget consume와 single dispatch 순서
  - type: code
    path: apps/edge/internal/openai/stream_gate_runtime.go
    notes: OpenAI Chat과 provider tunnel host wiring
  - type: code
    path: apps/edge/internal/openai/openai_request_rebuilder.go
    notes: bounded lossless OpenAI request rebuild
  - type: test
    path: packages/go/streamgate/runtime_test.go
    notes: Core lifecycle, recovery와 terminal 검증
  - type: test
    path: apps/edge/internal/openai/stream_gate_vertical_slice_test.go
    notes: Edge 실제 admission과 full-cycle 검증
  - type: test
    path: apps/edge/internal/openai/filter_observation_sink_test.go
    notes: raw-free observation allowlist와 correlation 검증
---

# 스펙: Stream Evidence Gate

## 목적

codec이 정규화한 provider event를 downstream에 쓰기 전에 evidence와 모든 활성 filter 결과를 확인하고, 한 번의 release·terminal·recovery 결정으로 수렴시키는 현재 request-local runtime을 설명한다.

## 기능 목록

| 기능 | 설명 |
|------|------|
| normalized event contract | response-start, text/reasoning, tool-call, terminal, provider-error event와 base disposition을 transport와 분리한다. |
| evidence hold | 기본 500 Unicode rune rolling window와 bounded terminal/fragment gate를 사용하며 안전한 prefix만 release한다. |
| staged commit | status/header/opening event를 첫 safe release까지 보류하고 `transport_uncommitted`, `stream_open`, `terminal_committed` 상태에서 terminal을 한 번만 commit한다. |
| filter registry와 arbitration | request 시작의 registry/config generation을 고정하고 attempt별 active filter를 다시 해석한 뒤 병렬 결과를 모두 모아 deterministic action 하나를 선택한다. |
| bounded recovery | exact replay, continuation repair, schema repair는 request-total·strategy별 fault cap 안에서 실행하며 managed continuation은 별도 trajectory budget을 사용한다. |
| request rebuild | 기본값이자 절대 상한 16 MiB의 ingress snapshot에서 OpenAI JSON unknown field를 보존하고 필요한 typed subtree만 bounded patch한다. |
| host re-admission | 현재 provider ownership을 닫은 뒤 optional one-shot prepare, rebuild, budget consume, 단일 dispatch 순서로 새 actual model/provider/path binding을 설치한다. |
| raw-free observation | request correlation, attempt/epoch, filter/rule, decision, recovery와 bounded sanitized cause/evidence만 timeline sink로 보낸다. |

## 범위

- 포함: transport-agnostic Core, OpenAI-compatible Chat runtime, provider-pool mixed path, Chat/Responses streaming provider tunnel, request-local ingress/rebuild와 Edge observation sink.
- 제외: 반복·missing tool-call·schema 같은 semantic detector 자체, provider/model 선택 알고리즘, raw parser, cross-request 저장과 범용 오류 수정 workflow.

## 주요 흐름

```mermaid
sequenceDiagram
  participant Host as Edge host
  participant Core as Stream Gate Core
  participant Filters
  participant Provider
  participant Sink as Release sink

  Host->>Core: request snapshot + initial AttemptBinding
  Provider->>Core: normalized response-start/event
  Core->>Core: stage + evidence hold
  Core->>Filters: immutable EvidenceBatch 병렬 평가
  Filters-->>Core: all outcomes
  alt release 또는 terminal
    Core->>Sink: safe release / single terminal
  else recovery
    Core->>Provider: current attempt abort
    Core->>Host: optional prepare + bounded rebuild
    Host->>Provider: single re-admission
    Provider->>Core: next attempt events
  end
```

## 계약

- 외부 OpenAI-compatible 오류와 stream framing: `agent-contract/outer/openai-compatible-api.md`
- Edge 설정과 refresh 분류: `agent-contract/inner/edge-config-runtime-refresh.md`
- Edge-Node provider tunnel wire: `agent-contract/inner/edge-node-runtime-wire.md`

## 설정/데이터/이벤트

- `openai.stream_evidence_gate.enabled` 기본값은 `false`이며 활성화 시 지원 경로의 response lifecycle을 Core가 소유한다.
- `max_request_fault_recovery`는 0..3, `max_strategy_fault_recovery`는 0..request-total이고 생략 시 request-total을 상속한다.
- `max_ingress_snapshot_bytes`는 1..16777216이며 생략 시 16 MiB다. raw body limit은 첫 read 전에 적용되고 canonical body, typed view와 rebuild peak가 같은 request-local ledger에 포함된다.
- Stream Evidence Gate 설정 변경은 현재 restart-required다. request가 시작된 뒤 config/registry snapshot은 바뀌지 않는다.
- production Core registry는 공통 Noop filter와 적용 가능한 request-local tool validation을 포함한다. 추가 semantic filter는 별도 소비 Milestone이 등록한다.

## 검증

- `make proto` - generated protobuf가 현재 schema와 일치해야 한다.
- `go test -race -count=1 ./packages/go/streamgate ./apps/edge/internal/openai ./packages/go/config` - Core, Edge vertical cycle, request rebuild, observation과 config 경계가 통과해야 한다.
- `git diff --check` - 문서와 코드 diff에 공백 오류가 없어야 한다.

## 한계와 주의사항

- normalized `/v1/responses`는 현재 streaming을 지원하지 않으며 해당 non-stream path는 Stream Evidence Gate runtime을 사용하지 않는다.
- direct provider tunnel의 non-stream response는 기존 buffered passthrough 경로를 유지한다. ingress 상한은 runtime 활성 여부와 무관하게 적용된다.
- Core 활성화만으로 후속 semantic filter가 자동 활성화되지는 않는다.
- observation은 저장소가 아니라 event envelope이며 보존·조회 정책은 host observability sink가 소유한다.

## 변경 기록

- 2026-07-28: Stream Evidence Gate Core 완료 감사에서 현재 Core, Edge wiring, 계약과 테스트 근거로 targeted spec 생성.