Skip to main content

decision_attendance/
lib.rs

1//! Explainable attendance decisions from hard requirements and preferences.
2//!
3//! Required criteria are never offset by preference weight, and unknown
4//! evidence is never treated as support or opposition.
5//!
6//! ```
7//! use decision_attendance::{
8//!     AttendanceCriterion, AttendanceDecision, AttendancePolicy,
9//!     DecisionAttendance, Evidence,
10//! };
11//!
12//! let criteria = [
13//!     AttendanceCriterion::required("schedule", Evidence::Supports)?,
14//!     AttendanceCriterion::preference("travel", 3, Evidence::Supports)?,
15//!     AttendanceCriterion::preference("cost", 1, Evidence::Opposes)?,
16//! ];
17//! let report = DecisionAttendance::evaluate(
18//!     &criteria,
19//!     AttendancePolicy::new(7_000, 4_000)?,
20//! )?;
21//! assert_eq!(report.decision(), AttendanceDecision::Attend);
22//! assert_eq!(report.preference_score_basis_points(), Some(7_500));
23//! # Ok::<(), decision_attendance::AttendanceError>(())
24//! ```
25
26use std::collections::BTreeSet;
27use std::error::Error;
28use std::fmt::{self, Display, Formatter};
29use std::num::NonZeroU32;
30
31/// Evidence currently available for one criterion.
32#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
33pub enum Evidence {
34    /// Evidence favors attendance.
35    Supports,
36    /// Evidence opposes attendance.
37    Opposes,
38    /// Evidence is not yet known.
39    Unknown,
40}
41
42/// Whether a criterion is mandatory or contributes weighted preference.
43#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
44pub enum CriterionKind {
45    /// A hard requirement that preference scores cannot offset.
46    Required,
47    /// A preference with a positive integer weight.
48    Preference(NonZeroU32),
49}
50
51impl CriterionKind {
52    /// Preference weight, or `None` for a required criterion.
53    pub const fn weight(self) -> Option<NonZeroU32> {
54        match self {
55            Self::Required => None,
56            Self::Preference(weight) => Some(weight),
57        }
58    }
59}
60
61/// One named input to an attendance decision.
62#[derive(Clone, Debug, PartialEq, Eq, Hash)]
63pub struct AttendanceCriterion {
64    id: String,
65    kind: CriterionKind,
66    evidence: Evidence,
67}
68
69impl AttendanceCriterion {
70    /// Creates a hard requirement.
71    pub fn required(id: impl Into<String>, evidence: Evidence) -> Result<Self, AttendanceError> {
72        Self::new(id, CriterionKind::Required, evidence)
73    }
74
75    /// Creates a weighted preference.
76    pub fn preference(
77        id: impl Into<String>,
78        weight: u32,
79        evidence: Evidence,
80    ) -> Result<Self, AttendanceError> {
81        let weight = NonZeroU32::new(weight).ok_or(AttendanceError::ZeroWeight)?;
82        Self::new(id, CriterionKind::Preference(weight), evidence)
83    }
84
85    fn new(
86        id: impl Into<String>,
87        kind: CriterionKind,
88        evidence: Evidence,
89    ) -> Result<Self, AttendanceError> {
90        let id = id.into();
91        if id.trim().is_empty() {
92            return Err(AttendanceError::EmptyCriterionId);
93        }
94        Ok(Self { id, kind, evidence })
95    }
96
97    /// Stable criterion identifier.
98    pub fn id(&self) -> &str {
99        &self.id
100    }
101
102    /// Requirement or weighted preference.
103    pub const fn kind(&self) -> CriterionKind {
104        self.kind
105    }
106
107    /// Current evidence.
108    pub const fn evidence(&self) -> Evidence {
109        self.evidence
110    }
111}
112
113/// Score thresholds used after all requirements are satisfied.
114#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
115pub struct AttendancePolicy {
116    attend_basis_points: u16,
117    conditional_basis_points: u16,
118}
119
120impl AttendancePolicy {
121    /// Creates score thresholds.
122    ///
123    /// Both values must be at most 10,000 and
124    /// `conditional_basis_points <= attend_basis_points`.
125    pub fn new(
126        attend_basis_points: u16,
127        conditional_basis_points: u16,
128    ) -> Result<Self, AttendanceError> {
129        if attend_basis_points > 10_000
130            || conditional_basis_points > 10_000
131            || conditional_basis_points > attend_basis_points
132        {
133            return Err(AttendanceError::InvalidThresholds {
134                attend: attend_basis_points,
135                conditional: conditional_basis_points,
136            });
137        }
138        Ok(Self {
139            attend_basis_points,
140            conditional_basis_points,
141        })
142    }
143
144    /// Score at or above which attendance is selected.
145    pub const fn attend_basis_points(self) -> u16 {
146        self.attend_basis_points
147    }
148
149    /// Score at or above which conditional attendance is selected.
150    pub const fn conditional_basis_points(self) -> u16 {
151        self.conditional_basis_points
152    }
153}
154
155impl Default for AttendancePolicy {
156    fn default() -> Self {
157        Self::new(7_000, 4_000).expect("default thresholds are valid")
158    }
159}
160
161/// Overall result of attendance evaluation.
162#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
163pub enum AttendanceDecision {
164    /// Requirements are satisfied and preference support is high enough.
165    Attend,
166    /// Requirements are satisfied and preference support is mixed.
167    Conditional,
168    /// A requirement failed or preference opposition is too strong.
169    Decline,
170    /// Required or preference evidence is insufficient to decide.
171    Defer,
172}
173
174/// Complete explanation of one attendance decision.
175#[derive(Clone, Debug, PartialEq, Eq)]
176pub struct AttendanceReport {
177    decision: AttendanceDecision,
178    preference_score_basis_points: Option<u16>,
179    supporting_weight: u128,
180    opposing_weight: u128,
181    blocking_required: Vec<String>,
182    unknown_required: Vec<String>,
183    unknown_preferences: Vec<String>,
184}
185
186impl AttendanceReport {
187    /// Overall decision.
188    pub const fn decision(&self) -> AttendanceDecision {
189        self.decision
190    }
191
192    /// Known preference support divided by all known preference weight.
193    pub const fn preference_score_basis_points(&self) -> Option<u16> {
194        self.preference_score_basis_points
195    }
196
197    /// Sum of preference weights supporting attendance.
198    pub const fn supporting_weight(&self) -> u128 {
199        self.supporting_weight
200    }
201
202    /// Sum of preference weights opposing attendance.
203    pub const fn opposing_weight(&self) -> u128 {
204        self.opposing_weight
205    }
206
207    /// Unmet required criterion identifiers, in sorted order.
208    pub fn blocking_required(&self) -> &[String] {
209        &self.blocking_required
210    }
211
212    /// Unknown required criterion identifiers, in sorted order.
213    pub fn unknown_required(&self) -> &[String] {
214        &self.unknown_required
215    }
216
217    /// Unknown preference identifiers, in sorted order.
218    pub fn unknown_preferences(&self) -> &[String] {
219        &self.unknown_preferences
220    }
221
222    /// Whether the result permits attendance directly or conditionally.
223    pub const fn can_attend(&self) -> bool {
224        matches!(
225            self.decision,
226            AttendanceDecision::Attend | AttendanceDecision::Conditional
227        )
228    }
229}
230
231/// Implements the attendance-decision principle.
232#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
233pub struct DecisionAttendance;
234
235impl DecisionAttendance {
236    /// Evaluates criteria independently of their input order.
237    pub fn evaluate(
238        criteria: &[AttendanceCriterion],
239        policy: AttendancePolicy,
240    ) -> Result<AttendanceReport, AttendanceError> {
241        if criteria.is_empty() {
242            return Err(AttendanceError::NoCriteria);
243        }
244
245        let mut ids = BTreeSet::new();
246        for criterion in criteria {
247            if !ids.insert(criterion.id.as_str()) {
248                return Err(AttendanceError::DuplicateCriterionId(criterion.id.clone()));
249            }
250        }
251
252        let mut ordered: Vec<_> = criteria.iter().collect();
253        ordered.sort_by(|left, right| left.id.cmp(&right.id));
254
255        let mut supporting_weight = 0u128;
256        let mut opposing_weight = 0u128;
257        let mut preference_count = 0usize;
258        let mut blocking_required = Vec::new();
259        let mut unknown_required = Vec::new();
260        let mut unknown_preferences = Vec::new();
261
262        for criterion in ordered {
263            match criterion.kind {
264                CriterionKind::Required => match criterion.evidence {
265                    Evidence::Supports => {}
266                    Evidence::Opposes => blocking_required.push(criterion.id.clone()),
267                    Evidence::Unknown => unknown_required.push(criterion.id.clone()),
268                },
269                CriterionKind::Preference(weight) => {
270                    preference_count += 1;
271                    match criterion.evidence {
272                        Evidence::Supports => {
273                            supporting_weight = supporting_weight
274                                .checked_add(u128::from(weight.get()))
275                                .ok_or(AttendanceError::WeightOverflow)?;
276                        }
277                        Evidence::Opposes => {
278                            opposing_weight = opposing_weight
279                                .checked_add(u128::from(weight.get()))
280                                .ok_or(AttendanceError::WeightOverflow)?;
281                        }
282                        Evidence::Unknown => unknown_preferences.push(criterion.id.clone()),
283                    }
284                }
285            }
286        }
287
288        let known_weight = supporting_weight
289            .checked_add(opposing_weight)
290            .ok_or(AttendanceError::WeightOverflow)?;
291        let scaled_support = supporting_weight
292            .checked_mul(10_000)
293            .ok_or(AttendanceError::WeightOverflow)?;
294        let preference_score_basis_points = match scaled_support.checked_div(known_weight) {
295            Some(scaled) => {
296                Some(u16::try_from(scaled).map_err(|_| AttendanceError::WeightOverflow)?)
297            }
298            None => None,
299        };
300
301        let decision = if !blocking_required.is_empty() {
302            AttendanceDecision::Decline
303        } else if !unknown_required.is_empty() {
304            AttendanceDecision::Defer
305        } else if preference_count == 0 {
306            AttendanceDecision::Attend
307        } else {
308            match preference_score_basis_points {
309                None => AttendanceDecision::Defer,
310                Some(score) if score >= policy.attend_basis_points => AttendanceDecision::Attend,
311                Some(score) if score >= policy.conditional_basis_points => {
312                    AttendanceDecision::Conditional
313                }
314                Some(_) => AttendanceDecision::Decline,
315            }
316        };
317
318        Ok(AttendanceReport {
319            decision,
320            preference_score_basis_points,
321            supporting_weight,
322            opposing_weight,
323            blocking_required,
324            unknown_required,
325            unknown_preferences,
326        })
327    }
328}
329
330/// Invalid criterion, policy, or checked arithmetic.
331#[derive(Clone, Debug, PartialEq, Eq)]
332#[non_exhaustive]
333pub enum AttendanceError {
334    /// No criteria were supplied.
335    NoCriteria,
336    /// A criterion identifier was empty.
337    EmptyCriterionId,
338    /// A preference weight was zero.
339    ZeroWeight,
340    /// A criterion identifier appeared more than once.
341    DuplicateCriterionId(String),
342    /// Thresholds were outside their valid range or order.
343    InvalidThresholds {
344        /// Supplied attendance threshold.
345        attend: u16,
346        /// Supplied conditional threshold.
347        conditional: u16,
348    },
349    /// Checked weight arithmetic overflowed.
350    WeightOverflow,
351}
352
353impl Display for AttendanceError {
354    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
355        match self {
356            Self::NoCriteria => f.write_str("at least one attendance criterion is required"),
357            Self::EmptyCriterionId => f.write_str("criterion identifier cannot be empty"),
358            Self::ZeroWeight => f.write_str("preference weight must be greater than zero"),
359            Self::DuplicateCriterionId(id) => write!(f, "duplicate criterion identifier: {id}"),
360            Self::InvalidThresholds {
361                attend,
362                conditional,
363            } => write!(
364                f,
365                "invalid thresholds: attend={attend}, conditional={conditional}"
366            ),
367            Self::WeightOverflow => f.write_str("preference weight arithmetic overflowed"),
368        }
369    }
370}
371
372impl Error for AttendanceError {}
373
374#[cfg(test)]
375mod tests {
376    use super::*;
377
378    #[test]
379    fn known_preferences_produce_an_explainable_score() {
380        let criteria = [
381            AttendanceCriterion::required("schedule", Evidence::Supports).unwrap(),
382            AttendanceCriterion::preference("travel", 3, Evidence::Supports).unwrap(),
383            AttendanceCriterion::preference("cost", 1, Evidence::Opposes).unwrap(),
384        ];
385        let report = DecisionAttendance::evaluate(&criteria, AttendancePolicy::default()).unwrap();
386        assert_eq!(report.decision(), AttendanceDecision::Attend);
387        assert_eq!(report.preference_score_basis_points(), Some(7_500));
388        assert_eq!(report.supporting_weight(), 3);
389        assert_eq!(report.opposing_weight(), 1);
390    }
391
392    #[test]
393    fn unmet_requirement_cannot_be_offset_by_preferences() {
394        let criteria = [
395            AttendanceCriterion::required("access", Evidence::Opposes).unwrap(),
396            AttendanceCriterion::preference("fun", 100, Evidence::Supports).unwrap(),
397        ];
398        let report = DecisionAttendance::evaluate(&criteria, AttendancePolicy::default()).unwrap();
399        assert_eq!(report.decision(), AttendanceDecision::Decline);
400        assert_eq!(report.blocking_required(), ["access"]);
401        assert!(!report.can_attend());
402    }
403
404    #[test]
405    fn unknown_requirement_defers() {
406        let criteria = [
407            AttendanceCriterion::required("schedule", Evidence::Unknown).unwrap(),
408            AttendanceCriterion::preference("fun", 1, Evidence::Supports).unwrap(),
409        ];
410        let report = DecisionAttendance::evaluate(&criteria, AttendancePolicy::default()).unwrap();
411        assert_eq!(report.decision(), AttendanceDecision::Defer);
412        assert_eq!(report.unknown_required(), ["schedule"]);
413    }
414
415    #[test]
416    fn unknown_preferences_are_reported_and_excluded_from_score() {
417        let criteria = [
418            AttendanceCriterion::preference("known", 1, Evidence::Supports).unwrap(),
419            AttendanceCriterion::preference("unknown", 99, Evidence::Unknown).unwrap(),
420        ];
421        let report = DecisionAttendance::evaluate(&criteria, AttendancePolicy::default()).unwrap();
422        assert_eq!(report.preference_score_basis_points(), Some(10_000));
423        assert_eq!(report.unknown_preferences(), ["unknown"]);
424        assert_eq!(report.decision(), AttendanceDecision::Attend);
425    }
426
427    #[test]
428    fn satisfied_requirements_alone_allow_attendance() {
429        let criteria = [AttendanceCriterion::required("schedule", Evidence::Supports).unwrap()];
430        let report = DecisionAttendance::evaluate(&criteria, AttendancePolicy::default()).unwrap();
431        assert_eq!(report.decision(), AttendanceDecision::Attend);
432        assert_eq!(report.preference_score_basis_points(), None);
433    }
434
435    #[test]
436    fn thresholds_distinguish_conditional_and_decline() {
437        let conditional = [
438            AttendanceCriterion::preference("yes", 1, Evidence::Supports).unwrap(),
439            AttendanceCriterion::preference("no", 1, Evidence::Opposes).unwrap(),
440        ];
441        let decline = [
442            AttendanceCriterion::preference("yes", 1, Evidence::Supports).unwrap(),
443            AttendanceCriterion::preference("no", 3, Evidence::Opposes).unwrap(),
444        ];
445        let policy = AttendancePolicy::default();
446        assert_eq!(
447            DecisionAttendance::evaluate(&conditional, policy)
448                .unwrap()
449                .decision(),
450            AttendanceDecision::Conditional
451        );
452        assert_eq!(
453            DecisionAttendance::evaluate(&decline, policy)
454                .unwrap()
455                .decision(),
456            AttendanceDecision::Decline
457        );
458    }
459
460    #[test]
461    fn invalid_inputs_are_rejected() {
462        assert_eq!(
463            AttendanceCriterion::required("", Evidence::Supports).unwrap_err(),
464            AttendanceError::EmptyCriterionId
465        );
466        assert_eq!(
467            AttendanceCriterion::preference("x", 0, Evidence::Supports).unwrap_err(),
468            AttendanceError::ZeroWeight
469        );
470        assert_eq!(
471            AttendancePolicy::new(4_000, 7_000).unwrap_err(),
472            AttendanceError::InvalidThresholds {
473                attend: 4_000,
474                conditional: 7_000,
475            }
476        );
477        let duplicate = [
478            AttendanceCriterion::required("same", Evidence::Supports).unwrap(),
479            AttendanceCriterion::preference("same", 1, Evidence::Supports).unwrap(),
480        ];
481        assert_eq!(
482            DecisionAttendance::evaluate(&duplicate, AttendancePolicy::default()).unwrap_err(),
483            AttendanceError::DuplicateCriterionId("same".to_string())
484        );
485        assert_eq!(
486            DecisionAttendance::evaluate(&[], AttendancePolicy::default()).unwrap_err(),
487            AttendanceError::NoCriteria
488        );
489    }
490}