wardline-core 0.1.0

Synchronous, embeddable guardrail evaluation core: the Guard trait, Verdict, fail policies, and the blocking pipeline executor.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
//! The synchronous, short-circuiting evaluator that runs a list of guards.

use crate::observe::{self, GuardSpan};
use crate::{Context, FailPolicy, Guard, GuardError, Trace, TraceEntry, TraceOutcome, Verdict};
use core::fmt;
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::Arc;
use std::sync::mpsc::{self, RecvTimeoutError};
use std::time::{Duration, Instant};

/// Recovers a panic payload as a string for [`GuardError::Panicked`].
fn panic_message(payload: Box<dyn std::any::Any + Send>) -> String {
    match payload.downcast::<String>() {
        Ok(message) => *message,
        Err(payload) => match payload.downcast::<&'static str>() {
            Ok(message) => (*message).to_owned(),
            Err(_) => "unknown panic payload".to_owned(),
        },
    }
}

/// Runs `guard.check`, converting a panic into [`GuardError::Panicked`].
///
/// This is the backstop that keeps a misbehaving guard from unwinding past
/// [`Pipeline::evaluate`]. Guard authors still must not panic.
fn invoke_check<In, Out>(
    guard: &dyn Guard<Input = In, Output = Out>,
    input: &In,
    ctx: &Context,
) -> Result<Verdict<Out>, GuardError>
where
    In: ?Sized,
{
    match catch_unwind(AssertUnwindSafe(|| guard.check(input, ctx))) {
        Ok(result) => result,
        Err(payload) => Err(GuardError::panicked(panic_message(payload))),
    }
}

/// A caller-supplied verdict for [`FailPolicy::FailClosedWithFallback`].
///
/// A closure rather than a stored `Verdict<Out>` so `Out` need not be
/// `Clone`, and so the substituted verdict can be built fresh each time.
type Fallback<Out> = Arc<dyn Fn() -> Verdict<Out> + Send + Sync>;

/// What the pipeline does about a guard that failed rather than decided.
enum Resolution<Out> {
    /// Skip this guard and keep going.
    Continue,
    /// Stop, with this verdict standing in for the one the guard never gave.
    Halt(Verdict<Out>),
}

/// An ordered list of guards, evaluated in place on the calling thread.
///
/// Guards run in the order they were added, and the first [`Verdict::Block`]
/// ends the run — the remaining guards are never called. This is why order is
/// worth thinking about: put the cheap, decisive checks first.
///
/// # Failure, not refusal
///
/// A guard that returns [`GuardError`] made no decision. The pipeline
/// resolves that with **that guard's own** [`Guard::fail_policy`], never a
/// pipeline-wide default, so what a broken guard does to your request path is
/// readable off the guard itself.
///
/// # Modifications
///
/// [`Verdict::Modify`] does not short-circuit; later guards still run and
/// still see the original input. The last modification wins, and the trace
/// records every one, because collapsing several rewrites into one is a
/// decision only the caller can make correctly.
///
/// # Sharing
///
/// A `Pipeline` is `Send + Sync` and holds no per-request state, so build it
/// once at startup and share it across request threads. Everything about one
/// evaluation lives in the [`PipelineResult`] it returns.
///
/// # Examples
///
/// ```
/// use std::sync::Arc;
/// use wardline_core::{Context, Guard, GuardError, Pipeline, Verdict};
///
/// struct NonEmpty;
///
/// impl Guard for NonEmpty {
///     type Input = str;
///     type Output = ();
///
///     fn check(&self, input: &str, _ctx: &Context) -> Result<Verdict, GuardError> {
///         if input.trim().is_empty() {
///             return Ok(Verdict::block("prompt is empty"));
///         }
///         Ok(Verdict::Allow)
///     }
///
///     fn name(&self) -> &'static str {
///         "non_empty"
///     }
/// }
///
/// struct NoApiKeys;
///
/// impl Guard for NoApiKeys {
///     type Input = str;
///     type Output = ();
///
///     fn check(&self, input: &str, _ctx: &Context) -> Result<Verdict, GuardError> {
///         if input.contains("sk-") {
///             return Ok(Verdict::block("prompt contains an API key"));
///         }
///         Ok(Verdict::Allow)
///     }
///
///     fn name(&self) -> &'static str {
///         "no_api_keys"
///     }
/// }
///
/// let pipeline = Pipeline::new().with(NonEmpty).with(NoApiKeys);
/// let ctx = Context::new();
///
/// let allowed = pipeline.evaluate(&Arc::from("summarise this"), &ctx);
/// assert!(allowed.is_allow());
/// assert_eq!(allowed.trace().len(), 2);
///
/// // The first guard blocks, so the second one never runs.
/// let blocked = pipeline.evaluate(&Arc::from("   "), &ctx);
/// assert_eq!(blocked.block_reason(), Some("prompt is empty"));
/// assert_eq!(blocked.trace().len(), 1);
/// assert_eq!(blocked.trace().halted_by(), Some("non_empty"));
/// ```
pub struct Pipeline<In: ?Sized, Out = ()> {
    guards: Vec<Arc<dyn Guard<Input = In, Output = Out>>>,
    trace_capacity: usize,
    fallback: Option<Fallback<Out>>,
    /// Set when at least one guard will be run on a spawned thread, so the
    /// per-request `Context` is cloned once instead of once per guard.
    shares_context: bool,
}

