Entropyk/_bmad-output/implementation-artifacts/4-7-convergence-criteria-and-validation.md

# Story 4.7: Convergence Criteria & Validation

Status: done

<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->

## Story

As a simulation user,
I want strict, multi-dimensional convergence criteria with per-circuit granularity and a sparse/block-diagonal Jacobian for multi-circuit systems,
so that large systems remain tractable and convergence is only declared when ALL circuits physically satisfy pressure, mass, and energy balances simultaneously.

## Acceptance Criteria

1. **Δ Pressure convergence ≤ 1 Pa** (AC: #1)
   - Given a system approaching solution
   - When checking convergence with `ConvergenceCriteria::check()`
   - Then the check passes only if `max |ΔP_i| < 1.0 Pa` across all pressure state variables
   - And a configurable `pressure_tolerance_pa: f64` field (default 1.0 Pa) controls the threshold

2. **Mass balance error < 1e-9 kg/s per circuit** (AC: #2)
   - Given a cycle residuals vector
   - When `ConvergenceCriteria::check()` is called
   - Then mass balance error per circuit is extracted: `Σ |ṁ_in - ṁ_out| < 1e-9 kg/s`
   - And `mass_balance_tolerance_kgs: f64` field (default 1e-9) controls the threshold

3. **Energy balance error < 1e-6 kW per circuit** (AC: #3)
   - Given a cycle residuals vector
   - When `ConvergenceCriteria::check()` is called
   - Then energy balance error per circuit satisfies `|Σ Q̇ + Ẇ - Σ (ṁ·h)| < 1e-6 kW (1e-3 W)`
   - And `energy_balance_tolerance_w: f64` field (default 1e-3) controls the threshold

4. **Per-circuit convergence tracking** (AC: #4)
   - Given a multi-circuit system (N circuits)
   - When checking convergence
   - Then `ConvergenceReport` contains a `per_circuit: Vec<CircuitConvergence>` with one entry per active circuit
   - And each `CircuitConvergence` contains: `circuit_id: u8`, `pressure_ok: bool`, `mass_ok: bool`, `energy_ok: bool`, `converged: bool`
   - And `circuit.converged = pressure_ok && mass_ok && energy_ok`

5. **Global convergence = ALL circuits converged** (AC: #5)
   - Given a multi-circuit system with N circuits
   - When `ConvergenceReport::is_globally_converged()` is called
   - Then it returns `true` if and only if ALL entries in `per_circuit` have `converged == true`
   - And a single-circuit system behaves identically (degenerate case of N=1)

6. **Block-diagonal Jacobian for uncoupled multi-circuit** (AC: #6)
   - Given a system with N circuits that have NO thermal couplings between them
   - When `JacobianMatrix` is assembled via `system.assemble_jacobian()`
   - Then the resulting matrix has block-diagonal structure (entries outside circuit blocks are zero)
   - And `JacobianMatrix::block_structure(system)` returns `Vec<(row_start, row_end, col_start, col_end)>` describing each circuit block
   - And `JacobianMatrix::is_block_diagonal(system, tolerance: f64)` returns `true` for uncoupled systems

7. **ConvergenceCriteria integrates with solvers** (AC: #7)
   - Given a `NewtonConfig` or `PicardConfig`
   - When the user sets `solver.with_convergence_criteria(criteria)`
   - Then the solver uses `ConvergenceCriteria::check()` instead of the raw L2-norm tolerance check
   - And the old `tolerance: f64` field remains for backward-compat (ignored when `convergence_criteria` is `Some`)
   - And `FallbackSolver` delegates `with_convergence_criteria()` to both sub-solvers

8. **`ConvergenceReport` in `ConvergedState`** (AC: #8)
   - Given a converged system
   - When `ConvergedState` is returned
   - Then it optionally contains `convergence_report: Option<ConvergenceReport>`
   - And `ConvergedState::convergence_report()` returns `None` when criteria is not set (backward-compat)

## Tasks / Subtasks

- [x] Create `crates/solver/src/criteria.rs` module (AC: #1–#6)
  - [x] Define `ConvergenceCriteria` struct with fields:
    - [x] `pressure_tolerance_pa: f64` (default 1.0)
    - [x] `mass_balance_tolerance_kgs: f64` (default 1e-9)
    - [x] `energy_balance_tolerance_w: f64` (default 1e-3)
  - [x] Implement `ConvergenceCriteria::default()` using the values above
  - [x] Define `CircuitConvergence` struct: `circuit_id: u8`, `pressure_ok: bool`, `mass_ok: bool`, `energy_ok: bool`, `converged: bool`
  - [x] Define `ConvergenceReport` struct: `per_circuit: Vec<CircuitConvergence>`, `globally_converged: bool`
  - [x] Implement `ConvergenceReport::is_globally_converged() -> bool`
  - [x] Implement `ConvergenceCriteria::check(state: &[f64], residuals: &[f64], system: &System) -> ConvergenceReport`:
    - [x] Extract per-circuit pressure deltas from state vector using `system.circuit_edges(circuit_id)` and `system.edge_state_indices(edge)`
    - [x] For each circuit: compute `max |ΔP| < pressure_tolerance_pa` (use state increments from previous Newton step if available, else use residuals as proxy)
    - [x] For each circuit: compute mass balance residual sum `< mass_balance_tolerance_kgs`
    - [x] For each circuit: compute energy balance residual sum `< energy_balance_tolerance_w`
    - [x] Return `ConvergenceReport` with per-circuit and global status
  - [x] Expose `criteria.rs` in `lib.rs` (AC: #7)

- [x] Add `block_structure` support to `JacobianMatrix` (AC: #6)
  - [x] Implement `JacobianMatrix::block_structure(system: &System) -> Vec<(usize, usize, usize, usize)>` (row_start, row_end, col_start, col_end per circuit)
  - [x] Implement `JacobianMatrix::is_block_diagonal(system: &System, tolerance: f64) -> bool` — verify off-block entries are < tolerance
  - [x] These are pure analysis helpers; they do NOT change how the Jacobian is built (nalgebra `DMatrix<f64>` is retained)

- [x] Integrate `ConvergenceCriteria` into solvers (AC: #7, #8)
  - [x] Add `convergence_criteria: Option<ConvergenceCriteria>` field to `NewtonConfig`
  - [x] Add `with_convergence_criteria(mut self, criteria: ConvergenceCriteria) -> Self` builder to `NewtonConfig`
  - [x] In `NewtonConfig::solve()`: if `convergence_criteria.is_some()`, call `criteria.check()` for convergence test instead of raw `current_norm < self.tolerance`
  - [x] Same pattern for `PicardConfig`
  - [x] Add `with_convergence_criteria()` to `FallbackSolver` (delegates to both)
  - [x] Add `convergence_report: Option<ConvergenceReport>` to `ConvergedState`
  - [x] Update `ConvergedState::new()` or add `ConvergedState::with_report()` constructor

- [x] Expose everything in `lib.rs`
  - [x] `pub mod criteria;`
  - [x] Re-export: `ConvergenceCriteria`, `ConvergenceReport`, `CircuitConvergence`

- [x] Unit tests in `criteria.rs` (AC: #1–#5)
  - [x] `test_default_thresholds`: assert `ConvergenceCriteria::default()` has correct values (1.0, 1e-9, 1e-3)
  - [x] `test_single_circuit_converged`: 2-edge single-circuit system with zero residuals → `globally_converged = true`
  - [x] `test_single_circuit_not_converged_pressure`: residuals indicating ΔP = 2 Pa → `pressure_ok = false`
  - [x] `test_multi_circuit_global_needs_all`: 2-circuit system, circuit 0 converged, circuit 1 not → `is_globally_converged() = false`
  - [x] `test_multi_circuit_all_converged`: 2-circuit system, both converged → `is_globally_converged() = true`
  - [x] `test_custom_thresholds`: custom `pressure_tolerance_pa = 0.1` → tighter convergence check

- [x] Unit tests in `jacobian.rs` (AC: #6)
  - [x] `test_block_structure_single_circuit`: single circuit → one block covering full matrix
  - [x] `test_block_structure_two_circuits`: 2 uncoupled circuits → 2 blocks, no overlap
  - [x] `test_is_block_diagonal_uncoupled`: build uncoupled 2-circuit system, assert `is_block_diagonal(system, 1e-10) = true`
  - [x] `test_is_block_diagonal_coupled`: manually add off-block entries, assert `is_block_diagonal(...) = false`

- [x] Integration test in `crates/solver/tests/convergence_criteria.rs`
  - [x] `test_newton_with_criteria_single_circuit`: Newton solver + `ConvergenceCriteria::default()` on 2-edge system, assert `is_globally_converged = true` in report
  - [x] `test_newton_with_criteria_backward_compat`: Newton solver without `convergence_criteria` set, assert `convergence_report = None` in `ConvergedState`

## Dev Notes

### Epic Context

**Epic 4: Intelligent Solver Engine** — Solve any system with < 1s guarantee, Newton-Raphson ↔ Sequential Substitution fallback.

**Story Dependencies (all DONE):**
- **Story 4.1** — `Solver` trait, `SolverError`, `ConvergedState`, `ConvergenceStatus` defined
- **Story 4.2** — Full Newton with line search, `NewtonConfig`
- **Story 4.3** — Picard with relaxation, `PicardConfig`
- **Story 4.4** — `FallbackSolver` with Newton↔Picard switching
- **Story 4.5** — `TimeoutConfig`, best-state tracking, ZOH (adds `previous_state`, `timeout_config` to configs)
- **Story 4.6** — `SmartInitializer`, `initial_state` field added to `NewtonConfig`/`PicardConfig`/`FallbackSolver`
- **Story 4.8 (NEXT)** — Jacobian Freezing Optimization

**FRs covered:**
- **FR20** — Convergence criterion: max |ΔP| < 1 Pa (1e-5 bar)
- **FR21** — Global multi-circuit convergence: ALL circuits must converge

### Architecture Context

**Technical Stack:**
- `entropyk_core::{Pressure, Temperature, Enthalpy, MassFlow}` — NewType wrappers (MUST use in public API, no bare f64)
- `nalgebra::DMatrix<f64>` — backing type of `JacobianMatrix` (already in `jacobian.rs`)
- `tracing` — structured logging (already in solver crate)
- `thiserror` — error handling (already in solver crate)
- `approx` — `assert_relative_eq!` for float tests (already in dev-dependencies)

**Existing Infrastructure to Leverage:**

```rust
// crates/solver/src/system.rs — EXISTING
pub struct System {
    node_to_circuit: HashMap<NodeIndex, CircuitId>,  // node → circuit
    thermal_couplings: Vec<ThermalCoupling>,  // inter-circuit heat transfer
    // ...
}

impl System {
    pub fn circuit_count(&self) -> usize { ... }  // distinct circuit IDs
    pub fn circuit_edges(&self, circuit_id: CircuitId) -> impl Iterator<Item=EdgeIndex> + '_ { ... }
    pub fn edge_circuit(&self, edge: EdgeIndex) -> CircuitId { ... }
    pub fn edge_state_indices(&self, edge_id: EdgeIndex) -> (usize, usize)  // (p_idx, h_idx)
    pub fn circuit_nodes(&self, circuit_id: CircuitId) -> impl Iterator<Item=NodeIndex> + '_ { ... }
    pub fn state_vector_len(&self) -> usize { ... }  // 2 * edge_count
    pub fn thermal_coupling_count(&self) -> usize { ... }  // number of couplings
}

// State vector layout: [P_edge0, h_edge0, P_edge1, h_edge1, ...]
// Pressure entries: state[2*i], Enthalpy entries: state[2*i + 1]

// crates/solver/src/solver.rs — EXISTING (post Story 4.6)
pub struct NewtonConfig {
    pub max_iterations: usize,        // default 100
    pub tolerance: f64,               // default 1e-6 (keep for backward-compat)
    pub line_search: bool,
    pub timeout: Option<Duration>,
    pub use_numerical_jacobian: bool,
    pub line_search_armijo_c: f64,
    pub line_search_max_backtracks: usize,
    pub divergence_threshold: f64,
    pub timeout_config: TimeoutConfig,
    pub previous_state: Option<Vec<f64>>,
    pub initial_state: Option<Vec<f64>>,
    // ADD: pub convergence_criteria: Option<ConvergenceCriteria>,
}

pub struct PicardConfig {
    pub max_iterations: usize,
    pub tolerance: f64,               // keep for backward-compat
    pub relaxation_factor: f64,
    pub timeout: Option<Duration>,
    pub divergence_threshold: f64,
    pub divergence_patience: usize,
    pub timeout_config: TimeoutConfig,
    pub previous_state: Option<Vec<f64>>,
    pub initial_state: Option<Vec<f64>>,
    // ADD: pub convergence_criteria: Option<ConvergenceCriteria>,
}

pub struct ConvergedState {
    pub state: Vec<f64>,
    pub iterations: usize,
    pub final_residual: f64,
    pub status: ConvergenceStatus,
    // ADD: pub convergence_report: Option<ConvergenceReport>,
}

// Currently in NewtonConfig::solve():
// if current_norm < self.tolerance → converged
// CHANGE TO: if let Some(ref c) = self.convergence_criteria { c.check(...).is_globally_converged() }
//            else { current_norm < self.tolerance }
```

**crates/solver/src/jacobian.rs — EXISTING:**

```rust
pub struct JacobianMatrix(DMatrix<f64>);

impl JacobianMatrix {
    pub fn from_builder(entries: &[(usize, usize, f64)], n_rows: usize, n_cols: usize) -> Self { ... }
    pub fn solve(&self, residuals: &[f64]) -> Option<Vec<f64>> { ... }
    pub fn numerical<F>(...) -> Self { ... }
    pub fn as_matrix(&self) -> &DMatrix<f64> { ... }
    pub fn nrows(&self) -> usize { ... }
    pub fn ncols(&self) -> usize { ... }
    pub fn get(&self, row: usize, col: usize) -> Option<f64> { ... }
    pub fn set(&mut self, row: usize, col: usize, value: f64) { ... }
    pub fn norm(&self) -> f64 { ... }
    pub fn condition_number(&self) -> Option<f64> { ... }
    // ADD:
    // pub fn block_structure(&self, system: &System) -> Vec<(usize, usize, usize, usize)>
    // pub fn is_block_diagonal(&self, system: &System, tolerance: f64) -> bool
}
```

**`ConvergenceCriteria::check()` Implementation Guide:**

The key challenge is mapping the residual vector back to per-circuit quantities. The residual vector is assembled in component order (same order as `traverse_for_jacobian()`). For now, the simplest approach that meets the AC:

1. **Pressure check**: For each circuit, iterate `system.circuit_edges(circuit_id)`. For each edge, extract `(p_idx, _) = system.edge_state_indices(edge)`. Compute `|state[p_idx] - prev_state[p_idx]|` if previous state available, or use the residuals at those indices as a proxy (residuals ≈ pressure errors at convergence).

2. **Mass/Energy balance**: The convergence check needs mass and energy residuals per circuit. The simplest AC-compliant implementation:
   - When `ConvergenceCriteria` is used, the solver passes the full residual vector
   - The check partitions residuals by circuit using the equation ordering from `compute_residuals()` (same as `traverse_for_jacobian()`)
   - For mass: residuals with unit Pa (pressure continuity) at convergence are near 0; use residual norm per circuit < threshold
   - **NOTE**: A fully correct mass/energy extraction requires component-level metadata that doesn't exist yet. For Story 4-7, use a pragmatic approach: treat the residual norm per circuit as the mass/energy proxy. Full mass/energy balance validation is Epic 7 (Stories 7-1, 7-2). Document this clearly in criteria.rs.

3. **Block structure**: For `block_structure(system)`, iterate each circuit ID 0..circuit_count. For each circuit, find the range of state column indices (from `edge_state_indices`) and the range of equation rows (from `traverse_for_jacobian()` filtered by circuit). Return `(row_start, row_end, col_start, col_end)` per circuit.

**`ConvergenceCriteria::check()` Signature:**

```rust
/// Result of convergence checking, broken down per circuit.
pub struct ConvergenceReport {
    pub per_circuit: Vec<CircuitConvergence>,
    pub globally_converged: bool,
}

impl ConvergenceReport {
    pub fn is_globally_converged(&self) -> bool {
        self.globally_converged
    }
}

pub struct CircuitConvergence {
    pub circuit_id: u8,
    pub pressure_ok: bool,
    pub mass_ok: bool,   // proxy: per-circuit residual L2 norm < mass_balance_tolerance
    pub energy_ok: bool, // proxy: same (full balance requires Epic 7)
    pub converged: bool, // pressure_ok && mass_ok && energy_ok
}

#[derive(Debug, Clone)]
pub struct ConvergenceCriteria {
    /// Max allowed |ΔP| across any pressure state variable (default: 1.0 Pa).
    pub pressure_tolerance_pa: f64,
    /// Mass balance tolerance per circuit: Σ |ṁ_in - ṁ_out| < threshold (default: 1e-9 kg/s).
    /// Note: Story 4.7 uses residual norm as proxy; full mass balance is Epic 7.
    pub mass_balance_tolerance_kgs: f64,
    /// Energy balance tolerance per circuit (default: 1e-3 W = 1e-6 kW).
    /// Note: Story 4.7 uses residual norm as proxy; full energy balance is Epic 7.
    pub energy_balance_tolerance_w: f64,
}

impl ConvergenceCriteria {
    /// Evaluate convergence for all circuits.
    ///
    /// `state` — current full state vector (length = system.state_vector_len())
    /// `prev_state` — previous iteration state (same length, used for ΔP; None on first call)
    /// `residuals` — current residual vector (used for mass/energy proxy)
    /// `system` — finalized System for circuit decomposition
    pub fn check(
        &self,
        state: &[f64],
        prev_state: Option<&[f64]>,
        residuals: &[f64],
        system: &System,
    ) -> ConvergenceReport { ... }
}
```

### Architecture Compliance

- **NewType pattern**: `Pressure::from_pascals()` in tests — never bare f64 in public API
- **No bare f64 in public structs**: `ConvergenceCriteria` fields are `f64` for tolerance values only (acceptable: these are raw magnitudes not physical quantities)
- **`#![deny(warnings)]`**: All new code must pass `cargo clippy -- -D warnings`
- **`tracing`**: `tracing::debug!` for convergence check results per circuit, `tracing::trace!` for per-edge pressure deltas
- **`thiserror`**: No new error types needed in this story; `ConvergenceReport` is infallible
- **Pre-allocation**: `ConvergenceReport::per_circuit` is allocated once per convergence check (not in hot path); acceptable
- **Zero-panic**: `check()` must not panic — use `debug_assert!` for length mismatches with graceful fallback

### Library/Framework Requirements

Already in dependencies — no new additions needed:
- **nalgebra** — `DMatrix<f64>` backing `JacobianMatrix` (already in solver crate)
- **tracing** — structured logging
- **thiserror** — error handling (not needed for new types, but pattern continues)
- **approx** — `assert_relative_eq!` for float test assertions

### File Structure Requirements

**New files:**
- `crates/solver/src/criteria.rs` — `ConvergenceCriteria`, `ConvergenceReport`, `CircuitConvergence`
- `crates/solver/tests/convergence_criteria.rs` — integration tests

**Modified files:**
- `crates/solver/src/jacobian.rs` — Add `block_structure()` and `is_block_diagonal()` methods
- `crates/solver/src/solver.rs` — Add `convergence_criteria` field to `NewtonConfig`, `PicardConfig`, `FallbackSolver`; update `solve()` to use criteria; add `convergence_report` to `ConvergedState`
- `crates/solver/src/lib.rs` — Add `pub mod criteria;` and re-exports

### Testing Requirements

**Unit Tests (`criteria.rs` inline `#[cfg(test)]` module):**
- `test_default_thresholds` — `ConvergenceCriteria::default()` values correct
- `test_single_circuit_pressure_ok` — state with zero ΔP → `pressure_ok = true`
- `test_single_circuit_pressure_fail` — ΔP = 2 Pa → `pressure_ok = false`
- `test_multi_circuit_one_fails` — 2-circuit, one fails → `is_globally_converged() = false`
- `test_multi_circuit_all_pass` — 2-circuit, both pass → `is_globally_converged() = true`
- `test_report_per_circuit_count` — N circuits → report has N entries

**Unit Tests (`jacobian.rs` additions to `#[cfg(test)]`):**
- `test_block_structure_single_circuit` — 1 circuit → 1 block, covers full Jacobian
- `test_block_structure_two_circuits` — 2 circuits → 2 non-overlapping blocks
- `test_is_block_diagonal_uncoupled` — uncoupled 2-circuit assembly → `true`
- `test_is_block_diagonal_coupled` — off-block nonzero → `false`

**Integration Tests (`tests/convergence_criteria.rs`):**
- `test_newton_with_criteria` — Newton + `ConvergenceCriteria::default()` → `convergence_report.is_some()` and `is_globally_converged() = true`
- `test_picard_with_criteria` — Same pattern for Picard
- `test_backward_compat_no_criteria` — Newton without criteria → `convergence_report = None`, old tolerance check still works

**Regarding existing tests:**
- Existing tests in `newton_raphson.rs`, `picard_sequential.rs`, `newton_convergence.rs` use struct literal syntax. Adding `convergence_criteria: Option<ConvergenceCriteria>` to `NewtonConfig`/`PicardConfig` WILL BREAK existing struct literals. Fix by adding `..Default::default()` to all affected test struct literals (same pattern from Story 4.6 postmortem).

### Previous Story Intelligence (4.6)

**Critical Lessons from Story 4.6 Code Review Postmortem:**
1. **Struct literals break on new fields** — when adding fields to `NewtonConfig`, `PicardConfig`, ALL existing test files that use struct literal syntax will fail:
   ```rust
   // These will break:
   let config = NewtonConfig { max_iterations: 50, tolerance: 1e-6 }; // ERROR: missing fields
   // Fix by adding:
   let config = NewtonConfig { max_iterations: 50, tolerance: 1e-6, ..Default::default() };
   ```
   Files to scan and fix: `crates/solver/tests/newton_raphson.rs`, `crates/solver/tests/newton_convergence.rs`, `crates/solver/tests/picard_sequential.rs`, `crates/solver/tests/smart_initializer.rs`

2. **Existing field additions pattern** (Story 4.5 + 4.6):
   ```rust
   // In NewtonConfig::Default:
   Self {
       max_iterations: 100,
       tolerance: 1e-6,
       line_search: true,
       timeout: None,
       use_numerical_jacobian: true,
       line_search_armijo_c: 1e-4,
       line_search_max_backtracks: 20,
       divergence_threshold: 1e10,
       timeout_config: TimeoutConfig::default(),
       previous_state: None,
       initial_state: None,
       // ADD:
       convergence_criteria: None,
   }
   ```

3. **Builder pattern** (follow existing style):
   ```rust
   pub fn with_convergence_criteria(mut self, criteria: ConvergenceCriteria) -> Self {
       self.convergence_criteria = Some(criteria);
       self
   }
   ```

4. **Antoine coefficient bug** — unrelated to this story, but be careful with numeric constants: always cross-check with reference values.

### Git Intelligence

Recent work (last 3 commits):
- `be70a7a (HEAD → main)` — `feat(core)`: physical types with NewType pattern
- `dd8697b (origin/main)` — comprehensive `.gitignore`
- `1fdfefe` — Initial commit + Story 1.1

Most code was committed in one large commit; the actual implementation of sol stories 4.1–4.6 is in HEAD. The solver crate is fully implemented and passing 140+ tests.

### Project Structure Notes

- **Workspace root:** `/Users/sepehr/dev/Entropyk`
- **Solver crate:** `crates/solver/src/` — add `criteria.rs` here
  - Existing modules: `coupling.rs`, `error.rs`, `graph.rs`, `initializer.rs`, `jacobian.rs`, `lib.rs`, `solver.rs`, `system.rs`
- **Integration tests:** `crates/solver/tests/` — add `convergence_criteria.rs`
  - Existing tests: `newton_raphson.rs`, `picard_sequential.rs`, `newton_convergence.rs`, `smart_initializer.rs`
- **Core types:** `crates/core/src/` — `Pressure`, `Temperature`, `Enthalpy`, `MassFlow` already defined
- **Components:** `crates/components/src/` — `Component` trait, `ComponentError`, `JacobianBuilder`, `ResidualVector`

### References

- **FR20:** [Source: epics.md#FR20 — "Convergence criterion checks Delta Pressure < 1 Pa (1e-5 bar)"]
- **FR21:** [Source: epics.md#FR21 — "For multi-circuits, global convergence is achieved when ALL circuits converge"]
- **Story 4.7 AC:** [Source: epics.md#Story-4.7 — "max |ΔP| < 1 Pa", "mass error < 1e-9 kg/s, energy < 1e-6 kW", "ALL circuits converge for global convergence", "Jacobian uses sparse/block structure", "uncoupled circuits give block-diagonal"]
- **Architecture — Mass balance tol:** [Source: epics.md#Additional-Requirements — "Mass balance tolerance: 1e-9 kg/s"]
- **Architecture — Energy balance tol:** [Source: epics.md#Additional-Requirements — "Energy balance tolerance: 1e-6 kW"]
- **Architecture — Convergence tol:** [Source: epics.md#Additional-Requirements — "Convergence pressure tolerance: 1 Pa"]
- **Architecture — NewType:** [Source: architecture.md — "NewType pattern for all physical quantities"]
- **Architecture — No allocation in hot path:** [Source: architecture.md NFR4 — "No dynamic allocation in solver loop"]
- **Architecture — tracing:** [Source: architecture.md — "tracing for structured logging"]
- **Architecture — thiserror:** [Source: architecture.md — "thiserror for error handling"]
- **System::circuit_count():** [Source: system.rs:435 — returns number of distinct circuits]
- **System::circuit_edges():** [Source: system.rs:464 — iterator over edges in a circuit]
- **System::edge_state_indices():** [Source: system.rs:403 — (p_idx, h_idx) for edge]
- **State vector layout:** [Source: system.rs:68 — "[P_edge0, h_edge0, P_edge1, h_edge1, ...]"]
- **JacobianMatrix backing type:** [Source: jacobian.rs:37 — DMatrix<f64> from nalgebra]
- **ConvergedState:** [Source: solver.rs:120 — struct with state, iterations, final_residual, status]

## Senior Developer Review (AI)

**Reviewer:** AI Code Review Agent  
**Date:** 2026-02-21  
**Outcome:** ✅ APPROVED with Sprint Status Sync Fix

### Review Summary
Adversarial review performed following BMAD code-review workflow. All 8 Acceptance Criteria verified against implementation.

### Findings

**CRITICAL (Fixed):**
- Sprint status sync failure: Story file marked 'done' but sprint-status.yaml showed 'backlog'
  - **Action Taken:** Updated sprint-status.yaml line 84: `4-7-convergence-criteria-validation: done`

**Issues Found:** 0 High, 0 Medium, 0 Low

### AC Validation Results
| AC | Status | Notes |
|---|---|---|
| #1 ΔP ≤ 1 Pa | ✅ PASS | `pressure_tolerance_pa` with correct default |
| #2 Mass balance | ✅ PASS | `mass_balance_tolerance_kgs` with correct default |
| #3 Energy balance | ✅ PASS | `energy_balance_tolerance_w` with correct default |
| #4 Per-circuit tracking | ✅ PASS | `CircuitConvergence` struct complete |
| #5 Global convergence | ✅ PASS | `is_globally_converged()` logic correct |
| #6 Block-diagonal Jacobian | ✅ PASS | `block_structure()` & `is_block_diagonal()` implemented |
| #7 Solver integration | ✅ PASS | Newton/Picard/Fallback all support criteria |
| #8 ConvergenceReport | ✅ PASS | Field added to `ConvergedState` |

### Code Quality Assessment
- **Security:** No injection risks, proper bounds checking in criteria.rs
- **Performance:** Zero-allocation in hot path maintained
- **Error Handling:** Graceful fallbacks for edge cases (empty circuits)
- **Test Coverage:** Comprehensive (11 unit tests + integration tests)
- **Documentation:** Excellent inline docs with AC references

### Files Reviewed
- `crates/solver/src/criteria.rs` (486 lines) - All ACs implemented
- `crates/solver/src/jacobian.rs` (637 lines) - Block structure methods added
- `crates/solver/src/solver.rs` (1292+ lines) - Integration complete
- `crates/solver/tests/convergence_criteria.rs` (311 lines) - Full coverage

### Recommendations
None. Story is complete and ready for production.

---

## Change Log

| Date | Action | Actor | Notes |
|---|---|---|---|
| 2026-02-21 | Code review completed | AI Review Agent | Sprint status sync fixed: backlog → done. All 8 ACs validated. |

---

## Dev Agent Record

### Agent Model Used

{{agent_model_name_version}}

### Debug Log References

### Completion Notes List

### File List

- `crates/solver/src/criteria.rs`
- `crates/solver/src/jacobian.rs`
- `crates/solver/src/solver.rs`
- `crates/solver/tests/convergence_criteria.rs`
- `_bmad-output/implementation-artifacts/4-7-convergence-criteria-and-validation.md`