Calybris Core

A deterministic decision engine: it selects under explicit constraints, and makes the decision verifiable afterwards.

Given a frozen catalog, a policy snapshot, and a typed request, Calybris returns one action plus an audit bundle that replays to the same answer.

catalog + policy + request  ->  decision + audit bundle

Integer-only hot path — no f64 anywhere in it. No hosted dependency. #![forbid(unsafe_code)].

What this crate is

A proof-carrying decision kernel: not an OMS, not an LLM gateway, not a matching engine. You bring the catalog — suppliers, carriers, venues, models — and the kernel evaluates hard constraints, picks the best eligible candidate, and emits digests you can replay and verify offline.

The kernel does not know what a candidate is. Supplier routing, carrier selection, model routing and pre-trade admission are reference mappings onto one API, not four products.

Two claims it does not make. It does not find the best commercial outcome; it selects by the rules you wrote, and a wrong rule produces a wrong decision you can at least see. And it proves the integrity of the trail, not the truth of your inputs.

Quick start

[dependencies]

calybris-core = "0.6"

use calybris_core::kernel::*;
use calybris_core::verify::{verified_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_checked(input)?;
assert_eq!(verify_decision(&snapshot, input, &decision), VerifyResult::Valid);

// Fail-closed: this returns a bundle only after the decision replays exactly.
// The bare `audit_bundle` returns one with `replay_valid = false` instead of refusing.
let bundle = verified_audit_bundle(&snapshot, input, &decision)
    .expect("decision must replay to be audited");
assert!(bundle.replay_valid);

cargo run --example quickstart runs this end to end and prints the bundle. cargo run --example llm_routing and --example pretrade_guard are two of the reference mappings.

What gets proved

policy digest + input digest + decision digest + replay result

The proof format is a written contract, not an implementation detail. docs/CALY_PROOF.md specifies every digest and chain byte-exactly, and golden and conformance vectors pin them across versions and platforms, so an independent reimplementation can prove itself against a fixed reference.

The crate ships a calybris-verify binary so a third party can check a decision trail without running your engine:

cargo install calybris-core

calybris-verify chain decisions.wal.jsonl --anchor trusted-head.json

calybris-verify audit decisions.wal.jsonl --policy policy.json --json

The trail carries fail-closed receipts (verify_receipt_full binds replay, claims, trusted signature, state anchor and WAL anchor in one call), canonical trusted policy construction, state trajectories, ledger digests bound to WAL watermarks, per-record policy resolution across rotations, suffix-truncation detection, and domain-separated Ed25519 policy provenance.

The verification path builds for wasm32-unknown-unknown (--no-default-features).

docs/THREAT_MODEL.md is explicit about scope: the system proves trail integrity, not confidentiality, policy quality, or input truth.

Modules

0.6.0

This release adds a typed decision surface over the same kernel, published separately as the calybris Python package: a fixed-quote adapter, a bounded policy comparison that identifies both policies it compared, and an atomic budget lifecycle report. The Rust decision and replay protocol is unchanged, and calybris-core remains the contract that surface is built on.

Two reporting defects were fixed here: the kernel dropped its rejection histogram on the trace path, so a rejected decision reported every gate as zero. Neither touched the ledger. See the CHANGELOG.

Performance

CodSpeed CI (Linux x86_64, release): ~8.6M prescribe/sec, ~115 ns/decision on a 22-model synthetic catalog. Hardware and workload dependent — provenance and a reproduction recipe are in docs/BENCHMARKS.md; run cargo bench --bench kernel_bench on your own hardware.

Documentation

The full README, the Python surface and the adapter walkthroughs live in the repository.

MSRV 1.85. Apache-2.0.