# Show HN: Calybris Core, a deterministic audit engine for decisions in Rust

> Source: <https://github.com/emirhuseynrmx/calybris-core>
> Published: 2026-06-29 00:03:59+00:00

**Deterministic proof-carrying decision core** for systems that must explain and replay why an action was allowed, substituted, or rejected.

Not an LLM framework. Not an exchange or strategy engine. A domain-neutral primitive:

```
candidate + policy constraints → decision + digests + optional WAL + budget proof
```

`#![forbid(unsafe_code)]`

· unit/proptest/Loom/Miri coverage · Apache-2.0

| Use case | What Calybris does |
|---|---|
LLM routing |
Select / substitute / reject models under budget, risk, quality, latency |
Pre-trade guard |
Admit / reject candidate orders under exposure, risk, and latency limits |

Calybris is **not** an exchange, market data feed, colocation stack, or alpha engine. It is a **deterministic pre-trade decision kernel** — integer-only constraints, replay verification, and fixed-point conservation proofs.

Use Calybris when a service has to make the same decision twice and prove it got the same answer:

- route an LLM request under budget, latency, provider, and quality constraints
- reject or substitute a candidate action before it crosses a risk boundary
- write an auditable decision record to a tamper-evident WAL
- reconcile budget state with fixed-point conservation proofs

Do not use it as a hosted API, trading strategy, exchange adapter, web framework, or model orchestration platform. Calybris is the deterministic core you put behind those systems.

```
git clone https://github.com/emirhuseynrmx/calybris-core
cd calybris-core
cargo run --example quickstart
cargo run --example llm_routing
cargo run --example replay_audit
cargo add calybris-core
use calybris_core::budget::BudgetEngine;
use calybris_core::finance::{prove_conservation, ConservationProof};
use calybris_core::kernel::*;
use calybris_core::verify::{audit_bundle, verify_decision, VerifyResult};

let models = vec![
    KernelModel {
        model_id: 1,
        provider_id: 0,
        quality_bps: 9000,
        risk_ceiling_bps: 9500,
        enabled: 1,
        p95_latency_ms: 200,
        capabilities: 0,
        region_mask: ALL_REGIONS,
        input_cost_microunits_per_million_tokens: 250,
        output_cost_microunits_per_million_tokens: 1000,
    },
    KernelModel {
        model_id: 2,
        provider_id: 1,
        quality_bps: 7000,
        risk_ceiling_bps: 9500,
        enabled: 1,
        p95_latency_ms: 90,
        capabilities: 0,
        region_mask: ALL_REGIONS,
        input_cost_microunits_per_million_tokens: 25,
        output_cost_microunits_per_million_tokens: 125,
    },
];

let snapshot = PolicySnapshot::try_new(1, 1, 9600, 5500, 3500, 2, models)?;

let input = KernelInput {
    request_sequence: 1,
    requested_model_id: 1,
    input_tokens: 1000,
    output_tokens: 500,
    business_value_microunits: 100_000,
    budget_limit_microunits: 50_000_000,
    risk_bps: 1000,
    confidence_bps: 9000,
    minimum_quality_bps: 5000,
    max_p95_latency_ms: 1000,
    required_capabilities: 0,
    allowed_provider_mask: ALL_PROVIDERS,
    required_region_mask: 0,
};

let decision = snapshot.prescribe(input);
assert_eq!(verify_decision(&snapshot, input, &decision), VerifyResult::Valid);
assert!(audit_bundle(&snapshot, input, &decision).replay_valid);

let budget = BudgetEngine::new();
budget.ensure_tenant("desk-1", 100_000_000);
let proof: ConservationProof = prove_conservation(&budget)?;
assert_eq!(proof.ledger_digest_hex.len(), 64);
```

Kernel-only (no WAL):

```
cargo add calybris-core --no-default-features
```

— Integer-only decision kernel (~115ns/decision).`kernel`

`prescribe_with_trace`

exposes per-constraint rejection counts.— Policy + input + decision digests, full replay,`verify`

