rafatahmed · Oct 20, 2026 · Oct 20, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## 0.5.0 — Unreleased
 
 - Publish Benchmark v1 snapshot 2026-10-20-linux-df0d30b (hosted run 39515183621 on `main`, after #62, #65 and #69), the first with every correctness gate passing: 7/7 controlled NNLS cases, 21/21 stored chemistry comparisons, 17/17 timing workloads; complete recipes 34/52 (was 29/52). The results page no longer calls a fully passing scorecard 'not fully passing' (#66).
 - Fix `recommend()` slowness and start-dependent recipes under incidental-ion ceilings (#68). Two root causes, both measured against SciPy on every fit: the NNLS optimality test used one tolerance scaled by the whole matrix (max |A| times |b|), so a heavily weighted row hid real descent directions in the other columns and NNLS stopped early (doses off by up to 4.2e-3 g/L); it now bounds each column's dual weight by the rounding error of its own terms. And a binding ceiling was enforced by a 1024-weight penalty, which left the problem so flat in double precision that doses were fixed only to ~2e-3 g/L and depended on the solver's starting point. A binding ceiling is now a constraint: a weight-8 row whose aim is shifted by the Lagrange multiplier, found by a bracketed secant search, with one Gram cache per search. Every ceiling fit now matches SciPy to 1.4e-10 g/L, warm and cold starts agree to 7e-9 g/L, and binding ions land on their aim. Over the 52 benchmark recipes `recommend()` is 34% faster with the default ammonium limit (4.20 -> 2.78 s) and unchanged with a 3 mmol/L Cl ceiling (3.77 -> 3.87 s); the Benchmark v1 formulation workload falls from about 30 to 16 ms. Pass counts are unchanged by default (34/52 recipes, 571/636 targets) and rise with the Cl ceiling (41 -> 42 recipes, 598 -> 599 targets), with no limit violations; the 10 recipes that change have equal or better target fit.

diff --git a/CITATION.cff b/CITATION.cff
@@ -14,7 +14,7 @@ authors:
   - family-names: Al Khashan
     given-names: Rafat A.
     orcid: https://orcid.org/0009-0009-4692-4552
-version: 0.4.0
+version: 0.5.0
 url: https://pypi.org/project/flahax/
 repository-code: https://github.com/rafatahmed/Flahax
 license: Apache-2.0
@@ -35,6 +35,6 @@ preferred-citation:
       given-names: Rafat A.
       orcid: https://orcid.org/0009-0009-4692-4552
   year: 2026
-  version: 0.4.0
+  version: 0.5.0
   url: https://pypi.org/project/flahax/
   license: Apache-2.0
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ with its own releases.
 Python 3.11 or newer. There are no third-party runtime dependencies.
 
 ```bash
-python -m pip install flahax==0.4.0
+python -m pip install flahax==0.5.0
 ```
 
 Pin the version for reproducible work. `python -m pip install flahax`
@@ -160,15 +160,15 @@ and [CONTRIBUTING](https://github.com/rafatahmed/Flahax/blob/main/CONTRIBUTING.m
 
 ## Citation
 
-Al Khashan, R. A. (2026). *FlahaX* (Version 0.4.0) [Computer software].
+Al Khashan, R. A. (2026). *FlahaX* (Version 0.5.0) [Computer software].
 https://pypi.org/project/flahax/
 
 ```bibtex
 @software{alkhashan2026flahax,
   author  = {Al Khashan, Rafat A.},
   title   = {FlahaX: plant-nutrient chemistry engine for fertilizer formulation and delivery planning},
   year    = {2026},
-  version = {0.4.0},
+  version = {0.5.0},
   url     = {https://pypi.org/project/flahax/},
   license = {Apache-2.0}
 }

diff --git a/docs/development-status.md b/docs/development-status.md
@@ -1,6 +1,6 @@
 # Water-to-delivery development status
 
-Updated 2026-10-17. **0.4.0 is published on PyPI** (tag `v0.4.0`; Apache-2.0, measured-pH water balancing) through the [hardened release workflow](publishing.md); see the [0.4.0 publication evidence](site/evidence/release-evidence.md#040-publication---2026-10-17). Before it, **0.3.1** was published (tag `v0.3.1`); see the
+Updated 2026-10-21. **0.5.0 is prepared, not published** (see the [0.5.0 preparation record](site/evidence/release-evidence.md#050-preparation---2026-10-21)). **0.4.0 is published on PyPI** (tag `v0.4.0`; Apache-2.0, measured-pH water balancing) through the [hardened release workflow](publishing.md); see the [0.4.0 publication evidence](site/evidence/release-evidence.md#040-publication---2026-10-17). Before it, **0.3.1** was published (tag `v0.3.1`); see the
 [publication evidence](site/evidence/release-evidence.md#031-publication---2026-10-17).
 The matrix below describes the 0.3.1 capabilities and their boundaries.
 

diff --git a/docs/index.md b/docs/index.md
@@ -4,7 +4,7 @@ Readers: the documentation is at <https://flahax.readthedocs.io/>. This index is
 
 ## Start here
 
-- [User manual](../src/flahax/data/USER_GUIDE.md) (version 0.4.0): the canonical, self-contained guide shipped inside the package.
+- [User manual](../src/flahax/data/USER_GUIDE.md) (version 0.5.0): the canonical, self-contained guide shipped inside the package.
 - [Changelog](../CHANGELOG.md): new capabilities, compatibility notes and release status.
 - [Core API and CLI](site/guide/usage.md): formulation inputs and output fields.
 - [Complete public API reference](../src/flahax/data/API_REFERENCE.md): generated signatures, source docstrings and result-record fields for every top-level export; shipped offline.

diff --git a/docs/publishing.md b/docs/publishing.md
@@ -76,6 +76,17 @@ Dashboard settings, recorded here because they live outside the repository:
 - The default version is `latest` until that release, then `stable`.
 - Never put a Read the Docs token in the repository.
 
+## Checklist (in progress: 0.5.0)
+
+- [x] Choose the version and align metadata, runtime version, citation, manual and changelog.
+- [x] Review compatibility, scientific provenance and distribution contents.
+- [x] Pass local tests with live PHREEQC and isolated wheel/sdist verification.
+- [ ] Observe successful hosted Python 3.11–3.13 checks on the merged revision.
+- [ ] Obtain explicit publication authorization.
+- [ ] Publish the `v0.5.0` GitHub Release; review the run; approve the deployment.
+- [ ] Verify PyPI metadata and a fresh installed-package check; record the date, run and hashes.
+- [ ] Confirm the Read the Docs `stable` version builds `v0.5.0` and serves the benchmark pages (#48).
+
 ## Checklist (last run: 0.4.0)
 
 - [x] Choose the version and align metadata, runtime version, citation, manual and changelog.

diff --git a/docs/release-readiness.md b/docs/release-readiness.md
@@ -2,6 +2,22 @@
 
 The current preparation comes first; dated audits below it are history.
 
+## 0.5.0 - preparation 2026-10-21
+
+Prepared on `release/0.5.0` from `main` at `9bea54a`. The evidence is the
+[0.5.0 preparation record](site/evidence/release-evidence.md#050-preparation---2026-10-21).
+
+0.5.0 changes:
+- recipe selection: the ammonium limit, ceilings as constraints and miss diagnosis;
+- catalogue identities and provenance;
+- experimental irrigation EC;
+- solver speed and accuracy.
+
+It keeps every 0.4.0 export. Remaining gates:
+- hosted checks on the release revision;
+- review and explicit owner publication authorization;
+- the workflow build, with recorded hashes and a fresh-install check.
+
 ## 0.4.0 - published 2026-10-17
 
 Prepared on `release/0.4.0` from `main` at `00d855a`, finalized in PR #18 and

diff --git a/docs/site/api/package-verification.md b/docs/site/api/package-verification.md
@@ -2,7 +2,7 @@
 
 ## User manual and retained release artifacts
 
-The canonical manual is `src/flahax/data/USER_GUIDE.md`. It is bundled as a package resource in both distributions; all eight Python examples are executed during source regression and isolated wheel/sdist verification. The verification report records the exact manual hash and example count. The bundled `API_REFERENCE.md` covers every top-level public export; source tests reject signature drift and clean installs check export coverage and record its hash. `docs/index.md` is the documentation navigation page; historical material is separate.
+The canonical manual is `src/flahax/data/USER_GUIDE.md`. It is bundled as a package resource in both distributions; all nine Python examples are executed during source regression and isolated wheel/sdist verification. The verification report records the exact manual hash and example count. The bundled `API_REFERENCE.md` covers every top-level public export; source tests reject signature drift and clean installs check export coverage and record its hash. `docs/index.md` is the documentation navigation page; historical material is separate.
 
 To retain only artifacts that passed clean-install checks, use `python tools/verify_distribution.py --artifacts-dir dist/<version>`. The destination must be new or empty; existing release files are never overwritten. This command builds and tests locally; it does not tag, upload or publish. Afterward, run `python -m twine check --strict dist/<version>/*` in a development environment with `twine` installed. The build and metadata tools are not runtime dependencies. Releases themselves are built and uploaded by the [hardened release workflow](https://github.com/rafatahmed/Flahax/blob/main/docs/publishing.md).
 

diff --git a/docs/site/evidence/release-evidence.md b/docs/site/evidence/release-evidence.md
@@ -26,6 +26,59 @@ They are kept here because the records cite them.
 | 0.3.1 | 2026-10-17 | Published | [Publication](#031-publication-2026-10-17), [release audit](#031-release-audit-2026-10-17), [documentation audit](#031-documentation-audit-2026-10-02), [preparation](#031-preparation-2026-10-01) |
 | 0.3.0 | 2026-09-27 | Yanked 2026-10-17 | [Publication exception](#030-authorized-publication-exception-2026-09-27), [automated evidence](#030-automated-evidence), [P2/P3 acceptance](#p2p3-end-to-end-numerical-acceptance), [continuation](#package-and-delivery-continuation-2026-09-27), [cleanup](#030-release-readiness-cleanup), [preparation](#030-preparation) |
 
+## 0.5.0 preparation (2026-10-21)
+
+Prepared revision: `release/0.5.0`, cut from `main` at `9bea54a` (merge of
+[PR #67](https://github.com/rafatahmed/Flahax/pull/67)). Hosted CI passed on `9bea54a`
+([run 39515601654](https://github.com/rafatahmed/Flahax/actions/runs/39515601654):
+Python 3.11, 3.12 and 3.13, live PHREEQC replay, docs). Assessor: Rafat Al Khashan
+with Claude Code assistance. This is release-readiness evidence, not publication
+authorization. Version 0.5.0 is unpublished; PyPI's latest release is 0.4.0.
+
+| Check | Result |
+|---|---|
+| Version alignment | `0.5.0` in `pyproject.toml`, `flahax.__version__`, `CITATION.cff`, README, user manual and API reference; changelog section `0.5.0 — Unreleased`; tag `v0.5.0` not yet created |
+| Licence | Unchanged: Apache-2.0. Wheel metadata `License-Expression: Apache-2.0`, with `LICENSE` and `NOTICE` as licence files |
+| Local regression | 373 tests passed with zero skips and `FLAHAX_REQUIRE_PHREEQC=1` (pinned PHREEQC 3.8.6) on Python 3.13.15 (33.4 s) and 3.14.0 (28.2 s), with the documentation site built so its checks run. `compileall` and `git diff --check` passed |
+| Public API compatibility against `v0.4.0` | 103 exports retained, none removed; 18 added (121 total): the material traceability API (`DocumentReference`, `Grade`, `Lot`, `ResolvedMaterial`, `load_identities`, `identity_for_product`, `make_grade`, `make_lot`, `resolve_material`, `nutrient_band`) and experimental irrigation EC (`DeclaredPureWater`, `IrrigationECResult`, `assay_charge_residual`, `calculate_ec_from_totals`, `calculate_irrigation_ec`, `calculate_irrigation_ec_band`, `calculate_irrigation_ec_from_plan`, `compare_measured_ec`). Two signatures gain keyword-only parameters with defaults: `recommend` (`maximum_concentrations`, `max_ammonium_fraction`) and `catalogue_dose_totals` (`materials`) |
+| Isolated distribution check | `tools/verify_distribution.py` passed: clean wheel and sdist installs on Python 3.13.15 (builder 3.14.0, `build` 1.6.1), nine manual examples, 30 catalogue products, all public exports, both CLI entry points, planning EC 1.15 mS/cm. Sdist 468 files, 5,086,439 bytes; no PDF; `docs/publication/` excluded |
+| Metadata | `twine check --strict` (Twine 7.0.0) passed for both artifacts |
+| Packaged resources | `USER_GUIDE.md` `92f5d5806b1f0931df05fe490b738b8b277486d70a21d6ea53e2839f36c5ffb9`; `API_REFERENCE.md` `db350573e41e407468d0ddb7bd7b86304c80562baf8d6b77d146d4f8df1ab9c8`; `chemistry_25c.json` `ad87363818ccc2471c1343a0791f9ae63798bc0b3530b5b710344aff3077188f`; `library.json` `dfc65ac7fc0060ebe760870b832e6c2c4febce2babf8cfa9defa6a858e28a05a` |
+| Thermodynamic data | Unchanged since 0.3.1: `chemistry_25c.json` has the same LF hash as the published 0.4.0 wheel |
+| Benchmark and comparison evidence | [Benchmark v1 snapshot 2026-10-20-linux-df0d30b](benchmark-results.md): every correctness gate passes (NNLS 7/7, stored chemistry 21/21, timing 17/17; complete recipes 34/52). [Competitor comparison](competitor-comparison.md) at `ed568c5` |
+
+Candidate hashes, built on Windows from the LF working tree before the final
+form of this record (the record changes the sdist, so the publication artifacts
+must be rebuilt from the final reviewed revision and hashed again):
+
+| Artifact | SHA-256 |
+|---|---|
+| `flahax-0.5.0-py3-none-any.whl` | `1c6d76bdf04cb21860b153fae8ccd294af7a3142d503173a09158bf0baadb96e` |
+| `flahax-0.5.0.tar.gz` | `52122a12d154753b8726ba6649a954c78325314378ea6ac9c8995c7c421ae987` |
+
+What 0.5.0 changes scientifically:
+    - **Recipes.** `recommend` allows incidental NH4-N up to the smaller of 10% of
+  the target N and 1.5 mmol/L when the formula omits NH4 (#54). It treats a
+  binding incidental-ion ceiling as a constraint (#68), and it explains every
+  missed target and the formula's own ion balance (#39).
+- **Catalogue.** Mg nitrate is corrected to the hexahydrate and phosphoric acid
+  to a 75% solution. Potassium chloride and calcium chloride dihydrate are
+  added, and are used only with chloride consent. Every product is linked to a
+  chemical identity and source document.
+- **Shipped recipes change.** Most shipped formulas get different doses, and
+  chelate sodium appears in chemistry and EC.
+- **Solvers.** The equilibrium and NNLS solvers are faster, with numerically
+  equivalent or more accurate results (#59, #61, #68).
+- **Unchanged.** No reaction constant or phase changed.
+
+Remaining before publication, per the [publishing checklist](https://github.com/rafatahmed/Flahax/blob/main/docs/publishing.md):
+- hosted CI on the release revision;
+- explicit owner authorization;
+- the `v0.5.0` GitHub Release, the workflow's own build and gates, and approval of the `pypi` deployment;
+- PyPI metadata, hash identity and fresh-install verification;
+- the publication date in the changelog and the manual;
+- confirming that the Read the Docs `stable` version serves the benchmark pages (#48).
+
 ## 0.4.0 publication (2026-10-17)
 
 0.4.0 was published to PyPI on **2026-10-17** by the hardened release workflow

diff --git a/docs/site/guide/usage.md b/docs/site/guide/usage.md
@@ -12,7 +12,7 @@ From PyPI, inside a virtual environment (pin the version for reproducible
 work):
 
 ```powershell
-python -m pip install flahax==0.4.0
+python -m pip install flahax==0.5.0
 ```
 
 From a checkout of this repository:

diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flahax"
-version = "0.4.0"
+version = "0.5.0"
 description = "Plant-nutrient chemistry engine: fertilizer formulation, aqueous equilibrium chemistry and auditable delivery planning."
 readme = "README.md"
 requires-python = ">=3.11"

diff --git a/src/flahax/__init__.py b/src/flahax/__init__.py
@@ -132,7 +132,7 @@
     "transition_plan",
     "validate_delivery_request",
 ]
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 from .equilibrium_delivery import EquilibriumPhPlan, plan_equilibrium_delivery
 __all__ += ["EquilibriumPhPlan", "plan_equilibrium_delivery"]
 __all__ += ["AqueousResult", "AcidResult", "catalogue_dose_totals", "plan_catalogue_nitric_target"]

diff --git a/src/flahax/data/API_REFERENCE.md b/src/flahax/data/API_REFERENCE.md