docs(wiki): full 5-page wiki matching the rotatingMachine reference format

Replaces the prior stub/partial wiki with a Home + Reference-{Architecture,
Contracts,Examples,Limitations} + _Sidebar structure. Topic-contract and
data-model sections wrapped in AUTOGEN markers for the future wiki-gen tool.
Source-vs-spec contradictions surfaced and flagged inline (not silently
fixed). Pending-review notes mark sections that need a full node review.

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

wiki/Home.md

@@ -1,13 +1,28 @@
 # measurement
 
-> **Reflects code as of `125f964` · regenerated `2026-05-11` via `npm run wiki:all`**
+![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue) ![s88](https://img.shields.io/badge/S88-Control_Module-a9daee) ![status](https://img.shields.io/badge/status-under--review-orange)
-> If this banner is stale, the page may be out of date. Treat as informative, not authoritative.
 
-## 1. What this node is
+A `measurement` turns a raw sensor signal into a validated, scaled, smoothed reading and re-emits it for any upstream parent. Two modes: **analog** (one channel built from the flat config — classic 4–20 mA / PLC style) and **digital** (one `Channel` per `config.channels[]` entry — MQTT / IoT JSON style). It is a leaf in the S88 hierarchy — no children of its own — and registers itself as a child of any parent that accepts measurements (`rotatingMachine`, `machineGroupControl`, `pumpingStation`, `reactor`, `monster`, …).
 
-**measurement** is an S88 Control Module that turns a raw sensor signal into a validated, scaled, smoothed reading and re-emits it for any parent. Two modes: **analog** (one channel built from the flat config) and **digital** (one Channel per `config.channels[]` entry). It is a leaf in the hierarchy — no children of its own.
+> [!NOTE]
+> Pending full node review (2026-05). Content reflects `CONTRACT.md`, `src/commands/index.js`, and current source only. Some sections are best-effort placeholders pending the next pass.
 
-## 2. Position in the platform
+---
+
+## At a glance
+
+| Thing | Value |
+|:---|:---|
+| What it represents | One sensor signal — pressure / flow / power / temperature / level / … |
+| S88 level | Control Module |
+| Use it when | You need to scale, offset, smooth, outlier-filter, or simulate a sensor reading before handing it to an equipment / unit / process-cell node |
+| Don't use it for | Sensor fusion, threshold-trip alarms, or as a control output — this node is read-only signal conditioning |
+| Children it accepts | None — leaf node |
+| Parents it talks to | Any node that subscribes to `<type>.measured.<position>` events (`rotatingMachine`, `MGC`, `pumpingStation`, `reactor`, `monster`, &hellip;) |
+
+---
+
+## How it fits
 
 ```mermaid
 flowchart LR
@@ -18,12 +33,12 @@ flowchart LR
     p3[pumpingStation<br/>Process Cell]:::pc
 
     raw -->|data.measurement| m
-    m -->|child.register| p1
+    m -->|child.register<br/>(Port 2 at startup)| p1
     m -->|child.register| p2
     m -->|child.register| p3
-    m -.<type>.measured.<position>.-> p1
+    m -.->|"&lt;type&gt;.measured.&lt;position&gt;"| p1
-    m -.<type>.measured.<position>.-> p2
+    m -.->|"&lt;type&gt;.measured.&lt;position&gt;"| p2
-    m -.<type>.measured.<position>.-> p3
+    m -.->|"&lt;type&gt;.measured.&lt;position&gt;"| p3
     classDef pc fill:#0c99d9,color:#fff
     classDef unit fill:#50a8d9,color:#000
     classDef equip fill:#86bbdd,color:#000
@@ -32,227 +47,117 @@ flowchart LR
 
 S88 colours: Control Module `#a9daee`, Equipment `#86bbdd`, Unit `#50a8d9`, Process Cell `#0c99d9`. Source of truth: `.claude/rules/node-red-flow-layout.md`.
 
-## 3. Capability matrix
+---
 
-| Capability | Status | Notes |
+## Try it &mdash; 1-minute demo
-|---|---|---|
-| Analog mode — single channel from flat config | ✅ | Default. `data.measurement` payload is numeric. |
-| Digital mode — many channels from `config.channels[]` | ✅ | Payload is an object keyed by `channel.key`. |
-| Outlier detection | ✅ | Median ± window check. Toggleable via `set.outlier-detection`. |
-| Scaling (input range → process range + offset) | ✅ | `config.scaling.{inputMin,inputMax,absMin,absMax,offset}`. |
-| Smoothing (moving window) | ✅ | `config.smoothing.{smoothWindow,smoothMethod}`. |
-| Min/max tracking | ✅ | `totalMinValue`, `totalMaxValue`, smoothed variants. |
-| Calibration (capture current as zero/reference) | ✅ | `cmd.calibrate`. Mutates `config.scaling.offset`. |
-| Built-in simulator | ✅ | Sinusoidal/noise driver — `set.simulator` toggles. |
-| Repeatability / stability metrics | ✅ | `evaluateRepeatability()`, `isStable()`. |
-| Accepts children of its own | ❌ | Leaf node. |
 
-## 4. Code map
+Import the basic example flow, deploy, and drive a single sensor through scaling + smoothing.
 
-```mermaid
+```bash
-flowchart TB
+curl -X POST -H 'Content-Type: application/json' \
-    subgraph nodeRED["nodeClass.js — adapter (BaseNodeAdapter)"]
+  --data @nodes/measurement/examples/basic.flow.json \
-        nc["buildDomainConfig()<br/>static DomainClass, commands<br/>static tickInterval = 1000ms"]
+  http://localhost:1880/flows
-    end
-    subgraph domain["specificClass.js — orchestrator (BaseDomain)"]
-        sc["Measurement.configure()<br/>mode = analog | digital<br/>builds Channel(s)"]
-    end
-    subgraph concerns["src/ concern modules"]
-        channel["channel.js<br/>outlier → offset → scaling →<br/>smoothing → minMax pipeline"]
-        simulation["simulation/<br/>built-in Simulator"]
-        calibration["calibration/<br/>Calibrator + stability"]
-        commands["commands/<br/>topic registry + handlers"]
-    end
-    nc --> sc
-    sc --> channel
-    sc --> simulation
-    sc --> calibration
-    nc --> commands
 ```
 
-| Module | Owns | Read first if you're changing… |
+What to do after deploy:
-|---|---|---|
-| `channel.js` | Per-channel pipeline (outlier → offset → scaling → smoothing → emit) | Per-tick reading flow, unit semantics, emitted event name. |
-| `simulation/` | Built-in signal generator for demos and offline tests | Sim behaviour, period / amplitude. |
-| `calibration/` | Stability checks, repeatability, offset capture | `cmd.calibrate` behaviour, stable-window heuristic. |
-| `commands/` | Input-topic registry and handlers | New input topics, payload validation. |
 
-The analog/digital branch is decided once in `configure()` based on `config.mode.current`. There is no FSM — `tick()` only pumps the simulator when enabled.
+1. Click the `measurement 42` inject &mdash; sends `topic: 'measurement'` (legacy alias of `data.measurement`) with payload `42`.
+2. Watch Port 0 in the debug pane: `mAbs` updates immediately. After a few injects `totalMinValue` / `totalMaxValue` start tracking the rolling min/max.
+3. Toggle the simulator: send `topic: 'set.simulator'`. `tick()` (1000 ms) starts driving `inputValue` through `Simulator.step()`.
+4. Trigger calibration: send `topic: 'cmd.calibrate'`. If the rolling window is stable (`stdDev <= config.calibration.stabilityThreshold`) the calibrator captures the current output as the new `config.scaling.offset`.
 
-```mermaid
+> [!IMPORTANT]
-flowchart LR
+> **GIF needed.** Demo recording of steps 1&ndash;4 with the live status badge. Save as `wiki/_partial-gifs/measurement/01-basic-demo.gif`, target &le; 1&nbsp;MB after `gifsicle -O3 --lossy=80`.
-    cfg[config.mode.current]
-    cfg -->|"=== 'digital'"| dig[Build N Channels<br/>from config.channels[]]
-    cfg -->|"=== 'analog' (default)"| ana[Build 1 Channel<br/>from flat config]
-    dig --> emit_d[handleDigitalPayload<br/>fan-out per channel]
-    ana --> emit_a[inputValue setter<br/>single channel update]
-```
 
-## 5. Topic contract
+---
 
-> **Auto-generated** from `src/commands/index.js`. Do NOT hand-edit between the markers. Re-run `npm run wiki:contract`.
+## The four things you'll send
 
-<!-- BEGIN AUTOGEN: topic-contract -->
+| Topic | Aliases | Payload | What it does |
+|:---|:---|:---|:---|
+| `data.measurement` | `measurement` | analog: `number` (or numeric string); digital: `{<channelKey>: number, &hellip;}` | Push a raw reading into the pipeline. Wrong shape for the configured mode logs a hint suggesting the other mode. |
+| `set.simulator` | `simulator` | (ignored) | Toggle the built-in `Simulator` random-walk on / off. Mutates `config.simulation.enabled`. |
+| `set.outlier-detection` | `outlierDetection` | (ignored) | Toggle outlier detection on the analog pipeline. Mutates `config.outlierDetection.enabled`. |
+| `cmd.calibrate` | `calibrate` | (ignored) | Run a one-shot calibration. Captures the current output as `config.scaling.offset`; aborts with a warn if the buffer is not stable. |
 
-| Canonical topic | Aliases | Payload | Unit | Effect |
+Aliases log a one-time deprecation warning the first time they fire.
-|---|---|---|---|---|
-| `set.simulator` | `simulator` | `any` | — | Toggle the built-in simulator on / off. |
-| `set.outlier-detection` | `outlierDetection` | `any` | — | Toggle / configure outlier detection on the measurement pipeline. |
-| `cmd.calibrate` | `calibrate` | `any` | — | Trigger a one-shot calibration of the measurement. |
-| `data.measurement` | `measurement` | `any` | — | Push a raw measurement (analog: number; digital: per-channel object). |
 
-<!-- END AUTOGEN: topic-contract -->
+---
 
-## 6. Child registration
+## What you'll see come out
 
-`measurement` does **not accept children**. It only **registers itself** as a child on its upstream parent.
+Sample Port 0 message (analog mode, after a few injects):
 
-```mermaid
+```json
-flowchart LR
-    m[measurement]:::ctrl -->|"child.register<br/>(Port 2 at startup)"| parent[rotatingMachine /<br/>MGC / pumpingStation /<br/>reactor / monster]
-    m -.->|"&lt;type&gt;.measured.&lt;position&gt;<br/>(measurements.emitter)"| parent
-    classDef ctrl fill:#a9daee,color:#000
-```
-
-| What | softwareType payload | Side-effect on parent |
-|---|---|---|
-| Registration | `measurement` | Parent attaches listener for `<asset.type>.measured.<positionVsParent>`. |
-| Subsequent updates | event on `child.measurements.emitter` | Parent mirrors value into its own `MeasurementContainer`. |
-
-Position labels are normalised to **lowercase** in the event name (`upstream`, `downstream`, `atequipment`).
-
-## 7. Lifecycle — what one event (or tick) does
-
-```mermaid
-sequenceDiagram
-    participant ext as external sender
-    participant m as measurement
-    participant ch as Channel pipeline
-    participant emitter as measurements.emitter
-    participant parent as parent (e.g. rotatingMachine)
-
-    ext->>m: data.measurement (12.4)
-    m->>m: command dispatch (analog branch)
-    m->>ch: update(12.4)
-    ch->>ch: outlier check → offset → scale → smooth → minMax
-    ch->>emitter: <type>.measured.<position> {value, ts, unit}
-    emitter-->>parent: child event (subscribed at register-time)
-    m->>m: notifyOutputChanged()
-    m-->>ext: Port 0 + Port 1 (delta-compressed)
-    Note over m: every 1000 ms: if simulation.enabled,<br/>simulator.step() → inputValue
-```
-
-## 8. Data model — `getOutput()`
-
-Analog mode emits the legacy scalar shape. Digital mode emits a nested `{channels:{...}}` keyed by `channel.key`.
-
-<!-- BEGIN AUTOGEN: data-model -->
-
-| Key | Type | Unit | Sample |
-|---|---|---|---|
-| `mAbs` | number | — | `0` |
-| `mPercent` | number | — | `0` |
-| `totalMaxSmooth` | number | — | `0` |
-| `totalMaxValue` | number | — | `0` |
-| `totalMinSmooth` | number | — | `0` |
-| `totalMinValue` | number | — | `0` |
-
-<!-- END AUTOGEN: data-model -->
-
-**Concrete digital sample** (when `mode='digital'`):
-
-~~~json
 {
+  "topic": "measurement#sensor_a",
+  "payload": {
+    "mAbs": 0.42,
+    "mPercent": 42,
+    "totalMinValue": 0.12,
+    "totalMaxValue": 0.78,
+    "totalMinSmooth": 0.20,
+    "totalMaxSmooth": 0.65
+  }
+}
+```
+
+Sample Port 0 message (digital mode):
+
+```json
+{
+  "topic": "measurement#multi",
+  "payload": {
     "channels": {
       "level-a": { "mAbs": 1.84, "mPercent": 73.6, "totalMinValue": 0.1, "totalMaxValue": 2.4 },
       "temp-a":  { "mAbs": 18.2, "mPercent": 36.4, "totalMinValue": 14.0, "totalMaxValue": 22.1 }
     }
+  }
 }
-~~~
-
-In addition, the legacy `source.emitter` fires `'mAbs'` (analog only) — kept for the editor status badge during the refactor window.
-
-## 9. Configuration — editor form ↔ config keys
-
-```mermaid
-flowchart TB
-    subgraph editor["Node-RED editor form"]
-        f1[Mode: analog / digital]
-        f2[Asset type + unit]
-        f3[Position vs parent]
-        f4[Scaling: inputMin/Max, absMin/Max, offset]
-        f5[Smoothing: window + method]
-        f6[Outlier detection: enabled + window]
-        f7[Simulation: enabled + amplitude/period]
-        f8[Digital channels list]
-    end
-    subgraph cfg["Domain config slice"]
-        c1[mode.current]
-        c2[asset.type / asset.unit]
-        c3[functionality.positionVsParent]
-        c4[scaling.*]
-        c5[smoothing.*]
-        c6[outlierDetection.*]
-        c7[simulation.*]
-        c8[channels []]
-    end
-    f1 --> c1
-    f2 --> c2
-    f3 --> c3
-    f4 --> c4
-    f5 --> c5
-    f6 --> c6
-    f7 --> c7
-    f8 --> c8
 ```
 
-| Form field | Config key | Default | Range | Where used |
+| Field | Meaning |
-|---|---|---|---|---|
+|:---|:---|
-| Mode | `mode.current` | `analog` | enum (`analog`, `digital`) | `Measurement.configure` |
+| `mAbs` | Latest output value in scaling-units (after offset + scaling + smoothing). |
-| Asset type | `asset.type` | `pressure` | enum | event name + unit policy |
+| `mPercent` | Same value mapped to `interpolation.percentMin..percentMax` (default 0..100). |
-| Position vs parent | `functionality.positionVsParent` | `atEquipment` | enum | event name suffix |
+| `totalMinValue` / `totalMaxValue` | Rolling min/max of **raw** (pre-scaling) values. `0` until first sample. |
-| Scaling enabled | `scaling.enabled` | `false` | bool | `Channel._applyScaling` |
+| `totalMinSmooth` / `totalMaxSmooth` | Rolling min/max of the smoothed output. |
-| Input min/max | `scaling.inputMin/Max` | `0` / `1` | numeric | linear map foot/top |
-| Output min/max | `scaling.absMin/absMax` | `50` / `100` | numeric | linear map foot/top |
-| Offset | `scaling.offset` | `0` | numeric | calibration target |
-| Smoothing window | `smoothing.smoothWindow` | `10` | ≥ 1 (samples) | moving window |
-| Outlier detection | `outlierDetection.enabled` | varies | bool | `Channel._isOutlier` |
-| Simulation enabled | `simulation.enabled` | `false` | bool | `tick()` step |
 
-## 10. Examples
+Additionally the `source.measurements.emitter` fires `<type>.measured.<position>` on every accepted update &mdash; parents subscribe to that event through the `child.measurements.emitter` handshake established at register time. See [Architecture &mdash; Lifecycle](Reference-Architecture#lifecycle) for the full path.
 
-| Tier | File | What it shows | Status |
+---
-|---|---|---|---|
-| Basic | `examples/basic.flow.json` | Inject + dashboard, no parent | ⚠️ legacy shape, pre-refactor |
-| Integration | `examples/integration.flow.json` | measurement registered as child of a parent | ⚠️ legacy shape, pre-refactor |
-| Edge | `examples/edge.flow.json` | Outlier / scaling / simulator edge cases | ⚠️ legacy shape, pre-refactor |
 
-Tier 1/2/3 visual-first example flows are still TODO (see `MEMORY.md` "TODO: Example Flows"). Screenshots will land under `wiki/_partial-screenshots/measurement/` when the new flows ship.
+## How the pipeline behaves
 
-## 11. Debug recipes
+```mermaid
+flowchart LR
+    in[input value] --> out{outlierDetection.enabled?}
+    out -- yes --> oc[_isOutlier]
+    oc -- outlier --> drop[drop + warn]
+    oc -- ok --> off[apply scaling.offset]
+    out -- no --> off
+    off --> mm[update raw totalMin/Max]
+    mm --> sc{scaling.enabled?}
+    sc -- yes --> lin[linear map<br/>input range → abs range]
+    sc -- no --> sm[pass-through]
+    lin --> sm
+    sm --> sw[push to storedValues<br/>length capped by smoothWindow]
+    sw --> sf[smoothMethod:<br/>mean / median / kalman / &hellip;]
+    sf --> sm2[update smooth totalMin/Max]
+    sm2 --> wo[round + write outputAbs<br/>+ emit measurement event]
+```
 
-| Symptom | First thing to check | Where to look |
+The same pipeline runs per `Channel` instance &mdash; once in analog mode, N times in digital mode.
-|---|---|---|
-| Parent never receives `<type>.measured.<position>` | `assetType` must match parent's filter exactly (e.g. `flow` — not `flow-electromagnetic`). | `config.asset.type` + `MEMORY.md` integration gotcha. |
-| Position labels look uppercase to parent | Event name lowercases — but `functionality.positionVsParent` is sent as-is on `child.register`. | `_buildAnalogChannel` event-name composition. |
-| Outliers seem to pass through | `outlierDetection.enabled` may be off (default varies by config). Toggle with `set.outlier-detection`. | `Channel._isOutlier`. |
-| `cmd.calibrate` does nothing | Calibrator requires ≥ 2 stable samples — check `isStable()` first. | `calibration/calibrator.js`. |
-| Digital payload silently dropped | Unknown channel keys land in the `unknown` log line only at debug level. | enable `logging.logLevel=debug` momentarily. |
-| Simulator still running after toggle off | `tick()` reads `config.simulation.enabled` each tick — confirm the toggle actually mutated the config. | `toggleSimulation`. |
 
-> Never ship `enableLog: 'debug'` in a demo — fills the container log within seconds and obscures real errors.
+---
 
-## 12. When you would NOT use this node
+## Need more?
 
-- Don't use measurement to **fuse** signals from multiple sensors — it's per-channel only. Aggregate at the parent.
+| Page | What you'll find |
-- Don't use measurement for **control output** — it's read-only signal conditioning. Use `rotatingMachine` / `valve` for actuation.
+|:---|:---|
-- Don't use measurement for **alarm logic** — there is no threshold-trip output. Build that on top of the emitted reading at the parent or in a dashboard rule.
+| [Reference &mdash; Contracts](Reference-Contracts) | Full topic contract, config schema, child-registration handshake |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map, lifecycle, analog vs digital branching, per-Channel pipeline |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped example flows + debug recipes |
+| [Reference &mdash; Limitations](Reference-Limitations) | When not to use, known limitations, open questions |
 
-## 13. Known limitations / current issues
+[EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home) &middot; [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) &middot; [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)
-
-| # | Issue | Tracked in |
-|---|---|---|
-| 1 | Legacy `source.emitter` 'mAbs' event still fired alongside `measurements.emitter` — slated for removal in Phase 7. | `OPEN_QUESTIONS.md` (2026-05-10) |
-| 2 | Digital mode's per-channel scaling/smoothing falls back to the analog block's defaults when not specified per channel. | `_buildDigitalChannels`. |
-| 3 | Tier 1/2/3 visual-first example flows not yet written; current `examples/` only contains pre-refactor flows. | P9 / P2.14 follow-up. |
-| 4 | No automatic recalibration — `cmd.calibrate` is operator-triggered. | `calibration/calibrator.js`. |

wiki/Reference-Architecture.md

@@ -0,0 +1,244 @@
+# Reference — Architecture
+
+![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue)
+
+> [!NOTE]
+> Code structure for `measurement`: the three-tier sandwich, the `src/` layout, the per-`Channel` pipeline, the analog vs digital branching, the lifecycle, and the output-port pipeline. For an intuitive overview, return to [Home](Home).
+>
+> Pending full node review (2026-05). Content reflects current source and `CONTRACT.md`; sections noted as TODO require a second pass.
+
+---
+
+## Three-tier code layout
+
+```
+nodes/measurement/
+|
++-- measurement.js                 entry: RED.nodes.registerType('measurement', NodeClass)
+|                                  + admin endpoints (menu.js, configData.js, asset-reg)
+|
++-- src/
+|     nodeClass.js                 extends BaseNodeAdapter (Node-RED bridge)
+|     specificClass.js             extends BaseDomain (orchestrates Channels + helpers)
+|     channel.js                   one scalar pipeline (outlier → offset → scale → smooth → emit)
+|     |
+|     +-- commands/
+|     |     index.js               topic registry (set.simulator / set.outlier-detection /
+|     |                            cmd.calibrate / data.measurement)
+|     |     handlers.js            pure handler functions (mode-dispatching for data.measurement)
+|     |
+|     +-- simulation/
+|     |     simulator.js           Simulator — random-walk driver for the analog input
+|     |
+|     +-- calibration/
+|           calibrator.js          Calibrator — stability check, offset capture, repeatability proxy
+```
+
+### Tier responsibilities
+
+| Tier | File | What it owns | Touches `RED.*` |
+|:---|:---|:---|:---:|
+| entry | `measurement.js` | Type registration; admin HTTP endpoints (`/menu.js`, `/configData.js`, `/asset-reg`) | Yes |
+| nodeClass | `src/nodeClass.js` | Wraps `BaseNodeAdapter`; declares `DomainClass = Measurement`, `commands`, `tickInterval = 1000 ms`, `statusInterval = 1000 ms`; `buildDomainConfig()` reshapes the editor's flat `uiConfig` into the domain config slice | Yes (via base class) |
+| specificClass | `src/specificClass.js` | Orchestrator. In `configure()` builds one `Channel` (analog) or N `Channels` (digital), wires up `Simulator` and `Calibrator`, installs legacy mirrors so pre-refactor tests keep passing | No |
+| concern | `src/channel.js` | Pure per-channel pipeline: outlier → offset → scaling → smoothing → min/max → emit | No |
+| concern | `src/simulation/simulator.js` | Random-walk driver used when `config.simulation.enabled` is true | No |
+| concern | `src/calibration/calibrator.js` | Stability detection (`isStable`), calibration offset capture (`calibrate`), repeatability proxy (`evaluateRepeatability`) | No |
+
+`specificClass` is stitching. All real work lives in the concern modules.
+
+---
+
+## No FSM — just modes + a pipeline
+
+Unlike `rotatingMachine` or `pumpingStation`, `measurement` has **no state machine**. The behavioural switch is a one-time decision made in `Measurement.configure()`:
+
+```mermaid
+flowchart LR
+    cfg[config.mode.current]
+    cfg -->|"=== 'digital'"| dig[_buildDigitalChannels<br/>one Channel per config.channels[i]]
+    cfg -->|"=== 'analog' (default)"| ana[_buildAnalogChannel<br/>one Channel from flat config]
+    dig --> emit_d[handleDigitalPayload<br/>fan-out per channel]
+    ana --> emit_a[inputValue setter<br/>single channel update]
+    classDef ctrl fill:#a9daee,color:#000
+```
+
+After `configure()`:
+
+- **analog mode** &rarr; `this.analogChannel` is set, `this.channels` is an empty `Map`. Setting `m.inputValue = v` runs the whole pipeline and `notifyOutputChanged()` fires Port 0.
+- **digital mode** &rarr; `this.channels` is keyed by `channel.key`; `analogChannel` is `undefined`. `handleDigitalPayload(payload)` walks every key in the incoming object, dispatches to the matching `Channel`, and collects a per-channel `{ok, mAbs, mPercent}` summary.
+
+The 1000 ms `tick()` is **only** used to drive the built-in simulator when `config.simulation.enabled` is true; the rest of the node is event-driven (input msg arrives &rarr; pipeline runs &rarr; emit).
+
+---
+
+## The per-`Channel` pipeline
+
+```mermaid
+flowchart TB
+    in[update&#40;value&#41;] --> oe{outlierDetection<br/>.enabled?}
+    oe -- no --> off[+= scaling.offset]
+    oe -- yes --> iso[_isOutlier&#40;value&#41;]
+    iso -- outlier --> drop[return false<br/>warn + drop]
+    iso -- ok --> off
+    off --> rmm[update totalMinValue<br/>/ totalMaxValue]
+    rmm --> sc{scaling.enabled?}
+    sc -- yes --> as[_applyScaling]
+    sc -- no --> sm[(unchanged)]
+    as --> sm
+    sm --> push[push to storedValues<br/>cap at smoothWindow]
+    push --> meth[switch&#40;smoothMethod&#41;]
+    meth --> sms[update totalMinSmooth<br/>/ totalMaxSmooth]
+    sms --> wo[round to 2dp<br/>compare to outputAbs<br/>(only emit on change)]
+    wo --> emit[measurements.emitter<br/>fires &lt;type&gt;.measured.&lt;position&gt;]
+```
+
+Source: `src/channel.js` `update(value)`.
+
+### Outlier methods
+
+| `method` (config) | Implementation | Threshold default |
+|:---|:---|:---:|
+| `zScore` (default) | `_zScore`: `\|val - mean\| / stdDev > threshold` | `3` |
+| `iqr` | `_iqr`: `val < q1 - 1.5*iqr` or `val > q3 + 1.5*iqr` | `3` |
+| `modifiedZScore` | `_modifiedZScore`: `0.6745 * (val - median) / mad > threshold` | `3.5` |
+
+`_isOutlier` returns `false` when fewer than 2 samples are stored (warm-up). The `zScore` branch is intentionally **not** short-circuited at `stdDev === 0`: a perfectly flat baseline marks any deviation as an outlier.
+
+### Smoothing methods
+
+Each tick the smoother pushes the post-scaling value into `storedValues`, trims the buffer to `smoothing.smoothWindow`, then collapses it to a single scalar via `smoothing.smoothMethod`:
+
+| Method | Behaviour |
+|:---|:---|
+| `none` | Pass through the latest sample |
+| `mean` (default) | Arithmetic mean of the window |
+| `min` / `max` | Smallest / largest in the window |
+| `sd` | Standard deviation |
+| `median` | Middle value, robust to outliers |
+| `weightedMovingAverage` | Linear weights `1..N` |
+| `lowPass` | EWMA, `alpha = 0.2` |
+| `highPass` | First-order high-pass, `alpha = 0.8` |
+| `bandPass` | LP + HP combination |
+| `kalman` | Simple 1-D Kalman with fixed gain |
+| `savitzkyGolay` | 5-point cubic SG filter (`[-3, 12, 17, 12, -3] / 35`) |
+
+Unknown method names log an error and pass the raw value through.
+
+### Scaling and percent mapping
+
+`_applyScaling(value)` performs a linear map `[scaling.inputMin..inputMax]` &rarr; `[scaling.absMin..absMax]`, clamping the input to the source range first. An invalid input range (`inputMax <= inputMin`) self-heals to `[0, 1]` and logs a warn.
+
+`_computePercent(value)` then maps the **clamped** result into the percent range `[interpolation.percentMin..percentMax]` (defaults 0..100). When `scaling.enabled` is false and `absMax <= absMin` the percent uses the live `totalMinValue / totalMaxValue` instead.
+
+`_writeOutput` rounds to 2 decimal places and only emits a new measurement when `rounded !== outputAbs` &mdash; so a stable input does **not** retrigger downstream.
+
+---
+
+## Lifecycle &mdash; what one event does
+
+### Analog mode
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant ext as external sender
+    participant nc as nodeClass
+    participant m as Measurement
+    participant ch as Channel pipeline
+    participant emitter as measurements.emitter
+    participant parent as registered parent
+
+    ext->>nc: msg {topic:'data.measurement', payload:42}
+    nc->>m: dispatch via commands.handlers.dataMeasurement
+    m->>m: set inputValue = 42
+    m->>ch: analogChannel.update&#40;42&#41;
+    ch->>ch: outlier → offset → scale → smooth → minMax
+    ch->>emitter: pressure.measured.atequipment {value, ts, unit}
+    emitter-->>parent: child measurement event (subscribed at register-time)
+    m->>nc: notifyOutputChanged&#40;&#41;
+    nc-->>ext: Port 0 + Port 1 (delta-compressed)
+    Note over nc: every 1000 ms: if simulation.enabled,<br/>simulator.step&#40;&#41; → m.inputValue
+```
+
+### Digital mode
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant ext as external sender
+    participant nc as nodeClass
+    participant m as Measurement
+    participant chs as Channels (per key)
+    participant emitter as measurements.emitter
+    participant parent as registered parent
+
+    ext->>nc: msg {topic:'data.measurement', payload:{level-a:1.8, temp-a:18}}
+    nc->>m: handlers.dataMeasurement (digital branch)
+    m->>m: handleDigitalPayload&#40;payload&#41;
+    loop for each key in payload
+        m->>chs: Channel.update&#40;value&#41;
+        chs->>emitter: &lt;type&gt;.measured.&lt;position&gt; per channel
+        emitter-->>parent: one event per channel that accepted a value
+    end
+    m-->>ext: Port 0 + Port 1 (nested {channels:{...}})
+```
+
+> [!NOTE]
+> Digital mode currently does **not** call `notifyOutputChanged()` from `handleDigitalPayload`. TODO: confirm whether Port 0 fan-out relies on the tick or on a follow-up notify; pending review of how `BaseNodeAdapter` schedules digital-mode output emission.
+
+---
+
+## Output ports
+
+| Port | Carries | Sample shape |
+|:---|:---|:---|
+| 0 (process) | Delta-compressed snapshot of `getOutput()` &mdash; analog scalar fields or digital `{channels:{...}}` | `{topic: <name>, payload: {mAbs, mPercent, totalMin/MaxValue, totalMin/MaxSmooth}}` (analog) |
+| 1 (telemetry) | InfluxDB line-protocol payload, same fields as Port 0 | `measurement,id=sensor_a mAbs=0.42,mPercent=42,...` |
+| 2 (registration) | One `{topic:'registerChild', payload:<node.id>, positionVsParent, distance}` at startup | `{topic:'registerChild', payload:'<id>'}` |
+
+Port-0 / Port-1 use the standard `outputUtils.formatMsg(..., 'process' | 'influxdb')` formatters. Delta compression means consumers see only the keys that changed since the previous tick.
+
+See [EVOLV &mdash; Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) for the platform InfluxDB layout.
+
+---
+
+## Event sources
+
+| Source | Where it fires | What it triggers |
+|:---|:---|:---|
+| Inbound `msg.topic` | Node-RED input wire | `commands.handlers.<topic>` dispatch via `BaseNodeAdapter` |
+| `setInterval(tickInterval = 1000)` | `BaseNodeAdapter` | `Measurement.tick()` &mdash; runs `Simulator.step()` only when `config.simulation.enabled` |
+| `setInterval(statusInterval = 1000)` | `BaseNodeAdapter` | `Measurement.getStatusBadge()` re-rendered |
+| `Channel._writeOutput` &rarr; `measurements.emitter` | Every accepted update where the rounded output changed | `<type>.measured.<position>` fires once per channel that produced a new value |
+| `source.emitter` `'mAbs'` (legacy) | Analog `inputValue` setter | Editor status badge during the refactor window &mdash; deprecated, slated for removal in Phase 7 |
+
+No per-tick FSM. The only background work is the 1000 ms simulator pump.
+
+---
+
+## Where to start reading
+
+| If you're changing... | Read first |
+|:---|:---|
+| The per-sample pipeline (outlier / scaling / smoothing) | `src/channel.js` `update`, `_isOutlier`, `_applyScaling`, `_applySmoothing` |
+| Analog vs digital branching | `src/specificClass.js` `configure`, `_buildAnalogChannel`, `_buildDigitalChannels`, `handleDigitalPayload` |
+| Top-level topic dispatch | `src/commands/{index, handlers}.js` |
+| Simulator step / bounds | `src/simulation/simulator.js` `step` |
+| Calibration stability / offset capture | `src/calibration/calibrator.js` `isStable`, `calibrate`, `evaluateRepeatability` |
+| Editor &rarr; domain config reshape | `src/nodeClass.js` `buildDomainConfig` |
+| Per-node status badge | `Measurement.getStatusBadge` |
+| Output shape | `Measurement.getOutput` (analog) / `getDigitalOutput` (digital) |
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Contracts](Reference-Contracts) | Topic + config + child registration |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped flows + debug recipes |
+| [Reference &mdash; Limitations](Reference-Limitations) | Known issues and open questions |
+| [rotatingMachine wiki](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) | The most common consumer of measurement |
+| [EVOLV &mdash; Architecture](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Architecture) | Platform-wide three-tier pattern |

wiki/Reference-Contracts.md

@@ -0,0 +1,279 @@
+# Reference — Contracts
+
+![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue)
+
+> [!NOTE]
+> Full topic contract, configuration schema, and child-registration handshake for `measurement`. Source of truth: `src/commands/index.js`, `src/commands/handlers.js`, `src/specificClass.js` `configure()`, and the schema at `generalFunctions/src/configs/measurement.json`.
+>
+> Pending full node review (2026-05). Hand-written best-effort placeholder where indicated. For an intuitive overview, return to [Home](Home).
+
+---
+
+## Topic contract
+
+The registry lives in `src/commands/index.js`. Each descriptor maps a canonical `msg.topic` to a handler; aliases emit a one-time deprecation warning the first time they fire.
+
+<!-- BEGIN AUTOGEN: topic-contract — populate via wiki-gen tool (TODO) -->
+
+| Canonical topic | Aliases | Payload | Unit | Effect |
+|:---|:---|:---|:---|:---|
+| `set.simulator` | `simulator` | (ignored) | &mdash; | Toggles `source.toggleSimulation()` &mdash; flips `config.simulation.enabled`. |
+| `set.outlier-detection` | `outlierDetection` | (ignored) | &mdash; | Toggles `source.toggleOutlierDetection()` &mdash; flips `config.outlierDetection.enabled` and propagates the new value to `analogChannel.outlierDetection.enabled`. |
+| `cmd.calibrate` | `calibrate` | (ignored) | &mdash; | Calls `source.calibrate()` &mdash; if the rolling window is stable, captures the current output as the new `config.scaling.offset`. Aborts with a warn when unstable or when the calibration baseline is missing. |
+| `data.measurement` | `measurement` | mode-dependent (see below) | per channel (configured) | Push a raw sensor reading into the pipeline. Mode-dispatched in `handlers.dataMeasurement`: **analog** expects a number / numeric string &rarr; `source.inputValue = parsed`; **digital** expects an object keyed by channel name &rarr; `source.handleDigitalPayload(payload)`. Wrong shape for the configured mode logs a hint suggesting the other mode. |
+
+<!-- END AUTOGEN: topic-contract -->
+
+### Payload-shape rules
+
+| Mode | Accepted | Rejected (logs warn) |
+|:---|:---|:---|
+| `analog` | `number`; numeric string (trimmed, non-empty, parses with `Number`) | object payload (hint: "Switch Input Mode to 'digital' &hellip;"); non-numeric string |
+| `digital` | object `{ key1: number, key2: number, &hellip; }` &mdash; keys must match `config.channels[*].key` | number (hint: "Switch Input Mode to 'analog' &hellip;"); array; any non-object |
+
+Unknown channel keys in a digital payload are collected and reported at `debug` level via `digital payload contained unmapped keys: <list>`.
+
+### Source / mode allow-lists
+
+> [!NOTE]
+> TODO: `measurement` does not appear to implement a `flowController`-style action/source allow-list (consult `src/specificClass.js`); it relies on the topic registry's typeof checks. If a future hardening pass adds mode-source gating, fold the table in here.
+
+---
+
+## Data model &mdash; `getOutput()` shape
+
+Source: `src/specificClass.js` `getOutput()` / `getDigitalOutput()` and `src/channel.js` `getOutput()`. Delta-compressed by `outputUtils.formatMsg`: consumers see only the keys that changed.
+
+<!-- BEGIN AUTOGEN: data-model — populate via wiki-gen tool (TODO) -->
+
+### Analog mode (`Measurement.getOutput()`)
+
+| Key | Type | Unit | Notes |
+|:---|:---|:---|:---|
+| `mAbs` | number | scaling units (`asset.unit` / `general.unit`) | Latest output value after offset + scaling + smoothing. Rounded to 2 dp. |
+| `mPercent` | number | % | Output mapped to `interpolation.percentMin..percentMax`. Rounded to 2 dp. |
+| `totalMinValue` | number | scaling units | Rolling minimum of the **post-offset, pre-smoothing** values. Reported as `0` until the first sample. |
+| `totalMaxValue` | number | scaling units | Rolling maximum of the same. Reported as `0` until the first sample. |
+| `totalMinSmooth` | number | scaling units | Rolling minimum of the smoothed output. Starts at `0`. |
+| `totalMaxSmooth` | number | scaling units | Rolling maximum of the smoothed output. Starts at `0`. |
+
+### Digital mode (`Measurement.getDigitalOutput()`)
+
+```jsonc
+{
+  "channels": {
+    "<channel.key>": {
+      "key":            "<channel.key>",
+      "type":           "<channel.type>",
+      "position":       "<channel.position>",
+      "unit":           "<channel.unit>",
+      "mAbs":           <number>,
+      "mPercent":       <number>,
+      "totalMinValue":  <number>,
+      "totalMaxValue":  <number>,
+      "totalMinSmooth": <number>,
+      "totalMaxSmooth": <number>
+    }
+    // ... one entry per channel that has produced output
+  }
+}
+```
+
+<!-- END AUTOGEN: data-model -->
+
+### Status badge
+
+`Measurement.getStatusBadge()`:
+
+| Mode | Badge text | Fill / shape |
+|:---|:---|:---|
+| `analog` | `<mAbs> <unit>` (e.g. `0.42 bar`) | green / dot |
+| `digital` | `digital · <N> channel(s)` | blue / ring |
+
+The legacy `source.emitter` fires `'mAbs'` (analog only) and is kept for the editor status badge during the refactor window &mdash; see [Limitations](Reference-Limitations#legacy-source-emitter).
+
+---
+
+## Events emitted on `source.measurements.emitter`
+
+The shared `MeasurementContainer` fires `<type>.measured.<position>` whenever a `Channel`'s rounded output changes. The type / position come from:
+
+- **analog**: `config.asset.type` and `config.functionality.positionVsParent`.
+- **digital**: per-channel `config.channels[i].type` and `config.channels[i].position` (falls back to the node-level `positionVsParent` when missing).
+
+Position labels are normalised to **lowercase** in the event name (`upstream`, `downstream`, `atequipment`). Examples:
+
+- `pressure.measured.upstream`
+- `flow.measured.atequipment`
+- `level.measured.downstream`
+- `temperature.measured.atequipment`
+
+Parents subscribe through the generic `child.measurements.emitter.on(eventName, &hellip;)` handshake established by `childRegistrationUtils` (in `generalFunctions`).
+
+In digital mode one input message can fan out into several events &mdash; one per channel that accepted a value on that tick.
+
+---
+
+## Configuration schema &mdash; editor form to config keys
+
+Source of truth: `generalFunctions/src/configs/measurement.json` plus `nodeClass.buildDomainConfig`. Defaults below come from the schema.
+
+### General (`config.general`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Name | `general.name` | `Sensor` | Human-readable label. |
+| (auto-assigned) | `general.id` | `null` | Node-RED node id. |
+| Default unit | `general.unit` | `unitless` | Falls back to the asset unit. |
+| Enable logging | `general.logging.enabled` | `true` | Master switch. |
+| Log level | `general.logging.logLevel` | `info` | `debug` / `info` / `warn` / `error`. |
+
+### Functionality (`config.functionality`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Software type | `functionality.softwareType` | `measurement` | Constant. |
+| Role | `functionality.role` | `Sensor` | Constant. |
+| Position vs parent | `functionality.positionVsParent` | `atEquipment` | One of `atEquipment` / `upstream` / `downstream`. Used in the `child.register` payload and as the suffix of the measurement event name. |
+| Distance offset | `functionality.distance` | `null` | Optional spatial offset; sent with `child.register`. |
+
+### Asset (`config.asset`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Asset UUID | `asset.uuid` | `null` | Globally-unique identifier. |
+| Tag code / number | `asset.tagCode` / `asset.tagNumber` | `null` | Asset-registry identifiers. |
+| Geolocation | `asset.geoLocation` | `{x:0, y:0, z:0}` | |
+| Supplier | `asset.supplier` | `Unknown` | Free text. |
+| Category | `asset.category` | `sensor` | `sensor` / `measurement`. |
+| Asset type | `asset.type` | `pressure` | **Required.** Matches the type axis on `MeasurementContainer` and the parent's filter (e.g. `flow`, `power`, `temperature`). |
+| Model | `asset.model` | `Unknown` | Free text. |
+| Asset unit | `asset.unit` | `unitless` | Output unit label for the measurement event payload. |
+| Accuracy | `asset.accuracy` | `null` | Optional sensor accuracy. |
+| Repeatability | `asset.repeatability` | `null` | Optional repeatability metric. |
+
+> [!IMPORTANT]
+> `asset.type` must match the **exact** string the parent listens for. The parent's filter is typically the bare type (`flow`, `pressure`, `power`, &hellip;) &mdash; a measurement configured as `flow-electromagnetic` will not register with a `flow`-only filter on its parent (see [Limitations](Reference-Limitations#asset-type-must-match-the-parents-filter-exactly)).
+
+### Scaling (`config.scaling`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Scaling enabled | `scaling.enabled` | `false` | When false, the input is passed through with only the offset applied. |
+| Input min/max | `scaling.inputMin` / `scaling.inputMax` | `0` / `1` | Source range; clamps the input before mapping. |
+| Output min/max | `scaling.absMin` / `scaling.absMax` | `50` / `100` | Target range. |
+| Offset | `scaling.offset` | `0` | Added before scaling; mutated by `cmd.calibrate`. |
+
+### Smoothing (`config.smoothing`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Window size | `smoothing.smoothWindow` | `10` | `>= 1`. Rolling buffer length. |
+| Method | `smoothing.smoothMethod` | `mean` | One of `none` / `mean` / `min` / `max` / `sd` / `median` / `weightedMovingAverage` / `lowPass` / `highPass` / `bandPass` / `kalman` / `savitzkyGolay`. |
+
+### Outlier detection (`config.outlierDetection`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Enabled | `outlierDetection.enabled` | `false` | Toggle with `set.outlier-detection`. |
+| Method | `outlierDetection.method` | `zScore` | One of `zScore` / `iqr` / `modifiedZScore`. |
+| Threshold | `outlierDetection.threshold` | `3` | Method-specific (e.g. z &gt; 3, mz &gt; 3.5). |
+
+### Simulation (`config.simulation`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Enabled | `simulation.enabled` | `false` | When true, `tick()` (1000 ms) drives `inputValue` via `Simulator.step()`. |
+| Safe calibration time | `simulation.safeCalibrationTime` | `100` | ms before calibration is finalised in sim mode. |
+
+### Interpolation (`config.interpolation`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Percent min | `interpolation.percentMin` | `0` | Lower bound of the `mPercent` output. |
+| Percent max | `interpolation.percentMax` | `100` | Upper bound. |
+
+### Calibration (`config.calibration`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Stability threshold | `calibration.stabilityThreshold` | `0.01` | Absolute stdDev ceiling (in scaling-units) below which the buffer is considered stable. Fits the default `[50,100]` range; tighten / relax for your sensor. |
+
+### Mode (`config.mode`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Input mode | `mode.current` | `analog` | `analog` (one channel, scalar payload) or `digital` (N channels, object payload). |
+
+### Channels (`config.channels[]` &mdash; digital only)
+
+In digital mode, each entry in `config.channels` defines its own pipeline:
+
+| Field | Required | Falls back to |
+|:---|:---:|:---|
+| `key` | yes | &mdash; (skipped if missing) |
+| `type` | yes | &mdash; (skipped if missing) |
+| `position` | no | `config.functionality.positionVsParent` &rarr; `atEquipment` |
+| `unit` | no | `config.asset.unit` &rarr; `unitless` |
+| `distance` | no | `config.functionality.distance` &rarr; `null` |
+| `scaling` | no | `{enabled:false, inputMin:0, inputMax:1, absMin:0, absMax:1, offset:0}` |
+| `smoothing` | no | `config.smoothing` |
+| `outlierDetection` | no | `config.outlierDetection` |
+| `interpolation` | no | `config.interpolation` |
+
+Invalid entries (missing `key` or `type`) are logged and skipped. An empty `config.channels[]` in digital mode logs `digital mode enabled but config.channels is empty; no channels will be emitted.`
+
+### Asset registration (`config.assetRegistration`)
+
+Used by the `/measurement/asset-reg` admin endpoint to register / sync the asset with the upstream asset registry. Not part of the runtime data path.
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Profile / location / process ids | `assetRegistration.{profileId, locationId, processId}` | `1` | Free integer ids in the asset registry. |
+| Status | `assetRegistration.status` | `actief` | Lifecycle status. |
+| Child assets | `assetRegistration.childAssets` | `[]` | List of child asset ids. |
+
+### Output (`config.output`)
+
+| Form field | Config key | Default | Notes |
+|:---|:---|:---|:---|
+| Process output | `output.process` | `process` | `process` / `json` / `csv`. Port-0 formatter. |
+| Database output | `output.dbase` | `influxdb` | `influxdb` / `json` / `csv`. Port-1 formatter. |
+
+### Unit policy
+
+> [!NOTE]
+> TODO: `measurement` does not currently declare a `unitPolicy` block on its `BaseDomain` configuration (unlike `rotatingMachine`). The per-channel `unit` is carried verbatim into the `MeasurementContainer` write at `_writeOutput`. If a future hardening pass adds a unit-policy enforcement, add the canonical / output / required-unit table here. See `CONTRACT.md` for the current invariants.
+
+---
+
+## Child registration
+
+Source: `src/specificClass.js` `configure` (registers itself via the `BaseDomain` plumbing) and the standard `childRegistrationUtils` handshake in `generalFunctions`.
+
+`measurement` does **not accept children**. It only **registers itself** as a child on its upstream parent.
+
+| Layer | Direction | Topic / event | Payload |
+|:---|:---|:---|:---|
+| Startup (Port 2) | child &rarr; parent | `registerChild` | `{topic: 'registerChild', payload: <node.id>, positionVsParent, distance}` |
+| Runtime | child &rarr; parent | `<asset.type>.measured.<positionVsParent>` on `child.measurements.emitter` | `{value, timestamp, unit, distance?}` (per `MeasurementContainer.value()`) |
+
+| What | softwareType payload | Side-effect on parent |
+|:---|:---|:---|
+| Registration | `measurement` | Parent attaches a listener for `<asset.type>.measured.<positionVsParent>` on the child's `measurements.emitter`. |
+| Subsequent updates | event on `child.measurements.emitter` | Parent mirrors the value into its own `MeasurementContainer` slot. |
+
+Position labels are normalised to **lowercase** in the event name (`upstream`, `downstream`, `atequipment`); the `positionVsParent` field in the register payload is sent as configured (preserves case).
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map + per-`Channel` pipeline + lifecycle |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped flows + debug recipes |
+| [Reference &mdash; Limitations](Reference-Limitations) | Known issues and open questions |
+| [EVOLV &mdash; Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions) | Platform-wide topic rules |
+| [EVOLV &mdash; Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry) | Port 0 / 1 / 2 InfluxDB layout |

wiki/Reference-Examples.md

@@ -0,0 +1,148 @@
+# Reference — Examples
+
+![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue)
+
+> [!NOTE]
+> Every example flow shipped under `nodes/measurement/examples/`, plus how to load them, what they show, and the debug recipes that go with them. Live source: `nodes/measurement/examples/`.
+>
+> Pending full node review (2026-05). Tier-1/2/3 visual-first example flows are still TODO (tracked in the superproject `MEMORY.md` "TODO: Example Flows"). The current shipped flows pre-date the refactor; treat them as smoke tests, not as production templates.
+
+---
+
+## Shipped examples
+
+| File | Tier | Dependencies | What it shows | Status |
+|:---|:---:|:---|:---|:---|
+| `basic.flow.json` | 1 | EVOLV only | Single measurement node driven by inject buttons — analog scalar input, scaling enabled, three debug taps on Port 0/1/2. | Legacy pre-refactor shape, still imports. |
+| `integration.flow.json` | 2 | EVOLV only | Parent-child wiring &mdash; measurement registers as a child of another node and emits its `<type>.measured.<position>` events. | Legacy pre-refactor shape. |
+| `edge.flow.json` | 3 | EVOLV only | Invalid / edge payload driving for robustness checks (non-numeric strings, object in analog mode, &hellip;). | Legacy pre-refactor shape. |
+
+The three legacy files predate the AssetResolver refactor and the analog-vs-digital mode flag. They still deploy (the editor will accept the older shape and `nodeClass.buildDomainConfig` reshapes whatever it finds), but the recommended Tier-1/2/3 visual-first replacements are still to be written.
+
+> [!IMPORTANT]
+> **TODO &mdash; Tier-1/2/3 visual-first flows.** Replace the three legacy files with:
+> - `01 - Basic Analog.json` &mdash; one measurement, inject + scaling + smoothing + outlier-detection toggle + simulator.
+> - `02 - Integration with rotatingMachine.json` &mdash; measurement registered as a pressure sensor on a `rotatingMachine`, Port 2 auto-register on deploy, parent's prediction updates as the measurement value moves.
+> - `03 - Digital Multi-Channel.json` &mdash; one measurement in `digital` mode with 2&ndash;3 channels (e.g. `level-a`, `temp-a`, `flow-a`) fed by a single object-payload inject.
+
+---
+
+## Loading a flow
+
+### Via the editor
+
+1. Open the Node-RED editor at `http://localhost:1880`.
+2. Menu &rarr; Import &rarr; drag the JSON file.
+3. Click Deploy.
+
+### Via the Admin API
+
+```bash
+curl -X POST -H 'Content-Type: application/json' \
+  --data @nodes/measurement/examples/basic.flow.json \
+  http://localhost:1880/flows
+```
+
+---
+
+## Example &mdash; `basic.flow.json`
+
+Single-measurement flow with the minimum kit to exercise scaling.
+
+### Nodes on the tab
+
+| Type | Purpose |
+|:---|:---|
+| `inject` | One-shot `topic: 'measurement', payload: 42` (legacy alias of `data.measurement`) |
+| `measurement` | The unit under test &mdash; analog mode, scaling enabled (0..100 &rarr; 0..10), `mean` smoothing, window 5 |
+| `debug` &times; 3 | Port 0 (process), Port 1 (InfluxDB), Port 2 (registration) |
+
+### What to do after deploy
+
+1. Click the inject. Port 0 fires with `mAbs ≈ 4.2` (42 scaled into 0..10), `mPercent ≈ 42`.
+2. Send another value via the same inject (edit the inject payload to `60`). `totalMinValue` / `totalMaxValue` start tracking, `mAbs` jumps to ~6.0.
+3. Send `topic: 'set.simulator'` (use a second inject). `tick()` starts driving `inputValue` through `Simulator.step()` every 1000 ms; Port 0 updates appear automatically.
+4. Send `topic: 'cmd.calibrate'`. If `stdDev <= 0.01` (the default `stabilityThreshold`), `config.scaling.offset` jumps to `inputMin - currentOutput`; if not, a warn appears in the log.
+5. Send `topic: 'set.outlier-detection'`, then inject a wildly out-of-band value (e.g. `9999`). With outlier detection on the value is dropped with `Outlier detected. Ignoring value=9999`.
+
+> [!IMPORTANT]
+> **Screenshot needed.** Editor capture of `basic.flow.json` plus the Port 0 debug output. Save as `wiki/_partial-screenshots/measurement/basic-flow.png`. Replace this callout with the image link.
+
+---
+
+## Example &mdash; `integration.flow.json`
+
+Demonstrates the parent-child handshake: the measurement node's Port 2 auto-fires `child.register` to its parent on deploy, and the parent then receives the `<type>.measured.<position>` event whenever a new reading lands.
+
+> [!IMPORTANT]
+> **Screenshot needed.** Editor capture of `integration.flow.json` showing the wiring. Save as `wiki/_partial-screenshots/measurement/integration-flow.png`.
+
+> [!NOTE]
+> TODO: confirm the integration flow targets a real EVOLV parent (e.g. `rotatingMachine`) versus a mock function node; if it's a mock, the Tier-2 replacement should use a real parent.
+
+---
+
+## Example &mdash; `edge.flow.json`
+
+Drives the node with malformed inputs to verify the warn paths land cleanly:
+
+- Non-numeric string in analog mode &rarr; `Invalid numeric measurement payload: <value>`.
+- Object payload in analog mode &rarr; `analog mode received an object payload (keys: &hellip;). Switch Input Mode to 'digital' &hellip;`.
+- Numeric scalar in digital mode &rarr; `digital mode received a number (&hellip;); expected an object &hellip;`.
+- Outlier toggle on/off mid-stream &rarr; verifies `analogChannel.outlierDetection.enabled` mirrors `config.outlierDetection.enabled`.
+
+> [!IMPORTANT]
+> **Screenshot needed.** Editor capture of `edge.flow.json` plus the log lines each inject triggers. Save as `wiki/_partial-screenshots/measurement/edge-flow.png`.
+
+---
+
+## Debug recipes
+
+| Symptom | First thing to check | Where to look |
+|:---|:---|:---|
+| Parent never receives `<type>.measured.<position>` | `asset.type` must match the parent's filter exactly (e.g. `flow` &mdash; not `flow-electromagnetic`). Position labels lowercase in the event name. | `config.asset.type` + parent's `childRegistrationUtils` filter. |
+| Outliers seem to pass through | `outlierDetection.enabled` may be off (default `false`). Toggle with `set.outlier-detection`. With `<2` samples in the buffer, `_isOutlier` returns `false` regardless. | `Channel._isOutlier`. |
+| `cmd.calibrate` does nothing | Calibrator requires `stdDev <= calibration.stabilityThreshold` over `storedValues`. If `storedValues.length < 2`, `isStable()` returns `false` (legacy shape). | `src/calibration/calibrator.js` `isStable`, `calibrate`. |
+| Digital payload silently dropped | Unknown channel keys are reported only at `debug` log level (`digital payload contained unmapped keys`). Numeric values that fail `Number.isFinite` warn at `warn`. | `Measurement.handleDigitalPayload`. |
+| Simulator still running after toggle off | `tick()` reads `config.simulation.enabled` each tick. Confirm the toggle actually mutated the config (the `set.simulator` handler is idempotent &mdash; it just flips). | `Measurement.tick`, `toggleSimulation`. |
+| Port 0 emits nothing after `data.measurement` | Analog: `_writeOutput` only emits when `rounded !== outputAbs`. A repeated identical value is silent by design. | `Channel._writeOutput`. |
+| `mPercent` is stuck at `0` or unbounded | `processRange <= 0` (i.e. `absMax <= absMin`); percent falls back to `totalMinValue / totalMaxValue` which start at `0` / `0`. Configure `absMin < absMax`. | `Channel._computePercent`. |
+| Scaling output looks clamped | `_applyScaling` clamps the input to `[inputMin, inputMax]` before mapping. Wide-band sensors need `inputMin / inputMax` set to the full physical range. | `Channel._applyScaling`. |
+| `mAbs` jumps after `cmd.calibrate` | Expected. Calibration sets `config.scaling.offset = baseline - currentOutputAbs`, which makes the next reading land on the baseline (`inputMin` when scaling enabled, `absMin` otherwise). | `Calibrator.calibrate`. |
+| Legacy `setpoint` / `simulator` topics work without warning | First fire emits a one-time deprecation warning via `BaseNodeAdapter`'s alias handling. Subsequent fires are silent &mdash; the topic still works. | `commands/index.js` `aliases`. |
+
+> Never ship `enableLog: 'debug'` in a demo &mdash; fills the container log within seconds and obscures real errors.
+
+---
+
+## Docker compose snippet
+
+To bring up Node-RED + InfluxDB with EVOLV nodes pre-loaded:
+
+```yaml
+# docker-compose.yml (extract)
+services:
+  nodered:
+    build: ./docker/nodered
+    ports: ['1880:1880']
+    volumes:
+      - ./docker/nodered/data:/data/evolv
+  influxdb:
+    image: influxdb:2.7
+    ports: ['8086:8086']
+```
+
+Full file: [EVOLV/docker-compose.yml](https://gitea.wbd-rd.nl/RnD/EVOLV/src/branch/development/docker-compose.yml).
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Contracts](Reference-Contracts) | Topic + config + child registration |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map + per-`Channel` pipeline + lifecycle |
+| [Reference &mdash; Limitations](Reference-Limitations) | Known issues and open questions |
+| [rotatingMachine &mdash; Examples](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Reference-Examples) | Most common consumer of measurement |
+| [EVOLV &mdash; Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns) | Where measurement fits in a larger plant |

wiki/Reference-Limitations.md

@@ -0,0 +1,117 @@
+# Reference — Limitations
+
+![code-ref](https://img.shields.io/badge/code--ref-b884c0f-blue)
+
+> [!NOTE]
+> What `measurement` does not do, current rough edges, and open questions. Open items live in `.agents/improvements/IMPROVEMENTS_BACKLOG.md` in the EVOLV superproject; node-local follow-ups are tracked in the superproject's `MEMORY.md` and `.claude/refactor/OPEN_QUESTIONS.md`.
+>
+> Pending full node review (2026-05).
+
+---
+
+## When you would not use this node
+
+| Scenario | Use instead |
+|:---|:---|
+| Fusing signals from multiple sensors into one virtual measurement | This node is per-channel only. Aggregate at the parent (e.g. `rotatingMachine` already combines upstream + downstream into a differential). |
+| Producing a control output / actuating something | This is read-only signal conditioning. Use `rotatingMachine`, `valve`, or another equipment-level node. |
+| Threshold-trip alarms / latched state | There is no comparator / latch output. Build alarm logic on top of the emitted reading at the parent or in a dashboard rule. |
+| A "passive" measurement that should not register with a parent | Registration is automatic at startup — not currently opt-out. TODO: confirm whether a "no-parent" mode exists; if not, leave the parent input unwired. |
+
+---
+
+## Known limitations
+
+### Asset type must match the parent's filter exactly
+
+Parents subscribe to events by exact string match on `<asset.type>.measured.<position>`. A measurement configured as `flow-electromagnetic` will not be picked up by a parent that filters on `flow`. The fix is mechanical &mdash; set `asset.type` to the bare type the parent expects.
+
+This is documented in the superproject `MEMORY.md` under "Key Integration Gotchas":
+
+> Measurement `assetType: "flow"` required (not "flow-electromagnetic") for pumpingStation/monster.
+
+### Position labels lowercase only in the event name
+
+The event name emits `<type>.measured.<position>` with `position` lowercased (`upstream`, `downstream`, `atequipment`). The `positionVsParent` field in the `child.register` payload, however, is sent **as configured** (preserves case). If a parent indexes children by the register-payload position string, mixed-case there will not match the lowercase position in subsequent events. Document the convention in any new parent that joins measurement.
+
+### Legacy `source.emitter`
+
+`source.emitter` fires `'mAbs'` on the analog `inputValue` setter alongside the canonical `measurements.emitter` path. It is kept for the editor status badge during the refactor window and is **slated for removal in Phase 7**. New consumers must use `measurements.emitter`.
+
+### Digital mode &mdash; `notifyOutputChanged()` not explicitly called
+
+`Measurement.handleDigitalPayload` collects a per-key summary but does not directly call `notifyOutputChanged()`. The analog `inputValue` setter does. TODO: confirm whether digital-mode Port 0 emissions rely on the next `tick()` or a follow-up notify path inside `BaseNodeAdapter`. Until verified, treat digital-mode Port 0 latency as "up to one tick" (1000 ms).
+
+### Digital mode &mdash; per-channel scaling / smoothing fall back to the analog block
+
+When a `config.channels[i]` entry omits a per-channel `scaling`, `smoothing`, `outlierDetection`, or `interpolation`, the missing fields fall back to the node-level config &mdash; **not** to a sensible per-type default. Setting `smoothing.smoothMethod = 'kalman'` at the node level applies that to every digital channel that does not override it. Operators should set every block per channel in production digital flows.
+
+### `data.measurement` accepts numeric strings &mdash; not arrays / NaN
+
+The analog handler parses with `Number(p)` and rejects `NaN`. Empty / whitespace strings are skipped silently. Arrays are not accepted in either mode and log a warn in digital mode.
+
+### Simulator does not respect outlier detection
+
+`Simulator.step()` writes directly into `m.inputValue`. The downstream `Channel.update` does run outlier detection if enabled &mdash; but the simulator's random walk is well-behaved enough that this is effectively a no-op. Don't expect the outlier path to be exercised by the simulator alone.
+
+### `cmd.calibrate` requires &ge; 2 stored values
+
+`Calibrator.isStable()` returns `{isStable:false}` when `storedValues.length < 2`. The legacy `Measurement.isStable()` wrapper returns a bare `false` in that case. A fresh calibration call before any data has arrived is silently rejected.
+
+### Calibration baseline depends on `scaling.enabled`
+
+When `scaling.enabled` is true, the calibration baseline is `scaling.inputMin`. When disabled, it is `scaling.absMin`. Toggling `scaling.enabled` after calibrating shifts the meaning of the captured offset; recalibrate after any scaling-toggle.
+
+### Smoothing buffer not cleared on config change
+
+Changing `smoothing.smoothMethod` or `smoothing.smoothWindow` at runtime does not clear `storedValues`. A previously-mean-smoothed buffer can produce a stale first sample after switching to `lowPass` until the window churns. The conservative workaround is to redeploy.
+
+### `outlierDetection.enabled` mirrored only into `analogChannel`
+
+`toggleOutlierDetection()` propagates the new boolean to `this.analogChannel.outlierDetection.enabled` only. In digital mode the per-channel `Channel.outlierDetection.enabled` is **not** updated by the toggle. TODO: digital-mode parity for `set.outlier-detection`.
+
+### Min/max counters never reset
+
+`totalMinValue` / `totalMaxValue` / `totalMinSmooth` / `totalMaxSmooth` are monotonic over the node's lifetime. There is no explicit reset command. The smooth-min/max additionally have a "first-write" rule that snaps both to the first value &mdash; before that, both read `0`, which can mislead downstream chart axes.
+
+---
+
+## Open questions (tracked)
+
+| Question | Where it lives |
+|:---|:---|
+| Should digital-mode `notifyOutputChanged()` fire on every accepted update? | Internal &mdash; pending P9 review |
+| Drop the legacy `source.emitter 'mAbs'` event | Phase 7 removal |
+| Replace legacy `examples/{basic,integration,edge}.flow.json` with Tier-1/2/3 visual-first flows | Superproject `MEMORY.md` "TODO: Example Flows" |
+| Add `data.clear-min-max` / `data.reset` topic for the rolling counters | Internal |
+| Add per-channel `set.outlier-detection` for digital mode | Internal |
+| Auto-recalibration heuristics (currently operator-triggered only) | Internal |
+| Per-channel `smoothing` window-clear on config change | Internal |
+
+---
+
+## Migration notes
+
+### From pre-refactor flat config
+
+Older flows used `assetType` / `supplier` / `category` at the top level of the editor config. `nodeClass.buildDomainConfig` reshapes the editor's flat `uiConfig` into the nested domain config slice (`scaling`, `smoothing`, `simulation`, `calibration`, `mode`, `channels`), so legacy flows continue to deploy. The migration is best-effort &mdash; re-saving each measurement node in the editor regenerates the canonical shape.
+
+### From analog-only
+
+Adding `config.mode.current` was additive. Flows that omit it default to `analog` and behave exactly as before. To switch to digital: set the editor's "Input Mode" to `digital` and define `config.channels`.
+
+### From legacy alias topics
+
+`simulator`, `outlierDetection`, `calibrate`, `measurement` continue to work; each emits a one-time deprecation warning on first fire. Prefer the canonical `set.simulator` / `set.outlier-detection` / `cmd.calibrate` / `data.measurement` for new flows.
+
+---
+
+## Related pages
+
+| Page | Why |
+|:---|:---|
+| [Home](Home) | Intuitive overview |
+| [Reference &mdash; Contracts](Reference-Contracts) | Topic + config + child registration (alias map at the end) |
+| [Reference &mdash; Architecture](Reference-Architecture) | Code map + per-`Channel` pipeline + lifecycle |
+| [Reference &mdash; Examples](Reference-Examples) | Shipped flows + debug recipes |
+| [rotatingMachine &mdash; Limitations](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Reference-Limitations) | Where the most common consumer's caveats overlap |

wiki/_Sidebar.md

@@ -0,0 +1,20 @@
+### measurement
+
+- [Home](Home)
+
+**Reference**
+
+- [Contracts](Reference-Contracts)
+- [Architecture](Reference-Architecture)
+- [Examples](Reference-Examples)
+- [Limitations](Reference-Limitations)
+
+**Related**
+
+- [EVOLV master wiki](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Home)
+- [rotatingMachine wiki](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home)
+- [machineGroupControl wiki](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home)
+- [pumpingStation wiki](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home)
+- [Topology Patterns](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topology-Patterns)
+- [Topic Conventions](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Topic-Conventions)
+- [Telemetry](https://gitea.wbd-rd.nl/RnD/EVOLV/wiki/Telemetry)