governance + unit-self-describing demand + dashboard fixes

Two governance items from the 2026-05-14 quality review:
- test/_output-manifest.md enumerates every Port 0/1/2 key MGC emits, its
  source, type, range, and which tests cover it in populated/degraded states
  (per .claude/rules/output-coverage.md).
- src/control/strategies.js extracts computeEqualFlowDistribution as a pure
  function so the equal-flow algorithm is testable without an MGC fixture.
  test/basic/equalFlowDistribution.basic.test.js (6 tests) covers all three
  demand branches and pins the legacy quirk where the default branch counts
  active machines but iterates priority-ordered first-N (documented in the
  test so the future cleanup is a deliberate change).

Plus rolled-up session work that landed alongside:
- set.demand is now unit-self-describing ({value, unit:'m3/h'|'l/s'|'%'|...}
  or bare number = %); setScaling/scaling.current removed from MGC, commands,
  editor (mgc.html), specificClass.
- _optimalControl + equalFlowControl now compute eta = (Q*dP)/P_shaft rather
  than Q/P, keeping the metric in the same scale as each child's cog.
- groupEfficiency.calcRelativeDistanceFromPeak returns undefined (was 1) when
  pumps are homogeneous (|max-min| < 1e-9). Dashboard treats undefined as
  '-' instead of showing a misleading 100% / 0% reading.
- examples/02-Dashboard.json: auto-init inject so the dashboard populates at
  deploy, NCog formatter normalizes the SUM emitted by MGC by
  machineCountActive, Q-H fanout trims the flat-Q tail so the H axis isn't
  stretched to 40m by curve-envelope clamp points, num/pct treat null AND
  undefined as no-data (closes the +null === 0 trap).
- new test/integration/dashboard-fanout.integration.test.js (17 tests),
  bep-distance-demand-sweep.integration.test.js (3 tests),
  group-bep-cascade.integration.test.js -- total suite now 108/108 green.
- .gitignore: wiki/test.gif (143 MB screen recording, kept locally only).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

test/basic/equalFlowDistribution.basic.test.js

