53 lines
3.2 KiB
Markdown
53 lines
3.2 KiB
Markdown
---
|
|
domain: integrations
|
|
last_rule_review_commit: unborn-head
|
|
last_rule_updated_at: 2026-07-23
|
|
---
|
|
|
|
# integrations
|
|
|
|
## 목적 / 책임
|
|
|
|
Ariadne가 소유하는 외부 오류 입력과 IOP 실행 경계를 버전 계약으로 정의하고, 외부 실행 계층이 도메인·권한 경계를 침범하지 못하도록 요청과 이벤트를 검증한다.
|
|
|
|
## 포함 경로
|
|
|
|
- `internal/integration/iop/` — LLM·CLI 작업의 실행, 이벤트 스트림, 취소를 위한 Ariadne 소유 인터페이스다.
|
|
- `contracts/error-event/` — 외부 시스템이 전송하는 오류 이벤트 JSON Schema다.
|
|
- `contracts/execution-failure/` — 처리 실패 원인 스택의 JSON Schema다.
|
|
- `contracts/iop-execution/` — IOP 실행 요청과 상태 이벤트의 버전별 JSON Schema다.
|
|
|
|
## 제외 경로
|
|
|
|
- `internal/domain/` — 오류와 수정 작업의 내부 의미와 불변 규칙은 domain-model 책임이다.
|
|
- `internal/platform/httpserver/` — Ariadne HTTP 프로세스의 수명주기와 라우팅은 platform 책임이다.
|
|
- `internal/platform/database/` — 계약 데이터의 영속화와 조직 격리는 platform 책임이다.
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `iop.Executor` — 실행 시작, 조직 범위 이벤트 조회, 취소를 추상화한 Ariadne 소유 포트다.
|
|
- `iop.Request` — 오류, 저장소, 읽기 전용 실행 환경, 실행 정책과 deadline을 묶는 요청이다.
|
|
- `iop.Event` — 순서 번호와 단일 타입별 payload를 갖는 실행 이벤트다.
|
|
- `contracts/*/v1/*.json` — 외부 wire format의 v1 기준 문서다.
|
|
|
|
## 유지할 패턴
|
|
|
|
- 계약은 버전 디렉터리와 `schema_version`을 함께 사용하고 기존 버전을 제자리에서 깨지 않는다.
|
|
- `Request.Validate`에서 조직·프로젝트·입력 출처 범위가 오류 이벤트 범위와 일치하는지 확인한다.
|
|
- 분석 요청은 읽기 전용 저장소 접근만, 변경 요청은 격리된 작업 가지 접근만 허용한다.
|
|
- 실행 환경은 항상 읽기 전용이고 `AllowMerge`는 항상 거부한다.
|
|
- 변경 요청은 승인 또는 정책이 허용한 `ProposalDigest`를 요구하고 분석 요청에는 digest를 넣지 않는다.
|
|
- 이벤트 타입별 payload는 정확히 하나만 허용하며 실패 payload는 domain-model의 표준 실패 검증을 통과해야 한다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **domain-model**: 내부 의미와 닫힌 값 집합을 재사용하되 IOP 네이티브 형식을 도메인 타입으로 만들지 않는다.
|
|
- **platform**: HTTP·설정·데이터베이스 어댑터가 이 포트를 조립하며 integrations는 원시 연결 풀을 소유하지 않는다.
|
|
- **client**: 화면에 필요한 상태는 Ariadne API를 통해 제공하고 클라이언트가 IOP에 직접 연결하지 않는다.
|
|
|
|
## 금지 사항
|
|
|
|
- 조직 식별자, 비밀값, endpoint를 입력 본문이나 LLM payload의 임의 값으로 신뢰하지 않는다.
|
|
- IOP에 운영 환경 쓰기 권한이나 직접 병합 권한을 표현하거나 전달하지 않는다.
|
|
- 분석 요청에 격리 가지 쓰기 권한을 주거나 변경 요청을 기본 가지에서 실행하지 않는다.
|
|
- 계약 변경과 Go 경계 타입 변경을 서로 검증하지 않은 채 따로 반영하지 않는다.
|