#API Stability Contract

Version: 0.51.0 release baseline Updated: 2026-06-04 Applies to: ranvier, ranvier-core, ranvier-runtime, ranvier-http, ranvier-macros, supported extension crates 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.

#1. Stability Tiers

Tier	Meaning	Change policy
Stable	Production-facing API that users can build against.	No breaking change without deprecation and migration guidance.
Beta	Supported, but still being refined before v1.0.	Breaking change requires release notes and migration guidance.
Experimental	Useful for exploration, examples, or candidate designs.	May change in minor releases; must not be described as production-frozen.
Internal	Implementation detail.	May change at any time; not part of the user contract.
Deprecated	Supported only for migration.	Must include replacement guidance and a removal target.

#2. Frozen Core Paradigm

The following primitives define Ranvier's identity and remain the highest-stability surface:

Primitive	Tier	Contract
`Transition<I, O>`	Stable	Business logic enters through `run(input, resources, bus) -> Outcome<O, E>`.
`Outcome<T, E>`	Stable	Control flow is explicit data: `Next`, `Fault`, `Branch`, `Jump`, and `Emit`.
`Bus`	Stable	Per-execution typed context carrier; no hidden dependency injection.
`Schematic`	Stable	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.

#3. Runtime API Tiers

API	Tier	Notes
`Axon::new`, `Axon::start`, `Axon::simple`, `Axon::typed`	Stable	Constructor surface for explicit Axon flows.
`.then(...)`, `.then_fn(...)`, `.execute(...)`, `.execute_simple(...)`	Stable	Core execution composition and execution entry points.
`.schematic()`, `.into_schematic()`, schematic export helpers	Stable	Structural visibility is part of the core product contract.
retry, timeout, DLQ, Saga compensation helpers	Beta	Supported runtime features; semantics may still tighten before v1.0.
persistence stores and resumption helpers	Beta	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(...)`	Beta, 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 `HttpIngress` route builder	Stable	Main HTTP ingress surface.
typed JSON route helpers and `Json<T>` response conversion	Stable	JSON serialization stays at the route boundary.
`RanvierService`	Stable low-level adapter	Maps `Outcome::Next` to JSON `200`, `Fault` to JSON `500`, `Emit` to JSON `202`, and unresolved `Branch`/`Jump` to JSON `409`.
`RanvierService::with_response_mapper(...)`	Stable escape hatch	Applications can define exact egress semantics without changing Transition logic.
validation, multipart, Askama, htmx, TLS, HTTP/3 features	Beta or 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. Extension Crates

Crate	Tier	Boundary rule
`ranvier-audit`	Beta	Durable audit implementation for the core audit port; not a runtime dependency.
`ranvier-inspector`	Beta	Operational dashboard/inspection server; opt-in from runtime.
`ranvier-openapi`	Beta	Projection/generation adapter, not a core execution primitive.
`ranvier-compliance`	Beta	Compliance helpers and domain types; no hidden runtime policy.
`ranvier-guard`	Beta	Boundary guard primitives; fail-open/fail-closed behavior must be explicit.
`ranvier-std`	Beta	Convenience transitions; must not redefine the core paradigm.

#7. Deprecation Policy

Stable APIs require a documented replacement before deprecation.
A deprecated stable API remains available for at least two minor release cycles unless a security issue 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.

#8. 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.

Production Readiness Checklist
Operational Policy
Boundary Map
M401-M408 backend hardening board