EVOLV/.claude/refactor/OPEN_QUESTIONS.md

# Open questions

Things deferred. Append, don't rewrite history. Add a date when you add
or resolve an entry. Anyone (human or agent) discovering an unclear
decision during refactor work writes it here rather than guessing.

---

## 2026-05-11 — Interview round — resolved decisions

| Topic | Decision |
|---|---|
| Ramp foot for run-zone curve (control/levelBased) | `inflowLevel` (current). startLevel is the 0% minimum, not the curve foot. |
| `overfillLevel` vs `highVolumeSafetyLevel` | **`highVolumeSafetyLevel` canonical**; drop the legacy alias. |
| measurement `isStable` tautology | Fix now with a config-driven absolute threshold (`stabilityThreshold` in scaling-units). Add to schema + editor UI. |
| monster cooldown-guard pre-existing fail | **RESOLVED 2026-05-11** — root cause was missing `nominalFlowMin`/`flowMax`/`maxRainRef`/`minSampleIntervalSec` in `monster.json`, stripped by `configUtils.initConfig` before reaching the domain. Added the four keys to the schema. |
| pumpingStation plain child dicts | Migrate to `declareChildGetter`; rewrite affected tests. |
| VGC custom `registerChild` overload | Adopt ChildRouter; rewrite disambiguation tests. |
| MGC inline dispatch gate vs LatestWinsGate | Extend LatestWinsGate with `fireAndWait(value)` returning the per-fire settlement promise. Migrate MGC. |
| measurement legacy `'mAbs'` event | Remove now. |
| ChildRouter wildcard emit-patch | Per-listener fan-out using canonical POSITIONS. No more emit patching. |
| commandRegistry payload schema | Add `'none'` type + per-command `description` field (wikiGen consumes). |
| UnitPolicy property-vs-method shape | Expose both. Frozen property bags alongside the methods. Drop `_unitView` workarounds. |
| rotatingMachine + reactor private-method-pinning tests (13 files) | Rewrite all to drive only the public BaseNodeAdapter surface. Phase 10. |
| **Unit-aware commands (new)** | Each numeric setter declares `units: { measure, default }`. commandRegistry normalises + warns + lists accepted units. `query.units` topic returns spec. Phase 11. |


Format:

```
## YYYY-MM-DD — Short title

**Context:** what we're trying to do
**Question:** what's unresolved
**Default chosen:** what we did meanwhile
**Decision needed by:** which phase or task
```

---

## 2026-05-10 — External Port-0 topic naming — RESOLVED

**Decision (2026-05-10):** Use canonical names (`set.*` / `cmd.*` /
`data.*` / `child.*` / `query.*` / `evt.*`) **from Phase 1 onwards**.
Each `commands/index.js` declares the canonical name as the topic and
lists legacy names in `aliases`. Aliases log a one-time deprecation
warning. Phase 7 shrinks to: remove aliases after one release cycle.

The full prefix glossary (with what each does and why) is now in
`CONTRACTS.md §1`. See it before naming a topic.

---

## 2026-05-10 — Parent EVOLV repo `development` branch lineage — RESOLVED

**Decision (2026-05-10):** Rebase parent `development` onto
`origin/main` before the refactor proceeds. Done at the start of
Phase 1.

---

## 2026-05-10 — `generalFunctions` deprecated paths — RESOLVED

**Decision (2026-05-10):** Tracked as Phase 8.5 in `TASKS.md`. Cleanup
runs after promotion to main. The list of paths to remove is captured
there so it isn't lost.

---

## 2026-05-10 — Two child-storage shapes — RESOLVED

**Decision (2026-05-10):** Registry-as-truth, **with named getters** that
read clearly in code. `domain.machines` keeps working — it's a getter
that returns the rotatingMachine slice of `this.child`. Same for
`domain.stations`, `domain.machineGroups`, etc. Domain code reads
naturally; the registry is the source of truth underneath.

Named getters are declared by the domain subclass in `configure()`:

```js
configure() {
  Object.defineProperty(this, 'machines',
    { get: () => this.child?.machine?.centrifugal ?? {} });
}
```

(`BaseDomain` provides a helper for this pattern.)

---

## 2026-05-10 — Async vs sync `tick()` — RESOLVED with redesign

**Decision (2026-05-10):** Default is **event-driven**. Ticks are
opt-in.

`BaseNodeAdapter` exposes two timers:

- `static tickInterval = null` — opt-in periodic tick. Default null = no
  tick. Domain emits `'output-changed'` on `this.emitter` instead, and
  BaseNodeAdapter subscribes to that event to push outputs.
- `static statusInterval = 1000` — always-on status badge poll.
  Required because Node-RED's editor refresh expects a heartbeat. Set
  to 0 only in headless test environments.

