113 lines
6.3 KiB
Markdown
113 lines
6.3 KiB
Markdown
---
|
|
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 생성.
|