#API Stability Contract

Version: 0.33.0 Updated: 2026-03-15 Applies to: ranvier-core, ranvier-runtime, ranvier-http, ranvier-macros Category: Architecture

This document defines the stability guarantees, freeze boundaries, and deprecation policies for the Ranvier public API. It applies to the current v0.33 release and establishes the contract for the upcoming v1.0.

#1. Core Paradigm (Frozen)

The following four primitives are the non-negotiable foundation of Ranvier. They are frozen and will not receive breaking changes:

#Transition

The core execution trait. All business logic flows through 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>;
}

Stable surface:

run() — execution method
label() — node identifier
description() — human-readable description
bus_access_policy() — access control declaration
Associated types: Error, Resources

Macro equivalent: #[transition] converts an async function into a Transition implementation.

#Outcome\

The control flow enum. All transitions return Outcome, not Result.

Variant	Purpose
`Next(T)`	Linear progression to next node
`Fault(E)`	Error path — stops chain execution
`Branch(String, Option<Value>)`	Conditional routing by branch ID
`Jump(Uuid, Option<Value>)`	Loop/goto to previous node
`Emit(String, Option<Value>)`	Side-effect event signal

Stable helpers: map(), map_err(), is_fault(), next(), branch(), fault().

#Bus

The type-safe state carrier, shared across all transitions in an Axon execution.

Stable methods:

Method	Returns	Panics
`new()`	`Bus`	—
`insert<T>(value)`	`()`	—
`read<T>()`	`Option<&T>`	—
`read_mut<T>()`	`Option<&mut T>`	—
`get<T>()`	`Option<T>` (cloned)	—
`get_mut<T>()`	`Option<&mut T>`	—
`has<T>()`	`bool`	—
`require<T>()`	`&T`	Yes, if missing
`try_require<T>()`	`Result<&T, BusError>`	—

#Schematic

Generated structure representing the Axon execution graph. Every Axon automatically produces a Schematic.

Stable surface: axon.schematic() returns the graph structure with node metadata.

#2. Axon (Stable with Extensions)

The execution engine that chains Transitions.

Stable constructors:

Constructor	Purpose
`Axon::new(label)`	Full type-parameterized constructor
`Axon::simple::<T>(label)`	Identity pipeline (`T → T`) convenience
`Axon::parallel(label)`	Fan-out/fan-in execution

Stable methods:

then(transition) — append a transition node
then_with_retry(transition, policy) — append with retry policy
then_with_timeout(transition, duration, error_fn) — append with timeout
branch(id, axon) — attach a branch path
execute(input, resources, bus) — run the pipeline
schematic() — generate execution graph
serve_inspector() — attach Inspector dashboard

#3. HTTP Boundary (ranvier-http)

Stable surface:

API	Status
`Ranvier::http()`	Stable — Ingress builder entry point
`.bind(addr)`	Stable
`.route(path, axon)`	Stable
`.run(resources)`	Stable
`HttpIngress` builder pattern	Stable

Note: Ranvier uses Hyper 1.0 directly (not Tower). The HTTP layer is an Ingress Builder, not a web server framework.

#4. 10-Crate Architecture

Post v0.21 consolidation (23 → 10 crates). All 10 crates follow the same semver policy:

Tier	Crate	Stability
T0	`ranvier-core`	Frozen (paradigm)
T0	`ranvier-macros`	Frozen (`#[transition]`)
T1	`ranvier-runtime`	Stable (Axon)
T1	`ranvier-http`	Stable (Ingress)
T1	`ranvier-std`	Stable (Guards)
T2	`ranvier-audit`	Stable
T2	`ranvier-compliance`	Stable
T2	`ranvier-inspector`	Stable
T2	`ranvier-openapi`	Stable
T3	`ranvier` (facade)	Stable (re-exports)

#5. Experimental APIs (Non-Contract)

The following APIs are NOT subject to the stability guarantee and may change in minor releases:

API	Crate	Notes
`PersistenceAdapter`	ranvier-runtime	Recovery semantics may evolve
`LlmTransition`	ranvier-runtime	LLM-as-Transition pattern
Inspector custom overlays	ranvier-inspector	Visualization layout
`AlertHook` / `AlertDispatcher`	ranvier-inspector	Notification system

#6. Breaking Change Policy

Ranvier follows strict Semantic Versioning (SemVer):

Release	Scope	Requirement
PATCH (0.33.x)	Bug fixes, security updates	No API changes
MINOR (0.x.0)	New features, new nodes	No breaking changes to public APIs
MAJOR (x.0.0)	Breaking changes	Migration guide + 6-month deprecation window

#Deprecation Process

Feature marked #[deprecated] with migration instructions in MINOR release
Deprecation warning persists for at least 2 MINOR releases
Feature removed in next MAJOR release

Example (v0.21 consolidation):

13 crates deprecated in v0.20 with migration guide
Yanked from crates.io in v0.21
Functionality merged into 10 remaining crates

#7. MSRV (Minimum Supported Rust Version)

Current MSRV: Rust 1.85+ (edition 2024)
Policy: Rolling 12-month window (last 8–10 stable releases)
MSRV bumps are MINOR changes, never PATCH

#8. Migration Path: v0.x → v1.0

Phase	Version	Scope
Current	v0.33	Core paradigm stable, edge APIs experimental
Stabilization	v0.x	Freeze experimental APIs, finalize persistence
RC	v1.0-rc	Full API freeze, migration guide published
Release	v1.0.0	All documented APIs subject to this contract

#v1.0 Criteria

See v1.0 Stabilization Criteria for the full checklist:

Core paradigm frozen (Transition, Outcome, Bus, Schematic)
100% rustdoc coverage on public APIs
All examples compile and pass
Persistence API finalized
MSRV policy documented

Design Principles — ADR-format architecture decisions
Philosophy — "Opinionated Core, Flexible Edges"
Production Readiness Checklist — deployment checklist
Security Hardening — security patterns