# valveGroupControl

> **Reflects code as of `e02cd1a` · regenerated `2026-05-11` via `npm run wiki:all`**
> If this banner is stale, the page may be out of date. Treat as informative, not authoritative.

## 1. What this node is

**valveGroupControl** (VGC) is an S88 Unit that distributes a group-level flow target across registered `valve` children proportional to their current Kv, aggregates the per-valve accepted flow back into a group total, and surfaces the maximum delta-P across the group. It also reconciles each child's fluid-contract advertisement into a single group-level service-type view.

## 2. Position in the platform

```mermaid
flowchart LR
    src[machine / MGC / PS<br/>upstream source]:::unit -.flow.predicted.-> vgc[valveGroupControl<br/>Unit]:::unit
    vgc -->|set.position| v1[valve A]:::equip
    vgc -->|set.position| v2[valve B]:::equip
    v1 -->|evt.deltaPChange| vgc
    v2 -->|evt.deltaPChange| vgc
    vgc -->|child.register| parent[upstream parent]:::unit
    classDef unit fill:#50a8d9,color:#000
    classDef equip fill:#86bbdd,color:#000
```

S88 colours: Unit `#50a8d9`, Equipment `#86bbdd`. Source of truth: `.claude/rules/node-red-flow-layout.md`.

## 3. Capability matrix

| Capability | Status | Notes |
|---|---|---|
| Proportional flow distribution by Kv | ✅ | `groupOps/flowDistribution.js`. |
| Two-pass residual reconciliation | ✅ | `maxPasses: 2`, `residualTolerance: 0.001`. |
| Periodic tick re-balance | ✅ | Runs each adapter tick; `set.reconcileInterval` re-tunes. |
| Group `maxDeltaP` aggregation | ✅ | Recomputed on any child `deltaPChange`. |
| Upstream fluid-contract aggregation | ✅ | `sources/fluidContract.js`. |
| Sequence dispatch to all valves | ✅ | `cmd.execSequence` → per-valve `handleInput`. |
| Per-valve positional override | ❌ | `set.position` reserved; no-op in current build. |
| Multi-source aggregation | ✅ | Multiple machines / MGCs may register as sources. |

## 4. Code map

```mermaid
flowchart TB
    subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"]
        nc["buildDomainConfig()<br/>static DomainClass, commands"]
    end
    subgraph domain["specificClass.js — orchestrator (BaseDomain)"]
        sc["ValveGroupControl.configure()<br/>registerChild dispatch<br/>tick → calcValveFlows"]
    end
    subgraph concerns["src/ concern modules"]
        gops["groupOps/<br/>flowDistribution"]
        srcs["sources/<br/>fluidContract"]
        cmds["commands/<br/>topic registry + handlers"]
        io["io/<br/>output + status badge"]
    end
    nc --> sc
    sc --> gops
    sc --> srcs
    sc --> io
    nc --> cmds
```

| Module | Owns | Read first if you're changing… |
|---|---|---|
| `groupOps/` | Flow distribution, residual solver, max-deltaP aggregation | How the group divides flow. |
| `sources/` | Upstream-source registration, fluid-contract reconciliation | Service-type aggregation, source-event subscriptions. |
| `commands/` | Input-topic registry + per-topic handlers | New input topics, payload validation. |
| `io/` | Port-0 output shape + status badge | What lands on the wire. |

## 5. Topic contract

> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`.

<!-- BEGIN AUTOGEN: topic-contract -->

| Canonical topic | Aliases | Payload | Effect |
|---|---|---|---|
| `set.mode` | `setMode` | `string` | Replaces the named state value with the supplied payload. |
| `set.position` | `setpoint` | `any` | Replaces the named state value with the supplied payload. |
| `child.register` | `registerChild` | `string` | Parent/child plumbing — registers or unregisters a child node. |
| `cmd.execSequence` | `execSequence` | `object` | Triggers an action / sequence — not idempotent. |
| `data.totalFlow` | `totalFlowChange` | `any` | Pushes a value into the node's measurement stream. |
| `cmd.emergencyStop` | `emergencyStop`, `emergencystop` | `any` | Triggers an action / sequence — not idempotent. |
| `set.reconcileInterval` | `setReconcileInterval` | `any` | Replaces the named state value with the supplied payload. |

<!-- END AUTOGEN: topic-contract -->

## 6. Child registration

```mermaid
flowchart LR
    subgraph kids["accepted children (softwareType)"]
        v["valve"]:::equip
        src["machine / rotatingmachine /<br/>machinegroup / pumpingstation /<br/>valvegroupcontrol"]:::unit
    end
    v   -->|positionChange| handler1[onPositionChange<br/>calcValveFlows]
    v   -->|deltaPChange|   handler2[onDeltaPChange<br/>calcMaxDeltaP]
    src -->|flow.predicted.*| handler3[updateFlow<br/>at atEquipment]
    src -->|fluidContractChange| handler4[sources.refresh<br/>aggregate contract]
    classDef equip fill:#86bbdd,color:#000
    classDef unit fill:#50a8d9,color:#000
```

| softwareType | onRegister side-effect | Subscribed events |
|---|---|---|
| `valve` | Stored in `this.valves[id]`; binds `positionChange` + `deltaPChange`; triggers `calcValveFlows` + `calcMaxDeltaP`. | `positionChange`, `deltaPChange`. |
| `machine` / `rotatingmachine` | Stored as upstream source; reads `getFluidContract()` (or default `liquid`). | `flow.predicted.*`, `flow.measured.*`, `fluidContractChange`. |
| `machinegroup` / `machinegroupcontrol` | Same as machine. | Same as machine. |
| `pumpingstation` | Same as machine. | Same as machine. |
| `valvegroupcontrol` | Allowed for cascaded VGCs; not exercised in production. | Same. |

## 7. Lifecycle — what one tick / event does

```mermaid
sequenceDiagram
    participant src as upstream source
    participant vgc as VGC
    participant v1 as valve A
    participant v2 as valve B
    participant out as Port-0

    src->>vgc: flow.predicted.downstream (m3/s)
    vgc->>vgc: _write flow.predicted.atEquipment
    vgc->>vgc: calcValveFlows()
    Note over vgc: solveFlowDistribution<br/>(by Kv share)
    vgc->>v1: updateFlow('predicted', shareA, 'downstream')
    vgc->>v2: updateFlow('predicted', shareB, 'downstream')
    v1-->>vgc: accepted flow + deltaPChange
    v2-->>vgc: accepted flow + deltaPChange
    vgc->>vgc: residual pass (up to maxPasses)
    vgc->>vgc: calcMaxDeltaP
    vgc->>out: msg{topic, payload (delta-compressed)}
```

## 11. Distribution loop — flow-share solver

VGC has no FSM. The loop below replaces the state chart for this section.

```mermaid
sequenceDiagram
    participant tick as adapter tick / event
    participant vgc as VGC
    participant solver as solveFlowDistribution
    participant valves as valve children

    tick->>vgc: calcValveFlows()
    vgc->>vgc: read flow.measured / predicted .atEquipment
    vgc->>solver: target=totalFlow, entries=availableValves
    loop ≤ maxPasses while |residual| > tolerance
        solver->>valves: updateFlow share by (Kv / totalKv)
        valves-->>solver: accepted flow back
        solver->>solver: residual = target - sum(accepted)
    end
    solver-->>vgc: { flowsById, residual, passes }
    vgc->>vgc: write flow.predicted.atEquipment = assignedTotal
    vgc->>vgc: notifyOutputChanged()