impl<In: ?Sized, Out> Pipeline<In, Out> {
    /// Creates an empty pipeline.
    ///
    /// An empty pipeline allows everything. That is the honest answer to
    /// "no checks configured", but it is worth asserting against in the code
    /// that assembles one.
    pub fn new() -> Self {
        Pipeline {
            guards: Vec::new(),
            trace_capacity: Trace::DEFAULT_CAPACITY,
            fallback: None,
            shares_context: false,
        }
    }

    /// Appends a guard. Builder-style.
    #[must_use]
    pub fn with<G>(mut self, guard: G) -> Self
    where
        G: Guard<Input = In, Output = Out> + 'static,
    {
        self.push(guard);
        self
    }

    /// Appends a guard.
    pub fn push<G>(&mut self, guard: G)
    where
        G: Guard<Input = In, Output = Out> + 'static,
    {
        self.shares_context |= guard.timeout().is_some() && !guard.strict();
        self.guards.push(Arc::new(guard));
    }

    /// Sets how many trace entries an evaluation keeps. Builder-style.
    ///
    /// Defaults to [`Trace::DEFAULT_CAPACITY`]. Raise it for a long pipeline
    /// whose full trace you intend to persist; the cap itself is not
    /// removable, by design.
    #[must_use]
    pub fn with_trace_capacity(mut self, capacity: usize) -> Self {
        self.trace_capacity = capacity;
        self
    }

    /// Sets the verdict substituted for a failing
    /// [`FailPolicy::FailClosedWithFallback`] guard. Builder-style.
    ///
    /// It lives on the pipeline, not the guard, because the safe answer is a
    /// property of the call site. Without one, such a guard halts as plain
    /// [`FailPolicy::FailClosed`] — a missing fallback is never read as
    /// permission to continue.
    #[must_use]
    pub fn with_fallback<F>(mut self, fallback: F) -> Self
    where
        F: Fn() -> Verdict<Out> + Send + Sync + 'static,
    {
        self.fallback = Some(Arc::new(fallback));
        self
    }

    /// The number of guards.
    pub fn len(&self) -> usize {
        self.guards.len()
    }

    /// Returns `true` if this pipeline has no guards, and so allows
    /// everything.
    pub fn is_empty(&self) -> bool {
        self.guards.is_empty()
    }

