Calybris Core

A small Rust decision engine for auditable, deterministic policy decisions.

Calybris Core evaluates candidates under hard constraints, selects the highest-utility valid option, and records decisions through tamper-evident primitives.

The first packaged use case is LLM/model routing: choosing between models under budget, latency, risk, quality, provider, and region constraints. The core pattern is domain-neutral — any system that chooses between candidates under constraints can use the same primitives.

Built from three components:

1. kernel — Integer-only decision kernel. 11 constraint gates, ~115ns per decision. No floating-point, no allocation in the hot path.
2. wal — Hash-chained write-ahead log. SHA-256 or HMAC-SHA256. Generic over any Serialize type.
3. budget — CAS atomic budget engine. Conservation invariant: remaining + reserved + committed = initial.

#![forbid(unsafe_code)] · 37 tests · 6 direct dependencies · Apache-2.0

Quick Start

cargo add calybris-core

use calybris_core::kernel::*;

let models = vec![/* your model catalog */];
let snapshot = PolicySnapshot::new(1, 1, 9600, 5500, 3500, 0, models);
let decision = snapshot.prescribe(input);
// decision.action: ExecuteRequested | Substitute | Reject
// decision.selected_model_id: which model was chosen
// decision.expected_utility_microunits: why

Modules

kernel.rs

The kernel scores every candidate model with:

utility = quality_adjusted_value - risk_penalty - cost - latency_penalty

All values are basis points (1/10,000) or microunits (1/1,000,000). The fast path uses u64 with overflow guards; when inputs don't fit, it falls back to u128. Proptest verifies both paths agree on every random input.

Constraints checked per decision: risk ceiling, confidence floor, quality minimum, budget limit, latency cap, capability match, provider mask, region mask, cost, utility sign, optimality.

wal.rs

// Unkeyed — detects accidental corruption
let mut wal = WalWriter::open(&path)?;
let entry = wal.append(my_data)?;

// Keyed — attacker can't forge valid hashes
let mut wal = WalWriter::open_keyed(&path, b"secret")?;

Chain is validated on open. Constant-time comparison (subtle) on keyed WALs. append() writes to the OS buffer; call flush_and_sync() when you need crash durability.

budget.rs

let engine = BudgetEngine::new();
engine.ensure_tenant("team-a", 100_000_000);
let (res, id) = engine.try_reserve("team-a", 25_000_000);
engine.commit(id.unwrap(), 20_000_000); // surplus refunded

Arc<AtomicI64> per tenant, cloned out before the CAS loop — no mutex held during contention. Lock ordering: reservations → budgets.

Benchmarks

cargo bench

Results from Criterion on one machine. Your numbers will differ.

Tests

cargo test           # 37 tests (36 + 1 doc)
cargo test --release # includes latency guard

Includes proptest property-based verification, 100-thread concurrency stress, HMAC chain validation, and WAL fuzz roundtrips.

What This Crate Is Not

This is the open-source decision core. It doesn't include:

• Adaptive routing (Thompson Sampling)
• Policy evolution (counterfactual replay)
• HTTP gateway or API server
• Prompt classification models

Those are part of the proprietary engine. See emirhuseyin.tech/engine for the full architecture.

Contributing

See CONTRIBUTING.md. Issues labeled good first issue are a good starting point.

License

Apache-2.0. See LICENSE.