reactor/CONTRACT.md

# reactor — Contract

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 |
|---|---|---|---|
| `data.clock` | `clock` | `msg.timestamp` (ms since epoch) | Calls `source.updateState(timestamp)` — advances the ASM kinetics integrator by `n_iter` time steps that fit between `currentTime` and the supplied timestamp (scaled by `speedUpFactor`). |
| `data.fluent` | `Fluent` | `{ inlet: number, F: number, C: number[13] }` | Writes the per-inlet flow rate (`F`, m³/d) and concentration vector (`C`) into `engine.Fs[inlet]` / `engine.Cs_in[inlet]`. |
| `data.otr` | `OTR` | numeric | Sets the externally-supplied oxygen transfer rate (used when `kla` is NaN). |
| `data.temperature` | `Temperature` | numeric or `{ value: number }` | Sets `engine.temperature` (°C). Non-numeric payloads are warned and ignored. |
| `data.dispersion` | `Dispersion` | numeric | PFR only — sets the axial dispersion coefficient `D` (m²/d). |
| `child.register` | `registerChild` | child node id (string) | Looks up the sibling node via `RED.nodes.getNode(id)` and delegates to `source.childRegistrationUtils.registerChild` with `msg.positionVsParent`. |

Aliases log a one-time deprecation warning the first time they fire.

## Outputs (msg.topic on Port 0/1/2)

- **Port 0 (process):** every tick emits the engine's effluent:
  `{ topic: 'Fluent', payload: { inlet: 0, F, C: number[13] }, timestamp }`.
  For a PFR an additional `{ topic: 'GridProfile', payload: { grid, n_x, d_x, length, species, timestamp } }`
  message goes out on the same port before the effluent.
- **Port 1 (InfluxDB telemetry):** formatted via `outputUtils.formatMsg(..., 'influxdb')`
  from `getOutput()` — carries `flow_total`, `temperature`, and one field per ASM3
  species (`S_O`, `S_I`, `S_S`, `S_NH`, `S_N2`, `S_NO`, `S_HCO`, `X_I`, `X_S`, `X_H`,
  `X_STO`, `X_A`, `X_TS`).
- **Port 2 (registration):** at startup the node sends one
  `{ topic: 'child.register', payload: <node.id>, positionVsParent, distance }`
  to its parent.

## Events emitted by `source.emitter`

- `stateChange` — fires after every `updateState()` that advances the integrator.
  Payload is the new `currentTime` (ms since epoch). Downstream reactors register
  via `child.register` and subscribe to this event to pull the upstream
  effluent on each advance.
- `output-changed` — base notification fired by `updateState()` so the
  BaseNodeAdapter pipeline pushes outputs (currently used only as a heartbeat;
  effluent is emitted directly from the periodic tick).

## Children accepted

- `measurement` — subscribes to `<type>.measured.<position>` on the child's
  `measurements.emitter`. Recognised reconciliations: `temperature.measured.atEquipment`
  writes `engine.temperature`; PFR additionally honours
  `quantity (oxygen).measured.<distance>` to reconcile dissolved-oxygen
  concentration into the nearest grid cell.
- `reactor` — registers as the upstream reactor; the downstream `updateState`
  pulls the upstream effluent into `Fs[0]` / `Cs_in[0]` before integrating.