origin/

lib.rs

//! # Origin
//!
//! Every value is origin, at a boundary, or contents.
//! The compiler knows which. One pattern. Every domain.
//!
//! Three sorts — matching the formal foundation in `Val α`:
//! - `Origin(B)` — pure absorption. The system hit its absolute boundary.
//!   No last value. The reason is all that exists.
//! - `Boundary { reason, last }` — crossed an edge. The container preserves
//!   the last known value and the reason.
//! - `Contents(T)` — actual value. Arithmetic lives here.

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.
///
/// The `'static` bound means boundary kinds must be owned —
/// they cannot borrow from the computation that produced them.
/// Use owned `String` instead of `&str`, clone data you need
/// to carry. This keeps boundary reasons self-contained and
/// safe to propagate across thread boundaries.
pub trait BoundaryKind: fmt::Debug + Send + Sync + 'static {}

/// The core type. Origin, Boundary, or Contents. Three sorts. Every domain.
///
/// Formally verified in Lean 4 as `Val α`:
/// - `origin` — absorbs everything (I1, I2, I3)
/// - `container` — structural, preserves last known value
/// - `contents` — actual arithmetic, the field interior
///
/// 508 theorems. Zero errors. Zero sorries.
#[derive(Debug)]
#[must_use = "this Value may be at a boundary that must be handled"]
pub enum Value<T, B: BoundaryKind = GenericBoundary> {
    /// Origin: the computation hit the absolute boundary.
    /// There is no last value. The reason is all that exists.
    /// The ocean absorbed the fish.
    Origin(B),
    /// Boundary: the computation crossed an edge.
    /// Carries the reason and the last known value.
    /// The container preserves what was there.
    Boundary {
        reason: B,
        last: T,
    },
    /// Contents: the value is in safe territory. Arithmetic lives here.
    Contents(T),
}

impl<T, B: BoundaryKind> Value<T, B> {
    /// Construct an origin value — pure boundary, no last value.
    pub fn origin(reason: B) -> Self {
        Value::Origin(reason)
    }

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

    /// Construct a contents value.
    pub fn contents(value: T) -> Self {
        Value::Contents(value)
    }

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

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

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

    /// Unwrap the contents value, or return a fallback.
    ///
    /// Both Origin and Boundary return the fallback — if you need to
    /// distinguish them, use `match` or `or_else` instead.
    pub fn or(self, fallback: T) -> T {
        match self {
            Value::Contents(v) => v,
            Value::Boundary { .. } => fallback,
            Value::Origin(_) => fallback,
        }
    }

    /// Handle Origin and Boundary distinctly when extracting a value.
    ///
    /// Unlike `or`, this preserves the distinction between the three sorts:
    /// - Contents: returns the value directly
    /// - Boundary: calls `on_boundary` with the reason AND last value
    /// - Origin: calls `on_origin` with only the reason (no last value)
    pub fn or_else(
        self,
        on_boundary: impl FnOnce(B, T) -> T,
        on_origin: impl FnOnce(B) -> T,
    ) -> T {
        match self {
            Value::Contents(v) => v,
            Value::Boundary { reason, last } => on_boundary(reason, last),
            Value::Origin(reason) => on_origin(reason),
        }
    }

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

    /// Map over the contents value. Origin passes through unchanged.
    /// Boundary maps the transform over `last`.
    ///
    /// Note: if you chain multiple `map` calls, `last` reflects the
    /// transformed value at each step, not the original value at the
    /// boundary. If you need the original `last`, use `match` explicitly.
    pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Value<U, B> {
        match self {
            Value::Contents(v) => Value::Contents(f(v)),
            Value::Boundary { reason, last } => Value::Boundary {
                reason,
                last: f(last),
            },
            Value::Origin(reason) => Value::Origin(reason),
        }
    }

    /// Extract the contents value, or return the boundary reason as `Err`
    /// for `?` propagation.
    ///
    /// Both Boundary and Origin become `Err(reason)`. The `last` value
    /// in Boundary is dropped. If you need `last`, use `match` or
    /// `propagate_with_last` instead.
    pub fn propagate(self) -> Result<T, B> {
        match self {
            Value::Contents(v) => Ok(v),
            Value::Boundary { reason, .. } => Err(reason),
            Value::Origin(reason) => Err(reason),
        }
    }

    /// Propagate, preserving the last value if at a Boundary.
    ///
    /// - Contents → `Ok(value)`
    /// - Boundary → `Err((reason, Some(last)))`
    /// - Origin → `Err((reason, None))`
    pub fn propagate_with_last(self) -> Result<T, (B, Option<T>)> {
        match self {
            Value::Contents(v) => Ok(v),
            Value::Boundary { reason, last } => Err((reason, Some(last))),
            Value::Origin(reason) => Err((reason, None)),
        }
    }

