cobre-io 0.4.2

//! # cobre-io
//!
//! Case directory loading, validation, and result writing for the
//! [Cobre](https://github.com/cobre-rs/cobre) power systems ecosystem.
//!
//! This crate provides two top-level entry points:
//!
//! - [`load_case`] — reads a case directory and produces a fully-validated
//!   [`cobre_core::System`] ready for use by the solver.
//! - [`write_results`] — accepts aggregate result types and writes all output
//!   artifacts to a specified root directory.
//!
//! ## Loading pipeline
//!
//! [`load_case`] executes a five-layer validation pipeline:
//!
//! 1. **Structural validation** — checks that required files exist on disk and records
//!    which optional files are present ([`validation::structural`]).
//! 2. **Schema validation** — verifies required fields, types, and value ranges.
//! 3. **Referential integrity** — checks all entity ID cross-references are resolvable.
//! 4. **Dimensional consistency** — cross-file coverage checks (e.g., inflow params
//!    cover all hydros).
//! 5. **Semantic validation** — domain business rules (acyclic cascade, penalty ordering,
//!    PAR stationarity, etc.).
//!
//! All validation diagnostics are collected by [`validation::ValidationContext`] before
//! failing, so users see every problem in a single report.  Final errors are reported
//! via [`LoadError`], which carries enough context for diagnostic messages without
//! re-reading input files.
//!
//! ## Status
//!
//! This crate is in early development. The API **will** change.
//!
//! See the [repository](https://github.com/cobre-rs/cobre) for the current status.

#[cfg(feature = "schema")]
pub mod schema;

pub mod broadcast;
pub mod config;
pub mod constraints;
pub mod error;
pub mod extensions;
pub mod initial_conditions;
pub mod output;
pub(crate) mod parquet_helpers;
pub mod penalties;
pub(crate) mod pipeline;
pub mod report;
pub mod resolution;
pub mod scenarios;
pub mod stages;
pub mod system;
pub mod validation;

pub use broadcast::{deserialize_system, serialize_system};
pub use config::{Config, EstimationConfig, OrderSelectionMethod, PolicyMode, parse_config};
pub use constraints::{
    BlockExchangeFactor, BusPenaltyOverrideRow, ContractBoundsRow, ExchangeFactorEntry,
    GenericConstraintBoundsRow, HydroBoundsRow, HydroPenaltyOverrideRow, LineBoundsRow,
    LinePenaltyOverrideRow, NcsPenaltyOverrideRow, PumpingBoundsRow, ThermalBoundsRow,
    load_contract_bounds, load_exchange_factors, load_generic_constraint_bounds,
    load_generic_constraints, load_hydro_bounds, load_line_bounds, load_penalty_overrides_bus,
    load_penalty_overrides_hydro, load_penalty_overrides_line, load_penalty_overrides_ncs,
    load_pumping_bounds, load_thermal_bounds, parse_contract_bounds, parse_exchange_factors,
    parse_generic_constraint_bounds, parse_generic_constraints, parse_hydro_bounds,
    parse_line_bounds, parse_penalty_overrides_bus, parse_penalty_overrides_hydro,
    parse_penalty_overrides_line, parse_penalty_overrides_ncs, parse_pumping_bounds,
    parse_thermal_bounds,
};
pub use error::LoadError;
pub use extensions::{
    FittingWindow, FphaColumnLayout, FphaHyperplaneRow, HydroGeometryRow, ProductionModelConfig,
    SeasonConfig, SelectionMode, StageRange, load_fpha_hyperplanes, load_hydro_geometry,
    load_production_models, parse_fpha_hyperplanes, parse_hydro_geometry, parse_production_models,
};
pub use initial_conditions::parse_initial_conditions;
pub use output::policy::{
    OwnedPolicyBasisRecord, OwnedPolicyCutRecord, PolicyBasisRecord, PolicyCheckpoint,
    PolicyCheckpointMetadata, PolicyCutRecord, StageCutsPayload, StageCutsReadResult,
    StageStatesPayload, StageStatesReadResult, deserialize_stage_basis, deserialize_stage_cuts,
    deserialize_stage_states, read_policy_checkpoint, serialize_stage_basis, serialize_stage_cuts,
    serialize_stage_states, write_policy_checkpoint,
};
pub use output::{
    ConvergenceSummary, CutSelectionRecord, CutStatistics, DistributionInfo, IterationRecord,
    MetadataConfiguration, MetadataConvergence, MetadataCuts, MetadataIterations,
    MetadataProblemDimensions, MetadataScenarios, OutputContext, OutputError, ParquetWriterConfig,
    SimulationMetadata, SimulationOutput, SolverStatsRow, TrainingMetadata, TrainingOutput,
    TrainingParquetWriter, get_hostname, now_iso8601, read_convergence_summary,
    read_simulation_metadata, read_training_metadata, write_cut_selection_records,
    write_dictionaries, write_fpha_hyperplanes, write_provenance_report, write_results,
    write_scaling_report, write_simulation_metadata, write_simulation_results,
    write_simulation_solver_stats, write_solver_stats, write_training_metadata,
    write_training_results,
};
pub use penalties::parse_penalties;
pub use report::{ReportEntry, ValidationReport, generate_report};
pub use resolution::{resolve_bounds, resolve_penalties};
pub use scenarios::{
    BlockFactor, ExternalLoadRow, ExternalNcsRow, ExternalScenarioRow, InflowArCoefficientRow,
    InflowHistoryRow, InflowSeasonalStatsRow, LoadFactorEntry, LoadSeasonalStatsRow,
    NoiseOpeningRow, ScenarioData, assemble_inflow_models, assemble_load_models, load_correlation,
    load_external_inflow_scenarios, load_external_load_scenarios, load_external_ncs_scenarios,
    load_inflow_ar_coefficients, load_inflow_history, load_inflow_seasonal_stats,
    load_load_factors, load_load_seasonal_stats, load_noise_openings, load_scenarios,
    parse_correlation, parse_external_inflow_scenarios, parse_external_load_scenarios,
    parse_external_ncs_scenarios, parse_inflow_ar_coefficients, parse_inflow_history,
    parse_inflow_seasonal_stats, parse_load_factors, parse_load_seasonal_stats,
};
pub use stages::{StagesData, build_season_stage_map, parse_stages};
pub use system::{
    load_energy_contracts, load_non_controllable_sources, load_pumping_stations, parse_buses,
    parse_energy_contracts, parse_hydros, parse_lines, parse_non_controllable_sources,
    parse_pumping_stations, parse_thermals,
};
pub use validation::structural::{FileManifest, validate_structure};
pub use validation::{ErrorKind, Severity, ValidationContext, ValidationEntry};

