Calybris Core

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

Two Reference Use Cases

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.

When to use it

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.

Try it locally

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

Use as a dependency

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

Architecture

1. kernel — Integer-only decision kernel (~115ns/decision). prescribe_with_trace exposes per-constraint rejection counts.
2. verify — Policy + input + decision digests, full replay, DigestDecodeError on public API.
3. finance — Ledger digest, FinancialCertificate, ConservationProof, prove_conservation, certify_snapshot.
4. wal — Tamper-evident hash chain, append_verified_audited (fail-closed), replay_audited_wal.
5. budget — CAS reserve/commit/release. Conservation holds after completed ops: remaining + reserved + committed_lifetime == initial. Loom + Miri in CI.
6. proof — ProofEnvelope: single struct binding policy + input + decision digests + WAL position + budget proof.
7. config — Runtime EngineConfig with builder pattern, validation, and budget integration (ensure_tenant).
8. builder — InputBuilder, ModelBuilder, PolicyBuilder with BuildError (config + policy + catalog size enforcement).
9. persistence — fsync-backed snapshot save/load, checkpoint_with_wal, recovery_plan with WAL high-watermark.
10. async_wal (feature async) — Tokio-based non-blocking WAL with HMAC, chain validation, configurable sync.
11. instrument (feature observability) — Structured tracing spans for prescribe, verify, budget, WAL.

Audit Pipeline

prescribe → verify_decision → append_verified_audited → replay_audited_wal (fail-closed)
                ↓                        ↓
     calypol1 / calyinp1 / calydcn1    ProofEnvelope (optional)

Financial layer & policy

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/release
• top_up_tenant — add funds without resetting lifetime spend
• restore_from_snapshot — exclusive-recovery restore from frozen BudgetSnapshot
• 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);

Feature Flags

cargo add calybris-core                        # default (wal)
cargo add calybris-core --features full        # everything
cargo add calybris-core --no-default-features  # kernel only

Builder Ergonomics (v0.4.0)

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);

Persistence & Recovery

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"))?;

Proof Envelope

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

Examples

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

Tests & CI

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.

Integration contract

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")?;

External audit

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.

Security Posture

• #![forbid(unsafe_code)] — zero unsafe blocks
• cargo-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

What This Crate Is Not

• Exchange gateway, market data, or order lifecycle
• Thompson Sampling / adaptive routing
• HTTP API server

See emirhuseyin.tech/engine for the full proprietary stack.

License

Apache-2.0. See LICENSE.