rafatahmed · Oct 19, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,13 @@
 ## Unreleased
 
 - Add experimental irrigation EC25 from speciation (McCleskey 2012 Eq. 8) with explicit partial results, envelope checks and provenance; no accuracy claim.
+- Add the material traceability API (`docs/materials.md`): shipped identity records (`load_identities`, `identity_for_product`), user grades and lots (`make_grade`, `make_lot`), `resolve_material` (per-nutrient basis, band ends, flags, provenance) and `nutrient_band`; `catalogue_dose_totals` and `calculate_irrigation_ec` take `materials=`, undisclosed blends raise or report `composition_undisclosed` in chemistry, and EC and equilibrium-delivery audits carry material provenance.
+- Link every catalogue product in `library.json` to its chemical identity (`identityId`) and record its `analysisBasis` (`declared_catalogue`, `identity_theoretical` or `grade_typical`) and `source` document reference. Product `id` and `name` values are unchanged.
+- Correct Mg Nitrate to Mg(NO3)2·6H2O theory (owner decision D1): formula `Mg(NO3)2` → `Mg(NO3)2.6H2O`; N_NO3 11 → 10.92564 %, Mg 9.65 → 9.47931 %; basis `identity_theoretical`. Its declared-form charge residual at 1 g/kg water goes from +0.5532 % to ~0 %, so it no longer trips the EC O5 gate on its own.
+- Correct Phosphoric Acid (75%) to the 75 % w/w solution: P 31.61 → 23.706035 % (0.75 × 31.608046, product-mass dosing); PO4 delivered per gram falls to 0.74995 × the old value. Its stored assay is now reported as drifting from the H3PO4 formula, as intended for a solution.
+- Calcium Nitrate (ag grade) keeps N_NO3 14.4 / N_NH4 1.1 / Ca 19 % and now cites the Haifa Cal NG technical data sheet (October 2018) with basis `grade_typical`. Metadata: Urea formula `Urea` → `CO(NH2)2` (the formula check now reads urea's amide N as N_UREA, so Urea stays eligible); display names "Iron(II) Sulfate (Heptahydrate)" and "Potassium Citrate (anhydrous)".
+- Recommended doses (g/L, `recommend` with all eligible products and the formula's water) change for 20 of the 26 shipped formulas: Chilli, DEFAULT, Generic Bloom, Generic Dry Season, Generic Grow, Generic Wet Season, Generic for Berries, Hoagland, Lettuce 2, Lettuce General, Melons, Pepper (Howard Resh), Rice, Strawberry Drip Irrigation, Strawberry Fruiting, Tomato (Howard Resh), Tomatoes Fourth/Third Cluster and to termination, Tropical Lettuce. Pepper regression recipe (Test01, Ca 20 ppm water): Mg Nitrate 0.414486 → 0.421953, Phosphoric Acid (75%) 0.117392 → 0.151738; pepper water workflow: Mg Nitrate 0.414483 → 0.421949, Phosphoric Acid (75%) 0.098687 → 0.126809, incidental N_NH4 4.845114 → 4.845193 ppm.
+- Chelates now carry their sodium counterions in chemistry totals (D2); recipes with chelates show incidental Na in equilibrium and EC results. Per formula unit: Fe-EDTA 1, Mn/Zn/Cu-EDTA 2, Fe-DTPA 2, Fe-o,o-EDDHA 1 Na, also added to CH - micro's borax and molybdate sodium; product `elements` are unchanged, so formulation is unaffected. Na+ at 1 g/kg water: Iron EDTA 0 → 53.52 mg, Zn EDTA 0 → 98.46 mg, Mn EDTA 0 → 108.80 mg, Copper EDTA 0 → 101.30 mg, Iron DTPA 0 → 90.57 mg, Iron EDDHA 0 → 24.70 mg, CH - micro 14.06 → 63.23 mg. Declared-form charge residuals fall to ~0 % (Iron EDTA −14.29 %, Zn/Mn/Cu EDTA −33.33 %, Iron DTPA −25.00 %, Iron EDDHA −14.29 %, CH - micro −12.76 %), so chelate recipes no longer trip the EC O5 gate. Borax declares its ion forms (`Na+`, `B(OH)4-`, `B(OH)3`; −0.5 charge per B in the residual): residual +100 % → +0.006 %; its equilibrium totals are unchanged (boron stays the H3BO3 basis).
 
 ## 0.4.0 — 2026-10-17
 

diff --git a/docs/audit/2026-10-17-flahax-vs-horticalc/review.md b/docs/audit/2026-10-17-flahax-vs-horticalc/review.md
@@ -70,6 +70,24 @@ with the report:
    (`plan_ec_delivery`, see [EC planning](../../conductivity.md)). "No
    ion-based model" is correct; "brochure anchors only" is not.
 
+## Product library: what "253 vs 28" measures
+
+The report lists "253 real commercial fertilizers vs 28 generic salts" as a
+Horticalc win. Catalogue size does not measure chemical coverage or model
+accuracy. FlahaX's chemistry uses explicit chemical identities and
+composition assumptions. Its catalogue should keep chemical identity
+separate from supplier grade and batch assay, with traceable specifications
+and impurity information. Several commercial products can share one
+chemical source.
+
+A factory blend has a declared nutrient analysis, but its exact
+ingredients, proportions, counterions or additives may be incomplete or
+undisclosed. Some manufacturers do disclose ingredients, so this varies by
+product. A declared analysis is enough for a mass balance, which is what
+Horticalc computes. Speciation, precipitatio
10BC8
n and pH need the composition.
+The [materials identity audit](../2026-10-18-materials-identity/review.md)
+traces FlahaX's own 28 products to that standard.
+
 ## Consequences for FlahaX
 
 - The anchor tests in `tests/test_site_planning.py` and the 1.15 mS/cm smoke

diff --git a/docs/audit/2026-10-18-materials-identity/data/materials-audit.csv b/docs/audit/2026-10-18-materials-identity/data/materials-audit.csv
diff --git a/docs/audit/2026-10-18-materials-identity/review.md b/docs/audit/2026-10-18-materials-identity/review.md
@@ -0,0 +1,100 @@
+# Materials identity audit, 2026-10-18: maintainer review
+
+The audit itself is [data/materials-audit.csv](data/materials-audit.csv), kept
+as received. It compares each of the 28 catalogue products with a named
+reference material: identity, formula, molecular weight, CAS number,
+hydration, assay basis and impurity limits. It also recomputes the
+theoretical nutrient analysis from the catalogue formula. Reference
+products (Sigma-Aldrich, Merck, Haifa, Yara, Nouryon, Thermo) are
+**comparators for chemical identity**, not the materials FlahaX users buy.
+
+## Position
+
+Catalogue size does not measure chemical coverage or model accuracy.
+FlahaX's chemistry approach uses explicit chemical identities and
+composition assumptions. Its raw-material catalogue should distinguish
+chemical identity from supplier grade and batch assay, with traceable
+specifications and impurity information. Multiple commercial products may
+represent the same underlying chemical source.
+
+A factory blend has a declared nutrient analysis, but its exact
+ingredients, proportions, counterions or additives may be incomplete or
+undisclosed. Some manufacturers do disclose ingredients, so this varies by
+product. Equilibrium chemistry needs that composition. A declared analysis
+alone supports a mass balance, but not speciation, precipitation or pH.
+
+## Results
+
+| Status | Products |
+|---|---|
+| Identity consistent | 15 |
+| Chelate identity incomplete | 6: Copper EDTA, Iron DTPA, Iron EDDHA, Iron EDTA, Mn EDTA, Zn EDTA |
+| Metadata correction | 2: Iron II Sulfate ("Hepahydrate" → heptahydrate), Urea (formula text) |
+| Unresolved blend | 1: CH - micro |
+| Commercial profile needs provenance | 1: Calcium Nitrate (ag grade) |
+| Formula/assay conflict | 1: Mg Nitrate |
+| Concentration/assay conflict | 1: Phosphoric Acid (75%) |
+| Hydration must be explicit | 1: Potassium Citrate |
+
+**No product has a supplier grade or batch assay** (`actual_FlahaX_supplier_grade_lot`
+is "not specified" for all 28). Every catalogue analysis is a declared or
+theoretical figure, not a purchased-material certificate.
+
+## Independent confirmation from the irrigation EC work
+
+The irrigation EC module (M1, 2026-10-18) computes each product's assay
+charge residual from its declared ion forms. It was written without
+reference to this audit. Run on 1 g/kgw of each product:
+
+| Audit status | Charge residual |
+|---|---|
+| Identity consistent (15) | all within ±0.025 % |
+| Mg Nitrate, formula/assay conflict | +0.553 %: the N:Mg ratio is not that of Mg(NO₃)₂ |
+| Calcium Nitrate, commercial profile | −0.068 %: a consistent commercial analysis, not the ideal double salt |
+| Chelates (6), identity incomplete | −14 % to −33 %: no sodium or other counterion is declared, so each chelate carries net negative charge |
+| CH - micro, unresolved blend | −12.8 % |
+| Borax | +100 % (see below) |
+
+The two methods agree. Every product the audit marks consistent passes the
+0.1 % charge rule; every identity problem the audit names shows up as a
+charge residual. This is why calculated-mode EC rejects recipes that
+contain chelates or Mg Nitrate.
+
+## Findings the audit adds or sharpens
+
 1. **Phosphoric Acid (75%) overstates P by about 33 %.** The catalogue
+   lists 31.61 % P, the pure-acid value. A 75 % w/w solution is about
+   23.71 % P. This was already noted in
+   [water-to-delivery.md](../../water-to-delivery.md) but remains in the
+   data. It changes recipe doses, not only labels.
+2. **Chelates lack counterions and grade definitions.** Catalogue metal
+   percentages are grade assays, not identities. For example, dry NaFeEDTA
+   is about 15.2 % Fe, so 13 % Fe needs a declared hydration and sodium
+   content. Fe-EDDHA total Fe and o,o-bound Fe differ (Rexolin Q48: 6 %
+   versus 4.8 %).
+3. **Mg Nitrate's formula and analysis disagree.** The formula is anhydrous
+   but the analysis looks hydrated, and the N:Mg ratio fits neither exactly.
+4. **Borax's declared chemistry is incomplete (found here, not in the
+   CSV).** The audit rates borax "identity consistent" on mass. FlahaX
+   declares it as Na⁺ plus B(OH)₃, which leaves the sodium with no anion.
+   In water, borax gives 2 Na⁺ + 2 B(OH)₄⁻ + 2 B(OH)₃. The ion forms
+   need correcting.
+5. **CH - micro is a project assumption**, not an identified product. It
+   should not be presented as a raw material.
+
+## Consequences
+
+- Supplier grade and batch assay become explicit, separate inputs. The
+  catalogue entry keeps chemical identity; a grade or lot record carries
+  the measured or certified assay, hydration, counterions and impurity
+  limits, with its source document.
+- Material-level corrections (findings 1–4) change numbers and need their
+  own reviewed change with regression evidence. None is made by this review.
+- Resolved by the traceable-catalogue change (branch `feat/traceable-catalogue`): identity,
+  grade and lot layers ([materials](../../materials.md)); Mg Nitrate D1, phosphoric acid 75 %,
+  chelate sodium D2 and the borax declared form.
+
+## Source
+
+Audit file received 2026-10-18, accessed dates per row. Reference URLs are
+in the CSV; manufacturer documents are not stored in the repository.
diff --git a/docs/audit/README.md b/docs/audit/README.md
@@ -7,4 +7,5 @@ claims; the review page takes precedence over the report where they differ.
 
 | Date | Audit | Scope | Review |
 |---|---|---|---|
+| 2026-10-18 | [Materials identity audit](2026-10-18-materials-identity/data/materials-audit.csv) | Chemical identity, hydration, assay basis and impurity limits of all 28 catalogue products against reference materials | [Maintainer review, 2026-10-18](2026-10-18-materials-identity/review.md) |
 | 2026-10-17 | [FlahaX vs Horticalc benchmark](2026-10-17-flahax-vs-horticalc/report.md) | Formulation accuracy, equilibrium chemistry against PHREEQC 3.8.6, electrical conductivity, scope | [Maintainer review, 2026-10-18](2026-10-17-flahax-vs-horticalc/review.md) |
diff --git a/docs/development-status.md b/docs/development-status.md
@@ -20,6 +20,7 @@ The matrix below describes the 0.3.1 capabilities and their boundaries.
 | Stock planning API | Existing sourced compatibility/solubility/capacity checks | Caller must supply complete applicable records; absence from a pairwise table is not evidence of compatibility |
 | Injector design flow and inventory | `injector_sizing.py`, batch/area arithmetic and tests | Pump/venturi/Dosatron operating-point data still needed for a specific model |
 | Offline graphical capability report | `examples/run_all.py`, `visual_report.py`, `test_examples.py` | Separate pepper, manufacturer-screening and synthetic demonstrations; no cross-scenario dosing inference |
+| Traceable materials (identity, grade, lot, nutrient band) | `materials.py`, `material_identities.json`, material tests; [materials](materials.md) | Grades and lots are user supplied; band covers nutrient amounts only; undisclosed blends refused for chemistry |
 
 Paths in this matrix refer to `src/flahax/`, `tests/` or `examples/` as named.
 See [site planning](site-planning.md), [water-to-delivery](water-to-delivery.md),

diff --git a/docs/index.md b/docs/index.md
@@ -23,6 +23,7 @@
 
 - [Quantities and batch recipes](delivery-quantities.md)
 - [Input contracts and audit records](delivery-contracts.md)
+- [Traceable materials: identity, grade, lot and nutrient band](materials.md)
 - [Stock assignment](stock-planning.md)
 - [Measured-curve pH planning](ph-planning.md)
 - [Equilibrium-to-delivery API and runnable example](package-verification.md)