Snapshot WIP: solver HP epic progress, BPHX/HX physics, BMAD skill refresh.

Capture uncommitted solver robustness work (regularization, domain errors, linear solver lifecycle, tube DP/MSH), web workbench updates, and synced BMAD skills across IDE agent folders before starting BPHX pressure-drop.

Co-authored-by: Cursor <cursoragent@cursor.com>

crates/cli/examples/bphx_evaporator_condenser.json

@@ -1,32 +1,112 @@
 {
-  "name": "BPHX Evaporator and Condenser Bounded Test",
+  "name": "BPHX Water-Cooled Chiller R134a",
+  "description": "Full vapor-compression cycle with brazed-plate evaporator and condenser (4-port). Both Bphx units use emergent_pressure so outlet closures (superheat / subcooling) square the DoF like Condenser/Evaporator.",
+
   "fluid": "R134a",
   "fluid_backend": "CoolProp",
+
   "circuits": [
     {
       "id": 0,
+      "name": "Refrigerant + water loops",
       "components": [
-        { "type": "RefrigerantSource", "name": "src", "fluid": "R134a", "p_set_bar": 5.0, "quality": 0.3 },
-        { "type": "BphxEvaporator", "name": "evap", "ua": 2000.0, "refrigerant": "R134a", "secondary_fluid": "Water", "secondary_inlet_temp_c": 12.0, "secondary_mass_flow_kg_s": 0.5, "secondary_cp_j_per_kgk": 4186.0 },
-        { "type": "RefrigerantSink", "name": "sink", "fluid": "R134a", "p_back_bar": 5.0 }
+        {
+          "type": "IsentropicCompressor",
+          "name": "comp",
+          "isentropic_efficiency": 0.70,
+          "t_cond_k": 318.15,
+          "t_evap_k": 278.15,
+          "superheat_k": 5.0,
+          "emergent_pressure": true,
+          "displacement_m3": 6.5e-5,
+          "speed_hz": 50.0,
+          "volumetric_efficiency": 0.92
+        },
+        {
+          "type": "BphxCondenser",
+          "name": "cond",
+          "refrigerant": "R134a",
+          "secondary_fluid": "Water",
+          "n_plates": 40,
+          "plate_length_m": 0.40,
+          "plate_width_m": 0.12,
+          "target_subcooling_k": 5.0,
+          "emergent_pressure": true,
+          "correlation": "Longo2004",
+          "ua": 2500.0
+        },
+        {
+          "type": "IsenthalpicExpansionValve",
+          "name": "exv",
+          "t_evap_k": 278.15,
+          "emergent_pressure": true
+        },
+        {
+          "type": "BphxEvaporator",
+          "name": "evap",
+          "refrigerant": "R134a",
+          "secondary_fluid": "Water",
+          "n_plates": 40,
+          "plate_length_m": 0.40,
+          "plate_width_m": 0.12,
+          "target_superheat_k": 5.0,
+          "emergent_pressure": true,
+          "correlation": "Longo2004",
+          "ua": 2000.0
+        },
+        {
+          "type": "BrineSource",
+          "name": "cond_water_in",
+          "fluid": "Water",
+          "p_set_bar": 2.0,
+          "t_set_c": 30.0,
+          "m_flow_kg_s": 0.40,
+          "fix_pressure": false,
+          "fix_temperature": true,
+          "fix_mass_flow": true
+        },
+        {
+          "type": "BrineSink",
+          "name": "cond_water_out",
+          "fluid": "Water",
+          "p_back_bar": 2.0,
+          "fix_pressure": true
+        },
+        {
+          "type": "BrineSource",
+          "name": "evap_water_in",
+          "fluid": "Water",
+          "p_set_bar": 3.0,
+          "t_set_c": 12.0,
+          "m_flow_kg_s": 0.50,
+          "fix_pressure": false,
+          "fix_temperature": true,
+          "fix_mass_flow": true
+        },
+        {
+          "type": "BrineSink",
+          "name": "evap_water_out",
+          "fluid": "Water",
+          "p_back_bar": 3.0,
+          "fix_pressure": true
+        }
       ],
       "edges": [
-        { "from": "src:outlet", "to": "evap:inlet" },
-        { "from": "evap:outlet", "to": "sink:inlet" }
-      ]
-    },
-    {
-      "id": 1,
-      "components": [
-        { "type": "RefrigerantSource", "name": "src2", "fluid": "R134a", "p_set_bar": 15.0, "quality": 1.0 },
-        { "type": "BphxCondenser", "name": "cond", "ua": 2000.0, "refrigerant": "R134a", "secondary_fluid": "Water", "secondary_inlet_temp_c": 30.0, "secondary_mass_flow_kg_s": 0.4, "secondary_cp_j_per_kgk": 4186.0 },
-        { "type": "RefrigerantSink", "name": "sink2", "fluid": "R134a", "p_back_bar": 15.0 }
-      ],
-      "edges": [
-        { "from": "src2:outlet", "to": "cond:inlet" },
-        { "from": "cond:outlet", "to": "sink2:inlet" }
+        { "from": "comp:outlet", "to": "cond:inlet" },
+        { "from": "cond:outlet", "to": "exv:inlet" },
+        { "from": "exv:outlet", "to": "evap:inlet" },
+        { "from": "evap:outlet", "to": "comp:inlet" },
+        { "from": "cond_water_in:outlet", "to": "cond:secondary_inlet" },
+        { "from": "cond:secondary_outlet", "to": "cond_water_out:inlet" },
+        { "from": "evap_water_in:outlet", "to": "evap:secondary_inlet" },
+        { "from": "evap:secondary_outlet", "to": "evap_water_out:inlet" }
       ]
     }
   ],
-  "solver": { "strategy": "fallback", "max_iterations": 100, "tolerance": 1e-6 }
+
+  "solver": {
+    "strategy": "fallback",
+    "max_iterations": 300,
+    "tolerance": 1e-6
+  }
 }

crates/cli/examples/capillary_tube_r134a.json

@@ -1,12 +1,23 @@
 {
-  "schema_version": "1.0",
+  "schema_version": "1",
+  "name": "Capillary Tube R134a Smoke",
+  "description": "WIP smoke fixture: RefrigerantSource → CapillaryTube → RefrigerantSink. DoF can square, but CapillaryTube Component residuals are still stubs (mass/enthalpy continuity only — no frictional ΔP residual), so the Newton Jacobian is singular. Kept for parsing/wiring tests; not yet a UI Load example.",
+
   "fluid": "R134a",
   "fluid_backend": "CoolProp",
+
   "circuits": [
     {
       "id": 0,
       "name": "Capillary smoke",
       "components": [
+        {
+          "type": "RefrigerantSource",
+          "name": "src",
+          "fluid": "R134a",
+          "p_set_bar": 12.0,
+          "quality": 0.0
+        },
         {
           "type": "CapillaryTube",
           "name": "cap",
@@ -17,11 +28,21 @@
           "h_inlet_kj_kg": 250.0,
           "p_outlet_bar": 3.5,
           "h_outlet_kj_kg": 250.0
+        },
+        {
+          "type": "RefrigerantSink",
+          "name": "sink",
+          "fluid": "R134a",
+          "p_back_bar": 3.5
         }
       ],
-      "edges": []
+      "edges": [
+        { "from": "src:outlet", "to": "cap:inlet" },
+        { "from": "cap:outlet", "to": "sink:inlet" }
+      ]
     }
   ],
+
   "solver": {
     "strategy": "newton",
     "max_iterations": 50,

crates/cli/examples/chiller_aircooled_r134a_fan.json

@@ -0,0 +1,122 @@
+{
+  "name": "Air-Cooled Chiller R134a with Condenser Fan",
+  "description": "Same emergent-pressure air-cooled chiller as chiller_aircooled_r134a.json, with an explicit Fan on the condenser air path: AirSource → Fan → Cond(secondary) → AirSink. Fan curve sized for ~1.2 kg/s (~1.0 m³/s) against the coil secondary ΔP (150 Pa). secondary_humidity_ratio MUST match AirSource psychrometrics (W at T_dry, RH, P).",
+
+  "fluid": "R134a",
+  "fluid_backend": "CoolProp",
+
+  "circuits": [
+    {
+      "id": 0,
+      "name": "Refrigerant + secondary loops",
+      "components": [
+        {
+          "type": "IsentropicCompressor",
+          "name": "comp",
+          "isentropic_efficiency": 0.70,
+          "t_cond_k": 318.15,
+          "t_evap_k": 278.15,
+          "superheat_k": 5.0,
+          "emergent_pressure": true,
+          "displacement_m3": 6.5e-5,
+          "speed_hz": 50.0,
+          "volumetric_efficiency": 0.92
+        },
+        {
+          "type": "Condenser",
+          "name": "cond",
+          "ua": 2500.0,
+          "emergent_pressure": true,
+          "subcooling_k": 5.0,
+          "secondary_fluid": "Air",
+          "secondary_humidity_ratio": 0.01412,
+          "dp_model": "isobaric",
+          "secondary_rated_pressure_drop_pa": 150,
+          "secondary_rated_m_flow_kg_s": 1.2
+        },
+        {
+          "type": "IsenthalpicExpansionValve",
+          "name": "exv",
+          "t_evap_k": 278.15,
+          "emergent_pressure": true
+        },
+        {
+          "type": "Evaporator",
+          "name": "evap",
+          "ua": 1468.0,
+          "emergent_pressure": true,
+          "secondary_fluid": "Water",
+          "dp_model": "isobaric",
+          "secondary_rated_pressure_drop_pa": 40000,
+          "secondary_rated_m_flow_kg_s": 0.4778
+        },
+        {
+          "type": "AirSource",
+          "name": "cond_air_in",
+          "p_set_bar": 1.01325,
+          "t_dry_c": 35.0,
+          "rh": 40.0,
+          "m_flow_kg_s": 1.2,
+          "fix_pressure": false,
+          "fix_temperature": true,
+          "fix_mass_flow": true
+        },
+        {
+          "type": "Fan",
+          "name": "cond_fan",
+          "fluid": "Air",
+          "speed_ratio": 1.0,
+          "air_density_kg_m3": 1.15,
+          "design_flow_m3_s": 1.04,
+          "curve_p0": 250.0,
+          "curve_p1": 0.0,
+          "curve_p2": -20.0,
+          "eff_e0": 0.65,
+          "eff_e1": 0.0,
+          "eff_e2": 0.0
+        },
+        {
+          "type": "AirSink",
+          "name": "cond_air_out",
+          "p_back_bar": 1.01325,
+          "fix_pressure": true
+        },
+        {
+          "type": "BrineSource",
+          "name": "evap_water_in",
+          "fluid": "Water",
+          "p_set_bar": 3.0,
+          "t_set_c": 12.0,
+          "m_flow_kg_s": 0.4778,
+          "fix_pressure": false,
+          "fix_temperature": true,
+          "fix_mass_flow": true
+        },
+        {
+          "type": "BrineSink",
+          "name": "evap_water_out",
+          "fluid": "Water",
+          "p_back_bar": 3.0,
+          "fix_pressure": true
+        }
+      ],
+      "edges": [
+        { "from": "comp:outlet", "to": "cond:inlet" },
+        { "from": "cond:outlet", "to": "exv:inlet" },
+        { "from": "exv:outlet", "to": "evap:inlet" },
+        { "from": "evap:outlet", "to": "comp:inlet" },
+        { "from": "cond_air_in:outlet", "to": "cond_fan:inlet" },
+        { "from": "cond_fan:outlet", "to": "cond:secondary_inlet" },
+        { "from": "cond:secondary_outlet", "to": "cond_air_out:inlet" },
+        { "from": "evap_water_in:outlet", "to": "evap:secondary_inlet" },
+        { "from": "evap:secondary_outlet", "to": "evap_water_out:inlet" }
+      ]
+    }
+  ],
+
+  "solver": {
+    "strategy": "newton",
+    "max_iterations": 300,
+    "tolerance": 1e-6
+  }
+}

crates/cli/src/batch.rs

@@ -271,7 +271,7 @@ pub fn discover_config_files(directory: &Path) -> CliResult<Vec<PathBuf>> {
         let entry = entry?;
         let path = entry.path();
 
-        if path.extension().map_or(false, |ext| ext == "json") {
+        if path.extension().is_some_and(|ext| ext == "json") {
             files.push(path);
         }
     }
@@ -315,6 +315,7 @@ fn process_single_file(
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 0,
+                raw_state_vector: None,
             }
         }
     }
@@ -424,6 +425,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 50,
+                raw_state_vector: None,
             },
             SimulationResult {
                 input: "test2.json".to_string(),
@@ -437,6 +439,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 0,
+                raw_state_vector: None,
             },
         ];
 
