powerio_capi/

lib.rs

//! C ABI for `powerio`: ABI v4.
//!
//! Parse any supported power system case format into an opaque handle, query
//! it, convert it to another format, and pull out the numeric tables a
//! downstream solver needs to assemble matrices. Every entry point is
//! `extern "C"`, catches panics at the boundary, and returns error text into a
//! caller-provided buffer.
//!
//! The surface follows a fixed grammar, written out in the header preamble
//! (`include/powerio.h`, generated by cbindgen, never hand-edit):
//!
//! - Verb-led names are operations and the verb fixes the return family:
//!   `parse`/`read`/`normalize` return a new handle, `write` has a filesystem
//!   effect, `convert` transcodes without keeping a handle, `free` destroys.
//! - `to_` marks a representation change of the same network; the target is a
//!   format string (`pio_to_format`) unless the output type differs
//!   (`pio_to_arrow` fills Arrow C Data Interface structs).
//! - Format names never appear in symbols: formats are strings, so a new
//!   format never changes this ABI. The canonical snapshot is the
//!   `powerio-json` format name.
//! - Array extractors share the cap/count convention: write up to `cap`
//!   values, return the total available, `NULL` out is a pure count query.
//! - Vocabulary: a *bus* is a named connection point (this surface is bus
//!   granular); a *node* is one conductor's point at a bus, reserved for the
//!   multiconductor surface; a *branch* is any two-terminal series element,
//!   lines and transformers alike.

#![allow(clippy::missing_safety_doc)]

use std::ffi::{CStr, CString, c_char};
use std::panic::{AssertUnwindSafe, catch_unwind};

use powerio::{IndexCore, IndexedNetwork, Network, TargetFormat};

#[cfg(feature = "arrow")]
mod arrow_export;
#[cfg(feature = "arrow")]
pub use arrow_export::{
    PIO_ARROW_TABLE_BRANCH, PIO_ARROW_TABLE_BUS, PIO_ARROW_TABLE_GEN, PIO_ARROW_TABLE_LOAD,
    PIO_ARROW_TABLE_SHUNT, PIO_ARROW_TABLE_SOLVER_ARC, PIO_ARROW_TABLE_SOLVER_BRANCH,
    PIO_ARROW_TABLE_SOLVER_BUS, PIO_ARROW_TABLE_SOLVER_GEN, PIO_ARROW_TABLE_SOLVER_HVDC,
    PIO_ARROW_TABLE_SOLVER_LOAD, PIO_ARROW_TABLE_SOLVER_SHUNT, PIO_ARROW_TABLE_SOLVER_STORAGE,
    PIO_ARROW_TABLE_SOLVER_SWITCH, PIO_ARROW_TABLE_SWITCH,
};

/// Opaque parsed network handle. Carries the parsed [`Network`], the
/// [`IndexCore`] derived from it once at parse time (so every indexed query
/// reuses the same bus-id map and per-bus aggregates instead of rebuilding
/// them), and the reader's fidelity warnings ([`pio_warnings`]).
pub struct PioNetwork {
    net: Network,
    core: IndexCore,
    warnings: Vec<String>,
}

// The handle is immutable after construction and the C ABI documents concurrent
// reads from any number of threads as safe (see the cbindgen header preamble).
// That guarantee requires `PioNetwork: Send + Sync`; pin it at compile time so
// a future field that is not `Sync` fails the build instead of weakening it.
const _: fn() = || {
    fn assert_send_sync<T: Send + Sync>() {}
    assert_send_sync::<PioNetwork>();
};

/// Copy `msg` (truncated to fit) into a caller `char[len]` buffer, always
/// NUL-terminated. Truncation backs up to a UTF-8 character boundary so a
/// clipped message is still valid UTF-8. Shared by the error and warning
/// outputs.
///
/// # Safety
/// A non-NULL `buf` must point to at least `len` writable bytes; the write
/// stays within `len` (at most `len - 1` message bytes plus the terminating
/// NUL). NULL or `len == 0` is a no-op.
unsafe fn copy_to_buf(buf: *mut c_char, len: usize, msg: &str) {
    unsafe {
        if buf.is_null() || len == 0 {
            return;
        }
        let bytes = msg.as_bytes();
        let mut n = bytes.len().min(len - 1);
        while n > 0 && !msg.is_char_boundary(n) {
            n -= 1;
        }
        std::ptr::copy_nonoverlapping(bytes.as_ptr().cast::<c_char>(), buf, n);
        *buf.add(n) = 0;
    }
}

unsafe fn cstr<'a>(p: *const c_char) -> Option<&'a str> {
    unsafe {
        if p.is_null() {
            return None;
        }
        CStr::from_ptr(p).to_str().ok()
    }
}

/// Move `s` into an owned C string, or `None` if it holds an interior NUL byte
/// (which can't cross as a C string). Callers surface the `None` as a real error
/// rather than silently handing back an empty string.
fn into_cstring(s: String) -> Option<*mut c_char> {
    CString::new(s).ok().map(CString::into_raw)
}

/// Finish a `*mut c_char` entry point: hand back the owned C string, or on an
/// interior NUL write the error into `errbuf` (NULL/0 to skip) and return NULL.
/// The shared tail of the string-returning functions.
fn finish_cstring(s: String, errbuf: *mut c_char, errlen: usize) -> *mut c_char {
    match into_cstring(s) {
        Some(p) => p,
        None => {
            unsafe { copy_to_buf(errbuf, errlen, "output contained an interior NUL byte") };
            std::ptr::null_mut()
        }
    }
}

/// Run `f` at the FFI boundary, catching any panic so it can't unwind across
/// `extern "C"` (UB). Returns `fallback` if `f` panics.
unsafe fn guard<R>(fallback: R, f: impl FnOnce() -> R) -> R {
    catch_unwind(AssertUnwindSafe(f)).unwrap_or(fallback)
}

/// Box a `Network` into an owned network handle, building its [`IndexCore`] once so
/// every indexed query reuses it. The one constructor for `*mut PioNetwork`.
fn make_network(net: Network, warnings: Vec<String>) -> *mut PioNetwork {
    let core = IndexCore::build(&net);
    Box::into_raw(Box::new(PioNetwork {
        net,
        core,
        warnings,
    }))
}

/// Finish a `*mut PioNetwork` entry point: run `f` (producing a `Network` with
/// its read warnings, or an error message) under the panic guard, hand back an
/// owned handle, or write the error, `panic_msg` if `f` panicked, into `errbuf`
/// and return NULL. The shared tail of every handle-returning function
/// (`pio_parse_file`, `pio_parse_str`, `pio_read_dir`, `pio_normalize`).
unsafe fn finish_network(
    errbuf: *mut c_char,
    errlen: usize,
    panic_msg: &str,
    f: impl FnOnce() -> Result<(Network, Vec<String>), String>,
) -> *mut PioNetwork {
    unsafe {
        // make_network runs inside the guard: IndexCore::build is part of the
        // entry point's work and the header promises panics never cross the
        // boundary.
        match catch_unwind(AssertUnwindSafe(|| {
            f().map(|(net, warnings)| make_network(net, warnings))
        })) {
            Ok(Ok(handle)) => handle,
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                std::ptr::null_mut()
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, panic_msg);
                std::ptr::null_mut()
            }
        }
    }
}

/// ABI version of this C interface. Bump on any breaking change to an existing
/// `pio_*` signature or to the `powerio-json` snapshot schema (new additive
/// symbols don't require a bump). A consumer compares [`pio_abi_version`]
/// against the value it was built against (the `PIO_ABI_VERSION` macro in
/// `powerio.h`) and refuses a mismatched library instead of calling in blind.
///
/// v4 froze the naming grammar and conventions (see the header preamble); the
/// surface evolves additively from here: new data means new symbols, and rich
/// or multiconductor data rides the Arrow and `powerio-json` schemas, which
/// carry their own structure and never force a signature change.
pub const PIO_ABI_VERSION: u32 = 4;

/// ABI version of the optional `pio_dist_*` C surface. This is separate from
/// [`PIO_ABI_VERSION`] so distribution C entry points can evolve without forcing
/// a core ABI bump. Version 1 is the supported dist surface with conversion
/// order `(input, from, to, ...)`.
#[cfg(feature = "dist")]
pub const PIO_DIST_ABI_VERSION: u32 = 1;

/// A comfortable error-buffer size: pass a `char[PIO_ERRBUF_MIN]` to any
/// `errbuf`/`warnbuf` parameter and a message always fits without truncation.
pub const PIO_ERRBUF_MIN: usize = 256;

/// The ABI version the library was built with (see [`PIO_ABI_VERSION`]). Lets a
/// consumer detect a stale or incompatible library at load time. Infallible.
#[unsafe(no_mangle)]
pub extern "C" fn pio_abi_version() -> u32 {
    PIO_ABI_VERSION
}

/// The ABI version of the optional `pio_dist_*` surface. Only linked when the
/// `dist` feature is compiled in; probe that first with `pio_has_feature("dist")`
/// if loading dynamically.
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub extern "C" fn pio_dist_abi_version() -> u32 {
    PIO_DIST_ABI_VERSION
}

/// Whether an optional build feature is compiled in: pass `"arrow"`, `"gridfm"`,
/// `"dist"`, or `"pkg"`. Returns 1 if present, 0 otherwise (and 0 for a NULL or
/// unknown name). The optional surfaces (`pio_to_arrow`, the `pio_read_dir`/
/// gridfm path, the `pio_dist_*` block, and the `pio_package_*` block) are only
/// linked when their feature is built, so a consumer that loaded the library at
/// runtime probes for them here instead of resolving symbols blind. Feature
/// names are strings like format names, so a new feature never changes this
/// signature. Infallible.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_has_feature(feature: *const c_char) -> i32 {
    unsafe {
        guard(0, || {
            let Some(name) = cstr(feature) else { return 0 };
            let features: &[(&str, bool)] = &[
                ("arrow", cfg!(feature = "arrow")),
                ("gridfm", cfg!(feature = "gridfm")),
                ("dist", cfg!(feature = "dist")),
                ("pkg", cfg!(feature = "pkg")),
            ];
            i32::from(features.iter().any(|&(n, on)| n == name && on))
        })
    }
}

/// The crate version string (a semver string), `'static` and NUL-terminated. Do
/// NOT free it. Informational; pair it with [`pio_abi_version`] for the actual
/// compatibility check.
#[unsafe(no_mangle)]
pub extern "C" fn pio_version() -> *const c_char {
    // env! is resolved at compile time; the trailing NUL makes it a valid C
    // string and the 'static lifetime means the pointer is always valid and
    // never owned by the caller.
    concat!(env!("CARGO_PKG_VERSION"), "\0")
        .as_ptr()
        .cast::<c_char>()
}

fn target_format_from_c(to: *const c_char) -> Result<TargetFormat, String> {
    let to = unsafe { cstr(to) }.ok_or_else(|| "to is NULL or not UTF-8".to_string())?;
    to.parse::<TargetFormat>().map_err(|e| e.to_string())
}

fn optional_cstr<'a>(p: *const c_char, name: &str) -> Result<Option<&'a str>, String> {
    if p.is_null() {
        Ok(None)
    } else {
        unsafe { cstr(p) }
            .map(Some)
            .ok_or_else(|| format!("{name} is not UTF-8"))
    }
}

/// Like [`cstr`] but a NULL or non-UTF-8 pointer is an error naming the
/// offending parameter. Entry points use this for required strings.
#[cfg(any(feature = "dist", feature = "pkg"))]
fn required_cstr<'a>(p: *const c_char, name: &str) -> Result<&'a str, String> {
    unsafe { cstr(p) }.ok_or_else(|| format!("{name} is NULL or not UTF-8"))
}

/// Parse `path` (format from extension, or `from` if non-NULL) into a network
/// handle. `from` accepts the [`pio_parse_str`] format names plus
/// `pypsa-csv`/`pypsa`, `goc3-json`/`goc3`, `surge-json`/`surge`, and `pwb`;
/// that includes `pslf`/`epc`, and `.epc` is inferred by extension. A PyPSA CSV folder is a directory, so it can only
/// enter through this function, with `from = "pypsa-csv"` (or NULL when the
/// directory holds a `network.csv`). Read fidelity warnings attach to the
/// handle ([`pio_warnings`]). Returns `NULL` on error and writes the message
/// into `errbuf`. Free the handle with [`pio_network_free`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_parse_file(
    path: *const c_char,
    from: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while parsing", || {
            let path = cstr(path).ok_or_else(|| "path is NULL or not UTF-8".to_string())?;
            let from = optional_cstr(from, "from")?;
            powerio::parse_file(std::path::Path::new(path), from)
                .map(|p| (p.network, p.warnings))
                .map_err(|e| e.to_string())
        })
    }
}

/// Parse in-memory case `text` of the named `format` into a network handle.
/// Unlike [`pio_parse_file`] there is no path to infer from, so `format` is
/// required: one of `matpower`/`m`, `powermodels`/`pm`, `egret`,
/// `pandapower-json`/`pandapower`/`pp`, `psse`/`raw`, `powerworld`/`aux`,
/// `pslf`/`epc`, `goc3-json`/`goc3`, `surge-json`/`surge`, or `powerio-json`/`json` (the canonical snapshot
/// [`pio_to_format`] writes, validated on read). PyPSA CSV folders are
/// directories, not text; parse them with [`pio_parse_file`] and
/// `from = "pypsa-csv"`. Read fidelity warnings attach to the handle
/// ([`pio_warnings`]). Returns `NULL` on error and writes the message into
/// `errbuf`. Free the handle with [`pio_network_free`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_parse_str(
    text: *const c_char,
    format: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while parsing", || {
            let text = cstr(text).ok_or_else(|| "text is NULL or not UTF-8".to_string())?;
            let format = cstr(format).ok_or_else(|| "format is NULL or not UTF-8".to_string())?;
            powerio::parse_str(text, format)
                .map(|p| (p.network, p.warnings))
                .map_err(|e| e.to_string())
        })
    }
}

