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 Calybris when... | Do not use it for... | |----------------------|--------------------------| | Decisions must be deterministic and replay-auditable | Inventory, WMS, label printing, carrier booking | | You need hard gates (budget, risk, latency, region, capability) in your control plane | A hosted routing API or managed decision service | | Post-mortems and compliance need proof bundles, not log grep | Live market data, order matching, exchange connectivity |

Stability model

| Layer | Status | Notes | |-------|--------|-------| | calybris-core (Rust) | Stable | crates.io: this is the contract | | calybris (Python) | Production-capable / pre-1.0 API | First-class PyO3 surface for decisions, signed policy provenance, state proofs, receipts, keyed WAL, anchors, and replay | | calybris_commerce (Python) | Experimental / pre-1.0 | Thicker adapter (orders, suppliers, batch routing), still calls the same Rust kernel; API may change |

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 statedigestbefore/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

| Module | Role | |--------|------| | kernel | Integer-only decision kernel (~115 ns/decision); prescribe, prescribewithtrace for per-constraint rejection counts | | digest | Canonical tagged byte digests — policy / input / decision / ledger / state | | verify | Full replay verification and audit bundles; fail-closed verifiedauditbundle | | certificate | Compatibility envelope for 0.5.0 certificate artifacts | | receipt | Canonical claims digest + optional signature binding decision, state, and WAL evidence (0.5.5) | | state | Domain-state digest trajectories; verify_trajectory rejects dropped/reordered/forged steps (0.5.0) | | provenance | Ed25519-signed policies, domain-separated (0.5.0, feature) | | wal | Hash-chained WAL; keyed HMAC, trusted head anchors, and single-writer enforcement | | budget | CAS reserve/commit/release; remaining + reserved + committed == initial (Loom + Miri) | | finance | Ledger digests, conservation proofs and certificates | | proof | ProofEnvelope: policy + input + decision digests + WAL position + budget proof | | builder / config | Hard-to-misuse constructors with validation | | persistence | fsync-backed snapshot save/load, crash recovery_plan | | async_wal / instrument | Tokio WAL (feature async), tracing spans (feature observability) |

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:

| Question | Rust | Python | |----------|------|--------| | Which model/provider? | cargo run --example llmrouting | quickstart.py, batchrouting.py | | Which venue admits an order? | cargo run --example pretradeguard | pretradebudget_guard.py | | Which supplier fulfills? | - | orionmarket.py, novamartbenchmark.py |

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: verifiedauditbundle / appendverifiedaudited

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.

• visitverifiedwal* 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

| Doc | Contents | |-----|----------| | docs/AUDIT_GUIDE.md | Module map, audit commands, external review checklist | | docs/CALY_PROOF.md | CALY-PROOF v1 digest and proof contract | | docs/THREAT_MODEL.md | Assets, trust boundaries, attackers | | docs/KEY_MANAGEMENT.md | HMAC / Ed25519 key custody and rotation | | docs/BENCHMARKS.md | Throughput provenance and reproduction | | docs/SECURITY_INVARIANTS.md | Invariants I1-I10 and test mapping | | docs/MIRI.md | UB detection scope in CI | | docs/PYTHON.md | Python wrappers vs Rust core, commerce API notes | | SECURITY.md | Vulnerability reporting, supported versions | | CONTRIBUTING.md | Dev setup, test gate, PR expectations |

License

Apache-2.0. See LICENSE.