use cobre_core::System;
use std::path::Path;

/// Load a case directory and return a fully-validated [`System`].
///
/// `path` must point to the root case directory containing `config.json` and the
/// standard subdirectories (`system/`, `scenarios/`, `constraints/`, `policy/`).
///
/// The function executes a five-layer validation pipeline:
///
/// 1. **Structural** — all required files exist on disk.
/// 2. **Schema** — required fields, types, and value ranges are valid.
/// 3. **Referential integrity** — all cross-entity ID references resolve.
/// 4. **Dimensional consistency** — entity coverage across optional files.
/// 5. **Semantic** — domain business rules (acyclic cascade, penalty ordering, etc.).
///
/// After all layers pass, three-tier penalty/bound resolution and scenario assembly
/// are performed before constructing the [`System`].
///
/// Warnings collected during validation are silently discarded. Use [`validate_case`]
/// when you need to inspect or display warnings alongside the loaded [`System`].
///
/// # Errors
///
/// - [`LoadError::IoError`] — a required file is missing or cannot be read.
/// - [`LoadError::ParseError`] — a file contains malformed JSON or invalid Parquet.
/// - [`LoadError::SchemaError`] — a domain constraint violation detected
///   post-deserialization (e.g., AR coefficient count mismatch).
/// - [`LoadError::ConstraintError`] — one or more validation errors collected
///   across Layers 1-5, or `SystemBuilder` rejected the assembled data.
pub fn load_case(path: &Path) -> Result<System, LoadError> {
    pipeline::run_pipeline(path)
}

/// Load a case directory and return both the fully-validated [`System`] and a
/// [`ValidationReport`] containing all warnings collected during the pipeline.
///
/// This function runs the same five-layer validation pipeline as [`load_case`] but
/// preserves warnings so that callers can display them to the user. Errors still
/// cause the function to return `Err`; warnings never block loading.
///
/// # Errors
///
/// Same error conditions as [`load_case`].
pub fn validate_case(path: &Path) -> Result<(System, ValidationReport), LoadError> {
    pipeline::run_pipeline_with_report(path)
}