    /// The guard names, in evaluation order.
    pub fn guard_names(&self) -> Vec<&'static str> {
        self.guards.iter().map(|guard| guard.name()).collect()
    }

    /// How long the pipeline will wait for one guard, if it will bound it at
    /// all.
    ///
    /// Only a declared [`Guard::timeout`] earns a bound; a request deadline
    /// alone does not, because enforcing one costs a thread per guard. The
    /// deadline still tightens a declared timeout, and cooperative guards can
    /// read it from the [`Context`] themselves.
    fn budget(guard: &dyn Guard<Input = In, Output = Out>, ctx: &Context) -> Option<Duration> {
        let timeout = guard.timeout()?;
        Some(match ctx.deadline() {
            Some(deadline) => timeout.min(deadline.remaining()),
            None => timeout,
        })
    }

    /// Turns a guard's failure into a decision, using that guard's policy.
    fn resolve(
        &self,
        name: &'static str,
        error: &GuardError,
        policy: FailPolicy,
    ) -> Resolution<Out> {
        match policy {
            FailPolicy::FailOpen => Resolution::Continue,
            FailPolicy::FailClosed => {
                Resolution::Halt(Verdict::block(format!("{name} failed: {error}")))
            }
            FailPolicy::FailClosedWithFallback => match &self.fallback {
                Some(fallback) => Resolution::Halt(fallback()),
                None => Resolution::Halt(Verdict::block(format!(
                    "{name} failed: {error} (no fallback verdict registered)"
                ))),
            },
        }
    }
}

