train-kouts 0.1.0

Explainable planning decisions across railways and roads
Documentation
//! Explainable planning decisions where railways and roads interact.
//!
//! The model treats safety as a gate and keeps every conclusion tied to
//! non-empty evidence. It is not a traffic simulation or regulatory approval.

#![forbid(unsafe_code)]
#![warn(missing_docs)]

use std::collections::BTreeMap;
use std::error::Error;
use std::fmt;

/// MLIT information about railway-crossing safety.
pub const MLIT_CROSSING_SAFETY_URL: &str = "https://www.mlit.go.jp/tetudo/tetudo_tk9_000004.html";

/// MLIT information about integrated transport terminals.
pub const MLIT_TRANSPORT_HUB_URL: &str = "https://www.mlit.go.jp/road/busterminal/";

/// A principle for evaluating the relationship between rail and road.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum TransportPrinciple {
    /// Prevent collisions and protect pedestrians at crossings and interfaces.
    InterfaceSafety,
    /// Keep transfers short, legible, and continuous across modes.
    ConnectedJourney,
    /// Include step-free, visible, and usable routes for diverse travelers.
    UniversalAccess,
    /// Balance delay and reliability without shifting harm to another mode.
    ReliableFlow,
    /// Reduce emissions, noise, and avoidable land consumption.
    EnvironmentalCare,
    /// Maintain useful alternatives during disruption or maintenance.
    NetworkResilience,
}

impl TransportPrinciple {
    /// Every principle in stable report order.
    pub const ALL: [Self; 6] = [
        Self::InterfaceSafety,
        Self::ConnectedJourney,
        Self::UniversalAccess,
        Self::ReliableFlow,
        Self::EnvironmentalCare,
        Self::NetworkResilience,
    ];
}

/// Evidence-based impact on one transport principle.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Impact {
    /// The proposal measurably improves the principle.
    Improves,
    /// The proposal has no material effect.
    Neutral,
    /// A plausible risk remains and needs mitigation.
    NeedsMitigation,
    /// Evidence shows material harm.
    Harms,
}

/// An impact and its supporting evidence.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Assessment {
    impact: Impact,
    evidence: String,
}

impl Assessment {
    /// Creates an assessment, rejecting blank evidence.
    pub fn new(impact: Impact, evidence: impl Into<String>) -> Result<Self, TransportError> {
        let evidence = evidence.into();
        if evidence.trim().is_empty() {
            return Err(TransportError::EmptyEvidence);
        }
        Ok(Self { impact, evidence })
    }

    /// Returns the impact.
    pub const fn impact(&self) -> Impact {
        self.impact
    }

    /// Returns the evidence.
    pub fn evidence(&self) -> &str {
        &self.evidence
    }
}

/// A railway-and-road project proposal.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransportPlan {
    name: String,
    assessments: BTreeMap<TransportPrinciple, Assessment>,
}

impl TransportPlan {
    /// Creates an unassessed plan with a non-blank name.
    pub fn new(name: impl Into<String>) -> Result<Self, TransportError> {
        let name = name.into();
        if name.trim().is_empty() {
            return Err(TransportError::EmptyPlanName);
        }
        Ok(Self {
            name,
            assessments: BTreeMap::new(),
        })
    }

    /// Adds or replaces an assessment and returns the plan for chaining.
    pub fn assess(
        mut self,
        principle: TransportPrinciple,
        impact: Impact,
        evidence: impl Into<String>,
    ) -> Result<Self, TransportError> {
        self.set_assessment(principle, impact, evidence)?;
        Ok(self)
    }

    /// Adds or replaces an assessment in place.
    pub fn set_assessment(
        &mut self,
        principle: TransportPrinciple,
        impact: Impact,
        evidence: impl Into<String>,
    ) -> Result<(), TransportError> {
        self.assessments
            .insert(principle, Assessment::new(impact, evidence)?);
        Ok(())
    }

    /// Returns the plan name.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// Returns an assessment when present.
    pub fn assessment(&self, principle: TransportPrinciple) -> Option<&Assessment> {
        self.assessments.get(&principle)
    }
}

/// Final decision from the integrated policy.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransportDecision {
    /// Known interface-safety harm is a veto.
    Decline,
    /// At least one principle lacks evidence.
    NeedsEvidence,
    /// Every principle is assessed, but mitigation or harm remains.
    Revise,
    /// Every principle is neutral or improved with evidence.
    Integrated,
}

/// Strict transport policy in which safety harm cannot be traded away.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct IntegratedPolicy;