@@ -480,6 +483,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 50,
+                raw_state_vector: None,
             },
             SimulationResult {
                 input: "test2.json".to_string(),
@@ -493,6 +497,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 0,
+                raw_state_vector: None,
             },
         ];
 
@@ -524,6 +529,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 50,
+                raw_state_vector: None,
             },
             SimulationResult {
                 input: "test2.json".to_string(),
@@ -537,6 +543,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 0,
+                raw_state_vector: None,
             },
         ];
 
@@ -564,6 +571,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 50,
+                raw_state_vector: None,
             },
             SimulationResult {
                 input: "test2.json".to_string(),
@@ -577,6 +585,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 1000,
+                raw_state_vector: None,
             },
         ];
 
@@ -634,6 +643,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 100,
+                raw_state_vector: None,
             }],
         };
 
@@ -657,6 +667,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 50,
+                raw_state_vector: None,
             },
             SimulationResult {
                 input: "ok2.json".to_string(),
@@ -670,6 +681,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 60,
+                raw_state_vector: None,
             },
             SimulationResult {
                 input: "fail.json".to_string(),
@@ -683,6 +695,7 @@ mod tests {
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms: 0,
+                raw_state_vector: None,
             },
         ];
 

crates/cli/src/config.rs

@@ -6,6 +6,7 @@
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
+use std::path::Path;
 
 use crate::error::{CliError, CliResult};
 