    /// Extract the contents value while recording the step in a trace.
    pub fn trace(self, chain: &mut Chain, label: &'static str) -> Result<T, B>
    where
        T: std::fmt::Debug,
    {
        match self {
            Value::Contents(v) => {
                chain.record(label, &v);
                Ok(v)
            }
            Value::Boundary { reason, last } => {
                chain.record_boundary(label, &last);
                Err(reason)
            }
            Value::Origin(reason) => {
                chain.record_origin(label);
                Err(reason)
            }
        }
    }

    /// Chain operations that may themselves hit a boundary.
    ///
    /// If already at Origin, propagates as Origin.
    /// If at Boundary, `last` is dropped and propagates as Origin —
    /// because the type has changed and the old `last` has no meaning
    /// in the new type. If you need `last`, use `match` before chaining.
    ///
    /// `and_then` is for Contents pipelines. For Boundary-aware chaining,
    /// use `match` explicitly. No `Default` bound needed — Origin carries
    /// no value.
    pub fn and_then<U>(self, f: impl FnOnce(T) -> Value<U, B>) -> Value<U, B> {
        match self {
            Value::Contents(v) => f(v),
            Value::Boundary { reason, .. } => Value::Origin(reason),
            Value::Origin(reason) => Value::Origin(reason),
        }
    }
}

// -- 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 contents 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,
        });
    }

    /// Record an origin hit — pure boundary, no value.
    pub fn record_origin(&mut self, label: &'static str) {
        self.entries.push(ChainEntry {
            label,
            value: "⊘ origin".to_string(),
            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 demonstrate that contents
// divided by contents is always contents — the sort is determined by
// the type, not by the value.
//
// IEEE 754 already handles the value-level edge cases: 0/0 = NaN,
// x/0 = ±Inf, sqrt(-1) = NaN. These are contents values — they're
// what the arithmetic produces. The sort system doesn't override
// IEEE 754. It names what IEEE 754 leaves unnamed: origin is the
// boundary of the system, not a float value.

/// Division. Contents divided by contents is always contents.
/// IEEE 754 handles the value: 10/0 = Inf, 0/0 = NaN.
/// The sort is determined. The value is arithmetic's problem.
pub fn divide(a: f64, b: f64) -> f64 {
    a / b
}

/// Square root. Contents in, contents out.
/// IEEE 754 handles negative input: sqrt(-1) = NaN.
/// The sort is determined. The value is arithmetic's problem.
pub fn sqrt(a: f64) -> f64 {
    a.sqrt()
}

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

    #[test]
    fn division_is_always_contents() {
        // Contents divided by contents is contents. Always.
        assert_eq!(divide(10.0, 2.0), 5.0);
    }

    #[test]
    fn division_by_zero_is_contents() {
        // 0.0 is contents(0), not origin. IEEE 754 gives infinity.
        // The SORT is determined. The VALUE is arithmetic's problem.
        assert!(divide(10.0, 0.0).is_infinite());
    }

    #[test]
    fn zero_div_zero_is_contents() {
        // 0/0 = NaN. NaN is a contents value — what IEEE 754 produces.
        // Not origin. Not boundary. Contents.
        assert!(divide(0.0, 0.0).is_nan());
    }

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

    #[test]
    fn sqrt_negative_is_contents() {
        // sqrt(-1) = NaN. A contents value. Not a boundary.
        assert!(sqrt(-1.0).is_nan());
    }

    #[test]
    fn map_propagates_boundary() {
        let v: Value<f64, DivisionByZero> = Value::boundary(DivisionByZero, 10.0);
        let result = v.map(|v| v * 2.0);
        assert!(result.is_boundary());
    }

    #[test]
    fn map_transforms_contents() {
        let v: Value<f64, DivisionByZero> = Value::contents(10.0);
        let result = v.map(|v| v * 2.0);
        assert_eq!(result.unwrap(), 20.0);
    }

    #[test]
    fn map_propagates_origin() {
        let v: Value<f64, DivisionByZero> = Value::origin(DivisionByZero);
        let result = v.map(|x| x * 2.0);
        assert!(result.is_origin());
    }

    #[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_contents() {
        let v: Value<f64, DivisionByZero> = Value::contents(10.0);
        let result = v.and_then(|x| Value::contents(x / 2.0));
        assert!(result.is_contents());
        assert_eq!(result.unwrap(), 5.0);
    }

    #[test]
    fn and_then_propagates_boundary_as_origin() {
        // Boundary through and_then becomes Origin (type changed, last meaningless)
        let v: Value<f64, DivisionByZero> = Value::boundary(DivisionByZero, 10.0);
        let result = v.and_then(|x| Value::contents(x / 2.0));
        assert!(result.is_origin());
    }

    #[test]
    fn origin_propagates_through_and_then() {
        let v: Value<f64, DivisionByZero> = Value::origin(DivisionByZero);
        let result = v.and_then(|x| Value::contents(x / 2.0));
        assert!(result.is_origin());
    }

    #[test]
    fn origin_or_fallback() {
        let v: Value<f64, DivisionByZero> = Value::origin(DivisionByZero);
        assert_eq!(v.or(42.0), 42.0);
    }

    // -- boundary_check macro tests --

    fn make_value(a: f64, b: f64) -> Value<f64, DivisionByZero> {
        // Domain logic decides what's a boundary — not the arithmetic.
        // This is how a real application would use Value:
        // the application defines its own boundary conditions.
        if b.abs() < 1e-10 {
            Value::boundary(DivisionByZero, a)
        } else {
            Value::contents(a / b)
        }
    }

    #[boundary_check]
    fn safe_divide(a: f64, b: f64) -> f64 {
        make_value(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 make_value(a, b) {
            Value::Contents(v) => v,
            Value::Boundary { reason: DivisionByZero, last } => last,
            Value::Origin(DivisionByZero) => 0.0,
        }
    }

    #[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"),
        }
    }
}