# rotatingMachine — Contract

Hand-maintained for Phase 5; 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 |
|---|---|---|---|
| `set.mode` | `setMode` | `string` — one of the allowed mode names | Calls `source.setMode(payload)`. |
| `cmd.startup` | — | `{ source?: string }` | Calls `source.handleInput(payload.source ?? 'parent', 'execSequence', 'startup')`. |
| `cmd.shutdown` | — | `{ source?: string }` | Calls `source.handleInput(payload.source ?? 'parent', 'execSequence', 'shutdown')`. |
| `cmd.estop` | `emergencystop` | `{ source?: string, action?: string }` | Calls `source.handleInput(payload.source ?? 'parent', payload.action ?? 'emergencystop')`. |
| `execSequence` | — (legacy umbrella) | `{ source, action, parameter }` with `action ∈ {'startup','shutdown'}` | Content-based router: forwards to `cmd.startup` / `cmd.shutdown` handler based on `payload.action`. Unknown action logs `warn` and is dropped. Whole topic is legacy — prefer the canonical `cmd.*` topics. |
| `set.setpoint` | `execMovement` | `{ source, action, setpoint }` — setpoint coerced to `Number` | Calls `source.handleInput(payload.source ?? 'parent', payload.action ?? 'execMovement', Number(payload.setpoint))`. |
| `set.flow-setpoint` | `flowMovement` | `{ source, action, setpoint }` | Calls `source.handleInput(payload.source ?? 'parent', payload.action ?? 'flowMovement', Number(payload.setpoint))`. |
| `data.simulate-measurement` | `simulateMeasurement` | `{ type, position?, value, unit, timestamp? }` — `type ∈ {pressure, flow, temperature, power}`; `position` defaults to `'atEquipment'` | Validated dispatch: rejects non-finite `value`, unsupported `type`, missing `unit`, or unit that fails `isUnitValidForType`. Pressure routes via `updateSimulatedMeasurement(type, position, value, ctx)`; flow/temperature/power route via `updateMeasured<Type>(value, position, ctx)`. The injected `childId/childName = 'dashboard-sim'` marks the source. |
| `query.curves` | `showWorkingCurves` | none | Calls `source.showWorkingCurves()` and replies on **Port 0** with `{ topic: 'showWorkingCurves', payload: <result> }` via `ctx.send`. |
| `query.cog` | `CoG` | none | Calls `source.showCoG()` and replies on **Port 0** with `{ topic: 'showCoG', payload: <result> }`. |
| `child.register` | `registerChild` | `string` — child Node-RED id; `msg.positionVsParent` carries position | Resolves child via `RED.nodes.getNode(payload)` and registers it through `childRegistrationUtils.registerChild(child.source, msg.positionVsParent)`. Unknown ids log `warn`. |

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

### `execSequence` demux

The pre-refactor topic `execSequence` carried `{ source, action, parameter }`
where `action` selected the verb (`startup` or `shutdown`). The command
registry does not natively dispatch by payload content, so `execSequence`
keeps its own descriptor whose handler **forwards directly** to the
canonical `cmd.startup` / `cmd.shutdown` handler based on
`payload.action`. The deprecation warning fires once. Future-Phase-7
removal of `execSequence` is a behavioural change — callers must migrate
to `cmd.startup` / `cmd.shutdown`.

## 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). On `query.curves` / `query.cog` the
  node additionally emits `{ topic: 'showWorkingCurves' | 'showCoG',
  payload: <result> }` as a synchronous reply on Port 0.
- **Port 1 (InfluxDB telemetry):** same shape as Port 0, formatted with the
  `'influxdb'` formatter.
- **Port 2 (registration):** at startup the node sends one
  `{ topic: 'registerChild', payload: <node.id>, positionVsParent }` to
  the upstream parent (typically a `machineGroupControl` or
  `pumpingStation`). `positionVsParent` defaults to `'atEquipment'`.

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

The `MeasurementContainer` fires `<type>.<variant>.<position>` whenever
the corresponding series receives a new value. Parents subscribe via the
generic `child.measurements.emitter.on(eventName, ...)` handshake.
rotatingMachine publishes:

- `flow.predicted.atequipment`, `flow.predicted.downstream`,
  `flow.predicted.max`, `flow.predicted.min` — predicted operating point.
- `power.predicted.atequipment` — predicted shaft power.
- `temperature.measured.atequipment` — ambient/process temperature.
- `atmPressure.measured.atequipment` — barometric reference.
- `pressure.measured.upstream`, `pressure.measured.downstream`,
  `pressure.measured.differential` — when pressure children register or
  `data.simulate-measurement type=pressure` runs.
- `flow.measured.<position>`, `power.measured.atequipment`,
  `temperature.measured.<position>` — when sensor children register or
  the `data.simulate-measurement` topic supplies values.

Position labels are normalised to lowercase in the event name. The exact
set is data-driven by which children register and what they publish.

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

- `positionChange` — fires when the position percentage changes (per
  movement tick). Data: `{ position, state, mode, timestamp }`.
- `stateChange` — fires on transitions of the operating state machine
  (`idle → starting → warmingup → operational → accelerating →
  decelerating → stopping → coolingdown → idle`, plus `off`,
  `maintenance`). Data: the new state string.

## Children registered by this node

rotatingMachine accepts `measurement` children through the
`childRegistrationUtils` handshake. Children typically have
`asset.type ∈ {pressure, flow, power, temperature}`. The machine
subscribes to the matching `<asset.type>.measured.<positionVsParent>`
event and mirrors the value into its own `MeasurementContainer`.

Two **virtual** children are reserved by the `data.simulate-measurement`
topic: incoming simulated values are tagged with
`childId/childName = 'dashboard-sim'` so dashboard-driven inputs are
distinguishable from real sensor children in downstream telemetry.

Position labels accepted from children are `upstream`, `downstream`,
`atEquipment` (and case variants — normalised internally).