[AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현

[hywznn]

한 줄 목표

Server가 Prompt나 Provider를 직접 소유하지 않고, 비식별 요청을 별도 AI Runtime에
정확히 한 번 전달한 뒤 응답을 불신 경계에서 다시 검증합니다.

호출 경계

AiRunWorker (#24)
  → ValidatingAiRuntimeClient
    → RemoteAiRuntimeClient
      → POST /internal/v1/analyses (fowoco/ai)
        → Agent Pipeline → pinned Knowledge Bundle → LLM Provider

Server는 요청 최소화, 서비스 인증, deadline과 장애 격리, 응답의 최종 방어 검증을
소유합니다. Prompt·모델·Provider 연동은 fowoco/ai 책임입니다.

내부 요청 계약

• Header: Authorization: Bearer <service-credential>, X-Request-Id, 선택적 traceparent
• Body: requestId, attemptId, contractVersion, requiredKnowledgeVersion,
  deadlineMs, maskedInput
• Worker 정보: 원문 식별번호가 아닌 workerRef, language, stayExpiryDate,
  workStatus 등 최소 context

별도 Service-Authorization custom header는 사용하지 않습니다. 실제 외국인등록번호,
여권번호, 전화번호, 계좌번호, JWT, Worker Link token은 AI 경계로 보내지 않습니다.

내부 응답 계약

• requestId, outcome, candidates, validationErrors
• agentVersion, modelProvider, modelName, modelVersion
• promptVersion, contextPackVersion, workflowCatalogVersion, contractVersion
• providerAttemptCount, latencyMs

낮은 신뢰도와 누락정보는 기술 장애가 아니라 정상 NEEDS_INFO/REVIEW_REQUIRED
분석 결과입니다. HTTP·timeout·parsing 장애는 안전한 AiRuntimeFailureCode로 구분합니다.

Server 구현 현황

• AiRuntimeClient port와 Provider-neutral DTO
• FakeAiRuntimeClient — Server 단위·통합 테스트 전용
• RemoteAiRuntimeClient — Bearer service auth, request/trace propagation
• PII allow-list와 outbound request test
• 전체 deadline, connect timeout, circuit breaker, concurrency bulkhead
• strict JSON과 requestId 상관관계 재검증
• 대상 workerRef와 Server 기준 stay_expiry_date 보존 검증
• 지원하지 않는 contract/knowledge version 안전 실패
• version, latency와 안정적인 error code를 #24가 받을 수 있는 계약
• contract fixture와 WireMock integration test
• fowoco/ai 원본 OpenAPI·JSON Schema release 후 동일 version fixture 확인

구현 PR:

• feat: AI Runtime 연동 계약과 안전한 검증 기반 구현 #42 — Provider-neutral 계약, PII와 응답 검증 기반
• feat: AI Runtime HTTP 연결과 장애 격리 구현 #56 — 실제 HTTP Adapter, deadline·bulkhead·circuit breaker·WireMock

Retry 소유권

• Server: 영속 AiRun attempt 생성, 재시작 복구, 사용자 수동 retry, 전체 deadline/budget
• AI Runtime: 한 attempt 안에서만 제한된 Provider retry
• RemoteAiRuntimeClient는 투명한 HTTP retry를 하지 않습니다. 다시 호출하려면 #24가
  새로운 AiAttempt를 먼저 기록해야 합니다.

이 이슈에서 하지 않는 것

• Prompt/Context 조립, Agent Router, Intent 추출
• OpenAI/Gemini/Anthropic/LM Studio client
• 모델 선택·fallback·fine-tuning·evaluation runner
• Knowledge YAML/Schema 원본 소유
• Task 생성·승인·발송

위 항목은 각각 fowoco/ai, fowoco/knowledge, Server #24/#11의 책임입니다.

완료 조건

• Fake와 Remote를 바꿔도 Server application 계약이 같습니다.
• 민감정보가 outbound body, 일반 log, metric, exception에 포함되지 않습니다.
• 잘못된 JSON, 다른 requestId, 핵심 날짜 변경, 미지원 version을 거부합니다.
• Runtime timeout/429/5xx에서 호출 수와 대기 시간을 제한합니다.
• 서버 저장소에 Provider SDK/API Key/Prompt 전문이 없습니다.
• fowoco/ai의 versioned internal contract와 staging smoke test가 통과합니다.

관계

• 완료된 기반: [Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25
• [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8 완료 후 시작: [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24 AiRun/AiAttempt orchestration
• 외부 통합 조건: fowoco/ai internal contract, Knowledge release
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2