```

## 8. Data model — `getOutput()`

What lands on Port 0. Composed in `io/output`, then delta-compressed by `outputUtils.formatMsg`.

<!-- BEGIN AUTOGEN: data-model -->

| Key | Type | Unit | Sample |
|---|---|---|---|
| `maxDeltaP` | number | — | `0` |
| `mode` | string | — | `"auto"` |

<!-- END AUTOGEN: data-model -->

Measurement-derived keys follow the `<position>_<variant>_<type>` shape (e.g. `atEquipment_predicted_flow`) and are emitted only when the container holds a finite value.

## 9. Configuration — editor form ↔ config keys

```mermaid
flowchart TB
    subgraph editor["Node-RED editor form"]
        f1[Mode]
        f2[Sequences]
        f3[Allowed sources per mode]
        f4[Reconciliation interval]
    end
    subgraph config["Domain config slice"]
        c1[mode.current]
        c2[sequences.<name>]
        c3[mode.allowedSources.<mode>]
        c4[flowReconciliation (runtime)]
    end
    f1 --> c1
    f2 --> c2
    f3 --> c3
    f4 --> c4
```

| Form field | Config key | Default | Range | Where used |
|---|---|---|---|---|
| Mode | `mode.current` | per schema | enum | `setMode` |
| Sequences | `sequences.<name>` | per schema | Set of state names | `executeSequence` |
| Allowed sources | `mode.allowedSources.<mode>` | per schema | Set of source ids | `isValidSourceForMode` |
| Reconcile maxPasses | `flowReconciliation.maxPasses` | `2` | ≥ 1 | `solveFlowDistribution` |
| Reconcile tolerance | `flowReconciliation.residualTolerance` | `0.001` | ≥ 0 | `solveFlowDistribution` |
| Reconcile interval | (runtime, via `set.reconcileInterval`) | adapter default | ≥ 100 ms | `setReconcileIntervalSeconds` |

## 10. State chart

Skipped — VGC has no FSM of its own. State semantics belong to the child valves; VGC is a coordinator. See section 11 for the flow-distribution loop.

## 11. Examples

| Tier | File | What it shows | Mandatory? |
|---|---|---|---|
| Basic | `examples/01-Basic.flow.json` | Inject `data.totalFlow` + 2 valves + dashboard | ✅ |
| Integration | `examples/02-Integration.flow.json` | VGC + valves + upstream rotatingMachine | ✅ |
| Dashboard | `examples/03-Dashboard.flow.json` | Live FlowFuse charts (per-valve flow, max ΔP) | ⭕ |

Screenshots under `wiki/_partial-screenshots/valveGroupControl/` when produced. Docker compose snippet under `examples/README.md`.

## 12. Debug recipes

| Symptom | First thing to check | Where to look |
|---|---|---|
| All valves show `assigned flow = 0` | `getAvailableValves()` empty; check Kv > 0 and state ≠ `off` / `maintenance`. | `groupOps/flowDistribution.isValveAvailable` |
| Residual never converges | `flowReconciliation.maxPasses` too low for the valve curve shape. | `lastFlowSolve.residual` |
| Group `maxDeltaP` stale | Child `deltaPChange` not subscribed; valve emitter not exposed. | `_bindValveEvents` |
| Service-type stays `unknown` | No source registered yet or all sources advertise unknown. | `sources.refreshFluidContract` |
| `data.totalFlow` ignored | Mode rejects the source; check `mode.allowedSources`. | `isValidSourceForMode` |

> Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors. Use only for live debugging.

## 13. When you would NOT use this node

- Use VGC for **2+ parallel valves** sharing a header. For a single valve, wire `valve` directly under the upstream parent.
- Don't use VGC to coordinate series valves — the flow-distribution model assumes parallel branches with a shared upstream pressure.
- Skip VGC when the upstream source already publishes per-branch flow setpoints; route those straight to each valve.

## 14. Known limitations / current issues

| # | Issue | Tracked in |
|---|---|---|
| 1 | `set.position` is reserved but currently a no-op — per-valve override is pending Phase 7. | CONTRACT.md `## Inputs` |
| 2 | Residual solver assumes Kv share is a good first estimate; pathological curves can need more passes than the default `2`. | `groupOps/flowDistribution.js` |
| 3 | Cascaded `valvegroupcontrol` registration accepted but not test-covered. | CONTRACT.md `## Children` |