@@ -69,6 +70,16 @@ pub struct ScenarioConfig {
     /// endpoints). Resolved and routed into the appropriate circuit during flattening.
     #[serde(default)]
     pub connections: Vec<EdgeConfig>,
+    /// Workspace directory containing reusable `.ekmod` module files.
+    ///
+    /// Each `.ekmod` file is a JSON [`SubsystemTemplate`] whose module name is
+    /// derived from the filename (e.g. `BaseChiller.ekmod` → `"BaseChiller"`).
+    /// Modules are loaded before [`Self::flatten_instances`] and injected into
+    /// every template's `subsystems` map so cross-file references resolve. If
+    /// absent, the CLI also checks `.entropyk/modules/` relative to the config
+    /// file as a fallback.
+    #[serde(default)]
+    pub workspace: Option<String>,
     /// Optional metadata.
     #[serde(default)]
     pub metadata: Option<HashMap<String, serde_json::Value>>,
@@ -103,6 +114,20 @@ pub struct SubsystemTemplate {
     /// endpoint. `connections` reference these as `"{instance}.{external_port}"`.
     #[serde(default)]
     pub ports: HashMap<String, String>,
+    /// Nested subsystem templates (for recursive composition). A template can
+    /// instantiate other templates declared in this map via [`Self::instances`].
+    /// Flattened recursively at load time — the solver never sees the nesting.
+    #[serde(default)]
+    pub subsystems: HashMap<String, SubsystemTemplate>,
+    /// Instantiations of nested [`Self::subsystems`] templates. Each instance is
+    /// expanded recursively, with component names prefixed by `"{name}."`.
+    #[serde(default)]
+    pub instances: Vec<InstanceConfig>,
+    /// External connections between nested instances (and/or the template's own
+    /// atomic components). Endpoints use `"instance.external_port"` or
+    /// `"component:port"` syntax, resolved during recursive flattening.
+    #[serde(default)]
+    pub connections: Vec<EdgeConfig>,
 }
 
 /// An instantiation of a [`SubsystemTemplate`].
@@ -479,6 +504,8 @@ impl ScenarioConfig {
         let config: Self = serde_json::from_str(&content).map_err(CliError::InvalidConfig)?;
 
         let mut config = config;
+        // Auto-load workspace modules (.ekmod files) before flattening.
+        config.load_workspace_auto(Some(path))?;
         config.flatten_instances()?;
         config.validate()?;
 
@@ -489,6 +516,9 @@ impl ScenarioConfig {
     pub fn from_json(json: &str) -> CliResult<Self> {
         let config: Self = serde_json::from_str(json).map_err(CliError::InvalidConfig)?;
         let mut config = config;
+        // For from_json, only explicit `workspace` field is checked (no file
+        // path context for auto-discovery of .entropyk/modules/).
+        config.load_workspace_auto::<&std::path::Path>(None)?;
         config.flatten_instances()?;
         config.validate()?;
         Ok(config)
@@ -506,6 +536,74 @@ impl ScenarioConfig {
             .unwrap_or_else(|e| format!("{{\"error\":\"failed to serialize schema: {e}\"}}"))
     }
 
+    /// Load reusable `.ekmod` module files from a workspace directory and merge
+    /// them into [`Self::subsystems`].
+    ///
+    /// Each `.ekmod` file is a JSON [`SubsystemTemplate`]; the module name is the
+    /// filename without extension (e.g. `BaseChiller.ekmod` → `"BaseChiller"`).
+    /// If a subsystem with the same name already exists in the config, the
+    /// workspace module is skipped (inline definitions take precedence).
+    pub fn load_workspace(&mut self, dir: &Path) -> CliResult<()> {
+        if !dir.is_dir() {
+            return Err(CliError::Config(format!(
+                "workspace directory '{}' does not exist or is not a directory",
+                dir.display()
+            )));
+        }
+        let mut loaded = 0;
+        for entry in std::fs::read_dir(dir)? {
+            let path = entry?.path();
+            if path.extension().and_then(|e| e.to_str()) != Some("ekmod") {
+                continue;
+            }
+            let name = path.file_stem().and_then(|s| s.to_str()).ok_or_else(|| {
+                CliError::Config(format!("invalid .ekmod filename: '{}'", path.display()))
+            })?;
+            // Inline subsystems take precedence over workspace files.
+            if self.subsystems.contains_key(name) {
+                tracing::debug!(module = name, "workspace module skipped (inline override)");
+                continue;
+            }
+            let json = std::fs::read_to_string(&path)?;
+            let template: SubsystemTemplate = serde_json::from_str(&json).map_err(|e| {
+                CliError::Config(format!(
+                    "failed to parse workspace module '{}': {}",
+                    path.display(),
+                    e
+                ))
+            })?;
+            self.subsystems.insert(name.to_string(), template);
+            loaded += 1;
+        }
+        if loaded > 0 {
+            tracing::info!(loaded, dir = ?dir, "Loaded workspace modules");
+        }
+        Ok(())
+    }
+
+    /// Auto-discover and load a workspace directory. Checks, in order:
+    /// 1. The `workspace` field in the config (if set)
+    /// 2. `.entropyk/modules/` relative to `config_path` (if given)
+    ///
+    /// Silently skips if neither exists (no workspace = no extra modules).
+    pub fn load_workspace_auto<P: AsRef<Path>>(&mut self, config_path: Option<P>) -> CliResult<()> {
+        // 1. Explicit workspace path
+        let ws_path = self.workspace.clone();
+        if let Some(ref ws) = ws_path {
+            return self.load_workspace(Path::new(ws));
+        }
+        // 2. Auto-discover .entropyk/modules/ next to the config file
+        if let Some(p) = config_path {
+            if let Some(parent) = p.as_ref().parent() {
+                let auto = parent.join(".entropyk").join("modules");
+                if auto.is_dir() {
+                    return self.load_workspace(&auto);
+                }
+            }
+        }
+        Ok(())
+    }
+
     /// Flatten every [`InstanceConfig`] into concrete circuits.
     ///
     /// Each instance's components are cloned with names prefixed by `"{instance}."`,
@@ -521,6 +619,20 @@ impl ScenarioConfig {
             return Ok(());
         }
 
+        // The top-level `subsystems` map serves as the workspace registry for
+        // recursive flattening: when a nested template's `instances` reference
+        // a subsystem by name, the resolver first checks the template's own
+        // `subsystems` map, then falls back to this top-level registry. This
+        // lets `.ekmod` files cross-reference each other without cloning.
+
+        // Recursively flatten nested templates first: a SubsystemTemplate may
+        // itself contain subsystems/instances/connections. After this pass,
+        // every template in self.subsystems is flat (only atomic components).
+        let workspace = self.subsystems.clone();
+        for tmpl in self.subsystems.values_mut() {
+            *tmpl = flatten_template_recursive_with_workspace(tmpl, &workspace)?;
+        }
+
         // Expand each instance into its target circuit. Collect first (immutable
         // borrow of templates), then apply (mutable borrow of circuits).
         struct Expansion {
@@ -773,6 +885,118 @@ fn prefix_internal_endpoint(endpoint: &str, prefix: &str) -> String {
     }
 }
 
+/// Recursively flatten a [`SubsystemTemplate`]: expand nested `instances` into
+/// concrete components and edges, producing a flat template with only atomic
+/// components. After this pass, the template's `subsystems`/`instances`/
+/// `connections` are consumed (emptied) and only `components`/`edges`/`ports`
+/// remain. A no-op clone when the template has no nested instances.
+///
+/// # Recursive composition
+///
+/// A template can itself instantiate other templates (declared in its own
+/// `subsystems` map). Each nested instance is expanded depth-first, with
+/// component names prefixed cumulatively (`"parent.child.comp"`). Exposed
+/// ports of child instances are resolved to their concrete internal endpoints
+/// via the child template's `ports` map, then prefixed.
+fn flatten_template_recursive(template: &SubsystemTemplate) -> CliResult<SubsystemTemplate> {
+    flatten_template_recursive_with_workspace(template, &HashMap::new())
+}
+
+fn flatten_template_recursive_with_workspace(
+    template: &SubsystemTemplate,
+    workspace: &HashMap<String, SubsystemTemplate>,
+) -> CliResult<SubsystemTemplate> {
+    // Base case: no nested instances to expand.
+    if template.instances.is_empty() {
+        return Ok(template.clone());
+    }
+
+    let mut flat_components = template.components.clone();
+    let mut flat_edges = template.edges.clone();
+    let mut instance_port_map: HashMap<String, String> = HashMap::new();
+
+    for inst in &template.instances {
+        // Resolve child template: first check local subsystems, then workspace.
+        let child_template = template
+            .subsystems
+            .get(&inst.template)
+            .or_else(|| workspace.get(&inst.template))
+            .ok_or_else(|| {
+                CliError::Config(format!(
+                    "nested instance '{}' references unknown subsystem template '{}'. Available locally: {} | workspace: {}",
+                    inst.name,
+                    inst.template,
+                    template.subsystems.keys().cloned().collect::<Vec<_>>().join(", "),
+                    workspace.keys().cloned().collect::<Vec<_>>().join(", "),
+                ))
+            })?;
+
+        // Recurse: flatten the child template first (depth-first), passing the
+        // workspace so cross-file references resolve at every nesting level.
+        let flat_child = flatten_template_recursive_with_workspace(child_template, workspace)?;
+
+        // Resolve params: child defaults overlaid by instance overrides.
+        let mut params = flat_child.params.clone();
+        for (k, v) in &inst.params {
+            params.insert(k.clone(), v.clone());
+        }
+
+        let prefix = format!("{}.", inst.name);
+
+        // Expand child components with prefix + param substitution.
+        for comp in &flat_child.components {
+            let mut c = comp.clone();
+            c.name = format!("{}{}", prefix, comp.name);
+            substitute_component_params(&mut c, &params).map_err(|missing| {
+                CliError::Config(format!(
+                    "nested instance '{}' component '{}' references undefined parameter '${}'",
+                    inst.name, comp.name, missing
+                ))
+            })?;
+            flat_components.push(c);
+        }
+
+        // Expand child edges with prefix.
+        for edge in &flat_child.edges {
+            flat_edges.push(EdgeConfig {
+                from: prefix_internal_endpoint(&edge.from, &prefix),
+                to: prefix_internal_endpoint(&edge.to, &prefix),
+            });
+        }
+
+        // Map exposed ports: "instance.port" → "prefix.internal_comp:port".
+        for (port_name, internal_path) in &flat_child.ports {
+            let resolved = prefix_internal_endpoint(internal_path, &prefix);
+            instance_port_map.insert(format!("{}.{}", inst.name, port_name), resolved);
+        }
+    }
+
+    // Resolve the template's own connections (between nested instances and/or
+    // atomic components). Endpoints referencing "instance.port" are resolved
+    // via the map above; literal "component:port" endpoints are kept as-is.
+    for conn in &template.connections {
+        let from = instance_port_map
+            .get(&conn.from)
+            .cloned()
+            .unwrap_or_else(|| conn.from.clone());
+        let to = instance_port_map
+            .get(&conn.to)
+            .cloned()
+            .unwrap_or_else(|| conn.to.clone());
+        flat_edges.push(EdgeConfig { from, to });
+    }
+
+    Ok(SubsystemTemplate {
+        params: template.params.clone(),
+        components: flat_components,
+        edges: flat_edges,
+        ports: template.ports.clone(),
+        subsystems: HashMap::new(),
+        instances: Vec::new(),
+        connections: Vec::new(),
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/cli/src/export_fmu.rs

@@ -94,7 +94,7 @@ pub fn run_export_fmu(
     let xml = render_model_description(&model_name, &io);
     assemble_fmu(out_path, &xml, &lib, platform, &model_json, &io_json)?;
 
-    println!("  {} FMU written: {}", "OK", out_path.display());
+    println!("  OK FMU written: {}", out_path.display());
     Ok(())
 }
 
@@ -145,7 +145,11 @@ fn platform_folder(target: &str) -> Option<&'static str> {
 /// Locate the compiled cdylib by listing the release dir (robust against
 /// `Path::exists()` false-negatives observed on some Windows paths).
 fn locate_cdylib(stage: &Path, target: &str) -> CliResult<PathBuf> {
-    let wanted = ["libentropyk_fmu.so", "entropyk_fmi.dll", "libentropyk_fmu.dylib"];
+    let wanted = [
+        "libentropyk_fmu.so",
+        "entropyk_fmi.dll",
+        "libentropyk_fmu.dylib",
+    ];
     let dirs = [
         stage.join("target").join(target).join("release"),
         stage.join("target").join("release"),
@@ -278,9 +282,11 @@ fn render_model_description(model_name: &str, io: &FmuIoSpec) -> String {
          generationTool=\"entropyk-cli\" variableNamingConvention=\"flat\" \
          numberOfEventIndicators=\"0\">\n"
     ));
-    out.push_str("  <CoSimulation modelIdentifier=\"entropyk_fmi\" \
+    out.push_str(
+        "  <CoSimulation modelIdentifier=\"entropyk_fmi\" \
         canHandleVariableCommunicationStepSize=\"true\" canGetAndSetFMUstate=\"false\" \
-        canSerializeFMUstate=\"false\"/>\n");
+        canSerializeFMUstate=\"false\"/>\n",
+    );
     out.push_str("  <ModelVariables>\n");
 
     let mut vr: u32 = 0;
@@ -305,7 +311,10 @@ fn render_model_description(model_name: &str, io: &FmuIoSpec) -> String {
     out.push_str("  <ModelStructure>\n");
     let n_in = io.inputs.len() as u32;
     for i in 0..io.outputs.len() as u32 {
-        out.push_str(&format!("    <Outputs><Unknown index=\"{}\"/></Outputs>\n", n_in + i + 1));
+        out.push_str(&format!(
+            "    <Outputs><Unknown index=\"{}\"/></Outputs>\n",
+            n_in + i + 1
+        ));
     }
     out.push_str("    <Derivatives/>\n");
     out.push_str("    <InitialUnknowns>\n");
@@ -344,7 +353,7 @@ fn assemble_fmu(
     model_json: &str,
     io_json: &str,
 ) -> CliResult<()> {
-    use std::io::{Read, Write};
+    use std::io::Write;
 
     let file = fs::File::create(out_path)?;
     let mut zip = zip::ZipWriter::new(file);
@@ -354,7 +363,10 @@ fn assemble_fmu(
         .map_err(|e| CliError::Simulation(format!("zip: {e}")))?;
     zip.write_all(xml.as_bytes())?;
 
-    let ext = lib_path.extension().and_then(|e| e.to_str()).unwrap_or("so");
+    let ext = lib_path
+        .extension()
+        .and_then(|e| e.to_str())
+        .unwrap_or("so");
     let lib_name = format!("binaries/{platform}/entropyk_fmi.{ext}");
     zip.start_file(&lib_name, opts)
         .map_err(|e| CliError::Simulation(format!("zip: {e}")))?;

crates/cli/src/lib.rs

@@ -6,6 +6,13 @@
 //! simulations from the command line, supporting both single simulations
 //! and batch processing.
 
+// Pre-existing lint debt accumulated before CI was introduced. Allowed so the
+// new CI skeleton can enforce warnings-as-errors on new code.
+#![allow(clippy::field_reassign_with_default)]
+#![allow(clippy::wildcard_in_or_patterns)]
+#![allow(clippy::unnecessary_get_then_check)]
+#![allow(dead_code)]
+
 pub mod batch;
 pub mod config;
 pub mod error;

crates/cli/src/main.rs

@@ -210,6 +210,10 @@ fn main() {
         } => run_export_fmu(&config, &io, &target, &output, cli.verbose),
     };
 
+    if entropyk_fluids::profiling::enabled() {
+        eprintln!("{}", entropyk_fluids::profiling::report());
+    }
+
     match result {
         Ok(()) => std::process::exit(ExitCode::Success as i32),
         Err(e) => {
@@ -288,7 +292,10 @@ fn print_result(result: &entropyk_cli::run::SimulationResult) {
         } else {
             format!("{} ≠ {}", dof.n_equations, dof.n_unknowns).red()
         };
-        println!("  DoF:        {} eqs / {} unk  [{}]", dof.n_equations, dof.n_unknowns, tag);
+        println!(
+            "  DoF:        {} eqs / {} unk  [{}]",
+            dof.n_equations, dof.n_unknowns, tag
+        );
         println!("              balance: {}", dof.balance);
     }
 

crates/cli/src/run.rs

@@ -69,6 +69,13 @@ pub struct SimulationResult {
     pub dof: Option<DofSummary>,
     /// Execution time in milliseconds.
     pub elapsed_ms: u64,
+    /// Raw Newton state vector at the end of the solve (length =
+    /// `system.full_state_vector_len()`). Populated for both converged and
+    /// failed runs when a state is available. Useful for warm-starting another
+    /// config (e.g. transfer a `dp_model=quadratic` solution into an `msh`
+    /// solve via the `ENTROPYK_INIT_STATE_JSON` environment variable).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub raw_state_vector: Option<Vec<f64>>,
 }
 
 /// Compact DoF summary for CLI / web API consumers.
@@ -238,6 +245,91 @@ pub fn run_simulation(
     Ok(result)
 }
 
+/// Physical-parameter continuation on a fixed-opening EXV (TLK-Thermo /
+/// Modelica 2019 homotopy on a physical parameter).
+///
+/// When a direct solve fails, the opening is first reduced to `target × 0.5`
+/// (an easier operating point: the valve dominates the resistance chain and
+/// the momentum block is well-conditioned), then walked back up to `target`
+/// with adaptive steps, warm-starting every step from the previous converged
+/// solution. This keeps each intermediate solve near a feasible point of the
+/// same branch instead of jumping from the cold start across the stiff
+/// region created by two-phase pressure drops at high opening.
+fn solve_with_opening_continuation<S>(
+    system: &mut entropyk_solver::System,
+    exv_name: &str,
+    target: f64,
+    initial_state: Vec<f64>,
+    solve_once: &S,
+) -> Result<entropyk_solver::solver::ConvergedState, entropyk_solver::solver::SolverError>
+where
+    S: Fn(
+        &mut entropyk_solver::System,
+        Vec<f64>,
+    )
+        -> Result<entropyk_solver::solver::ConvergedState, entropyk_solver::solver::SolverError>,
+{
+    const MIN_STEP: f64 = 0.001;
+
+    let node = system.get_component_node(exv_name).ok_or_else(|| {
+        entropyk_solver::solver::SolverError::InvalidSystem {
+            message: format!("EXV '{exv_name}' not found for opening continuation"),
+        }
+    })?;
+
+    tracing::info!(
+        exv = exv_name,
+        target,
+        "Direct solve failed; starting EXV opening continuation"
+    );
+
+    // Baseline: solve at the reduced opening.
+    let mut current = target * 0.5;
+    if let Some(comp) = system.component_mut(node) {
+        comp.set_opening_fraction(current);
+    }
+    let mut result = solve_once(system, initial_state)?;
+    let mut warm = result.state.clone();
+
+    // Adaptive walk back to the target opening.
+    let mut step = ((target - current) / 4.0).max(MIN_STEP);
+    while current < target - 1e-9 {
+        let next = (current + step).min(target);
+        if let Some(comp) = system.component_mut(node) {
+            comp.set_opening_fraction(next);
+        }
+        match solve_once(system, warm.clone()) {
+            Ok(converged) => {
+                tracing::info!(
+                    opening = next,
+                    final_residual = converged.final_residual,
+                    "Opening continuation step converged"
+                );
+                current = next;
+                warm = converged.state.clone();
+                result = converged;
+                step = (step * 1.2).min(0.1);
+            }
+            Err(err) => {
+                step *= 0.5;
+                // Restore the last good opening before retrying smaller.
+                if let Some(comp) = system.component_mut(node) {
+                    comp.set_opening_fraction(current);
+                }
+                if step < MIN_STEP {
+                    tracing::warn!(
+                        opening = current,
+                        target,
+                        "Opening continuation could not reach the target"
+                    );
+                    return Err(err);
+                }
+            }
+        }
+    }
+    Ok(result)
+}
+
 /// Execute the simulation with the given configuration.
 fn execute_simulation(
     config: &ScenarioConfig,
@@ -273,11 +365,24 @@ fn execute_simulation(
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms,
+            raw_state_vector: None,
         };
     }
 
     let backend: Arc<dyn entropyk_fluids::FluidBackend> = match config.fluid_backend.as_deref() {
-        Some("CoolProp") => Arc::new(entropyk_fluids::CoolPropBackend::new()),
+        Some("CoolProp") => {
+            let inner = entropyk_fluids::CoolPropBackend::new();
+            // Opt-in property cache (Story 0.7): finite-only values and
+            // overflow-safe keys; bit-identical results, off by default.
+            if std::env::var("ENTROPYK_CACHE")
+                .map(|v| v == "1")
+                .unwrap_or(false)
+            {
+                Arc::new(entropyk_fluids::CachedBackend::new(inner))
+            } else {
+                Arc::new(inner)
+            }
+        }
         Some("Test") | None => Arc::new(TestBackend::new()),
         Some(other) => {
             return SimulationResult {
@@ -295,6 +400,7 @@ fn execute_simulation(
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms,
+                raw_state_vector: None,
             };
         }
     };
@@ -455,6 +561,11 @@ fn execute_simulation(
         legacy_superheat_k,
     );
 
+    // Physical-parameter continuation support: first fixed-opening EXV
+    // (name, target opening), captured during component expansion below so a
+    // failed solve can be retried by walking the opening up from a reduced value.
+    let mut fixed_exv_opening: Option<(String, f64)> = None;
+
     for circuit_config in &config.circuits {
         let circuit_id = CircuitId(circuit_config.id as u16);
         let auto_t_cond_k = circuit_auto_t_cond.get(&circuit_config.id).copied();
@@ -501,13 +612,36 @@ fn execute_simulation(
 
         // Fixed EXV orifice opening sets ṁ via the valve — skip compressor
         // displacement ṁ closure so DoF stays square (ṁ follows the valve).
-        let meter_mass_flow_via_exv = expanded_components
-            .iter()
-            .any(|c| exv_uses_fixed_orifice(&c.params) && matches!(c.component_type.as_str(), "IsenthalpicExpansionValve" | "EXV"));
+        let meter_mass_flow_via_exv = expanded_components.iter().any(|c| {
+            exv_uses_fixed_orifice(&c.params)
+                && matches!(
+                    c.component_type.as_str(),
+                    "IsenthalpicExpansionValve" | "EXV"
+                )
+        });
+
+        // Capture the first fixed-opening EXV for opening continuation.
+        if fixed_exv_opening.is_none() {
+            fixed_exv_opening = expanded_components
+                .iter()
+                .find(|c| {
+                    exv_uses_fixed_orifice(&c.params)
+                        && matches!(
+                            c.component_type.as_str(),
+                            "IsenthalpicExpansionValve" | "EXV"
+                        )
+                })
+                .and_then(|c| {
+                    c.params
+                        .get("opening")
+                        .and_then(|v| v.as_f64())
+                        .map(|o| (c.name.clone(), o))
+                });
+        }
 
         for component_config in &expanded_components {
             match create_component(
-                &component_config,
+                component_config,
                 &fluid_id,
                 Arc::clone(&backend),
                 auto_t_cond_k,
@@ -576,6 +710,7 @@ fn execute_simulation(
                             initialization_diagnostics: None,
                             dof: None,
                             elapsed_ms,
+                            raw_state_vector: None,
                         };
                     }
                 },
@@ -595,6 +730,7 @@ fn execute_simulation(
                         initialization_diagnostics: None,
                         dof: None,
                         elapsed_ms,
+                        raw_state_vector: None,
                     };
                 }
             }
@@ -613,8 +749,8 @@ fn execute_simulation(
             let from_parts: Vec<&str> = edge.from.split(':').collect();
             let to_parts: Vec<&str> = edge.to.split(':').collect();
 
-            let from_name = from_parts.get(0).copied().unwrap_or("");
-            let to_name = to_parts.get(0).copied().unwrap_or("");
+            let from_name = from_parts.first().copied().unwrap_or("");
+            let to_name = to_parts.first().copied().unwrap_or("");
             let from_port_name = from_parts.get(1).copied();
             let to_port_name = to_parts.get(1).copied();
 
@@ -639,6 +775,7 @@ fn execute_simulation(
                                     initialization_diagnostics: None,
                                     dof: None,
                                     elapsed_ms,
+                                    raw_state_vector: None,
                                 };
                             }
                         },
@@ -658,7 +795,8 @@ fn execute_simulation(
                                 initialization_diagnostics: None,
                                 dof: None,
                                 elapsed_ms,
-                            };
+                raw_state_vector: None,
+            };
                         }
                         None => 1,
                     };
@@ -678,6 +816,7 @@ fn execute_simulation(
                                     initialization_diagnostics: None,
                                     dof: None,
                                     elapsed_ms,
+                                    raw_state_vector: None,
                                 };
                             }
                         },
@@ -697,7 +836,8 @@ fn execute_simulation(
                                 initialization_diagnostics: None,
                                 dof: None,
                                 elapsed_ms,
-                            };
+                raw_state_vector: None,
+            };
                         }
                         None => 0,
                     };
@@ -720,6 +860,7 @@ fn execute_simulation(
                             initialization_diagnostics: None,
                             dof: None,
                             elapsed_ms,
+                            raw_state_vector: None,
                         };
                     }
                 }
