#API Stability Contract
Version: 0.51.0 M418 candidate baseline Updated: 2026-07-16 Applies to: the manifest-derived publishable Ranvier product-crate set Category: Architecture
This document defines the public API tiers, feature policy, and deprecation
rules for the Ranvier Typed Decision Engine. It is a v1.0-entry contract, not a
claim that every current API is already frozen. The machine-readable authority
is ranvier/.ranvier-api-policy.json; the generated
ranvier/api-surface-inventory.json proves that every discovered public item
has a tier and owner.
#1. Stability Tiers
| Tier | Meaning | Change policy |
|---|---|---|
| Stable Candidate | Selected surface intended to become the 1.0 compatibility promise. | Breaking change requires semver review, migration guidance, and a new reviewed baseline. |
| Experimental | Useful for exploration, examples, or candidate designs. | May change in minor releases; must not be described as production-frozen. |
| Internal/not promised | Publicly unreachable implementation detail. Accidental public items stay Experimental until actually hidden. | May change at any time after reachability verification. |
| Deprecated | Supported only for migration. | Must include replacement, removal condition, and earliest eligible release. |
#2. Frozen Core Paradigm
The following primitives define Ranvier's identity and remain the highest-stability surface:
| Primitive | Tier | Contract |
|---|---|---|
Transition<I, O> |
Stable Candidate | Business logic enters through run(input, resources, bus) -> Outcome<O, E>. |
Outcome<T, E> |
Stable Candidate | Next/Fault preserve Rust types; Branch/Jump/Emit carry schema-described JSON. The lossy into_result() adapter remains Experimental. |
Bus |
Stable Candidate | Per-execution type-indexed context carrier; presence and access policy are runtime checks. Mandatory compile-time dependencies belong in Transition::Resources. |
Schematic |
Stable Candidate | Versioned structural execution graph emitted by Axon construction. |
Boundary rule: adapters may translate HTTP, CLI, Inspector, persistence, audit, or deployment concerns into these primitives, but they must not hide execution flow behind controller/service/repository assumptions.
The compiler guarantees compatible Rust types on linear Axon handoffs. It does not guarantee that a Bus resource is present/authorized or that a JSON control payload conforms to an application schema. See Outcome and Bus Typed-Boundary Decision.
#3. Runtime API Tiers
| API | Tier | Notes |
|---|---|---|
Axon::new, Axon::start, Axon::simple, Axon::typed |
Stable Candidate | Constructor surface for explicit Axon flows. |
.then(...), .then_fn(...), .execute(...), .execute_simple(...) |
Stable Candidate | Core execution composition and execution entry points. |
.schematic(), .into_schematic(), selected export/schema helpers |
Stable Candidate | Structural visibility is part of the core product contract. |
| retry, timeout, DLQ, Saga compensation helpers | Experimental | Available runtime features whose semantics may still tighten before v1.0. |
| persistence stores and resumption helpers | Experimental | Operationally important, but persistence semantics remain a v1.0-readiness focus. |
| LLM transition helpers | Experimental | Pattern support, not a frozen provider abstraction. |
| streaming Axon helpers | Experimental | Available behind streaming; API may still evolve. |
serve_inspector(...) |
Experimental, feature-gated | Available only with ranvier-runtime/inspector; not part of the minimal runtime build. |
#4. HTTP Boundary API Tiers
ranvier-http is an adapter boundary. It converts protocol input into Axon input and converts Outcome back into HTTP responses. It is not a general-purpose web framework.
| API | Tier | Notes |
|---|---|---|
Ranvier::http() and the selected HttpIngress core methods |
Stable Candidate | Main native HTTP ingress surface; all other public methods remain Experimental unless selected in policy. |
selected typed JSON route helpers and Json<T> conversion |
Stable Candidate | JSON serialization stays at the route boundary. |
RanvierService and response mapper |
Stable Candidate low-level adapter | Tower/Axum can own routing while Axon owns the decision workflow. |
| validation, multipart, Askama, htmx, TLS, HTTP/3 features | Experimental by feature | Feature docs must state production readiness separately. |
#5. Feature Policy
Minimal users must be able to build without operational extensions:
| Crate | Default features | Minimal command | Operational opt-ins |
|---|---|---|---|
ranvier-core |
none | cargo check -p ranvier-core --no-default-features |
streaming |
ranvier-runtime |
none | cargo check -p ranvier-runtime --no-default-features |
inspector, schema, streaming, persistence-postgres, persistence-redis |
ranvier-http |
none | cargo check -p ranvier-http --no-default-features |
validation, multer, askama, streaming, htmx, tls, http3 |
ranvier facade |
http, std, guard |
cargo check -p ranvier --no-default-features |
http, std, guard, inspector, openapi, streaming, validation |
M407 boundary rule: ranvier-runtime must not depend on ranvier-audit directly. Runtime intervention logging uses the core ranvier_core::telemetry::AuditLogger port; ranvier-audit implements that port as an adapter.
#6. Enforced Compatibility Baseline
Ranvier commit 8aa5428300b7735a766822ab5b9414681e0bf2f9 freezes 184
Stable Candidate items across ranvier, ranvier-core, ranvier-http,
ranvier-macros, and ranvier-runtime against tag v0.51.0 (commit
3578799759da5d2fb3ad5742b67b7c281b726754). The checked-in
api-stable-candidate-baseline.json is the exact item-level contract: path,
kind, owner, re-export target, and typed/runtime boundary must match.
cargo-semver-checks runs with all features on the four ordinary library
crates as a conservative whole-crate superset. The proc-macro-only
ranvier-macros crate is compile-gated because cargo-semver-checks cannot
analyze proc-macro-only targets. A facade-only external-style fixture proves
that the documented use ranvier::prelude::* macro, resource, Axon, Outcome,
Bus, native HTTP, and hybrid service path compiles without direct Ranvier
subcrate dependencies.
Changing the generated candidate baseline is not a routine regeneration. A review must classify the change as additive, deprecation, or breaking; record migration impact; run the compile and SemVer gates; and update this contract.
#7. Toolchain, Platform, and Feature Support
| Dimension | Current 0.51 candidate evidence | Candidate-promotion requirement |
|---|---|---|
| MSRV | Workspace rust-version = 1.93.0; no silent bump allowed |
dedicated Rust 1.93.0 job plus current stable |
| Linux x86_64 GNU | Ubuntu CI runs inventory, compile contract, and all-features SemVer | required |
| Windows x86_64 MSVC | M417 fresh recursive clone passed on Windows | required recurring job before candidate promotion |
| macOS x86_64 / arm64 | No current recurring evidence; not yet a support promise | recurring build/test evidence or an explicit published exclusion |
| Minimal features | commands are documented in section 5 | every candidate-bearing library must pass --no-default-features where supported |
| Default features | facade-only compile fixture covers the documented default path | required for candidate crates and canonical examples |
| All features | inventory and SemVer gates cover candidate-bearing crates; workspace CI covers the current streaming aggregate | required for candidate crates; operational integrations follow their scheduled/release tier |
The table records evidence, not an inference from Rust portability. M419 owns the missing recurring platform/MSRV matrix. Until it passes, documentation may say that the targets are intended, but must not call macOS or the full matrix verified or production-supported.
The first candidate compatibility line is 0.51.x; there is no earlier
candidate-supported line. After a successor candidate line is published, the
current and immediately previous candidate lines remain in the compatibility
window for at least 90 days. Stable API deprecation remains subject to the
longer window below, and security maintenance follows VERSION_POLICY.md.
#8. Extension Crates
| Crate | Tier | Boundary rule |
|---|---|---|
ranvier-audit |
Experimental | Durable audit implementation for the core audit port; not a runtime dependency. |
ranvier-inspector |
Experimental | Operational dashboard/inspection server; opt-in from runtime. |
ranvier-openapi |
Experimental | Projection/generation adapter, not a core execution primitive. |
ranvier-compliance |
Experimental | Compliance helpers and domain types; no hidden runtime policy. |
ranvier-guard |
Experimental | Boundary guard primitives; fail-open/fail-closed behavior must be explicit. |
ranvier-std |
Experimental | Convenience transitions; must not redefine the core paradigm. |
#9. Deprecation and Tier-Transition Policy
- Stable APIs require a documented replacement before deprecation.
- A deprecated stable API remains available for at least two minor release trains or 90 days, whichever is longer, unless an approved security, soundness, or data-corruption exception requires faster removal.
- Experimental APIs may change faster, but release notes must say so clearly.
- A feature-gated API that moves out of the default build must document the new feature flag.
- An Experimental member of a Stable Candidate type does not become stable by association; the generated item-level policy is authoritative.
- Experimental to Stable Candidate requires a named owner, boundary/semantic decision, exact baseline addition, canonical compile coverage, and migration or adoption guidance.
- Stable Candidate to Deprecated requires a documented replacement, migration path, earliest eligible removal, and removal condition. Removal is allowed only after the notice window and the relevant compatibility gates pass.
#10. v1.0 Entry Criteria
Before Ranvier can enter a v1.0 release-candidate track:
- stable API tiers must be reviewed crate by crate;
- minimal feature builds must be part of the release gate;
- supported examples must compile under their documented support tiers;
- production operational defaults must be documented and smoke-tested;
- every supported adapter must preserve the explicit Axon / Transition / Outcome / Bus / Schematic boundary.
#Related Documents
- Production Readiness Checklist
- Operational Policy
- Boundary Map
- M401-M408 backend hardening board