iop/agent-spec/runtime/stream-evidence-gate.md

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

주요 흐름

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 생성.