# SDD: Integration 카탈로그와 Secret 경계

## 위치

- Milestone: [Milestone 문서](../../../phase/platform-foundation/milestones/integration-catalog-and-secrets.md)
- Phase: [PHASE.md](../../../phase/platform-foundation/PHASE.md)

## 상태

[승인됨]

## SDD 잠금

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

## 문제 / 비목표

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

## Source of Truth

| 영역 | 기준 | 메모 |
|------|------|------|
| Roadmap | [Milestone 문서](../../../phase/platform-foundation/milestones/integration-catalog-and-secrets.md) | 범위와 완료 상태 원장 |
| Code | [Integration ports](../../../../packages/go/integration/ports.go) | 제품 중립 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](../../../../packages/go/integration/ports.go)
- 입력:
  - `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

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

## 사용자 리뷰 이력

- 없음

## 작업 컨텍스트

- 표준선: compile-time registry, versioned manifest, fail-closed binding, secret reference
- 후속 SDD: [수집과 Dataset 수명주기](../../knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md), [Index 게시와 Release 수명주기](../../rag-serving/index-publication-and-release/SDD.md)