-
Notifications
You must be signed in to change notification settings - Fork 0
feat(relation): refuse unobserved pairs as no-relationship #132
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| [package] | ||
| name = "relation_absence" | ||
| description = "Unobserved relation pairs are not evidence of no relationship." | ||
| version.workspace = true | ||
| edition.workspace = true | ||
| rust-version.workspace = true | ||
| license.workspace = true | ||
| authors.workspace = true | ||
| repository.workspace = true | ||
| homepage.workspace = true | ||
| readme.workspace = true | ||
| keywords.workspace = true | ||
| categories.workspace = true | ||
| publish = false | ||
|
|
||
| [lints] | ||
| workspace = true |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| //! Fail-closed relation-absence errors. | ||
|
|
||
| use std::fmt; | ||
|
|
||
| /// A fail-closed relation-absence error. | ||
| #[derive(Clone, Copy, Debug, Eq, PartialEq)] | ||
| #[non_exhaustive] | ||
| pub enum RelationAbsenceError { | ||
| /// An unobserved pair was treated as evidence of no relationship. | ||
| AbsenceIsNotNegative, | ||
| /// A recovery slice was empty or length-mismatched. | ||
| InvalidObservationPayload, | ||
| } | ||
|
|
||
| impl fmt::Display for RelationAbsenceError { | ||
| fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { | ||
| let message = match self { | ||
| Self::AbsenceIsNotNegative => { | ||
| "unobserved relation pairs are not evidence of no relationship" | ||
| } | ||
| Self::InvalidObservationPayload => "invalid relation-absence payload", | ||
| }; | ||
| formatter.write_str(message) | ||
| } | ||
| } | ||
|
|
||
| impl std::error::Error for RelationAbsenceError {} | ||
|
|
||
| #[cfg(test)] | ||
| mod tests { | ||
| use super::RelationAbsenceError; | ||
|
|
||
| #[test] | ||
| fn error_messages_are_stable() { | ||
| for (error, message) in [ | ||
| ( | ||
| RelationAbsenceError::AbsenceIsNotNegative, | ||
| "unobserved relation pairs are not evidence of no relationship", | ||
| ), | ||
| ( | ||
| RelationAbsenceError::InvalidObservationPayload, | ||
| "invalid relation-absence payload", | ||
| ), | ||
| ] { | ||
| assert_eq!(error.to_string(), message); | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| #![forbid(unsafe_code)] | ||
| #![deny(missing_docs)] | ||
| #![allow(clippy::cast_precision_loss)] | ||
| //! Unobserved relation pairs are not evidence of no relationship. | ||
| //! | ||
| //! Observed and inferred statuses stay distinct. Missing pairs remain | ||
| //! unobserved and never become negative edges (ADR 0003). | ||
|
|
||
| mod error; | ||
| mod status; | ||
|
|
||
| /// Fail-closed relation-absence errors. | ||
| pub use error::RelationAbsenceError; | ||
| /// Closed vocabulary of observed, inferred, and unobserved statuses. | ||
| pub use status::ObservationStatus; | ||
| /// Refuse to treat an unobserved pair as evidence of no relationship. | ||
| pub use status::refuse_absence_as_negative; | ||
| /// Fraction of recovered observation statuses that match known truth. | ||
| pub use status::status_recovery_rate; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| //! Observed, inferred, and unobserved relation statuses stay distinct. | ||
|
|
||
| use crate::RelationAbsenceError; | ||
|
|
||
| /// Closed vocabulary of relation observation statuses. | ||
| /// | ||
| /// Unobserved is a missing-status, not a negative edge. | ||
| #[derive(Clone, Copy, Debug, Eq, PartialEq)] | ||
| pub enum ObservationStatus { | ||
| /// Directly observed in source documents or authoritative systems. | ||
| Observed, | ||
| /// Derived by a model, reasoner, or heuristic and not yet promoted. | ||
| Inferred, | ||
| /// No observed or inferred evidence exists for this pair. | ||
| Unobserved, | ||
| } | ||
|
|
||
| impl ObservationStatus { | ||
| /// Return the stable wire status name. | ||
| #[must_use] | ||
| pub const fn wire_name(self) -> &'static str { | ||
| match self { | ||
| Self::Observed => "observed", | ||
| Self::Inferred => "inferred", | ||
| Self::Unobserved => "unobserved", | ||
| } | ||
| } | ||
|
|
||
| /// Parse a stable wire status name. | ||
| /// | ||
| /// # Errors | ||
| /// | ||
| /// Returns [`RelationAbsenceError::InvalidObservationPayload`] for | ||
| /// unrecognized names, including `no_relationship`. | ||
| pub fn from_wire_name(name: &str) -> Result<Self, RelationAbsenceError> { | ||
| match name { | ||
| "observed" => Ok(Self::Observed), | ||
| "inferred" => Ok(Self::Inferred), | ||
| "unobserved" => Ok(Self::Unobserved), | ||
| _ => Err(RelationAbsenceError::InvalidObservationPayload), | ||
| } | ||
| } | ||
| } | ||
|
|
||
| /// Refuse to treat an unobserved pair as evidence of no relationship. | ||
| /// | ||
| /// Observed and inferred statuses are presence evidence. They are not | ||
| /// absence, so this gate lets them through. | ||
| /// | ||
| /// # Errors | ||
| /// | ||
| /// Returns [`RelationAbsenceError::AbsenceIsNotNegative`] when `status` is | ||
| /// [`ObservationStatus::Unobserved`]. | ||
| pub fn refuse_absence_as_negative(status: ObservationStatus) -> Result<(), RelationAbsenceError> { | ||
| match status { | ||
| ObservationStatus::Unobserved => Err(RelationAbsenceError::AbsenceIsNotNegative), | ||
| ObservationStatus::Observed | ObservationStatus::Inferred => Ok(()), | ||
| } | ||
| } | ||
|
|
||
| /// Fraction of recovered observation statuses that match known truth. | ||
| /// | ||
| /// # Errors | ||
| /// | ||
| /// Returns [`RelationAbsenceError::InvalidObservationPayload`] when either | ||
| /// slice is empty or the lengths differ. | ||
| pub fn status_recovery_rate( | ||
| truth: &[ObservationStatus], | ||
| decided: &[ObservationStatus], | ||
| ) -> Result<f64, RelationAbsenceError> { | ||
| if truth.is_empty() || truth.len() != decided.len() { | ||
| return Err(RelationAbsenceError::InvalidObservationPayload); | ||
| } | ||
| let mut matches = 0_u32; | ||
| for (truth_status, decided_status) in truth.iter().zip(decided) { | ||
| if truth_status == decided_status { | ||
| matches += 1; | ||
| } | ||
| } | ||
| Ok(f64::from(matches) / truth.len() as f64) | ||
| } | ||
|
|
||
| #[cfg(test)] | ||
| mod tests { | ||
| use super::{ObservationStatus, refuse_absence_as_negative, status_recovery_rate}; | ||
| use crate::RelationAbsenceError; | ||
|
|
||
| #[test] | ||
| fn local_branches_cover_statuses_payloads_and_wire_names() { | ||
| assert_eq!( | ||
| refuse_absence_as_negative(ObservationStatus::Unobserved), | ||
| Err(RelationAbsenceError::AbsenceIsNotNegative) | ||
| ); | ||
| refuse_absence_as_negative(ObservationStatus::Observed).expect("observed"); | ||
| refuse_absence_as_negative(ObservationStatus::Inferred).expect("inferred"); | ||
| for status in [ | ||
| ObservationStatus::Observed, | ||
| ObservationStatus::Inferred, | ||
| ObservationStatus::Unobserved, | ||
| ] { | ||
| assert_eq!( | ||
| ObservationStatus::from_wire_name(status.wire_name()).expect("round-trip"), | ||
| status | ||
| ); | ||
| } | ||
| assert_eq!( | ||
| ObservationStatus::from_wire_name("no_relationship"), | ||
| Err(RelationAbsenceError::InvalidObservationPayload) | ||
| ); | ||
| let truth = [ObservationStatus::Observed, ObservationStatus::Unobserved]; | ||
| let matched = status_recovery_rate(&truth, &truth).expect("rate"); | ||
| assert!((matched - 1.0).abs() < f64::EPSILON); | ||
| let partial = status_recovery_rate( | ||
| &truth, | ||
| &[ObservationStatus::Observed, ObservationStatus::Observed], | ||
| ) | ||
| .expect("partial"); | ||
| assert!((partial - 0.5).abs() < f64::EPSILON); | ||
| assert_eq!( | ||
| status_recovery_rate(&[], &[]), | ||
| Err(RelationAbsenceError::InvalidObservationPayload) | ||
| ); | ||
| assert_eq!( | ||
| status_recovery_rate(&truth, &[]), | ||
| Err(RelationAbsenceError::InvalidObservationPayload) | ||
| ); | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| //! Observed, inferred, and unobserved statuses stay distinct. | ||
|
|
||
| use relation_absence::{ | ||
| ObservationStatus, RelationAbsenceError, refuse_absence_as_negative, status_recovery_rate, | ||
| }; | ||
|
|
||
| #[test] | ||
| fn unobserved_pairs_cannot_become_negative_evidence() { | ||
| assert_eq!( | ||
| refuse_absence_as_negative(ObservationStatus::Unobserved), | ||
| Err(RelationAbsenceError::AbsenceIsNotNegative) | ||
| ); | ||
| refuse_absence_as_negative(ObservationStatus::Observed).expect("observed is not absence"); | ||
| refuse_absence_as_negative(ObservationStatus::Inferred).expect("inferred is not absence"); | ||
| } | ||
|
|
||
| #[test] | ||
| fn recovered_statuses_match_known_truth_better_than_an_absence_collapse() { | ||
| let truth = [ | ||
| ObservationStatus::Observed, | ||
| ObservationStatus::Inferred, | ||
| ObservationStatus::Unobserved, | ||
| ]; | ||
| let recovered = truth; | ||
| let collapsed = [ | ||
| ObservationStatus::Observed, | ||
| ObservationStatus::Observed, | ||
| ObservationStatus::Observed, | ||
| ]; | ||
| let recovered_rate = status_recovery_rate(&truth, &recovered).expect("recovered"); | ||
| let collapsed_rate = status_recovery_rate(&truth, &collapsed).expect("collapsed"); | ||
| let expected = { | ||
| let mut matches = 0_u32; | ||
| for (truth_status, decided_status) in truth.iter().zip(recovered.iter()) { | ||
| if truth_status == decided_status { | ||
| matches += 1; | ||
| } | ||
| } | ||
| f64::from(matches) / f64::from(u32::try_from(truth.len()).expect("len")) | ||
| }; | ||
| assert!((recovered_rate - expected).abs() < f64::EPSILON); | ||
| assert!(recovered_rate > collapsed_rate); | ||
| } | ||
|
|
||
| #[test] | ||
| fn empty_or_mismatched_status_payloads_fail_closed() { | ||
| assert_eq!( | ||
| status_recovery_rate(&[], &[]), | ||
| Err(RelationAbsenceError::InvalidObservationPayload) | ||
| ); | ||
| assert_eq!( | ||
| status_recovery_rate(&[ObservationStatus::Observed], &[]), | ||
| Err(RelationAbsenceError::InvalidObservationPayload) | ||
| ); | ||
| assert_eq!( | ||
| status_recovery_rate( | ||
| &[ObservationStatus::Observed, ObservationStatus::Unobserved], | ||
| &[ObservationStatus::Observed] | ||
| ), | ||
| Err(RelationAbsenceError::InvalidObservationPayload) | ||
| ); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| //! Integration contract for the `relation_absence` package identity. | ||
|
|
||
| #[test] | ||
| fn package_identity_is_stable() { | ||
| let observed = std::hint::black_box(env!("CARGO_PKG_NAME")); | ||
| assert_eq!(observed, "relation_absence"); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
📝 Info: Stale README crate counts
README.md still states 50 and 54 crates (README.md:21, README.md:28); the workspace now has 57 members after
relation_absence. The counts were already stale before this PR and lie outside the changed hunks.Was this helpful? React with 👍 or 👎 to provide feedback.