/// Read one scenario of a dataset directory in the named `from` format into a
/// network handle: the directory sibling of [`pio_parse_file`]. `gridfm` (the
/// gridfm-datakit Parquet layout; `dir` resolves leniently: the `raw/` leaf,
/// a `<case>/` directory with a `raw/` child, or a parent holding exactly one
/// such case) is the one dataset format today. `scenario` selects within a
/// multi-scenario dataset ([`pio_scenario_ids`] enumerates them); formats
/// without scenarios take `0`. Read fidelity warnings attach to the handle
/// ([`pio_warnings`]). Returns `NULL` on error and writes the message into
/// `errbuf`. Free the handle with [`pio_network_free`]. Built
/// `--features gridfm`.
#[cfg(feature = "gridfm")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_read_dir(
    dir: *const c_char,
    from: *const c_char,
    scenario: i64,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while reading dataset", || {
            let dir = cstr(dir).ok_or_else(|| "dir is NULL or not UTF-8".to_string())?;
            let from = cstr(from).ok_or_else(|| "from is NULL or not UTF-8".to_string())?;
            powerio_matrix::read_dataset_dir(std::path::Path::new(dir), from, scenario)
                .map(|read| (read.network, read.warnings))
                .map_err(|e| e.to_string())
        })
    }
}

/// Write the distinct scenario ids (ascending) of the dataset directory `dir`
/// in the named `from` format into `out`, up to `cap` entries, and return the
/// total count: the cap/count convention of [`pio_bus_ids`]. `gridfm` is the
/// one dataset format today. Returns `-1` on error and writes the message into
/// `errbuf` (unlike the handle extractors, this reads the filesystem and can
/// fail). Built `--features gridfm`.
#[cfg(feature = "gridfm")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_scenario_ids(
    dir: *const c_char,
    from: *const c_char,
    out: *mut i64,
    cap: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> isize {
    unsafe {
        let r = catch_unwind(AssertUnwindSafe(|| {
            let dir = cstr(dir).ok_or_else(|| "dir is NULL or not UTF-8".to_string())?;
            let from = cstr(from).ok_or_else(|| "from is NULL or not UTF-8".to_string())?;
            powerio_matrix::dataset_scenario_ids(std::path::Path::new(dir), from)
                .map_err(|e| e.to_string())
        }));
        match r {
            Ok(Ok(ids)) => {
                let Ok(total) = isize::try_from(ids.len()) else {
                    copy_to_buf(errbuf, errlen, "scenario count exceeds isize");
                    return -1;
                };
                fill(out, cap, ids.iter().copied());
                total
            }
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                -1
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while reading scenario ids");
                -1
            }
        }
    }
}

/// The fidelity warnings attached to the handle at construction (by whichever
/// of [`pio_parse_file`], [`pio_parse_str`], [`pio_read_dir`], or
/// [`pio_normalize`] built it), `\n`-joined into `warnbuf` (truncated to fit
/// on a UTF-8 boundary; NULL/0 to skip). Returns the byte length of the full
/// joined text, excluding the NUL; call once with `(NULL, 0)` to size, then
/// pass a `char[len + 1]`. `0` means no warnings (or a NULL handle); readers
/// that are total attach none.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_warnings(
    net: *const PioNetwork,
    warnbuf: *mut c_char,
    warnlen: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            let msg = c.warnings.join("\n");
            copy_to_buf(warnbuf, warnlen, &msg);
            msg.len()
        })
    }
}

/// Free a network handle from [`pio_parse_file`], [`pio_parse_str`],
/// [`pio_read_dir`], or [`pio_normalize`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_network_free(net: *mut PioNetwork) {
    unsafe {
        // Under the same panic guard as every other entry point: the drop is
        // pure deallocation today, but "catches panics" must not depend on that
        // staying true.
        guard((), || {
            if !net.is_null() {
                drop(Box::from_raw(net));
            }
        });
    }
}

unsafe fn network_ref<'a>(net: *const PioNetwork) -> Option<&'a PioNetwork> {
    unsafe { net.as_ref() }
}

/// View `net` through its cached [`IndexCore`] with no per-call rebuild.
unsafe fn view<'a>(net: *const PioNetwork) -> Option<IndexedNetwork<'a>> {
    unsafe {
        net.as_ref()
            .map(|c| IndexedNetwork::with_core(&c.net, &c.core))
    }
}

/// Normalize `net` into a NEW network handle: per unit, radians, out-of-service
/// filtered, source bus ids preserved, bus types canonicalized (see
/// `Network::to_normalized`). A value transform, not a serialization, hence
/// the verb, while the `to_*` family re-encodes unchanged data. The result is
/// independent of `net`; free both with [`pio_network_free`]. Every extractor
/// and serializer works on it unchanged (the handle is per unit, not MW).
/// Returns `NULL` on error (no reference bus can be chosen, or a non-positive
/// base MVA) and writes the message into `errbuf`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_normalize(
    net: *const PioNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while normalizing", || {
            let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
            c.net
                .to_normalized()
                .map(|n| (n, c.warnings.clone()))
                .map_err(|e| e.to_string())
        })
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_buses(net: *const PioNetwork) -> usize {
    unsafe { guard(0, || network_ref(net).map_or(0, |c| c.net.buses.len())) }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_branches(net: *const PioNetwork) -> usize {
    unsafe { guard(0, || network_ref(net).map_or(0, |c| c.net.branches.len())) }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_switches(net: *const PioNetwork) -> usize {
    unsafe { guard(0, || network_ref(net).map_or(0, |c| c.net.switches.len())) }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_gens(net: *const PioNetwork) -> usize {
    unsafe { guard(0, || network_ref(net).map_or(0, |c| c.net.generators.len())) }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_base_mva(net: *const PioNetwork) -> f64 {
    unsafe { guard(0.0, || network_ref(net).map_or(0.0, |c| c.net.base_mva)) }
}

/// Dense `[0, n)` index of the single reference (slack) bus, or `-1` if not
/// exactly one. An INDEX into the [`pio_bus_ids`] ordering, not a bus id;
/// `pio_branches` from/to carry ids, so the unit is in the name. A network may
/// carry several references (one per island, or a normalized case that kept
/// the file's multiple `REF` buses); [`pio_ref_bus_indices`] reads them all,
/// and its count (`NULL` out) tells zero from many.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_ref_bus_index(net: *const PioNetwork) -> i64 {
    unsafe {
        guard(-1, || match view(net) {
            Some(v) => v
                .reference_bus_index()
                .map_or(-1, |i| i64::try_from(i).unwrap_or(-1)),
            None => -1,
        })
    }
}

/// Write the dense `[0, n)` indices of the reference (slack) buses, ascending,
/// into `out`, up to `cap` entries, and return the total count: the cap/count
/// convention of [`pio_bus_ids`]. `0` means none; `> 1` means one reference
/// per island or several fixed references in one island (a normalized case
/// always reports `>= 1`).
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_ref_bus_indices(
    net: *const PioNetwork,
    out: *mut i64,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            view(net).map_or(0, |v| {
                fill(
                    out,
                    cap,
                    v.reference_bus_indices()
                        .into_iter()
                        .map(|i| i64::try_from(i).unwrap_or(-1)),
                )
            })
        })
    }
}

/// Number of islands: connected components of the in-service topology.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_islands(net: *const PioNetwork) -> usize {
    unsafe { guard(0, || view(net).map_or(0, |v| v.n_connected_components())) }
}

/// `1` if the in-service topology is radial (every island a tree), else `0`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_is_radial(net: *const PioNetwork) -> i32 {
    unsafe { guard(0, || view(net).map_or(0, |v| i32::from(v.is_radial()))) }
}

/// Serialize `net` to the named format `to`: the one text serializer; every
/// format is named by a string. Accepts the [`pio_parse_str`] names:
/// `matpower` is a byte-exact echo when the handle was parsed from MATPOWER,
/// and `powerio-json` is the canonical snapshot (validated by [`pio_parse_str`]
/// on the way back; the retained source text is the one field it omits). The
/// snapshot is lossless except for a non-finite `f64` (`Inf`/`NaN`), which JSON
/// cannot represent: it is written as `null`, named in a fidelity warning, and
/// then fails to read back; pass `warnbuf` to detect it.
///
/// Returns the text as an owned C string (free with [`pio_string_free`]),
/// `NULL` on error (message into `errbuf`). Fidelity warnings, if any, are
/// written `\n`-joined into `warnbuf`; a returned string has no handle to
/// attach them to.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_to_format(
    net: *const PioNetwork,
    to: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(warnbuf, warnlen, errbuf, errlen, || {
            let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
            let target = target_format_from_c(to)?;
            let conv = c.net.to_format(target).map_err(|e| e.to_string())?;
            Ok((conv.text, conv.warnings))
        })
    }
}

/// Finish a text-conversion entry point: run `f` (producing the converted text
/// with its fidelity warnings, or an error message) under the panic guard,
/// write the warnings into `warnbuf`, and hand back the owned C string, or
/// write the error and return NULL. The shared tail of [`pio_to_format`],
/// [`pio_convert_file`], and [`pio_convert_str`], mirroring [`finish_network`].
unsafe fn finish_conversion(
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
    f: impl FnOnce() -> Result<(String, Vec<String>), String>,
) -> *mut c_char {
    unsafe {
        match catch_unwind(AssertUnwindSafe(f)) {
            Ok(Ok((text, warnings))) => {
                copy_to_buf(warnbuf, warnlen, &warnings.join("\n"));
                finish_cstring(text, errbuf, errlen)
            }
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                std::ptr::null_mut()
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while converting");
                std::ptr::null_mut()
            }
        }
    }
}

/// Convert the case file at `path` from format `from` (NULL to infer from the
/// path, as [`pio_parse_file`]) to format `to`, without keeping a handle.
/// Returns the converted text as an owned C string (free with
/// [`pio_string_free`]), `NULL` on error. Fidelity warnings, read side first,
/// are written `\n`-joined into `warnbuf`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_convert_file(
    path: *const c_char,
    from: *const c_char,
    to: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(warnbuf, warnlen, errbuf, errlen, || {
            let path = cstr(path).ok_or_else(|| "path is NULL or not UTF-8".to_string())?;
            let from = optional_cstr(from, "from")?;
            let target = target_format_from_c(to)?;
            let conv = powerio::convert_file(std::path::Path::new(path), target, from)
                .map_err(|e| e.to_string())?;
            Ok((conv.text, conv.warnings))
        })
    }
}

/// Convert in-memory case `text` from format `from` (required; there is no
/// path to infer from) to format `to`, without keeping a handle: the in-memory
/// sibling of [`pio_convert_file`]. Returns the converted text as an owned C
/// string (free with [`pio_string_free`]), `NULL` on error. Fidelity warnings,
/// read side first, are written `\n`-joined into `warnbuf`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_convert_str(
    text: *const c_char,
    from: *const c_char,
    to: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(warnbuf, warnlen, errbuf, errlen, || {
            let text = cstr(text).ok_or_else(|| "text is NULL or not UTF-8".to_string())?;
            let from = cstr(from).ok_or_else(|| "from is NULL or not UTF-8".to_string())?;
            let target = target_format_from_c(to)?;
            let conv = powerio::convert_str(text, target, from).map_err(|e| e.to_string())?;
            Ok((conv.text, conv.warnings))
        })
    }
}

/// Write `net` into the directory `out_dir` as the named directory-shaped
/// format `to`: the directory sibling of [`pio_to_format`]. PyPSA CSV
/// (`pypsa-csv`/`pypsa`) is the one such format today; a text format name is
/// an error pointing back at [`pio_to_format`]. Returns `0` on success and
/// `-1` on error (message into `errbuf`). Fidelity warnings, if any, are
/// written `\n`-joined into `warnbuf`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_write_dir(
    net: *const PioNetwork,
    to: *const c_char,
    out_dir: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> i32 {
    unsafe {
        let r = catch_unwind(AssertUnwindSafe(|| {
            let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
            let to = cstr(to).ok_or_else(|| "to is NULL or not UTF-8".to_string())?;
            let out_dir =
                cstr(out_dir).ok_or_else(|| "out_dir is NULL or not UTF-8".to_string())?;
            powerio::write_dir(&c.net, to, std::path::Path::new(out_dir)).map_err(|e| e.to_string())
        }));
        match r {
            Ok(Ok(warnings)) => {
                copy_to_buf(warnbuf, warnlen, &warnings.join("\n"));
                0
            }
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                -1
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while writing directory");
                -1
            }
        }
    }
}

/// Free a string returned by [`pio_to_format`], [`pio_convert_file`], or
/// [`pio_convert_str`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_string_free(s: *mut c_char) {
    unsafe {
        // Same rationale as `pio_network_free`: the boundary catches panics.
        guard((), || {
            if !s.is_null() {
                drop(CString::from_raw(s));
            }
        });
    }
}

/// Write up to `cap` values from `vals` into `out` and return the total number
/// available. A NULL `out` skips the write, so `(NULL, 0)` is the pure count
/// query of the cap/count convention every array extractor shares.
unsafe fn fill<T: Copy>(out: *mut T, cap: usize, vals: impl ExactSizeIterator<Item = T>) -> usize {
    unsafe {
        let total = vals.len();
        if !out.is_null() {
            for (i, v) in vals.take(cap).enumerate() {
                *out.add(i) = v;
            }
        }
        total
    }
}

