iapws-if97 2.1.5 → 2.8.0

package/CHANGELOG.md

@@ -1,6 +1,37 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## 2.8.0 (2026-10-20)
+
+### Added
+
+- Add `solveBasic(input)` and exported `BasicProperties` for all eight modes, without density or transport fields.
+- Include liquid and vapor endpoints in Region 4 `saturation` (`SaturationEndpoints`), including at `x = 0` and `x = 1`.
+- Test backward and boundary equations against official IAPWS values at their printed precision, including all 26 Region 3 `v(p,T)` subregions.
+
+### Changed
+
+- Remove decimal snapping and backward property input overwrites. Region 3 PT preserves input pressure after checking equation-of-state (EOS) convergence.
+- Throw `AmbiguousStateError`, an `IF97Error` subclass, when `TH`/`TS` inputs match multiple states. This applies to direct solvers, `solve`, `solveBasic`, and region detectors. Its `candidates` field contains validated basic states in ascending pressure order. Callers that previously received one branch must handle ambiguity.
+- Tighten ordinary backward enthalpy/entropy acceptance to `1e-9 × max(1, |input|)` and Region 3 PT pressure convergence to relative `1e-12`, with separate endpoint and fit-gap tolerances.
+- Shorten the README, move API details to `docs/reference.md`, and redraw the P–T region map.
+
+### Fixed
+
+- Correct 11 coefficient transcription errors in Region 1/3 `p(h,s)`, Region 3 `v(p,T)`, HS boundaries, and Region 2a `T(p,h)`/`T(p,s)`. Public `region3Volume` results change; refined solver results can differ in their last floating-point bits.
+- Search all valid `TH`/`TS` branches, including non-monotonic isotherms, subcritical Region 3 vapor, and roots near open endpoints. Preserve multiple candidates near the triple point; low-temperature `TS` can match two liquid states and wet steam.
+- Recover PH/PS and HS boundary roots and resolve region overlaps using `solvePT` boundary ownership. Recompute EOS properties after boundary normalization and revalidate input constraints before accepting candidates or fit-gap states.
+- Preserve saturation input pressure or temperature, endpoint quality, and phase selection at `623.15 K` and near critical conditions. Use extended precision for saturation equations and Region 3 pressure inversion. Throw `IF97Error` when a stable phase or distinct saturation endpoints cannot be constructed.
+- Correct global and pressure/entropy-dependent input limits. Reject out-of-range backward inputs while retaining valid boundary states; explain the triple-point lower bound in saturation errors.
+- Force bisection when two iterations fail to halve the Newton bracket, preserving roots with quantized residuals near the triple point.
+- Compute density as `1 / specificVolume`. Reject non-finite or non-positive viscosity, non-positive thermal-conductivity `cp`, and dielectric-constant inputs at or below `228 K`.
+
+## 2.2.0
+
+### Fixed
+
+- Improved backward-solver accuracy and performance.
+- Fixed saturation-region detection and package validation.
+- Requires Node.js `>=20.19.0`.
 
 ## 2.1.5
 

package/README.md

@@ -1,266 +1,129 @@
-# `iapws-if97`
+# iapws-if97
 
