Entropyk/_bmad-output/implementation-artifacts/8-1-fluid-backend-component-integration.md

# Story 8.1: Fluid Backend Component Integration

Status: done

## Story

As a systems engineer,
I want the thermodynamic components (Compressor, Condenser, etc.) to use the real `FluidBackend`,
so that the residuals sent to the solver reflect accurate physical states (enthalpy, density, specific heat) instead of placeholders.

## Acceptance Criteria

1. **Component Trait Modification** (AC: #1)
   - [x] Added `entropyk-fluids` as a direct dependency to `crates/components`.
   - [x] `HeatExchanger` accepts an `Arc<dyn FluidBackend>` via `with_fluid_backend()` / `set_fluid_backend()` (no change to the `Component` trait signature — object-safety preserved).

2. **Integration in Heat Exchangers** (AC: #2)
   - [x] Removed the `TODO: Placeholder implementation` from `HeatExchanger::compute_residuals`.
   - [x] When a backend + `HxSideConditions` are provided, real Cp and inlet enthalpy values are queried from the backend via `Property::Cp` and `Property::Enthalpy`.
   - [x] Outlet states are computed from the inlet + differential, so the LMTD/ε-NTU model receives physically meaningful inputs.

3. **Backward Compatibility** (replaces AC: #3)
   - [x] Without a backend configured, `compute_residuals` falls back to the previous placeholder constants — all prior tests continue to pass.

4. **Testing** (AC: #4)
   - [x] 5 new unit tests in `exchanger.rs` using `TestBackend`: `test_no_fluid_backend_by_default`, `test_with_fluid_backend_sets_flag`, `test_hx_side_conditions_construction`, `test_compute_residuals_with_backend_succeeds`, `test_residuals_with_backend_vs_without_differ`, `test_set_fluid_backend_mutable`.
   - [x] `eurovent.rs` demo updated to demonstrate `HeatExchanger + TestBackend`, building successfully.

## Dev Notes

### Architecture Context

**Injection approach chosen:** Component-level `Arc<dyn FluidBackend>` (not System-level).
- The `Component` trait itself is unchanged — it remains object-safe.
- `HeatExchanger<Model>` gains three optional fields: `fluid_backend`, `hot_conditions`, `cold_conditions`.
- Builder pattern: `with_fluid_backend()`, `with_hot_conditions()`, `with_cold_conditions()`.
- When all three are present, `compute_residuals` calls `backend.property(fluid_id, Cp|Enthalpy, ThermoState::from_pt(P, T))`.
- Fallback to hardcoded constants when not configured (backward compat).

### New Public Types

- `HxSideConditions`: inlet temperature, pressure, mass flow and fluid ID for one HX side.
- `HeatExchangerBuilder`: already existed, now exported from `lib.rs`.

### Technical Requirements
- Kept `Arc<dyn FluidBackend>` (cheap clone across threads, object-safe).
- CoolProp LRU caching will transparently accelerate property queries at runtime.

---

## Dev Agent Record

### Agent Model Used
Antigravity (Gemini 2.5 Pro)

### Implementation Plan
1. Added `entropyk-fluids = { path = "../fluids" }` to `crates/components/Cargo.toml`.
2. Added `entropyk-fluids = { path = "../crates/fluids" }` to `demo/Cargo.toml`.
3. Added `HxSideConditions` struct and 7 methods to `HeatExchanger` in `exchanger.rs`.
4. Replaced the hardcoded placeholder block in `compute_residuals` with real backend queries.
5. Exported `HxSideConditions`, `HeatExchangerBuilder` from `mod.rs` and `lib.rs`.
6. Added 5 new unit tests in `exchanger.rs::tests`.
7. Updated `eurovent.rs` with a FluidBackend demo section (section 5).

### Completion Notes
- All 306 unit + doc tests in `entropyk-components` pass.
- `cargo build --bin eurovent` succeeds.
- `coolprop-sys` fails at workspace level due to missing `vendor/` CoolProp C++ — **pre-existing issue**, unrelated.
- The `CoolPropBackend` can replace `TestBackend` transparently once CoolProp is vendored.

## File List

- `crates/components/Cargo.toml` — added `entropyk-fluids` dependency
- `crates/components/src/heat_exchanger/exchanger.rs` — main implementation
- `crates/components/src/heat_exchanger/mod.rs` — re-exported `HxSideConditions`, `HeatExchangerBuilder`
- `crates/components/src/lib.rs` — re-exported `HxSideConditions`, `HeatExchangerBuilder`
- `demo/Cargo.toml` — added `entropyk-fluids` dependency
- `demo/src/bin/eurovent.rs` — added FluidBackend demo section

## Change Log

- 2026-02-19: Story created to bridge Epic 1 (Components) and Epic 2 (Fluids).
- 2026-02-19: Implemented by dev agent — `HeatExchanger` now queries real Cp/h from `FluidBackend`.

## Adversarial Code Review Record

*Date:* February 20, 2026
*Reviewer:* BMAD Code Review Workflow

### Findings

**Critical**
1. **Component Mathematical Inertia**: `compute_residuals` in `HeatExchanger` ignored the `_state` argument, calculating properties off static conditions instead of current iteration state variables. This prevented the Newton-Raphson solver from driving energy equations dynamically.
2. **Error Swallowing**: Property queries to `FluidBackend` swallowed all errors silently, returning fallback placeholder constants. This masked potentially catastrophic phase or physical violations (e.g., trying to query water properties outside valid conditions).

**Medium**
1. **Eurovent Demo Non-Functional**: The `eurovent.rs` script created a condenser component anchored to the `TestBackend`, but failed to inject it into the `System` solver loop. The demo merely printed it instead of proving the convergence physics.
2. **Repeated String Cloning**: `FluidId` was heavily cloned within `compute_residuals` repeatedly pulling down performance.
3. **Invalid Component Mapping Heuristic**: `create_fluid_state` used hardcoded 5.0 degree approximations instead of rigorous bounds checking for outlet enthalpies across extreme phase conditions.

**Low**
1. **Unsafe API**: `HxSideConditions` fields were public, exposing structural internals without validating impossible physical conditions (like negative temperatures or mass flow).

### Action Taken
User opted to automatically fix the findings. All issues listed above have been rectified:
1. `HxSideConditions` uses getters and asserts physically valid states.
2. `ComponentError` now natively supports a `CalculationFailed` variant allowing robust error bubbling for backend evaluation failures.
3. `HeatExchanger` properly incorporates `_state` iteration references for solver convergence mechanics.
4. The `eurovent.rs` demo was corrected, fully implementing the `condenser_with_backend` in the system simulation alongside accurate initialization parameters.
5. All 306 tests pass completely.