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

Use cases

Four reference mappings onto one kernel. Each is a runnable example in this repository, not a pitch.

Model and provider routing. A gateway picks among premium, fast, and budget providers under quality, latency, risk, provider, and budget ceilings. Every decision is verified before it enters the audited WAL, so "why did this request get the premium model" is answered from the proof rather than from log archaeology. → cargo run --example llm_routing

Pre-trade admission. A desk runs a VWAP algo at the cash open. Each child order clears a policy gate (an eligible venue under risk, latency, quality, and fee caps) and an exposure gate (notional reserved against the desk budget, routing fees committed on admit). The ledger carries the conservation proof remaining + reserved + committed == initial, in checked integers. Calybris owns the two gates and the proof — not the OMS, the market-data feed, or the matching engine. → cargo run --example pretrade_guard

Fulfillment and supplier routing. 10,000 orders across 8 courier networks with distinct SLAs, regional coverage, and risk tolerances. Substitutions are recorded as decisions, so "why this courier, for this order" stays answerable months later. → python bindings/python/examples/orion_market.py

Defending a policy change with numbers. The same catalog evaluated under strict, medium, and relaxed profiles, reporting fulfillment and substitution rates, cost percentiles, batch and single-decision throughput, resident memory, and the audit success and tamper-detection counts for the resulting trail. Copy this one when a policy change needs evidence instead of intuition. → python bindings/python/examples/novamart_benchmark.py

The domain objects differ. The kernel, the digests, and the replay contract do not.

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.7, 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. See the 0.5.7 trust-release migration for the canonical production path and CALY-PROOF v1 compatibility boundary.

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

calybris-verify audit rotated.wal.jsonl --policy policy-v1.json --policy policy-v2.json --json

0.5.7 hardens the production trust boundary:

• receipt::verify_receipt_full verifies replay, claims, trusted signature, state anchor, and WAL anchor as one fail-closed operation.
• Trusted policy construction canonicalizes catalog order, reserves model ID 0, and rejects catalogs that cannot fit public decision counters.
• Ledger digests bind WAL watermarks and reservation allocator state; coordinated checkpoints commit immutable snapshot/anchor generations behind one atomic manifest, with an additive loader that verifies the actual WAL.
• Library and CLI WAL replay resolve the exact policy per record across policy rotations; CLI --json verdicts use standards-compliant JSON escaping.
• 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_complete_trajectory binds genesis and the expected terminal step, while verify_trajectory remains an unanchored compatibility-fragment check.
• provenance (feature) — bind a policy digest to an Ed25519 signer and timestamp, non-transferable across policies.
• certificate — CALY-PROOF v1 compatibility envelope; its optional signature attests policy provenance only. Use signed receipts to bind full evidence.
• 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.7 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.