Calybris Core

Deterministic, auditable decision primitive for high-stakes routing & guardrails.

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 Rust hot path. No hosted dependency. No unsafe in project code.

What is this?

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

Same primitive, different adapters: supplier routing, model routing, and pre-trade admission are reference mappings onto one API, not three products.

When to use / when not to

Stability model

Rust owns correctness and replay semantics. Python packages are ergonomic entry points for integration and demos; mature them in your stack before treating them as production infrastructure.

Quickstart (~5 minutes)

git clone https://github.com/emirhuseynrmx/calybris-core.git

cd calybris-core

cargo run --example quickstart

That example builds a two-model policy, prescribes one request, verifies replay, and prints an audit bundle. For Python:

pip install maturin pydantic

maturin develop --release

python bindings/python/examples/quickstart.py

What gets proved

Calybris can bind the full decision path:

policy digest + input digest + decision digest + replay result

Since 0.5.0 the proof format is a written contract, not an implementation detail: docs/CALY_PROOF.md specifies every digest and chain byte-exactly, golden vectors pin them across versions and platforms, and the bundled calybris-verify CLI lets an auditor check a decision trail: chain integrity, digests, and full kernel replay against a policy artifact without running your engine.

cargo install calybris-core   # ships the calybris-verify binary

calybris-verify chain decisions.wal.jsonl

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

0.5.0 adds:

• state — record state_digest_before/after per decision; verify_trajectory rejects dropped, reordered, or forged transitions in a sequence.
• provenance (feature) — bind a policy digest to an Ed25519 signer and timestamp, non-transferable across policies.
• certificate — bind the audit bundle, state trajectory, WAL position, and signer into one fail-closed envelope.
• Golden and conformance vectors pin the byte-exact contract, so an independent reimplementation can prove itself against a fixed reference.

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.

Architecture at a glance

Ships a calybris-verify auditor CLI (chain / audit / policy, --json) so a third party can verify a decision trail without running your engine.

Install

# Rust (stable surface)

cargo add calybris-core


# Python (experimental wrappers)

pip install calybris

Local Python build: maturin develop --release or see docs/PYTHON.md.

Examples & adapters

Reference integrations that map domain objects onto the kernel:

Full command list and code samples: docs/ADAPTERS.md

Performance

CodSpeed CI (Linux x86_64, release): ~8.6M prescribe/sec, ~115 ns/decision, 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.

Security posture

• #![forbid(unsafe_code)] — no unsafe in project code.
• Fail-closed audit boundaries: verified_audit_bundle / append_verified_audited refuse to emit or log a decision that does not replay exactly.
• Tamper-evident WAL: SHA-256 hash chain, optional HMAC-SHA256 with constant-time comparison (subtle).
• Ed25519-signed policy provenance, domain-separated so a signature is non-transferable across policies, signers, and timestamps (0.5.0).
• Byte-exact proof contract (docs/CALY_PROOF.md) locked by golden + conformance vectors and cross-checked in Rust and Python (0.5.0).
• Concurrency and UB: 7 Loom exhaustive interleavings on budget ops; Miri on nightly for the library tests.
• Supply chain: cargo-audit + cargo-deny in CI; feature-matrix CI (default / no-default / async / full).
• Documented boundaries: docs/THREAT_MODEL.md (what it does not guarantee) and docs/KEY_MANAGEMENT.md (key custody and rotation).

Deployment security remains the caller's job: key storage, tenant isolation, inventory/capacity freshness, and an external audit.

Deep dive

License

Apache-2.0. See LICENSE.