{"slug": "building-a-replayable-decision-kernel-in-rust", "title": "Building a Replayable Decision Kernel in Rust", "summary": "A developer built Calybris Core, a Rust crate that provides a deterministic, replayable decision kernel for systems that need to prove decisions after the fact. The crate evaluates candidates against policy snapshots to produce decisions with digests and optional write-ahead logs, enabling independent verification that the same input and policy yield the same result. It avoids floating-point arithmetic in favor of integer amounts and basis points to ensure repeatable behavior.", "body_md": "I built [Calybris Core](https://github.com/emirhuseynrmx/calybris-core) because I kept running into the same uncomfortable question in decision-heavy systems:\n\nAfter the system says \"yes\", \"no\", or \"use this instead\", what exactly can we prove later?\n\nNot prove in the formal-methods sense. I mean the practical engineering version:\n\nCalybris Core is my attempt to make that boundary small, deterministic, and boring.\n\nIt is not an LLM framework.\n\nIt is not an exchange.\n\nIt is not a strategy engine.\n\nIt is not a web service.\n\nIt is a Rust core primitive:\n\n``` php\ncandidate + policy constraints -> decision + digests + optional WAL + budget proof\n```\n\nThe first reference examples are LLM routing and pre-trade admission guards, but the crate itself is domain-neutral.\n\nRepo: [github.com/emirhuseynrmx/calybris-core](https://github.com/emirhuseynrmx/calybris-core)\n\nCrate: [crates.io/crates/calybris-core](https://crates.io/crates/calybris-core)\n\nDocs: [docs.rs/calybris-core](https://docs.rs/calybris-core)\n\nA lot of systems have a hidden decision point that looks simple from the outside:\n\n```\nrequest comes in\nsystem checks constraints\nsystem returns allow / substitute / reject\n```\n\nBut when something goes wrong, that simple decision becomes hard to reconstruct.\n\nMaybe the model was changed.\n\nMaybe a budget was exceeded.\n\nMaybe a cheaper fallback was selected.\n\nMaybe an operator needs to explain why an action was rejected.\n\nMaybe an audit log was modified after the fact.\n\nThe typical response is to add more logs.\n\nThat helps, but logs alone are not the same as replayable decisions. I wanted the core decision result to carry enough structure that an independent verifier can ask:\n\nIf I replay the same input against the same policy snapshot, do I get the same decision?\n\nThat became the central design constraint.\n\nThe `kernel`\n\nmodule evaluates a `KernelInput`\n\nagainst a validated `PolicySnapshot`\n\n.\n\nThe result is a `KernelDecision`\n\n:\n\n`ExecuteRequested`\n\n`Substitute`\n\n`Reject`\n\nThe decision contains the selected candidate, reason, estimated cost, utility, counterfactual fields, evaluated/eligible counts, and policy/catalog epochs.\n\nThe important part is not the specific domain. The important part is that the decision is deterministic and replayable.\n\nIn code, the shape is intentionally direct:\n\n```\nuse calybris_core::kernel::*;\nuse calybris_core::verify::{verify_decision, VerifyResult};\n\nlet decision = snapshot.prescribe(input);\n\nassert_eq!(\n    verify_decision(&snapshot, input, &decision),\n    VerifyResult::Valid\n);\n```\n\nThe hot path deliberately avoids:\n\nThe crate root uses:\n\n```\n#![forbid(unsafe_code)]\n```\n\nThat is not magic, but it is a useful line in the sand.\n\nThe reference use cases both involve costs, budgets, confidence, risk, and utility.\n\nIt would be easy to reach for `f64`\n\n. I avoided it.\n\nCalybris uses integer amounts and basis points. Financial amounts are fixed-point microcents. Quality, risk, confidence, and policy thresholds are represented as integer basis points.\n\nThat keeps replay behavior less surprising.\n\nFor audit-oriented code, \"close enough\" is a dangerous phrase. If a decision depends on a threshold, I want the arithmetic to be explicit and repeatable.\n\nReplay alone is not enough. You also need stable fingerprints.\n\nCalybris computes canonical SHA-256 digests for:\n\nThe digest layouts are version-tagged byte layouts, not hashes of arbitrary JSON.\n\nThat distinction matters. JSON is great for transport and inspection, but field order and serialization choices are not a good audit boundary.\n\nThe digest tags are explicit:\n\n```\ncalypol1\ncalyinp1\ncalydcn1\ncalyldg1\n```\n\nPolicy models are sorted before hashing. Ledger tenants are sorted before hashing. A logically equivalent snapshot should not get a different fingerprint because a map happened to iterate differently.\n\nA decision can be wrapped in an audit bundle:\n\n```\npolicy digest\ninput digest\ndecision digest\nreplay_valid\n```\n\nThe verifier checks the structural decision, not just a string.\n\nIf you change the input, replay fails.\n\nIf you change the decision, replay fails.\n\nIf you use the wrong policy, replay fails.\n\nIf the digest fields do not match canonical recomputation, replay fails.\n\nThat is the reason I have been using the phrase \"proof-carrying decision core\", although I am still looking for feedback on whether that wording is too strong.\n\nTo be clear: this is not a formal proof system. It is a replayable evidence bundle.\n\nThe crate also includes an optional write-ahead log.\n\nEach WAL entry contains:\n\nThe unkeyed mode is useful for corruption detection and basic tamper evidence. The keyed mode uses HMAC-SHA256, which is the mode you would use if an attacker might rewrite entries and recompute hashes.\n\nThe audited WAL path looks like this:\n\n``` php\nprescribe\n  -> audit_bundle\n  -> append_audited\n  -> replay_audited_wal\n```\n\nReplay fails closed if the chain is broken or if any policy/input/decision digest does not match.\n\nI intentionally did not put secret storage, key rotation, file locking, or multi-process coordination inside this crate. Those are deployment concerns and should be owned by the embedding system.\n\nThe budget engine is another small core primitive.\n\nThe invariant is:\n\n```\nremaining + reserved + committed_lifetime == initial\n```\n\nA reservation removes spendable balance.\n\nA commit turns a reservation into lifetime committed spend.\n\nA release returns the hold.\n\nA top-up extends initial and remaining budget.\n\nThe budget engine uses CAS for the hot balance updates and mutex-protected metadata maps for the surrounding state.\n\nThe invariant is checked on frozen snapshots. Multi-step operations may have transient internal states, so the docs are careful not to claim every mid-operation snapshot is linearizable.\n\nThat distinction matters. Audit docs should say what is guaranteed, not what sounds good.\n\nCalybris is narrower than a rules engine.\n\nIt does not try to provide a policy language. It does not parse arbitrary user rules. It does not evaluate scripts.\n\nThe current kernel is closer to:\n\n```\nrank candidates under hard constraints\nreturn the best positive-utility candidate\notherwise reject\n```\n\nThat narrowness is intentional. I wanted the core to be small enough to reason about, test, replay, and document.\n\nA larger product can put a policy language above this layer. Calybris is the deterministic bottom layer.\n\nThe project has tests for the parts I would worry about first:\n\nThe CI runs MSRV and stable jobs, clippy with warnings denied, docs, examples, proptest-heavy jobs, Loom, Miri, cargo-audit, and cargo-deny.\n\nThat does not make it \"audited\". It does make it less hand-wavy.\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\n```\n\nUse it as a dependency:\n\n```\ncargo add calybris-core\n```\n\nKernel-only, without WAL:\n\n```\ncargo add calybris-core --no-default-features\n```\n\nThe current release is `v0.3.10`\n\n.\n\nRelease notes:\n\n[github.com/emirhuseynrmx/calybris-core/releases/tag/v0.3.10](https://github.com/emirhuseynrmx/calybris-core/releases/tag/v0.3.10)\n\nThe crate is Apache-2.0 and usable, but I would not describe it as a complete production platform.\n\nIt is a core primitive. If you embed it in a production system, you still own:\n\nI would especially like feedback from Rust, security, infra, and systems people on:\n\nThe repo is here:", "url": "https://wpnews.pro/news/building-a-replayable-decision-kernel-in-rust", "canonical_source": "https://dev.to/emirhuseyininci/building-a-replayable-decision-kernel-in-rust-nl4", "published_at": "2026-06-26 22:28:01+00:00", "updated_at": "2026-06-26 23:34:11.712321+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure"], "entities": ["Calybris Core", "Rust", "SHA-256"], "alternates": {"html": "https://wpnews.pro/news/building-a-replayable-decision-kernel-in-rust", "markdown": "https://wpnews.pro/news/building-a-replayable-decision-kernel-in-rust.md", "text": "https://wpnews.pro/news/building-a-replayable-decision-kernel-in-rust.txt", "jsonld": "https://wpnews.pro/news/building-a-replayable-decision-kernel-in-rust.jsonld"}}