origin/

lib.rs

//! # Origin
//!
//! Every value is either in the interior or at a boundary.
//! The compiler knows which. One pattern. Every domain.

use std::fmt;

// Re-export proc-macros so users write `use origin::BoundaryKind;`
pub use origin_macros::BoundaryKind;
pub use origin_macros::boundary_check;

/// A boundary reason. Every domain defines its own.
pub trait BoundaryKind: fmt::Debug + Send + Sync + 'static {}

/// The core type. Interior or Boundary. One distinction. Every domain.
#[derive(Debug)]
#[must_use = "this Value may be a Boundary that must be handled"]
pub enum Value<T, B: BoundaryKind = GenericBoundary> {
    /// Interior: the value is in safe territory.
    Interior(T),
    /// Boundary: the value crossed the edge. Carries the reason and last known value.
    Boundary {
        reason: B,
        last: T,
    },
}

impl<T, B: BoundaryKind> Value<T, B> {
    /// Construct an interior value.
    pub fn interior(value: T) -> Self {
        Value::Interior(value)
    }

    /// Construct a boundary value with a reason and last known value.
    pub fn boundary(reason: B, last: T) -> Self {
        Value::Boundary { reason, last }
    }

    pub fn is_interior(&self) -> bool {
        matches!(self, Value::Interior(_))
    }

    pub fn is_boundary(&self) -> bool {
        matches!(self, Value::Boundary { .. })
    }

    /// Unwrap the interior value, or return a fallback.
    pub fn or(self, fallback: T) -> T {
        match self {
            Value::Interior(v) => v,
            Value::Boundary { .. } => fallback,
        }
    }

    /// Unwrap the interior value, or panic.
    pub fn unwrap(self) -> T {
        match self {
            Value::Interior(v) => v,
            Value::Boundary { reason, .. } => {
                panic!("called unwrap on a Boundary: {reason:?}")
            }
        }
    }

    /// Map over the interior value. Boundaries propagate unchanged.
    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Value<U, B> {
        match self {
            Value::Interior(v) => Value::Interior(f(v)),
            Value::Boundary { reason, last } => Value::Boundary {
                reason,
                last: f(last),
            },
        }
    }

    /// Extract the interior value, or return the boundary reason as `Err`
    /// for `?` propagation. The residual is not carried through propagation —
    /// match explicitly to access it.
    pub fn propagate(self) -> Result<T, B> {
        match self {
            Value::Interior(v) => Ok(v),
            Value::Boundary { reason, .. } => Err(reason),
        }
    }

    /// Extract the interior value while recording the step in a trace.
    /// If boundary, records the residual in the chain and returns the reason.
    /// If interior, records the value and continues.
    pub fn trace(self, chain: &mut Chain, label: &'static str) -> Result<T, B>
    where
        T: std::fmt::Debug,
    {
        match self {
            Value::Interior(v) => {
                chain.record(label, &v);
                Ok(v)
            }
            Value::Boundary { reason, last } => {
                chain.record_boundary(label, &last);
                Err(reason)
            }
        }
    }

    /// Chain operations that may themselves hit a boundary.
    /// Requires U: Default so a boundary can carry a last value when types change.
    pub fn and_then<U: Default>(self, f: impl FnOnce(T) -> Value<U, B>) -> Value<U, B> {
        match self {
            Value::Interior(v) => f(v),
            Value::Boundary { reason, .. } => Value::Boundary {
                reason,
                last: U::default(),
            },
        }
    }
}

// -- Residual chain --

/// A step in the residual chain: what was computed at each layer.
#[derive(Debug, Clone)]
pub struct ChainEntry {
    /// Which layer produced this value.
    pub label: &'static str,
    /// Debug representation of the value at this layer.
    pub value: String,
    /// Whether this was the layer that hit the boundary.
    pub is_boundary: bool,
}

/// The residual chain: every step of how you got there.
///
/// When a pipeline propagates through `?`, each layer records what it
/// computed. If a boundary is reached, the chain shows the full path —
/// not just where you stopped, but every step on the way.
#[derive(Debug, Clone, Default)]
pub struct Chain {
    entries: Vec<ChainEntry>,
}

impl Chain {
    pub fn new() -> Self {
        Chain { entries: Vec::new() }
    }

    /// Record a successful interior step.
    pub fn record(&mut self, label: &'static str, value: &dyn fmt::Debug) {
        self.entries.push(ChainEntry {
            label,
            value: format!("{value:?}"),
            is_boundary: false,
        });
    }

    /// Record the residual at the boundary — the last step before propagation.
    pub fn record_boundary(&mut self, label: &'static str, value: &dyn fmt::Debug) {
        self.entries.push(ChainEntry {
            label,
            value: format!("{value:?}"),
            is_boundary: true,
        });
    }

    /// The entries in order, from first layer to the boundary.
    pub fn entries(&self) -> &[ChainEntry] {
        &self.entries
    }

    /// How many layers completed before the boundary.
    pub fn depth(&self) -> usize {
        self.entries.iter().filter(|e| !e.is_boundary).count()
    }
}

impl fmt::Display for Chain {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for (i, entry) in self.entries.iter().enumerate() {
            let marker = if entry.is_boundary { "✗" } else { "✓" };
            write!(f, "  {marker} [{}] {}: {}", i + 1, entry.label, entry.value)?;
            if i < self.entries.len() - 1 {
                writeln!(f)?;
            }
        }
        Ok(())
    }
}

// -- Built-in boundary kinds --

#[derive(Debug, Clone)]
pub struct GenericBoundary;
impl BoundaryKind for GenericBoundary {}

// Math
#[derive(Debug, Clone)]
pub struct DivisionByZero;
impl BoundaryKind for DivisionByZero {}

