qubit-budget 0.5.0

Dependency-light resource limit and budget accounting primitives for Qubit Rust crates
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

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Defines point-limit failures for finite resource constraints.

use std::fmt::Debug;

use thiserror::Error;

use crate::resource::Observation;

/// Structured facts for a point measurement that exceeded its maximum.
///
/// # Type Parameters
///
/// * `R` - Caller-defined resource value retained for diagnostics.
/// * `Q` - Copyable measurement value used by the failed constraint.
///
/// # Examples
///
/// ```
/// use qubit_budget::LimitExceededError;
/// use qubit_budget::Observation;
///
/// let error = LimitExceededError::exact("depth", 3_u64, 2);
/// assert_eq!(error.observation(), Observation::Exact(3));
/// assert_eq!(error.maximum(), 2);
/// ```
#[must_use]
#[derive(Debug, Error, Clone, PartialEq, Eq)]
#[error("resource {resource:?} measured {observed}, exceeding the maximum of {maximum:?}")]
pub struct LimitExceededError<R, Q = u64>
where
    Q: Copy + Debug,
{
    /// Resource associated with the failed point check.
    pub resource: R,
    /// Observed point measurement or safe lower bound.
    pub observed: Observation<Q>,
    /// Configured inclusive point maximum.
    pub maximum: Q,
}

impl<R, Q> LimitExceededError<R, Q>
where
    Q: Copy + Debug,
{
    /// Creates a failure from an exact point measurement.
    ///
    /// # Parameters
    ///
    /// * `resource` - Resource associated with the failed point check.
    /// * `observed` - Exact measurement that exceeded `maximum`.
    /// * `maximum` - Configured inclusive point maximum.
    ///
    /// # Returns
    ///
    /// A structured failure containing an [`Observation::Exact`] measurement.
    #[inline(always)]
    pub const fn exact(resource: R, observed: Q, maximum: Q) -> Self {
        Self {
            resource,
            observed: Observation::Exact(observed),
            maximum,
        }
    }

    /// Creates a failure from a safe lower bound for a point measurement.
    ///
    /// # Parameters
    ///
    /// * `resource` - Resource associated with the failed point check.
    /// * `lower_bound` - Proven lower bound that exceeded `maximum`.
    /// * `maximum` - Configured inclusive point maximum.
    ///
    /// # Returns
    ///
    /// A structured failure containing an [`Observation::AtLeast`]
    /// measurement.
    #[inline(always)]
    pub const fn at_least(resource: R, lower_bound: Q, maximum: Q) -> Self {
        Self {
            resource,
            observed: Observation::AtLeast(lower_bound),
            maximum,
        }
    }

    /// Returns the resource associated with this failure.
    ///
    /// # Returns
    ///
    /// Returns the resource associated with this failure.
    #[must_use]
    #[inline(always)]
    pub const fn resource(&self) -> &R {
        &self.resource
    }

    /// Consumes this error and returns its associated resource.
    ///
    /// # Returns
    ///
    /// Consumes this error and returns its associated resource.
    #[must_use]
    #[inline(always)]
    pub fn into_resource(self) -> R {
        self.resource
    }

    /// Returns the observed point measurement or safe lower bound.
    ///
    /// # Returns
    ///
    /// Returns the observed point measurement or safe lower bound.
    #[must_use]
    #[inline(always)]
    pub const fn observation(&self) -> Observation<Q> {
        self.observed
    }

    /// Returns the exact point measurement when the observation is exact.
    ///
    /// # Returns
    ///
    /// Returns the exact point measurement when the observation is exact.
    ///
    /// `None` indicates that the observation is only a lower bound.
    #[must_use]
    #[inline(always)]
    pub const fn exact_observed(&self) -> Option<Q> {
        match self.observed {
            Observation::Exact(value) => Some(value),
            Observation::AtLeast(_) => None,
        }
    }

    /// Returns the safe lower bound of the observed point measurement.
    ///
    /// # Returns
    ///
    /// Returns the safe lower bound of the observed point measurement.
    #[must_use]
    #[inline(always)]
    pub const fn observed_lower_bound(&self) -> Q {
        self.observed.lower_bound()
    }

    /// Returns the configured inclusive point maximum.
    ///
    /// # Returns
    ///
    /// Returns the configured inclusive point maximum.
    #[must_use]
    #[inline(always)]
    pub const fn maximum(&self) -> Q {
        self.maximum
    }
}