Entropyk/project-context.md

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.