매뉴얼

Ranvier 핵심 개념과 워크플로.

이 매뉴얼은 Ranvier의 기본 원리, 계층 경계, 그리고 CLI 도구를 빠르게 참조할 수 있도록 정리했습니다.

레이어 모델

Core

프로토콜 독립 계약: Transition, Outcome, Bus, Schematic.

Runtime

Axon 실행 엔진과 명시적 조합.

Adapter

Ingress/Egress 경계. HTTP는 이 계층에 존재합니다.

코어 타입

Transition: 상태를 Outcome으로 변환하는 async 계약.

Outcome: Next, Branch, Jump, Emit, Fault.

Bus: 타입 기반 리소스 컨테이너.

Schematic: Axon에서 추출된 노드/엣지 구조.

Bus & 리소스 연결

Bus는 의존성을 명시적으로 보여줍니다. 리소스는 경계에서 삽입되고, Transition은 필요한 시점에 읽습니다.

let mut bus = Bus::new();
bus.insert(DbPool::new(...));
bus.insert(Tracer::global());

// Later, inside a transition:
let db = bus.read::<DbPool>();

Ingress Builder

Ranvier::http()
    .bind("127.0.0.1:3000")
    .route("/", axon)
    .fallback(not_found)
    .run(resources)
    .await?;

Ranvier::http()는 웹 서버가 아니라, 프로토콜 트래픽을 Axon 실행으로 연결하는 Ingress Builder입니다.

Ingress / Egress 경계

Ingress는 요청을 타입 입력 상태로 변환합니다.

Axon이 Transition을 실행하고 Outcome을 반환합니다.

Egress가 Outcome을 프로토콜 응답으로 변환합니다.

Schematic Diff & Validation

Schematic은 구조 데이터이므로 런타임 전에 diff와 검증을 수행할 수 있습니다. CI 체크, 리팩터링 안정성, 시각적 검증에 사용됩니다.

신뢰 경계 & LLM

LLM은 구조나 문서 제안만 가능합니다. 런타임 로직 변경은 명시적 리뷰와 Schematic 검증을 거칩니다.

CLI 도구

Schematic Export

ranvier schematic basic-schematic --output schematic.json

Projection From Schematic

ranvier status projection-from-schematic basic-schematic --output ./dist/trace

Projection From Timeline

ranvier status projection-from-timeline ./dist/sample.timeline.json --output ./dist/trace

Inspector + Trace 아티팩트

RANVIER_TRACE_PUBLIC_PATH=./dist/trace/trace.public.json
RANVIER_TRACE_INTERNAL_PATH=./dist/trace/trace.internal.json
RANVIER_TIMELINE_MODE=overwrite
RANVIER_TIMELINE_MAX_EVENTS=1000
RANVIER_TIMELINE_SAMPLE_RATE=1.0
RANVIER_TIMELINE_ADAPTIVE=fault_branch

검증 스냅샷 (2026-02-05)

cargo run -p typed-state-tree: 성공 (정상 경로 + 접근 거부 경로).

cargo run -p basic-schematic: 성공 (schematic JSON + Axon 실행 출력).

cargo run -p order-processing-demo: 성공 (성공 + 분기 케이스).

참고: hello-world는 HTTP 서버가 상주합니다. cargo run -p hello-world로 검증하세요.