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 still owns correctness and replay semantics; Python calls those exact Rust implementations rather than reimplementing security-sensitive logic. Starting with 0.5.5, the core Python package exposes the production trust boundary and is tested as an installed abi3 wheel. The Python API remains pre-1.0, so pin minor versions even though its runtime integrity guarantees match the Rust core.

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 chain decisions.wal.jsonl --anchor trusted-head.json
calybris-verify audit decisions.wal.jsonl --policy policy.json

0.5.5 hardens the production trust boundary:

• receipt binds the decision, state evidence, WAL position, and optional Ed25519 receipt signer into one canonical claims digest.
• WalAnchor detects clean suffix truncation when the trusted head is stored outside the WAL file.
• Sync and async WAL writers enforce one active writer per file.
• Keyed WAL APIs reject HMAC keys shorter than 32 bytes.
• prescribe_checked and checked batch/trace APIs validate untrusted Rust inputs.
• Python exposes the same signed policies, state-chain transitions, decision receipts, keyed audited WAL, durable anchors, and replay verification.

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 (production-capable core binding; pre-1.0 API)
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.

0.5.5 also carries a release-blocking production torture suite covering a 64-model checked kernel, state trajectories, signed receipts, keyed audited WAL, suffix-truncation detection, contended budgets, and a 25,000-tenant ledger.

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).
• Trusted WalAnchor verification detects a cleanly removed WAL suffix; the hash chain alone validates only the records still present.
• Anchored recovery APIs refuse to build a recovery plan from a valid but incomplete WAL prefix.
• visit_verified_wal* streams verified entries, so CLI audit and recovery planning do not retain the complete log in memory.
• Signed decision receipts bind optional state and WAL evidence to the exact replay-verified decision.
• 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.
• Security CI: Semgrep Rust/Python/secrets/security-audit, cargo-audit, and cargo-deny; feature matrix covers 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.