/// Write the 1-based external bus ids, in dense order, into `out`, up to `cap`
/// entries, and return the total bus count. This ordering DEFINES the dense
/// index space every other per-bus array shares. Call once with `(NULL, 0)` to
/// size, allocate, then call again to fill. Ids are int64 in `1..2^63-1` (a v4
/// invariant); a source id that is a string or exceeds that range is mapped to
/// dense int64 at read, never passed through raw.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_bus_ids(net: *const PioNetwork, out: *mut i64, cap: usize) -> usize {
    unsafe {
        guard(0, || {
            network_ref(net).map_or(0, |c| {
                fill(
                    out,
                    cap,
                    c.net
                        .buses
                        .iter()
                        .map(|b| i64::try_from(b.id.0).unwrap_or(-1)),
                )
            })
        })
    }
}

/// Write the branch table as parallel arrays, each up to `cap` entries, and
/// return the total branch count. A branch is any two-terminal series element
/// lines and transformers alike (a transformer has `tap != 0`). `from`/`to`
/// are 1-based bus IDS (the [`pio_bus_ids`] id space, not dense indices); map
/// them to dense matrix rows with the [`pio_bus_ids`] ordering. Any output
/// pointer may be NULL to skip that column; all NULL is the count query.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_branches(
    net: *const PioNetwork,
    from: *mut i64,
    to: *mut i64,
    r: *mut f64,
    x: *mut f64,
    b: *mut f64,
    tap: *mut f64,
    shift: *mut f64,
    in_service: *mut u8,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            let net = &c.net;
            fill(
                from,
                cap,
                net.branches
                    .iter()
                    .map(|br| i64::try_from(br.from.0).unwrap_or(-1)),
            );
            fill(
                to,
                cap,
                net.branches
                    .iter()
                    .map(|br| i64::try_from(br.to.0).unwrap_or(-1)),
            );
            fill(r, cap, net.branches.iter().map(|br| br.r));
            fill(x, cap, net.branches.iter().map(|br| br.x));
            fill(
                b,
                cap,
                net.branches.iter().map(|br| br.legacy_total_charging_b()),
            );
            fill(tap, cap, net.branches.iter().map(|br| br.tap));
            fill(shift, cap, net.branches.iter().map(|br| br.shift));
            fill(
                in_service,
                cap,
                net.branches.iter().map(|br| u8::from(br.in_service)),
            );
            net.branches.len()
        })
    }
}

/// Write the branch terminal charging table as parallel arrays, each up to
/// `cap` entries, and return the total branch count. Columns are p.u.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_branch_charging(
    net: *const PioNetwork,
    g_fr: *mut f64,
    b_fr: *mut f64,
    g_to: *mut f64,
    b_to: *mut f64,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            let net = &c.net;
            fill(
                g_fr,
                cap,
                net.branches.iter().map(|br| br.terminal_charging().g_fr),
            );
            fill(
                b_fr,
                cap,
                net.branches.iter().map(|br| br.terminal_charging().b_fr),
            );
            fill(
                g_to,
                cap,
                net.branches.iter().map(|br| br.terminal_charging().g_to),
            );
            fill(
                b_to,
                cap,
                net.branches.iter().map(|br| br.terminal_charging().b_to),
            );
            net.branches.len()
        })
    }
}

/// Write the switch table as parallel arrays, each up to `cap` entries, and
/// return the total switch count. `from`/`to` are external bus ids.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_switches(
    net: *const PioNetwork,
    from: *mut i64,
    to: *mut i64,
    closed: *mut u8,
    thermal_rating: *mut f64,
    current_rating: *mut f64,
    pf: *mut f64,
    qf: *mut f64,
    pt: *mut f64,
    qt: *mut f64,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            let net = &c.net;
            fill(
                from,
                cap,
                net.switches
                    .iter()
                    .map(|sw| i64::try_from(sw.from.0).unwrap_or(-1)),
            );
            fill(
                to,
                cap,
                net.switches
                    .iter()
                    .map(|sw| i64::try_from(sw.to.0).unwrap_or(-1)),
            );
            fill(
                closed,
                cap,
                net.switches.iter().map(|sw| u8::from(sw.closed)),
            );
            fill(
                thermal_rating,
                cap,
                net.switches
                    .iter()
                    .map(|sw| sw.thermal_rating.unwrap_or(0.0)),
            );
            fill(
                current_rating,
                cap,
                net.switches
                    .iter()
                    .map(|sw| sw.current_rating.unwrap_or(0.0)),
            );
            fill(pf, cap, net.switches.iter().map(|sw| sw.pf.unwrap_or(0.0)));
            fill(qf, cap, net.switches.iter().map(|sw| sw.qf.unwrap_or(0.0)));
            fill(pt, cap, net.switches.iter().map(|sw| sw.pt.unwrap_or(0.0)));
            fill(qt, cap, net.switches.iter().map(|sw| sw.qt.unwrap_or(0.0)));
            net.switches.len()
        })
    }
}

/// Write the generator table as parallel arrays, each up to `cap` entries, and
/// return the total generator count. `bus` is the 1-based bus id (the
/// [`pio_bus_ids`] id space). Any output pointer may be NULL to skip.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_gens(
    net: *const PioNetwork,
    bus: *mut i64,
    pg: *mut f64,
    pmax: *mut f64,
    pmin: *mut f64,
    in_service: *mut u8,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            let net = &c.net;
            fill(
                bus,
                cap,
                net.generators
                    .iter()
                    .map(|g| i64::try_from(g.bus.0).unwrap_or(-1)),
            );
            fill(pg, cap, net.generators.iter().map(|g| g.pg));
            fill(pmax, cap, net.generators.iter().map(|g| g.pmax));
            fill(pmin, cap, net.generators.iter().map(|g| g.pmin));
            fill(
                in_service,
                cap,
                net.generators.iter().map(|g| u8::from(g.in_service)),
            );
            net.generators.len()
        })
    }
}

/// Write the per-bus demand aggregates (active `pd`, reactive `qd`, summed
/// over each bus's loads, dense [`pio_bus_ids`] order), each up to `cap`
/// entries, and return the total bus count. Either pointer may be NULL.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_bus_demand(
    net: *const PioNetwork,
    pd: *mut f64,
    qd: *mut f64,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            view(net).map_or(0, |v| {
                // Return an explicit bus count, not the last fill's result, so the
                // cap/count return is independent of which columns were requested.
                let n = fill(pd, cap, v.pd().iter().copied());
                fill(qd, cap, v.qd().iter().copied());
                n
            })
        })
    }
}

/// Write the per-bus shunt aggregates (conductance `gs`, susceptance `bs`,
/// dense [`pio_bus_ids`] order), each up to `cap` entries, and return the
/// total bus count. Either pointer may be NULL.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_bus_shunt(
    net: *const PioNetwork,
    gs: *mut f64,
    bs: *mut f64,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            view(net).map_or(0, |v| {
                // Explicit bus count, not the last fill's result (see pio_bus_demand).
                let n = fill(gs, cap, v.gs().iter().copied());
                fill(bs, cap, v.bs().iter().copied());
                n
            })
        })
    }
}

/// Export one network table over the Arrow C Data Interface: the `to_`
/// conversion whose output type is Arrow structs rather than a string, and the
/// bulk plane this ABI evolves on. Tables 0..5 are raw network tables; tables 6
/// and up are normalized solver tables with per unit/radian values and dense
/// zero based row ids. New or richer columns arrive in the Arrow schema, leaving
/// the C signatures fixed.
///
/// `table` is one of the `PIO_ARROW_TABLE_*` selectors. Raw table columns use
/// EXTERNAL bus ids (the `pio_bus_ids` id space), not the gridfm schema. On
/// success (returns `0`),
/// `out_array` and `out_schema` are populated with owned C Data Interface
/// structs: ownership of the Arrow buffers transfers to the caller, both
/// `release` callbacks are non-NULL, and the caller MUST invoke each exactly
/// once when done (skipping one leaks; the structs outlive `pio_network_free`).
/// On error (returns `-1`) the message is written into `errbuf` and the
/// out-params are left untouched. Only built with the `arrow` cargo feature.
#[cfg(feature = "arrow")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_to_arrow(
    net: *const PioNetwork,
    table: i32,
    out_array: *mut arrow::ffi::FFI_ArrowArray,
    out_schema: *mut arrow::ffi::FFI_ArrowSchema,
    errbuf: *mut c_char,
    errlen: usize,
) -> i32 {
    unsafe {
        let r = catch_unwind(AssertUnwindSafe(|| {
            if out_array.is_null() || out_schema.is_null() {
                return Err("out_array or out_schema is NULL".to_string());
            }
            let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
            arrow_export::export(&c.net, table)
        }));
        match r {
            Ok(Ok((array, schema))) => {
                // Move the FFI structs into caller memory: ptr::write does not
                // drop the (caller-zeroed) destination and does not run Drop on
                // `array`/`schema`, so the producer release callbacks transfer to
                // the caller. Exactly one owner.
                std::ptr::write(out_array, array);
                std::ptr::write(out_schema, schema);
                0
            }
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                -1
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while exporting Arrow");
                -1
            }
        }
    }
}

// ---------------------------------------------------------------------------
// Package surface (`pkg` feature). `.pio.json` compiler packages sit above the
// balanced and multiconductor handles: a package wraps exactly one payload and
// carries provenance, validation, diagnostics, and lowering history.
// ---------------------------------------------------------------------------

/// Opaque `.pio.json` compiler package handle. A package owns one
/// [`powerio_pkg::NetworkPackage`], which wraps either a balanced
/// [`PioNetwork`] payload or a multiconductor [`PioDistNetwork`] payload.
#[cfg(feature = "pkg")]
pub struct PioPackage {
    package: powerio_pkg::NetworkPackage,
}

#[cfg(feature = "pkg")]
const _: fn() = || {
    fn assert_send_sync<T: Send + Sync>() {}
    assert_send_sync::<PioPackage>();
};

#[cfg(feature = "pkg")]
fn lowering_options(base_mva: f64) -> powerio_pkg::MulticonductorToBalancedOptions {
    powerio_pkg::MulticonductorToBalancedOptions {
        base_mva,
        ..Default::default()
    }
}

#[cfg(feature = "pkg")]
unsafe fn finish_package(
    errbuf: *mut c_char,
    errlen: usize,
    panic_msg: &str,
    f: impl FnOnce() -> Result<powerio_pkg::NetworkPackage, String>,
) -> *mut PioPackage {
    unsafe {
        match catch_unwind(AssertUnwindSafe(f)) {
            Ok(Ok(package)) => Box::into_raw(Box::new(PioPackage { package })),
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                std::ptr::null_mut()
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, panic_msg);
                std::ptr::null_mut()
            }
        }
    }
}

/// Parse a `.pio.json` package file into an opaque package handle. This reads
/// only the package envelope; case format names still enter through
/// [`pio_parse_file`] / [`pio_dist_parse_file`] and package constructors.
/// Returns `NULL` on error and writes the message into `errbuf`. Free the handle
/// with [`pio_package_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_parse_file(
    path: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(errbuf, errlen, "panic while parsing package", || {
            let path = required_cstr(path, "path")?;
            let text = std::fs::read_to_string(path).map_err(|e| e.to_string())?;
            powerio_pkg::NetworkPackage::from_json(&text).map_err(|e| e.to_string())
        })
    }
}

/// Parse in-memory `.pio.json` text into an opaque package handle. Returns
/// `NULL` on error and writes the message into `errbuf`. Free the handle with
/// [`pio_package_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_parse_str(
    text: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(errbuf, errlen, "panic while parsing package", || {
            let text = required_cstr(text, "text")?;
            powerio_pkg::NetworkPackage::from_json(text).map_err(|e| e.to_string())
        })
    }
}

/// Free a package handle returned by `pio_package_*`. NULL is a no-op; free
/// exactly once.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_free(pkg: *mut PioPackage) {
    unsafe {
        guard((), || {
            if !pkg.is_null() {
                drop(Box::from_raw(pkg));
            }
        });
    }
}

/// Finish a `*mut c_char` package accessor: run `f` on the non-NULL handle
/// under the panic guard and hand back an owned C string, or write the error
/// (`panic_msg` if `f` panicked) into `errbuf` and return NULL. The shared
/// tail of the `pio_package_*_json` getters.
#[cfg(feature = "pkg")]
unsafe fn finish_package_json(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
    panic_msg: &str,
    f: impl FnOnce(&PioPackage) -> Result<String, String>,
) -> *mut c_char {
    unsafe {
        let result = catch_unwind(AssertUnwindSafe(|| {
            let pkg = pkg
                .as_ref()
                .ok_or_else(|| "package handle is NULL".to_string())?;
            f(pkg)
        }));
        match result {
            Ok(Ok(text)) => finish_cstring(text, errbuf, errlen),
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                std::ptr::null_mut()
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, panic_msg);
                std::ptr::null_mut()
            }
        }
    }
}

/// Serialize a package handle to compact `.pio.json`. Returns an owned C string
/// (free with [`pio_string_free`]) or `NULL` on error.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_to_json(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_package_json(
            pkg,
            errbuf,
            errlen,
            "panic while serializing package",
            |p| p.package.to_json().map_err(|e| e.to_string()),
        )
    }
}

/// Wrap a balanced [`PioNetwork`] handle in a `.pio.json` package. The C handle
/// name is historical; the payload is `powerio::BalancedNetwork`.
/// `include_solver_metadata != 0` attaches compact normalized solver table
/// metadata.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_from_balanced_network(
    net: *const PioNetwork,
    include_solver_metadata: i32,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(
            errbuf,
            errlen,
            "panic while packaging balanced network",
            || {
                let net = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
                let mut package = powerio_pkg::NetworkPackage::from_balanced(net.net.clone());
                if include_solver_metadata != 0 {
                    package
                        .attach_normalized_solver_table_metadata()
                        .map_err(|e| e.to_string())?;
                }
                Ok(package)
            },
        )
    }
}

