#API 안정성 계약

버전: 0.33.0 최종 업데이트: 2026-03-15 적용 대상: ranvier-core, ranvier-runtime, ranvier-http, ranvier-macros 카테고리: Architecture

이 문서는 Ranvier 공개 API의 안정성 보장, 동결 범위, 폐기 정책을 정의합니다. 현재 v0.33 릴리스에 적용되며 향후 v1.0에 대한 계약을 수립합니다.

#1. 핵심 패러다임 (동결됨)

다음 네 가지 프리미티브는 Ranvier의 타협 불가한 기반입니다. 이들은 동결되었으며 호환성을 깨뜨리는 변경을 받지 않습니다:

#Transition

핵심 실행 트레이트입니다. 모든 비즈니스 로직은 Transition을 통해 흐릅니다.

#[async_trait]
pub trait Transition<I, O>: Send + Sync {
    type Error: Send + Sync;
    type Resources: Send + Sync;

    async fn run(
        &self,
        input: I,
        resources: &Self::Resources,
        bus: &mut Bus,
    ) -> Outcome<O, Self::Error>;
}

안정적 표면:

run() — 실행 메서드
label() — 노드 식별자
description() — 사람이 읽을 수 있는 설명
bus_access_policy() — 접근 제어 선언
연관 타입: Error, Resources

매크로 동등물: #[transition]은 비동기 함수를 Transition 구현으로 변환합니다.

#Outcome\

제어 흐름 열거형입니다. 모든 Transition은 Result가 아닌 Outcome을 반환합니다.

변형	용도
`Next(T)`	다음 노드로의 선형 진행
`Fault(E)`	에러 경로 — 체인 실행 중단
`Branch(String, Option<Value>)`	분기 ID에 의한 조건부 라우팅
`Jump(Uuid, Option<Value>)`	이전 노드로의 루프/goto
`Emit(String, Option<Value>)`	부작용 이벤트 시그널

안정적 헬퍼: map(), map_err(), is_fault(), next(), branch(), fault().

#Bus

타입 안전 상태 캐리어로, Axon 실행 내 모든 Transition에서 공유됩니다.

안정적 메서드:

메서드	반환 타입	패닉
`new()`	`Bus`	—
`insert<T>(value)`	`()`	—
`read<T>()`	`Option<&T>`	—
`read_mut<T>()`	`Option<&mut T>`	—
`get<T>()`	`Option<T>` (복제됨)	—
`get_mut<T>()`	`Option<&mut T>`	—
`has<T>()`	`bool`	—
`require<T>()`	`&T`	예, 누락 시
`try_require<T>()`	`Result<&T, BusError>`	—

#Schematic

Axon 실행 그래프를 나타내는 생성된 구조체입니다. 모든 Axon은 자동으로 Schematic을 생성합니다.

안정적 표면: axon.schematic()은 노드 메타데이터를 포함한 그래프 구조를 반환합니다.

#2. Axon (확장 포함 안정)

Transition을 연결하는 실행 엔진입니다.

안정적 생성자:

생성자	용도
`Axon::new(label)`	전체 타입 매개변수화된 생성자
`Axon::simple::<T>(label)`	항등 파이프라인 (`T → T`) 편의 메서드
`Axon::parallel(label)`	Fan-out/fan-in 실행

안정적 메서드:

then(transition) — Transition 노드 추가
then_with_retry(transition, policy) — 재시도 정책과 함께 추가
then_with_timeout(transition, duration, error_fn) — 타임아웃과 함께 추가
branch(id, axon) — 분기 경로 연결
execute(input, resources, bus) — 파이프라인 실행
schematic() — 실행 그래프 생성
serve_inspector() — Inspector 대시보드 연결

#3. HTTP 경계 (ranvier-http)

안정적 표면:

API	상태
`Ranvier::http()`	안정 — Ingress 빌더 진입점
`.bind(addr)`	안정
`.route(path, axon)`	안정
`.run(resources)`	안정
`HttpIngress` 빌더 패턴	안정

참고: Ranvier는 Hyper 1.0을 직접 사용합니다 (Tower 아님). HTTP 레이어는 웹 서버 프레임워크가 아닌 Ingress Builder입니다.

#4. 10-크레이트 아키텍처

v0.21 통합 이후 (23 → 10 크레이트). 모든 10개 크레이트는 동일한 semver 정책을 따릅니다:

티어	크레이트	안정성
T0	`ranvier-core`	동결 (패러다임)
T0	`ranvier-macros`	동결 (`#[transition]`)
T1	`ranvier-runtime`	안정 (Axon)
T1	`ranvier-http`	안정 (Ingress)
T1	`ranvier-std`	안정 (Guards)
T2	`ranvier-audit`	안정
T2	`ranvier-compliance`	안정
T2	`ranvier-inspector`	안정
T2	`ranvier-openapi`	안정
T3	`ranvier` (파사드)	안정 (재내보내기)

#5. 실험적 API (비계약)

다음 API는 안정성 보장 대상이 아니며 마이너 릴리스에서 변경될 수 있습니다:

API	크레이트	비고
`PersistenceAdapter`	ranvier-runtime	복구 시맨틱이 변경될 수 있음
`LlmTransition`	ranvier-runtime	LLM-as-Transition 패턴
Inspector 커스텀 오버레이	ranvier-inspector	시각화 레이아웃
`AlertHook` / `AlertDispatcher`	ranvier-inspector	알림 시스템

#6. 호환성 파괴 변경 정책

Ranvier는 엄격한 유의적 버전 관리(SemVer)를 따릅니다:

릴리스	범위	요구사항
PATCH (0.33.x)	버그 수정, 보안 업데이트	API 변경 없음
MINOR (0.x.0)	새 기능, 새 노드	공개 API에 대한 호환성 파괴 변경 없음
MAJOR (x.0.0)	호환성 파괴 변경	마이그레이션 가이드 + 6개월 폐기 기간

#폐기 프로세스

MINOR 릴리스에서 마이그레이션 지침과 함께 #[deprecated]로 기능 표시
최소 2회의 MINOR 릴리스 동안 폐기 경고 유지
다음 MAJOR 릴리스에서 기능 제거

예시 (v0.21 통합):

v0.20에서 마이그레이션 가이드와 함께 13개 크레이트 폐기
v0.21에서 crates.io에서 yank 처리
나머지 10개 크레이트에 기능 통합

#7. MSRV (최소 지원 Rust 버전)

현재 MSRV: Rust 1.85+ (edition 2024)
정책: 12개월 롤링 윈도우 (최근 8-10개 안정 릴리스)
MSRV 변경은 MINOR 변경이며, PATCH가 아님

#8. 마이그레이션 경로: v0.x → v1.0

단계	버전	범위
현재	v0.33	핵심 패러다임 안정, 엣지 API 실험적
안정화	v0.x	실험적 API 동결, 영속성 확정
RC	v1.0-rc	전체 API 동결, 마이그레이션 가이드 발행
릴리스	v1.0.0	모든 문서화된 API가 이 계약의 적용을 받음

#v1.0 기준

전체 체크리스트는 v1.0 안정화 기준을 참조하세요:

핵심 패러다임 동결 (Transition, Outcome, Bus, Schematic)
공개 API에 대한 100% rustdoc 커버리지
모든 예제 컴파일 및 통과
Persistence API 확정
MSRV 정책 문서화

#관련 문서

설계 원칙 — ADR 형식의 아키텍처 결정
철학 — "Opinionated Core, Flexible Edges"
프로덕션 준비 체크리스트 — 배포 체크리스트
보안 강화 — 보안 패턴