powerio_capi/

lib.rs

//! C ABI for `powerio`: ABI v5.
//!
//! Functions parse, query, and convert networks through opaque handles. Feature
//! gates add Arrow tables, directory datasets, distribution networks,
//! `.pio.json` packages, and SCOPF problem instances. Each entry point is
//! `extern "C"` and writes errors to a caller provided buffer.
//!
//! The C API 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. Model JSON uses `pio_to_json` and
//!   `pio_from_json`.
//! - 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 API is bus
//!   granular); a *node* is one conductor's point at a bus, reserved for the
//!   multiconductor API; 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::{BalancedNetwork, IndexCore, IndexedNetwork, NormalizeOptions, TargetFormat};

#[cfg(feature = "arrow")]
mod arrow_export;
#[cfg(feature = "arrow")]
pub use arrow_export::{
    PIO_ARROW_TABLE_BDOUBLEPRIME, PIO_ARROW_TABLE_BPRIME, PIO_ARROW_TABLE_BRANCH,
    PIO_ARROW_TABLE_BUS, PIO_ARROW_TABLE_GEN, PIO_ARROW_TABLE_INCIDENCE, PIO_ARROW_TABLE_LOAD,
    PIO_ARROW_TABLE_MATRIX_BRANCH, PIO_ARROW_TABLE_MATRIX_BUS, 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, PIO_ARROW_TABLE_YBUS,
};

/// Opaque parsed network handle. Carries the parsed [`BalancedNetwork`], 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: BalancedNetwork,
    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 return 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()
        }
    }
}

/// Finish a `*mut c_char` entry point: run `f` (the string payload or an error
/// message) 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 string-returning functions that carry no warning buffer.
/// Used by the always built `pio_to_json` as well as the dist and pkg
/// entry points, so it carries no feature gate.
unsafe fn finish_string(
    errbuf: *mut c_char,
    errlen: usize,
    panic_msg: &str,
    f: impl FnOnce() -> Result<String, String>,
) -> *mut c_char {
    unsafe {
        match catch_unwind(AssertUnwindSafe(f)) {
            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()
            }
        }
    }
}

/// 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 `BalancedNetwork` 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: BalancedNetwork, 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 `BalancedNetwork` 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<(BalancedNetwork, 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 documented behavior, including removing a supported
/// format token from the C API. New additive symbols do not 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 before calling another function.
///
/// New data uses new symbols or versioned Arrow, `.pio.json`, or format
/// specific JSON schemas. Existing signatures do not change without an ABI
/// version increment.
///
/// 5 is the current version. It bumped because every ABI visible JSON document
/// changed shape: `pio_schema_versions_json` dropped four keys,
/// `pio_dist_capabilities_json` renamed `schema_version` to `powerio_version`,
/// and the Arrow metadata key became `powerio.version`. A binding built against
/// 4 would pass a handshake it should fail and read `null` for keys it mirrors.
pub const PIO_ABI_VERSION: u32 = 5;

/// Frozen at 1 and no longer meaningful. It existed to absorb distribution
/// volatility, but that volatility lives in the BMOPF schema, which changes a
/// reader, a writer and an emitted token, and no C signature. One shared object
/// carrying two compatibility promises is a thing no mature C library does.
///
/// The symbol stays because PowerIO.jl gates thirteen distribution call sites on
/// resolving it, and removing it would break every distribution call on a
/// library that fully supports distribution. Foreign schema drift is reported at
/// runtime by [`pio_build_info`] instead, which can express "BMOPF 0.2 but not
/// 0.3"; an integer checked once at load cannot.
#[cfg(feature = "dist")]
pub const PIO_DIST_ABI_VERSION: u32 = 1;

/// Recommended 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_*` C API. 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
}

#[cfg(feature = "dist")]
fn dist_capabilities_json() -> String {
    serde_json::json!({
        "dist": true,
        // This document is powerio's own, so it states the release that wrote
        // it. The BMOPF schema it reports below belongs to the task force, and
        // its version is theirs to set.
        powerio::version::VERSION_KEY: powerio::VERSION,
        "bmopf_fixed_taps": true,
        "bmopf_center_tap_leakage": true,
        "bmopf_delta_wye_leakage": true,
        "bmopf_delta_roll": true,
        "bmopf_voltage_source_merge": true,
        "bmopf_transformer_diagnostics": true,
        // Not a fetch location. Use it together with `bmopf_schema_version`.
        "bmopf_schema_id": powerio_dist::BMOPF_SCHEMA_ID,
        "bmopf_schema_version": powerio_dist::BMOPF_SCHEMA_VERSION,
        "typed_capacitors": true,
        "line_and_generator_ratings": true,
        "per_sequence_bus_bounds": true,
        "transformer_extras_relocation": true,
    })
    .to_string()
}

/// Return distribution capability flags as owned JSON. Free the returned string
/// with [`pio_string_free`]. Only linked when the `dist` feature is compiled in;
/// runtime loaders can either check `pio_has_feature("dist")` or probe for this
/// symbol directly. The JSON schema is versioned separately from
/// [`PIO_DIST_ABI_VERSION`] so new additive flags do not force a C signature
/// change.
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub extern "C" fn pio_dist_capabilities_json() -> *mut c_char {
    // Guarded like every other allocating entry point: `serde_json::json!`
    // expands to `to_value(..).unwrap()`, so the panic-free property would
    // otherwise rest on the current field types alone.
    unsafe {
        guard(std::ptr::null_mut(), || {
            into_cstring(dist_capabilities_json()).unwrap_or(std::ptr::null_mut())
        })
    }
}

/// Report the schema version of each document format in this library, as
/// owned JSON. Free the returned string with [`pio_string_free`]. Infallible.
///
/// [`PIO_ABI_VERSION`] does not cover these versions. A binding that
/// mirrors one of them must read it from here and refuse a library it does
/// not agree with. A key is `null` when the owning feature is not compiled
/// in. Keys are only added over time. `powerio_version` covers every
/// document powerio authors; `bmopf_schema` is the foreign schema this build
/// speaks, whose version belongs to whoever owns it.
#[unsafe(no_mangle)]
pub extern "C" fn pio_schema_versions_json() -> *mut c_char {
    unsafe { guard(std::ptr::null_mut(), schema_versions_json_ptr) }
}

/// The body of [`pio_schema_versions_json`], called inside the panic guard.
fn schema_versions_json_ptr() -> *mut c_char {
    // Every document powerio authors states one version, the release that
    // wrote it, so this report needs one key for all of them. What stays
    // separate is the C handshake integer and any foreign schema this build
    // speaks, whose version belongs to whoever owns that schema.
    #[cfg(feature = "dist")]
    let bmopf_schema = Some(powerio_dist::BMOPF_SCHEMA_VERSION);
    // `None` serializes to `null`: the build cannot speak that format.
    #[cfg(not(feature = "dist"))]
    let bmopf_schema: Option<&str> = None;

    let doc = serde_json::json!({
        powerio::version::VERSION_KEY: powerio::VERSION,
        "abi": PIO_ABI_VERSION,
        "bmopf_schema": bmopf_schema,
    });
    into_cstring(doc.to_string()).unwrap_or(std::ptr::null_mut())
}

/// Everything a loader needs to decide what this library can do, as one owned
/// JSON document. Free the returned string with [`pio_string_free`]. Infallible.
///
/// `curl_version_info` is the shape: one call, one report, and new keys arrive
/// without a new symbol. Keys are only added. A caller with no JSON parser
/// keeps using [`pio_has_feature`] and [`pio_abi_version`], which say the same
/// things one answer at a time.
///
/// `error_categories` lists the tokens that prefix an `errbuf` message. The ABI
/// reports errors as text, so a consumer that wants to branch on the kind of
/// failure matches these rather than parsing prose. They are stable; a new
/// category may be added.
#[unsafe(no_mangle)]
pub extern "C" fn pio_build_info() -> *mut c_char {
    unsafe { guard(std::ptr::null_mut(), build_info_ptr) }
}

/// The body of [`pio_build_info`], called inside the panic guard.
fn build_info_ptr() -> *mut c_char {
    #[cfg(feature = "dist")]
    let bmopf_schema = Some(powerio_dist::BMOPF_SCHEMA_VERSION);
    #[cfg(not(feature = "dist"))]
    let bmopf_schema: Option<&str> = None;

    let doc = serde_json::json!({
        powerio::version::VERSION_KEY: powerio::VERSION,
        "abi": PIO_ABI_VERSION,
        "features": {
            "arrow": cfg!(feature = "arrow"),
            "matrix": cfg!(feature = "matrix"),
            "gridfm": cfg!(feature = "gridfm"),
            "dist": cfg!(feature = "dist"),
            "pkg": cfg!(feature = "pkg"),
            "prob": cfg!(feature = "prob"),
        },
        // Foreign schemas this build speaks. The version belongs to whoever
        // owns the schema, which is why an integer checked once at load cannot
        // express it.
        "foreign_schemas": { "bmopf": bmopf_schema },
        "error_categories": powerio::ErrorCategory::TOKENS,
    });
    into_cstring(doc.to_string()).unwrap_or(std::ptr::null_mut())
}

/// Whether the matrix Arrow table API is usable in this build. Returns 1
/// only when both `arrow` and `matrix` are compiled in. Matrix tables use
/// `pio_to_arrow`. Infallible.
#[unsafe(no_mangle)]
pub extern "C" fn pio_matrix_available() -> i32 {
    i32::from(cfg!(all(feature = "arrow", feature = "matrix")))
}

/// Whether an optional build feature is compiled in: pass `"arrow"`, `"matrix"`,
/// `"gridfm"`, `"dist"`, `"pkg"`, or `"prob"`. Returns 1 if present, 0 otherwise (and 0
/// for a NULL or unknown name). The optional entry points (`pio_to_arrow`, the
/// matrix Arrow tables, 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")),
                ("matrix", cfg!(feature = "matrix")),
                ("gridfm", cfg!(feature = "gridfm")),
                ("dist", cfg!(feature = "dist")),
                ("pkg", cfg!(feature = "pkg")),
                ("prob", cfg!(feature = "prob")),
            ];
            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.
/// Used by the always-built `pio_classify_str` as well as the dist and pkg
/// entry points, so it carries no feature gate.
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`, or `surge-json`/`surge`. 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`]. Also accepts
/// `powerio-json`/`json` as aliases for [`pio_from_json`].
#[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())
        })
    }
}

/// Parse `len` bytes of in-memory case data of the named `format` into a
/// network handle. Accepts every [`pio_parse_str`] format name plus `pwb`:
/// PowerWorld binary has no text form, so before this call the only way to
/// reach that reader was [`pio_parse_file`], which means staging a temporary
/// file. `bytes` need not be NUL-terminated and may contain interior NULs;
/// text formats are decoded as UTF-8 and fail with a message if they are not.
///
/// 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_bytes(
    bytes: *const u8,
    len: usize,
    format: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while parsing", || {
            let format = required_cstr(format, "format")?;
            // A zero length read is an empty case, and every reader rejects
            // one with its own message; a NULL pointer is a caller bug.
            let slice = if len == 0 {
                &[][..]
            } else if bytes.is_null() {
                return Err("bytes is NULL".to_string());
            } else {
                std::slice::from_raw_parts(bytes, len)
            };
            powerio::parse_bytes(slice, format)
                .map(|p| (p.network, p.warnings))
                .map_err(|e| e.to_string())
        })
    }
}

