# diffuser — Contract

Hand-maintained for Phase 6; the `## Inputs` table is generated from
`src/commands/index.js` (see Phase 9 generator). Keep ≤ 100 lines.

## Inputs (msg.topic on Port 0)

| Canonical | Aliases (deprecated) | Payload | Effect |
|---|---|---|---|
| `data.flow` | `air_flow` | `number` — airflow in Nm³/h | Calls `source.setFlow(payload)`; clamps to ≥ 0 and recomputes OTR. |
| `set.density` | `density` | `number` — diffuser density (per m²) | Calls `source.setDensity(payload)` and recomputes. |
| `set.water-height` | `height_water` | `number` — water column height in m | Calls `source.setWaterHeight(payload)`; clamps to ≥ 0 and recomputes head + total pressure. |
| `set.header-pressure` | `header_pressure` | `number` — header gauge pressure in mbar | Calls `source.setHeaderPressure(payload)` and recomputes. |
| `set.elements` | `elements` | `number` — element count (rounded; must be > 0) | Calls `source.setElementCount(payload)` and recomputes per-element flow. |
| `set.alfa-factor` | `alfaFactor` | `number` — alpha correction (≥ 0) | Calls `source.setAlfaFactor(payload)` and recomputes oxygen output. |

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

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

- **Port 0 (process):** `msg.topic = config.general.name`. Payload built
  by `outputUtils.formatMsg(..., 'process')` from `getOutput()` —
  delta-compressed (only changed fields are emitted). Fields:
  - `iPressure`, `iMWater`, `iFlow` — echoed inputs.
  - `nFlow` — normalised airflow (Nm³/h).
  - `oOtr` — interpolated oxygen transfer rate (g O₂ / Nm³).
  - `oPLoss` — total head loss (mbar) = static head + diffuser ΔP.
  - `oKgo2H` — kg O₂ per hour at current operating point.
  - `oFlowElement` — flow per element (Nm³/h/element).
  - `efficiency` — combined OTR/ΔP efficiency (0–100).
  - `slope` — local OTR-vs-flow slope.
  - `oZoneOtr` — reactor zone OTR (kg O₂ / m³ / day) computed against
    `diffuser.zoneVolume`; `0` when zone volume is unset.
  - `idle` — true when `data.flow ≤ 0`.
  - `warning`, `alarm` — string arrays describing flow-per-element band
    excursions.
- **Port 1 (InfluxDB telemetry):** same shape as Port 0, formatted with
  the `'influxdb'` formatter.
- **Port 2 (registration):** at startup the node sends one
  `{ topic: 'child.register', payload: <node.id>, positionVsParent,
  distance }` to the upstream parent (typically a reactor).
  `positionVsParent` defaults to `'atEquipment'`.

## Port-count change (Phase 6)

Pre-refactor the diffuser exposed 4 outputs (process, dbase, reactor
control with `topic: 'OTR'`, parent registration). The reactor control
message merged into Port 0 as `oZoneOtr`; consumers that previously
listened to the dedicated control port should switch to reading
`payload.oZoneOtr` from the process output. The legacy `OTR` topic is
removed in this refactor — there is no alias, since the data shape
differs (single value vs full process payload).

## Events emitted by `source.measurements.emitter`

None today. The diffuser does not currently publish typed measurements
through `MeasurementContainer`; all output flows via `getOutput()`.
A future phase may promote `oOtr` and `oZoneOtr` to typed series so
parent reactors can subscribe through the standard `ChildRouter`
handshake.

## Events emitted by `source.emitter`

- `output-changed` — fires whenever an input setter recomputes the
  oxygen-transfer state. `BaseNodeAdapter` listens and pushes the
  delta-compressed Port 0 / Port 1 messages.

## Children registered by this node

None. The diffuser is a leaf Equipment Module; it registers itself with
its parent (reactor / process cell) via the Port 2 handshake.