@@ -0,0 +1,132 @@
+// Unit tests for the pure distribution math extracted out of equalFlowControl.
+// Decoupling target: the algorithm should be testable without a full MGC.
+
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { computeEqualFlowDistribution } = require('../../src/control/strategies.js');
+
+// Tiny helpers to make synthetic machines. The pure function still calls
+// filterOutUnavailableMachines, which reads machine.state.getCurrentState()
+// and machine.isValidActionForMode() — stub both so the algorithm sees the
+// machine as available. groupFlow/groupCalcPower are injected.
+function mkMachine(id, capability = { min: 0.01, max: 0.10, power: (flow) => flow * 1000 }, state = 'operational') {
+    return {
+        id,
+        machine: {
+            __testCapability: capability,
+            state: { getCurrentState: () => state },
+            isValidActionForMode: () => true,
+        },
+    };
+}
+const dummyLogger = { warn() {}, error() {}, debug() {}, info() {} };
+
+// Default injected helpers: read from the synthetic machine's __testCapability.
+const groupFlow = (m) => ({
+    currentFxyYMin: m.__testCapability.min,
+    currentFxyYMax: m.__testCapability.max,
+});
+const groupCalcPower = (m, flow) => m.__testCapability.power(flow);
+
+function basicArgs(overrides = {}) {
+    const m = { a: mkMachine('a').machine, b: mkMachine('b').machine, c: mkMachine('c').machine };
+    return {
+        machines: m, Qd: 0.06,
+        dynamicTotals: { flow: { min: 0.01, max: 0.30 } },
+        activeTotals:  { flow: { min: 0.03, max: 0.30 } },
+        priorityList: ['a', 'b', 'c'],
+        isMachineActive: () => true,
+        groupFlow, groupCalcPower, logger: dummyLogger,
+        ...overrides,
+    };
+}
+
+test('default case: distributes Qd equally across active machines', () => {
+    const r = computeEqualFlowDistribution(basicArgs({ Qd: 0.06 }));
+    // 3 active pumps, demand 0.06 → 0.02 per pump.
+    assert.equal(r.flowDistribution.length, 3);
+    for (const entry of r.flowDistribution) {
+        assert.ok(Math.abs(entry.flow - 0.02) < 1e-12, `entry.flow=${entry.flow}`);
+    }
+    assert.ok(Math.abs(r.totalFlow - 0.06) < 1e-12);
+    // power(flow) = flow * 1000 in the test capability → 0.02 * 1000 = 20 W per pump.
+    assert.ok(Math.abs(r.totalPower - 60) < 1e-9);
+});
+
+test('Qd above active capacity: starts additional priority machines until covered', () => {
+    // Only one machine "active" to start with; demand exceeds its envelope.
+    // Algorithm should bring more priority machines online via the high-demand branch.
+    const active = new Set(['a']);
+    const args = basicArgs({
+        Qd: 0.18, // above any single pump's max (0.10)
+        activeTotals: { flow: { min: 0.01, max: 0.10 } },
+        isMachineActive: (id) => active.has(id),
+    });
+    const r = computeEqualFlowDistribution(args);
+    // The algorithm reduces Qd iteratively (Qd /= i) until it fits per-pump max.
+    // We don't assert exact splits — only that flowDistribution is non-empty
+    // and totalFlow is finite, since the legacy algorithm is preserved as-is.
+    assert.ok(r.flowDistribution.length >= 1);
+    assert.ok(Number.isFinite(r.totalFlow));
+    assert.ok(Number.isFinite(r.totalPower));
+});
+
+test('Qd below active min flow: routes excess machines to flow=0 and redistributes', () => {
+    // demand below active min — algorithm shuts off lowest-priority machine(s)
+    // and redistributes Qd across the remainder.
+    const args = basicArgs({
+        Qd: 0.015,
+        dynamicTotals: { flow: { min: 0.01, max: 0.30 } },
+        activeTotals:  { flow: { min: 0.03, max: 0.30 } }, // active min > Qd
+    });
+    const r = computeEqualFlowDistribution(args);
+    const offCount = r.flowDistribution.filter(e => e.flow === 0).length;
+    assert.ok(offCount >= 1, `expected ≥1 machine to be shut off, got distribution: ${JSON.stringify(r.flowDistribution)}`);
+    const totalServed = r.flowDistribution.filter(e => e.flow > 0).reduce((s, e) => s + e.flow, 0);
+    assert.ok(Math.abs(totalServed - 0.015) < 1e-12, `served flow ${totalServed} should equal Qd 0.015`);
+});
+
+test('totalCog is always 0 for equalFlow — preserves legacy contract', () => {
+    // The historical algorithm sets totalCog = 0 in this strategy (BEP-Gravitation
+    // is the only optimizer that produces a meaningful per-combination cog).
+    // Pinned here so a future "improvement" doesn't silently introduce a fake value.
+    const r = computeEqualFlowDistribution(basicArgs());
+    assert.equal(r.totalCog, 0);
+});
+
+test('isMachineActive is consulted for COUNT but not for SELECTION (legacy quirk)', () => {
+    // Pins pre-existing behaviour of the default branch: it counts how many
+    // machines are active (countActive) to decide how to split Qd, but then
+    // iterates the FIRST countActive machines in priority order — which may
+    // include inactive ones. So 2 of 3 active + Qd within range → first 2 in
+    // priorityList both get flow, regardless of which are actually active.
+    //
+    // This is a latent bug that pre-dates the strategies decoupling refactor.
+    // Documenting it here so a future cleanup is a deliberate change with a
+    // failing-then-passing test, not a silent semantic shift.
+    const active = new Set(['a', 'c']);
+    const r = computeEqualFlowDistribution(basicArgs({
+        Qd: 0.06,
+        isMachineActive: (id) => active.has(id),
+    }));
+    // Today: machinesInPriorityOrder[0]='a', [1]='b' → 'a' and 'b' both get 0.03.
+    // 'c' (active but third in priority order) gets nothing.
+    const aFlow = r.flowDistribution.find(e => e.machineId === 'a')?.flow;
+    const bFlow = r.flowDistribution.find(e => e.machineId === 'b')?.flow;
+    const cFlow = r.flowDistribution.find(e => e.machineId === 'c')?.flow;
+    assert.equal(aFlow, 0.03, 'a (priority 0, active)');
+    assert.equal(bFlow, 0.03, 'b (priority 1, INACTIVE — receives flow anyway, bug)');
+    assert.equal(cFlow, undefined, 'c (priority 2, active — does NOT receive flow, bug)');
+});
+
+test('priorityList controls iteration order', () => {
+    // The order in flowDistribution should match priorityList — i.e., machine 'c'
+    // appears before machine 'a' when priorityList = ['c', 'b', 'a'].
+    const r = computeEqualFlowDistribution(basicArgs({
+        priorityList: ['c', 'b', 'a'],
+    }));
+    assert.equal(r.flowDistribution[0].machineId, 'c');
+});