valve/CONTRACT.md

# valve — Contract

Generated from `src/commands/index.js` (canonical topic + alias list) plus
the hand-written events section. 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)`. Invalid mode logs `warn` and is dropped. |
| `cmd.startup` | — | `{ source?: string }` | Calls `source.handleInput(payload.source ?? 'parent', 'execSequence', 'startup')`. |
| `cmd.shutdown` | — | `{ source?: string }` | Calls `source.handleInput(payload.source ?? 'parent', 'execSequence', 'shutdown')`. Pre-shutdown the valve ramps to position 0 if currently operational. |
| `cmd.estop` | `emergencystop`, `emergencyStop` | `{ source?: string, action?: string }` | Calls `source.handleInput(payload.source ?? 'parent', payload.action ?? 'emergencystop')`. |
| `execSequence` | — (legacy umbrella) | `{ source, action, parameter }` with `action ∈ {'startup','shutdown','emergencyStop','emergencystop'}` | Content-based router: forwards to canonical `cmd.startup` / `cmd.shutdown` / `cmd.estop` based on `payload.action`. Unknown action logs `warn`. Prefer the canonical `cmd.*` topics. |
| `set.position` | `execMovement` | `{ source, action, setpoint }` — setpoint coerced to `Number`; valve position percent in `[0, 100]` | Calls `source.handleInput(payload.source ?? 'parent', payload.action ?? 'execMovement', Number(payload.setpoint))`. |
| `data.flow` | `updateFlow` | `{ variant, value, position, unit? }` — `variant ∈ {'measured','predicted'}` | Pushes a flow value into the measurement container at `<position>` and triggers a deltaP recompute through the hydraulic model. |
| `query.curve` | `showcurve` | none | Calls `source.showCurve()` and replies on **Port 0** with `{ topic: 'Showing curve', payload: <result> }` via `ctx.send`. |
| `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)`. The valve's `registerChild` records the child for fluid-contract tracking. |

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. 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` / `cmd.estop` handler based on `payload.action`. The
deprecation warning fires once. Future-Phase-7 removal of `execSequence`
is a behavioural change — callers must migrate to the canonical topics.

## 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.curve` the node additionally
  emits `{ topic: 'Showing curve', 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: 'child.register', payload: <node.id>, positionVsParent, distance }`
  to its upstream parent (typically a `valveGroupControl`).
  `positionVsParent` defaults to `'atEquipment'`.

`getOutput()` keys per tick include: `<position>_<variant>_<type>` slots
from the measurement container (e.g. `delta_predicted_pressure`,
`downstream_measured_flow`), plus `state`, `percentageOpen`, `moveTimeleft`,
`mode`.

## Events emitted by `source.emitter`

- `deltaPChange` — fires whenever the hydraulic model recomputes a finite
  deltaP. Data: the deltaP value in `unitPolicy.output.pressure` (default
  `mbar`). Consumed by `valveGroupControl` to update group totals.
- `fluidCompatibilityChange` — fires when the upstream fluid-contract
  status changes (status / expected / received / sourceCount / message).
  Data: `FluidCompatibility.getCompatibility()`.
- `fluidContractChange` — fires whenever the fluid contract that this valve
  advertises downstream changes. Data: `FluidCompatibility.getContract()`.

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

- `positionChange` — fires when the position percentage changes (per
  movement tick). Data: `{ position, state, mode, timestamp }`. The valve
  itself listens and triggers a Kv lookup + deltaP recompute.
- `stateChange` — fires on transitions of the operating state machine
  (`idle → starting → warmingup → operational → accelerating →
  decelerating → stopping → coolingdown → idle`, plus `off`).

## Limitations vs `rotatingMachine`

- **No `maintenance` state machine.** The schema's `mode.current` enum
  accepts `maintenance` (gates sources via `isValidSourceForMode`), but
  the FSM has no `entermaintenance` / `exitmaintenance` states and the
  `sequences` schema declares only `startup`, `shutdown`, `emergencystop`,
  and `boot`. Configuring `maintenance` mode therefore disables external
  command sources but does not put the valve through a maintenance
  sequence. Aligns with valve's role as a passive flow-controlled
  actuator; lift to RM-style FSM if/when site maintenance procedures
  require explicit state transitions.

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

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

- `pressure.predicted.delta` — predicted pressure drop across the valve.
- `pressure.measured.<position>`, `pressure.predicted.<position>` — when
  upstream pressure data arrives via `data.flow`-driven recompute or
  direct measurement pushes.
- `flow.measured.<position>`, `flow.predicted.<position>` — mirrored from
  upstream sources via `data.flow`.

Position labels are normalised to lowercase in the event name.

## Children registered by this node

valve accepts upstream sources (`machine`, `rotatingmachine`,
`machinegroup`, `machinegroupcontrol`, `pumpingstation`, `valvegroupcontrol`,
…) via `child.register`. The handler records each child for fluid-contract
tracking: the valve reads either the child's `getFluidContract()` result,
its `asset.serviceType` field, or a default per software type
(`liquid` for the rotating-equipment family). It then subscribes to the
child's `fluidContractChange` so re-keyed contracts propagate.