Entropyk/docs/audits/jacobian-health-report.md

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:

   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.