`DigestDecodeError`

on public API.— Ledger digest,`finance`

`FinancialCertificate`

,`ConservationProof`

,`prove_conservation`

,`certify_snapshot`

.— Tamper-evident hash chain,`wal`

`append_verified_audited`

(fail-closed),`replay_audited_wal`

.— CAS reserve/commit/release. Conservation holds after completed ops:`budget`

`remaining + reserved + committed_lifetime == initial`

. Loom + Miri in CI.—`proof`

`ProofEnvelope`

: single struct binding policy + input + decision digests + WAL position + budget proof.— Runtime`config`

`EngineConfig`

with builder pattern, validation, and budget integration (`ensure_tenant`

).—`builder`

`InputBuilder`

,`ModelBuilder`

,`PolicyBuilder`

with`BuildError`

(config + policy + catalog size enforcement).— fsync-backed snapshot save/load,`persistence`

`checkpoint_with_wal`

,`recovery_plan`

with WAL high-watermark.`async_wal`

*(feature*— Tokio-based non-blocking WAL with HMAC, chain validation, configurable sync.`async`

)`instrument`

*(feature*— Structured`observability`

)`tracing`

spans for prescribe, verify, budget, WAL.

```
prescribe → verify_decision → append_verified_audited → replay_audited_wal (fail-closed)
                ↓                        ↓
     calypol1 / calyinp1 / calydcn1    ProofEnvelope (optional)
```

Fixed-point `i64`

microcents (1 cent = 1,000,000). No `f64`

.

`committed_microcents`

—**lifetime cumulative spend**(monotonic; never decreases)`reserved_microcents`

— active holds awaiting commit/release`top_up_tenant`

— add funds without resetting lifetime spend`restore_from_snapshot`

— exclusive-recovery restore from frozen`BudgetSnapshot`

`verify_conservation`

— audit/reconciliation path (full snapshot)`PolicySnapshot::utility_for_model`

— per-model utility (not prescribe winner/runner-up)

```
budget.ensure_tenant("desk", 100_000_000);
budget.top_up_tenant("desk", 50_000_000);
let proof = prove_conservation(&budget)?;
let cert = certify_ledger(&budget);
assert!(cert.conservation_balanced);
```

| Policy API | Use |
|---|---|
`PolicySnapshot::try_new` |
Production — validates catalog + BPS (`MAX_BPS` , etc.) |
`PolicySnapshot::new_unchecked` |
Tests / fuzz only — never serve without explicit `validate()` |
`PolicySnapshot::new` |
Deprecated alias for `new_unchecked` |

| Feature | What it adds | Dependencies |
|---|---|---|
`wal` (default) |
Hash-chained WAL, HMAC-SHA256, audited append | `serde` , `hmac` , `subtle` |
`async` |
Tokio-based async WAL | `wal` + `tokio` |
`observability` |
Structured tracing spans/events | `tracing` |
`full` |
All of the above | — |