impl IntegratedPolicy {
    /// Evaluates a plan and returns an explainable report.
    pub fn evaluate(plan: &TransportPlan) -> TransportReport {
        let mut missing = Vec::new();
        let mut needs_mitigation = Vec::new();
        let mut harms = Vec::new();

        for principle in TransportPrinciple::ALL {
            match plan.assessment(principle).map(Assessment::impact) {
                None => missing.push(principle),
                Some(Impact::Improves | Impact::Neutral) => {}
                Some(Impact::NeedsMitigation) => needs_mitigation.push(principle),
                Some(Impact::Harms) => harms.push(principle),
            }
        }

        let safety_harm = harms.contains(&TransportPrinciple::InterfaceSafety);
        let decision = if safety_harm {
            TransportDecision::Decline
        } else if !missing.is_empty() {
            TransportDecision::NeedsEvidence
        } else if !needs_mitigation.is_empty() || !harms.is_empty() {
            TransportDecision::Revise
        } else {
            TransportDecision::Integrated
        };

        TransportReport {
            decision,
            missing,
            needs_mitigation,
            harms,
        }
    }
}

/// Explainable decision report in stable principle order.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransportReport {
    decision: TransportDecision,
    missing: Vec<TransportPrinciple>,
    needs_mitigation: Vec<TransportPrinciple>,
    harms: Vec<TransportPrinciple>,
}

impl TransportReport {
    /// Returns the final decision.
    pub const fn decision(&self) -> TransportDecision {
        self.decision
    }

    /// Returns principles without evidence.
    pub fn missing(&self) -> &[TransportPrinciple] {
        &self.missing
    }

    /// Returns principles requiring mitigation.
    pub fn needs_mitigation(&self) -> &[TransportPrinciple] {
        &self.needs_mitigation
    }

    /// Returns principles with known harm.
    pub fn harms(&self) -> &[TransportPrinciple] {
        &self.harms
    }
}

/// Invalid transport-plan input.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransportError {
    /// Plan name was blank.
    EmptyPlanName,
    /// Assessment evidence was blank.
    EmptyEvidence,
}

impl fmt::Display for TransportError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::EmptyPlanName => formatter.write_str("plan name must not be blank"),
            Self::EmptyEvidence => formatter.write_str("assessment evidence must not be blank"),
        }
    }
}

impl Error for TransportError {}

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

    fn integrated_plan() -> TransportPlan {
        TransportPrinciple::ALL
            .into_iter()
            .try_fold(
                TransportPlan::new("station approach").unwrap(),
                |plan, principle| plan.assess(principle, Impact::Improves, "measured improvement"),
            )
            .unwrap()
    }

    #[test]
    fn complete_positive_plan_is_integrated() {
        assert_eq!(
            IntegratedPolicy::evaluate(&integrated_plan()).decision(),
            TransportDecision::Integrated
        );
    }

    #[test]
    fn safety_harm_is_a_veto_even_with_missing_evidence() {
        let plan = TransportPlan::new("crossing change")
            .unwrap()
            .assess(
                TransportPrinciple::InterfaceSafety,
                Impact::Harms,
                "pedestrian conflict increases",
            )
            .unwrap();
        let report = IntegratedPolicy::evaluate(&plan);
        assert_eq!(report.decision(), TransportDecision::Decline);
        assert_eq!(report.harms(), &[TransportPrinciple::InterfaceSafety]);
    }

    #[test]
    fn empty_plan_needs_all_evidence_in_stable_order() {
        let report = IntegratedPolicy::evaluate(&TransportPlan::new("draft").unwrap());
        assert_eq!(report.decision(), TransportDecision::NeedsEvidence);
        assert_eq!(report.missing(), &TransportPrinciple::ALL);
    }

    #[test]
    fn unresolved_access_risk_requires_revision() {
        let mut plan = integrated_plan();
        plan.set_assessment(
            TransportPrinciple::UniversalAccess,
            Impact::NeedsMitigation,
            "step-free detour is too long",
        )
        .unwrap();
        let report = IntegratedPolicy::evaluate(&plan);
        assert_eq!(report.decision(), TransportDecision::Revise);
        assert_eq!(
            report.needs_mitigation(),
            &[TransportPrinciple::UniversalAccess]
        );
    }

    #[test]
    fn blank_inputs_are_rejected() {
        assert_eq!(TransportPlan::new(" "), Err(TransportError::EmptyPlanName));
        assert_eq!(
            Assessment::new(Impact::Neutral, "\t"),
            Err(TransportError::EmptyEvidence)
        );
    }
}