impl<In, Out> Pipeline<In, Out>
where
    In: Send + Sync + ?Sized + 'static,
    Out: Send + 'static,
{
    /// Runs every guard in order and returns the decision with its trace.
    ///
    /// The input arrives as an [`Arc`] because a guard the pipeline may stop
    /// waiting on has to run on a thread that can outlive this call, and
    /// handing owned, shared data to that thread is the only way to bound the
    /// wait without `unsafe` or copying the input per guard. Guards still see
    /// a plain `&In`.
    ///
    /// Every `check` is wrapped in [`catch_unwind`]. A panic becomes
    /// [`GuardError::Panicked`] and is resolved through that guard's
    /// [`FailPolicy`]; it never unwinds out of this method.
    ///
    /// Enable the `tracing` feature to emit a `wardline.evaluate` span and a
    /// `wardline.guard` span (plus a `guard panicked` error event) for each
    /// check.
    ///
    /// [`catch_unwind`]: std::panic::catch_unwind
    pub fn evaluate(&self, input: &Arc<In>, ctx: &Context) -> PipelineResult<Out> {
        let _eval = observe::enter_evaluate();
        let mut trace = Trace::with_capacity(self.trace_capacity);
        let shared_ctx = self.shares_context.then(|| Arc::new(ctx.clone()));

        // Allow unless something says otherwise; a `Modify` replaces it.
        let mut verdict = Verdict::Allow;

        for guard in &self.guards {
            let name = guard.name();
            let span = GuardSpan::enter(name);
            let started = Instant::now();
            let outcome = self.run(guard, input, ctx, shared_ctx.as_ref());
            let elapsed = started.elapsed();

            match outcome {
                Ok(Verdict::Block { reason }) => {
                    let decided = Verdict::<Out>::Block {
                        reason: reason.clone(),
                    };
                    span.decided(&decided);
                    trace.record(TraceEntry::new(
                        name,
                        TraceOutcome::from_verdict(&decided),
                        elapsed,
                    ));
                    return PipelineResult {
                        verdict: Verdict::Block { reason },
                        trace,
                    };
                }
                Ok(decided) => {
                    span.decided(&decided);
                    trace.record(TraceEntry::new(
                        name,
                        TraceOutcome::from_verdict(&decided),
                        elapsed,
                    ));
                    if decided.is_modify() {
                        verdict = decided;
                    }
                }
                Err(error) => {
                    span.failed(&error);
                    let policy = guard.fail_policy();
                    let resolution = self.resolve(name, &error, policy);
                    let halted = matches!(resolution, Resolution::Halt(_));
                    trace.record(TraceEntry::new(
                        name,
                        TraceOutcome::Failed {
                            error,
                            policy,
                            halted,
                        },
                        elapsed,
                    ));
                    if let Resolution::Halt(substitute) = resolution {
                        return PipelineResult {
                            verdict: substitute,
                            trace,
                        };
                    }
                }
            }
        }

        PipelineResult { verdict, trace }
    }

    /// Runs one guard, bounding the wait if it asked to be bounded.
    fn run(
        &self,
        guard: &Arc<dyn Guard<Input = In, Output = Out>>,
        input: &Arc<In>,
        ctx: &Context,
        shared_ctx: Option<&Arc<Context>>,
    ) -> Result<Verdict<Out>, GuardError> {
        let Some(budget) = Self::budget(guard.as_ref(), ctx) else {
            return invoke_check(guard.as_ref(), input, ctx);
        };

        if budget.is_zero() {
            // The request deadline has already passed. Running the guard
            // cannot produce an answer anyone is still waiting for.
            return Err(if guard.strict() {
                GuardError::DeadlineViolated
            } else {
                GuardError::Timeout
            });
        }

        if guard.strict() {
            // A strict guard promised to police its own deadline, so it runs
            // inline and is never abandoned to a detached thread. If it
            // overruns anyway, that is a contract violation, not a timeout.
            let started = Instant::now();
            let result = invoke_check(guard.as_ref(), input, ctx);
            if result.is_ok() && started.elapsed() > budget {
                return Err(GuardError::DeadlineViolated);
            }
            return result;
        }

        // Best-effort, not cancellation: on timeout the pipeline stops
        // waiting, but the guard keeps running to completion on its own
        // thread. See `docs/ARCHITECTURE.md`.
        let (sender, receiver) = mpsc::channel();
        let guard = Arc::clone(guard);
        let input = Arc::clone(input);
        let ctx = match shared_ctx {
            Some(shared) => Arc::clone(shared),
            None => Arc::new(ctx.clone()),
        };

        std::thread::spawn(move || {
            let _ = sender.send(invoke_check(guard.as_ref(), &input, &ctx));
        });

        match receiver.recv_timeout(budget) {
            Ok(result) => result,
            Err(RecvTimeoutError::Timeout) => Err(GuardError::Timeout),
            // The thread ended without sending. Panics are caught above, so
            // this is a residual — the worker died some other way.
            Err(RecvTimeoutError::Disconnected) => Err(GuardError::internal(
                "guard thread ended without returning a verdict",
            )),
        }
    }
}

impl<In: ?Sized, Out> Default for Pipeline<In, Out> {
    fn default() -> Self {
        Pipeline::new()
    }
}

impl<In: ?Sized, Out> fmt::Debug for Pipeline<In, Out> {
    /// Names the guards rather than trying to print them — a `Guard` is
    /// arbitrary user code with no `Debug` bound.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Pipeline")
            .field("guards", &self.guard_names())
            .field("trace_capacity", &self.trace_capacity)
            .field("has_fallback", &self.fallback.is_some())
            .finish()
    }
}

/// One evaluation: the decision, and the record of how it was reached.
///
/// The trace comes back on every path, block or allow, because "why was this
/// blocked" is the question asked of a guardrail system in production, and
/// answering it after the fact from logs that were never written is not
/// possible.
#[derive(Debug, Clone)]
pub struct PipelineResult<Out = ()> {
    verdict: Verdict<Out>,
    trace: Trace,
}

impl<Out> PipelineResult<Out> {
    /// The pipeline's decision.
    pub fn verdict(&self) -> &Verdict<Out> {
        &self.verdict
    }

    /// Every guard that ran, in order.
    pub fn trace(&self) -> &Trace {
        &self.trace
    }