/// Classify in-memory JSON case `text` by its top level markers, without
/// parsing the case. Writes one of
///
/// - `transmission:<format>` (e.g. `transmission:powermodels-json`)
/// - `distribution:<format>` (e.g. `distribution:pmd-json`)
/// - `package` (a `.pio.json` package; read it with the package entry points)
/// - `ambiguous` (strong markers from both domains; pass an explicit format)
/// - `unknown` (no recognized marker, or not a JSON object)
///
/// into the caller `outbuf` (truncated to fit, always NUL-terminated) and
/// returns the total byte length of the classification string (the
/// size-then-fill idiom of [`pio_warnings`]). Returns 0 for NULL `text`. The
/// markers are the same ones the transmission parser's `.json` sniffing uses,
/// so a binding can route a bare `.json` before choosing a parser.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_classify_str(
    text: *const c_char,
    outbuf: *mut c_char,
    outlen: usize,
) -> usize {
    unsafe {
        // Terminate up front so every early return, including a panic inside
        // the guard, leaves outbuf a valid empty string.
        copy_to_buf(outbuf, outlen, "");
        guard(0, || {
            let Ok(text) = required_cstr(text, "text") else {
                return 0;
            };
            let label = classify_label(text);
            copy_to_buf(outbuf, outlen, &label);
            label.len()
        })
    }
}

fn classify_label(text: &str) -> String {
    use powerio::format::routing::{self, Detection, Domain, JsonClass};
    match routing::classify_json_text(text) {
        JsonClass::Package => "package".to_string(),
        JsonClass::Case(Detection::Known(format)) => {
            let domain = match format.domain() {
                Domain::Transmission => "transmission",
                Domain::Distribution => "distribution",
                _ => return "unknown".to_string(),
            };
            format!("{domain}:{}", format.name())
        }
        JsonClass::Case(Detection::Ambiguous) => "ambiguous".to_string(),
        JsonClass::Case(Detection::Unknown) => "unknown".to_string(),
    }
}

/// Serialize `net` to its model JSON: the same object a `.pio.json` package
/// carries under `model.balanced_network`, without the surrounding document,
/// and the same text the `powerio-json` format token writes. This is the
/// bindings' data transport; the token remains as a compatibility alias for
/// file based workflows. Returns an owned C string (free with
/// [`pio_string_free`]), `NULL` on error.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_to_json(
    net: *const PioNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while serializing model JSON", || {
            let net = net
                .as_ref()
                .ok_or_else(|| "network handle is NULL".to_string())?;
            net.net.to_json().map_err(|e| e.to_string())
        })
    }
}

/// Parse model JSON produced by [`pio_to_json`] (or lifted from a `.pio.json`
/// document's `model.balanced_network`) back into an owned handle, the
/// inverse of [`pio_to_json`] and the function form of parsing under the
/// `powerio-json` token. Returns `NULL` on error. Free with
/// [`pio_network_free`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_from_json(
    text: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while parsing model JSON", || {
            let text = required_cstr(text, "text")?;
            BalancedNetwork::from_json(text)
                .map(|net| (net, Vec::new()))
                .map_err(|e| e.to_string())
        })
    }
}

/// Read one scenario of a dataset directory in the named `from` format into a
/// network handle. `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 currently supported dataset format. `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
/// currently supported dataset format. 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`, [`pio_normalize`], or [`pio_normalize_with_options`].
#[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
/// `BalancedNetwork::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())
        })
    }
}

/// Normalize `net` into a NEW network handle, with opt in solver preparation
/// repairs.
/// `clamp_angle_bounds != 0` applies the same branch angle difference bound
/// repair as PowerModels (`angmin <= -pi/2`, `angmax >= pi/2`, and zero/zero
/// bounds replaced by `[-angle_bound_pad, angle_bound_pad]`). A repair that
/// would invert the interval widens to that same window. The default pad is
/// 1.0472 radians.
/// Existing read warnings and repair warnings are attached to the returned
/// handle and can be read with [`pio_warnings`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_normalize_with_options(
    net: *const PioNetwork,
    clamp_angle_bounds: i32,
    angle_bound_pad: f64,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(
            errbuf,
            errlen,
            "panic while normalizing with options",
            || {
                let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
                let options = NormalizeOptions {
                    clamp_angle_bounds: clamp_angle_bounds != 0,
                    angle_bound_pad,
                };
                let out = c
                    .net
                    .to_normalized_with_options(&options)
                    .map_err(|e| e.to_string())?;
                let mut warnings = c.warnings.clone();
                warnings.extend(out.warnings);
                Ok((out.network, warnings))
            },
        )
    }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_buses(net: *const PioNetwork) -> usize {
    // The star-lowered space, which is what every other per-bus extractor
    // reports. Through v4 this counted the unexpanded table while
    // pio_bus_demand, pio_bus_shunt and pio_n_islands counted the expansion, so
    // a caller sizing a per-bus buffer from here read short by one entry per
    // in-service 3-winding transformer.
    unsafe { guard(0, || view(net).map_or(0, |v| v.n())) }
}

#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_n_branches(net: *const PioNetwork) -> usize {
    // The star-lowered space, matching pio_n_buses: a 3-winding transformer
    // becomes a star bus plus three branches, and a caller building a matrix
    // from these tables needs both halves of that or the star bus is an
    // isolated row.
    unsafe { guard(0, || view(net).map_or(0, |v| v.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)) }
}

/// Case name. Writes UTF-8 bytes into `out`, up to `cap`, NUL-terminates when
/// possible, and returns the byte length needed excluding the NUL. `NULL` or
/// `cap == 0` is a size query.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_network_name(
    net: *const PioNetwork,
    out: *mut c_char,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            copy_to_buf(out, cap, &c.net.name);
            c.net.name.len()
        })
    }
}

/// Source format enum spelling used by the JSON snapshot, for example
/// `Matpower`, `PowerModelsJson`, or `Normalized`. Uses the same cap/count
/// string convention as [`pio_network_name`].
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_source_format(
    net: *const PioNetwork,
    out: *mut c_char,
    cap: usize,
) -> usize {
    unsafe {
        guard(0, || {
            let Some(c) = network_ref(net) else { return 0 };
            let name = format!("{:?}", c.net.source_format);
            copy_to_buf(out, cap, &name);
            name.len()
        })
    }
}

/// Serialize a compact balanced network summary as JSON for display and scalar
/// queries without serializing [`pio_to_json`]'s full payload.
///
/// `counts` is the case file's own inventory, so it counts a 3-winding
/// transformer once under `transformers_3w` rather than as the star bus and
/// three branches it lowers to. `topology.n_buses` and `topology.n_branches`
/// are that lowered space, the one [`pio_n_buses`] and [`pio_branches`]
/// report and the one the rest of `topology` is computed over. The two differ
/// only for a case with an in-service 3-winding transformer.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_summary_json(
    net: *const PioNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(
            errbuf,
            errlen,
            "panic while serializing summary JSON",
            || {
                let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
                let v = IndexedNetwork::with_core(&c.net, &c.core);
                let reference_bus_indices = v.reference_bus_indices();
                let reference_bus_ids: Vec<usize> = reference_bus_indices
                    .iter()
                    .map(|&idx| v.bus_id(idx).0)
                    .collect();
                let summary = serde_json::json!({
                    powerio::version::VERSION_KEY: powerio::VERSION,
                    "name": c.net.name,
                    "source_format": format!("{:?}", c.net.source_format),
                    "base_mva": c.net.base_mva,
                    "base_frequency": c.net.base_frequency,
                    "counts": {
                        "buses": c.net.buses.len(),
                        "loads": c.net.loads.len(),
                        "shunts": c.net.shunts.len(),
                        "branches": c.net.branches.len(),
                        "switches": c.net.switches.len(),
                        "generators": c.net.generators.len(),
                        "storage": c.net.storage.len(),
                        "hvdc": c.net.hvdc.len(),
                        "transformers_3w": c.net.transformers_3w.len(),
                        "areas": c.net.areas.len(),
                        "warnings": c.warnings.len(),
                    },
                    "topology": {
                        "n_buses": v.n(),
                        "n_branches": v.branches().len(),
                        "reference_bus_ids": reference_bus_ids,
                        "reference_bus_indices": reference_bus_indices,
                        "n_components": v.n_connected_components(),
                        "is_radial": v.is_radial(),
                    },
                });
                serde_json::to_string(&summary).map_err(|e| e.to_string())
            },
        )
    }
}

/// 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.
/// Also accepts `powerio-json` as an alias for
/// [`pio_to_json`]. Model JSON cannot represent a non-finite `f64` (`Inf`/`NaN`):
/// it writes `null`, records the field in `out_warnings`, and fails validation when
/// read back.
///
/// Returns the text as an owned C string (free with [`pio_string_free`]),
/// `NULL` on error (message into `errbuf`). Fidelity warnings, if any, are
/// published through `out_warnings` as one owned C string (free it with
/// [`pio_string_free`]), or NULL when there are none; a returned string has no
/// handle to attach them to. Pass NULL to discard them.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_to_format(
    net: *const PioNetwork,
    to: *const c_char,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(out_warnings, 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))
        })
    }
}

/// Write `warnings` to `out_warnings` as one owned, `\n`-joined C string, or
/// NULL when there are none. NULL `out_warnings` discards them.
///
/// A caller buffer cannot work here. Warnings are unbounded in a way an error
/// message is not: one per lossy element, so a large case produces more than
/// any fixed size a caller can guess, and guessing is what PowerIO.jl was doing
/// with a 64 KiB buffer. The errbuf idiom stays for errors, which are one
/// message.
unsafe fn set_out_warnings(out_warnings: *mut *mut c_char, warnings: &[String]) {
    unsafe {
        if out_warnings.is_null() {
            return;
        }
        *out_warnings = if warnings.is_empty() {
            std::ptr::null_mut()
        } else {
            // An interior NUL cannot reach here: warnings are library-authored
            // text. If one ever did, reporting no warnings beats truncating at
            // the NUL and reporting a prefix as the whole set.
            into_cstring(warnings.join("\n")).unwrap_or(std::ptr::null_mut())
        };
    }
}

/// Finish a text-conversion entry point: run `f` (producing the converted text
/// with its fidelity warnings, or an error message) under the panic guard,
/// publish the warnings through `out_warnings`, 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(
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
    f: impl FnOnce() -> Result<(String, Vec<String>), String>,
) -> *mut c_char {
    unsafe {
        // Set before running f: a caller reads it on every return path, and a
        // stale value from an earlier call must not be mistaken for this one's.
        set_out_warnings(out_warnings, &[]);
        match catch_unwind(AssertUnwindSafe(f)) {
            Ok(Ok((text, warnings))) => {
                set_out_warnings(out_warnings, &warnings);
                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 published through `out_warnings` as one owned C string (free it with
/// [`pio_string_free`]), NULL when there are none. Pass NULL to discard them.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_convert_file(
    path: *const c_char,
    from: *const c_char,
    to: *const c_char,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(out_warnings, 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. 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,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(out_warnings, 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 `out_dir` as the named directory format `to`. PyPSA CSV
/// (`pypsa-csv`/`pypsa`) is the currently supported directory format; 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
/// published through `out_warnings` as one owned C string (free it with
/// [`pio_string_free`]), NULL when there are none. Pass NULL to discard them.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_write_dir(
    net: *const PioNetwork,
    to: *const c_char,
    out_dir: *const c_char,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> i32 {
    unsafe {
        set_out_warnings(out_warnings, &[]);
        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)) => {
                set_out_warnings(out_warnings, &warnings);
                0
            }
            Ok(Err(msg)) => {
                copy_to_buf(errbuf, errlen, &msg);
                -1
            }
            Err(_) => {
                copy_to_buf(errbuf, errlen, "panic while writing directory");
                -1
            }
        }
    }
}

/// Free any owned C string returned by this API.
#[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, || {
            // The star-lowered space, so every per-bus column keyed to this
            // ordering has an id at every index. A star bus carries the
            // synthesized id the expansion assigned it.
            view(net).map_or(0, |v| {
                fill(
                    out,
                    cap,
                    (0..v.n()).map(|i| i64::try_from(v.bus_id(i).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(v) = view(net) else { return 0 };
            let branches = v.branches();
            fill(
                from,
                cap,
                branches
                    .iter()
                    .map(|br| i64::try_from(br.from.0).unwrap_or(-1)),
            );
            fill(
                to,
                cap,
                branches
                    .iter()
                    .map(|br| i64::try_from(br.to.0).unwrap_or(-1)),
            );
            fill(r, cap, branches.iter().map(|br| br.r));
            fill(x, cap, branches.iter().map(|br| br.x));
            fill(b, cap, branches.iter().map(|br| br.total_charging_b()));
            fill(tap, cap, branches.iter().map(|br| br.tap));
            fill(shift, cap, branches.iter().map(|br| br.shift));
            fill(
                in_service,
                cap,
                branches.iter().map(|br| u8::from(br.in_service)),
            );
            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(v) = view(net) else { return 0 };
            let branches = v.branches();
            fill(
                g_fr,
                cap,
                branches.iter().map(|br| br.terminal_charging().g_fr),
            );
            fill(
                b_fr,
                cap,
                branches.iter().map(|br| br.terminal_charging().b_fr),
            );
            fill(
                g_to,
                cap,
                branches.iter().map(|br| br.terminal_charging().g_to),
            );
            fill(
                b_to,
                cap,
                branches.iter().map(|br| br.terminal_charging().b_to),
            );
            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 table surface of this ABI. Tables 0..5 are raw network tables; tables
/// 6..14 are normalized solver tables with per unit/radian values and dense
/// zero based row ids; the matrix tables carry COO triplets in that dense index
/// space with dimensions in schema metadata. New columns extend the Arrow
/// schema without changing an existing C signature.
///
/// `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, &c.core, 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
            }
        }
    }
}

/// Return the Arrow table catalog as owned compact JSON.
///
/// The catalog is feature based rather than handle based: it describes what
/// this library build can export, not what a particular network contains. Top
/// level fields are `powerio_version`, `producer`, and `tables`. Each table
/// entry includes `id`, `name`, `format`, `feature_requirements`, `available`,
/// `row_axis`, `col_axis`, `units`, and `columns`. Each column entry includes
/// `name`, `type`, and `nullable`. Through v4 both levels carried a
/// `schema_version`; one release version now covers every document powerio
/// authors, so the top level names it and the per-table copy is gone.
///
/// Free the returned string with [`pio_string_free`]. On error this returns
/// NULL and writes the message into `errbuf`. Only built with the `arrow` cargo
/// feature.
#[cfg(feature = "arrow")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_arrow_catalog_json(errbuf: *mut c_char, errlen: usize) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while building Arrow catalog", || {
            Ok(arrow_export::catalog_json())
        })
    }
}

// ---------------------------------------------------------------------------
// Package API (`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; 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 {
        finish_string(errbuf, errlen, panic_msg, || {
            let pkg = pkg
                .as_ref()
                .ok_or_else(|| "package handle is NULL".to_string())?;
            f(pkg)
        })
    }
}

