powerio_pkg/lib.rs
1//! `powerio-pkg`: the `.pio.json` compiler package.
2//!
3//! PowerIO has no single flattened "universal network" struct. It has two
4//! concrete static-grid IR families that stay distinct:
5//!
6//! - [`powerio::BalancedNetwork`] (the scalar positive-sequence transmission
7//! model, historically `powerio::Network`);
8//! - [`powerio_dist::MulticonductorNetwork`] (the wire-coordinate distribution
9//! model, historically `powerio_dist::DistNetwork`).
10//!
11//! A [`CompilerPackage`] is the readable envelope that wraps exactly one of
12//! those payloads at a time, alongside the metadata a compiler artifact needs
13//! to be trustworthy: an explicit [`ModelKind`], producer and origin metadata,
14//! source maps, structured diagnostics, a validation summary, and lowering
15//! history. It serializes to `.pio.json`. See `docs/src/compiler-ir.md` for the
16//! architecture and `docs/src/pio-json-schema.md` for the field reference.
17//!
18//! The package always carries [`CompilerPackage::model_kind`] explicitly; a
19//! reader must never infer whether the payload is balanced or multiconductor
20//! from which field is present. [`CompilerPackage::kind_is_consistent`] asserts
21//! the explicit kind agrees with the payload variant.
22//!
23//! ```
24//! use powerio_pkg::{CompilerPackage, ModelKind};
25//!
26//! let net = powerio::BalancedNetwork::in_memory("demo", 100.0, vec![], vec![]);
27//! let pkg = CompilerPackage::from_balanced(net);
28//! assert_eq!(pkg.model_kind(), ModelKind::Balanced);
29//! assert!(pkg.kind_is_consistent());
30//! let json = pkg.to_json_pretty().unwrap();
31//! let back = CompilerPackage::from_json(&json).unwrap();
32//! assert_eq!(back.model_kind(), ModelKind::Balanced);
33//! ```
34//!
35//! Binary `.pio` is out of scope until the JSON package stabilizes; this crate
36//! is JSON only.
37
38pub mod diagnostics;
39pub mod lowering;
40pub mod model;
41pub mod package;
42pub mod provenance;
43pub mod summary;
44pub mod validation;
45
46pub use diagnostics::{DiagnosticCode, DiagnosticSeverity, DiagnosticStage, StructuredDiagnostic};
47pub use lowering::{
48 LoweringRecord, MulticonductorToBalancedError, MulticonductorToBalancedLowering,
49 MulticonductorToBalancedOptions, MulticonductorToBalancedReadiness,
50 SequenceTransformConvention, check_multiconductor_to_balanced_lowering,
51 lower_multiconductor_to_balanced,
52};
53pub use model::{ModelKind, ModelPayload};
54pub use package::{
55 CompilerPackage, DerivedMetadata, NormalizedSolverTableMetadata,
56 NormalizedSolverTableRowCounts, NormalizedSolverTableSourceRows, PIO_PACKAGE_SCHEMA_URL,
57 PIO_PACKAGE_SCHEMA_VERSION,
58};
59pub use provenance::{
60 Confidence, MappingKind, Origin, Producer, SourceDescriptor, SourceMapEntry, SourceRef,
61};
62pub use summary::{ObjectSummary, ObjectTopology, ObjectUnits};
63pub use validation::{ValidationCounts, ValidationPass, ValidationStatus, ValidationSummary};