    /// Returns `true` if the action may proceed unchanged.
    pub fn is_allow(&self) -> bool {
        self.verdict.is_allow()
    }

    /// Returns `true` if the action was refused.
    ///
    /// True for a guard that said no *and* for one that failed under a
    /// halting [`FailPolicy`]; the trace distinguishes them.
    pub fn is_block(&self) -> bool {
        self.verdict.is_block()
    }

    /// Returns `true` if the action may proceed with a replacement payload.
    pub fn is_modify(&self) -> bool {
        self.verdict.is_modify()
    }

    /// Why the action was refused, if it was.
    pub fn block_reason(&self) -> Option<&str> {
        self.verdict.block_reason()
    }

    /// The replacement payload, if there is one.
    pub fn modified(&self) -> Option<&Out> {
        self.verdict.modified()
    }

    /// Takes the verdict, discarding the trace.
    pub fn into_verdict(self) -> Verdict<Out> {
        self.verdict
    }

    /// Takes both parts.
    pub fn into_parts(self) -> (Verdict<Out>, Trace) {
        (self.verdict, self.trace)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A guard whose behaviour is chosen at construction, so a test can
    /// describe a pipeline rather than define a type per case.
    struct Scripted {
        name: &'static str,
        outcome: fn() -> Result<Verdict<String>, GuardError>,
        policy: FailPolicy,
        timeout: Option<Duration>,
        strict: bool,
    }

    impl Scripted {
        fn new(name: &'static str, outcome: fn() -> Result<Verdict<String>, GuardError>) -> Self {
            Scripted {
                name,
                outcome,
                policy: FailPolicy::FailClosed,
                timeout: None,
                strict: false,
            }
        }

        fn with_policy(mut self, policy: FailPolicy) -> Self {
            self.policy = policy;
            self
        }

        fn with_timeout(mut self, timeout: Duration) -> Self {
            self.timeout = Some(timeout);
            self
        }

        fn strict(mut self) -> Self {
            self.strict = true;
            self
        }
    }

    impl Guard for Scripted {
        type Input = str;
        type Output = String;

        fn check(&self, _input: &str, _ctx: &Context) -> Result<Verdict<String>, GuardError> {
            (self.outcome)()
        }

        fn fail_policy(&self) -> FailPolicy {
            self.policy
        }

        fn timeout(&self) -> Option<Duration> {
            self.timeout
        }

        fn strict(&self) -> bool {
            self.strict
        }

        fn name(&self) -> &'static str {
            self.name
        }
    }

    fn allow() -> Result<Verdict<String>, GuardError> {
        Ok(Verdict::Allow)
    }

    fn block() -> Result<Verdict<String>, GuardError> {
        Ok(Verdict::block("refused"))
    }

    fn fail() -> Result<Verdict<String>, GuardError> {
        Err(GuardError::dependency("classifier unreachable"))
    }

    fn boom() -> Result<Verdict<String>, GuardError> {
        panic!("deliberate unit-test panic");
    }

    fn input() -> Arc<str> {
        Arc::from("payload")
    }

    #[test]
    fn an_empty_pipeline_allows_and_traces_nothing() {
        let pipeline: Pipeline<str, String> = Pipeline::new();
        assert!(pipeline.is_empty());

        let result = pipeline.evaluate(&input(), &Context::new());
        assert!(result.is_allow());
        assert!(result.trace().is_empty());
    }

