diff --git a/CONTRACT.md b/CONTRACT.md index 78624c5..986d4f0 100644 --- a/CONTRACT.md +++ b/CONTRACT.md @@ -3,6 +3,28 @@ Hand-maintained for Phase 6; the `## Inputs` table is generated from `src/commands/index.js` (see Phase 9 generator). Keep ≤ 80 lines. +## Unit convention — approved exception to the canonical-unit rule + +EVOLV's canonical units (`CLAUDE.md`, `generalFunctions/CONTRACT.md`) +are Pa / m³/s / W / K. **reactor diverges deliberately** — it follows +the ASM (Activated Sludge Model) kinetics literature convention: + +- Concentrations: `mg/L` (= g/m³), `mmol/L` for alkalinity. +- Flow internally: `m³/d` (engine integrator runs in days; see + `baseEngine.js` line 40 — `timeStep` config field is seconds, but the + internal time base is days). +- Temperature: `°C`. +- KLa: `1/h` per the schema; multiplied by the seconds-input `timeStep` + inside `_calcOTR` — readers verifying the math should account for the + day-internal time base. + +Unit conversion at the parent/child boundary happens via +`MeasurementContainer.UnitPolicy` and the `convert` utility. Other +nodes (rotatingMachine, pumpingStation, …) honour canonical units; +reactor is the only ASM-modelled node and pays the small cost of +domain-textbook units to stay aligned with every published reactor +reference. + ## Inputs (msg.topic on Port 0) | Canonical | Aliases (deprecated) | Payload | Effect |