1use std::collections::BTreeSet;
27use std::error::Error;
28use std::fmt::{self, Display, Formatter};
29use std::num::NonZeroU32;
30
31#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
33pub enum Evidence {
34 Supports,
36 Opposes,
38 Unknown,
40}
41
42#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
44pub enum CriterionKind {
45 Required,
47 Preference(NonZeroU32),
49}
50
51impl CriterionKind {
52 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#[derive(Clone, Debug, PartialEq, Eq, Hash)]
63pub struct AttendanceCriterion {
64 id: String,
65 kind: CriterionKind,
66 evidence: Evidence,
67}
68
69impl AttendanceCriterion {
70 pub fn required(id: impl Into<String>, evidence: Evidence) -> Result<Self, AttendanceError> {
72 Self::new(id, CriterionKind::Required, evidence)
73 }
74
75 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 pub fn id(&self) -> &str {
99 &self.id
100 }
101
102 pub const fn kind(&self) -> CriterionKind {
104 self.kind
105 }
106
107 pub const fn evidence(&self) -> Evidence {
109 self.evidence
110 }
111}
112
113#[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 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 pub const fn attend_basis_points(self) -> u16 {
146 self.attend_basis_points
147 }
148
149 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#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
163pub enum AttendanceDecision {
164 Attend,
166 Conditional,
168 Decline,
170 Defer,
172}
173
174#[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 pub const fn decision(&self) -> AttendanceDecision {
189 self.decision
190 }
191
192 pub const fn preference_score_basis_points(&self) -> Option<u16> {
194 self.preference_score_basis_points
195 }
196
197 pub const fn supporting_weight(&self) -> u128 {
199 self.supporting_weight
200 }
201
202 pub const fn opposing_weight(&self) -> u128 {
204 self.opposing_weight
205 }
206
207 pub fn blocking_required(&self) -> &[String] {
209 &self.blocking_required
210 }
211
212 pub fn unknown_required(&self) -> &[String] {
214 &self.unknown_required
215 }
216
217 pub fn unknown_preferences(&self) -> &[String] {
219 &self.unknown_preferences
220 }
221
222 pub const fn can_attend(&self) -> bool {
224 matches!(
225 self.decision,
226 AttendanceDecision::Attend | AttendanceDecision::Conditional
227 )
228 }
229}
230
231#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
233pub struct DecisionAttendance;
234
235impl DecisionAttendance {
236 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#[derive(Clone, Debug, PartialEq, Eq)]
332#[non_exhaustive]
333pub enum AttendanceError {
334 NoCriteria,
336 EmptyCriterionId,
338 ZeroWeight,
340 DuplicateCriterionId(String),
342 InvalidThresholds {
344 attend: u16,
346 conditional: u16,
348 },
349 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}