When opting into ticks:
- Document **why** in a one-line comment above
  `static tickInterval = ...` (e.g. "needs delta-time for predicted
  volume integrator").
- A node should opt in only when truly time-driven. Examples that need
  it: `pumpingStation` (predicted volume integrates over time),
  `measurement` (when simulator is enabled — ticks the random walk).
- Examples that DO NOT need it: `MGC` (recomputes on pressure events),
  `rotatingMachine` (recomputes on measurement events + state changes).

`tick()` is treated as fire-and-forget (no await). A node that needs
serialisation uses `LatestWinsGate` internally.

See `CONTRACTS.md §2` for the BaseNodeAdapter shape.

---

## 2026-05-10 — ChildRouter wildcard subscriptions monkey-patch `emit` — RESOLVED

**Resolution (2026-05-11):** Switched to per-listener fan-out using the
canonical `POSITIONS` list and a 19-type set (`MeasurementContainer.measureMap`
keys + synthetic EVOLV types). Each partial-filter subscription enumerates
every concrete `<type>.<variant>.<position>` event name and registers a
plain `emitter.on()` per combo. Multi-parent works without emit patching.
ChildRouter.js 184 → 164 lines; 12/12 tests pass including a new
multi-parent regression test.

### Original entry below
## 2026-05-10 — ChildRouter wildcard subscriptions monkey-patch `emit` (history)

**Context:** P1.2 implementation. EventEmitter has no native wildcard.
Subscriptions with a partial filter (`{type}`-only or `{position}`-only)
install a per-variant `emit` proxy on the child's emitter; concrete
`{type, position}` filters use plain `emitter.on`.

**Question:** Multi-parent children. `child.parent` is already an array
in `childRegistrationUtils`, so a child can be registered under several
parents. If two parents each install ChildRouter wildcard proxies on
the same `child.measurements.emitter`, the wraps stack — but
`tearDown` only unwraps when its own bookkeeping is empty. Is this
correct semantics for multi-parent teardown ordering? Or should we
switch to per-listener fan-out (subscribe to every known
`<type>.<variant>.<position>` enumerated from a registry)?

**Default chosen:** Stacked wrappers. The current `childRegistrationUtils`
multi-parent path is rarely exercised in production. Revisit if
Phase 2 / Phase 4 hits a real multi-parent case.

**Decision needed by:** Phase 4.

---

## 2026-05-10 — `predictionHealth` migration in rotatingMachine

**Context:** P1.4 implementation flagged that the existing
`rotatingMachine.predictionHealth` carries `quality` (string) +
`confidence` (0..1 numeric) on top of the new `HealthStatus` shape's
`{level, flags, message, source}`.

**Question:** Where does `confidence` live after migration?

**Default chosen:** Keep `confidence` on the per-metric drift
container as a sibling to a `health: HealthStatus` field. Drift
diagnostics (`nrmse`, `longTermNRMSD`, `immediateLevel`) stay as
siblings too. `HealthStatus` carries only the standardised five fields.

**Decision needed by:** Phase 5 (`rotatingMachine` refactor).

---

## 2026-05-10 — `dashboardAPI` basic test broken (pre-existing) — RESOLVED

**Context:** P1.12 sanity gate. `dashboardAPI/test/basic/structure-module-load.basic.test.js` uses Mocha-style `describe()` globals which don't exist under `node:test`. Reports 0 pass / 1 fail with `ReferenceError: describe is not defined`.

**Action:** Pre-existing — not caused by Phase 1. Convert to `node:test` form during Phase 6 when `dashboardAPI` gets its skeleton refactor. Tracked here so it isn't lost.

**Update (P6.7, 2026-05-10):** Converted to `node:test` form (`const test = require('node:test')` + `assert.doesNotThrow`). Basic test now reports 1 pass / 0 fail. The Mocha-style `test/dashboardapi.test.js`, `test/nodeClass.test.js`, `test/integration/`, and `test/edge/` files still use jest/Mocha globals — out of scope for P6.7; deferred to P10 test-suite refactor.

---

## 2026-05-10 — `dashboardAPI` skipped BaseNodeAdapter + BaseDomain

**Context:** P6.7. dashboardAPI is a passive HTTP-emitter utility node: no
`generalFunctions/src/configs/dashboardapi.json`, no periodic Port-0/1
telemetry stream, no parent registration, no measurements, no tick loop,
no status badge. `BaseDomain` constructor would throw on the missing
config file; `BaseNodeAdapter._scheduleRegistration` would emit a
spurious `child.register` for a node that has no parent; the
`outputUtils.formatMsg` pipeline assumes a measurement-shaped output
which dashboardAPI lacks.

**Default chosen:** `nodeClass` stays a plain class (does **not** extend
`BaseNodeAdapter`); `specificClass` (`DashboardApi`) stays a plain class
(does **not** extend `BaseDomain`). Only the shared `commandRegistry`
is adopted (canonical topic `child.register` with `registerChild` alias
+ deprecation warning). One handler module in `src/commands/`. nodeClass
shrunk from 134 → 73 lines.

**Decision needed by:** Phase 7 / Phase 8 — revisit if `BaseNodeAdapter`
grows a passive/HTTP-only mode (skip-registration + skip-output-stream
flags) or if a `dashboardapi.json` config gets added to generalFunctions.
Either makes adoption straightforward; until then the bespoke shape is
correct.

---

## 2026-05-10 — pumpingStation: plain dicts vs `declareChildGetter` — RESOLVED 2026-05-11

**Resolution (2026-05-11, B2.1):** Migrated. `this.machines / machineGroups
/ stations` are now BaseDomain `declareChildGetter` accessors over the
`childRegistrationUtils` registry; the `predictedFlowChildren` Map and
the dict-mutation lines in the router `onRegister` callbacks are gone.
The `context()` override installs **live getters** for the same three
names on the returned ctx so SafetyController (which captures ctx once
at construct-time) keeps reading the live registry across later
registrations. specificClass.js 316 → 314 lines.

Affected test files rewritten to inject mock children through the real
handshake instead of dict-assignment:

- `test/basic/specificClass.test.js` — added a `registerMockGroup(ps, id)`
  helper that builds a mock with `config.functionality.softwareType =
  'machinegroup'`, a stub `measurements.emitter.on`, and instrumented
  `handleInput` / `turnOffAllMachines`. All 9 `ps.machineGroups['mgc1']
  = {...}` blocks now call the helper; the 4 sub-tests that previously
  asserted on a captured `turnOffCalls` / `demands` array assert on the
  helper-returned `mock._calls` instead.
- `test/integration/shifted-ramp-end-to-end.test.js` — `buildHarness()`
  now calls a local `registerMockGroup(ps, 'mgc1', demands)` helper that
  pushes into the existing `demands` array via the registered mock's
  `handleInput`. No assertion shape changed.

128/130 pumpingStation tests pass after the migration (the 2 remaining
failures — `canonical topics dispatch to their handlers` and `set.inflow
accepts number payload …` in `test/basic/commands.basic.test.js` — are
pre-existing and unrelated to child storage).

### Original entry below
## 2026-05-10 — pumpingStation: plain dicts vs `declareChildGetter` (history)

**Context:** P2.7+P2.8+P2.9. The 2026-05-10 "Two child-storage shapes"
decision says use `declareChildGetter` (registry-as-truth), but the
existing pumpingStation test suite mutates `ps.machineGroups['mgc1'] = {...}`
directly to inject mock children before driving `_controlLevelBased`.
A getter-backed `machineGroups` returns a fresh object per call, so the
mutation is on a throwaway and the orchestrator never sees the mock.

**Default chosen:** Keep `machines / stations / machineGroups` as plain
id-keyed dicts on `this`. ChildRouter `onRegister` handlers populate them
on real registration; tests can still assign directly. Registry remains
the upstream source of truth (handshake still flows through it), but the
flat dicts are also writable. Revisit if other domains can adopt
`declareChildGetter` cleanly without test rewrites.

**Decision needed by:** Phase 10 (test-suite refactor).

---

## 2026-05-10 — `reactor` test runtime is mathjs-bound (pre-existing)

**Context:** P1.12 sanity gate. Every reactor test file takes ~13 s because `require('mathjs')` alone is ~12.5 s on this machine (mathjs is huge and loads its full operator set eagerly). With basic tests parallelised by `node --test`, each subprocess pays the cost. A 90 s outer timeout doesn't accommodate the parallel load.

**Action:** Pre-existing — not caused by Phase 1. Two options to track for Phase 5/6 cleanup:
1. Switch to a tree-shaken mathjs subset (only ops actually used).
2. Cache the mathjs instance at module top and pass into Reactor classes.

Tracked; not blocking the refactor.

---

## 2026-05-10 — measurement `isStable` tautology (pre-existing bug) — RESOLVED

**Resolution (2026-05-11):** Replaced the tautological `stdDev < stdDev*2`
check with a config-driven absolute threshold. New schema field
`calibration.stabilityThreshold` (number, ≥ 0, default `0.01` in
scaling-units) added to `generalFunctions/src/configs/measurement.json` so
all callers see it. `Calibrator.isStable()` now returns `true` when
`stdDev === 0` or `stdDev <= threshold`, falling back to the default when
the config slot is missing or non-numeric. The two BUG-PRESERVED calibrator
tests were rewritten — high-variance buffers now correctly report unstable
under the default and only flip to stable when an explicit relaxed
threshold is supplied. Added edge tests for the relaxed-threshold path,
constant-buffer-with-zero-threshold path, just-above-threshold path, and
missing-config fallback. `nodeClass.buildDomainConfig` and
`measurement.html` (defaults + form field + oneditsave) propagate the UI
value through to the domain. 100/100 measurement tests pass; 70/70
generalFunctions basic tests pass.

### Original entry below
## 2026-05-10 — measurement `isStable` tautology (pre-existing bug) (history)

**Context:** P3.4. The existing `isStable` in `measurement/src/specificClass.js` does:

```js
stableThreshold = stdDev * marginFactor;     // marginFactor = 2
return { isStable: (stdDev < stableThreshold || stdDev == 0), stdDev };
```

`stdDev < stdDev * 2` is always true for `stdDev > 0`, and the OR catches the
zero case. So `isStable` returns `true` for every non-empty buffer. That makes
`calibrate()` essentially un-gateable (it only aborts when there are < 2
samples) and `evaluateRepeatability()` happily reports a huge stdDev as
"repeatability".

**Action:** Preserved verbatim by the new `Calibrator` (additive). A
behavioural fix needs an external reference (config-driven absolute
threshold, or % of full scale). Two BUG-PRESERVED tests pin the current
shape so a follow-up behavioural PR is intentional.

**Decision needed by:** Phase 10 (test-suite refactor) — naturally
adjacent to the calibration test cleanup.

---

## 2026-05-10 — `commandRegistry` payload schema needs `'none'`/`'void'` type — RESOLVED

**Resolution (2026-05-11):** Added `'none'` to the payloadSchema.type
enum. Handler still fires; logs `warn` if `msg.payload` is non-empty
(catches accidental object payloads on trigger topics). Also added an
optional `description` field per descriptor for wikiGen consumption.
23/23 commandRegistry tests pass; CONTRACTS.md §4 updated.

### Original entry below
## 2026-05-10 — commandRegistry payload schema needs 'none'/'void' type (history)

**Context:** P3.7+P3.8. Trigger-only commands (`set.simulator`,
`set.outlier-detection`, `cmd.calibrate`) ignore their payload. The
current registry's `payloadSchema.type` enum is
`'string'|'number'|'object'|'boolean'|'any'`. Trigger commands fall
into `'any'`, which is too permissive (an object slipped past would
not be flagged).

**Default chosen:** Use `'any'` for now. Add `'none'`/`'void'` to the
registry schema enum during Phase 7 (topic-name standardisation).

**Decision needed by:** Phase 7.

---

## 2026-05-10 — measurement legacy `'mAbs'` emitter event — RESOLVED

**Resolution (2026-05-11):** Removed the on-emit subscription that
bridged the analog channel's `<type>.measured.<position>` event to
`source.emitter` as `'mAbs'`. No production consumer was reading it.
96/96 measurement tests pass.

### Original entry below
## 2026-05-10 — measurement legacy 'mAbs' emitter event (history)

**Context:** P3.7+P3.8 CONTRACT.md noted that the existing `Measurement`
class emits `'mAbs'` on `source.emitter` whenever the analog output
updates. This was a pre-MeasurementContainer broadcast. It's still
fired but no production consumer reads it (per the existing comment
"DEPRECATED: Use measurements container instead").

**Default chosen:** Keep firing it through Phase 3 (post-integration).
Remove in Phase 7 alongside the topic-rename cleanup, or in Phase 8.5
deprecated-path cleanup.

**Update (P3.2+P3.5+P3.6+P3.9, 2026-05-10):** Re-emitted from the analog
specificClass by subscribing to the MeasurementContainer's
`<type>.measured.<position>` event (position lowercased to match
container normalisation). Channel itself stays event-name-agnostic.

**Decision needed by:** Phase 7 / Phase 8.5.

---

## 2026-05-10 — measurement legacy property mirrors

**Context:** P3.2+P3.5+P3.6+P3.9. The analog pipeline now lives inside
`Channel`. The pre-refactor test suite pins many fields directly on the
Measurement instance: `outputAbs`, `outputPercent`, `storedValues`,
`totalMinValue`, `totalMaxValue`, `totalMinSmooth`, `totalMaxSmooth`,
`inputRange`, `processRange`. Some tests *write* `m.storedValues` /
`m.totalMinValue` directly before calling pipeline helpers.

**Default chosen:** Install getter/setter mirrors on the Measurement
instance (`_installChannelMirrors`) that forward read/write through
`this.analogChannel`. Storage stays single-sourced in Channel, the
legacy public surface stays writable, no test rewrites required.

**Decision needed by:** Phase 10 (test-suite refactor) — replace these
with direct `m.analogChannel.xxx` access in tests, then drop the mirrors.

---

## 2026-05-10 — measurement `handleScaling` mutates config.scaling

**Context:** P3.2+P3.5+P3.6+P3.9. Channel's `_applyScaling` resets its
*own* `scaling.inputMin/inputMax` to `[0,1]` when the input range
collapses (`inputMax <= inputMin`). The pre-refactor `handleScaling`
mutated `this.config.scaling.inputMin/inputMax` instead, and a basic
test pins that contract.

**Default chosen:** The Measurement-level `handleScaling` delegate
copies Channel's reset back to `config.scaling` after the call so the
visible behaviour is preserved. Long-term, the test should read the
new state from `m.analogChannel.scaling` and we drop the mirror write.

**Decision needed by:** Phase 10 (test-suite refactor).

---

## 2026-05-10 — measurement nodeClass routing tests pin private wiring

**Context:** P3.2+P3.5+P3.6+P3.9. The basic `nodeclass-routing` and
edge `invalid-payload` tests instantiated `NodeClass.prototype` and
called `_attachInputHandler()` / `_registerChild()` directly. The
BaseNodeAdapter superclass renamed these to `_attachInputHandler`
(unchanged) and `_scheduleRegistration` (was `_registerChild`), and
dispatch now goes through `this._commands` built in the constructor.

**Action:** Adjusted the two tests in-place to seed `inst._commands`
via `createRegistry(commands, …)` and to call `_scheduleRegistration`
instead of `_registerChild`. The on-the-wire payload topic also moved
from `'registerChild'` → `'child.register'` (BaseNodeAdapter
convention); the test assertion was updated accordingly.

**Decision needed by:** Phase 10 — these tests should be rewritten to
drive a full nodeClass through `new nodeClass(uiConfig, RED, node,
'measurement')` rather than poking at private members.

---

## 2026-05-10 — MGC `calcAbsoluteTotals` implicit pressure-key coupling

**Context:** P4.1/4.2 extracted `totals/totalsCalculator.js` preserving
original behaviour. `calcAbsoluteTotals` iterates
`machine.predictFlow.inputCurve` and re-uses the same pressure key to
index `machine.predictPower.inputCurve[pressure]`. If the two curves were
sampled at different pressures (legitimate when power was extrapolated
separately from flow), the lookup is `undefined` and the call throws.
**Question:** should the totals calculator defensively skip mismatched
pressure keys, or should the invariant "flow + power curves share pressure
keys" be enforced upstream in rotatingMachine's curveLoader/normalizer?
**Default chosen:** preserved the implicit coupling — no behavioural change.
**Decision needed by:** P5 (rotatingMachine refactor) — curveLoader/Normalizer
is the natural place to enforce or document the pairing.

---

## 2026-05-10 — MGC concern modules use legacy unitPolicy object shape — RESOLVED

**Resolution (2026-05-11):** UnitPolicy.declare() now exposes
canonical/output/curve as BOTH callable methods AND frozen property
bags. Both shapes work: `policy.canonical('flow')` and `policy.canonical.flow`.
Dropped the `_unitView`/`unitPolicyView` workaround in both MGC
(specificClass 336→318) and rotatingMachine (400→377). CONTRACTS.md §6
updated. All platform tests stay green.

### Original entry below
## 2026-05-10 — MGC concern modules use legacy unitPolicy object shape (history)

**Context:** The MGC concern modules (groupOps/groupOperatingPoint,
totals/totalsCalculator, combinatorics/pumpCombinations, control/strategies)
extracted in Wave 1 read units as `ctx.unitPolicy.canonical.flow` — the old
plain-object shape carried on the pre-refactor specificClass. `BaseDomain`
now wires `this.unitPolicy` to a `UnitPolicy` instance whose canonical/output
are methods (`canonical('flow')`).
**Question:** Should the concern modules be updated to call the methods, or
should we keep the object-shaped view long-term?
**Default chosen:** specificClass builds a frozen `this._unitView` ({
canonical: {flow,pressure,power,temperature}, output: {…} }) and passes it
to the modules. Two surface shapes live side-by-side in the same node.
**Decision needed by:** P5 (rotatingMachine) — the same concern-module
shape will likely repeat. Pick one and migrate before the second node lands
on the pattern.

---

## 2026-05-10 — rotatingMachine Machine constructor takes 3 positional args

**Context:** P5.9/5.10/5.12. The pre-refactor Machine class accepted
`(machineConfig, stateConfig, errorMetricsConfig)`. BaseDomain's
constructor only knows about the first slot. The whole test suite (~30
files) constructs Machines directly with two positional args, and
BaseNodeAdapter instantiates DomainClass with just `this.config`.

**Question:** Where do the extra positional configs travel? Schema
validation in `configUtils.initConfig` strips unknown top-level keys, so
embedding them in machineConfig doesn't work. Subclass-overriding
constructor before super() is blocked by ES6's pre-super `this` rule.

**Default chosen:** Static stash on the class itself
(`Machine._pendingExtras`) assigned just before `super()` (or by
nodeClass.buildDomainConfig before BaseNodeAdapter instantiates the
domain). `configure()` reads + clears it. Single-threaded JS makes the
hand-off race-free.

**Decision needed by:** P10 (test-suite refactor) — when tests get
rewritten to use the BaseNodeAdapter-built domain, drop the multi-arg
constructor and fold stateConfig/errorMetricsConfig into machineConfig
slices.

---

## 2026-05-10 — rotatingMachine private nodeClass tests (4 files adjusted) — RESOLVED 2026-05-11

**Resolution (2026-05-11, P10):** Rewritten to drive only the public
BaseNodeAdapter surface. Three test files were rewritten:

- `test/basic/nodeClass-config.basic.test.js` — `buildAdapter(ui)`
  constructs a full `new nodeClass(ui, RED, node, 'rotatingMachine')`
  and asserts against `inst.source.config.*` (the validated merged
  shape from `configManager.buildConfig`) and observable state on the
  domain. No `Object.create(NodeClass.prototype)` or direct
  `buildDomainConfig` calls — `Machine._pendingExtras` is no longer
  touched by tests.
- `test/edge/nodeClass-routing.edge.test.js` — dispatch is driven via
  `node._handlers.input(msg, send, done)` (the handler the base
  installs on `node.on('input', …)`). Assertions are against
  `node._sent`, instrumented `source.handleInput` call lists, and the
  `childRegistrationUtils.registerChild` side-effect. Status-badge
  pressure-warn case calls `inst.source.getStatusBadge()` directly,
  not `io.buildStatusBadge(source)`.
- `test/edge/error-paths.edge.test.js` — the error-on-status-badge
  test now builds the adapter, forces `state.getCurrentState` to
  throw, and asserts via `inst.source.getStatusBadge()`. The three
  pre-existing Machine-direct-construction tests were untouched
  (they never poked nodeClass privates).

Teardown of the always-on status-poll timer goes through the public
`node._handlers.close(() => {})` path (the BaseNodeAdapter close
handler) so the rewritten tests don't reach into `inst._statusUpdater`.

Verification: `npm test` reports 202 pass / 0 fail (up from 196 — net
+6 tests across the three rewritten files). No `inst._<private>`,
`_attachInputHandler`, `_commands = createRegistry`, `_pendingExtras`,
or `io.buildStatusBadge` references remain in the rewritten files.

### Original entry below
## 2026-05-10 — rotatingMachine private nodeClass tests (4 files adjusted) (history)

**Context:** P5.9/5.10/5.12. Four pre-refactor tests pinned private
nodeClass methods: `_loadConfig`, `_setupSpecificClass`,
`_updateNodeStatus`, and the inline `_attachInputHandler` switch. After
the BaseNodeAdapter migration those private methods are gone — config
build lives in `buildDomainConfig()`, dispatch in `commands/`, status
badge in `source.getStatusBadge()`.

**Default chosen:** Updated the four test files to drive the new
surface: `buildDomainConfig` returns the per-node slice (and stamps
`Machine._pendingExtras`); routing tests seed `inst._commands` via
`createRegistry(commands, …)` and assert through that path; status-badge
tests call `io.buildStatusBadge(source)` directly.

**Decision needed by:** P10 — these tests still poke private members
(`_commands`, `_attachInputHandler`). The right shape is constructing
a full `new nodeClass(uiConfig, RED, node, 'rotatingMachine')` and
asserting against the resulting `node._sent` / `node._statuses`.

---

## 2026-05-10 — monster schema strips command-line constraint keys — RESOLVED 2026-05-11

**Context:** P6.3. The monster JSON schema in `generalFunctions/src/configs/monster.json` defines `samplingtime`, `minVolume`, `maxWeight` and others under `constraints`, but NOT `nominalFlowMin`, `flowMax`, `maxRainRef`, `minSampleIntervalSec`. `configUtils.initConfig` strips these unknown keys with a `Unknown key … Removing it.` warning. The legacy code read them anyway — `Number.isFinite(undefined)` returns false, so guards naturally route into invalid-bounds territory and tests pass via the undefined cascade.

**Resolution (2026-05-11, B1.4):** Added the four missing fields (`nominalFlowMin`, `flowMax`, `maxRainRef`, `minSampleIntervalSec`) to the `constraints` section of `generalFunctions/src/configs/monster.json` with sensible defaults (0/0/10/60). The unknown-key warning disappears and user-supplied values now propagate through validation to the domain, restoring the documented sampling behaviour.

---

## 2026-05-10 — monster sampling-guards cooldown test fails on development (pre-existing) — RESOLVED 2026-05-11

**Context:** P6.3 baseline run. `test/edge/sampling-guards.edge.test.js` "cooldown guard blocks pulses when flow implies oversampling" already fails on `development` BEFORE the refactor (`assert.ok(monster.sumPuls > 0)` — sumPuls stays at 0 across 80 ticks). The legacy in-file equivalent in `test/monster.test.js` (Mocha-style wrapper, not picked up by `node:test`) appears to have passed in an earlier era.

**Resolution (2026-05-11, B1.4):** Root cause was the schema-stripping issue documented immediately above — `nominalFlowMin`/`flowMax`/`minSampleIntervalSec` were stripped by `configUtils.initConfig` before reaching the domain, so `validateFlowBounds` saw NaN/NaN and routed every `i_start` into the invalid-bounds early return, which prevented `_beginRun` from ever firing. With the four constraint keys now declared in `monster.json`, the test config propagates intact: `_beginRun` runs, the m3PerTick integrator accumulates ~0.056 m3/tick, `temp_pulse` crosses 1 at tick ~18, the first pulse fires, subsequent pulses are correctly blocked by the 60 s cooldown, and `sumPuls > 0` / `missedSamples > 0` / `bucketVol > 0` / `getSampleCooldownMs() > 0` all hold. Added a guard-site comment in `parameters/parameters.js#validateFlowBounds` pointing back at the schema contract. All 10/10 monster tests green.

---

## 2026-05-10 — MGC handleInput retained inline latest-wins (not DemandDispatcher) — RESOLVED

**Resolution (2026-05-11):** Extended `LatestWinsGate` with
`fireAndWait(value)` that returns a per-fire settlement promise. A
parked call superseded by a later fire resolves with the frozen
sentinel `LatestWinsGate.SUPERSEDED = { superseded: true }` (not a
reject) so callers branch on a value without try/catch. Dispatch
errors still resolve the promise (with `undefined`) and surface via
`gate.lastError`.

MGC's `handleInput` now delegates to `DemandDispatcher.fireAndWait`;
the inline `_dispatchInFlight` + `_delayedCall` block is gone.
`turnOffAllMachines` calls `cancelPending()` on the dispatcher
instead of zeroing `_delayedCall`. `LatestWinsGate.js` 75 → 116 lines
(under the 150 cap). MGC `specificClass.js` net −14 lines.

The `turnoff-deadlock` test that pinned `_delayedCall` was rewritten
to assert against the parked `fireAndWait` resolving as superseded.
Other awaiting tests (`ncog-distribution`, `idle-startup-deadlock`,
`demand-cycle-walkthrough`) needed no change since `fireAndWait`
preserves the "await waits for the call's dispatch" shape for
non-superseded calls. All 77/77 MGC tests pass; 12/12 LatestWinsGate
basic tests pass.

### Original entry below
## 2026-05-10 — MGC handleInput retained inline latest-wins (not DemandDispatcher) (history)

**Context:** Wave 1 added `src/dispatch/demandDispatcher.js` wrapping
`LatestWinsGate`. Tests (`turnoff-deadlock`, `idle-startup-deadlock`,
`ncog-distribution`) call `await mgc.handleInput(...)` and rely on the
awaited promise resolving after the dispatch completes; they also pin the
exact `_delayedCall` field. `LatestWinsGate.fire(value)` returns void.
**Question:** Should `handleInput` switch to the gate (changing the test
contract), or stay inline (keeping the awaitable shape)?
**Default chosen:** kept the inline `_dispatchInFlight + _delayedCall`
gate verbatim. `DemandDispatcher` remains exported but unused by the
orchestrator for now — its basic test still passes since it tests the
wrapper in isolation.
**Decision needed by:** P7 (topic-name standardisation) or P10 (test-suite
refactor) — adopting the gate requires either rewriting tests to drain
the gate or changing the gate to return a settle promise.

---

## 2026-05-10 — valveGroupControl registerChild overload (skipped ChildRouter)

**Context:** P6.2. `ValveGroupControl.registerChild(child, posOrType)` is
called from two distinct paths: (a) `childRegistrationUtils.registerChild`
delegates with the canonical softwareType as 2nd arg, and (b) tests + a
few in-process callers invoke it directly passing **either** a position
(`'atEquipment'`) **or** a softwareType (`'machine'`). The legacy code
disambiguated via a `KNOWN_POSITIONS` set lookup and returned a boolean
indicating registration success (used by `flow-distribution` regression
test to assert a non-valve payload yields `false`).

**Default chosen:** kept the legacy resolver in the domain — override
`this.registerChild` inside `configure()` so the boolean return + dual
semantics survive. `ChildRouter` is **not** used for VGC (no `onRegister`
/ `onMeasurement` handlers declared). Source-side event wiring still
lives in `src/sources/fluidContract.js` (raw emitter `.on` on each
`SOURCE_FLOW_EVENTS` name) because the source family includes mixed-case
event names (`flow.predicted.atEquipment` and lowercase variants both fire).

**RESOLVED 2026-05-11 (B2.2):** Migrated to `ChildRouter.onRegister`.
`configure()` now declares `router.onRegister('valve', …)` plus one
`onRegister(…)` per canonical source softwareType (`machine`,
`machinegroup`, `pumpingstation`, `valvegroupcontrol`); the custom
overloaded `registerChild` and `_resolveRegistrationContext` resolver
were removed and BaseDomain's default `registerChild` (which delegates
straight to `router.dispatchRegister`) is back in charge. Position now
comes from `child.positionVsParent` (set by `childRegistrationUtils`) or
`child.config.functionality.positionVsParent`, falling back to
`atEquipment`. The boolean-return regression test was rewritten to assert
via the side-effect (`Object.keys(group.valves).length === 0`) for the
non-valve-like payload, and a new test pins router dispatch through
`childRegistrationUtils.registerChild(valve, 'upstream')` honouring the
config's `positionVsParent`. Source-side measurement-event wiring still
lives in `sources/fluidContract.bindSource` — the mixed-case
`flow.{measured,predicted}.atEquipment` listeners remain raw `.on`
attachments until topic casing standardises platform-wide. specificClass
shrank 270→255 lines; tests 9→10, all green.