#[derive(Debug, Clone)]
pub struct Overflow;
impl BoundaryKind for Overflow {}

#[derive(Debug, Clone)]
pub struct Underflow;
impl BoundaryKind for Underflow {}

#[derive(Debug, Clone)]
pub struct Imaginary { pub real_part: f64 }
impl BoundaryKind for Imaginary {}

// AI inference
#[derive(Debug, Clone)]
pub struct ModelUncertain { pub confidence: f64 }
impl BoundaryKind for ModelUncertain {}

#[derive(Debug, Clone)]
pub struct Hallucinated { pub confidence: f64, pub grounding: Option<String> }
impl BoundaryKind for Hallucinated {}

#[derive(Debug, Clone)]
pub struct Contradicted { pub sources: Vec<String>, pub claim: String }
impl BoundaryKind for Contradicted {}

// -- Demonstration functions --
//
// These show the shape of Value<T, B>. They are teaching examples,
// not domain rules. `divide` catches exact zero — IEEE 754 handles
// near-zero differently (it returns infinity). If your domain cares
// about near-zero, define your own boundary kind and threshold.
// That's the point: Origin gives you the mechanism, you define
// what "boundary" means for your domain.

/// Division that catches exact zero. A demonstration of Value<T, B>.
pub fn divide(a: f64, b: f64) -> Value<f64, DivisionByZero> {
    if b == 0.0 {
        Value::Boundary { reason: DivisionByZero, last: a }
    } else {
        Value::Interior(a / b)
    }
}

/// Square root that catches negative input. A demonstration of Value<T, B>.
pub fn sqrt(a: f64) -> Value<f64, Imaginary> {
    if a < 0.0 {
        Value::Boundary { reason: Imaginary { real_part: a }, last: 0.0 }
    } else {
        Value::Interior(a.sqrt())
    }
}

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

    #[test]
    fn division_interior() {
        let result = divide(10.0, 2.0);
        assert!(result.is_interior());
        assert_eq!(result.unwrap(), 5.0);
    }

    #[test]
    fn division_boundary() {
        let result = divide(10.0, 0.0);
        assert!(result.is_boundary());
        match result {
            Value::Boundary { reason: DivisionByZero, last } => {
                assert_eq!(last, 10.0);
            }
            _ => panic!("expected boundary"),
        }
    }

    #[test]
    fn division_or_fallback() {
        assert_eq!(divide(10.0, 0.0).or(0.0), 0.0);
    }

    #[test]
    fn sqrt_interior() {
        assert_eq!(sqrt(9.0).unwrap(), 3.0);
    }

    #[test]
    fn sqrt_boundary() {
        let result = sqrt(-1.0);
        assert!(result.is_boundary());
    }

    #[test]
    fn map_propagates_boundary() {
        let result = divide(10.0, 0.0).map(|v| v * 2.0);
        assert!(result.is_boundary());
    }

    #[test]
    fn map_transforms_interior() {
        let result = divide(10.0, 2.0).map(|v| v * 2.0);
        assert_eq!(result.unwrap(), 10.0);
    }

    #[test]
    fn model_uncertain() {
        let result: Value<String, ModelUncertain> = Value::Boundary {
            reason: ModelUncertain { confidence: 0.3 },
            last: "Paris is the capital of France".to_string(),
        };
        assert!(result.is_boundary());
    }

    #[test]
    fn hallucinated() {
        let result: Value<String, Hallucinated> = Value::Boundary {
            reason: Hallucinated { confidence: 0.1, grounding: None },
            last: "The moon is made of cheese".to_string(),
        };
        match result {
            Value::Boundary { reason, .. } => assert!(reason.grounding.is_none()),
            _ => panic!("expected boundary"),
        }
    }

    #[test]
    fn and_then_interior() {
        let result = divide(10.0, 2.0).and_then(|v| divide(v, 2.0));
        assert!(result.is_interior());
        assert_eq!(result.unwrap(), 2.5);
    }

    #[test]
    fn and_then_propagates_boundary() {
        let result = divide(10.0, 0.0).and_then(|v| divide(v, 2.0));
        assert!(result.is_boundary());
    }

    // -- boundary_check macro tests --

    #[boundary_check]
    fn safe_divide(a: f64, b: f64) -> f64 {
        divide(a, b).or(0.0)
    }

    #[test]
    fn boundary_check_allows_or() {
        assert_eq!(safe_divide(10.0, 2.0), 5.0);
        assert_eq!(safe_divide(10.0, 0.0), 0.0);
    }

    #[boundary_check]
    fn safe_match(a: f64, b: f64) -> f64 {
        match divide(a, b) {
            Value::Interior(v) => v,
            Value::Boundary { reason: DivisionByZero, last } => last,
        }
    }

    #[test]
    fn boundary_check_allows_match() {
        assert_eq!(safe_match(10.0, 2.0), 5.0);
        assert_eq!(safe_match(10.0, 0.0), 10.0);
    }

    // -- derive(BoundaryKind) test --

    #[derive(Debug, Clone, BoundaryKind)]
    #[boundary_kind(crate_path = "crate")]
    struct InsufficientFunds {
        balance: f64,
        required: f64,
    }

    #[test]
    fn user_defined_boundary() {
        let result: Value<f64, InsufficientFunds> = Value::Boundary {
            reason: InsufficientFunds { balance: 50.0, required: 100.0 },
            last: 50.0,
        };
        assert!(result.is_boundary());
        match result {
            Value::Boundary { reason, .. } => {
                assert_eq!(reason.balance, 50.0);
                assert_eq!(reason.required, 100.0);
            }
            _ => panic!("expected boundary"),
        }
    }
}