iapws-if97 2.2.0 → 2.8.0

package/CHANGELOG.md

@@ -1,12 +1,35 @@
 # 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, robustness, and performance.
+- Improved backward-solver accuracy and performance.
 - Fixed saturation-region detection and package validation.
 - Requires Node.js `>=20.19.0`.
 

package/README.md

@@ -1,295 +1,122 @@
-# `iapws-if97`
+# iapws-if97
 
-[![CI](https://github.com/jltonghui/iapws-if97/actions/workflows/ci.yml/badge.svg)](https://github.com/jltonghui/iapws-if97/actions/workflows/ci.yml)
+**Industrial water and steam properties for Node.js and TypeScript.**
+
+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.
 
-`iapws-if97` calculates industrial water and steam properties in Node.js and TypeScript using the [IAPWS-IF97](https://www.iapws.org/) standard published by the International Association for the Properties of Water and Steam.
+[![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)
 
-It includes forward and backward state solvers, saturation solvers, and transport-property helpers.
+[API reference](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md) · [References](#references) · [Changelog](CHANGELOG.md)
 
-## Features
+![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)
 
-- 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
+- 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.
 
-## Installation
+## Start calculating
 
-Requires Node.js `>=20.19.0`. The package publishes ESM, and all documented examples use `import`. CommonJS is not part of the tested API.
+Requires Node.js ≥20.19.0. Use ESM imports.
 
 ```bash
 npm install iapws-if97
 ```
 
-## Quick start
-
-Save the following as `example.mjs` and run it with `node example.mjs`:
+Save as `example.mjs` and run `node example.mjs`:
 
 ```js
-import { solve, solvePT, solvePx } from 'iapws-if97';
+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)
 
-| Function | Input pair | Units |
-| --- | --- | --- |
-| `solvePT(p, T)` | pressure, temperature | `MPa`, `K` |
-| `solvePH(p, h)` | pressure, enthalpy | `MPa`, `kJ/kg` |
-| `solvePS(p, s)` | pressure, entropy | `MPa`, `kJ/(kg·K)` |
-| `solveHS(h, s)` | enthalpy, entropy | `kJ/kg`, `kJ/(kg·K)` |
-| `solveTH(T, h)` | temperature, enthalpy | `K`, `kJ/kg` |
-| `solveTS(T, s)` | temperature, entropy | `K`, `kJ/(kg·K)` |
-| `solvePx(p, x)` | pressure, vapor quality | `MPa`, dimensionless `[0, 1]` |
-| `solveTx(T, x)` | temperature, vapor quality | `K`, dimensionless `[0, 1]` |
+## Use the properties you have
 
-All numeric inputs must be finite numbers.
-
-### Unified `solve()`
-
-Use `solve({ mode, ... })` when the input pair is determined at runtime:
+| 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)` |
 
-```ts
-import { solve } from 'iapws-if97';
+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).
 
-const state = solve({ mode: 'PT', p: 16, T: 823.15 });
-```
+Use `solve()` when the input pair is chosen at runtime:
 
-Each mode accepts canonical short fields or their long aliases:
-
-| Mode | Short fields | Long aliases |
-| --- | --- | --- |
-| `PT` | `p`, `T` | `pressure`, `temperature` |
-| `PH` | `p`, `h` | `pressure`, `enthalpy` |
-| `PS` | `p`, `s` | `pressure`, `entropy` |
-| `HS` | `h`, `s` | `enthalpy`, `entropy` |
-| `Px` | `p`, `x` | `pressure`, `quality` |
-| `Tx` | `T`, `x` | `temperature`, `quality` |
-| `TH` | `T`, `h` | `temperature`, `enthalpy` |
-| `TS` | `T`, `s` | `temperature`, `entropy` |
-
-```ts
-import type { SolveInput } from 'iapws-if97';
+```js
 import { solve } from 'iapws-if97';
 
-const shortForm: SolveInput = { mode: 'PT', p: 16, T: 823.15 };
-const longForm: SolveInput = { mode: 'PT', pressure: 16, temperature: 823.15 };
-
-const a = solve(shortForm);
-const b = solve(longForm);
+const state = solve({ mode: 'PH', p: 3, h: 3000 });
 ```
 
-You can mix short and long names within one input. If both aliases for the same property are present, their values must match exactly. The exported `SolveInput` type is the source of truth for accepted combinations.
-
-## 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;
-};
-```
-
-`SteamState` always uses canonical property names.
-
-**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`.
 
-- `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, so there is no need to invert `specificVolume`.
-- `ionizationConstant` is `null` outside the IAPWS validity range for that correlation.
+## Work with saturation
 
-## Units
+Specify quality to calculate saturated liquid, saturated vapor, or wet steam:
 
-- 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.
+```js
+import { solvePx } from 'iapws-if97';
 
-## Advanced imports
+const wet = solvePx(1, 0.9); // 1 MPa, 90% vapor by mass
 
-The package root is limited to the main solvers, `SteamState`, `SolveInput`, `Region`, and the public error classes. Lower-level helpers are available from explicit subpaths:
+console.log(wet.temperature.toFixed(2)); // 453.04 K
 
-| Subpath | Exports |
-| --- | --- |
-| `iapws-if97/transport` | `viscosity`, `thermalConductivity`, `surfaceTension`, `dielectricConstant`, `ionizationConstant` |
-| `iapws-if97/regions` | `region1`, `region2`, `region3ByRhoT`, `region5` |
-| `iapws-if97/saturation` | `saturationPressure`, `saturationTemperature` |
-| `iapws-if97/boundaries` | `boundary23_T_to_P`, `boundary23_P_to_T`, `region3Volume`, `region3SatVolume` |
-| `iapws-if97/detect` | `detectRegionPT`, `detectRegionPH`, `detectRegionPS`, `detectRegionHS`, `detectRegionTH`, `detectRegionTS` |
-
-```ts
-import { viscosity } from 'iapws-if97/transport';
-import { region1 } from 'iapws-if97/regions';
-import { saturationTemperature } from 'iapws-if97/saturation';
-import { detectRegionPT } from 'iapws-if97/detect';
+if (wet.saturation) {
+  const { liquid, vapor } = wet.saturation;
+  const latentHeat = vapor.enthalpy - liquid.enthalpy;
+  console.log(latentHeat.toFixed(2)); // 2014.44 kJ/kg
+}
 ```
 
-These are low-level mathematical interfaces:
+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.
 
-- Region functions return core thermodynamic properties without `density` or transport-property enrichment.
-- Region, boundary, and detection helpers expect callers to respect the corresponding equation domains. Detection helpers return a `Region` value or `-1` when no valid region is found.
-- `thermalConductivity(T, rho)` calculates the base contribution. Pass `cp`, `cv`, `drhodP_T`, and `mu` to include the IAPWS 2011 critical-enhancement term.
-- `surfaceTension(T)` is a saturation-line property. `saturationPressure(T)` and `saturationTemperature(p)` expose the mathematical Region 4 boundary and are more permissive at endpoints than `solveTx` and `solvePx`.
+## Before integrating
 
-## Transport correlation limits
+- 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)
 
-Transport correlations have validity ranges independent of the IF97 thermodynamic envelope. The library may return extrapolated values where noted:
-
-| Property | Implemented behavior |
+| Thermodynamic temperature range | Maximum pressure |
 | --- | --- |
-| Viscosity | Uses the IAPWS 2008 dilute-gas and finite-density terms. The near-critical enhancement is omitted, as permitted for industrial use by the release. |
-| Thermal conductivity | Full `SteamState` calculations include the IAPWS 2011 critical enhancement. The two-argument low-level call does not. Values above the release's temperature range are extrapolations. |
-| Surface tension | Defined for saturation states below the critical point. The low-level helper permits `273.15 K ≤ T ≤ Tc`; values below the triple point `Tt = 273.16 K` are extrapolations. |
-| Dielectric constant | The IAPWS 1997 release is valid through `873 K`. The low-level helper does not enforce that upper bound, so higher-temperature results are extrapolations. |
-| Ionization constant (`pKw`) | Returns `null` outside `273.15 K ≤ T ≤ 1273.15 K`. The release's `1000 MPa` pressure limit describes the correlation, not the state-solver pressure range. |
-
-## Saturation endpoints
-
-The triple and critical points are `Pt = 0.000611657 MPa`, `Tt = 273.16 K`, `Pc = 22.064 MPa`, and `Tc = 647.096 K`.
-
-- Low-level Region 4 helpers accept a wider endpoint range. The saturation state solvers use these stricter bounds:
-  - `solvePx(p, x)` accepts `Pt ≤ p < Pc`
-  - `solveTx(T, x)` accepts `Tt = 273.16 K ≤ T < Tc`
-- The 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 solvers do not return the exact critical point as a Region 4 state.
-- `solveTH(T, h)` and `solveTS(T, s)` 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; root solvers also use it directly for non-numeric or non-finite inputs, conflicting aliases, unsupported modes, and unsupported critical-point states |
-
-Numeric inputs to root solvers and transport helpers must be finite. Low-level region, boundary, and detection helpers rely on callers to respect their equation domains. `solvePT(Pc, Tc)`, exact critical Region 4 states, and `solveTH`/`solveTS` inputs within `0.001 K` of `Tc` are rejected because the required derivative properties or inverse solution are singular or ill-conditioned.
+| 273.15–1073.15 K | 100 MPa |
+| Above 1073.15 K, up to 2273.15 K | 50 MPa |
 
-## Thermodynamic validity
+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).
 
-The thermodynamic solvers follow the piecewise IF97 industrial range:
+## Verification and development
 
-- `273.15 K ≤ T ≤ 1073.15 K`: pressure up to `100 MPa`.
-- `1073.15 K < T ≤ 2273.15 K` (Region 5): pressure up to `50 MPa`.
-
-Transport-property limits are separate; see [Transport correlation limits](#transport-correlation-limits).
-
-## Verification
-
-The test suite covers:
-
-- 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
-
-For a clean local verification run:
+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)
 
 ```bash
 npm ci
-npm run test:package
+npm run typecheck
 npm test
+npm run test:package
 ```
 
-`test:package` performs a clean build and checks that the dry-run npm tarball has no dangling source-map references. Coverage and published-table comparisons are available separately:
-
-```bash
-npm run test:coverage
-npm run test:standards
-```
-
-## Integration validation
-
-![Mollier h-s diagram generated with iapws-if97](https://raw.githubusercontent.com/jltonghui/iapws-if97/main/assets/pics/mollier-hs-diagram.svg)
-
-This Mollier `h-s` diagram was generated with `iapws-if97` as an end-to-end check of the calculation pipeline.
-
-The standards tests check the published tables below. Both suites enforce `maxRelativeError < 5e-4` (less than `0.05%`).
-
-| Reference | Coverage | Points checked | Worst relative error |
-| --- | --- | ---: | ---: |
-| *ASME International Steam Tables for Industrial Use*, 3rd ed., Table S-2 | Saturation states at 6 pressures | 42 | `0.0315405%` |
-| *GB/T 34060-2017*, Table A.3(续), page 55 | Superheated steam at `10 MPa` and 6 temperatures | 24 | `0.0007020%` |
-
-See [`tests/standards-asme`](tests/standards-asme) and [`tests/standards-cn`](tests/standards-cn) for the source values and per-case comparisons.
-
-## TypeScript
-
-The package ships with generated TypeScript declarations for the root and every public subpath.
-
-```ts
-import type { SolveInput, SteamState } from 'iapws-if97';
-import { Region, solve } from 'iapws-if97';
-
-const input: SolveInput = { mode: 'PT', p: 3, T: 300 };
-const state: SteamState = solve(input);
-
-if (state.region === Region.Region1) {
-  console.log('compressed liquid');
-}
-```
+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).
 
 ## References
 
-- [IAPWS official website](https://www.iapws.org/)
-- [IAPWS R7-97(2012), Industrial Formulation 1997](https://www.iapws.org/relguide/IF97-Rev.html)
-- [IAPWS supplementary releases](https://www.iapws.org/release.html) for `T(p,h)`, `T(p,s)`, `p(h,s)`, Region 3 boundary equations, `Tsat(h,s)`, and `v(p,T)`
-- [IAPWS SR4-04(2014), Region 3 `p(h,s)` and Region 4 `Tsat(h,s)`](https://iapws.org/documents/release/Supp-phs3-2014)
-- [IAPWS R12-08, Viscosity of Ordinary Water Substance](https://www.iapws.org/relguide/viscosity.html)
-- [IAPWS R15-11, Thermal Conductivity of Ordinary Water Substance](https://www.iapws.org/relguide/ThCond.html)
-- [IAPWS R8-97, Static Dielectric Constant of Ordinary Water Substance](https://www.iapws.org/relguide/dielec.pdf)
-- [IAPWS R1-76(2014), Surface Tension of Ordinary Water Substance](https://www.iapws.org/relguide/Surf-H2O.html)
-- [IAPWS R11-24, Ionization Constant of H2O](https://www.iapws.org/relguide/Ionization.html)
+- [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).
+
+See the [full reference list](https://github.com/jltonghui/iapws-if97/blob/main/docs/reference.md#references) for release details.
 
 ## Project origin
 
@@ -299,8 +126,4 @@ if (state.region === Region.Region1) {
 
 ## 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;