Ranvier
KR Browse Docs

#Ranvier is a Typed Decision Engine

Version: 0.33.0 Updated: 2026-03-15 Applies to: ranvier (facade), ranvier-core, ranvier-runtime Category: Philosophy & Architecture

It is not a web framework. It is a structural layer that keeps execution explicit, inspectable, and safe to refactor. Your Rust code becomes a circuit. Ranvier turns on the lights.

#Core Principles

Principle Description
Execution is explicit Axon chains describe the exact order of decisions. No hidden middleware and no implicit control flow.
Structure is inspectable Schematic captures nodes and edges without executing the runtime. It is the artifact for diff, validation, and visualization.
Control flow is data Outcome models branch, jump, emit, and fault as explicit results. You can audit and replay decisions without guessing.

#The Contract

  • Core stays protocol-agnostic. HTTP lives in the adapter layer.
  • Schematic never executes runtime logic. It is read/validate/visualize only.
  • Flat API is allowed, but it must not hide complexity. We isolate it.

#Resources Stay Explicit

Ranvier does not hide state behind global middleware. Shared resources live in a typed Bus or an explicit resource bundle, and every transition chooses when to read them.

  • Bus is type-indexed and opt-in. No implicit injection.
  • Resources are wired at ingress, not magically discovered at runtime.
  • Capability rules can be layered without changing core contracts.

#Ingress / Egress Boundaries

  • Ingress adapts protocol requests into the initial state.
  • Axon executes the decision flow with typed transitions.
  • Egress maps Outcomes back into protocol responses.

#Schematic Diff & Validation

Schematic is a static artifact. You can diff and validate circuits in CI before runtime, without executing the system.

#Trust & LLM Boundaries

AI can propose structure, but it does not mutate runtime logic. Every change remains explicit, reviewable, and validated against the Schematic.

#Quick Example

use ranvier::prelude::*;

let axon = Axon::simple::<anyhow::Error>("Hello")
    .then(Hello);

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

If you are looking for a batteries-included framework, Ranvier is not it. If you want your runtime logic to remain visible and verifiable, you are in the right place.

#Next Steps

  • Tutorial โ€” First run
  • Philosophy โ€” Opinionated Core, Flexible Edges
  • Design Principles โ€” Architecture Decision Records