calybris 0.5.5

Production-grade Python bindings for the Calybris deterministic decision and audit core

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

Module	Role
kernel	Integer-only decision kernel (~115 ns/decision); prescribe, prescribe_with_trace for per-constraint rejection counts
digest	Canonical tagged byte digests — policy / input / decision / ledger / state
verify	Full replay verification and audit bundles; fail-closed verified_audit_bundle
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 llm_routing	quickstart.py, batch_routing.py
Which venue admits an order?	cargo run --example pretrade_guard	pretrade_budget_guard.py
Which supplier fulfills?	-	orion_market.py, novamart_benchmark.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: 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

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.