@@ -739,6 +880,7 @@ fn execute_simulation(
                         initialization_diagnostics: None,
                         dof: None,
                         elapsed_ms,
+                        raw_state_vector: None,
                     };
                 }
             }
@@ -808,6 +950,7 @@ fn execute_simulation(
                 initialization_diagnostics: None,
                 dof: None,
                 elapsed_ms,
+                raw_state_vector: None,
             };
         }
     }
@@ -833,6 +976,7 @@ fn execute_simulation(
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms,
+            raw_state_vector: None,
         };
         let find_component = |name: &str| {
             config
@@ -910,6 +1054,7 @@ fn execute_simulation(
                         initialization_diagnostics: None,
                         dof: None,
                         elapsed_ms,
+                        raw_state_vector: None,
                     };
                 }
                 system.add_saturated_controller(controller);
@@ -927,6 +1072,7 @@ fn execute_simulation(
                     initialization_diagnostics: None,
                     dof: None,
                     elapsed_ms,
+                    raw_state_vector: None,
                 };
             }
         }
@@ -1100,6 +1246,7 @@ fn execute_simulation(
                                 initialization_diagnostics: None,
                                 dof: None,
                                 elapsed_ms,
+                                raw_state_vector: None,
                             };
                         }
                         system.add_free_actuator(var_id);
