powerio-pkg 0.4.0

The .pio.json compiler package: a versioned envelope around one PowerIO IR payload with explicit model kind, provenance, source maps, structured diagnostics, validation, and lowering history.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# powerio-pkg

The `.pio.json` compiler package: a versioned envelope around one PowerIO IR
payload.

PowerIO has no single flattened "universal network" struct. It keeps two
concrete static-grid IR families distinct:

- `powerio::BalancedNetwork` — the scalar positive-sequence transmission model
  (historically `powerio::Network`);
- `powerio_dist::MulticonductorNetwork` — the wire-coordinate distribution model
  (historically `powerio_dist::DistNetwork`).

A `CompilerPackage` wraps exactly one of those payloads at a time and carries the
metadata a compiler artifact needs to be trustworthy:

- an explicit `model_kind` (never inferred from which field is present);
- `producer` and `origin` metadata;
- `sources` and `source_maps` (which canonical field came from which source
  record, by what `mapping_kind`);
- structured `diagnostics` with stable codes;
- a `validation` summary;
- `lowering_history`;
- optional `derived` metadata for matrix stats, normalized solver table
  identities, and cache keys.

It serializes to `.pio.json`. Binary `.pio` is out of scope until the JSON
package stabilizes.

See `docs/src/compiler-ir.md` and `docs/src/pio-json-schema.md` in the
repository root.

```rust
use powerio_pkg::{CompilerPackage, ModelKind};

let net = powerio::BalancedNetwork::in_memory("demo", 100.0, vec![], vec![]);
let pkg = CompilerPackage::from_balanced(net);
assert_eq!(pkg.model_kind(), ModelKind::Balanced);
assert!(pkg.kind_is_consistent());

let json = pkg.to_json_pretty().unwrap();
let back = CompilerPackage::from_json(&json).unwrap();
assert_eq!(back.model_kind(), ModelKind::Balanced);
```

Balanced packages can record the dense normalized solver table contract without
embedding every table row:

```rust
let net = powerio::parse_str("...", "matpower").unwrap().network;
let mut pkg = CompilerPackage::from_balanced(net);
pkg.attach_normalized_solver_table_metadata().unwrap();
```