/// 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_with_read_warnings(
                    net.net.clone(),
                    powerio_pkg::READ_TRANSMISSION_PARSE_WARNING,
                    net.warnings.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(),
                ))
            },
        )
    }
}

/// Materialize the balanced payload of a package handle as an owned network
/// handle: the inverse of [`pio_package_from_balanced_network`]. Errors when
/// the package holds a different model kind. The handle is built from the
/// payload alone: it retains no source text, so a same format write is a fresh
/// serialization rather than a byte-exact echo, and it carries no parse
/// warnings. Free with [`pio_network_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_to_balanced_network(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(
            errbuf,
            errlen,
            "panic while extracting balanced network",
            || {
                let pkg = pkg
                    .as_ref()
                    .ok_or_else(|| "package handle is NULL".to_string())?;
                let net = pkg.package.model.as_balanced().ok_or_else(|| {
                    if cfg!(feature = "dist") {
                        "package holds a multiconductor model, not balanced; use \
                         pio_package_to_multiconductor_network"
                            .to_string()
                    } else {
                        "package holds a multiconductor model, not balanced; extracting \
                         it needs a build with the `dist` feature \
                         (pio_package_to_multiconductor_network)"
                            .to_string()
                    }
                })?;
                let mut net = net.clone();
                // An in-memory package still holds the payload's #[serde(skip)]
                // source text; drop it so extraction behaves the same whether
                // or not the package crossed JSON, and a same-format write is
                // the promised fresh serialization.
                net.source = None;
                Ok((net, Vec::new()))
            },
        )
    }
}

/// Materialize the multiconductor payload of a package handle as an owned
/// distribution network handle: the inverse of
/// [`pio_package_from_multiconductor_network`]. Errors when the package holds
/// a different model kind. The handle retains no source text, so a
/// same format write is a fresh serialization. The handle retains the payload's
/// parse warnings, readable through [`pio_dist_warnings`]. Free with
/// [`pio_dist_network_free`].
#[cfg(all(feature = "pkg", feature = "dist"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_to_multiconductor_network(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioDistNetwork {
    unsafe {
        finish_handle(
            errbuf,
            errlen,
            "panic while extracting multiconductor network",
            || {
                let pkg = pkg
                    .as_ref()
                    .ok_or_else(|| "package handle is NULL".to_string())?;
                let net = pkg.package.model.as_multiconductor().ok_or_else(|| {
                    "package holds a balanced model, not multiconductor; use \
                     pio_package_to_balanced_network"
                        .to_string()
                })?;
                let mut net = net.clone();
                // Same in-memory strip as the balanced inverse: source and the
                // defaulted provenance are #[serde(skip)], so dropping them
                // here matches what a JSON crossing produces.
                net.source = None;
                net.defaulted = Default::default();
                Ok(PioDistNetwork { net })
            },
        )
    }
}

/// 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. [`pio_package_set_operating_points`] is the other such
/// entry point; every other call takes the handle `const` and shares it.
#[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()),
        )
    }
}

/// Replace the package's operating point series from `json`. `null` or an
/// empty series clears it. Validation is recomputed before this function
/// returns. Returns `0` on success and `-1` on error.
///
/// This rewrites the handle, so it takes it non-`const` and needs exclusive
/// access: no other call may touch the same handle concurrently. See
/// [`pio_package_validate`], the other such entry point.
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_set_operating_points(
    pkg: *mut PioPackage,
    json: *const c_char,
    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())?;
            let json = required_cstr(json, "json")?;
            let series: Option<powerio_pkg::OperatingPointSeries> =
                serde_json::from_str(json).map_err(|e| e.to_string())?;
            match series {
                Some(series) => pkg.package.set_operating_points(series),
                None => pkg.package.clear_operating_points(),
            }
            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 setting package operating points",
                );
                -1
            }
        }
    }
}

/// Return the package study block 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_study_json(
    pkg: *const PioPackage,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_package_json(
            pkg,
            errbuf,
            errlen,
            "panic while reading package study block",
            |p| serde_json::to_string(&p.package.study).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())
            },
        )
    }
}

/// Materialize one study commit into a new static package.
///
/// The returned handle owns a package with commits `0..=index` applied and no
/// operating point series or study block. Free it with [`pio_package_free`].
#[cfg(feature = "pkg")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_package_materialize_study_commit(
    pkg: *const PioPackage,
    index: i64,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioPackage {
    unsafe {
        finish_package(
            errbuf,
            errlen,
            "panic while materializing package study commit",
            || {
                let pkg = pkg
                    .as_ref()
                    .ok_or_else(|| "package handle is NULL".to_string())?;
                let index = usize::try_from(index)
                    .map_err(|_| "study commit index must be non-negative".to_string())?;
                pkg.package
                    .materialize_study_commit(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 {
        finish_string(
            errbuf,
            errlen,
            "panic while preflighting package lowering",
            || {
                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())
            },
        )
    }
}

/// 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())
        })
    }
}

// ---------------------------------------------------------------------------
// Geographic layer API. String in and string out, no new object lifetimes:
// the canonical form is a GeoJSON FeatureCollection with the
// `powerio_geo` foreign member (see the geo chapter of the guide).
// ---------------------------------------------------------------------------

/// Normalize a tolerant geographic sidecar (headerless buscoords CSV, aliased
/// CSV/JSON records, GeoJSON Point/LineString) to the canonical GeoJSON form.
/// `name_hint` (a file name, nullable) picks CSV against JSON when given;
/// otherwise the content is sniffed. The tolerant reader's notes are not
/// returned here; parse through the Rust or Python surface to see them. Free
/// the returned string with `pio_string_free`. Returns `NULL` on input that
/// carries no usable coordinates and writes the message into `errbuf`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_geo_parse(
    text: *const c_char,
    name_hint: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while parsing geo layer", || {
            let text = required_cstr(text, "text")?;
            let name_hint = optional_cstr(name_hint, "name_hint")?;
            let parsed = powerio::GeoLayer::parse_bytes(text.as_bytes(), name_hint)
                .map_err(|e| e.to_string())?;
            Ok(parsed.layer.to_geojson())
        })
    }
}

/// Extract a network's coordinates as the canonical GeoJSON layer: one point
/// per located bus, one route per routed branch. Free the returned string
/// with `pio_string_free`. Returns `NULL` (with a message) when the network
/// carries no coordinates.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_geo_extract(
    net: *const PioNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while extracting geo layer", || {
            let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
            c.net
                .geo_layer()
                .extracted_geojson()
                .map_err(|e| e.to_string())
        })
    }
}

/// Apply a geographic sidecar (any form [`pio_geo_parse`] accepts) onto a NEW
/// network handle; the input handle is unchanged and both are freed with
/// `pio_network_free`. `name_hint` (a file name, nullable) picks CSV against
/// JSON as in [`pio_geo_parse`]. Matched bus points land in `Bus.location`,
/// matched branch routes in `Branch.route`. The returned handle drops the
/// retained source text, so a same-format write re-serializes the placed case
/// instead of echoing the original. The reader's notes and an apply summary
/// (`geo apply: N bus point(s), ...`) are appended to the handle's warnings
/// ([`pio_warnings`]). Returns `NULL` on error.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_geo_apply(
    net: *const PioNetwork,
    layer: *const c_char,
    name_hint: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioNetwork {
    unsafe {
        finish_network(errbuf, errlen, "panic while applying geo layer", || {
            let c = network_ref(net).ok_or_else(|| "network handle is NULL".to_string())?;
            let layer = required_cstr(layer, "layer")?;
            let name_hint = optional_cstr(name_hint, "name_hint")?;
            let parsed = powerio::GeoLayer::parse_bytes(layer.as_bytes(), name_hint)
                .map_err(|e| e.to_string())?;
            let mut out = c.net.clone();
            let report = out.apply_geo_layer(&parsed.layer);
            out.source = None;
            let mut warnings = c.warnings.clone();
            warnings.extend(parsed.warnings);
            warnings.push(geo_apply_summary(&report));
            warnings.extend(report.notes);
            Ok((out, warnings))
        })
    }
}

/// One-line apply summary lifted into the returned handle's warnings.
fn geo_apply_summary(report: &powerio::GeoApplyReport) -> String {
    format!(
        "geo apply: {} bus point(s), {} branch route(s), {} unmatched feature(s), \
         {} bus(es) with no location, {} branch(es) with no route",
        report.matched_buses,
        report.matched_branches,
        report.unmatched_features,
        report.unlocated_buses,
        report.unlocated_branches
    )
}

// ---------------------------------------------------------------------------
// Problem instance API (`prob` feature).
// ---------------------------------------------------------------------------

/// Opaque matrix free SCOPF instance.
#[cfg(feature = "prob")]
pub struct PioScopfInstance {
    instance: powerio_prob::ScopfInstance,
}

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

/// Parse SCOPF source text into an owned problem instance. `from` currently
/// accepts `"goc3-json"`. Returns `NULL` on error and writes the message into
/// `errbuf`. Free the handle with `pio_scopf_instance_free`.
#[cfg(feature = "prob")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_scopf_parse_str(
    text: *const c_char,
    from: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioScopfInstance {
    unsafe {
        finish_handle(errbuf, errlen, "panic while parsing SCOPF instance", || {
            let text = required_cstr(text, "text")?;
            let from = required_cstr(from, "from")?;
            let instance =
                powerio_prob::parse_scopf_str(text, from).map_err(|error| error.to_string())?;
            Ok(PioScopfInstance { instance })
        })
    }
}

