Deterministic proof-carrying decision core for systems that must explain and replay why an action was allowed, substituted, or rejected.
Not an LLM framework. Not an exchange or strategy engine. A domain-neutral primitive:
candidate + policy constraints → decision + digests + optional WAL + budget proof
#![forbid(unsafe_code)]
· unit/proptest/Loom/Miri coverage · Apache-2.0
| Use case | What Calybris does |
|---|---|
| LLM routing | |
| Select / substitute / reject models under budget, risk, quality, latency | |
| Pre-trade guard | |
| Admit / reject candidate orders under exposure, risk, and latency limits |
Calybris is not an exchange, market data feed, colocation stack, or alpha engine. It is a deterministic pre-trade decision kernel — integer-only constraints, replay verification, and fixed-point conservation proofs.
Use Calybris when a service has to make the same decision twice and prove it got the same answer:
- route an LLM request under budget, latency, provider, and quality constraints
- reject or substitute a candidate action before it crosses a risk boundary
- write an auditable decision record to a tamper-evident WAL
- reconcile budget state with fixed-point conservation proofs
Do not use it as a hosted API, trading strategy, exchange adapter, web framework, or model orchestration platform. Calybris is the deterministic core you put behind those systems.
git clone https://github.com/emirhuseynrmx/calybris-core
cd calybris-core
cargo run --example quickstart
cargo run --example llm_routing
cargo run --example replay_audit
cargo add calybris-core
use calybris_core::budget::BudgetEngine;
use calybris_core::finance::{prove_conservation, ConservationProof};
use calybris_core::kernel::*;
use calybris_core::verify::{audit_bundle, verify_decision, VerifyResult};
let models = vec![
KernelModel {
model_id: 1,
provider_id: 0,
quality_bps: 9000,
risk_ceiling_bps: 9500,
enabled: 1,
p95_latency_ms: 200,
capabilities: 0,
region_mask: ALL_REGIONS,
input_cost_microunits_per_million_tokens: 250,
output_cost_microunits_per_million_tokens: 1000,
},
KernelModel {
model_id: 2,
provider_id: 1,
quality_bps: 7000,
risk_ceiling_bps: 9500,
enabled: 1,
p95_latency_ms: 90,
capabilities: 0,
region_mask: ALL_REGIONS,
input_cost_microunits_per_million_tokens: 25,
output_cost_microunits_per_million_tokens: 125,
},
];
let snapshot = PolicySnapshot::try_new(1, 1, 9600, 5500, 3500, 2, models)?;
let input = KernelInput {
request_sequence: 1,
requested_model_id: 1,
input_tokens: 1000,
output_tokens: 500,
business_value_microunits: 100_000,
budget_limit_microunits: 50_000_000,
risk_bps: 1000,
confidence_bps: 9000,
minimum_quality_bps: 5000,
max_p95_latency_ms: 1000,
required_capabilities: 0,
allowed_provider_mask: ALL_PROVIDERS,
required_region_mask: 0,
};
let decision = snapshot.prescribe(input);
assert_eq!(verify_decision(&snapshot, input, &decision), VerifyResult::Valid);
assert!(audit_bundle(&snapshot, input, &decision).replay_valid);
let budget = BudgetEngine::new();
budget.ensure_tenant("desk-1", 100_000_000);
let proof: ConservationProof = prove_conservation(&budget)?;
assert_eq!(proof.ledger_digest_hex.len(), 64);
Kernel-only (no WAL):
cargo add calybris-core --no-default-features
— Integer-only decision kernel (~115ns/decision).kernel
prescribe_with_trace
exposes per-constraint rejection counts.— Policy + input + decision digests, full replay,verify
DigestDecodeError
on public API.— Ledger digest,finance
FinancialCertificate
,ConservationProof
,prove_conservation
,certify_snapshot
.— Tamper-evident hash chain,wal
append_verified_audited
(fail-closed),replay_audited_wal
.— CAS reserve/commit/release. Conservation holds after completed ops:budget
remaining + reserved + committed_lifetime == initial
. Loom + Miri in CI.—proof
ProofEnvelope
: single struct binding policy + input + decision digests + WAL position + budget proof.— Runtimeconfig
EngineConfig
with builder pattern, validation, and budget integration (ensure_tenant
).—builder
InputBuilder
,ModelBuilder
,PolicyBuilder
withBuildError
(config + policy + catalog size enforcement).— fsync-backed snapshot save/load,persistence
checkpoint_with_wal
,recovery_plan
with WAL high-watermark.async_wal
(feature— Tokio-based non-blocking WAL with HMAC, chain validation, configurable sync.async
)instrument
(feature— Structuredobservability
)tracing
spans for prescribe, verify, budget, WAL.
prescribe → verify_decision → append_verified_audited → replay_audited_wal (fail-closed)
↓ ↓
calypol1 / calyinp1 / calydcn1 ProofEnvelope (optional)
Fixed-point i64
microcents (1 cent = 1,000,000). No f64
.
committed_microcents
—lifetime cumulative spend(monotonic; never decreases)reserved_microcents
— active holds awaiting commit/releasetop_up_tenant
— add funds without resetting lifetime spendrestore_from_snapshot
— exclusive-recovery restore from frozenBudgetSnapshot
verify_conservation
— audit/reconciliation path (full snapshot)PolicySnapshot::utility_for_model
— per-model utility (not prescribe winner/runner-up)
budget.ensure_tenant("desk", 100_000_000);
budget.top_up_tenant("desk", 50_000_000);
let proof = prove_conservation(&budget)?;
let cert = certify_ledger(&budget);
assert!(cert.conservation_balanced);
| Policy API | Use |
|---|---|
PolicySnapshot::try_new |
|
Production — validates catalog + BPS (MAX_BPS , etc.) |
|
PolicySnapshot::new_unchecked |
|
Tests / fuzz only — never serve without explicit validate() |
|
PolicySnapshot::new |
|
Deprecated alias for new_unchecked |
| Feature | What it adds | Dependencies |
|---|---|---|
wal (default) |
||
| Hash-chained WAL, HMAC-SHA256, audited append | serde , hmac , subtle |
|
async |
||
| Tokio-based async WAL | wal + tokio |
|
observability |
||
| Structured tracing spans/events | tracing |
|
full |
||
| All of the above | — |
cargo add calybris-core # default (wal)
cargo add calybris-core --features full # everything
cargo add calybris-core --no-default-features # kernel only
use calybris_core::config::EngineConfig;
use calybris_core::builder::{InputBuilder, ModelBuilder, PolicyBuilder};
let config = EngineConfig::new()
.latency_penalty(3)
.hard_risk_limit(9_500)
.default_exposure_cap(500_000_000);
let snapshot = PolicyBuilder::new(config)
.epochs(1, 1)
.model(ModelBuilder::new(1, 0).quality(9500).cost(250, 1000).build())
.model(ModelBuilder::new(2, 1).quality(7000).cost(25, 125).build())
.build()?;
let input = InputBuilder::new(1, 1)
.tokens(1000, 500)
.business_value(100_000)
.risk(1000, 9000)
.minimum_quality(5000)
.build();
let decision = snapshot.prescribe(input);
use calybris_core::persistence::{checkpoint_with_wal, restore, recovery_plan};
// Checkpoint budget state alongside WAL position (fsync-backed)
let snap = checkpoint_with_wal(&budget, Path::new("budget.json"), wal.sequence())?;
// After crash: figure out what needs replay
let plan = recovery_plan(Path::new("budget.json"), Path::new("wal.jsonl"))?;
println!("{} WAL entries to replay", plan.entries_to_replay);
// Restore from last checkpoint
let fresh = BudgetEngine::new();
restore(&fresh, Path::new("budget.json"))?;
js
use calybris_core::proof::ProofEnvelopeBuilder;
let envelope = ProofEnvelopeBuilder::new(&snapshot, input, &decision)
.wal(wal_entry.sequence, wal_entry.entry_hash)
.budget(budget_snap.version, ledger_digest_hex)
.build();
assert!(envelope.is_complete()); // replay + WAL + budget all present
cargo run --example quickstart
cargo run --example production_gateway # full pipeline: config→build→prescribe→verify→budget→WAL→checkpoint→recovery
cargo run --example llm_routing
cargo run --example hft_pretrade_guard
cargo run --example replay_audit
cargo run --example finance_hft # throughput benchmark
cargo run --example route_decision # legacy alias
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-features
cargo test --no-default-features
RUSTFLAGS='--cfg loom' LOOM_MAX_PREEMPTIONS=3 cargo test --test budget_loom
cargo +nightly miri test --lib --all-features # see docs/MIRI.md for CI filters
cargo doc --no-deps
Extensive test coverage across unit, property-based (proptest), 7 Loom exhaustive concurrency, and Miri UB detection targets. Feature matrix CI: default
, no-default-features
, async
, full
. See CI for the current test count.
Calybris verifies decisions and conservation proofs — it does not auto-invoke verify_decision
in your hot path. You must call it at audit boundaries:
prescribe → verify_decision → (optional WAL / prove_conservation)
Use append_verified_audited
(not append_audited
) at production boundaries — it verifies before writing. See docs/AUDIT_GUIDE.md.
For fail-closed audit boundaries, use the verified helpers:
use calybris_core::verify::verified_audit_bundle;
let bundle = verified_audit_bundle(&snapshot, input, &decision)?;
assert!(bundle.replay_valid);
With the wal
feature enabled, append_verified_audited
verifies before writing. Invalid or tampered decisions do not enter the log:
use calybris_core::wal::WalWriter;
let mut wal = WalWriter::open(std::path::Path::new("decisions.jsonl"))?;
wal.append_verified_audited(&snapshot, input, decision, "metadata")?;
Invariant docs, adversarial tests, Loom, Miri, and supply-chain checks are in place for third-party review. A paid external audit is still your responsibility — see docs/AUDIT_GUIDE.md §7.
#![forbid(unsafe_code)]
— zero unsafe blockscargo-audit
+cargo-deny
in CI- Miri on nightly — UB detection for all lib tests
- 7 Loom exhaustive concurrency tests for budget operations
- HMAC-SHA256 keyed tamper-evident WAL with constant-time comparison (
subtle
) - Fail-closed
append_verified_audited
— invalid decisions never enter the log - fsync-backed snapshot persistence with atomic rename
- Feature matrix CI:
default
,no-default-features
,async
,full
- Exchange gateway, market data, or order lifecycle
- Thompson Sampling / adaptive routing
- HTTP API server
See emirhuseyin.tech/engine for the full proprietary stack.
Apache-2.0. See LICENSE.