{"slug": "show-hn-calybris-core-a-deterministic-audit-engine-for-decisions-in-rust", "title": "Show HN: Calybris Core, a deterministic audit engine for decisions in Rust", "summary": "Calybris Core, a deterministic audit engine for decisions written in Rust, has been released as an open-source project on GitHub. The engine provides a domain-neutral primitive for systems that must explain and replay why an action was allowed, substituted, or rejected, with applications in LLM routing and pre-trade risk checks. It features integer-only constraints, replay verification, and fixed-point conservation proofs, and is designed to be embedded in other systems rather than used as a standalone service.", "body_md": "**Deterministic proof-carrying decision core** for systems that must explain and replay why an action was allowed, substituted, or rejected.\n\nNot an LLM framework. Not an exchange or strategy engine. A domain-neutral primitive:\n\n```\ncandidate + policy constraints → decision + digests + optional WAL + budget proof\n```\n\n`#![forbid(unsafe_code)]`\n\n· unit/proptest/Loom/Miri coverage · Apache-2.0\n\n| Use case | What Calybris does |\n|---|---|\nLLM routing |\nSelect / substitute / reject models under budget, risk, quality, latency |\nPre-trade guard |\nAdmit / reject candidate orders under exposure, risk, and latency limits |\n\nCalybris 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.\n\nUse Calybris when a service has to make the same decision twice and prove it got the same answer:\n\n- route an LLM request under budget, latency, provider, and quality constraints\n- reject or substitute a candidate action before it crosses a risk boundary\n- write an auditable decision record to a tamper-evident WAL\n- reconcile budget state with fixed-point conservation proofs\n\nDo 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.\n\n```\ngit clone https://github.com/emirhuseynrmx/calybris-core\ncd calybris-core\ncargo run --example quickstart\ncargo run --example llm_routing\ncargo run --example replay_audit\ncargo add calybris-core\nuse calybris_core::budget::BudgetEngine;\nuse calybris_core::finance::{prove_conservation, ConservationProof};\nuse calybris_core::kernel::*;\nuse calybris_core::verify::{audit_bundle, verify_decision, VerifyResult};\n\nlet models = vec![\n    KernelModel {\n        model_id: 1,\n        provider_id: 0,\n        quality_bps: 9000,\n        risk_ceiling_bps: 9500,\n        enabled: 1,\n        p95_latency_ms: 200,\n        capabilities: 0,\n        region_mask: ALL_REGIONS,\n        input_cost_microunits_per_million_tokens: 250,\n        output_cost_microunits_per_million_tokens: 1000,\n    },\n    KernelModel {\n        model_id: 2,\n        provider_id: 1,\n        quality_bps: 7000,\n        risk_ceiling_bps: 9500,\n        enabled: 1,\n        p95_latency_ms: 90,\n        capabilities: 0,\n        region_mask: ALL_REGIONS,\n        input_cost_microunits_per_million_tokens: 25,\n        output_cost_microunits_per_million_tokens: 125,\n    },\n];\n\nlet snapshot = PolicySnapshot::try_new(1, 1, 9600, 5500, 3500, 2, models)?;\n\nlet input = KernelInput {\n    request_sequence: 1,\n    requested_model_id: 1,\n    input_tokens: 1000,\n    output_tokens: 500,\n    business_value_microunits: 100_000,\n    budget_limit_microunits: 50_000_000,\n    risk_bps: 1000,\n    confidence_bps: 9000,\n    minimum_quality_bps: 5000,\n    max_p95_latency_ms: 1000,\n    required_capabilities: 0,\n    allowed_provider_mask: ALL_PROVIDERS,\n    required_region_mask: 0,\n};\n\nlet decision = snapshot.prescribe(input);\nassert_eq!(verify_decision(&snapshot, input, &decision), VerifyResult::Valid);\nassert!(audit_bundle(&snapshot, input, &decision).replay_valid);\n\nlet budget = BudgetEngine::new();\nbudget.ensure_tenant(\"desk-1\", 100_000_000);\nlet proof: ConservationProof = prove_conservation(&budget)?;\nassert_eq!(proof.ledger_digest_hex.len(), 64);\n```\n\nKernel-only (no WAL):\n\n```\ncargo add calybris-core --no-default-features\n```\n\n— Integer-only decision kernel (~115ns/decision).`kernel`\n\n`prescribe_with_trace`\n\nexposes per-constraint rejection counts.— Policy + input + decision digests, full replay,`verify`\n\n`DigestDecodeError`\n\non public API.— Ledger digest,`finance`\n\n`FinancialCertificate`\n\n,`ConservationProof`\n\n,`prove_conservation`\n\n,`certify_snapshot`\n\n.— Tamper-evident hash chain,`wal`\n\n`append_verified_audited`\n\n(fail-closed),`replay_audited_wal`\n\n.— CAS reserve/commit/release. Conservation holds after completed ops:`budget`\n\n`remaining + reserved + committed_lifetime == initial`\n\n. Loom + Miri in CI.—`proof`\n\n`ProofEnvelope`\n\n: single struct binding policy + input + decision digests + WAL position + budget proof.— Runtime`config`\n\n`EngineConfig`\n\nwith builder pattern, validation, and budget integration (`ensure_tenant`\n\n).—`builder`\n\n`InputBuilder`\n\n,`ModelBuilder`\n\n,`PolicyBuilder`\n\nwith`BuildError`\n\n(config + policy + catalog size enforcement).— fsync-backed snapshot save/load,`persistence`\n\n`checkpoint_with_wal`\n\n,`recovery_plan`\n\nwith WAL high-watermark.`async_wal`\n\n*(feature*— Tokio-based non-blocking WAL with HMAC, chain validation, configurable sync.`async`\n\n)`instrument`\n\n*(feature*— Structured`observability`\n\n)`tracing`\n\nspans for prescribe, verify, budget, WAL.\n\n```\nprescribe → verify_decision → append_verified_audited → replay_audited_wal (fail-closed)\n                ↓                        ↓\n     calypol1 / calyinp1 / calydcn1    ProofEnvelope (optional)\n```\n\nFixed-point `i64`\n\nmicrocents (1 cent = 1,000,000). No `f64`\n\n.\n\n`committed_microcents`\n\n—**lifetime cumulative spend**(monotonic; never decreases)`reserved_microcents`\n\n— active holds awaiting commit/release`top_up_tenant`\n\n— add funds without resetting lifetime spend`restore_from_snapshot`\n\n— exclusive-recovery restore from frozen`BudgetSnapshot`\n\n`verify_conservation`\n\n— audit/reconciliation path (full snapshot)`PolicySnapshot::utility_for_model`\n\n— per-model utility (not prescribe winner/runner-up)\n\n```\nbudget.ensure_tenant(\"desk\", 100_000_000);\nbudget.top_up_tenant(\"desk\", 50_000_000);\nlet proof = prove_conservation(&budget)?;\nlet cert = certify_ledger(&budget);\nassert!(cert.conservation_balanced);\n```\n\n| Policy API | Use |\n|---|---|\n`PolicySnapshot::try_new` |\nProduction — validates catalog + BPS (`MAX_BPS` , etc.) |\n`PolicySnapshot::new_unchecked` |\nTests / fuzz only — never serve without explicit `validate()` |\n`PolicySnapshot::new` |\nDeprecated alias for `new_unchecked` |\n\n| Feature | What it adds | Dependencies |\n|---|---|---|\n`wal` (default) |\nHash-chained WAL, HMAC-SHA256, audited append | `serde` , `hmac` , `subtle` |\n`async` |\nTokio-based async WAL | `wal` + `tokio` |\n`observability` |\nStructured tracing spans/events | `tracing` |\n`full` |\nAll of the above | — |\n\n```\ncargo add calybris-core                        # default (wal)\ncargo add calybris-core --features full        # everything\ncargo add calybris-core --no-default-features  # kernel only\nuse calybris_core::config::EngineConfig;\nuse calybris_core::builder::{InputBuilder, ModelBuilder, PolicyBuilder};\n\nlet config = EngineConfig::new()\n    .latency_penalty(3)\n    .hard_risk_limit(9_500)\n    .default_exposure_cap(500_000_000);\n\nlet snapshot = PolicyBuilder::new(config)\n    .epochs(1, 1)\n    .model(ModelBuilder::new(1, 0).quality(9500).cost(250, 1000).build())\n    .model(ModelBuilder::new(2, 1).quality(7000).cost(25, 125).build())\n    .build()?;\n\nlet input = InputBuilder::new(1, 1)\n    .tokens(1000, 500)\n    .business_value(100_000)\n    .risk(1000, 9000)\n    .minimum_quality(5000)\n    .build();\n\nlet decision = snapshot.prescribe(input);\nuse calybris_core::persistence::{checkpoint_with_wal, restore, recovery_plan};\n\n// Checkpoint budget state alongside WAL position (fsync-backed)\nlet snap = checkpoint_with_wal(&budget, Path::new(\"budget.json\"), wal.sequence())?;\n\n// After crash: figure out what needs replay\nlet plan = recovery_plan(Path::new(\"budget.json\"), Path::new(\"wal.jsonl\"))?;\nprintln!(\"{} WAL entries to replay\", plan.entries_to_replay);\n\n// Restore from last checkpoint\nlet fresh = BudgetEngine::new();\nrestore(&fresh, Path::new(\"budget.json\"))?;\njs\nuse calybris_core::proof::ProofEnvelopeBuilder;\n\nlet envelope = ProofEnvelopeBuilder::new(&snapshot, input, &decision)\n    .wal(wal_entry.sequence, wal_entry.entry_hash)\n    .budget(budget_snap.version, ledger_digest_hex)\n    .build();\n\nassert!(envelope.is_complete()); // replay + WAL + budget all present\ncargo run --example quickstart\ncargo run --example production_gateway  # full pipeline: config→build→prescribe→verify→budget→WAL→checkpoint→recovery\ncargo run --example llm_routing\ncargo run --example hft_pretrade_guard\ncargo run --example replay_audit\ncargo run --example finance_hft       # throughput benchmark\ncargo run --example route_decision    # legacy alias\ncargo fmt --check\ncargo clippy --all-targets -- -D warnings\ncargo test --all-features\ncargo test --no-default-features\nRUSTFLAGS='--cfg loom' LOOM_MAX_PREEMPTIONS=3 cargo test --test budget_loom\ncargo +nightly miri test --lib --all-features   # see docs/MIRI.md for CI filters\ncargo doc --no-deps\n```\n\nExtensive test coverage across unit, property-based (proptest), 7 Loom exhaustive concurrency, and Miri UB detection targets. Feature matrix CI: `default`\n\n, `no-default-features`\n\n, `async`\n\n, `full`\n\n. See CI for the current test count.\n\nCalybris verifies decisions and conservation proofs — it does **not** auto-invoke `verify_decision`\n\nin your hot path. **You** must call it at audit boundaries:\n\n```\nprescribe → verify_decision → (optional WAL / prove_conservation)\n```\n\nUse `append_verified_audited`\n\n(not `append_audited`\n\n) at production boundaries — it verifies before writing. See [docs/AUDIT_GUIDE.md](/emirhuseynrmx/calybris-core/blob/main/docs/AUDIT_GUIDE.md).\n\nFor fail-closed audit boundaries, use the verified helpers:\n\n``` js\nuse calybris_core::verify::verified_audit_bundle;\n\nlet bundle = verified_audit_bundle(&snapshot, input, &decision)?;\nassert!(bundle.replay_valid);\n```\n\nWith the `wal`\n\nfeature enabled, `append_verified_audited`\n\nverifies before writing. Invalid or tampered decisions do not enter the log:\n\n``` js\nuse calybris_core::wal::WalWriter;\n\nlet mut wal = WalWriter::open(std::path::Path::new(\"decisions.jsonl\"))?;\nwal.append_verified_audited(&snapshot, input, decision, \"metadata\")?;\n```\n\nInvariant 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.\n\n`#![forbid(unsafe_code)]`\n\n— zero unsafe blocks`cargo-audit`\n\n+`cargo-deny`\n\nin CI- Miri on nightly — UB detection for all lib tests\n- 7 Loom exhaustive concurrency tests for budget operations\n- HMAC-SHA256 keyed tamper-evident WAL with constant-time comparison (\n`subtle`\n\n) - Fail-closed\n`append_verified_audited`\n\n— invalid decisions never enter the log - fsync-backed snapshot persistence with atomic rename\n- Feature matrix CI:\n`default`\n\n,`no-default-features`\n\n,`async`\n\n,`full`\n\n- Exchange gateway, market data, or order lifecycle\n- Thompson Sampling / adaptive routing\n- HTTP API server\n\nSee [emirhuseyin.tech/engine](https://emirhuseyin.tech/engine) for the full proprietary stack.\n\nApache-2.0. See [LICENSE](/emirhuseynrmx/calybris-core/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-calybris-core-a-deterministic-audit-engine-for-decisions-in-rust", "canonical_source": "https://github.com/emirhuseynrmx/calybris-core", "published_at": "2026-06-29 00:03:59+00:00", "updated_at": "2026-06-29 00:28:50.967287+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools"], "entities": ["Calybris Core", "GitHub", "Rust"], "alternates": {"html": "https://wpnews.pro/news/show-hn-calybris-core-a-deterministic-audit-engine-for-decisions-in-rust", "markdown": "https://wpnews.pro/news/show-hn-calybris-core-a-deterministic-audit-engine-for-decisions-in-rust.md", "text": "https://wpnews.pro/news/show-hn-calybris-core-a-deterministic-audit-engine-for-decisions-in-rust.txt", "jsonld": "https://wpnews.pro/news/show-hn-calybris-core-a-deterministic-audit-engine-for-decisions-in-rust.jsonld"}}