/// Serialize a SCOPF instance as its Julia compatibility document. The JSON records
/// its schema version and index base. Free the returned string with
/// `pio_string_free`. Returns `NULL` for a null handle or serialization error.
#[cfg(feature = "prob")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_scopf_to_json(
    instance: *const PioScopfInstance,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(
            errbuf,
            errlen,
            "panic while serializing SCOPF instance",
            || {
                let instance = instance
                    .as_ref()
                    .ok_or_else(|| "SCOPF instance handle is NULL".to_string())?;
                powerio_prob::scopf::json::to_json(&instance.instance)
                    .map_err(|error| error.to_string())
            },
        )
    }
}

/// Free a SCOPF instance handle. `NULL` is a no-op; free each handle once.
#[cfg(feature = "prob")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_scopf_instance_free(instance: *mut PioScopfInstance) {
    unsafe {
        guard((), || {
            if !instance.is_null() {
                drop(Box::from_raw(instance));
            }
        });
    }
}

// ---------------------------------------------------------------------------
// Distribution API (`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 API is EXPERIMENTAL while the IEEE BMOPF
// schema is a draft: C signature changes bump `PIO_DIST_ABI_VERSION`. BMOPF
// JSON carries its own meta.version; the model JSON of `pio_dist_to_json` is
// covered by the `.pio.json` `schema_version` in powerio-pkg.
// ---------------------------------------------------------------------------

/// Finish a handle-returning 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(any(feature = "dist", feature = "prob"))]
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::MulticonductorNetwork,
}

// 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 a compact summary of a distribution handle as JSON. This lets
/// bindings answer display and scalar queries without forcing
/// [`pio_dist_to_json`]'s full model payload.
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_summary_json(
    net: *const PioDistNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(
            errbuf,
            errlen,
            "panic while serializing summary JSON",
            || {
                let net = net
                    .as_ref()
                    .ok_or_else(|| "distribution network handle is NULL".to_string())?;
                let summary = serde_json::json!({
                    powerio::version::VERSION_KEY: powerio::VERSION,
                    "name": net.net.name.as_deref(),
                    "source_format": net.net.source_format.map(|f| f.name()),
                    "base_frequency": net.net.base_frequency,
                    "counts": {
                        "buses": net.net.buses.len(),
                        "linecodes": net.net.linecodes.len(),
                        "lines": net.net.lines.len(),
                        "switches": net.net.switches.len(),
                        "transformers": net.net.transformers.len(),
                        "loads": net.net.loads.len(),
                        "generators": net.net.generators.len(),
                        "ibrs": net.net.ibrs.len(),
                        "control_profiles": net.net.control_profiles.len(),
                        "shunts": net.net.shunts.len(),
                        "capacitors": net.net.capacitors.len(),
                        "sources": net.net.sources.len(),
                        "untyped": net.net.untyped.len(),
                        "warnings": net.net.warnings.len(),
                    },
                });
                serde_json::to_string(&summary).map_err(|e| e.to_string())
            },
        )
    }
}

/// Serialize `net` to its model JSON: the same object a `.pio.json` package
/// carries under `model.multiconductor_network`, without the surrounding
/// document. This is the bindings' data transport, not a case format: the
/// converter, CLI, and format inference do not know it; distribution cases
/// exchanged with other tools are BMOPF JSON ([`pio_dist_to_format`]).
/// Returns 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_json(
    net: *const PioDistNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while serializing model JSON", || {
            let net = net
                .as_ref()
                .ok_or_else(|| "distribution network handle is NULL".to_string())?;
            serde_json::to_string(&net.net).map_err(|e| e.to_string())
        })
    }
}

/// Serialize the collapsed bus and terminal graph projection for `net` as JSON.
/// The returned string is owned by the library; free it with
/// [`pio_string_free`].
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_graph_json(
    net: *const PioDistNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while serializing graph JSON", || {
            let net = net
                .as_ref()
                .ok_or_else(|| "distribution network handle is NULL".to_string())?;
            serde_json::to_string(&net.net.graph()).map_err(|e| e.to_string())
        })
    }
}

/// Parse model JSON produced by [`pio_dist_to_json`] (or lifted from a
/// `.pio.json` document's `model.multiconductor_network`) back into an owned
/// handle: the inverse of [`pio_dist_to_json`]. The rebuilt handle retains
/// no source text, so a same format write is a fresh serialization. The handle
/// retains the model JSON `warnings`. Returns `NULL` on error. Free with
/// [`pio_dist_network_free`].
#[cfg(feature = "dist")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_from_json(
    text: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioDistNetwork {
    unsafe {
        finish_handle(errbuf, errlen, "panic while parsing model JSON", || {
            let text = required_cstr(text, "text")?;
            serde_json::from_str::<powerio_dist::MulticonductorNetwork>(text)
                .map(|net| PioDistNetwork { net })
                .map_err(|e| format!("model JSON: {e}"))
        })
    }
}

/// Append a fidelity warning for each companion file the writer produced.
/// The text-only C entry points cannot return these files, so the case text
/// can refer to a file the caller does not have. The warning names it.
#[cfg(feature = "dist")]
fn warn_dropped_sidecars(
    mut warnings: Vec<String>,
    sidecars: &[powerio_dist::ConversionSidecar],
) -> Vec<String> {
    for sidecar in sidecars {
        warnings.push(sidecar.dropped_warning(
            "this entry point returns the case text only, and that text refers to the file; \
             write it beside the case before loading",
        ));
    }
    warnings
}

/// 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,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(out_warnings, 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,
                warn_dropped_sidecars(conv.warnings, &conv.sidecars),
            ))
        })
    }
}

/// 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,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(out_warnings, 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,
                warn_dropped_sidecars(conv.warnings, &conv.sidecars),
            ))
        })
    }
}

/// 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,
    out_warnings: *mut *mut c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_conversion(out_warnings, 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,
                warn_dropped_sidecars(conv.warnings, &conv.sidecars),
            ))
        })
    }
}

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

/// Extract a multiconductor network's coordinates as the canonical GeoJSON
/// layer, keyed by the string bus and line names. Free the returned string
/// with `pio_string_free`. Returns `NULL` (with a message) when the network
/// carries no coordinates.
#[cfg(all(feature = "dist", feature = "pkg"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_geo_extract(
    net: *const PioDistNetwork,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut c_char {
    unsafe {
        finish_string(errbuf, errlen, "panic while extracting geo layer", || {
            let c = net
                .as_ref()
                .ok_or_else(|| "distribution network handle is NULL".to_string())?;
            powerio_pkg::dist_geo_layer(&c.net)
                .extracted_geojson()
                .map_err(|e| e.to_string())
        })
    }
}

