rara/agent-roadmap/sdd/platform-foundation/integration-catalog-and-secrets/SDD.md

SDD: Integration 카탈로그와 Secret 경계

위치

• Milestone: Milestone 문서
• Phase: PHASE.md

상태

[승인됨]

SDD 잠금

• 상태: 해제
• 사용자 리뷰: 없음
• 잠금 항목:
  • 없음

문제 / 비목표

• 문제: 제품 중립 port는 존재하지만 integration instance의 수명주기, manifest 호환성, secret resolution과 runtime binding 규칙이 아직 실행 가능한 계약으로 연결되지 않았다.
• 비목표:
  • runtime Go plugin과 임의 바이너리 설치
  • secret vault 제품 자체 구현
  • vendor request·response 타입의 공통 계약 노출

Source of Truth

영역	기준	메모
Roadmap	Milestone 문서	범위와 완료 상태 원장
Code	Integration ports	제품 중립 capability 계약
External Provider	없음	provider별 adapter는 이 계약을 구현한다
User Decision	없음	secret reference와 compile-time registry 방향이 확정되어 있다

State Machine

상태	진입 조건	다음 상태	근거
configured	instance와 config·secret_ref가 저장됨	validated, invalid	control-plane mutation
validated	manifest와 config schema가 호환됨	active, disabled, invalid	conformance 결과
active	factory binding과 필수 health가 통과함	disabled, invalid	activation event
disabled	운영자 또는 정책이 비활성화함	validated	revision update
invalid	schema·capability·secret binding이 실패함	configured, validated	validation evidence

Interface Contract

• 계약 원문: Integration ports
• 입력:
  • project_id: integration을 소유하는 project
  • kind, implementation, schema_version: factory와 manifest identity
  • config: secret 원문이 없는 adapter 설정
  • secret_ref: runtime resolver에 전달할 opaque reference
• 출력:
  • capabilities: 검증된 versioned capability
  • binding: 요청 범위에서 사용할 typed adapter
  • health: 활성화와 readiness에 사용할 상태
• 금지:
  • config, log, trace, error에 secret 원문을 저장하지 않는다.
  • capability가 맞지 않는 adapter를 fallback으로 암묵 선택하지 않는다.
  • 특정 vendor 타입을 control-plane이나 RAG 공개 계약으로 노출하지 않는다.

Acceptance Scenarios

ID	Milestone Task	Given	When	Then
S01	catalog-lifecycle	project와 유효한 instance revision	create·update·disable 요청	revision과 상태가 project 범위에서 조회된다
S02	manifest-validation	호환·비호환 manifest와 config	활성화 검증	호환 항목만 validated로 전이한다
S03	secret-resolution	secret_ref가 있는 instance	runtime binding	resolver가 요청 시점에만 secret을 제공하고 원문이 영속화되지 않는다
S04	runtime-binding	active instance와 factory registry	adapter 요청	kind·version·capability가 일치하는 typed adapter만 반환한다
S05	conformance-suite	fake와 최소 실제 adapter	port conformance 실행	동일 필수 시나리오를 통과한다
S06	adapter-telemetry	성공·실패 provider 호출	metric·trace 수집	capability identity와 오류 등급은 남고 secret은 남지 않는다

Evidence Map

Scenario	Required Evidence	agent-task 연결	완료 Evidence 기대
S01	control-plane integration lifecycle test	agent-task/m-integration-catalog-and-secrets/...	catalog-lifecycle 완료와 revision evidence
S02	manifest·config validation matrix	agent-task/m-integration-catalog-and-secrets/...	manifest-validation pass·reject evidence
S03	secret persistence·log negative test	agent-task/m-integration-catalog-and-secrets/...	secret-resolution redaction evidence
S04	capability binding unit·integration test	agent-task/m-integration-catalog-and-secrets/...	runtime-binding fail-closed evidence
S05	fake·실제 adapter conformance 결과	agent-task/m-integration-catalog-and-secrets/...	conformance-suite provider matrix
S06	telemetry snapshot과 secret scan	agent-task/m-integration-catalog-and-secrets/...	adapter-telemetry metric·trace evidence

Cross-repo Dependencies

• 없음

Drift Check

• Milestone 기능 Task와 Acceptance Scenario가 일치한다.
• Evidence Map이 code-review/complete.log에서 검증 가능하다.
• agent-contract 원문을 SDD에 복제하지 않았다.
• 사용자 리뷰가 필요한 항목이 없다.

사용자 리뷰 이력

• 없음

작업 컨텍스트

• 표준선: compile-time registry, versioned manifest, fail-closed binding, secret reference
• 후속 SDD: 수집과 Dataset 수명주기, Index 게시와 Release 수명주기