Skip to main content

wardline_core/
lib.rs

1//! Core vocabulary and execution engine for Wardline.
2//!
3//! Wardline evaluates guardrails inline and synchronously, in the caller's
4//! request path: a check returns a blocking verdict *before* an action is
5//! taken or an LLM response is released. No queue, no separate service, no
6//! async runtime — a blocked action never happens rather than being detected
7//! shortly after it did.
8//!
9//! | Type | Role |
10//! |---|---|
11//! | [`Guard`] | One check. The trait you implement. |
12//! | [`Verdict`] | What a guard decided: allow, block, or modify. |
13//! | [`GuardError`] | Why a guard reached no decision at all. |
14//! | [`FailPolicy`] | What the pipeline does about that failure. |
15//! | [`Context`] | Per-request metadata and the deadline. |
16//! | [`Deadline`] | A cooperative wall-clock bound. |
17//! | [`Pipeline`] | An ordered list of guards, run in place. |
18//! | [`Trace`] | The bounded record of what each guard did. |
19//! | [`Metrics`] | Optional per-guard counters (allow/block/error/panic). |
20//!
21//! The key distinction: [`Verdict::Block`] means the guard said *no*;
22//! [`GuardError`] means it said *nothing*. Failures are resolved by the
23//! failing guard's own [`FailPolicy`], which defaults to
24//! [`FailPolicy::FailClosed`], so a broken guard doesn't silently stop
25//! guarding.
26//!
27//! [`Pipeline::evaluate`] runs guards in order, stops at the first block, and
28//! returns the decision together with its [`Trace`] — so a caller can log
29//! *why* something was refused, not just that it was. A panic inside a guard
30//! becomes [`GuardError::Panicked`] and is resolved through that guard's
31//! [`FailPolicy`]; it never unwinds past the caller.
32//!
33//! Enable the `tracing` feature to emit a `wardline.evaluate` span and a
34//! `wardline.guard` span per check, including an error event when a guard
35//! panics. Without that feature this crate still depends on nothing outside
36//! `std`. See `AGENTS.md` for the architectural invariants.
37//!
38//! # Example
39//!
40//! ```
41//! use wardline_core::{Context, Guard, GuardError, Verdict};
42//!
43//! struct NoProfanity;
44//!
45//! impl Guard for NoProfanity {
46//!     type Input = str;
47//!     type Output = ();
48//!
49//!     fn check(&self, input: &str, _ctx: &Context) -> Result<Verdict, GuardError> {
50//!         if input.contains("darn") {
51//!             return Ok(Verdict::block("profanity detected"));
52//!         }
53//!         Ok(Verdict::Allow)
54//!     }
55//!
56//!     fn name(&self) -> &'static str {
57//!         "no_profanity"
58//!     }
59//! }
60//!
61//! let ctx = Context::new();
62//! assert_eq!(NoProfanity.check("hello there", &ctx), Ok(Verdict::Allow));
63//! assert!(NoProfanity.check("well darn", &ctx).is_ok_and(|v| v.is_block()));
64//! ```
65
66#![forbid(unsafe_code)]
67#![deny(missing_docs)]
68
69mod context;
70mod deadline;
71mod error;
72mod guard;
73mod metrics;
74mod observe;
75mod pipeline;
76mod policy;
77mod trace;
78mod verdict;
79
80pub use context::{Context, Value};
81pub use deadline::Deadline;
82pub use error::GuardError;
83pub use guard::Guard;
84pub use metrics::{GuardCounters, InMemoryMetrics, Metrics};
85pub use pipeline::{Pipeline, PipelineResult};
86pub use policy::FailPolicy;
87pub use trace::{Trace, TraceEntry, TraceOutcome};
88pub use verdict::Verdict;
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93    use std::panic::RefUnwindSafe;
94
95    /// The pipeline borrows a `Context` across a `catch_unwind` boundary.
96    /// Asserting the bound here means a future field breaks this test rather
97    /// than the pipeline.
98    #[test]
99    fn context_survives_the_catch_unwind_boundary() {
100        fn assert_unwind_safe<T: RefUnwindSafe>() {}
101        assert_unwind_safe::<Context>();
102        assert_unwind_safe::<Deadline>();
103        assert_unwind_safe::<Value>();
104    }
105
106    /// A pipeline is shared across request threads, so what travels with it
107    /// must be `Send + Sync`.
108    #[test]
109    fn public_types_are_thread_safe() {
110        fn assert_send_sync<T: Send + Sync>() {}
111        assert_send_sync::<Context>();
112        assert_send_sync::<Deadline>();
113        assert_send_sync::<FailPolicy>();
114        assert_send_sync::<GuardError>();
115        assert_send_sync::<Trace>();
116        assert_send_sync::<TraceEntry>();
117        assert_send_sync::<TraceOutcome>();
118        assert_send_sync::<Value>();
119        assert_send_sync::<Verdict<String>>();
120        assert_send_sync::<PipelineResult<String>>();
121    }
122}