valveGroupControl/CONTRACT.md

valveGroupControl — Contract

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

Inputs (msg.topic on Port 0)

Canonical	Aliases (deprecated)	Payload	Effect
set.mode	setMode	string — one of auto, virtualControl, fysicalControl, maintenance	Switches the control strategy via source.setMode(payload).
set.position	setpoint	any	Reserved for future per-valve positional override; currently a debug-logged no-op pending Phase 7.
child.register	registerChild	string — the child node's Node-RED id	Resolves the child via RED.nodes.getNode and registers it through childRegistrationUtils.registerChild(childObj.source, msg.positionVsParent).
cmd.execSequence	execSequence	{ source, action, parameter }	Forwards to source.handleInput(source, action, parameter).
data.totalFlow	totalFlowChange	numeric, { value, position?, variant?, unit? }, or { source, action, ... }	Updates total measured/predicted flow at the configured position; drives calcValveFlows to re-distribute across valves.
cmd.emergencyStop	emergencyStop, emergencystop	optional { source }	Runs the emergencystop sequence via handleInput.
set.reconcileInterval	setReconcileInterval	numeric — seconds (> 0)	Re-tunes the periodic flow-reconciliation interval. Min clamp 100 ms.

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). Output keys follow <position>_<variant>_<type> plus mode and maxDeltaP.
• 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 } to the upstream parent.

Events emitted by source.emitter / source.measurements.emitter

• output-changed (source.emitter) — public output state shifted; the adapter listens and pushes Ports 0/1.
• fluidContractChange (source.emitter) — group-level fluid contract (status / serviceType / sourceCount) changed. Parents (e.g. an upstream valve registering this VGC as its parent) subscribe to react.
• reconcileIntervalChange (source.emitter) — emitted by setReconcileIntervalSeconds; the adapter restarts the tick loop.
• flow.predicted.atequipment (source.measurements.emitter) — total predicted group flow (sum of per-valve assigned flows).
• pressure.predicted.deltaMax (source.measurements.emitter) — max delta-P across registered valves.

The exact set is data-driven by which sources/valves register and what they publish; downstream consumers subscribe by event name.

Children registered by this node

valveGroupControl accepts two child classes through the childRegistrationUtils handshake:

• valve — an individual valve. Stored in source.valves[id]. VGC binds to the child's positionChange (via child.state.emitter) and deltaPChange (via child.emitter) events to re-distribute flow and re-compute group max delta-P.
• machine / rotatingmachine / machinegroup / machinegroupcontrol / pumpingstation / valvegroupcontrol — an upstream source. Stored in source.sources[id]. VGC subscribes to the source's flow.predicted.* / flow.measured.* events to drive updateFlow, and reads the child's getFluidContract() (if present) plus fluidContractChange events to aggregate the group's upstream service type (getFluidContract() exposes the resolved view).

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