```
cargo add calybris-core                        # default (wal)
cargo add calybris-core --features full        # everything
cargo add calybris-core --no-default-features  # kernel only
use calybris_core::config::EngineConfig;
use calybris_core::builder::{InputBuilder, ModelBuilder, PolicyBuilder};

let config = EngineConfig::new()
    .latency_penalty(3)
    .hard_risk_limit(9_500)
    .default_exposure_cap(500_000_000);

let snapshot = PolicyBuilder::new(config)
    .epochs(1, 1)
    .model(ModelBuilder::new(1, 0).quality(9500).cost(250, 1000).build())
    .model(ModelBuilder::new(2, 1).quality(7000).cost(25, 125).build())
    .build()?;

let input = InputBuilder::new(1, 1)
    .tokens(1000, 500)
    .business_value(100_000)
    .risk(1000, 9000)
    .minimum_quality(5000)
    .build();

let decision = snapshot.prescribe(input);
use calybris_core::persistence::{checkpoint_with_wal, restore, recovery_plan};

// Checkpoint budget state alongside WAL position (fsync-backed)
let snap = checkpoint_with_wal(&budget, Path::new("budget.json"), wal.sequence())?;

// After crash: figure out what needs replay
let plan = recovery_plan(Path::new("budget.json"), Path::new("wal.jsonl"))?;
println!("{} WAL entries to replay", plan.entries_to_replay);

// Restore from last checkpoint
let fresh = BudgetEngine::new();
restore(&fresh, Path::new("budget.json"))?;
js
use calybris_core::proof::ProofEnvelopeBuilder;

let envelope = ProofEnvelopeBuilder::new(&snapshot, input, &decision)
    .wal(wal_entry.sequence, wal_entry.entry_hash)
    .budget(budget_snap.version, ledger_digest_hex)
    .build();

assert!(envelope.is_complete()); // replay + WAL + budget all present
cargo run --example quickstart
cargo run --example production_gateway  # full pipeline: config→build→prescribe→verify→budget→WAL→checkpoint→recovery
cargo run --example llm_routing
cargo run --example hft_pretrade_guard
cargo run --example replay_audit
cargo run --example finance_hft       # throughput benchmark
cargo run --example route_decision    # legacy alias
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-features
cargo test --no-default-features
RUSTFLAGS='--cfg loom' LOOM_MAX_PREEMPTIONS=3 cargo test --test budget_loom
cargo +nightly miri test --lib --all-features   # see docs/MIRI.md for CI filters
cargo doc --no-deps
```

Extensive test coverage across unit, property-based (proptest), 7 Loom exhaustive concurrency, and Miri UB detection targets. Feature matrix CI: `default`

, `no-default-features`

, `async`

, `full`

. See CI for the current test count.

Calybris verifies decisions and conservation proofs — it does **not** auto-invoke `verify_decision`

in your hot path. **You** must call it at audit boundaries:

```
prescribe → verify_decision → (optional WAL / prove_conservation)
```

Use `append_verified_audited`

(not `append_audited`

) at production boundaries — it verifies before writing. See [docs/AUDIT_GUIDE.md](/emirhuseynrmx/calybris-core/blob/main/docs/AUDIT_GUIDE.md).

For fail-closed audit boundaries, use the verified helpers:

``` js
use calybris_core::verify::verified_audit_bundle;

let bundle = verified_audit_bundle(&snapshot, input, &decision)?;
assert!(bundle.replay_valid);
```

With the `wal`

feature enabled, `append_verified_audited`

verifies before writing. Invalid or tampered decisions do not enter the log:

``` js
use calybris_core::wal::WalWriter;

let mut wal = WalWriter::open(std::path::Path::new("decisions.jsonl"))?;
wal.append_verified_audited(&snapshot, input, decision, "metadata")?;
```

Invariant docs, adversarial tests, Loom, Miri, and supply-chain checks are in place for third-party review. A paid external audit is still your responsibility — see [docs/AUDIT_GUIDE.md](/emirhuseynrmx/calybris-core/blob/main/docs/AUDIT_GUIDE.md) §7.

`#![forbid(unsafe_code)]`

— zero unsafe blocks`cargo-audit`

+`cargo-deny`

in CI- Miri on nightly — UB detection for all lib tests
- 7 Loom exhaustive concurrency tests for budget operations
- HMAC-SHA256 keyed tamper-evident WAL with constant-time comparison (
`subtle`

) - Fail-closed
`append_verified_audited`

— invalid decisions never enter the log - fsync-backed snapshot persistence with atomic rename
- Feature matrix CI:
`default`

,`no-default-features`

,`async`

,`full`

- Exchange gateway, market data, or order lifecycle
- Thompson Sampling / adaptive routing
- HTTP API server

See [emirhuseyin.tech/engine](https://emirhuseyin.tech/engine) for the full proprietary stack.

Apache-2.0. See [LICENSE](/emirhuseynrmx/calybris-core/blob/main/LICENSE).