/// Apply a geographic sidecar (any form [`pio_geo_parse`] accepts) onto a NEW
/// distribution network handle; the input handle is unchanged and both are
/// freed with `pio_dist_network_free`. `name_hint` (a file name, nullable)
/// picks CSV against JSON as in [`pio_geo_parse`]. The returned handle drops
/// the retained source text, so a same-format write re-serializes the placed
/// case. The reader's notes and an apply summary are appended to the handle's
/// warnings ([`pio_dist_warnings`]). Returns `NULL` on error.
#[cfg(all(feature = "dist", feature = "pkg"))]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn pio_dist_geo_apply(
    net: *const PioDistNetwork,
    layer: *const c_char,
    name_hint: *const c_char,
    errbuf: *mut c_char,
    errlen: usize,
) -> *mut PioDistNetwork {
    unsafe {
        finish_handle(errbuf, errlen, "panic while applying geo layer", || {
            let c = net
                .as_ref()
                .ok_or_else(|| "distribution network handle is NULL".to_string())?;
            let layer = required_cstr(layer, "layer")?;
            let name_hint = optional_cstr(name_hint, "name_hint")?;
            let parsed = powerio::GeoLayer::parse_bytes(layer.as_bytes(), name_hint)
                .map_err(|e| e.to_string())?;
            let mut out = c.net.clone();
            let report = powerio_pkg::apply_dist_geo_layer(&mut out, &parsed.layer);
            out.source = None;
            out.source_format = None;
            out.warnings.extend(parsed.warnings);
            out.warnings.push(geo_apply_summary(&report));
            out.warnings.extend(report.notes);
            Ok(PioDistNetwork { net: out })
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use powerio::POWER_MODELS_ANGLE_BOUND_PAD;
    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}");
    }

    #[test]
    fn parse_bytes_reads_binary_and_text_without_a_file() {
        let read = |name: &str| {
            std::fs::read(
                std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
                    .join("../tests/data")
                    .join(name),
            )
            .unwrap()
        };
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            // The reason the symbol exists: PowerWorld binary has no text form,
            // so pio_parse_str cannot reach this reader at all.
            let pwb = read("powerworld/ACTIVSg200.pwb");
            let fmt = CString::new("pwb").unwrap();
            let net = pio_parse_bytes(
                pwb.as_ptr(),
                pwb.len(),
                fmt.as_ptr(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                !net.is_null(),
                "pwb bytes: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            assert_eq!(pio_n_buses(net), 200);
            pio_network_free(net);

            // A text format agrees with the path parse of the same file.
            let m = read("case9.m");
            let fmt = CString::new("matpower").unwrap();
            let from_bytes = pio_parse_bytes(
                m.as_ptr(),
                m.len(),
                fmt.as_ptr(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(!from_bytes.is_null());
            let from_path = case9();
            assert_eq!(pio_n_buses(from_bytes), pio_n_buses(from_path));
            assert_eq!(pio_n_branches(from_bytes), pio_n_branches(from_path));
            pio_network_free(from_bytes);
            pio_network_free(from_path);

            // Bytes that are not UTF-8 fail with a message, not a panic.
            let junk = [0xffu8, 0xfe, 0x00, 0x01];
            let bad = pio_parse_bytes(
                junk.as_ptr(),
                junk.len(),
                fmt.as_ptr(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(bad.is_null());
            assert!(
                CStr::from_ptr(err.as_ptr())
                    .to_str()
                    .unwrap()
                    .contains("UTF-8"),
                "expected a UTF-8 message, got {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );

            // A NULL buffer with a nonzero length is a caller bug, reported
            // rather than dereferenced.
            let null_bytes = pio_parse_bytes(
                std::ptr::null(),
                8,
                fmt.as_ptr(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(null_bytes.is_null());
        }
    }

    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 angle_bounds_case() -> *mut PioNetwork {
        let path = data_path("angle_bounds_clamp.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 = BalancedNetwork::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_out: *mut c_char = std::ptr::null_mut();
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_to_format(net, to.as_ptr(), &mut warn_out, 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
        }
    }

    unsafe fn network_json(net: *const PioNetwork) -> serde_json::Value {
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let s = pio_to_json(net, err.as_mut_ptr(), err.len());
            assert!(
                !s.is_null(),
                "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);
            serde_json::from_str(&text).unwrap()
        }
    }

    unsafe fn warning_text(net: *const PioNetwork) -> String {
        let n = unsafe { pio_warnings(net, std::ptr::null_mut(), 0) };
        let mut buf = vec![0 as c_char; n + 1];
        unsafe {
            pio_warnings(net, buf.as_mut_ptr(), buf.len());
            CStr::from_ptr(buf.as_ptr()).to_str().unwrap().to_owned()
        }
    }

    #[test]
    /// Confirms that the generic C API can detect a DeepMind OPFData file,
    /// expose its basic network data and warnings, and convert it to MATPOWER.
    fn deepmind_opfdata_uses_shared_c_api() {
        let path = data_path("opfdataset/example_0.json");
        let mut err = [0 as c_char; 512];
        let net =
            unsafe { pio_parse_file(path.as_ptr(), std::ptr::null(), err.as_mut_ptr(), err.len()) };
        assert!(
            !net.is_null(),
            "parse returned null: {}",
            unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
        );

        unsafe {
            assert_eq!(pio_n_buses(net), 14);
            assert_eq!(pio_n_branches(net), 20);
            assert_eq!(pio_n_gens(net), 5);
            close(pio_base_mva(net), 100.0);

            let mut source_format = [0 as c_char; 64];
            let len = pio_source_format(net, source_format.as_mut_ptr(), source_format.len());
            assert_eq!(
                CStr::from_ptr(source_format.as_ptr()).to_str().unwrap(),
                "DeepMindOpfDataJson"
            );
            assert_eq!(len, "DeepMindOpfDataJson".len());
            assert!(warning_text(net).contains("solver initial values"));
            assert!(to_format(net, "matpower").contains("mpc.bus"));
            pio_network_free(net);
        }
    }

    #[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 every_extractor_reports_the_star_lowered_space() {
        // A 3-winding transformer star-lowers into one bus plus three branches
        // before the dense extractors run. Through v4 the bus and branch
        // tables reported the unexpanded network while pio_bus_demand and
        // pio_n_islands reported the expansion, so a caller sizing from them
        // read short. Both halves have to move together: 10 buses against 9
        // branches leaves the star point an isolated row and the transformer
        // contributing nothing.
        let case = case9_json_with_a_3w_transformer();
        let text = CString::new(case).unwrap();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let net = pio_from_json(text.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(
                !net.is_null(),
                "from_json failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );

            let n = pio_n_buses(net);
            let demand = pio_bus_demand(net, std::ptr::null_mut(), std::ptr::null_mut(), 0);
            let shunt = pio_bus_shunt(net, std::ptr::null_mut(), std::ptr::null_mut(), 0);
            let ids = pio_bus_ids(net, std::ptr::null_mut(), 0);

            assert_eq!(n, 10, "9 buses plus one star point");
            assert_eq!(demand, n, "pio_bus_demand must agree with pio_n_buses");
            assert_eq!(shunt, n, "pio_bus_shunt must agree with pio_n_buses");
            assert_eq!(ids, n, "pio_bus_ids must agree with pio_n_buses");

            let m = pio_n_branches(net);
            let (ni, nf, nb) = (
                std::ptr::null_mut::<i64>(),
                std::ptr::null_mut::<f64>(),
                std::ptr::null_mut::<u8>(),
            );
            let rows = pio_branches(net, ni, ni, nf, nf, nf, nf, nf, nb, 0);
            let charging = pio_branch_charging(net, nf, nf, nf, nf, 0);
            assert_eq!(m, 12, "9 branches plus three star legs");
            assert_eq!(rows, m, "pio_branches must agree with pio_n_branches");
            assert_eq!(charging, m, "pio_branch_charging must agree too");

            // Every index a per-bus column addresses has an id, the star point
            // included: sizing from pio_n_buses is now sufficient.
            let mut buf = vec![-1i64; n];
            assert_eq!(pio_bus_ids(net, buf.as_mut_ptr(), buf.len()), n);
            assert!(
                buf.iter().all(|&id| id > 0),
                "every dense index carries an id, got {buf:?}"
            );

            // The two tables close over each other: every branch endpoint is a
            // bus this API reports, and every bus is reachable, so an incidence
            // matrix built from these arrays has no isolated row.
            let mut from = vec![-1i64; m];
            let mut to = vec![-1i64; m];
            assert_eq!(
                pio_branches(
                    net,
                    from.as_mut_ptr(),
                    to.as_mut_ptr(),
                    nf,
                    nf,
                    nf,
                    nf,
                    nf,
                    nb,
                    m
                ),
                m
            );
            for id in from.iter().chain(&to) {
                assert!(
                    buf.contains(id),
                    "branch endpoint {id} is not in pio_bus_ids"
                );
            }
            for id in &buf {
                assert!(
                    from.contains(id) || to.contains(id),
                    "bus {id} has no incident branch"
                );
            }

            // The summary carries both spaces and says which is which: counts
            // is the case file's inventory, so the transformer is one row
            // there, and topology is the space the extractors report.
            let raw = pio_summary_json(net, err.as_mut_ptr(), err.len());
            assert!(!raw.is_null());
            let summary: serde_json::Value =
                serde_json::from_str(CStr::from_ptr(raw).to_str().unwrap()).unwrap();
            pio_string_free(raw);
            assert_eq!(summary["counts"]["buses"], 9);
            assert_eq!(summary["counts"]["branches"], 9);
            assert_eq!(summary["counts"]["transformers_3w"], 1);
            assert_eq!(summary["topology"]["n_buses"], n);
            assert_eq!(summary["topology"]["n_branches"], m);

            pio_network_free(net);
        }
    }

    /// case9 with one in-service 3-winding transformer spliced in, as model
    /// JSON. Built here rather than vendored: the fixtures are real MATPOWER
    /// cases and none of them carries a 3-winding transformer.
    fn case9_json_with_a_3w_transformer() -> String {
        let net = case9();
        let mut doc: serde_json::Value = unsafe {
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let raw = pio_to_json(net, err.as_mut_ptr(), err.len());
            assert!(!raw.is_null());
            let text = CStr::from_ptr(raw).to_str().unwrap().to_owned();
            pio_string_free(raw);
            pio_network_free(net);
            serde_json::from_str(&text).unwrap()
        };
        let winding = |bus: i64| {
            serde_json::json!({
                "bus": bus, "tap": 1.0, "shift": 0.0, "nominal_kv": 0.0,
                "rate_a": 0.0, "rate_b": 0.0, "rate_c": 0.0
            })
        };
        let z = serde_json::json!({ "r": 0.0, "x": 0.05, "base_mva": 100.0 });
        doc["transformers_3w"] = serde_json::json!([{
            "windings": [winding(4), winding(5), winding(6)],
            "z": [z, z, z],
            "star_vm": 1.0, "star_va": 0.0, "mag_g": 0.0, "mag_b": 0.0,
            "in_service": true, "name": "t3", "extras": {}
        }]);
        doc.to_string()
    }

    #[test]
    fn build_info_reports_the_build_in_one_document() {
        let raw = pio_build_info();
        assert!(!raw.is_null());
        let doc: serde_json::Value =
            serde_json::from_str(unsafe { CStr::from_ptr(raw) }.to_str().unwrap()).unwrap();
        unsafe { pio_string_free(raw) };

        assert_eq!(doc["abi"], serde_json::json!(PIO_ABI_VERSION));
        assert_eq!(
            doc[powerio::version::VERSION_KEY],
            serde_json::json!(powerio::VERSION)
        );
        // Every feature this build knows about answers here and through
        // pio_has_feature; the two must not disagree.
        for name in ["arrow", "matrix", "gridfm", "dist", "pkg", "prob"] {
            let c = CString::new(name).unwrap();
            let probed = unsafe { pio_has_feature(c.as_ptr()) } == 1;
            assert_eq!(
                doc["features"][name],
                serde_json::json!(probed),
                "{name} disagrees between pio_build_info and pio_has_feature"
            );
        }
        assert_eq!(
            doc["error_categories"],
            serde_json::json!(powerio::ErrorCategory::TOKENS)
        );
    }

    #[test]
    fn version_api() {
        // 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, 5);
        let v = unsafe { CStr::from_ptr(pio_version()) }.to_str().unwrap();
        assert_eq!(v, env!("CARGO_PKG_VERSION"));
        assert!(!v.is_empty());
    }

    #[test]
    fn matrix_probe_matches_build_features() {
        let matrix = CString::new("matrix").unwrap();
        unsafe {
            assert_eq!(
                pio_has_feature(matrix.as_ptr()),
                i32::from(cfg!(feature = "matrix"))
            );
        }
        assert_eq!(
            pio_matrix_available(),
            i32::from(cfg!(all(feature = "arrow", feature = "matrix")))
        );
    }

    #[test]
    fn prob_probe_matches_build_features() {
        let prob = CString::new("prob").unwrap();
        unsafe {
            assert_eq!(
                pio_has_feature(prob.as_ptr()),
                i32::from(cfg!(feature = "prob"))
            );
        }
    }

    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 5",
            "#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",
            "#define PIO_ARROW_TABLE_YBUS 15",
            "#define PIO_ARROW_TABLE_INCIDENCE 16",
            "#define PIO_ARROW_TABLE_BPRIME 17",
            "#define PIO_ARROW_TABLE_BDOUBLEPRIME 18",
            "#define PIO_ARROW_TABLE_MATRIX_BUS 19",
            "#define PIO_ARROW_TABLE_MATRIX_BRANCH 20",
            "typedef struct PioDistNetwork PioDistNetwork;",
            "typedef struct PioNetwork PioNetwork;",
            "typedef struct PioPackage PioPackage;",
            "typedef struct PioScopfInstance PioScopfInstance;",
            "uint32_t pio_abi_version(void);",
            "uint32_t pio_dist_abi_version(void);",
            "char *pio_dist_capabilities_json(void);",
            "char *pio_schema_versions_json(void);",
            "char *pio_build_info(void);",
            "int32_t pio_matrix_available(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_parse_bytes(const uint8_t *bytes, size_t len, const char *format, char *errbuf, size_t errlen);",
            "size_t pio_classify_str(const char *text, char *outbuf, size_t outlen);",
            "char *pio_to_json(const PioNetwork *net, char *errbuf, size_t errlen);",
            "PioNetwork *pio_from_json(const char *text, 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);",
            "PioNetwork *pio_normalize_with_options(const PioNetwork *net, int32_t clamp_angle_bounds, double angle_bound_pad, 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);",
            "size_t pio_network_name(const PioNetwork *net, char *out, size_t cap);",
            "size_t pio_source_format(const PioNetwork *net, char *out, size_t cap);",
            "char *pio_summary_json(const PioNetwork *net, char *errbuf, size_t errlen);",
            "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 **out_warnings, char *errbuf, size_t errlen);",
            "char *pio_convert_file(const char *path, const char *from, const char *to, char **out_warnings, char *errbuf, size_t errlen);",
            "char *pio_convert_str(const char *text, const char *from, const char *to, char **out_warnings, char *errbuf, size_t errlen);",
            "int32_t pio_write_dir(const PioNetwork *net, const char *to, const char *out_dir, char **out_warnings, 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);",
            "char *pio_arrow_catalog_json(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);",
            "PioNetwork *pio_package_to_balanced_network(const PioPackage *pkg, char *errbuf, size_t errlen);",
            "PioDistNetwork *pio_package_to_multiconductor_network(const PioPackage *pkg, 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);",
            "int32_t pio_package_set_operating_points(PioPackage *pkg, const char *json, char *errbuf, size_t errlen);",
            "char *pio_package_study_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);",
            "PioPackage *pio_package_materialize_study_commit(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);",
            "char *pio_geo_parse(const char *text, const char *name_hint, char *errbuf, size_t errlen);",
            "char *pio_geo_extract(const PioNetwork *net, char *errbuf, size_t errlen);",
            "PioNetwork *pio_geo_apply(const PioNetwork *net, const char *layer, const char *name_hint, char *errbuf, size_t errlen);",
            "PioScopfInstance *pio_scopf_parse_str(const char *text, const char *from, char *errbuf, size_t errlen);",
            "char *pio_scopf_to_json(const PioScopfInstance *instance, char *errbuf, size_t errlen);",
            "void pio_scopf_instance_free(PioScopfInstance *instance);",
            "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_summary_json(const PioDistNetwork *net, char *errbuf, size_t errlen);",
            "char *pio_dist_to_json(const PioDistNetwork *net, char *errbuf, size_t errlen);",
            "char *pio_dist_graph_json(const PioDistNetwork *net, char *errbuf, size_t errlen);",
            "PioDistNetwork *pio_dist_from_json(const char *text, char *errbuf, size_t errlen);",
            "char *pio_dist_to_format(const PioDistNetwork *net, const char *to, char **out_warnings, char *errbuf, size_t errlen);",
            "char *pio_dist_convert_file(const char *path, const char *from, const char *to, char **out_warnings, char *errbuf, size_t errlen);",
            "char *pio_dist_convert_str(const char *text, const char *from, const char *to, char **out_warnings, char *errbuf, size_t errlen);",
            "char *pio_dist_geo_extract(const PioDistNetwork *net, char *errbuf, size_t errlen);",
            "PioDistNetwork *pio_dist_geo_apply(const PioDistNetwork *net, const char *layer, const char *name_hint, 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);
            let mut name = [0 as c_char; 64];
            let name_len = pio_network_name(c, name.as_mut_ptr(), name.len());
            assert_eq!(CStr::from_ptr(name.as_ptr()).to_str().unwrap(), "case9");
            assert_eq!(name_len, 5);
            let mut source_format = [0 as c_char; 64];
            let fmt_len = pio_source_format(c, source_format.as_mut_ptr(), source_format.len());
            assert_eq!(
                CStr::from_ptr(source_format.as_ptr()).to_str().unwrap(),
                "Matpower"
            );
            assert_eq!(fmt_len, 8);
            let mut err = [0 as c_char; 256];
            let summary = pio_summary_json(c, err.as_mut_ptr(), err.len());
            assert!(
                !summary.is_null(),
                "summary json failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let summary_value: serde_json::Value =
                serde_json::from_str(CStr::from_ptr(summary).to_str().unwrap()).unwrap();
            assert_eq!(summary_value["name"], "case9");
            assert_eq!(summary_value["source_format"], "Matpower");
            assert_eq!(summary_value["base_mva"], 100.0);
            assert_eq!(summary_value["counts"]["buses"], 9);
            assert_eq!(summary_value["counts"]["branches"], 9);
            assert_eq!(summary_value["counts"]["generators"], 3);
            assert_eq!(
                summary_value["topology"]["reference_bus_ids"],
                serde_json::json!([1])
            );
            assert_eq!(summary_value["topology"]["n_components"], 1);
            assert_eq!(summary_value["topology"]["is_radial"], false);
            pio_string_free(summary);
            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(),
                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_out: *mut c_char = std::ptr::null_mut();
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_convert_file(
                path.as_ptr(),
                std::ptr::null(),
                to.as_ptr(),
                &mut warn_out,
                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_out: *mut c_char = std::ptr::null_mut();
        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(),
                &mut warn_out,
                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_out: *mut c_char = std::ptr::null_mut();
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_convert_str(
                text.as_ptr(),
                from.as_ptr(),
                to.as_ptr(),
                &mut warn_out,
                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_out: *mut c_char = std::ptr::null_mut();
        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(),
                &mut warn_out,
                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_out: *mut c_char = std::ptr::null_mut();
        err.fill(0);
        let s = unsafe {
            pio_convert_file(
                path.as_ptr(),
                bad_from.as_ptr().cast::<c_char>(),
                to.as_ptr(),
                &mut warn_out,
                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());
            assert!(
                pio_normalize_with_options(
                    nil,
                    1,
                    POWER_MODELS_ANGLE_BOUND_PAD,
                    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 normalize_with_options_clamps_angle_bounds_and_warns() {
        let c = angle_bounds_case();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let cn = pio_normalize_with_options(
                c,
                1,
                POWER_MODELS_ANGLE_BOUND_PAD,
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                !cn.is_null(),
                "normalize with options returned null: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let v = network_json(cn);
            close(
                v["branches"][0]["angmin"].as_f64().unwrap(),
                -POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][0]["angmax"].as_f64().unwrap(),
                POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][1]["angmin"].as_f64().unwrap(),
                -POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][1]["angmax"].as_f64().unwrap(),
                POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][2]["angmin"].as_f64().unwrap(),
                -std::f64::consts::PI / 6.0,
            );
            close(
                v["branches"][2]["angmax"].as_f64().unwrap(),
                std::f64::consts::PI / 6.0,
            );
            close(
                v["branches"][3]["angmin"].as_f64().unwrap(),
                -POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][3]["angmax"].as_f64().unwrap(),
                POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][4]["angmin"].as_f64().unwrap(),
                -POWER_MODELS_ANGLE_BOUND_PAD,
            );
            close(
                v["branches"][4]["angmax"].as_f64().unwrap(),
                POWER_MODELS_ANGLE_BOUND_PAD,
            );
            for branch in v["branches"].as_array().unwrap() {
                assert!(branch["angmin"].as_f64().unwrap() <= branch["angmax"].as_f64().unwrap());
            }

            let warnings = warning_text(cn);
            assert!(warnings.contains("branch 0 angle difference bounds clamped"));
            assert!(warnings.contains("branch 1 angle difference bounds clamped"));
            assert!(warnings.contains("branch 3 angle difference bounds clamped"));
            assert!(warnings.contains("branch 4 angle difference bounds clamped"));

            pio_network_free(cn);
            pio_network_free(c);
        }
    }

    #[test]
    fn normalize_with_options_rejects_invalid_angle_pad() {
        let c = angle_bounds_case();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let cn = pio_normalize_with_options(
                c,
                1,
                std::f64::consts::FRAC_PI_2,
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(cn.is_null());
            let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(msg.contains("angle_bound_pad"), "{msg}");
            pio_network_free(c);
        }
    }

    #[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_out: *mut c_char = std::ptr::null_mut();
        let mut err = [0 as c_char; 256];
        unsafe {
            let s = pio_convert_file(
                path.as_ptr(),
                std::ptr::null(),
                to.as_ptr(),
                &mut warn_out,
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(!s.is_null());
            assert!(!warn_out.is_null(), "expected fidelity warnings");
            let w = CStr::from_ptr(warn_out).to_str().unwrap().to_owned();
            assert!(
                w.contains("converter detail"),
                "expected an HVDC converter-detail warning, got {w:?}"
            );
            pio_string_free(warn_out);
            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_set_operating_points_round_trips() {
        use powerio_pkg::NetworkPackage;

        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 json = CString::new(NetworkPackage::from_balanced(net).to_json().unwrap()).unwrap();
        let series_text = r#"{
            "time_axis": {"periods": 1, "duration_hours": [1.0]},
            "points": [
                {
                    "index": 0,
                    "updates": [
                        {
                            "element": {"table": "generators", "source_uid": "generators:0"},
                            "fields": {"pg": 1.5}
                        }
                    ]
                }
            ]
        }"#;
        let series = CString::new(series_text).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()
            );
            assert!(
                package_report_json(pio_package_operating_points_json, pkg).is_null(),
                "freshly parsed package must start with no operating points"
            );

            let status =
                pio_package_set_operating_points(pkg, series.as_ptr(), err.as_mut_ptr(), err.len());
            assert_eq!(
                status,
                0,
                "set_operating_points failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );

            let expected: serde_json::Value = serde_json::from_str(series_text).unwrap();
            let echoed = package_report_json(pio_package_operating_points_json, pkg);
            assert_eq!(echoed, expected, "attached series did not echo back");

            let invalid = CString::new("not json").unwrap();
            let status = pio_package_set_operating_points(
                pkg,
                invalid.as_ptr(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert_eq!(status, -1);
            assert_eq!(
                package_report_json(pio_package_operating_points_json, pkg),
                expected,
                "a parse error must not replace the existing series"
            );

            let materialized =
                pio_package_materialize_operating_point(pkg, 0, err.as_mut_ptr(), err.len());
            assert!(
                !materialized.is_null(),
                "materialize failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let materialized_json = package_json(materialized);
            assert_eq!(
                materialized_json["model"]["balanced_network"]["generators"][0]["pg"],
                serde_json::json!(1.5)
            );
            pio_package_free(materialized);

            // Attaching `null` clears the series back out.
            let clear = CString::new("null").unwrap();
            let status =
                pio_package_set_operating_points(pkg, clear.as_ptr(), err.as_mut_ptr(), err.len());
            assert_eq!(status, 0);
            assert!(package_report_json(pio_package_operating_points_json, pkg).is_null());
            assert_eq!(
                package_report_json(pio_package_validation_json, pkg)["status"],
                serde_json::json!("ok")
            );

            pio_package_free(pkg);
        }
    }

    #[cfg(feature = "pkg")]
    #[test]
    fn package_study_json_and_materialize_commit() {
        use powerio_pkg::{ElementRef, NetworkPackage, StudyBlock, StudyCommit, StudyEdit};

        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 commit = StudyCommit::default();
        commit.label = Some("load step".to_owned());
        commit.edits.push(StudyEdit::DemandDelta {
            bus: ElementRef::by_source_uid("buses", "buses:0"),
            p_mw: 7.0,
            q_mvar: Some(3.0),
        });
        let mut study = StudyBlock::default();
        study.label = Some("binding study".to_owned());
        study.commits.push(commit);
        let package = NetworkPackage::from_balanced(net).with_study(study);
        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 study = package_report_json(pio_package_study_json, pkg);
            assert_eq!(study["label"], serde_json::json!("binding study"));
            assert_eq!(
                study["commits"][0]["edits"][0]["kind"],
                serde_json::json!("demand_delta")
            );

            let materialized =
                pio_package_materialize_study_commit(pkg, 0, err.as_mut_ptr(), err.len());
            assert!(
                !materialized.is_null(),
                "study materialization failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let materialized_json = package_json(materialized);
            assert!(materialized_json.get("study").is_none());
            assert!(materialized_json.get("operating_points").is_none());
            let loads = materialized_json["model"]["balanced_network"]["loads"]
                .as_array()
                .unwrap();
            assert!(loads.iter().any(|load| {
                load["uid"] == serde_json::json!("study:load:buses:0")
                    && load["p"] == serde_json::json!(7.0)
                    && load["q"] == serde_json::json!(3.0)
            }));

            let negative =
                pio_package_materialize_study_commit(pkg, -1, err.as_mut_ptr(), err.len());
            assert!(negative.is_null());
            let message = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
            assert!(
                message.contains("study commit index must be non-negative"),
                "unexpected error: {message}"
            );

            pio_package_free(materialized);
            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[powerio::version::VERSION_KEY],
                serde_json::json!(powerio::VERSION)
            );
            assert_eq!(v["model_kind"], serde_json::json!("balanced"));
            assert_eq!(v["model"]["kind"], serde_json::json!("balanced"));
            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(feature = "prob")]
    const GOC3_SMALL_FIXTURE: &str = include_str!("../../powerio-prob/tests/data/goc3_small.json");

    #[cfg(feature = "prob")]
    #[test]
    fn scopf_handle_serializes_its_julia_document() {
        let text = CString::new(GOC3_SMALL_FIXTURE).unwrap();
        let from = CString::new("goc3-json").unwrap();
        let feature = CString::new("prob").unwrap();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            assert_eq!(pio_has_feature(feature.as_ptr()), 1);
            let instance =
                pio_scopf_parse_str(text.as_ptr(), from.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(
                !instance.is_null(),
                "pio_scopf_parse_str failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let json = pio_scopf_to_json(instance, err.as_mut_ptr(), err.len());
            assert!(!json.is_null());
            let text = CStr::from_ptr(json).to_str().unwrap().to_owned();
            let v: serde_json::Value = serde_json::from_str(&text).unwrap();

            assert_eq!(v["schema"], "powerio.scopf.julia");
            assert_eq!(v[powerio::version::VERSION_KEY], powerio::VERSION);
            assert_eq!(v["index_base"], 1);
            assert_eq!(v["instance"]["lengths"]["I"], 2);
            assert_eq!(v["instance"]["static"]["acl_branch"][0]["j_ln"], 1);

            pio_string_free(json);
            pio_scopf_instance_free(instance);
            pio_scopf_instance_free(std::ptr::null_mut());
        }
    }

    #[cfg(feature = "prob")]
    #[test]
    fn scopf_handle_reports_format_parse_and_null_errors() {
        let valid = CString::new(GOC3_SMALL_FIXTURE).unwrap();
        let text = CString::new("not json").unwrap();
        let from = CString::new("goc3-json").unwrap();
        let unsupported = CString::new("matpower").unwrap();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            let instance =
                pio_scopf_parse_str(text.as_ptr(), from.as_ptr(), err.as_mut_ptr(), err.len());
            assert!(instance.is_null());
            assert!(!CStr::from_ptr(err.as_ptr()).to_bytes().is_empty());

            let instance = pio_scopf_parse_str(
                valid.as_ptr(),
                unsupported.as_ptr(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(instance.is_null());
            assert!(
                CStr::from_ptr(err.as_ptr())
                    .to_str()
                    .unwrap()
                    .contains("unsupported SCOPF source format")
            );

            let json = pio_scopf_to_json(std::ptr::null(), err.as_mut_ptr(), err.len());
            assert!(json.is_null());
            assert!(
                CStr::from_ptr(err.as_ptr())
                    .to_str()
                    .unwrap()
                    .contains("handle is NULL")
            );
        }
    }

    #[test]
    fn geo_parse_normalizes_and_apply_returns_a_placed_handle() {
        let net = case9();
        let coords = CString::new("1, -89.6, 40.6\n2, -89.2, 39.8\n").unwrap();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        unsafe {
            // No coordinates yet: extract refuses.
            let empty = pio_geo_extract(net, err.as_mut_ptr(), err.len());
            assert!(empty.is_null());

            let canonical = pio_geo_parse(
                coords.as_ptr(),
                std::ptr::null(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                !canonical.is_null(),
                "pio_geo_parse failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let v: serde_json::Value =
                serde_json::from_str(CStr::from_ptr(canonical).to_str().unwrap()).unwrap();
            assert_eq!(v["type"], "FeatureCollection");
            assert_eq!(v["powerio_geo"]["space"], "geographic");

            let placed = pio_geo_apply(
                net,
                coords.as_ptr(),
                std::ptr::null(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(
                !placed.is_null(),
                "pio_geo_apply failed: {}",
                CStr::from_ptr(err.as_ptr()).to_str().unwrap()
            );
            let layer = pio_geo_extract(placed, err.as_mut_ptr(), err.len());
            assert!(!layer.is_null());
            let v: serde_json::Value =
                serde_json::from_str(CStr::from_ptr(layer).to_str().unwrap()).unwrap();
            assert_eq!(v["features"].as_array().unwrap().len(), 2);

            // The apply summary rides the new handle's warnings.
            let count = pio_warnings(placed, std::ptr::null_mut(), 0);
            assert!(count > 0);

            pio_string_free(layer);
            pio_string_free(canonical);
            pio_network_free(placed);
            pio_network_free(net);

            let garbage = CString::new("not a geo file").unwrap();
            let out = pio_geo_parse(
                garbage.as_ptr(),
                std::ptr::null(),
                err.as_mut_ptr(),
                err.len(),
            );
            assert!(out.is_null());
            assert!(!CStr::from_ptr(err.as_ptr()).to_bytes().is_empty());
        }
    }

    #[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::MulticonductorNetwork {
            use powerio_dist::{
                DistBus, DistLine, DistLineCode, MulticonductorNetwork, VoltageSource,
            };

            let n = terminals.len();
            let terminal_map = strings(terminals);
            let (v_magnitude, v_angle) = phase_reference(terminals, grounded);
            let mut net = MulticonductorNetwork::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 = "arrow")]
    #[test]
    fn arrow_catalog_json_symbol_returns_table_catalog() {
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        let ptr = unsafe { pio_arrow_catalog_json(err.as_mut_ptr(), err.len()) };
        assert!(
            !ptr.is_null(),
            "{}",
            unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
        );
        let text = unsafe { CStr::from_ptr(ptr) }.to_str().unwrap().to_owned();
        unsafe { pio_string_free(ptr) };
        let catalog: serde_json::Value = serde_json::from_str(&text).unwrap();
        assert_eq!(catalog[powerio::version::VERSION_KEY], powerio::VERSION);
        assert!(catalog["tables"].as_array().unwrap().iter().any(|table| {
            table["id"] == serde_json::json!(PIO_ARROW_TABLE_MATRIX_BUS)
                && table["name"] == serde_json::json!("matrix_bus")
        }));
    }

    #[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(),
                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")]
    fn fourwire() -> std::path::PathBuf {
        std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("../tests/data/dist/micro/fourwire_linecode.dss")
    }

    #[cfg(feature = "dist")]
    fn fourwire_cstr() -> CString {
        CString::new(fourwire().to_str().unwrap()).unwrap()
    }

    /// Write `net` as BMOPF JSON. Shared by the round trip tests that compare
    /// a handle's output before and after crossing the package boundary.
    #[cfg(feature = "dist")]
    unsafe fn bmopf(net: *const PioDistNetwork) -> String {
        let to = CString::new("bmopf").unwrap();
        let mut warn_out: *mut c_char = std::ptr::null_mut();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        let s = unsafe {
            pio_dist_to_format(net, to.as_ptr(), &mut warn_out, err.as_mut_ptr(), err.len())
        };
        assert!(!s.is_null());
        let text = unsafe { std::ffi::CStr::from_ptr(s) }
            .to_str()
            .unwrap()
            .to_owned();
        unsafe { pio_string_free(s) };
        text
    }

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

        #[cfg(feature = "pkg")]
        #[test]
        fn dist_geo_apply_returns_a_placed_handle() {
            let master = CString::new(
                "New Circuit.c1 bus1=sourcebus basekv=12.47\n\
                 New Line.l1 bus1=sourcebus bus2=loadbus length=1 units=km\n",
            )
            .unwrap();
            let format = CString::new("dss").unwrap();
            let coords = CString::new("sourcebus, -89.6, 40.6\nloadbus, -89.2, 39.8\n").unwrap();
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            unsafe {
                let net = pio_dist_parse_str(
                    master.as_ptr(),
                    format.as_ptr(),
                    err.as_mut_ptr(),
                    err.len(),
                );
                assert!(!net.is_null());
                let empty = pio_dist_geo_extract(net, err.as_mut_ptr(), err.len());
                assert!(empty.is_null());

                let placed = pio_dist_geo_apply(
                    net,
                    coords.as_ptr(),
                    std::ptr::null(),
                    err.as_mut_ptr(),
                    err.len(),
                );
                assert!(
                    !placed.is_null(),
                    "pio_dist_geo_apply failed: {}",
                    CStr::from_ptr(err.as_ptr()).to_str().unwrap()
                );
                let layer = pio_dist_geo_extract(placed, err.as_mut_ptr(), err.len());
                assert!(!layer.is_null());
                let v: serde_json::Value =
                    serde_json::from_str(CStr::from_ptr(layer).to_str().unwrap()).unwrap();
                assert_eq!(v["features"].as_array().unwrap().len(), 2);
                pio_string_free(layer);
                pio_dist_network_free(placed);
                pio_dist_network_free(net);
            }
        }

        #[test]
        fn dist_abi_version_is_frozen_at_one() {
            assert_eq!(pio_abi_version(), PIO_ABI_VERSION);
            assert_eq!(PIO_ABI_VERSION, 5);
            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 version_report_states_one_powerio_version_and_the_foreign_ones() {
            let raw = pio_schema_versions_json();
            assert!(!raw.is_null());
            let text = unsafe { CStr::from_ptr(raw) }.to_str().unwrap().to_owned();
            unsafe { pio_string_free(raw) };
            let doc: serde_json::Value = serde_json::from_str(&text).unwrap();

            // One key for every document powerio authors, and the C handshake
            // integer, which is a different mechanism.
            assert_eq!(
                doc[powerio::version::VERSION_KEY],
                serde_json::json!(powerio::VERSION)
            );
            assert_eq!(doc["abi"], serde_json::json!(PIO_ABI_VERSION));

            // The per document numbers this report used to carry are gone,
            // not renamed: a binding that still reads one must fail loudly.
            for retired in ["schema_version", "package", "arrow", "dist_capabilities"] {
                assert_eq!(doc[retired], serde_json::Value::Null, "{retired}");
            }

            // A foreign schema keeps its owner's version, which is the whole
            // reason this report exists.
            #[cfg(feature = "dist")]
            assert_eq!(
                doc["bmopf_schema"],
                serde_json::json!(powerio_dist::BMOPF_SCHEMA_VERSION)
            );
            #[cfg(not(feature = "dist"))]
            assert_eq!(doc["bmopf_schema"], serde_json::Value::Null);
        }

        #[test]
        fn dist_capabilities_json_reports_bmopf_fidelity_flags() {
            let ptr = pio_dist_capabilities_json();
            assert!(!ptr.is_null(), "dist capabilities JSON returned NULL");
            let text = unsafe { CStr::from_ptr(ptr) }.to_str().unwrap().to_owned();
            unsafe { pio_string_free(ptr) };

            let caps: serde_json::Value = serde_json::from_str(&text).unwrap();
            // Whole-document equality: each addition must be a deliberate
            // edit here.
            assert_eq!(
                caps,
                serde_json::json!({
                    "dist": true,
                    powerio::version::VERSION_KEY: powerio::VERSION,
                    "bmopf_fixed_taps": true,
                    "bmopf_center_tap_leakage": true,
                    "bmopf_delta_wye_leakage": true,
                    "bmopf_delta_roll": true,
                    "bmopf_voltage_source_merge": true,
                    "bmopf_transformer_diagnostics": true,
                    "bmopf_schema_id": powerio_dist::BMOPF_SCHEMA_ID,
                    "bmopf_schema_version": powerio_dist::BMOPF_SCHEMA_VERSION,
                    "typed_capacitors": true,
                    "line_and_generator_ratings": true,
                    "per_sequence_bus_bounds": true,
                    "transformer_extras_relocation": true,
                })
            );
        }

        #[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 compatible BMOPF JSON out.
            let to = CString::new("bmopf").unwrap();
            let mut warn_out: *mut c_char = std::ptr::null_mut();
            let s = unsafe {
                pio_dist_to_format(net, to.as_ptr(), &mut warn_out, 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(), &mut warn_out, 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!(warn_out.is_null(), "a byte exact echo loses nothing");
            unsafe { pio_string_free(s) };

            unsafe { pio_dist_network_free(net) };
        }

        #[test]
        fn graph_json_reports_bus_edge_projection() {
            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()
            );

            let graph = unsafe { pio_dist_graph_json(net, err.as_mut_ptr(), err.len()) };
            assert!(
                !graph.is_null(),
                "graph json failed: {}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );
            let graph_json: serde_json::Value =
                serde_json::from_str(unsafe { CStr::from_ptr(graph) }.to_str().unwrap()).unwrap();
            let buses = graph_json["buses"].as_array().unwrap();
            assert_eq!(buses.len(), 2);
            assert!(buses.iter().any(|bus| {
                bus["id"] == serde_json::json!("sourcebus")
                    && bus["has_source"] == serde_json::json!(true)
            }));
            let edges = graph_json["edges"].as_array().unwrap();
            assert!(edges.iter().any(|edge| {
                edge["kind"] == serde_json::json!("line")
                    && edge["id"] == serde_json::json!("l1")
                    && edge["from"] == serde_json::json!("sourcebus")
                    && edge["to"] == serde_json::json!("loadbus")
                    && edge["n_phases"] == serde_json::json!(4)
                    && edge["conductors"].as_array().unwrap().len() == 4
            }));

            unsafe {
                pio_string_free(graph);
                pio_dist_network_free(net);
            }
        }

        #[test]
        fn summary_json_reports_counts_without_model_payload() {
            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()
            );

            let summary = unsafe { pio_dist_summary_json(net, err.as_mut_ptr(), err.len()) };
            assert!(
                !summary.is_null(),
                "summary json failed: {}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );
            let value: serde_json::Value =
                serde_json::from_str(unsafe { CStr::from_ptr(summary) }.to_str().unwrap()).unwrap();
            assert_eq!(
                value[powerio::version::VERSION_KEY],
                serde_json::json!(powerio::VERSION)
            );
            assert_eq!(value["source_format"], serde_json::json!("dss"));
            assert_eq!(value["base_frequency"], serde_json::json!(60.0));
            assert_eq!(value["counts"]["buses"], serde_json::json!(2));
            assert_eq!(value["counts"]["lines"], serde_json::json!(1));
            assert_eq!(value["counts"]["loads"], serde_json::json!(3));

            unsafe {
                pio_string_free(summary);
                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_out: *mut c_char = std::ptr::null_mut();
            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(),
                    &mut warn_out,
                    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 capabilities_json_reports_the_bmopf_vintage_the_writer_targets() {
            let raw = pio_dist_capabilities_json();
            assert!(!raw.is_null());
            let text = unsafe { CStr::from_ptr(raw) }.to_str().unwrap().to_owned();
            unsafe { pio_string_free(raw) };
            let caps: serde_json::Value = serde_json::from_str(&text).unwrap();

            // The vendored schema file's own `version` field must agree
            // with BMOPF_SCHEMA_VERSION.
            let vendored: serde_json::Value = serde_json::from_str(
                &std::fs::read_to_string("../tests/data/dist/bmopf/draft_bmopf_schema.json")
                    .unwrap(),
            )
            .unwrap();
            assert_eq!(vendored["version"], caps["bmopf_schema_version"]);

            assert_eq!(
                caps[powerio::version::VERSION_KEY],
                serde_json::json!(powerio::VERSION)
            );
        }

        #[test]
        fn convert_str_warns_that_the_buscoords_sidecar_was_dropped() {
            // Bus coordinates make the dss writer emit a `Buscoords`
            // directive plus the CSV it names. This surface returns text
            // only, so the CSV is dropped.
            let source = "\
New Circuit.c basekv=12.47
New Line.l1 bus1=a bus2=b phases=3
";
            let text = CString::new(source).unwrap();
            let from = CString::new("dss").unwrap();
            let to = CString::new("dss").unwrap();
            let mut warn_out: *mut c_char = std::ptr::null_mut();
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            // Convert through bmopf so the dss writer runs instead of an
            // echo of the source text.
            let bmopf_target = CString::new("bmopf").unwrap();
            let as_bmopf = unsafe {
                pio_dist_convert_str(
                    text.as_ptr(),
                    from.as_ptr(),
                    bmopf_target.as_ptr(),
                    &mut warn_out,
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(!as_bmopf.is_null());
            let bmopf_text = unsafe { CStr::from_ptr(as_bmopf) }
                .to_str()
                .unwrap()
                .to_owned();
            unsafe { pio_string_free(as_bmopf) };

            // Give the document coordinates so the dss writer produces a sidecar.
            let mut doc: serde_json::Value = serde_json::from_str(&bmopf_text).unwrap();
            if let Some(buses) = doc["bus"].as_object_mut() {
                for (i, (_, bus)) in buses.iter_mut().enumerate() {
                    bus["longitude"] = serde_json::json!(i as f64);
                    bus["latitude"] = serde_json::json!(i as f64);
                }
            }
            let with_coords = CString::new(doc.to_string()).unwrap();
            let bmopf_from = CString::new("bmopf").unwrap();
            let mut warn2_out: *mut c_char = std::ptr::null_mut();
            let s = unsafe {
                pio_dist_convert_str(
                    with_coords.as_ptr(),
                    bmopf_from.as_ptr(),
                    to.as_ptr(),
                    &mut warn2_out,
                    err.as_mut_ptr(),
                    err.len(),
                )
            };
            assert!(
                !s.is_null(),
                "{}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );
            let dss = unsafe { CStr::from_ptr(s) }.to_str().unwrap().to_owned();
            unsafe { pio_string_free(s) };
            assert!(!warn2_out.is_null(), "expected a dropped sidecar warning");
            let warnings = unsafe { CStr::from_ptr(warn2_out) }
                .to_str()
                .unwrap()
                .to_owned();
            unsafe { pio_string_free(warn2_out) };

            // Guard the premise: the writer must emit the directive, or the
            // warning assertion below proves nothing.
            assert!(
                dss.to_lowercase().contains("buscoords"),
                "expected the dss writer to reference a buscoords file; output was: {dss}"
            );
            // The text names a companion file, so a warning must name it too.
            assert!(
                warnings.contains("was not written"),
                "dss output references a buscoords file but no warning reported the drop; \
                 warnings were: {warnings}"
            );
        }

        #[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_out: *mut c_char = std::ptr::null_mut();
            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(),
                    &mut warn_out,
                    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
            // report 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_out: *mut c_char = std::ptr::null_mut();
            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(),
                    &mut warn_out,
                    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_out: *mut c_char = std::ptr::null_mut();
            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(),
                    &mut warn_out,
                    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);
        }
    }

    /// The balanced model JSON pair: one call out, one call back, byte
    /// identical to the `powerio-json` token writer.
    #[test]
    fn balanced_model_json_round_trip_matches_token_writer() {
        let net = case9();
        let mut err = [0 as c_char; PIO_ERRBUF_MIN];
        let json = unsafe { pio_to_json(net, err.as_mut_ptr(), err.len()) };
        assert!(!json.is_null());
        let text = unsafe { CStr::from_ptr(json) }.to_str().unwrap().to_owned();
        unsafe { pio_string_free(json) };
        assert_eq!(text, unsafe { to_format(net, "powerio-json") });

        let c = CString::new(text).unwrap();
        let back = unsafe { pio_from_json(c.as_ptr(), err.as_mut_ptr(), err.len()) };
        assert!(!back.is_null());
        unsafe {
            assert_eq!(pio_n_buses(back), pio_n_buses(net));
            close(pio_base_mva(back), pio_base_mva(net));
            pio_network_free(back);
            pio_network_free(net);
        }
    }

    /// `pio_classify_str` labels: same markers as the `.json` sniffing.
    #[test]
    fn classify_str_labels() {
        fn classify(text: &str) -> String {
            let c = CString::new(text).unwrap();
            let mut out = [0 as c_char; 64];
            let n = unsafe { pio_classify_str(c.as_ptr(), out.as_mut_ptr(), out.len()) };
            let label = unsafe { CStr::from_ptr(out.as_ptr()) }.to_str().unwrap();
            assert_eq!(n, label.len(), "size-then-fill length disagrees");
            label.to_string()
        }
        assert_eq!(
            classify(r#"{"baseMVA": 100.0, "bus": {}}"#),
            "transmission:powermodels-json"
        );
        assert_eq!(
            classify(r#"{"data_model": "ENGINEERING"}"#),
            "distribution:pmd-json"
        );
        assert_eq!(
            classify(r#"{"line": {}, "bus": {}}"#),
            "distribution:bmopf-json"
        );
        assert_eq!(
            classify(r#"{"model_kind": "balanced", "model": {}}"#),
            "package"
        );
        assert_eq!(classify("not json"), "unknown");
        assert_eq!(classify(r#"{"nothing": 1}"#), "unknown");
        assert_eq!(
            unsafe { pio_classify_str(std::ptr::null(), std::ptr::null_mut(), 0) },
            0
        );
    }

    /// The package inverse pair: wrap a handle, cross the JSON document, and
    /// extract an owned handle again, the binding materialization path.
    #[cfg(feature = "pkg")]
    mod package_inverse {
        use super::*;
        use std::ffi::CStr;

        unsafe fn package_round_trip(pkg: *mut PioPackage) -> *mut PioPackage {
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let json = unsafe { pio_package_to_json(pkg, err.as_mut_ptr(), err.len()) };
            assert!(!json.is_null());
            let text = unsafe { CStr::from_ptr(json) }.to_str().unwrap().to_owned();
            unsafe { pio_string_free(json) };
            let c = CString::new(text).unwrap();
            let reread = unsafe { pio_package_parse_str(c.as_ptr(), err.as_mut_ptr(), err.len()) };
            assert!(!reread.is_null());
            unsafe { pio_package_free(pkg) };
            reread
        }

        #[test]
        fn balanced_wrap_extract_across_json() {
            let net = case9();
            let mut err = [0 as c_char; PIO_ERRBUF_MIN];
            let pkg =
                unsafe { pio_package_from_balanced_network(net, 0, err.as_mut_ptr(), err.len()) };
            assert!(!pkg.is_null());

            // An in-memory extraction (no JSON crossing) sheds the retained
            // source text too: same-format writes are fresh serializations,
            // never byte echoes of the wrapped handle's source.
            unsafe {
                let mem = pio_package_to_balanced_network(pkg, err.as_mut_ptr(), err.len());
                assert!(!mem.is_null());
                assert!((*mem).net.source.is_none());
                pio_network_free(mem);
            }

            let pkg = unsafe { package_round_trip(pkg) };

            // Wrong-kind extraction refuses with a directed message.
            #[cfg(feature = "dist")]
            unsafe {
                let wrong = pio_package_to_multiconductor_network(pkg, err.as_mut_ptr(), err.len());
                assert!(wrong.is_null());
                let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
                assert!(msg.contains("balanced"), "got: {msg}");
            }

            let back = unsafe { pio_package_to_balanced_network(pkg, err.as_mut_ptr(), err.len()) };
            assert!(
                !back.is_null(),
                "{}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );
            unsafe {
                assert_eq!(pio_n_buses(back), pio_n_buses(net));
                assert_eq!(pio_n_gens(back), pio_n_gens(net));
                close(pio_base_mva(back), pio_base_mva(net));
                pio_package_free(pkg);
                pio_network_free(back);
                pio_network_free(net);
            }
        }

        #[cfg(feature = "dist")]
        #[test]
        fn dist_model_json_round_trip_matches_package_field() {
            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());

            // One call out, one call back: bmopf output survives unchanged.
            let json = unsafe { pio_dist_to_json(net, err.as_mut_ptr(), err.len()) };
            assert!(!json.is_null());
            let text = unsafe { CStr::from_ptr(json) }.to_str().unwrap().to_owned();
            unsafe { pio_string_free(json) };
            let c = CString::new(text.clone()).unwrap();
            let back = unsafe { pio_dist_from_json(c.as_ptr(), err.as_mut_ptr(), err.len()) };
            assert!(!back.is_null());

            unsafe { assert_eq!(bmopf(back), bmopf(net)) };

            // The model JSON is the same object the .pio.json document carries
            // under model.multiconductor_network.
            let pkg = unsafe {
                pio_package_from_multiconductor_network(net, err.as_mut_ptr(), err.len())
            };
            assert!(!pkg.is_null());
            let pkg_json = unsafe { pio_package_to_json(pkg, err.as_mut_ptr(), err.len()) };
            assert!(!pkg_json.is_null());
            let doc: serde_json::Value =
                serde_json::from_str(unsafe { CStr::from_ptr(pkg_json) }.to_str().unwrap())
                    .unwrap();
            let direct: serde_json::Value = serde_json::from_str(&text).unwrap();
            assert_eq!(doc["model"]["multiconductor_network"], direct);

            unsafe {
                pio_string_free(pkg_json);
                pio_package_free(pkg);
                pio_dist_network_free(back);
                pio_dist_network_free(net);
            }
        }

        #[cfg(feature = "dist")]
        #[test]
        fn multiconductor_wrap_extract_across_json() {
            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());
            let pkg = unsafe {
                pio_package_from_multiconductor_network(net, err.as_mut_ptr(), err.len())
            };
            assert!(!pkg.is_null());

            // Same in-memory strip check as the balanced side: source and the
            // defaulted provenance never survive extraction.
            unsafe {
                let mem = pio_package_to_multiconductor_network(pkg, err.as_mut_ptr(), err.len());
                assert!(!mem.is_null());
                assert!((*mem).net.source.is_none());
                assert!((*mem).net.defaulted.is_empty());
                pio_dist_network_free(mem);
            }

            let pkg = unsafe { package_round_trip(pkg) };
            let back =
                unsafe { pio_package_to_multiconductor_network(pkg, err.as_mut_ptr(), err.len()) };
            assert!(
                !back.is_null(),
                "{}",
                unsafe { CStr::from_ptr(err.as_ptr()) }.to_str().unwrap()
            );

            // The extracted model writes the same BMOPF text as the original:
            // nothing the model represents is lost crossing the package.
            unsafe {
                assert_eq!(bmopf(back), bmopf(net));
                let wrong = pio_package_to_balanced_network(pkg, err.as_mut_ptr(), err.len());
                assert!(wrong.is_null());
                let msg = CStr::from_ptr(err.as_ptr()).to_str().unwrap();
                assert!(msg.contains("multiconductor"), "got: {msg}");
                pio_package_free(pkg);
                pio_dist_network_free(back);
                pio_dist_network_free(net);
            }
        }
    }
}