@@ -1121,6 +1268,7 @@ fn execute_simulation(
                             initialization_diagnostics: None,
                             dof: None,
                             elapsed_ms,
+                            raw_state_vector: None,
                         };
                     }
                 }
@@ -1141,6 +1289,7 @@ fn execute_simulation(
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms,
+            raw_state_vector: None,
         };
     }
 
@@ -1171,6 +1320,7 @@ fn execute_simulation(
                 initialization_diagnostics: None,
                 dof: Some(summary),
                 elapsed_ms,
+                raw_state_vector: None,
             };
         }
         summary
@@ -1243,6 +1393,7 @@ fn execute_simulation(
                 })
             });
             if emergent {
+                let hx_dp_est = estimate_hx_dp_pa(config, &component_indices);
                 if let Some(staged) = build_staged_emergent_seed(
                     &system,
                     &component_indices,
@@ -1252,6 +1403,7 @@ fn execute_simulation(
                     t_cond,
                     initialization_guesses.superheat_k,
                     n_state,
+                    &hx_dp_est,
                     &mut initialization_diagnostics,
                 ) {
                     state = staged;
@@ -1293,6 +1445,36 @@ fn execute_simulation(
         }
     }
 
+    // Optional warm-start from another run's state. Useful for cross-model
+    // verification (e.g. feed a `dp_model=quadratic` converged state into a
+    // `dp_model=msh` solve to test whether the msh root is in the basin of
+    // attraction). Format: JSON array of f64, length must match
+    // `system.full_state_vector_len()`.
+    if let Ok(state_json) = std::env::var("ENTROPYK_INIT_STATE_JSON") {
+        match serde_json::from_str::<Vec<f64>>(&state_json) {
+            Ok(parsed) if parsed.len() == initial_state.len() => {
+                tracing::info!(
+                    len = parsed.len(),
+                    "Warm-starting from ENTROPYK_INIT_STATE_JSON override"
+                );
+                initial_state = parsed;
+            }
+            Ok(parsed) => {
+                tracing::warn!(
+                    expected = initial_state.len(),
+                    got = parsed.len(),
+                    "ENTROPYK_INIT_STATE_JSON length mismatch — ignoring warm-start override"
+                );
+            }
+            Err(e) => {
+                tracing::warn!(
+                    error = %e,
+                    "ENTROPYK_INIT_STATE_JSON is not a valid JSON array of f64 — ignoring"
+                );
+            }
+        }
+    }
+
     let diagnostic_capture = VerboseConfig {
         enabled: true,
         log_residuals: true,
@@ -1305,6 +1487,11 @@ fn execute_simulation(
     let strategy_name = config.solver.strategy.clone();
     let max_iter = config.solver.max_iterations;
     let tol = config.solver.tolerance;
+    // Cooperative time budget (0 = unbounded). Propagated to every strategy so
+    // pathological cases (e.g. stiff two-phase ΔP grinding through the recovery
+    // cascade) fail with an honest `Timeout` instead of running for minutes.
+    let solve_time_budget = (config.solver.timeout_ms > 0)
+        .then(|| std::time::Duration::from_millis(config.solver.timeout_ms));
     let needs_guarded_newton = !config.controls.is_empty()
         || config.circuits.iter().any(|c| {
             c.enabled
@@ -1313,10 +1500,7 @@ fn execute_simulation(
                         || component_has_free_boundary_pressure(comp)
                 })
         });
-    if !matches!(
-        strategy_name.as_str(),
-        "newton" | "picard" | "fallback"
-    ) {
+    if !matches!(strategy_name.as_str(), "newton" | "picard" | "fallback") {
         return SimulationResult {
             input: input_name.to_string(),
             status: SimulationStatus::Error,
@@ -1333,6 +1517,7 @@ fn execute_simulation(
             initialization_diagnostics: None,
             dof: Some(dof_summary),
             elapsed_ms,
+            raw_state_vector: None,
         };
     }
 
@@ -1343,12 +1528,20 @@ fn execute_simulation(
     //
     // `fallback` uses the real `FallbackSolver` (Newton → Picard on divergence),
     // not an ad-hoc double call.
+    // Budget countdown shared by the direct solve AND every continuation step
+    // (the continuation re-enters `solve_once` per step; without a shared
+    // countdown each step would get a fresh full budget and the total runtime
+    // would be unbounded).
+    let solve_start = std::time::Instant::now();
+    let remaining_budget = || solve_time_budget.map(|b| b.saturating_sub(solve_start.elapsed()));
+
     let solve_once = |system: &mut System, init: Vec<f64>| match strategy_name.as_str() {
         "newton" => {
             let mut cfg = NewtonConfig::default();
             cfg.max_iterations = max_iter;
             cfg.tolerance = tol;
             cfg.line_search = needs_guarded_newton;
+            cfg.timeout = remaining_budget();
             let mut strategy = SolverStrategy::NewtonRaphson(
                 cfg.with_initial_state(init)
                     .with_verbose(diagnostic_capture.clone()),
@@ -1359,6 +1552,7 @@ fn execute_simulation(
             let mut cfg = PicardConfig::default();
             cfg.max_iterations = max_iter;
             cfg.tolerance = tol;
+            cfg.timeout = remaining_budget();
             let mut strategy = SolverStrategy::SequentialSubstitution(
                 cfg.with_initial_state(init)
                     .with_verbose(diagnostic_capture.clone()),
@@ -1384,12 +1578,47 @@ fn execute_simulation(
             })
             .with_newton_config(newton_cfg)
             .with_picard_config(picard_cfg)
+            .with_homotopy(entropyk_solver::HomotopyConfig::default())
             .with_initial_state(init);
+            if let Some(budget) = remaining_budget() {
+                fallback = fallback.with_timeout(budget);
+            }
             fallback.solve(system)
         }
         _ => unreachable!("solver strategy was validated before solve_once"),
     };
 
+    // Warm-started solve for continuation steps: each step starts near the
+    // previous converged point, so a plain Newton was originally enough. On the
+    // stiff two-phase ΔP regime at high EXV opening the Newton step stagnates
+    // (~0.02 plateau) and the continuation collapses. We therefore run a
+    // *trimmed* FallbackSolver chain that still reaches trust-region and
+    // homotopy when needed — iteration budgets are cut to keep the per-step
+    // cost down (each step is a warm-start, not a cold start).
+    let solve_quick_fallback = |system: &mut System, init: Vec<f64>| {
+        let mut newton_cfg = NewtonConfig::default();
+        newton_cfg.max_iterations = 80;
+        newton_cfg.tolerance = tol;
+        newton_cfg.line_search = needs_guarded_newton;
+
+        let mut picard_cfg = PicardConfig::default();
+        picard_cfg.max_iterations = 80;
+        picard_cfg.tolerance = tol;
+
+        let mut fallback = FallbackSolver::new(FallbackConfig {
+            fallback_enabled: true,
+            ..FallbackConfig::default()
+        })
+        .with_newton_config(newton_cfg)
+        .with_picard_config(picard_cfg)
+        .with_homotopy(entropyk_solver::HomotopyConfig::default())
+        .with_initial_state(init);
+        if let Some(budget) = remaining_budget() {
+            fallback = fallback.with_timeout(budget);
+        }
+        fallback.solve(system)
+    };
+
     let result = if system.has_network_controllers() {
         // Warm-started **adaptive activation continuation** (predictor–corrector
         // homotopy on the override activation λ). This mirrors the Newton-homotopy
@@ -1448,7 +1677,33 @@ fn execute_simulation(
             }
         }
     } else {
-        solve_once(&mut system, initial_state)
+        match solve_once(&mut system, initial_state.clone()) {
+            Ok(converged) => Ok(converged),
+            Err(first_err) => {
+                // Physical-parameter continuation: when a fixed-opening EXV
+                // meters the flow and the direct solve fails, walk the opening
+                // up from a reduced value (see solve_with_opening_continuation).
+                match fixed_exv_opening {
+                    Some((ref exv_name, target))
+                        if target > 0.5 && std::env::var("ENTROPYK_NO_CONTINUATION").is_err() =>
+                    {
+                        match solve_with_opening_continuation(
+                            &mut system,
+                            exv_name,
+                            target,
+                            initial_state,
+                            &solve_quick_fallback,
+                        ) {
+                            Ok(converged) => Ok(converged),
+                            // Surface the original error: it is the actionable
+                            // diagnostic, not the continuation failure.
+                            Err(_) => Err(first_err),
+                        }
+                    }
+                    _ => Err(first_err),
+                }
+            }
+        }
     };
 
     match result {
@@ -1490,6 +1745,7 @@ fn execute_simulation(
                 initialization_diagnostics: Some(initialization_diagnostics),
                 dof: Some(dof_summary.clone()),
                 elapsed_ms,
+                raw_state_vector: Some(converged.state.clone()),
             }
         }
         Err(e) => {
@@ -1535,6 +1791,7 @@ fn execute_simulation(
                 initialization_diagnostics: Some(initialization_diagnostics),
                 dof: Some(dof_summary),
                 elapsed_ms,
+                raw_state_vector: None,
             }
         }
     }
@@ -1685,11 +1942,7 @@ fn resolve_port_index(
         // Condenser / Evaporator / Flooded*: Modelica-style 4-port heat exchangers.
         // Refrigerant: inlet (0) → outlet (1).
         // Secondary (water/brine/air): secondary_inlet (2) → secondary_outlet (3).
-        "Condenser"
-        | "Evaporator"
-        | "FloodedEvaporator"
-        | "FloodedCondenser"
-        | "CondenserCoil"
+        "Condenser" | "Evaporator" | "FloodedEvaporator" | "FloodedCondenser" | "CondenserCoil"
         | "EvaporatorCoil" => match port_lower.as_str() {
             "inlet" | "in" | "refrigerant_in" | "refrigerant_inlet" => Ok(0),
             "outlet" | "out" | "refrigerant_out" | "refrigerant_outlet" => Ok(1),
@@ -1898,12 +2151,10 @@ enum HxDpApply {
     },
 }
 
-fn parse_hx_dp_model(
-    params: &std::collections::HashMap<String, serde_json::Value>,
-) -> HxDpApply {
+fn parse_hx_dp_model(params: &std::collections::HashMap<String, serde_json::Value>) -> HxDpApply {
     use entropyk_components::heat_exchanger::{
-        calibrate_quadratic_k, parse_dp_model_name, TubeChannelGeometry,
-        TwoPhaseDpCorrelation, DEFAULT_REFRIGERANT_M_NOMINAL_KG_S,
+        calibrate_quadratic_k, parse_dp_model_name, TubeChannelGeometry, TwoPhaseDpCorrelation,
+        DEFAULT_REFRIGERANT_M_NOMINAL_KG_S,
     };
 
     if params
@@ -1998,7 +2249,10 @@ fn parse_hx_dp_model(
     }
 }
 
-fn apply_condenser_dp(cond: &mut entropyk_components::heat_exchanger::Condenser, params: &std::collections::HashMap<String, serde_json::Value>) {
+fn apply_condenser_dp(
+    cond: &mut entropyk_components::heat_exchanger::Condenser,
+    params: &std::collections::HashMap<String, serde_json::Value>,
+) {
     match parse_hx_dp_model(params) {
         HxDpApply::Isobaric => {
             // Explicit clear via zero coeff (isobaric).
@@ -2012,7 +2266,10 @@ fn apply_condenser_dp(cond: &mut entropyk_components::heat_exchanger::Condenser,
     }
 }
 
-fn apply_evaporator_dp(evap: &mut entropyk_components::heat_exchanger::Evaporator, params: &std::collections::HashMap<String, serde_json::Value>) {
+fn apply_evaporator_dp(
+    evap: &mut entropyk_components::heat_exchanger::Evaporator,
+    params: &std::collections::HashMap<String, serde_json::Value>,
+) {
     match parse_hx_dp_model(params) {
         HxDpApply::Isobaric => {
             evap.set_pressure_drop_coeff(0.0);
@@ -2046,6 +2303,51 @@ fn parse_coeffs3(
     }
 }
 
+/// Estimates the per-HX refrigerant ΔP [Pa] used to stratify the staged seed:
+/// a uniform per-side pressure seed ignores the tube two-phase ΔP and starts
+/// the near-singular emergent loop far off (measured σ_min ≈ 1.6e-6 on the
+/// 2026-07-19 reference config). Priority: `rated_pressure_drop_pa` param →
+/// nominal design ΔP when a tube model is configured (`dp_model=msh|friedel`
+/// or tube geometry keys) → 0 (uniform seed, unchanged behavior).
+fn estimate_hx_dp_pa(
+    config: &ScenarioConfig,
+    component_indices: &std::collections::HashMap<String, (petgraph::graph::NodeIndex, String)>,
+) -> std::collections::HashMap<usize, f64> {
+    let mut map = std::collections::HashMap::new();
+    for circuit in config.circuits.iter().filter(|c| c.enabled) {
+        for comp in &circuit.components {
+            let Some((node, _)) = component_indices.get(&comp.name) else {
+                continue;
+            };
+            let dp = comp
+                .params
+                .get("rated_pressure_drop_pa")
+                .and_then(|v| v.as_f64())
+                .filter(|dp| *dp > 0.0)
+                .unwrap_or_else(|| {
+                    let tube = comp
+                        .params
+                        .get("dp_model")
+                        .and_then(|v| v.as_str())
+                        .map(|m| matches!(m, "msh" | "friedel"))
+                        .unwrap_or(false)
+                        || comp.params.get("tube_length_m").is_some()
+                        || comp.params.get("tube_diameter_m").is_some()
+                        || comp.params.get("n_parallel_tubes").is_some();
+                    if tube {
+                        entropyk_components::heat_exchanger::two_phase_dp::DEFAULT_REFRIGERANT_DP_NOMINAL_PA
+                    } else {
+                        0.0
+                    }
+                });
+            if dp > 0.0 {
+                map.insert(node.index(), dp);
+            }
+        }
+    }
+    map
+}
+
 /// Builds a physically-staged initial state for an **emergent-pressure** cycle.
 ///
 /// In emergent mode no component hard-pins the condensing/evaporating pressures
@@ -2071,6 +2373,7 @@ fn build_staged_emergent_seed(
     t_cond_k: f64,
     superheat_k: f64,
     n_state: usize,
+    hx_dp_est: &std::collections::HashMap<usize, f64>,
     diagnostics: &mut entropyk_solver::InitializationDiagnostics,
 ) -> Option<Vec<f64>> {
     use petgraph::graph::{EdgeIndex, NodeIndex};
@@ -2186,7 +2489,20 @@ fn build_staged_emergent_seed(
             if evaporator_nodes.contains(&cur.index()) {
                 past_evaporator = true;
             }
-            let p = if side_low { p_evap_pa } else { p_cond_pa };
+            // Stratified pressure: an edge ENTERING a heat exchanger sits
+            // upstream of its ΔP (P_in = P_out + ΔP_est); every other edge
+            // keeps the side's saturation anchor. Uniform when ΔP_est = 0.
+            let p = match hx_dp_est.get(&tgt.index()) {
+                Some(&dp) if !side_low && condenser_nodes.contains(&tgt.index()) => p_cond_pa + dp,
+                Some(&dp) if side_low && evaporator_nodes.contains(&tgt.index()) => p_evap_pa + dp,
+                _ => {
+                    if side_low {
+                        p_evap_pa
+                    } else {
+                        p_cond_pa
+                    }
+                }
+            };
             let (h, regime) = if side_low {
                 if past_evaporator || tgt == start {
                     (
@@ -3018,11 +3334,11 @@ fn create_component(
                 port_dis,
                 port_eco,
             )
-            .map_err(|e| CliError::Component(e))?;
+            .map_err(CliError::Component)?;
 
             if let Some(freq_hz) = params.get("frequency_hz").and_then(|v| v.as_f64()) {
                 comp.set_frequency_hz(freq_hz)
-                    .map_err(|e| CliError::Component(e))?;
+                    .map_err(CliError::Component)?;
             }
 
             // Volume index Vi + slide valve position (part-load Vi penalty).
@@ -3830,7 +4146,7 @@ fn create_component(
                 Some(r) => PipeGeometry::new(length_m, diameter_m, r),
                 None => PipeGeometry::smooth(length_m, diameter_m),
             }
-            .map_err(|e| CliError::Component(e))?;
+            .map_err(CliError::Component)?;
 
             let density = params
                 .get("density_kg_m3")
@@ -3945,7 +4261,7 @@ fn create_component(
             let mut valve = BypassValve::new(&name, config);
             valve
                 .set_position(position)
-                .map_err(|e| CliError::Component(e))?;
+                .map_err(CliError::Component)?;
 
             Ok(Box::new(valve.with_edge_coupling()))
         }
@@ -3979,7 +4295,7 @@ fn create_component(
             } else {
                 FlowSplitter::compressible(fluid, inlet, outlets)
             }
-            .map_err(|e| CliError::Component(e))?;
+            .map_err(CliError::Component)?;
 
             Ok(Box::new(splitter))
         }
@@ -4012,14 +4328,14 @@ fn create_component(
             } else {
                 FlowMerger::compressible(fluid, inlets, outlet)
             }
-            .map_err(|e| CliError::Component(e))?;
+            .map_err(CliError::Component)?;
 
             // Optional mass-flow weights for enthalpy mixing.
             let merger = if let Some(weights) = params.get("mass_flow_weights").and_then(|v| v.as_array())
             {
                 let w: Vec<f64> = weights.iter().filter_map(|v| v.as_f64()).collect();
                 if w.len() == n_inlets {
-                    merger.with_mass_flows(w).map_err(|e| CliError::Component(e))?
+                    merger.with_mass_flows(w).map_err(CliError::Component)?
                 } else {
                     merger
                 }
@@ -4055,7 +4371,7 @@ fn create_component(
             let p2 = params.get("curve_p2").and_then(|v| v.as_f64()).unwrap_or(-20.0);
 
             let curves = FanCurves::quadratic(p0, p1, p2, 0.0, 1.6, -0.64)
-                .map_err(|e| CliError::Component(e))?;
+                .map_err(CliError::Component)?;
 
             let p_bar = params.get("p_bar").and_then(|v| v.as_f64()).unwrap_or(1.01325);
             let h_kj_kg = params.get("h_kj_kg").and_then(|v| v.as_f64()).unwrap_or(420.0);
@@ -4079,11 +4395,11 @@ fn create_component(
                 .unwrap_or(false);
 
             let mut fan_disconnected = Fan::new(curves, inlet_a, outlet_a, air_density)
-                .map_err(|e| CliError::Component(e))?
+                .map_err(CliError::Component)?
                 .with_drive_chain(use_drive_chain);
             fan_disconnected
                 .set_speed_ratio(speed_ratio)
-                .map_err(|e| CliError::Component(e))?;
+                .map_err(CliError::Component)?;
 
             let inlet_b = Port::new(
                 fluid_id.clone(),
@@ -4098,7 +4414,7 @@ fn create_component(
 
             let fan = fan_disconnected
                 .connect(inlet_b, outlet_b)
-                .map_err(|e| CliError::Component(e))?
+                .map_err(CliError::Component)?
                 .with_edge_coupling(design_flow_m3_s);
 
             Ok(Box::new(fan))
@@ -4147,7 +4463,7 @@ fn create_component(
                 vapor_outlet,
                 Arc::clone(&backend),
             )
-            .map_err(|e| CliError::Component(e))?
+            .map_err(CliError::Component)?
             .with_edge_coupling(t_sat_k);
 
             Ok(Box::new(drum))
@@ -4234,7 +4550,7 @@ fn create_component(
                 displacement_m3,
                 efficiency,
             )
-            .map_err(|e| CliError::Component(e))?;
+            .map_err(CliError::Component)?;
 
             let suction_b = Port::new(
                 fluid_id.clone(),
@@ -4249,7 +4565,7 @@ fn create_component(
 
             let comp = comp_disconnected
                 .connect(suction_b, discharge_b)
-                .map_err(|e| CliError::Component(e))?;
+                .map_err(CliError::Component)?;
 
             Ok(Box::new(comp))
         }
@@ -4323,7 +4639,7 @@ fn create_component(
 
             // Build ExpansionValve<Disconnected> with selected flow model
             let valve_disconnected = ExpansionValve::new(inlet_a, outlet_a, Some(opening))
-                .map_err(|e| CliError::Component(e))?
+                .map_err(CliError::Component)?
                 .with_flow_model(flow_model);
 
             // Connect ports to transition Disconnected → Connected
@@ -4340,7 +4656,7 @@ fn create_component(
 
             let mut valve = valve_disconnected
                 .connect(inlet_b, outlet_b)
-                .map_err(|e| CliError::Component(e))?;
+                .map_err(CliError::Component)?;
             if let Some(p_bulb) = params
                 .get("bulb_pressure_pa")
                 .or_else(|| params.get("p_bulb_pa"))
@@ -4786,6 +5102,16 @@ fn create_component(
                 evap = evap.with_correlation(correlation);
             }
 
+            // Emergent-pressure mode: +1 outlet-closure residual pins h_out to
+            // h(P, Tsat + target_superheat) so P_evap emerges from the secondary.
+            if params
+                .get("emergent_pressure")
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false)
+            {
+                evap = evap.with_emergent_pressure();
+            }
+
             // Convention (Evaporator): hot_fluid = secondary (brine/water), cold_fluid = refrigerant.
             // The refrigerant evaporates (absorbs heat from the secondary).
             // Note: this is opposite to the Condenser convention — see BphxCondenser.
@@ -4832,6 +5158,21 @@ fn create_component(
                 cond = cond.with_correlation(correlation);
             }
 
+            // Emergent-pressure mode: +1 outlet-closure residual pins h_out to
+            // h(P, Tsat − subcooling) so P_cond emerges from the secondary.
+            if params
+                .get("emergent_pressure")
+                .and_then(|v| v.as_bool())
+                .unwrap_or(false)
+            {
+                let subcooling_k = params
+                    .get("subcooling_k")
+                    .and_then(|v| v.as_f64())
+                    .or_else(|| params.get("target_subcooling_k").and_then(|v| v.as_f64()))
+                    .unwrap_or(target_subcooling);
+                cond = cond.with_emergent_pressure(subcooling_k);
+            }
+
             // Convention (Condenser): hot_fluid = refrigerant, cold_fluid = secondary (brine/water).
             // The refrigerant condenses (releases heat to the secondary).
             // Note: this is opposite to the Evaporator convention — see BphxEvaporator.
@@ -4997,8 +5338,7 @@ fn extract_state(
     fluid: &str,
     backend: &dyn entropyk_fluids::FluidBackend,
 ) -> Vec<StateEntry> {
-    use entropyk_core::{Enthalpy, Pressure};
-    use entropyk_fluids::{FluidId, FluidState, Property, Quality};
+    use entropyk_fluids::FluidId;
 
     let state = &converged.state;
     let refrigerant = FluidId::new(fluid);
@@ -5013,21 +5353,20 @@ fn extract_state(
             let enthalpy_kj_kg = h_j / 1000.0;
             let mass_flow_kg_s = state.get(m_idx).copied().filter(|m| m.is_finite());
 
-            let (source, source_port, target, target_port) =
-                match system.edge_endpoints(e) {
-                    Some((src, tgt)) => {
-                        let edge_w = system.graph().edge_weight(e);
-                        let sp = edge_w.map(|w| w.source_port).unwrap_or(1);
-                        let tp = edge_w.map(|w| w.target_port).unwrap_or(0);
-                        (
-                            Some(component_display_name(system, src)),
-                            Some(port_display_name(system, src, sp)),
-                            Some(component_display_name(system, tgt)),
-                            Some(port_display_name(system, tgt, tp)),
-                        )
-                    }
-                    None => (None, None, None, None),
-                };
+            let (source, source_port, target, target_port) = match system.edge_endpoints(e) {
+                Some((src, tgt)) => {
+                    let edge_w = system.graph().edge_weight(e);
+                    let sp = edge_w.map(|w| w.source_port).unwrap_or(1);
+                    let tp = edge_w.map(|w| w.target_port).unwrap_or(0);
+                    (
+                        Some(component_display_name(system, src)),
+                        Some(port_display_name(system, src, sp)),
+                        Some(component_display_name(system, tgt)),
+                        Some(port_display_name(system, tgt, tp)),
+                    )
+                }
+                None => (None, None, None, None),
+            };
 
             // CRITICAL: secondary water/air edges must NOT flash with the cycle
             // refrigerant (that produced absurd T ≈ −58 °C on BrineSource outlets).
@@ -5291,6 +5630,7 @@ mod tests {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 50,
+            raw_state_vector: None,
         };
 
         let json = serde_json::to_string_pretty(&result).unwrap();
@@ -5446,4 +5786,67 @@ mod tests {
             "Configuration error: BphxEvaporator: unsupported correlation 'not-a-correlation'. Use 'Longo2004', 'Shah1979', or 'Shah2021'."
         );
     }
+
+    fn comp_from_json(v: serde_json::Value) -> crate::config::ComponentConfig {
+        serde_json::from_value(v).expect("valid component JSON")
+    }
+
+    #[test]
+    fn test_estimate_hx_dp_pa_rated_tube_and_plain() {
+        use serde_json::json;
+        let config: ScenarioConfig = serde_json::from_value(json!({
+            "fluid": "R134a",
+            "circuits": [{
+                "components": [
+                    {"type": "Condenser", "name": "cond", "rated_pressure_drop_pa": 15000.0},
+                    {"type": "Evaporator", "name": "evap", "dp_model": "msh", "tube_length_m": 6.0},
+                    {"type": "Pipe", "name": "pipe"}
+                ]
+            }]
+        }))
+        .expect("valid scenario JSON");
+        let indices = std::collections::HashMap::from([
+            (
+                "cond".to_string(),
+                (petgraph::graph::NodeIndex::new(1), "Condenser".to_string()),
+            ),
+            (
+                "evap".to_string(),
+                (petgraph::graph::NodeIndex::new(3), "Evaporator".to_string()),
+            ),
+            (
+                "pipe".to_string(),
+                (petgraph::graph::NodeIndex::new(5), "Pipe".to_string()),
+            ),
+        ]);
+        let map = estimate_hx_dp_pa(&config, &indices);
+        assert_eq!(map.get(&1), Some(&15000.0));
+        assert_eq!(
+            map.get(&3),
+            Some(
+                &entropyk_components::heat_exchanger::two_phase_dp::DEFAULT_REFRIGERANT_DP_NOMINAL_PA
+            )
+        );
+        assert!(!map.contains_key(&5));
+    }
+
+    #[test]
+    fn test_boundary_mass_flow_seeding() {
+        use serde_json::json;
+        let backend = entropyk_fluids::TestBackend::new();
+        // A source seeds the branch ṁ with its imposed value.
+        let source = comp_from_json(
+            json!({"type": "BrineSource", "name": "cond_water_in", "fluid": "Water", "p_set_bar": 2.0, "t_set_c": 30.0, "m_flow_kg_s": 0.31}),
+        );
+        let seed = boundary_seed_from_component(&source, &backend, true)
+            .expect("BrineSource seed should evaluate");
+        assert_eq!(seed.3, 0.31);
+        // A sink without explicit ṁ falls back to the default seed.
+        let sink = comp_from_json(
+            json!({"type": "BrineSink", "name": "cond_water_out", "fluid": "Water", "p_back_bar": 2.0, "fix_pressure": true}),
+        );
+        let seed = boundary_seed_from_component(&sink, &backend, false)
+            .expect("BrineSink seed should evaluate");
+        assert_eq!(seed.3, entropyk_solver::system::DEFAULT_MASS_FLOW_SEED_KG_S);
+    }
 }

crates/cli/tests/batch_execution.rs

@@ -92,6 +92,7 @@ fn test_simulation_result_statuses() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 50,
+            raw_state_vector: None,
         },
         SimulationResult {
             input: "fail.json".to_string(),
@@ -105,6 +106,7 @@ fn test_simulation_result_statuses() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 0,
+            raw_state_vector: None,
         },
         SimulationResult {
             input: "timeout.json".to_string(),
@@ -118,6 +120,7 @@ fn test_simulation_result_statuses() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 1000,
+            raw_state_vector: None,
         },
     ];
 
@@ -146,12 +149,12 @@ fn test_batch_aggregator_csv_output() {
             input: "scenario1.json".to_string(),
             status: SimulationStatus::Converged,
             convergence: Some(entropyk_cli::run::ConvergenceInfo {
-            final_residual: 1e-8,
-            tolerance: 1e-6,
-            iterations: None,
-            strategy: None,
-            iteration_history: vec![],
-        }),
+                final_residual: 1e-8,
+                tolerance: 1e-6,
+                iterations: None,
+                strategy: None,
+                iteration_history: vec![],
+            }),
             iterations: Some(25),
             state: None,
             performance: None,
@@ -160,17 +163,18 @@ fn test_batch_aggregator_csv_output() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 150,
+            raw_state_vector: None,
         },
         SimulationResult {
             input: "scenario2.json".to_string(),
             status: SimulationStatus::Converged,
             convergence: Some(entropyk_cli::run::ConvergenceInfo {
-            final_residual: 5e-7,
-            tolerance: 1e-6,
-            iterations: None,
-            strategy: None,
-            iteration_history: vec![],
-        }),
+                final_residual: 5e-7,
+                tolerance: 1e-6,
+                iterations: None,
+                strategy: None,
+                iteration_history: vec![],
+            }),
             iterations: Some(30),
             state: None,
             performance: None,
@@ -179,6 +183,7 @@ fn test_batch_aggregator_csv_output() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 200,
+            raw_state_vector: None,
         },
         SimulationResult {
             input: "scenario3.json".to_string(),
@@ -192,6 +197,7 @@ fn test_batch_aggregator_csv_output() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 0,
+            raw_state_vector: None,
         },
     ];
 
@@ -223,6 +229,7 @@ fn test_batch_aggregator_json_summary() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 50,
+            raw_state_vector: None,
         },
         SimulationResult {
             input: "test2.json".to_string(),
@@ -236,6 +243,7 @@ fn test_batch_aggregator_json_summary() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 75,
+            raw_state_vector: None,
         },
         SimulationResult {
             input: "test3.json".to_string(),
@@ -249,6 +257,7 @@ fn test_batch_aggregator_json_summary() {
             initialization_diagnostics: None,
             dof: None,
             elapsed_ms: 5000,
+            raw_state_vector: None,
         },
     ];
 
@@ -313,6 +322,7 @@ fn test_batch_summary_csv_with_convergence() {
         initialization_diagnostics: None,
         dof: None,
         elapsed_ms: 300,
+        raw_state_vector: None,
     }];
 
     let summary = BatchSummary {

crates/cli/tests/hx_standalone.rs

@@ -304,9 +304,13 @@ fn test_hx_air_ref_condenser_4port() {
           { "from": "hx:secondary_outlet", "to": "cold_out:inlet" }
         ]
       }],
-      "solver": { "strategy": "newton", "max_iterations": 300, "tolerance": 1e-6 }
+      "solver": { "strategy": "newton", "max_iterations": 1000, "tolerance": 1e-6 }
     }
     "#;
+    // NOTE: with the Modelica Free-P AirSource default, this case converges
+    // linearly (~450 iterations) because the Condenser Jacobian is partially
+    // finite-difference (see audit plan Step 4 — exact HX Jacobians). Restore
+    // max_iterations: 300 once the analytic Jacobian lands.
     let result = run_config(json);
     assert_converged(&result, "Air/Ref Condenser");
 

crates/cli/tests/single_run.rs

@@ -29,6 +29,7 @@ fn test_simulation_result_serialization() {
         initialization_diagnostics: None,
         dof: None,
         elapsed_ms: 50,
+        raw_state_vector: None,
     };
 
     let json = serde_json::to_string_pretty(&result).unwrap();
@@ -69,6 +70,7 @@ fn test_error_result_serialization() {
         initialization_diagnostics: None,
         dof: None,
         elapsed_ms: 0,
+        raw_state_vector: None,
     };
 
     let json = serde_json::to_string(&result).unwrap();
@@ -94,6 +96,7 @@ fn test_error_result_serializes_failure_diagnostics() {
         initialization_diagnostics: None,
         dof: None,
         elapsed_ms: 0,
+        raw_state_vector: None,
     };
 
     let json = serde_json::to_string(&result).unwrap();
@@ -1293,13 +1296,13 @@ fn test_bphx_bounded_circuit_reaches_solver_stage() {
     }
 }
 
-/// AC2 + spec-cli-failure-diagnostics.md: Given a closed-loop simulation that
-/// the solver fails to converge (limited iterations), the JSON result includes
-/// `failure_diagnostics` with `dominant_residual_index` and `dominant_residual_value`.
+/// AC2 + spec-cli-failure-diagnostics.md: Given a DoF-square closed-loop simulation
+/// that the solver fails to converge (iteration budget exhausted), the JSON result
+/// includes `failure_diagnostics` with a finite residual norm.
 ///
-/// This test uses a 2-component closed loop (Pump → Pump) with extremely tight
-/// tolerance so Newton runs at least one iteration before reporting NonConvergence,
-/// verifying that the CLI captures and surfaces the post-mortem diagnostics.
+/// Fixture: a DoF-square R134a vapor-compression cycle. Solver budget is capped so
+/// Newton cannot reach tolerance; the run must fail at the solver stage (not during
+/// finalize) and surface post-mortem diagnostics.
 #[test]
 fn test_failed_run_json_includes_failure_diagnostics() {
     use entropyk_cli::run::run_simulation;
@@ -1307,25 +1310,53 @@ fn test_failed_run_json_includes_failure_diagnostics() {
     let dir = tempdir().unwrap();
     let config_path = dir.path().join("tight_tolerance_failure.json");
 
-    // A closed water loop (two pumps) with an impossibly tight tolerance
-    // ensures Newton runs at least one iteration then reports NonConvergence.
-    // The CLI wraps this in a FallbackSolver with VerboseConfig enabled,
-    // so `failure_diagnostics` must be present in the result.
     let json = r#"
     {
-        "name": "Tight tolerance failure diagnostics test",
-        "fluid": "Water",
-        "circuits": [{
-            "id": 0,
-            "components": [
-                { "type": "Pump", "name": "pump1" },
-                { "type": "Pump", "name": "pump2" }
-            ],
-            "edges": [
-                { "from": "pump1:outlet", "to": "pump2:inlet" },
-                { "from": "pump2:outlet", "to": "pump1:inlet" }
-            ]
-        }],
+        "fluid": "R134a",
+        "fluid_backend": "CoolProp",
+        "circuits": [
+            {
+                "id": 0,
+                "components": [
+                    {
+                        "type": "IsentropicCompressor", "name": "comp",
+                        "isentropic_efficiency": 0.70,
+                        "t_cond_k": 318.15, "t_evap_k": 278.15, "superheat_k": 5.0,
+                        "emergent_pressure": true,
+                        "displacement_m3": 6.5e-5, "speed_hz": 50.0,
+                        "volumetric_efficiency": 0.92
+                    },
+                    {
+                        "type": "Condenser", "name": "cond", "ua": 766.0,
+                        "emergent_pressure": true, "subcooling_k": 5.0,
+                        "secondary_fluid": "Water"
+                    },
+                    {
+                        "type": "IsenthalpicExpansionValve", "name": "exv",
+                        "t_evap_k": 278.15, "emergent_pressure": true
+                    },
+                    {
+                        "type": "Evaporator", "name": "evap", "ua": 1468.0,
+                        "emergent_pressure": true,
+                        "secondary_fluid": "Water"
+                    },
+                    { "type": "BrineSource", "name": "cond_water_in", "fluid": "Water", "p_set_bar": 2.0, "t_set_c": 30.0, "m_flow_kg_s": 0.3583 },
+                    { "type": "BrineSink", "name": "cond_water_out", "fluid": "Water", "p_back_bar": 2.0 },
+                    { "type": "BrineSource", "name": "evap_water_in", "fluid": "Water", "p_set_bar": 2.0, "t_set_c": 12.0, "m_flow_kg_s": 0.4778 },
+                    { "type": "BrineSink", "name": "evap_water_out", "fluid": "Water", "p_back_bar": 2.0 }
+                ],
+                "edges": [
+                    { "from": "comp:outlet", "to": "cond:inlet" },
+                    { "from": "cond:outlet", "to": "exv:inlet" },
+                    { "from": "exv:outlet", "to": "evap:inlet" },
+                    { "from": "evap:outlet", "to": "comp:inlet" },
+                    { "from": "cond_water_in:outlet", "to": "cond:secondary_inlet" },
+                    { "from": "cond:secondary_outlet", "to": "cond_water_out:inlet" },
+                    { "from": "evap_water_in:outlet", "to": "evap:secondary_inlet" },
+                    { "from": "evap:secondary_outlet", "to": "evap_water_out:inlet" }
+                ]
+            }
+        ],
         "solver": {
             "strategy": "newton",
             "max_iterations": 2,
@@ -1337,54 +1368,34 @@ fn test_failed_run_json_includes_failure_diagnostics() {
 
     let result = run_simulation(&config_path, None, false).unwrap();
 
-    // The solver must have failed (either NonConverged or Error after iterations).
-    // Accepted statuses: NonConverged or Error — both indicate the solver gave up.
-    let failed = matches!(
+    assert!(
+        matches!(
+            result.status,
+            SimulationStatus::NonConverged | SimulationStatus::Error
+        ),
+        "expected solver-stage failure, got {:?} (error: {:?})",
         result.status,
-        SimulationStatus::NonConverged | SimulationStatus::Error
+        result.error
+    );
+
+    let diagnostics = result.failure_diagnostics.as_ref().unwrap_or_else(|| {
+        panic!(
+            "failure_diagnostics must be present after solver-stage failure \
+             (status: {:?}, error: {:?})",
+            result.status, result.error
+        )
+    });
+
+    let json_str = serde_json::to_string(&result).unwrap();
+    assert!(
+        json_str.contains("failure_diagnostics"),
+        "JSON result must contain 'failure_diagnostics' key"
     );
     assert!(
-        failed || matches!(result.status, SimulationStatus::Converged),
-        "Unexpected status: {:?}",
-        result.status
+        diagnostics.final_residual_norm.is_finite() && diagnostics.final_residual_norm >= 0.0,
+        "failure_diagnostics.final_residual_norm must be finite and non-negative, got {}",
+        diagnostics.final_residual_norm
     );
-
-    // The pump loop must reach the solver stage (2 pumps in a closed loop finalize cleanly).
-    // With max_iterations=2 and tolerance=1e-100, Newton runs 2 iterations then declares
-    // NonConvergence — diagnostics MUST be present.
-    if matches!(
-        result.status,
-        SimulationStatus::NonConverged | SimulationStatus::Error
-    ) {
-        if let Some(ref err_msg) = result.error {
-            let is_pre_solver_error = err_msg.contains("finalization")
-                || err_msg.contains("Unknown component")
-                || err_msg.contains("Failed to add");
-            if is_pre_solver_error {
-                return; // pre-solver failure: no diagnostics expected
-            }
-        }
-
-        // The solver ran and failed: failure_diagnostics MUST be present.
-        assert!(
-            result.failure_diagnostics.is_some(),
-            "failure_diagnostics must be present when solver ran at least one iteration and failed \
-             (status: {:?}, error: {:?})",
-            result.status,
-            result.error
-        );
-
-        let json_str = serde_json::to_string(&result).unwrap();
-        assert!(
-            json_str.contains("failure_diagnostics"),
-            "JSON result must contain 'failure_diagnostics' key"
-        );
-        let fd = result.failure_diagnostics.as_ref().unwrap();
-        assert!(
-            fd.final_residual_norm >= 0.0,
-            "failure_diagnostics.final_residual_norm must be non-negative"
-        );
-    }
 }
 
 /// spec-cli-failure-diagnostics.md AC3 (integration): Given an empty system config that
@@ -2292,6 +2303,7 @@ fn test_structural_failure_serializes_without_diagnostics() {
         initialization_diagnostics: None,
         dof: None,
         elapsed_ms: 0,
+        raw_state_vector: None,
     };
 
     let json = serde_json::to_string(&result).unwrap();
@@ -2336,6 +2348,7 @@ fn test_success_result_does_not_include_failure_diagnostics() {
         initialization_diagnostics: None,
         dof: None,
         elapsed_ms: 120,
+        raw_state_vector: None,
     };
 
     let json = serde_json::to_string(&result).unwrap();