-Calculate industrial water and steam properties in Node.js and TypeScript, based on the [IAPWS-IF97](https://www.iapws.org/) standard (International Association for the Properties of Water and Steam — Industrial Formulation 1997).
+**Industrial water and steam properties for Node.js and TypeScript.**
 
-This library provides forward and backward state solvers, saturation solvers, and transport-property helpers for engineering calculations involving water and steam.
+Turn two known properties into a water or steam state using [IAPWS-IF97](https://iapws.org/technical-guidance/release/IF97-Rev). For steam tables, thermal-cycle calculations, and engineering tools.
 
-## Features
+[![CI](https://github.com/jltonghui/iapws-if97/actions/workflows/ci.yml/badge.svg)](https://github.com/jltonghui/iapws-if97/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/iapws-if97.svg)](https://www.npmjs.com/package/iapws-if97)
 
-- Covers IF97 Regions 1–5, including high-temperature Region 5
-- Forward, backward, and saturation solvers behind a consistent API
-- Transport properties: viscosity, thermal conductivity, surface tension, dielectric constant, and ionization constant
-- Verified against official IAPWS tables and published engineering references
+[API reference](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md) · [References](#references) · [Changelog](CHANGELOG.md)
 
-## Project Origin
+![IAPWS-IF97 pressure–temperature map showing Regions 1–5, the saturation curve, and the 100 MPa and 50 MPa pressure limits.](https://raw.githubusercontent.com/jltonghui/iapws-if97/main/assets/pics/if97-regions.svg)
 
-> `iapws-if97` is the core calculation engine behind the WeChat Mini Program "汽水计算器" (`wxid: wx7201fd1713b524e5`). Since its launch in 2019, it has served nearly 20,000 users. With the help of AI, this edition has been updated to incorporate `R11-24 (2024)`. I am open-sourcing it in the hope that it will help others with similar engineering needs.
+- Forward, backward, and saturation solvers for eight input pairs across IF97 Regions 1–5.
+- Saturation results include liquid and vapor endpoints.
+- Viscosity, thermal conductivity, surface tension, dielectric constant, and ionization constant where applicable.
+- ESM with TypeScript declarations and no runtime dependencies.
 
-<p align="right">-- Retired Thermodynamic Engineer, Shuping</p>
+## Start calculating
 
-## Installation
+Requires Node.js ≥20.19.0. Use ESM imports.
 
 ```bash
 npm install iapws-if97
 ```
 
-## Quick Start
+Save as `example.mjs` and run `node example.mjs`:
 
-```ts
-import { solve, solvePT, solvePx } from 'iapws-if97';
+```js
+import { solvePT } from 'iapws-if97';
 
-const a = solvePT(3, 300);
-const b = solve({ mode: 'PH', p: 3, h: a.enthalpy });
-const c = solvePx(1, 0.5);
+const steam = solvePT(3, 573.15); // 3 MPa, 300 °C
 
-console.log(a.enthalpy);   // kJ/kg
-console.log(b.temperature); // K
-console.log(c.quality);     // 0.5
+console.log(steam.enthalpy.toFixed(2)); // 2994.35 kJ/kg
+console.log(steam.density.toFixed(3));  // 12.319 kg/m³
 ```
 
-## Main API
+The result includes pressure, temperature, enthalpy, entropy, density, heat capacities, speed of sound, and applicable transport properties. [All fields and units →](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#solver-return-value)
 
-- `solvePT(p, T)` // `MPa`, `K`
-- `solvePH(p, h)` // `MPa`, `kJ/kg`
-- `solvePS(p, s)` // `MPa`, `kJ/(kg·K)`
-- `solveHS(h, s)` // `kJ/kg`, `kJ/(kg·K)`
-- `solveTH(T, h)` // `K`, `kJ/kg`
-- `solveTS(T, s)` // `K`, `kJ/(kg·K)`
-- `solvePx(p, x)` // `MPa`, quality `[0, 1]`
-- `solveTx(T, x)` // `K`, quality `[0, 1]`
-- `solve(input)` // same units as the selected `mode`
+## Use the properties you have
 
-Use `solve({ mode, ... })` when the input pair is determined at runtime:
-
-```ts
-import { solve } from 'iapws-if97';
-
-const state = solve({ mode: 'PT', p: 16, T: 823.15 });
-```
+| Known properties | Solver |
+| --- | --- |
+| Pressure + temperature | `solvePT(p, T)` |
+| Pressure + enthalpy | `solvePH(p, h)` |
+| Pressure + entropy | `solvePS(p, s)` |
+| Enthalpy + entropy | `solveHS(h, s)` |
+| Temperature + enthalpy | `solveTH(T, h)` |
+| Temperature + entropy | `solveTS(T, s)` |
+| Pressure + vapor quality | `solvePx(p, x)` |
+| Temperature + vapor quality | `solveTx(T, x)` |
 
-`solve` accepts both short-form and long-form property names:
+Use MPa, K, kJ/kg, and kJ/(kg·K) for pressure, temperature, enthalpy, and entropy. Vapor quality `x` is the vapor mass fraction, from `0` (saturated liquid) to `1` (saturated vapor).
 
-```ts
-const a = solve({ mode: 'PT', p: 16, T: 823.15 });
-const b = solve({ mode: 'PT', pressure: 16, temperature: 823.15 });
-```
+Use `solve()` when the input pair is chosen at runtime:
 
-Supported modes:
-
-```ts
-type SolveInput =
-  | { mode: 'PT'; p: number; T: number }
-  | { mode: 'PH'; p: number; h: number }
-  | { mode: 'PS'; p: number; s: number }
-  | { mode: 'HS'; h: number; s: number }
-  | { mode: 'Px'; p: number; x: number }
-  | { mode: 'Tx'; T: number; x: number }
-  | { mode: 'TH'; T: number; h: number }
-  | { mode: 'TS'; T: number; s: number };
-```
+```js
+import { solve } from 'iapws-if97';
 
-You can use either form for each property. If you provide both, their values must match.
-
-## Solver Return Value
-
-All solvers return a `SteamState` object containing both thermodynamic and transport properties:
-
-```ts
-type SteamState = {
-  region: Region;
-  pressure: number;
-  temperature: number;
-  specificVolume: number;
-  density: number;
-  internalEnergy: number;
-  entropy: number;
-  enthalpy: number;
-  cp: number | null;
-  cv: number | null;
-  speedOfSound: number | null;
-  quality: number | null;
-  viscosity: number | null;
-  thermalConductivity: number | null;
-  surfaceTension: number | null;
-  dielectricConstant: number | null;
-  ionizationConstant: number | null;
-  isobaricExpansion: number | null;
-  isothermalCompressibility: number | null;
-};
+const state = solve({ mode: 'PH', p: 3, h: 3000 });
 ```
 
-`SteamState` always uses canonical property names. 
-
-**Notes:**
-
-- `quality` is `null` for single-phase states — it is only defined on the saturation line.
-- In two-phase mixtures (`0 < x < 1`), `cp`, `cv`, `speedOfSound`, `isobaricExpansion`, `isothermalCompressibility`, `viscosity`, `thermalConductivity`, `dielectricConstant`, and `ionizationConstant` are `null`.
-- Saturation endpoints (`x = 0` or `x = 1`) still expose single-phase transport properties even though they carry Region 4 metadata.
-- `solvePT(p, T)` is a single-phase solver. On the subcritical saturation boundary it resolves to the liquid side.
-- `surfaceTension` is only available for Region 4 saturation states below the critical point; otherwise `null`.
-- `density` is provided directly — no need to invert `specificVolume`.
-- `ionizationConstant` is `null` outside the IAPWS validity range for that correlation.
-
-## Units
-
-- Pressure: `MPa`
-- Temperature: `K`
-- Specific volume: `m^3/kg`
-- Density: `kg/m^3`
-- Enthalpy, internal energy: `kJ/kg`
-- Entropy, heat capacities: `kJ/(kg·K)`
-- Speed of sound: `m/s`
-- Quality: dimensionless, `0`–`1` (saturation line only)
-- Viscosity: `Pa·s`
-- Thermal conductivity: `W/(m·K)`
-- Surface tension: `N/m`
-- Dielectric constant: dimensionless
-- Ionization constant (`pKw`): dimensionless
-- Isobaric expansion coefficient: `1/K`
-- Isothermal compressibility: `1/MPa`
-
-Any field typed as `number | null` returns `null` when the property is undefined for the given state.
-
-## Saturation Endpoint
-
-- Low-level Region 4 helpers stay mathematically permissive and high-level saturation state solvers are stricter:
-  - `solvePx(p, x)` accepts `Pt ≤ p < Pc`
-  - `solveTx(T, x)` accepts `Tt = 273.16 K ≤ T < Tc`
-- The true triple point is supported as a saturation-state boundary:
-  - `solvePx(Pt, x)` is valid
-  - `solveTx(Tt, x)` is valid
-- `273.15 K` is treated as a low-level extrapolation boundary only.
-- The exact critical point is never returned as a Region 4 state.
-- `solveTH(T, h)` and `solveTS(T, s)` keep a small exclusion band around `Tc` and reject inputs within `0.001 K` of the critical temperature.
-
-## Errors and Limits
-
-The library throws typed errors:
-
-| Error | Meaning |
-| --- | --- |
-| `OutOfRangeError` | Input is outside the supported IF97 range |
-| `ConvergenceError` | An internal iterative solve failed to converge |
-| `IF97Error` | Base class for all library-specific errors |
-
-## Validity Notes
+Long field names such as `pressure` and `enthalpy` are also accepted. Use [`solveBasic()`](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#thermodynamics-without-transport) when you only need thermodynamics; it skips transport calculations and omits `density`.
 
-- Thermodynamic properties follow IF97 validity ranges: up to `100 MPa` and `2273.15 K` (including Region 5).
-- Surface tension applies only along the saturation line below the critical point.
-- Thermal conductivity follows the IAPWS 2011 release.
-- Ionization constant follows the IAPWS 2024 revised release, valid for stable fluid states from `273.15 K` to `1273.15 K` and up to `1000 MPa`.
+## Work with saturation
 
-## Verification
+Specify quality to calculate saturated liquid, saturated vapor, or wet steam:
 
-The test suite covers:
+```js
+import { solvePx } from 'iapws-if97';
 
-- Official IF97 verification tables (Regions 1–5)
-- Backward-equation round-trip accuracy
-- Temperature-led backward round trips (`TH` and `TS`)
-- High-pressure Region 4 regressions
-- IAPWS R11-24 ionization-constant verification values
-- Coverage thresholds enforced locally
-- ASME and GB/T steam-table comparisons against published values
+const wet = solvePx(1, 0.9); // 1 MPa, 90% vapor by mass
 
-To run locally:
+console.log(wet.temperature.toFixed(2)); // 453.04 K
 
-```bash
-npm run build
-npm test
-npm run test:coverage
-npm run test:standards
+if (wet.saturation) {
+  const { liquid, vapor } = wet.saturation;
+  const latentHeat = vapor.enthalpy - liquid.enthalpy;
+  console.log(latentHeat.toFixed(2)); // 2014.44 kJ/kg
+}
 ```
 
-## Integration Validation
+Every saturation result includes `saturation.liquid` and `saturation.vapor` for phase properties and latent-heat calculations. Use `solveTx(T, x)` when temperature is known instead of pressure.
 
-![Mollier h-s diagram generated with iapws-if97](https://raw.githubusercontent.com/jltonghui/iapws-if97/main/assets/pics/mollier-hs-diagram.svg)
+## Before integrating
 
-This Mollier `h-s` diagram was generated with `iapws-if97` as a practical end-to-end validation artifact.
+- PT selects a single phase. Pressure and temperature alone do not determine wet-steam quality; use `Px` or `Tx` for a mixture.
+- Single-phase `quality` is `null`. Mixtures return `null` for heat capacities, speed of sound, and most transport properties. [Return-value details →](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#solver-return-value)
+- TH and TS throw `AmbiguousStateError` with candidate states when multiple solutions exist. Use pressure or quality to resolve the state. [Errors →](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#errors-and-limits)
+- The exact critical point is unsupported, and near-critical solves can fail. Transport correlations have separate validity ranges. [Numerical limits →](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#saturation-endpoints) · [Transport limits →](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#transport-correlation-limits)
 
-### ASME Validation Snapshot
-
-Compares saturation states against *ASME International Steam Tables for Industrial Use*, 3rd ed., Table S-2 ("Properties of Saturated Water and Steam — Pressure").
-Each case checks 7 values: saturation temperature, liquid/vapor specific volume, enthalpy, and entropy.
-The snapshot below reflects the current `tests/standards-asme` regression run.
-
-| ASME case | Pressure (MPa) | Points checked | Max relative error |
-| --- | ---: | ---: | ---: |
-| Table S-2 @ 0.01 MPa | 0.01 | 7 | 0.0257993% |
-| Table S-2 @ 0.10 MPa | 0.10 | 7 | 0.0141744% |
-| Table S-2 @ 1.00 MPa | 1.00 | 7 | 0.0207405% |
-| Table S-2 @ 5.0 MPa | 5.0 | 7 | 0.0315405% |
-| Table S-2 @ 10.0 MPa | 10.0 | 7 | 0.0261599% |
-| Table S-2 @ 20.0 MPa | 20.0 | 7 | 0.0173004% |
-| Overall worst case | - | 42 | 0.0315405% |
-
-The current ASME regression threshold is `maxRelativeError < 5e-4` (less than `0.05%`).
+| Thermodynamic temperature range | Maximum pressure |
+| --- | --- |
+| 273.15–1073.15 K | 100 MPa |
+| Above 1073.15 K, up to 2273.15 K | 50 MPa |
 
-### GB/T Validation Snapshot
+Saturation solvers accept 273.16 ≤ T < 647.096 K or 0.000611657 ≤ p < 22.064 MPa. All numeric inputs must be finite; invalid or unresolved states throw [typed errors](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#errors-and-limits).
 
-Compares superheated-steam states against *GB/T 34060-2017*, Table A.3(续), page 55.
-Each case checks 4 values at `10 MPa`: specific volume, enthalpy, entropy, and speed of sound.
-The snapshot below reflects the current `tests/standards-cn` regression run.
+## Verification and development
 
-| GB/T case | Pressure (MPa) | Temperature (°C) | Points checked | Max relative error |
-| --- | ---: | ---: | ---: | ---: |
-| Table A.3 @ 10 MPa, 350 C | 10 | 350 | 4 | 0.0007020% |
-| Table A.3 @ 10 MPa, 400 C | 10 | 400 | 4 | 0.0004650% |
-| Table A.3 @ 10 MPa, 500 C | 10 | 500 | 4 | 0.0006808% |
-| Table A.3 @ 10 MPa, 600 C | 10 | 600 | 4 | 0.0005630% |
-| Table A.3 @ 10 MPa, 700 C | 10 | 700 | 4 | 0.0004072% |
-| Table A.3 @ 10 MPa, 800 C | 10 | 800 | 4 | 0.0004146% |
-| Overall worst case | - | - | 24 | 0.0007020% |
+Tests cover official IAPWS verification values, backward-solver round trips, region boundaries, and published ASME and GB/T steam tables. CI also checks TypeScript types, package exports, and coverage thresholds. [Verification details and references →](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#verification)
 
-The current GB/T regression threshold is `maxRelativeError < 5e-4` (less than `0.05%`).
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run test:package
+```
 
-## TypeScript
+For low-level region equations, saturation curves, transport correlations, or region detection, see [advanced imports](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#advanced-imports).
 
-The package ships with bundled TypeScript declarations and ESM exports.
+## References
 
-```ts
-import type { SolveInput, SteamState } from 'iapws-if97';
-import { Region, solve } from 'iapws-if97';
+- [IAPWS R7-97(2012), Industrial Formulation 1997](https://iapws.org/technical-guidance/release/IF97-Rev).
+- [IAPWS supplementary releases](https://iapws.org/technical-guidance/release) for alternative input pairs, region boundaries, and Region 3 specific volume.
+- [R12-08, viscosity](https://iapws.org/technical-guidance/release/viscosity) and [R15-11, thermal conductivity](https://iapws.org/technical-guidance/release/ThCond).
+- [R1-76(2014), surface tension](https://iapws.org/technical-guidance/release/Surf-H2O), [R8-97, dielectric constant](https://iapws.org/technical-guidance/release/Dielec), and [R11-24, ionization constant](https://iapws.org/technical-guidance/release/Ionization).
 
-const input: SolveInput = { mode: 'PT', p: 3, T: 300 };
-const state: SteamState = solve(input);
+See the [full reference list](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#references) for release details.
 
-if (state.region === Region.Region1) {
-  console.log('compressed liquid');
-}
-```
+## Project origin
 
-## References
+> `iapws-if97` began as the calculation engine behind the WeChat Mini Program "汽水计算器" (`wxid: wx7201fd1713b524e5`). Since its 2019 launch, it has served more than 20,000 users. AI-assisted review helped bring this open-source edition up to date with IAPWS `R11-24 (2024)`. I am sharing the engine so it can reach engineers far beyond the original program.
 
-- [IAPWS official website](https://www.iapws.org/)
-- IAPWS R7-97(2012), Revised Release on the IAPWS Industrial Formulation 1997 for the Thermodynamic Properties of Water and Steam
-- IAPWS supplementary releases for backward equations `T(p,h)`, `T(p,s)`, and `p(h,s)`
-- IAPWS R15-11, Thermal Conductivity of Ordinary Water Substance
-- IAPWS R1-76(2014), Surface Tension of Ordinary Water Substance
-- IAPWS R11-24, Revised Release on the Ionization Constant of H2O
+<p align="right">Shuping, retired thermodynamic engineer</p>
 
 ## License
 
-MIT
-
-## Disclaimer
-
-This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability arising from the use of this software.
+[MIT](LICENSE)

package/dist/backward/candidate-resolution.d.ts

@@ -0,0 +1,8 @@
+import type { FormulationSeamResolution } from '../core/formulation-seams.js';
+import { type BasicProperties } from '../types.js';
+import { type BackwardConstraint } from './solution-validation.js';
+/** Exhaust nearby roots before applying inverse seam and saturation ownership. */
+export declare function resolveBackwardCandidates(attempts: readonly (() => BasicProperties | null)[], constraints: readonly BackwardConstraint[], options: {
+    solverName: string;
+    seam?: FormulationSeamResolution;
+}): BasicProperties | null;

package/dist/backward/candidate-resolution.js

@@ -0,0 +1,40 @@
+import { NumericalStateError, RegionMismatchError } from '../errors.js';
+import { IF97Error, Region } from '../types.js';
+import { backwardCandidateError, normalizeBackwardState, validateBackwardState, } from './solution-validation.js';
+/** Exhaust nearby roots before applying inverse seam and saturation ownership. */
+export function resolveBackwardCandidates(attempts, constraints, options) {
+    const candidates = [];
+    let failure = null;
+    for (const attempt of attempts) {
+        try {
+            let state = attempt();
+            if (state !== null) {
+                let error = backwardCandidateError(state, constraints, options);
+                if (error instanceof RegionMismatchError) {
+                    state = normalizeBackwardState(state, constraints, options.solverName);
+                    error = backwardCandidateError(state, constraints, options);
+                }
+                if (error === null)
+                    candidates.push(state);
+                else if (error instanceof NumericalStateError)
+                    failure ??= error;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof IF97Error))
+                throw error;
+            if (!(error instanceof RegionMismatchError))
+                failure ??= error;
+        }
+    }
+    const saturated = candidates.find(({ region }) => region === Region.Region4);
+    const owned = candidates.find(({ region }) => region === options.seam?.pair.canonical.region);
+    if (candidates.length > 0)
+        return saturated ?? owned ?? candidates[0];
+    if (failure !== null)
+        throw failure;
+    if (options.seam !== undefined && options.seam.kind === 'gap') {
+        return validateBackwardState(options.seam.state, constraints, options);
+    }
+    return null;
+}

package/dist/backward/fixed-temperature-candidates.d.ts

@@ -0,0 +1,4 @@
+import type { BasicProperties } from '../types.js';
+import { type FixedTemperatureProperty } from './fixed-temperature-solver.js';
+/** Return the only physical TH/TS state, or null if unresolved; proven envelope violations throw. */
+export declare function uniqueFixedTemperatureState(T: number, target: number, property: FixedTemperatureProperty): BasicProperties | null;

package/dist/backward/fixed-temperature-candidates.js

@@ -0,0 +1,188 @@
+import * as C from '../constants.js';
+import { solveRegion3PTBasic } from '../core/region3-pt.js';
+import { nextPositiveFloat } from '../core/floating-point.js';
+import { NumericalStateError } from '../errors.js';
+import { formulationSeamAtTemperature, matchFixedSeam } from '../core/formulation-seams.js';
+import { boundary23_T_to_P } from '../regions/boundaries.js';
+import { region1 } from '../regions/region1.js';
+import { region2 } from '../regions/region2.js';
+import { region5 } from '../regions/region5.js';
+import { mixSaturationState, qualityFromSaturationProperty, saturationEndpointsAtTemperature, } from '../saturation/common.js';
+import { AmbiguousStateError, OutOfRangeError } from '../types.js';
+import { createFixedTemperatureStationaryPressureFinder } from './fixed-temperature-stationary.js';
+import { solveFixedTemperaturePressure } from './fixed-temperature-solver.js';
+import { backwardCandidateError, validateBackwardState } from './solution-validation.js';
+import { fixedTemperatureRootTolerance } from './tolerances.js';
+/** Return the only physical TH/TS state, or null if unresolved; proven envelope violations throw. */
+export function uniqueFixedTemperatureState(T, target, property) {
+    if (!Number.isFinite(T) || !Number.isFinite(target) || T < C.T_MIN || T > C.T_MAX) {
+        return null;
+    }
+    const solverName = property === 'enthalpy' ? 'solveTH' : 'solveTS';
+    const rootTolerance = fixedTemperatureRootTolerance(property);
+    const constraints = [
+        { label: 'temperature', expected: T },
+        { label: property, expected: target },
+    ];
+    const candidates = [];
+    let propertyMin = Infinity;
+    let propertyMax = -Infinity;
+    let finiteEnvelope = true;
+    const seamPair = formulationSeamAtTemperature(T);
+    const seam = seamPair === null ? null : matchFixedSeam(seamPair, property, target, 'temperature');
+    const incidentCandidates = new Set();
+    const stationaryPressures = createFixedTemperatureStationaryPressureFinder(T, property);
+    const sameState = (first, second) => Math.abs(first.pressure - second.pressure) <= 1e-9 * Math.max(1, Math.abs(second.pressure)) &&
+        Math.abs(first.specificVolume - second.specificVolume) <=
+            1e-9 * Math.max(first.specificVolume, second.specificVolume);
+    const add = (state, incident = false) => {
+        if (state !== seam?.state) {
+            const error = backwardCandidateError(state, constraints, { solverName });
+            if (error instanceof NumericalStateError)
+                throw error;
+            if (error !== null)
+                return;
+        }
+        // The same saturation endpoint or stationary point can bound two intervals.
+        let existing = candidates.find((other) => sameState(other, state));
+        if (existing !== undefined && incident && seam?.kind === 'overlap' &&
+            state.region === seam.state.region && existing.region !== state.region) {
+            candidates[candidates.indexOf(existing)] = state;
+            incidentCandidates.delete(existing);
+            existing = state;
+        }
+        if (existing === undefined) {
+            candidates.push(state);
+        }
+        if (incident)
+            incidentCandidates.add(existing ?? state);
+    };
+    const addInterval = (evaluator, lower, upper, includeLower = true, includeUpper = true) => {
+        if (upper.pressure < lower.pressure ||
+            ((!includeLower || !includeUpper) && upper.pressure === lower.pressure))
+            return;
+        const stateAt = (p, temperature) => {
+            if (p === lower.pressure)
+                return lower;
+            if (p === upper.pressure)
+                return upper;
+            return evaluator(p, temperature);
+        };
+        const points = [
+            lower,
+            ...stationaryPressures(lower, upper)
+                .map((p) => stateAt(p, T)),
+            upper,
+        ];
+        const lowerIncident = seamPair !== null && lower.pressure === seamPair.pressure;
+        const upperIncident = seamPair !== null && upper.pressure === seamPair.pressure;
+        for (let i = 0; i < points.length; i++) {
+            const current = points[i];
+            if (Number.isFinite(current[property])) {
+                propertyMin = Math.min(propertyMin, current[property]);
+                propertyMax = Math.max(propertyMax, current[property]);
+            }
+            else {
+                finiteEnvelope = false;
+            }
+            const residual = current[property] - target;
+            const currentIncluded = (i > 0 || includeLower) && (i < points.length - 1 || includeUpper);
+            const currentMatches = Math.abs(residual) <= rootTolerance &&
+                (currentIncluded || candidates.some((other) => sameState(other, current)));
+            if (currentMatches && currentIncluded) {
+                add(current, (i === 0 && lowerIncident) || (i === points.length - 1 && upperIncident));
+            }
+            if (!currentIncluded && Math.abs(residual) <= rootTolerance && !currentMatches) {
+                // The closest admissible float is the endpoint of the supported pressure domain.
+                const pressure = nextPositiveFloat(current.pressure, i === 0 ? 1 : -1);
+                if (pressure > lower.pressure && pressure < upper.pressure) {
+                    const interior = stateAt(pressure, T);
+                    if (Math.abs(interior[property] - target) <= rootTolerance) {
+                        add(interior, (i === 0 && lowerIncident) || (i === points.length - 1 && upperIncident));
+                    }
+                }
+            }
+            if (i === 0)
+                continue;
+            const previous = points[i - 1];
+            const previousResidual = previous[property] - target;
+            const previousIncluded = i > 1 || includeLower;
+            const previousMatches = Math.abs(previousResidual) <= rootTolerance &&
+                (previousIncluded || candidates.some((other) => sameState(other, previous)));
+            // An excluded endpoint cannot hide a root just inside its open interval.
+            if (currentMatches || previousMatches ||
+                previousResidual * residual >= 0)
+                continue;
+            add(solveFixedTemperaturePressure(stateAt, T, target, previous.pressure, current.pressure, property, solverName, previousIncluded, currentIncluded), (i === 1 && lowerIncident) || (i === points.length - 1 && upperIncident));
+        }
+    };
+    if (T > C.R5_T_MIN) {
+        addInterval(region5, region5(C.P_MIN, T), region5(C.R5_P_MAX, T));
+    }
+    else if (T >= C.B23_T_MAX) {
+        addInterval(region2, region2(C.P_MIN, T), region2(C.P_MAX, T));
+    }
+    else if (T >= C.Tc) {
+        const p23 = Math.min(C.P_MAX, boundary23_T_to_P(T));
+        addInterval(region2, region2(C.P_MIN, T), region2(p23, T), true, false);
+        addInterval(solveRegion3PTBasic, solveRegion3PTBasic(p23, T), solveRegion3PTBasic(C.P_MAX, T));
+    }
+    else {
+        const endpoints = saturationEndpointsAtTemperature(T);
+        if (T >= C.Tt &&
+            target >= endpoints.liquid[property] - rootTolerance &&
+            target <= endpoints.vapor[property] + rootTolerance) {
+            add(mixSaturationState(endpoints, qualityFromSaturationProperty(endpoints.liquid[property], endpoints.vapor[property], target)));
+        }
+        if (T <= C.R2_T_MIN) {
+            addInterval(region1, region1(endpoints.pressure, T), region1(C.P_MAX, T));
+            addInterval(region2, region2(C.P_MIN, T), region2(endpoints.pressure, T), true, false);
+        }
+        else {
+            const p23 = boundary23_T_to_P(T);
+            addInterval(region2, region2(C.P_MIN, T), region2(Math.min(p23, endpoints.pressure), T), true, false);
+            // Keep the vapor and liquid Region 3 branches separate at saturation.
+            addInterval(solveRegion3PTBasic, solveRegion3PTBasic(p23, T), endpoints.vapor);
+            addInterval(solveRegion3PTBasic, endpoints.liquid, solveRegion3PTBasic(C.P_MAX, T));
+        }
+    }
+    if (seam !== null) {
+        if (seam.kind === 'canonical') {
+            for (let i = candidates.length - 1; i >= 0; i--) {
+                if (incidentCandidates.has(candidates[i]))
+                    candidates.splice(i, 1);
+            }
+            add(seam.state);
+        }
+        else if (seam.kind === 'overlap') {
+            const canonical = candidates.find((state) => incidentCandidates.has(state) &&
+                state.region === seam.pair.canonical.region);
+            if (canonical !== undefined) {
+                for (let i = candidates.length - 1; i >= 0; i--) {
+                    if (candidates[i] !== canonical && incidentCandidates.has(candidates[i]))
+                        candidates.splice(i, 1);
+                }
+            }
+        }
+        else if (candidates.length === 0) {
+            add(seam.state);
+        }
+    }
+    // Only the hull exterior proves a range error; an interior gap can be numerical.
+    if (candidates.length === 0 && finiteEnvelope &&
+        Number.isFinite(propertyMin) && Number.isFinite(propertyMax) &&
+        (target < propertyMin - rootTolerance || target > propertyMax + rootTolerance)) {
+        throw new OutOfRangeError(`${property === 'enthalpy' ? 'Enthalpy' : 'Entropy'} at T=${T} K`, target, propertyMin, propertyMax);
+    }
+    const validate = (state) => validateBackwardState(state, constraints, {
+        solverName,
+        expectedRegion: state.region,
+        ...(seam !== null && state === seam.state ? { seam } : {}),
+    });
+    if (candidates.length > 1) {
+        const validated = candidates.map(validate);
+        validated.sort((first, second) => first.pressure - second.pressure);
+        throw new AmbiguousStateError(T, target, property, validated);
+    }
+    return candidates.length === 0 ? null : validate(candidates[0]);
+}