# Milestone: OpenAI-compatible Runtime Output Integrity Filter

## 위치

- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../PHASE.md)

## 목표

OpenAI-compatible provider 응답에서 절대 정상 완료로 인정하면 안 되는 terminal output 형태를 공통 runtime filter pipeline으로 관리한다.
기본 invariant는 terminal assistant 응답이 user-visible content, valid tool call, 또는 명시적으로 허용된 structured/error finish 중 하나를 반드시 가져야 한다는 것이다.
이 Milestone은 LLM 의미 판단이 아니라 deterministic detector와 bounded retry/action policy를 묶는 상위 설계 스케치이며, 정책이 닫히기 전까지 구현 계획과 코드 구현 대상으로 삼지 않는다.

## 상태

[스케치]

## 승격 조건

- [ ] terminal assistant invariant를 확정한다. 예: content, valid tool call, allowed structured/error finish 중 하나가 없으면 정상 완료가 아니다.
- [ ] detector별 violation taxonomy를 확정한다. 예: `empty_terminal_response`, `reasoning_only_terminal`, `incomplete_tool_call_syntax`, `malformed_tool_call_emit`, `repeat_loop`, `schema_contract_violation`.
- [ ] 각 detector가 반환할 공통 결과 형태를 확정한다. 예: `pass`, `retryable_violation`, `fatal_violation`, `observe_only`.
- [ ] bounded retry 정책을 확정한다. 예: max attempt, same violation 반복 시 fatal, retry 내부 재귀 금지, tool side-effect 이후 retry 금지.
- [ ] streaming boundary를 확정한다. 예: first byte 전 buffer가 필요한 rule, 이미 downstream으로 보낸 content를 되돌릴 수 없는 rule, continuation repair가 가능한 rule.
- [ ] 기존 [OpenAI-compatible 출력 검증 필터](openai-compatible-output-validation-filters.md)와 [OpenAI-compatible Incomplete Tool Call Syntax Gate](openai-compatible-incomplete-tool-call-syntax-gate.md)를 통합할지, 공통 interface만 공유할지 결정한다.
- [ ] OpenAI-compatible stream/retry/error 계약 변경으로 승격할 때 SDD 필요 여부와 후속 구현 Milestone 분리 방식을 결정한다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 문서: 없음
- SDD 사유: 현재 Milestone은 runtime filter 통합 정책 스케치이며, public API/stream/retry/error 계약 구현으로 승격할 때 SDD 필요 여부를 재판정한다.
- 잠금 해제 조건: 아래 체크리스트
  - [ ] 승격 조건의 invariant, detector taxonomy, action policy가 해소되어 있다.
  - [ ] detector별 retry 가능 여부와 fatal 처리 기준이 문서화되어 있다.
  - [ ] 기존 output validation/filter Milestone과의 중복/통합 경계가 정리되어 있다.
- 결정 필요: 아래 체크리스트
  - [ ] "재귀"를 허용하지 않고 bounded retry로만 표현할지 결정한다.
  - [ ] `empty_terminal_response`와 `reasoning_only_terminal`을 기본 retryable로 볼지 fatal로 볼지 결정한다.
  - [ ] `incomplete_tool_call_syntax`를 retryable로 볼지 invalid-provider-output으로 볼지 결정한다.
  - [ ] provider/model/environment별 rule enablement를 config/registry로 둘지 hard invariant로 둘지 결정한다.
  - [ ] retry 실패를 client-visible error로 노출할지, provider output error event/metadata/log only로 둘지 결정한다.

## 범위

- OpenAI-compatible Chat Completions provider stream의 terminal response integrity 검사
- deterministic detector pipeline과 detector 결과 taxonomy
- terminal assistant invariant: content, valid tool call, allowed structured/error finish
- empty terminal, reasoning-only terminal, incomplete tool-call syntax, malformed tool-call, repeat-loop, schema-contract detector의 공통 관리 후보
- bounded retry/action policy와 retry loop guard
- Edge 실행 로그와 smoke evidence에 남길 integrity filter observation 필드

## 기능

### Epic: [integrity-filter] Runtime Output Integrity Filter

deterministic output integrity rule을 개별 one-off gate가 아니라 공통 runtime filter pipeline으로 관리하는 산출물을 묶는다.

- [ ] [invariant-catalog] terminal assistant 응답이 정상 완료로 인정되기 위한 최소 invariant와 allowed exception 목록이 정리되어 있다.
- [ ] [detector-contract] detector interface가 입력 observation, 결과 enum, evidence field, retryability, severity를 공통 형태로 반환하도록 정의되어 있다.
- [ ] [detector-set] `empty_terminal_response`, `reasoning_only_terminal`, `incomplete_tool_call_syntax`, `malformed_tool_call_emit`, `repeat_loop`, `schema_contract_violation`의 초기 detector 후보가 정리되어 있다.
- [ ] [action-policy] `retryable_violation`, `fatal_violation`, `observe_only`별 action과 bounded retry 제한, same-violation 반복 처리, side-effect 이후 retry 금지 조건이 정리되어 있다.
- [ ] [stream-boundary] first-byte buffer가 필요한 rule과 streaming passthrough/continuation repair가 가능한 rule이 분리되어 있다.
- [ ] [integration-map] 기존 output validation filter, incomplete tool-call syntax gate, LLM judge gate와의 선후 관계와 중복 제거 방식이 정리되어 있다.
- [ ] [ops-evidence] filter 결과가 model/provider/run id, assembled counts, detector evidence, retry attempt, final action과 함께 로그/observation으로 남는 기준이 정리되어 있다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 스케치 Milestone이며 invariant와 action policy가 아직 확정되지 않았다.
- 검토 항목: 사용자 리뷰 통과, 승격 조건 충족, 후속 구현 Milestone 및 SDD gate 분리 여부
- agent-ui 상태 반영: 해당 없음
- 리뷰 코멘트: 없음

## 범위 제외

- LLM judge를 이용한 tool 필요 여부 의미 판단
- 무제한 재귀 retry 또는 recursive repair loop
- 이미 downstream으로 보낸 content를 되돌리거나 덮어쓰는 방식
- 모델 교체, Pi prompt 변경, provider option 변경
- 개별 detector 구현 코드 작성
- output integrity와 무관한 routing/model selection 정책

## 작업 컨텍스트

- 관련 경로: `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/node/internal/adapters/openai_compat`, [openai-compatible-api.md](../../../../agent-contract/outer/openai-compatible-api.md)
- 표준선(선택): 이 filter 계층은 "모델이 의미적으로 tool을 써야 했는가"가 아니라 "terminal output이 runtime invariant를 만족하는가"를 deterministic하게 판단한다.
- 표준선(선택): 재시도는 재귀가 아니라 bounded retry로 표현한다. retry 내부에서 같은 integrity filter가 다시 retry를 중첩 호출하지 않는다.
- 표준선(선택): detector는 독립 모듈로 두고, retry/fatal/observe action은 중앙 policy가 결정한다.
- 선행 작업: [OpenAI-compatible 출력 검증 필터](openai-compatible-output-validation-filters.md), [OpenAI-compatible Incomplete Tool Call Syntax Gate](openai-compatible-incomplete-tool-call-syntax-gate.md)
- 후속 작업: detector별 implementation Milestone 또는 기존 output validation filter Milestone 통합
- 확인 필요: `구현 잠금 > 결정 필요` 항목