---

## 2026-05-10 — valveGroupControl `set.position` placeholder

**Context:** P6.2 command registry. Task spec required canonical name
`setpoint → set.position`, but VGC's pre-refactor input switch did not
implement a `setpoint` topic — valve position is driven by `data.totalFlow`
re-distribution, not direct per-valve setpoints. Registering `set.position`
with an empty handler keeps the canonical name reserved without breaking
the contract surface.

**Default chosen:** registered `set.position` with a no-op handler that
debug-logs the payload. `setpoint` listed as alias so a legacy emitter
gets the same no-op path.

**Decision needed by:** P7 — decide whether VGC actually needs a
per-valve setpoint topic (probably yes when virtualControl mode lands).
At that point promote the handler from no-op to real dispatch.

---

## 2026-05-10 — reactor private nodeClass tests (8 files adjusted) — RESOLVED 2026-05-11

**Resolution (2026-05-11, P10):** Rewrote all 8 reactor test files to drive
only the public BaseNodeAdapter surface — `new nodeClass(uiConfig, RED, node,
'reactor')`, then fire msgs through `node.handlers.input(...)` and observe
via `node.sends` / `node.statuses` / `inst.source.engine.*` /
`inst.source.tick(dt)`. The pre-refactor private methods (`_loadConfig`,
`_setupClass`, `_attachInputHandler`, `_updateNodeStatus`, `_registerChild`,
`_tick`, `_startTickLoop`, `_attachCloseHandler`) are no longer referenced.
`buildDomainConfig` is invoked on the real constructed instance (it's the
documented override hook in CONTRACTS.md §2). `_emitOutputs` is called on
the real instance for the tick-loop assertions (it's the reactor-specific
override for Port-0 emission, also documented). The "scheduled registration"
test now waits ~130 ms for the BaseNodeAdapter setTimeout to fire and
inspects the resulting Port-2 send. 46/46 reactor tests pass (was 39 pre-
rewrite — net +7 tests added covering canonical topic acceptance, alias
acceptance, child-with-no-source guard, empty-string reactor_type, missing-
topic guard, and the new Reactor.tick(dt) wrapper introduced in B2.3).