/// Wrap a multiconductor [`PioDistNetwork`] handle in a `.pio.json` package. The
/// C handle name is historical; the payload is
/// `powerio_dist::MulticonductorNetwork`.
#[cfg(all(feature = "pkg", feature = "dist"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_from_multiconductor_network(
    net: *const PioDistNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(
            errbuf,
            errlen,
            "panic while packaging multiconductor network",
            || {
                let net = net
                    .as_ref()
                    .ok_or_else(|| "distribution network handle is NULL".to_string())?;
                Ok(powerio_pkg::NetworkPackage::from_multiconductor(
                    net.net.clone(),
                ))
            },
        )
    }
}

/// Run the package semantic validation profile in place. Returns `0` on
/// success, `-1` on error.
///
/// Unlike the read-only accessors, this rewrites the handle's `diagnostics` and
/// `validation` (the payload is untouched), so it takes the handle non-`const`
/// and needs exclusive access: no other call may touch the same handle
/// concurrently. This is the one exception to the header's blanket
/// concurrent-read guarantee.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_validate(
    pkg: *mut PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> i32 {
    unsafe {
        let result = catch_unwind(AssertUnwindSafe(|| {
            let pkg = pkg
                .as_mut()
                .ok_or_else(|| "package handle is NULL".to_string())?;
            pkg.package.run_sane_validation();
            Ok::<_, String>(())
        }));
        match result {
            Ok(Ok(())) => 0,
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                -1
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while validating package");
                -1
            }
        }
    }
}

/// Return the package validation summary as JSON. The returned string is owned
/// by the library; free it with [`pio_string_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_validation_json(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_package_json(
            pkg,
            errbuf,
            errlen,
            "panic while reading package validation",
            |p| serde_json::to_string(&p.package.validation).map_err(|e| e.to_string()),
        )
    }
}

/// Return the package structured diagnostics array as JSON. The returned string
/// is owned by the library; free it with [`pio_string_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_diagnostics_json(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_package_json(
            pkg,
            errbuf,
            errlen,
            "panic while reading package diagnostics",
            |p| serde_json::to_string(&p.package.diagnostics).map_err(|e| e.to_string()),
        )
    }
}

/// Return the package operating point series as JSON, or `null` when absent.
/// The returned string is owned by the library; free it with
/// [`pio_string_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_operating_points_json(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_package_json(
            pkg,
            errbuf,
            errlen,
            "panic while reading package operating points",
            |p| serde_json::to_string(&p.package.operating_points).map_err(|e| e.to_string()),
        )
    }
}

/// Materialize one operating point into a new static package.
///
/// The returned handle owns a package with the selected updates applied and no
/// operating point series. Free it with [`pio_package_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_materialize_operating_point(
    pkg: *const PioPackage,
    index: i64,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(
            errbuf,
            errlen,
            "panic while materializing package operating point",
            || {
                let pkg = pkg
                    .as_ref()
                    .ok_or_else(|| "package handle is NULL".to_string())?;
                let index = usize::try_from(index)
                    .map_err(|_| "operating point index must be non-negative".to_string())?;
                pkg.package
                    .materialize_operating_point(index)
                    .map_err(|e| e.to_string())
            },
        )
    }
}

/// Return the multiconductor-to-balanced lowering preflight report as JSON.
/// `base_mva` is the three phase system power base used for the balanced
/// per-unit projection. Returns `NULL` if the package is not multiconductor.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_multiconductor_to_balanced_preflight_json(
    pkg: *const PioPackage,
    base_mva: f64,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        let result = catch_unwind(AssertUnwindSafe(|| {
            let pkg = pkg
                .as_ref()
                .ok_or_else(|| "package handle is NULL".to_string())?;
            let net = pkg.package.as_multiconductor().ok_or_else(|| {
                format!(
                    "multiconductor preflight requires a multiconductor package, got {:?}",
                    pkg.package.model_kind()
                )
            })?;
            let report = powerio_pkg::check_multiconductor_to_balanced_lowering(
                net,
                lowering_options(base_mva),
            );
            serde_json::to_string(&report).map_err(|e| e.to_string())
        }));
        match result {
            Ok(Ok(text)) => finish_cstring(text, errbuf, errlen),
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                std::ptr::null_mut()
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while preflighting package lowering");
                std::ptr::null_mut()
            }
        }
    }
}

/// Lower a multiconductor package to a new balanced package. Call
/// [`pio_package_multiconductor_to_balanced_preflight_json`] first when the
/// caller needs structured blockers for unsupported inputs. `base_mva` is the
/// three phase system power base used for the balanced per-unit projection.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_lower_multiconductor_to_balanced(
    pkg: *const PioPackage,
    base_mva: f64,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(errbuf, errlen, "panic while lowering package", || {
            let pkg = pkg
                .as_ref()
                .ok_or_else(|| "package handle is NULL".to_string())?;
            pkg.package
                .lower_multiconductor_to_balanced(lowering_options(base_mva))
                .map_err(|e| e.to_string())
        })
    }
}

// ---------------------------------------------------------------------------
// Distribution surface (`dist` feature). The multiconductor model behind its own
// opaque `PioDistNetwork` handle and the `pio_dist_*` entry points. It is gated
// on the `dist` feature / `PIO_DIST` define, exactly like `arrow`/`gridfm`; a
// runtime consumer probes it with `pio_has_feature("dist")`, then checks
// `pio_dist_abi_version()`. The surface is EXPERIMENTAL while the IEEE BMOPF
// schema is a draft: C signature changes bump `PIO_DIST_ABI_VERSION`, and the
// JSON payloads (bmopf-json, powerio-dist-json) carry their own meta.version.
// ---------------------------------------------------------------------------

/// Finish a handle-returning dist entry point: run `f` (the handle payload or an
/// error message) under the panic guard and box the payload into an owned handle,
/// or write the error (`panic_msg` if `f` panicked) into `errbuf` and return NULL.
#[cfg(feature = "dist")]
unsafe fn finish_handle<H>(
    errbuf: *mut c_char,
    errlen: usize,
    panic_msg: &str,
    f: impl FnOnce() -> Result<H, String>,
) -> *mut H {
    unsafe {
        match catch_unwind(AssertUnwindSafe(f)) {
            Ok(Ok(h)) => Box::into_raw(Box::new(h)),
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                std::ptr::null_mut()
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, panic_msg);
                std::ptr::null_mut()
            }
        }
    }
}

/// Opaque parsed distribution network handle (the multiconductor wire-coordinate
/// model). Distinct from [`PioNetwork`] (the positive-sequence transmission
/// model); none of the `pio_n_*`/extractor functions accept it. Only built with
/// the `dist` cargo feature.
#[cfg(feature = "dist")]
pub struct PioDistNetwork {
    net: powerio_dist::DistNetwork,
}

// Same cross-thread read guarantee as `PioNetwork` (see that assertion): pin
// `Send + Sync` so a future non-`Sync` field fails the build.
#[cfg(feature = "dist")]
const _: fn() = || {
    fn assert_send_sync<T: Send + Sync>() {}
    assert_send_sync::<PioDistNetwork>();
};

/// Parse a distribution case file into a [`PioDistNetwork`] handle. The format
/// comes from `from` if non-NULL (`dss`, `pmd`, or `bmopf`), else from the file
/// itself: `.dss` is OpenDSS, and `.json` holding the ENGINEERING `data_model`
/// key is PMD JSON, otherwise BMOPF JSON. Returns `NULL` on error and writes the
/// message into `errbuf`. Free the handle with [`pio_dist_network_free`].
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_parse_file(
    path: *const c_char,
    from: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioDistNetwork {
    unsafe {
        finish_handle(errbuf, errlen, "panic while parsing", || {
            let path = required_cstr(path, "path")?;
            let from = optional_cstr(from, "from")?;
            powerio_dist::parse_file(std::path::Path::new(path), from)
                .map(|net| PioDistNetwork { net })
                .map_err(|e| e.to_string())
        })
    }
}

/// Parse in-memory distribution case `text` of the named `format` (`dss`, `pmd`,
/// or `bmopf`; required, since there is no path to infer from). An OpenDSS
/// `Redirect`/`Compile` in `text` resolves against the current working directory.
/// Returns `NULL` on error and writes the message into `errbuf`. Free the handle
/// with [`pio_dist_network_free`].
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_parse_str(
    text: *const c_char,
    format: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioDistNetwork {
    unsafe {
        finish_handle(errbuf, errlen, "panic while parsing", || {
            let text = required_cstr(text, "text")?;
            let format = required_cstr(format, "format")?;
            powerio_dist::parse_str(text, format)
                .map(|net| PioDistNetwork { net })
                .map_err(|e| e.to_string())
        })
    }
}

/// Free a distribution network handle from [`pio_dist_parse_file`] or
/// [`pio_dist_parse_str`]. NULL is a no-op; free exactly once.
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_network_free(net: *mut PioDistNetwork) {
    unsafe {
        // Same rationale as `pio_network_free`: the boundary catches panics so a
        // Drop on the `serde_json::Value` extras can't unwind across the ABI.
        guard((), || {
            if !net.is_null() {
                drop(Box::from_raw(net));
            }
        });
    }
}

/// Parse warnings retained on the handle (everything the reader could not
/// represent or had to assume), `\n`-joined and written into the caller `warnbuf`
/// (truncated to fit, always NUL-terminated). Returns the total byte length of
/// the joined message; call with `NULL`/0 to size first, then fill — the same
/// idiom as [`pio_warnings`]. Returns 0 for a NULL handle.
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_warnings(
    net: *const PioDistNetwork,
    warnbuf: *mut c_char,
    warnlen: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = net.as_ref() else { return 0 };
            let msg = c.net.warnings.join("\n");
            copy_to_buf(warnbuf, warnlen, &msg);
            msg.len()
        })
    }
}

/// Serialize `net` to distribution format `to` (`dss`, `pmd`, or `bmopf`).
/// Writing back to the format the handle was parsed from echoes the source text
/// byte for byte; a cross-format write reports every fidelity loss in `warnbuf`
/// (`\n`-joined). Returns the text as an owned C string (free with
/// [`pio_string_free`]), `NULL` on error.
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_to_format(
    net: *const PioDistNetwork,
    to: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(warnbuf, warnlen, errbuf, errlen, || {
            let c = net
                .as_ref()
                .ok_or_else(|| "network handle is NULL".to_string())?;
            let target = dist_target_from_c(to)?;
            let conv = c.net.to_format(target);
            Ok((conv.text, conv.warnings))
        })
    }
}

/// Convert distribution case `path` from optional source format `from` to format
/// `to`; see [`pio_dist_parse_file`] for the inference rules. Returns the
/// converted text as an owned C string (free with [`pio_string_free`]), `NULL` on
/// error. The warnings written `\n`-joined into `warnbuf` carry both the parse
/// warnings and the writer's fidelity losses (there is no handle to query them).
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_convert_file(
    path: *const c_char,
    from: *const c_char,
    to: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(warnbuf, warnlen, errbuf, errlen, || {
            let path = required_cstr(path, "path")?;
            let from = optional_cstr(from, "from")?;
            let to = dist_target_from_c(to)?;
            let conv = powerio_dist::convert_file(std::path::Path::new(path), to, from)
                .map_err(|e| e.to_string())?;
            Ok((conv.text, conv.warnings))
        })
    }
}

/// Convert in-memory distribution case `text` of format `from` to format `to`
/// (both required; `dss`, `pmd`, or `bmopf`). The parameter order is input,
/// source, target, matching [`pio_dist_convert_file`]. Returns the converted text
/// as an owned C string (free with [`pio_string_free`]), `NULL` on error. The
/// warnings written `\n`-joined into `warnbuf` carry both the parse warnings and
/// the writer's fidelity losses (there is no handle to query them).
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_convert_str(
    text: *const c_char,
    from: *const c_char,
    to: *const c_char,
    warnbuf: *mut c_char,
    warnlen: usize,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(warnbuf, warnlen, errbuf, errlen, || {
            let text = required_cstr(text, "text")?;
            let to = dist_target_from_c(to)?;
            let from = required_cstr(from, "from")?;
            let conv = powerio_dist::convert_str(text, to, from).map_err(|e| e.to_string())?;
            Ok((conv.text, conv.warnings))
        })
    }
}

