# Jacobian Health Report (Epic 0 / Story 0.5)

**Date:** 2026-07-18  
**Gate:** `cargo test -p entropyk-components --test jacobian_health_sweep`  
**Harness:** `entropyk_components::jacobian_fd`  
**Allow-list:** empty for Epic-0 P0 surfaces (`EPIC0_ALLOW_LIST` in the test binary)

## How to regenerate

1. Run:
   ```bash
   cargo test -p entropyk-components --test jacobian_health_sweep -- --nocapture
   ```
2. Confirm all gated tests pass.
3. Manually sync this markdown if grids, configs, or statuses change.
   Default CI tests do **not** rewrite this file (avoids dirty working trees).

Optional machine-readable twin: `docs/audits/jacobian-health-report.json`.

---

## Config presets

| Preset | `rel_epsilon` | `h_floor` | `rel_tol` | Notes |
|--------|---------------|-----------|-----------|-------|
| `DEFAULT_CFG` | `1e-6` | `1e-3` | `1e-4` | Documented default |
| `EDGE_CFG` | `1e-6` | `1e-6` | `1e-4` | C¹ `smooth_clamp` neighborhoods / actuator edges |

---

## Status matrix (gated surfaces)

| Surface | Region / probes | Config | Status | Notes |
|---------|-----------------|--------|--------|-------|
| `valve_flow` / `IsenthalpicOrifice` | openings `{0,0.5,1}` × `{ΔP>0, ΔP≤0}` | helper FD / phantom checks | `clean` | Informative `dp_up` at ΔP≤0; `dp_down` FD at interior ΔP>0 |
| `valve_flow` / `ExvCdA` | same grid | helper FD / phantom checks | `clean` | Same as orifice model |
| `exv_orifice` | openings `{0,0.5,1}` × `{dp_positive, dp_le_0}` | `EDGE_CFG` | `clean` | `assert_jacobian_healthy` via allow-list (empty) |
| `condenser_fan` | `φ ∈ {0.005, 0.75, 1.495}` | `EDGE_CFG` | `clean` | Inside C¹ ramps (not exact kink) |
| `condenser_flood` | `λ ∈ {0.005, 0.5, 0.975}` | `EDGE_CFG` | `clean` | Inside C¹ ramps |
| `two_phase_quality` | interior `0.5`, near-band `0.005`, exterior `-0.2` / `1.2` | helper checks | `clean` | Soft≠hard in band; exterior saturates |
| `msh_dome_edge` | quality `{0.5,0.8,0.90,0.95,0.99,0.999,1−ε}` | central FD on `msh_gradient` | `clean` | Bounded `∂g/∂x` across Hermite blend |

---

## Deferred debt (not probed — do not allow-list P0)

These remain documented debt and are **out of the Epic-0 gate**. Adding probes later requires either a fix or an explicit allow-list entry with rationale in this file and the audit catalogue.

| Item | Reason | Status |
|------|--------|--------|
| `heat_exchanger/exchanger.rs` 4-port production FD Jacobian | NFR9 — analytic path is already FD | not probed |
| `python_components*` empty / stub Jacobians | Binding stubs | not probed |
| `screw_economizer_compressor` incomplete analytic rows / P1 clamps | Separate remediation | not probed |
| `sat_domain.rs` P1 pressure clamp | Deferred P1 | not probed |
| `bphx_correlation` P2 quality clamps | Correlation-local P2 | not probed |

---

## NFR11 attribution (pending Story 2.6)

Epic 0 regularized P0 Jacobian killers (valve ΔP≤0 phantom gradients, EXV opening C¹ clamps, two-phase quality / condenser fan-flood C¹, MSH Hermite near x→1).  

First-try convergence % across the operating envelope (`T_source` / `T_sink` / load / fluid) will be measured by **Story 2.6** robustness-sweep infrastructure.  

**Before/after delta attributable to Epic 0 regularization: TBD** (fill when Story 2.6 lands). Do not invent placeholder percentages.