### Original entry below
## 2026-05-10 — reactor private nodeClass tests (8 files adjusted) (history)

**Context:** P6.5. Eight pre-refactor reactor tests pinned private
nodeClass methods (`_loadConfig`, `_setupClass`, `_registerChild`, inline
`_attachInputHandler` switch, `_tick`, `_startTickLoop`, `_attachCloseHandler`).
After the BaseNodeAdapter migration those private methods are gone — config
build lives in `buildDomainConfig()`, dispatch in `commands/`, registration in
`_scheduleRegistration` (renamed), and the periodic emit lives in
`_emitOutputs` (overridden so the Fluent / GridProfile Port-0 contract is
preserved — delta-compressed payloads can't carry the C-vector).

**Default chosen:** Adjusted in place: `test/basic/constructor.basic.test.js`,
`test/basic/input-routing.basic.test.js`, `test/basic/register-child.basic.test.js`,
`test/basic/speedup-factor.basic.test.js`, `test/edge/invalid-topic.edge.test.js`,
`test/edge/missing-child.edge.test.js`, `test/edge/invalid-reactor-type.edge.test.js`,
`test/integration/tick-loop.integration.test.js`. Routing tests seed
`inst._commands` via `createRegistry(commands, …)`; topic moved from
`'registerChild'` → `'child.register'`. The "unknown reactor_type throws"
edge case became "falls back to CSTR" — the legacy bottom-of-switch already
fell back to CSTR; only the surface changed (warning channel now via
domain logger, not `node.warn`).

**Decision needed by:** Phase 10 — same shape as the rotatingMachine /
measurement adjustments. The right fix is to drive a full
`new nodeClass(...)` and assert against `node._sent` / `node._statuses`
instead of poking private members.

---

## 2026-05-10 — reactor schema enum lowercases `reactor_type`

**Context:** P6.5. The reactor JSON schema defines `reactor.reactor_type`
as `type: 'enum'` with values `'CSTR'` / `'PFR'`. The shared enum validator
lowercases the user-supplied value before comparing, so an inbound `'PFR'`
ends up stored as `'pfr'` in the validated config. The pre-refactor
nodeClass switched on the raw uiConfig value and never saw the lowercased
form; after the BaseDomain migration the wrapper reads the validated
config and would always fall back to CSTR.

**Default chosen:** `Reactor._buildEngine` upper-cases the value before
switching. The schema is left intact so external Phase-7 enum-casing
work can decide whether to preserve original casing globally.

**Decision needed by:** Phase 7 (topic-name + schema standardisation) —
once enums standardise on a canonical casing, drop the `.toUpperCase()`
guard here.

---

## 2026-05-21 — Palette swatches switched to domain-hue (resolved)

**Context:** Node-RED sidebar showed every EVOLV node in a shade of blue because palette colours were set from the S88 level (Area / ProcessCell / Unit / Equipment / ControlModule). Operators reported difficulty picking the right node by eye.

**Decision:** Split the colour systems. The **palette swatch** in each `<node>.html` (`RED.nodes.registerType({ color })`) becomes domain-hue per node; family hue = function (rotating = orange, valves = teal, biology = green/olive, sampling = violet, sensor = amber, infrastructure = slate, aeration = sky blue). Within a family, darker = higher S88 (e.g. RM → MGC → pumpingStation darkens the orange). **Editor-group rectangles** in `flow.json` (`style.fill`) continue to follow S88 level — the hierarchy story stays visible in flow diagrams. Two systems, two purposes.

**Final palette table:** see `.claude/rules/node-red-flow-layout.md` §10.0.

**Why split rather than rework S88:** S88 hierarchy is genuinely useful for flow-diagram readability (it's the whole point of group boxes). Throwing it out to fix palette identifiability would have cost the hierarchy signal. Two systems = both problems solved.

**Files touched (palette):** the 12 `nodes/<n>/<n>.html` files, one line each.

**Files touched (docs):** `CLAUDE.md` (L52 split into palette + group lines); `.claude/rules/node-red-flow-layout.md` (new §10.0); `.claude/refactor/MODULE_SPLIT.md` (per-node headers annotated with both hexes); `.claude/refactor/WIKI_HOME_TEMPLATE.md` + `WIKI_TEMPLATE.md` (clarifying sentence — Mermaid classDefs are hierarchy, not palette); this entry.

**Unchanged on purpose:** 32 submodule wiki/CLAUDE.md files that name S88 hexes — they describe hierarchy diagrams or editor-group boxes, both of which still use S88. Spot-checked `rotatingMachine` + `reactor` wikis to confirm.

**Open follow-ups:**
- If `coresync` ends up classified as a process-data node rather than infrastructure, repick a non-slate hue.
- Consider a `tools/palette-lint/` check that diffs declared palette hexes vs. this table to catch future drift (low priority).