#[cfg(feature = "dist")]
fn dist_target_from_c(to: *const c_char) -> Result<powerio_dist::DistTargetFormat, String> {
    let to = required_cstr(to, "to")?;
    // The message comes from the real error so it can't drift from what the
    // powerio-dist dispatchers report for the same mistake.
    to.parse::<powerio_dist::DistTargetFormat>()
        .map_err(|e| e.to_string())
}

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

    fn data_path(name: &str) -> CString {
        CString::new(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
                .join("../tests/data")
                .join(name)
                .to_str()
                .unwrap(),
        )
        .unwrap()
    }

    fn close(actual: f64, expected: f64) {
        assert!((actual - expected).abs() < 1e-12, "{actual} != {expected}");
    }

    fn case9() -> *mut PioNetwork {
        let path = data_path("case9.m");
        let mut err = [0 as c_char; 256];
        let c =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(!c.is_null(), "parse returned null");
        c
    }

    fn terminal_projection_case() -> *mut PioNetwork {
        use powerio::{Branch, BranchCharging, Bus, BusId, BusType};

        let mut branch = Branch::new(BusId(1), BusId(2), 0.01, 0.1);
        branch.charging = Some(BranchCharging::new(0.01, 0.02, 0.03, 0.05));
        branch.rate_a = 100.0;
        let net = Network::in_memory(
            "terminal-projection",
            100.0,
            vec![
                Bus::new(BusId(1), BusType::Ref, 230.0),
                Bus::new(BusId(2), BusType::Pq, 230.0),
            ],
            vec![branch],
        );
        let text = CString::new(net.to_json().unwrap()).unwrap();
        let format = CString::new("powerio-json").unwrap();
        let mut err = [0 as c_char; 256];
        let c =
            unsafe { pio_parse_str(text.as_ptr(), format.as_ptr(), err.as_mut_ptr(), err.len()) };
        assert!(
            !c.is_null(),
            "parse returned null: {}",
            unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
        );
        c
    }

    /// `pio_to_format` with a Rust-side format name, asserting success.
    unsafe fn to_format(net: *const PioNetwork, to: &str) -> String {
        let to = CString::new(to).unwrap();
        let mut warn = [0 as c_char; 512];
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_to_format(
                net,
                to.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                !s.is_null(),
                "to_format failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let text = CStr::from_ptr(s).to_str().unwrap().to_owned();
            pio_string_free(s);
            text
        }
    }

    #[cfg(feature = "pkg")]
    unsafe fn package_json_text(pkg: *const PioPackage) -> String {
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let s = pio_package_to_json(pkg, err.as_mut_ptr(), err.len());
            assert!(
                !s.is_null(),
                "package to json failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let text = CStr::from_ptr(s).to_str().unwrap().to_owned();
            pio_string_free(s);
            text
        }
    }

    #[cfg(feature = "pkg")]
    unsafe fn package_json(pkg: *const PioPackage) -> serde_json::Value {
        unsafe { serde_json::from_str(&package_json_text(pkg)).unwrap() }
    }

    #[cfg(feature = "pkg")]
    unsafe fn package_report_json(
        f: unsafe extern "C" fn(*const PioPackage, *mut c_char, usize) -> *mut c_char,
        pkg: *const PioPackage,
    ) -> serde_json::Value {
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let s = f(pkg, err.as_mut_ptr(), err.len());
            assert!(
                !s.is_null(),
                "package report failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let text = CStr::from_ptr(s).to_str().unwrap().to_owned();
            pio_string_free(s);
            serde_json::from_str(&text).unwrap()
        }
    }

    #[test]
    fn version_surface() {
        // The ABI version is the load-time compatibility check; the version
        // string is static, NUL-terminated, and non-empty.
        assert_eq!(pio_abi_version(), PIO_ABI_VERSION);
        assert_eq!(PIO_ABI_VERSION, 4);
        let v = unsafe { CStr::from_ptr(pio_version()) }.to_str().unwrap();
        assert_eq!(v, env!("CARGO_PKG_VERSION"));
        assert!(!v.is_empty());
    }

    fn strip_c_comments(input: &str) -> String {
        let mut out = String::with_capacity(input.len());
        let mut chars = input.chars().peekable();
        let mut in_block = false;
        while let Some(ch) = chars.next() {
            if in_block {
                if ch == '*' && chars.peek() == Some(&'/') {
                    chars.next();
                    in_block = false;
                } else if ch == '\n' {
                    out.push('\n');
                }
            } else if ch == '/' && chars.peek() == Some(&'*') {
                chars.next();
                in_block = true;
            } else if ch == '/' && chars.peek() == Some(&'/') {
                chars.next();
                for tail in chars.by_ref() {
                    if tail == '\n' {
                        out.push('\n');
                        break;
                    }
                }
            } else {
                out.push(ch);
            }
        }
        out
    }

    fn collapse_ws(s: &str) -> String {
        s.split_whitespace().collect::<Vec<_>>().join(" ")
    }

    fn c_header_abi_manifest(header: &str) -> Vec<String> {
        let clean = strip_c_comments(header);
        let mut entries = Vec::new();
        let mut prototype = String::new();
        for line in clean.lines().map(str::trim).filter(|line| !line.is_empty()) {
            if !prototype.is_empty() {
                prototype.push(' ');
                prototype.push_str(line);
                if line.ends_with(';') {
                    entries.push(collapse_ws(&prototype));
                    prototype.clear();
                }
                continue;
            }

            if line.starts_with("#define PIO_") || line.starts_with("typedef struct Pio") {
                entries.push(collapse_ws(line));
            } else if line.contains("pio_") {
                if line.ends_with(';') {
                    entries.push(collapse_ws(line));
                } else {
                    prototype.push_str(line);
                }
            }
        }
        assert!(prototype.is_empty(), "unterminated prototype: {prototype}");
        entries
    }

    fn pio_symbol_names_from_manifest(manifest: &[String]) -> Vec<String> {
        let mut names = std::collections::BTreeSet::new();
        for entry in manifest {
            if let Some(start) = entry.find("pio_") {
                let tail = &entry[start..];
                if let Some(end) = tail.find('(') {
                    names.insert(tail[..end].to_string());
                }
            }
        }
        names.into_iter().collect()
    }

    fn source_exported_pio_symbols(source: &str) -> Vec<String> {
        let mut names = std::collections::BTreeSet::new();
        let mut saw_no_mangle = false;
        for line in source.lines() {
            let trimmed = line.trim();
            if trimmed == "#[unsafe(no_mangle)]" {
                saw_no_mangle = true;
                continue;
            }
            if !trimmed.contains("extern \"C\"") {
                if !trimmed.is_empty()
                    && !trimmed.starts_with("#[")
                    && !trimmed.starts_with("//")
                    && !trimmed.starts_with("///")
                {
                    saw_no_mangle = false;
                }
                continue;
            }
            if let Some(start) = trimmed.find("fn pio_") {
                let tail = &trimmed[start + "fn ".len()..];
                let end = tail
                    .find('(')
                    .unwrap_or_else(|| panic!("unterminated extern fn line: {trimmed}"));
                let name = &tail[..end];
                assert!(
                    saw_no_mangle,
                    "{name} is exported in Rust source without #[unsafe(no_mangle)]"
                );
                names.insert(name.to_string());
                saw_no_mangle = false;
                continue;
            }
            if !trimmed.is_empty() && !trimmed.starts_with("#[") && !trimmed.starts_with("//") {
                saw_no_mangle = false;
            }
        }
        names.into_iter().collect()
    }

    #[test]
    fn c_header_abi_manifest_is_pinned() {
        let actual = c_header_abi_manifest(include_str!("../include/powerio.h"));
        let expected = [
            "#define PIO_ABI_VERSION 4",
            "#define PIO_DIST_ABI_VERSION 1",
            "#define PIO_ERRBUF_MIN 256",
            "#define PIO_ARROW_TABLE_BUS 0",
            "#define PIO_ARROW_TABLE_BRANCH 1",
            "#define PIO_ARROW_TABLE_GEN 2",
            "#define PIO_ARROW_TABLE_LOAD 3",
            "#define PIO_ARROW_TABLE_SHUNT 4",
            "#define PIO_ARROW_TABLE_SWITCH 5",
            "#define PIO_ARROW_TABLE_SOLVER_BUS 6",
            "#define PIO_ARROW_TABLE_SOLVER_LOAD 7",
            "#define PIO_ARROW_TABLE_SOLVER_SHUNT 8",
            "#define PIO_ARROW_TABLE_SOLVER_BRANCH 9",
            "#define PIO_ARROW_TABLE_SOLVER_SWITCH 10",
            "#define PIO_ARROW_TABLE_SOLVER_ARC 11",
            "#define PIO_ARROW_TABLE_SOLVER_GEN 12",
            "#define PIO_ARROW_TABLE_SOLVER_STORAGE 13",
            "#define PIO_ARROW_TABLE_SOLVER_HVDC 14",
            "typedef struct PioDistNetwork PioDistNetwork;",
            "typedef struct PioNetwork PioNetwork;",
            "typedef struct PioPackage PioPackage;",
            "uint32_t pio_abi_version(void);",
            "uint32_t pio_dist_abi_version(void);",
            "int32_t pio_has_feature(const char *feature);",
            "const char *pio_version(void);",
            "PioNetwork *pio_parse_file(const char *path, const char *from, char *errbuf, size_t errlen);",
            "PioNetwork *pio_parse_str(const char *text, const char *format, char *errbuf, size_t errlen);",
            "PioNetwork *pio_read_dir(const char *dir, const char *from, int64_t scenario, char *errbuf, size_t errlen);",
            "ptrdiff_t pio_scenario_ids(const char *dir, const char *from, int64_t *out, size_t cap, char *errbuf, size_t errlen);",
            "size_t pio_warnings(const PioNetwork *net, char *warnbuf, size_t warnlen);",
            "void pio_network_free(PioNetwork *net);",
            "PioNetwork *pio_normalize(const PioNetwork *net, char *errbuf, size_t errlen);",
            "size_t pio_n_buses(const PioNetwork *net);",
            "size_t pio_n_branches(const PioNetwork *net);",
            "size_t pio_n_switches(const PioNetwork *net);",
            "size_t pio_n_gens(const PioNetwork *net);",
            "double pio_base_mva(const PioNetwork *net);",
            "int64_t pio_ref_bus_index(const PioNetwork *net);",
            "size_t pio_ref_bus_indices(const PioNetwork *net, int64_t *out, size_t cap);",
            "size_t pio_n_islands(const PioNetwork *net);",
            "int32_t pio_is_radial(const PioNetwork *net);",
            "char *pio_to_format(const PioNetwork *net, const char *to, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
            "char *pio_convert_file(const char *path, const char *from, const char *to, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
            "char *pio_convert_str(const char *text, const char *from, const char *to, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
            "int32_t pio_write_dir(const PioNetwork *net, const char *to, const char *out_dir, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
            "void pio_string_free(char *s);",
            "size_t pio_bus_ids(const PioNetwork *net, int64_t *out, size_t cap);",
            "size_t pio_branches(const PioNetwork *net, int64_t *from, int64_t *to, double *r, double *x, double *b, double *tap, double *shift, uint8_t *in_service, size_t cap);",
            "size_t pio_branch_charging(const PioNetwork *net, double *g_fr, double *b_fr, double *g_to, double *b_to, size_t cap);",
            "size_t pio_switches(const PioNetwork *net, int64_t *from, int64_t *to, uint8_t *closed, double *thermal_rating, double *current_rating, double *pf, double *qf, double *pt, double *qt, size_t cap);",
            "size_t pio_gens(const PioNetwork *net, int64_t *bus, double *pg, double *pmax, double *pmin, uint8_t *in_service, size_t cap);",
            "size_t pio_bus_demand(const PioNetwork *net, double *pd, double *qd, size_t cap);",
            "size_t pio_bus_shunt(const PioNetwork *net, double *gs, double *bs, size_t cap);",
            "int32_t pio_to_arrow(const PioNetwork *net, int32_t table, struct ArrowArray *out_array, struct ArrowSchema *out_schema, char *errbuf, size_t errlen);",
            "PioPackage *pio_package_parse_file(const char *path, char *errbuf, size_t errlen);",
            "PioPackage *pio_package_parse_str(const char *text, char *errbuf, size_t errlen);",
            "void pio_package_free(PioPackage *pkg);",
            "char *pio_package_to_json(const PioPackage *pkg, char *errbuf, size_t errlen);",
            "PioPackage *pio_package_from_balanced_network(const PioNetwork *net, int32_t include_solver_metadata, char *errbuf, size_t errlen);",
            "PioPackage *pio_package_from_multiconductor_network(const PioDistNetwork *net, char *errbuf, size_t errlen);",
            "int32_t pio_package_validate(PioPackage *pkg, char *errbuf, size_t errlen);",
            "char *pio_package_validation_json(const PioPackage *pkg, char *errbuf, size_t errlen);",
            "char *pio_package_diagnostics_json(const PioPackage *pkg, char *errbuf, size_t errlen);",
            "char *pio_package_operating_points_json(const PioPackage *pkg, char *errbuf, size_t errlen);",
            "PioPackage *pio_package_materialize_operating_point(const PioPackage *pkg, int64_t index, char *errbuf, size_t errlen);",
            "char *pio_package_multiconductor_to_balanced_preflight_json(const PioPackage *pkg, double base_mva, char *errbuf, size_t errlen);",
            "PioPackage *pio_package_lower_multiconductor_to_balanced(const PioPackage *pkg, double base_mva, char *errbuf, size_t errlen);",
            "PioDistNetwork *pio_dist_parse_file(const char *path, const char *from, char *errbuf, size_t errlen);",
            "PioDistNetwork *pio_dist_parse_str(const char *text, const char *format, char *errbuf, size_t errlen);",
            "void pio_dist_network_free(PioDistNetwork *net);",
            "size_t pio_dist_warnings(const PioDistNetwork *net, char *warnbuf, size_t warnlen);",
            "char *pio_dist_to_format(const PioDistNetwork *net, const char *to, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
            "char *pio_dist_convert_file(const char *path, const char *from, const char *to, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
            "char *pio_dist_convert_str(const char *text, const char *from, const char *to, char *warnbuf, size_t warnlen, char *errbuf, size_t errlen);",
        ]
        .into_iter()
        .map(str::to_string)
        .collect::<Vec<_>>();
        assert_eq!(actual, expected);
    }

    #[test]
    fn c_header_and_rust_exported_symbols_match() {
        let manifest = c_header_abi_manifest(include_str!("../include/powerio.h"));
        let header_symbols = pio_symbol_names_from_manifest(&manifest);
        let rust_symbols = source_exported_pio_symbols(include_str!("lib.rs"));
        assert_eq!(rust_symbols, header_symbols);
    }

    #[test]
    fn parse_query_free() {
        let c = case9();
        unsafe {
            assert_eq!(pio_n_buses(c), 9);
            assert_eq!(pio_n_branches(c), 9);
            assert_eq!(pio_n_gens(c), 3);
            assert_eq!(pio_base_mva(c), 100.0);
            assert_eq!(pio_n_islands(c), 1);
            assert!(pio_ref_bus_index(c) >= 0);
            // The MATPOWER reader is total: no warnings, zero bytes.
            assert_eq!(pio_warnings(c, std::ptr::null_mut(), 0), 0);
            pio_network_free(c);
        }
    }

    #[test]
    fn warnings_size_then_fill_exactly() {
        // The pandapower fixture carries switches the model ignores. The byte
        // length returned by the NULL-out call must size a buffer that then
        // receives the full text untruncated.
        let path = data_path("pandapower/example.json");
        let mut err = [0 as c_char; 256];
        let c =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(
            !c.is_null(),
            "parse failed: {}",
            unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
        );
        unsafe {
            let len = pio_warnings(c, std::ptr::null_mut(), 0);
            assert!(len > 0, "expected read warnings");
            let mut warn = vec![0x7f as c_char; len + 1];
            assert_eq!(pio_warnings(c, warn.as_mut_ptr(), warn.len()), len);
            let w = CStr::from_ptr(warn.as_ptr()).to_str().unwrap();
            assert_eq!(w.len(), len, "buffer sized from the return holds it all");
            assert!(w.contains("switch"), "expected a switch warning, got {w:?}");
            // A NULL handle reports zero bytes.
            assert_eq!(
                pio_warnings(std::ptr::null(), warn.as_mut_ptr(), warn.len()),
                0
            );
            pio_network_free(c);
        }
    }

    #[test]
    fn matpower_write_is_byte_exact() {
        let src = std::fs::read_to_string(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../tests/data/case9.m"),
        )
        .unwrap();
        let c = case9();
        unsafe {
            assert_eq!(to_format(c, "matpower"), src);

            // A NULL handle is an error message, not a crash.
            let to = CString::new("matpower").unwrap();
            let mut err = [0 as c_char; 256];
            let null = pio_to_format(
                std::ptr::null(),
                to.as_ptr(),
                std::ptr::null_mut(),
                0,
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(null.is_null());
            assert_eq!(
                CStr::from_ptr(err.as_ptr()).to_str().unwrap(),
                "network handle is NULL"
            );
            pio_network_free(c);
        }
    }

    #[test]
    fn extract_branch_tables() {
        let c = case9();
        unsafe {
            // All-NULL is the count query.
            let nb = pio_branches(
                c,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                0,
            );
            assert_eq!(nb, pio_n_branches(c));
            let mut from = vec![0i64; nb];
            let mut x = vec![0f64; nb];
            let total = pio_branches(
                c,
                from.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                x.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                nb,
            );
            assert_eq!(total, nb);
            // `from` carries the 1-based bus ids (case9 buses are 1..=9), the
            // same id space as pio_bus_ids, not dense indices.
            assert!(from.iter().all(|&f| f >= 1));
            assert!(x.iter().all(|&xx| xx > 0.0));
            pio_network_free(c);
        }
    }

    #[test]
    fn branch_tables_project_terminal_charging_to_legacy_b() {
        let c = terminal_projection_case();
        unsafe {
            let mut b = [0.0];
            let nb = pio_branches(
                c,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                b.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                1,
            );
            assert_eq!(nb, 1);
            close(b[0], 0.07);

            let mut g_fr = [0.0];
            let mut b_fr = [0.0];
            let mut g_to = [0.0];
            let mut b_to = [0.0];
            let nb = pio_branch_charging(
                c,
                g_fr.as_mut_ptr(),
                b_fr.as_mut_ptr(),
                g_to.as_mut_ptr(),
                b_to.as_mut_ptr(),
                1,
            );
            assert_eq!(nb, 1);
            close(g_fr[0], 0.01);
            close(b_fr[0], 0.02);
            close(g_to[0], 0.03);
            close(b_to[0], 0.05);
            pio_network_free(c);
        }
    }

    #[test]
    fn cap_clamps_the_write_and_returns_the_total() {
        let c = case9();
        unsafe {
            let total = pio_bus_ids(c, std::ptr::null_mut(), 0);
            assert_eq!(total, 9);
            // A two-slot buffer gets exactly two ids; the total still comes back,
            // so a short read is detectable.
            let mut ids = [-1i64; 2];
            assert_eq!(pio_bus_ids(c, ids.as_mut_ptr(), ids.len()), 9);
            assert!(ids.iter().all(|&id| id >= 1));
            pio_network_free(c);
        }
    }

    #[test]
    fn convert_matpower_echo() {
        let path = data_path("case14.m");
        let to = CString::new("matpower").unwrap();
        let mut warn = [0 as c_char; 256];
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_convert_file(
                path.as_ptr(),
                std::ptr::null(),
                to.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(!s.is_null());
            let got = CStr::from_ptr(s).to_str().unwrap();
            let src = std::fs::read_to_string(
                std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../tests/data/case14.m"),
            )
            .unwrap();
            assert_eq!(got, src);
            pio_string_free(s);
        }
    }

    #[test]
    fn convert_file_rejects_target_before_source_order() {
        let path = data_path("case14.m");
        let old_target = CString::new("powermodels-json").unwrap();
        let old_source = CString::new("matpower").unwrap();
        let mut warn = [0 as c_char; 512];
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let s = pio_convert_file(
                path.as_ptr(),
                old_target.as_ptr(),
                old_source.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                s.is_null(),
                "legacy target-before-source order unexpectedly succeeded"
            );
            let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(!msg.is_empty(), "expected an explanatory parse error");
        }
    }

    #[test]
    fn convert_str_round_trips_in_memory() {
        // The in-memory converter is parse_str + to_format fused: matpower in,
        // powermodels out, no filesystem.
        let src = std::fs::read_to_string(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../tests/data/case9.m"),
        )
        .unwrap();
        let text = CString::new(src).unwrap();
        let from = CString::new("matpower").unwrap();
        let to = CString::new("powermodels-json").unwrap();
        let mut warn = [0 as c_char; 512];
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_convert_str(
                text.as_ptr(),
                from.as_ptr(),
                to.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                !s.is_null(),
                "convert_str failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let out = CStr::from_ptr(s).to_str().unwrap();
            assert!(out.contains("\"bus\""));
            pio_string_free(s);
        }
    }

    #[test]
    fn convert_str_rejects_target_before_source_order() {
        let src = std::fs::read_to_string(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../tests/data/case9.m"),
        )
        .unwrap();
        let text = CString::new(src).unwrap();
        let old_target = CString::new("powermodels-json").unwrap();
        let old_source = CString::new("matpower").unwrap();
        let mut warn = [0 as c_char; 512];
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let s = pio_convert_str(
                text.as_ptr(),
                old_target.as_ptr(),
                old_source.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                s.is_null(),
                "legacy target-before-source order unexpectedly succeeded"
            );
            let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(!msg.is_empty(), "expected an explanatory parse error");
        }
    }

    #[test]
    fn to_format_converts_live_handle() {
        let c = case9();
        unsafe {
            let text = to_format(c, "powermodels-json");
            assert!(text.contains("\"bus\""));
            pio_network_free(c);
        }
    }

    #[test]
    fn parse_error_sets_message_not_null_handle() {
        let path = CString::new("/no/such/case.m").unwrap();
        let mut err = [0 as c_char; 256];
        let c =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(c.is_null());
        let msg = unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap();
        assert!(!msg.is_empty(), "expected an error message");
    }

    #[test]
    fn non_utf8_from_hint_errors_instead_of_falling_back() {
        let path = data_path("case9.m");
        let to = CString::new("matpower").unwrap();
        let bad_from = [0xff_u8, 0];
        let mut err = [0 as c_char; 256];
        let c = unsafe {
            pio_parse_file(
                path.as_ptr(),
                bad_from.as_ptr().cast::<c_char>(),
                err.as_mut_ptr(),
                err.len(),
            )
        };
        assert!(c.is_null());
        assert_eq!(
            unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap(),
            "from is not UTF-8"
        );

        let mut warn = [0 as c_char; 256];
        err.fill(0);
        let s = unsafe {
            pio_convert_file(
                path.as_ptr(),
                bad_from.as_ptr().cast::<c_char>(),
                to.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            )
        };
        assert!(s.is_null());
        assert_eq!(
            unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap(),
            "from is not UTF-8"
        );
    }

    #[test]
    fn extract_gen_and_bus_aggregate_tables() {
        // case30 carries generators, loads, and shunts: cross-check the table
        // extractors against known counts and aggregate signs (a column swap in
        // pio_gens/pio_bus_* would otherwise ship silently).
        let path = data_path("case30.m");
        let mut err = [0 as c_char; 256];
        let c =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(!c.is_null());
        unsafe {
            let nb = pio_n_buses(c);
            let ng = pio_n_gens(c);
            assert_eq!(nb, 30);
            assert!(ng > 0);

            let mut gbus = vec![-9i64; ng];
            let mut pmax = vec![0f64; ng];
            let total = pio_gens(
                c,
                gbus.as_mut_ptr(),
                std::ptr::null_mut(),
                pmax.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                ng,
            );
            assert_eq!(total, ng);
            // Generator buses are 1-based ids within the case's id range.
            assert!(gbus.iter().all(|&b| (1..=nb as i64).contains(&b)));
            assert!(pmax.iter().any(|&p| p > 0.0));

            let mut ids = vec![0i64; nb];
            assert_eq!(pio_bus_ids(c, ids.as_mut_ptr(), nb), nb);
            assert!(ids.iter().all(|&id| id >= 1)); // MATPOWER bus ids are 1-based

            let mut pd = vec![0f64; nb];
            let mut qd = vec![0f64; nb];
            assert_eq!(pio_bus_demand(c, pd.as_mut_ptr(), qd.as_mut_ptr(), nb), nb);
            assert!(pd.iter().sum::<f64>() > 0.0, "case30 has active demand");

            let mut gs = vec![0f64; nb];
            let mut bs = vec![0f64; nb];
            assert_eq!(pio_bus_shunt(c, gs.as_mut_ptr(), bs.as_mut_ptr(), nb), nb);
            assert!(gs.iter().chain(bs.iter()).all(|x| x.is_finite()));

            pio_network_free(c);
        }
    }

    #[test]
    fn null_handle_and_null_out_are_safe() {
        // Every query tolerates a NULL handle (the documented safe default), and
        // a NULL output pointer on a valid case is a count query, not a deref.
        unsafe {
            let nil: *const PioNetwork = std::ptr::null();
            assert_eq!(pio_n_buses(nil), 0);
            assert_eq!(pio_n_branches(nil), 0);
            assert_eq!(pio_n_gens(nil), 0);
            assert_eq!(pio_base_mva(nil), 0.0);
            assert_eq!(pio_ref_bus_index(nil), -1);
            assert_eq!(pio_ref_bus_indices(nil, std::ptr::null_mut(), 0), 0);
            assert_eq!(pio_is_radial(nil), 0);
            assert_eq!(pio_n_islands(nil), 0);

            // The two FFI constructors reject a NULL input rather than crash.
            let mut err = [0 as c_char; 128];
            assert!(pio_normalize(nil, err.as_mut_ptr(), err.len()).is_null());
            let fmt = CString::new("matpower").unwrap();
            assert!(
                pio_parse_str(std::ptr::null(), fmt.as_ptr(), err.as_mut_ptr(), err.len())
                    .is_null()
            );

            let c = case9();
            assert_eq!(pio_bus_ids(c, std::ptr::null_mut(), 0), 9);
            pio_ref_bus_indices(c, std::ptr::null_mut(), 0);
            pio_bus_demand(c, std::ptr::null_mut(), std::ptr::null_mut(), 0);
            pio_gens(
                c,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                0,
            );
            pio_network_free(c);
        }
    }

    #[test]
    fn normalized_multi_ref_is_legible() {
        // A two-slack case (both gen-backed file REF buses) normalizes to a
        // handle that keeps both references. `pio_ref_bus_index` can't name a
        // single slack (returns -1), but the reference-set extractor does, so a
        // C consumer can tell "two slacks, you pick" from "no slack, broken".
        let src = "\
function mpc = tworef
mpc.version = '2';
mpc.baseMVA = 100;
mpc.bus = [
\t1\t3\t0\t0\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
\t2\t3\t0\t0\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
\t3\t1\t50\t10\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
];
mpc.gen = [
\t1\t0\t0\t100\t-100\t1\t100\t1\t100\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0;
\t2\t0\t0\t100\t-100\t1\t100\t1\t300\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0;
];
mpc.branch = [
\t1\t2\t0.01\t0.1\t0\t0\t0\t0\t0\t0\t1\t-360\t360;
\t2\t3\t0.01\t0.1\t0\t0\t0\t0\t0\t0\t1\t-360\t360;
];
";
        let text = CString::new(src).unwrap();
        let fmt = CString::new("matpower").unwrap();
        let mut err = [0 as c_char; 256];
        unsafe {
            let cs = pio_parse_str(text.as_ptr(), fmt.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(!cs.is_null(), "parse_str returned null");
            let cn = pio_normalize(cs, err.as_mut_ptr(), err.len());
            assert!(!cn.is_null(), "normalize returned null");

            // Count via NULL out, then fill.
            assert_eq!(pio_ref_bus_indices(cn, std::ptr::null_mut(), 0), 2);
            // Multiple references: the single-slack query reports -1, by design.
            assert_eq!(pio_ref_bus_index(cn), -1);
            let mut refs = [-1i64; 2];
            assert_eq!(pio_ref_bus_indices(cn, refs.as_mut_ptr(), refs.len()), 2);
            assert_eq!(refs, [0, 1]);

            pio_network_free(cn);
            pio_network_free(cs);
        }
    }

    #[test]
    fn normalized_preserves_source_bus_ids() {
        let src = "\
function mpc = sparseids
mpc.version = '2';
mpc.baseMVA = 100;
mpc.bus = [
\t1\t3\t0\t0\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
\t2\t1\t0\t0\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
\t3\t1\t0\t0\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
\t4\t1\t0\t0\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
\t10\t1\t50\t10\t0\t0\t1\t1\t0\t230\t1\t1.1\t0.9;
];
mpc.gen = [
\t1\t0\t0\t100\t-100\t1\t100\t1\t200\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0;
];
mpc.branch = [
\t1\t2\t0.01\t0.1\t0\t0\t0\t0\t0\t0\t1\t-360\t360;
\t2\t3\t0.01\t0.1\t0\t0\t0\t0\t0\t0\t1\t-360\t360;
\t3\t4\t0.01\t0.1\t0\t0\t0\t0\t0\t0\t1\t-360\t360;
\t4\t10\t0.01\t0.1\t0\t0\t0\t0\t0\t0\t1\t-360\t360;
];
";
        let text = CString::new(src).unwrap();
        let fmt = CString::new("matpower").unwrap();
        let mut err = [0 as c_char; 256];
        unsafe {
            let cs = pio_parse_str(text.as_ptr(), fmt.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(!cs.is_null(), "parse_str returned null");
            let cn = pio_normalize(cs, err.as_mut_ptr(), err.len());
            assert!(!cn.is_null(), "normalize returned null");

            let mut ids = vec![0i64; pio_n_buses(cn)];
            pio_bus_ids(cn, ids.as_mut_ptr(), ids.len());
            assert_eq!(ids, vec![1, 2, 3, 4, 10]);

            let mut from = vec![0i64; pio_n_branches(cn)];
            let mut to = vec![0i64; pio_n_branches(cn)];
            pio_branches(
                cn,
                from.as_mut_ptr(),
                to.as_mut_ptr(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                from.len(),
            );
            assert_eq!((from[3], to[3]), (4, 10));

            pio_network_free(cn);
            pio_network_free(cs);
        }
    }

    #[test]
    fn convert_emits_warning_into_buffer() {
        // t_case9_dcline carries an HVDC dcline. PSS/E writes it as two-terminal DC
        // but defaults the converter detail; that fidelity note must reach the
        // caller's warning buffer, not vanish.
        let path = data_path("t_case9_dcline.m");
        let to = CString::new("psse").unwrap();
        let mut warn = [0 as c_char; 512];
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_convert_file(
                path.as_ptr(),
                std::ptr::null(),
                to.as_ptr(),
                warn.as_mut_ptr(),
                warn.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(!s.is_null());
            let w = CStr::from_ptr(warn.as_ptr()).to_str().unwrap();
            assert!(
                w.contains("converter detail"),
                "expected an HVDC converter-detail warning, got {w:?}"
            );
            pio_string_free(s);
        }
    }

    #[test]
    fn snapshot_round_trip_preserves_structure() {
        // to_format("powerio-json") -> parse_str("powerio-json") must reproduce
        // the structured tables. case30 carries loads, shunts, and gen costs,
        // so a dropped field shows up.
        let path = data_path("case30.m");
        let mut err = [0 as c_char; 256];
        let c =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(!c.is_null());
        unsafe {
            let json = to_format(c, "powerio-json");
            assert!(json.contains("\"buses\""));

            let text = CString::new(json).unwrap();
            let fmt = CString::new("powerio-json").unwrap();
            let back = pio_parse_str(text.as_ptr(), fmt.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(
                !back.is_null(),
                "snapshot parse failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            // The snapshot is lossless: no fidelity warnings on the way back.
            assert_eq!(pio_warnings(back, std::ptr::null_mut(), 0), 0);
            // Counts and base survive the round trip.
            assert_eq!(pio_n_buses(back), pio_n_buses(c));
            assert_eq!(pio_n_branches(back), pio_n_branches(c));
            assert_eq!(pio_n_gens(back), pio_n_gens(c));
            assert_eq!(pio_base_mva(back), pio_base_mva(c));
            assert_eq!(pio_ref_bus_index(back), pio_ref_bus_index(c));

            // The bare "json" alias means the same snapshot format.
            let alias = CString::new("json").unwrap();
            let again = pio_parse_str(text.as_ptr(), alias.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(!again.is_null());
            assert_eq!(pio_n_buses(again), pio_n_buses(c));

            pio_network_free(again);
            pio_network_free(back);
            pio_network_free(c);
        }
    }

    #[test]
    fn snapshot_rejects_garbage() {
        let bad = CString::new("{ not json").unwrap();
        let fmt = CString::new("powerio-json").unwrap();
        let mut err = [0 as c_char; 256];
        let h = unsafe { pio_parse_str(bad.as_ptr(), fmt.as_ptr(), err.as_mut_ptr(), err.len()) };
        assert!(h.is_null());
        let msg = unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap();
        assert!(!msg.is_empty(), "expected a JSON parse error message");
    }

    #[test]
    fn error_buffer_truncates_and_nul_terminates() {
        // copy_to_buf must truncate an oversized message to fit and keep the
        // trailing NUL (the one piece of pointer arithmetic in the file).
        let path = CString::new("/no/such/directory/deeply/nested/missing/case.m").unwrap();
        let mut err = [0x7f as c_char; 16]; // prefill nonzero so the NUL is visible
        let c =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(c.is_null());
        let nul = err
            .iter()
            .position(|&b| b == 0)
            .expect("buffer must be NUL-terminated");
        assert!(nul <= 15);
    }

    #[test]
    fn truncation_lands_on_a_utf8_char_boundary() {
        // "aé€" is 1+2+3 bytes; a 6-byte buffer fits 5 message bytes, which
        // would split '€'. The copy must back up to "aé" instead of emitting a
        // dangling partial codepoint.
        let mut buf = [0x7f as c_char; 6];
        unsafe { copy_to_buf(buf.as_mut_ptr(), buf.len(), "aé€") };
        let s = unsafe { CStr::from_ptr(buf.as_ptr()) }
            .to_str()
            .expect("truncated message must be valid UTF-8");
        assert_eq!(s, "aé");

        // A message that fits is copied whole.
        let mut buf = [0x7f as c_char; 8];
        unsafe { copy_to_buf(buf.as_mut_ptr(), buf.len(), "aé€") };
        let s = unsafe { CStr::from_ptr(buf.as_ptr()) }.to_str().unwrap();
        assert_eq!(s, "aé€");
    }

    #[cfg(feature = "pkg")]
    #[test]
    fn package_feature_is_reported() {
        let pkg = CString::new("pkg").unwrap();
        let nope = CString::new("nope").unwrap();
        unsafe {
            assert_eq!(pio_has_feature(pkg.as_ptr()), 1);
            assert_eq!(pio_has_feature(nope.as_ptr()), 0);
        }
    }

    #[cfg(feature = "pkg")]
    #[test]
    fn package_materialize_reports_unknown_identity() {
        use powerio_pkg::{
            ElementRef, ElementUpdate, NetworkPackage, OperatingPoint, OperatingPointSeries,
            TimeAxis,
        };

        let case = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../tests/data")
            .join("case9.m");
        let net = powerio::parse_str(&std::fs::read_to_string(case).unwrap(), "matpower")
            .unwrap()
            .network;
        let mut point = OperatingPoint::new(0);
        point.updates.push(ElementUpdate::new(
            ElementRef::by_source_uid("generators", "no-such-uid"),
            std::collections::BTreeMap::from([("pg".to_owned(), serde_json::json!(1.0))]),
        ));
        let package = NetworkPackage::from_balanced(net).with_operating_points(
            OperatingPointSeries::new(TimeAxis::new(1).with_duration_hours(vec![1.0]), vec![point]),
        );
        let json = CString::new(package.to_json().unwrap()).unwrap();

        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let pkg = pio_package_parse_str(json.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(
                !pkg.is_null(),
                "package parse_str failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let materialized =
                pio_package_materialize_operating_point(pkg, 0, err.as_mut_ptr(), err.len());
            assert!(materialized.is_null(), "unknown identity must fail");
            let message = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(
                message.contains("unknown identity"),
                "unexpected error: {message}"
            );
            pio_package_free(pkg);
        }
    }

    #[cfg(feature = "pkg")]
    #[test]
    fn package_parse_free_to_json_and_reports() {
        let net = case9();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let pkg = pio_package_from_balanced_network(net, 1, err.as_mut_ptr(), err.len());
            assert!(
                !pkg.is_null(),
                "package constructor failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let v = package_json(pkg);
            assert_eq!(v["schema_version"], serde_json::json!("0.1.1"));
            assert_eq!(v["model_kind"], serde_json::json!("balanced"));
            assert_eq!(v["model"]["kind"], serde_json::json!("balanced"));
            assert_eq!(
                v["payload_schema"],
                serde_json::json!(powerio_pkg::PIO_PAYLOAD_BALANCED_SCHEMA_URL)
            );
            assert_eq!(
                v["payload_schema_version"],
                serde_json::json!(powerio_pkg::PIO_PAYLOAD_BALANCED_SCHEMA_VERSION)
            );
            assert_eq!(
                v["derived"]["normalized_solver_tables"]["row_counts"]["buses"],
                serde_json::json!(9)
            );

            let json = CString::new(package_json_text(pkg)).unwrap();
            let parsed = pio_package_parse_str(json.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(
                !parsed.is_null(),
                "package parse_str failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );

            let tmp = tempfile::tempdir().unwrap();
            let path = tmp.path().join("case9.pio.json");
            std::fs::write(&path, CStr::from_ptr(json.as_ptr()).to_bytes()).unwrap();
            let path = CString::new(path.to_str().unwrap()).unwrap();
            let parsed_file = pio_package_parse_file(path.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(
                !parsed_file.is_null(),
                "package parse_file failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );

            assert_eq!(
                pio_package_validate(parsed_file, err.as_mut_ptr(), err.len()),
                0
            );
            let validation = package_report_json(pio_package_validation_json, parsed_file);
            assert_eq!(validation["status"], serde_json::json!("ok"));
            assert!(
                validation["passes"]
                    .as_array()
                    .unwrap()
                    .iter()
                    .any(|p| p["name"] == "balanced.structure")
            );
            let diagnostics = package_report_json(pio_package_diagnostics_json, parsed_file);
            assert!(diagnostics.as_array().unwrap().is_empty());

            pio_package_free(parsed_file);
            pio_package_free(parsed);
            pio_package_free(pkg);
            pio_network_free(net);
        }
    }

    #[cfg(feature = "pkg")]
    #[test]
    fn package_balanced_constructor_omits_solver_metadata_by_default() {
        let net = case9();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let pkg = pio_package_from_balanced_network(net, 0, err.as_mut_ptr(), err.len());
            assert!(
                !pkg.is_null(),
                "package constructor failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let v = package_json(pkg);
            assert!(v["derived"].get("normalized_solver_tables").is_none());
            pio_package_free(pkg);
            pio_network_free(net);
        }
    }

    #[cfg(all(feature = "pkg", feature = "dist"))]
    mod package_dist {
        use super::*;

        fn strings(values: &[&str]) -> Vec<String> {
            values.iter().map(|v| (*v).to_owned()).collect()
        }

        fn zero_matrix(n: usize) -> powerio_dist::Mat {
            vec![vec![0.0; n]; n]
        }

        fn diagonal_matrix(n: usize, value: f64) -> powerio_dist::Mat {
            let mut matrix = zero_matrix(n);
            for (idx, row) in matrix.iter_mut().enumerate() {
                row[idx] = value;
            }
            matrix
        }

        fn phase_reference(terminals: &[&str], grounded: &[&str]) -> (Vec<f64>, Vec<f64>) {
            let phase_angles = [
                0.0,
                -2.0 * std::f64::consts::PI / 3.0,
                2.0 * std::f64::consts::PI / 3.0,
            ];
            let mut magnitudes = vec![0.0; terminals.len()];
            let mut angles = vec![0.0; terminals.len()];
            let mut active = 0;
            for (idx, terminal) in terminals.iter().enumerate() {
                if grounded.contains(terminal) || *terminal == "0" {
                    continue;
                }
                magnitudes[idx] = 240.0;
                if active < phase_angles.len() {
                    angles[idx] = phase_angles[active];
                }
                active += 1;
            }
            (magnitudes, angles)
        }

        fn preflight_network(terminals: &[&str], grounded: &[&str]) -> powerio_dist::DistNetwork {
            use powerio_dist::{DistBus, DistLine, DistLineCode, DistNetwork, VoltageSource};

            let n = terminals.len();
            let terminal_map = strings(terminals);
            let (v_magnitude, v_angle) = phase_reference(terminals, grounded);
            let mut net = DistNetwork::default();
            for id in ["sourcebus", "loadbus"] {
                let mut bus = DistBus::new(id, terminal_map.clone());
                bus.grounded = strings(grounded);
                net.buses.push(bus);
            }
            let mut linecode =
                DistLineCode::new("lc", diagonal_matrix(n, 0.01), diagonal_matrix(n, 0.10));
            linecode.g_from = zero_matrix(n);
            linecode.b_from = zero_matrix(n);
            linecode.g_to = zero_matrix(n);
            linecode.b_to = zero_matrix(n);
            net.linecodes.push(linecode);
            net.lines.push(DistLine::new(
                "l1",
                "sourcebus",
                "loadbus",
                terminal_map.clone(),
                terminal_map.clone(),
                "lc",
                1.0,
            ));
            net.sources.push(VoltageSource::new(
                "source",
                "sourcebus",
                terminal_map,
                v_magnitude,
                v_angle,
            ));
            net
        }

        #[test]
        fn multiconductor_package_preflight_and_lowering() {
            let dist = PioDistNetwork {
                net: preflight_network(&["1", "2", "3"], &[]),
            };
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            unsafe {
                let pkg =
                    pio_package_from_multiconductor_network(&dist, err.as_mut_ptr(), err.len());
                assert!(
                    !pkg.is_null(),
                    "multiconductor package constructor failed: {}",
                    CStr::from_ptr(err.as_ptr()).to_str().unwrap()
                );
                let v = package_json(pkg);
                assert_eq!(v["model_kind"], serde_json::json!("multiconductor"));

                let report = pio_package_multiconductor_to_balanced_preflight_json(
                    pkg,
                    50.0,
                    err.as_mut_ptr(),
                    err.len(),
                );
                assert!(
                    !report.is_null(),
                    "preflight failed: {}",
                    CStr::from_ptr(err.as_ptr()).to_str().unwrap()
                );
                let report_json: serde_json::Value =
                    serde_json::from_str(CStr::from_ptr(report).to_str().unwrap()).unwrap();
                assert_eq!(report_json["status"], serde_json::json!("ok"));
                assert_eq!(report_json["base_mva"], serde_json::json!(50.0));
                pio_string_free(report);

                let lowered = pio_package_lower_multiconductor_to_balanced(
                    pkg,
                    75.0,
                    err.as_mut_ptr(),
                    err.len(),
                );
                assert!(
                    !lowered.is_null(),
                    "lowering failed: {}",
                    CStr::from_ptr(err.as_ptr()).to_str().unwrap()
                );
                let lowered_json = package_json(lowered);
                assert_eq!(lowered_json["model_kind"], serde_json::json!("balanced"));
                assert_eq!(
                    lowered_json["model"]["balanced_network"]["base_mva"],
                    serde_json::json!(75.0)
                );
                assert_eq!(
                    lowered_json["lowering_history"][0]["pass"],
                    serde_json::json!("multiconductor-to-balanced")
                );

                let invalid_report = pio_package_multiconductor_to_balanced_preflight_json(
                    pkg,
                    0.0,
                    err.as_mut_ptr(),
                    err.len(),
                );
                assert!(
                    !invalid_report.is_null(),
                    "invalid-base preflight failed: {}",
                    CStr::from_ptr(err.as_ptr()).to_str().unwrap()
                );
                let invalid_report_json: serde_json::Value =
                    serde_json::from_str(CStr::from_ptr(invalid_report).to_str().unwrap()).unwrap();
                assert_eq!(invalid_report_json["status"], serde_json::json!("error"));
                assert!(
                    invalid_report_json["diagnostics"]
                        .as_array()
                        .unwrap()
                        .iter()
                        .any(|d| d["code"] == "LOWER.MULTI_TO_BALANCED.INVALID_BASE_MVA")
                );
                pio_string_free(invalid_report);

                let invalid_lowered = pio_package_lower_multiconductor_to_balanced(
                    pkg,
                    0.0,
                    err.as_mut_ptr(),
                    err.len(),
                );
                assert!(invalid_lowered.is_null());
                let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
                assert!(msg.contains("base_mva must be positive"), "got: {msg}");

                pio_package_free(lowered);
                pio_package_free(pkg);
            }
        }
    }

    #[cfg(feature = "arrow")]
    #[test]
    fn to_arrow_null_out_params_return_error() {
        // A NULL out_array/out_schema must be reported (-1), not dereferenced.
        let c = case9();
        let mut err = [0 as c_char; 256];
        let rc = unsafe {
            pio_to_arrow(
                c,
                PIO_ARROW_TABLE_BUS,
                std::ptr::null_mut(),
                std::ptr::null_mut(),
                err.as_mut_ptr(),
                err.len(),
            )
        };
        assert_eq!(rc, -1);
        let msg = unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap();
        assert!(!msg.is_empty(), "expected an error message");
        unsafe { pio_network_free(c) };
    }

    #[cfg(feature = "gridfm")]
    #[test]
    fn read_dir_round_trips_and_enumerates_scenarios() {
        use powerio_matrix::{GridfmOptions, write_gridfm_dataset};
        // Write a one-scenario dataset, then read it back over the C ABI.
        let net = powerio::parse_file(
            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../tests/data/case14.m"),
            None,
        )
        .unwrap()
        .network;
        let tmp = tempfile::tempdir().unwrap();
        let out = write_gridfm_dataset(&net, 0, tmp.path(), &GridfmOptions::default()).unwrap();
        let dir = CString::new(out.dir.to_str().unwrap()).unwrap();
        let from = CString::new("gridfm").unwrap();

        let mut err = [0 as c_char; 256];
        unsafe {
            let h = pio_read_dir(dir.as_ptr(), from.as_ptr(), 0, err.as_mut_ptr(), err.len());
            assert!(
                !h.is_null(),
                "read failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            assert_eq!(pio_n_buses(h), 14);
            // The lossy read's fidelity warnings attach to the handle, like
            // every other constructor's.
            assert!(
                pio_warnings(h, std::ptr::null_mut(), 0) > 0,
                "expected fidelity warnings on the handle"
            );
            pio_network_free(h);

            // Scenario ids: size with a NULL out, then fill. One scenario -> [0].
            let count = pio_scenario_ids(
                dir.as_ptr(),
                from.as_ptr(),
                std::ptr::null_mut(),
                0,
                err.as_mut_ptr(),
                err.len(),
            );
            assert_eq!(count, 1);
            let mut ids = [-1i64; 4];
            let n = pio_scenario_ids(
                dir.as_ptr(),
                from.as_ptr(),
                ids.as_mut_ptr(),
                ids.len(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert_eq!(n, 1);
            assert_eq!(ids[0], 0);

            // An unknown dataset format is a loud error naming the known ones.
            let bad = CString::new("pypsa").unwrap();
            let h = pio_read_dir(dir.as_ptr(), bad.as_ptr(), 0, err.as_mut_ptr(), err.len());
            assert!(h.is_null());
            let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(msg.contains("gridfm"), "got: {msg}");

            // A missing dataset directory errors (NULL handle + message), not a panic.
            let missing = CString::new(tmp.path().join("nope").to_str().unwrap()).unwrap();
            let bad = pio_read_dir(
                missing.as_ptr(),
                from.as_ptr(),
                0,
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(bad.is_null());
            assert!(!CStr::from_ptr(err.as_ptr()).to_str().unwrap().is_empty());
        }
    }

    #[test]
    fn write_dir_rejects_text_formats_by_name() {
        let c = case9();
        let to = CString::new("matpower").unwrap();
        let dir = CString::new("/tmp/unused").unwrap();
        let mut err = [0 as c_char; 256];
        unsafe {
            let rc = pio_write_dir(
                c,
                to.as_ptr(),
                dir.as_ptr(),
                std::ptr::null_mut(),
                0,
                err.as_mut_ptr(),
                err.len(),
            );
            assert_eq!(rc, -1);
            let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(msg.contains("pypsa"), "got: {msg}");
            pio_network_free(c);
        }
    }

    #[cfg(feature = "dist")]
    mod dist {
        use super::*;
        use std::ffi::CStr;

        fn fourwire() -> std::path::PathBuf {
            std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
                .join("../tests/data/dist/micro/fourwire_linecode.dss")
        }

        fn fourwire_cstr() -> CString {
            CString::new(fourwire().to_str().unwrap()).unwrap()
        }

        #[test]
        fn dist_abi_version_is_separate() {
            assert_eq!(pio_abi_version(), PIO_ABI_VERSION);
            assert_eq!(PIO_ABI_VERSION, 4);
            assert_eq!(pio_dist_abi_version(), PIO_DIST_ABI_VERSION);
            assert_eq!(PIO_DIST_ABI_VERSION, 1);
            let feature = CString::new("dist").unwrap();
            assert_eq!(unsafe { pio_has_feature(feature.as_ptr()) }, 1);
        }

        #[test]
        fn parse_file_convert_and_echo() {
            let path = fourwire_cstr();
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let net = unsafe {
                pio_dist_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len())
            };
            assert!(
                !net.is_null(),
                "{}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );

            // Cross format write: schema-shaped BMOPF JSON out.
            let to = CString::new("bmopf").unwrap();
            let mut warn = [0 as c_char; 4096];
            let s = unsafe {
                pio_dist_to_format(
                    net,
                    to.as_ptr(),
                    warn.as_mut_ptr(),
                    warn.len(),
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(!s.is_null());
            let text = unsafe { CStr::from_ptr(s) }.to_str().unwrap();
            assert!(text.contains("\"bus\""));
            unsafe { pio_string_free(s) };

            // Same format write echoes the retained source byte for byte.
            let to = CString::new("dss").unwrap();
            let s = unsafe {
                pio_dist_to_format(
                    net,
                    to.as_ptr(),
                    warn.as_mut_ptr(),
                    warn.len(),
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(!s.is_null());
            let echoed = unsafe { CStr::from_ptr(s) }.to_str().unwrap();
            let source = std::fs::read_to_string(fourwire()).unwrap();
            assert_eq!(echoed, source);
            assert_eq!(
                unsafe { CStr::from_ptr(warn.as_ptr()) }.to_str().unwrap(),
                ""
            );
            unsafe { pio_string_free(s) };

            unsafe { pio_dist_network_free(net) };
        }

        #[test]
        fn convert_str_round_trips_through_pmd() {
            let source = std::fs::read_to_string(fourwire()).unwrap();
            let text = CString::new(source).unwrap();
            let from = CString::new("dss").unwrap();
            let to = CString::new("pmd").unwrap();
            let mut warn = [0 as c_char; 4096];
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let s = unsafe {
                pio_dist_convert_str(
                    text.as_ptr(),
                    from.as_ptr(),
                    to.as_ptr(),
                    warn.as_mut_ptr(),
                    warn.len(),
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(
                !s.is_null(),
                "{}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );
            let pmd = unsafe { CStr::from_ptr(s) }.to_str().unwrap();
            assert!(pmd.contains("\"data_model\": \"ENGINEERING\""));
            unsafe { pio_string_free(s) };
        }

        #[test]
        fn convert_str_rejects_target_before_source_order() {
            let source = std::fs::read_to_string(fourwire()).unwrap();
            let text = CString::new(source).unwrap();
            let old_target = CString::new("pmd").unwrap();
            let old_source = CString::new("dss").unwrap();
            let mut warn = [0 as c_char; 4096];
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let s = unsafe {
                pio_dist_convert_str(
                    text.as_ptr(),
                    old_target.as_ptr(),
                    old_source.as_ptr(),
                    warn.as_mut_ptr(),
                    warn.len(),
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(
                s.is_null(),
                "legacy target-before-source order unexpectedly succeeded"
            );
            let msg = unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap();
            assert!(!msg.is_empty(), "expected an explanatory parse error");
        }

        #[test]
        fn warnings_report_count_and_text() {
            // An unknown length unit draws a parse warning; the handle must
            // surface it. Warnings use the size-then-fill idiom of `pio_warnings`.
            let text = CString::new(
                "clear\nnew circuit.w basekv=12.47 bus1=src\nnew line.l1 bus1=src bus2=b2 length=1 units=furlong\n",
            )
            .unwrap();
            let fmt = CString::new("dss").unwrap();
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let net = unsafe {
                pio_dist_parse_str(text.as_ptr(), fmt.as_ptr(), err.as_mut_ptr(), err.len())
            };
            assert!(!net.is_null());
            let mut warn = [0 as c_char; 4096];
            let n = unsafe { pio_dist_warnings(net, warn.as_mut_ptr(), warn.len()) };
            assert!(n > 0, "expected a nonzero warning length");
            let msg = unsafe { CStr::from_ptr(warn.as_ptr()) }.to_str().unwrap();
            assert!(
                msg.lines().any(|w| w.contains("furlong")),
                "expected the units warning, got: {msg}"
            );
            // NULL handle is a 0-length count, not a crash.
            assert_eq!(
                unsafe { pio_dist_warnings(std::ptr::null(), warn.as_mut_ptr(), warn.len()) },
                0
            );
            unsafe { pio_dist_network_free(net) };
        }

        #[test]
        fn convert_file_round_trips_through_bmopf() {
            let path = fourwire_cstr();
            let to = CString::new("bmopf-json").unwrap();
            let mut warn = [0 as c_char; 4096];
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let s = unsafe {
                pio_dist_convert_file(
                    path.as_ptr(),
                    std::ptr::null(),
                    to.as_ptr(),
                    warn.as_mut_ptr(),
                    warn.len(),
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(
                !s.is_null(),
                "{}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );
            let text = unsafe { CStr::from_ptr(s) }.to_str().unwrap();
            assert!(text.contains("\"bus\""));
            unsafe { pio_string_free(s) };
        }

        #[test]
        fn convert_file_rejects_target_before_source_order() {
            let path = fourwire_cstr();
            let old_target = CString::new("pmd").unwrap();
            let old_source = CString::new("dss").unwrap();
            let mut warn = [0 as c_char; 4096];
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let s = unsafe {
                pio_dist_convert_file(
                    path.as_ptr(),
                    old_target.as_ptr(),
                    old_source.as_ptr(),
                    warn.as_mut_ptr(),
                    warn.len(),
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(
                s.is_null(),
                "legacy target-before-source order unexpectedly succeeded"
            );
            let msg = unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap();
            assert!(!msg.is_empty(), "expected an explanatory parse error");
        }

        #[test]
        fn unknown_format_is_an_error_not_a_crash() {
            let text = CString::new("clear\n").unwrap();
            let fmt = CString::new("matpower").unwrap();
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let net = unsafe {
                pio_dist_parse_str(text.as_ptr(), fmt.as_ptr(), err.as_mut_ptr(), err.len())
            };
            assert!(net.is_null());
            let msg = unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap();
            assert!(msg.contains("unknown distribution format"));
        }

        #[test]
        fn has_feature_reports_dist() {
            let dist = CString::new("dist").unwrap();
            assert_eq!(unsafe { pio_has_feature(dist.as_ptr()) }, 1);
            let nope = CString::new("nope").unwrap();
            assert_eq!(unsafe { pio_has_feature(nope.as_ptr()) }, 0);
        }
    }
}