# Entropyk Project Context & Rules

This file serves as the system-wide foundational reference (`project-context.md`) for all AI agents working on Entropyk.

## Component Integration Process - CRITICAL RULE

When adding a new thermodynamic component, it **MUST** be fully integrated across all supported target interfaces natively. Follow this protocol:

### 1. Core Rust & Solver Representation (`crates/components`)
- **Implement Trait**: Implement `entropyk::Component` (`compute_residuals`, `jacobian_entries`, `n_equations`, `get_ports`, `signature`, `energy_transfers`).
- **Jacobian Accuracy**: The Jacobian **MUST** be exact. Do not use numerical differentiation unless explicitly requested. Verify with tests.
- **Type-State APIs**: Use `Disconnected` -> `Connected` typestate pattern for port connections (`new()` returns disconnected, `connect()` returns connected).
- **Facade Export**: Export in `crates/components/src/lib.rs` AND re-export in `crates/entropyk/src/lib.rs`.
- **Solver Constraints API**: If the component has control variables (e.g., fan speed, opening, frequency), ensure these fields can be manipulated and registered via the `embedding` / `Bounded` / `Constraint` API for inverse calibration/Eurovent rating.

### 2. CLI Integration (`crates/cli`)
- **Config Parsing**: Add a new match arm in `crates/cli/src/run.rs` inside `create_component`.
- **Parameter Extraction**: Extract required and optional parameters from JSON. Provide safe default values (e.g. `unwrap_or()`).
- **Port Resolution**: Instantiate the component using `make_connected_port` for boundaries, or the standard `Port::new(...)` -> `.connect()` pattern for N-port components. 

### 3. Python Bindings (`crates/bindings/python` via PyO3)
- **PyClass Wrapper**: Define a `#[pyclass]` structural wrapper mapping Python primitives to Rust's strong types.
- **State & Properties**: Expose getters (`#[getter]`) and setters (`#[setter]`) for variables.
- **Registration**: Register the wrapper in the PyModule definition.

### 4. WebAssembly Integration (`crates/bindings/wasm`)
- **Wasm Wrapper**: Create a `#[wasm_bindgen]` wrapper.
- **Methods**: Expose state mutation methods to JS using `#[wasm_bindgen]`, mapping complex types to strings/f64s.