    #[test]
    fn guards_run_in_the_order_they_were_added() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("first", allow))
            .with(Scripted::new("second", allow))
            .with(Scripted::new("third", allow));

        assert_eq!(pipeline.guard_names(), ["first", "second", "third"]);

        let result = pipeline.evaluate(&input(), &Context::new());
        let names: Vec<_> = result.trace().iter().map(TraceEntry::name).collect();
        assert_eq!(names, ["first", "second", "third"]);
    }

    #[test]
    fn a_block_short_circuits_the_rest() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("first", allow))
            .with(Scripted::new("second", block))
            .with(Scripted::new("third", allow));

        let result = pipeline.evaluate(&input(), &Context::new());
        assert_eq!(result.block_reason(), Some("refused"));
        assert_eq!(result.trace().len(), 2, "the third guard must not run");
        assert_eq!(result.trace().halted_by(), Some("second"));
    }

    #[test]
    fn a_modification_does_not_short_circuit_and_the_last_one_wins() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("first", || {
                Ok(Verdict::Modify("once".to_owned()))
            }))
            .with(Scripted::new("second", allow))
            .with(Scripted::new("third", || {
                Ok(Verdict::Modify("twice".to_owned()))
            }));

        let result = pipeline.evaluate(&input(), &Context::new());
        assert_eq!(result.modified(), Some(&"twice".to_owned()));
        assert_eq!(result.trace().len(), 3);
    }

    #[test]
    fn a_failure_is_resolved_by_that_guards_own_policy() {
        let open = Pipeline::new()
            .with(Scripted::new("flaky", fail).with_policy(FailPolicy::FailOpen))
            .with(Scripted::new("after", allow));
        let result = open.evaluate(&input(), &Context::new());
        assert!(result.is_allow());
        assert_eq!(result.trace().len(), 2, "the pipeline must keep going");

        let closed = Pipeline::new()
            .with(Scripted::new("flaky", fail))
            .with(Scripted::new("after", allow));
        let result = closed.evaluate(&input(), &Context::new());
        assert!(result.is_block());
        assert_eq!(result.trace().len(), 1);
        assert_eq!(result.trace().halted_by(), Some("flaky"));
    }

    #[test]
    fn a_failure_is_traced_as_a_failure_not_as_a_refusal() {
        let pipeline = Pipeline::new().with(Scripted::new("flaky", fail));
        let result = pipeline.evaluate(&input(), &Context::new());

        let Some(entry) = result.trace().last() else {
            panic!("the failing guard should have been traced");
        };
        let TraceOutcome::Failed { error, policy, .. } = entry.outcome() else {
            panic!("expected a failure, got {:?}", entry.outcome());
        };
        assert_eq!(error.kind(), "dependency");
        assert_eq!(*policy, FailPolicy::FailClosed);
    }

    #[test]
    fn a_registered_fallback_replaces_the_failed_guards_verdict() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("flaky", fail).with_policy(FailPolicy::FailClosedWithFallback))
            .with(Scripted::new("after", allow))
            .with_fallback(|| Verdict::Modify("safe default".to_owned()));

        let result = pipeline.evaluate(&input(), &Context::new());
        assert_eq!(result.modified(), Some(&"safe default".to_owned()));
        assert_eq!(result.trace().len(), 1, "the fallback still halts");
    }

    #[test]
    fn a_missing_fallback_halts_rather_than_letting_the_request_through() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("flaky", fail).with_policy(FailPolicy::FailClosedWithFallback));

        let result = pipeline.evaluate(&input(), &Context::new());
        assert!(result.is_block());
        assert!(
            result
                .block_reason()
                .is_some_and(|reason| reason.contains("no fallback"))
        );
    }

    #[test]
    fn a_slow_guard_times_out_without_delaying_the_pipeline() {
        let pipeline = Pipeline::new()
            .with(
                Scripted::new("slow", || {
                    std::thread::sleep(Duration::from_secs(5));
                    allow()
                })
                .with_timeout(Duration::from_millis(50))
                .with_policy(FailPolicy::FailOpen),
            )
            .with(Scripted::new("after", allow));

        let started = Instant::now();
        let result = pipeline.evaluate(&input(), &Context::new());
        let elapsed = started.elapsed();

        assert!(
            elapsed < Duration::from_secs(2),
            "waited {elapsed:?}: the pipeline must be bounded by the timeout, \
             not by the guard's real runtime"
        );
        assert!(result.is_allow(), "the guard failed open");

        let Some(entry) = result.trace().iter().next() else {
            panic!("the slow guard should have been traced");
        };
        let TraceOutcome::Failed { error, .. } = entry.outcome() else {
            panic!("expected a timeout, got {:?}", entry.outcome());
        };
        assert_eq!(*error, GuardError::Timeout);
    }

    #[test]
    fn a_guard_inside_its_timeout_is_left_alone() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("prompt", allow).with_timeout(Duration::from_secs(30)));
        let result = pipeline.evaluate(&input(), &Context::new());
        assert!(result.is_allow());
        assert_eq!(result.trace().len(), 1);
    }

    #[test]
    fn a_strict_guard_that_overruns_reports_a_contract_violation() {
        let pipeline = Pipeline::new().with(
            Scripted::new("stubborn", || {
                std::thread::sleep(Duration::from_millis(60));
                allow()
            })
            .with_timeout(Duration::from_millis(10))
            .strict(),
        );

        let result = pipeline.evaluate(&input(), &Context::new());
        let Some(entry) = result.trace().last() else {
            panic!("the strict guard should have been traced");
        };
        let TraceOutcome::Failed { error, .. } = entry.outcome() else {
            panic!("expected a deadline violation, got {:?}", entry.outcome());
        };
        assert_eq!(*error, GuardError::DeadlineViolated);
    }

    #[test]
    fn an_expired_deadline_stops_a_bounded_guard_before_it_starts() {
        use crate::Deadline;

        let pipeline = Pipeline::new()
            .with(Scripted::new("bounded", allow).with_timeout(Duration::from_secs(30)));
        let expired = Context::new().with_deadline(Deadline::after(Duration::ZERO));

        let result = pipeline.evaluate(&input(), &expired);
        assert!(result.is_block());
        assert_eq!(result.trace().halted_by(), Some("bounded"));
    }

    #[test]
    fn the_trace_is_bounded_however_long_the_pipeline_is() {
        let mut pipeline: Pipeline<str, String> = Pipeline::new().with_trace_capacity(4);
        for _ in 0..200 {
            pipeline.push(Scripted::new("noisy", allow));
        }

        let result = pipeline.evaluate(&input(), &Context::new());
        assert!(result.is_allow());
        assert_eq!(result.trace().len(), 4);
        assert_eq!(result.trace().dropped(), 196);
        assert!(!result.trace().is_complete());
    }

    #[test]
    fn a_panicking_guard_is_caught_and_does_not_unwind() {
        let pipeline = Pipeline::new()
            .with(Scripted::new("volatile", boom).with_policy(FailPolicy::FailOpen))
            .with(Scripted::new("after", allow));

        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
            pipeline.evaluate(&input(), &Context::new())
        }));
        let result = match result {
            Ok(result) => result,
            Err(_) => panic!("evaluate must not unwind past the caller"),
        };
        assert!(result.is_allow());
        assert_eq!(result.trace().len(), 2);

        let Some(entry) = result.trace().iter().next() else {
            panic!("the panicking guard should have been traced");
        };
        let TraceOutcome::Failed { error, halted, .. } = entry.outcome() else {
            panic!("expected a panic failure, got {:?}", entry.outcome());
        };
        assert!(error.is_panic());
        assert_eq!(error.message(), Some("deliberate unit-test panic"));
        assert!(!*halted);
    }

    #[test]
    fn a_pipeline_is_shareable_across_threads() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<Pipeline<str, String>>();

        let pipeline = Arc::new(Pipeline::new().with(Scripted::new("first", allow)));
        let mut handles = Vec::new();
        for _ in 0..4 {
            let pipeline = Arc::clone(&pipeline);
            handles.push(std::thread::spawn(move || {
                pipeline.evaluate(&input(), &Context::new()).is_allow()
            }));
        }
        for handle in handles {
            assert_eq!(handle.join().ok(), Some(true));
        }
    }
}